pixelize-design-library 3.0.1-beta.1 → 3.1.1

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

@@ -0,0 +1,245 @@
+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";
+import { buildFocusRing } from "./focusRing.js";
+import { buildSurfaceRaised, filledMarks } from "./surfaceRaised.js";
+import { buildStar } from "./star.js";
+import { CARD_LIFT, lift } from "./planes.js";
+// Structural ramps are rebuilt at explicit targets (not reversed — light ramps bottom near 35%);
+// utility hues are reversed so index roles survive; brand/semantic ramps shift one step lighter.
+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;
+// NOTE: floor is min(AA, light mode's own contrast) — 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;
+    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;
+};
+// [50]/[100] are subtle-tint rungs (dark on a dark canvas); [800]/[900] read as text (light). Inverts light mode.
+const BRAND_DARK_MIN_L = 12;
+const BRAND_DARK_MAX_L = 93;
+const RUNG_ORDER = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+const ACCENT_INDEX = RUNG_ORDER.indexOf(500);
+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) {
+            const t = i / ACCENT_INDEX;
+            l = BRAND_DARK_MIN_L + (accentL - BRAND_DARK_MIN_L) * t;
+        }
+        else {
+            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,
+};
+// NOTE: rung 200 is the default hairline — held at L22, above the perceptible step off an L13 card.
+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,
+};
+// NOTE: gray[500] is the de-facto muted-text token — tuned to clear AA on the lightest named surface, not just the canvas.
+const GRAY_TARGETS = {
+    50: 10, 100: 14, 200: 22, 300: 32, 400: 48, 500: 64, 600: 72, 700: 79, 800: 86, 900: 93,
+};
+// NOTE: elevation inverts vs light mode — "stronger" surfaces get lighter than the canvas, not darker.
+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,
+};
+// NOTE: surfaces are hue-neutral on every brand; brand hue stays on accents, ink and rules.
+const SURFACE_SAT = 0;
+const TEXT_SAT = 12;
+const PLACEHOLDER_SAT = 10;
+const BORDER_SAT = 12;
+const DISABLED_SAT = 8;
+const GRAY_SAT = 0;
+// Fill rungs drawn ON a card keep their step above it, so they rise with the card; ink and chrome rungs stay.
+const BACKGROUND_FILLS = [100, 200, 300, 400, 500];
+// NOTE: table.hover[500] gates every ink (it is a named surface), so it climbs one rung per step, not the card's full rise.
+const TABLE_HOVER_ABOVE_CARD = {
+    50: 1, 100: 3, 200: 5, 300: 6, 400: 6.5, 500: 7,
+};
+const GRAY_FILLS = [50, 100, 200];
+const raise = (targets, rungs, by) => ({
+    ...targets,
+    ...Object.fromEntries(rungs.map((k) => [k, targets[k] + by])),
+});
+const cardPlane = (canvas, white, planes) => {
+    if (planes === "flat")
+        return { card: canvas, rise: 0, tableHover: TABLE_HOVER_TARGETS };
+    const card = lift(white, canvas, CARD_LIFT);
+    const cardL = hexToHsl(card).l;
+    const tableHover = {
+        ...TABLE_HOVER_TARGETS,
+        ...Object.fromEntries(Object.entries(TABLE_HOVER_ABOVE_CARD).map(([k, step]) => [k, cardL + step])),
+    };
+    return { card, rise: cardL - hexToHsl(canvas).l, tableHover };
+};
+export function buildDarkPalette(light, { planes = "lifted" } = {}) {
+    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 { card, rise, tableHover } = cardPlane(namedSurfaces.main, white, planes);
+    const primary = liftBrand(light.primary, white);
+    const background = {
+        ...fromTargets(hueSource, raise(SURFACE_TARGETS, BACKGROUND_FILLS, rise), SURFACE_SAT),
+        50: card,
+    };
+    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),
+    };
+    // border/boxborder are one divider ramp — see CHROME-CONSISTENCY.md.
+    const dividerRamp = fromTargets(hueSource, BORDER_TARGETS, BORDER_SAT);
+    return {
+        ...light,
+        primary,
+        secondary: liftBrand(light.secondary, white),
+        tertiary: liftBrand(light.tertiary, white),
+        gradient: light.gradient,
+        semantic,
+        // NOTE: white stays white on purpose — it is the label color on filled buttons, not a surface.
+        transparent: light.transparent,
+        black: light.black,
+        white: light.white,
+        gray: fromTargets(hueSource, raise(GRAY_TARGETS, GRAY_FILLS, rise), 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,
+        text: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT),
+        header: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT + 2),
+        placeholder: fromTargets(hueSource, PLACEHOLDER_TARGETS, PLACEHOLDER_SAT),
+        border: dividerRamp,
+        boxborder: dividerRamp,
+        table: {
+            hover: fromTargets(hueSource, tableHover, SURFACE_SAT),
+        },
+        disabled: fromTargets(hueSource, DISABLED_TARGETS, DISABLED_SAT),
+        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),
+        focusRing: buildFocusRing({ primary, background, backgroundColor: namedSurfaces }),
+        surfaceRaised: buildSurfaceRaised({ backgroundColor: namedSurfaces, background, white }, filledMarks({ primary, semantic })),
+        star: buildStar(namedSurfaces.main),
+        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,39 @@
+import { isDarkCanvas, onFilled } from "./accentText.js";
+// NOTE: fixed OKLCH hue sequence per mode, six-check validated (CVD separation 10.9/11.6 dE vs target 8) — re-run the validator before editing.
+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.boxborder[200],
+        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,128 @@
+// Pure color math, no dependencies or platform APIs — safe for the mobile port.
+import { memoize } from "./memo.js";
+const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
+// NOTE: #rrggbbaa throws on purpose — alpha over an unknown backdrop has no defined luminance; composite first.
+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 };
+}
+// Flattens a translucent foreground onto a backdrop before measuring contrast — contrastRatio(tint, ...) now throws.
+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,
+    });
+}
+const linearChannel = (v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+};
+const luminanceOf = memoize((hex) => {
+    const { r, g, b } = hexToRgb(hex);
+    return 0.2126 * linearChannel(r) + 0.7152 * linearChannel(g) + 0.0722 * linearChannel(b);
+}, (hex) => hex, 4096);
+/** WCAG 2.1 relative luminance. */
+export function relativeLuminance(hex) {
+    return luminanceOf(hex);
+}
+/** 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/filledSurface.js

@@ -0,0 +1,91 @@
+import { contrastRatio } from "./color.js";
+import { AA_NORMAL_TEXT, isDarkCanvas, onFilled } from "./accentText.js";
+import { AA_NON_TEXT, CHROME_BORDER } from "./outlineRung.js";
+import { memoize, scaleKey } from "./memo.js";
+const RUNGS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+// NOTE: "darker than [500]" is [600]/[700] in light but [400]/[300] in dark, since dark ramps run dark -> light.
+const FILL_STEP_RUNGS = { light: [600, 700], dark: [400, 300] };
+// NOTE: walks away from canvas one named rung at a time from 500 — one direction, so hues stay comparable.
+const rungAwayFromCanvas = (scale, canvas) => {
+    const dir = isDarkCanvas(canvas) ? -1 : 1;
+    let last = 500;
+    for (let i = RUNGS.indexOf(500); i >= 0 && i < RUNGS.length; i += dir) {
+        last = RUNGS[i];
+        if (contrastRatio(scale[last], canvas) >= AA_NON_TEXT)
+            return last;
+    }
+    return last;
+};
+// Below this a white-labelled fill melts into the surface (zinc dark primary), so ink yields instead.
+const WHITE_FILL_MIN_SURFACE = 2.5;
+const lightestWhiteRung = (scale, white) => {
+    if (contrastRatio(scale[500], white) >= AA_NORMAL_TEXT)
+        return 500;
+    const passing = RUNGS.filter((r) => contrastRatio(scale[r], white) >= AA_NORMAL_TEXT);
+    if (!passing.length)
+        return undefined;
+    return passing.reduce((a, b) => contrastRatio(scale[a], white) <= contrastRatio(scale[b], white) ? a : b);
+};
+// Lightest rung carrying a white label at AA; falls back to stepping away from canvas and letting ink flip.
+export const solidFillRung = (scale, white, canvas) => {
+    const whiteRung = lightestWhiteRung(scale, white);
+    if (whiteRung && (!canvas || contrastRatio(scale[whiteRung], canvas) >= WHITE_FILL_MIN_SURFACE)) {
+        return whiteRung;
+    }
+    if (!canvas || contrastRatio(scale[500], canvas) >= AA_NON_TEXT)
+        return 500;
+    return rungAwayFromCanvas(scale, canvas);
+};
+const steppedRung = (base, canvas, step) => {
+    const dir = isDarkCanvas(canvas) ? -1 : 1;
+    const index = RUNGS.indexOf(base) + dir * step;
+    return RUNGS[Math.min(RUNGS.length - 1, Math.max(0, index))];
+};
+const steppedTowardBase = (from, base) => RUNGS[RUNGS.indexOf(from) + (from > base ? -1 : 1)];
+/**
+ * Hover (step 0) or active (step 1) fill rung, one step darker than `solidFillRung`. A step may not
+ * flip the label's side of AA (zinc dark: near-white fill, black ink) or fall below `CHROME_BORDER`
+ * against the canvas (a pressed warning solid used to reach 1.00:1 on the card).
+ */
+export const darkerFillRung = (scale, canvas, white, step) => {
+    const base = solidFillRung(scale, white, canvas);
+    const wantsWhite = contrastRatio(white, scale[base]) >= AA_NORMAL_TEXT;
+    const holds = (rung) => contrastRatio(scale[rung], canvas) >= CHROME_BORDER &&
+        (contrastRatio(white, scale[rung]) >= AA_NORMAL_TEXT) === wantsWhite;
+    let rung;
+    if (base === 500) {
+        const mode = isDarkCanvas(canvas) ? "dark" : "light";
+        rung = FILL_STEP_RUNGS[mode][step];
+    }
+    else {
+        rung = steppedRung(base, canvas, step === 0 ? 1 : 2);
+    }
+    while (rung !== base && !holds(rung))
+        rung = steppedTowardBase(rung, base);
+    return rung;
+};
+/** Label ink for a specific fill swatch — always `onFilled`, exported for style configs. */
+export const labelOnFill = (fill, white, black) => onFilled(fill, white, black);
+const filledSurfaceMemo = memoize((scale, white, black, main, card) => {
+    const canvas = contrastRatio(scale[500], main) <= contrastRatio(scale[500], card) ? main : card;
+    const rung = solidFillRung(scale, white, canvas);
+    const fill = scale[rung];
+    const hoverRung = darkerFillRung(scale, canvas, white, 0);
+    const hoverFill = scale[hoverRung];
+    const activeRung = darkerFillRung(scale, canvas, white, 1);
+    const activeFill = scale[activeRung];
+    return {
+        rung,
+        fill,
+        color: labelOnFill(fill, white, black),
+        hoverRung,
+        hoverFill,
+        hoverColor: labelOnFill(hoverFill, white, black),
+        activeRung,
+        activeFill,
+        activeColor: labelOnFill(activeFill, white, black),
+    };
+}, (scale, white, black, main, card) => `${scaleKey(scale)}|${white}|${black}|${main}|${card}`);
+export const resolveFilledSurface = (scale, colors) => ({
+    ...filledSurfaceMemo(scale, colors.white, colors.black, colors.backgroundColor.main, colors.background[50]),
+});

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

