@oxyhq/bloom 0.89.0 → 1.0.1

package/docs/avatar.mdx

@@ -0,0 +1,126 @@
+---
+title: Avatar
+description: Image avatar with initials fallback, verified badge, and squircle option.
+order: 12
+---
+
+# Avatar
+
+Display a user's avatar. Accepts a URL, an `ImageSourcePropType`, or no image at all — falls back to a colored circle with the first letter of `name` (deterministic per name). Optional verified badge. Optional squircle shape.
+
+## Basic
+
+```tsx
+import { Avatar } from '@oxyhq/bloom';
+
+<Avatar uri="https://cloud.oxy.so/avatars/abc.png" size={48} />
+```
+
+## Initials fallback
+
+```tsx
+<Avatar name="Ada Lovelace" size={48} />
+```
+
+Picks a deterministic background color from the `name` so the same user always gets the same color. White letter on top.
+
+## Verified badge
+
+```tsx
+<Avatar uri={user.avatarUrl} verified size={64} />
+```
+
+Custom badge:
+
+```tsx
+<Avatar uri={user.avatarUrl} verified verifiedIcon={<StarIcon />} size={64} />
+```
+
+## Squircle shape
+
+```tsx
+<Avatar uri={user.avatarUrl} shape="squircle" size={56} />
+```
+
+Requires `react-native-svg`. Matches the iOS app-icon shape — a softened super-ellipse.
+
+## Pressable
+
+```tsx
+<Avatar uri={user.avatarUrl} size={40} onPress={() => navigate('Profile', { id: user.id })} />
+```
+
+Wraps the avatar in `TouchableOpacity` when `onPress` is set.
+
+## Custom placeholder
+
+```tsx
+<Avatar
+  placeholderColor={theme.colors.primary}
+  placeholderIcon={<PersonIcon />}
+  size={64}
+/>
+```
+
+When no `source`, `uri`, or `name` resolves, you can fully control the placeholder.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `source?` | `string \| ImageSourcePropType \| null` | — | Flexible image source. Takes precedence over `uri`. |
+| `uri?` | `string` | — | Direct URI string. |
+| `variant?` | `string` | `'thumb'` | Rendition forwarded to the `ImageResolver` when `source` is a bare file ID. Defaults to `'thumb'` so avatars never request the full-size original; pass an explicit larger variant when you need a bigger image. Ignored for full URL / `{uri}` sources. |
+| `fallbackSource?` | `ImageSourcePropType` | — | Shown when `source`/`uri` errors. |
+| `size?` | `number` | `40` | Diameter in dp. |
+| `verified?` | `boolean` | `false` | Show a verified badge bottom-right. |
+| `verifiedIcon?` | `React.ReactNode` | check icon | Custom badge node. |
+| `shape?` | `'circle' \| 'squircle'` | `'circle'` | `'squircle'` needs `react-native-svg`. |
+| `style?` | `StyleProp<ViewStyle>` | — | Container style. |
+| `imageStyle?` | `StyleProp<ImageStyle>` | — | Image style (circle only). |
+| `placeholderColor?` | `string` | derived | Override placeholder background. |
+| `placeholderIcon?` | `React.ReactNode` | initial | Override placeholder icon/letter. |
+| `name?` | `string` | — | Used to derive initials + a stable background color. |
+| `onPress?` | `() => void` | — | Wraps in `TouchableOpacity`. |
+| `testID?` | `string` | — | |
+
+## Recipes
+
+### Stacked avatars
+
+```tsx
+<View style={{ flexDirection: 'row' }}>
+  {users.slice(0, 3).map((u, i) => (
+    <View key={u.id} style={{ marginLeft: i === 0 ? 0 : -8 }}>
+      <Avatar uri={u.avatarUrl} name={u.name} size={32} style={{ borderWidth: 2, borderColor: theme.colors.background }} />
+    </View>
+  ))}
+  {users.length > 3 ? (
+    <View style={{ marginLeft: -8, /* counter chip */ }}>
+      <Text>+{users.length - 3}</Text>
+    </View>
+  ) : null}
+</View>
+```
+
+### Initials-only (no image)
+
+```tsx
+<Avatar name={user.displayName ?? 'Anonymous'} size={40} />
+```
+
+This is the recommended fallback when you don't have an avatar URL — never show a generic person silhouette unless you also have `placeholderColor` set to something brand-consistent.
+
+### With a status dot
+
+```tsx
+<View>
+  <Avatar uri={user.avatarUrl} size={48} />
+  <View style={{
+    position: 'absolute', bottom: 0, right: 0,
+    width: 12, height: 12, borderRadius: 6,
+    backgroundColor: theme.colors.positive,
+    borderWidth: 2, borderColor: theme.colors.background,
+  }} />
+</View>
+```

