Chapter 12: Custom Properties (CSS Variables)

Define values once and reuse them everywhere with CSS custom properties

Dania Rifki

Table of content

Defining and using custom properties
Fallback values
Scoping
Building a token system

It seems that your browser JavaScript is disabled, LibDoc is set to fallback mode with reduced features.

Custom properties (often called CSS variables) are one of the most powerful features in modern CSS. They let you define values once and reuse them everywhere. For artists, they're the equivalent of defining a color palette before you start painting.

Defining and using custom properties

Custom properties start with -- and are accessed with var(). This is your first encounter with a CSS function: a name followed by parentheses that takes an input and produces a result. You'll see several CSS functions throughout this guide: var(), clamp(), min(), oklch(), and others. They all follow the same pattern: function-name(inputs).

Here's how custom properties work:

:root {
  --color-primary: #120A8F;
  --color-accent: #E97451;
  --font-body: "Georgia", serif;
}

h1 {
  color: var(--color-primary);
}

a {
  color: var(--color-accent);
}

body {
  font-family: var(--font-body);
}

The :root selector targets the top-level element of the document (effectively <html>). Defining custom properties here makes them available everywhere on the page.

Fallback values

The var() function accepts a second argument as a fallback:

.card {
  padding: var(--card-padding, 1.5rem);
}

If --card-padding isn't defined, it falls back to 1.5rem. This is useful for creating flexible components that can be customized from the outside but have sensible defaults.

Remember the color swatch example from the HTML guide?

<p>Available in <span class="color-swatch" style="--swatch: #120A8F">ultramarine</span> and <span class="color-swatch" style="--swatch: #E97451">burnt sienna</span>.</p>

Each <span> sets a --swatch custom property via an inline style attribute. The CSS can then use that value with a fallback:

.color-swatch {
  background-color: var(--swatch, currentColor);
}

Setting a custom property in HTML and consuming it with var() in CSS is one of the most practical reasons to use <span> and inline styles. The HTML provides the data, the CSS decides what to do with it.

Scoping

Custom properties follow the cascade and inheritance, which means you can redefine them in a smaller scope:

:root {
  --color-bg: #ffffff;
  --color-text: #1a1a1a;
}

[data-theme="dark"] {
  --color-bg: #1a1a1a;
  --color-text: #f0f0f0;
}

<body>
  <section>
    <p>This text is dark on light.</p>
  </section>

  <section data-theme="dark">
    <p>This text is light on dark.</p>
  </section>
</body>

Every element inside [data-theme="dark"] inherits the overridden values. The same CSS properties (color: var(--color-text), background: var(--color-bg)) produce completely different results depending on context. This is the foundation of theming, and it's incredibly elegant.

Click a button to toggle data-theme="dark" on a section and watch the same CSS produce a completely different look. (Uses JavaScript for the toggle button.)

Scoped theming demo

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Scoped Theming Demo</title>
  <style>
    :root {
      --color-bg: #ffffff;
      --color-text: #1a1a2e;
      --color-heading: #120A8F;
      --color-link: #E97451;
      --color-surface: #f8f9fa;
    }

    [data-theme="dark"] {
      --color-bg: #1a1a2e;
      --color-text: #f0f0f0;
      --color-heading: #a29bfe;
      --color-link: #fdcb6e;
      --color-surface: #2d2d44;
    }

    /*
      Page scaffolding only, not part of the demo.
    */
    body {
      font-family: system-ui, sans-serif;
      margin: 0;
      padding: 1rem;
      line-height: 1.6;
    }

    .toggle-bar {
      text-align: center;
      padding: 1rem;
      margin-block-end: 1.5rem;
    }

    .toggle-bar button {
      padding: 0.5rem 1.5rem;
      border: 2px solid #6c5ce7;
      background: white;
      border-radius: 2rem;
      cursor: pointer;
      font: inherit;
      font-weight: 600;
    }

    section {
      background: var(--color-bg);
      color: var(--color-text);
      padding: 2rem;
      border-radius: 0.5rem;
      margin-block-end: 1rem;
    }

    @media (prefers-reduced-motion: no-preference) {
      section {
        transition: color 300ms ease, background-color 300ms ease;
      }
    }

    section h2 {
      color: var(--color-heading);
      margin-block-start: 0;
    }

    section a {
      color: var(--color-link);
    }

    section .card {
      background: var(--color-surface);
      padding: 1rem;
      border-radius: 0.5rem;
      margin-block-start: 1rem;
    }

    h1,
    .intro {
      text-align: center;
    }

    .intro {
      color: #666;
    }

    .demo-note {
      font-size: 0.875rem;
      color: #6c757d;
      font-style: italic;
      padding: 1rem;
      background: #f8f9fa;
      border-radius: 0.5rem;
      margin: 1rem 0;
    }
  </style>
