Theme & tokens

Every visual value in Joy runs through CSS custom properties. Override a token after loading joy-tokens.css and the whole system — buttons, cards, dock, modal — picks up the change.

Color tokens

Which one to reach for

Glass tokens

The translucent-blur look (topbar, dock, modal, .joy-glass from Cards & layout) is also token-driven:

Blur scale

Not tied to any single component — reach for these directly in your own CSS with backdrop-filter: blur(var(--joy-blur-md)) or similar:

Building your own theme

A theme override is just CSS loaded after joy-tokens.css that redefines some of its variables — no build step, no config file, no fork of the source. Here's a complete example: a purple brand color, plus a matching dark-mode variant:

:root {
    /* Light mode — loads after joy-tokens.css, before joy-dark.css */
    --joy-accent: #6d28d9;
    --joy-accent-hover: #5b21b6;
    --joy-accent-glow: rgba(109, 40, 217, 0.35);
    --joy-accent-soft: rgba(109, 40, 217, 0.1);
}

/* Dark mode — joy-dark.css only redefines color tokens under :root, with
   no extra selector guarding it (see "How the switch works" below), so
   your override needs the same specificity: plain :root, placed AFTER
   the <link id="joy-dark-theme"> tag in the <head> order. */
:root {
    --joy-accent-soft: rgba(109, 40, 217, 0.18);
}

Dark mode: how the switch actually works

joy-dark.css is a second stylesheet tag, always present in the page but starting disabled. Almost all of it is :root variable redefinitions — the same variable names as joy-tokens.css, different values — plus a small number of component-specific tweaks where a plain token swap wasn't enough (the background blobs, and the dock's selected-item text color). It never touches layout or spacing, so enabling it can't rearrange anything, only recolor it.

<link id="joy-dark-theme" rel="stylesheet" href="https://cdn.vaneltonmedia.com/joy/styles/joy-dark.css" disabled>

Toggling the theme is one line: flip that disabled attribute. JoyTheme.toggle() does exactly this, plus saves the choice:

Which tokens actually change between the two themes — everything else (spacing, radius, easing, accent unless you override it) stays identical:

No-flash-of-wrong-theme script — reads the saved choice before first paint and flips the attribute immediately, so there's no visible flicker on load. This goes right after the <link id="joy-dark-theme"> tag:

<script>(function(){var t=localStorage.getItem('selectedTheme')||(matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light');if(t==='dark'){document.getElementById('joy-dark-theme').disabled=false;}})();</script>

Spacing scale

Every margin/padding/gap utility in Sizing & spacing and Flexbox & grid maps to one of these — override the scale here and every one of those classes follows.

Border radius

Easing

Font

Everything uses --joy-font: 'Poppins', sans-serif;. To swap it, override the token and load whichever font you prefer instead of the Google Fonts link (see Getting started). For the full size scale — proportional steps and fixed-pixel options — see Typography.