pixelize-design-library 2.4.2-beta.9 → 3.0.0

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

@@ -1,19 +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;
-/**
- * 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) {
+// NOTE: settles below AA_NON_TEXT — focusRing.ts covers the 1.4.11 gate instead.
+export const CHROME_BORDER = 1.5;
+export const CHROME_RULE = 1.31;
+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;
+}
+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);
@@ -29,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);
@@ -47,37 +57,55 @@ 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). 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.
- */
+// 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
         : palette.background[50];
-    const resolved = liftToContrast(current, backdrop);
+    const resolved = contrastRatio(current, backdrop) > CHROME_BORDER
+        ? softenToContrast(current, backdrop, CHROME_BORDER)
+        : liftToContrast(current, backdrop, CHROME_BORDER);
     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);
 }
+// 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)) {
+        return surfaces.reduce((ink, s) => liftToContrast(ink, s, target), hex);
+    }
+    const { s: sat, l: start } = hexToHsl(hex);
+    const toward = relativeLuminance(surfaces[0]) < 0.5 ? -1 : 1;
+    let settled = hex;
+    for (let l = start; l > 0 && l < 100; l += toward) {
+        const next = withLightness(hex, l, sat);
+        if (!clearsAll(next))
+            break;
+        settled = next;
+    }
+    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,23 +1,15 @@
 import { contrastRatio } from "./color.js";
-import { liftToContrast } from "./outlineRung.js";
+import { liftToContrast, softenToContrast } from "./outlineRung.js";
 import { PLACEHOLDER_TEXT } from "./surfaceRungs.js";
-/**
- * The hint ink for a field: the rung the brand authored, guaranteed to clear `PLACEHOLDER_TEXT`
- * on every surface a field can land on.
- *
- * It does not walk the rung toward AA in either direction. Lifting it to 4.5 made an empty field
- * read as one already typed into; softening it back down again undershot on the next surface.
- * The published library ships this rung untouched and that is the look being matched.
- */
+// 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);
-    return liftToContrast(rung, hardest, PLACEHOLDER_TEXT);
+    return contrastRatio(rung, hardest) > PLACEHOLDER_TEXT
+        ? 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",
+    };
+}

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

@@ -1,10 +1,7 @@
 /** One width everywhere. The 3px, 4px, 5px and 10px bars in use were all accidents. */
 export const SCROLLBAR_WIDTH = "6px";
 const RADIUS = "6px";
-/**
- * The single source of scrollbar chrome. `overlay` drops the track for bars that float over a
- * card; `hover` keeps the thumb invisible until the region is hovered.
- */
+// NOTE: single source of scrollbar chrome — `overlay` drops the track, `hover` hides the thumb until hovered.
 export function scrollbarStyles(palette, variant = "default") {
     const { gray } = palette;
     const track = variant === "default" ? gray[100] : "transparent";

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

@@ -1,11 +1,7 @@
 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.
- */
+// NOTE: semantic[tone][500] is a fill rung (1.84-3.68:1 as text) — stepped here until it clears AA.
 export const buildSemanticText = (semantic, canvas) => SEMANTIC_TONES.reduce((acc, tone) => {
     acc[tone] = liftToContrast(semantic[tone][500], canvas, AA_NORMAL_TEXT);
     return acc;

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

@@ -1,23 +1,36 @@
 import { compositeOver } from "./color.js";
-import { liftToContrast, resolveHoverTint, AA_NON_TEXT } from "./outlineRung.js";
+import { liftToContrast, resolveHoverTint, settleAcross, 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]);
+/** Lightest a row ever gets on ANY rail surface — what chrome inside a row must clear. */
+export const sidebarRowPeak = (surface) => compositeOver(ACTIVE_SURFACE_TINT, surface);
+/** Stronger than the divider — a hover fill must read as an action, not a rule. */
+export const HOVER_SURFACE_TINT = "#ffffff20";
+/** Chakra whiteAlpha.100 (0.06) — a divider only needs to read, not shout. */
+export const DIVIDER_SURFACE_TINT = "#ffffff0f";
+export const sidebarHoverSurface = (background) => resolveHoverTint(compositeOver(HOVER_SURFACE_TINT, background[500]), background[500]);
+export const sidebarDivider = (background) => resolveHoverTint(compositeOver(DIVIDER_SURFACE_TINT, background[500]), 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]);
+    // Muted chrome must clear contrast on the bare rail AND the lightest row-hover overlay.
+    const rowPeak = sidebarRowPeak(elevated);
     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),
