roast-my-design-system 9.0.7 → 9.1.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
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
<img src="assets/
|
|
1
|
+
<img src="assets/roastmds.svg" width="100" alt="roast-my-design-system">
|
|
2
2
|
|
|
3
3
|
# roast-my-design-system
|
|
4
4
|
|
|
5
|
-
[](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) [](#what-makes-the-numbers-trustworthy)
|
|
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) [](#what-makes-the-numbers-trustworthy)
|
|
6
6
|
|
|
7
7
|
[](#live-answers-over-mcp) [](#live-answers-over-mcp) [](#live-answers-over-mcp)
|
|
8
8
|
|
|
@@ -10,77 +10,123 @@
|
|
|
10
10
|
|
|
11
11
|
Your AI can write the UI. This makes sure it writes *your* UI.
|
|
12
12
|
|
|
13
|
-
An agent builds UI the way a new hire does on their first day: it looks around the repo and copies what it finds. We measured that on 10 real products, 259 agent sessions, with and without this tool. On everyday work the agent reused the components and tokens that were there and stayed on-system. It went off-system in the places where the repo had no answer to copy. A chart, in a codebase with no chart palette. A theme, where nobody had named the surfaces. And it filled each gap the way the repo's own code did: by hand.
|
|
14
|
-
|
|
15
13
|
```bash
|
|
16
14
|
npx roast-my-design-system@latest
|
|
17
15
|
```
|
|
18
16
|
|
|
19
|
-
Run it at the root of a UI repo.
|
|
17
|
+
Run it at the root of a UI repo. One second later, a report opens.
|
|
18
|
+
No account. No network. No telemetry. Nothing in your repo changes.
|
|
19
|
+
|
|
20
|
+
**Current release: 9.1.** Version history in [CHANGELOG.md](CHANGELOG.md).
|
|
21
|
+
|
|
22
|
+
## The idea
|
|
23
|
+
|
|
24
|
+
### An agent copies what it finds.
|
|
25
|
+
|
|
26
|
+
### It invents where the repo has no answer.
|
|
27
|
+
|
|
28
|
+
We tested this on 10 real open-source products, 259 agent sessions, with and without this tool.
|
|
29
|
+
|
|
30
|
+
Findings each session added, counted by this tool's own rules:
|
|
31
|
+
|
|
32
|
+
| Task | Model | Without roast | Roast MCP and rules installed | Roast edit hook on |
|
|
33
|
+
|---|---|---|---|---|
|
|
34
|
+
| Add a panel, build a dashboard, tighten a list (80 sessions) | Sonnet 5 | 7 | 9 | not run |
|
|
35
|
+
| A Christmas theme, 10 products | Sonnet 5 | 28 | 2 | not run |
|
|
36
|
+
| A new chart, 4 products, 5 runs each | Sonnet 5 | 10 in 20 runs | 0 in 20 runs, hook installed too but it never had to speak | |
|
|
37
|
+
| A new chart, 4 products | Haiku 4.5 | 25 | 39 | 0 in 14 of 15 runs |
|
|
38
|
+
| Chart, status colour, empty state, new component | Haiku 4.5 | 42 in 16 runs | 49 in 16 runs | 3 in 51 runs |
|
|
20
39
|
|
|
21
|
-
|
|
40
|
+
Routine work stayed on-system either way. Invention drifted.
|
|
22
41
|
|
|
23
|
-
|
|
42
|
+
Sonnet called the MCP tools in about one session in three. Haiku never did, so for Haiku the MCP on its own changed nothing. The edit hook runs without being asked, and that is the column that goes to zero.
|
|
24
43
|
|
|
25
|
-
|
|
44
|
+
Where did the agent invent? Where the repo had nothing to copy. Dub has no chart palette. Its own charts hardcode 17 colours. Asked for a chart, Haiku hardcoded 9 more.
|
|
26
45
|
|
|
27
|
-
|
|
46
|
+
So the mess an agent adds is a map of the gaps in your system.
|
|
47
|
+
|
|
48
|
+
This tool draws the map.
|
|
49
|
+
|
|
50
|
+
## Roast. Teach. Guard.
|
|
51
|
+
|
|
52
|
+
**Roast** the repo to find its real design system, the mess in it, and the gaps.
|
|
53
|
+
|
|
54
|
+
**Teach** the agent, through generated rules and a local MCP server.
|
|
55
|
+
|
|
56
|
+
**Guard** every edit, so the agent does not have to remember to ask.
|
|
57
|
+
|
|
58
|
+
ROAST what is in the repo, and what is missing
|
|
59
|
+
↓
|
|
60
|
+
TEACH rules in the agent files, answers over MCP
|
|
61
|
+
↓
|
|
62
|
+
GUARD every edit checked, the PR gated
|
|
28
63
|
|
|
29
64
|
## What you get
|
|
30
65
|
|
|
31
|
-
|
|
66
|
+
### Where agents will invent
|
|
32
67
|
|
|
33
|
-
|
|
68
|
+
The places where the repo has no answer yet.
|
|
34
69
|
|
|
35
|
-
|
|
70
|
+
- the gap, in one line
|
|
71
|
+
- the files that prove it
|
|
72
|
+
- the one move that closes it
|
|
36
73
|
|
|
37
|
-
|
|
74
|
+
One gap is known for certain today, because the runs found it: charts hardcoding colours in a repo with no chart palette. 43 of 126 public repos look like that. A gap joins the list when it has been measured.
|
|
38
75
|
|
|
39
|
-
|
|
76
|
+
### Fix what makes agents guess
|
|
40
77
|
|
|
41
|
-
|
|
78
|
+
The mess the agent will copy, ranked by what fixing it is worth.
|
|
42
79
|
|
|
43
|
-
|
|
80
|
+
- what was found
|
|
81
|
+
- where, with the file path
|
|
82
|
+
- why it matters
|
|
83
|
+
- what to change
|
|
84
|
+
- a copy button with the fix prompt for your agent
|
|
44
85
|
|
|
45
|
-
|
|
86
|
+
Fix, rescan, press the next button.
|
|
46
87
|
|
|
47
|
-
|
|
48
|
-
npx roast-my-design-system@latest
|
|
49
|
-
```
|
|
88
|
+
### A score you can defend in a meeting
|
|
50
89
|
|
|
51
|
-
|
|
90
|
+
0 to 100. The same number every run.
|
|
52
91
|
|
|
53
|
-
|
|
92
|
+
Measured against three yardsticks: the ideal norms of a design system, the median of 34 product repos at the core of a 112-repo benchmark, and 10 reputable systems (Primer, Polaris, Carbon, shadcn/ui and others).
|
|
54
93
|
|
|
55
|
-
|
|
56
|
-
claude mcp add roast -- npx roast-my-design-system@latest --mcp
|
|
57
|
-
```
|
|
94
|
+
Monorepos get a score per package. `packages/ui` at 80 stops hiding `apps/web` at 40.
|
|
58
95
|
|
|
59
|
-
###
|
|
96
|
+
### Every finding, with its file path
|
|
60
97
|
|
|
61
|
-
|
|
98
|
+
- every hardcoded colour, and its near-identical twin
|
|
99
|
+
- every spacing value off the scale
|
|
100
|
+
- every duplicated component
|
|
62
101
|
|
|
63
|
-
|
|
64
|
-
npx roast-my-design-system@latest --check
|
|
65
|
-
```
|
|
102
|
+
And 8 more kinds, all in [What it measures](#what-it-measures). One HTML file. Open it, Slack it, email it.
|
|
66
103
|
|
|
67
|
-
|
|
104
|
+
### Rules for your agent
|
|
68
105
|
|
|
69
|
-
|
|
106
|
+
Generated from your repo, into `design-system-rules.md`:
|
|
70
107
|
|
|
71
|
-
|
|
108
|
+
canonical components
|
|
109
|
+
the token file
|
|
110
|
+
known duplicates to avoid
|
|
111
|
+
spacing steps
|
|
112
|
+
typefaces
|
|
113
|
+
the kit's own vocabulary
|
|
72
114
|
|
|
73
|
-
|
|
115
|
+
`--apply` writes them into every agent file you have: Claude, Cursor, GitHub Copilot, Windsurf. Every scan also checks the rules you already have for stale references.
|
|
74
116
|
|
|
75
|
-
|
|
76
|
-
- **42 in 16 runs, to 3 in 51.** Haiku 4.5 asked for a chart, a status colour, an empty state and a new component, without the tool and with the edit hook on.
|
|
77
|
-
- **10 in 20 runs, to 0 in 20.** Sonnet 5 asked for a chart, without and with the plugin installed. It called no tool and the hook never had to speak: the rules in its context were enough.
|
|
117
|
+
### A script does the counting
|
|
78
118
|
|
|
79
|
-
|
|
119
|
+
Every number comes from a deterministic read of your files. Claude writes the explanation, labelled as written by AI and kept apart from the numbers.
|
|
120
|
+
|
|
121
|
+
## How the runs were done
|
|
122
|
+
|
|
123
|
+
Claude Code, headless, on 10 public products pinned to one commit each: cal.com, Dub, Metabase, Plausible, SigNoz, trigger.dev and four more. 259 sessions, Sonnet 5 and Haiku 4.5, September 2026. Every changed file was judged by this tool's rules at the end of the session and at the pinned commit; a finding counts only if the session added it.
|
|
124
|
+
|
|
125
|
+
Nothing was rendered. Zero findings means on-system by these rules: a floor, not a design review. Method, tables and limits are in the research write-up, which will be published separately.
|
|
80
126
|
|
|
81
127
|
## Live examples
|
|
82
128
|
|
|
83
|
-
Eleven reports, hosted exactly as the tool writes them
|
|
129
|
+
Eleven reports, hosted exactly as the tool writes them. Every number deterministic, every path real.
|
|
84
130
|
|
|
85
131
|
- **[npx shadcn create, fresh](https://gregkozakiewicz.github.io/roast-my-design-system/examples/shadcn-create-fresh.html)** (factory install, all 61 components): read as a fresh install, "the score is the kit's, not yours"; 13 colours, every theme variable in place, shadcn's own 24 bracket values named and not counted. No score.
|
|
86
132
|
- **[Unleash](https://gregkozakiewicz.github.io/roast-my-design-system/examples/unleash-mui.html)** (MUI): 1,109 files import the kit and the theme is read 6,166 times; 4 colours and 2 spacings per 100 kit files are written onto components. Score 60.
|
|
@@ -94,38 +140,43 @@ Eleven reports, hosted exactly as the tool writes them: self-contained HTML, eve
|
|
|
94
140
|
- **[magicuidesign/magicui](https://gregkozakiewicz.github.io/roast-my-design-system/examples/magicui.html)** (registry): counted on the components it publishes, 52 off-theme colours per 100 files in the code it ships, its docs site kept out and named. Score 78.
|
|
95
141
|
- **[adobe/spectrum-web-components](https://gregkozakiewicz.github.io/roast-my-design-system/examples/adobe-spectrum.html)** (Lit): hardcoded colours sitting beside 744 colour tokens, and 37 !important declarations. Score 66.
|
|
96
142
|
|
|
97
|
-
The full report for vercel/ai-chatbot,
|
|
143
|
+
The full report for vercel/ai-chatbot. The verdict answers what the agent will learn here, the gap section comes first, then "What the repo teaches the agent", Claude's read of the scan:
|
|
98
144
|
|
|
99
|
-
|
|
100
146
|
|
|
101
147
|
The same report in light mode (one file, built-in toggle):
|
|
102
148
|
|
|
103
|
-
|
|
150
|
+
|
|
151
|
+
## Why the numbers hold
|
|
104
152
|
|
|
105
|
-
|
|
153
|
+
- **Deterministic.** A zero-dependency Node script reads every file and returns the same numbers every run. About a second on a normal repo.
|
|
154
|
+
- **Read-only. No network. No telemetry.** The test suite fails if package.json ever declares a dependency.
|
|
155
|
+
- **Honest gaps.** What the scan cannot read says "not measured" and drops out of the score.
|
|
156
|
+
- **Honest exclusions.** Tests, stories, docs sites, artwork and email templates are left out. Your own exclusions are printed in the report header with file counts.
|
|
157
|
+
- **A real benchmark.** 112 public React repos. A core fleet of 34 sets the medians; the rest feed the kit profiles, so a shadcn repo is compared with shadcn repos. The builder is in `tools/benchmark/`.
|
|
158
|
+
- **Importable scoring.** `scoreHarvest(harvest)` returns the score and metrics as plain data. The report and a CI check get the same numbers.
|
|
106
159
|
|
|
107
|
-
|
|
108
|
-
- **Read-only, no network, no telemetry.** Nothing in your repo is modified and nothing about your code leaves your machine. The suite fails if package.json ever declares a dependency.
|
|
109
|
-
- **Honest gaps and exclusions.** What the scan cannot read says "not measured" and drops out of the score. Test files, stories, docs sites, artwork and email templates are left out, and your own exclusions are printed in the report header with file counts.
|
|
110
|
-
- **A real benchmark.** 112 public React repos scanned; a core fleet of 34 sets the medians, the rest feed the kit profiles so a shadcn repo is compared with shadcn repos. Ten reputable systems (Primer, Polaris, Carbon, GOV.UK and others) are the second yardstick. The builder is in `tools/benchmark/`, so the ruler can be checked.
|
|
111
|
-
- **Importable scoring.** `scoreHarvest(harvest)` returns the score and metrics as plain data; the report and a CI check get the same numbers.
|
|
160
|
+
The long version, with scan scoping and what the plugin runs on your machine, is in [docs/reference.md](docs/reference.md).
|
|
112
161
|
|
|
113
|
-
|
|
162
|
+
## Works with
|
|
114
163
|
|
|
115
|
-
|
|
164
|
+
### Frameworks
|
|
116
165
|
|
|
117
|
-
|
|
166
|
+
React, Next.js, Remix, Vite
|
|
167
|
+
Stencil, Lit, custom elements
|
|
118
168
|
|
|
119
|
-
|
|
120
|
-
- Web-component repos: Stencil and Lit.
|
|
121
|
-
- 4 kinds of repo: product, library, shadcn, registry.
|
|
122
|
-
- 5 kit profiles: Tailwind theme, MUI, Mantine, Chakra, Ant Design.
|
|
123
|
-
- Any styling on top: Tailwind, styled-components, Emotion, Sass, Less, vanilla-extract, Stitches, CVA, CSS Modules.
|
|
169
|
+
### Kits and styling
|
|
124
170
|
|
|
125
|
-
|
|
171
|
+
Tailwind, shadcn/ui, MUI, Mantine, Chakra UI, Ant Design
|
|
172
|
+
CSS Modules, Sass, Less, Emotion, styled-components, vanilla-extract, CVA, Stitches
|
|
126
173
|
|
|
127
|
-
|
|
128
|
-
|
|
174
|
+
Four kinds of repo: product, library, shadcn install, registry. Each compared with repos built the same way.
|
|
175
|
+
|
|
176
|
+
### Recognised, not measured yet
|
|
177
|
+
|
|
178
|
+
Vue, Angular, Svelte: named in the header, colours and spacing counted, components not measured. The report says so.
|
|
179
|
+
HeroUI, NextUI, Radix Themes, Fluent UI, React Bootstrap, Grommet: named in the header, no kit rules.
|
|
129
180
|
|
|
130
181
|
## Every command
|
|
131
182
|
|
|
@@ -152,13 +203,13 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
|
|
|
152
203
|
|
|
153
204
|
| Command | What you get |
|
|
154
205
|
|---|---|
|
|
155
|
-
| <code>... --notes <file.md></code> | The agent's read of this scan, embedded in the report as **"What the
|
|
206
|
+
| <code>... --notes <file.md></code> | The agent's read of this scan, embedded in the report as **"What the repo teaches the agent"**: 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 |
|
|
156
207
|
| <code>... --section "Title" <file.md></code> | A further agent-written chapter after the notes, same styling, same label, sub-headings allowed. Repeatable |
|
|
157
208
|
| `... --hook` | The check the Claude Code plugin runs after every edit, for hand-installed setups: reads the hook event on stdin, checks the file that changed, prints only the findings the edit added as JSON. Always exits 0 |
|
|
158
209
|
| `... --mcp` | The scan as a local MCP server: 5 tools your agent calls while writing UI, plus the `roast-fix` prompt that serves the top fix from a fresh scan. See [Live answers over MCP](#live-answers-over-mcp) |
|
|
159
|
-
| <code>/roast-my-design-system</code> (in Claude Code) | The full experience: the roast in chat *and* embedded in the report as "What the
|
|
210
|
+
| <code>/roast-my-design-system</code> (in Claude Code) | The full experience: the roast in chat *and* embedded in the report as "What the repo teaches the agent", the rules offer, and the fix loop with Claude on your own numbers |
|
|
160
211
|
|
|
161
|
-
**"Why this matters"** is generic, ships with the tool and reads the same in every report. **"What the
|
|
212
|
+
**"Why this matters"** is generic, ships with the tool and reads the same in every report. **"What the repo teaches the agent"** is your agent's read of your repo, and only appears when an agent passed it.
|
|
162
213
|
|
|
163
214
|
## Live answers over MCP
|
|
164
215
|
|
|
@@ -292,13 +343,13 @@ It runs the same check as `--check` on the files in your git diff and lists each
|
|
|
292
343
|
You get the roast in chat plus `design-system-roast.html` at your repo root, a self-contained page with:
|
|
293
344
|
|
|
294
345
|
- a **health score** computed from how your numbers sit against the ideal
|
|
295
|
-
- **"What the
|
|
346
|
+
- **"What the repo teaches the agent"**: Claude's read of your scan, embedded in the file you'll forward, labelled as written by Claude and kept apart from the measured numbers. The score alone can flatter; this section keeps a shared 85/100 honest
|
|
296
347
|
- stat tiles comparing you to all 3 yardsticks
|
|
297
348
|
- a **light/dark theme toggle** in one file
|
|
298
349
|
- the usage-weighted palette bar, the grey ramp, the off-scale spacing receipts, the duplicate-component receipts with clickable file paths, and the worst-offenders ledger
|
|
299
|
-
- a **
|
|
300
|
-
- a **Where agents will invent**
|
|
301
|
-
-
|
|
350
|
+
- a **Fix what makes agents guess** list: up to 3 moves derived from your repo's own numbers, each with a file-path receipt
|
|
351
|
+
- a **Where agents will invent** section, first under the verdict: the gaps where the repo has no answer yet, with the files that prove each one and the move that closes it, or the honest empty state when none is found
|
|
352
|
+
- **Give the agent the answers**: `design-system-rules.md` wrapped inside the report as a present. Unwrap, then copy or download the agent rules generated from your scan
|
|
302
353
|
|
|
303
354
|
After the roast, the skill offers to write `design-system-rules.md` to disk and merge it into your CLAUDE.md, `.cursor/rules` or AGENTS.md.
|
|
304
355
|
|
|
@@ -360,8 +411,6 @@ Yes, the median repo is already a mess. That is the point. An agent arriving in
|
|
|
360
411
|
|
|
361
412
|
**Your AI can write the UI. This makes sure it writes *your* UI.**
|
|
362
413
|
|
|
363
|
-
<a href="https://github.com/gregkozakiewicz/roast-my-design-system"><img src="https://img.shields.io/badge/If%20it%20roasted%20you%20fairly%2C%20a%20star%20helps%20other%20people%20find%20it-a855f7?style=for-the-badge&logo=github&logoColor=white" alt="If it roasted you fairly, a star helps other people find it"></a>
|
|
364
|
-
|
|
365
414
|
## License
|
|
366
415
|
|
|
367
416
|
MIT. The code is yours to fork, modify and redistribute; the copyright notice travels with it.
|
package/cli/roast.mjs
CHANGED
|
@@ -100,7 +100,7 @@ Run it yourself
|
|
|
100
100
|
For your agent (a plain terminal has no agent to write these)
|
|
101
101
|
|
|
102
102
|
--notes <file> the agent's read of this scan, embedded in the report as
|
|
103
|
-
"What the
|
|
103
|
+
"What the repo teaches the agent", labelled as written by AI and kept
|
|
104
104
|
apart from the measured numbers. The Claude Code skill
|
|
105
105
|
writes and passes this automatically
|
|
106
106
|
--section "Title" <file>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "roast-my-design-system",
|
|
3
|
-
"version": "9.0
|
|
3
|
+
"version": "9.1.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 112 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": [
|
|
@@ -351,6 +351,15 @@ let verdict = noSystemLikely
|
|
|
351
351
|
? 'This repo is in good shape, and your agent has rules to read. Keep them in step with the code.'
|
|
352
352
|
: 'This repo is in good shape. The gap is documentation: your agent still can\'t see the system.')
|
|
353
353
|
: findings.slice(0, 3).join('. ') + '.';
|
|
354
|
+
// The lead line answers the report's question before the measured verdict
|
|
355
|
+
// does: does this repo give an agent something to copy, and where does it
|
|
356
|
+
// not. A gap named here is one lib/gaps admitted after a fleet probe.
|
|
357
|
+
const gapLead = (noSystemLikely || fresh) ? '' : (() => {
|
|
358
|
+
const gaps = h.gaps ?? [];
|
|
359
|
+
if (!gaps.length) return 'This repo gives an agent something to copy everywhere this scan can measure.';
|
|
360
|
+
const named = gaps.map((g) => g.title.charAt(0).toLowerCase() + g.title.slice(1));
|
|
361
|
+
return `Most of this repo gives an agent something to copy. ${gaps.length === 1 ? 'One gap remains' : `${gaps.length} gaps remain`}: ${esc(named.join('; '))}.`;
|
|
362
|
+
})();
|
|
354
363
|
if (bench && findings.length && !fresh) {
|
|
355
364
|
const core = [['colors', tokenLed ? colorStrays : colors.length], ['greys', tokenLed ? greyStrays : greys.length],
|
|
356
365
|
['spacing', spacingTotal], ['typefaces', typefaces.length], ['exactDuplicates', hardDupes.length], ['inlineStyles', inline.count]];
|
|
@@ -958,7 +967,7 @@ function componentsSection() {
|
|
|
958
967
|
function giftSection() {
|
|
959
968
|
const { text: rulesText, ruleCount } = rulesMarkdown(h);
|
|
960
969
|
return `<section class="glass pad gift-sec">
|
|
961
|
-
${sectionHead('
|
|
970
|
+
${sectionHead('Give the agent the answers', 'the rules file generated from this scan, wrapped as a present. Agents do not always ask before inventing, so the plugin also checks every file they edit, and guard-my-design-system checks the pull request.')}
|
|
962
971
|
<div class="gift-stage">
|
|
963
972
|
<button class="gift" id="gift" aria-label="Unwrap your generated agent rules file">
|
|
964
973
|
<svg viewBox="0 0 64 64" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
|
|
@@ -1020,7 +1029,7 @@ function notesSection() {
|
|
|
1020
1029
|
return `<section class="glass pad notes-sec">
|
|
1021
1030
|
<div class="sec-head">
|
|
1022
1031
|
${eyebrow(`Written by ${esc(arg('notes-author', 'Claude'))} from this scan · ${esc((h.harvestedAt ?? '').slice(0, 10))} · not part of the measurement`)}
|
|
1023
|
-
<h2>What the
|
|
1032
|
+
<h2>What the repo teaches the agent</h2>
|
|
1024
1033
|
</div>
|
|
1025
1034
|
<div class="notes-body">${notesBody(notesText)}</div>
|
|
1026
1035
|
</section>`;
|
|
@@ -1234,7 +1243,7 @@ function whereToStartSection() {
|
|
|
1234
1243
|
delta: item.delta || 0, prompt: promptFor(item),
|
|
1235
1244
|
}));
|
|
1236
1245
|
return `<section class="glass pad">
|
|
1237
|
-
${sectionHead('
|
|
1246
|
+
${sectionHead('Fix what makes agents guess', head)}
|
|
1238
1247
|
<div class="ledger">${top3.map((item, i) => `
|
|
1239
1248
|
<div class="ledger-row start-row">
|
|
1240
1249
|
<span class="ledger-idx">${String(i + 1).padStart(2, '0')}</span>
|
|
@@ -1249,10 +1258,15 @@ function whereToStartSection() {
|
|
|
1249
1258
|
// The September 2026 runs showed agents inventing exactly there; the section
|
|
1250
1259
|
// names the gap, the files that prove it and the one move that closes it.
|
|
1251
1260
|
function gapsSection() {
|
|
1261
|
+
if (noSystemLikely || fresh) return '';
|
|
1252
1262
|
const gaps = h.gaps ?? [];
|
|
1253
|
-
if (!gaps.length)
|
|
1254
|
-
|
|
1255
|
-
|
|
1263
|
+
if (!gaps.length) {
|
|
1264
|
+
return `<section class="glass pad" style="margin-top:16px">
|
|
1265
|
+
${sectionHead('Where agents will invent', 'No gap found. This scan checks for one kind of gap so far, a chart palette, and this repo either has one or has no charts. The list grows as more gap kinds are measured on real agent runs; a clean result here says the known gaps are closed, and no more than that.')}
|
|
1266
|
+
</section>`;
|
|
1267
|
+
}
|
|
1268
|
+
const head = `${gaps.length === 1 ? 'One place' : `${gaps.length} places`} where this repo gives an agent nothing to copy. Asked to build there, an agent invents, because that is what the repo taught it. Nothing here is a violation: there is no rule yet to break. Define the answer once and every agent after that inherits it.`;
|
|
1269
|
+
return `<section class="glass pad" style="margin-top:16px">
|
|
1256
1270
|
${sectionHead('Where agents will invent', head)}
|
|
1257
1271
|
<div class="ledger">${gaps.map((g, i) => `
|
|
1258
1272
|
<div class="ledger-row gap-row">
|
|
@@ -1523,8 +1537,8 @@ function exclusionsLine() {
|
|
|
1523
1537
|
// Title and description come from the scan; an image and canonical URL are
|
|
1524
1538
|
// passed in when the report is hosted (--og-image, --og-url), never guessed.
|
|
1525
1539
|
function ogTags() {
|
|
1526
|
-
const title = `${repoName}:
|
|
1527
|
-
const desc =
|
|
1540
|
+
const title = `${repoName}: where an AI agent will invent UI${healthScore !== null ? ` · ${healthScore}/100` : ''}`;
|
|
1541
|
+
const desc = `${gapLead ? `${gapLead.replace(/<[^>]+>/g, '')} ` : ''}${verdict}`.replace(/\s+/g, ' ').trim().slice(0, 200);
|
|
1528
1542
|
const image = arg('og-image', null), url = arg('og-url', null);
|
|
1529
1543
|
return [
|
|
1530
1544
|
`<meta property="og:type" content="website">`,
|
|
@@ -1636,7 +1650,7 @@ function exceptionsBlock() {
|
|
|
1636
1650
|
function addIndex(page) {
|
|
1637
1651
|
// heading text is already HTML-escaped; strip tags and leading counts only
|
|
1638
1652
|
const short = (t) => t.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim().replace(/^[\d,]+ /, '')
|
|
1639
|
-
.replace(/^What your AI agent sees today$/, 'What your agent sees').replace(/^
|
|
1653
|
+
.replace(/^What your AI agent sees today$/, 'What your agent sees').replace(/^Give the agent the answers$/, 'Agent rules').replace(/^What the repo teaches the agent$/, 'What it teaches').replace(/^Fix what makes agents guess$/, 'What to fix')
|
|
1640
1654
|
.replace(/^The shadcn theme and the 2 shadcn checks$/, 'shadcn theme and checks')
|
|
1641
1655
|
.replace(/^Your Tailwind theme, and what goes around it$/, 'Your Tailwind theme').replace(/^Your (\w+) theme, and what is written around it$/, 'Your $1 theme').replace(/, declared .*$/, '')
|
|
1642
1656
|
.replace(/^off-scale spacing values$/, 'Off-scale spacing').replace(/^inline style blocks?$/, 'Inline styles').replace(/^typefaces?$/, 'Typefaces');
|
|
@@ -1772,6 +1786,9 @@ ${ogTags()}
|
|
|
1772
1786
|
.verdict-card .b1 { right:-64px; top:-64px; width:256px; height:256px; background:var(--blob); filter:blur(48px); }
|
|
1773
1787
|
.verdict-card .b2 { left:-40px; bottom:-80px; width:224px; height:224px; background:var(--blob2); filter:blur(48px); }
|
|
1774
1788
|
.verdict { position:relative; font:600 clamp(18px,2.6vw,24px)/1.45 var(--disp); letter-spacing:-.01em; margin-top:10px; }
|
|
1789
|
+
.verdict-sub { position:relative; margin-top:12px; font-size:14.5px; line-height:1.6; color:var(--dim); }
|
|
1790
|
+
.gap-empty { padding:0 26px 22px; color:var(--dim); font-size:14px; line-height:1.6; }
|
|
1791
|
+
.gap-why { margin-top:6px; color:var(--dim); font-size:13.5px; }
|
|
1775
1792
|
|
|
1776
1793
|
section, .agent { margin-top:28px; }
|
|
1777
1794
|
|
|
@@ -2093,18 +2110,18 @@ ${sidePanel()}
|
|
|
2093
2110
|
: `There is most likely <b>no design system in this repo</b>: almost no colour or spacing values were found. Styling may live outside this codebase (CDN stylesheets, a parent repo, or generated output). No score is given.`}</span></div>` : ''}
|
|
2094
2111
|
<div class="glass verdict-card">
|
|
2095
2112
|
<div class="blob b1"></div><div class="blob b2"></div>
|
|
2096
|
-
${eyebrow('Summary')}
|
|
2097
|
-
|
|
2113
|
+
${eyebrow(noSystemLikely || fresh ? 'Summary' : 'What will your agent learn here?')}
|
|
2114
|
+
${gapLead ? `<div class="verdict">${gapLead}</div><div class="verdict-sub">${esc(verdict)}</div>` : `<div class="verdict">${esc(verdict)}</div>`}
|
|
2098
2115
|
</div>
|
|
2099
2116
|
|
|
2117
|
+
${gapsSection()}
|
|
2118
|
+
|
|
2100
2119
|
${notesSection()}
|
|
2101
2120
|
|
|
2102
2121
|
${extraSectionsHtml()}
|
|
2103
2122
|
|
|
2104
2123
|
${whereToStartHtml}
|
|
2105
2124
|
|
|
2106
|
-
${gapsSection()}
|
|
2107
|
-
|
|
2108
2125
|
${agentSection()}
|
|
2109
2126
|
|
|
2110
2127
|
${giftSection()}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Where agents will invent. The September 2026 runs (
|
|
2
|
+
* Where agents will invent. The September 2026 runs (259 sessions, 10 real
|
|
3
3
|
* products) showed agents copying what a repo already has and inventing only
|
|
4
4
|
* where the design system has no answer: a theme, a chart. A gap is a place
|
|
5
5
|
* where the next piece of UI, human or agent, has nothing to reuse, so the
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// Single version constant for the engine — imported by diagnose (report
|
|
2
2
|
// footer) and rules (generated-by line). This is the bump spot that used to
|
|
3
3
|
// live as a const inside diagnose/index.mjs.
|
|
4
|
-
export const VERSION = '9.0
|
|
4
|
+
export const VERSION = '9.1.0';
|
|
5
5
|
// The shape of harvest.json and summary.json. Bumped only when a field is
|
|
6
6
|
// renamed, removed or changes meaning; a new field is not a new schema. A
|
|
7
7
|
// tool comparing two scans compares like with like by this number, not by VERSION.
|