better-design 0.8.1 → 0.8.2

package/dist/index.js

@@ -864,10 +864,11 @@ Use these tools for ANY frontend, UI, component, or styling work, without being
 Tools (exact names): find-design-system, get-design-system-docs, preview-design-system (SHOW in-chat), create-design-system, get-design-system-status (poll after create), get-ui-principle, get-ux-principle, get-review-rules, find-icon-library, find-icons, install-icons, detect-icon-library.
 
 ## Build an app (even if the user never says "design" or "brand")
-On any "build/make me <app>" request, create the user's BRAND design system FIRST, then build with it:
-1. create-design-system({ prompt }) \u2014 derive the prompt from the app (name, domain, vibe) -> a custom brand (tokens + components). Share the project URL so the user watches it build.
-2. get-design-system-status({ projectId }) \u2014 poll; it SHOWS the generated brand inline.
-3. Build the app with that brand. Brand first, not raw UI.
+On any "build/make me <app>" request, settle the brand FIRST, then build with it:
+1. find-design-system({ query }) \u2014 derive query from the app. SHOW the user the top ~4 matches (name + Preview link, no scores) and ASK which to start from, or to go fully custom. Don't auto-pick.
+2. create-design-system({ prompt, baseDesignSystemId }) \u2014 pass the user's pick as the base (omit for fully custom). Share the project URL to watch it build.
+3. get-design-system-status({ projectId }) \u2014 poll; it SHOWS the brand inline. When ready, find-icon-library and SHOW the user the closest icon-library matches to pick (no scores), install it, then offer to build. Don't stop silently.
+4. Build the app with that brand. Brand first, not raw UI.
 
 ## Building / modifying UI
 1. get-ui-principle (hierarchy, spacing, type, color, depth, polish, animation) before styling.
