@oxy.so/bloom 3.6.0 → 4.1.0

package/docs/carrier-quote.mdx

@@ -0,0 +1,121 @@
+---
+title: Carrier quote
+description: A carrier's offer on a job, and the offers together — the identity, the price, the window and the ETA, the cheapest and fastest marks, and the empty and loading states of a list that is still filling up.
+order: 135
+---
+
+# Carrier quote
+
+```tsx
+import { CarrierQuoteCard, CarrierQuoteList } from '@oxy.so/bloom/carrier-quote';
+
+<CarrierQuoteList
+  quotes={quotes}
+  selectedId={accepted}
+  onAccept={accept}
+  onMessage={openThread}
+  onDecline={decline}
+/>
+```
+
+## The card is a record of a person
+
+An offer is a **person with a number attached**, so the card is drawn in the
+register Bloom draws a person in — the same blocks in the same order as a contact
+record, with the price where a record puts its headline figure:
+
+```
+mark      the 48 avatar
+identity  the name at title-3-semibold with the verified glyph, then ONE meta
+          line: the list's marks, the rating, the jobs done, the trade line
+headline  the price at title-1-medium in tabular figures, right-aligned
+tiles     pick-up, arrival, vehicle — value over label, on the next fill up
+message   what the carrier wrote, three lines then truncated
+price     the itemisation, collapsed, through PriceSummary
+footer    decline · message · accept, over a hairline
+```
+
+`density="compact"` is a **list row**, not a card with the padding taken out: 64
+tall, a 36 mark, the name, one meta line, the price at the end, and no tiles or
+breakdown at all — a list that draws a card per row has stopped being a list.
+
+**The marks sit on the meta line, never beside the name.** A pill states a fact
+in one word and must not shrink; the name beside it is what gives way, and at 390
+that left `Maris…` next to a full-width `Cheapest`.
+
+### The card is not one big button
+
+`onPressCarrier` is bound to the **identity block**; the three actions sit outside
+it. A control inside a control is invalid on web and ambiguous everywhere, and it
+renders perfectly well either way, which is why it needs saying.
+
+### The actions never lose their names
+
+Each action is a `Button`. Under 420 of the card's **own** width they drop to
+`iconOnly`, and each one is named `"<action> <carrier>"` whichever way it is
+drawn — losing the label must not lose the name. The same measurement stacks the
+tiles two by two, because a card too narrow for three tiles is too narrow for
+three labelled buttons beside a 48 mark.
+
+## The marks belong to the SET
+
+`cheapest` and `fastest` are statements about a group of offers. A card handed
+one out of context is claiming something it cannot know, so it does not derive
+them: `CarrierQuoteList` computes them with `markCarrierQuotes` and passes them
+down.
+
+They are derived from `priceValue` and `etaMinutes` — **numbers the app supplies
+for comparison and this family never draws.** Money arrives here as a
+pre-formatted string (`price`, `priceNote`, every `priceLines` amount) and
+nothing in this family parses, sums, converts or rounds it; the numeric fields
+exist only so the list can ask which of two is smaller.
+
+**Every offer tied at a minimum is marked.** Two offers at the same price are
+both the cheapest; picking one of them would be this component inventing a
+tie-break the app never asked for, and marking neither would hide a true
+statement.
+
+**A quote with no number cannot be marked, and sorts last.** Within that group
+the caller's own order is kept — there is nothing left to sort on, and
+re-shuffling a group of equals makes a list jump for no visible reason.
+`sortCarrierQuotes` is stable for the same reason.
+
+`rating` sorts high-first; price and ETA sort low-first. That is the only place
+the direction differs, and it is a property of what the number means.
+
+## The list's two non-list states
+
+- **loading** draws placeholder cards of the same height, inside an
+  `aria-busy` group. Not a spinner: the answer arriving is a list, and a list is
+  what should be reserved for it.
+- **empty** draws a tinted glyph disc over one line of explanation and the
+  caller's own action. An empty offers list is a **wait**, not a failure, so the
+  default copy says what happens next rather than what went wrong. Pass
+  `emptyTitle` / `emptyDescription` when it is a failure.
+
+## Traps
+
+- **There is no head until there is a list.** "0 offers" over a control that can
+  reorder nothing is chrome for a list that does not exist yet, and the empty
+  state already says the same thing in words a reader can act on.
+- **`quotes.length` is the count, not `ordered.length`.** The heading counts what
+  the caller has, which is the same number either way today — but it is the
+  caller's set that a "3 offers" line is about.
+- **The sort is uncontrolled by default.** Pass `sort` + `onSortChange` to own
+  it; `sortOptions={[]}` draws no control at all, which is right for a list of
+  two.
+- **`selected` moves a pixel of border and gives it back.** The chosen card takes
+  a 2px accent border and drops its own inset by one, so nothing inside it moves
+  when it is chosen.
+- **`vehicleIcon` has no default.** A marketplace routing five bodies has five
+  glyphs, and Bloom's icon set has no generic one that is honest about all of
+  them, so a caller that names none gets no glyph rather than the wrong vehicle.
+- **A tile the quote does not answer is not drawn.** A tile holding an em dash is
+  a slot that failed to load.
+
+## Tracking is not here
+
+Once an offer is accepted the job is tracked with
+[`order-status`](/docs/order-status) — `OrderStatusBar` for the live line and
+`OrderStatusTimeline` for what has happened. This family draws no timeline; the
+`EndToEnd` story shows the three families in one screen.

