marketplaces/docs/UI-ICON-AUDIT.md

# RC UI Sprint — Icon & Visual Language Audit

Full-application audit and consolidation onto **one icon library** (Lucide, via
`@lucide/angular`) across storefront, Marketplace Builder, and backoffice. Before this
pass the app mixed three icon systems in the same screens: **PrimeIcons** (`pi pi-*`
CSS classes), **dozens of hand-rolled inline `<svg>` blocks** (often the same icon
redrawn from scratch at different sizes/colors), and **bare text glyphs** (`♥`, `⇄`,
`«`, `»`) standing in for icons entirely outside any icon system.

## Foundation

- Added `@lucide/angular` (the maintained package; the unscoped `lucide-angular` is
  deprecated upstream — installed the correct one directly).
- One shared entry point for every icon: `app-icon` (`src/app/shared/ui/icon/`),
  backed by a canonical `name → Lucide icon` registry (`icon-registry.ts`). Default
  size 20px, default stroke-width 2 — the same visual weight everywhere unless a
  call site explicitly overrides it for a specific context (e.g. a 48px empty-state
  illustration vs. a 14px inline chevron).
- `app-icon` is decorative (`aria-hidden`) by default. An `ariaLabel` input exists for
  the rare case an icon carries meaning with no adjacent text; in practice, the label
  almost always belongs on the surrounding interactive element instead.

## Old icon → New icon → Reason

