pixelize-design-library 2.4.2 → 3.0.0

package/dist/esm/Theme/chakra/createBrandTheme.js

@@ -2,67 +2,65 @@ import { extendTheme } from "@chakra-ui/react";
 import common from "./common.web.js";
 import fonts from "./fonts.web.js";
 import { componentStyles } from "./componentStyles.js";
-import { onFilled } from "../tokens/builders/accentText.js";
+import { resolveFilledSurface } from "../tokens/builders/filledSurface.js";
 import { globalScrollbarStyles } from "../tokens/builders/scrollbar.js";
-/**
- * Builds a Chakra theme from a pure brand palette.
- *
- * Replaces the seven byte-identical `<Brand>/theme.ts` files — they differed only in
- * which palette they imported.
- *
- * Dark mode works by swapping which palette the theme carries: `componentStyles` variants
- * are functions of `({ theme })` and `useCustomTheme()` reads `theme.colors`, so both follow
- * the palette automatically without any per-component `_dark` overrides.
- */
+import { focusRingShadow } from "./focusRing.styles.js";
+import { shadowsFor } from "../tokens/primitives/shadows.js";
+import { reducedMotionGlobalStyles } from "./motion.js";
+import { TEXT_STYLES } from "../tokens/primitives/typography.js";
+import { memoiseByReads } from "../tokens/builders/memoByReads.js";
+const memoisedStyle = (value) => typeof value === "function" ? memoiseByReads(value) : value;
+const memoisedGroup = (group) => Object.fromEntries(Object.entries(group).map(([key, value]) => [key, memoisedStyle(value)]));
+const memoisedConfig = (config) => Object.fromEntries(Object.entries(config).map(([key, value]) => [
+    key,
+    key === "baseStyle"
+        ? memoisedStyle(value)
+        : key === "variants" || key === "sizes"
+            ? memoisedGroup(value)
+            : value,
+]));
+// NOTE: extendTheme deep-merges Chakra's and our style output on every call; cache it per theme.
+const withMemoisedStyles = (theme) => {
+    const components = theme.components;
+    return {
+        ...theme,
+        components: {
+            ...components,
+            ...Object.fromEntries(Object.keys(componentStyles).map((name) => [name, memoisedConfig(components[name])])),
+        },
+    };
+};
+// Builds a Chakra theme from a pure brand palette — dark mode works by swapping which palette it carries.
 export const createBrandTheme = (palette, options = {}) => {
     var _a;
     const colorMode = (_a = options.colorMode) !== null && _a !== void 0 ? _a : "light";
+    const motionRule = options.reducedMotion === "global" ? reducedMotionGlobalStyles : {};
     const brand = {
         colors: palette,
         ...fonts,
         ...common,
+        // NOTE: binds the palette-derived ring to shadows.outline — Chakra's stock one failed 1.4.11 on every brand.
+        shadows: { ...shadowsFor(colorMode), outline: focusRingShadow(palette) },
     };
-    return extendTheme({
+    return withMemoisedStyles(extendTheme({
         ...brand,
         config: {
             ...common.config,
-            // Deliberately ALWAYS "light", even for the dark theme — this is not a bug.
-            //
-            // Dark works by swapping the palette, so the palette is ALREADY mode-adapted by the time
-            // Chakra sees it. Telling Chakra it is in dark mode makes it adapt a second time: its
-            // built-ins carry `_dark` blocks that reach for `gray.700`/`gray.800` assuming a scale where
-            // those rungs are dark. Our dark gray ramp runs dark -> light, so those rungs are LIGHT —
-            // producing a light Card/Skeleton/Menu on a dark canvas. Adapting twice cancels out.
-            //
-            // Keeping Chakra on its `_light` branch is what makes the swap work: those defaults are
-            // gray-RUNG references (`gray.100`, `gray.200`, `gray.600`), and our reversed ramp already
-            // maps each rung to the right value per mode. `semanticTokens` below patches the one default
-            // that hardcodes a literal color instead of a rung.
+            // NOTE: always "light" on purpose, even for the dark theme — Chakra's own `_dark` blocks would adapt an already-adapted palette a second time.
             initialColorMode: "light",
             useSystemColorMode: false,
         },
-        // `chakra-body-bg` is the only stock semantic token that resolves to a LITERAL (`white`)
-        // rather than a gray rung, so it is the only one the palette swap cannot correct on its own —
-        // it is what paints a white Card/Modal/Menu on the dark canvas. `background[50]` is the
-        // canvas-following equivalent: byte-identical `#ffffff` in light, the canvas in dark.
-        // `chakra-inverse-text` is the same literal-`white` problem in text form.
         semanticTokens: {
             colors: {
                 "chakra-body-bg": palette.background[50],
                 "chakra-inverse-text": palette.background[50],
             },
         },
-        // Light themes intentionally declare no global styles — that is the pre-existing
-        // behavior, and adding any would shift every consuming app's light rendering.
-        // Dark needs a canvas, otherwise the page stays white behind the components.
+        // NOTE: light declares no global styles (pre-existing behavior); dark needs one or the page stays white behind components.
         ...(colorMode === "dark"
             ? {
                 styles: {
                     global: {
-                        // Native widgets the page cannot style — the `<select>` dropdown list and the
-                        // time/date picker popups — are painted by the browser, which defaults to light
-                        // and produced white popups on the dark canvas. `color-scheme` is the only way to
-                        // tell it otherwise.
                         html: {
                             colorScheme: "dark",
                         },
@@ -70,36 +68,37 @@ export const createBrandTheme = (palette, options = {}) => {
                             bg: palette.backgroundColor.main,
                             color: palette.text[900],
                         },
-                        // Text selection is another browser-painted surface `color-scheme` doesn't cover —
-                        // the UA default `::selection` stays a light highlight regardless of theme, so
-                        // selecting text anywhere (e.g. a table cell) shows a stray white/lavender patch on
-                        // the dark canvas. Brand it instead, with WCAG-safe ink via the same `onFilled` math
-                        // used for buttons/badges.
-                        "::selection": {
-                            background: palette.primary[500],
-                            color: onFilled(palette.primary[500], palette.white, palette.black),
-                        },
-                        "::-moz-selection": {
-                            background: palette.primary[500],
-                            color: onFilled(palette.primary[500], palette.white, palette.black),
-                        },
-                        // `color-scheme: dark` gives WebKit/Blink a dark scrollbar by default, but it's the
-                        // OS's generic dark gray, not brand-aware.
+                        // NOTE: ::selection isn't covered by color-scheme — branded here with the same onFilled math as buttons.
+                        "::selection": (() => {
+                            const solid = resolveFilledSurface(palette.primary, palette);
+                            return {
+                                background: solid.fill,
+                                color: solid.color,
+                            };
+                        })(),
+                        "::-moz-selection": (() => {
+                            const solid = resolveFilledSurface(palette.primary, palette);
+                            return {
+                                background: solid.fill,
+                                color: solid.color,
+                            };
+                        })(),
                         ...globalScrollbarStyles(palette),
-                        // Chrome/Edge autofill paints its own opaque yellow/white fill behind the input
-                        // text via `-webkit-box-shadow` (not `background`), so a plain `bg` override never
-                        // reaches it — a bright light box survives on every dark autofilled field unless
-                        // overridden with the same trick.
+                        // NOTE: autofill paints its own fill via -webkit-box-shadow, so a plain `bg` override can't reach it.
                         "input:-webkit-autofill, input:-webkit-autofill:hover, input:-webkit-autofill:focus": {
                             WebkitBoxShadow: `0 0 0px 1000px ${palette.backgroundColor.secondary} inset`,
                             WebkitTextFillColor: palette.text[900],
                             caretColor: palette.text[900],
                         },
+                        ...motionRule,
                     },
                 },
             }
-            : {}),
+            : options.reducedMotion === "global"
+                ? { styles: { global: motionRule } }
+                : {}),
+        textStyles: TEXT_STYLES,
         components: componentStyles,
-    });
+    }));
 };
 export default createBrandTheme;