package/docs/badge.mdx

@@ -0,0 +1,74 @@
+---
+title: Badge
+description: Counts, dots and status pills — inline, or attached to the thing they are about.
+order: 21
+---
+
+# Badge
+
+`Badge` is a small piece of state about something else: how many unread, which
+status, whether there is anything new. It has two shapes behind one component —
+an inline pill when it has no children, and an overlay pinned to a corner when
+it wraps one.
+
+```tsx
+import { Badge } from '@oxyhq/bloom/badge';
+
+<Badge content="Beta" color="info" variant="subtle" />
+
+<Badge content={5} color="error">
+  <IconCircle icon={BellIcon} />
+</Badge>
+```
+
+## Which prop decides what
+
+| prop        | decides                                                     |
+| ----------- | ----------------------------------------------------------- |
+| `content`   | the label; absent, the badge draws nothing                   |
+| `color`     | the semantic tone                                            |
+| `variant`   | how loudly it is painted — `solid` · `subtle` · `outlined`   |
+| `dot`       | drops the label entirely for a presence marker               |
+| `max`       | caps a number and appends a plus                             |
+| `invisible` | hides the badge **without unmounting the child**             |
+| `placement` | which corner, when it wraps a child                          |
+
+`color` and `variant` are resolved together through `resolveAccentColors`,
+which reads the `*Subtle` / `*SubtleForeground` pairs. That is why a subtle
+badge is legible rather than one colour on the same colour — a tone lightened
+by appending alpha to a token would not be. Concretely: an accent token
+resolves to `rgb(...)`, so hand-appending a hex alpha suffix parses back
+OPAQUE (contrast 1.00, a label on its own colour) rather than translucent —
+`resolveAccentColors` is what makes the pairing legible instead of that.
+
+## Three props that each prevent a specific bug
+
+**`max`** — an unread count is unbounded, and `1204` inside a 20px pill either
+stretches the nav icon off screen or clips. `max={99}` renders `99+`.
+
+**`invisible`** — the reason to prefer this over rendering the badge
+conditionally: when a count reaches zero the child must stay exactly where it
+is. Unmounting the badge is fine; unmounting the wrapper reflows the row.
+
+```tsx
+<Badge content={unread} invisible={unread === 0}>
+  <InboxIcon />
+</Badge>
+```
+
+**`dot`** — a dot has no label to make legible, so it always paints the tone's
+**fill**, whatever the `variant`. Following the variant made
+`dot variant="outlined"` a fully transparent circle: visually absent, with
+markup that reads as correct.
+
+## Accessibility
+
+A badge is decoration for the control it sits on. The count must also be in
+that control's accessible name — a screen reader user should hear
+"Inbox, 5 unread", not "Inbox" and then a stray "5".
+
+```tsx
+<Badge content={5}>
+  <Pressable accessibilityLabel={`Inbox, ${unread} unread`}>…</Pressable>
+</Badge>
+```

package/docs/benefit-list.mdx

