The Nine Validation Rules for the DESIGN.md Linter Explained

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 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, forming the complete default rule set applied to every 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.

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.

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.

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.

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.

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.

unknown-key

The unknown-key rule flags any top-level keys in the 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.

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.

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.

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 file from the repository root:

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:

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

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