@ksmv/ui-checks 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0 - 2026-09-29
+
+- **Contrato de tema 2.0.0** empacotado, com os 20 tokens de densidade obrigatórios e os 3 derivados. Pontes da 0.1.x ficam incompletas em `tokens/complete`, e evidência capturada antes da mudança deixa de conferir com a identidade do contrato.
+- **Validação de valor dos tokens de densidade** em `tokens/complete`, pela lista fechada de tokens (nunca por padrão de nome): fonte e altura aceitam comprimento maior que zero em `px`, `rem` ou `em`; respiro e espaçamento aceitam também `0`; entrelinha, número sem unidade maior que zero; nos três, também `calc()`, `clamp()`, `min()` ou `max()`; peso, inteiro de 1 a 1000, `normal` ou `bold`. A conferência usa o valor da evidência calculada quando existe; sem evidência, um `var()` é conferido pelo token do mesmo tema ou pelo fallback que ele alcança. Valor inválido é cobertura obrigatória: sai com código 2 e não entra em baseline, e a mensagem diz o formato esperado, sem repetir o valor.
+- `css/no-literal-color` deixa de ler como cor uma palavra só com dígitos hexadecimais e sem `#`, como o peso `600` numa custom property fora do seletor de tema.
+
 ## 0.1.5 - 2026-09-28
 
 - **Fingerprints de baseline estáveis.** O fingerprint passa a seguir o conteúdo do achado e a ordem entre achados idênticos no mesmo arquivo, e não mais a linha e a coluna. Na 0.1.4, uma linha inserida acima de dívida conhecida fazia toda a dívida seguinte reaparecer como achado novo; numa aplicação consumidora real, um comentário no topo do CSS gerou 115 falsos achados novos. O conteúdo entra no fingerprint só como hash, e nenhum trecho é gravado ou relatado.

package/README.md

@@ -88,6 +88,8 @@ A evidência não é uma exceção manual. O arquivo é recusado, com código `2
 
 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.
 
+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.
+
 A captura usa a API pública deste pacote e um navegador à sua escolha. Com Playwright, e a aplicação servida localmente:
 
 ```js

package/dist/color.js

