Design token metrics

[GarthDB]

Description

This PR introduces a new CLI tool located at tools/token-metrics to extract and report quantitative metrics from @adobe/spectrum-tokens. The tool provides a comprehensive baseline analysis of the design token system, covering inventory, scope, architecture, data quality, and component coverage. It generates both a human-readable summary (printed to stdout) and a machine-readable JSON report (token-metrics-report.json).

Related Issue

This addresses the Spectrum OKR: "Token metrics are defined and included into our metrics system & have a baseline to compare moving forward." Specifically, it provides a concrete answer to Alison's question: "what does this mean specifically, and when should this be done by?"

Motivation and Context

The primary motivation is to establish a clear, quantifiable understanding of the current state of Spectrum's design token system. This baseline is crucial for:

• Tracking the health, maturity, and growth of tokens over time.
• Identifying areas for improvement (e.g., deprecation migration path coverage).
• Enabling data-informed decisions for future token development and governance.
• Providing transparency and accountability for the "Token metrics" OKR.

How Has This Been Tested?

• Unit Tests: Comprehensive unit tests (tools/token-metrics/test/index.test.js) cover all core utility functions and metric computations.
• Integration Test: An integration test runs computeMetrics against the actual packages/tokens/src directory to ensure real-world data processing.
• Manual Execution: The CLI tool was executed locally to generate the token-metrics-report.json and verify the summary output.

Screenshots (if appropriate):

N/A (CLI tool, output is text/JSON). The generated token-metrics-report.json serves as an example output.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• I have signed the Adobe Open Source CLA.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[changeset-bot]

🦋 Changeset detected

Latest commit: bd9ba63

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@adobe/spectrum-tokens-metrics	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[GarthDB]

Run report for bd9ba63b

Total time: 7.2ms | Comparison time: 0s | Estimated loss: 7.2ms (100.0% slower)

	Action	Time	Status	Info
🟩	SyncWorkspace	7.1ms	Passed

Touched files

.changeset/token-metrics-tool.md
pnpm-lock.yaml
tools/token-metrics/README.md
tools/token-metrics/ava.config.js
tools/token-metrics/moon.yml
tools/token-metrics/package.json
tools/token-metrics/src/cli.js
tools/token-metrics/src/index.js
tools/token-metrics/test/index.test.js
tools/token-metrics/token-metrics-report.json

[GarthDB]

Maintainer triage (Mar 2026)

main has advanced (design-data-spec, Rust SDK CLI, token validation). CI was previously green but this branch is stale.

Suggested next steps

• Rebase onto latest main and push to get a fresh CI run / mergeability check.
• Resolve conflicts, then ping for review when ready.

[GarthDB]

Refreshed this PR against current main and marked it ready for review.

Verification + fixes applied:

• Merged latest main (clean) and re-ran the tool against the current token corpus.
• Fixed a stale data path: component schemas moved under the component-format spec, so DEFAULT_COMPONENT_SCHEMAS now points at packages/design-data-spec/components. Schema coverage was silently reporting 0% before this fix; it now correctly resolves 54/54 (100%).
• Recalibrated the real-data integration thresholds — the active-token / deprecation-rate assertions were stale because deprecation rose to 32.2% after the token corpus migration. Added a regression test that fails if the component-schema path goes stale again.
• Refreshed the README baseline and regenerated token-metrics-report.json.
• Added a changeset for the new @adobe/spectrum-tokens-metrics tool (passes changeset-linter --fail-on-warnings).

Current baseline: 2,460 total tokens / 1,667 active / 793 deprecated (32.2%, 70% with migration path) / 100% UUID coverage / 96 components with tokens / 54 components with schema. All 22 tests pass.