| Area | Old | New | Reason |
|---|---|---|---|
| Admin dashboard | `pi-file-edit`, `pi-heart`, `pi-clock`, `pi-question-circle`, `pi-check-circle`, `pi-save`, `pi-upload`, `pi-book`, `pi-bolt`, `pi-flag`, `pi-megaphone`, `pi-circle` (data-driven via `icon: 'pi-*'` fields) | `edit`, `heart`, `clock`, `help`, `checkCircle`, `save`, `upload`, `book`, `zap`, `flag`, `megaphone`, `circle` | PrimeIcons → Lucide; icon fields retyped `AppIconName` so an unmapped name is a compile error, not a silently blank icon |
| Backoffice shell (sidebar nav + topbar) | `pi-home`, `pi-box`, `pi-tags`, `pi-shopping-cart`, `pi-user`, `pi-credit-card`, `pi-star`, `pi-chart-bar`, `pi-sitemap`, `pi-users`, `pi-cog`, `pi-desktop`, `pi-chart-line`, `pi-sign-out`, `pi-bars`, `pi-search`, `pi-upload`, `pi-building`, `pi-bell` | `home`, `package`, `tags`, `cart`, `user`, `creditCard`, `star`, `chartBar`, `network`, `users`, `settings`, `monitor`, `chartLine`, `logOut`, `menu`, `search`, `upload`, `building`, `bell` | PrimeIcons → Lucide |
| Marketplace Builder (overview, nav, sections, HTML editor toolbar) | `pi-arrow-left/right-circle/up/down`, `pi-check-circle`, `pi-circle`, `pi-circle-fill`, `pi-question-circle`, `pi-desktop`, `pi-shop`, `pi-image`, `pi-th-large`, `pi-box`, `pi-images`, `pi-history`, `pi-megaphone`, `pi-verified`, `pi-code`, `pi-globe`, `pi-sliders-h`, `pi-compass`, `pi-copy`, `pi-trash`, `pi-list`, `pi-link`, `pi-table`, `pi-minus`, `pi-video`, **`pi-bars` reused for drag handles** | `arrowLeft/Right/Up/Down`, `checkCircle`, `circle`, `help`, `monitor`, `store`, `image`, `layoutGrid`, `package`, `images`, `history`, `megaphone`, `verified`, `code`, `globe`, `slidersHorizontal`, `compass`, `copy`, `trash`, `list`, `link`, `table`, `minus`, `video`, **new dedicated `grip` icon** | PrimeIcons → Lucide. `pi-bars` had been reused for both the hamburger menu **and** every drag-to-reorder handle — two unrelated meanings sharing one icon, exactly the "duplicated icon, different meaning" pattern the audit brief calls out. Added `GripVertical` as a distinct drag-handle icon. |
| Header (storefront) | Two hand-drawn magnifying-glass SVGs (`#576463` desktop / `#1e3c38` mobile — same icon, two different hardcoded colors), `♥`/`⇄` **text glyphs** for wishlist/compare, hand-drawn cart SVG, hand-drawn home/catalog mobile-menu icons, 3× duplicated inline chevron SVG | `search` (color via `currentColor`), `heart`, `scale`, `cart`, `home`, `layoutGrid`, `chevronRight` | Consolidates one icon drawn twice with two different colors into one; replaces bare text characters (`♥`/`⇄`) that weren't part of any icon system at all |
| Search page | Same magnifying-glass path hand-duplicated **4 times** (input icon, empty-query, no-results, no-query states) at 3 sizes/3 colors | `search` ×4, color preserved per state via a CSS `color` property on the wrapper | Textbook duplication — one icon, four copy-pasted SVGs |
| Cart | Trash/X/plus/minus inline SVGs, standalone `EmptyCartIconComponent` (an 80px duplicate of the same cart glyph, only used once), chat-bubble "login gate" icon, duplicated close-X icon (2 modals), duplicated refresh icon (QR expired/error) | `trash`, `x`, `plus`, `minus`, `cart` (inline, component deleted), `lock`, `x`, `refresh` | Removed a whole component that existed only to duplicate an icon already available; unified the "login required" icon with telegram-login's identical icon (same concept, was drawn twice) |
| Language/region selectors | 3× duplicated chevron SVG (language dropdown, currency dropdown, region dropdown — identical path, copy-pasted), map-pin SVG, crosshair "locate" SVG, globe SVG | `chevronDown` ×3, `mapPin`, `locate`, `globe` | Same chevron redrawn three times in two components |
| Items carousel, category/subcategories, item-detail | Hand-drawn star (hardcoded `#497671` fill), hand-drawn cart icon (×3 separate redraws across 3 files), no-image/package/grid empty-state illustrations, check/X status icons, thumbs-up/down vote icons, dynamic fill/stroke rating stars | `star` (with new `color` input + `.dx-star--filled` CSS class for the solid/outline toggle), `cart`, `image`/`package`/`layoutGrid`, `check`/`x`, `thumbsUp`/`thumbsDown` | The cart icon alone had been hand-drawn from scratch in 5 different files across this audit (header, items-carousel, subcategories, item-detail, cart) — now one icon, one registry entry |
| Shared `app-select` | Browser-native `<select>` dropdown indicator (renders differently per browser, no relation to the icon system) | `chevronDown` (native indicator hidden via `appearance: none`) | "Selects: replace browser default indicators" — this component is used by nearly every admin form, so the fix applies everywhere at once |
| Shared `app-pagination` | `&laquo;` / `&raquo;` HTML entities | `chevronLeft` / `chevronRight` | "Pagination: use proper chevrons" |
| Every native `<details>`/`<summary>` expander (7 call sites: admin product form ×4, page editor, builder widget panel) | Browser-default disclosure triangle (differs Chrome/Firefox/Safari) | Lucide `ChevronDown` path drawn via one global CSS rule (`details > summary::after`), rotated 180° on `[open]` | Covers all 7 expanders with a single CSS change rather than touching each template — no shared class existed to hang a component-based fix on |

## Consistency improvements

- **One icon family everywhere.** Zero PrimeIcons (`pi-*`) class usages remain
  anywhere in the app (verified by full-repo sweep after each batch). PrimeIcons
  (`primeicons` package) is still installed as a PrimeNG peer dependency but no
  longer used directly for any icon in app code.
- **One default size/stroke-width.** `app-icon` defaults to 20px / stroke-width 2;
  every call site that deviates does so for a legible, deliberate reason (48px empty-
  state illustration, 14px inline chevron), not arbitrary per-instance sizing.
- **Color via `currentColor`, not hardcoded hex.** Every hand-rolled SVG that baked a
  specific hex into its `fill`/`stroke` attribute now inherits color from its
  surrounding CSS `color`, so hover/active/disabled states that already change text
  color also correctly recolor the icon — previously several icons ignored those
  states entirely because their color was hardcoded in the SVG markup.
