audit

What this skill does

# Design Audit Skill

Audits UI designs for compliance against the 60-rule design standard (`constitution/standards/design/`). Claude acts as a thin orchestrator: the Python CLI (`python3 -m audit_cli`) owns crawl, interaction discovery, dedup, and automated audit runs; Claude handles only the subjective visual judgments the CLI flags and renders the final report. Like `/lint` for visual design -- reports scored findings with severity classification, does NOT fix.

> **Visual Grounding Principle**: The **primary** visual evidence for every AI-adjudicated finding is a **section-focused crop** bounded by `getBoundingClientRect()` of a known section element (minimum: **nav, hero, mid, footer**; also TOC, CTA, pricing-band when detected), captured **per viewport** (desktop/tablet/mobile) so cross-viewport regressions stay visible. A full-page top-to-bottom screenshot **may** accompany a crop as **supplementary context**, but **must not** be the only image passed to AI assessment -- at thumbnail scale it loses pixel fidelity everywhere. In report artifacts, `evidence.crop_path` (section crop) is primary; `evidence.context_path` (full-page) is supplementary. If only a full-page screenshot exists, the reviewer records `ai_verdict.passed = null` with reason `"missing_section_crop"` and surfaces it as a **skill defect**, not a rule failure.

## 1. INTRODUCTION

### Purpose & Context

**Purpose**: Produce a comprehensive, evidence-backed design audit report covering 60 rules across 13 categories, using an automation CLI for deterministic checks and AI visual grounding for rules that require subjective judgment.

**When to use**:
- Audit design quality against the design standard (full, quick, or category-specific)
- Check accessibility and WCAG AA compliance with rendered values
- Design QA before handoff, launch, or PR merge
- Evaluate responsive behavior across desktop, tablet, and mobile viewports

**Prerequisites**:
- chrome-devtools MCP is **required** (primary Chrome owner): launched with `--isolated`, it creates an isolated Chrome instance per session. Confirm Chrome is running with `list_pages` before proceeding.
- `agent-browser` CLI: secondary browser client that connects to chrome-devtools MCP's Chrome via `--cdp <port>`. Subcommands used by this skill: `--cdp <port> open <url>` (attach to existing Chrome), `wait --fn` (await readiness predicates), `eval` (inject audit scripts into the live page).
- Python 3 available (for the `audit_cli` package and static servers)

### Your Role

You are a **Design QA Director** who delegates mechanical work to the audit CLI and reserves your attention for subjective visual judgments. You never fix issues -- only adjudicate, classify, and report them. Your approach:

- **Thin orchestrator**: Invoke the CLI, then review only items it flags `needs_ai_review`
- **Evidence-first**: Every AI verdict cites the crop image the CLI captured
- **No re-runs**: Do not re-crawl, re-capture, or re-audit rules the CLI already covered
- **Systematic Coverage**: Every rule is checked; no category is skipped
- **Multi-Viewport**: Every page is tested at desktop, tablet, and mobile breakpoints (CLI-owned)

## 2. SKILL OVERVIEW

### Skill Input/Output Specification

#### Required Inputs

- **Target**: URL of a live page, OR path to a source code project (Next.js, Vite, CRA, static HTML)

#### Optional Inputs

- **Scope**: `full` (all 60 rules, default), `quick` (text + structure only), or a specific category name
- **Pages**: List of specific routes/paths to audit (default: current URL only)
- **`--all-pages`**: Enable multi-page crawling via navigation discovery. Without this flag, only the current URL is audited
- **DESIGN.md path**: Path to project design tokens document (auto-detected if not provided)

#### Expected Outputs

- **Markdown report**: Scored findings with evidence, output to conversation
- **JSON summary**: Machine-readable contract appended as code block
- **Section crops (primary)**: Section-focused screenshot crops (nav, hero, mid, footer minimum; TOC/CTA/pricing-band when detected) captured per viewport. Attached to findings as `evidence.crop_path`.
- **Full-page screenshots (supplementary)**: Top-to-bottom captures retained only as `evidence.context_path` for cross-section rhythm checks. Never the sole image on a finding -- if a section crop is missing, AI verdict is `null` with reason `"missing_section_crop"` (skill defect, not a rule failure).

#### Data Flow Summary

The skill takes a target URL or source project and hands it to the Python audit CLI, which crawls, captures screenshots/snapshots at 3 viewports, injects audit scripts, discovers and exercises interactive elements, deduplicates recurring components site-wide, and writes a structured `report.json`. Claude then opens the report, fills in AI verdicts for items marked `needs_ai_review`, and renders the final markdown using `references/review-template.md`. Screenshots persist in an OS temp directory (`$TMPDIR/audit-<kebab>-<ts>/`) and are served via the CLI's HTTP server for report linking.

**Capture step (Visual Grounding contract)**: During Phase 2, the CLI captures **section-focused crops** (nav, hero, mid, footer at minimum; TOC/CTA/pricing-band when detected) at **each viewport** (desktop/tablet/mobile). These section crops are the **primary** visual artifacts attached to findings as `evidence.crop_path`. A full-page screenshot may be additionally retained as `evidence.context_path` for supplementary disambiguation, but is never the sole image passed to AI assessment.

### Visual Overview

```plaintext
  PHASE 1: PLAN                    PHASE 1.5: OPEN BROWSER
  ─────────────                    ───────────────────────
  Parse input mode                 list_pages (confirm MCP Chrome running)
  (URL or source code)             Note port from webSocketDebuggerUrl
  │                                new_page <url>
  ├─ URL → target_url              agent-browser --cdp <port> open <url>
  └─ Source → target_url +         chrome-devtools MCP owns Chrome;
              source_path          agent-browser connects as CDP client.
  │                                │
  Resolve viewports                v
  Resolve scope                    PHASE 2: DELEGATE TO CLI
  Emit plan:                       ────────────────────────
  {target_url, source_path?,       python3 -m audit_cli audit <url> \
   scope, viewports, all_pages}      --all-pages? --source? --viewports
  │                                  --scope --out $TMPDIR/audit-<...>
  │                                │
  │                                CLI owns:
  │                                  route discovery, BFS crawl,
  │                                  interaction discovery, recurring-
  │                                  element dedup, 3-viewport capture,
  │                                  automated rule runs, crop capture,
  │                                  cross-origin filtering
  │                                │
  │                                Exit 0 → last stdout line = out dir
  │                                │
  v                                v
  PHASE 3: AI VISUAL REVIEW        PHASE 4: REPORT
  ─────────────────────────        ────────────────
  Read <out>/report.json           Render per review-template.md
  Prompt once on cross_origin_       Context, scores, findings by
    candidates (if any)              priority, findings by area
  For each finding with            Append Site-Level Findings
    needs_ai_review: open crop,      (orphan routes, recurring
    apply ai_prompt, fill            elements, cross-origin,
    ai_verdict                       per-page scores, worst 3)
  Write <out>/report-final.json    JSON summary block
```

### 60-Rule Coverage

| Category | Automated | AI/Grounding | Total |
|----------|-----------|--------------|-------|
| Text & readability | 8 | 0 | 8 |
| Semantic structure | 9 | 0 | 9 |
| Accessibility | 3 | 1 (partial) | 4 |
| Interaction