package/docs/cart-panel.mdx

@@ -0,0 +1,76 @@
+---
+title: Cart Panel
+description: The basket — the vendor it belongs to, lines with their options and a stepper, a minimum-order warning, a tip picker, a promo code field, and the totals drawn by price-breakdown.
+order: 136
+---
+
+# Cart Panel
+
+`@oxy.so/bloom/cart-panel`
+
+What is in the basket, and what it costs.
+
+```tsx
+import { CartPanel } from '@oxy.so/bloom/cart-panel';
+
+<CartPanel
+  vendorName="Fig & Ember"
+  vendorPhoto="fig-ember-cover"
+  vendorMeta="25–35 min · €1.90 delivery"
+  lines={lines}
+  onLineQuantityChange={setQuantity}
+  onLineRemove={remove}
+  tip={{ options: TIPS, value: tip, onValueChange: setTip }}
+  promo={{ value: code, onChangeText: setCode, onApply: apply, applied }}
+  summary={{ lines: priceLines, total: { label: 'Total', amount: '€52.00' } }}
+  onCheckout={checkout}
+/>
+```
+
+The family also publishes its parts — `CartLine`, `CartTipPicker`, `CartPromoField` — for a screen that arranges them itself.
+
+## It is content, not a surface
+
+Inline in a desktop sidebar it is dropped in a `Card`; on a phone it is what a `BottomSheet` holds. It paints no background of its own and claims no edge, so the same tree works in both. Every colour it *does* paint is read **relative to whatever it was dropped on** (`styles/surface-levels.ts`): a hairline picked for a card disappears on a sheet, and a panel that hardcoded one would be right in exactly one of the two places it ships.
+
+## There is one breakdown, and it is `PriceSummary`
+
+`summary` is handed straight to `price-breakdown`'s `PriceSummary`: subtotal, delivery, service, discount, tip and total are `PriceLine`s the app formatted. Nothing in this family adds anything up — the minimum-order `message` is a sentence the app wrote, not a subtraction performed here.
+
+**A note on the duplicate that exists.** `booking/PriceBreakdown` and `price-breakdown/PriceSummary` are the same idea in two spellings: rows with a label and a right-aligned tabular amount, a discount tone, a hairline, a bold total, and no arithmetic in either. `PriceSummary` is the later and larger one — it has the estimated/pending states, the per-line info popover, the collapsible disclosure and the surface-relative paint — so it is the one this family composes, and `booking`'s is the one to fold in. A third was never an option.
+
+## A basket belongs to one vendor
+
+Which is why the vendor is a header and not a field on every line. Switching vendor is a different action — it empties the basket — and this component does not offer it.
+
+## The stepper does not remove
+
+`CartLine`'s stepper has a floor of **1**, and removing is its own control with its own accessible name. A stepper that deletes the line when you press `−` once too often is a destructive action hiding behind an arithmetic one, and it has no label saying so.
+
+The line is never pressable, which is what lets its controls live inside it: a pressable `Item` is a real `<button>` on web, and a control inside one is invalid HTML whose click also fires the row. Editing a line's options is `MenuItemOptions` in a sheet, opened from the dish rather than from a row that is mostly controls.
+
+## The promo field has two states, not one
+
+While `applied` is set the input is **replaced** by a removable pill. A field still holding a code that has already been accepted invites a reader to press Apply again and wonder why nothing happened. Apply is disabled while the field is blank — an action that can only fail teaches a reader to distrust it — and whether a code is *valid* is the app's to say, which it says by handing back `error` or `applied`.
+
+Both states are a `Field`, so the rejection message is wired to the input through `aria-describedby` and the group paints invalid, rather than a red line sitting nearby with no association.
+
+## The tip is a `SegmentedControl`
+
+`type="radio"`, at the `large` rung — which is 44 tall, the floor a touch target has. It is already a `radiogroup` of `radio`s that reads a `Field`, slides its thumb and carries one focus ring; a row of pills would be a second grouped-choice control with the same meaning, and the one thing it could not do is announce "2 of 4".
+
+Every amount is a label the app formatted. A percentage and a fixed amount are the same thing here, and "No tip" is an option like any other rather than a state this component invents.
+
+## The shortfall sits above the totals
+
+Not at the top. Read before there is a total to compare it to, "€4.50 more to reach the €14 minimum" is a sentence about nothing; beside the number it is about, it is the reason checkout is blocked. It is an `Admonition` in the warning tone, with an optional `Meter` under it — never a bar drawn by hand.
+
+## Order tracking is not here
+
+Once the order is placed it belongs to `order-status`: `OrderStatusTimeline` for the steps and `OrderStatusBar` for the live line with its ETA. This family draws no second timeline, and the courier's own card is not one of its components — the `AfterCheckout` story composes one from `Avatar` and `Card` to show the seam.
+
+## Traps
+
+- **Every amount is a string.** `price` on a line is the line's own total, already multiplied by `quantity` **by the app**. Nothing here multiplies, converts or rounds.
+- **The empty basket hides everything after the lines.** No tip picker, no promo field, no totals and no checkout button — each of them would be a control acting on nothing.
+- **`CartLine` takes the line's fields, not the entry.** `CartLineEntry` carries the `id` the panel keys and reports by; the standalone component takes the rest, so a caller cannot pass an id that reaches nothing.

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.
 