@@ -100,6 +100,8 @@ export function containsLiteralColor(value) {
         if (node.type === "word" &&
             node.value.toLowerCase() !== "currentcolor" &&
             node.value.toLowerCase() !== "transparent" &&
+            // culori parses bare hex digits ("600", "fed") as colors; CSS never does.
+            !/^[0-9a-f]{3,8}$/iu.test(node.value) &&
             parsedColor(node.value)) {
             literal = true;
             return false;

package/dist/density.d.ts

@@ -0,0 +1,22 @@
+export type DensityKind = "control-height" | "font-size" | "font-weight" | "line-height" | "spacing";
+/**
+ * The closed list of density tokens whose values the checker validates. It is
+ * matched by exact name, never by pattern: `--ui-font-body` or
+ * `--ui-shadow-sm` must not be read as lengths.
+ */
+export declare const densityTokenKinds: Readonly<Record<string, DensityKind>>;
+export declare function isValidDensityValue(kind: DensityKind, raw: string): boolean;
+/**
+ * Human-readable description of what a valid value looks like for the given
+ * density kind, used in checker diagnostics. Never echoes the offending
+ * value itself.
+ */
+export declare function densityExpectation(kind: DensityKind): string;
+/**
+ * Resolves a whole-value `var()` reference to the literal it ends in, using
+ * the theme's own declarations (and the evidence) first and the reference's
+ * fallback second. Returns undefined when the chain does not end in a literal
+ * (the reference check reports that) or when it passes through another
+ * density token, which is validated on its own.
+ */
+export declare function resolveDensityReference(value: string, tokens: ReadonlyMap<string, string>, seen?: ReadonlySet<string>): string | undefined;

package/dist/density.js

@@ -0,0 +1,100 @@
+import valueParser from "postcss-value-parser";
+/**
+ * The closed list of density tokens whose values the checker validates. It is
+ * matched by exact name, never by pattern: `--ui-font-body` or
+ * `--ui-shadow-sm` must not be read as lengths.
+ */
+export const densityTokenKinds = Object.freeze({
+    "--ui-font-size-xs": "font-size",
+    "--ui-font-size-sm": "font-size",
+    "--ui-font-size-md": "font-size",
+    "--ui-font-size-lg": "font-size",
+    "--ui-font-size-xl": "font-size",
+    "--ui-font-weight-strong": "font-weight",
+    "--ui-line-height-control": "line-height",
+    "--ui-control-height-sm": "control-height",
+    "--ui-control-height-md": "control-height",
+    "--ui-control-height-lg": "control-height",
+    "--ui-control-padding-inline-sm": "spacing",
+    "--ui-control-padding-inline-md": "spacing",
+    "--ui-control-padding-inline-lg": "spacing",
+    "--ui-space-1": "spacing",
+    "--ui-space-1-5": "spacing",
+    "--ui-space-2": "spacing",
+    "--ui-space-3": "spacing",
+    "--ui-space-4": "spacing",
+    "--ui-space-6": "spacing",
+    "--ui-space-8": "spacing",
+    "--ui-field-height": "control-height",
+    "--ui-dialog-title-font-size": "font-size",
+    "--ui-button-font-weight": "font-weight",
+});
+const lengthPattern = /^(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em)$/iu;
+const math = /^(?:calc|clamp|min|max)\(.+\)$/iu;
+const unitless = /^(?:\d+(?:\.\d+)?|\.\d+)$/u;
+export function isValidDensityValue(kind, raw) {
+    const value = raw.trim();
+    switch (kind) {
+        case "font-weight": {
+            if (/^(?:normal|bold)$/iu.test(value))
+                return true;
+            if (!/^\d+$/u.test(value))
+                return false;
+            const weight = Number(value);
+            return weight >= 1 && weight <= 1000;
+        }
+        case "line-height":
+            return math.test(value) || (unitless.test(value) && Number(value) > 0);
+        case "spacing":
+            return value === "0" || math.test(value) || lengthPattern.test(value);
+        case "control-height":
+        case "font-size":
+            return math.test(value) || (lengthPattern.test(value) && Number.parseFloat(value) > 0);
+    }
+}
+/**
+ * Human-readable description of what a valid value looks like for the given
+ * density kind, used in checker diagnostics. Never echoes the offending
+ * value itself.
+ */
+export function densityExpectation(kind) {
+    switch (kind) {
+        case "control-height":
+        case "font-size":
+            return "a length above zero in px, rem or em, or calc()/clamp()/min()/max()";
+        case "spacing":
+            return "zero or a length in px, rem or em, or calc()/clamp()/min()/max()";
+        case "line-height":
+            return "a unitless number above zero, or calc()/clamp()/min()/max()";
+        case "font-weight":
+            return "an integer from 1 to 1000, normal or bold";
+    }
+}
+/**
+ * Resolves a whole-value `var()` reference to the literal it ends in, using
+ * the theme's own declarations (and the evidence) first and the reference's
+ * fallback second. Returns undefined when the chain does not end in a literal
+ * (the reference check reports that) or when it passes through another
+ * density token, which is validated on its own.
+ */
+export function resolveDensityReference(value, tokens, seen = new Set()) {
+    const trimmed = value.trim();
+    const nodes = valueParser(trimmed).nodes;
+    if (nodes.length !== 1)
+        return undefined;
+    const [node] = nodes;
+    if (node.type !== "function" || node.value.toLowerCase() !== "var")
+        return trimmed;
+    const comma = node.nodes.findIndex((child) => child.type === "div" && child.value === ",");
+    const name = valueParser.stringify(comma === -1 ? node.nodes : node.nodes.slice(0, comma)).trim();
+    const fallback = comma === -1 ? undefined : valueParser.stringify(node.nodes.slice(comma + 1)).trim();
+    if (name in densityTokenKinds || seen.has(name))
+        return undefined;
+    const next = new Set([...seen, name]);
+    const declared = tokens.get(name);
+    if (declared !== undefined)
+        return resolveDensityReference(declared, tokens, next);
+    if (fallback)
+        return resolveDensityReference(fallback, tokens, next);
+    return undefined;
+}

package/dist/rules/tokenComplete.js

@@ -1,5 +1,6 @@
 import { unresolvedTokenReferences } from "../color.js";
 import { parseThemeContract, } from "../contracts.js";
+import { densityExpectation, densityTokenKinds, isValidDensityValue, resolveDensityReference, } from "../density.js";
 import { createThemeCollector } from "./theme.js";
 export async function loadThemeContract(url) {
     const { readFile } = await import("node:fs/promises");
@@ -116,6 +117,38 @@ export function createTokenCompleteRule({ computed = {}, contract, themes, }) {
                         }
                     }
                 }
+                // Density values are checked on the value the browser resolved when the
+                // evidence carries it; without evidence, a var() is checked through
+                // what it resolves to in this theme or its own fallback, and one that
+                // resolves to nothing stays with the reference check above. An invalid
+                // value is mandatory coverage, so no baseline can absorb it.
+                for (const [token, kind] of Object.entries(densityTokenKinds)) {
+                    if (!evidenceTokens.has(token))
+                        continue;
+                    const declaration = theme.declarations.get(token);
+                    // A derived token that is not declared here is validated through
+                    // its own source (the fallback token it derives from); reporting
+                    // it again from this theme would just duplicate that diagnostic.
+                    if (token in contract.derived && !declaration)
+                        continue;
+                    const raw = computedTheme[token] ?? declaration?.value;
+                    if (raw === undefined)
+                        continue;
+                    const value = /var\s*\(/iu.test(raw) ? resolveDensityReference(raw, tokens) : raw;
+                    if (value === undefined)
+                        continue;
+                    if (!isValidDensityValue(kind, value)) {
+                        result.uncovered.push({
+                            ...(declaration
+                                ? { column: declaration.column, line: declaration.line, path: declaration.path }
+                                : location),
+                            message: `Theme ${theme.name} has an invalid value for ${token}; expected ${densityExpectation(kind)}.`,
+                            nodeKind: "theme-density-value",
+                            rule: "tokens/complete",
+                            required: true,
+                        });
+                    }
+                }
             }
             return result;
         },

