pixelize-design-library 2.4.2-beta.4 → 2.4.2-beta.40

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

@@ -0,0 +1,52 @@
+import type { FocusRingTokens, PaletteProps } from "../types";
+/**
+ * The nearest re-lighting of `hex` that clears `target` against EVERY backdrop at once.
+ *
+ * Not `settleAcross`: that folds one `liftToContrast` per surface, and each lift walks AWAY from
+ * the surface it was handed. That is correct when every backdrop sits on the same side of the ink
+ * (its case — a set of light surfaces, or a set of dark ones), and wrong here, where a focus ring
+ * is squeezed BETWEEN a near-white canvas and a mid-dark button fill: the lift against the fill
+ * walks straight back across the canvas it had just cleared. Seeding `settleAcross` with
+ * `primary[500]` measured 1.08-1.99 on the light canvas for every brand for exactly that reason.
+ *
+ * Walking outward from the seed and testing every backdrop at each step keeps the result the
+ * CLOSEST passing colour to the brand accent, so the ring still reads as brand chrome. Contrast is
+ * a function of relative luminance alone, and lightness sweeps luminance monotonically from 0 to 1,
+ * so if any colour on this hue clears the set, this finds it.
+ */
+export declare function settleBetween(hex: string, backdrops: readonly string[], target?: number): string;
+/** Everything the ring is derived from. A `PaletteProps` satisfies it; so does a brand source. */
+export type FocusRingSource = Pick<PaletteProps, "primary" | "background" | "backgroundColor">;
+/**
+ * The three backdrops a focused button's ring is actually drawn against: the page canvas, a card
+ * surface, and — because a solid button's ring sits directly against its own fill — `primary[500]`.
+ *
+ * Deliberately NOT every named surface. `muted`/`accent`/`quaternary` are mid-tone, and a single
+ * band asked to clear those AND a dark brand fill has no solution at any hue — contrast is
+ * luminance alone, and `skyline`/`storefront` come out with an empty band. That is what the second
+ * tone is for: `halo` owns the fill-side adjacency instead.
+ */
+export declare const focusRingBackdrops: (source: FocusRingSource) => string[];
+/**
+ * The two-tone `:focus-visible` indicator.
+ *
+ * Chakra's stock ring (`shadows.outline`, a fixed `rgba(66,153,225,.6)`) measured 1.83:1 on the
+ * lavender canvas and 1.38:1 on a primary button — a focus indicator you cannot see, on all nine
+ * brands. It is one hardcoded blue, so no palette could have saved it.
+ *
+ * `halo` is the surface tone, drawn as the inner band so the indicator separates from a filled
+ * control whatever `colorScheme` painted it. `ring` is the brand accent, walked to the nearest
+ * lightness that clears 3:1 on all three backdrops at once — including the halo, so the two tones
+ * are always told apart.
+ */
+export declare const buildFocusRing: (source: FocusRingSource) => FocusRingTokens;
+/**
+ * Re-derives the ring from the FINISHED palette, as the last step of the rung chain.
+ *
+ * `finalizeLightPalette` and `buildDarkPalette` seed it, but neither is the final word: a brand
+ * file may replace `primary` or `background` after the generic derivation runs — `zinc`'s dark
+ * palette replaces both, inverting the filled button to near-white — and a ring resolved against
+ * the pre-override values is then silently wrong. Same reason `withSurfaceRungs` re-lifts inks the
+ * finalizers already derived. `focusRing.test.ts` asserts this is a fixed point.
+ */
+export declare const withFocusRing: (palette: PaletteProps) => PaletteProps;

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

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFocusRing = exports.buildFocusRing = exports.focusRingBackdrops = void 0;
+exports.settleBetween = settleBetween;
+const color_1 = require("./color");
+const outlineRung_1 = require("./outlineRung");
+/** Same lightness granularity `buildDarkPalette` walks its accents at. */
+const LIGHTNESS_STEP = 0.5;
+/**
+ * The nearest re-lighting of `hex` that clears `target` against EVERY backdrop at once.
+ *
+ * Not `settleAcross`: that folds one `liftToContrast` per surface, and each lift walks AWAY from
+ * the surface it was handed. That is correct when every backdrop sits on the same side of the ink
+ * (its case — a set of light surfaces, or a set of dark ones), and wrong here, where a focus ring
+ * is squeezed BETWEEN a near-white canvas and a mid-dark button fill: the lift against the fill
+ * walks straight back across the canvas it had just cleared. Seeding `settleAcross` with
+ * `primary[500]` measured 1.08-1.99 on the light canvas for every brand for exactly that reason.
+ *
+ * Walking outward from the seed and testing every backdrop at each step keeps the result the
+ * CLOSEST passing colour to the brand accent, so the ring still reads as brand chrome. Contrast is
+ * a function of relative luminance alone, and lightness sweeps luminance monotonically from 0 to 1,
+ * so if any colour on this hue clears the set, this finds it.
+ */
+function settleBetween(hex, backdrops, target = outlineRung_1.AA_NON_TEXT) {
+    const clears = (candidate) => backdrops.every((backdrop) => (0, color_1.contrastRatio)(candidate, backdrop) >= target);
+    if (clears(hex))
+        return hex;
+    const { l } = (0, color_1.hexToHsl)(hex);
+    for (let step = LIGHTNESS_STEP; step <= 100; step += LIGHTNESS_STEP) {
+        const darker = (0, color_1.withLightness)(hex, l - step);
+        if (clears(darker))
+            return darker;
+        const lighter = (0, color_1.withLightness)(hex, l + step);
+        if (clears(lighter))
+            return lighter;
+    }
+    // Unreachable for every shipped brand (the gate proves it) — a brand whose fill and canvas are
+    // close enough to leave no gap would land here. Take the end that is least bad rather than throw
+    // at import time, and let `focusRing.test.ts` be what reports it.
+    const ends = [(0, color_1.withLightness)(hex, 0), (0, color_1.withLightness)(hex, 100)];
+    const worst = (candidate) => Math.min(...backdrops.map((backdrop) => (0, color_1.contrastRatio)(candidate, backdrop)));
+    return worst(ends[0]) >= worst(ends[1]) ? ends[0] : ends[1];
+}
+/**
+ * The three backdrops a focused button's ring is actually drawn against: the page canvas, a card
+ * surface, and — because a solid button's ring sits directly against its own fill — `primary[500]`.
+ *
+ * Deliberately NOT every named surface. `muted`/`accent`/`quaternary` are mid-tone, and a single
+ * band asked to clear those AND a dark brand fill has no solution at any hue — contrast is
+ * luminance alone, and `skyline`/`storefront` come out with an empty band. That is what the second
+ * tone is for: `halo` owns the fill-side adjacency instead.
+ */
+const focusRingBackdrops = (source) => [
+    source.backgroundColor.main,
+    source.background[50],
+    source.primary[500],
+];
+exports.focusRingBackdrops = focusRingBackdrops;
+/**
+ * The two-tone `:focus-visible` indicator.
+ *
+ * Chakra's stock ring (`shadows.outline`, a fixed `rgba(66,153,225,.6)`) measured 1.83:1 on the
+ * lavender canvas and 1.38:1 on a primary button — a focus indicator you cannot see, on all nine
+ * brands. It is one hardcoded blue, so no palette could have saved it.
+ *
+ * `halo` is the surface tone, drawn as the inner band so the indicator separates from a filled
+ * control whatever `colorScheme` painted it. `ring` is the brand accent, walked to the nearest
+ * lightness that clears 3:1 on all three backdrops at once — including the halo, so the two tones
+ * are always told apart.
+ */
+const buildFocusRing = (source) => {
+    const halo = settleBetween(source.background[50], [source.primary[500]]);
+    return {
+        halo,
+        ring: settleBetween(source.primary[500], [...(0, exports.focusRingBackdrops)(source), halo]),
+    };
+};
+exports.buildFocusRing = buildFocusRing;
+/**
+ * Re-derives the ring from the FINISHED palette, as the last step of the rung chain.
+ *
+ * `finalizeLightPalette` and `buildDarkPalette` seed it, but neither is the final word: a brand
+ * file may replace `primary` or `background` after the generic derivation runs — `zinc`'s dark
+ * palette replaces both, inverting the filled button to near-white — and a ring resolved against
+ * the pre-override values is then silently wrong. Same reason `withSurfaceRungs` re-lifts inks the
+ * finalizers already derived. `focusRing.test.ts` asserts this is a fixed point.
+ */
+const withFocusRing = (palette) => ({
+    ...palette,
+    focusRing: (0, exports.buildFocusRing)(palette),
+});
+exports.withFocusRing = withFocusRing;

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

