gh-hopeoverture-worldbuilding-app-skills-plugins-ui-library-usage-auditor/skills/ui-library-usage-auditor/references/audit-checklist.md

UI Component Audit Checklist

Accessibility Checklist

Semantic HTML

• Use semantic elements (header, nav, main, article, aside, footer)
• Proper heading hierarchy (h1 → h2 → h3, no skips)
• Use button for actions, anchor for navigation
• Use lists (ul, ol) for list content
• Use appropriate input types (email, tel, url, number, etc.)

ARIA Attributes

• All interactive elements have accessible names
• Form inputs have associated labels (explicit or aria-label)
• Images have alt text (or alt="" for decorative)
• Buttons have descriptive text or aria-label
• Links have descriptive text or aria-label
• aria-describedby used for additional context
• aria-required on required form fields
• aria-invalid on fields with errors
• aria-live regions for dynamic content
• Proper role attributes when needed

Keyboard Navigation

• All interactive elements reachable via Tab
• Logical tab order
• Visible focus indicators
• Escape closes modals/dropdowns
• Enter/Space activates buttons
• Arrow keys navigate menus/lists
• No keyboard traps
• Skip links for navigation

Forms

• All inputs have labels
• Required fields indicated visually and programmatically
• Error messages associated with fields
• Success messages announced to screen readers
• Fieldsets and legends for grouped fields
• Autocomplete attributes for common fields
• Clear error recovery instructions

Visual Design

• Sufficient color contrast (4.5:1 for text, 3:1 for UI)
• Information not conveyed by color alone
• Text resizable to 200% without loss of functionality
• No content flashing more than 3 times per second
• Sufficient spacing for touch targets (44x44px min)

shadcn/ui Best Practices

Component Imports

• All UI components imported from @/components/ui
• No custom implementations of existing shadcn components
• Correct component variants used

Form Components

• Using Form component wrapper
• FormField for each field with proper render prop
• FormLabel for all inputs
• FormControl wrapping input elements
• FormDescription for helpful context
• FormMessage for error display
• Proper form validation with zodResolver

Button Usage

• Correct Button component used (not divs/spans)
• Appropriate variants (default, destructive, outline, ghost, link)
• Appropriate sizes (default, sm, lg, icon)
• Loading states with disabled prop
• Icons with proper sizing

Dialog/Modal

• DialogTrigger wraps trigger element
• DialogContent contains modal content
• DialogHeader with DialogTitle
• DialogDescription for context
• DialogFooter for actions
• Proper close button with DialogClose

Card Components

• Card wrapper for card layout
• CardHeader for card top section
• CardTitle for card heading
• CardDescription for card subtitle
• CardContent for main content
• CardFooter for actions/metadata

Table Components

• Table wrapper for tables
• TableHeader with TableRow and TableHead
• TableBody with TableRow and TableCell
• TableCaption for table description
• Proper column alignment

Select/Dropdown

• Select component for dropdowns
• SelectTrigger with SelectValue
• SelectContent with SelectItems
• SelectGroup and SelectLabel for grouping
• Proper placeholder text

Consistency Checks

Spacing

• Consistent spacing scale (gap-2, gap-4, gap-6, gap-8)
• Avoid odd spacing values (gap-3, gap-5)
• Consistent padding on containers
• Consistent margins between sections
• No hardcoded pixel values in spacing

Typography

• Consistent font sizes using Tailwind scale
• Consistent font weights
• Consistent line heights
• Proper heading hierarchy and sizes
• Consistent text colors (foreground, muted-foreground, etc.)

Colors

• Using theme colors from CSS variables
• Consistent color usage (primary, secondary, destructive, etc.)
• No hardcoded color values
• Proper use of foreground/background pairs

Layout

• Consistent container max-widths
• Consistent grid/flex patterns
• Proper responsive breakpoints
• Mobile-first responsive design
• Consistent section spacing

Icons

• Single icon library used consistently
• Consistent icon sizes (h-4 w-4, h-5 w-5, etc.)
• Icons have proper aria-hidden or aria-label
• Consistent icon placement (left/right of text)

Component Patterns

Loading States

• Loading indicators for async operations
• Skeleton loaders for content loading
• Disabled state during operations
• Loading text/icon feedback
• Proper loading state cleanup

Error Handling

• Error messages displayed consistently
• Error states visually distinct
• Error recovery instructions provided
• Errors announced to screen readers
• Form field errors associated with inputs

Empty States

• Meaningful empty state messages
• Call-to-action for empty states
• Icons/illustrations for visual interest
• Consistent empty state styling