package/dist/theme-contract.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.0.0",
+  "contractVersion": "2.0.0",
   "schemaVersion": 1,
   "prefix": "--ui-",
   "required": [
@@ -62,7 +62,27 @@
     "--ui-radius-pill",
     "--ui-shadow-sm",
     "--ui-shadow-md",
-    "--ui-shadow-lg"
+    "--ui-shadow-lg",
+    "--ui-font-size-xs",
+    "--ui-font-size-sm",
+    "--ui-font-size-md",
+    "--ui-font-size-lg",
+    "--ui-font-size-xl",
+    "--ui-font-weight-strong",
+    "--ui-line-height-control",
+    "--ui-control-height-sm",
+    "--ui-control-height-md",
+    "--ui-control-height-lg",
+    "--ui-control-padding-inline-sm",
+    "--ui-control-padding-inline-md",
+    "--ui-control-padding-inline-lg",
+    "--ui-space-1",
+    "--ui-space-1-5",
+    "--ui-space-2",
+    "--ui-space-3",
+    "--ui-space-4",
+    "--ui-space-6",
+    "--ui-space-8"
   ],
   "derived": {
     "--ui-action-primary-border": "--ui-action-primary-bg",
@@ -71,7 +91,10 @@
     "--ui-status-success-border": "--ui-status-success",
     "--ui-status-warning-border": "--ui-status-warning",
     "--ui-status-danger-border": "--ui-status-danger",
-    "--ui-status-info-border": "--ui-status-info"
+    "--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"
   },
   "brandComposition": [
     "--ui-brand-primary",

package/package.json

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