Design QA

Structured quality gate for UI code. Run against any component, page, or feature before shipping. Every check is binary — pass or fail. Report ONLY failures. Silence = quality.

Scanner

bash "$PI_SKILL_DIR/scripts/design-scan.sh" <target-dir>                  # human output
bash "$PI_SKILL_DIR/scripts/design-scan.sh" <target-dir> --json           # machine output (stdout = pure JSON)
bash "$PI_SKILL_DIR/scripts/design-scan.sh" <target-dir> --critical-only  # gate only Critical findings
bash "$PI_SKILL_DIR/scripts/design-scan.sh" <target-dir> --allowlist FILE # structured exceptions
bash "$PI_SKILL_DIR/scripts/design-scan.sh" <target-dir> --allow-empty    # zero supported files is not an error

If $PISKILLDIR is unset, resolve the script relative to this SKILL.md's directory.

Dependencies: rg and jq required in every mode. ast-grep optional (adds structural TSX checks).

Support tiers: lexical checks cover tsx jsx ts js css scss html vue svelte astro mdx; structural checks are TSX-only (the shipped ast-grep rule set). Symlinked files are not followed.

Exit contract:

JSON schema: status pass|fail, target, scannedFiles, support, total/critical/high/medium, advisory score, categories, issues[] (each: severity, category, file, one-based line, content, fix). On scanner error with --json: {"status":"error","errors":[…]} and exit 2.

Allowlist format (tab-separated, # comments): CATEGORY<TAB>PATH_REGEX<TAB>REASON. Category exact or *. Invalid rows exit 2.

The scanner covers only mechanical facts. Scanner silence says nothing about the judgment checks below — run the gates after the scan, in order, and report failures with line numbers and fixes. Finish with Gate 12 whenever the app can be rendered — the rendered page outranks source-level passes.

Gate 1: Anti-Slop (Critical)

Mechanical rows are scanner-automated; judgment rows apply the intent-and-repetition test — the treatment communicates state, hierarchy, focus, information, or brand meaning, and is bounded to a named role.

Gate 2: Typography

Gate 3: Color

Gate 4: Spacing

Gate 5: Component Reuse

Gate 6: Interaction States

Gate 7: Accessibility

Gate 8: Product States & Edge Cases

Gate 9: Performance

Gate 10: Responsive

Gate 11: Error Resilience

Gate 12: Live Verification (agent-browser)

Static gates read source; this gate checks the rendered page.

Prerequisites: a dev/preview command exists (or a URL is supplied) and agent-browser responds. Both present → the gate is mandatory. Either missing → record Gate 12: N-A — <which prerequisite is missing and why>. N-A is never a pass; a state that should exist but cannot be exposed is a failing state check.

Viewports: 375×812 and 1440×900 always; 768×1024 when the layout has a tablet breakpoint.

States: loaded (both required viewports) — then empty, loading, error, long-content, interactive states at one representative viewport each; dark mode and reduced-motion when supported. Repeat a state at a second viewport only when responsive behavior could change its verdict.

Machine probes (binary): console/page/network errors = 0 · no horizontal overflow at 375px · one h1, ordered headings in the accessibility snapshot · rendered contrast meets Gate 3 floors · focus ring visible on every interactive element in a tab cycle · primary targets ≥44px at 375px · no dead-air bands above the runbook probe's fail tier at 1440px (judge-tier bands reviewed against Gate 4) · marketing: zero full-width section rules and ≤3 distinct section surfaces · reduced-motion emulation removes positional animation.

Screenshot review (judgment): overlap, hierarchy, blank/thin sections, truncation recovery, empty-state usefulness, dark-mode quality, visible anti-slop regressions — against Gate 1.

Exact commands, probe JavaScript, and evidence schema: READ [reference/live-verification.md](reference/live-verification.md) before running this gate.

Complete when every required state × viewport has a screenshot + console/error capture recorded, every machine probe is listed in the report with its measured result (a probe not listed was not run — the gate is incomplete), all probes pass, and no Critical visual finding remains. Attach screenshot paths and repro steps for every finding. A failure here outranks any static-gate pass — the rendered page is the product.

Report Format

## QA Report: [Component/Page Name]

### Critical (must fix before merge)
- **[Gate]: [Check]** — [File:Line] — [Issue and fix]

### High (fix soon)
- **[Gate]: [Check]** — [File:Line] — [Issue and fix]

### Medium (improve when touching this code)
- **[Gate]: [Check]** — [File:Line] — [Issue and fix]

Severity: Critical = accessibility blockers, dead controls, Gate 1 hard guardrails, Gate 12 machine-probe failures, blank/broken render. High = hardcoded colors, missing required states or recovery, spacing/type system violations, missing loading/rollback. Medium = contextual craft issues and non-blocking polish.

Quick-Check (6 items for fast PR reviews)

1. No anti-slop patterns (Gate 1)
2. No hardcoded colors (Gate 3)
3. Focus visible on all interactives (Gate 6)
4. Four-state contract on async surfaces (Gate 8)
5. No layout animations (Gate 9)
6. Renders clean at 1440px + 375px with zero console errors (Gate 12; N-A per its rule when no renderable target exists)