</head>

<body>
  <main>
    <h1>Scoped Theming with Custom Properties</h1>
    <p class="intro">Both sections use the <em>exact same CSS</em>. Only the <code>data-theme</code> attribute changes.
    </p>

    <div class="toggle-bar">
      <button type="button" id="themeToggle">Toggle dark theme on second section</button>
    </div>

    <section>
      <h2>Light Section (default)</h2>
      <p>This section inherits the default custom property values. <a href="#">Links look like this.</a></p>
      <div class="card">
        <p>Cards use <code>--color-surface</code> for their background.</p>
      </div>
    </section>

    <section id="darkSection">
      <h2>Second Section</h2>
      <p>Click the button above to apply <code>data-theme="dark"</code> to this section. <a href="#">Links adapt
          too.</a></p>
      <div class="card">
        <p>The same CSS, completely different appearance.</p>
      </div>
    </section>

    <script>
      document.getElementById('themeToggle').addEventListener('click', () => {
        const section = document.getElementById('darkSection');
        if (section.dataset.theme === 'dark') {
          delete section.dataset.theme;
        } else {
          section.dataset.theme = 'dark';
        }
      });
    </script>

    <p class="demo-note">This demo uses JavaScript for the interactive controls. The CSS concepts being demonstrated don't
      require JavaScript.</p>
  </main>
</body>

</html>

Enable

Open

Enable

Width: -px
Height: -px

Building a token system

Custom properties really shine when you use them to build a system of values. Rather than picking colors and sizes ad hoc, you define a set of design tokens, named values (a color, a size, a font) that you reference by name instead of by their raw value:

:root {
  /* Colors (using OKLCH, which I'll explain in the next chapter) */
  --color-primary: oklch(30% 0.19 268);
  --color-accent: oklch(69% 0.15 37);
  --color-light: oklch(97% 0.005 264);
  --color-dark: oklch(20% 0.02 264);

  /* Font families */
  --font-heading: "Garamond", serif;
  --font-body: "Verdana", sans-serif;

  /* A fluid type scale (we'll generate these properly in Chapter 15) */
  --step-0: 1rem;
  --step-1: 1.25rem;
  --step-2: 1.563rem;
  --step-3: 1.953rem;

  /* A spacing scale */
  --space-s: 0.75rem;
  --space-m: 1.5rem;
  --space-l: 3rem;
}

Once defined, these tokens become the vocabulary of your entire design. You never write a raw color value or a magic number in your component styles. Everything references a token:

h1 {
  font-family: var(--font-heading);
  font-size: var(--step-3);
  color: var(--color-primary);
}

section + section {
  margin-block-start: var(--space-l);
}

Change custom property values with color pickers and watch the entire page update in real time. This is the "aha" moment for design tokens. (Uses JavaScript for the interactive controls.)

