@appfire-ux/audit-agent 0.20260702.2 → 0.20260706.0

package/README.md

@@ -1,6 +1,6 @@
 # @appfire-ux/audit-agent
 
-One-command install of two Claude Code audit agents for Appfire repos. **Every audit run refreshes both npm packages to `@latest`** (Phase 0):
+One-command install of three Claude Code audit agents for Appfire repos. **Every audit run refreshes both npm packages to `@latest`** (Phase 0):
 
 - **`@appfire-ux/audit-agent`** — agent/command definitions in `.claude/`
 - **`@appfire-ux/guidelines`** — rules, skills, and `guidelines/` kit
@@ -9,6 +9,7 @@ Agents:
 
 - **ux-auditor** (`/ux-audit`) — guideline-compliance UX audit: design tokens, spacing/typography, accessibility, UX writing, messaging patterns, persona fit.
 - **ui-auditor** (`/ui-audit`) — UI & usability audit from a UI Designer's perspective: cross-screen consistency, layout & visual hierarchy, information architecture, navigation, interaction design, forms, data-dense views, responsiveness. Screenshot-driven (browser MCP or bundled Playwright fallback).
+- **a11y-auditor** (`/a11y-audit`) — deep accessibility audit per the Appfire VPAT Compliance Protocol: WCAG 2.2 A/AA, automated axe-core scans of the running app (Baseline Accessibility Score), static four-principles code audit, manual validation register, evidence-gap register, and JSON datapoints that feed the "AI Agent: VPAT Document" (Confluence, CRUX) to draft the Accessibility Conformance Report. Strict no-over-claiming language.
 
 ## Install
 
@@ -21,9 +22,10 @@ npm install -D @appfire-ux/audit-agent
 The postinstall script copies the agent and command into `<repo>/.claude/`. Done — open Claude Code and run:
 
 ```
-/full-audit   # both audits in parallel (recommended)
+/full-audit   # all audits in parallel (recommended)
 /ux-audit     # compliance only
 /ui-audit     # UI & usability only
+/a11y-audit   # accessibility / VPAT readiness only
 ```
 
 Once, for all repos on your machine:
@@ -34,7 +36,7 @@ npx @appfire-ux/audit-agent --global   # installs into ~/.claude/
 
 ## Update (manual, optional)
 
