#!/usr/bin/env node /** * systemscan.mjs — the multi-screen gate: does this product still have ONE design system? * * slopscan reads source and catches defaults. shoot.mjs photographs one page. Neither can see the * failure mode of a real app: drift. Screen 1 has three button variants, screen 7 invents a fourth, * and nobody notices because every screen looks fine on its own. This crawls every route, reads what * the browser ACTUALLY PAINTED, and reports the system as built rather than as documented. * * Usage: * node scripts/systemscan.mjs [...] * node scripts/systemscan.mjs http://localhost:3000 --routes /,/settings,/billing * * Options: * --routes a,b,c paths to append to the first url (instead of listing full urls) * --out DIR output dir (default design/system) * --max-variants B variant budget: a number, or per kind — `button=5,select=1,4` (default 4) * --width N viewport width (default 1440) * --no-shots skip the component contact sheet * * Writes DIR/SYSTEM-REPORT.md (read it), DIR/system.json, DIR/components.png. * Exit 1 when the system is provably broken: a control type over budget, an interactive element with * no visible focus state, or a token used on exactly one route. */ import { mkdir, writeFile } from 'fs/promises'; import { resolve, join } from 'path'; const args = process.argv.slice(2); if (!args.length || args.includes('--help')) { console.log(`systemscan.mjs — cross-route design-system drift gate node scripts/systemscan.mjs [...] node scripts/systemscan.mjs http://localhost:3000 --routes /,/settings,/billing --out DIR --max-variants 4|button=5,select=1 --width 1440 --no-shots`); process.exit(0); } const get = (f, d) => { const i = args.indexOf(f); return i !== -1 ? args[i + 1] : d; }; const has = f => args.includes(f); const outDir = resolve(get('--out', 'design/system')); // Per-kind budgets: `--max-variants button=5,select=1` (a bare number sets the default for the rest). // One global number meant a sheet declaring button:5 and select:1 had to pass 5, leaving every // smaller kind unpoliced — the sheet's central promise enforced for exactly one control kind. const rawBudget = get('--max-variants', '4'); const budget = { default: 4, byKind: {} }; for (const part of String(rawBudget).split(',').map(s => s.trim()).filter(Boolean)) { const m = part.match(/^([a-z]+)\s*=\s*(\d+)$/i); if (m) budget.byKind[m[1].toLowerCase()] = +m[2]; else if (/^\d+$/.test(part)) budget.default = +part; else console.error(`[systemscan] ignoring unparseable budget "${part}" — use 4 or button=5,select=1`); } const budgetFor = kind => budget.byKind[kind] ?? budget.default; const width = parseInt(get('--width', '1440'), 10) || 1440; const shots = !has('--no-shots'); let urls = args.filter(a => /^https?:\/\//.test(a) || a.startsWith('file://')); const routes = get('--routes', null); if (routes && urls.length) { const base = urls[0].replace(/\/$/, ''); urls = routes.split(',').map(r => base + (r.startsWith('/') ? r : '/' + r)); } if (!urls.length) { console.error('[systemscan] no urls. Pass them, or a base url + --routes /a,/b'); process.exit(1); } let chromium; try { ({ chromium } = await import('playwright')); } catch { console.error('playwright not found. Install: npm i -D playwright && npx playwright install chromium'); process.exit(2); } // Everything below is read off getComputedStyle, i.e. the system as PAINTED. A token that exists in // the stylesheet but is never rendered is not part of the system; a one-off inline style is. const COLLECT = () => { const cs = getComputedStyle; const px = v => Math.round(parseFloat(v) || 0); const vis = el => { const s = cs(el); if (s.display === 'none' || s.visibility === 'hidden' || +s.opacity === 0) return false; const r = el.getBoundingClientRect(); return r.width > 1 && r.height > 1; }; const all = [...document.querySelectorAll('*')].slice(0, 6000).filter(vis); const controlKind = el => { const t = el.tagName.toLowerCase(); const role = el.getAttribute('role'); if (t === 'button' || role === 'button') return 'button'; if (t === 'a' && /(^|\s)(btn|button)/i.test(el.className || '')) return 'button'; if (t === 'a') return 'link'; if (t === 'input') return ['checkbox', 'radio'].includes(el.type) ? 'toggle' : 'input'; if (t === 'select') return 'select'; if (t === 'textarea') return 'input'; if (role === 'tab') return 'tab'; return null; }; // The signature is what a user can SEE. Two buttons with different class names but identical // paint are one variant; two with the same class and different paint are two. const sig = el => { const s = cs(el); return [ s.backgroundColor, s.color, s.borderColor, `${px(s.borderTopWidth)}b`, `${px(s.borderTopLeftRadius)}r`, `${px(s.fontSize)}/${s.fontWeight}`, `${px(s.paddingTop)}x${px(s.paddingLeft)}`, s.boxShadow === 'none' ? 'noshadow' : 'shadow', ].join(' | '); }; // A STATE is not a variant. A disabled secondary button paints differently from an enabled one by // design — that is the state matrix system.md demands, and counting it as a fifth button punishes // the team that built it while a system with no disabled state at all sails through. Same for a // control that inverts because the row it sits in is in an alert state: the component did not // multiply, its container changed colour underneath it. Both are counted and reported separately. const stateOf = el => { if (el.disabled || el.getAttribute('aria-disabled') === 'true') return 'disabled'; if (el.getAttribute('aria-current') || el.getAttribute('aria-selected') === 'true') return 'current'; for (let n = el.parentElement, hops = 0; n && hops < 4; n = n.parentElement, hops++) { const st = n.getAttribute?.('data-state'); if (st && st !== 'default') return `in-${st}`; } return null; }; const controls = {}; const states = {}; let shotId = 0; for (const el of all) { const kind = controlKind(el); if (!kind) continue; const state = stateOf(el); if (state) { (states[kind] ??= {})[state] = ((states[kind] ??= {})[state] || 0) + 1; continue; } const k = sig(el); (controls[kind] ??= {}); if (!controls[kind][k]) { // Tag the exemplar NOW and re-select it by attribute in the screenshot pass. Handing a // positional index between two independent DOM walks produced tiles that showed a parent or a // sibling rather than the control they were captioned with — which destroys the sheet's whole // purpose, because a tile showing the wrong element looks different for the wrong reason. const tag = `ss${shotId++}`; el.setAttribute('data-ss-shot', tag); controls[kind][k] = { count: 0, sample: (el.innerText || el.value || el.type || '').trim().slice(0, 24), tag }; } controls[kind][k].count++; } const tally = (map, key) => { map[key] = (map[key] || 0) + 1; }; const colors = {}, type = {}, radii = {}, shadows = {}, space = {}; for (const el of all) { const s = cs(el); if (s.backgroundColor && s.backgroundColor !== 'rgba(0, 0, 0, 0)') tally(colors, s.backgroundColor); // `color` on a wrapper paints no glyph. Tallying it unfiltered made 's inherited initial // colour the most common "colour in the product" and inflates the headline count for everyone. const leafText = el.children.length === 0 && (el.textContent || '').trim(); if (s.color && leafText) tally(colors, s.color); if (leafText) { tally(type, `${px(s.fontSize)}px/${s.fontWeight}/${s.fontFamily.split(',')[0].replace(/["']/g, '')}`); } const r = px(s.borderTopLeftRadius); if (r) tally(radii, `${r}px`); if (s.boxShadow && s.boxShadow !== 'none') tally(shadows, s.boxShadow.slice(0, 60)); for (const v of [s.paddingTop, s.paddingLeft, s.marginTop]) { const n = px(v); if (n) tally(space, `${n}px`); } } return { controls, states, colors, type, radii, shadows, space, focusable: all.filter(el => el.matches('a[href],button,input,select,textarea,[tabindex]:not([tabindex="-1"])')).length, hasDisabled: all.some(el => el.matches('[disabled],[aria-disabled="true"]')), title: document.title.slice(0, 60), landmarks: ['header', 'nav', 'main', 'footer', 'aside'].filter(t => document.querySelector(t)).join(','), h1: document.querySelectorAll('h1').length, }; }; /** * Focus state cannot be read from a stylesheet: a `:focus-visible` rule may exist and be overridden, * and `:focus-visible` itself is a heuristic that programmatic `.focus()` does not reliably trigger. * So drive the real thing — press Tab and look at what the browser actually paints. Tabbing also * skips disabled and unfocusable elements for free, which a `.focus()` loop reports as failures. */ const PROBE_FOCUS = async (page, maxStops = 40) => { const paint = () => { const cs = getComputedStyle; // Only properties that actually PAINT. outline-offset alone draws nothing, and including it // let an element that kills its outline still read as "focus state changed". const sig = el => { const s = cs(el); return `${s.outlineStyle === 'none' ? 'no-outline' : s.outline} ${s.boxShadow} ${s.borderColor} ${s.backgroundColor} ${s.color} ${s.textDecorationLine}`; }; const els = [...document.querySelectorAll('a[href],button,input,select,textarea,summary,[tabindex]:not([tabindex="-1"])')]; els.forEach((el, i) => el.setAttribute('data-ss-i', String(i))); return els.map(sig); }; const unfocused = await page.evaluate(paint); await page.evaluate(() => (document.activeElement || document.body).blur?.()); const bad = [], seen = new Set(); for (let i = 0; i < maxStops; i++) { await page.keyboard.press('Tab'); const stop = await page.evaluate(() => { const el = document.activeElement; if (!el || el === document.body || !el.hasAttribute?.('data-ss-i')) return null; const s = getComputedStyle(el); const r = el.getBoundingClientRect(); return { i: +el.getAttribute('data-ss-i'), sig: `${s.outlineStyle === 'none' ? 'no-outline' : s.outline} ${s.boxShadow} ${s.borderColor} ${s.backgroundColor} ${s.color} ${s.textDecorationLine}`, label: el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + ' “' + (el.innerText || el.value || el.getAttribute('aria-label') || '').trim().slice(0, 20) + '”', offscreen: r.width < 1 || r.height < 1, }; }); if (!stop) continue; if (seen.has(stop.i)) break; // wrapped around the tab ring seen.add(stop.i); if (!stop.offscreen && unfocused[stop.i] === stop.sig) bad.push(stop.label); } return { probed: seen.size, noFocusRing: bad }; }; const browser = await chromium.launch({ headless: true }); const ctx = await browser.newContext({ viewport: { width, height: 900 } }); await mkdir(outDir, { recursive: true }); const perRoute = []; for (const url of urls) { const page = await ctx.newPage(); const errs = []; page.on('pageerror', e => errs.push(e.message)); page.on('console', m => m.type() === 'error' && errs.push(m.text())); try { process.stderr.write(`[systemscan] ${url}\n`); const resp = await page.goto(url, { waitUntil: 'commit', timeout: 30_000 }); const dcl = await page.waitForLoadState('domcontentloaded', { timeout: 15_000 }).then(() => true).catch(() => false); await page.waitForTimeout(dcl ? 2500 : 6000); if (!dcl) await page.evaluate(() => window.stop()).catch(() => {}); const data = await page.evaluate(COLLECT); const focus = await PROBE_FOCUS(page); const status = resp?.status?.() ?? 0; // A route that renders nothing contributes nothing to the counts, so a mistyped route list made // the gate QUIETER instead of louder. A gate that goes green on a 404 is worse than no gate. const empty = !data.landmarks && !data.h1 && !data.focusable; perRoute.push({ url, ...data, focus, errors: errs, status, empty }); if (status >= 400) console.error(`[systemscan] ${url} → HTTP ${status}`); else if (empty) console.error(`[systemscan] ${url} → rendered nothing measurable (no landmark, no h1, no focusable)`); if (shots) { // one exemplar screenshot per distinct control variant, so the report has a picture of the // drift and not only a count of it for (const [kind, variants] of Object.entries(data.controls)) { let i = 0; for (const [, v] of Object.entries(variants)) { if (!v.tag) continue; const name = `${kind}-${perRoute.length}-${i++}.png`; try { const box = await page.$(`[data-ss-shot="${v.tag}"]`); // the element we actually measured if (box) { await box.scrollIntoViewIfNeeded({ timeout: 4000 }); await box.screenshot({ path: join(outDir, 'components', name), timeout: 8000 }); v.shot = `components/${name}`; } } catch { /* an element that will not sit still is not worth failing the run over */ } } } } } catch (e) { perRoute.push({ url, error: e.message.split('\n')[0] }); } finally { await page.close(); } } // ---- aggregate across routes ------------------------------------------------- const ok = perRoute.filter(r => !r.error); if (!ok.length) { console.error('[systemscan] no route could be read.'); await browser.close(); process.exit(1); } // A document scanned twice (`/settings` and `/settings#state-error` are the same DOM) must not count // twice — summing across URLs meant scanning MORE thoroughly hid genuine one-off variants, which is // the opposite of what `system.md` tells you to do. Count per document, take the max, then sum. const docOf = u => u.split('#')[0]; const docs = [...new Set(ok.map(r => docOf(r.url)))]; const mergeCount = key => { const m = {}; for (const r of ok) for (const [k, n] of Object.entries(r[key] || {})) { (m[k] ??= { perDoc: {} }); const d = docOf(r.url); m[k].perDoc[d] = Math.max(m[k].perDoc[d] || 0, n); } return Object.entries(m) .map(([k, v]) => ({ k, total: Object.values(v.perDoc).reduce((a, b) => a + b, 0), routes: Object.keys(v.perDoc).length })) .sort((a, b) => b.total - a.total); }; const controlVariants = {}; for (const r of ok) for (const [kind, vars] of Object.entries(r.controls || {})) { (controlVariants[kind] ??= {}); for (const [sig, v] of Object.entries(vars)) { const slot = (controlVariants[kind][sig] ??= { perDoc: {}, sample: v.sample, shot: v.shot }); const d = docOf(r.url); slot.perDoc[d] = Math.max(slot.perDoc[d] || 0, v.count); slot.shot ??= v.shot; } } for (const vars of Object.values(controlVariants)) for (const v of Object.values(vars)) { v.count = Object.values(v.perDoc).reduce((a, b) => a + b, 0); v.routes = new Set(Object.keys(v.perDoc)); } // States, gathered the same way but never counted against the variant budget. const controlStates = {}; for (const r of ok) for (const [kind, st] of Object.entries(r.states || {})) for (const [name, n] of Object.entries(st)) { ((controlStates[kind] ??= {})[name] ??= 0); controlStates[kind][name] += n; } const fails = [], warns = []; for (const [kind, vars] of Object.entries(controlVariants)) { const n = Object.keys(vars).length, b = budgetFor(kind); if (n > b) fails.push(`${kind}: ${n} distinct rendered variants (budget ${b}). A variant nobody can name is drift.`); for (const [sig, v] of Object.entries(vars)) { if (v.count === 1 && n > 1) warns.push(`${kind} variant used exactly once ("${v.sample}") — either promote it into the system or delete it: ${sig}`); } } const blank = perRoute.filter(r => !r.error && (r.status >= 400 || r.empty)); if (blank.length) fails.push(`${blank.length} route(s) rendered nothing measurable or returned an error status — a gate that goes green on a 404 is worse than no gate: ${blank.map(r => `${r.url}${r.status >= 400 ? ` (HTTP ${r.status})` : ''}`).join(', ')}`); const noFocus = ok.flatMap(r => (r.focus?.noFocusRing || []).map(t => `${r.url} → ${t}`)); if (noFocus.length) fails.push(`${noFocus.length} interactive element(s) paint identically when focused — keyboard users cannot see where they are`); const colors = mergeCount('colors'), type = mergeCount('type'), radii = mergeCount('radii'), shadows = mergeCount('shadows'); if (docs.length > 1) { for (const [label, list] of [['colour', colors], ['type step', type], ['radius', radii]]) { const singles = list.filter(x => x.routes === 1 && x.total >= 3); if (singles.length) warns.push(`${singles.length} ${label}(s) appear on exactly one route and nowhere else — that is where the system is splitting: ${singles.slice(0, 4).map(s => s.k).join(' · ')}`); } } if (type.length > 12) warns.push(`${type.length} distinct type steps across the product — a scale nobody can hold in their head is not a scale`); if (!ok.some(r => r.hasDisabled)) warns.push('no disabled control appeared on any route — the disabled state is probably undesigned, not absent'); // ---- component contact sheet ------------------------------------------------- let sheet = null; const tiles = Object.entries(controlVariants).flatMap(([kind, vars]) => Object.entries(vars).filter(([, v]) => v.shot).map(([, v], i) => ({ kind, i, ...v }))); if (shots && tiles.length) { const html = `
${tiles.map(t => `
${t.kind} ×${t.count} · ${t.routes.size} route(s)
`).join('')}
`; const f = join(outDir, '_components.html'); await writeFile(f, html, 'utf8'); const p = await ctx.newPage(); await p.setViewportSize({ width: 1200, height: 900 }); await p.goto('file:///' + f.replace(/\\/g, '/'), { waitUntil: 'load', timeout: 20_000 }).catch(() => {}); await p.waitForTimeout(900); // shoot the grid, not the viewport — a fullPage shot of a two-row sheet is mostly empty canvas const grid = await p.$('.g'); await (grid || p).screenshot({ path: join(outDir, 'components.png') }); await p.close(); sheet = 'components.png'; } await browser.close(); // ---- report ------------------------------------------------------------------ const L = []; L.push(`# SYSTEM-REPORT — ${ok.length} route(s), ${new Date().toISOString().slice(0, 10)}`); L.push(''); L.push('The system as **painted**, not as documented. A token in the stylesheet that never renders is'); L.push('not part of the system; a one-off inline style is. Read this against `design/DESIGN.md` — every'); L.push('number below that DESIGN.md does not account for is drift.'); L.push(''); if (sheet) L.push(`**Look at \`${sheet}\`** — one tile per distinct rendered control variant. Two tiles that look the same to you but appear separately are the drift.\n`); L.push('## Controls'); L.push(''); L.push('| kind | distinct variants | budget | total instances |'); L.push('|---|---|---|---|'); for (const [kind, vars] of Object.entries(controlVariants)) { const n = Object.keys(vars).length; L.push(`| ${kind} | **${n}** | ${budgetFor(kind)} | ${Object.values(vars).reduce((s, v) => s + v.count, 0)} |`); } L.push(''); for (const [kind, vars] of Object.entries(controlVariants)) { L.push(`### ${kind}`); for (const [sig, v] of Object.entries(vars)) L.push(`- ×${v.count} on ${v.routes.size} route(s) — "${v.sample}" — \`${sig}\``); if (controlStates[kind]) { const st = Object.entries(controlStates[kind]).map(([n, c]) => `${n} ×${c}`).join(' · '); L.push(`- *states (not counted as variants): ${st}*`); } L.push(''); } if (Object.keys(controlStates).length) { L.push('> States — disabled, current, and controls inside a row carrying a `data-state` — are'); L.push('> excluded from the variant budget. A disabled button paints differently on purpose; a'); L.push('> product that has no disabled state at all should not score better than one that does.'); L.push(''); } L.push('## Tokens as rendered'); L.push(''); for (const [label, list] of [['Colour', colors], ['Type step', type], ['Radius', radii], ['Shadow', shadows]]) { L.push(`**${label}** (${list.length} distinct)`); for (const x of list.slice(0, 10)) L.push(`- \`${x.k}\` — ${x.total}× on ${x.routes} route(s)`); if (list.length > 10) L.push(`- …and ${list.length - 10} more`); L.push(''); } L.push('## Per route'); L.push(''); L.push('| route | landmarks | h1 | focusable | console errors |'); L.push('|---|---|---|---|---|'); for (const r of ok) L.push(`| ${r.url} | ${r.landmarks || '—'} | ${r.h1} | ${r.focusable} | ${r.errors.length} |`); for (const r of perRoute.filter(r => r.error)) L.push(`| ${r.url} | **unreachable** — ${r.error} | | | |`); L.push(''); if (fails.length) { L.push('## FAIL'); fails.forEach(f => L.push(`- ${f}`)); L.push(''); } if (noFocus.length) { L.push('### Elements with no visible focus state'); noFocus.slice(0, 20).forEach(t => L.push(`- ${t}`)); L.push(''); } if (warns.length) { L.push('## WARN'); warns.forEach(w => L.push(`- ${w}`)); L.push(''); } if (!fails.length && !warns.length) L.push('No drift detected. The product renders one system.\n'); await writeFile(join(outDir, 'SYSTEM-REPORT.md'), L.join('\n'), 'utf8'); await writeFile(join(outDir, 'system.json'), JSON.stringify({ routes: perRoute.map(r => ({ ...r, controls: undefined })), controls: Object.fromEntries(Object.entries(controlVariants).map(([k, v]) => [k, Object.entries(v).map(([sig, x]) => ({ sig, count: x.count, routes: [...x.routes], sample: x.sample }))])), colors, type, radii, shadows, fails, warns, }, null, 2), 'utf8'); console.log(`\n=== systemscan ===`); console.log(`routes : ${ok.length}/${perRoute.length} read (${docs.length} distinct document(s))`); console.log(`controls: ${Object.entries(controlVariants).map(([k, v]) => `${k} ${Object.keys(v).length}`).join(' · ') || '—'}`); console.log(`tokens : ${colors.length} colours · ${type.length} type steps · ${radii.length} radii · ${shadows.length} shadows`); console.log(`report : ${join(outDir, 'SYSTEM-REPORT.md')}${sheet ? `\nsheet : ${join(outDir, sheet)}` : ''}`); for (const f of fails) console.log(`FAIL ${f}`); for (const w of warns.slice(0, 5)) console.log(`WARN ${w}`); process.exit(fails.length ? 1 : 0);