pixelize-design-library 2.4.1 → 2.4.2-beta.1

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

@@ -0,0 +1,297 @@
+import { buildPrimaryOpacity, buildPrimaryShadowTint } from "./buildBrandTokens.js";
+import { contrastRatio, hexToHsl, hslToHex, withLightness } from "./color.js";
+import { pickAccentText, onFilled } from "./accentText.js";
+import { withSidebarTokens } from "./sidebarAccent.js";
+import { buildMutedText } from "./mutedText.js";
+import { buildSemanticText, buildOnSemantic } from "./semanticText.js";
+/**
+ * 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);
+    const 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),
+    };
+    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,
+        // `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),
+        textMuted: buildMutedText(fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT), namedSurfaces.main),
+        semanticText: buildSemanticText(semantic, namedSurfaces.main),
+        onPrimary: onFilled(primary[500], light.white, light.black),
+        onSemantic: buildOnSemantic(semantic, light.white, light.black),
+        // Sidebar is already near-black in light mode, so it needs no inversion.
+        sidebar: withSidebarTokens(light),
+        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,46 @@
+import { isDarkCanvas, onFilled } from "./accentText.js";
+/**
+ * Categorical series palette. Generated in OKLCH on one fixed hue sequence per mode, so a
+ * theme switch never repaints a series. Verified with the six-check validator: lightness
+ * band, chroma floor, CVD separation, normal-vision floor and contrast all pass on both
+ * surfaces. Worst adjacent protan/deutan separation is 10.9 (light) / 11.6 (dark) OKLab
+ * dE, against a target of 8 — the previous four-color default scored 4.8 and was
+ * unreadable for red-green color blindness. Re-run the validator before editing a value.
+ */
+export const CATEGORICAL_SERIES = {
+    light: ["#009068", "#3177dc", "#5a8b00", "#8b5dce", "#9b7300", "#af4da9", "#cb4a2a", "#009d82"],
+    dark: ["#00976d", "#377ee3", "#5f9200", "#9163d5", "#a27900", "#b654b0", "#d25030", "#00aa8e"],
+};
+export const chartMode = (colors) => isDarkCanvas(colors.backgroundColor.main) ? "dark" : "light";
+export function getCategoricalSeriesColors(colors) {
+    return [...CATEGORICAL_SERIES[chartMode(colors)]];
+}
+export function getDefaultSeriesColors(colors) {
+    return getCategoricalSeriesColors(colors);
+}
+/** Ink, grid and surface tokens every chart type shares. */
+export function chartInk(colors) {
+    const surface = colors.backgroundColor.main;
+    return {
+        surface,
+        text: colors.text[900],
+        muted: colors.text[500],
+        grid: colors.border[500],
+        axis: colors.text[500],
+        tooltipBg: colors.backgroundColor.secondary,
+    };
+}
+/** Ink for a label drawn on top of a filled mark. Always clears AA. */
+export const labelOnSeries = (fill, colors) => onFilled(fill, colors.white, colors.black);
+export function mergeChartTitleStyle(colors, titleStyle) {
+    return {
+        fontSize: "14px",
+        fontWeight: 600,
+        fontFamily: "inherit",
+        color: colors.text[900],
+        ...titleStyle,
+    };
+}
+export function chartAxisLabelColor(colors) {
+    return colors.text[500];
+}

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.js";
+export * from "./buildBrandTokens.js";
+export * from "./buildDarkPalette.js";
+export * from "./chartColorsFromTheme.js";
+export * from "./color.js";

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

@@ -0,0 +1,5 @@
+import { liftToContrast } from "./outlineRung.js";
+/** WCAG 1.4.3 — muted is still body text. */
+export const AA_NORMAL_TEXT = 4.5;
+/** Seeded from the ramp's muted rung so brand tint survives, then lifted until it clears AA. */
+export const buildMutedText = (text, canvas) => liftToContrast(text[400], canvas, AA_NORMAL_TEXT);

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

