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.

CollectionsFamiliesBrandsRegionsJournalNotesGuidesFree ResourcesEmbed widgetConvertColorblindAboutSupportUpdates
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 naming design systems design token color semantic color names color system naming scale colors tokens

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 SystemsColor TokensNaming ConventionsFrontend Development
Key points
Scale-based naming (blue-100 to blue-900) is flexible and composable but requires external documentation to tell developers which value to use for which context. It drifts over time as teams make different choices.
Semantic naming (success, error, background-primary) encodes intent into the name, preventing misuse — but proliferates tokens over time as edge cases accumulate.
The two-tier approach separates primitives (blue-50 maps to a hex value) from semantics (background-primary maps to blue-50). Themes are made by remapping the semantic layer to different primitives, with zero changes to component code.

Why Naming Decisions Have Long-Term Consequences

Color naming in a design system is an architectural decision, not a stylistic one. Once a naming convention is established and adopted across a codebase and component library, changing it is expensive: every usage must be updated, every contributor must be re-educated, and the migration period where both old and new names coexist creates confusion. The naming convention chosen at the start shapes how the team reasons about color for as long as the system runs. Choosing the wrong model is recoverable, but only at significant cost. The decision deserves proportionate attention at system founding.

Scale-Based Naming

Scale-based naming assigns color positions along a lightness scale, typically using numbers (blue-100 through blue-900) or descriptive scales (blue-lightest through blue-darkest). The numbers or descriptors encode position without encoding intent — blue-600 says nothing about whether this value should be used for text, borders, backgrounds, or interactive states. This approach is flexible and composable: any component can use any scale value without violating a semantic rule. The weakness is that the appropriate use of each scale value must be documented externally and learned by contributors. Scale-based systems are susceptible to drift as different teams make independent choices about which value maps to which role. The advantage is that adding new colors or reorganizing the palette is straightforward — you are only rearranging primitives.

Semantic Naming

Semantic naming encodes the intended use directly into the token name: success, error, warning, background-primary, text-secondary, border-interactive. The name carries the usage contract — a developer using success-default knows it is for success states and cannot accidentally apply it to a background context without visibly violating the semantic convention. This approach reduces drift and makes the system self-documenting. The weakness is proliferation: as components multiply and edge cases accumulate, semantic systems grow large. A color used for both an interactive border and a focus ring may need two separate tokens to preserve semantic clarity, even if both point to the same underlying hex value. Large semantic systems can become difficult to navigate.

Two-Tier Architecture

The modern best practice is a two-tier approach that separates concerns: a primitive layer and a semantic layer. Primitives map meaningful names to raw values — blue-50 maps to #EFF6FF, blue-900 maps to #1E3A5F. Semantics map intent names to primitives — background-primary maps to blue-50, text-interactive maps to blue-700. Component code references only semantic tokens, never primitives directly. This separation enables theme changes (light to dark mode) by remapping the semantic layer to different primitives without changing any component code. Background-primary maps to blue-50 in light mode and to gray-950 in dark mode; components using background-primary automatically get the correct value in each theme.

Practical Naming Conventions

For the semantic layer, a consistent naming structure improves navigability: [component/context]-[role]-[variant]-[state]. For example: button-background-primary-default, button-background-primary-hover, text-heading-primary, border-input-default, border-input-error. For the primitive layer, a simple numeric scale works well: [hue]-[scale-number], where scale-number increases with lightness (50 very light, 900 very dark) or decreases with lightness (100 dark, 900 light) — choose one convention and be consistent. Document which convention your scale uses; both exist in the wild and mixing them across systems creates confusion. For semantic neutrals, warm-gray and cool-gray should be separate scales — treating all grays as a single scale obscures important temperature distinctions that affect visual tone.

Open next
Browse color system palettesBuild a paletteExplore neutral color families
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
Design Notes

One practical color note a week

Contrast and accessibility, color spaces like OKLCH, palette structure, design tokens — written for people who build things. No daily noise.

Get Design Notes weekly

One email a week. Unsubscribe anytime.

Related guides
Design Systems
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.
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 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.