@@ -0,0 +1,56 @@
+---
+title: BenefitList
+description: The "icon plus caption" card — what an app is asking for, in a consent step.
+order: 60
+---
+
+# BenefitList
+
+A bordered card of icon-and-caption rows. It is the consent-screen shape: what
+an app is about to get, one line each.
+
+```tsx
+import { BenefitList, BenefitRow } from '@oxyhq/bloom/benefit-list';
+
+<BenefitList accessibilityLabel="What you're sharing">
+  <BenefitRow icon={<PersonIcon size="sm" />} label="Your name and profile photo" />
+  <BenefitRow icon={<LockIcon size="sm" />} label="Your password is never shared" />
+  <BenefitRow icon={<ShieldIcon size="sm" />} label="You can revoke access at any time" />
+</BenefitList>
+```
+
+## Which prop decides what
+
+| prop                 | decides                                            |
+| -------------------- | --------------------------------------------------- |
+| `icon` (row)         | the glyph — required                                |
+| `label` (row)        | the caption, for the common one-line case            |
+| `children` (row)     | rich content instead of a plain label                |
+| `accessibilityLabel` | names the card as a group                            |
+
+## Write what the user gets, not what the API grants
+
+"Your name and profile photo" rather than "profile:read". A consent list is
+read by someone deciding, and a scope name is not a decision they can make.
+
+Say the limits too. "Your password is never shared" is a benefit row precisely
+because it answers the question the user actually has.
+
+## `icon` is required for a reason
+
+A row without a glyph collapses to a bullet list, and the icons are what make
+the list scannable — someone skimming reads the shapes, not the sentences. If a
+row has no natural icon, that is a sign it is prose rather than a benefit.
+
+## Keep the list short
+
+Three to five rows. A consent screen with twelve is not more transparent — it
+is a screen nobody reads, and the important row is buried among the routine
+ones.
+
+## Chrome
+
+The card is [`Card`](/docs/bloom/main/card)'s: the `card` background, a hairline
+border, `shadow-s`, at the `radius-20` rung. It deliberately does **not** clip
+its content, so an Android elevation draws the way it should under a rounded
+view.

package/docs/bottom-sheet.mdx

