synthesisui 0.16.228 → 0.16.233

package/dist/doctor/apply-fix.js

@@ -25,6 +25,7 @@
  */
 import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { nameToWrite } from "./scan.js";
 /**
  * A substituição numa linha só, e ela é deliberadamente burra.
  *
@@ -56,7 +57,15 @@ export function planFix(d, read) {
      * literal no texto que o primeiro já deixou.
      */
     for (const f of d.findings) {
-        if (!f.token) {
+        /**
+         * O NOME DELE GANHA - ver `nameToWrite` em `scan.ts`.
+         *
+         * `--fix --write` edita o arquivo DELE, então o nome que entra ali é o do vocabulário dele
+         * quando existe um. Era aqui que a troca virava renomeação: 737 das 995 sugestões medidas no
+         * repo vivo escreviam `--ds-*` sobre um valor que uma variável dele já nomeia.
+         */
+        const name = nameToWrite(f);
+        if (!name) {
             skipped.push({
                 file: f.file,
                 line: f.line,
@@ -73,7 +82,23 @@ export function planFix(d, read) {
          * `var(--ds-typography-scale-h1-font-size)` no repo do dono (05/08) - um canto que se move no dia
          * em que alguém edita a escala de tipo. Medido lá: 14 de 129, e 0 de 76 na biblioteca dele.
          */
-        if (f.crossFamily) {
+        /**
+         * O COMPRIMENTO QUE SEGUE A FONTE É DECISÃO DELE - ver `Finding.fontRelative`.
+         *
+         * `1em` e o degrau `1rem` do sistema são o mesmo número e não necessariamente o mesmo pixel. O
+         * comando MOSTRA a troca, porque sem ela não há conversa; escrevê-la sozinho em 933 lugares seria
+         * mudar o layout dele em silêncio por uma equivalência que a gente não pode conferir.
+         */
+        if (f.fontRelative) {
+            skipped.push({
+                file: f.file,
+                line: f.line,
+                literal: f.literal,
+                because: "font-relative",
+            });
+            continue;
+        }
+        if (f.crossFamily && !f.theirToken) {
             skipped.push({
                 file: f.file,
                 line: f.line,
@@ -100,7 +125,7 @@ export function planFix(d, read) {
             continue;
         const idx = f.line - 1;
         const current = body[idx];
-        const swapped = current === undefined ? null : swap(current, f.literal, f.token);
+        const swapped = current === undefined ? null : swap(current, f.literal, name);
         if (swapped === null) {
             /** O arquivo mudou desde a medição, ou o literal já foi trocado por outro achado. */
             skipped.push({
@@ -116,7 +141,7 @@ export function planFix(d, read) {
             file: f.file,
             line: f.line,
             literal: f.literal,
-            token: f.token,
+            token: name,
         });
     }
     for (const [file, body] of lines) {
@@ -154,11 +179,15 @@ export function describeFix(result, dry) {
     const coincidence = skipped.filter((s) => s.because === "cross-family").length;
     const unread = skipped.filter((s) => s.because === "unreadable").length;
     const decisions = skipped.filter((s) => s.because === "no-token").length;
+    /** O `em` que o comando mostra e não escreve - ver o guard em `planFix`. */
+    const relative = skipped.filter((s) => s.because === "font-relative").length;
     const lines = [];
     if (applied.length === 0) {
         lines.push(decisions > 0
             ? `Nothing to apply. All ${decisions} findings are values your system has no name for - those are design decisions, not fixes.`
-            : "Nothing to apply.");
+            : relative > 0
+                ? `Nothing to apply. All ${relative} findings are lengths in \`em\`, which follow the element's font size - swapping them can move the layout, so that call is yours.`
+                : "Nothing to apply.");
         return lines;
     }
     lines.push(`${dry ? "Would replace" : "Replaced"} ${applied.length} hand-written value${applied.length === 1 ? "" : "s"} with the token your system already has, across ${result.files} file${result.files === 1 ? "" : "s"}.`);
@@ -169,6 +198,12 @@ export function describeFix(result, dry) {
         .sort((a, b) => b[1] - a[1])
         .slice(0, 6))
         lines.push(`  var(${token}) · ${n} time${n === 1 ? "" : "s"}`);
+    /**
+     * DITO SEMPRE QUE ACONTECE - senão o número de "trocado" some da conta sem explicação, e a pessoa
+     * conclui que o comando falhou onde ele se recusou de propósito.
+     */
+    if (relative > 0)
+        lines.push(`  ${relative} more ${relative === 1 ? "is a length" : "are lengths"} in \`em\`, which follow the element's font size - your system names the same number, but the pixel may differ. Left for you to decide.`);
     if (moved > 0)
         lines.push(`${moved} line${moved === 1 ? "" : "s"} changed since the scan and ${moved === 1 ? "was" : "were"} left alone - run it again.`);
     if (coincidence > 0)

package/dist/doctor/scan.js

@@ -10,6 +10,15 @@
  * takes eight seconds and needs a build step is a diagnosis nobody runs.
  */
 import { normalizeValue, tokenMatch } from "./tokens.js";
+/**
+ * O NOME QUE SE ESCREVE NO ARQUIVO DELE - e existe uma função só para isto por um motivo.
+ *
+ * Seis lugares decidem o que a pessoa vê ou o que o `--fix` grava: o relatório, o plano, o hook, o
+ * MCP, a aplicação e a contagem. Deixar cada um lembrar de preferir `theirToken` é o padrão do
+ * argumento opcional que se esquece - e o sintoma seria o pior possível: o comando aconselhando um
+ * nome e o hook aconselhando outro, sobre o mesmo arquivo.
+ */
+export const nameToWrite = (f) => f.theirToken ?? f.token;
 /**
  * `next/og` renders JSX to a PNG on the server. There is no document, so there
  * is no `var(--ds-*)` to read: every colour in such a file MUST be a literal.
@@ -54,9 +63,35 @@ const OPEN = `["']?`;
 /** `rounded-[14px]`, `border-radius: 14px`, `borderRadius: "14px"`. Zero and
  *  full pills are idiom, not drift - nobody tokenizes `0` or `9999px`. */
 const RADIUS = new RegExp(`(?:border-?[Rr]adius\\s*:\\s*${OPEN}|rounded(?:-[a-z]+)?-\\[)(-?\\d*\\.?\\d+)(px|rem|em)`, "g");
-/** Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`, `gap: "18px"`.
- *  The JSX side also writes `paddingLeft`, `marginTop` and friends. */
-const SPACING = new RegExp(`(?:\\b[pmg](?:[trblxy])?-\\[|gap-\\[|(?:padding|margin|gap)(?:[A-Z][a-z]+)?\\s*:\\s*${OPEN})(-?\\d*\\.?\\d+)(px|rem)`, "g");
+/**
+ * Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`, `gap: "18px"`.
+ * The JSX side also writes `paddingLeft`, `marginTop` and friends.
+ *
+ * `em` ENTROU EM 13/08, e a falta dele era uma palavra: o padrão do RAIO logo acima já aceitava as
+ * três unidades e o do espaçamento aceitava duas. Não era doutrina, era assimetria - e o custo dela é
+ * o pior tipo, porque um valor que a varredura não vê não aparece nem como lacuna.
+ *
+ * Medido no repositório real, o que estava invisível:
+ *
+ *     933  espaçamentos em `em`   300×0.5em · 276×1em · 116×0.25em
+ *     144  raios em `em`          lidos, mas nunca nomeados (ver `normalizeValue`)
+ *     325  arquivos
+ *
+ * O dono achou pelo caminho que a gente não quer que ele precise usar (13/08): a skill abriu o
+ * `.scss` por conta própria e listou quatro `em` que o comando tinha acabado de chamar de limpo -
+ * *"não chegou nem a entrar no css, acho isso errado"*.
+ *
+ * E O KEBAB VEIO NA MESMA PUXADA, escondido atrás do primeiro. O sufixo aceito era só o camelCase
+ * do JSX (`paddingLeft`), então `padding-right: 1em` - a forma que TODO css escreve - não casava com
+ * nada. Foram os quatro `em` daquele mesmo arquivo que denunciaram: com `em` já no padrão, um
+ * continuou aparecendo e três não.
+ *
+ *     1175  `padding-*`/`margin-*` em kebab, em 335 arquivos do repositório real
+ *
+ * Duas gramáticas para a mesma propriedade é o tipo de coisa que só aparece quando alguém aponta
+ * para um arquivo e conta na mão.
+ */
+const SPACING = new RegExp(`(?:\\b[pmg](?:[trblxy])?-\\[|gap-\\[|(?:padding|margin|gap)(?:[A-Z][a-z]+|(?:-[a-z]+)+)?\\s*:\\s*${OPEN})(-?\\d*\\.?\\d+)(px|rem|em)`, "g");
 /** A font stack written by hand rather than taken from the type scale. */
 const FONT = /font-family\s*:\s*([^;}\n]+)/g;
 /**
@@ -370,11 +405,22 @@ function scanCore(file, source, table) {
             // The kind is already known here, and without passing it the lookup
             // answers a `gap` with a radius token.
             const match = tokenMatch(table, literal, kind);
+            /**
+             * O NOME DELE VEM DA MESMA CHAVE QUE A NOSSA FAMÍLIA VALIDOU - ver `theirNames`.
+             *
+             * A chave carrega o `kind` porque o valor sozinho não decide: `4px` é `--radius-xs` e
+             * `--spacing` no vocabulário dele, e qual dos dois está certo depende de onde o literal está.
+             */
+            const theirs = table.aliases.get(`${kind}:${normalizeValue(literal, table.rootPx)}`);
             findings.push({
                 kind,
                 line: at,
                 literal,
                 token: match?.token ?? null,
+                ...(/(?<!r)em$/i.test(literal.trim())
+                    ? { fontRelative: true }
+                    : {}),
+                ...(theirs ? { theirToken: theirs } : {}),
                 /**
                  * A COINCIDÊNCIA VIAJA COM O ACHADO - ver `tokenMatch`.
                  *
@@ -562,6 +608,8 @@ export function diagnose(files) {
             byLiteral.set(key, {
                 kind: f.kind,
                 token: f.token,
+                ...(f.theirToken ? { theirToken: f.theirToken } : {}),
+                ...(f.fontRelative ? { fontRelative: true } : {}),
                 count: 1,
                 files: new Set([f.file]),
                 ...(f.crossFamily ? { crossFamily: true } : {}),
@@ -573,6 +621,8 @@ export function diagnose(files) {
         literal: key.slice(key.indexOf(":") + 1),
         kind: v.kind,
         token: v.token,
+        ...(v.theirToken ? { theirToken: v.theirToken } : {}),
+        ...(v.fontRelative ? { fontRelative: true } : {}),
         count: v.count,
         files: v.files.size,
         ...(v.crossFamily ? { crossFamily: true } : {}),
@@ -585,7 +635,15 @@ export function diagnose(files) {
         files: files.filter((f) => f.findings.length > 0 || (f.phantoms?.length ?? 0) > 0),
         findings: flat,
         counts,
-        named: flat.filter((f) => f.token).length,
+        /**
+         * QUANTOS JÁ TÊM NOME NESTE REPOSITÓRIO - e o dele conta.
+         *
+         * Este número é a promessa que a tela faz ("9 of those have a name waiting"), e enquanto ele
+         * contava só os nossos, 852 achados que o repositório DELE nomeia saíam como "the system has no
+         * name for it". Uma promessa medida por metade do vocabulário que existe é uma promessa menor
+         * que a verdade.
+         */
+        named: flat.filter((f) => nameToWrite(f)).length,
         tokenUses,
         phantomUses,
         coverage: total === 0 ? 100 : Math.round(((tokenUses + ownUses) / total) * 100),

package/dist/doctor/their-names.js

@@ -0,0 +1,175 @@
+import { DS_FAMILY, familySays, normalizeValue, } from "./tokens.js";
+/**
+ * COMO ELE CHAMA O VALOR - para a gente parar de renomear as variáveis dele.
+ *
+ * O doctor sempre soube dizer o que o sistema chama de `#888`. O que ele fazia com isso é que estava
+ * errado: mandava trocar por `var(--ds-color-gray-400)` num repositório que declara
+ * `--color-lightgray-700: #888888` desde antes de a gente existir. `--fix --write` escrevia o NOSSO
+ * nome dentro do arquivo dele.
+ *
+ * Medido no repositório vivo em 13/08, repo inteiro:
+ *
+ *     141  tokens que ELE declara
+ *     181  tokens que o sistema declara
+ *     114  dos nossos seguram um valor que um dos dele também segura
+ *
+ *     995  achados com nome nosso
+ *     737  deles (74%) renomeavam uma variável que ele já tem
+ *
+ * E o grupo que saía como "the system has no name for it":
+ *
+ *    5383  sem nome nosso
+ *     852  ...mas o repositório DELE nomeia   (843 cor · 8 tipo · 1 motion)
+ *
+ * A LEI JÁ EXISTIA, num sentido só. `absorb-plan.ts` diz, sobre a direção repo -> sistema: *"quando o
+ * vocabulário DELES já nomeia o valor, o nome é o deles"*. Na direção sistema -> repo a gente fazia o
+ * contrário. É a mesma lei 11 um nível abaixo da cor: não reescrever o vocabulário dele.
+ *
+ * ESTE MAPA NÃO É UM ARQUIVO, e é de propósito (dono, 13/08: *"talvez essas informações possam vir do
+ * MCP para não levar isso para o usuário ficar vendo"*). Ele é derivado das folhas de estilo dele a
+ * cada rodada - 686 folhas e 797KB no repo real, 4ms no hook inteiro (80ms -> 84ms, medido ponta a
+ * ponta), e o `absorb` já pagava essa varredura hoje. Um
+ * mapa gravado envelhece no dia em que ele renomeia um token, e aí a gente sugere um nome que não
+ * existe mais. O MCP ganha de graça, porque `check_file` roda este mesmo doctor.
+ *
+ * E ele nunca aparece na tela: o que aparece é o nome DELE, no lugar onde antes aparecia o nosso.
+ */
+/**
+ * QUANDO A FORMA DO VALOR JÁ DECIDE A FAMÍLIA - e é isto que a segunda porta pede.
+ *
+ * A porta admitia só COR, e o motivo estava certo pela metade: o que impede um comprimento de entrar
+ * é a AMBIGUIDADE (`24px` pode ser raio, espaçamento ou tamanho de fonte, e sem um token nosso não há
+ * o que decidisse), não o fato de ser cor. Uma pilha de fontes não é ambígua - `'Figtree', sans-serif`
+ * não pode ser um espaçamento -, e uma duração também não: `s` e `ms` só existem em motion.
+ *
+ * Então a regra é a forma, e o comprimento continua de fora, declarado. Medido no repositório real em
+ * 14/08: 7 achados em 6 arquivos saíam como "the system has no name for it" sobre a família de fontes
+ * que o próprio css dele nomeia `--dashboard-font-family`. É pouco, e é o único grupo que sobrou do
+ * item que eu tinha nomeado - os `em` saíram na leva anterior.
+ */
+const UNAMBIGUOUS = {
+    /** `#rrggbbaa`, que é onde toda a família de dialetos cai. */
+    color: /^#[0-9a-f]{8}$/,
+    /** `s` e `ms` não aparecem em nenhuma outra família do contrato. */
+    motion: /^-?[\d.]+ms$/,
+    /** Uma pilha de fontes: tem vírgula, ou é uma das palavras genéricas do CSS. */
+    font: /,|^(?:serif|sans-serif|monospace|cursive|fantasy|system-ui)$/,
+};
+const segments = (name) => name.replace(/^--/, "").split("-");
+/**
+ * QUAL DOS NOMES DELE, quando mais de um segura o mesmo valor - e são 18 no repo real.
+ *
+ * O empate não é decorativo: `4px` é `--radius-xs` E `--spacing` lá dentro, `24px` é `--text-h2` E
+ * `--spacing-lg`. Escolher errado escreve um token de tipo numa posição de espaçamento, que é
+ * exatamente o erro de categoria que o `crossFamily` foi criado para impedir do nosso lado.
+ *
+ * Três critérios, nesta ordem, e todos LIDOS do repositório dele:
+ *
+ *     1. quantos segmentos ele compartilha com o nosso token daquela família
+ *        `--ds-radius-xs` puxa `--radius-xs` (2) e não `--spacing` (0)
+ *     2. a convenção dominante dele - o primeiro segmento mais frequente entre os tokens dele
+ *        no repo real, `--color-*` (57) contra `--dashboard-*` (25)
+ *     3. ordem de declaração, que é o desempate que sempre existe e nunca inventa
+ */
+function pick(candidates, ours, convention) {
+    const mine = ours ? new Set(segments(ours)) : null;
+    let best = candidates[0];
+    let bestScore = [-1, -1];
+    for (const name of candidates) {
+        const parts = segments(name);
+        const shared = mine ? parts.filter((p) => mine.has(p)).length : 0;
+        const score = [
+            shared,
+            convention.get(parts[0] ?? "") ?? 0,
+        ];
+        if (score[0] > bestScore[0] ||
+            (score[0] === bestScore[0] && score[1] > bestScore[1])) {
+            best = name;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+/**
+ * O MAPA DE UMA RODADA: `<natureza>:<valor normalizado>` -> como ELE chama.
+ *
+ * A chave carrega a natureza porque o valor sozinho não decide: o mesmo `4px` tem dois nomes no
+ * vocabulário dele, e qual dos dois está certo depende de o literal estar num raio ou num
+ * espaçamento. É a mesma razão pela qual `tokenMatch` recebe o `kind`.
+ *
+ * DUAS PORTAS, e a segunda é o que faz o número dobrar:
+ *
+ *     o sistema nomeia o valor     a NOSSA família valida a natureza, e o nome dele entra
+ *     o sistema NÃO nomeia         entra o valor cuja FORMA já decide a família - ver `UNAMBIGUOUS`
+ *
+ * O que fica de fora da segunda porta é o COMPRIMENTO, e ele fica por um motivo e não por descuido:
+ * `24px` pode ser raio, espaçamento ou tamanho de fonte, e sem um token nosso não há o que validasse.
+ * Esses continuam saindo como "no name for it", que é verdade e é o caminho do `absorb`.
+ */
+export function theirNames(ours, theirs) {
+    const out = new Map();
+    if (theirs.byName.size === 0)
+        return out;
+    /** A convenção dominante dele, contada e não suposta - ver `pick`. */
+    const convention = new Map();
+    for (const name of theirs.byName.keys()) {
+        const head = segments(name)[0] ?? "";
+        convention.set(head, (convention.get(head) ?? 0) + 1);
+    }
+    for (const [kind, prefix] of Object.entries(DS_FAMILY)) {
+        for (const [name, raw] of ours.byName) {
+            if (!name.startsWith(prefix))
+                continue;
+            const value = normalizeValue(raw, ours.rootPx);
+            const key = `${kind}:${value}`;
+            if (out.has(key))
+                continue;
+            const candidates = theirs.byValue.get(value);
+            if (!candidates || candidates.length === 0)
+                continue;
+            /**
+             * E A CATEGORIA DO NOME DELE TEM QUE FECHAR - senão o nosso nome fica, e ele está certo.
+             *
+             * O NOSSO prefixo carrega a família por construção; o dele não carrega nada garantido. Quando a
+             * FORMA do valor já decide (hex, `ms`, pilha de fontes) não há o que proteger e o nome dele
+             * entra. Quando o valor é um comprimento cru, `12px` pode ser `--text-caption` ou `--spacing-sm`
+             * no vocabulário dele, e escolher errado escreve um token de tipo num `border-radius`.
+             *
+             * Medido no repositório real em 14/08, antes desta linha: 290 sugestões com a categoria trocada,
+             * 66 delas gravadas por um `--fix --write`, e a pior na PRIMEIRA página do relatório -
+             * `0.25em → --radius-xs` em 116 arquivos. Ver `FAMILY_WORDS`.
+             *
+             * Recusar aqui não perde informação: sem alias, `nameToWrite` cai no NOSSO token, que é da
+             * família certa porque foi o prefixo dela que o trouxe a este laço.
+             */
+            const formDecides = Object.values(UNAMBIGUOUS).some((f) => f.test(value));
+            const usable = formDecides
+                ? candidates
+                : candidates.filter((n) => familySays(kind, n));
+            if (usable.length === 0)
+                continue;
+            out.set(key, pick(usable, name, convention));
+        }
+    }
+    for (const [value, candidates] of theirs.byValue) {
+        for (const [kind, form] of Object.entries(UNAMBIGUOUS)) {
+            if (!form.test(value))
+                continue;
+            const key = `${kind}:${value}`;
+            if (out.has(key))
+                continue;
+            out.set(key, pick(candidates, null, convention));
+        }
+    }
+    return out;
+}
+/**
+ * A TABELA COM O VOCABULÁRIO DELE DENTRO - um passo, e é este que os comandos chamam.
+ *
+ * `ours` continua sendo a lei: é ela que diz se `2rem` é tipo ou raio, e é dela que sai a cobertura.
+ * A dele decide só COMO SE ESCREVE. Separar as duas é o mesmo desenho que o `absorb` já usa
+ * ("DUAS TABELAS, e é a diferença entre elas que define o trabalho").
+ */
+export function withTheirNames(ours, theirs) {
+    return { ...ours, aliases: theirNames(ours, theirs) };
+}

package/dist/doctor/tokens.js

@@ -31,6 +31,7 @@ export const EMPTY_TABLE = {
     byValue: new Map(),
     rootPx: DEFAULT_ROOT_PX,
     rootFrom: null,
+    aliases: new Map(),
     declared: new Set(),
     keyframes: new Set(),
 };
@@ -120,10 +121,19 @@ export function normalizeValue(raw, rootPx) {
      * A FAMÍLIA CONTINUA MANDANDO: `4px` passa a casar com `--ds-radius-xs` E com `--ds-spacing-3xs`,
      * e é `tokenMatch` quem escolhe pelo `kind` - um raio não vira espaçamento dentro de um `gap`.
      */
-    const len = /^(-?\d*\.?\d+)(px|rem)$/.exec(v);
+    /**
+     * `em` CAI AQUI JUNTO, e o que impede isso de virar uma suposição é o achado, não o normalizador.
+     *
+     * Converter `1em` por `rootPx` é certo sempre que a fonte do elemento é a da raiz, e errado quando
+     * um ancestral a mudou - e isto aqui não tem como saber qual dos dois. Ele converte para a
+     * CONVERSA existir (sem isto, `1em` não casa com degrau nenhum e sai como "o sistema não nomeia
+     * isto", sobre um valor que o sistema nomeia); quem impede a troca automática é `Finding.fontRelative`,
+     * que o `--fix` recusa. Ver `scan.ts`.
+     */
+    const len = /^(-?\d*\.?\d+)(px|r?em)$/.exec(v);
     if (len) {
         const n = Number.parseFloat(len[1]);
-        const px = len[2] === "rem" ? n * rootPx : n;
+        const px = len[2] === "px" ? n : n * rootPx;
         /** Arredonda o rastro binário: `0.35rem * 16` é 5.6000000000000005. */
         return `${Math.round(px * 1e4) / 1e4}px`;
     }
@@ -431,6 +441,8 @@ export function buildTable(input) {
         byValue,
         rootPx,
         rootFrom: input.rootFrom ?? null,
+        /** Vazio até `withTheirNames` ler o vocabulário dele - ver `their-names.ts`. */
+        aliases: new Map(),
         declared: parseDeclaredNames(input.css),
         keyframes: new Set([...input.css.matchAll(/@keyframes\s+([a-zA-Z0-9_-]+)/g)].map((m) => m[1])),
     };
@@ -492,13 +504,56 @@ export function nearestToken(table, literal) {
  * radius is one a person stops reading, and this one has exactly one job that
  * nobody else does: naming the right token.
  */
-const FAMILY = {
+/** Exportado para `their-names.ts`, que precisa da MESMA divisão de família para validar a natureza
+ *  de um nome dele - duas tabelas de família seriam duas leis. */
+export const DS_FAMILY = {
     color: "--ds-color-",
     radius: "--ds-radius-",
     spacing: "--ds-spacing-",
     font: "--ds-typography-",
     motion: "--ds-motion-",
 };
+/**
+ * AS PALAVRAS COM QUE O MUNDO NOMEIA CADA FAMÍLIA - e é isto que impede um erro de categoria.
+ *
+ * O NOSSO prefixo carrega a família (`--ds-spacing-md` é espaçamento por construção). O DELE não
+ * carrega nada garantido, e nada verificava: `--text-caption` e `--spacing-sm` podem segurar o mesmo
+ * `12px`, e sugerir o primeiro para um `border-radius` é escrever um token de tipo numa posição de
+ * raio. É exatamente o erro que o `crossFamily` foi criado para impedir do NOSSO lado, e ele passou
+ * a acontecer pelo lado dele quando o mapa de vocabulário nasceu.
+ *
+ * Medido no repositório real em 14/08, antes desta trava:
+ *
+ *     2680  achados com nome dele
+ *     1635  categoria concorda
+ *      290  categoria DISCORDA   <- sugestão errada na tela
+ *       66  dessas o `--fix --write` GRAVARIA (o resto é `em`, que já tem trava)
+ *      755  nome sem palavra de categoria - e são todos cor (748) e fonte (7)
+ *
+ * A pior estava na primeira página: `0.25em → --radius-xs` em 116 arquivos, na lista das mais
+ * repetidas. E `4px → --radius-xs` num padding é uma escrita silenciosa, sem `em` para barrá-la.
+ *
+ * `text` está na lista de tipo porque `--text-h2` é a forma dominante no mundo real, e `transition`
+ * na de motion pelo mesmo motivo.
+ */
+export const FAMILY_WORDS = {
+    color: ["color", "colour"],
+    radius: ["radius", "rounded", "corner"],
+    spacing: ["spacing", "space", "gap", "inset"],
+    font: ["font", "type", "text"],
+    motion: ["duration", "motion", "ease", "easing", "transition"],
+};
+/**
+ * O NOME DELE DIZ QUE É DESTA FAMÍLIA - por QUALQUER segmento, não só pelo primeiro.
+ *
+ * `--dashboard-radius-lg` é um raio e o primeiro segmento é o namespace dele. Olhar só o começo
+ * recusaria um nome certo por causa de um prefixo de produto, que é a metade oposta do mesmo erro.
+ */
+export const familySays = (kind, name) => {
+    const words = FAMILY_WORDS[kind] ?? [];
+    const segments = name.replace(/^--/, "").toLowerCase().split("-");
+    return segments.some((seg) => words.includes(seg));
+};
 /**
  * O token que carrega este valor, e SE ELE É DA MESMA FAMÍLIA.
  *
@@ -521,7 +576,7 @@ export function tokenMatch(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal, table.rootPx));
     if (!hit || hit.length === 0)
         return null;
-    const prefix = kind ? FAMILY[kind] : undefined;
+    const prefix = kind ? DS_FAMILY[kind] : undefined;
     const family = prefix ? hit.filter((n) => n.startsWith(prefix)) : [];
     const pool = family.length > 0 ? family : hit;
     // Semantic roles name intent; primitives name a shelf. Prefer intent.

package/dist/install-marks.js

@@ -71,7 +71,16 @@
  * a prop, e 104 das 207 condições sem expressão nenhuma. Um `upgrade` anterior a esta versão reescreve
  * os componentes dele com a perda intacta.
  */
-export const MATERIALISER_SINCE = "0.16.220";
+/**
+ * 0.16.220 -> 0.16.233 em 14/08: o componente materializado muda de bytes. A regra de contenção HTML
+ * era enumerada à mão em `elementFor` e a enumeração esquecia `heading`, `row` e `stack` - uma raiz de
+ * papel `action` com um heading no topo saía como `<button><h3>…</h3></button>`, que é marcação
+ * inválida embarcada num copy-paste. Agora sai `<article>`.
+ *
+ * Zero ocorrências no sistema real medido (todos os headings dele estão aninhados, e o `children > 0`
+ * já os pegava), então para ele o `upgrade` é no-op. A marca é sobre o caso geral.
+ */
+export const MATERIALISER_SINCE = "0.16.233";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -96,7 +105,41 @@ export const MATERIALISER_SINCE = "0.16.220";
  * tem nome para isto" sobre um valor que o sistema dela nomeia - medido no repo real, 243 trocas
  * viraram 764 sobre os mesmos 4433 valores à mão.
  */
-export const CHECKER_SINCE = "0.16.223";
+/**
+ * 0.16.223 -> 0.16.229 em 13/08, e o SIM mais forte que esta marca já teve: o hook passou a
+ * aconselhar o nome DELE. Um pin anterior lê o mesmo arquivo e manda escrever
+ * `var(--ds-color-gray-400)` num repositório que declara `--color-lightgray-700: #888888` - e a
+ * pessoa acaba com dois conselhos diferentes sobre o mesmo valor, porque o `doctor` de hoje diz o
+ * nome dela. Medido no repo real: 737 de 995 sugestões renomeavam uma variável dela, e outras 852
+ * saíam como "o sistema não nomeia isto" sobre valores que o repositório dela nomeia.
+ *
+ * É também a primeira vez que o hook VARRE as folhas de estilo, revisando a escolha declarada em
+ * `loadSystem` - medido ponta a ponta no repo real, 80ms -> 84ms, contra oferecer o nome errado.
+ */
+/**
+ * 0.16.229 -> 0.16.230 em 13/08: `em` passou a ser um comprimento como os outros. O padrão do RAIO
+ * já aceitava as três unidades e o do ESPAÇAMENTO aceitava duas - assimetria, não doutrina - e um
+ * hook pinado antes disto lê o mesmo arquivo e não vê 933 espaçamentos e 144 raios, em 325 arquivos
+ * do repositório real. Não é medir menos: é chamar de limpo o que não é.
+ *
+ * A 0.16.229 nunca chegou ao npm, mas a marca sobe assim mesmo - uma marca que aponta para uma
+ * versão que ninguém pode instalar é uma marca que nunca dispara.
+ */
+/**
+ * 0.16.230 -> 0.16.231 em 14/08: a segunda porta do mapa de vocabulário deixou de ser "só cor" e
+ * passou a ser "a forma que já decide a família" - uma pilha de fontes não pode ser um espaçamento, e
+ * `ms` só existe em motion. Um hook pinado antes disto olha o arquivo que a pessoa acabou de escrever
+ * e diz que o sistema não nomeia a fonte que o css dela nomeia. Medido no repositório real: as trocas
+ * com nome disponível foram de 1624 para 1631.
+ */
+/**
+ * 0.16.231 -> 0.16.232 em 14/08, e este é o pior que esta marca já carregou: o pinado não erra por
+ * omissão, ele erra o CONSELHO. O mapa de vocabulário escolhia entre os nomes DELE sem conferir a
+ * categoria, então um hook pinado antes disto olha um `border-radius: 12px` recém-escrito e manda usar
+ * `var(--text-caption)` - um token de tipo numa posição de raio. Medido no repositório real: 290
+ * sugestões com a categoria trocada, 66 delas graváveis por um `--fix --write`.
+ */
+export const CHECKER_SINCE = "0.16.232";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/dist/measured-scope.js

@@ -117,7 +117,9 @@ export function describeScope(m) {
             ]
             : []),
     ];
-    return `read from your census: ${parts.join(" · ")}`;
+    /** O ARQUIVO, e não a palavra: "census" é o nosso nome para a medição; `_synthesisui/census.json`
+     *  é um caminho que ele abre. Ver a guarda de vocabulário em `doctor-intent.spec.ts`. */
+    return `read from _synthesisui/census.json: ${parts.join(" · ")}`;
 }
 /**
  * GRAVA ONDE ESTE SISTEMA FOI MEDIDO, no ponteiro dele.