@ksmv/ui-checks 0.22.0 → 0.23.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.23.2 - 2026-10-19
+
+- **Nem a 0.23.0 nem a 0.23.1 foram publicadas.** A release do `@ksmv/ui-react` parou nas duas, na suíte de navegadores, e as do checks, que saem junto com ela, ficaram retidas no npm sem aprovação. Nada mudou no pacote desde então: de 0.22.1, atualize direto para a 0.23.2. As tags `checks-v0.23.0` e `checks-v0.23.1` existem no repositório, mas não têm versão no registro.
+- **Contratos de tema 3.5.0 e de contraste 13.0.0** empacotados (#397 a #401). O de tema ganha 70 derivados opcionais (338 no total); o de contraste ganha 115 pares e altera um (451 no total). Nenhum par sai. Atualize o `@ksmv/ui-react` junto (ver o CHANGELOG dele).
+- **O contrato de contraste passa ao `schemaVersion` 3:** um par pode medir a opacidade de um grupo. Com `opacity`, o par compõe o texto e o fundo esmaecidos sobre a superfície de fora (`over`), e `group` dá o fundo próprio do grupo; uma opacidade sem `over` é recusada. A versão anterior do `@ksmv/ui-checks` recusa o schema 3.
+- **Quem usa `computedEvidence` precisa capturar a evidência de novo:** os dois contratos mudaram, e um par com opacidade exige o `group` e o `over` na evidência.
+
+## 0.22.1 - 2026-10-17
+
+- **Contratos de tema 3.4.0 e de contraste 12.0.0** empacotados (#394). O de tema ganha o derivado opcional `--ui-surface-inverse-end`, a ponta do degradê da superfície inversa; o de contraste ganha 20 pares: o texto apagado sobre a superfície inversa (`inverse-muted-text`) e cada par de um derivado `-on-inverse` sobre a superfície medido também sobre a ponta (contexto `-end`). Nenhum par sai. Um tema que não declara nenhum dos dois tokens passa como antes.
+- **A regra `tokens/contrast` mede um par na ponta de um degradê ao longo dele:** um token `<início>-end`, quando o início também é um token, é a ponta de um degradê, e o par é medido em 17 pontos, em sRGB e em Oklab (os espaços em que o navegador interpola um degradê que não declara espaço), com o alfa pré-multiplicado, ficando com o pior. Um texto que passa nas duas pontas pode reprovar no meio.
+- **Quem usa `computedEvidence` precisa capturar a evidência de novo:** os dois contratos mudaram.
+
 ## 0.22.0 - 2026-10-17
 
 - **Contratos de tema 3.3.0 e de contraste 11.0.0** empacotados. O de tema ganha 89 derivados opcionais e 5 tokens de forma; o de contraste ganha 104 pares. Nenhum par sai. Os pares do pressionado contra as superfícies e os da linha com tom são obrigações novas, e um tema com o primário claro demais, ou com um fundo de tom escuro, reprova. Atualize o `@ksmv/ui-react` junto (ver o CHANGELOG dele).

package/README.md

@@ -1,6 +1,6 @@
 # @ksmv/ui-checks
 
-Verificações de qualidade para o contrato semântico `--ui-*` de `@ksmv/ui-react`: completude dos temas, contraste dos pares do contrato (ações, estados, campos, controles e, desde o contrato de contraste `3.0.0`, o texto base sobre as superfícies e, desde o `4.0.0`, a cor de link e, desde o `5.0.0`, a borda das ações e, desde o `6.0.0`, as variantes de ação da 0.17.0 e o botão de texto e, desde o `7.0.0`, os botões da casa da 0.18.1 e o hover por tom do botão de texto e, desde o `7.1.0`, o texto de hover dos botões suaves e do contorno de aviso e, desde o `9.0.0`, o texto, o limite de controle, o link, o botão de texto e o fantasma sobre a superfície inversa, a paleta categórica, a descrição do diálogo, o giro contra a superfície, o aviso e o rótulo de seção, o item de menu e o cartão de rádio, o cabeçalho da tabela e o grupo de alternância, e o selo cheio, a bolinha sobre a superfície inversa e a barra e, desde o `10.0.0`, o fundo do botão de ícone contornado, a cor da ajuda e a caixa de seleção e, desde o `11.0.0`, o botão pressionado contra as superfícies, a linha da lista com tom, o selo com marca à frente, o cabeçalho de página e a métrica, os passos e a navegação lateral, a conversa e a mídia, a escolha de horário e de dia, a grade de calendário e o quadro), prefixo dos tokens, cores literais fora dos arquivos de tema e evidência calculada vinculada às fontes.
+Verificações de qualidade para o contrato semântico `--ui-*` de `@ksmv/ui-react`: completude dos temas, contraste dos pares do contrato (ações, estados, campos, controles e, desde o contrato de contraste `3.0.0`, o texto base sobre as superfícies e, desde o `4.0.0`, a cor de link e, desde o `5.0.0`, a borda das ações e, desde o `6.0.0`, as variantes de ação da 0.17.0 e o botão de texto e, desde o `7.0.0`, os botões da casa da 0.18.1 e o hover por tom do botão de texto e, desde o `7.1.0`, o texto de hover dos botões suaves e do contorno de aviso e, desde o `9.0.0`, o texto, o limite de controle, o link, o botão de texto e o fantasma sobre a superfície inversa, a paleta categórica, a descrição do diálogo, o giro contra a superfície, o aviso e o rótulo de seção, o item de menu e o cartão de rádio, o cabeçalho da tabela e o grupo de alternância, e o selo cheio, a bolinha sobre a superfície inversa e a barra e, desde o `10.0.0`, o fundo do botão de ícone contornado, a cor da ajuda e a caixa de seleção e, desde o `11.0.0`, o botão pressionado contra as superfícies, a linha da lista com tom, o selo com marca à frente, o cabeçalho de página e a métrica, os passos e a navegação lateral, a conversa e a mídia, a escolha de horário e de dia, a grade de calendário e o quadro e, desde o `12.0.0`, o texto apagado sobre a superfície inversa e cada par da superfície inversa medido também sobre a ponta do degradê e, desde o `13.0.0`, a caixa redonda, a linha de lista com o hover, a feita e o título como link, e os passos por fazer, com a opacidade de grupo, e a mídia na bolha, o documento por tom e o áudio), prefixo dos tokens, cores literais fora dos arquivos de tema e evidência calculada vinculada às fontes.
 
 A regra `css/no-literal-color` recusa cor literal fora dos temas configurados. Desde a 0.22.0, ela aceita uma exceção: o fallback de `var(--ui-x, <cor>)`, quando a cor é, texto por texto, o padrão literal que o contrato de tema dá à própria `--ui-x` (como `var(--ui-media-overlay-bg, rgb(0 0 0 / 70%))`). Quem escreve esse fallback implementa o contrato. Outra cor, ainda que equivalente, uma cor fora do `var()` ou o fallback de um token sem padrão literal continuam reprovados.
 
@@ -97,6 +97,8 @@ config Invalid computed theme evidence in artifacts/theme-evidence.json: the the
 
 Depois de atualizar o pacote React, a mensagem traz a versão do contrato da captura e a do contrato instalado; quando faltam tokens ou resta `var(...)`, traz os nomes dos tokens, em ordem, até dez, e a contagem dos demais. A mensagem não repete valores do produto: aparecem só o caminho da evidência e o nome do tema como estão na configuração, nomes de tokens e versões de contrato. Falha ao resolver os contratos também é relatada com a própria causa (`Unable to resolve the configured contract source.`, `Unsupported theme contract.` ou `Unsupported contrast manifest.`).
 
+Desde o contrato de contraste `13.0.0` (`schemaVersion` 3), um par pode medir a opacidade de um grupo, como a linha feita a 0,75: `opacity` dá a opacidade, `over` a superfície opaca fora do grupo e, quando o texto está numa camada dentro dele, `group` o fundo do elemento que tem a opacidade. A regra pinta o grupo guardando o alfa e compõe o resultado, com a opacidade, sobre `over`; um degradê (um token `-end`) em qualquer camada é medido ao longo dele, e vale o pior ponto; um par sem `over`, com uma camada que não resolve ou com a superfície de fora translúcida fica sem cobertura, nunca aprovado. A evidência calculada precisa trazer todas as camadas de cada par (o texto, o fundo, `over` e `group`).
+
 Tokens opcionais, os derivados e os de marca, podem ficar vazios na captura: é assim que o navegador informa um token que o tema não declarou. Um derivado vazio assume o valor do token de origem, que é o padrão documentado no contrato. Quando a origem também é um derivado, como no texto do hover do contorno de aviso (`--ui-action-warning-outline-text-hover` deriva de `--ui-action-warning-outline-text`, que deriva do contorno de perigo), a cadeia é seguida até um token declarado. Um derivado que é ponta de um par de contraste, como `--ui-control-checked-bg`, também pode ficar vazio; a captura precisa então do token em que a cadeia dele termina. Sem evidência, `tokens/contrast` segue a mesma cadeia: um derivado que o tema não declara é avaliado pelo valor da origem, ou pelo padrão literal do contrato (`transparent`, uma cor). Um par com `over` mede um fundo translúcido composto sobre aquela superfície; sem `over`, um fundo translúcido continua cobertura pendente.
 
 Desde o contrato de tema `3.0.0`, a forma é da biblioteca: a regra `themes/no-shape` aponta, como violação, cada token da lista `shape` do contrato que um seletor de tema declarar. Quem migra de um tema que declarava forma pode carregar essas violações na baseline enquanto tira as linhas.

package/dist/color.d.ts

@@ -18,5 +18,8 @@ export declare function containsLiteralColor(value: string, contractDefaults?: R
 export declare function referencedTokens(value: string): string[];
 export declare function unresolvedTokenReferences(value: string, tokens: ReadonlyMap<string, string>, stack?: ReadonlySet<string>): string[];
 export declare function resolveColor(value: string | undefined, tokens: ReadonlyMap<string, string>, stack?: ReadonlySet<string>): ColorResolution;
+export declare function paintOver(top: RgbColor, bottom: RgbColor): RgbColor;
+export declare function faded(color: RgbColor, opacity: number): RgbColor;
 export declare function composite(foreground: RgbColor, background: RgbColor): RgbColor;
+export declare function mix(start: RgbColor, end: RgbColor, at: number): RgbColor[];
 export declare function contrastRatio(foreground: RgbColor, background: RgbColor): number | undefined;

package/dist/color.js

@@ -1,6 +1,7 @@
 import { converter, parse } from "culori";
 import valueParser from "postcss-value-parser";
 const toRgb = converter("rgb");
+const toOklab = converter("oklab");
 const unsupportedFunctions = new Set(["color-mix", "light-dark"]);
 const literalColorFunctions = new Set([
     "color",
@@ -186,6 +187,19 @@ export function resolveColor(value, tokens, stack = new Set()) {
     const color = parsedColor(value.trim());
     return color ? { color, status: "resolved" } : { status: "uncovered" };
 }
+// One color painted over another, keeping the alpha of the result (Porter-Duff
+// source-over), for a layer that is itself translucent: a group's paint
+// before its opacity. composite() below assumes an opaque background.
+export function paintOver(top, bottom) {
+    const [topAlpha, bottomAlpha] = [top.alpha ?? 1, bottom.alpha ?? 1];
+    const alpha = topAlpha + bottomAlpha * (1 - topAlpha);
+    const channel = (upper, lower) => alpha === 0 ? 0 : (upper * topAlpha + lower * bottomAlpha * (1 - topAlpha)) / alpha;
+    return { alpha, b: channel(top.b, bottom.b), g: channel(top.g, bottom.g), mode: "rgb", r: channel(top.r, bottom.r) };
+}
+// A color under a group's opacity: its alpha scaled by it.
+export function faded(color, opacity) {
+    return { ...color, alpha: (color.alpha ?? 1) * opacity };
+}
 export function composite(foreground, background) {
     const alpha = foreground.alpha ?? 1;
     return {
@@ -195,6 +209,21 @@ export function composite(foreground, background) {
         r: foreground.r * alpha + background.r * (1 - alpha),
     };
 }
+// A point of a gradient between two colors. The browser interpolates legacy
+// colors (hex, rgb(), hsl()) in sRGB and the others, as oklch(), in Oklab
+// (CSS Color 4, §12.1); the space is chosen by the syntax, so the check takes
+// both points. Both interpolate with premultiplied alpha (§12.3): a channel
+// is weighted by its color's alpha, so a transparent end lends no hue.
+export function mix(start, end, at) {
+    const [startAlpha, endAlpha] = [start.alpha ?? 1, end.alpha ?? 1];
+    const alpha = startAlpha + (endAlpha - startAlpha) * at;
+    const between = (from, to) => alpha === 0 ? 0 : (from * startAlpha + (to * endAlpha - from * startAlpha) * at) / alpha;
+    const srgb = { alpha, b: between(start.b, end.b), g: between(start.g, end.g), mode: "rgb", r: between(start.r, end.r) };
+    const [from, to] = [toOklab(start), toOklab(end)];
+    const clamp = (value) => Math.min(1, Math.max(0, value));
+    const oklab = toRgb({ a: between(from.a, to.a), alpha, b: between(from.b, to.b), l: between(from.l, to.l), mode: "oklab" });
+    return [srgb, { alpha, b: clamp(oklab.b), g: clamp(oklab.g), mode: "rgb", r: clamp(oklab.r) }];
+}
 function luminance(color) {
     const channel = (value) => value <= 0.04045
         ? value / 12.92

package/dist/contracts.d.ts

@@ -29,13 +29,21 @@ export interface ContrastPair {
     context: string;
     foreground: string;
     minimum: number;
-    /** The surface under a background that may be translucent (schema 2). */
+    /** The background of the element that has the opacity, when the text sits on
+     * a layer inside it, as a marker inside a card (schema 3). Without it, the
+     * background is the element's own and is painted once. */
+    group?: string;
+    /** The opacity of a group around the pair, as a done row's 0.75 (schema 3).
+     * It needs the opaque surface outside the group in over. */
+    opacity?: number;
+    /** The surface under a background that may be translucent (schema 2), or
+     * the surface outside a group with an opacity (schema 3). */
     over?: string;
 }
 export interface ContrastManifest {
     contractVersion: string;
     pairs: ContrastPair[];
-    schemaVersion: 2;
+    schemaVersion: 2 | 3;
 }
 export interface ContractIdentity {
     contractVersion: string;

package/dist/contracts.js

@@ -96,18 +96,20 @@ export function parseContrastManifest(content) {
     }
     if (!isRecord(value) ||
         !exactKeys(value, ["contractVersion", "pairs", "schemaVersion"]) ||
-        value.schemaVersion !== 2 ||
+        (value.schemaVersion !== 2 && value.schemaVersion !== 3) ||
         typeof value.contractVersion !== "string" ||
         !semverPattern.test(value.contractVersion) ||
         !Array.isArray(value.pairs)) {
         throw new CheckSetupError("Unsupported contrast manifest.");
     }
+    const schema = value.schemaVersion;
     const identities = [];
     for (const pair of value.pairs) {
         if (!isRecord(pair) ||
             !(exactKeys(pair, ["background", "context", "foreground", "minimum"]) ||
                 (exactKeys(pair, ["background", "context", "foreground", "minimum", "over"]) &&
-                    typeof pair.over === "string" && tokenNamePattern.test(pair.over))) ||
+                    typeof pair.over === "string" && tokenNamePattern.test(pair.over)) ||
+                (schema === 3 && isGroupPair(pair))) ||
             typeof pair.background !== "string" ||
             !tokenNamePattern.test(pair.background) ||
             typeof pair.foreground !== "string" ||
@@ -119,13 +121,26 @@ export function parseContrastManifest(content) {
             pair.minimum <= 0) {
             throw new CheckSetupError("Unsupported contrast manifest.");
         }
-        identities.push(`${pair.context}\u0000${pair.foreground}\u0000${pair.background}\u0000${pair.over ?? ""}`);
+        identities.push(`${pair.context}\u0000${pair.foreground}\u0000${pair.background}\u0000${pair.over ?? ""}\u0000${pair.group ?? ""}\u0000${pair.opacity ?? ""}`);
     }
     if (new Set(identities).size !== identities.length) {
         throw new CheckSetupError("Unsupported contrast manifest.");
     }
     return value;
 }
+// A pair under a group's opacity (schema 3): the opacity in (0, 1], the
+// opaque surface outside the group in over, and the group's own background
+// when the text sits on a layer inside it.
+function isGroupPair(pair) {
+    const keys = ["background", "context", "foreground", "minimum", "opacity", "over"];
+    return ((exactKeys(pair, keys) || (exactKeys(pair, [...keys, "group"]) && typeof pair.group === "string" && tokenNamePattern.test(pair.group))) &&
+        typeof pair.opacity === "number" &&
+        Number.isFinite(pair.opacity) &&
+        pair.opacity > 0 &&
+        pair.opacity <= 1 &&
+        typeof pair.over === "string" &&
+        tokenNamePattern.test(pair.over));
+}
 function identity(content, contractVersion) {
     return {
         contractVersion,

package/dist/contrast-contract.json

@@ -1,6 +1,6 @@
 {
-  "contractVersion": "11.0.0",
-  "schemaVersion": 2,
+  "contractVersion": "13.0.0",
+  "schemaVersion": 3,
   "pairs": [
     { "foreground": "--ui-action-primary-text", "background": "--ui-action-primary-bg", "minimum": 4.5, "context": "normal-text" },
     { "foreground": "--ui-action-primary-text", "background": "--ui-action-primary-bg-hover", "minimum": 4.5, "context": "normal-text-hover" },
@@ -259,7 +259,7 @@
     { "foreground": "--ui-side-nav-count-text-on-inverse", "background": "--ui-side-nav-count-bg-on-inverse", "over": "--ui-surface-inverse", "minimum": 4.5, "context": "side-nav-count-text-on-inverse" },
     { "foreground": "--ui-steps-current", "background": "--ui-steps-current-bg", "over": "--ui-surface", "minimum": 3, "context": "steps-current-boundary" },
     { "foreground": "--ui-steps-current", "background": "--ui-surface", "minimum": 3, "context": "steps-current-border" },
-    { "foreground": "--ui-steps-current", "background": "--ui-surface", "minimum": 3, "context": "steps-complete-mark" },
+    { "foreground": "--ui-steps-current", "background": "--ui-steps-complete-marker-bg", "minimum": 3, "context": "steps-complete-mark" },
     { "foreground": "--ui-steps-track-filled", "background": "--ui-surface", "minimum": 3, "context": "steps-track-filled" },
     { "foreground": "--ui-side-nav-count-dot", "background": "--ui-surface", "minimum": 3, "context": "side-nav-count-dot" },
     { "foreground": "--ui-message-incoming-text", "background": "--ui-message-incoming-bg", "over": "--ui-surface", "minimum": 4.5, "context": "message-incoming-text" },
@@ -317,6 +317,141 @@
     { "foreground": "--ui-board-card-border-hover", "background": "--ui-surface-subtle", "minimum": 3, "context": "board-card-border-hover" },
     { "foreground": "--ui-board-drop-border", "background": "--ui-surface-subtle", "minimum": 3, "context": "board-drop-border" },
     { "foreground": "--ui-board-drop-border", "background": "--ui-board-drop-bg", "over": "--ui-surface-subtle", "minimum": 3, "context": "board-drop-line" },
-    { "foreground": "--ui-border-control", "background": "--ui-surface-subtle", "minimum": 3, "context": "board-placeholder-boundary" }
+    { "foreground": "--ui-border-control", "background": "--ui-surface-subtle", "minimum": 3, "context": "board-placeholder-boundary" },
+    { "foreground": "--ui-text-muted-on-inverse", "background": "--ui-surface-inverse", "minimum": 4.5, "context": "inverse-muted-text" },
+    { "foreground": "--ui-text-primary-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 4.5, "context": "inverse-body-text-end" },
+    { "foreground": "--ui-text-secondary-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 4.5, "context": "inverse-secondary-text-end" },
+    { "foreground": "--ui-border-control-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 3, "context": "inverse-control-boundary-end" },
+    { "foreground": "--ui-link-text-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 4.5, "context": "inverse-link-text-end" },
+    { "foreground": "--ui-text-button-text-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 4.5, "context": "inverse-text-button-text-end" },
+    { "foreground": "--ui-action-ghost-text-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 4.5, "context": "inverse-ghost-text-end" },
+    { "foreground": "--ui-action-ghost-text-hover-on-inverse", "background": "--ui-action-ghost-bg-hover-on-inverse", "over": "--ui-surface-inverse-end", "minimum": 4.5, "context": "inverse-ghost-text-hover-end" },
+    { "foreground": "--ui-action-ghost-text-hover-on-inverse", "background": "--ui-action-ghost-bg-active-on-inverse", "over": "--ui-surface-inverse-end", "minimum": 4.5, "context": "inverse-ghost-text-active-end" },
+    { "foreground": "--ui-icon-button-ghost-text-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 3, "context": "inverse-icon-button-ghost-icon-end" },
+    { "foreground": "--ui-icon-button-ghost-text-on-inverse", "background": "--ui-action-ghost-bg-hover-on-inverse", "over": "--ui-surface-inverse-end", "minimum": 3, "context": "inverse-icon-button-ghost-icon-hover-end" },
+    { "foreground": "--ui-icon-button-ghost-text-on-inverse", "background": "--ui-action-ghost-bg-active-on-inverse", "over": "--ui-surface-inverse-end", "minimum": 3, "context": "inverse-icon-button-ghost-icon-active-end" },
+    { "foreground": "--ui-status-success-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 3, "context": "status-indicator-success-on-inverse-end" },
+    { "foreground": "--ui-status-warning-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 3, "context": "status-indicator-warning-on-inverse-end" },
+    { "foreground": "--ui-status-danger-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 3, "context": "status-indicator-danger-on-inverse-end" },
+    { "foreground": "--ui-status-info-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 3, "context": "status-indicator-info-on-inverse-end" },
+    { "foreground": "--ui-button-pressed-bg-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 3, "context": "button-pressed-boundary-on-inverse-end" },
+    { "foreground": "--ui-button-pressed-bg-hover-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 3, "context": "button-pressed-boundary-hover-on-inverse-end" },
+    { "foreground": "--ui-side-nav-count-text-on-inverse", "background": "--ui-side-nav-count-bg-on-inverse", "over": "--ui-surface-inverse-end", "minimum": 4.5, "context": "side-nav-count-text-on-inverse-end" },
+    { "foreground": "--ui-text-muted-on-inverse", "background": "--ui-surface-inverse-end", "minimum": 4.5, "context": "inverse-muted-text-end" },
+    { "foreground": "--ui-checkbox-border", "background": "--ui-checkbox-circle-bg", "over": "--ui-surface", "minimum": 3, "context": "checkbox-circle-ring" },
+    { "foreground": "--ui-checkbox-circle-hover", "background": "--ui-checkbox-circle-bg", "over": "--ui-surface", "minimum": 3, "context": "checkbox-circle-ring-hover" },
+    { "foreground": "--ui-checkbox-border", "background": "--ui-checkbox-circle-bg", "over": "--ui-surface-raised", "minimum": 3, "context": "checkbox-circle-ring-raised" },
+    { "foreground": "--ui-checkbox-circle-hover", "background": "--ui-checkbox-circle-bg", "over": "--ui-surface-raised", "minimum": 3, "context": "checkbox-circle-ring-hover-raised" },
+    { "foreground": "--ui-checkbox-border", "background": "--ui-checkbox-circle-bg", "over": "--ui-surface-subtle", "minimum": 3, "context": "checkbox-circle-ring-subtle" },
+    { "foreground": "--ui-checkbox-circle-hover", "background": "--ui-checkbox-circle-bg", "over": "--ui-surface-subtle", "minimum": 3, "context": "checkbox-circle-ring-hover-subtle" },
+    { "foreground": "--ui-text-primary", "background": "--ui-list-item-success-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-title-success-hover" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-list-item-success-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-description-success-hover" },
+    { "foreground": "--ui-text-primary", "background": "--ui-list-item-warning-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-title-warning-hover" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-list-item-warning-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-description-warning-hover" },
+    { "foreground": "--ui-text-primary", "background": "--ui-list-item-danger-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-title-danger-hover" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-list-item-danger-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-description-danger-hover" },
+    { "foreground": "--ui-text-primary", "background": "--ui-list-item-info-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-title-info-hover" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-list-item-info-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-description-info-hover" },
+    { "foreground": "--ui-text-primary", "background": "--ui-list-item-success-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-title-success-hover-raised" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-list-item-success-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-description-success-hover-raised" },
+    { "foreground": "--ui-text-primary", "background": "--ui-list-item-warning-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-title-warning-hover-raised" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-list-item-warning-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-description-warning-hover-raised" },
+    { "foreground": "--ui-text-primary", "background": "--ui-list-item-danger-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-title-danger-hover-raised" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-list-item-danger-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-description-danger-hover-raised" },
+    { "foreground": "--ui-text-primary", "background": "--ui-list-item-info-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-title-info-hover-raised" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-list-item-info-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-description-info-hover-raised" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-success-bg", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover-success" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-success-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover-success-hover" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-warning-bg", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover-warning" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-warning-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover-warning-hover" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-danger-bg", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover-danger" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-danger-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover-danger-hover" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-info-bg", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover-info" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-info-bg-hover", "over": "--ui-surface", "minimum": 4.5, "context": "list-item-link-hover-info-hover" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-success-bg", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-link-hover-success-raised" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-success-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-link-hover-success-hover-raised" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-warning-bg", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-link-hover-warning-raised" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-warning-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-link-hover-warning-hover-raised" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-danger-bg", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-link-hover-danger-raised" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-danger-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-link-hover-danger-hover-raised" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-info-bg", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-link-hover-info-raised" },
+    { "foreground": "--ui-list-item-title-hover", "background": "--ui-list-item-info-bg-hover", "over": "--ui-surface-raised", "minimum": 4.5, "context": "list-item-link-hover-info-hover-raised" },
+    { "foreground": "--ui-list-item-done-title", "background": "--ui-surface-subtle", "over": "--ui-surface", "opacity": 0.75, "minimum": 4.5, "context": "list-item-done-title" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-surface-subtle", "over": "--ui-surface", "opacity": 0.75, "minimum": 4.5, "context": "list-item-done-description" },
+    { "foreground": "--ui-control-checked-bg", "background": "--ui-surface-subtle", "over": "--ui-surface", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-disc" },
+    { "foreground": "--ui-checkbox-mark", "background": "--ui-control-checked-bg", "group": "--ui-surface-subtle", "over": "--ui-surface", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-mark" },
+    { "foreground": "--ui-list-item-done-title", "background": "--ui-surface-subtle", "over": "--ui-surface-raised", "opacity": 0.75, "minimum": 4.5, "context": "list-item-done-title-raised" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-surface-subtle", "over": "--ui-surface-raised", "opacity": 0.75, "minimum": 4.5, "context": "list-item-done-description-raised" },
+    { "foreground": "--ui-control-checked-bg", "background": "--ui-surface-subtle", "over": "--ui-surface-raised", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-disc-raised" },
+    { "foreground": "--ui-checkbox-mark", "background": "--ui-control-checked-bg", "group": "--ui-surface-subtle", "over": "--ui-surface-raised", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-mark-raised" },
+    { "foreground": "--ui-list-item-done-title", "background": "--ui-surface-subtle", "over": "--ui-surface-subtle", "opacity": 0.75, "minimum": 4.5, "context": "list-item-done-title-subtle" },
+    { "foreground": "--ui-text-secondary", "background": "--ui-surface-subtle", "over": "--ui-surface-subtle", "opacity": 0.75, "minimum": 4.5, "context": "list-item-done-description-subtle" },
+    { "foreground": "--ui-control-checked-bg", "background": "--ui-surface-subtle", "over": "--ui-surface-subtle", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-disc-subtle" },
+    { "foreground": "--ui-checkbox-mark", "background": "--ui-control-checked-bg", "group": "--ui-surface-subtle", "over": "--ui-surface-subtle", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-mark-subtle" },
+    { "foreground": "--ui-list-item-done-ring", "background": "--ui-checkbox-circle-bg", "group": "--ui-surface-subtle", "over": "--ui-surface", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-ring" },
+    { "foreground": "--ui-checkbox-circle-hover", "background": "--ui-checkbox-circle-bg", "group": "--ui-surface-subtle", "over": "--ui-surface", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-ring-hover" },
+    { "foreground": "--ui-list-item-done-ring", "background": "--ui-checkbox-circle-bg", "group": "--ui-surface-subtle", "over": "--ui-surface-raised", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-ring-raised" },
+    { "foreground": "--ui-checkbox-circle-hover", "background": "--ui-checkbox-circle-bg", "group": "--ui-surface-subtle", "over": "--ui-surface-raised", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-ring-hover-raised" },
+    { "foreground": "--ui-list-item-done-ring", "background": "--ui-checkbox-circle-bg", "group": "--ui-surface-subtle", "over": "--ui-surface-subtle", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-ring-subtle" },
+    { "foreground": "--ui-checkbox-circle-hover", "background": "--ui-checkbox-circle-bg", "group": "--ui-surface-subtle", "over": "--ui-surface-subtle", "opacity": 0.75, "minimum": 3, "context": "list-item-done-circle-ring-hover-subtle" },
+    { "foreground": "--ui-steps-upcoming-title", "background": "--ui-surface", "over": "--ui-surface", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-title" },
+    { "foreground": "--ui-steps-upcoming-description", "background": "--ui-surface", "over": "--ui-surface", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-description" },
+    { "foreground": "--ui-steps-upcoming-marker-text", "background": "--ui-steps-upcoming-marker-bg", "group": "--ui-surface", "over": "--ui-surface", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-marker" },
+    { "foreground": "--ui-steps-upcoming-title", "background": "--ui-surface", "over": "--ui-surface-raised", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-title-raised" },
+    { "foreground": "--ui-steps-upcoming-description", "background": "--ui-surface", "over": "--ui-surface-raised", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-description-raised" },
+    { "foreground": "--ui-steps-upcoming-marker-text", "background": "--ui-steps-upcoming-marker-bg", "group": "--ui-surface", "over": "--ui-surface-raised", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-marker-raised" },
+    { "foreground": "--ui-steps-upcoming-title", "background": "--ui-surface", "over": "--ui-surface-subtle", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-title-subtle" },
+    { "foreground": "--ui-steps-upcoming-description", "background": "--ui-surface", "over": "--ui-surface-subtle", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-description-subtle" },
+    { "foreground": "--ui-steps-upcoming-marker-text", "background": "--ui-steps-upcoming-marker-bg", "group": "--ui-surface", "over": "--ui-surface-subtle", "opacity": 0.7, "minimum": 4.5, "context": "steps-upcoming-marker-subtle" },
+    { "foreground": "--ui-message-incoming-document-text", "background": "--ui-message-incoming-document-bg", "over": "--ui-message-incoming-bg", "minimum": 4.5, "context": "message-incoming-document-text" },
+    { "foreground": "--ui-message-incoming-document-meta", "background": "--ui-message-incoming-document-bg", "over": "--ui-message-incoming-bg", "minimum": 4.5, "context": "message-incoming-document-meta" },
+    { "foreground": "--ui-message-incoming-document-download-icon", "background": "--ui-message-incoming-document-download-bg", "group": "--ui-message-incoming-document-bg", "over": "--ui-message-incoming-bg", "opacity": 1, "minimum": 3, "context": "message-incoming-document-download" },
+    { "foreground": "--ui-message-incoming-document-download-icon-hover", "background": "--ui-message-incoming-document-download-bg-hover", "group": "--ui-message-incoming-document-bg", "over": "--ui-message-incoming-bg", "opacity": 1, "minimum": 3, "context": "message-incoming-document-download-hover" },
+    { "foreground": "--ui-message-assistant-document-text", "background": "--ui-message-assistant-document-bg", "over": "--ui-message-assistant-bg", "minimum": 4.5, "context": "message-assistant-document-text" },
+    { "foreground": "--ui-message-assistant-document-meta", "background": "--ui-message-assistant-document-bg", "over": "--ui-message-assistant-bg", "minimum": 4.5, "context": "message-assistant-document-meta" },
+    { "foreground": "--ui-message-assistant-document-download-icon", "background": "--ui-message-assistant-document-download-bg", "group": "--ui-message-assistant-document-bg", "over": "--ui-message-assistant-bg", "opacity": 1, "minimum": 3, "context": "message-assistant-document-download" },
+    { "foreground": "--ui-message-assistant-document-download-icon-hover", "background": "--ui-message-assistant-document-download-bg-hover", "group": "--ui-message-assistant-document-bg", "over": "--ui-message-assistant-bg", "opacity": 1, "minimum": 3, "context": "message-assistant-document-download-hover" },
+    { "foreground": "--ui-message-outgoing-document-text", "background": "--ui-message-outgoing-document-bg", "over": "--ui-message-outgoing-bg", "minimum": 4.5, "context": "message-outgoing-document-text" },
+    { "foreground": "--ui-message-outgoing-document-meta", "background": "--ui-message-outgoing-document-bg", "over": "--ui-message-outgoing-bg", "minimum": 4.5, "context": "message-outgoing-document-meta" },
+    { "foreground": "--ui-message-outgoing-document-download-icon", "background": "--ui-message-outgoing-document-download-bg", "group": "--ui-message-outgoing-document-bg", "over": "--ui-message-outgoing-bg", "opacity": 1, "minimum": 3, "context": "message-outgoing-document-download" },
+    { "foreground": "--ui-message-outgoing-document-download-icon-hover", "background": "--ui-message-outgoing-document-download-bg-hover", "group": "--ui-message-outgoing-document-bg", "over": "--ui-message-outgoing-bg", "opacity": 1, "minimum": 3, "context": "message-outgoing-document-download-hover" },
+    { "foreground": "--ui-media-enlarge-icon", "background": "--ui-media-enlarge-bg", "group": "--ui-media-thumbnail-veil", "over": "--ui-surface", "opacity": 1, "minimum": 3, "context": "media-enlarge-icon" },
+    { "foreground": "--ui-message-incoming-audio-play-icon", "background": "--ui-message-incoming-audio-play-bg", "over": "--ui-message-incoming-bg", "minimum": 3, "context": "message-incoming-audio-play" },
+    { "foreground": "--ui-message-incoming-audio-wave-played", "background": "--ui-message-incoming-bg", "over": "--ui-surface", "minimum": 3, "context": "message-incoming-audio-wave-played" },
+    { "foreground": "--ui-message-incoming-audio-wave-unplayed", "background": "--ui-message-incoming-bg", "over": "--ui-surface", "minimum": 3, "context": "message-incoming-audio-wave-unplayed" },
+    { "foreground": "--ui-message-incoming-audio-playhead", "background": "--ui-message-incoming-bg", "over": "--ui-surface", "minimum": 3, "context": "message-incoming-audio-playhead" },
+    { "foreground": "--ui-message-incoming-audio-time", "background": "--ui-message-incoming-bg", "over": "--ui-surface", "minimum": 4.5, "context": "message-incoming-audio-time" },
+    { "foreground": "--ui-message-incoming-audio-speed-text", "background": "--ui-message-incoming-audio-speed-bg", "over": "--ui-message-incoming-bg", "minimum": 4.5, "context": "message-incoming-audio-speed" },
+    { "foreground": "--ui-message-assistant-audio-play-icon", "background": "--ui-message-assistant-audio-play-bg", "over": "--ui-message-assistant-bg", "minimum": 3, "context": "message-assistant-audio-play" },
+    { "foreground": "--ui-message-assistant-audio-wave-played", "background": "--ui-message-assistant-bg", "over": "--ui-surface", "minimum": 3, "context": "message-assistant-audio-wave-played" },
+    { "foreground": "--ui-message-assistant-audio-wave-unplayed", "background": "--ui-message-assistant-bg", "over": "--ui-surface", "minimum": 3, "context": "message-assistant-audio-wave-unplayed" },
+    { "foreground": "--ui-message-assistant-audio-playhead", "background": "--ui-message-assistant-bg", "over": "--ui-surface", "minimum": 3, "context": "message-assistant-audio-playhead" },
+    { "foreground": "--ui-message-assistant-audio-time", "background": "--ui-message-assistant-bg", "over": "--ui-surface", "minimum": 4.5, "context": "message-assistant-audio-time" },
+    { "foreground": "--ui-message-assistant-audio-speed-text", "background": "--ui-message-assistant-audio-speed-bg", "over": "--ui-message-assistant-bg", "minimum": 4.5, "context": "message-assistant-audio-speed" },
+    { "foreground": "--ui-message-outgoing-audio-play-icon", "background": "--ui-message-outgoing-audio-play-bg", "over": "--ui-message-outgoing-bg", "minimum": 3, "context": "message-outgoing-audio-play" },
+    { "foreground": "--ui-message-outgoing-audio-wave-played", "background": "--ui-message-outgoing-bg", "over": "--ui-surface", "minimum": 3, "context": "message-outgoing-audio-wave-played" },
+    { "foreground": "--ui-message-outgoing-audio-wave-unplayed", "background": "--ui-message-outgoing-bg", "over": "--ui-surface", "minimum": 3, "context": "message-outgoing-audio-wave-unplayed" },
+    { "foreground": "--ui-message-outgoing-audio-playhead", "background": "--ui-message-outgoing-bg", "over": "--ui-surface", "minimum": 3, "context": "message-outgoing-audio-playhead" },
+    { "foreground": "--ui-message-outgoing-audio-time", "background": "--ui-message-outgoing-bg", "over": "--ui-surface", "minimum": 4.5, "context": "message-outgoing-audio-time" },
+    { "foreground": "--ui-message-outgoing-audio-speed-text", "background": "--ui-message-outgoing-audio-speed-bg", "over": "--ui-message-outgoing-bg", "minimum": 4.5, "context": "message-outgoing-audio-speed" },
+    { "foreground": "--ui-message-incoming-audio-play-icon", "background": "--ui-message-incoming-audio-play-bg", "over": "--ui-surface", "minimum": 3, "context": "audio-play" },
+    { "foreground": "--ui-message-incoming-audio-wave-played", "background": "--ui-surface", "minimum": 3, "context": "audio-wave-played" },
+    { "foreground": "--ui-message-incoming-audio-wave-unplayed", "background": "--ui-surface", "minimum": 3, "context": "audio-wave-unplayed" },
+    { "foreground": "--ui-message-incoming-audio-playhead", "background": "--ui-surface", "minimum": 3, "context": "audio-playhead" },
+    { "foreground": "--ui-message-incoming-audio-time", "background": "--ui-surface", "minimum": 4.5, "context": "audio-time" },
+    { "foreground": "--ui-message-incoming-audio-speed-text", "background": "--ui-message-incoming-audio-speed-bg", "over": "--ui-surface", "minimum": 4.5, "context": "audio-speed" },
+    { "foreground": "--ui-message-incoming-audio-play-icon", "background": "--ui-message-incoming-audio-play-bg", "over": "--ui-surface-raised", "minimum": 3, "context": "audio-play-raised" },
+    { "foreground": "--ui-message-incoming-audio-wave-played", "background": "--ui-surface-raised", "minimum": 3, "context": "audio-wave-played-raised" },
+    { "foreground": "--ui-message-incoming-audio-wave-unplayed", "background": "--ui-surface-raised", "minimum": 3, "context": "audio-wave-unplayed-raised" },
+    { "foreground": "--ui-message-incoming-audio-playhead", "background": "--ui-surface-raised", "minimum": 3, "context": "audio-playhead-raised" },
+    { "foreground": "--ui-message-incoming-audio-time", "background": "--ui-surface-raised", "minimum": 4.5, "context": "audio-time-raised" },
+    { "foreground": "--ui-message-incoming-audio-speed-text", "background": "--ui-message-incoming-audio-speed-bg", "over": "--ui-surface-raised", "minimum": 4.5, "context": "audio-speed-raised" },
+    { "foreground": "--ui-message-incoming-audio-play-icon", "background": "--ui-message-incoming-audio-play-bg", "over": "--ui-surface-subtle", "minimum": 3, "context": "audio-play-subtle" },
+    { "foreground": "--ui-message-incoming-audio-wave-played", "background": "--ui-surface-subtle", "minimum": 3, "context": "audio-wave-played-subtle" },
+    { "foreground": "--ui-message-incoming-audio-wave-unplayed", "background": "--ui-surface-subtle", "minimum": 3, "context": "audio-wave-unplayed-subtle" },
+    { "foreground": "--ui-message-incoming-audio-playhead", "background": "--ui-surface-subtle", "minimum": 3, "context": "audio-playhead-subtle" },
+    { "foreground": "--ui-message-incoming-audio-time", "background": "--ui-surface-subtle", "minimum": 4.5, "context": "audio-time-subtle" },
+    { "foreground": "--ui-message-incoming-audio-speed-text", "background": "--ui-message-incoming-audio-speed-bg", "over": "--ui-surface-subtle", "minimum": 4.5, "context": "audio-speed-subtle" }
   ]
 }

package/dist/rules/tokenContrast.js

@@ -1,7 +1,73 @@
 import { isComputedPropertyName, isIdentifier, isJsxAttribute, isJsxExpression, isObjectLiteralExpression, isPropertyAssignment, isJsxSpreadAttribute, isStringLiteralLikeNode, } from "typescript/unstable/ast";
-import { composite, contrastRatio, isColorBearingProperty, resolveColor, } from "../color.js";
+import { composite, contrastRatio, faded, isColorBearingProperty, mix, paintOver, resolveColor, } from "../color.js";
 import { parseContrastManifest, } from "../contracts.js";
 import { createThemeCollector } from "./theme.js";
+// The end of a gradient (#394): a token named <start>-end, when the start is
+// a token too, paints a gradient from the start to itself. A pair on it is
+// measured along the whole gradient, and not only at the end: between two
+// colors that pass, the mix can fall below the minimum, as when the text's
+// luminance lies between the two ends. Each point is taken in sRGB and in
+// Oklab, the two spaces a browser may interpolate in.
+const gradientSteps = 16;
+function resolveAlong(token, tokens) {
+    const end = resolveColor(tokens.get(token), tokens);
+    const startName = token.endsWith("-end") ? token.slice(0, -"-end".length) : undefined;
+    if (!startName || !tokens.has(startName))
+        return [end];
+    const start = resolveColor(tokens.get(startName), tokens);
+    if (start.status !== "resolved" || end.status !== "resolved")
+        return [{ status: "uncovered" }];
+    return Array.from({ length: gradientSteps + 1 }, (_, step) => mix(start.color, end.color, step / gradientSteps))
+        .flat()
+        .map((color) => ({ color, status: "resolved" }));
+}
+function groupRatio(pair, tokens) {
+    const opacity = pair.opacity;
+    const foreground = resolveColor(tokens.get(pair.foreground), tokens);
+    const backgrounds = resolveAlong(pair.background, tokens);
+    const groups = pair.group === undefined ? [undefined] : resolveAlong(pair.group, tokens);
+    const surfaces = pair.over === undefined ? [] : resolveAlong(pair.over, tokens);
+    if (foreground.status !== "resolved" ||
+        [...backgrounds, ...groups, ...surfaces].some((layer) => layer !== undefined && layer.status !== "resolved") ||
+        surfaces.length === 0) {
+        return "uncovered";
+    }
+    let worst = Infinity;
+    for (const background of backgrounds) {
+        for (const group of groups) {
+            if (background.status !== "resolved" || group?.status === "uncovered")
+                return "uncovered";
+            const inner = group?.status === "resolved" ? paintOver(background.color, group.color) : background.color;
+            const text = paintOver(foreground.color, inner);
+            for (const surface of surfaces) {
+                if (surface.status !== "resolved" || (surface.color.alpha ?? 1) < 1)
+                    return "translucent";
+                const seenBackground = composite(faded(inner, opacity), surface.color);
+                const seenText = composite(faded(text, opacity), surface.color);
+                const ratio = contrastRatio(seenText, seenBackground);
+                if (ratio === undefined)
+                    return "translucent";
+                worst = Math.min(worst, ratio);
+            }
+        }
+    }
+    return worst;
+}
+function reportPair(result, location, themeName, pair, ratio) {
+    // A group pair (schema 3) may differ from another only by its group, the
+    // surface outside or the opacity: they are in its fingerprint. The pairs
+    // before schema 3 keep theirs, so a baseline stays valid.
+    const nodeKind = `contrast-pair:${pair.context}:${pair.foreground}:${pair.background}:${pair.group ?? ""}:${pair.over}:${pair.opacity}`;
+    if (ratio === "uncovered") {
+        result.uncovered.push({ ...location, message: `Contrast pair ${pair.context} could not be resolved.`, nodeKind, rule: "tokens/contrast", required: true });
+    }
+    else if (ratio === "translucent") {
+        result.uncovered.push({ ...location, message: `Contrast pair ${pair.context} requires a known opaque background.`, nodeKind, rule: "tokens/contrast", required: true });
+    }
+    else if (ratio < pair.minimum) {
+        result.violations.push({ ...location, anchor: themeName, message: `Contrast pair ${pair.context} is below ${pair.minimum}:1.`, nodeKind, rule: "tokens/contrast" });
+    }
+}
 export async function loadContrastManifest(url) {
     const { readFile } = await import("node:fs/promises");
     const packaged = url ?? new URL("../contrast-contract.json", import.meta.url);
@@ -98,8 +164,9 @@ export function createTokenContrastRule({ computed = {}, defaults = {}, derived
             for (const theme of collector.themes) {
                 const location = findingLocation(theme);
                 const computedTheme = computed[theme.name] ?? {};
-                const hasCompleteComputedEvidence = manifest.pairs.every(({ background, foreground }) => computedTheme[background] !== undefined &&
-                    computedTheme[foreground] !== undefined);
+                // Every layer a pair reads: the text, its background, the surface
+                // under a translucent one and a group's background.
+                const hasCompleteComputedEvidence = manifest.pairs.every((pair) => [pair.foreground, pair.background, pair.over, pair.group].every((token) => token === undefined || computedTheme[token] !== undefined));
                 if (theme.overlapping && !hasCompleteComputedEvidence) {
                     result.uncovered.push({
                         ...location,
@@ -111,7 +178,7 @@ export function createTokenContrastRule({ computed = {}, defaults = {}, derived
                     continue;
                 }
                 const missingComputedEndpoints = theme.unresolved
-                    ? manifest.pairs.flatMap(({ background, foreground }) => [background, foreground].filter((token) => computedTheme[token] === undefined))
+                    ? manifest.pairs.flatMap(({ background, foreground, group, over }) => [background, foreground, over, group].filter((token) => token !== undefined && computedTheme[token] === undefined))
                     : [];
                 if (missingComputedEndpoints.length > 0) {
                     result.uncovered.push({
@@ -144,17 +211,30 @@ export function createTokenContrastRule({ computed = {}, defaults = {}, derived
                         tokens.set(token, value);
                 }
                 for (const pair of manifest.pairs) {
-                    let background = resolveColor(tokens.get(pair.background), tokens);
+                    if (pair.opacity !== undefined) {
+                        const ratio = groupRatio(pair, tokens);
+                        reportPair(result, location, theme.name, pair, ratio);
+                        continue;
+                    }
                     const foreground = resolveColor(tokens.get(pair.foreground), tokens);
-                    // A translucent background is measured as painted over the surface
-                    // the pair names (schema 2); without one it stays uncovered below.
-                    if (pair.over && background.status === "resolved" && (background.color.alpha ?? 1) < 1) {
-                        const over = resolveColor(tokens.get(pair.over), tokens);
-                        background = over.status === "resolved" && (over.color.alpha ?? 1) === 1
-                            ? { color: composite(background.color, over.color), status: "resolved" }
-                            : { status: "uncovered" };
+                    // Each point of the background, a gradient's included, and of the
+                    // surface under it; the pair is as good as its worst point.
+                    const backgrounds = [];
+                    for (const painted of resolveAlong(pair.background, tokens)) {
+                        // A translucent background is measured as painted over the surface
+                        // the pair names (schema 2); without one it stays uncovered below.
+                        if (pair.over && painted.status === "resolved" && (painted.color.alpha ?? 1) < 1) {
+                            for (const over of resolveAlong(pair.over, tokens)) {
+                                backgrounds.push(over.status === "resolved" && (over.color.alpha ?? 1) === 1
+                                    ? { color: composite(painted.color, over.color), status: "resolved" }
+                                    : { status: "uncovered" });
+                            }
+                        }
+                        else {
+                            backgrounds.push(painted);
+                        }
                     }
-                    if (background.status === "uncovered" ||
+                    if (backgrounds.some((background) => background.status === "uncovered") ||
                         foreground.status === "uncovered") {
                         result.uncovered.push({
                             ...location,
@@ -165,7 +245,8 @@ export function createTokenContrastRule({ computed = {}, defaults = {}, derived
                         });
                         continue;
                     }
-                    const ratio = contrastRatio(foreground.color, background.color);
+                    const ratios = backgrounds.map((background) => background.status === "resolved" ? contrastRatio(foreground.color, background.color) : undefined);
+                    const ratio = ratios.includes(undefined) ? undefined : Math.min(...ratios);
                     if (ratio === undefined) {
                         result.uncovered.push({
                             ...location,

package/dist/theme-contract.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "3.3.0",
+  "contractVersion": "3.5.0",
   "schemaVersion": 2,
   "prefix": "--ui-",
   "required": [
@@ -320,7 +320,78 @@
     "--ui-board-count-text": { "kind": "token", "token": "--ui-text-primary" },
     "--ui-board-card-border-hover": { "kind": "token", "token": "--ui-action-primary-bg" },
     "--ui-board-drop-bg": { "kind": "token", "token": "--ui-action-soft-accent-bg" },
-    "--ui-board-drop-border": { "kind": "token", "token": "--ui-action-primary-bg" }
+    "--ui-board-drop-border": { "kind": "token", "token": "--ui-action-primary-bg" },
+    "--ui-surface-inverse-end": { "kind": "token", "token": "--ui-surface-inverse" },
+    "--ui-checkbox-circle-bg": { "kind": "literal", "value": "transparent" },
+    "--ui-checkbox-circle-hover": { "kind": "token", "token": "--ui-control-checked-bg" },
+    "--ui-list-item-border-hover": { "kind": "token", "token": "--ui-border-strong" },
+    "--ui-list-item-success-bg-hover": { "kind": "token", "token": "--ui-list-item-success-bg" },
+    "--ui-list-item-warning-bg-hover": { "kind": "token", "token": "--ui-list-item-warning-bg" },
+    "--ui-list-item-danger-bg-hover": { "kind": "token", "token": "--ui-list-item-danger-bg" },
+    "--ui-list-item-info-bg-hover": { "kind": "token", "token": "--ui-list-item-info-bg" },
+    "--ui-list-item-shadow-color": { "kind": "literal", "value": "transparent" },
+    "--ui-list-item-done-border": { "kind": "token", "token": "--ui-border" },
+    "--ui-list-item-done-title": { "kind": "token", "token": "--ui-text-secondary" },
+    "--ui-list-item-done-ring": { "kind": "token", "token": "--ui-text-secondary" },
+    "--ui-list-item-title-hover": { "kind": "token", "token": "--ui-link-text" },
+    "--ui-steps-complete-marker-bg": { "kind": "token", "token": "--ui-surface" },
+    "--ui-steps-upcoming-title": { "kind": "token", "token": "--ui-text-primary" },
+    "--ui-steps-upcoming-description": { "kind": "token", "token": "--ui-text-primary" },
+    "--ui-steps-upcoming-marker-bg": { "kind": "token", "token": "--ui-surface-subtle" },
+    "--ui-steps-upcoming-marker-text": { "kind": "token", "token": "--ui-text-primary" },
+    "--ui-media-thumbnail-veil": { "kind": "token", "token": "--ui-media-overlay-bg" },
+    "--ui-media-enlarge-bg": { "kind": "literal", "value": "transparent" },
+    "--ui-media-enlarge-icon": { "kind": "token", "token": "--ui-media-overlay-text" },
+    "--ui-media-enlarge-shadow-color": { "kind": "literal", "value": "transparent" },
+    "--ui-message-incoming-document-bg": { "kind": "token", "token": "--ui-surface" },
+    "--ui-message-incoming-document-border": { "kind": "token", "token": "--ui-border" },
+    "--ui-message-incoming-document-text": { "kind": "token", "token": "--ui-text-primary" },
+    "--ui-message-incoming-document-meta": { "kind": "token", "token": "--ui-text-secondary" },
+    "--ui-message-incoming-document-download-bg": { "kind": "literal", "value": "transparent" },
+    "--ui-message-incoming-document-download-bg-hover": { "kind": "token", "token": "--ui-action-ghost-bg-hover" },
+    "--ui-message-incoming-document-download-icon": { "kind": "token", "token": "--ui-action-ghost-text" },
+    "--ui-message-incoming-document-download-icon-hover": { "kind": "token", "token": "--ui-action-ghost-text-hover" },
+    "--ui-message-assistant-document-bg": { "kind": "token", "token": "--ui-surface" },
+    "--ui-message-assistant-document-border": { "kind": "token", "token": "--ui-border" },
+    "--ui-message-assistant-document-text": { "kind": "token", "token": "--ui-text-primary" },
+    "--ui-message-assistant-document-meta": { "kind": "token", "token": "--ui-text-secondary" },
+    "--ui-message-assistant-document-download-bg": { "kind": "literal", "value": "transparent" },
+    "--ui-message-assistant-document-download-bg-hover": { "kind": "token", "token": "--ui-action-ghost-bg-hover" },
+    "--ui-message-assistant-document-download-icon": { "kind": "token", "token": "--ui-action-ghost-text" },
+    "--ui-message-assistant-document-download-icon-hover": { "kind": "token", "token": "--ui-action-ghost-text-hover" },
+    "--ui-message-outgoing-document-bg": { "kind": "token", "token": "--ui-surface" },
+    "--ui-message-outgoing-document-border": { "kind": "token", "token": "--ui-border" },
+    "--ui-message-outgoing-document-text": { "kind": "token", "token": "--ui-text-primary" },
+    "--ui-message-outgoing-document-meta": { "kind": "token", "token": "--ui-text-secondary" },
+    "--ui-message-outgoing-document-download-bg": { "kind": "literal", "value": "transparent" },
+    "--ui-message-outgoing-document-download-bg-hover": { "kind": "token", "token": "--ui-action-ghost-bg-hover" },
+    "--ui-message-outgoing-document-download-icon": { "kind": "token", "token": "--ui-action-ghost-text" },
+    "--ui-message-outgoing-document-download-icon-hover": { "kind": "token", "token": "--ui-action-ghost-text-hover" },
+    "--ui-message-incoming-audio-play-bg": { "kind": "token", "token": "--ui-action-primary-bg" },
+    "--ui-message-incoming-audio-play-icon": { "kind": "token", "token": "--ui-action-primary-text" },
+    "--ui-message-incoming-audio-wave-played": { "kind": "token", "token": "--ui-action-primary-bg" },
+    "--ui-message-incoming-audio-wave-unplayed": { "kind": "token", "token": "--ui-border-strong" },
+    "--ui-message-incoming-audio-playhead": { "kind": "token", "token": "--ui-message-incoming-text" },
+    "--ui-message-incoming-audio-time": { "kind": "token", "token": "--ui-message-incoming-meta" },
+    "--ui-message-incoming-audio-speed-bg": { "kind": "token", "token": "--ui-surface-subtle" },
+    "--ui-message-incoming-audio-speed-text": { "kind": "token", "token": "--ui-text-primary" },
+    "--ui-message-assistant-audio-play-bg": { "kind": "token", "token": "--ui-action-primary-bg" },
+    "--ui-message-assistant-audio-play-icon": { "kind": "token", "token": "--ui-action-primary-text" },
+    "--ui-message-assistant-audio-wave-played": { "kind": "token", "token": "--ui-action-primary-bg" },
+    "--ui-message-assistant-audio-wave-unplayed": { "kind": "token", "token": "--ui-border-strong" },
+    "--ui-message-assistant-audio-playhead": { "kind": "token", "token": "--ui-message-assistant-text" },
+    "--ui-message-assistant-audio-time": { "kind": "token", "token": "--ui-message-assistant-meta" },
+    "--ui-message-assistant-audio-speed-bg": { "kind": "token", "token": "--ui-surface-subtle" },
+    "--ui-message-assistant-audio-speed-text": { "kind": "token", "token": "--ui-text-primary" },
+    "--ui-message-outgoing-audio-play-bg": { "kind": "token", "token": "--ui-action-primary-text" },
+    "--ui-message-outgoing-audio-play-icon": { "kind": "token", "token": "--ui-action-primary-bg" },
+    "--ui-message-outgoing-audio-wave-played": { "kind": "token", "token": "--ui-action-primary-text" },
+    "--ui-message-outgoing-audio-wave-unplayed": { "kind": "literal", "value": "rgb(255 255 255 / 60%)" },
+    "--ui-message-outgoing-audio-playhead": { "kind": "token", "token": "--ui-message-outgoing-text" },
+    "--ui-message-outgoing-audio-time": { "kind": "token", "token": "--ui-message-outgoing-meta" },
+    "--ui-message-outgoing-audio-speed-bg": { "kind": "literal", "value": "rgb(0 0 0 / 20%)" },
+    "--ui-message-outgoing-audio-speed-text": { "kind": "token", "token": "--ui-action-primary-text" },
+    "--ui-audio-play-shadow-color": { "kind": "literal", "value": "transparent" }
   },
   "shape": [
     "--ui-font-body",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksmv/ui-checks",
-  "version": "0.22.0",
+  "version": "0.23.2",
   "description": "Static and computed quality checks for semantic UI token contracts.",
   "keywords": ["accessibility", "design-tokens", "quality", "static-analysis"],
   "license": "Apache-2.0",