# Frontend UI Validation Checklist

**Purpose:** Use this checklist when frontend-design skill is invoked to validate UI changes.

**Last Updated:** 2026-01-17

---

## When to Use This Checklist

**MANDATORY:** After ANY code change that affects UI elements:
- Creating new UI components
- Modifying existing styles or markup
- Adding features to frontend code
- Refactoring frontend components
- Fixing UI bugs

---

## Validation Categories

### 1. Visual Appearance

**Layout & Structure:**
- [ ] Elements render in correct positions
- [ ] Grid/flexbox layouts work as expected
- [ ] Z-index stacking is correct
- [ ] No unexpected overlaps or gaps
- [ ] Aspect ratios are maintained
- [ ] Images load and display correctly

**Typography:**
- [ ] Fonts load and display correctly
- [ ] Font sizes are appropriate (readability)
- [ ] Line height provides good readability
- [ ] Text alignment is intentional
- [ ] No text overflow or truncation issues
- [ ] Headings have proper hierarchy

**Colors & Contrast:**
- [ ] Colors match design specifications
- [ ] Sufficient contrast for readability (WCAG AA minimum)
- [ ] Color themes (light/dark) work correctly
- [ ] CSS variables applied consistently
- [ ] Gradients render smoothly
- [ ] Transparency/opacity levels correct

**Spacing & Rhythm:**
- [ ] Padding is consistent and intentional
- [ ] Margins create proper visual separation
- [ ] Whitespace enhances readability
- [ ] Vertical rhythm is maintained
- [ ] No cramped or overly sparse areas
- [ ] Spacing scales appropriately

**Visual Effects:**
- [ ] Shadows render correctly (no performance issues)
- [ ] Border-radius values are consistent
- [ ] Background images/patterns display properly
- [ ] Filters (blur, grayscale, etc.) work as expected
- [ ] Decorative elements enhance, don't distract
- [ ] No visual glitches or rendering artifacts

---

### 2. Interactive Behavior

**Click/Tap Interactions:**
- [ ] Buttons respond to clicks
- [ ] Links navigate correctly
- [ ] Forms submit properly
- [ ] Checkboxes/radios toggle
- [ ] Dropdowns open/close
- [ ] Click targets are appropriately sized (minimum 44x44px)

**Hover States:**
- [ ] Hover effects trigger on desktop
- [ ] Cursor changes appropriately (pointer, text, etc.)
- [ ] Visual feedback is clear
- [ ] Transitions are smooth
- [ ] No flickering or jank
- [ ] Tooltips appear when expected

**Focus States:**
- [ ] Focus indicators visible (keyboard navigation)
- [ ] Focus order is logical
- [ ] Focus trap works in modals/dialogs
- [ ] Skip links function correctly
- [ ] Focus doesn't get lost
- [ ] Custom focus styles meet contrast requirements

**Active States:**
- [ ] Pressed/active states provide feedback
- [ ] Buttons show active state during click
- [ ] Form inputs show active state when selected
- [ ] Loading states appear during async operations

**Disabled States:**
- [ ] Disabled elements are visually distinct
- [ ] Disabled elements don't respond to interaction
- [ ] Cursor indicates disabled state
- [ ] Tooltips explain why disabled (if applicable)

---

### 3. Responsive Behavior

**Breakpoints:**
- [ ] Desktop (1920px+) layout works
- [ ] Laptop (1366px-1919px) layout works
- [ ] Tablet landscape (1024px-1365px) layout works
- [ ] Tablet portrait (768px-1023px) layout works
- [ ] Mobile landscape (568px-767px) layout works
- [ ] Mobile portrait (320px-567px) layout works

**Adaptive Layout:**
- [ ] Content reflows appropriately
- [ ] No horizontal scrolling (unless intentional)
- [ ] Touch targets are finger-sized on mobile (44x44px min)
- [ ] Navigation adapts (hamburger menu, etc.)
- [ ] Images scale/crop appropriately
- [ ] Text remains readable at all sizes

**Responsive Typography:**
- [ ] Font sizes scale appropriately
- [ ] Line length stays readable (45-75 characters)
- [ ] Headings scale proportionally
- [ ] No text overflow at any breakpoint

**Mobile-Specific:**
- [ ] Touch gestures work (swipe, pinch, etc.)
- [ ] No hover-dependent interactions
- [ ] Virtual keyboard doesn't obscure inputs
- [ ] Mobile browser chrome accounted for
- [ ] Fixed elements don't interfere with scrolling

