# The Nine Validation Rules for the DESIGN.md Linter Explained

> Discover the nine validation rules for the DESIGN.md linter: broken-ref, missing-primary, contrast-ratio, orphaned-tokens, token-summary, missing-sections, missing-typography, section-order, and unknown-key. Learn how they catc...

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

---

**The DESIGN.md linter validates design system definitions using nine specific rules—broken-ref, missing-primary, contrast-ratio, orphaned-tokens, token-summary, missing-sections, missing-typography, section-order, and unknown-key—each with defined severities to catch critical errors, unused tokens, and spec violations.**

The [`google-labs-code/design.md`](https://github.com/google-labs-code/design.md/blob/main/google-labs-code/design.md) repository includes a command-line linter that enforces strict consistency across design system files. These nine DESIGN.md linter validation rules are exported as `DEFAULT_RULE_DESCRIPTORS` from [`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), forming the complete default rule set applied to every [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file.

## Error-Level Validation Rules

Two rules default to `error` severity, halting validation when critical issues are detected.

### broken-ref

The **broken-ref** rule detects unresolved token references and unknown component sub-tokens. When a `$color.foo` reference appears in your file but resolves to no defined token, this rule triggers an error. The 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).

### contrast-ratio

The **contrast-ratio** rule enforces accessibility standards by verifying that color pairs meet minimum contrast ratios. This prevents inaccessible color combinations from passing validation. You can find the logic in [`packages/cli/src/linter/linter/rules/contrast-ratio.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/contrast-ratio.ts).

## Warning-Level Validation Rules

Five rules operate at `warning` severity, flagging potential issues that may not break the build but indicate missing or incorrect configuration.

### missing-primary

The **missing-primary** rule warns when a color palette exists without a defined `primary` color. While the agent can auto-generate key colors, explicit definition is recommended. See [`packages/cli/src/linter/linter/rules/missing-primary.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/missing-primary.ts).

### orphaned-tokens

The **orphaned-tokens** rule identifies tokens defined in the system but never referenced elsewhere. These unused definitions clutter the design system and should be removed or utilized. Implementation is in [`packages/cli/src/linter/linter/rules/orphaned-tokens.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/orphaned-tokens.ts).

### missing-typography

The **missing-typography** rule ensures every required typography property—such as `fontFamily` and `lineHeight`—is present in the definition. Missing properties trigger warnings to prevent incomplete type systems. Check [`packages/cli/src/linter/linter/rules/missing-typography.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/missing-typography.ts).

### section-order

The **section-order** rule enforces the canonical ordering of sections according to the DESIGN.md specification. Sections appearing out of their expected sequence generate warnings. The validator lives in [`packages/cli/src/linter/linter/rules/section-order.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/section-order.ts).

### unknown-key

The **unknown-key** rule flags any top-level keys in the [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file that are not part of the official specification. This prevents typos and deprecated properties from persisting in your configuration. See [`packages/cli/src/linter/linter/rules/unknown-key.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/unknown-key.ts).

## Info-Level Validation Rules

Two rules provide informational feedback to help optimize and audit your design system.

### token-summary

The **token-summary** rule generates a summary of token usage across the file. This informational output helps surface missing or duplicated definitions without blocking the build. The implementation is in [`packages/cli/src/linter/linter/rules/token-summary.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/token-summary.ts).

### missing-sections

The **missing-sections** rule notes when optional sections—such as `spacing` or `rounded`—are absent from the design definition. While these sections are optional, their absence is reported as `info` since the agent will fall back to defaults. See [`packages/cli/src/linter/linter/rules/missing-sections.ts`](https://github.com/google-labs-code/design.md/blob/main/packages/cli/src/linter/linter/rules/missing-sections.ts).

## Running the Linter

You can execute these nine validation rules via the CLI or programmatically in TypeScript applications.

### Command Line Usage

Run the linter against any [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) file from the repository root:

```bash
bun run cli lint path/to/DESIGN.md

```

The command loads `DEFAULT_RULE_DESCRIPTORS` and outputs findings with severity prefixes:

```

ERROR   broken-ref          Reference $color.foo does not resolve to any defined token.
WARNING missing-primary    No 'primary' color defined. The agent will auto‑generate key colors.
INFO    missing-sections   No 'spacing' section defined. Layout spacing will fall back to agent defaults.

```

### Programmatic Integration

Import the `lintDesign` function to validate files within your own tooling:

```typescript
import { lintDesign } from '@design-md/cli';
import { readFileSync } from 'fs';

// Load a DESIGN.md file as a string
const designContent = readFileSync('examples/totality-festival/DESIGN.md', 'utf-8');

// Run the linter (returns an array of findings)
const findings = lintDesign(designContent);

// Filter for critical errors only
const errors = findings.filter(f => f.severity === 'error');
console.log(errors);

```

The `lintDesign` helper internally creates a `DesignSystemState` and executes the complete array of nine rules against your content.

## Summary

- The DESIGN.md linter applies **nine fixed rules** exported as `DEFAULT_RULE_DESCRIPTORS` from [`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).
- **broken-ref** and **contrast-ratio** default to `error` severity, catching unresolved references and accessibility violations.
- **missing-primary**, **orphaned-tokens**, **missing-typography**, **section-order**, and **unknown-key** emit `warning` level alerts for specification deviations.
- **token-summary** and **missing-sections** provide `info` level feedback to audit token usage and optional section coverage.
- Each rule has a dedicated implementation file in `packages/cli/src/linter/linter/rules/` named after the rule identifier.
- Use `bun run cli lint` for command-line validation or import `lintDesign` for programmatic checking.

## Frequently Asked Questions

### What triggers the broken-ref rule to fail?

The **broken-ref** rule fails when a token reference—such as `$color.foo` or a component sub-token—cannot be resolved to any defined token in the design system. This prevents runtime errors where undefined values would otherwise propagate through the system.

### How does the contrast-ratio rule validate accessibility?

The **contrast-ratio** rule checks color pairs against minimum contrast thresholds required for accessibility compliance. When two colors fail to meet the WCAG contrast ratio requirements, the linter reports an error, ensuring that text remains readable against its background colors.

### Can I run the linter programmatically outside the CLI?

Yes. The `lintDesign` function exported from `@design-md/cli` allows you to validate [`DESIGN.md`](https://github.com/google-labs-code/design.md/blob/main/DESIGN.md) content programmatically. The function accepts a string content, creates a `DesignSystemState` internally, and returns an array of findings that you can filter by severity or process in custom build pipelines.

### Why does the linter distinguish between warnings and errors?

The DESIGN.md linter uses **error** severity for critical issues—such as broken references and accessibility failures—that would prevent proper rendering or violate standards. **Warning** severity indicates specification deviations that might cause inconsistent behavior but won't break the system, while **info** severity provides optimization suggestions for optional sections and token usage audits.