What Are the DESIGN.md Linting Rules and Their Severity Levels?

The DESIGN.md linter enforces 11 validation rules across three severity levels—error, warning, and info—with each rule implemented as a TypeScript module in packages/cli/src/linter/linter/rules/.

The google-labs-code/design.md repository provides a specification and CLI tool for documenting design systems. A core component of this CLI is the built-in linter, which validates DESIGN.md files against a canonical schema. According to the source code, the linter aggregates rules defined in individual files and assigns each a default severity that determines whether an issue blocks validation or merely alerts the developer.

Where the Linting Rules Are Defined

All linting logic resides in the packages/cli/src/linter/linter/rules/ directory. The entry point, packages/cli/src/linter/linter/rules/index.ts, exports a DEFAULT_RULES array that registers every rule by importing the rule modules. You can view the complete list of rule files with:

ls packages/cli/src/linter/linter/rules/

Each .ts file (e.g., unknown-key.ts, contrast-ratio.ts) exports a descriptor object containing the rule’s identifier, default severity, and validation logic.

Error-Level Linting Rules

Rules marked as error are blocking issues that must be resolved for the DESIGN.md file to be considered valid. Five rules ship with this severity by default:

• broken-ref – Detects token references (such as {colors.primary-60}) that point to non-existent definitions. Severity: error. Source: packages/cli/src/linter/linter/rules/broken-ref.ts.

• missing-primary – Ensures that a primary color token is explicitly defined in the specification. Severity: error. Source: packages/cli/src/linter/linter/rules/missing-primary.ts.

• missing-sections – Validates that all required top-level sections (for example, Overview and Colors) are present in the document. Severity: error. Source: packages/cli/src/linter/linter/rules/missing-sections.ts.

• missing-typography – Requires every typography token referenced in component definitions to be defined within the file. Severity: error. Source: packages/cli/src/linter/linter/rules/missing-typography.ts.

• unknown-key – Flags keys that are not recognized by the DESIGN.md specification. Severity: error. Source: packages/cli/src/linter/linter/rules/unknown-key.ts.

Warning-Level Linting Rules

Rules marked as warning highlight best-practice violations or potential mistakes that do not prevent the file from validating. Five rules default to this level:

• contrast-ratio – Flags color pairs whose contrast ratio falls below WCAG accessibility thresholds. Severity: warning. Source: packages/cli/src/linter/linter/rules/contrast-ratio.ts.

• levenshtein – Suggests corrections for misspelled keys by calculating Levenshtein distance against known valid keys. Severity: warning. Source: packages/cli/src/linter/linter/rules/levenshtein.ts.

• orphaned-tokens – Identifies token definitions that are never referenced elsewhere in the document. Severity: warning. Source: packages/cli/src/linter/linter/rules/orphaned-tokens.ts.

• section-order – Enforces the canonical ordering of top-level sections as defined by the specification. Severity: warning. Source: packages/cli/src/linter/linter/rules/section-order.ts.

• token-like-ignored – Detects values that look like tokens but are ignored by the parser (e.g., deprecated syntax). Severity: warning. Source: packages/cli/src/linter/linter/rules/token-like-ignored.ts.

Info-Level Linting Rules

The linter also provides non-blocking informational feedback:

• token-summary – Generates a summary report of all tokens used within the file. Severity: info. Source: packages/cli/src/linter/linter/rules/token-summary.ts.

Customizing Rule Severity

While the defaults above are hard-coded in the rule descriptors found in packages/cli/src/linter/linter/rules/, the CLI exposes a --rules command-line option that allows developers to override severities at runtime. This accepts a mapping of rule identifiers to desired severity levels, enabling you to downgrade unknown-key to a warning or elevate contrast-ratio to an error to match your team's requirements.

Summary

• The linter contains 11 built-in rules located in packages/cli/src/linter/linter/rules/.
• Severities are partitioned into three buckets: error (5 rules), warning (5 rules), and info (1 rule).
• Error-level rules (broken-ref, missing-primary, missing-sections, missing-typography, unknown-key) block validation until fixed.
• Warning-level rules address accessibility, ordering, spelling, and unused tokens without blocking builds.
• The token-summary rule provides informational feedback only.
• All defaults can be overridden via the CLI’s --rules option.

Frequently Asked Questions

What are the DESIGN.md linting rules?

The DESIGN.md linting rules are a set of 11 validation checks defined in the google-labs-code/design.md CLI. They verify specification compliance, token integrity, section ordering, and accessibility criteria, each implemented as a TypeScript module in packages/cli/src/linter/linter/rules/.

How do I change the severity of a specific rule?

You can override the default severity using the --rules command-line option when invoking the linter. This accepts a mapping of rule identifiers to desired severity levels (e.g., error, warning, info), allowing you to tailor the validation strictness to your project needs.

Which rules are considered blocking errors?

Five rules default to the error severity and will block validation until resolved: broken-ref, missing-primary, missing-sections, missing-typography, and unknown-key. These enforce core specification requirements such as valid token references and mandatory sections.

Where can I find the source code for the token-summary rule?

The token-summary rule is implemented in packages/cli/src/linter/linter/rules/token-summary.ts. This file exports the rule descriptor that assigns the info severity and defines the logic for aggregating token usage statistics.

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