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

package/dist/Theme/provider/ThemeSwitcher.js

@@ -26,7 +26,10 @@ const toBrandLabel = (brand) => brand.charAt(0).toUpperCase() + brand.slice(1);
  * regardless of which brand/mode is currently active.
  */
 const brandSwatchColor = (brand) => index_1.brandThemes[brand].light.colors.primary[500];
-const BrandSwatch = ({ brand }) => ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-block", w: "0.625rem", h: "0.625rem", borderRadius: "full", bg: brandSwatchColor(brand), border: "1px solid", borderColor: "whiteAlpha.300", flexShrink: 0 }));
+const BrandSwatch = ({ brand }) => {
+    const { colors } = (0, useCustomTheme_1.useCustomTheme)();
+    return ((0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", display: "inline-block", w: "0.625rem", h: "0.625rem", borderRadius: "full", bg: brandSwatchColor(brand), border: "1px solid", borderColor: colors.boxborder[200], flexShrink: 0 }));
+};
 /**
  * Palette values already differ per color mode (`brandThemes[brand].light|dark`), so tokens
  * are read straight from the active theme — no `useColorModeValue` pairing needed here.
@@ -39,7 +42,7 @@ const useSwitcherColors = () => {
         activeColor: colors.primary[500],
         mutedColor: colors.text[600],
         hoverBg: colors.gray[100],
-        borderColor: colors.border[200],
+        borderColor: colors.boxborder[200],
         // NOTE: menuBg lives in Menu.styles.ts — re-pushing it via `sx` flickers on every render.
         menuColor: colors.text[900],
     };

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

@@ -46,6 +46,7 @@ const sidebarAccent_1 = require("../builders/sidebarAccent");
 const mutedText_1 = require("../builders/mutedText");
 const semanticText_1 = require("../builders/semanticText");
 const resolvedRungs_1 = require("../builders/resolvedRungs");
+const focusRing_1 = require("../builders/focusRing");
 const surfaceRungs_1 = require("../builders/surfaceRungs");
 /** Derived, never hand-written: a copied hex goes stale the moment a canvas moves. */
 const finalizeLightPalette = (source) => ({
@@ -56,9 +57,13 @@ const finalizeLightPalette = (source) => ({
     semanticText: (0, semanticText_1.buildSemanticText)(source.semantic, source.backgroundColor.main),
     onPrimary: (0, accentText_1.onFilled)(source.primary[500], source.white, source.black),
     onSemantic: (0, semanticText_1.buildOnSemantic)(source.semantic, source.white, source.black),
+    focusRing: (0, focusRing_1.buildFocusRing)(source),
 });
 exports.finalizeLightPalette = finalizeLightPalette;
-const resolveRungs = (palette) => (0, surfaceRungs_1.withSurfaceRungs)((0, resolvedRungs_1.withTableHoverRung)((0, resolvedRungs_1.withPlaceholderRung)((0, outlineRung_1.withOutlineRung)(palette))));
+// `withFocusRing` is outermost: it is the only step that reads `primary` and the surfaces
+// TOGETHER, so it must see both after every earlier step — and after a brand file's own
+// post-derivation overrides (zinc dark replaces `primary` and `background` wholesale).
+const resolveRungs = (palette) => (0, focusRing_1.withFocusRing)((0, surfaceRungs_1.withSurfaceRungs)((0, resolvedRungs_1.withTableHoverRung)((0, resolvedRungs_1.withPlaceholderRung)((0, outlineRung_1.withOutlineRung)(palette)))));
 const lightBrand = (source) => resolveRungs((0, exports.finalizeLightPalette)(source));
 /** Light palette per brand. `lavender` is the base the other six extend. */
 exports.lightPalettes = {

package/dist/Theme/tokens/brands/zinc/palette.dark.d.ts

@@ -197,6 +197,7 @@ declare const palette: {
     purple: import("../..").ColorScale;
     pink: import("../..").ColorScale;
     backgroundColor: import("../..").NamedSurfaces;
+    focusRing: import("../..").FocusRingTokens;
     sidebar: import("../..").SidebarTokens;
     semanticText: import("../..").SemanticTextTokens;
     textMuted: string;

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

@@ -8,6 +8,7 @@ const accentText_1 = require("./accentText");
 const sidebarAccent_1 = require("./sidebarAccent");
 const mutedText_1 = require("./mutedText");
 const semanticText_1 = require("./semanticText");
+const focusRing_1 = require("./focusRing");
 /**
  * Derives a brand's dark palette from its light palette.
  *
@@ -246,6 +247,7 @@ function buildDarkPalette(light) {
     ]));
     const white = light.white;
     const primary = liftBrand(light.primary, white);
+    const background = fromTargets(hueSource, SURFACE_TARGETS, SURFACE_SAT);
     const semantic = {
         success: liftAccent(light.semantic.success, white),
         error: liftAccent(light.semantic.error, white),
@@ -276,7 +278,7 @@ function buildDarkPalette(light) {
         purple: (0, exports.reverseScale)(light.purple),
         pink: (0, exports.reverseScale)(light.pink),
         backgroundColor: namedSurfaces,
-        background: fromTargets(hueSource, SURFACE_TARGETS, SURFACE_SAT),
+        background,
         text: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT),
         header: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT + 2),
         placeholder: fromTargets(hueSource, PLACEHOLDER_TARGETS, PLACEHOLDER_SAT),
@@ -293,6 +295,9 @@ function buildDarkPalette(light) {
         semanticText: (0, semanticText_1.buildSemanticText)(semantic, namedSurfaces.main),
         onPrimary: (0, accentText_1.onFilled)(primary[500], light.white, light.black),
         onSemantic: (0, semanticText_1.buildOnSemantic)(semantic, light.white, light.black),
+        // The dark ring is derived from the LIFTED accent against the dark canvas, not copied from
+        // light: the two modes squeeze it from opposite sides, so a shared value fails one of them.
+        focusRing: (0, focusRing_1.buildFocusRing)({ primary, background, backgroundColor: namedSurfaces }),
         // Sidebar is already near-black in light mode, so it needs no inversion.
         sidebar: (0, sidebarAccent_1.withSidebarTokens)(light),
         boxShadow: {

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

@@ -34,7 +34,7 @@ function chartInk(colors) {
         surface,
         text: colors.text[900],
         muted: colors.text[500],
-        grid: colors.border[500],
+        grid: colors.boxborder[200],
         axis: colors.text[500],
         tooltipBg: colors.backgroundColor.secondary,
     };

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

@@ -0,0 +1,29 @@
+import type { ColorScale, PaletteProps } from "../types";
+/** Resolved fill + ink for a solid surface, including hover/active steps. */
+export type FilledSurface = {
+    rung: keyof ColorScale;
+    fill: string;
+    color: string;
+    hoverRung: keyof ColorScale;
+    hoverFill: string;
+    hoverColor: string;
+    activeRung: keyof ColorScale;
+    activeFill: string;
+    activeColor: string;
+};
+/**
+ * Lightest rung on `scale` that still carries `white` at WCAG AA. Prefers [500] when it already
+ * passes; otherwise walks toward darker rungs. Used for solid fills on buttons, tags, badges and
+ * table status pills so consumers never get black ink on a saturated fill when white is achievable.
+ */
+export declare const solidFillRung: (scale: ColorScale, white: string) => keyof ColorScale;
+/** Hover (step 0) or active (step 1) fill rung, one step darker than `solidFillRung`. */
+export declare const darkerFillRung: (scale: ColorScale, canvas: string, white: string, step: 0 | 1) => keyof ColorScale;
+/** Label ink for a specific fill swatch — always `onFilled`, exported for style configs. */
+export declare const labelOnFill: (fill: string, white: string, black: string) => string;
+/**
+ * Consumer-facing helper: given any `ColorScale` (primary, red, semantic.error, …), return the
+ * fill rung and matching ink for solid / hover / active states. Use this whenever you paint a
+ * `bg` from a scale — never pair `scale[500]` with `onFilled` or `colors.white` by hand.
+ */
+export declare const resolveFilledSurface: (scale: ColorScale, colors: Pick<PaletteProps, "white" | "black" | "backgroundColor">) => FilledSurface;

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

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFilledSurface = exports.labelOnFill = exports.darkerFillRung = exports.solidFillRung = void 0;
+const color_1 = require("./color");
+const accentText_1 = require("./accentText");
+const RUNGS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+/**
+ * The rung one/two steps DARKER than the accent — what a filled button's hover/active needs so its
+ * white label stays legible.
+ *
+ * Every dark scale runs dark -> light across 50 -> 900 (brand scales are rebuilt that way, utility
+ * hues are reversed), the mirror of light mode. So "darker than [500]" is [600]/[700] in light but
+ * [400]/[300] in dark.
+ */
+const FILL_STEP_RUNGS = { light: [600, 700], dark: [400, 300] };
+/**
+ * Lightest rung on `scale` that still carries `white` at WCAG AA. Prefers [500] when it already
+ * passes; otherwise walks toward darker rungs. Used for solid fills on buttons, tags, badges and
+ * table status pills so consumers never get black ink on a saturated fill when white is achievable.
+ */
+const solidFillRung = (scale, white) => {
+    if ((0, color_1.contrastRatio)(scale[500], white) >= accentText_1.AA_NORMAL_TEXT)
+        return 500;
+    const passing = RUNGS.filter((r) => scale[r] && (0, color_1.contrastRatio)(scale[r], white) >= accentText_1.AA_NORMAL_TEXT);
+    if (!passing.length)
+        return 500;
+    return passing.reduce((a, b) => (0, color_1.contrastRatio)(scale[a], white) <= (0, color_1.contrastRatio)(scale[b], white) ? a : b);
+};
+exports.solidFillRung = solidFillRung;
+const steppedRung = (base, canvas, step) => {
+    const dir = (0, accentText_1.isDarkCanvas)(canvas) ? -100 : 100;
+    return Math.min(900, Math.max(50, base + dir * step));
+};
+/** Hover (step 0) or active (step 1) fill rung, one step darker than `solidFillRung`. */
+const darkerFillRung = (scale, canvas, white, step) => {
+    const base = (0, exports.solidFillRung)(scale, white);
+    if (base === 500) {
+        const mode = (0, accentText_1.isDarkCanvas)(canvas) ? "dark" : "light";
+        return FILL_STEP_RUNGS[mode][step];
+    }
+    const stepped = steppedRung(base, canvas, step === 0 ? 1 : 2);
+    return stepped;
+};
+exports.darkerFillRung = darkerFillRung;
+/** Label ink for a specific fill swatch — always `onFilled`, exported for style configs. */
+const labelOnFill = (fill, white, black) => (0, accentText_1.onFilled)(fill, white, black);
+exports.labelOnFill = labelOnFill;
+/**
+ * Consumer-facing helper: given any `ColorScale` (primary, red, semantic.error, …), return the
+ * fill rung and matching ink for solid / hover / active states. Use this whenever you paint a
+ * `bg` from a scale — never pair `scale[500]` with `onFilled` or `colors.white` by hand.
+ */
+const resolveFilledSurface = (scale, colors) => {
+    const { white, black, backgroundColor } = colors;
+    const canvas = backgroundColor.main;
+    const rung = (0, exports.solidFillRung)(scale, white);
+    const fill = scale[rung];
+    const hoverRung = (0, exports.darkerFillRung)(scale, canvas, white, 0);
+    const hoverFill = scale[hoverRung];
+    const activeRung = (0, exports.darkerFillRung)(scale, canvas, white, 1);
+    const activeFill = scale[activeRung];
+    return {
+        rung,
+        fill,
+        color: (0, exports.labelOnFill)(fill, white, black),
+        hoverRung,
+        hoverFill,
+        hoverColor: (0, exports.labelOnFill)(hoverFill, white, black),
+        activeRung,
+        activeFill,
+        activeColor: (0, exports.labelOnFill)(activeFill, white, black),
+    };
+};
+exports.resolveFilledSurface = resolveFilledSurface;

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