@@ -0,0 +1,65 @@
+import { contrastRatio, hexToHsl, relativeLuminance, withLightness } from "./color.js";
+/**
+ * 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 hue and saturation.
+ * Direction is DERIVED from the backdrop, never passed: a mode argument here was redundant
+ * with the backdrop in every call site, and a redundant argument is one that can be wrong.
+ * Tries the far side first, falls back to the near side, and stops at the first passing step.
+ */
+export function liftToContrast(hex, backdrop, target = AA_NON_TEXT) {
+    if (contrastRatio(hex, backdrop) >= target)
+        return hex;
+    const { s, l: start } = hexToHsl(hex);
+    const away = relativeLuminance(backdrop) < 0.5 ? 1 : -1;
+    for (const step of [away, -away]) {
+        let l = start;
+        while (l > 0 && l < 100) {
+            l += step;
+            const next = withLightness(hex, l, s);
+            if (contrastRatio(next, backdrop) >= target)
+                return next;
+        }
+    }
+    const ends = [withLightness(hex, 100, s), withLightness(hex, 0, s)];
+    return contrastRatio(ends[0], backdrop) >= contrastRatio(ends[1], backdrop) ? ends[0] : ends[1];
+}
+/**
+ * `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) {
+    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);
+    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) {
+    return liftToContrast(seed, restSurface, MIN_PERCEPTIBLE_STEP);
+}

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

@@ -0,0 +1,20 @@
+import { liftToContrast, AA_NON_TEXT } from "./outlineRung.js";
+import { AA_NORMAL_TEXT } from "./accentText.js";
+/** Placeholder text measured 4.32:1 on a card for 8 of 9 brands — text, so held to 4.5:1. */
+export function withPlaceholderRung(palette) {
+    const resolved = liftToContrast(palette.placeholder[500], palette.background[50], AA_NORMAL_TEXT);
+    if (resolved === palette.placeholder[500])
+        return palette;
+    return { ...palette, placeholder: { ...palette.placeholder, 500: resolved } };
+}
+/** The hover row is a SURFACE, so it steps away from the ink rather than the ink moving. */
+export function withTableHoverRung(palette) {
+    const resolved = liftToContrast(palette.table.hover[500], palette.text[500], AA_NORMAL_TEXT);
+    if (resolved === palette.table.hover[500])
+        return palette;
+    return {
+        ...palette,
+        table: { hover: { ...palette.table.hover, 500: resolved } },
+    };
+}
+export { AA_NON_TEXT };

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

@@ -0,0 +1,17 @@
+import { liftToContrast } from "./outlineRung.js";
+import { AA_NORMAL_TEXT, onFilled } from "./accentText.js";
+export const SEMANTIC_TONES = ["success", "error", "warning", "info"];
+/**
+ * `semantic[tone][500]` is a FILL rung — as ink on a light canvas it measures 1.84-3.68:1 across
+ * every brand. Each tone is stepped here until it clears AA as text, so a call site that wants
+ * "error-coloured text" cannot pick the unreadable one.
+ */
+export const buildSemanticText = (semantic, canvas) => SEMANTIC_TONES.reduce((acc, tone) => {
+    acc[tone] = liftToContrast(semantic[tone][500], canvas, AA_NORMAL_TEXT);
+    return acc;
+}, {});
+/** Ink ON the fill, not on the canvas — the pair a CSS module needs but cannot compute. */
+export const buildOnSemantic = (semantic, white, black) => SEMANTIC_TONES.reduce((acc, tone) => {
+    acc[tone] = onFilled(semantic[tone][500], white, black);
+    return acc;
+}, {});

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

@@ -0,0 +1,23 @@
+import { compositeOver } from "./color.js";
+import { liftToContrast, resolveHoverTint, AA_NON_TEXT } from "./outlineRung.js";
+import { buildSemanticText } from "./semanticText.js";
+/** WCAG 1.4.3 — the active label is normal-size text. */
+export const AA_NORMAL_TEXT = 4.5;
+/** Lightest surface an active row reaches: Chakra `whiteAlpha.400` (0.24) on hover. */
+export const ACTIVE_SURFACE_TINT = "#ffffff3d";
+export const sidebarActiveSurface = (background) => compositeOver(ACTIVE_SURFACE_TINT, background[500]);
+/** The rail never inverts, so both modes take the accent from the LIGHT primary. */
+export const buildSidebarTokens = (background, lightPrimary, semantic) => {
+    const surface = sidebarActiveSurface(background);
+    const elevated = resolveHoverTint(background[500], background[500]);
+    return {
+        background,
+        elevated,
+        activeIcon: liftToContrast(lightPrimary[300], surface, AA_NON_TEXT),
+        activeLabel: liftToContrast(lightPrimary[100], surface, AA_NORMAL_TEXT),
+        mutedIcon: liftToContrast(background[300], elevated, AA_NON_TEXT),
+        mutedLabel: liftToContrast(background[100], elevated, AA_NORMAL_TEXT),
+        semanticText: buildSemanticText(semantic, elevated),
+    };
+};
+export const withSidebarTokens = (source) => buildSidebarTokens(source.sidebar.background, source.primary, source.semantic);