@polderlabs/bizar 8.0.0 → 9.0.0

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/web/v8/ui/styles/globals.css

@@ -0,0 +1,220 @@
+/* globals.css — typography, body baseline, density variants. v8.
+ * Source of truth: DESIGN.md §3 (tokens), §4 (typography).
+ * Variables come from tokens.css. No font-file imports — system stack only.
+ */
+
+@import url("./tokens.css");
+@import url("./reset.css");
+
+/* ── typography: system UI stack (no web-font dependency) ───────────── */
+:root {
+  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
+    "Segoe UI", "Inter", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas,
+    "Liberation Mono", monospace;
+
+  --fs-12: 0.75rem;
+  --fs-13: 0.8125rem;
+  --fs-14: 0.875rem;
+  --fs-16: 1rem;
+  --fs-18: 1.125rem;
+  --fs-20: 1.25rem;
+  --fs-24: 1.5rem;
+  --fs-32: 2rem;
+
+  --lh-tight: 1.2;
+  --lh-snug: 1.35;
+  --lh-base: 1.5;
+  --lh-relaxed: 1.65;
+
+  --fw-regular: 400;
+  --fw-medium: 500;
+  --fw-semibold: 600;
+  --fw-bold: 700;
+
+  --tracking-tight: -0.01em;
+  --tracking-base: 0;
+  --tracking-wide: 0.04em;
+}
+
+body {
+  font-family: var(--font-sans);
+  font-size: var(--fs-14);
+  line-height: var(--lh-base);
+  color: var(--fg);
+  background: var(--bg);
+  font-feature-settings: "cv02", "cv03", "cv04", "cv11";
+}
+
+code, kbd, pre, samp {
+  font-family: var(--font-mono);
+  font-size: 0.9em;
+}
+
+kbd {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 1.5em;
+  height: 1.5em;
+  padding: 0 var(--space-1);
+  font-family: var(--font-mono);
+  font-size: var(--fs-12);
+  color: var(--fg-muted);
+  background: var(--surface-1);
+  border: 1px solid var(--border);
+  border-bottom-width: 2px;
+  border-radius: var(--radius-sm);
+}
+
+/* ── density variants (DESIGN.md §3 token system) ───────────────────── */
+:root[data-density='comfortable'] {
+  --density-row-h: 36px;
+  --density-control-h: 36px;
+  --density-card-pad: var(--space-5);
+}
+
+:root[data-density='compact'] {
+  --density-row-h: 28px;
+  --density-control-h: 28px;
+  --density-card-pad: var(--space-3);
+}
+
+/* ── headings (used directly; most layout uses Stack+fs-* tokens) ──── */
+h1 {
+  font-size: var(--fs-24);
+  line-height: var(--lh-tight);
+  font-weight: var(--fw-semibold);
+  letter-spacing: var(--tracking-tight);
+}
+h2 {
+  font-size: var(--fs-20);
+  line-height: var(--lh-snug);
+  font-weight: var(--fw-semibold);
+}
+h3 {
+  font-size: var(--fs-18);
+  line-height: var(--lh-snug);
+  font-weight: var(--fw-medium);
+}
+h4 {
+  font-size: var(--fs-16);
+  line-height: var(--lh-base);
+  font-weight: var(--fw-medium);
+}
+
+/* ── a11y helpers (see VisuallyHidden primitive) ────────────────────── */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* ── global content layer (the v8 app lives inside #root) ───────────── */
+#root {
+  display: flex;
+  flex-direction: column;
+  min-height: 100%;
+  isolation: isolate;
+}
+
+/* ── keyframes (shared across feedback + data layers) ────────────────── */
+
+@keyframes v8-skeleton-pulse {
+  0%, 100% { opacity: 1; }
+  50%      { opacity: 0.55; }
+}
+
+@keyframes v8-spin {
+  to { transform: rotate(360deg); }
+}
+
+@keyframes v8-dialog-overlay-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+@keyframes v8-dialog-content-in {
+  from { opacity: 0; transform: translate(-50%, -48%) scale(0.96); }
+  to   { opacity: 1; transform: translate(-50%, -50%) scale(1); }
+}
+
+@keyframes v8-sheet-in-right {
+  from { transform: translateX(100%); }
+  to   { transform: translateX(0); }
+}
+@keyframes v8-sheet-in-left {
+  from { transform: translateX(-100%); }
+  to   { transform: translateX(0); }
+}
+@keyframes v8-sheet-in-top {
+  from { transform: translateY(-100%); }
+  to   { transform: translateY(0); }
+}
+@keyframes v8-sheet-in-bottom {
+  from { transform: translateY(100%); }
+  to   { transform: translateY(0); }
+}
+
+@keyframes v8-menu-in {
+  from { opacity: 0; transform: translateY(-4px) scale(0.98); }
+  to   { opacity: 1; transform: translateY(0) scale(1); }
+}
+
+@keyframes v8-tooltip-in {
+  from { opacity: 0; transform: translateY(2px); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+/* ── animation bindings (opt-in via class) ──────────────────────────── */
+
+.v8-skeleton {
+  animation: v8-skeleton-pulse 1.4s var(--easing-standard, cubic-bezier(0.4, 0, 0.2, 1)) infinite;
+}
+
+.v8-spinner {
+  animation: v8-spin 0.8s linear infinite;
+}
+
+.v8-dialog-overlay {
+  animation: v8-dialog-overlay-in 160ms var(--easing-standard, cubic-bezier(0.4, 0, 0.2, 1));
+}
+.v8-dialog-content {
+  animation: v8-dialog-content-in 200ms var(--easing-standard, cubic-bezier(0.4, 0, 0.2, 1));
+}
+
+.v8-sheet[data-side='right'] { animation: v8-sheet-in-right 240ms cubic-bezier(0.32, 0.72, 0, 1); }
+.v8-sheet[data-side='left']  { animation: v8-sheet-in-left  240ms cubic-bezier(0.32, 0.72, 0, 1); }
+.v8-sheet[data-side='top']   { animation: v8-sheet-in-top   240ms cubic-bezier(0.32, 0.72, 0, 1); }
+.v8-sheet[data-side='bottom']{ animation: v8-sheet-in-bottom 240ms cubic-bezier(0.32, 0.72, 0, 1); }
+
+.v8-dropdown-menu,
+.v8-context-menu,
+.v8-popover {
+  animation: v8-menu-in 140ms var(--easing-standard, cubic-bezier(0.4, 0, 0.2, 1));
+  transform-origin: var(--radix-dropdown-menu-content-transform-origin, var(--radix-context-menu-content-transform-origin, var(--radix-popover-content-transform-origin, top)));
+}
+
+.v8-tooltip {
+  animation: v8-tooltip-in 120ms var(--easing-standard, cubic-bezier(0.4, 0, 0.2, 1));
+}
+
+/* ── menu item focus state (Radix data-* attributes) ────────────────── */
+.v8-dropdown-menu__item[data-highlighted],
+.v8-context-menu__item[data-highlighted] {
+  background: var(--surface-2);
+}
+.v8-dropdown-menu__item.is-danger[data-highlighted],
+.v8-context-menu__item.is-danger[data-highlighted] {
+  background: color-mix(in oklch, var(--danger) 12%, transparent);
+}
+
+.v8-dropdown-menu__checkbox[data-state='checked'] .v8-dropdown-menu__checkbox-indicator,
+.v8-dropdown-menu__radio[data-state='checked'] .v8-dropdown-menu__radio-indicator {
+  display: inline-flex;
+}

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/web/v8/ui/styles/reset.css

@@ -0,0 +1,57 @@
+/* reset.css — Modern minimal CSS reset (v8)
+ * Source of truth: DESIGN.md §1 (principles), §3 (tokens).
+ * No vendor prefixes; we target modern browsers only (last 2 versions).
+ */
+
+*, *::before, *::after { box-sizing: border-box; }
+
+html, body, #root { height: 100%; }
+
+body {
+  margin: 0;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+}
+
+h1, h2, h3, h4, h5, h6, p, figure, blockquote, dl, dd { margin: 0; }
+
+ul[role='list'], ol[role='list'] { list-style: none; padding: 0; margin: 0; }
+
+a { color: inherit; text-decoration: none; }
+
+img, picture, video, canvas, svg {
+  display: block;
+  max-width: 100%;
+}
+
+input, button, textarea, select {
+  font: inherit;
+  color: inherit;
+}
+
+button { background: none; border: 0; padding: 0; cursor: pointer; }
+
+table { border-collapse: collapse; border-spacing: 0; }
+
+[hidden] { display: none !important; }
+
+:focus-visible {
+  outline: 2px solid var(--focus-ring);
+  outline-offset: 2px;
+  border-radius: var(--radius-sm);
+}
+
+::selection {
+  background: var(--accent-soft);
+  color: var(--fg);
+}
+
+::-webkit-scrollbar { width: 10px; height: 10px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb {
+  background: var(--border-strong);
+  border-radius: var(--radius-pill);
+  border: 2px solid var(--bg);
+}
+::-webkit-scrollbar-thumb:hover { background: var(--fg-subtle); }

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/web/v8/ui/styles/tokens.css

@@ -0,0 +1,217 @@
+/* tokens.css — generated from tokens.json; v8 design contract (DESIGN.md §3).
+ * Do not edit values inline. All component CSS consumes var(--token).
+ * Light + dark variants defined here. System detection via media query.
+ *
+ * Note: this is the canonical source for color, geometry, elevation, motion, z-index.
+ */
+
+:root {
+  /* ── color: light theme (OKLch) ─────────────────────────────────────── */
+  --bg:                  oklch(0.99 0 0);
+  --surface-1:           oklch(0.97 0 0);
+  --surface-2:           oklch(0.95 0 0);
+  --surface-3:           oklch(0.93 0 0);
+  --surface-popover:     oklch(0.99 0 0);
+
+  --fg:                  oklch(0.20 0 0);
+  --fg-muted:            oklch(0.45 0 0);
+  --fg-subtle:           oklch(0.60 0 0);
+  --fg-on-accent:        oklch(0.99 0 0);
+  --fg-link:             oklch(0.527 0.154 150.069);
+
+  --accent:              oklch(0.527 0.154 150.069);  /* THE green */
+  --accent-hover:        oklch(0.475 0.154 150.069);
+  --accent-soft:         oklch(0.93 0.04 150);
+  --accent-ring:         oklch(0.527 0.154 150.069 / 0.4);
+
+  --success:             oklch(0.55 0.13 150);
+  --warning:             oklch(0.72 0.15 80);
+  --danger:              oklch(0.55 0.20 25);
+  --info:                oklch(0.55 0.13 240);
+
+  --border:              oklch(0.90 0 0);
+  --border-strong:       oklch(0.85 0 0);
+  --input-bg:            oklch(0.99 0 0);
+  --focus-ring:          oklch(0.527 0.154 150.069);
+
+  /* charts: grayscale + one accent */
+  --chart-1:             oklch(0.55 0 0);
+  --chart-2:             oklch(0.40 0 0);
+  --chart-3:             oklch(0.70 0 0);
+  --chart-4:             oklch(0.25 0 0);
+  --chart-5:             oklch(0.85 0 0);
+  --chart-accent:        oklch(0.527 0.154 150.069);
+
+  /* sidebar — solid fill (no transparency per DESIGN.md §10: glass banned) */
+  --sidebar-bg:          oklch(0.97 0 0);
+  --sidebar-fg:          oklch(0.20 0 0);
+  --sidebar-accent:      oklch(0.527 0.154 150.069);
+  --sidebar-accent-fg:   oklch(0.99 0 0);
+  --sidebar-hover:       oklch(0.93 0 0);
+  --sidebar-border:      oklch(0.90 0 0);
+
+  /* ── geometry ───────────────────────────────────────────────────────── */
+  --radius:              10px;
+  --radius-sm:           6px;
+  --radius-lg:           14px;
+  --radius-pill:         9999px;
+
+  /* ── elevation (solid shadows, no glass) ────────────────────────────── */
+  --shadow-1:            0 1px 2px oklch(0 0 0 / 0.04), 0 1px 1px oklch(0 0 0 / 0.02);
+  --shadow-2:            0 2px 4px oklch(0 0 0 / 0.06), 0 1px 2px oklch(0 0 0 / 0.04);
+  --shadow-3:            0 8px 16px oklch(0 0 0 / 0.08), 0 2px 4px oklch(0 0 0 / 0.04);
+  --shadow-4:            0 16px 32px oklch(0 0 0 / 0.10), 0 4px 8px oklch(0 0 0 / 0.06);
+
+  /* ── motion ─────────────────────────────────────────────────────────── */
+  --motion-instant:      50ms;
+  --motion-fast:         120ms;
+  --motion-base:         200ms;
+  --motion-slow:         320ms;
+  --ease-out:            cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-in-out:         cubic-bezier(0.65, 0, 0.35, 1);
+  --ease-spring:         cubic-bezier(0.34, 1.56, 0.64, 1);
+
+  /* ── z-index scale (DESIGN.md §3 — never go higher than tooltip) ───── */
+  --z-base:              0;
+  --z-sticky:            10;
+  --z-dropdown:          1000;
+  --z-sticky-nav:        1100;
+  --z-overlay:           1300;
+  --z-modal:             1400;
+  --z-popover:           1500;
+  --z-toast:             1600;
+  --z-tooltip:           1700;
+
+  /* ── spacing & sizing tokens (4px base) ────────────────────────────── */
+  --space-1:             4px;
+  --space-2:             8px;
+  --space-3:             12px;
+  --space-4:             16px;
+  --space-5:             20px;
+  --space-6:             24px;
+  --space-8:             32px;
+  --space-10:            40px;
+  --space-12:            48px;
+  --space-16:            64px;
+
+  --topbar-h:            56px;
+  --sidebar-w:           260px;
+  --sidebar-w-collapsed: 60px;
+  --statusbar-h:         32px;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg:                  oklch(0.18 0 0);
+    --surface-1:           oklch(0.22 0 0);
+    --surface-2:           oklch(0.25 0 0);
+    --surface-3:           oklch(0.28 0 0);
+    --surface-popover:     oklch(0.25 0 0);
+
+    --fg:                  oklch(0.97 0 0);
+    --fg-muted:            oklch(0.75 0 0);
+    --fg-subtle:           oklch(0.60 0 0);
+    --fg-on-accent:        oklch(0.15 0 0);
+    --fg-link:             oklch(0.448 0.119 151.328);
+
+    --accent:              oklch(0.448 0.119 151.328);  /* dark green */
+    --accent-hover:        oklch(0.50 0.119 151.328);
+    --accent-soft:         oklch(0.30 0.04 150);
+    --accent-ring:         oklch(0.448 0.119 151.328 / 0.4);
+
+    --success:             oklch(0.65 0.13 150);
+    --warning:             oklch(0.75 0.15 80);
+    --danger:              oklch(0.65 0.20 25);
+    --info:                oklch(0.65 0.13 240);
+
+    --border:              oklch(0.30 0 0);
+    --border-strong:       oklch(0.35 0 0);
+    --input-bg:            oklch(0.22 0 0);
+    --focus-ring:          oklch(0.448 0.119 151.328);
+
+    --chart-1:             oklch(0.75 0 0);
+    --chart-2:             oklch(0.60 0 0);
+    --chart-3:             oklch(0.85 0 0);
+    --chart-4:             oklch(0.50 0 0);
+    --chart-5:             oklch(0.30 0 0);
+    --chart-accent:        oklch(0.448 0.119 151.328);
+
+    --sidebar-bg:          oklch(0.20 0 0);
+    --sidebar-fg:          oklch(0.95 0 0);
+    --sidebar-accent:      oklch(0.448 0.119 151.328);
+    --sidebar-accent-fg:   oklch(0.15 0 0);
+    --sidebar-hover:       oklch(0.25 0 0);
+    --sidebar-border:      oklch(0.30 0 0);
+
+    --shadow-1:            0 1px 2px oklch(0 0 0 / 0.20), 0 1px 1px oklch(0 0 0 / 0.10);
+    --shadow-2:            0 2px 4px oklch(0 0 0 / 0.30), 0 1px 2px oklch(0 0 0 / 0.20);
+    --shadow-3:            0 8px 16px oklch(0 0 0 / 0.40), 0 2px 4px oklch(0 0 0 / 0.20);
+    --shadow-4:            0 16px 32px oklch(0 0 0 / 0.50), 0 4px 8px oklch(0 0 0 / 0.30);
+  }
+}
+
+/* explicit class-based theme overrides (wins over media query) */
+:root[data-theme='light'] {
+  --bg:                  oklch(0.99 0 0);
+  --surface-1:           oklch(0.97 0 0);
+  --surface-2:           oklch(0.95 0 0);
+  --surface-3:           oklch(0.93 0 0);
+  --surface-popover:     oklch(0.99 0 0);
+  --fg:                  oklch(0.20 0 0);
+  --fg-muted:            oklch(0.45 0 0);
+  --fg-subtle:           oklch(0.60 0 0);
+  --fg-on-accent:        oklch(0.99 0 0);
+  --accent:              oklch(0.527 0.154 150.069);
+  --accent-hover:        oklch(0.475 0.154 150.069);
+  --accent-soft:         oklch(0.93 0.04 150);
+  --accent-ring:         oklch(0.527 0.154 150.069 / 0.4);
+  --border:              oklch(0.90 0 0);
+  --border-strong:       oklch(0.85 0 0);
+  --input-bg:            oklch(0.99 0 0);
+  --focus-ring:          oklch(0.527 0.154 150.069);
+  --sidebar-bg:          oklch(0.97 0 0);
+  --sidebar-fg:          oklch(0.20 0 0);
+  --sidebar-accent:      oklch(0.527 0.154 150.069);
+  --sidebar-accent-fg:   oklch(0.99 0 0);
+  --sidebar-hover:       oklch(0.93 0 0);
+  --sidebar-border:      oklch(0.90 0 0);
+}
+
+:root[data-theme='dark'] {
+  --bg:                  oklch(0.18 0 0);
+  --surface-1:           oklch(0.22 0 0);
+  --surface-2:           oklch(0.25 0 0);
+  --surface-3:           oklch(0.28 0 0);
+  --surface-popover:     oklch(0.25 0 0);
+  --fg:                  oklch(0.97 0 0);
+  --fg-muted:            oklch(0.75 0 0);
+  --fg-subtle:           oklch(0.60 0 0);
+  --fg-on-accent:        oklch(0.15 0 0);
+  --accent:              oklch(0.448 0.119 151.328);
+  --accent-hover:        oklch(0.50 0.119 151.328);
+  --accent-soft:         oklch(0.30 0.04 150);
+  --accent-ring:         oklch(0.448 0.119 151.328 / 0.4);
+  --border:              oklch(0.30 0 0);
+  --border-strong:       oklch(0.35 0 0);
+  --input-bg:            oklch(0.22 0 0);
+  --focus-ring:          oklch(0.448 0.119 151.328);
+  --sidebar-bg:          oklch(0.20 0 0);
+  --sidebar-fg:          oklch(0.95 0 0);
+  --sidebar-accent:      oklch(0.448 0.119 151.328);
+  --sidebar-accent-fg:   oklch(0.15 0 0);
+  --sidebar-hover:       oklch(0.25 0 0);
+  --sidebar-border:      oklch(0.30 0 0);
+  --shadow-1:            0 1px 2px oklch(0 0 0 / 0.20), 0 1px 1px oklch(0 0 0 / 0.10);
+  --shadow-2:            0 2px 4px oklch(0 0 0 / 0.30), 0 1px 2px oklch(0 0 0 / 0.20);
+  --shadow-3:            0 8px 16px oklch(0 0 0 / 0.40), 0 2px 4px oklch(0 0 0 / 0.20);
+  --shadow-4:            0 16px 32px oklch(0 0 0 / 0.50), 0 4px 8px oklch(0 0 0 / 0.30);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --motion-instant:      0ms;
+    --motion-fast:         0ms;
+    --motion-base:         0ms;
+    --motion-slow:         0ms;
+  }
+}

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/web/v8/ui/theme/DensityProvider.tsx

@@ -0,0 +1,66 @@
+import { createContext, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+/**
+ * UI density — affects row heights, control heights, card padding via tokens.
+ *   - 'comfortable' → standard spacing (default).
+ *   - 'compact'     → dense data tables, power-user mode.
+ *
+ * Persisted to localStorage and reflected as `data-density="…"` on <html>
+ * so tokens.css rules (e.g. `--density-row-h`) swap without a re-render.
+ */
+export type Density = 'comfortable' | 'compact';
+
+export interface DensityContextValue {
+  density: Density;
+  setDensity: (next: Density) => void;
+  toggle: () => void;
+}
+
+export const DensityContext = createContext<DensityContextValue | null>(null);
+
+const STORAGE_KEY = 'bizar:density';
+
+function readStoredDensity(): Density {
+  if (typeof window === 'undefined') return 'comfortable';
+  const raw = window.localStorage.getItem(STORAGE_KEY);
+  if (raw === 'comfortable' || raw === 'compact') return raw;
+  return 'comfortable';
+}
+
+function applyDensityAttribute(density: Density): void {
+  if (typeof document === 'undefined') return;
+  document.documentElement.dataset['density'] = density;
+}
+
+export interface DensityProviderProps {
+  children: ReactNode;
+  defaultDensity?: Density;
+}
+
+export function DensityProvider({ children, defaultDensity }: DensityProviderProps): JSX.Element {
+  const [density, setDensityState] = useState<Density>(() => defaultDensity ?? readStoredDensity());
+
+  useEffect(() => {
+    applyDensityAttribute(density);
+  }, [density]);
+
+  const setDensity = useCallback((next: Density) => {
+    setDensityState(next);
+    if (typeof window !== 'undefined') window.localStorage.setItem(STORAGE_KEY, next);
+  }, []);
+
+  const toggle = useCallback(() => {
+    setDensityState((prev) => {
+      const next: Density = prev === 'comfortable' ? 'compact' : 'comfortable';
+      if (typeof window !== 'undefined') window.localStorage.setItem(STORAGE_KEY, next);
+      return next;
+    });
+  }, []);
+
+  const value = useMemo<DensityContextValue>(
+    () => ({ density, setDensity, toggle }),
+    [density, setDensity, toggle],
+  );
+
+  return <DensityContext.Provider value={value}>{children}</DensityContext.Provider>;
+}

package/.claude/worktrees/kanban-overhaul/bizar-dash/src/web/v8/ui/theme/ThemeProvider.tsx

@@ -0,0 +1,94 @@
+import { createContext, useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+/**
+ * Theme modes.
+ *   - 'system'  → follows `prefers-color-scheme` media query, stored as `data-theme="light|dark"` on <html>.
+ *   - 'light'   → forces light.
+ *   - 'dark'    → forces dark.
+ */
+export type ThemeMode = 'system' | 'light' | 'dark';
+export type ResolvedTheme = 'light' | 'dark';
+
+export interface ThemeContextValue {
+  /** The user's chosen mode (may be 'system'). */
+  mode: ThemeMode;
+  /** The active theme after resolving 'system' against the OS preference. */
+  resolved: ResolvedTheme;
+  /** Persist a new mode. */
+  setMode: (mode: ThemeMode) => void;
+  /** Cycle through light → dark → system → light. Wired to the toolbar toggle. */
+  cycle: () => void;
+}
+
+export const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+const STORAGE_KEY = 'bizar:theme';
+
+function readStoredMode(): ThemeMode {
+  if (typeof window === 'undefined') return 'system';
+  const raw = window.localStorage.getItem(STORAGE_KEY);
+  if (raw === 'light' || raw === 'dark' || raw === 'system') return raw;
+  return 'system';
+}
+
+function systemPrefersDark(): boolean {
+  if (typeof window === 'undefined' || !window.matchMedia) return false;
+  return window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+function resolveTheme(mode: ThemeMode): ResolvedTheme {
+  if (mode === 'light' || mode === 'dark') return mode;
+  return systemPrefersDark() ? 'dark' : 'light';
+}
+
+function applyThemeAttribute(resolved: ResolvedTheme): void {
+  if (typeof document === 'undefined') return;
+  document.documentElement.dataset['theme'] = resolved;
+}
+
+export interface ThemeProviderProps {
+  children: ReactNode;
+  /** Override default mode on first render (still persists on change). */
+  defaultMode?: ThemeMode;
+}
+
+export function ThemeProvider({ children, defaultMode }: ThemeProviderProps): JSX.Element {
+  const [mode, setModeState] = useState<ThemeMode>(() => defaultMode ?? readStoredMode());
+  const [systemDark, setSystemDark] = useState<boolean>(systemPrefersDark);
+
+  // Subscribe to system preference changes when in 'system' mode.
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+    const mql = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = (e: MediaQueryListEvent): void => setSystemDark(e.matches);
+    mql.addEventListener('change', handler);
+    return () => mql.removeEventListener('change', handler);
+  }, []);
+
+  const resolved: ResolvedTheme = mode === 'system' ? (systemDark ? 'dark' : 'light') : mode;
+
+  // Apply to <html data-theme="…"> so tokens.css overrides win over media query.
+  useEffect(() => {
+    applyThemeAttribute(resolved);
+  }, [resolved]);
+
+  const setMode = useCallback((next: ThemeMode) => {
+    setModeState(next);
+    if (typeof window !== 'undefined') window.localStorage.setItem(STORAGE_KEY, next);
+  }, []);
+
+  const cycle = useCallback(() => {
+    setModeState((prev) => {
+      const next: ThemeMode = prev === 'light' ? 'dark' : prev === 'dark' ? 'system' : 'light';
+      if (typeof window !== 'undefined') window.localStorage.setItem(STORAGE_KEY, next);
+      return next;
+    });
+  }, []);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({ mode, resolved, setMode, cycle }),
+    [mode, resolved, setMode, cycle],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}