joshuashepherd/my-skills/icon-audit

Audit and fix icon anti-patterns across the movemental codebase.

Target: $ARGUMENTS

If no target is provided, scan src/components/ and src/app/(site)/.

Before Starting

1. Read docs/design/DESIGN.md — icon conventions.
2. Grep for icon imports to understand current usage patterns.

Icon Standard

Single library: `lucide-react` — no other icon libraries allowed.

Size Scale

Color

• Icons inherit currentColor by default
• Use semantic tokens via parent: text-primary, text-muted-foreground, etc.
• Never hardcode icon colors (text-blue-600, fill="#000")

Accessibility

• Decorative icons: aria-hidden attribute
• Meaningful icons (no adjacent label): wrap with <span className="sr-only">Label</span>
• Icon-only buttons: must have aria-label

Audit Checklist

1. WRONG LIBRARY (Critical)

Search for non-lucide icon imports:

• @heroicons/react → replace with lucide equivalent
• react-icons → replace with lucide equivalent
• @radix-ui/react-icons → replace with lucide equivalent
• Material Symbols (material-symbols-outlined) → replace with lucide
• Inline SVGs that duplicate a lucide icon → use the lucide component

2. SIZE INCONSISTENCY (High)

• Mixed icon sizes in the same context (e.g., size-4 and size-6 in the same card grid)
• Icons not using the Tailwind size-* utility (using w-5 h-5 instead of size-5)
• Icons larger than size-6 (24px) in non-hero contexts

3. COLOR VIOLATIONS (High)

• Hardcoded colors: text-blue-600, fill="#0053db", stroke="black"
• Should use parent's semantic color or explicit token: text-primary, text-muted-foreground

4. ACCESSIBILITY (Medium)

• Decorative icons missing aria-hidden
• Icon-only buttons without aria-label
• Icons conveying meaning without text alternative

5. FLEX COMPRESSION (Medium)

• Icons inside flex containers without shrink-0 (can get squished)
• Fix: add shrink-0 to icons in flex layouts

Output Format

## Icon Audit Report
 
### Summary
- Files scanned: X
- Icons found: X
- Violations: X
 
### Issues
| # | Severity | File:Line | Issue | Fix |
|---|----------|-----------|-------|-----|
 
### Fixes Applied
- file.tsx — description of change

Rules

• Lucide is the ONLY icon library. No exceptions.
• Icons use size-* utility, not w-*/h-* pairs.
• All decorative icons get aria-hidden.
• Never modify src/components/ui/* — only domain components and pages.