Initial commit

skills/ui-library-usage-auditor/references/audit-checklist.md

@@ -0,0 +1,360 @@
+# 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