@oxy.so/bloom 5.4.1 → 6.1.0

package/docs/adoption-matrix.mdx

@@ -14,7 +14,7 @@ The contracts in [Composition](/docs/composition) are worth something only where
 ## 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`.
+- **Control presentation** — `appearance/context.ts`. The size and tone inherited from the nearest BloomScope. Explicit control props override this visual default; constraints remain separate. Applies to controls using the canonical size vocabulary.
 - **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`, …).
 
@@ -32,15 +32,15 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ## Totals
 
-- **207 families** in `src/`, **205** published (a subpath, the root barrel, or both). **40** carry a web fork.
+- **207 families** in `src/`, **205** published (a subpath, the root barrel, or both). **41** 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 | 47 | 21 | 0 | 21 | 5 |
-| Control presentation | 16 | 8 | 2 | 6 | 0 |
+| Control presentation | 42 | 39 | 1 | 2 | 0 |
 | Trigger composition | 10 | 8 | 0 | 2 | 0 |
-| Controlled / uncontrolled state | 49 | 40 | 1 | 1 | 7 |
+| Controlled / uncontrolled state | 53 | 44 | 1 | 1 | 7 |
 
 ## What remains — the named adaptations
 
@@ -90,14 +90,9 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ### 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.
-- `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.
-- `place-card` (does-not-apply) — its `density` is the CARD’s — a result row against a detail header — not a control’s size, and the only controls it draws are `Button`s, which read nothing by design (`docs/composition.mdx`).
-- `tenancy` (does-not-apply) — sizes a tenancy summary row: a presentation part, for the same reason as `creator-studio` and `chat-people`.
+- `phone-input` (delegated) — passes `size` straight through to `TextField`, which inherits density — so a `BloomScope` reaches the phone field without this family reading anything.
 
 ### Trigger composition
 
@@ -129,35 +124,35 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `animated-check` | `@oxy.so/bloom/animated-check` + barrel | universal | `animated-check.mdx` | yes | 2 |  |  |  |  |
 | `announcement` | `@oxy.so/bloom/announcement` + barrel | universal | `announcement.mdx` | yes | 2 |  |  |  |  |
 | `app-shell` | `@oxy.so/bloom/app-shell` + barrel | web fork | `app-shell.mdx` | yes | 6 |  |  |  | reads |
-| `appearance` | `@oxy.so/bloom/appearance` + barrel | universal | `appearance.mdx` | yes | 4 |  |  |  |  |
+| `appearance` | `@oxy.so/bloom/appearance` + barrel | universal | `composition.mdx` | yes | 9 |  | 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 | 2 |  |  |  |  |
-| `avatar` | `@oxy.so/bloom/avatar` + barrel | universal | `avatar.mdx` | yes | 7 |  |  |  |  |
+| `avatar` | `@oxy.so/bloom/avatar` + barrel | universal | `avatar.mdx` | yes | 7 |  | reads |  |  |
 | `avatar-group` | `@oxy.so/bloom/avatar-group` + barrel | web fork | `avatar-group.mdx` | yes | 4 |  |  |  |  |
-| `badge` | `@oxy.so/bloom/badge` + barrel | universal | `badge.mdx` | yes | 2 |  |  |  |  |
+| `badge` | `@oxy.so/bloom/badge` + barrel | universal | `badge.mdx` | yes | 2 |  | reads |  |  |
 | `booking` | `@oxy.so/bloom/booking` + barrel | universal | `booking.mdx` | yes | 5 |  |  |  | reads |
 | `bottom-bar` | `@oxy.so/bloom/bottom-bar` + barrel | web fork | `bottom-bar.mdx` | yes | 2 |  |  |  |  |
 | `bottom-sheet` | `@oxy.so/bloom/bottom-sheet` + barrel | web fork | `bottom-sheet.mdx` | yes | 7 |  |  |  |  |
 | `breadcrumb` | `@oxy.so/bloom/breadcrumb` + barrel | universal | `breadcrumb.mdx` | yes | 2 |  |  |  |  |
-| `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 39 |  |  | n/a¹ |  |
-| `button-group` | `@oxy.so/bloom/button-group` + barrel | web fork | `button-group.mdx` | yes | 7 |  | reads |  |  |
+| `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 40 |  | reads | n/a¹ |  |
+| `button-group` | `@oxy.so/bloom/button-group` + barrel | web fork | `button-group.mdx` | yes | 8 |  | reads |  |  |
 | `calendar` | `@oxy.so/bloom/calendar` + barrel | universal | `calendar.mdx` | yes | 3 |  |  |  | reads |
-| `call-ui` | `@oxy.so/bloom/call-ui` + barrel | universal | `call-ui.mdx` | yes | 2 |  |  |  |  |
-| `card` | `@oxy.so/bloom/card` + barrel | universal | `card.mdx` | yes | 5 |  |  |  |  |
+| `call-ui` | `@oxy.so/bloom/call-ui` + barrel | universal | `call-ui.mdx` | yes | 2 |  | reads |  |  |
+| `card` | `@oxy.so/bloom/card` + barrel | universal | `card.mdx` | yes | 5 |  | reads |  |  |
 | `card-form` | `@oxy.so/bloom/card-form` + barrel | universal | `card-form.mdx` | yes | 2 | reads |  |  | reads |
 | `carousel` | `@oxy.so/bloom/carousel` + barrel | universal | `carousel.mdx` | yes | 2 |  |  |  |  |
 | `carrier-quote` | `@oxy.so/bloom/carrier-quote` + barrel | universal | `carrier-quote.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `cart-panel` | `@oxy.so/bloom/cart-panel` + barrel | universal | `cart-panel.mdx` | yes | 1 |  |  |  |  |
 | `category-bar` | `@oxy.so/bloom/category-bar` + barrel | universal | `category-bar.mdx` | yes | 3 |  |  |  |  |
 | `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 34 |  |  |  | **adaptation** |
-| `chat-composer` | `@oxy.so/bloom/chat-composer` + barrel | web fork | `chat-composer.mdx` | yes | 4 | n/a¹ | n/a¹ |  | reads |
+| `chat-composer` | `@oxy.so/bloom/chat-composer` + barrel | web fork | `chat-composer.mdx` | yes | 4 | n/a¹ | reads |  | reads |
 | `chat-indicators` | `@oxy.so/bloom/chat-indicators` + barrel | universal | `chat-indicators.mdx` | yes | 2 |  |  |  |  |
 | `chat-list` | `@oxy.so/bloom/chat-list` + barrel | universal | `chat-list.mdx` | yes | 3 | n/a¹ |  |  | **adaptation** |
 | `chat-people` | `@oxy.so/bloom/chat-people` + barrel | universal | `chat-people.mdx` | yes | 2 | n/a¹ | n/a¹ |  |  |