+        mutedIcon: settleAcross(background[300], [elevated, rowPeak], AA_NON_TEXT),
+        mutedLabel: settleAcross(background[100], [elevated, rowPeak], AA_NORMAL_TEXT),
         semanticText: buildSemanticText(semantic, elevated),
+        hoverBg: sidebarHoverSurface(background),
+        activeBg: surface,
+        divider: sidebarDivider(background),
     };
 };
 export const withSidebarTokens = (source) => buildSidebarTokens(source.sidebar.background, source.primary, source.semantic);

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

@@ -0,0 +1,21 @@
+import { contrastRatio, hexToHsl, relativeLuminance, withLightness } from "./color.js";
+/** Same pulse depth as the mobile library's `SKELETON_SHIMMER_CONTRAST`. */
+export const SKELETON_SHIMMER_CONTRAST = 1.35;
+const settleAway = (seed, base, target) => {
+    const { s } = hexToHsl(seed);
+    let near = hexToHsl(base).l;
+    let far = relativeLuminance(base) < 0.5 ? 100 : 0;
+    for (let i = 0; i < 20; i += 1) {
+        const mid = (near + far) / 2;
+        if (contrastRatio(withLightness(seed, mid, s), base) < target)
+            near = mid;
+        else
+            far = mid;
+    }
+    return withLightness(seed, far, s);
+};
+/** The two colours a Skeleton pulses between: `gray[100]`, and `gray[300]`'s tint settled to the amplitude. */
+export const skeletonShimmer = (palette) => ({
+    start: palette.gray[100],
+    end: settleAway(palette.gray[300], palette.gray[100], SKELETON_SHIMMER_CONTRAST),
+});

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

@@ -0,0 +1,4 @@
+import { relativeLuminance } from "./color.js";
+export const STAR_ON_LIGHT = "#f5a70a";
+export const STAR_ON_DARK = "#f6b93b";
+export const buildStar = (canvas) => relativeLuminance(canvas) > 0.18 ? STAR_ON_LIGHT : STAR_ON_DARK;

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

@@ -1,15 +1,7 @@
 import { contrastRatio } from "./color.js";
 import { AA_NORMAL_TEXT } from "./accentText.js";
 import { AA_NON_TEXT, liftToContrast } from "./outlineRung.js";