package/docs/chat-people.mdx

@@ -47,6 +47,7 @@ with `onSelectedChange`, an action button with `onAction`, nothing otherwise.
 | `subtitle`              | the quiet second line — a handle, a last-seen string      |
 | `actionDone`            | swaps the button for a quiet "Added" mark                 |
 | `size`                  | `'medium'` 44px avatar (default), `'small'` 36 for a picker |
+| `horizontalInset`       | Avatar/text inset, default `10`. Use `0` when the surrounding widget already provides its inset. |
 
 ### Selection is ONE target
 
@@ -275,3 +276,21 @@ and its refusal to jump to an absent letter, the role badges, and both pure
 functions. It cannot see whether the sticky headings actually stick, whether the
 rail is reachable with a thumb, or whether the story chrome stays legible over a
 bright photo. Those are browser and device checks.
+
+
+### Application identity in ContactRow
+
+`avatarSlot` replaces `AvatarPresence`; `identitySlot` replaces the visible name/subtitle block. Both accept React nodes, including `null` to intentionally omit that content. The row retains its flexible identity column, trailing action and selection behavior. Provide an appropriately sized avatar; the defaults are36px for `small` and44px for `medium`.
+
+```tsx
+<ContactRow
+  id={user.id}
+  name={user.displayName}
+  subtitle={user.handle}
+  avatarSlot={<VerifiedAvatar user={user} />}
+  identitySlot={<UserName user={user} showFederation />}
+  onPress={openProfile}
+/>
+```
+
+`VerifiedAvatar` and `UserName` are application components. Keep `name` as plain text: it still supplies the accessible name for selection and action buttons; pressable rows also include `subtitle`. Slots preserve application verification, federation and placeholder logic without duplicating those policies inside Bloom. Keep slot content non-interactive when the row itself is an interactive target.

package/docs/chat-screen.mdx

@@ -162,47 +162,53 @@ inside it.
 
 ### Measured contrast
 
-A bubble is an OPAQUE fill, so the wallpaper never gets between a fill and its
-own label — **bubble text contrast is a property of the bubble**, and it does not
-move with the wallpaper. What a wallpaper CAN do is stop a bubble being told
-apart from the page. So the number that matters is the SEPARATION between a
-bubble fill and the worst pixel a variant can paint behind it, and that needs the
-extremes, not an average.
+A bubble is an opaque fill: its label contrast does not move with the
+wallpaper. Wallpaper separation is a different measurement, between that fill
+and the background behind it. **Checking the darkest and lightest endpoints
+of a photograph does not cover all its pixels**: an intermediate pixel can
+have exactly the bubble's luminance.
 