-| `chat-screen` | `@oxy.so/bloom/chat-screen` + barrel | universal | `chat-screen.mdx` | yes | 3 |  | n/a¹ |  | reads |
-| `checkbox` | `@oxy.so/bloom/checkbox` + barrel | universal | `checkbox.mdx` | yes | 4 | reads |  |  |  |
+| `chat-screen` | `@oxy.so/bloom/chat-screen` + barrel | universal | `chat-screen.mdx` | yes | 3 |  | reads |  | reads |
+| `checkbox` | `@oxy.so/bloom/checkbox` + barrel | universal | `checkbox.mdx` | yes | 5 | reads | reads |  | reads |
 | `checkout-summary` | `@oxy.so/bloom/checkout-summary` + barrel | universal | `checkout-summary.mdx` | yes | 2 |  |  |  |  |
-| `chip` | `@oxy.so/bloom/chip` + barrel | universal | `chip.mdx` | yes | 6 |  |  |  |  |
+| `chip` | `@oxy.so/bloom/chip` + barrel | universal | `chip.mdx` | yes | 6 |  | reads |  |  |
 | `code` | `@oxy.so/bloom/code` + barrel | universal | `code.mdx` | yes | 4 |  |  |  |  |
 | `command` | `@oxy.so/bloom/command` + barrel | web fork | `command.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `composer-loader` | `@oxy.so/bloom/composer-loader` + barrel | web fork | `composer-loader.mdx` | yes | 1 |  |  |  |  |
@@ -168,9 +163,8 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `contact-card` | `@oxy.so/bloom/contact-card` + barrel | universal | `contact-card.mdx` | yes | 2 |  |  |  |  |
 | `content-panel` | `@oxy.so/bloom/content-panel` + barrel | web fork | `content-panel.mdx` | yes | 8 |  |  |  |  |
 | `context-menu` | `@oxy.so/bloom/context-menu` + barrel | web fork | `context-menu.mdx` | yes | 5 |  |  | reads |  |
-| `control-surface` | `@oxy.so/bloom/control-surface` + barrel | universal | `composition.mdx` | yes | 4 |  | reads |  |  |
 | `creator-studio` | `@oxy.so/bloom/creator-studio` + barrel | universal | `creator-studio.mdx` | yes | 4 |  | n/a¹ |  | **adaptation** |
-| `data-table` | `@oxy.so/bloom/data-table` + barrel | universal | `data-table.mdx` | yes | 4 |  |  |  | reads |
+| `data-table` | `@oxy.so/bloom/data-table` + barrel | universal | `data-table.mdx` | yes | 4 |  | reads |  | reads |
 | `date-picker` | `@oxy.so/bloom/date-picker` + barrel | universal | `date-picker.mdx` | yes | 5 | reads | reads |  | reads |
 | `delivery-slot` | `@oxy.so/bloom/delivery-slot` + barrel | universal | `delivery-slot.mdx` | yes | 2 | reads |  |  |  |
 | `design-tokens` | `@oxy.so/bloom/design-tokens` + barrel | universal | `design-tokens.mdx` | yes | 5 |  |  |  |  |
@@ -183,14 +177,14 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `empty-state` | `@oxy.so/bloom/empty-state` + barrel | universal | `empty-state.mdx` | yes | 1 |  |  |  |  |
 | `error-boundary` | `@oxy.so/bloom/error-boundary` + barrel | universal | `error-boundary.mdx` | yes | 2 |  |  |  |  |
 | `eviction` | `@oxy.so/bloom/eviction` + barrel | universal | `eviction.mdx` | yes | 2 |  |  |  |  |
-| `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 4 |  |  |  |  |
-| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 10 | reads |  |  |  |
+| `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 4 |  | reads |  |  |
+| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 13 | reads |  |  |  |
 | `file-upload` | `@oxy.so/bloom/file-upload` + barrel | universal | `file-upload.mdx` | yes | 4 | reads |  |  |  |
 | `fill` | `@oxy.so/bloom/fill` + barrel | universal | `fill.mdx` | yes | 1 |  |  |  |  |
 | `floating` | internal | universal | — | — | 18 | 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` | — | 2 |  | reads |  |  |
+| `frosted-icon-button` | `@oxy.so/bloom/frosted-icon-button` + barrel | web fork | `frosted-icon-button.mdx` | yes | 4 |  | reads |  |  |
+| `glass` | internal | universal | `glass.mdx` | — | 2 |  |  |  |  |
 | `grid` | `@oxy.so/bloom/grid` + barrel | universal | `grid.mdx` | yes | 1 |  |  |  |  |
 | `home-search` | `@oxy.so/bloom/home-search` + barrel | universal | `home-search.mdx` | yes | 2 | n/a¹ |  |  |  |
 | `hooks` | `@oxy.so/bloom/hooks` + barrel | universal | `hooks.mdx` | yes | 12 |  |  |  | reads |
