ui-library-usage-auditor

What this skill does

# UI Library Usage Auditor

Review and audit shadcn/ui component usage across the codebase to ensure accessible, consistent, and maintainable UI patterns. This skill identifies issues, suggests improvements, and recommends component extractions or layout optimizations.

## When to Use This Skill

Apply this skill when:
- Auditing UI components for accessibility compliance
- Reviewing shadcn/ui usage patterns for consistency
- Identifying opportunities for component extraction
- Checking layout structure and responsive design
- Ensuring proper ARIA attributes and semantic HTML
- Finding duplicate component patterns
- Reviewing form implementations
- Checking for proper error handling in UI
- Validating design system adherence

## Audit Categories

### 1. Accessibility Audit

Check for:
- Missing ARIA labels and descriptions
- Improper heading hierarchy
- Missing alt text on images
- Insufficient color contrast
- Missing keyboard navigation support
- Form fields without labels
- Non-semantic HTML usage
- Missing focus indicators
- Improper button vs link usage
- Missing skip links for navigation

### 2. Component Consistency Audit

Check for:
- Inconsistent component variants across pages
- Mixed styling approaches (inline vs className)
- Duplicate component implementations
- Inconsistent spacing patterns
- Mixed icon libraries or icon sizes
- Inconsistent typography usage
- Non-standard button patterns
- Inconsistent error message displays
- Mixed loading state implementations

### 3. Component Extraction Opportunities

Identify:
- Repeated component patterns (3+ instances)
- Complex inline JSX that could be components
- Reusable form field groups
- Common layout patterns
- Shared modal/dialog content
- Repeated table structures
- Common card layouts
- Shared empty states
- Repeated loading skeletons

### 4. Layout and Responsiveness

Review:
- Responsive breakpoint usage
- Container max-width consistency
- Grid and flexbox usage patterns
- Mobile-first responsive design
- Overflow handling
- Scroll behavior
- Fixed positioning issues
- Z-index management

### 5. shadcn/ui Best Practices

Verify:
- Correct component imports from @/components/ui
- Proper use of composition patterns
- Correct variant prop usage
- Proper form component structure
- Correct dialog/modal patterns
- Proper toast/notification usage
- Appropriate dropdown/select usage
- Correct table implementations

## Audit Process

### Step 1: Scan Codebase for Components

Use Glob to identify all component files:

```bash
# Find all component files
Glob: **/*.tsx
Glob: app/**/*.tsx
Glob: components/**/*.tsx
```

### Step 2: Grep for Specific Patterns

Search for common patterns and potential issues:

```bash
# Find form implementations
Grep: pattern="<form" output_mode="files_with_matches"

# Find button usage
Grep: pattern="<Button" output_mode="files_with_matches"

# Find ARIA usage
Grep: pattern="aria-" output_mode="content"

# Find inline styles
Grep: pattern='style=' output_mode="files_with_matches"

# Find accessibility issues
Grep: pattern="<img" output_mode="content"  # Check for alt text
Grep: pattern="onClick.*<div" output_mode="content"  # Div as button antipattern

# Find repeated patterns
Grep: pattern="className=\".*flex.*items-center.*gap" output_mode="count"
```

### Step 3: Read and Analyze Components

Read identified files to perform detailed analysis:

```bash
Read: /path/to/component.tsx
```

Analyze for:
- Component structure and complexity
- Props interface design
- State management approach
- Event handler patterns
- Conditional rendering logic
- Accessibility attributes

### Step 4: Generate Audit Report

Create structured report with findings organized by:
- **Critical Issues**: Accessibility violations, broken patterns
- **Warnings**: Inconsistencies, suboptimal patterns
- **Suggestions**: Refactoring opportunities, extractions
- **Best Practices**: Recommendations for improvement

## Common Issues and Solutions

### Issue 1: Missing Form Labels

**Problem:**
```tsx
<Input
  type="text"
  value={name}
  onChange={(e) => setName(e.target.value)}
/>
```

**Solution:**
```tsx
<FormField
  control={form.control}
  name="name"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Name</FormLabel>
      <FormControl>
        <Input {...field} />
      </FormControl>
      <FormMessage />
    </FormItem>
  )}
/>
```

