pixelize-design-library 3.0.1-beta.1 → 3.1.0

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

@@ -0,0 +1,253 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liftScale = exports.accentLightnessDelta = exports.shiftLighter = exports.reverseScale = void 0;
+exports.buildDarkPalette = buildDarkPalette;
+const buildBrandTokens_1 = require("./buildBrandTokens");
+const color_1 = require("./color");
+const accentText_1 = require("./accentText");
+const sidebarAccent_1 = require("./sidebarAccent");
+const mutedText_1 = require("./mutedText");
+const semanticText_1 = require("./semanticText");
+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);
+    const out = {};
+    for (const k of SCALE_KEYS) {
+        out[k] = (0, color_1.hslToHex)({ h, s: saturation, l: targets[k] });
+    }
+    return out;
+};
+/** Mirrors index roles: 50↔900, 100↔800, 200↔700, 300↔600, 400↔500. */
+const reverseScale = (scale) => ({
+    50: scale[900],
+    100: scale[800],
+    200: scale[700],
+    300: scale[600],
+    400: scale[500],
+    500: scale[400],
+    600: scale[300],
+    700: scale[200],
+    800: scale[100],
+    900: scale[50],
+});
+exports.reverseScale = reverseScale;
+/** Shifts a ramp one step lighter, keeping hue. Used for brand + semantic accents. */
+const shiftLighter = (scale) => ({
+    50: (0, color_1.withLightness)(scale[50], Math.min((0, color_1.hexToHsl)(scale[50]).l + 4, 97)),
+    100: scale[50],
+    200: scale[100],
+    300: scale[200],
+    400: scale[300],
+    500: scale[400],
+    600: scale[500],
+    700: scale[600],
+    800: scale[700],
+    900: scale[800],
+});
+exports.shiftLighter = shiftLighter;
+/** WCAG AA for normal text — the bar for a solid button's white label. */
+const WHITE_LABEL_TARGET = 4.5;
+const MAX_ACCENT_LIGHTNESS = 85;
+const LIGHTNESS_STEP = 0.5;
+// 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;
+    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;
+        best = l;
+    }
+    return best - originalL;
+};
+exports.accentLightnessDelta = accentLightnessDelta;
+/** Raises every rung by the same lightness delta, preserving the ramp's shape and hue. */
+const liftScale = (scale, delta) => {
+    const out = {};
+    for (const k of SCALE_KEYS) {
+        out[k] = (0, color_1.withLightness)(scale[k], Math.min((0, color_1.hexToHsl)(scale[k]).l + delta, 97));
+    }
+    return out;
+};
+exports.liftScale = liftScale;
+// [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;
+const RUNG_ORDER = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900];
+const ACCENT_INDEX = RUNG_ORDER.indexOf(500);
+const toDarkRamp = (scale, accentHex) => {
+    const accentL = (0, color_1.hexToHsl)(accentHex).l;
+    const out = {};
+    RUNG_ORDER.forEach((key, i) => {
+        let l;
+        if (i === ACCENT_INDEX) {
+            l = accentL;
+        }
+        else if (i < ACCENT_INDEX) {
+            const t = i / ACCENT_INDEX;
+            l = BRAND_DARK_MIN_L + (accentL - BRAND_DARK_MIN_L) * t;
+        }
+        else {
+            const t = (i - ACCENT_INDEX) / (RUNG_ORDER.length - 1 - ACCENT_INDEX);
+            l = accentL + (BRAND_DARK_MAX_L - accentL) * t;
+        }
+        const { s } = (0, color_1.hexToHsl)(scale[key]);
+        out[key] = (0, color_1.hslToHex)({ h: (0, color_1.hexToHsl)(accentHex).h, s, l });
+    });
+    return out;
+};
+/** Dark accent scale: accent pinned as light as the white label allows, ramp rebuilt around it. */
+const liftAccent = (scale, white) => {
+    const accent = (0, color_1.withLightness)(scale[500], (0, color_1.hexToHsl)(scale[500]).l + (0, exports.accentLightnessDelta)(scale[500], white));
+    return { ...toDarkRamp(scale, accent), 500: accent };
+};
+const liftBrand = (brand, white) => {
+    const lifted = liftAccent(brand, white);
+    return { ...lifted, opacity: (0, buildBrandTokens_1.buildPrimaryOpacity)(lifted[500]) };
+};
+// Lightness targets per structural ramp. Index roles match light mode; only lightness flips.
+const SURFACE_TARGETS = {
+    50: 7, 100: 9, 200: 11, 300: 14, 400: 17, 500: 21, 600: 30, 700: 45, 800: 60, 900: 75,
+};
+const TEXT_TARGETS = {
+    50: 30, 100: 38, 200: 45, 300: 55, 400: 62, 500: 70, 600: 76, 700: 82, 800: 88, 900: 95,
+};
+const PLACEHOLDER_TARGETS = {
+    50: 25, 100: 30, 200: 35, 300: 42, 400: 48, 500: 54, 600: 60, 700: 66, 800: 72, 900: 80,
+};
+// 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,
+};
+const DISABLED_TARGETS = {
+    50: 14, 100: 18, 200: 22, 300: 26, 400: 30, 500: 34, 600: 42, 700: 52, 800: 62, 900: 72,
+};
+const TABLE_HOVER_TARGETS = {
+    50: 9, 100: 11, 200: 13, 300: 15, 400: 17, 500: 19, 600: 24, 700: 32, 800: 42, 900: 52,
+};
+// 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,
+};
+// NOTE: elevation inverts vs light mode — "stronger" surfaces get lighter than the canvas, not darker.
+const NAMED_SURFACE_L = {
+    main: 7,
+    base: 8,
+    subtle: 10,
+    secondary: 11,
+    tableHeader: 12,
+    light: 13,
+    tertiary: 13,
+    medium: 14,
+    neutral: 15,
+    quaternary: 16,
+    accent: 17,
+    muted: 18,
+};
+// 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;
+const GRAY_SAT = 0;
+// 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]) => [
+        key,
+        (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,
+        primary,
+        secondary: liftBrand(light.secondary, white),
+        tertiary: liftBrand(light.tertiary, white),
+        gradient: light.gradient,
+        semantic,
+        // 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,
+        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),
+        green: (0, exports.reverseScale)(light.green),
+        teal: (0, exports.reverseScale)(light.teal),
+        blue: (0, exports.reverseScale)(light.blue),
+        cyan: (0, exports.reverseScale)(light.cyan),
+        purple: (0, exports.reverseScale)(light.purple),
+        pink: (0, exports.reverseScale)(light.pink),
+        backgroundColor: namedSurfaces,
+        background,
+        text: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT),
+        header: fromTargets(hueSource, TEXT_TARGETS, TEXT_SAT + 2),
+        placeholder: fromTargets(hueSource, PLACEHOLDER_TARGETS, PLACEHOLDER_SAT),
+        border: dividerRamp,
+        boxborder: dividerRamp,
+        table: {
+            hover: fromTargets(hueSource, tableHover, SURFACE_SAT),
+        },
+        disabled: fromTargets(hueSource, DISABLED_TARGETS, DISABLED_SAT),
+        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),
+        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]),
+            error: light.boxShadow.error,
+            default: "#00000080",
+        },
+    };
+}
+exports.default = buildDarkPalette;

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

