npm - synthesisui - Versions diffs - 0.1.23 → 0.2.0 - Mend

synthesisui 0.1.23 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/commands/component.js +70 -0
package/dist/commands/init.js +2 -0
package/dist/component-codegen.js +382 -0
package/dist/config.js +2 -0
package/dist/guide.js +12 -0
package/dist/index.js +40 -1
package/dist/registry.js +21 -0
package/package.json +1 -1

package/dist/commands/component.js ADDED Viewed

@@ -0,0 +1,70 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { generateComponentFiles } from "../component-codegen.js";
+import { readProjectConfig, resolveRegistry } from "../config.js";
+import { fetchComponent, RegistryError } from "../registry.js";
+/** Slugs/names are kebab-case by contract; reject anything else before it ever
+ *  reaches a filesystem path (defense-in-depth against `../` traversal). */
+const SAFE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Brings ONE component from a design system into the project (granular "bring
+ * specific", INS-18 fatia 3):
+ *
+ * 1. Artifacts (source of truth) → `_synthesisui/ds/<slug>/components/`:
+ *    the recipe (.json, for agents/tooling) + compiled CSS (.css).
+ * 2. YOUR component (unless --artifacts-only, target "next") →
+ *    `<componentsDir>/<name>/` from `_synthesisui/config.json`: a real
+ *    `export function <Pascal>()` with variants as typed props, in the
+ *    project's chosen flavor (`styles: "css" | "tailwind"`).
+ *
+ * The component's styles reference the DS tokens, so the system itself must be
+ * installed (`synthesisui add <slug>`) for `tokens.css`/`theme.css` to resolve.
+ */
+export async function component(slug, name, opts) {
+    const base = resolveRegistry(opts.registry);
+    const root = opts.dir ?? process.cwd();
+    if (!SAFE_NAME.test(slug)) {
+        throw new RegistryError(`Invalid slug "${slug}".`);
+    }
+    console.log(`→ fetching "${name}" from "${slug}" …`);
+    const res = await fetchComponent(base, slug, name, opts.version);
+    // The server should only ever return a kebab-case name, but never trust a
+    // network value as a path segment.
+    if (!SAFE_NAME.test(res.name)) {
+        throw new RegistryError(`Registry returned an unsafe component name.`);
+    }
+    const dir = join(root, "_synthesisui", "ds", slug, "components");
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, `${res.name}.json`), `${JSON.stringify(res.recipe, null, 2)}\n`, "utf8");
+    await writeFile(join(dir, `${res.name}.css`), `${res.css}\n`, "utf8");
+    console.log(`✓ ${res.name} → _synthesisui/ds/${slug}/components/${res.name}.{json,css}  (${slug} v${res.version})`);
+    // 2. YOUR component - a real, importable `export function <Pascal>()` in the
+    //    project's flavor (config: styles css|tailwind), under componentsDir.
+    const config = await readProjectConfig(root);
+    if (!opts.artifactsOnly && config.target === "next") {
+        const compDir = join(root, config.componentsDir, res.name);
+        await mkdir(compDir, { recursive: true });
+        const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles);
+        for (const file of files) {
+            await writeFile(join(compDir, file.filename), file.code, "utf8");
+        }
+        const names = files.map((f) => f.filename).join(", ");
+        console.log(`✓ ${config.componentsDir}/${res.name}/ → ${names}  (styles: ${config.styles})`);
+    }
+    console.log("");
+    console.log("Use it:");
+    console.log(`  • once per app: synthesisui add ${slug} (tokens.css${config.styles === "tailwind" ? " + theme.css" : ""}), import it globally,`);
+    console.log(`    and put data-ds="${slug}" on a root element (e.g. <body data-ds="${slug}">)`);
+    if (!opts.artifactsOnly && config.target === "next") {
+        const pascalName = res.name
+            .split(/[^a-zA-Z0-9]+/)
+            .filter(Boolean)
+            .map((p) => p[0].toUpperCase() + p.slice(1))
+            .join("");
+        console.log(`  • import { ${pascalName} } from "./${config.componentsDir}/${res.name}" and render <${pascalName} />`);
+        console.log(`  • or ask your agent: "use the ${pascalName} component from ${config.componentsDir}/${res.name} (SynthesisUI ${slug})"`);
+    }
+    else {
+        console.log(`  • @import "_synthesisui/ds/${slug}/components/${res.name}.css" and use <div class="ds-${res.name}">…</div>`);
+    }
+}