@@ -0,0 +1,44 @@
+import { contrastRatio, hexToHsl, withLightness } from "./color.js";
+import { AA_NON_TEXT } from "./outlineRung.js";
+import { bandOn } from "./planeStep.js";
+/** Same lightness granularity `buildDarkPalette` walks its accents at. */
+const LIGHTNESS_STEP = 0.5;
+// NOTE: not settleAcross — a ring squeezed between a light canvas and a dark fill needs the closest color that clears both, not a per-surface lift.
+export function settleBetween(hex, backdrops, target = AA_NON_TEXT) {
+    const clears = (candidate) => backdrops.every((backdrop) => contrastRatio(candidate, backdrop) >= target);
+    if (clears(hex))
+        return hex;
+    const { l } = hexToHsl(hex);
+    for (let step = LIGHTNESS_STEP; step <= 100; step += LIGHTNESS_STEP) {
+        const darker = withLightness(hex, l - step);
+        if (clears(darker))
+            return darker;
+        const lighter = withLightness(hex, l + step);
+        if (clears(lighter))
+            return lighter;
+    }
+    // NOTE: unreachable for shipped brands (gated by focusRing.test.ts) — takes the least-bad end rather than throwing.
+    const ends = [withLightness(hex, 0), withLightness(hex, 100)];
+    const worst = (candidate) => Math.min(...backdrops.map((backdrop) => contrastRatio(candidate, backdrop)));
+    return worst(ends[0]) >= worst(ends[1]) ? ends[0] : ends[1];
+}
+// NOTE: canvas, card and the table header band — including the fill or every named surface leaves no solvable hue.
+export const focusRingBackdrops = (source) => [
+    source.backgroundColor.main,
+    source.background[50],
+    source.backgroundColor.tableHeader,
+    bandOn(source.backgroundColor.tableHeader, source.background[50]),
+];
+// NOTE: replaces Chakra's stock ring (a fixed blue that measured under 2:1 on every brand).
+export const buildFocusRing = (source) => {
+    const halo = settleBetween(source.background[50], [source.primary[500]]);
+    return {
+        halo,
+        ring: settleBetween(source.primary[500], [...focusRingBackdrops(source), halo]),
+    };
+};
+// NOTE: re-derives against the FINISHED palette — a brand file can still override primary/background after the generic pass.
+export const withFocusRing = (palette) => ({
+    ...palette,
+    focusRing: buildFocusRing(palette),
+});

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