package/dist/esm/Theme/chakra/focusRing.styles.js

@@ -0,0 +1,37 @@
+// Web binding for the focusRing token pair — colors come from tokens/builders/focusRing.ts; CSS shape is web-only.
+/** Inner band, in the surface tone: separates the ring from the control's own fill. */
+export const FOCUS_HALO_WIDTH = 2;
+/** Outer edge of the brand band. The band itself is the 2px between halo and ring. */
+export const FOCUS_RING_WIDTH = 4;
+// NOTE: a box-shadow, not an outline — drawn outside the border box so it never resizes the control.
+export const focusRingShadow = (colors) => `0 0 0 ${FOCUS_HALO_WIDTH}px ${colors.focusRing.halo}, ` +
+    `0 0 0 ${FOCUS_RING_WIDTH}px ${colors.focusRing.ring}`;
+/** For controls whose shell clips overflow: ring on the edge, halo inside, so an opaque child leaves the ring. */
+export const insetFocusRingShadow = (colors) => `inset 0 0 0 ${FOCUS_RING_WIDTH - FOCUS_HALO_WIDTH}px ${colors.focusRing.ring}, ` +
+    `inset 0 0 0 ${FOCUS_RING_WIDTH}px ${colors.focusRing.halo}`;
+// NOTE: stacked pseudo-classes raise specificity above Chakra's _hover, so a hovered+focused button keeps its ring.
+export const FOCUS_VISIBLE_OVER_STATE = "&:hover:focus-visible, &:active:focus-visible, &[data-active]:focus-visible";
+// NOTE: transparent outline isn't decorative — forced-colors mode drops box-shadow but repaints an outline.
+export const focusVisibleRing = (colors) => ({
+    outline: "2px solid transparent",
+    outlineOffset: "2px",
+    boxShadow: focusRingShadow(colors),
+});
+/** Blurred, never a flat band: a band has a hard outer edge at every opacity and reads as a second border. */
+export const FOCUS_GLOW_BLUR = 6;
+/** Negative spread keeps the bloom tight to the border instead of haloing the whole control. */
+export const FOCUS_GLOW_SPREAD = -1;
+/** Step on `primary.opacity`. Safe to raise because a blur has no edge to sharpen. */
+export const FOCUS_GLOW_ALPHA = 32;
+export const focusGlowShadow = (colors) => `0 0 ${FOCUS_GLOW_BLUR}px ${FOCUS_GLOW_SPREAD}px ${colors.primary.opacity[FOCUS_GLOW_ALPHA]}`;
+/** Field focus: the brand border is the indicator, this only makes it findable. */
+export const fieldFocusVisible = (colors) => ({
+    outline: "2px solid transparent",
+    outlineOffset: "2px",
+    boxShadow: focusGlowShadow(colors),
+});
+/** Both selectors a control needs to keep the ring on top of its own hover/active styling. */
+export const focusVisibleStyles = (colors) => {
+    const ring = focusVisibleRing(colors);
+    return { _focusVisible: ring, [FOCUS_VISIBLE_OVER_STATE]: ring };
+};

