@ksmv/ui-checks 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.4.0 - 2026-10-03
+
+- **Contratos de tema 2.2.0 e de contraste 2.0.0** empacotados: dois derivados e dois pares do controle marcado (ver o CHANGELOG do `@ksmv/ui-react`). Um par novo pode reprovar um tema que hoje passa.
+- **`tokens/contrast` resolve derivados não declarados** pela cadeia do contrato até um token declarado. Na 0.3.3 e anteriores, um par com um derivado que o tema não declarava ficava como cobertura pendente quando não havia evidência calculada.
+- **A evidência pede a origem de um derivado usado num par de contraste.** Na 0.3.3 e anteriores, toda ponta de par era exigida com valor, e um derivado não declarado, que o navegador informa vazio, fazia a evidência ser recusada.
+- **A identidade dos contratos muda**, então evidência capturada antes da atualização é recusada com código 2: quem usa `computedEvidence` precisa capturar de novo.
+
 ## 0.3.3 - 2026-10-02
 
 - **O erro de inicialização das regras diz a causa.** Na 0.3.2 e anteriores, evidência recusada ou contrato não resolvido saíam com código 2 e só com `Unable to initialize configured rules.`. O erro operacional agora diz qual foi o motivo e, quando há, o remédio: arquivo de evidência ausente, ilegível ou fora do formato; identidade do contrato diferente da instalada, com as duas versões; hash das fontes do tema diferente; seletores ou tema diferentes dos configurados; `capturedAt` inválido ou no futuro; tokens sem valor ou com `var(...)` restante, com os nomes dos tokens. A mensagem não repete valores do produto, e a saída continua sendo código 2.

package/README.md

