Fixing token-like-ignored in DESIGN.md

Why ignored token maps matter#

Only five top-level keys in a DESIGN.md file hold tokens: colors, typography, rounded, spacing, and components. The other schema keys (version, name, description, omitted) describe the file. Anything under a key outside those nine is not part of the token model. The linter's other rules never see it, diff never lists its values among added, removed, or modified tokens, and every export format leaves it out. An agent or tool that works from the parsed tokens gets a design system without those values, while the YAML still looks complete to a person reading it.

Until 0.4.0, the only check on unrecognized keys was unknown-key, added in 0.3.0, which catches keys within two edits of a schema key. A key such as brandColors or palette is too far from every schema key for that, so its values disappeared without a warning. token-like-ignored closes the gap by looking at the values instead of the spelling.

What counts as token-like#

The rule checks every unrecognized top-level key whose value is a map. It reports the key when any entry in that map, at any depth, matches one of these:

• A key named fontFamily, fontSize, fontWeight, lineHeight, or letterSpacing.
• A string of at most 64 characters that is a hex color: #RGB, #RGBA, #RRGGBB, or #RRGGBBAA.
• A string of at most 64 characters that is a CSS dimension: a number followed by letters or %, such as 8px, 1.5rem, or 50%.

Nested maps are checked recursively. The rule emits one finding per key, however many token-like values it holds, and the finding's path is the key name.

How 0.4.0 treats some common unrecognized keys:

The check is a heuristic. A misplaced palette written as rgb() or oklch() values, or a scale of bare numbers, is still dropped without any warning, so compare the token-summary counts against what you meant to define.

What triggers it#

Example that trips the rule:

---
name: Harbor
colors:
  primary: "#0B5FFF"
  on-primary: "#FFFFFF"
brandColors:
  accent: "#FF5A1F"
  highlight: "#FFD166"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
spacing:
  sm: 8px
  md: 16px
rounded:
  md: 8px
---

## Colors

A deep blue primary, with an orange accent and a yellow highlight for promotions.

brandColors is five edits away from colors, so unknown-key stays silent. Its entries are hex colors, so the map is token-like. The complete output of npx @google/design.md lint DESIGN.md:

{
  "findings": [
    {
      "severity": "info",
      "message": "Design system defines 2 colors, 1 typography scale, 1 rounding level, 2 spacing tokens.",
      "rule": "token-summary"
    },
    {
      "severity": "warning",
      "path": "brandColors",
      "message": "\"brandColors\" 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": 1, "infos": 1 }
}

The token-summary count already shows the loss: two colors, not four. The viewer at /tool lists the same warning with its rule id and a link to this page.

What export writes#

Running npx @google/design.md export DESIGN.md --format css-vars on the same file prints:

:root {
  --color-primary: #0b5fff;
  --color-on-primary: #ffffff;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --rounded-md: 8px;
}

accent and highlight are missing, and the export still exits with code 0. Since 0.4.0, a successful export never fails because of lint findings, so the warning from lint is the only signal.

How to fix#

Option A: move the values under the matching schema group

---
name: Harbor
colors:
  primary: "#0B5FFF"
  on-primary: "#FFFFFF"
  accent: "#FF5A1F"
  highlight: "#FFD166"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
spacing:
  sm: 8px
  md: 16px
rounded:
  md: 8px
---

The linter now reports only Design system defines 4 colors, 1 typography scale, 1 rounding level, 2 spacing tokens., and the css-vars export gains --color-accent: #ff5a1f; and --color-highlight: #ffd166;.

To keep related colors together, nest them as a group inside colors instead of a separate top-level key. A brand: group with an accent entry becomes the token brand.accent and exports as --color-brand-accent.

Option B: rename the key

If the key is a misspelled schema key and the file does not already use the correct one, rename it: colour: becomes colors:. Do not rename a second map to a key that already exists. YAML keys must be unique, and a file with two colors: keys fails to parse: the linter reports Map keys must be unique and runs no other checks.

Option C: document values that have no token group

Motion durations, breakpoints, and similar values have no group in the schema. Describe them in the Markdown body instead, for example under a custom ## Motion heading. Custom headings do not affect the section-order rule.

After the fix, re-run npx @google/design.md lint DESIGN.md to confirm the warning is gone.

Relationship to unknown-key#

The two rules look at different things. unknown-key checks the spelling of a key; token-like-ignored checks what the key holds. A key can trip either, both, or neither:

For the colour case, 0.4.0 reports both findings on the same path:

[
  {
    "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"
  }
]

The CLI prints an em dash in the unknown-key message; the example writes it as the JSON escape \u2014, which decodes to the same character. Renaming colour to colors clears both warnings.

Related rules#

• unknown-key: warns when a top-level key looks like a typo of a schema key.
• token-summary: info that counts the tokens the linter actually parsed.
• omitted-rules: the other check added in 0.4.0, for token groups a file leaves out on purpose.
• CLI and Lint Rules Reference: full rules table and command reference.

Try it in the tool