@@ -200,12 +194,12 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `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 | 8 |  |  |  |  |
 | `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-group` | `@oxy.so/bloom/input-group` + barrel | universal | `input-group.mdx` | yes | 3 | reads | reads |  |  |
 | `input-otp` | `@oxy.so/bloom/input-otp` + barrel | universal | `input-otp.mdx` | yes | 3 | reads |  |  | **adaptation** |
 | `item` | `@oxy.so/bloom/item` + barrel | universal | `item.mdx` | yes | 2 |  |  |  |  |
 | `job-board` | `@oxy.so/bloom/job-board` + barrel | universal | `job-board.mdx` | yes | 2 | n/a¹ |  |  | reads |
-| `kbd` | `@oxy.so/bloom/kbd` + barrel | universal | `kbd.mdx` | yes | 1 |  |  |  |  |
-| `label` | `@oxy.so/bloom/label` + barrel | universal | `label.mdx` | yes | 2 |  |  |  |  |
+| `kbd` | `@oxy.so/bloom/kbd` + barrel | universal | `kbd.mdx` | yes | 1 |  | reads |  |  |
+| `label` | `@oxy.so/bloom/label` + barrel | universal | `label.mdx` | yes | 2 |  | reads |  |  |
 | `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 9 |  |  |  |  |
 | `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 | 3 |  |  |  |  |
@@ -214,7 +208,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `listing-card` | `@oxy.so/bloom/listing-card` + barrel | universal | `listing-card.mdx` | yes | 6 |  |  |  |  |
 | `listing-details` | `@oxy.so/bloom/listing-details` + barrel | universal | `listing-details.mdx` | yes | 5 |  |  |  | reads |
 | `listing-editor` | `@oxy.so/bloom/listing-editor` + barrel | universal | `listing-editor.mdx` | yes | 2 | **adaptation** |  |  | reads |
-| `loading` | `@oxy.so/bloom/loading` + barrel | web fork | `loading.mdx` | yes | 3 |  |  |  |  |
+| `loading` | `@oxy.so/bloom/loading` + barrel | web fork | `loading.mdx` | yes | 3 |  | reads |  |  |
 | `locale` | `@oxy.so/bloom/locale` + barrel | universal | `locale.mdx` | — | 23 |  |  |  |  |
 | `location-puck` | `@oxy.so/bloom/location-puck` + barrel | universal | `location-puck.mdx` | yes | 2 |  |  |  |  |
 | `lyrics` | `@oxy.so/bloom/lyrics` + barrel | universal | `lyrics.mdx` | yes | 3 |  |  |  |  |
@@ -225,36 +219,36 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `map-controls` | `@oxy.so/bloom/map-controls` + barrel | universal | `map-controls.mdx` | yes | 2 |  |  |  | delegated |
 | `map-marker` | `@oxy.so/bloom/map-marker` + barrel | universal | `map-marker.mdx` | yes | 3 | n/a¹ |  |  |  |
 | `media-card` | `@oxy.so/bloom/media-card` + barrel | universal | `media-card.mdx` | yes | 5 |  |  |  |  |
-| `media-controls` | `@oxy.so/bloom/media-controls` + barrel | universal | `media-controls.mdx` | yes | 4 | n/a¹ |  |  |  |
+| `media-controls` | `@oxy.so/bloom/media-controls` + barrel | universal | `media-controls.mdx` | yes | 4 | n/a¹ | reads |  |  |
 | `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 | 4 |  |  |  |  |
+| `media-header` | `@oxy.so/bloom/media-header` + barrel | universal | `media-header.mdx` | yes | 4 |  | reads |  |  |
 | `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 | 5 |  |  |  |  |
+| `media-player` | `@oxy.so/bloom/media-player` + barrel | universal | `media-player.mdx` | yes | 5 |  | reads |  |  |
 | `media-shelf` | `@oxy.so/bloom/media-shelf` + barrel | universal | `media-shelf.mdx` | yes | 2 |  |  |  |  |
 | `menu-item` | `@oxy.so/bloom/menu-item` + barrel | universal | `menu-item.mdx` | yes | 1 |  |  |  |  |
 | `menubar` | `@oxy.so/bloom/menubar` + barrel | web fork | `menubar.mdx` | yes | 5 |  |  | reads | reads |
 | `message-bubble` | `@oxy.so/bloom/message-bubble` + barrel | universal | `message-bubble.mdx` | yes | 2 |  |  |  |  |
-| `message-media` | `@oxy.so/bloom/message-media` + barrel | universal | `message-media.mdx` | yes | 2 | n/a¹ |  |  |  |
-| `motion` | `@oxy.so/bloom/motion` + barrel | web fork | `motion.mdx` | yes | 2 |  |  |  |  |
+| `message-media` | `@oxy.so/bloom/message-media` + barrel | universal | `message-media.mdx` | yes | 3 | n/a¹ |  |  |  |
+| `motion` | `@oxy.so/bloom/motion` + barrel | web fork | `motion.mdx` | yes | 4 |  |  |  |  |
 | `music-library` | `@oxy.so/bloom/music-library` + barrel | universal | `music-library.mdx` | yes | 4 | n/a¹ |  |  |  |
 | `navigation-banner` | `@oxy.so/bloom/navigation-banner` + barrel | universal | `navigation-banner.mdx` | yes | 2 |  |  |  |  |
 | `note-card` | `@oxy.so/bloom/note-card` + barrel | universal | `note-card.mdx` | yes | 2 | n/a¹ |  |  |  |
-| `note-editor` | `@oxy.so/bloom/note-editor` + barrel | universal | `note-editor.mdx` | yes | 2 | n/a¹ | delegated |  |  |
+| `note-editor` | `@oxy.so/bloom/note-editor` + barrel | universal | `note-editor.mdx` | yes | 2 | n/a¹ | reads |  |  |
 | `notification` | `@oxy.so/bloom/notification` + barrel | universal | `notification.mdx` | yes | 4 |  |  |  |  |
 | `notification-center` | `@oxy.so/bloom/notification-center` + barrel | universal | `notification-center.mdx` | yes | 4 |  |  |  | reads |
 | `offering-badge` | `@oxy.so/bloom/offering-badge` + barrel | universal | `offering-badge.mdx` | yes | 4 |  |  |  |  |
 | `order-confirmation` | `@oxy.so/bloom/order-confirmation` + barrel | universal | `order-confirmation.mdx` | yes | 1 |  |  |  |  |
 | `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 | 2 |  |  |  |  |
-| `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 15 |  |  |  |  |
-| `page-header` | `@oxy.so/bloom/page-header` + barrel | universal | `page-header.mdx` | yes | 4 |  | reads |  |  |
+| `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 16 |  |  |  |  |
+| `page-header` | `@oxy.so/bloom/page-header` + barrel | universal | `page-header.mdx` | yes | 4 |  |  |  |  |
 | `pagination` | `@oxy.so/bloom/pagination` + barrel | universal | `pagination.mdx` | yes | 2 |  |  |  |  |
 | `patient-info-card` | `@oxy.so/bloom/patient-info-card` + barrel | universal | `patient-info-card.mdx` | yes | 1 |  |  |  |  |
 | `payment-method` | `@oxy.so/bloom/payment-method` + barrel | universal | `payment-method.mdx` | yes | 3 | reads |  |  |  |
 | `payment-status` | `@oxy.so/bloom/payment-status` + barrel | universal | `payment-status.mdx` | yes | 2 |  |  |  |  |
 | `phone-input` | `@oxy.so/bloom/phone-input` | universal | `phone-input.mdx` | yes | 3 | reads | delegated |  | reads |
 | `pipeline` | `@oxy.so/bloom/pipeline` + barrel | universal | `pipeline.mdx` | yes | 1 |  |  |  | reads |
