# Create a new artifact Source: https://www.magicpatterns.com/docs/api/create-artifact openapi-v3.yml post /v3/designs/{editorId}/artifacts Creates a new artifact by cloning an existing one (typically the currently active artifact). The new artifact becomes the active artifact for the design and a new version entry is added to the timeline. Use this to create a safe working branch before writing files — users can revert to the previous artifact if needed. # Create a design Source: https://www.magicpatterns.com/docs/api/create-design openapi-v3.yml post /v3/designs Creates a new Magic Patterns design. Behavior depends on the request: - **With `prompt`**: kicks off AI generation in the background. The response returns immediately with `editorId`; poll `GET /v3/designs/{editorId}/status` until `isGenerating` is `false`. Generation typically takes 2–10 minutes. - **Without `prompt`**: creates a blank design with scaffold files (App.tsx, index.tsx, index.css, tailwind.config.js) and returns immediately. - **With `templateId`**: forks an existing design first, then optionally applies the prompt to the fork. Generation calls bill credits from the authenticated user's normal credit balance. # Get the active artifact Source: https://www.magicpatterns.com/docs/api/get-active-artifact openapi-v3.yml get /v3/designs/{editorId}/active-artifact Returns the design's currently active artifact — the one shown in the editor and preview. Includes the artifact ID and the list of file names in it. Because the active artifact can change (the user may select a different version in the UI, or AI generation may produce a new artifact), always call this (or `GET /v3/designs/{editorId}/status`) to get the latest active artifact before working with files. # Read recent message history Source: https://www.magicpatterns.com/docs/api/get-design-messages openapi-v3.yml get /v3/designs/{editorId}/messages Returns the last 10 chat items for a design (user prompts, AI responses, artifact versions, manual edits). Use `?skip=N` to paginate backwards through older items. Page size is fixed at 10. Because the editor is collaborative, the user (or other agents) may have sent prompts or made changes between your tool calls. Use this to stay in sync with the current state. Code contents are omitted from chat items to keep the response small. Use `POST /v3/designs/{editorId}/artifacts/{artifactId}/files/read` to read full file contents. # Get design status Source: https://www.magicpatterns.com/docs/api/get-design-status openapi-v3.yml get /v3/designs/{editorId}/status Returns the current state of a design: whether AI generation is in flight, the active artifact ID, and which files exist in that artifact. Use this to poll after `POST /v3/designs` (with a prompt) or `POST /v3/designs/{editorId}/prompts`. Poll no more than once every 60 seconds. # List version history Source: https://www.magicpatterns.com/docs/api/get-design-versions openapi-v3.yml get /v3/designs/{editorId}/versions Returns the most recent 20 artifact versions for a design, with their artifact IDs, labels, and titles. Use `?skip=N` to paginate backwards. Page size is fixed at 20. Each version corresponds to a snapshot of the design's code at a point in time. Use the returned `artifactId` with the artifact read/write endpoints, or fork from it with `POST /v3/designs/{editorId}/artifacts`. # Getting Started Source: https://www.magicpatterns.com/docs/api/getting-started Programmatic access to Magic Patterns with the v3 API The Magic Patterns API lets you create and iterate on designs programmatically — kicking off generations, polling status, reading and writing artifact files, and publishing changes — all from your own systems. v3 is the current API surface. It mirrors the [Magic Patterns MCP server](/docs/documentation/features/mcp-server/overview) endpoint-for-endpoint, so the same key works for both REST and MCP. You don't need to choose. > [!NOTE] > > Already integrated against the legacy `/v2/pattern` endpoint? See the [v2 reference](/docs/documentation/api/getting-started). v2 is being deprecated and will be removed in a future release — plan to migrate to v3 when convenient. ## Authentication All v3 endpoints require an API key in the `x-mp-api-key` header. **1. Log in** Sign in (or create an account) at [magicpatterns.com](https://www.magicpatterns.com/). **2. Create an API key** Open [Settings → API Keys](https://www.magicpatterns.com/settings/api-keys) and click **Create Key**. Copy the key immediately — you can only see it once. **3. Send your first request** Use the key in the `x-mp-api-key` header on every request. ```bash theme={null} curl https://api.magicpatterns.com/api/v3/health \ -H "x-mp-api-key: mp_live_..." ``` A `200 OK` with `{"status":"ok"}` confirms your key is valid. ## Billing v3 usage draws from your normal Magic Patterns **credit balance** — the same credits the web app and MCP use. There is no separate API subscription. * Free-tier accounts get free monthly credits and can call v3 up to that limit. * Need more? Upgrade your plan or buy credit packs at [Settings → Billing & Subscription](https://www.magicpatterns.com/settings/subscription). * When you run out, v3 calls that consume credits return `402 Payment Required`. Read endpoints continue to work. ## Quickstart: create a design This kicks off generation in the background, then polls until the design is ready. ```bash theme={null} # 1. Create the design — returns immediately with an editorId. curl https://api.magicpatterns.com/api/v3/designs \ -H "x-mp-api-key: mp_live_..." \ -H "Content-Type: application/json" \ -d '{"prompt": "A landing page for a coffee shop"}' # Response: # { "editorId": "abc123", "editorUrl": "https://www.magicpatterns.com/c/abc123", ... } # 2. Poll status until generation finishes. Wait at least 60 seconds between polls. curl https://api.magicpatterns.com/api/v3/designs/abc123/status \ -H "x-mp-api-key: mp_live_..." # Response: # { "isGenerating": false, "activeArtifactId": "...", "availableFiles": [...] } ``` Generation typically takes 2–10 minutes. **Don't poll more than once every 60 seconds.** ## Asynchronous endpoints Two endpoints kick off long-running work and return immediately: * `POST /v3/designs` (when `prompt` is set) * `POST /v3/designs/{editorId}/prompts` Both return a `requestId` (or `editorId`) right away. To know when the work is done, poll `GET /v3/designs/{editorId}/status` until `isGenerating` is `false`. There are no webhooks in v3 — polling is the only mechanism. We may add webhooks in a future release if customers ask. ## Same key for MCP The same API key authenticates the [Magic Patterns MCP server](/docs/documentation/features/mcp-server/overview) — no separate OAuth login required. Configure the MCP server with an `Authorization: Bearer ` header (the MCP server also accepts `x-mp-api-key`), and the key works across both transports. See [API Key Authentication](/docs/documentation/features/mcp-server/overview#api-key-authentication) for client config examples. ## Common errors | Status | Meaning | | - | - | | `400` | Invalid input — check the request body and parameters. | | `401` | Missing or invalid `x-mp-api-key`. | | `402` | Out of credits. Top up at [Settings → Billing](https://www.magicpatterns.com/settings/subscription). | | `403` | The key's owner doesn't have access to the requested design or artifact. | | `404` | The design or artifact doesn't exist. | | `422` | Compilation failed on a `publish` call. | | `500` | Unexpected server error — logged on our side. | All error responses are `application/json` with a single `error` field: ```json theme={null} { "error": "Insufficient credits. Please upgrade your plan or add credits." } ``` ## Rate limits 1000 generations per 10 hours per key. Contact us if you need a higher limit. ## Next steps > **[Browse endpoints](/docs/api/health)** > > Full API reference with request/response examples and a try-it widget. > **[MCP server](/docs/documentation/features/mcp-server/overview)** > > Use the same key with our Model Context Protocol server. # Health check Source: https://www.magicpatterns.com/docs/api/health openapi-v3.yml get /v3/health Returns `200 OK` only when the supplied API key is valid and active. Returns `401 Unauthorized` for invalid or missing keys. Use this to verify your key and connectivity before making real requests. # List design systems Source: https://www.magicpatterns.com/docs/api/list-design-systems openapi-v3.yml get /v3/design-systems Returns every design system accessible to the authenticated user — both built-in (reserved) systems (e.g. Base, Shadcn, MUI) and any custom systems the user owns or has been invited to. Use the returned `id` as the `designSystemId` parameter when creating new designs. # Publish an artifact Source: https://www.magicpatterns.com/docs/api/publish-artifact openapi-v3.yml post /v3/designs/{editorId}/artifacts/{artifactId}/publish Compiles the artifact's source files and sets it as the active artifact for the design. This is the final step in a code-first workflow: after writing files, call this to make the changes visible in the editor and live preview. Returns `422 Unprocessable Entity` if compilation fails. # Read artifact files Source: https://www.magicpatterns.com/docs/api/read-artifact-files openapi-v3.yml post /v3/designs/{editorId}/artifacts/{artifactId}/files/read Returns the contents of one or more files in an artifact. Files that don't exist in the artifact are simply omitted from the response. This endpoint uses POST (with a request body) rather than GET (with a query string) so file names containing `/`, commas, or other special characters don't need URL encoding. # Resolve a Magic Patterns URL to an editor ID Source: https://www.magicpatterns.com/docs/api/resolve-design-url openapi-v3.yml post /v3/designs/resolve-url Given a Magic Patterns URL, returns the underlying `editorId`. Supports: - Design URLs: `magicpatterns.com/c/` - Published URLs: `project-.magicpatterns.app` - Canvas URLs: `magicpatterns.com/s/?nodeIds=`, and the `/n/`, `/p/` and `/e/` pages of the same canvas. A link to the canvas alone names a board of designs rather than a design, and is refused. Use this when a user shares a Magic Patterns link and you need the `editorId` to call other endpoints. # Send a prompt Source: https://www.magicpatterns.com/docs/api/send-prompt openapi-v3.yml post /v3/designs/{editorId}/prompts Sends a natural-language prompt to update an existing design. Returns immediately with a `requestId`; the AI generation runs in the background. Poll `GET /v3/designs/{editorId}/status` until `isGenerating` is `false`. Generation typically takes 2–10 minutes; do not poll more than once every 60 seconds. Before calling, check `GET /v3/designs/{editorId}/status` to confirm the design isn't already generating. Bills credits from the authenticated user's normal credit balance. # Write artifact files Source: https://www.magicpatterns.com/docs/api/write-artifact-files openapi-v3.yml patch /v3/designs/{editorId}/artifacts/{artifactId}/files Creates or overwrites one or more files in an artifact. Files that already exist are replaced; new files are appended. Files not mentioned in the request are left untouched. This only updates source files — it does **not** compile or publish. Call `POST /v3/designs/{editorId}/artifacts/{artifactId}/publish` when you're done with all file changes to compile and set the artifact active. # Inline Comments Source: https://www.magicpatterns.com/docs/documentation/collaboration/inline-comments Leave feedback directly on specific elements in a design Inline comments let you leave feedback directly on specific elements in a design. This makes reviews faster, clearer, and easier to track across teammates and iterations. ![](https://mintcdn.com/magicpatterns/r7WxSEN_k7EK12_1/documentation/collaboration/images/comments-full-sidebar.png?fit=max\&auto=format\&n=r7WxSEN_k7EK12_1\&q=85\&s=ed02512e5655ad070bf7238660dbae95) ## Get your share link To collect feedback, start by clicking on the Share button in the editor navbar. **1. Open Share** In the editor, click the Share button. **2. Copy the Link** ![](https://cdn.magicpatterns.com/uploads/hLz5mzwxDWRcge45n1sdQz/share-panel.png) **3. Send it to your teammates** Anyone with the preview link can view the design and leave comments (if they have access). ## Enter Comment Mode ### From the editor * Click the **comment** icon in the editor navbar to toggle Comment Mode. ![](https://mintcdn.com/magicpatterns/r7WxSEN_k7EK12_1/documentation/collaboration/images/editor-room-comment-mode-button.png?fit=max\&auto=format\&n=r7WxSEN_k7EK12_1\&q=85\&s=4f0392593c64f7857fb056e2e7e6997d) ### From the share link * Open the preview link and click the **comment** icon to toggle Comment Mode. ![](https://mintcdn.com/magicpatterns/r7WxSEN_k7EK12_1/documentation/collaboration/images/preview-link-comment-mode-button.png?fit=max\&auto=format\&n=r7WxSEN_k7EK12_1\&q=85\&s=2db7ee8a07ac32fa795578d15f67d755) > [!TIP] > > You can quickly toggle Comment Mode with **C**. You can also > hide/show comment indicators with **H**. ## Add an inline comment Once Comment Mode is enabled: **1. Click an element in the design** Tap on the specific UI element you want to comment on. **2. Write your feedback** Add context, describe the issue, and include a suggestion if you can. **3. Post the comment** Your comment appears as an indicator on the design and in the comments panel. > [!NOTE] > > Comments are **tied to elements** in the design. If you resize > the screen and elements move, your comments stay anchored to the right > elements. ![](https://mintcdn.com/magicpatterns/r7WxSEN_k7EK12_1/documentation/collaboration/images/adding-new-comment.png?fit=max\&auto=format\&n=r7WxSEN_k7EK12_1\&q=85\&s=c3a59016214210d6afb126ad4a05e3ad) ## Commmon workflows: * Async design reviews: Share a preview link, ask reviewers to leave comments directly on the relevant UI, and iterate without long meetings. * Collecting feedback: Product, engineering, and stakeholders can comment on exactly what they mean—even if they're not editing the design. * Bug or polish tracking: Use comments as a lightweight checklist while you refine the UI (resolve items as you address them). * Version-aware feedback: Comments can be grouped by design version, so you can understand what feedback applies to which iteration. ## Troubleshooting > [!WARNING] > > If you don't see comment indicators in the editor, make sure **comment mode** > is active (toggle it in the toolbar). ## Video Guide This topic is covered in our video lesson [Team Workflows and Sharing](/docs/documentation/guide/team-workflows-and-sharing). [Team Workflows and Sharing](https://www.youtube.com/embed/KMd_1dNQLeI?si=9xAlg5KBE941_5sP) # Live Multiplayer Source: https://www.magicpatterns.com/docs/documentation/collaboration/live-multiplayer Work on the same design or canvas with your team in real time. Magic Patterns is multiplayer everywhere, much like Figma. When you and a teammate open the same design or canvas, you both see who else is around and the page updates live as either of you (or the agent) makes changes. ## In the design editor You'll see your teammates' avatars in the toolbar, and the chat thread, generations, and design preview update for everyone at the same time. Read-only viewers can follow along and leave [inline comments](/docs/documentation/collaboration/inline-comments). ![Two teammates on the same Magic Patterns design with synchronized chat and preview](https://cdn.magicpatterns.com/uploads/dgMseN8Su1c8ECNTnAV6Tn/multiplayer-design.gif) ## On the canvas The MagicOS goes a step further with live cursors. When a teammate selects a screen, it gets a colored outline matching their cursor color, so you can see exactly where each teammate is and what they're working on. ![Live cursors and selections on a shared Magic Patterns canvas](https://cdn.magicpatterns.com/uploads/bcYyKSV4yms73eHKNM8YJb/multiplayer.gif) ## Who can join Anyone with access to the design or canvas joins automatically when they open it. Set permissions through [Sharing Designs](/docs/documentation/editor/sharing) and [Team Workspaces](/docs/documentation/collaboration/team-workspaces). # Team Workspaces Source: https://www.magicpatterns.com/docs/documentation/collaboration/team-workspaces Invite team members, manage your brand context, and configure workspace settings. Team Workspaces give your team a shared place to work together, manage members, share Design Systems and components, and centralize billing. ## Getting started Go to [magicpatterns.com/settings/team](https://www.magicpatterns.com/settings/team) to manage your workspace. Only admins can manage the workspace; you can see who is the admin in the Team Members table under the Role column. You'll see: * Team Members – Everyone in your workspace * Subscription Plan – Your current plan (Starter, Business, or Enterprise) * Billable Seats – How many paid seats you're paying for * Available Seats – How many seats are free to assign ![Team Members table showing subscription overview and member list with Role column](https://cdn.magicpatterns.com/static/docs/team-members-table.png) > [!TIP] > > You can invite unlimited team members. Free seats are included at no cost. > Only paid seats count toward your bill. ## Understanding seats A seat is a paid spot on your workspace plan. Each seat gets its own monthly credits and full access to generate designs. You pay for the number of seats you need. * Paid seat – Full access, uses credits, counts toward your bill * Free seat – In the workspace at no cost, free monthly credits for generation When you invite someone, they join with a Free seat by default. To give them full access, add a paid seat first (if needed), then assign it to them. Only admins can invite and manage members. ## Workspace size and plans Each plan has a limit on the number of paid seats: * Starter: Up to 10 paid seats * Business: 11 or more paid seats * Enterprise: 10 paid seats minimum If your workspace grows beyond 10 paid seats, you'll need to upgrade to Business or Enterprise. Free seats don't count toward this limit. ## Common scenarios > **I need to add a teammate with full access** > > 1. Go to [magicpatterns.com/settings/team](https://www.magicpatterns.com/settings/team) > 2. If you're out of seats, click Add more seats first and complete the payment > 3. Click Invite and enter their email > 4. Once they've joined, click the ... next to their name > 5. Click Upgrade to assign them a paid seat > **Someone left the team. I want to give their seat to someone else** > > Use Reassign Seat to move a paid seat from one person to another: > > 1. Click the ... next to the member who is leaving > 2. Click Reassign Seat > 3. Select the team member who should receive the seat > > Credits already used on that seat transfer to the new member. The person who > had the seat stays in the workspace but moves to a Free seat. The person > receiving the seat gets it right away. > **I want to remove someone's seat but keep them in the workspace** > > Use Cancel Seat when you want to free up a seat but keep the person in the > workspace: > > 1. Click the ... next to the member > 2. Click Cancel Seat > 3. Their seat is marked for cancellation and frees up at the end of your > billing cycle > 4. Until then, they keep full access. After the billing cycle ends, they > remain in the workspace with a Free seat > > You cannot cancel your own seat. Use Manage Plan to change or cancel the > workspace subscription instead. > **I need to remove someone from the workspace entirely** > > 1. Click the ... next to the member > 2. Click Remove > 3. They are removed from the workspace > **I changed my mind about cancelling a seat** > > 1. Click the ... next to the member whose seat is pending cancellation > 2. Click Undo Cancellation > 3. The seat stays active > **I'm out of seats. How do I add more?** > > 1. Go to [magicpatterns.com/settings/team](https://www.magicpatterns.com/settings/team) > 2. Click Add more seats > 3. Choose how many seats you need > 4. Complete the payment > > Seats are prorated. You pay for the remainder of your billing cycle. > **I have too many seats. How do I reduce them?** > > Cancel seats for members who no longer need full access. Each cancelled seat > frees up at the end of your billing cycle. You cannot reduce seats below the > number of members who currently have active seats. > **I want to change our plan (upgrade or downgrade)** > > 1. Go to [magicpatterns.com/settings/subscription](https://www.magicpatterns.com/settings/subscription) or [magicpatterns.com/settings/team](https://www.magicpatterns.com/settings/team) > 2. Click Manage Plan > 3. Select a new plan and complete the change in the payment portal > > See [Credits and Billing](/docs/documentation/get-started/credits-and-billing) > for how upgrades, downgrades, and prorating work. ## When to use a Team Workspace Team Workspaces work well when you: * Work with multiple designers or developers on the same product * Need a consistent brand across many pages or projects * Share design systems, components, or templates * Want one person to manage billing for the whole team Once teammates are in the workspace, opening the same design or canvas puts you in a [live multiplayer session](/docs/documentation/collaboration/live-multiplayer), with shared chat, generations, and (on the canvas) live cursors and shared selections. ## Roles * Admin – Can invite members, add seats, manage plans, upgrade or downgrade members, remove members, and change roles * Member – Can use the workspace based on their seat; cannot manage billing or other members ## Usage reporting **Business** and **Enterprise** workspaces include Usage Reports at [magicpatterns.com/settings/usage-reports](https://www.magicpatterns.com/settings/usage-reports). There you can track workspace adoption, compare activity with a team leaderboard, and review time saved. Workspaces on other plans see an upgrade prompt until you move to Business or Enterprise. ![Unlock Usage Reporting modal on the Usage Reports dashboard](https://cdn.magicpatterns.com/uploads/jcHU4QviYhREXQAGjYWm5P/usage-report.png) ## Moving files between workspaces You can move designs between workspaces directly from the dashboard. Right-click on any file to see the option to move it to a different workspace. ![Right-click on a file to move it between workspaces](https://cdn.magicpatterns.com/uploads/cCfwJZdrt33DxMB91dGGDE/right-click-to-change-files.png) This is useful when you need to: * Transfer a design from your personal workspace to a team workspace * Reorganize designs between different team workspaces * Move completed work to a shared workspace for collaboration ## SSO and SCIM SSO, SCIM, and auto-join are available for team workspaces. SSO is self-serve and available on Business plans and Enterprise plans. SCIM is available on Enterprise plans. See [SSO and SCIM setup](/docs/documentation/enterprise/sso-scim-setup) for details. # Connectors Source: https://www.magicpatterns.com/docs/documentation/connectors/connectors Connect your tools, databases, and apps to Magic Patterns for more relevant AI responses. ## What are Connectors? Connectors let Magic Patterns work with your external tools, databases, and applications to give you more relevant responses. Powered by the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), connectors allow the AI assistant to pull in real context from the services you already use -- like meeting notes, project issues, or analytics data -- and incorporate it directly into your designs. When a connector is enabled, the AI assistant can discover and call tools exposed by the connected service. For example, if you connect Granola, the assistant can pull your recent meeting notes and use them to inform a design. [Introducing Connectors](https://www.youtube.com/embed/A-seva8EuqU?si=uNkGTbh3gjf05r0p) ## Available Connectors Magic Patterns ships with built-in support for the following services: | Connector | Description | | - | - | | **Granola** | Pull meeting notes and context into your designs. | | **Notion** | Pull pages, databases, and content from your Notion workspace. | | **Linear** | Pull issues, projects, and roadmaps from Linear. | | **Jira** | Pull issues, sprints, and project context from Atlassian Jira. | | **Miro** | Pull boards, frames, and visual context from Miro. | | **Mobbin** | Pull real-world UI screens, user flows, and design patterns from Mobbin. | More connectors are being added regularly. You can also [add your own custom MCP server](#adding-a-custom-mcp-server). ## Getting Started with Connectors This walkthrough uses **Granola** as an example, but the steps are the same for any built-in connector. **1. Open the Connectors Menu** In the editor, open the prompt bar dropdown and select the **Connectors** section. You will see a list of available connectors you can connect. ![Connectors menu in the prompt bar](https://cdn.magicpatterns.com/uploads/mD9fR7kytQYP8Ch6J6S5NB/pick-connector.png) **2. Connect a Service** Click the connector you want to enable (e.g. Granola). An OAuth dialog will appear. **3. Authorize Access** Click **Connect with OAuth**. A popup window will open asking you to sign in and authorize Magic Patterns to access your account. Once you approve, the popup will close and the connector will show as **Connected**. ![OAuth authorization flow for Granola](https://cdn.magicpatterns.com/uploads/g5y1JZmmGwMamJ5Bhwn7tH/granola-oauth.png) **4. Use It in Your Prompts** Once connected, the AI assistant will automatically have access to the tools exposed by your connector. Just mention the data you need in your prompts and the assistant will pull it in: * "Pull my latest meeting notes from Granola and design a summary dashboard" * "What did we discuss in yesterday's standup? Use that to create a task board" The assistant handles the connector calls behind the scenes and incorporates the returned data into your design. ## Managing Connectors ![Connectors settings page](https://cdn.magicpatterns.com/uploads/scRUd2jRLCHtG3WccKQgG2/connectors.png) From the **Connectors** section in Settings, you can: * Enable / Disable a connector using the toggle switch. Disabled connectors are not used by the AI assistant but remain connected. * Re-authenticate a connector by clicking the refresh icon. This is useful if your access token has expired. * Disconnect a connector by clicking the trash icon. This removes the connector and its stored credentials entirely. You can also manage connectors from the **Connectors** submenu in the editor prompt bar. ## Adding a Custom MCP Server If your team runs a custom MCP server, you can connect it to Magic Patterns directly. **1. Open Connector Settings** In the editor, open the prompt bar dropdown and select the Connectors section. At the bottom, click Manage Connectors to open the Connectors settings page. **2. Click Add Custom Connector** On the Connectors settings page, click the Add Custom Connector button at the bottom of the list. **3. Enter Server Details** Provide a Name (how it will appear in the UI) and the MCP Server URL (for example, [https://mcp.yourcompany.com/mcp](https://mcp.yourcompany.com/mcp)). **4. Authenticate** After adding the connector, click Connect to begin the OAuth flow. Magic Patterns will automatically discover your server's OAuth endpoints via the standard well-known metadata endpoints. > [!WARNING] > > Only connect to MCP servers that you trust — Magic Patterns will be able to call any tools they expose. Your credentials are encrypted and never exposed to the frontend. Custom servers must support OAuth 2.0 and be publicly reachable. ## How It Works Connectors use the **Model Context Protocol (MCP)**, an open standard for connecting AI assistants to external data sources and tools. 1. When you connect a service, Magic Patterns performs OAuth 2.1 dynamic client registration with the MCP server's authorization server. 2. OAuth endpoints are discovered automatically via well-known metadata -- no manual configuration needed. 3. When the AI assistant needs data from a connector, it calls the MCP server's tools using the stored access token. 4. Tool results are returned to the assistant and incorporated into its response. You can expand any connector tool call in the chat to see the raw result. # Colors Source: https://www.magicpatterns.com/docs/documentation/design-systems/editing/colors Define your color palette for AI generation and Visual Edit The Colors page lets you define your color palette inside your Design System: your primary, secondary, accent, and any other colors your brand uses. Once defined, these colors are available across the platform in generated code and in the [Visual Edit](/docs/documentation/editor/how-to-prompt) color picker. This keeps your styling consistent without having to re-specify colors every time. ![Colors page in a Design System](https://cdn.magicpatterns.com/uploads/s1u2Vn3kY2aKAyjtLyxMgZ/CleanShot_2026-04-30_at_11.42.032x.png) To add a color, click **+ Add** and give it a name. Click any color swatch to open the color picker, or type a hex value directly. ## Why set up colors? ### Consistent AI Generation When you generate a design or [component](/docs/documentation/design-systems/editing/components) with a [Design System](/docs/documentation/design-systems/overview) that has colors set up, the AI will use your palette in the generated code. This means your colors end up in every new design without having to specify them in every prompt. ### Visual Edit When you select an element in [Visual Edit](/docs/documentation/editor/how-to-prompt), the color picker shows a "Design System" section with your defined colors. This lets you apply colors from your palette directly to any element. ![Design System colors in the Visual Edit color picker](https://cdn.magicpatterns.com/uploads/wHNGeKqpqmFkk2TG6YZh5B/CleanShot_2026-04-30_at_13.10.212x.png) ## Importing Colors You can bulk-import color tokens into your Design System from a `.csv` file or a Figma `.json` variable export. This is the fastest way to bring an existing palette into Magic Patterns without manually adding each color. ![Design System Color Import Flow](https://cdn.magicpatterns.com/uploads/dFCtQpduz3E9hAWCpmDUxJ/CleanShot_2026-04-30_at_13.12.41.png) > [!TIP] > > You can upload multiple files at once. For example, upload a light-mode and a > dark-mode export and Magic Patterns will let you assign each group to the > correct mode during review. ### Importing from CSV Your CSV file should have two columns: a **token name** and a **color value**. The first row can be a header or you can start with data directly. Accepted header names for the **name column**: `name`, `key`, `token`, `variable`. Accepted header names for the **value column**: `value`, `color`, `hex`, `code`. Color values can be hex (`#FF0000`), rgb (`rgb(255, 0, 0)`), or hsl (`hsl(0, 100%, 50%)`). ```csv theme={null} token,hex color.blue.10,#DDF3FC color.blue.20,#BBE7F9 color.blue.30,#98DBF7 color.gray.10,#F2F2F2 color.gray.20,#EBEBEB ``` Dotted or hyphenated names like `color.blue.10` or `background-primary` are automatically converted to readable labels (e.g. "Color Blue 10", "Background Primary") during import. ### Importing from Figma Variables Follow these steps to export your color variables from Figma as a JSON file that Magic Patterns can read. **1. Open the Variables Panel** In Figma, go to **View > Panels > Toggle Variables** to open the variables panel. ![Figma Variables Panel](https://cdn.magicpatterns.com/uploads/4nV7AwcHzanPzH4zsuVyuw/figma-variables.png) **2. Export a Collection** Right-click on the collection you want to export and select **Export modes**. This will export all variables in that collection. ![Figma Export Modes](https://cdn.magicpatterns.com/uploads/11kqLn6S24VCUwmDsd5Kx8/figma-export-modes.png) **3. Unzip Multi-Mode Exports** If your collection has multiple modes (e.g. Light and Dark), Figma will download a `.zip` file. Unzip it to find separate `.json` files for each mode, so that you can upload them all into the color import flow. ### Importing into your Design System Once you have your files ready: **1. Tap on 'Import from File'** Go to your Design System's **Colors** page and click the **Import from File** button. You can find it in the empty state or next to the **Add** button in the color table. **2. Upload your files** Drag and drop your `.csv` or `.json` files, or click to browse. You can upload up to 20 files at once. **3. Review and assign modes** Magic Patterns parses your files into color groups. For each group you can toggle it on or off and assign it to **Light** or **Dark** mode. **4. Import** Click **Import** to add the colors to your Design System. If you already have colors defined, you will be asked to confirm before they are merged. > [!NOTE] > > Importing **merges** into your Design System. Tokens whose names match the > imported ones are updated with the new values, and all of your other tokens > are kept. Colors and spacing are imported separately: the **Colors** page only > writes color tokens, and the **Spacing & Misc. Tokens** page only writes > spacing and other tokens. ## What's Next? > **[Rules](/docs/documentation/design-systems/editing/rules)** > > Define spacing, visual rules, and brand guidelines for the AI. > **[Typography and Icons](/docs/documentation/design-systems/editing/typography-and-icons)** > > Manage font groups and icons in your Design System. # Components Source: https://www.magicpatterns.com/docs/documentation/design-systems/editing/components Reuse your custom components in your designs Components are like lego bricks. You can reuse them in your designs. Example components are buttons, cards, and modals. All of your components live inside a [Design System](/docs/documentation/design-systems/overview) and are managed together in a single, unified editor. You chat with the Design System as a whole to add, edit, and refine one or many components at a time, then publish a new version of the Design System when you're ready. > [!TIP] > > Do you work with an existing design system? You can [import it from > Figma](/docs/documentation/design-systems/importing/figma) or [link a GitHub > repo](/docs/documentation/design-systems/importing/github) to bring your components > into Magic Patterns. ## Creating a New Component Components live inside [Design Systems](/docs/documentation/design-systems/overview). To create a new component, you simply ask the agent for it from the Design System chat. **1. Open your Design System** From the dashboard, navigate to [**Design Systems**](/docs/documentation/design-systems/overview) and open the Design System where you want to add the component. ![](https://cdn.magicpatterns.com/uploads/8hSQJbDdAU9qkDdDX1NkoZ/CleanShot_2026-04-30_at_11.41.422x.png) **2. Go to the Components page** Inside your [Design System](/docs/documentation/design-systems/overview), open the **Components** page. It shows the component list on the left, the selected component's preview/code in the middle, and the unified chat on the right. ![](https://cdn.magicpatterns.com/uploads/cfvY3b5TVStnNB8HdPUYYf/CleanShot_2026-04-30_at_11.42.562x.png) **3. Ask the agent to create your component** In the chat, describe the component you want. You can attach a screenshot, paste a Figma frame, or describe it in plain English. ```text theme={null} Add a PricingCard component with three tiers and a featured highlight on the middle tier. ``` The agent creates the component, adds it to your Design System, and shows it in the preview. You can keep iterating in the same chat that edits every other part of your Design System. We recommend being specific and using screenshots as references when possible for the best results. ## Editing Components Everything inside a Design System (components, typography, colors, icons, spacing, rules) is edited from a single chat that lives with the Design System. The chat is available on every tab in the Design System and operates on the **whole** Design System, not just the tab you're on. You can: * **Edit one component**: tag it with `@` or refer to it by name. *"Make `@Button` rounder and add a destructive variant."* * **Edit several at once**: *"Update `@Card`, `@Modal`, and `@Toast` to use a 12px border radius."* * **Make universal updates**: *"Tighten the spacing scale across the whole system"* or *"switch the primary color to indigo and update every component that uses it."* * **Update typography or colors from any tab**: ask in the chat and the agent updates the relevant tokens and the components that depend on them. The chat history lives on the Design System, so you (and your teammates) can see exactly how the Design System has evolved over time. ## Versioning & Publishing Versions are tracked at the **Design System level**. The version selector in the top-right of the editor shows your current version (e.g. `v1.2`), and you can revert to a prior version from the same dropdown. When you publish a new version of your Design System, a modal appears letting you choose which existing designs to upgrade to that version. This lets you roll out a batch of changes (across many components, tokens, or rules) to all your designs in one step. ![](https://cdn.magicpatterns.com/uploads/c5D91uHadZ2nr7jgoe9tmz/CleanShot_2026-04-30_at_14.08.01.png) ![](https://cdn.magicpatterns.com/uploads/vkmaDG23NWrCa9ovHivWiC/CleanShot_2026-04-30_at_14.08.38.png) ## Using Components There are two ways to use components from your Design System in designs: ### Automatic Usage with Design Systems When you create a [Design System](/docs/documentation/design-systems/overview) and add components to it, the AI will automatically use those components when generating designs. You don't need to manually reference them. Just select your Design System when creating a new design. > **[Learn about Design Systems](/docs/documentation/design-systems/overview)** > > Set up a Design System with your components for automatic usage across all > designs. ### Manual Reference with @ You can also explicitly reference components in your prompts using the `@` symbol. This is useful when you want to use a specific component or reference components from outside your current Design System. How it works: 1. Start typing `@` in the chat 2. A component selector appears 3. Select the component you want 4. The component is added to your prompt ![](https://cdn.magicpatterns.com/uploads/e1ZHQkaKciLdWXy76LkoKm/CleanShot_2026-04-30_at_12.47.16.png) Example: ``` Create a pricing page using @PricingCard and @CTAButton ``` ## Deleting Components > [!WARNING] > > Deleting a component is permanent and cannot be undone! You can also deprecate a component instead of deleting it, which means the AI will no longer use it in new designs. 1. Open your [Design System](/docs/documentation/design-systems/overview) and find the component 2. Click the three dots next to the component name and select **Delete** 3. Confirm the deletion ![Delete a component from a Design System](https://cdn.magicpatterns.com/uploads/8AWRRJsMRR62CVmF3TNLWb/CleanShot_2026-04-30_at_11.43.032x.png) # Rules Source: https://www.magicpatterns.com/docs/documentation/design-systems/editing/rules Define default styling rules for consistent designs Rules is where you define the general design rules and prompts that the AI uses when generating components and pages. If you are familiar with other AI tools, you can think of this as "default prompts" or "skills." Define it once, and every design follows your brand rules. ![](https://cdn.magicpatterns.com/uploads/rwvpNLGHisVmRfnXw63BbQ/CleanShot_2026-04-30_at_11.42.252x.png) ## Example Rules > [!TIP] > > Upload your brand guidelines to ChatGPT and ask it to create Rules for Magic > Patterns! Here's a well-structured Rules page: ```text theme={null} You are designing for the Acme Inc company. Acme Inc makes B2B SaaS and has users that do XYZ. ## Brand Voice: Professional but approachable ## Visual Rules - Border radius: 8px - Shadows: subtle (0 1px 3px rgba(0,0,0,0.1)) - Spacing: 16px between sections - Style: Clean, minimal, lots of whitespace ``` ## What's Next? > **[Colors](/docs/documentation/design-systems/editing/colors)** > > Manage your brand color tokens visually with the Colors page. > **[Typography and Icons](/docs/documentation/design-systems/editing/typography-and-icons)** > > Manage font groups and icons in your Design System. # Skills Source: https://www.magicpatterns.com/docs/documentation/design-systems/editing/skills Reusable instructions the AI activates when a task matches Skills are reusable instruction packages that the AI can activate when a task matches their description. They extend what designs built with your [Design System](/docs/documentation/design-systems/overview) can do, beyond the always-on guidance in [Rules](/docs/documentation/design-systems/editing/rules). A skill is a `SKILL.md` package with a name and a description. The description tells the AI *when* to reach for the skill; the body holds the specialized instructions it should follow once activated. Unlike Rules (which apply to every generation), skills are pulled in only when they're relevant to what you're asking for. ![Skills in a Design System](https://cdn.magicpatterns.com/uploads/8hSQJbDdAU9qkDdDX1NkoZ/CleanShot_2026-04-30_at_11.41.422x.png) ## Adding a Skill Open your Design System and go to the **Skills** section. You have two options: ### Create a new skill Click **New Skill** to scaffold a `SKILL.md` package you can edit in place. Give it a clear name and a description that states exactly when the AI should use it, then write the instructions in the body. > [!TIP] > > The description is the most important part. The AI matches the user's request > against it to decide whether to activate the skill, so be specific about the > scenarios it covers. ### Install a skill Click **Install Skill** and paste an install command. Only the `npx skills add --skill ` format is supported. Repos must be hosted on `github.com`, `gitlab.com`, or `bitbucket.org` (or use the GitHub `owner/repo` shorthand). ```bash theme={null} npx skills add vercel-labs/agent-skills --skill frontend-design ``` ## Managing Skills The Skills section lists every package in your Design System with its name and description. Open a skill to edit its files, or use the kebab menu to delete a package. Skills that fail validation are flagged as **Invalid** so you can fix the `SKILL.md` frontmatter. Like everything else in a Design System, skills are versioned with the Design System, so changes roll out when you publish a new version. # Typography and Icons Source: https://www.magicpatterns.com/docs/documentation/design-systems/editing/typography-and-icons Learn how to use custom fonts and icons in your Magic Patterns designs ## Typography Magic Patterns supports custom fonts through the **Typography** section of your [Design System](/docs/documentation/design-systems/overview). You can upload your own font files, choose a popular Google Font, or paste a web-hosted font URL. Every design created with that Design System will automatically use your specified fonts. You can also reference any font by name directly in your prompts: ```Example Prompt theme={null} Use Merriweather font from Google Fonts. ``` ### Managing Fonts in Your Design System The Typography section lives inside your Design System and lets you create font groups for different use cases like headings, or body text ![Typography in Design Systems](https://cdn.magicpatterns.com/uploads/qe3dGXfetVTGPRSKSpP4XG/CleanShot_2026-04-30_at_11.41.492x.png) To set up fonts in your Design System: 1. Open your Design System 2. Go to the **Typography** section 3. Click Add Font Group to create a new group 4. Choose your font source: * Upload your own custom font file * Pick a Google Font from [fonts.google.com](https://fonts.google.com) * Paste a link to any web-hosted font 5. Save your changes Now every design you create with that Design System will automatically use your specified fonts. ### Finding Google Fonts To explore available fonts: 1. Visit [Google Fonts](https://fonts.google.com) to browse thousands of free fonts 2. Preview different fonts and styles 3. Note the font name (e.g., "Roboto", "Playfair Display") 4. Use that exact name when adding a Google Font group, or reference it directly in your prompt ## Icons Magic Patterns supports custom icons through the **Icons** section of your [Design System](/docs/documentation/design-systems/overview). You can choose from popular icon libraries like Lucide, or import your own custom icons by uploading SVG files or providing URLs. ![Icons in Design Systems](https://cdn.magicpatterns.com/uploads/7GfrnL9Y2imEPXwrftgyJV/CleanShot_2026-04-30_at_11.42.102x.png) ### Managing Icons in Your Design System The Icons section lives inside your Design System and lets you choose between two modes: 1. **Icon Library** - Select from popular icon packages like Lucide React 2. **Manual Import** - Upload your own custom icons by providing SVG files or URLs To set up icons in your Design System: 1. Open your Design System 2. Go to the **Icons** section 3. Choose your icon source: * Select an icon library from the dropdown (e.g., Lucide React) * Or switch to Manual Import to add custom icons 4. For manual imports, you can: * Drag and drop SVG files * Paste SVG code directly * Provide URLs to hosted icon files 5. Save your changes Now every design you create with that Design System will have access to your specified icons. # Figma Source: https://www.magicpatterns.com/docs/documentation/design-systems/importing/figma Import frames and components from Figma into your Design System > [!NOTE] > > Looking to import a full Figma library? [Book a > call](https://cal.com/team/magicpatterns/book-a-call?utm_source=docs) and our team will help. We are working > towards making this self-serve! You can bring your Figma work into Magic Patterns to seed a Design System: import full frames as designs, or import individual Figma components as reusable [components](/docs/documentation/design-systems/editing/components). ## Connect your Figma account Before importing, connect your Figma account to Magic Patterns. This enables both copy-paste and URL-based imports, and lets us use the **Figma MCP Server** to extract richer design data for higher-quality imports. > [!NOTE] > > The Figma MCP Server is only available for `Dev` and `Full` Figma accounts. > `Free` and `Collab` accounts will still work but may have less precise > imports. ## Import a .fig file Uploading a `.fig` file is the fastest way to seed a whole Design System from Figma. Magic Patterns parses the file and extracts your **colors** (including color variables), **typography**, **spacing/sizing tokens**, and **components** (component sets and their variants) to build your import plan with no Figma account connection required. **1. Save a local copy of your Figma file** In Figma, open the file you want to import and choose **File → Save local copy…** to download a `.fig` file to your computer. **2. Link Figma as a Source** When creating a new Design System or updating your linked sources in the **Settings**, open **Link Figma**. **3. Drop in your .fig file** Drag the `.fig` file onto the drop zone, or click to browse for it. Once it uploads, finish creating the Design System and we'll extract your colors, typography, variables, and components into the import plan for you to review. > [!NOTE] > > Current limits: we read the file's default variable mode (light/dark mode > themes aren't split out yet), and embedded raster images aren't imported. > Colors and components are ranked by usage and capped so the most-used tokens > come through first. ## Import a component into your Design System **1. Open your Design System and create a component** Go into your [Design System](/docs/documentation/design-systems/overview), open the **Components** page, and click **Create Component**. Choose the **Import from Figma** tab. ![](https://cdn.magicpatterns.com/static/docs/component-import-from-figma.png) **2. Copy the link to a frame in Figma** Select a frame or component in Figma, right click and choose **Copy as → Copy link to selection** (or press `CMD + L`). **3. Paste the link and import** Paste the link into the import dialog, confirm the preview looks right, choose your library, and click **Import**. > [!NOTE] > > You can import **one frame at a time**. Import from Figma won't always produce > a pixel-perfect frame, because every Magic Patterns design is code-first and > interactive, whereas Figma frames are not. ## Learn more > **[Import from Figma](/docs/documentation/importing/import-from-figma)** > > The full guide to importing designs and components from Figma, including > copy-paste and URL imports. # GitHub Source: https://www.magicpatterns.com/docs/documentation/design-systems/importing/github Link a GitHub repository to import components and styles Linking a GitHub repository lets Magic Patterns read your component source directly, so generated designs use your real code and import paths. This is the fastest way to seed a Design System when your components already live in a repo. ## Connect your GitHub account Before you can link a repo, connect your GitHub account so Magic Patterns can read the repository and browse its folders. When you open the **Link GitHub** connector, you'll be prompted to connect if you haven't already. > [!NOTE] > > We only need read access. Magic Patterns reads the repository to import your > components and styles; it does not write to your repo. ## Link a repository **1. Open the GitHub connector** From your Design System, open the linked-sources panel (during onboarding, or later from **Access & Settings**) and choose **Link GitHub**. **2. Pick or paste a repository** If your account is connected, start typing to autocomplete from the repositories Magic Patterns can see. You can also paste a repository URL directly: ``` https://github.com/your-org/your-repo ``` **3. Choose subfolders (optional)** Once the repo resolves, you can browse its folders and select specific subfolders to import. For large repos, selecting a subfolder (for example the folder that holds your components) is required so we only scan the relevant code. **4. Link** Click **Link** to attach the repository. Magic Patterns scans it and proposes the components, colors, and tokens it finds for you to review. > [!TIP] > > You can paste a `/tree//` folder URL or a `/blob/...` file URL > and Magic Patterns will pre-select that subfolder for you. ## What's Next? > **[NPM Package](/docs/documentation/design-systems/importing/npm-package)** > > Connect a published component library instead of (or alongside) a repo. > **[Importing overview](/docs/documentation/design-systems/importing/overview)** > > See every way to bring an existing design system into Magic Patterns. # Local Code Folder Source: https://www.magicpatterns.com/docs/documentation/design-systems/importing/local-code-folder Upload a zipped export of your component library from your machine If your component library lives on your machine rather than in a connected repo, you can upload it directly. Magic Patterns reads your component source so generated designs use your real code and import paths. ## Upload your code **1. Open the Local Code connector** From your Design System, open the linked-sources panel (during onboarding, or later from **Access & Settings**) and choose **Link Local Code**. **2. Add your zipped export** Drag and drop, or click to browse for, a zipped export of your component library. Supported formats are `.zip`, `.tar.gz`, and `.tgz`. You can add more than one file. **3. Choose subfolders (optional)** After a file uploads, you can browse its contents and select specific subfolders to import (for example the folder that holds your components) so we only scan the relevant code. **4. Done** Once your uploads finish, continue. Magic Patterns scans the code and proposes the components, colors, and tokens it finds for you to review. > [!TIP] > > Linking [GitHub](/docs/documentation/design-systems/importing/github) instead keeps > your Design System in sync with a repo you already maintain. Use a local > upload when the code isn't in a repository Magic Patterns can reach. ## What's Next? > **[GitHub](/docs/documentation/design-systems/importing/github)** > > Link a repository to import components and styles straight from your code. > **[Importing overview](/docs/documentation/design-systems/importing/overview)** > > See every way to bring an existing design system into Magic Patterns. # NPM Package Source: https://www.magicpatterns.com/docs/documentation/design-systems/importing/npm-package Connect your published React component library so the AI uses your real code > [!NOTE] > > [Book a call](https://cal.com/team/magicpatterns/book-a-call?utm_source=docs) and our team will help set this > up. We are working towards making this self-serve! Connecting a published component library brings your existing React components into Magic Patterns. After everything is connected, the AI will: * Use your actual component code in generated designs * Respect your component APIs, props, and variants * Generate code with correct import paths * Stay consistent with your design system > [!NOTE] > > Everything on this page is guidance, not a checklist. We work with you during > onboarding and adapt to how your team already ships components. For example, > we have connected teams using the public NPM registry, private NPM, and GitHub > Packages (an npm-compatible registry with a read-only token and `.npmrc` > scoped to your organization). Prefer working from a repository instead? See > [linking GitHub](/docs/documentation/design-systems/importing/github). ## What we need To import your components, we need two things: 1. **Component code**: either via an NPM package plus access token, or a zip or tar bundle you send manually. This lets us render the components in the Magic Patterns editor and ensures visual parity. 2. **Component documentation**: either via Storybook or a custom MCP. This serves as context for the AI to understand your components and when to use each one. NPM, GitHub Packages, and other private registries are different ways to host and version the same package artifact; a zip, tar, or `npm pack` tarball you send manually fills the same role. ## Package structure We recommend keeping Storybook files next to your component sources so documentation stays close to the code and is easier for the AI to relate to usage. ``` my-design-system/ ├── package.json ├── src/ │ ├── components/ │ │ ├── Button/ │ │ │ ├── Button.tsx │ │ │ ├── Button.stories.tsx # Storybook file │ │ │ └── index.ts │ │ ├── Card/ │ │ │ ├── Card.tsx │ │ │ ├── Card.stories.tsx │ │ │ └── index.ts │ │ └── index.ts # Re-exports all components │ └── index.ts # Main entry point └── dist/ # Compiled output ``` > **React Components** > > Your code must be written in React. ## Ways to share **Registry token** If your package is on a private registry (NPM, GitHub Packages, or another npm-compatible host), share a read-only access token. ```bash theme={null} # Generate a read-only token npm token create --read-only ``` Share this token securely with your Magic Patterns contact. **Manual Bundle** You can also send a zip or tar bundle of your component library. ```bash theme={null} # Create a tarball of your package npm pack ``` That produces a `.tgz` file you can send to us directly. ## Documentation best practices Good documentation helps the AI understand not only what your components do, but when to use them. > [!WARNING] > > Listing props alone is not enough. The AI needs context about when to pick one > component or variant over another. ### Usage guidance For each component, cover: * Purpose: what problem the component solves * When to use: which scenarios should lead to this component * When not to use: anti-patterns or wrong fits * Variants: when each variant is appropriate ```tsx theme={null} /** * Button component for user actions. * * @usage * - Use `primary` variant for the main call-to-action on a page * - Use `secondary` variant for less important actions * - Use `destructive` variant only for delete/remove actions * - Use `ghost` variant for tertiary actions or in toolbars * * @when-not-to-use * - Do not use Button for navigation; use Link instead * - Do not use multiple primary buttons in the same section */ export const Button = ({ variant, size, children, ...props }) => { // ... } ``` ## Working with multiple packages Many design systems split across packages that depend on each other. Magic Patterns supports that layout. > **Monorepo** > > Multiple packages in one repository (for example Yarn workspaces, Turborepo, > or Nx) > **Multi-Repo** > > Separate repositories for packages that depend on each other If packages depend on each other, we account for that when syncing: ``` @mycompany/tokens # Design tokens (colors, spacing, etc.) @mycompany/primitives # Low-level components (Box, Text, etc.) @mycompany/components # High-level components (Card, Modal, etc.) ``` The AI can: * Import from the correct package * Use shared tokens in a consistent way * Respect your component layering For multiple packages, plan to share: 1. Package list: every package that belongs to the design system 2. Dependency graph: how those packages relate 3. Access tokens: credentials for each private package when needed > [!TIP] > > In a monorepo, one access token often covers every package in the workspace. Generated code can then follow your structure: ```tsx theme={null} import { colors, spacing } from '@mycompany/tokens' import { Box, Text } from '@mycompany/primitives' import { Card, Button } from '@mycompany/components' export const PricingCard = () => { return ( Premium Plan ) } ``` ## Next steps > **[Schedule a call](https://cal.com/team/magicpatterns/book-a-call?utm_source=docs)** > > Book time to plan connecting your real component library with your team. # Overview Source: https://www.magicpatterns.com/docs/documentation/design-systems/importing/overview Bring an existing design system into Magic Patterns If you already have a design system, you don't have to rebuild it from scratch. Magic Patterns can pull your existing components, tokens, and styles from the sources you already use, so generated designs match your product from day one. You can start a Design System empty and build it up in the dashboard (see [Getting Started](/docs/documentation/design-systems/overview)), or seed it by linking one or more of the sources below. ## Ways to import > **[GitHub](/docs/documentation/design-systems/importing/github)** > > Link a repository and pull components and styles straight from your code. > **[Local Code Folder](/docs/documentation/design-systems/importing/local-code-folder)** > > Upload a zipped export of your component library from your machine. > **[NPM Package](/docs/documentation/design-systems/importing/npm-package)** > > Connect a published React component library so the AI uses your real code. > **[Figma](/docs/documentation/design-systems/importing/figma)** > > Import frames and components from a Figma file. > **[Your website](/docs/documentation/design-systems/importing/overview)** > > Match colors, fonts, and styles from a live website. ## How linking works When you create a Design System, you can link sources during onboarding (or later, from **Access & Settings**). After you link a source, Magic Patterns scans it and proposes the components, colors, typography, and tokens it finds. You review what gets imported before it lands in your Design System. > [!TIP] > > You can link more than one source. For higher-quality results, pair a visual > source like your website or a Figma file with a code source like GitHub so the > AI has both the look and the real implementation. ## Connecting your real engineering design system Enterprise teams often want generated UI to match a real engineering handoff: the same React components and import paths your product ships with, not only visual parity. That flow is **not fully self-serve** because every codebase has nuances (build configs, token formats, export conventions) that benefit from a guided setup. > **[Schedule a call](https://cal.com/team/magicpatterns/book-a-call?utm_source=docs)** > > Book time to plan connecting your real component library with your team. See [customer case studies](https://www.magicpatterns.com/customers) for examples of teams that ship from their real design system. # Prompting Source: https://www.magicpatterns.com/docs/documentation/design-systems/importing/prompting Describe or paste references in chat to build your Design System You don't have to import anything to get started. From the Design System chat, you can describe what you want in plain English and the agent builds it for you, adding components, colors, typography, and tokens to your Design System as you go. ## Ways to prompt * **Describe it**: Tell the agent what you're building. *"Create a Button, Card, and Modal that all share a 12px border radius and our brand blue."* * **Paste an image**: Drop in a screenshot or reference image and ask the agent to match it. Great for recreating an existing UI or working from a mockup. * **Paste a Figma frame**: Copy a frame in Figma (`⌘C`) and paste it into the chat to seed components from your designs. * **Reference what exists**: Mention components by name with `@` to build on or refine pieces you've already added. > [!TIP] > > Be specific and include references where you can. A short description plus a > screenshot usually produces a much closer result than words alone. ## How it works The chat lives with your Design System and operates on the **whole** system, so you can add several things at once or refine many components in a single message. Keep iterating in the same chat, then publish a new version when you're ready. > **[Editing your Design System](/docs/documentation/design-systems/editing/components)** > > Learn how to chat with your Design System to add, edit, version, and publish > components. # Getting Started Source: https://www.magicpatterns.com/docs/documentation/design-systems/overview Set up your design system in Magic Patterns A Design System is your team's single source of truth for styling and components. Our Design Systems feature is what makes Magic Patterns fundamentally different from other AI tools. Once you have your design system set up, it ensures every design follows the same visual rules and uses the same building blocks. ![](https://cdn.magicpatterns.com/uploads/8hSQJbDdAU9qkDdDX1NkoZ/CleanShot_2026-04-30_at_11.41.422x.png) You can build a Design System from scratch in the dashboard, or seed it from tools you already use by [importing](/docs/documentation/design-systems/importing/overview) from GitHub, an NPM package, Figma, or your website. ## What's Inside a Design System | Concept | Purpose | | - | - | | **Components** | Browse and manage reusable UI building blocks used across your designs | | **Typography & Icons** | Manage font groups and icon sets used across your designs | | **Colors** | Visually manage your brand color tokens, with dark mode and token references | | **Rules** | Default styling rules (spacing, visual style, brand voice) applied to every design | | **Skills** | Reusable instructions the AI activates when a task matches their description | | **Access & Settings** | Manage sharing, permissions, and other Design System configuration | ## Getting Started **1. Create a Design System** From your dashboard, click **Design Systems** → **Create a design system**. You can also go directly to [magicpatterns.com/design-systems](https://www.magicpatterns.com/design-systems). ![](https://cdn.magicpatterns.com/uploads/7cHAwSGA6HjVBZ76eEwf4y/CleanShot_2026-04-30_at_11.46.142x.png) **2. Import your existing sources (optional)** Already have a design system? Link [GitHub](/docs/documentation/design-systems/importing/github), an [NPM package](/docs/documentation/design-systems/importing/npm-package), [Figma](/docs/documentation/design-systems/importing/figma), or your website to seed components, colors, and tokens. See the [importing overview](/docs/documentation/design-systems/importing/overview). **3. Add your Rules** Define your spacing, visual style, and brand guidelines. This acts as a default prompt for all designs. For those familiar with other AI tools, you can think of this as "default prompts" or "skills" that are applied to the context of all designs. ![](https://cdn.magicpatterns.com/uploads/hRBEYP6dnTaSQGa6pTn8Eu/CleanShot_2026-04-30_at_11.42.252x.png) **4. Set up Typography and Icons** Go to **Typography** to manage font groups (custom fonts, Google Fonts, or font URLs) and **Icons** to pick an icon library or upload your own. ![Typography in Design Systems](https://cdn.magicpatterns.com/uploads/qe3dGXfetVTGPRSKSpP4XG/CleanShot_2026-04-30_at_11.41.492x.png) **5. Define your Colors** Open the Colors page to set up your brand palette with colors like Primary, Secondary, Accent, and more. ![](https://cdn.magicpatterns.com/uploads/s1u2Vn3kY2aKAyjtLyxMgZ/CleanShot_2026-04-30_at_11.42.032x.png) **6. Add Components** Create or import reusable components. The AI will use them automatically when generating designs. > [!TIP] > > You can add or refine many components at once from the same chat. For example: > *"Add a Button, Card, and Modal that all share a 12px border radius."* ![](https://cdn.magicpatterns.com/uploads/rUwMAYMxidhESmkVdmp2X2/CleanShot_2026-04-30_at_11.41.422x.png) ## Editing your Design System Once your Design System is set up, you keep evolving it from one place: a single chat that lives with the Design System. The chat is available on every tab (Components, Typography, Colors, etc.) and operates on the **whole** Design System. You can edit one component, several at once, or make universal updates like changing a color token or tightening the spacing scale system-wide. Versioning and publishing also happen at the Design System level. > **[Editing components and your Design System](/docs/documentation/design-systems/editing/components)** > > Learn how to chat with your Design System to add, edit, version, and publish > components. ## How to Use It When creating a new design, select your Design System from the dropdown. The AI will automatically: * Apply your Rules * Use your color tokens from the Colors page * Use your Typography font groups and icons * Use components from your Design System when appropriate ![](https://cdn.magicpatterns.com/uploads/gEGikpBACanWPwk24wyagV/CleanShot_2026-04-30_at_12.47.16.png) > [!TIP] > > You don't have to pick it every time. The dropdown remembers your last-used > Design System and pre-selects it on every new design. Once you create a design > with a Design System other than Base, that one becomes your default and is > applied automatically on the next new design (and the one after that). You can also reference specific components with `@`: ``` Create a pricing page using @PricingCard and @CTAButton ``` ## Controlling Access 1. Open your Design System 2. Click **Access & Settings** in the left sidebar 3. In the **Access & Permissions** section, enter one or more emails (comma-separated) and click **Invite** By default, anyone in your workspace can access the Design System with **Can write** permissions. You can adjust each teammate's role from the **Who has access** list. Teammates can then use the Design System, browse components, and add new ones (based on permissions). ![](https://cdn.magicpatterns.com/uploads/k4m68vrxiEvio4XUUgVdbr/CleanShot_2026-04-30_at_11.42.352x.png) ## Learn More > **[Importing your Design System](/docs/documentation/design-systems/importing/overview)** > > Bring an existing design system in from GitHub, NPM, Figma, or your website. > **[Colors](/docs/documentation/design-systems/editing/colors)** > > Visually manage your brand color tokens with dark mode and references. > **[Rules](/docs/documentation/design-systems/editing/rules)** > > Write effective styling rules with examples and naming tips. > **[Using Components](/docs/documentation/design-systems/editing/components)** > > Create, edit, and manage components in your Design System. > **[Converting Design Systems](/docs/documentation/design-systems/using/converting-design-systems)** > > Switch a design from one Design System to another. > **[Typography and Icons](/docs/documentation/design-systems/editing/typography-and-icons)** > > Manage font groups and icons in your Design System. ## Video Guide This topic is covered in our video lesson [Design Systems](/docs/documentation/guide/design-systems). [Design Systems](https://www.youtube.com/embed/obZRvV-w_WQ?si=GBDXni7qZ6rnBZOu) # Converting Design Systems Source: https://www.magicpatterns.com/docs/documentation/design-systems/using/converting-design-systems Switch a design from one Design System to another ## Overview Converting Design Systems allows you to take any existing design and convert it to use a different [Design System](/docs/documentation/design-systems/overview). The AI attempts to rewrite your code to match the new Design System's styling and components while keeping the same views and functionality. ## When to Convert This feature is helpful when you want to: * Switch [Design Systems](/docs/documentation/design-systems/overview): move a design from one Design System to another * Apply a new brand: update an existing design to match a newly created [Design System](/docs/documentation/design-systems/overview) * Explore variations: see how your design looks with different styling rules * Standardize old designs: bring legacy designs up to date with your current [Design System](/docs/documentation/design-systems/overview) ## How to Convert ![](https://cdn.magicpatterns.com/static/docs/convert.gif) **1. Open the design you want to convert** Navigate to the design you want to change the Design System for in the editor. **2. Click Convert in the dropdown** Click the **Convert** button in the top bar of the editor. This opens the [Design System](/docs/documentation/design-systems/overview) conversion dialog. **3. Choose your target Design System** Select the [Design System](/docs/documentation/design-systems/overview) you want to convert to from the dropdown menu. **4. Review the conversion** A new design will be generated in a separate tab with your design migrated to the new [Design System](/docs/documentation/design-systems/overview). The original design remains unchanged. # Detaching Components Source: https://www.magicpatterns.com/docs/documentation/design-systems/using/detaching-components Detach components from your Design System to create one-off customizations ## Detach Components Tutorial > [!NOTE] > > Use the "detach components" option sparingly when you need one-off > customizations that do not need to sync with the main design system. [How to detach](https://www.youtube.com/embed/pIqxaHmNiaA?si=5TXG_O3OSd93Ye3V\&start=245) While we recommend editing components directly to keep your design system consistent, there may be cases where you want more flexibility. For those situations, you can enable a preference to automatically detach components when adding them from a library. This setting can be found under Settings > [Preferences](https://www.magicpatterns.com/settings#preferences) > Automatically Detach Components. Detaching gives you a raw instance of the component, allowing the AI to modify specific parts. However, it also breaks the link to the original component, so updates to the library version will not carry over. Think of your components as the "lego bricks" of your app. You might use detach when: 1. You want the AI to edit the component directly 2. You are ok with the component not syncing with the main design system 3. You need to link screens together in the canvas (components are not currently supported in prototyping mode) In most instances, you likely might be better off editing the instance of the component directly. ![](https://cdn.magicpatterns.com/uploads/cHKwWPTSREGFZUcMKAKGSW/CleanShot_2026-04-30_at_13.15.29.png) # Controls Source: https://www.magicpatterns.com/docs/documentation/editor/controls Compare design variants and tune meaningful options directly in Preview. Controls let you compare intentional design variants and tune meaningful details without asking the agent to regenerate the design after every change.