# Wonder Documentation > The full Wonder documentation, every page concatenated as plain text for AI agents. The human-readable version lives at https://wonder.design/docs. # What is Wonder > Wonder is a canvas where you ideate with AI to get to something you actually love. Bring in existing designs from Figma or code, create variations, play with layouts, and wonder! The best part? What you design is code, so what you see is exactly what gets shipped. Source: https://wonder.design/docs/what-is-wonder ## What can you do with Wonder? Instead of handing off static mockups or prototyping in isolation, your canvas reads and writes the same components, tokens, and source your product is built from. Change something in one place and it carries over to the other, with no duplication and nothing to keep in sync by hand. Open the canvas, type your first prompt, and see where it takes you. Over the next few guides we'll go deeper on each of these, one at a time, so you're not trying to learn everything at once. ## Start with the basics - [Design is code](/docs/design-is-code): the idea behind the canvas, where your designs are real, shippable code. - [Designing with AI](/docs/ideate-on-the-canvas): prompt Wonder to generate, explore, and refine designs on the canvas. ## Bring your work in - [From Figma](/docs/bring-your-designs): paste Figma frames straight onto the canvas as editable layers. - [From your codebase](/docs/from-your-codebase): design with your real components, tokens, and icons. ## Work with your design system - [Variables](/docs/variables): manage color, typography, and spacing tokens, synced with code. - [Icons](/docs/icons): add and reuse icons from your file's library. ## Create graphics and effects - [Vectors](/docs/generate-vectors): generate SVGs from the chat, powered by Quiver. - [Shaders](/docs/shaders): add animated backgrounds and effects. ## Connect your code - [GitHub](/docs/github): connect a repository as your source of truth and open pull requests. - [MCP](/docs/mcp): connect your coding agent to read and write the canvas. --- # Design is code > Code is just a material that allows you to create something. Source: https://wonder.design/docs/design-is-code For years, design and code have lived apart. A design gets handed off, re-implemented in code, and from the first change onward the two drift, leaving designers to maintain a second version of a product they can't actually touch. We're closing that gap. In Wonder you work directly with the medium you're designing for: no handoff, and no being pushed off the canvas you love into a terminal or some other developer environment. The canvas is built on real code, so everything you design is ready to ship. ## One source of truth The real source of truth is the product itself: the live, user-facing interface your code ships. Your codebase always holds the latest and greatest version of it, yet for a long time that surface was uneditable for designers. AI is changing that. Designers increasingly have the power to shape the real interface directly, without the handoff. But working in code usually means leaving the canvas behind. Wonder brings your codebase to the canvas instead: you work with the actual components, tokens, icons, and screens from your repository, and Wonder reads from GitHub directly, so there's no second tool to keep in sync. ## It works both ways The connection runs in both directions: | Direction | What happens | | --- | --- | | **Pull** | Bring code onto the canvas, so your designs reflect what's actually built. | | **Push** | Send approved canvas changes back to your repository as a pull request. | ## Why it matters We believe designers should be the advocates for users across the whole product-building lifecycle, and that means shaping the user-facing interface exactly as it ships, not a mockup of it. Wonder closes gaps designers and developers have lived with for years: - **No drift**: one source of truth, not two sides of the same coin to keep reconciled. - **Real building blocks**: you design with your actual components and tokens, right on the canvas. - **Faster to ship**: what you sign off on the canvas is what ends up in the product. ## Where this shows up You'll see this idea throughout Wonder: - [Variables](/docs/variables) stay in sync with the values in your codebase. - [From your codebase](/docs/from-your-codebase) brings your real components, tokens, and icons onto the canvas. - [GitHub](/docs/github) connects a repository as the source of truth. - [MCP](/docs/mcp) lets your coding agent read and write the canvas. --- # Designing with AI > Prompt Wonder to generate, explore, and refine designs directly on the canvas. Source: https://wonder.design/docs/ideate-on-the-canvas Designing with AI does not mean writing something in a prompt box and hoping it does your job end to end. We define designing with AI as sparring between you and your AI sparring partner. Working with AI on a canvas should help you delegate busywork to the agent and focus on the real, deep work yourself. AI can also help you ideate, find different perspectives, and widen your exploration. To get the most out of collaborating with AI, communicating intent and the right context is key. ## Write a good prompt The more context you give Wonder about the surface, the intent, and any constraints, the better it can collaborate with you. A good prompt usually covers: - **Surface**: what you're designing, such as a mobile onboarding flow, a settings page, or a pricing table. - **Intent**: the goal, such as increasing readability and reducing the complexity of your pricing table. - **Constraints**: anything fixed, such as existing components or legal requirements. You can also point Wonder at things that are already on the canvas. Drop in a reference image or select an existing frame. ### Be specific The more specific you are, the better the outcome, so include your design preferences and technical requirements too. Instead of `Create a mobile home screen`, try something more specific: ```text Create a mobile screen for my simple to-do list app. It should show the tasks due today, tomorrow, and this week, plus a small input field to quickly add tasks. Use monochrome colors and sharp edges. ``` ## Explore with AI You can ask Wonder to explore several variations of one design side by side, so you can weigh them against each other and pick a direction to pursue: - **Variations**: `Give me three style directions for this screen.` - **Perspectives**: `Show me a few different layout options for this hero section.` Keep the direction that works best and refine it, or combine the strongest ideas from several into one. ## Refine Once you have a direction you like, you can nudge it using Wonder until it feels right: - **Style**: `Increase the spacing and soften the shadows.` - **Structure**: `Move the CTA above the fold.` - **Cleanup**: `Align these cards and make them equal height.` Everything Wonder generates stays fully editable, so you can always jump in and tweak designs by hand. --- # Variables & Themes > Define, import, and manage design tokens for color, typography, and spacing, kept in sync with code. Source: https://wonder.design/docs/variables Variables (also known as Tokens or CSS Variables) are named values for things like colors, spacing, typography, and much more. You can use them in Wonder to keep your codebase and Wonder file in sync. You can either import variables directly from your codebase or create new variables in Wonder via chat or manually. You can manage variables in the **Variables** sidebar panel. ## Token types Currently we support the following types of variables: - colors - spacing - gap - radius - width & height - opacity - typography - font family - font size - font weight - letter spacing - line height We're working hard to add support for more properties and additional features such as grouped variables (e.g. classes) for typography and shadows. ## Add / Create variables in Wonder To use variables in Wonder, you can either import them from your codebase, ask Wonder AI to create them for you, or create them manually by hand. ### From your codebase 1. Connect your Wonder file to your codebase via the [GitHub integration](/docs/github) 2. Ask Wonder AI to import the variables from your codebase 3. Enable the variables panel in the sidebar ### Ask Wonder to generate variables 1. Open the chat panel 2. Ask Wonder AI to generate variables based on your context 3. Enable the variables panel in the sidebar ### Create manually 1. Open the variables panel in the sidebar 2. Click on the little "+" in the top right corner 3. Select your variable type 4. Give it the correct name 5. Change the value 6. Optional: with a right-click on the value, you can reference another variable. ## Variable naming You can organize variables in folders by changing the name to `neutral/500`. This will create a `neutral` folder and nest the 500 variable inside it. The raw value of that variable when exported will stay `neutral-500`. So it is just a visual organizing tool for you and your team. ## Use a variable You can assign variables to the supported properties via the visual reference for variables "". By clicking this icon, a dropdown will appear which lets you search for your desired variable. When attached, the property's input field visually shows you that a variable is attached. To detach a variable, click the little detach icon which appears when hovering over a field with an attached variable "". You can also ask Wonder AI or your agent of choice via MCP to apply tokens to a design, just ask for it in the chat or terminal.
Synced with code

