better-design 0.15.0 → 0.19.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 (4) hide show
  1. package/README.md +47 -56
  2. package/dist/index.js +2381 -537
  3. package/dist/index.js.map +1 -1
  4. package/package.json +3 -1
package/README.md CHANGED
@@ -1,71 +1,62 @@
1
- # better-design
1
+ # Better Design
2
2
 
3
- Design systems, UI principles, icons, and code review for AI coding agents. [better-design.com](https://better-design.com)
3
+ ## Give your AI real design skills
4
4
 
5
- ## Install
5
+ Better Design connects your coding agent to design systems, UI and UX guidance, icons, and quality reviews.
6
+
7
+ Use it to design and build for web, mobile, Shopify, 3D, and product video.
6
8
 
7
9
  ```bash
8
10
  npx better-design
9
11
  ```
10
12
 
11
- 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.
12
-
13
- Using ZCode? Follow the [ZCode MCP setup guide](https://better-design.com/mcp/install/zcode) to add Better Design as an HTTP server.
14
-
15
- 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).
16
-
17
- > 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.
18
-
19
- ## Tools
20
-
21
- The server exposes MCP tools only; it does not register prompts.
13
+ Run it once. The installer detects your supported coding tools and adds Better Design without overwriting their existing configuration.
22
14
 
23
- | Tool | Purpose |
24
- | --- | --- |
25
- | `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. |
26
- | `create-design-system` | Start a custom design system generation job. |
27
- | `get-design-system-status` | Poll a generated design system and return the install command when ready. |
28
- | `review-illustration` | Render an SVG illustration you drew, look at it, and report what is visibly wrong |
29
- | `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. |
30
- | `preview-design-system` | Return a token-true visual preview for a catalog design system. |
31
- | `get-ui-principle` | Load or search visual UI principles. |
32
- | `get-ux-principle` | Load or search flow and interaction principles. |
33
- | `get-react-native-guide` | Load or search implementation guidance and code recipes for React Native and Expo projects. |
34
- | `get-three-js-guide` | Load or search implementation guidance and code recipes for Three.js and React Three Fiber projects. |
35
- | `get-motion-guide` | Load or search guidance for building a product demo video in code, from composition setup to checking the render. |
36
- | `get-review-rules` | Return the Better Design self-review checklist. Supports `category`: `accessibility`, `visual-design`, `animation`, `content`, `comprehension`, or `all`. |
37
- | `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. |
38
- | `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. |
39
- | `find-icon-library` | Find an icon library for an app or project style. |
40
- | `find-icons` | Search icons by name, library, and variant. |
41
- | `install-icons` | Generate local icon components in the target project. |
42
- | `detect-icon-library` | Read an existing icon-library manifest and report the active library. |
15
+ Free. No account required.
43
16
 
44
- ## Retrieve Principles
17
+ Works with Codex, Claude Code, Cursor, VS Code, Windsurf, and other MCP clients.
45
18
 
46
- 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.
47
-
48
- ```text
49
- get-ui-principle({ topic: "blur test" })
50
- get-ui-principle({ query: "group this dense settings screen with clearer proximity" })
51
- get-ux-principle({ topic: "reward design" })
52
- get-ux-principle({ query: "confirm a high-stakes action with control rather than celebration" })
53
- get-ux-principle({ topic: "clarity audit" })
54
- get-ux-principle({ topic: "motion brief" })
55
- ```
19
+ ## What your agent can do
56
20
 
57
- 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.
21
+ - Find, generate, or extract a design system.
22
+ - Build with consistent, editable components and styles.
23
+ - Apply guidance for interfaces, interactions, motion, mobile, Shopify, and 3D.
24
+ - Find and install a matching icon library.
25
+ - Review accessibility, usability, content, and visual quality, against the guidance the session already loaded.
58
26
 
59
- ## Setup Behavior
27
+ Your code stays in your repo and remains yours to change.
60
28
 
61
- `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.
62
-
63
- Options:
29
+ ## Tools
64
30
 
65
- | Option | Description |
31
+ | Tool | Purpose |
66
32
  | --- | --- |
67
- | `-y`, `--yes` | Non-interactive: skip prompts, auto-create a key. |
68
- | `BETTER_DESIGN_API_KEY` | Use your own key instead of auto-provisioning. |
69
- | `--global` | Install at user/global scope when the client supports it. |
70
- | `--project` | Install in the current project when the client supports it. |
71
- | `--help` | Print setup usage. |
33
+ | `find-design-system` | Find a catalog system for a requested interface. |
34
+ | `get-design-system-kit` | Retrieve installable React, HTML, or Shopify kit output. |
35
+ | `get-design-system-status` | Check a generated system's progress and result. |
36
+ | `create-design-system` | Generate a custom design system for a product. Pass an extracted token sheet as `brandCss` to build from the user's own brand instead of a catalog look-alike. |
37
+ | `preview-design-system` | Show a token-true preview for a system. |
38
+ | `get-ui-principle` | Load visual guidance for layout, type, color, polish, and accessibility. |
39
+ | `get-ux-principle` | Load guidance for flows, forms, navigation, errors, onboarding, and behavior. |
40
+ | `get-react-native-guide` | Load React Native and Expo build guidance. |
41
+ | `get-three-js-guide` | Load Three.js and React Three Fiber build guidance. |
42
+ | `get-motion-guide` | Load animation and motion guidance. |
43
+ | `get-review-rules` | Review UI output for visual, UX, content, accessibility, and motion issues. Names the principles this session already loaded and orders their rules first. |
44
+ | `check-comprehension` | Check whether a finished interface communicates clearly. Names the principles this session already loaded. |
45
+ | `extract-design-system` | Extract a brand from any mix of sources: pasted CSS, a computed-style sample from the live site, or a design-tokens export (W3C or Figma variables). |
46
+ | `extract-from-url` | Point it at a public URL: the server fetches the site's stylesheets, renders the page in a headless browser, and returns the brand as an oklch token sheet. |
47
+ | `find-icon-library` | Pick an icon library that fits the project. |
48
+ | `find-icons` | Find icons inside a selected library. |
49
+ | `install-icons` | Install selected icons into the local project. |
50
+ | `detect-icon-library` | Detect an existing icon library in the project. |
51
+ | `review-illustration` | Review illustration output against Better Design rules. |
52
+
53
+ ## Explore Better Design
54
+
55
+ [Design systems](https://better-design.com/design-systems) ·
56
+ [Templates](https://better-design.com/templates) ·
57
+ [Slides](https://better-design.com/slides) ·
58
+ [Shopify](https://better-design.com/shopify) ·
59
+ [Video](https://better-design.com/video)
60
+
61
+ [See Better Design](https://better-design.com) ·
62
+ [Installation guide](https://better-design.com/mcp/install)