### Issue 2: Div as Button

**Problem:**
```tsx
<div onClick={handleClick} className="cursor-pointer">
  Click me
</div>
```

**Solution:**
```tsx
<Button onClick={handleClick}>
  Click me
</Button>
```

### Issue 3: Missing Image Alt Text

**Problem:**
```tsx
<img src="/avatar.jpg" className="rounded-full" />
```

**Solution:**
```tsx
<img
  src="/avatar.jpg"
  alt="User profile avatar"
  className="rounded-full"
/>
```

### Issue 4: Inconsistent Spacing

**Problem:**
```tsx
// File 1
<div className="flex gap-4">

// File 2
<div className="flex gap-2">

// File 3
<div className="flex space-x-3">
```

**Solution:**
```tsx
// Standardize spacing scale
<div className="flex gap-4">  // Use consistent gap values (2, 4, 6, 8)
```

### Issue 5: Complex Inline Component

**Problem:**
```tsx
// Repeated in multiple files
<Card>
  <CardHeader>
    <div className="flex items-center justify-between">
      <div className="flex items-center gap-3">
        <Avatar>
          <AvatarImage src={user.avatar} />
          <AvatarFallback>{user.initials}</AvatarFallback>
        </Avatar>
        <div>
          <CardTitle>{user.name}</CardTitle>
          <CardDescription>{user.role}</CardDescription>
        </div>
      </div>
      <DropdownMenu>
        {/* Menu items */}
      </DropdownMenu>
    </div>
  </CardHeader>
</Card>
```

**Solution:**
Extract to reusable component:
```tsx
// components/UserCard.tsx
export function UserCard({ user }: UserCardProps) {
  return (
    <Card>
      <CardHeader>
        <div className="flex items-center justify-between">
          <div className="flex items-center gap-3">
            <Avatar>
              <AvatarImage src={user.avatar} alt={user.name} />
              <AvatarFallback>{user.initials}</AvatarFallback>
            </Avatar>
            <div>
              <CardTitle>{user.name}</CardTitle>
              <CardDescription>{user.role}</CardDescription>
            </div>
          </div>
          <UserMenu user={user} />
        </div>
      </CardHeader>
    </Card>
  )
}
```

### Issue 6: Improper Heading Hierarchy

**Problem:**
```tsx
<div className="page">
  <h1>Dashboard</h1>
  <div className="section">
    <h3>Recent Activity</h3>  {/* Skipped h2 */}
  </div>
</div>
```

**Solution:**
```tsx
<div className="page">
  <h1>Dashboard</h1>
  <div className="section">
    <h2>Recent Activity</h2>  {/* Proper hierarchy */}
  </div>
</div>
```

### Issue 7: Missing Loading States

**Problem:**
```tsx
<Button onClick={handleSubmit}>
  Submit
</Button>
```

**Solution:**
```tsx
<Button onClick={handleSubmit} disabled={isSubmitting}>
  {isSubmitting ? (
    <>
      <Loader2 className="mr-2 h-4 w-4 animate-spin" />
      Submitting...
    </>
  ) : (
    'Submit'
  )}
</Button>
```

### Issue 8: Inconsistent Error Display

**Problem:**
```tsx
// Mixing different error patterns
{error && <p className="text-red-500">{error}</p>}
{error && <span style={{ color: 'red' }}>{error}</span>}
{error && <Alert variant="destructive">{error}</Alert>}
```

**Solution:**
```tsx
// Standardize on Alert component
{error && (
  <Alert variant="destructive">
    <AlertCircle className="h-4 w-4" />
    <AlertDescription>{error}</AlertDescription>
  </Alert>
)}
```

## Audit Report Template

Generate audit reports using this structure:

```markdown
# UI Library Usage Audit Report

**Generated:** [Date]
**Scope:** [Files/directories audited]
**Total Components Reviewed:** [Count]

## Executive Summary

[Brief overview of findings and overall code health]

## Critical Issues (Must Fix)

### 1. Accessibility Violations

- **Issue:** Missi