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

package/dist/esm/Theme/index.js

@@ -1,11 +1,6 @@
 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.
- */
+// Chakra themes per brand, built from the pure palettes in tokens/brands via createBrandTheme.
 const lavender = createBrandTheme(lightPalettes.lavender);
 const meadow = createBrandTheme(lightPalettes.meadow);
 const radiant = createBrandTheme(lightPalettes.radiant);
@@ -16,12 +11,7 @@ const rosewood = createBrandTheme(lightPalettes.rosewood);
 const storefront = createBrandTheme(lightPalettes.storefront);
 const zinc = createBrandTheme(lightPalettes.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 +23,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

@@ -7,20 +7,7 @@ import { getSystemColorMode, readStoredTheme, subscribeToSystemColorMode, writeS
 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 +15,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.
- */
+// 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, }) => {
-    // 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.
     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 +33,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 +40,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 +47,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 +58,14 @@ 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: 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.
+    // 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.
     const onModeChangeRef = useRef(onModeChange);
     const onBrandChangeRef = useRef(onBrandChange);
     useLayoutEffect(() => {
@@ -134,30 +82,16 @@ 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).
         // 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.
-     */
+    // 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;
@@ -169,8 +103,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],

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

@@ -16,21 +16,13 @@ const SIZES = {
     lg: { control: "lg", icon: 18 },
 };
 const toBrandLabel = (brand) => brand.charAt(0).toUpperCase() + brand.slice(1);
-/**
- * Same swatch each brand's own theme carries at `colors.primary[500]` (the
- * anchor a filled button reads) — resolved per brand from its OWN palette so
- * the dot always matches what selecting that brand actually looks like,
- * regardless of which brand/mode is currently active.
- */
+// NOTE: resolved from each brand's OWN palette so the dot matches that brand, regardless of the active one.
 const brandSwatchColor = (brand) => brandThemes[brand].light.colors.primary[500];
 const BrandSwatch = ({ brand }) => {
     const { colors } = useCustomTheme();
     return (_jsx(Box, { as: "span", display: "inline-block", w: "0.625rem", h: "0.625rem", borderRadius: "full", bg: brandSwatchColor(brand), border: "1px solid", borderColor: colors.boxborder[200], flexShrink: 0 }));
 };
-/**
- * Palette values already differ per color mode (`brandThemes[brand].light|dark`), so tokens
- * are read straight from the active theme — no `useColorModeValue` pairing needed here.
- */
+// Palette already differs per mode, so tokens read straight from the active theme — no useColorModeValue needed.
 const useSwitcherColors = () => {
     const { colors } = useCustomTheme();
     return {

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

@@ -1,8 +1,5 @@
 const DARK_QUERY = "(prefers-color-scheme: dark)";
-/**
- * Stored values are untrusted input — a stale or hand-edited entry must never reach
- * `brandThemes[brand]` and hand Chakra an `undefined` theme.
- */
+// NOTE: stored values are untrusted — a stale/hand-edited entry must never reach brandThemes[brand] as undefined.
 const VALID_MODES = ["light", "dark", "system"];
 const VALID_BRANDS = [
     "lavender",

package/dist/esm/Theme/tokens/brands/emerald/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the emerald brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/emerald/palette.light.js

@@ -18,10 +18,7 @@ const primary = {
 const palette = {
     ...neutralTokens,
     ...buildBrandInk(PRIMARY_500),
-    // Stops retuned so white gradient-button text (onGradient, accentText.ts) clears AA at both
-    // ends — the original pair let white drop to 3.38/2.43 against from/to. Same hue, darker.
-    // Both nudged one step further (4.537/4.515 -> 4.618/4.616): the first pass cleared AA by
-    // <0.02, too thin a margin to trust against rounding/rendering variance.
+    // NOTE: stops retuned so white gradient-button text clears AA at both ends — original let it drop to 3.38/2.43.
     gradient: { from: "#0d8474", to: "#048096" }, // teal → cyan
     primary,
     // 🌫️ Neutral gray (slightly cool to match teal)
@@ -31,12 +28,7 @@ const palette = {
         200: "#dce5e5",
         300: "#c3d2d2",
         400: "#9fb3b3",
-        // Retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff — a value that
-        // clears AA by <0.02 is treated as failing, see Wave D QA follow-up) against every
-        // backgroundColor surface it's actually rendered on (main/secondary/light/subtle —
-        // verified via usage grep). muted/accent/tertiary/etc. have 0-1 live call sites today and
-        // none pair them with gray[500] text; going dark enough to also clear those would push
-        // past gray[600]'s own lightness and break the ramp order.
+        // NOTE: retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff) against live backgroundColor surfaces.
         500: "#617474",
         600: "#5e7070",
         700: "#475555",

package/dist/esm/Theme/tokens/brands/index.js

@@ -24,6 +24,7 @@ import { buildSemanticText, buildOnSemantic } from "../builders/semanticText.js"
 import { withPlaceholderRung, withTableHoverRung } from "../builders/resolvedRungs.js";
 import { buildFocusRing, withFocusRing } from "../builders/focusRing.js";
 import { withSurfaceRungs } from "../builders/surfaceRungs.js";
+import { buildSurfaceRaised, withSurfaceRaised } from "../builders/surfaceRaised.js";
 /** Derived, never hand-written: a copied hex goes stale the moment a canvas moves. */
 export const finalizeLightPalette = (source) => ({
     ...source,
@@ -34,13 +35,12 @@ export const finalizeLightPalette = (source) => ({
     onPrimary: onFilled(source.primary[500], source.white, source.black),
     onSemantic: buildOnSemantic(source.semantic, source.white, source.black),
     focusRing: buildFocusRing(source),
+    surfaceRaised: buildSurfaceRaised(source),
 });
 export { lavender, meadow, radiant, skyline, slate, emerald, rosewood, storefront, zinc };
 export { lavenderDark, meadowDark, radiantDark, skylineDark, slateDark, emeraldDark, rosewoodDark, storefrontDark, zincDark, };
-// `withFocusRing` is outermost: it is the only step that reads `primary` and the surfaces
-// TOGETHER, so it must see both after every earlier step — and after a brand file's own
-// post-derivation overrides (zinc dark replaces `primary` and `background` wholesale).
-const resolveRungs = (palette) => withFocusRing(withSurfaceRungs(withTableHoverRung(withPlaceholderRung(withOutlineRung(palette)))));
+// NOTE: withFocusRing is outermost — it must see primary and surfaces together, after every earlier step.
+const resolveRungs = (palette) => withFocusRing(withSurfaceRungs(withSurfaceRaised(withTableHoverRung(withPlaceholderRung(withOutlineRung(palette))))));
 const lightBrand = (source) => resolveRungs(finalizeLightPalette(source));
 /** Light palette per brand. `lavender` is the base the other six extend. */
 export const lightPalettes = {

package/dist/esm/Theme/tokens/brands/lavender/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the lavender brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/lavender/palette.light.js

@@ -1,4 +1,5 @@
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
+import { rotateScaleHue } from "../../builders/brandInk.js";
 import { neutralTokens, sharedBoxShadow } from "../neutrals.js";
 const PRIMARY_500 = "#8B3FC8";
 const SECONDARY_ANCHOR = "#1e0f30";
@@ -28,19 +29,14 @@ const secondary = {
     900: "#08030b",
     opacity: buildPrimaryOpacity(SECONDARY_ANCHOR),
 };
-const tertiary = { ...secondary };
+const tertiary = { ...rotateScaleHue(secondary), opacity: secondary.opacity };
 const gray = {
     50: "#f9f7fb",
     100: "#f0eaf6",
     200: "#e4d9f0",
     300: "#cdbde3",
     400: "#a897cc",
-    // Retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff — a value that
-    // clears AA by <0.02 is treated as failing, see Wave D QA follow-up) against every
-    // backgroundColor surface it's actually rendered on (main/secondary/light/subtle —
-    // verified via usage grep). muted/accent/tertiary/etc. have 0-1 live call sites today and
-    // none pair them with gray[500] text; going dark enough to also clear those would push
-    // past gray[600]'s own lightness and break the ramp order.
+    // NOTE: retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff) against live backgroundColor surfaces.
     500: "#746499",
     600: "#5e527a",
     700: "#4a4060",
@@ -142,12 +138,7 @@ const boxborder = {
     800: "#6d6879",
     900: "#52505b",
 };
-/**
- * The low rungs sat two steps too pale to draw anything: `200` — the default hairline for
- * cards, dividers and inputs — was L94 against a L98 canvas, so a card had no visible edge.
- * It now lands at L88, contrast 1.22 against a white card, matching Chakra's gray.200 hairline.
- * Rungs 700+ are unchanged; they were never the problem.
- */
+// NOTE: 200 lifted to L88 (was L94, invisible against an L98 canvas) — matches Chakra's gray.200 hairline.
 const border = {
     50: "#f6f4f9",
     100: "#ede9f4",

package/dist/esm/Theme/tokens/brands/meadow/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the meadow brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/meadow/palette.light.js

@@ -18,25 +18,16 @@ const primary = {
 const palette = {
     ...neutralTokens,
     ...buildBrandInk(PRIMARY_500),
-    // `to` stop retuned so white gradient-button text (onGradient, accentText.ts) clears AA — the
-    // original let white drop to 2.49 there (`from` already passed at 6.39, unchanged).
-    // Nudged one step further (4.519 -> 4.627): the first pass cleared AA by <0.02, too thin a
-    // margin to trust against rounding/rendering variance.
+    // NOTE: `to` stop retuned so white gradient-button text clears AA — original let it drop to 2.49.
     gradient: { from: "#2d6a4f", to: "#0f8376" }, // forest green → teal
     primary,
-    tertiary: { ...primary },
     gray: {
         50: "#f6f9f7",
         100: "#ecf1ee",
         200: "#dce5e0",
         300: "#c4d2cb",
         400: "#93a99f",
-        // Retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff — a value that
-        // clears AA by <0.02 is treated as failing, see Wave D QA follow-up) against every
-        // backgroundColor surface it's actually rendered on (main/secondary/light/subtle —
-        // verified via usage grep). muted/accent/tertiary/etc. have 0-1 live call sites today and
-        // none pair them with gray[500] text; going dark enough to also clear those would push
-        // past gray[600]'s own lightness and break the ramp order.
+        // NOTE: retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff) against live backgroundColor surfaces.
         500: "#5c7369",
         600: "#445f52",
         700: "#344a3f",

package/dist/esm/Theme/tokens/brands/radiant/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the radiant brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/radiant/palette.light.js

@@ -18,10 +18,7 @@ const primary = {
 const palette = {
     ...neutralTokens,
     ...buildBrandInk(PRIMARY_500),
-    // Stops retuned so white gradient-button text (onGradient, accentText.ts) clears AA at both
-    // ends — the original pair let white drop to 4.37/2.15 against from/to. Same hue, darker.
-    // Both nudged one step further (4.509/4.502 -> 4.601/4.617): the first pass cleared AA by
-    // <0.01, too thin a margin to trust against rounding/rendering variance.
+    // NOTE: stops retuned so white gradient-button text clears AA at both ends — original let it drop to 4.37/2.15.
     gradient: { from: "#cd4733", to: "#a36807" }, // terracotta red → amber
     primary,
     // 🌫️ Neutral gray (slightly warm, not pink)
@@ -31,12 +28,7 @@ const palette = {
         200: "#e2dad5",
         300: "#cec2bb",
         400: "#b3a39a",
-        // Retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff — a value that
-        // clears AA by <0.02 is treated as failing, see Wave D QA follow-up) against every
-        // backgroundColor surface it's actually rendered on (main/secondary/light/subtle —
-        // verified via usage grep). muted/accent/tertiary/etc. have 0-1 live call sites today and
-        // none pair them with gray[500] text; going dark enough to also clear those would push
-        // past gray[600]'s own lightness and break the ramp order.
+        // NOTE: retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff) against live backgroundColor surfaces.
         500: "#796861",
         600: "#6e6058",
         700: "#534841",

package/dist/esm/Theme/tokens/brands/rosewood/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the rosewood brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/rosewood/palette.light.js

@@ -18,10 +18,7 @@ const primary = {
 const palette = {
     ...neutralTokens,
     ...buildBrandInk(PRIMARY_500),
-    // Stops retuned so white gradient-button text (onGradient, accentText.ts) clears AA at both
-    // ends — the original pair let white drop to 3.46/2.69 against from/to. Same hue, darker.
-    // Both nudged one step further (4.520/4.505 -> 4.609/4.607): the first pass cleared AA by
-    // <0.02, too thin a margin to trust against rounding/rendering variance.
+    // NOTE: stops retuned so white gradient-button text clears AA at both ends — original let it drop to 3.46/2.69.
     gradient: { from: "#c74962", to: "#ea0727" }, // rose → coral pink
     primary,
     // 🌫️ Neutral gray (slightly warm, avoids purple tint)
@@ -31,16 +28,7 @@ const palette = {
         200: "#e4dada",
         300: "#d0c1c1",
         400: "#b4a2a2",
-        // Retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff — a value that
-        // clears AA by <0.02 is treated as failing, see Wave D QA follow-up) against every
-        // backgroundColor surface it's actually rendered on (main/secondary/light/subtle —
-        // verified via usage grep). muted/accent/tertiary/etc. have 0-1 live call sites today and
-        // none pair them with gray[500] text; going dark enough to also clear those would push
-        // past gray[600]'s own lightness and break the ramp order.
-        //
-        // First pass (#7b6868) measured 4.516 against `secondary` — a 0.016 margin, too thin to
-        // trust (same failure mode as the gradient-stop retune). Darkened ~0.7 lightness points
-        // (hue/saturation preserved) to restore the safe margin below.
+        // NOTE: retuned to a safe >=4.6 AA margin — first pass (#7b6868) measured 4.516, too thin a margin to trust.
         500: "#796666",
         600: "#6e5e5e",
         700: "#534747",

package/dist/esm/Theme/tokens/brands/skyline/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the skyline brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/skyline/palette.light.js

@@ -18,25 +18,16 @@ const primary = {
 const palette = {
     ...neutralTokens,
     ...buildBrandInk(PRIMARY_500),
-    // `to` stop retuned so white gradient-button text (onGradient, accentText.ts) clears AA — the
-    // original let white drop to 2.14 there (`from` already passed at 11.28, unchanged).
-    // Nudged one step further (4.515 -> 4.600): the first pass cleared AA by <0.02, too thin a
-    // margin to trust against rounding/rendering variance.
+    // NOTE: `to` stop retuned so white gradient-button text clears AA — original let it drop to 2.14.
     gradient: { from: "#1a3a6b", to: "#067db2" }, // deep navy → sky blue
     primary,
-    tertiary: { ...primary },
     gray: {
         50: "#f4f6fa",
         100: "#e6eaf2",
         200: "#d3dae8",
         300: "#b0bcd4",
         400: "#8094b0",
-        // Retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff — a value that
-        // clears AA by <0.02 is treated as failing, see Wave D QA follow-up) against every
-        // backgroundColor surface it's actually rendered on (main/secondary/light/subtle —
-        // verified via usage grep). muted/accent/tertiary/etc. have 0-1 live call sites today and
-        // none pair them with gray[500] text; going dark enough to also clear those would push
-        // past gray[600]'s own lightness and break the ramp order.
+        // NOTE: retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff) against live backgroundColor surfaces.
         500: "#566c8b",
         600: "#3d526b",
         700: "#2e3f54",

package/dist/esm/Theme/tokens/brands/slate/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the slate brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/slate/palette.light.js

@@ -20,23 +20,13 @@ const palette = {
     ...buildBrandInk(PRIMARY_500),
     gradient: { from: "#666d7a", to: "#4a4e59" },
     primary,
-    tertiary: { ...primary },
     gray: {
         50: "#f9fafb",
         100: "#f3f4f6",
         200: "#e5e7eb",
         300: "#d1d5db",
         400: "#9ca3af",
-        // Retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff — a value that
-        // clears AA by <0.02 is treated as failing, see Wave D QA follow-up) against every
-        // backgroundColor surface it's actually rendered on (main/secondary/light/subtle —
-        // verified via usage grep). muted/accent/tertiary/etc. have 0-1 live call sites today and
-        // none pair them with gray[500] text; going dark enough to also clear those would push
-        // past gray[600]'s own lightness and break the ramp order.
-        //
-        // First pass (#6a707e) measured 4.509 against `secondary` — a 0.009 margin, too thin to
-        // trust (same failure mode as the gradient-stop retune). Darkened ~0.7 lightness points
-        // (hue/saturation preserved) to restore the safe margin below.
+        // NOTE: retuned to a safe >=4.6 AA margin — first pass (#6a707e) measured 4.509, too thin a margin to trust.
         500: "#686e7c",
         600: "#4b5563",
         700: "#374151",

package/dist/esm/Theme/tokens/brands/storefront/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the storefront brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/zinc/palette.dark.js

@@ -1,26 +1,9 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
+import { rotateScaleHue } from "../../builders/brandInk.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 import { pickAccentText, onFilled } from "../../builders/accentText.js";
 import light from "./palette.light.js";
-/**
- * zinc dark is the shadcn dark look and INVERTS the primary: the filled button is near-white
- * `#e4e4e7` carrying a `#18181b` label (13.96:1) — the opposite of every other brand, whose dark
- * primary stays a lifted version of its own hue. `#e4e4e7` is shadcn's actual dark-mode `--primary`
- * (verified against shadcn's live zinc theme registry, 2026-07-18) — a shade dimmer than pure
- * `#fafafa`, which is shadcn's `--foreground` (default body text), not `--primary`. The generic
- * `buildDarkPalette` derivation would only lift zinc's near-black accent to a mid grey (a light
- * label's floor), so `primary`/`secondary`/`background` (numeric ramp)/`text`/`header`/`gray`/
- * `border`/`boxborder`/`placeholder`/`disabled`/`table` are pinned here as explicit literals ported
- * verbatim from Mobile-Components, matching shadcn's own dark palette as closely as web's token
- * shape allows.
- *
- * `backgroundColor` (named surfaces) and `sidebar` are the two fields left to `...derived` instead
- * of a literal port — see the comment above the `palette` object for why.
- *
- * `accentText` is recomputed against the OVERRIDDEN `primary` and `derived.backgroundColor.main`,
- * not spread from `derived` — the generic derivation's `accentText` was picked for the generic
- * (wrong) lifted primary and would be stale once `primary` is replaced below.
- */
+// NOTE: zinc dark INVERTS the primary (near-white fill, dark label) to match shadcn — every other brand lifts its own hue instead. Most ramps below are literals ported from Mobile-Components.
 const derived = buildDarkPalette(light);
 const PRIMARY_500 = "#e4e4e7";
 const SECONDARY_500 = "#a1a1aa";
@@ -87,11 +70,7 @@ const header = {
     800: "#fefefe",
     900: "#ffffff",
 };
-// muted-foreground = gray[500] = #a1a1aa (5.81:1 on the #27272a muted surface); it also serves
-// as the focus ring on the #09090b canvas (7.76:1). gray[400] = the interactive border/icon rung,
-// and is the one value here NOT ported verbatim: it is pinned to whatever clears the 3:1 non-text
-// bar on the LIGHTEST named surface, which is derived rather than ported. shadcn's own #71717a
-// measures 2.81 there, so this sits two steps lighter (3.19).
+// NOTE: gray[400] is the one value here NOT ported verbatim — pinned to clear the 3:1 non-text bar (shadcn's own measures 2.81).
 const gray = {
     50: "#18181b",
     100: "#27272a",
@@ -172,17 +151,8 @@ const palette = {
     gradient: { from: PRIMARY_500, to: "#a1a1aa" },
     primary,
     secondary,
-    tertiary: { ...secondary },
-    // `backgroundColor` (named surfaces) and `sidebar` are deliberately NOT overridden with
-    // mobile's literal values: mobile's zinc names 5 groups of surfaces onto the same hex each
-    // (e.g. quaternary/medium/neutral all "#18181b"), which violates web's "every named surface
-    // is a visually distinct elevation step" invariant (`darkSurfaces.test.ts`) that every other
-    // brand is held to. Falling through to `...derived` runs zinc through the SAME generic
-    // `NAMED_SURFACE_L` staircase every other brand uses — zinc's hue is ~240deg/near-zero
-    // saturation, so the result is visually the same cool neutral, just with distinct steps.
-    // `sidebar` similarly falls through to `derived.sidebar` (== `light.sidebar`, non-inverting)
-    // rather than mobile's separately-tuned dark sidebar, matching the "sidebar never inverts"
-    // invariant every other web brand relies on (including this session's own SideBar accent fix).
+    tertiary: { ...rotateScaleHue(secondary), opacity: secondary.opacity },
+    // NOTE: backgroundColor/sidebar fall through to `...derived` — mobile's literals collapse distinct elevation steps, breaking darkSurfaces.test.ts.
     background,
     text,
     header,