/audit

name: audit
description: "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review."
argument-hint: "[area (feature, page, component...)]"
user-invocable: false

MANDATORY PREPARATION

Invoke /frontend-design — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first.

---

Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address.

This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.

Diagnostic Scan

Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.

1. Accessibility (A11y)

**Check for**:

• **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA)
• **Missing ARIA**: Interactive elements without proper roles, labels, or states
• **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps
• **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons
• **Alt text**: Missing or poor image descriptions
• **Form issues**: Inputs without labels, poor error messaging, missing required indicators

**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA)

2. Performance

**Check for**:

• **Layout thrashing**: Reading/writing layout properties in loops
• **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity
• **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change
• **Bundle size**: Unnecessary imports, unused dependencies
• **Render performance**: Unnecessary re-renders, missing memoization

**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized)

3. Theming

**Check for**:

• **Hard-coded colors**: Colors not using design tokens
• **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme
• **Inconsistent tokens**: Using wrong tokens, mixing token types
• **Theme switching issues**: Values that don't update on theme change

**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly)

4. Responsive Design

**Check for**:

• **Fixed widths**: Hard-coded widths that break on mobile
• **Touch targets**: Interactive elements < 44x44px
• **Horizontal scroll**: Content overflow on narrow viewports
• **Text scaling**: Layouts that break when text size increases
• **Missing breakpoints**: No mobile/tablet variants

**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets)

5. Anti-Patterns (CRITICAL)

Check against ALL the **DON'T** guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy).

**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design)

Generate Report

Audit Health Score

| # | Dimension | Score | Key Finding | |---|-----------|-------|-------------| | 1 | Accessibility | ? | [most critical a11y issue or "--"] | | 2 | Performance | ? | | | 3 | Responsive Design | ? | | | 4 | Theming | ? | | | 5 | Anti-Patterns | ? | | | **Total** | | **??/20** | **[Rating band]** |

**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)

Anti-Patterns Verdict

**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest.

Executive Summary

• Audit Health Score: **??/20** ([rating band])
• Total issues found (count by severity: P0/P1/P2/P3)
• Top 3-5 critical issues
• Recommended next steps

Detailed Findings by Severity

Tag every issue with **P0-P3 severity**:

• **P0 Blocking**: Prevents task completion — fix immediately
• **P1 Major**: Significant difficulty or WCAG AA violation — fix before release
• **P2 Minor**: Annoyance, workaround exists — fix in next pass
• **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits

For each issue, document:

• **[P?] Issue name**
• **Location**: Component, file, line
• **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern
• **Impact**: How it affects users
• **WCAG/Standard**: Which standard it violates (if applicable)
• **Recommendation**: How to fix it
• **Suggested command**: Which command to use (prefer: /audit, /critique, /normalize, /polish, /distill, /clarify, /optimize, /harden, /animate, /colorize, /bolder, /quieter, /delight, /extract, /adapt, /onboard, /typeset, /arrange, /overdrive, /teach-impeccable)

Patterns & Systemic Issues

Identify recurring problems that indicate systemic gaps r