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
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.

Featured collection
Data Dashboard

Cobalt signal, teal confirmation, amber warning, crimson alert, and slate neutral — a perceptually balanced palette designed for analytics dashboards and data visualization interfaces.

Open collectionAll collections
Open next
Design Token GeneratorBrand Color GeneratorData Dashboard Collection
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
Token Architecture
Design Token Architecture for Color: Building Scalable, Maintainable Systems
A well-structured token architecture makes color systems easier to maintain, theme, and evolve. The three-tier model — primitive, semantic, component — provides the foundation for color systems that survive rebrands, multi-theme requirements, and team scale.
Design Systems
Naming Colors in Design Systems: Semantic vs. Scale vs. Primitive
How you name colors in a design system shapes how your team reasons about color for years. Semantic names encode intent. Scale names encode position. The two-tier approach separates both concerns. Here is how to choose the right architecture.
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.