When a repo is connected, variable values track the source: edit them in code or on the canvas and both stay aligned. When you update something, you can also open a PR to update the variables in the codebase. To learn more, see create a pull request.

--- # Icons > Add, manage, and reuse icons in your Wonder files. Source: https://wonder.design/docs/icons Every Wonder file has its own icon library, which lives in the **Icons** panel in the sidebar. Icons are vectors, so they stay crisp at any size, and you can recolor them to match your design. ## Add an icon to your library You can build up your library in two ways. ### From your codebase When you connect a repository, Wonder can import the icon set your product already uses: 1. Connect your Wonder file to your codebase via the [GitHub integration](/docs/github). 2. Ask Wonder AI to import your icons. 3. Find them in the **Icons** panel, ready to use. ### Add your own You can also turn any SVG element into an icon: 1. Add an SVG to the canvas via drag and drop, or [generate an SVG using Quiver AI](/docs/generate-vectors) 2. Select the element or frame on the canvas. 3. In the properties panel, find the **Icon** section and click **Add to library**. 4. It becomes a reusable icon you can use anywhere in the file. ## Use an icon You can either select an SVG from the sidebar panel, or replace it by **selecting** an element and clicking on "Link Icon". Once an icon is placed, you can: - **Recolor it** from the **Colors** section of the properties panel. Icons also support [variable](/docs/variables) colors. - **Resize it** freely: it's a vector, so nothing gets blurry at any size. --- # Generate Vectors > Generate scalable vector graphics from the Wonder AI chat, powered by Quiver. Source: https://wonder.design/docs/generate-vectors You can generate vector graphics (SVGs) directly from the Wonder AI chat. Under the hood, Wonder uses [Quiver](https://quiver.ai/), a model built specifically for generating SVGs. ## Generate a vector Open the Wonder AI chat and describe what you want: ```text Create a SVG wordmark reading “Wonder” in a bold, fluid, hand-lettered brush script similar to a vintage signature logo. Use smooth connected letterforms, rounded strokes, a slightly forward-leaning rhythm and a long sweeping underline extending from the final letters. ``` Wonder generates the vector on the canvas as an SVG. ## Adjust the colors You can recolor a generated vector, and bind its colors to your [variables](/docs/variables) so it stays in sync with your theme. ## Download You can download any generated vector as a clean SVG, ready to drop into your codebase or use anywhere else.
Editing is on the way