-| `place-card` | `@oxy.so/bloom/place-card` + barrel | universal | `place-card.mdx` | yes | 3 |  | n/a¹ |  |  |
+| `place-card` | `@oxy.so/bloom/place-card` + barrel | universal | `place-card.mdx` | yes | 3 |  | reads |  |  |
 | `place-details` | `@oxy.so/bloom/place-details` + barrel | universal | `place-details.mdx` | yes | 2 |  |  |  | reads |
 | `place-list` | `@oxy.so/bloom/place-list` + barrel | universal | `place-list.mdx` | yes | 2 |  |  |  |  |
 | `place-reviews` | `@oxy.so/bloom/place-reviews` + barrel | universal | `place-reviews.mdx` | yes | 2 |  |  |  | reads |
@@ -268,47 +262,48 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `provider` | `@oxy.so/bloom/provider` | universal | `provider.mdx` | yes | 3 |  |  |  |  |
 | `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 | 3 |  |  |  | **adaptation** |
-| `radio` | `@oxy.so/bloom/radio` + barrel | universal | `radio.mdx` | yes | 3 | reads |  |  |  |
+| `radio` | `@oxy.so/bloom/radio` + barrel | universal | `radio.mdx` | yes | 4 | reads | reads |  | 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 | 4 | reads |  |  |  |
+| `rating` | `@oxy.so/bloom/rating` + barrel | universal | `rating.mdx` | yes | 4 | reads | 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 | 2 |  |  |  |  |
 | `screen` | `@oxy.so/bloom/screen` + barrel | universal | `screen.mdx` | yes | 5 |  |  |  |  |
 | `scroll` | `@oxy.so/bloom/scroll` + barrel | web fork | `scroll.mdx` | yes | 5 |  |  |  |  |
 | `search` | `@oxy.so/bloom/search` + barrel | universal | `search.mdx` | yes | 3 |  |  |  |  |
-| `segmented-control` | `@oxy.so/bloom/segmented-control` + barrel | universal | `segmented-control.mdx` | yes | 4 | reads |  |  |  |
-| `select` | `@oxy.so/bloom/select` + barrel | web fork | `select.mdx` | yes | 9 | reads |  | reads |  |
+| `segmented-control` | `@oxy.so/bloom/segmented-control` + barrel | universal | `segmented-control.mdx` | yes | 4 | reads | reads |  |  |
+| `select` | `@oxy.so/bloom/select` + barrel | web fork | `select.mdx` | yes | 10 | reads | reads | 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 | 10 |  |  |  | reads |
 | `shapes` | `@oxy.so/bloom/shapes` + barrel | universal | `shapes.mdx` | yes | 4 |  |  |  |  |
 | `shipment-request` | `@oxy.so/bloom/shipment-request` + barrel | universal | `shipment-request.mdx` | yes | 1 | **adaptation** |  |  |  |
-| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 10 | n/a¹ |  |  | reads |
+| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 10 | n/a¹ | reads |  | reads |
 | `skeleton` | `@oxy.so/bloom/skeleton` + barrel | universal | `skeleton.mdx` | yes | 1 |  |  |  |  |
-| `slider` | `@oxy.so/bloom/slider` + barrel | universal | `slider.mdx` | yes | 5 | reads |  |  |  |
-| `social-button` | `@oxy.so/bloom/social-button` + barrel | web fork | `social-button.mdx` | yes | 2 |  |  |  |  |
+| `slider` | `@oxy.so/bloom/slider` + barrel | universal | `slider.mdx` | yes | 5 | reads | reads |  |  |
+| `social-button` | `@oxy.so/bloom/social-button` + barrel | web fork | `social-button.mdx` | yes | 2 |  | reads |  |  |
 | `sortable-media` | `@oxy.so/bloom/sortable-media` + barrel | universal | `sortable-media.mdx` | yes | 2 |  |  |  |  |
 | `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 | 5 | n/a¹ |  |  |  |
+| `stay-filters` | `@oxy.so/bloom/stay-filters` + barrel | universal | `stay-filters.mdx` | yes | 5 | n/a¹ | reads |  |  |
 | `stay-search` | `@oxy.so/bloom/stay-search` + barrel | universal | `stay-search.mdx` | yes | 5 |  |  |  |  |
-| `stepper` | `@oxy.so/bloom/stepper` + barrel | universal | `stepper.mdx` | yes | 4 | reads |  |  |  |
-| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 82 | n/a¹ |  |  |  |
+| `stepper` | `@oxy.so/bloom/stepper` + barrel | universal | `stepper.mdx` | yes | 4 | reads | reads |  |  |
+| `sticker` | `@oxy.so/bloom/sticker` + barrel | web fork | `sticker.mdx` | yes | 1 |  |  |  |  |
+| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 83 | n/a¹ |  |  |  |
 | `subtle-hover` | `@oxy.so/bloom/subtle-hover` + barrel | universal | `subtle-hover.mdx` | yes | 1 |  |  |  |  |
-| `surface` | `@oxy.so/bloom/surface` + barrel | web fork | `surface.mdx` | yes | 5 |  |  |  |  |
+| `surface` | `@oxy.so/bloom/surface` + barrel | web fork | `surface.mdx` | yes | 37 |  |  |  |  |
 | `surfaces` | `@oxy.so/bloom/surfaces` + barrel | web fork | `alert.mdx` | yes | 3 |  |  |  |  |
 | `swipe-row` | `@oxy.so/bloom/swipe-row` + barrel | universal | `swipe-row.mdx` | yes | 2 |  |  |  |  |
-| `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 6 | reads |  |  |  |
+| `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 7 | reads | reads |  | reads |
 | `tab-bar` | `@oxy.so/bloom/tab-bar` | web fork | `tab-bar.mdx` | yes | 14 |  |  | reads |  |
-| `table` | `@oxy.so/bloom/table` + barrel | universal | `table.mdx` | yes | 1 |  |  |  |  |
+| `table` | `@oxy.so/bloom/table` + barrel | universal | `table.mdx` | yes | 1 |  | reads |  |  |
 | `tabs` | `@oxy.so/bloom/tabs` + barrel | universal | `tabs.mdx` | yes | 3 |  |  |  |  |
 | `tag-field` | `@oxy.so/bloom/tag-field` + barrel | universal | `tag-field.mdx` | yes | 3 | 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 | 5 |  | n/a¹ |  |  |
+| `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 5 |  | reads |  |  |
 | `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 16 | 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 | 343 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 344 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 2 | 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 |  |  |  |  |

package/docs/app-shell.mdx