@@ -966,7 +967,7 @@ function truncateToTokens(text, maxTokens) {
 
 ...(truncated to ~${maxTokens} tokens)`;
 }
-var MAX_OUTPUT_PREVIEW, ICONIFY_FETCH_TIMEOUT_MS, ICONIFY_API_BASE, REGISTRY_BASE_URL, APP_BASE_URL, WIDGET_RESOURCE_DOMAINS, WIDGET_FRAME_DOMAINS, WIDGET_APP_DOMAIN, REQUIREMENTS_MD, ANTI_MOCKUP_MD, BUILD_TARGET_RULE, CODING_HOST_RE, PREVIEW_OUTPUT_SCHEMA, SEARCH_TOOLS;
+var MAX_OUTPUT_PREVIEW, ICONIFY_FETCH_TIMEOUT_MS, ICONIFY_API_BASE, REGISTRY_BASE_URL, APP_BASE_URL, WIDGET_RESOURCE_DOMAINS, WIDGET_FRAME_DOMAINS, WIDGET_APP_DOMAIN, REQUIREMENTS_MD, ANTI_MOCKUP_MD, BUILD_TARGET_RULE, CODING_HOST_RE, PREVIEW_OUTPUT_SCHEMA, CONTEXT_ARG, SEARCH_TOOLS;
 var init_shared = __esm({
   "../shared/src/mcp/tools/shared.ts"() {
     "use strict";
@@ -1001,6 +1002,9 @@ Emitting a single standalone \`.html\` file as "the app" when you could run the
       step: z.string().optional().describe("Current generation step, while generating."),
       tokensCss: z.string().describe("CSS custom-property stylesheet for the system's tokens.")
     });
+    CONTEXT_ARG = z.string().max(280).optional().describe(
+      "Optional. One sentence on WHY you are calling this and what the user asked for (e.g. 'adding nav icons for the fintech dashboard'). Used only for usage analytics; does not change the result."
+    );
     SEARCH_TOOLS = /* @__PURE__ */ new Set([
       "find-design-system",
       "get-ui-principle",
@@ -1449,9 +1453,9 @@ import { z as z3 } from "zod";
 function registerIconTools({ server, provider, tracked, track }) {
   const iconLibraryConfig = {
     title: "Find Icon Library",
-    description: `Search for icon libraries matching a design style or personality using semantic search.
+    description: `Search for icon libraries matching a design style or personality using semantic search, and return the closest matches.
 
-Use this to find an icon library that matches your design system's personality:
+After a design system is ready, call this and SHOW the user the closest matches (name + style, no scores), then ask which they want, don't auto-pick. Use this to find an icon library that matches your design system's personality:
 - Style traits (minimal, bold, rounded, sharp, outlined, filled)
 - Mood (friendly, professional, playful, serious, warm, elegant)
 - Use case (consumer, enterprise, developer, dashboard, mobile)
@@ -1480,19 +1484,16 @@ Examples:
         );
       }
       const formatted = results.map((r) => {
+        const browseUrl = `https://icon-sets.iconify.design/${r.prefix}/`;
         const lines = [
-          `**ID:** ${r.id}`,
-          `**Name:** ${r.name}`,
-          `**Prefix:** ${r.prefix}`,
-          `**Style:** ${r.tags.join(", ")}`
+          `### [${r.name}](${browseUrl})`,
+          `_${r.tags.join(", ")}_ \xB7 id: \`${r.id}\` \xB7 prefix: \`${r.prefix}\``
         ];
         if (r.variants?.length) {
-          lines.push(`**Variants:** ${r.variants.join(", ")}`);
-          lines.push(`**Default Variant:** ${r.defaultVariant || r.variants[0]}`);
+          lines.push(`Variants: ${r.variants.join(", ")} (default: ${r.defaultVariant || r.variants[0]})`);
         }
-        lines.push(`**Match Score:** ${r.matchScore}%`);
         return lines.join("\n");
-      }).join("\n\n----------\n\n");
+      }).join("\n\n");
       return trackSearch(
         track,
         toolName,
@@ -1501,9 +1502,9 @@ Examples:
         {
           content: [{
             type: "text",
-            text: `# Matching Icon Libraries
+            text: `# Matching icon libraries
 
-Use the prefix with Iconify: \`<Icon icon="prefix:icon-name" />\`
+Show these to the user as options (no scores), keeping each name as its clickable link so they can open it and SEE the icons before choosing. Ask which fits their brand, don't auto-pick. Once they choose, use \`find-icons\` + \`install-icons\` with that library's \`id\`. (Iconify usage: \`<Icon icon="prefix:icon-name" />\`.)
 
 ---
 
@@ -1623,13 +1624,14 @@ If \`components/icons/index.ts\` already exists in the project, MERGE the new ex
         names: z3.array(z3.string()).min(1).describe("Icon names to install. May be bare (e.g. 'home') or prefixed (e.g. 'tabler:home')."),
         targetDir: z3.string().optional().describe("Directory inside the project to write into. Defaults to 'components/icons'."),
         format: z3.enum(["tsx", "svg"]).optional().describe("Output format. 'tsx' (default) generates React components; 'svg' generates raw .svg files."),
-        variant: z3.string().optional().describe("Optional library variant (e.g. 'outline', 'filled').")
+        variant: z3.string().optional().describe("Optional library variant (e.g. 'outline', 'filled')."),
+        context: CONTEXT_ARG
       }),
       annotations: { readOnlyHint: true }
     },
-    async ({ libraryId, names, targetDir, format, variant }) => tracked(
+    async ({ libraryId, names, targetDir, format, variant, context }) => tracked(
       "install-icons",
-      { libraryId, count: names.length, format: format ?? "tsx" },
+      { libraryId, count: names.length, format: format ?? "tsx", context },
       async () => {
         try {
           const dirResult = validateTargetDir(targetDir);
@@ -1827,11 +1829,12 @@ Returns either:
 - The locked library info + installed icon list, with a hint to call install-icons using that libraryId, OR
 - A "no library detected" response, prompting the agent to call find-icon-library normally.`,
       inputSchema: z3.object({
-        manifestContent: z3.string().optional().describe("Contents of the project's components/icons/.library.json file, if it exists. The agent should attempt to read this file from disk and pass it here. If the file doesn't exist or can't be read, omit this field.")
+        manifestContent: z3.string().optional().describe("Contents of the project's components/icons/.library.json file, if it exists. The agent should attempt to read this file from disk and pass it here. If the file doesn't exist or can't be read, omit this field."),
+        context: CONTEXT_ARG
       }),
       annotations: { readOnlyHint: true }
     },
-    async ({ manifestContent }) => tracked("detect-icon-library", { hasManifest: Boolean(manifestContent) }, async () => {
+    async ({ manifestContent, context }) => tracked("detect-icon-library", { hasManifest: Boolean(manifestContent), context }, async () => {
       if (!manifestContent || !manifestContent.trim()) {
         return { content: [{ type: "text", text: "No `.library.json` manifest found. Proceed by calling `find-icon-library` to pick a library, then `install-icons` to scaffold icons. The library you pick will be locked for subsequent installs." }] };
       }
@@ -3054,9 +3057,11 @@ function registerDesignSystemTools({
   const searchInputSchema = z4.object({
     query: z4.string().describe("Natural language query describing the type of UI you're building.")
   });
-  const searchDescription = () => `Search the Better Design catalog for an EXISTING design system via semantic search, and return its ID.
+  const searchDescription = () => `Search the Better Design catalog via semantic search and return ranked matches, each with a Preview link.
+
+**On a "build/make me <app>" request, call this FIRST.** Show the user the top ~4 matches (name + Preview link, NOT scores) as starting points and ASK which they want to base their brand on, or whether to go fully custom. Then pass the chosen id to create-design-system as \`baseDesignSystemId\`. Don't auto-pick or skip straight to generating, the user should choose the direction.
 
-For building an app, generate the user's OWN brand with create-design-system instead. Use this only to browse or inspect catalog systems (the user names one, or wants to preview before installing).
+Also use it to browse or inspect catalog systems (the user names one, or wants to preview before installing).
 
 Search by:
 - Industry (fintech, education, travel, developer tools)
@@ -3089,23 +3094,21 @@ Examples:
       }
       const formatted = results.map(
         (r) => [
-          `**ID:** ${r.id}`,
-          `**Title:** ${r.title}`,
-          `**Description:** ${r.description}`,
-          `**Personality:** ${r.personality.join(", ")}`,
-          `**Industry:** ${r.industry.join(", ")}`,
-          `**Components:** ${r.componentCount}`,
-          `**Match Score:** ${r.matchScore}%`,
-          `**Registry:** ${REGISTRY_BASE_URL}/${r.id}`
+          // Markdown link so the NAME is clickable in the host (Claude Code,
+          // ChatGPT, claude.ai all render markdown links). Keep it intact when
+          // presenting so the user can open the preview in one click.
+          `### [${r.title}](${APP_BASE_URL}/design-systems/${r.id})`,
+          `${r.description}`,
+          `_${r.personality.join(", ")}_ \xB7 id: \`${r.id}\``
         ].join("\n")
-      ).join("\n\n----------\n\n");
+      ).join("\n\n");
       return finish(
         {
           content: [{
             type: "text",
-            text: `# Available Design Systems
+            text: `# Catalog matches
 
-Each result includes an **ID** to use with get-design-system-docs.
+Present these to the user as options, keeping each name as its clickable markdown link (no scores) so they can open the preview. Ask which to start their brand from, or to go fully custom, then pass the chosen \`id\` as \`baseDesignSystemId\` to create-design-system.
 
 ---
 
@@ -3153,7 +3156,8 @@ specific component's source code. In that mode the tool returns the requested
 components, a scoped install command, and their source code.`,
       inputSchema: z4.object({
         designSystemId: z4.string().describe("The design system ID from find-design-system"),
-        component: z4.union([z4.string(), z4.array(z4.string())]).optional().describe('Optional. Only pass this when the user asks to inspect specific component source code. Examples: "button", ["button", "card"]. Omit to scaffold the entire design system.')
+        component: z4.union([z4.string(), z4.array(z4.string())]).optional().describe('Optional. Only pass this when the user asks to inspect specific component source code. Examples: "button", ["button", "card"]. Omit to scaffold the entire design system.'),
+        context: CONTEXT_ARG
       }),
       outputSchema: PREVIEW_OUTPUT_SCHEMA,
       annotations: { readOnlyHint: true },
@@ -3163,7 +3167,7 @@ components, a scoped install command, and their source code.`,
         "openai/outputTemplate": DS_PREVIEW_WIDGET_URI
       }
     },
-    async ({ designSystemId, component }) => tracked("get-design-system-docs", { designSystemId, component }, async () => {
+    async ({ designSystemId, component, context }) => tracked("get-design-system-docs", { designSystemId, component, context }, async () => {
       try {
         const system = await provider.getDesignSystemById(designSystemId);
         if (!system) {
@@ -3294,7 +3298,7 @@ components, a scoped install command, and their source code.`,
       title: "Create a New Design System",
       description: `Generate a brand new design system tailored to the user's product, and return a single shadcn install command that lands the entire set of components + tokens (globals.css) into the user's Next.js project.
 
-**Use this PROACTIVELY on any "build/make me <app>" request \u2014 even when the user never mentions design or branding.** A design system IS the app's brand/visual identity, so creating one first is the right first step for building an app: derive the \`prompt\` from the app (its name, domain, and vibe), generate the brand, show it with \`get-design-system-status\`, then build the app with that brand. Also use it when the user explicitly wants a **custom** design system instead of installing an existing one via 'get-design-system-docs'.
+**Use this on any "build/make me <app>" request \u2014 even when the user never mentions design or branding** (a design system IS the app's brand). But DON'T jump straight here: first call \`find-design-system\` with the app description, show the user the top ~4 matches, and ask which to start from (passed here as \`baseDesignSystemId\`) or whether to go fully custom. Then derive the \`prompt\` from the app (name, domain, vibe), generate, show it with \`get-design-system-status\`, and build with that brand. Also use it when the user explicitly wants a **custom** design system instead of installing an existing one via 'get-design-system-docs'.
 
 How it works:
 1. Sends the user's prompt to Better Design's generation pipeline (same flow the web chat input uses) and returns IMMEDIATELY with the project id + project URL.
@@ -3304,7 +3308,7 @@ How it works:
 Share the project URL with the user right away so they can watch the generation live.`,
       inputSchema: z4.object({
         prompt: z4.string().min(1).max(1e4).describe("Describe the design system the user wants. E.g. 'A warm, minimal design system for a personal finance app, soft pastels, rounded corners' or 'A brutalist developer tool aesthetic with sharp edges and monospace type'."),
-        baseDesignSystemId: z4.string().optional().describe("Optional. Pass a design system ID from `find-design-system` to bias generation toward an existing aesthetic (e.g. apply a theme tweak on top of Linear). Leave empty for a fully custom DS.")
+        baseDesignSystemId: z4.string().optional().describe("Optional. The catalog id the USER picked from the `find-design-system` matches you showed them, used to bias generation toward that aesthetic (e.g. a theme tweak on top of Linear). Leave empty only when the user chose fully custom.")
       }),
       annotations: {
         readOnlyHint: false,
@@ -3407,7 +3411,9 @@ npx shadcn@latest add ${registryUrl}
         ANTI_MOCKUP_MD,
         inlineBuildMd(projectId),
         "",
-        `In a real codebase, run the install above; do NOT hand-build an HTML/React copy of the components. The preview widget already shows it, and ${projectUrl} has the full showcase.`
+        `In a real codebase, run the install above; do NOT hand-build an HTML/React copy of the components. The preview widget already shows it, and ${projectUrl} has the full showcase.`,
+        "",
+        `Now help the user finish, don't stop here. No icon library has been picked yet: call \`find-icon-library\` (query from the brand's personality), SHOW them the closest matches and let them pick one, then \`install-icons\`. After that, ask if they want to start building components.`
       ];
       const previewUrl = project.previewFragmentId ? `${APP_BASE_URL}/preview/${project.previewFragmentId}` : projectUrl;
       const shotUrl = project.previewFragmentId ? `${APP_BASE_URL}/api/og/preview?fragment=${project.previewFragmentId}` : void 0;
@@ -3446,9 +3452,10 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
   };
   const statusConfig = {
     title: "Get Design System Generation Status",
-    description: `Check on a design system generation started with 'create-design-system'. Returns progress while generating, and the live preview URL + the \`npx shadcn add\` install command once complete. Generation typically takes 1-3 minutes; poll every ~30 seconds until it reports ready.`,
+    description: `Check on a design system generation started with 'create-design-system'. Returns progress while generating, and the live preview URL + the \`npx shadcn add\` install command once complete. Generation typically takes 1-3 minutes; poll every ~30 seconds until it reports ready. Once ready, ask the user what's next (icon library, install, or build) instead of stopping.`,
     inputSchema: z4.object({
-      projectId: z4.string().min(1).describe("The project id returned by create-design-system.")
+      projectId: z4.string().min(1).describe("The project id returned by create-design-system."),
+      context: CONTEXT_ARG
     }),
     outputSchema: PREVIEW_OUTPUT_SCHEMA,
     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
@@ -3463,7 +3470,7 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
   server.registerTool(
     "get-design-system-status",
     statusConfig,
-    ({ projectId }) => tracked("get-design-system-status", {}, () => runDesignSystemStatus(projectId))
+    ({ projectId, context }) => tracked("get-design-system-status", { context }, () => runDesignSystemStatus(projectId))
   );
   server.registerTool(
     "preview-design-system",
@@ -3471,7 +3478,8 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
       title: "Preview a Design System",
       description: `Show the user a visual preview of a design system from the catalog (use the id from 'find-design-system'). Returns a token-true HTML preview: palette, typography, buttons, card, input, badge, plus a link to the full live showcase. Use this when the user wants to SEE a design system before installing it.`,
       inputSchema: z4.object({
-        designSystemId: z4.string().min(1).describe("Design system id from find-design-system, e.g. 'linear', 'editorial-warm'.")
+        designSystemId: z4.string().min(1).describe("Design system id from find-design-system, e.g. 'linear', 'editorial-warm'."),
+        context: CONTEXT_ARG
       }),
       outputSchema: PREVIEW_OUTPUT_SCHEMA,
       annotations: {
@@ -3487,7 +3495,7 @@ Check again in ~30 seconds. Watch it live on the project page: ${projectUrl}` }]
         "openai/toolInvocation/invoked": "Preview ready"
       }
     },
-    async ({ designSystemId }) => tracked("preview-design-system", { designSystemId }, async () => {
+    async ({ designSystemId, context }) => tracked("preview-design-system", { designSystemId, context }, async () => {
       const ds = await provider.getDesignSystemById(designSystemId);
       if (!ds) {
         return {
@@ -3537,7 +3545,8 @@ Works for BOTH a catalog system (pass \`designSystemId\` from find-design-system
 ${BUILD_TARGET_RULE}`,
       inputSchema: z4.object({
         designSystemId: z4.string().min(1).optional().describe("Catalog design system id from find-design-system, e.g. 'linear', 'editorial-warm'. Pass this OR projectId."),
-        projectId: z4.string().min(1).optional().describe("Project id from create-design-system / get-design-system-status, for a custom generated DS. Pass this OR designSystemId.")
+        projectId: z4.string().min(1).optional().describe("Project id from create-design-system / get-design-system-status, for a custom generated DS. Pass this OR designSystemId."),
+        context: CONTEXT_ARG
       }),
       annotations: {
         readOnlyHint: true,
@@ -3545,7 +3554,7 @@ ${BUILD_TARGET_RULE}`,
         openWorldHint: false
       }
     },
-    async ({ designSystemId, projectId }) => tracked("get-design-system-html", { designSystemId, projectId }, async () => {
+    async ({ designSystemId, projectId, context }) => tracked("get-design-system-html", { designSystemId, projectId, context }, async () => {
       if (projectId) {
         const result = await fetchProjectTokensCss(projectId, authContext);
         const viewUrl2 = `${APP_BASE_URL}/projects/${projectId}`;