diff --git a/web/src/App.tsx b/web/src/App.tsx
index 3db62cc..620d6bc 100644
--- a/web/src/App.tsx
+++ b/web/src/App.tsx
@@ -1,3 +1,9 @@
+import { ThemeProvider } from "./contexts/ThemeContext";
+
export function App() {
- return
;
+ return (
+
+
+
+ );
}
diff --git a/web/src/contexts/ThemeContext.test.tsx b/web/src/contexts/ThemeContext.test.tsx
new file mode 100644
index 0000000..3ba2600
--- /dev/null
+++ b/web/src/contexts/ThemeContext.test.tsx
@@ -0,0 +1,163 @@
+// @vitest-environment happy-dom
+import { act, cleanup, render, screen } from "@testing-library/react";
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { PALETTES, ThemeProvider, useTheme } from "./ThemeContext";
+
+// happy-dom's vitest environment ships neither localStorage nor matchMedia;
+// back both with plain in-memory fakes so persistence and system-theme
+// reactivity are observable (mirrors ../theme.test.ts's localStorage fake).
+let store = new Map();
+let systemPrefersLight = false;
+let mediaListeners: Array<(e: MediaQueryListEvent) => void> = [];
+
+beforeAll(() => {
+ Object.defineProperty(window, "localStorage", {
+ value: {
+ getItem: (k: string) => store.get(k) ?? null,
+ setItem: (k: string, v: string) => store.set(k, v),
+ removeItem: (k: string) => store.delete(k),
+ },
+ });
+ Object.defineProperty(window, "matchMedia", {
+ value: (query: string) => ({
+ matches: query.includes("light") ? systemPrefersLight : false,
+ media: query,
+ addEventListener: (_type: string, cb: (e: MediaQueryListEvent) => void) => {
+ mediaListeners.push(cb);
+ },
+ removeEventListener: (_type: string, cb: (e: MediaQueryListEvent) => void) => {
+ mediaListeners = mediaListeners.filter((l) => l !== cb);
+ },
+ }),
+ });
+});
+
+function fireSystemThemeChange(matches: boolean): void {
+ systemPrefersLight = matches;
+ for (const cb of mediaListeners) {
+ cb({ matches } as MediaQueryListEvent);
+ }
+}
+
+function Probe() {
+ const { theme, palette, setTheme, toggleTheme, setPalette } = useTheme();
+ return (
+
+ {theme}
+ {palette}
+
+
+
+
+
+ );
+}
+
+describe("ThemeProvider / useTheme", () => {
+ beforeEach(() => {
+ store = new Map();
+ mediaListeners = [];
+ systemPrefersLight = false;
+ delete document.documentElement.dataset.theme;
+ delete document.documentElement.dataset.palette;
+ });
+
+ afterEach(() => {
+ cleanup();
+ });
+
+ it("defaults to graphite and the system theme, no data-palette attribute", () => {
+ render(
+
+
+ ,
+ );
+ expect(screen.getByTestId("theme").textContent).toBe("dark");
+ expect(screen.getByTestId("palette").textContent).toBe("graphite");
+ expect(document.documentElement.dataset.palette).toBeUndefined();
+ });
+
+ it("follows a system theme change while unpinned", () => {
+ render(
+
+
+ ,
+ );
+ act(() => fireSystemThemeChange(true));
+ expect(screen.getByTestId("theme").textContent).toBe("light");
+ });
+
+ it("setTheme pins, persists, and stops following the system", () => {
+ render(
+
+
+ ,
+ );
+ act(() => screen.getByText("pin-light").click());
+ expect(screen.getByTestId("theme").textContent).toBe("light");
+ expect(document.documentElement.dataset.theme).toBe("light");
+ expect(localStorage.getItem("maestro-theme")).toBe("light");
+
+ act(() => fireSystemThemeChange(true));
+ expect(screen.getByTestId("theme").textContent).toBe("light");
+ });
+
+ it("toggleTheme flips the resolved theme", () => {
+ render(
+
+
+ ,
+ );
+ act(() => screen.getByText("toggle").click());
+ expect(screen.getByTestId("theme").textContent).toBe("light");
+ act(() => screen.getByText("toggle").click());
+ expect(screen.getByTestId("theme").textContent).toBe("dark");
+ });
+
+ it("setPalette stamps data-palette and persists; graphite clears it", () => {
+ render(
+
+
+ ,
+ );
+ act(() => screen.getByText("set-ember").click());
+ expect(document.documentElement.dataset.palette).toBe("ember");
+ expect(localStorage.getItem("maestro-palette")).toBe("ember");
+
+ act(() => screen.getByText("set-graphite").click());
+ expect(document.documentElement.dataset.palette).toBeUndefined();
+ });
+
+ it("a fresh mount re-applies a stored palette", () => {
+ localStorage.setItem("maestro-palette", "periwinkle");
+ render(
+
+
+ ,
+ );
+ expect(screen.getByTestId("palette").textContent).toBe("periwinkle");
+ expect(document.documentElement.dataset.palette).toBe("periwinkle");
+ });
+
+ it("exposes every palette in picker order", () => {
+ expect(PALETTES).toEqual([
+ "graphite",
+ "ice-cyan",
+ "periwinkle",
+ "amber-phosphor",
+ "ember",
+ "orchid",
+ ]);
+ });
+
+ it("throws when used outside a provider", () => {
+ const Bare = () => {
+ useTheme();
+ return null;
+ };
+ expect(() => render()).toThrow(
+ "useTheme must be used within a ThemeProvider",
+ );
+ });
+});
diff --git a/web/src/contexts/ThemeContext.tsx b/web/src/contexts/ThemeContext.tsx
new file mode 100644
index 0000000..7589cde
--- /dev/null
+++ b/web/src/contexts/ThemeContext.tsx
@@ -0,0 +1,118 @@
+// React port of ../theme.ts. Same storage keys and `data-theme`/`data-palette`
+// attributes on , so this can sit alongside the vanilla shell (which
+// still owns theme.ts) without either one fighting the other over state.
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useLayoutEffect,
+ useState,
+ type ReactNode,
+} from "react";
+
+type Theme = "light" | "dark";
+const THEME_KEY = "maestro-theme";
+
+/** Every `data-palette` value, in picker order. Graphite is the default. */
+export const PALETTES = [
+ "graphite",
+ "ice-cyan",
+ "periwinkle",
+ "amber-phosphor",
+ "ember",
+ "orchid",
+] as const;
+export type Palette = (typeof PALETTES)[number];
+const PALETTE_KEY = "maestro-palette";
+
+function storedTheme(): Theme | null {
+ const v = localStorage.getItem(THEME_KEY);
+ return v === "light" || v === "dark" ? v : null;
+}
+
+function storedPalette(): Palette | null {
+ const v = localStorage.getItem(PALETTE_KEY);
+ return (PALETTES as readonly string[]).includes(v ?? "")
+ ? (v as Palette)
+ : null;
+}
+
+function systemPrefersLight(): boolean {
+ return window.matchMedia("(prefers-color-scheme: light)").matches;
+}
+
+// Dev-only `?theme=` override for visual review, same as theme.ts's — never
+// persisted, just seeds the initial pin for this session.
+function devThemeOverride(): Theme | null {
+ if (!import.meta.env.DEV) return null;
+ const q = new URLSearchParams(location.search).get("theme");
+ return q === "light" || q === "dark" ? q : null;
+}
+
+interface ThemeContextValue {
+ theme: Theme;
+ palette: Palette;
+ setTheme: (t: Theme) => void;
+ toggleTheme: () => void;
+ setPalette: (p: Palette) => void;
+}
+
+const ThemeContext = createContext(null);
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+ const [pinnedTheme, setPinnedTheme] = useState(
+ () => devThemeOverride() ?? storedTheme(),
+ );
+ const [systemIsLight, setSystemIsLight] = useState(systemPrefersLight);
+ const [palette, setPaletteState] = useState(
+ () => storedPalette() ?? "graphite",
+ );
+
+ const theme: Theme = pinnedTheme ?? (systemIsLight ? "light" : "dark");
+
+ useLayoutEffect(() => {
+ const mql = window.matchMedia("(prefers-color-scheme: light)");
+ const onChange = (e: MediaQueryListEvent) => setSystemIsLight(e.matches);
+ mql.addEventListener("change", onChange);
+ return () => mql.removeEventListener("change", onChange);
+ }, []);
+
+ // Pinning is one-way (no UI un-pins back to "follow system"), so this only
+ // ever needs to set the attribute — never clear it — same as theme.ts.
+ useLayoutEffect(() => {
+ if (pinnedTheme) document.documentElement.dataset.theme = pinnedTheme;
+ }, [pinnedTheme]);
+
+ useLayoutEffect(() => {
+ if (palette === "graphite") delete document.documentElement.dataset.palette;
+ else document.documentElement.dataset.palette = palette;
+ }, [palette]);
+
+ const setTheme = useCallback((t: Theme) => {
+ localStorage.setItem(THEME_KEY, t);
+ setPinnedTheme(t);
+ }, []);
+
+ const toggleTheme = useCallback(() => {
+ setTheme(theme === "dark" ? "light" : "dark");
+ }, [theme, setTheme]);
+
+ const setPalette = useCallback((p: Palette) => {
+ localStorage.setItem(PALETTE_KEY, p);
+ setPaletteState(p);
+ }, []);
+
+ return (
+
+ {children}
+
+ );
+}
+
+export function useTheme(): ThemeContextValue {
+ const ctx = useContext(ThemeContext);
+ if (!ctx) throw new Error("useTheme must be used within a ThemeProvider");
+ return ctx;
+}
diff --git a/web/src/main.css b/web/src/main.css
index f1d8c73..aaba0ba 100644
--- a/web/src/main.css
+++ b/web/src/main.css
@@ -1 +1,2 @@
@import "tailwindcss";
+@config "../tailwind.config.ts";
diff --git a/web/tailwind.config.ts b/web/tailwind.config.ts
index 9bc9dfc..cfd95f4 100644
--- a/web/tailwind.config.ts
+++ b/web/tailwind.config.ts
@@ -1,5 +1,105 @@
import type { Config } from "tailwindcss";
+// Bridges Tailwind utilities to the OKLCH custom-property tokens defined in
+// src/styles.css. Every value here is `var(--token)`, never a literal, so
+// theme/palette switching (data-theme, data-palette on ) keeps working
+// through Tailwind classes exactly as it does through the vanilla CSS.
export default {
content: ["src/**/*.{ts,tsx}"],
+ theme: {
+ extend: {
+ colors: {
+ bg: "var(--bg)",
+ "bg-grid": "var(--bg-grid)",
+ surface: "var(--surface)",
+ "surface-2": "var(--surface-2)",
+ "surface-3": "var(--surface-3)",
+ border: "var(--border)",
+ "border-strong": "var(--border-strong)",
+
+ ink: "var(--ink)",
+ muted: "var(--muted)",
+ faint: "var(--faint)",
+
+ accent: "var(--accent)",
+ "accent-strong": "var(--accent-strong)",
+ "accent-ink": "var(--accent-ink)",
+ "accent-tint": "var(--accent-tint)",
+ "accent-ring": "var(--accent-ring)",
+ "accent-fill": "var(--accent-fill)",
+
+ preview: "var(--preview)",
+ "preview-ink": "var(--preview-ink)",
+ "preview-tint": "var(--preview-tint)",
+ "preview-ring": "var(--preview-ring)",
+
+ live: "var(--live)",
+ "live-glow": "var(--live-glow)",
+ danger: "var(--danger)",
+ "danger-tint": "var(--danger-tint)",
+ warn: "var(--warn)",
+
+ "term-bg": "var(--term-bg)",
+ },
+ spacing: {
+ "sp-1": "var(--sp-1)",
+ "sp-2": "var(--sp-2)",
+ "sp-3": "var(--sp-3)",
+ "sp-4": "var(--sp-4)",
+ "sp-5": "var(--sp-5)",
+ "sp-6": "var(--sp-6)",
+ "sp-8": "var(--sp-8)",
+ },
+ borderRadius: {
+ "r-1": "var(--r-1)",
+ "r-2": "var(--r-2)",
+ "r-3": "var(--r-3)",
+ "r-pill": "var(--r-pill)",
+ },
+ fontSize: {
+ "fs-11": "var(--fs-11)",
+ "fs-12": "var(--fs-12)",
+ "fs-13": "var(--fs-13)",
+ "fs-14": "var(--fs-14)",
+ "fs-15": "var(--fs-15)",
+ "fs-17": "var(--fs-17)",
+ "fs-20": "var(--fs-20)",
+ },
+ fontFamily: {
+ mono: "var(--font-mono)",
+ sans: "var(--font-sans)",
+ },
+ height: {
+ "row-h": "var(--row-h)",
+ "control-h": "var(--control-h)",
+ tap: "var(--tap)",
+ "bar-h": "var(--bar-h)",
+ },
+ width: {
+ tap: "var(--tap)",
+ },
+ minHeight: {
+ "control-h": "var(--control-h)",
+ tap: "var(--tap)",
+ },
+ zIndex: {
+ sticky: "var(--z-sticky)",
+ backdrop: "var(--z-backdrop)",
+ modal: "var(--z-modal)",
+ toast: "var(--z-toast)",
+ },
+ transitionDuration: {
+ fast: "var(--dur-fast)",
+ DEFAULT: "var(--dur)",
+ slow: "var(--dur-slow)",
+ },
+ transitionTimingFunction: {
+ out: "var(--ease-out)",
+ },
+ boxShadow: {
+ 1: "var(--shadow-1)",
+ 2: "var(--shadow-2)",
+ },
+ },
+ },
} satisfies Config;