Courses/HTML & CSS/CSS Custom Properties

CSS Custom Properties

Lesson 14 • Expert Track

What You'll Learn

Declare and use CSS variables with --name and var()

Global variables with :root vs scoped variables

Fallback values for missing variables

Build a light/dark theme switcher

Design tokens: colors, spacing, typography scales

Update CSS variables dynamically with JavaScript

💡 Think of It Like This

CSS variables are like paint swatches at a hardware store. Instead of writing "Pantone 2728 C" every time you want blue, you label it --brand-blue and reference that label everywhere. When the client wants a different blue, you change one swatch and every room in the house updates automatically.

1. Declaring & Using CSS Variables

CSS variables (officially called "custom properties") start with -- and are accessed with var().

Concept	Syntax	Example
Declare (global)	`:root { --name: value; }`	`--primary: #3b82f6;`
Declare (scoped)	`.card { --padding: 20px; }`	Only available inside .card
Use	`var(--name)`	`color: var(--primary);`
Fallback	`var(--name, fallback)`	`var(--accent, #f59e0b)`

CSS Variables Basics

See how one variable change updates an entire design system

Try it Yourself »

Code Preview

<!DOCTYPE html>
<html>
<head>
  <title>CSS Variables</title>
  <style>
    :root {
      /* Change these values to retheme everything! */
      --primary: #3b82f6;
      --primary-dark: #2563eb;
      --bg: #0f172a;
      --surface: #1e293b;
      --text: #e5e7eb;
      --text-muted: #94a3b8;
      --radius: 12px;
      --spacing: 20px;
    }

    * { box-sizing: border-box; margin: 0; padding: 0; }
    body {
      background: var(--bg);
      font-family: system-ui, sans-serif;
      color: va
...

2. Building a Theme Switcher

The most powerful use of CSS variables — define different themes and switch between them by changing a single attribute on the HTML element.

Light/Dark Theme Switcher

Toggle between themes with one CSS variable swap

Try it Yourself »

Code Preview

<!DOCTYPE html>
<html data-theme="light">
<head>
  <title>Theme Switcher</title>
  <style>
    /* LIGHT THEME (default) */
    :root, [data-theme="light"] {
      --bg: #f8fafc;
      --surface: #ffffff;
      --text: #1e293b;
      --text-muted: #64748b;
      --primary: #3b82f6;
      --border: #e2e8f0;
    }

    /* DARK THEME */
    [data-theme="dark"] {
      --bg: #0f172a;
      --surface: #1e293b;
      --text: #e5e7eb;
      --text-muted: #94a3b8;
      --primary: #60a5fa;
      --border
...

3. Design Tokens — Best Practices

Professional design systems organise variables into semantic tokens:

:root {
  /* Primitive tokens (raw values) */
  --blue-500: #3b82f6;
  --gray-900: #0f172a;

  /* Semantic tokens (what it means) */
  --color-primary: var(--blue-500);
  --color-bg: var(--gray-900);
  --button-bg: var(--color-primary);

  /* Scale tokens */
  --space-xs: 4px;
  --space-sm: 8px;
  --space-md: 16px;
  --space-lg: 24px;
  --space-xl: 32px;

  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.25rem;
  --text-xl: 1.5rem;
}

💡 Pro Tip: Use descriptive names like --button-bg instead of --blue. When you rebrand from blue to green, you won't need to rename variables everywhere.

⚠️ Common Mistakes

Naming variables after colours — --blue breaks when you rebrand. Use --primary instead.
Forgetting var() syntax — You must use var(--name) to access variables. Just writing --name won't work.
Not providing fallbacks — Use var(--primary, #3b82f6) as a safety net in case the variable is undefined.
Too many variables — Only create variables for values that repeat or need to be themeable. Not every value needs a variable.

🎉 Lesson Complete

You now know how to build maintainable, themeable CSS with custom properties:

✅ Declare with --name: value; in :root
✅ Use with var(--name) and provide fallbacks
✅ Build light/dark themes with [data-theme] selectors
✅ Use semantic design tokens for scalable design systems
✅ Update variables dynamically with JavaScript