@@ -3,5 +3,7 @@ export * from "./buildBrandTokens";
 export * from "./buildDarkPalette";
 export * from "./chartColorsFromTheme";
 export * from "./color";
+export * from "./focusRing";
 export * from "./scrollbar";
 export * from "./gradientInk";
+export * from "./placeholderInk";

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

@@ -19,5 +19,7 @@ __exportStar(require("./buildBrandTokens"), exports);
 __exportStar(require("./buildDarkPalette"), exports);
 __exportStar(require("./chartColorsFromTheme"), exports);
 __exportStar(require("./color"), exports);
+__exportStar(require("./focusRing"), exports);
 __exportStar(require("./scrollbar"), exports);
 __exportStar(require("./gradientInk"), exports);
+__exportStar(require("./placeholderInk"), exports);

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

@@ -7,6 +7,28 @@ import type { PaletteProps } from "../types";
 export declare const MIN_PERCEPTIBLE_STEP = 1.15;
 /** WCAG 1.4.11 — a control outline is a UI component boundary, held to 3:1. */
 export declare const AA_NON_TEXT = 3;
+/**
+ * Resting chrome — card, popover and field outlines — settles here, not at `AA_NON_TEXT`.
+ * At 3:1 a container border is text-weight and the UI reads as a wireframe; every mainstream
+ * system draws this line far lighter (Tailwind gray-200 1.24, Chakra gray.200 1.30, Material
+ * outline-variant 1.61). 1.4.11 asks that a control be identifiable, not that its resting
+ * border carry the whole job: the fill, the label and the focus ring do that.
+ *
+ * That defence was untrue when it was written. Buttons defined no `_focusVisible` at all, so the
+ * focus ring was Chakra's stock `shadows.outline` — a fixed blue measuring 1.38:1 on a primary
+ * button — and nothing in the library was held to `AA_NON_TEXT` at the moment of focus. It is
+ * true now: `focusRing` (`builders/focusRing.ts`) is derived per brand per mode and gated at 3:1
+ * on the canvas, on a card and on the button's own fill by `builders/focusRing.test.ts`. If that
+ * gate is ever relaxed, this constant loses its justification with it.
+ */
+export declare const CHROME_BORDER = 1.5;
+export declare const CHROME_RULE = 1.31;
+/**
+ * A rule is decorative, so it has a ceiling and no floor: soften it until the surface it reads
+ * hardest against sits at `target`, and leave a already-fainter rung alone. Never `settleAcross`
+ * here — that clears a floor on EVERY surface, so one tinted surface drags the rule darker.
+ */
+export declare function ruleInk(hex: string, surfaces: readonly string[], target: number): string;
 /**
  * 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
@@ -21,9 +43,10 @@ export declare function liftToContrast(hex: string, backdrop: string, target?: n
 export declare function softenToContrast(hex: string, backdrop: string, target: number): string;
 /**
  * `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.
+ * pickers, the editor's inputs). Settled onto `CHROME_BORDER` — lifted when a brand authored it
+ * invisibly pale, softened when it overshoots. It was previously lifted to `AA_NON_TEXT`, which
+ * shipped 3.85-4.95:1 outlines: a text-weight box around every card and popover.
+ * Resolved here rather than hand-pinned per brand: a copied hex goes stale the moment a canvas moves.
  *
  * `border[*]` is deliberately untouched — that ramp draws table gridlines, which are decorative
  * and outside 1.4.11.
@@ -38,3 +61,18 @@ export declare function withOutlineRung(palette: PaletteProps): PaletteProps;
  * its OWN list background, not necessarily the page canvas.
  */
 export declare function resolveHoverTint(seed: string, restSurface: string): string;
