Design Systems & CSS

A design system is what keeps a hundred components looking like they were built by one person on one afternoon, instead of forty people over three years. The mechanism that makes this practical in CSS is deceptively simple: variables. This chapter builds up from raw color values to a full token system with dark mode, and draws the line between styles that are safe to share and styles that must stay local.

CSS custom properties #

A CSS custom property (see MDN's reference) is a variable, declared with a double-dash prefix and read with var():

:root {
  --accent: #c1502e;
}

.button-primary {
  background: var(--accent);
}

The payoff isn't the syntax, it's where the value lives. Change --accent once, in one place, and every rule that reads var(--accent) updates. Compare that to a codebase where #c1502e is typed literally into forty different stylesheets — changing the brand color becomes a find-and-replace across the whole project, and you'll inevitably miss one.

Primitive tokens vs. semantic tokens #

A mature design token system has two layers, not one. The bottom layer is primitives: a raw scale of values with no opinion about what they're for — just "here are the oranges we use," numbered from light to dark. The layer above is semantic tokens: names that describe a role — "the color of a border," "the color of primary text" — and each one points at a primitive.

:root {
  --orange-40: #f3ddd0;
  --orange-60: #e8865b;
  --orange-70: #c1502e;
  --orange-80: #a3401f;

  --neutral-10: #faf7f2;
  --neutral-90: #241f1a;
}

:root {
  --bg-base: var(--neutral-10);
  --fg-1: var(--neutral-90);
  --accent: var(--orange-70);
  --accent-hover: var(--orange-80);
  --accent-soft: var(--orange-40);
}

Components should only ever reference semantic tokens, never primitives directly. A button reads var(--accent), not var(--orange-70). That indirection is what makes theming possible: if "accent" is redefined to point at a different primitive, or reassigned entirely under a different selector, every component that consumes --accent updates without a single line of component code changing.

Dark mode: reassigning tokens, not rewriting styles #

Because components only ever read semantic tokens, dark mode becomes a matter of reassigning those tokens under a different selector — not writing a second stylesheet, and not touching a single component:

[data-theme="dark"] {
  --bg-base: #16130f;
  --fg-1: #f4ede1;
  --accent: #e8865b;
  --border-default: #3d3325;
}

Toggling dark mode is then just setting an attribute on the root element:

document.documentElement.setAttribute("data-theme", "dark");

Every component that was already written against var(--bg-base) and var(--fg-1) repaints instantly. No component needed to know dark mode existed.

That single line is enough to demonstrate the token mechanism, but it's not enough for a real toggle. Two things are missing:

• It doesn't remember the choice. Without saving it somewhere (typically localStorage) and re-reading that value on the next page load, the theme silently resets to light every time the user comes back.
• It ignores the OS-level preference. Browsers expose the user's system-wide choice through a media query, prefers-color-scheme: dark. A theme picker should default to that preference before the user has made an explicit choice of their own, not hardcode light as the starting point.

const saved = localStorage.getItem("theme");
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const theme = saved ?? (prefersDark ? "dark" : "light");

document.documentElement.setAttribute("data-theme", theme);

function setTheme(next) {
  document.documentElement.setAttribute("data-theme", next);
  localStorage.setItem("theme", next);
}

Spacing and radius scales #

The same token approach applies to anything that benefits from consistency: spacing, corner radius, type size. Instead of every component inventing its own padding value, they all pick from a shared, small scale:

:root {
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;

  --radius-sm: 6px;
  --radius-md: 10px;
  --radius-lg: 16px;
}

.card {
  padding: var(--space-4);
  border-radius: var(--radius-md);
}
.modal {
  border-radius: var(--radius-lg);
}

A small, deliberate scale (four to eight steps) is a feature, not a limitation. It forces every component to align to the same rhythm instead of accumulating one-off values like 13px and 15px that only ever existed because someone eyeballed it once.

Shared stylesheet vs. scoped styles #

A design system needs exactly two kinds of CSS, and confusing them is the most common way a frontend's styles rot over time.

In a component framework, scoped styles are typically enforced by the build tool: it rewrites your selectors with a unique, generated attribute so .title in NoteCard.vue can never collide with .title in SettingsPanel.vue, even though both files use the exact same class name.

<style scoped>
.title {
  font-weight: 600;
  color: var(--fg-1);
}
</style>