Semantic Color Token
语义色
Aliases:语义色语义色 token角色色主题色变量换肤semantic colorcolor token
What is it
Colour variables named by purpose, not hue: bg, surface, text, muted, accent, danger. Components consume roles only, so a theme switch re-points the mapping layer instead of touching components. Light, dark, high-contrast and brand skins are simply different value tables over the same roles.
Interactive playground
Try it. Make an informed choice.Loading lab…
✓ When to use
- Light and dark themes, or skinnable branding, are required
- A component library ships across products and colour meaning must stay stable
- Accessibility demands a high-contrast or forced-colours theme
✕ When not to use
- A one-page campaign where the colour is the final visual
- More role names than actual colours — --color-card-header-icon-hover
- Illustration-only colours forced into the semantic layer
Variants
Light / dark dual
浅深双主题
Two value tables per role, swapped under .dark
High contrast
高对比
Tightened lightness gaps, heavier borders and text
Brand override
品牌覆盖
Swap accent and a few roles; leave the rest alone
Implementation
:rootcolor-scheme--color-bg--color-surfaceTwo layers: the ramp (--color-primary-500) and the role layer (--color-accent: var(--color-primary-600)). Components may only reference roles. The dark theme overrides role values and sets color-scheme: dark so scrollbars and form controls follow. High contrast gets its own table — do not pile conditionals onto the dark one. Add forced-colors handling where the OS palette applies.
Platform API
:rootcolor-schemeCSS custom propertiesIn code
The exact names this thing goes by in each ecosystem — use the row that matches your project.
| Framework | Name |
|---|---|
| CSS | color-scheme Lets UA controls follow the theme |
| CSS | :root |
| Tailwind CSS | @theme / dark: |
Related concepts
Start from one base hue and generate an ordered ramp (50–900), then assign primary, secondary, accent and neutral roles. Steps advance by lightness rather than ad-hoc picks, so hover, disabled and border always have the right depth on hand. Name roles before hex values and themes stay swappable.
FoundationUsed withThe luminance ratio between foreground and background — the measure of whether text can be read. WCAG 2.1 sets hard floors: 4.5:1 for AA body, 7:1 for AAA, dropping to 3:1 and 4.5:1 for large text. APCA refines this by weight and size against perception. Compute the ratio before picking colours; never sign off by eye.
FoundationUsed withShadow depth expresses how far an element sits from the page: 0 rests flat, 1–2 lift, 3 and above become overlays. Each shadow stacks umbra, penumbra and ambient layers — higher levels mean larger, softer casts. Use elevation to describe stacking relations, never as ornament.
FoundationUsed with