better-design

Design systems, UI principles, icons, and code review for AI coding agents. better-design.com

Install

npx better-design

Run it once. The installer detects your installed MCP clients (Claude Code, Cursor, VS Code, Windsurf, Zed, Cline, JetBrains, and more), writes the config merge-safe, and drops an auto-invoke rule so agents use Better Design on UI work automatically. Get an API key at 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.

Tools

The server exposes MCP tools only; it does not register prompts.

| Tool | Purpose | | --- | --- | | find-design | 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.) | | resolve-design-system | Deprecated alias of find-design, kept one release for backward compatibility. | | 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. | | create-design-system | Start a custom design system generation job. | | check-design-system-status | Poll a generated design system and return the install command when ready. | | 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. | | resolve-icon-library | Find an icon library for an app or project style. | | search-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. |

Setup Behavior

npx better-design prompts for an API key, clients, install scope, and whether to add auto-invoke rules. For non-interactive runs, set BETTER_DESIGN_API_KEY and pass --global or --project.

Client configs are merged into existing JSON, JSONC, TOML, or dedicated config files without removing other MCP servers. Existing files are backed up before writes, and files that contain bearer tokens are written with owner-only permissions.

The installer resolves scope per client before writing. If a client supports the requested scope, it uses that scope. If a client supports only one scope, the installer falls back to that supported scope and marks the summary, for example installed project (only scope this client supports). Auto-invoke rule targets use the same resolved per-client scope, so project-only clients such as Continue get project rules while global-only clients keep manual or global rule guidance.

Relevant configuration:

| Option | Description | | --- | --- | | BETTER_DESIGN_API_KEY | API key used for non-interactive setup. | | BETTER_DESIGN_API_URL | Overrides the MCP API base URL for generated client configs. | | --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. |