# Dark / Light Theme System — Implementation Plan **Spec:** docs/specs/2026-05-31-dark-light-theme.md · **Slug:** dark-light-theme · **Wave:** 2 **Depends on:** foundation-auth-rbac, foundation-design-system ## Goal Deliver Zync.is's two-theme system (dark default, light, system) toggled via a `.dark` class on ``. This spec owns the **single source of truth** for all OKLCH color tokens — both the dark (`html.dark`, navy/teal) and light (`:root`, VirtuAc teal/navy) palettes plus the mode-independent z-index scale — which `foundation-design-system` and every UI spec consume. It adds the `ui_theme` preference column, the `PATCH /api/user/preferences` API, cookie+localStorage persistence, a `ThemeToggle` component, and an SSR flash-prevention inline script that is CSP-nonce-compliant. ## Architecture - **Token ownership:** This plan writes the color + z-index tokens into `packages/ui/src/tokens/index.css` (the file `foundation-design-system` scaffolds but deliberately leaves color-free per spec 2's note "Color tokens are owned by dark-light-theme"). The design-system file owns only non-color primitives (`--radius`, `--font-*`, structural `--shadow` overrides are also defined here for both modes). Tailwind preset (`packages/config/tailwind.preset.ts`, owned by design-system) maps utilities onto these CSS vars — no change needed there. - **Persistence (DB):** Adds `ui_theme` column to the existing `user_preferences` table from `foundation-auth-rbac` (composite PK `(user_id, tenant_id)`, FK `user_id UUID REFERENCES users(id)`, `tenant_id UUID REFERENCES tenants(id)`). - **API:** New `PATCH /api/user/preferences` route in `zync-api` (Hono). Reads authenticated session (`user_id`, `tenant_id`), updates `user_preferences.ui_theme`, and emits `Set-Cookie: ui_theme=…; HttpOnly; SameSite=Strict; Path=/`. Body validated with Zod per the monorepo Input Validation Mandate. - **Cookie on login:** The login handler in `foundation-auth-rbac` already sets the session cookie; this plan adds a `ui_theme` cookie emission on login by reading `user_preferences.ui_theme`. Implemented as a small helper consumed by the login route. - **SSR flash prevention:** A blocking inline ` ``` **Acceptance:** - [ ] First paint matches the persisted theme — no flash of the wrong theme on reload. - [ ] CSP `script-src 'self' 'nonce-'` matches the script's `nonce`; browser console shows no CSP violation. ### Task 9: SSR flash-prevention script in `zync-www` (Astro, `locals.nonce`) **Blocks:** — · **Blocked by:** 1, 4 **Files:** - Create: `apps/zync-www/src/middleware/security.ts` (if not already present from monorepo; otherwise extend) - Modify: `apps/zync-www/src/layouts/BaseLayout.astro` (root layout ``) **Steps:** - [ ] In Astro middleware, generate a per-request nonce (`crypto.getRandomValues(new Uint8Array(16))` → base64url), set `context.locals.nonce`, and add `script-src 'self' 'nonce-${nonce}'` to the `Content-Security-Policy` response header. - [ ] In the root layout ``, render the blocking inline script with `nonce={Astro.locals.nonce}`, same cookie→localStorage→`'dark'` precedence. - [ ] Ensure the script is the first `` child, before CSS. **Schema / Interfaces:** ```ts // apps/zync-www/src/middleware/security.ts import { defineMiddleware } from 'astro:middleware' export const onRequest = defineMiddleware(async (context, next) => { const nonce = Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString('base64url') context.locals.nonce = nonce const response = await next() response.headers.set( 'Content-Security-Policy', `default-src 'self'; script-src 'self' 'nonce-${nonce}'; frame-ancestors 'none'; base-uri 'self'; form-action 'self'`, ) return response }) ``` ```astro ``` **Acceptance:** - [ ] `zync-www` pages render with the correct theme on first paint, no flash. - [ ] Response CSP `script-src` carries the same nonce as the inline script; no CSP violation logged. ### Task 10: Settings > Appearance page + nav-header toggle wiring **Blocks:** — · **Blocked by:** 5, 6, 7 **Files:** - Create: `apps/zync-app/src/pages/settings/appearance.tsx` - Modify: `apps/zync-app/src/main.tsx` (wrap app in `ThemeProvider`) - Modify: the app shell nav header component (place a compact `ThemeToggle`) **Steps:** - [ ] Wrap the React tree in `ThemeProvider` so `useTheme` is available app-wide. - [ ] Build the Appearance settings section rendering `ThemeToggle` bound to `useThemeSync().setTheme` / `.theme`. - [ ] Add a compact `ThemeToggle` to the nav header, also bound to `useThemeSync`. - [ ] Verify both controls stay in sync (shared context state). **Acceptance:** - [ ] Changing the theme in Settings updates the nav-header toggle instantly and vice versa. - [ ] Selection persists across reload (cookie/localStorage) and across sessions (DB) for authenticated users. ### Task 11: Storybook dual-mode + theme tests **Blocks:** — · **Blocked by:** 5, 6, 7, 8, 9, 10 **Files:** - Create: `packages/ui/src/theme/theme-toggle.stories.tsx` - Create: `packages/ui/.storybook/preview.tsx` modification (dark/light addon panel) - Create: `apps/zync-api/test/user-preferences.test.ts` **Steps:** - [ ] Add Storybook global toolbar / addon switch that toggles the `.dark` class so every story renders in both modes. - [ ] Add a `ThemeToggle` story exercising all three states and keyboard nav. - [ ] Add an API test: `PATCH /api/user/preferences` with each valid value updates the row + sets the cookie; invalid value → 400; unauthenticated → 401. - [ ] Add a contrast assertion (or document the verification) that `--ink`/`--ink-soft` meet ≥ 12:1 on `--bg` per mode and `--accent` meets ≥ 4.5:1 (WCAG AA) per spec 115. **Acceptance:** - [ ] Storybook renders components in both dark and light from the addon panel. - [ ] API test suite passes for valid/invalid/unauthenticated cases. - [ ] Documented contrast checks pass for both modes.