pixelize-design-library 2.4.2 → 3.0.0

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

@@ -1,19 +1,11 @@
 import { onGradient } from "./accentText.js";
 import { resolveAvatarFill } from "./statusTone.js";
-/**
- * Sinks both stops until WHITE ink clears AA, keeping each stop's hue. Any mid-tone gradient
- * otherwise flips `onGradient` to black ink, so the same element reads white-on-colour in one
- * brand and black-on-pastel in the next.
- */
+// 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 text on a gradient: returns the stops to draw AND the ink for
- * them. Calling `onGradient` on raw stops is the black-text bug — it picks ink for a backdrop
- * that is then painted differently.
- */
+// 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) };

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

@@ -3,6 +3,12 @@ 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());

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

@@ -0,0 +1,46 @@
+export const READS_MEMO_LIMIT = 16;
+// NOTE: keyed on exactly the props a call read; a call that enumerates or probes props is never cached.
+export const memoiseByReads = (fn, limit = READS_MEMO_LIMIT) => {
+    const entries = [];
+    return (props) => {
+        const source = props;
+        const hit = entries.find((entry) => entry.keys.every((key, i) => Object.is(source[key], entry.values[i])));
+        if (hit)
+            return hit.result;
+        const reads = new Map();
+        let opaque = false;
+        const tracked = new Proxy(props, {
+            get(target, key, receiver) {
+                const value = Reflect.get(target, key, receiver);
+                if (typeof key !== "string")
+                    opaque = true;
+                else if (!reads.has(key))
+                    reads.set(key, value);
+                return value;
+            },
+            has(target, key) {
+                opaque = true;
+                return Reflect.has(target, key);
+            },
+            ownKeys(target) {
+                opaque = true;
+                return Reflect.ownKeys(target);
+            },
+            getOwnPropertyDescriptor(target, key) {
+                opaque = true;
+                return Reflect.getOwnPropertyDescriptor(target, key);
+            },
+        });
+        const result = fn(tracked);
+        if (!opaque) {
+            if (entries.length >= limit)
+                entries.shift();
+            entries.push({
+                keys: [...reads.keys()],
+                values: [...reads.values()],
+                result,
+            });
+        }
+        return result;
+    };
+};

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

@@ -1,5 +1,15 @@
+import { contrastRatio, hexToHsl, relativeLuminance, withLightness } from "./color.js";
 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);
+export const MUTED_TEXT_CEILING = 8;
+const settleUnder = (hex, canvas, ceiling) => {
+    const { s, l } = hexToHsl(hex);
+    const toward = relativeLuminance(canvas) < 0.5 ? -1 : 1;
+    let settled = hex;
+    for (let next = l; contrastRatio(settled, canvas) > ceiling; next += toward) {
+        settled = withLightness(hex, next, s);
+    }
+    return settled;
+};
+export const buildMutedText = (text, canvas) => liftToContrast(settleUnder(text[400], canvas, MUTED_TEXT_CEILING), canvas, AA_NORMAL_TEXT);

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

@@ -1,42 +1,30 @@
 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.
- */
+import { memoize } from "./memo.js";
 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;
-/**
- * Resting chrome — card, popover and field outlines — settles here, not at `AA_NON_TEXT`.
- * At 3:1 a container border is text-weight and the UI reads as a wireframe; every mainstream
- * system draws this line far lighter (Tailwind gray-200 1.24, Chakra gray.200 1.30, Material
- * outline-variant 1.61). 1.4.11 asks that a control be identifiable, not that its resting
- * border carry the whole job: the fill, the label and the focus ring do that, and the focus
- * ring is still held to `AA_NON_TEXT`.
- */
+// NOTE: settles below AA_NON_TEXT — focusRing.ts covers the 1.4.11 gate instead.
 export const CHROME_BORDER = 1.5;
-// The resting rule between two surfaces — a card edge, a divider, a menu outline. Lighter than
-// CHROME_BORDER, which outlines a control the user acts on.
 export const CHROME_RULE = 1.31;