package/dist/commands/init.js CHANGED Viewed

@@ -14,12 +14,14 @@ export async function init(opts) {
         target,
         pagesDir: opts.pagesDir ?? (target === "next" ? "app" : DEFAULT_CONFIG.pagesDir),
         componentsDir: opts.componentsDir ?? DEFAULT_CONFIG.componentsDir,
+        styles: opts.styles === "tailwind" ? "tailwind" : "css",
     };
     await writeProjectConfig(root, config);
     console.log("✓ wrote _synthesisui/config.json");
     console.log(`  target:        ${config.target}`);
     console.log(`  pagesDir:      ${config.pagesDir}`);
     console.log(`  componentsDir: ${config.componentsDir}`);
+    console.log(`  styles:        ${config.styles}`);
     // --ds bootstraps the project with a system in one step (tokens + philosophy
     // + rules + CLAUDE.md all arrive via `add`).
     if (opts.ds) {

package/dist/component-codegen.js ADDED Viewed

@@ -0,0 +1,382 @@
+const kebab = (v) => v.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+const pascal = (name) => name
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((p) => p[0].toUpperCase() + p.slice(1))
+    .join("");
+const camel = (name) => {
+    const p = pascal(name);
+    return p[0].toLowerCase() + p.slice(1);
+};
+/** Intrinsic element + extra attrs per component, chosen like the platform
+ *  renderer does (name first, then preview.kind). Fallback: div + children. */
+function elementFor(name, recipe) {
+    const byName = {
+        input: { tag: "input" },
+        textarea: { tag: "textarea" },
+        select: { tag: "select" },
+        checkbox: { tag: "input", attrs: ' type="checkbox"' },
+        radio: { tag: "input", attrs: ' type="radio"' },
+        switch: { tag: "input", attrs: ' type="checkbox" role="switch"' },
+        slider: { tag: "input", attrs: ' type="range"' },
+        button: { tag: "button", attrs: ' type="button"' },
+        "icon-button": { tag: "button", attrs: ' type="button"' },
+        badge: { tag: "span" },
+        tag: { tag: "span" },
+        avatar: { tag: "span" },
+        divider: { tag: "hr" },
+        link: { tag: "a" },
+    };
+    const hit = byName[name] ??
+        (recipe.preview?.kind === "action"
+            ? { tag: "button", attrs: ' type="button"' }
+            : undefined);
+    const tag = hit?.tag ?? "div";
+    return {
+        tag,
+        attrs: hit?.attrs ?? "",
+        voidEl: tag === "input" || tag === "hr",
+    };
+}
+/** Variant axes → typed props. An axis whose options ⊆ {true,false} is a
+ *  boolean prop; empty axes (no visual effect) are skipped. */
+function axesOf(variants) {
+    const axes = [];
+    for (const [axis, options] of Object.entries(variants ?? {})) {
+        const keys = Object.keys(options).filter((k) => Object.keys(options[k] ?? {}).length > 0);
+        if (keys.length === 0)
+            continue;
+        axes.push({
+            key: axis,
+            prop: camel(axis),
+            attr: kebab(axis),
+            boolean: keys.every((k) => k === "true" || k === "false"),
+            styledFalse: keys.includes("false"),
+            options: keys,
+        });
+    }
+    return axes;
+}
+function propsType(axes, tag) {
+    const extras = axes.map((a) => a.boolean
+        ? `  ${a.prop}?: boolean;`
+        : `  ${a.prop}?: ${a.options.map((o) => `"${o}"`).join(" | ")};`);
+    if (extras.length === 0)
+        return `ComponentPropsWithoutRef<"${tag}">`;
+    return `ComponentPropsWithoutRef<"${tag}"> & {\n${extras.join("\n")}\n}`;
+}
+function dataAttrLines(axes) {
+    return axes
+        .map((a) => a.boolean
+        ? a.styledFalse
+            ? `      data-${a.attr}={${a.prop} ? "true" : "false"}`
+            : `      data-${a.attr}={${a.prop} ? "true" : undefined}`
+        : `      data-${a.attr}={${a.prop}}`)
+        .join("\n");
+}
+// ── Tailwind translation ─────────────────────────────────────────────────────
+/**
+ * Namespace-aware token key: returns the utility suffix ONLY when the ref
+ * lives in a namespace the `theme.css` @theme adapter actually maps
+ * (semantic/series colors, spacing, radius, shadow, families, weights, type
+ * scale). Anything else (e.g. color primitives) must use the --ds-* fallback.
+ */
+const nsKey = (v, ns) => {
+    const m = v.match(new RegExp(`^\\{${ns.replace(/\./g, "\\.")}\\.([a-zA-Z0-9-]+)\\}$`));
+    return m ? kebab(m[1]) : null;
+};
+/** Color refs the adapter maps: semantic → <role>, series → series-<n>. */
+const colorKey = (v) => {
+    const semantic = nsKey(v, "color.semantic");
+    if (semantic)
+        return semantic;
+    const series = nsKey(v, "color.series");
+    if (series)
+        return `series-${series}`;
+    return null;
+};
+/** "{typography.scale.sm.fontSize}" → "sm" (the --text-<key> utility). */
+const scaleKey = (v) => {
+    const m = v.match(/^\{typography\.scale\.([a-zA-Z0-9-]+)\.fontSize\}$/);
+    return m ? kebab(m[1]) : null;
+};
+/** "{color.semantic.primary}" → "var(--ds-color-semantic-primary)" - the raw
+ *  scoped vars always exist, so arbitrary-property fallbacks never dangle. */
+const refToDsVar = (v) => v.replace(/\{([a-z0-9.-]+)\}/gi, (_, path) => {
+    return `var(--ds-${path.split(".").map(kebab).join("-")})`;
+});
+/** Arbitrary-property escape hatch: guaranteed-faithful when no pretty utility
+ *  exists. Spaces become underscores per Tailwind's arbitrary syntax. */
+const arbitrary = (prop, value) => `[${kebab(prop)}:${refToDsVar(value).replace(/\s+/g, "_")}]`;
+const STATIC = {
+    display: {
+        flex: "flex",
+        "inline-flex": "inline-flex",
+        grid: "grid",
+        block: "block",
+        "inline-block": "inline-block",
+        none: "hidden",
+    },
+    alignItems: {
+        center: "items-center",
+        "flex-start": "items-start",
+        "flex-end": "items-end",
+        baseline: "items-baseline",
+        stretch: "items-stretch",
+    },
+    justifyContent: {
+        center: "justify-center",
+        "space-between": "justify-between",
+        "flex-start": "justify-start",
+        "flex-end": "justify-end",
+    },
+    flexDirection: { column: "flex-col", row: "flex-row" },
+    textAlign: { center: "text-center", left: "text-left", right: "text-right" },
+    cursor: { pointer: "cursor-pointer", "not-allowed": "cursor-not-allowed" },
+    width: { "100%": "w-full" },
+    height: { "100%": "h-full" },
+    textDecoration: { none: "no-underline", underline: "underline" },
+};
+/** One declaration → Tailwind classes (pretty when mappable, arbitrary-property
+ *  otherwise - never dropped). */
+function declToTailwind(prop, value) {
+    const stat = STATIC[prop]?.[value];
+    if (stat)
+        return [stat];
+    switch (prop) {
+        case "backgroundColor": {
+            if (value === "transparent")
+                return ["bg-transparent"];
+            const key = colorKey(value);
+            if (key)
+                return [`bg-${key}`];
+            break;
+        }
+        case "color": {
+            const key = colorKey(value);
+            if (key)
+                return [`text-${key}`];
+            break;
+        }
+        case "borderColor": {
+            const key = colorKey(value);
+            if (key)
+                return [`border-${key}`];
+            break;
+        }
+        case "border": {
+            // "1px solid {color.semantic.x}" → border + border-<x>
+            const m = value.match(/^1px\s+solid\s+(\{[^}]+\})$/);
+            if (m) {
+                const key = colorKey(m[1]);
+                if (key)
+                    return ["border", `border-${key}`];
+            }
+            break;
+        }
+        case "borderRadius": {
+            const key = nsKey(value, "radius");
+            if (key)
+                return [`rounded-${key}`];
+            break;
+        }
+        case "gap": {
+            const key = nsKey(value, "spacing");
+            if (key)
+                return [`gap-${key}`];
+            break;
+        }
+        case "padding": {
+            const keys = value.split(/\s+/).map((v) => nsKey(v, "spacing"));
+            if (keys.length === 1 && keys[0])
+                return [`p-${keys[0]}`];
+            if (keys.length === 2 && keys[0] && keys[1])
+                return [`py-${keys[0]}`, `px-${keys[1]}`];
+            break;
+        }
+        case "fontSize": {
+            const key = scaleKey(value);
+            if (key)
+                return [`text-${key}`];
+            break;
+        }
+        case "fontFamily": {
+            const key = nsKey(value, "typography.families");
+            if (key)
+                return [`font-${key}`];
+            break;
+        }
+        case "fontWeight": {
+            const key = nsKey(value, "typography.weights");
+            if (key)
+                return [`font-${key}`];
+            break;
+        }
+        case "boxShadow": {
+            const key = nsKey(value, "shadow");
+            if (key)
+                return [`shadow-${key}`];
+            break;
+        }
+        case "lineHeight":
+            // usually paired with the same scale's fontSize (text-<key> carries the
+            // scale's line-height via --text-<key>--line-height)
+            if (/^\{typography\.scale\./.test(value))
+                return [];
+            break;
+    }
+    return [arbitrary(prop, value)];
+}
+const STATE_PREFIX = {
+    hover: "hover:",
+    focus: "focus:",
+    focusVisible: "focus-visible:",
+    active: "active:",
+    disabled: "disabled:",
+};
+function blockToTailwind(block, prefix = "") {
+    return Object.entries(block).flatMap(([prop, value]) => declToTailwind(prop, value).map((cls) => `${prefix}${cls}`));
+}
+function tailwindClassList(recipe) {
+    const classes = [
+        ...blockToTailwind(recipe.base),
+        ...Object.entries(recipe.states ?? {}).flatMap(([state, block]) => STATE_PREFIX[state] ? blockToTailwind(block, STATE_PREFIX[state]) : []),
+    ];
+    return classes.join(" ");
+}
+// ── Emission ─────────────────────────────────────────────────────────────────
+function header(slug, name, version, mode) {
+    const setup = mode === "tailwind"
+        ? `import _synthesisui/ds/${slug}/theme.css (Tailwind adapter) + tokens.css`
+        : `import _synthesisui/ds/${slug}/tokens.css`;
+    return [
+        `// Generated by SynthesisUI - "${name}" from the "${slug}" design system (v${version}).`,
+        `// On-system by construction: every style resolves to the DS tokens.`,
+        `// Global setup (once per app): ${setup}`,
+        `// and put data-ds="${slug}" on a root element (e.g. <body data-ds="${slug}">).`,
+    ].join("\n");
+}
+const joinCls = (parts) => `[${parts.join(", ")}].filter(Boolean).join(" ")`;
+function emitCssMode(slug, name, recipe, version) {
+    const { tag, attrs, voidEl } = elementFor(name, recipe);
+    const axes = axesOf(recipe.variants);
+    const comp = pascal(name);
+    const propNames = axes.map((a) => a.prop);
+    const destructure = [...propNames, "className", "...props"].join(", ");
+    void voidEl; // both void and container elements self-close ({...props} carries children)
+    const rootJsx = `    <${tag}${attrs}\n      className={${joinCls([`"ds-${name}"`, "className"])}}\n${dataAttrLines(axes)}${axes.length ? "\n" : ""}      {...props}\n    />`;
+    const parts = Object.entries(recipe.parts ?? {}).map(([partName, part]) => {
+        const partAxes = axesOf(part.variants ?? {});
+        const partComp = `${comp}${pascal(partName)}`;
+        const partDestructure = [
+            ...partAxes.map((a) => a.prop),
+            "className",
+            "...props",
+        ].join(", ");
+        return `
+/** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
+export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, "div")}) {
+  return (
+    <div
+      className={${joinCls([`"ds-${name}-${kebab(partName)}"`, "className"])}}
+${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
+    />
+  );
+}`;
+    });
+    return `${header(slug, name, version, "css")}
+import "./${name}.css";
+import type { ComponentPropsWithoutRef } from "react";
+type ${comp}Props = ${propsType(axes, tag)};
+export function ${comp}({ ${destructure} }: ${comp}Props) {
+  return (
+${rootJsx}
+  );
+}
+${parts.join("\n")}`;
+}
+function emitTailwindMode(slug, name, recipe, version) {
+    const { tag, attrs, voidEl } = elementFor(name, recipe);
+    const axes = axesOf(recipe.variants);
+    const comp = pascal(name);
+    const variantConsts = axes
+        .filter((a) => !a.boolean)
+        .map((a) => {
+        const entries = a.options
+            .map((o) => `  ${JSON.stringify(o)}: ${JSON.stringify(blockToTailwind(recipe.variants[a.key]?.[o] ?? {}).join(" "))},`)
+            .join("\n");
+        return `const ${a.prop.toUpperCase()}: Record<string, string> = {\n${entries}\n};`;
+    });
+    const booleanConsts = axes
+        .filter((a) => a.boolean)
+        .map((a) => `const ${a.prop.toUpperCase()} = ${JSON.stringify(blockToTailwind(recipe.variants[a.key]?.true ?? {}).join(" "))};`);
+    const clsParts = [
+        "BASE",
+        ...axes.map((a) => a.boolean
+            ? `${a.prop} ? ${a.prop.toUpperCase()} : ""`
+            : `${a.prop} ? ${a.prop.toUpperCase()}[${a.prop}] : ""`),
+        "className",
+    ];
+    const destructure = [
+        ...axes.map((a) => a.prop),
+        "className",
+        "...props",
+    ].join(", ");
+    void voidEl;
+    return `${header(slug, name, version, "tailwind")}
+import type { ComponentPropsWithoutRef } from "react";
+const BASE = ${JSON.stringify(tailwindClassList(recipe))};
+${[...variantConsts, ...booleanConsts].join("\n")}
+type ${comp}Props = ${propsType(axes, tag)};
+export function ${comp}({ ${destructure} }: ${comp}Props) {
+  return (
+    <${tag}${attrs}
+      className={${joinCls(clsParts)}}
+      {...props}
+    />
+  );
+}
+${Object.entries(recipe.parts ?? {})
+        .map(([partName, part]) => {
+        const partComp = `${comp}${pascal(partName)}`;
+        return `
+/** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
+export function ${partComp}({ className, ...props }: ComponentPropsWithoutRef<"div">) {
+  return (
+    <div className={${joinCls([JSON.stringify(tailwindClassList(part)), "className"])}} {...props} />
+  );
+}`;
+    })
+        .join("\n")}`;
+}
+/** All files for one component, under `<componentsDir>/<name>/`. */
+export function generateComponentFiles(slug, name, recipe, css, version, styles) {
+    const comp = pascal(name);
+    const files = [];
+    if (styles === "css") {
+        files.push({
+            filename: `${name}.tsx`,
+            code: `${emitCssMode(slug, name, recipe, version)}\n`,
+        });
+        files.push({ filename: `${name}.css`, code: `${css}\n` });
+    }
+    else {
+        files.push({
+            filename: `${name}.tsx`,
+            code: `${emitTailwindMode(slug, name, recipe, version)}\n`,
+        });
+    }
+    files.push({
+        filename: "index.ts",
+        code: `export * from "./${name}";\n`,
+    });
+    void comp;
+    return files;
+}

package/dist/config.js CHANGED Viewed

@@ -40,6 +40,7 @@ export const DEFAULT_CONFIG = {
     target: "next",
     pagesDir: "app",
     componentsDir: "components",
+    styles: "css",
 };
 const projectConfigPath = (root) => join(root, "_synthesisui", "config.json");
 /** Reads the project config, falling back to defaults when absent/invalid. */
@@ -55,6 +56,7 @@ export async function readProjectConfig(root) {
             componentsDir: typeof parsed.componentsDir === "string" && parsed.componentsDir
                 ? parsed.componentsDir
                 : DEFAULT_CONFIG.componentsDir,
+            styles: parsed.styles === "tailwind" ? "tailwind" : "css",
         };
     }
     catch {

package/dist/guide.js CHANGED Viewed

@@ -145,6 +145,18 @@ place** - wire real data, split into components, swap the chart/icon/media place
 \`data-ds="${slug}"\` wrapper and the \`.ds-*\` / layout classes so it stays on-system. Run
 \`synthesisui init\` once to set the target (next/general) and the output folder.
+## Single components as YOUR code
+Bring one component in as a real, typed React component (variants become props):
+\`\`\`bash
+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.
 ---
 `
         : "";

package/dist/index.js CHANGED Viewed

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { add } from "./commands/add.js";
 import { advise } from "./commands/advise.js";
+import { component } from "./commands/component.js";
 import { generate } from "./commands/generate.js";
 import { init } from "./commands/init.js";
 import { list } from "./commands/list.js";
@@ -16,6 +17,7 @@ Usage:
   synthesisui list [options]               list the published design systems
   synthesisui add <slug> [options]         materialize a DS into _synthesisui/ds/<slug>/
   synthesisui template <slug> <name>       materialize a whole page from a DS template
+  synthesisui component <slug> <name>      bring one component in - artifacts + YOUR <Pascal>.tsx in componentsDir
   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)
@@ -29,6 +31,8 @@ Options:
   --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)
