@mrmeg/expo-ui 0.28.0 → 0.29.1

package/CHANGELOG.md

@@ -5,6 +5,86 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.29.1]
+
+### Changed
+
+- The shipped Lucide snapshot (`dist/icons/lucide.json`) moves from Lucide
+  1.55.0 to 1.57.0: 13 new glyphs (among them `cpu-ai`, `folder-user`,
+  `message-circle-text`, `server-nas`, `users-collaboration`), no removals or
+  alias changes. After upgrading, run `bunx expo-ui-icons` and
+  `bunx expo-ui-icons tabs`.
+
+## [0.29.0]
+
+### Added
+
+- **`ThemeSelector`** (`@mrmeg/expo-ui/components`): a compact System / Light /
+  Dark switch bound to `useThemeStore`, so a settings screen needs one row for
+  appearance instead of three radio rows. Icon-only by default (about 116 pt,
+  sized for `ItemActions`); `showLabels` stretches it with text. Translated
+  `labels` name each segment for screen readers. Drawn in RN on every platform,
+  with a 44 pt vertical hit area and a selection haptic; `value` /
+  `onValueChange` make it controlled.
+- **`registerIcons(icons)`** and **`isIconName(value)`**
+  (`@mrmeg/expo-ui/components/Icon`): register an app's glyphs once at module
+  scope in the root layout, and narrow a runtime string to `IconName`. The
+  `IconRegistry` interface they back is what an app's generated module
+  augments. Also exported: the `IconGlyph`, `IconTag`, `IconComponent`,
+  `IconAccessibilityProps`, and `NamedIconProps` types, and a `testID` prop on
+  `Icon` (a named icon defaults to `icon-<name>` in development).
+- **`expo-ui-icons` bin**: compiles `client/icons.json` against the shipped
+  Lucide snapshot (`dist/icons/lucide.json`, Lucide 1.55.0, ISC license in
+  `dist/icons/LICENSE.lucide`) into `client/icons.generated.ts` (`appIcons` plus
+  the `IconRegistry` augmentation). `init` seeds the manifest from the app's
+  `name="…"` / `icon="…"` literals, `add` inserts names (an alias becomes its
+  canonical name), `--check` fails on a stale module, and `tabs` rasterizes the
+  `tabIcons` subset to 1x/2x/3x template PNGs for a native tab bar, with a
+  hash manifest so `tabs --check` needs no rasterizer.
+- `design-system.json` `icons` gains `aliases` (Lucide's renamed names →
+  canonical) and `lucide` (the snapshot version).
+- Exact `./components/iconTypes` (the glyph types) and
+  `./components/iconBuiltins.generated` (`BUILTIN_ICONS`) subpaths. `Icon`
+  re-exports everything an app needs; these exist so every `.ts` module the
+  `./components/*` pattern exposes also resolves through the repo's source
+  condition.
+
+### Changed
+
+- **`Icon` renders package-owned glyph data instead of `lucide-react-native`.**
+  Glyphs are plain `[tag, attrs]` data drawn by the package: an inline `<svg>`
+  on web and in server HTML (stroked `currentColor`, so theme changes recolor
+  through CSS), `react-native-svg` on native with Lucide's own geometry and
+  stroke handling. The web bundle no longer carries `react-native-svg` or the
+  Lucide runtime, and Jest needs no icon mocks.
+- **`IconName` is the 19 builtins plus app-registered names.** The package
+  registers only what its components draw (`check`, `x`, the chevrons, the
+  status and theme-mode glyphs, `eye`/`eye-off`, `user`, …); every other name
+  comes from the app's `client/icons.json`. `<Icon name>` call sites do not
+  change once the names are registered.
+- `ToggleIcon` and `ToggleGroupIcon` take `IconProps` (`name` or `component`,
+  plus `size`, `style`, `accessibilityLabel`, …) like `Button.Icon`: color from
+  the control's text color and decorative by default.
+- `Icon`'s `component` prop is typed `IconComponent` (`size`, `color`, `style`,
+  accessibility props); any component taking `size` and `color` still fits.
+
+Upgrading from 0.28: run `bunx expo-ui-icons init` once, typecheck, and
+`bunx expo-ui-icons add` each name it reports (names built at runtime are not
+found by the scan); add `registerIcons(appIcons)` at module scope in the root
+layout (`import { appIcons } from "@/client/icons.generated"`); register
+`appIcons` in the Jest setup too; delete the Lucide Jest module mapping or
+`transformIgnorePatterns` entry and any `iconRegistry.generated` mock; and
+remove `lucide-react-native` from `package.json` once nothing imports it.
+Optionally list `tabIcons` and run `bunx expo-ui-icons tabs` to replace
+`@expo/vector-icons` tab glyphs with template PNGs. Add
+`bunx expo-ui-icons --check` to CI.
+
+### Removed
+
+- The `lucide-react-native` peer dependency.
+- The `./components/iconRegistry.generated` export (`ICONS`); glyphs are
+  registered data now, and `IconName` comes from `@mrmeg/expo-ui/components/Icon`.
+
 ## [0.28.0]
 
 ### Added

