How to Resolve Broken Token References in DESIGN.md Files

To resolve broken token references in DESIGN.md files, run the linter to identify unresolved or circular references, verify the token exists in the YAML front-matter, correct the syntax to {group.token}, and ensure component properties use only valid sub-tokens.

The google-labs-code/design.md repository provides a CLI tool that validates design token references against your front-matter YAML. When the linter reports a broken-ref error, it indicates that a token reference inside your DESIGN.md file cannot resolve to a defined value, which blocks downstream consumers from processing your design system correctly.

What Causes Broken Token References?

The linter's broken-ref rule (implemented in packages/cli/src/linter/linter/rules/broken-ref.ts) scans every component and reports errors when references fail to resolve. According to the source code, broken references typically fall into three categories.

Non-Existent Token References

A reference points to a token that does not exist in the YAML front-matter. For example, {colors.primary-60} fails when primary-60 is not declared under the colors group. The linter explicitly checks that the dotted path in the curly braces matches a defined primitive value in the YAML tree.

Circular Reference Chains

Token A references Token B, which in turn references Token A, creating an infinite loop. The linter detects these cycles and reports them as broken references because they cannot resolve to concrete values.

Invalid Component Sub-Tokens

Inside the components section, only specific properties are permitted. The broken-ref.ts rule validates against VALID_COMPONENT_SUB_TOKENS, flagging unsupported properties like borderColor that do not match the allowed schema.

Step-by-Step Fix for Broken Token References

Follow these steps to identify and resolve broken references in your DESIGN.md files.

1. Run the Linter to Identify Errors

Execute the CLI lint command to surface all broken references:

npx @google/design.md lint DESIGN.md

The output lists every broken reference with the component path, such as components.button-primary.backgroundColor.

2. Verify the Token Exists in Front-Matter

Open your DESIGN.md file and check the YAML front-matter for the referenced token. If the linter reports {colors.primary-60} as broken, ensure your front-matter includes:

colors:
  primary-60: "#0F0F0F"

If the token is missing, add it with the appropriate primitive value.

3. Correct the Reference Syntax

Ensure the reference follows the exact syntax defined in docs/spec.md: wrapped in curly braces using a dotted path ({group.token}) with no spaces or extra characters. Invalid syntax prevents the linter from parsing the reference correctly.

4. Break Circular References

If you encounter a circular dependency (e.g., spacing.base references spacing.gutter and vice versa), resolve the cycle by converting one reference to a literal value:

# Before (circular)

spacing:
  base: "{spacing.gutter}"
  gutter: "{spacing.base}"

# After (fixed)

spacing:
  base: "16px"
  gutter: "{spacing.base}"

5. Validate Component Properties

Check that component definitions use only recognized sub-tokens. Remove or rename any unsupported properties. For example, change borderColor to a valid property like backgroundColor or textColor as defined in the VALID_COMPONENT_SUB_TOKENS array in the source code.

6. Re-run the Linter

After making corrections, run the linter again to confirm the broken-ref errors are resolved and no new warnings appear.

Common Broken Token Reference Errors and Solutions

Error	Cause	Solution
Typo in token name	{colors.priimary} instead of {colors.primary}	Correct the spelling in the reference or add the missing token to the YAML front-matter
Reference to a group	Using {colors} instead of a specific token	Replace with a concrete token path like {colors.primary}
Missing component sub-token	Using borderColor which is not in VALID_COMPONENT_SUB_TOKENS	Remove the property or rename it to a valid sub-token like backgroundColor
Circular reference	Token A → Token B → Token A	Break the cycle by assigning a literal value to one token

Example: Fixing a Broken Reference

Here is a complete example showing the error state and the corrected version.

Broken state (error):

---
colors:
  primary: "#1A1C1E"
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
---

Running npx @google/design.md lint DESIGN.md produces:

components.button-primary – Reference {colors.primary-60} does not resolve to any defined token.

Fixed state:

---
colors:
  primary: "#1A1C1E"
  primary-60: "#0F0F0F"
components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
---

Key Source Files

Understanding these implementation files helps diagnose complex reference issues:

• packages/cli/src/linter/linter/rules/broken-ref.ts – Contains the broken-ref rule implementation that validates token resolution and component sub-tokens
• docs/spec.md – Defines the formal token reference syntax and scoping rules
• packages/cli/src/linter/linter/rules/index.ts – Aggregates all linter rules including the broken-ref validator
• README.md – Documents the CLI commands and error codes for the linting process

Summary

• Run npx @google/design.md lint DESIGN.md to identify broken references via the broken-ref rule
• Verify that all referenced tokens exist as primitive values in the YAML front-matter
• Use exact {group.token} syntax without spaces, as specified in docs/spec.md
• Resolve circular references by converting one token to a literal value
• Ensure component definitions use only valid sub-tokens defined in VALID_COMPONENT_SUB_TOKENS

Frequently Asked Questions

What does the "broken-ref" error mean in the DESIGN.md linter?

The broken-ref error indicates that a token reference inside your DESIGN.md file cannot resolve to a defined value. According to the implementation in packages/cli/src/linter/linter/rules/broken-ref.ts, this occurs when the reference points to a non-existent token, creates a circular dependency, or uses an invalid component sub-token.

Can I reference an entire token group like {colors}?

No. The specification in docs/spec.md requires that references point to primitive values, not to entire groups. References must use the {group.token} format to specify a concrete value. Component sections are the exception where composite references are permitted, but they still must resolve to valid sub-tokens.

How do I fix circular token references?

Break the cycle by converting one reference in the chain to a literal value. For example, if spacing.base references spacing.gutter and spacing.gutter references spacing.base, change one to a static value like 16px. This allows the linter to resolve the remaining reference successfully.

Why is my component property flagged as a broken reference?

The linter checks component properties against VALID_COMPONENT_SUB_TOKENS to ensure only recognized sub-tokens are used. If you use a property like borderColor that is not in the allowed list, the linter reports it as a broken reference. Remove the unsupported property or rename it to a valid sub-token such as backgroundColor or textColor.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}