Success Feedback

• Success messages/toasts for user actions
• Visual confirmation of changes
• Undo option when appropriate
• Success states don't obstruct content

Component Extraction Opportunities

Repeated Patterns (3+ instances)

• Card layouts with similar structure
• Form field groups
• List item layouts
• Modal/dialog content
• Table row formats
• Navigation items
• Status badges

Complex Inline JSX (10+ lines)

• Complex conditional rendering
• Nested component structures
• Repeated layout patterns
• Form sections

Shared Business Logic

• Similar data transformations
• Common validation logic
• Shared state management
• Repeated API calls

Layout and Responsiveness

Responsive Design

• Mobile-first approach
• Proper breakpoint usage (sm, md, lg, xl, 2xl)
• Content readable on mobile (320px+)
• Touch targets adequate size (44x44px)
• No horizontal scroll on mobile
• Appropriate font sizes on mobile

Flexbox/Grid

• Proper flex/grid usage
• Appropriate flex properties
• Grid column/row definitions
• Gap instead of margin for spacing
• Proper alignment properties

Overflow Handling

• Long text truncated or wrapped appropriately
• Scroll containers have proper styling
• Tables responsive (scroll or stack)
• Modal content scrollable when needed

Z-index Management

• Logical z-index layering
• No arbitrary z-index values
• Proper stacking context
• Modals/dropdowns above other content

Performance Considerations

Component Optimization

• Appropriate use of React.memo
• Event handlers not recreated on every render
• Heavy computations memoized
• Proper key props on lists

Image Optimization

• Next.js Image component used
• Appropriate image sizes
• Lazy loading for below-fold images
• Proper aspect ratios

Bundle Size

• No unused component imports
• Dynamic imports for large components
• Proper tree-shaking

Code Quality

TypeScript

• Proper prop types defined
• No 'any' types
• Proper type inference
• Union types for variants

Props Interface

• Clear prop names
• Appropriate default values
• Optional vs required props clearly defined
• Proper JSDoc comments

Component Structure

• Single responsibility principle
• Appropriate component size (<200 lines)
• Clear component hierarchy
• Proper file organization

State Management

• Appropriate state location
• No prop drilling (use context if needed)
• Proper state updates
• No unnecessary state

Worldbuilding App Specific

Entity Display

• Consistent card layout for entities
• Proper entity type indicators
• Consistent metadata display
• Relationship indicators

Forms

• Consistent field ordering
• Appropriate input types for data
• Proper validation rules
• Consistent submit/cancel patterns

Data Visualization

• Accessible color schemes
• Legend/key provided
• Keyboard navigation support
• Screen reader descriptions

Navigation

• Consistent navigation patterns
• Breadcrumbs for deep navigation
• Clear current location indicator
• Consistent menu structure

Testing Checklist

Manual Testing

• Keyboard navigation tested
• Screen reader tested (NVDA/JAWS/VoiceOver)
• Mobile device tested
• Different browsers tested
• Different viewport sizes tested

Automated Testing

• Unit tests for components
• Integration tests for forms
• Accessibility tests (axe, jest-axe)
• Visual regression tests

Documentation

Component Documentation

• Props documented
• Usage examples provided
• Variants documented
• Edge cases noted

Style Guide

• Component patterns documented
• Color palette defined
• Typography scale defined
• Spacing scale defined
• Accessibility guidelines

Common Issues to Flag

Critical (Must Fix)

• Missing alt text on images
• Form inputs without labels
• Div/span with onClick (should be button)
• Missing keyboard navigation
• Insufficient color contrast
• Broken heading hierarchy

High Priority (Should Fix Soon)

• Inline styles (use Tailwind classes)
• Inconsistent spacing values
• Missing loading states
• Missing error handling
• Inconsistent button variants
• Missing focus indicators

Medium Priority (Should Address)

• Component duplication (3+ instances)
• Complex components (>200 lines)
• Inconsistent empty states
• Missing TypeScript types
• Inconsistent naming conventions

Low Priority (Nice to Have)

• Component extraction opportunities (2 instances)
• Minor styling inconsistencies
• Missing JSDoc comments
• Optimization opportunities

Audit Report Sections

Include in final report:

1. Executive Summary
2. Critical Issues (with file paths and line numbers)
3. Warnings (grouped by category)
4. Suggestions (component extractions, refactoring)
5. Metrics (files scanned, issues found, accessibility score)
6. Best Practices Adherence
7. Recommendations Priority
8. Next Steps