@@ -0,0 +1,14 @@
+import { onGradient } from "./accentText.js";
+import { resolveAvatarFill } from "./statusTone.js";
+// NOTE: sinks both stops until white ink clears AA — otherwise a mid-tone gradient flips onGradient to black.
+export const inkSafeGradient = (gradient) => ({
+    from: resolveAvatarFill(gradient.from),
+    to: resolveAvatarFill(gradient.to),
+});
+// The only correct way to paint gradient text — returns the stops to draw AND the ink for them together.
+export const resolveGradient = (gradient, white, black) => {
+    const { from, to } = inkSafeGradient(gradient);
+    return { from, to, ink: onGradient(from, to, white, black) };
+};
+/** `linear-gradient(...)` for a resolved pair — one spelling of the CSS everywhere. */
+export const gradientCss = (g, angle = "135deg") => `linear-gradient(${angle}, ${g.from} 0%, ${g.to} 100%)`;

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

@@ -0,0 +1,14 @@
+export * from "./accentText.js";
+export * from "./buildBrandTokens.js";
+export * from "./buildDarkPalette.js";
+export * from "./chartColorsFromTheme.js";
+export * from "./color.js";
+export * from "./focusRing.js";
+export * from "./scrollbar.js";
+export * from "./gradientInk.js";
+export * from "./placeholderInk.js";
+export * from "./tone.js";
+export * from "./scrim.js";
+export * from "./tooltipSurface.js";
+export * from "./surfaceRaised.js";
+export * from "./star.js";

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

