pixelize-design-library 2.4.1-beta.11 → 2.4.1-beta.13

package/dist/esm/Theme/tokens/builders/buildDarkPalette.js

@@ -0,0 +1,289 @@
+import { buildPrimaryOpacity, buildPrimaryShadowTint } from "./buildBrandTokens";
+import { contrastRatio, hexToHsl, hslToHex, withLightness } from "./color";
+import { pickAccentText } from "./accentText";
+/**
+ * Derives a brand's dark palette from its light palette.
+ *
+ * Every value is computed from the brand's OWN hue, so each brand keeps its identity in
+ * dark mode instead of collapsing onto one shared grey.
+ *
+ * Three different strategies are used, because a single rule gives wrong results:
+ *
+ * - **Structural ramps** (surfaces, text, borders) are rebuilt at explicit lightness
+ *   targets around the brand hue. They are NOT simply reversed: the light ramps bottom out
+ *   around 35% lightness, which is nowhere near dark enough for a dark-mode canvas.
+ * - **Utility hue ramps** (red/green/…) are reversed, so index roles survive: `red.50` is a
+ *   pale badge background in light and becomes a deep one in dark, while `red.900` flips to
+ *   near-white for text on it.
+ * - **Brand + semantic ramps** are shifted one step lighter, preserving hue while lifting
+ *   the accent to a legible lightness against a dark canvas.
+ *
+ * `white`, `black` and `transparent` are deliberately untouched — `white` is a *text* color
+ * on filled buttons (see `Button.styles.ts`), not a surface. Components that use `white` as a
+ * surface are migrated to a surface token instead.
+ */
+const SCALE_KEYS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+const fromTargets = (hueSource, targets, saturation) => {
+    const { h } = hexToHsl(hueSource);
+    const out = {};
+    for (const k of SCALE_KEYS) {
+        out[k] = hslToHex({ h, s: saturation, l: targets[k] });
+    }
+    return out;
+};
+/** Mirrors index roles: 50↔900, 100↔800, 200↔700, 300↔600, 400↔500. */
+export const reverseScale = (scale) => ({
+    50: scale[900],
+    100: scale[800],
+    200: scale[700],
+    300: scale[600],
+    400: scale[500],
+    500: scale[400],
+    600: scale[300],
+    700: scale[200],
+    800: scale[100],
+    900: scale[50],
+});
+/** Shifts a ramp one step lighter, keeping hue. Used for brand + semantic accents. */
+export const shiftLighter = (scale) => ({
+    50: withLightness(scale[50], Math.min(hexToHsl(scale[50]).l + 4, 97)),
+    100: scale[50],
+    200: scale[100],
+    300: scale[200],
+    400: scale[300],
+    500: scale[400],
+    600: scale[500],
+    700: scale[600],
+    800: scale[700],
+    900: scale[800],
+});
+/** WCAG AA for normal text — the bar for a solid button's white label. */
+const WHITE_LABEL_TARGET = 4.5;
+const MAX_ACCENT_LIGHTNESS = 85;
+const LIGHTNESS_STEP = 0.5;
+/**
+ * How much lighter this accent can go in dark mode.
+ *
+ * An accent faces two opposing constraints: lighter reads better against a dark canvas, but
+ * worse under the white label of a solid button. There is no single rung that satisfies both
+ * for all seven brands, so this maximizes canvas contrast subject to keeping the white label
+ * legible.
+ *
+ * The floor is `min(AA, whatLightModeAlreadyShips)`: emerald and rosewood already ship white
+ * labels below AA in light mode, so demanding AA here would force their brand color to change.
+ * Dark is held to "no worse than light", never stricter.
+ */
+export const accentLightnessDelta = (accent500, white) => {
+    const originalL = hexToHsl(accent500).l;
+    const floor = Math.min(WHITE_LABEL_TARGET, contrastRatio(white, accent500));
+    let best = originalL;
+    // Contrast against white falls monotonically as lightness rises, so stop at the first miss.
+    for (let l = originalL; l <= MAX_ACCENT_LIGHTNESS; l += LIGHTNESS_STEP) {
+        if (contrastRatio(white, withLightness(accent500, l)) < floor)
+            break;
+        best = l;
+    }
+    return best - originalL;
+};
+/** Raises every rung by the same lightness delta, preserving the ramp's shape and hue. */
+export const liftScale = (scale, delta) => {
+    const out = {};
+    for (const k of SCALE_KEYS) {
+        out[k] = withLightness(scale[k], Math.min(hexToHsl(scale[k]).l + delta, 97));
+    }
+    return out;
+};
+/**
+ * Dark-ramp endpoints for a brand/semantic scale.
+ *
+ * `[50]`/`[100]` are the SUBTLE TINT rungs — chips, avatars, ghost hovers. On a dark canvas they
+ * must be dark, not near-white. `[800]`/`[900]` are the STRONG rungs and get read as text, so on
+ * a dark canvas they must be light. Both roles invert versus light mode.
+ */
+const BRAND_DARK_MIN_L = 12;
+const BRAND_DARK_MAX_L = 93;
+/** Rung order, used to interpolate lightness on each side of the pinned accent. */
+const RUNG_ORDER = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+const ACCENT_INDEX = RUNG_ORDER.indexOf(500);
+/**
+ * Rebuild a scale as a proper DARK ramp: monotonically dark -> light across 50 -> 900, with `[500]`
+ * pinned to the accent.
+ *
+ * Replaces a flat lift for brand/semantic scales. A flat lift adds the same delta to every rung, so
+ * `[50]` stayed near-white (it clamps at L97) and `[600]`+ stayed DARKER than the accent — which is
+ * wrong in both directions on a dark canvas: the tint rungs painted white chips, and components
+ * that use `[600]` as text (e.g. Accordion) rendered dark-on-dark at ~1.3 contrast.
+ *
+ * Interpolating around the pinned accent (rather than using fixed lightness targets) keeps the ramp
+ * monotonic for every brand, whatever lightness that brand's accent lands on. Hue and saturation are
+ * taken from the light scale's OWN matching rung, so each brand keeps its character and its tint
+ * rungs stay as desaturated as they were designed to be.
+ */
+const toDarkRamp = (scale, accentHex) => {
+    const accentL = hexToHsl(accentHex).l;
+    const out = {};
+    RUNG_ORDER.forEach((key, i) => {
+        let l;
+        if (i === ACCENT_INDEX) {
+            l = accentL;
+        }
+        else if (i < ACCENT_INDEX) {
+            // 50 -> just below the accent.
+            const t = i / ACCENT_INDEX;
+            l = BRAND_DARK_MIN_L + (accentL - BRAND_DARK_MIN_L) * t;
+        }
+        else {
+            // Just above the accent -> 900.
+            const t = (i - ACCENT_INDEX) / (RUNG_ORDER.length - 1 - ACCENT_INDEX);
+            l = accentL + (BRAND_DARK_MAX_L - accentL) * t;
+        }
+        const { s } = hexToHsl(scale[key]);
+        out[key] = hslToHex({ h: hexToHsl(accentHex).h, s, l });
+    });
+    return out;
+};
+/** Dark accent scale: accent pinned as light as the white label allows, ramp rebuilt around it. */
+const liftAccent = (scale, white) => {
+    const accent = withLightness(scale[500], hexToHsl(scale[500]).l + accentLightnessDelta(scale[500], white));
+    return { ...toDarkRamp(scale, accent), 500: accent };
+};
+const liftBrand = (brand, white) => {
+    const lifted = liftAccent(brand, white);
+    return { ...lifted, opacity: buildPrimaryOpacity(lifted[500]) };
+};
+// Lightness targets per structural ramp. Index roles match light mode; only lightness flips.
+const SURFACE_TARGETS = {
+    50: 7, 100: 9, 200: 11, 300: 14, 400: 17, 500: 21, 600: 30, 700: 45, 800: 60, 900: 75,
+};
+const TEXT_TARGETS = {
+    50: 30, 100: 38, 200: 45, 300: 55, 400: 62, 500: 70, 600: 76, 700: 82, 800: 88, 900: 95,
+};
+const PLACEHOLDER_TARGETS = {
+    50: 25, 100: 30, 200: 35, 300: 42, 400: 48, 500: 54, 600: 60, 700: 66, 800: 72, 900: 80,
+};
+// Rung 200 is the default hairline. At L18 it sat 5 points off a card at L13 — below the
+// perceptible step, so dark cards read as edgeless. L22 draws the same 1.2x edge the light
+// ramp does, which is what makes a card look like a card in either mode.
+const BORDER_TARGETS = {
+    50: 14, 100: 18, 200: 22, 300: 24, 400: 26, 500: 27, 600: 33, 700: 42, 800: 52, 900: 62,
+};
+const DISABLED_TARGETS = {
+    50: 14, 100: 18, 200: 22, 300: 26, 400: 30, 500: 34, 600: 42, 700: 52, 800: 62, 900: 72,
+};
+const TABLE_HOVER_TARGETS = {
+    50: 9, 100: 11, 200: 13, 300: 15, 400: 17, 500: 19, 600: 24, 700: 32, 800: 42, 900: 52,
+};
+/**
+ * `gray[500]` is the library's de-facto muted-text token (~43 call sites), so its rung is set by
+ * contrast, not by an even ramp — and it must clear AA against the LIGHTEST named surface it can
+ * land on, not merely against the canvas. Tuning it to the canvas alone is what shipped the first
+ * two misses: L48 measured 4.18 on the canvas, then L52 cleared the canvas (4.81) but still failed
+ * on every surface above `secondary` (3.39 on `muted`). L64 clears all of them (5.66 worst case).
+ *
+ * That lands on shadcn's own answer independently: its dark `muted-foreground` is zinc-400
+ * (#a1a1aa, L65) against a near-black canvas. Ours is #a49ea9 — same lightness, brand hue kept.
+ * Rungs at/below 400 stay decorative (borders, dividers, disabled) and are not held to text AA.
+ */
+const GRAY_TARGETS = {
+    50: 10, 100: 14, 200: 22, 300: 32, 400: 48, 500: 64, 600: 72, 700: 79, 800: 86, 900: 93,
+};
+/**
+ * Named surface lightness. Elevation INVERTS versus light mode: in light, `muted`/`accent`
+ * are the strongest tints away from white; in dark, "stronger" means lighter than the canvas.
+ *
+ * The top of the ramp is deliberately compressed (accent 18->17, muted 20->18): dark elevation
+ * reads through small lightness steps plus borders, so a wide spread just looks washed out rather
+ * than layered. `light`/`tertiary` share a rung by design (they are aliases); no other pair may,
+ * or that step of elevation silently disappears.
+ */
+const NAMED_SURFACE_L = {
+    main: 7,
+    base: 8,
+    subtle: 10,
+    secondary: 11,
+    tableHeader: 12,
+    light: 13,
+    tertiary: 13,
+    medium: 14,
+    neutral: 15,
+    quaternary: 16,
+    accent: 17,
+    muted: 18,
+};
+/**
+ * Surfaces are hue-NEUTRAL in dark: every brand shares one canvas, so switching theme recolors the
+ * accents and nothing else. Tinting them instead (this was 14) made a full-screen wash — Meadow's
+ * whole app read green — which reads as a different product per brand rather than a different
+ * accent. Light mode keeps its tinted canvas; there the tint is a hint on white, not the whole
+ * screen. Brand identity in dark lives in `primary`/semantic/text, which stay hued.
+ */
+const SURFACE_SAT = 0;
+const TEXT_SAT = 12;
+const PLACEHOLDER_SAT = 10;
+const BORDER_SAT = 12;
+const DISABLED_SAT = 8;
+// Neutral for the same reason as SURFACE_SAT — gray's low rungs ARE surfaces, and a tinted ramp
+// on a neutral canvas reads as a mismatch. It also buys back the contrast the neutral canvas
+// cost: `gray[400]` on `muted` was 2.99 on lavender/zinc at sat 6, and is 3.16 at 0.
+const GRAY_SAT = 0;
+export function buildDarkPalette(light) {
+    const hueSource = light.primary[500];
+    const { h } = hexToHsl(hueSource);
+    const namedSurfaces = Object.fromEntries(Object.entries(NAMED_SURFACE_L).map(([key, l]) => [
+        key,
+        hslToHex({ h, s: SURFACE_SAT, l }),
+    ]));
+    const white = light.white;
+    const primary = liftBrand(light.primary, white);
+    return {
+        ...light,
+        // Brand identity: hue preserved, accent lifted as far as the white label allows.
+        primary,
+        secondary: liftBrand(light.secondary, white),
+        tertiary: liftBrand(light.tertiary, white),
+        gradient: light.gradient,
+        semantic: {
+            success: liftAccent(light.semantic.success, white),
+            error: liftAccent(light.semantic.error, white),
+            warning: liftAccent(light.semantic.warning, white),
+            info: liftAccent(light.semantic.info, white),
+        },
+        // `white` stays white on purpose: it is the label color on filled buttons.
+        transparent: light.transparent,
+        black: light.black,
+        white: light.white,
+        // Utility hues keep their meaning; only the light/dark role of each index flips.
+        gray: fromTargets(hueSource, GRAY_TARGETS, GRAY_SAT),
+        red: reverseScale(light.red),
+        orange: reverseScale(light.orange),
+        yellow: reverseScale(light.yellow),
+        green: reverseScale(light.green),
+        teal: reverseScale(light.teal),
+        blue: reverseScale(light.blue),
+        cyan: reverseScale(light.cyan),
+        purple: reverseScale(light.purple),
+        pink: reverseScale(light.pink),
+        backgroundColor: namedSurfaces,
+        background: fromTargets(hueSource, SURFACE_TARGETS, SURFACE_SAT),
+        text: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT),
+        header: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT + 2),
+        placeholder: fromTargets(hueSource, PLACEHOLDER_TARGETS, PLACEHOLDER_SAT),
+        border: fromTargets(hueSource, BORDER_TARGETS, BORDER_SAT),
+        boxborder: fromTargets(hueSource, BORDER_TARGETS, BORDER_SAT),
+        // Neutral: a row hover is a surface fill, and across a full table its tint is exactly the
+        // brand wash the canvas was changed to avoid.
+        table: { hover: fromTargets(hueSource, TABLE_HOVER_TARGETS, SURFACE_SAT) },
+        disabled: fromTargets(hueSource, DISABLED_TARGETS, DISABLED_SAT),
+        // Derived from the LIFTED accent against the dark canvas: the lift stops at the white-label
+        // floor (~4.55), which leaves primary[500] short of AA as text, so text needs its own rung.
+        accentText: pickAccentText(primary, namedSurfaces.main, "dark"),
+        // Sidebar is already near-black in light mode, so it needs no inversion.
+        sidebar: light.sidebar,
+        boxShadow: {
+            primary: buildPrimaryShadowTint(primary[500]),
+            error: light.boxShadow.error,
+            default: "#00000080",
+        },
+    };
+}
+export default buildDarkPalette;

