Building a CSS only design system with custom properties

Nov 30, 2024

CSS

Design system

Simplifying design system theming

After years of wrestling with theming solutions - SASS variables, CSS-in-JS, theme providers, utility frameworks - I've reached a conclusion:

We've drastically overcomplicated theming in modern web development.

Last week at RNL Conf, this hit home during a design systems discussion. The room had the classic framework talk. Tailwind for utilities. Material UI for Google's design language. Chakra for component-driven development. Styled Components for CSS-in-JS.

Each with the promise to solve all our theming problems. Each in my mind adds its own complexity.

An attendee asked about my experience. I shared our approach at my mid-sized company: CSS Modules for scoping. That's it.

The simplicity of this was in stark contrast to our previous discussion, but honestly I didn't and still don't know why all these tools are needed. Yes, we have developed an over-reliance on frameworks to handle what should be straightforward, and I say this as someone who adores Next.js.

But let's think about it for a second.

Our complex solutions emerged from a different era of web development:

SASS variables filled the gap before CSS had dynamic values
CSS-in-JS solved component-level styling
Utility classes sped up development
Theme providers added type safety and IDE support

Each solution solved problems of its time. But here's the key: the web platform has evolved. Our approaches should too.

Many of these tools predate the true power of custom properties and modern CSS features.

Let me show you something different: We can build a sophisticated theming system using just CSS custom properties.

No preprocessors. No JavaScript engines. No utility frameworks. Just modern CSS features that work in every major browser.

The approach is simple: define your base colour palettes as custom properties and use inheritance for theme switching.

Plan your variables thoughtfully. Build relationships carefully. The result? A clean, scalable system that grows with your application - no external dependencies needed.

First define your root styles✨

Let's start with the foundation of our theming system by setting up the root styles. This is where we'll define our colour palettes and establish the inheritance patterns. Here's a look at our abridged base CSS file:

app.css

/* Base color palettes */
:root {
  /* Blue palette */
  --blue-50: #eff6ff;
  --blue-500: #3182ce;
  --blue-700: #2b6cb0;
  --blue-x: /* Define as many shades as you need 50, 100 etc. -> 900 */;
  
  /* Green palette */
  --green-50: #f0fdf4;
  --green-500: #2f855a;
  --green-700: #276749;

  /* Neutral palette */
  --neutral-50: #f7fafc;
  --neutral-500: #718096;
  --neutral-700: #2d3748;
}

/* We set the primary style explicitly to blue, this will
    be our default and we can override it later at component level */
[data-theme="blue"] {
  --primary-50: var(--blue-50);
  --primary-500: var(--blue-500);
  --primary-700: var(--blue-700);
}

/* Want to switch to green? Just update the inheritance */
[data-theme="green"] {
  --primary-50: var(--green-50);
  --primary-500: var(--green-500);
  --primary-700: var(--green-700);
}