-Measured over 16 presets × light and dark (32 themes), against an incoming bubble
-(the chrome surface) and an outgoing one (accent-500):
+Measured over the 16 named presets × light and dark in
+`ChatBackgroundContrast.test.ts`, against actual incoming `colors.card` and
+outgoing `colors.primary` fills:
 
 | what                                          | worst  | best  |
 | --------------------------------------------- | ------ | ----- |
-| incoming bubble text over its own fill        | 13.82  | —     |
-| outgoing bubble text over its own fill        | 4.55   | —     |
-| date-pill text over the pill                  | 4.71   | —     |
-| bubble ↔ `plain` wallpaper (the baseline)     | 1.07   | 1.11  |
-| bubble ↔ `pattern` wallpaper                  | 1.07   | 1.11  |
-| bubble ↔ `gradient` wallpaper                 | 1.07   | 1.11  |
-| bubble ↔ `image` wallpaper (dimmed)           | 1.12   | 1.24  |
-
-Both text figures clear WCAG AA (the incoming one clears AAA). **No variant
-separates worse than the bare page**, and the dimmed image variant separates
-BETTER than it — that is what the dim is for, not taste. The figures are pinned
-as equalities in `ChatBackgroundContrast.test.ts`, so a recipe change goes red in
-either direction.
-
-Two decisions fall out of the measurement, and both are counter-intuitive:
-
-- **The image dim is toward a mid-light neutral, not toward white.** White
-  dimmed toward white is white, which is the card colour — a white incoming
-  bubble over a bright photo then separated by exactly **1.00**, i.e. not at all.
-  The gate keeps that as a negative control.
-- **The gradient's stops move AWAY from the page, never toward the card**:
-  darker than the page in light, lighter in dark. The first recipe brightened a
-  light page and put its lightest pixel onto the incoming bubble's own colour —
-  16 of 32 themes separated worse than no wallpaper at all.
-
-The floating surfaces (the date pill, the two jump buttons) are deliberately NOT
-in that measurement: their separation reaches 1.00 in the worst case — a dark
-patterned wallpaper IS the pill's own surface colour — which is exactly why every
-one of them carries a 1px hairline. A bubble has no such rule to fall back on.
+| incoming bubble text over its own fill         | 9.47   | —     |
+| outgoing bubble text over its own fill         | 4.55   | —     |
+| date-pill text over the pill                   | 8.84   | —     |
+| bubble ↔ `plain` wallpaper endpoints           | 1.10   | 1.57  |
+| bubble ↔ `pattern` wallpaper endpoints         | 1.10   | 1.57  |
+| bubble ↔ `gradient` wallpaper endpoints        | 1.10   | 1.57  |
+| bubble ↔ `image` wallpaper endpoints (dimmed)   | 1.17   | 1.65  |
+
+Opaque bubble labels clear AA; incoming text clears AAA. Generated pattern and
+gradient endpoints retain at least the bare-page separation. The image case
+has a recorded limitation: `yellow/dark` has poorer endpoint separation than
+the plain page, and **all 16 dark themes have an image luminance interval that
+contains a bubble fill's luminance**. A photograph can therefore produce
+separation **1.00** at an intermediate pixel. The test pins both named sets and
+the endpoint ranges as equalities; it does not assert full-image separation.
+The default dim remains `0.55` light / `0.62` dark, preserving photo visibility.
+Caller-supplied stops, ink, opacity or images need their own visual check.
+
+Historical hazards remain relevant:
+
+- White dimmed toward white stays white: for the monochrome light card this
+  removes the incoming bubble edge completely (**1.00**). The negative control
+  retains that case; the light image dim uses a mid-light neutral instead.
+- The original gradient brightened a light page toward the incoming card;
+  **16 of 32 themes** then separated worse than the page. With the current tonal
+  ladder, dark pattern ink and gradient stops must also move darker, away from
+  the raised card. Reusing the old dark brightening direction reduced separation.
+- Before the tonal ladder and exact-primary migration, measured incoming text
+  was **13.82**, pill text **4.71**, generated endpoints **1.07–1.11**, and image
+  endpoints **1.12–1.24**. The former image-is-safer claim covered endpoints only;
+  it never proved a continuous photograph could not match a bubble.
+
+Floating date and jump controls carry a 1px hairline because wallpaper can
+match their surface. Their old measured separation of **1.00** on a dark
+pattern remains the reason for that border; it is not a bubble-text failure.
 
 ## `ScrollToBottomButton` and `JumpToMentionButton`
 

