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

> Understand DESIGN.md linting rules and their severity levels error warning and info coded in TypeScript. Ensure code quality for your projects.

- Repository: [Google Labs Code/design.md](https://github.com/google-labs-code/design.md)
- Tags: api-reference
- Published: 2026-07-01

---

**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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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:

```bash
ls packages/cli/src/linter/linter/rules/

```

Each `.ts` file (e.g., [`unknown-key.ts`](https://github.com/google-labs-code/design.md/blob/main/unknown-key.ts), [`contrast-ratio.ts`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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`](https://github.com/google-labs-code/design.md/blob/main/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.