@oxy.so/bloom 3.6.0 → 4.0.0

package/docs/activity-feed.mdx

@@ -0,0 +1,116 @@
+---
+title: ActivityFeed
+description: Everything anyone did with a customer — calls, emails, meetings, notes, stage changes and completed tasks — grouped by day, with a filter row for the kinds.
+order: 125
+---
+
+# ActivityFeed
+
+```tsx
+import { ActivityFeed, ActivityFeedFilters, ACTIVITY_FEED_KINDS } from '@oxy.so/bloom';
+
+<ActivityFeedFilters
+  kinds={ACTIVITY_FEED_KINDS}
+  selected={kinds}
+  counts={countsByKind}
+  onToggle={toggleKind}
+/>
+<ActivityFeed entries={visible} accessibilityLabel="Activity" />
+```
+
+## A feed is not a status timeline
+
+Bloom already has two timelines, and this is deliberately a third SHAPE rather
+than a third copy.
+
+`TenancyTimeline` (and `EvictionTimeline`, which is that component with a marker
+table) draws ONE PROCESS ADVANCING. Its entries are homogeneous steps of the
+same journey, each carries a state — `complete`, `current`, `upcoming` — and a
+connector runs from each marker to the next. The connector is the component's
+central claim: this step follows that one, and there are more to come.
+
+An activity feed has no such claim to make.
+
+| | timeline | feed |
+| --- | --- | --- |
+| entries | steps of one process | heterogeneous events |
+| state | complete / current / upcoming | none — it happened |
+| subject | the process | the ACTOR, a different one each time |
+| structure | a connected spine | days, and entries inside a day |
+| ordering claim | this follows that | only "same day" |
+
+So the feed's leading mark is the ACTOR's avatar with the kind on its corner,
+there is no connector and no marker state, and the only ordering statement it
+makes is the day heading. Forcing this into `TenancyTimeline` would mean giving
+every call a `state` it does not have and drawing a line between a note and a
+stage change as if one caused the other.
+
+What they do share is the `list` / `listitem` semantics and the vocabulary of a
+tone per kind — shared by convention, not by a base component neither of them
+would fit.
+
+## Grouping is by the day STRING
+
+`entry.day` is already formatted by the app ("Today", "12 March"), and
+`groupActivityByDay` buckets on that exact string in first-seen order.
+
+Bloom does no date maths here, exactly as it does no money maths in `pipeline`.
+The app has the timezone, the locale and the decision about whether today is
+called "Today"; a component that parsed a date would be guessing at all three,
+and could then disagree with the heading it drew. Entries of the same day still
+reunite if they arrive apart — the bucket is keyed, not run-length.
+
+## The geometry
+
+```
+[avatar 32 + kind mark 18]   Marta Oyeleye called Nora about the renewal
+                             Call · 14:10
+                             The body, clamped to three lines…
+                             [Show more]
+                             (Renewal likely)
+                             Logged by Marta Oyeleye
+```
+
+16 between entries, 12 between the mark and the text, and a day heading over a
+rule that runs to the edge. The kind mark is hidden from assistive technology
+(`aria-hidden` AND `accessibilityElementsHidden`): the kind's word is already in
+the meta line, and an `img` announcing "Call" a second time reads as two events.
+
+## The clamp and its reveal
+
+`bodyLines` (default 3) clamps a long body, and a `text` button reveals it.
+`bodyLines={0}` never clamps and never draws the toggle.
+
+**The reveal is offered by CHARACTER COUNT, not by measurement**, via
+`activityBodyIsLong()` and `ACTIVITY_BODY_CHARS_PER_LINE`. React Native gives no
+reliable "did this overflow" signal on both platforms: `onTextLayout` is native
+only, and a measurement pass on web lands a frame after paint. That left two
+mistakes to choose between — a toggle that appears after the text has settled,
+moving content under the reader's eyes, or one that is occasionally offered on a
+body that did fit and collapses to the same text. The second is the cheaper one,
+and this is it. An explicit newline count wins over the character heuristic, so
+a short multi-line note clamps correctly. The per-line count is calibrated on
+the NARROW reading (about 310px of text, which is what a 390 phone leaves after
+the gutters and the 32-wide actor mark), so a wide feed errs toward offering the
+reveal rather than toward a body that silently runs on.
+
+The reveal's accessible name carries the entry ("Show more: called Nora about
+the renewal"), because a column of identical "Show more" buttons is a list of
+identical buttons to a screen reader.
+
+## The filter row is a GROUP of toggles
+
+`ActivityFeedFilters` is a `ChipRow role="group"` of `Chip`s, and each chip is a
+toggle carrying `aria-pressed`.
+
+Not a `tablist` and not a `radiogroup`: the kinds COMBINE. Turning "Call" on
+does not turn "Email" off, and a `tab` or a `radio` would announce single
+selection — the opposite of what the control does. `Chip` spells the state its
+role defines, in both the `aria-*` form web reads and the `accessibilityState`
+form native reads, so the pill is a real toggle rather than a pill that looks
+selected. (`SegmentedControl` is the right control for the other question — one
+view OF the feed — and the wrong one for this.)
+
+It is CONTROLLED and filters nothing itself. Which entries reach `ActivityFeed`
+is the app's decision; a filter row that also held the answer would be a second
+source of truth for one list.

package/docs/address.mdx

