Uselayout Cli

@layoutdesign/context

Give your AI agent a design system in one command.

[](https://www.npmjs.com/package/@layoutdesign/context) [](./LICENSE) [](https://nodejs.org)

An MCP server and CLI that gives AI coding agents structured design system context — tokens, components, rules — so they produce on-brand UI instead of generic code.

---

Quick Start

Get set up in 60 seconds.

# Initialise your project with a starter kit
npx @layoutdesign/context init --kit linear-lite

# Auto-configure your AI coding agent
npx @layoutdesign/context install

# Add a pre-built, token-contracted UI component
npx @layoutdesign/context add button

That's it. The install command detects Claude Code, Cursor, Windsurf, VS Code / Copilot, Codex CLI, and Gemini CLI automatically and configures the MCP server.

Your agent now has access to your full design system on every request.

---

Layout UI components

Layout UI is a reskinnable component system: 50+ token-contracted primitives (button, card, dialog, data-table…) where every gallery kit is a theme. The components stay the same; swap the theme and they take on a whole new brand. Your AI agent can discover them with the list-ui-components MCP tool and install them without writing primitives from scratch.

There are two ways to install a component:

# 1. The Layout CLI — resolves registry + npm deps and merges theme variables
npx @layoutdesign/context add button card dialog

# 2. The stock shadcn CLI — point it at the Layout registry
npx shadcn@latest add https://ui.staging.layout.design/r/button.json

Apply any published gallery kit as a theme by pulling its theme.json:

npx shadcn@latest add https://layout.design/r/stripe/theme.json

Browse the full catalogue at ui.staging.layout.design.

---

What It Does

AI coding agents don't know your design system. They produce UI that looks generic, uses hardcoded colours, ignores your spacing scale, and references components that don't exist.

@layoutdesign/context solves this by exposing your design system — tokens, components, rules — as MCP tools. Your agent calls get_design_system before writing UI, get_tokens when it needs exact values, and check_compliance before it finishes. The result is on-brand code from the first attempt.

---

MCP Tools

Eleven tools are registered with the MCP server automatically.

| Tool | Description | |------|-------------| | get_design_system | Returns the full layout.md, or a filtered section (colours, typography, spacing, components). Use this before writing any UI. | | get_tokens | Returns design tokens in CSS custom properties, W3C DTCG JSON, or Tailwind config format. | | get_component | Returns the spec and code example for a named component. | | list_components | Lists all components defined in the active kit, plus auto-detected codebase and Storybook components. | | list-ui-components | Lists the pre-built, token-contracted Layout UI components installable from the registry, with an add command and usage/never rules for each. Use before writing UI primitives from scratch. | | check_compliance | Validates a code snippet against the design system — flags hardcoded colours, bad spacing, unknown tokens, and unrecognised components. | | preview | Pushes a component to the local live preview canvas at localhost:4321. Requires the preview server to be running. | | push_to_figma | Bridges to the Figma MCP server to create an editable Figma frame from component code. Requires Figma MCP to be configured separately. | | design_in_figma | Takes a natural language prompt (e.g. "A pricing card with 3 tiers") and returns design tokens, component specs, and step-by-step instructions for calling Figma MCP's generate_figma_design. Enables AI agents to design in Figma before writing code. Inputs: prompt (required), fileKey (optional), viewports (optional: desktop/tablet/mobile). | | url_to_figma | Captures a live website URL as editable Figma frames with auto-layout. Inputs: url, viewports, outputMode (newFile/existingFile/clipboard), fileKey. Requires both Figma MCP and Playwright MCP servers. | | update_tokens | Updates token values in tokens.css, tokens.json, and layout.md simultaneously. Use when tweaking colours, spacing, or other tokens without re-extracting. Keeps the entire design system consistent. |

---

Live integration (preview)

> Added in v0.7.0. Pairs with the layout Live desktop app.

When the layout Live desktop app is running, four extra MCP tools give your AI coding agent context on what you're doing visually:

| Tool | Description | |------|-------------| | get-selected-element | Returns the element currently selected in Live. Use when the user says "this" or "that one". Returns { running: false } if Live isn't running. | | get-recent-visual-edits | Recent class/token/inline-style edits. Reads Live's socket when running; falls back to the on-disk .layout/live/recent-edits.json log otherwise — so it's useful even when Live is closed. | | get-pending-requests | Free-text changes the user pinned to elements/regions in Live ("make this the primary CTA"). Reads Live's socket when running; falls back to .layout/live/requests.json otherwise. Use when the user says "apply my requests" or "do the things I flagged". | | lock-file | Reserves exclusive write access to a file before editing, so Claude and Live don't clobber each other. | | unlock-file | Releases a previously-acquired lock. |

These tools register unconditionally and degrade gracefully: if Live isn't running they return cleanly-typed "not running" responses rather than errors. File locks are coordinated atomically via .layout/live/locks.json (gitignore it in your project). check-setup also reports Live's status under a new live field. Live communicates over a local Unix socket — nothing is sent over the network.

---

Build plugins (preview)

> Added in v0.8.0. Power layout Live's click-to-source resolution.

Two zero-config build plugins inject data-layout-source-* attributes into your JSX in dev only (no-ops in production), so layout Live can map any clicked DOM element straight back to its source file, line, and component. They ship as sub-exports — no extra npm install.

Vite:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import layout from "@layoutdesign/context/vite-plugin";

export default defineConfig({
  plugins: [layout(), react()], // layout() must come before react()
});

Next.js:

// next.config.ts
import withLayout from "@layoutdesign/context/next-plugin";

export default withLayout({
  // ...your next config (an existing webpack() override is preserved)
});

Or let the CLI wire it up for you (detects the framework, edits the config with recast so formatting and comments survive, backs the original up first, scaffolds .layout/live/, and augments CLAUDE.md):

npx @layoutdesign/context install --live

Re-running install --live is idempotent. Both plugins skip Fragments, capitalised components, and pre-attributed elements, and preserve source maps so stack traces still point at your real line numbers.

---

CLI Commands

| Command | Description | |---------|-------------| | init | Initialise .layout/ in the current directory, optionally with a starter kit. | | init --kit | Initialise with a specific kit (e.g. linear-lite). | | serve | Start the MCP server. This is what your AI agent connects to. | | install | Auto-configure MCP settings for Claude Code, Cursor, Windsurf, VS Code / Copilot, Codex CLI, and Gemini CLI. | | install --target | Target a specific tool: claude, cursor, windsurf, vscode, codex, or gemini. | | install --global | Install globally so the MCP server is available in all projects (Claude Code only). | | doctor | Check Node.js version, AI tool CLIs, and MCP dependencies (Figma, Playwright). Use --fix to auto-install any missing tools. | | doctor --fix | Auto-install missing dependencies (Figma MCP, Playwright MCP). | | serve-local | Serve a local directory over HTTP for use with the url-to-figma MCP tool. Requires Python 3. | | add | Install Layout UI components from the registry (our answer to npx shadcn add). Resolves registry + npm dependencies, writes the files, and merges theme variables into your global stylesheet. | | add --dir | Install into a specific components directory (default: components/ui, auto-detects src/). | | add --dry-run | Preview files, dependencies, and CSS changes without writing anything. | | list | List all available kits (free and pro). | | use | Switch the active kit in an existing .layout/ directory. | | import | Import a design system bundle exported from Layout (.zip). |

Examples:

# Start with the Linear-inspired dark kit
npx @layoutdesign/context init --kit linear-lite

# Start with a blank template and write your own layout.md
npx @layoutdesign/context init

# Auto-configure MCP settings for all supported editors
npx @layoutdesign/context install

# Auto-configure for Claude Code only
npx @layoutdesign/context install --target claude

# Install globally (available in all projects — each project uses its own .layout/)
npx @layoutdesign/context install --global

# Install Layout UI components (resolves deps + theme vars)
npx @layoutdesign/context add button
npx @layoutdesign/context add button card dialog

# Preview an install without writing anything
npx @layoutdesign/context add data-table --dry-run

# Install into a custom directory
npx @layoutdesign/context add button --dir src/ui

# Switch to a different kit
npx @layoutdesign/context use stripe-lite

# See all available kits
npx @layoutdesign/context list

# Import a bundle from Layout
npx @layoutdesign/context import ./my-design-export.zip

# Check setup and detect issues
npx @layoutdesign/context doctor

# Auto-install missing dependencies
npx @layoutdesign/context doctor --fix

# Serve a local directory for url-to-figma (requires Python 3)
npx @layoutdesign/context serve-local ./path/to/files
npx @layoutdesign/context serve-local ./path/to/files --port 8080

---

Available Kits

Three free starter kits are included. Premium kits are available at layout.design/kits.

Free

| Kit | Aesthetic | Description | |-----|-----------|-------------| | linear-lite | Dark, minimal, developer-focused | Developer tool design system inspired by Linear | | stripe-lite | Light, clean, high-trust | Payment UI design system inspired by Stripe | | notion-lite | Light, content-first, block-based | Productivity design system inspired by Notion |

Pro

| Kit | Aesthetic | Components | |-----|-----------|------------| | linear | Dark, minimal, developer-focused | 24 components, all tokens | | stripe | Light, clean, high-trust | 20 components, all tokens | | notion | Light, content-first, block-based | 22 components, all tokens | | revolut | Dark fintech, data-rich | 30 components, all tokens | | airbnb | Warm, rounded, photo-forward | 25 components, all tokens | | tiktok | Dark, vibrant, video-first | 28 components, all tokens | | netflix | Dark, cinematic, content-forward | 18 components, all tokens |

---

Setup Guides

The easiest way to configure any supported editor is:

npx @layoutdesign/context install

This auto-detects Claude Code, Cursor, Windsurf, VS Code / Copilot, Codex CLI, and Gemini CLI and configures the MCP server. For Claude Code it uses claude mcp add; for other tools it writes the appropriate config file (.cursor/mcp.json, .windsurf/mcp.json, .vscode/mcp.json, ~/.codex/config.json, or ~/.gemini/settings.json).

Per-Project vs Global

By default, the MCP server is registered per-project. Each project needs its own install.

For users working across multiple projects, install globally:

npx @layoutdesign/context install --global

The MCP server always reads .layout/ from the current working directory, so each project uses its own design system — even with a global install.

Updating

Layout Context uses npx -y which fetches the latest version automatically when a new agent session starts. To force an update mid-session:

# Clear the npx cache to force a fresh download
npx clear-npx-cache

# Verify dependencies after updating
npx @layoutdesign/context doctor

Claude Code users: The MCP server restarts automatically on new conversations. To force a restart mid-conversation, use /mcp and restart the layout server.

Manual Setup

If you prefer to configure manually:

Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "layout": {
      "command": "npx",
      "args": ["-y", "@layoutdesign/context", "serve"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "layout": {
      "command": "npx",
      "args": ["-y", "@layoutdesign/context", "serve"]
    }
  }
}

Windsurf (.windsurf/mcp.json):

{
  "mcpServers": {
    "layout": {
      "command": "npx",
      "args": ["-y", "@layoutdesign/context", "serve"]
    }
  }
}

VS Code / GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "layout": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@layoutdesign/context", "serve"]
    }
  }
}

