roast-my-design-system 3.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Greg Kozakiewicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# roast-my-design-system
+
+## A Claude Code skill that roasts your repo's design system with real data.
+
+Run this skill on your codebase and get three things: a health score for your design system, the receipts behind it (every colour, spacing value, duplicated component and inline style, with real file paths), and the first fixes ranked by payoff. It benchmarks you against an Ideal Design System, 29 scanned public repos, and 10 reputable design systems (Primer, Polaris, Carbon, shadcn/ui…), and generates one shareable HTML report: **keep it as the audit, or hand it to Claude as the punch list for the fix.**
+
+## Why this exists
+
+Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in your repo. If your repo has 112 colours and four Button implementations, your agent guesses which one is canonical, and it picks wrong half the time. That's why AI-generated UI looks *almost-but-not-quite* right. The first step to fixing it is seeing the mess measured.
+
+## Example use cases
+
+- **Pre-refactor audit.** Run `/roast-my-design-system` before a design-system cleanup to get the measured baseline: every colour, spacing value, duplicated component and inline style, with real file paths.
+- **Diagnosing almost-right AI output.** When Claude keeps generating UI that looks slightly off, the report shows which duplicated components and stray values it is imitating, and where the canonical ones live.
+- **Making the case without a meeting.** Drop the self-contained HTML report in Slack: a health score and three benchmarks (ideal norms, the 29-repo median, 10 reputable systems) argue for the design system for you.
+- **The fix loop.** Hand the report back to Claude as the punch list and work through the Where to start section, file by file.
+
+The full report for vercel/ai-chatbot, top to bottom:
+
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png)
+
+The same report in light mode (one file, built-in toggle):
+
+![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png)
+
+## What makes the numbers trustworthy
+
+- **Deterministic scanner, not AI sampling.** A zero-dependency Node script reads *every* file (a 5,000-file monorepo takes ~1.5s) and returns the same numbers every run. Claude narrates; it never counts.
+- **Read-only.** Nothing in your repo is modified. The only outputs are a temp JSON and the HTML report.
+- **No network, no telemetry.** Everything runs locally. Nothing about your code leaves your machine.
+- **Honest exclusions.** Test files, Storybook stories, docs sites, example apps, SVG artwork, and email templates (which *must* inline styles) are excluded, so you can't discredit the numbers on a technicality.
+- **Intent-aware counting (v3).** Runtime-computed inline styles, compound-component APIs and wrapper components are not crimes and are not counted as ones. Token-led repos are judged on their hardcoded strays, not their token architecture. Repeated arbitrary values are read as decisions without names, not drift.
+- **A real benchmark.** The "Avg Design System" yardstick comes from scanning 29 public React repos (cal.com, excalidraw, outline, twenty, dub, langfuse…). Median: 88 colours, 12 greys, 17 duplicated components, 42 inline style blocks.
+- **A second yardstick: reputable systems.** Curated, scoped scans of 10 well-known design systems (shadcn/ui, Primer, Polaris, Carbon, Material UI, Chakra, Ant Design, GOV.UK, Spectrum, Cloudscape) show what disciplined looks like at scale.
+
+## Install
+
+**No install, no Claude needed — just try it:**
+
+```bash
+npx roast-my-design-system
+```
+
+Run it inside any repo. Same scanner, same report, straight from npm. Add `--theme light`, `--out <file>` or `--no-open` if you want them. The Claude Code skill below adds the conversation on top: the roast in chat, then a punch list you can actually work through with Claude.
+
+**Claude Code (recommended):**
+
+```bash
+/plugin marketplace add pencilrebel/roast-my-design-system
+/plugin install roast-my-design-system@roast-my-design-system
+```
+
+If those commands error, your Claude Code is likely older than the plugin marketplace feature: update Claude Code and retry, or just use the manual route below (it works everywhere and installs the same skill).
+
+**Manual (Claude Code, any version):**
+
+```bash
+git clone https://github.com/pencilrebel/roast-my-design-system.git
+cp -r roast-my-design-system/skills/roast-my-design-system ~/.claude/skills/
+```
+
+(Use `.claude/skills/` inside a repo instead to share it with your team.)
+
+**OpenAI Codex CLI** (same SKILL.md, same folder):
+
+```bash
+git clone https://github.com/pencilrebel/roast-my-design-system.git
+cp -r roast-my-design-system/skills/roast-my-design-system ~/.codex/skills/
+```
+
+Invoke with `$roast-my-design-system` (or let Codex auto-match it). Use `.codex/skills/` inside a repo to share with your team.
+
+**`npx skills`:** `npx skills add pencilrebel/roast-my-design-system` works for agents that read `~/.agents/skills/`. Claude Code currently reads `~/.claude/skills/`, so prefer one of the routes above.
+
+Requires Node 18+.
+
+## Use
+
+Open Claude Code in the repo you want roasted and type:
+
+```
+/roast-my-design-system
+```
+
+You get the roast in chat plus `design-system-roast.html` at your repo root: a self-contained page (open it, Slack it, email it, no external requests) with:
+
+- a **health score** computed from how your numbers sit against the ideal
+- stat tiles comparing you to all three yardsticks: Ideal, the 29-repo average, and the reputable systems
+- a **light/dark theme toggle** in one file
+- 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
+- a **Where to start** close: up to three moves derived from your repo's own numbers, each with a file-path receipt
+
+## Live examples
+
+Three real roasts of public repos, hosted as-is (the same self-contained HTML the skill generates):
+
+- **[excalidraw/excalidraw](https://pencilrebel.github.io/roast-my-design-system/examples/excalidraw-excalidraw.html)**
+- **[dubinc/dub](https://pencilrebel.github.io/roast-my-design-system/examples/dubinc-dub.html)**
+- **[vercel/ai-chatbot](https://pencilrebel.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)**
+
+## What it measures
+
+| Metric | Ideal Design System | Median of 29 scanned repos | Median of 10 reputable systems |
+|---|---|---|---|
+| Distinct colours | ~24 | 88 | 24 |
+| Shades of grey | up to 13 | 12 | 5 |
+| Off-scale spacing values | ~12 | 26 | 6 |
+| Typefaces | 2–3 | 2 | 1 |
+| Border radii | up to 10 | 12 | 2 |
+| Duplicated components | 0 | 17 | 10 |
+| Inline style blocks | 0 | 42 | 11 |
+
+Yes, the median repo is already a mess. That's the point.
+
+## License
+
+MIT
+
+Built and designed by [Greg Kozakiewicz](https://gregkozakiewicz.com).

package/bin/roast.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * roast-my-design-system — npx entrypoint. Runs the same deterministic,
+ * zero-dependency scanner the Claude Code skill uses: harvest the repo,
+ * diagnose it against Ideal Design System norms and the 29-repo benchmark,
+ * write design-system-roast.html, open it, print the score.
+ *
+ *   npx roast-my-design-system [path] [--theme dark|light] [--out report.html] [--no-open]
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPTS = join(HERE, '../skills/roast-my-design-system/scripts');
+const VERSION = JSON.parse(readFileSync(join(HERE, '../package.json'), 'utf8')).version;
+
+const argv = process.argv.slice(2);
+function flag(name) {
+  const i = argv.indexOf(`--${name}`);
+  if (i === -1) return null;
+  argv.splice(i, 1);
+  return true;
+}
+function opt(name, fallback) {
+  const i = argv.indexOf(`--${name}`);
+  if (i === -1 || !argv[i + 1]) return fallback;
+  const v = argv[i + 1];
+  argv.splice(i, 2);
+  return v;
+}
+
+if (flag('version') || flag('v')) { console.log(VERSION); process.exit(0); }
+if (flag('help') || flag('h')) {
+  console.log(`roast-my-design-system ${VERSION}
+
+Usage: npx roast-my-design-system [path] [options]
+
+  path            repo to scan (default: current directory)
+  --theme <t>     dark | light (default: dark)
+  --out <file>    report path (default: design-system-roast.html in the repo)
+  --no-open       write the report without opening it
+
+Read-only scan. No network, no telemetry, nothing leaves your machine.`);
+  process.exit(0);
+}
+
+const noOpen = flag('no-open') === true;
+const theme = opt('theme', 'dark');
+const target = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());
+if (!existsSync(target) || !statSync(target).isDirectory()) {
+  console.error(`Not a directory: ${target}`);
+  process.exit(1);
+}
+const outPath = resolve(opt('out', join(target, 'design-system-roast.html')));
+
+const tmp = mkdtempSync(join(tmpdir(), 'roast-'));
+const harvestPath = join(tmp, 'harvest.json');
+const summaryPath = join(tmp, 'summary.json');
+
+function run(script, args) {
+  const r = spawnSync(process.execPath, [join(SCRIPTS, script), ...args], { stdio: 'inherit' });
+  if (r.status !== 0) {
+    rmSync(tmp, { recursive: true, force: true });
+    process.exit(r.status ?? 1);
+  }
+}
+
+console.log(`roast-my-design-system ${VERSION} · read-only scan, nothing leaves your machine\n`);
+run('harvest/index.mjs', [target, '--out', harvestPath]);
+console.log('');
+run('diagnose/index.mjs', [harvestPath, '--out', outPath, '--theme', theme, '--summary', summaryPath]);
+
+let summary = null;
+try { summary = JSON.parse(readFileSync(summaryPath, 'utf8')); } catch { /* report still exists */ }
+rmSync(tmp, { recursive: true, force: true });
+
+if (summary) {
+  const bad = summary.tiles.filter((t) => t.health === 'bad');
+  if (bad.length) {
+    console.log(`\n  worst offenders: ${bad.map((t) => `${t.value} ${t.label}`).join(' · ')}`);
+  }
+}
+
+console.log(`\nWant the fixes, not just the roast? The free Claude Code skill runs this same
+scan, then walks the punch list with you: https://github.com/pencilrebel/roast-my-design-system`);
+
+if (!noOpen) {
+  const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+  spawnSync(opener, [outPath], { stdio: 'ignore', shell: process.platform === 'win32' });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "roast-my-design-system",
+  "version": "3.2.0",
+  "description": "Roast your design system with real data. A deterministic, zero-dependency scanner that counts every colour, grey, spacing value, typeface, duplicated component and inline style in your repo, scores it 0-100 against Ideal Design System norms and a 29-repo benchmark, and generates a shareable HTML diagnosis.",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "css",
+    "audit",
+    "lint",
+    "tailwind",
+    "ui",
+    "claude-code",
+    "developer-tools"
+  ],
+  "homepage": "https://pencilrebel.github.io/roast-my-design-system/",
+  "bugs": "https://github.com/pencilrebel/roast-my-design-system/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pencilrebel/roast-my-design-system.git"
+  },
+  "license": "MIT",
+  "author": "Greg Kozakiewicz (https://gregkozakiewicz.com)",
+  "type": "module",
+  "bin": {
+    "roast-my-design-system": "bin/roast.mjs"
+  },
+  "files": [
+    "bin/",
+    "skills/roast-my-design-system/scripts/"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}