Themes
A theme is a set of token values on :root or on a subtree, with a built-in dark theme and no theme JavaScript, store or Provider.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Palette
| Color | main | light | dark | contrast-text | soft | soft-text |
|---|---|---|---|---|---|---|
primary | ||||||
secondary | ||||||
error | ||||||
warning | ||||||
info | ||||||
success | ||||||
neutral |
Code
<!-- Each color has six tones; data-color picks one palette for a subtree. -->
{#each ['primary', 'secondary', 'error', 'warning', 'info', 'success', 'neutral'] as color (color)}
{#each ['main', 'light', 'dark', 'contrast-text', 'soft', 'soft-text'] as tone (tone)}
<span style="background: var(--slean-{color}-{tone})"></span>
{/each}
{/each}Typography
Code
<!-- data-typography applies one step of the scale (a font shorthand token) to any element. -->
<h1 data-typography="h4">Invoices</h1>
<p data-typography="overline">Billing</p>
<p data-typography="subtitle1">Harbor Studio</p>
<p data-typography="body2">Paid on 2 October 2026.</p>
<p data-typography="caption">Updated a minute ago</p>Elevation
Code
<!-- 0 none, 1 resting surfaces, 2 raised cards, 3 menus and popovers, 4 dialogs, 5 drawers
and toasts. Components read them through their defaults (--slean-card-elevation, …). -->
{#each [0, 1, 2, 3, 4, 5] as level (level)}
<div style="box-shadow: var(--slean-elevation-{level})">{level}</div>
{/each}Create a theme
A theme is one block of token overrides, unlayered so it wins over the package: the palette, --slean-spacing, --slean-radius, the typography scale, elevation and
component defaults such as --slean-button-radius. The token reference lists every value.
Code
<script lang="ts">
import './harbor.css'; // the block below
</script>
<div data-slean-theme="harbor">
<button type="button" data-slean="button">Publish</button>
<button type="button" data-slean="button" data-variant="outlined">Preview</button>
<input data-slean="input" aria-label="Title" placeholder="Focus me" />
<label><input type="checkbox" role="switch" data-slean="checkbox" checked /> Public</label>
<span data-slean="badge" data-color="primary">Draft</span>
<progress data-slean="progress" value="40" max="100" aria-label="Upload"></progress>
</div>/* harbor.css: one block of overrides. Here on a subtree (data-slean-theme); on :root it
* themes the whole application. */
[data-slean-theme='harbor'] {
--slean-primary-main: oklch(50% 0.11 195);
--slean-primary-dark: oklch(43% 0.11 195);
--slean-primary-contrast-text: oklch(100% 0 0);
--slean-primary-soft: oklch(95% 0.03 195);
--slean-primary-soft-text: oklch(38% 0.09 195);
--slean-field-radius: 0.25rem;
--slean-button-radius: 9999px;
--slean-typography-button-transform: uppercase;
--slean-card-elevation: var(--slean-elevation-0);
}
/* The same tokens for the dark theme, under the package's two dark conditions. */
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light'], .light) [data-slean-theme='harbor'] {
--slean-primary-main: oklch(72% 0.11 195);
--slean-primary-dark: oklch(65% 0.11 195);
--slean-primary-contrast-text: oklch(18% 0.02 195);
--slean-primary-soft: oklch(28% 0.05 195);
--slean-primary-soft-text: oklch(86% 0.07 195);
}
}
:is([data-theme='dark'], .dark) [data-slean-theme='harbor'] {
--slean-primary-main: oklch(72% 0.11 195);
--slean-primary-dark: oklch(65% 0.11 195);
--slean-primary-contrast-text: oklch(18% 0.02 195);
--slean-primary-soft: oklch(28% 0.05 195);
--slean-primary-soft-text: oklch(86% 0.07 195);
}The same block on :root, with every tone of the color and a dark palette:
/* A theme is one block of token overrides (packages/styles/README.md, "Create a theme").
* Unlayered rules win over the package's layers; there is no JavaScript. */
:root {
/* Brand color: the palette of one color has six tones. */
--slean-primary-main: oklch(52% 0.16 160);
--slean-primary-light: oklch(65% 0.13 160);
--slean-primary-dark: oklch(45% 0.16 160);
--slean-primary-contrast-text: oklch(100% 0 0);
--slean-primary-soft: oklch(95% 0.03 160);
--slean-primary-soft-text: oklch(40% 0.12 160);
/* Shape, spacing, type */
--slean-radius: 0.375rem;
--slean-spacing: 0.25rem;
--slean-font-sans: 'IBM Plex Sans', system-ui, sans-serif;
--slean-typography-button-transform: uppercase;
/* Component defaults */
--slean-button-radius: 9999px;
--slean-card-elevation: var(--slean-elevation-0);
}
/* Dark mode: the same tokens under the package's two dark conditions. */
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light'], .light) {
--slean-primary-main: oklch(66% 0.14 160);
--slean-primary-soft: oklch(28% 0.06 160);
--slean-primary-soft-text: oklch(86% 0.08 160);
}
}
[data-theme='dark'],
.dark {
--slean-primary-main: oklch(66% 0.14 160);
--slean-primary-soft: oklch(28% 0.06 160);
--slean-primary-soft-text: oklch(86% 0.08 160);
}Overriding tokens
Tokens live in the slean.tokens layer, so any unlayered declaration wins. Redefine
what you want on :root:
/* A theme is a set of token values. Redefine them on :root to retheme every primitive. */
:root {
--slean-primary-main: oklch(45% 0.13 150);
--slean-primary-dark: oklch(40% 0.13 150);
--slean-radius: 0.25rem;
--slean-font-sans: 'IBM Plex Sans', system-ui, sans-serif;
}Color and density in the markup
data-color selects the current color (--slean-color-main and its five
siblings) for an element and its subtree; every variant of every primitive is drawn from it. data-density changes the control heights of a whole region (Variants).
<!-- data-color picks the palette every variant is drawn from, on the element or a subtree. -->
<button type="button" data-slean="button" data-color="error">Delete</button>
<div data-color="success">
<span data-slean="badge" data-color="success">Paid</span>
<button type="button" data-slean="button" data-variant="outlined">Mark as sent</button>
</div>
<!-- data-density changes control heights and option rows for everything inside it. -->
<main data-density="compact">…</main>Theming a subtree
Put the overrides on any element and mark it with data-slean-theme (any value): the
aliases derived from --slean-primary-main (focus ring, focused field border and halo,
selected option, the current color) are recomputed only on theme scopes.
- Theme scopes:
data-slean-theme,data-theme, thelightanddarkclasses. - A palette token (
--slean-primary-main, the neutral scale, status colors) needs only:root; an alias such as--slean-control-bordermust also be overridden on the scope selectors.
Dark theme
| Condition | Theme |
|---|---|
| Nothing on the root | The system (prefers-color-scheme) |
data-theme="light" or .light on the root | Light |
data-theme="dark" or .dark on any element | Dark for that subtree |
The light block and both dark blocks set the same tokens(59); the package's static check fails when the dark blocks differ.
/* packages/styles/css/tokens.css, abridged. Every selector is zero-specificity; the source
* order decides inside the slean.tokens layer. */
@layer slean.tokens {
/* The light palette: the default, and any subtree marked data-theme="light" or .light. */
:where(:root, [data-theme='light'], .light) {
--slean-color-scheme: light;
/* … light values … */
}
/* Follows the system, unless the root forces light. */
@media (prefers-color-scheme: dark) {
:where(:root:not([data-theme='light'], .light)) {
--slean-color-scheme: dark;
/* … dark values … */
}
}
/* Forced: data-theme="dark" or class="dark", on the root or on any subtree. The two dark
* blocks are identical by contract. */
:where([data-theme='dark'], .dark) {
--slean-color-scheme: dark;
/* … the same dark values … */
}
/* The aliases (the current color, borders, the focus ring) are derived again on every scope. */
:where(:root, [data-theme], [data-slean-theme], .dark, .light) {
--slean-color-main: var(--slean-primary-main);
--slean-focus-ring-color: var(--slean-primary-main);
/* … */
}
}Following the system
The media query decides, so the first paint is in the right theme without JavaScript.
Forcing a theme
Write data-theme on <html>; store it if it should survive a
reload.
<!-- Force a theme for the whole document; leave the attribute off to follow the system. -->
<html lang="en" data-theme="dark">// A blocking script in <head>, before the first paint: no flash, no framework, no Provider.
try {
const theme = localStorage.getItem('theme');
if (theme === 'dark' || theme === 'light') document.documentElement.dataset.theme = theme;
} catch {
// Storage unavailable: the document follows the system.
}
// The toggle writes the attribute and the storage key. Primitives read the tokens; nothing else
// needs to know.
function setTheme(theme) {
document.documentElement.dataset.theme = theme;
localStorage.setItem('theme', theme);
}This site's toggle is that script (theme.js). The dark and light classes work the same way, so mode-watcher and Tailwind's
class-based dark variant need no bridge.
<!-- The class convention of mode-watcher and Tailwind's dark variant works as well. -->
<html lang="en" class="dark">
<!-- A region in the other theme: the attribute or the class on any element. -->
<aside data-theme="dark">…</aside>
<aside class="light">…</aside>Warning A class toggle that removes dark without adding light leaves the
system in charge: on a dark system the primitives turn dark on a light page. Add light (or data-theme="light") while the page is light.
Bridging a design system
Map the tokens to your variables on :root, unlayered; your own light and dark
values switch underneath. Map on the root, not on a wrapper without data-slean-theme, or aliases such as --slean-option-selected keep the root's
palette. The option-row tokens in the sample match a listbox that marks the chosen row with its check
alone.
/* An application with its own design system (shadcn, Tailwind variables): map the palette,
the aliases and the option rows once, on :root. Its own light and dark values switch under
them, so nothing follows the system behind the application's back. */
:root {
--slean-color-scheme: light;
--slean-surface: var(--popover);
--slean-fg: var(--foreground);
--slean-fg-muted: var(--muted-foreground);
--slean-border: var(--border);
--slean-border-strong: var(--input);
--slean-muted: var(--muted);
--slean-primary-main: var(--primary);
--slean-primary-soft: var(--accent);
--slean-primary-soft-text: var(--accent-foreground);
--slean-control-bg: var(--card);
--slean-control-border: var(--input);
--slean-option-active: var(--secondary);
--slean-option-active-fg: var(--secondary-foreground);
--slean-option-selected: var(--accent);
--slean-option-selected-fg: var(--accent-foreground);
--slean-option-selected-weight: 500;
--slean-option-selected-ring: none;
/* … the rest of the palette the primitives read … */
}
:root.dark {
--slean-color-scheme: dark;
}Native parts
Each primitive sets color-scheme from --slean-color-scheme: dialog
canvases and scrollbars follow the theme; the page's own color-scheme is untouched.
/* packages/styles/css/base.css: native parts (scrollbars, the dialog canvas) follow the theme
* of each primitive, and the page's own color-scheme is left alone. */
@layer slean.base {
:where([data-slean]) {
color-scheme: var(--slean-color-scheme);
}
}Presets
A preset is a stylesheet of token overrides, imported after the package. This one is ink on grey with tighter radii, like shadcn/ui's neutral theme:
/* A neutral preset: an ink accent on grey, smaller radii. Unlayered, so it wins over the
* package defaults; the dark block mirrors the package's own two dark conditions. */
:root {
--slean-primary-main: oklch(20.5% 0 0);
--slean-primary-dark: oklch(30% 0 0);
--slean-primary-contrast-text: oklch(98.5% 0 0);
--slean-primary-soft: oklch(95% 0 0);
--slean-primary-soft-text: oklch(20.5% 0 0);
--slean-radius: 0.5rem;
}
@media (prefers-color-scheme: dark) {
:root:not([data-theme='light'], .light) {
--slean-primary-main: oklch(92% 0 0);
--slean-primary-dark: oklch(85% 0 0);
--slean-primary-contrast-text: oklch(20.5% 0 0);
--slean-primary-soft: oklch(27% 0 0);
--slean-primary-soft-text: oklch(92% 0 0);
}
}
:root:is([data-theme='dark'], .dark) {
--slean-primary-main: oklch(92% 0 0);
--slean-primary-dark: oklch(85% 0 0);
--slean-primary-contrast-text: oklch(20.5% 0 0);
--slean-primary-soft: oklch(27% 0 0);
--slean-primary-soft-text: oklch(92% 0 0);
}The site as an example
Every primitive on this site takes its palette from one unlayered block mapping the package
tokens to the site's --site-* tokens; the package CSS is never edited (app.css).
/* sveltelean.dev, src/app.css: the site's own tokens are mapped onto the package tokens.
* Unlayered, so it wins over the slean.tokens layer; every primitive on this site inherits
* the site palette through this block and nothing else. The aliases are mapped on the theme
* scopes too, because the package derives them again there. */
:root,
[data-slean-theme] {
--slean-bg: var(--site-bg);
--slean-fg: var(--site-text);
--slean-fg-muted: var(--site-text-muted);
--slean-border: var(--site-border);
--slean-control-border: var(--site-border-control);
}
:root {
--slean-surface: var(--site-surface);
--slean-primary-main: var(--site-accent);
--slean-primary-dark: var(--site-accent-hover);
--slean-primary-contrast-text: var(--site-on-accent);
--slean-focus-ring-color: var(--site-accent);
--slean-font-sans: var(--site-font-sans);
--slean-radius-md: var(--site-radius-2);
}Forced colors
Under forced-colors: active the platform replaces most colors; the tokens map the rest
to system colors:
| Token | Value under forced colors |
|---|---|
--slean-focus-ring-color | Highlight |
--slean-border | CanvasText |
--slean-border-strong | CanvasText |
--slean-elevation-1 | none |
--slean-elevation-2 | none |
--slean-elevation-3 | none |
--slean-elevation-4 | none |
--slean-elevation-5 | none |
Component files add buttons' ButtonText border and GrayText for disabled
controls.
Reduced motion
Transitions drop to zero; the loading indicator's --slean-duration-indicator grows longer
instead, since a stopped ring reads as a stuck page. Components never write a raw duration (the static
check rejects one).
| Token | Value under reduced motion |
|---|---|
--slean-duration-fast | 0ms |
--slean-duration-normal | 0ms |
--slean-duration-slow | 0ms |
--slean-duration-indicator | 1600ms |
/* Component files never write a raw duration. A transition reads the token, so the
* reduced-motion block in tokens.css stops it without a second rule. */
:where([data-slean='dialog']) {
transition:
opacity var(--slean-duration-normal) var(--slean-ease),
scale var(--slean-duration-normal) var(--slean-ease);
}
/* A loading indicator (the circular progress, the busy button) reads its own token, which
* reduced motion slows instead of zeroing. */
:where([data-slean='progress'][data-variant='circular']:indeterminate) {
animation: slean-progress-rotate var(--slean-duration-indicator) linear infinite;
}Why there is no Provider
- Theme values are custom properties; the cascade delivers them.
- Behavior routing attaches to the document, not to component context.
- Trade-off: a theme computed from JavaScript values has to be written into custom properties by you.