@@ -0,0 +1,93 @@
+---
+title: Address
+description: An address as a row — a glyph or an avatar, two lines, a trailing action, a selected state and a provenance flavour expressed as data — plus the sectioned list they live in.
+order: 132
+---
+
+# Address
+
+What a result list is made of. The text INPUT is not here: an app searches with `search`
+or `text-field` and renders what comes back as these rows.
+
+```tsx
+import { AddressList, AddressRow } from '@oxy.so/bloom/address';
+
+<AddressList
+  variant="picker"
+  accessibilityLabel="Delivery address"
+  selectedId={selected}
+  onSelect={setSelected}
+  sections={[
+    { title: 'Saved', entries: [
+      { id: 'home', kind: 'saved', title: 'Home', subtitle: 'Carrer de l’Om 14, 3r 2a', badge: <Badge content="Default" variant="subtle" size="label-small" /> },
+    ] },
+    { title: 'Recent', entries: [
+      { id: 'r1', kind: 'recent', title: 'Plaça de les Bruixes 2', meta: '1.2 km' },
+    ] },
+  ]}
+/>
+```
+
+## The flavour is data
+
+`kind` is `place | saved | recent | suggestion`, and it chooses the default glyph and
+nothing else. There is no `SavedAddressRow`, `RecentAddressRow` and `SuggestionRow`,
+because a picker list, a checkout summary and a search result list all draw the same row
+and differ only in what they put in it.
+
+An app whose provenance is not one of those four passes `icon`. An app that wants a face
+or a map thumbnail passes `leading`.
+
+## `leading` is read for presence
+
+- omitted → the glyph tile
+- a node → that node instead
+- **`null` → no media at all**
+
+The last one is the shape `RouteStops` needs: the marker column outside the row is already
+the gutter, so the row must not draw a tile of its own. It is a presence check rather than
+a `??`, so `leading={null}` cannot be silently answered with the tile.
+
+## It is `Item`, filled in
+
+`AddressRow` is Bloom's `Item` with an address's slots filled: the row, the press target,
+the density rungs, the selected wash, the disabled opacity and the ARIA role translation
+are all `Item`'s, and this family owns no second copy of any of them. What it adds is the
+leading tile, the badge beside the title, the `meta`/`action` pairing in the trailing
+slot, and an accessible name assembled from the row's own text in reading order.
+
+If a row needs something `Item` does not do, that is a report about `Item`, not a fork
+here.
+
+## The variant is the announced tree
+
+`AddressList`'s `variant` is not a style.
+
+| variant | container | row |
+| --- | --- | --- |
+| `list` | one `list` per section, named by its header | a `listitem` wrapping a button |
+| `picker` | a `radiogroup`, one `group` per section | a `radio` carrying `aria-checked` |
+
+**The picker is a radio group rather than the listbox ARIA would suggest, and that is a
+platform decision.** React Native's `Role` has no `listbox`; `radiogroup` and `radio` exist
+on both platforms and say exactly the right thing — pick one of these. A role that reached
+only web would be the silent half of an accessibility bug, correct in the browser and
+absent on the device.
+
+## Loading and empty
+
+`loading` draws `loadingRows` placeholder rows at the row's own geometry, on a container
+marked `aria-busy` so a reader is told to wait rather than told nothing. The empty block
+is a glyph, a title and an optional line; `empty` replaces the whole thing when an app
+wants an action in it.
+
+Empty is measured across ALL sections: a list whose sections exist but hold nothing is
+empty, which is what a search with a stale section header would otherwise render as a
+column of headings over nothing.
+
+## Naming
+
+The announced name defaults to the title, the subtitle and the meta joined in reading
+order, so a row reads as one utterance instead of three. Pass `accessibilityLabel` when
+the visible text is not the sentence you want announced — a title that is an abbreviation,
+a meta that is a distance a reader does not need.

package/docs/adoption-matrix.mdx

@@ -32,15 +32,15 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ## Totals
 
-- **161 families** in `src/`, **159** published (a subpath, the root barrel, or both). **33** carry a web fork.
+- **180 families** in `src/`, **178** published (a subpath, the root barrel, or both). **35** carry a web fork.
 - Docs, stories and suites are gated as a standard by `src/__tests__/family-coverage.test.ts`; the per-family counts are in the table below.
 
 | contract | applies to | reads | delegated | n/a¹ | adaptation |
 | --- | --- | --- | --- | --- | --- |
-| Field membership | 34 | 16 | 0 | 15 | 3 |
-| Control presentation | 14 | 7 | 1 | 6 | 0 |
+| Field membership | 39 | 18 | 0 | 18 | 3 |
+| Control presentation | 16 | 8 | 2 | 6 | 0 |
 | Trigger composition | 10 | 8 | 0 | 2 | 0 |
-| Controlled / uncontrolled state | 38 | 30 | 0 | 1 | 7 |
+| Controlled / uncontrolled state | 42 | 34 | 0 | 1 | 7 |
 
 ## What remains — the named adaptations
 
@@ -64,6 +64,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ### Field membership
 
+- `address` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
 - `agent-chat` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
 - `chat-composer` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
 - `chat-list` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
@@ -76,6 +77,8 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 - `media-controls` (does-not-apply) — a transport SCRUBBER (`adjustable`): it is named by the track it plays and lives in a player, not in a field.
 - `message-media` (does-not-apply) — a voice message’s scrubber — same as `media-controls`.
 - `music-library` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
+- `note-card` (does-not-apply) — the `checkbox` role is on the CARD (bulk selection in a list) and on read-only checklist PREVIEW rows. Neither is a form control: a note card is never inside a `Field`, and the preview rows take no press at all.
+- `note-editor` (does-not-apply) — the raw `TextInput` is a DOCUMENT TITLE — it draws no box, no label and no hint, because the words are the document rather than a value being collected. A `Field` around it would put a form label above a heading.
 - `sidebar` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
 - `stay-filters` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
 - `theme-toggle` (does-not-apply) — the switch row draws its own label ("Dark mode") as both visible text and accessible name, inside the toggle’s own menu.
@@ -87,6 +90,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 - `chat-screen` (does-not-apply) — sizes the chat HEADER, which is chrome around the screen rather than a control a container sets the density of.
 - `creator-studio` (does-not-apply) — sizes a studio stat block — a presentation part, whose two sizes happen to be spelled with the same two words as the density pair.
 - `media-header` (does-not-apply) — sizes the media header’s meta row, which is layout of a header rather than a control inside a container.
+- `note-editor` (delegated) — the toolbar passes `size` straight to `ButtonGroup`, which reads the contract — so a `ControlSurface` reaches the formatting row without this family reading anything.
 - `phone-input` (delegated) — passes `size` straight through to `TextField`, which inherits density — so a `ControlSurface` reaches the phone field without this family reading anything.
 - `tenancy` (does-not-apply) — sizes a tenancy summary row: a presentation part, for the same reason as `creator-studio` and `chat-people`.
 
