pixelize-design-library 2.4.2-beta.0 → 2.4.2-beta.10

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

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

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

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

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

@@ -0,0 +1,5 @@
+import type { ColorScale } from "../types";
+/** WCAG 1.4.3 — muted is still body text. */
+export declare const AA_NORMAL_TEXT = 4.5;
+/** Seeded from the ramp's muted rung so brand tint survives, then lifted until it clears AA. */
+export declare const buildMutedText: (text: ColorScale, canvas: string) => string;

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

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMutedText = exports.AA_NORMAL_TEXT = void 0;
+const outlineRung_1 = require("./outlineRung");
+/** WCAG 1.4.3 — muted is still body text. */
+exports.AA_NORMAL_TEXT = 4.5;
+/** Seeded from the ramp's muted rung so brand tint survives, then lifted until it clears AA. */
+const buildMutedText = (text, canvas) => (0, outlineRung_1.liftToContrast)(text[400], canvas, exports.AA_NORMAL_TEXT);
+exports.buildMutedText = buildMutedText;

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

@@ -1,4 +1,4 @@
-import type { PaletteProps, ResolvedColorMode } from "../types";
+import type { PaletteProps } from "../types";
 /**
  * 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.
@@ -8,21 +8,44 @@ 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;
 /**
- * Walks a hex toward `target` contrast against `backdrop`, keeping its hue and saturation so the
- * result still reads as the same colour. Darkens when `mode` is light, lightens when dark, and
- * stops at the FIRST passing step so nothing overshoots to black or white.
+ * Resting chrome — card, popover and field outlines — settles here, not at `AA_NON_TEXT`.
+ * At 3:1 a container border is text-weight and the UI reads as a wireframe; every mainstream
+ * system draws this line far lighter (Tailwind gray-200 1.24, Chakra gray.200 1.30, Material
+ * outline-variant 1.61). 1.4.11 asks that a control be identifiable, not that its resting
+ * border carry the whole job: the fill, the label and the focus ring do that, and the focus
+ * ring is still held to `AA_NON_TEXT`.
  */
-export declare function liftToContrast(hex: string, backdrop: string, mode: ResolvedColorMode, target?: number): string;
+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
+ * with the backdrop in every call site, and a redundant argument is one that can be wrong.
+ * Tries the far side first, falls back to the near side, and stops at the first passing step.
+ */
+export declare function liftToContrast(hex: string, backdrop: string, target?: number): string;
+/**
+ * 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 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.
  */
-export declare function withOutlineRung(palette: PaletteProps, mode: ResolvedColorMode): PaletteProps;
+export declare function withOutlineRung(palette: PaletteProps): PaletteProps;
 /**
  * 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
@@ -32,3 +55,10 @@ export declare function withOutlineRung(palette: PaletteProps, mode: ResolvedCol
  * 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;

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

@@ -1,11 +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;
 const color_1 = require("./color");
-const accentText_1 = require("./accentText");
 /**
  * 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.
@@ -15,34 +17,80 @@ 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 its hue and saturation so the
- * result still reads as the same colour. Darkens when `mode` is light, lightens when dark, and
- * stops at the FIRST passing step so nothing overshoots to black or white.
+ * Resting chrome — card, popover and field outlines — settles here, not at `AA_NON_TEXT`.
+ * At 3:1 a container border is text-weight and the UI reads as a wireframe; every mainstream
+ * system draws this line far lighter (Tailwind gray-200 1.24, Chakra gray.200 1.30, Material
+ * outline-variant 1.61). 1.4.11 asks that a control be identifiable, not that its resting
+ * border carry the whole job: the fill, the label and the focus ring do that, and the focus
+ * ring is still held to `AA_NON_TEXT`.
  */
