CSS Academy · Lesson

CSS Variables for Theming

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

Lesson 2 of 413 steps

CSS Variables for Theming is a free CSS Academy lesson on CoddyKit. This is 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, and your progress syncs across the web and the CoddyKit app. The CSS Academy course includes 4 lessons in total.

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:

<div class="demo">Themed surface<br/><button class="btn">Primary Button</button></div>

Dark Theme Override

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

<div class="demo">Adapts to dark mode automatically</div>

Using Tokens in Components

Components use semantic tokens, never hardcoded values:

<div class="card">Card using theme tokens</div>

Class-Based Override

Allow manual override with a class on <html>:

<div data-theme="dark" class="demo">Dark theme via data-theme</div>
<div data-theme="light" class="demo">Light theme via data-theme</div>

Component-Level Theming

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

<div class="card">Component-level theming</div>

White-Label Theming

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

<div data-brand="client-a" class="brand-demo">Client A brand color</div>
<div data-brand="client-b" class="brand-demo">Client B brand color</div>

Transition Theme Changes

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

<div class="demo" id="theme-demo">Themed content</div>
<button onclick="document.documentElement.classList.toggle('theme-transitioning'); const d=document.getElementById('theme-demo'); const dark = d.style.background==='rgb(17, 17, 17)'; d.style.background = dark ? '#fff' : '#111'; d.style.color = dark ? '#111' : '#fff';">Toggle Theme (transitions smoothly)</button>

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?

Answer it in the interactive lesson

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.

Free to start

Learn CSS with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 40
Lessons: 159

Start learning free View the full course

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. 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. The CSS Academy course includes 4 lessons in total.

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, so you can start here or from the beginning and move at your own pace. This is lesson 2 of 4.

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