Richie
aa7cdeecf0
Phase 1: Session log archived (1096→91 lines), D031 token access convention
Phase 2: ESLint v9 + Prettier + jsx-a11y, initial config and lint fixes
Phase 3: 7 new skills (polish, harden, normalize, clarify, typeset, quieter, adapt)
+ Vercel reference docs, updated audit/review-component refs
Phase 4: Husky + lint-staged pre-commit hooks, preflight updated to 8 checks
Phase 5: Vitest + Testing Library + /write-tests skill
- Badge.tsx colour maps unified to CSS variables (D031)
- 5 empty interface→type alias fixes (Switch, Radio, Divider, IconButton, Link)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
121 lines
4.5 KiB
Markdown
121 lines
4.5 KiB
Markdown
---
|
|
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. Adapted from impeccable (Apache 2.0).
|
|
user-invocable: true
|
|
argument-hint: "[component or area to audit]"
|
|
---
|
|
|
|
Run systematic **technical** quality checks on a component or area and generate a scored report. This is assessment-only — don't fix issues, document them.
|
|
|
|
**Target:** $ARGUMENTS
|
|
|
|
## Preparation
|
|
|
|
1. Read `docs/design-system.md` for FA design conventions
|
|
2. Read the component/area source files
|
|
3. Reference `docs/reference/impeccable/` for detailed design guidelines when scoring
|
|
4. Reference `docs/reference/vercel/web-design-guidelines.md` for additional WCAG/accessibility rules (optional, for deeper a11y scoring)
|
|
|
|
## Diagnostic Scan
|
|
|
|
Score each dimension 0-4.
|
|
|
|
### 1. Accessibility (A11y)
|
|
|
|
**Check for**:
|
|
- Contrast ratios < 4.5:1 for text, < 3:1 for large text and UI components
|
|
- Missing ARIA: interactive elements without proper roles, labels, or states
|
|
- Keyboard navigation: missing focus-visible indicators, illogical tab order
|
|
- Semantic HTML: divs instead of buttons, missing landmarks, heading hierarchy
|
|
- Form issues: inputs without labels, poor error messaging
|
|
- Touch targets < 44px (critical for FA's audience — elderly, distressed)
|
|
|
|
**Score**: 0=Fails WCAG A, 1=Major gaps, 2=Partial effort, 3=AA mostly met, 4=AA fully met
|
|
|
|
### 2. Performance
|
|
|
|
**Check for**:
|
|
- Expensive animations: animating layout properties instead of transform/opacity
|
|
- Missing optimisation: unoptimised assets, missing lazy loading
|
|
- Bundle concerns: unnecessary imports, unused dependencies
|
|
- Render performance: unnecessary re-renders, missing memoisation
|
|
|
|
**Score**: 0=Severe issues, 1=Major problems, 2=Partial, 3=Mostly optimised, 4=Excellent
|
|
|
|
### 3. Theming & Token Compliance
|
|
|
|
**Check for**:
|
|
- Hardcoded colours not using theme palette or CSS variables
|
|
- Hardcoded spacing not using theme.spacing() or token values
|
|
- Hardcoded typography not using theme.typography variants
|
|
- Inconsistent token usage: wrong tier (primitive instead of semantic)
|
|
- Component tokens missing `$description` fields
|
|
|
|
**Score**: 0=Hardcoded everything, 1=Minimal tokens, 2=Inconsistent, 3=Good with minor gaps, 4=Full token compliance
|
|
|
|
### 4. Responsive Design
|
|
|
|
**Check for**:
|
|
- Fixed widths that break on mobile
|
|
- Touch targets < 44px on interactive elements
|
|
- Horizontal scroll/overflow on narrow viewports
|
|
- Text scaling: layouts that break when text size increases
|
|
- Missing responsive padding (mobile vs desktop)
|
|
|
|
**Score**: 0=Desktop-only, 1=Major issues, 2=Partial, 3=Good, 4=Fluid and responsive
|
|
|
|
### 5. Design Quality
|
|
|
|
**Check against these anti-patterns** (from impeccable frontend-design guidelines):
|
|
- Gray text on coloured backgrounds (looks washed out)
|
|
- Cards nested inside cards (visual noise)
|
|
- Identical card grids with no variation
|
|
- Bounce/elastic easing (dated, tacky)
|
|
- Every button styled as primary (no hierarchy)
|
|
- Redundant copy (headers restating the same info)
|
|
- Glassmorphism/blur used decoratively
|
|
- Missing interactive states (hover without focus, or vice versa)
|
|
|
|
**Score**: 0=Multiple anti-patterns, 1=Several issues, 2=A couple, 3=Mostly clean, 4=Intentional, distinctive design
|
|
|
|
## Report Format
|
|
|
|
### Audit Health Score
|
|
|
|
| # | Dimension | Score | Key Finding |
|
|
|---|-----------|-------|-------------|
|
|
| 1 | Accessibility | ? | |
|
|
| 2 | Performance | ? | |
|
|
| 3 | Theming & Tokens | ? | |
|
|
| 4 | Responsive Design | ? | |
|
|
| 5 | Design Quality | ? | |
|
|
| **Total** | | **??/20** | **[Rating]** |
|
|
|
|
**Ratings**: 18-20 Excellent, 14-17 Good, 10-13 Acceptable, 6-9 Poor, 0-5 Critical
|
|
|
|
### Executive Summary
|
|
- Score and rating
|
|
- Issue count by severity (P0/P1/P2/P3)
|
|
- Top 3-5 critical issues
|
|
- Recommended next steps
|
|
|
|
### Detailed Findings
|
|
|
|
Tag each issue **P0-P3**:
|
|
- **P0 Blocking**: Prevents task completion — fix immediately
|
|
- **P1 Major**: WCAG AA violation or significant UX issue — fix before release
|
|
- **P2 Minor**: Annoyance, workaround exists — fix in next pass
|
|
- **P3 Polish**: Nice-to-fix — address if time permits
|
|
|
|
For each issue:
|
|
- **[P?] Issue name**
|
|
- **Location**: Component, file, line
|
|
- **Category**: Accessibility / Performance / Theming / Responsive / Design Quality
|
|
- **Impact**: How it affects users
|
|
- **Recommendation**: How to fix it
|
|
|
|
### Positive Findings
|
|
Note what's working well — good practices to maintain.
|
|
|
|
**NEVER**: Report issues without explaining impact. Provide generic recommendations. Skip positive findings. Mark everything as P0.
|