Color Token Best Practices

Color token best practices establish the foundation for consistent, accessible, and themeable color usage across design systems. Colors present unique challenges among design tokens due to their complexity, accessibility requirements, and the emotional and brand significance they carry. A well-structured color token system enables confident color application while preventing the proliferation of one-off values.

What Are Color Tokens

Color tokens are design tokens that store color values such as hex codes, RGB values, or HSL definitions. These tokens abstract specific color values behind meaningful names, allowing designers and developers to reference colors by purpose rather than by their technical definitions.

Color tokens typically exist at multiple levels of abstraction. Primitive color tokens define the available palette, while semantic color tokens assign those palette colors to specific use cases. Some systems add a third layer for component-specific color tokens.

How Color Token Systems Work

A color token system begins with defining primitive scales. These scales establish the complete range of colors available within the design system. A common approach creates numbered scales (50, 100, 200, through 900) for each hue, providing light to dark variations that support different contexts.

color.primitive.blue.50: #EFF6FF
color.primitive.blue.100: #DBEAFE
color.primitive.blue.500: #3B82F6
color.primitive.blue.900: #1E3A8A

Semantic tokens map these primitives to use cases. Rather than naming tokens by color, semantic tokens describe function:

color.background.primary: {ref: color.primitive.white}
color.background.secondary: {ref: color.primitive.gray.100}
color.text.primary: {ref: color.primitive.gray.900}
color.interactive.primary: {ref: color.primitive.blue.500}

This semantic layer enables theming. A dark theme redefines these same semantic tokens with different primitive references:

color.background.primary: {ref: color.primitive.gray.900}
color.background.secondary: {ref: color.primitive.gray.800}
color.text.primary: {ref: color.primitive.gray.50}
color.interactive.primary: {ref: color.primitive.blue.400}

Components reference only semantic tokens, gaining automatic theme support without any code changes.

Key Considerations

• Primitive color scales should provide sufficient contrast steps for accessibility needs
• Semantic tokens should cover all common use cases to prevent primitive leakage
• Color tokens should include alpha/opacity variants when transparency is needed
• Text and background color pairs should be validated for WCAG contrast compliance
• Brand colors may need multiple tints and shades for different contexts
• Interactive states (hover, focus, disabled) require dedicated token variants
• Color tokens should support both light and dark themes from the start
• Gradients and complex colors may need specialized token structures

Common Questions

How should color scales be constructed?

Color scales should provide perceptually even steps that work together harmoniously. Simply adjusting lightness values often produces scales that appear uneven to the human eye. Perceptually uniform color spaces like OKLCH produce more consistent results.

A typical scale includes nine to eleven steps. The middle value (500) often represents the primary brand expression, with lighter values (50-400) providing backgrounds and tints, and darker values (600-900) providing accessible text and emphasis.

Each step should maintain sufficient contrast with adjacent steps while remaining recognizable as the same hue. Testing scales against actual use cases reveals whether the steps serve real needs or create artificial granularity.

How should accessibility be handled in color tokens?

Accessibility requires treating color contrast as a first-class concern in token architecture. Text colors and their corresponding background colors should be validated as pairs during token definition, not left for individual developers to verify.

One approach defines explicit pairings through naming conventions. Tokens like color.text.on-primary indicate text colors designed to work on primary backgrounds. These paired tokens undergo contrast validation during the build process.

Semantic tokens should also account for WCAG requirements by role. Body text requires 4.5:1 contrast (AA level), while large text needs only 3:1. Decorative elements may have no contrast requirement. Encoding these distinctions in token organization helps teams apply appropriate colors without manual calculation.

What about colors that do not fit the scale?

Not all colors fit neatly into numbered scales. Status colors (error, warning, success, info) carry fixed semantic meaning. Chart colors need to be distinguishable from each other rather than variations of one hue. Brand accent colors may have no scale context.

These colors can exist as standalone primitives without numbered scales. A token like color.primitive.error or color.primitive.chart.purple communicates that these colors serve specific purposes rather than participating in a graduated scale.

When standalone colors need variations (lighter error backgrounds, darker error text), dedicated light and dark variants can be defined explicitly rather than creating artificial scales. This approach maintains clarity about each color’s intended use.

Summary

Color token best practices combine thoughtful primitive scales with comprehensive semantic mappings. Effective systems build scales with perceptual uniformity, define semantic tokens that cover common use cases, and validate accessibility at the token level. By establishing clear structures and consistent patterns, color token systems enable confident color usage while supporting the theming and brand flexibility that design systems require.