@@ -0,0 +1,103 @@
+---
+title: BottomSheet
+description: A standalone, draggable bottom sheet built on RN Modal + Reanimated + Gesture Handler.
+order: 4
+---
+
+# BottomSheet
+
+A standalone, draggable bottom sheet built on React Native `Modal` + `react-native-reanimated` + `react-native-gesture-handler`. **Not** based on `@gorhom/bottom-sheet`, so it does not require `BottomSheetModalProvider`.
+
+Use it when the compound `Dialog` API doesn't fit, when you want to avoid the Gorhom dependency, or when you need direct control over scroll, keyboard handling, or detached presentation.
+
+## Basic usage
+
+```tsx
+import { useRef } from 'react';
+import { BottomSheet, type BottomSheetRef } from '@oxyhq/bloom/bottom-sheet';
+
+function Example() {
+  const sheetRef = useRef<BottomSheetRef>(null);
+
+  return (
+    <>
+      <Button onPress={() => sheetRef.current?.present()}>Open</Button>
+
+      <BottomSheet ref={sheetRef} onDismiss={() => console.log('dismissed')}>
+        <Text>Sheet content</Text>
+      </BottomSheet>
+    </>
+  );
+}
+```
+
+## Ref methods
+
+| Method | Description |
+|--------|-------------|
+| `present()` | Open the sheet. |
+| `dismiss()` | Close and call `onDismiss`. |
+| `close()` | Alias for `dismiss()`. |
+| `expand()` | Snap to the upper position. |
+| `collapse()` | Snap to the lower position. |
+| `scrollTo(y, animated?)` | Programmatic scroll within the internal ScrollView. |
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | — | |
+| `onDismiss?` | `() => void` | — | Fires when the sheet finishes closing. |
+| `enablePanDownToClose?` | `boolean` | `true` | |
+| `enableHandlePanningGesture?` | `boolean` | `true` | |
+| `onDismissAttempt?` | `() => boolean` | — | Return `false` to veto a dismiss attempt. |
+| `detached?` | `boolean` | `false` | Float with horizontal margins and rounded corners on all sides. |
+| `showHandle?` | `boolean` | `true` | Toggle the drag handle pill. |
+| `backdropOpacity?` | `number` | `0.5` | Opacity (0–1) of the dimming backdrop once fully visible. |
+| `backgroundComponent?` | `ReactNode` | — | Custom background renderer. |
+| `backdropComponent?` | `ReactNode` | — | Custom backdrop renderer. |
+| `style?` | `StyleProp<ViewStyle>` | — | |
+| `scrollable?` | `boolean` | `true` | When `false`, renders `children` directly without an internal `Animated.ScrollView` wrapper. Required when the sheet's content owns its own scrolling primitive (e.g. `FlatList`). |
+| `manualActivation?` | `boolean` | `false` | When `true`, the body pan uses RNGH's `manualActivation` and only activates when the inner ScrollView is at the top AND the user has moved their finger downward by > 8dp. Recommended for sheets that contain a scrolling region on Android. |
+| `dynamicBackdrop?` | `boolean` | `false` | Backdrop dims proportionally to drag distance — fades from full `backdropOpacity` to 30% as the sheet is pulled down 40% of the screen height. iOS Photos / iMessage look. |
+| `handleComponent?` | `() => ReactNode` | — | Custom drag-handle renderer. Replaces the default 36×5 pill. |
+
+## Patterns
+
+### Sheet with a `FlatList` inside
+
+Use `scrollable={false}` so the BottomSheet doesn't wrap the list in its own ScrollView, plus `manualActivation` so the drag handle remains the dedicated drag-to-dismiss surface while the list owns vertical scroll:
+
+```tsx
+<BottomSheet ref={sheetRef} scrollable={false} manualActivation>
+  <FlatList data={items} renderItem={renderItem} />
+</BottomSheet>
+```
+
+### iOS Photos-style backdrop dim
+
+Combine `manualActivation` (so the inner photo grid keeps scroll ownership) with `dynamicBackdrop` (so the overlay fades as the user pulls down):
+
+```tsx
+<BottomSheet
+  ref={sheetRef}
+  scrollable={false}
+  manualActivation
+  dynamicBackdrop
+  backdropOpacity={0.85}
+>
+  <PhotoGrid />
+</BottomSheet>
+```
+
+### Detached "floating" presentation
+
+```tsx
+<BottomSheet ref={sheetRef} detached>
+  <PromptInput />
+</BottomSheet>
+```
+
+<Callout variant="info" title="Dialog vs BottomSheet">
+If you just need a confirmation flow or a small custom panel, prefer [Dialog](/docs/bloom/main/dialog) — it cross-platforms to a centered modal on web. Reach for `BottomSheet` only when you need direct gesture / scroll control on native.
+</Callout>

package/docs/button.mdx