package/LLM_USAGE.md

@@ -191,7 +191,7 @@ configureExpoUiI18n((key, options) => i18n.t(key, options));
 - Web SSR paints the visitor's scheme: wrap the root layout in `<InitialSchemeProvider scheme>` (`@mrmeg/expo-ui/state`) with the `"light"`/`"dark"` value read from a cookie on both server and client (template: `shared/ssrColorScheme.ts`, written by `+html.tsx` and `client/features/app/colorSchemeCookie.ts`); `useTheme()` uses it until `hasLoadedTheme`. Never read `localStorage` for the first render.
 - A Radix-backed component (`Tabs`, `Accordion`, `Collapsible`, `Select`, `DropdownMenu`, `Popover`) on a server-rendered web route logs a `useId` hydration mismatch (Expo Router hydrates `#root`, the server rendered `+html.tsx`). Wrap that subtree — not the page — in `<Hydrated fallback={…}>` (`@mrmeg/expo-ui/components`) with a fallback that holds its height; never branch on `typeof window`. Content that must be in the server HTML stays outside the gate.
 - Web console hygiene: animate with `useNativeDriver: shouldUseNativeDriver` (`@mrmeg/expo-ui/lib`), never `true`; set `pointerEvents` in `style`, never as a prop (react-native-web deprecates the prop, and its lazy warning module has overflowed the first SSR render of deep routes). `AnimatedView` folds a `pointerEvents` prop into style for you.
