> ## Documentation Index
> Fetch the complete documentation index at: https://canvas-docs.vibeflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Design systems

> Lock palette, typography, and components as rules. Every frame inherits them.

A design system in VibeFlow is a **hard contract**, not a suggestion. When you attach one to a canvas, the agent treats your tokens, components, and guidelines as rules. Brand drift becomes a generator bug, not a human error.

## What's in one

| Layer          | What it locks                                                                              |
| -------------- | ------------------------------------------------------------------------------------------ |
| **Tokens**     | Colors (named roles, not just hex), typography scale, spacing scale, radius, shadows.      |
| **Components** | Real JSX or HTML snippets. Buttons, cards, navs, forms. Each one has when-to-use guidance. |
| **Assets**     | Logo files, badge marks, pattern fills, hero photography.                                  |
| **Guidance**   | Markdown rules: voice, layout principles, what to never do.                                |

Internally it compiles to a `SKILL.md` plus a folder of references, which is what the canvas agent reads on each turn.

***

## Where it lives in the canvas

### Pinning to a canvas

In the chat composer footer:

* **Palette icon** opens the style preset picker (visual aesthetic).
* **Layers icon** opens the design system picker (your saved systems for this organization).

Pick one. It writes to the canvas (`canvas.designSystemIds`, `canvas.selectedStyle`) and stays pinned. Every future generation in this canvas reads it.

You can swap or remove the design system at any time. Existing frames don't change. Future generations follow the new contract.

### Using it on a single message

Sometimes you want a one-off variation without unpinning the brand. Two ways:

* **Prompt override.** *"For this frame only, swap primary to teal. Keep typography and spacing locked."*
* **Style preset.** Add an aesthetic style on top. The agent treats the design system as the brand and the style as the mood.

***

## Building a design system

You don't build design systems on the canvas. They live in their own product at [`/design-systems`](https://ui.vibeflow.ai/design-systems). Three ways to make one:

<CardGroup cols={3}>
  <Card title="From a URL" icon="link">
    Paste any public website. The agent extracts palette, typography, spacing, components, and logo into a fresh system.
  </Card>

  <Card title="From a brief" icon="message-pen">
    Describe the brand in chat. The agent generates a starting system you can refine.
  </Card>

  <Card title="From your codebase" icon="code">
    Use the MCP from your editor. The agent reads your real components and tokens. See the [MCP overview](/mcp/overview).
  </Card>
</CardGroup>

You can also ask the canvas agent to extract a design system on the fly:

*"Clone [yourwebsite.com](https://yourwebsite.com) as a design system and attach it to this canvas."*

This runs the `clone_website` tool in **design-system** mode (2 credits), saves the new system, and auto-attaches it.

***

## How the contract is enforced

When the agent generates a frame, the design system shapes the output at three places:

1. **System prompt.** Every turn includes the compiled `SKILL.md` and a summary of components.
2. **Validation.** The agent is told to use only tokens defined in the system. Frames that drift get flagged in chat.
3. **Asset resolution.** Asset references (logos, hero photos) resolve to your real files via `get_assets`.

In practice this means: ask for *"a hero with our brand color"* and the agent uses the exact hex. Ask for *"our button"* and you get your `PrimaryButton`, not a guess.

***

## Skills on top of a design system

A design system is the brand. **Skills** are the playbook. You can stack both.

| Layer         | Example                                                                  |
| ------------- | ------------------------------------------------------------------------ |
| Design system | Acme tokens, components, logo                                            |
| Skill         | "Deck composition for product launches" or "Editorial photography rules" |

Skills come from two places:

* Your account's enabled custom skills (uploaded `SKILL.md` zips).
* Skills compiled out of the design system itself.

The agent reads both on every turn. To see what's loaded for a canvas, ask: *"What skills do you have access to right now?"* The agent will run `get_skills` and list them.

***

## Best practices

<AccordionGroup>
  <Accordion title="Start with tokens, add components later">
    A design system with a clean color and type scale will beat a system with 40 components and vague tokens. Tokens are what the agent locks hardest.
  </Accordion>

  <Accordion title="Name colors by role, not by hex">
    *"`brand.primary` is `#0F1413`. Use for CTAs and headings on light surfaces."* The agent learns the rule, not just the value.
  </Accordion>

  <Accordion title="Document the components people forget">
    Your nav. Your footer. Your empty state. Your loading skeleton. The agent will compose layouts from whatever is documented.
  </Accordion>

  <Accordion title="One system per brand, not per surface">
    Don't make a "social system" and a "deck system". Make one *Acme Brand* and let the agent compose for any surface from a single source of truth.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Inline edit" icon="hand-pointer" href="/concepts/inline-edit">
    Edit single elements without breaking the rest of the frame.
  </Card>

  <Card title="MCP tools" icon="plug" href="/mcp/tools">
    Manage design systems and frames from your editor.
  </Card>
</CardGroup>