@@ -104,53 +108,58 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | family | import | platform | doc | story | suites | Field membership | Control presentation | Trigger composition | Controlled / uncontrolled state |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 | `accordion` | `@oxy.so/bloom/accordion` + barrel | universal | `accordion.mdx` | yes | 2 |  |  |  |  |
+| `activity-feed` | `@oxy.so/bloom/activity-feed` + barrel | universal | `activity-feed.mdx` | yes | 1 |  |  |  |  |
 | `activity-heatmap` | `@oxy.so/bloom/activity-heatmap` + barrel | universal | `activity-heatmap.mdx` | yes | 1 |  |  |  |  |
+| `address` | `@oxy.so/bloom/address` + barrel | universal | `address.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `admonition` | `@oxy.so/bloom/admonition` + barrel | universal | `admonition.mdx` | yes | 1 |  |  |  |  |
-| `agent-chat` | `@oxy.so/bloom/agent-chat` + barrel | web fork | `agent-chat.mdx` | yes | 1 | n/a¹ |  |  | reads |
+| `agent-chat` | `@oxy.so/bloom/agent-chat` + barrel | web fork | `agent-chat.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `agent-limits-card` | `@oxy.so/bloom/agent-limits-card` + barrel | universal | `agent-limits-card.mdx` | yes | 1 |  |  |  | reads |
 | `agent-log` | `@oxy.so/bloom/agent-log` + barrel | universal | `agent-log.mdx` | yes | 1 |  |  |  |  |
 | `agent-progress` | `@oxy.so/bloom/agent-progress` + barrel | universal | `agent-progress.mdx` | yes | 1 |  |  |  | reads |
 | `agent-thinking` | `@oxy.so/bloom/agent-thinking` + barrel | universal | `agent-thinking.mdx` | yes | 1 |  |  |  |  |
-| `ai-chat` | `@oxy.so/bloom/ai-chat` + barrel | web fork | `ai-chat.mdx` | yes | 4 |  |  |  | reads |
+| `ai-chat` | `@oxy.so/bloom/ai-chat` + barrel | web fork | `ai-chat.mdx` | yes | 5 |  |  |  | reads |
 | `ai-profile-card` | `@oxy.so/bloom/ai-profile-card` + barrel | universal | `ai-profile-card.mdx` | yes | 1 |  |  |  | reads |
 | `alert-dialog` | `@oxy.so/bloom/alert-dialog` + barrel | web fork | `alert-dialog.mdx` | yes | 1 |  |  |  |  |
 | `animated-check` | `@oxy.so/bloom/animated-check` + barrel | universal | `animated-check.mdx` | yes | 2 |  |  |  |  |
 | `announcement` | `@oxy.so/bloom/announcement` + barrel | universal | `announcement.mdx` | yes | 1 |  |  |  |  |
-| `app-shell` | `@oxy.so/bloom/app-shell` + barrel | universal | `app-shell.mdx` | yes | 1 |  |  |  | reads |
+| `app-shell` | `@oxy.so/bloom/app-shell` + barrel | web fork | `app-shell.mdx` | yes | 2 |  |  |  | reads |
+| `appearance` | `@oxy.so/bloom/appearance` + barrel | universal | `appearance.mdx` | yes | 4 |  |  |  |  |
 | `aspect-ratio` | `@oxy.so/bloom/aspect-ratio` + barrel | universal | `aspect-ratio.mdx` | yes | 1 |  |  |  |  |
 | `auth-card` | `@oxy.so/bloom/auth-card` + barrel | universal | `auth-card.mdx` | yes | 1 |  |  |  |  |
-| `avatar` | `@oxy.so/bloom/avatar` + barrel | universal | `avatar.mdx` | yes | 5 |  |  |  |  |
+| `avatar` | `@oxy.so/bloom/avatar` + barrel | universal | `avatar.mdx` | yes | 6 |  |  |  |  |
 | `avatar-group` | `@oxy.so/bloom/avatar-group` + barrel | web fork | `avatar-group.mdx` | yes | 3 |  |  |  |  |
-| `badge` | `@oxy.so/bloom/badge` + barrel | universal | `badge.mdx` | yes | 1 |  |  |  |  |
+| `badge` | `@oxy.so/bloom/badge` + barrel | universal | `badge.mdx` | yes | 2 |  |  |  |  |
 | `booking` | `@oxy.so/bloom/booking` + barrel | universal | `booking.mdx` | yes | 3 |  |  |  | reads |
+| `bottom-bar` | `@oxy.so/bloom/bottom-bar` + barrel | web fork | `bottom-bar.mdx` | yes | 1 |  |  |  |  |
 | `bottom-sheet` | `@oxy.so/bloom/bottom-sheet` + barrel | web fork | `bottom-sheet.mdx` | yes | 6 |  |  |  |  |
 | `breadcrumb` | `@oxy.so/bloom/breadcrumb` + barrel | universal | `breadcrumb.mdx` | yes | 1 |  |  |  |  |
-| `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 48 |  |  | n/a¹ |  |
-| `button-group` | `@oxy.so/bloom/button-group` + barrel | universal | `button-group.mdx` | yes | 4 |  | reads |  |  |
+| `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 30 |  |  | n/a¹ |  |
+| `button-group` | `@oxy.so/bloom/button-group` + barrel | universal | `button-group.mdx` | yes | 5 |  | reads |  |  |
 | `calendar` | `@oxy.so/bloom/calendar` + barrel | universal | `calendar.mdx` | yes | 1 |  |  |  | reads |
 | `call-ui` | `@oxy.so/bloom/call-ui` + barrel | universal | `call-ui.mdx` | yes | 1 |  |  |  |  |
-| `card` | `@oxy.so/bloom/card` + barrel | universal | `card.mdx` | yes | 2 |  |  |  |  |
+| `card` | `@oxy.so/bloom/card` + barrel | universal | `card.mdx` | yes | 3 |  |  |  |  |
 | `carousel` | `@oxy.so/bloom/carousel` + barrel | universal | `carousel.mdx` | yes | 1 |  |  |  |  |
 | `category-bar` | `@oxy.so/bloom/category-bar` + barrel | universal | `category-bar.mdx` | yes | 2 |  |  |  |  |