package/docs/checkbox.mdx

@@ -44,21 +44,21 @@ const [checked, setChecked] = useState(false);
 
 ## Sizes and colour
 
-`size` is `small`, `medium` (default) or `large`. `color` overrides the accent the checked gradient is built from; it defaults to the theme primary, and the mark on top of it resolves to that preset's readable foreground rather than a hardcoded white (a caller `color` falls back to white).
+`size` is `sm`, `md` (default) or `lg`. `tone` selects the shared semantic fill and its paired mark foreground; it defaults to `accent`.
 
 ## What it looks like
 
 Geometry and colours, the latter run through the shared recipe (the `button/shared.ts` ramps).
 
-|         | `small` | `medium` | `large` |
+|         | `sm` | `md` | `lg` |
 | ------- | ------- | -------- | ------- |
 | box     | 14      | 16       | 20      |
 | label   | `body-2-medium` 13/18 | `body-medium` 14/20 | `headline-medium` 16/22 |
 | gap     | 6       | 8        | 8       |
 
-`large` extends the ramp beyond the standard two sizes. The box has a 4px radius. Label and description are set in Inter from the type ramp (`TYPE_SCALE`), not the platform face.
+`lg` extends the ramp beyond the standard two sizes. The box has a 4px radius. Label and description are set in Inter from the type ramp (`TYPE_SCALE`), not the platform face.
 
-- **Unchecked** — the card surface, a 1px neutral-300 border and the `xs` shadow (dark: neutral-800 fill, neutral-700 border). Hover darkens the border one stop.
+- **Unchecked** — the themed card surface, a 1px semantic border and the `xs` shadow.
 - **Checked / mixed** — an accent-500 → accent-600 gradient with an inset white top highlight and an inset 1px accent edge; hover lightens it to 400 → 500. The tick draws itself in over 200ms (skipped under reduced motion); the mixed state is a rounded bar.
 - **Disabled** — the BOX drops to 50% opacity. The label stays at full strength.
 - No press scale. On native, where there is no hover, a held press shows the hover paint.
@@ -103,13 +103,13 @@ in one field is the `multiple` case — see [Field](/docs/field).
 
 ## Touch target
 
-The box is 16dp at the default size, well under what a finger needs. The pressable is grown to 44dp with `hitSlop` — the target grows, the drawing does not — and the slack is derived per size, so `large` does not overshoot into a neighbouring row.
+The box is 16dp at the default size, well under what a finger needs. The pressable is grown to 44dp with `hitSlop` — the target grows, the drawing does not — and the slack is derived per size, so `lg` does not overshoot into a neighbouring row.
 
 For a labelled checkbox the pressable already spans the label, so the whole row is the target.
 
 ## Keyboard focus on web
 
-The pressable takes a `:focus-visible` ring, drawn from the same shared recipe every Bloom control's web CSS is built from. The browser focuses the row — the box AND its label — but the ring is drawn around the BOX whenever that row has keyboard focus — `ring-2 ring-offset-2`: a 2px accent ring outside a 2px **white** offset. The offset is white in dark mode too; that is Tailwind's default `ring-offset-color`, left un-overridden; the row's own outline is suppressed so there is exactly one ring, and it is only ever shown for the focused row.
+The pressable takes a `:focus-visible` ring, drawn from the same shared recipe every Bloom control's web CSS is built from. The browser focuses the row — the box AND its label — but the ring is drawn around the BOX whenever that row has keyboard focus — `ring-2 ring-offset-2`: a 2px accent ring outside a 2px offset matching the scoped page background; the row's own outline is suppressed so there is exactly one ring, and it is only ever shown for the focused row.
 
 `:focus-visible`, not `:focus`: a mouse click never leaves a ring behind.
 

package/docs/checkout-summary.mdx

