@ksmv/ui-checks 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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.
+- Quem compara o texto exato `Invalid computed theme evidence.` lançado por `loadComputedEvidence` precisa ajustar: as mensagens novas começam com esse texto e seguem com a causa.
+- **Contrato de tema 2.1.0** empacotado, com 3 derivados opcionais novos: `--ui-button-font-weight-sm`, `--ui-button-font-weight-md` e `--ui-button-font-weight-lg`, que herdam de `--ui-button-font-weight`. Nenhuma declaração nova é exigida do tema.
+- **A identidade do contrato muda**, então evidência capturada antes da atualização é recusada com código 2: quem usa `computedEvidence` precisa capturar de novo.
+- `tokens/complete` valida os três como peso (inteiro de 1 a 1000, `normal` ou `bold`) e passa a seguir a cadeia de derivados até um token declarado. Na 0.3.2 e anteriores só o primeiro nível era conferido, e um derivado de outro derivado ficava sem fallback quando o tema não declarava o intermediário.
+
 ## 0.3.2 - 2026-10-01
 
 - **O hash das fontes do tema deixa de depender do fim de linha do checkout.** Num repositório sem regra de fim de linha, o mesmo commit sai com CRLF no Windows e com LF no Linux. Na 0.3.1 e anteriores o hash cobria os bytes do arquivo, então a evidência capturada num sistema era recusada no outro, com código 2: verde na máquina de quem capturou e vermelho no CI. `CRLF` passa a contar como `LF`; qualquer outra diferença continua mudando o hash.

package/README.md

@@ -80,13 +80,22 @@ Seletores disjuntos, como `[data-theme="light"]` e `[data-theme="dark"]`, são v
 
 A evidência não é uma exceção manual. O arquivo é recusado, com código `2`, quando:
 
-- `capturedAt` está no futuro;
-- os seletores diferem dos configurados;
+- o arquivo não existe, não pode ser lido, não é JSON válido ou não tem a estrutura da receita abaixo;
+- `capturedAt` não é um horário UTC ou está no futuro;
+- os seletores diferem dos configurados, ou o tema nomeado em `computedEvidence.theme` não está no arquivo ou foi capturado para outro seletor;
 - o hash das fontes diverge, ou seja, o tema mudou depois da captura (o fim de linha não conta: o mesmo arquivo em CRLF e em LF tem o mesmo hash);
 - a identidade de um dos contratos diverge da instalada, ou seja, o pacote React mudou depois da captura;
 - falta algum token exigido, ou algum valor ainda contém `var(...)`.
 
-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.
+O erro operacional diz qual desses motivos ocorreu e, quando há, o remédio. Por exemplo, depois de alterar um arquivo de tema sem capturar de novo:
+
+```text
+config Invalid computed theme evidence in artifacts/theme-evidence.json: the theme source hash differs, so a theme file changed after the capture. Capture the evidence again.
+```
+
+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. 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/contracts.d.ts

@@ -32,6 +32,13 @@ export interface ContractSet {
     source: ContractSource;
     theme: ThemeContract;
 }
