Skip to content
ColorArchive
Design Systems
Search intent: color token naming conventions design system

Color Token Naming Conventions: Primitive, Semantic, and Component Layers

How to structure a three-layer token naming system that scales from a small product to a multi-brand design system — with practical naming patterns used by leading teams.

Design TokensDesign SystemsNaming ConventionsComponent Library
Key points
A two-layer system (primitive + semantic) solves most single-product needs; multi-brand systems require a third component layer.
Primitive tokens describe what a color is ('blue-500'); semantic tokens describe what it means ('color.action.primary'); component tokens describe where it lives ('button.background.default').
Consistent naming prevents token sprawl — without a convention, teams end up with dozens of one-off tokens that duplicate each other.

The three-layer model

Most production design token systems use three layers. Primitive tokens are the raw values — they describe what the color is. Examples: `color.blue.500 = #3B82F6`, `color.gray.100 = #F3F4F6`. Semantic tokens describe intent — they reference primitives by role. Examples: `color.action.primary = {color.blue.500}`, `color.surface.default = {color.gray.100}`. Component tokens describe specific component slots and reference semantic tokens. Examples: `button.background.primary = {color.action.primary}`. This hierarchy allows you to retheme an entire product by changing a single semantic token, or retheme just one component by changing its component token.

Primitive token patterns

Primitive tokens follow a scale pattern: `{namespace}.{hue}.{step}`. Common step scales: 50-100-200-300-400-500-600-700-800-900 (Tailwind-style) or 0-10-20-30-40-50-60-70-80-90-100 (Radix-style). Choose one scale and apply it consistently to all hues in your palette. Avoid naming primitives by their intended use ('brand-blue', 'error-red') — primitives should be purely descriptive. ColorArchive's full archive exports work naturally as primitive tokens, with the color's lightness and chroma bands mapping directly to scale steps.

Semantic token patterns

Semantic tokens answer 'what is this used for?' The most common semantic categories are: surface (backgrounds and containers), text (all typography), border (dividers and outlines), action (interactive elements), status (success, warning, error, info), and icon. Within each category, define variants for state: `color.action.primary.default`, `color.action.primary.hover`, `color.action.primary.pressed`, `color.action.primary.disabled`. Keeping state as a suffix rather than a top-level category keeps related tokens together when sorted alphabetically.

Avoiding common mistakes

The most common token mistakes are: creating semantic tokens that duplicate primitives without adding meaning ('color.brand = {color.blue.500}' is not semantic — what does 'brand' mean?); using semantic tokens as primitives in component tokens (component tokens should always reference semantic, not primitive, tokens); and creating too many semantic tokens for edge cases before you need them. Start with fewer, broader semantic tokens and subdivide only when you have a concrete need. A token system with 20 semantic tokens that cover 90% of your UI is more useful than one with 200 that no one uses consistently.

Exporting from ColorArchive

ColorArchive's token export generates both primitive and semantic layers. The primitive layer maps the full archive to a consistent scale. The semantic layer provides a starter set of role tokens you can rename and extend for your product. Export as CSS custom properties, JSON (W3C Design Token format), or Figma-compatible structures. The brand generator creates a focused palette with pre-assigned semantic roles so you can move directly from palette selection to token implementation without a manual mapping step.

Practical next step

Move from the guide into a concrete palette lane

Guides explain the use case. Collections prove the taste. Packs handle the export and implementation layer.

Browse packsMore guides
Related guides
Design Systems
Color Token Architecture: Building Maintainable Design Token Systems
A poorly designed token architecture makes dark mode a two-week rebuild. A well-designed one makes it a two-hour configuration change. This guide covers the structural principles — primitive, semantic, and component tier design — that determine how maintainable your color system is over time.
Design Systems Guide
How to Build a Color Token System: The Complete Designer's Guide
A color token system is the infrastructure layer between your abstract brand palette and the code that implements it. Tokens translate color decisions into reusable, maintainable variables that can be updated globally, themed, and exported to any platform. Building a token system is not about adding complexity — it is about removing the hidden complexity that accumulates when colors are hard-coded directly into components.
Design Systems
Documenting Color Systems: The Three Layers Every Design System Needs
Most color systems fail not because the colors are wrong, but because the decisions behind them were never written down. When the designer who chose the palette leaves, the rationale disappears. This guide covers the minimum viable color system documentation — three layers targeting designers, engineers, and QA — and how to structure it so it actually gets used.