Fixing missing-typography in DESIGN.md

The missing-typography rule fires with severity: warning when your colors map has at least one entry but no typography tokens are defined. The file is accepted (warnings do not fail the CLI), but agents will fall back to their own default font choices instead of using fonts you specified. Since 0.4.0, listing typography in the omitted key suppresses the warning when the gap is intentional.

Why typography tokens matter#

When a DESIGN.md file defines color tokens but omits typography, agents that consume the file have a partial picture of the design system. They know the palette but have no authoritative information about typefaces, scales, or weights. The result is that each agent independently picks fonts and sizes: a text generation tool may use one typeface, a component generator may use another, and a documentation renderer may use a third. None of these choices are traceable back to your specification.

Typography tokens close that gap. A body-md token with an explicit fontFamily, fontSize, and fontWeight is a contract: any conforming agent must use those values when rendering body text. The rule is advisory (warning severity) because a file without typography is structurally valid. You can ship it. The warning signals that typographic control has been left to the agent rather than expressed in the file.

What triggers it#

The rule checks three conditions simultaneously:

The colors map has at least one entry (the rule does not fire on a completely empty file).
The typography map has zero entries (an absent typography: key and an empty typography: block are both treated as zero entries).
typography is not listed in the omitted key (see Skipping typography on purpose).

All three conditions must hold. A file with only typography tokens and no colors does not trigger the rule.

Example that trips the rule:

---
name: Studio Noir
colors:
  primary: "#111111"
  surface: "#F7F5F2"
  accent: "#C84B2D"
---

## Colors

A near-black primary on a warm off-white surface, with a burnt-orange accent.

No typography key is present. The linter emits:

{
  "severity": "warning",
  "path": "typography",
  "message": "No typography tokens defined. Agents will use default font choices, reducing your control over the design system's typographic identity.",
  "rule": "missing-typography"
}

How to fix#

Add a typography map to the YAML frontmatter with at least one named token. Each token requires at minimum a fontFamily and a fontSize.

Step 1: Choose a scale name. The spec recommends following the pattern headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm. You do not need all nine; one is enough to suppress the warning.

Step 2: Add the token with the supported properties (fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation). Since 0.4.0, a property name outside that list, such as a misspelled lineHeigth, gets its own warning at typography.<token>.<property>.

Step 3: Run the linter to confirm zero warnings.

Corrected example:

---
name: Studio Noir
colors:
  primary: "#111111"
  surface: "#F7F5F2"
  accent: "#C84B2D"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
---

## Colors

A near-black primary on a warm off-white surface, with a burnt-orange accent.

## Typography

Inter at 16 px / 1.6 line height for body text.

After this addition, re-run the linter:

npx @google/design.md lint DESIGN.md --format json

The missing-typography warning will no longer appear.

Skipping typography on purpose#

Some design systems deliberately leave fonts to someone else, for example a component kit that inherits type from the host app's theme. In that case, declare the gap with the omitted key instead of adding placeholder tokens:

---
name: Studio Noir
omitted:
  - section: typography
    reason: "Fonts come from the host app's theme"
colors:
  primary: "#111111"
  surface: "#F7F5F2"
  accent: "#C84B2D"
---

## Colors

A near-black primary on a warm off-white surface, with a burnt-orange accent.

The missing-typography warning is gone, and the file's warning count drops to zero. In its place, the omitted-rules check reports an info:

{
  "severity": "info",
  "path": "omitted.typography",
  "message": "typography intentionally omitted \u2014 no typography tokens will be validated",
  "rule": "declared-omission"
}

The CLI prints an em dash in this message; the JSON escape \u2014 stands for it. The plain form - typography works the same way; the reason is optional and does not appear in the lint output. If the file later gains typography tokens, the entry turns into a redundant-omission warning. See the omitted key for details.

Recommended starting set#

Adding only the minimum one token suppresses the rule. However, a complete set gives agents a richer typographic system to work with. The spec recommends these nine scale names:

typography:
  headline-display:
    fontFamily: Inter
    fontSize: 48px
    fontWeight: 700
    lineHeight: 1.1
    letterSpacing: "-0.02em"
  headline-lg:
    fontFamily: Inter
    fontSize: 32px
    fontWeight: 600
    lineHeight: 1.2
  headline-md:
    fontFamily: Inter
    fontSize: 24px
    fontWeight: 600
    lineHeight: 1.3
  body-lg:
    fontFamily: Inter
    fontSize: 18px
    fontWeight: 400
    lineHeight: 1.6
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
  body-sm:
    fontFamily: Inter
    fontSize: 14px
    fontWeight: 400
    lineHeight: 1.5
  label-lg:
    fontFamily: Inter
    fontSize: 14px
    fontWeight: 500
    lineHeight: 1.0
  label-md:
    fontFamily: Inter
    fontSize: 12px
    fontWeight: 500
    lineHeight: 1.0
  label-sm:
    fontFamily: Inter
    fontSize: 11px
    fontWeight: 500
    lineHeight: 1.0
    letterSpacing: "0.05em"

Adjust fontFamily to match your brand typeface. All nine entries can reference a single family or mix families (e.g., a serif headline face with a sans-serif body face).

Typography tokens and components#

Once typography tokens exist, component definitions can reference them:

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.surface}"
    typography: "{typography.label-lg}"
    rounded: 4px
    padding: 12px

The typography component sub-token accepts a reference in {typography.<name>} form. If the reference is unresolved, the broken-ref rule will flag it with severity error. Defining the token first ensures the reference resolves cleanly.

omitted-rules: the omitted key that marks typography as skipped on purpose, and the findings that validate it.
missing-primary: warns when no primary color is defined.
missing-sections: info finding when spacing or rounded are absent.
broken-ref: error when a token reference cannot be resolved.
CLI and Lint Rules Reference: full rules table and command reference.

Try it in the tool

Was this page helpful?