- **Duplicated icons resolved to one instance:**
  - Magnifying glass: was hand-drawn independently in header (×2), search page (×4).
    Now one `search` icon everywhere.
  - Shopping cart: was hand-drawn independently in header, items-carousel,
    subcategories, item-detail, and cart (via the now-deleted
    `EmptyCartIconComponent`). Now one `cart` icon everywhere.
  - Chevron/dropdown arrow: was hand-drawn independently in language-selector (×2),
    region-selector, and the builder mobile nav (×3). Now one `chevronDown`/
    `chevronRight` everywhere.
  - "Login required" icon (chat-bubble shape): was drawn identically in both
    telegram-login and cart's login gate. Now one `lock` icon in both, matching the
    actual semantic ("authentication required") better than a chat bubble did.
- **Bare text glyphs replaced with real icons.** `♥` and `⇄` in the header were plain
  Unicode characters, not part of any icon system, inconsistent stroke weight and
  optical size versus every other icon on the same toolbar. Now `heart` and `scale`.
- **Corrected a genuine meaning collision**, not just a style one: PrimeIcons'
  `pi-bars` (hamburger lines) was reused in the Marketplace Builder for both the
  mobile menu toggle *and* every drag-to-reorder handle. A user scanning the builder
  UI would see the same glyph mean "open navigation" in the header and "drag this
  row" in a list — added a dedicated `grip` icon (`GripVertical`) so the two concepts
  are now visually distinct.
- **Icon-only buttons audited for accessible names.** Swept every button whose only
  content is an icon; found three relying on `title` alone (not reliably announced by
  screen readers) or nothing at all (region-selector detect-location, carousel
  add-to-cart, subcategories add-to-cart) and added `aria-label` to all three.
- **Decorative icons intentionally kept as custom SVG (not migrated):**
  - The **Telegram brand logo** (cart, telegram-login) — a brand mark, not a generic
    icon; replacing it with a generic Lucide icon would misrepresent the brand.
  - **`layout-switcher`'s grid-pattern preview icons** — these show the actual layout
    being selected (2-column, compact grid, list, etc.) as a literal visual preview,
    not a stand-in for a word. Lucide has no equivalent "this exact grid pattern"
    icon set; redrawing them as generic layout icons would lose the preview function.

## Remaining issues / backlog

- **No sortable table columns exist anywhere in the app** to add sort-direction
  icons to (every admin list table has static, non-interactive `<th>` labels). Adding
  actual column-sort interactivity would be new functionality, out of scope for an
  icon/visual-language pass — flagged here rather than invented.
- **Bundle size**: `app-icon` renders each Lucide icon as its own standalone Angular
  component (the current `@lucide/angular` API — no tree-shakeable "icon font" or
  sprite sheet). The initial bundle grew from the prior build's already-over-budget
  ~585 KB over the 700 KB target to ~760 KB over, mostly from icon components now
  bundled eagerly in the admin shell/dashboard/builder (loaded on every admin route).
  Worth a follow-up pass to lazy-load icon-heavy admin sections if bundle size becomes
  a concrete problem.
- **No `docs/DESIGN.md` exists** in this repo (confirmed across all three RC sprints
  this session). The `impeccable` design-quality hook flagged pre-existing font-size/
  radius/color values against a document that doesn't exist — none of those findings
  were introduced by this pass; they're pre-existing values in files this pass
  touched for unrelated reasons (colors, radii, spacing untouched).
- **PrimeIcons (`primeicons` npm package) is still installed** — it's a transitive
  dependency PrimeNG components may rely on internally (calendar, carousel nav
  arrows rendered by `p-carousel`, etc.), so it wasn't removed from `package.json`.
  No app code imports `pi-*` classes directly anymore, but a future pass could audit
  whether PrimeNG's own internal icon usage (e.g. `p-carousel`'s built-in prev/next
  arrows) should also be re-skinned to match, or left as PrimeNG's own visual
  language since those are framework-owned, not hand-authored.