CSS Academy · Lesson

CSS Variables for Theming

Create a token-based theme system using CSS custom properties that swap between light and dark values.

CSS Variables for Theming is a free CSS Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the CSS Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Theming Architecture Overview

CSS custom properties are the foundation of modern CSS theming. They act as a live token layer that can be swapped at runtime — enabling dark mode, white-labeling, and user-controlled personalization.

Design Token Layers

A well-structured theme system has three layers:

Primitive tokens: raw values (--blue-500: #3b82f6)
Semantic tokens: meaning-based (--color-primary: var(--blue-500))
Component tokens: component-specific (--button-bg: var(--color-primary))

Defining the Light Theme

Define the complete light theme on :root:

:root {
  /* Surface */
  --color-bg-base: #ffffff;
  --color-bg-raised: #f8f9fa;
  --color-bg-overlay: #f0f1f2;

  /* Text */
  --color-text-primary: #111827;
  --color-text-secondary: #6b7280;

  /* Brand */
  --color-primary: #3b82f6;
  --color-primary-hover: #2563eb;
}

Dark Theme Override

Override tokens in a dark scope (media query or class):

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg-base: #111827;
    --color-bg-raised: #1f2937;
    --color-bg-overlay: #374151;
    --color-text-primary: #f9fafb;
    --color-text-secondary: #9ca3af;
    --color-primary: #60a5fa; /* lighter blue for dark bg */
    --color-primary-hover: #93c5fd;
  }
}

Using Tokens in Components

Components use semantic tokens, never hardcoded values:

.card {
  background: var(--color-bg-raised);
  color: var(--color-text-primary);
  border: 1px solid var(--color-border);
}

Class-Based Override

Allow manual override with a class on <html>:

[data-theme="dark"] {
  --color-bg-base: #111827;
  --color-text-primary: #f9fafb;
  /* ... */
}

[data-theme="light"] {
  --color-bg-base: #ffffff;
  --color-text-primary: #111827;
}

Component-Level Theming

A component can define its own token layer for deeper customization:

.card {
  --card-bg: var(--color-bg-raised);
  --card-text: var(--color-text-primary);
  --card-padding: 24px;

  background: var(--card-bg);
  color: var(--card-text);
  padding: var(--card-padding);
}

White-Label Theming

CSS variables enable white-label products where each client gets a different theme by overriding a small set of brand tokens:

[data-brand="client-a"] {
  --color-primary: #e63946;
  --color-secondary: #457b9d;
}

[data-brand="client-b"] {
  --color-primary: #2d6a4f;
  --color-secondary: #74c69d;
}

Transition Theme Changes

Smooth theme transitions can be achieved with a CSS transition on color-related properties:

html.theme-transitioning * {
  transition:
    background-color 200ms ease,
    border-color 200ms ease,
    color 100ms ease !important;
}

Token Documentation

Document your design tokens so all developers know which variables to use. A style guide component (like Storybook) that displays all tokens with their light/dark values is invaluable for large teams.

Token Tooling: Style Dictionary

Style Dictionary (by Amazon) transforms design tokens defined in JSON into CSS custom properties, JavaScript constants, and other platform formats automatically — keeping tokens in sync across design and code.

Quick Check

In a two-level token architecture, which token type should a .button component reference for its background color?

Recap

CSS variables power robust theming systems. Build three layers: primitive tokens, semantic tokens, and component tokens. Define themes as token overrides on :root via media query or attribute selector. Use semantic tokens in components for automatic theme inheritance. Tools like Style Dictionary automate token distribution across platforms.

Frequently asked questions

Is the “CSS Variables for Theming” lesson free?

Yes — the full text of “CSS Variables for Theming” is free to read here on the web, and the CSS Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the CSS Academy course, upgrade to CoddyKit PRO.

What will I learn in “CSS Variables for Theming”?

Create a token-based theme system using CSS custom properties that swap between light and dark values. You practise CSS Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start CSS Academy?

No prior experience is required. CSS Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “CSS Variables for Theming” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this CSS Academy lesson?

Yes. Every CSS Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to CSS Academy