+/**
+ * Settles ink into `target` against EVERY surface at once. Softening one step can change which
+ * surface is hardest, so resolving against a single pre-computed "hardest" one lands under the
+ * floor on another — that is how radiant and rosewood ended up with an invisible outline on
+ * their muted surface.
+ */
+export declare function settleAcross(hex: string, surfaces: readonly string[], target: number): string;
+/**
+ * A pure-grey surface sitting `target` contrast away from `backdrop`. Binary search, not a walk:
+ * `liftToContrast` cannot move a seed already at lightness 0 or 100, and a pure-white panel seeded
+ * itself straight to black. Neutral on purpose — the light palettes are hand-authored and tinted,
+ * so lifting one of their surface rungs turns a selected row into a saturated brand block, while
+ * the derived dark palettes land on grey and look right.
+ */
+export declare function neutralStep(backdrop: string, target: number): string;

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

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AA_NON_TEXT = exports.MIN_PERCEPTIBLE_STEP = void 0;
+exports.CHROME_RULE = exports.CHROME_BORDER = exports.AA_NON_TEXT = exports.MIN_PERCEPTIBLE_STEP = void 0;
+exports.ruleInk = ruleInk;
 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
@@ -14,6 +17,35 @@ const color_1 = require("./color");
 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;
+/**
+ * Resting chrome — card, popover and field outlines — settles here, not at `AA_NON_TEXT`.
+ * At 3:1 a container border is text-weight and the UI reads as a wireframe; every mainstream
+ * system draws this line far lighter (Tailwind gray-200 1.24, Chakra gray.200 1.30, Material
+ * outline-variant 1.61). 1.4.11 asks that a control be identifiable, not that its resting
+ * border carry the whole job: the fill, the label and the focus ring do that.
+ *
+ * That defence was untrue when it was written. Buttons defined no `_focusVisible` at all, so the
+ * focus ring was Chakra's stock `shadows.outline` — a fixed blue measuring 1.38:1 on a primary
+ * button — and nothing in the library was held to `AA_NON_TEXT` at the moment of focus. It is
+ * true now: `focusRing` (`builders/focusRing.ts`) is derived per brand per mode and gated at 3:1
+ * on the canvas, on a card and on the button's own fill by `builders/focusRing.test.ts`. If that
+ * gate is ever relaxed, this constant loses its justification with it.
+ */
+exports.CHROME_BORDER = 1.5;
+// The resting rule between two surfaces — a card edge, a divider, a menu outline. Lighter than
+// CHROME_BORDER, which outlines a control the user acts on.
+exports.CHROME_RULE = 1.31;
+/**
+ * A rule is decorative, so it has a ceiling and no floor: soften it until the surface it reads
+ * hardest against sits at `target`, and leave a already-fainter rung alone. Never `settleAcross`
+ * here — that clears a floor on EVERY surface, so one tinted surface drags the rule darker.
+ */
+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;
+}
 /**
  * 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
@@ -57,9 +89,10 @@ function softenToContrast(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.
+ * pickers, the editor's inputs). Settled onto `CHROME_BORDER` — lifted when a brand authored it
+ * invisibly pale, softened when it overshoots. It was previously lifted to `AA_NON_TEXT`, which
+ * shipped 3.85-4.95:1 outlines: a text-weight box around every card and popover.
+ * Resolved here rather than hand-pinned per brand: a copied hex goes stale the moment a canvas moves.
  *
  * `border[*]` is deliberately untouched — that ramp draws table gridlines, which are decorative
  * and outside 1.4.11.
@@ -72,7 +105,9 @@ function withOutlineRung(palette) {
         (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 } };
@@ -88,3 +123,45 @@ function withOutlineRung(palette) {
 function resolveHoverTint(seed, restSurface) {
     return liftToContrast(seed, restSurface, exports.MIN_PERCEPTIBLE_STEP);
 }
+/**
+ * Settles ink into `target` against EVERY surface at once. Softening one step can change which
+ * surface is hardest, so resolving against a single pre-computed "hardest" one lands under the
+ * floor on another — that is how radiant and rosewood ended up with an invisible outline on
+ * their muted surface.
+ */
+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;
+}
+/**
+ * A pure-grey surface sitting `target` contrast away from `backdrop`. Binary search, not a walk:
+ * `liftToContrast` cannot move a seed already at lightness 0 or 100, and a pure-white panel seeded
+ * itself straight to black. Neutral on purpose — the light palettes are hand-authored and tinted,
+ * so lifting one of their surface rungs turns a selected row into a saturated brand block, while
+ * the derived dark palettes land on grey and look right.
+ */
+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,19 @@
+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[]];
+/**
+ * The hint ink for a field: the brand's authored rung settled onto `PLACEHOLDER_TEXT` against the
+ * hardest surface a field can land on — lifted when it falls short, softened when it overshoots.
+ *
+ * Settled rather than floored because the authored rungs measured 3.96-7.73:1 across the brands,
+ * and anything much past the floor reads as a field already typed into. The floor is the look:
+ * one hint weight for every brand in both modes, instead of a per-brand accident.
+ */
+export declare const placeholderInkOn: (palette: PaletteProps, surfaces: FieldSurfaces) => string;
+/**
+ * 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.
+ */
+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,35 @@
+"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");
+/**
+ * The hint ink for a field: the brand's authored rung settled onto `PLACEHOLDER_TEXT` against the
+ * hardest surface a field can land on — lifted when it falls short, softened when it overshoots.
+ *
+ * Settled rather than floored because the authored rungs measured 3.96-7.73:1 across the brands,
+ * and anything much past the floor reads as a field already typed into. The floor is the look:
+ * one hint weight for every brand in both modes, instead of a per-brand accident.
+ */
+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;
+/**
+ * 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.
+ */
+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,10 @@
 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. */