-| `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 27 |  |  |  | **adaptation** |
+| `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 29 |  |  |  | **adaptation** |
 | `chat-composer` | `@oxy.so/bloom/chat-composer` + barrel | universal | `chat-composer.mdx` | yes | 2 | n/a¹ | n/a¹ |  | reads |
 | `chat-indicators` | `@oxy.so/bloom/chat-indicators` + barrel | universal | `chat-indicators.mdx` | yes | 1 |  |  |  |  |
 | `chat-list` | `@oxy.so/bloom/chat-list` + barrel | universal | `chat-list.mdx` | yes | 2 | n/a¹ |  |  | **adaptation** |
 | `chat-people` | `@oxy.so/bloom/chat-people` + barrel | universal | `chat-people.mdx` | yes | 1 | n/a¹ | n/a¹ |  |  |
 | `chat-screen` | `@oxy.so/bloom/chat-screen` + barrel | universal | `chat-screen.mdx` | yes | 2 |  | n/a¹ |  | reads |
 | `checkbox` | `@oxy.so/bloom/checkbox` + barrel | universal | `checkbox.mdx` | yes | 4 | reads |  |  |  |
-| `chip` | `@oxy.so/bloom/chip` + barrel | universal | `chip.mdx` | yes | 4 |  |  |  |  |
-| `code` | `@oxy.so/bloom/code` + barrel | universal | `code.mdx` | yes | 2 |  |  |  |  |
+| `chip` | `@oxy.so/bloom/chip` + barrel | universal | `chip.mdx` | yes | 5 |  |  |  |  |
+| `code` | `@oxy.so/bloom/code` + barrel | universal | `code.mdx` | yes | 3 |  |  |  |  |
 | `command` | `@oxy.so/bloom/command` + barrel | web fork | `command.mdx` | yes | 1 | n/a¹ |  |  | reads |
 | `composer-loader` | `@oxy.so/bloom/composer-loader` + barrel | web fork | `composer-loader.mdx` | yes | 1 |  |  |  |  |
 | `composer-panel` | `@oxy.so/bloom/composer-panel` + barrel | web fork | `composer-panel.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `composition-bar` | `@oxy.so/bloom/composition-bar` + barrel | universal | `composition-bar.mdx` | yes | 1 |  |  |  |  |
 | `connection-dots` | `@oxy.so/bloom/connection-dots` + barrel | web fork | `connection-dots.mdx` | yes | 1 |  |  |  |  |
 | `connection-status` | `@oxy.so/bloom/connection-status` + barrel | web fork | `connection-status.mdx` | yes | 1 |  |  |  |  |
+| `contact-card` | `@oxy.so/bloom/contact-card` + barrel | universal | `contact-card.mdx` | yes | 1 |  |  |  |  |
 | `content-panel` | `@oxy.so/bloom/content-panel` + barrel | web fork | `content-panel.mdx` | yes | 6 |  |  |  |  |
 | `context-menu` | `@oxy.so/bloom/context-menu` + barrel | web fork | `context-menu.mdx` | yes | 2 |  |  | reads |  |
 | `control-surface` | `@oxy.so/bloom/control-surface` + barrel | universal | `composition.mdx` | yes | 3 |  | reads |  |  |
-| `creator-studio` | `@oxy.so/bloom/creator-studio` + barrel | universal | `creator-studio.mdx` | yes | 2 |  | n/a¹ |  | **adaptation** |
+| `creator-studio` | `@oxy.so/bloom/creator-studio` + barrel | universal | `creator-studio.mdx` | yes | 3 |  | n/a¹ |  | **adaptation** |
 | `data-table` | `@oxy.so/bloom/data-table` + barrel | universal | `data-table.mdx` | yes | 3 |  |  |  | reads |
 | `date-picker` | `@oxy.so/bloom/date-picker` + barrel | universal | `date-picker.mdx` | yes | 4 | reads | reads |  | reads |
 | `design-tokens` | `@oxy.so/bloom/design-tokens` + barrel | universal | `design-tokens.mdx` | yes | 3 |  |  |  |  |
@@ -160,11 +169,11 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `dropdown-menu` | `@oxy.so/bloom/dropdown-menu` + barrel | web fork | `dropdown-menu.mdx` | yes | 4 |  |  | reads | reads |
 | `error-boundary` | `@oxy.so/bloom/error-boundary` + barrel | universal | `error-boundary.mdx` | yes | 1 |  |  |  |  |
 | `eviction` | `@oxy.so/bloom/eviction` + barrel | universal | `eviction.mdx` | yes | 1 |  |  |  |  |
-| `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 4 |  |  |  |  |
-| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 4 | reads |  |  |  |
+| `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 3 |  |  |  |  |
+| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 6 | reads |  |  |  |
 | `file-upload` | `@oxy.so/bloom/file-upload` + barrel | universal | `file-upload.mdx` | yes | 3 | reads |  |  |  |
 | `fill` | `@oxy.so/bloom/fill` + barrel | universal | `fill.mdx` | yes | 1 |  |  |  |  |
-| `floating` | internal | universal | — | — | 11 | n/a¹ |  | reads | reads |
+| `floating` | internal | universal | — | — | 14 | n/a¹ |  | reads | reads |
 | `fonts` | `@oxy.so/bloom/fonts` + barrel | web fork | `fonts.mdx` | yes | 2 |  |  |  |  |
 | `frosted-icon-button` | `@oxy.so/bloom/frosted-icon-button` + barrel | web fork | `frosted-icon-button.mdx` | yes | 4 |  |  |  |  |
 | `glass` | internal | universal | `glass.mdx` | — | 1 |  | reads |  |  |
@@ -173,7 +182,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `hooks` | `@oxy.so/bloom/hooks` + barrel | universal | `hooks.mdx` | yes | 9 |  |  |  | reads |
 | `hover-card` | `@oxy.so/bloom/hover-card` + barrel | web fork | `hover-card.mdx` | yes | 2 |  |  | reads | reads |
 | `icon-circle` | `@oxy.so/bloom/icon-circle` + barrel | universal | `icon-circle.mdx` | yes | 1 |  |  |  |  |
-| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 34 |  |  |  |  |
+| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 41 |  |  |  |  |
 | `image-aspect-ratio-cache` | `@oxy.so/bloom/image-aspect-ratio-cache` + barrel | universal | `image-aspect-ratio-cache.mdx` | yes | 1 |  |  |  |  |
 | `image-resolver` | `@oxy.so/bloom/image-resolver` + barrel | universal | `image-resolver.mdx` | yes | 7 |  |  |  |  |
 | `important-alerts-card` | `@oxy.so/bloom/important-alerts-card` + barrel | universal | `important-alerts-card.mdx` | yes | 1 |  |  |  |  |
@@ -182,7 +191,8 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `item` | `@oxy.so/bloom/item` + barrel | universal | `item.mdx` | yes | 2 |  |  |  |  |
 | `kbd` | `@oxy.so/bloom/kbd` + barrel | universal | `kbd.mdx` | yes | 1 |  |  |  |  |
 | `label` | `@oxy.so/bloom/label` + barrel | universal | `label.mdx` | yes | 1 |  |  |  |  |
-| `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 6 |  |  |  |  |
+| `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 5 |  |  |  |  |
+| `lead-score` | `@oxy.so/bloom/lead-score` + barrel | universal | `lead-score.mdx` | yes | 1 |  |  |  |  |
 | `link-preview` | `@oxy.so/bloom/link-preview` + barrel | universal | `link-preview.mdx` | yes | 2 |  |  |  |  |
 | `list` | `@oxy.so/bloom/list` + barrel | web fork | `list.mdx` | yes | 2 |  |  |  |  |
 | `listing-actions` | `@oxy.so/bloom/listing-actions` + barrel | universal | `listing-actions.mdx` | yes | 2 | **adaptation** |  |  | reads |
@@ -191,11 +201,14 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `listing-editor` | `@oxy.so/bloom/listing-editor` + barrel | universal | `listing-editor.mdx` | yes | 1 | **adaptation** |  |  | reads |
 | `loading` | `@oxy.so/bloom/loading` + barrel | web fork | `loading.mdx` | yes | 2 |  |  |  |  |
 | `lyrics` | `@oxy.so/bloom/lyrics` + barrel | universal | `lyrics.mdx` | yes | 2 |  |  |  |  |
+| `mail-compose` | `@oxy.so/bloom/mail-compose` + barrel | universal | `mail-compose.mdx` | yes | 2 | reads |  |  | reads |
+| `mail-list` | `@oxy.so/bloom/mail-list` + barrel | universal | `mail-list.mdx` | yes | 2 |  |  |  |  |
+| `mail-thread` | `@oxy.so/bloom/mail-thread` + barrel | universal | `mail-thread.mdx` | yes | 1 |  |  |  | reads |
 | `map-marker` | `@oxy.so/bloom/map-marker` + barrel | universal | `map-marker.mdx` | yes | 2 | n/a¹ |  |  |  |
-| `media-card` | `@oxy.so/bloom/media-card` + barrel | universal | `media-card.mdx` | yes | 3 |  |  |  |  |
-| `media-controls` | `@oxy.so/bloom/media-controls` + barrel | universal | `media-controls.mdx` | yes | 2 | n/a¹ |  |  |  |
+| `media-card` | `@oxy.so/bloom/media-card` + barrel | universal | `media-card.mdx` | yes | 4 |  |  |  |  |
+| `media-controls` | `@oxy.so/bloom/media-controls` + barrel | universal | `media-controls.mdx` | yes | 3 | n/a¹ |  |  |  |
 | `media-flight` | `@oxy.so/bloom/media-flight` | web fork | `media-flight.mdx` | yes | 3 |  |  |  |  |
-| `media-header` | `@oxy.so/bloom/media-header` + barrel | universal | `media-header.mdx` | yes | 2 |  | n/a¹ |  |  |
+| `media-header` | `@oxy.so/bloom/media-header` + barrel | universal | `media-header.mdx` | yes | 3 |  | n/a¹ |  |  |
 | `media-inset-border` | `@oxy.so/bloom/media-inset-border` + barrel | universal | `media-inset-border.mdx` | yes | 1 |  |  |  |  |
 | `media-player` | `@oxy.so/bloom/media-player` + barrel | universal | `media-player.mdx` | yes | 3 |  |  |  |  |
 | `media-shelf` | `@oxy.so/bloom/media-shelf` + barrel | universal | `media-shelf.mdx` | yes | 1 |  |  |  |  |
@@ -203,62 +216,72 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `message-bubble` | `@oxy.so/bloom/message-bubble` + barrel | universal | `message-bubble.mdx` | yes | 1 |  |  |  |  |
 | `message-media` | `@oxy.so/bloom/message-media` + barrel | universal | `message-media.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `motion` | `@oxy.so/bloom/motion` + barrel | web fork | `motion.mdx` | yes | 2 |  |  |  |  |
