pixelize-design-library 2.4.2-beta.5 → 2.4.2-beta.50

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

@@ -1,19 +1,6 @@
-/**
- * Pure color math. No dependencies, no platform APIs — safe for the mobile port.
- *
- * Used by `buildDarkPalette` to derive dark ramps from each brand's own light colors,
- * and to assert contrast in tests.
- */
+// Pure color math, no dependencies or platform APIs — safe for the mobile port.
 const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
-/**
- * Accepts `#rgb` or `#rrggbb` only. An `#rrggbbaa` throws ON PURPOSE.
- *
- * The old version silently dropped the alpha and returned the fully-opaque rgb. That made
- * `contrastRatio` score a 16%-alpha hover tint as if it were solid — a measured 4.18 for a fill that
- * actually renders at 1.17 over the canvas, a 3.6x overstatement — with a doc comment saying "alpha
- * ignored" that made it look handled. Alpha over an unknown backdrop has no defined luminance, so the
- * only correct move is to refuse it: composite it first with `compositeOver`, then measure the result.
- */
+// 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)
@@ -36,11 +23,7 @@ export function hexToRgba(hex) {
     }
     return { ...hexToRgb(`#${h}`), a: 1 };
 }
-/**
- * Flatten a translucent foreground onto an opaque backdrop — the ONLY way to get a real color for a
- * tint before measuring contrast. `contrastRatio(tint, canvas)` now throws; the correct call is
- * `contrastRatio(compositeOver(tint, canvas), canvas)`.
- */
+// 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);

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

@@ -0,0 +1,77 @@
+import { contrastRatio } from "./color.js";
+import { AA_NORMAL_TEXT, isDarkCanvas, onFilled } from "./accentText.js";
+import { AA_NON_TEXT } from "./outlineRung.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) ? -100 : 100;
+    return Math.min(900, Math.max(50, base + dir * step));
+};
+/** Hover (step 0) or active (step 1) fill rung, one step darker than `solidFillRung`. */
+export const darkerFillRung = (scale, canvas, white, step) => {
+    const base = solidFillRung(scale, white, canvas);
+    if (base === 500) {
+        const mode = isDarkCanvas(canvas) ? "dark" : "light";
+        return FILL_STEP_RUNGS[mode][step];
+    }
+    const stepped = steppedRung(base, canvas, step === 0 ? 1 : 2);
+    return stepped;
+};
+/** Label ink for a specific fill swatch — always `onFilled`, exported for style configs. */
+export const labelOnFill = (fill, white, black) => onFilled(fill, white, black);
+// Consumer-facing helper: fill rung + ink for solid/hover/active. Never pair scale[500] with onFilled by hand.
+export const resolveFilledSurface = (scale, colors) => {
+    const { white, black, backgroundColor, background } = colors;
+    const canvas = contrastRatio(scale[500], backgroundColor.main) <= contrastRatio(scale[500], background[50])
+        ? backgroundColor.main
+        : background[50];
+    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),
+    };
+};

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

@@ -0,0 +1,41 @@
+import { contrastRatio, hexToHsl, withLightness } from "./color.js";
+import { AA_NON_TEXT } from "./outlineRung.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: only canvas + card surface — including the fill or every named surface leaves no solvable hue.
+export const focusRingBackdrops = (source) => [
+    source.backgroundColor.main,
+    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,5 +3,11 @@ 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";

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

@@ -1,18 +1,27 @@
 import { contrastRatio, hexToHsl, relativeLuminance, withLightness } from "./color.js";
-/**
- * The floor a hover/active state's step off its own resting surface must clear to be seen at
- * all — same value the SideBar ladder, Accordion, and NavigationBar hover states are held to.
- * A "hover" a user cannot perceive is not a hover.
- */
 export const MIN_PERCEPTIBLE_STEP = 1.15;
-/** WCAG 1.4.11 — a control outline is a UI component boundary, held to 3:1. */
 export const AA_NON_TEXT = 3;
-/**
- * Walks a hex toward `target` contrast against `backdrop`, keeping hue and saturation.
- * Direction is DERIVED from the backdrop, never passed: a mode argument here was redundant
- * with the backdrop in every call site, and a redundant argument is one that can be wrong.
- * Tries the far side first, falls back to the near side, and stops at the first passing step.
- */
+// 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);
+}
 export function liftToContrast(hex, backdrop, target = AA_NON_TEXT) {
     if (contrastRatio(hex, backdrop) >= target)
         return hex;
@@ -30,10 +39,6 @@ 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];
 }
-/**
- * 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) {
     if (contrastRatio(hex, backdrop) <= target)
         return hex;
@@ -48,36 +53,51 @@ export function softenToContrast(hex, backdrop, target) {
     }
     return softest;
 }
-/**
- * `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/placeholderInk.js

@@ -0,0 +1,19 @@
+import { contrastRatio } from "./color.js";
+import { liftToContrast, softenToContrast } from "./outlineRung.js";
+import { PLACEHOLDER_TEXT } from "./surfaceRungs.js";
+// 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 contrastRatio(rung, hardest) > PLACEHOLDER_TEXT
+        ? softenToContrast(rung, hardest, PLACEHOLDER_TEXT)
+        : liftToContrast(rung, hardest, PLACEHOLDER_TEXT);
+};
+// 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],
+    palette.backgroundColor.main,
+];
+/** The hint ink every field in this library reads. Takes no backdrop: see `fieldSurfaces`. */
+export const placeholderInk = (palette) => placeholderInkOn(palette, fieldSurfaces(palette));

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

