layout.md Specification

The layout.md file is the core output of Layout. It follows a strict structure optimised for LLM consumption, not for humans to read, but for AI agents to parse reliably and reference consistently when generating UI code.

Every layout.md produced by Layout follows the same 9-section + 2-appendix format. This predictability means agents always know where to find what they need, and the MCP tools can return specific sections on demand without the agent having to search for them.

layout.md is always included in every export bundle from AI Studio, regardless of which other formats you select. It is the canonical source of truth that all other export formats (CLAUDE.md, .cursorrules, tokens.css) are derived from.

Token Types

layout.md works with five categories of design token. Understanding the format for each type prevents the most common agent errors.

Type	Examples	Format notes
Colour	--color-primary: #6366F1, --color-bg-surface: #17171C	Hex, RGB, or HSL
Typography	body-md: { font-family, size, weight, line-height, letter-spacing }	Composite object, never individual properties
Spacing	--space-4: 16px, --space-8: 32px	px values on a 4px base unit
Radius	--radius-md: 8px, --radius-full: 9999px	px values
Effect	--shadow-lg: 0 10px 15px rgba(0,0,0,0.1)	CSS shadow shorthand

Section Breakdown

Each section serves a specific role in giving an AI agent complete and unambiguous design context. The sections are ordered from broadest (philosophy) to most specific (anti-patterns), mirroring how a developer would naturally consume a design system.

Quick Reference

50–75 lines

A dense, copy-pasteable summary of the entire design system. Structured so an agent can drop it directly into CLAUDE.md or .cursorrules without including the full file. Contains: the top 8-12 colour tokens, the primary typography group, one complete component example with all states, and the critical NEVER rules.

This section is what the agent uses most. Keep it under 75 lines so it fits comfortably within a system prompt without eating too much of the context window.

markdown

## Quick Reference

**Design language:** Dark, precise, developer-focused. No gradients. No decorative elements.

### Core colour tokens
```css
--color-bg-app: #0C0C0E;
--color-bg-surface: #17171C;
--color-bg-elevated: #1E1E24;
--color-primary: #6366F1;
--color-primary-hover: #7577F3;
--text-primary: #E8E8F0;
--text-secondary: rgba(232,232,240,0.55);
--border: rgba(255,255,255,0.07);
```

### Core typography
- **UI text:** Geist, 14px/1.5, weight 400
- **Headings:** Geist, 24–32px, weight 700
- **Code/mono:** Geist Mono, 13px/1.6

### Button: primary variant
```tsx
<button className="bg-[var(--color-primary)] text-white px-4 py-2 rounded-lg
  hover:bg-[var(--color-primary-hover)] transition-all duration-150
  focus-visible:ring-2 focus-visible:ring-[var(--color-primary)] focus-visible:outline-none
  disabled:opacity-40 disabled:cursor-not-allowed">
  Get started
</button>
```

### NEVER rules
1. NEVER use raw hex values. Always use CSS variables
2. NEVER use box-shadow for elevation. Use background colour difference
3. NEVER use font-size below 12px
4. NEVER use opacity for disabled. Use the disabled token

Design Direction & Philosophy

Prose

Personality and aesthetic intent in plain language. Describes what the design system is trying to feel like, what it explicitly rejects, and what category of product it belongs to. This section tells the agent whether to reach for rounded corners or sharp edges, saturated or muted colours, dense or airy layouts, without giving explicit rules.

Example entry: "Dark, precise, developer-focused. Influenced by Linear and Vercel. Rejects: decorative gradients, rounded-pill buttons, bright accent colours. Accepts: monochrome palettes, tight spacing, clear hierarchy."

Colour System

Three tiers

Colour tokens are structured across three tiers to enforce correct usage. Agents should only ever reference Tier 2 (semantic) or Tier 3 (component) tokens in generated code, never Tier 1 primitives directly. This mirrors how professional design systems work and prevents hardcoded values from creeping into components. When the source design system uses multiple modes (e.g. light and dark), tokens include a mode field and are grouped by mode. Each mode defines its own set of semantic values for the same token names, enabling theme-aware code generation.

