pixelize-design-library 2.4.2-beta.43 → 2.4.2-beta.44

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

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

@@ -6,21 +6,7 @@ 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.
- */
+// NOTE: not settleAcross — a ring squeezed between a light canvas and a dark fill needs the closest color that clears both, not a per-surface lift.
 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))
@@ -34,40 +20,18 @@ function settleBetween(hex, backdrops, target = outlineRung_1.AA_NON_TEXT) {
         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.
+    // NOTE: unreachable for shipped brands (gated by focusRing.test.ts) — takes the least-bad end rather than throwing.
     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.
- */
+// NOTE: only canvas + card surface — including the fill or every named surface leaves no solvable hue.
 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.
- */
+// NOTE: replaces Chakra's stock ring (a fixed blue that measured under 2:1 on every brand).
 const buildFocusRing = (source) => {
     const halo = settleBetween(source.background[50], [source.primary[500]]);
     return {
@@ -76,15 +40,7 @@ const buildFocusRing = (source) => {
     };
 };
 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.
- */
+// NOTE: re-derives against the FINISHED palette — a brand file can still override primary/background after the generic pass.
 const withFocusRing = (palette) => ({
     ...palette,
     focusRing: (0, exports.buildFocusRing)(palette),

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

@@ -6,17 +6,7 @@ export type Gradient = {
 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

@@ -3,21 +3,13 @@ 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.
- */
+// NOTE: sinks both stops until white ink clears AA — otherwise a mid-tone gradient flips onGradient to black.
 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.
- */
+// The only correct way to paint gradient text — returns the stops to draw AND the ink for them together.
 const resolveGradient = (gradient, white, black) => {
     const { from, to } = (0, exports.inkSafeGradient)(gradient);
     return { from, to, ink: (0, accentText_1.onGradient)(from, to, white, black) };

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

@@ -7,3 +7,7 @@ export * from "./focusRing";
 export * from "./scrollbar";
 export * from "./gradientInk";
 export * from "./placeholderInk";
+export * from "./tone";
+export * from "./scrim";
+export * from "./tooltipSurface";
+export * from "./surfaceRaised";

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

@@ -23,3 +23,7 @@ __exportStar(require("./focusRing"), exports);
 __exportStar(require("./scrollbar"), exports);
 __exportStar(require("./gradientInk"), exports);
 __exportStar(require("./placeholderInk"), exports);
+__exportStar(require("./tone"), exports);
+__exportStar(require("./scrim"), exports);
+__exportStar(require("./tooltipSurface"), exports);
+__exportStar(require("./surfaceRaised"), exports);

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

@@ -1,78 +1,12 @@
 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.
- * A "hover" a user cannot perceive is not a hover.
- */
 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
- * 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). 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): 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
- * and Accordion: a pale `primary[50]`/`gray[50]` tint that measures near-1.0 on a near-white
- * surface — invisible — with no dark-mode branch, so the same call site is wrong in both modes at
- * once. `restSurface` is required rather than assumed white/black: a menu item's hover sits on
- * its OWN list background, not necessarily the page canvas.
- */
 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

@@ -9,49 +9,17 @@ exports.resolveHoverTint = resolveHoverTint;
 exports.settleAcross = settleAcross;
 exports.neutralStep = neutralStep;
 const color_1 = require("./color");
-/**
- * The floor a hover/active state's step off its own resting surface must clear to be seen at
- * all — same value the SideBar ladder, Accordion, and NavigationBar hover states are held to.
- * A "hover" a user cannot perceive is not a hover.
- */
 exports.MIN_PERCEPTIBLE_STEP = 1.15;
-/** WCAG 1.4.11 — a control outline is a UI component boundary, held to 3:1. */
 exports.AA_NON_TEXT = 3;
-/**
- * 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.
- */
+// NOTE: settles below AA_NON_TEXT — focusRing.ts covers the 1.4.11 gate instead.
 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;
@@ -69,10 +37,6 @@ function liftToContrast(hex, backdrop, target = exports.AA_NON_TEXT) {
     const ends = [(0, color_1.withLightness)(hex, 100, s), (0, color_1.withLightness)(hex, 0, s)];
     return (0, color_1.contrastRatio)(ends[0], backdrop) >= (0, color_1.contrastRatio)(ends[1], backdrop) ? ends[0] : ends[1];
 }
-/**
- * Mirror of `liftToContrast`: walks ink TOWARD the backdrop, stopping at the last step that
- * still clears `target`. For ink that must stay legible without reading as body copy.
- */
 function softenToContrast(hex, backdrop, target) {
     if ((0, color_1.contrastRatio)(hex, backdrop) <= target)
         return hex;
@@ -87,20 +51,9 @@ function softenToContrast(hex, backdrop, target) {
     }
     return softest;
 }
-/**
- * `boxborder[500]` is the rung every control outline reads (Checkbox, SearchSelect, the date
- * pickers, the editor's inputs). 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.
- */
+// NOTE: border[*] is untouched — it draws decorative table gridlines, outside 1.4.11.
 function withOutlineRung(palette) {
     const current = palette.boxborder[500];
-    // The border sits between the control's fill and the surface behind it; hold it to the
-    // harder of the two.
     const backdrop = (0, color_1.contrastRatio)(current, palette.backgroundColor.main) <=
         (0, color_1.contrastRatio)(current, palette.background[50])
         ? palette.backgroundColor.main
@@ -112,23 +65,10 @@ function withOutlineRung(palette) {
         return palette;
     return { ...palette, boxborder: { ...palette.boxborder, 500: resolved } };
 }
-/**
- * A hover/active tint resolved against the surface it actually sits on, guaranteed to clear
- * `MIN_PERCEPTIBLE_STEP`. Written for the recurring shape found across NavigationBar, UserDetails
- * and Accordion: a pale `primary[50]`/`gray[50]` tint that measures near-1.0 on a near-white
- * surface — invisible — with no dark-mode branch, so the same call site is wrong in both modes at
- * once. `restSurface` is required rather than assumed white/black: a menu item's hover sits on
- * its OWN list background, not necessarily the page canvas.
- */
 function resolveHoverTint(seed, restSurface) {
     return liftToContrast(seed, restSurface, exports.MIN_PERCEPTIBLE_STEP);
 }
-/**
- * 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.
- */
+// NOTE: settles against every surface at once — a single "hardest" surface can drop under target on another.
 function settleAcross(hex, surfaces, target) {
     const clearsAll = (c) => surfaces.every((s) => (0, color_1.contrastRatio)(c, s) >= target);
     if (!clearsAll(hex)) {
@@ -145,13 +85,7 @@ function settleAcross(hex, surfaces, target) {
     }
     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.
- */
+// NOTE: binary search, not liftToContrast — a seed already at lightness 0/100 can't walk.
 function neutralStep(backdrop, target) {
     const grey = (l) => (0, color_1.withLightness)("#808080", l, 0);
     let lo = (0, color_1.hexToHsl)(backdrop).l;

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

@@ -1,19 +1,7 @@
 import type { PaletteProps } from "../types";
 /** A field always renders on at least one surface — the first is the reference backdrop. */
 export type FieldSurfaces = readonly [string, ...string[]];
-/**
- * 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

@@ -4,14 +4,7 @@ exports.placeholderInk = exports.fieldSurfaces = exports.placeholderInkOn = void
 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.
- */
+// NOTE: settled (not floored) onto PLACEHOLDER_TEXT — one hint weight across brands, not a per-brand accident.
 const placeholderInkOn = (palette, surfaces) => {
     const rung = palette.placeholder[500];
     const hardest = surfaces.reduce((worst, s) => (0, color_1.contrastRatio)(rung, s) < (0, color_1.contrastRatio)(rung, worst) ? s : worst);
@@ -20,10 +13,7 @@ const placeholderInkOn = (palette, surfaces) => {
         : (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.
- */
+// NOTE: enabled fields only — 1.4.3 exempts disabled ones, and folding their dimmer fill in would darken every other field's hint.
 const fieldSurfaces = (palette) => [
     palette.gray[50],
     palette.background[50],

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

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

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

@@ -7,11 +7,7 @@ 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.
- */
+// NOTE: hint floored at 3:1, not 4.5:1 — held to body-text contrast it read as already-typed-into. See CHROME-CONSISTENCY.md.
 function withPlaceholderRung(palette) {
     const resolved = (0, outlineRung_1.liftToContrast)(palette.placeholder[500], palette.background[50], surfaceRungs_1.PLACEHOLDER_TEXT);
     if (resolved === palette.placeholder[500])

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

@@ -4,10 +4,4 @@ export interface RowStateBackgrounds {
     selected: string;
     selectedActive: string;
 }
-/**
- * The three backgrounds a selectable list row can rest on. Every rung is NEUTRAL and pale, so a
- * row's ink stays the canvas ink `withSurfaceRungs` already settled. Seeding a row state from
- * `primary[500]` instead — the filled-button rung — is what painted SelectV2's hovered rows a
- * solid brand fill under unreadable text.
- */
 export declare const listRowBackgrounds: (colors: PaletteProps) => RowStateBackgrounds;

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

@@ -2,16 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listRowBackgrounds = void 0;
 const outlineRung_1 = require("./outlineRung");
-/**
- * The three backgrounds a selectable list row can rest on. Every rung is NEUTRAL and pale, so a
- * row's ink stays the canvas ink `withSurfaceRungs` already settled. Seeding a row state from
- * `primary[500]` instead — the filled-button rung — is what painted SelectV2's hovered rows a
- * solid brand fill under unreadable text.
- */
+// NOTE: rungs stay neutral/pale — seeding from primary[500] instead once painted SelectV2's hover solid brand fill.
 const listRowBackgrounds = (colors) => {
-    const selected = colors.backgroundColor.tertiary;
+    // Dark aliases backgroundColor.tertiary to the panel, leaving the selected row at 1.025:1.
+    const selected = (0, outlineRung_1.liftToContrast)(colors.backgroundColor.tertiary, colors.surfaceRaised, outlineRung_1.MIN_PERCEPTIBLE_STEP);
     return {
-        active: (0, outlineRung_1.resolveHoverTint)(colors.gray[50], colors.backgroundColor.light),
+        active: (0, outlineRung_1.resolveHoverTint)(colors.gray[50], colors.surfaceRaised),
         selected,
         selectedActive: (0, outlineRung_1.resolveHoverTint)(selected, selected),
     };

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

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

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

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

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

@@ -3,10 +3,6 @@ export type ScrollbarStyle = Record<string, unknown>;
 /** One width everywhere. The 3px, 4px, 5px and 10px bars in use were all accidents. */
 export declare const SCROLLBAR_WIDTH = "6px";
 export type ScrollbarVariant = "default" | "overlay" | "hover";
-/**
- * The single source of scrollbar chrome. `overlay` drops the track for bars that float over a
- * card; `hover` keeps the thumb invisible until the region is hovered.
- */
 export declare function scrollbarStyles(palette: PaletteProps, variant?: ScrollbarVariant): ScrollbarStyle;
 /** The same chrome for the document itself, where `&` selectors do not apply. */
 export declare function globalScrollbarStyles(palette: PaletteProps): ScrollbarStyle;

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

@@ -6,10 +6,7 @@ exports.globalScrollbarStyles = globalScrollbarStyles;
 /** One width everywhere. The 3px, 4px, 5px and 10px bars in use were all accidents. */
 exports.SCROLLBAR_WIDTH = "6px";
 const RADIUS = "6px";
-/**
- * The single source of scrollbar chrome. `overlay` drops the track for bars that float over a
- * card; `hover` keeps the thumb invisible until the region is hovered.
- */
+// NOTE: single source of scrollbar chrome — `overlay` drops the track, `hover` hides the thumb until hovered.
 function scrollbarStyles(palette, variant = "default") {
     const { gray } = palette;
     const track = variant === "default" ? gray[100] : "transparent";

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

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

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

@@ -4,11 +4,7 @@ exports.buildOnSemantic = exports.buildSemanticText = exports.SEMANTIC_TONES = v
 const outlineRung_1 = require("./outlineRung");
 const accentText_1 = require("./accentText");
 exports.SEMANTIC_TONES = ["success", "error", "warning", "info"];
-/**
- * `semantic[tone][500]` is a FILL rung — as ink on a light canvas it measures 1.84-3.68:1 across
- * every brand. Each tone is stepped here until it clears AA as text, so a call site that wants
- * "error-coloured text" cannot pick the unreadable one.
- */
+// NOTE: semantic[tone][500] is a fill rung (1.84-3.68:1 as text) — stepped here until it clears AA.
 const buildSemanticText = (semantic, canvas) => exports.SEMANTIC_TONES.reduce((acc, tone) => {
     acc[tone] = (0, outlineRung_1.liftToContrast)(semantic[tone][500], canvas, accentText_1.AA_NORMAL_TEXT);
     return acc;

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

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