# How to Fix Broken Token References with the broken-ref Lint Rule in Design MD

> Fix broken token references in Design MD with the broken-ref lint rule. Learn to identify and resolve missing tokens and unsupported property names for a cleaner design system.

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

---

**The `broken-ref` lint rule detects unresolved token references and unknown component sub-tokens in Design System Specifications, reporting errors for missing tokens and warnings for unsupported property names.**

The `broken-ref` rule is a core validator in the Design MD CLI linter that ensures your Design System Specification remains internally consistent. As implemented in the [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository, this rule scans component definitions to verify that every token reference points to a defined token and that every property uses supported sub-token names.

## What the broken-ref Rule Checks

The rule 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) performs two distinct validation passes over the `DesignSystemState`.

### Unresolved Token References

The rule iterates through every component's `unresolvedRefs` array to catch references that cannot be resolved to a defined token. At lines 22–31, the code walks each component and creates an error finding for any `ref` value that does not point to an entry in the `tokens` section of the spec.

### Unknown Component Sub-Tokens

The rule validates property names against the `VALID_COMPONENT_SUB_TOKENS` constant defined in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts). At lines 34–42, the code checks each `[propName]` in `comp.properties`. If the property name is not listed in the allowed sub-tokens, the rule adds a **warning** (not an error) to the report.

## How to Fix Broken Token References

Follow this workflow to resolve issues flagged by the `broken-ref` rule.

### 1. Locate the Offending Component

The linter output includes the full component path (e.g., `components.Button`). Note the specific reference path that "does not resolve" or the property name flagged as unrecognized.

### 2. Verify Token Existence

Open your Design System Specification file and check the `tokens` section. Confirm whether the token referenced in the component's `ref` field actually exists.

### 3. Correct or Add the Missing Token

- **If the token is misspelled**, update the `ref` value in the component definition to match the exact token name.
- **If the token is missing**, define it under `tokens.<tokenName>` with the appropriate value structure.

### 4. Resolve Unknown Sub-Token Warnings

For warnings about property names not in `VALID_COMPONENT_SUB_TOKENS`:

- **Rename the property** to one of the standard allowed tokens (such as `background`, `color`, or `border`).
- **Extend the whitelist** only if you control the specification and need a custom sub-token. Modify `VALID_COMPONENT_SUB_TOKENS` in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts).

### 5. Re-run the Linter

After editing the spec file, execute the lint command to verify the fixes:

```bash
design-md lint <your-spec>.md

```

## Code Examples: Before and After

### Fixing an Unresolved Token Reference

**Before (broken):**

```yaml
components:
  Button:
    ref: tokens.buttonPrimary   # Token does not exist

    background: primary

```

**Linter output:**

```

error: components.Button – Reference tokens.buttonPrimary does not resolve to any defined token.

```

**After (fixed):**

```yaml
tokens:
  buttonPrimary:
    background: '#ff5722'
    color: '#ffffff'

components:
  Button:
    ref: tokens.buttonPrimary
    background: primary

```

### Fixing an Unknown Sub-Token

**Before (warning):**

```yaml
components:
  Card:
    background: surface
    shadow: medium   # 'shadow' is not in VALID_COMPONENT_SUB_TOKENS

```

**Linter output:**

```

warning: components.Card.shadow – 'shadow' is not a recognized component sub-token.

```

**After (fixed):**

```yaml
components:
  Card:
    background: surface
    elevation: medium   # 'elevation' is a valid sub-token

```

## Summary

- The **broken-ref** rule is defined 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) with a default severity of `error`.
- It validates two issues: **unresolved token references** (errors) and **unknown component sub-tokens** (warnings).
- Fix unresolved refs by ensuring the target token exists in the `tokens` section or correcting the reference path.
- Fix sub-token warnings by renaming properties to match `VALID_COMPONENT_SUB_TOKENS` or extending the whitelist in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts).
- The rule metadata is exported as `brokenRefRule` following the `RuleDescriptor` interface consumed by the linter engine in [`packages/cli/src/linter/lint.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/lint.ts).

## Frequently Asked Questions

### What severity level does the broken-ref rule use for different issues?

The rule reports **errors** for unresolved token references and **warnings** for unknown component sub-tokens. This distinction is configured in the `RuleDescriptor` exported at lines 47–52 of [`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), where the default severity is set to `'error'` for the rule itself, while sub-token checks explicitly emit warnings.

### Where is the list of valid component sub-tokens defined?

The `VALID_COMPONENT_SUB_TOKENS` constant is defined in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts). This file establishes the canonical list of property names that components are allowed to use without triggering a warning from the `broken-ref` rule.

### Can I add custom sub-tokens to the valid list?

Yes, but only if you maintain control over the specification codebase. To add custom sub-tokens, modify the `VALID_COMPONENT_SUB_TOKENS` array in [`packages/cli/src/linter/model/spec.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/model/spec.ts). After changing the source code, rebuild the CLI to apply the new validation rules to your Design System Specifications.

### How does the linter identify which references are broken?

The linter builds a `DesignSystemState` object (prepared in [`packages/cli/src/linter/spec-config.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/spec-config.ts)) that tracks every component's `unresolvedRefs` array. The `broken-ref` rule simply iterates this array at lines 22–31 of its implementation file, creating a finding for each entry that remains unresolved after the spec is fully parsed.