Interface Review

Terse PR comments. Actionable findings for code review, not teaching.

When to Use

Reviewing a PR
CI/automated checks
When brevity matters

Principles Reference

Before reviewing, know the principles:

Interaction: See principles/interaction.md Visual: See principles/visual.md

Output Format

## UX Review

### Interaction

⚠️ **Reversibility** — `src/components/ItemCard.tsx:42`
   Delete without undo. Add confirmation or soft delete.

⚠️ **Persistence** — `src/components/Form.tsx:15`
   Form state in useState only. Lost on refresh.

⚠️ **Forgiveness** — `src/components/SubmitButton.tsx:8`
   Button not disabled during async. Double-submit possible.

✓ **Transparency** — Error states show actionable messages
✓ **Escape** — Modal has close button and ESC handler
✓ **Consistency** — Delete behavior matches other screens

### Visual

⚠️ **States** — `src/components/UserList.tsx:23`
   No empty state. Show guidance when list is empty.

⚠️ **Accessibility** — `src/components/IconButton.tsx:5`
   Missing aria-label on icon-only button.

✓ **Motion** — prefers-reduced-motion respected
✓ **Layout** — Consistent spacing throughout

### Craft

⚠️ **Tokens** — `src/components/Card.tsx:12`
   Hardcoded colors (#3b82f6). Use design tokens.

⚠️ **Depth** — `src/components/Modal.tsx:8`
   Mixed strategies: borders AND shadows. Pick one.

✓ **Polish** — Hover and focus states present

Format Rules

Category header — Group by principle type
Status icon — ⚠️ for issues, ✓ for passing
Principle name in bold — One word identifier
File:line — Clickable location reference
One line problem + fix — Minimal explanation

What to Include

Interaction (from interaction principles)

Check	Pass/Fail Criteria
Reversibility	Delete handlers have confirmation/undo/trash
Forgiveness	Async buttons disabled during loading
Persistence	Important state survives refresh
Transparency	try/catch on async, errors explain next steps
Escape	Modals closeable, flows have back/cancel
Consistency	Same action = same behavior everywhere
Recognition	Options visible, not hidden behind memorization

Visual (from visual principles)

Check	Pass/Fail Criteria
States	Loading, empty, error states present
Accessibility	aria-labels, keyboard nav, focus management
Hierarchy	Consistent typography, single accent
Layout	Consistent spacing, proper mobile handling
Motion	reduced-motion respected, compositor props only

Craft (from visual principles)

Check	Pass/Fail Criteria
Tokens	Colors/spacing use tokens, not hardcoded values
Depth	ONE strategy (borders OR shadows), not mixed
Text hierarchy	Four levels defined, used consistently
Polish	Hover, focus, transition states present

Severity Markers

Use for serious issues only:

🔴 **Blocker: Accessibility** — `src/Button.tsx:12`
   div with onClick. Use <button> for keyboard access.

Most issues are just ⚠️ warnings.

What NOT to Include

Long explanations (save for audit mode)
Principle rationales (user can look them up)
Multiple fix options (just state what's needed)
Teaching content (this is for experienced reviewers)

Example: Full Review

## UX Review: PR #142 — Add item deletion

### Interaction

⚠️ **Reversibility** — `src/components/ItemCard.tsx:42`
   Delete without safeguard. Add confirmation dialog.

⚠️ **Reversibility** — `src/api/items.ts:28`
   Hard delete. Consider soft delete to trash.

✓ **Forgiveness** — Delete button styled distinctly from primary actions
✓ **Transparency** — Toast shown after deletion

### Visual

⚠️ **States** — `src/components/ItemList.tsx:15`
   No empty state after last item deleted.

✓ **Accessibility** — Delete button has aria-label
✓ **Motion** — No animations added

---

**Summary:** 3 issues (2 interaction, 1 visual). Main concern is delete without recovery path.

Integration Note

This format is designed for:

PR comments (GitHub, GitLab)
CI output
Slack summaries

Keep it scannable. Link to full docs if user wants to learn more.

interface-review