You can already recolor a vector, but reshaping its points and curves isn't supported on the canvas yet: that's on our roadmap. For now, refine the shape by prompting again, then download it.

--- # Shaders > Add rich, animated backgrounds and effects from Wonder's shader library Source: https://wonder.design/docs/shaders ## Add a shader to your design You can add a shader in two ways: - **From the toolbar**: pick a shader and drop it onto the canvas. - **As a background fill**: select a frame, then add a shader as its background fill from the properties panel on the right. ## Shader presets The Free plan includes 100 curated presets. Pro and Enterprise plans include access to 1000+ presets. You can browse the library by type: - **Background shaders**: animated gradients and surfaces for full-bleed backgrounds. - **Image shaders**: effects that run over an image. - **SVG shaders**: generative, vector-based surfaces. ## Customization Once a shader is applied, you can tune it to fit your design. You can change the colors or other values depending on the shader type. To open more advanced customization, click the little preferences icon in the sidebar panel. ## Exporting shaders When exporting or developing a design which contains a shader, the shader is fully functional and loaded via the `shaders/react` package by [shaders.com](https://shaders.com). To learn more about the package, please read the documentation [here](https://shaders.com/docs/guide). ```typescript import { FilmGrain, FlowingGradient, Grid, Shader } from 'shaders/react' function ShaderEffect() { return ( ) } ``` ## Limitations Shaders are not yet supported by the Wonder AI chat. Also, we currently do not support variable-driven shaders. We are working on shipping this implementation soon.
Performance

Shaders are GPU-heavy. Using a lot of shaders on one canvas can cause FPS drops.

--- # From Figma > Paste existing Figma frames straight as editable layers onto the Wonder canvas Source: https://wonder.design/docs/bring-your-designs Designers' work lives in many places. In Wonder, you can bring your designs from different sources including Figma, just copy any selection from a Figma file and paste it onto the canvas, where it renders as editable layers. ## Copy & paste a Figma selection To import your work from Figma into Wonder: 1. Open the Figma file you want to import from. 2. Select the frames you want to bring into Wonder. 3. Copy the selection to your clipboard (`cmd + c`, or right-click and choose **Copy**). 4. Open your Wonder file and paste the selection (`cmd + v`, or right-click and choose **Paste**). ## Variables Wonder can import designs that have Figma variables attached. If your Wonder file already has a variable with the same name, Wonder matches them automatically during the import. For example, if a frame in Figma uses `--neutral-50` for its background and your Wonder file has a variable of the same name, that connection stays intact through the import rather than breaking. ## Limitations and gotchas The Wonder canvas is built on real code and CSS (see [Design is code](/docs/design-is-code)). Because of that, some Figma features that CSS can't reproduce in the browser aren't supported, or are translated to the closest equivalent. Here's what to watch for. ### Importing images Importing images from Figma isn't supported yet. If your selection contains images, they won't come across, they'll appear as empty image frames instead. To complete the design, export the images from Figma and add them to your design in Wonder. ### Components Figma components and their instances are detached when you paste them into Wonder. ### Borders Some border features aren't supported by CSS, so they're translated on import: - **Multiple stacked colors**: the first color is preserved here. - **Custom border styles**: translated to a dashed border. - **Gradient border strokes**: are not preserved in Wonder. ### Effects Drop shadows, layer blurs, and background blurs translate correctly. Inner shadows translate too, with one edge case: because Figma handles them differently from CSS, a translated inner shadow is applied to each child element rather than the parent. (In Figma, an inner shadow on a fill-less parent shows on its children but is assigned to the parent.) These effects aren't supported and won't be preserved: - Textures - Glass - Noise ### Layout Grid layouts aren't supported yet, so they're translated to a flex layout while preserving the design intent. ### Text Multiple text formats (rich text) within a single text box aren't supported yet (Example: different font sizes or weights in one text box). ## Other ways to bring your work in - [From your codebase](/docs/from-your-codebase): connect a repository for your real components, tokens, and icons. --- # From the browser > Capture any webpage with Wonder Capture and paste it onto the canvas as editable layers. Source: https://wonder.design/docs/wonder-capture With **Wonder Capture**, a Chrome extension, you can grab any webpage, or just parts of it, and paste it onto the canvas as fully editable layers. ## Install Wonder Capture 1. Add [Wonder Capture](https://chromewebstore.google.com/detail/wonder-capture/dhapfpkbeokfngalhbijopidpadjdppk) from the Chrome Web Store. 2. Optional: pin it to your toolbar for one-click access. ## Capture from the web 1. Open the page you want to capture and start **Wonder Capture** from the toolbar. 2. Capture the whole page, or select just the part you want. 3. The capture is copied to your clipboard. 4. Open your Wonder file and paste it (`cmd + v`), and it lands on the canvas as editable layers. --- # From your codebase > Connect a GitHub repository to design with your real components, tokens, icons, and views. Source: https://wonder.design/docs/from-your-codebase Connect a GitHub repository and your codebase becomes something you can design with. Wonder reads your real components, tokens, icons, and views and brings them onto the canvas. ## Bring designs onto the canvas 1. Open a Wonder file. 2. Connect your GitHub repository. 3. Ask Wonder AI to bring the screen or design you want onto the canvas.
The first prompt can take a little longer

