What Is the Token Summary Info Finding and How Is It Generated?

The token-summary info finding is an informational diagnostic that reports the count of design tokens in each category—colors, typography, rounded corners, spacing, and components—defined in a DESIGN.md file.

The token-summary info finding helps you quickly audit the scope of your design system without manually counting definitions. This informational diagnostic is emitted by the Design.md linter to give you immediate visibility into token distribution across your design specification. Understanding how this summary is generated helps you interpret linter output and integrate the rule into custom tooling workflows.

How the Token Summary Rule Works

The finding is produced by the tokenSummary rule implemented in packages/cli/src/linter/linter/rules/token-summary.ts. When the linter executes, it constructs a DesignSystemState object that holds parsed token collections.

The DesignSystemState Collection

The rule accesses five specific collections from the state object:

• state.colors – Contains color token definitions
• state.typography – Holds typography scale definitions
• state.rounded – Stores rounded corner tokens
• state.spacing – Contains spacing token definitions
• state.components – Holds component token definitions

Each collection is a Map-like structure where the size property indicates how many tokens are defined in that group.

Generating the Human-Readable Summary

The rule iterates over these collections and constructs a sentence fragment for every non-empty group. It joins these fragments with commas to create a single message string. If all collections are empty, the rule returns an empty array and no finding is emitted.

The resulting RuleFinding contains a message field formatted as:

Design system defines 12 colors, 5 typography scales, 3 rounding levels, 8 spacing tokens, 4 components.

Viewing the Token Summary via CLI

You can see the token-summary info finding by running the linter against any DESIGN.md file:

npx @google/design.md lint DESIGN.md

The output includes an INFO level message showing your token distribution:

INFO  token-summary  Design system defines 14 colors, 4 typography scales, 2 rounding levels, 10 spacing tokens, 6 components.

Programmatic Usage of the Token Summary Rule

You can invoke the rule directly in TypeScript to access token counts without running the full CLI:

import { parseDesignSystem } from '@google/design.md/parser';
import { tokenSummaryRule } from '@google/design.md/packages/cli/src/linter/linter/rules/token-summary.js';

// Load and parse a DESIGN.md file
const spec = await parseDesignSystem('examples/totality-festival/DESIGN.md');

// Run the token-summary rule directly
const findings = tokenSummaryRule.run(spec);
console.log(findings[0].message);
// → "Design system defines 12 colors, 5 typography scales, 3 rounding levels, 8 spacing tokens, 4 components."

Customizing the Token Summary Output

If you need to modify the output format or add support for additional token groups, edit the tokenSummary function in packages/cli/src/linter/linter/rules/token-summary.ts. Adjust the parts construction logic to change how fragments are built and joined.

The rule is registered in the linter's rule registry via packages/cli/src/linter/linter/rules/index.ts, making it available to the runner defined in packages/cli/src/linter/linter/runner.test.ts.

Summary

• The token-summary info finding reports design token counts across five categories: colors, typography, rounded corners, spacing, and components.
• The rule reads the size property of Map-like collections stored in DesignSystemState.
• It generates a human-readable sentence by joining non-empty group counts with commas.
• You can view the finding via CLI or import tokenSummaryRule programmatically from packages/cli/src/linter/linter/rules/token-summary.ts.

Frequently Asked Questions

What triggers the token-summary info finding?

The finding triggers when your DESIGN.md file contains at least one design token in any of the five supported categories. The rule checks state.colors, state.typography, state.rounded, state.spacing, and state.components for non-empty collections and generates a summary sentence showing the count in each category.

Why does the linter sometimes show no token-summary output?

If your DESIGN.md file defines no tokens in any category, the tokenSummary rule returns an empty array instead of a RuleFinding. According to the implementation in token-summary.ts, this silent behavior prevents cluttering the output when no design tokens are present.

Can I filter specific token categories from the summary?

The current implementation in packages/cli/src/linter/linter/rules/token-summary.ts does not support filtering specific categories. The rule always checks all five collections (colors, typography, rounded, spacing, components) and includes any non-empty groups in the final message. To hide specific categories, you would need to modify the rule's parts construction logic.

How do I test the token-summary rule locally?

You can exercise the rule using the test suite in packages/cli/src/linter/linter/runner.test.ts. Import the tokenSummaryRule from the rules index, create a mock DesignSystemState with populated token collections, and call tokenSummaryRule.run(state) to verify the output message format matches your expectations.

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