-| `music-library` | `@oxy.so/bloom/music-library` + barrel | universal | `music-library.mdx` | yes | 2 | n/a¹ |  |  |  |
-| `notification` | `@oxy.so/bloom/notification` + barrel | universal | `notification.mdx` | yes | 2 |  |  |  |  |
-| `notification-center` | `@oxy.so/bloom/notification-center` + barrel | universal | `notification-center.mdx` | yes | 2 |  |  |  | reads |
+| `music-library` | `@oxy.so/bloom/music-library` + barrel | universal | `music-library.mdx` | yes | 3 | n/a¹ |  |  |  |
+| `note-card` | `@oxy.so/bloom/note-card` + barrel | universal | `note-card.mdx` | yes | 1 | n/a¹ |  |  |  |
+| `note-editor` | `@oxy.so/bloom/note-editor` + barrel | universal | `note-editor.mdx` | yes | 1 | n/a¹ | delegated |  |  |
+| `notification` | `@oxy.so/bloom/notification` + barrel | universal | `notification.mdx` | yes | 3 |  |  |  |  |
+| `notification-center` | `@oxy.so/bloom/notification-center` + barrel | universal | `notification-center.mdx` | yes | 3 |  |  |  | reads |
 | `offering-badge` | `@oxy.so/bloom/offering-badge` + barrel | universal | `offering-badge.mdx` | yes | 3 |  |  |  |  |
