audit-svg — read-only audit of where SVG icons & accessible tooltips belong
Map the project's existing icon/tooltip stack, its UI
slots (the insertion points for an icon or tooltip), its clipping traps, and its accessibility gaps into a structured
register — the
Icon & Tooltip Target Register — that becomes the exact input to
. This command is strictly
read-only: it inspects and reports; it writes no application code.
The flow
1. Stack & dependency verification. Detect the icon libraries present (
,
,
,
, or raw inline
), the tooltip infrastructure (
,
, or custom
CSS patterns), and confirm
/
. If none is installed, record the default recommendations:
(or
if Tailwind is primary) plus Radix UI Tooltip.
Done when: the icon, tooltip, and class-merge stack is recorded from the actual files, with defaults noted if a library is absent.
2. UI slot & visual gap analysis. Locate the slots that need enhancement: icon-only action triggers lacking visual hierarchy; text-only buttons that would gain a leading/trailing affordance ("Download CSV", "Create New", "Delete", "Refresh"); dense table headers or form labels needing an
/
icon + explainer tooltip; status badges/pills needing a semantic status icon (
,
,
); and copy-to-clipboard, filter, or settings triggers needing micro-interaction states.
Done when: every candidate slot is listed with its location, its current snippet, and its visual deficiency.
3. Layout & stacking trap detection. For each slot, inspect the parent containers for
/
/
or low
, and decide the
tooltip strategy:
Portal (bypasses clipping — the default for any clipped or table context) vs
CSS (pure Tailwind group/peer, safe only in unconstrained parents). Flag any flex/grid parent where adding an SVG needs an explicit
and a
to prevent text truncation or reflow.
Done when: every slot has a tooltip strategy (Portal or CSS) and a note on the
/gap it needs.
4. Accessibility baseline audit. Flag interactive buttons lacking an
or accessible text; elements lacking
linkage to a helper description; and raw SVGs missing
where they accompany visible text.
Done when: the accessibility prescription is written for every flagged slot.
5. Write the register. Save
at the project root containing the stack summary and the
Icon & Tooltip Target Register — the markdown table below, one row per slot. No code is modified.
Done when: exists with the register filled (one row per slot, every column populated) and ready to hand to
.
Register format (the table inside svg-audit.md)
| Element Ref / Location | Existing Code Snippet | Visual Deficiency & Context | Recommended SVG Icon | Recommended Tooltip Copy | Tooltip Strategy (Portal vs. CSS) | Accessibility Prescription |
|---|
| e.g., Line 42: ExportBtn | <button onClick={onExport}>Export</button>
| Plain text, lacks visual export affordance | (Lucide) leading | "Export dataset as formatted CSV (⌘E)" | CSS (parent unconstrained) | on SVG; keep text |
| e.g., Line 88: TrashAction | <button onClick={handleDelete}><span>Del</span></button>
| Icon-only ambiguous target | (Lucide) | "Permanently delete record" | Portal (inside scrollable table cell) | aria-label="Permanently delete record"
|