synthesisui 0.16.268 → 0.16.269

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/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,7 @@
  * 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";
+export const MATERIALISER_SINCE = "0.16.269";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/package.json

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