package/dist/esm/Theme/chakra/fonts.web.js

@@ -1,10 +1,6 @@
 /** Self-hosted Inter Variable (wght 100–900); required for theme fontWeights to render correctly. */
 import "@fontsource-variable/inter/index.css";
 import typography from "../tokens/primitives/typography.js";
-/**
- * Web font binding: loads the Inter font face (CSS side-effect) and re-exports the pure
- * typography tokens. The CSS import lives here rather than in `tokens/` so the token
- * layer stays portable to mobile.
- */
+// Web font binding: loads Inter (CSS side-effect) and re-exports typography tokens, kept out of tokens/ for portability.
 const fonts = typography;
 export default fonts;

package/dist/esm/Theme/chakra/motion.js

@@ -0,0 +1,34 @@
+import { useMatchMedia } from "../../Hooks/useMatchMedia.js";
+export const REDUCED_MOTION_QUERY = "@media (prefers-reduced-motion: reduce)";
+export const MOTION_OK_QUERY = "@media (prefers-reduced-motion: no-preference)";
+const MEDIA = "(prefers-reduced-motion: reduce)";
+export const usePrefersReducedMotion = () => useMatchMedia(MEDIA, false);
+/** Spread into `sx`: drops transitions and animations when the user asks for less motion. */
+export const reducedMotionSx = (overrides = {}) => ({
+    [REDUCED_MOTION_QUERY]: { transition: "none", animation: "none", ...overrides },
+});
+/** Add to an element whose loop is essential feedback; it and its subtree keep moving. */
+export const MOTION_KEEP_CLASS = "pz-motion-keep";
+const KEPT = [
+    ".chakra-spinner",
+    ".chakra-progress",
+    ".chakra-progress *",
+    `.${MOTION_KEEP_CLASS}`,
+    `.${MOTION_KEEP_CLASS} *`,
+];
+const notKept = KEPT.map((selector) => `:not(${selector})`).join("");
+export const REDUCED_MOTION_SELECTOR = [
+    `*${notKept}`,
+    `*${notKept}::before`,
+    `*${notKept}::after`,
+].join(", ");
+export const reducedMotionGlobalStyles = {
+    [REDUCED_MOTION_QUERY]: {
+        [REDUCED_MOTION_SELECTOR]: {
+            transitionDuration: "0.01ms !important",
+            animationDuration: "0.01ms !important",
+            animationIterationCount: "1 !important",
+            scrollBehavior: "auto !important",
+        },
+    },
+};