---

### 4. Animations & Transitions

**Animation Quality:**
- [ ] Animations run smoothly (60fps)
- [ ] No janky or stuttering motion
- [ ] Timing feels natural (not too slow/fast)
- [ ] Easing curves are appropriate
- [ ] Animation-delay creates stagger effect (if intended)

**Performance:**
- [ ] Animations use transform/opacity (GPU-accelerated)
- [ ] No layout thrashing
- [ ] Will-change used appropriately (if needed)
- [ ] Animations don't block interactions
- [ ] Reduce motion preference respected

**Transition States:**
- [ ] Enter animations work
- [ ] Exit animations work
- [ ] State transitions are smooth
- [ ] Loading spinners/skeletons appear
- [ ] No flash of unstyled content (FOUC)

**Scroll Animations:**
- [ ] Scroll-triggered animations fire correctly
- [ ] Parallax effects are subtle, not nauseating
- [ ] Sticky elements stick at right position
- [ ] Scroll progress indicators update
- [ ] Smooth scroll behavior works

---

### 5. Accessibility

**Keyboard Navigation:**
- [ ] All interactive elements are keyboard accessible
- [ ] Tab order is logical
- [ ] Enter/Space activate buttons/links
- [ ] Escape closes modals/dropdowns
- [ ] Arrow keys navigate menus/lists (if applicable)
- [ ] No keyboard traps

**Screen Reader Support:**
- [ ] Semantic HTML used (header, nav, main, article, etc.)
- [ ] ARIA labels on icons/buttons without text
- [ ] ARIA live regions for dynamic content
- [ ] Form inputs have associated labels
- [ ] Error messages are announced
- [ ] Skip links present

**Visual Accessibility:**
- [ ] Color contrast meets WCAG AA (4.5:1 text, 3:1 UI)
- [ ] Color isn't the only indicator (use icons/text too)
- [ ] Focus indicators are highly visible
- [ ] Text can be resized to 200% without breaking layout
- [ ] No content hidden by fixed elements

**Alternative Content:**
- [ ] Images have descriptive alt text
- [ ] Decorative images have empty alt=""
- [ ] Icons have labels or tooltips
- [ ] Videos have captions/transcripts
- [ ] Complex graphics have text alternatives

---

### 6. Performance

**Load Performance:**
- [ ] Critical CSS inlined (if applicable)
- [ ] Fonts load efficiently (font-display: swap)
- [ ] Images lazy-loaded (below fold)
- [ ] No render-blocking resources
- [ ] First contentful paint is fast (<2s)

**Runtime Performance:**
- [ ] No layout shifts (CLS near 0)
- [ ] Smooth scrolling (no jank)
- [ ] Animations run at 60fps
- [ ] No memory leaks
- [ ] Event handlers don't block main thread

**Resource Optimization:**
- [ ] Images optimized (WebP, compression)
- [ ] CSS is minified (in production)
- [ ] JavaScript is minified (in production)
- [ ] Unused CSS removed
- [ ] Critical resources preloaded

---

### 7. Cross-Browser Compatibility

**Modern Browsers:**
- [ ] Chrome/Edge (latest)
- [ ] Firefox (latest)
- [ ] Safari (latest)
- [ ] Mobile Safari (iOS)
- [ ] Chrome Mobile (Android)

**Fallbacks:**
- [ ] Graceful degradation for older browsers
- [ ] Feature detection (not browser sniffing)
- [ ] Polyfills loaded if needed
- [ ] CSS fallbacks for modern features (grid, flexbox)
- [ ] No JavaScript errors in console

---

### 8. Content & Copy

**Text Quality:**
- [ ] No typos or grammatical errors
- [ ] Placeholder text replaced with real content
- [ ] Proper capitalization (title case, sentence case)
- [ ] Consistent voice and tone
- [ ] Microcopy is helpful and clear

**Internationalization:**
- [ ] Text doesn't break layout in longer languages
- [ ] RTL support if needed
- [ ] Date/number formatting appropriate
- [ ] No hardcoded strings (use i18n keys)

---

## Validation Workflow

### Quick Validation (Simple Changes)

For minor changes like color updates or spacing tweaks:

1. Visual check at 1-2 breakpoints
2. Verify hover/focus states
3. Quick accessibility scan
4. Report: [OK] or [WARNING]

