CSS Custom Properties: The Modern Way to Manage Design Tokens

CSS custom properties (also called CSS variables) landed in browsers in 2016 and are now supported everywhere. If you're still using Sass variables or hardcoded hex values throughout your CSS, this guide will show you what you're missing — and why custom properties solve problems that preprocessors can't.

The basics

/* Declare a custom property on :root */
:root {
  --primary: #2f855a;
  --primary-light: #48bb78;
  --spacing-md: 1rem;
  --border-radius: 8px;
}

/* Use it anywhere */
.button {
  background-color: var(--primary);
  border-radius: var(--border-radius);
  padding: var(--spacing-md) calc(var(--spacing-md) * 1.5);
}

.button:hover {
  background-color: var(--primary-light);
}

Custom properties are inherited by child elements and can be redeclared at any scope — which is what makes them fundamentally different from Sass variables.

Scoped variables

Unlike Sass variables which are resolved at build time, CSS custom properties are resolved at runtime and respect the cascade:

:root {
  --bg: white;
  --text: black;
}

.card {
  background: var(--bg);
  color: var(--text);
}

/* Redefine in a dark-mode context */
.dark-theme {
  --bg: #1a1a2e;
  --text: #e8e8e8;
}

Every .card inside .dark-theme automatically uses the dark values — no class changes required on the cards themselves.

Dark mode without the mess

This is the cleanest use case for custom properties:

:root {
  --surface: white;
  --on-surface: #1a1a1a;
  --accent: #2f855a;
  --border: #e2e8f0;
}

@media (prefers-color-scheme: dark) {
  :root {
    --surface: #1a1a2e;
    --on-surface: #e8e8e8;
    --accent: #68d391;
    --border: #2d3748;
  }
}

body {
  background: var(--surface);
  color: var(--on-surface);
}

.card {
  background: var(--surface);
  border: 1px solid var(--border);
}

One set of variable overrides adapts the entire UI. No duplicated selectors, no body.dark .component .element {} chains.

JavaScript integration

Custom properties are readable and writable from JavaScript — this is something Sass variables can never do:

// Read a variable
const root = document.documentElement;
const primary = getComputedStyle(root)
  .getPropertyValue('--primary')
  .trim(); // "#2f855a"

// Write a variable
root.style.setProperty('--primary', '#ff6b6b');

// Per-element overrides
const card = document.querySelector('.card');
card.style.setProperty('--bg', '#f0fff4');

This enables dynamic theming, user-controlled colour schemes, and animations driven by scroll position or mouse coordinates.

Fallback values

var() accepts a fallback as the second argument:

.button {
  background: var(--primary, #2f855a);  /* fallback if not defined */
  padding: var(--spacing, 1rem 2rem);
}

Fallbacks can even be other var() calls:

color: var(--brand-color, var(--fallback-color, black));

Computed values and calc()

Custom properties work seamlessly with calc():

:root {
  --base-spacing: 8px;
}

.sm { margin: var(--base-spacing); }
.md { margin: calc(var(--base-spacing) * 2); }
.lg { margin: calc(var(--base-spacing) * 4); }

You can even store partial values:

:root {
  --shadow-color: 220 3% 15%;  /* HSL components without hsl() wrapper */
}

.card {
  box-shadow: 0 2px 8px hsl(var(--shadow-color) / 0.2);
}

.card:hover {
  box-shadow: 0 8px 24px hsl(var(--shadow-color) / 0.35);
}

This technique — storing HSL components separately — lets you change both lightness and opacity independently from a single variable.

Animating custom properties

Custom properties can be animated with @property (CSS Houdini):

@property --angle {
  syntax: '<angle>';
  initial-value: 0deg;
  inherits: false;
}

.spinner {
  background: conic-gradient(from var(--angle), #ff6b6b, #4ecdc4);
  animation: rotate 2s linear infinite;
}

@keyframes rotate {
  to { --angle: 360deg; }
}

Without @property, custom property animations snap between start and end values instead of interpolating. With it, you get smooth transitions for any CSS value type.

Naming conventions

There is no enforced standard, but common patterns:

:root {
  /* Component-prefixed */
  --button-bg: var(--primary);
  --button-text: white;
  --button-hover-bg: var(--primary-dark);

  /* Semantic tokens */
  --color-primary: #2f855a;
  --color-text: #1a202c;
  --color-background: white;

  /* Scale-based spacing */
  --space-1: 4px;
  --space-2: 8px;
  --space-4: 16px;
  --space-8: 32px;
}

Prefix component-specific variables with the component name to avoid naming conflicts across large stylesheets.

When to still use Sass

CSS custom properties do not replace Sass entirely. Sass remains useful for:

• Loops and maps — generating utility classes programmatically
• Mixins — reusable blocks of CSS that vary by parameter
• Functions — complex colour math at build time
• Nesting — (though native CSS nesting is now available)

For colour palettes, spacing scales, typography tokens, and theming — CSS custom properties are the right tool.

Debugging

Custom properties show up in browser DevTools like any other property. In Chrome DevTools, the Styles panel shows computed variable values inline — hover over a var(--name) declaration and it shows the resolved value. The console command getComputedStyle(element).getPropertyValue('--name') also works for quick inspection.

---

CSS custom properties are not a niche feature — they are the foundation of modern CSS architecture. Once you model your design system as variables on :root, theming, dark mode, and component variants become trivial to implement and maintain. The JavaScript integration is what makes them genuinely more powerful than preprocessors: your design tokens become live, accessible, and modifiable at runtime.