Separate primitives from semantic tokens
Primitive tokens describe raw values, such as --blue-600 or --gray-100. Semantic tokens describe purpose, such as --color-action-primary or --color-text-muted. Components should usually consume semantic tokens so a theme can change without rewriting every selector.
Keep the mapping understandable. Too many abstraction layers make debugging difficult, while direct HEX values scattered through components make global changes risky.
Define tokens at the appropriate scope
Place global theme tokens on :root and override them for dark mode or branded themes. Use component-level variables only when a component genuinely needs configurable internal roles. Avoid redefining the same global name in many unrelated containers.
Document fallback behavior for browsers or embedded contexts when required. A missing variable can silently make a property invalid, so defaults may be useful for critical styles.
Name states consistently
Use predictable suffixes for hover, active, focus, disabled, subtle background, border, and foreground. Consistency helps developers discover existing tokens instead of inventing new shades.
Do not derive every state with opacity alone. Transparency changes according to the background beneath it and can create unexpected contrast. Explicit tested tokens are safer for important interactions.
Connect tokens to accessibility checks
Maintain a small table of approved foreground/background token pairs. When a base value changes, retest all semantic combinations that depend on it. This turns contrast review into a system task instead of a manual hunt through pages.
Include focus, borders, icons, and status components in the test set. Text pairings are only part of an accessible color system.
Prevent one-off color drift
Use linting, code review, or a simple search to flag raw color values outside the token file. Exceptions may be allowed for illustrations or third-party content, but they should be intentional.
Provide designers with the same token names used in code. Shared terminology reduces translation errors between design files, specifications, and implementation.
Practical checklist
- Keep raw values separate from role-based tokens
- Use semantic variables inside components
- Name interaction states predictably
- Retest approved token pairings after changes
- Flag unapproved raw color values
This guide is maintained by the Colorrow Editorial Team. Suggestions and corrections can be sent to contact.colorrow@gmail.com.