@mrmeg/expo-ui 0.27.1 → 0.29.0

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
@@ -59,6 +60,14 @@ Importable paths: root, `components`, `components/*`, `constants`,
 `constants/*`, `hooks`, `hooks/*`, `state`, `state/*`, `lib`. Never import from
 `dist/*` or a source checkout path.
 
+The package declares `sideEffects`: only `state/themeStore` does work at import
+time (on native it loads the saved theme and starts the OS color-scheme
+listener). A bundler that tree-shakes (Expo with `EXPO_UNSTABLE_TREE_SHAKING=1`,
+esbuild, Rollup, webpack) keeps only the modules a barrel import actually uses,
+so `import { Button } from "@mrmeg/expo-ui"` costs about what the
+`components/Button` deep import does. Metro without tree shaking bundles
+everything a file imports, so the deep imports stay the smaller choice there.
+
 ## App Startup
 
 Call `useResources()` once near the Expo app root before hiding the splash
@@ -97,6 +106,21 @@ export default function RootLayout() {
 }
 ```
 
+On web with server rendering, tell the kit the visitor's scheme for the first
+render: `<InitialSchemeProvider scheme={cookieScheme}>` around the root layout
+(or `<UIProvider initialScheme>` when nothing above it reads the theme), where
+`cookieScheme` is `"light"` / `"dark"` read from the same cookie on the server
+and the client — see the template's `shared/ssrColorScheme.ts`. `useTheme()`
+paints it until the persisted preference has loaded.
+
+A Radix-backed component (`Tabs`, `Accordion`, `Collapsible`, `Select`,
+`DropdownMenu`, `Popover`) inside a server-rendered route logs a `useId`
+hydration mismatch in development, because Expo Router's server renders the app
+inside `+html.tsx` while the client hydrates `#root`. Wrap that subtree in
+`<Hydrated fallback={…}>` (from `@mrmeg/expo-ui/components`): the fallback holds
+the layout in the server HTML and the children mount in the first client render.
+Keep content that must be server-rendered outside the gate.
+
 `UIProvider` is required before `Dialog`, `AlertDialog`, `BottomSheet`,
 `Drawer`, `DropdownMenu`, `Popover`, `SelectContent`, `Tooltip`, and package
 notifications.
@@ -113,6 +137,45 @@ For a subtree with custom keyboard behavior, use `KeyboardAvoidingView`
 directly (`behavior`, `automaticOffset`, `contentContainerStyle`,
 `keyboardVerticalOffset`).
 
