synthesisui 0.1.21 → 0.1.23

package/dist/commands/init.js

@@ -2,7 +2,7 @@ import { DEFAULT_CONFIG, writeProjectConfig } from "../config.js";
 import { add } from "./add.js";
 /**
  * Bootstraps a project for SynthesisUI: writes `_synthesisui/config.json`
- * (where `page` materializes pages, where components live, which framework to
+ * (where `template` materializes pages, where components live, which framework to
  * target) and - with `--ds <slug>` - immediately brings that system in, so the
  * project lands with tokens, philosophy, rules and a CLAUDE.md in one step.
  * Committable; safe to re-run.
@@ -30,5 +30,5 @@ export async function init(opts) {
     console.log("");
     console.log("Next steps:");
     console.log("  • synthesisui add <slug>              bring a design system in");
-    console.log("  • synthesisui page <slug> <template>  materialize a full page");
+    console.log("  • synthesisui template <slug> <name>  materialize a full page");
 }

package/dist/commands/template.js

@@ -0,0 +1,42 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { readProjectConfig, resolveRegistry } from "../config.js";
+import { fetchTemplate } from "../registry.js";
+/**
+ * Materializes a whole page from a DS template into the project (hybrid
+ * codegen-first): the server codegens deterministic files, we write them, and
+ * the agent refines them in place. The page uses the DS's `.ds-*` classes +
+ * path classes; the co-located CSS (Next target) carries the responsive media
+ * queries + the CSS-only hamburger, so it re-vests once `tokens.css` is in.
+ */
+export async function template(slug, name, opts) {
+    const base = resolveRegistry(opts.registry);
+    const root = opts.dir ?? process.cwd();
+    const config = await readProjectConfig(root);
+    const target = opts.target === "general" || opts.target === "next"
+        ? opts.target
+        : config.target;
+    console.log(`→ generating "${name}" from "${slug}" (${target}) …`);
+    const generated = await fetchTemplate(base, slug, name, target, opts.version);
+    // --out targets the page (1st file); sibling files (e.g. the CSS) land in the
+    // same directory. Without --out, everything goes under <pagesDir>.
+    const [pageFile, ...siblings] = generated.files;
+    const pageRel = opts.out ?? join(config.pagesDir, pageFile.filename);
+    const pageDir = dirname(join(root, pageRel));
+    await mkdir(pageDir, { recursive: true });
+    await writeFile(join(root, pageRel), pageFile.code, "utf8");
+    console.log(`✓ wrote ${pageRel}  (${slug} v${generated.version})`);
+    for (const f of siblings) {
+        const rel = opts.out
+            ? join(dirname(pageRel), f.filename)
+            : join(config.pagesDir, f.filename);
+        await writeFile(join(root, rel), f.code, "utf8");
+        console.log(`✓ wrote ${rel}`);
+    }
+    console.log("");
+    console.log("Next steps:");
+    console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
+    console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
+    console.log("  • refine the file: wire real data, split into components, swap placeholders");
+    console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
+}

package/dist/guide.js