@@ -17,7 +17,7 @@ import { AppShell, NotificationBell, ProOfferCard } from '@oxy.so/bloom/app-shel
   breadcrumb={<Breadcrumb>…</Breadcrumb>}
   actions={<>
     <NotificationBell notifications={inbox} onAction={handle} />
-    <Button variant="primary" leadingIcon={RiAddFill}>Create ticket</Button>
+    <Button  leadingIcon={RiAddFill} tone="accent" appearance="solid">Create ticket</Button>
   </>}
   overlay={showOffer ? <ProOfferCard … onDismiss={hideOffer} /> : null}
 >
@@ -111,7 +111,7 @@ clearance is reserved automatically. Do not render your own
   variant="canvas"
   sidebar={{ ...sidebar, surface: 'docked' }}
   aside={<PlacesInView />}
-  floatingAction={<Button variant="primary" leadingIcon={RiAddFill}>Add a pin</Button>}
+  floatingAction={<Button  leadingIcon={RiAddFill} tone="accent" appearance="solid">Add a pin</Button>}
 >
   <Map />
 </AppShell>

package/docs/booking.mdx

@@ -59,7 +59,7 @@ const [guests, setGuests] = useState({ adults: 2, children: 0, infants: 0, pets:
     ],
     total: '$937',
   }}
-  footer={<Button variant="link" linkTone="secondary" size="small">Report this listing</Button>}
+  footer={<LinkButton  linkTone="secondary" size="sm">Report this listing</LinkButton>}
 />
 ```
 
@@ -187,7 +187,7 @@ Keeping it at the bottom of the screen is the screen's job:
   dates="Oct 12 – 17, 2026"
   status="confirmed"              // 'confirmed' | 'pending' | 'cancelled' | 'completed'
   onPress={() => openTrip(trip.id)}
-  actions={<Button variant="secondary" size="small" onPress={message}>Message host</Button>}
+  actions={<Button  size="sm" onPress={message} tone="neutral" appearance="outline">Message host</Button>}
 />
 ```
 
@@ -220,4 +220,4 @@ Keeping it at the bottom of the screen is the screen's job:
 
 ## Shared card shell
 
-`ActionCardShell` composes Bloom `Card`, shared by BookingCard and the listing action cards. Card owns the solid material and relative surface layer; the shell retains its 372px maximum width, 24px padding, radius 16 and medium elevation. Measurement is forwarded through Card's `onLayout` to the existing host. Explicit style backgrounds are published to descendants as their actual backing.
+`ActionCardShell` composes Bloom `Card`, shared by BookingCard and the listing action cards. Card owns the shared translucent material and relative surface layer; the shell retains its 372px maximum width, 24px padding, radius 16 and medium elevation. Measurement is forwarded through Card's `onLayout` to the existing host. The tint composited against the parent is published as the descendant backing estimate.

package/docs/bottom-bar.mdx

@@ -26,7 +26,7 @@ screen chrome; otherwise it reads the nearest `TabBarMinimizeProvider`.
 The root occupies its expanded footprint, including the bottom safe area.
 `Screen.bottomBar` positions it and reserves that footprint for scrolling content.
 `actionBehavior="hide"` (the default) fades out the accessory and releases its width and gap while minimizing, centering the navigation. Upward scroll brings it back. `visible` keeps the accessory available. An action without navigation always stays visible. Hidden accessories are removed from hit testing and accessibility; web also marks the subtree inert to prevent keyboard focus. Reduced motion snaps the geometry. Native keyboard visibility hides
-this bottom region. BottomBar always uses the shared translucent `SurfacePaint`: tint, sheen and rim on every platform, with refraction on web. There is no material variant. Native uses the same translucent paint without requiring Apple-only glass peers or a per-control blur. Add `blur` explicitly for the separate screen-edge band; it is off by default. `maxWidth` defaults to 560 points.
+this bottom region. BottomBar always uses the shared `SurfacePaint`: a 90%-opacity body, sheen and rim, with a thin refracted edge on web. There is no material variant. Native uses the same body and edge paint without requiring Apple-only glass peers or a per-control blur. Add `blur` explicitly for the separate screen-edge band; it is off by default. `maxWidth` defaults to 560 points.
 
 The universal entry uses no Apple-only peers. The specialized `tab-bar` subpath
 continues to provide its native enhancements independently.

package/docs/bottom-sheet.mdx

@@ -110,6 +110,6 @@ Combine `manualActivation` (so the inner photo grid keeps scroll ownership) with
 If you just need a confirmation flow or a small custom panel, prefer [Dialog](/docs/bloom/main/dialog) — it cross-platforms to a centered modal on web. Reach for `BottomSheet` only when you need direct gesture / scroll control on native.
 </Callout>
 
-The default panel uses Bloom’s shared solid `SurfacePaint` with its gradient and rim. The paint is absolute inside the existing measured panel, so gestures, focus, imperative controls and layout retain their hosts. Explicit caller backgrounds and BottomSheet’s `backgroundComponent` remain overrides. The actual resolved surface color supplies descendant tokens; the default fill is opaque and independent of the backdrop.
+The default panel uses Bloom’s shared `SurfacePaint` with its gradient and rim. The paint is absolute inside the existing measured panel, so gestures, focus, imperative controls and layout retain their hosts. Explicit caller backgrounds and BottomSheet’s `backgroundComponent` remain overrides. The actual resolved surface color supplies descendant tokens; the default body has 90% opacity and only its edge refracts the backdrop on web.
 
-The sheet publishes level 0 using the same resolved opaque fill as its material and web variables. A custom `backgroundComponent` must declare its backing with `backgroundFill`; omitted, the backing defaults to `style.backgroundColor` or the page token. The custom renderer remains responsible for matching that declared color.
+The sheet publishes level 0 using the composited tint estimate of its material and web variables. A custom `backgroundComponent` must declare its backing with `backgroundFill`; omitted, the backing defaults to `style.backgroundColor` or the page token. The custom renderer remains responsible for matching that declared color.

package/docs/button-group.mdx

@@ -1,15 +1,12 @@
 ---
 title: ButtonGroup
-description: Buttons the consumer declared as one control — a fused bordered pill, or one translucent island — for toolbars, filters, pagers and a floating header's actions.
+description: Buttons the consumer declared as one control — one shared glass surface — for toolbars, filters, pagers and a floating header's actions.
 order: 11
 ---
 
 # ButtonGroup
 