Codex CLI (~/.codex/config.json — global):

{
  "mcpServers": {
    "layout": {
      "command": "npx",
      "args": ["-y", "@layoutdesign/context", "serve"]
    }
  }
}

Gemini CLI (~/.gemini/settings.json — global):

{
  "mcpServers": {
    "layout": {
      "command": "npx",
      "args": ["-y", "@layoutdesign/context", "serve"]
    }
  }
}

---

Live Preview

The preview MCP tool and the preview canvas work together to give you visual verification without leaving your agent session.

Start the preview server alongside the MCP server:

npx @layoutdesign/context serve

The preview canvas opens at http://localhost:4321. It features:

• Dark UI with your active kit's design tokens applied
• WebSocket-powered live updates — components render as the agent pushes them
• Viewport toggles (mobile, tablet, desktop)
• Source code panel to inspect what was rendered
• TSX transpilation on the server — no browser-side build step

When your agent calls the preview tool with a component, it appears in the canvas within milliseconds. Open the canvas in a browser tab alongside your editor and you have a live design review loop without any manual copy-paste.

---

Figma Integration

Three MCP tools bridge the gap between design and code using the Figma MCP server: push_to_figma, design_in_figma, and url_to_figma.

Setup

Add the Figma MCP server to your agent config alongside design-context. It uses OAuth — no API key required:

claude mcp add --transport http figma https://mcp.figma.com/mcp

Then authenticate when prompted. The Figma MCP server will open a browser tab for OAuth consent.

Figma Tools

| Tool | What It Does | |------|--------------| | push_to_figma | Creates an editable Figma frame from component code. Returns a structured prompt for Figma MCP's generate_figma_design. | | design_in_figma | Takes a natural language prompt and returns design tokens, component specs, and step-by-step instructions for generate_figma_design. Design in Figma before writing any code. | | url_to_figma | Captures a live website URL as editable Figma frames with auto-layout. Requires Playwright MCP alongside Figma MCP. |

The Closed Loop

Developer prompts AI → AI calls get_design_system → generates TSX
        ↓
AI calls p

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [uselayout](https://github.com/uselayout)
- **Source:** [uselayout/cli](https://github.com/uselayout/cli)
- **License:** MIT
- **Homepage:** https://layout.design

Install and usage instructions live in the source repository linked above.