roast-my-design-system 5.0.0 → 5.0.2
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.
package/README.md
CHANGED
|
@@ -6,6 +6,8 @@
|
|
|
6
6
|
|
|
7
7
|
A free CLI tool (and Claude Code skill) that roasts your repo's design system with real data, then generates the rules that keep your AI agent on-system.
|
|
8
8
|
|
|
9
|
+
> **New in 5.0: it runs as a local MCP server.** One command, and your agent asks the design system before writing UI, then gets the work checked after: which Button is canonical, which token holds that colour, review my changes. Local, deterministic, nothing leaves your machine. See [Live answers over MCP](#live-answers-over-mcp).
|
|
10
|
+
|
|
9
11
|
Run it on your codebase and get, in about a second:
|
|
10
12
|
|
|
11
13
|
- **A health score you can defend in a meeting.** 0-100, deterministic, benchmarked against Ideal Design System norms, 34 scanned public repos and 10 reputable design systems (Primer, Polaris, Carbon, shadcn/ui…).
|
|
@@ -22,21 +24,21 @@ Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in
|
|
|
22
24
|
|
|
23
25
|
One scan powers all of it; the flags decide what lands on disk. Combine freely.
|
|
24
26
|
|
|
25
|
-
| Command | What you get |
|
|
27
|
+
| Command | What you get |
|
|
26
28
|
|---|---|
|
|
27
|
-
|
|
|
28
|
-
|
|
|
29
|
+
| <code>npx roast-my-design-system</code> | The scan and `design-system-roast.html`, opened in your browser |
|
|
30
|
+
| <code>npx roast-my-design-system <path></code> | Scan a different repo than the current directory |
|
|
29
31
|
| `... --apply` | The generated agent rules injected straight into every agent file you have: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `.cursor/rules/`, `.windsurfrules` and `.github/copilot-instructions.md`, inside a marked block. Re-running replaces only that block, never your own text. Windsurf and Copilot get a compact variant sized for their limits |
|
|
30
32
|
| `... --rules` | The same rules written to `design-system-rules.md` instead, for pasting by hand |
|
|
31
33
|
| `... --card` | `roast-card.svg`: a shareable 1200x630 card with the score and worst findings. Pure SVG, embeds in a README |
|
|
32
34
|
| `... --sarif` | `design-system-roast.sarif` for GitHub code scanning: upload it in CI and findings appear in the Security tab, annotated on files |
|
|
33
35
|
| `... --mcp` | The scan as a local MCP server: five tools your agent calls while writing UI, from "is there a Button already?" to "review my changes". See [Live answers over MCP](#live-answers-over-mcp) |
|
|
34
36
|
| `... --check` | The working tree's changed files checked against the design system, in the terminal. Exits 1 on findings, so it slots into scripts |
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
+
| <code>... --by "Dwayne Hicks"</code> | A requester credit in the report header, next to the scan date |
|
|
38
|
+
| <code>... --exclude lab/</code> | Leave a folder out of the scan (repeat the flag or comma-separate). Or list folders in a `.roastignore` file at the repo root. Either way the report says so in the header; see [Scoping the scan](#scoping-the-scan) |
|
|
37
39
|
| `... --json` | The scan summary as JSON on stdout, for scripts and pipelines |
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
+
| <code>... --theme light</code> / <code>--out <file></code> / <code>--no-open</code> | Light report, custom report path, don't open the browser |
|
|
41
|
+
| <code>/roast-my-design-system</code> (in Claude Code) | The full experience: the roast in chat, the report, the rules offer, and the fix loop with Claude on your own numbers |
|
|
40
42
|
|
|
41
43
|
**One scan writes rules for every agent: Claude, Cursor, GitHub Copilot, and Windsurf.** Every scan also checks the agent rules you already have and flags stale references, no flag needed.
|
|
42
44
|
|
|
@@ -49,11 +51,11 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
|
|
|
49
51
|
|
|
50
52
|
The full report for vercel/ai-chatbot, top to bottom:
|
|
51
53
|
|
|
52
|
-
|
|
53
55
|
|
|
54
56
|
The same report in light mode (one file, built-in toggle):
|
|
55
57
|
|
|
56
|
-
|
|
57
59
|
|
|
58
60
|
## What makes the numbers trustworthy
|
|
59
61
|
|
|
@@ -105,8 +107,6 @@ claude mcp add roast -- npx roast-my-design-system --mcp
|
|
|
105
107
|
|
|
106
108
|
Any MCP client can register the same stdio command (tested with Claude Code; Cursor and Windsurf speak the same protocol). Same promise as the scan: local, read-only, one scan at startup, no port, no account, nothing about your code leaves your machine. And a clean answer reads "no measured violations found" with the list of checks attached, because a scanner can only certify what it can count.
|
|
107
109
|
|
|
108
|
-
<!-- demo video: open this README in the GitHub web editor and drag demo_mcp_roast.mp4 here -->
|
|
109
|
-
|
|
110
110
|
## In CI
|
|
111
111
|
|
|
112
112
|
The scanner already speaks SARIF, so wiring it into GitHub code scanning is six lines. Findings appear in the Security tab, annotated on the files themselves:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "roast-my-design-system",
|
|
3
|
-
"version": "5.0.
|
|
3
|
+
"version": "5.0.2",
|
|
4
4
|
"description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 34 public repos, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"design-system",
|
|
@@ -22,38 +22,40 @@ import { VERSION } from '../lib/version.mjs';
|
|
|
22
22
|
const PROTOCOL = '2025-06-18';
|
|
23
23
|
|
|
24
24
|
// ---------- tool + resource + prompt catalogue ----------
|
|
25
|
+
// Descriptions are budgeted: every client loads them into every session, so
|
|
26
|
+
// each one carries only what changes an agent's tool choice (5.0.1 trim).
|
|
25
27
|
const TOOLS = [
|
|
26
28
|
{
|
|
27
29
|
name: 'roast_get_context',
|
|
28
|
-
description: '
|
|
29
|
-
inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Repo-relative folder
|
|
30
|
+
description: 'Design-system context before writing UI in this repo: tokens, canonical components, duplicates, spacing and type rules, from a real scan. Optional path ("packages/ui") narrows the slice.',
|
|
31
|
+
inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Repo-relative folder (optional)' } } },
|
|
30
32
|
},
|
|
31
33
|
{
|
|
32
34
|
name: 'roast_find_component',
|
|
33
|
-
description: '
|
|
35
|
+
description: 'Find the canonical component for a name or intent ("icon button"). Returns import path, usage count and a real usage example, or an honest zero. Ties are reported, never guessed.',
|
|
34
36
|
inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Component name or intent' } }, required: ['query'] },
|
|
35
37
|
},
|
|
36
38
|
{
|
|
37
39
|
name: 'roast_find_token',
|
|
38
|
-
description: '
|
|
39
|
-
inputSchema: { type: 'object', properties: { value: { type: 'string', description: '
|
|
40
|
+
description: 'Snap a raw value (#111111, 13px) to this repo\'s nearest token or scale step. Says so when no scale exists.',
|
|
41
|
+
inputSchema: { type: 'object', properties: { value: { type: 'string', description: 'Colour or length value' } }, required: ['value'] },
|
|
40
42
|
},
|
|
41
43
|
{
|
|
42
44
|
name: 'roast_validate',
|
|
43
|
-
description: 'Check code
|
|
44
|
-
inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'The code to check' }, file: { type: 'string', description: 'Intended file path (optional
|
|
45
|
+
description: 'Check code before saving: hardcoded colours, near-token twins, off-scale spacing, arbitrary brackets, inline styles, !important, duplicate components. Findings name the fix.',
|
|
46
|
+
inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'The code to check' }, file: { type: 'string', description: 'Intended file path (optional)' } }, required: ['code'] },
|
|
45
47
|
},
|
|
46
48
|
{
|
|
47
49
|
name: 'roast_review',
|
|
48
|
-
description: 'Review the working tree\'s changed files (git diff + untracked) against the design system. Reads the diff itself; send no code. Call before finishing
|
|
50
|
+
description: 'Review the working tree\'s changed files (git diff + untracked) against the design system. Reads the diff itself; send no code. Call before finishing UI work.',
|
|
49
51
|
inputSchema: { type: 'object', properties: {} },
|
|
50
52
|
},
|
|
51
53
|
];
|
|
52
54
|
|
|
53
55
|
const RESOURCES = [
|
|
54
|
-
{ uri: 'roast://rules', name: 'Design system rules', description: '
|
|
55
|
-
{ uri: 'roast://components', name: 'Component ledger', description: '
|
|
56
|
-
{ uri: 'roast://tokens', name: 'Token map', description: 'Colour tokens
|
|
56
|
+
{ uri: 'roast://rules', name: 'Design system rules', description: 'Generated agent rules, compact', mimeType: 'text/markdown' },
|
|
57
|
+
{ uri: 'roast://components', name: 'Component ledger', description: 'Canonical picks, duplicates, never-imported, with usage counts', mimeType: 'text/plain' },
|
|
58
|
+
{ uri: 'roast://tokens', name: 'Token map', description: 'Colour tokens and spacing values in real use', mimeType: 'text/plain' },
|
|
57
59
|
];
|
|
58
60
|
|
|
59
61
|
const PROMPTS = [
|
|
@@ -129,7 +131,7 @@ export function serve(root) {
|
|
|
129
131
|
protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL,
|
|
130
132
|
capabilities: { tools: {}, resources: {}, prompts: {} },
|
|
131
133
|
serverInfo: { name: 'roast-my-design-system', version: VERSION },
|
|
132
|
-
instructions: '
|
|
134
|
+
instructions: 'Design-system answers for this repo, from a real scan, all local and read-only. Loop: roast_get_context before building, find_component / find_token while building, roast_validate before saving, roast_review before finishing.',
|
|
133
135
|
});
|
|
134
136
|
return;
|
|
135
137
|
case 'notifications/initialized':
|