How to Use CSS Variables

Use CSS variables when the same colors, spacing, sizes, or shadows repeat across multiple components. They help you update a design system faster without editing the same value in many places.

What you’ll build or solve

You’ll learn how to use CSS variables with --custom-properties and var(). You’ll also know how to define reusable design values once and apply them across buttons, cards, forms, and layouts.

When this approach works best

This approach is the right choice when multiple components share the same visual values.

Common real-world scenarios include:

• Brand colors
• Reusable spacing values
• Border radius tokens
• Shadow presets
• Dark mode theme switching

This is a bad idea when a value is used only once and the variable name adds more complexity than clarity.

Prerequisites

You only need:

• A basic HTML and CSS file
• A text editor
• Basic CSS knowledge

Step-by-step instructions

Step 1: Define reusable variables and apply them with var()

Start by defining variables in :root so they are available globally.

<button class="cta">Start lesson</button>

<style>
  :root {
    --brand-blue: #0057ff;
    --button-radius: 8px;
    --space-md: 16px;
  }

  .cta {
    background: var(--brand-blue);
    padding: var(--space-md);
    border-radius: var(--button-radius);
    color: white;
  }
</style>

You can also override variables inside a specific component.

<div class="promo-card">Featured plan</div>

<style>
  .promo-card {
    --brand-blue: #003bb3;
    background: var(--brand-blue);
  }
</style>

What to look for:

• Variable names start with --
• :root makes them global
• Use var(--name) to read the value
• Component-level overrides are great for themes and variants
• Use clear naming based on purpose, not random color names

Examples you can copy

Reusable colors

<style>
  :root {
    --primary-color: #111827;
  }

  h1 {
    color: var(--primary-color);
  }
</style>

Shared spacing

<style>
  :root {
    --space-lg: 24px;
  }

  .card {
    padding: var(--space-lg);
  }
</style>

Radius token

<style>
  :root {
    --radius-md: 12px;
  }

  .button {
    border-radius: var(--radius-md);
  }
</style>

Common mistakes and how to fix them

Mistake 1: Forgetting the -- prefix

What the reader might do:

:root {
  brand-blue: #0057ff;
}

Why it breaks: CSS variables must start with --.

Corrected approach:

:root {
  --brand-blue: #0057ff;
}

Mistake 2: Using the variable name without var()

What the reader might do:

.button {
  background: --brand-blue;
}

Why it breaks: CSS expects var() to read the stored value.

Corrected approach:

.button {
  background: var(--brand-blue);
}

Mistake 3: Naming variables by exact appearance only

What the reader might do:

:root {
  --blue-color: #0057ff;
}

Why it breaks: if the design changes to purple, the name becomes misleading.

Corrected approach:

:root {
  --primary-action-color: #0057ff;
}

Name by purpose whenever possible.

Troubleshooting

If the variable does not apply, confirm the name starts with --.

If the style still fails, wrap the variable in var().

If a component override does not work, check CSS specificity and selector scope.

If naming becomes messy, switch to design-token style names like --space-md or --radius-sm.

Quick recap

• Define variables with --name
• Put shared values in :root
• Read them with var()
• Override locally for variants
• Name variables by purpose, not color alone