@@ -0,0 +1,30 @@
+import type { PaletteProps } from "../types";
+export type ThemeColorPalette = PaletteProps;
+export type ChartMode = "light" | "dark";
+export declare const CATEGORICAL_SERIES: Record<ChartMode, readonly string[]>;
+export declare const chartMode: (colors: ThemeColorPalette) => ChartMode;
+export declare function getCategoricalSeriesColors(colors: ThemeColorPalette): string[];
+export declare function getDefaultSeriesColors(colors: ThemeColorPalette): string[];
+/** Ink, grid and surface tokens every chart type shares. */
+export declare function chartInk(colors: ThemeColorPalette): {
+    surface: string;
+    text: string;
+    muted: string;
+    grid: string;
+    axis: string;
+    tooltipBg: string;
+};
+/** Ink for a label drawn on top of a filled mark. Always clears AA. */
+export declare const labelOnSeries: (fill: string, colors: ThemeColorPalette) => string;
+export declare function mergeChartTitleStyle(colors: ThemeColorPalette, titleStyle?: {
+    color?: string;
+    fontSize?: string;
+    fontWeight?: number | string;
+    fontFamily?: string;
+}): {
+    color: string;
+    fontSize: string;
+    fontWeight: number | string;
+    fontFamily: string;
+};
+export declare function chartAxisLabelColor(colors: ThemeColorPalette): string;

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

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.labelOnSeries = exports.chartMode = exports.CATEGORICAL_SERIES = void 0;
+exports.getCategoricalSeriesColors = getCategoricalSeriesColors;
+exports.getDefaultSeriesColors = getDefaultSeriesColors;
+exports.chartInk = chartInk;
+exports.mergeChartTitleStyle = mergeChartTitleStyle;
+exports.chartAxisLabelColor = chartAxisLabelColor;
+const accentText_1 = require("./accentText");
+// 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"],
+};
+const chartMode = (colors) => (0, accentText_1.isDarkCanvas)(colors.backgroundColor.main) ? "dark" : "light";
+exports.chartMode = chartMode;
+function getCategoricalSeriesColors(colors) {
+    return [...exports.CATEGORICAL_SERIES[(0, exports.chartMode)(colors)]];
+}
+function getDefaultSeriesColors(colors) {
+    return getCategoricalSeriesColors(colors);
+}
+/** Ink, grid and surface tokens every chart type shares. */
+function chartInk(colors) {
+    const surface = colors.backgroundColor.main;
+    return {
+        surface,
+        text: colors.text[900],
+        muted: colors.text[500],
+        grid: colors.boxborder[200],
+        axis: colors.text[500],
+        tooltipBg: colors.backgroundColor.secondary,
+    };
+}
+/** Ink for a label drawn on top of a filled mark. Always clears AA. */
+const labelOnSeries = (fill, colors) => (0, accentText_1.onFilled)(fill, colors.white, colors.black);
+exports.labelOnSeries = labelOnSeries;
+function mergeChartTitleStyle(colors, titleStyle) {
+    return {
+        fontSize: "14px",
+        fontWeight: 600,
+        fontFamily: "inherit",
+        color: colors.text[900],
+        ...titleStyle,
+    };
+}
+function chartAxisLabelColor(colors) {
+    return colors.text[500];
+}

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