Tier 1 primitive tokens (raw hex values) are listed for reference only. They should never appear in component code. Always use the semantic alias.

markdown

## Colour System

### Tier 1: Primitives
Raw colour values. Never use directly in components.
```css
--primitive-indigo-500: #6366F1;
--primitive-indigo-400: #7577F3;
--primitive-gray-950: #0C0C0E;
--primitive-gray-900: #111115;
```

### Tier 2: Semantic aliases
Intent-based names that map to primitives.
```css
--color-primary: var(--primitive-indigo-500);
--color-bg-app: var(--primitive-gray-950);
--color-bg-surface: var(--primitive-gray-900);
```

### Tier 3: Component tokens
State-specific tokens for individual components.
```css
--button-primary-bg: var(--color-primary);
--button-primary-bg-hover: var(--color-primary-hover);
--button-primary-text: var(--color-text-on-primary);
```

Typography System

Composite groups

Typography tokens are always defined as composite groups: a single named token that bundles font-family, size, weight, line-height, and letter-spacing together. Individual properties (font-size: 14px) are not valid tokens. This prevents the common mistake of agents mixing and matching properties from different type scales, which destroys typographic hierarchy.

Typography tokens are always composites. Never list font-size, font-weight, or line-height as standalone tokens. They must always appear as part of a named composite group like body-md or heading-lg.

markdown

## Typography System

### Token format: always composites
```
body-md:
  font-family: "Geist", system-ui, sans-serif
  font-size: 14px
  font-weight: 400
  line-height: 1.5
  letter-spacing: 0

heading-lg:
  font-family: "Geist", system-ui, sans-serif
  font-size: 32px
  font-weight: 700
  line-height: 1.25
  letter-spacing: -0.02em
```

### Pairing rules
- Use heading-sm through heading-xl for page headings. Never use raw font-size values
- Pair heading tokens with body-md or body-sm for supporting text
- Mono tokens (code-sm, code-md) for all code, terminal output, and token names

Spacing & Layout

Scale + grid

Defines the base unit (typically 4px), the full spacing scale, the grid system (column count, gutter, margin), responsive breakpoints, and explicit rules for when to use flexbox vs CSS grid. Agents use this section to ensure spacing is always on-scale and layouts are predictably responsive.

Spacing scale values are always multiples of the base unit. Any spacing value that does not appear in the scale is a violation of the design system and will be flagged by check_compliance.

Page Structure & Layout Patterns

From screenshots

Derived from the full-page and viewport screenshots captured during extraction. Documents recurring layout patterns: nav placement, sidebar widths, hero sections, card grids, with annotated measurements. This gives agents a reference for how full pages are assembled from the available components, not just how individual components look in isolation.

This section is only populated when screenshots were captured during extraction (website extraction always includes them; Figma extraction requires explicit screenshot capture in the source file).

Component Patterns

5–10 components

The most detailed section. Each component entry includes: anatomy (the DOM structure), token mappings for every state (default, hover, focus, active, disabled, loading, error), property defaults and preferred values, and one complete TSX example using the design system tokens. Property defaults tell agents what the initial prop values should be (e.g. variant='primary', size='md'), and preferred values list the valid options for each prop. Agents should always call get_component before building a component that exists here. This section defines the canonical implementation.

Every state must be mapped. Components with unmapped states (e.g. no disabled token defined) are considered incomplete and will be flagged in the compliance check.

markdown

## Component Patterns

### Button

**Anatomy:** [container] > [icon?] [label] [icon?]

**Token mappings**
| State    | Background                    | Text               | Border          |
|----------|-------------------------------|-------------------|-----------------|
| default  | --button-primary-bg           | --text-on-primary  | none            |
| hover    | --button-primary-bg-hover     | --text-on-primary  | none            |
| focus    | --button-primary-bg           | --text-on-primary  | --border-focus  |
| active   | --button-primary-bg-active    | --text-on-primary  | none            |
| disabled | --button-primary-bg (40% opacity) | --text-on-primary  | none        |
| loading  | --button-primary-bg           | transparent        | none            |

