pixelize-design-library 2.4.1 → 2.4.2-beta.1

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

@@ -0,0 +1,203 @@
+import { buildDarkPalette } from "../../builders/buildDarkPalette.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.
+ */
+const derived = buildDarkPalette(light);
+const PRIMARY_500 = "#e4e4e7";
+const SECONDARY_500 = "#a1a1aa";
+const primary = {
+    50: "#18181b",
+    100: "#27272a",
+    200: "#3f3f46",
+    300: "#52525b",
+    400: "#a1a1aa",
+    500: PRIMARY_500,
+    600: "#fbfbfb",
+    700: "#fcfcfc",
+    800: "#fefefe",
+    900: "#ffffff",
+    opacity: buildPrimaryOpacity(PRIMARY_500),
+};
+const secondary = {
+    50: "#18181b",
+    100: "#27272a",
+    200: "#3f3f46",
+    300: "#52525b",
+    400: "#71717a",
+    500: SECONDARY_500,
+    600: "#b4b4bb",
+    700: "#d4d4d8",
+    800: "#e4e4e7",
+    900: "#fafafa",
+    opacity: buildPrimaryOpacity(SECONDARY_500),
+};
+// background[50] = the elevated surface (#0e0e11), resolved through a token, not a literal.
+const background = {
+    50: "#0e0e11",
+    100: "#131316",
+    200: "#18181b",
+    300: "#212124",
+    400: "#27272a",
+    500: "#3f3f46",
+    600: "#52525b",
+    700: "#71717a",
+    800: "#a1a1aa",
+    900: "#d4d4d8",
+};
+const text = {
+    50: "#71717a",
+    100: "#8a8a93",
+    200: "#a1a1aa",
+    300: "#b4b4bb",
+    400: "#d4d4d8",
+    500: "#fafafa",
+    600: "#fbfbfb",
+    700: "#fcfcfc",
+    800: "#fefefe",
+    900: "#ffffff",
+};
+const header = {
+    50: "#8a8a93",
+    100: "#a1a1aa",
+    200: "#c4c4c9",
+    300: "#d4d4d8",
+    400: "#e4e4e7",
+    500: "#fafafa",
+    600: "#fbfbfb",
+    700: "#fcfcfc",
+    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).
+const gray = {
+    50: "#18181b",
+    100: "#27272a",
+    200: "#3f3f46",
+    300: "#52525b",
+    400: "#7a7a83",
+    500: "#a1a1aa",
+    600: "#b4b4bb",
+    700: "#d4d4d8",
+    800: "#e4e4e7",
+    900: "#f4f4f5",
+};
+// border[200] = decorative (#27272a); border[500] = interactive outline (#6b6b75, 3.78:1 on canvas).
+const border = {
+    50: "#18181b",
+    100: "#212124",
+    200: "#27272a",
+    300: "#3f3f46",
+    400: "#52525b",
+    500: "#6b6b75",
+    600: "#8a8a93",
+    700: "#a1a1aa",
+    800: "#d4d4d8",
+    900: "#e4e4e7",
+};
+const boxborder = {
+    50: "#18181b",
+    100: "#212124",
+    200: "#27272a",
+    300: "#3f3f46",
+    400: "#52525b",
+    500: "#6b6b75",
+    600: "#8a8a93",
+    700: "#a1a1aa",
+    800: "#d4d4d8",
+    900: "#e4e4e7",
+};
+const placeholder = {
+    50: "#3f3f46",
+    100: "#52525b",
+    200: "#6b6b75",
+    300: "#71717a",
+    400: "#8a8a93",
+    500: "#a1a1aa",
+    600: "#b4b4bb",
+    700: "#c4c4c9",
+    800: "#d4d4d8",
+    900: "#e4e4e7",
+};
+const disabled = {
+    50: "#18181b",
+    100: "#212124",
+    200: "#27272a",
+    300: "#3f3f46",
+    400: "#4a4a52",
+    500: "#52525b",
+    600: "#6b6b75",
+    700: "#8a8a93",
+    800: "#a1a1aa",
+    900: "#d4d4d8",
+};
+const table = {
+    hover: {
+        50: "#0e0e11",
+        100: "#131316",
+        200: "#18181b",
+        300: "#1f1f22",
+        400: "#27272a",
+        500: "#2f2f33",
+        600: "#3f3f46",
+        700: "#52525b",
+        800: "#71717a",
+        900: "#a1a1aa",
+    },
+};
+const palette = {
+    ...derived,
+    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).
+    background,
+    text,
+    header,
+    gray,
+    border,
+    boxborder,
+    placeholder,
+    disabled,
+    table,
+    accentText: pickAccentText(primary, derived.backgroundColor.main),
+    onPrimary: onFilled(PRIMARY_500, derived.white, derived.black),
+    boxShadow: {
+        primary: buildPrimaryShadowTint(PRIMARY_500),
+        error: derived.boxShadow.error,
+        default: "#00000080",
+    },
+};
+export default palette;

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