+/**
+ * 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.
+ */
 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,14 @@ 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");
+/**
+ * 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.
+ */
 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,13 @@
+import type { PaletteProps } from "../types";
+export interface RowStateBackgrounds {
+    active: string;
+    selected: string;
+    selectedActive: string;
+}
+/**
+ * The three backgrounds a selectable list row can rest on. Every rung is NEUTRAL and pale, so a
+ * row's ink stays the canvas ink `withSurfaceRungs` already settled. Seeding a row state from
+ * `primary[500]` instead — the filled-button rung — is what painted SelectV2's hovered rows a
+ * solid brand fill under unreadable text.
+ */
+export declare const listRowBackgrounds: (colors: PaletteProps) => RowStateBackgrounds;

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

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listRowBackgrounds = void 0;
+const outlineRung_1 = require("./outlineRung");
+/**
+ * The three backgrounds a selectable list row can rest on. Every rung is NEUTRAL and pale, so a
+ * row's ink stays the canvas ink `withSurfaceRungs` already settled. Seeding a row state from
+ * `primary[500]` instead — the filled-button rung — is what painted SelectV2's hovered rows a
+ * solid brand fill under unreadable text.
+ */
+const listRowBackgrounds = (colors) => {
+    const selected = colors.backgroundColor.tertiary;
+    return {
+        active: (0, outlineRung_1.resolveHoverTint)(colors.gray[50], colors.backgroundColor.light),
+        selected,
+        selectedActive: (0, outlineRung_1.resolveHoverTint)(selected, selected),
+    };
+};
+exports.listRowBackgrounds = listRowBackgrounds;

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/surfaceRungs.d.ts

