What are CSS custom properties (variables)?

CSS custom properties (also called CSS variables) are entities defined by CSS authors using the -- prefix (e.g. --color-primary). They can hold any value and are referenced anywhere in a stylesheet using var(). They cascade and inherit like regular CSS properties, making them ideal for design tokens, theming, and consistent styling across a project.

How do I use CSS variables in my stylesheet?

Define variables in a :root block at the top of your CSS file, then reference them with the var() function. For example: ':root { --color-primary: #6366f1; }' and '.button { background: var(--color-primary); }'. The var() function accepts an optional fallback: var(--color-primary, blue).

What is the difference between CSS variables and Sass/LESS variables?

CSS custom properties are native browser features that work at runtime — they can be changed dynamically with JavaScript, inherit through the DOM, and are scoped to their selector. Sass and LESS variables are compile-time only; they're resolved before the browser receives the CSS and cannot be read or changed at runtime.

Can I change CSS variables with JavaScript?

Yes. Use element.style.setProperty('--variable-name', 'value') to set a variable on any element, or document.documentElement.style.setProperty() to change a :root variable globally. Read variables with getComputedStyle(element).getPropertyValue('--variable-name'). This enables runtime theming and animations.

What CSS units should I use for spacing variables?

rem is recommended for most spacing (padding, margin, gap) because it scales with the root font size and respects user browser preferences. Use px for borders, outlines, and fixed decorative elements. Use % for fluid layouts, and vw/vh for viewport-relative sizing. This tool supports all CSS length units.

Does this tool work with Tailwind CSS?

Yes. Tailwind CSS 4 uses CSS custom properties natively for its theme. You can paste the generated :root block into your CSS file, or map the variables to Tailwind's @theme configuration. In Tailwind 3 you can reference CSS variables using arbitrary values like bg-[var(--color-primary)].

CSS Variables Generator

Create and organize CSS custom properties — color picker, spacing units, font stacks, live :root preview

All processing happens in your browser. No data is sent to any server.

Colors Variables

Brand colors, semantic colors, neutrals

Color preview

color-primary

color-secondary

color-accent

color-bg

color-text

Generated CSS

18 of 18 variables with valid names

:root {
  /* Colors */
  --color-primary: #6366f1;
  --color-secondary: #8b5cf6;
  --color-accent: #ec4899;
  --color-bg: #ffffff;
  --color-text: #111827;

  /* Spacing */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 48px;

  /* Typography */
  --font-sans: Inter, system-ui, -apple-system, sans-serif;
  --font-mono: 'Fira Code', 'Cascadia Code', 'JetBrains Mono', monospace;
  --font-serif: Georgia, 'Times New Roman', serif;

  /* Borders */
  --border-default: 1px solid #e5e7eb;
  --border-focus: 2px solid #6366f1;

  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
}

Usage in CSS

.element {
  color: var(--color-primary);
  padding: var(--spacing-md);
  font-family: var(--font-sans);
}

You’re starting a new project and need a clean :root block with your design tokens — colors, spacing scale, font sizes, border radii, shadows. You could type it all out, but getting consistent naming (--color-primary-500 vs --primary vs --brand-color), remembering to add dark mode overrides, and organizing variables by category takes longer than it should for what’s essentially boilerplate.

Why This Generator (Not the Custom Properties Generator)

PureDevTools has two CSS variables generators. The CSS Custom Properties Generator includes preset themes and automatic dark mode generation. This tool takes a simpler approach: define variables category by category with a live :root preview, see the output build in real time. Choose this for a lightweight workflow without presets. Everything runs in your browser; no data is sent anywhere.

CSS Custom Properties Explained

CSS custom properties — commonly called CSS variables — are a native browser feature that lets you define reusable values directly in your stylesheet. Unlike preprocessor variables (Sass, LESS), CSS variables are resolved at runtime, can be modified with JavaScript, and inherit through the DOM tree like any other CSS property.

You define a variable with the -- prefix and read it back with var():

:root {
  --color-primary: #6366f1;
  --spacing-md: 16px;
  --font-sans: Inter, system-ui, sans-serif;
}

.button {
  background-color: var(--color-primary);
  padding: var(--spacing-md);
  font-family: var(--font-sans);
}

The :root selector targets the document root element (<html>), making the variables globally available across the entire page.

Why Organize Variables by Category

A flat list of custom properties becomes unmanageable as projects grow. Grouping variables into categories — colors, spacing, typography, borders, shadows — creates a design token system: a single source of truth for all visual values in a codebase.

Benefits of a categorized variable system:

Consistency: Every button, card, and modal uses the same --spacing-md value instead of scattered hardcoded 16px values
Theming: Swap a color scheme by changing a handful of variables in one place — dark mode, brand variants, customer whitelabels
Maintainability: Rename a brand color once (--color-primary: #4f46e5) and it updates everywhere
Collaboration: Designers and developers share the same token vocabulary, reducing handoff ambiguity

Color Variables

Color custom properties form the foundation of a design system. Common patterns:

:root {
  /* Brand */
  --color-primary: #6366f1;
  --color-secondary: #8b5cf6;
  --color-accent: #ec4899;

  /* Neutrals */
  --color-bg: #ffffff;
  --color-text: #111827;
  --color-muted: #6b7280;

  /* Semantic */
  --color-success: #22c55e;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
}

Reference them in components: color: var(--color-muted) or border-color: var(--color-error).

Spacing Variables

Spacing variables encode your layout scale — the consistent set of sizes used for padding, margin, and gap. A numeric scale based on a base unit (commonly 4px or 8px) is easiest to reason about:

:root {
  --spacing-xs:  4px;
  --spacing-sm:  8px;
  --spacing-md:  16px;
  --spacing-lg:  24px;
  --spacing-xl:  48px;
  --spacing-2xl: 96px;
}

rem vs px for spacing: rem units scale with the root font size and respect user browser preferences for accessibility. For spacing values intended to scale with text, prefer rem. Use px for borders, outlines, and small decorative elements that should stay fixed regardless of font size.

Typography Variables

Typography variables encode your font stacks. A font stack lists fonts in priority order with a generic fallback:

:root {
  --font-sans:  Inter, system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
  --font-mono:  'Fira Code', 'Cascadia Code', 'JetBrains Mono', Consolas, monospace;
  --font-serif: Georgia, 'Times New Roman', Times, serif;
}

System fonts (system-ui, -apple-system) render using the OS default sans-serif — no web font download required, excellent performance. Web fonts like Inter go first as the preferred choice.

You can extend the pattern to include font-size scales and line-height values:

:root {
  --text-sm:   0.875rem;
  --text-base: 1rem;
  --text-lg:   1.125rem;
  --text-xl:   1.25rem;
  --leading-normal: 1.5;
}

Border Variables

Border variables store complete border shorthand values, making it easy to apply a consistent border style:

:root {
  --border-default: 1px solid #e5e7eb;
  --border-focus:   2px solid #6366f1;
  --border-error:   1px solid #ef4444;
  --border-radius:  0.5rem;
}

.input {
  border: var(--border-default);
  border-radius: var(--border-radius);
}

.input:focus {
  border: var(--border-focus);
}

Shadow Variables

Box shadow variables encode your elevation scale — from subtle hover states to modal overlays:

:root {
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
}

Using rgb(0 0 0 / 0.1) (modern syntax) instead of rgba(0,0,0,0.1) is now broadly supported and aligns with the CSS Color Level 4 specification.

Cascading and Scoping

CSS variables follow the cascade — you can override them at any selector level:

:root {
  --color-primary: #6366f1; /* global default */
}

.dark-theme {
  --color-primary: #818cf8; /* dark mode override */
}

.widget {
  --color-primary: #ec4899; /* component-level override */
}

Any descendant of .dark-theme will use the overridden value. This makes CSS variables the foundation of dark mode and multi-theme systems.

JavaScript Integration

CSS variables are readable and writable from JavaScript at runtime:

// Read a variable
const primary = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-primary').trim();

// Write a variable globally
document.documentElement.style.setProperty('--color-primary', '#4f46e5');

// Write scoped to an element
document.querySelector('.widget').style.setProperty('--color-primary', '#ec4899');

// Remove an override (falls back to :root value)
document.querySelector('.widget').style.removeProperty('--color-primary');

This enables powerful patterns: theme switchers, user-customizable color palettes, dynamic animation values, and A/B testing visual variants.

Fallback Values

var() accepts an optional second argument as a fallback:

color: var(--color-primary, #6366f1);
font-family: var(--font-sans, system-ui, sans-serif);

The fallback is used when the variable is not defined or has an invalid value. Fallbacks can themselves contain var() references, enabling chains of defaults.

Browser Support and Performance

CSS custom properties are supported in all modern browsers and have been since 2016 (Chrome 49, Firefox 31, Safari 9.1, Edge 16). No PostCSS plugin or polyfill is needed for modern projects.

Performance notes:

Declaring many variables in :root has negligible overhead
Changing a variable at runtime (via JavaScript) triggers re-style only for elements that use that variable — not a full page repaint
Variables are not interpolated in calc() in older browsers, but this is resolved in modern engines

Frequently Asked Questions

What is the naming convention for CSS variables? The most common convention is kebab-case with a category prefix: --color-primary, --spacing-lg, --font-sans. This mirrors the naming system in popular design tools (Figma tokens) and utility frameworks. Avoid starting names with digits or using camelCase.

Can CSS variables be used in media queries? Not directly — CSS variables cannot be used as media query values. Media queries are evaluated before variable substitution. However, you can use variables inside the rules within a media query, including overriding their values: @media (prefers-color-scheme: dark) { :root { --color-bg: #111827; } }.

Does this CSS variables generator work with Tailwind CSS 4? Yes. Tailwind CSS 4 uses CSS custom properties natively for its theme. You can paste the generated :root block into your CSS file alongside Tailwind’s @import. You can also use the generated variables with Tailwind’s arbitrary value syntax: bg-[var(--color-primary)].

How do CSS variables compare to Sass variables? Sass variables ($color-primary: #6366f1) are resolved at compile time and do not exist in the output CSS. They cannot be changed by JavaScript or overridden with the cascade. CSS custom properties exist in the browser at runtime and support all of these capabilities at the cost of slightly more verbose syntax.

Is my data sent to a server when using this tool? No. All CSS variable generation happens entirely in your browser using JavaScript. No data is transmitted to any server.

Related Tools

Color Converter

Convert between HEX, RGB, HSL and other color formats

CSS Gradient Generator

Create linear and radial CSS gradients with a visual editor

Box Shadow Generator

Build CSS box shadows visually with real-time preview

More CSS Tools

CSS Gradient Generator CSS Grid Generator CSS Flexbox Playground CSS Animation Generator CSS Keyframes Generator CSS Box Shadow Visual Builder View all →