@@ -0,0 +1,381 @@
+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"`.
+ */
+const PRIMARY_500 = "#18181b";
+const SECONDARY_500 = "#71717a";
+const primary = {
+    50: "#f4f4f5",
+    100: "#e4e4e7",
+    200: "#d4d4d8",
+    300: "#a1a1aa",
+    400: "#3f3f46",
+    500: PRIMARY_500,
+    600: "#141417",
+    700: "#101013",
+    800: "#0c0c0e",
+    900: "#09090b",
+    opacity: buildPrimaryOpacity(PRIMARY_500),
+};
+const secondary = {
+    50: "#fafafa",
+    100: "#f4f4f5",
+    200: "#e4e4e7",
+    300: "#d4d4d8",
+    400: "#a1a1aa",
+    500: SECONDARY_500,
+    600: "#52525b",
+    700: "#3f3f46",
+    800: "#27272a",
+    900: "#18181b",
+    opacity: buildPrimaryOpacity(SECONDARY_500),
+};
+const tertiary = { ...secondary };
+// Shared status ramps — identical across every brand (status is universal, brand is the hue).
+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 gray = {
+    50: "#fafafa",
+    100: "#f4f4f5",
+    200: "#e4e4e7",
+    300: "#d4d4d8",
+    400: "#a1a1aa",
+    500: "#71717a",
+    600: "#52525b",
+    700: "#3f3f46",
+    800: "#27272a",
+    900: "#18181b",
+};
+// Shared utility hues — same values as every brand.
+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",
+};
+const backgroundColor = {
+    main: "#ffffff",
+    secondary: "#fafafa",
+    tertiary: "#f4f4f5",
+    quaternary: "#e4e4e7",
+    light: "#ffffff",
+    medium: "#f4f4f5",
+    accent: "#e4e4e7",
+    subtle: "#fafafa",
+    muted: "#f4f4f5",
+    neutral: "#f4f4f5",
+    base: "#fafafa",
+    tableHeader: "#f4f4f5",
+};
+// background[50] is the elevated-surface token and must BE the literal canvas colour (#ffffff),
+// so a "white surface" resolves through a token, never a hardcoded "white".
+const background = {
+    50: "#ffffff",
+    100: "#fafafa",
+    200: "#f4f4f5",
+    300: "#e4e4e7",
+    400: "#d4d4d8",
+    500: "#a1a1aa",
+    600: "#71717a",
+    700: "#52525b",
+    800: "#3f3f46",
+    900: "#27272a",
+};
+const text = {
+    50: "#a1a1aa",
+    100: "#71717a",
+    200: "#52525b",
+    300: "#3f3f46",
+    400: "#27272a",
+    500: "#18181b",
+    600: "#141417",
+    700: "#101013",
+    800: "#0c0c0e",
+    900: "#09090b",
+};
+const header = {
+    50: "#71717a",
+    100: "#52525b",
+    200: "#3f3f46",
+    300: "#27272a",
+    400: "#1f1f22",
+    500: "#18181b",
+    600: "#121215",
+    700: "#0e0e11",
+    800: "#0b0b0d",
+    900: "#09090b",
+};
+const placeholder = {
+    50: "#d4d4d8",
+    100: "#a1a1aa",
+    200: "#8a8a93",
+    300: "#71717a",
+    400: "#63636b",
+    500: "#52525b",
+    600: "#47474e",
+    700: "#3f3f46",
+    800: "#27272a",
+    900: "#18181b",
+};
+const boxShadow = {
+    primary: buildPrimaryShadowTint(PRIMARY_500),
+    error: "#F2463A47",
+    default: "#00000033",
+};
+const sidebar = {
+    background: {
+        50: "#d4d4d8",
+        100: "#a1a1aa",
+        200: "#71717a",
+        300: "#52525b",
+        400: "#3f3f46",
+        500: "#18181b",
+        600: "#141417",
+        700: "#101013",
+        800: "#0c0c0e",
+        900: "#09090b",
+    },
+};
+const boxborder = {
+    50: "#fafafa",
+    100: "#f4f4f5",
+    200: "#e4e4e7",
+    300: "#d4d4d8",
+    400: "#c4c4c9",
+    500: "#a1a1aa",
+    600: "#8a8a93",
+    700: "#71717a",
+    800: "#52525b",
+    900: "#3f3f46",
+};
+// border[200] = decorative (#e4e4e7); border[500] = interactive input outline (#8a8a93, 3.42:1 on
+// canvas — a 1px control outline is a UI component under WCAG 1.4.11 and needs 3:1, not 4.5:1).
+const border = {
+    50: "#fafafa",
+    100: "#f4f4f5",
+    200: "#e4e4e7",
+    300: "#d4d4d8",
+    400: "#b4b4bb",
+    500: "#8a8a93",
+    600: "#71717a",
+    700: "#52525b",
+    800: "#3f3f46",
+    900: "#27272a",
+};
+const table = {
+    hover: {
+        50: "#fcfcfc",
+        100: "#fafafa",
+        200: "#f4f4f5",
+        300: "#efeff0",
+        400: "#e9e9eb",
+        500: "#e4e4e7",
+        600: "#d4d4d8",
+        700: "#a1a1aa",
+        800: "#78787f",
+        900: "#5a5a60",
+    },
+};
+const disabled = {
+    50: "#fafafa",
+    100: "#f4f4f5",
+    200: "#e4e4e7",
+    300: "#d4d4d8",
+    400: "#c4c4c9",
+    500: "#a1a1aa",
+    600: "#8a8a93",
+    700: "#71717a",
+    800: "#52525b",
+    900: "#3f3f46",
+};
+const gradient = { from: "#18181b", to: "#52525b" };
+const palette = {
+    gradient,
+    primary,
+    secondary,
+    tertiary,
+    transparent: "transparent",
+    black: "#000",
+    white: "#fff",
+    semantic,
+    gray,
+    red,
+    orange,
+    yellow,
+    green,
+    teal,
+    blue,
+    cyan,
+    purple,
+    pink,
+    backgroundColor,
+    background,
+    text,
+    header,
+    placeholder,
+    boxShadow,
+    sidebar,
+    boxborder,
+    border,
+    table,
+    disabled,
+};
+export default palette;

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

