synthesisui 0.16.248 → 0.16.250

package/dist/absorb-plan.js

@@ -170,15 +170,26 @@ export function describeAbsorb(plan) {
         return [
             "Nothing to absorb: every repeated value your code writes by hand already has a name in the system.",
         ];
-    lines.push(`${ready.length} of ${plan.entries.length} values already have a name in YOUR vocabulary - those travel as they are:`);
+    /**
+     * A SEÇÃO DOS QUE JÁ TÊM NOME SÓ EXISTE SE ALGUM TIVER - e no dia 1 nenhum tem.
+     *
+     * Quem começa do zero não declarou um token ainda, então isto abria com "0 of 4 values
+     * already have a name" e uma lista vazia: a primeira frase do comando dizendo um zero que
+     * não é notícia nenhuma, antes da única seção que importa para ela.
+     */
+    if (ready.length > 0)
+        lines.push(`${ready.length} of ${plan.entries.length} values already have a name in YOUR vocabulary - those travel as they are:`);
     for (const e of ready.slice(0, 8))
         lines.push(`  ${e.value.padEnd(24)} ${e.path.padEnd(28)} ${e.files} file${e.files === 1 ? "" : "s"}${e.theirName ? ` · your ${e.theirName}` : ""}`);
     if (ready.length > 8)
         lines.push(`  (${ready.length - 8} more)`);
     if (pending.length > 0) {
         const close = pending.filter((e) => e.near);
-        lines.push("");
-        lines.push(`${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`);
+        if (ready.length > 0)
+            lines.push("");
+        lines.push(ready.length > 0
+            ? `${pending.length} nobody names yet. Naming is a design decision, so those wait for a word from you:`
+            : `${pending.length} repeated values, and none of them has a name yet. Naming is a design decision, so each waits for a word from you:`);
         for (const e of pending.slice(0, 8))
             lines.push(`  ${e.value.padEnd(24)} ${`<${e.kind}, ${e.files} file${e.files === 1 ? "" : "s"}>`.padEnd(28)} ${e.near ? `≈ your ${e.near.name} (${e.near.away})` : 'path: ""'}`);
         if (pending.length > 8)

package/dist/commands/absorb.js

@@ -32,11 +32,23 @@ export async function absorb(opts) {
     if (opts.send)
         return sendProposal(root, path, opts.registry);
     const installed = await loadSystem(root);
-    if (!installed.table.slug) {
-        console.log(section("Absorb"));
-        console.log(body("No system installed here, so there is nothing to absorb INTO. `synthesisui list` shows what you can add."));
-        return;
-    }
+    /**
+     * SEM SISTEMA INSTALADO ISTO CONTINUA VALENDO - e recusar aqui fechava o dia 1.
+     *
+     * Este comando recusava com "não há nada para absorver PARA DENTRO", o que confundia o
+     * DESTINO com o TRABALHO. O trabalho é ler os valores que ela escreveu à mão e propor um
+     * nome para cada um; ele não depende de sistema nenhum, e as quatro coisas de que ele
+     * precisa já funcionam sem um: a tabela vem vazia (nada tem nome, então tudo é candidato),
+     * o vocabulário lido é o DELA, e a fundação existente é um conjunto vazio.
+     *
+     * Quem começa do zero era justamente quem mais precisava disto e quem menos podia rodar:
+     * ela escreve o primeiro componente, o doctor diz "9 valores à mão, nenhum tem nome", e o
+     * comando que dá nome respondia que não. Caminhado num projeto em branco em 18/08.
+     *
+     * O DESTINO É QUE MUDA, e ele se resolve sozinho: sem sistema, os tokens pertencem ao CSS
+     * dela - o mesmo caminho que `absorb: "code"` já servia a quem escolheu. Ver `sendProposal`.
+     */
+    const hasSystem = Boolean(installed.table.slug);
     const measured = await measuredScope(root);
     const rel = scopePaths(measured);
     const roots = rel.length > 0 ? rel.map((s) => resolve(root, s)) : [root];
@@ -61,7 +73,9 @@ export async function absorb(opts) {
         reports.push(scanSource(file.slice(root.length + 1), source, installed.table));
     }
     const plan = absorbPlan(diagnose(reports), theirs, pathsInSystem(installed.documents), opts.cap ?? 40);
-    console.log(section("What the system could absorb"));
+    console.log(section(hasSystem
+        ? "What the system could absorb"
+        : "Name what you wrote by hand"));
     console.log(body(paint.dim(`read from ${rel.length > 0 ? rel.join(", ") : "this project"} · your own vocabulary read from the root`)));
     console.log("");
     for (const line of describeAbsorb(plan))
@@ -69,7 +83,7 @@ export async function absorb(opts) {
     if (plan.entries.length === 0)
         return;
     const proposal = {
-        slug: installed.table.slug,
+        slug: installed.table.slug ?? null,
         at: new Date().toISOString(),
         scope: rel,
         entries: plan.entries,
@@ -146,17 +160,25 @@ async function sendProposal(root, path, registry) {
      * colar. Nunca escrevemos no arquivo do cliente - e o import seguinte lê os tokens de volta, o que faz
      * o caminho fechar sem nós tocarmos em nada.
      */
-    const target = (await readProjectConfig(root)).absorb ?? "system";
+    /**
+     * E SEM SISTEMA O DESTINO NÃO É UMA PREFERÊNCIA, é a única resposta que existe: os tokens
+     * pertencem ao CSS dela, porque não há outro lugar. Um `system` configurado aqui apontaria
+     * para um slug nulo e a chamada morreria num 404 depois de ela ter nomeado tudo à mão.
+     */
+    const configured = (await readProjectConfig(root)).absorb ?? "system";
+    const target = proposal.slug ? configured : "code";
     if (target === "code") {
         console.log(section("Paste this into your own vocabulary"));
-        console.log(body(paint.dim("Your config says absorbed values belong in your CSS, so nothing was sent.")));
+        console.log(body(paint.dim(proposal.slug
+            ? "Your config says absorbed values belong in your CSS, so nothing was sent."
+            : "You have no system yet, so these belong in your own CSS - nothing was sent, and nothing needed an account.")));
         console.log("");
         console.log("  :root {");
         for (const e of ready)
             console.log(`    --${e.path.replace(/\./g, "-")}: ${e.value};`);
         console.log("  }");
         console.log("");
-        console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor cobra them by your own names."));
+        console.log(body("The next import or `sync` reads these back as tokens you declared, and from then on the doctor holds your code to them by your own names."));
         return;
     }
     const token = await readToken();

package/dist/commands/doctor.js

@@ -401,6 +401,18 @@ function verdict(d, hasSystem, overruled, conflicts) {
             body("installed. Nothing to fix, and nothing to compare against."),
         ];
     }
+    /**
+     * O DIA ZERO - e o comando que serve a ele não era dito em lugar nenhum.
+     *
+     * "Dê um nome a eles" seguido de `init --ds <slug>` e o link da galeria oferece UMA saída, e
+     * ela é adotar o vocabulário de outra pessoa. A outra saída existe, faz exatamente o que a
+     * frase promete, e roda aqui mesmo sem conta e sem rede: `absorb` lê os valores repetidos e
+     * pede um nome para cada um. Ele passou a rodar sem sistema instalado neste mesmo PR, e uma
+     * capacidade que a pessoa precisa adivinhar não existe.
+     *
+     * A ordem é a da decisão dela: nomear o que ela já escreveu vem antes de escolher o de
+     * alguém, porque o primeiro é sobre o código que está na tela dela agora.
+     */
     if (!hasSystem) {
         const distinct = new Set(d.findings.map((f) => f.literal.toLowerCase()));
         return [
@@ -408,7 +420,10 @@ function verdict(d, hasSystem, overruled, conflicts) {
             body(`${distinct.size} distinct design values are written by hand here.`),
             body("No design system is installed, so none of them has a name yet."),
             "",
-            body("Give them one:"),
+            body("Name them yourself - this reads them and asks you for the words:"),
+            snippet(["npx synthesisui@latest absorb"]),
+            "",
+            body("Or start from a system somebody already published:"),
             snippet(["npx synthesisui@latest init --ds <slug>"]),
             body("Browse systems at https://www.synthesisui.com/gallery"),
         ];
@@ -784,7 +799,19 @@ export async function doctor(opts) {
      * na mesma tela (dono: "fiquei perdido"). Ou o número não significa nada, ou existe uma lista de
      * prioridades; as duas não cabem juntas.
      */
-    const blocked = hasSystem && (!wiring.imported || !wiring.scoped);
+    /**
+     * A FIAÇÃO SÓ EXISTE PARA UM SISTEMA NOSSO - e usar "tem nomes" no lugar disso recusava o
+     * `--fix` a quem nunca instalou nada (medido em 18/08, no caminho de quem começa do zero).
+     *
+     * Ela escreve os tokens dela no próprio `:root`, o doctor passa a dizer "7 dos seus valores
+     * têm nome", e o `--fix` respondia "trocar agora apontaria para variáveis que o navegador não
+     * resolve". Ele resolve: o CSS é dela e já está na página. A frase era literalmente falsa, e
+     * ela aparece no primeiro comando que promete adotar.
+     *
+     * `table.source` é a distinção certa e ela já estava aqui, uma linha abaixo, em `unwired`:
+     * `"yours"` e `"adopted"` são o vocabulário dela, e não há duas linhas para ligar.
+     */
+    const blocked = table.source === "installed" && (!wiring.imported || !wiring.scoped);
     const unwired = table.source === "installed" &&
         (!wiring.imported || !wiring.scoped || fontsPending);
     if (unwired) {
@@ -897,7 +924,15 @@ export async function doctor(opts) {
     if (hasSystem && measurable) {
         console.log("");
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${paint.strong(`${String(d.coverage).padStart(3)}%`)}`));
-        console.log(body(paint.dim(`                ${d.tokenUses} from ${systemName}${d.ownUses > 0 ? `, ${d.ownUses} from your own tokens` : ""}, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
+        console.log(body(paint.dim(
+        /**
+         * DE QUEM É O VOCABULÁRIO, dito na própria linha.
+         *
+         * `systemName` cai em "this system" quando não há um instalado - e aí a tabela é a DELA,
+         * lida das folhas dela. "8 from this system" lê como se existisse um sistema nosso no
+         * projeto, e não existe: são os tokens que ela mesma declarou, usados no código dela.
+         */
+        `                ${d.tokenUses} ${table.source === "installed" ? `from ${systemName}` : "through your own tokens"}${d.ownUses > 0 ? `, ${d.ownUses} from your own tokens` : ""}, ${d.findings.length} by hand${d.phantomUses > 0 ? `, ${d.phantomUses} naming nothing` : ""}`)));
         /**
          * A CAMADA DE TOKEN DELE, CONTADA - e a decisão é do dono, em 13/08.
          *
@@ -911,7 +946,22 @@ export async function doctor(opts) {
          * `--ds-*` também segura. Apontar uma para a outra é uma linha por variável, num arquivo só - e
          * os 122 usos seguem o sistema sem tocar em um componente sequer.
          */
-        if (d.ownTokens > 0) {
+        /**
+         * E ESTE BLOCO SÓ EXISTE CONTRA UM SISTEMA NOSSO - ele estava se comparando consigo mesmo.
+         *
+         * `mirrored` marca um token dela quando a tabela segura aquele valor. Quando a tabela É a
+         * dela, ela foi construída a partir daquelas mesmas declarações, então TODO token dela sai
+         * espelhado por construção - 4 de 4 no projeto que caminhei em 18/08. E a linha seguinte
+         * mandava apontá-los para `--ds-*` num projeto que não tem um único `--ds-*`: um conselho
+         * impossível de seguir, no primeiro relatório que ela lê.
+         *
+         * O `used 0x` era falso pelo mesmo motivo: os usos dos tokens dela foram contados na linha
+         * de cima, porque contra a tabela dela eles SÃO o vocabulário conhecido.
+         *
+         * Quando não há sistema nosso, "os seus tokens" e "o sistema" são a mesma coisa, e não há
+         * nada a apontar - a linha de cima já disse tudo o que é verdade.
+         */
+        if (d.ownTokens > 0 && table.source === "installed") {
             console.log(body(paint.dim(`                ${d.ownTokens} token${d.ownTokens === 1 ? "" : "s"} of your own, used ${d.ownUses}x${d.ownMirrored > 0 ? ` - ${d.ownMirrored} hold a value ${systemName} also names` : ""}`)));
             if (d.ownMirrored > 0)
                 console.log(body(paint.dim(`                point those at the \`--ds-*\` that holds it: ${d.ownMirrored} lines, one file`)));
@@ -1671,16 +1721,31 @@ export async function doctor(opts) {
          */
         if (table.source === "yours") {
             console.log("");
-            // Careful about what is being offered. This reader ALREADY has a design
-            // system, so "install ours" would mean replacing theirs, and a CTA that
-            // pretends otherwise is the kind of confident overclaim that costs
-            // trust the first time somebody follows it. What they are missing is
-            // not tokens - it is a contract their agent reads before writing UI.
+            /**
+             * E O COMANDO OFERECIDO É O QUE FAZ O SISTEMA DELA.
+             *
+             * O comentário que estava aqui já dizia a coisa certa - *"este leitor JÁ TEM um design
+             * system, então 'instale o nosso' significaria substituir o dele, e um CTA que finge o
+             * contrário é o tipo de exagero confiante que custa confiança"* - e a linha logo abaixo
+             * oferecia `init --ds <slug>` mais a galeria, que é literalmente instalar o de outra
+             * pessoa. O diagnóstico estava escrito e o conserto não (medido em 18/08).
+             *
+             * O comando que serve a ela existe e é outro: `import` lê o repositório DELA e devolve
+             * um sistema com o vocabulário dela dentro. Caminhado num projeto em branco: quatro
+             * tokens próprios e um componente saíram como "1 of 1 components came out with a
+             * blueprint - 100%".
+             *
+             * A galeria continua dita, uma linha abaixo e em voz baixa: forkar um sistema pronto é
+             * uma escolha legítima, só não é a primeira coisa a oferecer a quem já tem o dela.
+             */
             console.log(body("Your tokens exist. What your agent is missing is a contract:"));
             console.log(body("rules it reads BEFORE writing UI, and a manifest of what exists."));
             console.log("");
-            console.log(paint.blue(snippet(["npx synthesisui@latest init --ds <slug>"])));
-            console.log(body(paint.dim("starts you on a system that ships one - browse them at")));
+            console.log(paint.blue(snippet(["npx synthesisui@latest import --dry"])));
+            console.log(body(paint.dim("reads THIS repo and turns your own vocabulary into that contract -")));
+            console.log(body(paint.dim("local, free, and it writes nothing but the measurement.")));
+            console.log("");
+            console.log(body(paint.dim("Or start from a system somebody already published, if you would rather:")));
             console.log(body(paint.blue("https://www.synthesisui.com/gallery")));
         }
         console.log("");

package/dist/commands/import.js

@@ -1586,7 +1586,7 @@ export async function takeCensus(root, opts) {
         islandRead: islandClassesRead,
         refused: new Set(skips.map((s) => s.file)),
     }));
-    const coverageLines = describeCoverage(coverage, composition);
+    const coverageLines = describeCoverage(coverage, composition, skips.length);
     if (coverageLines.length > 0) {
         say("");
         say(section("What this version reads, on your files"));

package/dist/commands/mcp.js

@@ -1147,6 +1147,45 @@ const BY_COMPONENT = {
     describe_component: "describe",
     add_component: "add",
 };
+/**
+ * QUAL ARGUMENTO CARREGA O ASSUNTO DE CADA CHAMADA - e sem isto a medição não responde nada.
+ *
+ * Medido em 18/08: 2 das 15 ferramentas gravavam O QUE foi pedido; as outras 13 gravavam o
+ * próprio nome. `compose_context` estava entre as 13 - e ela é a ÚNICA que emite `composed`,
+ * que é o sinal inteiro de "aqui faltou uma receita". O banco acumulava "compose_context: 47"
+ * e nunca "a família `field`: 12", e é o segundo número que abre uma candidata a receita.
+ *
+ * Esperar volume não consertaria isso: o dado que estava sendo guardado não responde a
+ * pergunta, então o relógio da espera não estava correndo.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O QUE ENTRA, E O QUE NÃO ENTRA DE PROPÓSITO
+ *
+ * Entra o que é um NOME - do vocabulário dela ou do nosso. Ficam de fora, e não por
+ * esquecimento:
+ *
+ *     find_token   `value`  é um valor do repositório dele (`#4f46e5`)
+ *     check_file   `path`   é um caminho do repositório dele
+ *     playbook     `section` é navegação nossa, e não diz nada sobre o sistema dele
+ *
+ * Os dois primeiros são dado DELE, e a nossa tabela de contadores não é lugar para eles. O
+ * `SLUG` do outro lado já os rejeitaria em silêncio; não mandar é dizer a mesma coisa em voz
+ * alta. `list_components`, `system_doctrine`, `recipe_vocabulary` e `refresh_system` não têm
+ * assunto nenhum - a pergunta É o sistema inteiro.
+ *
+ * `validate_recipes` no plural é um LOTE, e um lote não tem um assunto só.
+ */
+const SUBJECT_ARG = {
+    describe_component: "name",
+    add_component: "name",
+    /** A família pedida - o sinal que o A1 precisa e que não estava sendo guardado. */
+    compose_context: "family",
+    /** O que ela pediu e o sistema não tinha: a lacuna, com nome. */
+    request_component: "name",
+    request_rule: "name",
+    request_token: "name",
+    validate_recipe: "name",
+};
 /**
  * O ÚNICO PONTO DE INSTRUMENTAÇÃO - e é isto que o dono pediu (18/08): *"vira
  * comportamento padrão e não depende de disciplina futura."*
@@ -1163,8 +1202,9 @@ async function callTool(root, name, args,
 cli) {
     const answer = await runTool(root, name, args);
     const gesture = BY_COMPONENT[name];
-    const target = gesture
-        ? String(args.name ?? "")
+    const subject = SUBJECT_ARG[name];
+    const target = subject
+        ? String(args[subject] ?? "")
             .trim()
             .toLowerCase()
         : "";

package/dist/commands/status.js

@@ -52,7 +52,21 @@ export async function status(opts) {
     }
     console.log(section("Status"));
     if (installed.length === 0) {
+        /**
+         * NADA INSTALADO NÃO SIGNIFICA NADA A OFERECER, e mandar `list` era o conselho da outra pessoa.
+         *
+         * `list` mostra a GALERIA - sistemas que outros publicaram. Quem roda isto num repositório que
+         * já tem o próprio vocabulário recebia "escolha o de alguém", quando o comando que serve a ela
+         * lê o repositório DELA. O `doctor` cometia o mesmo desvio no parágrafo final, e ali o
+         * comentário até diagnosticava (medido em 18/08).
+         *
+         * As duas continuam ditas, na ordem certa: o dela primeiro, o de outra pessoa como alternativa.
+         */
         console.log(body("No design system installed in this project, so there is nothing to be in sync with."));
+        console.log("");
+        console.log(body("Make one out of this repo:"));
+        console.log(paint.blue(snippet(["npx synthesisui@latest import --dry"])));
+        console.log(body("Or bring in one somebody published:"));
         console.log(paint.blue(snippet(["npx synthesisui@latest list"])));
         return;
     }

package/dist/doctor/component-gate.js

@@ -304,6 +304,13 @@ export function groupSkips(skips) {
  *
  * The sentence a person needs in order to trust a number that just dropped by an
  * order of magnitude - and to notice if it dropped too far.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * E ELA VIAJA COLADA À MANCHETE (dono, 18/08).
+ *
+ * "340 de 340 com blueprint - 100%" sozinho é autoelogio: um portão que admite
+ * pouco fecha 100% fácil. As duas linhas juntas são uma promessa que se pode
+ * conferir - o que entrou, e o que ficou de fora com o motivo de cada um.
  */
 export function describeGate(kept, skipped) {
     if (skipped === 0) {

package/dist/doctor/coverage.js

@@ -110,7 +110,7 @@ export function summarizeCoverage(counts, components, read, declarations) {
 /**
  * The report, in the words a person needs before they decide whether to import.
  *
- * Leads with the number that matters - how many components came out with a look - and
+ * Leads with the number that matters - how many components came out with a blueprint - and
  * then names every shape that is not fully read, with the reason. No percentages without
  * the count behind them: "75%" of an unknown total is a marketing number.
  */
@@ -123,12 +123,41 @@ export function describeCoverage(c,
  * arranjo e fluxo, e é isso que a receita deles carrega. Medido no dashboard dele: 235 de
  * 271 (04/08).
  */
-composition) {
+composition, 
+/**
+ * O QUE O PORTÃO DEIXOU DE FORA - e ele viaja COLADO à manchete (dono, 18/08).
+ *
+ * A explicação longa e a lista nominal continuam onde sempre estiveram, 79
+ * linhas abaixo. O que sobe para cá é só o número, porque é ele que impede a
+ * manchete de ser autoelogio: um portão que admite pouco fecha 100% fácil, e
+ * as duas contas juntas são uma promessa que se pode conferir.
+ */
+leftOut) {
     if (c.components === 0)
         return [];
     const lines = [];
     const pct = Math.round((c.read / c.components) * 100);
-    lines.push(`${c.read} of ${c.components} components came out with a look - ${pct}%, ${c.declarations} declarations in total. This is measured on your files, not an estimate.`);
+    /**
+     * A MANCHETE É BLUEPRINT POR COMPONENTE, e não fragmento de estilo (dono, 18/08).
+     *
+     * As duas contas existiam, e a que liderava era a errada. "62% dos fragmentos
+     * interpretados" mistura no mesmo denominador coisas que NÃO PODEM ser lidas
+     * por natureza - medido no repo real: 120 fragmentos são `computed`, o valor
+     * nasce no navegador e não está no código em nível nenhum; 4 são partials que
+     * o build dele nem compila. Perseguir 100% ali é perseguir um número que
+     * obriga a mentir.
+     *
+     * A conta que pode fechar em 100%, e que é o objetivo do recurso, é esta:
+     * dos componentes ADMITIDOS, quantos saíram com blueprint. Medido no
+     * `frontend-hub`: 340 de 340.
+     *
+     * `blueprint` é o nome público do que a plataforma produz; `recipe` continua
+     * sendo o nome interno, no documento e no código.
+     */
+    lines.push(`${c.read} of ${c.components} components came out with a blueprint - ${pct}%, ${c.declarations} declarations in total. This is measured on your files, not an estimate.`);
+    if (leftOut && leftOut > 0) {
+        lines.push(`  and ${leftOut} export${leftOut === 1 ? "" : "s"} did not become one - each is named below with the reason, so a 100% here never means "we admitted little".`);
+    }
     if (composition && composition > 0) {
         lines.push(
         /**

package/dist/doctor/their-names.js

@@ -1,4 +1,4 @@
-import { FAMILY_PREFIX, familySays, normalizeValue, } from "./tokens.js";
+import { FAMILY_PREFIX, familySays, formDecides, normalizeValue, UNAMBIGUOUS, } from "./tokens.js";
 /**
  * COMO ELE CHAMA O VALOR - para a gente parar de renomear as variáveis dele.
  *
@@ -47,14 +47,6 @@ import { FAMILY_PREFIX, familySays, normalizeValue, } from "./tokens.js";
  * 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.
@@ -142,8 +134,7 @@ export function theirNames(ours, theirs) {
              * 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
+            const usable = formDecides(value)
                 ? candidates
                 : candidates.filter((n) => familySays(kind, n));
             if (usable.length === 0)

package/dist/doctor/tokens.js

@@ -569,6 +569,27 @@ export const FAMILY_WORDS = {
  * `--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.
  */
+/**
+ * OS VALORES CUJA FORMA JÁ DIZ A FAMÍLIA - e por isso o nome não precisa dizer.
+ *
+ * Morava em `their-names.ts`, privada, e a falta dela aqui foi medida no corpus: filtrar por
+ * palavra sem esta porta trocou `--brand-500` por `--loader-color` num hex. Os dois são cor, e
+ * o segundo só ganhou por ter a palavra "color" no nome - a doc de `FAMILY_WORDS` já avisava
+ * que 748 dos 755 nomes sem palavra de categoria são cor.
+ *
+ * O que fica de fora é o COMPRIMENTO, e fica de propósito: `24px` pode ser raio, espaçamento ou
+ * tamanho de fonte, e ali o nome é a única pista que existe.
+ */
+export 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)$/,
+};
+/** A forma deste valor já decide a família dele, então a palavra no nome não precisa. */
+export const formDecides = (value) => Object.values(UNAMBIGUOUS).some((f) => f.test(value));
 export const familySays = (kind, name) => {
     const words = FAMILY_WORDS[kind] ?? [];
     const segments = name.replace(/^--/, "").toLowerCase().split("-");
@@ -596,8 +617,33 @@ export function tokenMatch(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal, table.rootPx));
     if (!hit || hit.length === 0)
         return null;
+    /**
+     * O PREFIXO É NOSSO; O NOME PODE SER DELA - e olhar só o prefixo reprovava todo o vocabulário
+     * dela como coincidência entre famílias (medido em 18/08, no caminho de quem começa do zero).
+     *
+     * `--ds-radius-md` carrega a família por construção, e é isso que o prefixo lê. `--radius-card`
+     * não carrega prefixo nenhum, então nenhum token dela casava e TODO achado saía marcado como
+     * erro de categoria - com a frase se contradizendo na mesma linha: "no radius named for it ·
+     * the value lives as --radius-card". O `--fix` então deixava de trocar exatamente os valores
+     * que ela acabou de nomear.
+     *
+     * `familySays` é a resposta e ela já existia para o outro lado da mesma pergunta (`their-names`,
+     * `absorb-plan`): a família sai de QUALQUER segmento do nome, então o namespace de produto dela
+     * não atrapalha. Os dois caminhos somam - a garantia por construção continua valendo primeiro.
+     */
     const prefix = kind ? FAMILY_PREFIX[kind] : undefined;
-    const family = prefix ? hit.filter((n) => n.startsWith(prefix)) : [];
+    /**
+     * E A PALAVRA SÓ DECIDE QUANDO A FORMA NÃO DECIDE - a mesma porta que `their-names` usa.
+     *
+     * Sem ela, filtrar por palavra num hex escolhia `--loader-color` em vez de `--brand-500`
+     * (medido no corpus dourado): os dois são cor, e o segundo perdia por não ter a palavra
+     * "color" no nome. Num comprimento cru é o contrário - ali a palavra é a única pista.
+     */
+    const byWord = kind && !formDecides(normalizeValue(literal, table.rootPx));
+    const family = kind
+        ? hit.filter((n) => (prefix ? n.startsWith(prefix) : false) ||
+            (byWord ? familySays(kind, n) : false))
+        : [];
     const pool = family.length > 0 ? family : hit;
     // Semantic roles name intent; primitives name a shelf. Prefer intent.
     const semantic = pool.find((n) => n.includes("-semantic-"));

package/dist/install-marks.js

@@ -159,7 +159,7 @@ export const MATERIALISER_SINCE = "0.16.241";
  * `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";
+export const CHECKER_SINCE = "0.16.250";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.248",
+  "version": "0.16.250",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {