Layout CLI

@layoutdesign/context is an open-source, MIT-licensed npm package that serves your design system context to AI agents via the Model Context Protocol (MCP). Once configured, your AI agent calls get_design_system automatically whenever it builds UI. No manual context pasting required.

Prerequisites

Node.js 18 or later. Run node --version to check. Download from nodejs.org.
npm 7+ or npx, included with Node.js. Run npm --version to confirm.

Installation

Initialise a .layout/ directory in your project with a free starter kit. No signup required.

bash

npx @layoutdesign/context init --kit linear-lite

This creates a .layout/ directory containing layout.md and the token files for the chosen starter kit. See the Free Starter Kits section below for all available kit names.

After init, run npx @layoutdesign/context installto auto-configure your AI agent's MCP settings. No manual JSON editing required.

Importing from Studio

If you have already exported a ZIP bundle from Layout, import it directly. No need to use a starter kit.

bash

npx @layoutdesign/context import ./export.zip

This unpacks the bundle into .layout/ and makes your extracted layout.md and tokens available to the MCP server immediately.

Starting the MCP Server

Start the local MCP server in your project directory:

bash

npx @layoutdesign/context serve

The server runs on stdio and responds to MCP tool calls from your configured AI agent. No port is opened. Communication is via standard input/output, the MCP convention for local tools.

Add the MCP server to your agent config once. After that, every session in that project directory automatically has access to the design system tools. No flags, no manual context injection.

Auto-Configure AI Tools

The installcommand automatically writes the MCP server configuration to your AI tool's settings file:

bash

npx @layoutdesign/context install

This detects Claude Code, Cursor, Windsurf, Copilot, Codex, and Gemini CLI and configures whichever are present. To target a specific tool:

bash

npx @layoutdesign/context install --target claude
npx @layoutdesign/context install --target cursor
npx @layoutdesign/context install --target windsurf
npx @layoutdesign/context install --target vscode
npx @layoutdesign/context install --target codex
npx @layoutdesign/context install --target gemini

Managing Design Kits