package/dist/esm/Theme/tokens/builders/chartColorsFromTheme.js

@@ -0,0 +1,21 @@
+/** Default multi-series palette for Apex charts (strings required by ApexCharts). */
+export function getDefaultSeriesColors(colors) {
+    return [
+        colors.primary[500],
+        colors.semantic.error[500],
+        colors.semantic.success[500],
+        colors.orange[500],
+    ];
+}
+export function mergeChartTitleStyle(colors, titleStyle) {
+    return {
+        fontSize: "16px",
+        fontWeight: 600,
+        fontFamily: "Arial",
+        color: colors.primary[500],
+        ...titleStyle,
+    };
+}
+export function chartAxisLabelColor(colors) {
+    return colors.gray[700];
+}

package/dist/esm/Theme/tokens/builders/color.js

@@ -0,0 +1,141 @@
+/**
+ * Pure color math. No dependencies, no platform APIs — safe for the mobile port.
+ *
+ * Used by `buildDarkPalette` to derive dark ramps from each brand's own light colors,
+ * and to assert contrast in tests.
+ */
+const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
+/**
+ * Accepts `#rgb` or `#rrggbb` only. An `#rrggbbaa` throws ON PURPOSE.
+ *
+ * The old version silently dropped the alpha and returned the fully-opaque rgb. That made
+ * `contrastRatio` score a 16%-alpha hover tint as if it were solid — a measured 4.18 for a fill that
+ * actually renders at 1.17 over the canvas, a 3.6x overstatement — with a doc comment saying "alpha
+ * ignored" that made it look handled. Alpha over an unknown backdrop has no defined luminance, so the
+ * only correct move is to refuse it: composite it first with `compositeOver`, then measure the result.
+ */
+export function hexToRgb(hex) {
+    let h = hex.trim().replace(/^#/, "");
+    if (h.length === 3)
+        h = h.split("").map((c) => c + c).join("");
+    if (!/^[0-9a-fA-F]{6}$/.test(h)) {
+        throw new Error(`hexToRgb needs an opaque #rgb/#rrggbb color, got "${hex}". ` +
+            `If this is an #rrggbbaa tint, composite it over its backdrop first (compositeOver).`);
+    }
+    const int = parseInt(h, 16);
+    return { r: (int >> 16) & 255, g: (int >> 8) & 255, b: int & 255 };
+}
+/** Alpha in 0..1. `#rgb`/`#rrggbb` read as fully opaque (`a: 1`); `#rgba`/`#rrggbbaa` carry their alpha. */
+export function hexToRgba(hex) {
+    let h = hex.trim().replace(/^#/, "");
+    if (h.length === 4)
+        h = h.split("").map((c) => c + c).join("");
+    if (h.length === 8) {
+        const a = parseInt(h.slice(6, 8), 16) / 255;
+        return { ...hexToRgb(`#${h.slice(0, 6)}`), a };
+    }
+    return { ...hexToRgb(`#${h}`), a: 1 };
+}
+/**
+ * Flatten a translucent foreground onto an opaque backdrop — the ONLY way to get a real color for a
+ * tint before measuring contrast. `contrastRatio(tint, canvas)` now throws; the correct call is
+ * `contrastRatio(compositeOver(tint, canvas), canvas)`.
+ */
+export function compositeOver(foreground, backdrop) {
+    const f = hexToRgba(foreground);
+    const b = hexToRgb(backdrop);
+    return rgbToHex({
+        r: f.r * f.a + b.r * (1 - f.a),
+        g: f.g * f.a + b.g * (1 - f.a),
+        b: f.b * f.a + b.b * (1 - f.a),
+    });
+}
+export function rgbToHex({ r, g, b }) {
+    const to = (n) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0");
+    return `#${to(r)}${to(g)}${to(b)}`;
+}
+export function rgbToHsl({ r, g, b }) {
+    const rn = r / 255;
+    const gn = g / 255;
+    const bn = b / 255;
+    const max = Math.max(rn, gn, bn);
+    const min = Math.min(rn, gn, bn);
+    const l = (max + min) / 2;
+    const d = max - min;
+    if (d === 0)
+        return { h: 0, s: 0, l: l * 100 };
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h;
+    if (max === rn)
+        h = ((gn - bn) / d + (gn < bn ? 6 : 0)) / 6;
+    else if (max === gn)
+        h = ((bn - rn) / d + 2) / 6;
+    else
+        h = ((rn - gn) / d + 4) / 6;
+    return { h: h * 360, s: s * 100, l: l * 100 };
+}
+export function hslToRgb({ h, s, l }) {
+    const hn = ((h % 360) + 360) % 360 / 360;
+    const sn = clamp(s, 0, 100) / 100;
+    const ln = clamp(l, 0, 100) / 100;
+    if (sn === 0) {
+        const v = ln * 255;
+        return { r: v, g: v, b: v };
+    }
+    const q = ln < 0.5 ? ln * (1 + sn) : ln + sn - ln * sn;
+    const p = 2 * ln - q;
+    const channel = (t) => {
+        let tn = t;
+        if (tn < 0)
+            tn += 1;
+        if (tn > 1)
+            tn -= 1;
+        if (tn < 1 / 6)
+            return p + (q - p) * 6 * tn;
+        if (tn < 1 / 2)
+            return q;
+        if (tn < 2 / 3)
+            return p + (q - p) * (2 / 3 - tn) * 6;
+        return p;
+    };
+    return {
+        r: channel(hn + 1 / 3) * 255,
+        g: channel(hn) * 255,
+        b: channel(hn - 1 / 3) * 255,
+    };
+}
+export const hexToHsl = (hex) => rgbToHsl(hexToRgb(hex));
+export const hslToHex = (hsl) => rgbToHex(hslToRgb(hsl));
+/** Re-lights a color while keeping its hue (and, unless overridden, its saturation). */
+export function withLightness(hex, lightness, saturation) {
+    const { h, s } = hexToHsl(hex);
+    return hslToHex({ h, s: saturation !== null && saturation !== void 0 ? saturation : s, l: clamp(lightness, 0, 100) });
+}
+/** Linear RGB blend. `weight` is how much of `b` to take (0 → a, 1 → b). */
+export function mix(a, b, weight) {
+    const ca = hexToRgb(a);
+    const cb = hexToRgb(b);
+    const w = clamp(weight, 0, 1);
+    return rgbToHex({
+        r: ca.r + (cb.r - ca.r) * w,
+        g: ca.g + (cb.g - ca.g) * w,
+        b: ca.b + (cb.b - ca.b) * w,
+    });
+}
+/** WCAG 2.1 relative luminance. */
+export function relativeLuminance(hex) {
+    const { r, g, b } = hexToRgb(hex);
+    const channel = (v) => {
+        const c = v / 255;
+        return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+/** WCAG 2.1 contrast ratio, 1–21. AA body text needs >= 4.5. */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const light = Math.max(la, lb);
+    const dark = Math.min(la, lb);
+    return (light + 0.05) / (dark + 0.05);
+}

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

@@ -0,0 +1,5 @@
+export * from "./accentText";
+export * from "./buildBrandTokens";
+export * from "./buildDarkPalette";
+export * from "./chartColorsFromTheme";
+export * from "./color";

package/dist/esm/Theme/tokens/builders/outlineRung.js

@@ -0,0 +1,63 @@
+import { contrastRatio, hexToHsl, withLightness } from "./color";
+import { isDarkCanvas } from "./accentText";
+/**
+ * The floor a hover/active state's step off its own resting surface must clear to be seen at
+ * all — same value the SideBar ladder, Accordion, and NavigationBar hover states are held to.
+ * A "hover" a user cannot perceive is not a hover.
+ */
+export const MIN_PERCEPTIBLE_STEP = 1.15;
+/** WCAG 1.4.11 — a control outline is a UI component boundary, held to 3:1. */
+export const AA_NON_TEXT = 3;
+/**
+ * Walks a hex toward `target` contrast against `backdrop`, keeping its hue and saturation so the
+ * result still reads as the same colour. Darkens when `mode` is light, lightens when dark, and
+ * stops at the FIRST passing step so nothing overshoots to black or white.
+ */
+export function liftToContrast(hex, backdrop, mode, target = AA_NON_TEXT) {
+    if (contrastRatio(hex, backdrop) >= target)
+        return hex;
+    const { s } = hexToHsl(hex);
+    const step = mode === "dark" ? 1 : -1;
+    let { l } = hexToHsl(hex);
+    while (l > 0 && l < 100) {
+        l += step;
+        const next = withLightness(hex, l, s);
+        if (contrastRatio(next, backdrop) >= target)
+            return next;
+    }
+    return withLightness(hex, mode === "dark" ? 100 : 0, s);
+}
+/**
+ * `boxborder[500]` is the rung every control outline reads (Checkbox, SearchSelect, the date
+ * pickers, the editor's inputs). It was authored as a decorative value — measured 1.30-2.56:1
+ * across brands, so those controls rendered effectively borderless in BOTH modes. Resolved here
+ * rather than hand-pinned per brand: a copied hex goes stale the moment a canvas moves.
+ *
+ * `border[*]` is deliberately untouched — that ramp draws table gridlines, which are decorative
+ * and outside 1.4.11.
+ */
+export function withOutlineRung(palette, mode) {
+    const current = palette.boxborder[500];
+    // The border sits between the control's fill and the surface behind it; hold it to the
+    // harder of the two.
+    const backdrop = contrastRatio(current, palette.backgroundColor.main) <=
+        contrastRatio(current, palette.background[50])
+        ? palette.backgroundColor.main
+        : palette.background[50];
+    const resolved = liftToContrast(current, backdrop, mode);
+    if (resolved === current)
+        return palette;
+    return { ...palette, boxborder: { ...palette.boxborder, 500: resolved } };
+}
+/**
+ * A hover/active tint resolved against the surface it actually sits on, guaranteed to clear
+ * `MIN_PERCEPTIBLE_STEP`. Written for the recurring shape found across NavigationBar, UserDetails
+ * and Accordion: a pale `primary[50]`/`gray[50]` tint that measures near-1.0 on a near-white
+ * surface — invisible — with no dark-mode branch, so the same call site is wrong in both modes at
+ * once. `restSurface` is required rather than assumed white/black: a menu item's hover sits on
+ * its OWN list background, not necessarily the page canvas.
+ */
+export function resolveHoverTint(seed, restSurface) {
+    const mode = isDarkCanvas(restSurface) ? "dark" : "light";
+    return liftToContrast(seed, restSurface, mode, MIN_PERCEPTIBLE_STEP);
+}

package/dist/esm/Theme/tokens/builders/statusTone.js

@@ -0,0 +1,56 @@
+import { contrastRatio } from "./color";
+import { AA_NORMAL_TEXT } from "./accentText";
+import { AA_NON_TEXT, liftToContrast } from "./outlineRung";
+/**
+ * Status chips (open / in-progress / resolved …) were authored as `X.500` text on an `X.100`
+ * tint, which measures 3.3-4.4:1 — under the 4.5:1 body-text bar in BOTH modes. The ink is
+ * resolved from the scale's own hue instead of pinned, so every brand and both modes land on the
+ * lightest ink that still passes rather than a hand-copied hex that goes stale.
+ *
+ * `reverseScale` flips the utility ramps in dark, so `X.100` is already a dark tint there and the
+ * ink walks lighter instead of darker — hence the mode argument.
+ */
+export function resolveStatusTone(scale, mode) {
+    const bg = scale[100];
+    const inkSeed = mode === "dark" ? scale[300] : scale[700];
+    const edgeSeed = mode === "dark" ? scale[400] : scale[300];
+    return {
+        bg,
+        fg: liftToContrast(inkSeed, bg, mode, AA_NORMAL_TEXT),
+        border: liftToContrast(edgeSeed, bg, mode, AA_NON_TEXT),
+    };
+}
+/**
+ * Avatar initials are drawn white on a generated fill. The seed hues in use measured 1.92:1
+ * (`#eab308`), 2.54:1 (`#10b981`) and 3.76:1 (`#ef4444`) — failing in light mode too, not just
+ * dark. Darkening the fill keeps the intended hue and the white-initials look while clearing AA.
+ */
+export function resolveAvatarFill(hex, target = AA_NORMAL_TEXT) {
+    // "light" walks downward in lightness — i.e. darken until white ink clears the bar.
+    return liftToContrast(hex, "#ffffff", "light", target);
+}
+/**
+ * Hue set for generated avatars. Values are seeds, not final fills — always pass them through
+ * `resolveAvatarFill` so the white initials stay legible.
+ */
+export const AVATAR_SEEDS = [
+    "#ef4444",
+    "#f97316",
+    "#eab308",
+    "#22c55e",
+    "#10b981",
+    "#06b6d4",
+    "#3b82f6",
+    "#8b5cf6",
+    "#ec4899",
+];
+/** Stable per-name avatar fill: same name always yields the same accessible colour. */
+export function avatarFillFor(seedText) {
+    let hash = 0;
+    for (let i = 0; i < seedText.length; i++) {
+        hash = (hash * 31 + seedText.charCodeAt(i)) >>> 0;
+    }
+    return resolveAvatarFill(AVATAR_SEEDS[hash % AVATAR_SEEDS.length]);
+}
+/** True when `fg` clears the body-text bar on `bg` — exported for consumer assertions. */
+export const meetsBodyText = (fg, bg) => contrastRatio(fg, bg) >= AA_NORMAL_TEXT;

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

@@ -0,0 +1,14 @@
+/**
+ * Pixelize design tokens — the portable core of the design system.
+ *
+ * PURITY CONTRACT: nothing in this folder imports Chakra, React, or CSS. It is plain
+ * TypeScript data + pure functions, so the mobile design library can consume this
+ * folder as-is. Keep it that way — a single Chakra/CSS import here breaks the mobile port.
+ *
+ * Web-only concerns (Chakra `extendTheme`, `cssVarPrefix`, the Inter font-face CSS import)
+ * live in `Theme/chakra/` instead.
+ */
+export * from "./types";
+export * from "./primitives";
+export * from "./brands";
+export * from "./builders";

package/dist/esm/Theme/tokens/primitives/breakpoints.js

@@ -0,0 +1,8 @@
+const breakpoints = {
+    sm: "30em",
+    md: "48em",
+    lg: "62em",
+    xl: "80em",
+    "2xl": "96em",
+};
+export default breakpoints;

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

@@ -0,0 +1,9 @@
+export { default as space } from "./space";
+export { default as sizes } from "./sizes";
+export { default as radii } from "./radii";
+export { default as shadows } from "./shadows";
+export { default as zIndices } from "./zIndices";
+export { default as breakpoints } from "./breakpoints";
+export { default as lineHeights } from "./lineHeights";
+export { default as letterSpacings } from "./letterSpacings";
+export { default as typography, fonts, fontSizes, fontWeights } from "./typography";

package/dist/esm/Theme/tokens/primitives/letterSpacings.js

@@ -0,0 +1,9 @@
+const letterSpacings = {
+    tighter: "-0.05em",
+    tight: "-0.025em",
+    normal: "0",
+    wide: "0.025em",
+    wider: "0.05em",
+    widest: "0.1em",
+};
+export default letterSpacings;

package/dist/esm/Theme/tokens/primitives/lineHeights.js

@@ -0,0 +1,18 @@
+const lineHeights = {
+    normal: "normal",
+    none: 1,
+    shorter: 1.25,
+    short: 1.375,
+    base: 1.5,
+    tall: 1.625,
+    taller: "2",
+    "3": ".75rem",
+    "4": "1rem",
+    "5": "1.25rem",
+    "6": "1.5rem",
+    "7": "1.75rem",
+    "8": "2rem",
+    "9": "2.25rem",
+    "10": "2.5rem",
+};
+export default lineHeights;

package/dist/esm/Theme/tokens/primitives/radii.js

@@ -0,0 +1,12 @@
+const radii = {
+    none: "0",
+    sm: "0.125rem",
+    base: "0.25rem",
+    md: "0.375rem",
+    lg: "0.5rem",
+    xl: "0.75rem",
+    "2xl": "1rem",
+    "3xl": "1.5rem",
+    full: "9999px",
+};
+export default radii;

package/dist/esm/Theme/tokens/primitives/shadows.js

@@ -0,0 +1,15 @@
+/** Light-mode shadow ramp. Dark mode deepens these — see `builders/buildDarkShadows`. */
+const shadows = {
+    xs: "0 0 0 1px rgba(0, 0, 0, 0.05)",
+    sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
+    base: "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)",
+    md: "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
+    lg: "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)",
+    xl: "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)",
+    "2xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
+    outline: "0 0 0 3px rgba(66, 153, 225, 0.6)",
+    inner: "inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)",
+    none: "none",
+    darkLg: "0 10px 15px -3px rgba(0, 0, 0, 0.5), 0 4px 6px -2px rgba(0, 0, 0, 0.5)",
+};
+export default shadows;