-/**
- * A rule is decorative, so it has a ceiling and no floor: soften it until the surface it reads
- * hardest against sits at `target`, and leave a already-fainter rung alone. Never `settleAcross`
- * here — that clears a floor on EVERY surface, so one tinted surface drags the rule darker.
- */
 export function ruleInk(hex, surfaces, target) {
     const loudest = surfaces.reduce((worst, s) => contrastRatio(hex, s) > contrastRatio(hex, worst) ? s : worst);
     return contrastRatio(hex, loudest) > target
         ? softenToContrast(hex, loudest, target)
         : hex;
 }
-/**
- * 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) {
+export const STACKED_STATE_STEP = 1.08;
+// NOTE: walks out from the backdrop, so it settles a too-loud seed down as readily as it lifts a faint one.
+export function tintStep(seed, backdrop, target) {
+    const { s } = hexToHsl(seed);
+    const away = relativeLuminance(backdrop) < 0.5 ? 1 : -1;
+    for (let l = hexToHsl(backdrop).l; l >= 0 && l <= 100; l += away) {
+        const next = withLightness(seed, l, s);
+        if (contrastRatio(next, backdrop) >= target)
+            return next;
+    }
+    return withLightness(seed, away > 0 ? 100 : 0, s);
+}
+const contrastKey = (hex, backdrop, target) => `${hex}|${backdrop}|${target}`;
+const liftMemo = memoize((hex, backdrop, target) => {
     if (contrastRatio(hex, backdrop) >= target)
         return hex;
     const { s, l: start } = hexToHsl(hex);
@@ -52,12 +40,11 @@ export function liftToContrast(hex, backdrop, target = AA_NON_TEXT) {
     }
     const ends = [withLightness(hex, 100, s), withLightness(hex, 0, s)];
     return contrastRatio(ends[0], backdrop) >= contrastRatio(ends[1], backdrop) ? ends[0] : ends[1];
+}, contrastKey);
+export function liftToContrast(hex, backdrop, target = AA_NON_TEXT) {
+    return liftMemo(hex, backdrop, target);
 }
-/**
- * Mirror of `liftToContrast`: walks ink TOWARD the backdrop, stopping at the last step that
- * still clears `target`. For ink that must stay legible without reading as body copy.
- */
-export function softenToContrast(hex, backdrop, target) {
+const softenMemo = memoize((hex, backdrop, target) => {
     if (contrastRatio(hex, backdrop) <= target)
         return hex;
     const { s, l: start } = hexToHsl(hex);
@@ -70,21 +57,13 @@ export function softenToContrast(hex, backdrop, target) {
         softest = next;
     }
     return softest;
+}, contrastKey);
+export function softenToContrast(hex, backdrop, target) {
+    return softenMemo(hex, backdrop, target);
 }
-/**
- * `boxborder[500]` is the rung every control outline reads (Checkbox, SearchSelect, the date
- * pickers, the editor's inputs). Settled onto `CHROME_BORDER` — lifted when a brand authored it
- * invisibly pale, softened when it overshoots. It was previously lifted to `AA_NON_TEXT`, which
- * shipped 3.85-4.95:1 outlines: a text-weight box around every card and popover.
- * 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.
- */
+// NOTE: border[*] is untouched — it draws decorative table gridlines, 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
@@ -96,23 +75,10 @@ export function withOutlineRung(palette) {
         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);
 }
