Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

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-mode

About 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)

  1. One attribute. <html data-theme="light|dark"> is the only switch. Never a .dark class somewhere else, a theme prop threaded through components, or two mechanisms side by side.
  2. Three preferences, two themes. The stored preference is light, dark or system. What lands on <html> is always resolved to light or dark. Resolution order: stored choice → the default (normally system, which means the OS setting) → light.
  3. Colors are variables. Light values on :root, [data-theme="light"], dark overrides on [data-theme="dark"], each block with its own color-scheme. Any literal color outside the token block is a bug.
  4. No flash. A blocking inline script in <head>, ahead of every stylesheet, sets the attribute and the theme-color meta. Hydration only takes over from it.
  5. Validate what you read. Storage can hold anything or throw. Accept only the three values; wrap every storage access in try/catch.
  6. Follow the OS live only while the preference is system. An explicit choice wins until the user changes it.
  7. One set of constants. Storage key, default preference and theme-color values are identical in the boot script and the controller. In SSR frameworks, build the boot script string from the same constants.
  8. 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)

DecisionDefaultAlternative
Default preferencesystem (follow the OS until the user picks)light for products whose design is light-first; only an explicit System choice follows the OS
ControlTwo-state toggle in the header (flips what is on screen and stores it)Light / Dark / System segmented control in settings
Storage keytheme<app>:theme when several apps share one origin
Signed-in syncnoneSave 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
Read the complete source ↗