PixelPilot uiux-audit-automation.instructions.md

UI/UX Audit Automation 2026

Navigate → inject axe-core → scan → report → fix. Produces a structured WCAG 2.1 AA + 3.0 violation report for any live URL or local dev server page.

---

PREREQUISITES

# Required MCP: Chrome DevTools (or Puppeteer MCP)
# Confirm it is active before running any step:
# - Tool: browser_navigate, browser_evaluate, browser_screenshot

# axe-core CDN (injected at runtime — no install needed):
AXE_CDN = "https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.9.1/axe.min.js"

---

STEP 1 — NAVIGATE TO TARGET

// Via Chrome DevTools MCP tool: browser_navigate
await browser_navigate({ url: TARGET_URL });
// Wait for network idle — important for SPAs
await browser_evaluate({ script: `
  await new Promise(resolve => {
    if (document.readyState === 'complete') return resolve();
    window.addEventListener('load', resolve);
  });
  await new Promise(r => setTimeout(r, 500)); // extra tick for hydration
` });

For local dev servers, use http://localhost:PORT/PATH. For SPAs, navigate to the specific route — not just /.

---

STEP 2 — INJECT AXE-CORE

await browser_evaluate({ script: `
  // Inject axe-core from CDN
  const script = document.createElement('script');
  script.src = '${AXE_CDN}';
  document.head.appendChild(script);
  await new Promise((res, rej) => {
    script.onload = res;
    script.onerror = () => rej(new Error('axe-core failed to load'));
  });
  console.log('axe-core loaded:', typeof axe !== 'undefined');
` });

---

STEP 3 — RUN THE SCAN

const results = await browser_evaluate({ script: `
  // Run full axe scan with WCAG 2.1 AA + 2.2 tags
  const results = await axe.run(document, {
    runOnly: {
      type: 'tag',
      values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa', 'best-practice']
    },
    resultTypes: ['violations', 'incomplete'],
  });

  // Summarise for output
  return {
    url:        location.href,
    timestamp:  new Date().toISOString(),
    violations: results.violations.map(v => ({
      id:          v.id,
      impact:      v.impact,          // critical | serious | moderate | minor
      description: v.description,
      help:        v.help,
      helpUrl:     v.helpUrl,
      wcag:        v.tags.filter(t => t.startsWith('wcag')),
      nodes:       v.nodes.map(n => ({
        html:    n.html.slice(0, 200),
        summary: n.failureSummary,
        target:  n.target,
      })),
    })),
    incomplete: results.incomplete.length,
    passes:     results.passes.length,
  };
` });