We're live on Product Hunt!Support us
ColorArchive

A curated color library with 5,000+ algorithmically generated colors. Browse, search, save favorites, and export palette tokens — no account required.

CollectionsFamiliesNotesGuidesFree ResourcesConvertColorblindAboutSupportUpdates
Ready for static export
Privacy·Terms·Refunds·Cookies·Commerce Disclosure
colorarchive.org · © 2026 ColorArchive
Skip to content
ColorArchive
ProLog in
ArchiveAll ColorsCollections
Design Systems Guide
Search intent: design token color naming system

Design Token Color Naming: A System That Scales

How to name color tokens in a design system that survives rebranding, dark mode, and team growth. Covers primitive vs semantic naming, common mistakes, and the two-tier structure that most successful systems use.

Design SystemsUI/UXBrand
Key points
Primitive color tokens define what a color is (blue-60, amber-30). Semantic tokens define what it does (action-primary, surface-default). UI code should only reference semantic tokens — this means a complete rebrand changes one mapping file, not hundreds of component references.
Avoid hue-specific names in semantic tokens. 'color-blue-primary' locks the primary action color to blue, which breaks if the brand changes hue. 'color-action-primary' is theme-agnostic and equally valid in a green or violet rebrand.
Plan for states before naming anything. A semantic token named 'action-primary' must eventually accommodate 'action-primary-hover', 'action-primary-disabled', 'action-primary-on-dark'. If your naming taxonomy doesn't accommodate compound names from the start, you'll rename tokens mid-project.

The two-tier naming model: primitives and semantics

The two-tier model is the current standard for scalable color systems. Tier 1 — Primitives: named stops on a perceptually even scale (brand-blue-10 through brand-blue-90, neutral-0 through neutral-100). These exist in the token dictionary but are not directly referenced in component code. Tier 2 — Semantics: purpose-driven names that map to primitives (color-text-primary maps to neutral-90, color-action-primary maps to brand-blue-60). Components reference only semantic tokens. A rebrand or theme change updates only the primitive-to-semantic mapping — all component code remains unchanged. The key discipline: never let component code reference a primitive. If it does, the two-tier model degrades to a one-tier system and loses its main advantage.

Naming conventions for dark mode and multi-theme systems

Dark mode naming fails when semantic tokens embed appearance assumptions. 'color-background-white' is incorrect in dark mode; 'color-surface-default' is correct in both. The rule: name by role and context, never by appearance. For theming beyond light/dark, the semantic token vocabulary must be theme-agnostic — it defines the structural relationships (primary action, default surface, interactive border) without specifying the color that satisfies those roles. The primitive-to-semantic mapping files — one per theme — resolve the structural names to actual values. Components never change; themes are swapped by loading a different mapping.

Common naming mistakes and how to fix them

Mistake 1: Hue names leaking into semantics ('color-blue-cta'). Fix: split into primitive (blue-60) and semantic (action-cta). Mistake 2: Ordinal names without meaning ('color-1', 'color-2'). Fix: use semantic role names even in small systems — the documentation overhead of 'primary, secondary, tertiary' is lower than the cognitive overhead of numbered aliases. Mistake 3: Flat naming with no category structure ('primary, secondary, accent, muted'). Fix: namespace by category ('text-primary', 'surface-secondary', 'border-accent') so the system remains navigable as it grows past 20 tokens. Mistake 4: Not planning for states ('action-primary' with no hover, focus, disabled variants). Fix: define the full state vocabulary before assigning primitive values, so the taxonomy is consistent from the first token.

Featured collection
Quiet Luxury

Soft neutrals and muted warm surfaces for editorial, beauty, and premium product work.

Open collectionAll collections
Open next
Explore Quiet Luxury paletteExplore Dark Mode UI KitBrowse all design system guides
Practical next step

Move from the guide into a concrete palette lane

Guides explain the use case. Collections prove the taste. Pro handles the export and implementation layer.

Upgrade to ProMore guides
Related guides
Design Systems
Pairing Color with Typography: A Systems Approach
Every typeface has a palette it prefers and a palette it fights. How to match font personality to palette personality for cohesive design systems.
Design Systems
How to Build a Tints and Shades Color Scale for Any Brand Color
A complete guide to generating tonal color scales for design systems. Learn the difference between tints, shades, and tones, the WCAG contrast requirements for each step, and how to choose the right scale for your brand.
Brand Systems Guide
How to design a proprietary brand color system from scratch
Learn how to build a proprietary brand color system from a single anchor color, with five functional roles, tonal ranges, and production-ready CMYK specifications.