+| `order-status` | `@oxy.so/bloom/order-status` + barrel | universal | `order-status.mdx` | yes | 1 |  |  |  |  |
+| `outline-nav` | `@oxy.so/bloom/outline-nav` + barrel | universal | `outline-nav.mdx` | yes | 1 |  |  |  |  |
 | `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 7 |  |  |  |  |
 | `page-header` | `@oxy.so/bloom/page-header` + barrel | universal | `page-header.mdx` | yes | 2 |  | reads |  |  |
 | `pagination` | `@oxy.so/bloom/pagination` + barrel | universal | `pagination.mdx` | yes | 1 |  |  |  |  |
 | `patient-info-card` | `@oxy.so/bloom/patient-info-card` + barrel | universal | `patient-info-card.mdx` | yes | 1 |  |  |  |  |
 | `phone-input` | `@oxy.so/bloom/phone-input` | universal | `phone-input.mdx` | yes | 2 | reads | delegated |  | reads |
+| `pipeline` | `@oxy.so/bloom/pipeline` + barrel | universal | `pipeline.mdx` | yes | 1 |  |  |  | reads |
 | `place-reviews` | `@oxy.so/bloom/place-reviews` + barrel | universal | `place-reviews.mdx` | yes | 1 |  |  |  | reads |
-| `popover` | `@oxy.so/bloom/popover` + barrel | web fork | `popover.mdx` | yes | 6 |  |  | reads | reads |
-| `portal` | `@oxy.so/bloom/portal` + barrel | web fork | `portal.mdx` | yes | 14 |  |  |  |  |
+| `popover` | `@oxy.so/bloom/popover` + barrel | web fork | `popover.mdx` | yes | 7 |  |  | reads | reads |
+| `portal` | `@oxy.so/bloom/portal` + barrel | web fork | `portal.mdx` | yes | 15 |  |  |  |  |
 | `pressable-scale` | `@oxy.so/bloom/pressable-scale` + barrel | universal | `pressable-scale.mdx` | yes | 1 |  |  |  |  |
+| `price-breakdown` | `@oxy.so/bloom/price-breakdown` + barrel | universal | `price-breakdown.mdx` | yes | 1 |  |  |  | reads |
 | `progressive-blur` | `@oxy.so/bloom/progressive-blur` + barrel | web fork | `progressive-blur.mdx` | yes | 1 |  |  |  |  |
-| `property-insights` | `@oxy.so/bloom/property-insights` + barrel | universal | `property-insights.mdx` | yes | 3 |  |  |  | reads |
+| `property-insights` | `@oxy.so/bloom/property-insights` + barrel | universal | `property-insights.mdx` | yes | 4 |  |  |  | reads |
 | `provider` | `@oxy.so/bloom/provider` | universal | `provider.mdx` | yes | 1 |  |  |  |  |
 | `questionnaire` | `@oxy.so/bloom/questionnaire` + barrel | universal | `questionnaire.mdx` | yes | 1 | **adaptation** |  |  | **adaptation** |
-| `queue-panel` | `@oxy.so/bloom/queue-panel` + barrel | universal | `queue-panel.mdx` | yes | 1 |  |  |  | **adaptation** |
+| `queue-panel` | `@oxy.so/bloom/queue-panel` + barrel | universal | `queue-panel.mdx` | yes | 2 |  |  |  | **adaptation** |
 | `radio` | `@oxy.so/bloom/radio` + barrel | universal | `radio.mdx` | yes | 3 | reads |  |  |  |
 | `radio-indicator` | `@oxy.so/bloom/radio-indicator` + barrel | universal | `radio-indicator.mdx` | yes | 1 |  |  |  |  |
 | `rail` | `@oxy.so/bloom/rail` + barrel | universal | `rail.mdx` | yes | 1 |  |  |  |  |
 | `rating` | `@oxy.so/bloom/rating` + barrel | universal | `rating.mdx` | yes | 3 | reads |  |  |  |
 | `recent-hires-card` | `@oxy.so/bloom/recent-hires-card` + barrel | universal | `recent-hires-card.mdx` | yes | 1 |  |  |  |  |
+| `route-stops` | `@oxy.so/bloom/route-stops` + barrel | universal | `route-stops.mdx` | yes | 1 |  |  |  |  |
+| `screen` | `@oxy.so/bloom/screen` + barrel | universal | `screen.mdx` | yes | 4 |  |  |  |  |
 | `scroll` | `@oxy.so/bloom/scroll` + barrel | web fork | `scroll.mdx` | yes | 5 |  |  |  |  |
 | `search` | `@oxy.so/bloom/search` + barrel | universal | `search.mdx` | yes | 1 |  |  |  |  |
 | `segmented-control` | `@oxy.so/bloom/segmented-control` + barrel | universal | `segmented-control.mdx` | yes | 3 | reads |  |  |  |
 | `select` | `@oxy.so/bloom/select` + barrel | web fork | `select.mdx` | yes | 6 | reads |  | reads |  |
 | `settings-list` | `@oxy.so/bloom/settings-list` + barrel | universal | `settings-list.mdx` | yes | 5 |  |  |  |  |
 | `settings-modal` | `@oxy.so/bloom/settings-modal` + barrel | universal | `settings-modal.mdx` | yes | 1 |  |  |  | reads |
-| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 1 | n/a¹ |  |  | reads |
+| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `skeleton` | `@oxy.so/bloom/skeleton` + barrel | universal | `skeleton.mdx` | yes | 1 |  |  |  |  |
 | `slider` | `@oxy.so/bloom/slider` + barrel | universal | `slider.mdx` | yes | 4 | reads |  |  |  |
 | `social-button` | `@oxy.so/bloom/social-button` + barrel | universal | `social-button.mdx` | yes | 1 |  |  |  |  |
 | `sortable-media` | `@oxy.so/bloom/sortable-media` + barrel | universal | `sortable-media.mdx` | yes | 1 |  |  |  |  |
-| `stat-bar` | `@oxy.so/bloom/stat-bar` + barrel | universal | `stat-bar.mdx` | yes | 4 |  |  |  |  |
+| `stat-bar` | `@oxy.so/bloom/stat-bar` + barrel | universal | `stat-bar.mdx` | yes | 5 |  |  |  |  |
 | `stat-cards` | `@oxy.so/bloom/stat-cards` + barrel | universal | `stat-cards.mdx` | yes | 4 |  |  |  |  |
 | `stay-filters` | `@oxy.so/bloom/stay-filters` + barrel | universal | `stay-filters.mdx` | yes | 4 | n/a¹ |  |  |  |
 | `stay-search` | `@oxy.so/bloom/stay-search` + barrel | universal | `stay-search.mdx` | yes | 4 |  |  |  |  |
 | `stepper` | `@oxy.so/bloom/stepper` + barrel | universal | `stepper.mdx` | yes | 3 | reads |  |  |  |
-| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 42 |  |  |  |  |
+| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 57 |  |  |  |  |
 | `subtle-hover` | `@oxy.so/bloom/subtle-hover` + barrel | universal | `subtle-hover.mdx` | yes | 1 |  |  |  |  |
 | `surfaces` | `@oxy.so/bloom/surfaces` + barrel | web fork | `alert.mdx` | yes | 2 |  |  |  |  |
-| `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 5 | reads |  |  |  |
+| `swipe-row` | `@oxy.so/bloom/swipe-row` + barrel | universal | `swipe-row.mdx` | yes | 1 |  |  |  |  |
+| `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 6 | reads |  |  |  |
 | `tab-bar` | `@oxy.so/bloom/tab-bar` | web fork | `tab-bar.mdx` | yes | 12 |  |  | reads |  |
 | `table` | `@oxy.so/bloom/table` + barrel | universal | `table.mdx` | yes | 1 |  |  |  |  |
 | `tabs` | `@oxy.so/bloom/tabs` + barrel | universal | `tabs.mdx` | yes | 2 |  |  |  |  |
+| `tag-field` | `@oxy.so/bloom/tag-field` + barrel | universal | `tag-field.mdx` | yes | 2 | reads | reads |  |  |
 | `task-list` | `@oxy.so/bloom/task-list` + barrel | universal | `task-list.mdx` | yes | 1 |  |  |  |  |
 | `teleport` | `@oxy.so/bloom/teleport` | universal | `teleport.mdx` | yes | 1 |  |  |  |  |
 | `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 3 |  | n/a¹ |  |  |
