synthesisui 0.16.268 → 0.16.270

package/dist/claude-md.js

@@ -312,8 +312,35 @@ async function readInterfaceLanguage(projectRoot) {
     return null;
 }
 async function renderRegion(projectRoot, installed) {
+    /**
+     * AINDA NÃO EXISTE SISTEMA, E O BLOCO PASSA A DIZER ISSO - antes ele saía vazio.
+     *
+     * Medido no repo do dono (21/08): 52 bytes, só o par de marcadores. A informação existia por três
+     * canais e os três dependem de execução - as skills e o MCP exigem REABRIR a sessão, e o
+     * `SessionStart` exige `npx ... align` rodar. O CLAUDE.md é o único que não depende de nada, e era
+     * justamente o calado: se o SessionStart falhar, o agente abre sem saber que há algo a fazer aqui.
+     *
+     * UMA LINHA, NÃO UM MANUAL, e nada sobre token ou componente: um bloco que falasse de
+     * `--ds-color-*` num repo sem sistema mandaria o agente escrever refs que não resolvem. O erro
+     * oposto é pior que o silêncio.
+     */
     if (installed.length === 0) {
-        return `${START}\n${END}`;
+        return [
+            START,
+            "## Design system",
+            "",
+            "This project is wired to synthesisui and has **no design system yet** - so there is",
+            "no token vocabulary to follow, and nothing here to obey.",
+            "",
+            "To turn this repository into one, run `/sui-import-ds` and I will read what is",
+            "already in the code: the colours, the type, the shapes and the components. Nothing",
+            "is invented, and nothing is copied out.",
+            "",
+            "The `synthesisui` MCP server is registered, so ASK it instead of guessing - it",
+            "answers what exists and what does not. This block fills itself in once a system is",
+            "installed.",
+            END,
+        ].join("\n");
     }
     /**
      * A CAPACIDADE, MEDIDA UMA VEZ POR ARQUIVO - ver `recallAvailable`.

package/dist/commands/add.js

@@ -41,6 +41,27 @@ const IGNORED = [
 const IGNORE_HEADER = "# Managed by synthesisui. The identity and the CSS are committed so a fresh\n" +
     "# clone is governed; the measurement and the local record are not, because\n" +
     "# both are rewritten in full on every run and would conflict on every merge.\n";
+/**
+ * A CASA DO REGISTRO LOCAL, ABERTA ANTES DE ALGUÉM ESCREVER NELA.
+ *
+ * Medido no repo do dono em 21/08, depois de apagar tudo e rodar só o `connect`: `.claude/`,
+ * `.mcp.json` e `CLAUDE.md` nasceram, e `_synthesisui/` não. `appendEvent` grava com `appendFile` e
+ * nunca cria diretório - sem a pasta é `ENOENT`, e o `catch` dele engole em silêncio. Então TODO
+ * evento entre o `connect` e o primeiro `import` se perdia: o `run` do próprio connect, e cada check
+ * do hook depois de cada escrita.
+ *
+ * POR QUE AQUI E NÃO NO `appendEvent`: fazer o gravador criar a pasta faria um `npx synthesisui list`
+ * de curiosidade plantar `_synthesisui/` no repo de quem só estava olhando - e aquele `catch` existe
+ * exatamente para esse caso. O `connect` é o comando que INSTALA, e é o único lugar onde abrir a casa
+ * é uma decisão que a pessoa tomou.
+ *
+ * A casa nasce com o `.gitignore`, senão o primeiro `ledger.jsonl` aparece no `git status` dele antes
+ * de o `add` rodar - a diferença entre um registro local e um arquivo que ele commita por engano.
+ */
+export async function ensureGovernanceHome(projectRoot) {
+    await mkdir(join(projectRoot, "_synthesisui"), { recursive: true });
+    await writeGovernanceIgnore(projectRoot);
+}
 async function writeGovernanceIgnore(projectRoot) {
     const path = join(projectRoot, "_synthesisui", ".gitignore");
     const existing = await readFile(path, "utf8").catch(() => null);

package/dist/commands/connect.js

@@ -7,7 +7,7 @@ import { body, paint, section, snippet } from "../output.js";
 import { readShellAnswer, rememberShellNo } from "../shell-answer.js";
 import { existingRc, hasHook, pinnedInHook, rcPathFor, shellFrom, shellSnippet, withHook, } from "../shell-hook.js";
 import { SKILLS } from "../skills.js";
-import { add } from "./add.js";
+import { add, ensureGovernanceHome } from "./add.js";
 import { reportWhatIsLeft } from "./align.js";
 import { ci } from "./ci.js";
 import { MCP_TOOL_COUNT } from "./mcp.js";
@@ -209,6 +209,14 @@ export async function connect(opts) {
      * `syncClaudeMd` abaixo tem que ser o último a falar sobre ele.
      */
     const refreshed = await refreshInstall(root, opts.version, opts.registry).catch(() => null);
+    /**
+     * A CASA DO REGISTRO LOCAL, ANTES DA PRIMEIRA ESCRITA - ver `ensureGovernanceHome`.
+     *
+     * Aqui e não depois: o `wireAgent` já é um comando que roda, e o `run` desta própria execução é
+     * gravado no fim pelo wrapper do `index.ts`. Sem a pasta ele cai num `catch` silencioso, junto com
+     * todo check do hook até o primeiro `import` - medido no repo do dono em 21/08.
+     */
+    await ensureGovernanceHome(root);
     const wired = await wireAgent(root, opts.version, want);
     // The block reads the settings we just wrote, so it must be regenerated
     // after them, not before.
@@ -299,9 +307,20 @@ export async function connect(opts) {
         const moved = contract.changed.includes(home);
         console.log(body(`${moved ? "✓" : "·"} ${home.padEnd(22)} ${moved
             ? home === "CLAUDE.md"
-                ? "rewritten for what is installed"
+                ? /**
+                   * A FRASE DIZ O QUE O BLOCO CARREGA, e ela descrevia um conteúdo que não existia.
+                   *
+                   * Num repo sem sistema o bloco saía vazio e esta linha dizia "rewritten for what is
+                   * installed" - nada estava instalado, e nada foi escrito. Agora o bloco diz o que
+                   * fazer, e a linha diz qual dos dois ele é (dono, 21/08).
+                   */
+                    contract.count === 0
+                        ? "how to turn this repo into your system"
+                        : "rewritten for what is installed"
                 : "the same rules, where this agent reads them"
-            : "already says what is installed"}`));
+            : contract.count === 0
+                ? "already says how to start"
+                : "already says what is installed"}`));
     }
     /**
      * The fourth layer, and the one that had no installer at all: the import

package/dist/commands/import.js

@@ -35,6 +35,7 @@ import { buildTable } from "../doctor/tokens.js";
 import { definitionSpan, parseClass, readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
 import { frontierKind, packageRoot } from "../frontier-kind.js";
+import { keyframesInSheets } from "../global-keyframes.js";
 import { withLibraryStructure } from "../library-structure.js";
 import { mergeCensus } from "../merge-census.js";
 import { claimName } from "../name-claim.js";
@@ -435,6 +436,18 @@ export async function takeCensus(root, opts) {
      * porque é isso que o juiz do ledger precisa para chamar a classe e a regra de LIDAS.
      */
     const globalClasses = readGlobalClasses(globalSheets, declaredValues);
+    /**
+     * OS KEYFRAMES DA FOLHA DELE, colhidos onde as folhas globais já estão na mão.
+     *
+     * Eram 35 dos 84 tokens declarados do codelevel - 42% do vocabulário - e o censo saía com
+     * `keyframes: undefined`, porque o leitor só olhava CSS Module e `<style>` island. Ver
+     * `global-keyframes.ts` para o porquê e para o que o valor de cada `--animate-*` carrega.
+     *
+     * Aqui e não dentro de `harvestOwnCss` porque aquela função é o laço de COLHEITA, e esta é uma
+     * leitura sobre o que ela colheu - a mesma divisão que `readGlobalClasses` já respeita, uma linha
+     * acima.
+     */
+    const globalKeyframes = keyframesInSheets(globalSheets);
     const globalClassesClaimed = new Set();
     /** Por arquivo, as classes cuja regra a `<style>` island já entregou - ver o juiz. */
     const islandClassesRead = new Map();
@@ -1952,7 +1965,17 @@ export async function takeCensus(root, opts) {
                 : {}),
         },
         declared: Object.fromEntries(table.byName),
-        ...(Object.keys(keyframes).length > 0 ? { keyframes } : {}),
+        /**
+         * A FOLHA DELE ENTRA POR ÚLTIMO, e a ordem é a resposta a quem manda.
+         *
+         * `keyframes` já traz o que veio de CSS Module e de `<style>` island - definições de COMPONENTE.
+         * A folha global é a base do app, então ela preenche o que falta e não sobrescreve o que um
+         * componente declarou para si. Sem esta linha o codelevel saía com `keyframes: undefined` e 35 dos
+         * 84 tokens dele - 42% do vocabulário - não chegavam a lugar nenhum.
+         */
+        ...(Object.keys({ ...globalKeyframes, ...keyframes }).length > 0
+            ? { keyframes: { ...globalKeyframes, ...keyframes } }
+            : {}),
         ...(animations.size > 0 ? { animations: [...animations].sort() } : {}),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
         /**

package/dist/commands/mcp.js

@@ -3,6 +3,7 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import { provenanceAction, toolSlug, withSource, } from "../agent-provenance.js";
 import { pinnedHookVersion } from "../agent-wiring.js";
+import { elementClass, kebabAxis } from "../component-codegen.js";
 import { composePlan, FAMILIES, isFamily, noFamilyAnswer, renderPlan, } from "../compose-context.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
@@ -11,6 +12,7 @@ import { diagnose, nameToWrite, scanSource } from "../doctor/scan.js";
 import { nearestToken, normalizeValue, tokenFor } from "../doctor/tokens.js";
 import { fromCensus } from "../memory/observation.js";
 import { handleRecall, handleRemember, MEMORY_TOOLS } from "../memory/tools.js";
+import { readInstalledConvention } from "../project-facts.js";
 import { repoStateOf } from "../repo-state.js";
 import { detectStack } from "../stack.js";
 import { component } from "./component.js";
@@ -974,7 +976,7 @@ query) {
     }
 }
 async function describeComponent(root, name) {
-    const { documents, requires } = await loadSystem(root);
+    const { documents, requires, table } = await loadSystem(root);
     let recipe;
     for (const doc of documents) {
         const d = doc;
@@ -1118,6 +1120,69 @@ async function describeComponent(root, name) {
     if (composes.length > 0) {
         out.push("", `Built out of: ${composes.join(", ")}. Change one of those in one place rather than reproducing it here, and call describe_component on it before you do.`);
     }
+    /**
+     * HOW TO DRESS IT - and it was the half this answer never carried.
+     *
+     * Measured on the owner's own census (21/08): his Button declares three axes -
+     * `variant` with eight options, `size` with four, `glow` with two - plus
+     * defaults, 32 layers and 78 properties. The whole reply for a component like
+     * that was its name, its description and "no rules govern this yet". An agent
+     * reading it composes without knowing `gold` exists, and nothing anywhere
+     * says an option was missed.
+     *
+     * The material was already here: `recipe.variants` is the SAME field the
+     * `GUIDE.md` reads to print `data-variant="primary|gold|…"`. Two surfaces
+     * answering one question, and only the file on disk answered it.
+     *
+     * The class comes from `readInstalledConvention`, never from a literal `ds-`:
+     * an imported system may carry its own prefix in `meta.classNames`, and
+     * telling the agent to write a class that does not exist is worse than
+     * telling it nothing.
+     */
+    const axes = Object.entries(recipe.variants ?? {});
+    if (axes.length > 0) {
+        const convention = await readInstalledConvention(root, String(table.slug ?? ""));
+        const cls = elementClass(name, convention);
+        out.push("", `How to dress it: \`${cls}\`, plus one data attribute per axis.`);
+        for (const [axis, options] of axes) {
+            const names = Object.keys(options ?? {});
+            if (names.length === 0)
+                continue;
+            const resting = recipe.defaults?.[axis];
+            /**
+             * O DEFAULT É O QUE ELE NÃO PRECISA ESCREVER, e dizer isso encurta o
+             * código que o agente produz em vez de só informá-lo.
+             */
+            const rest = resting
+                ? ` - at rest it is \`${resting}\`, so you can leave the attribute out`
+                : "";
+            out.push(`  data-${kebabAxis(axis)}="${names.join("|")}"${rest}`);
+        }
+        const states = Object.keys(recipe.states ?? {});
+        if (states.length > 0) {
+            out.push(`  states the recipe already carries: ${states.join(", ")} - they are CSS, so do not write them again in JS.`);
+        }
+        out.push(`  Or call add_component { "name": "${name}" } and get it as typed code, one prop per axis.`);
+    }
+    /**
+     * AS INSTRUÇÕES DE RENDER QUE A LEITURA MEDIU - e até aqui elas morriam no
+     * terminal.
+     *
+     * O CLI mede `renderNotes` por componente e imprime uma vez, no import. São
+     * 25 delas em 14 dos 59 componentes do dono, e uma diz: *"`ring` gates a look
+     * and is a boolean rather than an axis - `data-ring` has to be set for it to
+     * apply"*. Sem essa linha o agente escreve markup correto e o look nunca
+     * aparece, que é o pior modo de falhar - nada reclama.
+     *
+     * O princípio, e ele vale além destas notas: **interpretada ou não por nós,
+     * a instrução vai para quem constrói**. Uma nota que a esteira não soube
+     * transformar em regra continua sendo a coisa mais útil que existe sobre
+     * aquele componente.
+     */
+    const renderNotes = recipe.renderNotes ?? [];
+    if (renderNotes.length > 0) {
+        out.push("", "Read off your own code, and it decides whether the look appears:", ...renderNotes.map((n) => `  ${n}`));
+    }
     /**
      * WHAT IT NEEDS INSTALLED - the whole reason this tool earns its place.
      *

package/dist/component-codegen.js

@@ -4,8 +4,16 @@ export const DEFAULT_CONVENTION = {
     partSeparator: "-",
 };
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-/** `metric-card` → `ds-metric-card`, or `metric-card`, or `sui-metric-card`. */
-const elementClass = (name, c) => `${c.prefix}${kebab(name)}`;
+/**
+ * `metric-card` → `ds-metric-card`, or `metric-card`, or `sui-metric-card`.
+ *
+ * EXPORTADA porque o `describe_component` passou a dizer ao agente qual classe
+ * escrever, e uma segunda implementação do mesmo nome é como as duas começam a
+ * divergir: o MCP mandaria escrever uma classe que este codegen não emite.
+ */
+export const elementClass = (name, c) => `${c.prefix}${kebab(name)}`;
+/** O mesmo kebab que decide a classe e o `data-*`, para quem precisa só do eixo. */
+export const kebabAxis = (v) => kebab(v);
 /** `metric-card` + `title` → `ds-metric-card-title`, or `metric-card__title`. */
 const partClassName = (name, part, c) => `${elementClass(name, c)}${c.partSeparator}${kebab(part)}`;
 const pascal = (name) => name

package/dist/fonts.js

@@ -12,12 +12,31 @@ const GENERIC_FAMILIES = new Set([
     "inherit",
     "initial",
 ]);
-/** Famílias CUSTOM (display/body/mono), dedup e sem os genéricos. */
+/**
+ * TODA VAGA DE FONTE DO DOCUMENTO, dedup e sem os genéricos.
+ *
+ * Enumerava `[display, body, mono]` literalmente, e o documento passou a aceitar as famílias que o
+ * código DELE declara além das nossas três - `--font-serif` do codelevel é "Instrument Serif", 25 usos,
+ * reservada por ele para "editorial moments". O token existia, o compilador emitia
+ * `--ds-typography-families-serif`, e ninguém baixava a fonte: o texto saía no fallback do navegador e
+ * nada avisava. Um token que aponta para uma fonte que ninguém carregou é pior que um token ausente -
+ * o ausente pelo menos aparece na conta.
+ *
+ * A ORDEM É DETERMINÍSTICA: as três vagas primeiro, as dele em ordem alfabética. Isto vira href num
+ * arquivo gerado, e um conjunto que muda de ordem entre rodadas produz diff onde nada mudou.
+ */
+export const familySlots = (families) => {
+    const ours = ["display", "body", "mono"].filter((k) => k in families);
+    const theirs = Object.keys(families)
+        .filter((k) => !ours.includes(k))
+        .sort();
+    return [...ours, ...theirs];
+};
 export function customFontFamilies(families) {
     const seen = new Set();
     const names = [];
-    for (const family of [families.display, families.body, families.mono]) {
-        const name = family?.trim();
+    for (const slot of familySlots(families)) {
+        const name = families[slot]?.trim();
         if (!name)
             continue;
         const key = name.toLowerCase();
@@ -47,7 +66,8 @@ export function googleFontsHref(families) {
  * fallback - it works everywhere but swaps visibly on cold loads.
  */
 export function nextFontSnippet(families, slug, appDir = "app") {
-    const roles = ["display", "body", "mono"].filter((role) => {
+    /** Toda vaga que o documento tem, não só as nossas três - ver `customFontFamilies`. */
+    const roles = familySlots(families).filter((role) => {
         const name = families[role]?.trim();
         return name && !GENERIC_FAMILIES.has(name.toLowerCase());
     });
@@ -58,7 +78,7 @@ export function nextFontSnippet(families, slug, appDir = "app") {
     const importNames = [];
     const consts = [];
     for (const role of roles) {
-        const name = families[role].trim();
+        const name = (families[role] ?? "").trim();
         if (!seen.has(name)) {
             seen.set(name, role);
             importNames.push(importName(name));
@@ -81,13 +101,13 @@ export function nextFontSnippet(families, slug, appDir = "app") {
         ...consts,
     ];
     const roleVar = (role) => {
-        const name = families[role].trim();
+        const name = (families[role] ?? "").trim();
         return `--font-ds-${seen.get(name)}`;
     };
     const layout = [
         `// ${appDir}/layout.tsx`,
-        `import { ${[...new Set(roles.map((r) => seen.get(families[r].trim())))].join(", ")} } from "./fonts";`,
-        `<body data-ds="${slug}" className={\`${[...new Set(roles.map((r) => `\${${seen.get(families[r].trim())}.variable}`))].join(" ")}\`}>`,
+        `import { ${[...new Set(roles.map((r) => seen.get((families[r] ?? "").trim())))].join(", ")} } from "./fonts";`,
+        `<body data-ds="${slug}" className={\`${[...new Set(roles.map((r) => `\${${seen.get((families[r] ?? "").trim())}.variable}`))].join(" ")}\`}>`,
     ];
     const css = [
         `/* ${appDir}/globals.css - AFTER the tokens.css import */`,

package/dist/global-keyframes.js

@@ -0,0 +1,46 @@
+import { keyframeOffsets, readModuleCss } from "./doctor/css-modules.js";
+/**
+ * OS KEYFRAMES QUE A FOLHA DELE DECLARA - e eram 42% do vocabulário do codelevel.
+ *
+ * O leitor colhia keyframes de duas fontes: o CSS Module de um componente e o `<style>` island. Não da
+ * folha GLOBAL, que é exatamente onde um projeto Tailwind v4 com `@theme` os escreve. Medido no censo
+ * do dono (21/08): 35 dos 84 tokens declarados são `--animate-*`, e o censo saía com
+ * `keyframes: undefined`.
+ *
+ * O valor de cada atalho carrega tudo o que importa, e nada disso chegava:
+ *
+ *     --animate-fade-slide-in: fade-slide-in 1s var(--ease-out-soft) both
+ *                              ^ o keyframe   ^ dur ^ o easing DELE  ^ fill
+ *
+ * E a consequência não era só perder token. `unknownAnimations` crescia: o documento recusava definir
+ * quatro animações que os componentes dele nomeiam - a nota dizia "a plugin's own" - quando a definição
+ * estava na folha dele, a um parser de distância.
+ *
+ * NADA AQUI É PARSER NOVO. `readModuleCss` já extrai `@keyframes` de qualquer CSS e `keyframeOffsets`
+ * já vira o corpo cru na forma que o documento quer (offset → declarações). Só ninguém os chamava para
+ * a folha global. É o mesmo defeito de forma que apareceu seis vezes nesta rodada: a varredura
+ * enumerando as fontes que já conhecia.
+ *
+ * MATERIALISER - um cliente pinado recebe diferente? Não: isto muda o CENSO, e o que cai na pasta dele
+ * vem do documento que o servidor compila depois. Ele só vê a diferença após um re-import, e é por isso
+ * que esta é a única entrega da rodada que exige um.
+ */
+export function keyframesInSheets(sheets) {
+    const out = {};
+    for (const sheet of sheets) {
+        if (!sheet.body.includes("@keyframes"))
+            continue;
+        const read = readModuleCss(sheet.body);
+        for (const [name, body] of Object.entries(read.keyframes)) {
+            /** A PRIMEIRA declaração vence, como em todo leitor daqui: duas folhas com o mesmo nome é
+             *  theming por área, e escolher a última faria a ordem de caminhada decidir o resultado. */
+            if (out[name])
+                continue;
+            const offsets = keyframeOffsets(body);
+            /** Um nome sem corpo legível viraria uma referência que não anima nada. */
+            if (Object.keys(offsets).length > 0)
+                out[name] = offsets;
+        }
+    }
+    return out;
+}

package/dist/guide.js

@@ -1,4 +1,12 @@
-import { nextFontSnippet } from "./fonts.js";
+/**
+ * UMA IMPLEMENTAÇÃO SÓ, e este arquivo tinha a terceira.
+ *
+ * `customFontFamilies` existia aqui, em `fonts.ts` e em `ds-font-link.tsx` - três cópias de um
+ * julgamento, e as três enumeravam `[display, body, mono]`. Quando o documento passou a aceitar as
+ * famílias que o código dele declara, as três deixaram de carregar a fonte ao mesmo tempo. Este
+ * arquivo já importava `nextFontSnippet` do mesmo módulo; a cópia não tinha razão de existir.
+ */
+import { customFontFamilies, familySlots, nextFontSnippet } from "./fonts.js";
 import { animationShorthand, classifyKeyframe, describeKeyframe, isFullRotation, } from "./motion.js";
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
 /**
@@ -25,21 +33,6 @@ const GENERIC_FAMILIES = new Set([
     "initial",
 ]);
 /** Famílias custom do documento (display/body/mono), deduplicadas, sem genéricos. */
-function customFontFamilies(families) {
-    const seen = new Set();
-    const out = [];
-    for (const family of [families.display, families.body, families.mono]) {
-        const name = family?.trim();
-        if (!name)
-            continue;
-        const key = name.toLowerCase();
-        if (GENERIC_FAMILIES.has(key) || seen.has(key))
-            continue;
-        seen.add(key);
-        out.push(name);
-    }
-    return out;
-}
 /**
  * THE STRUCTURE, WITH WHAT EACH PART IS FOR AND WHEN IT EXISTS.
  *
@@ -269,6 +262,14 @@ export function buildGuide(payload) {
     const { document: doc, slug, name, version } = payload;
     const { meta, foundations, motion, components } = doc;
     const semanticRoles = Object.keys(foundations.color.semantic);
+    /**
+     * AS CORES QUE ELE NOMEIA POR PROPÓSITO, no arquivo que o agente lê primeiro.
+     *
+     * O compilador passou a emitir `--ds-color-tier-gold` e o `find_token` já as acha (ele lê o
+     * `tokens.css`), mas o GUIDE é onde o agente descobre o vocabulário ANTES de perguntar - e ele não
+     * as mencionava. São 19 no censo do dono, e são a parte que faz o sistema dele ser dele.
+     */
+    const namedColours = Object.keys(foundations.color.named ?? {});
     const seriesKeys = Object.keys(foundations.color.series ?? {});
     const fontFamilies = customFontFamilies(foundations.typography.families);
     const fontsHref = fontFamilies.length > 0
@@ -680,13 +681,17 @@ ${hasTailwind
 - **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)}.
 - Primitives (\`--ds-color-<palette>-<step>\`) exist but should **not** be referenced directly -
-  they feed the semantic roles.${seriesKeys.length > 0
+  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.`
+        : ""}${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.`
         : ""}
 - 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))}.
-- Typography: families \`--ds-typography-families-{display,body,mono}\` (${foundations.typography.families.display}, ${foundations.typography.families.body}, ${foundations.typography.families.mono});
+- Typography: families ${familySlots(foundations.typography.families)
+        .map((slot) => `\`--ds-typography-families-${slot}\` (${foundations.typography.families[slot]})`)
+        .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

package/dist/install-marks.js

@@ -115,7 +115,20 @@
  * O índice de componentes é BYTE-IDÊNTICO nos dois caminhos - mesma fonte canônica, mesmos nomes,
  * mesma quantidade (`claude-md.f0.spec.ts`). O corte troca uma frase, nunca o inventário.
  */
-export const MATERIALISER_SINCE = "0.16.265";
+/**
+ * 0.16.269 -> 0.16.270 em 21/08, e a correção é de uma ARMADILHA que vai repetir.
+ *
+ * A marca foi escrita como "0.16.269" porque era o que o `package.json` dizia naquele instante. Só que
+ * o dono PUBLICOU o 0.16.269 antes de o código entrar - o pacote no npm saiu 17:46 e o PR foi mergeado
+ * 18:53. Então a marca apontava para uma versão que existe e NÃO tem a mudança, e o efeito era o pior
+ * possível: `installedBehind("0.16.269", "0.16.270", "0.16.269")` é FALSO, então o cliente que instalou
+ * aquele 0.16.269 nunca seria avisado.
+ *
+ * A REGRA, para não repetir: a marca aponta para a versão que vai ser PUBLICADA COM a mudança, e essa
+ * é sempre o bump deste PR - nunca o número que o `package.json` já carrega, porque alguém pode
+ * publicar no meio.
+ */
+export const MATERIALISER_SINCE = "0.16.270";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *
@@ -217,7 +230,21 @@ export const CHECKER_SINCE = "0.16.250";
  *               (era 53% no melhor caminho; o derivado dava 38%). Um censo medido antes disto não
  *               tem versão nenhuma - e o mapa de blueprints por versão não tem o que consultar.
  */
-export const READER_SINCE = "0.16.261";
+/**
+ * `0.16.261` -> `0.16.269` em 21/08: os keyframes que a folha GLOBAL dele declara passaram a ser
+ * lidos - ver `global-keyframes.ts`.
+ *
+ * O portão desta marca é o corpus dourado, e ele NÃO cobrou: o censo dos treze apps saiu idêntico,
+ * porque nenhuma das treze fixtures escreve `@keyframes` em folha global. A marca sobe por decisão,
+ * não por vermelho - e o número que justifica está no repo real: 35 dos 84 tokens declarados do
+ * codelevel são `--animate-*`, o censo dele saía com `keyframes: undefined`, e agora sai com 35.
+ *
+ * Sem subir, o `align` nunca diria a quem já importou que vale remedir - que é a única coisa que esta
+ * marca existe para fazer.
+ */
+/** 0.16.269 -> 0.16.270 pelo mesmo motivo do MATERIALISER acima: o 0.16.269 foi publicado sem o
+ *  leitor de keyframes globais, e uma marca que aponta para ele cala o aviso para quem o instalou. */
+export const READER_SINCE = "0.16.270";
 /**
  * O QUE ESTÁ INSTALADO AQUI FICOU PARA TRÁS - e as DUAS condições que fazem isso ser verdade.
  *

package/package.json

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