-/**
- * Settles ink into `target` against EVERY surface at once. Softening one step can change which
- * surface is hardest, so resolving against a single pre-computed "hardest" one lands under the
- * floor on another — that is how radiant and rosewood ended up with an invisible outline on
- * their muted surface.
- */
+// NOTE: settles against every surface at once — a single "hardest" surface can drop under target on another.
 export function settleAcross(hex, surfaces, target) {
     const clearsAll = (c) => surfaces.every((s) => contrastRatio(c, s) >= target);
     if (!clearsAll(hex)) {
@@ -129,3 +95,17 @@ export function settleAcross(hex, surfaces, target) {
     }
     return settled;
 }
+// NOTE: binary search, not liftToContrast — a seed already at lightness 0/100 can't walk.
+export function neutralStep(backdrop, target) {
+    const grey = (l) => withLightness("#808080", l, 0);
+    let lo = hexToHsl(backdrop).l;
+    let hi = relativeLuminance(backdrop) < 0.5 ? 100 : 0;
+    for (let i = 0; i < 20; i += 1) {
+        const mid = (lo + hi) / 2;
+        if (contrastRatio(grey(mid), backdrop) < target)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return grey(hi);
+}

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

@@ -0,0 +1,6 @@
+const isColorScale = (value) => typeof value === "object" && value !== null && "500" in value;
+export const scaleNamed = (colors, name) => {
+    const entries = colors;
+    const value = entries[name];
+    return isColorScale(value) ? value : undefined;
+};

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

@@ -1,14 +1,7 @@
 import { contrastRatio } from "./color.js";
 import { liftToContrast, softenToContrast } from "./outlineRung.js";
 import { PLACEHOLDER_TEXT } from "./surfaceRungs.js";
-/**
- * The hint ink for a field: the brand's authored rung settled onto `PLACEHOLDER_TEXT` against the
- * hardest surface a field can land on — lifted when it falls short, softened when it overshoots.
- *
- * Settled rather than floored because the authored rungs measured 3.96-7.73:1 across the brands,
- * and anything much past the floor reads as a field already typed into. The floor is the look:
- * one hint weight for every brand in both modes, instead of a per-brand accident.
- */
+// NOTE: settled (not floored) onto PLACEHOLDER_TEXT — one hint weight across brands, not a per-brand accident.
 export const placeholderInkOn = (palette, surfaces) => {
     const rung = palette.placeholder[500];
     const hardest = surfaces.reduce((worst, s) => contrastRatio(rung, s) < contrastRatio(rung, worst) ? s : worst);
@@ -16,10 +9,7 @@ export const placeholderInkOn = (palette, surfaces) => {
         ? softenToContrast(rung, hardest, PLACEHOLDER_TEXT)
         : liftToContrast(rung, hardest, PLACEHOLDER_TEXT);
 };
-/**
- * Every surface an ENABLED field renders on. Disabled fields are deliberately absent — 1.4.3
- * exempts them, and folding their dimmer fill in here would darken the hint on every other field.
- */
+// NOTE: enabled fields only — 1.4.3 exempts disabled ones, and folding their dimmer fill in would darken every other field's hint.
 export const fieldSurfaces = (palette) => [
     palette.gray[50],
     palette.background[50],

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

@@ -0,0 +1,14 @@
+import { DEFAULT_BLACK, isDarkCanvas } from "./accentText.js";
+import { contrastRatio } from "./color.js";
+import { CHROME_RULE, MIN_PERCEPTIBLE_STEP, liftToContrast, tintStep } from "./outlineRung.js";
+import { lift } from "./planes.js";
+const holds = (fill, plane, target) => !isDarkCanvas(plane) || contrastRatio(fill, plane) >= target;
+export const bandOn = (fill, plane) => holds(fill, plane, MIN_PERCEPTIBLE_STEP) ? fill : tintStep(fill, plane, MIN_PERCEPTIBLE_STEP);
+export const recessOn = (fill, plane) => holds(fill, plane, MIN_PERCEPTIBLE_STEP)
+    ? fill
+    : lift(DEFAULT_BLACK, plane, MIN_PERCEPTIBLE_STEP);
+export const ruleOn = (colors, plane) => {
+    const rule = colors.boxborder[200];
+    return holds(rule, plane, CHROME_RULE) ? rule : liftToContrast(rule, plane, CHROME_RULE);
+};
+export const cardRule = (colors) => ruleOn(colors, colors.background[50]);

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

@@ -0,0 +1,28 @@
+import { contrastRatio, mix } from "./color.js";
+import { AA_NON_TEXT } from "./outlineRung.js";
+export const CARD_LIFT = 1.16;
+export const RAISED_LIFT = 1.15;
+const STEP = 0.005;
+const MAX_WEIGHT = 0.4;
+export function lift(ink, base, target) {
+    for (let t = STEP * 4; t < MAX_WEIGHT; t += STEP) {
+        const next = mix(base, ink, t);
+        if (contrastRatio(next, base) >= target)
+            return next;
+    }
+    return mix(base, ink, MAX_WEIGHT);
+}
+const clearsMarks = (surface, marks) => marks.every((mark) => contrastRatio(mark, surface) >= AA_NON_TEXT);
+// NOTE: stops one step early rather than drop a filled mark under 3:1 on the lifted plane.
+export function liftUnder(ink, base, target, marks) {
+    let settled = base;
+    for (let t = STEP * 4; t < MAX_WEIGHT; t += STEP) {
+        const next = mix(base, ink, t);
+        if (!clearsMarks(next, marks))
+            return settled;
+        if (contrastRatio(next, base) >= target)
+            return next;
+        settled = next;
+    }
+    return settled;
+}

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

@@ -0,0 +1,37 @@
+import radii from "../primitives/radii.js";
+import { chartInk, getCategoricalSeriesColors } from "./chartColorsFromTheme.js";
+const FONT = "inherit";
+const FONT_SIZE = "12px";
+const DASH = "4 4";
+// Reuses chartInk/getCategoricalSeriesColors — no parallel color derivation. No recharts import.
+export function buildRechartsTheme(colors) {
+    const ink = chartInk(colors);
+    return {
+        seriesColors: getCategoricalSeriesColors(colors),
+        grid: { stroke: ink.grid, strokeDasharray: DASH },
+        axis: {
+            stroke: ink.grid,
+            tick: { fill: ink.axis, fontSize: FONT_SIZE, fontFamily: FONT },
+        },
+        tooltip: {
+            contentStyle: {
+                backgroundColor: ink.tooltipBg,
+                border: `1px solid ${ink.grid}`,
+                borderRadius: radii.md,
+                color: ink.text,
+                fontSize: FONT_SIZE,
+                fontFamily: FONT,
+            },
+            labelStyle: { color: ink.text, fontWeight: 600 },
+            itemStyle: { color: ink.text },
+            cursor: { stroke: ink.grid, strokeDasharray: DASH },
+        },
+        legend: {
+            wrapperStyle: { color: ink.muted, fontSize: FONT_SIZE, fontFamily: FONT },
+        },
+        referenceLine: { stroke: ink.muted, strokeDasharray: DASH },
+        surface: ink.surface,
+        text: ink.text,
+        muted: ink.muted,
+    };
+}

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

@@ -1,11 +1,7 @@
 import { liftToContrast, AA_NON_TEXT } from "./outlineRung.js";
 import { AA_NORMAL_TEXT } from "./accentText.js";
 import { PLACEHOLDER_TEXT } from "./surfaceRungs.js";
-/**
- * A hint is floored at 3:1, not 4.5:1. Held to body-text contrast it stopped reading as a hint —
- * an empty field looked like one already typed into — and the published library ships this rung
- * as the brand authored it. See CHROME-CONSISTENCY.md.
- */
+// NOTE: hint floored at 3:1, not 4.5:1 — held to body-text contrast it read as already-typed-into. See CHROME-CONSISTENCY.md.
 export function withPlaceholderRung(palette) {
     const resolved = liftToContrast(palette.placeholder[500], palette.background[50], PLACEHOLDER_TEXT);
     if (resolved === palette.placeholder[500])

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

@@ -0,0 +1,22 @@
+import { contrastRatio } from "./color.js";
+import { AA_NON_TEXT, MIN_PERCEPTIBLE_STEP, neutralStep, resolveHoverTint, STACKED_STATE_STEP, tintStep, } from "./outlineRung.js";
+export const listRowBackgrounds = (colors) => {
+    // Raw tertiary reaches 1.29:1 and reads as pressed; dark aliases it to the panel at 1.025:1.
+    const selected = tintStep(colors.backgroundColor.tertiary, colors.surfaceRaised, MIN_PERCEPTIBLE_STEP);
+    return {
+        active: resolveHoverTint(colors.gray[50], colors.surfaceRaised),
+        selected,
+        selectedActive: tintStep(selected, selected, STACKED_STATE_STEP),
+    };
+};
+export const SELECTED_ROW_STEP = 1.28;
+export const DISTINCT_ROW_STEP = 1.1;
+// NOTE: every rung is a neutral step off the panel, so hover and selected carry no brand hue in either mode.
+export const selectRowBackgrounds = (colors) => {
+    const panel = colors.surfaceRaised;
+    const active = neutralStep(panel, MIN_PERCEPTIBLE_STEP);
+    const selectedStep = Math.max(SELECTED_ROW_STEP, contrastRatio(active, panel) * DISTINCT_ROW_STEP);
+    const selected = neutralStep(panel, selectedStep);
+    const selectedActive = neutralStep(selected, STACKED_STATE_STEP);
+    return { active, selected, selectedActive, keyboardRing: neutralStep(selectedActive, AA_NON_TEXT) };
+};

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

@@ -0,0 +1,12 @@
+import { hexToRgb } from "./color.js";
+export const SCRIM_OPACITY = 0.6;
+export const BACKDROP_SCRIM_OPACITY = 0.5;
+/** Modal/Drawer backdrop: `black` never remaps between modes, so one alpha works in both. */
+export const overlayScrim = (colors) => {
+    const { r, g, b } = hexToRgb(colors.black);
+    return `rgba(${r}, ${g}, ${b}, ${SCRIM_OPACITY})`;
+};
+export const backdropScrim = (colors) => {
+    const { r, g, b } = hexToRgb(colors.black);
+    return `rgba(${r}, ${g}, ${b}, ${BACKDROP_SCRIM_OPACITY})`;
+};

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

@@ -0,0 +1,28 @@
+import { isDarkCanvas } from "./accentText.js";
+const EDGE = "24px";
+const TINT = "rgba(0, 0, 0, 0.08)";
+const TINT_ON_DARK = "rgba(0, 0, 0, 0.32)";
+const VERTICAL_SHADOW = "8px";
+// CSS-only overflow hint via background-attachment local vs scroll — no listener, no extra node.
+export function scrollShadowStyles(surface) {
+    return {
+        backgroundColor: surface,
+        backgroundImage: `linear-gradient(to right, ${surface}, ${surface}), linear-gradient(to left, ${surface}, ${surface}), linear-gradient(to right, ${TINT}, transparent), linear-gradient(to left, ${TINT}, transparent)`,
+        backgroundRepeat: "no-repeat",
+        backgroundSize: `${EDGE} 100%, ${EDGE} 100%, 8px 100%, 8px 100%`,
+        backgroundPosition: "0 0, 100% 0, 0 0, 100% 0",
+        backgroundAttachment: "local, local, scroll, scroll",
+    };
+}
+// NOTE: dark panels swallow an 8% black edge, so the vertical hint steps up on a dark surface.
+export function scrollShadowStylesVertical(surface) {
+    const tint = isDarkCanvas(surface) ? TINT_ON_DARK : TINT;
+    return {
+        backgroundColor: surface,
+        backgroundImage: `linear-gradient(${surface}, ${surface}), linear-gradient(${surface}, ${surface}), linear-gradient(${tint}, transparent), linear-gradient(transparent, ${tint})`,
+        backgroundRepeat: "no-repeat",
+        backgroundSize: `100% ${EDGE}, 100% ${EDGE}, 100% ${VERTICAL_SHADOW}, 100% ${VERTICAL_SHADOW}`,
+        backgroundPosition: "0 0, 0 100%, 0 0, 0 100%",
+        backgroundAttachment: "local, local, scroll, scroll",
+    };
+}