@@ -95,7 +95,7 @@ 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.`).
 
-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 peso do botão por tamanho (`--ui-button-font-weight-sm`, `-md` e `-lg` derivam de `--ui-button-font-weight`), a cadeia é seguida até um token declarado.
+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 peso do botão por tamanho (`--ui-button-font-weight-sm`, `-md` e `-lg` derivam de `--ui-button-font-weight`), 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.
 
 Os tokens de densidade têm o valor conferido por `tokens/complete`: comprimento maior que zero em `px`, `rem` ou `em` para fonte e altura; também `0` para respiro e espaçamento; número sem unidade maior que zero para a entrelinha; em todos esses, também `calc()`, `clamp()`, `min()` ou `max()`; inteiro de 1 a 1000, `normal` ou `bold` para o peso. Com evidência, vale o valor capturado no navegador. Sem evidência, um valor que chega por `var()` é conferido pelo que ele alcança: o token declarado no mesmo tema ou, se não houver, o fallback do próprio `var()`; uma referência que não chega a valor nenhum fica como cobertura pendente. Valor inválido é cobertura obrigatória e não entra em baseline.
 

package/dist/contrast-contract.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.0.0",
+  "contractVersion": "2.0.0",
   "schemaVersion": 1,
   "pairs": [
     { "foreground": "--ui-action-primary-text", "background": "--ui-action-primary-bg", "minimum": 4.5, "context": "normal-text" },
@@ -33,6 +33,8 @@
     { "foreground": "--ui-text-inverse", "background": "--ui-surface-inverse", "minimum": 4.5, "context": "inverse-text" },
     { "foreground": "--ui-border-control", "background": "--ui-surface", "minimum": 3, "context": "control-boundary" },
     { "foreground": "--ui-focus-ring", "background": "--ui-surface", "minimum": 3, "context": "focus-indicator" },
-    { "foreground": "--ui-focus-ring", "background": "--ui-focus-ring-offset", "minimum": 3, "context": "focus-indicator" }
+    { "foreground": "--ui-focus-ring", "background": "--ui-focus-ring-offset", "minimum": 3, "context": "focus-indicator" },
+    { "foreground": "--ui-control-checked-bg", "background": "--ui-surface", "minimum": 3, "context": "checked-control-boundary" },
+    { "foreground": "--ui-control-checked-fg", "background": "--ui-control-checked-bg", "minimum": 3, "context": "checked-indicator" }
   ]
 }

package/dist/evidence.js

@@ -54,16 +54,24 @@ function isIdentity(value) {
         hashPattern.test(value.sha256);
 }
 // Derived tokens are not required: a theme may leave them to their documented
-// default, the source token, and the browser then reports them as empty.
+// default, the source token, and the browser then reports them as empty. A
+// contrast endpoint that is such a token is required through its source.
 function requiredEvidenceTokens(contracts) {
     const derived = contracts.theme.derived;
+    const required = new Set(contracts.theme.required);
+    const origin = (token, seen = new Set()) => {
+        const source = derived[token];
+        if (required.has(token) || source === undefined || seen.has(token))
+            return token;
+        return origin(source, new Set([...seen, token]));
+    };
     return new Set([
-        ...contracts.theme.required,
+        ...required,
         // A source that is itself derived is optional too; its chain is followed.
         ...Object.values(derived).filter((source) => !(source in derived)),
         ...contracts.contrast.pairs.flatMap(({ background, foreground }) => [
-            background,
-            foreground,
+            origin(background),
+            origin(foreground),
         ]),
     ]);
 }

package/dist/rules/default.js

@@ -12,7 +12,12 @@ export async function createDefaultRules({ components, computed, contract, manif
         createNoLiteralColorRule({ themes }),
         createTokenPrefixRule(),
         createTokenCompleteRule({ computed, contract: resolvedContract, themes }),
-        createTokenContrastRule({ computed, manifest: resolvedManifest, themes }),
+        createTokenContrastRule({
+            computed,
+            derived: resolvedContract.derived,
+            manifest: resolvedManifest,
+            themes,
+        }),
         ...(components
             ? [createComponentOverrideRule({ classHelpers: components.classHelpers, sources: components.sources })]
             : []),

package/dist/rules/tokenContrast.d.ts

@@ -4,8 +4,9 @@ import type { CheckRule } from "../scan.js";
 export type { ContrastManifest, ContrastPair } from "../contracts.js";
 export interface TokenContrastOptions {
     computed?: Record<string, Record<string, string>>;
+    derived?: Record<string, string>;
     manifest: ContrastManifest;
     themes: ThemeConfig[];
 }
 export declare function loadContrastManifest(url?: URL): Promise<ContrastManifest>;
-export declare function createTokenContrastRule({ computed, manifest, themes, }: TokenContrastOptions): CheckRule;
+export declare function createTokenContrastRule({ computed, derived, manifest, themes, }: TokenContrastOptions): CheckRule;

package/dist/rules/tokenContrast.js

@@ -84,7 +84,7 @@ function dynamicStyleResult(file) {
     sourceFile.forEachChild(visit);
     return result;
 }
-export function createTokenContrastRule({ computed = {}, manifest, themes, }) {
+export function createTokenContrastRule({ computed = {}, derived = {}, manifest, themes, }) {
     const collector = createThemeCollector(themes);
     return {
         name: "tokens/contrast",
@@ -130,6 +130,14 @@ export function createTokenContrastRule({ computed = {}, manifest, themes, }) {
                 for (const [name, value] of Object.entries(computedTheme)) {
                     tokens.set(name, value);
                 }
+                // A derived token the theme leaves undeclared takes its documented
+                // default, the source token. resolveColor follows the chain and stops
+                // on a cycle.
+                for (const [token, source] of Object.entries(derived)) {
+                    if (!tokens.has(token)) {
+                        tokens.set(token, `var(${source})`);
+                    }
+                }
                 for (const pair of manifest.pairs) {
                     const background = resolveColor(tokens.get(pair.background), tokens);
                     const foreground = resolveColor(tokens.get(pair.foreground), tokens);

package/dist/theme-contract.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "2.1.0",
+  "contractVersion": "2.2.0",
   "schemaVersion": 1,
   "prefix": "--ui-",
   "required": [
@@ -97,7 +97,9 @@
     "--ui-button-font-weight": "--ui-font-weight-strong",
     "--ui-button-font-weight-sm": "--ui-button-font-weight",
     "--ui-button-font-weight-md": "--ui-button-font-weight",
-    "--ui-button-font-weight-lg": "--ui-button-font-weight"
+    "--ui-button-font-weight-lg": "--ui-button-font-weight",
+    "--ui-control-checked-bg": "--ui-action-primary-bg",
+    "--ui-control-checked-fg": "--ui-action-primary-text"
   },
   "brandComposition": [
     "--ui-brand-primary",

package/package.json

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