@@ -0,0 +1,90 @@
+---
+title: Checkout summary
+description: Review and confirm — the rows a buyer checks before paying, each showing its chosen value and opening the thing that changes it, the totals from price-breakdown, and one confirm control that cannot place two orders.
+order: 137
+---
+
+# Checkout summary
+
+Between "I want this" and "it is ordered" there is one screen: where it goes, when, how
+it is paid, what it costs, and the note to the seller. This family is that screen's body.
+
+```tsx
+import { CheckoutSummary } from '@oxy.so/bloom/checkout-summary';
+
+<CheckoutSummary
+  address={{ title: 'Home', subtitle: 'Carrer de l’Om 14, 2nd floor', kind: 'saved', onPress: pickAddress }}
+  delivery={{ label: 'Delivery window', value: 'Friday 24, 17:00 – 19:00', onPress: pickWindow }}
+  payment={<PaymentMethodRow onPress={pickCard} />}
+  note={{ label: 'Note for the shop', placeholder: 'Add a note', onPress: editNote }}
+  price={{ lines, total: { label: 'Total', amount: '€49.62' } }}
+  confirm={{ amount: '€49.62', terms: 'By placing this order you agree to the shop’s terms.', busy, onConfirm: place }}
+/>;
+```
+
+## The row is the summary AND the trigger
+
+A label with a "Change" button beside it is two targets for one decision, and two screen
+reader stops that do not mention each other. Here the whole row is the button: its name is
+`"<label>: <value>"`, its hint is what pressing it opens, and the chevron is decoration.
+A row with no `onPress` draws no chevron and is a static receipt line — which is what the
+same component is after the order is placed.
+
+**Known gap: the hint is NATIVE ONLY.** react-native-web has no `accessibilityHint` — not
+a wrong mapping, no mapping at all — so on web the affordance is the `button` role and the
+chevron, and the row says nothing about what pressing it opens. It is pinned in the suite
+rather than hidden, and it is not swapped for an `aria-describedby` because native would
+then announce the same sentence twice.
+
+The row reads label-first and value-below (`caption-2-bold` uppercase over `body-medium`),
+which is the other way round from `SettingsListItem`'s title-with-a-value-on-the-right.
+The difference is length: a settings value is a word, and a checkout value is an address,
+a two-hour window and a masked card number — none of which fits in the right half of a
+390 row without truncating the thing the reader came to check.
+
+## What this family does not own
+
+- **The totals are `price-breakdown`'s `PriceSummary`**, passed straight through as
+  `price`. There is no second breakdown here and no arithmetic anywhere: every amount is
+  a string the app formatted, including the one on the confirm button.
+- **The address row is `address`'s `AddressRow`.** It goes inside the summary row's value
+  column with `leading={null}` — the row already drew the gutter, which is the case
+  `AddressRow` documents — and with `Item`'s padding reset in the LONGHANDS `Item` itself
+  writes, so there is one row's chrome rather than two. (Overriding `paddingVertical`
+  with `paddingTop`/`paddingBottom` would have worked on native and been silently
+  dropped on web, where the atomic sheet ranks the shorthand higher whatever the array's
+  order.)
+- **`payment` is a SLOT**, not data. The payment-method row is its own family; a
+  placeholder drawn here would be a second spelling of it. An app that has no such family
+  yet renders a `CheckoutSummaryRow` in the same register, which is what the stories do.
+- **Tracking, afterwards, is `order-status`**, and the screen that says it worked is
+  `order-confirmation`.
+
+## The group publishes its surface
+
+The rows sit in a group one rung above whatever the summary was dropped on, and that rung
+is PUBLISHED with `SurfaceLevelProvider`. Without it every row's glyph tile resolves one
+step off the PAGE rather than one step off the group, and the tiles disappear into the
+group on exactly the surfaces where a summary is most often put — a sheet, a panel, a
+card.
+
+## Two guards against a double order
+
+`busy` is the app's: while the order is in flight the button spins, is renamed to
+`busyLabel`, and drops every press. That is not enough on its own. A press calls
+`onConfirm`, the app sets its state, and `busy` only arrives on the NEXT commit — the
+second tap of a double-tap lands inside that window and places a second order. So
+`CheckoutConfirm` also latches on its own press, synchronously, in a ref: React state
+would not do, because two presses in one tick read the same render's value.
+
+The latch clears on the first commit where `busy` is false again. An app that never sets
+`busy` — a confirm that navigates away, a story — therefore gets exactly one press per
+tick and is never wedged; an app that does sets the button inert for the whole flight.
+
+## The amount is on the button
+
+The number a press commits to and the press are one decision. A total elsewhere on the
+screen and a button reading "Place order" are two, and the gap between them is where a
+reader confirms a figure they last saw before a tip picker changed it. The separator is a
+middle dot: "Place order - €49.62" reads as a subtraction at a glance in a row that is
+otherwise full of money.

