# Design Review

## Purpose

Define design review process and UI/UX quality standards.

## Scope

**In**: UI review criteria, design consistency, accessibility.
**Out**: Implementation details (see agents/coding-standards.md).

## Registry-First Pre-Work (BLOCKING when `features.has_design_system: true`)

Before walking the checklist below, execute the cascade defined in
[`framework/agents/design-system-protocol.md`](design-system-protocol.md):

1. Read `${paths.design_system}/INDEX.md` and extract the Authority Matrix for
   every primitive present on the route under review.
2. Read `${paths.design_system}/tokens-reference.md` and use it as the SSOT
   when judging color / shadow / radius / spacing decisions.
3. For each component visible in the screenshots/DOM, read the corresponding
   `${paths.design_system}/components/<Name>.md` spec.

When `features.has_design_system: false`, skip the registry reads and run the
checklist using `${paths.ui_guidelines}` alone — but flag in the report that
the absence of a registry is preventing systematic conformance checks, and
recommend `/design-system-init`.

## Do

- Review designs before implementation
- Check accessibility
- Ensure consistency with design system
- Test across devices/browsers

## Do Not

- Skip design review for "small" changes
- Ignore accessibility requirements
- Assume designs work on all screen sizes

## Design Review Checklist

### Design-System Conformance (when `has_design_system: true`)

- [ ] Every primitive in the DOM is listed in `${paths.design_system}/INDEX.md`
- [ ] No reinvented variant of an existing registry primitive
- [ ] No hardcoded color / shadow / radius / spacing values that bypass
      `${paths.design_system}/tokens-reference.md`
- [ ] Each component matches its `components/<Name>.md` spec (props, variants,
      a11y hooks)
- [ ] Authority Matrix respected — no local override of registry-authoritative
      decisions
- [ ] New primitives introduced in the change ship with their per-component
      spec in the same change

### Visual Design

- [ ] Follows design system/style guide
- [ ] Consistent spacing and alignment
- [ ] Appropriate typography
- [ ] Color contrast meets WCAG standards
- [ ] Icons and imagery appropriate
- [ ] Loading states designed
- [ ] Error states designed
- [ ] Empty states designed

### Layout

- [ ] Responsive across breakpoints
- [ ] Mobile-first approach
- [ ] Proper use of grid/flexbox
- [ ] No horizontal scroll on mobile
- [ ] Touch targets minimum 44x44px
- [ ] Content hierarchy clear

### Interaction Design

- [ ] Clear call-to-actions
- [ ] Feedback for user actions
- [ ] Loading indicators where needed
- [ ] Error messages helpful
- [ ] Forms easy to complete
- [ ] Navigation intuitive

### Accessibility (WCAG 2.1 AA)

- [ ] Color contrast ≥ 4.5:1 (text)
- [ ] Color contrast ≥ 3:1 (UI components)
- [ ] Keyboard navigation works
- [ ] Focus indicators visible
- [ ] Alt text for images
- [ ] ARIA labels where needed
- [ ] Form labels proper
- [ ] Screen reader friendly

### Performance

- [ ] Images optimized
- [ ] Fonts optimized
- [ ] Animations performant
- [ ] No layout shift
- [ ] Fast loading

### Content

- [ ] Copy clear and concise
- [ ] Tone consistent with brand
- [ ] No jargon (unless necessary)
- [ ] Error messages helpful
- [ ] Microcopy thoughtful

## Review Process

### 1. Pre-Implementation Review

- Review designs/mockups
- Clarify requirements
- Identify technical constraints
- Estimate effort

### 2. Implementation Review

- Build matches design
- Interactions work as specified
- Edge cases handled

### 3. Final Review

- Test on multiple devices
- Test on multiple browsers
- Accessibility check
- Performance check

## Common Issues

### Layout Issues

- Inconsistent spacing
- Misaligned elements
- Broken responsive behavior
- Text overflow

### Interaction Issues

- Missing feedback
- Confusing navigation
- Unclear error messages
- Slow interactions

### Accessibility Issues

- Low color contrast
- Missing alt text
- No keyboard navigation
- Poor focus indicators
- Missing ARIA labels

## Review Tools

- **Design**: [e.g., Figma, Sketch, Adobe XD]
- **Accessibility**: [e.g., axe DevTools, WAVE, Lighthouse]
- **Responsive**: [e.g., Browser DevTools, BrowserStack]
- **Performance**: [e.g., Lighthouse, WebPageTest]

## Design System

Reference your design system:

- **Components**: [Link to component library]
- **Colors**: [Link to color palette]
- **Typography**: [Link to typography scale]
- **Spacing**: [Link to spacing system]
- **Icons**: [Link to icon set]

## Browser Support

Define supported browsers:

| Browser | Minimum Version |
|---------|----------------|
| Chrome | [version] |
| Firefox | [version] |
| Safari | [version] |
| Edge | [version] |
| Mobile Safari | [version] |
| Mobile Chrome | [version] |

## Device Support

Define supported devices:

- **Desktop**: [min resolution]
- **Tablet**: [resolution range]
- **Mobile**: [resolution range]

## Review Outcomes

- **Approved**: Ready for implementation/deployment
- **Approved with minor changes**: Small tweaks needed
- **Needs revision**: Significant changes required
- **Rejected**: Fundamental issues, needs redesign

## Report Template

Every `/design-review` report MUST include a top-level section
**Design-System Conformance** with these subsections (when
`has_design_system: true`):

- **Primitives reused** — list of `<Name>` taken from
  `${paths.design_system}/INDEX.md`.
- **Primitives reinvented** — DOM components that duplicate or overlap with an
  existing registry primitive. HIGH severity.
- **Tokens bypassed** — hardcoded values that should have used a token from
  `tokens-reference.md`. HIGH severity.
- **Spec drift** — components in the diff that diverge from their
  `components/<Name>.md`. MEDIUM severity.
- **New primitives proposed** — components that legitimately need a new
  registry entry, with a one-line justification.

When `has_design_system: false`, replace the section with:
> Design-system conformance check skipped — `features.has_design_system: false`.
> Run `/design-system-init` to enable systematic conformance checks.
