Typography

Typography tokens go under the typography key as named objects. Each object has up to seven sub-fields: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, and fontVariation. All sub-fields are optional. Missing typography when colors are defined triggers a linter warning.

Token shape#

Each typography token is a key mapped to an object with named sub-fields. The key is a free-form name (e.g., h1, body-md, label-caps):

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"

Sub-fields reference#

Field	Type	Description
`fontFamily`	string	Font family name as it appears in CSS `font-family`. No quotes needed in YAML unless the name contains special characters.
`fontSize`	Dimension	A number followed by `px`, `em`, or `rem`. Example: `48px`, `1.5rem`.
`fontWeight`	number	Numeric weight (e.g., `400`, `700`). Can be written as a bare number or a quoted string in YAML; both are equivalent.
`lineHeight`	Dimension or number	A Dimension (e.g., `24px`, `1.5rem`) or a unitless multiplier (e.g., `1.6`). A unitless number multiplies `fontSize`, matching standard CSS behavior.
`letterSpacing`	Dimension	Tracking value. Negative values (e.g., `"-0.02em"`) tighten headlines. Positive values (e.g., `"0.1em"`) open up all-caps labels.
`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"`.

All sub-fields are optional. A typography token with only fontFamily and fontSize is valid.

Recommended token names#

The spec-config recommends these names for maximum interoperability with agents and exporters:

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

Custom names (e.g., h1, caption, overline-sm) are accepted without error or warning.

Linter rule: missing-typography#

If colors tokens are defined but no typography tokens exist, the linter fires a missing-typography warning. The message is: "No typography tokens defined. Agents will use default font choices, reducing your control over the design system's typographic identity." This is a warning, not an error. The file remains valid.

Type scale example#

A minimal type scale for a marketing site:

typography:
  headline-display:
    fontFamily: "Playfair Display"
    fontSize: 64px
    fontWeight: 700
    lineHeight: 1.0
    letterSpacing: "-0.03em"
  headline-lg:
    fontFamily: "Playfair Display"
    fontSize: 40px
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  body-md:
    fontFamily: "Inter"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.65
  body-sm:
    fontFamily: "Inter"
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.5
  label-md:
    fontFamily: "Inter"
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1.0
    letterSpacing: "0.08em"
    fontFeature: '"tnum", "ss01"'

Variable font example#

For a variable font, fontVariation controls the optical size and weight axes directly:

typography:
  headline-display:
    fontFamily: "Roboto Flex"
    fontSize: 56px
    fontVariation: "'wght' 720, 'opsz' 56"
    lineHeight: 1.05
    letterSpacing: "-0.025em"
  body-md:
    fontFamily: "Roboto Flex"
    fontSize: 16px
    fontVariation: "'wght' 400, 'opsz' 16"
    lineHeight: 1.6

Using typography in components#

A component can reference a typography token by name using the {typography.token-name} reference syntax:

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

If the reference resolves to a defined typography token, agents can apply all its sub-fields to the component. A broken reference triggers a broken-ref error.

Full DESIGN.md example: typography section#

---
name: Editorial Black
colors:
  primary: "#0D0D0D"
  on-primary: "#FFFFFF"
typography:
  headline-display:
    fontFamily: "Playfair Display"
    fontSize: 64px
    fontWeight: 700
    lineHeight: 1.0
    letterSpacing: "-0.03em"
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.65
  label-caps:
    fontFamily: Inter
    fontSize: 11px
    fontWeight: 600
    letterSpacing: "0.12em"
    fontFeature: '"c2sc", "smcp"'
---

## Typography

Three cuts: a display serif for hero text, a neutral sans for body copy,
and a small-caps label style for metadata and kickers.

- **headline-display:** Playfair Display 700 at 64px; tight tracking pulls
  letterforms together at large sizes.
- **body-md:** Inter Regular 16px at 1.65 line-height; generous leading for
  long-form reading.
- **label-caps:** Inter SemiBold 11px with wide tracking and small-caps
  OpenType feature; used for tags, categories, and nav labels.

Try it in the tool

Was this page helpful?