pixelize-design-library 2.4.2-beta.43 → 2.4.2-beta.45

package/dist/Theme/chakra/createBrandTheme.js

@@ -11,16 +11,7 @@ const componentStyles_1 = require("./componentStyles");
 const filledSurface_1 = require("../tokens/builders/filledSurface");
 const scrollbar_1 = require("../tokens/builders/scrollbar");
 const focusRing_styles_1 = require("./focusRing.styles");
-/**
- * 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.
- */
+// Builds a Chakra theme from a pure brand palette — dark mode works by swapping which palette it carries.
 const createBrandTheme = (palette, options = {}) => {
     var _a;
     const colorMode = (_a = options.colorMode) !== null && _a !== void 0 ? _a : "light";
@@ -28,54 +19,28 @@ const createBrandTheme = (palette, options = {}) => {
         colors: palette,
         ...fonts_web_1.default,
         ...common_web_1.default,
-        // `shadows.outline` is what Chakra's stock `_focusVisible` reaches for on EVERY component it
-        // themes. The primitive ships one hardcoded blue (`rgba(66,153,225,.6)`), which measured
-        // 1.83:1 on the lavender canvas and 1.38:1 on a primary button — below 1.4.11's 3:1 on all
-        // nine brands, in both modes. A primitive cannot know the palette; this is the first place
-        // that does, so the palette-derived ring is bound here and every stock focus state inherits it.
+        // NOTE: binds the palette-derived ring to shadows.outline — Chakra's stock one failed 1.4.11 on every brand.
         shadows: { ...common_web_1.default.shadows, outline: (0, focusRing_styles_1.focusRingShadow)(palette) },
     };
     return (0, react_1.extendTheme)({
         ...brand,
         config: {
             ...common_web_1.default.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",
                         },
@@ -83,11 +48,7 @@ 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.
+                        // NOTE: ::selection isn't covered by color-scheme — branded here with the same onFilled math as buttons.
                         "::selection": (() => {
                             const solid = (0, filledSurface_1.resolveFilledSurface)(palette.primary, palette);
                             return {
@@ -102,13 +63,8 @@ const createBrandTheme = (palette, options = {}) => {
                                 color: solid.color,
                             };
                         })(),
-                        // `color-scheme: dark` gives WebKit/Blink a dark scrollbar by default, but it's the
-                        // OS's generic dark gray, not brand-aware.
                         ...(0, scrollbar_1.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],

package/dist/Theme/chakra/focusRing.styles.d.ts

@@ -1,9 +1,4 @@
-import type { FocusRingTokens } from "../tokens/types";
-/**
- * WEB binding for the `focusRing` token pair. The colours are derived in
- * `tokens/builders/focusRing.ts` (pure, shared with the mobile library); the CSS shape —
- * box-shadow bands, the forced-colors outline — is web-only and lives here.
- */
+import type { BrandScale, FocusRingTokens } from "../tokens/types";
 /** Inner band, in the surface tone: separates the ring from the control's own fill. */
 export declare const FOCUS_HALO_WIDTH = 2;
 /** Outer edge of the brand band. The band itself is the 2px between halo and ring. */
@@ -11,31 +6,29 @@ export declare const FOCUS_RING_WIDTH = 4;
 type WithFocusRing = {
     focusRing: FocusRingTokens;
 };
-/**
- * The two-tone ring as a single `box-shadow`. Drawn OUTSIDE the border box, so it costs no
- * layout and never resizes the control — the reason this is a shadow and not an outline.
- */
+type WithBrandGlow = {
+    primary: BrandScale;
+};
 export declare const focusRingShadow: (colors: WithFocusRing) => string;
-/**
- * `:hover`, `:active` and `:focus-visible` all score the same specificity, so which one paints
- * comes down to source order — and in the merged style object Chakra's own Button baseStyle
- * registers `_focusVisible` BEFORE `_hover`. A focused button that is also hovered would then
- * drop the ring for `_hover`'s `boxShadow: "sm"`. Stacking the pseudo-classes raises the
- * specificity above both, so the ring survives whatever else the state repaints.
- */
 export declare const FOCUS_VISIBLE_OVER_STATE = "&:hover:focus-visible, &:active:focus-visible, &[data-active]:focus-visible";
-/**
- * `:focus-visible`, never `:focus` — a mouse click must not draw a ring.
- *
- * The transparent outline is not decoration: in Windows High Contrast / `forced-colors` mode
- * box-shadows are dropped entirely, and a transparent outline is the one thing the OS repaints
- * in its own focus colour. Without it, forced-colors users get no indicator at all.
- */
 export declare const focusVisibleRing: (colors: WithFocusRing) => {
     outline: string;
     outlineOffset: string;
     boxShadow: string;
 };
+/** Blurred, never a flat band: a band has a hard outer edge at every opacity and reads as a second border. */
+export declare const FOCUS_GLOW_BLUR = 6;
+/** Negative spread keeps the bloom tight to the border instead of haloing the whole control. */
+export declare const FOCUS_GLOW_SPREAD = -1;
+/** Step on `primary.opacity`. Safe to raise because a blur has no edge to sharpen. */
+export declare const FOCUS_GLOW_ALPHA = 32;
+export declare const focusGlowShadow: (colors: WithBrandGlow) => string;
+/** Field focus: the brand border is the indicator, this only makes it findable. */
+export declare const fieldFocusVisible: (colors: WithBrandGlow) => {
+    outline: string;
+    outlineOffset: string;
+    boxShadow: string;
+};
 /** Both selectors a control needs to keep the ring on top of its own hover/active styling. */
 export declare const focusVisibleStyles: (colors: WithFocusRing) => {
     _focusVisible: {

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

@@ -1,43 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.focusVisibleStyles = exports.focusVisibleRing = exports.FOCUS_VISIBLE_OVER_STATE = exports.focusRingShadow = exports.FOCUS_RING_WIDTH = exports.FOCUS_HALO_WIDTH = void 0;
-/**
- * WEB binding for the `focusRing` token pair. The colours are derived in
- * `tokens/builders/focusRing.ts` (pure, shared with the mobile library); the CSS shape —
- * box-shadow bands, the forced-colors outline — is web-only and lives here.
- */
+exports.focusVisibleStyles = exports.fieldFocusVisible = exports.focusGlowShadow = exports.FOCUS_GLOW_ALPHA = exports.FOCUS_GLOW_SPREAD = exports.FOCUS_GLOW_BLUR = exports.focusVisibleRing = exports.FOCUS_VISIBLE_OVER_STATE = exports.focusRingShadow = exports.FOCUS_RING_WIDTH = exports.FOCUS_HALO_WIDTH = void 0;
+// 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. */
 exports.FOCUS_HALO_WIDTH = 2;
 /** Outer edge of the brand band. The band itself is the 2px between halo and ring. */
 exports.FOCUS_RING_WIDTH = 4;
-/**
- * The two-tone ring as a single `box-shadow`. Drawn OUTSIDE the border box, so it costs no
- * layout and never resizes the control — the reason this is a shadow and not an outline.
- */
+// NOTE: a box-shadow, not an outline — drawn outside the border box so it never resizes the control.
 const focusRingShadow = (colors) => `0 0 0 ${exports.FOCUS_HALO_WIDTH}px ${colors.focusRing.halo}, ` +
     `0 0 0 ${exports.FOCUS_RING_WIDTH}px ${colors.focusRing.ring}`;
 exports.focusRingShadow = focusRingShadow;
-/**
- * `:hover`, `:active` and `:focus-visible` all score the same specificity, so which one paints
- * comes down to source order — and in the merged style object Chakra's own Button baseStyle
- * registers `_focusVisible` BEFORE `_hover`. A focused button that is also hovered would then
- * drop the ring for `_hover`'s `boxShadow: "sm"`. Stacking the pseudo-classes raises the
- * specificity above both, so the ring survives whatever else the state repaints.
- */
+// NOTE: stacked pseudo-classes raise specificity above Chakra's _hover, so a hovered+focused button keeps its ring.
 exports.FOCUS_VISIBLE_OVER_STATE = "&:hover:focus-visible, &:active:focus-visible, &[data-active]:focus-visible";
-/**
- * `:focus-visible`, never `:focus` — a mouse click must not draw a ring.
- *
- * The transparent outline is not decoration: in Windows High Contrast / `forced-colors` mode
- * box-shadows are dropped entirely, and a transparent outline is the one thing the OS repaints
- * in its own focus colour. Without it, forced-colors users get no indicator at all.
- */
+// NOTE: transparent outline isn't decorative — forced-colors mode drops box-shadow but repaints an outline.
 const focusVisibleRing = (colors) => ({
     outline: "2px solid transparent",
     outlineOffset: "2px",
     boxShadow: (0, exports.focusRingShadow)(colors),
 });
 exports.focusVisibleRing = focusVisibleRing;
+/** Blurred, never a flat band: a band has a hard outer edge at every opacity and reads as a second border. */
+exports.FOCUS_GLOW_BLUR = 6;
+/** Negative spread keeps the bloom tight to the border instead of haloing the whole control. */
+exports.FOCUS_GLOW_SPREAD = -1;
+/** Step on `primary.opacity`. Safe to raise because a blur has no edge to sharpen. */
+exports.FOCUS_GLOW_ALPHA = 32;
+const focusGlowShadow = (colors) => `0 0 ${exports.FOCUS_GLOW_BLUR}px ${exports.FOCUS_GLOW_SPREAD}px ${colors.primary.opacity[exports.FOCUS_GLOW_ALPHA]}`;
+exports.focusGlowShadow = focusGlowShadow;
+/** Field focus: the brand border is the indicator, this only makes it findable. */
+const fieldFocusVisible = (colors) => ({
+    outline: "2px solid transparent",
+    outlineOffset: "2px",
+    boxShadow: (0, exports.focusGlowShadow)(colors),
+});
+exports.fieldFocusVisible = fieldFocusVisible;
 /** Both selectors a control needs to keep the ring on top of its own hover/active styling. */
 const focusVisibleStyles = (colors) => {
     const ring = (0, exports.focusVisibleRing)(colors);

package/dist/Theme/chakra/fonts.web.d.ts

@@ -1,10 +1,5 @@
 /** Self-hosted Inter Variable (wght 100–900); required for theme fontWeights to render correctly. */
 import "@fontsource-variable/inter/index.css";
-/**
- * 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.
- */
 declare const fonts: {
     fonts: {
         body: string;

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

@@ -6,10 +6,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /** Self-hosted Inter Variable (wght 100–900); required for theme fontWeights to render correctly. */
 require("@fontsource-variable/inter/index.css");
 const typography_1 = __importDefault(require("../tokens/primitives/typography"));
-/**
- * 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_1.default;
 exports.default = fonts;

package/dist/Theme/chakra/motion.d.ts

@@ -0,0 +1,5 @@
+import type { SystemStyleObject } from "@chakra-ui/react";
+export declare const REDUCED_MOTION_QUERY = "@media (prefers-reduced-motion: reduce)";
+export declare const usePrefersReducedMotion: () => boolean;
+/** Spread into `sx`: drops transitions and animations when the user asks for less motion. */
+export declare const reducedMotionSx: (overrides?: SystemStyleObject) => SystemStyleObject;

package/dist/Theme/chakra/motion.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reducedMotionSx = exports.usePrefersReducedMotion = exports.REDUCED_MOTION_QUERY = void 0;
+const react_1 = require("react");
+exports.REDUCED_MOTION_QUERY = "@media (prefers-reduced-motion: reduce)";
+const MEDIA = "(prefers-reduced-motion: reduce)";
+// NOTE: jsdom has no matchMedia; Chakra's hook throws there and breaks consumer test suites.
+const hasMatchMedia = () => typeof window !== "undefined" && typeof window.matchMedia === "function";
+const readPreference = () => hasMatchMedia() && window.matchMedia(MEDIA).matches;
+const usePrefersReducedMotion = () => {
+    const [reduced, setReduced] = (0, react_1.useState)(readPreference);
+    (0, react_1.useEffect)(() => {
+        if (!hasMatchMedia())
+            return;
+        const query = window.matchMedia(MEDIA);
+        const onChange = () => setReduced(query.matches);
+        query.addEventListener("change", onChange);
+        return () => query.removeEventListener("change", onChange);
+    }, []);
+    return reduced;
+};
+exports.usePrefersReducedMotion = usePrefersReducedMotion;
+/** Spread into `sx`: drops transitions and animations when the user asks for less motion. */
+const reducedMotionSx = (overrides = {}) => ({
+    [exports.REDUCED_MOTION_QUERY]: { transition: "none", animation: "none", ...overrides },
+});
+exports.reducedMotionSx = reducedMotionSx;

package/dist/Theme/chakra/overlay.styles.d.ts

@@ -0,0 +1,51 @@
+import type { PaletteProps } from "../tokens/types";
+export declare const OVERLAY_BLUR = "blur(4px)";
+/** The one Modal/Drawer backdrop; reuse it for any custom full-screen scrim. */
+export declare const overlayScrimStyles: (colors: Pick<PaletteProps, "black">) => {
+    bg: string;
+    backdropFilter: string;
+};
+/** Shared dialog chrome for Modal and Drawer: surface, header/body/footer rhythm, close button. */
+export declare const dialogPartStyles: (colors: PaletteProps) => {
+    overlay: {
+        bg: string;
+        backdropFilter: string;
+    };
+    dialog: {
+        color: string;
+        borderWidth: string;
+        borderStyle: string;
+        borderColor: string;
+        boxShadow: string;
+    };
+    header: {
+        px: number;
+        py: number;
+        pe: number;
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: number;
+        color: string;
+        borderBottomWidth: string;
+        borderBottomStyle: string;
+        borderBottomColor: string;
+    };
+    closeButton: {
+        top: number;
+        insetEnd: number;
+    };
+    body: {
+        px: number;
+        py: number;
+    };
+    footer: {
+        px: number;
+        py: number;
+        display: string;
+        justifyContent: string;
+        gap: number;
+        borderTopWidth: string;
+        borderTopStyle: string;
+        borderTopColor: string;
+    };
+};

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

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dialogPartStyles = exports.overlayScrimStyles = exports.OVERLAY_BLUR = void 0;
+const scrim_1 = require("../tokens/builders/scrim");
+const surfaceRaised_1 = require("../tokens/builders/surfaceRaised");
+exports.OVERLAY_BLUR = "blur(4px)";
+/** The one Modal/Drawer backdrop; reuse it for any custom full-screen scrim. */
+const overlayScrimStyles = (colors) => ({
+    bg: (0, scrim_1.overlayScrim)(colors),
+    backdropFilter: exports.OVERLAY_BLUR,
+});
+exports.overlayScrimStyles = overlayScrimStyles;
+/** Shared dialog chrome for Modal and Drawer: surface, header/body/footer rhythm, close button. */
+const dialogPartStyles = (colors) => ({
+    overlay: (0, exports.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: (0, surfaceRaised_1.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: (0, surfaceRaised_1.raisedRule)(colors),
+    },
+});
+exports.dialogPartStyles = dialogPartStyles;

package/dist/Theme/chakra/paletteFromTheme.d.ts

@@ -3,8 +3,4 @@ import type { ColorScale, PaletteProps } from "../tokens/types";
 export declare const paletteOf: (theme: {
     colors?: unknown;
 }) => PaletteProps;
-/**
- * `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 declare const scaleFor: (palette: PaletteProps, colorScheme: string) => ColorScale;

package/dist/Theme/chakra/paletteFromTheme.js

@@ -6,9 +6,6 @@ const assertPalette_1 = require("../assertPalette");
 const paletteOf = (theme) => (0, assertPalette_1.assertPixelizePalette)(theme);
 exports.paletteOf = paletteOf;
 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.
- */
+// NOTE: colorScheme is consumer-supplied and can name a built-in we never themed — unknowns resolve to gray.
 const scaleFor = (palette, colorScheme) => { var _a; return (_a = asScale(palette[colorScheme])) !== null && _a !== void 0 ? _a : palette.gray; };
 exports.scaleFor = scaleFor;

package/dist/Theme/index.d.ts

@@ -1,11 +1,5 @@
 import createBrandTheme from "./chakra/createBrandTheme";
 import type { ResolvedColorMode, ThemeName } from "./tokens/types";
-/**
- * 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.
- */
 declare const lavender: Record<string, any>;
 declare const meadow: Record<string, any>;
 declare const radiant: Record<string, any>;
@@ -16,12 +10,6 @@ declare const rosewood: Record<string, any>;
 declare const storefront: Record<string, any>;
 declare const zinc: Record<string, any>;
 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.
- */
 export declare const ThemesList: {
     lavender: Record<string, any>;
     meadow: Record<string, any>;

package/dist/Theme/index.js

@@ -6,12 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.brandThemes = exports.ThemesList = exports.zinc = exports.storefront = exports.rosewood = exports.emerald = exports.slate = exports.lavender = exports.radiant = exports.meadow = exports.skyline = void 0;
 const createBrandTheme_1 = __importDefault(require("./chakra/createBrandTheme"));
 const brands_1 = require("./tokens/brands");
-/**
- * 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.
- */
+// Chakra themes per brand, built from the pure palettes in tokens/brands via createBrandTheme.
 const lavender = (0, createBrandTheme_1.default)(brands_1.lightPalettes.lavender);
 exports.lavender = lavender;
 const meadow = (0, createBrandTheme_1.default)(brands_1.lightPalettes.meadow);
@@ -30,12 +25,7 @@ const storefront = (0, createBrandTheme_1.default)(brands_1.lightPalettes.storef
 exports.storefront = storefront;
 const zinc = (0, createBrandTheme_1.default)(brands_1.lightPalettes.zinc);
 exports.zinc = 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.
 exports.ThemesList = {
     lavender: lavender,
     meadow: meadow,
@@ -47,12 +37,7 @@ exports.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/Theme/provider/PixelizeThemeProvider.d.ts

@@ -10,45 +10,13 @@ export type ThemeModeContextValue = {
 };
 export type PixelizeThemeProviderProps = {
     children: React.ReactNode;
-    /** Initial brand. A persisted brand wins over this. Re-synced if the prop changes after mount. */
     brand?: ThemeName;
-    /** Brand counterpart of `onModeChange`, with the same user-intent-only contract. */
     onBrandChange?: (brand: ThemeName) => void;
-    /** Initial color mode. A persisted mode wins over this. Re-synced if the prop changes after mount. */
     defaultMode?: ColorMode;
-    /**
-     * Fired only when the mode changes through `setMode`/`toggle` — i.e. user intent. It is NOT
-     * fired when a changed `defaultMode` prop is synced in, which is what makes it safe to persist
-     * from: an app that instead mirrors `mode` in an effect re-persists its own echo, and if that
-     * store feeds `defaultMode` back the two ends flip each other forever.
-     */
     onModeChange?: (mode: ColorMode) => void;
     storageKey?: string;
     disablePersistence?: boolean;
-    /**
-     * App-specific theme overrides (fonts, sizes, component defaultProps, zIndices, ...) merged
-     * onto the resolved `brandThemes[brand][resolvedMode]` via `extendTheme`. Re-evaluated whenever
-     * `brand`/`resolvedMode` change, so overrides always layer onto the CURRENT palette rather than
-     * a stale one. Safe to merge post-resolution: `createBrandTheme` already fixes
-     * `config.initialColorMode` to `"light"` on every palette, and `extendTheme` is a pure additive
-     * merge — it does not re-derive `_dark:` blocks or re-run color-mode resolution, so this cannot
-     * reintroduce the double-adaptation bug `forcedLightColorModeManager` avoids (see above).
-     */
     themeOverrides?: Record<string, unknown>;
 };
 export declare const ThemeModeContext: React.Context<ThemeModeContextValue | 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 declare const PixelizeThemeProvider: ({ children, brand: brandProp, onBrandChange, defaultMode, onModeChange, storageKey, disablePersistence, themeOverrides, }: PixelizeThemeProviderProps) => import("react/jsx-runtime").JSX.Element;