-/**
- * 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.
- */
+// NOTE: X.500-on-X.100 measured 3.3-4.4:1 (under AA) — ink is resolved per brand/mode instead of pinned.
 export function resolveStatusTone(scale, mode) {
     const bg = scale[100];
     const inkSeed = mode === "dark" ? scale[300] : scale[700];
@@ -20,18 +12,11 @@ export function resolveStatusTone(scale, mode) {
         border: liftToContrast(edgeSeed, bg, 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.
- */
+// NOTE: seed hues measured as low as 1.92:1 for white initials — darkened here to clear AA, hue kept.
 export function resolveAvatarFill(hex, target = AA_NORMAL_TEXT) {
     return liftToContrast(hex, "#ffffff", target);
 }
-/**
- * Hue set for generated avatars. Values are seeds, not final fills — always pass them through
- * `resolveAvatarFill` so the white initials stay legible.
- */
+// Seeds only, not final fills — always pass through resolveAvatarFill so white initials stay legible.
 export const AVATAR_SEEDS = [
     "#ef4444",
     "#f97316",
@@ -43,7 +28,7 @@ export const AVATAR_SEEDS = [
     "#8b5cf6",
     "#ec4899",
 ];
-/** Stable per-name avatar fill: same name always yields the same accessible colour. */
+/** @deprecated Use `resolveAvatarColorway(seed, colors)` — different arity and returns `{bg, color}`. */
 export function avatarFillFor(seedText) {
     let hash = 0;
     for (let i = 0; i < seedText.length; i++) {

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

@@ -0,0 +1,24 @@
+import { contrastRatio, mix, relativeLuminance } from "./color.js";
+import { liftToContrast } from "./outlineRung.js";
+import { RAISED_LIFT, liftUnder } from "./planes.js";
+import { cardRule } from "./planeStep.js";
+import { SEMANTIC_TONES } from "./semanticText.js";
+export const RAISED_OVERLAY = 0.07;
+/** The filled fills a raised plane must keep at 3:1, or a button on a menu stops reading. */
+export const filledMarks = (colors) => [
+    colors.primary[500],
+    ...SEMANTIC_TONES.map((tone) => colors.semantic[tone][500]),
+];
+// Never below the card: the lighter of one white-overlay step off the canvas and a RAISED_LIFT step off the card.
+export const buildSurfaceRaised = (source, marks = []) => {
+    const card = source.background[50];
+    const overlay = mix(source.backgroundColor.main, source.white, RAISED_OVERLAY);
+    const stepped = liftUnder(source.white, card, RAISED_LIFT, marks);
+    return [overlay, stepped].reduce((top, c) => (relativeLuminance(c) > relativeLuminance(top) ? c : top), card);
+};
+export const withSurfaceRaised = (palette) => ({
+    ...palette,
+    surfaceRaised: buildSurfaceRaised(palette, filledMarks(palette)),
+});
+// A divider inside an overlay, at the weight a rule has inside a card.
+export const raisedRule = (colors) => liftToContrast(colors.boxborder[200], colors.surfaceRaised, contrastRatio(cardRule(colors), colors.background[50]));

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

@@ -1,15 +1,14 @@
 import { contrastRatio } from "./color.js";
-import { liftToContrast, AA_NON_TEXT } from "./outlineRung.js";
+import { liftToContrast, settleAcross, ruleInk, AA_NON_TEXT, CHROME_BORDER, CHROME_RULE } from "./outlineRung.js";
 import { AA_NORMAL_TEXT, pickAccentText } from "./accentText.js";
 import { SEMANTIC_TONES } from "./semanticText.js";
-/**
- * A hint is held to the non-text floor, not the body-text one. Deliberate: at 4.5 an empty field
- * reads as one already typed into. See CHROME-CONSISTENCY.md.
- */
+import { listRowBackgrounds } from "./rowStates.js";
+// NOTE: hint held to the non-text floor, not body-text — at 4.5 an empty field reads as typed-into. See CHROME-CONSISTENCY.md.
 export const PLACEHOLDER_TEXT = AA_NON_TEXT;
 export const namedSurfaces = (palette) => [
     ...Object.values(palette.backgroundColor),
     palette.background[50],
+    palette.surfaceRaised,
     palette.table.hover[500],
 ];
 /** The surface an ink is closest to — clearing it clears every other one. */
@@ -17,7 +16,10 @@ export const hardestSurface = (ink, surfaces) => surfaces.reduce((worst, s) => c
 // Runs last: `table.hover` is one of the surfaces, and it settles in its own rung.
 export function withSurfaceRungs(palette) {
     const surfaces = namedSurfaces(palette);
+    const accentSurfaces = [...surfaces, ...Object.values(listRowBackgrounds(palette))];
     const lift = (ink, target) => liftToContrast(ink, hardestSurface(ink, surfaces), target);
+    const settle = (ink, target) => settleAcross(ink, surfaces, target);
+    const rule = (ink) => ruleInk(ink, [palette.backgroundColor.main, palette.background[50]], CHROME_RULE);
     const semanticText = SEMANTIC_TONES.reduce((acc, tone) => {
         acc[tone] = lift(palette.semanticText[tone], AA_NORMAL_TEXT);
         return acc;
@@ -25,13 +27,18 @@ export function withSurfaceRungs(palette) {
     return {
         ...palette,
         textMuted: lift(palette.textMuted, AA_NORMAL_TEXT),
-        accentText: pickAccentText(palette.primary, hardestSurface(palette.accentText, surfaces)),
+        accentText: pickAccentText(palette.primary, hardestSurface(palette.accentText, accentSurfaces)),
         semanticText,
         text: { ...palette.text, 500: lift(palette.text[500], AA_NORMAL_TEXT) },
         header: { ...palette.header, 500: lift(palette.header[500], AA_NORMAL_TEXT) },
-        // `placeholder` is deliberately absent: the brand authors that rung and the published
-        // library ships it untouched. Its floor is enforced in `placeholderInk`, against the
-        // surfaces a FIELD renders on — not `table.hover`, which no field sits on.
-        boxborder: { ...palette.boxborder, 500: lift(palette.boxborder[500], AA_NON_TEXT) },
+        boxborder: {
+            ...palette.boxborder,
+            200: rule(palette.boxborder[200]),
+            // NOTE: settled, not lifted — lifting again here to AA_NON_TEXT shipped 3.85-4.95:1 outlines.
+            500: settle(palette.boxborder[500], CHROME_BORDER),
+        },
+        // The 200 rung of both ramps is the same job under two names; settle them together or an
+        // app picking `border` gets a heavier rule than one picking `boxborder`.
+        border: { ...palette.border, 200: rule(palette.border[200]) },
     };
 }

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

@@ -0,0 +1,48 @@
+import { isDarkCanvas } from "./accentText.js";
+import { compositeOver } from "./color.js";
+import { liftToContrast } from "./outlineRung.js";
+import { memoize } from "./memo.js";
+export const TONES = ["neutral", "info", "success", "warning", "error"];
+export const toneToColorScheme = {
+    neutral: "gray",
+    info: "blue",
+    success: "green",
+    warning: "orange",
+    error: "red",
+};
+export const toneToSemantic = {
+    info: "info",
+    success: "success",
+    warning: "warning",
+    error: "error",
+};
+export const isTone = (value) => typeof value === "string" && TONES.includes(value);
+export const toneScale = (colors, tone) => colors[toneToColorScheme[tone]];
+/** Status ink on the canvas: `semanticText.<tone>`, or `textMuted` for neutral. */
+export const toneInk = (colors, tone) => tone === "neutral" ? colors.textMuted : colors.semanticText[toneToSemantic[tone]];
+const BG_ALPHA = { light: 0.1, dark: 0.17 };
+const RING_ALPHA = { light: 0.22, dark: 0.28 };
+const STATE_STEP = 0.08;
+const SOFT_INK_TARGET = 6.5;
+const withAlpha = (hex, alpha) => `${hex}${Math.round(Math.min(1, Math.max(0, alpha)) * 255)
+    .toString(16)
+    .padStart(2, "0")}`;
+const softToneMemo = memoize((hue, surface) => {
+    const dark = isDarkCanvas(surface);
+    const bgAlpha = dark ? BG_ALPHA.dark : BG_ALPHA.light;
+    const ringAlpha = dark ? RING_ALPHA.dark : RING_ALPHA.light;
+    const bg = withAlpha(hue, bgAlpha);
+    const border = withAlpha(hue, ringAlpha);
+    const fg = liftToContrast(hue, compositeOver(bg, surface), SOFT_INK_TARGET);
+    return {
+        bg,
+        fg,
+        border,
+        hoverBg: withAlpha(hue, bgAlpha + STATE_STEP),
+        hoverBorder: withAlpha(hue, ringAlpha + STATE_STEP * 1.5),
+        activeBg: withAlpha(hue, bgAlpha + STATE_STEP * 1.75),
+        activeBorder: withAlpha(hue, ringAlpha + STATE_STEP * 2),
+    };
+}, (hue, surface) => `${hue}|${surface}`);
+/** Translucent tint of the scale's own `[500]` hue — one rung for every scheme, any surface. */
+export const resolveSoftTone = (colors, scale, surface = colors.backgroundColor.main) => ({ ...softToneMemo(scale[500], surface) });

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

@@ -0,0 +1,6 @@
+import { onFilled } from "./accentText.js";
+/** The one tooltip chip: the rail surface stays dark in both modes, so it floats over either canvas. */
+export const tooltipSurface = (colors) => {
+    const bg = colors.sidebar.background[500];
+    return { bg, fg: onFilled(bg, colors.white, colors.black) };
+};

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

@@ -0,0 +1,6 @@
+/** Full viewport height. `dvh` excludes mobile browser chrome; `vh` does not. */
+export const fullViewportHeight = {
+    height: "100vh",
+    "@supports (height: 100dvh)": { height: "100dvh" },
+};
+export default fullViewportHeight;

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

@@ -1,13 +1,4 @@
-/**
- * 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.
- */
+// NOTE: purity contract — nothing here imports Chakra/React/CSS, so the mobile design library can consume it as-is.
 export * from "./types.js";
 export * from "./primitives/index.js";
 export * from "./brands/index.js";