CSS custom properties (variables)

CSS custom properties (commonly called CSS variables) are defined with a double-dash prefix and can be reused throughout a stylesheet. They are scoped to the element where they are defined and cascade to descendants.

Syntax

/* Define on :root to make globally available */
:root {
  --primary-color: #3b82f6;
  --spacing-base: 1rem;
}

/* Use with var() */
.button {
  background: var(--primary-color);
  padding: var(--spacing-base);
}

/* Fallback value */
color: var(--text-color, #111);

Advantages over preprocessor variables

Live in the DOM - can be changed at runtime with JavaScript (element.style.setProperty('--color', 'red')).
Respect the cascade - you can override a variable for a specific component or theme without changing the global value.
No build step required; they work in plain CSS.

Color theming pattern

Implement light/dark mode using CSS custom properties and a combination of prefers-color-scheme and a data-theme attribute:

:root {
  --bg-color: #fff;
  --text-color: #111;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg-color: #111;
    --text-color: #eee;
  }
}

[data-theme="light"] {
  --bg-color: #fff;
  --text-color: #111;
}

[data-theme="dark"] {
  --bg-color: #111;
  --text-color: #eee;
}

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

The prefers-color-scheme media query respects the OS-level dark mode preference. The data-theme attribute allows users to override the OS setting with a manual toggle. JavaScript can switch the theme by changing document.documentElement.dataset.theme.

CSS variable naming conventions

BEM-style: --block-element-property (e.g., --button-background-color). Good for component-scoped variables.
Design token style: --color-primary, --spacing-4, --font-size-lg. Preferred for design systems and global scales.
Semantic naming: --text-color, --background-color instead of --color-blue. Easier to maintain when you rebrand.

Consistency matters more than the specific convention. Document your naming pattern in a README or style guide.