For AI agents

Layout UI is designed to be consumed by AI coding agents. Every component ships machine-readable rules, and the Layout MCP server gives agents verified, up-to-date context.

The problem with generic component libraries

AI coding agents (Claude Code, Cursor, Copilot, Windsurf) write a lot of UI code. The problem is they often reach for hard-coded colours, arbitrary spacing, or wrong component variants because they have no structured understanding of the rules governing your specific design system.

Layout UI solves this by treating rules as first-class data. Every registry item carries structured meta that agents can read, and the Layout MCP server exposes both context retrieval and compliance validation as callable tools.

Registry meta rules

Every component in the Layout registry ships three structured rule fields alongside its code:

meta.usage

A prose rule explaining when to use the component, which variant to prefer, and how to compose it with other components.

meta.never

An array of explicit prohibitions: things an agent must never do with this component. These map directly to compliance check rules.

meta.tokens

The canonical --layout-* tokens consumed by this component. Agents use this to understand which kit tokens affect a given component.

Here is the Button's full meta block from registry.json:

{
  "name": "button",
  "type": "registry:ui",
  "title": "Button",
  "description": "Button with six intent variants and four sizes. Polymorphic via the Base UI render prop.",
  "meta": {
    "usage": "Primary actions use the default variant; one default button per view section. Secondary and outline are for supporting actions, ghost for toolbars and dense UI, destructive only for irreversible actions, link for inline navigation. Use render={<a href/>} to render as a link.",
    "never": [
      "Never hardcode colours; variants already map to intent tokens",
      "Never place two default-variant buttons in the same action group",
      "Never use destructive for cancel/dismiss actions",
      "Never override border-radius directly; it derives from --layout-radius"
    ],
    "tokens": [
      "--layout-primary",
      "--layout-primary-fg",
      "--layout-secondary",
      "--layout-secondary-fg",
      "--layout-accent",
      "--layout-accent-fg",
      "--layout-danger",
      "--layout-danger-fg",
      "--layout-input",
      "--layout-ring",
      "--layout-radius",
      "--layout-shadow-xs",
      "--layout-duration-base"
    ]
  }
}

layout.md context files

Layout kits from layout.design include a layout.md file: a structured, LLM-optimised context document that combines:

All design tokens with their values and purposes
Typography scale, spacing system, and shape rules
Component inventory with usage and anti-patterns
Brand-specific overrides and intent mapping
Anti-pattern rules (what never to do)

Place layout.md in your .layout/ directory and the Layout MCP server surfaces it to any connected agent automatically.

The Layout MCP server

The @layoutdesign/context MCP server runs alongside your editor and exposes your design system to any agent that supports the Model Context Protocol (Claude Code, Cursor, Windsurf).

# Install and initialise
npx @layoutdesign/context init
npx @layoutdesign/context serve

Key MCP tools available to agents:

Tool	What it does
get_design_system	Returns the full layout.md context document for the current kit.
get_design_section	Returns a single section (colours, typography, spacing, components…).
get_tokens	Returns all CSS custom properties by category, ready to paste.
get_component	Returns a component's code, usage rules, and never rules by name.
get_component_with_context	Component code plus resolved token values and brand-specific guidelines.
list_components	Full component inventory with metadata, tags, and token usage.
check_compliance	Validates a code snippet against design system rules. Returns violations.

The check_compliance tool is the key differentiator: before an agent commits generated code it can call this tool and receive a list of rule violations (hardcoded colours, wrong variants, missing aria attributes) resolved against your specific kit's token values.

Recommended agent workflow

The recommended pattern for agents building UI with Layout UI:

# 1. Fetch design context before writing UI
get_design_system()           # load layout.md into context

# 2. Look up the component you need
get_component("button")       # rules + code for the button

# 3. Generate the component code
# ... agent writes the UI ...

# 4. Validate before finishing
check_compliance(code)        # returns violations if any

# 5. Fix any violations and re-validate
# ... agent iterates until compliance passes ...

This loop means agents produce on-brand, rule-compliant UI on the first pass rather than requiring manual correction after the fact.