DESIGN.md Field Reference

Every top-level YAML key the parser recognizes, what value type each accepts, the three primitive token types (Color, Dimension, Reference), the seven typography sub-fields, the eight component sub-tokens, and the canonical section order. All drawn from @google/design.md 0.3.0 (spec-config.yaml and dist/linter/index.js).

Try it in the tool

Top-level frontmatter fields#

The parser recognizes exactly eight top-level YAML keys. Any other key is checked by the unknown-key rule (see the CLI reference).

Key	Type	Required	Description
`version`	string	No	Format version string. The current value is `"alpha"`. Omitting this field is valid.
`name`	string	Recommended	Short human-readable name for the design system (for example, `Heritage` or `Mono Studio`). Consumed by agents and display tools.
`description`	string	No	One-line summary of the visual identity. Shown in diffs and agent context.
`colors`	map<string, Color>	No	Color tokens as name-to-hex pairs. Values must be `#` followed by exactly six hex digits (sRGB).
`typography`	map<string, TypographyObject>	No	Typography tokens as name-to-object pairs. Each object holds up to seven sub-fields (see below).
`rounded`	map<string, Dimension>	No	Border-radius scale as name-to-dimension pairs (for example, `sm: 4px`, `md: 8px`).
`spacing`	map<string, Dimension>	No	Spacing scale as name-to-dimension pairs. Used for padding, margin, and gap tokens.
`components`	map<string, ComponentObject>	No	Component-level token groups. Each entry maps a component name to an object with up to eight sub-tokens (see below).

Primitive token types#

Color#

A string starting with # followed by exactly six hexadecimal digits (case-insensitive, sRGB). No shorthand (three-digit) form is accepted.

colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"

primary#1A1C1E tertiary#B8422E neutral#F7F5F2

Dimension#

A number followed immediately by a unit. The three accepted units are px, em, and rem. No space between the number and the unit. Negative values are valid (used for negative letter-spacing).

rounded:
  sm: 4px
  md: 8px
spacing:
  base: 1rem
  tight: 0.5em
typography:
  body-md:
    letterSpacing: "-0.02em"

Token Reference#

A string of the form {path.to.token} that resolves to a token defined elsewhere in the same frontmatter. The reference path is a dot-separated chain of YAML keys.

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    typography: "{typography.label-md}"

Depth limits (from spec-config.yaml):

Limit	Value	What it governs
`max_reference_depth`	10	How many hops a reference chain may follow before the parser stops resolving.
`max_token_nesting_depth`	20	Maximum depth of nested token objects before a standalone `error` finding is emitted (message: "Token nesting depth exceeds maximum allowed depth of 20"). This is distinct from a `broken-ref` error.

A reference that points to a non-existent token triggers a broken-ref error (severity: error).

Typography object#

Each entry under typography maps a name to an object with up to seven sub-fields. All sub-fields are optional; a token with only fontFamily and fontSize is valid.

Sub-field	Type	Description
`fontFamily`	string	CSS `font-family` value. No quotes needed in YAML unless the name contains special characters.
`fontSize`	Dimension	Size with unit (`px`, `em`, `rem`). Example: `48px`, `1.5rem`.
`fontWeight`	number	Numeric weight such as `400` or `700`. In YAML, either a bare number or a quoted string is accepted; both are equivalent.
`lineHeight`	Dimension or number	A Dimension (e.g., `24px`) or a unitless multiplier (e.g., `1.6`). A unitless number multiplies `fontSize`, matching standard CSS behavior.
`letterSpacing`	Dimension	Tracking value. Negative values tighten headlines; positive values open up all-caps labels. Example: `"-0.02em"`, `"0.1em"`.
`fontFeature`	string	Maps to CSS `font-feature-settings`. Controls OpenType features such as tabular numbers (`"tnum"`) or stylistic alternates (`"ss01"`).
`fontVariation`	string	Maps to CSS `font-variation-settings`. Used with variable fonts. Example: `"'wght' 650, 'opsz' 32"`.

Example:

typography:
  h1:
    fontFamily: Public Sans
    fontSize: 48px
    fontWeight: 600
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1.0
    letterSpacing: "0.1em"

Recommended token names (from spec-config.yaml): headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm. Custom names are accepted without error.

Component sub-tokens#

Each entry under components maps a component name to an object. The recognized sub-tokens are:

Sub-token	Type	Description
`backgroundColor`	Color	Fill color of the component surface. Checked against `textColor` for WCAG AA contrast.
`textColor`	Color	Foreground color for text and icons. Checked against `backgroundColor` for WCAG AA contrast.
`typography`	Typography (Reference)	Reference to a typography token (e.g., `{typography.label-md}`). Resolved at lint time.
`rounded`	Dimension	Corner radius. Accepts a literal Dimension or a reference (e.g., `{rounded.md}`).
`padding`	Dimension	Internal padding. Accepts a literal Dimension value.
`size`	Dimension	General size (used for icon size, avatar diameter, etc.).
`height`	Dimension	Explicit height of the component.
`width`	Dimension	Explicit width of the component.

Unknown sub-token names produce a broken-ref warning (severity: warning), not an error. The valid sub-token names are: backgroundColor, textColor, typography, rounded, padding, size, height, width.

Example:

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Canonical section order#

Markdown sections (introduced with ## headings) must appear in this order when present. Sections may be omitted freely; only the relative order of those that do appear is checked.

Position	Canonical name	Accepted aliases
1	Overview	Brand & Style
2	Colors
3	Typography
4	Layout	Layout & Spacing
5	Elevation & Depth	Elevation
6	Shapes
7	Components
8	Do's and Don'ts

Out-of-order sections trigger a section-order warning. Additional or custom sections (Icons, Accessibility, Voice & Tone, etc.) are accepted and preserved by the parser without error. Duplicate top-level YAML keys across multiple code blocks in the same file trigger a parser-level error (the adapter returns a DUPLICATE_SECTION error code, e.g., "Section 'colors' is defined in both frontmatter and code block 2").

Recommended token names#

The spec-config defines recommended names per token group to maximize interoperability with agents and exporters:

Colors: primary, secondary, tertiary, neutral, surface, on-surface, error

Typography: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm

Rounded: none, sm, md, lg, xl, full

These names are recommendations only. Custom names do not produce errors or warnings.

Spec version#

The current spec version is alpha (package @google/design.md 0.3.0). Inspect the live rules table with:

npx @google/design.md spec --rules

Was this page helpful?