@jamie-tam/forge 6.0.0

package/skills/quality-uiux/SKILL.md

@@ -0,0 +1,481 @@
+---
+name: quality-uiux
+description: "Use when working on frontend code to evaluate accessibility, component reuse, design-token compliance, and interaction patterns."
+---
+
+# UI/UX Quality
+
+## Overview
+
+Evaluate frontend code for accessibility, usability, component quality, visual consistency, and library choices. Produce actionable recommendations that improve the user experience.
+
+**Core principle:** Good UI/UX is not decoration. It is usability, accessibility, and consistency -- measured and enforced, not subjective.
+
+**Announce at start:** "I'm using the quality-uiux skill to evaluate the frontend code."
+
+## When to Use
+
+- During or after frontend implementation
+- When adding new UI components
+- When choosing between UI libraries
+- When the user requests a UI/UX review
+- During `/feature` command when the feature has frontend components
+
+**Not for:**
+- Backend-only code
+- CLI tools (unless they have interactive UI)
+- API-only services
+
+## The Evaluation Process
+
+### Area 0: Codex Mode Check
+
+Run the Codex consent flow from `protocols/codex.md` before proceeding.
+
+- **Takeover selected:** Dispatch Codex to perform the full UI/UX evaluation across all 6 areas. Claude reviews the report.
+- **Verify selected** or **Skip / Codex unavailable:** Proceed with Areas 1-6 below. If Verify was selected, the Codex Accessibility Review step will dispatch Codex to check Claude's evaluation.
+
+### Area 1: Accessibility (WCAG Compliance)
+
+Check against Web Content Accessibility Guidelines (WCAG) 2.1 Level AA.
+
+#### Keyboard Navigation
+
+- [ ] All interactive elements are reachable via Tab key
+- [ ] Tab order follows visual layout (logical reading order)
+- [ ] Focus indicator is visible on all interactive elements
+- [ ] No keyboard traps (user can always Tab away from any element)
+- [ ] Custom components support expected keyboard interactions:
+  - Buttons: Enter/Space to activate
+  - Dropdowns: Arrow keys to navigate, Enter to select, Escape to close
+  - Modals: Escape to close, focus trapped inside while open
+  - Tabs: Arrow keys to switch, Tab to move into content
+
+**Check method:**
+```
+1. Start at the top of the page
+2. Press Tab repeatedly to navigate through all interactive elements
+3. Verify each element is reachable and usable
+4. Verify focus indicator is visible at each step
+5. Test Escape, Enter, Space, Arrow keys where applicable
+```
+
+#### Screen Reader Compatibility
+
+- [ ] All images have descriptive `alt` text (or `alt=""` for decorative images)
+- [ ] Form inputs have associated `<label>` elements (or `aria-label`/`aria-labelledby`)
+- [ ] Headings follow hierarchical order (h1 > h2 > h3, no skipping levels)
+- [ ] ARIA landmarks used appropriately (`main`, `nav`, `aside`, `footer`)
+- [ ] Dynamic content changes announced with `aria-live` regions
+- [ ] Custom components have appropriate ARIA roles
+- [ ] Error messages associated with form fields via `aria-describedby`
+- [ ] Page has a descriptive `<title>`
+
+**Common ARIA issues:**
+```html
+<!-- BAD: div acting as button without ARIA -->
+<div onClick={handleClick}>Submit</div>
+
+<!-- GOOD: proper button element -->
+<button onClick={handleClick}>Submit</button>
+
+<!-- GOOD: if div must be used, add ARIA -->
+<div role="button" tabIndex={0} onClick={handleClick}
+     onKeyDown={(e) => e.key === 'Enter' && handleClick()}>
+  Submit
+</div>
+```
+
+#### Color and Contrast
+
+- [ ] Text contrast ratio meets WCAG AA: 4.5:1 for normal text, 3:1 for large text
+- [ ] Information not conveyed by color alone (also use icons, patterns, text)
+- [ ] UI usable in high contrast mode
+- [ ] Focus indicators have sufficient contrast against background
+
+**Check method:**
+```
+1. Inspect text elements for color contrast ratios
+2. Check that error states use more than just red text (add icon or border)
+3. Check that success/warning/info states have non-color indicators
+4. Verify links are distinguishable from plain text without relying on color alone
+```
+
+#### Motion and Animation
+
+- [ ] Respects `prefers-reduced-motion` media query
+- [ ] No auto-playing animations that cannot be paused
+- [ ] No content that flashes more than 3 times per second
+- [ ] Transitions serve a purpose (communicate state change, not decoration)
+
+```css
+/* Respect user preference */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### Area 2: Responsive Design
+
+Verify the UI works across viewport sizes.
+
+#### Breakpoint Verification
+
+- [ ] Mobile (320px - 480px): Content readable, no horizontal scroll, touch targets 44x44px minimum
+- [ ] Tablet (481px - 768px): Layout adapts, navigation accessible
+- [ ] Desktop (769px - 1200px): Full layout, appropriate use of space
+- [ ] Large desktop (1201px+): Content does not stretch beyond readable width (max-width applied)
+
+#### Responsive Patterns
+
+- [ ] Navigation collapses to hamburger/drawer on mobile
+- [ ] Tables convert to cards or scroll horizontally on mobile
+- [ ] Images scale appropriately (no overflow, no pixelation)
+- [ ] Font sizes are readable at all viewports (minimum 16px body text on mobile)
+- [ ] Form layouts stack vertically on mobile
+- [ ] Modals/dialogs fill screen on mobile, center on desktop
+
+#### Touch Targets
+
+- [ ] All interactive elements are at least 44x44px on touch devices
+- [ ] Adequate spacing between touch targets (no accidental taps)
+- [ ] No hover-only interactions (provide tap alternatives)
+
+**Check method:**
+```
+1. Test at 320px, 768px, 1024px, 1440px viewport widths
+2. Verify no horizontal scrollbar at any width
+3. Verify all content is accessible at each width
+4. Check touch target sizes on mobile viewport
+```
+
+### Area 3: Component Reusability
+
+Evaluate component architecture for reuse and maintainability.
+
+#### Duplicate Detection
+
+Scan for components with similar purpose:
+
+```
+DUPLICATE FOUND:
+  - src/components/UserCard.tsx (used in /users page)
+  - src/features/dashboard/MemberCard.tsx (used in /dashboard)
+  Both render: user avatar, name, email, role badge.
+  Difference: UserCard has "edit" button, MemberCard has "remove" button.
+  RECOMMENDATION: Extract shared UserCardBase, compose with action slots.
+```
+
+- [ ] No two components render substantially the same UI
+- [ ] Shared patterns extracted to reusable components
+- [ ] Components accept composition via children/slots (not prop-based if/else)
+
+#### Component API Quality
+
+- [ ] Props have TypeScript types (no `any`)
+- [ ] Required vs optional props are clearly defined
+- [ ] Default values provided for optional props
+- [ ] Components are controlled or uncontrolled (not mixed)
+- [ ] Event handlers follow naming convention (onAction, handleAction)
+
+```typescript
+// BAD: unclear API
+interface Props {
+  data: any;
+  type: string;
+  show: boolean;
+  cb: Function;
+}
+
+// GOOD: clear, typed API
+interface UserCardProps {
+  user: User;
+  variant?: 'compact' | 'detailed';
+  isHighlighted?: boolean;
+  onEdit?: (userId: string) => void;
+  children?: React.ReactNode; // composition slot for actions
+}
+```
+
+#### Component Composition
+
+- [ ] Prefer composition over configuration (slots/children over boolean props)
+- [ ] No components with more than 10 props (split into smaller components)
+- [ ] No conditional rendering trees deeper than 3 levels
+- [ ] Business logic in hooks/services, not in component body
+
+### Area 4: Library Recommendations
+
+When the project needs a new UI library, evaluate candidates on these criteria.
+
+#### Evaluation Matrix
+
+| Criteria | Weight | How to Check |
+|----------|--------|-------------|
+| Bundle size | High | bundlephobia.com or `npm pack --dry-run` |
+| Tree-shakeable | High | Check if library supports ESM imports |
+| Maintenance | High | Last commit date, release frequency, open issues/PRs ratio |
+| Community | Medium | npm weekly downloads, GitHub stars, Stack Overflow questions |
+| TypeScript support | Medium | Built-in types vs @types package vs no types |
+| License | Medium | MIT/Apache preferred. Check for copyleft (GPL) restrictions. |
+| Accessibility | High | Built-in ARIA support, keyboard navigation |
+| Documentation | Medium | Quality of docs, examples, migration guides |
+| SSR compatibility | Varies | Server-side rendering support if needed |
+
+**Recommendation format:**
+```markdown
+### Library Recommendation: Date Picker
+
+| Candidate | Bundle Size | Downloads/wk | Last Release | TS | A11y | License |
+|-----------|-------------|-------------|--------------|-----|------|---------|
+| react-datepicker | 12KB | 2.1M | 2 weeks ago | Yes | Good | MIT |
+| @mui/x-date-pickers | 45KB | 800K | 1 week ago | Yes | Excellent | MIT |
+| react-day-picker | 8KB | 500K | 1 month ago | Yes | Good | MIT |
+
+**Recommendation:** react-day-picker
+**Reasoning:** Smallest bundle size, good accessibility, active maintenance.
+  MUI option is better for accessibility but 5x larger and pulls in MUI dependency.
+  react-datepicker is popular but larger than react-day-picker for similar features.
+```
+
+**Rules:**
+- Always compare at least 2 candidates
+- Bundle size matters -- every KB affects load time
+- Check if the library is actively maintained (last release within 6 months)
+- Verify TypeScript support quality (not just @types with 50 open issues)
+- Check license compatibility with project
+- Verify via context7 or websearch when uncertain about library features
+
+### Area 5: Visual Consistency
+
+**If `DESIGN.md` exists at the project root** (from `plan-design-system`), load it and validate the implementation against the approved design tokens. Every check below should reference the specific values from `DESIGN.md` rather than generic best practices. Flag any deviation where the implementation uses hardcoded values instead of the approved tokens. Also check for feature-scoped overrides in `.forge/work/{type}/{name}/design-overrides.md` — if present, those tokens take precedence over root `DESIGN.md` for this feature.
+
+**If no `DESIGN.md` exists** (on-demand review, bugfix, or backend-only), evaluate against the project's existing patterns.
+
+Check that the UI follows a consistent design language.
+
+#### Spacing System
+
+- [ ] Consistent spacing scale used (e.g., 4px, 8px, 12px, 16px, 24px, 32px, 48px)
+- [ ] No arbitrary pixel values (everything from the scale)
+- [ ] Consistent padding within similar components
+- [ ] Consistent margins between sections
+
+#### Typography
+
+- [ ] Consistent font family throughout (or intentional variation for headings)
+- [ ] Consistent type scale (e.g., 12px, 14px, 16px, 20px, 24px, 32px)
+- [ ] Line height appropriate for readability (1.4-1.6 for body text)
+- [ ] No more than 2-3 font weights used
+- [ ] Maximum line width for readability (45-75 characters)
+
+#### Color Usage
+
+- [ ] Consistent color palette (defined as variables/tokens)
+- [ ] Semantic color naming (--color-error, --color-success, not --color-red)
+- [ ] Consistent use of primary, secondary, accent colors
+- [ ] Dark mode support (if applicable) via CSS custom properties
+- [ ] No hardcoded color values in components (use tokens)
+
+```css
+/* BAD: hardcoded colors scattered throughout */
+.button { background: #3b82f6; }
+.link { color: #2563eb; }
+
+/* GOOD: design tokens */
+:root {
+  --color-primary: #3b82f6;
+  --color-primary-hover: #2563eb;
+  --color-error: #ef4444;
+  --color-success: #22c55e;
+}
+.button { background: var(--color-primary); }
+.link { color: var(--color-primary); }
+```
+
+#### Iconography
+
+- [ ] Consistent icon set used throughout (not mixing multiple icon libraries)
+- [ ] Icons have consistent size at each usage context
+- [ ] Icons have accessible labels (aria-label or accompanying text)
+
+### Area 6: Interaction Patterns
+
+Verify all UI states are handled properly.
+
+#### Loading States
+
+- [ ] Skeleton screens or spinners for async content
+- [ ] Loading indicators for form submissions
+- [ ] Button disabled state during async operations (prevent double submit)
+- [ ] Progressive loading for large lists (pagination or infinite scroll)
+- [ ] Timeout handling (show error after reasonable wait)
+
+```tsx
+// BAD: no loading state
+{data && <UserList users={data} />}
+
+// GOOD: all states handled
+{isLoading && <UserListSkeleton />}
+{error && <ErrorMessage error={error} onRetry={refetch} />}
+{data?.length === 0 && <EmptyState message="No users found" />}
+{data && data.length > 0 && <UserList users={data} />}
+```
+
+#### Error States
+
+- [ ] Form validation errors shown inline (next to the field, not just at top)
+- [ ] API error messages shown to user (not just console.error)
+- [ ] Network error handling (offline state, retry option)
+- [ ] Error boundary for unexpected crashes (show fallback UI)
+- [ ] Error messages are actionable ("Check your email format" not "Error 422")
+
+#### Empty States
+
+- [ ] Empty lists show helpful message (not blank space)
+- [ ] Empty states suggest action ("Add your first item")
+- [ ] Search with no results shows helpful message and suggestions
+- [ ] First-time user experience handles empty data gracefully
+
+#### Success States
+
+- [ ] Success feedback shown for form submissions (toast, redirect, inline message)
+- [ ] Optimistic updates where appropriate (with rollback on failure)
+- [ ] Confirmation for destructive actions (delete, cancel, discard)
+
+### Codex Accessibility Review 
+After completing all 6 evaluation areas, check the mode recorded at Area 0. If **Verify** was selected, dispatch Codex to review for missed accessibility issues, component consistency gaps, and responsive breakpoints. Merge findings into the evaluation report. If **Takeover** was selected, skip this step (Codex already ran). If **Skip**, do nothing. Do NOT re-run the consent flow. See **Codex Integration** section below for full details.
+
+## Evaluation Report Format
+
+```markdown
+## UI/UX Evaluation Report
+
+**Scope:** [components/pages reviewed]
+**Date:** {date}
+
+### Accessibility Score
+| Category | Status | Issues |
+|----------|--------|--------|
+| Keyboard navigation | PASS / FAIL | {details} |
+| Screen reader | PASS / FAIL | {details} |
+| Color contrast | PASS / FAIL | {details} |
+| Motion | PASS / FAIL | {details} |
+
+### Responsive Design Score
+| Viewport | Status | Issues |
+|----------|--------|--------|
+| Mobile (320px) | PASS / FAIL | {details} |
+| Tablet (768px) | PASS / FAIL | {details} |
+| Desktop (1024px) | PASS / FAIL | {details} |
+| Large (1440px) | PASS / FAIL | {details} |
+
+### Component Quality
+- **Duplicates found:** {count}
+- **Components needing refactor:** {list}
+- **API quality issues:** {list}
+
+### Visual Consistency
+- **Spacing issues:** {count}
+- **Typography issues:** {count}
+- **Color issues:** {count}
+
+### Interaction Patterns
+| Pattern | Implemented | Missing |
+|---------|------------|---------|
+| Loading states | {components} | {components} |
+| Error states | {components} | {components} |
+| Empty states | {components} | {components} |
+| Success feedback | {components} | {components} |
+
+### Library Recommendations
+[If applicable, comparison tables and recommendations]
+
+### Prioritized Fixes
+1. [Critical accessibility issues first]
+2. [Responsive breakage second]
+3. [Component quality third]
+4. [Visual consistency fourth]
+5. [Interaction pattern gaps fifth]
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Accessibility as afterthought | Check accessibility first -- it affects architecture |
+| Testing only desktop viewport | Test 320px, 768px, 1024px, 1440px at minimum |
+| Ignoring empty/error states | Every data-driven component needs all four states |
+| Choosing libraries by popularity | Evaluate by bundle size, maintenance, accessibility |
+| Hardcoded colors throughout | Use design tokens (CSS custom properties) |
+| Hover-only interactions | Always provide touch/keyboard alternatives |
+| Skipping keyboard testing | Tab through every page. Every interactive element. |
+| Giant components with many props | Prefer composition. Split at 10+ props. |
+
+## Red Flags
+
+**Never:**
+- Ship inaccessible UI (WCAG AA is the minimum)
+- Choose a library without evaluating alternatives
+- Ignore mobile viewports
+- Leave unhandled loading/error/empty states
+- Use hover-only interactions
+- Skip keyboard navigation testing
+
+**Always:**
+- Test keyboard navigation through entire flows
+- Check color contrast ratios for all text
+- Handle all four states (loading, error, empty, success)
+- Use design tokens for colors, spacing, typography
+- Evaluate libraries on concrete criteria (not "popular")
+- Verify via context7 or websearch when uncertain about library features
+- Capture screenshots at each viewport for review
+
+## Codex Integration
+**Modes:** Verify or Takeover | **Protocol:** `protocols/codex.md`
+
+- **Verify:** Claude evaluates UI/UX, Codex reviews for missed issues.
+- **Takeover:** Codex evaluates UI/UX, Claude reviews the report.
+
+**When:** After Claude has produced the UI/UX evaluation report.
+
+**Context to pass:**
+- Path to `.forge/work/{type}/{name}/uiux-report.md`
+- Path to frontend source directories
+- Path to `DESIGN.md` (if available)
+
+**What Codex reviews:**
+- Accessibility issues Claude may have missed (ARIA attributes, focus management, screen reader compatibility)
+- Component consistency gaps across pages/views
+- Responsive breakpoint coverage
+- Design token compliance against DESIGN.md
+
+**Prompt focus:** "Review this UI/UX evaluation for missed accessibility issues, component inconsistencies, and responsive gaps. Focus on what the evaluation MISSED."
+
+**Presentation:** Merge Codex findings into the evaluation report under a "Second Opinion" section.
+
+---
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | Frontend implementation code. `DESIGN.md` at project root (if available — from `plan-design-system`). Component library in use. |
+| **Produces** | `.forge/work/{type}/{name}/uiux-report.md` (evaluation report with prioritized recommendations) |
+| **Feeds into** | `quality-code-review` (apply improvements), `build-tdd` (write tests for accessibility/interaction fixes) |
+| **Updates manifest** | `quality.uiux-review.status: complete, gate-passed: true/false` |
+
+## Integration
+
+**Called by:**
+- `/feature` command (when feature has frontend components)
+- On-demand when user requests UI/UX review
+
+**Pairs with:**
+- `quality-code-review` (UI/UX findings feed into code review fixes)
+- `build-tdd` (accessibility and interaction fixes follow TDD cycle)
+- `quality-test-plan` (E2E tests should cover interaction patterns)
+- `quality-test-execution` (Playwright tests verify accessibility)