**Time:** 1-2 minutes

### Standard Validation (Component Changes)

For component modifications or feature additions:

1. Visual check at all breakpoints
2. Test all interactive states
3. Keyboard navigation test
4. Basic performance check
5. Report: [OK], [WARNING], or [ERROR]

**Time:** 3-5 minutes

### Comprehensive Validation (New Features)

For new components or major refactors:

1. Complete visual review (all categories above)
2. Full interaction testing
3. Cross-browser testing
4. Accessibility audit
5. Performance profiling
6. Report: Detailed findings with fixes

**Time:** 10-15 minutes

---

## Validation Report Format

### Success Report

```markdown
## UI Validation: PASSED

**Component:** [Component name]
**Changes:** [Brief description]

**Validation Results:**
- [OK] Visual appearance correct
- [OK] Interactive behavior working
- [OK] Responsive at all breakpoints
- [OK] Accessibility requirements met

**Notes:** [Any observations or recommendations]
```

### Warning Report

```markdown
## UI Validation: WARNINGS

**Component:** [Component name]
**Changes:** [Brief description]

**Validation Results:**
- [OK] Visual appearance correct
- [WARNING] Minor hover state issue detected
- [OK] Responsive at all breakpoints
- [OK] Accessibility requirements met

**Issues Found:**
1. **Minor: Hover state transition**
   - **Problem:** Transition is too slow (500ms)
   - **Fix:** Reduce to 200ms for better UX
   - **Fixed:** Yes

**Status:** Issues resolved, ready to proceed
```

### Error Report

```markdown
## UI Validation: ERRORS

**Component:** [Component name]
**Changes:** [Brief description]

**Validation Results:**
- [OK] Visual appearance correct
- [ERROR] Interactive behavior broken
- [WARNING] Responsive issues on mobile
- [ERROR] Accessibility violations

**Critical Issues:**
1. **CRITICAL: Button click handler not working**
   - **Problem:** Event listener not attached
   - **Impact:** Form cannot be submitted
   - **Fix Required:** Add onClick handler

2. **CRITICAL: Missing keyboard accessibility**
   - **Problem:** Modal cannot be closed with Escape
   - **Impact:** Keyboard users trapped
   - **Fix Required:** Add keydown listener

**Status:** BLOCKED - fixes required before proceeding
```

---

## Common Issues to Watch For

### Layout Issues
- Flexbox/grid container missing
- Z-index conflicts
- Overflow hidden cutting off content
- Fixed positioning causing mobile issues

### Typography Issues
- Font not loading (fallback showing)
- Line-height too tight/loose
- Text overflow not handled
- Inconsistent font weights

### Color Issues
- Insufficient contrast
- Theme not applied consistently
- CSS variable not defined
- Color only indicator (accessibility)

### Interaction Issues
- Event handler not attached
- Hover state persisting on mobile
- Focus outline removed without replacement
- Click target too small

### Responsive Issues
- Breakpoint gaps (768.5px edge cases)
- Images not scaling
- Text wrapping awkwardly
- Mobile menu not working

### Animation Issues
- Animating width/height (use transform)
- No will-change on expensive animations
- Animations running on page load (jarring)
- Reduce motion not respected

### Accessibility Issues
- Missing alt text
- No keyboard focus indicators
- Color contrast too low
- ARIA labels missing

---

## Decision Matrix: Pass, Warn, or Block

### PASS - Approve Changes
- All critical validations passed
- No major issues detected
- Minor observations noted but don't block
- Ready for code review/testing

### WARN - Approve with Notes
- Minor issues detected
- Issues fixed during validation
- Recommendations for improvement
- Can proceed but note improvements

### BLOCK - Require Fixes
- Critical functionality broken
- Accessibility violations (WCAG A/AA)
- Visual appearance significantly wrong
- Responsive layout broken
- Performance severely degraded

---

## Integration with Other Tools

**Works alongside:**
- Code Review Agent (checks code quality)
- Testing Agent (runs automated tests)
- Browser DevTools (performance profiling)
- Lighthouse (accessibility/performance audits)
- Screen readers (NVDA, JAWS, VoiceOver)

**Reports to:**
- Main Claude (coordination)
- Code Review Agent (combined approval)
- User (final validation)

---

**Remember:** This skill is invoked AUTOMATICALLY for ANY UI change. Quick validations keep velocity high while ensuring quality.