# What Is the `broken-ref` Linting Rule in Design-MD?

> Learn how the broken-ref linting rule in Design-MD finds unresolved token references and unrecognized component sub-tokens to ensure your specifications are valid.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: deep-dive
- Published: 2026-06-25

---

**The `broken-ref` linting rule validates Design-MD specifications by flagging unresolved token references as errors and warning against unrecognized component sub-tokens.**

The `broken-ref` linting rule is a core validation mechanism in the **Design-MD** specification toolchain maintained by Google Labs. According to the google-labs-code/design.md repository, this rule ensures that design tokens and component properties remain type-safe and resolvable throughout the development lifecycle.

## How the `broken-ref` Rule Detects Unresolved Token References

The primary responsibility of the `broken-ref` linting rule is to **detect unresolved token references**. When a component property refers to a token using the curly-brace syntax (e.g., `"{colors.primary}"`) that does not exist in the design system, the rule records an error. This prevents broken styling references from propagating into generated code or UI previews.

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), the implementation iterates over each component’s `unresolvedRefs` collection and pushes a finding for every entry that cannot be resolved (lines 22-31). If a specification references `{colors.nonexistent}` while only `{colors.primary}` is defined, the linter emits a severity-`error` finding.

```ts
import { lintDesign } from '@design-md/cli';
import { brokenRefRule } from './broken-ref.js';

const designSpec = {
  colors: { primary: '#ff0000' },
  components: {
    button: { backgroundColor: '{colors.nonexistent}' }, // ← unresolved
  },
};

const results = lintDesign(designSpec, [brokenRefRule]);
console.log(results);
// → [
//     {
//       path: 'components.button',
//       message: 'Reference {colors.nonexistent} does not resolve to any defined token.',
//       severity: 'error',
//     }
//   ]

```

## Validating Component Sub-Tokens with `broken-ref`

The rule also performs a secondary check against **unknown component sub-tokens**. Design-MD defines a whitelist of valid property names (`VALID_COMPONENT_SUB_TOKENS`). If a component contains a property name not present in this list, the `broken-ref` rule emits a **warning** (not an error) to guide authors toward supported tokens while still allowing the specification to be linted.

This logic is implemented in [`broken-ref.ts`](https://github.com/google-labs-code/design.md/blob/main/broken-ref.ts) (lines 33-41), where a second loop inspects each component’s property names and creates a warning finding when a name is missing from the whitelist.

```ts
import { lintDesign } from '@design-md/cli';
import { brokenRefRule } from './broken-ref.js';

const designSpec = {
  colors: { primary: '#ff0000' },
  components: {
    button: { borderColor: '#ff0000' }, // “borderColor” is not a valid sub‑token
  },
};

const results = lintDesign(designSpec, [brokenRefRule]);
console.log(results);
// → [
//     {
//       path: 'components.button.borderColor',
//       message: "'borderColor' is not a recognized component sub-token. Valid sub-tokens: …",
//       severity: 'warning',
//     }
//   ]

```

## Rule Configuration and Severity

The `broken-ref` rule is exposed through a descriptor object named `brokenRefRule` that declares its default severity as **error**, provides a short description, and references the runner function (lines 47-52 in [`broken-ref.ts`](https://github.com/google-labs-code/design.md/blob/main/broken-ref.ts)). The linter framework aggregates these findings with those from other rules, presenting developers a consolidated report of design-system issues before code generation or publishing.

By catching both hard problems (missing tokens) and soft problems (unsupported sub-tokens), the rule helps maintain a consistent, type-safe design token ecosystem across projects.

## Running the `broken-ref` Rule from the Command Line

You can invoke the `broken-ref` linting rule directly via the Design-MD CLI to validate specification files before they enter your build pipeline.

```bash
design-md lint ./my-design.yaml --rule broken-ref

```

The CLI outputs unresolved references as errors and unknown sub-tokens as warnings, mirroring the programmatic behavior of the `lintDesign` function.

## Summary

- The **`broken-ref` linting rule** detects unresolved token references (errors) and unknown component sub-tokens (warnings) in Design-MD specifications.
- It validates component properties against the **`VALID_COMPONENT_SUB_TOKENS`** whitelist to ensure type safety.
- The core implementation resides 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)**, specifically handling `unresolvedRefs` iteration (lines 22-31) and sub-token validation (lines 33-41).
- The rule descriptor **`brokenRefRule`** exposes the runner with a default severity of **error**.
- Available via CLI using **`design-md lint --rule broken-ref`**.

## Frequently Asked Questions

### What triggers an error in the `broken-ref` linting rule?

An error occurs when a component property references a design token that does not exist in the specification, such as `"{colors.nonexistent}"` when only `"{colors.primary}"` is defined. The rule iterates through the `unresolvedRefs` collection in [`broken-ref.ts`](https://github.com/google-labs-code/design.md/blob/main/broken-ref.ts) (lines 22-31) and assigns severity `error` to these findings.

### What is the difference between an error and a warning in the `broken-ref` rule?

Errors are generated for **unresolved token references** that would break code generation, while **warnings** are generated for component properties that are not in the `VALID_COMPONENT_SUB_TOKENS` whitelist. Warnings allow the specification to pass linting but alert authors to use supported sub-tokens for better compatibility.

### How do I run the `broken-ref` linting rule from the command line?

Execute `design-md lint ./my-design.yaml --rule broken-ref` or include the rule in your [`design-md.config.js`](https://github.com/google-labs-code/design.md/blob/main/design-md.config.js) file. The CLI will process the specification and output any validation findings directly to the terminal.

### Where is the `broken-ref` rule implemented in the Design-MD source code?

The rule logic 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)**, with unit tests in **[`broken-ref.test.ts`](https://github.com/google-labs-code/design.md/blob/main/broken-ref.test.ts)** and registration in **[`rules/index.ts`](https://github.com/google-labs-code/design.md/blob/main/rules/index.ts)**. These files define, expose, and validate the rule within the Design-MD CLI package.