Color Naming Conventions for Scalable Design Systems

Why Color Naming Matters

Good color naming makes your codebase easier to maintain, enables theme switching, and helps team members understand color purposes at a glance.

Semantic vs Descriptive Names

There are two main approaches to color naming:

• Descriptive: Names describe the color (blue-500, forest-green)
• Semantic: Names describe the purpose (primary, success, warning)
• Recommended: Use semantic names that reference descriptive colors

// tailwind.config.js - Recommended approach
module.exports = {
  theme: {
    extend: {
      colors: {
        // Base palette (descriptive)
        brand: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        },
        // Semantic aliases
        primary: 'var(--color-primary)', // Set via CSS variables
        secondary: 'var(--color-secondary)',
        success: '#22c55e',
        warning: '#f59e0b',
        error: '#ef4444',
        // Surface colors
        surface: {
          DEFAULT: '#ffffff',
          secondary: '#f8fafc',
          elevated: '#ffffff',
        },
        // Text colors
        content: {
          DEFAULT: '#0f172a',
          secondary: '#475569',
          muted: '#94a3b8',
        }
      }
    }
  }
}

CSS Variables for Theming

:root {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
  --color-surface: #ffffff;
  --color-content: #0f172a;
}

.dark {
  --color-primary: #60a5fa;
  --color-secondary: #a78bfa;
  --color-surface: #0f172a;
  --color-content: #f1f5f9;
}