roast-my-design-system 8.7.0 → 8.9.0

package/README.md

@@ -44,6 +44,7 @@ Run it on your codebase and get, in about a second:
 - **Reads React and web components alike.** Stencil, Lit and custom elements are detected by tag registration and counted by kebab tag. Libraries get composition maps, not adoption accusations. Earned token namespaces are named in the header. Anything the scan can not read is declared "not measured" instead of scored.
 - **The receipts behind it.** Every colour and its near-identical twin. Every spacing value, typeface, duplicated or never-imported component, inline style and !important. All with real file paths, in one self-contained HTML report you can open, Slack or email.
 - **The first fixes ranked by payoff, each with its prompt.** A "Where to start" list derived from your own numbers. Every move carries a copy button with a ready-made fix prompt for your agent: the finding, the files, the expected payoff, and rules that respect deliberate craft. Fix, re-run the scan, press the next button.
+- **Where agents will invent.** The places where the repo has no answer yet, so the next piece of UI, human or agent, will make one up. Today that is one gap, found by measuring 164 agent sessions on real products: charts that paint their series colours by hand in a repo with no chart palette. The section names the files and the one move that closes it.
 - **Rules that stop the mess coming back.** A generated `design-system-rules.md` with canonical components, your token file, and known duplicates to avoid, so your AI agent follows your system instead of guessing at it. `--apply` injects them into every agent file you have: Claude, Cursor, GitHub Copilot, and Windsurf. Every scan also checks the rules you already have for stale references: paths that no longer exist, components named canonical that nothing imports anymore. And the agent card states which tools can actually read the rules you have (Claude Code, Codex, Cursor), with the one-line fix where a door is missing.
 
 ## Why this exists
@@ -114,11 +115,11 @@ Not to be confused with each other: **"Why this matters"** is generic, ships wit
 
 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:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then the summary, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=8.2.2)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then the summary, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=8.9.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=8.2.2)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=8.9.0)
 
 ## What it works on
 
@@ -180,6 +181,8 @@ The report and the rules file describe the repo as it was at scan time. `--mcp`
 
 The loop: context before building, find while building, validate before saving, review before finishing.
 