package/docs/chip.mdx

@@ -147,3 +147,7 @@ The `:focus-visible` ring is the accent ramp's 500, the colour every other ring
 ## A pill does not shrink
 
 In a flex row of chips — a filter bar, a tag list — each pill keeps its size and the row overflows, rather than every label squeezing into an ellipsis to make room. Inside one pill, the label yields first: a chip narrower than its own text ellipsises rather than spilling past its radius.
+
+## 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/coherent-system-migration.mdx

@@ -0,0 +1,58 @@
+---
+title: Coherent system migration
+description: Shared component contracts and composition alongside the current APIs.
+order: 2
+---
+
+# Coherent system migration
+
+This integration adds a shared vocabulary while retaining the current Button, field, Chip, Badge and AppShell APIs. The table shows the preferred spellings for new code, not a list of removed props. Explicit shared props win over compatibility presets. Existing AppShell variants, slots and drawer behavior remain supported; passing a navigation model selects the adaptive composition.
+
+| Previous usage | Replacement |
+| --- | --- |
+| `size="small/medium/large"`, duplicate aliases | `size="sm/md/lg"` |
+| Button `variant="primary"` | `appearance="solid" tone="accent"` |
+| Button `variant="secondary"` | `appearance="outline" tone="neutral"` |
+| Button `variant="destructive"` | `appearance="solid" tone="danger"` |
+| Button `variant="ghost"` | `appearance="subtle"` |
+| Button `variant="text/link"` | `appearance="plain"`; add `href` for navigation |
+| `PrimaryButton`, `SecondaryButton`, `GhostButton`, `OutlineButton`, `TextButton`, `DestructiveButton`, `LinkButton` | `Button` with explicit semantic props |
+| `IconButton`, `iconOnly`, `size="icon"` | `Button icon={IconComponent}` with no children |
+| `InverseButton` | Explicit scoped colors or a themed surface; no implicit white control over unknown media |
+| Button `onClick` | `onPress` |
+| Button `aria-label` | `accessibilityLabel` |
+| Button `fullWidth` | `style={{ width: '100%' }}` or layout class |
+| Icon elements in managed icon slots | Icon components; custom nodes go in `leading` / `trailing` |
+| Semantic badge/chip `color` | `tone`; `default → neutral`, `primary → accent`, `error → danger` |
+| Badge/chip `variant` | `appearance`; `outlined → outline` |
+| `isInvalid` | `invalid` |
+| Field `onChangeText` | `onValueChange` |
+| Switch `value/onValueChange` | `checked/onCheckedChange` |
+| Radio/RadioCard `selected/onSelect` | `checked/onValueChange`; selection callback receives the option value |
+| SegmentedControl `onChange` | `onValueChange` |
+| DataTableSearch `onChangeText` | `onValueChange` |
+| Chip / ButtonGroupItem `selected`; FrostedIconButton `active` | `checked`; optionally use `onCheckedChange` for a controlled toggle. `onPress` remains the action callback |
+| Card `variant="elevated/filled/outlined/plain"` | `appearance="solid/subtle/outline/plain"`; `elevation` remains an independent override |
+| FrostedIconButton icon element or `children` alias | `icon={IconComponent}`; size and active-state `tone` inherit from `BloomScope` |
+| Menu item `variant="default/destructive"` | `tone="neutral/danger"` |
+| ButtonGroup / ButtonGroupItem `variant="solid/glass"` | `material="solid/glass"`; the shared island and inherited control surface are preserved |
+| ControlSurface `density="medium/small"` | `density="md/sm"`; item heights remain 34/30 |
+| ThemeToggle `appearance`, `ThemeToggleAppearance` | Structural `variant`, `ThemeToggleVariant` |
+| FAB `placement/offset/zIndex/minimizeBehavior` | Still supported; prefer parent composition with `Screen` / `BottomBar` for new screens |
+| Implicit Expo Router root | Universal `BloomProvider` from the provider subpath; explicit `scrollAdapter` |
+| Sidebar `flat` | `surface="plain"`; choose `surface="card"` for a detached rounded panel or `surface="docked"` for an edge-attached square column |
+| AppShell `drawer`, `drawerOpen`, `onDrawerOpenChange` | `navigationPlacement="auto"` or explicit `bottom` / `rail` / `sidebar`; existing drawer state remains supported |
+| AppShell with an already scrolling list | `scroll="external"`; `VirtualList screen={{ active, restoration }}` |
+| FAB `variant`, numeric `size`, icon element | Still supported alongside `tone` / `appearance` and `size="xs/sm/md/lg"` |
+
+The shared vocabulary is `size: xs|sm|md|lg`, `tone: neutral|accent|support|action|success|warning|danger|info`, and `appearance: solid|subtle|outline|plain`. `BloomScope` inherits size and tone only; component props win. Appearance, interaction state, callbacks and navigation selection stay local. Visual sizes remain family-specific. Do not mechanically apply the control scale to image aspect ratios, chart data, typography roles, or platform-native props such as `ActivityIndicator.size`.
+
+## Navigation
+
+`AppShell` accepts a destination model with `value`, `label`, and `icon`, a selected `value`, and `onValueChange`. `navigationPlacement="auto"` chooses bottom navigation below 768, rail from 768 through 1023, and sidebar from 1024. Breakpoints use the measured shell width. Set `bottom`, `rail`, or `sidebar` to override. `primaryAction` takes Fab props and travels with the navigation. `navigationMaterial` selects `solid` or `translucent`. For a standalone screen, `Screen.primaryAction` takes a React node; when using a BottomBar directly, supply `action={<Fab ... />}`.
+
+AppShell persists around route Screens: routes inherit navigation motion and bottom clearance while keeping independent scroll offsets. A covering modal uses `Screen navigationScope="isolated"`. Use one scroller per content region. `ScreenScrollView` is for normal content; virtualized lists bind to the screen without being wrapped in another scroll view. `Screen active={focused}` or `AppShell active={focused}` disables retained background scroll writers; `headerHeight` / `bottomBarHeight` declare custom initial footprints. Geometry reserves the expanded chrome footprint; the visible collapse runs on shared animated values.
+
+## Verification
+
+Review `Templates/Coherent system` stories **Feed**, **Form**, **Desktop**, and **Surfaces**, plus `Foundations/Screen / Continuous Content` alongside the component stories. Verify narrow/wide containers, both color modes, disabled/loading controls, nested scopes and long lists. The browser verifies DOM and web behavior; native safe areas, keyboard and gestures require an iOS/Android run before release.

