automatic OS-driven dark mode on every web frontend (authd, buchinese, dashcam #17

New Issue

brendan · 2026-05-13T19:02:10Z

brendan commented

2026-05-13 19:02:10 +00:00

Originally filed: 2026-05-11 in ~/features.md, block #11.
Cross-project companion issues: brendan/authd, brendan/buchinese, brendan/dashcam, brendan/inventory, brendan/movement

2026-05-11 — cross-project: automatic OS-driven dark mode on every web frontend (authd, buchinese, dashcam, inventory, movement, nanodrop) — no in-app toggle, no preference persistence, purely prefers-color-scheme media-query driven

User wants every bchen.dev web app to follow the device's system theme automatically. When the OS (iOS, macOS, Android, Windows, Linux desktop) is in dark mode, the app renders in dark mode; when light, light. No toggle switch anywhere in the UI. No setting, no cookie, no localStorage, no per-account preference — the only input is @media (prefers-color-scheme: dark). If the user changes their system theme, the app updates live (browsers re-evaluate the media query on theme change with no reload needed).

Source request (verbatim from user): "file automatic dark mode as a feature request for every app. no need for a toggle switch anywhere, just have it be automatic based on device theming"

Apps in scope (one PR per app — these ship independently and don't share CSS):

~/authd/public/style.css + login/account/oauth-consent HTML pages
~/buchinese/public/style.css + articles list/new/view HTML pages
~/dashcam/public/style.css (single shared stylesheet, server-rendered via src/views/layout.ts)
~/inventory/public/style.css + all HTML pages under public/ (login, index, item, items-new, oauth-clients, oauth-consent, api-tokens). Note: inventory already has /icon-color-scheme.js for the PWA home-screen icon swap — that's icon-only and unrelated; the CSS work is still needed.
~/movement/src/client/styles/main.css + popover.css (and any other stylesheets under src/client/styles/)
~/nanodrop/public/style.css

Out of scope this round (no web frontend, or N/A): portman, tradebot, fleet (CLI/supervisor), the roles/ docs.

Implementation approach (apply to every app; details may vary by stylesheet):

Declare both schemes to the browser. Add <meta name="color-scheme" content="light dark"> to every served HTML page's <head>. This tells the browser the page supports both modes and lets it pick sensible defaults for form controls, scrollbars, and the initial paint background before CSS loads (prevents the "white flash on dark OS" problem). In server-rendered layouts (dashcam src/views/layout.ts, movement client) add it there once; in static HTML files (authd/buchinese/inventory/nanodrop public/*.html) add to each file. Verify there is no existing <meta name="color-scheme" content="light"> that would block this — if so, change it to light dark.
Refactor each stylesheet to CSS custom properties. Replace hardcoded colors with var(--name) references. Define the light-mode palette under :root { ... } and the dark-mode palette under @media (prefers-color-scheme: dark) { :root { ... } }. Minimum variable set per app (extend as the design needs):
- --bg (page background)
- --bg-elevated (cards, panels, modals)
- --fg (primary text)
- --fg-muted (secondary text, labels, hints)
- --border (dividers, input borders)
- --accent (primary buttons, links)
- --accent-fg (text on accent backgrounds)
- --danger (destructive buttons, error text) + --danger-fg
- --success (where used) + --success-fg
- Form control background/text/border (--input-bg, --input-fg, --input-border)
Pick the dark palette carefully — don't just invert. True-black (#000) on OLED looks dramatic but causes haloing around text; aim for a soft near-black like #0f1115 or #111827 for --bg and #1a1d23 / #1f2937 for --bg-elevated. Text should be off-white (#e5e7eb / #f3f4f6), not pure white. Accent color often needs a saturation/brightness bump in dark mode to keep contrast — e.g. an accent that's #2563eb on light might become #3b82f6 on dark. Verify WCAG AA contrast (4.5:1 for body text, 3:1 for large text) for every color pair using a tool like https://webaim.org/resources/contrastchecker/ or npx wcag-contrast-check.
Form controls — the input/textarea/select { font-size: 16px } rule from the global CLAUDE.md still applies and is orthogonal to dark mode; do NOT regress it. For dark mode specifically, set --input-bg, --input-fg, --input-border and apply them. Browser-native controls (<input type="date">, <select>) will mostly take care of themselves once color-scheme: light dark is in <meta>, but verify their popups look right on both iOS Safari and desktop Chrome.
Images, icons, illustrations. Where an image has a transparent background and dark foreground (logos, line-art icons), it may disappear on dark mode. Options:
- Use SVG with currentColor and let CSS color it via color: var(--fg).
- Provide a <picture><source media="(prefers-color-scheme: dark)" srcset="logo-dark.svg"><img src="logo-light.svg" /></picture> swap.
- For PWA app icons, inventory's /icon-color-scheme.js already handles the home-screen icon swap on install; mirror that pattern in any other PWA that ships maskable icons (currently just inventory and nanodrop have manifests — check public/manifest.webmanifest).
Code blocks, syntax highlighting, charts. buchinese has prose articles with Chinese text and English translations — make sure both the article body and the inline word-popover are themed. dashcam has clip thumbnails and analyzer output — make sure the analyzer's color-coded labels still have AA contrast on dark. If any app uses a syntax-highlighting library (e.g. highlight.js, shiki) check it ships dual themes or load a dark theme inside the media query.
Charts / data visualization. Currently none of the apps in scope have charts; if one is added later, the chart library should respect the theme variables.
Email templates (authd password-reset, etc.) — out of scope. Email dark-mode support is a separate beast (@media (prefers-color-scheme: dark) inside HTML emails works on Apple Mail and Outlook.com but is unreliable elsewhere). Skip for this round; file as a follow-up if the user wants it.
PDFs, printed output — out of scope; print stylesheets should remain light-on-white.

Anti-patterns to avoid:

No <html class="dark"> JS toggle. That's the Tailwind/Next.js default, but the user explicitly said no toggle and no persisted preference. Pure media query only.
No localStorage / cookie that overrides the OS preference. The OS is the single source of truth.
No "auto / light / dark" three-way switch. Just auto.
Do not gate behind a feature flag or user account preference — the rollout is "ship it on the next deploy and it's live for everyone".
Do not break the global iOS font-size rule (input,textarea,select { font-size: 16px }) when refactoring CSS — it must still compute to ≥16px on mobile for affected controls.
Do not use <meta name="viewport" ... user-scalable=no> to suppress any iOS quirk — same accessibility reasoning as the font-size rule.

Test plan per app:

Open every page on macOS / iOS Safari with system theme set to Dark, then to Light. Verify legibility, no white flashes on navigation, no invisible elements.
DevTools "Emulate CSS prefers-color-scheme" — toggle both modes on every route.
Run an axe-core or Lighthouse accessibility audit; fail if any text drops below AA contrast.
For PWAs (inventory, nanodrop): add-to-home-screen on iOS in both themes, verify the splash + icon look right (inventory's /icon-color-scheme.js already covers the icon; verify it still works after the CSS refactor).
Movement: the popover overlays (popover.css) need verification — overlays on top of arbitrary page content are a common dark-mode breakage point.
buchinese: verify the Chinese-character word-popover (which floats on top of article text) and the per-sentence English translation toggles both render legibly in dark mode.

Acceptance per app PR:

npm run build / tsc --noEmit clean.
All existing tests still pass; no new tests are required (this is presentation-only) but a Playwright smoke test that loads the index page in both prefers-color-scheme values and asserts getComputedStyle(document.body).backgroundColor differs is a nice-to-have.
Manual visual inspection by user on the deployed site in both modes before the next app's PR opens (or implementer ships all six in parallel and the user reviews together — implementer's call based on whether they bundle).
No regression in the iOS focus-zoom rule (font-size ≥16px on text inputs).

Sequencing / coordination:

Six independent PRs, one per app. No cross-app coordination needed — each app's CSS is self-contained.
Suggested order (lowest risk first): nanodrop → dashcam → authd → inventory → buchinese → movement. nanodrop and dashcam have the smallest stylesheets; movement has the most complex client (multiple stylesheets, popovers, client-rendered DOM); buchinese has the most content-rich pages where bad contrast would be most visible.
The implementer can pick any one app per tick; this is a long-tail polish feature and doesn't need to ship all six at once.
Standard implementer pipeline applies (plan → execute → review → push to a feature branch → auto-merge if all checks pass and tests are green).

Out of scope (file as follow-ups if wanted):

A user-facing theme toggle (the user explicitly rejected this).
Per-account theme preference persisted in authd or per-app DB.
Email-template dark mode.
A new "high-contrast" mode beyond standard dark.
Themed PWA splash screens beyond what the current manifest.webmanifest declares.
Going back and adding dark mode to any historical screenshots / docs (the README screenshots can stay light-mode).

Going-forward expectation: like the iOS focus-zoom rule in ~/.claude/CLAUDE.md, this is a one-off retrofit. After all six apps ship, any new web frontend the user builds should bake in prefers-color-scheme support from day one. If this pattern becomes load-bearing, the reporter or user can promote it to a global rule in ~/.claude/CLAUDE.md or ~/.claude/rules/common/coding-style.md (filing note: same writability caveat as the focus-zoom rule — the rules tree is owned by nobody:nogroup from sandbox sessions, so the rule may have to live in ~/.claude/CLAUDE.md instead).

Source: user via spawn-host chat (2026-05-11). Filed by reporter; spawn-host sessions do not edit project code directly per ~/CLAUDE.md policy.

> **Originally filed:** 2026-05-11 in ~/features.md, block #11. > **Cross-project companion issues:** brendan/authd, brendan/buchinese, brendan/dashcam, brendan/inventory, brendan/movement     **2026-05-11 — cross-project: automatic OS-driven dark mode on every web frontend (authd, buchinese, dashcam, inventory, movement, nanodrop) — no in-app toggle, no preference persistence, purely `prefers-color-scheme` media-query driven** User wants every bchen.dev web app to follow the device's system theme automatically. When the OS (iOS, macOS, Android, Windows, Linux desktop) is in dark mode, the app renders in dark mode; when light, light. **No toggle switch anywhere in the UI.** No setting, no cookie, no localStorage, no per-account preference — the only input is `@media (prefers-color-scheme: dark)`. If the user changes their system theme, the app updates live (browsers re-evaluate the media query on theme change with no reload needed). **Source request (verbatim from user):** "file automatic dark mode as a feature request for every app. no need for a toggle switch anywhere, just have it be automatic based on device theming" **Apps in scope** (one PR per app — these ship independently and don't share CSS): 1. `~/authd/public/style.css` + login/account/oauth-consent HTML pages 2. `~/buchinese/public/style.css` + articles list/new/view HTML pages 3. `~/dashcam/public/style.css` (single shared stylesheet, server-rendered via `src/views/layout.ts`) 4. `~/inventory/public/style.css` + all HTML pages under `public/` (login, index, item, items-new, oauth-clients, oauth-consent, api-tokens). **Note:** inventory already has `/icon-color-scheme.js` for the PWA home-screen icon swap — that's icon-only and unrelated; the CSS work is still needed. 5. `~/movement/src/client/styles/main.css` + `popover.css` (and any other stylesheets under `src/client/styles/`) 6. `~/nanodrop/public/style.css` **Out of scope this round** (no web frontend, or N/A): `portman`, `tradebot`, `fleet` (CLI/supervisor), the `roles/` docs. **Implementation approach** (apply to every app; details may vary by stylesheet): 1. **Declare both schemes to the browser.** Add `<meta name="color-scheme" content="light dark">` to every served HTML page's `<head>`. This tells the browser the page supports both modes and lets it pick sensible defaults for form controls, scrollbars, and the initial paint background before CSS loads (prevents the "white flash on dark OS" problem). In server-rendered layouts (dashcam `src/views/layout.ts`, movement client) add it there once; in static HTML files (authd/buchinese/inventory/nanodrop public/*.html) add to each file. **Verify there is no existing `<meta name="color-scheme" content="light">` that would block this** — if so, change it to `light dark`. 2. **Refactor each stylesheet to CSS custom properties.** Replace hardcoded colors with `var(--name)` references. Define the light-mode palette under `:root { ... }` and the dark-mode palette under `@media (prefers-color-scheme: dark) { :root { ... } }`. Minimum variable set per app (extend as the design needs): - `--bg` (page background) - `--bg-elevated` (cards, panels, modals) - `--fg` (primary text) - `--fg-muted` (secondary text, labels, hints) - `--border` (dividers, input borders) - `--accent` (primary buttons, links) - `--accent-fg` (text on accent backgrounds) - `--danger` (destructive buttons, error text) + `--danger-fg` - `--success` (where used) + `--success-fg` - Form control background/text/border (`--input-bg`, `--input-fg`, `--input-border`) 3. **Pick the dark palette carefully — don't just invert.** True-black (`#000`) on OLED looks dramatic but causes haloing around text; aim for a soft near-black like `#0f1115` or `#111827` for `--bg` and `#1a1d23` / `#1f2937` for `--bg-elevated`. Text should be off-white (`#e5e7eb` / `#f3f4f6`), not pure white. Accent color often needs a saturation/brightness bump in dark mode to keep contrast — e.g. an accent that's `#2563eb` on light might become `#3b82f6` on dark. Verify WCAG AA contrast (4.5:1 for body text, 3:1 for large text) for every color pair using a tool like `https://webaim.org/resources/contrastchecker/` or `npx wcag-contrast-check`. 4. **Form controls** — the `input/textarea/select { font-size: 16px }` rule from the global CLAUDE.md still applies and is orthogonal to dark mode; do NOT regress it. For dark mode specifically, set `--input-bg`, `--input-fg`, `--input-border` and apply them. Browser-native controls (`<input type="date">`, `<select>`) will mostly take care of themselves once `color-scheme: light dark` is in `<meta>`, but verify their popups look right on both iOS Safari and desktop Chrome. 5. **Images, icons, illustrations.** Where an image has a transparent background and dark foreground (logos, line-art icons), it may disappear on dark mode. Options: - Use SVG with `currentColor` and let CSS color it via `color: var(--fg)`. - Provide a `<picture><source media="(prefers-color-scheme: dark)" srcset="logo-dark.svg"><img src="logo-light.svg" /></picture>` swap. - For PWA app icons, inventory's `/icon-color-scheme.js` already handles the home-screen icon swap on install; mirror that pattern in any other PWA that ships maskable icons (currently just inventory and nanodrop have manifests — check `public/manifest.webmanifest`). 6. **Code blocks, syntax highlighting, charts.** buchinese has prose articles with Chinese text and English translations — make sure both the article body and the inline word-popover are themed. dashcam has clip thumbnails and analyzer output — make sure the analyzer's color-coded labels still have AA contrast on dark. If any app uses a syntax-highlighting library (e.g. highlight.js, shiki) check it ships dual themes or load a dark theme inside the media query. 7. **Charts / data visualization.** Currently none of the apps in scope have charts; if one is added later, the chart library should respect the theme variables. 8. **Email templates** (authd password-reset, etc.) — **out of scope.** Email dark-mode support is a separate beast (`@media (prefers-color-scheme: dark)` inside HTML emails works on Apple Mail and Outlook.com but is unreliable elsewhere). Skip for this round; file as a follow-up if the user wants it. 9. **PDFs, printed output** — out of scope; print stylesheets should remain light-on-white. **Anti-patterns to avoid:** - **No `<html class="dark">` JS toggle.** That's the Tailwind/Next.js default, but the user explicitly said no toggle and no persisted preference. Pure media query only. - **No localStorage / cookie that overrides the OS preference.** The OS is the single source of truth. - **No "auto / light / dark" three-way switch.** Just auto. - **Do not gate behind a feature flag or user account preference** — the rollout is "ship it on the next deploy and it's live for everyone". - **Do not break the global iOS font-size rule** (`input,textarea,select { font-size: 16px }`) when refactoring CSS — it must still compute to ≥16px on mobile for affected controls. - **Do not use `<meta name="viewport" ... user-scalable=no>` to suppress any iOS quirk** — same accessibility reasoning as the font-size rule. **Test plan per app:** - Open every page on macOS / iOS Safari with system theme set to Dark, then to Light. Verify legibility, no white flashes on navigation, no invisible elements. - DevTools "Emulate CSS prefers-color-scheme" — toggle both modes on every route. - Run an axe-core or Lighthouse accessibility audit; fail if any text drops below AA contrast. - For PWAs (inventory, nanodrop): add-to-home-screen on iOS in both themes, verify the splash + icon look right (inventory's `/icon-color-scheme.js` already covers the icon; verify it still works after the CSS refactor). - Movement: the popover overlays (`popover.css`) need verification — overlays on top of arbitrary page content are a common dark-mode breakage point. - buchinese: verify the Chinese-character word-popover (which floats on top of article text) and the per-sentence English translation toggles both render legibly in dark mode. **Acceptance per app PR:** - `npm run build` / `tsc --noEmit` clean. - All existing tests still pass; no new tests are required (this is presentation-only) but a Playwright smoke test that loads the index page in both prefers-color-scheme values and asserts `getComputedStyle(document.body).backgroundColor` differs is a nice-to-have. - Manual visual inspection by user on the deployed site in both modes before the next app's PR opens (or implementer ships all six in parallel and the user reviews together — implementer's call based on whether they bundle). - No regression in the iOS focus-zoom rule (font-size ≥16px on text inputs). **Sequencing / coordination:** - Six independent PRs, one per app. No cross-app coordination needed — each app's CSS is self-contained. - **Suggested order** (lowest risk first): nanodrop → dashcam → authd → inventory → buchinese → movement. nanodrop and dashcam have the smallest stylesheets; movement has the most complex client (multiple stylesheets, popovers, client-rendered DOM); buchinese has the most content-rich pages where bad contrast would be most visible. - The implementer can pick any one app per tick; this is a long-tail polish feature and doesn't need to ship all six at once. - Standard implementer pipeline applies (plan → execute → review → push to a feature branch → auto-merge if all checks pass and tests are green). **Out of scope (file as follow-ups if wanted):** - A user-facing theme toggle (the user explicitly rejected this). - Per-account theme preference persisted in authd or per-app DB. - Email-template dark mode. - A new "high-contrast" mode beyond standard dark. - Themed PWA splash screens beyond what the current `manifest.webmanifest` declares. - Going back and adding dark mode to any historical screenshots / docs (the README screenshots can stay light-mode). **Going-forward expectation:** like the iOS focus-zoom rule in `~/.claude/CLAUDE.md`, this is a one-off retrofit. After all six apps ship, any *new* web frontend the user builds should bake in `prefers-color-scheme` support from day one. If this pattern becomes load-bearing, the reporter or user can promote it to a global rule in `~/.claude/CLAUDE.md` or `~/.claude/rules/common/coding-style.md` (filing note: same writability caveat as the focus-zoom rule — the rules tree is owned by `nobody:nogroup` from sandbox sessions, so the rule may have to live in `~/.claude/CLAUDE.md` instead). Source: user via spawn-host chat (2026-05-11). Filed by reporter; spawn-host sessions do not edit project code directly per `~/CLAUDE.md` policy.

brendan added the feature label 2026-05-13 19:02:10 +00:00

brendan closed this issue

2026-05-13 19:02:10 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: brendan/nanodrop#17