**TSX example**
```tsx
interface ButtonProps {
  variant?: "primary" | "secondary" | "ghost";
  size?: "sm" | "md" | "lg";
  loading?: boolean;
  disabled?: boolean;
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant = "primary", size = "md", loading, disabled, children, onClick }: ButtonProps) {
  return (
    <button
      onClick={onClick}
      disabled={disabled || loading}
      className={cn(
        "inline-flex items-center justify-center font-medium rounded-lg transition-all duration-150",
        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-primary)]",
        "disabled:opacity-40 disabled:cursor-not-allowed",
        variant === "primary" && "bg-[var(--color-primary)] text-white hover:bg-[var(--color-primary-hover)]",
        variant === "secondary" && "bg-[var(--bg-surface)] text-[var(--text-primary)] border border-[var(--border)]",
        size === "sm" && "text-sm px-3 py-1.5 h-8",
        size === "md" && "text-sm px-4 py-2 h-9",
        size === "lg" && "text-base px-5 py-2.5 h-11",
      )}
    >
      {loading ? <Spinner size={14} /> : children}
    </button>
  );
}
```

Elevation & Depth

Shadow + z-index

Defines how depth is expressed without box-shadow. In dark design systems, elevation is almost always achieved through background colour, where darker = lower, lighter = higher. This section documents the elevation scale, the corresponding background tokens, border behaviour at each level, and the z-index scale for layered UI elements like modals, tooltips, and drawers.

Do not use box-shadow to create elevation unless the design system explicitly defines shadow tokens at each elevation level. Most dark design systems do not.

Motion

Timing + easing

Timing functions, duration values, and easing tokens for transitions and animations. Includes: the base duration (typically 150ms), the full duration scale for complex animations, named easing curves (ease-out, spring, etc.), and rules for which interaction types use which duration. Agents use this section to write consistent transition CSS.

Anti-Patterns & Constraints

NEVER rules

Numbered rules that define what must never appear in generated code. Each rule has three parts: what is forbidden, why it fails (the actual reason, not just 'it looks bad'), and what to do instead. This is the section the check_compliance tool validates against. Well-written anti-pattern rules dramatically reduce the correction loop between agent output and production-ready code.

Write anti-patterns as precise, machine-checkable rules. Vague rules like 'avoid harsh colours' cannot be validated. Precise rules like 'NEVER use a colour value not present in the colour token system' can.

markdown

## Anti-Patterns & Constraints

### Rule 1: No hardcoded colour values
❌ NEVER: `color: #6366F1`, `className="text-indigo-500"`
✅ DO: `color: var(--color-primary)`, `className="text-[var(--color-primary)]"`
**Why it fails:** Hardcoded values break when the design system updates. Tokens are the single source of truth.

### Rule 2: No box-shadow for elevation
❌ NEVER: `box-shadow: 0 4px 12px rgba(0,0,0,0.3)`
✅ DO: Use a darker/lighter background token from the elevation scale
**Why it fails:** Shadows look broken on dark backgrounds and are impossible to theme.

### Rule 3: No arbitrary spacing
❌ NEVER: `padding: 13px`, `margin-top: 7px`
✅ DO: Use spacing tokens from the defined scale (4, 8, 12, 16, 20, 24, 32, 40, 48, 64px)
**Why it fails:** Off-scale values create visual inconsistency that accumulates across components.

Appendix A: Complete Token Reference

A flat table of every token extracted from the source (Figma file or website), with its name, resolved value, type, and the section it belongs to. This is the exhaustive reference. The main sections only document tokens that appear in components, but Appendix A includes everything. Useful for agents doing token lookup when the section content does not cover an edge case.

Appendix B: Token Source Metadata

Records where each token came from and how confident the extraction was. Each token has a source field (CSS variable, Figma style, computed DOM style, etc.), an extraction method, and a confidence level (high / medium / low). Tokens with low confidence were inferred rather than directly extracted and should be treated as approximate. This appendix is primarily useful for debugging extraction output and understanding which parts of the design system are well-defined versus inferred.

Low-confidence tokens are included in Appendix B but excluded from the main sections. They will not appear in component token mappings or in the Quick Reference. If you see a token in Appendix B that you expect to be in the main content, the extraction may need to be re-run against the Figma source rather than the website.