When you first connect a repository, Wonder imports your variables, so it has the context to produce accurate results. Because of that, your first prompt after connecting can take slightly longer and consume more tokens.

Besides connecting a GitHub repository via the Wonder app, you can also use the Wonder MCP to connect to your codebase. Read more about both approaches below:
GitHub Connect a repository as your source of truth and export pull requests. MCP Connect your coding agent to read and write the canvas.
--- # Get started with Wonder MCP > Connect Wonder to your coding agent over MCP so design changes and code changes stay in sync. Source: https://wonder.design/docs/mcp Design and code have always lived in separate worlds. Wonder changes that. The Wonder MCP server gives your AI coding agent direct read and write access to your Wonder canvas, so you can pull designs into code or push code back into designs.
Before you start

You need a Wonder account with at least one file. The MCP server is free on every plan, including the free tier.

# What is Wonder MCP? Wonder's MCP server plugs into coding agents (Claude, Cursor, and others) so that designs created in Wonder can be read, edited, and updated by your agent, and vice versa. # How it works Wonder connects to your agent through the Wonder MCP server at `https://mcp.wonder.so/mcp`. On first use you'll sign in through a standard OAuth flow. There are no API keys to manage, and tokens refresh automatically. For Cursor, install Wonder from Cursor's plugin marketplace. Claude Code and Codex support the Wonder plugin directly. # Install Pick your agent below. We currently support Cursor, Claude Code, Claude Desktop, Claude custom connectors, Codex, Antigravity, Lovable, and custom MCP clients. ## Cursor Open Customize 1. Click **Browse Marketplace**. 2. Search for **Wonder** and open the result. 3. Click **Add**. 4. Click **Manage**. Wonder should now appear under **MCP**. 5. Click **Authenticate** and complete the browser sign-in. ## Claude Code **Plugin (recommended)** Open your terminal and run `claude` to start Claude Code. Add the marketplace: ``` /plugin marketplace add aquila-lab/wonder-plugins ``` Install the plugin: ``` /plugin install wonder@wonder ```
Claude Code showing the Wonder plugin available to install
Reload to activate it: ``` /reload-plugins ``` To check if it worked, run `/plugin` and confirm that Wonder appears under **installed**.
Claude Code showing the Wonder plugin under Installed
Open the Wonder app and any canvas file you want generations drawn to. Then, back in Claude Code, type a prompt like: ``` Generate a purple button in Wonder ``` On first use, Claude will say the Wonder MCP needs authentication and print a URL. Open that link in your browser to authorize, then come back to Claude Code and re-send the same prompt. Watch it draw onto your canvas in real time. **Manual setup** 1. Open the terminal on your computer. 2. Run the command below (not inside Claude) to register the Wonder MCP server: ```bash claude mcp add --transport http wonder https://mcp.wonder.so/mcp ```
Run the command in your terminal
3. Run `claude mcp list` to confirm the Wonder server appears.
Confirm the Wonder server appears
4. Open a Claude Code session and run `/mcp`. You should see Wonder in the list of MCPs. If you don't, restart your Claude session. Wonder will prompt you to sign in to your account in the browser. Once done, your agent is connected. Tokens refresh automatically, so you should only need to do this once.
Wonder appears in the /mcp list
New to the terminal?

