# How to Resolve Broken Token References in DESIGN.md Files

> Fix broken token references in DESIGN.md files. Run the linter, verify YAML tokens, correct syntax, and ensure valid sub-tokens for seamless documentation.

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

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

```bash
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:

```yaml
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`](https://github.com/google-labs-code/design.md/blob/main/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:

```yaml

# 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):**

```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 state:**

```markdown
---
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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)** – Defines the formal token reference syntax and scoping rules
- **[`packages/cli/src/linter/linter/rules/index.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/index.ts)** – Aggregates all linter rules including the broken-ref validator
- **[`README.md`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`.