-| `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 10 | reads | reads |  |  |
+| `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 13 | reads | reads |  |  |
 | `textarea` | `@oxy.so/bloom/textarea` + barrel | universal | `textarea.mdx` | yes | 4 | reads | reads |  | n/a¹ |
-| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 246 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 276 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `toast` | `@oxy.so/bloom/toast` + barrel | universal | `toast.mdx` | yes | 17 |  |  |  |  |
 | `tooltip` | `@oxy.so/bloom/tooltip` + barrel | web fork | `tooltip.mdx` | yes | 1 |  |  |  |  |
-| `track-list` | `@oxy.so/bloom/track-list` + barrel | universal | `track-list.mdx` | yes | 1 |  |  |  | **adaptation** |
+| `track-list` | `@oxy.so/bloom/track-list` + barrel | universal | `track-list.mdx` | yes | 2 |  |  |  | **adaptation** |
 | `typography` | `@oxy.so/bloom/typography` + barrel | universal | `typography.mdx` | yes | 7 |  |  |  |  |
 | `user-hover-card` | `@oxy.so/bloom/user-hover-card` + barrel | universal | `user-hover-card.mdx` | yes | 4 |  |  |  |  |
 | `web-search` | `@oxy.so/bloom/web-search` + barrel | universal | `web-search.mdx` | yes | 1 |  |  |  |  |

package/docs/ai-profile-card.mdx

@@ -18,8 +18,8 @@ import { AiProfileCard } from '@oxy.so/bloom/ai-profile-card';
   coverSource={cover}
   actions={
     <>
-      <Button variant="secondary" size="small" leadingIcon={RiShare2Line}>Share</Button>
-      <Button variant="secondary" size="small" leadingIcon={RiEditBoxLine}>Edit</Button>
+      <Button size="sm" leadingIcon={RiShare2Line} appearance="outline" tone="neutral">Share</Button>
+      <Button size="sm" leadingIcon={RiEditBoxLine} appearance="outline" tone="neutral">Edit</Button>
     </>
   }
   contributions={7462}

package/docs/announcement.mdx

@@ -36,7 +36,7 @@ import { Announcement } from '@oxy.so/bloom/announcement';
 | icon | 20px, foreground/icon/secondary — default `RiShieldStarFill` |
 | close | `CloseButton` xs at top 12 / right 12 of the card |
 | text | column, gap 2 — title body-medium text/primary, description body-2-medium text/secondary |