package/dist/esm/Theme/chakra/overlay.styles.js

@@ -0,0 +1,46 @@
+import { overlayScrim } from "../tokens/builders/scrim.js";
+import { raisedRule } from "../tokens/builders/surfaceRaised.js";
+import { RADIUS_ROLE } from "../tokens/primitives/radii.js";
+export const OVERLAY_BLUR = "blur(4px)";
+/** Radius and elevation every anchored popup shares: menus, popovers, selects, dropdowns. */
+export const POPUP_SURFACE = { borderRadius: RADIUS_ROLE.float, boxShadow: "md" };
+/** The one Modal/Drawer backdrop; reuse it for any custom full-screen scrim. */
+export const overlayScrimStyles = (colors) => ({
+    bg: overlayScrim(colors),
+    backdropFilter: OVERLAY_BLUR,
+});
+/** Shared dialog chrome for Modal and Drawer: surface, header/body/footer rhythm, close button. */
+export const dialogPartStyles = (colors) => ({
+    overlay: overlayScrimStyles(colors),
+    dialog: {
+        color: colors.text[900],
+        borderWidth: "1px",
+        borderStyle: "solid",
+        borderColor: colors.boxborder[200],
+        boxShadow: "lg",
+    },
+    header: {
+        px: 5,
+        py: 4,
+        pe: 12,
+        fontSize: "1rem",
+        fontWeight: 600,
+        lineHeight: 1.5,
+        color: colors.header[900],
+        borderBottomWidth: "1px",
+        borderBottomStyle: "solid",
+        borderBottomColor: raisedRule(colors),
+    },
+    closeButton: { top: 3, insetEnd: 4 },
+    body: { px: 5, py: 4 },
+    footer: {
+        px: 5,
+        py: 4,
+        display: "flex",
+        justifyContent: "flex-end",
+        gap: 3,
+        borderTopWidth: "1px",
+        borderTopStyle: "solid",
+        borderTopColor: raisedRule(colors),
+    },
+});

package/dist/esm/Theme/chakra/paletteFromTheme.js

@@ -1,9 +1,19 @@
 import { assertPixelizePalette } from "../assertPalette.js";
+import { scaleNamed } from "../tokens/builders/paletteScale.js";
 /** Chakra hands style functions an untyped theme; this is the boundary that makes it typed. */
 export const paletteOf = (theme) => assertPixelizePalette(theme);
-const asScale = (value) => typeof value === "object" && value !== null ? value : undefined;
-/**
- * `colorScheme` is a consumer-supplied Chakra scale name, so this lookup is genuinely dynamic —
- * it can name a built-in we never themed. An unknown name resolves to the neutral ramp.
- */
-export const scaleFor = (palette, colorScheme) => { var _a; return (_a = asScale(palette[colorScheme])) !== null && _a !== void 0 ? _a : palette.gray; };
+const warned = new Set();
+export const warnUnknownColorScheme = (colorScheme) => {
+    if (process.env.NODE_ENV === "production" || warned.has(colorScheme))
+        return;
+    warned.add(colorScheme);
+    console.warn(`[pixelize-design-library] colorScheme "${colorScheme}" is not a themed colour scale; using the fallback scale.`);
+};
+// NOTE: colorScheme is consumer-supplied and can name a built-in we never themed — unknowns use the fallback.
+export const scaleFor = (palette, colorScheme, fallback = palette.gray) => {
+    const scale = scaleNamed(palette, colorScheme);
+    if (scale)
+        return scale;
+    warnUnknownColorScheme(colorScheme);
+    return fallback;
+};

