Theming
Light and dark come from one attribute: data-theme="light|dark|system" on <html> or any subtree. Components read only tokens, so they switch by themselves; you never write dark-mode CSS for a component.
Usage
Use it when
- Setting up a page: put
class="lds"anddata-themeon<html>, and callrestoreTheme()before first paint so the saved choice is used without a flash. - Offering an appearance switch (Light, Dark, System) in settings or a sidebar footer.
- A region must stay dark (or light) regardless of the page: a code preview, a media player, a marketing band. Put
data-themeon that element only. - Writing project CSS on top of the system: use the tokens (
--bg-fill,--text-subtle,--line,--accent) so your additions switch with the theme.
Use something else when
- Showing a status (approved, overdue) with color: use Badge. Status colors come with words and an icon; never theme a region to signal state.
- Picking a view of the same content (not appearance): use Segmented control.
- A setting that turns a feature on or off: use Switch. Appearance has three values, so it is a segmented control, not a switch.
- Colors for data series: use Chart principles.
--series-1..4are already tuned per theme and fixed in order.
Where it goes. data-theme belongs on <html> for the page. The switch lives in settings, the account menu or the sidebar footer, never in the main toolbar. Scoped themes go on the outermost element of the region that should differ.
Examples
data-lds-theme. It switches this whole page and remembers the choice in localStorage.<div class="seg" role="group" aria-label="Appearance" data-lds-segmented style="width: 300px;"> <span class="seg__thumb"></span> <button class="seg__btn" aria-pressed="true" data-lds-theme="light"><span class="ic ic--sm" aria-hidden="true">light_mode</span> Light</button> <button class="seg__btn" aria-pressed="false" data-lds-theme="dark"><span class="ic ic--sm" aria-hidden="true">dark_mode</span> Dark</button> <button class="seg__btn" aria-pressed="false" data-lds-theme="system"><span class="ic ic--sm" aria-hidden="true">contrast</span> System</button> </div>
<div class="auto-grid" style="--min: 260px;">
<div class="lds" data-theme="light" style="padding: 20px; border-radius: var(--r-lg);">
<div class="card stack" style="--gap: 12px;">
<div class="cluster" style="justify-content: space-between;"><span class="card__title">Database Systems</span><span class="badge badge--success">Open</span></div>
<div class="progress"><span class="progress__fill" style="transform: scaleX(0.72);"></span></div>
<div class="cluster"><button class="btn btn--primary btn--md">Continue</button><button class="btn btn--secondary btn--md">Syllabus</button></div>
</div>
</div>
<div class="lds" data-theme="dark" style="padding: 20px; border-radius: var(--r-lg);">
<div class="card stack" style="--gap: 12px;">
<div class="cluster" style="justify-content: space-between;"><span class="card__title">Database Systems</span><span class="badge badge--success">Open</span></div>
<div class="progress"><span class="progress__fill" style="transform: scaleX(0.72);"></span></div>
<div class="cluster"><button class="btn btn--primary btn--md">Continue</button><button class="btn btn--secondary btn--md">Syllabus</button></div>
</div>
</div>
</div>restoreTheme() sets the attribute and returns the mode, so you can sync the switch.<html lang="en" class="lds" data-theme="light">
<head>
<link rel="stylesheet" href="css/lds.css">
<script type="module">
import { init, restoreTheme } from './js/lds.js';
const mode = restoreTheme(document.documentElement, 'light');
init();
</script>
</head><html lang="en" class="lds" data-theme="light">
<head>
<link rel="stylesheet" href="css/lds.css">
<script type="module">
import { init, restoreTheme } from './js/lds.js';
const mode = restoreTheme(document.documentElement, 'light');
document.querySelectorAll('[data-lds-theme]').forEach((b) => b.setAttribute('aria-pressed', String(b.getAttribute('data-lds-theme') === mode)));
init();
</script>
</head>Anatomy
| Part | What it is |
|---|---|
[data-theme="light"] | The default (also what :root gets with no attribute). |
[data-theme="dark"] | Dark tokens for this element and everything inside it. |
[data-theme="system"] | Follows the operating system through prefers-color-scheme, live. |
.lds | Required on the root (or subtree): base font, text color, canvas background, resets. A scoped theme needs .lds too, so it paints its own background. |
[data-lds-theme] | Optional. A button with data-lds-theme="dark" calls setTheme("dark") on click after init(). |
Variants and sizes
| Class or attribute | When |
|---|---|
light | Default. White canvas, groups on --bg-fill. |
dark | Near-black canvas (#0B0B0D). Same accent, lifted series colors, softer skeleton shine. |
system | Follows the OS and updates live when it changes. A good default for the switch once the person has seen both. |
Motion and microinteractions
- A theme change is instant on purpose.
setTheme()(throughswapTheme()) adds.lds-theme-swapto<html>for 120 ms, which setstransition: noneon everything, so colors do not fade in patches at different speeds. - The one exception is the segmented thumb, which still slides on
--spring-smoothover--d-smoothso the switch itself feels physical. - Reduced motion changes nothing here; the swap is already instant.
Accessibility
- Both themes meet the same contrast:
--text-subtleis 6.6:1 in light and 7.7:1 in dark;--accent-text6.7:1 and 9.4:1. Project colors must be checked in both. - The switch is a group of buttons with
aria-pressed(the segmented control), labelled "Appearance", with icon and text in each button. setThemedispatcheslds:themewith{ mode }on the root; use it to updatearia-pressedon switches thatinit()did not create.- Do not convey anything by theme alone; a scoped dark band still needs its own heading and text.
Do and don't
Do
- Use tokens for every color in project CSS so it follows the theme.
- Check every new screen in both light and dark before shipping.
- Set the theme before first paint with
restoreTheme()in the head.
Don't
- Write
@media (prefers-color-scheme: dark)rules for components; setdata-theme="system"instead. - Hard-code hex values or
#fffbackgrounds in project styles. - Animate the theme change with a long cross-fade.
Behavior and code
Plain HTML. setTheme(mode, root = document.documentElement) sets data-theme, saves it under localStorage key lds-theme and dispatches lds:theme. restoreTheme(root, fallback = "light") reads it back and returns the mode. swapTheme(fn) runs any DOM change with transitions held off for 120 ms. Buttons with data-lds-theme="light|dark|system" call setTheme after init().