Fixing unknown-key in DESIGN.md

The unknown-key rule fires with severity: warning when a top-level YAML key is not one of the eight recognized schema keys and its spelling is within two edits (Levenshtein distance) of a known key. Keys that differ by more than two edits are silently ignored. The warning is advisory; the file is accepted.

Why typo detection matters#

The eight recognized top-level YAML keys in a DESIGN.md file are version, name, description, colors, typography, rounded, spacing, and components. Any key outside that set is unknown to the spec. Unknown keys are silently ignored by the parser and by every agent that consumes the file: none of the token values under a mistyped key are read.

This silent discard is the core problem. A file with colour: ... instead of colors: ... appears well-formed; the YAML parses without error. But the entire color palette is invisible to the linter, to the export command, and to downstream agents. The unknown-key rule catches the subset of unknown keys that look like typos (within two character edits) and surfaces them as warnings so you can correct the key before the silent discard affects your output.

The eight recognized schema keys#

Key	Purpose
`version`	Schema version of the DESIGN.md file.
`name`	Human-readable name of the design system.
`description`	Short prose description of the design system's intent.
`colors`	Map of named color tokens (hex values or token references).
`typography`	Map of named typography scale tokens.
`rounded`	Map of named corner-radius tokens.
`spacing`	Map of named spacing tokens.
`components`	Map of named component style definitions.

How Levenshtein distance is used#

The rule computes the Levenshtein distance between the unknown key (lowercased) and each of the eight known keys (also lowercased). The closest match is selected. If the minimum distance is 2 or fewer, the rule emits a warning naming the closest known key as the likely intended key. If the minimum distance is 3 or more, the key is silently ignored: no warning, no error.

The maximum distance of 2 covers the most common class of typos: one deletion (colours vs colors, distance 1), one substitution (typograhy vs typography, distance 1), one insertion (rouneded vs rounded, distance 1), or one deletion (spacng vs spacing, distance 1). It also covers pairs requiring two edits, such as two substitutions (colour vs colors, distance 2), which catches slightly more divergent variants.

Common typos caught by the rule:

Unknown key	Closest match	Distance
`colour`	`colors`	2
`colours`	`colors`	1
`typograhy`	`typography`	1
`rouneded`	`rounded`	1
`spacng`	`spacing`	1
`component`	`components`	1

Keys that fall outside the threshold and are silently ignored:

Unknown key	Closest match	Distance
`palette`	`name`	5
`fonts`	`colors`	4
`radius`	`name`	5

What triggers it#

The rule checks all top-level YAML keys against the known set. Keys that are already recognized are skipped. For each unrecognized key, it computes the minimum Levenshtein distance to any known key. If that distance is 2 or fewer, a warning is emitted.

Example that trips the rule:

---
name: Dusk Theme
colour:
  primary: "#3D2B8E"
  surface: "#FAF8F5"
---

## Colors

A deep violet primary on a warm off-white surface.

The key colour is not in the recognized set. Its Levenshtein distance from colors is 2: both words are six characters long, and two substitutions are needed to align them (u to r at position five, then r to s at position six). The linter emits a warning.

The actual CLI message uses an em dash as the separator between the unknown key and the suggestion (for example: Unknown key "colour" [em dash] did you mean "colors"?). The exact JSON output is:

{
  "severity": "warning",
  "path": "colour",
  "message": "Unknown key \"colour\": did you mean \"colors\"?"
}

(Note: the JSON example above substitutes a colon for the em dash separator. The actual CLI output uses an em dash in that position. This matches how the reference page at /guide/cli presents the message.)

How to fix#

Rename the top-level key in the YAML frontmatter to the closest recognized key.

Step 1: Note the suggested correction in the warning message.

Step 2: Open the DESIGN.md file and find the misspelled top-level key.

Step 3: Replace it with the exact recognized key name (case-sensitive: colors, not Colors).

Step 4: Re-run npx @google/design.md lint DESIGN.md to confirm the warning is gone.

Corrected example:

---
name: Dusk Theme
colors:
  primary: "#3D2B8E"
  surface: "#FAF8F5"
---

## Colors

A deep violet primary on a warm off-white surface.

The key colour is renamed to colors. The linter now recognizes the section, parses the two color tokens, and the unknown-key warning is gone. The previously invisible primary and surface tokens are now available to other rules (including missing-primary, contrast-ratio, and orphaned-tokens).

Keys with no suggestion#

A completely unrelated key (Levenshtein distance 3 or more) produces no warning and is silently dropped. There is no way to detect these from the lint output. If you suspect a key is being ignored, run:

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

Then check the token-summary info finding. If a section you defined (for example, rounded) reports zero tokens, that section's key may be unrecognized and too far from any known key to trigger unknown-key.

missing-primary: warns when no primary color is defined.
missing-typography: warns when colors exist but no typography tokens are defined.
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?