claudetools/.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md

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

## 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

## 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

## 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.