@@ -84,6 +84,32 @@ its typographic identity. Load them once (any one approach):
 - **Next.js** (\`next/font/google\`), **Fontsource**, or self-hosted \`@font-face\` work too - just
   register the families above. If a family isn't on Google Fonts, self-host it.
 
+---
+`
+        : "";
+    // Libraries the system references but doesn't bundle - the agent should
+    // install them when it actually renders icons/charts (INS-19).
+    const iconLibraries = doc.icons?.libraries ?? [];
+    const hasCharts = !!doc.charts && Object.keys(doc.charts).length > 0;
+    const depLines = [
+        iconLibraries.includes("lucide")
+            ? "- **Icons** - components reference Lucide icon names. Run `npm i lucide-react` " +
+                "(or swap in your own icon set) to render them."
+            : "",
+        hasCharts
+            ? "- **Charts** - charts are themed through your series tokens, but you bring the " +
+                "renderer. Run `npm i recharts` (the gallery uses Recharts)."
+            : "",
+    ].filter(Boolean);
+    const depsSection = depLines.length
+        ? `
+## Dependencies
+
+Beyond loading the fonts above, the system references libraries it doesn't bundle - install them
+when you actually render that UI:
+
+${depLines.join("\n")}
+
 ---
 `
         : "";
@@ -109,8 +135,8 @@ This system ships whole-page templates: ${layoutNames.map((n) => `\`${n}\``).joi
 
 Materialize one as a real file:
 \`\`\`bash
-synthesisui page ${slug} ${layoutNames[0]}                 # Next .tsx + .css (default)
-synthesisui page ${slug} ${layoutNames[0]} --target general  # single self-contained HTML
+synthesisui template ${slug} ${layoutNames[0]}                 # Next .tsx + .css (default)
+synthesisui template ${slug} ${layoutNames[0]} --target general  # single self-contained HTML
 \`\`\`
 It writes a **deterministic scaffold**: the page uses this DS's \`.ds-*\` recipe classes + layout
 path-classes, paired with a co-located scoped CSS (Next target) that carries the **responsive** media
@@ -186,7 +212,7 @@ ${hasAlt
    root.toggleAttribute("data-scheme"); // present = ${altScheme}, absent = ${meta.scheme}
    \`\`\`
 `
-        : ""}${fontsSection}${hasTailwind
+        : ""}${fontsSection}${depsSection}${hasTailwind
         ? `
 ## Styling with Tailwind v4 (preferred in this project)
 

package/dist/index.js

@@ -5,7 +5,7 @@ import { generate } from "./commands/generate.js";
 import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
 import { login } from "./commands/login.js";
-import { page } from "./commands/page.js";
+import { template } from "./commands/template.js";
 import { use } from "./commands/use.js";
 import { RegistryError } from "./registry.js";
 const HELP = `synthesisui - bring SynthesisUI design systems into your project
@@ -15,7 +15,7 @@ Usage:
   synthesisui init [options]               write _synthesisui/config.json (target, dirs); --ds to bring one in
   synthesisui list [options]               list the published design systems
   synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
-  synthesisui page <slug> <template>       materialize a whole page from a DS template
+  synthesisui template <slug> <name>       materialize a whole page from a DS template
   synthesisui use <slug> "<intent>"        print a ready-to-paste agent prompt to build/modify on-system
   synthesisui advise "<value prop>"        engagement-pattern proposals for this project (login required)
   synthesisui generate "<desc>"            generate a token-only component recipe for your DS (login required)
@@ -26,10 +26,10 @@ Options:
   --version <n>      install a specific version (default: latest)
   --ds <slug>        init: bring this DS in right away · generate: target DS (default: installed)
   --name <name>      preferred component name for generate
-  --target <t>       page/init target: next | general (default: next)
+  --target <t>       template/init target: next | general (default: next)
   --pages-dir <dir>  init: folder for generated pages (default: app)
   --components-dir <dir>  init: folder where components live (default: components)
-  --out <path>       output path for the generated page (default: <pagesDir>/<file>)
+  --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
 
 Examples:
@@ -39,8 +39,8 @@ Examples:
   synthesisui list
   synthesisui add halogen
   synthesisui add halogen --version 3
-  synthesisui page halogen dashboard-sidebar
-  synthesisui page halogen landing --out app/page.tsx
+  synthesisui template halogen dashboard-sidebar
+  synthesisui template halogen landing --out app/page.tsx
   synthesisui use halogen "a pricing section with three tiers and a highlighted plan"
   synthesisui use halogen "make the card shadow softer in components/StatCard.tsx"
   synthesisui advise "habit-building app for tracking personal finances"
@@ -125,11 +125,17 @@ async function main() {
             await init({ dir, registry, target, pagesDir, componentsDir, ds });
             break;
         }
-        case "page": {
+        // `page` is the legacy alias (renamed to `template`); it still works so
+        // GUIDE.md files materialized before the rename don't break.
+        case "page":
+        case "template": {
+            if (command === "page") {
+                console.error("note: `synthesisui page` was renamed to `synthesisui template` - the old name still works for now.");
+            }
             const slug = args[0];
-            const template = args[1];
-            if (!slug || !template) {
-                console.error("error: provide slug and template - `synthesisui page <slug> <template>`");
+            const name = args[1];
+            if (!slug || !name) {
+                console.error("error: provide slug and template name - `synthesisui template <slug> <name>`");
                 process.exitCode = 1;
                 return;
             }
@@ -144,7 +150,7 @@ async function main() {
             }
             const target = typeof flags.target === "string" ? flags.target : undefined;
             const out = typeof flags.out === "string" ? flags.out : undefined;
-            await page(slug, template, { registry, dir, out, target, version });
+            await template(slug, name, { registry, dir, out, target, version });
             break;
         }
         case "use": {

package/dist/registry.js

@@ -43,12 +43,12 @@ export async function fetchDesignSystem(base, slug, version) {
     return (await res.json());
 }
 /**
- * Fetches a whole page generated from a DS template (`?page=&target=`). The
+ * Fetches a whole page generated from a DS template (`?template=&target=`). The
  * server codegens it from `document.layouts[<template>]`; the CLI just writes it.
  */
-export async function fetchPage(base, slug, template, target, version) {
+export async function fetchTemplate(base, slug, template, target, version) {
     const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
-    url.searchParams.set("page", template);
+    url.searchParams.set("template", template);
     url.searchParams.set("target", target);
     if (version != null)
         url.searchParams.set("version", String(version));

package/package.json

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