better-design 0.15.0 → 0.15.1

package/README.md

@@ -8,64 +8,42 @@ Design systems, UI principles, icons, and code review for AI coding agents. [bet
 npx better-design
 ```
 
-Run it once. No signup needed: a free key is created automatically and written into your installed MCP clients (Claude Code, Cursor, VS Code, Windsurf, Zed, Cline, JetBrains, and more), merge-safe, with an auto-invoke rule.
+Run it once. It creates a free key, writes the config into the MCP clients you already have, and merges rather than overwriting. No signup. [See a page per client](https://better-design.com/mcp/install).
 
-Using ZCode? Follow the [ZCode MCP setup guide](https://better-design.com/mcp/install/zcode) to add Better Design as an HTTP server.
+Already have a key? Set `BETTER_DESIGN_API_KEY`. Manage keys at [better-design.com/mcp](https://better-design.com/mcp).
 
-The free key has a query limit; the tools link you to turn it into a free account (same key, unlimited, history kept). Already have a key? Set `BETTER_DESIGN_API_KEY`. Manage keys at [better-design.com/mcp](https://better-design.com/mcp).
-
-> After install, set `"style": "new-york"` in `components.json` before running the shadcn command (the default `base-nova` style rewrites Radix `asChild` and breaks components). The returned install instructions include this.
+> Set `"style": "new-york"` in `components.json` before running the shadcn command. The default `base-nova` style rewrites Radix `asChild` and breaks components.
 
 ## Tools
 
-The server exposes MCP tools only; it does not register prompts.
-
 | Tool | Purpose |
 | --- | --- |
-| `find-design-system` | Start any UI build by searching the catalog for visual foundations, or browse and compare existing systems. Returns IDs and the build/review guardrails needed for the next step. |
-| `create-design-system` | Start a custom design system generation job. |
-| `get-design-system-status` | Poll a generated design system and return the install command when ready. |
-| `review-illustration` | Render an SVG illustration you drew, look at it, and report what is visibly wrong |
-| `get-design-system-kit` | Return the correct implementation kit through one entry point. Use `target: "react"` in coding hosts for shadcn install commands and real components; use `target: "html"` only in inline canvases/artifacts for the framework-free HTML/CSS kit; use `target: "shopify"` for ready-to-write Liquid theme files (CSS asset, snippets, theme editor sections) that drop into any Online Store 2.0 theme. Accepts a catalog `designSystemId`, or a generated `projectId` for the html and shopify targets. Base UI is the default React flavor; pass `library: "radix"` when the project already uses Radix. |
-| `preview-design-system` | Return a token-true visual preview for a catalog design system. |
-| `get-ui-principle` | Load or search visual UI principles. |
+| `find-design-system` | Search the catalog for a look to build on. |
+| `create-design-system` | Generate a custom design system. |
+| `get-design-system-status` | Poll a generation job and return the install command. |
+| `get-design-system-kit` | Return the implementation kit: React components, framework-free HTML, or Shopify Liquid. |
+| `preview-design-system` | Return a token-true visual preview. |
+| `extract-design-system` | Pull a semantic token set out of a project's existing CSS. |
+| `get-ui-principle` | Load or search visual principles. |
 | `get-ux-principle` | Load or search flow and interaction principles. |
-| `get-react-native-guide` | Load or search implementation guidance and code recipes for React Native and Expo projects. |
-| `get-three-js-guide` | Load or search implementation guidance and code recipes for Three.js and React Three Fiber projects. |
-| `get-motion-guide` | Load or search guidance for building a product demo video in code, from composition setup to checking the render. |
-| `get-review-rules` | Return the Better Design self-review checklist. Supports `category`: `accessibility`, `visual-design`, `animation`, `content`, `comprehension`, or `all`. |
-| `check-comprehension` | Check a finished screen against the mom test, the 15 second test, and the screenshot test. Pass the copy (`headline`, `body`, `actions`) or the screen's `code`, and it returns the findings that would stop a stranger understanding it. |
-| `extract-design-system` | Distill an oklch-normalized semantic token set out of a project's existing CSS (paste `globals.css` / Tailwind v4 `@theme`) so new components match the app the user already built. |
-| `find-icon-library` | Find an icon library for an app or project style. |
+| `get-react-native-guide` | React Native and Expo implementation guidance. |
+| `get-three-js-guide` | Three.js and React Three Fiber implementation guidance. |
+| `get-motion-guide` | Building a product demo video in code. |
+| `get-review-rules` | The self-review checklist. `category`: `accessibility`, `visual-design`, `animation`, `content`, `comprehension`, `all`. |
+| `check-comprehension` | Check a finished screen against the mom test, the 15 second test, and the screenshot test. |
+| `review-illustration` | Render an SVG you drew, look at it, report what is visibly wrong. |
+| `find-icon-library` | Find an icon library that fits the project. |
 | `find-icons` | Search icons by name, library, and variant. |
-| `install-icons` | Generate local icon components in the target project. |
-| `detect-icon-library` | Read an existing icon-library manifest and report the active library. |
-
-## Retrieve Principles
-
-Use `topic` when you know the principle or one of its aliases. Use `query` when you want the most relevant sections for a specific design problem.
-
-```text
-get-ui-principle({ topic: "blur test" })
-get-ui-principle({ query: "group this dense settings screen with clearer proximity" })
-get-ux-principle({ topic: "reward design" })
-get-ux-principle({ query: "confirm a high-stakes action with control rather than celebration" })
-get-ux-principle({ topic: "clarity audit" })
-get-ux-principle({ topic: "motion brief" })
-```
-
-The principle tools return complete documents for topic lookups and focused document sections for natural-language searches. After implementation, call `get-review-rules({ category: "all" })` so the same hierarchy, accessibility, motion, copy, and reward guidance is applied during review.
-
-## Setup Behavior
+| `install-icons` | Write icon components into the project. |
+| `detect-icon-library` | Report which icon library a project already uses. |
 
-`npx better-design` auto-creates a free key when none is set, then prompts for clients, scope, and auto-invoke rules. Non-interactive runs (agents, or `-y`/`--yes`) install silently. Configs are merged into your existing files (backed up first, never clobbering other MCP servers); scope falls back per client when one isn't supported.
+Every load-or-search tool takes `topic` when you know the name, or `query` when you are describing a problem.
 
-Options:
+## Options
 
 | Option | Description |
 | --- | --- |
-| `-y`, `--yes` | Non-interactive: skip prompts, auto-create a key. |
-| `BETTER_DESIGN_API_KEY` | Use your own key instead of auto-provisioning. |
-| `--global` | Install at user/global scope when the client supports it. |
-| `--project` | Install in the current project when the client supports it. |
-| `--help` | Print setup usage. |
+| `-y`, `--yes` | Skip prompts. Agents and CI run this way by default. |
+| `--global` | Install at user scope, where the client supports it. |
+| `--project` | Install in the current project, where the client supports it. |
+| `--help` | Print usage. |

package/dist/index.js

@@ -1037,7 +1037,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, BUILD_KIT_OUTPUT_SCHEMA, CONTEXT_ARG, 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, BUILD_KIT_OUTPUT_SCHEMA, CONTEXT_ARG, READ_ONLY_TOOL_ANNOTATIONS, SEARCH_TOOLS;
 var init_shared = __esm({
   "../shared/src/mcp/tools/shared.ts"() {
     "use strict";
@@ -1086,6 +1086,11 @@ The UI copy inside the screen follows the same restraint: short headlines (about
     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."
     );
+    READ_ONLY_TOOL_ANNOTATIONS = {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false
+    };
     SEARCH_TOOLS = /* @__PURE__ */ new Set([
       "find-design-system",
       "get-ui-principle",
@@ -1278,7 +1283,7 @@ Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
         maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000-10000."),
         context: CONTEXT_ARG
       }),
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({ topic, query, maxTokens, context }) => {
       const start = Date.now();
@@ -1319,7 +1324,7 @@ Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
         maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000-10000."),
         context: CONTEXT_ARG
       }),
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({ topic, query, maxTokens, context }) => {
       const start = Date.now();
@@ -1365,7 +1370,7 @@ Prefer query search when you do not know the topic name. Use maxTokens to keep r
           maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000-10000."),
           context: CONTEXT_ARG
         }),
-        annotations: { readOnlyHint: true }
+        annotations: READ_ONLY_TOOL_ANNOTATIONS
       },
       async ({ topic, query, maxTokens, context }) => {
         const start = Date.now();
@@ -1422,7 +1427,7 @@ Prefer query search when you do not know the topic name. Use maxTokens to keep r
           maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000-10000."),
           context: CONTEXT_ARG
         }),
-        annotations: { readOnlyHint: true }
+        annotations: READ_ONLY_TOOL_ANNOTATIONS
       },
       async ({ topic, query, maxTokens, context }) => {
         const start = Date.now();
@@ -1482,7 +1487,7 @@ Prefer query search when you do not know the topic name. Use maxTokens to keep r
         maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000-10000."),
         context: CONTEXT_ARG
       }),
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({ topic, query, maxTokens, context }) => {
       const start = Date.now();
@@ -1550,7 +1555,7 @@ Use maxTokens to keep responses focused (recommended: 5000\u201310000).`,
         maxTokens: z2.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates content to fit. Recommended: 5000\u201310000."),
         context: CONTEXT_ARG
       }),
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({ category = "all", maxTokens, context }) => {
       const start = Date.now();
@@ -2107,7 +2112,7 @@ Use knownTerms for words your audience genuinely knows, so the check stops flagg
         knownTerms: z3.array(z3.string().trim().min(1).max(60)).max(50).optional().describe("Words this audience already knows, so they are not flagged as insider language."),
         context: CONTEXT_ARG
       }),
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({ context, ...args }) => {
       const start = Date.now();
@@ -2292,7 +2297,7 @@ Examples:
     inputSchema: z4.object({
       query: z4.string().describe("Style description or personality traits to match.")
     }),
-    annotations: { readOnlyHint: true }
+    annotations: READ_ONLY_TOOL_ANNOTATIONS
   };
   const makeIconLibraryHandler = (toolName) => async ({ query }) => {
     const start = Date.now();
@@ -2368,7 +2373,7 @@ Returns icons formatted for use with Iconify React. If you pass a variant, Bette
       libraryId: z4.string().describe("The icon library ID from find-icon-library"),
       variant: z4.string().optional().describe("Optional variant style (e.g., 'bold', 'outline', 'duotone').")
     }),
