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

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

@@ -1,14 +1,6 @@
 import type { PaletteProps } from "../types";
 export type ThemeColorPalette = PaletteProps;
 export type ChartMode = "light" | "dark";
-/**
- * Categorical series palette. Generated in OKLCH on one fixed hue sequence per mode, so a
- * theme switch never repaints a series. Verified with the six-check validator: lightness
- * band, chroma floor, CVD separation, normal-vision floor and contrast all pass on both
- * surfaces. Worst adjacent protan/deutan separation is 10.9 (light) / 11.6 (dark) OKLab
- * dE, against a target of 8 — the previous four-color default scored 4.8 and was
- * unreadable for red-green color blindness. Re-run the validator before editing a value.
- */
 export declare const CATEGORICAL_SERIES: Record<ChartMode, readonly string[]>;
 export declare const chartMode: (colors: ThemeColorPalette) => ChartMode;
 export declare function getCategoricalSeriesColors(colors: ThemeColorPalette): string[];

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

@@ -7,14 +7,7 @@ exports.chartInk = chartInk;
 exports.mergeChartTitleStyle = mergeChartTitleStyle;
 exports.chartAxisLabelColor = chartAxisLabelColor;
 const accentText_1 = require("./accentText");
-/**
- * Categorical series palette. Generated in OKLCH on one fixed hue sequence per mode, so a
- * theme switch never repaints a series. Verified with the six-check validator: lightness
- * band, chroma floor, CVD separation, normal-vision floor and contrast all pass on both
- * surfaces. Worst adjacent protan/deutan separation is 10.9 (light) / 11.6 (dark) OKLab
- * dE, against a target of 8 — the previous four-color default scored 4.8 and was
- * unreadable for red-green color blindness. Re-run the validator before editing a value.
- */
+// NOTE: fixed OKLCH hue sequence per mode, six-check validated (CVD separation 10.9/11.6 dE vs target 8) — re-run the validator before editing.
 exports.CATEGORICAL_SERIES = {
     light: ["#009068", "#3177dc", "#5a8b00", "#8b5dce", "#9b7300", "#af4da9", "#cb4a2a", "#009d82"],
     dark: ["#00976d", "#377ee3", "#5f9200", "#9163d5", "#a27900", "#b654b0", "#d25030", "#00aa8e"],

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

@@ -1,9 +1,3 @@
-/**
- * Pure color math. No dependencies, no platform APIs — safe for the mobile port.
- *
- * Used by `buildDarkPalette` to derive dark ramps from each brand's own light colors,
- * and to assert contrast in tests.
- */
 export type Rgb = {
     r: number;
     g: number;
@@ -14,25 +8,11 @@ export type Hsl = {
     s: number;
     l: number;
 };
-/**
- * Accepts `#rgb` or `#rrggbb` only. An `#rrggbbaa` throws ON PURPOSE.
- *
- * The old version silently dropped the alpha and returned the fully-opaque rgb. That made
- * `contrastRatio` score a 16%-alpha hover tint as if it were solid — a measured 4.18 for a fill that
- * actually renders at 1.17 over the canvas, a 3.6x overstatement — with a doc comment saying "alpha
- * ignored" that made it look handled. Alpha over an unknown backdrop has no defined luminance, so the
- * only correct move is to refuse it: composite it first with `compositeOver`, then measure the result.
- */
 export declare function hexToRgb(hex: string): Rgb;
 /** Alpha in 0..1. `#rgb`/`#rrggbb` read as fully opaque (`a: 1`); `#rgba`/`#rrggbbaa` carry their alpha. */
 export declare function hexToRgba(hex: string): Rgb & {
     a: number;
 };
-/**
- * Flatten a translucent foreground onto an opaque backdrop — the ONLY way to get a real color for a
- * tint before measuring contrast. `contrastRatio(tint, canvas)` now throws; the correct call is
- * `contrastRatio(compositeOver(tint, canvas), canvas)`.
- */
 export declare function compositeOver(foreground: string, backdrop: string): string;
 export declare function rgbToHex({ r, g, b }: Rgb): string;
 export declare function rgbToHsl({ r, g, b }: Rgb): Hsl;

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

@@ -1,10 +1,5 @@
 "use strict";
-/**
- * Pure color math. No dependencies, no platform APIs — safe for the mobile port.
- *
- * Used by `buildDarkPalette` to derive dark ramps from each brand's own light colors,
- * and to assert contrast in tests.
- */
+// Pure color math, no dependencies or platform APIs — safe for the mobile port.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hslToHex = exports.hexToHsl = void 0;
 exports.hexToRgb = hexToRgb;
@@ -18,15 +13,7 @@ exports.mix = mix;
 exports.relativeLuminance = relativeLuminance;
 exports.contrastRatio = contrastRatio;
 const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
-/**
- * Accepts `#rgb` or `#rrggbb` only. An `#rrggbbaa` throws ON PURPOSE.
- *
- * The old version silently dropped the alpha and returned the fully-opaque rgb. That made
- * `contrastRatio` score a 16%-alpha hover tint as if it were solid — a measured 4.18 for a fill that
- * actually renders at 1.17 over the canvas, a 3.6x overstatement — with a doc comment saying "alpha
- * ignored" that made it look handled. Alpha over an unknown backdrop has no defined luminance, so the
- * only correct move is to refuse it: composite it first with `compositeOver`, then measure the result.
- */
+// NOTE: #rrggbbaa throws on purpose — alpha over an unknown backdrop has no defined luminance; composite first.
 function hexToRgb(hex) {
     let h = hex.trim().replace(/^#/, "");
     if (h.length === 3)
@@ -49,11 +36,7 @@ function hexToRgba(hex) {
     }
     return { ...hexToRgb(`#${h}`), a: 1 };
 }
-/**
- * Flatten a translucent foreground onto an opaque backdrop — the ONLY way to get a real color for a
- * tint before measuring contrast. `contrastRatio(tint, canvas)` now throws; the correct call is
- * `contrastRatio(compositeOver(tint, canvas), canvas)`.
- */
+// Flattens a translucent foreground onto a backdrop before measuring contrast — contrastRatio(tint, ...) now throws.
 function compositeOver(foreground, backdrop) {
     const f = hexToRgba(foreground);
     const b = hexToRgb(backdrop);

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

@@ -11,19 +11,9 @@ export type FilledSurface = {
     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;
+export declare const solidFillRung: (scale: ColorScale, white: string, canvas?: 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;
+export declare const resolveFilledSurface: (scale: ColorScale, colors: Pick<PaletteProps, "white" | "black" | "backgroundColor" | "background">) => FilledSurface;

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

@@ -3,29 +3,41 @@ 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 outlineRung_1 = require("./outlineRung");
 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.
- */
+// NOTE: "darker than [500]" is [600]/[700] in light but [400]/[300] in dark, since dark ramps run dark -> light.
 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) => {
+// NOTE: walks away from canvas one named rung at a time from 500 — one direction, so hues stay comparable.
+const rungAwayFromCanvas = (scale, canvas) => {
+    const dir = (0, accentText_1.isDarkCanvas)(canvas) ? -1 : 1;
+    let last = 500;
+    for (let i = RUNGS.indexOf(500); i >= 0 && i < RUNGS.length; i += dir) {
+        last = RUNGS[i];
+        if ((0, color_1.contrastRatio)(scale[last], canvas) >= outlineRung_1.AA_NON_TEXT)
+            return last;
+    }
+    return last;
+};
+// Below this a white-labelled fill melts into the surface (zinc dark primary), so ink yields instead.
+const WHITE_FILL_MIN_SURFACE = 2.5;
+const lightestWhiteRung = (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);
+    const passing = RUNGS.filter((r) => (0, color_1.contrastRatio)(scale[r], white) >= accentText_1.AA_NORMAL_TEXT);
     if (!passing.length)
-        return 500;
+        return undefined;
     return passing.reduce((a, b) => (0, color_1.contrastRatio)(scale[a], white) <= (0, color_1.contrastRatio)(scale[b], white) ? a : b);
 };
+// Lightest rung carrying a white label at AA; falls back to stepping away from canvas and letting ink flip.
+const solidFillRung = (scale, white, canvas) => {
+    const whiteRung = lightestWhiteRung(scale, white);
+    if (whiteRung && (!canvas || (0, color_1.contrastRatio)(scale[whiteRung], canvas) >= WHITE_FILL_MIN_SURFACE)) {
+        return whiteRung;
+    }
+    if (!canvas || (0, color_1.contrastRatio)(scale[500], canvas) >= outlineRung_1.AA_NON_TEXT)
+        return 500;
+    return rungAwayFromCanvas(scale, canvas);
+};
 exports.solidFillRung = solidFillRung;
 const steppedRung = (base, canvas, step) => {
     const dir = (0, accentText_1.isDarkCanvas)(canvas) ? -100 : 100;
@@ -33,7 +45,7 @@ const steppedRung = (base, canvas, 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);
+    const base = (0, exports.solidFillRung)(scale, white, canvas);
     if (base === 500) {
         const mode = (0, accentText_1.isDarkCanvas)(canvas) ? "dark" : "light";
         return FILL_STEP_RUNGS[mode][step];
@@ -45,15 +57,13 @@ 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.
- */
+// Consumer-facing helper: fill rung + ink for solid/hover/active. Never pair scale[500] with onFilled by hand.
 const resolveFilledSurface = (scale, colors) => {
-    const { white, black, backgroundColor } = colors;
-    const canvas = backgroundColor.main;
-    const rung = (0, exports.solidFillRung)(scale, white);
+    const { white, black, backgroundColor, background } = colors;
+    const canvas = (0, color_1.contrastRatio)(scale[500], backgroundColor.main) <= (0, color_1.contrastRatio)(scale[500], background[50])
+        ? backgroundColor.main
+        : background[50];
+    const rung = (0, exports.solidFillRung)(scale, white, canvas);
     const fill = scale[rung];
     const hoverRung = (0, exports.darkerFillRung)(scale, canvas, white, 0);
     const hoverFill = scale[hoverRung];

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;