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]

⚠️ No Changeset found

Latest commit: f68c4a5

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[GarthDB]

Run report for f68c4a5b

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

	Action	Time	Status	Info
🟩	SyncWorkspace	7ms	Passed

Touched files

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.