Layout

Layout tokens live under the spacing key in YAML frontmatter, not under layout. Each token maps a scale name (e.g., sm, gutter) to a Dimension string (px, em, rem) or a unitless number. The section heading in the Markdown body should be ## Layout or ## Layout & Spacing. Valid units are px, em, and rem.

The Layout / `spacing` name mismatch#

The canonical Markdown heading for this section is ## Layout (or the accepted alias ## Layout & Spacing). The tool's engine recognizes both and classifies the section as layout.

However, the YAML frontmatter key that holds the actual tokens is spacing, not layout. This is intentional: spacing describes the token data type (a spacing scale), while Layout describes the design concept the tokens serve. When you write a DESIGN.md file, you must use spacing as the YAML key:

spacing:
  base: 16px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
  gutter: 24px
  margin: 32px

A top-level key named layout in frontmatter is not recognized by the parser and will appear in unknownKeys.

Token shape#

Each token in spacing is a key mapped to one of:

A Dimension: a number followed by px, em, or rem. Example: 16px, 1.5rem.
A unitless number: e.g., 12 (column counts, ratios, or multipliers). The linter does not validate it as a dimension and passes it through without error.

Token type	Example value	When to use
Dimension (px)	`8px`, `24px`	Absolute spacing units, padding, gap, margin
Dimension (rem)	`1rem`, `2.5rem`	Root-relative units that scale with browser font-size preferences
Unitless number	`12`, `4`	Column counts, grid ratios, or other layout multipliers

Recommended token names#

There is no enforced name set for spacing tokens. Common names used by design systems and recognized across tooling:

xs, sm, md, lg, xl, 2xl, base, gutter, margin, section

Any descriptive key is valid. Unknown key names are accepted without error.

Component references#

Spacing tokens can be referenced from component definitions using {spacing.token-name}:

spacing:
  sm: 8px
  md: 16px
  lg: 32px
components:
  card:
    padding: "{spacing.md}"
  modal:
    padding: "{spacing.lg}"

A reference to a spacing token that does not exist triggers a broken-ref error.

Full DESIGN.md example: Layout section#

---
name: Clean Grid
spacing:
  base: 8px
  xs: 4px
  sm: 8px
  md: 16px
  lg: 32px
  xl: 64px
  gutter: 24px
  margin: 48px
  columns: 12
---

## Layout

The layout follows a strict **8px base grid** with a 4px half-step for
micro-adjustments such as icon padding and label offsets.

- **Grid**: 12 columns with 24px gutters; 48px page margins at desktop.
- **Section rhythm**: 64px vertical separation between major page sections;
  32px between subsections.
- **Component padding**: 16px internal padding for cards and panels;
  8px for compact list items.

Try it in the tool

Was this page helpful?