---
name: review-component
description: Review a component against design system conventions
argument-hint: "[ComponentName]"
---

Review a component against FA Design System conventions and report pass/fail for each check.

**Component to review:** $ARGUMENTS

**Instructions:**
1. Read `docs/conventions/component-conventions.md` for the rules
2. Read `docs/conventions/token-conventions.md` for token usage rules
3. Read the component source file in `src/components/`
4. Read the component's Storybook stories
5. Reference `docs/reference/vercel/react-best-practices.md` for React performance patterns (optional, for deeper code quality review)

**Check each of these and report pass/fail:**

### Code quality
- [ ] Component uses TypeScript with proper types
- [ ] Props interface exported with JSDoc on every prop
- [ ] Uses `React.forwardRef` for interactive elements
- [ ] Accepts and forwards `sx` prop
- [ ] Uses `shouldForwardProp` for custom props on styled components

### Theme compliance
- [ ] NO hardcoded colours — all from `theme.palette.*`
- [ ] NO hardcoded spacing — all from `theme.spacing()`
- [ ] NO hardcoded typography — all from `theme.typography.*`
- [ ] NO hardcoded shadows — all from `theme.shadows`
- [ ] NO hardcoded border radius — all from `theme.shape.*`

### Accessibility
- [ ] Minimum 44px touch target on mobile
- [ ] Visible focus indicator (focus-visible)
- [ ] Appropriate ARIA attributes
- [ ] Disabled state uses `aria-disabled`
- [ ] Colour contrast meets WCAG 2.1 AA

### Storybook coverage
- [ ] Default story
- [ ] All variants story
- [ ] All sizes story (if applicable)
- [ ] Disabled state
- [ ] Loading state (if applicable)
- [ ] Long content / overflow
- [ ] autodocs tag present

### Interactive states (ref: docs/reference/impeccable/interaction-design.md)
- [ ] Default (resting) state is styled
- [ ] Hover state provides visual feedback (not just cursor change)
- [ ] Focus-visible state is distinct from hover (keyboard users never see hover)
- [ ] Active/pressed state feels responsive
- [ ] Disabled state is visually diminished but still distinguishable
- [ ] Transitions use 150ms ease-in-out (FA convention)

### Design anti-patterns (ref: docs/reference/impeccable/frontend-design-skill.md)
- [ ] No grey text on coloured backgrounds (use a shade of the background colour instead)
- [ ] No cards nested inside cards (flatten hierarchy with spacing/typography)
- [ ] No identical card grids with zero variation (vary content, size, or emphasis)
- [ ] No bounce/elastic easing (use ease-out-quart or ease-in-out)
- [ ] Not every button is primary (use variant hierarchy: contained > soft > outlined > text)
- [ ] No redundant copy (headings don't restate content below them)
- [ ] No glassmorphism/blur used purely as decoration
- [ ] Whitespace is intentional, not leftover

**Report format:** List each check with pass/fail and specific issues found. End with a summary and recommended fixes.