AppIcon Migration Checklist

Goal: Move every existing icon call site in src/ over to the AppIcon API (tone / variant / weight), replacing raw <svg> / direct lucide-react JSX and hard-coded text-* color classes with the unified wrapper from src/shared/ui/icon.tsx.

​

1. Scope & baseline

​

Baseline (captured 2026-04-21)

​

Lucide imports by bucket

grep -rE "from 'lucide-react'" src | wc -l
grep -rE "<AppIcon" src | wc -l
grep -rEo "<AppIcon[^>]*text-(success|warning|destructive|info|muted-foreground|primary|accent|foreground)" src | wc -l

​

2. Migration phases

​

Phase 0 — Tooling guardrails ✅

• ESLint rule northsight/prefer-appicon-tone flags hard-coded tone classes on <AppIcon>.
• Dry-run codemod report at reports/codemod-appicon-tone-dryrun.json.
• Domain-status mapping domainStatusToIconTone() in src/shared/lib/semantic-colors.ts.
• Solid-variant + weight + tone documented in docs/development/ICON_GUIDE.md.

​

Phase 1 — src/shared/ui and src/shared/components

• Inventory: grep -rl "from 'lucide-react'" src/shared/ui src/shared/components
• Convert each file per §4 per-call-site checklist.
• Apply codemod findings from reports/codemod-appicon-tone-dryrun.json (2 hits today).
• Re-run dry-run codemod; confirm byBucket["shared/ui"] === 0 and byBucket["shared/components"] === 0.
• Verification block (see §5).

​

Phase 2 — src/platform/**

• Inventory: grep -rl "from 'lucide-react'" src/platform | wc -l (baseline: 756).
• Skip-list: any file matching */icons/*, *-icons.ts, *StepIcons*, *ModuleIcons*, src/shared/ui/icon.tsx.
• Sub-batches by surface area (suggested 100-file chunks):
  • src/platform/wizards/**
  • src/platform/forms/**
  • src/platform/table-v2/**
  • src/platform/navigation/**
  • src/platform/dashboard/**
  • Remainder.
• Verification block per sub-batch.

​

Phase 3 — src/cores/**

• Inventory: grep -rl "from 'lucide-react'" src/cores | wc -l (baseline: 2,471).
• Land per core in this order (smallest blast radius first): it, lo, gr, fm, fw, ce, rh, cl, pm, fa, hr.
• Skip-list: */icons/*, *-icons.ts, module config maps with LucideIcon typed values.
• Verification block per core.

​

Phase 4 — Domain-status surfaces

• Audit call sites: grep -rE "tone=\"(success|warning|destructive|info)\"" src and confirm any status-driven tones use the helper.
• Replace hand-rolled status === 'approved' ? 'success' : ... ternaries with domainStatusToIconTone(status).
• Surfaces to sweep: StatusBadge, EntityStatusPill, workflow node cards, lead/contact stage chips, billing claim status, encounter status, contract lifecycle.

​

Phase 5 — Solid variant sweep

• EmptyState, ErrorState, SuccessState hero icons → variant="solid".
• Toast leading icons (sonner custom icons) → variant="solid".
• Terminal status badges (paid, approved, completed, denied, cancelled) → variant="solid".
• Inline list-row status (in-flight, draft) stay outline.

​

Phase 6 — Weight sweep

• Dense table chrome (sort carets, row affordances, kebab menus) → weight="thin".
• Primary CTAs (Button leading icons) and section headers → weight="bold".
• Everything else stays default (regular).

​

3. Coverage targets

​

4. Per-call-site checklist

1. Replace JSX:
   // before
   import { CheckCircle2 } from 'lucide-react';
   <CheckCircle2 className="h-4 w-4 text-success" />
   
   // after
   import { AppIcon } from '@/shared/ui/icon';
   import { CheckCircle2 } from 'lucide-react';
   <AppIcon icon={CheckCircle2} size="sm" tone="success" />
   
2. Resolve tone from one of:
   • Explicit semantic intent (success, warning, destructive, info, muted, neutral, primary, accent).
   • domainStatusToIconTone(status) for status-driven tones.
   • Context (e.g. tone="muted" for dense table chrome).
3. Resolve variant: solid for terminal badges / hero glyphs / toast leads, otherwise default outline.
4. Resolve weight: bold for CTAs / section headers, thin for dense table chrome, otherwise default regular.
5. Accessibility: decorative? leave default (aria-hidden="true"). Meaningful (icon-only button)? add decorative={false} + aria-label="...".
6. Drop redundant sizing (h-*, w-*) in favor of size="xs|sm|md|lg".
7. Strip the tone class from className so caller className only carries layout/animation utilities.
8. Re-run lint locally for the changed file:
   npx eslint --fix path/to/changed/file.tsx
   

​

5. Verification steps

​

Per phase / sub-batch

• npm run lint — must pass with zero new northsight/prefer-appicon-tone warnings in scope.
• npm run typecheck — must pass.
• npm run test -- icon — AppIcon unit tests must remain green.
• Re-run the codemod in dry-run mode and confirm byBucket counts for the phase drop to 0:
  node /tmp/codemod-appicon-tone.mjs --dry-run > reports/codemod-appicon-tone-dryrun.json
  jq '.byBucket' reports/codemod-appicon-tone-dryrun.json
  

​

Final acceptance (after Phase 6)

• npm run audit:hardcoded-colors — no new hits on icon className regex.
• npm run validate — full gate green (format + typecheck + lint + build).
• Visual spot check on three pages per core (list, detail, dialog) using the Preview URL.
• Update mem://design/v3-visual-identity-and-component-specs noting the migration is complete.
• Mark this checklist’s phases as ✅.

​

6. Roll-out & rollback

• Roll-out: Land per-bucket in separate PRs (Shared → Platform → Cores → Domain-status → Solid → Weight) so reviewers can verify visually.
• Each PR includes:
  • Before/after dry-run JSON diff for its bucket (paste relevant byBucket slice).
  • Screenshots of 2 representative surfaces (light + dark mode preferred).
  • Lint warning count diff.
• Rollback: Each bucket is a pure refactor; revert the PR. No DB / runtime contract changes.

​

7. Out of scope

• No new icon tokens, no new AppIcon props.
• No changes to icon registries (WIZARD_STEP_ICONS, MODULE_ICONS, core stepIcons).
• No automatic rewrite of raw <svg> (manual review only — too rare to script safely).
• No PHI/PII handling implications; pure UI refactor.
• No changes to test files (tests/**, src/**/__tests__/**).

​

8. References

• docs/development/ICON_GUIDE.md — usage patterns, tone/variant/weight examples.
• docs/development/SEMANTIC_COLORS.md — token catalog and PF-95 theming.
• reports/codemod-appicon-tone-dryrun.json — current codemod findings.
• src/shared/ui/icon.tsx — AppIcon source of truth.
• src/shared/lib/semantic-colors.ts — domainStatusToIconTone() mapping.