-    annotations: { readOnlyHint: true }
+    annotations: READ_ONLY_TOOL_ANNOTATIONS
   };
   const makeIconSearchHandler = (toolName) => async ({ query, libraryId, variant }) => {
     const start = Date.now();
@@ -2452,7 +2457,7 @@ If \`components/icons/index.ts\` already exists in the project, MERGE the new ex
         variant: z4.string().optional().describe("Optional library variant (e.g. 'outline', 'filled')."),
         context: CONTEXT_ARG
       }),
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({ libraryId, names, targetDir, format, variant, context }) => tracked(
       "install-icons",
@@ -2657,7 +2662,7 @@ Returns either:
         manifestContent: z4.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 }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({ manifestContent, context }) => tracked("detect-icon-library", { hasManifest: Boolean(manifestContent), context }, async () => {
       if (!manifestContent || !manifestContent.trim()) {
@@ -6079,9 +6084,9 @@ function inlineBuildMd(projectId) {
   return `
 **Building inline (ChatGPT canvas / Claude artifact)?** There is no npm or Tailwind there, so the install above can't run. Call \`get-design-system-kit\` with \`target: "html"\` and projectId \`${projectId}\` to get this system's real tokens + a framework-free CSS kit you paste into one \`<style>\` and build with immediately.`;
 }
