pixelize-design-library 2.4.2-beta.3 → 2.4.2-beta.31

package/dist/Theme/chakra/focusRing.styles.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.focusVisibleStyles = exports.focusVisibleRing = exports.FOCUS_VISIBLE_OVER_STATE = exports.focusRingShadow = exports.FOCUS_RING_WIDTH = exports.FOCUS_HALO_WIDTH = void 0;
+/**
+ * WEB binding for the `focusRing` token pair. The colours are derived in
+ * `tokens/builders/focusRing.ts` (pure, shared with the mobile library); the CSS shape —
+ * box-shadow bands, the forced-colors outline — is web-only and lives here.
+ */
+/** Inner band, in the surface tone: separates the ring from the control's own fill. */
+exports.FOCUS_HALO_WIDTH = 2;
+/** Outer edge of the brand band. The band itself is the 2px between halo and ring. */
+exports.FOCUS_RING_WIDTH = 4;
+/**
+ * The two-tone ring as a single `box-shadow`. Drawn OUTSIDE the border box, so it costs no
+ * layout and never resizes the control — the reason this is a shadow and not an outline.
+ */
+const focusRingShadow = (colors) => `0 0 0 ${exports.FOCUS_HALO_WIDTH}px ${colors.focusRing.halo}, ` +
+    `0 0 0 ${exports.FOCUS_RING_WIDTH}px ${colors.focusRing.ring}`;
+exports.focusRingShadow = focusRingShadow;
+/**
+ * `:hover`, `:active` and `:focus-visible` all score the same specificity, so which one paints
+ * comes down to source order — and in the merged style object Chakra's own Button baseStyle
+ * registers `_focusVisible` BEFORE `_hover`. A focused button that is also hovered would then
+ * drop the ring for `_hover`'s `boxShadow: "sm"`. Stacking the pseudo-classes raises the
+ * specificity above both, so the ring survives whatever else the state repaints.
+ */
+exports.FOCUS_VISIBLE_OVER_STATE = "&:hover:focus-visible, &:active:focus-visible, &[data-active]:focus-visible";
+/**
+ * `:focus-visible`, never `:focus` — a mouse click must not draw a ring.
+ *
+ * The transparent outline is not decoration: in Windows High Contrast / `forced-colors` mode
+ * box-shadows are dropped entirely, and a transparent outline is the one thing the OS repaints
+ * in its own focus colour. Without it, forced-colors users get no indicator at all.
+ */
+const focusVisibleRing = (colors) => ({
+    outline: "2px solid transparent",
+    outlineOffset: "2px",
+    boxShadow: (0, exports.focusRingShadow)(colors),
+});
+exports.focusVisibleRing = focusVisibleRing;
+/** Both selectors a control needs to keep the ring on top of its own hover/active styling. */
+const focusVisibleStyles = (colors) => {
+    const ring = (0, exports.focusVisibleRing)(colors);
+    return { _focusVisible: ring, [exports.FOCUS_VISIBLE_OVER_STATE]: ring };
+};
+exports.focusVisibleStyles = focusVisibleStyles;

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

@@ -0,0 +1,22 @@
+export type Gradient = {
+    from: string;
+    to: string;
+};
+/** A gradient already safe to paint, plus the ink that is guaranteed legible on it. */
+export type ResolvedGradient = Gradient & {
+    ink: string;
+};
+/**
+ * Sinks both stops until WHITE ink clears AA, keeping each stop's hue. Any mid-tone gradient
+ * otherwise flips `onGradient` to black ink, so the same element reads white-on-colour in one
+ * brand and black-on-pastel in the next.
+ */
+export declare const inkSafeGradient: (gradient: Gradient) => Gradient;
+/**
+ * The only correct way to paint text on a gradient: returns the stops to draw AND the ink for
+ * them. Calling `onGradient` on raw stops is the black-text bug — it picks ink for a backdrop
+ * that is then painted differently.
+ */
+export declare const resolveGradient: (gradient: Gradient, white: string, black: string) => ResolvedGradient;
+/** `linear-gradient(...)` for a resolved pair — one spelling of the CSS everywhere. */
+export declare const gradientCss: (g: Gradient, angle?: string) => string;

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

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gradientCss = exports.resolveGradient = exports.inkSafeGradient = void 0;
+const accentText_1 = require("./accentText");
+const statusTone_1 = require("./statusTone");
+/**
+ * Sinks both stops until WHITE ink clears AA, keeping each stop's hue. Any mid-tone gradient
+ * otherwise flips `onGradient` to black ink, so the same element reads white-on-colour in one
+ * brand and black-on-pastel in the next.
+ */
+const inkSafeGradient = (gradient) => ({
+    from: (0, statusTone_1.resolveAvatarFill)(gradient.from),
+    to: (0, statusTone_1.resolveAvatarFill)(gradient.to),
+});
+exports.inkSafeGradient = inkSafeGradient;
+/**
+ * The only correct way to paint text on a gradient: returns the stops to draw AND the ink for
+ * them. Calling `onGradient` on raw stops is the black-text bug — it picks ink for a backdrop
+ * that is then painted differently.
+ */
+const resolveGradient = (gradient, white, black) => {
+    const { from, to } = (0, exports.inkSafeGradient)(gradient);
+    return { from, to, ink: (0, accentText_1.onGradient)(from, to, white, black) };
+};
+exports.resolveGradient = resolveGradient;
+/** `linear-gradient(...)` for a resolved pair — one spelling of the CSS everywhere. */
+const gradientCss = (g, angle = "135deg") => `linear-gradient(${angle}, ${g.from} 0%, ${g.to} 100%)`;
+exports.gradientCss = gradientCss;

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

@@ -3,3 +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,3 +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
@@ -14,11 +36,17 @@ export declare const AA_NON_TEXT = 3;
  * 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.
@@ -33,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,9 +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
@@ -13,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
@@ -36,11 +69,30 @@ function liftToContrast(hex, backdrop, target = exports.AA_NON_TEXT) {
     const ends = [(0, color_1.withLightness)(hex, 100, s), (0, color_1.withLightness)(hex, 0, s)];
     return (0, color_1.contrastRatio)(ends[0], backdrop) >= (0, color_1.contrastRatio)(ends[1], backdrop) ? ends[0] : ends[1];
 }
+/**
+ * Mirror of `liftToContrast`: walks ink TOWARD the backdrop, stopping at the last step that
+ * still clears `target`. For ink that must stay legible without reading as body copy.
+ */
+function softenToContrast(hex, backdrop, target) {
+    if ((0, color_1.contrastRatio)(hex, backdrop) <= target)
+        return hex;
+    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)
+            break;
+        softest = next;
+    }
+    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.
@@ -53,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 } };
@@ -69,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;