pixelize-design-library 2.4.2-beta.0 → 2.4.2-beta.2

package/dist/esm/Theme/tokens/brands/neutrals.js

@@ -0,0 +1,116 @@
+const semantic = {
+    success: {
+        50: "#e9f8ef",
+        100: "#bbe9cc",
+        200: "#9adeb4",
+        300: "#6ccf92",
+        400: "#4fc67d",
+        500: "#23b85c",
+        600: "#20a754",
+        700: "#198341",
+        800: "#136533",
+        900: "#0f4d27",
+    },
+    error: {
+        50: "#feedeb",
+        100: "#fbc6c2",
+        200: "#f9aaa4",
+        300: "#f6837b",
+        400: "#f56b61",
+        500: "#f2463a",
+        600: "#dc4035",
+        700: "#ac3229",
+        800: "#852720",
+        900: "#661d18",
+    },
+    warning: {
+        50: "#fff4ef",
+        100: "#ffddce",
+        200: "#ffccb7",
+        300: "#ffb596",
+        400: "#ffa781",
+        500: "#ff9162",
+        600: "#e88459",
+        700: "#b56746",
+        800: "#8c5036",
+        900: "#6b3d29",
+    },
+    info: {
+        50: "#eff9fc",
+        100: "#cdedf5",
+        200: "#b5e4f0",
+        300: "#94d7e9",
+        400: "#7fd0e5",
+        500: "#5fc4de",
+        600: "#56b2ea",
+        700: "#438b9e",
+        800: "#346c78",
+        900: "#28525d",
+    },
+};
+const red = {
+    50: "#feedeb", 100: "#fbc6c2", 200: "#f9aaa4", 300: "#f6837b",
+    400: "#f56b61", 500: "#f2463a", 600: "#dc4035", 700: "#ac3229",
+    800: "#852720", 900: "#661d18",
+};
+const orange = {
+    50: "#fff4ef", 100: "#ffddce", 200: "#ffccb7", 300: "#ffb596",
+    400: "#ffa781", 500: "#ff9162", 600: "#e88459", 700: "#b56746",
+    800: "#8c5036", 900: "#6b3d29",
+};
+const yellow = {
+    50: "#fefbec", 100: "#fdf1c5", 200: "#fbeba9", 300: "#fae281",
+    400: "#f9dc69", 500: "#f7d343", 600: "#e1c03d", 700: "#af9630",
+    800: "#887425", 900: "#68591c",
+};
+const green = {
+    50: "#e9f8ef", 100: "#bbe9cc", 200: "#9adeb4", 300: "#6ccf92",
+    400: "#4fc67d", 500: "#23b85c", 600: "#20a754", 700: "#198341",
+    800: "#136533", 900: "#0f4d27",
+};
+const teal = {
+    50: "#eff9fc", 100: "#cdedf5", 200: "#b5e4f0", 300: "#94d7e9",
+    400: "#7fd0e5", 500: "#5fc4de", 600: "#56b2ea", 700: "#438b9e",
+    800: "#346c78", 900: "#28525d",
+};
+const blue = {
+    50: "#ebf8ff", 100: "#bee3f8", 200: "#90cdf4", 300: "#63b3ed",
+    400: "#4299e1", 500: "#3182ce", 600: "#2b6cb0", 700: "#2c5282",
+    800: "#2a4365", 900: "#1a365d",
+};
+const cyan = {
+    50: "#edfdfd", 100: "#c4f1f9", 200: "#9decf9", 300: "#76e4f7",
+    400: "#0bc5ea", 500: "#00b5d8", 600: "#00a3c4", 700: "#0987a0",
+    800: "#086f83", 900: "#065666",
+};
+const purple = {
+    50: "#faf5ff", 100: "#e9d8fd", 200: "#d6bcfa", 300: "#b794f4",
+    400: "#9f7aea", 500: "#805ad5", 600: "#6b46c1", 700: "#553c9a",
+    800: "#44337a", 900: "#322659",
+};
+const pink = {
+    50: "#fff5f7", 100: "#fed7e2", 200: "#fbb6ce", 300: "#f687b3",
+    400: "#ed64a6", 500: "#d53f8c", 600: "#b83280", 700: "#97266d",
+    800: "#702459", 900: "#521b41",
+};
+/** Non-brand shadow tints. Only `primary` is brand-derived. */
+export const sharedBoxShadow = {
+    error: "#F2463A47",
+    default: "#00000033",
+};
+/** Utility scales shared by every brand — never theme-specific. */
+export const neutralTokens = {
+    transparent: "transparent",
+    black: "#000",
+    white: "#fff",
+    semantic,
+    red,
+    orange,
+    yellow,
+    green,
+    teal,
+    blue,
+    cyan,
+    purple,
+    pink,
+};

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

