Design Systems

Naming Conventions for Color Variables: Semantic vs. Descriptive

The names you give your color variables determine how flexible and maintainable your color system is over time. There are two main approaches: descriptive naming (what the color looks like) and semantic naming (what the color does).

Descriptive Names

Descriptive names describe the color itself: --blue-600, --red-500, --gray-100. PaletteRx">Tailwind CSS popularized this approach. The advantage: the name tells you exactly what color you will get. The disadvantage: if your brand blue changes to purple during a rebrand, every reference to --blue-600 now points to something that is not blue. The name lies.

Semantic Names

Semantic names describe the color's purpose: --color-primary, --color-error, --color-surface. PaletteRx uses this approach in its exports. The advantage: the name stays accurate through rebrands. If your primary changes from blue to purple, --color-primary still means "our primary brand color." No references break. The disadvantage: the name does not tell you what color you will see without checking the definition.

The Layered Approach

Many mature design systems use both layers. A primitive layer uses descriptive names (--blue-600: #2563eb). A semantic layer references the primitive layer (--color-primary: var(--blue-600)). Components reference only the semantic layer. A rebrand changes one mapping (--color-primary: var(--purple-600)) and every component updates.

PaletteRx's Approach

PaletteRx exports use semantic naming by default: --color-primary, --color-supporting, --color-light-base, --color-dark-base. This is the most practical approach for most projects because it directly maps to how colors are used in production.

💡 Recommendation: Use semantic names (PaletteRx's default export) for most projects. Add a descriptive primitive layer only if your design system is large enough to benefit from the abstraction (typically 20+ components, multiple themes, or a multi-brand system).

Ready to Build Your Palette?

PaletteRx guides you from color selection to accessible, export-ready design systems in minutes.

🎨 Launch PaletteRx