Use this workflow when you have a live website or stylesheet and need an auditable token inventory before documenting or consolidating the design system.
What this workflow examines
Colors and gradients
Hex, RGB, HSL, named colors, custom properties, borders, fills, text usage, and gradient stops.
Typography
Font families, sizes, weights, line heights, letter spacing, text transforms, and recurring type combinations.
Geometry and spacing
Margins, padding, gaps, widths, heights, radii, container constraints, and breakpoint patterns.
Elevation and motion
Box shadows, filters, transitions, easing curves, durations, keyframes, and reduced-motion overrides.
A review-first extraction workflow
Collect relevant authored CSS
Prefer the styles used by the representative page. Avoid treating every value in a large vendor or utility bundle as part of the intentional system.
Normalize equivalent values
Resolve case, shorthand, alpha, units, and custom-property aliases so visually equivalent values are not counted as separate tokens.
Measure frequency and context
A value used often matters, but selector context explains whether it belongs to text, borders, actions, surfaces, layout, or one decorative effect.
Consolidate into semantic roles
Choose a small set of role-based tokens and preserve aliases only when they communicate a real product distinction.
Validate against rendered pages
Check whether proposed tokens reproduce representative components and whether removing an apparent duplicate changes visible behavior.
Example: consolidate aliases without losing meaning
Before: raw evidence
:root {
--indigo-600: #4f46e5;
--brand: rgb(79 70 229);
--button-bg: var(--brand);
}
.button-primary { background: #4F46E5; }After: useful context
design.tokens
color.action.primary: #4F46E5
Usage rule
Use color.action.primary for the main CTA, active controls, and keyboard-focus emphasis. Keep implementation aliases only where existing code requires them.What the output should contain
- Semantic tokens: named color, typography, spacing, radius, elevation, layout, and motion roles.
- Component recipes: anatomy, variants, states, content constraints, and when to reuse each pattern.
- Responsive guidance: container behavior, breakpoints, stacking, overflow, density, and mobile priorities.
- Guardrails: visual choices the implementation must not invent or apply outside approved contexts.
- Validation evidence: a representative preview and a record of assumptions, unknowns, and intentional exceptions.
Important limitations
- Unused framework utilities can dominate frequency counts.
- Dynamic styles and runtime themes may not appear in static CSS.
- The same raw value can serve different semantic roles.
- Token consolidation must be checked against rendered components.
Responsible use: analyze only material you own, control, or are permitted to study. Extract reusable design principles; do not copy protected content, private code, trademarks, or distinctive assets without permission.
Frequently asked questions
What is a CSS design token?
A design token is a named design decision—such as an action color, spacing step, radius, or motion duration—that can be reused across components and platforms.
Should every CSS custom property become a token?
No. Some variables are implementation details, temporary calculations, or component-local values. Promote values that represent reusable design decisions.
How do you handle duplicate color formats?
Normalize equivalent formats and aliases before counting them, then use selector context to determine whether one value serves one role or several distinct roles.
Why is a rendered-page check necessary?
Static CSS can include dead code, hidden themes, utilities, and vendor styles. Rendering shows which extracted decisions actually shape the interface.