Color Naming Conventions in Design Systems

← Back to Blog

Color Naming Conventions in Design Systems

· 6 min read

Why Color Naming Matters

A good color variable naming system is the cornerstone of design system maintainability. When you use HEX values directly (like #4A90E2) without naming them, changing a brand color means globally replacing that value throughout the codebase, with no way to understand the color's purpose from the code. A good naming system makes color intent self-documenting and makes theme switching and brand updates easy.

Three Primary Naming Strategies

Color variable naming primarily uses three strategies, each with pros and cons:

• Value-based naming: Like --blue-500, --gray-100. Describes the color itself directly; Tailwind CSS uses this strategy.
• Role-based naming: Like --color-primary, --color-background. Describes the color's purpose; Bootstrap and many design systems use this strategy.
• Two-tier naming: Combines both approaches — first defining a color tier (raw values), then a semantic tier (purpose). This is the best practice for modern design systems.

Implementing a Two-Tier Naming System

The two-tier naming system is currently the most recommended approach: the first tier (palette layer) defines all available color values; the second tier (semantic layer) references the first tier and assigns semantic meaning:

/* Tier 1: Color palette (raw values) */
:root {
  --blue-100: hsl(214, 80%, 92%);
  --blue-500: hsl(214, 80%, 52%);
  --blue-700: hsl(214, 80%, 35%);
  --blue-900: hsl(214, 80%, 18%);

  --gray-50:  hsl(220, 15%, 98%);
  --gray-800: hsl(220, 15%, 20%);
}

/* Tier 2: Semantic tokens */
:root {
  --color-primary:        var(--blue-500);
  --color-primary-hover:  var(--blue-700);
  --color-primary-subtle: var(--blue-100);
  --color-bg:             var(--gray-50);
  --color-text:           var(--gray-800);
}

/* Usage in components */
.btn-primary {
  background: var(--color-primary);
  color: white;
}
.btn-primary:hover {
  background: var(--color-primary-hover);
}

Naming Practices from Major Design Systems

Different major design systems have different naming conventions — understanding them helps make more informed choices:

• Tailwind CSS: Uses color name + number (50–950), like text-blue-500, bg-gray-100. Concise and intuitive but carries no semantic meaning.
• Material Design: Primary, Secondary, Background, Surface, Error — each with an "On-" prefix (like On-Primary for text color on top of Primary).
• GitHub Primer: Uses a two-tier system — bottom tier is color palettes, top tier is functional semantic names (like --color-btn-primary-bg). Extremely granular.

Best Practices for Naming Conventions

• Avoid specific color names as semantic names: --color-blue is worse than --color-primary — the former causes confusion when the brand color changes to green
• Use consistent suffix conventions: State suffixes like hover/active/disabled/focus should be consistent across the entire system
• Add context for semantic colors: Don't just have --error — also have --error-bg (error alert background) and --error-border
• Document each variable's purpose: Write comments explaining the specific scenarios each color variable is intended for

Best Practices for SCSS Color Variables

// SCSS: Two-tier color system

// === Tier 1: Color palette ===
$blue-50:   #EFF6FF;
$blue-500:  #3B82F6;
$blue-600:  #2563EB;
$blue-700:  #1D4ED8;

// === Tier 2: Semantic tokens ===
$color-primary:          $blue-500;
$color-primary-hover:    $blue-600;
$color-primary-active:   $blue-700;
$color-primary-focus-ring: rgba($blue-500, 0.4);

// === Component-level tokens ===
$btn-primary-bg:         $color-primary;
$btn-primary-bg-hover:   $color-primary-hover;
$btn-primary-text:       #ffffff;

Migrating to CSS Custom Properties

If your project currently uses SCSS color variables, consider gradually migrating to CSS custom properties (CSS variables). The main advantage of CSS variables is that they can be changed at runtime (like theme switching), which SCSS variables cannot do. For migration: first replace the semantic tier with CSS variables while keeping SCSS variables as raw color values, then gradually update component styles from SCSS variables to CSS variables.

Try the online tool now — no installation, completely free.

Open Tool →