Agent skills
Agent Skill: Token Normalization
Token cleanup is safest after the UI already matches. The goal is to replace arbitrary values with design-system primitives without changing the result.
Adarsh Trivedi · August 20, 2025 · 3 min read
Takeaway: Visual accuracy comes first. Tokenization is a cleanup pass, not a redesign pass.
What it does
This skill reviews migrated UI code and colocated style files, then replaces arbitrary colors, spacing, typography, and sizing with the closest approved design tokens where safe.
It also checks whether a design-system primitive should replace custom markup. The goal is consistency with the token system, not clever refactoring.
Why it helps
During migration, raw values often appear because the first priority is visual parity. A separate token pass keeps that pragmatic implementation step from becoming permanent design debt.
Sanitized skill notes
This is the public version of the saved skill markdown. I replaced product, package, and repository names with generic placeholders.
name: token-normalization
purpose: Normalize migrated UI to design-system primitives and design tokens.
when to run:
After visual parity is achieved, not before.
priority order:
1. Preserve visual accuracy.
2. Prefer design-system primitives for common UI elements.
3. Prefer shared design tokens over raw values.
4. Keep custom values only when no safe token exists.
checks:
- replace raw colors with approved color tokens
- replace spacing, sizing, typography, and borders with tokens where safe
- consolidate matching typography into text styles
- use token references consistently
- avoid redesigning during cleanup
verification:
Re-check the UI after token changes so cleanup does not create visual drift.