@@ -1,5 +1,6 @@
-import lavenderPalette from "../lavender/palette.light.js";
+import { neutralTokens, sharedBoxShadow } from "../neutrals.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
+import { buildBrandInk } from "../../builders/brandInk.js";
 const PRIMARY_500 = "#cf4e3a"; // warm red (terracotta leaning)
 const primary = {
     50: "#fdf1ee",
@@ -15,7 +16,8 @@ const primary = {
     opacity: buildPrimaryOpacity(PRIMARY_500),
 };
 const palette = {
-    ...lavenderPalette,
+    ...neutralTokens,
+    ...buildBrandInk(PRIMARY_500),
     // Stops retuned so white gradient-button text (onGradient, accentText.ts) clears AA at both
     // ends — the original pair let white drop to 4.37/2.15 against from/to. Same hue, darker.
     // Both nudged one step further (4.509/4.502 -> 4.601/4.617): the first pass cleared AA by
@@ -123,8 +125,7 @@ const palette = {
     },
     boxShadow: {
         primary: buildPrimaryShadowTint(PRIMARY_500),
-        error: lavenderPalette.boxShadow.error,
-        default: lavenderPalette.boxShadow.default,
+        ...sharedBoxShadow,
     },
 };
 export default palette;

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

@@ -1,5 +1,6 @@
-import lavenderPalette from "../lavender/palette.light.js";
+import { neutralTokens, sharedBoxShadow } from "../neutrals.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
+import { buildBrandInk } from "../../builders/brandInk.js";
 const PRIMARY_500 = "#d16a7e"; // muted warm rose (not neon pink)
 const primary = {
     50: "#fdf2f5",
@@ -15,7 +16,8 @@ const primary = {
     opacity: buildPrimaryOpacity(PRIMARY_500),
 };
 const palette = {
-    ...lavenderPalette,
+    ...neutralTokens,
+    ...buildBrandInk(PRIMARY_500),
     // Stops retuned so white gradient-button text (onGradient, accentText.ts) clears AA at both
     // ends — the original pair let white drop to 3.46/2.69 against from/to. Same hue, darker.
     // Both nudged one step further (4.520/4.505 -> 4.609/4.607): the first pass cleared AA by
@@ -127,8 +129,7 @@ const palette = {
     },
     boxShadow: {
         primary: buildPrimaryShadowTint(PRIMARY_500),
-        error: lavenderPalette.boxShadow.error,
-        default: lavenderPalette.boxShadow.default,
+        ...sharedBoxShadow,
     },
 };
 export default palette;

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

@@ -1,5 +1,6 @@
-import lavenderPalette from "../lavender/palette.light.js";
+import { neutralTokens, sharedBoxShadow } from "../neutrals.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
+import { buildBrandInk } from "../../builders/brandInk.js";
 const PRIMARY_500 = "#1a3a6b"; // was #0088cc — deep navy
 const primary = {
     50: "#e8ecf4",
@@ -15,7 +16,8 @@ const primary = {
     opacity: buildPrimaryOpacity(PRIMARY_500),
 };
 const palette = {
-    ...lavenderPalette,
+    ...neutralTokens,
+    ...buildBrandInk(PRIMARY_500),
     // `to` stop retuned so white gradient-button text (onGradient, accentText.ts) clears AA — the
     // original let white drop to 2.14 there (`from` already passed at 11.28, unchanged).
     // Nudged one step further (4.515 -> 4.600): the first pass cleared AA by <0.02, too thin a
@@ -121,8 +123,7 @@ const palette = {
     },
     boxShadow: {
         primary: buildPrimaryShadowTint(PRIMARY_500),
-        error: lavenderPalette.boxShadow.error,
-        default: lavenderPalette.boxShadow.default,
+        ...sharedBoxShadow,
     },
 };
 export default palette;

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

@@ -1,5 +1,6 @@
-import lavenderPalette from "../lavender/palette.light.js";
+import { neutralTokens, sharedBoxShadow } from "../neutrals.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
+import { buildBrandInk } from "../../builders/brandInk.js";
 const PRIMARY_500 = "#6b7280"; // was #475569 — pure neutral gray, no blue cast
 const primary = {
     50: "#f9fafb",
@@ -15,7 +16,8 @@ const primary = {
     opacity: buildPrimaryOpacity(PRIMARY_500),
 };
 const palette = {
-    ...lavenderPalette,
+    ...neutralTokens,
+    ...buildBrandInk(PRIMARY_500),
     // `to` stop retuned so white gradient-button text (onGradient, accentText.ts) clears AA — the
     // original let white drop to 2.98 there (`from` already passed at 4.83, unchanged).
     // Nudged one step further (4.520 -> 4.608): the first pass cleared AA by <0.02, too thin a
@@ -102,7 +104,7 @@ const palette = {
             200: "#f1f1f3",
             300: "#ebebed",
             400: "#e5e5e8",
-            500: "#dfdfе2",
+            500: "#dfdfe2",
             600: "#cbcbcf",
             700: "#a0a0a5",
             800: "#787880",
@@ -125,8 +127,7 @@ const palette = {
     },
     boxShadow: {
         primary: buildPrimaryShadowTint(PRIMARY_500),
-        error: lavenderPalette.boxShadow.error,
-        default: lavenderPalette.boxShadow.default,
+        ...sharedBoxShadow,
     },
 };
 export default palette;

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

@@ -1,5 +1,6 @@
-import lavenderPalette from "../lavender/palette.light.js";
+import { neutralTokens, sharedBoxShadow } from "../neutrals.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
+import { buildBrandInk } from "../../builders/brandInk.js";
 const PRIMARY_500 = "#004f4b"; // deep spruce teal — storefront/retail brand anchor
 const primary = {
     50: "#eafaf9",
@@ -15,7 +16,8 @@ const primary = {
     opacity: buildPrimaryOpacity(PRIMARY_500),
 };
 const palette = {
-    ...lavenderPalette,
+    ...neutralTokens,
+    ...buildBrandInk(PRIMARY_500),
     // Same hue as primary, darker stop for the "to" end — mirrors emerald's gradient pattern.
     // White gradient-button text verified AA at both stops (4.98 / 6.96).
     gradient: { from: "#0c7d77", to: "#095e90" }, // spruce teal → deep blue
@@ -115,8 +117,7 @@ const palette = {
     },
     boxShadow: {
         primary: buildPrimaryShadowTint(PRIMARY_500),
-        error: lavenderPalette.boxShadow.error,
-        default: lavenderPalette.boxShadow.default,
+        ...sharedBoxShadow,
     },
 };
 export default palette;

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

@@ -1,6 +1,6 @@
 import { buildDarkPalette } from "../../builders/buildDarkPalette.js";
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "../../builders/buildBrandTokens.js";
-import { pickAccentText } from "../../builders/accentText.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
@@ -192,7 +192,8 @@ const palette = {
     placeholder,
     disabled,
     table,
-    accentText: pickAccentText(primary, derived.backgroundColor.main, "dark"),
+    accentText: pickAccentText(primary, derived.backgroundColor.main),
+    onPrimary: onFilled(PRIMARY_500, derived.white, derived.black),
     boxShadow: {
         primary: buildPrimaryShadowTint(PRIMARY_500),
         error: derived.boxShadow.error,

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

@@ -2,19 +2,11 @@ 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;
 /**
- * Rungs to try, ordered nearest-to-accent first. `primary[500]` is the true brand accent, so
- * it is always tried first and only stepped away from when it fails AA — that keeps brand
- * identity as strong as contrast allows instead of flattening every brand to one safe rung.
- *
- * Light canvases need darker rungs; dark canvases need lighter ones. Both walk 500 -> 900 because
- * BOTH ramps put their light end at 900: light mode runs light -> dark (so 900 is the darkest),
- * while every dark scale runs dark -> light (so 900 is the lightest). Same direction, opposite
- * meaning — walking 500 -> 100 for dark would step toward the canvas and land at ~1.4 contrast.
+ * 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.
  */
-const SEARCH_ORDER = {
-    light: [500, 600, 700, 800, 900],
-    dark: [500, 600, 700, 800, 900],
-};
+const SEARCH_ORDER = [500, 600, 700, 800, 900];
 /**
  * Pick the accent rung to use for accent-COLORED TEXT sitting on the canvas.
  *
@@ -32,20 +24,9 @@ const SEARCH_ORDER = {
  * 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`.
  */
-export const pickAccentText = (primary, canvas, mode) => {
-    const safeInk = () => (contrastRatio("#ffffff", canvas) >= AA_NORMAL_TEXT ? "#ffffff" : "#000000");
-    if (!primary)
-        return safeInk();
-    const order = SEARCH_ORDER[mode];
-    const found = order.find((rung) => primary[rung] != null && contrastRatio(primary[rung], canvas) >= AA_NORMAL_TEXT);
-    if (found !== undefined)
-        return primary[found];
-    for (let i = order.length - 1; i >= 0; i--) {
-        const rung = primary[order[i]];
-        if (rung != null)
-            return rung;
-    }
-    return safeInk();
+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]];
 };
 /** Canvas assumed when no Pixelize theme is mounted. Never painted; only fed to contrast math. */
 export const DEFAULT_CANVAS = "#ffffff";
@@ -64,7 +45,7 @@ export const isDarkCanvas = (canvas) => relativeLuminance(canvas) < DARK_CANVAS_
  * 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.
  */
-export const accentTextOnCanvas = (scale, canvas) => pickAccentText(scale, canvas, relativeLuminance(canvas) < DARK_CANVAS_LUMINANCE ? "dark" : "light");
+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

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

@@ -0,0 +1,103 @@
+import { buildPrimaryOpacity } from "./buildBrandTokens.js";
+import { hexToHsl, 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;
+const SECONDARY = {
+    50: [39.4, 0.8231],
+    100: [41.0, 0.61132],
+    200: [37.7, 0.39479],
+    300: [27.4, 0.18614],
+    400: [28.4, 0.10269],
+    500: [52.4, 0.00831],
+    600: [55.1, 0.00573],
+    700: [55.6, 0.00386],
+    800: [60.0, 0.00245],
+    900: [57.1, 0.00141],
+};
+const TEXT = {
+    50: [25.9, 0.86267],
+    100: [32.4, 0.63853],
+    200: [32.7, 0.48344],
+    300: [30.6, 0.30607],
+    400: [29.2, 0.21515],
+    500: [26.3, 0.10787],
+    600: [26.6, 0.08786],
+    700: [26.7, 0.05281],
+    800: [27.4, 0.03145],
+    900: [29.0, 0.01826],
+};
+const HEADER = {
+    50: [31.3, 0.83382],
+    100: [31.0, 0.59779],
+    200: [30.6, 0.44729],
+    300: [29.3, 0.27622],
+    400: [30.0, 0.19238],
+    500: [29.9, 0.10467],
+    600: [29.9, 0.08682],
+    700: [29.7, 0.05281],
+    800: [29.1, 0.0319],
+    900: [29.9, 0.01915],
+};
+const PLACEHOLDER = {
+    50: [30.4, 0.87913],
+    100: [35.4, 0.67128],
+    200: [36.1, 0.53513],
+    300: [34.7, 0.37333],
+    400: [31.4, 0.30462],
+    500: [28.2, 0.19307],
+    600: [22.8, 0.15818],
+    700: [22.0, 0.09196],
+    800: [21.5, 0.05448],
+    900: [22.3, 0.03206],
+};
+const DISABLED = {
+    50: [33.3, 0.90353],
+    100: [38.9, 0.80618],
+    200: [40.7, 0.71546],
+    300: [41.0, 0.60545],
+    400: [39.6, 0.53328],
+    500: [40.5, 0.43688],
+    600: [28.2, 0.35566],
+    700: [13.4, 0.20289],
+    800: [11.4, 0.1171],
+    900: [11.2, 0.06724],
+};
+// Lightness is monotonic in luminance for a fixed hue/saturation, so bisection converges.
+const atLuminance = (anchor, saturation, target) => {
+    let low = 0;
+    let high = 100;
+    for (let i = 0; i < 30; i += 1) {
+        const mid = (low + high) / 2;
+        if (relativeLuminance(withLightness(anchor, mid, saturation)) < target)
+            low = mid;
+        else
+            high = mid;
+    }
+    return withLightness(anchor, (low + high) / 2, saturation);
+};
+const ramp = (anchor, profile) => {
+    const ratio = hexToHsl(anchor).s / REFERENCE_SATURATION;
+    const scale = {};
+    for (const rung of RUNGS) {
+        const [saturation, luminance] = profile[rung];
+        scale[rung] = atLuminance(anchor, Math.min(100, saturation * ratio), luminance);
+    }
+    return scale;
+};
+const brandRamp = (anchor, profile) => {
+    const scale = ramp(anchor, profile);
+    return { ...scale, opacity: buildPrimaryOpacity(scale[500]) };
+};
+/** Brand-hued ink ramps at lavender's verified luminances, so contrast carries over. */
+export function buildBrandInk(primary500) {
+    const secondary = brandRamp(primary500, SECONDARY);
+    return {
+        secondary,
+        tertiary: { ...secondary },
+        text: ramp(primary500, TEXT),
+        header: ramp(primary500, HEADER),
+        placeholder: ramp(primary500, PLACEHOLDER),
+        disabled: ramp(primary500, DISABLED),
+    };
+}

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

@@ -1,6 +1,9 @@
 import { buildPrimaryOpacity, buildPrimaryShadowTint } from "./buildBrandTokens.js";
 import { contrastRatio, hexToHsl, hslToHex, withLightness } from "./color.js";
-import { pickAccentText } from "./accentText.js";
+import { pickAccentText, onFilled } from "./accentText.js";
+import { withSidebarTokens } from "./sidebarAccent.js";
+import { buildMutedText } from "./mutedText.js";
+import { buildSemanticText, buildOnSemantic } from "./semanticText.js";
 /**
  * Derives a brand's dark palette from its light palette.
  *
@@ -235,6 +238,12 @@ export function buildDarkPalette(light) {
     ]));
     const white = light.white;
     const primary = liftBrand(light.primary, white);
+    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),
+    };
     return {
         ...light,
         // Brand identity: hue preserved, accent lifted as far as the white label allows.
@@ -242,12 +251,7 @@ export function buildDarkPalette(light) {
         secondary: liftBrand(light.secondary, white),
         tertiary: liftBrand(light.tertiary, white),
         gradient: light.gradient,
-        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),
-        },
+        semantic,
         // `white` stays white on purpose: it is the label color on filled buttons.
         transparent: light.transparent,
         black: light.black,
@@ -276,9 +280,13 @@ export function buildDarkPalette(light) {
         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, "dark"),
+        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),
         // Sidebar is already near-black in light mode, so it needs no inversion.
-        sidebar: light.sidebar,
+        sidebar: withSidebarTokens(light),
         boxShadow: {
             primary: buildPrimaryShadowTint(primary[500]),
             error: light.boxShadow.error,

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

@@ -0,0 +1,5 @@
+import { liftToContrast } from "./outlineRung.js";
+/** WCAG 1.4.3 — muted is still body text. */
+export const AA_NORMAL_TEXT = 4.5;
+/** Seeded from the ramp's muted rung so brand tint survives, then lifted until it clears AA. */
+export const buildMutedText = (text, canvas) => liftToContrast(text[400], canvas, AA_NORMAL_TEXT);

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

@@ -1,5 +1,4 @@
-import { contrastRatio, hexToHsl, withLightness } from "./color.js";
-import { isDarkCanvas } from "./accentText.js";
+import { contrastRatio, hexToHsl, relativeLuminance, withLightness } from "./color.js";
 /**
  * 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.
@@ -9,23 +8,27 @@ export const MIN_PERCEPTIBLE_STEP = 1.15;
 /** WCAG 1.4.11 — a control outline is a UI component boundary, held to 3:1. */
 export const AA_NON_TEXT = 3;
 /**
- * Walks a hex toward `target` contrast against `backdrop`, keeping its hue and saturation so the
- * result still reads as the same colour. Darkens when `mode` is light, lightens when dark, and
- * stops at the FIRST passing step so nothing overshoots to black or white.
+ * 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 function liftToContrast(hex, backdrop, mode, target = AA_NON_TEXT) {
+export function liftToContrast(hex, backdrop, target = AA_NON_TEXT) {
     if (contrastRatio(hex, backdrop) >= target)
         return hex;
-    const { s } = hexToHsl(hex);
-    const step = mode === "dark" ? 1 : -1;
-    let { l } = hexToHsl(hex);
-    while (l > 0 && l < 100) {
-        l += step;
-        const next = withLightness(hex, l, s);
-        if (contrastRatio(next, backdrop) >= target)
-            return next;
+    const { s, l: start } = hexToHsl(hex);
+    const away = relativeLuminance(backdrop) < 0.5 ? 1 : -1;
+    for (const step of [away, -away]) {
+        let l = start;
+        while (l > 0 && l < 100) {
+            l += step;
+            const next = withLightness(hex, l, s);
+            if (contrastRatio(next, backdrop) >= target)
+                return next;
+        }
     }
-    return withLightness(hex, mode === "dark" ? 100 : 0, s);
+    const ends = [withLightness(hex, 100, s), withLightness(hex, 0, s)];
+    return contrastRatio(ends[0], backdrop) >= contrastRatio(ends[1], backdrop) ? ends[0] : ends[1];
 }
 /**
  * `boxborder[500]` is the rung every control outline reads (Checkbox, SearchSelect, the date
@@ -36,7 +39,7 @@ export function liftToContrast(hex, backdrop, mode, target = AA_NON_TEXT) {
  * `border[*]` is deliberately untouched — that ramp draws table gridlines, which are decorative
  * and outside 1.4.11.
  */
-export function withOutlineRung(palette, mode) {
+export 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.
@@ -44,7 +47,7 @@ export function withOutlineRung(palette, mode) {
         contrastRatio(current, palette.background[50])
         ? palette.backgroundColor.main
         : palette.background[50];
-    const resolved = liftToContrast(current, backdrop, mode);
+    const resolved = liftToContrast(current, backdrop);
     if (resolved === current)
         return palette;
     return { ...palette, boxborder: { ...palette.boxborder, 500: resolved } };
@@ -58,6 +61,5 @@ export function withOutlineRung(palette, mode) {
  * its OWN list background, not necessarily the page canvas.
  */
 export function resolveHoverTint(seed, restSurface) {
-    const mode = isDarkCanvas(restSurface) ? "dark" : "light";
-    return liftToContrast(seed, restSurface, mode, MIN_PERCEPTIBLE_STEP);
+    return liftToContrast(seed, restSurface, MIN_PERCEPTIBLE_STEP);
 }

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

@@ -0,0 +1,20 @@
+import { liftToContrast, AA_NON_TEXT } from "./outlineRung.js";
+import { AA_NORMAL_TEXT } from "./accentText.js";
+/** Placeholder text measured 4.32:1 on a card for 8 of 9 brands — text, so held to 4.5:1. */
+export function withPlaceholderRung(palette) {
+    const resolved = liftToContrast(palette.placeholder[500], palette.background[50], AA_NORMAL_TEXT);
+    if (resolved === palette.placeholder[500])
+        return palette;
+    return { ...palette, placeholder: { ...palette.placeholder, 500: resolved } };
+}
+/** The hover row is a SURFACE, so it steps away from the ink rather than the ink moving. */
+export function withTableHoverRung(palette) {
+    const resolved = liftToContrast(palette.table.hover[500], palette.text[500], AA_NORMAL_TEXT);
+    if (resolved === palette.table.hover[500])
+        return palette;
+    return {
+        ...palette,
+        table: { hover: { ...palette.table.hover, 500: resolved } },
+    };
+}
+export { AA_NON_TEXT };

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

@@ -0,0 +1,17 @@
+import { liftToContrast } from "./outlineRung.js";
+import { AA_NORMAL_TEXT, onFilled } from "./accentText.js";
+export const SEMANTIC_TONES = ["success", "error", "warning", "info"];
+/**
+ * `semantic[tone][500]` is a FILL rung — as ink on a light canvas it measures 1.84-3.68:1 across
+ * every brand. Each tone is stepped here until it clears AA as text, so a call site that wants
+ * "error-coloured text" cannot pick the unreadable one.
+ */
+export const buildSemanticText = (semantic, canvas) => SEMANTIC_TONES.reduce((acc, tone) => {
+    acc[tone] = liftToContrast(semantic[tone][500], canvas, AA_NORMAL_TEXT);
+    return acc;
+}, {});
+/** Ink ON the fill, not on the canvas — the pair a CSS module needs but cannot compute. */
+export const buildOnSemantic = (semantic, white, black) => SEMANTIC_TONES.reduce((acc, tone) => {
+    acc[tone] = onFilled(semantic[tone][500], white, black);
+    return acc;
+}, {});

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

@@ -0,0 +1,23 @@
+import { compositeOver } from "./color.js";
+import { liftToContrast, resolveHoverTint, AA_NON_TEXT } from "./outlineRung.js";
+import { buildSemanticText } from "./semanticText.js";
+/** WCAG 1.4.3 — the active label is normal-size text. */
+export const AA_NORMAL_TEXT = 4.5;
+/** Lightest surface an active row reaches: Chakra `whiteAlpha.400` (0.24) on hover. */
+export const ACTIVE_SURFACE_TINT = "#ffffff3d";
+export const sidebarActiveSurface = (background) => compositeOver(ACTIVE_SURFACE_TINT, background[500]);
+/** The rail never inverts, so both modes take the accent from the LIGHT primary. */
+export const buildSidebarTokens = (background, lightPrimary, semantic) => {
+    const surface = sidebarActiveSurface(background);
+    const elevated = resolveHoverTint(background[500], background[500]);
+    return {
+        background,
+        elevated,
+        activeIcon: liftToContrast(lightPrimary[300], surface, AA_NON_TEXT),
+        activeLabel: liftToContrast(lightPrimary[100], surface, AA_NORMAL_TEXT),
+        mutedIcon: liftToContrast(background[300], elevated, AA_NON_TEXT),
+        mutedLabel: liftToContrast(background[100], elevated, AA_NORMAL_TEXT),
+        semanticText: buildSemanticText(semantic, elevated),
+    };
+};
+export const withSidebarTokens = (source) => buildSidebarTokens(source.sidebar.background, source.primary, source.semantic);