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

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, 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.

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 (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.

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). 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.

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, 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 (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 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, with unit tests in broken-ref.test.ts and registration in rules/index.ts. These files define, expose, and validate the rule within the Design-MD CLI package.

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