@ksmv/ui-checks 0.22.0 → 0.22.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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ê), 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.
 

package/dist/color.d.ts

@@ -19,4 +19,5 @@ 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 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",
@@ -195,6 +196,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/contrast-contract.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "11.0.0",
+  "contractVersion": "12.0.0",
   "schemaVersion": 2,
   "pairs": [
     { "foreground": "--ui-action-primary-text", "background": "--ui-action-primary-bg", "minimum": 4.5, "context": "normal-text" },
@@ -317,6 +317,26 @@
     { "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" }
   ]
 }

package/dist/rules/tokenContrast.js

@@ -1,7 +1,26 @@
 import { isComputedPropertyName, isIdentifier, isJsxAttribute, isJsxExpression, isObjectLiteralExpression, isPropertyAssignment, isJsxSpreadAttribute, isStringLiteralLikeNode, } from "typescript/unstable/ast";
-import { composite, contrastRatio, isColorBearingProperty, resolveColor, } from "../color.js";
+import { composite, contrastRatio, isColorBearingProperty, mix, 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" }));
+}
 export async function loadContrastManifest(url) {
     const { readFile } = await import("node:fs/promises");
     const packaged = url ?? new URL("../contrast-contract.json", import.meta.url);
@@ -144,17 +163,25 @@ export function createTokenContrastRule({ computed = {}, defaults = {}, derived
                         tokens.set(token, value);
                 }
                 for (const pair of manifest.pairs) {
-                    let background = resolveColor(tokens.get(pair.background), tokens);
                     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 +192,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.4.0",
   "schemaVersion": 2,
   "prefix": "--ui-",
   "required": [
@@ -320,7 +320,8 @@
     "--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" }
   },
   "shape": [
     "--ui-font-body",

package/package.json

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