# preset AI Documentation

> Documentation for preset AI, the design system memory layer for AI coding tools.

Full documentation corpus : 46 pages. Each section below is a single page delimited by its URL header, with a structured metadata block preceding the body.

---

# preset AI · Documentation

Source: https://presetai.dev/docs/
Summary: Pick a path: scan a repo, set up enforcement, plug an AI tool in, or read about the memory layer.
Last updated: 2026-05-11
Related: Why the memory layer matters (https://presetai.dev/docs/memory-layer), Scan your repo (https://presetai.dev/docs/scan), Set up enforcement (https://presetai.dev/docs/enforce), Agent resources (https://presetai.dev/docs/agent-resources)

---
owner: jschuyler
updated: '2026-05-11'
status: stable
---

export const metadata = {
  title: 'preset AI · Documentation',
  description: 'Make AI fluent in your design system. The memory layer that teaches AI coding tools to follow your tokens, components, and patterns.',
  summary: 'Pick a path: scan a repo, set up enforcement, plug an AI tool in, or read about the memory layer.',
  last_updated: '2026-05-11',
  related: ['/memory-layer', '/scan', '/enforce', '/agent-resources'],
}

export const sections = [
  { title: 'Choose where to start', id: 'choose-where-to-start' },
  { title: 'Recipes', id: 'recipes' },
]

<div className="not-prose">

<div className="grid grid-cols-1 lg:grid-cols-[1fr_28rem] gap-12 items-start">

<div>

<div className="text-[12px] text-muted-foreground mb-4">Documentation</div>

<h1 className="text-[32px] sm:text-[42px] leading-[1.05] font-semibold tracking-tight text-foreground mb-5 text-balance">
  Make AI fluent in <span className="text-muted-foreground">your design system.</span>
</h1>

<p className="text-[17px] leading-[1.55] text-muted-foreground max-w-[44ch] mb-8 text-pretty">
  The memory layer that teaches AI coding tools to follow your tokens, components, and patterns. Start with the Quickstart, or pick a path below that matches what you're trying to do.
</p>

<div className="flex flex-wrap items-center gap-2.5">
  <a href="/docs/scan" className="inline-flex items-center gap-1.5 h-9 px-4 rounded-[2px] bg-foreground text-background text-[14px] font-medium hover:opacity-90 transition-opacity">
    Quickstart
    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.75"><path d="M2.5 6H9.5M9.5 6L6.5 3M9.5 6L6.5 9"/></svg>
  </a>
  <a href="/docs/agent-resources" className="inline-flex items-center gap-1.5 h-9 px-4 rounded-[2px] border border-border text-[14px] font-medium hover:border-muted-foreground/50 transition-colors">
    Agent resources
  </a>
  <a href="https://github.com/fndd-LLC/preset" className="inline-flex items-center gap-1.5 h-9 px-3 text-[14px] text-muted-foreground hover:text-foreground transition-colors">
    View on GitHub
    <svg width="11" height="11" viewBox="0 0 11 11" fill="none" stroke="currentColor" strokeWidth="1.5"><path d="M3 8L8 3M8 3H4M8 3V7"/></svg>
  </a>
</div>

</div>

<div className="rounded-[2px] border border-border bg-muted/40 overflow-hidden">
  <div className="flex items-center justify-between border-b border-border px-2 py-2 bg-background">
    <div className="flex items-center gap-1 text-[12px]">
      <span className="px-2.5 py-1 rounded-[2px] bg-muted text-foreground font-medium">llms.txt</span>
      <a href="/docs/llms-full.txt" className="px-2.5 py-1 rounded-[2px] text-muted-foreground hover:bg-muted hover:text-foreground transition-colors focus:outline-none focus-visible:ring-1 focus-visible:ring-foreground/50 focus-visible:ring-offset-1">llms-full.txt</a>
      <a href="/docs/index.md" className="px-2.5 py-1 rounded-[2px] text-muted-foreground hover:bg-muted hover:text-foreground transition-colors focus:outline-none focus-visible:ring-1 focus-visible:ring-foreground/50 focus-visible:ring-offset-1">index.md</a>
    </div>
    <span className="text-[11px] text-muted-foreground font-mono pr-1">read-only</span>
  </div>
  <pre className="px-4 py-3.5 font-mono text-[12.5px] leading-[1.7] text-foreground overflow-x-auto whitespace-pre m-0">{`# preset AI Documentation

> Documentation for preset AI, the
> design system memory layer for AI
> coding tools.

- [What is preset AI](/index.md):
  Overview and core concepts.
- [The memory layer](/memory-layer.md):
  Why longitudinal beats snapshot.
- [Scan your repo](/scan.md):
  Run the scanner; review the output.
- [Set up enforcement](/enforce.md):
  Install MCP; watch the first reject.
- [Agent resources](/agent-resources.md):
  Every surface AI tools can read.`}</pre>
  <div className="border-t border-border px-3 py-2 bg-background flex items-center justify-between text-[11px] text-muted-foreground">
    <span>Live at <span className="font-mono text-foreground">presetai.dev/docs/llms.txt</span></span>
    <a href="/docs/llms.txt" className="hover:text-foreground">Open ↗</a>
  </div>
</div>

</div>

</div>

## Choose where to start

<p className="text-[15px] text-muted-foreground max-w-[60ch] mb-6">Four paths into preset AI. Pick the one that matches what you're trying to do; they connect.</p>

<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-px bg-border rounded-[2px] overflow-hidden border border-border mb-12">

  <a href="/docs/scan" className="group bg-background p-6 hover:bg-muted transition-colors block">
    <div className="flex items-start justify-between mb-2">
      <div className="text-[11px] font-medium text-muted-foreground">Guide · 8 min</div>
      <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" className="text-muted-foreground group-hover:text-foreground group-hover:translate-x-0.5 transition-all"><path d="M3 7H11M11 7L8 4M11 7L8 10"/></svg>
    </div>
    <div className="text-[17px] font-semibold mb-1.5">Scan your repo</div>
    <p className="text-[13.5px] leading-[1.55] text-muted-foreground">Point the scanner at an existing codebase. Get your first memory layer in one command, no config.</p>
  </a>

  <a href="/docs/enforce" className="group bg-background p-6 hover:bg-muted transition-colors block">
    <div className="flex items-start justify-between mb-2">
      <div className="text-[11px] font-medium text-muted-foreground">Guide · 5 min</div>
      <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" className="text-muted-foreground group-hover:text-foreground group-hover:translate-x-0.5 transition-all"><path d="M3 7H11M11 7L8 4M11 7L8 10"/></svg>
    </div>
    <div className="text-[17px] font-semibold mb-1.5">Set up enforcement</div>
    <p className="text-[13.5px] leading-[1.55] text-muted-foreground">Install the MCP server. Connect your AI tool. Watch the first generation get redirected to a real preset.</p>
  </a>

  <a href="/docs/agent-resources" className="group bg-background p-6 hover:bg-muted transition-colors block">
    <div className="flex items-start justify-between mb-2">
      <div className="text-[11px] font-medium text-muted-foreground">For AI tools</div>
      <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" className="text-muted-foreground group-hover:text-foreground group-hover:translate-x-0.5 transition-all"><path d="M3 7H11M11 7L8 4M11 7L8 10"/></svg>
    </div>
    <div className="text-[17px] font-semibold mb-1.5">Plug an AI tool in</div>
    <p className="text-[13.5px] leading-[1.55] text-muted-foreground">MCP server, llms.txt, per-page markdown, copy-to-AI: every surface for making an agent fluent in your system.</p>
  </a>

  <a href="/docs/memory-layer" className="group bg-background p-6 hover:bg-muted transition-colors block">
    <div className="flex items-start justify-between mb-2">
      <div className="text-[11px] font-medium text-muted-foreground">Concept · 6 min</div>
      <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" strokeWidth="1.5" className="text-muted-foreground group-hover:text-foreground group-hover:translate-x-0.5 transition-all"><path d="M3 7H11M11 7L8 4M11 7L8 10"/></svg>
    </div>
    <div className="text-[17px] font-semibold mb-1.5">Read about the memory layer</div>
    <p className="text-[13.5px] leading-[1.55] text-muted-foreground">Why longitudinal beats snapshot for design systems in the AI age, and what that unlocks.</p>
  </a>

</div>

---

# Agent resources

Source: https://presetai.dev/docs/agent-resources
Type: reference
Summary: Every surface AI tools can read: MCP server, llms.txt, per-page markdown, copy-to-AI.
Last updated: 2026-05-11
Related: Set up enforcement (https://presetai.dev/docs/enforce), Why the memory layer matters (https://presetai.dev/docs/memory-layer)

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'Agent resources',
  description: 'Every way an AI tool can read preset AI: MCP server, llms.txt, per-page markdown, and one-click context handoff.',
  type: 'reference',
  summary: 'Every surface AI tools can read: MCP server, llms.txt, per-page markdown, copy-to-AI.',
  last_updated: '2026-05-11',
  related: ['/enforce', '/memory-layer'],
}

export const sections = [
  { title: 'MCP server', id: 'mcp-server' },
  { title: 'llms.txt and llms-full.txt', id: 'llmstxt-and-llms-fulltxt' },
  { title: 'Per-page markdown', id: 'per-page-markdown' },
  { title: 'Copy this page to AI', id: 'copy-this-page-to-ai' },
  { title: "What's next", id: 'whats-next' },
]

# Agent resources

preset AI is built to be read by AI tools, not just humans. This page lists every surface an agent can use: to query your memory layer, to ingest these docs, or to act on what it reads.

Pick the surface that matches what the agent is trying to do.

## MCP server

The Model Context Protocol server is the deepest surface. It lets an AI tool call into your live memory layer: list components, look up presets, validate generated code, read context rules at the moment of generation.

```bash
claude mcp add --transport http preset https://mcp.presetai.dev/mcp
```

For Cursor, Windsurf, VS Code Agent, and Zed, the install command differs per client. See [developers.presetai.dev](https://developers.presetai.dev/) for the full per-tool list.

The MCP server runs over OAuth: no config files, no API keys, no manual rotation. It's free on every plan.

<Note>
Use MCP when the agent needs to **act** on your memory layer: generate code that matches your presets, validate against forbidden primitives, look up the current state of a token. Use the markdown surfaces below when the agent just needs to **read** these docs.
</Note>

## llms.txt and llms-full.txt

For agents that ingest documentation as context, both files live at the root of this site:

- [`/llms.txt`](https://presetai.dev/docs/llms.txt): a manifest listing every page with a one-line summary. Compact. Use it for "give me a map" prompts.
- [`/llms-full.txt`](https://presetai.dev/docs/llms-full.txt): the full content of every page concatenated into a single payload. Drop the URL into any AI tool that supports remote context.

Both regenerate on request, so they stay in sync with the live MDX corpus. No build step.

```bash
curl https://presetai.dev/docs/llms-full.txt
```

## Per-page markdown

Every page on this site is also served as raw markdown: same path, `.md` suffix:

| Page                          | Markdown                          |
| ----------------------------- | --------------------------------- |
| `presetai.dev/docs/enforce`     | `presetai.dev/docs/enforce.md`      |
| `presetai.dev/docs/memory-layer`| `presetai.dev/docs/memory-layer.md` |
| `presetai.dev/docs/` (this index) | `presetai.dev/docs/index.md`      |

The markdown view strips the chrome and leaves the prose and code blocks. Use it when you want to feed exactly one page to an agent: surgical context, not the whole site.

## Copy this page to AI

The button in the top-right of every desktop page handles the common case:

- **Copy as markdown**: copies the page's raw markdown to your clipboard, ready to paste into any AI tool.
- **Open in Claude**: opens a Claude conversation pre-filled with this page's URL.
- **Open in ChatGPT**: same, for ChatGPT.

Use it when you're reading something and want the agent to read along with you.

## What's next

<div className="not-prose grid grid-cols-1 md:grid-cols-3 gap-3 mt-6">
  <a href="/docs/enforce" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Set up enforcement</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Connect a tool via MCP and watch the first rejection land.</p>
  </a>
  <a href="https://developers.presetai.dev/" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Developers</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Per-tool quickstarts</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Claude Code, Cursor, Windsurf, VS Code, Zed: bespoke setup for each.</p>
  </a>
  <a href="/docs/" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Overview</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">What is preset AI</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Back to the overview.</p>
  </a>
</div>

---

# Connect an AI coding tool

Source: https://presetai.dev/docs/ai-coding-tools
Type: guide
Summary: One-line MCP install for each major AI coding tool. preset AI becomes the design-system runtime for the agent.
Last updated: 2026-05-12
Related: Agent resources (https://presetai.dev/docs/agent-resources), Set up enforcement (https://presetai.dev/docs/enforce)
Install: claude mcp add --transport http preset https://mcp.presetai.dev/mcp

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'Connect an AI coding tool',
  description: 'Give your AI coding assistant access to your design system via MCP. Per-tool install for Claude Code, Cursor, Copilot, Windsurf.',
  type: 'guide',
  summary: 'One-line MCP install for each major AI coding tool. preset AI becomes the design-system runtime for the agent.',
  last_updated: '2026-05-12',
  related: ['/agent-resources', '/enforce'],
  install_command: 'claude mcp add --transport http preset https://mcp.presetai.dev/mcp',
}

export const sections = [
  { title: 'Pick a tool', id: 'pick-a-tool' },
  { title: 'Claude Code', id: 'claude-code' },
  { title: 'Cursor', id: 'cursor' },
  { title: 'GitHub Copilot', id: 'github-copilot' },
  { title: 'Windsurf', id: 'windsurf' },
  { title: 'What your AI can do', id: 'what-your-ai-can-do' },
  { title: 'Adaptive behavior', id: 'adaptive-behavior' },
  { title: 'Troubleshooting', id: 'troubleshooting' },
]

# Connect an AI coding tool

Give your AI coding assistant access to your design system. Once connected via MCP, the agent reads your tokens, presets, and patterns before it writes, and validates code against your rules after.

## Pick a tool

Every major AI coding tool that speaks MCP works with preset AI. The install is one line in each.

| Tool | Mode | Install |
|---|---|---|
| **Claude Code** | Terminal | `claude mcp add --transport http preset https://mcp.presetai.dev/mcp` |
| **Cursor** | Editor | Add via Settings → MCP, see below |
| **GitHub Copilot** | Editor (Agent Mode) | Via VS Code MCP settings |
| **Windsurf** | Editor | Via MCP plugin settings |

The MCP server runs over OAuth: no API keys to manage. Free on every plan.

For a tool-specific operating loop (what to prompt, when to validate, common pitfalls) see the per-tool pages linked from the sidebar.

## Claude Code

The fastest install. From any terminal:

```bash
claude mcp add --transport http preset https://mcp.presetai.dev/mcp
```

Verify the connection:

```bash
claude mcp list
```

You should see `preset` with status `connected`. See the [Claude Code guide](/ai-coding-tools/claude-code) for the recommended operating loop.

## Cursor

In Cursor, open **Settings → MCP**. Add a new server:

```json
{
  "mcpServers": {
    "preset": {
      "url": "https://mcp.presetai.dev/mcp",
      "type": "http"
    }
  }
}
```

Cursor will prompt you to authenticate via OAuth on first use. See the [Cursor guide](/ai-coding-tools/cursor) for the prompting template.

## GitHub Copilot

Copilot Agent Mode (VS Code) supports remote MCP servers. In VS Code, open **Settings → Copilot → Agent mode → MCP servers** and add:

```json
{
  "preset": {
    "url": "https://mcp.presetai.dev/mcp"
  }
}
```

OAuth flow runs on first request. See the [Copilot guide](/ai-coding-tools/copilot) for the governance recommendations.

## Windsurf

In Windsurf, open the MCP settings panel and add:

```json
{
  "mcpServers": {
    "preset": {
      "url": "https://mcp.presetai.dev/mcp"
    }
  }
}
```

OAuth on first use. See the [Windsurf guide](/ai-coding-tools/windsurf) for team operating rules.

## What your AI can do

Once connected, the agent gains these capabilities:

| Capability | Example prompt |
|---|---|
| **Search** | "Search for button presets." |
| **Suggest** | "What preset should I use for a delete action?" |
| **Generate** | "Generate a form with email and password inputs." |
| **Validate** | "Check this code for design system violations." |
| **Fix** | "Fix the violations in this component." |
| **Audit** | "Run a design system audit on this file." |

### Example conversations

**Finding the right component**:

> I need a dropdown for selecting a time period.

The agent uses `get_intent_route` and `get_preferred_component` to find the matching preset, then generates code using your design system.

**Checking your work**:

> Validate this component for design system compliance.

The agent uses `validate_generated_code` to check for violations and suggest fixes.

**Understanding constraints**:

> What should I avoid when building this form?

The agent uses `get_forbidden_primitives` and `get_anti_patterns` to explain which patterns are blocked.

## Adaptive behavior

The MCP server adapts to your design system's maturity:

| Mode | Behavior | Best for |
|---|---|---|
| **Generative** | Proposes new patterns; warns but doesn't block | Early-stage teams |
| **Hybrid** | Suggests existing patterns; warns on violations | Growing teams |
| **Enforcement** | Requires existing presets; blocks violations | Enterprise teams |

The mode is auto-detected from your preset count, token coverage, and other signals. Override with `set_system_mode`.

## Troubleshooting

### "Connection failed"

1. Confirm you're signed in to preset AI in your browser (OAuth state is shared)
2. Restart your AI tool after configuring MCP
3. Test the server directly: `curl https://mcp.presetai.dev/` returns a JSON health check (the `/mcp` path speaks MCP, not plain GET)

### "Tools not appearing"

1. Restart your AI tool after configuration
2. Check for JSON syntax errors in your config file
3. Confirm OAuth completed: first request opens a browser; you must approve

### "Gateway online but tools don't work"

1. The MCP server is healthy but tool calls may fail for other reasons
2. Check the specific error in the agent's reasoning trace
3. Ensure your design system has data (presets, tokens, components) to act on

## FAQ

### Do I need an API key?

No. The MCP server runs over OAuth: your AI tool authenticates once, and the memory layer becomes available immediately.

### Can I use multiple AI tools with the same account?

Yes. Every tool authenticates independently but reads from the same memory layer.

### Is my code sent to preset AI servers?

Only when you explicitly ask the AI to validate or audit code. MCP tools operate on the code snippets you provide, not your entire codebase.

### What MCP tools are available?

60+ tools across guardrails, discovery, generation, validation, typography, accessibility, Figma, and workflows. See [developers.presetai.dev](https://developers.presetai.dev) for the full reference.

---

# Claude Code with preset AI

Source: https://presetai.dev/docs/ai-coding-tools/claude-code
Type: guide
Summary: Operating loop for Claude Code: read context first, generate with constraints, validate, propose canonical changes.
Last updated: 2026-05-12
Prerequisites: Connect an AI coding tool (https://presetai.dev/docs/ai-coding-tools)
Related: Agent resources (https://presetai.dev/docs/agent-resources), Set up enforcement (https://presetai.dev/docs/enforce)
Install: claude mcp add --transport http preset https://mcp.presetai.dev/mcp

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'Claude Code with preset AI',
  description: 'Use Claude Code as a governed design-system runtime. The recommended operating loop: read context, generate within constraints, validate, propose.',
  type: 'guide',
  summary: 'Operating loop for Claude Code: read context first, generate with constraints, validate, propose canonical changes.',
  last_updated: '2026-05-12',
  prerequisites: ['/ai-coding-tools'],
  related: ['/agent-resources', '/enforce'],
  install_command: 'claude mcp add --transport http preset https://mcp.presetai.dev/mcp',
}

export const sections = [
  { title: 'Setup', id: 'setup' },
  { title: 'Recommended operating loop', id: 'recommended-operating-loop' },
  { title: 'Prompting pattern', id: 'prompting-pattern' },
  { title: 'Read, generate, apply', id: 'read-generate-apply' },
  { title: 'Common failure patterns', id: 'common-failure-patterns' },
  { title: 'Team policy', id: 'team-policy' },
]

# Claude Code with preset AI

Use Claude Code with preset AI as a governed design-system runtime.

## Setup

One command:

```bash
claude mcp add --transport http preset https://mcp.presetai.dev/mcp
```

OAuth runs on first request. Verify the connection:

```bash
claude mcp list
```

You should see `preset` with status `connected`. The full per-tool install matrix lives in [Connect an AI coding tool](/ai-coding-tools).

## Recommended operating loop

The four-step loop that keeps Claude Code aligned with the system:

1. **Read context first**: inspect relevant presets, patterns, and tokens; fetch active constraints for the target file or intent
2. **Generate with constraints**: request code by preset name and semantic intent; avoid hardcoded values and unapproved primitives
3. **Validate before and after**: run pre-generation checks when available; run generated-code validation and drift checks
4. **Propose before apply** (for system-level changes): for new or changed presets or rules, use the proposal lifecycle; apply only after validation and required approvals

## Prompting pattern

Structure your prompts like this:

- **Intent**: what you are building
- **Context**: target route or component, and constraints
- **Required artifacts**: preset names, token categories, patterns
- **Validation ask**: request drift and compliance checks before finalizing

Example:

> Build a destructive confirmation flow for account deletion. Use approved destructive presets, token-based colors, and the interaction rules from the design system. Validate generated code and report drift and compliance findings before final output.

## Read, generate, apply

### Read

- at the start of a task
- when uncertain about naming or policy
- when working in unfamiliar domains or components

### Generate

- only after retrieving required constraints or artifacts
- for implementation and refactor suggestions

### Apply

- direct apply for low-risk local code changes with passing validation
- proposal + approval path for canonical system artifacts

## Common failure patterns

- generating from generic UI patterns without querying preset AI first
- hardcoding style values where tokens exist
- skipping post-generation validation
- applying system-level changes without the proposal workflow

## Team policy

Adopt a simple policy:

- **No merge** without passing drift and compliance checks
- **No canonical model writes from AI** without a proposal trail
- **Require explicit approval** in stricter compliance modes

---

# GitHub Copilot with preset AI

Source: https://presetai.dev/docs/ai-coding-tools/copilot
Type: guide
Summary: Operating model for Copilot: gather context first, generate with intent-based constraints, validate, route canonical writes.
Last updated: 2026-05-12
Prerequisites: Connect an AI coding tool (https://presetai.dev/docs/ai-coding-tools)
Related: Claude Code with preset AI (https://presetai.dev/docs/ai-coding-tools/claude-code), Cursor with preset AI (https://presetai.dev/docs/ai-coding-tools/cursor)

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'GitHub Copilot with preset AI',
  description: 'Keep Copilot outputs aligned with preset AI tokens, presets, and patterns while maintaining development speed.',
  type: 'guide',
  summary: 'Operating model for Copilot: gather context first, generate with intent-based constraints, validate, route canonical writes.',
  last_updated: '2026-05-12',
  prerequisites: ['/ai-coding-tools'],
  related: ['/ai-coding-tools/claude-code', '/ai-coding-tools/cursor'],
}

export const sections = [
  { title: 'Setup', id: 'setup' },
  { title: 'Operating model', id: 'operating-model' },
  { title: 'Prompting guidance', id: 'prompting-guidance' },
  { title: 'Governance', id: 'governance' },
  { title: 'Common pitfalls', id: 'common-pitfalls' },
]

# GitHub Copilot with preset AI

Keep Copilot outputs aligned with preset AI tokens, presets, and patterns while maintaining development speed.

## Setup

GitHub Copilot Agent Mode (VS Code) supports remote MCP servers. In VS Code, open **Settings → Copilot → Agent mode → MCP servers** and add:

```json
{
  "preset": {
    "url": "https://mcp.presetai.dev/mcp"
  }
}
```

OAuth runs on first request. See [Connect an AI coding tool](/ai-coding-tools) for the full install matrix.

<Note>
Standard Copilot inline completions don't consume MCP. Use Agent Mode for governed generation against your design system.
</Note>

## Operating model

Use Copilot as a coding accelerator, with preset AI as the policy and system-intelligence layer.

Recommended flow:

1. Gather preset AI context first (presets, tokens, pattern guidance)
2. Generate with intent-based constraints
3. Validate generated output with drift and compliance checks
4. Route system-level changes through the proposal lifecycle

## Prompting guidance

When requesting code, include:

- intended component behavior
- required preset names
- token usage requirements
- validation expectation before final merge

Example:

> Generate a settings card using approved presets and semantic tokens only. Include accessible interaction states and avoid hardcoded styles.

## Governance

- enable PR checks for drift and policy validation
- require explicit approval for canonical model writes
- track recurring violation patterns to refine rules

## Common pitfalls

- accepting quick suggestions that bypass semantic presets
- copying generated code without a validation pass
- mixing local style overrides that create drift

---

# Cursor with preset AI

Source: https://presetai.dev/docs/ai-coding-tools/cursor
Type: guide
Summary: Operating workflow for Cursor: discover context, generate within constraints, validate, govern canonical writes.
Last updated: 2026-05-12
Prerequisites: Connect an AI coding tool (https://presetai.dev/docs/ai-coding-tools)
Related: Claude Code with preset AI (https://presetai.dev/docs/ai-coding-tools/claude-code), Agent resources (https://presetai.dev/docs/agent-resources)

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'Cursor with preset AI',
  description: 'Run Cursor with preset AI as a constrained design-system context source. Discover, generate within constraints, validate, govern.',
  type: 'guide',
  summary: 'Operating workflow for Cursor: discover context, generate within constraints, validate, govern canonical writes.',
  last_updated: '2026-05-12',
  prerequisites: ['/ai-coding-tools'],
  related: ['/ai-coding-tools/claude-code', '/agent-resources'],
}

export const sections = [
  { title: 'Setup', id: 'setup' },
  { title: 'Recommended Cursor workflow', id: 'recommended-cursor-workflow' },
  { title: 'Prompting template', id: 'prompting-template' },
  { title: 'Common mistakes', id: 'common-mistakes' },
  { title: 'Team policy', id: 'team-policy' },
]

# Cursor with preset AI

Generate and edit UI in Cursor while preserving preset AI alignment by default.

## Setup

In Cursor, open **Settings → MCP** and add:

```json
{
  "mcpServers": {
    "preset": {
      "url": "https://mcp.presetai.dev/mcp",
      "type": "http"
    }
  }
}
```

OAuth runs on first request. Verify MCP server connectivity before coding sessions. The full per-tool install matrix lives in [Connect an AI coding tool](/ai-coding-tools).

## Recommended Cursor workflow

Four steps per task:

1. **Discover context first**: ask Cursor to fetch relevant presets, patterns, and token guidance; retrieve active constraints for the target task
2. **Generate within constraints**: request intent-based outputs using approved preset names; avoid raw style values and ad-hoc component decisions
3. **Validate and iterate**: run drift and validation checks after generation; apply suggested fixes before finalizing
4. **Govern writes**: for canonical system changes, route through the proposal lifecycle; avoid direct apply in stricter compliance modes without approvals

## Prompting template

Use a constrained prompt shape:

- task intent
- target file or surface
- required system artifacts
- validation requirement before final answer

Example:

> Implement a settings form using existing presets and semantic tokens. Validate for drift and compliance and show required fixes before final code.

## Common mistakes

- generating from generic framework defaults without a preset AI lookup
- accepting output without a validation pass
- hardcoding token-like values in component code

## Team policy

For teams using Cursor heavily:

- enforce PR drift checks
- require a proposal trail for system-level artifact changes
- review recurring violations to improve rules and guidance

---

# Windsurf with preset AI

Source: https://presetai.dev/docs/ai-coding-tools/windsurf
Type: guide
Summary: Operating workflow for Windsurf: retrieve context, generate within constraints, validate, govern canonical writes.
Last updated: 2026-05-12
Prerequisites: Connect an AI coding tool (https://presetai.dev/docs/ai-coding-tools)
Related: Claude Code with preset AI (https://presetai.dev/docs/ai-coding-tools/claude-code), Cursor with preset AI (https://presetai.dev/docs/ai-coding-tools/cursor), GitHub Copilot with preset AI (https://presetai.dev/docs/ai-coding-tools/copilot)

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'Windsurf with preset AI',
  description: 'Run Windsurf workflows with preset AI as the system constraint and governance source. Context, generation, validation, governed changes.',
  type: 'guide',
  summary: 'Operating workflow for Windsurf: retrieve context, generate within constraints, validate, govern canonical writes.',
  last_updated: '2026-05-12',
  prerequisites: ['/ai-coding-tools'],
  related: ['/ai-coding-tools/claude-code', '/ai-coding-tools/cursor', '/ai-coding-tools/copilot'],
}

export const sections = [
  { title: 'Setup', id: 'setup' },
  { title: 'Recommended workflow', id: 'recommended-workflow' },
  { title: 'Team operating rules', id: 'team-operating-rules' },
  { title: 'Failure modes', id: 'failure-modes' },
]

# Windsurf with preset AI

Use Windsurf for high-velocity implementation while preserving design-system consistency and governance controls.

## Setup

In Windsurf, open the MCP settings panel and add:

```json
{
  "mcpServers": {
    "preset": {
      "url": "https://mcp.presetai.dev/mcp"
    }
  }
}
```

OAuth runs on first request. See [Connect an AI coding tool](/ai-coding-tools) for the full install matrix.

## Recommended workflow

Four steps per task:

1. **Context retrieval**: fetch relevant presets, patterns, and token guidance; identify active constraints for the target surface
2. **Generation**: request intent-first UI output; require semantic token and preset usage
3. **Validation**: run drift and compliance checks; capture violations and remediation before merge
4. **Governed changes**: for system-level artifact updates, use propose → validate → apply; require approvals based on current compliance mode

## Team operating rules

- no production merge without automated drift and compliance checks
- no direct system-artifact apply from AI without an approval path in stricter modes
- maintain auditability of major AI-generated changes

## Failure modes

Watch for these:

- pattern drift introduced by convenience refactors
- token bypass through local literals
- unreviewed proposal application

---

# Active guardrails

Source: https://presetai.dev/docs/compliance/active-guardrails
Type: guide
Summary: Active guardrails combine pre-generation constraints, post-generation validation, and policy gates before apply: a controlled loop instead of ad-hoc assistant behavior.
Last updated: 2026-05-12
Related: Rule model (https://presetai.dev/docs/compliance/rule-model), Validation and confidence (https://presetai.dev/docs/compliance/validation-and-confidence), Set up enforcement (https://presetai.dev/docs/enforce)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Active guardrails',
  description: 'How preset AI moves from passive guidance to active constraint enforcement for AI workflows.',
  type: 'guide',
  summary: 'Active guardrails combine pre-generation constraints, post-generation validation, and policy gates before apply: a controlled loop instead of ad-hoc assistant behavior.',
  last_updated: '2026-05-12',
  related: ['/compliance/rule-model', '/compliance/validation-and-confidence', '/enforce'],
}

export const sections = [
  { title: 'Objective', id: 'objective' },
  { title: 'Guardrail model', id: 'guardrail-model' },
  { title: 'Core guardrail layers', id: 'core-guardrail-layers' },
  { title: 'Expected outcomes', id: 'expected-outcomes' },
  { title: 'Integration guidance', id: 'integration-guidance' },
  { title: 'Relationship to compliance modes', id: 'relationship-to-compliance-modes' },
]

# Active guardrails

How preset AI moves from passive guidance to active constraint enforcement for AI workflows.

## Objective

Ensure AI-generated output is system-aligned by design, not corrected after drift appears.

## Guardrail model

Active guardrails combine three moments:

- **Constraints before generation**: the agent reads what's allowed before writing
- **Validation after generation**: generated code is checked against rules
- **Policy gates before apply**: canonical writes are gated on approval

Together these create a controlled loop instead of ad-hoc assistant behavior.

## Core guardrail layers

1. Forbidden primitives and anti-pattern constraints
2. Context-aware active constraints by file, intent, or surface
3. Pre-generation validation checks
4. Post-generation code validation and drift checks
5. Mode-aware apply policy gates

## Expected outcomes

- lower cleanup work after AI generation
- fewer policy violations entering PRs
- more predictable assistant behavior across teams

## Integration guidance

Use guardrails as the default policy in AI-assisted coding flows:

- retrieve constraints first
- generate within constraints
- validate before commit or apply
- route unresolved cases into the proposal workflow

## Relationship to compliance modes

Each compliance mode tunes how strictly guardrails block versus advise:

- **Observe / Assist**: emphasis on guidance and learning
- **Guard / Enforce**: stricter blocking and approval requirements

See [Rule model](/compliance/rule-model) for the underlying rule contract and [Validation and confidence](/compliance/validation-and-confidence) for how guardrail results feed scoring.

---

# Exceptions and escalation

Source: https://presetai.dev/docs/compliance/exceptions-and-escalation
Type: guide
Summary: Three exception levels (local, domain, system), explicit escalation triggers, and review cadence. No permanent exceptions by default.
Last updated: 2026-05-12
Related: Rule model (https://presetai.dev/docs/compliance/rule-model), Active guardrails (https://presetai.dev/docs/compliance/active-guardrails)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Exceptions and escalation',
  description: 'How to handle policy exceptions without weakening governance. Controlled, traceable, and temporary by default.',
  type: 'guide',
  summary: 'Three exception levels (local, domain, system), explicit escalation triggers, and review cadence. No permanent exceptions by default.',
  last_updated: '2026-05-12',
  related: ['/compliance/rule-model', '/compliance/active-guardrails'],
}

export const sections = [
  { title: 'Principle', id: 'principle' },
  { title: 'Exception policy', id: 'exception-policy' },
  { title: 'Exception levels', id: 'exception-levels' },
  { title: 'Escalation triggers', id: 'escalation-triggers' },
  { title: 'Escalation path', id: 'escalation-path' },
  { title: 'AI-specific exception handling', id: 'ai-specific-exception-handling' },
  { title: 'Review cadence', id: 'review-cadence' },
  { title: 'Metrics to track', id: 'metrics-to-track' },
]

# Exceptions and escalation

How to handle policy exceptions without weakening governance.

## Principle

Exceptions should be controlled, traceable, and temporary.

## Exception policy

Every exception must include:

- **reason**: what's being exempted and why
- **owner**: who's accountable
- **scope**: what it applies to
- **expiry date**: when it must be re-reviewed
- **rollback or remediation plan**: how it gets cleaned up

No permanent exceptions by default.

## Exception levels

### Level 1: Local exception

- scoped to one artifact or file set
- short expiry
- no broad policy change

### Level 2: Domain exception

- scoped to a rule domain (for example, token-naming migration)
- steward approval required
- explicit impact tracking

### Level 3: System exception

- cross-domain or org-wide impact
- governance lead approval required
- mandatory review checkpoint

## Escalation triggers

Escalate when any of the following occur:

- repeated violations of the same rule category
- increasing exception count over time
- policy blocks critical delivery repeatedly
- security, accessibility, or compliance-critical rules violated
- conflicting ownership decisions

## Escalation path

1. Capture issue and context
2. Classify severity and blast radius
3. Assign governance owner
4. Choose immediate containment action
5. Decide rule adjustment, exception extension, or rejection
6. Document final decision and follow-up tasks

## AI-specific exception handling

For AI-generated changes:

- keep proposal artifacts when exceptions are requested
- require explicit human approval in Guard / Enforce modes
- log model, tool, and context for post-incident analysis

## Review cadence

Run exception reviews at minimum:

- **weekly** for active programs
- **monthly** for mature, stable systems

Review outcomes:

- remove expired exceptions
- convert recurring exceptions into updated policy
- tighten policy where exception abuse appears

## Metrics to track

- active exceptions by level
- expired exceptions not remediated
- repeat exceptions by rule
- time-to-resolution by severity

---

# Rule model

Source: https://presetai.dev/docs/compliance/rule-model
Type: reference
Summary: Rule shape, severity model, evaluation lifecycle, and quality criteria. The contract underneath every guardrail and validation check.
Last updated: 2026-05-12
Related: Active guardrails (https://presetai.dev/docs/compliance/active-guardrails), Validation and confidence (https://presetai.dev/docs/compliance/validation-and-confidence), Exceptions and escalation (https://presetai.dev/docs/compliance/exceptions-and-escalation)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Rule model',
  description: 'How preset AI expresses, evaluates, and evolves enforceable system rules: the contract for guardrails, validation, and policy gates.',
  type: 'reference',
  summary: 'Rule shape, severity model, evaluation lifecycle, and quality criteria. The contract underneath every guardrail and validation check.',
  last_updated: '2026-05-12',
  related: ['/compliance/active-guardrails', '/compliance/validation-and-confidence', '/compliance/exceptions-and-escalation'],
}

export const sections = [
  { title: 'Why this exists', id: 'why-this-exists' },
  { title: 'Rule shape', id: 'rule-shape' },
  { title: 'Rule categories', id: 'rule-categories' },
  { title: 'Severity model', id: 'severity-model' },
  { title: 'Evaluation lifecycle', id: 'evaluation-lifecycle' },
  { title: 'Rule evolution', id: 'rule-evolution' },
  { title: 'Exceptions and overrides', id: 'exceptions-and-overrides' },
  { title: 'Rule outputs', id: 'rule-outputs' },
  { title: 'Rule quality criteria', id: 'rule-quality-criteria' },
]

# Rule model

Defines how preset AI expresses, evaluates, and evolves enforceable system rules.

## Why this exists

Rules are preset AI's enforcement layer. They convert design-system intent into machine-evaluable constraints for:

- product workflows
- CI and CLI checks
- MCP read/write governance

## Rule shape

At minimum, a rule encodes:

- **intent**: the behavior or outcome it governs
- **predicate**: the condition to evaluate
- **severity**: impact level when violated
- **scope**: where it applies (artifact, route, workspace, org)
- **guidance / fix**: how to remediate

## Rule categories

Common categories:

- token usage and naming
- preset usage and prop constraints
- pattern composition rules
- interaction and accessibility requirements
- AI generation and write constraints

## Severity model

Use consistent severity semantics:

- **info**: informational, no action required
- **warning**: should fix, doesn't block
- **error**: should fix, signals real problem
- **blocking**: policy-gated, must fix before merge or apply

Severity is mode-aware. Same rule, different teeth depending on whether you're in Observe, Assist, Guard, or Enforce.

## Evaluation lifecycle

Rules can be evaluated at multiple points:

- **pre-generation**: AI constraints
- **post-generation**: validate output
- **pre-apply**: proposal gate
- **CI / PR checks**
- **periodic health and audit scans**

## Rule evolution

Rules should evolve with system maturity:

- start descriptive (guidance-heavy)
- graduate to stricter enforcement when confidence is high
- track exception volume and false-positive rates
- sunset or split brittle rules

## Exceptions and overrides

Exceptions should be:

- explicit
- time-bounded
- owner-attributed
- auditable

Overrides should never silently disable baseline governance. See [Exceptions and escalation](/compliance/exceptions-and-escalation) for the full lifecycle.

## Rule outputs

Every evaluation should produce machine- and human-usable output:

- pass / fail result
- severity and scope
- violation location and context
- recommended fix path

## Rule quality criteria

A good rule is:

- **unambiguous**: one interpretation, no edge cases the author meant differently
- **testable**: outcome can be verified deterministically
- **scoped**: applies only where intended
- **explainable**: the violation message tells the reader what to do
- **stable**: doesn't flag false positives in typical development workflows

---

# Validation and confidence

Source: https://presetai.dev/docs/compliance/validation-and-confidence
Type: reference
Summary: Validation asks 
Last updated: 2026-05-12
Related: Rule model (https://presetai.dev/docs/compliance/rule-model), Active guardrails (https://presetai.dev/docs/compliance/active-guardrails)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Validation and confidence',
  description: 'How preset AI evaluates quality and determines trust levels for automated guidance and enforcement.',
  type: 'reference',
  summary: 'Validation asks "is the output correct?" Confidence asks "how reliable is our interpretation?" Together they tune how much automation is safe.',
  last_updated: '2026-05-12',
  related: ['/compliance/rule-model', '/compliance/active-guardrails'],
}

export const sections = [
  { title: 'Validation goals', id: 'validation-goals' },
  { title: 'Confidence goals', id: 'confidence-goals' },
  { title: 'Practical usage', id: 'practical-usage' },
  { title: 'Operational guidance', id: 'operational-guidance' },
]

# Validation and confidence

How preset AI evaluates quality and determines trust levels for automated guidance and enforcement.

## Validation goals

Validation should answer:

- Is the output structurally and semantically correct?
- How severe are detected issues?
- What fixes are safe and actionable?

## Confidence goals

Confidence should answer:

- How reliable is the system's interpretation or mapping?
- How much automation is safe at this stage?
- When should workflows require human review?

## Practical usage

Validation and confidence work together:

- **High validation confidence + low-risk scope** → faster apply paths
- **Low confidence or ambiguous findings** → proposal + review path
- **Repeated low-confidence zones** → improve taxonomy, rules, and metadata

## Operational guidance

Track and use:

- violation severity distribution
- false-positive and false-negative signals
- confidence trends by artifact type
- remediation latency

These should inform rule tuning and maturity-mode progression. See [Rule model](/compliance/rule-model) for the underlying rule contract and [Active guardrails](/compliance/active-guardrails) for how validation feeds the enforcement loop.

---

# Set up enforcement

Source: https://presetai.dev/docs/enforce
Type: guide
Summary: Install the MCP server and watch your first AI generation get redirected to a real preset.
Last updated: 2026-05-11
Prerequisites: Scan your repo (https://presetai.dev/docs/scan), Review what was extracted (https://presetai.dev/docs/extract)
Related: Agent resources (https://presetai.dev/docs/agent-resources)
Install: claude mcp add --transport http preset https://mcp.presetai.dev/mcp

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'Set up enforcement',
  description: 'Connect an AI coding tool, install the enforcement layer, and watch your first rejection land.',
  type: 'guide',
  summary: 'Install the MCP server and watch your first AI generation get redirected to a real preset.',
  last_updated: '2026-05-11',
  prerequisites: ['/scan', '/extract'],
  related: ['/agent-resources'],
  install_command: 'claude mcp add --transport http preset https://mcp.presetai.dev/mcp',
}

export const sections = [
  { title: 'Pick a connection', id: 'pick-a-connection' },
  { title: 'Install the MCP server', id: 'install-the-mcp-server' },
  { title: 'Watch the first enforcement', id: 'watch-the-first-enforcement' },
  { title: 'Raise the bar over time', id: 'raise-the-bar-over-time' },
  { title: "What's next", id: 'whats-next' },
]

# Set up enforcement

Your memory layer exists. Every AI tool in your stack is still ignoring it. This step changes that.

## Pick a connection

preset AI exposes your memory layer to agents three ways. Pick the one that matches where you want enforcement to land:

- **MCP server**: for Claude Code, Cursor, Windsurf, VS Code Agent Mode, and Zed. Enforces at generation time. Recommended for most teams.
- **GitHub Action**: for PRs. Runs `preset validate` on every commit and posts a comment with violations and fixes. Good backstop even if some developers don't use MCP.
- **CLI pre-commit hook**: for individual machines. Catches violations before they leave the developer's laptop.

You can combine them. MCP for generation, GitHub Action for review, pre-commit as a belt-and-suspenders local gate.

## Install the MCP server

For Claude Code (most common):

```bash
claude mcp add --transport http preset https://mcp.presetai.dev/mcp
```

For Cursor, Windsurf, VS Code Agent, and Zed, see the [developer quickstarts](https://developers.presetai.dev/). Every client has its own one-command install.

The MCP server runs over OAuth: no config files, no API keys to rotate. Your AI tool authenticates once; the memory layer becomes available immediately.

## Watch the first enforcement

Open your AI tool and ask it to generate something your design system has a pattern for. A realistic first prompt:

> Generate a destructive confirmation dialog for the delete account flow.

A tool connected via MCP now sees your presets before it writes anything. You'll get a response that looks more like this:

> Using `btn.destructive-confirm` from your preset (matched at 94% confidence). It requires a confirmation dialog: I'll include that too.

Compare to the same prompt without preset AI, where the tool invents a button, guesses at a color, and calls the dialog whatever it felt like in the moment.

If the tool tries something forbidden, `<button onClick={window.confirm(...)}>`, for example, preset AI rejects the generation and redirects. The rejection is visible in the tool's reasoning, not silently swapped.

## Raise the bar over time

Start permissive. The default configuration is a floor, not a ceiling: it blocks the worst violations and leaves soft patterns as suggestions. As your team gets comfortable, tighten.

You can:

- Add forbidden primitives to block specific anti-patterns (hardcoded hex colors, raw `<select>` elements, inline styles).
- Write context rules that change behavior based on file location (stricter in `src/app/`, looser in `src/dev/`).
- Route intents to presets (any "submit button" maps to `btn.primary`).

Every rule lives in your memory layer. When agents read the layer, they read the rules too. A forbidden primitive becomes an instruction the tool incorporates before generation, not a gate it slams into afterward.

## What's next

<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-3 mt-6">
  <a href="https://developers.presetai.dev/" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Developers</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Full quickstart per tool</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Claude Code, Cursor, Windsurf, VS Code, Zed: bespoke setup for each.</p>
  </a>
  <a href="/docs/" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Overview</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Back to the start</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Share the overview with a teammate.</p>
  </a>
</div>

---

# Review what was extracted

Source: https://presetai.dev/docs/extract
Type: guide
Summary: Confirm, edit, or reject extracted artifacts before they enter your memory layer.
Last updated: 2026-05-11
Prerequisites: Scan your repo (https://presetai.dev/docs/scan)
Related: Set up enforcement (https://presetai.dev/docs/enforce), Why the memory layer matters (https://presetai.dev/docs/memory-layer)

---
owner: jschuyler
updated: '2026-06-20'
status: stable
---

export const metadata = {
  title: 'Review what was extracted',
  description: 'The scan is a proposal, not a commit. Confirm, edit, or reject each artifact before it enters your memory layer.',
  type: 'guide',
  summary: 'Confirm, edit, or reject extracted artifacts before they enter your memory layer.',
  last_updated: '2026-05-11',
  prerequisites: ['/scan'],
  related: ['/enforce', '/memory-layer'],
}

export const sections = [
  { title: 'Open the dashboard', id: 'open-the-dashboard' },
  { title: 'Three actions per artifact', id: 'three-actions-per-artifact' },
  { title: 'Identity is assigned here', id: 'identity-is-assigned-here' },
  { title: "What's next", id: 'whats-next' },
]

# Review what was extracted

The scan produces a proposal. Nothing is canonical yet. This is the step where you decide what your memory layer remembers.

## Open the dashboard

From your repo root:

```bash
preset open
```

The command opens the review dashboard in your browser with your scan loaded. You'll see three tabs, **Tokens**, **Patterns**, and **Proposals**, with a count and an average confidence score at the top of each.

The dashboard is a private, per-repo view. Nothing is published until you explicitly promote it.

## Three actions per artifact

Every extracted item has the same three actions:

- **Confirm**: accept as-is. The artifact enters the memory layer with the name and shape the scanner inferred.
- **Edit**: adjust the name, description, or fields. Useful when the scanner's name is technically correct but doesn't match how your team talks about it.
- **Reject**: remove from the proposal. Rejected items are tracked so re-scanning doesn't re-propose them.

Confidence scores guide your attention. High-confidence items are usually correct; you'll mostly skim and confirm. Medium and low-confidence items deserve a closer look: those are where the scanner saw a recurring shape but isn't sure what to call it.

<Note>
Edit freely. The AI tools that consume your memory layer will read the names and descriptions you chose here. An agent asked to build a "primary action" is more likely to match a preset you named `primary-action` than one called `btn_submit_v2`.
</Note>

## Identity is assigned here

When you confirm an artifact, preset AI mints a stable identity: independent of the name. If you rename the preset later, agents still resolve correctly because the identity tracks through the rename.

This is the move that makes rename-safe refactors possible. Your team can evolve the vocabulary; the memory layer preserves the continuity.

What you reject is also recorded. Drift detection uses that record: if you rejected a pattern once and the scanner re-proposes it after new code lands, preset AI can flag the regression rather than silently re-suggesting.

## What's next

<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-3 mt-6">
  <a href="/docs/enforce" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Set up enforcement</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Install the MCP server. Watch your first rejection land.</p>
  </a>
  <a href="/docs/scan" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Scan again</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Re-run the scanner after your first review to pick up what you changed.</p>
  </a>
</div>

---

# First workflow

Source: https://presetai.dev/docs/first-workflow
Type: guide
Summary: Connect a system, create one preset, validate it, and watch an AI tool generate against it. End-to-end in five steps.
Last updated: 2026-05-12
Prerequisites: Key concepts (https://presetai.dev/docs/key-concepts)
Related: Scan your repo (https://presetai.dev/docs/scan), Set up enforcement (https://presetai.dev/docs/enforce), Agent resources (https://presetai.dev/docs/agent-resources)

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'First workflow',
  description: 'A practical hello-world path: connect a design system, create one artifact, validate it, and distribute it to AI and dev workflows.',
  type: 'guide',
  summary: 'Connect a system, create one preset, validate it, and watch an AI tool generate against it. End-to-end in five steps.',
  last_updated: '2026-05-12',
  prerequisites: ['/key-concepts'],
  related: ['/scan', '/enforce', '/agent-resources'],
}

export const sections = [
  { title: 'Goal', id: 'goal' },
  { title: 'Connect your system', id: 'connect-your-system' },
  { title: 'Build your first artifact', id: 'build-your-first-artifact' },
  { title: 'Use AI with system context', id: 'use-ai-with-system-context' },
  { title: 'Validate and review', id: 'validate-and-review' },
  { title: 'Apply and distribute', id: 'apply-and-distribute' },
  { title: 'What success looks like', id: 'what-success-looks-like' },
  { title: 'Suggested next moves', id: 'suggested-next-moves' },
]

# First workflow

A practical hello-world path from setup to governed output. Five steps; under an hour.

## Goal

Connect one design system, create one artifact, validate it, and distribute it to AI and dev workflows.

## Connect your system

From the app:

1. Choose or create a design system
2. Use **Connect** to attach upstream sources (Figma, codebase, or both)
3. Verify connection status in **Connect**

After this step a design-system workspace exists and source context is available for import and governance.

## Build your first artifact

Choose one quick path:

- **Tokens path**: define base semantic tokens
- **Preset path**: create or edit a preset in Studio
- **Content path**: establish core terminology and voice constraints

Recommended first artifact: a `primary-action` preset backed by semantic tokens.

After this step at least one canonical artifact exists and can be referenced by code or AI.

## Use AI with system context

Connect your coding assistant through MCP (via **Connect** / AI coding tools flow). For the one-line install on Claude Code:

```bash
claude mcp add --transport http preset https://mcp.presetai.dev/mcp
```

Then ask for an implementation using preset AI primitives. A realistic first prompt:

> Build a form using my presets and tokens.

Expected behavior from the agent:

- discovers valid components and presets
- uses token-aligned outputs
- avoids forbidden primitives and hardcoded values

After this step generated code is closer to system standards by default.

## Validate and review

Run validation in the surface that fits your workflow:

- **In app**: Health, audits, and related status surfaces
- **In MCP**: validation and drift tools
- **In CI/CLI**: drift and compliance checks in pipelines

If issues appear, generate a proposal or fix recommendation. Review before applying in stricter environments.

After this step changes are validated before broad rollout.

## Apply and distribute

After validation:

1. Approve or apply changes to the canonical model
2. Distribute through docs, MCP responses, and CI policy

After this step humans and AI consume the same updated system definition.

## What success looks like

By the end of your first workflow:

- the design system has a canonical baseline
- at least one preset is reusable
- AI output references system artifacts
- validation catches drift early
- a governance path exists: propose → validate → apply

## Suggested next moves

- Define 3-5 high-value presets (primary, secondary, destructive, text input, dialog action)
- Enable CI drift checks on key repos
- Set an initial compliance mode and review cadence

See [Set up enforcement](/enforce) for the MCP install in detail, and [Agent resources](/agent-resources) for every surface AI tools can read.

---

# Importing design systems

Source: https://presetai.dev/docs/importing-design-systems
Type: guide
Summary: Connect a GitHub, GitLab, or zip source. preset AI extracts tokens and components into a reviewable preset.yaml.
Last updated: 2026-05-12
Related: Updating design systems (https://presetai.dev/docs/updating-design-systems), Scan your repo (https://presetai.dev/docs/scan), Review what was extracted (https://presetai.dev/docs/extract)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Importing design systems',
  description: 'Extract design tokens and scan components from your existing system. Import from GitHub, GitLab, or upload a zip file.',
  type: 'guide',
  summary: 'Connect a GitHub, GitLab, or zip source. preset AI extracts tokens and components into a reviewable preset.yaml.',
  last_updated: '2026-05-12',
  related: ['/updating-design-systems', '/scan', '/extract'],
}

export const sections = [
  { title: 'Quick start', id: 'quick-start' },
  { title: 'Supported formats', id: 'supported-formats' },
  { title: 'Component library support', id: 'component-library-support' },
  { title: 'Importing from GitHub', id: 'importing-from-github' },
  { title: 'Importing from GitLab', id: 'importing-from-gitlab' },
  { title: 'Uploading a zip file', id: 'uploading-a-zip-file' },
  { title: 'Understanding the preview', id: 'understanding-the-preview' },
  { title: 'Component import wizard', id: 'component-import-wizard' },
  { title: 'Troubleshooting', id: 'troubleshooting' },
  { title: 'FAQ', id: 'faq' },
]

# Importing design systems

preset AI extracts design tokens and scans for components from your existing design system. Import from GitHub, GitLab, or upload a zip file of your codebase.

## Quick start

1. Go to **Design Systems** in the sidebar
2. Click **Import Design System**
3. Choose your import source: GitHub, GitLab, or upload
4. Enter the repository URL or upload your file
5. **Analyze token usage** (optional): find missing and unused tokens
6. Review the extracted tokens
7. Click **Import** to create your design system

<Note>
The analysis step finds tokens used in code but missing from your design system, and tokens defined but never used.
</Note>

## Supported formats

preset AI auto-detects and parses these token formats:

| Format | File types | What's extracted |
|---|---|---|
| **CSS Variables** | `globals.css`, `variables.css`, `tokens.css` | Colors, spacing, radius, typography |
| **Tailwind CSS** | `tailwind.config.js/ts` | Theme colors, spacing, fonts |
| **Tokens Studio** | `tokens.json`, `$metadata.json` | Full token sets with modes |
| **Style Dictionary** | `tokens/*.json`, `design-tokens.json` | Structured token hierarchies |

preset AI also recognizes Carbon, Material, Primer, and Chakra for optimized extraction.

## Component library support

Beyond token extraction, preset AI has built-in support for these libraries with full component and variant mapping:

| Library | Support |
|---|---|
| **shadcn/ui** | Full component mapping, variants, presets |
| **Material UI** | Full component mapping, variants, presets |
| **Ant Design** | Full component mapping, variants, presets |
| **Chakra UI** | Full component mapping, variants, presets |

### Theme generation

preset AI generates theme configurations for **Tailwind CSS**, **Radix**, **DaisyUI**, and **HeroUI**. AI tools then get not just your tokens, but your complete component patterns: generated code uses the right variants, props, and compositions.

## Importing from GitHub

You need a public GitHub repository URL (private requires an access token).

1. Click **Import Design System**
2. Select **GitHub**
3. Paste your repository URL: `https://github.com/owner/repo`, `https://github.com/owner/repo/tree/main`, or `owner/repo`
4. Click **Scan Repository**
5. Review the extracted tokens
6. Click **Import**

### Limitations

- Very large repositories may take longer to scan
- GitHub API rate limits apply: 60 requests/hour unauthenticated, 5,000/hour with a token

## Importing from GitLab

You need a GitLab repository URL and a Personal Access Token with `read_repository` scope.

### Creating a Personal Access Token

1. Go to GitLab → **Settings** → **Access Tokens**
2. Click **Add new token**
3. Name it (e.g. "preset AI Import")
4. Select scope: **read_repository**
5. Click **Create personal access token**
6. Copy the token: you won't see it again

### Steps

1. Click **Import Design System**
2. Select **GitLab**
3. Paste your repository URL: `https://gitlab.com/owner/repo` or `https://gitlab.com/group/subgroup/repo`
4. Enter your Personal Access Token
5. Click **Scan Repository**
6. Review the extracted tokens
7. Click **Import**

Your token is used only for this import. It is not stored on our servers.

## Uploading a zip file

For local codebases or when GitHub/GitLab isn't an option.

### What to include

Any of these files in your zip:

- `tokens.json` or `design-tokens.json`
- `tailwind.config.js` or `tailwind.config.ts`
- CSS files with custom properties (`globals.css`, `variables.css`)
- Token files from your design system

### What's skipped automatically

- `node_modules/`
- `.git/`
- `dist/` and `build/`
- Test files

### Steps

1. Click **Import Design System**
2. Select **Upload**
3. Drag and drop your `.zip` file or click to browse
4. Wait for extraction and parsing
5. Review the extracted tokens
6. Click **Import**

### Preparing your zip

```bash
zip -r design-system.zip \
  tailwind.config.js \
  src/styles/globals.css \
  tokens/ \
  -x "node_modules/*" -x ".git/*"
```

## Understanding the preview

After scanning, you'll see a preview of extracted tokens.

### Token categories

| Category | What's included |
|---|---|
| **Colors** | Color values, scales, semantic colors |
| **Spacing** | Margin/padding values |
| **Typography** | Font families, sizes, weights, line heights |
| **Radius** | Border radius values |
| **Shadows** | Box shadow definitions |

### Extraction confidence

| Level | Meaning |
|---|---|
| **High** | Parsed from a standard format (Tailwind, Tokens Studio, etc.) |
| **Medium** | Detected patterns with some ambiguity |
| **Low** | Extracted via AI analysis |

### Color philosophy

preset AI detects how your design system organizes colors:

- **Scale-first**: raw color scales like `blue-500`, `gray-100`
- **Semantic-first**: role-based tokens like `primary`, `background`
- **Hybrid**: a mix of scales and semantic tokens

## Component import wizard

In addition to token extraction, preset AI includes a **component import wizard** that scans your codebase for React components, detects variants, and creates presets automatically.

### How it works

Four steps:

1. **Source**: choose where to scan: upload a zip, connect to GitHub, or connect to GitLab
2. **Configure**: select folders to include (e.g. `src/components`), add exclude patterns, toggle AI-enhanced analysis
3. **Review**: browse discovered components, variants, inferred props, and confidence scores; select what to import
4. **Import**: preset AI creates one preset per variant and registers any inferred design tokens

### What gets created

| Artifact | How |
|---|---|
| **Presets** | One preset per component variant, named automatically (e.g. "Button: Destructive") |
| **Design tokens** | Token references found in component code are registered; duplicates skipped |
| **Import session** | A tracking record so you can review what was imported and retry failures |

### Importing from Storybook

If your project uses Storybook, zip your stories directory and upload:

```bash
zip -r stories.zip src/stories/ -x "node_modules/*"
```

The scanner recognizes `.stories.tsx`, `.stories.jsx`, and `.stories.mdx`, extracts story metadata (args, argTypes), and maps them to component variants.

### Component scanning sources

| Source | What's scanned |
|---|---|
| **Story files** (`.stories.tsx/jsx/mdx`) | Story args become variant props; argTypes inform token inference |
| **Component files** (`.tsx/jsx`) | JSX usage patterns, prop spreads, component composition |
| **Both combined** | Results are merged and deduplicated by component name |

### Confidence scores

Each discovered component has a 0-100% confidence score:

| Range | Meaning |
|---|---|
| **80-100%** | Strong signal from Storybook stories or high usage frequency |
| **50-79%** | Detected from code patterns with moderate certainty |
| **Below 50%** | Flagged for manual review; may be a utility or helper |

### Retrying failed imports

If some components fail (e.g. duplicate name conflicts), the wizard shows which failed and offers a **Retry** button that re-attempts only those.

## Troubleshooting

### "No design token files found"

The scanner couldn't identify any token files in your repository or zip.

- Make sure your token files use standard names (`tokens.json`, `tailwind.config.js`, `variables.css`)
- Check that files aren't in excluded directories (`node_modules`, `dist`)
- Try including more specific token files in your zip

### "No tokens could be extracted"

Files were found but couldn't be parsed.

- Verify your token files contain valid syntax
- Check that CSS files have `:root` with custom properties
- Make sure JSON files follow Tokens Studio or Style Dictionary format

### "GitHub API rate limit exceeded"

Too many requests to GitHub's public API.

- Wait an hour for the limit to reset
- Try a smaller repository
- Use zip upload instead

### "Invalid GitLab token"

The Personal Access Token is incorrect or expired.

- Generate a new token in GitLab settings
- Make sure the token has `read_repository` scope
- Check you copied the full token

### "Access denied" (GitLab)

The token doesn't have permission to read the repository.

- Verify you have access to the repository
- Regenerate the token with `read_repository` scope
- For group repos, ensure your GitLab account has access

## FAQ

### Can I import from private GitHub repos?

Yes. Enter an access token in the GitHub source form and preset AI uses it for all API calls and file fetches. The token is used only for this import; it is not stored.

### What if my design system uses a custom format?

preset AI uses AI analysis on non-standard files. Results may have lower confidence. Consider exporting to Tokens Studio or Style Dictionary format for best results.

### Can I re-import to update tokens?

Yes. See [Updating design systems](/updating-design-systems) for a complete guide to reviewing and applying changes from your source.

### What happens to existing tokens when I import?

Import creates a new design system. Your existing design systems are not affected.

### Is my code stored anywhere?

No. Repository scanning and zip processing happen in your browser. Only the extracted tokens are stored when you click **Import**.

### Can I import from Bitbucket?

Not yet. Bitbucket support is planned.

### What's the maximum zip file size?

There's no hard limit, but files over ~500MB may cause browser memory issues. Include only relevant token files.

### Does preset AI work with Tailwind CSS?

Yes. preset AI imports tokens from `tailwind.config.js/ts` files and generates Tailwind theme configurations. AI tools then reference your exact Tailwind classes and design tokens.

---

# Key concepts

Source: https://presetai.dev/docs/key-concepts
Type: concept
Summary: Vocabulary for everything else in the docs: tokens, presets, patterns, drift, compliance modes.
Last updated: 2026-05-12
Related: Why the memory layer matters (https://presetai.dev/docs/memory-layer), First workflow (https://presetai.dev/docs/first-workflow)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Key concepts',
  description: 'The core primitives of preset AI in plain language: design systems, tokens, presets, patterns, drift, and the memory model.',
  type: 'concept',
  summary: 'Vocabulary for everything else in the docs: tokens, presets, patterns, drift, compliance modes.',
  last_updated: '2026-05-12',
  related: ['/memory-layer', '/first-workflow'],
}

export const sections = [
  { title: 'What preset AI is', id: 'what-preset-ai-is' },
  { title: 'Core primitives', id: 'core-primitives' },
  { title: 'Product surfaces', id: 'product-surfaces' },
  { title: 'Creation vs. consumption', id: 'creation-vs-consumption' },
]

# Key concepts

This page defines preset AI's core primitives in plain language. Read it once: every other page in the docs assumes this vocabulary.

## What preset AI is

preset AI is **the design governance layer**. It is the infrastructure that exposes a team's design system to AI agents in a form they can read and defer to. It does not just document rules. It stores design intent in a canonical model, then uses that model to power:

- authoring (Studios + Rules)
- validation (Health + audits + drift checks)
- distribution (MCP, CI, docs, integrations)

## Core primitives

### Design System
A workspace-scoped system containing tokens, presets, patterns, interactions, recipes, and integration context.

### Snapshot
A point-in-time state of system artifacts used for comparison, auditing, and rollback-safe operations.

Practical use:

- compare before/after changes
- trace drift over time
- support release and governance review

### Token
A semantic design value (for example `color-primary`, not just `#3B82F6`).

Why it matters:

- gives human- and AI-readable intent
- enables consistent, centralized updates
- prevents hardcoded values from spreading

### Component
A UI primitive or compound element from your codebase or library (Button, Input, Card, etc.).

### Preset
A reusable, intent-based configuration for a component.

Example intent:

- `primary-action`
- `destructive-action`

Presets convert "how it should be used" into executable config that AI tools and developers can apply consistently.

### Pattern
A higher-order rule for composition and behavior across components.

Patterns define when and how pieces should be combined: not just styling details.

### Interaction
State and behavior rules (hover, focus, disabled, transitions, modality-specific behavior).

### Rule
An enforceable statement of what is allowed or required. Rules drive validation, drift checks, and AI guardrails.

### Drift
Deviation between implemented UI and the design system model.

Typical drift types:

- **token drift**: hardcoded values that bypass the token layer
- **preset drift**: manual overrides of canonical configurations
- **pattern drift**: incorrect composition or sequence

### Compliance mode
A policy posture controlling strictness of AI and developer workflows.

Common progression:

- **Observe**: measure
- **Assist**: recommend
- **Guard**: strong warnings + constrained generation
- **Enforce**: hard blocks + explicit approvals

### Proposal
A structured change suggestion that is reviewed before becoming canonical.

Typical flow:

1. generate / propose
2. validate
3. approve
4. apply

### System intelligence
The combination of canonical model + usage data + policy + MCP tooling that lets preset AI make context-aware recommendations and constraints.

## Product surfaces

The app groups the platform into four areas:

- **Studios**: compose domain-specific assets (tokens, typography, icons, color, content)
- **Rules**: define cross-domain enforcement artifacts (presets, patterns, interactions, recipes)
- **Health**: monitor quality and drift
- **Distribute**: connect tools and deliver system outputs

## Creation vs. consumption

preset AI separates:

- **creation**: defining and evolving system assets
- **consumption**: using those assets in code, AI tools, CI, and docs

This separation is key to scale: teams can move fast on creation without losing governance, and consumers always read from the canonical layer.

---

# Why the memory layer matters

Source: https://presetai.dev/docs/memory-layer
Type: concept
Summary: Why longitudinal memory beats snapshot for design systems in the AI age.
Last updated: 2026-05-11
Related: Scan your repo (https://presetai.dev/docs/scan), Agent resources (https://presetai.dev/docs/agent-resources)

---
owner: jschuyler
updated: '2026-05-11'
status: stable
---

export const metadata = {
  title: 'Why the memory layer matters',
  description: 'Design systems used to be snapshots. AI coding tools require memory. This is the difference that matters most.',
  type: 'concept',
  summary: 'Why longitudinal memory beats snapshot for design systems in the AI age.',
  last_updated: '2026-05-11',
  related: ['/scan', '/agent-resources'],
}

export const sections = [
  { title: 'Snapshot vs. memory', id: 'snapshot-vs-memory' },
  { title: 'What memory unlocks', id: 'what-memory-unlocks' },
  { title: 'How preset AI stores memory', id: 'how-preset-ai-stores-memory' },
  { title: "What's next", id: 'whats-next' },
]

# Why the memory layer matters

A design system used to be a snapshot: a set of tokens, components, and documentation frozen at the point a team wrote them down. That worked when humans were the only ones reading it. It does not work when agents are writing against it all day.

## Snapshot vs. memory

A snapshot is a point-in-time artifact. Figma libraries, static docs sites, shared style guides: they all describe how the system looked when someone described it. They carry no direction, no sequence, no record of what changed or why.

A memory is longitudinal. It records not just the current state but the history that led there: what superseded what, which decisions held, which drifted, where the pattern was adopted and where it was skipped. Memory gives an agent, or a reviewer, a way to reason about the system across time, not just a frozen frame.

## What memory unlocks

Concretely, the memory layer gives preset AI four capabilities a snapshot can't:

- **Identity across change.** When a token is renamed or a preset splits, the memory tracks the lineage. An agent referencing the old name still resolves correctly.
- **Drift as a signal, not a bug.** The memory knows what used to be canonical. When an agent deviates, preset AI can tell the difference between a deliberate change and a mistake.
- **Governance that ages well.** Forbidden primitives, context rules, and enforcement decisions carry their own history. A new team member sees the reason, not just the rule.
- **Deprecation without erasure.** Removing a pattern does not delete its record. The supersession is preserved, and every agent that encounters the old name gets pointed at the replacement.

## How preset AI stores memory

The memory is a typed, versioned graph. Every artifact (preset, pattern, token, rule) has a stable identity independent of its current name or location. Edges record supersession, composition, and usage. The graph is queryable via MCP, shipped to every agent in your stack.

This is the move that separates preset AI from smarter prompt pasting. A prompt is a snapshot an agent takes home; the memory is a shared surface an agent returns to every time it works.

<Note>
If you are familiar with design tokens as a format (Style Dictionary, Design Tokens Community Group), preset AI is the layer above: it treats your tokens as one kind of memory and adds identity, history, and governance to the rest of your system.
</Note>

## What's next

<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-3 mt-6">
  <a href="/docs/scan" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Scan your repo</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Point the scanner at your codebase and get a first pass at your memory layer.</p>
  </a>
  <a href="/docs/" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Overview</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">What is preset AI</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Back to the overview.</p>
  </a>
</div>

---

# CI integration

Source: https://presetai.dev/docs/platform/ci-cd/ci-integration
Type: guide
Summary: Three ways to add preset AI to CI: GitHub Action (one-line), CLI for other systems, SARIF for security tools. Full configs for GitHub/GitLab/CircleCI/Jenkins.
Last updated: 2026-05-12
Related: Validate in PR (https://presetai.dev/docs/platform/ci-cd/validate-in-pr), Active guardrails (https://presetai.dev/docs/compliance/active-guardrails)
Install: curl -fsSL https://presetai.dev/install.sh | sh

---
owner: jschuyler
updated: '2026-06-20'
status: stable
---

export const metadata = {
  title: 'CI integration',
  description: 'Integrate preset AI into your CI/CD pipeline: GitHub Action, CLI commands, SARIF for GitHub Code Scanning.',
  type: 'guide',
  summary: 'Three ways to add preset AI to CI: GitHub Action (one-line), CLI for other systems, SARIF for security tools. Full configs for GitHub/GitLab/CircleCI/Jenkins.',
  last_updated: '2026-05-12',
  related: ['/platform/ci-cd/validate-in-pr', '/compliance/active-guardrails'],
  install_command: 'curl -fsSL https://presetai.dev/install.sh | sh',
}

export const sections = [
  { title: 'Overview', id: 'overview' },
  { title: 'GitHub Action', id: 'github-action' },
  { title: 'CLI integration', id: 'cli-integration' },
  { title: 'SARIF integration', id: 'sarif-integration' },
  { title: 'Example CI configurations', id: 'example-ci-configurations' },
  { title: 'Best practices', id: 'best-practices' },
  { title: 'Troubleshooting', id: 'troubleshooting' },
]

# CI integration

Integrate preset AI into your CI/CD pipeline to enforce design system consistency automatically.

## Overview

preset AI provides three ways to integrate with your CI pipeline:

1. **GitHub Action**: one-line setup for GitHub repos
2. **CLI commands**: direct CLI usage in any CI system
3. **SARIF output**: GitHub Code Scanning integration

## GitHub Action

The easiest way to add preset AI to your workflow.

### Quick setup

Create `.github/workflows/preset.yml`:

```yaml
name: Design System Check

on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write   # post the results comment
  id-token: write        # mint the per-run OIDC token (recommended auth)

jobs:
  preset:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check design system
        uses: preset-ai/compliance-check@v1
        with:
          design-system-id: ${{ secrets.PRESET_DESIGN_SYSTEM_ID }}
```

### What it does

On every pull request, the action validates the changed files against your design system and:

1. **Flags violations**: native elements where a preset exists, hardcoded colors, arbitrary spacing, forbidden primitives, and token misuse
2. **Annotates the diff and posts a PR comment**: results land inline and in a single updating comment
3. **Fails on errors**: blocks merge when errors are found (configurable; warnings do not fail by default)

It checks changed `.tsx`, `.jsx`, `.ts`, `.vue`, and `.svelte` files by default. There is no command to choose: the action always runs design-system validation. (The `drift`, `scan`, and `audit-copy` workflows below are CLI commands, for non-GitHub CI.)

### Authentication

The recommended path is keyless OIDC: install the [Preset GitHub App](https://github.com/apps/preset-ai) (binding it to your design system during install) and set `permissions: id-token: write`. The action mints a fresh OIDC token per run, scoped to your repo, so there is no secret to rotate. If your runner cannot grant `id-token: write`, fall back to an API key: `preset-api-key: ${{ secrets.PRESET_API_KEY }}`.

### Configuration options

```yaml
- uses: preset-ai/compliance-check@v1
  with:
    design-system-id: ${{ secrets.PRESET_DESIGN_SYSTEM_ID }}

    # Full DB-backed validation (optional; scopes the design system)
    supabase-url: ${{ secrets.PRESET_SUPABASE_URL }}
    supabase-key: ${{ secrets.PRESET_SUPABASE_ANON_KEY }}

    # Which files to check (defaults shown)
    include: '**/*.tsx,**/*.jsx,**/*.ts,**/*.vue,**/*.svelte'
    exclude: '**/node_modules/**'

    # Gating
    fail-on-errors: 'true'        # default
    fail-on-warnings: 'false'     # default
    score-threshold: '0'          # min health score to pass (0 = off)
    regression-threshold: '0'     # max score drop vs the last snapshot (0 = off)

    # Surfaces
    comment-on-pr: 'true'         # default
    upload-sarif: 'false'         # GitHub Code Scanning

    # API-key fallback (only if not using the OIDC App)
    preset-api-key: ${{ secrets.PRESET_API_KEY }}
```

## CLI integration

For non-GitHub CI systems or custom pipelines.

### Installation

```bash
curl -fsSL https://presetai.dev/install.sh | sh
```

### Commands

#### Drift detection

```bash
# Table output (human-readable)
preset drift src

# JSON output (for parsing)
preset drift src --format json --output drift.json

# SARIF output (for security tools)
preset drift src --format sarif --output drift.sarif

# With custom presets
preset drift src --presets ./my-presets.json

# Strict mode (exit 1 on any drift)
preset drift src --strict
```

#### Pattern scanning

```bash
# Find patterns in codebase
preset scan src

# JSON output with compliance score
preset scan src --format json --output scan.json

# Adjust threshold
preset scan src --threshold 5
```

#### Copy audit

```bash
# Check terminology
preset audit-copy src --config terminology.json

# SARIF output
preset audit-copy src --format sarif --output copy.sarif

# Strict mode
preset audit-copy src --strict
```

### Exit codes

| Code | Meaning |
|---|---|
| 0 | Success, no violations |
| 1 | Violations found (with `--strict`) or error |

### JSON output structure

#### Drift report

```json
{
  "driftScore": 25,
  "hasDrift": true,
  "summary": {
    "totalComponents": 156,
    "usingPresets": 142,
    "withDrift": 8,
    "unknown": 6
  },
  "instances": [
    {
      "file": "src/components/Button.tsx",
      "line": 15,
      "column": 5,
      "component": "Button",
      "severity": "warning",
      "driftType": "prop_override",
      "actualProps": { "variant": "primary" },
      "expectedPreset": "primary-action",
      "expectedProps": { "variant": "default" },
      "suggestedFix": "Use preset 'primary-action' instead"
    }
  ]
}
```

#### Scan report

```json
{
  "meta": {
    "fileCount": 42,
    "duration": 1234
  },
  "summary": {
    "filesScanned": 42,
    "totalUsages": 156,
    "patternsDetected": 12,
    "proposalsGenerated": 8
  },
  "score": 85,
  "proposals": [
    {
      "name": "primary-button",
      "component": "Button",
      "props": { "variant": "default" },
      "usageCount": 24,
      "confidence": 0.92
    }
  ]
}
```

## SARIF integration

SARIF (Static Analysis Results Interchange Format) enables integration with GitHub Code Scanning and other security tools.

### GitHub Code Scanning

Upload SARIF results to see violations in the Security tab:

```yaml
- name: Run preset AI drift
  run: preset drift src --format sarif --output results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
    category: preset-drift
```

### SARIF structure

preset AI generates SARIF 2.1.0 compliant output:

```json
{
  "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
  "version": "2.1.0",
  "runs": [{
    "tool": {
      "driver": {
        "name": "preset-drift",
        "rules": [
          {
            "id": "drift/prop-override",
            "name": "PropOverride",
            "shortDescription": { "text": "Component props override preset" }
          }
        ]
      }
    },
    "results": [
      {
        "ruleId": "drift/prop-override",
        "level": "warning",
        "message": { "text": "Use preset 'primary-action' instead" },
        "locations": [{
          "physicalLocation": {
            "artifactLocation": { "uri": "src/Button.tsx" },
            "region": { "startLine": 15, "startColumn": 5 }
          }
        }]
      }
    ]
  }]
}
```

## Example CI configurations

### GitHub Actions (full)

```yaml
name: Design System

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read
  pull-requests: write   # post the results comment
  id-token: write        # mint the per-run OIDC token (recommended auth)
  security-events: write # upload SARIF to Code Scanning

jobs:
  preset:
    name: Design system check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: preset-ai/compliance-check@v1
        id: preset
        with:
          design-system-id: ${{ secrets.PRESET_DESIGN_SYSTEM_ID }}
          upload-sarif: 'true'
      - name: Report score
        if: always()
        run: |
          echo "Design system score: ${{ steps.preset.outputs.health-score }}/100 (${{ steps.preset.outputs.health-grade }})"
```

To also run drift detection, terminology, or pattern analysis in CI, add CLI steps (see [CLI integration](#cli-integration) above): `preset drift src --strict` and `preset audit-copy src`.

### GitLab CI

```yaml
preset-drift:
  stage: test
  image: node:20
  script:
    - curl -fsSL https://presetai.dev/install.sh | sh
    - preset drift src --format json --output drift.json --strict
  artifacts:
    reports:
      dotenv: drift.json
    when: always

preset-copy:
  stage: test
  image: node:20
  script:
    - curl -fsSL https://presetai.dev/install.sh | sh
    - preset audit-copy src --config terminology.json --strict
```

### CircleCI

```yaml
version: 2.1

jobs:
  preset-check:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install preset AI CLI
          command: curl -fsSL https://presetai.dev/install.sh | sh
      - run:
          name: Run drift check
          command: preset drift src --format sarif --output results.sarif --strict
      - store_artifacts:
          path: results.sarif

workflows:
  main:
    jobs:
      - preset-check
```

### Jenkins

```groovy
pipeline {
    agent { docker { image 'node:20' } }

    stages {
        stage('Design system check') {
            steps {
                sh 'curl -fsSL https://presetai.dev/install.sh | sh'
                sh 'preset drift src --format json --output drift.json'
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'drift.json'
        }
    }
}
```

## Best practices

### Start with warnings, graduate to errors

Begin with `fail-on-errors: false` to see the scope of issues without blocking merges, then tighten:

```yaml
# Phase 1: visibility (the comment posts; nothing fails the build)
fail-on-errors: 'false'
comment-on-pr: 'true'

# Phase 2: enforcement
fail-on-errors: 'true'
```

### Use SARIF for tracking

Upload SARIF to track trends over time in GitHub's Security tab.

### Run on push to main

Run the check on push to main (not just PRs) so each merge records a health snapshot. That snapshot is the baseline `regression-threshold` and `fail-on-new-only` compare against on later PRs:

```yaml
on:
  push:
    branches: [main]

jobs:
  preset:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: preset-ai/compliance-check@v1
        with:
          design-system-id: ${{ secrets.PRESET_DESIGN_SYSTEM_ID }}
          fail-on-errors: 'false'   # observe on main; do not block the push
```

### Version-control your presets and terminology

The CLI `drift` and `audit-copy` commands read local config you keep in the repo:

```
project/
├── src/
├── design-system/
│   ├── presets.json      # passed to `preset drift --presets`
│   └── terminology.json  # passed to `preset audit-copy --config`
└── .github/
    └── workflows/
        └── preset.yml
```

### Staged file checks

For pre-commit hooks, use the `--staged` flag:

```bash
preset scan --staged --format json
```

## Troubleshooting

### "No presets found"

The drift command uses default presets if none are provided. To point it at your own:

```bash
preset drift src --presets ./path/to/presets.json
```

### "SARIF upload failed"

Ensure your workflow has the required permission:

```yaml
permissions:
  security-events: write
```

### "PR comment not appearing"

Check that:

1. Event is `pull_request` (not `push`)
2. Token has `pull-requests: write` permission
3. `comment-on-pr` is `'true'` (string, not boolean)

### "CLI command not found"

The `preset` binary is not on your `PATH`. Install it:

```bash
curl -fsSL https://presetai.dev/install.sh | sh
```

If the installer placed it in `~/.local/bin`, add that directory to your `PATH`.

---

# Validate in PR

Source: https://presetai.dev/docs/platform/ci-cd/validate-in-pr
Type: guide
Summary: Run drift + audit-copy + scan in PR; emit JSON/SARIF; block on configured severity. Rollout: Observe → Assist → Enforce.
Last updated: 2026-05-12
Prerequisites: CI integration (https://presetai.dev/docs/platform/ci-cd/ci-integration)
Related: CI integration (https://presetai.dev/docs/platform/ci-cd/ci-integration), Active guardrails (https://presetai.dev/docs/compliance/active-guardrails)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Validate in PR',
  description: 'Focused guide for enforcing preset AI checks in pull requests: catch drift and policy violations before merge.',
  type: 'guide',
  summary: 'Run drift + audit-copy + scan in PR; emit JSON/SARIF; block on configured severity. Rollout: Observe → Assist → Enforce.',
  last_updated: '2026-05-12',
  prerequisites: ['/platform/ci-cd/ci-integration'],
  related: ['/platform/ci-cd/ci-integration', '/compliance/active-guardrails'],
}

export const sections = [
  { title: 'Objective', id: 'objective' },
  { title: 'Baseline checks', id: 'baseline-checks' },
  { title: 'Recommended PR workflow', id: 'recommended-pr-workflow' },
  { title: 'Example command set', id: 'example-command-set' },
  { title: 'Suggested policy thresholds', id: 'suggested-policy-thresholds' },
  { title: 'Rollout strategy', id: 'rollout-strategy' },
  { title: 'Outputs to keep', id: 'outputs-to-keep' },
]

# Validate in PR

A focused guide for enforcing preset AI checks in pull requests.

## Objective

Catch design-system drift and policy violations before merge.

## Baseline checks

Run at least one of:

- drift detection: `preset drift`
- copy and policy checks: `preset audit-copy` (where applicable)
- scan and proposal reporting: `preset scan` (for discovery workflows)

## Recommended PR workflow

1. Run checks on every pull request
2. Emit machine-readable output (`json` and/or `sarif`)
3. Surface findings directly in the PR
4. Block merge on configured severity thresholds

## Example command set

```bash
preset drift src --strict --format sarif --output drift.sarif
preset drift src --format json --output drift.json
```

Optional:

```bash
preset audit-copy src --strict --format sarif --output copy.sarif
```

## GitHub-oriented implementation

Use either:

- the preset AI GitHub Action (see [CI integration](/platform/ci-cd/ci-integration))
- direct CLI commands in workflow steps

Minimum expectations:

- PR comment or annotations with violations
- upload SARIF when available
- clear pass/fail signal for branch protection

## Suggested policy thresholds

- **Enforce mode repos**: fail on any high-severity violation
- **Assist / Guard repos**: fail on critical, warn on medium/low
- **Legacy repos**: warn-only initial rollout, then tighten

## Rollout strategy

1. **Observe**: report only
2. **Assist**: warn + remediation guidance
3. **Enforce**: block merge for policy-breaking drift

## Outputs to keep

Store artifacts for traceability:

- SARIF report
- JSON report
- summary metrics (drift score trend, violations by category)

For the full GitHub Action / CLI / SARIF reference, see [CI integration](/platform/ci-cd/ci-integration).

---

# Ingestion overview

Source: https://presetai.dev/docs/platform/ingestion
Type: reference
Summary: External sources are inputs, not the long-term source of truth. Flow: external → normalization → canonical → governance + distribution.
Last updated: 2026-05-12
Related: /platform/api (https://presetai.dev/docs/platform/api), Importing design systems (https://presetai.dev/docs/importing-design-systems)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Ingestion overview',
  description: 'How external systems (Figma, codebases, Storybook, ecosystems) flow into preset AI\'s canonical model.',
  type: 'reference',
  summary: 'External sources are inputs, not the long-term source of truth. Flow: external → normalization → canonical → governance + distribution.',
  last_updated: '2026-05-12',
  related: ['/platform/api', '/importing-design-systems'],
}

export const sections = [
  { title: 'Why ingestion matters', id: 'why-ingestion-matters' },
  { title: 'Ingestion principle', id: 'ingestion-principle' },
  { title: 'Primary ingestion pathways', id: 'primary-ingestion-pathways' },
  { title: 'What ingestion must preserve', id: 'what-ingestion-must-preserve' },
  { title: 'Governance checkpoints', id: 'governance-checkpoints' },
]

# Ingestion overview

How external systems flow into preset AI's canonical model.

## Why ingestion matters

Most teams are not starting from zero. They begin from:

- Figma variables and component styles
- existing codebases
- Storybook libraries
- third-party ecosystems (for example, shadcn/ui, Carbon)

preset AI ingestion should accelerate standardization without forcing a full rebuild.

## Ingestion principle

External sources are inputs, not the long-term source of truth.

```
external source → normalization → canonical model → governance + distribution
```

## Primary ingestion pathways

### Figma

- variables, styles, and components imported and mapped to tokens and presets
- drift detected via comparison workflows

### Codebase / GitHub

- scan component usage and infer patterns and preset candidates
- detect drift and adoption gaps

### Storybook

- extract component APIs and usage examples
- map to preset AI artifacts and the enforcement model

### Ecosystem / template starts

- map existing conventions to the semantic preset AI taxonomy
- identify where direct import vs. guided migration is safer

## What ingestion must preserve

- source provenance
- confidence of mappings
- explicit unresolved items requiring human review
- safe change boundaries before apply

## Governance checkpoints

Before imported artifacts become canonical defaults:

- naming normalization
- token / preset semantic quality checks
- pattern and policy alignment
- proposal + validation + approval workflow where needed

See [Importing design systems](/importing-design-systems) for the user-facing import flow and [API overview](/platform/api) for the underlying surfaces.

---

# Claude Code integration

Source: https://presetai.dev/docs/platform/integrations/claude-code
Type: guide
Summary: CLAUDE.md snippet to attach preset AI MCP usage, plus installing the skill family (guidance skill, write-time hook, and slash utilities) materialized from your live design system. Validated end-to-end on inline hex, all-caps tracking, off-grid spacing, inline styles.
Last updated: 2026-06-18
Related: Claude Code with preset AI (https://presetai.dev/docs/ai-coding-tools/claude-code), Cursor integration (https://presetai.dev/docs/platform/integrations/cursor), OpenAI Codex integration (https://presetai.dev/docs/platform/integrations/codex)
Install: claude mcp add --transport http preset https://mcp.presetai.dev/mcp

---
owner: jschuyler
updated: '2026-06-20'
status: stable
---

export const metadata = {
  title: 'Claude Code integration',
  description: 'Wire preset AI into Claude Code via MCP + CLAUDE.md so the agent calls preset AI on UI work.',
  type: 'guide',
  summary: 'CLAUDE.md snippet to attach preset AI MCP usage, plus installing the skill family (guidance skill, write-time hook, and slash utilities) materialized from your live design system. Validated end-to-end on inline hex, all-caps tracking, off-grid spacing, inline styles.',
  last_updated: '2026-06-18',
  related: ['/ai-coding-tools/claude-code', '/platform/integrations/cursor', '/platform/integrations/codex'],
  install_command: 'claude mcp add --transport http preset https://mcp.presetai.dev/mcp',
}

export const sections = [
  { title: 'CLAUDE.md setup', id: 'claudemd-setup' },
  { title: 'Install the skill family', id: 'install-the-skill-family' },
  { title: 'What this catches', id: 'what-this-catches' },
  { title: 'How it works', id: 'how-it-works' },
  { title: 'FAQ', id: 'faq' },
]

# Claude Code integration

> Claude Code generates and edits code. preset AI makes that code design-system-aware.

Claude Code is Anthropic's coding agent: a CLI binary that reads your repo, writes code, and runs tools. On its own, the agent has no vocabulary for your design system: it sees `bg-[#0a0a0a]` and might propose semantic-looking alternatives that don't actually exist in your token catalog. Connect preset AI's MCP server and Claude Code validates against your tokens, cites your rules by name, and proposes fixes from your canonical preset library.

This page is the **setup config**. For the operating loop, prompting pattern, and team policy, see [Claude Code operating guide](/ai-coding-tools/claude-code).

## CLAUDE.md setup

Claude Code reads `CLAUDE.md` at the start of each session. To make sure the agent calls preset AI on UI work, append this block to your project's `CLAUDE.md` (or create one if it doesn't exist):

```markdown
## preset AI MCP: design system enforcement

When working on UI components, Tailwind classes, CSS, or design tokens:

1. Before writing or suggesting UI code, call `validate_code` from the preset AI
   MCP server to check it against the active design system. Cite the returned
   `ruleId` and `fix` fields verbatim in your response.
2. When the user shares a hex color, px value, or arbitrary Tailwind value
   (e.g. `bg-[#0a0a0a]`, `p-[17px]`), call `resolve_value` to get the
   canonical token name or closest alternatives.
3. When generating new components or files, call
   `get_active_constraints(filePath)` first to learn path-scoped rules.
4. Before introducing a new utility or class, check `get_forbidden_primitives()`.

Always cite preset AI rule names (e.g. `no-uppercase`, `no-inline-hex-color`,
`ai-slop-arbitrary-spacing`) when explaining design system violations.
```

This pattern was validated on Cursor (`.cursor/rules/preset.mdc`) and Codex (`AGENTS.md`): `CLAUDE.md` is the Claude Code equivalent.

## Install the skill family

The MCP connection above lets the agent call preset AI when it judges a tool relevant. The skill family goes further: it materializes your design system into Claude Code skills that load before the agent writes UI, enforce on write, and answer on demand. It is the same shape as Stripe's `stripe-best-practices` skill, except the payload is your live design system, not static vendor docs.

{/* TODO(PRE-1555): asciinema recording of the export + a UI write triggering preset-best-practices. */}

### Install

Run this in your project, with preset AI connected (OAuth, or a `pk_live_` key for headless use):

```bash
preset skills export --skill-family preset
```

This fetches your live design system and writes the skills into `.claude/skills/`:

- `preset-best-practices/`: the guidance skill. Loads your ranked principles, named anti-patterns, forbidden primitives, and recommended presets when you build or edit UI. You do not invoke it; it fires on UI work.
- `preset-check/`: `/preset:check [file]` validates a file against your design system.
- `preset-tokens/`: `/preset:tokens` shows your token reference.
- `preset-explain/`: `/preset:explain <principle>` explains one of your principles in full.
- `preset-propose-preset/`: `/preset:propose-preset` proposes a new preset from the current component.

A `manifest.json` records what was materialized. `preset doctor` reads it offline to report the materialized skills, their age, and the template version; to check the snapshot against your live design system, use `preset skills export --skill-family preset --check`.

### Verify

1. Open a UI file (a `.tsx` component) and ask Claude Code to make a change. The `preset-best-practices` skill loads your doctrine into the agent's context before it writes.
2. Run `/preset:tokens` in Claude Code. It returns your token reference on demand.
3. Run `preset doctor`. It reports the materialized skills, their age, and the current enforcement mode.

### The enforcement lever

One field in `.presetrc` governs how strict the family is, consistently across the skill, the write-time hook, and CI:

```jsonc
// .presetrc
{ "designSystem": "your-ds-slug", "mode": "advisory", "skipPaths": ["src/legacy/**"] }
```

- `advisory` (the default): the agent sees findings; nothing blocks.
- `warn`: findings plus a "not yet fixed" note; still nothing blocks.
- `enforce`: the PreToolUse hook blocks a write that carries an error-severity violation, and CI fails the check.

Start on `advisory` to feel the gate without friction, then flip to `enforce` when your team is ready. `preset doctor` nudges you once the family has been advisory for a while. `preset init` seeds `.presetrc` at `advisory` for you.

### Refresh after design system changes

The materialized body is a snapshot. When you change principles, tokens, or rules, re-run the export:

```bash
preset skills export --skill-family preset
```

`preset doctor` is offline: it reports the snapshot's age and template version and reminds you to verify, but it does not detect principle or token edits on its own. The live check is `preset skills export --skill-family preset --check`, which exits non-zero when the snapshot is behind your design system, so it doubles as a CI gate.

### Troubleshooting

**The skill is not firing on UI work.** Confirm `.claude/skills/preset-best-practices/SKILL.md` exists (re-run the export if not), and that you are editing a UI file (`.tsx` / `.jsx` / `.vue` / `.svelte` under a components path). The skill deliberately skips tests, docs, config, and server-only files.

**The hook is not blocking in enforce mode.** The PreToolUse hook ships with the plugin and shells to the `preset` CLI, so make sure `preset` is on your PATH (`curl -fsSL https://presetai.dev/install.sh | sh`) and `.presetrc` `mode` is `enforce`. If preset AI is unreachable, the hook falls back to a local check and never blocks on a connection failure.

**A slash command says it cannot reach preset AI.** The utilities work offline against the materialized body and fall back to the live MCP when available. If a command needs live data (token values, the freshest principle copy) while you are offline, re-run the export when you are connected.

To declare the principles and anti-patterns this family materializes, see the design system's **Principles** section in the preset AI dashboard.

## What this catches

Tested end-to-end. Sample violations and the agent's response when `validate_code` fires:

| Violation | preset AI MCP returns | Claude Code agent renders |
|---|---|---|
| `<div className="bg-[#0a0a0a]">` | `no-inline-hex-color`, `severity: warning`, fix: "Use CSS variable" | "Hit on `#0a0a0a`: use `var(--color-surface)`" |
| `<span className="uppercase tracking-widest">BETA</span>` | `no-uppercase`, hits on `uppercase` and `tracking-widest` | "Use sentence case + size/weight hierarchy: `text-xs font-medium text-[var(--color-text-secondary)]`" |
| `<div className="p-[17px]">` | `ai-slop-arbitrary-spacing`, `forbidden_primitive` | "Off-grid spacing: use `p-4` from the spacing scale" |
| `style={{ backgroundColor: '#00aaff' }}` | `no-inline-hex-color` | "Saturated cyan `#00aaff` is specifically out of system" |

## How it works

### OAuth vs API key

**OAuth (recommended)**: Each Claude Code user authenticates individually. Tokens refresh automatically. Best for individuals and teams.

```bash
claude mcp add --transport http preset https://mcp.presetai.dev/mcp
```

**API key (Bearer)**: Generate a `pk_live_*` key at [presetai.dev/api](https://presetai.dev/api) and pass it as the Authorization header:

```bash
claude mcp add --transport http preset https://mcp.presetai.dev/mcp \
  --header "Authorization: Bearer pk_live_xxx"
```

Best for shared-account or CI setups where browser-based OAuth isn't viable.

### Tool scoping

Claude Code's agent has access to all of preset AI's MCP tools by default and chooses which to call based on the task. Like Cursor and Codex, Claude Code is IDE-class: it benefits from the full tool surface (generation + validation + lookup), not the narrowed 7-tool review profile that PR-review clients (e.g. CodeRabbit) use.

### Data flow

When Claude Code's agent calls a preset AI tool, it sends the file path, code snippet, and any inferred intent. preset AI resolves the active design system's rules: forbidden primitives, context rules, tokens, presets, scoped by layer if configured, and returns structured results. Claude Code renders these inline and applies suggested fixes if you accept them.

No code is stored on preset AI's side. Queries are processed in real time and logged to the design system's audit trail, not Anthropic's.

## FAQ

**Which Claude plan do I need?**

Any Claude plan that includes Claude Code works. preset AI is plan-agnostic on the Anthropic side: your preset AI connection authenticates against your preset AI account, not your Anthropic subscription tier.

**Does this work in Claude Desktop?**

Yes. Claude Desktop supports MCP servers via `claude_desktop_config.json`. The configuration is slightly different from Claude Code; see preset AI's in-app **Connect → Claude Desktop** section for the desktop-specific snippet.

**How do I revoke Claude Code's access?**

Two paths. From Claude Code: `claude mcp remove preset`. From preset AI: **Connect → Active integrations**, find the Claude Code entry, revoke. Either revokes the refresh token immediately.

**What's the difference between the MCP install and the plugin install?**

The MCP install (`claude mcp add ...`) registers preset AI as an MCP server. Claude Code's agent can then call its tools when it judges them relevant. The plugin install (`claude plugin install ...`) does that **plus** registers slash commands (`/preset:check`, `/preset:tokens`), pre-write validation hooks, and auto-injects design-system rules. The plugin is richer; the MCP-only path is simpler.

**Why does the agent sometimes ignore preset AI and read local docs instead?**

Claude Code's agent picks the cheapest path to an answer. If your repo already has `CLAUDE.md`, `tokens.css`, or design-system docs that cover the same ground, it may read those instead of calling preset AI. The recommended `CLAUDE.md` snippet above tells the agent when preset AI is the authoritative source.

**What gets logged?**

Every MCP call from Claude Code is logged to preset AI's audit trail with client ID, tool name, and timestamp: queryable from the preset AI dashboard. OAuth events (token issuance, refresh, revocation) are captured in the `oauth_events` telemetry table.

---

# CodeRabbit integration

Source: https://presetai.dev/docs/platform/integrations/coderabbit
Type: guide
Summary: CodeRabbit + preset AI MCP turns generic 
Last updated: 2026-05-12
Related: CI integration (https://presetai.dev/docs/platform/ci-cd/ci-integration), OpenAI Codex integration (https://presetai.dev/docs/platform/integrations/codex), v0 by Vercel integration (https://presetai.dev/docs/platform/integrations/v0)

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'CodeRabbit integration',
  description: 'Wire preset AI into CodeRabbit so PR reviews cite your design tokens by name and propose token-aware diff fixes.',
  type: 'guide',
  summary: 'CodeRabbit + preset AI MCP turns generic "use a theme color" feedback into named-rule citations with diff-format fixes. 7-tool review profile.',
  last_updated: '2026-05-12',
  related: ['/platform/ci-cd/ci-integration', '/platform/integrations/codex', '/platform/integrations/v0'],
}

export const sections = [
  { title: 'The workflow', id: 'the-workflow' },
  { title: 'Quick start', id: 'quick-start' },
  { title: 'What this catches', id: 'what-this-catches' },
  { title: 'How it works', id: 'how-it-works' },
  { title: 'FAQ', id: 'faq' },
]

# CodeRabbit integration

> CodeRabbit reviews PRs. preset AI makes those reviews design-system-aware.

CodeRabbit is an AI code reviewer that posts inline comments on every pull request. On its own, it catches generic code issues but has no vocabulary for your design system: it sees `bg-[#0a0a0a]` and suggests "use a theme color" without knowing your tokens exist. Connect preset AI's MCP server and the same review cites your tokens by name, enforces your forbidden-primitive rules, and proposes fixes using your design system.

## The workflow

```
┌──────────────────────────────────────────────────────────────────┐
│  1. CONNECT        2. OPEN PR         3. REVIEW                  │
│  ─────────         ──────────         ──────────                 │
│  CodeRabbit        GitHub             CodeRabbit + preset AI     │
│                                                                  │
│  • Add preset AI   • Push code        • Inline comments          │
│    as MCP          • CodeRabbit       • Named rules              │
│  • Authorize         reviews          • Token suggestions        │
│    via OAuth       • With DS context  • Diff-format fixes        │
└──────────────────────────────────────────────────────────────────┘
```

## Quick start

### 1. Prerequisites

- **CodeRabbit Pro or Pro Plus** plan: MCP Server integrations require a paid tier. A 14-day trial is available at [coderabbit.ai](https://coderabbit.ai/pricing) and supports MCP.
- **preset AI account** with at least one active design system.

### 2. Add preset AI to CodeRabbit

In the CodeRabbit dashboard, go to **Integrations → MCP Servers → + New MCP Server**.

| Field | Value |
|---|---|
| **Label** | `preset AI` |
| **Server URL** | `https://mcp.presetai.dev/mcp` |
| **Authentication method** | `OAuth` (recommended) |
| **Additional headers** | *leave blank* |

### 3. Paste the usage guidance

CodeRabbit's review agent works best when it knows which of preset AI's tools to call during review. Paste this into the **Usage guidance** field:

```
Use this MCP to check code against the team's design system during PR review.

Recommended tools for PR review:
- validate_code(code, filePath): primary violation check. Returns structured
  violations with file, line, severity, rule name, human-readable `fix`, and
  machine-applicable `fixCode`.
- resolve_value(value): checks if a raw hex/px value matches a design token.
  Returns the canonical token name or 3 closest alternatives.
- get_forbidden_primitives(): patterns and elements that MUST NOT be used.
- get_active_constraints(filePath): path-scoped rules for the file being reviewed.
- quick_check_violations(code): fast boolean for PR-level summary.
- suggest_preset(intent): suggests the canonical preset for a piece of code.
- get_component_api(component): returns the props contract for a component.

When citing a violation in a review comment, quote the tool's `fix` and
`fixCode` fields verbatim and cite design tokens by their canonical name.
File:line is always in the response: map it to inline review comments.

Ignore generation-oriented tools (generate_code, figma_*, sync_*) during review.
```

### 4. Connect with OAuth

You'll be redirected to `app.presetai.dev` to authorize. Approve access and select the design system you want CodeRabbit to use during review. Tokens are stored securely by CodeRabbit; preset AI retains full control and can be revoked at any time from your Connect settings.

### 5. Open a pull request

Your next PR will receive inline annotations for design-system violations. Each comment includes a severity badge, the named rule being enforced, and a diff-format fix suggestion.

## What this catches

Tested end-to-end. Example violations and what the combined review produces:

| Violation in diff | Design-system-aware review comment |
|---|---|
| `<div className="bg-[#0a0a0a]">` | Major: cites `no-inline-hex-color` rule, suggests canonical token |
| `<span className="uppercase tracking-widest">BETA</span>` | Critical: cites `no-uppercase` rule, proposes font-hierarchy fix using your type scale |
| `<div className="p-[17px] gap-[11px]">` | Major: flags off-grid spacing, suggests tokens from your spacing scale |
| `style={{ backgroundColor: '#00aaff' }}` | Major: cites `no-inline-hex-color`, proposes CSS variable fix |
| `text-[var(--nonexistent-color)]` | Major: flags invalid CSS variable, suggests nearest valid token |

## How it works

### OAuth vs API key

**OAuth (recommended)**: Each user on the CodeRabbit team authenticates individually. No shared credentials, clean audit trail, tokens refresh automatically. Best for teams.

**API key**: Generate a `pk_live_*` key at [presetai.dev/api](https://presetai.dev/api), paste it in CodeRabbit's dashboard as the bearer token. CodeRabbit's own documentation notes that MCP credentials are shared across the organization, so this path is best for single-user setups or when scoped to a dedicated integration account.

### Tool scoping

CodeRabbit's agent has access to all of preset AI's MCP tools by default, but the usage guidance above directs it to call only the seven tools relevant for code review. You can verify this in CodeRabbit's dashboard under **Integrations → preset AI → Tools**.

### Data flow

When CodeRabbit reviews a PR, its agent calls preset AI's MCP tools with the file path, code diff, and any inferred intent. preset AI resolves the active design system's rules (forbidden primitives, context rules, tokens, presets), scoped by layer if configured, and returns structured violations. CodeRabbit renders these as inline review comments with severity and diff-format fixes.

No PR content is stored on preset AI's side: queries are processed in real time and logged to the design system's own audit trail, not CodeRabbit's.

## FAQ

**Does this work on PRs opened before preset AI was connected?**

CodeRabbit does not re-review already-reviewed commits. Existing open PRs won't pick up design-system-aware review automatically. To apply preset AI review to an existing PR, push a new commit (real diff) or close and reopen the PR.

**Which CodeRabbit plan do I need?**

MCP Server integrations require a paid plan. CodeRabbit Pro supports 5 MCP connections and Pro Plus supports 15. preset AI uses one slot. CodeRabbit offers a 14-day trial with MCP enabled: confirm current plan limits at [coderabbit.ai/pricing](https://coderabbit.ai/pricing).

**Can I use this with CodeRabbit's IDE extension too?**

Yes. Once preset AI is added as an MCP server in the CodeRabbit dashboard, it's available in both PR reviews and CodeRabbit's VS Code / JetBrains extensions.

**How do I revoke CodeRabbit's access?**

Two paths. From preset AI: **Connect → Active integrations**, find the CodeRabbit MCP Client entry, revoke. From CodeRabbit: **Integrations → MCP Servers → preset AI → Disconnect**. Either revokes the refresh token immediately.

**What gets logged?**

Every MCP call from CodeRabbit is logged to preset AI's audit trail with client ID, tool name, and timestamp. OAuth events (token issuance, refresh, revocation) are captured in the `oauth_events` telemetry table with structured reason codes.

---

# OpenAI Codex integration

Source: https://presetai.dev/docs/platform/integrations/codex
Type: guide
Summary: AGENTS.md snippet to attach preset AI MCP. Works across Codex CLI, desktop, and IDE extension. Native enabled_tools/disabled_tools for review profile scoping.
Last updated: 2026-05-12
Related: Claude Code integration (https://presetai.dev/docs/platform/integrations/claude-code), Cursor integration (https://presetai.dev/docs/platform/integrations/cursor), CodeRabbit integration (https://presetai.dev/docs/platform/integrations/coderabbit)

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'OpenAI Codex integration',
  description: 'Wire preset AI into OpenAI Codex via MCP + AGENTS.md so the agent calls preset AI on UI work.',
  type: 'guide',
  summary: 'AGENTS.md snippet to attach preset AI MCP. Works across Codex CLI, desktop, and IDE extension. Native enabled_tools/disabled_tools for review profile scoping.',
  last_updated: '2026-05-12',
  related: ['/platform/integrations/claude-code', '/platform/integrations/cursor', '/platform/integrations/coderabbit'],
}

export const sections = [
  { title: 'AGENTS.md setup', id: 'agentsmd-setup' },
  { title: 'What this catches', id: 'what-this-catches' },
  { title: 'How it works', id: 'how-it-works' },
  { title: 'FAQ', id: 'faq' },
]

# OpenAI Codex integration

> Codex generates and edits code. preset AI makes that code design-system-aware.

OpenAI Codex is a coding agent available as a CLI binary, a desktop app, and an IDE extension, all sharing the same configuration. On its own, Codex's agent reads your repo and writes code, but it has no vocabulary for your design system: it sees `bg-[#0a0a0a]` and might propose semantic-looking alternatives that don't actually exist in your token catalog. Connect preset AI's MCP server and Codex validates against your tokens, cites your rules by name, and proposes fixes from your canonical preset library.

## AGENTS.md setup

Codex's agent does not automatically prefer MCP tools when your repo already has design-system documentation in `AGENTS.md` or `CLAUDE.md`. To make sure the agent calls preset AI on UI work, append this block to your project's `AGENTS.md` (or create one if it doesn't exist):

```markdown
## preset AI MCP: design system enforcement

When working on UI components, Tailwind classes, CSS, or design tokens:

1. Before writing or suggesting UI code, call `validate_code` from the preset AI
   MCP server to check it against the active design system. Cite the returned
   `ruleId` and `fix` fields verbatim in your response.
2. When the user shares a hex color, px value, or arbitrary Tailwind value
   (e.g. `bg-[#0a0a0a]`, `p-[17px]`), call `resolve_value` to get the
   canonical token name or closest alternatives.
3. When generating new components or files, call
   `get_active_constraints(filePath)` first to learn path-scoped rules.
4. Before introducing a new utility or class, check `get_forbidden_primitives()`.

Always cite preset AI rule names (e.g. `no-uppercase`, `no-inline-hex-color`,
`ai-slop-arbitrary-spacing`) when explaining design system violations.
```

The block auto-attaches when Codex reads `AGENTS.md` at the start of a session.

## What this catches

Tested end-to-end. Sample violations and the agent's response when `validate_code` fires:

| Violation | preset AI MCP returns | Codex agent renders |
|---|---|---|
| `<div className="bg-[#0a0a0a]">` | `no-inline-hex-color`, `severity: warning`, fix: "Use CSS variable" | "Hit on `#0a0a0a`: use `var(--color-surface)`" |
| `<span className="uppercase tracking-widest">BETA</span>` | `no-uppercase`, hits on `uppercase` and `tracking-widest` | "Use sentence case + size/weight hierarchy: `text-xs font-medium text-[var(--color-text-secondary)]`" |
| `<div className="p-[17px]">` | `ai-slop-arbitrary-spacing`, `forbidden_primitive` | "Off-grid spacing: use `p-4` from the spacing scale" |
| `style={{ backgroundColor: '#00aaff' }}` | `no-inline-hex-color` | "Saturated cyan `#00aaff` is specifically out of system" |

The agent renders structured violations from preset AI (`rule`, `found`, `fix`, `severity`, `line`, `ruleId`) inline and typically follows up with a token-compliant rewrite.

## How it works

### OAuth vs API key

**OAuth (recommended)**, Each Codex user authenticates individually. Tokens refresh automatically. Codex implements OAuth metadata discovery, so the bare `url = "..."` config is enough, no client registration step required.

**API key (Bearer)**: Generate a `pk_live_*` key at [presetai.dev/api](https://presetai.dev/api), set it as an environment variable, then reference it in `config.toml`:

```toml
[mcp_servers.preset]
url = "https://mcp.presetai.dev/mcp"
bearer_token_env_var = "PRESET_API_KEY"
```

Best for shared-account or CI setups where browser-based OAuth isn't viable.

### Tool scoping

Codex's agent has access to all of preset AI's MCP tools by default and chooses which to call based on the task. Like Cursor, Codex is IDE-class: it benefits from the full tool surface (generation + validation + lookup), not the narrowed 7-tool review profile that PR-review clients use.

If you want a narrower surface, Codex supports native per-tool toggling via `enabled_tools` and `disabled_tools` in the server config:

```toml
[mcp_servers.preset]
url = "https://mcp.presetai.dev/mcp"
enabled_tools = ["validate_code", "quick_check_violations", "get_forbidden_primitives", "get_active_constraints", "resolve_value", "suggest_preset", "get_component_api"]
```

This scopes preset AI to the 7-tool review profile: useful if you're using Codex primarily for review-style tasks and want to suppress generation tools.

### Data flow

When Codex's agent calls a preset AI tool, it sends the file path, code snippet, and any inferred intent. preset AI resolves the active design system's rules: forbidden primitives, context rules, tokens, presets, scoped by layer if configured, and returns structured results. Codex renders these inline in the agent panel and applies suggested fixes if you accept them.

No code is stored on preset AI's side. Queries are processed in real time and logged to the design system's audit trail, not Codex's.

## FAQ

**Which Codex plan or surface do I need?**

Any Codex surface that supports MCP works: CLI, desktop app, and the IDE extension all read `~/.codex/config.toml`. preset AI is plan-agnostic on the Codex side: your preset AI connection authenticates against your preset AI account, not your OpenAI subscription tier.

**Does this work in Codex Cloud (`chatgpt.com/codex`)?**

OpenAI's documentation does not currently address whether the cloud-hosted Codex agent supports custom MCP servers. The CLI / desktop / IDE-extension paths are the confirmed surfaces. If you need preset AI enforcement in cloud Codex specifically, watch [developers.openai.com/codex](https://developers.openai.com/codex) for updates.

**How do I revoke Codex's access?**

Two paths. From Codex: open the desktop app → **Plugins → Manage → MCPs**, find preset AI, toggle off. From preset AI: **Connect → Active integrations**, find the Codex MCP Client entry, revoke. Either revokes the refresh token immediately.

**Why does the agent sometimes ignore preset AI and read local docs instead?**

Codex's agent picks the cheapest path to an answer. If your repo already has `AGENTS.md`, `CLAUDE.md`, `tokens.css`, or design-system docs that cover the same ground, it may read those instead of calling preset AI. The recommended `AGENTS.md` snippet above tells the agent when preset AI is the authoritative source.

**My project already has an AGENTS.md: will adding a preset AI section break anything?**

No. `AGENTS.md` is additive and section-based. Append the preset AI block as a new `## preset AI MCP: design system enforcement` section; existing sections (project layout, conventions, build commands, etc.) keep working. Codex reads the whole file.

**What's the difference between Plugins and MCPs in the Codex desktop app?**

Plugins are OpenAI's curated catalog (one-click install from the marketplace; examples: GitHub, Slack). MCPs are servers you've added to `config.toml` directly. Both surface in the same Manage view but live in different config sections (`[plugins.*]` vs `[mcp_servers.*]`).

**What gets logged?**

Every MCP call from Codex is logged to preset AI's audit trail with client ID, tool name, and timestamp. OAuth events (token issuance, refresh, revocation) are captured in the `oauth_events` telemetry table.

---

# Cursor integration

Source: https://presetai.dev/docs/platform/integrations/cursor
Type: guide
Summary: Cursor Rule (.cursor/rules/preset.mdc) tells the agent when preset AI is the authoritative source. Validated on inline hex, all-caps tracking, off-grid spacing.
Last updated: 2026-05-12
Related: Cursor with preset AI (https://presetai.dev/docs/ai-coding-tools/cursor), Claude Code integration (https://presetai.dev/docs/platform/integrations/claude-code), OpenAI Codex integration (https://presetai.dev/docs/platform/integrations/codex)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Cursor integration',
  description: 'Wire preset AI into Cursor via MCP + .cursor/rules/preset.mdc so the agent calls preset AI on UI work.',
  type: 'guide',
  summary: 'Cursor Rule (.cursor/rules/preset.mdc) tells the agent when preset AI is the authoritative source. Validated on inline hex, all-caps tracking, off-grid spacing.',
  last_updated: '2026-05-12',
  related: ['/ai-coding-tools/cursor', '/platform/integrations/claude-code', '/platform/integrations/codex'],
}

export const sections = [
  { title: 'Cursor Rule setup', id: 'cursor-rule-setup' },
  { title: 'What this catches', id: 'what-this-catches' },
  { title: 'How it works', id: 'how-it-works' },
  { title: 'FAQ', id: 'faq' },
]

# Cursor integration

> Cursor generates UI code. preset AI makes that code design-system-aware.

Cursor is an AI-first IDE whose agent writes code, refactors files, and answers questions about your repo. On its own, the agent has no vocabulary for your design system: it sees your repo's components but can invent off-token colors, off-grid spacing, or forbidden utilities without flagging them. Connect preset AI's MCP server and the same agent validates against your tokens before suggesting code, cites your rules by name when reviewing snippets, and proposes fixes from your canonical preset library.

This page is the **setup config**. For the operating workflow, prompting template, and team policy, see [Cursor operating guide](/ai-coding-tools/cursor).

## Cursor Rule setup

Cursor's agent does not automatically prefer MCP tools when your repo already has design-system documentation. To make sure the agent calls preset AI on UI work, drop a rule file at `.cursor/rules/preset.mdc` in your project:

```mdc
---
description: Validate UI code against the preset AI design system
globs: ["**/*.tsx", "**/*.jsx", "**/*.ts", "**/*.css", "**/*.scss"]
alwaysApply: false
---

When working on UI components, Tailwind classes, CSS, or design tokens:

1. Before writing or suggesting UI code, call `validate_code` from the preset AI
   MCP server to check it against the active design system. Cite the returned
   `ruleId` and `fix` fields verbatim in your response.
2. When the user shares a hex color, px value, or arbitrary Tailwind value
   (e.g. `bg-[#0a0a0a]`, `p-[17px]`), call `resolve_value` to get the
   canonical token name or closest alternatives.
3. When generating new components or files, call
   `get_active_constraints(filePath)` first to learn path-scoped rules.
4. Before introducing a new utility or class, check `get_forbidden_primitives()`.

Always cite preset AI rule names (e.g. `no-uppercase`, `no-inline-hex-color`,
`ai-slop-arbitrary-spacing`) when explaining design system violations.
```

This is Cursor's equivalent of the per-server usage guidance other MCP clients support. The rule auto-attaches to UI files and tells the agent when preset AI is the right tool to reach for.

## What this catches

Tested end-to-end. Sample violations and the agent's response when `validate_code` fires:

| Violation | preset AI MCP returns | Cursor agent renders |
|---|---|---|
| `<div className="bg-[#0a0a0a]">` | `no-inline-hex-color`, `severity: "warning"`, `fix: "Use canonical token"` | "Hit on `#0a0a0a`: use a CSS token variable" + diff |
| `<span className="uppercase tracking-widest">BETA</span>` | `no-uppercase`, hits on `uppercase` and `tracking-widest` | "Use hierarchy via size/weight (`text-xs font-medium`) instead of uppercase + tracking" |
| `<div className="p-[17px] gap-[11px]">` | `ai-slop-arbitrary-spacing`, `forbidden_primitive` | "Off-grid spacing: use `p-2`, `p-4` from the Tailwind spacing scale" |
| `style={{ backgroundColor: '#00aaff' }}` | `no-inline-hex-color` | "Saturated cyan `#00aaff` is specifically out of system" |

The agent renders the structured violations from preset AI (`rule`, `found`, `fix`, `severity`, `line`, `ruleId`) inline and typically follows up with a token-compliant rewrite.

## How it works

### OAuth vs API key

**OAuth (recommended)**, Each Cursor user authenticates individually. No shared credentials, clean audit trail, tokens refresh automatically. Cursor implements OAuth metadata discovery, so the bare `{"url": "..."}` config is enough, no client registration step required. Best for individuals and teams.

**API key**: Generate a `pk_live_*` key at [presetai.dev/api](https://presetai.dev/api) and pass it as a Bearer header. Best for shared-account or scripted setups. Replace your `mcpServers.preset` block with the `auth` form documented at [cursor.com/docs/mcp](https://cursor.com/docs/mcp).

### Tool scoping

Cursor's agent has access to all of preset AI's MCP tools by default and chooses which to call based on the task. Unlike review-only MCP clients (e.g. CodeRabbit), Cursor benefits from the full tool surface: generation tools (`generate_code`, `suggest_preset`), validation tools (`validate_code`, `quick_check_violations`), and lookup tools (`resolve_value`, `get_active_constraints`) all matter inside an IDE.

If you want a narrower surface, expand the chevron next to the tool count in **Settings → Tools & MCPs → preset** and toggle individual tools off.

### Data flow

When Cursor's agent calls a preset AI tool, it sends the file path, code snippet, and any inferred intent. preset AI resolves the active design system's rules: forbidden primitives, context rules, tokens, presets, scoped by layer if configured, and returns structured results. Cursor renders these inline in the agent panel and applies suggested fixes if you accept them.

No code is stored on preset AI's side. Queries are processed in real time and logged to the design system's audit trail, not Cursor's.

## FAQ

**Which Cursor plan do I need?**

Any plan, including Free. Cursor does not gate MCP server installation by plan tier.

**Do I need to install Cursor's CLI / `cursor` command for this to work?**

No. The MCP integration runs inside the Cursor desktop app. The `cursor` CLI is for launching the editor from the terminal and is independent of MCP.

**How do I revoke Cursor's access?**

Two paths. From Cursor: **Settings → Tools & MCPs → preset → Logout**. From preset AI: **Connect → Active integrations**, find the Cursor MCP Client entry, revoke. Either revokes the refresh token on preset AI's side immediately.

**Does this work in Cursor's terminal product or on cursor.com (Web)?**

The integration is validated for Cursor Desktop. Cursor's terminal agent and Web product surface MCP differently and are not yet covered. File a request if you need either.

**Why does the agent sometimes ignore preset AI and read local docs instead?**

Cursor's agent picks the cheapest path to an answer. If your repo already has `CLAUDE.md`, `AGENTS.md`, or design-system docs that cover the same ground, it may read those instead of calling preset AI. The recommended Cursor Rule above (`.cursor/rules/preset.mdc`) tells the agent when preset AI is the authoritative source.

**What gets logged?**

Every MCP call from Cursor is logged to preset AI's audit trail with client ID, tool name, and timestamp. OAuth events (token issuance, refresh, revocation) are captured in the `oauth_events` telemetry table with structured reason codes.

---

# Figma integration

Source: https://presetai.dev/docs/platform/integrations/figma
Type: guide
Summary: Connect a Figma file on /figma, choose which token types to sync (colors, spacing, radius), and use the drift panel to preview and selectively apply changes. preset AI never auto-overwrites. Figma proposes, you decide.
Last updated: 2026-05-13
Related: Figma MCP integration (https://presetai.dev/docs/platform/integrations/figma-mcp), Importing design systems (https://presetai.dev/docs/importing-design-systems), Updating design systems (https://presetai.dev/docs/updating-design-systems)

---
owner: jschuyler
updated: '2026-05-13'
status: stable
---

export const metadata = {
  title: 'Figma integration',
  description: 'Connect a Figma library to preset AI. Sync token values from Figma Variables. Review drift before applying changes to your design system.',
  type: 'guide',
  summary: 'Connect a Figma file on /figma, choose which token types to sync (colors, spacing, radius), and use the drift panel to preview and selectively apply changes. preset AI never auto-overwrites. Figma proposes, you decide.',
  last_updated: '2026-05-13',
  related: ['/platform/integrations/figma-mcp', '/importing-design-systems', '/updating-design-systems'],
}

export const sections = [
  { title: 'What this connects', id: 'what-this-connects' },
  { title: 'Connect a Figma file', id: 'connect-a-figma-file' },
  { title: 'What syncs', id: 'what-syncs' },
  { title: 'The sync workflow', id: 'the-sync-workflow' },
  { title: 'Authority and drift', id: 'authority-and-drift' },
  { title: 'Requirements', id: 'requirements' },
  { title: 'Troubleshooting', id: 'troubleshooting' },
]

# Figma integration

> Connect your Figma library to preset AI. Sync token values from Figma. Review drift before anything changes.

Designers move fast in Figma. Engineers ship in code. The gap between them is where design systems decay. A hex value updated in Figma never reflects in the codebase. A spacing scale tightened in code drifts from the design source. preset AI's Figma integration closes that gap without forcing either side to abandon their tools.

## What this connects

Two surfaces, one design system.

- **Figma** holds the visual structure: the actual color values, the spacing scale, the radius scale.
- **preset AI** holds the design system contract: the canonical names, the allowed variants, the rules your team enforces in code.

The integration moves token values from Figma into preset AI on demand. It does not move them back to Figma. It does not change anything in your design system without your explicit confirmation.

## Connect a Figma file

In the dashboard, open **Connect**, then **Figma**. Paste:

- The URL of your Figma library file.
- A Figma personal access token with `file_variables:read` scope.

Choose which token types to pull from this file: colors, spacing, radius. Typography sync is not yet available.

preset AI does not store your PAT on the server. The connect modal asks for it to verify the file is reachable; the sync modal asks for it again at every sync and discards it once the sync completes. Tokens are redacted in all logs.

## What syncs

preset AI reads from the Figma Variables API:

| Token type | What gets pulled | Modes |
|---|---|---|
| Color | `COLOR` variables, RGBA converted to hex | Light and dark modes are detected and mapped |
| Spacing | `FLOAT` variables whose names suggest spacing | Single-mode |
| Radius | `FLOAT` variables whose names suggest radius or corner | Single-mode |

Variables that do not match any of those classifications appear in the drift report as "unmapped." You can map them by hand or ignore them.

Components, published styles, and typography are not pulled by this integration. Component-level workflows flow through the MCP path described in [Figma MCP integration](/platform/integrations/figma-mcp).

## The sync workflow

The first sync is one action. Subsequent syncs add a drift-review step in between.

**First sync.** Click **Sync Now** on the connection card. Paste your PAT in the modal that appears, confirm the token types selected, and run. preset AI imports the matching variables and records the result to sync history.

**Subsequent syncs.** Once you have sync history, a drift panel renders below the connection card with the latest comparison. It exposes three actions.

1. **Check for drift.** preset AI re-fetches the current Figma state and compares it against your design system. The result is a fresh drift report: added tokens, removed tokens, value changes. Nothing has been applied yet.
2. **Preview changes.** Pick which differences to apply. The preview shows what your design system will look like after the apply, with exact values. You can scope by token type, by individual token, or by strategy (apply all additions, apply value changes only).
3. **Apply.** Confirm. preset AI writes the selected changes to your design system. Every apply is recorded in the sync history with its before and after snapshot.

Sync history persists. If a colorist edits a token in Figma overnight and the next morning's drift report surprises you, you can scroll back through previous syncs and see exactly when the value changed.

## Authority and drift

The model is asymmetric on purpose.

| Concern | Authority |
|---|---|
| What hex value a color resolves to | Figma |
| What spacing or radius values exist | Figma |
| The canonical name for a token | preset AI |
| Whether a token is allowed in a given context | preset AI |
| Whether to apply a Figma change to the design system | You |

When Figma proposes something preset AI has not seen, a renamed token, a deleted variable, or a new color, the drift report flags it and waits. preset AI does not silently rename, soft-delete, or import. A rename in Figma reads as a delete plus an add in the drift report. If you want to treat it as a rename, you map the two manually.

This is the deliberate trade. Bi-directional auto-sync is faster and wrong more often than not. Drift-with-confirmation is slower and stays correct.

## Requirements

- **Figma plan.** Token sync uses the Variables API, which Figma scopes to its higher-tier plans. If your account does not include Variables API access, the drift check returns a clear error and the integration degrades to "not available on this plan."
- **Personal access token scopes.** `file_variables:read` is the minimum. Writing back to Figma needs `file_variables:write` plus edit access on the file.
- **preset AI plan.** Any plan supports the integration. There is no separate gating on the preset AI side.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `Token invalid or expired` | The PAT was revoked, regenerated, or its scopes changed | Generate a new PAT and re-enter on the `/figma` connection card |
| `Variables API not available` | The file's Figma plan does not include Variables API access | Upgrade the Figma workspace, or sync values through a different source |
| `File not found` | The file was moved, deleted, or the PAT no longer has access | Re-connect with a current file URL, or confirm sharing permissions in Figma |
| `Rate limited, retrying` | Figma's per-tier rate limit was hit | Wait. The sync queue retries automatically with backoff |
| Drift report includes unfamiliar tokens | The Figma file has variables outside the colors, spacing, and radius scope | Ignore them in the preview, or rename in Figma to match your conventions |

## Related

For agent workflows that read live Figma context inside Claude Code or Cursor, see [Figma MCP integration](/platform/integrations/figma-mcp).

For the broader import path (one-off token imports from JSON, Style Dictionary, or scanned codebases), see [Importing design systems](/importing-design-systems).

---

# Figma MCP integration

Source: https://presetai.dev/docs/platform/integrations/figma-mcp
Type: guide
Summary: Dual-server pattern. Figma MCP exposes the selection your designer is looking at. preset AI MCP exposes your tokens, presets, and rules. Together the agent generates code that respects both.
Last updated: 2026-05-13
Related: Figma integration (https://presetai.dev/docs/platform/integrations/figma), Claude Code integration (https://presetai.dev/docs/platform/integrations/claude-code), Cursor integration (https://presetai.dev/docs/platform/integrations/cursor), MCP (https://presetai.dev/docs/platform/mcp)

---
owner: jschuyler
updated: '2026-06-19'
status: stable
---

export const metadata = {
  title: 'Figma MCP integration',
  description: "Run Figma's MCP server alongside preset AI's MCP server. The agent reads live Figma context from one and validates code against your design system from the other.",
  type: 'guide',
  summary: 'Dual-server pattern. Figma MCP exposes the selection your designer is looking at. preset AI MCP exposes your tokens, presets, and rules. Together the agent generates code that respects both.',
  last_updated: '2026-05-13',
  related: ['/platform/integrations/figma', '/platform/integrations/claude-code', '/platform/integrations/cursor', '/platform/mcp'],
}

export const sections = [
  { title: 'The dual-server pattern', id: 'the-dual-server-pattern' },
  { title: 'When to use MCP vs the sync page', id: 'when-to-use-mcp-vs-the-sync-page' },
  { title: 'Setup', id: 'setup' },
  { title: 'What the agent can do', id: 'what-the-agent-can-do' },
  { title: 'Code Connect', id: 'code-connect' },
  { title: 'Requirements', id: 'requirements' },
  { title: 'Troubleshooting', id: 'troubleshooting' },
]

# Figma MCP integration

> Two MCP servers, one workflow. Figma MCP brings the design context your team is looking at. preset AI MCP brings the rules they have to follow.

When an AI assistant generates UI code from a Figma selection, it usually invents tokens: a hex color it pulled from the design, a spacing value it eyeballed, a class name that almost matches your scale. The fix is not a better model. The fix is for the assistant to see your design system alongside the Figma file, so it knows which canonical token a given Figma value should resolve to.

That is what the dual-server setup gives you.

## The dual-server pattern

Two MCP servers, configured side by side in your AI tool.

- **Figma MCP** (Figma's official server) provides live design context. When you have a frame selected in the Figma desktop app, the server exposes its layers, variables, styles, and screenshot to whichever assistant is connected.
- **preset AI MCP** provides governed design-system intelligence. It knows your tokens, your canonical presets, your forbidden primitives, and your enforcement rules. When the agent passes in Figma-shaped data ("here are the variables I see in this selection"), preset AI answers in your system's vocabulary.

Each server stays in its lane. preset AI does not proxy Figma. Figma's server does not know about your design system. The agent calls both, and the model bridges them.

## When to use MCP vs the sync page

| Use the MCP path when | Use the sync page when |
|---|---|
| A designer is on a frame, asking the agent to generate code from it | You want a scheduled or one-off pull of token values |
| The work is selection-scoped and interactive | The work is file-wide |
| You want the agent to suggest preset mappings for the components it sees | You want a drift report you can audit and apply |

The sync page is described in [Figma integration](/platform/integrations/figma).

## Setup

The minimum is two MCP server entries in your AI tool's configuration: preset AI and Figma. The exact syntax differs by tool.

### Claude Code

```bash
# preset AI MCP
claude mcp add --transport http preset https://mcp.presetai.dev/mcp

# Figma MCP (desktop server, requires Dev Mode in Figma)
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp
```

For full preset AI auth options (OAuth, API keys) see [Claude Code integration](/platform/integrations/claude-code).

### Cursor

In `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "preset": {
      "type": "http",
      "url": "https://mcp.presetai.dev/mcp"
    },
    "figma-desktop": {
      "transport": "http",
      "url": "http://127.0.0.1:3845/mcp"
    }
  }
}
```

For Cursor's rule file (`.cursor/rules/preset.mdc`) and tool scoping see [Cursor integration](/platform/integrations/cursor).

### Other tools

VS Code with Copilot, Windsurf, and OpenAI Codex all support MCP servers. See [Codex integration](/platform/integrations/codex) for AGENTS.md setup, and the [MCP overview](/platform/mcp) for the broader picture.

## What the agent can do

With both servers connected, the agent can run end-to-end workflows that would otherwise require two tools and a copy-paste step.

**Generate code from a Figma selection.** Ask: "Build this card from my Figma selection using our preset library." The agent pulls the selection from Figma MCP, asks preset AI for the closest matching preset, and emits code that uses your canonical tokens instead of the raw hex values it saw in Figma.

**Map a Figma component to a preset.** Ask: "What preset matches this Figma component?" The agent passes the component's name, description, and structure to preset AI, which returns ranked preset suggestions with reasoning. If you confirm, the agent records the mapping so future generations from that Figma component go straight to the right preset.

**Detect drift from inside the editor.** Ask: "Are any of the tokens in this Figma file out of sync with our design system?" The agent walks the variables from Figma MCP, compares against preset AI's current state, and reports differences. For file-wide drift audits with a review UI, use the [sync page](/platform/integrations/figma) instead.

In all three flows, preset AI is the source of design-system intelligence. Figma MCP is the source of design context. The agent decides when to call which.

## Code Connect

Figma's MCP server also exposes Code Connect tools: a way to register that a Figma component maps to a specific React component at a specific path in your codebase. Code Connect belongs to Figma, not preset AI, and the dual-server setup leaves it untouched.

If your team uses Code Connect today, the agent can call Code Connect for component-to-file mappings and call preset AI for token, rule, and preset coverage. The two complement each other.

## Requirements

- **Figma MCP plan limits.** Figma rate-limits its MCP server by plan tier. Starter and view-only seats are capped at a small number of MCP calls per month. Dev and Full seats run on a per-minute rate limit and are recommended for any real workflow.
- **Figma desktop app.** The local Figma MCP server runs on `http://127.0.0.1:3845/mcp` and requires the Figma desktop app with Dev Mode active. A remote server is also available at `https://mcp.figma.com/mcp` if you cannot run the desktop app.
- **preset AI plan.** The preset AI MCP is available on every plan. Authentication is OAuth by default, or API key for shared-account setups.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Agent says "Figma desktop not running" | The local MCP server is not reachable | Open the Figma desktop app, enable Dev Mode, confirm port 3845 is free |
| Agent says "no selection" | No layer is currently selected in Figma | Click a frame in Figma before issuing the prompt |
| Generated code uses raw hex instead of token names | The agent skipped the preset AI step | Re-prompt explicitly: "Use our preset AI design system tokens for any colors or spacing" |
| Preset suggestions feel off | The Figma component lacks a description, or its description does not match your library's vocabulary | Add a description in Figma, or map the component manually via preset AI's connection panel |

---

# v0 by Vercel integration

Source: https://presetai.dev/docs/platform/integrations/v0
Type: guide
Summary: Three-step workflow: define presets in preset AI, prototype in v0 (loaded as a registry), validate generated code with preset drift.
Last updated: 2026-05-12
Related: CI integration (https://presetai.dev/docs/platform/ci-cd/ci-integration), Cursor integration (https://presetai.dev/docs/platform/integrations/cursor)

---
owner: jschuyler
updated: '2026-06-20'
status: stable
---

export const metadata = {
  title: 'v0 by Vercel integration',
  description: 'Generate UI fast with v0; validate against your preset AI rules before shipping. preset AI exports your design system as a v0 component registry.',
  type: 'guide',
  summary: 'Three-step workflow: define presets in preset AI, prototype in v0 (loaded as a registry), validate generated code with preset drift.',
  last_updated: '2026-05-12',
  related: ['/platform/ci-cd/ci-integration', '/platform/integrations/cursor'],
}

export const sections = [
  { title: 'The workflow', id: 'the-workflow' },
  { title: 'Quick start', id: 'quick-start' },
  { title: 'How it works', id: 'how-it-works' },
  { title: 'Complete example', id: 'complete-example' },
  { title: 'CI/CD integration', id: 'cicd-integration' },
  { title: 'Best practices', id: 'best-practices' },
  { title: 'Troubleshooting', id: 'troubleshooting' },
]

# v0 by Vercel integration

> Generate with v0, enforce with preset AI.

v0 by Vercel generates UI fast. preset AI ensures that generated code follows your design system rules. Together they create a complete workflow: define your standards in preset AI, prototype rapidly in v0, then validate before shipping.

## The workflow

```
┌─────────────────────────────────────────────────────────────────┐
│  1. DEFINE          2. PROTOTYPE        3. VALIDATE            │
│  ─────────          ────────────        ──────────             │
│  preset AI          v0                  preset AI CLI          │
│                                                                 │
│  • Tokens           • Generate UI       • preset drift         │
│  • Presets          • Iterate fast      • Fix violations       │
│  • Patterns         • Use your tokens   • Commit clean         │
└─────────────────────────────────────────────────────────────────┘
```

## Quick start

### 1. Open your design system in v0

From the preset AI dashboard, go to **Settings → Export** and click the **Open in v0** button. This sends your presets to v0 as a component registry.

Alternatively, from any preset detail page (Studio), click the **Open in v0** button in the header to open that specific preset.

### 2. Generate UI in v0

Once in v0, your design system context is loaded. You can:

- Ask v0 to generate components using your presets
- Reference your design tokens for consistent styling
- Build new UI that aligns with your existing patterns

### 3. Validate with preset AI

After generating code in v0, validate it against your design system:

```bash
# Check for drift in your codebase
preset drift ./src

# Strict mode — fail on any violation
preset drift ./src --strict

# Output for CI integration
preset drift ./src --format sarif
```

## How it works

### v0 registry format

preset AI exports your design system in v0's Registry JSON format, making your presets available as components in v0:

```bash
# Export to registry.json
preset export --format v0-registry --output registry.json
```

The registry includes:

- **Component definitions** with props and variants
- **AI guidance** for each preset (when to use, what to avoid)
- **Dependencies** for proper imports
- **Documentation** inline with components

### Registry endpoint

preset AI hosts a registry endpoint for each design system. v0 fetches it in real time, so v0 always has your latest definitions.

### Open in v0 URL

The **Open in v0** button constructs a `v0.dev/chat/api/open` URL pointing at your registry. v0 fetches your registry and loads your design system context into the chat.

## Complete example

### Step 1: Define a button preset in preset AI

```json
{
  "name": "primary-action",
  "component": "button",
  "description": "Primary call-to-action button",
  "props": {
    "variant": "default",
    "size": "default"
  },
  "usage": [
    "Form submissions",
    "Primary page actions",
    "Checkout flows"
  ],
  "avoid": [
    "Secondary actions (use secondary-action)",
    "Destructive actions (use destructive-action)"
  ]
}
```

### Step 2: Open in v0 and generate

Click **Open in v0** and ask:

> Create a checkout form with a submit button using my primary-action preset.

v0 generates code using your preset definitions.

### Step 3: Validate the generated code

```bash
$ preset drift ./src/components/CheckoutForm.tsx

Checking 1 file...

✓ CheckoutForm.tsx
  └── Button: matches primary-action preset

No drift detected. Your code follows the design system.
```

### Step 4: Handle violations

If v0 generated something that doesn't match:

```bash
$ preset drift ./src/components/CheckoutForm.tsx

Checking 1 file...

✗ CheckoutForm.tsx
  └── Button (line 24): variant="primary" not in design system
     Suggestion: Use variant="default" (primary-action preset)

1 violation found.
```

Fix the code and re-run until clean.

## CI/CD integration

Add drift detection to your CI pipeline:

```yaml
# .github/workflows/drift.yml
name: Design system drift check

on: [pull_request]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install preset AI CLI
        run: curl -fsSL https://presetai.dev/install.sh | sh

      - name: Check for drift
        run: preset drift ./src --strict --format sarif > results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
```

See [CI integration](/platform/ci-cd/ci-integration) for the full reference.

## Best practices

### Define before generating

Create your presets in preset AI before prototyping in v0. This ensures v0 has your design system context.

### Validate early and often

Run `preset drift` locally before pushing. Catch violations before they reach code review.

### Use preset AI's AI guidance

Each preset includes `usage` and `avoid` fields. v0 uses these to make better suggestions.

### Don't skip validation

v0 generates fast, but it may not always match your exact specifications. Always validate.

### Don't modify generated code without re-validating

If you tweak v0's output, run drift again to ensure you didn't introduce violations.

## Troubleshooting

### "Open in v0" not working

1. Ensure you have a design system selected in preset AI
2. Check that your design system has at least one preset
3. Try the direct registry URL in your browser to verify it's accessible

### v0 not using my presets

1. Verify the registry URL is correct
2. Check that presets have descriptive names and AI guidance
3. Be explicit in your prompt: "Use the primary-action preset from my design system"

### Drift detection false positives

1. Ensure your preset definitions are up to date
2. Check that component prop mappings are correct
3. Use `preset drift --verbose` for detailed matching info

---

# MCP

Source: https://presetai.dev/docs/platform/mcp
Type: concept
Summary: MCP is the runtime that gets your tokens, presets, patterns, and constraints into Claude Code, Cursor, and other AI tools.
Last updated: 2026-05-13
Related: Connect an AI coding tool (https://presetai.dev/docs/ai-coding-tools), Claude Code integration (https://presetai.dev/docs/platform/integrations/claude-code), Active guardrails (https://presetai.dev/docs/compliance/active-guardrails)

---
owner: jschuyler
updated: '2026-05-13'
status: stable
---

export const metadata = {
  title: 'MCP',
  description: 'How preset AI delivers your design system into AI coding tools, and how its behavior adapts to your team.',
  type: 'concept',
  summary: 'MCP is the runtime that gets your tokens, presets, patterns, and constraints into Claude Code, Cursor, and other AI tools.',
  last_updated: '2026-05-13',
  related: ['/ai-coding-tools', '/platform/integrations/claude-code', '/compliance/active-guardrails'],
}

export const sections = [
  { title: 'What MCP is', id: 'what-mcp-is' },
  { title: 'What it does for your team', id: 'what-it-does-for-your-team' },
  { title: 'Adaptive behavior by maturity', id: 'adaptive-behavior-by-maturity' },
  { title: 'When to read this vs. the reference', id: 'when-to-read-this-vs-the-reference' },
]

# MCP

The dashboard is where you *define* your design system. MCP is how your team *uses* it.

As AI tools become the primary code writers, MCP is the daily touchpoint: the bridge between your design decisions and every line of generated code. Without MCP, assistants generate generic UI that drifts from your system. With MCP, assistants discover approved components, validate proposals against your constraints, and follow the rules you've set.

## What MCP is

MCP (Model Context Protocol) is an open protocol that AI coding tools speak. preset AI ships an MCP server. When Claude Code, Cursor, Windsurf, or any other MCP-capable tool connects, it gains access to your design system in a structured way the model can reason about.

What flows through MCP:

- **Discovery**: the model can ask "what tokens, presets, and components exist?"
- **Constraints**: the model can ask "what's forbidden in this file?"
- **Validation**: the model can submit a proposed change and get back a pass/fail with reasons
- **Apply**: when allowed by policy, the model can write changes back through a governed lifecycle

For the technical reference, protocol surfaces, tool categories, write lifecycle, adaptive modes, see [developers.presetai.dev/mcp](https://developers.presetai.dev/mcp).

## What it does for your team

Three audiences feel MCP differently:

- **Designers**: your tokens and patterns reach generated code without manual prompting. The AI knows what "primary button" means in your system.
- **Operators and admins**: you decide what the AI can do via [active guardrails](/compliance/active-guardrails) and [maturity mode](#adaptive-behavior-by-maturity). MCP carries those decisions into every AI session.
- **Product**: generated code stays inside the system. Drift gets caught before it ships.

## Adaptive behavior by maturity

MCP isn't one-size-fits-all. It adapts to your design system's maturity:

| Mode | Maturity | AI role | Behavior |
| --- | --- | --- | --- |
| **Generative** | Early: building the system | Co-creator | Proposes new presets when none match. Warns on drift but doesn't block. |
| **Hybrid** | Growing: some standards in place | Suggester + validator | Suggests presets. Validates proposals. Warns on drift. |
| **Enforcement** | Established: compliance critical | Guardian | Strict validation. Blocks non-compliant generation without an approved path. |

A startup gets help building. An enterprise gets enforcement. The same MCP server, different behavior: driven by your design system's measured maturity score and your active compliance mode.

For the full mode table, detection logic, and how to override, see [adaptive modes on developers.presetai.dev/mcp/adaptive-modes](https://developers.presetai.dev/mcp/adaptive-modes).

## When to read this vs. the reference

This page is the concept entry: what MCP is, what it does for your team, how its behavior adapts.

If you're configuring MCP in a tool, integrating against it, or writing code that calls MCP, read the reference on [developers.presetai.dev/mcp](https://developers.presetai.dev/mcp) instead: it covers protocol surfaces, tool categories, the propose → validate → apply lifecycle, and per-tool details.

---

# Confidence scores

Source: https://presetai.dev/docs/product/health/confidence-scores
Type: reference
Summary: Confidence indicates how certain preset AI is about a token extraction. Compounds across 4 stages: detection, parsing, extraction, mapping.
Last updated: 2026-05-12
Related: Importing design systems (https://presetai.dev/docs/importing-design-systems), Token analysis (https://presetai.dev/docs/product/health/token-analysis)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Confidence scores',
  description: 'How preset AI shows confidence in extracted design tokens. Higher confidence = more trustworthy results.',
  type: 'reference',
  summary: 'Confidence indicates how certain preset AI is about a token extraction. Compounds across 4 stages: detection, parsing, extraction, mapping.',
  last_updated: '2026-05-12',
  related: ['/importing-design-systems', '/product/health/token-analysis'],
}

export const sections = [
  { title: 'What confidence means', id: 'what-confidence-means' },
  { title: 'Why confidence varies', id: 'why-confidence-varies' },
  { title: 'How confidence is calculated', id: 'how-confidence-is-calculated' },
  { title: 'Confidence by source', id: 'confidence-by-source' },
  { title: 'What to do with low confidence', id: 'what-to-do-with-low-confidence' },
  { title: 'Improving confidence', id: 'improving-confidence' },
]

# Confidence scores

When importing design tokens, preset AI shows confidence scores to help you understand how reliable each extraction is. Higher confidence means more trustworthy results.

## What confidence means

Confidence indicates how certain preset AI is about an extracted token's accuracy. It's displayed as a percentage or visual indicator:

| Level | Score | Visual | Meaning |
|---|---|---|---|
| **Very high** | 85%+ | Five filled dots | Highly reliable, parsed from standard format |
| **High** | 70-84% | Four dots | Likely accurate, minor uncertainty |
| **Medium** | 50-69% | Three dots | Review recommended |
| **Low** | 30-49% | Two dots | Manual verification needed |
| **Very low** | `<30%` | One dot | May be incorrect |

## Why confidence varies

Token extraction involves multiple stages, each adding potential uncertainty.

### 1. File detection

Did preset AI find the right files?

| Scenario | Confidence |
|---|---|
| Standard file names (`tokens.json`, `tailwind.config.js`) | High |
| Non-standard locations or names | Lower |
| Files guessed from directory structure | Low |

### 2. Format parsing

Did preset AI understand the file format?

| Scenario | Confidence |
|---|---|
| Tokens Studio with `$metadata` | Very high |
| Standard Tailwind config | High |
| CSS with clear `:root` custom properties | High |
| Unknown JSON structure | Lower |

### 3. Value extraction

Did preset AI extract the actual values correctly?

| Scenario | Confidence |
|---|---|
| Direct value (e.g., `#3b82f6`) | High |
| One level of reference resolved | Slightly lower |
| Multiple reference levels resolved | Lower |
| AI-extracted from unstructured content | Low |

### 4. Semantic mapping

Did preset AI map tokens to the right semantic meaning?

| Scenario | Confidence |
|---|---|
| Exact name match (e.g., `primary` → `--primary`) | High |
| Pattern-based match (e.g., `button-bg` → `--primary`) | Medium |
| AI-inferred semantic meaning | Lower |

## How confidence is calculated

Confidence compounds across stages. If each stage is 90% confident:

```
0.90 × 0.90 × 0.90 × 0.90 = 0.66 (66%)
```

This is why even reliable-seeming extractions may show medium confidence: uncertainty accumulates.

### Example breakdown

**Token: `design.color.brand.primary`**

| Stage | Confidence | Reason |
|---|---|---|
| Detection | 98% | Found `tokens.json` with `$metadata` |
| Parsing | 95% | Standard Tokens Studio format |
| Extraction | 90% | Resolved two token references |
| Mapping | 85% | Name contains "primary" |
| **Compound** | **71%** | 0.98 × 0.95 × 0.90 × 0.85 |

## Confidence by source

Different import sources produce different typical confidence levels:

| Source format | Typical confidence |
|---|---|
| **Tokens Studio** | 85-95% |
| **CSS Variables** | 80-90% |
| **Tailwind Config** | 70-85% |
| **Style Dictionary** | 75-85% |
| **AI Analysis** | 25-50% |

Tokens Studio files have the highest confidence because they use a well-defined schema with explicit metadata.

## What to do with low confidence

### For individual tokens

| Confidence | Action |
|---|---|
| High (70%+) | Trust the extraction |
| Medium (50-69%) | Quick visual check |
| Low (`<50%`) | Verify value manually |

### For the overall import

If many tokens have low confidence:

1. **Check your source format**: consider exporting to Tokens Studio or Style Dictionary
2. **Review flagged tokens**: focus on low-confidence items first
3. **Verify critical tokens**: especially primary colors, typography, spacing

## Import summary

At the end of scanning, preset AI shows aggregate statistics:

```
Import Summary
--------------
Total tokens: 24
Average confidence: 78%
High confidence: 20 tokens (83%)
Low confidence: 2 tokens (8%)

Weakest stage: Mapping (avg 72%)
```

This helps you understand overall extraction quality before importing.

## Improving confidence

### Use standard formats

The most reliable extraction comes from:

1. **Tokens Studio**: export from Figma plugin or create manually
2. **Style Dictionary**: industry-standard token format
3. **CSS custom properties**: in `:root` block with clear naming

### Clear naming conventions

Tokens with semantic names are easier to map:

| Naming | Confidence impact |
|---|---|
| `primary`, `background`, `destructive` | Higher |
| `blue-500`, `gray-100` | Medium |
| `color1`, `c1`, `main` | Lower |

### Avoid deep references

Each level of token reference (`{color.blue.500}` → `{primitives.blue}` → `#3b82f6`) reduces confidence.

## FAQ

**Why does the same token have different confidence in light vs. dark mode?**

Each mode is evaluated independently. If dark mode required more reference resolution, it may have lower confidence.

**Can I import tokens even with low confidence?**

Yes. Confidence is advisory: it helps you prioritize which tokens to verify, but doesn't block import.

**Does confidence affect anything after import?**

No. Once imported, all tokens are treated equally. Confidence is only shown during the import preview.

**Why is AI extraction confidence so low?**

AI analysis is probabilistic. While often accurate, there's inherent uncertainty in inferring structure from unstructured content. We're transparent about this uncertainty.

**Can I see the confidence breakdown for each token?**

During import preview, click on a token to see its detailed confidence breakdown by stage.

---

# Token analysis

Source: https://presetai.dev/docs/product/health/token-analysis
Type: reference
Summary: Token analysis compares defined tokens (config files) vs actual usage (component code). Surfaces missing tokens, unused tokens, and component patterns.
Last updated: 2026-05-12
Related: Importing design systems (https://presetai.dev/docs/importing-design-systems), Confidence scores (https://presetai.dev/docs/product/health/confidence-scores)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Token analysis',
  description: 'Compare defined tokens against actual code usage. Find missing tokens, unused tokens, and AI-detected component patterns.',
  type: 'reference',
  summary: 'Token analysis compares defined tokens (config files) vs actual usage (component code). Surfaces missing tokens, unused tokens, and component patterns.',
  last_updated: '2026-05-12',
  related: ['/importing-design-systems', '/product/health/confidence-scores'],
}

export const sections = [
  { title: 'What is token analysis?', id: 'what-is-token-analysis' },
  { title: 'Running analysis', id: 'running-analysis' },
  { title: 'Missing tokens', id: 'missing-tokens' },
  { title: 'Unused tokens', id: 'unused-tokens' },
  { title: 'Component patterns', id: 'component-patterns' },
  { title: 'Analysis summary', id: 'analysis-summary' },
]

# Token analysis

When importing a design system, preset AI can analyze how tokens are actually used in your codebase. This helps identify gaps and opportunities to improve your design system.

## What is token analysis?

Token analysis compares your **defined tokens** (from config files) against **actual usage** (from component code). This reveals:

- **Missing tokens**: colors used in code but not defined in your design system
- **Unused tokens**: tokens defined but never used in code
- **Component patterns**: AI-detected groupings of similar component usage

## Running analysis

After scanning your repository or zip file, you'll see the Analysis step:

1. Click **Run Analysis** to start
2. Wait for the analysis to complete (usually a few seconds)
3. Review the findings
4. Take action on any issues
5. Click **Continue** to proceed to import

You can also **Skip** analysis and import directly.

## Missing tokens

Color values found in your component code that don't have a corresponding token in your design system.

### Why this matters

When developers use raw values like `#3b82f6` instead of tokens like `primary`, it creates:

- inconsistent colors across your app
- harder maintenance when colors need to change
- no single source of truth

### What you'll see

| Element | Description |
|---|---|
| Color swatch | Visual preview of the color |
| Value | The hex/rgb value found in code |
| Usage count | How many times it appears |
| Suggested name | AI-suggested token name |

### Actions

| Action | Result |
|---|---|
| **Add to import** | Includes this token in your design system |

**Tip:** Focus on colors with high usage counts first: these are the most impactful to tokenize.

## Unused tokens

Tokens defined in your design system but never referenced in your component code.

### Why this matters

Unused tokens can indicate:

- outdated tokens that should be removed
- tokens intended for future use
- tokens used in CSS that wasn't scanned

### What you'll see

| Element | Description |
|---|---|
| Token name | The defined token name |
| Defined in | Source file where token is defined |

### Actions

| Action | Result |
|---|---|
| **Remove** | Excludes this token from import |
| **Keep** | Keeps the token in your design system |

**Tip:** Don't remove tokens just because they're unused: they may be intentionally reserved or used in unscanned files.

## Component patterns

AI analyzes your component usage to detect semantic patterns: groups of components that serve similar purposes.

### Why this matters

Patterns help you:

- identify opportunities for presets
- ensure consistent styling for similar actions
- understand how your design system is actually used

### What you'll see

| Element | Description |
|---|---|
| Intent badge | The detected purpose (e.g., "Destructive Action") |
| Component count | Number of components in this pattern |
| Confidence | How certain the AI is (High / Medium / Low) |
| AI rationale | Explanation of why this pattern was detected |
| Common props | Shared properties across components |
| Suggested preset | Recommended preset name |

### Confidence levels

| Level | Meaning |
|---|---|
| **High** | Strong signal from naming and usage patterns |
| **Medium** | Good indicators but some ambiguity |
| **Low** | Weak signal, manual review recommended |

### Actions

Creating presets from patterns is coming in a future release. For now, use patterns as guidance for manual preset creation.

## Analysis summary

At the top of the analysis step, you'll see a summary card:

| Indicator | Meaning |
|---|---|
| Green dot | No issues found |
| Amber dot | Review recommended |
| Blue dot (pulsing) | Analysis in progress |
| Red dot | Analysis failed |

The summary shows counts for each category:

- `+ X missing`: tokens to potentially add
- `− X unused`: tokens to potentially remove
- `✦ X patterns`: component patterns detected

## Preview step banner

After completing analysis, the preview step shows a summary banner if issues were found:

- **When issues exist**: amber banner with key metrics and "View Analysis" button
- **When no issues**: no banner, just a subtle "View analysis" link

You can dismiss the banner with the X button.

## FAQ

**What if analysis finds no issues?**

Great. Your design system is well-aligned with your codebase. Proceed with import.

**Can I skip analysis?**

Yes. Click **Skip** to go directly to the preview step. You can always re-import later with analysis.

**Why are some tokens marked as "missing" when I know they exist?**

Analysis only checks files that were scanned. If tokens are used in files outside the scan scope (e.g., CSS-in-JS, external stylesheets), they won't be detected.

**Should I add all missing tokens?**

Not necessarily. Consider:

- Is this a one-off value or a recurring pattern?
- Should this use an existing token instead?
- Is this value intentionally not tokenized?

**Should I remove all unused tokens?**

Be cautious. Tokens may be:

- reserved for future use
- used in files that weren't scanned
- part of a complete color scale (you might want `gray-100` through `gray-900` even if only `gray-500` is used)

**How accurate is the AI pattern detection?**

Pattern detection uses heuristics based on:

- token naming patterns (e.g., "red" suggests destructive)
- common prop combinations
- usage frequency

High-confidence patterns are usually accurate. Review medium and low confidence patterns manually.

**Will analysis slow down my import?**

Analysis typically takes 2-5 seconds. It runs after scanning completes and doesn't affect the scan itself.

---

# Typography health audit

Source: https://presetai.dev/docs/product/health/typography-audit
Type: reference
Summary: Six categories (foundations, tokens, semantic, responsive, accessibility, usage) score 0-100. Grade A, F. Common issues + fixes.
Last updated: 2026-05-12
Related: Typography Studio (https://presetai.dev/docs/product/studios/typography), Confidence scores (https://presetai.dev/docs/product/health/confidence-scores), Token analysis (https://presetai.dev/docs/product/health/token-analysis)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Typography health audit',
  description: 'Understand your typography system\'s health with actionable insights. Score, grade, category breakdown, recommendations.',
  type: 'reference',
  summary: 'Six categories (foundations, tokens, semantic, responsive, accessibility, usage) score 0-100. Grade A, F. Common issues + fixes.',
  last_updated: '2026-05-12',
  related: ['/product/studios/typography', '/product/health/confidence-scores', '/product/health/token-analysis'],
}

export const sections = [
  { title: 'What is the typography audit?', id: 'what-is-the-typography-audit' },
  { title: 'Categories', id: 'categories' },
  { title: 'Understanding your score', id: 'understanding-your-score' },
  { title: 'Common issues and fixes', id: 'common-issues-and-fixes' },
  { title: 'Improving your score', id: 'improving-your-score' },
  { title: 'Running an audit', id: 'running-an-audit' },
]

# Typography health audit

Understand your typography system's health with actionable insights.

## What is the typography audit?

The typography audit analyzes your design system's typography configuration and provides:

- **Health score** (0-100): overall typography quality
- **Grade** (A, F): quick assessment
- **Category breakdown**: detailed scores per area
- **Recommendations**: specific improvements to make

## Categories

Your typography is evaluated across six categories.

### Foundations (25%)

The building blocks: type scale, font families, and base settings. A weak foundation affects everything else.

Key checks:

- Is there a base font size?
- Are font families defined?
- Is the type scale mathematical?

### Tokens (15%)

How well your tokens are defined and structured.

Key checks:

- Are size, weight, and line-height tokens defined?
- Are tokens actually being used?
- Is naming consistent?

### Semantic (20%)

Whether your typography has clear meaning and purpose.

Key checks:

- Are roles defined (heading, body, caption)?
- Is usage documented?
- Do tokens cover common UI needs?

### Responsive (10%)

How typography adapts across screen sizes.

Key checks:

- Does typography adapt to breakpoints?
- Are scaling rules defined (fluid or breakpoints)?
- Is mobile styling consistent?

### Accessibility (20%)

Critical for users with visual impairments or reading difficulties.

Key checks:

- Are minimum text sizes respected (14px body, 12px caption)?
- Is body text line-height readable (≥ 1.5)?
- Is letter-spacing not too tight?

### Usage (10%)

Governance and documentation quality.

Key checks:

- Do tokens have descriptions/guidance?
- Are arbitrary values avoided?
- Is the system documented?

## Understanding your score

| Score | Grade | Meaning |
|---|---|---|
| 90-100 | A | **Excellent**: industry-leading typography system |
| 75-89 | B | **Good**: solid foundation with minor improvements needed |
| 50-74 | C | **Fair**: functional but significant gaps exist |
| 25-49 | D | **Poor**: major issues affecting usability |
| 0-24 | F | **Critical**: fundamental problems need addressing |

## Common issues and fixes

### "No typographic scale detected"

**Problem:** Font sizes don't follow a mathematical ratio.

**Fix:** Use a scale ratio like 1.25 (Major Third) or 1.333 (Perfect Fourth):

```
base: 16px
lg:   16 * 1.25 = 20px
xl:   20 * 1.25 = 25px
```

### "Body text line-height too tight"

**Problem:** Line-height under 1.5 makes long text hard to read.

**Fix:** Set body text line-height to at least 1.5:

```css
--line-height-normal: 1.5;
```

### "Arbitrary values detected"

**Problem:** Code uses hardcoded values like `text-[14px]` instead of tokens.

**Fix:**

1. Identify commonly used arbitrary values
2. Create tokens for them
3. Replace hardcoded values with tokens
4. Consider lint rules to prevent future arbitrary values

### "Missing token guidance"

**Problem:** Tokens lack descriptions explaining when to use them.

**Fix:** Add descriptions to tokens:

```typescript
fontSize: {
  base: {
    value: '1rem',
    description: 'Default body text size',
    usage: ['Paragraphs', 'List items', 'Table cells'],
  },
}
```

### "Too many font sizes"

**Problem:** More than 12-15 font sizes creates inconsistency.

**Fix:**

1. Audit which sizes are actually used
2. Consolidate similar sizes
3. Remove unused sizes
4. Stick to 8-12 sizes for most systems

## Improving your score

### Quick wins

1. **Add descriptions** to your most-used tokens
2. **Document your scale ratio** in config
3. **Set minimum sizes** for body (14px) and caption (12px)
4. **Use line-height 1.5+** for body text

### Medium effort

1. **Implement fluid typography** with `clamp()`
2. **Define semantic roles** (heading, body, caption, etc.)
3. **Create governance docs** for adding new tokens
4. **Audit arbitrary values** in codebase

### Structural improvements

1. **Establish a type scale** with consistent ratios
2. **Integrate with the scanner** to track actual usage
3. **Create onboarding docs** for new team members
4. **Set up lint rules** to enforce token usage

## Running an audit

### In the dashboard

Navigate to **Health → Typography** to see your current score and recommendations.

### Via API

```typescript
import { runTypographyAudit } from '@preset/health'

const result = runTypographyAudit(yourConfig)
console.log(result.score, result.grade)
```

### Quick check

For a fast assessment of just critical checks:

```typescript
import { runQuickTypographyAudit } from '@preset/health'

const quick = runQuickTypographyAudit(yourConfig)
```

## FAQ

**Why is accessibility weighted so heavily (20%)?**

Typography accessibility directly affects users with visual impairments, dyslexia, and cognitive disabilities. Small text and tight spacing make content unreadable for many users.

**What's the ideal score to aim for?**

Aim for 75+ (B grade) for a production-ready system. 90+ (A grade) represents industry-leading typography.

**Does this check color contrast?**

Not yet. Color contrast requires integration with your color tokens. Run the color audit separately for contrast checking.

**How often should I run the audit?**

Run after any typography changes. Consider adding to CI/CD to catch regressions.

**Can I skip certain checks?**

Yes. Pass `checkOptions: { skip: ['checkpoint-id'] }` to skip specific checks.

---

# Content patterns

Source: https://presetai.dev/docs/product/rules/content-patterns
Type: reference
Summary: Microcopy templates for error/empty/button/confirm/success patterns. Tone rules: helpful not blaming, specific not generic, plain language not jargon.
Last updated: 2026-05-12
Related: Feedback patterns (https://presetai.dev/docs/product/rules/feedback-patterns)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Content patterns',
  description: 'Standardized microcopy templates: error messages, button labels, empty states, success messages, confirmations.',
  type: 'reference',
  summary: 'Microcopy templates for error/empty/button/confirm/success patterns. Tone rules: helpful not blaming, specific not generic, plain language not jargon.',
  last_updated: '2026-05-12',
  related: ['/product/rules/feedback-patterns'],
}

export const sections = [
  { title: 'Pattern categories', id: 'pattern-categories' },
  { title: 'Error messages', id: 'error-messages' },
  { title: 'Empty states', id: 'empty-states' },
  { title: 'Button labels', id: 'button-labels' },
  { title: 'Confirmation dialogs', id: 'confirmation-dialogs' },
  { title: 'Success messages', id: 'success-messages' },
  { title: 'MCP tool usage', id: 'mcp-tool-usage' },
  { title: 'Template placeholders', id: 'template-placeholders' },
  { title: 'Common mistakes', id: 'common-mistakes' },
]

# Content patterns

Content patterns provide standardized microcopy for error messages, button labels, empty states, and other UI text. Using consistent, well-crafted copy helps users understand your interface and builds trust.

## Pattern categories

| Category | Purpose | Examples |
|---|---|---|
| **Error** | Explain what went wrong | Validation errors, API errors, permission denied |
| **Empty** | Guide when no content | No results, first-time user, inbox zero |
| **Button** | Label actions clearly | Save, Delete, Create, Cancel |
| **Confirm** | Verify destructive actions | Delete confirmation, unsaved changes |
| **Success** | Confirm completion | Saved, Created, Sent |
| **Hint** | Help users fill forms | Placeholders, helper text |

## Error messages

### Tone rules

1. **Be helpful, not blaming**: never blame the user; focus on the problem and solution
2. **Explain what happened**: don't just say "error"; describe the issue
3. **Suggest a fix**: tell users how to resolve the problem
4. **Avoid technical jargon**: use plain language, not error codes

### Error patterns

| Pattern | Template | Use case |
|---|---|---|
| `error-required-field` | `{field} is required` | Required field validation |
| `error-invalid-email` | `Please enter a valid email address` | Email format validation |
| `error-password-too-short` | `Password must be at least {minLength} characters` | Password length |
| `error-network-connection` | `We couldn't connect to the server...` | Network failures |
| `error-server-error` | `We're having trouble processing your request...` | 500 errors |
| `error-not-found` | `The {item} you're looking for doesn't exist...` | 404 errors |
| `error-permission-denied` | `You don't have permission to {action}...` | 403 errors |

### Examples

```typescript
// Good error messages
fill_content_template({ pattern: 'error-required-field', values: { field: 'Email' } })
// → "Email is required"

fill_content_template({ pattern: 'error-password-too-short', values: { minLength: 8 } })
// → "Password must be at least 8 characters"

// Bad error messages (don't use)
// "Invalid input"
// "Error occurred"
// "Something went wrong"
// "You entered an invalid email"
```

## Empty states

### Types

| Type | When to use | Key elements |
|---|---|---|
| **First-time** | User has no items yet | Encouraging title, create CTA |
| **No results** | Search returned nothing | Show query, suggest alternatives |
| **No matches** | Filters exclude everything | Clear filters CTA |
| **Inbox zero** | All items processed | Positive, encouraging tone |

### Empty state patterns

| Pattern | Title | Message |
|---|---|---|
| `empty-first-time` | `No {items} yet` | `Create your first {item} to get started.` |
| `empty-no-search-results` | `No results found` | `We couldn't find anything matching "{query}".` |
| `empty-no-filter-results` | `No matches` | `No {items} match your current filters.` |
| `empty-inbox-zero` | `All caught up!` | `You have no new {items} to review.` |

### Examples

```typescript
// First-time empty state
fill_content_template({
  pattern: 'empty-first-time',
  values: { items: 'projects', item: 'project' }
})
// → { title: "No projects yet", message: "Create your first project to get started.", action: "Create project" }

// Search with no results
fill_content_template({
  pattern: 'empty-no-search-results',
  values: { query: 'dashboard' }
})
// → { title: "No results found", message: "We couldn't find anything matching \"dashboard\".", action: "Clear search" }
```

## Button labels

### Rules

1. **Use action verbs**: describe what will happen: "Save", "Delete", "Create"
2. **Be specific**: "Delete Project" is better than "Delete"
3. **Avoid generic labels**: "OK", "Yes", "Submit" are unclear
4. **Match the context**: "Save Draft" vs "Publish" vs "Send"

### Button patterns

| Pattern | Label | Secondary | Context |
|---|---|---|---|
| `button-save` | `Save` | `Cancel` | General save |
| `button-save-changes` | `Save changes` | `Discard` | Editing existing |
| `button-create` | `Create {item}` | `Cancel` | Creating new |
| `button-delete` | `Delete` | `Cancel` | Destructive |
| `button-delete-item` | `Delete {item}` | `Cancel` | Destructive with context |
| `button-cancel` | `Cancel` |: | Dismiss / abort |
| `button-back` | `Back` |: | Navigation |

## Confirmation dialogs

### When to confirm

- Permanent deletions
- Actions that can't be undone
- Navigating away with unsaved changes
- Bulk operations affecting multiple items

### Confirmation patterns

| Pattern | Title | Message |
|---|---|---|
| `confirm-delete` | `Delete {item}?` | `This action cannot be undone. All data...` |
| `confirm-delete-with-count` | `Delete {count} {items}?` | `This action cannot be undone. All selected...` |
| `confirm-unsaved-changes` | `Unsaved changes` | `You have unsaved changes that will be lost...` |
| `confirm-discard-changes` | `Discard changes?` | `Your changes have not been saved...` |

## Success messages

### Rules

1. **Be specific**: confirm exactly what happened
2. **Keep it brief**: success should be obvious
3. **Include the item**: "Project created" not just "Created"

### Success patterns

| Pattern | Message | Context |
|---|---|---|
| `success-saved` | `Changes saved` | General save |
| `success-created` | `{item} created` | Item creation |
| `success-deleted` | `{item} deleted` | Item deletion |
| `success-sent` | `{item} sent` | Messages, emails |

## MCP tool usage

```typescript
// Get all error patterns
get_content_pattern({ category: 'error' })

// Get specific pattern
get_content_pattern({ name: 'confirm-delete' })

// Include tone rules
get_content_pattern({ category: 'button', includeRules: true })

// Fill a template
fill_content_template({
  pattern: 'error-required-field',
  values: { field: 'Email' }
})

// Use variants
fill_content_template({
  pattern: 'error-required-field',
  values: { field: 'Email' },
  variant: 'short'
})
// → "Required"
```

## Template placeholders

Placeholders use `{curly braces}` syntax:

| Placeholder | Type | Description |
|---|---|---|
| `{field}` | string | Field name (Email, Password) |
| `{item}` | string | Singular item (project, user) |
| `{items}` | string | Plural items (projects, users) |
| `{count}` | number | Number of items |
| `{query}` | string | Search query |
| `{minLength}` | number | Minimum length |
| `{action}` | string | Action being attempted |

## Common mistakes

### Blaming the user

```
// Bad — blames user
"You entered an invalid email"

// Good — focuses on the input
"Please enter a valid email address"
```

### Generic messages

```
// Bad — unhelpful
"Something went wrong"

// Good — explains and suggests fix
"We couldn't save your changes. Please try again."
```

### Technical jargon

```
// Bad — confusing
"HTTP 500 Internal Server Error"

// Good — plain language
"We're having trouble processing your request. Please try again in a moment."
```

### Generic button labels

```jsx
// Bad — unclear
<Button>OK</Button>
<Button>Yes</Button>
<Button>Submit</Button>

// Good — descriptive
<Button>Save Project</Button>
<Button>Delete Account</Button>
<Button>Send Message</Button>
```

---

# Feedback patterns

Source: https://presetai.dev/docs/product/rules/feedback-patterns
Type: reference
Summary: Skeleton vs spinner rules, toast types and timing, contextual empty states, progress indicators, accessibility requirements.
Last updated: 2026-05-12
Related: Content patterns (https://presetai.dev/docs/product/rules/content-patterns)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Feedback patterns',
  description: 'UI states that communicate system status: loading, toasts, empty states, errors, success, progress.',
  type: 'reference',
  summary: 'Skeleton vs spinner rules, toast types and timing, contextual empty states, progress indicators, accessibility requirements.',
  last_updated: '2026-05-12',
  related: ['/product/rules/content-patterns'],
}

export const sections = [
  { title: 'Pattern categories', id: 'pattern-categories' },
  { title: 'Loading patterns', id: 'loading-patterns' },
  { title: 'Toast patterns', id: 'toast-patterns' },
  { title: 'Empty state patterns', id: 'empty-state-patterns' },
  { title: 'Progress patterns', id: 'progress-patterns' },
  { title: 'MCP tool usage', id: 'mcp-tool-usage' },
  { title: 'Accessibility', id: 'accessibility' },
  { title: 'Decision flowchart', id: 'decision-flowchart' },
  { title: 'Common mistakes', id: 'common-mistakes' },
]

# Feedback patterns

Feedback patterns are UI states that communicate system status to users: loading indicators, success/error toasts, empty states, and progress indicators. Consistent feedback helps users understand what's happening and what to do next.

## Pattern categories

| Category | Purpose | Examples |
|---|---|---|
| **Loading** | Show work in progress | Skeleton screens, spinners, progress bars |
| **Toast** | Communicate outcomes | Success, error, warning, info notifications |
| **Empty** | Guide when no content | Empty lists, no results, first-time states |
| **Error** | Explain problems | Connection errors, validation failures |
| **Success** | Confirm completion | Saved, submitted, completed states |
| **Progress** | Show advancement | Step indicators, upload progress |

## Loading patterns

### When to use skeleton vs spinner

| Scenario | Pattern | Why |
|---|---|---|
| Layout is known, > 500ms expected | **Skeleton** | Reduces perceived wait time |
| Quick operation, < 500ms expected | **Spinner** | Simpler, less visual noise |
| Unknown layout or complex content | **Spinner** | Can't fake what you don't know |
| Full page loading | **Page spinner** or **Skeleton page** | Depends on layout predictability |
| Button action in progress | **Inline spinner** | Shows action is processing |

### Skeleton patterns

```jsx
// Card skeleton
<div className="animate-pulse">
  <div className="h-48 bg-muted rounded-t-lg" />
  <div className="p-4 space-y-3">
    <div className="h-4 bg-muted rounded w-3/4" />
    <div className="h-3 bg-muted rounded w-1/2" />
  </div>
</div>

// Table row skeleton
<tr className="animate-pulse">
  <td><div className="h-4 bg-muted rounded w-20" /></td>
  <td><div className="h-4 bg-muted rounded w-32" /></td>
  <td><div className="h-4 bg-muted rounded w-16" /></td>
</tr>

// Text skeleton
<div className="animate-pulse space-y-2">
  <div className="h-4 bg-muted rounded w-full" />
  <div className="h-4 bg-muted rounded w-5/6" />
  <div className="h-4 bg-muted rounded w-4/6" />
</div>
```

### Spinner patterns

```jsx
// Inline spinner (in button)
<Button disabled>
  <Loader2 className="mr-2 h-4 w-4 animate-spin" />
  Saving...
</Button>

// Page spinner (centered)
<div className="flex items-center justify-center min-h-[200px]">
  <Loader2 className="h-8 w-8 animate-spin text-muted-foreground" />
</div>

// Overlay spinner (blocking)
<div className="fixed inset-0 bg-background/80 flex items-center justify-center z-50">
  <Loader2 className="h-12 w-12 animate-spin" />
</div>
```

## Toast patterns

### Toast types

| Type | Icon | Color | Duration | Use case |
|---|---|---|---|---|
| **Success** | Check | Green | 5s auto-dismiss | Operation completed |
| **Error** | X | Red | Persistent until dismissed | Operation failed |
| **Warning** | AlertTriangle | Amber | 8s or dismiss | Caution needed |
| **Info** | Info | Blue | 5s auto-dismiss | Neutral notification |

### Toast guidelines

```jsx
// Success — brief, no action needed
toast.success("Changes saved")

// Error — explain what happened, offer action
toast.error("Failed to save changes", {
  description: "Check your connection and try again",
  action: { label: "Retry", onClick: handleRetry }
})

// Warning — alert to potential issue
toast.warning("Unsaved changes", {
  description: "Your changes will be lost if you leave"
})

// Info — neutral information
toast.info("New version available")
```

### Toast timing

| Type | Duration | Reason |
|---|---|---|
| Success | 5 seconds | Brief confirmation |
| Info | 5 seconds | Non-critical information |
| Warning | 8 seconds | User needs time to read and decide |
| Error | Persistent | User must acknowledge and potentially act |

## Empty state patterns

### Types

| Type | Context | Includes action? |
|---|---|---|
| **First-time** | No content created yet | Yes: "Create your first X" |
| **No results** | Search/filter yielded nothing | Yes: "Clear filters" or "Try different search" |
| **Cleared** | User deleted all items | Optional: "Undo" or guidance |
| **Error** | Failed to load content | Yes: "Retry" or troubleshooting |

### Templates

```jsx
// First-time empty state
<div className="text-center py-12">
  <Inbox className="mx-auto h-12 w-12 text-muted-foreground" />
  <h3 className="mt-4 text-lg font-medium">No projects yet</h3>
  <p className="mt-2 text-sm text-muted-foreground">
    Get started by creating your first project.
  </p>
  <Button className="mt-4">
    <Plus className="mr-2 h-4 w-4" />
    Create Project
  </Button>
</div>

// No search results
<div className="text-center py-12">
  <Search className="mx-auto h-12 w-12 text-muted-foreground" />
  <h3 className="mt-4 text-lg font-medium">No results found</h3>
  <p className="mt-2 text-sm text-muted-foreground">
    Try adjusting your search or filters.
  </p>
  <Button variant="outline" className="mt-4" onClick={clearFilters}>
    Clear filters
  </Button>
</div>

// Error state
<div className="text-center py-12">
  <AlertTriangle className="mx-auto h-12 w-12 text-destructive" />
  <h3 className="mt-4 text-lg font-medium">Failed to load</h3>
  <p className="mt-2 text-sm text-muted-foreground">
    Something went wrong. Please try again.
  </p>
  <Button variant="outline" className="mt-4" onClick={retry}>
    <RefreshCw className="mr-2 h-4 w-4" />
    Retry
  </Button>
</div>
```

## Progress patterns

### Progress bar

```jsx
// Determinate
<div className="space-y-2">
  <div className="flex justify-between text-sm">
    <span>Uploading...</span>
    <span>75%</span>
  </div>
  <div className="h-2 bg-muted rounded-full overflow-hidden">
    <div
      className="h-full bg-primary transition-all duration-300"
      style={{ width: '75%' }}
    />
  </div>
</div>

// Indeterminate
<div className="h-2 bg-muted rounded-full overflow-hidden">
  <div className="h-full w-1/3 bg-primary animate-[progress_1s_ease-in-out_infinite]" />
</div>
```

### Step progress

```jsx
<div className="flex items-center gap-2">
  {steps.map((step, i) => (
    <React.Fragment key={step.id}>
      <div className={cn(
        "flex items-center justify-center w-8 h-8 rounded-full text-sm font-medium",
        i < currentStep && "bg-primary text-primary-foreground",
        i === currentStep && "border-2 border-primary text-primary",
        i > currentStep && "bg-muted text-muted-foreground"
      )}>
        {i < currentStep ? <Check className="h-4 w-4" /> : i + 1}
      </div>
      {i < steps.length - 1 && (
        <div className={cn(
          "flex-1 h-0.5",
          i < currentStep ? "bg-primary" : "bg-muted"
        )} />
      )}
    </React.Fragment>
  ))}
</div>
```

## MCP tool usage

### Suggest feedback pattern

```typescript
// Loading a list of items
suggest_feedback_pattern({
  context: 'data-loading',
  contentType: 'list'
})
// Returns: skeleton-card pattern

// Form submission
suggest_feedback_pattern({
  context: 'form-submit',
  dataState: 'success'
})
// Returns: toast-success pattern

// Search with no results
suggest_feedback_pattern({
  context: 'data-loading',
  contentType: 'list',
  dataState: 'empty'
})
// Returns: empty-search pattern
```

### Get feedback template

```typescript
get_feedback_template({
  pattern: 'skeleton-card',
  includeCode: true
})

get_feedback_template({
  pattern: 'toast-success',
  includeCode: true
})
```

## Accessibility

### Loading states

| Requirement | Implementation |
|---|---|
| Announce loading | `aria-live="polite"` on loading container |
| Announce completion | Update live region when loaded |
| Visible focus | Loading must not trap focus |

### Toasts

| Requirement | Implementation |
|---|---|
| Announce to screen readers | `role="alert"` or `aria-live="assertive"` for errors |
| Keyboard dismissible | Escape key closes toast |
| Auto-dismiss consideration | Errors should not auto-dismiss |

### Empty states

| Requirement | Implementation |
|---|---|
| Clear heading | Use semantic heading for empty state title |
| Actionable | Provide clear next step |
| Focus management | Focus the CTA when appropriate |

## Decision flowchart

```
Is data loading?
├── Yes → Is layout known?
│   ├── Yes → Is it expected to take > 500ms?
│   │   ├── Yes → Use skeleton
│   │   └── No → Use spinner (or nothing for < 200ms)
│   └── No → Use page spinner
└── No → Is there data?
    ├── Yes → Show content
    └── No → What's the reason?
        ├── First time → Empty state with CTA
        ├── No results → Empty state with "clear filters"
        └── Error → Error state with retry
```

## Common mistakes

### Using spinners when skeletons are better

```jsx
// Spinner for known layout
<div>
  {isLoading ? <Spinner /> : <CardList items={items} />}
</div>

// Skeleton that matches the layout
<div>
  {isLoading ? <CardListSkeleton count={3} /> : <CardList items={items} />}
</div>
```

### Generic empty states

```jsx
// Unhelpful empty state
<div>No data</div>

// Contextual empty state with action
<EmptyState
  icon={<Inbox />}
  title="No projects yet"
  description="Create your first project to get started."
  action={<Button>Create Project</Button>}
/>
```

### Auto-dismissing errors

```jsx
// Error disappears before user can read it
toast.error("Failed to save", { duration: 3000 })

// Error persists until acknowledged
toast.error("Failed to save", {
  duration: Infinity,
  action: { label: "Retry", onClick: handleRetry }
})
```

---

# Focus management patterns

Source: https://presetai.dev/docs/product/rules/focus-patterns
Type: reference
Summary: Component-specific focus rules + keyboard navigation tables + WCAG requirements. Modals trap, menus wrap, combobox doesn\
Last updated: 2026-05-12
Related: Interaction states (https://presetai.dev/docs/product/rules/interaction-states)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Focus management patterns',
  description: 'Keyboard navigation and focus behavior across components: modals, menus, tabs, toolbars, combobox, skip links.',
  type: 'reference',
  summary: 'Component-specific focus rules + keyboard navigation tables + WCAG requirements. Modals trap, menus wrap, combobox doesn\'t.',
  last_updated: '2026-05-12',
  related: ['/product/rules/interaction-states'],
}

export const sections = [
  { title: 'Component patterns', id: 'component-patterns' },
  { title: 'Focus rules', id: 'focus-rules' },
  { title: 'Landmark regions', id: 'landmark-regions' },
  { title: 'MCP tool usage', id: 'mcp-tool-usage' },
  { title: 'Validation checks', id: 'validation-checks' },
  { title: 'Quick reference', id: 'quick-reference' },
  { title: 'Decision guide', id: 'decision-guide' },
]

# Focus management patterns

Focus management patterns define how keyboard navigation and focus behavior work across components. These patterns ensure accessible, predictable interactions for all users, including those who rely on keyboard navigation.

## Component patterns

### Modal dialog

```jsx
<Dialog
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
>
  <DialogTitle id="dialog-title">Confirm Action</DialogTitle>
  <DialogContent>
    <p>Are you sure?</p>
    <Button onClick={onCancel}>Cancel</Button>
    <Button onClick={onConfirm}>Confirm</Button>
  </DialogContent>
</Dialog>
```

**Behavior:**

- Focus traps within dialog
- Focus moves to first interactive element on open
- Escape closes dialog
- Focus returns to trigger element on close

**Common mistakes:**

- Not trapping focus, allowing Tab to exit modal
- Not restoring focus to trigger on close
- Missing `aria-modal="true"`

### Alert dialog (critical)

For destructive or critical confirmations where Escape should NOT close.

```jsx
<Dialog
  role="alertdialog"
  aria-modal="true"
  aria-labelledby="alert-title"
  aria-describedby="alert-desc"
>
  <DialogTitle id="alert-title">Delete Item?</DialogTitle>
  <p id="alert-desc">This action cannot be undone.</p>
  <Button autoFocus onClick={onCancel}>Cancel</Button>
  <Button intent="destructive" onClick={onDelete}>Delete</Button>
</Dialog>
```

**Key difference:** Focus the LEAST destructive option (Cancel) by default.

### Dropdown menu

```jsx
<Menu
  role="menu"
  aria-labelledby="menu-button"
>
  {items.map((item, index) => (
    <MenuItem
      key={item.id}
      role="menuitem"
      tabIndex={index === activeIndex ? 0 : -1}
    >
      {item.label}
    </MenuItem>
  ))}
</Menu>
```

**Keyboard navigation:**

- ↑/↓: move between items (wraps at boundaries)
- Enter / Space: activate item
- Escape: close menu
- Tab: exit menu (does NOT navigate items)
- Home / End: jump to first/last item
- Type character: jump to item starting with that letter

### Tabs

```jsx
<div role="tablist" aria-orientation="horizontal">
  {tabs.map((tab, index) => (
    <button
      key={tab.id}
      role="tab"
      aria-selected={index === activeIndex}
      aria-controls={`panel-${tab.id}`}
      tabIndex={index === activeIndex ? 0 : -1}
    >
      {tab.label}
    </button>
  ))}
</div>
{tabs.map((tab, index) => (
  <div
    key={tab.id}
    id={`panel-${tab.id}`}
    role="tabpanel"
    aria-labelledby={`tab-${tab.id}`}
    hidden={index !== activeIndex}
  >
    {tab.content}
  </div>
))}
```

**Keyboard navigation:**

- ←/→: move between tabs (wraps)
- Usually automatic activation (arrow changes tab)
- Tab key: exit tablist to panel content

### Toolbar

```jsx
<div
  role="toolbar"
  aria-label="Formatting options"
  aria-orientation="horizontal"
>
  {tools.map((tool, index) => (
    <Button
      key={tool.id}
      tabIndex={index === activeIndex ? 0 : -1}
      aria-pressed={tool.active}
    >
      {tool.icon}
    </Button>
  ))}
</div>
```

**Key behavior:** Toolbar is ONE tab stop. Use arrow keys to move between items.

### Combobox / select

```jsx
<div>
  <input
    role="combobox"
    aria-haspopup="listbox"
    aria-expanded={isOpen}
    aria-controls="listbox-id"
    aria-activedescendant={activeOption ? `option-${activeOption}` : undefined}
  />
  {isOpen && (
    <ul id="listbox-id" role="listbox">
      {options.map((option) => (
        <li
          key={option.id}
          id={`option-${option.id}`}
          role="option"
          aria-selected={option.id === selectedId}
        >
          {option.label}
        </li>
      ))}
    </ul>
  )}
</div>
```

**Key difference:** Arrow keys do NOT wrap: stop at first/last option.

### Skip links

```jsx
<a
  href="#main-content"
  className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:bg-white focus:p-4"
>
  Skip to main content
</a>

{/* Later in the page */}
<main id="main-content" tabIndex="-1">
  {/* Content */}
</main>
```

**Requirements:**

- Must be first focusable element on page
- Hidden until focused
- Target needs `tabIndex="-1"` to receive programmatic focus

## Focus rules

### Visibility rules

| Rule | Requirement | WCAG |
|---|---|---|
| Visible focus indicator | All interactive elements must show focus | 2.4.7 (AA) |
| Use focus-visible | Show focus only on keyboard nav, not clicks | Best practice |
| Focus contrast | Focus indicator must have 3:1 contrast | 2.4.11 (AAA) |

```jsx
// Good — visible focus
className="focus:ring-2 focus:ring-offset-2"
className="focus-visible:ring-2 focus-visible:ring-offset-2"

// Bad — hidden focus
className="focus:outline-none"  // Without replacement
```

### Order rules

| Rule | Requirement | WCAG |
|---|---|---|
| Logical tab order | Must follow visual / reading order | 2.4.3 (A) |
| No positive tabindex | Never use `tabindex="1"`, `"2"`, etc. | 2.4.3 (A) |
| Skip links first | Skip links must be first focusable | 2.4.1 (A) |

```jsx
// Good
tabIndex="0"   // Focusable in natural order
tabIndex="-1"  // Programmatic focus only

// Bad
tabIndex="5"   // Creates unpredictable order
tabIndex="99"  // Maintenance nightmare
```

### Focus trap rules

| Rule | Requirement | WCAG |
|---|---|---|
| Modal focus trap | Focus must cycle within modal | 2.4.3 (A) |
| Focus return | Return focus to trigger on close | 2.4.3 (A) |
| Escape closes | Escape should close overlays (except critical) | Best practice |

## Landmark regions

Standard landmark regions for skip link navigation:

| Name | Role | HTML Element | Skip Link |
|---|---|---|---|
| main | main | `<main>` | "Skip to main content" |
| navigation | navigation | `<nav>` | "Skip to navigation" |
| search | search | `<search>` | "Skip to search" |
| banner | banner | `<header>` |: |
| contentinfo | contentinfo | `<footer>` |: |

## MCP tool usage

### Get focus pattern

```typescript
// Get patterns for modal components
get_focus_pattern({ componentType: 'modal' })

// Get specific pattern
get_focus_pattern({ name: 'alert-dialog' })

// Include rules and landmarks
get_focus_pattern({
  componentType: 'modal',
  includeRules: true,
  includeLandmarks: true
})
```

### Validate focus management

```typescript
// Basic validation
validate_focus_management({
  code: '<Dialog role="dialog">...</Dialog>'
})

// With component type context
validate_focus_management({
  code: '<nav role="menu">...</nav>',
  componentType: 'dropdown'
})

// Strict mode (warnings become errors)
validate_focus_management({
  code: '...',
  strict: true
})
```

## Validation checks

| Issue | Severity | Fix |
|---|---|---|
| Missing focus indicator | Error | Add `focus:ring-2` or equivalent |
| Positive tabindex | Error | Use `tabindex="0"` or `-1` |
| Modal without focus trap | Error | Use focus trap library + `aria-modal` |
| Dialog missing aria-modal | Warning | Add `aria-modal="true"` |
| Tab missing aria-selected | Error | Add `aria-selected` attribute |
| Click without keyboard | Warning | Add `role="button"` + keyboard handler |
| autoFocus usage | Warning | Ensure intentional and appropriate |

## Quick reference

### Keyboard navigation by component

| Component | Navigation | Wrap? | Activation |
|---|---|---|---|
| Modal | Tab | Trap | Enter / Space |
| Menu | Arrow | Yes | Enter / Space |
| Tabs | Arrow | Yes | Auto or Enter |
| Toolbar | Arrow | Yes | Enter / Space |
| Combobox | Arrow | No | Enter |
| Tree | Arrow | No | Enter |

### Required ARIA by component

| Component | Required attributes |
|---|---|
| Modal | `role="dialog"`, `aria-modal`, `aria-labelledby` |
| Alert Dialog | `role="alertdialog"`, `aria-modal`, `aria-labelledby`, `aria-describedby` |
| Menu | `role="menu"`, `aria-labelledby` |
| Menu Item | `role="menuitem"` |
| Tabs | `role="tablist"`, `aria-orientation` |
| Tab | `role="tab"`, `aria-selected`, `aria-controls` |
| Tab Panel | `role="tabpanel"`, `aria-labelledby` |
| Combobox | `role="combobox"`, `aria-haspopup`, `aria-expanded`, `aria-controls` |

## Decision guide

```
Building interactive component?
├── Is it an overlay?
│   ├── Modal / blocking? → Use focus trap + aria-modal
│   └── Non-modal? → No trap, but restore focus on close
├── Is it a list of options?
│   ├── Actions? → role="menu" + arrow keys + wrap
│   ├── Selection? → role="listbox" + arrow keys + no wrap
│   └── Navigation? → role="tablist" + arrow keys + wrap
├── Is it a button group?
│   └── Toolbar? → role="toolbar" + arrow keys + one tab stop
└── Is it page-level?
    └── Add skip links (first focusable element)
```

---

# Interaction states

Source: https://presetai.dev/docs/product/rules/interaction-states
Type: reference
Summary: Consistent hover/focus/active/disabled states. Use focus-visible for buttons/cards, focus for inputs. Subtle transitions, complete disabled states.
Last updated: 2026-05-12
Related: Motion tokens (https://presetai.dev/docs/product/rules/motion-tokens), Focus management patterns (https://presetai.dev/docs/product/rules/focus-patterns)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Interaction states',
  description: 'Four core states: hover, focus, active, disabled, and the patterns for buttons, inputs, cards, and links.',
  type: 'reference',
  summary: 'Consistent hover/focus/active/disabled states. Use focus-visible for buttons/cards, focus for inputs. Subtle transitions, complete disabled states.',
  last_updated: '2026-05-12',
  related: ['/product/rules/motion-tokens', '/product/rules/focus-patterns'],
}

export const sections = [
  { title: 'The 4 core states', id: 'the-4-core-states' },
  { title: 'State patterns by component', id: 'state-patterns-by-component' },
  { title: 'Global rules', id: 'global-rules' },
  { title: 'MCP tool usage', id: 'mcp-tool-usage' },
  { title: 'Common mistakes', id: 'common-mistakes' },
]

# Interaction states

Interaction states define how UI elements visually respond to user actions: hover, focus, active (pressed), and disabled. Consistent interaction states help users understand what's clickable, what's focused, and what's unavailable.

## The 4 core states

| State | Trigger | Purpose |
|---|---|---|
| **Hover** | Mouse over element | Indicates interactivity |
| **Focus** | Keyboard navigation / click | Shows which element is active |
| **Active** | Mouse down / pressing | Confirms the click is registering |
| **Disabled** | Element unavailable | Prevents interaction |

## State patterns by component

### Buttons

| State | Visual change | Tailwind classes |
|---|---|---|
| Hover | Background darkens 10% | `hover:bg-primary/90` |
| Focus | Ring appears (keyboard only) | `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` |
| Active | Scale down + darken | `active:bg-primary/80 active:scale-[0.98]` |
| Disabled | Opacity 50% + cursor | `disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none` |

**Key rule:** Use `focus-visible` instead of `focus` for buttons. This shows the focus ring only for keyboard users, not mouse clicks.

### Inputs

| State | Visual change | Tailwind classes |
|---|---|---|
| Hover | Border darkens | `hover:border-muted-foreground/50` |
| Focus | Ring appears | `focus:ring-1 focus:ring-ring focus:outline-none` |
| Disabled | Muted background + opacity | `disabled:opacity-50 disabled:bg-muted disabled:cursor-not-allowed` |

**Key rule:** Inputs use `focus` (not `focus-visible`) because users need to see which field is active at all times.

### Interactive cards

| State | Visual change | Tailwind classes |
|---|---|---|
| Hover | Lift + shadow | `hover:shadow-md hover:-translate-y-0.5 transition-all` |
| Focus | Ring appears | `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` |
| Active | Depress | `active:scale-[0.99] active:shadow-sm` |

**Key rule:** Non-interactive cards should have NO hover effect. This avoids false affordance.

### Links

| State | Visual change | Tailwind classes |
|---|---|---|
| Hover | Underline | `hover:underline` |
| Focus | Ring appears | `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2` |

## Global rules

### 1. Hover feedback should be immediate

Hover states need instant feedback (under 50ms). Use `transition-colors` with short duration.

```jsx
// Good — fast transition
className="transition-colors duration-50 hover:bg-primary/90"

// Bad — too slow
className="transition-all duration-300 hover:bg-primary/90"
```

### 2. Use focus-visible for keyboard focus

For buttons, links, and cards, use `focus-visible` to show focus rings only for keyboard navigation.

```jsx
// Good — keyboard users only see ring
className="focus-visible:ring-2 focus-visible:ring-ring"

// Bad — mouse users see ring on every click
className="focus:ring-2 focus:ring-ring"
```

### 3. Disabled states need three things

1. **Visual indicator**: `disabled:opacity-50`
2. **Cursor feedback**: `disabled:cursor-not-allowed`
3. **Prevent interaction**: `disabled:pointer-events-none`

```jsx
// Complete disabled state
className="disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none"

// Incomplete — hover effects still work
className="disabled:opacity-50 disabled:cursor-not-allowed"
```

### 4. Keep hover effects subtle

Hover changes should be 5-10% opacity/lightness shifts, not dramatic transforms.

```jsx
// Good — subtle
className="hover:bg-primary/90"  // 10% darker

// Bad — too dramatic
className="hover:scale-110 hover:rotate-2"
```

## MCP tool usage

### Getting interaction states

```typescript
// Get all states for a button
get_interaction_states({ component: 'button' })

// Get specific state
get_interaction_states({
  component: 'button',
  variant: 'primary',
  state: 'hover'
})

// Include rules for learning
get_interaction_states({
  component: 'input',
  includeRules: true
})
```

### Validating implementation

```typescript
// Check if a component has all required states
validate_interaction_states({
  code: '<Button className="hover:bg-primary/90">Click</Button>',
  component: 'button'
})

// Returns missing states, violations, and recommendations
```

## Common mistakes

### Using focus instead of focus-visible

```jsx
// Problem: Ring shows on mouse click
<Button className="focus:ring-2">Click</Button>

// Solution: Ring only on keyboard focus
<Button className="focus-visible:ring-2">Click</Button>
```

### Incomplete disabled states

```jsx
// Problem: Hover still works when disabled
<Button
  disabled
  className="disabled:opacity-50 hover:bg-primary/90"
>
  Submit
</Button>

// Solution: Disable pointer events
<Button
  disabled
  className="disabled:opacity-50 disabled:pointer-events-none hover:bg-primary/90"
>
  Submit
</Button>
```

### Static cards with hover effects

```jsx
// Problem: Card looks clickable but isn't
<div className="p-4 border hover:shadow-md">
  <p>Content</p>
</div>

// Solution: No hover on non-interactive elements
<div className="p-4 border">
  <p>Content</p>
</div>
```

## FAQ

**When should I use focus vs focus-visible?**

- **focus-visible**: buttons, links, cards, tabs (mouse users don't need focus indication)
- **focus**: inputs, textareas, selects (users need to see which field is active)

**Should all interactive elements have all four states?**

Not necessarily:

- **Buttons**: hover, focus-visible, active, disabled
- **Inputs**: hover, focus, disabled (no active needed)
- **Links**: hover, focus-visible (active optional)
- **Static cards**: none (they're not interactive)

**How dark should hover be?**

10% is the sweet spot. Use `/90` opacity in Tailwind:

- `hover:bg-primary/90` (10% darker)
- `hover:text-primary/90` (10% darker text)

Going darker (e.g., `/70`) is too dramatic for most cases.

---

# Motion tokens

Source: https://presetai.dev/docs/product/rules/motion-tokens
Type: reference
Summary: Four duration tokens (instant/quick/normal/slow), five easing tokens (out-quart/out-expo/in-quart/in-out-quart/linear). Semantic intent, not arbitrary numbers.
Last updated: 2026-05-12
Related: Transition patterns (https://presetai.dev/docs/product/rules/transition-patterns), Interaction states (https://presetai.dev/docs/product/rules/interaction-states)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Motion tokens',
  description: 'Consistent timing values for animations and transitions. Semantic duration + easing tokens instead of arbitrary values.',
  type: 'reference',
  summary: 'Four duration tokens (instant/quick/normal/slow), five easing tokens (out-quart/out-expo/in-quart/in-out-quart/linear). Semantic intent, not arbitrary numbers.',
  last_updated: '2026-05-12',
  related: ['/product/rules/transition-patterns', '/product/rules/interaction-states'],
}

export const sections = [
  { title: 'Duration tokens', id: 'duration-tokens' },
  { title: 'Easing tokens', id: 'easing-tokens' },
  { title: 'Common combinations', id: 'common-combinations' },
  { title: 'Using motion tokens', id: 'using-motion-tokens' },
  { title: 'MCP tool', id: 'mcp-tool' },
  { title: 'Accessibility', id: 'accessibility' },
]

# Motion tokens

Motion tokens define consistent timing values for animations and transitions across your design system. Instead of using arbitrary values like `duration-300` or `ease-in-out`, use semantic tokens that convey meaning.

Motion tokens come in two categories:

- **Duration tokens**: how long an animation takes
- **Easing tokens**: how an animation accelerates and decelerates

## Duration tokens

| Token | Value | When to use |
|---|---|---|
| `instant` | 100ms | Micro-interactions like checkboxes, toggles, hover states |
| `quick` | 200ms | UI feedback like button presses, dropdowns, tooltips |
| `normal` | 300ms | Standard transitions like modals, sidebars, page changes |
| `slow` | 500ms | Emphasis moments: onboarding, hero animations, celebrations |

### Duration selection guide

- **Default to `quick`** (200ms) for most UI interactions
- Use `instant` (100ms) when feedback needs to feel immediate
- Use `normal` (300ms) for significant state changes users need to notice
- Use `slow` (500ms) sparingly: only for moments that deserve emphasis

## Easing tokens

| Token | Value | When to use |
|---|---|---|
| `out-quart` | `cubic-bezier(0.25, 1, 0.5, 1)` | Standard exits and settling into place |
| `out-expo` | `cubic-bezier(0.16, 1, 0.3, 1)` | Snappy entrances, elements appearing |
| `in-quart` | `cubic-bezier(0.5, 0, 0.75, 0)` | Exits that accelerate away, dismissals |
| `in-out-quart` | `cubic-bezier(0.76, 0, 0.24, 1)` | Continuous motion, carousels |
| `linear` | `linear` | Progress indicators, loading bars |

### Easing selection guide

- **Default to `out-quart`** for most transitions
- Use `out-expo` when elements need to "pop" into place
- Use `in-quart` when elements are leaving or being dismissed
- Use `in-out-quart` for continuous or looping animations
- Use `linear` only for progress indicators where a constant rate conveys predictability

## Common combinations

Recommended duration + easing pairs for common UI patterns:

| Pattern | Duration | Easing | Example |
|---|---|---|---|
| Dropdown open | `quick` | `out-expo` | Menu appearing below button |
| Modal enter | `normal` | `out-expo` | Dialog opening |
| Modal exit | `quick` | `in-quart` | Dialog closing |
| Tooltip show | `quick` | `out-quart` | Tooltip appearing on hover |
| Page transition | `normal` | `out-quart` | Navigating between pages |

## Using motion tokens

### In CSS

```css
:root {
  --motion-duration-instant: 100ms;
  --motion-duration-quick: 200ms;
  --motion-duration-normal: 300ms;
  --motion-duration-slow: 500ms;

  --motion-easing-out-quart: cubic-bezier(0.25, 1, 0.5, 1);
  --motion-easing-out-expo: cubic-bezier(0.16, 1, 0.3, 1);
  --motion-easing-in-quart: cubic-bezier(0.5, 0, 0.75, 0);
  --motion-easing-in-out-quart: cubic-bezier(0.76, 0, 0.24, 1);
  --motion-easing-linear: linear;
}

.modal {
  transition: opacity var(--motion-duration-normal) var(--motion-easing-out-expo);
}
```

### In Tailwind CSS

Add to your `tailwind.config.js`:

```js
module.exports = {
  theme: {
    extend: {
      transitionDuration: {
        'instant': '100ms',
        'quick': '200ms',
        'normal': '300ms',
        'slow': '500ms',
      },
      transitionTimingFunction: {
        'out-quart': 'cubic-bezier(0.25, 1, 0.5, 1)',
        'out-expo': 'cubic-bezier(0.16, 1, 0.3, 1)',
        'in-quart': 'cubic-bezier(0.5, 0, 0.75, 0)',
        'in-out-quart': 'cubic-bezier(0.76, 0, 0.24, 1)',
      },
    },
  },
}
```

Then use the classes:

```html
<div class="transition-opacity duration-normal ease-out-expo">
  Modal content
</div>
```

## MCP tool

AI coding tools retrieve motion tokens via `get_motion_tokens`.

Parameters:

- `category` (optional): `'duration'`, `'easing'`, or `'all'` (default: `'all'`)
- `format` (optional): `'tokens'`, `'css'`, or `'tailwind'` (default: `'tokens'`)

```
get_motion_tokens({ category: "duration" })
get_motion_tokens({ category: "easing", format: "css" })
get_motion_tokens({ format: "tailwind" })
```

## Accessibility

Always respect user preferences for reduced motion:

```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
```

Or in Tailwind:

```html
<div class="transition-opacity duration-normal motion-reduce:duration-0">
  Content
</div>
```

## FAQ

**Why use semantic tokens instead of arbitrary values?**

Semantic tokens like `quick` and `normal` communicate intent and ensure consistency. When you see `duration-quick`, you know it's for UI feedback. When you see `duration-300`, you have to guess.

**How do I choose between out-quart and out-expo?**

- `out-quart` is gentler: good for subtle transitions
- `out-expo` is snappier: good for elements that need to "pop"

When in doubt, start with `out-quart`.

**What if 200ms feels too slow for my dropdown?**

Trust the tokens first. If something feels slow, it might be a perception issue from other factors (layout shift, render delay). If after testing you truly need faster, consider whether `instant` (100ms) is appropriate for that interaction type.

**Can I create custom duration/easing tokens?**

Yes, but be deliberate. Every new token adds complexity. Before adding a custom token, ask: "Does this truly represent a new semantic category, or can I use an existing token?"

---

# Responsive patterns

Source: https://presetai.dev/docs/product/rules/responsive-patterns
Type: reference
Summary: Beyond hide/show. Six behavior types: layout-shift, variant-change, size-adaptation, content-truncation, component-swap, visibility. Mobile-first.
Last updated: 2026-05-12
Related: Interaction states (https://presetai.dev/docs/product/rules/interaction-states)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Responsive patterns',
  description: 'How components adapt across screen sizes: layout shifts, variant changes, touch targets, component swaps.',
  type: 'reference',
  summary: 'Beyond hide/show. Six behavior types: layout-shift, variant-change, size-adaptation, content-truncation, component-swap, visibility. Mobile-first.',
  last_updated: '2026-05-12',
  related: ['/product/rules/interaction-states'],
}

export const sections = [
  { title: 'Breakpoints', id: 'breakpoints' },
  { title: 'Behavior types', id: 'behavior-types' },
  { title: 'Core patterns', id: 'core-patterns' },
  { title: 'Touch target guidelines', id: 'touch-target-guidelines' },
  { title: 'Mobile-first development', id: 'mobile-first-development' },
  { title: 'Common issues', id: 'common-issues' },
  { title: 'MCP tool usage', id: 'mcp-tool-usage' },
  { title: 'Validation checks', id: 'validation-checks' },
  { title: 'Decision guide', id: 'decision-guide' },
]

# Responsive patterns

Responsive patterns define how components adapt across screen sizes. Going beyond simple hide/show, these patterns cover layout shifts, variant changes, touch target adaptations, and component swaps.

## Breakpoints

Standard Tailwind breakpoints:

| Breakpoint | Min width | Devices | Tailwind |
|---|---|---|---|
| default | 0px | Mobile | (no prefix) |
| sm | 640px | Large mobile, small tablet | `sm:` |
| md | 768px | Tablet, small laptop | `md:` |
| lg | 1024px | Laptop, small desktop | `lg:` |
| xl | 1280px | Desktop | `xl:` |
| 2xl | 1536px | Large desktop | `2xl:` |

## Behavior types

| Type | Description | Example |
|---|---|---|
| **layout-shift** | Component rearranges layout | Sidebar → bottom nav |
| **variant-change** | Component switches variant | Full button → icon-only |
| **size-adaptation** | Dimensions change | Larger touch targets on mobile |
| **content-truncation** | Content is shortened | Full text → 2-line truncation |
| **component-swap** | Different component entirely | Table → card list |
| **visibility** | Show / hide elements | Secondary actions hidden |

## Core patterns

### Navigation: sidebar to bottom

Desktop sidebar becomes bottom navigation on mobile.

```jsx
<nav className="
  fixed bottom-0 left-0 right-0 h-16 border-t
  md:static md:h-auto md:w-64 md:border-t-0 md:border-r
">
  {/* Nav items */}
</nav>
```

**When to use:**

- Primary app navigation
- Apps with 3-5 main sections

**When to avoid:**

- Content-heavy sites
- Simple marketing pages

### Button: icon collapse

Full button on desktop becomes icon-only on mobile.

```jsx
<Button className="
  h-11 w-11 p-2
  sm:h-10 sm:w-auto sm:px-4 sm:py-2
">
  <Icon className="sm:mr-2" />
  <span className="hidden sm:inline">Save</span>
</Button>
```

**When to use:**

- Toolbars with multiple actions
- Compact mobile layouts

**When to avoid:**

- Primary CTAs
- Single action that needs a clear label

### Button: stack to inline

Buttons stack vertically on mobile, inline on desktop.

```jsx
<div className="
  flex flex-col gap-2 w-full
  sm:flex-row sm:w-auto sm:gap-3
">
  <Button className="w-full sm:w-auto">Cancel</Button>
  <Button className="w-full sm:w-auto">Save</Button>
</div>
```

**When to use:**

- Form submit / cancel pairs
- Confirmation dialogs

### Table: cards on mobile

Table displays as cards on mobile.

```jsx
{/* Desktop table */}
<Table className="hidden md:table">
  <TableHeader>...</TableHeader>
  <TableBody>{rows.map(...)}</TableBody>
</Table>

{/* Mobile cards */}
<div className="md:hidden space-y-3">
  {rows.map(row => (
    <Card key={row.id}>
      <CardHeader>{row.name}</CardHeader>
      <CardContent>...</CardContent>
    </Card>
  ))}
</div>
```

**When to use:**

- Tables with many columns
- Detail-rich data

**When to avoid:**

- Simple 2-3 column tables
- Tables requiring side-by-side comparison

### Modal: fullscreen on mobile

Modals expand to fullscreen on mobile.

```jsx
<Dialog className="
  fixed inset-0 rounded-t-xl pt-safe
  md:inset-auto md:rounded-[2px] md:max-w-lg md:mx-auto md:my-auto
">
  {/* Dialog content */}
</Dialog>
```

**When to use:**

- Form dialogs
- Detail views

**When to avoid:**

- Simple alerts

### Card grid: responsive columns

```jsx
<div className="
  grid grid-cols-1 gap-4
  sm:grid-cols-2
  lg:grid-cols-3
  xl:grid-cols-4
">
  {cards.map(...)}
</div>
```

## Touch target guidelines

**Minimum size: 44 × 44 pixels (`h-11 w-11`)**

| Element | Mobile classes |
|---|---|
| Buttons | `min-h-11 min-w-11` |
| Icon buttons | `h-11 w-11 p-2` |
| Nav items | `min-h-11 py-3` |
| List items | `min-h-11 py-2` |

```jsx
// Good — meets touch target
<Button className="min-h-11 min-w-11 p-2">
  <X className="h-5 w-5" />
</Button>

// Bad — too small
<Button className="h-6 w-6 p-1">
  <X className="h-4 w-4" />
</Button>
```

## Mobile-first development

**Always write mobile styles first, then add breakpoint overrides.**

```jsx
// Mobile-first
className="flex flex-col md:flex-row"
className="w-full md:w-1/2"
className="text-base md:text-sm"

// Desktop-first (anti-pattern)
className="hidden md:block"  // Content hidden on mobile
className="flex-row md:flex-col"  // Reversed logic
```

## Common issues

### Input zoom on iOS

iOS Safari zooms when input text is smaller than 16px.

```jsx
// Good — 16px on mobile prevents zoom
<Input className="text-base md:text-sm" />

// Bad — triggers zoom on mobile
<Input className="text-sm" />
```

### Table overflow

Tables overflow on narrow screens.

```jsx
// Option 1: horizontal scroll
<div className="overflow-x-auto">
  <Table className="min-w-[640px]" />
</div>

// Option 2: component swap
<Table className="hidden md:table" />
<CardList className="md:hidden" />

// Bad — overflows
<Table className="w-full" />
```

### Spacing differences

Use larger touch-friendly spacing on mobile.

```jsx
// Good — more padding on mobile
className="p-4 md:p-3"
className="gap-3 md:gap-2"

// Bad — too cramped on touch
className="p-1"
className="gap-1"
```

## MCP tool usage

### Get responsive behavior

```typescript
// Get patterns for navigation
get_responsive_behavior({ component: 'navigation' })

// Get all layout-shift patterns
get_responsive_behavior({ behaviorType: 'layout-shift' })

// Include breakpoint definitions and rules
get_responsive_behavior({
  component: 'button',
  includeBreakpoints: true,
  includeRules: true
})
```

### Validate implementation

```typescript
validate_responsive_pattern({
  code: '<Button className="h-6 w-6">X</Button>'
})
// Returns: warning about small touch target

validate_responsive_pattern({
  code: '<nav className="hidden md:block">...</nav>'
})
// Returns: warning about desktop-first pattern
```

## Validation checks

| Issue | Severity | Fix |
|---|---|---|
| Small touch target | Warning | Use `min-h-11 min-w-11` |
| Desktop-first hiding | Warning | Use mobile-first approach |
| Small input text | Warning | Use `text-base md:text-sm` |
| Table without scroll | Warning | Add `overflow-x-auto` or card swap |
| Fixed width without responsive | Warning | Add breakpoint variants |

## Decision guide

```
Building component?
├── Does layout change at breakpoints?
│   └── Yes → Use layout-shift pattern
├── Does variant change at breakpoints?
│   └── Yes → Use variant-change pattern
├── Are there touch targets?
│   └── Yes → Ensure 44px minimum on mobile
├── Is it a table with many columns?
│   └── Yes → Use component-swap (cards) or scroll
└── Is there text that might be too long?
    └── Yes → Consider content-truncation
```

---

# Transition patterns

Source: https://presetai.dev/docs/product/rules/transition-patterns
Type: reference
Summary: Each transition conveys a specific spatial message. Pick by relationship: same thing morphs, peer content, hierarchy, overlay, in-place replace.
Last updated: 2026-05-12
Related: Motion tokens (https://presetai.dev/docs/product/rules/motion-tokens), Interaction states (https://presetai.dev/docs/product/rules/interaction-states)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Transition patterns',
  description: 'Five core patterns, Container Transform, Shared Axis, Drill, Layer, Fade, each conveying a spatial relationship between states.',
  type: 'reference',
  summary: 'Each transition conveys a specific spatial message. Pick by relationship: same thing morphs, peer content, hierarchy, overlay, in-place replace.',
  last_updated: '2026-05-12',
  related: ['/product/rules/motion-tokens', '/product/rules/interaction-states'],
}

export const sections = [
  { title: 'The 5 core patterns', id: 'the-5-core-patterns' },
  { title: 'Pattern selection decision tree', id: 'pattern-selection-decision-tree' },
  { title: 'Container Transform', id: 'container-transform' },
  { title: 'Shared Axis', id: 'shared-axis' },
  { title: 'Drill Forward / Back', id: 'drill-forward--back' },
  { title: 'Layer', id: 'layer' },
  { title: 'Fade', id: 'fade' },
  { title: 'Common scenarios', id: 'common-scenarios' },
  { title: 'Accessibility', id: 'accessibility' },
]

# Transition patterns

Transition patterns define HOW content moves between states in your UI. Each pattern conveys a specific spatial relationship to the user, helping them understand where content came from and where it went.

## The 5 core patterns

| Pattern | Spatial message | When to use |
|---|---|---|
| **Container Transform** | "This IS that" | Shared element morphs between states |
| **Shared Axis** | "This is NEXT TO that" | Switching between peer content |
| **Drill Forward/Back** | "This is INSIDE that" | Navigating up/down hierarchy |
| **Layer** | "This is ON TOP of that" | Overlays, modals, dropdowns |
| **Fade** | "This REPLACES that" | In-place content changes |

## Pattern selection decision tree

When choosing a transition pattern, ask these questions in order:

1. **Is there a shared visual element that should morph?**
   - YES → **Container Transform**
   - NO → continue
2. **Is content appearing ON TOP (overlay)?**
   - YES → **Layer**
   - NO → continue
3. **Is this navigation between hierarchical levels?**
   - Going deeper (parent → child) → **Drill Forward**
   - Going back (child → parent) → **Drill Back**
   - NO → continue
4. **Is this switching between peer content (same level)?**
   - YES → **Shared Axis**
   - NO → continue
5. **Is content just changing in place?**
   - YES → **Fade**

## Container Transform

**Spatial message:** "This IS that"

The user perceives that one element has transformed into another, maintaining visual identity and continuity.

### When to use

- Card thumbnail expanding to full image
- List avatar morphing to profile header
- Compact view expanding to detailed view
- FAB transforming into a dialog

### When to avoid

- No shared visual element exists between states
- Elements are semantically different (not the same "thing")

### Implementation

```jsx
// Enter: element grows from origin
className="origin-center scale-95 opacity-0"

// Active: element at full size
className="origin-center scale-100 opacity-100"

// Duration: normal (300ms), Easing: out-quart
```

## Shared Axis

**Spatial message:** "This is NEXT TO that"

Content slides horizontally or vertically, indicating sibling/peer relationship at the same hierarchical level.

### When to use

- Tab switching
- Carousel / slider navigation
- Segmented control switching
- Pagination
- Onboarding step progression

### When to avoid

- Hierarchical navigation (use Drill)
- Overlay content (use Layer)

### Direction rule

- Going **forward / next**: content slides **LEFT**
- Going **back / previous**: content slides **RIGHT**

### Implementation

```jsx
// Enter from right (forward navigation)
className="translate-x-4 opacity-0"

// Exit to left
className="-translate-x-4 opacity-0"

// Duration: quick (200ms), Easing: out-quart
```

## Drill Forward / Back

**Spatial message:** "This is INSIDE that"

Navigating deeper into or back up the information hierarchy. Like drilling into a folder structure.

### When to use Drill Forward

- List item to detail view
- Parent to child navigation
- Breadcrumb drilling down
- Folder to contents

### When to use Drill Back

- Detail view back to list
- Back button pressed
- Breadcrumb clicking parent

### Key indicators

- **Drill Forward**: breadcrumbs would ADD a level, URL path gets longer
- **Drill Back**: breadcrumbs would REMOVE a level, URL path gets shorter

### Implementation

```jsx
// Drill Forward — new content from right
enterClass="translate-x-full opacity-0"
exitClass="-translate-x-1/3 opacity-50"

// Drill Back — parent returns from left
enterClass="-translate-x-1/3 opacity-50"
exitClass="translate-x-full opacity-0"

// Duration: normal (300ms), Easing: out-expo
```

## Layer

**Spatial message:** "This is ON TOP of that"

Content appears above existing content. The underlying content remains visible (often dimmed) to maintain context.

### When to use

- Modal dialogs
- Dropdown menus
- Tooltips and popovers
- Command palette (Cmd+K)
- Bottom sheets
- Context menus

### Key characteristics

- Backdrop / scrim present
- Dismissible by clicking outside
- Escape key closes it
- Does NOT change URL
- Focus should be trapped inside

### When to avoid

- Full page navigation (use Drill)
- Content replacement (use Fade)

### Implementation

```jsx
// Enter: scale up and fade in
className="scale-95 opacity-0"

// Active: full size and visible
className="scale-100 opacity-100"

// Duration: quick (200ms), Easing: out-quart
```

## Fade

**Spatial message:** "This REPLACES that"

Content crossfades in place with no spatial movement. Used when there's no meaningful spatial relationship.

### When to use

- Loading state to content
- Skeleton to real data
- Image swap
- Toast notifications
- State changes in place
- Error to success state

### When to avoid

- Navigation that implies direction (use Drill or Shared Axis)
- When spatial relationship matters

### Implementation

```jsx
// Enter and exit are just opacity
enterClass="opacity-0"
exitClass="opacity-100"

// Duration: quick (200ms), Easing: out-quart
// Keep it subtle — fade should feel almost instant
```

## Common scenarios

| Scenario | Pattern | Notes |
|---|---|---|
| Open modal from button | Layer | Standard overlay |
| Open modal from card | Container Transform | If card morphs into modal |
| Switch tabs | Shared Axis | Horizontal slide |
| List item → detail | Drill Forward | Push from right |
| Back button pressed | Drill Back | Return from left |
| Skeleton → content | Fade | In-place replacement |
| Show dropdown | Layer | Overlay near trigger |
| Carousel next | Shared Axis | Slide left |
| Toast appear | Fade | No spatial origin |

## Accessibility

Always respect `prefers-reduced-motion`:

```css
@media (prefers-reduced-motion: reduce) {
  * {
    transition-duration: 0.01ms !important;
  }
}
```

For essential animations that convey meaning (like drill direction), consider showing them but making them instant rather than removing them entirely.

## FAQ

**How do I choose between Container Transform and Drill?**

- **Container Transform**: a specific element (thumbnail, avatar, card) morphs into the destination
- **Drill**: the whole view transitions, no specific element continuity

If you can point to "this element becomes that element," use Container Transform. If it's general navigation, use Drill.

**Should dropdowns use Layer or Fade?**

**Layer.** Dropdowns are overlays that appear on top of content. Fade is for in-place content replacement where there's no "on top of" relationship.

**What duration should I use?**

- **Quick (200ms)**: most UI feedback (dropdowns, tooltips, tabs)
- **Normal (300ms)**: significant transitions (modals, page navigation)

Use the motion tokens: `duration-quick`, `duration-normal`.

**Can I combine patterns?**

Generally no. Each transition should use one pattern. The pattern choice communicates spatial meaning; mixing patterns confuses users about the relationship between states.

The exception is Container Transform, which may incorporate scaling/opacity similar to other patterns, but the differentiator is the shared element morph.

---

# Color: setting up your system

Source: https://presetai.dev/docs/product/studios/color
Type: guide
Summary: Four ways to start a color system, one staged review. Every candidate arrives named and scaled for light and dark; feeds to semantic roles are per-row opt-ins; contrast figures are measured, never estimated.
Last updated: 2026-06-10
Related: Typography Studio (https://presetai.dev/docs/product/studios/typography), Importing design systems (https://presetai.dev/docs/importing-design-systems)

---
owner: jschuyler
updated: '2026-06-10'
status: stable
---

export const metadata = {
  title: 'Color: setting up your system',
  description: 'Create a color system from a template, a description, an import, or a single hex. Colors land named, scaled, and unassigned; nothing is written until you keep it.',
  type: 'guide',
  summary: 'Four ways to start a color system, one staged review. Every candidate arrives named and scaled for light and dark; feeds to semantic roles are per-row opt-ins; contrast figures are measured, never estimated.',
  last_updated: '2026-06-10',
  related: ['/product/studios/typography', '/importing-design-systems'],
}

export const sections = [
  { title: 'The four ways to start', id: 'the-four-ways-to-start' },
  { title: 'The staged review', id: 'the-staged-review' },
  { title: 'What gets written', id: 'what-gets-written' },
  { title: 'Names and scales', id: 'names-and-scales' },
  { title: 'Tips', id: 'tips' },
]

# Color: setting up your system

Before a color system exists, the **Color** page offers four ways to start. All four land in the same place: a staged review of candidate colors, where nothing is written until you keep it.

## The four ways to start

| Lane | What it does |
|---|---|
| **Start from a template** | Pre-configured palettes (neutral first, brand forward, status complete) staged as candidates. |
| **Describe it** | Say what the product should feel like; AI proposes seed colors. An optional brand hex anchors the proposal. |
| **Import what exists** | Paste CSS custom properties, a Tailwind config, or a tokens JSON export; or choose a file. Your authored values become named, scaled candidates. |
| **Start from a hex** | One brand color generates a palette skeleton: a near-neutral anchored to your hue, the brand scale, and the status set. |

The lanes are equal: none of them is the "right" way, and every one ends in the same review.

## The staged review

Each candidate arrives:

- **Named.** A name is proposed from the color's hue family (like "iris" or "ember"). Rename anything inline; the name is the color's identity, and the system suggests alternatives without ever forcing one.
- **Scaled.** Twelve steps for light mode and twelve for dark, generated with perceptual OKLCH math. Step 9 is the solid: the canonical expression of the color.
- **Unassigned, with suggested feeds.** Some candidates carry a suggested role ("feed accent · 9"). Each suggestion is a per-row checkbox you can decline; a color without a feed simply lands in your palette, ready for later.

Imported values are kept as-is and pinned to their nearest steps; pinned steps carry a dot and survive regeneration. Contrast figures shown in the review are measured against the app background, never estimated.

Set aside anything that does not belong; bring it back if you change your mind. The footer states exactly what will be written before you commit.

## What gets written

**Make this your palette** writes:

- every kept color as a named palette color with both scales, and
- a semantic role for each feed you opted into.

Nothing else. Declined feeds and set-aside colors write nothing, and the baseline roles you did not feed wait in the studio with suggested feeds.

## Names and scales

- Scales are **fixed at 12 steps for both modes**: a system property, shared by every color, so that "step 9" means the same thing everywhere.
- Names are proposed at creation. If you later change a color's value across hue families, the studio suggests a rename and never forces one.

## Tips

- The import lane accepts CSS variables, Tailwind configs, Figma variable exports, Tokens Studio files, and Style Dictionary output. Auto-detection picks the parser.
- The describe lane proposes seeds only; every scale is generated locally with the same math as every other lane.
- If you only have one brand color, the hex lane builds a complete working skeleton you can refine in the studio.

---

# Icons Studio

Source: https://presetai.dev/docs/product/studios/icons
Type: guide
Summary: Import icons from Phosphor/Lucide/Heroicons, define semantic roles (delete, save, edit), set size tokens, sync to MCP.
Last updated: 2026-05-12
Related: Typography Studio (https://presetai.dev/docs/product/studios/typography), Agent resources (https://presetai.dev/docs/agent-resources)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Icons Studio',
  description: 'Manage your icon library and define semantic icon roles for consistent usage across your design system.',
  type: 'guide',
  summary: 'Import icons from Phosphor/Lucide/Heroicons, define semantic roles (delete, save, edit), set size tokens, sync to MCP.',
  last_updated: '2026-05-12',
  related: ['/product/studios/typography', '/agent-resources'],
}

export const sections = [
  { title: 'Getting started', id: 'getting-started' },
  { title: 'Icon sources', id: 'icon-sources' },
  { title: 'Icon roles', id: 'icon-roles' },
  { title: 'Size tokens', id: 'size-tokens' },
  { title: 'Default weight', id: 'default-weight' },
  { title: 'Preview tabs', id: 'preview-tabs' },
  { title: 'Exporting', id: 'exporting' },
  { title: 'Tips', id: 'tips' },
]

# Icons Studio

Manage your icon library and define semantic icon roles for consistent usage across your design system.

## Getting started

Icons Studio opens in **edit mode**: a focused workspace without the sidebar. Access it from the sidebar menu under **Icons**.

### Layout

| Panel | Purpose |
|---|---|
| **Left** | Configuration: icon sources, roles summary, size tokens, weight |
| **Right** | Preview and management: browse icons, manage roles, export code |
| **Bottom** | Status, export, and save |

## Icon sources

Import icons from popular libraries:

| Library | Icons | Weights |
|---|---|---|
| **Phosphor Icons** | 1,248 | 6 (thin, light, regular, bold, fill, duotone) |
| **Lucide Icons** | 1,400+ | Customizable stroke |
| **Heroicons** | 300+ | Outline & solid |
| **Custom SVG** | Your own | Varies |

### Adding an icon library

1. Click **Import existing** dropdown
2. Select a library (e.g., Phosphor Icons)
3. Library loads instantly with full icon manifest
4. Icons appear in the Browse tab

You can import multiple libraries: useful when migrating or comparing options.

## Icon roles

The core feature: map **semantic action names** to specific icons. This ensures:

- consistency across your codebase
- AI tools use the correct icons automatically
- clear vocabulary for your team

### Example roles

| Role | Icon | Description |
|---|---|---|
| `delete` | Trash | Permanently remove. Cannot be undone. |
| `remove` | MinusCircle | Remove from list. Can be re-added. |
| `cancel` | X | Stop operation, close dialog. |
| `save` | FloppyDisk | Save changes. |
| `edit` | PencilSimple | Edit content. |

### Categories

Roles are organized by category:

- **Destructive**: delete, remove, cancel, discard
- **Save**: save, submit, confirm
- **Navigation**: back, forward, menu, close
- **Edit**: edit, copy, paste, duplicate
- **User**: profile, settings, logout
- **Status**: success, error, warning, info

### Managing roles

1. Click **Manage roles** in the left panel (or select **Icon Roles** tab)
2. Select a category from the sidebar
3. View existing roles as cards
4. Click **+ Add Role** to create a new mapping
5. Edit role details: name, icon, description, severity

### Severity levels

Each role has a severity that affects icon color:

| Severity | Color | Use for |
|---|---|---|
| **Permanent** | Red | Destructive, irreversible actions |
| **Reversible** | Amber | Actions that can be undone |
| **Neutral** | Default | Standard actions |

## Size tokens

Define standard icon sizes:

| Token | Default | Use case |
|---|---|---|
| `xs` | 12px | Inline indicators, badges |
| `sm` | 16px | Buttons, form inputs |
| `md` | 20px | Default size |
| `lg` | 24px | Headers, emphasis |
| `xl` | 32px | Hero sections, empty states |

Edit sizes in the left panel. Values export as CSS custom properties.

## Default weight

Set the default weight for all icons:

| Weight | Style |
|---|---|
| **Thin** | Lightest stroke |
| **Light** | Subtle |
| **Regular** | Balanced (recommended) |
| **Bold** | Emphasis |
| **Fill** | Solid shapes |
| **Duotone** | Two-tone effect |

Individual roles can override the default weight.

## Preview tabs

| Tab | Purpose |
|---|---|
| **Browse** | Search and browse all icons in your library |
| **Icon Roles** | Manage semantic mappings by category |
| **In Context** | See icons in realistic UI patterns |
| **Code** | Export configurations |

## Exporting

Download icon configurations:

- **CSS Variables**: size tokens as custom properties
- **JSON Tokens**: full configuration in token format

Exports are available from the **Export** dropdown in the bottom toolbar.

### AI integration

Icon roles automatically sync to your MCP server. AI coding tools (Claude Code, Cursor, Windsurf) will:

- use `delete` role → Trash icon
- use `save` role → FloppyDisk icon
- apply correct size tokens
- respect weight settings

No manual configuration needed in AI tools. See [Agent resources](/agent-resources) for how this surfaces.

## Tips

1. **Start with one library**: Phosphor is recommended for its 6 weights
2. **Define roles early**: establish vocabulary before building UI
3. **Use categories**: group related actions for easier management
4. **Test in context**: use "In Context" tab to see icons in real UI
5. **Keep it simple**: 20-30 roles cover most applications
6. **Document severity**: help your team understand when to use destructive styling

---

# Typography Studio

Source: https://presetai.dev/docs/product/studios/typography
Type: guide
Summary: Add fonts (Google/URL/upload/system), map families to semantic roles, set scale ratio and fluid sizing, preview in Article/Dashboard/Marketing contexts.
Last updated: 2026-05-12
Related: Icons Studio (https://presetai.dev/docs/product/studios/icons), Typography health audit (https://presetai.dev/docs/product/health/typography-audit)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Typography Studio',
  description: 'Configure your design system\'s typography with real-time preview: fonts, families, scale, contexts.',
  type: 'guide',
  summary: 'Add fonts (Google/URL/upload/system), map families to semantic roles, set scale ratio and fluid sizing, preview in Article/Dashboard/Marketing contexts.',
  last_updated: '2026-05-12',
  related: ['/product/studios/icons', '/product/health/typography-audit'],
}

export const sections = [
  { title: 'Getting started', id: 'getting-started' },
  { title: 'Font sources', id: 'font-sources' },
  { title: 'Families', id: 'families' },
  { title: 'Scale', id: 'scale' },
  { title: 'Preview', id: 'preview' },
  { title: 'Saving and exporting', id: 'saving-and-exporting' },
  { title: 'Contexts', id: 'contexts' },
  { title: 'Tips', id: 'tips' },
]

# Typography Studio

Configure your design system's typography with real-time preview.

## Getting started

Typography Studio opens in **edit mode**: a focused workspace without the sidebar. Access it from the sidebar menu under **Typography**.

### Layout

| Panel | Purpose |
|---|---|
| **Left** | Configuration: font sources, families, scale, text styles |
| **Right** | Preview: see typography in realistic contexts |
| **Bottom** | Status, export, and save |

## Font sources

Add fonts from multiple sources:

- **Google Fonts**: search 1,500+ free fonts
- **URL / CDN**: Adobe Fonts, Fontshare, or custom CDN
- **Upload**: self-hosted `.woff2`, `.woff`, `.ttf` files
- **System Fonts**: native fonts with no loading time

### Adding Google Fonts

1. Click **+ Add font** in the Font Sources section
2. Select **Google Fonts**
3. Search by name or browse categories
4. Select weights to include (400, 500, 600, 700)
5. Click **Add**: font loads immediately

## Families

Map fonts to semantic roles:

| Role | Description | Example |
|---|---|---|
| **Headings** | H1, H6 text | Fraunces |
| **Body** | Paragraphs, UI text | Inter |
| **Mono** | Code blocks | JetBrains Mono |
| **Display** | Hero headlines | Fraunces |
| **UI** | Buttons, labels | Inter |
| **Accent** | Special emphasis | Fraunces |

**Tip:** Enable "Single font family" to use one font for all roles: common for minimal designs.

## Scale

Configure your type scale.

### Base size

The foundation: typically 16px for web. All other sizes derive from this.

### Scale ratio

How sizes grow between steps:

| Ratio | Name | Best for |
|---|---|---|
| 1.125 | Major Second | Dashboards, data-dense UIs |
| 1.200 | Minor Third | General apps |
| 1.250 | Major Third | Most websites (recommended) |
| 1.333 | Perfect Fourth | Editorial, marketing |
| 1.414 | Augmented Fourth | Landing pages |
| 1.618 | Golden Ratio | Maximum expression |

### Fluid sizing

Enable to automatically scale typography between viewport sizes. Typography smoothly transitions from mobile to desktop without breakpoints.

## Preview

The right panel shows your typography in context:

| Tab | Shows |
|---|---|
| **Article** | Long-form content with headings, body, and captions |
| **Dashboard** | Stats, tables, and UI elements |
| **Marketing** | Hero sections and feature grids |

### Preview controls

- **Light/Dark**: toggle background color
- **Mobile/Desktop**: test responsive sizing
- **Grid**: show baseline alignment

## Saving and exporting

### Save draft

Saves to your design system. Other team members won't see changes until published.

### Publish

Makes changes live for all team members and exports to connected tools.

### Export

Download typography as:

- **CSS Variables**: custom properties for web
- **JSON Tokens**: design token format for tools like Tokens Studio

## Contexts

Contexts let one design system vary by surface: Marketing, Editorial,
Slides, Email: while staying the same brand. The selector in the studio
header switches between them:

- **Base** is your brand truth. Editing on Base changes the design
  system itself.
- **Other contexts inherit from Base live.** A context stores only what
  you override there; everything else follows Base automatically: change
  a Base font and every context that didn't override it updates too.
- **Setting a value back to its Base value removes the override**, so the
  context resumes inheriting.

The switch is design-system-wide, not per-studio: picking a context here
moves Typography, Color, and Icons (and token views) to the same lens.
Use **Add context** in the selector to create a new one: it starts as a
transparent overlay on Base with no overrides.

## Tips

1. **Start with presets**: use "Import existing" to load curated starting points
2. **Preview often**: switch between Article/Dashboard/Marketing to catch issues
3. **Test both themes**: check light and dark mode
4. **Use fluid sizing**: eliminates most responsive typography issues
5. **Limit fonts**: 2-3 fonts maximum for cohesion

---

# Workspace Home

Source: https://presetai.dev/docs/product/workspace-home
Type: reference
Summary: Home answers three questions: where am I, what should I do next, is anything broken or disconnected?
Last updated: 2026-05-12
Related: Typography health audit (https://presetai.dev/docs/product/health/typography-audit), Key concepts (https://presetai.dev/docs/key-concepts)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Workspace Home',
  description: 'The Home surface as a lightweight workspace launchpad for a design system. Recent work, create CTAs, system status.',
  type: 'reference',
  summary: 'Home answers three questions: where am I, what should I do next, is anything broken or disconnected?',
  last_updated: '2026-05-12',
  related: ['/product/health/typography-audit', '/key-concepts'],
}

export const sections = [
  { title: 'Purpose', id: 'purpose' },
  { title: 'Experience model', id: 'experience-model' },
  { title: 'What Home should not do', id: 'what-home-should-not-do' },
  { title: 'Routing expectations', id: 'routing-expectations' },
  { title: 'Data requirements', id: 'data-requirements' },
]

# Workspace Home

The Home surface is a lightweight workspace launchpad for a design system.

## Purpose

Home should answer three questions quickly:

1. Where am I?
2. What should I do next?
3. Is anything broken or disconnected?

Home is not a full dashboard, integrations setup flow, or documentation hub.

## Experience model

### Primary zones

**1. Continue working**

- recent artifacts (last edited)
- in-progress items and drafts (when available)
- link to full activity / browse view

**2. Create**

- create token
- create preset
- create pattern

**3. System status (signals only)**

- health score + link to issues and audits
- MCP connection status + link to Connect
- code/repo connection status + link to Connect

**4. Context links**

- principles
- about
- team / contributors

**5. Other design systems (optional)**

- either bottom section in Home, or centralized switcher

## What Home should not do

- host full analytics workflows (Health owns this)
- host integration configuration flows (Integrate owns this)
- become a docs content index (Use / Docs owns this)

## Routing expectations

Home should link out to deeper workflows:

- continue item → artifact-specific editor / browse route
- create CTA → creation route
- health signal → Health Dashboard / Audits
- connection signals → Connect / Integrate routes

## Data requirements

Home needs fast summary data:

- design system identity (name, optional description)
- counts (presets, tokens, patterns)
- recent artifacts with type + timestamp (+ draft/published where supported)
- health score and top issue count
- MCP connection status
- code connection status

---

# Scan your repo

Source: https://presetai.dev/docs/scan
Type: guide
Summary: Run the scanner on your codebase. Extract tokens, patterns, and candidate presets.
Last updated: 2026-05-11
Related: Review what was extracted (https://presetai.dev/docs/extract), Why the memory layer matters (https://presetai.dev/docs/memory-layer)
Install: preset scan

---
owner: jschuyler
updated: '2026-06-20'
status: stable
---

export const metadata = {
  title: 'Scan your repo',
  description: 'Run the scanner on your codebase. preset AI extracts tokens, patterns, and candidate presets without touching your code.',
  type: 'guide',
  summary: 'Run the scanner on your codebase. Extract tokens, patterns, and candidate presets.',
  last_updated: '2026-05-11',
  related: ['/extract', '/memory-layer'],
  install_command: 'preset scan',
}

export const sections = [
  { title: 'Before you start', id: 'before-you-start' },
  { title: 'Run the scanner', id: 'run-the-scanner' },
  { title: 'What it found', id: 'what-it-found' },
  { title: "What's next", id: 'whats-next' },
]

# Scan your repo

Point preset AI at your codebase. The scanner reads your component tree, extracts tokens and patterns, and writes a first-draft `preset.yaml` you can review. Nothing is modified; nothing is committed.

## Before you start

You need Node 20 or later and a repo with a component library. preset AI recognizes:

- **Component libraries**: shadcn/ui, Radix, Chakra, Material UI, Ant Design, HeroUI, DaisyUI.
- **Token sources**: Tailwind config, CSS custom properties, Style Dictionary output, Figma Variables exports.
- **Pattern inputs**: Storybook stories, your own MDX documentation, fixture files.

The scanner is read-only. It does not write into your `src/` tree. The only file it creates is `preset.yaml` at the repo root: which you can delete or move if you want it elsewhere.

## Run the scanner

From your repo root:

```bash
preset scan
```

On the first run the CLI bootstraps its cache under `.preset/` (added to `.gitignore` automatically) and writes `preset.yaml`.

Typical output:

```
✓ Scanning ./src/components .......... 42 components
✓ Extracting tokens ................... 128 tokens
✓ Identifying patterns ................ 17 patterns

✓ Writing preset.yaml ................. done

Review at https://presetai.dev/dashboard
```

For a detailed scan with per-component breakdowns, pass `--verbose`. To restrict to one component, `--component Button`. Every flag is documented in the [CLI reference](https://developers.presetai.dev/cli/scan).

<Note>
The scanner uses static analysis, not AI. It reads your code as an AST and matches known shapes. That means it is fast, deterministic, and free to run: no API key required for the scan itself.
</Note>

## What it found

`preset.yaml` is the human-readable output. It has three top-level sections:

- `tokens`: colors, spacing, typography, radii, and shadows, grouped by category with confidence scores.
- `patterns`: recurring shapes in your component tree (e.g. "button + icon", "form field with label + helper + error").
- `proposals`: presets the scanner suggests based on patterns that appeared three or more times.

Confidence is a number between 0 and 1. High-confidence entries are ones the scanner is sure about: exact matches on known library patterns, for example. Low-confidence entries are candidates that need your eyes.

You don't have to accept anything. The next step is where you decide what becomes part of your memory layer.

## What's next

<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-3 mt-6">
  <a href="/docs/extract" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Review what was extracted</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Confirm, edit, or reject. Decide what becomes canonical.</p>
  </a>
  <a href="https://developers.presetai.dev/cli/scan" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Reference</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">preset scan (all flags)</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Every flag documented on the developers site.</p>
  </a>
</div>

---

# Snapshot a PDF

Source: https://presetai.dev/docs/snapshot-pdf
Type: guide
Summary: Scan a brand-guidelines PDF to extract its declared tokens. Useful for agencies onboarding a client.
Last updated: 2026-05-25
Related: Snapshot a URL (https://presetai.dev/docs/snapshot-url), Scan your repo (https://presetai.dev/docs/scan), Review what was extracted (https://presetai.dev/docs/extract)
Install: preset snapshot --pdf brand-guidelines.pdf

---
owner: jschuyler
updated: '2026-06-20'
status: stable
---

export const metadata = {
  title: 'Snapshot a PDF',
  description: 'Bootstrap a starter design system from a brand-guidelines PDF. preset AI reads declared token literals from the text and infers the rest per page via vision.',
  type: 'guide',
  summary: 'Scan a brand-guidelines PDF to extract its declared tokens. Useful for agencies onboarding a client.',
  last_updated: '2026-05-25',
  related: ['/snapshot-url', '/scan', '/extract'],
  install_command: 'preset snapshot --pdf brand-guidelines.pdf',
}

export const sections = [
  { title: 'When to use the PDF lane', id: 'when-to-use' },
  { title: 'Run the snapshot', id: 'run-the-snapshot' },
  { title: 'What the scanner captures', id: 'what-it-captures' },
  { title: 'What it cannot capture', id: 'what-it-cannot-capture' },
  { title: 'Accuracy expectations', id: 'accuracy-expectations' },
  { title: 'How the four lanes compare', id: 'comparing-lanes' },
  { title: "What's next", id: 'whats-next' },
]

# Snapshot a PDF

Point preset AI at a brand-guidelines PDF. The scanner reads the text for declared hex literals ("Cobalt, #1F47FF"), rasterizes each page, and runs vision-per-page to infer everything the text doesn't declare. The result is the same `DesignSystemSnapshot` shape the other lanes produce, primitives, semantic tokens, type styles, spacing rhythm, ready to refine into your own system.

## When to use the PDF lane

The PDF lane is the right starting point when:

- You're an agency onboarding a client who has a brand-guidelines PDF but no public site or codebase yet.
- You have a brand book that declares colors, type, and spacing in text alongside the visual examples.
- You want exact hex values, not vision-inferred approximations, where the document declares them.

If you have a repo, prefer the [codebase lane](/scan). If you have a live site, prefer the [URL lane](/snapshot-url). The PDF lane is best for the brand-book-handoff case.

## Run the snapshot

From your terminal:

```bash
preset snapshot --pdf brand-guidelines.pdf
```

Typical output:

```
✓ Reading brand-guidelines.pdf and capturing tokens per page...
✓ Snapshot generated in 42,180ms

Coherence score: 71 / 100
Colors:        14 primitives, 6 semantic roles
Typography:    4 type styles
Spacing:       6 distinct values
```

### Flags

| Flag | Default | What it does |
| -- | -- | -- |
| `--pdf <path>` | required | The PDF file to snapshot. |
| `--output <file>` | stdout | Write the snapshot JSON or narrative to a file instead of stdout. |
| `--format <type>` | `narrative` | `narrative` for a readable summary, `json` for the full snapshot. |
| `--vision-model <model>` | `gemini-2.5-pro` | Vision model for the per-page inference. Same model set as the [image lane](#what-it-captures). |
| `--threshold <n>` | `1` | Minimum usage count to keep a token. |
| `--color-threshold <n>` | `0.005` | Cluster distance threshold (0-1). |
| `-v, --verbose` | off | Print per-stage timing and observation counts. |

<Note>
The PDF lane is also available from the workspace dashboard at **Bootstrap → Source**. The same scanner runs server-side; you don't need a local pdfjs install for the dashboard flow.
</Note>

## What the scanner captures

The PDF lane runs two passes and merges them:

1. **Text mining.** The scanner extracts every text run, looks for `#RRGGBB` and `#RGB` literals, and walks the immediately-preceding words for a label. A run like "Cobalt, #1F47FF" gives a token named `cobalt` with exact value `#1F47FF`, surfaced as `pdfDeclaredNames` on the snapshot. Declared values are authoritative, they aren't re-inferred from pixels.
2. **Per-page vision.** Each page is rasterized at 144 DPI and passed through the image lane's vision-LLM + pixel-histogram pipeline. The model identifies palette, type styles, and spacing rhythm visible on the page. The pixel histogram grounds the LLM's color claims against actual page pixels.

The two passes are merged field-by-field: text-declared tokens win on hex values; vision-inferred tokens fill in everything the text didn't claim.

### Page cap

By default, the scanner processes the first 15 pages and stops. A typical brand book is 20-40 pages; the first 15 carry the brand-system content (palette, type, logo). Cover pages and voice/copy pages add no token signal.

### Vision-per-page cost

Each page makes one LLM call. On Gemini 2.5 Flash that's ~$0.005 per page; on Gemini 2.5 Pro it's higher (the default favors quality over cost). For a 15-page PDF, expect ~$0.07 on Pro or ~$0.075 total on Flash. The CLI never sends pages to a model you didn't pick.

## What it cannot capture

| Limitation | Why | Workaround |
| -- | -- | -- |
| Scanned/OCR-only PDFs | Text mining needs real text runs; OCR-on-rendering is unreliable | Use a vector-PDF source (export from Figma, Keynote, or InDesign) |
| Encrypted PDFs | pdfjs can't read encrypted streams | Unlock the file before snapshotting |
| Multi-PDF inputs | V1 processes one PDF per command | Run twice and merge by hand, or pick the canonical brand book |
| Component identity | The scanner sees pages, not components | Use the [codebase lane](/scan) once the system has a codebase |
| Animations, interactions | A PDF is a static document | Use the [URL lane](/snapshot-url) once there's a built product |

## Accuracy expectations

The PDF lane mixes two signal qualities. Trust them differently:

1. **Text-declared hexes are exact.** If the PDF says `#1F47FF`, the snapshot value is `#1F47FF`. The label recovered from the surrounding words ("Cobalt", "Primary Blue") is also high-confidence: it's literally what the brand team wrote.
2. **Vision-inferred tokens carry the image lane's caveats.** Vision is good at "what palette is on this page" and "what type styles appear"; it's noisier on exact spacing values and unable to capture component identity. Treat vision-inferred values as starting points to confirm, not as ground truth.
3. **Coherence scores apply per-document, not across documents.** A 71/100 from one brand book isn't directly comparable to a 71/100 from another. The score reflects internal consistency of what the scanner observed, not absolute design-system maturity.

For most brand-book bootstraps, the PDF lane gives you a workable starter system in ~30-60 seconds for a 15-page document.

## How the four lanes compare

| | Codebase | URL | Image | PDF |
| -- | -- | -- | -- | -- |
| **Input** | Repo directory | `https://...` | PNG, JPG, or screenshot | `brand.pdf` |
| **What it reads** | AST of components + token sources | Computed styles of every visible element | Pixels via vision LLM + histogram | Text-declared hexes + per-page vision |
| **Symbolic names** | Direct from source | Recovered from stylesheets (best effort) | Inferred from labels in the image | Mined from text adjacent to hex literals |
| **Component identity** | Yes | No | No | No |
| **Coherence scores** | Source-level (truth) | Render-level (observation) | Inference-level (estimate) | Mixed (text exact, vision estimate) |
| **Best for** | Your own product, deep audit | Reference products, agency onboarding | Brand decks, moodboards, single screens | Brand guidelines, agency client onboarding |
| **Speed** | ~5s for a mid-size repo | 10-30s per page | 5-10s per image | ~30-60s for 15 pages |
| **Cost** | Free | Free locally; Browserless quota on the dashboard | LLM tokens (~$0.001 per scan with Gemini Flash) | LLM tokens (~$0.005/page on Flash, hard cap at 15 pages) |

## What's next

<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-3 mt-6">
  <a href="/docs/extract" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Review the snapshot</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Confirm tokens, edit primitives, set semantic roles. Decide what becomes canonical.</p>
  </a>
  <a href="/docs/snapshot-url" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Snapshot a URL</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Already have a live product? The URL lane reads computed styles in 10-30 seconds.</p>
  </a>
</div>

---

# Snapshot a URL

Source: https://presetai.dev/docs/snapshot-url
Type: guide
Summary: Scan a live URL to extract its computed design tokens. Useful when there is no codebase to scan.
Last updated: 2026-05-24
Related: Scan your repo (https://presetai.dev/docs/scan), Review what was extracted (https://presetai.dev/docs/extract)
Install: preset snapshot --url https://example.com

---
owner: jschuyler
updated: '2026-06-20'
status: stable
---

export const metadata = {
  title: 'Snapshot a URL',
  description: 'Bootstrap a starter design system from a rendered web page. preset AI captures the computed-style fingerprint of any public URL and turns it into tokens you can refine.',
  type: 'guide',
  summary: 'Scan a live URL to extract its computed design tokens. Useful when there is no codebase to scan.',
  last_updated: '2026-05-24',
  related: ['/scan', '/extract'],
  install_command: 'preset snapshot --url https://example.com',
}

export const sections = [
  { title: 'When to use the URL lane', id: 'when-to-use' },
  { title: 'Run the snapshot', id: 'run-the-snapshot' },
  { title: 'What the scanner captures', id: 'what-it-captures' },
  { title: 'What it cannot capture', id: 'what-it-cannot-capture' },
  { title: 'Accuracy expectations', id: 'accuracy-expectations' },
  { title: 'robots.txt and the user agent', id: 'robots-and-ua' },
  { title: 'How the three lanes compare', id: 'comparing-lanes' },
  { title: "What's next", id: 'whats-next' },
]

# Snapshot a URL

Point preset AI at a public URL. The scanner renders the page in headless Chromium, walks every visible element, and synthesizes a `DesignSystemSnapshot` you can refine into your own design system. Useful when you do not have a codebase to scan: agencies onboarding from a client's live product, brand teams capturing a launched site, designers extracting tokens from a reference.

## When to use the URL lane

| You have | Pick |
| -- | -- |
| A repo with components and tokens in source | The [codebase lane](/scan) |
| A live URL but no source access | The URL lane (this page) |
| A brand-guidelines PDF | The [PDF lane](/snapshot-pdf) |
| A screenshot or moodboard image | The image lane (see [comparison](#comparing-lanes)) |

The four lanes produce the same shape of output. They differ in what signal they can reach. The URL lane is the only one that captures **rendered** values: what the browser actually paints, including resolved CSS variables, theme overrides, and runtime-computed styles.

## Run the snapshot

From your terminal:

```bash
preset snapshot --url https://stripe.com
```

The first run downloads Chromium via Playwright (~120MB, one-time). After that, a snapshot typically completes in 10-30 seconds depending on the page.

Typical output:

```
✓ Rendering stripe.com and capturing computed styles...
✓ Snapshot generated in 18,420ms (3,847 nodes visited)

Coherence score: 67 / 100
Colors:        24 primitives, 8 semantic roles
Typography:    6 type styles
Spacing:       8 distinct values
Components:    37 candidate patterns
```

### Flags

| Flag | Default | What it does |
| -- | -- | -- |
| `--url <url>` | required | The URL to snapshot. Must start with `http://` or `https://`. |
| `--output <file>` | stdout | Write the snapshot JSON or narrative to a file instead of stdout. |
| `--format <type>` | `narrative` | `narrative` for a readable summary, `json` for the full snapshot. |
| `--threshold <n>` | `1` | Minimum usage count to keep a token. Filters out one-off observations. |
| `--color-threshold <n>` | `0.005` | Cluster distance threshold (0-1). Lower = more granular palette. |
| `--ignore-robots` | off | Skip the robots.txt pre-flight. Use only for sites you own. |
| `-v, --verbose` | off | Print per-stage timing and observation counts. |

<Note>
The URL lane is also available from the workspace dashboard at **Bootstrap → Source**. The same scanner runs server-side via Browserless; you don't need a local Chromium for the dashboard flow.
</Note>

## What the scanner captures

For every visible element on the page, the scanner reads the computed-style values for these properties:

- **Color**: `color`, `background-color`, the four `border-*-color` channels, plus SVG `fill` and `stroke` (filtered to elements actually inside an `<svg>` so unrelated nodes don't pollute the palette).
- **Radius**: the four `border-*-radius` corners.
- **Typography**: `font-family`, `font-size`, `font-weight`, `line-height`, `letter-spacing`.
- **Spacing**: `padding-top/right/bottom/left`, `margin-top/right/bottom/left`, `gap`, `row-gap`, `column-gap`.
- **Effects**: `box-shadow`.

Each observation carries a **surface context**, element tag, parent tag, class list, ARIA role, position type, viewport coverage, which the surface-type classifier uses downstream to distinguish core-UI tokens from illustration, brand, marketing, and data-viz palettes. The primitive palette comes from core-UI observations only, so a brand wordmark or a chart's color scheme cannot accidentally become a primitive.

### Visibility filter

Hidden elements are skipped. An element is visible if it has `display !== 'none'`, `visibility !== 'hidden'`, `opacity > 0`, and a non-zero bounding box.

### Scroll-and-wait

After initial network-idle, the scanner scrolls the page in 200px increments (up to 6 seconds) to fire lazy-loaded content, then settles for 1.5s before sampling. Pages with heavy hero animations or `IntersectionObserver`-driven content reveal will still be captured.

### CSS-variable name recovery

The scanner also reads every accessible stylesheet's source CSS and recovers symbolic variable names (`--brand-primary`, `--surface-bg`) so that a captured `rgb(99, 102, 241)` traces back to its declared name. Cross-origin stylesheets are fetched server-side. Sites that declare tokens on `:root` (shadcn/ui, most design-token codebases) get high recovery rates.

## What it cannot capture

| Limitation | Why | Workaround |
| -- | -- | -- |
| Auth-gated pages | The scanner has no session cookies | Snapshot a public page on the same product, or use the codebase lane |
| Content inside `<iframe>` | Same-origin only; cross-origin frames refuse access | Snapshot the iframed page directly |
| Component identity | The scanner sees rendered DOM, not the React/Vue component tree | Use the codebase lane for component-level analysis |
| Behind a paywall, captcha, or geofence | Same as auth-gated | Snapshot a comparable open page |
| Single-page-app routes that need interaction | The scanner waits for network-idle but does not click | Pass the deep URL of the loaded view |

## Accuracy expectations

The URL lane gives you the **rendered** view, not the **source** view. Two things to keep in mind when comparing a URL snapshot to a codebase snapshot of the same product:

1. **Values are computed, not symbolic.** A button with `background: var(--brand-primary)` shows up as `rgb(99, 102, 241)` until variable-name recovery resolves it. Recovery works for `:root`-declared variables on accessible stylesheets; theme-scoped overrides (`.dark { --brand-primary: ... }`) won't always round-trip.
2. **Coherence scores will differ.** The codebase lane sees `bg-primary` 47 times across `Button`, `Link`, and `Badge` and reports high reuse. The URL lane sees 47 instances of `rgb(99, 102, 241)` and reports it as a frequently-observed color. Both are true; they measure different things. Don't compare scores across lanes: they're not the same metric.
3. **Rendered state is a moment in time.** The page you snapshot today may show different content tomorrow. The tokens it exposes (palette, type scale, spacing rhythm) are usually stable; the specific observation counts are not.

For most use cases, bootstrapping a starter DS from a live product, capturing a reference, comparing two brands, the URL lane gives you the right starting point in a few seconds. For deep audit work on your own product, prefer the codebase lane.

## robots.txt and the user agent

The scanner identifies itself with the user-agent token `PresetBootstrapper`. Before rendering, it consults `<origin>/robots.txt` and respects `Disallow` rules. If the target path is disallowed, the scan returns a structured opt-out (exit 0 on CLI, 403 `robots_opt_out` on the API): not a failure.

If your site uses preset AI internally and you want to allowlist the scanner:

```text
User-agent: PresetBootstrapper
Allow: /
```

If you want to block the scanner:

```text
User-agent: PresetBootstrapper
Disallow: /
```

If your robots.txt is missing, empty, or unreachable, the scanner treats that as "no restrictions stated" per the Robots Exclusion Protocol: it does not punish a flaky CDN.

The CLI's `--ignore-robots` flag bypasses the check. It exists for the user's own sites (private staging, internal tools where robots.txt is generic) and is intentionally not exposed in the web UI.

## How the four lanes compare

| | Codebase | URL | Image | PDF |
| -- | -- | -- | -- | -- |
| **Input** | Repo directory | `https://...` | PNG, JPG, or screenshot | `brand.pdf` |
| **What it reads** | AST of components + token sources | Computed styles of every visible element | Pixels via vision LLM + histogram | Text-declared hexes + per-page vision |
| **Symbolic names** | Direct from source | Recovered from stylesheets (best effort) | Inferred from labels in the image | Mined from text adjacent to hex literals |
| **Component identity** | Yes | No | No | No |
| **Coherence scores** | Source-level (truth) | Render-level (observation) | Inference-level (estimate) | Mixed (text exact, vision estimate) |
| **Best for** | Your own product, deep audit | Reference products, agency onboarding | Brand decks, moodboards, single screens | Brand guidelines, agency client onboarding |
| **Speed** | ~5s for a mid-size repo | 10-30s per page | 5-10s per image | ~30-60s for 15 pages |
| **Cost** | Free | Free locally; Browserless quota on the dashboard | LLM tokens (~$0.001 per scan with Gemini Flash) | LLM tokens (~$0.005/page on Flash, hard cap at 15 pages) |

The [PDF lane](/snapshot-pdf) is the most recent addition. Pick it when you have a brand-guidelines PDF but no public site or codebase yet.

## What's next

<div className="not-prose grid grid-cols-1 md:grid-cols-2 gap-3 mt-6">
  <a href="/docs/extract" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Review the snapshot</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">Confirm tokens, edit primitives, set semantic roles. Decide what becomes canonical.</p>
  </a>
  <a href="/docs/scan" className="group rounded-[2px] border border-border p-4 hover:border-muted-foreground/50 transition-colors block">
    <div className="text-[11px] text-muted-foreground mb-1">Guide</div>
    <div className="text-[14px] font-medium text-foreground mb-1.5 group-hover:underline underline-offset-2">Snapshot a codebase</div>
    <p className="text-[12px] leading-[1.5] text-muted-foreground">When you have the source repo, the codebase lane sees more.</p>
  </a>
</div>

---

# Updating design systems

Source: https://presetai.dev/docs/updating-design-systems
Type: guide
Summary: Re-scan a source you already imported; preset AI shows a diff of added, modified, and removed tokens before applying.
Last updated: 2026-05-12
Prerequisites: Importing design systems (https://presetai.dev/docs/importing-design-systems)
Related: Importing design systems (https://presetai.dev/docs/importing-design-systems)

---
owner: jschuyler
updated: '2026-05-12'
status: stable
---

export const metadata = {
  title: 'Updating design systems',
  description: 'Re-import to see exactly what changed before applying updates. Diff added, modified, and removed tokens before they land.',
  type: 'guide',
  summary: 'Re-scan a source you already imported; preset AI shows a diff of added, modified, and removed tokens before applying.',
  last_updated: '2026-05-12',
  prerequisites: ['/importing-design-systems'],
  related: ['/importing-design-systems'],
}

export const sections = [
  { title: 'Overview', id: 'overview' },
  { title: 'Updating from source', id: 'updating-from-source' },
  { title: 'Understanding the diff', id: 'understanding-the-diff' },
  { title: 'Resolving conflicts', id: 'resolving-conflicts' },
  { title: 'Partial updates', id: 'partial-updates' },
  { title: 'Best practices', id: 'best-practices' },
  { title: 'Troubleshooting', id: 'troubleshooting' },
  { title: 'FAQ', id: 'faq' },
]

# Updating design systems

Keep your design system in sync with its source. When your team updates tokens, colors, or typography, re-import to see exactly what changed before applying.

## Overview

Instead of blindly replacing tokens, preset AI shows you a diff of all changes:

- **Added**: new tokens in the source
- **Modified**: tokens with changed values
- **Removed**: tokens no longer in the source
- **Unchanged**: tokens that match exactly

You choose which changes to apply. Local customizations are preserved.

## Updating from source

1. Go to **Design Systems** in the sidebar
2. Open the design system you want to update
3. Click **Update from Source**
4. Select your source (GitHub, GitLab, or upload)
5. Enter the same repository URL or upload an updated zip
6. Click **Scan for Changes**
7. Review the diff
8. Select changes to apply
9. Click **Apply Changes**

## Understanding the diff

### Summary view

At the top you'll see a summary of all changes:

```
+ 3 new tokens
~ 5 modified tokens
- 2 removed tokens
= 18 unchanged tokens
```

### Added tokens

Tokens that exist in the source but not in your design system.

| Action | Result |
|---|---|
| **Include** (default) | Token will be added |
| **Exclude** | Token will not be imported |

### Modified tokens

Tokens that exist in both but with different values.

| Action | Result |
|---|---|
| **Use source** | Update to the new value from source |
| **Keep current** | Keep your existing value |
| **Custom** | Enter a different value |

Example:

```
primary
  Current:  #3b82f6
  Source:   #2563eb
```

### Removed tokens

Tokens in your design system that no longer exist in the source.

| Action | Result |
|---|---|
| **Remove** | Delete the token |
| **Keep** (default) | Preserve the token |
| **Deprecate** | Mark as deprecated but keep |

<Note>
preset AI warns you if a removed token is used by any presets: removing it may break those presets.
</Note>

### Unchanged tokens

Tokens with identical values in both. Collapsed by default since no action is needed. Click **Show unchanged** to expand the full list.

## Resolving conflicts

A conflict occurs when a token has been modified both locally (in preset AI) and in the source:

```
Conflict: primary
  Original (at last import):  #3b82f6
  Your changes:               #2563eb  (darker)
  Source changes:             #0ea5e9  (different hue)
```

### Resolution options

| Option | When to use |
|---|---|
| **Use source** | Source value should override your changes |
| **Keep yours** | Your local modification should be preserved |
| **Use custom value** | You want a different value than either |

preset AI tracks the original imported value, so it can detect when both sides have changed.

## Partial updates

You don't have to apply all changes at once.

### Accept only additions

1. Uncheck all modified and removed tokens
2. Keep all added tokens checked
3. Apply to get new tokens without affecting existing ones

### Review modifications individually

1. Expand each modified token
2. Compare current vs source values
3. Decide each one based on which value is correct

### Keep all local changes

1. Uncheck all changes
2. Cancel the update
3. Your design system remains unchanged

## Best practices

### Before updating

- **Note your customizations**: if you've made local changes, write them down so you can make informed decisions during the diff review
- **Check preset usage**: if removing tokens, check which presets use them first

### During review

- **Review modified tokens carefully**: value changes can be subtle but important
- **Check dark mode values**: a token might be unchanged in light mode but different in dark mode
- **Read the change type**: "value" means the color changed; "both-modes" means light and dark both changed

### After updating

- **Verify presets**: check that your presets still look correct with the new tokens
- **Export if needed**: re-export your design system to update your codebase

## Troubleshooting

### "No changes detected"

The source tokens are identical to your current design system.

- Verify you're scanning the correct repository/branch
- Check if the source was actually updated
- Look at the "Unchanged" section to confirm tokens match

### "Conflict not detected"

preset AI may not have recorded the original value at import time.

- This typically only affects tokens imported before provenance tracking was added
- Manually compare values and choose the correct one

### "Removed token is used by presets"

You're about to remove a token that presets depend on.

- Update the presets to use a different token first
- Keep the token instead of removing it
- Replace the token with an equivalent value

## FAQ

### Does updating overwrite my entire design system?

No. Only the changes you select are applied. Unselected changes are ignored.

### Can I undo an update?

There's no automatic undo. We recommend noting your current values before making significant changes.

### What if I want to reset to the source exactly?

Select all added, modified, and removed tokens (including removals), then apply. Your design system matches the source exactly.

### How does preset AI know which tokens I modified locally?

preset AI tracks "provenance": the original value at import time. When you edit a token, it compares against this original to detect local modifications.

### Can I update from a different source than I originally imported?

Yes, but the diff will compare against your current tokens regardless of where they came from. This can result in more "added" and "removed" tokens than expected.