-Phase 0 on every `/ux-audit`, `/ui-audit`, or `/full-audit` run already calls `npm update` + `@latest` for both packages. Use this only when you want to refresh **without** running an audit:
+Phase 0 on every `/ux-audit`, `/ui-audit`, `/a11y-audit`, or `/full-audit` run already calls `npm update` + `@latest` for both packages. Use this only when you want to refresh **without** running an audit:
 
 ```bash
 npm update @appfire-ux/audit-agent @appfire-ux/guidelines
@@ -46,17 +48,22 @@ npx @appfire-ux/guidelines
 
 | File | Purpose |
 |---|---|
-| `.claude/agents/ux-auditor.md` | 8-phase compliance audit: guidelines bootstrap → static + runtime audit → evidence-based report → self-verification |
-| `.claude/commands/ux-audit.md` | `/ux-audit [scope] [--static-only] [--lang pl] [--out <path>]` |
-| `.claude/agents/ui-auditor.md` | 8-phase UI & usability audit: guidelines bootstrap → screen/pattern inventory → screenshot capture → consistency/IA/interaction passes → report → self-verification |
-| `.claude/commands/ui-audit.md` | `/ui-audit [scope] [--static-only] [--lang pl] [--out <path>]` |
-| `.claude/commands/full-audit.md` | `/full-audit [scope] [--static-only] [--lang pl] [--out-dir <path>]` — runs **ux-auditor** and **ui-auditor** in parallel with shared guidelines bootstrap and one dev server |
-
-The audits complement each other: `ux-audit` checks *compliance with the guidelines*, `ui-audit` checks *the interface as designed*. Use `/full-audit` when you want both at once; findings each agent notices outside its lane are handed off to the other's report section, and the combined summary deduplicates cross-cutting issues.
+| `.claude/agents/ux-auditor.md` | Guideline-compliance audit → MD + HTML + `assets/*.png` (Confluence-ready) |
+| `.claude/commands/ux-audit.md` | `/ux-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod]` |
+| `.claude/agents/ui-auditor.md` | UI & usability audit → same deliverable format |
+| `.claude/commands/ui-audit.md` | `/ui-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod]` |
+| `.claude/agents/a11y-auditor.md` | Accessibility/VPAT audit → MD + HTML + JSON datapoints + `axe-results/` |
+| `.claude/commands/a11y-audit.md` | `/a11y-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod] [--routes …]` |
+| `.claude/commands/full-audit.md` | `/full-audit [--agents ux,ui,a11y]` — parallel run of selected agents, combined summary MD+HTML |
+| `scripts/ux-audit-capture.mjs` | Playwright screenshot fallback (`--widths 1440,768`) |
+| `scripts/a11y-audit-scan.mjs` | Playwright + axe-core scanner → per-route JSON + Baseline Score |
+| `scripts/build-html-reports.mjs` | MD → Confluence-ready HTML with local `assets/` gallery |
+
+The audits complement each other. Every run produces **Markdown + HTML + PNG assets** under `docs/audits/` (STOP & ASK on auth walls; no base64). Use `/full-audit` for all agents in parallel. The a11y audit additionally produces machine-readable datapoints (`A11Y-AUDIT-<date>.json` + `axe-results/*.json`) for the VPAT/ACR drafting workflow.
 
 ## Publishing (maintainers)
 
-**CI (preferred):** pushes to `main` that touch `appfire-ux-audit-agent/**` or the canonical agent/command files in `.claude/` (`ux-auditor.md`, `ux-audit.md`, `ui-auditor.md`, `ui-audit.md`, `full-audit.md`) run [`.github/workflows/publish-audit-agent.yml`](../.github/workflows/publish-audit-agent.yml). The workflow assembles the package (syncing templates from `.claude/`), bumps a date-based version (`0.YYYYMMDD.PATCH`), and publishes `@appfire-ux/audit-agent` using the `NPM_TOKEN` secret — same pattern as `@appfire-ux/guidelines` and `@appfire-ux/fonts`.
+**CI (preferred):** pushes to `main` that touch `appfire-ux-audit-agent/**` or the canonical agent/command files in `.claude/` (`ux-auditor.md`, `ux-audit.md`, `ui-auditor.md`, `ui-audit.md`, `a11y-auditor.md`, `a11y-audit.md`, `full-audit.md`) run [`.github/workflows/publish-audit-agent.yml`](../.github/workflows/publish-audit-agent.yml). The workflow assembles the package (syncing templates from `.claude/`), bumps a date-based version (`0.YYYYMMDD.PATCH`), and publishes `@appfire-ux/audit-agent` using the `NPM_TOKEN` secret — same pattern as `@appfire-ux/guidelines` and `@appfire-ux/fonts`.
 
 **Manual:**
 

package/bin/install.js

@@ -69,10 +69,11 @@ console.log('[appfire-ux-audit-agent] Installed ' + copied.length + ' file(s) in
 for (const f of copied) console.log('  - ' + f);
 console.log('');
 console.log('Usage (in Claude Code, inside your repo):');
-console.log('  /full-audit               both audits in parallel (recommended for full coverage)');
+console.log('  /full-audit               all audits in parallel (recommended; --agents ux,ui,a11y)');
 console.log('  /ux-audit                 guideline-compliance UX audit (tokens, a11y, content, messaging)');
 console.log('  /ui-audit                 UI & usability audit (consistency, IA, interaction design)');
+console.log('  /a11y-audit               accessibility audit: WCAG 2.2 + axe-core scan, feeds VPAT/ACR');
 console.log('  All accept: [scope-path] [--static-only] [--lang pl]');
-console.log('  /full-audit also: [--out-dir <path>]   /ux-audit|/ui-audit: [--out <path>]');
+console.log('  /full-audit also: [--out-dir <path>]   others: [--out <path>]');
 console.log('');
 console.log('Tip: run "npx appfire-ux-audit-agent --global" to install into ~/.claude for all repos.');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@appfire-ux/audit-agent",
-  "version": "0.20260702.2",
-  "description": "Claude Code audit agents for Appfire apps — installs ux-auditor (/ux-audit: guideline compliance) and ui-auditor (/ui-audit: UI consistency, IA, interaction design), auditing against @appfire-ux/guidelines",
+  "version": "0.20260706.0",
+  "description": "Claude Code audit agents for Appfire apps — ux-auditor (/ux-audit), ui-auditor (/ui-audit), a11y-auditor (/a11y-audit: WCAG 2.2 + axe-core scan feeding the Appfire VPAT/ACR process), /full-audit parallel orchestration. Confluence-ready MD+HTML+PNG output, runtime capture & scan scripts.",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -12,6 +12,10 @@
     "ux-audit",
     "ui-audit",
     "usability",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "vpat",
     "claude-code",
     "atlassian",
     "design-system"
@@ -28,6 +32,7 @@
     "scripts/"
   ],
   "optionalDependencies": {
-    "playwright": "^1.47.0"
+    "playwright": "^1.47.0",
+    "axe-core": "^4.10.0"
   }
 }

package/scripts/a11y-audit-scan.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Automated axe-core accessibility scanner for the a11y-auditor agent (Phase 3).
+ * Playwright loads each route, injects axe-core, and writes JSON results per route
+ * plus a summary.json with per-screen counts and the Appfire Baseline Score.
+ *
+ * Usage:
+ *   npx playwright install chromium          # once
+ *   node scripts/a11y-audit-scan.mjs --url http://localhost:5173 \
+ *     --out docs/audits/a11y-audit/axe-results --routes /,/dashboard [--width 1440]
+ *
+ * Requires "playwright" and "axe-core" (see package.json optionalDependencies).
+ *
+ * Baseline Score weighting (Appfire Baseline Accessibility Audit Process):
+ *   Critical x3 (axe impact: critical), Major x2 (serious), Minor x1 (moderate, minor).
+ */
+
+'use strict';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+function parseArgs(argv) {
+  const opts = { url: null, out: null, routes: ['/'], width: 1440, height: 900 };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--url') opts.url = argv[++i];
+    else if (arg === '--out') opts.out = argv[++i];
+    else if (arg === '--routes') opts.routes = argv[++i].split(',').map((r) => r.trim()).filter(Boolean);
+    else if (arg === '--width') opts.width = parseInt(argv[++i], 10) || 1440;
+    else if (arg === '--height') opts.height = parseInt(argv[++i], 10) || 900;
+  }
+  return opts;
+}
+
+function routeToSlug(route) {
+  return route === '/' ? 'root' : route.replace(/^\//, '').replace(/[/?#]+/g, '-');
+}
+
+// Appfire severity mapping: axe impact -> Critical / Major / Minor
+function toAppfireSeverity(impact) {
+  if (impact === 'critical') return 'Critical';
+  if (impact === 'serious') return 'Major';
+  return 'Minor'; // moderate, minor, null
+}
+
+const WEIGHTS = { Critical: 3, Major: 2, Minor: 1 };
+
+async function main() {
+  const { url, out, routes, width, height } = parseArgs(process.argv.slice(2));
+
+  if (!url || !out) {
+    console.error('[a11y-audit-scan] Usage: --url <base-url> --out <dir> [--routes /,/foo] [--width 1440] [--height 900]');
+    process.exit(1);
+  }
+
+  let chromium;
+  try {
+    ({ chromium } = await import('playwright'));
+  } catch {
+    console.error('[a11y-audit-scan] "playwright" is not installed. Run: npm install -D playwright && npx playwright install chromium');
+    process.exit(1);
+  }
+
+  let axeSource;
+  try {
+    axeSource = fs.readFileSync(require.resolve('axe-core/axe.min.js'), 'utf8');
+  } catch {
+    console.error('[a11y-audit-scan] "axe-core" is not installed. Run: npm install -D axe-core');
+    process.exit(1);
+  }
+
+  fs.mkdirSync(out, { recursive: true });
+
+  const browser = await chromium.launch();
+  const page = await browser.newPage({ viewport: { width, height } });
+
+  const summary = { baseUrl: url, scannedAt: new Date().toISOString(), viewport: { width, height }, screens: [], totals: { violations: 0, Critical: 0, Major: 0, Minor: 0 }, baselineScore: 0 };
+
+  for (const route of routes) {
+    const target = new URL(route, url).toString();
+    const slug = routeToSlug(route);
+    try {
+      await page.goto(target, { waitUntil: 'networkidle', timeout: 20000 });
+      await page.addScriptTag({ content: axeSource });
+      const results = await page.evaluate(async () => {
+        // eslint-disable-next-line no-undef
+        return await axe.run(document, { resultTypes: ['violations', 'incomplete'] });
+      });
+
+      const counts = { Critical: 0, Major: 0, Minor: 0 };
+      const violations = results.violations.map((v) => {
+        const severity = toAppfireSeverity(v.impact);
+        counts[severity] += v.nodes.length || 1;
+        return {
+          id: v.id,
+          impact: v.impact,
+          appfireSeverity: severity,
+          wcagTags: v.tags.filter((t) => /^wcag/.test(t)),
+          help: v.help,
+          helpUrl: v.helpUrl,
+          nodes: v.nodes.slice(0, 10).map((n) => ({ target: n.target, html: String(n.html).slice(0, 300), failureSummary: n.failureSummary })),
+          nodeCount: v.nodes.length,
+        };
+      });
+
+      const screen = {
+        route,
+        url: target,
+        file: `${slug}.json`,
+        violations: violations.length,
+        nodesAffected: violations.reduce((s, v) => s + v.nodeCount, 0),
+        ...counts,
+        needsReview: results.incomplete.length,
+        score: counts.Critical * WEIGHTS.Critical + counts.Major * WEIGHTS.Major + counts.Minor * WEIGHTS.Minor,
+      };
+
+      fs.writeFileSync(path.join(out, `${slug}.json`), JSON.stringify({ ...screen, details: violations, incomplete: results.incomplete.map((v) => ({ id: v.id, help: v.help, nodeCount: v.nodes.length })) }, null, 2));
+
+      summary.screens.push(screen);
+      summary.totals.violations += screen.violations;
+      summary.totals.Critical += counts.Critical;
+      summary.totals.Major += counts.Major;
+      summary.totals.Minor += counts.Minor;
+      summary.baselineScore += screen.score;
+
+      console.log(`[a11y-audit-scan] ${route}: ${screen.violations} violations (C:${counts.Critical} M:${counts.Major} m:${counts.Minor}, needs-review:${screen.needsReview}) -> ${slug}.json`);
+    } catch (err) {
+      summary.screens.push({ route, url: target, error: err.message });
+      console.error(`[a11y-audit-scan] failed ${route}: ${err.message}`);
+    }
+  }
+
+  await browser.close();
+
+  fs.writeFileSync(path.join(out, 'summary.json'), JSON.stringify(summary, null, 2));
+  console.log(`[a11y-audit-scan] Baseline Score: ${summary.baselineScore} (Critical x3, Major x2, Minor x1) -> summary.json`);
+
+  const failed = summary.screens.filter((s) => s.error);
+  if (failed.length === summary.screens.length) {
+    console.error('[a11y-audit-scan] all routes failed — STOP & ASK or fall back to static-only.');
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+main();

package/scripts/build-html-reports.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Convert audit Markdown reports to Confluence-ready HTML.
+ * Images stay as relative assets/*.png — never base64.
+ *
+ * Usage:
+ *   node build-html-reports.mjs --file docs/audits/ux-audit/UX-AUDIT-2026-07-02.md
+ *   node build-html-reports.mjs --dir docs/audits/ux-audit
+ *   node build-html-reports.mjs --dir docs/audits
+ *
+ * Bundled path: node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs
+ */
+
+'use strict';
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+function parseArgs(argv) {
+  const opts = { files: [], dirs: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--file') opts.files.push(argv[++i]);
+    else if (arg === '--dir') opts.dirs.push(argv[++i]);
+  }
+  return opts;
+}
+
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function inlineFormat(text) {
+  let out = escapeHtml(text);
+  out = out.replace(/`([^`]+)`/g, '<code>$1</code>');
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  out = out.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+  return out;
+}
+
+function mdToHtml(md) {
+  const lines = md.replace(/\r\n/g, '\n').split('\n');
+  const html = [];
+  let inCode = false;
+  let codeBuf = [];
+  let inTable = false;
+  let tableRows = [];
+
+  function flushTable() {
+    if (!tableRows.length) return;
+    html.push('<table>');
+    tableRows.forEach((row, idx) => {
+      const tag = idx === 0 ? 'th' : 'td';
+      const cells = row.split('|').map((c) => c.trim()).filter(Boolean);
+      if (cells.length === 0) return;
+      if (idx === 1 && cells.every((c) => /^[-:]+$/.test(c))) return;
+      html.push('<tr>' + cells.map((c) => `<${tag}>${inlineFormat(c)}</${tag}>`).join('') + '</tr>');
+    });
+    html.push('</table>');
+    tableRows = [];
+    inTable = false;
+  }
+
+  for (const line of lines) {
+    if (line.startsWith('```')) {
+      if (inCode) {
+        html.push('<pre><code>' + escapeHtml(codeBuf.join('\n')) + '</code></pre>');
+        codeBuf = [];
+        inCode = false;
+      } else {
+        flushTable();
+        inCode = true;
+      }
+      continue;
+    }
+    if (inCode) {
+      codeBuf.push(line);
+      continue;
+    }
+
+    if (line.trim().startsWith('|')) {
+      inTable = true;
+      tableRows.push(line.trim());
+      continue;
+    }
+    if (inTable) flushTable();
+
+    const img = line.match(/^!\[([^\]]*)\]\(([^)]+)\)\s*$/);
+    if (img) {
+      html.push(`<figure><img src="${img[2]}" alt="${escapeHtml(img[1])}" /><figcaption>${escapeHtml(img[1])}</figcaption></figure>`);
+      continue;
+    }
+
+    if (/^#{1,6}\s/.test(line)) {
+      const level = line.match(/^#+/)[0].length;
+      const text = line.replace(/^#+\s*/, '');
+      html.push(`<h${level}>${inlineFormat(text)}</h${level}>`);
+      continue;
+    }
+
+    if (/^[-*]\s/.test(line)) {
+      html.push(`<li>${inlineFormat(line.replace(/^[-*]\s/, ''))}</li>`);
+      continue;
+    }
+
+    if (/^\d+\.\s/.test(line)) {
+      html.push(`<li>${inlineFormat(line.replace(/^\d+\.\s/, ''))}</li>`);
+      continue;
+    }
+
+    if (line.trim() === '---') {
+      html.push('<hr />');
+      continue;
+    }
+
+    if (line.trim() === '') {
+      html.push('');
+      continue;
+    }
+
+    html.push(`<p>${inlineFormat(line)}</p>`);
+  }
+
+  if (inTable) flushTable();
+  if (inCode && codeBuf.length) {
+    html.push('<pre><code>' + escapeHtml(codeBuf.join('\n')) + '</code></pre>');
+  }
+
+  return html.join('\n');
+}
+
+function listPngs(assetsDir) {
+  if (!fs.existsSync(assetsDir)) return [];
+  return fs
+    .readdirSync(assetsDir)
+    .filter((f) => f.endsWith('.png'))
+    .sort()
+    .map((f) => `assets/${f}`);
+}
+
+function buildGallery(assetsDir) {
+  const images = listPngs(assetsDir);
+  if (!images.length) return '';
+  const items = images
+    .map((src) => `<figure><img src="${src}" alt="${path.basename(src)}" /><figcaption>${escapeHtml(path.basename(src))}</figcaption></figure>`)
+    .join('\n');
+  return `<section class="gallery"><h2>Visual evidence gallery</h2>\n${items}\n</section>`;
+}
+
+function wrapHtml(title, body, gallery) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; line-height: 1.5; max-width: 960px; margin: 0 auto; padding: 24px; color: #172b4d; }
+    .confluence-hint { background: #deebff; border-left: 4px solid #0052cc; padding: 12px 16px; margin-bottom: 24px; font-size: 14px; }
+    h1, h2, h3 { line-height: 1.25; }
+    table { border-collapse: collapse; width: 100%; margin: 16px 0; }
+    th, td { border: 1px solid #dfe1e6; padding: 8px 12px; text-align: left; vertical-align: top; }
+    th { background: #f4f5f7; }
+    img { max-width: 100%; height: auto; border: 1px solid #dfe1e6; border-radius: 3px; }
+    figure { margin: 16px 0; }
+    figcaption { font-size: 12px; color: #5e6c84; margin-top: 4px; }
+    pre { background: #f4f5f7; padding: 12px; overflow-x: auto; border-radius: 3px; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 0.9em; }
+    .gallery { margin-top: 48px; padding-top: 24px; border-top: 2px solid #dfe1e6; }
+    .gallery figure { display: inline-block; width: 48%; margin: 1%; vertical-align: top; }
+  </style>
+</head>
+<body>
+  <div class="confluence-hint">
+    <strong>Confluence:</strong> Open this file in a browser → <kbd>⌘A</kbd> / <kbd>Ctrl+A</kbd> → Copy → Paste into Confluence.
+    Images load from the local <code>assets/</code> folder — keep PNG files alongside this HTML when sharing.
+  </div>
+  <main>
+${body}
+  </main>
+${gallery}
+</body>
+</html>`;
+}
+
+function convertFile(mdPath) {
+  const abs = path.resolve(mdPath);
+  if (!fs.existsSync(abs)) {
+    console.error(`[build-html-reports] not found: ${abs}`);
+    return false;
+  }
+  const md = fs.readFileSync(abs, 'utf8');
+  const dir = path.dirname(abs);
+  const base = path.basename(abs, '.md');
+  const assetsDir = path.join(dir, 'assets');
+  const title = base;
+  const body = mdToHtml(md);
+  const gallery = buildGallery(assetsDir);
+  const html = wrapHtml(title, body, gallery);
+  const outPath = path.join(dir, `${base}.html`);
+  fs.writeFileSync(outPath, html);
+  console.log(`[build-html-reports] ${outPath}`);
+  return true;
+}
+
+function collectMdFiles(dir) {
+  const abs = path.resolve(dir);
+  if (!fs.existsSync(abs)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+    const full = path.join(abs, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'assets' || entry.name === 'node_modules') continue;
+      results.push(...collectMdFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith('.md') && /AUDIT/i.test(entry.name)) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function main() {
+  const { files, dirs } = parseArgs(process.argv.slice(2));
+  const targets = [...files];
+  for (const d of dirs) targets.push(...collectMdFiles(d));
+
+  if (!targets.length) {
+    console.error('[build-html-reports] Usage: --file <path.md> | --dir <folder>');
+    process.exit(1);
+  }
+
+  let ok = 0;
+  for (const f of [...new Set(targets)]) {
+    if (convertFile(f)) ok++;
+  }
+  if (ok === 0) process.exit(1);
+}
+
+main();

package/scripts/ux-audit-capture.mjs

@@ -7,7 +7,7 @@
  * Usage:
  *   npx playwright install chromium   # once, if not already installed
  *   node scripts/ux-audit-capture.mjs --url http://localhost:5173 \
- *     --out docs/ux-audit/assets --routes /,/dashboard/teams
+ *     --out docs/ux-audit/assets --routes /,/dashboard/teams --widths 1440,768
  *
  * Requires the optional "playwright" dependency (see package.json).
  */
@@ -18,15 +18,17 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 function parseArgs(argv) {
-  const opts = { url: null, out: null, routes: ['/'], width: 1440, height: 900 };
+  const opts = { url: null, out: null, routes: ['/'], widths: [1440], height: 900 };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--url') opts.url = argv[++i];
     else if (arg === '--out') opts.out = argv[++i];
     else if (arg === '--routes') opts.routes = argv[++i].split(',').map((r) => r.trim()).filter(Boolean);
-    else if (arg === '--width') opts.width = parseInt(argv[++i], 10) || 1440;
+    else if (arg === '--width') opts.widths = [parseInt(argv[++i], 10) || 1440];
+    else if (arg === '--widths') opts.widths = argv[++i].split(',').map((w) => parseInt(w.trim(), 10)).filter(Boolean);
     else if (arg === '--height') opts.height = parseInt(argv[++i], 10) || 900;
   }
+  if (!opts.widths.length) opts.widths = [1440];
   return opts;
 }
 
@@ -36,10 +38,10 @@ function routeToFilename(route, width) {
 }
 
 async function main() {
-  const { url, out, routes, width, height } = parseArgs(process.argv.slice(2));
+  const { url, out, routes, widths, height } = parseArgs(process.argv.slice(2));
 
   if (!url || !out) {
-    console.error('[ux-audit-capture] Usage: --url <base-url> --out <dir> [--routes /,/foo,/bar] [--width 1440] [--height 900]');
+    console.error('[ux-audit-capture] Usage: --url <base-url> --out <dir> [--routes /,/foo] [--width 1440 | --widths 1440,768] [--height 900]');
     process.exit(1);
   }
 
@@ -54,21 +56,24 @@ async function main() {
   fs.mkdirSync(out, { recursive: true });
 
   const browser = await chromium.launch();
-  const page = await browser.newPage({ viewport: { width, height } });
-
   const results = [];
-  for (const route of routes) {
-    const target = new URL(route, url).toString();
-    const file = path.join(out, routeToFilename(route, width));
-    try {
-      await page.goto(target, { waitUntil: 'networkidle', timeout: 15000 });
-      await page.screenshot({ path: file, fullPage: true });
-      results.push({ route, file, ok: true });
-      console.log(`[ux-audit-capture] captured ${route} -> ${file}`);
-    } catch (err) {
-      results.push({ route, file: null, ok: false, error: err.message });
-      console.error(`[ux-audit-capture] failed ${route}: ${err.message}`);
+
+  for (const width of widths) {
+    const page = await browser.newPage({ viewport: { width, height } });
+    for (const route of routes) {
+      const target = new URL(route, url).toString();
+      const file = path.join(out, routeToFilename(route, width));
+      try {
+        await page.goto(target, { waitUntil: 'networkidle', timeout: 15000 });
+        await page.screenshot({ path: file, fullPage: true });
+        results.push({ route, width, file, ok: true });
+        console.log(`[ux-audit-capture] captured ${route} @${width}w -> ${file}`);
+      } catch (err) {
+        results.push({ route, width, file: null, ok: false, error: err.message });
+        console.error(`[ux-audit-capture] failed ${route} @${width}w: ${err.message}`);
+      }
     }
+    await page.close();
   }
 
   await browser.close();