+  --styles <s>       init: component code flavor: css | tailwind (default: css)
+  --artifacts-only   component: skip the .tsx materialization (recipe + css only)
   --out <path>       output path for the generated template (default: <pagesDir>/<file>)
   -h, --help         this help
@@ -41,6 +45,7 @@ Examples:
   synthesisui add halogen --version 3
   synthesisui template halogen dashboard-sidebar
   synthesisui template halogen landing --out app/page.tsx
+  synthesisui component halogen pricing-tier
   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"
@@ -122,7 +127,16 @@ async function main() {
                 ? flags["components-dir"]
                 : undefined;
             const ds = typeof flags.ds === "string" ? flags.ds : undefined;
-            await init({ dir, registry, target, pagesDir, componentsDir, ds });
+            const styles = typeof flags.styles === "string" ? flags.styles : undefined;
+            await init({
+                dir,
+                registry,
+                target,
+                pagesDir,
+                componentsDir,
+                styles,
+                ds,
+            });
             break;
         }
         // `page` is the legacy alias (renamed to `template`); it still works so
@@ -153,6 +167,31 @@ async function main() {
             await template(slug, name, { registry, dir, out, target, version });
             break;
         }
+        case "component": {
+            const slug = args[0];
+            const name = args[1];
+            if (!slug || !name) {
+                console.error("error: provide slug and component name - `synthesisui component <slug> <name>`");
+                process.exitCode = 1;
+                return;
+            }
+            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 component(slug, name, {
+                registry,
+                dir,
+                version,
+                artifactsOnly: flags["artifacts-only"] === true,
+            });
+            break;
+        }
         case "use": {
             const slug = args[0];
             if (!slug) {

package/dist/registry.js CHANGED Viewed

@@ -63,6 +63,27 @@ export async function fetchTemplate(base, slug, template, target, version) {
     }
     return (await res.json());
 }
+/**
+ * Fetches ONE component from a DS (`?component=<name>`): its recipe + compiled
+ * CSS. Granular "bring specific" - the system must exist; works for public DS
+ * without login (private/owned needs the token).
+ */
+export async function fetchComponent(base, slug, name, version) {
+    const url = new URL(`${base}/api/registry/ds/${encodeURIComponent(slug)}`);
+    url.searchParams.set("component", name);
+    if (version != null)
+        url.searchParams.set("version", String(version));
+    const res = await request(url.toString());
+    if (res.status === 404) {
+        const body = (await res.json().catch(() => ({})));
+        throw new RegistryError(body.message ??
+            `No component "${name}" in "${slug}". Run \`synthesisui add ${slug}\` and check its components.`);
+    }
+    if (!res.ok) {
+        throw new RegistryError(`Registry responded ${res.status} while fetching "${name}".`);
+    }
+    return (await res.json());
+}
 /**
  * Calls the hosted advisor (`POST /api/ai/advisor`). Gated + metered server-side:
  * 401 = not logged in, 429 = daily quota reached. Sends the Bearer token if present.

package/package.json CHANGED Viewed

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