# Darkmode > Dark mode implementation for Astro + Tailwind v4 — class-based toggle, FOUC-free init script, cookie/localStorage persistence, and contrast-safe light/dark token pairing. - Skill: `casoon/darkmode` (Agent Skill) - Install (CLI): `npx skillmds@latest add casoon/darkmode` - Raw SKILL.md: https://api.skillmd.com/api/skills/casoon/darkmode/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: casoon (https://skillmd.com/u/casoon) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/casoon/darkmode --- # Dark mode ## Activation ### Class-based (recommended — supports a toggle) Tailwind v4 custom variant in the CSS entry: ```css @custom-variant dark (&:where(.dark, .dark *)); ``` FOUC-free init script in `` — must be `is:inline` to run before paint: ```html ``` Re-registering on `astro:after-swap` matters for `ClientRouter` (SPA transitions) so the theme persists across navigations. ### OS-only (no toggle) Tailwind v4 uses `prefers-color-scheme` by default — no configuration needed, just use `dark:` utilities. ## Persistence ### Cookie ```javascript document.cookie = 'theme=' + value + ';path=/;max-age=31536000;SameSite=Lax'; ``` Technical cookie — no consent banner required (UI preference, not tracking). Add `domain=` only when cross-subdomain persistence is a real requirement. ### localStorage fallback ```javascript localStorage.setItem('theme', value); ``` ## Toggle ```javascript btn.addEventListener('click', function () { var isDark = document.documentElement.classList.toggle('dark'); var v = isDark ? 'dark' : 'light'; document.cookie = 'theme=' + v + ';path=/;max-age=31536000;SameSite=Lax'; try { localStorage.setItem('theme', v); } catch (e) {} }); ``` Use the Cookie Store API only if your target browsers support it. Plain `document.cookie` remains the compatibility path. ## CSS patterns ### Scoped styles (Astro / Svelte) ```css ``` ### Tailwind utilities ```html
``` ## Color guidelines | Principle | Light | Dark | |---|---|---| | Background | Warm off-white | Warm dark (never pure black) | | Text | Near-black | Off-white (never pure white) | | Borders | Light gray | Muted dark | | Accents | Adjust brightness | Lighten or warm up | ### Contrast minimums (WCAG AA) - Body text: 4.5:1. - Large text (≥ 18 px bold / 24 px): 3:1. - Interactive elements: 3:1. Both modes must independently meet these — see the accessibility-audit skill for full pairing tables. ## Logo handling ```html Logo ``` ## Common mistakes | Mistake | Fix | |---|---| | `#000` background | Use warm dark, e.g. `#1e2628`, `#222a2c` | | `#fff` text on dark | Use off-white, e.g. `#e6e1dc`, `#d2cdc8` | | Cold grays in dark mode | Use warm-tinted grays (teal/sand undertone) | | Same accent in both modes | Lighten or warm the accent on dark surfaces | | `@media (prefers-color-scheme)` inside scoped styles | Use `:global(html.dark)` for class-based toggle | | Forgetting `dark:border-*` | Borders are very visible in dark mode — always pair |