roast-my-design-system 8.7.0 → 8.8.0

package/README.md

@@ -180,6 +180,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 +224,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "8.7.0",
+  "version": "8.8.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/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, "flowchart" is a diagram
+const CHART_NAME_RE = /(^|[^a-z])(chart|graph(?!ql)|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?|__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/guard-api.mjs

@@ -11,6 +11,7 @@
  */
 import { extname, join } from 'node:path';
 import { walkRepo, readSource, profileRepo } from '../harvest/walk.mjs';
+import { chartSystemOf } from './charts.mjs';
 import { decideProfile, profileOf, installedDirs } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { kitPaintFindings } from './kitpaint.mjs';
@@ -59,6 +60,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 +92,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
  * }
@@ -152,6 +155,8 @@ 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: chartSystemOf(files, read),
     // 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.8.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,7 @@ 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';
 
 const MAX_DEPTH = 14; // same ruler as the harvest CLI
 
@@ -128,6 +129,9 @@ 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);
 
   return {
     root,
@@ -156,6 +160,7 @@ export function loadKnowledge(root) {
     dupeByName,
     dupeCopies,
     tokenDefs,
+    charts,
     neverImported,
     // stock, not debt: see profiles/index.mjs
     vendoredUi: P.vendoredUi,