better-design 0.8.3 → 0.11.0

package/README.md

@@ -10,6 +10,8 @@ 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.
 
+Using ZCode? Follow the [ZCode MCP setup guide](https://better-design.com/mcp/install/zcode) to add Better Design as an HTTP server.
+
 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.
@@ -20,21 +22,39 @@ The server exposes MCP tools only; it does not register prompts.
 
 | Tool | Purpose |
 | --- | --- |
-| `find-design-system` | Search the Better Design catalog and return design system IDs. (For building an app, prefer `create-design-system` to generate the user's own brand.) |
-| `get-design-system-docs` | Return shadcn install commands and component source for a design system. Default path in any real project (filesystem + terminal): build real React components. Base UI (@base-ui/react) is the default flavor; pass `library: "radix"` for the Radix flavor when the project already uses Radix. |
+| `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. |
+| `draw-illustration` | Draw an original SVG illustration for a screen: an empty state, a hero object, a container something drops into. Uses the caller's brand colours when a `projectId` is passed, and returns named layers so parts can animate. Drawing runs in the background. |
+| `get-illustration-status` | Collect a drawing started by `draw-illustration`. Returns the complete svg and its layer names once ready. |
+| `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. Accepts a catalog `designSystemId`, or a generated `projectId` for the HTML target. 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-design-system-html` | Export a framework-free HTML/CSS kit (real tokens + each system's real component material: card depth, button gradient/rim, switch fill, badge radius) for inline chat canvases only (ChatGPT canvas / Claude artifact) with no filesystem or build step; otherwise use `get-design-system-docs` and build React. Takes a catalog `designSystemId` OR a generated `projectId`; lists covered vs interactive-excluded components. |
 | `get-ui-principle` | Load or search visual UI principles. |
 | `get-ux-principle` | Load or search flow and interaction principles. |
-| `get-review-rules` | Return the Better Design self-review checklist. Supports `category`: `accessibility`, `visual-design`, `content`, or `all`. |
+| `get-react-native-guide` | Load or search implementation guidance and code recipes for React Native and Expo projects. |
+| `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. |
 | `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
 
 `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.