# Icons

Site and admin icons are [Lucide](https://lucide.dev/icons) through [`@nuxt/icon`](https://github.com/nuxt/icon), rendered as **inline SVG**. They replaced the PrimeIcons icon font (package and CSS removed).

## Why SVG, not an icon font

| Concern    | Inline SVG (Lucide)                                                                                                  | Icon font (PrimeIcons, removed)             |
| ---------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| Responsive | Crisp at any size; sized in `em`, follows text                                                                       | Font hinting blurs at odd sizes             |
| Accessible | `currentColor`, works in forced-colors / high-contrast mode; unaffected by user font overrides (e.g. dyslexia fonts) | Glyphs break or vanish under font overrides |
| Touch      | Icon sits inside a 44px control; never the target on its own                                                         | Same                                        |
| Weight     | Only the icons used are bundled                                                                                      | Whole font downloaded for ~14 icons         |
| Coverage   | ~1,500 icons incl. 3D, audio, video, documents (admin media)                                                         | ~300                                        |

## Using icons

```pug
//- Decorative (default): aria-hidden, the control carries the name
UiButton(label="Copy", icon="copy")
UiIcon(name="download")

//- Icon-only control: name the control, not the icon
UiButton(icon="x", aria-label="Close details")

//- Standalone meaningful icon (rare): label → role="img"
UiIcon(name="triangle-alert", label="Warning")
```

- `UiIcon` (`packages/nuxt-layer-ui/app/components/ui/UiIcon.vue`; the whole kit lives in `packages/nuxt-layer-ui/app/components/ui`) takes a Lucide name (`lucide:` prefix optional).
- `UiButton` / `UiChip` / `UiTag` take the same name through `icon`. `UiButton` is at least 44px tall, and icon-only buttons at least 44px wide.
- Admin (`core/admin`, `packages/web-layer-admin`) gets `UiIcon` from `@tgmc/nuxt-layer-ui`, like web.
- Apps may turn icons off (`tgmc: { icon: false }`); see [UI components § With features off](./ui-components.md#with-features-off).

## One icon set

Owner decision 2026-10-14: Lucide via `UiIcon` is the one icon set. It is passed into PrimeVue icon slots (`UiButton`, `UiTag`, `UiChip`); PrimeVue's built-in `@primevue/icons` stay where the component draws them (close buttons, chevrons). No icon fonts, and no text glyphs (✓ ✕ ◷ ↗ → ←) acting as icons: `tests/icon-glyphs.spec.ts` scans every template. Direction cues use `arrow-left` / `arrow-right`, external links `external-link`, status `check` / `x` / `clock`; each name must be in `clientBundle.icons` in both apps.

## Social links

`AppSocialLinks` (`core/web/app/components/AppSocialLinks.vue`) renders `contact.social` from `content/profile.json` plus the contact email — see [footer-and-social-links.md](./footer-and-social-links.md). Each link's `icon` is a Lucide name and must be in web's `clientBundle.icons` (or `TGMC_BASE_ICONS`).

## Configuration

`@tgmc/nuxt-layer-base` owns the setup (`packages/nuxt-layer-base/src/config/icons.ts`, `tgmcIconConfig()`), so both apps get it by extending the layer:

- `mode: 'svg'` — inline SVG (not CSS masks, which disappear in forced-colors mode).
- `provider: 'server'`, `fallbackToApi: false`, `serverBundle.collections: ['lucide']` — icons come from the app's own server bundle, never the public Iconify API.
- `clientBundle.icons` — **every icon name we use**, pre-bundled for the client. `UiIcon` names are dynamic, so the build scanner can't find them.
  - Names the shared components (the UI kit and the layers) render, or that both apps use, go into `TGMC_BASE_ICONS` in `icons.ts` (for example `loader-circle`, the `UiButton` loading spinner).
  - Each app's `nuxt.config.ts` lists only its own extra names in `icon.clientBundle.icons`; Nuxt appends them to the base list.
  - `core/web/tests/icons.spec.ts` fails if a static `icon="…"` / `UiIcon(name="…")`, a `content/profile.json` social icon or an admin media-kind icon isn't in the base list plus that app's list, or if an app list repeats a base name.
