better-design 0.21.0 → 0.29.1

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 +54 -107
  2. package/dist/index.js +13847 -3514
  3. package/dist/index.js.map +1 -1
  4. package/package.json +15 -5
package/README.md CHANGED
@@ -1,129 +1,76 @@
1
1
  # Better Design
2
2
 
3
- ## Give your AI real design skills
3
+ Give your coding agent design systems, UI and UX guidance, icons, and code reviews through MCP.
4
4
 
5
- Better Design connects your coding agent to design systems, UI and UX guidance, icons, and quality reviews.
5
+ Works with Codex, Claude Code, Cursor, VS Code, Devin, Antigravity, and other MCP clients.
6
6
 
7
- Use it to design and build for web, mobile, Shopify, 3D, and product video.
7
+ ## Install
8
8
 
9
- Install the agent skill, then connect its MCP tools:
9
+ Run these commands in your project:
10
10
 
11
11
  ```bash
12
12
  npx skills add marvkr/better-design --skill better-design
13
13
  npx better-design
14
14
  ```
15
15
 
16
- Run each command once, then restart your coding agent. The first command teaches supported agents when to use Better Design. The second detects your coding tools and connects the MCP without overwriting their existing configuration.
17
-
18
- Free. No account required.
19
-
20
- Works with Codex, Claude Code, Cursor, VS Code, Windsurf, and other MCP clients.
21
-
22
- ## What your agent can do
23
-
24
- - Find, generate, or extract a design system.
25
- - Build with consistent, editable components and styles.
26
- - Apply guidance for interfaces, interactions, motion, mobile, Shopify, and 3D.
27
- - Build Shopify themes from ready-to-write files and MCP-served Liquid guidance, with no separate agent skill installation (private preview).
28
- - Find and install a matching icon library.
29
- - Review accessibility, usability, content, and visual quality, against the guidance the session already loaded.
30
-
31
- Your code stays in your repo and remains yours to change.
32
-
33
- ## Tools
34
-
35
- | Tool | Purpose |
36
- | --- | --- |
37
- | `find-design-system` | Find a catalog system for a requested interface. |
38
- | `get-design-system-kit` | Retrieve installable React, HTML, Shopify, or DTCG design-token output. |
39
- | `get-shopify-guide` | Load Shopify Liquid and theme-development guidance directly from Better Design (private preview). |
40
- | `get-design-system-status` | Check a generated system's progress and result. |
41
- | `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. |
42
- | `preview-design-system` | Show a token-true preview for a system. |
43
- | `get-ui-principle` | Load visual guidance for layout, type, color, polish, and accessibility. |
44
- | `get-ux-principle` | Load guidance for flows, forms, navigation, errors, onboarding, behavior, and landing page positioning. |
45
- | `get-react-native-guide` | Load React Native and Expo build guidance. |
46
- | `get-three-js-guide` | Load Three.js and React Three Fiber build guidance. |
47
- | `get-motion-guide` | Load animation and motion guidance. |
48
- | `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. |
49
- | `check-comprehension` | Check whether a finished interface communicates clearly. Names the principles this session already loaded. |
50
- | `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). |
51
- | `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. |
52
- | `find-icon-library` | Pick an icon library that fits the project. |
53
- | `find-icons` | Find icons inside a selected library. |
54
- | `install-icons` | Install selected icons into the local project. |
55
- | `detect-icon-library` | Detect an existing icon library in the project. |
56
- | `review-illustration` | Review illustration output against Better Design rules. |
57
- | `review-ui-code` | Deterministic review of React source: design-system drift, generated-UI tells, WCAG basics. |
58
-
59
- ## Review UI code like a PR bot
60
-
61
- The `review` command checks React code against deterministic UI and UX rules: native elements your design system already replaces, hardcoded colors and raw palette classes, `dark:` forks, generated-UI tells (letter-spaced capital labels, left-border callout boxes, gradient text, labels above titles, em dashes in copy), and WCAG basics. The same input always produces the same findings.
16
+ The first installs the agent skill. The second connects Better Design to your coding tools. Restart your agent after setup.
62
17
 
63
- ```bash
64
- npx better-design review # review changed files (vs HEAD, plus untracked)
65
- npx better-design review src/components # review specific files or folders
66
- npx better-design review --base main # review a branch, like a PR diff
67
- npx better-design review --json # machine-readable output for CI
68
- ```
18
+ If you have no account, setup creates a free key for you. Using that key accepts the [Terms of Service](https://better-design.com/terms) at the version setup prints.
69
19
 
70
- The command exits 1 when it finds critical or serious issues, so it works as a CI gate. Tune the threshold with `--fail-on critical|serious|moderate|none`.
20
+ Install links can record where you found Better Design with `npx better-design --source docs`.
21
+ Supported source labels are `docs`, `github`, `claude_directory`, `openai_catalog`, `campaign`, and `unknown` (the default).
22
+ The installer sends this label when creating a free key and records npm as the install method. It does not infer your referral source or active client from the editors installed on your computer.
71
23
 
72
- Put your agent on rails: install the Claude Code hook and every file write is checked in real time, with violations fed back to the agent so it self-corrects without your intervention.
24
+ ## Try it
73
25
 
74
- ```bash
75
- npx better-design review --install-hook
76
- ```
26
+ Ask your agent:
77
27
 
78
- Override the default rules per project in `.better-design/review.config.json`. For example, point element rules at your own component paths, or turn a rule group off:
79
-
80
- ```json
81
- {
82
- "rules": {
83
- "elements": {
84
- "button": { "use": "Button", "from": "@/ui/button" }
85
- },
86
- "semanticTokens": { "enabled": false }
87
- }
88
- }
89
- ```
28
+ > Use Better Design to build a settings page with my project's design system, then review it for accessibility and consistency.
90
29
 
91
- Agents can run the same checks through the `review-ui-code` MCP tool and fix the findings before presenting the result.
92
-
93
- ### Review every pull request
94
-
95
- Add this workflow to review UI code on each pull request. It fails the check when it finds critical or serious issues:
96
-
97
- ```yaml
98
- name: UI review
99
- on: pull_request
100
- jobs:
101
- review:
102
- runs-on: ubuntu-latest
103
- steps:
104
- - uses: actions/checkout@v4
105
- with:
106
- fetch-depth: 0
107
- - uses: actions/setup-node@v4
108
- with:
109
- node-version: "lts/*"
110
- - name: Review the changed UI code
111
- env:
112
- BASE_REF: ${{ github.base_ref }}
113
- run: npx -y better-design@^0.19 review --base "$(git merge-base "origin/${BASE_REF}" HEAD)"
114
- ```
30
+ ## Build a prototype from Figma
31
+
32
+ With the Better Design plugin open in a Figma file, `create-figma-prototype`
33
+ turns a frame into one HTML page built from that design system's components.
34
+ Name a frame, or omit the name to take the current selection. The server
35
+ starts a relay on `http://localhost:4397` that only the plugin talks to, so
36
+ the file never leaves your machine. This tool is local only: the hosted
37
+ connectors cannot reach your Figma.
115
38
 
116
- The `review` command needs version 0.19.0 or later, which the version range pins. Pass the branch through the environment rather than interpolating it into the script: a branch name is text a contributor controls, and `${{ }}` would place it straight into your shell.
39
+ A frame from a file that was not built from a Better Design library has no
40
+ components to map, so pass `mode: "model"` and a catalog `system`. The plugin
41
+ asks you to confirm the frame. Your agent is the model: the tool writes a
42
+ prompt file and the frame's image, your agent writes the page on its own
43
+ plan, and a second call with `frameId` and `answerPath` checks the page and
44
+ lists every layer that did not make it. No API key is needed. To use a local
45
+ model instead, pass `provider: "openai-compatible"`: the tool calls Ollama at
46
+ `http://localhost:11434/v1` with `gemma4:latest`, or the server in
47
+ `BETTER_DESIGN_MODEL_BASE_URL`, with `BETTER_DESIGN_MODEL_API_KEY` if it needs
48
+ one.
117
49
 
118
- To post the findings as review comments instead of failing the check, add `--json`, write the output to a file, and hand it to a script that calls the GitHub API. Better Design's own repository does this in `.github/workflows/ui-review.yml`.
50
+ ## Map your product's features and flows
119
51
 
120
- ## Explore Better Design
52
+ Your agent keeps a map of the product in `.better-design/feature-map.json`:
53
+ each feature, its flows, and the route, screen, components and data of every
54
+ step. `build-feature-map` drafts it from `git ls-files`, `read-feature-map`
55
+ names what a change to a flow touches, and `update-feature-map` adds, renames
56
+ or removes a feature or flow in one call. The map stays in your repository;
57
+ the tools store nothing.
58
+
59
+ ## Share your team's rules with every agent
60
+
61
+ Paste your team's rules into
62
+ [Team rules](https://better-design.com/dashboard/settings/team-rules), one
63
+ Markdown document of up to 32 KB. `get-team-rules` gives them to any agent
64
+ that uses your key, and `get-review-rules` checks the work against them.
65
+
66
+ ## Review UI code
67
+
68
+ Check changed JSX and TSX files in your project:
69
+
70
+ ```bash
71
+ npx better-design review
72
+ ```
121
73
 
122
- [Design systems](https://better-design.com/design-systems) ·
123
- [Templates](https://better-design.com/templates) ·
124
- [Slides](https://better-design.com/slides) ·
125
- [Shopify](https://better-design.com/shopify) ·
126
- [Video](https://better-design.com/video)
74
+ Run `npx better-design review --help` for options.
127
75
 
128
- [See Better Design](https://better-design.com) ·
129
- [Installation guide](https://better-design.com/mcp/install)
76
+ [Installation guide](https://better-design.com/mcp/install) · [Design systems](https://better-design.com/design-systems) · [Website](https://better-design.com)