Reading token-summary in DESIGN.md

What the rule reports#

token-summary is a structural inventory. The linter counts entries in each of the five token maps and composes a plain-English sentence listing only the sections that have at least one entry. Empty sections are omitted from the message.

The message template (from source):

Design system defines {n} color[s], {n} typography scale[s], {n} rounding level[s], {n} spacing token[s], {n} component[s].

Each term is pluralized independently: 1 color (no plural s), 2 colors (with s). Only terms for non-empty sections appear. A file with three colors and two typography scales but no rounding, spacing, or components produces:

{
  "severity": "info",
  "message": "Design system defines 3 colors, 2 typography scales."
}

A fully populated file produces all five terms:

{
  "severity": "info",
  "message": "Design system defines 4 colors, 3 typography scales, 2 rounding levels, 2 spacing tokens, 1 component."
}

If every token map is empty (no tokens at all), the rule emits no finding.

What triggers it#

Any DESIGN.md with at least one defined token triggers token-summary. There is no condition to satisfy beyond having a non-empty token map.

Example DESIGN.md:

---
name: Slate Design
colors:
  primary: "#0F172A"
  surface: "#F8FAFC"
  error: "#DC2626"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
---

## Overview

A dark-primary system with a light surface and neutral body type.

This file defines three colors and one typography scale. The linter emits:

{
  "severity": "info",
  "message": "Design system defines 3 colors, 1 typography scale."
}

How to read it, and when to act#

token-summary is not a defect report. The finding is always info, the CLI exit code is unaffected, and no fix is required. Its value is as a quick baseline check:

Low counts as signals

Tracking growth across commits

Because the token-summary message is deterministic and stable, it is easy to diff in CI. A pipeline that captures the JSON output of lint can compare the message field between the before and after files to detect token additions and removals without parsing the full diff output.

Cross-checking with diff

For a more detailed view of what changed between two versions of a DESIGN.md file, use:

npx @google/design.md diff before.md after.md --format json

The diff output breaks down additions, removals, and modifications per section. token-summary gives you totals; diff gives you the delta.

Suppressing the finding in CI#

If your CI pipeline treats any info finding as noise, filter the findings array by severity before evaluating:

npx @google/design.md lint DESIGN.md --format json \
  | jq '[.findings[] | select(.severity != "info")]'

The summary.infos count in the lint output captures how many info-level findings were emitted (at least one, from token-summary, whenever tokens exist).

Related rules#

• missing-sections: info when colors are present but spacing or rounded is absent.
• orphaned-tokens: warning when a color token is defined but no component references it.
• CLI and Lint Rules Reference: full rules table and severity summary.

Try it in the tool