-async function fetchProjectTokensCss(projectId, authContext) {
+async function fetchProjectTokensCss(projectId, apiFetch, authContext) {
   try {
-    const res = await fetch(`${APP_BASE_URL}/api/projects/${projectId}/registry/all.json`, {
+    const res = await apiFetch(`${APP_BASE_URL}/api/projects/${projectId}/registry/all.json`, {
       headers: authHeaders(authContext)
     });
     if (!res.ok) return null;
@@ -6171,7 +6176,8 @@ function registerDesignSystemTools({
   provider,
   tracked,
   track,
-  authContext
+  authContext,
+  apiFetch = globalThis.fetch
 }, { enableShopifyKit = true } = {}) {
   const searchInputSchema = z5.object({
     query: z5.string().describe(
@@ -6269,7 +6275,7 @@ ${BUILD_TARGET_RULE}` : ""}`
       title: "Find a Design System for a UI Build",
       description: searchDescription(),
       inputSchema: searchInputSchema,
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     makeSearchHandler("find-design-system", true)
   );
@@ -6290,7 +6296,7 @@ ${BUILD_TARGET_RULE}` : ""}`
           structuredContent: { status: "error", name: `Project ${projectId.slice(0, 8)}`, viewUrl: viewUrl2, tokensCss: "" }
         };
       }
-      const result = await fetchProjectTokensCss(projectId, authContext);
+      const result = await fetchProjectTokensCss(projectId, apiFetch, authContext);
       if (!result?.tokensCss) {
         return {
           content: [{ type: "text", text: `Could not load tokens for project "${projectId}". It may still be generating, or the id is wrong. Check ${viewUrl2}.` }],
@@ -6393,7 +6399,7 @@ ${fence3}` }],
   }) => tracked("get-design-system-kit", { target: "shopify", designSystemId, projectId, context }, async () => {
     if (projectId) {
       const viewUrl2 = `${APP_BASE_URL}/projects/${projectId}`;
-      const result = await fetchProjectTokensCss(projectId, authContext);
+      const result = await fetchProjectTokensCss(projectId, apiFetch, authContext);
       if (!result?.tokensCss) {
         return {
           content: [{ type: "text", text: `Could not load tokens for project "${projectId}". It may still be generating, or the id is wrong. Check ${viewUrl2}.` }],
@@ -6500,7 +6506,7 @@ ${BUILD_TARGET_RULE}`,
         context: CONTEXT_ARG
       }),
       outputSchema: buildKitOutputSchema(enableShopifyKit),
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
       // This tool returns build instructions, not a visual preview. Attaching
       // the preview template makes ChatGPT render a nested showcase iframe;
       // when that iframe is unavailable the user sees a large blank card even
@@ -6742,7 +6748,7 @@ Share the project URL with the user right away so they can watch the generation
         requestHeaders.Authorization = `Bearer ${bearer2}`;
       }
       try {
-        const startRes = await fetch(startUrl, {
+        const startRes = await apiFetch(startUrl, {
           method: "POST",
           headers: requestHeaders,
           body: JSON.stringify({
@@ -6786,7 +6792,7 @@ Share the project URL with the user right away so they can watch the generation
     const statusUrl = `${APP_BASE_URL}/api/projects/${projectId}`;
     let project;
     try {
-      const res = await fetch(statusUrl, { headers });
+      const res = await apiFetch(statusUrl, { headers });
       if (!res.ok) {
         return { content: [{ type: "text", text: `Could not read project ${projectId} (HTTP ${res.status}). Check the id, or view it at ${APP_BASE_URL}/projects/${projectId}.` }] };
       }
@@ -6803,7 +6809,7 @@ npx shadcn@latest add ${registryUrl}
       let tokensCss = "";
       let dsName = `Project ${projectId.slice(0, 8)}`;
       try {
-        const res = await fetch(registryUrl);
+        const res = await apiFetch(registryUrl);
         if (res.ok) {
           const json = await res.json();
           if (json.meta?.installInstructions) body = json.meta.installInstructions;
@@ -7525,7 +7531,7 @@ Returns: the semantic palette (primary, background, foreground, accent, border,
         name: z6.string().trim().min(1).max(120).optional().describe("Optional label for the extracted system, e.g. the app or repo name."),
         maxTokens: z6.number().min(500).max(5e4).optional().describe("Maximum tokens to return. Truncates the token sheet to fit.")
       }),
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({ css, name, maxTokens }) => tracked("extract-design-system", { name: name ?? null }, async () => {
       const result = extractDesignSystem(css, name);
@@ -7558,7 +7564,13 @@ function fail(message) {
     }
   };
 }
-function registerIllustrationTools({ server, track, tracked, authContext }) {
+function registerIllustrationTools({
+  server,
+  track,
+  tracked,
+  authContext,
+  apiFetch = globalThis.fetch
+}) {
   const authHeaders2 = () => {
     const headers = { "Content-Type": "application/json" };
     if (authContext) {
@@ -7591,7 +7603,7 @@ Markup carrying script, event handlers, remote references, or styles that reach
         reviewToken: z7.string().optional().describe("The token from a previous review of this drawing. Reviews it again free.")
       }),
       outputSchema: REVIEW_OUTPUT_SCHEMA,
-      annotations: { readOnlyHint: true }
+      annotations: READ_ONLY_TOOL_ANNOTATIONS
     },
     async ({
       svg,
@@ -7603,7 +7615,7 @@ Markup carrying script, event handlers, remote references, or styles that reach
       { query: intent, animated, repeat: Boolean(reviewToken) },
       async () => {
         try {
-          const res = await fetch(`${APP_BASE_URL}/api/illustrations/review`, {
+          const res = await apiFetch(`${APP_BASE_URL}/api/illustrations/review`, {
             method: "POST",
             headers: authHeaders2(),
             signal: AbortSignal.timeout(6e4),
@@ -7719,9 +7731,9 @@ var init_preview_resource = __esm({
 });
 
 // ../shared/src/mcp/tools.ts
-function registerAllTools(server, provider, onToolUsage, authContext, options = {}) {
+function registerAllTools(server, provider, onToolUsage, authContext, options = {}, apiFetch = globalThis.fetch) {
   const { track, tracked } = createTracking(server, onToolUsage);
-  const deps = { server, provider, track, tracked, authContext };
+  const deps = { server, provider, track, tracked, authContext, apiFetch };
   registerPrincipleTools(deps, options);
   registerComprehensionTools(deps);
   registerIconTools(deps);
@@ -7763,17 +7775,25 @@ function createMcpServer(options) {
     authContext,
     enableReactNativeGuide = true,
     enableThreeJsGuide = true,
-    enableShopifyKit = true
+    enableShopifyKit = true,
+    apiFetch = globalThis.fetch
   } = options;
   const server = new McpServer(
     { name, version },
     { instructions: getMcpInstructions({ enableReactNativeGuide, enableThreeJsGuide }) }
   );
-  registerAllTools(server, provider, onToolUsage, authContext, {
-    enableReactNativeGuide,
-    enableThreeJsGuide,
-    enableShopifyKit
-  });
+  registerAllTools(
+    server,
+    provider,
+    onToolUsage,
+    authContext,
+    {
+      enableReactNativeGuide,
+      enableThreeJsGuide,
+      enableShopifyKit
+    },
+    apiFetch
+  );
   return server;
 }
 var init_mcp = __esm({