Design Principle
A design system's theming power comes from a few predictable semantic controls: accent color, gray scale, panel background, scaling, radius, and component variants.
Large Theory
Tokens are not just hex values converted to variables. Maintainable tokens state whether they belong to brand, theme, component, state, or local context, and they work across light and dark modes.
Small Points
- Define global theme tokens first, then component semantic tokens, and only then local exceptions.
- Colors separate text, muted, border, surface, accent, danger, success, and focus.
- Radius, scaling, and density change product personality, not just color.
- Variants should express hierarchy and use, not expose a prop for every visual detail.
Design Judgment
If changing one accent token reliably affects buttons, links, focus, and selection, scope is healthy. If every component needs manual hex edits, the token contract failed.
Implementation Notes
Components consume only semantic tokens or variants. New tokens should document purpose, default value, dark value, accessibility constraints, and affected components.
Counterexamples/Risks
Hardcoded hex values, direct inversion from light to dark, state colors communicated only through color, and brand colors without contrast checks.
Case Study
Radix Themes exposes theme controls such as accentColor, grayColor, panelBackground, scaling, radius, and component variants. The useful pattern is a small semantic theme control surface, with variants creating hierarchy inside components.
Source Links
Radix Themes: https://www.radix-ui.com/themes/docs/theme/overview
Agent Directive
When adding a style system, produce a token table and component mapping; do not hardcode reference colors into individual components.