If you have trouble setting up Claude Code, watch this tutorial or ask any AI agent to walk you through it.

## Claude Desktop **Plugin (recommended)** 1. Open your Claude Desktop app and navigate to the **Code** tab in the top-left corner. 2. Click on **Customize**. 3. Click the plus icon under **Personal Plugins** > **Create Plugin** > **Add Marketplace**. 4. Enter the Wonder plugin URL in the field: `aquila-lab/wonder-plugins`. 5. Click **Sync** and add the Wonder plugin that appears to Claude.
Add Marketplace in Claude Desktop
Wonder plugin installed in Claude Desktop
You should now see Wonder in your MCP list when you start a `claude` session in your terminal and run `/mcp`. **Manual setup** Claude Desktop requires Node.js to run MCP servers. Verify by running `node --version` in your terminal. Open **Claude Desktop Settings > Developer > Edit Config**. This opens your `claude_desktop_config.json` file. Your file probably looks something like this: ```json { "preferences": { "coworkWebSearchEnabled": true, "ccdScheduledTasksEnabled": true, "sidebarMode": "chat" } } ``` Add the Wonder MCP section so it looks like this: ```json { "mcpServers": { "wonder": { "command": "npx", "args": [ "mcp-remote", "https://mcp.wonder.so/mcp" ] } }, "preferences": { "coworkWebSearchEnabled": true, "ccdScheduledTasksEnabled": true, "sidebarMode": "chat" } } ``` Save the file. Make sure there's a comma after the closing `}` of `mcpServers`. Fully quit and restart Claude Desktop. A browser window will open asking *"MCP CLI Proxy would like access to your account."* Click **Allow access**. Once the browser confirms "Authorization successful!", close it and return to Claude. Check the chat input area for the MCP indicator to verify Wonder is connected. ## Claude (custom connector) If you use the Claude desktop app or claude.ai in the browser and don't want to touch the terminal or config files, add Wonder as a custom connector. This is the simplest way to connect Claude to your canvas. There are two parts. An admin adds Wonder as a connector once, then each person connects their own Wonder account. On a personal Pro or Max plan you're the admin, so do both. **Add Wonder (admins)** 1. Open Claude (the desktop app or [claude.ai](https://claude.ai)). 2. Go to **Settings > Connectors**. 3. Click **Add**, choose **Custom**, then **Web**. In some versions this reads **Add custom connector**.
Add a custom connector from the Connectors settings
4. Enter the following details: - **Name:** `Wonder` - **Remote MCP server URL:** `https://mcp.wonder.so/mcp` 5. Claude auto-detects Wonder's authentication settings. Keep the detected defaults: - **Authentication:** **Always required** - **OAuth client:** **Use Anthropic's hosted client metadata** (Recommended)
Keep the detected authentication defaults
6. Scroll down and click **Add** to make Wonder available. Adding the connector doesn't give Wonder access to every member or file. Each person connects their own Wonder account and only sees files their existing Wonder permissions allow.
Who can do this

On Team and Enterprise, only a Claude organization Owner or Primary Owner can add a custom connector. If you don't see the option, you likely aren't an Owner or your organization has restricted custom connectors: send your admin this guide.

**Connect your account (everyone)** 1. In Claude, open **Customize > Connectors**. 2. Find **Wonder** in the list (it may have a **Custom** label) and click **Connect**. 3. Sign in to Wonder and approve the connection. 4. Open the **Wonder** connector settings. Under **Tool permissions**, set both groups to **Always allow**: - **Read-only tools:** Always allow - **Write/delete tools:** Always allow
Set both tool groups to Always allow
Why Always allow

This lets Claude work without asking before every Wonder tool call. Claude can still only reach files your Wonder account permits.

