Fixing unknown-key in DESIGN.md

Why typo detection matters#

The nine recognized top-level YAML keys in a DESIGN.md file are version, name, description, omitted, colors, typography, rounded, spacing, and components. Any key outside that set is unknown to the spec. Unknown keys are left out of the token model: none of the token values under a mistyped key are read by the linter's other rules, by export, or by agents and tools that work from the parsed tokens.

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. Since 0.4.0, token-like-ignored adds a second check that looks at the values under an unknown key instead of its spelling.

The nine recognized schema keys#

How Levenshtein distance is used#

The rule computes the Levenshtein distance between the unknown key (lowercased) and each of the nine known keys (also lowercased). To keep the check fast, 0.4.0 skips known keys whose length differs from the unknown key by more than two characters; such a pair is always more than two edits apart, so the outcome is the same. 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 rule emits nothing for that key, although token-like-ignored may still report it.

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. Because the comparison is lowercased, a key that differs only in case, such as Colors, has distance 0 and is flagged too.

Common typos caught by the rule:

Keys that fall outside the threshold:

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. Because colour holds hex colors, 0.4.0 also emits a token-like-ignored warning on the same path. The complete output of npx @google/design.md lint DESIGN.md:

{
  "findings": [
    {
      "severity": "warning",
      "path": "colour",
      "message": "Unknown key \"colour\" \u2014 did you mean \"colors\"?",
      "rule": "unknown-key"
    },
    {
      "severity": "warning",
      "path": "colour",
      "message": "\"colour\" looks like a design-token map but is not a recognized schema key (colors, typography, spacing, rounded, components). It will be silently ignored by export commands. Rename it to a supported key or move its values under a recognized section.",
      "rule": "token-like-ignored"
    }
  ],
  "summary": { "errors": 0, "warnings": 2, "infos": 0 }
}

The CLI prints an em dash between the unknown key and the suggestion. The JSON above writes it as the escape \u2014, which decodes to the same character. No token-summary finding appears: with the palette under an unknown key, the file defines no tokens at all.

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 both the unknown-key and the token-like-ignored warnings are 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 key three or more edits away from every schema key never gets an unknown-key warning. Since 0.4.0 that no longer means silence: if the key holds a map with hex colors, dimension strings such as 8px, or typography properties such as fontFamily, token-like-ignored reports it. A misplaced brandColors: or palette: map is flagged that way.

Only keys whose values do not look like tokens stay silent, for example owner: "Design team", a list of tags, or a map of bare numbers or rgb() colors. If you suspect such 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.

Related rules#

• token-like-ignored: warns when an unknown top-level key holds token-like values that export would drop.
• omitted-rules: the omitted key and the findings that validate it.
• 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