@aglyn/shared-ui-theme 1.0.0-beta.143

package/src/lib/theme.types.js

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ export { };
+
+//# sourceMappingURL=theme.types.js.map

package/src/lib/theme.types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/ui/theme/src/lib/theme.types.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport interface IActionStates {\n  main: string\n  hover: string\n  active: string\n  focus: string\n}\n\nexport interface ColorPropOverrides {\n  tertiary: true\n  surface: true\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GASD,WAGC"}

package/src/lib/util/accent-text.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { Palette, Theme } from '../../vendor/mui';
+/**
+ * The palette slot that carries "this accent, rendered AS TEXT on the
+ * scheme's own surfaces" (AGL-1293 / AGL-1297).
+ *
+ * `dark` is deliberately overloaded rather than a new slot being invented:
+ * `ensureAccessibleShades` already guarantees the value of this slot clears
+ * {@link AA_TEXT_CONTRAST} against `background.default` and
+ * `background.paper` in whichever direction the scheme needs (darker in
+ * light, LIGHTER in dark), so every tenant palette carries an accessible
+ * value here whether or not its author thought about one. A second slot
+ * would have to be whitelisted in `host-theme.ts`, authored per host, and
+ * kept in sync — three new ways for a palette to be missing it.
+ *
+ * `console.theme.ts` authors the shade explicitly for both schemes rather
+ * than relying on that repair, so the value a link resolves to is readable
+ * in the palette instead of recomputed at boot.
+ */
+export declare const ACCENT_TEXT_SHADE: "dark";
+/** WCAG AA contrast bar for non-text UI (borders, icon fills, indicators). */
+export declare const AA_NON_TEXT_CONTRAST = 3;
+/**
+ * The accent-as-text color for `color`, as a value safe to hand to a
+ * `styleOverrides` root.
+ *
+ * Wired into `MuiButton`'s `--variant-textColor` / `--variant-outlinedColor`
+ * and `MuiLink`'s `color` in `console.theme.ts`. Those three are the places
+ * MUI paints an accent at normal text size, where `main` owes 4.5:1 and the
+ * brand blue delivers 2.43:1 on white. Everything that paints the accent as
+ * a FILL, a BORDER or an INDICATOR — `--variant-containedBg`,
+ * `--variant-outlinedBorder`, the Tabs indicator — keeps `main`: those owe
+ * 3:1, and the brand color is meant to be seen there.
+ *
+ * Returns a CSS variable reference (`var(--mui-palette-primary-dark)`) on a
+ * CSS-vars theme and a literal on a single-mode theme. That distinction is
+ * load-bearing: `components` are evaluated ONCE against the root theme, so
+ * baking a light-scheme literal would freeze it into dark mode.
+ *
+ * @param theme the active MUI theme (CSS-vars or single-mode)
+ * @param color a palette key — `'primary'`, `'error'`, … Anything without a
+ *   PaletteColor shape (`'inherit'`, `'textPrimary'`, `undefined`) returns
+ *   `undefined`.
+ */
+export declare function accentTextColor(theme: Theme | undefined, color: string | undefined): string | undefined;
+/**
+ * The accent shade a FILLED surface can paint under the accent's own ink —
+ * the counterpart to {@link accentTextColor}, and a different value for a
+ * different question (AGL-2704).
+ *
+ * {@link ACCENT_TEXT_SHADE} answers "this accent, READ ON the page", so it
+ * inverts direction per scheme: darker than `main` in light, LIGHTER in
+ * dark. That makes it wrong as a fill in exactly one scheme. The console's
+ * `primary.dark` is `#0077ad` in light, where white on it measures 4.95:1,
+ * and `#4dc8ff` in dark, where the same white measures 1.91:1 — below the
+ * 2.43:1 the brand fill it replaced already scored.
+ *
+ * This shade answers "this accent, PAINTED UNDER its own `contrastText`"
+ * instead. The constraint is the ink, not the page, so the walk starts at
+ * `main` and darkens until the ink clears the bar — and the answer is the
+ * SAME in both schemes, which is the property a token reference needs. An
+ * `sx` value resolves against whichever scheme is active, so a fill token
+ * that only holds in one of them cannot be authored safely.
+ *
+ * Takes a resolved `Palette`, never `theme.vars`: the walk decomposes real
+ * colors, and a CSS-variable mirror hands it `var(--mui-palette-…)`.
+ *
+ * @param palette a resolved (non-`vars`) palette
+ * @param color a palette key — `'primary'`, `'error'`, …
+ * @param minContrast the bar the ink must clear. Default
+ *   {@link AA_TEXT_CONTRAST}.
+ */
+export declare function accentFillColor(palette: Palette | undefined, color: string | undefined, minContrast?: number): string | undefined;
+/** One measured way a palette fails its accessibility contract. */
+export type PaletteContrastViolation = {
+    /** Palette key — `'primary'`, `'error'`, … */
+    color: string;
+    /**
+     * `accentText` — the accent painted as text on the scheme's surfaces.
+     * `contrastText` — the foreground painted ON that accent.
+     * `accentFill` — that same foreground painted on the accent's TEXT shade,
+     *   i.e. a surface filled with {@link ACCENT_TEXT_SHADE}. Off by default;
+     *   see {@link AuditPaletteContrastOptions.roles}.
+     */
+    role: 'accentText' | 'contrastText' | 'accentFill';
+    /** The foreground colour that failed. */
+    value: string;
+    /** The background it failed against. */
+    against: string;
+    /** Measured WCAG ratio, 1–21. */
+    ratio: number;
+    /** The bar it had to clear. */
+    required: number;
+    /**
+     * Set only when this exact pairing matches a
+     * {@link DOCUMENTED_CONTRAST_EXCEPTIONS} entry: the human decision that
+     * knowingly accepts the measured ratio. Excluded from the default result;
+     * surfaced by `includeExempt`.
+     */
+    exemption?: string;
+};
+/**
+ * Pairings a human has knowingly SIGNED OFF below the bar — decided, not
+ * outstanding.
+ *
+ * The rest of what {@link auditPaletteContrast} reports is a FINDING: a
+ * measurement offered for a decision the account owner owns, not a defect queued for
+ * repair. Nothing in this module changes a rendered colour.
+ *
+ * This is not a suppression list and it must not become one. Each entry pins
+ * all four coordinates of one pairing — palette key, role, the exact
+ * foreground and the exact background — so it waives a decision, not a slot.
+ * Change the brand blue, change the white, or move the same white onto
+ * `secondary`, and none of them match: the audit reports it again, which is
+ * the point. A new entry needs a named person, a date, their words, and the
+ * measured ratio, the same as this one.
+ */
+export declare const DOCUMENTED_CONTRAST_EXCEPTIONS: ReadonlyArray<{
+    color: string;
+    role: PaletteContrastViolation['role'];
+    value: string;
+    against: string;
+    reason: string;
+}>;
+export type AuditPaletteContrastOptions = {
+    /** Bar for foreground text. Default {@link AA_TEXT_CONTRAST}. */
+    minContrast?: number;
+    /** Restrict the audit to these palette keys. Default: all accents. */
+    colors?: ReadonlyArray<string>;
+    /**
+     * Include pairings matched by {@link DOCUMENTED_CONTRAST_EXCEPTIONS},
+     * carrying their `exemption`. Default `false`, so a signed-off decision does
+     * not read as an open defect. Pass `true` to see everything measured — the
+     * spec that proves the exception is still exactly 2.43:1 uses this, so the
+     * waiver documents a number rather than hiding one.
+     */
+    includeExempt?: boolean;
+    /**
+     * Which roles to measure. Default {@link DEFAULT_AUDITED_ROLES} — the two
+     * pairings every palette owes unconditionally.
+     *
+     * `accentFill` is opt-in because it is a question about a SURFACE, not
+     * about the palette: it asks what a fill painted with
+     * {@link ACCENT_TEXT_SHADE} does to the accent's own ink. In a dark scheme
+     * that shade is lighter than `main` by design, so every accent fails it —
+     * correctly, and uselessly for a palette that fills with nothing. Pass it
+     * where something actually does (AGL-2704: the marketing pricing page
+     * filled a nav CTA and a badge with `primary.dark`, which held in light at
+     * 4.95:1 and collapsed to 1.91:1 in dark).
+     */
+    roles?: ReadonlyArray<PaletteContrastViolation['role']>;
+};
+/** The roles {@link auditPaletteContrast} measures unless told otherwise. */
+export declare const DEFAULT_AUDITED_ROLES: ReadonlyArray<PaletteContrastViolation['role']>;
+/**
+ * Measures whether a palette actually keeps the AGL-1293 promise, rather
+ * than trusting that the derivation ran.
+ *
+ * This is the part that can go RED. `ensureAccessibleShades` only repairs
+ * shades it DERIVED — an explicitly authored `primary.dark`, or an accent
+ * whose AA bar is simply unreachable in the scheme's foreground direction
+ * (walking toward white on a mid-grey page tops out at 3.95:1), passes
+ * straight through. Those palettes are exactly the ones a customer can build
+ * in the theme editor, so the contract has to be checked, not assumed.
+ *
+ * Returns every violation with its measured ratio; an empty array means the
+ * palette is AA-clean for text.
+ */
+export declare function auditPaletteContrast(palette: Palette | undefined, options?: AuditPaletteContrastOptions): PaletteContrastViolation[];
+/** Human-readable one-liner per violation, for test output and dev warnings. */
+export declare function formatPaletteContrastViolation(violation: PaletteContrastViolation): string;
+export default accentTextColor;

package/src/lib/util/accent-text.js

@@ -0,0 +1,277 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { AA_TEXT_CONTRAST, accessibleShade, contrastRatio } from "./accessible-shade.js";
+/**
+ * The palette slot that carries "this accent, rendered AS TEXT on the
+ * scheme's own surfaces" (AGL-1293 / AGL-1297).
+ *
+ * `dark` is deliberately overloaded rather than a new slot being invented:
+ * `ensureAccessibleShades` already guarantees the value of this slot clears
+ * {@link AA_TEXT_CONTRAST} against `background.default` and
+ * `background.paper` in whichever direction the scheme needs (darker in
+ * light, LIGHTER in dark), so every tenant palette carries an accessible
+ * value here whether or not its author thought about one. A second slot
+ * would have to be whitelisted in `host-theme.ts`, authored per host, and
+ * kept in sync — three new ways for a palette to be missing it.
+ *
+ * `console.theme.ts` authors the shade explicitly for both schemes rather
+ * than relying on that repair, so the value a link resolves to is readable
+ * in the palette instead of recomputed at boot.
+ */ export const ACCENT_TEXT_SHADE = 'dark';
+/** WCAG AA contrast bar for non-text UI (borders, icon fills, indicators). */ export const AA_NON_TEXT_CONTRAST = 3;
+/**
+ * The accent-as-text color for `color`, as a value safe to hand to a
+ * `styleOverrides` root.
+ *
+ * Wired into `MuiButton`'s `--variant-textColor` / `--variant-outlinedColor`
+ * and `MuiLink`'s `color` in `console.theme.ts`. Those three are the places
+ * MUI paints an accent at normal text size, where `main` owes 4.5:1 and the
+ * brand blue delivers 2.43:1 on white. Everything that paints the accent as
+ * a FILL, a BORDER or an INDICATOR — `--variant-containedBg`,
+ * `--variant-outlinedBorder`, the Tabs indicator — keeps `main`: those owe
+ * 3:1, and the brand color is meant to be seen there.
+ *
+ * Returns a CSS variable reference (`var(--mui-palette-primary-dark)`) on a
+ * CSS-vars theme and a literal on a single-mode theme. That distinction is
+ * load-bearing: `components` are evaluated ONCE against the root theme, so
+ * baking a light-scheme literal would freeze it into dark mode.
+ *
+ * @param theme the active MUI theme (CSS-vars or single-mode)
+ * @param color a palette key — `'primary'`, `'error'`, … Anything without a
+ *   PaletteColor shape (`'inherit'`, `'textPrimary'`, `undefined`) returns
+ *   `undefined`.
+ */ export function accentTextColor(theme, color) {
+    var _theme_vars;
+    var _source_palette;
+    if (!theme || !color) return undefined;
+    // `theme.vars` is the CSS-variable mirror of the palette; prefer it so the
+    // emitted value is a `var()` that follows the scheme.
+    const source = (_theme_vars = theme.vars) != null ? _theme_vars : theme;
+    const paletteColor = source == null ? void 0 : (_source_palette = source.palette) == null ? void 0 : _source_palette[color];
+    if (!paletteColor || typeof paletteColor !== 'object') return undefined;
+    const accent = paletteColor[ACCENT_TEXT_SHADE];
+    return typeof accent === 'string' ? accent : undefined;
+}
+/**
+ * The accent shade a FILLED surface can paint under the accent's own ink —
+ * the counterpart to {@link accentTextColor}, and a different value for a
+ * different question (AGL-2704).
+ *
+ * {@link ACCENT_TEXT_SHADE} answers "this accent, READ ON the page", so it
+ * inverts direction per scheme: darker than `main` in light, LIGHTER in
+ * dark. That makes it wrong as a fill in exactly one scheme. The console's
+ * `primary.dark` is `#0077ad` in light, where white on it measures 4.95:1,
+ * and `#4dc8ff` in dark, where the same white measures 1.91:1 — below the
+ * 2.43:1 the brand fill it replaced already scored.
+ *
+ * This shade answers "this accent, PAINTED UNDER its own `contrastText`"
+ * instead. The constraint is the ink, not the page, so the walk starts at
+ * `main` and darkens until the ink clears the bar — and the answer is the
+ * SAME in both schemes, which is the property a token reference needs. An
+ * `sx` value resolves against whichever scheme is active, so a fill token
+ * that only holds in one of them cannot be authored safely.
+ *
+ * Takes a resolved `Palette`, never `theme.vars`: the walk decomposes real
+ * colors, and a CSS-variable mirror hands it `var(--mui-palette-…)`.
+ *
+ * @param palette a resolved (non-`vars`) palette
+ * @param color a palette key — `'primary'`, `'error'`, …
+ * @param minContrast the bar the ink must clear. Default
+ *   {@link AA_TEXT_CONTRAST}.
+ */ export function accentFillColor(palette, color, minContrast = AA_TEXT_CONTRAST) {
+    if (!palette || !color) return undefined;
+    const paletteColor = palette[color];
+    if (!paletteColor || typeof paletteColor !== 'object') return undefined;
+    const { main, contrastText } = paletteColor;
+    if (typeof main !== 'string' || typeof contrastText !== 'string') {
+        return undefined;
+    }
+    try {
+        return accessibleShade(main, [
+            contrastText
+        ], 'darken', {
+            minContrast
+        });
+    } catch (unused) {
+        // Unparseable color (a `color()` literal, an unresolved variable). A
+        // caller gets nothing rather than a guess, the same as `accentTextColor`.
+        return undefined;
+    }
+}
+/**
+ * Pairings a human has knowingly SIGNED OFF below the bar — decided, not
+ * outstanding.
+ *
+ * The rest of what {@link auditPaletteContrast} reports is a FINDING: a
+ * measurement offered for a decision the account owner owns, not a defect queued for
+ * repair. Nothing in this module changes a rendered colour.
+ *
+ * This is not a suppression list and it must not become one. Each entry pins
+ * all four coordinates of one pairing — palette key, role, the exact
+ * foreground and the exact background — so it waives a decision, not a slot.
+ * Change the brand blue, change the white, or move the same white onto
+ * `secondary`, and none of them match: the audit reports it again, which is
+ * the point. A new entry needs a named person, a date, their words, and the
+ * measured ratio, the same as this one.
+ */ export const DOCUMENTED_CONTRAST_EXCEPTIONS = [
+    {
+        // AGL-1293. Computing this slot for contrast resolves it to dark ink
+        // (8.65:1), which turns every filled primary button dark-on-blue. The
+        // tradeoff is to darken the brand or to keep it and accept sub-AA white,
+        // and the brand blue is fixed: white on `#00b0ff` is 2.43:1, below the
+        // 4.5:1 AA text bar and below the 3:1 non-text bar. Accepted knowingly.
+        //
+        // This is the ONE decided pairing. Everything else the audit reports —
+        // the five other authored sub-AA `contrastText` literals, and `#00b0ff`
+        // as text — is a finding, not a waiver, and stays undecided here.
+        color: 'primary',
+        role: 'contrastText',
+        value: '#FFFFFF',
+        against: '#00b0ff',
+        reason: 'AGL-1293 — the brand blue stays as authored, with white text (white on #00b0ff = 2.43:1, knowingly below AA)'
+    }
+];
+/** Case-insensitive exact colour match; nothing fuzzy, nothing normalised away. */ function sameColor(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+/**
+ * The signed-off reason for this exact pairing, or `undefined`. Exact on all
+ * four coordinates — a near miss is not a match.
+ */ function documentedExemption(color, role, value, against) {
+    var _DOCUMENTED_CONTRAST_EXCEPTIONS_find;
+    return (_DOCUMENTED_CONTRAST_EXCEPTIONS_find = DOCUMENTED_CONTRAST_EXCEPTIONS.find((exception)=>exception.color === color && exception.role === role && sameColor(exception.value, value) && sameColor(exception.against, against))) == null ? void 0 : _DOCUMENTED_CONTRAST_EXCEPTIONS_find.reason;
+}
+const AUDITED_COLOR_KEYS = [
+    'primary',
+    'secondary',
+    'tertiary',
+    'error',
+    'warning',
+    'info',
+    'success'
+];
+/** The roles {@link auditPaletteContrast} measures unless told otherwise. */ export const DEFAULT_AUDITED_ROLES = [
+    'accentText',
+    'contrastText'
+];
+/**
+ * Measures whether a palette actually keeps the AGL-1293 promise, rather
+ * than trusting that the derivation ran.
+ *
+ * This is the part that can go RED. `ensureAccessibleShades` only repairs
+ * shades it DERIVED — an explicitly authored `primary.dark`, or an accent
+ * whose AA bar is simply unreachable in the scheme's foreground direction
+ * (walking toward white on a mid-grey page tops out at 3.95:1), passes
+ * straight through. Those palettes are exactly the ones a customer can build
+ * in the theme editor, so the contract has to be checked, not assumed.
+ *
+ * Returns every violation with its measured ratio; an empty array means the
+ * palette is AA-clean for text.
+ */ export function auditPaletteContrast(palette, options = {}) {
+    var _palette_background, _palette_background1;
+    const { minContrast = AA_TEXT_CONTRAST, colors = AUDITED_COLOR_KEYS, includeExempt = false, roles = DEFAULT_AUDITED_ROLES } = options;
+    const measures = (role)=>roles.includes(role);
+    const violations = [];
+    /** Records a measured failure unless a documented decision waives it. */ const record = (violation)=>{
+        const exemption = documentedExemption(violation.color, violation.role, violation.value, violation.against);
+        if (exemption && !includeExempt) return;
+        violations.push(exemption ? _extends({}, violation, {
+            exemption
+        }) : violation);
+    };
+    if (!palette) return violations;
+    const indexed = palette;
+    const backgrounds = [
+        (_palette_background = palette.background) == null ? void 0 : _palette_background.default,
+        (_palette_background1 = palette.background) == null ? void 0 : _palette_background1.paper
+    ].filter((background)=>typeof background === 'string');
+    for (const key of colors){
+        const color = indexed[key];
+        if (!color || typeof color.main !== 'string') continue;
+        const accent = color[ACCENT_TEXT_SHADE];
+        for (const background of backgrounds){
+            if (!measures('accentText') || typeof accent !== 'string') continue;
+            try {
+                const ratio = contrastRatio(accent, background);
+                if (ratio < minContrast) {
+                    record({
+                        color: key,
+                        role: 'accentText',
+                        value: accent,
+                        against: background,
+                        ratio,
+                        required: minContrast
+                    });
+                }
+            } catch (unused) {
+            // Unparseable colour (CSS variable, color-mix()): not measurable
+            // here. Silence rather than a false violation — the caller audits a
+            // resolved palette, not a `vars` mirror.
+            }
+        }
+        if (typeof color.contrastText !== 'string') continue;
+        if (measures('contrastText')) {
+            try {
+                const ratio = contrastRatio(color.contrastText, color.main);
+                if (ratio < minContrast) {
+                    record({
+                        color: key,
+                        role: 'contrastText',
+                        value: color.contrastText,
+                        against: color.main,
+                        ratio,
+                        required: minContrast
+                    });
+                }
+            } catch (unused) {
+            // As above.
+            }
+        }
+        // The same ink, on a surface filled with the accent's TEXT shade. That
+        // shade is chosen to be READ ON the page, so in a dark scheme it sits
+        // lighter than `main` and cannot carry a light ink — which is invisible
+        // to the `contrastText` measure above, because that one only ever looks
+        // at `main`.
+        if (measures('accentFill') && typeof accent === 'string') {
+            try {
+                const ratio = contrastRatio(color.contrastText, accent);
+                if (ratio < minContrast) {
+                    record({
+                        color: key,
+                        role: 'accentFill',
+                        value: color.contrastText,
+                        against: accent,
+                        ratio,
+                        required: minContrast
+                    });
+                }
+            } catch (unused) {
+            // As above.
+            }
+        }
+    }
+    return violations;
+}
+/** Human-readable one-liner per violation, for test output and dev warnings. */ export function formatPaletteContrastViolation(violation) {
+    const measured = `${violation.color}.${violation.role} ${violation.value} on ${violation.against} is ${violation.ratio.toFixed(2)}:1, below ${violation.required}:1`;
+    // The waived line still carries its number, so a reader sees what was
+    // accepted rather than a bare "exempt".
+    return violation.exemption ? `${measured} — KNOWN EXCEPTION: ${violation.exemption}` : measured;
+}
+export default accentTextColor;
+
+//# sourceMappingURL=accent-text.js.map

package/src/lib/util/accent-text.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/theme/src/lib/util/accent-text.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { Palette, PaletteColor, Theme } from '../../vendor/mui'\nimport {\n  AA_TEXT_CONTRAST,\n  accessibleShade,\n  contrastRatio,\n} from './accessible-shade'\n\n/**\n * The palette slot that carries \"this accent, rendered AS TEXT on the\n * scheme's own surfaces\" (AGL-1293 / AGL-1297).\n *\n * `dark` is deliberately overloaded rather than a new slot being invented:\n * `ensureAccessibleShades` already guarantees the value of this slot clears\n * {@link AA_TEXT_CONTRAST} against `background.default` and\n * `background.paper` in whichever direction the scheme needs (darker in\n * light, LIGHTER in dark), so every tenant palette carries an accessible\n * value here whether or not its author thought about one. A second slot\n * would have to be whitelisted in `host-theme.ts`, authored per host, and\n * kept in sync — three new ways for a palette to be missing it.\n *\n * `console.theme.ts` authors the shade explicitly for both schemes rather\n * than relying on that repair, so the value a link resolves to is readable\n * in the palette instead of recomputed at boot.\n */\nexport const ACCENT_TEXT_SHADE = 'dark' as const\n\n/** WCAG AA contrast bar for non-text UI (borders, icon fills, indicators). */\nexport const AA_NON_TEXT_CONTRAST = 3\n\n/**\n * The accent-as-text color for `color`, as a value safe to hand to a\n * `styleOverrides` root.\n *\n * Wired into `MuiButton`'s `--variant-textColor` / `--variant-outlinedColor`\n * and `MuiLink`'s `color` in `console.theme.ts`. Those three are the places\n * MUI paints an accent at normal text size, where `main` owes 4.5:1 and the\n * brand blue delivers 2.43:1 on white. Everything that paints the accent as\n * a FILL, a BORDER or an INDICATOR — `--variant-containedBg`,\n * `--variant-outlinedBorder`, the Tabs indicator — keeps `main`: those owe\n * 3:1, and the brand color is meant to be seen there.\n *\n * Returns a CSS variable reference (`var(--mui-palette-primary-dark)`) on a\n * CSS-vars theme and a literal on a single-mode theme. That distinction is\n * load-bearing: `components` are evaluated ONCE against the root theme, so\n * baking a light-scheme literal would freeze it into dark mode.\n *\n * @param theme the active MUI theme (CSS-vars or single-mode)\n * @param color a palette key — `'primary'`, `'error'`, … Anything without a\n *   PaletteColor shape (`'inherit'`, `'textPrimary'`, `undefined`) returns\n *   `undefined`.\n */\nexport function accentTextColor(\n  theme: Theme | undefined,\n  color: string | undefined,\n): string | undefined {\n  if (!theme || !color) return undefined\n  // `theme.vars` is the CSS-variable mirror of the palette; prefer it so the\n  // emitted value is a `var()` that follows the scheme.\n  const source = ((theme as unknown as { vars?: { palette?: unknown } }).vars ??\n    theme) as { palette?: Record<string, unknown> }\n  const paletteColor = source?.palette?.[color] as\n    Record<string, string> | undefined\n  if (!paletteColor || typeof paletteColor !== 'object') return undefined\n  const accent = paletteColor[ACCENT_TEXT_SHADE]\n  return typeof accent === 'string' ? accent : undefined\n}\n\n/**\n * The accent shade a FILLED surface can paint under the accent's own ink —\n * the counterpart to {@link accentTextColor}, and a different value for a\n * different question (AGL-2704).\n *\n * {@link ACCENT_TEXT_SHADE} answers \"this accent, READ ON the page\", so it\n * inverts direction per scheme: darker than `main` in light, LIGHTER in\n * dark. That makes it wrong as a fill in exactly one scheme. The console's\n * `primary.dark` is `#0077ad` in light, where white on it measures 4.95:1,\n * and `#4dc8ff` in dark, where the same white measures 1.91:1 — below the\n * 2.43:1 the brand fill it replaced already scored.\n *\n * This shade answers \"this accent, PAINTED UNDER its own `contrastText`\"\n * instead. The constraint is the ink, not the page, so the walk starts at\n * `main` and darkens until the ink clears the bar — and the answer is the\n * SAME in both schemes, which is the property a token reference needs. An\n * `sx` value resolves against whichever scheme is active, so a fill token\n * that only holds in one of them cannot be authored safely.\n *\n * Takes a resolved `Palette`, never `theme.vars`: the walk decomposes real\n * colors, and a CSS-variable mirror hands it `var(--mui-palette-…)`.\n *\n * @param palette a resolved (non-`vars`) palette\n * @param color a palette key — `'primary'`, `'error'`, …\n * @param minContrast the bar the ink must clear. Default\n *   {@link AA_TEXT_CONTRAST}.\n */\nexport function accentFillColor(\n  palette: Palette | undefined,\n  color: string | undefined,\n  minContrast: number = AA_TEXT_CONTRAST,\n): string | undefined {\n  if (!palette || !color) return undefined\n  const paletteColor = (palette as unknown as Record<string, unknown>)[\n    color\n  ] as Record<string, string> | undefined\n  if (!paletteColor || typeof paletteColor !== 'object') return undefined\n  const { main, contrastText } = paletteColor\n  if (typeof main !== 'string' || typeof contrastText !== 'string') {\n    return undefined\n  }\n  try {\n    return accessibleShade(main, [contrastText], 'darken', { minContrast })\n  } catch {\n    // Unparseable color (a `color()` literal, an unresolved variable). A\n    // caller gets nothing rather than a guess, the same as `accentTextColor`.\n    return undefined\n  }\n}\n\n/** One measured way a palette fails its accessibility contract. */\nexport type PaletteContrastViolation = {\n  /** Palette key — `'primary'`, `'error'`, … */\n  color: string\n  /**\n   * `accentText` — the accent painted as text on the scheme's surfaces.\n   * `contrastText` — the foreground painted ON that accent.\n   * `accentFill` — that same foreground painted on the accent's TEXT shade,\n   *   i.e. a surface filled with {@link ACCENT_TEXT_SHADE}. Off by default;\n   *   see {@link AuditPaletteContrastOptions.roles}.\n   */\n  role: 'accentText' | 'contrastText' | 'accentFill'\n  /** The foreground colour that failed. */\n  value: string\n  /** The background it failed against. */\n  against: string\n  /** Measured WCAG ratio, 1–21. */\n  ratio: number\n  /** The bar it had to clear. */\n  required: number\n  /**\n   * Set only when this exact pairing matches a\n   * {@link DOCUMENTED_CONTRAST_EXCEPTIONS} entry: the human decision that\n   * knowingly accepts the measured ratio. Excluded from the default result;\n   * surfaced by `includeExempt`.\n   */\n  exemption?: string\n}\n\n/**\n * Pairings a human has knowingly SIGNED OFF below the bar — decided, not\n * outstanding.\n *\n * The rest of what {@link auditPaletteContrast} reports is a FINDING: a\n * measurement offered for a decision the account owner owns, not a defect queued for\n * repair. Nothing in this module changes a rendered colour.\n *\n * This is not a suppression list and it must not become one. Each entry pins\n * all four coordinates of one pairing — palette key, role, the exact\n * foreground and the exact background — so it waives a decision, not a slot.\n * Change the brand blue, change the white, or move the same white onto\n * `secondary`, and none of them match: the audit reports it again, which is\n * the point. A new entry needs a named person, a date, their words, and the\n * measured ratio, the same as this one.\n */\nexport const DOCUMENTED_CONTRAST_EXCEPTIONS: ReadonlyArray<{\n  color: string\n  role: PaletteContrastViolation['role']\n  value: string\n  against: string\n  reason: string\n}> = [\n  {\n    // AGL-1293. Computing this slot for contrast resolves it to dark ink\n    // (8.65:1), which turns every filled primary button dark-on-blue. The\n    // tradeoff is to darken the brand or to keep it and accept sub-AA white,\n    // and the brand blue is fixed: white on `#00b0ff` is 2.43:1, below the\n    // 4.5:1 AA text bar and below the 3:1 non-text bar. Accepted knowingly.\n    //\n    // This is the ONE decided pairing. Everything else the audit reports —\n    // the five other authored sub-AA `contrastText` literals, and `#00b0ff`\n    // as text — is a finding, not a waiver, and stays undecided here.\n    color: 'primary',\n    role: 'contrastText',\n    value: '#FFFFFF',\n    against: '#00b0ff',\n    reason:\n      'AGL-1293 — the brand blue stays as authored, with white text (white on #00b0ff = 2.43:1, knowingly below AA)',\n  },\n]\n\n/** Case-insensitive exact colour match; nothing fuzzy, nothing normalised away. */\nfunction sameColor(a: string, b: string) {\n  return a.trim().toLowerCase() === b.trim().toLowerCase()\n}\n\n/**\n * The signed-off reason for this exact pairing, or `undefined`. Exact on all\n * four coordinates — a near miss is not a match.\n */\nfunction documentedExemption(\n  color: string,\n  role: PaletteContrastViolation['role'],\n  value: string,\n  against: string,\n): string | undefined {\n  return DOCUMENTED_CONTRAST_EXCEPTIONS.find(\n    (exception) =>\n      exception.color === color &&\n      exception.role === role &&\n      sameColor(exception.value, value) &&\n      sameColor(exception.against, against),\n  )?.reason\n}\n\nconst AUDITED_COLOR_KEYS = [\n  'primary',\n  'secondary',\n  'tertiary',\n  'error',\n  'warning',\n  'info',\n  'success',\n] as const\n\nexport type AuditPaletteContrastOptions = {\n  /** Bar for foreground text. Default {@link AA_TEXT_CONTRAST}. */\n  minContrast?: number\n  /** Restrict the audit to these palette keys. Default: all accents. */\n  colors?: ReadonlyArray<string>\n  /**\n   * Include pairings matched by {@link DOCUMENTED_CONTRAST_EXCEPTIONS},\n   * carrying their `exemption`. Default `false`, so a signed-off decision does\n   * not read as an open defect. Pass `true` to see everything measured — the\n   * spec that proves the exception is still exactly 2.43:1 uses this, so the\n   * waiver documents a number rather than hiding one.\n   */\n  includeExempt?: boolean\n  /**\n   * Which roles to measure. Default {@link DEFAULT_AUDITED_ROLES} — the two\n   * pairings every palette owes unconditionally.\n   *\n   * `accentFill` is opt-in because it is a question about a SURFACE, not\n   * about the palette: it asks what a fill painted with\n   * {@link ACCENT_TEXT_SHADE} does to the accent's own ink. In a dark scheme\n   * that shade is lighter than `main` by design, so every accent fails it —\n   * correctly, and uselessly for a palette that fills with nothing. Pass it\n   * where something actually does (AGL-2704: the marketing pricing page\n   * filled a nav CTA and a badge with `primary.dark`, which held in light at\n   * 4.95:1 and collapsed to 1.91:1 in dark).\n   */\n  roles?: ReadonlyArray<PaletteContrastViolation['role']>\n}\n\n/** The roles {@link auditPaletteContrast} measures unless told otherwise. */\nexport const DEFAULT_AUDITED_ROLES: ReadonlyArray<\n  PaletteContrastViolation['role']\n> = ['accentText', 'contrastText']\n\n/**\n * Measures whether a palette actually keeps the AGL-1293 promise, rather\n * than trusting that the derivation ran.\n *\n * This is the part that can go RED. `ensureAccessibleShades` only repairs\n * shades it DERIVED — an explicitly authored `primary.dark`, or an accent\n * whose AA bar is simply unreachable in the scheme's foreground direction\n * (walking toward white on a mid-grey page tops out at 3.95:1), passes\n * straight through. Those palettes are exactly the ones a customer can build\n * in the theme editor, so the contract has to be checked, not assumed.\n *\n * Returns every violation with its measured ratio; an empty array means the\n * palette is AA-clean for text.\n */\nexport function auditPaletteContrast(\n  palette: Palette | undefined,\n  options: AuditPaletteContrastOptions = {},\n): PaletteContrastViolation[] {\n  const {\n    minContrast = AA_TEXT_CONTRAST,\n    colors = AUDITED_COLOR_KEYS,\n    includeExempt = false,\n    roles = DEFAULT_AUDITED_ROLES,\n  } = options\n  const measures = (role: PaletteContrastViolation['role']) =>\n    roles.includes(role)\n  const violations: PaletteContrastViolation[] = []\n  /** Records a measured failure unless a documented decision waives it. */\n  const record = (violation: PaletteContrastViolation) => {\n    const exemption = documentedExemption(\n      violation.color,\n      violation.role,\n      violation.value,\n      violation.against,\n    )\n    if (exemption && !includeExempt) return\n    violations.push(exemption ? { ...violation, exemption } : violation)\n  }\n  if (!palette) return violations\n  const indexed = palette as unknown as Record<string, PaletteColor | undefined>\n  const backgrounds = [\n    palette.background?.default,\n    palette.background?.paper,\n  ].filter((background): background is string => typeof background === 'string')\n\n  for (const key of colors) {\n    const color = indexed[key]\n    if (!color || typeof color.main !== 'string') continue\n    const accent = (color as unknown as Record<string, string>)[\n      ACCENT_TEXT_SHADE\n    ]\n    for (const background of backgrounds) {\n      if (!measures('accentText') || typeof accent !== 'string') continue\n      try {\n        const ratio = contrastRatio(accent, background)\n        if (ratio < minContrast) {\n          record({\n            color: key,\n            role: 'accentText',\n            value: accent,\n            against: background,\n            ratio,\n            required: minContrast,\n          })\n        }\n      } catch {\n        // Unparseable colour (CSS variable, color-mix()): not measurable\n        // here. Silence rather than a false violation — the caller audits a\n        // resolved palette, not a `vars` mirror.\n      }\n    }\n    if (typeof color.contrastText !== 'string') continue\n    if (measures('contrastText')) {\n      try {\n        const ratio = contrastRatio(color.contrastText, color.main)\n        if (ratio < minContrast) {\n          record({\n            color: key,\n            role: 'contrastText',\n            value: color.contrastText,\n            against: color.main,\n            ratio,\n            required: minContrast,\n          })\n        }\n      } catch {\n        // As above.\n      }\n    }\n    // The same ink, on a surface filled with the accent's TEXT shade. That\n    // shade is chosen to be READ ON the page, so in a dark scheme it sits\n    // lighter than `main` and cannot carry a light ink — which is invisible\n    // to the `contrastText` measure above, because that one only ever looks\n    // at `main`.\n    if (measures('accentFill') && typeof accent === 'string') {\n      try {\n        const ratio = contrastRatio(color.contrastText, accent)\n        if (ratio < minContrast) {\n          record({\n            color: key,\n            role: 'accentFill',\n            value: color.contrastText,\n            against: accent,\n            ratio,\n            required: minContrast,\n          })\n        }\n      } catch {\n        // As above.\n      }\n    }\n  }\n  return violations\n}\n\n/** Human-readable one-liner per violation, for test output and dev warnings. */\nexport function formatPaletteContrastViolation(\n  violation: PaletteContrastViolation,\n): string {\n  const measured = `${violation.color}.${violation.role} ${violation.value} on ${\n    violation.against\n  } is ${violation.ratio.toFixed(2)}:1, below ${violation.required}:1`\n  // The waived line still carries its number, so a reader sees what was\n  // accepted rather than a bare \"exempt\".\n  return violation.exemption\n    ? `${measured} — KNOWN EXCEPTION: ${violation.exemption}`\n    : measured\n}\n\nexport default accentTextColor\n"],"names":["AA_TEXT_CONTRAST","accessibleShade","contrastRatio","ACCENT_TEXT_SHADE","AA_NON_TEXT_CONTRAST","accentTextColor","theme","color","source","undefined","vars","paletteColor","palette","accent","accentFillColor","minContrast","main","contrastText","DOCUMENTED_CONTRAST_EXCEPTIONS","role","value","against","reason","sameColor","a","b","trim","toLowerCase","documentedExemption","find","exception","AUDITED_COLOR_KEYS","DEFAULT_AUDITED_ROLES","auditPaletteContrast","options","colors","includeExempt","roles","measures","includes","violations","record","violation","exemption","push","indexed","backgrounds","background","default","paper","filter","key","ratio","required","formatPaletteContrastViolation","measured","toFixed"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SACEA,gBAAgB,EAChBC,eAAe,EACfC,aAAa,QACR,wBAAoB;AAE3B;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,MAAMC,oBAAoB,OAAe;AAEhD,4EAA4E,GAC5E,OAAO,MAAMC,uBAAuB,EAAC;AAErC;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,SAASC,gBACdC,KAAwB,EACxBC,KAAyB;QAKT;QAEKC;IALrB,IAAI,CAACF,SAAS,CAACC,OAAO,OAAOE;IAC7B,2EAA2E;IAC3E,sDAAsD;IACtD,MAAMD,UAAU,cAAA,AAACF,MAAsDI,IAAI,YAA3D,cACdJ;IACF,MAAMK,eAAeH,2BAAAA,kBAAAA,OAAQI,OAAO,qBAAfJ,eAAiB,CAACD,MAAM;IAE7C,IAAI,CAACI,gBAAgB,OAAOA,iBAAiB,UAAU,OAAOF;IAC9D,MAAMI,SAASF,YAAY,CAACR,kBAAkB;IAC9C,OAAO,OAAOU,WAAW,WAAWA,SAASJ;AAC/C;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;CA0BC,GACD,OAAO,SAASK,gBACdF,OAA4B,EAC5BL,KAAyB,EACzBQ,cAAsBf,gBAAgB;IAEtC,IAAI,CAACY,WAAW,CAACL,OAAO,OAAOE;IAC/B,MAAME,eAAe,AAACC,OAA8C,CAClEL,MACD;IACD,IAAI,CAACI,gBAAgB,OAAOA,iBAAiB,UAAU,OAAOF;IAC9D,MAAM,EAAEO,IAAI,EAAEC,YAAY,EAAE,GAAGN;IAC/B,IAAI,OAAOK,SAAS,YAAY,OAAOC,iBAAiB,UAAU;QAChE,OAAOR;IACT;IACA,IAAI;QACF,OAAOR,gBAAgBe,MAAM;YAACC;SAAa,EAAE,UAAU;YAAEF;QAAY;IACvE,EAAE,eAAM;QACN,qEAAqE;QACrE,0EAA0E;QAC1E,OAAON;IACT;AACF;AA+BA;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMS,iCAMR;IACH;QACE,qEAAqE;QACrE,sEAAsE;QACtE,yEAAyE;QACzE,uEAAuE;QACvE,wEAAwE;QACxE,EAAE;QACF,uEAAuE;QACvE,wEAAwE;QACxE,kEAAkE;QAClEX,OAAO;QACPY,MAAM;QACNC,OAAO;QACPC,SAAS;QACTC,QACE;IACJ;CACD,CAAA;AAED,iFAAiF,GACjF,SAASC,UAAUC,CAAS,EAAEC,CAAS;IACrC,OAAOD,EAAEE,IAAI,GAAGC,WAAW,OAAOF,EAAEC,IAAI,GAAGC,WAAW;AACxD;AAEA;;;CAGC,GACD,SAASC,oBACPrB,KAAa,EACbY,IAAsC,EACtCC,KAAa,EACbC,OAAe;QAERH;IAAP,QAAOA,uCAAAA,+BAA+BW,IAAI,CACxC,CAACC,YACCA,UAAUvB,KAAK,KAAKA,SACpBuB,UAAUX,IAAI,KAAKA,QACnBI,UAAUO,UAAUV,KAAK,EAAEA,UAC3BG,UAAUO,UAAUT,OAAO,EAAEA,8BAL1BH,qCAMJI,MAAM;AACX;AAEA,MAAMS,qBAAqB;IACzB;IACA;IACA;IACA;IACA;IACA;IACA;CACD;AA+BD,2EAA2E,GAC3E,OAAO,MAAMC,wBAET;IAAC;IAAc;CAAe,CAAA;AAElC;;;;;;;;;;;;;CAaC,GACD,OAAO,SAASC,qBACdrB,OAA4B,EAC5BsB,UAAuC,CAAC,CAAC;QAyBvCtB,qBACAA;IAxBF,MAAM,EACJG,cAAcf,gBAAgB,EAC9BmC,SAASJ,kBAAkB,EAC3BK,gBAAgB,KAAK,EACrBC,QAAQL,qBAAqB,EAC9B,GAAGE;IACJ,MAAMI,WAAW,CAACnB,OAChBkB,MAAME,QAAQ,CAACpB;IACjB,MAAMqB,aAAyC,EAAE;IACjD,uEAAuE,GACvE,MAAMC,SAAS,CAACC;QACd,MAAMC,YAAYf,oBAChBc,UAAUnC,KAAK,EACfmC,UAAUvB,IAAI,EACduB,UAAUtB,KAAK,EACfsB,UAAUrB,OAAO;QAEnB,IAAIsB,aAAa,CAACP,eAAe;QACjCI,WAAWI,IAAI,CAACD,YAAY,aAAKD;YAAWC;aAAcD;IAC5D;IACA,IAAI,CAAC9B,SAAS,OAAO4B;IACrB,MAAMK,UAAUjC;IAChB,MAAMkC,cAAc;SAClBlC,sBAAAA,QAAQmC,UAAU,qBAAlBnC,oBAAoBoC,OAAO;SAC3BpC,uBAAAA,QAAQmC,UAAU,qBAAlBnC,qBAAoBqC,KAAK;KAC1B,CAACC,MAAM,CAAC,CAACH,aAAqC,OAAOA,eAAe;IAErE,KAAK,MAAMI,OAAOhB,OAAQ;QACxB,MAAM5B,QAAQsC,OAAO,CAACM,IAAI;QAC1B,IAAI,CAAC5C,SAAS,OAAOA,MAAMS,IAAI,KAAK,UAAU;QAC9C,MAAMH,SAAS,AAACN,KAA2C,CACzDJ,kBACD;QACD,KAAK,MAAM4C,cAAcD,YAAa;YACpC,IAAI,CAACR,SAAS,iBAAiB,OAAOzB,WAAW,UAAU;YAC3D,IAAI;gBACF,MAAMuC,QAAQlD,cAAcW,QAAQkC;gBACpC,IAAIK,QAAQrC,aAAa;oBACvB0B,OAAO;wBACLlC,OAAO4C;wBACPhC,MAAM;wBACNC,OAAOP;wBACPQ,SAAS0B;wBACTK;wBACAC,UAAUtC;oBACZ;gBACF;YACF,EAAE,eAAM;YACN,iEAAiE;YACjE,oEAAoE;YACpE,yCAAyC;YAC3C;QACF;QACA,IAAI,OAAOR,MAAMU,YAAY,KAAK,UAAU;QAC5C,IAAIqB,SAAS,iBAAiB;YAC5B,IAAI;gBACF,MAAMc,QAAQlD,cAAcK,MAAMU,YAAY,EAAEV,MAAMS,IAAI;gBAC1D,IAAIoC,QAAQrC,aAAa;oBACvB0B,OAAO;wBACLlC,OAAO4C;wBACPhC,MAAM;wBACNC,OAAOb,MAAMU,YAAY;wBACzBI,SAASd,MAAMS,IAAI;wBACnBoC;wBACAC,UAAUtC;oBACZ;gBACF;YACF,EAAE,eAAM;YACN,YAAY;YACd;QACF;QACA,uEAAuE;QACvE,sEAAsE;QACtE,wEAAwE;QACxE,wEAAwE;QACxE,aAAa;QACb,IAAIuB,SAAS,iBAAiB,OAAOzB,WAAW,UAAU;YACxD,IAAI;gBACF,MAAMuC,QAAQlD,cAAcK,MAAMU,YAAY,EAAEJ;gBAChD,IAAIuC,QAAQrC,aAAa;oBACvB0B,OAAO;wBACLlC,OAAO4C;wBACPhC,MAAM;wBACNC,OAAOb,MAAMU,YAAY;wBACzBI,SAASR;wBACTuC;wBACAC,UAAUtC;oBACZ;gBACF;YACF,EAAE,eAAM;YACN,YAAY;YACd;QACF;IACF;IACA,OAAOyB;AACT;AAEA,8EAA8E,GAC9E,OAAO,SAASc,+BACdZ,SAAmC;IAEnC,MAAMa,WAAW,GAAGb,UAAUnC,KAAK,CAAC,CAAC,EAAEmC,UAAUvB,IAAI,CAAC,CAAC,EAAEuB,UAAUtB,KAAK,CAAC,IAAI,EAC3EsB,UAAUrB,OAAO,CAClB,IAAI,EAAEqB,UAAUU,KAAK,CAACI,OAAO,CAAC,GAAG,UAAU,EAAEd,UAAUW,QAAQ,CAAC,EAAE,CAAC;IACpE,sEAAsE;IACtE,wCAAwC;IACxC,OAAOX,UAAUC,SAAS,GACtB,GAAGY,SAAS,oBAAoB,EAAEb,UAAUC,SAAS,EAAE,GACvDY;AACN;AAEA,eAAelD,gBAAe"}

package/src/lib/util/accessible-shade.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** Ramp direction for a shade walk. */
+export type ShadeDirection = 'darken' | 'lighten';
+/** WCAG 2.x AA contrast bar for normal-size text. */
+export declare const AA_TEXT_CONTRAST = 4.5;
+export type AccessibleShadeOptions = {
+    /** Contrast every background must clear. Default {@link AA_TEXT_CONTRAST}. */
+    minContrast?: number;
+    /** HSL lightness moved per iteration (0–1 scale). Default 0.01. */
+    step?: number;
+    /**
+     * Iteration cap. The default covers the full lightness range at the
+     * default step with headroom, so the walk always terminates at a pole
+     * before hitting it in practice.
+     */
+    maxSteps?: number;
+};
+/**
+ * Exact WCAG relative luminance. MUI's `getLuminance` truncates to three
+ * digits, which is enough slop to misclassify a borderline shade either side
+ * of the 4.5:1 bar — the whole reason this module exists — so the math here
+ * keeps full precision. Alpha is ignored (this pipeline derives opaque
+ * tokens), matching MUI's behaviour for rgba inputs.
+ */
+export declare function relativeLuminance(color: string): number;
+/** Exact WCAG contrast ratio between two colors, 1–21. */
+export declare function contrastRatio(colorA: string, colorB: string): number;
+/** True when `foreground` clears `minContrast` against EVERY background. */
+export declare function meetsContrast(foreground: string, backgrounds: ReadonlyArray<string>, minContrast?: number): boolean;
+/**
+ * Nearest shade of `color`, walking HSL lightness in `direction` only, that
+ * clears `minContrast` against every background (AGL-1297). Hue and
+ * saturation are held fixed so the result stays the same colour, just
+ * deeper or lighter.
+ *
+ * - If `color` already clears the bar, it is returned UNCHANGED —
+ *   byte-identical, so a value that was fine yesterday stays byte-stable.
+ * - The walk is one-directional: pass `'darken'` for a foreground on light
+ *   backgrounds, `'lighten'` for a foreground on dark backgrounds.
+ * - If the bar is unreachable in that direction (e.g. lightening against a
+ *   mid-grey), the walk stops at the pole (black/white) or the iteration
+ *   cap and returns that best-effort value rather than looping or
+ *   reversing direction.
+ */
+export declare function accessibleShade(color: string, backgrounds: ReadonlyArray<string>, direction: ShadeDirection, options?: AccessibleShadeOptions): string;
+export default accessibleShade;