@@ -0,0 +1,49 @@
+const dataProperty = (value) => ({
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+});
+// NOTE: first read of any key builds once and swaps every getter for a plain data property.
+export const lazyObject = (keys, build) => {
+    const target = {};
+    let built;
+    const materialise = () => {
+        if (built)
+            return built;
+        const value = build();
+        built = value;
+        if (!Object.isSealed(target)) {
+            keys.forEach((key) => Object.defineProperty(target, key, dataProperty(value[key])));
+        }
+        return value;
+    };
+    keys.forEach((key) => Object.defineProperty(target, key, {
+        enumerable: true,
+        configurable: true,
+        get: () => materialise()[key],
+        set: (next) => {
+            materialise();
+            Object.defineProperty(target, key, dataProperty(next));
+        },
+    }));
+    return target;
+};
+// NOTE: order matches finalizeLightPalette and buildDarkPalette, which append these after the source keys.
+const DERIVED = {
+    accentText: true,
+    textMuted: true,
+    semanticText: true,
+    onPrimary: true,
+    onSemantic: true,
+    focusRing: true,
+    surfaceRaised: true,
+    star: true,
+};
+const DERIVED_KEYS = Object.keys(DERIVED);
+export const paletteKeys = (source) => [
+    ...Object.keys(source),
+    ...DERIVED_KEYS.filter((key) => !(key in source)),
+];
+/** A palette derived from `source` on its first read; same keys, order and values as `build()`. */
+export const lazyPalette = (source, build) => lazyObject(paletteKeys(source), build);

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

@@ -0,0 +1,21 @@
+const registry = [];
+export const MEMO_LIMIT = 1024;
+// NOTE: clear-on-overflow, not LRU — a hit stays one Map lookup; contrast walks mint many one-off keys.
+export const memoize = (fn, keyOf, limit = MEMO_LIMIT) => {
+    const cache = new Map();
+    registry.push({ cache, limit });
+    return (...args) => {
+        const key = keyOf(...args);
+        const hit = cache.get(key);
+        if (hit !== undefined)
+            return hit;
+        const value = fn(...args);
+        if (cache.size >= limit)
+            cache.clear();
+        cache.set(key, value);
+        return value;
+    };
+};
+export const scaleKey = (s) => `${s[50]}|${s[100]}|${s[200]}|${s[300]}|${s[400]}|${s[500]}|${s[600]}|${s[700]}|${s[800]}|${s[900]}`;
+export const memoCaches = () => registry.map(({ cache, limit }) => ({ size: cache.size, limit }));
+export const clearMemoCaches = () => registry.forEach(({ cache }) => cache.clear());