End-to-End Walkthrough

This walkthrough covers the complete Layout workflow: point Layout at your Figma file or production site, serve the extracted design system to your AI agent, and gate every edit to your tokens. Each step builds on the previous one, so read it in order the first time through.

Just want the CLI? Run npx @layoutdesign/context install to configure the MCP server for Claude Code, Cursor, Windsurf, Copilot, Codex, or Gemini CLI — then skip to step 7. Three free starter kits are bundled so you can test without extracting first. See the CLI guide for the full reference.

1. Extract from Figma

Paste a Figma file URL (e.g. https://www.figma.com/file/AbCdEf/My-Design-System) on the Studio home screen and enter your Figma Personal Access Token. You can create one at Figma → Settings → Account → Personal access tokens. The token is stored only in your browser and is never sent to Layout servers.

Layout calls the Figma REST API in two passes: first to list styles and component metadata, then to resolve actual values for each node. The following data is extracted:

What Gets Extracted	Details
Colour styles	Actual fill values resolved via node API, not just metadata
Typography styles	Font family, size, weight, line-height, and letter-spacing as composites
Effect styles	Drop shadows, inner shadows, and blur values
Component inventory	Name, description, variant count, and property definitions for every component
Variables	Enterprise plans only. The Variables API returns 403 on free/professional plans, which is treated as non-fatal and skipped automatically

The Figma Variables API returns 403 on non-Enterprise plans. This is expected. Layout treats it as non-fatal and continues extraction using colour and typography styles instead. You will still get a complete layout.md.

2. Extract from a Website

No Figma file? Paste any live website URL instead. Layout uses Playwright to load the page in a headless browser and extract design data directly from the rendered DOM and computed styles. This works on any public website, whether it is your own staging environment, a competitor site, or a design reference you admire.

The following is extracted from the live page:

What Gets Extracted	Details
CSS custom properties	Every --variable declaration found on the page
Font declarations	@font-face rules and computed font families in use
Computed styles	Colours, typography, spacing, borders, shadows, and transitions sampled from DOM elements
Animations	@keyframes rules defined in the page stylesheets
Library detection	Identifies Tailwind CSS, Bootstrap, and other CSS frameworks
Screenshots	Full-page and viewport captures for visual reference

Website extraction uses Playwright and cannot run on Vercel serverless. Self-hosted deployments on Coolify, Hetzner, or Railway work without any extra configuration.

3. Generate layout.md

Once extraction completes, click Generate layout.md in the Studio. Claude Sonnet analyses the raw extracted data and synthesises a structured, LLM-optimised context file. Generation typically finishes in under 2 minutes and streams into the editor in real time.

The output follows a fixed 9-section structure with 2 appendices:

Section	Contents
Quick Reference	One-page cheat sheet with the most important tokens and rules at a glance
1. Colour System	All colour tokens with hex values and usage guidance
2. Typography	Type scale, font families, weights, and line-heights
3. Spacing & Layout	Spacing scale and grid conventions
4. Component Specs	Per-component usage rules, variants, and TSX code examples
5. Elevation & Depth	Shadow tokens and z-index scale
6. Motion & Animation	Duration values, easing curves, and animation patterns
7. Border & Radius	Border widths, styles, and border-radius scale
8. Anti-Patterns	Explicit list of what the AI must not do, including hardcoded colours, wrong tokens, and off-brand patterns
9. Icons & Assets	Icon library in use and asset conventions
Appendix A	Raw CSS custom properties from the extraction
Appendix B	Raw typography declarations

The Quick Reference section is the highest-value part of layout.md. It is placed at the top because most AI agents read context top-to-bottom and may truncate long files. If you manually edit layout.md, prioritise keeping the Quick Reference accurate.

4. The Studio

When extraction completes, a "What's next" screen offers two routes: Serve to your agent (the primary path, taking you straight to the connect tab and export options) and Open Editor. The Studio itself opens in the editor, with Explore mode available as a utility when you want to generate test variants. All changes auto-save with a 2-second debounce. There is no Save button.

Source Panel (left)

Displays the raw extracted data: colour tokens, typography styles, spacing values, component inventory, and screenshots. Use this to verify what was captured before or after generation. If something is missing or misidentified, you can re-extract without losing any edits made in the editor.

Editor Mode (Source Panel + Monaco Editor)

A Monaco-based markdown editor, the same editor used in VS Code. This is where you refine layout.md: fix misidentified tokens, strengthen the anti-patterns section, rewrite component specs, or add brand guidance that extraction cannot infer. Section navigation pills let you jump between the 9 sections quickly. An AI edit bar below the editor lets you make targeted changes using natural language prompts.

Explore Mode (Source Panel + Explorer)

The Explorer is an optional utility for exploring design variants when you need them. Generate component variants, compare output with and without layout.md in a side-by-side comparison view, check the per-variant health score, and push variants to Figma directly from the canvas. It is not part of the core extract-serve-gate path, but it is useful for validating that your context file works.

5. Test Your Context

Before serving the context to your agent, two surfaces tell you whether layout.md is doing its job: the compliance checker in the Quality tab, and the Explorer's comparison view.

Compliance Checker

The Quality tab in the Source panel includes a Check code section. Paste any code snippet and it is validated against four rules derived from your design system: hardcoded colours, hardcoded spacing, missing token references, and unknown components. This is the same rule set your AI agent runs through the check_compliance MCP tool, so what passes here passes in your agent too.

Comparison View

The comparison view generates variants side by side, with and without layout.md context. Run a prompt and compare the two results directly. A well-written context file produces noticeably better output: correct token usage, proper spacing, on-brand typography, and no hardcoded colours. This A/B comparison is the clearest signal that your layout.md is working.

Quick Prompts

Preset component requests appear as one-click buttons in the Explorer: primary button, card, form input, badge, and more. If your extraction included Figma components, the Explorer also generates dynamic prompts for each extracted component name, giving you targeted tests for your specific design system rather than generic UI patterns.

Health Score

Each generated variant in the Explorer shows a 0-100 health score measuring token faithfulness, component accuracy, and anti-pattern violations. The score reflects how closely the generated code follows the rules in layout.md. Aim for 80 or higher before exporting.

Live Variant Preview

Each variant card in the Explorer renders the generated TSX live in a sandboxed iframe with React and Tailwind CSS loaded. You see the actual component, not just code, so visual errors such as wrong colours or broken layouts are immediately obvious without leaving the Studio.

If the health score is consistently below 60, check that the Colour System and Typography sections of layout.md contain well-formed CSS code blocks. The AI needs concrete, parseable examples to reference at generation time. Prose descriptions alone are not enough.

6. Export Your AI Kit

Click Export in the top bar to open the export modal. layout.md is always included. The ZIP bundle can contain up to 8 additional files, each optimised for a different AI tool or framework:

File	Optimised For
layout.md	All AI agents. The primary context file
CLAUDE.md	Claude Code. Persistent project context injected on every prompt
AGENTS.md	Codex, Copilot, Jules, Factory, Amp. Agents following the agents.md convention
.cursor/rules	Cursor. Project rules applied across all Composer and Chat sessions
DESIGN.md	Google's design.md format. Interoperable design context spec
Codex skill	OpenAI Codex. Agent Skill folder with token summary and component pointers
tokens.css	Any stylesheet. CSS custom properties ready to import directly
tokens.json	Style Dictionary, Theo, and W3C DTCG-compatible tooling
tailwind.config.js	Tailwind CSS. Theme extension with extracted colours, spacing, and radii

The tailwind.config.js uses theme.extend so it merges with your existing config without overwriting defaults. tokens.css can be imported at the top of your global stylesheet with no modifications required.

7. Set Up the CLI

The @layoutdesign/context CLI imports your Studio export and configures the MCP server so your AI agent automatically reads the design system on every session. Two commands are all that is needed:

bash

npx @layoutdesign/context import ./layout-export.zip
npx @layoutdesign/context install

The import command unpacks the ZIP into a .layout/ directory in your project. The install command detects Claude Code, Cursor, Windsurf, Copilot, Codex, and Gemini CLI and writes the MCP server configuration to whichever are present. It also creates AGENTS.md and .cursor/rules when they do not exist yet, so agents that read static context files are covered too. No manual JSON editing required. Need a specific format later? The export command emits design.md, AGENTS.md, CLAUDE.md, Cursor rules, or a Codex skill straight from the loaded kit. See the CLI guide.

After running install, restart your AI agent once so it picks up the new MCP server configuration. From that point on, every session in the project directory has automatic access to the design system tools.

8. MCP Tools Reference

Once the MCP server is configured, your AI agent can call 23 tools automatically when building UI. You do not need to invoke them manually. The agent decides when to use them based on the task.

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 tokens filtered by type (colour, spacing, etc.)
list-tokens	Returns a categorised token catalogue (colour, typography, spacing, radius, shadow) with dark-mode values tagged
get_component	Returns the spec and TSX code example for a named component
list_components	Returns the full inventory of components in the design system
check_compliance	Validates a code snippet against design rules and returns violations
preview	Renders a component in a local browser canvas at localhost:4321
push_to_figma	Sends a rendered component to Figma as editable frames. Supports capture (default) and native mode (editable auto-layout objects, no Playwright needed)
push_tokens_to_figma	Pushes design system tokens to Figma as native variables and styles via Figma MCP
url_to_figma	Captures a public URL as editable Figma frames with auto-layout via Figma MCP and Playwright
design_in_figma	Designs UI directly in Figma using extracted tokens from a natural language prompt
update_tokens	Updates or adds design tokens in the loaded kit. Mode-aware (light, dark, or all) so dark themes are never clobbered
get_screenshots	Returns screenshots captured during website extraction for visual reference
scan_project	Scans for React components and Storybook stories. Auto-runs on startup so agents reuse existing code.
check_setup	Diagnoses and auto-fixes MCP setup issues (Figma transport, OAuth, plugin shadows)
list_ui_components	Lists pre-built, token-contracted Layout UI components installable via the add command
get_selected_element	Returns the element currently selected in Layout Live, so 'this' and 'that one' resolve to real code
get_recent_visual_edits	Returns recent visual edits made in Layout Live for context before generating new code
get_pending_requests	Returns change requests left in Layout Live, pinned to elements, regions, or the page
mark-request	Reports progress on a Layout Live request (in progress or done, with an optional note); the pin recolours on the page
get-live-screenshot	Returns the screenshot stored with a Layout Live request, or a fresh capture of the current page while Live runs
lock_file	Reserves exclusive write access to a file that may also be open in Layout Live
unlock_file	Releases a file lock acquired with lock_file

9. Gate Your Edits with Layout Live

Context gets your agent most of the way. Enforcement closes the gap. Layout Live is the desktop app that sits alongside your dev server: click any element, edit it visually, and every change is a deterministic AST edit gated to your design system tokens. No AI call, no tokens burned, no off-system values. A compliance score gates each edit, and the Live MCP tools (get-selected-element, get-recent-visual-edits, get-pending-requests, mark-request, get-live-screenshot, lock-file, and unlock-file) hand the same context to your agent so visual edits and code edits stay in sync.

This is the end of the golden path: extract your design system, serve it to your agent, then gate every edit to your tokens. The golden-path checklist in the Studio connect tab tracks all three steps per project.

10. The Figma Workflow

Layout bridges the gap between code and design. Preview components locally at localhost:4321, push them to Figma for designer review, and design directly in Figma using the extracted tokens. A typical workflow looks like this:

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 -> frames placed in Figma
  -> Designer reviews and refines using the same tokens
  -> Developer uses Figma MCP to read designer feedback

Each step uses the same design tokens extracted from the source. The AI generates code with the tokens, the preview renders using Tailwind, and the Figma frames reference the same values, keeping code and design aligned.

The push_to_figma and design_in_figma tools require the Figma MCP server to be configured in your AI agent separately. See the Figma MCP documentation for setup instructions.

11. Tips & Troubleshooting

Health Score Ranges

Score	What It Means
80-100	Excellent. layout.md is providing strong, reliable context. Safe to export and ship.
60-79	Good. Context is working but some tokens or anti-patterns may be ignored. Review the weakest sections before exporting.
Below 60	Needs work. The AI is not reliably following your design system. Check that CSS code blocks are well-formed and the anti-patterns section is explicit.

Re-Extracting After a Design Update

When the design system changes (new brand colours, updated type scale, redesigned components), paste the URL again on the home screen and re-extract. The Studio loads the updated data into the Source panel. You can then re-generate layout.md or manually update only the changed sections in the editor.

Comparison View A/B Testing

The comparison view in the Explorer is the fastest way to validate whether layout.md is providing value. Generate variants with and without context side by side using the same prompt. If the output looks identical, the context file is not doing its job and needs strengthening. Focus on the Quick Reference section and the anti-patterns list first.

Free Starter Kits

If you want to try the CLI without extracting a design system first, three free 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, enough to get meaningful on-brand output immediately.

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

bash

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

Starter kits are a good way to test your AI agent integration end to end before committing to a full extraction. Import a kit, run install, and verify the MCP tools are working before bringing in your own design system.

Next Steps

Layout Live. The desktop app that gates every visual edit to your design system tokens.
Studio Guide. Deeper reference for the editor, Explorer, and all extraction options.
CLI Guide. Full CLI command reference including kit management and auto-configure options.
layout.md Spec. The formal specification for each section of the context file.
Claude Code Integration. Add the export files to your project for persistent on-brand context.
Cursor Integration. Set up MDC rules files for Cursor 0.43+.