package/dist/esm/Theme/chakra/ringShadow.js

@@ -0,0 +1,3 @@
+import { BORDER_WIDTHS } from "../tokens/primitives/borderWidths.js";
+/** A stroke drawn inside the border box as a box-shadow, so it never costs layout. */
+export const insetRingShadow = (color, width = "hairline") => `inset 0 0 0 ${BORDER_WIDTHS[width]} ${color}`;

package/dist/esm/Theme/index.js

@@ -1,27 +1,20 @@
 import createBrandTheme from "./chakra/createBrandTheme.js";
 import { lightPalettes, darkPalettes } from "./tokens/brands/index.js";
-/**
- * Chakra themes per brand, built from the pure palettes in `tokens/brands`.
- *
- * These used to be seven near-identical `<Brand>/theme.ts` files that differed only in
- * which palette they imported; `createBrandTheme` is that shared body.
- */
+import { lazyObject } from "./tokens/builders/lazy.js";
+// NOTE: lavender is built at import as the shape template — every light theme shares its keys.
 const lavender = createBrandTheme(lightPalettes.lavender);
-const meadow = createBrandTheme(lightPalettes.meadow);
-const radiant = createBrandTheme(lightPalettes.radiant);
-const skyline = createBrandTheme(lightPalettes.skyline);
-const slate = createBrandTheme(lightPalettes.slate);
-const emerald = createBrandTheme(lightPalettes.emerald);
-const rosewood = createBrandTheme(lightPalettes.rosewood);
-const storefront = createBrandTheme(lightPalettes.storefront);
-const zinc = createBrandTheme(lightPalettes.zinc);
+const lightThemeKeys = Object.keys(lavender);
+const lazyLightTheme = (brand) => lazyObject(lightThemeKeys, () => createBrandTheme(lightPalettes[brand]));
+const meadow = lazyLightTheme("meadow");
+const radiant = lazyLightTheme("radiant");
+const skyline = lazyLightTheme("skyline");
+const slate = lazyLightTheme("slate");
+const emerald = lazyLightTheme("emerald");
+const rosewood = lazyLightTheme("rosewood");
+const storefront = lazyLightTheme("storefront");
+const zinc = lazyLightTheme("zinc");
 export { skyline, meadow, radiant, lavender, slate, emerald, rosewood, storefront, zinc };
