Docs / Format spec

Tokens

Design tokens are the named, reusable values in the YAML front matter: colors, type scales, spacing, and border-radius. They form the single source of truth that both the CLI and AI agents read.

Once defined in the front matter, tokens can be referenced anywhere inside components using {namespace.key} syntax — keeping your component definitions DRY and automatically consistent with the token layer.

Color tokens

The colors object accepts any valid CSS color string. Prefer semantic names (what the color means) over descriptive names (what the color looks like).

Format

Example

Notes

Hex

"#1A1C1E"

Most common, safe for all tools

Hex with alpha

"#1A1C1E80"

Last two digits are opacity

RGB

"rgb(26, 28, 30)"

Full CSS rgb() syntax

RGBA

"rgba(0, 0, 0, 0.5)"

With opacity

OKLCH

"oklch(0.18 0.012 280)"

Perceptual, recommended for dark mode

colors:
  # Primary brand colors
  primary:    "#0A0A0A"
  accent:     "#E63946"

  # Neutral scale
  neutral-50: "#FAFAFA"
  neutral-100: "#F5F5F5"
  neutral-900: "#171717"

  # Semantic
  surface:    "#FFFFFF"
  error:      "#D32F2F"
  success:    "#388E3C"

WCAG AA check: When the linter finds a component with both textColor and backgroundColor defined, it automatically checks that the contrast ratio meets WCAG AA (4.5:1 for normal text, 3:1 for large text).

Typography tokens

The typography object is keyed by role. Common role names are h1–h6, body, body-sm, label, caption, and mono, but any key is valid.

Property

Accepted values

fontFamily

Any quoted font stack: "Inter", "Plus Jakarta Sans, sans-serif"

fontSize

px or rem: "16px", "1rem", "2.5rem"

fontWeight

Numeric: 300, 400, 500, 600, 700, 800, 900

lineHeight

Unitless or px: 1.5, 1.6, "24px"

letterSpacing

em values: "-0.025em", "0.06em"

typography:
  h1:
    fontFamily: "Plus Jakarta Sans"
    fontSize: 3.5rem
    fontWeight: 800
    lineHeight: 1.05
    letterSpacing: -0.035em
  h2:
    fontFamily: "Plus Jakarta Sans"
    fontSize: 2rem
    fontWeight: 700
    lineHeight: 1.15
  body:
    fontFamily: "Inter"
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.65
  label:
    fontFamily: "Manrope"
    fontSize: 0.75rem
    fontWeight: 500
    letterSpacing: 0.06em

Spacing tokens

Named spacing values that define your layout grid. Use any CSS length unit. A consistent scale prevents arbitrary values appearing in AI-generated code.

spacing:
  1: 4px
  2: 8px
  3: 12px
  4: 16px
  6: 24px
  8: 32px
  12: 48px
  16: 64px

Or use named sizes if that fits your team's language better:

spacing:
  xs:  4px
  sm:  8px
  md:  16px
  lg:  32px
  xl:  64px
  2xl: 128px

Rounded tokens

Named border-radius values. The linter accepts any valid CSS border-radius, including the canonical pill value.

rounded:
  none: 0
  sm:   4px
  md:   8px
  lg:   16px
  xl:   24px
  2xl:  32px
  full: 9999px

Token references

Inside the components block, any value can reference a previously defined token using {namespace.key}. References are resolved by the CLI and can also be expanded by AI agents before generating code.

# Token definitions
colors:
  brand: "#0070F3"
spacing:
  md: 16px
rounded:
  pill: 9999px

# References in components
components:
  cta-button:
    backgroundColor: "{colors.brand}"   # resolves to #0070F3
    padding: "{spacing.md} 24px"        # resolves to 16px 24px
    rounded: "{rounded.pill}"           # resolves to 9999px

Frontmatter Components