-A row of buttons declared as ONE control. Two materials:
-
-- **`solid`** (default): secondary-style buttons fused into one bordered, shadowed container, items divided by 1px hairlines, only the outer ends rounded. The container is a full pill, like `Button`. Colours come from the same Bloom-derived ramps as `Button` (`src/button/shared.ts`).
-- **`glass`**: the same group as a floating **island** — one translucent pane the items sit flush on, with no fill and no blur of their own.
+A row of buttons declared as one control, with one shared glass Surface. Unselected items remain plain; a checked item gains a rounded inset capsule. Dividers separate items by default.
 
 ```tsx
 import { ButtonGroup, ButtonGroupItem } from '@oxy.so/bloom/button-group';
@@ -24,19 +21,17 @@ import { ButtonGroup, ButtonGroupItem } from '@oxy.so/bloom/button-group';
 ## Materials
 
 ```tsx
-<ButtonGroup material="glass" accessibilityLabel="Page actions">
+<ButtonGroup accessibilityLabel="Page actions">
   <ButtonGroupItem iconOnly leadingIcon={RiSearchLine} accessibilityLabel="Search" />
   <ButtonGroupItem iconOnly leadingIcon={RiShare2Line} accessibilityLabel="Share" />
 </ButtonGroup>
 ```
 
-The material is **inherited** when you do not name it: a `ButtonGroup` inside a floating [`PageHeader`](/docs/page-header)'s `actions` is glass with no prop written on it, and the same group inside a card is solid without one either. An explicit `material` still wins. The rule and its limits are in [Composition](/docs/composition).
-
-On glass:
+Density inherits from `BloomScope`; the material is shared everywhere.
 
-- The GROUP owns the material. Items paint `transparent` at rest, and their hover/press states are an alpha of the theme's own `text` — an ink wash, not a fill. That is the one recipe that survives a backdrop Bloom cannot predict: a fixed neutral tuned against the island's fill disappears the moment a photograph moves the pane 40 levels, while a wash of the label's colour keeps the same relation to the label at every composite.
-- Items round their own press highlight, because the island does not clip. (`overflow: hidden` on a glass box clips the iOS drop shadow away.)
-- `dividers` defaults to **false**. A hairline is how a solid pill says "separate controls, fused"; over a moving backdrop it reads as an artifact of the material. Pass `dividers` to draw them anyway.
+- The GROUP owns the shared material. Unselected items paint `transparent` at rest, and their hover/press states are an alpha of the theme's own `text` — an ink wash, not a fill. That is the one recipe that survives a backdrop Bloom cannot predict: a fixed neutral tuned against the island's fill disappears the moment a photograph moves the pane 40 levels, while a wash of the label's colour keeps the same relation to the label at every composite.
+- An inner row clips highlights to the group shape. The outer native host stays unclipped so its shadow remains visible.
+- `dividers` defaults to **true**. Separators stop short of the outer rim. Pass `dividers={false}` to hide them.
 
 ## Items as triggers
 
@@ -85,9 +80,8 @@ Text is `body-medium` (Inter 14/20 500) through Bloom's typography `Text` — a
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `ButtonGroup.material?` | `'solid' \| 'glass'` | inherited, then `'solid'` | The material the group paints. |
 | `ButtonGroup.size?` | `'md' \| 'sm'` | inherited, then `'md'` | Size for every item. |
-| `ButtonGroup.dividers?` | `boolean` | `solid` → `true`, `glass` → `false` | Hairlines between items. |
+| `ButtonGroup.dividers?` | `boolean` | `true` | Hairlines between items. |
 | `ButtonGroup.accessibilityLabel?` | `string` | — | Names the group. |
 | `ButtonGroupItem.onPress?` | `(event) => void` | — | Press handler. Receives the event, so a composed trigger handler can `preventDefault()` it. |
 | `ButtonGroupItem.checked?` | `boolean` | `false` | Hover fill + pressed state. |
@@ -96,12 +90,11 @@ Text is `body-medium` (Inter 14/20 500) through Bloom's typography `Text` — a
 | `ButtonGroupItem.leadingIcon?` / `trailingIcon?` | `BloomIconComponent` | — | Icon components. |
 | `ButtonGroupItem.renderLeadingIcon?` / `renderTrailingIcon?` | `BloomIconRenderer` | — | Draw the glyph yourself, handed `{ size, color }` for the current state — for an app's own icon set. Wins over the icon component. [Icons](/docs/icons). |
 | `ButtonGroupItem.size?` | `'md' \| 'sm'` | group size | Per-item override. |
-| `ButtonGroupItem.material?` | `'solid' \| 'glass'` | group material | Per-item override. Rarely needed — the group owns it. |
 | `ButtonGroupItem.hitSlop?` | `number \| {top,bottom,left,right}` | — | Extra touch area. NOT defaulted: items in a group are adjacent, so slop on one overlaps its neighbour. Use it for an item that stands alone in its own island. |
 | `ButtonGroupItem.onLongPress?` / `aria-expanded` / `aria-haspopup` / `accessibilityRole` | | — | The trigger contract, set by an anchored family. |
 
-## Compatibility
+## API migration
 
-The shared `size`, `tone` and `appearance` vocabulary coexists with the previously published family props. Explicit shared props take precedence over legacy spellings; existing size and state callbacks remain supported. New code should prefer the shared vocabulary.
+Controls use canonical sizes and the shared visual scope. Removed aliases and migration mappings are documented in [Unified component API](/docs/unified-api).
 
-Each `ButtonGroupItem` now composes the actual `Button`, including icon render slots, toggle state, disabled state and trigger events. The group owns joining, dividers and inherited material/density. Glass groups keep one `GlassIsland` pane and plain Buttons flush inside it; joined groups use each Button’s Surface paint.
+Each `ButtonGroupItem` now composes the actual `Button`, including icon render slots, toggle state, disabled state and trigger events. The group owns joining, dividers and inherited density. The group uses one shared `Surface`. With one checked item, a measured rounded capsule moves behind the plain Buttons and resizes to their actual bounds. It shares the same spring and visibility transition as BottomBar, respects reduced motion, and fades in place when selection disappears. Until layout is available, or when multiple items are checked, each checked Button paints its own material instead. Each platform binding injects its own Surface and Button, so browser packages resolve the web implementations directly.

package/docs/button.mdx

@@ -18,7 +18,7 @@ import { RiAddLine } from '@oxy.so/bloom/icons';
 <Button href="/help" tone="accent" appearance="plain">Read the guide</Button>
 ```
 
