light-dark-mode
Implement, fix or audit light/dark mode on any website or web app, on any stack (static HTML, Astro, Vite/React, Next.js, SvelteKit, Vue): a data-theme attribute on the html element, semantic CSS variables with a dark override block, a blocking boot script so there is no flash of the wrong theme, a small controller for localStorage, OS preference, browser chrome color and cross-tab sync, and an accessible toggle or Light/Dark/System control. Use whenever the user asks for dark mode, a theme toggle or switcher, prefers-color-scheme, data-theme, color-scheme, theme-color, a flash of the wrong theme on load, dark mode for code blocks, canvas or images, or says the site "should follow the system theme", even if they only say "add a dark version". Not for Quantum Design token files (`system-light.json`, `system-dark.json`), which belong to the `quantum-design-tokens` skill.
glrodasz · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add glrodasz/dotfiles --skill light-dark-modeAbout this skill
name: light-dark-mode
description: >
Implement, fix or audit light/dark mode on any website or web app, on any stack (static
HTML, Astro, Vite/React, Next.js, SvelteKit, Vue): a data-theme attribute on the html
element, semantic CSS variables with a dark override block, a blocking boot script so
there is no flash of the wrong theme, a small controller for localStorage, OS
preference, browser chrome color and cross-tab sync, and an accessible toggle or
Light/Dark/System control. Use whenever the user asks for dark mode, a theme toggle or
switcher, prefers-color-scheme, data-theme, color-scheme, theme-color, a flash of the
wrong theme on load, dark mode for code blocks, canvas or images, or says the site
"should follow the system theme", even if they only say "add a dark version". Not for
Quantum Design token files (system-light.json, system-dark.json), which belong to
the quantum-design-tokens skill.
Light/Dark Mode
One mechanism for every site: the resolved theme lives in data-theme on <html>,
colors live in CSS variables, and an inline script sets the attribute before first
paint. Components never know which theme is active; they read variables, and the
variables change under them.
If the project uses Quantum Design tokens (system-light.json / system-dark.json,
--components-tokens--* variables), quantum-design-tokens owns the token files and the
boot script (its Phase 3). Skip Phases 3 and 4 here and keep that boot script, upgrade its
toggle in Phase 6 instead of adding a second one, read theme-color from a component
token instead of a literal, and do everything else.
Hard rules (never violate)
- One attribute.
<html data-theme="light|dark">is the only switch. Never a.darkclass somewhere else, a theme prop threaded through components, or two mechanisms side by side. - Three preferences, two themes. The stored preference is
light,darkorsystem. What lands on<html>is always resolved tolightordark. Resolution order: stored choice → the default (normallysystem, which means the OS setting) → light. - Colors are variables. Light values on
:root, [data-theme="light"], dark overrides on[data-theme="dark"], each block with its owncolor-scheme. Any literal color outside the token block is a bug. - No flash. A blocking inline script in
<head>, ahead of every stylesheet, sets the attribute and thetheme-colormeta. Hydration only takes over from it. - Validate what you read. Storage can hold anything or throw. Accept only the three values; wrap every storage access in try/catch.
- Follow the OS live only while the preference is
system. An explicit choice wins until the user changes it. - One set of constants. Storage key, default preference and
theme-colorvalues are identical in the boot script and the controller. In SSR frameworks, build the boot script string from the same constants. - Everything follows. Native controls and scrollbars (
color-scheme), the mobile browser bar (theme-color), code blocks, canvas, images and Storybook switch too.
Phase 1 — Inspect
- Stack and where the document
<head>is authored:index.html,BaseHead.astro,_document.tsx,app/layout.tsx,app.html, a template partial. - Existing mechanisms: grep for
prefers-color-scheme,data-theme,.dark,color-scheme,theme-color,next-themes,darkMode,localStorage+theme. - Hardcoded colors in component CSS/JS:
#hex,rgb(,hsl(, Tailwind palette classes (bg-white,text-gray-900). - Things that won't follow CSS variables: syntax highlighting,
<canvas>/WebGL/chart libraries,<picture>sources, iframes, inline SVG with fills. - A Content-Security-Policy that blocks inline scripts (needs a nonce or hash).
If a maintained library already does this (for example next-themes with
attribute="data-theme"), keep it, check it against the hard rules, and do only the
missing steps. Don't add a second mechanism.
Phase 2 — Decide (ask only if the user hasn't said)
| Decision | Default | Alternative |
|---|---|---|
| Default preference | system (follow the OS until the user picks) | light for products whose design is light-first; only an explicit System choice follows the OS |
| Control | Two-state toggle in the header (flips what is on screen and stores it) | Light / Dark / System segmented control in settings |
| Storage key | theme | <app>:theme when several apps share one origin |
| Signed-in sync | none | Save the preference on the user profile so it follows them across devices |
Phase 3 — CSS tokens
Primitives first, then semantic tokens that point at them. Components only use the semantic ones.
:root {
/* Primitives (theme-independent) */
--gray-0: #ffffff;
--gray-50: #f4f6f8;
--gray-400: #9aa4ad;
--gray-500: #6b7680;
--gray-600: #59636c;
--gray-800: #1f262c;
--gray-900: #121212;
--brand-500: #2a9dad;
--brand-600: #1c7480;
}
/* Light: the default, and the fallback for any token the dark block omits */
:root,
[data-theme="light"] {
color-scheme: light;
--color-bg: var(--gray-50);
--color-surface: var(--gray-0);
--color-text: var(--gray-800);
--color-text-muted: var(--gray-600);
--color-border: var(--gray-500);
--color-accent: var(--brand-600);
--shadow: 0 2px 8px rgb(0 0 0 / 0.12);
}
[data-theme="dark"] {
color-scheme: dark;
--color-bg: var(--gray-900);
--color-surface: var(--gray-800);
--color-text: var(--gray-50);
--color-text-muted: var(--gray-400);
--color-border: var(--gray-500);
--color-accent: var(--brand-500);
--shadow: 0 2px 8px rgb(0 0 0 / 0.4);
}
body {
background: var(--color-bg);
color: var(--color-text);
}
Rules:
- The dark block overrides colors (and color-carrying values like shadows) only. Spacing, type and radius never change per theme.
[data-theme="light"]sits in the light s