synthesisui 0.16.421 → 0.16.422

package/dist/doctor/scan.js

@@ -12,14 +12,40 @@
 import { utilitiesOn } from "./idiom-names.js";
 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.
+ * O NOME QUE SE ESCREVE NO ARQUIVO DELE - e ele é SEMPRE do vocabulário dele (`INV-GERAL-13`).
  *
  * 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.
+ *
+ * O NOSSO NOME SAIU DAQUI EM 11/09, e ele era a metade que contrariava a decisão de 07/09.
+ *
+ * A regra é literal: *"tem nome no sistema DELE? SIM -> a nossa receita usa o nome dele. NÃO ->
+ * mantém HARDCODED, e a plataforma só AVISA"*. Esta função devolvia `theirToken ?? token`, e o
+ * `token` é o nome COMPILADO do sistema - a grafia `--ds-*`, que é invenção nossa. Então o comando
+ * que promete adotar o sistema trocava um literal que funciona por uma variável que só resolve com
+ * uma folha nossa carregada no app dele.
+ *
+ * MEDIDO no `codelevel` em 04/09, sobre as 216 trocas com nome esperando: **60 (28%) escreviam a
+ * nossa grafia**. Eram exatamente as que exigiam o `@import` - e para protegê-las o comando recusava
+ * as outras 156 por inteiro, cobrando a folha em troca.
+ *
+ * O valor que só o nosso lado nomeia não desaparece do relatório: ele vira AVISO, com o valor e a
+ * linha, e a decisão de batizá-lo continua sendo dele. Ver `ourNameOnly`.
  */
