roast-my-design-system 5.12.2 → 6.0.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.
- package/README.md +30 -30
- package/package.json +1 -1
- package/skills/roast-my-design-system/scripts/benchmark/benchmark.json +573 -573
- package/skills/roast-my-design-system/scripts/diagnose/index.mjs +14 -1
- package/skills/roast-my-design-system/scripts/harvest/collisions.mjs +94 -0
- package/skills/roast-my-design-system/scripts/harvest/tokens.mjs +81 -10
- package/skills/roast-my-design-system/scripts/lib/color.mjs +20 -0
- package/skills/roast-my-design-system/scripts/lib/guard-api.mjs +5 -1
- package/skills/roast-my-design-system/scripts/lib/version.mjs +1 -1
package/README.md
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
<img src="https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/roaster_logo_300px.png?v=6.0.0" width="72" alt="roast-my-design-system">
|
|
2
|
+
|
|
1
3
|
# roast-my-design-system
|
|
2
4
|
|
|
3
5
|
[](https://www.npmjs.com/package/roast-my-design-system) [](https://www.npmjs.com/package/roast-my-design-system) [](https://socket.dev/npm/package/roast-my-design-system) [](LICENSE) [](https://www.npmjs.com/package/roast-my-design-system?activeTab=dependencies) [](https://github.com/gregkozakiewicz/roast-my-design-system#what-makes-the-numbers-trustworthy)
|
|
@@ -8,13 +10,7 @@
|
|
|
8
10
|
|
|
9
11
|
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.
|
|
10
12
|
|
|
11
|
-
> **New in
|
|
12
|
-
|
|
13
|
-
> **New in 5.11: the checker and the CI guard stop contradicting each other.** `roast --check` and [guard-my-design-system](https://github.com/gregkozakiewicz/guard-my-design-system) both answer "does this change fit the system", and they disagreed in seven places. A second hand-rolled `<Button>` passed the guard. A new radius, font size, shadow or typeface passed `--check` and was then stopped in CI. Both now measure the same things. And both leave alone the files that cannot be on-system: email, print, OG cards, PDF invoices, pixel renderers and SVG artwork. A skipped file is never called clean; the result says what was left unjudged and why.
|
|
14
|
-
|
|
15
|
-
> **New in 5.9: the agent card knows which doors your rules actually reach.** The report now states, as plain fact, which tools can read the rules files you have. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Cursor reads AGENTS.md and `.cursor/rules`. Where a door is missing, the card shows the one-line fix: Claude Code skips AGENTS.md, and a CLAUDE.md containing the single line `@AGENTS.md` closes the gap. The scan also finds rules files nested in subfolders, which is how monorepos really do it (twenty carries 35 AGENTS.md files; a root-only look reported 1). It recognises GEMINI.md, `.windsurf/rules` and `.github/instructions` too.
|
|
16
|
-
|
|
17
|
-
> **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).
|
|
13
|
+
> **New in 6.0: a dark mode is not sprawl, and the ruler has been rebuilt.** A system with a dark theme states most of its colours twice. One with a density switch states its spacing twice again. Every restatement was counted, so the systems doing the most work scored the worst. Now only a token's first statement counts. A factory-fresh shadcn install goes from 20 colours to 16, and Shoelace from 420 to 219. Two related faults went with it. `border-radius: var(--radius)` was counted as a radius value, so Polaris showed 49 radii of which 36 were references to its own tokens, and Telekom showed 52 font sizes of which 48 were. A new finding names one token holding two different colours in two packages of a monorepo, which fires 8 times across 19 real repos. The benchmark was rebuilt with all of it, so every score is measured against a ruler that counts the same way: cal.com 15 to 20, Cloudscape 35 to 40, MUI 50 to 55. If you have a score from 5.x, take a fresh one before you compare.
|
|
18
14
|
|
|
19
15
|
Run it on your codebase and get, in about a second:
|
|
20
16
|
|
|
@@ -33,30 +29,34 @@ Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in
|
|
|
33
29
|
|
|
34
30
|
One scan powers all of it; the flags decide what lands on disk. Combine freely.
|
|
35
31
|
|
|
36
|
-
|
|
32
|
+
### Run it yourself
|
|
33
|
+
|
|
34
|
+
Type these in a terminal and you get a result.
|
|
37
35
|
|
|
38
|
-
| Command | What you get |
|
|
36
|
+
| Command | What you get |
|
|
39
37
|
|---|---|
|
|
40
|
-
|
|
|
41
|
-
|
|
|
38
|
+
| <code>npx roast-my-design-system@latest</code> | The scan and `design-system-roast.html`, opened in your browser |
|
|
39
|
+
| <code>... <path></code> | Scan a different repo than the current directory |
|
|
42
40
|
| `... --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 |
|
|
43
41
|
| `... --rules` | The same rules written to `design-system-rules.md` instead, for pasting by hand |
|
|
44
42
|
| `... --card` | `roast-card.svg`: a shareable 1200x630 card with the score and worst findings. Pure SVG, embeds in a README |
|
|
45
43
|
| `... --sarif` | `design-system-roast.sarif` for GitHub code scanning: upload it in CI and findings appear in the Security tab, annotated on files |
|
|
46
44
|
| `... --check` | The working tree's changed files checked against the design system, in the terminal. Exits 1 on findings, so it slots into scripts |
|
|
47
|
-
|
|
|
45
|
+
| <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) |
|
|
48
46
|
| `... --json` | The scan summary as JSON on stdout, for scripts and pipelines |
|
|
49
|
-
|
|
|
50
|
-
|
|
|
47
|
+
| <code>... --by "Dwayne Hicks"</code> | Puts a name in the report header, for when you ran it for someone else |
|
|
48
|
+
| <code>... --theme light</code> / <code>--out <file></code> / <code>--no-open</code> / <code>--open</code> | Light report, custom report path, never open the browser, always open it |
|
|
49
|
+
|
|
50
|
+
### For your agent
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
These need an agent.
|
|
53
53
|
|
|
54
|
-
| Command | What you get |
|
|
54
|
+
| Command | What you get |
|
|
55
55
|
|---|---|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
56
|
+
| <code>... --notes <file.md></code> | The agent's read of this scan, embedded in the report as **"What the numbers mean"**: which findings matter, which good numbers are accidents, what to fix first. Labelled as written by AI and kept apart from the measured numbers. The Claude Code skill writes and passes it automatically; the flag is here so any agent can |
|
|
57
|
+
| <code>... --section "Title" <file.md></code> | A further agent-written chapter after the notes, same styling, same label, sub-headings allowed. Repeatable, so analysis that outgrows the notes still lives inside the report instead of a hand-built page |
|
|
58
58
|
| `... --mcp` | The scan as a local MCP server: 5 tools your agent calls while writing UI, from "is there a Button already?" to "review my changes", plus the `roast-fix` prompt that serves the top fix from a fresh scan. See [Live answers over MCP](#live-answers-over-mcp) |
|
|
59
|
-
|
|
|
59
|
+
| <code>/roast-my-design-system</code> (in Claude Code) | The full experience: the roast in chat *and* embedded in the report as "What the numbers mean", the rules offer, and the fix loop with Claude on your own numbers |
|
|
60
60
|
|
|
61
61
|
Not to be confused with each other: **"Why this matters"** is generic, ships with the tool and reads the same in every report. **"What the numbers mean"** is your agent's read of your repo, and only appears when an agent passed it.
|
|
62
62
|
|
|
@@ -71,11 +71,11 @@ Not to be confused with each other: **"Why this matters"** is generic, ships wit
|
|
|
71
71
|
|
|
72
72
|
The full report for vercel/ai-chatbot, top to bottom, including "What the numbers mean", Claude's read of the scan, embedded right under the verdict:
|
|
73
73
|
|
|
74
|
-
|
|
75
75
|
|
|
76
76
|
The same report in light mode (one file, built-in toggle):
|
|
77
77
|
|
|
78
|
-
|
|
79
79
|
|
|
80
80
|
## What makes the numbers trustworthy
|
|
81
81
|
|
|
@@ -236,16 +236,16 @@ After the roast, the skill also offers to write `design-system-rules.md` to disk
|
|
|
236
236
|
|
|
237
237
|
| Metric | Ideal Design System | Median of 34 scanned repos | Median of 10 reputable systems |
|
|
238
238
|
|---|---|---|---|
|
|
239
|
-
| Distinct colours | ~24 |
|
|
240
|
-
| Shades of grey | up to 13 |
|
|
241
|
-
| Off-scale spacing values | ~12 |
|
|
239
|
+
| Distinct colours | ~24 | 127 | 20 |
|
|
240
|
+
| Shades of grey | up to 13 | 26 | 5 |
|
|
241
|
+
| Off-scale spacing values | ~12 | 33 | 6 |
|
|
242
242
|
| Typefaces | 2 to 3 | 3 | 1 |
|
|
243
|
-
|
|
|
244
|
-
| Duplicated components | 0 |
|
|
245
|
-
| Inline style blocks | 0 |
|
|
246
|
-
| Arbitrary Tailwind values | ~20 |
|
|
247
|
-
| Near-identical colour pairs | 0 |
|
|
248
|
-
| !important declarations | 0 |
|
|
243
|
+
| Off-scale border radii | up to 10 | 14 | 0 |
|
|
244
|
+
| Duplicated components | 0 | 21 | 12 |
|
|
245
|
+
| Inline style blocks | 0 | 51 | 12 |
|
|
246
|
+
| Arbitrary Tailwind values | ~20 | 82 | 0 |
|
|
247
|
+
| Near-identical colour pairs | 0 | 11 | 1 |
|
|
248
|
+
| !important declarations | 0 | 10 | 3 |
|
|
249
249
|
| Components never imported | 0 | 0 | 0 |
|
|
250
250
|
|
|
251
251
|
Yes, the median repo is already a mess. That's the point.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "roast-my-design-system",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "6.0.0",
|
|
4
4
|
"mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
|
|
5
5
|
"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, reads React and web components (Stencil, Lit), hands you a copy-paste fix prompt for each top finding, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
|
|
6
6
|
"keywords": [
|