-function liftToContrast(hex, backdrop, mode, target = exports.AA_NON_TEXT) {
+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
+ * 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.
+ */
+function liftToContrast(hex, backdrop, target = exports.AA_NON_TEXT) {
     if ((0, color_1.contrastRatio)(hex, backdrop) >= target)
         return hex;
-    const { s } = (0, color_1.hexToHsl)(hex);
-    const step = mode === "dark" ? 1 : -1;
-    let { l } = (0, color_1.hexToHsl)(hex);
-    while (l > 0 && l < 100) {
-        l += step;
+    const { s, l: start } = (0, color_1.hexToHsl)(hex);
+    const away = (0, color_1.relativeLuminance)(backdrop) < 0.5 ? 1 : -1;
+    for (const step of [away, -away]) {
+        let l = start;
+        while (l > 0 && l < 100) {
+            l += step;
+            const next = (0, color_1.withLightness)(hex, l, s);
+            if ((0, color_1.contrastRatio)(next, backdrop) >= target)
+                return next;
+        }
+    }
+    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;
+    const { s, l: start } = (0, color_1.hexToHsl)(hex);
+    const toward = (0, color_1.relativeLuminance)(backdrop) < 0.5 ? -1 : 1;
+    let softest = hex;
+    for (let l = start; l > 0 && l < 100; l += toward) {
         const next = (0, color_1.withLightness)(hex, l, s);
-        if ((0, color_1.contrastRatio)(next, backdrop) >= target)
-            return next;
+        if ((0, color_1.contrastRatio)(next, backdrop) < target)
+            break;
+        softest = next;
     }
-    return (0, color_1.withLightness)(hex, mode === "dark" ? 100 : 0, s);
+    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.
+ * 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.
  */
-function withOutlineRung(palette, mode) {
+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.
@@ -50,7 +98,9 @@ function withOutlineRung(palette, mode) {
         (0, color_1.contrastRatio)(current, palette.background[50])
         ? palette.backgroundColor.main
         : palette.background[50];
-    const resolved = liftToContrast(current, backdrop, mode);
+    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 } };
@@ -64,6 +114,27 @@ function withOutlineRung(palette, mode) {
  * its OWN list background, not necessarily the page canvas.
  */
 function resolveHoverTint(seed, restSurface) {
-    const mode = (0, accentText_1.isDarkCanvas)(restSurface) ? "dark" : "light";
-    return liftToContrast(seed, restSurface, mode, exports.MIN_PERCEPTIBLE_STEP);
+    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;
 }

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

@@ -0,0 +1,11 @@
+import { AA_NON_TEXT } from "./outlineRung";
+import type { PaletteProps } from "../types";
+/**
+ * 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;
+export { AA_NON_TEXT };

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

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AA_NON_TEXT = void 0;
+exports.withPlaceholderRung = withPlaceholderRung;
+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");
+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], surfaceRungs_1.PLACEHOLDER_TEXT);
+    if (resolved === palette.placeholder[500])
+        return palette;
+    return { ...palette, placeholder: { ...palette.placeholder, 500: resolved } };
+}
+/** The hover row is a SURFACE, so it steps away from the ink rather than the ink moving. */
+function withTableHoverRung(palette) {
+    const resolved = (0, outlineRung_1.liftToContrast)(palette.table.hover[500], palette.text[500], accentText_1.AA_NORMAL_TEXT);
+    if (resolved === palette.table.hover[500])
+        return palette;
+    return {
+        ...palette,
+        table: { hover: { ...palette.table.hover, 500: resolved } },
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { PaletteProps } from "../types";
+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

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCROLLBAR_WIDTH = void 0;
+exports.scrollbarStyles = scrollbarStyles;
+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.
+ */
+function scrollbarStyles(palette, variant = "default") {
+    const { gray } = palette;
+    const track = variant === "default" ? gray[100] : "transparent";
+    const thumb = variant === "hover" ? "transparent" : gray[400];
+    return {
+        scrollbarWidth: "thin",
+        scrollbarColor: `${thumb} ${track}`,
+        "&::-webkit-scrollbar": {
+            width: exports.SCROLLBAR_WIDTH,
+            height: exports.SCROLLBAR_WIDTH,
+        },
+        "&::-webkit-scrollbar-track": {
+            background: track,
+            borderRadius: RADIUS,
+        },
+        "&::-webkit-scrollbar-thumb": {
+            background: thumb,
+            borderRadius: RADIUS,
+            transition: "background 0.2s ease",
+        },
+        "&::-webkit-scrollbar-thumb:hover": {
+            background: gray[500],
+        },
+        "&::-webkit-scrollbar-corner": {
+            background: track,
+        },
+        ...(variant === "hover"
+            ? {
+                "&:hover": { scrollbarColor: `${gray[400]} ${track}` },
+                "&:hover::-webkit-scrollbar-thumb": { background: gray[400] },
+            }
+            : {}),
+    };
+}
+/** The same chrome for the document itself, where `&` selectors do not apply. */
+function globalScrollbarStyles(palette) {
+    const { gray } = palette;
+    return {
+        "::-webkit-scrollbar": { width: exports.SCROLLBAR_WIDTH, height: exports.SCROLLBAR_WIDTH },
+        "::-webkit-scrollbar-track": { background: gray[100] },
+        "::-webkit-scrollbar-thumb": { background: gray[400], borderRadius: RADIUS },
+        "::-webkit-scrollbar-thumb:hover": { background: gray[500] },
+        "::-webkit-scrollbar-corner": { background: gray[100] },
+    };
+}

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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOnSemantic = exports.buildSemanticText = exports.SEMANTIC_TONES = void 0;
+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.
+ */
+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;
+}, {});
+exports.buildSemanticText = buildSemanticText;
+/** Ink ON the fill, not on the canvas — the pair a CSS module needs but cannot compute. */
+const buildOnSemantic = (semantic, white, black) => exports.SEMANTIC_TONES.reduce((acc, tone) => {
+    acc[tone] = (0, accentText_1.onFilled)(semantic[tone][500], white, black);
+    return acc;
+}, {});
+exports.buildOnSemantic = buildOnSemantic;

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

@@ -0,0 +1,9 @@
+import type { BrandPaletteSource, ColorScale, SemanticColors, SidebarTokens } from "../types";
+/** WCAG 1.4.3 — the active label is normal-size text. */
+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;
+/** 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

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSidebarTokens = exports.buildSidebarTokens = 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");
+/** WCAG 1.4.3 — the active label is normal-size text. */
+exports.AA_NORMAL_TEXT = 4.5;
+/** Lightest surface an active row reaches: Chakra `whiteAlpha.400` (0.24) on hover. */
+exports.ACTIVE_SURFACE_TINT = "#ffffff3d";
+const sidebarActiveSurface = (background) => (0, color_1.compositeOver)(exports.ACTIVE_SURFACE_TINT, background[500]);
+exports.sidebarActiveSurface = sidebarActiveSurface;
+/** 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);
+    const elevated = (0, outlineRung_1.resolveHoverTint)(background[500], background[500]);
+    return {
+        background,
+        elevated,
+        activeIcon: (0, outlineRung_1.liftToContrast)(lightPrimary[300], surface, outlineRung_1.AA_NON_TEXT),
+        activeLabel: (0, outlineRung_1.liftToContrast)(lightPrimary[100], surface, exports.AA_NORMAL_TEXT),
+        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),
+    };
+};
+exports.buildSidebarTokens = buildSidebarTokens;
+const withSidebarTokens = (source) => (0, exports.buildSidebarTokens)(source.sidebar.background, source.primary, source.semantic);
+exports.withSidebarTokens = withSidebarTokens;

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

@@ -22,8 +22,8 @@ function resolveStatusTone(scale, mode) {
     const edgeSeed = mode === "dark" ? scale[400] : scale[300];
     return {
         bg,
-        fg: (0, outlineRung_1.liftToContrast)(inkSeed, bg, mode, accentText_1.AA_NORMAL_TEXT),
-        border: (0, outlineRung_1.liftToContrast)(edgeSeed, bg, mode, outlineRung_1.AA_NON_TEXT),
+        fg: (0, outlineRung_1.liftToContrast)(inkSeed, bg, accentText_1.AA_NORMAL_TEXT),
+        border: (0, outlineRung_1.liftToContrast)(edgeSeed, bg, outlineRung_1.AA_NON_TEXT),
     };
 }
 /**
@@ -32,8 +32,7 @@ function resolveStatusTone(scale, mode) {
  * dark. Darkening the fill keeps the intended hue and the white-initials look while clearing AA.
  */
 function resolveAvatarFill(hex, target = accentText_1.AA_NORMAL_TEXT) {
-    // "light" walks downward in lightness — i.e. darken until white ink clears the bar.
-    return (0, outlineRung_1.liftToContrast)(hex, "#ffffff", "light", target);
+    return (0, outlineRung_1.liftToContrast)(hex, "#ffffff", target);
 }
 /**
  * Hue set for generated avatars. Values are seeds, not final fills — always pass them through

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

@@ -0,0 +1,10 @@
+import type { PaletteProps } from "../types";
+/**
+ * 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;
+export declare function withSurfaceRungs(palette: PaletteProps): PaletteProps;

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hardestSurface = exports.namedSurfaces = exports.PLACEHOLDER_TEXT = void 0;
+exports.withSurfaceRungs = withSurfaceRungs;
+const color_1 = require("./color");
+const outlineRung_1 = require("./outlineRung");
+const accentText_1 = require("./accentText");
+const semanticText_1 = require("./semanticText");
+/**
+ * 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],
+    palette.table.hover[500],
+];
+exports.namedSurfaces = namedSurfaces;
+/** The surface an ink is closest to — clearing it clears every other one. */
+const hardestSurface = (ink, surfaces) => surfaces.reduce((worst, s) => (0, color_1.contrastRatio)(ink, s) < (0, color_1.contrastRatio)(ink, worst) ? s : worst);
+exports.hardestSurface = hardestSurface;
+// Runs last: `table.hover` is one of the surfaces, and it settles in its own rung.
+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 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;
+    }, {});
+    return {
+        ...palette,
+        textMuted: lift(palette.textMuted, accentText_1.AA_NORMAL_TEXT),
+        accentText: (0, accentText_1.pickAccentText)(palette.primary, (0, exports.hardestSurface)(palette.accentText, surfaces)),
+        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` 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),
+        },
+        // 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]) },
+    };
+}