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.

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 two 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).

Both 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."
}

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).

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.

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.

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?