Live token system demo

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Live Token System Demo</title>
  <style>
    :root {
      --color-primary: #120A8F;
      --color-accent: #E97451;
      --color-bg: #fafafa;
      --color-text: #1a1a2e;
      --font-heading: Georgia, serif;
      --font-body: system-ui, sans-serif;
    }

    /*
      max-width, margin, padding, line-height and transition are page scaffolding.
      The rest of the body rule is part of the demo: it shows how tokens
      defined in :root get consumed by real CSS properties.
    */
    body {
      font-family: var(--font-body);
      color: var(--color-text);
      background: var(--color-bg);
      max-width: 50rem;
      margin: 0 auto;
      padding: 1rem;
      line-height: 1.6;
    }

    .controls {
      background: #f0f0f0;
      padding: 1.25rem;
      border-radius: 0.5rem;
      margin-block: 1.5rem;
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr));
      gap: 1rem;
    }

    .control label {
      display: block;
      font-size: 0.8rem;
      font-weight: 600;
      font-family: monospace;
      margin-block-end: 0.25rem;
    }

    .control input[type="color"] {
      width: 100%;
      height: 2rem;
      border: 1px solid #ccc;
      border-radius: 0.25rem;
      cursor: pointer;
    }

    .preview {
      border: 2px dashed #ddd;
      border-radius: 0.5rem;
      padding: 2rem;
      margin-block: 1rem;
    }

    .preview h2 {
      font-family: var(--font-heading);
      color: var(--color-primary);
      margin: 0 0 0.5rem;
    }

    .preview a {
      color: var(--color-accent);
    }

    @media (prefers-reduced-motion: no-preference) {
      body {
        transition: color 300ms ease, background-color 300ms ease;
      }

      .preview h2 {
        transition: color 300ms ease;
      }

      .preview a {
        transition: color 300ms ease;
      }
    }

    .preview .card {
      border: 1px solid #ddd;
      border-radius: 0.5rem;
      padding: 1rem;
      margin-block-start: 1rem;
      background: white;
    }

    .demo-note {
      font-size: 0.875rem;
      color: #6c757d;
      font-style: italic;
      padding: 1rem;
      background: #f8f9fa;
      border-radius: 0.5rem;
      margin: 1rem 0;
    }
  </style>
</head>

<body>
  <main>
    <h1>Live Token System</h1>
    <p>Change the custom property values below and watch the entire page update. This is the power of design tokens:
      change once, update everywhere.</p>

    <div class="controls">
      <div class="control">
        <label for="primary">--color-primary</label>
        <input type="color" id="primary" value="#120A8F">
      </div>
      <div class="control">
        <label for="accent">--color-accent</label>
        <input type="color" id="accent" value="#E97451">
      </div>
      <div class="control">
        <label for="bg">--color-bg</label>
        <input type="color" id="bg" value="#fafafa">
      </div>
      <div class="control">
        <label for="text">--color-text</label>
        <input type="color" id="text" value="#1a1a2e">
      </div>
    </div>

    <div class="preview">
      <h2>Selected Works</h2>
      <p>A collection of recent paintings. <a href="#">View the full gallery</a> for more.</p>
      <div class="card">
        <h3 style="color: var(--color-primary); font-family: var(--font-heading); margin: 0 0 0.25rem;">Harbor Study No.
          3</h3>
        <p style="margin: 0;">Oil on panel, 30 x 40 cm. <a href="#">View details</a></p>
      </div>
    </div>

    <script>
      const root = document.documentElement;
      document.getElementById('primary').addEventListener('input', e => root.style.setProperty('--color-primary', e.target.value));
      document.getElementById('accent').addEventListener('input', e => root.style.setProperty('--color-accent', e.target.value));
      document.getElementById('bg').addEventListener('input', e => root.style.setProperty('--color-bg', e.target.value));
      document.getElementById('text').addEventListener('input', e => root.style.setProperty('--color-text', e.target.value));
    </script>

    <p class="demo-note">This demo uses JavaScript for the interactive controls. The CSS concepts being demonstrated don't
      require JavaScript.</p>
  </main>
</body>

</html>

Enable

Open

Enable

Width: -px
Height: -px

This has practical benefits (change a color in one place, it updates everywhere) but it also has a design benefit: it forces you to work within a system. Every value is intentional. Nothing is arbitrary. Artists who work with limited palettes or strict grid systems will find this idea familiar.

We'll flesh out these tokens properly in Chapter 15 when I introduce fluid scales from Utopia. For now, the important thing is the pattern: define your system as custom properties, then reference those properties everywhere.