Primary references
These sources support the standards and technical explanations in this guide. Color Pick recommendations and product-specific limitations are identified separately in the article.
Web and UI
How to Build Semantic UI Color Roles
Map raw palette values to stable background, surface, text, action, feedback, focus, and interaction roles for light and dark interfaces.
Direct answer
Build semantic UI colors by separating raw values from product roles. Keep a base scale such as blue-500 or slate-900, then map those values to tokens such as background, surface, text, primary action, on-primary, border, focus, success, warning, and error. Create separate light and dark role maps while preserving the same semantic names.
At a glance
Use role names instead of visual names
A semantic token remains meaningful when the underlying color changes.
Names such as blue-600 or cool-gray-50 describe appearance or position in a scale. Names such as action-primary, text-muted, surface-elevated, and status-error describe purpose.
Keep both layers. Raw scales make systematic adjustment possible; semantic aliases let components consume stable product meaning.
Start with a compact core role set
A small complete role map is more useful than a large unlabeled palette.
| Role | Purpose | Typical requirement |
|---|---|---|
| background | Page canvas | Supports all content layers |
| surface | Cards and panels | Distinct from background |
| text-primary | Main reading text | Strong readable contrast |
| text-muted | Secondary information | Readable without competing |
| action-primary | Main interactive action | Clear label and states |
| on-primary | Content on primary action | Test against action fill |
| border | Inputs and separation | Meaningful boundaries remain perceivable |
| focus | Keyboard focus indicator | Visible against adjacent colors |
| success / warning / error | Feedback states | Use non-color cues too |
Define interaction states explicitly
A single primary color cannot represent default, hover, active, selected, focus, and disabled behavior by itself.
- action-primary
- action-primary-hover
- action-primary-active
- action-primary-selected
- focus-ring
- disabled-surface
- disabled-content
Keep role names stable across light and dark themes
Components should ask for a role, not a theme-specific color.
In light mode, background may use a near-white value while surface uses white. In dark mode, both become layered dark values. The component still requests background and surface.
Accent values often need separate dark-theme variants because identical RGB values can feel more intense on dark surfaces and may produce different readability results.
Worked example: product interface roles
The example maps six values into a small but usable interface system.
| Token | Light value | Dark value |
|---|---|---|
| --color-background | #F8FAFC | #0F172A |
| --color-surface | #FFFFFF | #111827 |
| --color-text | #0F172A | #F8FAFC |
| --color-action | #2563EB | #60A5FA |
| --color-success | #16A34A | #4ADE80 |
| --color-error | #DC2626 | #F87171 |
Step-by-step semantic token workflow
Map, test, and export roles before wiring them into components.
- 1
Create or import the raw palette.
- 2
Generate a light and dark base scale where needed.
- 3
Assign background, surface, text, action, focus, and feedback roles.
- 4
Preview buttons, fields, navigation, cards, and alerts.
- 5
Check contrast and color-vision resilience.
- 6
Export CSS or design tokens and keep role names stable.
How this example was tested
The role map was reviewed in actual component relationships rather than by inspecting token values alone.
- Body and muted text on background and surface
- Action label on default, hover, and active fills
- Input boundary and focus ring
- Status messages with icon and text cues
- Light and dark surface layering
- Grayscale and color-vision simulations
Common semantic color mistakes
Weak systems usually mix raw colors and roles without a clear contract.
- Naming a semantic token --blue-500
- Using one accent for action, link, focus, and status
- Leaving on-primary foreground implicit
- Changing token names between light and dark mode
- Skipping disabled, selected, and focus states
- Exporting before role coverage is complete
Key takeaways
Semantic tokens connect visual values to stable product meaning.
- Keep raw scales and role aliases separate.
- Start with a small complete role set.
- Define interaction states explicitly.
- Reuse role names across themes.
- Test roles in real components before export.
Put the guide into practice
Open Role MapperMap roles in the Color Playground
Assign semantic roles, preview interfaces, test readiness, and export reusable tokens.
Frequently asked questions
Should semantic tokens contain color names?
Prefer purpose-based names for component-facing tokens. Raw palette tokens may retain color-family or numeric names, but components should consume role names.
Do light and dark mode need different token names?
No. Keep semantic names stable and switch the mapped values by theme.
How many semantic roles should I start with?
Start with background, surface, primary and muted text, primary action and foreground, border, focus, success, warning, error, and disabled roles. Add more only when a real component requires them.