fix(cli): sync scaffold dark mode so ui-* components follow the theme (#101)

vivek7405 · web-flow · commit f0a1fa19ad77 · 2026-05-25T17:22:24.000+05:30
* fix(cli): sync scaffold dark mode so ui-* components follow the theme

The default scaffold shipped two unsynced theme systems: the editorial
chrome tokens (--fg/--bg) toggled via a `data-theme` attribute, while
the copied shadcn ui-* components (button, card, alert, etc.) key their
dark tokens off a `.dark` class (`@custom-variant dark (&amp;:is(.dark *))`).
Nothing ever set `.dark`, so every ui component was frozen in light
tokens. On the dark-default chrome this rendered, e.g., the outline
"View docs" button as white-on-light (invisible text) and cards as
white boxes. Light mode looked fine only because both systems were
light then.

Fix: the head init script and the theme-toggle now toggle a `.dark`
class in sync with the effective theme (dark by default unless the OS
prefers light or 'light' is chosen), and the head script re-applies on
OS theme changes. The chrome's `data-theme` mechanism is unchanged; the
`.dark` class simply drives the shadcn tokens alongside it.

Verified in a browser (emulated dark): outline button now renders with
the dark input tint + light text, cards render dark, and light mode is
unchanged.

* docs+test: document and guard the scaffold dark-mode dual-signal

Codify why dark mode broke while light worked so it can't recur silently:

- agent-docs/styling.md: new "Dark mode" section explaining the two
  theming signals (data-theme for the editorial chrome, .dark class for
  the Webjs UI kit), that a theme switch must drive both, and that light
  mode passing proves nothing about dark mode.
- agent-docs/testing.md: a "Verifying UI and theming" note: render in a
  real browser, test both themes, inspect computed styles, read the
  screenshot, and guard the wiring in a fast test.
- test/scaffolds/scaffold-integration.test.js: assert the generated
  layout head script AND theme-toggle both toggle the `.dark` class, so
  the sync mechanism can't regress unnoticed.
- templates/CONVENTIONS.md: a scaffolded-app note mirroring the
  dual-signal rule for agents working inside a user app.
diff --git a/agent-docs/styling.md b/agent-docs/styling.md
@@ -63,6 +63,34 @@ the definition site and compose naturally with other props (conditional
 classes, active states, etc.). They run at SSR time. Output HTML is
 identical to inline classes, no client-side runtime.
 
+## Dark mode: two signals, keep them in sync
+
+The default scaffold runs **two** theming systems, and a theme switch must
+drive **both** or one half goes stale (this is the single most common
+dark-mode bug in a scaffolded app):
+
+1. **Editorial chrome tokens** (`--fg`, `--bg`, `--accent`, ...) declared in
+   the root layout. They react to a **`data-theme` attribute** on `<html>`
+   (`data-theme="light"` vs absent) and default to dark.
+2. **Webjs UI (shadcn) component tokens** (`--background`, `--foreground`,
+   `--primary`, ...) used by everything under `components/ui/`. They react
+   to a **`.dark` class** on an ancestor (`@custom-variant dark (&:is(.dark *))`)
+   and default to light.
+
+The scaffold's head init script and `theme-toggle` set **both** signals on
+`<html>`: they write `data-theme` AND `classList.toggle('dark', isDark)`. If
+you wire your own theme switch or replace the toggle, you MUST set both.
+Setting only `data-theme` leaves the ui-* components rendering light tokens
+on a dark page (white buttons, white cards, invisible text) while the chrome
+looks correct.
+
+**Verify dark mode in a real browser, not just light.** Light mode passing
+proves nothing about dark mode: with neither signal set, both systems sit at
+a coincidentally matching default, so the divergence only appears once
+`.dark` / `data-theme` are applied. Emulate dark (`colorScheme: 'dark'` or
+flip the toggle) and check a shadcn component's computed `background-color`,
+not just the page chrome.
+
 ## Vanilla CSS for the whole app (opt-out of Tailwind)
 
 Tailwind isn't required. To hand-write CSS everywhere, you need a
diff --git a/agent-docs/testing.md b/agent-docs/testing.md
@@ -184,3 +184,26 @@ a feature, the test is probably testing too many things at once.
 - **Don't add `.unit` / `.integration` filename suffixes.** The
   folder tells you the kind; the filename should match what it
   tests.
+
+---
+
+## Verifying UI and theming changes
+
+For anything visual (layout, components, themes), a passing unit test or a
+clean-looking code diff is not enough. Render it in a real browser and look.
+
+- **Test both light AND dark mode.** Light mode passing proves nothing about
+  dark mode. The scaffold drives dark mode through two signals (a `data-theme`
+  attribute for the editorial chrome and a `.dark` class for the ui-* kit, see
+  `agent-docs/styling.md`), and when neither is set both default to a
+  coincidentally matching light, so a desync only shows once dark is active.
+  Emulate dark (Playwright `newContext({ colorScheme: 'dark' })` or flip the
+  theme toggle) and inspect a component's **computed** `background-color` /
+  `color`, not just the page chrome.
+- **Read the screenshot.** Capture `page.screenshot({ fullPage: true })` and
+  open the PNG; white-on-white or a stray light box is obvious visually and
+  invisible in the markup.
+- **Guard the wiring in a fast test where you can.** A runtime cascade bug
+  needs a browser, but the mechanism that triggers it (e.g. the theme toggle
+  setting `.dark`) can be asserted cheaply. See the dark-mode assertions in
+  `test/scaffolds/scaffold-integration.test.js`.
diff --git a/packages/cli/lib/create.js b/packages/cli/lib/create.js
@@ -642,10 +642,21 @@ export default function RootLayout({ children }: { children: unknown }) {
     <script>
       (function(){
         try {
-          var t = localStorage.getItem('webjs_theme');
-          if (t === 'light' || t === 'dark') {
-            document.documentElement.dataset.theme = t;
+          var mq = window.matchMedia('(prefers-color-scheme: light)');
+          function apply(){
+            var t = null;
+            try { t = localStorage.getItem('webjs_theme'); } catch (_) {}
+            var el = document.documentElement;
+            if (t === 'light' || t === 'dark') el.dataset.theme = t;
+            else delete el.dataset.theme;
+            // Keep shadcn's .dark class in sync with the effective theme so the
+            // copied ui-* components (button, card, etc.) follow light/dark too.
+            // Dark is the default unless the OS prefers light or 'light' is set.
+            var dark = t === 'dark' || (t !== 'light' && !mq.matches);
+            el.classList.toggle('dark', dark);
           }
+          apply();
+          mq.addEventListener('change', apply);
         } catch (_) {}
       })();
     </script>
@@ -874,8 +885,13 @@ export class ThemeToggle extends WebComponent {
       if (next === 'system') localStorage.removeItem('webjs_theme');
       else localStorage.setItem('webjs_theme', next);
     } catch {}
-    if (next === 'system') delete document.documentElement.dataset.theme;
-    else document.documentElement.dataset.theme = next;
+    const el = document.documentElement;
+    if (next === 'system') delete el.dataset.theme;
+    else el.dataset.theme = next;
+    // Keep shadcn's .dark class in sync so the ui-* components follow the theme.
+    const dark = next === 'dark'
+      || (next === 'system' && !window.matchMedia('(prefers-color-scheme: light)').matches);
+    el.classList.toggle('dark', dark);
   }
 
   render() {
diff --git a/packages/cli/templates/CONVENTIONS.md b/packages/cli/templates/CONVENTIONS.md
@@ -568,6 +568,17 @@ or a build-step pipeline. The framework has no hard dependency on Tailwind.
 If you mix custom CSS into a light-DOM component, apply the class-prefix
 rule (see Components section above).
 
+**Dark mode uses two signals; a theme switch must set both.** The editorial
+chrome tokens (`--fg`, `--bg`, `--accent`) follow a `data-theme` attribute on
+`<html>`; the Webjs UI kit under `components/ui/` follows a `.dark` class
+(`@custom-variant dark (&:is(.dark *))`). The scaffold's head init script and
+`theme-toggle` set **both** (`data-theme` AND
+`classList.toggle('dark', isDark)`). If you replace the toggle or build your
+own theme switch, set both, or the `components/ui/*` render light tokens on a
+dark page (white buttons and cards, invisible text) while the chrome looks
+correct. Light mode hides this (both systems default to light), so **verify
+dark mode in a browser, not just light.**
+
 ---
 
 ## Styling alternative: vanilla CSS end-to-end
diff --git a/test/scaffolds/scaffold-integration.test.js b/test/scaffolds/scaffold-integration.test.js
@@ -63,6 +63,18 @@ test('scaffoldApp full-stack: writes the canonical full-stack app layout', async
     assert.ok(existsSync(join(appDir, 'app', 'page.ts')), 'page.ts written');
     assert.ok(existsSync(join(appDir, 'components', 'theme-toggle.ts')), 'theme-toggle written');
 
+    // Dark-mode wiring: the head init script (in layout) AND the theme-toggle
+    // must toggle the shadcn `.dark` class, not only the `data-theme`
+    // attribute. Without `.dark`, the copied components/ui/* render light
+    // tokens on the dark chrome (white buttons/cards, invisible text). Light
+    // mode hides this, so guard it here. See agent-docs/styling.md "Dark mode".
+    const layoutSrc = readFileSync(join(appDir, 'app', 'layout.ts'), 'utf8');
+    const toggleSrc = readFileSync(join(appDir, 'components', 'theme-toggle.ts'), 'utf8');
+    assert.match(layoutSrc, /classList\.toggle\(['"]dark['"]/,
+      'layout head script must toggle the .dark class (shadcn dark-mode signal)');
+    assert.match(toggleSrc, /classList\.toggle\(['"]dark['"]/,
+      'theme-toggle must toggle the .dark class (shadcn dark-mode signal)');
+
     // Prisma + lib singleton wired up
     assert.ok(existsSync(join(appDir, 'prisma', 'schema.prisma')), 'prisma schema written');
     assert.ok(existsSync(join(appDir, 'lib', 'prisma.server.ts')), 'lib/prisma.server.ts written');