-`size` (`xs`, `sm`, `md`, `lg`) and `tone` inherit from `BloomScope`; defaults are `md` and `accent`. `appearance` defaults to `solid`. Appearance controls the fill, independently of semantic tone. The shared material rim is used instead of a coloured outline; the legacy outline geometry is retained. Surface appearances share the solid paint described below; semantic fill/foreground pairs remain authoritative.
+`size` (`xs`, `sm`, `md`, `lg`) and `tone` inherit from `BloomScope`; defaults are `md` and `accent`. `appearance` defaults to `solid`. Appearance controls the fill, independently of semantic tone. The shared material rim is used instead of a coloured outline; the legacy outline geometry is retained. Surface appearances share the glass paint described below; semantic fill/foreground pairs remain authoritative.
 
 The Color roles prototype assigns `accent` to identity and links, `support` to contextual emphasis, and `action` to the main CTA. Use `tone="action"` for a task’s Create/Send/Save button and keep secondary controls neutral. `tone="support" appearance="subtle"` can emphasize a related option when that distinction has meaning; it is not a replacement for every secondary button. All eight tones remain available through the shared contract.
 
@@ -56,16 +56,16 @@ On web `color` is `currentColor`, so the glyph follows the stylesheet's state
 colours without a re-render; native gets the resolved value. Full rationale, and
 why this is a separate prop rather than a wider `leadingIcon`: [Icons](/docs/icons).
 
-## Compatibility
+## API migration
 
-The shared `size`, `tone` and `appearance` vocabulary coexists with the previously published family props. Explicit shared props take precedence over legacy spellings; existing size and state callbacks remain supported. New code should prefer the shared vocabulary.
+Controls use canonical sizes and the shared visual scope. Removed aliases and migration mappings are documented in [Unified component API](/docs/unified-api).
 
 
-## Shared solid material
+## Shared glass material
 
-Surface appearances (`solid`, `subtle`, `outline`, including legacy surface variants) share Surface's gradient and specular rim over an opaque fill. There is no backdrop blur, refraction or coloured outline. `plain`, `text` and `link` retain their unfilled contract. Semantic tone, scope, icon slots, sizes, pressed state, loading and accessibility remain unchanged.
+Surface appearances (`solid`, `subtle`, `outline`, all using the shared material) share Surface's 90%-opaque body, gradient and specular rim, with subtle backdrop refraction on web. `appearance="plain"` and `LinkButton` retain their unfilled contract. Semantic tone, scope, icon slots, sizes, pressed state, loading and accessibility remain unchanged.
 
-Accent/status/brand colours keep their semantic foreground pairs. Subtle tints are composited onto a stable theme backing; neutral and disabled surfaces remain opaque. Loading retains its rest paint. The optional `colors={{ background, foreground }}` pair supports branded controls without changing geometry. Native uses one SVG; web uses a decorative pseudo-element. Geometry has no optical offsets.
+Accent/status/brand colours keep their semantic foreground pairs. Neutral, semantic and disabled defaults use the same 90%-opaque fills. Explicit caller transparency is preserved. Loading retains its rest paint. The optional `colors={{ background, foreground }}` pair supports branded controls without changing geometry. Native uses one SVG; web uses a decorative pseudo-element. Geometry has no optical offsets.
 
 Button forwards its ref to the interactive node (the native View handle or the actual web button/anchor), so menus can anchor to it without a layout wrapper. Optional `onLayout` reports React Native's layout shape on both platforms; web installs a resize observer only when that callback is supplied. Press-in/out, cancellation and long press share the base gesture lifecycle. String labels keep the typography defaults; custom content can supply icons, animated glyphs or a composed row. Accessibility visibility props support controls that fade out without leaving an invisible focus target.
 

package/docs/call-ui.mdx

@@ -118,7 +118,7 @@ the failure is a button that does nothing.
   onFlipCamera={flip}
   onScreenShareChange={setSharing}
   onEndCall={hangUp}