@@ -0,0 +1,29 @@
+export type Rgb = {
+    r: number;
+    g: number;
+    b: number;
+};
+export type Hsl = {
+    h: number;
+    s: number;
+    l: number;
+};
+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;
+};
+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;
+export declare function hslToRgb({ h, s, l }: Hsl): Rgb;
+export declare const hexToHsl: (hex: string) => Hsl;
+export declare const hslToHex: (hsl: Hsl) => string;
+/** Re-lights a color while keeping its hue (and, unless overridden, its saturation). */
+export declare function withLightness(hex: string, lightness: number, saturation?: number): string;
+/** Linear RGB blend. `weight` is how much of `b` to take (0 → a, 1 → b). */
+export declare function mix(a: string, b: string, weight: number): string;
+/** WCAG 2.1 relative luminance. */
+export declare function relativeLuminance(hex: string): number;
+/** WCAG 2.1 contrast ratio, 1–21. AA body text needs >= 4.5. */
+export declare function contrastRatio(a: string, b: string): number;

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

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hslToHex = exports.hexToHsl = void 0;
+exports.hexToRgb = hexToRgb;
+exports.hexToRgba = hexToRgba;
+exports.compositeOver = compositeOver;
+exports.rgbToHex = rgbToHex;
+exports.rgbToHsl = rgbToHsl;
+exports.hslToRgb = hslToRgb;
+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));
+// 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)
+        h = h.split("").map((c) => c + c).join("");
+    if (!/^[0-9a-fA-F]{6}$/.test(h)) {
+        throw new Error(`hexToRgb needs an opaque #rgb/#rrggbb color, got "${hex}". ` +
+            `If this is an #rrggbbaa tint, composite it over its backdrop first (compositeOver).`);
+    }
+    const int = parseInt(h, 16);
+    return { r: (int >> 16) & 255, g: (int >> 8) & 255, b: int & 255 };
+}
+/** Alpha in 0..1. `#rgb`/`#rrggbb` read as fully opaque (`a: 1`); `#rgba`/`#rrggbbaa` carry their alpha. */
+function hexToRgba(hex) {
+    let h = hex.trim().replace(/^#/, "");
+    if (h.length === 4)
+        h = h.split("").map((c) => c + c).join("");
+    if (h.length === 8) {
+        const a = parseInt(h.slice(6, 8), 16) / 255;
+        return { ...hexToRgb(`#${h.slice(0, 6)}`), a };
+    }
+    return { ...hexToRgb(`#${h}`), a: 1 };
+}
+// 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);
+    return rgbToHex({
+        r: f.r * f.a + b.r * (1 - f.a),
+        g: f.g * f.a + b.g * (1 - f.a),
+        b: f.b * f.a + b.b * (1 - f.a),
+    });
+}
+function rgbToHex({ r, g, b }) {
+    const to = (n) => clamp(Math.round(n), 0, 255).toString(16).padStart(2, "0");
+    return `#${to(r)}${to(g)}${to(b)}`;
+}
+function rgbToHsl({ r, g, b }) {
+    const rn = r / 255;
+    const gn = g / 255;
+    const bn = b / 255;
+    const max = Math.max(rn, gn, bn);
+    const min = Math.min(rn, gn, bn);
+    const l = (max + min) / 2;
+    const d = max - min;
+    if (d === 0)
+        return { h: 0, s: 0, l: l * 100 };
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h;
+    if (max === rn)
+        h = ((gn - bn) / d + (gn < bn ? 6 : 0)) / 6;
+    else if (max === gn)
+        h = ((bn - rn) / d + 2) / 6;
+    else
+        h = ((rn - gn) / d + 4) / 6;
+    return { h: h * 360, s: s * 100, l: l * 100 };
+}
+function hslToRgb({ h, s, l }) {
+    const hn = ((h % 360) + 360) % 360 / 360;
+    const sn = clamp(s, 0, 100) / 100;
+    const ln = clamp(l, 0, 100) / 100;
+    if (sn === 0) {
+        const v = ln * 255;
+        return { r: v, g: v, b: v };
+    }
+    const q = ln < 0.5 ? ln * (1 + sn) : ln + sn - ln * sn;
+    const p = 2 * ln - q;
+    const channel = (t) => {
+        let tn = t;
+        if (tn < 0)
+            tn += 1;
+        if (tn > 1)
+            tn -= 1;
+        if (tn < 1 / 6)
+            return p + (q - p) * 6 * tn;
+        if (tn < 1 / 2)
+            return q;
+        if (tn < 2 / 3)
+            return p + (q - p) * (2 / 3 - tn) * 6;
+        return p;
+    };
+    return {
+        r: channel(hn + 1 / 3) * 255,
+        g: channel(hn) * 255,
+        b: channel(hn - 1 / 3) * 255,
+    };
+}
+const hexToHsl = (hex) => rgbToHsl(hexToRgb(hex));
+exports.hexToHsl = hexToHsl;
+const hslToHex = (hsl) => rgbToHex(hslToRgb(hsl));
+exports.hslToHex = hslToHex;
+/** Re-lights a color while keeping its hue (and, unless overridden, its saturation). */
+function withLightness(hex, lightness, saturation) {
+    const { h, s } = (0, exports.hexToHsl)(hex);
+    return (0, exports.hslToHex)({ h, s: saturation !== null && saturation !== void 0 ? saturation : s, l: clamp(lightness, 0, 100) });
+}
+/** Linear RGB blend. `weight` is how much of `b` to take (0 → a, 1 → b). */
+function mix(a, b, weight) {
+    const ca = hexToRgb(a);
+    const cb = hexToRgb(b);
+    const w = clamp(weight, 0, 1);
+    return rgbToHex({
+        r: ca.r + (cb.r - ca.r) * w,
+        g: ca.g + (cb.g - ca.g) * w,
+        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) {
+    return luminanceOf(hex);
+}
+/** WCAG 2.1 contrast ratio, 1–21. AA body text needs >= 4.5. */
+function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const light = Math.max(la, lb);
+    const dark = Math.min(la, lb);
+    return (light + 0.05) / (dark + 0.05);
+}

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;