SlipItIn/.github/skills/design-md-validator/references/linting-rules.md

Linting Rules — @google/design.md

Generated against npm 0.3.0 + main as of 2026-07-18. Authoritative source at runtime: npx @google/design.md spec --rules-only.

The linter runs nine rules against a parsed DESIGN.md in the published npm 0.3.0 release; a tenth rule (token-like-ignored) has merged on main and ships in the next release. Each rule produces findings at a fixed severity level.

Rules Table

Rule	Severity	What it checks
broken-ref	error	Token references ({colors.primary}) that don't resolve to any defined token
missing-primary	warning	Colors are defined but no primary color exists — agents will auto-generate one
contrast-ratio	warning	Component backgroundColor/textColor pairs below WCAG AA minimum (4.5:1)
orphaned-tokens	warning	Color tokens defined but never referenced by any component
token-summary	info	Summary of how many tokens are defined in each section
missing-sections	info	Optional sections (spacing, rounded) absent when other tokens exist
missing-typography	warning	Colors are defined but no typography tokens exist — agents will use default fonts
section-order	warning	Sections appear out of the canonical order defined by the spec
unknown-key	warning	A top-level YAML key looks like a typo of a known schema key (e.g. colours: → colors:)
token-like-ignored	warning	Next release (on main since 2026-06-15, not in npm 0.3.0). Warns when a top-level YAML key looks like a design-token map but is not part of the recognized export schema and will be silently ignored

Section Order (canonical)

Sections use ## headings. They can be omitted, but those present must appear in this order:

#	Section	Aliases
1	Overview	Brand & Style
2	Colors
3	Typography
4	Layout	Layout & Spacing
5	Elevation & Depth	Elevation
6	Shapes
7	Components
8	Do's and Don'ts

Consumer Behavior for Unknown Content

Scenario	Behavior
Unknown section heading	Preserve; do not error
Unknown color token name	Accept if value is valid
Unknown typography token name	Accept as valid typography
Unknown component property	Accept with warning
Duplicate section heading	Error; reject the file

Exit Codes

• 0 — No errors (warnings/info may be present)
• 1 — Errors found (file is invalid per spec)

Programmatic API

import { lint } from '@google/design.md/linter';

const report = lint(markdownString);
console.log(report.findings);       // Finding[]
console.log(report.summary);        // { errors, warnings, infos }
console.log(report.designSystem);   // Parsed DesignSystemState