-  size="large"
+  size="lg"
   showLabels
 />
 ```
@@ -128,9 +128,9 @@ skipped, so it can never put a dead button back. The end button is last, always.
 
 | size     | button | glyph |
 | -------- | ------ | ----- |
-| `small`  | 40     | 20    |
-| `medium` | 48     | 22    |
-| `large`  | 56     | 26    |
+| `sm`  | 40     | 20    |
+| `md` | 48     | 22    |
+| `lg`  | 56     | 26    |
 
 ### Toggle accessibility
 
@@ -298,3 +298,5 @@ on a short screen, or whether the speaking ring reads as a ring at all. Those
 are browser and device checks.
 
 GroupCallBar uses the shared Surface container for its neutral frame. Call state colors and nested actions remain semantic controls; custom frame backgrounds are handled by Surface.
+
+Control sizes inherit `BloomScope` when omitted; explicit sizes override it. Controls with `sm`/`md`/`lg` geometry map scoped `xs` to `sm`.

package/docs/card.mdx

@@ -92,7 +92,7 @@ is a `button` (the default).
 
 ## Clipping
 
-`Card` uses the shared Surface material (`material="solid"` by default, retaining the gradient and rim; `material="glass"` opts into translucent refraction), while preserving the current appearance, tone and compatibility variant APIs. On native, the outer node keeps its shadow unclipped; an inner content node clips cover images and receives resolved padding, gap and child layout. Web retains one content layout node, where CSS overflow clips children without clipping the box shadow, preserving utility-class layout.
+`Card` uses the shared Surface material (90%-opaque body, gradient, rim and web refraction), with the shared `appearance` and `tone` vocabulary. On native, the outer node keeps its shadow unclipped; an inner content node clips cover images and receives resolved padding, gap and child layout. Web retains one content layout node, where CSS overflow clips children without clipping the box shadow, preserving utility-class layout.
 A surface that must *not* clip — because it has an Android elevation, or
 because a child deliberately overflows — opts out through `style`:
 
@@ -105,8 +105,7 @@ iOS continuous curves, circular corners on Android and unsupported browsers.
 `cornerCurve="round"` is circular everywhere. `radius-max` always remains a pill.
 `border="medium"` supplies a 2px selection border.
 Both layers use the same curve; the inner radius accounts for the border width.
-`radius`, `cornerCurve` and `border` own geometry. Set layout and paint in `style`,
-not border radii, border widths or overflow; `contentStyle` follows the same rule.
+Explicit `radius`, `cornerCurve` and `border` own geometry. With no radius prop, a resolved `style.borderRadius` is used before the family default, matching Surface and GlassIsland. Individual corner radii, border widths and overflow remain controlled by the shape, border and clipping props. `contentStyle` cannot replace the resolved clip geometry.
 
 ## Parts
 
@@ -117,13 +116,13 @@ other card.
 
 `LinkPreviewCard` composes Card and inherits this material without a separate glass implementation.
 
-`appearance="plain"` is an unpainted container: it does not mount SurfacePaint or add a gradient/rim. Explicit caller backgrounds, borders and elevation remain authoritative. This differs from the legacy `variant="plain"`, which retains its solid, unelevated contract.
+`appearance="plain"` is an unpainted container: it does not mount SurfacePaint or add a gradient/rim. Explicit caller backgrounds, borders and elevation remain authoritative. The removed `variant="plain"` maps to `appearance="solid" elevation="none"`; `elevated`, `outlined` and `filled` map to `solid`, `outline` and `subtle`.
 
 ## Parent-aware surface hierarchy
 
 Neutral, non-plain cards keep `colors.card` on the page and derive nested fills from the actual parent surface. The published level caps at three; the fill continues to step from its parent, so deeper cards do not collapse into the same colour. Children receive both the resolved fill through `SurfaceLevelProvider` and its web CSS variable.
 
-Explicit style backgrounds (including resolved class utilities) take precedence. Translucent solid fills are composited against the known parent before painting and publishing. Coloured semantic tones preserve their authored fill/foreground pairs. Glass publishes that same composite as an estimate for descendants; it cannot describe the exact refracted backdrop.
+Explicit style backgrounds (including resolved class utilities) take precedence. Default fills use 90% opacity; explicit caller alpha is preserved. Translucent paint is composited against the known parent only when publishing its estimate for descendants; it cannot describe the exact refracted backdrop.
 
 `appearance="plain"` adds neither material nor a hierarchy step. Its transparent background preserves the inherited fill. An explicit background on a plain card updates the published fill at the current level.
 
@@ -132,3 +131,5 @@ Backgrounds resolved by the styled adapter into `style` participate in this cont
 
 
 `ref` and `onLayout` address the outer card host in both passive and pressable forms. Responsive card families reuse that measurement rather than adding a layout wrapper. Dashboard, chart, booking, tenancy and specialized cards compose this base; their custom content retains its geometry and semantic colours while neutral fills derive from the surrounding surface.
+
+Material resolution is shared with Surface and overlays: one resolver chooses paint alpha, composited backing, depth and CSS aliases. Plain cards publish explicit backing without applying material or incrementing depth.

package/docs/category-bar.mdx

@@ -31,7 +31,7 @@ const [category, setCategory] = useState('trending');
   accessibilityLabel="Categories"
   trailing={
     <Badge content={3} placement="top-right">
-      <Button variant="outline" leadingIcon={RiEqualizerLine}>Filters</Button>
+      <Button  leadingIcon={RiEqualizerLine} tone="neutral" appearance="outline">Filters</Button>
     </Badge>
   }
 />

package/docs/chat-composer.mdx

@@ -68,7 +68,7 @@ What genuinely transfers is reused rather than retyped: the 56px attachment tile
 | attachment tile | 56, radius 12, 1px border; the ring is a 2px accent stroke over that border |
 | suggestion row | min 44, radius 10, in a radius-16 panel |
 | emoji cell | 36; category tabs 32; the grid body is 288 tall by default |
-| reaction cell | 36 (`small` 30), in a full-pill bar |
+| reaction cell | 36 (`sm` 30), in a full-pill bar |
 
 Full pill radius only on the button-like parts — the controls, the reaction bar, the emoji category tabs. The banner, the tiles and the panels keep normal radii.
 
@@ -238,3 +238,5 @@ All of them take `style` and `testID`.
 
 
 The composer controls compose Bloom Button, including its press-in/out recording lifecycle. Each public component has a thin platform binding; shared factories receive Button, Surface, and overlay components explicitly. Web bindings name their `.web` dependencies, so built browser packages work without Metro-style extension resolution. No additional layout wrappers are introduced.
+
+Interactive controls use canonical `sm`/`md`/`lg` sizes and inherit `BloomScope` when omitted. Their geometry remains family-specific; unsupported `xs` uses the compact rung. ReactionPicker has only `sm`/`md`, mapping scoped `lg` to `md`. Display badges and read-only rating sizes retain their existing vocabulary.

package/docs/chat-screen.mdx

@@ -313,8 +313,8 @@ panel cannot hold, so it takes a node:
         icon={<RiNotification3Line width={20} height={20} fill={colors.textSecondary} />}
         rightElement={
           <Switch
-            value={notifications}
-            onValueChange={setNotifications}
+            checked={notifications}
+            onCheckedChange={setNotifications}
             accessibilityLabel="Notifications for this conversation"
           />
         }

package/docs/checkbox.mdx

@@ -121,3 +121,8 @@ Tailwind's `ring-offset-color` default, never overridden — so in dark mode a
 focused checkbox drew a white halo on a near-black page. `FOCUS_RING_OFFSET_COLOR`
 survives only as a deprecated alias of the fallback. See
 [Styles → The focus ring gap](/docs/bloom/main/styles).
+
+
+Use `checked` for controlled state or `defaultChecked` for an initial uncontrolled state. `onCheckedChange` reports either mode. Size uses `xs`, `sm`, `md`, `lg` and inherits from `BloomScope`.
+
+An explicitly supplied `checked={undefined}` is controlled and reads as false. Omit `checked` to let `defaultChecked` initialize internal state.

package/docs/coherent-system-migration.mdx

@@ -35,8 +35,8 @@ This integration adds a shared vocabulary while retaining the current Button, fi
 | Card `variant="elevated/filled/outlined/plain"` | `appearance="solid/subtle/outline/plain"`; `elevation` remains an independent override |
 | FrostedIconButton icon element or `children` alias | `icon={IconComponent}`; size and active-state `tone` inherit from `BloomScope` |
 | Menu item `variant="default/destructive"` | `tone="neutral/danger"` |
-| ButtonGroup / ButtonGroupItem `variant="solid/glass"` | `material="solid/glass"`; the shared island and inherited control surface are preserved |
-| ControlSurface `density="medium/small"` | `density="md/sm"`; item heights remain 34/30 |
+| ButtonGroup / ButtonGroupItem `variant="solid/glass"` or `material` | Removed; one shared Surface material. BloomScope supplies control size and tone |
+| ControlSurface `density="medium/small"` | BloomScope `size="md/sm"`; item heights remain 34/30 |
 | ThemeToggle `appearance`, `ThemeToggleAppearance` | Structural `variant`, `ThemeToggleVariant` |
 | FAB `placement/offset/zIndex/minimizeBehavior` | Still supported; prefer parent composition with `Screen` / `BottomBar` for new screens |
 | Implicit Expo Router root | Universal `BloomProvider` from the provider subpath; explicit `scrollAdapter` |