+### Web setup
+
+Web needs two more pieces, because every web theme color is a CSS variable
+(see [Web theming is CSS variables](#web-theming-is-css-variables)) and the
+theme store boots at `"system"`/light so the first client render matches the
+server-rendered or exported HTML:
+
+1. **`app/+html.tsx`: define the variables.** Put `getThemeCssVariables()` (from
+   `constants`) in the document's global `<style>`, passing the same overrides
+   you give `setColors` if you re-brand. Without it every `var(--c-*)` color is
+   unset. A blocking inline script that stamps `data-theme` on `<html>` from
+   the persisted preference (`THEME_STORAGE_KEY`, from `state`) or
+   `prefers-color-scheme` makes the first frame paint in the visitor's scheme
+   before any JS runs.
+2. **Root layout: sync the store after the first commit.** Call
+   `syncThemeFromEnvironment()` (from `state`) in a top-level `useEffect` and
+   return its result as the cleanup. It reads the persisted preference and
+   starts following the OS color scheme. Never call it during render or at
+   module scope: the server has no `window`, and reading it while hydrating
+   would disagree with the markup. It is safe to call more than once
+   (StrictMode's double effects, several roots): the calls share one OS
+   listener, and each cleanup releases only its own call. `UIProvider` does not
+   call it. A web app that skips it stays on the boot default until the user
+   picks a theme. Native loads the preference and follows the OS at startup, so
+   the call is optional there.
+
+```tsx
+// app/+html.tsx (head)
+import { getThemeCssVariables } from "@mrmeg/expo-ui/constants";
+
+<style>{`${getThemeCssVariables()} body { background-color: var(--c-background); }`}</style>
+
+// Root layout
+import { useEffect } from "react";
+import { syncThemeFromEnvironment } from "@mrmeg/expo-ui/state";
+
+useEffect(() => syncThemeFromEnvironment(), []);
+```
+
 ### Keyboard dismissal
 
 `DismissKeyboard` owns tap-away dismissal without claiming touches. Its scroll
@@ -135,34 +198,35 @@ import { StyledText } from "@mrmeg/expo-ui/components";
 import { spacing } from "@mrmeg/expo-ui/constants";
 import { useTheme } from "@mrmeg/expo-ui/hooks";
 
-export function Panel() {
-  const { theme, getShadowStyle } = useTheme();
+export function Intro() {
+  const { theme } = useTheme();
 
   return (
-    <View
-      style={[
-        { backgroundColor: theme.colors.card, borderColor: theme.colors.border },
-        { borderWidth: StyleSheet.hairlineWidth, borderRadius: spacing.radiusLg },
-        { padding: spacing.cardPadding, gap: spacing.sm },
-        getShadowStyle("subtle"),
-      ]}
-    >
-      <StyledText semantic="heading">Theme-aware panel</StyledText>
+    <View style={{ paddingHorizontal: spacing.screenPadding, gap: spacing.sm }}>
+      <StyledText semantic="heading">Theme-aware section</StyledText>
       <StyledText semantic="body" style={{ color: theme.colors.mutedForeground }}>
         Uses package tokens instead of hardcoded colors.
       </StyledText>
+      <View style={{ height: StyleSheet.hairlineWidth, backgroundColor: theme.colors.border }} />
     </View>
   );
 }
 ```
 
+Sections sit on the screen's 16 pt gutter and end in a hairline, not in a
+bordered, shadowed panel; see [Screen layout](#screen-layout).
+
 `useTheme()` returns the active `theme`, resolved `scheme`, persisted
 `currentTheme`, `setTheme`, `toggleTheme`, `getShadowStyle`,
 `getFocusRingStyle(offset = 2)`, `getContrastingColor`, `getContrastRatio`,
 `getTextColorForBackground`, and `withAlpha`. `getShadowStyle(type)` takes
 `base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`,
 `cardHover`, or `cardSubtle` and returns a cross-platform `boxShadow` (RN 0.85
-and react-native-web 0.21 deprecate the legacy `shadow*` props).
+and react-native-web 0.21 deprecate the legacy `shadow*` props). The layers
+follow the scheme: in dark the raised presets add a 1px inset white top
+highlight to black shadows at real alpha (a faint drop shadow is invisible on a
+near-black base); in light it is the shadow alone, at about twice the original
+alpha.
 
 Semantic tokens on `theme.colors`: `surfaceSunken`, `background`, `foreground`,
 `card`, `cardForeground`, `popover`, `popoverForeground`, `text`, `textDim`,
@@ -172,12 +236,13 @@ Semantic tokens on `theme.colors`: `surfaceSunken`, `background`, `foreground`,
 `secondary` a neutral secondary surface, `accent` the teal highlight, `input`
 the default form-control border, `ring` the focus outline.
 
-Surfaces are layered tiers, not shadow depths: `surfaceSunken` (app chrome such
-as the Drawer rail) < `background` (content) < `card`/`popover` (raised panels)
-< `muted` (chips, insets). `border` is the hairline on `background`/`card`; use
+Surfaces are layered tiers, with an edge highlight in dark: `surfaceSunken` (app
+chrome such as the Drawer rail) < `background` (content) < `card`/`popover`
+(raised panels) < `muted` (chips, insets). `border` is the hairline on `background`/`card`; use
 `borderStrong` on filled surfaces. `textDim`/`mutedForeground` hold at least
 7:1 against `background`/`card` and 6:1 against `muted` in both schemes,
-enforced by a package test.
+enforced by a package test. If you override `background`, `card`, or `popover`,
+re-check them against the template's Surface Lab (`/surface-lab`).
 
 When `currentTheme` is `"system"` the package tracks the OS color scheme and
 updates every `useTheme()`/`useStyles()` consumer through the theme store. Do
@@ -193,10 +258,13 @@ helpers.
 import { useStyles } from "@mrmeg/expo-ui/hooks";
 
 const { styles } = useStyles(({ theme, spacing, withAlpha }) => ({
-  card: {
-    backgroundColor: withAlpha(theme.colors.primary, 0.08),
+  content: {
+    paddingVertical: spacing.md,
+    gap: spacing.sectionSpacing,
+  },
+  selectedIcon: {
+    backgroundColor: withAlpha(theme.colors.primary, 0.12),
     borderRadius: spacing.radiusMd,
-    padding: spacing.md,
   },
 }));
 ```
@@ -206,7 +274,13 @@ const { styles } = useStyles(({ theme, spacing, withAlpha }) => ({
 On web every `theme.colors.*` value resolves to a CSS custom property
 (`var(--c-<kebab-token>)`), so styles built from the theme — including HTML
 shells baked at export time — re-theme purely in CSS when `html[data-theme]`
-changes. Native keeps literal values.
+changes. Native keeps literal values. Because the references are the same in
+both schemes, web shares one object between them (`colors.light.colors ===
+colors.dark.colors`), so a scheme switch keeps `theme.colors` identical and
+anything memoized on it keeps its result. Re-brand through `setColors`, not by
+mutating that object. The package keeps `html[data-theme]` on the resolved
+scheme with one store subscription, started by the first `useTheme()` consumer
+to mount.
 
 Consequence: hex-suffix alpha (`theme.colors.x + "15"`) does not work. Use
 `withAlpha(theme.colors.x, 0.08)`, exported standalone from `hooks` as well as
@@ -235,21 +309,63 @@ everywhere at once:
 
 | Token | Value | Use |
 |-------|-------|-----|
-| `screenPadding` | 16 | Horizontal gutter for screens, scroll content, landing blocks |
-| `sectionSpacing` | 24 | Gap between grouped lists, cards, settings groups |
-| `cardPadding` | 16 | `Card`, `StatCard`, any bordered panel |
+| `screenPadding` | 16 | The one horizontal inset per screen: scroll content, landing blocks, text and forms between row groups |
+| `sectionSpacing` | 24 | Gap between screen sections and `ItemGroup`s |
+| `cardPadding` | 16 | Inside `Card` and `StatCard` tiles; not a layout inset |
 | `dialogPadding` | 20 | `Dialog` and `AlertDialog` content |
-| `rowPaddingY` / `rowPaddingX` | 10 / 16 | `Item` rows and hand-rolled list rows |
+| `rowPaddingY` / `rowPaddingX` | 10 / 16 | `Item` rows; `rowPaddingX` is the row's copy of the screen inset |
 | `rowGap` | 12 | Gap between row media, content, actions |
 | `rowMinHeight` | 40 | Visual row height on web; native rows keep `touchTarget` |
 | `formRowMinHeight` | 32 | Checkbox and radio rows on web; native keeps `touchTarget` |
-| `touchTarget` | 44 | Minimum native hit area; pair a smaller visual height with `hitSlop` |
+| `touchTarget` | 44 | Minimum hit area for a control. `Button`, `Toggle` and `ToggleGroup` items reach it on every platform: native through computed `hitSlop`, web through a transparent hit extender inside the drawn box (react-native-web ignores `hitSlop`) |
+| `minTarget` | 24 | Smallest pointer target the kit draws on web (WCAG 2.5.8); `Checkbox`/`RadioGroup` grow their hit box to it around a smaller drawn box |
 
 Controls size themselves from their own `size` prop and ignore these tokens:
 `Button` 28/32/40 (`sm`/`md`/`lg`), `TextInput` and `Select` 32/36/40
 (`sm`/`md`/`lg`), `Toggle` 32/36/40 (`sm`/`default`/`lg`), `Tabs` 32/36
 (`sm`/`md`).
 
+### Screen layout
+
+Phones are narrow, so every nested inset comes out of the content. Screens
+built from this package are flat:
+
+- **Start from `Screen`.** `<Screen edges={["bottom"]} scroll>` is the page
+  container: safe-area insets on the edges the screen owns (`edges` is
+  required — `["bottom"]` under a Stack header, `["top"]` above a tab bar,
+  `["top", "bottom"]` headerless, `[]` when the navigator owns both), the one
+  horizontal inset, the theme background under all of it. `scroll` puts the
+  insets on the `ScrollView`'s content so it scrolls under the island and home
+  indicator; `padded={false}` for full-bleed `ItemGroup` rows. Its
+  `contentContainerStyle` padding is added to the insets, never replaced.
+  Insets come from `useWindowInsets()` (`@mrmeg/expo-ui/hooks`), which also
+  covers content the system presents outside the app's `SafeAreaProvider`
+  (modals, native sheets), as `Notification`, `Dialog` and `BottomSheet` do.
+- **One horizontal inset: `spacing.screenPadding` (16).** Either a container
+  pads or its children do, never both. `Item` rows carry the inset themselves,
+  so a screen of `ItemGroup`s pads nothing horizontally; text, forms, and
+  buttons between the groups pad their own wrapper.
+- **No boxes as layout.** Don't wrap a section, a form, or a group of rows in
+  a bordered, shadowed, or tinted rounded panel. Separate sections with a
+  header, `spacing.sectionSpacing`, or a hairline (`Separator`).
+- **Lists and settings are `ItemGroup` + `Item`:** plain full-width rows,
+  inset hairlines, no card per row, no border around the group. A `Switch`,
+  `Checkbox` or `Toggle` in `ItemActions` takes its accessible name from the
+  row's `ItemTitle` (`useItemControlLabel` does the same for a custom control).
+- **Forms:** fields span the column, grouped under section headers.
+- **Primary content fills the width.** Photos, video, maps, QR codes, and
+  charts size to the column (`width: "100%"` plus `aspectRatio`), never a
+  fixed size in whitespace.
+- **Wide screens cap the column** instead of boxing it:
+  `contentContainerStyle={{ width: "100%", maxWidth: 640, alignSelf: "center" }}`.
+- **`Card` is for** one item in a collection (a feed entry, a grid tile, a
+  carousel slide) or a single tappable object. Never nest Cards.
+
+On a 390 pt phone a boxed settings group puts row content 33 pt from each edge
+(16 screen + 1 border + 16 row) and leaves 324 pt for it; the flat group puts
+it 16 pt in and leaves 358 pt. [`LLM_USAGE.md`](LLM_USAGE.md#screen-layout)
+has a complete screen.
+
 ### Color overrides
 
 Colors resolve in three layers, last wins: package defaults (zinc/teal) →
@@ -278,23 +394,113 @@ useThemeStore.getState().setColors({
 unwinds when that subtree unmounts. Nested scopes compose (inner keys win,
 outer fill in), and a scoped key beats the global brand inside it.
 
+#### Extending the palette
+
+An app with tokens the package does not have (a brand gold, a chart series)
+declares them once on `ThemeColorExtensions`, and they become part of
+`ThemeColors` everywhere: `setColors` and `ThemeColorScope` accept them,
+`useTheme().theme.colors.brandGold` is typed, and `getThemeCssVariables`
+emits a `--c-brand-gold` variable when the overrides you pass it name the
+key. No side palette, no cast.
+
+```ts
+// theme.d.ts (any file in the app's TypeScript program)
+declare module "@mrmeg/expo-ui/constants" {
+  interface ThemeColorExtensions {
+    brandGold: string;
+  }
+}
+
+// startup
+useThemeStore.getState().setColors({
+  light: { primary: "#7c3aed", brandGold: "#c9a227" },
+  dark: { primary: "#a78bfa", brandGold: "#ffe066" },
+});
+
+// anywhere
+const { theme } = useTheme();
+theme.colors.brandGold; // string
+```
+
+Two things to know. The package ships no value for an extension key, so
+provide it in both schemes or it is `undefined` at runtime in the scheme that
+lacks it. And on web the built-in tokens are `var(--c-*)` references while
+extension values are literals per scheme, so with any override `theme.colors`
+is a new object when the scheme changes (the identity caveat every override
+already has); the CSS variable from `getThemeCssVariables` is the way to use
+an extension token in an HTML shell.
+
 ### Shape overrides
 
-`setShape` is the geometry counterpart, grouped per component. It currently
-covers Button:
+`setShape` is the geometry counterpart, grouped per slot. Each slot takes a
+`borderRadius`; `button` also takes `withShadow`:
 
 ```tsx
 useThemeStore.getState().setShape({
-  button: {
-    borderRadius: 9999, // pill buttons everywhere; package default is 12
-    withShadow: false,  // flatten the `default` preset; package default is true
-  },
+  button: { borderRadius: 9999, withShadow: false }, // pills, flat `default` preset
+  input: { borderRadius: spacing.radiusXl },          // TextInput, Select, InputOTP
+  card: { borderRadius: spacing.radius2xl },          // Card, StatCard, EmptyState, SkeletonCard
+  sheet: { borderRadius: spacing.radius2xl },         // BottomSheet top corners
+  badge: { borderRadius: spacing.radiusSm },          // squarer badges
+  dialog: { borderRadius: spacing.radius2xl },        // Dialog and AlertDialog
 });
 ```
 
+| Slot | Reaches | Package default |
+|---|---|---|
+| `button` | Button, every preset (`withShadow` only affects `default`) | `spacing.radiusMd` (10), shadow on |
+| `input` | TextInput (`outline` and `filled`; `underlined` stays square), Select trigger, InputOTP cells | `spacing.radiusMd` (10) |
+| `card` | Card (surface and pressable focus ring), StatCard, EmptyState with `bordered`, SkeletonCard | `spacing.radiusLg` (14) |
+| `sheet` | BottomSheet top corners, where the platform lets the sheet draw them (web, Android); iOS system sheets keep the system radius | platform |
+| `badge` | Badge | `spacing.radiusFull` (pill) |
+| `dialog` | Dialog and AlertDialog content | `spacing.radiusLg` (14) |
+
 Precedence is caller-wins: a per-instance `style={{ borderRadius }}` or
 `withShadow` prop beats the global override, which beats the package default.
-`setShape({})` clears back to the defaults.
+`setShape({})` clears back to the defaults. A component reads its slot with
+`useShape(slot)` from `@mrmeg/expo-ui/hooks` and layers the radius after its
+static one; `shapeRadius(override)` turns the slot into a `{ borderRadius }`
+style or `undefined` for that layering.
+
+### Press feedback and haptics
+
+Every pressable shares one pressed look: a 0.97 scale (0.92 on small controls)
+plus `interaction.pressedOpacity` (0.85) on filled surfaces, and
+`interaction.disabledOpacity` (0.5) when disabled — both from
+`@mrmeg/expo-ui/constants`. Under the OS reduce-motion setting the scale stays
+at 1 and only the opacity signals the press.
+
+Haptics are one provider-level setting, read at event time:
+
+```tsx
+<UIProvider haptics="all">…</UIProvider>
+// or, from startup code:
+import { setHaptics } from "@mrmeg/expo-ui/state";
+setHaptics("all");
+```
+
+| `haptics` | Fires on |
+|---|---|
+| `"off"` | nothing |
+| `"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
+and haptic, dims, and leaves the web tab order — for actions that cannot run.
+`aria-disabled` (or `accessibilityState={{ disabled: true }}`) is announced
+and dimmed the same way but stays focusable and pressable, so the press can say
+why: a required question's "Next", a "Publish" without a title. Prefer it
+whenever the user could otherwise wonder why nothing happens.
+
+```tsx
+<Button text="Publish" aria-disabled={!title} onPress={() => (title ? publish() : notify.info("Add a title first"))} />
+```
+
+Web never vibrates. A single `Button` can force either way with `haptic`
+(`<Button haptic />`, `<Button haptic={false} />`); `useScalePress({ haptic })`
+takes `true` (always), `false` (never) or `"setting"` (the default, follows the
+provider). `hapticSuccess()` from `@mrmeg/expo-ui/lib` is there for completion
+moments the app owns.
 
 ## Typography
 
@@ -312,6 +518,11 @@ import { BodyText, CaptionText, HeadingText, StyledText } from "@mrmeg/expo-ui/c
 - `semantic`: `title`, `heading`, `subheading`, `body`, `caption`, `label`, `eyebrow`
 - `size`: `xs`, `sm`, `base`, `body`, `lg`, `xl`, `xxl`, `display`
 - `fontWeight`: `light`, `regular`, `medium`, `semibold`, `bold`
+- `italic`: a real italic face where the family has one (an app's `setFonts`
+  `italic` map, or the Newsreader serif preset below), otherwise
+  `fontStyle: "italic"` and the platform synthesizes the slant. Inter ships no
+  italic file on native (four upright weights, by design); on web the injected
+  Inter stylesheet carries the 400 italic, so body-weight italic is real there
 - `variant`: `sansSerif`, `serif`, `mono`
 - `align`, `text`, `tx`, `txOptions`
 - `selectable`: defaults to `true` on iOS and web and to `false` on Android
@@ -348,12 +559,16 @@ configureExpoUiI18n((key, options) => i18n.t(key, options));
 
 Inter is the sans face on every platform, in four static weights
 (`Inter_400Regular`, `Inter_500Medium`, `Inter_600SemiBold`, `Inter_700Bold`)
-from the bundled `@expo-google-fonts/inter`. Serif is Georgia; mono is the
-platform system monospace.
+from the bundled `@expo-google-fonts/inter`. Serif is Georgia by default, or
+Newsreader through the serif preset below; mono is the platform system
+monospace.
 
 `useResources()` loads those four weights on native, so `StyledText`'s
-`light`–`bold` range resolves to real files instead of a faked OS bold. Icons
-are SVG (`lucide-react-native`), so there is no icon font to load on any
+`light`–`bold` range resolves to real files instead of a faked OS bold. Each
+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 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
@@ -366,10 +581,82 @@ Expo Router web apps, add the links to app-owned `app/+html.tsx`:
 <link
   id="mrmeg-expo-ui-inter"
   rel="stylesheet"
-  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+  href="https://fonts.googleapis.com/css2?family=Inter:ital,wght@0,400;0,500;0,600;0,700;1,400&display=swap"
 />
 ```
 
+### Serif preset: Newsreader
+
+Georgia is one face per platform, so `SerifText fontWeight="bold"` is a faux
+bold and `italic` a synthesized slant. Newsreader is a real serif family —
+four weights and a 400 italic — offered as an opt-in preset that costs an app
+nothing unless it opts in: the package does not depend on the font package, so
+the app adds it and hands the native files over.
+
+```bash
+bun add @expo-google-fonts/newsreader
+```
+
+```ts
+// lib/newsreaderFonts.native.ts — per-weight subpaths, so the native bundle
+// carries exactly these five files. The web twin exports `null`.
+import { Newsreader_400Regular } from "@expo-google-fonts/newsreader/400Regular";
+import { Newsreader_400Regular_Italic } from "@expo-google-fonts/newsreader/400Regular_Italic";
+import { Newsreader_500Medium } from "@expo-google-fonts/newsreader/500Medium";
+import { Newsreader_600SemiBold } from "@expo-google-fonts/newsreader/600SemiBold";
+import { Newsreader_700Bold } from "@expo-google-fonts/newsreader/700Bold";
+
+export const newsreaderFontMap = {
+  Newsreader_400Regular,
+  Newsreader_500Medium,
+  Newsreader_600SemiBold,
+  Newsreader_700Bold,
+  Newsreader_400Regular_Italic,
+};
+```
+
+```tsx
+// where the app already calls useResources
+const { loaded } = useResources({ serif: "newsreader", serifFonts: newsreaderFontMap });
+```
+
+On native `useResources` registers the files and then sets the theme store's
+`serifPreset` to `"newsreader"`, so serif text resolves to
+`Newsreader_400Regular` … `Newsreader_700Bold` (`light` shares the 400 file)
+and `italic` to `Newsreader_400Regular_Italic` at every weight. On web it
+injects one Google Fonts stylesheet (`Newsreader:ital,wght@0,400;0,500;0,600;0,700;1,400`)
+under the id `mrmeg-expo-ui-newsreader` — put an element with that id in
+`+html.tsx` (the Google Fonts `<link>`, or self-hosted `@font-face` rules as
+this template does from `@fontsource-variable/newsreader`) and the hook skips
+its own — and switches the preset at once
+(the stack falls back to Georgia until the faces arrive); weight is numeric on
+the shared `"Newsreader"` family. A `setFonts` serif override wins over the
+preset and skips its load. Without `serifFonts` on native the hook warns once
+and keeps Georgia. The family names are exported as `newsreaderFamilies` from
+`@mrmeg/expo-ui/constants`; `SerifPreset` and `useThemeStore().serifPreset` /
+`setSerifPreset` are the store side.
+
+### Italic faces through `setFonts`
+
+Each family group in `setFonts` takes an `italic` map beside the weights:
+
+```ts
+useThemeStore.getState().setFonts({
+  families: {
+    sansSerif: {
+      regular: "Brand_Regular",
+      bold: "Brand_Bold",
+      italic: { regular: "Brand_Italic", bold: "Brand_BoldItalic" },
+    },
+  },
+});
+```
+
+`italic` on `StyledText` (or `useFontStyle(weight, variant, { italic: true })`)
+then uses the italic face for its weight, falls back to the group's italic
+`regular` when that weight has none, and emits no `fontStyle`; a group with no
+`italic` map synthesizes on its upright face.
+
 ### Font overrides
 
 Forward your own faces with `setFonts`, once at startup after they are
@@ -431,7 +718,7 @@ building a new primitive.
 | `Badge` | Short status labels | Draft/active state, counts, plan and role tags |
 | `BottomSheet` | Mobile-first modal sheets | Action pickers, mobile filters, quick edit forms |
 | `Button` | Commands and CTAs | Submit, save, delete, navigation CTAs; loading state keeps the resting width |
-| `Card` | Framed content groups | List items, pricing plans, settings sections, dashboards |
+| `Card` | One item in a collection, or a single tappable object; not a layout box | Feed entries, grid tiles, carousel slides, a tappable summary |
 | `Carousel` | Horizontally snapping slides with pressable dots | Testimonials, onboarding pages, image galleries |
 | `Checkbox` | Boolean selection | Terms consent, checklists, multi-select filters |
 | `Collapsible` | One-off disclosure | Advanced settings, hidden helper text |
@@ -441,68 +728,137 @@ 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 |
 | `KeyboardAvoidingView` | Native keyboard-aware layout | Screen roots, composer footers, form-heavy subtrees |
 | `Label` | Accessible form labels | Required, disabled, and group labels |
-| `MaxWidthContainer` | Centered responsive width | Web pages, tablet layouts, auth panels |
+| `MaxWidthContainer` | Centered responsive width | Web pages, tablet layouts, auth forms |
 | `Notification` | Global toast surface | Saved/error/sync toasts, action toasts, loading toast |
+| `Screen` | Page container: safe-area `edges`, one horizontal inset, theme background, optional scroll | Every screen root; under a header pass `edges={["bottom"]}` |
 | `Popover` | Anchored contextual content | Inline help, quick previews, small forms |
 | `Progress` | Determinate or indeterminate progress | Upload progress, onboarding completion |
 | `RadioGroup` | Mutually exclusive choices | Plan interval, visibility choice, survey answer |
-| `SectionHeader` | Eyebrow / title / description section intro | Landing sections, settings groups, report headers |
+| `SectionHeader` | Eyebrow / title / description section intro | Landing sections, report headers, empty-screen intros |
 | `SegmentedControl` | Native segmented picker (`@expo/ui`) | Platform-native view switchers, iOS-style filters |
 | `Select` | Option menus | Country, category, status pickers; `label` drives default item text |
-| `Separator` | Horizontal or vertical dividers | Menu, section, and card dividers |
+| `Separator` | Horizontal or vertical dividers | Section, menu, and toolbar dividers |
 | `Skeleton` | Loading placeholders | List, profile card, dashboard loading |
 | `Slider` | Numeric value selection (`@expo/ui`) | Volume, percentage, rating, threshold |
-| `StatCard` | Metric tile: `label`, `value`, `unit`, `change`, `icon`, `onPress` | KPI rows, analytics summaries, usage meters |
+| `StatCard` | Metric tile: `label`, `value`, `unit`, `change`, `icon`, `onPress` | A scrolling KPI rail, one tappable metric |
 | `StatusBar` | Theme-aware native status bar | Root layout status styling |
 | `StyledText` and aliases | Theme-aware typography | Titles, labels, body copy, captions, translated text |
 | `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), so only the icons the package
-and its consumers name ship in the bundle: the root `lucide-react-native`
-entry (1,800+ icons) is never imported. `color` takes a theme color name or a
-literal; `decorative` hides the glyph from assistive tech.
+`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 { Icon } from "@mrmeg/expo-ui/components";
-import Rocket from "lucide-react-native/icons/rocket";
+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 { 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 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.55.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
 
@@ -518,7 +874,7 @@ Lucide equivalent; use `component` with your own SVG.
 | `Dialog` | `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter`, `DialogTitle`, `DialogDescription`, `DialogClose` |
 | `Drawer` | `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerBody`, `DrawerFooter`, `DrawerClose`, `DrawerToggleCollapse` |
 | `DropdownMenu` | `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuGroup`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuLabel`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuPortal`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent` |
-| `Item` | `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions` |
+| `Item` | `ItemGroup`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions` |
 | `Popover` | `PopoverTrigger`, `PopoverContent`, `PopoverHeader`, `PopoverBody`, `PopoverFooter` |
 | `RadioGroup` | `RadioGroupItem` |
 | `Select` | `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, `SelectLabel`, `SelectSeparator` |
@@ -538,25 +894,34 @@ 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) |
 | `useFontStyle(weight?, variant?)` | `{ fontFamily, fontWeight? }` resolved through `setFonts` overrides |
 | `useReducedMotion()` | `true` when the OS asks for reduced motion |
+| `useFocusVisible(options?)` | `{ focused, onFocus, onBlur }` for a `Pressable`; on web `focused` follows `:focus-visible` (keyboard only), so layer `getFocusRingStyle()` while it is true — the gate every kit control uses |
 | `useScalePress(options?)` | Animated style plus `onPressIn`/`onPressOut` for a `Pressable` (`scaleTo`, `haptic`, `disabled`) |
 | `useStaggeredEntrance(options?)` | Entrance animated style for list rows (`delay`; `STAGGER_DELAY` is 30) |
 
 `SsrViewportContext` (from `state`) supplies the first-render viewport width on
-web, where the window cannot be read during export or hydration.
+web, where the window cannot be read during export or hydration. Right after
+hydration `useDimensions()` switches to the real window. On web every consumer
+shares one `resize` listener and one snapshot, re-renders only when the width or
+height changes, and a component that mounts later reads the current viewport
+straight away. The `mrmeg-vw` cookie (the width a server can seed the next
+render from) is written once per page view and then once resizing settles.
 
 ### Patterns And Gotchas
 
 - Use `Button.preset`, not `variant`: `default` is the neutral primary action,
   `secondary` a neutral secondary surface, `outline` lower emphasis, `ghost`
   compact toolbars, `link` text-like commands, `destructive` dangerous actions.
-  Native targets add computed hit slop up to 44px. Nested `StyledText` inherits
-  the Button size, so use `size="sm"` for popover, tooltip, and toolbar
+  Every platform gives a Button a 44pt vertical target: native through computed
+  `hitSlop`, web through a transparent hit extender inside the drawn 28/32/40pt
+  box, so the visual size, layout and popover anchoring do not change; a caller
+  `hitSlop` replaces both (on web it is honoured too). Nested `StyledText`
+  inherits the Button size, so use `size="sm"` for popover, tooltip, and toolbar
   triggers.
 - A plain `View` whose `opacity` or `pointerEvents` follows state (`disabled`,
   `loading`, `checked`, `editable`) must be `collapsable={false}` on Android.
@@ -601,6 +966,18 @@ web, where the window cannot be read during export or hydration.
   rebuild; the sheet warns once in development on Android when the native core
   is older. Web has none. Do not wrap sheet content in another
   `KeyboardAvoidingView`: it would lift twice.
+  `onDismissed` (root prop) fires once per close after the sheet is fully gone;
+  present the next modal — a `Dialog` (an RN `Modal` on iOS), a native stack
+  modal — from it, not from `onOpenChange(false)` or a timer: on iOS the sheet
+  is still dismissing when `onOpenChange` fires and UIKit rejects a `Modal`
+  presented then ("already presenting") with no retry. Detection per platform:
+  iOS uses `@expo/ui`'s native `onDismiss` event, raised by SwiftUI
+  `.sheet(isPresented:onDismiss:)` after the dismissal transition; Android uses
+  `@expo/ui`'s close callback, raised after Material's hide animation for a
+  swipe / back / scrim dismissal and with the removal of the Compose sheet for a
+  prop-driven close (which has no exit animation); web derives it from the HTML
+  `<dialog>`'s `close` event, which `@expo/ui` raises when its exit animation
+  ends (immediately under reduced motion).
   The sheet hosts its content in a separate
   native window outside the app's `DismissKeyboard`, so `BottomSheet.Content`
   mounts its own tap-away keyboard-dismiss boundary on the content column: it
@@ -647,16 +1024,41 @@ web, where the window cannot be read during export or hydration.
   not put `@expo/ui`-hosted controls inside them yet, and do not place a
   `Dialog` inside their content either — it has no view controller to present
   from there; render it at screen level and open it from the item's
-  `onPress`. The iOS Modal is outside `UIProvider`'s root
-  keyboard avoidance, so the dialog owns it there: the centered container is a
-  package `KeyboardAvoidingView` (`behavior="padding"`), the card recenters
-  above the keyboard with its fields and footer visible, and
-  `useKeyboardAvoidance()` is `true` inside dialog content. Do not wrap dialog
-  content in another `KeyboardAvoidingView`. The platform close request
+  `onPress`. Dialog content sits outside `UIProvider`'s root keyboard
+  avoidance on both native platforms (the iOS Modal is presented outside it;
+  the Android portal host is a sibling of it), so the dialog owns keyboard
+  avoidance on iOS and Android: the centered container is a package
+  `KeyboardAvoidingView` (`behavior="padding"`), the card recenters above the
+  keyboard with its fields and footer visible, and `useKeyboardAvoidance()` is
+  `true` inside dialog content. Do not wrap dialog content in another
+  `KeyboardAvoidingView`. Web has no software keyboard and no avoidance owner
+  (`useKeyboardAvoidance()` is `false` there). Dialog content also owns tap-away
+  keyboard dismissal on iOS and Android with the same boundary as
+  `DismissKeyboard` and `BottomSheet.Content`: `Dialog` carries it on the card
+  itself (the primitive's native content claims every touch inside the card so
+  the backdrop's close-on-press never fires there, and that claim would stop a
+  boundary on any ancestor from ever being asked), `AlertDialog` on its
+  centered container. A tap on the card's dead space (padding, labels, the gap
+  between fields and footer) hides the keyboard on release, a `Dialog` backdrop
+  tap closes the dialog and the keyboard with it, and `Close`, `Action`,
+  `Cancel`, buttons and fields still fire on the first tap; no
+  `DismissKeyboard` is needed inside a dialog (inert on web, which has no
+  software keyboard). The platform close request
   (hardware back, TV menu) routes to the root's `onOpenChange(false)`. Android
-  and web render dialog content inline into the portal host, which sits
-  outside the root avoidance, so an Android dialog does not avoid the keyboard
-  yet.
+  and web render dialog content inline into the portal host.
+- `PopoverContent` treats `side` as a preference. On iOS and Android it opens
+  on the other side when the content does not fit and there is more room
+  there, caps its height to the room it gets, and scrolls the children inside
+  that cap; `insets` default to the safe area, so the card stays clear of the
+  status bar and home indicator. Pass `scrollable={false}` when the content
+  brings its own `FlatList` (a VirtualizedList inside a vertical ScrollView
+  warns): the cap still applies, but the popover can no longer measure its full
+  height, so it stays on `side`. A `style` merges over the themed surface
+  (background, border, radius, shadow) instead of replacing it. On web, Radix
+  flips it and the card is capped to the space Radix measures; the primitive
+  cannot pass Radix a collision padding, so a card wider than the room beside
+  its trigger can sit flush against the viewport edge. A `PopoverTrigger` ref
+  (`PopoverTriggerRef`) exposes `open()` and `close()`.
 - `Carousel` renders every child (no virtualization), so slides survive into
   the exported HTML shell and the first client frame; use `FlatList` for large
   or unbounded data. An `itemWidth` below 1 (default `0.85`) is a fraction of
@@ -684,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>
   }
 />
@@ -693,19 +1095,39 @@ import { Drawer, Icon } from "@mrmeg/expo-ui/components";
 ### Quick Examples
 
 ```tsx
-import { Badge, Button, Card, CardContent, CardHeader, CardTitle } from "@mrmeg/expo-ui/components";
-
-<Card variant="outline">
-  <CardHeader>
-    <CardTitle>Subscription</CardTitle>
-    <Badge variant="secondary">Active</Badge>
-  </CardHeader>
-  <CardContent>
-    <Button preset="default" fullWidth>
-      Manage billing
-    </Button>
-  </CardContent>
-</Card>
+import {
+  Badge,
+  Icon,
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemDescription,
+  ItemGroup,
+  ItemMedia,
+  ItemTitle,
+} from "@mrmeg/expo-ui/components";
+
+<ItemGroup title="Subscription" footer="Renews on the 1st of each month.">
+  <Item>
+    <ItemMedia icon="award" />
+    <ItemContent>
+      <ItemTitle>Pro plan</ItemTitle>
+      <ItemDescription>$12 / month</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Badge variant="secondary">Active</Badge>
+    </ItemActions>
+  </Item>
+  <Item onPress={openBillingPortal}>
+    <ItemMedia icon="credit-card" />
+    <ItemContent>
+      <ItemTitle>Manage billing</ItemTitle>
+    </ItemContent>
+    <ItemActions>
+      <Icon name="chevron-right" size={18} color="mutedForeground" />
+    </ItemActions>
+  </Item>
+</ItemGroup>
 ```
 
 ```tsx
@@ -747,23 +1169,45 @@ after 4s (`DEFAULT_NOTIFICATION_DURATION`) unless a `duration` is given;
 auto-dismisses. `position` is `"top"` (default) or `"bottom"`. `globalUIStore`
 stays available for reactive selectors and tests.
 
+A bottom toast renders in the root layout, above every navigator, so a layout
+that owns a bar registers where it ends with `useNotificationOffset` from
+`@mrmeg/expo-ui/hooks`; the toast then sits 8 pt past the larger of the
+safe-area inset and the offset. The offset is measured from the window edge and
+includes the inset, so a JS tab layout passes `useBottomTabBarHeight()` as-is
+and a `NativeTabs` layout passes the platform bar height plus
+`useWindowInsets().bottom`. Pass `null` while the bar is hidden (keyboard up).
+
+```tsx
+import { Tabs } from "expo-router";
+import { useBottomTabBarHeight } from "@react-navigation/bottom-tabs";
+import { useNotificationOffset } from "@mrmeg/expo-ui/hooks";
+
+function ToastOffset() {
+  useNotificationOffset({ bottom: useBottomTabBarHeight() });
+  return null;
+}
+
+// Render <ToastOffset /> inside a tab screen (it must be a descendant of <Tabs>).
+```
+
 ## Package Release
 
 ```sh
-bun run ui:release -- --patch --publish
+bun run pkg ui release -- --patch --publish
 ```
 
-Use `--patch`, `--minor`, `--major`, or an exact version such as `0.2.0`. The
-command updates `packages/ui/package.json` and `bun.lock`, runs
-`bun run packages:peer-check` then the `ui:typecheck`, `ui:test`, `ui:build`,
-`ui:pack`, and `ui:consumer-smoke` gates, and publishes with
-`npm publish --access public` only when `--publish` is present (which also
-requires a working `npm whoami`). Without `--publish` it is the same bump and
-gate run as a dry run.
+Use `--patch`, `--minor`, `--major`, or an exact version such as `0.2.0` (the
+committed version itself releases without a bump). The command updates
+`packages/ui/package.json` and `bun.lock`, runs `bun run packages:peer-check`
+then `bun run pkg ui typecheck`, `test`, and `build`, packs one tarball, runs
+`bun run pkg ui consumer-smoke -- --tarball <that tarball>`, and publishes that
+same tarball with `npm publish <tarball> --access public` only when
+`--publish` is present (which also requires a working `npm whoami`). Without
+`--publish` it is the same bump and gate run as a dry run.
 
 A clean working tree is required; commit first or pass `--allow-dirty`.
 
-CI also installs and exports packed consumers against Expo 56 and 57
+CI also installs and exports packed consumers against Expo 56, 57, and 58
 (`.github/workflows/package-compatibility.yml`).
 
 ### GitHub Publishing
@@ -773,18 +1217,20 @@ publishing:
 
 1. In npm package settings for `@mrmeg/expo-ui`, add a trusted publisher:
    GitHub Actions, owner `mrmeg`, repository `expo-template`, workflow filename
-   `publish-ui.yml`.
+   `publish-packages.yml`.
 2. Bump `packages/ui/package.json` in a commit and push it to `main`.
 
-`publish-ui.yml` runs on a push to `main` touching `packages/ui/package.json`
-and on `workflow_dispatch`, using npm OIDC rather than a checked-in token or
-local npm login. On push it reads the committed version, skips cleanly if that
-version is already published, otherwise runs the gates and publishes from
-`packages/ui`. Manual runs take `version` (`patch`, `minor`, `major`, or exact
-`x.y.z`) and `ref` (default `main`); they bump the version, update `bun.lock`,
-run the gates, publish, then commit and push the bump. If a manual run fails
-after the bump landed, rerun it with the exact current version (e.g.
-`version=0.1.3`) — exact versions do not bump again.
+`publish-packages.yml` publishes every workspace package. It runs on a push to
+`main` that changes a `packages/*/package.json` and on `workflow_dispatch`, using
+npm OIDC rather than a checked-in token or local npm login. On push it releases
+the committed version when that version changed in the push and npm does not
+have it yet, through the same release script as the local command, then
+publishes the smoked tarball with provenance and tags `expo-ui-v<version>`.
+Manual runs take `package=ui`, `version` (`patch`, `minor`, `major`, or exact
+`x.y.z`), and `ref` (default `main`); they bump the version and commit it to
+`ref`, run the gates, publish, and tag. If a manual run fails after the bump
+landed, rerun it with the exact current version (e.g. `version=0.1.3`) — the
+committed version does not bump again.
 
 Keep `repository.url` in `package.json` as
 `git+https://github.com/mrmeg/expo-template.git`: npm trusted publishing checks
@@ -799,31 +1245,40 @@ CI configuration, never in the repository.
 
 ```sh
 bun run packages:peer-check
-bun run ui:typecheck
-bun run ui:test
-bun run ui:build
-bun run ui:pack
-bun run ui:consumer-smoke
+bun run pkg ui typecheck
+bun run pkg ui test
+bun run pkg ui build
+bun run pkg ui pack
+bun run pkg ui consumer-smoke
 ```
 
-`ui:pack` is a dry pack, so the published file list and package size can be
-inspected before release. `ui:consumer-smoke` installs the packed tarball into
-a clean fixture, checks every documented export-map target resolves,
-type-checks all public entrypoints, and runs an iOS `expo export` against the
-packed package at the workspace's Expo version, without a custom Metro config.
+`pkg ui pack` is a dry pack, so the published file list and package size can be
+inspected before release. `pkg ui consumer-smoke` installs the packed tarball
+into a clean fixture, checks every documented export-map target resolves,
+type-checks all public entrypoints, imports the Node-safe subpaths
+(`constants/spacing`, `constants/motion`, `components/keyboardFocusRegistry`,
+`state/notify` with `state/globalUIStore`, `state/SsrViewportContext`) in plain
+Node, and runs iOS, Android, and web `expo export`s against the packed package
+at the workspace's Expo version, without a custom Metro config. The web export's
+source maps must show one copy of React, react-dom, react-native-web, and every
+`@radix-ui/*` / `@rn-primitives/*` module: a consumer install that resolves two
+copies of `@radix-ui/react-slot` crashes the web `AlertDialog` with
+`React.Children.only expected to receive a single React element child`. Pass
+`-- --tarball <file>` to smoke an existing tarball instead of building one.
 
 ### Design-system manifest
 
-`ui:build` also writes `dist/design-system.json`
+`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.
-`ui:consumer-smoke` asserts the packed tarball carries it and that it parses at
+`pkg ui consumer-smoke` asserts the packed tarball carries it and that it parses at
 `schemaVersion: 1` with a non-empty component list. The build fails rather than
 writing an empty manifest, so a broken extractor cannot ship as "no rules to
 enforce".