UI Color Tokens Guide: Build Reliable Roles for Surfaces, Text, Borders, and States
UI designdesign systemscolor tokensproduct designdesign workflow

UI Color Tokens Guide: Build Reliable Roles for Surfaces, Text, Borders, and States

CChromatic Studio
2026-11-14
7 min read

Build a dependable UI color palette with semantic tokens for surfaces, content, actions, states, and light or dark themes.

A reliable UI color palette is more than a set of attractive swatches. This guide shows how to organize raw colors into semantic design tokens, map them across light and dark themes, and give designers and developers a shared checklist for surfaces, content, borders, actions, focus, and status states.

Overview

A token-based color system separates the color itself from the job it performs. A raw color might be a particular blue or neutral gray, but a semantic token explains how that color is used: color.action.primary, color.content.primary, or color.border.subtle. This distinction makes a product easier to maintain because a theme can change without requiring every component to be redesigned individually.

Start with three layers:

  1. Reference or raw tokens: the actual color values, such as blue.600, gray.100, or red.700.
  2. Semantic tokens: roles that describe purpose, such as surface.default or content.muted.
  3. Component tokens: narrowly scoped decisions, such as button.primary.background or input.error.border.

Keep these layers distinct. A semantic role should not be named after its current hue. color.action.primary can move from blue to green during a rebrand, while its purpose remains stable. Component tokens should be introduced when a component needs a deliberate exception, not as a substitute for a coherent semantic layer.

Use a naming pattern that is predictable across files and tools. For example:

color.{role}.{priority}.{state}

Examples:
color.surface.default
color.surface.raised
color.content.primary
color.content.muted
color.border.default
color.action.primary.default
color.action.primary.hover
color.action.primary.disabled
color.focus.ring
color.status.success
color.status.warning
color.status.error

Teams may prefer slash-separated paths, hyphenated names, or platform-specific formats. The important decision is consistency: choose one vocabulary, document it, and make the same names available in design files, code, and handoff documentation.

Checklist by scenario

For a new UI color palette

  • List the required roles before selecting individual swatches: surfaces, content, borders, actions, focus, and status.
  • Create a neutral scale for backgrounds, containers, text, dividers, and disabled elements.
  • Choose brand or accent colors separately from functional colors such as success, warning, and error.
  • Define interaction states for controls, including default, hover, pressed, focus, selected, disabled, and visited where relevant.
  • Check text and control combinations in their real context rather than judging swatches in isolation.
  • Record whether each token is intended for text, a background, an icon, a border, or a decorative element.

For a light theme

Map the light theme from the semantic roles outward. A typical starting structure might include:

Semantic roleTypical purposeLight-theme decision
SurfacePage, cards, overlays, inputsUse a clear hierarchy between the page background, raised surfaces, and interactive fields.
ContentHeadings, body text, metadata, iconsProvide distinct primary, secondary, muted, inverse, and disabled roles.
BorderDividers, fields, cards, focus-adjacent edgesSeparate subtle borders from stronger borders used for emphasis or errors.
ActionButtons, links, selected controlsDefine a clear primary action and quieter secondary or tertiary actions.
FocusKeyboard and input focus indicationUse a visible ring or boundary that remains distinguishable beside the component.
SuccessPositive completion or confirmationPair the color with text, an icon, or another cue; do not rely on hue alone.
WarningCaution, pending action, or riskReserve it for meaningful caution and give it a readable content color.
ErrorInvalid input or failed actionApply it consistently to the message, relevant field treatment, and supporting icon.

For a dark theme

Do not simply invert every light-theme value. Reassign the roles deliberately. Dark themes often need a layered set of dark surfaces rather than one black background, while bright text may require several levels of emphasis. Review borders carefully: a border that is barely visible in a light theme can disappear entirely on a dark surface, while a highly saturated accent can become visually overpowering.

  • Map page, raised, sunken, and overlay surfaces independently.
  • Choose primary and secondary content colors for comfortable reading at the intended sizes.
  • Recheck action colors against dark surfaces, including hover and pressed states.
  • Make focus indicators visible on both dark and colored controls.
  • Test status colors in banners, inline messages, charts, and icons rather than approving one example only.

For a component handoff

  1. Annotate each visible color with its semantic token, not only its hexadecimal value.
  2. Show every meaningful state and theme in the design file.
  3. Explain exceptions, such as a destructive button that uses a stronger error action than an inline error message.
  4. Supply token names in the format developers will use in source files or exported theme data.
  5. Link to the approved palette and accessibility checks so future edits can be compared with the same baseline.

What to double-check

Contrast in context: Test foreground and background pairs where they actually appear. Primary text, muted text, button labels, placeholder text, icons, focus indicators, and meaningful borders have different functional requirements. A color that works on the page surface may fail on a raised card or accent background. Use an accessible color palette checker as part of review, then inspect the result in the component itself.

State coverage: A token system is incomplete if it covers only the default state. Check hover, pressed, focus, selected, disabled, loading, success, warning, and error states where they apply. States should be distinguishable through more than color alone when the distinction affects task completion.

Theme parity: Every important semantic role should have a valid mapping in each supported theme. Do not leave a light-only token hidden inside a component stylesheet. If a role has no sensible dark equivalent, resolve that design decision explicitly and document the exception.

Token scope: Ask whether a name describes a reusable role or a one-off component detail. Overly broad tokens create accidental coupling; overly specific tokens make the system difficult to learn. A useful audit question is: “Would another component reasonably use this token?”

Design-to-code alignment: Compare token names, values, aliases, and state behavior between the design library and implementation. Look for hard-coded color values that bypass the token layer. Also check whether exported formats preserve references or flatten everything into raw values.

For broader palette work, the accessible color combinations library can provide starting points, while a poster color palette guide is more relevant to print-oriented projects than interface states. Keep those use cases separate: a visually effective poster palette is not automatically a reliable UI color system.

Common mistakes

  • Naming tokens by hue: Names such as blue-button become misleading after a rebrand or theme change. Name the role first.
  • Using one color for every purpose: Brand blue, link blue, selected blue, and focus blue may need different contrast and state behavior.
  • Treating dark mode as an inversion filter: Inversion rarely creates the right surface hierarchy or interaction contrast.
  • Relying on color as the only status signal: Add labels, icons, patterns, placement, or messages where users must interpret success, warning, or error.
  • Creating semantic names without a scale: Roles such as “light,” “medium,” and “dark” are less useful than a defined relationship such as primary, secondary, muted, or inverse.
  • Skipping disabled and focus states: These states are part of the component contract, not optional finishing details.
  • Adding aliases without documentation: If button.primary.background points to action.primary, record that relationship so updates remain understandable.
  • Approving tokens from isolated swatches: Review real layouts, content lengths, icons, overlays, and neighboring controls before release.

When to revisit

Review the token system before a major redesign, when adding a new product area, when introducing a light or dark theme, and whenever a new component exposes a role the existing vocabulary cannot describe. It is also worth checking at the start of a seasonal planning cycle if campaigns, illustrations, or promotional surfaces introduce new accent colors.

Repeat the audit after changes to design or developer tooling, because token export formats, variable support, and handoff workflows may change. A practical recurring review can be brief:

  1. Export the current token list from the design source and codebase.
  2. Search for hard-coded colors and names that describe hues rather than roles.
  3. Review a representative page, form, navigation pattern, dialog, and status message in every theme.
  4. Run contrast checks on text, controls, focus indicators, and meaningful borders.
  5. Remove unused tokens, document intentional exceptions, and update component examples.
  6. Share the revised naming and mapping notes in the handoff location used by the whole team.

Before assigning a new color, first ask whether an existing semantic role already fits. If it does, reuse the token. If it does not, define the new role with an example, theme mappings, state behavior, and an accessibility review. This small discipline keeps a UI color palette understandable as the product grows and gives designers and developers a dependable shared language.

Related Topics

#UI design#design systems#color tokens#product design#design workflow
C

Chromatic Studio

Design Resources Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.