5. Open the Wonder web or desktop app and keep the canvas file you want to use open. 6. In a Claude conversation, open **+ > Connectors** and enable Wonder if it isn't already. ## Codex **Plugin (recommended)** 1. Open Codex. 2. In the prompt box, start typing `/plugin` and select **Plugin Creator** from the command picker.
3. Complete the prompt with the Wonder plugins repo URL and send it: ``` Install the Wonder plugin from https://github.com/aquila-lab/wonder-plugins ``` 4. Type in `@wonder` and select the Wonder plugin from the list.
5. Type a prompt to test the connection: ``` Generate a purple button in Wonder ``` On first use, Codex will say the Wonder MCP needs authentication and show a URL. Open it in your browser to authorize, then come back to Codex and re-send the same prompt. Watch it draw onto your canvas in real time.
**Manual setup** Run the command below in your terminal to register the Wonder MCP server: ```bash codex mcp add wonder --url https://mcp.wonder.so/mcp ``` You can also configure it manually via `config.toml`. Run `codex mcp list` to confirm the Wonder server appears. ## Antigravity In Antigravity, click the **⋯** menu in the Agent panel > **MCP Servers**, then select **Manage MCP Servers** > **View raw config**. This opens your `mcp_config.json` file. The file is located at: - **macOS / Linux:** `~/.gemini/antigravity/mcp_config.json` - **Windows:** `C:\Users\\.gemini\antigravity\mcp_config.json` Add the following configuration. Note that Antigravity uses `serverUrl` instead of `url` for remote MCP servers. ```json { "mcpServers": { "wonder": { "serverUrl": "https://mcp.wonder.so/mcp" } } } ``` Close and reopen Antigravity. Go to **MCP Servers** and confirm Wonder appears with its tools listed. ## Lovable
Paid plan required

Custom MCP servers require a paid Lovable plan.

