Creating Maintainable Color Systems with CSS Variables

By swatches.net team • January 2026 • 11 min read

CSS custom properties (variables) have transformed how we manage colors in design systems. Gone are the days of find-and-replace across hundreds of files. Modern color systems are dynamic, themeable, and maintainable—if you structure them correctly.

Benefits of CSS Custom Properties

Maintainability: Change colors in one place, update everywhere
Theming: Switch between light/dark mode with ease
Runtime Updates: Change colors with JavaScript without recompiling
Inheritance: Cascade values through your component tree
calc() Support: Perform calculations on color properties

Naming Conventions

Your naming strategy determines how maintainable your system will be. There are two main approaches:

1. Semantic Names (Recommended)

Name variables based on their purpose, not their value:

/* Good - Semantic naming */
:root {
  --color-primary: #2D5BE3;
  --color-secondary: #6B7280;
  --color-success: #10B981;
  --color-error: #EF4444;
  --color-warning: #F59E0B;
  
  --text-primary: #1A1A1A;
  --text-secondary: #6B6B6B;
  --text-tertiary: #9A9A9A;
  
  --bg-primary: #FFFFFF;
  --bg-secondary: #F9FAFB;
}

2. Literal Names

Name variables after their color value (less flexible):

/* Less flexible - Literal naming */
:root {
  --blue-600: #2D5BE3;
  --gray-600: #6B7280;
  --green-600: #10B981;
}

Pro Tip: Use both! Define literal color scales, then reference them with semantic names.

Two-Tier System

The best approach combines both strategies:

/* Tier 1: Color Scales (Literal) */
:root {
  /* Blue scale */
  --blue-50: #EFF6FF;
  --blue-100: #DBEAFE;
  --blue-500: #3B82F6;
  --blue-600: #2563EB;
  --blue-900: #1E3A8A;

  /* Tier 2: Semantic Names */
  --color-primary: var(--blue-600);
  --color-primary-hover: var(--blue-700);
  --bg-primary-subtle: var(--blue-50);
}

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

Dark Mode Implementation

CSS variables make dark mode trivial to implement:

:root {
  /* Light mode (default) */
  --bg-primary: #FFFFFF;
  --text-primary: #1A1A1A;
}

/* Dark mode */
@media (prefers-color-scheme: dark) {
  :root {
    --bg-primary: #0F0F0F;
    --text-primary: #E5E5E5;
  }
}

/* Manual toggle support */
html[data-theme="dark"] {
  --bg-primary: #0F0F0F;
  --text-primary: #E5E5E5;
}

Complete Design System Example

:root {
  /* === Color Scales === */
  /* Gray scale */
  --gray-50: #F9FAFB;
  --gray-100: #F3F4F6;
  --gray-900: #111827;

  /* Brand colors */
  --blue-500: #3B82F6;
  --blue-600: #2563EB;

  /* === Semantic Tokens === */
  /* Backgrounds */
  --bg-primary: var(--gray-50);
  --bg-secondary: #FFFFFF;
  --bg-tertiary: var(--gray-100);

  /* Text */
  --text-primary: var(--gray-900);
  --text-secondary: var(--gray-600);

  /* Actions */
  --color-primary: var(--blue-600);
  --color-primary-hover: var(--blue-700);

  /* Borders */
  --border: var(--gray-200);
  --border-focus: var(--blue-500);
}

Organizing Your Variables

Structure matters for maintainability. Here's a recommended organization:

Primitive Colors: Raw color values (scales)
Semantic Tokens: Purpose-based references
Component Tokens: Component-specific overrides

JavaScript Integration

CSS variables can be read and modified with JavaScript:

// Get a CSS variable value
const primaryColor = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-primary');

// Set a CSS variable
document.documentElement.style
  .setProperty('--color-primary', '#FF0000');

// Toggle dark mode
function toggleDarkMode() {
  document.documentElement.dataset.theme = 
    document.documentElement.dataset.theme === 'dark' 
      ? 'light' 
      : 'dark';
}

Performance Considerations

CSS variables have minimal performance impact
They're faster than inline styles or className changes
Browser support is excellent (IE11 is the only exception)
No build step required—they work in vanilla CSS

Best Practices

Always define variables in :root for global access
Use semantic names for consumer-facing variables
Document your color system in code comments
Create a visual style guide alongside code
Test all color combinations for accessibility
Version your design tokens
Keep primitive and semantic tokens separate

Conclusion

CSS custom properties are the foundation of modern, maintainable color systems. By combining literal color scales with semantic naming, you create flexible systems that adapt to theming, scale with your product, and remain easy to maintain as your team grows.

Start with a solid structure, document your decisions, and your future self (and team) will thank you.