-/**
- * Published contract — consumers iterate this to render theme pickers, so both the keys
- * and their order are load-bearing. Stays light-only: these are the exact theme objects
- * apps already pass to `withTheme`, and dark is opt-in via `PixelizeThemeProvider`.
- * `storefront`/`zinc` are appended at the end — additive, doesn't reorder existing entries.
- */
+// NOTE: consumers iterate this to render theme pickers — key order is load-bearing. Stays light-only.
 export const ThemesList = {
     lavender: lavender,
     meadow: meadow,
@@ -33,12 +26,7 @@ export const ThemesList = {
     storefront: storefront,
     zinc: zinc,
 };
-/**
- * `dark` is built on first read, not at import. Nine `createBrandTheme` calls measure ~15ms on a
- * dev machine, and a light-only app (tickets, and every app before it opts in) never reads one.
- * A getter — rather than a lazy map — keeps `Object.keys(brandThemes)` and its order intact,
- * which `ThemeSwitcher` iterates to render the brand picker.
- */
+// NOTE: dark is built on first read via a getter, not at import — keeps Object.keys() order intact for ThemeSwitcher.
 const withLazyDark = (brand, light) => {
     let dark;
     return {

package/dist/esm/Theme/provider/PixelizeThemeProvider.js

@@ -1,26 +1,14 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { createContext, useCallback, useDeferredValue, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
 import { ChakraProvider, extendTheme } from "@chakra-ui/react";
 import { brandThemes } from "../index.js";
 import ToasterProvider from "../../Components/Toaster/Toaster.js";
+import { reducedMotionGlobalStyles } from "../chakra/motion.js";
 import { getSystemColorMode, readStoredTheme, subscribeToSystemColorMode, writeStoredTheme, } from "./colorModeStorage.js";
 const DEFAULT_BRAND = "lavender";
 const DEFAULT_MODE = "system";
 const DEFAULT_STORAGE_KEY = "pixelize-theme";
-/**
- * Chakra's default `colorModeManager` reads/writes its OWN `localStorage["chakra-ui-color-mode"]`
- * key — entirely separate from this app's `storageKey` above — and that stored value wins over
- * `theme.config.initialColorMode` on every load. `createBrandTheme` sets `initialColorMode: "light"`
- * on every theme object specifically so Chakra's native dark mode (and every un-migrated built-in
- * `_dark:` block — Card's "elevated" variant reaches for `gray.700`, which our reversed dark ramp
- * makes LIGHT) never fires. But a stale `"dark"` value in that key — from Chakra's own toggle ever
- * having been used on this origin, by this app or a prior version of it — silently overrides that
- * default and reintroduces exactly the bug `initialColorMode: "light"` was meant to prevent: a
- * washed-out light Card on an otherwise-correct dark canvas, while everything reading the palette
- * directly (i.e. everything else) stays right. Forcing this manager to always report `"light"` and
- * never persist removes Chakra's native color mode from the equation entirely, so no stray
- * `_dark:` block anywhere (present or future) can ever fire, regardless of what's in storage.
- */
+// NOTE: forces Chakra's own color mode to "light" always — a stale chakra-ui-color-mode key would otherwise re-fire un-migrated `_dark:` blocks.
 const forcedLightColorModeManager = {
     type: "localStorage",
     ssr: false,
@@ -28,27 +16,10 @@ const forcedLightColorModeManager = {
     set: () => { },
 };
 export const ThemeModeContext = createContext(undefined);
-/**
- * Chakra's own color mode is deliberately NOT synced to `resolvedMode`, and must not be.
- *
- * This provider adapts for dark by swapping the palette, so `theme.colors` is already correct for
- * the active mode. Putting Chakra into dark mode on top of that adapts a second time: its built-in
- * `_dark` blocks reach for `gray.700`/`gray.800` expecting those rungs to be dark, but our dark
- * ramp runs dark -> light, so they resolve LIGHT — a white Card/Skeleton/Menu on a dark canvas.
- * A previous revision synced it to keep `useColorModeValue()` working and shipped exactly that.
- *
- * Consequence for consumers: `useColorModeValue(light, dark)` always returns its LIGHT argument.
- * That is correct here — the palette has already resolved the mode, so the "light" argument is
- * whatever the active palette says. Read the mode from `useThemeMode()` instead. Existing apps are
- * unaffected: they are light-only, where that argument was always the one returned anyway.
- */
-export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRAND, onBrandChange, defaultMode = DEFAULT_MODE, onModeChange, storageKey = DEFAULT_STORAGE_KEY, disablePersistence = false, themeOverrides, }) => {
-    // Seed from storage during the first render: StrictMode re-runs the persist effect, and a
-    // ref guard cannot stop that second pass writing defaults over the stored value.
+// NOTE: Chakra's own color mode stays unsynced from resolvedMode — its built-in `_dark:` blocks assume the opposite ramp direction. Read mode via useThemeMode(), not useColorModeValue().
+export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRAND, onBrandChange, defaultMode = DEFAULT_MODE, onModeChange, storageKey = DEFAULT_STORAGE_KEY, disablePersistence = false, themeOverrides, reducedMotion = "components", }) => {
     const [mode, setModeState] = useState(() => { var _a; return (_a = (disablePersistence ? undefined : readStoredTheme(storageKey).mode)) !== null && _a !== void 0 ? _a : defaultMode; });
     const [brand, setBrandState] = useState(() => { var _a; return (_a = (disablePersistence ? undefined : readStoredTheme(storageKey).brand)) !== null && _a !== void 0 ? _a : brandProp; });
-    // Read synchronously: seeding "light" made every `system` user on a dark OS paint a light
-    // frame before the effect corrected it. SSR-safe — returns "light" with no window.
     const [systemMode, setSystemMode] = useState(getSystemColorMode);
     useEffect(() => {
         setSystemMode(getSystemColorMode());
@@ -63,12 +34,6 @@ export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRA
         if (stored.brand)
             setBrandState(stored.brand);
     }, [disablePersistence, storageKey]);
-    // `brandProp` only seeds initial state above, so a consumer that re-renders with a new
-    // `brand` prop after mount (e.g. persisting the pick through its own store, like tickets'
-    // Settings page dispatching Redux instead of calling `setBrand`) would otherwise never see
-    // it applied. Sync it here instead so every consumer gets it for free.
-    // Compare the previous prop, never a "first run" flag: StrictMode double-invokes effects while
-    // refs survive, so a flag guard lets pass 2 reset state to the prop and clobber stored values.
     const prevBrandProp = useRef(brandProp);
     useEffect(() => {
         if (prevBrandProp.current === brandProp)
@@ -76,8 +41,6 @@ export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRA
         prevBrandProp.current = brandProp;
         setBrandState(brandProp);
     }, [brandProp]);
-    // Same prop-sync for the mode, so an app owning it in its own store no longer needs the
-    // `mode` -> store mirror effect that deadlocks against this one.
     const prevModeProp = useRef(defaultMode);
     useEffect(() => {
         if (prevModeProp.current === defaultMode)
@@ -85,8 +48,6 @@ export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRA
         prevModeProp.current = defaultMode;
         setModeState(defaultMode);
     }, [defaultMode]);
-    // Skipping the mount run keeps the defaults from being written over a stored value before
-    // the rehydrate effect above has applied it.
     const isFirstPersistRun = useRef(true);
     useEffect(() => {
         if (isFirstPersistRun.current) {
@@ -98,26 +59,17 @@ export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRA
         writeStoredTheme(storageKey, { mode, brand });
     }, [mode, brand, disablePersistence, storageKey]);
     const resolvedMode = mode === "system" ? systemMode : mode;
-    /**
-     * Native browser UI (the `<select>` dropdown popup chrome, the `<input type="date">` calendar
-     * picker) is painted by the browser's own UA stylesheet keyed off the CSS `color-scheme`
-     * property, entirely separate from Chakra/React theming — no component style or palette swap
-     * above can reach it. Without this, that chrome always renders light, even on an otherwise dark
-     * page. Scoped to this provider (not a global stylesheet) so `withTheme` consumers — deliberately
-     * light-only, see the module doc's "Key rules" — are untouched.
-     */
+    // NOTE: the page re-themes in an interruptible second commit; the switcher paints first.
+    const appliedMode = useDeferredValue(resolvedMode);
+    const appliedBrand = useDeferredValue(brand);
+    // NOTE: sets CSS color-scheme so native chrome (select popups, date pickers) matches the mode.
     useLayoutEffect(() => {
-        document.documentElement.style.colorScheme = resolvedMode;
-    }, [resolvedMode]);
-    // Chakra's ColorModeProvider re-writes color-scheme in a passive effect, after the layout
-    // effect above, and forcedLightColorModeManager pins it to "light". Re-assert after it.
+        document.documentElement.style.colorScheme = appliedMode;
+    }, [appliedMode]);
+    // NOTE: re-asserted after Chakra's own ColorModeProvider effect overwrites it back to "light".
     useEffect(() => {
-        document.documentElement.style.colorScheme = resolvedMode;
-    }, [resolvedMode]);
-    // Held in refs so a caller's inline arrow never re-creates `setMode`/`setBrand`, which would
-    // invalidate the context value on every render of the consuming app. Written in a layout
-    // effect, not during render — a render-phase write is unsafe under StrictMode's double
-    // invocation, and this still lands before any click handler can fire.
+        document.documentElement.style.colorScheme = appliedMode;
+    }, [appliedMode]);
     const onModeChangeRef = useRef(onModeChange);
     const onBrandChangeRef = useRef(onBrandChange);
     useLayoutEffect(() => {
@@ -134,33 +86,23 @@ export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRA
         setBrandState(next);
         (_a = onBrandChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onBrandChangeRef, next);
     }, []);