1. Open Lovable. 2. Navigate to **Settings → Connectors → Personal connectors** via the sidebar. Scroll down to **New MCP server** and click it. You can also click **+** in the prompt box and go to **Connectors** for quick access.
Add Wonder to Lovable with a custom MCP server
3. Enter `Wonder` as the MCP name and paste this URL: ``` https://mcp.wonder.so/mcp ``` 4. Select **No authentication** and click **Add server**. Wonder will appear in your list of personal connectors. You can now reference your Wonder designs directly in prompts. ## Other MCP clients If your client isn't listed above, you can set up Wonder manually. The server URL is: ``` https://mcp.wonder.so/mcp ``` Most MCP clients accept a JSON config like this: ```json { "mcpServers": { "wonder": { "url": "https://mcp.wonder.so/mcp" } } } ``` If your client doesn't support remote URLs natively, use the `mcp-remote` bridge (requires Node.js): ```json { "mcpServers": { "wonder": { "command": "npx", "args": [ "mcp-remote", "https://mcp.wonder.so/mcp" ] } } } ``` # Try it out Once Wonder is connected, open a chat in your agent of choice and try one of these prompts to confirm everything is working. **If you are in an existing codebase:** ``` Read my Tailwind config and create a design in Wonder using my exact colors, typography, and spacing. ``` **If you're starting fresh:** ``` Create a simple landing page hero in Wonder with a headline, subheadline, and a call-to-action button. ``` **To test the round-trip:** ``` Look at my existing app's header component and design a matching hero section in Wonder. ``` Your agent will use the Wonder MCP tools to read and write directly to your canvas. Open Wonder to see the result. # Troubleshooting & FAQ
What does the Wonder MCP server do? The Wonder MCP gives your AI coding agent direct access to your designs, components, and documentation inside Wonder. Instead of screenshotting or describing your designs, your agent can read the actual design data and generate code that matches what you've built on the canvas.
Do I need a Wonder account? Yes. You need an active Wonder account with at least one project. The MCP server connects to your Wonder workspace, so the agent only sees designs you have access to.
Is the MCP server free? Yes, the Wonder MCP server is free to use on all plans, including the free tier.
Does it work with Windsurf, VS Code Copilot, or Cline? Yes. Any MCP-compatible client can connect to Wonder. Use the manual setup instructions above. The JSON config with `"url": "https://mcp.wonder.so/mcp"` works with most clients. For clients that don't support remote URLs directly, use the `mcp-remote` bridge method shown in the **Other MCP clients** section.
The Wonder server isn't showing up, or tools aren't working Try fully quitting and restarting your agent. Most MCP connection issues resolve after a restart.
The MCP server is connected but the agent isn't using it This usually means the agent doesn't know to look at your Wonder designs. Try being explicit in your prompt, for example: *"Use the Wonder MCP to pull my designs and generate the landing page layout."* Most agents discover the available tools automatically, but a nudge helps.
Can the agent modify my designs? Yes. The Wonder MCP server provides both read and write access. Your agent can pull your designs as context and push new designs or updates back to the canvas.
I already added other MCP servers. Will Wonder conflict? No. MCP servers run independently. Add the Wonder config alongside your existing `mcpServers` entries in the same JSON object: ```json { "mcpServers": { "wonder": { "url": "https://mcp.wonder.so/mcp" }, "other-server": { "url": "https://example.com/mcp" } } } ```
Where can I report issues or request features? Head to our [Feature Requests board](https://wonderdesign.featurebase.app/en) or drop a message in our [Discord](https://discord.gg/HHA2sq6XKp).
# Related - [Get started with GitHub](/docs/github): use your repository as the source of truth. --- # Get started with GitHub > Connect a GitHub repository to use your codebase as the source of truth. Pull code onto the canvas, keep it in sync, and turn approved changes into pull requests. Source: https://wonder.design/docs/github
Connect a GitHub repository to a Wonder file to use your codebase as the source of truth for components, tokens, icons, fonts, and views. Wonder can pull code onto the canvas, keep it in sync, and turn approved changes into a pull request. You trigger each of these by prompting Wonder AI in the chat, using prompts like the examples in each section below. ## What you can do | Action | What it does | Access | | --- | --- | --- | | **Import** | Bring components, tokens, icons, and views onto the canvas | Read | | **Sync** | Update imported elements when their source changes | Read | | **Create a PR** | Turn approved canvas changes into a branch and pull request | Write | ## Requirements - **Edit access** to the Wonder file. View-only collaborators can't connect a repository. - The **Wonder GitHub App** installed on the account or organization that owns the repository. Public repositories can be read by URL without it. - For pull requests, the app needs **Contents: Read and write** and **Pull requests: Read and write**. ## Quickstart 1. **Connect:** open your Wonder file, select **GitHub** in the file header, and authorize the repository. 2. **Import:** ask Wonder AI to bring a component, tokens, or a view onto the canvas. 3. **Export:** ask Wonder to turn your approved changes into a pull request. # Connect GitHub Each Wonder file connects to one repository at a time, and the connection is shared with everyone on that file. 1. Open the Wonder file and select **GitHub** in the file header. 2. Select **Continue with GitHub**. 3. Authorize Wonder on GitHub. If the Wonder GitHub App isn't installed on the owning account or organization, install it now. 4. Grant the app access to all repositories or only selected ones. 5. Return to Wonder and select the repository.
Connecting a Wonder file to a GitHub repository.
For a public repository, paste its GitHub URL instead, with no app required. Private repositories and all write actions need the app.
Authorizing vs. installing

GitHub treats these as separate steps: authorization identifies your GitHub user, and installation grants access to repositories. You may be asked to do both.

## Manage the connection - **Switch:** connect the file to a different repository. - **Add repositories** or **Manage on GitHub:** change which repositories the app can access. - **Disconnect:** remove the repository from this file. This doesn't uninstall the app or affect other files. To suspend, uninstall, or change the repository access of the app itself, follow GitHub's guide to managing installed apps.
Switch, disconnect, or manage the connected repository.
# Import code Wonder AI can read the connected repository (its file tree, paths, source, and branches) and bring it onto the canvas. Ask it to: - Import a component and its variants. - Import a component library into a Design Guide. - Import tokens, icons, and other foundations without the full library. - Reproduce a page or view as a Wonder design. - Create a new design from the repository's real components, tokens, fonts, and icons. - Work from a named branch instead of the default.
Get better results

Include a component name, route, source path, or branch when you know it. Large library imports take longer, so Wonder confirms the scope before it starts.

Example prompts: ```markdown - Import the Button and Card components from the connected repository, including their variants. - Import our design tokens and icons into a Design Guide, but not the full component library. - Reproduce the pricing page from the `develop` branch as a Wonder artboard. - Create a checkout page using the components and tokens in the connected repository. ```
Design tokens and icons imported into a Design Guide.
# Sync designs Imported elements remember their source path and commit. When an element still points to its source, you can: - **Open source on GitHub:** jump to the referenced source at the recorded commit. - **Sync with code:** compare the element with the latest source and update the canvas, keeping its place and identity. When GitHub reports a change to a referenced file, Wonder marks the affected element as out of sync. Select it and choose **Sync with code**, or ask the chat. Example prompts: ```md Update this selected card to match the latest source code. ``` ```md Sync this component with `src/components/Navigation.tsx` on `main`. ``` ```md Restyle this section using the latest version of our repository design system. ```
Needs a source reference

Elements created in Wonder, imported without a source, or detached from theirs can't sync automatically. Tell Wonder AI the source path and ask it to compare or re-import.

# Create a pull request You create a pull request by prompting Wonder AI in the chat, for example "turn these changes into a pull request." There's no separate export button. Wonder first reads the current source and shows a plan: the affected artboards, files, edits, branch, and pull request. Nothing is written until you approve it.
Beta feature

Pull request export is in beta and under active development. Review every pull request carefully before merging. Hit a problem? Email support@wonder.so.

After you approve, Wonder will: 1. Create a new branch from the current base-branch head. 2. Edit, add, or delete text source files as required by the change. 3. Commit those changes. 4. Open a draft or regular pull request against the base branch. Wonder-created branches use the `wonder/` prefix and never write to the base branch directly.
Wonder opens a pull request and links it back in the chat.
Example prompts: ```md Export the changes on the Pricing artboard as a pull request against `main`. ``` ```md Turn everything changed since import into a draft pull request titled "Update checkout design". ``` ```md Update the source component to match this selected design, then show me the exact export plan before making changes. ```
Get better results

Start from designs imported from the connected repository. Their source paths give Wonder a precise canvas-to-code mapping, and Wonder flags new elements that have no source destination and asks where they belong.

# Safeguards & privacy GitHub write access is intentionally limited: - The repository must be connected through the Wonder GitHub App. A public repository connected by URL is read-only. - Wonder writes only to a new `wonder/` branch, and only after you approve the export plan. - It edits and creates text source files only, skipping binary files (like images or fonts) and very large files. - Wonder never force-pushes, writes to a base branch, merges pull requests, approves reviews, or changes repository settings, secrets, or Actions workflows. Wonder stores the connection and installation identifiers, and requests short-lived tokens from GitHub only when access is needed. It doesn't persist those tokens. You can change repository access, suspend the installation, or uninstall the app from GitHub settings at any time. Always review the diff and repository checks on GitHub before merging. # Troubleshooting & FAQ
GitHub is missing Make sure you have edit access to the Wonder file. View-only collaborators can't connect, switch, or disconnect a repository. Refresh the file after your access changes.
Connection failed If Wonder shows **"Could not connect GitHub. Please try again."**, restart the flow and finish it within 10 minutes. Keep your Wonder session open and use the same browser and profile throughout. The connection can fail if you let the authorization expire, switch browsers or profiles, sign out of Wonder mid-flow, or decline the GitHub request. If it persists, check GitHub Status and retry later.
Owner approval required Your GitHub organization restricts app installation, so GitHub sent the request to an owner. Wonder can't approve it for you. Ask an owner to approve and install the Wonder GitHub App for the required repositories, then restart the connection. An owner can adjust the requested repositories before approving.
Repository not listed 1. Check the account filter and search for the full `owner/repository` name. 2. In Wonder, select **Add repositories** or **Manage on GitHub**. 3. On GitHub, add the missing repository under the app's **Repository access**. 4. Save, return to Wonder, and refresh the repository picker. For an organization repository, an owner or repository administrator may need to make this change. If nothing appears, confirm you authorized the same GitHub user that can access the installation. Use **Continue with GitHub** so Wonder finds the installations available to you.
Private repository unavailable Private repositories can't be connected by URL. Install the Wonder GitHub App on the owning account or organization, grant it access to the repository, then select it from Wonder. If Wonder says the repository isn't part of the installation, use **Manage on GitHub** to add it.
Public URL rejected Confirm the repository exists and is public. Wonder accepts common formats: - `owner/repository` - `https://github.com/owner/repository` - `git@github.com:owner/repository.git` Remove any typos and confirm the URL points to GitHub. If the repository is private, use the GitHub App flow instead.
Write access unavailable The repository was likely connected as a public URL, or its installation lacks write access. 1. Make sure the repository is connected through the Wonder GitHub App. 2. Ask the owner of the installation to confirm it's active and includes the repository. 3. Confirm the installation grants **Contents: Read and write** and **Pull requests: Read and write**. 4. Return to Wonder and retry the export.
Sync unavailable Check that the element was imported from the currently connected repository, still has a source path and commit, that you can edit the file and use AI chat, and that the source file still exists. If the source was deleted or the element has no attribution, ask Wonder AI to locate the replacement source and re-import.
Export failed Use the message from Wonder to choose the recovery: | Message or symptom | What to do | | --- | --- | | The branch already exists | Choose a different branch name and retry. | | The branch changed while committing | Ask Wonder to re-read the affected files and regenerate the plan. | | The source snippet was not found or was not unique | Ask Wonder to re-read the file and make the edit more specific. | | There are no file changes | The repository already has the proposed content; a PR may not be needed. | | There are no commits between the branches | Commit an approved change before opening the PR. | | GitHub rate limit or temporary error | Wait and retry. Reconnecting usually won't clear a rate limit. |
Still stuck? When contacting support, include the Wonder file URL, the `owner/repository` name and branch, whether the repo is personal or organization-owned and public or private, the exact error and when it happened, and the action you attempted. Don't send access tokens, authorization codes, cookies, keys, or repository secrets.
# Related - [Get started with Wonder MCP](/docs/mcp): connect Wonder to your coding agent.