The Problem With Naming Colors in Design Systems

Color naming in design systems is a design decision with long-term architectural consequences. Once a naming convention is established and adopted across a codebase and component library, changing it is expensive — it requires updating every usage, re-educating every contributor, and managing the migration period where both old and new names exist simultaneously. The naming convention you choose at the start will shape how your team thinks about color for years. The two dominant naming philosophies are scale-based and semantic. Scale-based naming (blue-100 through blue-900, or blue-lightest through blue-darkest) describes position on a lightness scale without encoding intent. It is neutral, flexible, and composable — any component can use any value in the scale without violating a semantic rule. The weakness is that it requires developers to know which scale value to use for which context, which knowledge lives in documentation and in people rather than in the system itself. Scale-based systems are more likely to drift over time as different teams make different choices about which scale value represents a background, a border, or a text color. Semantic naming (success, error, warning, info, background-primary, text-secondary) encodes the intended use directly into the name. A developer using success-default cannot accidentally apply it to a background context without violating the semantic contract. The weakness is that semantic names constrain reuse — a color named success-green cannot be reused for a progress bar that happens to use the same green without either bending the semantic (calling a progress bar 'success') or creating a new token that is a duplicate of the same value. Semantic systems tend to proliferate tokens over time as edge cases accumulate. The modern best practice is a two-tier approach: a scale-based primitive layer that maps to raw color values, and a semantic layer that maps intent-names to primitives. The semantic token background-primary points to the primitive gray-50, which points to a specific hex value. Theme changes (light to dark mode) are made by remapping the semantic layer to different primitives — background-primary maps to gray-50 in light mode and to gray-950 in dark mode — without changing any component code that references background-primary. This architecture separates the concerns of 'what color is this' (primitives) from 'what is this color used for' (semantics), and is why design token systems like Figma Variables, Style Dictionary, and Theo use this two-layer approach.