# Icon Audit

> Audits icon usage in a codebase, enforcing lucide-react as the single icon library, correct sizes, semantic colors, and accessibility standards, then applies fixes.

- Skill: `joshuashepherd/icon-audit` (Agent Skill)
- Install (CLI): `npx skillmds add joshuashepherd/icon-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joshuashepherd/icon-audit/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media, UI Design
- Tags: Accessibility, Frontend, Icon Audit, Lucide React, Tailwind Css
- Author: JoshuaShepherd (https://skillmd.com/u/joshuashepherd)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/joshuashepherd/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
| Context | Size | Tailwind |
|---------|------|----------|
| Inline with text | 16px | `size-4` |
| Standard UI | 20px | `size-5` |
| Feature cards | 20-24px | `size-5` or `size-6` |
| Hero features | 24px | `size-6` |

### 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.