-| action | `Button variant="secondary" size="small"`, full width (a full pill — Bloom's button rule) |
+| action | `Button appearance="subtle" tone="neutral" size="sm"`, full width (a full pill — Bloom's button rule) |
 
 Full height with every part: 12 + 20 + 4 + (20 + 2 + 36) + 12 + 32 + 12 = 150
 (plus the 1px border each side).

package/docs/app-shell.mdx

@@ -448,3 +448,71 @@ A medium secondary icon button with the unread count (16px red disc, 1.5px ring
 280 wide, 12 from the bottom-left (`placement="inline"` renders in flow), radius 16, card-coloured hairline, the waitlist shadow; a light band across the top (default: an accent gradient; pass `backdrop` for your own, masked the same way on web), the copy, a full-width CTA with a sweeping shimmer (hidden under reduced motion) and an xs close button. It rises in after `enterDelay` (1.2s). Persisting the dismissal is the host's job.
 
 A live ray-field WebGL backdrop and animated Pro logo are brand artwork and are not included — pass `backdrop` / `logo`.
+
+## Adaptive navigation
+
+---
+
+# AppShell
+
+`AppShell` composes `Screen`, `PageHeader`, `ScreenScrollView` and navigation.
+Use `navigation={[{ value, label, icon }]}`, `value` and `onValueChange` once.
+`navigationPlacement="auto"` chooses bottom below 768, rail from 768 through 1023,
+and sidebar from 1024. Explicit `bottom`, `rail` or `sidebar` overrides that choice.
+
+`primaryAction` accepts Fab props. In bottom placement it appears beside the tab
+capsule and shares its animation; wider placements float it at the bottom-right
+of the content area, independently of the sidebar.
+`header` overrides the default header; `title`, `breadcrumb` and `actions` configure
+that default. `contentMaxWidth` defaults to 1300. `overlay` stays in the screen's
+content tree, before its chrome; dialogs and toasts should use their proper outlets.
+
+Existing `sidebar` data remains accepted and supplies mobile navigation too. An
+explicit `navigation` model wins when both are supplied. The old `drawer`,
+`drawerOpen` and `onDrawerOpenChange` API is removed: select a responsive placement
+and use a separate dialog/sheet when a secondary navigation drawer is needed.
+
+Placement follows the measured shell width (window width is only the pre-layout
+fallback). `navigationMaterial` chooses `solid` or `translucent` on the bottom bar.
+Use `scroll="external"` when the child owns scrolling. For example:
+
+```tsx
+import { AppShell } from '@oxy.so/bloom/app-shell';
+
+<AppShell navigation={items} value={selected} onValueChange={setSelected} scroll="external">
+  <VirtualList screen={{ active: focused }} data={rows} renderItem={renderRow} />
+</AppShell>
+```
+
+There is no surrounding ScrollView in this mode. Native binds the animated list;
+web retains VirtualList's document virtualizer and pins chrome within the shell
+column. Restore by passing `screen={{ active: focused, restoration }}` with the
+same list ref used by `useScrollRestoration`.
+
+## Sidebar surfaces
+
+The desktop navigation uses `Sidebar` for both `navigation` and `sidebar.items`.
+Use `sidebar={{ surface: 'card' }}` for the detached panel (the default): 12px
+space around it, 24px rounded corners, the panel hairline and shadow. Use
+`sidebar={{ surface: 'docked' }}` for a column flush with the shell: no outer
+spacing, square corners, and a separator on its inner edge. These surfaces apply
+to the expanded panel; `navigationPlacement="rail"` keeps the compact rail.
+
+```tsx
+<AppShell navigation={items} sidebar={{ surface: 'card' }} />
+<AppShell navigation={items} sidebar={{ surface: 'docked' }} />
+```
+
+Sidebar configuration (including its logo, collapse control and size) also applies
+when `navigation` supplies the items.
+
+### Responsive navigation motion
+
+The sidebar/rail change fades the existing navigation out, swaps the single
+rendered tree, then interpolates its width while revealing it. Selection remains
+controlled and reduced motion applies the new placement immediately. After the
+transition the animated width resets explicitly to `auto`: returning an empty
+style or an undefined width retained the old width in the browser, leaving a
+260px space after the sidebar itself collapsed to 52px.
+
+The adaptive entry point is selected when `navigation`, `navigationPlacement`, `primaryAction`, or `scroll="auto" | "external"` is supplied. Existing layout calls keep their `dashboard`, `feed`, `split`, `focus`, and `canvas` engine, document/container/fixed scrolling, slots and drawer behavior. Both paths render the same Sidebar, PageHeader and themed surfaces.

package/docs/appearance.mdx

@@ -0,0 +1,56 @@
+---
+title: Component contract
+description: One vocabulary for controls and one owner for screen composition.
+order: 1
+---
+
+# Component contract
+
+Bloom separates **size**, **tone**, and **appearance**. A size describes a component's relative scale, not a universal pixel height: a badge and a button serve different purposes. Each family publishes the meaningful subset of the common vocabulary.
+
+| Axis | Values | Purpose |
+| --- | --- | --- |
+| `size` | `xs`, `sm`, `md`, `lg` | Component scale |
+| `tone` | `neutral`, `accent`, `support`, `action`, `success`, `warning`, `danger`, `info` | Semantic intent |
+| `appearance` | `solid`, `subtle`, `outline`, `plain` | Fill and border treatment |
+
+Structural options remain specific to their components. A tab indicator's `variant`, for example, describes its structure rather than its semantic color.
+
+## Color roles
+
+The approved **Color roles** Storybook prototype separates three jobs: `accent` carries product identity, links and active navigation; `support` gives related information and secondary surfaces a quieter tint; `action` marks the principal task, such as Create, Send, Generate or Save. `neutral` remains the default choice for ordinary supporting controls. Status tones retain their existing meanings.
+
+Choose one main action for each task area. Use `support` with `appearance="subtle"` for contextual emphasis, rather than tinting every button. These are theme roles with paired foreground colors: `support` resolves the secondary pair and `action` the tertiary pair. Their hues follow the selected preset and mode, not a hard-coded prototype color.
+
+## Visual scopes
+
+```tsx
+import { BloomScope } from '@oxy.so/bloom/appearance';
+import { Button } from '@oxy.so/bloom/button';
+
+<BloomScope size="lg" tone="action">
+  <Button>Save</Button>
+  <Button tone="danger" appearance="outline">Delete</Button>
+  <BloomScope size="sm">
+    <Button tone="neutral" appearance="plain">Secondary action</Button>
+  </BloomScope>
+</BloomScope>
+```
+
+Explicit props win over the nearest scope, which wins over the family's defaults. A nested scope inherits unspecified values. Scopes render no layout node and never carry actions, selection, disabled state, or screen geometry. `appearance` remains explicit so a scope cannot silently turn every control into a filled primary action.
+
+## Actions and icons
+
+`onPress` activates an action. `href` gives a button real link semantics on web. `disabled` blocks activation; `loading` preserves layout while blocking repeated presses. `accessibilityLabel` names icon-only controls.
+
+`icon` is an icon component for an icon-only action. `leadingIcon` and `trailingIcon` are icon components on labelled controls; Bloom supplies size and color. `leading` and `trailing` accept custom composed content. Use logical leading/trailing positions rather than left/right.
+
+## Values
+
+Boolean controls use `checked` and `onCheckedChange`. Fields and selections use `value` and `onValueChange`, delivering the semantic value rather than a platform event. Validation is `invalid`. Platform event handlers are separate from the value contract.
+
+## Screens
+
+`Screen` owns a continuous page surface and the geometry shared by its content and chrome. `ScreenScrollView` binds normal content; external scrollers use `useScreenScroll`. `AppShell` adapts navigation to its available width, with an explicit `navigationPlacement` override.
+
+`BottomBar` places navigation and its action side by side. `Fab` is the action itself; its parent owns positioning. Do not reproduce bottom offsets or independent minimize animations in an application.