synthesisui 0.1.2 → 0.1.5

package/README.md

@@ -1,54 +1,55 @@
 # synthesisui
 
-CLI para trazer design systems publicados no [SynthesisUI](https://www.synthesisui.com)
-para dentro de qualquer projeto. Materializa o sistema em `_synthesisui/ds/<slug>/` e injeta
-um bloco gerenciado no `CLAUDE.md` da raiz, de forma que o Claude Code construa
-componentes seguindo o design system.
+CLI to bring design systems published on [SynthesisUI](https://www.synthesisui.com)
+into any project. It materializes the system into `_synthesisui/ds/<slug>/` and injects
+a managed block into the root `CLAUDE.md`, so Claude Code builds components following the
+design system.
 
-## Uso
+## Usage
 
-Sem instalar nada:
+Without installing anything:
 
 ```bash
-npx synthesisui login        # conecta o CLI à sua conta (device-flow no browser)
-npx synthesisui list         # lista os design systems disponíveis
-npx synthesisui add <slug>   # traz um DS para _synthesisui/ds/<slug>/
+npx synthesisui login        # connect the CLI to your account (device-flow in the browser)
+npx synthesisui list         # list the available design systems
+npx synthesisui add <slug>   # bring a DS into _synthesisui/ds/<slug>/
 ```
 
-Ou instale globalmente:
+Or install globally:
 
 ```bash
 npm install -g synthesisui
 synthesisui add halogen
 ```
 
-### O que o `add` materializa
+### What `add` materializes
 
-Em `_synthesisui/ds/<slug>/`:
+In `_synthesisui/ds/<slug>/`:
 
-- `design-system.json` — a verdade canônica do design system
-- `tokens.css` — CSS custom properties escopadas por `data-ds`
-- `GUIDE.md` — instruções para o agente (papéis semânticos, mood, recipes, como adicionar componentes)
-- `.lock` — slug + versão pinada (reproduzível)
+- `design-system.json` — the canonical source of truth of the design system
+- `tokens.css` — CSS custom properties scoped by `data-ds`
+- `theme.css` — optional Tailwind v4 `@theme` adapter (use `bg-primary`, `p-md`, … backed by the tokens)
+- `GUIDE.md` — instructions for the agent (semantic roles, mood, recipes, how to add components)
+- `.lock` — pinned slug + version (reproducible)
 
-E injeta um bloco idempotente `<!-- synthesisui:start/end -->` no `CLAUDE.md` da raiz,
-refletindo todos os DSs instalados.
+And it injects an idempotent `<!-- synthesisui:start/end -->` block into the root `CLAUDE.md`,
+reflecting every installed DS.
 
-## Autenticação
+## Authentication
 
-`synthesisui login` usa device-flow (RFC 8628): abre o browser, você confirma um código,
-e o token é salvo em `~/.synthesisui/credentials.json` (por máquina). Logout = apagar esse arquivo.
+`synthesisui login` uses device-flow (RFC 8628): it opens the browser, you confirm a code,
+and the token is saved to `~/.synthesisui/credentials.json` (per machine). Logout = delete that file.
 
 ## Registry
 
-Por padrão aponta para `https://www.synthesisui.com`. Sobrescreva com:
+By default it points to `https://www.synthesisui.com`. Override it with:
 
 ```bash
 synthesisui list --registry http://localhost:3000
-# ou
+# or
 SYNTHESISUI_REGISTRY_URL=http://localhost:3000 synthesisui list
 ```
 
-## Licença
+## License
 
 MIT

package/dist/claude-md.js

@@ -2,7 +2,7 @@ import { readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 const START = "<!-- synthesisui:start -->";
 const END = "<!-- synthesisui:end -->";
-/** Lê os DSs instalados a partir dos .lock em _synthesisui/ds/<slug>/. */
+/** Reads the installed DSs from the .lock files in _synthesisui/ds/<slug>/. */
 async function readInstalled(projectRoot) {
     const dsDir = join(projectRoot, "_synthesisui", "ds");
     let entries = [];
@@ -21,7 +21,7 @@ async function readInstalled(projectRoot) {
             locks.push({ slug: lock.slug, name: lock.name, version: lock.version });
         }
         catch {
-            // pasta sem .lock válido — ignora
+            // folder without a valid .lock — ignore
         }
     }
     return locks;
@@ -31,26 +31,26 @@ function renderRegion(installed) {
         return `${START}\n${END}`;
     }
     const lines = installed
-        .map((ds) => `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) — guia: \`_synthesisui/ds/${ds.slug}/GUIDE.md\``)
+        .map((ds) => `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) — guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``)
         .join("\n");
     const body = `## Design Systems (via SynthesisUI)
 
-Este projeto usa design system(s) trazido(s) pelo \`synthesisui\` CLI. **Ao criar ou editar
-componentes, leia o GUIDE.md do sistema e siga-o:** use apenas tokens semânticos
-(\`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`, etc.), escope a UI com \`data-ds="<slug>"\`,
-e reaproveite as classes \`.ds-*\`. Não use valores crus fora da escala do sistema. **Para revisar um
-componente, crie uma página de amostra isolada (ex.: \`app/synthesisui-samples/<componente>/\`) — não
-aplique a páginas reais de produção a menos que seja pedido.**
+This project uses design system(s) brought in by the \`synthesisui\` CLI. **When creating or editing
+components, read the system's GUIDE.md and follow it:** use only semantic tokens
+(\`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`, etc.), scope the UI with \`data-ds="<slug>"\`,
+and reuse the \`.ds-*\` classes. Do not use raw values outside the system's scale. **To review a
+component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) — do not
+apply it to real production pages unless asked.**
 
 ${lines}
 
-_Bloco gerenciado pelo CLI — não edite à mão; rode \`synthesisui add <slug>\` para atualizar._`;
+_Block managed by the CLI — do not edit by hand; run \`synthesisui add <slug>\` to update._`;
     return `${START}\n${body}\n${END}`;
 }
 /**
- * Regenera o bloco gerenciado no CLAUDE.md da raiz refletindo todos os DSs
- * instalados. Idempotente: substitui o trecho entre os marcadores se existir,
- * senão cria o arquivo / anexa o bloco. Retorna se o arquivo foi criado.
+ * Regenerates the managed block in the root CLAUDE.md reflecting every installed
+ * DS. Idempotent: replaces the text between the markers if present, otherwise
+ * creates the file / appends the block. Returns whether the file was created.
  */
 export async function syncClaudeMd(projectRoot) {
     const installed = await readInstalled(projectRoot);

package/dist/commands/add.js

@@ -1,28 +1,50 @@
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { syncClaudeMd } from "../claude-md.js";
 import { resolveRegistry } from "../config.js";
 import { buildGuide } from "../guide.js";
 import { fetchDesignSystem } from "../registry.js";
+async function readRootLock(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
 /**
- * Materializa um DS publicado em `_synthesisui/ds/<slug>/` e atualiza o CLAUDE.md.
+ * Materializes a published DS into `_synthesisui/ds/<slug>/v<version>/`, points
+ * stable root re-exports (tokens.css/theme.css) and a `.lock` at it, and updates
+ * CLAUDE.md. Older version folders are kept for rollback/diff.
  */
 export async function add(slug, opts) {
     const base = resolveRegistry(opts.registry);
     const projectRoot = opts.dir ?? process.cwd();
-    console.log(`→ buscando "${slug}" em ${base} …`);
-    const payload = await fetchDesignSystem(base, slug);
-    const targetDir = join(projectRoot, "_synthesisui", "ds", payload.slug);
-    await mkdir(targetDir, { recursive: true });
-    // 1. artifacts compilados pelo servidor (tokens.css, e futuros theme.css…)
+    const label = opts.version != null ? `${slug}@v${opts.version}` : slug;
+    console.log(`→ fetching "${label}" from ${base} …`);
+    const payload = await fetchDesignSystem(base, slug, opts.version);
+    const slugDir = join(projectRoot, "_synthesisui", "ds", payload.slug);
+    const versionDir = join(slugDir, `v${payload.version}`);
+    const rootLockPath = join(slugDir, ".lock");
+    // know what was active before, to report install vs update vs switch
+    const prev = await readRootLock(rootLockPath);
+    await mkdir(versionDir, { recursive: true });
+    // 1. server artifacts (tokens.css, theme.css, …) → pinned version folder
     for (const [filename, content] of Object.entries(payload.artifacts)) {
-        await writeFile(join(targetDir, filename), content, "utf8");
+        await writeFile(join(versionDir, filename), content, "utf8");
+    }
+    // 2. canonical source of truth
+    await writeFile(join(versionDir, "design-system.json"), `${JSON.stringify(payload.document, null, 2)}\n`, "utf8");
+    // 3. guide for the agent (generated client-side from the document)
+    await writeFile(join(versionDir, "GUIDE.md"), buildGuide(payload), "utf8");
+    // 4. stable root re-exports for each CSS artifact → always the active version,
+    //    so the consumer's @import path never changes across updates
+    const cssArtifacts = Object.keys(payload.artifacts).filter((f) => f.endsWith(".css"));
+    for (const filename of cssArtifacts) {
+        await writeFile(join(slugDir, filename), `/* Active version (v${payload.version}). Managed by synthesisui — do not edit. */\n` +
+            `@import "./v${payload.version}/${filename}";\n`, "utf8");
     }
-    // 2. verdade canônica
-    await writeFile(join(targetDir, "design-system.json"), `${JSON.stringify(payload.document, null, 2)}\n`, "utf8");
-    // 3. guia para o agente (gerado client-side a partir do document)
-    await writeFile(join(targetDir, "GUIDE.md"), buildGuide(payload), "utf8");
-    // 4. lock reproduzível
+    // 5. root pointer
     const lock = {
         slug: payload.slug,
         name: payload.name,
@@ -30,21 +52,33 @@ export async function add(slug, opts) {
         registry: base,
         fetchedAt: new Date().toISOString(),
     };
-    await writeFile(join(targetDir, ".lock"), `${JSON.stringify(lock, null, 2)}\n`, "utf8");
-    // 5. descoberta pelo agente
+    await writeFile(rootLockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+    // 6. discovery by the agent
     const claudeMd = await syncClaudeMd(projectRoot);
+    // outcome line
+    const v = payload.version;
+    if (!prev) {
+        console.log(`✓ ${payload.name} v${v} installed → _synthesisui/ds/${payload.slug}/`);
+    }
+    else if (prev.version === v) {
+        console.log(`✓ ${payload.name} v${v} already installed${opts.version == null ? " (latest)" : ""} — refreshed`);
+    }
+    else if (v > prev.version) {
+        console.log(`↑ ${payload.name} v${prev.version} → v${v} (kept v${prev.version}/ for rollback)`);
+    }
+    else {
+        console.log(`↺ ${payload.name} active version set to v${v} (was v${prev.version})`);
+    }
     const files = [
         ...Object.keys(payload.artifacts),
         "design-system.json",
         "GUIDE.md",
-        ".lock",
     ];
-    console.log(`✓ ${payload.name} v${payload.version} → _synthesisui/ds/${payload.slug}/`);
-    console.log(`  ${files.join(", ")}`);
-    console.log(`  CLAUDE.md ${claudeMd.created ? "criado" : "atualizado"} (${claudeMd.count} sistema(s) instalado(s))`);
+    console.log(`  v${v}/: ${files.join(", ")}`);
+    console.log(`  CLAUDE.md ${claudeMd.created ? "created" : "updated"} (${claudeMd.count} system(s) installed)`);
     console.log("");
-    console.log("Próximos passos:");
-    console.log(`  • @import "_synthesisui/ds/${payload.slug}/tokens.css" no seu CSS global`);
-    console.log(`  • escope sua UI com data-ds="${payload.slug}"`);
-    console.log(`  • detalhes e regras em _synthesisui/ds/${payload.slug}/GUIDE.md`);
+    console.log("Next steps:");
+    console.log(`  • @import "_synthesisui/ds/${payload.slug}/tokens.css" in your global CSS (stable path)`);
+    console.log(`  • scope your UI with data-ds="${payload.slug}"`);
+    console.log(`  • details and rules in _synthesisui/ds/${payload.slug}/v${v}/GUIDE.md`);
 }

package/dist/commands/list.js

@@ -1,17 +1,17 @@
 import { resolveRegistry } from "../config.js";
 import { fetchList } from "../registry.js";
-/** Lista os design systems publicados disponíveis no registry. */
+/** Lists the published design systems available in the registry. */
 export async function list(opts) {
     const base = resolveRegistry(opts.registry);
     const systems = await fetchList(base);
     if (systems.length === 0) {
-        console.log(`Nenhum design system publicado em ${base}.`);
+        console.log(`No design systems published at ${base}.`);
         return;
     }
-    console.log(`Design systems disponíveis (${base}):\n`);
+    console.log(`Available design systems (${base}):\n`);
     const width = Math.max(...systems.map((s) => s.slug.length));
     for (const s of systems) {
         console.log(`  ${s.slug.padEnd(width)}  ${s.name}  (v${s.version})`);
     }
-    console.log(`\nTraga um com:  synthesisui add <slug>`);
+    console.log(`\nBring one in with:  synthesisui add <slug>`);
 }

package/dist/commands/login.js

@@ -4,7 +4,7 @@ import { RegistryError } from "../registry.js";
 const CLIENT_ID = "synthesisui-cli";
 const GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Tenta abrir o browser no SO; silencioso se não der. */
+/** Tries to open the OS browser; silent if it fails. */
 function openBrowser(url) {
     const [cmd, args] = process.platform === "darwin"
         ? ["open", [url]]
@@ -20,10 +20,10 @@ function openBrowser(url) {
         child.unref();
     }
     catch {
-        // sem browser disponível — o usuário abre manualmente
+        // no browser available — the user opens it manually
     }
 }
-/** Device authorization (RFC 8628): abre o browser, espera a aprovação. */
+/** Device authorization (RFC 8628): opens the browser, waits for approval. */
 export async function login(opts) {
     const base = resolveRegistry(opts.registry);
     const codeRes = await fetch(`${base}/api/auth/device/code`, {
@@ -32,20 +32,20 @@ export async function login(opts) {
         body: JSON.stringify({ client_id: CLIENT_ID }),
     }).catch(() => null);
     if (!codeRes || !codeRes.ok) {
-        throw new RegistryError(`Não consegui iniciar o login em ${base}` +
+        throw new RegistryError(`Could not start login at ${base}` +
             (codeRes
                 ? ` (HTTP ${codeRes.status}).`
-                : ". Confira a URL e a conexão."));
+                : ". Check the URL and your connection."));
     }
     const code = (await codeRes.json());
-    console.log("\nPara conectar o CLI à sua conta:");
-    console.log(`  1. abra: ${code.verification_uri}`);
-    console.log(`  2. confirme o código: ${code.user_code}\n`);
-    console.log("(tentando abrir o navegador…)");
+    console.log("\nTo connect the CLI to your account:");
+    console.log(`  1. open: ${code.verification_uri}`);
+    console.log(`  2. confirm the code: ${code.user_code}\n`);
+    console.log("(trying to open the browser…)");
     openBrowser(code.verification_uri_complete);
     let interval = (code.interval || 5) * 1000;
     const deadline = Date.now() + (code.expires_in || 900) * 1000;
-    process.stdout.write("aguardando aprovação");
+    process.stdout.write("waiting for approval");
     while (Date.now() < deadline) {
         await sleep(interval);
         process.stdout.write(".");
@@ -63,7 +63,7 @@ export async function login(opts) {
             : {};
         if (tokenRes?.ok && typeof data.access_token === "string") {
             await writeToken(data.access_token, base);
-            console.log("\n✓ Login concluído. Token salvo em ~/.synthesisui/credentials.json");
+            console.log("\n✓ Login complete. Token saved to ~/.synthesisui/credentials.json");
             return;
         }
         const err = data.error;
@@ -73,7 +73,7 @@ export async function login(opts) {
             interval += 5000;
             continue;
         }
-        throw new RegistryError(`\nLogin falhou: ${data.error_description ?? err ?? tokenRes?.status ?? "erro desconhecido"}`);
+        throw new RegistryError(`\nLogin failed: ${data.error_description ?? err ?? tokenRes?.status ?? "unknown error"}`);
     }
-    throw new RegistryError("\nO código expirou antes da aprovação. Rode `synthesisui login` de novo.");
+    throw new RegistryError("\nThe code expired before approval. Run `synthesisui login` again.");
 }

package/dist/config.js

@@ -2,20 +2,20 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 /**
- * Registry padrão (domínio canônico de produção). Sobrescrevível por
- * `--registry <url>` ou `SYNTHESISUI_REGISTRY_URL` (ex.: http://localhost:3000
- * em dev).
+ * Default registry (canonical production domain). Overridable via
+ * `--registry <url>` or `SYNTHESISUI_REGISTRY_URL` (e.g. http://localhost:3000
+ * in dev).
  */
 export const DEFAULT_REGISTRY = "https://www.synthesisui.com";
 export function resolveRegistry(flag) {
     const base = flag || process.env.SYNTHESISUI_REGISTRY_URL || DEFAULT_REGISTRY;
-    return base.replace(/\/+$/, ""); // sem barra final
+    return base.replace(/\/+$/, ""); // no trailing slash
 }
-/** Onde o token do device-flow (passo 3) vive — por máquina, na home. */
+/** Where the device-flow token lives — per machine, in the home dir. */
 export const credentialsPath = join(homedir(), ".synthesisui", "credentials.json");
 /**
- * Lê o token salvo, se existir. Hoje opcional (portão aberto); o device-flow
- * (passo 3) é quem vai gravá-lo. Mandamos como Bearer quando presente.
+ * Reads the saved token, if any. Optional for now (open gate); the device-flow
+ * is what writes it. Sent as a Bearer header when present.
  */
 export async function readToken() {
     try {
@@ -27,7 +27,7 @@ export async function readToken() {
         return null;
     }
 }
-/** Persiste o token do device-flow (chmod 600, dir só do usuário). */
+/** Persists the device-flow token (chmod 600, user-only dir). */
 export async function writeToken(token, registry) {
     await mkdir(dirname(credentialsPath), { recursive: true, mode: 0o700 });
     const payload = { token, registry, savedAt: new Date().toISOString() };

package/dist/guide.js

@@ -1,10 +1,10 @@
 const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-const list = (items) => items.length ? items.map((i) => `\`${i}\``).join(", ") : "_(nenhum)_";
+const list = (items) => items.length ? items.map((i) => `\`${i}\``).join(", ") : "_(none)_";
 /**
- * Gera o GUIDE.md — instruções *para o agente* sobre como construir
- * componentes seguindo o DS. É a peça que faz "com claude-code eu crio os
- * componentes" funcionar: não basta os tokens, o agente precisa das regras
- * e do vocabulário real (nomes de tokens semânticos e de recipes).
+ * Builds GUIDE.md — instructions *for the agent* on how to build components
+ * that follow the design system. This is the piece that makes "I create the
+ * components with claude-code" work: the tokens alone are not enough, the agent
+ * needs the rules and the real vocabulary (semantic token names and recipes).
  */
 export function buildGuide(payload) {
     const { document: doc, slug, name, version } = payload;
@@ -13,13 +13,14 @@ export function buildGuide(payload) {
     const hasAlt = foundations.color.semanticAlt &&
         Object.keys(foundations.color.semanticAlt).length > 0;
     const altScheme = meta.scheme === "light" ? "dark" : "light";
+    const hasTailwind = "theme.css" in payload.artifacts;
     const componentLines = Object.entries(components).map(([cname, recipe]) => {
         const cls = `.ds-${kebab(cname)}`;
         const axes = Object.entries(recipe.variants).map(([axis, opts]) => {
             const options = Object.keys(opts);
             return `\`data-${kebab(axis)}="${options.join("|")}"\``;
         });
-        const variantsText = axes.length ? ` — variantes: ${axes.join(", ")}` : "";
+        const variantsText = axes.length ? ` — variants: ${axes.join(", ")}` : "";
         return `- **${cname}** (\`${cls}\`)${variantsText}\n  ${recipe.description}`;
     });
     const artifactList = Object.keys(payload.artifacts)
@@ -27,81 +28,120 @@ export function buildGuide(payload) {
         .join(", ");
     return `# Design System: ${name}
 
-> Gerado por \`synthesisui add ${slug}\` (v${version}). **Não edite à mão** —
-> rode \`synthesisui add ${slug}\` de novo para atualizar.
+> Generated by \`synthesisui add ${slug}\` (v${version}). **Do not edit by hand** —
+> run \`synthesisui add ${slug}\` again to update.
 
 ${meta.tagline}
 
 **Mood:** ${meta.mood.join(" · ")}
-**Modo padrão:** ${meta.scheme}${hasAlt ? ` (suporta toggle para ${altScheme})` : ""}
-${meta.sourceUrl ? `**Releitura de:** ${meta.sourceUrl}` : "**Sistema autoral.**"}
+**Default scheme:** ${meta.scheme}${hasAlt ? ` (supports a toggle to ${altScheme})` : ""}
+${meta.sourceUrl ? `**Reinterpretation of:** ${meta.sourceUrl}` : "**Original system.**"}
 
 ${meta.narrative}
 
 ---
 
-## Como aplicar
+## How to apply
 
-1. Importe os tokens uma vez no CSS global do projeto:
+1. Import the tokens once in your project's global CSS:
    \`\`\`css
    @import "./_synthesisui/ds/${slug}/tokens.css";
    \`\`\`
-   (ajuste o caminho relativo conforme a localização do seu CSS.)
+   (adjust the relative path to where your CSS lives.)
 
-2. Envolva a árvore que deve usar o sistema com o atributo de escopo:
+2. Wrap the tree that should use the system with the scope attribute:
    \`\`\`html
-   <div data-ds="${slug}">…sua UI aqui…</div>
+   <div data-ds="${slug}">…your UI here…</div>
    \`\`\`
-   Todas as custom properties \`--ds-*\` e as classes \`.ds-*\` só valem dentro desse escopo.
+   All \`--ds-*\` custom properties and \`.ds-*\` classes only apply inside that scope.
 ${hasAlt
         ? `
-3. Light/dark: um ancestral com \`data-scheme="${altScheme}"\` troca os papéis neutros para o modo oposto.
+3. Light/dark: an ancestor with \`data-scheme="${altScheme}"\` switches the neutral roles to the opposite mode.
    \`\`\`html
    <div data-scheme="${altScheme}"><div data-ds="${slug}">…</div></div>
    \`\`\`
+`
+        : ""}${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-*\`, \`ease-*\`.
+
+**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.
+
+\`\`\`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>
+</main>
+
+// ❌ avoid — inline styles with raw var() when a utility exists
+<main style={{ background: "var(--ds-color-semantic-canvas)", padding: "var(--ds-spacing-2xl)" }}>
+\`\`\`
+
+---
 `
         : ""}
-Artefatos disponíveis em \`_synthesisui/ds/${slug}/\`: ${artifactList}, \`design-system.json\` (verdade canônica), \`GUIDE.md\` (este arquivo).
+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},
+\`design-system.json\` (canonical source of truth), \`GUIDE.md\` (this file) — live in
+\`_synthesisui/ds/${slug}/v${version}/\`.
 
 ---
 
-## Regras (siga ao criar componentes)
-
-- **Use SEMPRE tokens semânticos**, nunca valores crus nem primitivas diretas.
-  Cor: \`var(--ds-color-semantic-<papel>)\`. Os papéis são: ${list(semanticRoles)}.
-- Primitivas (\`--ds-color-<paleta>-<step>\`) existem mas **não** devem ser referenciadas direto —
-  elas alimentam os papéis semânticos.
-- Espaçamento → \`var(--ds-spacing-<key>)\`: ${list(Object.keys(foundations.spacing))}.
-- Raio → \`var(--ds-radius-<key>)\`: ${list(Object.keys(foundations.radius))}.
-- Sombra → \`var(--ds-shadow-<key>)\`: ${list(Object.keys(foundations.shadow))}.
-- Tipografia: famílias \`--ds-typography-families-{display,body,mono}\` (${foundations.typography.families.display}, ${foundations.typography.families.body}, ${foundations.typography.families.mono});
-  escala \`--ds-typography-scale-<key>-font-size\` etc.: ${list(Object.keys(foundations.typography.scale))}.
-- Motion: durações \`--ds-motion-durations-<key>\` (${list(Object.keys(motion.durations))}) e
+## Rules (follow them when creating components)
+${hasTailwind
+        ? `
+- **Styling mechanism:** prefer Tailwind utilities backed by the DS (\`bg-primary\`, \`p-md\`,
+  \`font-display\`, …) 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.`
+        : ""}
+- **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.
+- 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});
+  scale \`--ds-typography-scale-<key>-font-size\` etc.: ${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))}).
-- Ao **criar um componente novo** que o DS ainda não cobre: componha a partir desses tokens
-  semânticos para herdar a identidade do sistema; não invente cores/medidas fora da escala.
+- 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.
 
 ---
 
-## Onde testar/preview
+## Where to preview
 
-**Preview isolado, nunca em página real.** Ao criar ou demonstrar um componente, gere uma página de
-amostra dedicada — \`app/synthesisui-samples/<componente>/\` no Next.js App Router (ou a rota/pasta de
-samples equivalente na stack do projeto). **Não** aplique o componente a páginas reais de produção
-(home, layout, rotas existentes) a menos que seja explicitamente pedido. As amostras deixam revisar o
-componente no contexto do design system sem tocar no app.
+**Preview in isolation, never on a real page.** When creating or demoing a component, generate a
+dedicated sample page — \`app/synthesisui-samples/<component>/\` in the Next.js App Router (or the
+equivalent samples route/folder in the project's stack). **Do not** apply the component to real
+production pages (home, layout, existing routes) unless explicitly asked. Samples let you review the
+component in the context of the design system without touching the app.
 
 ---
 
-## Componentes prontos
+## Ready-made components
 
-Cada recipe vira uma classe \`.ds-<nome>\` (dentro do escopo \`[data-ds="${slug}"]\`).
-Variantes são atributos \`data-<eixo>="<opção>"\`; estados (hover/focus/active/disabled) já vêm no CSS.
+Each recipe becomes a \`.ds-<name>\` class (inside the \`[data-ds="${slug}"]\` scope).
+Variants are \`data-<axis>="<option>"\` attributes; states (hover/focus/active/disabled) ship in the CSS.
 
 ${componentLines.join("\n\n")}
 
 ---
 
-_Verdade canônica completa (incluindo valores e keyframes) em \`design-system.json\`._
+_Full canonical source of truth (including values and keyframes) in \`design-system.json\`._
 `;
 }

package/dist/index.js

@@ -3,25 +3,27 @@ import { add } from "./commands/add.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
 import { RegistryError } from "./registry.js";
-const HELP = `synthesisui — traz design systems do SynthesisUI para o seu projeto
+const HELP = `synthesisui — bring SynthesisUI design systems into your project
 
-Uso:
-  synthesisui login [opções]           conecta o CLI à sua conta (device-flow)
-  synthesisui list [opções]            lista os DSs publicados
-  synthesisui add <slug> [opções]      materializa um DS em _synthesisui/ds/<slug>/
+Usage:
+  synthesisui login [options]          connect the CLI to your account (device-flow)
+  synthesisui list [options]           list the published design systems
+  synthesisui add <slug> [options]     materialize a DS into _synthesisui/ds/<slug>/
 
-Opções:
-  --registry <url>   URL do registry (ou env SYNTHESISUI_REGISTRY_URL)
-  --dir <path>       raiz do projeto consumidor (default: diretório atual)
-  -h, --help         esta ajuda
+Options:
+  --registry <url>   registry URL (or env SYNTHESISUI_REGISTRY_URL)
+  --dir <path>       consumer project root (default: current directory)
+  --version <n>      install a specific version (default: latest)
+  -h, --help         this help
 
-Exemplos:
+Examples:
   synthesisui login
   synthesisui list
   synthesisui add halogen
+  synthesisui add halogen --version 3
   synthesisui add halogen --registry http://localhost:3737
 `;
-/** Extrai `--flag value` simples e os posicionais restantes. */
+/** Extracts simple `--flag value` pairs and the remaining positionals. */
 function parseFlags(argv) {
     const positionals = [];
     const flags = {};
@@ -63,25 +65,34 @@ async function main() {
         case "add": {
             const slug = args[0];
             if (!slug) {
-                console.error("erro: informe o slug — `synthesisui add <slug>`");
+                console.error("error: provide the slug — `synthesisui add <slug>`");
                 process.exitCode = 1;
                 return;
             }
-            await add(slug, { registry, dir });
+            let version;
+            if (typeof flags.version === "string") {
+                version = Number.parseInt(flags.version.replace(/^v/i, ""), 10);
+                if (!Number.isInteger(version) || version < 1) {
+                    console.error(`error: invalid --version "${flags.version}" — use an integer ≥ 1`);
+                    process.exitCode = 1;
+                    return;
+                }
+            }
+            await add(slug, { registry, dir, version });
             break;
         }
         case "login":
             await login({ registry });
             break;
         default:
-            console.error(`comando desconhecido: "${command}"\n`);
+            console.error(`unknown command: "${command}"\n`);
             console.log(HELP);
             process.exitCode = 1;
     }
 }
 main().catch((err) => {
     if (err instanceof RegistryError) {
-        console.error(`erro: ${err.message}`);
+        console.error(`error: ${err.message}`);
     }
     else {
         console.error(err);

package/dist/registry.js

@@ -11,29 +11,34 @@ async function request(url) {
         res = await fetch(url, { headers: await authHeaders() });
     }
     catch {
-        throw new RegistryError(`Não consegui falar com o registry em ${url}. ` +
-            `Confira a URL (--registry / SYNTHESISUI_REGISTRY_URL) e a conexão.`);
+        throw new RegistryError(`Could not reach the registry at ${url}. ` +
+            `Check the URL (--registry / SYNTHESISUI_REGISTRY_URL) and your connection.`);
     }
     return res;
 }
-/** Lista os design systems publicados disponíveis. */
+/** Lists the available published design systems. */
 export async function fetchList(base) {
     const res = await request(`${base}/api/registry/ds`);
     if (!res.ok) {
-        throw new RegistryError(`Registry respondeu ${res.status} ao listar.`);
+        throw new RegistryError(`Registry responded ${res.status} while listing.`);
     }
     const body = (await res.json());
     return body.designSystems ?? [];
 }
-/** Busca um DS publicado já compilado (document + artifacts). */
-export async function fetchDesignSystem(base, slug) {
-    const res = await request(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
+/**
+ * Fetches a published DS already compiled (document + artifacts). Without
+ * `version` it returns the latest; with `version` it returns that one.
+ */
+export async function fetchDesignSystem(base, slug, version) {
+    const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
+    if (version != null)
+        url.searchParams.set("version", String(version));
+    const res = await request(url.toString());
     if (res.status === 404) {
-        throw new RegistryError(`Nenhum design system publicado com slug "${slug}". ` +
-            `Rode \`synthesisui list\` para ver os disponíveis.`);
+        throw new RegistryError(`No design system published with slug "${slug}"${version != null ? ` at version v${version}` : ""}. Run \`synthesisui list\` to see what's available.`);
     }
     if (!res.ok) {
-        throw new RegistryError(`Registry respondeu ${res.status} ao buscar "${slug}".`);
+        throw new RegistryError(`Registry responded ${res.status} while fetching "${slug}".`);
     }
     return (await res.json());
 }

package/dist/types.js

@@ -1,6 +1,6 @@
 /**
- * Espelho mínimo do contrato do registry — o CLI é standalone e NÃO importa
- * `@synthesisui-hub/ds-contracts` (só consome o JSON do endpoint). Tipamos
- * apenas o que o CLI lê para gerar o GUIDE.md e o .lock.
+ * Minimal mirror of the registry contract — the CLI is standalone and does NOT
+ * import `@synthesisui-hub/ds-contracts` (it only consumes the endpoint JSON).
+ * We type only what the CLI reads to generate GUIDE.md and the .lock.
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Traz design systems do SynthesisUI para qualquer projeto (materializa em _local/ds/).",
   "type": "module",
   "bin": {