commit 76475ed2740b6e36f6ab3856e1eccf5686e53e32
Author: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date:   Sat Nov 29 18:47:03 2025 +0800

    Initial commit

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..949c838
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "ui-library-usage-auditor",
+  "description": "This skill should be used when reviewing shadcn/ui component usage to ensure accessibility, consistency, and proper patterns. Applies when auditing UI code, checking component patterns, reviewing layout structure, identifying component extraction opportunities, or ensuring design system compliance. Trigger terms include audit UI, review components, check shadcn, accessibility audit, component review, UI patterns, design system compliance, layout review, refactor components, extract component.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Hope Overture",
+    "email": "support@worldbuilding-app-skills.dev"
+  },
+  "skills": [
+    "./skills"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9d360c8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# ui-library-usage-auditor
+
+This skill should be used when reviewing shadcn/ui component usage to ensure accessibility, consistency, and proper patterns. Applies when auditing UI code, checking component patterns, reviewing layout structure, identifying component extraction opportunities, or ensuring design system compliance. Trigger terms include audit UI, review components, check shadcn, accessibility audit, component review, UI patterns, design system compliance, layout review, refactor components, extract component.
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..1d973ee
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,49 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:hopeoverture/worldbuilding-app-skills:plugins/ui-library-usage-auditor",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "28c17e127626c95550e54fe5a49e06a1e813f934",
+    "treeHash": "10b450e2c724f28c8ce8a87bc2c8b4ad9f62ea91000b2022a364c38c48f6f658",
+    "generatedAt": "2025-11-28T10:17:34.557187Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "ui-library-usage-auditor",
+    "description": "This skill should be used when reviewing shadcn/ui component usage to ensure accessibility, consistency, and proper patterns. Applies when auditing UI code, checking component patterns, reviewing layout structure, identifying component extraction opportunities, or ensuring design system compliance. Trigger terms include audit UI, review components, check shadcn, accessibility audit, component review, UI patterns, design system compliance, layout review, refactor components, extract component.",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "6380f5bc4ddb3ba9e03435e12a8b5092f3f727fd2c3aafeea2b374e5ef9edd64"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "ff40dfe4c6ec2b1ddb53514e95ed95d77ea4fd389a52c0d8b5783ac9d88e06e1"
+      },
+      {
+        "path": "skills/ui-library-usage-auditor/SKILL.md",
+        "sha256": "0c1948442b4755b309b4ee1f71f25e7b7d848f056970a2dbbd127b452cfeb175"
+      },
+      {
+        "path": "skills/ui-library-usage-auditor/references/audit-checklist.md",
+        "sha256": "aada711b275bb497f231a05e9a703ca2cfd5194256c55d628988a8de4a59f86c"
+      }
+    ],
+    "dirSha256": "10b450e2c724f28c8ce8a87bc2c8b4ad9f62ea91000b2022a364c38c48f6f658"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file
diff --git a/skills/ui-library-usage-auditor/SKILL.md b/skills/ui-library-usage-auditor/SKILL.md
new file mode 100644
index 0000000..22120aa
--- /dev/null
+++ b/skills/ui-library-usage-auditor/SKILL.md
@@ -0,0 +1,599 @@
+---
+name: ui-library-usage-auditor
+description: This skill should be used when reviewing shadcn/ui component usage to ensure accessibility, consistency, and proper patterns. Applies when auditing UI code, checking component patterns, reviewing layout structure, identifying component extraction opportunities, or ensuring design system compliance. Trigger terms include audit UI, review components, check shadcn, accessibility audit, component review, UI patterns, design system compliance, layout review, refactor components, extract component.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# 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:** Missing alt text on images
+  - **Files:** `app/characters/[id]/page.tsx:45`, `components/CharacterCard.tsx:23`
+  - **Fix:** Add descriptive alt attributes to all images
+  - **Priority:** High
+
+- **Issue:** Form inputs without labels
+  - **Files:** `app/create-location/page.tsx:78`
+  - **Fix:** Wrap inputs in FormField with FormLabel
+  - **Priority:** High
+
+### 2. Broken Patterns
+
+- **Issue:** Divs used as buttons with onClick handlers
+  - **Files:** `components/Navigation.tsx:34`, `app/timeline/page.tsx:102`
+  - **Fix:** Replace with Button component
+  - **Priority:** High
+
+## Warnings (Should Fix)
+
+### 1. Inconsistent Patterns
+
+- **Issue:** Mixed spacing scales (gap-2, gap-3, gap-4, space-x-2)
+  - **Occurrences:** 47 instances across 23 files
+  - **Recommendation:** Standardize on gap-{2,4,6,8} scale
+  - **Priority:** Medium
+
+- **Issue:** Inconsistent loading states
+  - **Files:** `app/characters/actions.ts`, `app/locations/actions.ts`
+  - **Recommendation:** Create shared LoadingButton component
+  - **Priority:** Medium
+
+### 2. Component Duplication
+
+- **Issue:** Character card pattern repeated 5 times
+  - **Files:** Multiple files listed
+  - **Recommendation:** Extract CharacterCard component
+  - **Priority:** Medium
+
+## Suggestions (Consider)
+
+### 1. Component Extraction Opportunities
+
+#### EntityCard Component
+**Occurrences:** 8 similar patterns
+**Files:**
+- `app/characters/page.tsx:67-89`
+- `app/locations/page.tsx:54-76`
+- `app/items/page.tsx:43-65`
+
+**Proposed Component:**
+```tsx
+interface EntityCardProps {
+  title: string
+  description: string
+  image?: string
+  tags?: string[]
+  actions?: ReactNode
+}
+
+export function EntityCard({ ... }: EntityCardProps) {
+  // Unified card implementation
+}
+```
+
+#### FormSection Component
+**Occurrences:** 12 similar patterns
+**Recommendation:** Extract reusable form section with heading and fields
+
+### 2. Layout Improvements
+
+- **Issue:** Inconsistent container max-width
+  - **Recommendation:** Use standard container classes
+  - **Files:** Multiple page components
+
+- **Issue:** Missing responsive breakpoints
+  - **Recommendation:** Add mobile-first responsive design
+  - **Files:** `app/timeline/page.tsx`, `components/WorldMap.tsx`
+
+## shadcn/ui Best Practices
+
+### Correct Usage [OK]
+
+- [OK] Forms using FormField pattern (23 components)
+- [OK] Proper Button variants (89 instances)
+- [OK] Consistent Dialog usage (14 components)
+
+### Needs Improvement
+
+- Use Card composition (found 7 instances using raw divs)
+- Use Table component instead of custom tables (3 instances)
+- Replace custom dropdowns with DropdownMenu (4 instances)
+
+## Accessibility Score
+
+**Overall Score:** 72/100
+
+- **Semantic HTML:** 85/100
+- **ARIA Attributes:** 65/100
+- **Keyboard Navigation:** 78/100
+- **Focus Management:** 70/100
+- **Color Contrast:** 88/100
+
+## Recommendations Priority
+
+1. **Immediate (This Week)**
+   - Fix missing alt text on images
+   - Add labels to all form inputs
+   - Replace div buttons with Button component
+
+2. **Short-term (This Month)**
+   - Extract repeated CharacterCard pattern
+   - Standardize loading state patterns
+   - Standardize spacing scale
+
+3. **Long-term (This Quarter)**
+   - Implement comprehensive component library documentation
+   - Create storybook for all shared components
+   - Establish component extraction guidelines
+
+## Metrics
+
+- **Total Files Scanned:** 127
+- **Components Reviewed:** 89
+- **Issues Found:** 34 critical, 67 warnings, 45 suggestions
+- **Average Component Complexity:** Medium
+- **Code Duplication Score:** 23% (target: <15%)
+
+## Next Steps
+
+1. Create GitHub issues for critical accessibility violations
+2. Schedule team review of component extraction opportunities
+3. Update style guide with standardized patterns
+4. Plan refactoring sprint for high-priority warnings
+```
+
+## Automation with Scripts
+
+Use references/audit-checklist.md for comprehensive checklist of items to verify during audit.
+
+## Best Practices for Auditing
+
+1. **Start Broad, Then Focus**: Begin with file scanning, then drill into specific issues
+2. **Prioritize by Impact**: Accessibility issues > Broken patterns > Inconsistencies > Optimizations
+3. **Provide Context**: Include file paths, line numbers, and code snippets
+4. **Suggest Solutions**: Don't just identify problems, provide concrete fixes
+5. **Quantify Issues**: Use metrics to show scope and track improvement
+6. **Group Related Issues**: Cluster similar problems for efficient fixing
+7. **Consider User Impact**: Prioritize issues affecting end-user experience
+8. **Balance Perfection vs Pragmatism**: Focus on high-value improvements
+
+## Common Grep Patterns for Auditing
+
+```bash
+# Find potential accessibility issues
+Grep: pattern="<img(?![^>]*alt=)" output_mode="files_with_matches"
+Grep: pattern="onClick.*<(div|span)" output_mode="content"
+Grep: pattern="<input(?![^>]*aria-label)" output_mode="content"
+
+# Find inconsistent patterns
+Grep: pattern="className=\"[^\"]*gap-[13579]" output_mode="count"
+Grep: pattern="style=" output_mode="files_with_matches"
+
+# Find component usage
+Grep: pattern="from ['\"]@/components/ui" output_mode="content"
+Grep: pattern="<Button" output_mode="count"
+Grep: pattern="<Form" output_mode="count"
+
+# Find potential duplications
+Grep: pattern="<Card>" -A 10 output_mode="content"
+Grep: pattern="className=\".*flex.*items-center.*justify-between" output_mode="count"
+
+# Find error handling patterns
+Grep: pattern="(error|Error)" output_mode="content"
+Grep: pattern="toast\\." output_mode="content"
+
+# Find loading states
+Grep: pattern="(isLoading|loading|isPending)" output_mode="content"
+```
+
+## Worldbuilding App Specific Checks
+
+### Entity Display Patterns
+
+Check for consistent entity card layouts across:
+- Character listings
+- Location browsing
+- Item inventories
+- Faction displays
+- Timeline events
+
+### Form Patterns
+
+Audit form consistency for:
+- Character creation/editing
+- Location forms
+- Item/artifact forms
+- Event timeline forms
+- Relationship management forms
+
+### Data Visualization
+
+Review accessibility of:
+- World maps (keyboard navigation, screen reader support)
+- Timeline visualizations
+- Relationship graphs
+- Stat displays
+- Progress indicators
+
+## Integration with Development Workflow
+
+Use audit findings to:
+1. Create linting rules for common issues
+2. Update team documentation
+3. Create component templates
+4. Establish PR review checklist
+5. Track technical debt
+6. Plan refactoring sprints
+7. Improve component library
+
+## Continuous Improvement
+
+After implementing fixes:
+1. Re-run audit to measure improvement
+2. Document new patterns in style guide
+3. Update component library
+4. Share learnings with team
+5. Adjust audit criteria based on findings
+6. Schedule regular audits (monthly/quarterly)
diff --git a/skills/ui-library-usage-auditor/references/audit-checklist.md b/skills/ui-library-usage-auditor/references/audit-checklist.md
new file mode 100644
index 0000000..71d8886
--- /dev/null
+++ b/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