@@ -1,6 +1,9 @@
 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;
+/**
+ * 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.
+ */
+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,8 +6,11 @@ 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;
+/**
+ * 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.
+ */
+exports.PLACEHOLDER_TEXT = outlineRung_1.AA_NON_TEXT;
 const namedSurfaces = (palette) => [
     ...Object.values(palette.backgroundColor),
     palette.background[50],
@@ -21,7 +24,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 +37,18 @@ 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),
+        // `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.
+        // Settled, not lifted: this rung already passed through `withOutlineRung`, and lifting it
+        // again here to AA_NON_TEXT is what shipped 3.85-4.95:1 outlines. See CHROME_BORDER.
+        boxborder: {
+            ...palette.boxborder,
+            200: rule(palette.boxborder[200]),
+            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/types.d.ts

@@ -65,6 +65,24 @@ export type SidebarTokens = {
     /** Status ink resolved against the RAIL. `semanticText` is canvas-relative, not rail. */
     semanticText: SemanticTextTokens;
 };
+/**
+ * The two-tone focus indicator. `ring` is the brand-toned band that carries WCAG 1.4.11
+ * against whatever is BEHIND the control; `halo` is the inner band drawn between the ring
+ * and the control's own fill, so the indicator stays visible on a filled button too.
+ *
+ * Two tones because one band cannot own both adjacencies. `ring` is resolved against three
+ * backdrops (canvas, card, `primary[500]`) and clears all three on every brand — but a button
+ * can be filled by any `colorScheme`, and widening the ring to cover the mid-tone named surfaces
+ * as well leaves `skyline` and `storefront` with no solution at any hue (contrast is luminance
+ * alone, and their bands come out empty). `halo` takes the fill-side adjacency instead, so the
+ * pair holds whatever the button is filled with and whatever it sits on.
+ */
+export type FocusRingTokens = {
+    /** Outer band. >=3:1 against the canvas, a card surface, and the control's own fill. */
+    ring: string;
+    /** Inner band, in the surface tone. >=3:1 against the fill it hugs and against `ring`. */
+    halo: string;
+};
 export type BoxShadowTokens = {
     primary: string;
     error: string;
@@ -102,6 +120,8 @@ export type PaletteProps = {
     header: ColorScale;
     placeholder: ColorScale;
     boxShadow: BoxShadowTokens;
+    /** Two-tone `:focus-visible` indicator, resolved to 3:1 (WCAG 1.4.11). Never hand-written. */
+    focusRing: FocusRingTokens;
     sidebar: SidebarTokens;
     boxborder: ColorScale;
     border: ColorScale;
@@ -125,7 +145,7 @@ export type PaletteProps = {
 };
 /** What a brand writes by hand; every token required, so a gap is a compile error. */
 /** Derived tokens are excluded — `finalizeLightPalette` resolves them per brand. */
-export type BrandPaletteSource = Omit<PaletteProps, "accentText" | "textMuted" | "semanticText" | "sidebar" | "onPrimary" | "onSemantic"> & {
+export type BrandPaletteSource = Omit<PaletteProps, "accentText" | "textMuted" | "semanticText" | "sidebar" | "onPrimary" | "onSemantic" | "focusRing"> & {
     sidebar: {
         background: ColorScale;
     };

package/dist/Utils/table.d.ts

@@ -16,6 +16,9 @@ export type TablePaletteColor = {
     text: string;
     onSolid?: string;
 };
+export type SemanticStatusTone = "info" | "warning" | "success" | "error" | "neutral";
+/** Theme-aware status palette per value — soft fill + semantic ink from `resolveStatusTone`. */
+export declare function buildSemanticStatusPalette(toneByValue: Record<string, SemanticStatusTone>, theme: CustomThemeProps): Record<string, TablePaletteColor>;
 /** Deterministic, theme-aware color palette for groups + status pills. */
 export declare function buildTablePalette(theme: CustomThemeProps): TablePaletteColor[];
 /** Pick a deterministic palette color for a value, with optional consumer override hex. */