Fixing broken-ref in DESIGN.md

Why unresolved references matter#

Component definitions often reference tokens defined elsewhere in the YAML frontmatter:

components:
  button-primary:
    backgroundColor: "{colors.brand}"
    textColor: "{colors.on-brand}"

If brand or on-brand do not exist under colors, the linter cannot resolve those values. Downstream agents, exporters, and the tool's diagnostics panel will either skip those properties or fall back to arbitrary defaults. The broken-ref error ensures the reference chain is complete before the file is accepted.

Two sub-cases#

Sub-case 1: Unresolved token reference (severity: error)#

What triggers it: A component property value contains a reference in {section.token-name} form, and that path does not resolve to any defined token in colors, typography, rounded, or spacing.

The linter rule default severity is error. Individual unresolved-reference findings inherit that severity (no per-finding override), so any unresolved reference causes the CLI to exit with status 1 and the export command to refuse processing.

Example that trips the rule:

---
name: Demo Brand
colors:
  primary: "#1A1C1E"
components:
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "#ffffff"
---

The token accent is referenced but never defined under colors. The linter emits:

{
  "severity": "error",
  "path": "components.button-primary",
  "message": "Reference {colors.accent} does not resolve to any defined token."
}

How to fix:

1. Check the reference path (here: {colors.accent}) and identify the intended token.
2. Either add the missing token to the appropriate section:

   colors:
     primary: "#1A1C1E"
     accent: "#4A6FFF"
   

   Copy
3. Or correct a typo in the reference so it points to an existing token:

   components:
     button-primary:
       backgroundColor: "{colors.primary}"
       textColor: "#ffffff"
   

   Copy

After the fix, npx @google/design.md lint DESIGN.md should report zero errors for broken-ref.

Sub-case 2: Unknown component sub-token name (severity: warning)#

What triggers it: A component definition contains a property whose name is not one of the eight recognized sub-tokens: backgroundColor, textColor, typography, rounded, padding, size, height, width. The finding overrides the rule's default severity to warning, so the file is still accepted, but the unknown property will be silently ignored by exporters and agents.

Example that trips the rule:

---
name: Demo Brand
colors:
  primary: "#1A1C1E"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    borderRadius: 8px
---

borderRadius is not in the recognized list. The linter emits:

{
  "severity": "warning",
  "path": "components.button-primary.borderRadius",
  "message": "'borderRadius' is not a recognized component sub-token. Valid sub-tokens: backgroundColor, textColor, typography, rounded, padding, size, height, width."
}

How to fix:

Map the property to the correct recognized sub-token. For corner rounding, the sub-token is rounded, not borderRadius:

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "#ffffff"
    rounded: 8px

If the intent was to use a token reference, rounded also accepts {rounded.md} and similar references.

The severity distinction in CI#

Because unresolved references are error severity, they cause npx @google/design.md lint to exit with code 1 and block export. Unknown sub-token names are warning and do not affect the exit code. A pipeline that uses the exit code as a gate will catch broken references automatically but will not catch sub-token typos unless you parse the JSON output and check the warnings count.

Check both in JSON mode:

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

The summary object reports errors, warnings, and infos separately.

Circular and deeply nested references#

The parser supports up to 10 levels of reference depth. A reference chain that exceeds that limit, or that contains a cycle (token A references token B which references token A), also counts as an unresolved reference and will produce a broken-ref error.

Related rules#

• missing-primary: warns when no primary color token is defined.
• contrast-ratio: warns when a backgroundColor/textColor pair fails WCAG AA (4.5:1).
• CLI and Lint Rules Reference: full rules table and command reference.

Try it in the tool