feat(maestro): map design tokens to Tailwind config, port theme to React

Wires tailwind.config.ts to every custom-property token in styles.css
(spacing, OKLCH colours, radii, z-index, sizing, durations) so Tailwind
utilities resolve to the same variables the vanilla CSS uses. Adds
ThemeContext/useTheme as a React port of theme.ts, keeping the same
localStorage keys and data-theme/data-palette attributes so it can run
alongside the vanilla shell.
This commit is contained in:
Miguel Palhas
2026-09-09 00:12:59 +01:00
parent 589e0144e2
commit 46bae13212
5 changed files with 389 additions and 1 deletions
+7 -1
View File
@@ -1,3 +1,9 @@
import { ThemeProvider } from "./contexts/ThemeContext";
export function App() {
return <div id="react-root" />;
return (
<ThemeProvider>
<div id="react-root" />
</ThemeProvider>
);
}
+163
View File
@@ -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<string, string>();
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 (
<div>
<span data-testid="theme">{theme}</span>
<span data-testid="palette">{palette}</span>
<button onClick={() => setTheme("light")}>pin-light</button>
<button onClick={toggleTheme}>toggle</button>
<button onClick={() => setPalette("ember")}>set-ember</button>
<button onClick={() => setPalette("graphite")}>set-graphite</button>
</div>
);
}
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(
<ThemeProvider>
<Probe />
</ThemeProvider>,
);
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(
<ThemeProvider>
<Probe />
</ThemeProvider>,
);
act(() => fireSystemThemeChange(true));
expect(screen.getByTestId("theme").textContent).toBe("light");
});
it("setTheme pins, persists, and stops following the system", () => {
render(
<ThemeProvider>
<Probe />
</ThemeProvider>,
);
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(
<ThemeProvider>
<Probe />
</ThemeProvider>,
);
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(
<ThemeProvider>
<Probe />
</ThemeProvider>,
);
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(
<ThemeProvider>
<Probe />
</ThemeProvider>,
);
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(<Bare />)).toThrow(
"useTheme must be used within a ThemeProvider",
);
});
});
+118
View File
@@ -0,0 +1,118 @@
// React port of ../theme.ts. Same storage keys and `data-theme`/`data-palette`
// attributes on <html>, 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<ThemeContextValue | null>(null);
export function ThemeProvider({ children }: { children: ReactNode }) {
const [pinnedTheme, setPinnedTheme] = useState<Theme | null>(
() => devThemeOverride() ?? storedTheme(),
);
const [systemIsLight, setSystemIsLight] = useState(systemPrefersLight);
const [palette, setPaletteState] = useState<Palette>(
() => 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 (
<ThemeContext.Provider
value={{ theme, palette, setTheme, toggleTheme, setPalette }}
>
{children}
</ThemeContext.Provider>
);
}
export function useTheme(): ThemeContextValue {
const ctx = useContext(ThemeContext);
if (!ctx) throw new Error("useTheme must be used within a ThemeProvider");
return ctx;
}
+1
View File
@@ -1 +1,2 @@
@import "tailwindcss";
@config "../tailwind.config.ts";