@oxy.so/bloom 3.0.0 → 3.1.0

package/docs/adoption-matrix.mdx

@@ -0,0 +1,266 @@
+---
+title: Adoption matrix
+description: Every family in Bloom against every composition contract that applies to it — derived from the source, with each shortfall named and justified.
+order: 3
+---
+
+{/* AUTO-GENERATED by scripts/generate-adoption-matrix.ts — do not edit. */}
+{/* `bun run generate:adoption-matrix`; asserted byte-identical by src/__tests__/adoption-matrix.test.ts. */}
+
+# Adoption matrix
+
+The contracts in [Composition](/docs/composition) are worth something only where they are read. This page is that measurement, and it is derived from the source on every change rather than written down once — a matrix maintained by hand is wrong the first time a family changes without its row being updated, and a stale row reads exactly like a fresh one.
+
+## What is measured
+
+- **Field membership** — `field/context.ts, field/membership.ts`. The id, accessible name, description, error, invalid, required and disabled state of an enclosing `Field`, applied to the control. Applies to a family that renders a raw `TextInput` or writes a form role of its own.
+- **Control presentation** — `control-surface/context.ts`. The material and density a container asks the controls inside it for. Applies to a family that PAINTS a container material, or whose size prop is the density pair `medium | small`.
+- **Trigger composition** — `floating/TriggerSlot.tsx`. `asChild`, the composed press handler, the cancellable open, the refused fragment and the two-sided disabled guard. Applies to a family that declares an `asChild` prop of its own.
+- **Controlled / uncontrolled state** — `hooks/use-controllable-state.ts`. One reconciliation of "controlled the moment the prop is passed", with the callback firing either way. Applies to a family that declares both halves of a pair (`value` and `defaultValue`, `open` and `defaultOpen`, …).
+
+A contract that a family does not read is not automatically a failure, and this is where a matrix usually starts lying in one direction or the other. `Search` renders no control of its own — it composes `TextFieldInput` — so the field contract is not its to read. A menu row carrying `role="checkbox"` is a menu item, not a form field. Every family a contract applies to and that does not read it is therefore classified, with a reason, in `src/__tests__/support/adoption-matrix.ts`:
+
+| verdict | means |
+| --- | --- |
+| `reads` | the family imports the contract and applies it itself |
+| `delegated` | it hands the decision to a child that reads it |
+| `n/a¹` | the derivation matched something that is not the contract’s subject — the reason is below |
+| `**adaptation**` | a real remaining gap, named rather than hidden |
+| blank | the contract does not apply: the family renders nothing it governs |
+
+The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, not a floor: a family that starts matching a contract and is not classified renders as `**UNCLASSIFIED**` and fails the gate, and a classification whose family no longer matches fails it too.
+
+## Totals
+
+- **161 families** in `src/`, **159** published (a subpath, the root barrel, or both). **33** 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 |
+| Trigger composition | 10 | 8 | 0 | 2 | 0 |
+| Controlled / uncontrolled state | 38 | 30 | 0 | 1 | 7 |
+
+## What remains — the named adaptations
+
+### Field membership
+
+- `listing-actions` — the mortgage calculator’s term picker is a hand-written `radiogroup`; it sits beside `TextFieldInput`s that DO read the contract, so one form has two association models.
+- `listing-editor` — the property-type, offering and address-precision pickers are hand-written `radiogroup`s over cards, for the same reason and with the same cost as `questionnaire`.
+- `questionnaire` — a FORM whose multi-select answers are hand-written `role="checkbox"` rows instead of `Checkbox`, so a `Field` can neither name nor disable them. Not closed here: the rows carry their own card chrome and selection model, so it is a redesign of the answer control rather than an import.
+
+### Controlled / uncontrolled state
+
+- `chart-cards` — a card’s range selector reconciles `range`/`defaultRange` by hand, in three cards, each with its own copy.
+- `chat-list` — the folder tabs reconcile `value`/`defaultValue` with their own `useState` seeded from the default, so a controlled caller’s later change to `value` is honoured but the callback and the internal state can disagree.
+- `creator-studio` — the streams chart’s metric picker keeps its own state seeded from `defaultMetric` instead of the shared hook.
+- `input-otp` — reconciles `value`/`defaultValue` by hand (`const controlled = value !== undefined`) because it also CLEANS and pads the string to `length`, which the shared hook does not do.
+- `questionnaire` — the step and the answers are each reconciled by hand, which is two copies of the rule in one family.
+- `queue-panel` — the panel’s tab keeps its own state seeded from `defaultTab` instead of the shared hook.
+- `track-list` — the selection set keeps its own state seeded from `defaultSelectedIds` instead of the shared hook, which matters more here because the value is an ARRAY and identity decides whether a caller’s update lands.
+
+## ¹ Why a match is not a subject
+
+### Field membership
+
+- `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.
+- `chat-people` (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`.
+- `command` (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.
+- `composer-panel` (does-not-apply) — its pills and effort slider are a toolbar of a composer, named by the group they sit in; the panel is never a field.
+- `floating` (does-not-apply) — a MENU row. `checkbox`/`radio` inside a menu is the menu-item semantic, and the menu owns its own name, state and keyboard model (`floating/menu-rows.tsx`).
+- `home-search` (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.
+- `map-marker` (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`.
+- `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.
+- `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.
+
+### Control presentation
+
+- `chat-composer` (does-not-apply) — the `small | medium` prop sizes a composer PART (an attachment row), not a control a container would set the density of.
+- `chat-people` (does-not-apply) — sizes an avatar row of its own, not a control: there is nothing for a container’s density to mean here, and honouring it would resize a presentation block.
+- `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.
+- `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`.
+
+### Trigger composition
+
+- `button` (does-not-apply) — `Button`’s own `asChild` renders the button AS an anchor or a router `Link` — it opens nothing and merges no open handler, so it is a different feature with the same name. It FORWARDS the trigger contract’s props when an anchored family clones it, which is the half that matters here.
+- `theme` (does-not-apply) — `BloomColorScope`/`SeedScope` clone their child to merge a style instead of adding a layout node. No surface, no press, no open.
+
+### Controlled / uncontrolled state
+
+- `textarea` (does-not-apply) — the VALUE belongs to React Native’s `TextInput`, which reconciles `value`/`defaultValue` itself; the only local state is the character count, which is why it is kept for the uncontrolled case alone.
+
+## Every family
+
+| 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-heatmap` | `@oxy.so/bloom/activity-heatmap` + barrel | universal | `activity-heatmap.mdx` | yes | 1 |  |  |  |  |
+| `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-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 | 1 |  |  |  | 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 |
+| `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-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 |  |  |  |  |
+| `booking` | `@oxy.so/bloom/booking` + barrel | universal | `booking.mdx` | yes | 3 |  |  |  | reads |
+| `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 |  |  |
+| `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 |  |  |  |  |
+| `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** |
+| `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 |  |  |  |  |
+| `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 | 1 | 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 |  |  |  |  |
+| `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** |
+| `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 |  |  |  |  |
+| `dialog` | `@oxy.so/bloom/dialog` + barrel | web fork | `dialog.mdx` | yes | 13 |  |  |  |  |
+| `divider` | `@oxy.so/bloom/divider` + barrel | universal | `divider.mdx` | yes | 1 |  |  |  |  |
+| `dot-grid-meter` | `@oxy.so/bloom/dot-grid-meter` + barrel | universal | `dot-grid-meter.mdx` | yes | 2 |  |  |  |  |
+| `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 |  |  |  |
+| `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 |
+| `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 |  |  |
+| `grid` | `@oxy.so/bloom/grid` + barrel | universal | `grid.mdx` | yes | 1 |  |  |  |  |
+| `home-search` | `@oxy.so/bloom/home-search` + barrel | universal | `home-search.mdx` | yes | 1 | n/a¹ |  |  |  |
+| `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 | 33 |  |  |  |  |
+| `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 |  |  |  |  |
+| `input-group` | `@oxy.so/bloom/input-group` + barrel | universal | `input-group.mdx` | yes | 3 | reads |  |  |  |
+| `input-otp` | `@oxy.so/bloom/input-otp` + barrel | universal | `input-otp.mdx` | yes | 2 | reads |  |  | **adaptation** |
+| `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 |  |  |  |  |
+| `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 |
+| `listing-card` | `@oxy.so/bloom/listing-card` + barrel | universal | `listing-card.mdx` | yes | 3 |  |  |  |  |
+| `listing-details` | `@oxy.so/bloom/listing-details` + barrel | universal | `listing-details.mdx` | yes | 4 |  |  |  | reads |
+| `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 |  |  |  |  |
+| `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-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-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 |  |  |  |  |
+| `menubar` | `@oxy.so/bloom/menubar` + barrel | web fork | `menubar.mdx` | yes | 2 |  |  | reads | reads |
+| `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 |
+| `offering-badge` | `@oxy.so/bloom/offering-badge` + barrel | universal | `offering-badge.mdx` | yes | 3 |  |  |  |  |
+| `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 |
+| `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 |  |  |  |  |
+| `pressable-scale` | `@oxy.so/bloom/pressable-scale` + barrel | universal | `pressable-scale.mdx` | yes | 1 |  |  |  |  |
+| `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 |
+| `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** |
+| `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 |  |  |  |  |
+| `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 |
+| `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-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 |  |  |  |  |
+| `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 |  |  |  |
+| `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 |  |  |  |  |
+| `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 |  |  |
+| `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 | 242 |  |  | 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** |
+| `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 |  |  |  |  |
+| `wizard` | `@oxy.so/bloom/wizard` + barrel | universal | `wizard.mdx` | yes | 1 |  |  |  |  |
+| `zoomable-media-gallery` | `@oxy.so/bloom/zoomable-media-gallery` | universal | `zoomable-media-gallery.mdx` | yes | 2 |  |  |  |  |

package/docs/checkbox.mdx

@@ -85,6 +85,22 @@ import { CheckboxCard } from '@oxy.so/bloom/checkbox';
 
 `title` is the accessible name and `description` the hint.
 
+## In a `Field`
+
+A checkbox inside a `Field` takes the field's id, its described-by, `aria-invalid`
+and `disabled` — and **keeps its own label as its name**, because the words beside
+the box are the ones the user reads as the control. The field's label names the
+FIELD:
+
+```tsx
+<Field label="Terms" error={errors.terms}>
+  <Checkbox label="I accept the terms" checked={ok} onCheckedChange={setOk} />
+</Field>
+```
+
+A checkbox with no label of its own falls back to the field's. Several checkboxes
+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.

package/docs/composition.mdx

@@ -1,6 +1,6 @@
 ---
 title: Composition
-description: How Bloom components work together — the inherited presentation contract, field membership, trigger composition, scroll ownership and edge claims — with what is done and what is not.
+description: How Bloom components work together — the inherited presentation contract, field membership, trigger composition, scroll ownership, edge claims and screen scope — with the adoption measured per family.
 order: 3
 ---
 
@@ -47,7 +47,21 @@ It renders no node of its own, so it can be dropped anywhere without moving anyt
 
 A field left `undefined` inherits rather than resetting: `<ControlSurface density="small">` inside a glass island stays glass.
 
-**Who reads it today:** `ButtonGroup` and `ButtonGroupItem`. `Button` does not — a `Button` in a floating header keeps its own chrome, which is right for a primary action in its own capsule and wrong for an icon action that should sit flush on an island. Use `ButtonGroup`/`ButtonGroupItem` for the latter. Extending this to more families is adoption work, not a gap in the contract; see [What is not done](#what-is-not-done).
+**Who reads it today:** `ButtonGroup` and `ButtonGroupItem` read `material`; `TextField`, `Textarea` and `TimeField` read `density`, and `PhoneInput` gets it by passing its `size` straight to `TextField`. `density` is `'medium' | 'small'`, which is exactly the text-field family's `size` vocabulary — so a filter row can ask for `small` once instead of writing it on five controls:
+
+```tsx
+<ControlSurface density="small">
+  <TextFieldInput label="Search" value={q} onChangeText={setQ} />
+  <Textarea label="Notes" />
+  <TimeField accessibilityLabel="From" value={from} onChange={setFrom} />
+</ControlSurface>
+```
+
+A family whose sizes are a THREE-rung scale of its own (`small | medium | large`) is deliberately not a subject: a container setting `density` could not say which rung it meant.
+
+**`Button` does not read it** — a `Button` in a floating header keeps its own chrome, which is right for a primary action in its own capsule and wrong for an icon action that should sit flush on an island. Use `ButtonGroup`/`ButtonGroupItem` for the latter.
+
+Which families read it, which are exempt and why: [Adoption matrix](/docs/adoption-matrix).
 
 Precedence is gated in both directions by `src/__tests__/ControlSurface.test.tsx`, including the assertion that the context carries exactly two fields.
 
@@ -69,22 +83,41 @@ A `Field` used to draw a label, a control and a hint, and wire none of them toge
 - **`multiple` is the several-controls case** — a radio set, a date's three boxes. The field becomes a labelled `group`, publishes no control id and describes the GROUP rather than each control: one id on three inputs is invalid HTML, and one error described by three inputs is announced three times.
 - **A floating label and a `Field` label are alternatives, not layers.** `<TextFieldInput floatingLabel>` inside a `Field label="…"` shows the same words above the box and inside it. Pick one.
 
-A control opts in by reading `useFieldControl()`:
+A control opts in with `useFieldMembership()`, which resolves the four decisions in one place:
 
 ```tsx
-const field = useFieldControl();
-<TextInput
-  nativeID={field?.controlId ?? nativeID}
-  aria-describedby={field?.describedBy}
-  aria-invalid={field?.invalid || isInvalid || undefined}
-  accessibilityLabel={field?.labelText ?? label}
-  editable={!(field?.disabled || disabled)}
+const field = useFieldMembership({ accessibilityLabel, label, disabled, invalid: isInvalid });
+
+<Pressable
+  nativeID={field.nativeID}
+  accessibilityLabel={field.accessibilityLabel}
+  aria-describedby={field.describedBy}
+  aria-invalid={field.invalid || undefined}
+  disabled={field.disabled}
 />
 ```
 
+It is a function rather than a convention because each of the four has a direction that is silently wrong the other way round:
+
+| what | direction | why |
+| --- | --- | --- |
+| the NAME | `??` — the field's, then the control's | a switch or a slider draws no words, so the field's label is the only name available |
+| `disabled`, `invalid` | `||` — both | they RESTRICT; a control that could re-enable itself inside a disabled field is the bug |
+| the ID | the caller's, then the field's | an app that wired its own association keeps it |
+| `aria-describedby` | JOINED | it is an id LIST, so the field's error is added to the control's own hint rather than replacing it |
+
+**`labelPlacement` decides which label wins.** A label drawn ABOVE the control (`TextField`, `Textarea`) is the same thing the field's label says, so the field wins. A label BESIDE the control (a checkbox's caption, a radio's option text) is the words the user reads AS the control, so it keeps its own and the field only fills a gap — otherwise a screen reader says one thing while the eye reads another.
+
 Opt-in, not magic. A child that does not read the context renders exactly as before — a container cannot give an arbitrary child behaviour by wrapping it, and one that inspected its children's types to try would be guessing.
 
-**Who reads it today:** `TextFieldInput` (both the default and floating-label renderings). Gate: `src/__tests__/FieldAssociation.test.tsx`.
+**Who reads it today:** `Checkbox`, `FileUpload`, `InputGroup`, `InputOtp`, `PhoneInput`, `Radio`, `RadioGroup`, `RatingInput`, `SegmentedControl`, `Select` (its trigger), `Slider`, `Stepper`, `Switch`, `Textarea`, `TextField`/`TextFieldInput` and `TimeField`.
+
+Two consequences worth knowing:
+
+- **A control that cannot name itself no longer needs a name prop inside a field.** `accessibilityLabel` on `Stepper`, `RatingInput` and `TimeField`, and `label` on `RadioGroup`, `SegmentedControl` and `SelectTrigger`, were required props and are now optional — with neither the prop nor a field the control announces nothing and warns once in development.
+- **A composite hands the field's state to the halves that cannot read it themselves.** `PhoneInput`'s country picker is the measured case: the number input read the field, the picker did not, so it stayed operable inside a disabled field.
+
+Gates: `src/__tests__/FieldAssociation.test.tsx` (the field publishes) and `src/__tests__/FieldMembership.test.tsx` (fifteen families apply, in both directions, and the subject list is asserted against the matrix).
 
 ## Trigger composition — `asChild`
 
@@ -107,6 +140,8 @@ Every anchored family (`Popover`, `DropdownMenu`, `ContextMenu`, `Menubar`, `Sel
 </ButtonGroup>
 ```
 
+**A trigger that IS a form control carries the field's wiring too** — `nativeID`, `aria-describedby` and `aria-invalid` are part of the handle, and `SelectTrigger` passes them. The other four families deliberately do not: a `Popover` inside a `Field` is not that field's control and must not take its id, so `TriggerSlot` reads no field context itself and each family decides whether it is the control.
+
 Gate: `src/__tests__/TriggerComposition.test.tsx`.
 
 ## Scroll ownership — `ScrollOffsetProvider`
@@ -144,16 +179,53 @@ The bottom edge is the tab bar and the FAB (`docs/fab.mdx`). The top edge is chr
 <ScrollView contentContainerStyle={{ paddingTop: useTopEdgeInset() }}>
 ```
 
-`BloomProvider` mounts both. A nested provider scopes a subtree to its own claims — a full-screen modal with its own header, whose content must clear the MODAL's header rather than the screen's.
+`BloomProvider` mounts both. A nested provider scopes a subtree to its own claims — which is what the next section is.
 
 A claim registers in an effect, so a reader mounted in the same commit sees `0` on its first render. `PageHeader` narrows that to one frame by claiming its resting height (safe area + 56) immediately and replacing it with the measured height when `onLayout` reports.
 
+## Screen scope — `ScreenScope`
+
+`@oxy.so/bloom/layout`
+
+A modal, a bottom sheet or a detail panel is a second SCREEN drawn over the first, and two of the contracts above are per-screen by design. Without a boundary they reach across it, in both directions and with no error either way:
+
+- A header inside a full-screen dialog **claims the top edge of the page underneath it**. Claims combine with `max`, so the page behind the modal is padded for chrome it does not have — and the padding appears and disappears with the modal, because the claim unregisters on unmount.
+- Chrome inside the sheet **reads the page's scroll offset** and follows a scroller the user is not touching. The sheet's own list scrolls and its header does not react; the page behind scrolls and it does.
+
+`ScreenScope` is the boundary: a fresh top-edge registry, a fresh bottom-edge registry and a `null` scroll offset, which is the honest value — nothing inside has said which scroller it owns yet. A scroll owner INSIDE publishes in the ordinary way and wins, because it is nearer.
+
+```tsx
+<ScreenScope>
+  <PageHeader title="Edit listing" onBack={close} />
+  <ScrollView contentContainerStyle={{ paddingTop: useTopEdgeInset() }}>…</ScrollView>
+</ScreenScope>
+```
+
+The bottom edge is scoped for the mirror reason: the bottom edge is the tab bar and the FAB, and a sheet is drawn OVER both, so a form inside it that cleared the tab bar would end in a band of empty space.
+
+**Bloom's own surfaces mount it** — `DialogBody` (so every `Dialog` placement, including the bottom-sheet one, gets it) and `BottomSheetBase`. Mount it yourself only around a surface Bloom does not own: an app's own full-screen route presented over another.
+
+Gate: `src/__tests__/ScreenScope.test.tsx`, asserting both directions — a claim inside must not escape, and the surface's own chrome must still be readable inside.
+
+## Five compositions that are not a header
+
+The contracts are worth nothing if they only work in the screen they were built for, so these five are gated together in `src/__tests__/composition-integration.test.tsx`:
+
+1. **A form in a bottom sheet** — the field's error reaches the input across the sheet boundary, `Field disabled` reaches the input, the select trigger AND the switch, the switch takes its name from the field, and submit fires once per press.
+2. **An interactive card with a secondary action** — pressing "Archive" inside a pressable row does not also open the row. (React Native does not bubble a press; a web build does bubble a click, so this half is a browser check, not this one.)
+3. **A chat composer** — two presses send twice, and a disabled bar fires nothing at all.
+4. **A data screen** — a table inside a panel inside a card keeps its own accessible name and renders its empty state; a filter in a `ControlSurface density="small"` draws the small geometry rather than merely receiving a prop.
+5. **A screen with overlaying chrome and a modal over it** — the page pads for its own chrome, the modal's chrome does not reach it, and a sheet on that screen clears nothing of the page.
+
+What that instrument cannot see is written at the top of the file: no paint, no layer order, no hit testing, no focus. Those have their own scripts in `scripts/verify-*.mjs`.
+
 ## What is not done
 
-This page describes contracts that exist and are gated. Issue #145 asks for more than that, and the rest is honest to name:
+This page describes contracts that exist and are gated, and the [adoption matrix](/docs/adoption-matrix) measures where they are read. What is still open, named rather than implied:
 
-- **No full inventory of the public API.** The matrix over every family — platforms, contexts, state families, triggers, semantics, styles, tests — has not been produced. Nothing here should be read as "the library was audited"; it was extended where the header integration needed it.
-- **State-family naming is not unified.** `value`/`defaultValue`/`onValueChange`, `checked`/`onCheckedChange` and `open`/`onOpenChange` are used consistently by the families that have them, and `useControllableState` is the shared implementation, but no sweep has been made to rename the exceptions (`onChangeText` among them, which is a React Native contract worth keeping).
-- **Only two families read `ControlSurface`, and one reads `Field`.** Every other control renders as it always did. Adoption is per-family work with its own regressions to check.
+- **Three families hand-roll the semantics of a grouped choice.** `questionnaire`, `listing-editor` and `listing-actions` write `role="radiogroup"`/`role="checkbox"` over their own cards instead of composing `RadioGroup`/`Checkbox`, so a `Field` can neither name nor disable them. Each is a redesign of an answer control rather than an import, which is why it is recorded instead of rushed. The matrix names them and the gate keeps the list from growing.
+- **Seven families reconcile a controlled/uncontrolled pair by hand** rather than through `useControllableState`. The matrix names them too; `input-otp` has a reason (it cleans and pads the string), the rest do not.
+- **State-family naming is not unified.** `value`/`defaultValue`/`onValueChange`, `checked`/`onCheckedChange` and `open`/`onOpenChange` are used consistently by the families that have them, but no sweep has been made to rename the exceptions (`onChangeText` among them, which is a React Native contract worth keeping).
 - **`BloomProvider` still imports the Expo Router adapter directly.** Decoupling the core from the router is listed in #145 §8 and is not in this change.
 - **No adaptive overflow.** Actions that do not fit are not collapsed into a menu. #145 says explicitly that this is not required for the first header, and nothing here does it.
+- **iOS and Android are not device-verified for any of this.** The instruments used are `tsc`, the jest suites and a real Chrome; a native run is not among them.

package/docs/date-picker.mdx

@@ -159,3 +159,14 @@ They are a convenience **on a text box**, not a `spinbutton`: the control
 announces itself as the text field it is, named by `accessibilityLabel`, and
 every value the arrows can reach can also be typed. A `spinbutton` role would
 promise `aria-valuenow` over a value that is a string and may be empty.
+
+`TimeField` reads the same two contracts the text field does: `size` comes from a
+`ControlSurface density` when it is not written, and an enclosing `Field` supplies
+the accessible name (`"--:--"` names nothing, which is why the name used to be a
+required prop), the id, the described-by, `aria-invalid` and `disabled`.
+
+```tsx
+<Field label="Check-in" error={errors.checkIn}>
+  <TimeField value={checkIn} onChange={setCheckIn} />
+</Field>
+```

package/docs/field.mdx

@@ -40,7 +40,7 @@ import { TextField, TextFieldInput } from '@oxy.so/bloom/text-field';
 
 ## What the wiring actually does
 
-The label, description and error are ASSOCIATED with the control, not merely stacked around it. A control opts in by reading `useFieldControl()`; Bloom's `TextFieldInput` does.
+The label, description and error are ASSOCIATED with the control, not merely stacked around it. A control opts in by reading `useFieldMembership()`, and fifteen Bloom families do.
 
 | the field publishes | the control applies |
 | --- | --- |
@@ -51,14 +51,40 @@ The label, description and error are ASSOCIATED with the control, not merely sta
 | `required` | `aria-required` |
 | `disabled` | its own disabled state |
 
-Three things worth knowing:
+Four things worth knowing:
 
 - **The ids come from `useId`** when no `nativeID` is given, so they survive SSR and hydration. An explicit `nativeID` still owns every derived id (`<id>-description`, `<id>-error`), so a form already wired by hand keeps working.
-- **The field's label wins over the control's own.** On web `aria-label` OVERRIDES a `<label for>`, and on native there is no association at all and the control must carry the name — so a control inside a field defers to the field's label text, and the visible label and the announced name cannot disagree.
-- **`disabled` is a constraint, not a default.** A control inside a disabled field is disabled and cannot opt out.
+- **The field's label wins over a label the control draws ABOVE itself.** On web `aria-label` OVERRIDES a `<label for>`, and on native there is no association at all and the control must carry the name — so a `TextFieldInput` or a `Textarea` inside a field defers to the field's label text, and the visible label and the announced name cannot disagree.
+- **A label the control draws BESIDE itself keeps winning.** A checkbox's caption and a radio's option text are the words the user reads as the control; the field's label names the FIELD. Giving the field's label to a checkbox that draws "Accept the terms" would announce one thing while the screen says another.
+- **`disabled` is a constraint, not a default.** A control inside a disabled field is disabled and cannot opt out — including the halves a composite owns, like `PhoneInput`'s country picker or an `InputGroup`'s addon button.
 
 Opt-in, not magic: a child that does not read the context renders exactly as before. A container cannot give an arbitrary child behaviour by wrapping it, and one that inspected its children's types to try would be guessing. See [Composition](/docs/composition).
 
+## Which controls read it
+
+`Checkbox`, `FileUpload`, `InputGroup`, `InputOtp`, `PhoneInput`, `Radio`,
+`RadioGroup`, `RatingInput`, `SegmentedControl`, `SelectTrigger`, `Slider`,
+`Stepper`, `Switch`, `Textarea`, `TextField`/`TextFieldInput`, `TimeField`.
+
+The practical consequence is that a control which draws no words of its own needs
+no name prop inside a field:
+
+```tsx
+<Field label="Notify members">
+  <Switch value={notify} onValueChange={setNotify} />
+</Field>
+```
+
+That switch announces "Notify members, switch, on". Outside a field it would
+announce "switch, on" and warn once in development, which is why
+`accessibilityLabel` is still the prop to reach for when there is no field.
+`label` on `RadioGroup`, `SegmentedControl` and `SelectTrigger`, and
+`accessibilityLabel` on `Stepper`, `RatingInput` and `TimeField`, were REQUIRED
+props before this and are optional now for the same reason.
+
+Which families are outside the contract, and why each one is: the
+[adoption matrix](/docs/adoption-matrix).
+
 ## One control, or several
 
 A field with ONE control gives it the field's id and describes the error BY that control. A field with several — a radio set, a date's three boxes — must not: three inputs sharing one id is invalid HTML, and one error described by three inputs is announced three times.
@@ -111,6 +137,11 @@ up to the pixel with a `TextField` built from `TextFieldLabel` / `TextFieldHint`
 `SegmentedControl`, a custom control. It supplies the label/description/error
 and the id wiring; the control supplies its own role and state.
 
+The rule a control applies is one function, `useFieldMembership()` — exported
+from `@oxy.so/bloom/field` for an app's own control, so it resolves membership
+the way Bloom's fifteen do rather than by reimplementing four `??`/`||`
+decisions. [Composition](/docs/composition) has the table of directions.
+
 For the label alone, without the surrounding structure, use
 [`Label`](/docs/bloom/main/label). For a control with attached buttons or
 prefixes, use [`InputGroup`](/docs/bloom/main/input-group) *inside* a `Field`.

package/docs/file-upload.mdx

@@ -77,6 +77,19 @@ The "Upload file" / "Upload in progress" frames, pixel-matched on web.
 
 Motion: fills and borders ease over 300ms, the ring's dash over 200ms linear, the pill over 160/300ms. Content swaps use a staggered reveal — each line rises 12px out of a 3px blur over 500ms (`cubic-bezier(0.22, 1, 0.36, 1)`), 40ms apart, and leaves with a 200ms fade. Web runs all of it as self-injected CSS on `dataSet` hooks; native drives opacity and translate with `Animated` **without the blur** (no portable blur filter). Reduced motion removes every transition.
 
+## In a `Field`
+
+The drop zone names itself with `accessibilityLabel`, or with the field's label
+when there is one — `'Upload a file'` is the last resort. The field's `disabled`
+blocks the picker whatever the caller passed, and its error is described BY the
+zone:
+
+```tsx
+<Field label="Lease agreement" error={errors.lease} description="PDF, up to 10 MB">
+  <FileUpload onPickFiles={pick} />
+</Field>
+```
+
 ## Hazards
 
 - **The progress dash is computed in real units, rather than a normalized `pathLength={100}`** — react-native-svg does not honour `pathLength` everywhere, so the length of the rounded-rect path is computed from the measured box instead. Change the inset or radius in one place only (`RING_INSET` / `RING_RADIUS`).

package/docs/glass.mdx

@@ -138,3 +138,18 @@ Gate: `src/theme/__tests__/chrome-glass.test.ts`, which pins the two floors to t
 An island also mounts a `ControlSurface` with `material: 'glass'`, so controls inside it paint flush. That is the material's rule rather than a preference: a translucent pane inside a translucent pane composites two alphas and two blurs for one pane's worth of depth, and on Android the second blur is not available at all.
 
 Internal (`glass/` is not a published subpath). It is reached through `ButtonGroup`'s `glass` variant and `PageHeader`'s floating presentation.
+
+### On a device: tint, and no blur
+
+Measured on a **Pixel 8a** over a hard 10dp stripe pattern, sampling the same rows inside a chrome island and on the bare stripes beside it:
+
+| backdrop stripe | bare | inside the island |
+| --- | --- | --- |
+| white | 255 | 254 |
+| black | 0 | 210 |
+
+The backdrop contributes **44 of 255** — the pane is translucent — and the stripe **edge stays sharp**, where a blur would smear a 26px transition. That is the Android behaviour this file describes: `expo-blur` is asked for no blur method, so it paints its tint and nothing else. Nothing in `logcat` asked for one or reported a crash.
+
+The composite works out at ≈**0.83** opacity against the web pane's 0.72 plus sheen. The difference is `expo-blur`'s own tint — one `intensity` drives it together with the radius and a caller cannot decline it — which is the platform gap `GLASS_BLUR_INTENSITY` documents, appearing exactly where it said it would.
+
+The ramp `PageHeader` draws over the same material was checked for the `stopColor` alpha trap at the same time: **0 achromatic rows of 311** in both modes, so the hue survives the SVG renderer.

package/docs/input-group.mdx

@@ -71,6 +71,28 @@ field, which belongs to [`Field`](/docs/bloom/main/field) or
 `InputGroup` goes *inside* a `Field` — the group is the control, the field is
 its label, hint and error.
 
+## In a `Field`
+
+A group holding a control and its addons is one control as far as a `Field` is
+concerned: the field's `disabled` and invalid state reach every member through the
+group — **including an addon's `Button`**, which reads neither the field nor the
+text-field group itself.
+
+```tsx
+<Field label="Domain" error={errors.domain} disabled={locked}>
+  <InputGroup>
+    <InputGroupAddon>https://</InputGroupAddon>
+    <TextFieldInput value={domain} onChangeText={setDomain} />
+    <InputGroupAddon divider>
+      <Button size="small" variant="ghost" onPress={check}>Check</Button>
+    </InputGroupAddon>
+  </InputGroup>
+</Field>
+```
+
+The group publishes no NAME: it does not know which of its children is the control
+the label points at, so the id stays the field's and the input's to apply.
+
 ## `divider`
 
 Use it when the addon is a distinct target — a button, a dropdown. Skip it for