+Charts get their own rule, because a chart needs several colours that differ from each other and most design systems never name them. In a repo that keeps a chart palette (its own `--chart-*` or `--series-*` tokens, a `chartColors` entry in the theme, or shadcn's `--chart-1` to `--chart-5` when a chart actually reads them), a colour written by hand in a chart file is a finding that names the palette. In a repo that has charts but no palette, a new chart that paints by hand gets one warning that names the existing chart doing the same and asks for the palette once. The first chart in a repo gets one warning asking for a name. The report never counted chart colours; the live checks now agree with it.
+
 The server reads the repo the way the report does. On a product built on MUI, Mantine, Chakra UI or Ant Design, the context names the theme file and the kit's own way of reading it, `roast_find_token` answers in spacing steps (`12px` is `p: 3` on a 4px MUI theme), and `roast_validate` and `roast_review` flag a colour or a pixel size written onto a kit component where the theme has a value. On a Tailwind theme or a shadcn repo they flag a palette class such as `text-gray-500` or `ring-green-500` where the theme names a colour of that kind.
 
 ### What a session looks like
@@ -222,7 +225,7 @@ It writes a first draft anyway and runs `roast_validate` before saving:
 Second draft: `color: 'text.secondary'`, `p: 1.5`, the radius read from the theme. `roast_validate` again:
 
 ```
-No measured violations found. Checked: hardcoded colours vs the token set, near-identical colour twins, off-scale spacing, off-scale radii, font sizes and shadows, typefaces outside the system, arbitrary bracket values, static inline style blocks, !important, duplicate component definitions, new colour tokens that twin an existing token, imports of a duplicate the canonical copy replaces, colours and pixel sizes written onto kit components where the theme has a value.
+No measured violations found. Checked: hardcoded colours vs the token set, near-identical colour twins, off-scale spacing, off-scale radii, font sizes and shadows, typefaces outside the system, arbitrary bracket values, static inline style blocks, !important, duplicate component definitions, new colour tokens that twin an existing token, imports of a duplicate the canonical copy replaces, chart colours against the chart palette, colours and pixel sizes written onto kit components where the theme has a value.
 ```
 
 Four calls, under 800 tokens in total, and the new component reads the theme instead of adding colour number 44. `roast_review` then checks the whole diff the same way before the agent says it is done.
@@ -336,6 +339,7 @@ You get the roast in chat plus `design-system-roast.html` at your repo root: a s
 - 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 3 moves derived from your repo's own numbers, each with a file-path receipt
+- a **Where agents will invent** list: the gaps where the repo has no answer yet, with the files that prove each one and the move that closes it
 - a **present** 🎁 below it: you sat through the roast, so `design-system-rules.md` is wrapped inside the report itself. Unwrap, then copy or download the agent rules generated from your scan.
 
 After the roast, the skill also offers to write `design-system-rules.md` to disk and merge it into your CLAUDE.md, `.cursor/rules` or AGENTS.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "8.7.0",
+  "version": "8.9.0",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "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.",
   "keywords": [

package/skills/roast-my-design-system/scripts/diagnose/index.mjs

@@ -1236,6 +1236,25 @@ function whereToStartSection() {
       </div>`).join('')}</div></section>`;
 }
 
+// ---------- where agents will invent ----------
+// A gap is a place where the next piece of UI has nothing to reuse (lib/gaps).
+// The September 2026 runs showed agents inventing exactly there; the section
+// names the gap, the files that prove it and the one move that closes it.
+function gapsSection() {
+  const gaps = h.gaps ?? [];
+  if (!gaps.length) return '';
+  const head = `${gaps.length === 1 ? 'One place' : `${gaps.length} places`} where this repo has no answer yet. An agent asked to build there will invent, because that is what the repo taught it. Close the gap once and the checks take over.`;
+  return `<section class="glass" style="margin-top:16px">
+    ${sectionHead('Where agents will invent', head)}
+    <div class="ledger">${gaps.map((g, i) => `
+      <div class="ledger-row gap-row">
+        <span class="ledger-idx">${String(i + 1).padStart(2, '0')}</span>
+        <div class="start-body"><div class="start-head"><div class="start-title">${esc(g.title)}</div></div><div class="sub">${esc(g.detail)}</div>
+        <div class="sub" style="margin-top:6px"><b>Close it:</b> ${esc(g.fix)}</div>
+        ${g.files?.length ? `<div class="chips-row" style="margin-top:8px">${g.files.map((f) => `<span class="chip mono">${esc(f)}</span>`).join('')}</div>` : ''}</div>
+      </div>`).join('')}</div></section>`;
+}
+
 // ---------- package by package ----------
 // One number for a monorepo hides which package is the problem. Each package
 // is judged on the same nine tiles, with usage counted repo-wide, so a shared
@@ -1860,10 +1879,10 @@ ${ogTags()}
   .ledger-row a.path { font-size:13px; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
   .ledger-pills { margin-left:auto; display:flex; gap:8px; flex-shrink:0; }
 
-  .start-row { align-items:flex-start; }
+  .start-row, .gap-row { align-items:flex-start; }
   .start-body { min-width:0; }
   .start-title { font:600 15px/1.4 var(--disp); }
-  .start-row .sub { margin-top:2px; overflow-wrap:anywhere; }
+  .start-row .sub, .gap-row .sub { margin-top:2px; overflow-wrap:anywhere; }
   .start-actions { display:flex; align-items:center; gap:10px; margin-top:10px; }
   .fixbtn { font:700 11.5px/1 var(--sans); padding:8px 13px; border-radius:8px; border:1px solid var(--accent);
     background:transparent; color:var(--accent); cursor:pointer; }
@@ -2076,6 +2095,8 @@ ${extraSectionsHtml()}
 
 ${whereToStartHtml}
 
+${gapsSection()}
+
 ${agentSection()}
 
 ${giftSection()}
@@ -2237,6 +2258,7 @@ if (summaryPath) {
     // what the page prints. Until 7.0.0 value was the formatted string.
     tiles: judgedTiles.map((t, i) => ({ metric: t.metric, label: t.label, value: t.value, display: bigStats[i].num, health: t.health })),
     ...(startMoves.length ? { moves: startMoves } : {}),
+    ...((h.gaps ?? []).length ? { gaps: h.gaps.map(({ id, title, files }) => ({ id, title, files })) } : {}),
     packages: (h.packages ?? []).filter((p) => p.scored && p.metrics)
       .map((p) => ({ dir: p.dir, name: p.name, ...(scorePackage(p.metrics) ?? {}) }))
       .filter((p) => p.score !== undefined)

package/skills/roast-my-design-system/scripts/harvest/index.mjs

@@ -14,7 +14,9 @@
  */
 import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { walkRepo, profileRepo } from './walk.mjs';
+import { walkRepo, profileRepo, readSource } from './walk.mjs';
+import { chartSystemOf } from '../lib/charts.mjs';
+import { designGaps } from '../lib/gaps.mjs';
 import { headerLines, detailLines } from './summary.mjs';
 import { harvestComponents } from './components.mjs';
 import { harvestTokens, isGrey } from './tokens.mjs';
@@ -155,6 +157,10 @@ const duplicates = findDuplicates(components, profile.uiDir, target, profile.uiD
   }
 }
 const context = harvestContext(target);
+// The chart palette the repo keeps, or the charts painting by hand without
+// one, and the gaps an agent will fill by inventing (lib/charts, lib/gaps).
+const charts = chartSystemOf(files, (f) => readSource(resolve(target, f)));
+const gaps = designGaps({ charts, tokenFile: tokens.tokenFile ?? null });
 const staleRules = ruleStaleness(target, components,
   new Set(neverImportedComponents(components, profile.uiDir).map((c) => c.name)),
   [...files.code, ...files.styles, ...files.other]);
@@ -263,6 +269,8 @@ const harvest = {
   duplicates,
   context,
   staleRules,
+  charts,
+  gaps,
   packages,
   // Active user exclusions with per-pattern removal counts. Present only when
   // something was excluded, so downstream renderers can trust its presence.

package/skills/roast-my-design-system/scripts/lib/charts.mjs

@@ -0,0 +1,146 @@
+/**
+ * Chart colours. A chart needs several colours that differ from each other,
+ * and most design systems never name them. Probe over the 126 benchmark
+ * repos (2026-09-25): charts in three quarters of them, a named chart palette
+ * in a quarter, and the biggest group (43) is charts painting their series
+ * by hand with no palette to point at. The report leaves chart colours out
+ * (a picture, not paint); the live checks counted every one, so the same
+ * file got two verdicts depending on the door. One rule now, three tiers:
+ *
+ *   1. The repo keeps a chart palette: its own names, or shadcn's default
+ *      --chart-1..5 when a chart actually reads them. A colour written by
+ *      hand in a chart is drift, and the finding names the palette.
+ *   2. No palette, but a chart already paints by hand. The new chart follows
+ *      a precedent rather than breaking a rule: one warning per file that
+ *      names the precedent and asks for the palette, once.
+ *   3. No palette, no chart: the first chart. One warning, so the colours
+ *      get a name before the second chart copies them.
+ *
+ * shadcn's --chart-1..5 arrive with the install whether or not any chart
+ * uses them (6 of the 126 repos), so they count as a palette only when a
+ * chart reads them; otherwise the repo is tier 2 with the fix ready-made.
+ */
+import { basename } from 'node:path';
+import { parseColor } from './color.mjs';
+
+// chart libraries only: a map or an editor is a renderer too, but its
+// colours are never a series (lib/kitpaint.mjs keeps the wider list)
+export const CHART_IMPORT_RE = /from\s+['"](?:recharts|chart\.js|react-chartjs-2|echarts|echarts-for-react|d3|d3-[\w-]+|@nivo\/[\w-]+|victory|apexcharts|react-apexcharts|highcharts|highcharts-react-official|plotly\.js[\w-]*|react-plotly\.js|@visx\/[\w-]+|@antv\/[\w-]+|@mui\/x-charts|@mantine\/charts|@tremor\/react|lightweight-charts|uplot|uplot-react|frappe-charts|@ant-design\/(?:plots|charts)|chartist|billboard\.js|vega|vega-lite|@observablehq\/plot|@carbon\/charts[\w-]*|react-vis)['"\/]/;
+// a file named for a chart; "graphql" is not a graph and neither is a "graphic"
+const CHART_NAME_RE = /(^|[^a-z])(chart|graph(?!ql|ic)|sparkline|donut|histogram|heatmap)/i;
+// an icon, an illustration, a story or a build is not a chart, whatever it
+// imports (likec4's icon set, twenty's storybook, a committed Next chunk)
+const NOT_CHART_RE = /(^|\/)(icons?|illustrations?|graphics?|__stories__|stories|storybook|\.storybook|static\/chunks|dist|build|out)\/|\.stories\.[jt]sx?$/i;
+const CHART_TOKEN_RE = /(--(?:chart|charts|series|graph|graphs|viz|dataviz|data-viz|visuali[sz]ation)[\w-]*)\s*:\s*([^;{}]+)[;}]/gi;
+// a key in a theme, tokens or palette file: chartColors, charts: {…}, series: […]
+const THEME_FILE_RE = /(^|\/)[\w.-]*(theme|palette|colou?rs?|tokens?|foundations?)[\w.-]*(\/|\.[jt]sx?$)/i;
+const CHART_KEY_RE = /\b((?:chart|charts|series|graph|dataviz|dataViz|visuali[sz]ation)(?:Colou?rs|Palette|colou?rs|palette)?)\s*:\s*[{[]/g;
+const COLOUR_LITERAL_RE = /(['"`])(#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|(?:rgba?|hsla?|oklch|oklab)\([^)'"`]*\))\1/g;
+const SHADCN_DEFAULT_RE = /^--chart-[1-5]$/;
+
+// a token value that is a colour: hex, rgb(), hsl(), oklch(), or shadcn's
+// bare "220 70% 50%" triplet. "--chart-help: 'Pick a range'" is not one.
+const isColourValue = (v) => {
+  const s = v.trim();
+  if (parseColor(s)) return true;
+  return /^(oklch|oklab|color|lab|lch)\(/.test(s) || /^\d+(?:\.\d+)?\s+\d+(?:\.\d+)?%\s+\d+(?:\.\d+)?%$/.test(s);
+};
+
+/** A chart file: imports a chart library, or is named for one. */
+export function isChartFile(file, text) {
+  if (file && NOT_CHART_RE.test(file)) return false;
+  if (text && CHART_IMPORT_RE.test(text)) return true;
+  return !!file && CHART_NAME_RE.test(basename(file));
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// how a chart would read a palette entry: var(--chart-1) or the class chart-1
+// for a CSS name, the key itself for a theme key
+const refRe = (name) => name.startsWith('--')
+  ? new RegExp(`(?:var\\(\\s*${escapeRe(name)}\\b|(?:^|[^\\w-])${escapeRe(name.slice(2))}(?![\\w-]))`)
+  : new RegExp(`\\b${escapeRe(name)}\\b`);
+
+/**
+ * What the repo already knows about charts, from the same file set the rest
+ * of the knowledge reads.
+ * @returns { palette: { names, file, shadcnDefault, referenced } | null,
+ *            precedents: [{ file, count, sample }], chartFiles }
+ */
+export function chartSystemOf(files, read) {
+  const names = [], where = new Map();
+  const noteToken = (name, file) => { if (!where.has(name)) { names.push(name); where.set(name, file); } };
+  for (const f of files.styles ?? []) {
+    const text = read(f); if (text === null) continue;
+    for (const m of text.matchAll(CHART_TOKEN_RE)) if (isColourValue(m[2])) noteToken(m[1], f);
+  }
+  const chartTexts = [];
+  for (const f of files.code ?? []) {
+    const text = read(f); if (text === null) continue;
+    // a CSS-in-JS theme or a Tailwind @theme inside a .ts file defines
+    // custom properties too
+    for (const m of text.matchAll(CHART_TOKEN_RE)) if (isColourValue(m[2])) noteToken(m[1], f);
+    if (THEME_FILE_RE.test(f)) {
+      for (const m of text.matchAll(CHART_KEY_RE)) {
+        if (COLOUR_LITERAL_RE.test(text.slice(m.index, m.index + 600))) noteToken(m[1], f);
+      }
+    }
+    if (isChartFile(f, text)) chartTexts.push({ f, text });
+  }
+  const palette = names.length ? { names, file: where.get(names[0]), shadcnDefault: names.every((n) => SHADCN_DEFAULT_RE.test(n)), referenced: false } : null;
+  const precedents = [];
+  for (const { f, text } of chartTexts) {
+    if (palette && !palette.referenced && palette.names.some((n) => refRe(n).test(text))) palette.referenced = true;
+    const literals = [...new Set([...text.matchAll(COLOUR_LITERAL_RE)].map((m) => m[2].toLowerCase()))];
+    if (literals.length >= 2) precedents.push({ file: f, count: literals.length, sample: literals.slice(0, 3) });
+  }
+  precedents.sort((a, b) => b.count - a.count);
+  return { palette, precedents, chartFiles: chartTexts.length };
+}
+
+/** 1: a palette to use; 2: a precedent and a gap; 3: the first chart. */
+export function chartTier(charts) {
+  if (!charts) return 3;
+  if (charts.palette && (!charts.palette.shadcnDefault || charts.palette.referenced)) return 1;
+  if (charts.precedents.length || charts.palette) return 2;
+  return 3;
+}
+
+const list = (values, max = 6) => `${values.slice(0, max).join(', ')}${values.length > max ? ` and ${values.length - max} more` : ''}`;
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+/**
+ * The findings for the colours a chart file writes by hand.
+ * @param colours [{ value, index }] the non-token colour literals in the file
+ */
+export function chartFindings({ file, colours, charts, tokenFile = null }) {
+  if (!colours?.length) return [];
+  const tier = chartTier(charts);
+  const distinct = [...new Set(colours.map((c) => c.value))];
+  const first = colours[0].index;
+  if (tier === 1) {
+    const { names, file: pf } = charts.palette;
+    const example = names[0].startsWith('--') ? `var(${names[0]})` : `${names[0]}[0]`;
+    return colours.map((c) => ({
+      rule: 'chart-colour', severity: 'violation', index: c.index,
+      message: `Chart colour ${c.value} written by hand; this repo keeps a chart palette (${list(names, 5)} in ${pf}).`,
+      fix: `Read the series colour from the palette (${example}). A series that needs a colour the palette lacks gets a new entry there, once.`,
+    }));
+  }
+  const where = tokenFile ?? 'the theme';
+  if (tier === 2) {
+    const prec = charts.precedents.find((p) => p.file !== file) ?? null;
+    const shadcn = charts.palette?.shadcnDefault ? charts.palette : null;
+    return [{
+      rule: 'chart-palette', severity: 'warning', index: first,
+      message: `This chart paints its ${plural(distinct.length, 'series colour')} by hand (${list(distinct)}); the repo has no chart palette${prec ? `, and ${prec.file} already does the same with ${prec.count}` : ''}.`,
+      fix: shadcn
+        ? `The theme already defines --chart-1 to --chart-5 in ${shadcn.file} and no chart reads them. Read them here (var(--chart-1))${prec ? ` and point ${prec.file} at them too` : ''}.`
+        : `Name these once as chart tokens (--chart-1, --chart-2 … in ${where}) and read them here${prec ? ` and in ${prec.file}` : ''}, so every chart draws from one set.`,
+    }];
+  }
+  return [{
+    rule: 'chart-palette', severity: 'warning', index: first,
+    message: `First chart in this repo: ${plural(distinct.length, 'series colour')} written by hand (${list(distinct)}) and no chart palette exists yet.`,
+    fix: `Name them once as chart tokens (--chart-1, --chart-2 … in ${where}) so the next chart reads the same set instead of copying these.`,
+  }];
+}

package/skills/roast-my-design-system/scripts/lib/gaps.mjs

@@ -0,0 +1,50 @@
+/**
+ * Where agents will invent. The September 2026 runs (164 sessions, 10 real
+ * products) showed agents copying what a repo already has and inventing only
+ * where the design system has no answer: a theme, a chart. A gap is a place
+ * where the next piece of UI, human or agent, has nothing to reuse, so the
+ * report names it before the invention happens. Every gap carries the files
+ * that prove it and the one move that closes it.
+ *
+ * A gap is admitted only after a fleet probe says it discriminates: it must
+ * be common enough to matter and absent often enough to be a finding.
+ * Chart palettes (probe of 126 repos, 2026-09-25): charts in three quarters,
+ * a palette in a quarter, 44 repos painting series by hand with no palette.
+ *
+ * Probed the same day and left out, so the next session does not re-run it:
+ *   - tokens without a dark value: 32 of the 49 dark-mode repos, median 29%
+ *     of tokens, but a token not restated in .dark is usually a deliberate
+ *     mode-invariant colour, so the innocent explanation wins;
+ *   - no radius, shadow or font-size scale: only 7 repos style without
+ *     Tailwind or a kit, and none of them lacks a scale, so it never fires;
+ *   - no status colours (success, warning, danger): missing in two thirds
+ *     of repos, and the agent runs showed no drift on a new status.
+ */
+import { chartTier } from './charts.mjs';
+
+const list = (xs, max = 3) => `${xs.slice(0, max).join(', ')}${xs.length > max ? ` and ${xs.length - max} more` : ''}`;
+
+/**
+ * @param charts   from chartSystemOf (lib/charts.mjs)
+ * @param tokenFile where the repo keeps its colour tokens, or null
+ * @returns [{ id, title, detail, fix, files, weight }] most pressing first
+ */
+export function designGaps({ charts = null, tokenFile = null } = {}) {
+  const gaps = [];
+  if (charts && chartTier(charts) === 2 && charts.precedents.length) {
+    const p = charts.precedents;
+    const colours = p.reduce((s, x) => s + x.count, 0);
+    const shadcn = charts.palette?.shadcnDefault ? charts.palette : null;
+    gaps.push({
+      id: 'chart-palette',
+      title: shadcn ? 'The chart palette exists and no chart reads it' : 'Charts have no palette',
+      detail: `${p.length} chart file${p.length === 1 ? '' : 's'} paint${p.length === 1 ? 's' : ''} ${colours} series colours by hand (${list(p.map((x) => `${x.file} (${x.count})`))})${shadcn ? `, while ${shadcn.file} already defines --chart-1 to --chart-5` : ', and no token names a chart colour'}. The next chart will invent colours ${colours + 1} to ${colours + 6}, because that is what every chart here did.`,
+      fix: shadcn
+        ? `Point ${p.length === 1 ? 'that chart' : 'the existing charts'} at var(--chart-1) to var(--chart-5), then the next chart has a palette to read.`
+        : `Name the series once (--chart-1, --chart-2 … in ${tokenFile ?? 'the theme'}) and point ${p.length === 1 ? 'that chart' : 'the existing charts'} at them. From then on a chart that writes a colour by hand is a finding the checks catch.`,
+      files: p.slice(0, 5).map((x) => x.file),
+      weight: Math.min(60, 20 + colours),
+    });
+  }
+  return gaps.sort((a, b) => b.weight - a.weight);
+}

package/skills/roast-my-design-system/scripts/lib/guard-api.mjs

@@ -11,6 +11,9 @@
  */
 import { extname, join } from 'node:path';
 import { walkRepo, readSource, profileRepo } from '../harvest/walk.mjs';
+import { chartSystemOf } from './charts.mjs';
+import { designGaps } from './gaps.mjs';
+export { designGaps } from './gaps.mjs';
 import { decideProfile, profileOf, installedDirs } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { kitPaintFindings } from './kitpaint.mjs';
@@ -59,6 +62,7 @@ export { kitPaintFindings };
 // Same words as roast_validate, roast_review and --check.
 export { tokenTwinFindings, tokenDefsOf } from './tokentwins.mjs';
 export { avoidedImportFindings, canonicalCopy } from './avoidedimports.mjs';
+export { isChartFile, chartSystemOf, chartTier, chartFindings } from './charts.mjs';
 
 // Radius, font size, shadow and typeface: the patterns, so both checkers agree
 // on what a declaration is and what counts as a disciplined value.
@@ -90,6 +94,7 @@ export const isStyleFile = (p) => STYLE_EXTS.has(extname(p));
  *   tailwind,         // { colors, spacing, radii, textSizes, arbitrary }
  *   components,       // [{ name, file, usageCount, isPage }] the ledger
  *   tokenDefs,        // [{ name, file, value, canon, darkValue?, darkCanon? }] colour tokens
+ *   charts,           // { palette, precedents, chartFiles } the chart palette or its absence
  *   duplicates,       // Map<name, { copies: [{ file, usageCount }], strays }>
  *   files,            // { styles: n, code: n } — how much was read
  * }
@@ -105,6 +110,7 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
   // the same two lists the MCP knowledge builds (mcp/knowledge.mjs), from the
   // same helpers, for tokenTwinFindings and avoidedImportFindings (8.6.1)
   const read = (f) => readSource(join(repoRoot, f));
+  const charts = chartSystemOf(files, read);
   const hardDupes = (findDuplicates(ledger, profile.uiDir, repoRoot).exactDuplicates ?? []).filter((d) => !d.wrapped);
   const P = profileOf(profile);
   // the kit the product is built on, with its definition attached, the way
@@ -152,6 +158,9 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
     // every colour token each stylesheet defines, light and dark: the
     // `others` tokenTwinFindings compares a new token with (8.6.1)
     tokenDefs: repoTokenDefs(files.styles, read),
+    // the chart palette, or the charts painting by hand without one (lib/charts.mjs)
+    charts,
+    gaps: designGaps({ charts, tokenFile: t.tokenFile ?? null }),
     // each duplicated name's copies, their usage and the colours each
     // non-canonical copy hard-codes: the `dupes` avoidedImportFindings reads
     duplicates: dupeCopiesOf(hardDupes, ledger, read),

package/skills/roast-my-design-system/scripts/lib/version.mjs

@@ -1,7 +1,7 @@
 // Single version constant for the engine — imported by diagnose (report
 // footer) and rules (generated-by line). This is the bump spot that used to
 // live as a const inside diagnose/index.mjs.
-export const VERSION = '8.7.0';
+export const VERSION = '8.9.0';
 // The shape of harvest.json and summary.json. Bumped only when a field is
 // renamed, removed or changes meaning; a new field is not a new schema. A
 // tool comparing two scans compares like with like by this number, not by VERSION.

package/skills/roast-my-design-system/scripts/mcp/engine.mjs

@@ -22,6 +22,7 @@ import { TAILWIND_DEFAULTS } from '../profiles/tailwind-defaults.mjs';
 import { oklab } from '../lib/color.mjs';
 import { tokenTwinFindings } from '../lib/tokentwins.mjs';
 import { avoidedImportFindings } from '../lib/avoidedimports.mjs';
+import { isChartFile, chartFindings } from '../lib/charts.mjs';
 
 // What this engine measures — shipped with every result, clean or not.
 export const CHECKS = [
@@ -36,6 +37,7 @@ export const CHECKS = [
   'duplicate component definitions',
   'new colour tokens that twin an existing token',
   'imports of a duplicate the canonical copy replaces',
+  'chart colours against the chart palette',
 ];
 // What a kit or a Tailwind theme adds to the list, so a clean result on an
 // MUI repo says the kit check ran.
@@ -121,7 +123,18 @@ export function validateContent(content, k) {
   // knows which are not paint (a comment, a fallback after a theme read, a
   // compare, SVG artwork), so the generic check stays out of its way.
   let kitOwnsColours = false;
-  if (k.kit?.def && !css) {
+  // ---------- chart colours ----------
+  // A chart's series colours are judged against the chart palette, or its
+  // absence, by lib/charts.mjs: the report never counted them, the live
+  // checks counted every one, and the same file got two verdicts. On a
+  // chart file the chart rule owns colours; the kit judge and the generic
+  // colour check stay out of its way.
+  const chartFile = !css && !!k.charts && isChartFile(file, text);
+  if (chartFile) {
+    const paint = got.colors.filter((c) => !k.colorInfo.get(c.value)?.isToken);
+    for (const f of chartFindings({ file, colours: paint, charts: k.charts, tokenFile: k.tokens.tokenFile })) add(f.rule, f.severity, f.index, f.message, f.fix);
+  }
+  if (k.kit?.def && !css && !chartFile) {
     const judged = kitPaintFindings(text, k.kit, { file });
     if (judged && !judged.exempt) {
       kitOwnsColours = true;
@@ -187,7 +200,7 @@ export function validateContent(content, k) {
   for (const c of got.colors) {
     if (seenHere.has(`${c.value}:${c.index}`)) continue;
     seenHere.add(`${c.value}:${c.index}`);
-    if (kitOwnsColours) continue; // the kit judge said it, or judged it not paint
+    if (kitOwnsColours || chartFile) continue; // the kit judge or the chart rule said it, or judged it not paint
     const info = k.colorInfo.get(c.value);
     if (info?.isToken) continue; // it IS the token's value — the system can see it
     const near = nearestToken(c.value, k);

package/skills/roast-my-design-system/scripts/mcp/knowledge.mjs

@@ -26,6 +26,8 @@ import { decideProfile, profileOf } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { repoTokenDefs } from '../lib/tokentwins.mjs';
 import { dupeCopiesOf } from '../lib/avoidedimports.mjs';
+import { chartSystemOf } from '../lib/charts.mjs';
+import { designGaps } from '../lib/gaps.mjs';
 
 const MAX_DEPTH = 14; // same ruler as the harvest CLI
 
@@ -128,6 +130,10 @@ export function loadKnowledge(root) {
   // Every colour token each stylesheet defines, light and dark, so a new one
   // can be compared with the ones already there (lib/tokentwins).
   const tokenDefs = repoTokenDefs(files.styles, read);
+  // the chart palette the repo keeps, or the charts that paint by hand
+  // without one (lib/charts.mjs)
+  const charts = chartSystemOf(files, read);
+  const gaps = designGaps({ charts, tokenFile: tokens.tokenFile ?? null });
 
   return {
     root,
@@ -156,6 +162,8 @@ export function loadKnowledge(root) {
     dupeByName,
     dupeCopies,
     tokenDefs,
+    charts,
+    gaps,
     neverImported,
     // stock, not debt: see profiles/index.mjs
     vendoredUi: P.vendoredUi,

package/skills/roast-my-design-system/scripts/mcp/tools.mjs

@@ -91,6 +91,8 @@ export function getContext(k, { path = null } = {}) {
   // stylesheet repeats more often
   const faces = distinctTypefaces([...(t.themeFonts ?? []), ...(t.fontFamilies ?? [])]);
   if (faces.length) L.push(`TYPE: ${faces.slice(0, 3).join(', ')}. No new typefaces, no hand-declared font stacks.`);
+  // where the repo has no answer yet, so the agent knows it is inventing
+  for (const g of (k.gaps ?? []).slice(0, 2)) L.push(`GAP: ${g.title.toLowerCase()}. ${g.fix}`);
   L.push('DISCIPLINE: no static style={{ }}, no !important, no new arbitrary values. Match the neighbouring component.');
   if (k.agentFiles.length === 0) L.push('NOTE: this repo has no agent rules file; these lines are the only guardrail. Suggest running npx roast-my-design-system@latest --apply.');
   L.push('Before finishing: call roast_validate on what you wrote, then roast_review.');