List all available kits (both free starter kits and any you've imported from Studio):

bash

npx @layoutdesign/context list

Switch to a different kit:

bash

npx @layoutdesign/context use stripe-lite

Quickstart (Studio Export)

The fastest path from Studio to working AI context is three commands:

bash

npx @layoutdesign/context import ./layout-export.zip
npx @layoutdesign/context install
# Done -  your AI agent reads the design system automatically

Available MCP Tools

The MCP server exposes 14 tools your AI agent can call automatically:

Tool	What It Does
get_design_system	Returns the full layout.md, or a specific section by number
get_tokens	Returns CSS, JSON, or Tailwind token output filtered by type (colour, spacing, etc.)
get_component	Returns the component spec and TSX code example for a named component
list_components	Returns the full inventory of components available in the design system
check_compliance	Validates a code snippet against the design rules and returns violations
preview	Renders a component live in a local browser canvas at localhost:4321
push_to_figma	Renders a component and pushes frames to Figma. Supports capture mode (screenshot-based, default) and native mode (editable auto-layout objects via Figma MCP, no Playwright needed)
push_tokens_to_figma	Pushes design system tokens to Figma as native variables and styles (via Figma MCP). Optionally specify a file key, or omit to create a new file
url_to_figma	Captures a public URL at multiple viewports and places the frames in Figma (via Figma MCP + Playwright)
design_in_figma	Designs UI directly in Figma using your extracted tokens, from a natural language prompt
update_tokens	Updates or adds design tokens in the loaded kit (CSS, JSON, or Tailwind format)
get_screenshots	Returns reference screenshots captured during website extraction for visual comparison
check_setup	Diagnoses and optionally fixes MCP server setup issues (registration, OAuth, reachability)
scan_project	Scans the project directory for React components and Storybook stories. Returns component names, file paths, props, import paths, and story associations. Auto-runs on MCP server startup.

Free Starter Kits

Three starter kits are bundled with the package. Each was extracted from a live website using Playwright and includes a Quick Reference, core tokens, and 5 component specs. That is enough to get meaningful on-brand output immediately.

Kit	Aesthetic
linear-lite	Developer tool, dark-first
stripe-lite	Clean, trust-focused
notion-lite	Document-first, typography-heavy

bash

# Use any kit name with the init command
npx @layoutdesign/context init --kit stripe-lite
npx @layoutdesign/context init --kit notion-lite

Checking Your Setup

The doctor command inspects your environment and reports any configuration issues:

bash

npx @layoutdesign/context doctor

It checks: Node.js version, Claude Code installation, Figma MCP configuration, and Playwright MCP availability. To automatically install any missing dependencies:

bash

npx @layoutdesign/context doctor --fix

Run doctor first if push_to_figma or url_to_figma are not working. Those tools require the Figma MCP and Playwright MCP to be configured separately.

Serving a Local Directory

The serve-local command serves a local directory over HTTP so the url_to_figma MCP tool can capture locally-built components as Figma frames:

bash

npx @layoutdesign/context serve-local ./my-components

The directory is served at http://localhost:4322. You can then pass that URL to the url_to_figma tool.

Requires Python 3 to be installed on your system. Check with python3 --version. Python 3 is pre-installed on macOS and most Linux distributions.

The Code-to-Design Loop

The preview and push_to_figma tools close the full loop between code and design, something no other open-source tool currently does:

text

Developer prompts Claude
  -> Claude calls get_design_system for context
  -> Claude generates on-brand TSX
  -> Claude calls preview -> renders at localhost:4321
  -> Developer reviews, requests changes
  -> Claude calls push_to_figma -> editable frame in Figma
  -> Designer tweaks in Figma
  -> Developer asks Claude to read Figma changes (via Figma MCP)
  -> Claude updates the code to match

The push_to_figma tool requires the Figma MCP server to also be configured in your agent. See the Figma MCP docs for setup instructions.

Codebase Scanner

Layout automatically detects React components and Storybook stories in your project. The MCP server scans your project on startup (~10–30ms). AI agents see your existing components via list_components which merges design system components from Figma with codebase components into a single unified list. This prevents AI agents from generating duplicates of components you already have.

Manual Scanning

To run a manual scan and optionally upload results to Layout Studio:

bash

npx @layoutdesign/context scan [path]
  --sync          Upload results to Layout Studio
  --project <id>  Target project ID
  --type <type>   storybook | codebase | both

What Gets Detected

The React component detector finds six patterns in your source files:

Pattern	Example
Function exports	export function Button() {}
Const exports	export const Card = () => {}
forwardRef	export const Input = forwardRef(...)
Grouped exports	export { Button, Card } from './components'
Props interfaces	interface ButtonProps { variant: string }
Default exports	export default function Page() {}

Import paths are generated using the @/ alias convention. For each component, the scanner extracts: name, file path, import path, props interface (if found), and whether it has associated Storybook stories.

Storybook Integration

The scanner parses Storybook CSF3 story files (.stories.ts and .stories.tsx) and extracts rich metadata for each story:

Component metadata from the default export (title, component reference)
argTypes defining the available props and their controls
args specifying default prop values for each story
Story names (Primary, Secondary, Disabled, Loading, etc.)
Tags for categorisation and filtering

Stories are fuzzy-matched against detected React components by name. When a match is found, the component entry in list_components includes the story count and story names. This means AI agents know that your Button component already has Primary, Secondary, Disabled, Loading, and Icon variants defined in Storybook, and will avoid regenerating those variants from scratch.

To scan only Storybook stories without the full component scan:

bash

npx @layoutdesign/context scan . --type storybook

When codebase components are synced via layout scan --sync, the Explorer includes them in AI generation context. Generated code includes production import comments showing exactly which components to use from your codebase. In the Studio, scanned components appear in the Design System page alongside Figma components, with a copy import path button for each.

Troubleshooting

Port 4321 already in use

Another process is using the preview port. Kill it and retry: lsof -ti:4321 | xargs kill

Figma MCP not authenticated

Run claude mcp run figma once in your terminal to complete the OAuth flow, then try again.

MCP tools not showing in Claude Code

Run npx @layoutdesign/context install again to re-register the MCP server, then fully restart Claude Code (not just reload the window).

ZIP import fails

Ensure the file ends in .zip and was downloaded directly from Layout Studio. Browser-zipped or re-archived files may have a different structure. Try re-downloading from Studio.

Integration Guides

Set up agent-specific integrations using the exported files:

Claude Code: add to CLAUDE.md for persistent context on every prompt
Cursor: .cursorrules or MDC rules for Composer and Chat
GitHub Copilot: copilot-instructions.md setup
Windsurf: .windsurfrules and tokens.css import
Google Antigravity: MCP server via MCP Store or manual config
OpenAI Codex: AGENTS.md placement and subdirectory overrides