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

package/dist/esm/Theme/tokens/brands/slate/palette.light.js

@@ -20,23 +20,13 @@ const palette = {
     ...buildBrandInk(PRIMARY_500),
     gradient: { from: "#666d7a", to: "#4a4e59" },
     primary,
-    tertiary: { ...primary },
     gray: {
         50: "#f9fafb",
         100: "#f3f4f6",
         200: "#e5e7eb",
         300: "#d1d5db",
         400: "#9ca3af",
-        // Retuned to clear AA with a safe >=4.6 margin (not the bare 4.5 cutoff — a value that
-        // clears AA by <0.02 is treated as failing, see Wave D QA follow-up) against every
-        // backgroundColor surface it's actually rendered on (main/secondary/light/subtle —
-        // verified via usage grep). muted/accent/tertiary/etc. have 0-1 live call sites today and
-        // none pair them with gray[500] text; going dark enough to also clear those would push
-        // past gray[600]'s own lightness and break the ramp order.
-        //
-        // First pass (#6a707e) measured 4.509 against `secondary` — a 0.009 margin, too thin to
-        // trust (same failure mode as the gradient-stop retune). Darkened ~0.7 lightness points
-        // (hue/saturation preserved) to restore the safe margin below.
+        // NOTE: retuned to a safe >=4.6 AA margin — first pass (#6a707e) measured 4.509, too thin a margin to trust.
         500: "#686e7c",
         600: "#4b5563",
         700: "#374151",

package/dist/esm/Theme/tokens/brands/storefront/palette.dark.js

@@ -1,8 +1,4 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import light from "./palette.light.js";
-/**
- * Dark palette for the storefront brand, derived from its own light palette so the brand hue
- * carries through. Override individual tokens here if this brand needs a bespoke dark value.
- */
 const palette = buildDarkPalette(light);
 export default palette;

package/dist/esm/Theme/tokens/brands/zinc/palette.dark.js

@@ -1,26 +1,9 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
+import { rotateScaleHue } from "../../builders/brandInk.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
 import { pickAccentText, onFilled } from "../../builders/accentText.js";
 import light from "./palette.light.js";
-/**
- * zinc dark is the shadcn dark look and INVERTS the primary: the filled button is near-white
- * `#e4e4e7` carrying a `#18181b` label (13.96:1) — the opposite of every other brand, whose dark
- * primary stays a lifted version of its own hue. `#e4e4e7` is shadcn's actual dark-mode `--primary`
- * (verified against shadcn's live zinc theme registry, 2026-07-18) — a shade dimmer than pure
- * `#fafafa`, which is shadcn's `--foreground` (default body text), not `--primary`. The generic
- * `buildDarkPalette` derivation would only lift zinc's near-black accent to a mid grey (a light
- * label's floor), so `primary`/`secondary`/`background` (numeric ramp)/`text`/`header`/`gray`/
- * `border`/`boxborder`/`placeholder`/`disabled`/`table` are pinned here as explicit literals ported
- * verbatim from Mobile-Components, matching shadcn's own dark palette as closely as web's token
- * shape allows.
- *
- * `backgroundColor` (named surfaces) and `sidebar` are the two fields left to `...derived` instead
- * of a literal port — see the comment above the `palette` object for why.
- *
- * `accentText` is recomputed against the OVERRIDDEN `primary` and `derived.backgroundColor.main`,
- * not spread from `derived` — the generic derivation's `accentText` was picked for the generic
- * (wrong) lifted primary and would be stale once `primary` is replaced below.
- */
+// NOTE: zinc dark INVERTS the primary (near-white fill, dark label) to match shadcn — every other brand lifts its own hue instead. Most ramps below are literals ported from Mobile-Components.
 const derived = buildDarkPalette(light);
 const PRIMARY_500 = "#e4e4e7";
 const SECONDARY_500 = "#a1a1aa";
@@ -87,11 +70,7 @@ const header = {
     800: "#fefefe",
     900: "#ffffff",
 };
-// muted-foreground = gray[500] = #a1a1aa (5.81:1 on the #27272a muted surface); it also serves
-// as the focus ring on the #09090b canvas (7.76:1). gray[400] = the interactive border/icon rung,
-// and is the one value here NOT ported verbatim: it is pinned to whatever clears the 3:1 non-text
-// bar on the LIGHTEST named surface, which is derived rather than ported. shadcn's own #71717a
-// measures 2.81 there, so this sits two steps lighter (3.19).
+// NOTE: gray[400] is the one value here NOT ported verbatim — pinned to clear the 3:1 non-text bar (shadcn's own measures 2.81).
 const gray = {
     50: "#18181b",
     100: "#27272a",
@@ -172,17 +151,8 @@ const palette = {
     gradient: { from: PRIMARY_500, to: "#a1a1aa" },
     primary,
     secondary,
-    tertiary: { ...secondary },
-    // `backgroundColor` (named surfaces) and `sidebar` are deliberately NOT overridden with
-    // mobile's literal values: mobile's zinc names 5 groups of surfaces onto the same hex each
-    // (e.g. quaternary/medium/neutral all "#18181b"), which violates web's "every named surface
-    // is a visually distinct elevation step" invariant (`darkSurfaces.test.ts`) that every other
-    // brand is held to. Falling through to `...derived` runs zinc through the SAME generic
-    // `NAMED_SURFACE_L` staircase every other brand uses — zinc's hue is ~240deg/near-zero
-    // saturation, so the result is visually the same cool neutral, just with distinct steps.
-    // `sidebar` similarly falls through to `derived.sidebar` (== `light.sidebar`, non-inverting)
-    // rather than mobile's separately-tuned dark sidebar, matching the "sidebar never inverts"
-    // invariant every other web brand relies on (including this session's own SideBar accent fix).
+    tertiary: { ...rotateScaleHue(secondary), opacity: secondary.opacity },
+    // NOTE: backgroundColor/sidebar fall through to `...derived` — mobile's literals collapse distinct elevation steps, breaking darkSurfaces.test.ts.
     background,
     text,
     header,

package/dist/esm/Theme/tokens/brands/zinc/palette.light.js

@@ -1,15 +1,6 @@
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
-/**
- * zinc — the shadcn-clone brand already shipped on Mobile-Components (the mobile design
- * library's own default brand). These exact hexes are ported verbatim from mobile's
- * `src/theme/tokens/brands/zinc/palette.light.ts` — the mobile file's own comment calls them
- * "the shared source of truth: web is adopting them verbatim" — so every rung here is
- * authoritative, not an approximation or a rehue.
- *
- * Unlike every other web brand, zinc's filled primary is the near-black anchor itself:
- * `primary[500]` is `#18181b`, a white label lands at 16.97:1. `background[50]` is the literal
- * canvas white as a real surface token, never a hardcoded `"white"`.
- */
+import { rotateScaleHue } from "../../builders/brandInk.js";
+// NOTE: hexes ported verbatim from Mobile-Components' zinc (the shadcn-clone brand) — authoritative, not an approximation.
 const PRIMARY_500 = "#18181b";
 const SECONDARY_500 = "#71717a";
 const primary = {
@@ -38,7 +29,7 @@ const secondary = {
     900: "#18181b",
     opacity: buildPrimaryOpacity(SECONDARY_500),
 };
-const tertiary = { ...secondary };
+const tertiary = { ...rotateScaleHue(secondary), opacity: secondary.opacity };
 // Shared status ramps — identical across every brand (status is universal, brand is the hue).
 const semantic = {
     success: {

package/dist/esm/Theme/tokens/builders/accentText.js

@@ -1,29 +1,9 @@
 import { contrastRatio, relativeLuminance } from "./color.js";
 /** WCAG AA for normal-size text. Accent-as-text must clear this against the canvas. */
 const AA_NORMAL_TEXT = 4.5;
-/**
- * Ordered nearest-to-accent first, so brand identity survives as far as contrast allows.
- * One order serves both modes: light ramps run light -> dark and dark ramps run dark -> light,
- * so 500 -> 900 always steps AWAY from that mode's own canvas.
- */
+// NOTE: 500->900 order, since light ramps run light->dark and dark ramps dark->light — always steps away from canvas.
 const SEARCH_ORDER = [500, 600, 700, 800, 900];
-/**
- * Pick the accent rung to use for accent-COLORED TEXT sitting on the canvas.
- *
- * `primary[500]` cannot serve both roles: it must stay dark enough for a white label on a
- * filled button (>=4.5) yet be light enough to read as text on a dark canvas (>=4.5). Those
- * constraints are mutually exclusive at a single lightness, so text gets its own token.
- *
- * Falls back to the most extreme rung when no candidate clears AA, so the result is always a
- * real brand color rather than a throw. If `primary` itself is missing (a caller rendered
- * outside a Pixelize theme, so the scale never got merged in), there is no brand rung to pick
- * from at all — fall back to whichever of white/black clears AA against `canvas`, using the
- * same proven-always-safe math as `onFilled` below, rather than throwing on `primary[rung]`.
- *
- * `ColorScale` requires every rung 50-900, but a caller can still hand in a partial object (a
- * sparse test theme mock, a hand-built scale) — treat a missing rung as "doesn't clear AA" and
- * keep walking rather than crashing `contrastRatio` on `undefined`.
- */
+// NOTE: primary[500] can't serve both a filled-button label and canvas text at one lightness — text gets its own rung.
 export const pickAccentText = (primary, canvas) => {
     const found = SEARCH_ORDER.find((rung) => contrastRatio(primary[rung], canvas) >= AA_NORMAL_TEXT);
     return primary[found !== null && found !== void 0 ? found : SEARCH_ORDER[SEARCH_ORDER.length - 1]];
@@ -37,33 +17,10 @@ export const DEFAULT_BLACK = "#000000";
 const DARK_CANVAS_LUMINANCE = 0.2;
 /** True when `canvas` is a dark surface. Lets style configs branch without threading color mode. */
 export const isDarkCanvas = (canvas) => relativeLuminance(canvas) < DARK_CANVAS_LUMINANCE;
-/**
- * Accent text color for any scale (primary, secondary, red, …) drawn on `canvas`.
- *
- * Held to AA in BOTH modes. This deliberately no longer returns light's `[500]` untouched: that
- * concession existed only while light mode was frozen for consumers, and it shipped known AA
- * failures (radiant 4.15, emerald 3.24, rosewood 3.29). Those brands now step to the nearest rung
- * that clears AA, which changes their light pixels — the accepted cost of meeting WCAG.
- */
+// NOTE: held to AA in both modes now — some brands' light [500] no longer passes through untouched.
 export const accentTextOnCanvas = (scale, canvas) => pickAccentText(scale, canvas);
-/**
- * Ink for text drawn ON a filled swatch (a button/tag/badge fill), not the canvas. `white`/`black`
- * must be the mode-stable absolutes (`theme.colors.white` / `theme.colors.black`) — NOT a
- * mode-adaptive token like `text[900]`, which is dark ink in light mode but near-white in dark and
- * would silently flip which candidate is "the dark one" depending on mode.
- *
- * Provably always clears AA: brute-forcing the sRGB cube shows `max(contrast(white,X),
- * contrast(black,X)) >= 4.583` for every X, so whichever of the two fails, the other clears 4.5 —
- * this never needs to step the fill's rung. Prefers white first (brand-conventional look) and
- * only falls back to black when white itself fails.
- */
+// NOTE: white/black must be the mode-stable absolutes, not an adaptive token — always clears AA.
 export const onFilled = (fill, white, black) => contrastRatio(white, fill) >= AA_NORMAL_TEXT ? white : black;
-/**
- * Ink for text on a two-stop gradient fill. Picks `onFilled` against whichever stop is LIGHTER —
- * the harder case for either ink to clear. Each brand's `gradient` token is tuned so this
- * resolves to the same ink at both ends (see palette.light.ts `gradient` comments); a caller
- * that overrides the gradient (e.g. `UpgradeButton`'s `gradient` prop) isn't guaranteed the same
- * safety, since an arbitrary pair can still need different inks at each end.
- */
+// NOTE: resolves against whichever gradient stop is lighter — the harder case for ink to clear.
 export const onGradient = (from, to, white, black) => onFilled(relativeLuminance(from) >= relativeLuminance(to) ? from : to, white, black);
 export { AA_NORMAL_TEXT, DARK_CANVAS_LUMINANCE };

package/dist/esm/Theme/tokens/builders/brandInk.js

@@ -1,5 +1,5 @@
 import { buildPrimaryOpacity } from "./buildBrandTokens.js";
-import { hexToHsl, relativeLuminance, withLightness } from "./color.js";
+import { hexToHsl, hslToHex, relativeLuminance, withLightness } from "./color.js";
 const RUNGS = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
 // Lavender's primary saturation. Each brand's ramps scale away from it.
 const REFERENCE_SATURATION = 55.5;
@@ -63,6 +63,12 @@ const DISABLED = {
     800: [11.4, 0.1171],
     900: [11.2, 0.06724],
 };
+// Material 3's tertiary: a rotated accent. Same luminances as secondary, so contrast is unchanged.
+const TERTIARY_HUE_SHIFT = 60;
+const rotateHue = (hex, degrees) => {
+    const { h, s, l } = hexToHsl(hex);
+    return hslToHex({ h: (h + degrees + 360) % 360, s, l });
+};
 // Lightness is monotonic in luminance for a fixed hue/saturation, so bisection converges.
 const atLuminance = (anchor, saturation, target) => {
     let low = 0;
@@ -85,6 +91,16 @@ const ramp = (anchor, profile) => {
     }
     return scale;
 };
+/** Rotates a scale's hue while restoring each rung's luminance, so contrast is untouched. */
+export const rotateScaleHue = (scale, degrees = TERTIARY_HUE_SHIFT) => {
+    const rotated = {};
+    for (const rung of RUNGS) {
+        const hex = scale[rung];
+        const turned = rotateHue(hex, degrees);
+        rotated[rung] = atLuminance(turned, hexToHsl(turned).s, relativeLuminance(hex));
+    }
+    return rotated;
+};
 const brandRamp = (anchor, profile) => {
     const scale = ramp(anchor, profile);
     return { ...scale, opacity: buildPrimaryOpacity(scale[500]) };
@@ -94,7 +110,7 @@ export function buildBrandInk(primary500) {
     const secondary = brandRamp(primary500, SECONDARY);
     return {
         secondary,
-        tertiary: { ...secondary },
+        tertiary: brandRamp(rotateHue(primary500, TERTIARY_HUE_SHIFT), SECONDARY),
         text: ramp(primary500, TEXT),
         header: ramp(primary500, HEADER),
         placeholder: ramp(primary500, PLACEHOLDER),

package/dist/esm/Theme/tokens/builders/buildBrandTokens.js

@@ -1,6 +1,4 @@
-/**
- * Builds 8-digit hex alpha tokens from a 6-digit brand color (Chakra primary.500).
- */
+// Builds 8-digit hex alpha tokens from a 6-digit brand color (Chakra primary.500).
 export function normalizeHex(hex) {
     const trimmed = hex.trim();
     const withHash = trimmed.startsWith("#") ? trimmed : `#${trimmed}`;

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

@@ -5,27 +5,9 @@ import { withSidebarTokens } from "./sidebarAccent.js";
 import { buildMutedText } from "./mutedText.js";
 import { buildSemanticText, buildOnSemantic } from "./semanticText.js";
 import { buildFocusRing } from "./focusRing.js";
-/**
- * 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.
- */
+import { buildSurfaceRaised } from "./surfaceRaised.js";
+// 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 } = hexToHsl(hueSource);
@@ -65,23 +47,11 @@ export const shiftLighter = (scale) => ({
 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.
 export const accentLightnessDelta = (accent500, white) => {
     const originalL = hexToHsl(accent500).l;
     const floor = Math.min(WHITE_LABEL_TARGET, 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 (contrastRatio(white, withLightness(accent500, l)) < floor)
             break;
@@ -97,32 +67,11 @@ export const liftScale = (scale, delta) => {
     }
     return out;
 };
-/**
- * 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 = hexToHsl(accentHex).l;
     const out = {};
@@ -132,12 +81,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;
         }
@@ -165,9 +112,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,
 };
@@ -177,29 +122,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,
@@ -214,21 +141,12 @@ 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 in dark (a tint wash reads as a different product per brand); accent lives in primary/semantic/text.
 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;
 export function buildDarkPalette(light) {
     const hueSource = light.primary[500];
@@ -246,19 +164,19 @@ export function buildDarkPalette(light) {
         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),
         red: reverseScale(light.red),
         orange: reverseScale(light.orange),
@@ -274,23 +192,17 @@ export function buildDarkPalette(light) {
         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.
+        border: dividerRamp,
+        boxborder: dividerRamp,
         table: { hover: fromTargets(hueSource, TABLE_HOVER_TARGETS, 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: pickAccentText(primary, namedSurfaces.main),
         textMuted: buildMutedText(fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT), namedSurfaces.main),
         semanticText: buildSemanticText(semantic, namedSurfaces.main),
         onPrimary: onFilled(primary[500], light.white, light.black),
         onSemantic: buildOnSemantic(semantic, light.white, light.black),
-        // The dark ring is derived from the LIFTED accent against the dark canvas, not copied from
-        // light: the two modes squeeze it from opposite sides, so a shared value fails one of them.
         focusRing: buildFocusRing({ primary, background, backgroundColor: namedSurfaces }),
-        // Sidebar is already near-black in light mode, so it needs no inversion.
+        surfaceRaised: buildSurfaceRaised({ backgroundColor: namedSurfaces, background, white }),
         sidebar: withSidebarTokens(light),
         boxShadow: {
             primary: buildPrimaryShadowTint(primary[500]),

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

@@ -1,12 +1,5 @@
 import { isDarkCanvas, onFilled } from "./accentText.js";
-/**
- * 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.
 export const CATEGORICAL_SERIES = {
     light: ["#009068", "#3177dc", "#5a8b00", "#8b5dce", "#9b7300", "#af4da9", "#cb4a2a", "#009d82"],
     dark: ["#00976d", "#377ee3", "#5f9200", "#9163d5", "#a27900", "#b654b0", "#d25030", "#00aa8e"],

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

@@ -1,19 +1,6 @@
-/**
- * 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.
 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.
 export function hexToRgb(hex) {
     let h = hex.trim().replace(/^#/, "");
     if (h.length === 3)
@@ -36,11 +23,7 @@ export 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.
 export function compositeOver(foreground, backdrop) {
     const f = hexToRgba(foreground);
     const b = hexToRgb(backdrop);

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

@@ -1,35 +1,47 @@
 import { contrastRatio } from "./color.js";
 import { AA_NORMAL_TEXT, isDarkCanvas, onFilled } from "./accentText.js";
+import { AA_NON_TEXT } from "./outlineRung.js";
 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.
- */
-export 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 = isDarkCanvas(canvas) ? -1 : 1;
+    let last = 500;
+    for (let i = RUNGS.indexOf(500); i >= 0 && i < RUNGS.length; i += dir) {
+        last = RUNGS[i];
+        if (contrastRatio(scale[last], canvas) >= 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 (contrastRatio(scale[500], white) >= AA_NORMAL_TEXT)
         return 500;
-    const passing = RUNGS.filter((r) => scale[r] && contrastRatio(scale[r], white) >= AA_NORMAL_TEXT);
+    const passing = RUNGS.filter((r) => contrastRatio(scale[r], white) >= AA_NORMAL_TEXT);
     if (!passing.length)
-        return 500;
+        return undefined;
     return passing.reduce((a, b) => contrastRatio(scale[a], white) <= 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.
+export const solidFillRung = (scale, white, canvas) => {
+    const whiteRung = lightestWhiteRung(scale, white);
+    if (whiteRung && (!canvas || contrastRatio(scale[whiteRung], canvas) >= WHITE_FILL_MIN_SURFACE)) {
+        return whiteRung;
+    }
+    if (!canvas || contrastRatio(scale[500], canvas) >= AA_NON_TEXT)
+        return 500;
+    return rungAwayFromCanvas(scale, canvas);
+};
 const steppedRung = (base, canvas, step) => {
     const dir = isDarkCanvas(canvas) ? -100 : 100;
     return Math.min(900, Math.max(50, base + dir * step));
 };
 /** Hover (step 0) or active (step 1) fill rung, one step darker than `solidFillRung`. */
 export const darkerFillRung = (scale, canvas, white, step) => {
-    const base = solidFillRung(scale, white);
+    const base = solidFillRung(scale, white, canvas);
     if (base === 500) {
         const mode = isDarkCanvas(canvas) ? "dark" : "light";
         return FILL_STEP_RUNGS[mode][step];
@@ -39,15 +51,13 @@ export const darkerFillRung = (scale, canvas, white, step) => {
 };
 /** Label ink for a specific fill swatch — always `onFilled`, exported for style configs. */
 export const labelOnFill = (fill, white, black) => onFilled(fill, white, black);
-/**
- * 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.
 export const resolveFilledSurface = (scale, colors) => {
-    const { white, black, backgroundColor } = colors;
-    const canvas = backgroundColor.main;
-    const rung = solidFillRung(scale, white);
+    const { white, black, backgroundColor, background } = colors;
+    const canvas = contrastRatio(scale[500], backgroundColor.main) <= contrastRatio(scale[500], background[50])
+        ? backgroundColor.main
+        : background[50];
+    const rung = solidFillRung(scale, white, canvas);
     const fill = scale[rung];
     const hoverRung = darkerFillRung(scale, canvas, white, 0);
     const hoverFill = scale[hoverRung];