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

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

@@ -1,25 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AA_NON_TEXT = exports.MIN_PERCEPTIBLE_STEP = void 0;
+exports.STACKED_STATE_STEP = exports.CHROME_RULE = exports.CHROME_BORDER = exports.AA_NON_TEXT = exports.MIN_PERCEPTIBLE_STEP = void 0;
+exports.ruleInk = ruleInk;
+exports.tintStep = tintStep;
 exports.liftToContrast = liftToContrast;
 exports.softenToContrast = softenToContrast;
 exports.withOutlineRung = withOutlineRung;
 exports.resolveHoverTint = resolveHoverTint;
+exports.settleAcross = settleAcross;
+exports.neutralStep = neutralStep;
 const color_1 = require("./color");
-/**
- * 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.
- */
 exports.MIN_PERCEPTIBLE_STEP = 1.15;
-/** WCAG 1.4.11 — a control outline is a UI component boundary, held to 3:1. */
 exports.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.
+exports.CHROME_BORDER = 1.5;
+exports.CHROME_RULE = 1.31;
+function ruleInk(hex, surfaces, target) {
+    const loudest = surfaces.reduce((worst, s) => (0, color_1.contrastRatio)(hex, s) > (0, color_1.contrastRatio)(hex, worst) ? s : worst);
+    return (0, color_1.contrastRatio)(hex, loudest) > target
+        ? softenToContrast(hex, loudest, target)
+        : hex;
+}
+exports.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.
+function tintStep(seed, backdrop, target) {
+    const { s } = (0, color_1.hexToHsl)(seed);
+    const away = (0, color_1.relativeLuminance)(backdrop) < 0.5 ? 1 : -1;
+    for (let l = (0, color_1.hexToHsl)(backdrop).l; l >= 0 && l <= 100; l += away) {
+        const next = (0, color_1.withLightness)(seed, l, s);
+        if ((0, color_1.contrastRatio)(next, backdrop) >= target)
+            return next;
+    }
+    return (0, color_1.withLightness)(seed, away > 0 ? 100 : 0, s);
+}
 function liftToContrast(hex, backdrop, target = exports.AA_NON_TEXT) {
     if ((0, color_1.contrastRatio)(hex, backdrop) >= target)
         return hex;
@@ -37,10 +50,6 @@ function liftToContrast(hex, backdrop, target = exports.AA_NON_TEXT) {
     const ends = [(0, color_1.withLightness)(hex, 100, s), (0, color_1.withLightness)(hex, 0, s)];
     return (0, color_1.contrastRatio)(ends[0], backdrop) >= (0, color_1.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.
- */
 function softenToContrast(hex, backdrop, target) {
     if ((0, color_1.contrastRatio)(hex, backdrop) <= target)
         return hex;
@@ -55,36 +64,51 @@ 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.
 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 = (0, color_1.contrastRatio)(current, palette.backgroundColor.main) <=
         (0, color_1.contrastRatio)(current, palette.background[50])
         ? palette.backgroundColor.main
         : palette.background[50];
-    const resolved = liftToContrast(current, backdrop);
+    const resolved = (0, color_1.contrastRatio)(current, backdrop) > exports.CHROME_BORDER
+        ? softenToContrast(current, backdrop, exports.CHROME_BORDER)
+        : liftToContrast(current, backdrop, exports.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.
- */
 function resolveHoverTint(seed, restSurface) {
     return liftToContrast(seed, restSurface, exports.MIN_PERCEPTIBLE_STEP);
 }
+// NOTE: settles against every surface at once — a single "hardest" surface can drop under target on another.
+function settleAcross(hex, surfaces, target) {
+    const clearsAll = (c) => surfaces.every((s) => (0, color_1.contrastRatio)(c, s) >= target);
+    if (!clearsAll(hex)) {
+        return surfaces.reduce((ink, s) => liftToContrast(ink, s, target), hex);
+    }
+    const { s: sat, l: start } = (0, color_1.hexToHsl)(hex);
+    const toward = (0, color_1.relativeLuminance)(surfaces[0]) < 0.5 ? -1 : 1;
+    let settled = hex;
+    for (let l = start; l > 0 && l < 100; l += toward) {
+        const next = (0, color_1.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.
+function neutralStep(backdrop, target) {
+    const grey = (l) => (0, color_1.withLightness)("#808080", l, 0);
+    let lo = (0, color_1.hexToHsl)(backdrop).l;
+    let hi = (0, color_1.relativeLuminance)(backdrop) < 0.5 ? 100 : 0;
+    for (let i = 0; i < 20; i += 1) {
+        const mid = (lo + hi) / 2;
+        if ((0, color_1.contrastRatio)(grey(mid), backdrop) < target)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return grey(hi);
+}

package/dist/Theme/tokens/builders/placeholderInk.d.ts

@@ -0,0 +1,7 @@
+import type { PaletteProps } from "../types";
+/** A field always renders on at least one surface — the first is the reference backdrop. */
+export type FieldSurfaces = readonly [string, ...string[]];
+export declare const placeholderInkOn: (palette: PaletteProps, surfaces: FieldSurfaces) => string;
+export declare const fieldSurfaces: (palette: PaletteProps) => FieldSurfaces;
+/** The hint ink every field in this library reads. Takes no backdrop: see `fieldSurfaces`. */
+export declare const placeholderInk: (palette: PaletteProps) => string;

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.placeholderInk = exports.fieldSurfaces = exports.placeholderInkOn = void 0;
+const color_1 = require("./color");
+const outlineRung_1 = require("./outlineRung");
+const surfaceRungs_1 = require("./surfaceRungs");
+// NOTE: settled (not floored) onto PLACEHOLDER_TEXT — one hint weight across brands, not a per-brand accident.
+const placeholderInkOn = (palette, surfaces) => {
+    const rung = palette.placeholder[500];
+    const hardest = surfaces.reduce((worst, s) => (0, color_1.contrastRatio)(rung, s) < (0, color_1.contrastRatio)(rung, worst) ? s : worst);
+    return (0, color_1.contrastRatio)(rung, hardest) > surfaceRungs_1.PLACEHOLDER_TEXT
+        ? (0, outlineRung_1.softenToContrast)(rung, hardest, surfaceRungs_1.PLACEHOLDER_TEXT)
+        : (0, outlineRung_1.liftToContrast)(rung, hardest, surfaceRungs_1.PLACEHOLDER_TEXT);
+};
+exports.placeholderInkOn = placeholderInkOn;
+// NOTE: enabled fields only — 1.4.3 exempts disabled ones, and folding their dimmer fill in would darken every other field's hint.
+const fieldSurfaces = (palette) => [
+    palette.gray[50],
+    palette.background[50],
+    palette.backgroundColor.main,
+];
+exports.fieldSurfaces = fieldSurfaces;
+/** The hint ink every field in this library reads. Takes no backdrop: see `fieldSurfaces`. */
+const placeholderInk = (palette) => (0, exports.placeholderInkOn)(palette, (0, exports.fieldSurfaces)(palette));
+exports.placeholderInk = placeholderInk;

package/dist/Theme/tokens/builders/resolvedRungs.d.ts

@@ -1,6 +1,5 @@
 import { AA_NON_TEXT } from "./outlineRung";
 import type { PaletteProps } from "../types";
-/** Placeholder text measured 4.32:1 on a card for 8 of 9 brands — text, so held to 4.5:1. */
 export declare function withPlaceholderRung(palette: PaletteProps): PaletteProps;
 /** The hover row is a SURFACE, so it steps away from the ink rather than the ink moving. */
 export declare function withTableHoverRung(palette: PaletteProps): PaletteProps;

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

@@ -6,9 +6,10 @@ exports.withTableHoverRung = withTableHoverRung;
 const outlineRung_1 = require("./outlineRung");
 Object.defineProperty(exports, "AA_NON_TEXT", { enumerable: true, get: function () { return outlineRung_1.AA_NON_TEXT; } });
 const accentText_1 = require("./accentText");
-/** Placeholder text measured 4.32:1 on a card for 8 of 9 brands — text, so held to 4.5:1. */
+const surfaceRungs_1 = require("./surfaceRungs");
+// 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.
 function withPlaceholderRung(palette) {
-    const resolved = (0, outlineRung_1.liftToContrast)(palette.placeholder[500], palette.background[50], accentText_1.AA_NORMAL_TEXT);
+    const resolved = (0, outlineRung_1.liftToContrast)(palette.placeholder[500], palette.background[50], surfaceRungs_1.PLACEHOLDER_TEXT);
     if (resolved === palette.placeholder[500])
         return palette;
     return { ...palette, placeholder: { ...palette.placeholder, 500: resolved } };

package/dist/Theme/tokens/builders/rowStates.d.ts

@@ -0,0 +1,7 @@
+import type { PaletteProps } from "../types";
+export interface RowStateBackgrounds {
+    active: string;
+    selected: string;
+    selectedActive: string;
+}
+export declare const listRowBackgrounds: (colors: PaletteProps) => RowStateBackgrounds;

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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listRowBackgrounds = void 0;
+const outlineRung_1 = require("./outlineRung");
+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 = (0, outlineRung_1.tintStep)(colors.backgroundColor.tertiary, colors.surfaceRaised, outlineRung_1.MIN_PERCEPTIBLE_STEP);
+    return {
+        active: (0, outlineRung_1.resolveHoverTint)(colors.gray[50], colors.surfaceRaised),
+        selected,
+        selectedActive: (0, outlineRung_1.tintStep)(selected, selected, outlineRung_1.STACKED_STATE_STEP),
+    };
+};
+exports.listRowBackgrounds = listRowBackgrounds;

package/dist/Theme/tokens/builders/scrim.d.ts

@@ -0,0 +1,6 @@
+import type { PaletteProps } from "../types";
+export declare const SCRIM_OPACITY = 0.6;
+export declare const BACKDROP_SCRIM_OPACITY = 0.5;
+/** Modal/Drawer backdrop: `black` never remaps between modes, so one alpha works in both. */
+export declare const overlayScrim: (colors: Pick<PaletteProps, "black">) => string;
+export declare const backdropScrim: (colors: Pick<PaletteProps, "black">) => string;

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backdropScrim = exports.overlayScrim = exports.BACKDROP_SCRIM_OPACITY = exports.SCRIM_OPACITY = void 0;
+const color_1 = require("./color");
+exports.SCRIM_OPACITY = 0.6;
+exports.BACKDROP_SCRIM_OPACITY = 0.5;
+/** Modal/Drawer backdrop: `black` never remaps between modes, so one alpha works in both. */
+const overlayScrim = (colors) => {
+    const { r, g, b } = (0, color_1.hexToRgb)(colors.black);
+    return `rgba(${r}, ${g}, ${b}, ${exports.SCRIM_OPACITY})`;
+};
+exports.overlayScrim = overlayScrim;
+const backdropScrim = (colors) => {
+    const { r, g, b } = (0, color_1.hexToRgb)(colors.black);
+    return `rgba(${r}, ${g}, ${b}, ${exports.BACKDROP_SCRIM_OPACITY})`;
+};
+exports.backdropScrim = backdropScrim;

package/dist/Theme/tokens/builders/scrollShadow.d.ts

@@ -0,0 +1,2 @@
+export type ScrollShadowStyle = Record<string, unknown>;
+export declare function scrollShadowStyles(surface: string): ScrollShadowStyle;

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

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scrollShadowStyles = scrollShadowStyles;
+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.
+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/Theme/tokens/builders/scrollbar.d.ts

@@ -3,10 +3,6 @@ export type ScrollbarStyle = Record<string, unknown>;
 /** One width everywhere. The 3px, 4px, 5px and 10px bars in use were all accidents. */
 export declare const SCROLLBAR_WIDTH = "6px";
 export type ScrollbarVariant = "default" | "overlay" | "hover";
-/**
- * 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.
- */
 export declare function scrollbarStyles(palette: PaletteProps, variant?: ScrollbarVariant): ScrollbarStyle;
 /** The same chrome for the document itself, where `&` selectors do not apply. */
 export declare function globalScrollbarStyles(palette: PaletteProps): ScrollbarStyle;

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

@@ -6,10 +6,7 @@ exports.globalScrollbarStyles = globalScrollbarStyles;
 /** One width everywhere. The 3px, 4px, 5px and 10px bars in use were all accidents. */
 exports.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.
 function scrollbarStyles(palette, variant = "default") {
     const { gray } = palette;
     const track = variant === "default" ? gray[100] : "transparent";

package/dist/Theme/tokens/builders/semanticText.d.ts

@@ -1,10 +1,5 @@
 import type { SemanticColors, SemanticTextTokens, SemanticTone } from "../types";
 export declare const SEMANTIC_TONES: readonly SemanticTone[];
-/**
- * `semantic[tone][500]` is a FILL rung — as ink on a light canvas it measures 1.84-3.68:1 across
- * every brand. Each tone is stepped here until it clears AA as text, so a call site that wants
- * "error-coloured text" cannot pick the unreadable one.
- */
 export declare const buildSemanticText: (semantic: SemanticColors, canvas: string) => SemanticTextTokens;
 /** Ink ON the fill, not on the canvas — the pair a CSS module needs but cannot compute. */
 export declare const buildOnSemantic: (semantic: SemanticColors, white: string, black: string) => SemanticTextTokens;

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

@@ -4,11 +4,7 @@ exports.buildOnSemantic = exports.buildSemanticText = exports.SEMANTIC_TONES = v
 const outlineRung_1 = require("./outlineRung");
 const accentText_1 = require("./accentText");
 exports.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.
 const buildSemanticText = (semantic, canvas) => exports.SEMANTIC_TONES.reduce((acc, tone) => {
     acc[tone] = (0, outlineRung_1.liftToContrast)(semantic[tone][500], canvas, accentText_1.AA_NORMAL_TEXT);
     return acc;

package/dist/Theme/tokens/builders/sidebarAccent.d.ts

@@ -4,6 +4,14 @@ export declare const AA_NORMAL_TEXT = 4.5;
 /** Lightest surface an active row reaches: Chakra `whiteAlpha.400` (0.24) on hover. */
 export declare const ACTIVE_SURFACE_TINT = "#ffffff3d";
 export declare const sidebarActiveSurface: (background: ColorScale) => string;
+/** Lightest a row ever gets on ANY rail surface — what chrome inside a row must clear. */
+export declare const sidebarRowPeak: (surface: string) => string;
+/** Stronger than the divider — a hover fill must read as an action, not a rule. */
+export declare const HOVER_SURFACE_TINT = "#ffffff20";
+/** Chakra whiteAlpha.100 (0.06) — a divider only needs to read, not shout. */
+export declare const DIVIDER_SURFACE_TINT = "#ffffff0f";
+export declare const sidebarHoverSurface: (background: ColorScale) => string;
+export declare const sidebarDivider: (background: ColorScale) => string;
 /** The rail never inverts, so both modes take the accent from the LIGHT primary. */
 export declare const buildSidebarTokens: (background: ColorScale, lightPrimary: ColorScale, semantic: SemanticColors) => SidebarTokens;
 export declare const withSidebarTokens: (source: BrandPaletteSource) => SidebarTokens;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withSidebarTokens = exports.buildSidebarTokens = exports.sidebarActiveSurface = exports.ACTIVE_SURFACE_TINT = exports.AA_NORMAL_TEXT = void 0;
+exports.withSidebarTokens = exports.buildSidebarTokens = exports.sidebarDivider = exports.sidebarHoverSurface = exports.DIVIDER_SURFACE_TINT = exports.HOVER_SURFACE_TINT = exports.sidebarRowPeak = exports.sidebarActiveSurface = exports.ACTIVE_SURFACE_TINT = exports.AA_NORMAL_TEXT = void 0;
 const color_1 = require("./color");
 const outlineRung_1 = require("./outlineRung");
 const semanticText_1 = require("./semanticText");
@@ -10,6 +10,17 @@ exports.AA_NORMAL_TEXT = 4.5;
 exports.ACTIVE_SURFACE_TINT = "#ffffff3d";
 const sidebarActiveSurface = (background) => (0, color_1.compositeOver)(exports.ACTIVE_SURFACE_TINT, background[500]);
 exports.sidebarActiveSurface = sidebarActiveSurface;
+/** Lightest a row ever gets on ANY rail surface — what chrome inside a row must clear. */
+const sidebarRowPeak = (surface) => (0, color_1.compositeOver)(exports.ACTIVE_SURFACE_TINT, surface);
+exports.sidebarRowPeak = sidebarRowPeak;
+/** Stronger than the divider — a hover fill must read as an action, not a rule. */
+exports.HOVER_SURFACE_TINT = "#ffffff20";
+/** Chakra whiteAlpha.100 (0.06) — a divider only needs to read, not shout. */
+exports.DIVIDER_SURFACE_TINT = "#ffffff0f";
+const sidebarHoverSurface = (background) => (0, outlineRung_1.resolveHoverTint)((0, color_1.compositeOver)(exports.HOVER_SURFACE_TINT, background[500]), background[500]);
+exports.sidebarHoverSurface = sidebarHoverSurface;
+const sidebarDivider = (background) => (0, outlineRung_1.resolveHoverTint)((0, color_1.compositeOver)(exports.DIVIDER_SURFACE_TINT, background[500]), background[500]);
+exports.sidebarDivider = sidebarDivider;
 /** The rail never inverts, so both modes take the accent from the LIGHT primary. */
 const buildSidebarTokens = (background, lightPrimary, semantic) => {
     const surface = (0, exports.sidebarActiveSurface)(background);
@@ -22,6 +33,9 @@ const buildSidebarTokens = (background, lightPrimary, semantic) => {
         mutedIcon: (0, outlineRung_1.liftToContrast)(background[300], elevated, outlineRung_1.AA_NON_TEXT),
         mutedLabel: (0, outlineRung_1.liftToContrast)(background[100], elevated, exports.AA_NORMAL_TEXT),
         semanticText: (0, semanticText_1.buildSemanticText)(semantic, elevated),
+        hoverBg: (0, exports.sidebarHoverSurface)(background),
+        activeBg: surface,
+        divider: (0, exports.sidebarDivider)(background),
     };
 };
 exports.buildSidebarTokens = buildSidebarTokens;

package/dist/Theme/tokens/builders/statusTone.d.ts

@@ -7,28 +7,10 @@ export type StatusTone = {
     /** Chip outline, guaranteed >= 3:1 on `bg`. */
     border: string;
 };
-/**
- * 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.
- */
 export declare function resolveStatusTone(scale: ColorScale, mode: ResolvedColorMode): StatusTone;
-/**
- * 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.
- */
 export declare function resolveAvatarFill(hex: string, target?: number): string;
-/**
- * Hue set for generated avatars. Values are seeds, not final fills — always pass them through
- * `resolveAvatarFill` so the white initials stay legible.
- */
 export declare const AVATAR_SEEDS: readonly ["#ef4444", "#f97316", "#eab308", "#22c55e", "#10b981", "#06b6d4", "#3b82f6", "#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 declare function avatarFillFor(seedText: string): string;
 /** True when `fg` clears the body-text bar on `bg` — exported for consumer assertions. */
 export declare const meetsBodyText: (fg: string, bg: string) => boolean;

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

@@ -7,15 +7,7 @@ exports.avatarFillFor = avatarFillFor;
 const color_1 = require("./color");
 const accentText_1 = require("./accentText");
 const outlineRung_1 = require("./outlineRung");
-/**
- * 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.
 function resolveStatusTone(scale, mode) {
     const bg = scale[100];
     const inkSeed = mode === "dark" ? scale[300] : scale[700];
@@ -26,18 +18,11 @@ function resolveStatusTone(scale, mode) {
         border: (0, outlineRung_1.liftToContrast)(edgeSeed, bg, outlineRung_1.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.
 function resolveAvatarFill(hex, target = accentText_1.AA_NORMAL_TEXT) {
     return (0, outlineRung_1.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.
 exports.AVATAR_SEEDS = [
     "#ef4444",
     "#f97316",
@@ -49,7 +34,7 @@ exports.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}`. */
 function avatarFillFor(seedText) {
     let hash = 0;
     for (let i = 0; i < seedText.length; i++) {

package/dist/Theme/tokens/builders/surfaceRaised.d.ts

@@ -0,0 +1,6 @@
+import type { PaletteProps } from "../types";
+export declare const RAISED_OVERLAY = 0.07;
+export type SurfaceRaisedSource = Pick<PaletteProps, "backgroundColor" | "background" | "white">;
+export declare const buildSurfaceRaised: (source: SurfaceRaisedSource) => string;
+export declare const withSurfaceRaised: (palette: PaletteProps) => PaletteProps;
+export declare const raisedRule: (colors: Pick<PaletteProps, "boxborder" | "background" | "surfaceRaised">) => string;

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

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.raisedRule = exports.withSurfaceRaised = exports.buildSurfaceRaised = exports.RAISED_OVERLAY = void 0;
+const color_1 = require("./color");
+const outlineRung_1 = require("./outlineRung");
+exports.RAISED_OVERLAY = 0.07;
+// Never below the card, and at least one white-overlay step above the canvas.
+const buildSurfaceRaised = (source) => {
+    const overlay = (0, color_1.mix)(source.backgroundColor.main, source.white, exports.RAISED_OVERLAY);
+    const card = source.background[50];
+    return (0, color_1.relativeLuminance)(overlay) > (0, color_1.relativeLuminance)(card) ? overlay : card;
+};
+exports.buildSurfaceRaised = buildSurfaceRaised;
+const withSurfaceRaised = (palette) => ({
+    ...palette,
+    surfaceRaised: (0, exports.buildSurfaceRaised)(palette),
+});
+exports.withSurfaceRaised = withSurfaceRaised;
+// A divider inside an overlay, at the weight `boxborder[200]` has on a card.
+const raisedRule = (colors) => (0, outlineRung_1.liftToContrast)(colors.boxborder[200], colors.surfaceRaised, (0, color_1.contrastRatio)(colors.boxborder[200], colors.background[50]));
+exports.raisedRule = raisedRule;

package/dist/Theme/tokens/builders/surfaceRungs.d.ts

@@ -1,6 +1,5 @@
 import type { PaletteProps } from "../types";
-/** Clear of the 4.5 gate, but well under body text so a hint never reads as a value. */
-export declare const PLACEHOLDER_TEXT = 5;
+export declare const PLACEHOLDER_TEXT = 3;
 export declare const namedSurfaces: (palette: PaletteProps) => string[];
 /** The surface an ink is closest to — clearing it clears every other one. */
 export declare const hardestSurface: (ink: string, surfaces: string[]) => string;

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

@@ -6,11 +6,12 @@ const color_1 = require("./color");
 const outlineRung_1 = require("./outlineRung");
 const accentText_1 = require("./accentText");
 const semanticText_1 = require("./semanticText");
-/** Clear of the 4.5 gate, but well under body text so a hint never reads as a value. */
-exports.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.
+exports.PLACEHOLDER_TEXT = outlineRung_1.AA_NON_TEXT;
 const namedSurfaces = (palette) => [
     ...Object.values(palette.backgroundColor),
     palette.background[50],
+    palette.surfaceRaised,
     palette.table.hover[500],
 ];
 exports.namedSurfaces = namedSurfaces;
@@ -21,7 +22,8 @@ exports.hardestSurface = hardestSurface;
 function withSurfaceRungs(palette) {
     const surfaces = (0, exports.namedSurfaces)(palette);
     const lift = (ink, target) => (0, outlineRung_1.liftToContrast)(ink, (0, exports.hardestSurface)(ink, surfaces), target);
-    const soften = (ink, target) => (0, outlineRung_1.softenToContrast)(ink, (0, exports.hardestSurface)(ink, surfaces), target);
+    const settle = (ink, target) => (0, outlineRung_1.settleAcross)(ink, surfaces, target);
+    const rule = (ink) => (0, outlineRung_1.ruleInk)(ink, [palette.backgroundColor.main, palette.background[50]], outlineRung_1.CHROME_RULE);
     const semanticText = semanticText_1.SEMANTIC_TONES.reduce((acc, tone) => {
         acc[tone] = lift(palette.semanticText[tone], accentText_1.AA_NORMAL_TEXT);
         return acc;
@@ -33,12 +35,14 @@ function withSurfaceRungs(palette) {
         semanticText,
         text: { ...palette.text, 500: lift(palette.text[500], accentText_1.AA_NORMAL_TEXT) },
         header: { ...palette.header, 500: lift(palette.header[500], accentText_1.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], accentText_1.AA_NORMAL_TEXT), exports.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], outlineRung_1.CHROME_BORDER),
         },
-        boxborder: { ...palette.boxborder, 500: lift(palette.boxborder[500], outlineRung_1.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/Theme/tokens/builders/tone.d.ts

@@ -0,0 +1,22 @@
+import type { ColorScale, PaletteProps, SemanticTone } from "../types";
+export type Tone = "neutral" | "info" | "success" | "warning" | "error";
+export type ToneColorScheme = "gray" | "blue" | "green" | "orange" | "red";
+export declare const TONES: readonly Tone[];
+export declare const toneToColorScheme: Readonly<Record<Tone, ToneColorScheme>>;
+export declare const toneToSemantic: Readonly<Record<Exclude<Tone, "neutral">, SemanticTone>>;
+export declare const isTone: (value: unknown) => value is Tone;
+export declare const toneScale: (colors: PaletteProps, tone: Tone) => ColorScale;
+/** Status ink on the canvas: `semanticText.<tone>`, or `textMuted` for neutral. */
+export declare const toneInk: (colors: PaletteProps, tone: Tone) => string;
+/** A soft fill + its hover/active steps, all translucent so they read correctly on any surface. */
+export type SoftTone = {
+    bg: string;
+    fg: string;
+    border: string;
+    hoverBg: string;
+    hoverBorder: string;
+    activeBg: string;
+    activeBorder: string;
+};
+/** Translucent tint of the scale's own `[500]` hue — one rung for every scheme, any surface. */
+export declare const resolveSoftTone: (colors: PaletteProps, scale: ColorScale, surface?: string) => SoftTone;

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSoftTone = exports.toneInk = exports.toneScale = exports.isTone = exports.toneToSemantic = exports.toneToColorScheme = exports.TONES = void 0;
+const accentText_1 = require("./accentText");
+const color_1 = require("./color");
+const outlineRung_1 = require("./outlineRung");
+exports.TONES = ["neutral", "info", "success", "warning", "error"];
+exports.toneToColorScheme = {
+    neutral: "gray",
+    info: "blue",
+    success: "green",
+    warning: "orange",
+    error: "red",
+};
+exports.toneToSemantic = {
+    info: "info",
+    success: "success",
+    warning: "warning",
+    error: "error",
+};
+const isTone = (value) => typeof value === "string" && exports.TONES.includes(value);
+exports.isTone = isTone;
+const toneScale = (colors, tone) => colors[exports.toneToColorScheme[tone]];
+exports.toneScale = toneScale;
+/** Status ink on the canvas: `semanticText.<tone>`, or `textMuted` for neutral. */
+const toneInk = (colors, tone) => tone === "neutral" ? colors.textMuted : colors.semanticText[exports.toneToSemantic[tone]];
+exports.toneInk = toneInk;
+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. */
+const resolveSoftTone = (colors, scale, surface = colors.backgroundColor.main) => {
+    const dark = (0, accentText_1.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 = (0, outlineRung_1.liftToContrast)(hue, (0, color_1.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),
+    };
+};
+exports.resolveSoftTone = resolveSoftTone;

package/dist/Theme/tokens/builders/tooltipSurface.d.ts

@@ -0,0 +1,6 @@
+import type { PaletteProps } from "../types";
+/** The one tooltip chip: the rail surface stays dark in both modes, so it floats over either canvas. */
+export declare const tooltipSurface: (colors: PaletteProps) => {
+    bg: string;
+    fg: string;
+};

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

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tooltipSurface = void 0;
+const accentText_1 = require("./accentText");
+/** The one tooltip chip: the rail surface stays dark in both modes, so it floats over either canvas. */
+const tooltipSurface = (colors) => {
+    const bg = colors.sidebar.background[500];
+    return { bg, fg: (0, accentText_1.onFilled)(bg, colors.white, colors.black) };
+};
+exports.tooltipSurface = tooltipSurface;