-    // From "system", flip to the opposite of what the OS currently gives, so a click always
-    // visibly changes the UI.
     const toggle = useCallback(() => setMode(resolvedMode === "dark" ? "light" : "dark"), [resolvedMode, setMode]);
     const value = useMemo(() => ({ mode, resolvedMode, setMode, toggle, brand, setBrand }), [mode, resolvedMode, setMode, toggle, brand, setBrand]);
-    // `themeOverrides` is caller-supplied, and the idiomatic way to pass it is an inline object
-    // literal — a new identity every render. Keying the memo on identity would re-run `extendTheme`
-    // and hand `ChakraProvider` a new theme on every render of the consuming app, invalidating
-    // emotion's style resolution for everything beneath it. Compare by value instead.
+    // NOTE: keyed by value, not identity — themeOverrides is usually an inline literal.
     const overridesKey = themeOverrides ? JSON.stringify(themeOverrides) : "";
     const resolvedTheme = useMemo(() => {
-        const base = brandThemes[brand][resolvedMode];
-        return themeOverrides ? extendTheme(base, themeOverrides) : base;
-        // Keyed on the serialized overrides, not their identity. `brand`/`resolvedMode` must stay:
-        // overrides re-layer onto the CURRENT palette (see the prop's doc comment above).
+        const base = brandThemes[appliedBrand][appliedMode];
+        const extensions = [
+            ...(reducedMotion === "global" ? [{ styles: { global: reducedMotionGlobalStyles } }] : []),
+            ...(themeOverrides ? [themeOverrides] : []),
+        ];
+        return extensions.length ? extendTheme(base, ...extensions) : base;
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [brand, resolvedMode, overridesKey]);
-    /**
-     * The library ships its `var(--color-*)` tokens light-only on `:root` (global.css), so any
-     * consumer that styles with those CSS vars rather than Chakra tokens stays light in dark mode —
-     * invisible text on the dark canvas, white panels. In dark, re-point every used var at the
-     * already-dark-correct resolved palette; in light, clear them so the static `:root` values apply
-     * unchanged (so a light-only app is byte-identical to before). Also mirror the mode to
-     * `data-mode` for consumers that want to hook their own dark CSS.
-     */
+    }, [appliedBrand, appliedMode, overridesKey, reducedMotion]);
+    // NOTE: global.css ships var(--color-*) light-only — re-point them here in dark, clear in light.
     useLayoutEffect(() => {
         const root = document.documentElement;
-        root.dataset.mode = resolvedMode;
+        root.dataset.mode = appliedMode;
         const { colors } = resolvedTheme;
         const { gray, semantic } = colors;
         const HUE_SCALES = [
@@ -169,8 +111,6 @@ export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRA
         ];
         const SEMANTIC_SCALES = ["success", "error", "warning", "info"];
         const RUNGS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
-        // The dark gray ramp runs dark(50) → light(900), so low rungs read as surfaces
-        // and high rungs as text — correct in dark, cleared in light.
         const SEMANTIC_VARS = {
             "text-heading": gray[900], "text-body": gray[700],
             "text-subtle": gray[500], "text-input": gray[500],
@@ -186,7 +126,7 @@ export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRA
         const set = (name, val) => root.style.setProperty(`--color-${name}`, val);
         const clear = (name) => root.style.removeProperty(`--color-${name}`);
         const allRampNames = [...HUE_SCALES, ...SEMANTIC_SCALES].flatMap((s) => RUNGS.map((r) => `${s}-${r}`));
-        if (resolvedMode === "dark") {
+        if (appliedMode === "dark") {
             for (const s of HUE_SCALES)
                 for (const r of RUNGS)
                     set(`${s}-${r}`, colors[s][r]);
@@ -202,6 +142,7 @@ export const PixelizeThemeProvider = ({ children, brand: brandProp = DEFAULT_BRA
             for (const name of Object.keys(SEMANTIC_VARS))
                 clear(name);
         }
-    }, [resolvedMode, resolvedTheme]);
-    return (_jsx(ThemeModeContext.Provider, { value: value, children: _jsx(ChakraProvider, { theme: resolvedTheme, colorModeManager: forcedLightColorModeManager, children: _jsx(ToasterProvider, { children: children }) }) }));
+    }, [appliedMode, resolvedTheme]);
+    const themedTree = useMemo(() => (_jsx(ChakraProvider, { theme: resolvedTheme, colorModeManager: forcedLightColorModeManager, children: _jsx(ToasterProvider, { children: children }) })), [resolvedTheme, children]);
+    return _jsx(ThemeModeContext.Provider, { value: value, children: themedTree });
 };