pixelize-native-library 1.2.1 → 1.3.0

package/COMPONENT-GOTCHAS.md

@@ -0,0 +1,309 @@
+# Component Gotchas
+
+For anyone — human or AI — consuming `pixelize-native-library` in an app, with no access to this
+source repo. Every entry below **typechecks cleanly, accepts what you pass, and produces the wrong
+(or no) result at runtime with no warning.** TypeScript cannot catch any of these, and a snapshot
+test that mocks the library won't either.
+
+This file ships inside the published package
+(`node_modules/pixelize-native-library/COMPONENT-GOTCHAS.md`) so it's available without checking
+out the library's source.
+
+---
+
+## Value ranges & units
+
+### `progress` is 0–100, not a 0–1 fraction
+
+`ProgressBar.value`, `Gantt`'s per-lane `progress`, and `FileUpload.progress` are all a **0–100**
+number, clamped internally (`Math.min(100, Math.max(0, value))` in `ProgressBar.variants.ts`;
+`Math.max(0, Math.min(100, lane.progress ?? 0))` in `Gantt.variants.ts`;
+`resolveFileUploadProgressFraction` divides by 100 in `FileUpload.variants.ts`). Passing `0.45`
+compiles fine and renders a sliver of a fill (~0.45%), not the 45% you meant — no error, no clamp
+warning.
+
+**Apply:** always pass a 0–100 number to these three props, never a 0–1 fraction.
+
+### `BottomSheet.snapPoints` are fractions 0–1, not percentages, and are silently clamped
+
+`resolveBottomSheetSnapOffset` (`BottomSheet.variants.ts:16-21`) clamps every entry to
+`[0.1, 0.95]` before using it. `snapPoints={[50, 90]}` — a natural mistake if you're thinking in
+percent — compiles fine and both values collapse to `0.95`, so the sheet ends up with one
+functional stop instead of two, with no error or warning.
+
+**Apply:** pass fractions (`snapPoints={[0.5, 0.9]}`), never whole-number percentages.
+
+---
+
+## Import surface
+
+### Heavy modules are subpath-only — never on the root barrel
+
+`bottom-nav`, `charts`, `date-picker`, `data-table`, `filter-sheet`, `gantt`, `image-viewer`,
+`reorder`, `rich-text-editor`, and `rich-text` (`HEAVY_MODULES` in `scripts/gen-index.mjs`) are
+deliberately **absent from the root `pixelize-native-library` barrel** so a lazy
+`import { Button } from "pixelize-native-library"` can never drag a chart engine, a calendar grid,
+or a table virtualizer into your bundle. Each still has its own subpath in `package.json`
+`exports`.
+
+```ts
+// Wrong — not exported from the root, fails to resolve
+import { DataTable } from "pixelize-native-library";
+
+// Right — subpath import
+import { DataTable } from "pixelize-native-library/data-table";
+```
+
+**Apply:** if an import from the package root doesn't resolve, check this list before assuming the
+component doesn't exist — it likely just needs its own subpath.
+
+---
+
+## Composing your own layout around library slots
+
+### A library slot silently wraps a bare string; your own `View` won't
+
+Slots that accept `ReactNode` (`Card`/`Section`/`Drawer`/`Accordion`/`Tabs` children, `ChipGroup`
+children, a `MultiSelect` option's `leading`, `BarList`'s icon) route through `renderNodeSlot`
+(`src/core/slot/nodeSlot.tsx`), which wraps a bare `string`/`number` in a `<Text>` for you and
+recurses into arrays — anything else (an already-rendered element) passes through untouched. That
+convenience is local to those library slots; RN itself cannot host a bare text node outside
+`<Text>`. If you get used to dropping a raw string into a library slot and then try the same thing
+inside your own plain `<View>` (or your own wrapper that isn't one of the components above), it
+throws "Text strings must be rendered within a `<Text>` component" instead of silently working.
+
+**Apply:** the "you can pass a raw string here" convenience only applies to the specific library
+slots that call `renderNodeSlot` internally — wrap plain strings in your own `<Text>` everywhere
+else.
+
+---
+
+## Known gotchas (silent failures)
+
+### `Combobox.filterFn` is silently ignored whenever `onSearchChange` is also passed
+
+`filteredOptions` (`Combobox.tsx:387-400`) checks `serverSide` (`= onSearchChange !== undefined`)
+first and returns `options` unfiltered before `filterFn` is ever evaluated — both props are
+independent optionals (`Combobox.tsx:117-127`), so passing both compiles fine and `filterFn` never
+runs.
+
+**Apply:** these are mutually exclusive — `onSearchChange` means you own filtering server-side;
+`filterFn` is only for the client-side path.
+
+### `Card`'s `disabled` / `onLongPress` / `accessibilityLabel` / `accessibilityState` are no-ops without `onPress`
+
+Without `onPress`, `CardImpl` (`Card.tsx:164-195`) renders `StaticCard`, which is only ever given
+`variant`, `style` and `testID` — the other four props are typed on `CardProps` and accepted, but
+never reach the rendered tree.
+
+**Apply:** pass `onPress` (even a no-op) to get the interactive `Card` that actually reads those
+props.
+
+### `showLegend` now defaults to `true` on every chart
+
+`BarChart.tsx:118`, `LineChart.tsx:87`, `DonutChart.tsx:45`, `PieChart.tsx:85` all changed their
+default from `false`/unset to `showLegend = true`. Upgrading consumers who never touched this prop
+get a legend that wasn't there before, with no compile-time signal.
+
+**Apply:** pass `showLegend={false}` explicitly to keep a chart's pre-upgrade look.
+
+### `Breadcrumbs`' `onPress` on the last item is always ignored
+
+`Breadcrumbs.tsx:27,30` only renders a `Pressable` when `item.onPress && !current` — the final
+(current-page) crumb is deliberately never pressable, no matter what `onPress` you attach to it.
+
+**Apply:** don't rely on the last breadcrumb being clickable; wire navigation only on the earlier
+items.
+
+### `FileUpload.values` is dropped unless `onValuesChange` is also passed
+
+`multiMode` (`FileUpload.tsx:233`) is `values !== undefined && onValuesChange !== undefined` — pass
+`values` alone, expecting a pre-populated multi-file list, and it's silently ignored; the component
+behaves as if neither were passed.
+
+**Apply:** always pass `values` and `onValuesChange` together for multi-file mode.
+
+### `Input`'s `secureTextEntry` silently overrides `trailingIcon` / `onTrailingIconPress`
+
+`Input.tsx:236-238` resolves the trailing icon/handler as `secureTextEntryProp === true ? "eye" /
+togglePassword : trailingIcon / onTrailingIconPress` — the password-visibility toggle always wins;
+your own trailing icon and its handler never render, with no warning.
+
+**Apply:** don't combine `secureTextEntry` with a custom trailing icon — they're mutually exclusive.
+
+### `Menu`'s `disabled` stops the menu opening, but the trigger's own `onPress` still fires
+
+`handleTriggerPress` (`Menu.tsx:277-282`) always calls `trigger.props.onPress?.(event)` before
+`openMenu()`, and only `openMenu` (`Menu.tsx:247-251`) checks `disabled`. Any side effect you put on
+your own trigger's `onPress` runs every tap, whether or not the menu is disabled.
+
+**Apply:** if your trigger's own `onPress` has a side effect, gate it on the same `disabled` value
+you pass to `Menu`.
+
+### `DocumentViewer` never renders a document
+
+`DocumentViewer.tsx:9-26` always shows a short explanatory message plus an "Open in browser" button
+that calls `Linking.openURL(uri)` — there is no in-app PDF/doc rendering path today.
+
+**Apply:** treat it as a hand-off to the OS/browser, not an in-app preview.
+
+### `DatePicker.confirmOnSelect`'s doc comment claims a default it doesn't have
+
+The JSDoc on `DatePicker.tsx:40` says tap-to-commit is the default for `mode="date"`; the actual
+default (`DatePicker.tsx:78`) is `confirmOnSelect = false`. The sheet stays open after picking a day
+unless you pass the prop explicitly.
+
+**Apply:** pass `confirmOnSelect={true}` yourself if you want tap-to-commit — don't rely on the
+doc comment's stated default.
+
+### `FilterBar.activeFilterCount` renders nothing unless `onOpenFilters` is also passed
+
+The count badge is nested inside the `{onOpenFilters ? (...) : null}` branch (`FilterBar.tsx:42-49`)
+— pass `activeFilterCount` alone, expecting a bare badge with no Filters button, and nothing
+renders at all.
+
+**Apply:** always pass `onOpenFilters` alongside `activeFilterCount`.
+
+### `PersonChip.subtitle` is dropped when `onRemove` is set
+
+The `onRemove` branch (`PersonChip.tsx:31-40`) renders only an `Avatar` and a `Chip` carrying
+`name` — `subtitle` is never read on that path, even though it's a normal prop the rest of the
+time.
+
+**Apply:** don't rely on `subtitle` showing up once `onRemove` is present; build a custom row if you
+need both.
+
+### `MultiSelectOption` has no `disabled` field
+
+`MultiSelect.tsx:63-67` — the option type is `{ label, value, leading? }` only. A non-literal options
+array carrying an extra `disabled` key still typechecks (TypeScript's excess-property check only
+fires on object literals), and every row stays fully selectable regardless.
+
+**Apply:** filter disabled items out of `options` yourself before handing them to `MultiSelect`.
+
+### `MoreItems.moreCount` only changes the badge text, not what's listed
+
+`resolveMoreItemsCount` (`MoreItems.variants.ts:15-17`) feeds only the "+N" badge number — the
+overflow sheet itself always lists every entry in `items`, regardless of `moreCount`.
+
+**Apply:** slice `items` yourself first if you want the sheet's list to actually be shorter.
+
+### `NumberInput.step` applies only to the +/- buttons, never to typed input
+
+Typed text is parsed and clamped to `[min, max]` (`NumberInput.tsx:139-142`,
+`clampNumberInputValue` in `NumberInput.variants.ts:188`) but never snapped to `step` — only the
+stepper buttons move in `step` increments.
+
+**Apply:** don't rely on `step` for typed-value validation; round/snap it yourself in your
+`onValueChange` handler if alignment matters.
+
+### `OrgSwitcher` renders `null` when there's one org or fewer
+
+`OrgSwitcher.tsx:335` — `if (options.length <= 1) return null;`. Mount it with a single-org account
+and it vanishes entirely (no trigger, nothing), which is easy to mistake for a data-fetch bug.
+
+**Apply:** this is deliberate — don't wrap `OrgSwitcher` in a label/section that would look broken
+with nothing inside it when there's only one org.
+
+### `PlanBadge` and `PlanPill` take an identical prop shape and mean different copy
+
+Both are `{ tier, style, testID }`. `PlanBadge`'s `pro` label is `"Pro"`; `PlanPill`'s is
+`"Pro plan"`. Swapping the import for the other typechecks with zero errors and silently changes
+the copy on screen.
+
+**Apply:** double-check which one you meant — the identical prop shape gives you no signal that
+you grabbed the wrong one.
+
+### `Slider.onSlidingComplete` fires on every keyboard keypress, not once per gesture
+
+`commitValue` (`Slider.tsx:184-188`) — the function that calls `onSlidingComplete` — is invoked from
+both the accessibility increment/decrement handler (`Slider.tsx:198-200`) and the keyboard handler
+(`Slider.tsx:212`), so keyboard/screen-reader users fire it on every single step, not once at
+gesture end the way a touch drag does.
+
+**Apply:** debounce or throttle `onSlidingComplete` if it does anything expensive (an API call,
+persistence) — don't assume "once per interaction."
+
+### `Toast` `tone="danger"` never auto-dismisses unless you pass an explicit numeric `duration`
+
+`resolveAutoDismissDelay` (`Toast.variants.ts:77`) returns `null` (no auto-dismiss) for
+`tone === "danger"` whenever `duration` is left `undefined` — every other tone falls back to the
+default duration. An error toast shown with no `duration` prop stays on screen until manually
+dismissed.
+
+**Apply:** pass a numeric `duration` explicitly if you want a danger toast to auto-dismiss.
+
+### `StatTile`'s `tone` only tints the icon's background chip, never the glyph itself
+
+`resolveStatTileColors` (`StatTile.variants.ts:25-31`) produces `iconFill` for the chip background
+only; the icon element itself is passed through `renderNodeSlot(icon, labelStyle)`
+(`StatTile.tsx:167`), and `renderNodeSlot` only applies a style to a bare string/number — an
+already-rendered icon element passes through with its own color unchanged.
+
+**Apply:** color the icon yourself at the call site if it needs to match `tone`; don't expect `tone`
+alone to recolor the glyph.
+
+### `SwipeableRow` — a non-`danger` action `tone` collapses to `"default"` once folded into the overflow menu
+
+`SwipeableRow.tsx:197` maps every action into the "more" `Menu` with
+`tone: action.tone === "danger" ? "danger" : "default"` — a `warning` (or any other) tone survives
+on the swipe-revealed action itself but reads as plain `default` once it's inside the overflow
+menu.
+
+**Apply:** don't rely on a non-`danger` tone being visually distinct once an action lands in the
+overflow menu.
+
+### `Tooltip` — a plain RN `Text` trigger typechecks but never opens on web
+
+`TooltipProps.children` is typed `ReactElement<TooltipTriggerProps>` (all fields optional), so a
+bare `<Text>` satisfies the type and compiles — but on web, `react-native-web`'s `Text` doesn't
+forward the hover/focus handlers `Tooltip` injects (`Tooltip.tsx:85,199-261`), so it silently never
+opens there. (Native platforms are unaffected — only the web target has no hover/focus channel into
+a plain `Text`.)
+
+**Apply:** always wrap the trigger in a `Pressable` (or another element that forwards
+`onHoverIn`/`onFocus`/etc.), never a bare `Text`.
+
+---
+
+## Fixed in this release — if you're still on an older published version
+
+### `Modal.isLoading` now actually blocks interaction
+
+Before this release, the loading overlay had `pointerEvents: 'none'` (`Modal.tsx:270-277`) — the
+dim scrim and spinner painted, but taps passed straight through to the content underneath.
+`isLoading` is now blocking. If you're on an older version, don't rely on `isLoading` alone to
+prevent a double-submit; also disable the triggering button.
+
+### `Switch`'s `testID` no longer collides when `label` is set
+
+Older versions rendered the same `testID` on both the row wrapper and the inner control when
+`label` was set, so `getByTestId(testID)` matched two elements. The row wrapper now gets
+`${testID}-row`; the inner control keeps the plain `testID` (`Switch.tsx:36,77,95`).
+
+### `StageProgress` no longer renders focusable dead controls
+
+Older versions rendered a focusable `Pressable` per stage even when `onStagePress` was omitted.
+Stages with no `onStagePress` now render as a plain (non-focusable) accessible `View` regardless of
+`readOnly` (`StageProgress.tsx:220,289`).
+
+---
+
+## Colour
+
+### A role colour's lightness direction flips between light and dark mode
+
+`bg.sunken` is **darker** than `bg.surface` in light mode and **lighter** than it in dark mode — see
+[`src/theme/tokens/THEME-CONTRACT.md`](src/theme/tokens/THEME-CONTRACT.md) for the measured numbers
+and the full rule. A component that reasons "sunken means recessed, so it must be darker" gets it
+backwards in dark mode with no error.
+
+**Apply:** never infer a surface's relative lightness from its token name — compare the actual
+resolved colours (or just use `useTheme()`/`useThemeColors()`, which already resolve correctly for
+the active mode).
+
+### Never hardcode a hex
+
+Read every colour from `useTheme()` / `useThemeColors()` (`pixelize-native-library/theme`). A
+hardcoded hex compiles fine and looks right in whichever mode you tested — and is stuck there,
+wrong in the other mode and on every non-default brand.

package/DESIGN-GUIDE.md

@@ -0,0 +1,215 @@
+# Pixelize Mobile Design Guide — how to design a screen with `pixelize-native-library`
+
+For any developer or LLM building UI in a consumer React Native app. `COMPONENT-GOTCHAS.md` (next
+to this file) says **which component does what and where it bites**; this file says **how to compose
+them into a screen that looks designed**. Read both before building a screen. Everything here is
+copyable as-is.
+
+This is the native sibling of `pixelize-design-library` (web). The roles, the 4dp grid and the
+brand palettes are the same; the components are not — nothing here is a Chakra component and there
+is no `className`, no `sx`, no CSS.
+
+```ts
+import { PixelizeProvider, useTheme, useThemeColors } from "pixelize-native-library/theme";
+
+const theme = useTheme();           // theme.colors (roles), space, radii, borderWidths, fontSizes
+const colors = useThemeColors();    // the role map on its own
+```
+
+Wrap the app in `PixelizeProvider` once, at the root. The theme lives on its own subpath — it is
+not on the root barrel.
+
+## 1. The look
+
+Calm, dense, professional. A tool people use all day, not a marketing screen.
+
+- **Hierarchy comes from type and whitespace, not boxes.** One border per surface. Never nest a
+  bordered `Card` inside a bordered `Card`; inside a card, separate with spacing or a `Divider`.
+- **One primary action per screen.** One `<Button variant="solid">`; everything else `outline`,
+  `ghost` or `link`. A `Fab` or a `SaveBar` counts as that one.
+- **Left-aligned and scannable.** Titles and forms left-aligned; numbers right-aligned in tables.
+- **Color means something.** Neutral by default; accent for the primary action and selection;
+  status color only for status. No decorative gradients, no colored section backgrounds.
+- **Borders, not shadows, for resting surfaces.** Elevation belongs to floating things — `Modal`,
+  `BottomSheet`, `Menu`, `Tooltip`, `Fab`.
+- **Touch targets are 44dp.** Anything pressable that is smaller needs `hitSlop`.
+
+## 2. Spacing — `theme.space`, unitless dp, one step = 4dp
+
+| Where | Value |
+| --- | --- |
+| Screen padding | `<Screen padded>` — don't hand-roll it |
+| Between screen sections | `theme.space[5]` (20) |
+| Between cards in a list | `theme.space[3]`–`theme.space[4]` |
+| Inside a card | `Card`'s own padding — don't add more |
+| Between form fields | `theme.space[4]` vertical, `theme.space[3]` side by side |
+| Inline clusters (chips, meta, icon + text) | `theme.space[1]`–`theme.space[2]` |
+
+Never a raw number in a style (`padding: 13`). The one exception is a hairline, which comes from
+`theme.borderWidths`, never from `space` — a hairline must not scale with the user's font setting.
+
+## 3. Radii — `theme.radii`
+
+`none 0 · sm 4 · base 8 · md 12 · lg 16 · xl 24 · full 9999`
+
+`base` (8) is the brand radius: chips, buttons, inputs, small controls. `md`/`lg` for cards, sheets
+and modals. `full` for avatars and pills only — never on something that can stretch to fill a row's
+height, or it renders as a giant oval.
+
+**Nested corners are concentric:** inner radius = outer radius − the padding between them.
+A `radii.md` (12) track with `space[1]` (4) padding holds a `radii.base` (8) pill. Getting this
+wrong is the most visible sloppiness in a mobile UI.
+
+## 4. Color — pick by role, never by ramp
+
+`theme.colors` is a role map. Never read a raw ramp (`primary[500]`) and never write a hex — both
+stay light in dark mode.
+
+| Need | Token |
+| --- | --- |
+| Screen background | `colors.bg.canvas` |
+| A card / list surface | `colors.bg.surface` |
+| A floating surface (modal, sheet, menu) | `colors.bg.raised` |
+| A well / inset area | `colors.bg.sunken` |
+| Pressed or hovered row | `colors.bg.hover` |
+| Selected row | `colors.bg.selected` |
+| Body text | `colors.fg.default` |
+| Secondary text, meta, helper | `colors.fg.muted` |
+| Placeholder in an empty field | `colors.fg.placeholder` |
+| Disabled anything | `colors.fg.disabled` / `colors.bg.disabled` |
+| Hairline between rows | `colors.border.default` |
+| A control's own outline | `colors.border.interactive` |
+| Keyboard/AT focus ring | `colors.border.focus` |
+| Primary button fill | `colors.accent.solid`, label `colors.accent.onSolid` |
+| Accent as text or icon | `colors.accent.text` |
+| Faint accent fill (selected chip) | `colors.accent.subtle` |
+| Status | `colors.status.success \| warning \| danger \| info` — each has `solid`, `onSolid`, `text`, `subtle`, `border` |
+
+**Never pair a solid fill with a hand-picked label color.** `accent.onSolid` is correct on
+`accent.solid` and on nothing else; `status.danger.onSolid` on `status.danger.solid`. Pairing a fill
+with white "because it looks right" is how a badge ships with 1.5:1 text.
+
+Every pairing above is locked by `roleColors.test.ts` across 9 brands × 2 modes. If you need a
+combination the roles don't offer, the role layer is missing something — say so rather than
+inventing a color in a component.
+
+## 5. Type — `Text` and `Heading`, never a raw `fontSize`
+
+| Role | Component |
+| --- | --- |
+| Screen title | `<Heading variant="h1">` |
+| Section / card title | `<Heading variant="h2">` or `<Heading variant="h3">` |
+| Body | `<Text variant="body">` (the default) |
+| Dense body, list rows | `<Text variant="body-sm">` |
+| Label above a control | `FormField`'s `label` — don't hand-build it |
+| Meta, helper, timestamps | `<Text variant="caption" color={colors.fg.muted}>` |
+| Big number on a KPI tile | `StatTile` — pass the value, don't compose it |
+| Eyebrow above a section | `<Text variant="overline">` (`Section` already does this) |
+
+Variants: `display · title · heading · subheading · body · body-sm · caption · label · label-sm ·
+overline`. Use the variant, not `fontSize`. Never render a bare string inside a `View` — RN throws;
+text always lives in a `Text`.
+
+## 6. Screen anatomy
+
+```tsx
+<Screen appBar={<AppBar title="Deals" />} padded state={state} onRefresh={refetch}>
+  <Section label="Pipeline">
+    <StatGrid items={stats} columns={2} />
+  </Section>
+  <Section label="Recent">
+    <ListItem … />
+  </Section>
+</Screen>
+```
+
+| Need | Component |
+| --- | --- |
+| Every screen's shell — safe area, keyboard avoidance, pull-to-refresh, async states | `Screen` |
+| A long list screen — virtualization + paging + refresh | `ListScreen` |
+| Sectioned list | `SectionList` |
+| Top bar | `AppBar` |
+| Tab bar with an overflow sheet | `BottomNav` (subpath) |
+| A labelled block inside a screen | `Section` (takes `label`, not `title`) |
+| A container with a border and padding | `Card` — or `Surface` when you need to pick the role yourself |
+| Search + filter row above a list | `FilterBar`, with `FilterSheet` (subpath) behind it |
+| A dirty-state action bar | `SaveBar` |
+| Confirm / destructive prompt | `AlertDialog` |
+| Anything else floating | `Modal` (centered) or `BottomSheet` (gesture-driven) |
+
+`Screen` handles the safe area and the keyboard. Do not wrap it in another `SafeAreaView`, and do
+not add your own `KeyboardAvoidingView` — you'll get double insets.
+
+## 7. Controls — `sm` for dense screens, `md` everywhere else
+
+`Button` takes `variant="solid" | "outline" | "ghost" | "link"`, `size="sm" | "md" | "lg"` and
+`tone="accent" | "neutral" | "danger"`. Destructive actions are `tone="danger"`, never a hand-set
+red.
+
+Every field goes inside a `FormField` — it owns the label, the required marker, the description and
+the error text, so no screen re-invents that stack. Controls: `Input`, `Textarea`, `Select`,
+`MultiSelect`, `Combobox`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `NumberInput`, `PinInput`,
+`SearchBar`, `SegmentedControl`, and `DatePicker` (subpath).
+
+## 8. Every screen has four states
+
+A screen that only handles "loaded" is unfinished. `Screen` and `ListScreen` take the slots:
+
+```tsx
+<Screen
+  state={isLoading ? "loading" : error ? "error" : rows.length ? "idle" : "empty"}
+  loading={<LoadingState />}
+  empty={<EmptyState title="No deals yet" action={{ label: "New deal", onPress: create }} />}
+  error={<ErrorState title="Couldn't load deals" action={{ label: "Retry", onPress: refetch }} />}
+/>
+```
+
+- **Loading** — `Skeleton` in the shape of the content, not a centered spinner, whenever the layout
+  is predictable. `Spinner` only for a short, indeterminate wait.
+- **Empty** — `EmptyState` with a real next action. "No results" after a filter is a different
+  message from "nothing here yet"; say which.
+- **Error** — `ErrorState` with a retry. Never a bare error string. Both `EmptyState.action` and
+  `ErrorState.action` take `{ label, onPress }` — an object, not a `<Button>` element.
+- **Idle** — the content. `state` is `"idle" | "loading" | "empty" | "error"`; `"idle"` is the
+  loaded screen, and it is the default when you pass no `state` at all.
+
+## 9. Imports
+
+Most components come from the root barrel:
+
+```ts
+import { Button, Card, Screen, Text } from "pixelize-native-library";
+```
+
+**Ten heavy modules are deliberately absent from it** so a `Button` import can never drag in a
+chart engine, a calendar grid, a table virtualizer or a gesture stack. Import those by subpath:
+
+```ts
+import { BottomNav } from "pixelize-native-library/bottom-nav";
+import { DataTable } from "pixelize-native-library/data-table";
+import { LineChart } from "pixelize-native-library/charts";
+```
+
+The ten: `bottom-nav`, `charts`, `data-table`, `date-picker`, `filter-sheet`, `gantt`,
+`image-viewer`, `reorder`, `rich-text`, `rich-text-editor`. A root import of one of these does not
+warn — it simply fails to resolve. Every other module also has its own subpath if you prefer them
+all explicit, and the theme is always `pixelize-native-library/theme`.
+
+## 10. Never
+
+- A hex, an `rgba()`, or a raw ramp value in a screen. Roles only.
+- A raw number for spacing, radius or font size.
+- A bare string inside a `View`.
+- `radii.full` on anything that stretches to a row's height.
+- A solid fill with a hand-picked label color — use the fill's own `onSolid`.
+- Your own `SafeAreaView` or `KeyboardAvoidingView` around a `Screen`.
+- A second bordered container inside a bordered container.
+- A screen with no empty and no error state.
+- Re-implementing a component this library ships. If the owned component can't express what you
+  need, that's a library gap worth reporting — not a reason to hand-roll one in the app.
+
+## 11. Where to look next
+
+- `COMPONENT-GOTCHAS.md` — the traps that compile fine and are wrong at runtime.
+- Each component's props carry one-line JSDoc; your editor shows it on hover.
+- `registry.json` (shipped) lists every module with a one-line description.

package/README.md

@@ -21,8 +21,16 @@ This is **not** tree-shaking. Metro's tree-shaking is experimental, production-o
 by a flag the *consumer app* sets — a library can't turn it on. Package Exports have been stable
 in Metro since 0.79 and work in dev and prod, on bare RN and Expo, with zero config in your app.
 
+## Gotchas
+
+- **Web + Reanimated text** — `Reanimated.Text` typechecks but is `undefined` at runtime on web.
+  Module code must use `AnimatedText` from `core/motion` (`createAnimatedComponent(Text)` at module
+  scope), never `Reanimated.Text`.
+
 ## Docs
 
+- Designing a screen: `DESIGN-GUIDE.md` (shipped in the package)
+- Traps that compile fine and are wrong at runtime: `COMPONENT-GOTCHAS.md` (shipped)
 - Component list and props: `registry.json` (generated)
 - Contributing / API contract: `CLAUDE.md`
 - Playground: `example/` (Expo)
@@ -32,3 +40,39 @@ in Metro since 0.79 and work in dev and prod, on bare RN and Expo, with zero con
 Themes and colours are shared with web by hand-copying one folder: `src/theme/tokens/`.
 It is byte-identical across both repos and hash-gated in CI (`.tokens.sha256`).
 Anything platform-specific lives in `src/theme/platform/`, which is never copied.
+
+### Typography
+
+Inter is opt-in. Register the faces once at startup, then pass `interLoaded` to
+`PixelizeProvider` (otherwise the library uses the system font and logs a dev warning):
+
+```tsx
+import { useFonts } from "expo-font";
+import {
+  Inter_400Regular,
+  Inter_500Medium,
+  Inter_600SemiBold,
+  Inter_700Bold,
+} from "@expo-google-fonts/inter";
+import { PixelizeProvider } from "pixelize-native-library/theme";
+
+const [interLoaded] = useFonts({
+  "Inter-Regular": Inter_400Regular,
+  "Inter-Medium": Inter_500Medium,
+  "Inter-SemiBold": Inter_600SemiBold,
+  "Inter-Bold": Inter_700Bold,
+});
+
+<PixelizeProvider interLoaded={interLoaded}>{/* … */}</PixelizeProvider>;
+```
+
+Override the brand accent (lfour uses `#3a75cf`) with `paletteFromAccent` from
+`pixelize-native-library/tokens`:
+
+```tsx
+import { paletteFromAccent } from "pixelize-native-library/tokens";
+
+<PixelizeProvider
+  palette={paletteFromAccent("#3a75cf", brand, resolvedMode)}
+>
+```

package/lib/module/core/MODULE.md

@@ -1,17 +1,29 @@
-# core
+# core/ — cross-cutting mechanism every module imports
 
-Cross-cutting mechanism every module imports. No feature logic, no components.
+No feature logic, no components.
 
 | Folder | Purpose | Docs |
 |--------|---------|------|
-| `style/` | `LayoutStyle` + the variant resolver (below) + `sx()` (spacing/flex shorthand, below) — published as `pixelize-native-library/style` | this file |
-| `icon/` | shared lucide icon registry (`IconName`, `Icon`; 56 glyphs) — hoisted out of `modules/button/` so every one of the 39 shipped modules reuses one registry instead of re-declaring its own | `icon/MODULE.md` |
-| `a11y/` | shared accessibility hooks (`useReducedMotion`) — hoisted out of `modules/button/` for the same reason | `a11y/MODULE.md` |
+| `style/` | `LayoutStyle` + the variant resolver (below) + `sx()` (spacing/flex shorthand, below) + `concentric()` and the `focusRing*` helpers — published as `pixelize-native-library/style` | this file |
+| `haptics/` | optional `expo-haptics` seam — published as `pixelize-native-library/haptics` and re-exported from the root barrel | `haptics/MODULE.md` |
+| `media/` | optional `expo-document-picker` / `expo-image-picker` / `expo-image` injectors — published as `pixelize-native-library/media` and re-exported from the root barrel | this file |
+| `icon/` | shared lucide icon registry (`IconName`, `Icon`; 74 glyphs) — hoisted out of `modules/button/` so every shipped module reuses one registry instead of re-declaring its own | `icon/MODULE.md` |
+| `a11y/` | shared accessibility hooks — `useReducedMotion`, `useAnnounce` (`announce.ts`/`.web.ts`), `useDismissOnEscape` (`keyboard.ts`/`.web.ts`), label helpers and touch-target maths | `a11y/MODULE.md` |
 | `device/` | the `low \| mid \| high` device tier every motion and list-window decision reads | `device/MODULE.md` |
 | `motion/` | the single global animation gate (`useMotion`, `config.ts`, `usePressState`, presets) | `motion/MODULE.md` |
-| `haptics/` | optional `expo-haptics` seam (`setHapticsModule`, `useHaptics`) | `haptics/MODULE.md` |
 | `list/` | `VirtualList` / `VirtualSectionList` — the one windowed list every list-bearing module renders through (FlashList when the peer is installed, FlatList otherwise) | this file |
 | `heading/` | `HeadingText`/`HeadingView` (typed `aria-level`) + `HEADING_LEVEL` — the fixed level every `accessibilityRole="header"` site needs so `react-native-web` doesn't render it as `<h1>` | `heading/MODULE.md` |
+| `slot/` | `renderNodeSlot` — wraps string/number `ReactNode` in `Text` before a `View` host (internal; not root-barrel exported) | `slot/MODULE.md` |
+| `blur/` | `setBlurModule`/`hasBlurModule`/`getBlurModule` — the optional blur-view seam, injected by the app | this file |
+| `gradient/` | `AccentGradientFill`, `ShimmerGradientFill`, `accentGradientStops`, `shouldRenderGradient`, `darkenHex`, `withAlpha` | this file |
+| `overlay/` | `ModalPortalContext` + `renderWebPortal` — how an overlay escapes its host on web | `overlay/MODULE.md` |
+| `screen-scroll/` | `ScreenScrollContext` + `useScreenScrollY` — the scroll offset a `Screen`'s chrome reads | this file |
+
+## Known gotchas
+
+- **Bare text in `ReactNode` slots** — `ReactNode` allows `string`/`number`; hosting either in a
+  `View`/`Pressable`/etc. crashes at runtime on RN and logs *Unexpected text node* on web. tsc and
+  ESLint do not catch it. Use `renderNodeSlot` from `core/slot` at every View-like slot.
 
 ## Escape-hatch doctrine
 
@@ -106,7 +118,7 @@ Spreading (`{ ...sx({...}), extra: 1 }`) is unaffected — spread always produce
 
 ## `list/` — VirtualList
 
-One windowed list for all 15 list-bearing modules. Device-tier window sizing (`core/device`),
+One windowed list for every list-bearing module. Device-tier window sizing (`core/device`),
 FlashList when the optional peer resolves, FlatList otherwise. `resolveFlashList()` returns `null`
 under Jest by design, so **only the FlatList branch is test-coverable** — the FlashList branch is
 asserted by nothing except its tier→`drawDistance` mapping
@@ -122,9 +134,9 @@ and `getItemLayout` is not passed at all — it has no meaning there. The FlatLi
 five-prop tuning unchanged. FlashList also never passes `separators`, so `renderItem` goes through a
 memoized adapter rather than a cast.
 
-`resolveFlashList()` runs **once at module scope**. It used to `require()` inside a try/catch on
-every render, constructing and catching a module-resolution error per render per mounted list
-whenever the optional peer was absent.
+`resolveFlashList()` runs **once at module scope** — never a `require()` inside a try/catch per
+render, which would construct and catch a module-resolution error per render per mounted list
+whenever the optional peer is absent.
 
 **The prop surface is a curated allowlist, never `{...rest}`.** `core/list` is internal, so it is a
 wider surface than a public module's — but the width is deliberate, and each entry is a prop a
@@ -180,9 +192,3 @@ and is now covered by `__tests__/VirtualSectionList.sections.test.tsx`:
    flattened rows. Given only `itemHeight`, **no** `getItemLayout` is passed — measuring is correct,
    guessing is not. `modules/section-list` currently passes only `itemHeight` and so measures; it
    can opt back into exact offsets by passing its header height.
-
-## Modernization (v1.0.7)
-
-- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
-- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
-- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.