+/**
+ * A failure whose message this package wrote, so a report may repeat it. The
+ * message of any other error is never reported: it could carry product content.
+ */
+export declare class CheckSetupError extends Error {
+}
+export declare const semverPattern: RegExp;
 export declare function parseThemeContract(content: string): ThemeContract;
 export declare function parseContrastManifest(content: string): ContrastManifest;
 export declare function resolveContractSet({ root, source, }: {

package/dist/contracts.js

@@ -3,7 +3,13 @@ import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { resolve } from "node:path";
 export const tokenNamePattern = /^--ui-[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/**
+ * A failure whose message this package wrote, so a report may repeat it. The
+ * message of any other error is never reported: it could carry product content.
+ */
+export class CheckSetupError extends Error {
+}
+export const semverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 function exactKeys(value, keys) {
     return Object.keys(value).sort().join(",") === [...keys].sort().join(",");
 }
@@ -19,7 +25,7 @@ export function parseThemeContract(content) {
         value = JSON.parse(content);
     }
     catch {
-        throw new Error("Unsupported theme contract.");
+        throw new CheckSetupError("Unsupported theme contract.");
     }
     if (!isRecord(value) ||
         !exactKeys(value, [
@@ -42,7 +48,7 @@ export function parseThemeContract(content) {
         Object.entries(value.derived).some(([token, fallback]) => !tokenNamePattern.test(token) ||
             typeof fallback !== "string" ||
             !tokenNamePattern.test(fallback))) {
-        throw new Error("Unsupported theme contract.");
+        throw new CheckSetupError("Unsupported theme contract.");
     }
     return value;
 }
@@ -52,7 +58,7 @@ export function parseContrastManifest(content) {
         value = JSON.parse(content);
     }
     catch {
-        throw new Error("Unsupported contrast manifest.");
+        throw new CheckSetupError("Unsupported contrast manifest.");
     }
     if (!isRecord(value) ||
         !exactKeys(value, ["contractVersion", "pairs", "schemaVersion"]) ||
@@ -60,7 +66,7 @@ export function parseContrastManifest(content) {
         typeof value.contractVersion !== "string" ||
         !semverPattern.test(value.contractVersion) ||
         !Array.isArray(value.pairs)) {
-        throw new Error("Unsupported contrast manifest.");
+        throw new CheckSetupError("Unsupported contrast manifest.");
     }
     const identities = [];
     for (const pair of value.pairs) {
@@ -75,12 +81,12 @@ export function parseContrastManifest(content) {
             typeof pair.minimum !== "number" ||
             !Number.isFinite(pair.minimum) ||
             pair.minimum <= 0) {
-            throw new Error("Unsupported contrast manifest.");
+            throw new CheckSetupError("Unsupported contrast manifest.");
         }
         identities.push(`${pair.context}\u0000${pair.foreground}\u0000${pair.background}`);
     }
     if (new Set(identities).size !== identities.length) {
-        throw new Error("Unsupported contrast manifest.");
+        throw new CheckSetupError("Unsupported contrast manifest.");
     }
     return value;
 }
@@ -99,7 +105,7 @@ async function reactContractPaths(root) {
         };
     }
     catch {
-        throw new Error("Unable to resolve the configured contract source.");
+        throw new CheckSetupError("Unable to resolve the configured contract source.");
     }
 }
 export async function resolveContractSet({ root, source, }) {
@@ -127,12 +133,9 @@ export async function resolveContractSet({ root, source, }) {
         };
     }
     catch (error) {
-        if (error instanceof Error &&
-            (error.message === "Unsupported theme contract." ||
-                error.message === "Unsupported contrast manifest." ||
-                error.message === "Unable to resolve the configured contract source.")) {
+        if (error instanceof CheckSetupError) {
             throw error;
         }
-        throw new Error("Unable to resolve the configured contract source.");
+        throw new CheckSetupError("Unable to resolve the configured contract source.");
     }
 }

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/density.js

@@ -28,6 +28,9 @@ export const densityTokenKinds = Object.freeze({
     "--ui-field-height": "control-height",
     "--ui-dialog-title-font-size": "font-size",
     "--ui-button-font-weight": "font-weight",
+    "--ui-button-font-weight-sm": "font-weight",
+    "--ui-button-font-weight-md": "font-weight",
+    "--ui-button-font-weight-lg": "font-weight",
 });
 const lengthPattern = /^(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)$/iu;
 const math = /^(?:calc|clamp|min|max)\(.+\)$/iu;

package/dist/evidence.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
-import { tokenNamePattern, } from "./contracts.js";
+import { CheckSetupError, semverPattern, tokenNamePattern, } from "./contracts.js";
+const hashPattern = /^sha256:[a-f0-9]{64}$/;
+const tokenListLimit = 10;
 function normalizedFiles(root, files) {
     return [...new Set(files.map((file) => file.replaceAll("\\", "/")))]
         .sort()
@@ -11,7 +13,7 @@ function normalizedFiles(root, files) {
         if (isAbsolute(file) ||
             fromRoot === ".." ||
             fromRoot.startsWith("../")) {
-            throw new Error("Invalid computed theme evidence.");
+            throw new CheckSetupError("Theme files must be relative paths inside the configured root.");
         }
         return { absolute, path: fromRoot };
     });
@@ -43,65 +45,75 @@ function exactKeys(value, keys) {
 function isRecord(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
-function sameIdentity(actual, expected) {
-    return isRecord(actual) &&
-        exactKeys(actual, ["contractVersion", "sha256"]) &&
-        actual.contractVersion === expected.contractVersion &&
-        actual.sha256 === expected.sha256;
+function isIdentity(value) {
+    return isRecord(value) &&
+        exactKeys(value, ["contractVersion", "sha256"]) &&
+        typeof value.contractVersion === "string" &&
+        semverPattern.test(value.contractVersion) &&
+        typeof value.sha256 === "string" &&
+        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),
         ]),
     ]);
 }
-function validateEvidenceShape(value, contracts) {
-    if (!isRecord(value) ||
-        !exactKeys(value, [
+// Structure only: whether the content agrees with the contracts, the
+// configuration and the theme files is checked afterwards, cause by cause.
+function hasEvidenceStructure(value) {
+    return isRecord(value) &&
+        exactKeys(value, [
             "capturedAt",
             "contracts",
             "schemaVersion",
             "selectors",
             "sourceHash",
             "themes",
-        ]) ||
-        value.schemaVersion !== 1 ||
-        typeof value.capturedAt !== "string" ||
-        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value.capturedAt) ||
-        typeof value.sourceHash !== "string" ||
-        !/^sha256:[a-f0-9]{64}$/.test(value.sourceHash) ||
-        !Array.isArray(value.selectors) ||
-        value.selectors.some((selector) => typeof selector !== "string") ||
-        !isRecord(value.contracts) ||
-        !exactKeys(value.contracts, ["contrast", "theme"]) ||
-        !sameIdentity(value.contracts.contrast, contracts.identities.contrast) ||
-        !sameIdentity(value.contracts.theme, contracts.identities.theme) ||
-        !isRecord(value.themes)) {
-        return false;
-    }
-    // A token the evidence must carry is never optional, even when the contract
-    // also lists it as derived or as a brand token.
-    const required = requiredEvidenceTokens(contracts);
-    const optional = new Set([...Object.keys(contracts.theme.derived), ...contracts.theme.brandComposition]
-        .filter((token) => !required.has(token)));
-    return Object.values(value.themes).every((theme) => isRecord(theme) &&
-        exactKeys(theme, ["selector", "tokens"]) &&
-        typeof theme.selector === "string" &&
-        isRecord(theme.tokens) &&
-        Object.entries(theme.tokens).every(([token, tokenValue]) => tokenNamePattern.test(token) &&
-            typeof tokenValue === "string" &&
-            // Empty means undeclared, which only an optional token may be: a derived
-            // token left to its default, or a brand token the theme does not use.
-            (tokenValue.trim().length > 0 || optional.has(token)) &&
-            !/var\s*\(/i.test(tokenValue)));
+        ]) &&
+        value.schemaVersion === 1 &&
+        typeof value.capturedAt === "string" &&
+        typeof value.sourceHash === "string" &&
+        hashPattern.test(value.sourceHash) &&
+        Array.isArray(value.selectors) &&
+        value.selectors.every((selector) => typeof selector === "string") &&
+        isRecord(value.contracts) &&
+        exactKeys(value.contracts, ["contrast", "theme"]) &&
+        isIdentity(value.contracts.contrast) &&
+        isIdentity(value.contracts.theme) &&
+        isRecord(value.themes) &&
+        Object.values(value.themes).every((theme) => isRecord(theme) &&
+            exactKeys(theme, ["selector", "tokens"]) &&
+            typeof theme.selector === "string" &&
+            isRecord(theme.tokens) &&
+            Object.entries(theme.tokens).every(([token, tokenValue]) => tokenNamePattern.test(token) && typeof tokenValue === "string"));
+}
+function counted(tokens, noun) {
+    return `${tokens.length} ${noun}${tokens.length === 1 ? "" : "s"}`;
+}
+// Token names only, never their values, and a long list is cut short.
+function named(tokens) {
+    const sorted = [...tokens].sort();
+    const shown = sorted.slice(0, tokenListLimit).join(", ");
+    return sorted.length > tokenListLimit
+        ? `${shown} and ${sorted.length - tokenListLimit} more`
+        : shown;
 }
 export async function loadComputedEvidence({ contracts, evidenceByPath, now = new Date(), root, themes, }) {
     try {
@@ -113,35 +125,100 @@ export async function loadComputedEvidence({ contracts, evidenceByPath, now = ne
         }
         const result = {};
         const requiredTokens = requiredEvidenceTokens(contracts);
+        // A token the evidence must carry is never optional, even when the contract
+        // also lists it as derived or as a brand token.
+        const optionalTokens = new Set([...Object.keys(contracts.theme.derived), ...contracts.theme.brandComposition]
+            .filter((token) => !requiredTokens.has(token)));
         for (const [path, group] of grouped) {
-            const injected = evidenceByPath?.get(path);
-            const evidence = injected ?? JSON.parse(await readFile(resolve(root, path), "utf8"));
-            if (!validateEvidenceShape(evidence, contracts)) {
-                throw new Error("shape");
+            const refused = (cause) => new CheckSetupError(`Invalid computed theme evidence in ${path}: ${cause}`);
+            let evidence = evidenceByPath?.get(path);
+            if (evidence === undefined) {
+                let content;
+                try {
+                    content = await readFile(resolve(root, path), "utf8");
+                }
+                catch {
+                    throw refused("the file is missing or cannot be read. Capture the evidence, or correct computedEvidence.file.");
+                }
+                try {
+                    evidence = JSON.parse(content);
+                }
+                catch {
+                    throw refused("the file is not valid JSON. Capture the evidence again.");
+                }
+            }
+            if (!hasEvidenceStructure(evidence)) {
+                throw refused("the file does not have the evidence structure. Capture the evidence again with the documented recipe.");
+            }
+            // The contracts come first: after a package upgrade the capture is stale
+            // in other ways too, and capturing again is what resolves them.
+            for (const contract of ["theme", "contrast"]) {
+                const captured = evidence.contracts[contract];
+                const installed = contracts.identities[contract];
+                if (captured.contractVersion !== installed.contractVersion) {
+                    throw refused(`it was captured for ${contract} contract ${captured.contractVersion}, and the installed ${contract} contract is ${installed.contractVersion}. Bring the theme up to the installed contract and capture the evidence again.`);
+                }
+                if (captured.sha256 !== installed.sha256) {
+                    throw refused(`it was captured for another build of ${contract} contract ${installed.contractVersion} than the installed one. Capture the evidence again.`);
+                }
             }
             const capturedAt = new Date(evidence.capturedAt);
-            if (!Number.isFinite(capturedAt.valueOf()) || capturedAt > now) {
-                throw new Error("time");
+            if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(evidence.capturedAt) ||
+                !Number.isFinite(capturedAt.valueOf())) {
+                throw refused("capturedAt is not a UTC timestamp such as 2026-01-31T12:00:00.000Z. Capture the evidence again.");
+            }
+            if (capturedAt > now) {
+                throw refused("capturedAt is in the future. Correct the clock of the capturing machine and capture the evidence again.");
             }
             const selectors = [...new Set(group.map(({ selector }) => selector))].sort();
             if ([...new Set(evidence.selectors)].sort().join("\0") !== selectors.join("\0")) {
-                throw new Error("selectors");
+                throw refused("its selectors differ from the selectors configured for the themes that use this file. Capture the evidence again.");
             }
             const files = [...new Set(group.flatMap(({ files }) => files))];
-            if (evidence.sourceHash !== await computeThemeSourceHash(root, files)) {
-                throw new Error("source");
+            let sourceHash;
+            try {
+                sourceHash = await computeThemeSourceHash(root, files);
+            }
+            catch (error) {
+                if (error instanceof CheckSetupError)
+                    throw error;
+                throw new CheckSetupError(`Unable to read the theme files that use the computed evidence in ${path}.`);
             }
+            if (evidence.sourceHash !== sourceHash) {
+                throw refused("the theme source hash differs, so a theme file changed after the capture. Capture the evidence again.");
+            }
+            // A referenced theme has to carry every required token; any other theme
+            // in the file only has to be sound in what it does carry.
+            const checkValues = (subject, tokens, referenced) => {
+                const hasNoValue = (token) => tokens[token] === undefined ? referenced : tokens[token].trim().length === 0;
+                const missing = [...requiredTokens].filter(hasNoValue);
+                if (missing.length > 0) {
+                    throw refused(`${subject} has no value for ${counted(missing, "required token")}: ${named(missing)}. Declare ${missing.length === 1 ? "it" : "them"} in the theme and capture the evidence again.`);
+                }
+                // Empty means undeclared, which only an optional token may be: a derived
+                // token left to its default, or a brand token the theme does not use.
+                const empty = Object.keys(tokens).filter((token) => hasNoValue(token) && !optionalTokens.has(token));
+                if (empty.length > 0) {
+                    throw refused(`${subject} has an empty value for ${counted(empty, "token")} the contract does not make optional: ${named(empty)}. Capture the evidence again with the documented recipe.`);
+                }
+                const unresolved = Object.keys(tokens).filter((token) => /var\s*\(/i.test(tokens[token]));
+                if (unresolved.length > 0) {
+                    throw refused(`${subject} still has var(...) in the value of ${counted(unresolved, "token")}: ${named(unresolved)}. Capture the values computed by a browser, where every var() is resolved.`);
+                }
+            };
             for (const theme of group) {
                 const name = theme.computedEvidence.theme;
-                const computedTheme = evidence.themes[name];
-                if (!computedTheme || computedTheme.selector !== theme.selector) {
-                    throw new Error("theme");
+                const subject = `its theme ${JSON.stringify(name)}`;
+                const computedTheme = Object.hasOwn(evidence.themes, name)
+                    ? evidence.themes[name]
+                    : undefined;
+                if (!computedTheme) {
+                    throw refused(`it has no theme named ${JSON.stringify(name)}, the name in computedEvidence.theme. Correct the name or capture the evidence again.`);
                 }
-                for (const token of requiredTokens) {
-                    if (computedTheme.tokens[token] === undefined) {
-                        throw new Error("tokens");
-                    }
+                if (computedTheme.selector !== theme.selector) {
+                    throw refused(`${subject} was captured for another selector than the configured one. Capture the evidence again.`);
                 }
+                checkValues(subject, computedTheme.tokens, true);
                 const tokens = Object.fromEntries(Object.entries(computedTheme.tokens).filter(([, tokenValue]) => tokenValue.trim().length > 0));
                 // A derived token left to its default takes its source's value,
                 // following sources that are derived themselves. A chain that does not
@@ -152,18 +229,34 @@ export async function loadComputedEvidence({ contracts, evidenceByPath, now = ne
                         return value;
                     const source = contracts.theme.derived[token];
                     if (source === undefined || seen.has(token))
-                        throw new Error("tokens");
+                        return undefined;
                     return derivedValue(source, new Set([...seen, token]));
                 };
+                const underivable = [];
                 for (const token of Object.keys(contracts.theme.derived)) {
-                    tokens[token] = derivedValue(token, new Set());
+                    const value = derivedValue(token, new Set());
+                    if (value === undefined)
+                        underivable.push(token);
+                    else
+                        tokens[token] = value;
+                }
+                if (underivable.length > 0) {
+                    throw refused(`${subject} has no value from which to derive ${counted(underivable, "token")}: ${named(underivable)}.`);
                 }
                 result[theme.name] = tokens;
             }
+            const referenced = new Set(group.map((theme) => theme.computedEvidence.theme));
+            for (const [name, theme] of Object.entries(evidence.themes)) {
+                if (!referenced.has(name)) {
+                    checkValues("a theme the configuration does not reference", theme.tokens, false);
+                }
+            }
         }
         return result;
     }
-    catch {
-        throw new Error("Invalid computed theme evidence.");
+    catch (error) {
+        if (error instanceof CheckSetupError)
+            throw error;
+        throw new CheckSetupError("Invalid computed theme evidence.");
     }
 }

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/tokenComplete.js

@@ -75,9 +75,18 @@ export function createTokenCompleteRule({ computed = {}, contract, themes, }) {
                         required: true,
                     });
                 }
-                for (const [token, fallback] of Object.entries(contract.derived)) {
-                    if (!theme.declarations.has(token) &&
-                        !theme.declarations.has(fallback)) {
+                // A derived token falls back to its source, and to the source's own
+                // source when that one is derived too, until a declared token.
+                const hasFallback = (token, seen) => {
+                    if (theme.declarations.has(token))
+                        return true;
+                    const source = contract.derived[token];
+                    if (source === undefined || seen.has(token))
+                        return false;
+                    return hasFallback(source, new Set([...seen, token]));
+                };
+                for (const token of Object.keys(contract.derived)) {
+                    if (!hasFallback(token, new Set())) {
                         result.violations.push({
                             ...location,
                             anchor: theme.name,

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/scan.js

@@ -3,7 +3,7 @@ import { extname, relative, resolve } from "node:path";
 import postcss from "postcss";
 import { computeLineStarts, createScanner, LanguageVariant, SyntaxKind, } from "typescript/unstable/ast";
 import { API } from "typescript/unstable/sync";
-import { resolveContractSet } from "./contracts.js";
+import { CheckSetupError, resolveContractSet, } from "./contracts.js";
 import { loadComputedEvidence } from "./evidence.js";
 import { assignFingerprints } from "./baseline.js";
 import { applyDebtControls } from "./governance.js";
@@ -234,7 +234,7 @@ export async function runChecks(config, options = {}) {
         }
         rules = [...(await configuredRules)].sort((left, right) => left.name.localeCompare(right.name));
     }
-    catch {
+    catch (error) {
         const report = emptyReport(["coverage/dynamic-expression"]);
         if (contracts) {
             report.contracts = {
@@ -243,9 +243,14 @@ export async function runChecks(config, options = {}) {
                 theme: contracts.identities.theme,
             };
         }
+        // Only the default rules say why: their causes are written by this package
+        // and repeat nothing of the product. Rules supplied by the caller, and any
+        // failure nobody anticipated, stay behind the generic message.
         report.operationalErrors.push({
             code: usesDefaultRules ? "config" : "internal",
-            message: "Unable to initialize configured rules.",
+            message: usesDefaultRules && error instanceof CheckSetupError
+                ? error.message
+                : "Unable to initialize configured rules.",
         });
         report.exitCode = 2;
         report.durationMs = Math.round((performance.now() - startedAt) * 100) / 100;

package/dist/theme-contract.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "2.0.0",
+  "contractVersion": "2.2.0",
   "schemaVersion": 1,
   "prefix": "--ui-",
   "required": [
@@ -94,7 +94,12 @@
     "--ui-status-info-border": "--ui-status-info",
     "--ui-field-height": "--ui-control-height-md",
     "--ui-dialog-title-font-size": "--ui-font-size-xl",
-    "--ui-button-font-weight": "--ui-font-weight-strong"
+    "--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-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.2",
+  "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",