@oxy.so/bloom 3.6.0 → 4.0.0

package/docs/auth-card.mdx

@@ -65,12 +65,12 @@ Fills its (positioned) parent and advances on its own, every `interval` ms (3200
 
 | Part | Value |
 | --- | --- |
-| Card | max 400 (split 880), radius 24, 1px `border-button-default`, `shadow-xs`; padding 24, 32 from `sm` (640) |
-| Surface | light `card`; dark neutral-900 (`background-secondary`) |
+| Card | max 400 (split 880), radius 24, 1px `colors.borderLight`, `shadow-xs`; padding 24, 32 from `sm` (640) |
+| Surface | `colors.card` in both modes |
 | Mark | 20 below |
 | Heading | `title-2-medium` / `body-regular` text-secondary, 6 apart |
-| Form | 24 below the heading, fields 16 apart; CTA primary medium, full width |
-| Links | `body-medium` accent-600 (accent-800 pressed), underlined on hover, offset 3 |
+| Form | 24 below the heading, fields 16 apart; CTA `tone="action"`, `size="md"`, full width |
+| Links | `body-medium` `colors.primarySubtleForeground` (including pressed), underlined on hover, offset 3 |
 | Divider | 20 above and below |
 | Footer | 24 below, centred |
 
@@ -85,3 +85,5 @@ Fills its (positioned) parent and advances on its own, every `interval` ms (3200
 - Provider buttons and the CTA are full pills (Bloom's button radius rule).
 - The default sign-up description is generic ("Start building in a couple of minutes.").
 - `translateZ` has no React Native equivalent: the carousel expresses the depth as the projection it produces (`perspective(850) translateX(t·k) scale(k)`, k = 850/1070), which is exact and runs on native.
+
+The auth palette reads `card`, `backgroundSecondary`, `borderLight`, `textSecondary`, and `textTertiary` directly from the theme. Focus uses `primary`; links use its legible subtle foreground. The submit action uses `tone="action"`; social-provider logos retain their own brand colors.

package/docs/badge.mdx

@@ -132,3 +132,7 @@ that control's accessible name — a screen reader user should hear
   <Pressable accessibilityLabel={`Inbox, ${unread} unread`}>…</Pressable>
 </Badge>
 ```
+
+## Compatibility
+
+The shared `size`, `tone` and `appearance` vocabulary coexists with the previously published family props. Explicit shared props take precedence over legacy spellings; existing size and state callbacks remain supported. New code should prefer the shared vocabulary.

package/docs/bottom-bar.mdx

@@ -0,0 +1,33 @@
+# BottomBar
+
+`BottomBar` composes navigation and an optional action in a single bottom region.
+Its blur paints behind both siblings. The action is outside the navigation's
+scrub detector, so pressing it never selects a tab.
+
+```tsx
+import { BottomBar } from '@oxy.so/bloom/bottom-bar';
+import { Fab } from '@oxy.so/bloom/fab';
+import * as Icons from '@oxy.so/bloom/icons';
+
+<BottomBar
+  items={items}
+  value={destination}
+  onValueChange={setDestination}
+  action={<Fab icon={Icons.RiAddLine} accessibilityLabel="Compose" onPress={compose} />}
+/>
+```
+
+Items use `TabBarItem` (`name`, `label`, `icon`). The bar measures the space its
+parent provides, reserves room for the action, and keeps navigation targets at
+least 44 points wide with horizontal overflow for many destinations. An explicit
+`minimizeProgress` shared value synchronizes navigation and row geometry with
+screen chrome; otherwise it reads the nearest `TabBarMinimizeProvider`.
+
+The root occupies its expanded footprint, including the bottom safe area.
+`Screen.bottomBar` positions it and reserves that footprint for scrolling content.
+`actionBehavior="hide"` (the default) fades out the accessory and releases its width and gap while minimizing, centering the navigation. Upward scroll brings it back. `visible` keeps the accessory available. An action without navigation always stays visible. Hidden accessories are removed from hit testing and accessibility; web also marks the subtree inert to prevent keyboard focus. Reduced motion snaps the geometry. Native keyboard visibility hides
+this bottom region. `material="solid"` removes blur; `translucent` uses the
+available platform material. `maxWidth` defaults to 560 points.
+
+The universal entry uses no Apple-only peers. The specialized `tab-bar` subpath
+continues to provide its native enhancements independently.

package/docs/button-group.mdx

@@ -24,13 +24,13 @@ import { ButtonGroup, ButtonGroupItem } from '@oxy.so/bloom/button-group';
 ## Materials
 
 ```tsx
-<ButtonGroup variant="glass" accessibilityLabel="Page actions">
+<ButtonGroup material="glass" accessibilityLabel="Page actions">
   <ButtonGroupItem iconOnly leadingIcon={RiSearchLine} accessibilityLabel="Search" />
   <ButtonGroupItem iconOnly leadingIcon={RiShare2Line} accessibilityLabel="Share" />
 </ButtonGroup>
 ```
 
-The variant is **inherited** when you do not name it: a `ButtonGroup` inside a floating [`PageHeader`](/docs/page-header)'s `actions` is glass with no prop written on it, and the same group inside a card is solid without one either. An explicit `variant` still wins. The rule and its limits are in [Composition](/docs/composition).
+The material is **inherited** when you do not name it: a `ButtonGroup` inside a floating [`PageHeader`](/docs/page-header)'s `actions` is glass with no prop written on it, and the same group inside a card is solid without one either. An explicit `material` still wins. The rule and its limits are in [Composition](/docs/composition).
 
 On glass:
 
@@ -57,12 +57,14 @@ The item announces its own expanded state on both platforms. A control whose pro
 
 ## Selection
 
-`selected` paints an item with its hover fill and announces it as pressed (`aria-pressed` on web, `accessibilityState.selected` on native). Drive it from state for single- or multi-select toolbars; leave every item unselected for a pure action row. For an animated thumb, use `SegmentedControl`.
+Use `checked` with `onCheckedChange` for a controlled boolean toggle. `onPress` receives the original press event and can be composed with a toggle callback; disabled items call neither.
+
+`checked` paints an item with its hover fill and announces it as pressed (`aria-pressed` on web, `accessibilityState.selected` on native). Drive it from state for single- or multi-select toolbars; leave every item unselected for a pure action row. For an animated thumb, use `SegmentedControl`.
 
 ```tsx
 <ButtonGroup accessibilityLabel="Range">
   {ranges.map((range) => (
-    <ButtonGroupItem key={range} selected={value === range} onPress={() => setValue(range)}>
+    <ButtonGroupItem key={range} checked={value === range} onPress={() => setValue(range)}>
       {range}
     </ButtonGroupItem>
   ))}
@@ -71,7 +73,7 @@ The item announces its own expanded state on both platforms. A control whose pro
 
 ## Sizes and icons
 
-| | medium | small |
+| | md | sm |
 |---|---|---|
 | item height | 34 | 30 |
 | padding-x | 12 | 10 |
@@ -83,16 +85,20 @@ Text is `body-medium` (Inter 14/20 500) through Bloom's typography `Text` — a
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `ButtonGroup.variant?` | `'solid' \| 'glass'` | inherited, then `'solid'` | The material the group paints. |
-| `ButtonGroup.size?` | `'medium' \| 'small'` | inherited, then `'medium'` | Size for every item. |
+| `ButtonGroup.material?` | `'solid' \| 'glass'` | inherited, then `'solid'` | The material the group paints. |
+| `ButtonGroup.size?` | `'md' \| 'sm'` | inherited, then `'md'` | Size for every item. |
 | `ButtonGroup.dividers?` | `boolean` | `solid` → `true`, `glass` → `false` | Hairlines between items. |
 | `ButtonGroup.accessibilityLabel?` | `string` | — | Names the group. |
 | `ButtonGroupItem.onPress?` | `(event) => void` | — | Press handler. Receives the event, so a composed trigger handler can `preventDefault()` it. |
-| `ButtonGroupItem.selected?` | `boolean` | `false` | Hover fill + pressed state. |
+| `ButtonGroupItem.checked?` | `boolean` | `false` | Hover fill + pressed state. |
 | `ButtonGroupItem.disabled?` | `boolean` | `false` | Disabled paint, blocks presses. |
 | `ButtonGroupItem.iconOnly?` | `boolean` | `false` | Square icon-only item. |
 | `ButtonGroupItem.leadingIcon?` / `trailingIcon?` | `BloomIconComponent` | — | Icon components. |
-| `ButtonGroupItem.size?` | `'medium' \| 'small'` | group size | Per-item override. |
-| `ButtonGroupItem.variant?` | `'solid' \| 'glass'` | group material | Per-item override. Rarely needed — the group owns it. |
+| `ButtonGroupItem.size?` | `'md' \| 'sm'` | group size | Per-item override. |
+| `ButtonGroupItem.material?` | `'solid' \| 'glass'` | group material | Per-item override. Rarely needed — the group owns it. |
 | `ButtonGroupItem.hitSlop?` | `number \| {top,bottom,left,right}` | — | Extra touch area. NOT defaulted: items in a group are adjacent, so slop on one overlaps its neighbour. Use it for an item that stands alone in its own island. |
 | `ButtonGroupItem.onLongPress?` / `aria-expanded` / `aria-haspopup` / `accessibilityRole` | | — | The trigger contract, set by an anchored family. |
+
+## Compatibility
+
+The shared `size`, `tone` and `appearance` vocabulary coexists with the previously published family props. Explicit shared props take precedence over legacy spellings; existing size and state callbacks remain supported. New code should prefer the shared vocabulary.

package/docs/button.mdx

@@ -1,318 +1,37 @@
 ---
 title: Button
-description: The all-purpose Bloom button — variants, sizes, loading state, icons.
-order: 10
+description: A shared action recipe across platforms.
+order: 12
 ---
 
 # Button
 
-The all-purpose Bloom button. Variants for primary/secondary/ghost/destructive actions plus inverse/icon/text/link, four sizes, loading state, sized icon components, and full accessibility props.
-
-Both forks read ONE table — `src/button/shared.ts` — for geometry and every state's colours, so native and web cannot drift apart.
-
-## Basic
-
 ```tsx
-import { Button } from '@oxy.so/bloom';
-
-<Button onPress={save}>Save</Button>
-```
+import { Button } from '@oxy.so/bloom/button';
+import { RiAddLine } from '@oxy.so/bloom/icons';
 
-## Variants
-
-```tsx
-<Button variant="primary">Primary</Button>
-<Button variant="secondary">Secondary</Button>
-<Button variant="ghost">Ghost</Button>
-<Button variant="destructive">Delete</Button>
-<Button variant="inverse">Inverse</Button>
-<Button variant="text">Text</Button>
+<Button tone="action" appearance="solid" onPress={save}>Save</Button>
+<Button tone="neutral" appearance="subtle" onPress={cancel}>Cancel</Button>
+<Button tone="danger" onPress={remove}>Delete</Button>
+<Button tone="action" icon={RiAddLine} accessibilityLabel="Add item" onPress={add} />
+<Button tone="action" leadingIcon={RiAddLine} size="lg">Add item</Button>
+<Button href="/help" tone="accent" appearance="plain">Read the guide</Button>
 ```
 
-| Variant | Paint |
-|---|---|
-| `primary` | Top-to-bottom gradient of `primary` (500 → 600). Hover lightens it (400 → 500), press deepens it (600 → 700). Label `primaryForeground`. xs drop shadow. |
-| `destructive` | The same recipe on `negative` / `negativeForeground`. |
-| `secondary` / `outline` | `card` surface, 1px `border`, `text` label, xs drop shadow; hover/press step the surface and border toward the label colour. |
-| `ghost` | The `primarySubtle` tint with its `primarySubtleForeground` label — the policy's own legibility-checked pair; hover/press deepen the tint. |
-| `icon` | `secondary`'s surface as a fixed square (border included), glyph 20 / 16 at medium / small; disabled dims the whole control to 0.6. |
-| `inverse` | White surface, black label — for use over media. |
-| `text` | Borderless `primary` label on a compact 4/8 padding with a hover wash (Bloom-only). |
-| `link` | No container at all — label only, `accent-600` (`linkTone="secondary"`: secondary text), underline (offset 3) on hover, `accent-800` while held. |
-
-### Which variant for which job
-
-The variants overlap, and five families answered the overlap with their own
-component rather than with this list. So, explicitly:
-
-| You want | Use |
-|---|---|
-| The action of the screen | `primary` |
-| A second action beside it | `secondary` |
-| A THIRD, still accent-coloured, action | `ghost` |
-| A destructive action | `destructive` |
-| A neutral ⋯ / × / clear / toggle GLYPH | **`GlyphButton`** (below) |
-| A neutral icon button WITH a surface | `icon` |
-| A transparent LABELLED button | `text` |
-| An action inside running copy | `link` + `linkTone` + `underline` |
+`size` (`xs`, `sm`, `md`, `lg`) and `tone` inherit from `BloomScope`; defaults are `md` and `accent`. `appearance` defaults to `solid`. Appearance controls fill and border, independently of semantic tone. Filled accent and status buttons retain Bloom’s subtle vertical gradient: ramp 500 → 600 at rest, 400 → 500 on hover and 600 → 700 when pressed. Native SVG and web CSS paint the same stops; `support` and `action` preserve their authored semantic fill/foreground pairs; neutral solid buttons retain a gentle gradient between the shared secondary and tertiary surfaces. Outline, subtle and plain appearances use their semantic flat fills.
 
-**`ghost` is not the transparent one.** It paints an accent WASH at rest
-(`accent-100`, dark `accent-900`) with an accent label, and that is the whole
-point of it: it is the low-emphasis member of the ACCENT family. A neutral ⋯ or
-× in it lands tinted, and a destructive action in it draws a RED label on a BLUE
-fill — which is what `track-list`'s selection bar shipped before this was
-written down.
+The Color roles prototype assigns `accent` to identity and links, `support` to contextual emphasis, and `action` to the main CTA. Use `tone="action"` for a task’s Create/Send/Save button and keep secondary controls neutral. `tone="support" appearance="subtle"` can emphasize a related option when that distinction has meaning; it is not a replacement for every secondary button. All eight tones remain available through the shared contract.
 
-**The neutral transparent icon button is `GlyphButton`**, not a `Button`
-variant: it takes an arbitrary diameter, where `Button iconOnly` is pinned to
-the four heights in the size table.
+An `icon` without children makes a square action. Labelled actions use `leadingIcon` and `trailingIcon`, each an icon component receiving width, height and fill. `leading` and `trailing` are custom content slots.
 
-The accent and neutral ramps are rebuilt around the theme colours in OKLCH (`button/shared.ts`), since Bloom presets carry one `primary` rather than a Tailwind ramp. There is NO press scale — a press is the active paint alone — and disabled buttons take their own paint instead of an opacity dip (`icon` excepted).
+`loading` blocks activation while preserving the mounted label's width. `disabled` also blocks activation. A control drawing no text needs `accessibilityLabel`. Native touch targets retain the padding around compact visuals; web has real button, anchor and form semantics (`type="submit"` or `"reset"`). Activation is always `onPress`.
 
-On web the state colours arrive as `--bloom-btn-*` custom properties and are declared only in the adopted stylesheet — an inline `background-color` would silence the `:hover` rule. The gradient variants cross-fade their hover gradient in through `::before`, because `background-image` does not transition. On native the gradient is a `react-native-svg` layer; every gradient stop is an opaque composite, since react-native-svg drops alpha in `stopColor`.
+The pressable is the parent's layout child: `className` and `style` are applied there, without an extra wrapper. Web styles flatten RN style arrays and register their interaction CSS using constructed stylesheets. `asChild` composes an existing web link; disabled state guards the composed handler.
 
-## Sizes
+`CloseButton` remains a semantic dismiss control with a required accessible name and sizes `xs | sm | md | lg`.
 
-```tsx
-<Button size="xs">Xs</Button>
-<Button size="small">Small</Button>
-<Button size="medium">Medium</Button>
-<Button size="large">Large</Button>
-```
-
-| | xs | small | medium | large |
-|---|---|---|---|---|
-| height | 24 | 32 | 36 | 44 |
-| radius | full pill | full pill | full pill | full pill |
-| padding-x | 8 | 8 | 8 | 12 |
-| gap | 2 | 2 | 2 | 2 |
-| icon | 14 | 18 | 20 | 20 |
-| text (`TYPE_SCALE`, Inter) | `caption-1-semibold` | `body-medium` | `body-medium` | `headline-medium` |
-| icon-only | 24 × 24 | 32 × 32 | 36 × (36 + 2 × border) | 44 × 44 |
-
-`large` extends the ramp to the 44 dp touch floor. Bloom keeps every button-like control a full pill. Height is fixed and the label's line box is centred inside it, so a bordered variant measures the same as a filled one. A medium icon-only button is NOT forced square — its width is content (8 + 20 + 8) plus the border, so a `secondary` one is 38 × 36; small and xs are forced squares. `text` / `link` drop the fixed height on web so the control hugs its label and sits inline.
-
-Native adds vertical `hitSlop` to bring every size up to a 44 dp touch target; 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.
-
-## Loading
-
-```tsx
-const [busy, setBusy] = useState(false);
-
-<Button
-  loading={busy}
-  onPress={async () => {
-    setBusy(true);
-    try { await submit(); } finally { setBusy(false); }
-  }}
->
-  Submit
-</Button>
-```
+See [Component contract](./appearance.mdx) for inheritance and [Migration](./coherent-system-migration.mdx) for the clean API cut.
 
-When `loading` is true, a centered spinner appears, children stay in the layout (hidden) so width doesn't jump, presses are blocked, and the button keeps its resting paint. `loadingColor` overrides the spinner color (defaults to the label color).
+## Compatibility
 
-## With icons
-
-Pass icon COMPONENTS, not elements — the button sizes and colours them for the current size and state:
-
-```tsx
-import { RiAddLine, RiArrowRightLine } from '@oxy.so/bloom/icons';
-
-<Button leadingIcon={RiAddLine}>New</Button>
-<Button leadingIcon={RiAddLine} trailingIcon={RiArrowRightLine}>Both sides</Button>
-<Button iconOnly leadingIcon={RiAddLine} accessibilityLabel="New" />
-```
-
-Use Remix icons (`RiAddLine`, `RiArrowRightLine`, `RiDeleteBinLine`…). `iconOnly` renders the icon-only shape from the table above and drops the label — name it with `accessibilityLabel`. `icon` takes either a component (sized like `leadingIcon`) or a pre-rendered node, which the button does not size.
-
-## IconButton, LinkButton, CloseButton
-
-Three more companions to `Button` (a fourth, `GlyphButton`, has its own section
-below), exported from the same family:
-
-```tsx
-<IconButton icon={RiMore2Line} accessibilityLabel="More" />          // 36, glyph 20
-<IconButton icon={RiMore2Line} size="small" accessibilityLabel="More" /> // 32, glyph 16
-
-<LinkButton trailingIcon={RiArrowRightSLine}>Browse components</LinkButton>
-<LinkButton variant="secondary" href="/docs">Docs</LinkButton>
-
-<CloseButton size="md" accessibilityLabel="Close" onPress={close} />
-```
-
-- `IconButton` is `<Button variant="icon">` and still accepts every `Button` prop (existing call sites keep working).
-- `LinkButton` is `<Button variant="link">`; its `variant` is the link COLOUR (`primary` | `secondary`). Sizes medium / small / xs use `body-medium` / `body-medium` / `caption-1-semibold` with 20 / 18 / 14 icons and a 4px gap.
-- `href` (any `Button`) renders a real `<a href>` on web and drops the `href` while disabled; on native a press opens the URL unless `onPress` is set.
-- `CloseButton` is a round `background/tertiary` disc (16 / 20 / 24 / 32) with a two-stroke X drawn per size in its own viewBox, so the stroke is a literal pixel value (1.6 / 2 / 2 / 2.5); the glyph turns `text/primary` on hover (held press on native). The control draws no text, so `accessibilityLabel` is required.
-
-## Inline text actions
-
-```tsx
-// The underline IS the affordance, at the reading colour: a "Clear all",
-// a "Show more", a price row's label, a listing's "128 reviews".
-<Button variant="link" linkTone="text" underline="rest" textVariant="body-semibold">
-  Clear all
-</Button>
-
-// The underline as the pointer cue, in the accent (the `link` default).
-<Button variant="link">Learn more</Button>
-```
-
-| Prop | Values | Default |
-|---|---|---|
-| `underline` | `rest` · `hover` · `none` | `hover` for `link`, `none` otherwise |
-| `linkTone` | `primary` (accent-600) · `secondary` (neutral-500) · `text` (the reading colour) | `primary` |
-| `textVariant` | any `TYPE_SCALE` step | the size's own step |
-
-`linkTone="text"` is `colors.text` at rest, `colors.textSecondary` under a
-pointer or a press, `colors.textTertiary` disabled — the tone for an action that
-sits inside a sentence and must not read as the accent. It is the only tone
-whose HOVER changes the label colour; on web that arrives as
-`--bloom-btn-fg-hover` and the hover rule falls back to the rest colour for
-every other variant.
-
-`underline="hover"` is web-only by nature: native dispatches no hover, so the
-underline never appears there. Reach for `rest` when the underline has to be
-visible on a phone.
-
-`textVariant` replaces the four TYPE fields the size picked (size, line height,
-weight, tracking) and nothing else — the height, padding, gap and icon size stay
-the size's. Use it rather than `textStyle`: a `lineHeight` NUMBER in a style
-object is CSS's unitless multiplier on web, so a ramp step passed that way
-renders at twenty times its size.
-
-`numberOfLines={1}` truncates a label with an ellipsis instead of clipping it
-(`.bloom-btn` is `white-space: nowrap; overflow: hidden`, so a long label was
-cut with nothing to say so). Native honours any count; web honours `1`.
-
-`accessibilityRole` overrides the announced role — `link` with no `href`, for a
-control that navigates through the app's own router. Prefer `href`, which
-renders a real anchor and is the only spelling middle-click and copy-link
-understand.
-
-## GlyphButton
-
-The round glyph-only control at an ARBITRARY size — the neutral, transparent
-⋯ / × / shuffle / clear affordance.
-
-```tsx
-import { GlyphButton } from '@oxy.so/bloom/button';
-
-<GlyphButton icon={RiMoreFill} accessibilityLabel="More options" onPress={open} />
-<GlyphButton size={40} icon={RiShuffleLine} accessibilityLabel="Shuffle"
-             pressed={shuffle} onPress={() => setShuffle(!shuffle)} />
-```
-
-|  | off | on (`pressed`) |
-|---|---|---|
-| rest | `color` — `textSecondary` | `activeColor` — the accent |
-| hover / press | `hoverColor` — `text` | `activeHoverColor` — `activeColor` |
-| fill | `fill` — none | the same |
-| fill, hover / press | `hoverFill` — the neutral wash (neutral-100, dark 800) | the same |
-
-All four corners are spellable because the on-state and the hover state are
-independent: a player's lit shuffle still brightens under the cursor.
-
-- **`size`** is the diameter (default 36); the glyph is **0.6 × the box**
-  (`GLYPH_BUTTON_GLYPH_RATIO`), and **`glyphSize`** overrides it. Across the five
-  family-local copies this replaced the ratio ran 0.50 to 0.75; 0.6 is the middle
-  of that range, and every call site that measured differently passes its own.
-- **`pressed`** makes it a TOGGLE and emits `aria-pressed` AND
-  `accessibilityState.selected` — react-native-web drops `accessibilityState`,
-  React Native has no `aria-pressed`. Leave it undefined for a plain button:
-  `aria-pressed="false"` on one announces a state nobody set.
-- **`accessibilityLabel` is required** — the control draws no text, so nothing
-  else can name it.
-- **`ring`** is the focus ring's colour (default the accent). Pass a light one on
-  a surface Bloom does not own — artwork, a player bar — or the ring disappears
-  exactly where a keyboard user needs it.
-- **`disabled`** blocks the press, sets `aria-disabled` and
-  `accessibilityState.disabled`, and dims the control to `disabledOpacity`
-  (0.5).
-- **`children`** replaces `icon` with a node you paint yourself; as a FUNCTION it
-  is handed the resolved foreground, so a text glyph still follows hover and the
-  toggle. **`grow`** turns the box into a minimum width for exactly that case.
-- **`decoration`** is an extra absolutely-positioned layer over the box — the
-  media player's 4px active dot. The family owns its geometry.
-
-Colour change only, 150ms, no scale. Focus is a 2px ring at a 2px offset, on
-`:focus-visible` so a mouse press leaves none behind.
-
-## Disabled
-
-```tsx
-<Button disabled>Can't click me</Button>
-```
-
-`disabled` blocks presses and switches to the variant's disabled paint.
-
-## 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, disabled paint. |
-| `variant?` | `'primary' \| 'secondary' \| 'ghost' \| 'destructive' \| 'outline' \| 'inverse' \| 'icon' \| 'text' \| 'link'` | `'primary'` | Visual style. |
-| `size?` | `'xs' \| 'small' \| 'medium' \| 'large'` (+ `sm \| md \| lg \| icon`) | `'medium'` | Height, radius, padding, type and icon size. |
-| `leadingIcon?` | `BloomIconComponent` | — | Icon component before the label, sized by the button. |
-| `trailingIcon?` | `BloomIconComponent` | — | Icon component after the label. |
-| `iconOnly?` | `boolean` | `false` | Square icon-only button. |
-| `icon?` | `React.ReactNode \| ComponentType` | — | Icon component (sized) or pre-rendered node next to the label. |
-| `linkTone?` | `'primary' \| 'secondary' \| 'text'` | `'primary'` | Colour of the `link` variant; `text` is the reading colour. |
-| `underline?` | `'rest' \| 'hover' \| 'none'` | `hover` for `link`, else `none` | When the label carries its underline. |
-| `textVariant?` | `TypeScaleVariant` | the size's step | Override the label's type-ramp step. |
-| `numberOfLines?` | `number` | — | Truncate the label. Web honours `1`. |
-| `accessibilityRole?` | `'button' \| 'link'` | derived from `href` | Override the announced role. |
-| `href?` | `string` | — | Renders an anchor on web; opens the URL on native. `target` / `rel` pass through on web. |
-| `iconPosition?` | `'left' \| 'right'` | `'left'` | Which side of the label `icon` goes. |
-| `loading?` | `boolean` | `false` | Show centered spinner, block presses. |
-| `loadingColor?` | `string` | label 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. |
-
-## Recipes
-
-### Destructive confirmation
-
-```tsx
-<Button variant="destructive" 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="secondary" iconOnly leadingIcon={RiBold} accessibilityLabel="Bold" />
-  <Button variant="secondary" iconOnly leadingIcon={RiItalic} accessibilityLabel="Italic" />
-  <Button variant="secondary" iconOnly leadingIcon={RiLink} accessibilityLabel="Link" />
-</View>
-```
+The shared `size`, `tone` and `appearance` vocabulary coexists with the previously published family props. Explicit shared props take precedence over legacy spellings; existing size and state callbacks remain supported. New code should prefer the shared vocabulary.

package/docs/card.mdx

@@ -19,7 +19,7 @@ different surfaces, and the radius scale has rungs precisely so they can differ.
 ```tsx
 import { Card, CardHeader, CardBody, CardFooter, CardTitle, CardDescription } from '@oxy.so/bloom/card';
 
-<Card variant="outlined" radius="radius-16">
+<Card appearance="outline" radius="radius-16">
   <CardHeader>
     <CardTitle>Weekly digest</CardTitle>
     <CardDescription>Sent every Monday at 09:00.</CardDescription>
@@ -28,30 +28,32 @@ import { Card, CardHeader, CardBody, CardFooter, CardTitle, CardDescription } fr
 </Card>
 ```
 
+`tone` inherits from `BloomScope` and defaults to `neutral`. Neutral solid cards use the card surface token; semantic tones use Bloom’s paired foreground and fill recipe.
+
 ## Which prop decides what
 
 | prop        | decides                                                          |
 | ----------- | ---------------------------------------------------------------- |
-| `variant`   | the preset combination of background, border and elevation        |
+| `appearance`   | the preset combination of background, border and elevation        |
 | `radius`    | the corner, as a **rung of the `RADIUS` scale** — never a number  |
 | `border`    | `none` · `hairline` (0.5px) · `thin` (1px)                        |
 | `elevation` | `none` · `s` (a subtle raise) · `m` (the overlay role)            |
 
-`variant` is only a named default for the other three. An explicit `border` or
+`appearance` is only a named default for the other three. An explicit `border` or
 `elevation` wins, in both directions — you can add a shadow to `plain` and take
-one away from `elevated`. That is deliberate: a surface that is "an outlined
+one away from `solid`. That is deliberate: a surface that is "an outlined
 card but flatter" should refine the axes rather than earn a fifth variant name.
 
 ```tsx
-<Card variant="plain" border="hairline" elevation="m" radius="radius-20" />
+<Card appearance="plain" border="hairline" elevation="m" radius="radius-20" />
 ```
 
-## Variants
+## Appearances
 
-- `plain` — the bare `card` surface: no border, no shadow.
-- `elevated` — `shadow-s`. The default.
-- `outlined` — a 1px border in the `border` role.
-- `filled` — paints from `backgroundSecondary` instead of `card`, for a surface
+- `plain` — transparent, with no border or shadow.
+- `solid` — `shadow-s`. The default.
+- `outline` — a 1px border in the `border` role.
+- `subtle` — paints from `backgroundSecondary` instead of `card`, for a surface
   that sits **on** a card rather than being one.
 
 ## `radius` is a rung, not a number

package/docs/chart-cards.mdx

@@ -74,19 +74,16 @@ All of it snaps under the OS reduced-motion setting.
 
 ## Colour
 
-| | light | dark | Token |
-|---|---|---|---|
-| card | neutral-100 | neutral-900 | `background-secondary-default` |
-| label, legend | neutral-500 | neutral-500 | `text-secondary` |
-| caption, ticks | neutral-400 | neutral-600 | `text-tertiary` |
-| last year | neutral-300 | neutral-800 | `chart-neutral` |
-| line cursor | neutral-300 | neutral-700 | `chart-cursor` |
-| bar cursor | neutral-200 | neutral-800 | `chart-track` |
-| rising delta | success 200 / 800 | success 950 at 60% / 500 | `status-lime` |
-| falling delta | negative 200 / 800 | negative 950 at 60% / 500 | `status-rose` |
-| flat delta | neutral-200 / 500 | neutral-800 / 500 | `background-tertiary` / `text-secondary` |
-
-The series hues — lime (`chart-2`) for revenue, indigo (`chart-9-active`) for orders — keep Tailwind's lightness and take their chroma ratio and hue distance from `blue-500` re-anchored on the theme's `primary`: a Tailwind-blue brand reproduces those hues exactly, any other preset rotates both hues with it. A chart hue is data, not status, so it does not follow `success` (whose deep green would paint a heavy teal line). The delta chips are status and do.
+Cards read `theme.colors.card`; labels and ticks use the semantic text roles.
+Delta badges consume the paired `successSubtle`/`successSubtleForeground` and
+`errorSubtle`/`errorSubtleForeground` colours. Inset tiles use the surface role.
+
+Series read `theme.chartColors`, generated from the same `--chart-1` through
+`--chart-9` tokens as CSS, each with a matching `-active` token. The original
+five series remain stable; four additional hues are interleaved. Monochrome
+presets separate series by lightness. Revenue uses series 2 and orders series 9.
+Explicit series colours still take precedence. Data categories are independent
+of success/warning/error; only delta and status indicators use status colours.
 
 ## Accessibility
 
@@ -147,7 +144,7 @@ Hovering clears whenever recharts reports no active tooltip: over the axes the c
 
 ## Colour
 
-Series tones follow the `CHART_TONES` order — `chart-2` lime, `chart-6` blue, `chart-5` purple, `chart-3` pink, `chart-8` yellow, `chart-7` emerald, `chart-4` sky, `chart-1` teal — 400 as the fill, 500 as `-active`, each re-anchored on the theme's `primary` like the dashboard cards (a Tailwind-blue brand reproduces those tones exactly). A series `color` overrides; without an `activeColor` it is darkened 18% towards black (`color-mix(… 82%, black)`).
+Series use the canonical nine-colour palette in token order. A series `color` overrides it; without an `activeColor`, the supplied colour is darkened 18% towards black.
 
 | | light | dark | Token |
 |---|---|---|---|

package/docs/chat-list.mdx

@@ -135,12 +135,20 @@ One list, two affordances:
   row travels with the finger and snaps open past 40% of the pane, closed below;
   while a pane is open, pressing the row closes it rather than opening the chat.
   The gesture fails on vertical travel, so a list scroll never becomes a swipe.
-- **Web** — the same actions appear as icon buttons over the right column on
-  hover and on keyboard focus, because a drag is undiscoverable with a mouse.
+  It is `SwipeRow`, the library's one drag implementation — see
+  [Swipe Row](/docs/swipe-row).
+- **A mouse** — the same actions appear as icon buttons over the right column on
+  hover and on keyboard focus, because a drag is undiscoverable with a pointer.
   They are hidden entirely under `@media (hover: none)`.
 
-`swipeEnabled` defaults to "on wherever the platform is not web"; set it to
-`false` to keep the hover buttons and drop the gesture.
+`swipeEnabled` defaults to `useSwipeAvailable()` — every touch pointer on any
+platform, which includes a web build running on a phone. Set it to `false` to
+keep the hover buttons and drop the gesture, or to `true` to force it.
+
+A swipe is not reachable by keyboard or by a screen reader. On web the hover
+buttons are that second path (they appear on `:focus-within` and are in the tab
+order); on native this family offers none, and a host that needs one should give
+the row a long-press menu of the same actions.
 
 `tone` paints the pane: `accent`, `negative` (delete), or the default neutral.