@@ -1,8 +1,9 @@
 import { liftToContrast, AA_NON_TEXT } from "./outlineRung.js";
 import { AA_NORMAL_TEXT } from "./accentText.js";
-/** Placeholder text measured 4.32:1 on a card for 8 of 9 brands — text, so held to 4.5:1. */
+import { PLACEHOLDER_TEXT } from "./surfaceRungs.js";
+// 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], AA_NORMAL_TEXT);
+    const resolved = liftToContrast(palette.placeholder[500], palette.background[50], PLACEHOLDER_TEXT);
     if (resolved === palette.placeholder[500])
         return palette;
     return { ...palette, placeholder: { ...palette.placeholder, 500: resolved } };

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

@@ -0,0 +1,10 @@
+import { MIN_PERCEPTIBLE_STEP, 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),
+    };
+};

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,13 @@
+const EDGE = "24px";
+const TINT = "rgba(0, 0, 0, 0.08)";
+// 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",
+    };
+}

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

@@ -6,6 +6,14 @@ 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);
@@ -18,6 +26,9 @@ export const buildSidebarTokens = (background, lightPrimary, semantic) => {
         mutedIcon: liftToContrast(background[300], elevated, AA_NON_TEXT),
         mutedLabel: liftToContrast(background[100], elevated, 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/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,15 @@
+import { contrastRatio, mix, relativeLuminance } from "./color.js";
+import { liftToContrast } from "./outlineRung.js";
+export const RAISED_OVERLAY = 0.07;
+// Never below the card, and at least one white-overlay step above the canvas.
+export const buildSurfaceRaised = (source) => {
+    const overlay = mix(source.backgroundColor.main, source.white, RAISED_OVERLAY);
+    const card = source.background[50];
+    return relativeLuminance(overlay) > relativeLuminance(card) ? overlay : card;
+};
+export const withSurfaceRaised = (palette) => ({
+    ...palette,
+    surfaceRaised: buildSurfaceRaised(palette),
+});
+// A divider inside an overlay, at the weight `boxborder[200]` has on a card.
+export const raisedRule = (colors) => liftToContrast(colors.boxborder[200], colors.surfaceRaised, contrastRatio(colors.boxborder[200], colors.background[50]));

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

@@ -1,12 +1,13 @@
 import { contrastRatio } from "./color.js";
-import { liftToContrast, softenToContrast, 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";
-/** Clear of the 4.5 gate, but well under body text so a hint never reads as a value. */
-export const PLACEHOLDER_TEXT = 5;
+// 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. */
@@ -15,7 +16,8 @@ export const hardestSurface = (ink, surfaces) => surfaces.reduce((worst, s) => c
 export function withSurfaceRungs(palette) {
     const surfaces = namedSurfaces(palette);
     const lift = (ink, target) => liftToContrast(ink, hardestSurface(ink, surfaces), target);
-    const soften = (ink, target) => softenToContrast(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;
@@ -27,12 +29,14 @@ export function withSurfaceRungs(palette) {
         semanticText,
         text: { ...palette.text, 500: lift(palette.text[500], AA_NORMAL_TEXT) },
         header: { ...palette.header, 500: lift(palette.header[500], AA_NORMAL_TEXT) },
-        // Placeholder must stay legible without reading as a filled value: the ramp delivered
-        // 6.85:1, level with `textMuted`, so it is settled back down to just clear of AA.
-        placeholder: {
-            ...palette.placeholder,
-            500: soften(lift(palette.placeholder[500], AA_NORMAL_TEXT), PLACEHOLDER_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),
         },
-        boxborder: { ...palette.boxborder, 500: lift(palette.boxborder[500], AA_NON_TEXT) },
+        // 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,47 @@
+import { isDarkCanvas } from "./accentText.js";
+import { compositeOver } from "./color.js";
+import { liftToContrast } from "./outlineRung.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")}`;
+/** 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) => {
+    const dark = isDarkCanvas(surface);
+    const hue = scale[500];
+    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),
+    };
+};

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";

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

@@ -0,0 +1,10 @@
+/** One height scale for fields, selects and buttons, so controls side by side line up. */
+export const CONTROL_SIZES = {
+    xs: { height: "1.75rem", fontSize: "0.75rem", paddingX: "0.5rem", iconSize: 12 },
+    sm: { height: "2.1875rem", fontSize: "0.8125rem", paddingX: "0.75rem", iconSize: 14 },
+    md: { height: "2.5rem", fontSize: "0.875rem", paddingX: "1rem", iconSize: 16 },
+    lg: { height: "3rem", fontSize: "1rem", paddingX: "1.5rem", iconSize: 18 },
+};
+export const CONTROL_SIZE_NAMES = ["xs", "sm", "md", "lg"];
+export const DEFAULT_CONTROL_SIZE = "sm";
+export const isControlSize = (value) => typeof value === "string" && CONTROL_SIZE_NAMES.includes(value);