package/docs/composer-loader.mdx

@@ -43,7 +43,7 @@ Under reduced motion the band stops (web: `animation: none`; native: no clock),
 |------|------|---------|-------------|
 | `children` | `ReactNode` | — | The composer. |
 | `active?` | `boolean` | `true` | Show the light; fades in/out over 450ms. |
-| `colors?` | `[string, string, string, string]` | `#5eead4 #46baec #e633a4 #00faa7` | Gradient left → right. Any colour string. |
+| `colors?` | `[string, string, string, string]` | Theme primary / support / action foreground roles | Gradient left → right. Any colour string. |
 | `speed?` | `number` | `4.5` | Seconds per lap. |
 | `intensity?` | `number` | `0.7` | Overall light opacity. |
 | `bloom?` | `number` | `16` | How far the bloom bleeds inward, px. `0` drops the layer. |
@@ -60,8 +60,10 @@ Under reduced motion the band stops (web: `animation: none`; native: no clock),
 | `style?` | `StyleProp<ViewStyle>` | — | Outer wrapper. |
 | `testID?` | `string` | — | Also derives `-surface` and `-light`. |
 
-The default colours are an iridescent set, kept literal on purpose: they are the effect's identity, not a theme role. Pass `colors` to tint it to a brand.
+The default colours follow the current preset and mode: `primarySubtleForeground`, `secondarySubtleForeground`, `tertiarySubtleForeground`, then primary again to close the moving band. Both platforms use `resolveComposerLoaderColors(theme)`. Pass `colors` for an explicit override.
 
 ## Accessibility
 
 The surface and the light are decorative (`aria-hidden`, `pointerEvents="none"`); only the children are exposed. Announce the busy state from the composer itself (for example on its send / stop button).
+
+`DEFAULT_COMPOSER_LOADER_COLORS` remains exported as a deprecated legacy rainbow for callers that pass it explicitly via `colors`. It is no longer the component default; prefer `resolveComposerLoaderColors(theme)` for theme-aware values.