-export const nameToWrite = (f) => f.theirToken ?? f.token;
+export const nameToWrite = (f) => f.theirToken ?? (f.tokenIsTheirs ? f.token : null);
+/**
+ * O VALOR QUE **SÓ** O NOSSO LADO NOMEIA - o que a plataforma AVISA em vez de escrever.
+ *
+ * É a outra metade de `nameToWrite`, e ela existe para o silêncio não acontecer: um achado sem nome
+ * dele e com nome nosso some das duas listas se ninguém perguntar por ele, e sumir é
+ * indistinguível de "está tudo nomeado" para quem lê (lei 8).
+ *
+ * Quem chama DIZ o valor e onde ele está - nunca propõe o nome. É a escolha dele de 10/09 entre as
+ * duas alternativas, e a mesma que o hook já segue.
+ */
+export const ourNameOnly = (f) => !f.theirToken && !f.tokenIsTheirs && Boolean(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.
@@ -607,6 +633,8 @@ function scanCore(file, source, table) {
              * `--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)}`);
+            /** A procedência do `token`, lida da tabela que o achou - ver `tokenIsTheirs`. */
+            const tableIsTheirs = table.source !== null && table.source !== "installed";
             findings.push({
                 kind,
                 line: at,
@@ -617,6 +645,9 @@ function scanCore(file, source, table) {
                     ? { fontRelative: true }
                     : {}),
                 ...(theirs?.writable ? { theirToken: theirs.name } : {}),
+                ...(tableIsTheirs && match?.token
+                    ? { tokenIsTheirs: true }
+                    : {}),
                 /**
                  * O NOME QUE SÓ SE DIZ - `$gray_dark` do Sass, `@brand` do Less.
                  *

package/dist/doctor/their-names.js

@@ -196,8 +196,14 @@ export function theirNames(ours, theirs) {
              * 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.
+             * E DESDE 11/09 RECUSAR AQUI SIGNIFICA SILÊNCIO, não um nome nosso no lugar.
+             *
+             * Esta linha dizia que recusar não perdia informação, *"porque sem alias `nameToWrite` cai no
+             * NOSSO token"*. Ele não cai mais: a nossa grafia deixou de ser escrita no código dele
+             * (`INV-GERAL-13`), então um valor cuja categoria não fecha sai da lista de trocas em vez de
+             * sair com o nosso nome. Isso é o desfecho certo - a troca errada era escrever um token de
+             * tipo num `border-radius` -, e o valor não desaparece: ele é DITO, com o valor e a linha,
+             * pelo caminho que `ourNameOnly` alimenta.
              */
             const usable = formDecides(value)
                 ? candidates

package/dist/fonts.js

@@ -89,7 +89,7 @@ export function googleFontsHref(families) {
  */
 export const FAMILY_SEAM_PREFIX = "--ds-typography-families-";
 export function nextFontSnippet(input) {
-    const { families, slug, appDir = "app", seam, facts, declaredWeights, } = input;
+    const { families, appDir = "app", facts, declaredWeights } = input;
     /**
      * A ORDEM É DETERMINÍSTICA e os duplicados saem: isto vira uma linha de arquivo gerado, e um
      * conjunto que muda de ordem entre rodadas produz diff onde nada mudou.
@@ -219,15 +219,39 @@ export function nextFontSnippet(input) {
      * projeto dele deixaria de compilar por causa da linha que a gente mandou colar.
      */
     const emitted = roles.filter((role) => constOf(role) !== undefined);
+    /**
+     * O `data-ds` SAIU DO LAYOUT DELE EM 11/09 - `INV-GERAL-13`.
+     *
+     * O atributo existia para a NOSSA folha aplicar dentro dele, e nenhum app dele carrega a nossa
+     * folha. O que resta na linha é o que o `next/font` exige e é dele: a classe que carrega a
+     * variável de cada fonte.
+     */
     const layout = [
         `// ${appDir}/layout.tsx`,
         `import { ${[...new Set(emitted.map(constOf))].join(", ")} } from "./fonts";`,
-        `<body data-ds="${slug}" className={\`${[...new Set(emitted.map((r) => `\${${constOf(r)}.variable}`))].join(" ")}\`}>`,
+        `<body className={\`${[...new Set(emitted.map((r) => `\${${constOf(r)}.variable}`))].join(" ")}\`}>`,
     ];
+    /**
+     * O BLOCO DE CSS PASSA A ESCREVER NO VOCABULÁRIO **DELE** - o conserto de 11/09.
+     *
+     * O QUE ELE ESCREVIA: um `[data-ds="<slug>"]` com `--ds-typography-families-<role>` apontando para
+     * a fonte. Nosso escopo, nossa variável, dentro da folha dele - e só resolvia com a nossa folha
+     * carregada, que é o que `INV-GERAL-13` proíbe.
+     *
+     * O QUE ELE ESCREVE AGORA: um `@theme` com `--font-<role>`, que é o namespace de fonte do Tailwind
+     * DELE. Duas coisas acontecem de uma vez, e as duas são dele: a utility `font-<role>` passa a
+     * existir no projeto dele carregando a fonte que o `next/font` baixou, e `theirThemeVars` -
+     * o leitor que decide o utilitário nomeado no codegen - passa a ver aquele nome. Daí em diante o
+     * componente que a plataforma escreve veste `font-<role>` em vez de um literal, porque o `@theme`
+     * DELE declara o nome.
+     *
+     * Nenhuma linha aqui menciona o sistema, o slug ou uma variável nossa: é a fonte dele, ligada ao
+     * Tailwind dele.
+     */
     const css = [
-        `/* ${appDir}/globals.css - AFTER the tokens.css import */`,
-        `[data-ds="${slug}"] {`,
-        ...emitted.map((role) => `  ${seam?.[role] ?? `${FAMILY_SEAM_PREFIX}${role}`}: var(${roleVar(role)});`),
+        `/* ${appDir}/globals.css - in your own @theme */`,
+        `@theme {`,
+        ...emitted.map((role) => `  --font-${role}: var(${roleVar(role)});`),
         `}`,
     ];
     /**

package/dist/global-sheet.js

@@ -1,134 +1,23 @@
-import { readdir, readFile } from "node:fs/promises";
-import { dirname, join, posix, relative, resolve } from "node:path";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
 import { exists } from "./agent-wiring.js";
 /**
- * A FOLHA GLOBAL QUE OS APPS DELE REALMENTE CARREGAM - e num monorepo ela quase nunca é a do app.
+ * AS PASTAS DE APP DESTE REPOSITÓRIO - e era um módulo sobre a folha global dele até 11/09.
  *
- * O QUE O CLIENTE PERCEBE SEM ISTO. O `add` manda importar os tokens em `apps/<x>/app/globals.css`.
- * MEDIDO em 01/09 no `codelevel`: os DOIS apps dele fazem `@import "@repo/ui/styles/globals.css"`, e
- * o `globals.css` do app diz, em comentário dele, *"Do not redeclare tokens or fonts here - extend in
- * styles/"*. A instrução apontava para o arquivo errado, e a convenção certa estava escrita ali do
- * lado.
+ * O QUE MORAVA AQUI: `globalSheetOf`, `sheetChainOf`, `prefixFrom` e o resolvedor de `exports` do
+ * workspace. Os quatro existiam para uma coisa - achar a folha que os apps dele realmente carregam,
+ * e contar o `../` até a raiz, para a instrução de `@import` apontar para o arquivo certo.
  *
- * Ele seguiu a instrução no arquivo CERTO - o do pacote - e o caminho relativo que a gente imprimiu
- * era o do app. Um monorepo com pacote de UI compartilhado não é exceção: é a forma comum, e a
- * instrução tem que derivar de onde o CSS dele mora em vez de assumir.
+ * Era a parte mais cuidadosa daquele texto. MEDIDO em 01/09 no `codelevel`: os dois apps dele fazem
+ * `@import "@repo/ui/styles/globals.css"`, e o `globals.css` do app diz, em comentário DELE, *"Do
+ * not redeclare tokens or fonts here"*. A instrução apontava para o arquivo errado, com o caminho
+ * relativo de outro, e o conserto foi seguir a cadeia em vez de assumir.
  *
- * ─────────────────────────────────────────────────────────────────────────
- * COMO A FOLHA REAL É ENCONTRADA, e nada aqui é palpite:
- *
- *     1. abre o `globals.css` do app
- *     2. procura `@import "<spec>"` que aponte para um CSS DENTRO deste repositório
- *     3. resolve o `<spec>`: caminho relativo, ou pacote do workspace pelo `exports`
- *     4. repete na folha encontrada, até ela não re-exportar mais
- *
- * O QUE NÃO É SEGUIDO: `tailwindcss` e qualquer coisa que não resolva para um arquivo daqui. Um
- * `@import "tailwindcss"` é a biblioteca, e mandar o cliente editá-la seria pior que a instrução que
- * isto conserta.
+ * O TEXTO INTEIRO DEIXOU DE EXISTIR (`INV-GERAL-13`): nada que a plataforma escreve no repositório
+ * dele depende de folha nossa, então não há `@import` para apontar. O que sobrevive é a única
+ * pergunta que não era sobre a nossa folha - *"quais pastas deste repositório são app?"* -, porque é
+ * onde o `fonts.ts` do `next/font` DELE entra, um por app.
  */
-/** Quantos saltos seguir antes de desistir - um ciclo de imports não pode travar um `add`. */
-const MAX_HOPS = 5;
-const IMPORT = /@import\s+["']([^"']+)["']/g;
-/** `@repo/ui/styles/globals.css` → `packages/ui/src/styles/globals.css`, pelo `exports` dele. */
-async function fromWorkspace(root, spec) {
-    for (const group of ["packages", "apps", "libs"]) {
-        let entries;
-        try {
-            const { readdir } = await import("node:fs/promises");
-            entries = await readdir(join(root, group));
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            const pkgPath = join(root, group, entry, "package.json");
-            const raw = await readFile(pkgPath, "utf8").catch(() => null);
-            if (!raw)
-                continue;
-            let pkg;
-            try {
-                pkg = JSON.parse(raw);
-            }
-            catch {
-                continue;
-            }
-            if (!pkg.name || !spec.startsWith(`${pkg.name}/`))
-                continue;
-            const sub = `./${spec.slice(pkg.name.length + 1)}`;
-            const target = pkg.exports?.[sub];
-            if (typeof target !== "string")
-                continue;
-            return posix.join(group, entry, target.replace(/^\.\//, ""));
-        }
-    }
-    return null;
-}
-/**
- * A folha onde os tokens dele devem entrar, relativa à raiz - `appSheet` quando nada a re-exporta.
- *
- * DELEGA, e não caminha: quem caminha é `sheetChainOf`. Dois caminhadores sobre a mesma cadeia é
- * como um deles para de seguir um salto que o outro segue, e ninguém descobre até um cliente
- * receber a instrução apontando para a folha errada - que é exatamente o defeito que
- * `INV-VOLTA-12` fechou.
- */
-export async function globalSheetOf(root, appSheet) {
-    const chain = await sheetChainOf(root, appSheet);
-    return chain[chain.length - 1] ?? appSheet;
-}
-/**
- * A CADEIA INTEIRA, da folha do app até a última que ninguém re-exporta - e por que ela é pública.
- *
- * O QUE O CLIENTE GANHA: a resposta "este app carrega o meu design system?" medida no app DELE, e
- * não no projeto. `readWiring` varria a raiz e devolvia "existe em algum lugar daqui": num monorepo
- * com dois apps servidos, um fiado e outro não, o fiado respondia pelo outro - e a pessoa recebia
- * "está tudo certo" sobre o app que não carrega nada.
- *
- * A pergunta dos IMPORTS não se responde varrendo pasta: ela se responde seguindo a cadeia de
- * `@import` a partir da folha daquele app, porque a folha que carrega os tokens quase nunca é a do
- * app - num monorepo é a do pacote compartilhado, e os dois apps chegam nela.
- *
- * A ordem é do app para fora, e o teto de saltos é o mesmo: um ciclo de imports não pode travar um
- * comando.
- */
-export async function sheetChainOf(root, appSheet) {
-    const chain = [];
-    let current = appSheet;
-    for (let hop = 0; hop < MAX_HOPS; hop += 1) {
-        chain.push(current);
-        const raw = await readFile(join(root, current), "utf8").catch(() => null);
-        if (!raw)
-            return chain;
-        let next = null;
-        for (const m of raw.matchAll(IMPORT)) {
-            const spec = m[1];
-            if (!spec.endsWith(".css"))
-                continue;
-            const candidate = spec.startsWith(".")
-                ? posix.normalize(posix.join(posix.dirname(current), spec))
-                : await fromWorkspace(root, spec);
-            if (!candidate)
-                continue;
-            /** Fora da raiz não é folha dele para editar - e um `..` demais sai do repositório. */
-            if (candidate.startsWith(".."))
-                continue;
-            const readable = await readFile(join(root, candidate), "utf8").catch(() => null);
-            if (readable === null)
-                continue;
-            next = candidate;
-            break;
-        }
-        /** Uma folha que aponta para si mesma encerra a cadeia em vez de gastar o teto de saltos. */
-        if (!next || next === current || chain.includes(next))
-            return chain;
-        current = next;
-    }
-    return chain;
-}
-/** O `../` que leva daquela folha até a raiz do repositório - o prefixo do `@import`. */
-export function prefixFrom(sheet) {
-    const up = relative(dirname(resolve("/r", sheet)), "/r");
-    return up === "" ? "./" : `${up.split(/[\\/]/).join("/")}/`;
-}
 /**
  * A RAIZ DE CADA APP DESTE REPOSITÓRIO - onde o escopo e a tipografia entram, um por app.
  *

package/dist/guide.js

@@ -293,8 +293,49 @@ toolsReachable = false,
  * essa porta; deixá-la entreaberta um nível acima seria vigiá-la em vez de fechá-la
  * (CLAUDE.md, Parte I, seção 6).
  */
-fontFacts) {
+fontFacts, 
+/**
+ * O VOCABULÁRIO DESTE REPOSITÓRIO - `tongueFromArtifacts`, ou `null` quando não há folha para ler.
+ *
+ * O QUE ISTO CONSERTA, e é a razão de existir desta etapa: este arquivo é o que o agente DELE lê
+ * antes de escrever, e ele ensinava a nossa grafia. *"Color: `var(--ds-color-semantic-<role>)`"*
+ * é uma instrução para escrever a NOSSA variável no código dele - e ela só resolve com a nossa
+ * folha carregada, que é o que `INV-GERAL-13` proíbe. Um guia que ensina isso produz a violação
+ * sem que ninguém decida nada: o agente obedece.
+ *
+ * Com o vocabulário em mão, cada linha abaixo diz o nome que o código DELE dá àquele valor - ou o
+ * valor, quando o código dele não nomeia nenhum.
+ *
+ * OBRIGATÓRIO, pelo mesmo argumento de `fontFacts` logo acima: um argumento opcional aqui é um
+ * argumento que um chamador novo esquece, e o esquecimento devolve a nossa grafia ao arquivo que
+ * mais a propaga.
+ */
+tongue) {
     const { document: doc, slug, name, version } = payload;
+    /**
+     * COMO ISTO SE ESCREVE NO CÓDIGO DELE - a mesma resposta que a materialização usa.
+     *
+     * `var(--nome-dele)` quando o repositório dele nomeia aquele valor; o valor literal quando não.
+     * Sem vocabulário (projeto que nunca buildou, folha ausente) a resposta é `null`, e quem chama
+     * DIZ isso em vez de imprimir uma grafia que ninguém pode escrever.
+     */
+    const saysAs = (ours) => {
+        if (!tongue)
+            return null;
+        const theirs = tongue.names.get(ours);
+        if (theirs)
+            return `var(${theirs})`;
+        return tongue.values.get(ours) ?? null;
+    };
+    /** `spacing` -> `md → var(--gap-md)`, para cada degrau que o vocabulário alcança. */
+    const family = (prefix, keys) => {
+        const said = keys
+            .map((k) => ({ k, as: saysAs(`--ds-${prefix}-${kebab(k)}`) }))
+            .filter((x) => x.as !== null);
+        return said.length > 0
+            ? said.map((x) => `\`${x.k}\` → \`${x.as}\``).join(", ")
+            : list(keys);
+    };
     const { meta, foundations, motion, components } = doc;
     const semanticRoles = Object.keys(foundations.color.semantic);
     /**
@@ -339,8 +380,6 @@ fontFacts) {
      */
     const fontPlan = nextFontSnippet({
         families: foundations.typography.families,
-        slug,
-        seam: payload.fontSeam,
         facts: fontFacts,
         /** Os pesos que ELE declara - ver `declaredWeights`. O guia é o arquivo que o agente dele cola. */
         declaredWeights: foundations.typography.weights,
@@ -548,7 +587,10 @@ It writes a **deterministic scaffold**: the page uses this DS's \`.ds-*\` recipe
 path-classes, paired with a co-located scoped CSS (Next target) that carries the **responsive** media
 queries and the **CSS-only hamburger** - so the page is mobile-ready out of the box. **Refine it in
 place** - wire real data, split into components, swap the chart/icon/media placeholders - but keep the
-\`data-ds="${slug}"\` wrapper and the \`.ds-*\` / layout classes so it stays on-system. Run
+wrapper and the \`.ds-*\` / layout classes: the stylesheet next to the page carries the rules for the
+ones it wears, scoped to that wrapper - the command says how many came along, so the page stands on
+its own with nothing imported. A \`.ds-*\` you ADD while refining has no rule there; bring that piece
+in with \`synthesisui component\` instead. Run
 \`synthesisui init\` once to set the target (next/general) and the output folder.
 
 ## Single components as YOUR code
@@ -560,8 +602,8 @@ synthesisui component ${slug} button
 It writes \`<componentsDir>/button/\` with \`button.tsx\` (+ colocated \`button.css\` in the default
 \`styles: "css"\` flavor, or Tailwind utilities inline with \`styles: "tailwind"\` - set once via
 \`synthesisui init --styles tailwind\`). Import and render: \`import { Button } from "components/button"\`.
-The boundary: tokens are global (\`tokens.css\` + the \`data-ds\` root attribute, once per app);
-everything a component owns lives in its own folder.
+The boundary: everything a component owns lives in its own folder, and every value in it is a name
+YOUR code declares or the value itself - there is nothing global to set up.
 
 **A component's conditional classes are decided at the call site, not in the stylesheet.** A recipe
 carries the look of a state as a rule keyed on a data attribute (\`[data-size="lg"]\`), and the caller
@@ -623,80 +665,73 @@ ${meta.narrative}
 ${rulesNote}
 ## How to apply
 
-1. Import the system once in your project's global CSS, using a path **relative to that CSS
-   file** - from \`app/globals.css\` in a Next App Router project that means a leading \`../\`:
-   \`\`\`css
-   @import "../_synthesisui/ds/${slug}/tokens.css";
-   \`\`\`
-   (drop the \`../\` if your global CSS sits at the project root.)${hasTailwind
-        ? `\n   **Using Tailwind (this project's default)? You also need \`theme.css\` right after \`tokens.css\` -\n   without it the DS-backed utilities (\`bg-primary\`, \`p-md\`…) aren't generated and the UI renders\n   unstyled. See "Styling with Tailwind v4" below for the full import block.**`
-        : ""}
+**Nothing here is imported into your app.** \`_synthesisui/ds/${slug}/\` is the reference this guide,
+the check, the doctor and the MCP server read to interpret your design - your code never points at
+it, and nothing we write into this repository needs it at runtime.
 
-2. Wrap the tree that should use the system with the scope attribute:
-   \`\`\`html
-   <div data-ds="${slug}">…your UI here…</div>
-   \`\`\`
-   All \`--ds-*\` custom properties and \`.ds-*\` classes only apply inside that scope.
-   Applying \`data-ds="${slug}"\` at the app root (e.g. \`<body>\` or the root layout)
-   is the simplest choice - the whole app then wears the system.
-${hasAlt
-        ? `
-3. Light/dark: an ancestor with \`data-scheme="${altScheme}"\` switches the neutral roles to the opposite mode.
-   \`\`\`tsx
-   <div data-scheme="${altScheme}"><div data-ds="${slug}">…</div></div>
+1. Ask for a component and it arrives as YOUR code:
    \`\`\`
-   A theme toggle just adds/removes that attribute on the scope element:
-   \`\`\`tsx
-   root.toggleAttribute("data-scheme"); // present = ${altScheme}, absent = ${meta.scheme}
+   npx synthesisui component ${slug} <name>
    \`\`\`
-`
+   It lands in your components directory speaking the names your own code declares - or carrying the
+   value itself, where your code names none. No import, no scope attribute, nothing at runtime.
+
+2. Writing something by hand? Use the vocabulary below. Every name in it is a name **your own code
+   declares**, written exactly as you would write it.
+${hasAlt
+        ? `\n3. Light/dark: this system's roles have two readings, and a component that arrives from
+   \`component\` carries both. Which one shows is your app's own scheme switch - we do not add one.\n`
         : ""}${fontsSection}${depsSection}${hasTailwind
         ? `
 ## Styling with Tailwind v4 (preferred in this project)
 
-Import \`theme.css\` after \`tailwindcss\` and \`tokens.css\`:
-\`\`\`css
-@import "tailwindcss";
-@import "./_synthesisui/ds/${slug}/tokens.css";
-@import "./_synthesisui/ds/${slug}/theme.css";
-\`\`\`
-This maps the DS tokens onto Tailwind's theme, so inside \`[data-ds="${slug}"]\` you get utilities
-backed by the design system: \`bg-*\`/\`text-*\`/\`border-*\` (semantic colors), \`p-*\`/\`m-*\`/\`gap-*\`
-(spacing), \`rounded-*\`, \`shadow-*\`, \`font-*\` (families **and** weights), \`text-*\` (type scale), \`ease-*\`${seriesKeys.length > 0
-            ? `, \`bg-series-*\`/\`text-series-*\`/\`fill-series-*\` (data-viz series)`
-            : ""}.
+Your own \`@theme\` is what backs the utilities, and it is the one that decides. Where it declares a
+name, the utility already paints your value and it is the most readable code you can write; where it
+does not, write the value.
 
-**Prefer these utilities for layout and new composition** - they are this project's idiom and read
-far better than inline \`style\`. Reach for inline \`var(--ds-*)\` only when no utility fits.
+**Prefer utilities for layout and new composition** - they are this project's idiom and read far
+better than inline \`style\`.
 
 \`\`\`tsx
-// ✅ preferred - Tailwind utilities backed by the DS
-<main className="bg-canvas text-foreground p-2xl flex flex-col gap-md">
-  <button className="ds-button" data-intent="primary">Save</button>
+// preferred - your project's own utilities
+<main className="p-2xl flex flex-col gap-md">
+  <button className="rounded-md px-md py-2xs">Save</button>
 </main>
+\`\`\`
+
+To give a utility the system's value, declare the name in **your own** \`@theme\` - it is your
+stylesheet, your namespace, and nothing of ours is involved:
 
-// ❌ avoid - inline styles with raw var() when a utility exists
-<main style={{ background: "var(--ds-color-semantic-canvas)", padding: "var(--ds-spacing-2xl)" }}>
+\`\`\`css
+@theme {
+  --radius-md: <the value you want rounded-md to paint>;
+}
 \`\`\`
 
+Do that and \`synthesisui component\` starts writing \`rounded-md\` instead of the raw value, because
+the name now exists in your project.
+
 ---
 `
         : ""}
-This is **v${version}**. The stable entrypoints at \`_synthesisui/ds/${slug}/\` (the
-\`tokens.css\`/\`theme.css\` re-exports, plus \`.lock\`) always point at the active version - import
-those, not the versioned ones. The pinned files for this version - ${artifactList},
+This is **v${version}**. The pinned files for this version - ${artifactList},
 \`design-system.json\` (canonical source of truth), \`GUIDE.md\` (this file) - live in
-\`_synthesisui/ds/${slug}/v${version}/\`.
+\`_synthesisui/ds/${slug}/v${version}/\`, and they are OURS to read: the check, the doctor and the MCP
+server use them to interpret your design. Your app imports none of them.
 
 ---
 ${pagesSection}
 ## Building with the system
 
 **This system is for building real product UI** - pages, layouts, dashboards, whole flows.
-Compose the \`.ds-*\` recipes (and their parts) together with the DS-backed utilities to assemble
-actual screens. There is **no "samples only" rule**: build the real app. An
-\`app/synthesisui-samples/<component>/\` page is a fine *optional* scratch space to eyeball a single
-component, but it is never required.
+Bring the recipes in as YOUR code (\`npx synthesisui component ${slug} <name>\`) and compose them with
+your own utilities to assemble actual screens. There is **no "samples only" rule**: build the real
+app. An \`app/synthesisui-samples/<component>/\` page is a fine *optional* scratch space to eyeball a
+single component, but it is never required.
+
+The \`.ds-*\` class names below describe the recipe's SHAPE - which parts it has and which
+\`data-*\` each one takes. They are what the materialized component wears, and the stylesheet that
+declares them comes with it.
 
 ### Layout & composition
 The system defines the scale; these are sensible defaults for spending it:
@@ -728,10 +763,9 @@ part classes and their \`data-*\` are listed per component below. Example - a ta
 `
         : ""}
 ### Overlays & portals
-Dialogs, menus and toasts are often rendered through a portal at the end of \`<body>\` - **outside**
-your \`data-ds\` scope. Since \`.ds-*\`/\`--ds-*\` only resolve inside the scope, wrap any portalled UI
-in its own \`<div data-ds="${slug}"${hasAlt ? ` data-scheme="…"` : ""}>\`, or apply \`data-ds\` at the
-app root so everything (portals included) inherits it. Behavior (open/close, focus trap, positioning,
+Dialogs, menus and toasts are often rendered through a portal at the end of \`<body>\` - outside
+the tree they were written in. A component brought in by \`synthesisui component\` carries its own
+stylesheet and works anywhere, portal included. Behavior (open/close, focus trap, positioning,
 keyboard) is yours to wire - the system ships the **looks**, not the JavaScript.
 
 ### Interactive recipes - the behavior contract
@@ -756,34 +790,47 @@ styles it, you make it work.
 ## Rules (follow them when creating components)
 ${hasTailwind
         ? `
-- **Styling mechanism:** prefer Tailwind utilities backed by the DS (\`bg-primary\`, \`p-md\`,
-  \`font-display\`, \`font-medium\`, …) for layout and new composition, and reuse the \`.ds-*\` recipes
-  for components the DS already covers. Use inline \`style\` with \`var(--ds-*)\` only as a last resort.
-  The token names below are the source vocabulary - every utility derives from them.`
+- **Styling mechanism:** prefer your project's own Tailwind utilities for layout and new
+  composition, and bring the recipes in as code (\`synthesisui component ${slug} <name>\`) for the
+  components this system already covers. Where no utility fits, write the name from the vocabulary
+  below - it is a name your own code declares.`
         : ""}
-- **Always use semantic tokens**, never raw values nor primitives directly.
-  Color: \`var(--ds-color-semantic-<role>)\`${hasTailwind ? " (utility: `bg-<role>`/`text-<role>`)" : ""}. The roles are: ${list(semanticRoles.map((r) => {
+- **Always use the system's vocabulary**, never raw values picked by eye. Every name below is a
+  name **your own code declares** - written exactly as you would write it. Nothing here comes from
+  a stylesheet of ours, and nothing needs one.
+  Color${hasTailwind ? " (utility: `bg-<role>`/`text-<role>`)" : ""}: ${semanticRoles
+        .map((r) => {
         const theirs = theirRole(r);
-        return theirs === r ? r : `${r} (${theirs} in your code)`;
-    }))}.
-- Primitives (\`--ds-color-<palette>-<step>\`) exist but should **not** be referenced directly -
-  they feed the semantic roles.${namedColours.length > 0
-        ? `\n- **Yours by name** → \`var(--ds-color-<name>)\`: ${namedColours.length} colour${namedColours.length === 1 ? "" : "s"} your code names by PURPOSE rather than by step, so no scale could hold ${namedColours.length === 1 ? "it" : "them"} - ${list(namedColours.slice(0, 8))}${namedColours.length > 8 ? ", …" : ""}. These are yours: reach for them when the purpose matches, and prefer a semantic role when it does not.`
+        /** O papel com o nome que ELE dá a ele - e o parêntese só sai quando os dois diferem. */
+        const named = theirs === r ? `\`${r}\`` : `\`${r} (${theirs} in your code)\``;
+        const as = saysAs(`--ds-color-semantic-${kebab(r)}`);
+        return as ? `${named} → \`${as}\`` : named;
+    })
+        .join(", ")}.${namedColours.length > 0
+        ? `\n- **Yours by name**: ${namedColours.length} colour${namedColours.length === 1 ? "" : "s"} your code names by PURPOSE rather than by step, so no scale could hold ${namedColours.length === 1 ? "it" : "them"} - ${family("color", namedColours.slice(0, 8))}${namedColours.length > 8 ? ", …" : ""}. These are yours: reach for them when the purpose matches, and prefer a semantic role when it does not.`
         : ""}${seriesKeys.length > 0
-        ? `\n- Data-viz → \`var(--ds-color-series-<n>)\`${hasTailwind ? " (utility: `bg-series-<n>`/`text-series-<n>`/`fill-series-<n>`)" : ""}: categorical chart/series colors, ${seriesKeys.length} of them (${list(seriesKeys)}). Use them in order for multi-series charts; they re-paint with the system.`
+        ? `\n- Data-viz${hasTailwind ? " (utility: `bg-series-<n>`/`text-series-<n>`/`fill-series-<n>`)" : ""}: categorical chart/series colors, ${seriesKeys.length} of them - ${family("color-series", seriesKeys)}. Use them in order for multi-series charts; they re-paint with the system.`
         : ""}
-- Spacing → \`var(--ds-spacing-<key>)\`: ${list(Object.keys(foundations.spacing))}.
-- Radius → \`var(--ds-radius-<key>)\`: ${list(Object.keys(foundations.radius))}.
-- Shadow → \`var(--ds-shadow-<key>)\`: ${list(Object.keys(foundations.shadow))}.
+- Spacing → ${family("spacing", Object.keys(foundations.spacing))}.
+- Radius → ${family("radius", Object.keys(foundations.radius))}.
+- Shadow → ${family("shadow", Object.keys(foundations.shadow))}.
 - Typography: families ${familySlots(foundations.typography.families)
-        .map((slot) => `\`${payload.fontSeam?.[slot] ?? `${FAMILY_SEAM_PREFIX}${slot}`}\` (${foundations.typography.families[slot]})`)
+        .map((slot) => {
+        const as = saysAs(`${FAMILY_SEAM_PREFIX}${kebab(slot)}`);
+        const face = foundations.typography.families[slot];
+        return as ? `\`${slot}\` → \`${as}\` (${face})` : `\`${slot}\` (${face})`;
+    })
         .join(", ")};
   weights${hasTailwind ? " (utility: `font-<key>`)" : ""}: ${list(weights)};
-  scale \`--ds-typography-scale-<key>-font-size\`${hasTailwind ? " (utility: `text-<key>`)" : ""}: ${list(Object.keys(foundations.typography.scale))}.
-- Motion: durations \`--ds-motion-durations-<key>\` (${list(Object.keys(motion.durations))}) and
-  easings \`--ds-motion-easings-<key>\` (${list(Object.keys(motion.easings))}). Use them on
-  \`transition\` (e.g. \`transition: color var(--ds-motion-durations-fast) var(--ds-motion-easings-standard)\`)
-  so timing stays on-brand. For ANIMATION, this system ships a named vocabulary - see
+  scale${hasTailwind ? " (utility: `text-<key>`)" : ""}: ${Object.keys(foundations.typography.scale)
+        .map((k) => {
+        const as = saysAs(`--ds-typography-scale-${kebab(k)}-font-size`);
+        return as ? `\`${k}\` → \`${as}\`` : `\`${k}\``;
+    })
+        .join(", ")}.
+- Motion: durations ${family("motion-durations", Object.keys(motion.durations))}
+  and easings ${family("motion-easings", Object.keys(motion.easings))}. Use them on
+  \`transition\` so timing stays on-brand. For ANIMATION, this system ships a named vocabulary - see
   **Motion vocabulary** below; never hand-roll \`@keyframes\` or raw durations.
 - When **creating a new component** the DS does not cover yet: compose it from these semantic
   tokens to inherit the system's identity; do not invent colors/measures outside the scale.
@@ -817,7 +864,8 @@ tell the person what you chose from the vocabulary instead.`
 
 ## Ready-made components
 
-Each recipe becomes a \`.ds-<name>\` class (inside the \`[data-ds="${slug}"]\` scope). Variants are
+Each recipe has a \`.ds-<name>\` class - the SHAPE it wears when \`synthesisui component\` writes it
+into your project, with the stylesheet that declares it alongside. Variants are
 \`data-<axis>="<option>"\` attributes; states (hover/focus/active/disabled) ship in the CSS;
 multi-part components expose \`.ds-<name>-<part>\` classes (listed under each).
 
@@ -832,7 +880,7 @@ A small gamification library the AI advisor (\`synthesisui advise\`) can propose
 \`.ds-<name>\` recipe shape as the components above, token-only so they wear the system. Use them
 **only where they fit the product** (progress, retention, recognition); they're a library to compose
 from, not a default - and lean against over-gamifying a serious B2B product. Each is a \`.ds-<name>\`
-class inside the \`[data-ds="${slug}"]\` scope; multi-part ones expose \`.ds-<name>-<part>\`.
+recipe; multi-part ones expose \`.ds-<name>-<part>\`.
 
 ${blockLines.join("\n\n")}
 `

package/dist/install-marks.js

@@ -235,7 +235,7 @@
  * chama `wireAgent`, então rodar o comando é o caminho de volta - e ele só alarga a string que era
  * nossa, nunca um filtro que uma pessoa escreveu.
  */
-export const MATERIALISER_SINCE = "0.16.421";
+export const MATERIALISER_SINCE = "0.16.422";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -343,8 +343,8 @@ export const MATERIALISER_SINCE = "0.16.421";
  * A frase viaja ao lado da versão porque as duas são uma coisa só: quem move a marca troca a
  * explicação no mesmo lugar, em vez de deixar o CI citando a causa da marca anterior.
  */
-export const COUNTED_DIFFERENTLY_SINCE = "0.16.421";
-export const COUNTED_DIFFERENTLY = "this run counts the utilities of your own theme - that version counted only `var(--token)`";
+export const COUNTED_DIFFERENTLY_SINCE = "0.16.422";
+export const COUNTED_DIFFERENTLY = "this run counts a value as named only when YOUR code names it - that version also counted the ones only the system named";
 /**
  * 0.16.408 -> 0.16.413 em 10/09: o hook passa a DIZER o valor que nada nomeia. Ele silenciava toda
  * deriva sem token de destino - a decisão estava escrita como "não vale interromper, porque o único
@@ -366,7 +366,7 @@ export const COUNTED_DIFFERENTLY = "this run counts the utilities of your own th
  * utility, um arquivo escrito inteiro no vocabulário do sistema recebia zero. A contagem em si é a
  * outra marca - ver `COUNTED_DIFFERENTLY_SINCE`, que sobe no mesmo diff.
  */
-export const CHECKER_SINCE = "0.16.421";
+export const CHECKER_SINCE = "0.16.422";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *