How to Design Semantic Color Tokens Without Letting Blue 500 Define Buttons, Text, and Errors

Semantic Color Tokens translate "what color is this?" into "what role does this color serve in the interface?" Once buttons, text, and states stop referencing Blue 500 directly, theme switching, brand updates, and accessibility improvements can scale.

Many teams already use color variables, yet their Figma files still show Button background = Blue/600, Error text = Red/500, and a duplicated Blue-dark palette for Dark Mode. These variables enable bulk replacement but do not create a stable semantic layer. A real Color Token system makes components depend on roles, not palette numbers.

01 1. Understand Four Layers: Value, Primitive, Semantic, and Component

Carbon's current color documentation defines a token as a role-based identifier, with the Theme determining the final color value for each role. The same text-secondary can map to different gray levels across themes. This model is more maintainable than sending palette numbers directly into components.

• Value: the final renderable value, such as #0F62FE.
• Primitive: a brand or foundation palette entry, such as blue-60 or gray-100.
• Semantic: an interface role, such as text-primary, border-subtle, or support-error.
• Component: semantics specific to one component, such as button-primary-background-hover.

02 2. Why Are Semantic Names More Stable Than Color Names?

Suppose primary text is Gray 100 today but becomes Gray 10 in Dark Mode. A component hardcoded to gray-100 requires a theme-specific override in every use. With text-primary, the Theme changes one mapping. If the brand moves from blue to purple, interactive-primary remains the primary action; its meaning does not change.

03 3. Describe Roles Without Embedding Implementation Details

Useful naming dimensions usually include object + intensity or role + state, as in text-primary, text-secondary, border-strong, background-hover, and support-error. Carbon's current core color tokens are likewise grouped by roles such as Background, Layer, Field, Border, Text, Link, Icon, Support, and Focus.

Avoid names such as blue-button or dark-gray-text. As soon as the theme or brand changes, those names become false.

04 4. Status Colors Are More Than Red, Yellow, and Green

Error, Warning, Success, and Info are meanings, not hues. Status tokens should define coordinated levels for text, icons, borders, and backgrounds, and meaning must not depend on color alone. An error state should include an error message or icon rather than only turning an input border red.

05 5. Dark Mode Should Not Duplicate the Entire Component Set

In the ideal theme model, components always reference the same semantic tokens while the Theme switches their values. Carbon v11 exposes color tokens through CSS Custom Properties, making local themes and Light/Dark switching easier. The design side should preserve the same structure instead of duplicating an entire "Button Dark" component set.

06 6. Nested Surfaces Need Contextual Tokens

Complex products often have Page → Card → Nested panel → Input background layers. With only background-default and background-subtle, the team soon asks to "add one more gray here." Create Layer or Surface levels so components can reference roles relative to their context. Carbon's layering tokens are designed for exactly this kind of nesting.

07 7. When Do You Need Component Tokens?

If every button can be expressed with interactive-primary and text-on-primary, do not create dozens of button tokens in advance. Add a component-level token when a component has a special state, may need independent theming, or cannot express a stable meaning through shared tokens. Component tokens are the last layer, not a shortcut around semantic modeling.

08 8. Check Accessibility at Both Token and Component Levels

Even if each primitive looks strong in isolation, a combination such as text-secondary on layer-02 may still fail contrast. Token documentation should define allowed pairings, and component tests should validate actual combinations. Focus, error borders, graphics, and other non-text elements also need to account for WCAG 2.2 Non-text Contrast.

09 9. Token Migration Is Not a Global Find-and-Replace

When migrating from Blue/600 to semantic tokens, first analyze the role it serves in each context. The same Blue/600 may currently represent links, buttons, chart data, and selected states. These need different semantic tokens rather than a bulk replacement with interactive-primary. Migration is itself a semantic audit.

10 10. Establish a Maintainable Color Workflow

• Retain the brand Primitive palette, but prevent business components from referencing it arbitrarily.
• Create core Semantic Tokens and document their roles and permitted scenarios.
• Provide value mappings for Light, Dark, and brand themes.
• Add Component Tokens only when necessary.
• Synchronize tokens with design tools and code, and validate theme switching automatically.
• Before adding any color, ask whether it represents a new meaning or an existing meaning that was modeled incorrectly.

The color system becomes maintainable product infrastructure when teams ask "Is text-secondary the right role here?" instead of "Can we make this gray a little lighter?"

Frequently Asked Questions

What is the difference between a Primitive Color and a Semantic Token?

A Primitive represents a foundation value or palette step. A Semantic Token represents its purpose in the interface. Components should generally reference the semantic layer.

Should developers be completely prohibited from using Hex values?

Production components are best managed through tokens. Specialized data visualization and brand content can have explicit exceptions, but arbitrary hardcoding in business code should be avoided.

Does Dark Mode need a separate set of token names?

Usually not. Mapping the same semantic tokens to different values in each Theme is easier to maintain.

Are more Component Tokens always better?

No. Too many component tokens erode shared semantics. Add one only when shared tokens cannot express a stable requirement.

Can status colors rely only on red, yellow, and green?

That is not recommended. Color must not be the sole information channel. Express states through text, icons, shapes, or other cues as well, and meet contrast requirements.