@@ -0,0 +1,69 @@
+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.
+ */
+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`.
+ */
+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";
+/** Mode-stable ink absolutes, used when no theme supplies `colors.white` / `colors.black`. */
+export const DEFAULT_WHITE = "#ffffff";
+export const DEFAULT_BLACK = "#000000";
+/** Below this relative luminance a canvas is treated as dark. Well clear of both real canvases. */
+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.
+ */
+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.
+ */
+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.
+ */
+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/buildBrandTokens.js

@@ -0,0 +1,28 @@
+/**
+ * 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}`;
+    if (!/^#[0-9a-fA-F]{6}$/.test(withHash)) {
+        throw new Error(`Invalid hex color (expected #RRGGBB): ${hex}`);
+    }
+    return withHash.toLowerCase();
+}
+export function buildPrimaryOpacity(primary500) {
+    const h = normalizeHex(primary500);
+    return {
+        4: `${h}0a`,
+        8: `${h}14`,
+        16: `${h}29`,
+        24: `${h}3d`,
+        32: `${h}52`,
+        40: `${h}66`,
+        48: `${h}7a`,
+    };
+}
+/** Tint used for focus rings / primary-tinted shadows (matches ~28% alpha pattern). */
+export function buildPrimaryShadowTint(primary500) {
+    const h = normalizeHex(primary500);
+    return `${h}47`;
+}