CSS Design Token Mining
Detect hardcoded CSS values that should become design tokens or CSS custom properties. A detection-only (code-mining) codemod that produces a structured report of findings.
Problem
Hardcoded CSS values scattered across a codebase lead to:
- Design drift — Near-duplicate values (e.g. 15px, 16px, 17px) that should be one token
- Theme blocking — Hardcoded colors prevent dark mode, branding, and white-labeling
- Maintenance cost — Repeated literals instead of semantic tokens
- Token misses — Literals that match existing tokens but were not migrated
Solution
A two-phase pipeline orchestrated by the workflow:
- Collect — codemod.ts parses CSS and Less files, extracts declarations, normalizes values, and appends raw records to node_modules/.cache/design-token-mining/raw.jsonl (gitignored)
- Analyze — analyze-codemod.ts runs on the trigger file, reads raw.jsonl, clusters values, matches against token inventory, and writes design-token-report.json with findings and recommendations
Usage
Run locally via CLI:
bash
Create dashboard in Codemod Insights
Go to app.codemod.com/insights, create a dashboard and a widget, set the source to js-ast-grep, and pick this package from the registry dropdown.
Metrics
- design-token-declarations-collected — Count of (property, literal) pairs that appear 2+ times per file. Cardinalities: family, file, property, literal, property-literal (combined property|literal for single-dimension grouping). Single-occurrence pairs are omitted to reduce cardinality for Codemod Insights.
Finding Types (v1)
- repeated-literal — Exact repeated literals in color, spacing, radius, typography, z-index
- existing-token-miss — Literals that match an existing custom property value
- near-duplicate-cluster — Clusters of close values (e.g. 15px, 16px, 17px) suggesting drift
- theme-sensitive-color — Hardcoded colors in theme-sensitive properties
- token-alias-duplication — Multiple custom properties with the same value
Report Format
json
What Gets Detected
Automated
- Repeated literals in token-heavy families
- Literals matching existing --* custom properties
- Near-duplicate spacing/radius/font-size clusters
- Hardcoded theme-sensitive colors
- Duplicated custom-property values (same value, different names)
Excluded (v1)
- var() and calc() values
- Gradients, complex shadows
- Generated/minified CSS
License
Fair Source License