# How to Fix Broken Token References in DESIGN.md: A Complete Guide

> Fix broken token references in DESIGN.md with this complete guide. Learn to identify and resolve invalid syntax and circular dependencies for seamless documentation.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: how-to-guide
- Published: 2026-06-26

---

**Run `npx @google/design.md lint DESIGN.md` to identify broken references, then verify that every token wrapped in curly braces exists in the YAML front-matter and uses valid dotted-path syntax without circular dependencies.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository defines a Markdown-based specification for design tokens that relies on YAML front-matter for token definitions. When working with these files, you may encounter `broken-ref` errors that prevent successful linting or export, typically caused by token references that cannot resolve to defined values. Learning how to fix broken token references in DESIGN.md is essential for maintaining valid design systems that compile correctly for downstream consumers.

## How the Broken-Ref Rule Works

The linter's **broken-ref rule** is implemented in [`packages/cli/src/linter/linter/rules/broken-ref.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/broken-ref.ts) at lines 22-31. This rule scans every component definition in your DESIGN.md file to detect two specific categories of errors:

1. **Unresolved references** – Token references in curly braces that point to non-existent tokens in the YAML front-matter
2. **Unknown component sub-tokens** – Properties within component definitions that are not recognized as valid sub-tokens

According to the implementation at lines 34-41 of the same file, the rule validates component properties against a `VALID_COMPONENT_SUB_TOKENS` constant, flagging any unsupported properties as warnings.

## Common Causes of Broken References

Token references break for several specific reasons defined in the specification at [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) (lines 86-88):

- **Reference syntax errors** – Tokens must be wrapped in curly braces and use dotted notation (e.g., `{colors.primary}`) that matches the YAML tree structure exactly
- **Missing token definitions** – A reference like `{colors.primary-60}` fails when `primary-60` is not declared in the front-matter colors group
- **Circular dependencies** – Token A references Token B, which references Token A, creating an infinite resolution loop
- **Invalid scope** – Most token groups require references to point to primitive values, not entire groups, though the `components` section allows composite references
- **Unsupported component properties** – Using property names like `borderColor` that are not included in the valid sub-tokens list

## Step-by-Step Resolution Process

Follow these steps to resolve broken token references in your DESIGN.md files:

1. **Run the linter** – Execute `npx @google/design.md lint DESIGN.md` to generate a report of all broken references with specific component paths

2. **Locate the offending reference** – Open the error message to find the full path (e.g., `components.button-primary.backgroundColor`) and locate the corresponding line in your markdown

3. **Verify token existence** – Check the YAML front-matter for the referenced token name. Ensure the group and token exist exactly as spelled in the reference

4. **Correct the syntax** – Ensure references follow the exact format `{group.token}` with no extra spaces, missing braces, or incorrect punctuation as specified in [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)

5. **Resolve circular references** – If token A references token B, ensure token B does not reference token A. Break the cycle by converting one reference to a primitive literal value

6. **Validate component sub-tokens** – Remove any properties from component definitions that are not recognized sub-tokens, or rename them to valid alternatives like `backgroundColor` or `textColor`

7. **Re-run the linter** – Execute the lint command again to confirm all `broken-ref` errors are resolved

## Code Examples

### Broken Reference (Missing Token)

This DESIGN.md file references a token that does not exist in the front-matter:

```markdown
---
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 Reference

Add the missing token to resolve the error:

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

```

### Circular Reference (Invalid)

This YAML creates an infinite loop:

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

```

### Circular Reference Resolved

Break the cycle with literal values:

```yaml
spacing:
  base: "16px"
  gutter: "24px"

```

### Invalid Component Sub-Token

This example uses an unsupported property:

```yaml
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    borderColor: "#ff0000"   # Not a valid sub-token

```

Fix by removing the invalid property or renaming it to a recognized sub-token defined in the validator.

## Summary

- **Broken token references** occur when DESIGN.md files contain references to non-existent tokens, circular dependencies, or invalid component sub-tokens
- **The linter** at [`packages/cli/src/linter/linter/rules/broken-ref.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/broken-ref.ts) automatically detects these issues when you run `npx @google/design.md lint DESIGN.md`
- **Reference syntax** must follow `{group.token}` format exactly as defined in the specification at [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)
- **Component sub-tokens** are restricted to a specific allow-list; unsupported properties trigger warnings
- **Circular references** must be broken by converting one side of the cycle to a primitive value

## Frequently Asked Questions

### What is the exact syntax for token references in DESIGN.md?

Token references must be wrapped in curly braces and use dotted notation that matches the YAML front-matter structure exactly, such as `{colors.primary}` or `{spacing.large}`. According to [`docs/spec.md`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) at line 86, the reference path must correspond to a primitive value in the token group, not the group itself, unless you are working within the special `components` section which allows composite references.

### How do I identify circular references in my design tokens?

Circular references occur when two tokens reference each other directly or through a chain of dependencies that loops back to the start. You can identify them by examining your YAML front-matter for any tokens that use curly-brace references to other tokens that might reference back. The linter will flag these as resolution errors, and you should break the cycle by giving at least one token in the loop a literal primitive value instead of a reference.

### What component sub-tokens are considered valid in DESIGN.md?

The `components` section only accepts specific property names defined in the `VALID_COMPONENT_SUB_TOKENS` constant within [`packages/cli/src/linter/linter/rules/broken-ref.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/broken-ref.ts) (lines 34-41). While the exact list depends on the current version of the linter, valid sub-tokens typically include standard properties like `backgroundColor` and `textColor`. Properties like `borderColor` will trigger warnings unless they are explicitly added to the valid tokens list.

### How do I run the linter locally to check for broken references?

Navigate to your project directory containing DESIGN.md and run `npx @google/design.md lint DESIGN.md`. This command, documented in the repository's [`README.md`](https://github.com/google-labs-code/design.md/blob/main/README.md) at lines 313-321, will scan your file and output specific error messages indicating which component paths contain broken references and what the unresolved tokens are.