With something like this we are conceptually 90% of the way there, which is scary because most of us are used to really complex solutions to handle theming (Providers I'm looking at you).

Let's break down what's happening:

First, we define our base color palettes using CSS custom properties. Each color gets its own variable with a descriptive name following a consistent numbering system (50 for lightest, 900 for darkest).
Instead of applying these colors directly, we create an abstraction layer using data-theme attributes. This is the magic that makes our theming so flexible.
The data-theme selectors map our base palette variables to semantic theme variables (--primary-50, --primary-500, etc.). This simple layer of abstraction means we can swap entire themes by changing a single attribute. And this works at any level in our DOM tree.

Using it in your elements

Here's where it gets really nice. Your css just references the primary colors, and your elements will automatically adapt when you switch themes:

buttons.html

button.css

<body data-theme="blue">
  <div className="container">
    <button class="button">Click me</button> <!-- inherits from theme (blue by default) -->
  </div>
  <div className="container" data-theme="blue">
    <button class="button">Click me</button> <!-- inherits from container (blue) -->
  </div>
  <div className="container" data-theme="green"> 
    <button class="button">Click me</button> <!-- inherits from container (green) -->
    <button class="button" data-theme="blue">Click me</button> <!-- explicitly blue -->
  </div>
</body>

.button {
  appearance: none;
  background: var(--primary-500);
  color: white;
  box-shadow: 0 0 10px var(--neutral-500); /* Neutral color unaffected by theme */
  border-bottom: 2px solid var(--primary-700);
}

This setup gives us incredible flexibility:

By default, elements inherit their theme from the nearest parent with a data-theme attribute
You can override the theme at any level in your DOM tree
Components remain largely theme-agnostic, using only the semantic colour variables
Switching themes is as simple as changing a data-theme attribute

Demo

Here's an interactive demo of something similar in action. Click the square blocks or items to change their theme. You can see how the theme can be taken to the extreme granular level

Click on a block to change its theme

body[data-theme="blue"]

group

item

group

item

group

item

Why I like this approach

I've worked with a lot of different theming solutions over the years, and here's why I keep coming back to this pattern:

It's Simple: The inheritance chain is short and easy to follow. You can look at the CSS and understand exactly what's happening.
It's Flexible: Need to add a new color scheme? Just define your colors and add a new theme rule. No build step, no configuration files.
It's Fast: The browser handles all the color inheritance natively. No JavaScript calculations, no class swapping.
It's DRY: Your components reference primary colors once and automatically adapt to theme changes. No repeated color classes.
It's DevTools Friendly: You can inspect and modify colors right in your browser and you know where they come from. Try doing that with preprocessor variables or utility classes 🫠.

Change themes with minimal JavaScript

If you do need to switch themes, here's all the JavaScript required:

Change theme

function setTheme(theme) {
  document.documentElement.setAttribute('data-theme', theme);
}

// That's it. Want to switch themes?
setTheme('green'); // Go green
setTheme('blue'); // Back to blue

Extending to light and dark mode

The same principle works beautifully for light and dark themes. Here's how we can expand our system:

theme.css

component.css

:root {
  /* Light mode defaults */
  --background: var(--neutral-50);
  --text-primary: var(--neutral-900);
  --text-secondary:  var(--neutral-700);
  --surface: var(--neutral-100);
  --surface-accent: var(--neutral-200);
}

[data-mode="dark"] {
  /* Dark mode overrides */
  --background: var(--neutral-900);
  --text-primary: var(--neutral-50);
  --text-secondary:  var(--neutral-200);
  --surface: var(--neutral-800);
  --surface-accent: var(--neutral-700);
}

Just like with our colour schemes, components don't need to know about light or dark mode - they just reference the semantic variables.

The JavaScript remains just as simple:

setColorMode.ts

function setColorMode(mode) {
  document.documentElement.setAttribute('data-mode', mode);
}

// Toggle between modes
setColorMode('dark');  // Switch to dark mode
setColorMode('light'); // Switch to light mode

// Bonus: Respect user's system preference
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
  setColorMode('dark');
}

Beyond colors: a complete design System

While this CSS-only approach to theming is powerful, it's important to note that a complete design system needs much more than just colour variables. A robust design system typically includes at least the below

spacing.css

typography.css

layout.css

:root {
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 16px;
  --space-4: 24px;
  --space-5: 32px;
  --space-6: 48px;
  --space-7: 64px;
  --space-8: 96px;
}

:root {
  --font-family-base: system-ui, -apple-system, sans-serif;
  --font-family-heading: 'Your-Heading-Font', serif;

  --font-size-s: 12px;
  --font-size-base: 14px;
  --font-size-l: 18px;
  --font-size-xl: 20px;

  --line-height-tight: 1.25;
  --line-height-base: 1.5;
  --line-height-loose: 1.75;
}

:root {
  --container-max: 1280px;
  --container-padding: 32px;

  --grid-gap: 16px;
  --grid-columns: 12;

  --breakpoint-s: 640px;
  --breakpoint-m: 768px;
  --breakpoint-l: 1024px;
  --breakpoint-xl: 1280px;
}

Other important considerations for a complete design system include:

Animation timings and easing
Border radii and shadow scales
Z-index scale
Component-specific attributes

The power of composition

The real strength of using CSS custom properties comes when you combine all these systems. Here's an example of a card component that uses multiple token types:

card.css

card.html

:root {
  --shadow-s: 0 1px 3px rgba(0,0,0,0.12);
  --shadow-m: 0 4px 6px rgba(0,0,0,0.15);
  --radius-m: 8px;
  --animation-duration-base: 200ms;
  --animation-ease-out: cubic-bezier(0.4, 0, 0.2, 1);
}

.card {
  background: var(--surface);
  color: var(--text-primary);
  padding: var(--space-4);
  border-radius: var(--radius-m);
  font-family: var(--font-family-base);
  font-size: var(--font-size-base);
  line-height: var(--line-height-base);
  box-shadow: var(--shadow-s);
  transition: box-shadow var(--animation-duration-base) var(--animation-ease-out);
}

.card:hover {
  box-shadow: var(--shadow-m);
}

<div class="card">
  <h2 class="card-title">Card Title</h2>
  <p class="card-content">
    This card uses multiple design attributes including colors,
    spacing, typography, and animation values.
  </p>
</div>

While CSS custom properties make theming straightforward, a production-ready design system needs careful planning of all these variables and their relationships. The goal is to create a consistent, maintainable system that scales with your application's needs.

The future of theming is already here

The next time you reach for a complex theming solution, ask yourself: Do you really need it? Or could you achieve the same result with the powerful features already built into the web platform?