-- Haptics are one setting: `<UIProvider haptics="off" | "selection" | "all">` (default `"selection"`: Switch/Checkbox/Toggle/ToggleGroup/SegmentedControl tap on change; `"all"` adds a light tap on press for Button, pressable Card and Item). Do not call `expo-haptics` per control; force one Button with `haptic`. Pressed/disabled looks come from `interaction.pressedOpacity` / `interaction.disabledOpacity` in `@mrmeg/expo-ui/constants`.
+- Haptics are one setting: `<UIProvider haptics="off" | "selection" | "all">` (default `"selection"`: Switch/Checkbox/Toggle/ToggleGroup/SegmentedControl/ThemeSelector tap on change; `"all"` adds a light tap on press for Button, pressable Card and Item). Do not call `expo-haptics` per control; force one Button with `haptic`. Pressed/disabled looks come from `interaction.pressedOpacity` / `interaction.disabledOpacity` in `@mrmeg/expo-ui/constants`.
 - Bottom toasts must clear the tab bar: the layout that owns a bar calls `useNotificationOffset({ bottom })` (`@mrmeg/expo-ui/hooks`) with the bar's distance from the window edge, inset included — `useBottomTabBarHeight()` for a JS `<Tabs>` layout, platform bar height + `useWindowInsets().bottom` for `NativeTabs` — and `null` while the bar is hidden. Never position a toast yourself.
 - Use `notify` plus a root `UIProvider` for transient global feedback. (`globalUIStore` stays available for reactive subscriptions and tests. In a component, read it with zustand's `useStore(globalUIStore, selector)`, never `globalUIStore()`: the React Compiler only treats `use*` calls as hooks, caches the bare call, and the next render crashes with React error #311.)
 - Keep app monitoring, auth, API, and domain behavior outside this package.
@@ -261,6 +261,11 @@ tokens and keeps a 44px hit area on native while rendering 40px on web.
 `spacing.cardPadding` (16) is the inner padding of `Card` and `StatCard` tiles,
 not a layout inset. See Screen Layout below.
 
+A settings screen picks the theme with one row: `ThemeSelector` in the row's
+`ItemActions`, with translated `labels`. It reads and writes `useThemeStore`, so
+it needs no state of its own. Describe the resolved scheme under the title only
+while the preference is `system`.
+
 When the saved theme preference is `system`, the package theme store owns the OS
 color-scheme subscription, including web `prefers-color-scheme`. Do not add
 app-local Appearance or `matchMedia` listeners. `THEME_STORAGE_KEY` (from
@@ -393,7 +398,7 @@ Check this before creating a new app-local primitive. All components come from
 | `DropdownMenu` | Menus and command lists | Homemade popover menus |
 | `EmptyState` | No-data or recoverable error regions | One-off empty placeholders |
 | `ErrorBoundary` | React render error fallback | Unhandled screen crashes |
-| `Icon` | Lucide or custom icons with theme tokens | Raw vector icons with hardcoded colors |
+| `Icon` | Registered Lucide glyphs or custom art with theme tokens | Raw vector icons with hardcoded colors |
 | `InputOTP` | Verification code entry | Several manually managed text inputs |
 | `Item`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions` | List / settings rows with density tokens | Hand-rolled row `View`s |
 | `ItemGroup` | A titled group of full-width `Item` rows with inset hairlines and an optional footer | Bordered or shadowed boxes around rows, a `Card` per row, hand-drawn dividers |
@@ -417,6 +422,7 @@ Check this before creating a new app-local primitive. All components come from
 | `Switch` | Binary settings | Custom toggle switches |
 | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | In-page tabbed views | Custom segmented/tab controls |
 | `TextInput` | Text entry with label, helper/error text, clear, password reveal | Raw `TextInput` plus repeated label/error code |
+| `ThemeSelector` | System / Light / Dark switch wired to the theme store; icon-only fits an `ItemActions` slot, `showLabels` stretches | Three radio rows or a hand-rolled theme picker |
 | `Toggle`, `ToggleIcon` | Pressed/unpressed control; an `iconOnly` toggle needs `accessibilityLabel` (dev warns once) | Button with local selected styling |
 | `ToggleGroup`, `ToggleGroupItem`, `ToggleGroupIcon` | Single or multi toggle groups | Custom segmented controls |
 | `Tooltip` | Short hover/focus help | Persistent helper text or custom hover cards |
@@ -446,7 +452,7 @@ already scope label selectability; ordinary iOS/web text stays selectable.
 - A plain `View` whose `opacity`/`pointerEvents` follows state must be `collapsable={false}` on Android (Fabric re-parents its children on the flip; a flip racing a navigation pop crashes). Package surfaces are pinned; spread `stateSurfaceProps()` from `@mrmeg/expo-ui/lib` on app-owned ones. `Pressable` already pins itself.
 - `TextInput` `onBlur` fires only after a real focus on Android (the native field's first-composition blur is dropped in the package); validate on blur directly and do not add a touched-fields guard in app code.
 - `Drawer.Header` takes `icon`, `title`, and `action` slots for a compact app-brand row; put `Drawer.ToggleCollapse` in `action` for a trailing rail control. `Drawer.Content` owns safe-area top/bottom padding — do not duplicate it in children.
-- `Icon` and `Button.Icon` take `name` (a kebab-case name from the package registry, typed `IconName`) or `component` (any Lucide import such as `import House from "lucide-react-native/icons/house"`, or another SVG component taking `size` and `color`). Both are sized, colored with theme tokens, and hidden from assistive tech unless `accessibilityLabel` names a standalone icon (`decorative` only silences a labelled one); `Button.Icon` inherits the button's label color and is decorative by default. Use `component` for icons outside the registry instead of rendering raw Lucide components.
+- `Icon` and `Button.Icon` take `name` (a kebab-case Lucide name typed `IconName`: the package builtins plus the names the app lists in `client/icons.json`, compiled with `bunx expo-ui-icons` and registered once with `registerIcons(appIcons)` at module scope in the root layout) or `component` (an `IconComponent` taking `size` and `color`, for art that is not a Lucide icon). Both are sized, colored with theme tokens, and hidden from assistive tech unless `accessibilityLabel` names a standalone icon (`decorative` only silences a labelled one); `Button.Icon` inherits the button's label color and is decorative by default. A missing name is a type error: run `bunx expo-ui-icons add <name>` (it maps an alias such as `home` to `house`) rather than importing an icon library. Check a name that arrives at runtime with `isIconName`.
 
 ## Minimal Examples
 
@@ -557,7 +563,7 @@ import { Drawer, Icon } from "@mrmeg/expo-ui/components";
   title="Acme"
   action={
     <Drawer.ToggleCollapse>
-      <Icon name="sidebar" decorative />
+      <Icon name="panel-left" decorative />
     </Drawer.ToggleCollapse>
   }
 />

package/README.md

@@ -32,9 +32,10 @@ Web 0.21. Install these peers at the versions your Expo SDK recommends: `expo`,
 `react-native-web`, `react-native-gesture-handler`,
 `react-native-keyboard-controller`, `react-native-safe-area-context`,
 `react-native-screens`, `@react-native-async-storage/async-storage`, `zustand`.
-`Icon` renders [Lucide](https://lucide.dev/icons) SVGs, so also install its two
-peers: `npx expo install react-native-svg` (a native module, pinned by your
-SDK) and `bun add lucide-react-native` (`>=1.46 <2`).
+`Icon` draws SVG, so also install `react-native-svg` (a native module, pinned
+by your SDK): `npx expo install react-native-svg`. The icons themselves are
+[Lucide](https://lucide.dev/icons) glyph data the package ships and renders;
+no icon library is a peer (see [Icons](#icons)).
 
 `@rn-primitives/*` and `@expo-google-fonts/inter` are package dependencies, not
 peers. Animations use React Native `Animated`. `BottomSheet`, `Slider`, and
@@ -481,7 +482,7 @@ setHaptics("all");
 | `haptics` | Fires on |
 |---|---|
 | `"off"` | nothing |
-| `"selection"` (default) | state changes: Switch, Checkbox, Toggle, ToggleGroup, SegmentedControl |
+| `"selection"` (default) | state changes: Switch, Checkbox, Toggle, ToggleGroup, SegmentedControl, ThemeSelector |
 | `"all"` | selection plus a light tap on press-in for Button, pressable Card and Item, and `useScalePress` consumers |
 
 Two ways to disable a `Button`. `disabled` swallows presses, skips the scale
@@ -567,7 +568,7 @@ monospace.
 weight is imported from its own `@expo-google-fonts/inter/<weight>` subpath, so
 a native bundle carries those four files and no other Inter face, and a web
 bundle carries no Inter file at all. Icons
-are SVG (`lucide-react-native`), so there is no icon font to load on any
+are SVG drawn from glyph data, so there is no icon font to load on any
 platform. On web
 it injects one Google Fonts Inter stylesheet (all four weights) after hydration
 unless the app already added it; web weight differentiation then comes from a
@@ -727,7 +728,7 @@ building a new primitive.
 | `DropdownMenu` | Menus and command lists | Row actions, account menu, sort menu, checkbox/radio groups |
 | `EmptyState` | No-data or recoverable error regions | Empty inbox, no results, failed list load |
 | `ErrorBoundary` | React render error fallback | Route-level and feature-level fallbacks |
-| `Icon` | Lucide or custom icons on theme tokens | Button accessories, menu icons, status glyphs |
+| `Icon` | Registered Lucide glyphs or custom art on theme tokens | Button accessories, menu icons, status glyphs |
 | `InputOTP` | Verification code entry | Email/SMS codes, MFA, invite codes |
 | `Item` | List and settings rows on the density tokens | Settings lists, inbox rows, pickers, detail rows |
 | `ItemGroup` | Flat grouped list: title, full-width `Item` rows with inset hairlines, footer | Settings sections, profile details, activity feeds |
@@ -751,61 +752,113 @@ building a new primitive.
 | `Switch` | Binary settings | Notification, privacy, and feature toggles |
 | `Tabs` | In-page tabbed views | Profile sections, report views, settings categories |
 | `TextInput` | Text entry with label, helper/error text, clear button, password reveal, numeric filtering, left/right elements | Email/password, search, multiline notes |
+| `ThemeSelector` | Compact System / Light / Dark switch bound to the theme store (icon-only, or `showLabels`) | The appearance row of a settings screen |
 | `Toggle` | Pressed/unpressed control | Favorite, mute, bold/italic, view mode |
 | `ToggleGroup` | Single or multi toggle groups | Alignment, formatting toolbar, filter chips |
 | `Tooltip` | Short hover/focus help | Icon button labels, field hints, disabled-action reasons |
 
 ### Icons
 
-`Icon` renders `lucide-react-native` — Lucide is a maintained superset of
-Feather in the same 24px, 2px round-stroke style. `name` is typed by
-`IconName`, the union of kebab-case Lucide names in the package registry
-(`src/components/icon-names.json`, about 150 names). Importing `Icon` includes
-that named registry because `name` is looked up at runtime, even when a caller
-uses `component`; the root `lucide-react-native` entry (1,800+ icons) is never
-imported. `color` takes a theme color name or a
-literal. `accessibilityLabel` names an icon that stands alone (`role="img"` +
-`aria-label` on web, `accessible` + `accessibilityLabel` on native); an icon
-without one is hidden from assistive tech — the glyph beside text that already
-says it would otherwise be announced as an unnamed image — and `decorative`
-only remains to silence a labelled icon. On web the SVG carries ARIA only
-(`aria-hidden` or `role="img"`), never the RN-only accessibility props. Instead of `name`,
-`Icon` and `Button.Icon` take `component`: any Lucide import (or another SVG
-component that accepts `size` and `color`), sized, colored, themed, and hidden
-from assistive tech exactly like a named icon. `Button.Icon` defaults its
-color to the button's label color either way.
+`Icon` draws Lucide glyphs from plain data: each icon is a list of
+`[tag, attrs]` SVG nodes on a 24×24 grid, stroked 2 px with round caps and
+joins. The package owns both renderers: an inline `<svg>` on web and in
+server-rendered HTML (stroked `currentColor` with the color as a style, so a
+theme change recolors it through CSS and server and client markup match), and
+`react-native-svg` on iOS and Android, drawn the way Lucide's own native
+component draws it. No icon runtime or font ships, and each registered glyph
+adds about 40 bytes (brotli) to the bundle.
+
+`name` is typed by `IconName`: the 19 names the package's own components draw
+(`src/components/icon-names.json`: the chevrons, `check`, `x`, the status and
+theme-mode glyphs) plus every name the app registers. An app lists the Lucide
+names it uses in `client/icons.json` and compiles them with the package's
+`expo-ui-icons` CLI:
+
+```json
+{ "icons": ["archive", "bell", "compass"], "tabIcons": ["compass"] }
+```
+
+```sh
+bunx expo-ui-icons init          # seed client/icons.json from name="…" / icon="…" literals in app/, client/, shared/
+bunx expo-ui-icons add calendar  # add names; an alias is replaced by its canonical name
+bunx expo-ui-icons               # write client/icons.generated.ts (--check: exit 1 when stale)
+bunx expo-ui-icons tabs          # rasterize tabIcons to 1x/2x/3x template PNGs (--check never rasterizes)
+```
+
+The generated module exports the glyphs as `appIcons` and augments the
+`IconRegistry` interface, so the new names type-check everywhere. Register them
+once at module scope in the root layout, so they are in place before any route
+renders, on the server as well as the client:
+
+```tsx
+import { registerIcons } from "@mrmeg/expo-ui/components/Icon";
+import { appIcons } from "@/client/icons.generated";
+
+registerIcons(appIcons);
+```
+
+An unregistered literal is a type error. A name that arrives at runtime (a
+database field, a server payload) renders nothing and warns once in
+development; check it with `isIconName(value)`, which narrows to `IconName`.
+The CLI rejects a name that is not in the snapshot, and an alias with its
+canonical name (`home → house`); the alias map also ships in
+`design-system.json` as `icons.aliases`. Brand glyphs (`github`, `chrome`,
+`facebook`, `instagram`, `linkedin`, `twitter`) have no Lucide equivalent.
+
+`tabs` writes `assets/icons/tabs/<name>.png` (plus `@2x` and `@3x`) and
+`client/tabIcons.generated.ts` (`TAB_ICONS`, `TabIconName`) for a native tab
+bar: `<NativeTabs.Trigger.Icon src={TAB_ICONS.compass} renderingMode="template" />`.
+The PNGs are black on transparent and the platform tints them. Freshness is a
+hash of each glyph's SVG in `assets/icons/tabs/manifest.json`, so `tabs --check`
+and an up-to-date `tabs` need no rasterizer; only a changed tab icon needs
+`rsvg-convert` (`brew install librsvg`, or point `RSVG_CONVERT` at it).
+
+`color` takes a theme color name or a literal. `accessibilityLabel` names an
+icon that stands alone (`role="img"` + `aria-label` on web, `accessible` +
+`accessibilityLabel` on native); an icon without one is hidden from assistive
+tech — the glyph beside text that already says it would otherwise be announced
+as an unnamed image — and `decorative` only remains to silence a labelled icon.
+On web the SVG carries ARIA only (`aria-hidden` or `role="img"`), never the
+RN-only accessibility props. A named icon's SVG root takes `testID`, which
+defaults to `icon-<name>` in development. Instead of `name`, `Icon` and
+`Button.Icon` take `component` (an `IconComponent`) for art that is not a
+Lucide icon, such as a brand mark: any component that accepts `size` and
+`color`, sized, colored, themed, and hidden from assistive tech exactly like a
+named icon. `Button.Icon`, `ToggleIcon`, and `ToggleGroupIcon` take the same
+props, default their color to the control's label color, and are decorative.
 
 ```tsx
 import { Button, Icon } from "@mrmeg/expo-ui/components";
-import House from "lucide-react-native/icons/house";
-import Rocket from "lucide-react-native/icons/rocket";
+import { GitHubMark } from "@/client/components/GitHubMark";
 
 <Icon name="circle-check-big" color="success" size={16} />
-<Icon component={Rocket} color="accent" />
+<Icon component={GitHubMark} color="accent" />
 <Button onPress={goHome}>
-  <Button.Icon component={House} />
+  <Button.Icon name="house" />
   <Button.Text>Home</Button.Text>
 </Button>
 ```
 
-Adding an icon: in this repo, add the kebab-case Lucide name to
-`packages/ui/src/components/icon-names.json` (keep it sorted), run
-`bun run ui:icons`, and commit both files — an unknown name fails with the
-alias lines from Lucide's root entry that point at its current name
-(`bun run ui:icons:check` guards freshness in CI). From a consuming app, pass
-any Lucide component through `component` instead; it needs no registry entry.
-Feather-era names that Lucide renamed: `alert-circle` → `circle-alert`,
-`check-circle` → `circle-check-big`, `x-circle` → `circle-x`,
-`alert-triangle` → `triangle-alert`, `help-circle` → `circle-question-mark`,
-`edit` → `square-pen`, `edit-2` → `pen`, `edit-3` → `pencil`,
-`sliders` → `sliders-horizontal`, `grid` → `layout-grid`, `home` → `house`,
-`unlock` → `lock-open`, `trash-2` → `trash`, `tool` → `wrench`,
-`layout` → `panels-top-left`, `bar-chart-2` → `chart-no-axes-column`,
-`plus-circle` → `circle-plus`, `stop-circle` → `circle-stop`,
-`more-vertical` → `ellipsis-vertical`, `more-horizontal` → `ellipsis`,
-`sidebar` → `panel-left`, `smile` → `face-slightly-smiling`. Brand glyphs
-(`github`, `chrome`, `facebook`, `instagram`, `linkedin`, `twitter`) have no
-Lucide equivalent; use `component` with your own SVG.
+The Lucide snapshot ships as `dist/icons/lucide.json` (Lucide 1.57.0: every
+icon plus the alias map) and the CLI compiles against it, so adding a name needs
+no package release. Lucide renames about one name in six minor releases and
+sometimes redraws a glyph under a stable name, so the snapshot is pinned
+exactly and moves only in a package release: after upgrading, run
+`bunx expo-ui-icons` and `bunx expo-ui-icons tabs`, review the glyph diff, and
+replace any name the CLI now rejects. Lucide is ISC-licensed (its
+Feather-derived icons MIT); the license ships as `dist/icons/LICENSE.lucide`.
+
+Tests need no icon mock and no Lucide module mapping: glyphs are plain objects
+drawn with `react-native-svg`. Register `appIcons` in the Jest setup (lazily, in
+a `beforeAll`, so test-file mocks still apply to `Icon`) and query a named icon
+by its `icon-<name>` test id.
+
+In this repository, `bun run ui:icons` regenerates `iconBuiltins.generated.ts`,
+`src/icons/lucide.json`, and `src/icons/LICENSE.lucide` from the exactly pinned
+`lucide-static` devDependency and `icon-names.json`. A Lucide bump changes that
+pin, then `bun install`, `bun run ui:icons`, `bun run icons`, and
+`bun run icons:tabs`. The template app's own list is `client/icons.json`
+(`bun run icons`, `bun run icons:tabs`).
 
 ### Compound Parts
 
@@ -841,7 +894,7 @@ are named exports only.
 
 | Hook | Returns |
 |------|---------|
-| `useResources()` | `{ loaded, error }` — loads the Inter faces (icons are SVG, nothing to load) |
+| `useResources()` | `{ loaded, error }` — loads the Inter faces (icons are SVG drawn from glyph data, nothing to load) |
 | `useTheme()` | Active theme, scheme helpers, shadow/contrast/alpha helpers |
 | `useStyles(factory)` | Memoized theme-aware styles plus the `useTheme()` helpers |
 | `useDimensions()` | `{ width, height, orientation, isSmallScreen, isMediumScreen, isLargeScreen }` against `SCREEN_SIZES` (768 / 1000 / 1200) |
@@ -1033,7 +1086,7 @@ import { Drawer, Icon } from "@mrmeg/expo-ui/components";
   title="Acme"
   action={
     <Drawer.ToggleCollapse>
-      <Icon name="sidebar" decorative />
+      <Icon name="panel-left" decorative />
     </Drawer.ToggleCollapse>
   }
 />
@@ -1218,9 +1271,10 @@ copies of `@radix-ui/react-slot` crashes the web `AlertDialog` with
 `pkg ui build` also writes `dist/design-system.json`
 ([`scripts/build-design-system-manifest.mjs`](../../scripts/build-design-system-manifest.mjs)):
 the spacing, radius and icon scales, the palette, the light and dark themes, the
-font variants, every component's variant and size values, and `icons.names` (the
-`IconName` registry), serialized out of `src` by the same extractor the lint
-rules use. It is exported as
+font variants, every component's variant and size values, and `icons` (the
+builtin `IconName` list as `names`, Lucide's renamed-name `aliases`, and the
+snapshot's `lucide` version), serialized out of `src` by the same extractor the
+lint rules use. It is exported as
 `@mrmeg/expo-ui/design-system.json`, and `@mrmeg/eslint-plugin-expo-ui` reads it
 in projects that install this package instead of checking out its sources — which
 is what lets the design-system rules quote this release's presets and tokens.