pixelize-design-library 2.4.2 → 3.0.0

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

@@ -8,27 +8,12 @@ const accentText_1 = require("./accentText");
 const sidebarAccent_1 = require("./sidebarAccent");
 const mutedText_1 = require("./mutedText");
 const semanticText_1 = require("./semanticText");
-/**
- * Derives a brand's dark palette from its light palette.
- *
- * Every value is computed from the brand's OWN hue, so each brand keeps its identity in
- * dark mode instead of collapsing onto one shared grey.
- *
- * Three different strategies are used, because a single rule gives wrong results:
- *
- * - **Structural ramps** (surfaces, text, borders) are rebuilt at explicit lightness
- *   targets around the brand hue. They are NOT simply reversed: the light ramps bottom out
- *   around 35% lightness, which is nowhere near dark enough for a dark-mode canvas.
- * - **Utility hue ramps** (red/green/…) are reversed, so index roles survive: `red.50` is a
- *   pale badge background in light and becomes a deep one in dark, while `red.900` flips to
- *   near-white for text on it.
- * - **Brand + semantic ramps** are shifted one step lighter, preserving hue while lifting
- *   the accent to a legible lightness against a dark canvas.
- *
- * `white`, `black` and `transparent` are deliberately untouched — `white` is a *text* color
- * on filled buttons (see `Button.styles.ts`), not a surface. Components that use `white` as a
- * surface are migrated to a surface token instead.
- */
+const focusRing_1 = require("./focusRing");
+const surfaceRaised_1 = require("./surfaceRaised");
+const star_1 = require("./star");
+const planes_1 = require("./planes");
+// Structural ramps are rebuilt at explicit targets (not reversed — light ramps bottom near 35%);
+// utility hues are reversed so index roles survive; brand/semantic ramps shift one step lighter.
 const SCALE_KEYS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
 const fromTargets = (hueSource, targets, saturation) => {
     const { h } = (0, color_1.hexToHsl)(hueSource);
@@ -70,23 +55,11 @@ exports.shiftLighter = shiftLighter;
 const WHITE_LABEL_TARGET = 4.5;
 const MAX_ACCENT_LIGHTNESS = 85;
 const LIGHTNESS_STEP = 0.5;
-/**
- * How much lighter this accent can go in dark mode.
- *
- * An accent faces two opposing constraints: lighter reads better against a dark canvas, but
- * worse under the white label of a solid button. There is no single rung that satisfies both
- * for all seven brands, so this maximizes canvas contrast subject to keeping the white label
- * legible.
- *
- * The floor is `min(AA, whatLightModeAlreadyShips)`: emerald and rosewood already ship white
- * labels below AA in light mode, so demanding AA here would force their brand color to change.
- * Dark is held to "no worse than light", never stricter.
- */
+// NOTE: floor is min(AA, light mode's own contrast) — dark is held to "no worse than light", never stricter.
 const accentLightnessDelta = (accent500, white) => {
     const originalL = (0, color_1.hexToHsl)(accent500).l;
     const floor = Math.min(WHITE_LABEL_TARGET, (0, color_1.contrastRatio)(white, accent500));
     let best = originalL;
-    // Contrast against white falls monotonically as lightness rises, so stop at the first miss.
     for (let l = originalL; l <= MAX_ACCENT_LIGHTNESS; l += LIGHTNESS_STEP) {
         if ((0, color_1.contrastRatio)(white, (0, color_1.withLightness)(accent500, l)) < floor)
             break;
@@ -104,32 +77,11 @@ const liftScale = (scale, delta) => {
     return out;
 };
 exports.liftScale = liftScale;
-/**
- * Dark-ramp endpoints for a brand/semantic scale.
- *
- * `[50]`/`[100]` are the SUBTLE TINT rungs — chips, avatars, ghost hovers. On a dark canvas they
- * must be dark, not near-white. `[800]`/`[900]` are the STRONG rungs and get read as text, so on
- * a dark canvas they must be light. Both roles invert versus light mode.
- */
+// [50]/[100] are subtle-tint rungs (dark on a dark canvas); [800]/[900] read as text (light). Inverts light mode.
 const BRAND_DARK_MIN_L = 12;
 const BRAND_DARK_MAX_L = 93;
-/** Rung order, used to interpolate lightness on each side of the pinned accent. */
 const RUNG_ORDER = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
 const ACCENT_INDEX = RUNG_ORDER.indexOf(500);
-/**
- * Rebuild a scale as a proper DARK ramp: monotonically dark -> light across 50 -> 900, with `[500]`
- * pinned to the accent.
- *
- * Replaces a flat lift for brand/semantic scales. A flat lift adds the same delta to every rung, so
- * `[50]` stayed near-white (it clamps at L97) and `[600]`+ stayed DARKER than the accent — which is
- * wrong in both directions on a dark canvas: the tint rungs painted white chips, and components
- * that use `[600]` as text (e.g. Accordion) rendered dark-on-dark at ~1.3 contrast.
- *
- * Interpolating around the pinned accent (rather than using fixed lightness targets) keeps the ramp
- * monotonic for every brand, whatever lightness that brand's accent lands on. Hue and saturation are
- * taken from the light scale's OWN matching rung, so each brand keeps its character and its tint
- * rungs stay as desaturated as they were designed to be.
- */
 const toDarkRamp = (scale, accentHex) => {
     const accentL = (0, color_1.hexToHsl)(accentHex).l;
     const out = {};
@@ -139,12 +91,10 @@ const toDarkRamp = (scale, accentHex) => {
             l = accentL;
         }
         else if (i < ACCENT_INDEX) {
-            // 50 -> just below the accent.
             const t = i / ACCENT_INDEX;
             l = BRAND_DARK_MIN_L + (accentL - BRAND_DARK_MIN_L) * t;
         }
         else {
-            // Just above the accent -> 900.
             const t = (i - ACCENT_INDEX) / (RUNG_ORDER.length - 1 - ACCENT_INDEX);
             l = accentL + (BRAND_DARK_MAX_L - accentL) * t;
         }
@@ -172,9 +122,7 @@ const TEXT_TARGETS = {
 const PLACEHOLDER_TARGETS = {
     50: 25, 100: 30, 200: 35, 300: 42, 400: 48, 500: 54, 600: 60, 700: 66, 800: 72, 900: 80,
 };
-// Rung 200 is the default hairline. At L18 it sat 5 points off a card at L13 — below the
-// perceptible step, so dark cards read as edgeless. L22 draws the same 1.2x edge the light
-// ramp does, which is what makes a card look like a card in either mode.
+// NOTE: rung 200 is the default hairline — held at L22, above the perceptible step off an L13 card.
 const BORDER_TARGETS = {
     50: 14, 100: 18, 200: 22, 300: 24, 400: 26, 500: 27, 600: 33, 700: 42, 800: 52, 900: 62,
 };
@@ -184,29 +132,11 @@ const DISABLED_TARGETS = {
 const TABLE_HOVER_TARGETS = {
     50: 9, 100: 11, 200: 13, 300: 15, 400: 17, 500: 19, 600: 24, 700: 32, 800: 42, 900: 52,
 };
-/**
- * `gray[500]` is the library's de-facto muted-text token (~43 call sites), so its rung is set by
- * contrast, not by an even ramp — and it must clear AA against the LIGHTEST named surface it can
- * land on, not merely against the canvas. Tuning it to the canvas alone is what shipped the first
- * two misses: L48 measured 4.18 on the canvas, then L52 cleared the canvas (4.81) but still failed
- * on every surface above `secondary` (3.39 on `muted`). L64 clears all of them (5.66 worst case).
- *
- * That lands on shadcn's own answer independently: its dark `muted-foreground` is zinc-400
- * (#a1a1aa, L65) against a near-black canvas. Ours is #a49ea9 — same lightness, brand hue kept.
- * Rungs at/below 400 stay decorative (borders, dividers, disabled) and are not held to text AA.
- */
+// NOTE: gray[500] is the de-facto muted-text token — tuned to clear AA on the lightest named surface, not just the canvas.
 const GRAY_TARGETS = {
     50: 10, 100: 14, 200: 22, 300: 32, 400: 48, 500: 64, 600: 72, 700: 79, 800: 86, 900: 93,
 };
-/**
- * Named surface lightness. Elevation INVERTS versus light mode: in light, `muted`/`accent`
- * are the strongest tints away from white; in dark, "stronger" means lighter than the canvas.
- *
- * The top of the ramp is deliberately compressed (accent 18->17, muted 20->18): dark elevation
- * reads through small lightness steps plus borders, so a wide spread just looks washed out rather
- * than layered. `light`/`tertiary` share a rung by design (they are aliases); no other pair may,
- * or that step of elevation silently disappears.
- */
+// NOTE: elevation inverts vs light mode — "stronger" surfaces get lighter than the canvas, not darker.
 const NAMED_SURFACE_L = {
     main: 7,
     base: 8,
@@ -221,23 +151,36 @@ const NAMED_SURFACE_L = {
     accent: 17,
     muted: 18,
 };
-/**
- * Surfaces are hue-NEUTRAL in dark: every brand shares one canvas, so switching theme recolors the
- * accents and nothing else. Tinting them instead (this was 14) made a full-screen wash — Meadow's
- * whole app read green — which reads as a different product per brand rather than a different
- * accent. Light mode keeps its tinted canvas; there the tint is a hint on white, not the whole
- * screen. Brand identity in dark lives in `primary`/semantic/text, which stay hued.
- */
+// NOTE: surfaces are hue-neutral on every brand; brand hue stays on accents, ink and rules.
 const SURFACE_SAT = 0;
 const TEXT_SAT = 12;
 const PLACEHOLDER_SAT = 10;
 const BORDER_SAT = 12;
 const DISABLED_SAT = 8;
-// Neutral for the same reason as SURFACE_SAT — gray's low rungs ARE surfaces, and a tinted ramp
-// on a neutral canvas reads as a mismatch. It also buys back the contrast the neutral canvas
-// cost: `gray[400]` on `muted` was 2.99 on lavender/zinc at sat 6, and is 3.16 at 0.
 const GRAY_SAT = 0;
-function buildDarkPalette(light) {
+// Fill rungs drawn ON a card keep their step above it, so they rise with the card; ink and chrome rungs stay.
+const BACKGROUND_FILLS = [100, 200, 300, 400, 500];
+// NOTE: table.hover[500] gates every ink (it is a named surface), so it climbs one rung per step, not the card's full rise.
+const TABLE_HOVER_ABOVE_CARD = {
+    50: 1, 100: 3, 200: 5, 300: 6, 400: 6.5, 500: 7,
+};
+const GRAY_FILLS = [50, 100, 200];
+const raise = (targets, rungs, by) => ({
+    ...targets,
+    ...Object.fromEntries(rungs.map((k) => [k, targets[k] + by])),
+});
+const cardPlane = (canvas, white, planes) => {
+    if (planes === "flat")
+        return { card: canvas, rise: 0, tableHover: TABLE_HOVER_TARGETS };
+    const card = (0, planes_1.lift)(white, canvas, planes_1.CARD_LIFT);
+    const cardL = (0, color_1.hexToHsl)(card).l;
+    const tableHover = {
+        ...TABLE_HOVER_TARGETS,
+        ...Object.fromEntries(Object.entries(TABLE_HOVER_ABOVE_CARD).map(([k, step]) => [k, cardL + step])),
+    };
+    return { card, rise: cardL - (0, color_1.hexToHsl)(canvas).l, tableHover };
+};
+function buildDarkPalette(light, { planes = "lifted" } = {}) {
     const hueSource = light.primary[500];
     const { h } = (0, color_1.hexToHsl)(hueSource);
     const namedSurfaces = Object.fromEntries(Object.entries(NAMED_SURFACE_L).map(([key, l]) => [
@@ -245,27 +188,32 @@ function buildDarkPalette(light) {
         (0, color_1.hslToHex)({ h, s: SURFACE_SAT, l }),
     ]));
     const white = light.white;
+    const { card, rise, tableHover } = cardPlane(namedSurfaces.main, white, planes);
     const primary = liftBrand(light.primary, white);
+    const background = {
+        ...fromTargets(hueSource, raise(SURFACE_TARGETS, BACKGROUND_FILLS, rise), SURFACE_SAT),
+        50: card,
+    };
     const semantic = {
         success: liftAccent(light.semantic.success, white),
         error: liftAccent(light.semantic.error, white),
         warning: liftAccent(light.semantic.warning, white),
         info: liftAccent(light.semantic.info, white),
     };
+    // border/boxborder are one divider ramp — see CHROME-CONSISTENCY.md.
+    const dividerRamp = fromTargets(hueSource, BORDER_TARGETS, BORDER_SAT);
     return {
         ...light,
-        // Brand identity: hue preserved, accent lifted as far as the white label allows.
         primary,
         secondary: liftBrand(light.secondary, white),
         tertiary: liftBrand(light.tertiary, white),
         gradient: light.gradient,
         semantic,
-        // `white` stays white on purpose: it is the label color on filled buttons.
+        // NOTE: white stays white on purpose — it is the label color on filled buttons, not a surface.
         transparent: light.transparent,
         black: light.black,
         white: light.white,
-        // Utility hues keep their meaning; only the light/dark role of each index flips.
-        gray: fromTargets(hueSource, GRAY_TARGETS, GRAY_SAT),
+        gray: fromTargets(hueSource, raise(GRAY_TARGETS, GRAY_FILLS, rise), GRAY_SAT),
         red: (0, exports.reverseScale)(light.red),
         orange: (0, exports.reverseScale)(light.orange),
         yellow: (0, exports.reverseScale)(light.yellow),
@@ -276,24 +224,24 @@ 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),
-        border: fromTargets(hueSource, BORDER_TARGETS, BORDER_SAT),
-        boxborder: fromTargets(hueSource, BORDER_TARGETS, BORDER_SAT),
-        // Neutral: a row hover is a surface fill, and across a full table its tint is exactly the
-        // brand wash the canvas was changed to avoid.
-        table: { hover: fromTargets(hueSource, TABLE_HOVER_TARGETS, SURFACE_SAT) },
+        border: dividerRamp,
+        boxborder: dividerRamp,
+        table: {
+            hover: fromTargets(hueSource, tableHover, SURFACE_SAT),
+        },
         disabled: fromTargets(hueSource, DISABLED_TARGETS, DISABLED_SAT),
-        // Derived from the LIFTED accent against the dark canvas: the lift stops at the white-label
-        // floor (~4.55), which leaves primary[500] short of AA as text, so text needs its own rung.
         accentText: (0, accentText_1.pickAccentText)(primary, namedSurfaces.main),
         textMuted: (0, mutedText_1.buildMutedText)(fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT), namedSurfaces.main),
         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),
-        // Sidebar is already near-black in light mode, so it needs no inversion.
+        focusRing: (0, focusRing_1.buildFocusRing)({ primary, background, backgroundColor: namedSurfaces }),
+        surfaceRaised: (0, surfaceRaised_1.buildSurfaceRaised)({ backgroundColor: namedSurfaces, background, white }, (0, surfaceRaised_1.filledMarks)({ primary, semantic })),
+        star: (0, star_1.buildStar)(namedSurfaces.main),
         sidebar: (0, sidebarAccent_1.withSidebarTokens)(light),
         boxShadow: {
             primary: (0, buildBrandTokens_1.buildPrimaryShadowTint)(primary[500]),

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,4 @@
 "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.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hslToHex = exports.hexToHsl = void 0;
 exports.hexToRgb = hexToRgb;
@@ -17,16 +11,10 @@ exports.withLightness = withLightness;
 exports.mix = mix;
 exports.relativeLuminance = relativeLuminance;
 exports.contrastRatio = contrastRatio;
+// Pure color math, no dependencies or platform APIs — safe for the mobile port.
+const memo_1 = require("./memo");
 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 +37,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);
@@ -137,14 +121,17 @@ function mix(a, b, weight) {
         b: ca.b + (cb.b - ca.b) * w,
     });
 }
+const linearChannel = (v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+};
+const luminanceOf = (0, memo_1.memoize)((hex) => {
+    const { r, g, b } = hexToRgb(hex);
+    return 0.2126 * linearChannel(r) + 0.7152 * linearChannel(g) + 0.0722 * linearChannel(b);
+}, (hex) => hex, 4096);
 /** WCAG 2.1 relative luminance. */
 function relativeLuminance(hex) {
-    const { r, g, b } = hexToRgb(hex);
-    const channel = (v) => {
-        const c = v / 255;
-        return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
-    };
-    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+    return luminanceOf(hex);
 }
 /** WCAG 2.1 contrast ratio, 1–21. AA body text needs >= 4.5. */
 function contrastRatio(a, b) {

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

@@ -0,0 +1,25 @@
+import type { ColorScale, PaletteProps } from "../types";
+/** Resolved fill + ink for a solid surface, including hover/active steps. */
+export type FilledSurface = {
+    rung: keyof ColorScale;
+    fill: string;
+    color: string;
+    hoverRung: keyof ColorScale;
+    hoverFill: string;
+    hoverColor: string;
+    activeRung: keyof ColorScale;
+    activeFill: string;
+    activeColor: string;
+};
+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`. A step may not
+ * flip the label's side of AA (zinc dark: near-white fill, black ink) or fall below `CHROME_BORDER`
+ * against the canvas (a pressed warning solid used to reach 1.00:1 on the card).
+ */
+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;
+type SurfaceColors = Pick<PaletteProps, "white" | "black" | "backgroundColor" | "background">;
+export declare const resolveFilledSurface: (scale: ColorScale, colors: SurfaceColors) => FilledSurface;
+export {};

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

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFilledSurface = exports.labelOnFill = exports.darkerFillRung = exports.solidFillRung = void 0;
+const color_1 = require("./color");
+const accentText_1 = require("./accentText");
+const outlineRung_1 = require("./outlineRung");
+const memo_1 = require("./memo");
+const RUNGS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+// 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] };
+// 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) => (0, color_1.contrastRatio)(scale[r], white) >= accentText_1.AA_NORMAL_TEXT);
+    if (!passing.length)
+        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) ? -1 : 1;
+    const index = RUNGS.indexOf(base) + dir * step;
+    return RUNGS[Math.min(RUNGS.length - 1, Math.max(0, index))];
+};
+const steppedTowardBase = (from, base) => RUNGS[RUNGS.indexOf(from) + (from > base ? -1 : 1)];
+/**
+ * Hover (step 0) or active (step 1) fill rung, one step darker than `solidFillRung`. A step may not
+ * flip the label's side of AA (zinc dark: near-white fill, black ink) or fall below `CHROME_BORDER`
+ * against the canvas (a pressed warning solid used to reach 1.00:1 on the card).
+ */
+const darkerFillRung = (scale, canvas, white, step) => {
+    const base = (0, exports.solidFillRung)(scale, white, canvas);
+    const wantsWhite = (0, color_1.contrastRatio)(white, scale[base]) >= accentText_1.AA_NORMAL_TEXT;
+    const holds = (rung) => (0, color_1.contrastRatio)(scale[rung], canvas) >= outlineRung_1.CHROME_BORDER &&
+        ((0, color_1.contrastRatio)(white, scale[rung]) >= accentText_1.AA_NORMAL_TEXT) === wantsWhite;
+    let rung;
+    if (base === 500) {
+        const mode = (0, accentText_1.isDarkCanvas)(canvas) ? "dark" : "light";
+        rung = FILL_STEP_RUNGS[mode][step];
+    }
+    else {
+        rung = steppedRung(base, canvas, step === 0 ? 1 : 2);
+    }
+    while (rung !== base && !holds(rung))
+        rung = steppedTowardBase(rung, base);
+    return rung;
+};
+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;
+const filledSurfaceMemo = (0, memo_1.memoize)((scale, white, black, main, card) => {
+    const canvas = (0, color_1.contrastRatio)(scale[500], main) <= (0, color_1.contrastRatio)(scale[500], card) ? main : card;
+    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];
+    const activeRung = (0, exports.darkerFillRung)(scale, canvas, white, 1);
+    const activeFill = scale[activeRung];
+    return {
+        rung,
+        fill,
+        color: (0, exports.labelOnFill)(fill, white, black),
+        hoverRung,
+        hoverFill,
+        hoverColor: (0, exports.labelOnFill)(hoverFill, white, black),
+        activeRung,
+        activeFill,
+        activeColor: (0, exports.labelOnFill)(activeFill, white, black),
+    };
+}, (scale, white, black, main, card) => `${(0, memo_1.scaleKey)(scale)}|${white}|${black}|${main}|${card}`);
+const resolveFilledSurface = (scale, colors) => ({
+    ...filledSurfaceMemo(scale, colors.white, colors.black, colors.backgroundColor.main, colors.background[50]),
+});
+exports.resolveFilledSurface = resolveFilledSurface;

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

@@ -0,0 +1,7 @@
+import type { FocusRingTokens, PaletteProps } from "../types";
+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">;
+export declare const focusRingBackdrops: (source: FocusRingSource) => string[];
+export declare const buildFocusRing: (source: FocusRingSource) => FocusRingTokens;
+export declare const withFocusRing: (palette: PaletteProps) => PaletteProps;

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

@@ -0,0 +1,51 @@
+"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");
+const planeStep_1 = require("./planeStep");
+/** Same lightness granularity `buildDarkPalette` walks its accents at. */
+const LIGHTNESS_STEP = 0.5;
+// 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))
+        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;
+    }
+    // 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];
+}
+// NOTE: canvas, card and the table header band — including the fill or every named surface leaves no solvable hue.
+const focusRingBackdrops = (source) => [
+    source.backgroundColor.main,
+    source.background[50],
+    source.backgroundColor.tableHeader,
+    (0, planeStep_1.bandOn)(source.backgroundColor.tableHeader, source.background[50]),
+];
+exports.focusRingBackdrops = focusRingBackdrops;
+// 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 {
+        halo,
+        ring: settleBetween(source.primary[500], [...(0, exports.focusRingBackdrops)(source), halo]),
+    };
+};
+exports.buildFocusRing = buildFocusRing;
+// 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),
+});
+exports.withFocusRing = withFocusRing;

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

@@ -3,6 +3,12 @@ export * from "./buildBrandTokens";
 export * from "./buildDarkPalette";
 export * from "./chartColorsFromTheme";
 export * from "./color";
+export * from "./focusRing";
 export * from "./scrollbar";
 export * from "./gradientInk";
 export * from "./placeholderInk";
+export * from "./tone";
+export * from "./scrim";
+export * from "./tooltipSurface";
+export * from "./surfaceRaised";
+export * from "./star";