@@ -0,0 +1,218 @@
+---
+title: Button
+description: The all-purpose Bloom button — variants, sizes, loading state, icons.
+order: 10
+---
+
+# Button
+
+The all-purpose Bloom button. Variants for primary/secondary/inverse/icon/ghost/text actions, three sizes, loading state, optional icons on either side, and full accessibility props.
+
+## Basic
+
+```tsx
+import { Button } from '@oxyhq/bloom';
+
+<Button onPress={save}>Save</Button>
+```
+
+## Variants
+
+```tsx
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="inverse">Inverse</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="text">Text</Button>
+<Button variant="icon" icon={<XIcon />} accessibilityLabel="Close" />
+```
+
+`primary`, `secondary`, and `inverse` get a press-scale animation; the rest don't. `icon` renders as a square hit target — pair it with `accessibilityLabel`.
+
+## The filled variants are glass
+
+`primary` and `destructive` are **tinted glass**: the brand colour at 85% over a `blur(10px)` of whatever is behind them, a hairline of the same colour at full strength, a lit white top rim and a soft drop shadow. The label is the fill's own on-colour, exactly as on the solid button — the pane IS the fill, so it carries the same label.
+
+The glass is the sheen, not the wash. What reads as glass is the rim, the vertical gradient and the hairline; the 15% of the backdrop that shows through is a hint of depth, not the effect itself.
+
+**One measured cost, stated because it is real.** The 15% bleed moves the pane toward the surface under it, which in light mode means lighter — the one direction a white label cannot afford. Of `primary`'s 340 preset × mode × surface combinations, **38 fall below WCAG AA**, in the band 4.17–4.49, all in light mode, on `blue`, `faircoin`, `green`, `lagoon`, `lavender`, `mint`, `olive`, `orange`, `pine`, `plum`, `pumpkin`, `rose`, `sky` and `yellow`. Both solid Button fills pass all 680 rows; glass `destructive` is also unaffected (0/340, worst 5.32). The alpha at which the failures reach zero is 0.89.
+
+The previous 18-preset oracle was exactly 30/180. Those same rows and nine IDs remain unchanged; all eight added failures come from the new recipes. A browser helper briefly printed 45 because it parsed the structured `GLASS_SHEEN.bottom` channel object as CSS. That was drift in the measurement script, not Bloom's shipped baseline and not a threshold relaxed from 45 to 38.
+
+If your app runs one of those fourteen presets in light mode and needs AA on its primary button, use `variant="inverse"` for that call site, or raise `GLASS_FILL_ALPHA`.
+
+Over a retained black/mid-grey/white media sample, **25 of 204** preset × mode × backdrop rows fall below AA, worst 3.61 (`destructive`: 0). That is a sample rather than a promise about arbitrary pixels. If a CTA must be legible over an image, `variant="inverse"` is opaque and backdrop-independent:
+
+```tsx
+<Button variant="inverse">Comprar</Button>
+```
+
+`secondary`, `outline`, `ghost`, `text`, `link` and `icon` are unchanged: they have no fill for the tint to replace.
+
+### On Android the blur is not applied, and it cannot be
+
+Measured on an Android emulator (API 37): the pane paints its tint and the backdrop behind it is **not blurred**. `expo-blur`'s `blurMethod` defaults to `'none'` on Android, and `dimezisBlurView` additionally needs a `blurTarget` ref pointing at a `BlurTargetView` that wraps the content to blur.
+
+The obvious fix — wrap the app in a `BlurTargetView` and hand the ref down — **crashes the app**. A `BlurView` that is a DESCENDANT of the view it points at makes the Android render tree recurse into itself: `SIGSEGV` in `RenderThread`, `RenderNode::prepareTreeImpl` repeating past 500 frames. Reproduced twice, isolated to one target and one pane. A glass `Button` fills its caller and therefore sits inside the content it would need to blur, so the only topology available to it is the one that crashes.
+
+Three topologies, all measured on device (over 10dp stripes, where `std` is the discriminator — the MEAN is nearly identical in every case, so a mean-only comparison reports "no difference"):
+
+| `BlurView` position | result |
+| --- | --- |
+| descendant of its own `blurTarget` | **native crash** |
+| sibling of the target | blurs; std 0.70 vs 11.95 unblurred |
+| inside a `Modal`, target in the root window | blurs; std 0.68, matches the blurred composite to 0.36/255 |
+
+So Bloom asks for no blur method on Android at all. What that costs:
+
+- Over Bloom's own flat surfaces — the documented backdrop range — nothing visible changes. A blur over a uniform colour is a no-op, so the painted pane matched the web composite to **0.75/255**, and every AA number above still holds.
+- Over **textured** content (a photograph, a busy list) the Android pane transmits that texture at 15% instead of smoothing it. The pill clip, the hairline, the rim, the sheen and the drop shadow are all unaffected.
+
+The third row is where an Android blur is still available, and Bloom now takes it — but only for surfaces inside a real RN `<Modal>`, which is the bottom-sheet path and not a `Button`. See `docs/dialog.mdx` for how to switch it on.
+
+**So on Android, "glass" means tint, top sheen, hairline and drop shadow — plus a blur only where a target exists.** A glass `Button` has the first four and never the fifth.
+
+iOS uses `UIVisualEffectView` and needs none of this, but it has not been verified on hardware.
+
+### What a lower alpha would buy, and what it would cost
+
+The recurring question about this material is whether it is transparent enough to be glass at all. `backdrop-filter` only acts on the fraction of the backdrop that gets **through** the pane, so at 0.85 the blur is running at full radius on 15% of the picture. Reproduce the whole trade with:
+
+```bash
+bun run storybook          # the DEV server; the script reads the theme through Vite
+node scripts/measure-glass-alpha.mjs --url http://localhost:6006 --image docs/glass-alpha-sweep.png
+```
+
+![The same button at eleven fill alphas, over a flat page, a photograph and a hard stripe pattern](./glass-alpha-sweep.png)
+
+Measured in Chrome off painted pixels, with the label removed from the measurement clones so a white glyph cannot be mistaken for backdrop:
+
+| alpha | backdrop response | blur delta over a photo (max/mean) | blur delta on a flat page | `primary` rows < AA | `destructive` rows < AA |
+| --- | --- | --- | --- | --- | --- |
+| 0.89 | 28.0 | 13 / 3.5 | 1 | 0 / 340 | 0 / 340 |
+| 0.88 | 31.0 | 15 / 3.8 | 1 | 5 / 340 | 0 / 340 |
+| 0.87 | 33.0 | 16 / 4.0 | 1 | 14 / 340 | 0 / 340 |
+| 0.86 | 36.0 | 17 / 4.4 | 1 | 25 / 340 | 0 / 340 |
+| **0.85** (shipped) | 38.0 | 18 / 4.7 | 1 | 38 / 340 | 0 / 340 |
+| 0.75 | 63.7 | 31 / 7.8 | 1 | 216 / 340 | 68 / 340 |
+| 0.65 | 88.7 | 43 / 10.9 | 1 | 252 / 340 | 340 / 340 |
+| 0.55 | 114.7 | 55 / 14.2 | 1 | 272 / 340 | 340 / 340 |
+| 0.45 | 139.3 | 67 / 17.4 | 0 | 301 / 340 | 340 / 340 |
+| 0.35 | 165.3 | 79 / 20.6 | 1 | 335 / 340 | 340 / 340 |
+| 0.25 | 190.3 | 91 / 23.8 | 1 | 335 / 340 | 340 / 340 |
+
+Everything is out of 255. Backdrop response is how far the painted pane moves between a white and a black backdrop — linear in `1 - alpha`, at 25.4 ± 0.7 per 0.10 of alpha. Blur delta is how much the picture changes when the blur is switched off, which is the honest form of "can you see the blur".
+
+Three things the table settles:
+
+- **On a flat page the blur is worth ~1/255 at every alpha, including 0.25.** There is nothing behind the pane to blur, so lowering the alpha does not make a flat page glassy — it only makes the button paler. That is the whole of the "it doesn't look glassy" complaint, and no alpha fixes it.
+- **Over a photograph the blur is already visible at 0.85** (18/255 peak). Where there is something to see, the shipped material is doing the thing.
+- **Legibility falls off a cliff immediately below 0.85.** One step down takes `primary` from 38 to 216 failures and `destructive` from 0 to 68; two steps down puts every one of `destructive`'s 340 rows under AA.
+
+So there is no single alpha that both matches the reference and reads as glass on a flat surface. That is a property of the material — a blur needs a backdrop — not a constant nobody has tuned yet. To make a specific surface read as glass, put something behind it.
+
+## Sizes
+
+```tsx
+<Button size="small">Small</Button>
+<Button size="medium">Medium</Button>
+<Button size="large">Large</Button>
+```
+
+Heights are 32 / 36 / 44 dp; font sizes 14 / 15 / 16. The height comes from `minHeight` alone — the vertical padding is sized to keep the label's line box underneath it — so a button measures the same on native and on web, and in every variant. The one exception is `text` / `link`, which clears `minHeight` on web so the control hugs its label and sits inline.
+
+Native adds vertical `hitSlop` to bring `small` and `medium` up to a 44 dp touch target; `large` is already there. Horizontal slop is zero, so two buttons in a row cannot steal each other's presses. On web `hitSlop` does not exist and the target is the box: 32 / 36 / 44 px.
+
+## Loading
+
+```tsx
+const [busy, setBusy] = useState(false);
+
+<Button
+  loading={busy}
+  onPress={async () => {
+    setBusy(true);
+    try { await submit(); } finally { setBusy(false); }
+  }}
+>
+  Submit
+</Button>
+```
+
+When `loading` is true, a centered spinner appears, children stay in the layout (hidden) so width doesn't jump, and presses are blocked. `loadingColor` overrides the spinner color (defaults to the resolved text color).
+
+## With an icon
+
+```tsx
+<Button icon={<DownloadIcon />} iconPosition="left">Download</Button>
+<Button icon={<ArrowRightIcon />} iconPosition="right">Continue</Button>
+```
+
+## Disabled
+
+```tsx
+<Button disabled>Can't click me</Button>
+```
+
+`disabled` blocks presses, drops opacity, and removes the press animation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onPress?` | `() => void` | — | Press handler. |
+| `children?` | `React.ReactNode` | — | Button label. Strings are auto-wrapped in `Text`. |
+| `disabled?` | `boolean` | `false` | Blocks presses + drops opacity. |
+| `variant?` | `'primary' \| 'secondary' \| 'inverse' \| 'icon' \| 'ghost' \| 'text'` | `'primary'` | Visual style. |
+| `size?` | `'small' \| 'medium' \| 'large'` | `'medium'` | Padding + font size + min height. |
+| `icon?` | `React.ReactNode` | — | Icon node rendered next to the label. |
+| `iconPosition?` | `'left' \| 'right'` | `'left'` | Which side of the label. |
+| `loading?` | `boolean` | `false` | Show centered spinner, block presses. |
+| `loadingColor?` | `string` | text color | Override the spinner color. |
+| `style?` | `StyleProp<ViewStyle>` | — | Outer container style. |
+| `textStyle?` | `StyleProp<TextStyle>` | — | Label style. |
+| `accessibilityLabel?` | `string` | — | Required for icon-only buttons. |
+| `accessibilityHint?` | `string` | — | |
+| `hitSlop?` | `{ top, bottom, left, right }` | — | Expand the touch target. |
+| `testID?` | `string` | — | RN testing id. |
+| `className?` | `string` | — | NativeWind class (web). |
+
+## Recipes
+
+### Destructive confirmation
+
+```tsx
+<Button variant="primary" style={{ backgroundColor: theme.colors.negative }} onPress={destroy}>
+  Delete forever
+</Button>
+```
+
+For most destructive actions, prefer a `<Dialog>` with `color: 'destructive'` actions over a destructive button in the main flow.
+
+### Submit button with promise
+
+```tsx
+const [busy, setBusy] = useState(false);
+
+<Button
+  loading={busy}
+  onPress={async () => {
+    setBusy(true);
+    try { await save(form); toast.success('Saved'); }
+    catch (err) { toast.error(extractErrorMessage(err)); }
+    finally { setBusy(false); }
+  }}
+>
+  Save changes
+</Button>
+```
+
+### Icon button row
+
+```tsx
+<View style={{ flexDirection: 'row', gap: 4 }}>
+  <Button variant="icon" icon={<BoldIcon />} accessibilityLabel="Bold" />
+  <Button variant="icon" icon={<ItalicIcon />} accessibilityLabel="Italic" />
+  <Button variant="icon" icon={<LinkIcon />} accessibilityLabel="Link" />
+</View>
+```