@oxy.so/bloom 5.4.0 → 6.0.0

package/docs/composer-panel.mdx

@@ -256,3 +256,7 @@ that could not have held the line anyway. An input method's Enter
 Mic, send and stop are Button compositions. They share the base material, keyboard focus, press lifecycle and disabled handling rather than maintaining a second gradient or hover engine. The microphone keeps only its voice-specific equalizer/swap animation. Send and stop use the semantic action tone; stop deliberately has no disabled input so cancellation remains available during a blocked draft. Platform entry points bind the actual native or DOM Button through the family context, including forwarded refs and measured layout for menu triggers.
 
 Composer action buttons compose Bloom Button: send, stop, voice, add, model/effort/permission triggers, folder/status actions, search, attachment retry/remove and the help link. Platform bindings inject the matching Button fork alongside the popover. The family keeps only content, measured geometry and icon animation; Button owns state paint, focus, disabled behavior, refs and layout callbacks. Radio options and tabs retain their selection roles.
+
+### Shared surface paint
+
+The painted host delegates its fill to Surface: a 90%-opacity body with a subtle refracted edge on web, plus the shared sheen and rim. The host itself stays transparent to avoid painting twice. Explicit alpha colours retain their alpha; descendants receive the corresponding composited fill. Plain or unframed content keeps its existing layout behavior.

package/docs/composition.mdx

@@ -6,7 +6,7 @@ order: 3
 
 # Composition
 
-Bloom components share tokens. Sharing tokens is not the same as working together: a control still has to be told what material the container around it is painting, a label still has to be wired to the control it names, and a header still has to know which scroller it is following. Written as props, each of those is a thing the app repeats at every call site and gets wrong at one of them.
+Bloom components share tokens. Sharing tokens is not the same as working together: a control still has to inherit the density of its container, a label still has to be wired to the control it names, and a header still has to know which scroller it is following. Written as props, each of those is a thing the app repeats at every call site and gets wrong at one of them.
 
 This page is the set of small, explicit contracts that answer those questions, and the rules that keep them small. Each is a context a container publishes and a component opts into. None of them is a framework, a singleton, or a component that reads its children's types to decide what to do with them.
 
@@ -18,52 +18,35 @@ Every contract on this page resolves the same way:
 an explicit prop  >  the nearest container  >  the component's own default
 ```
 
-`undefined` is the only value that defers. Passing `material="solid"` inside a glass island paints a solid control — the container is a default, not an override, and a caller can always win.
+`undefined` is the only value that defers. Passing `size="md"` inside a compact control surface keeps that control medium-sized — the container is a default, not an override, and a caller can always win.
 
 **A constraint is not a default.** Anything that RESTRICTS a control — `disabled`, a modal's inertness, the user's reduce-transparency or reduce-motion preference — travels on its own channel and combines with `||`, never `??`. The rule above is exactly wrong for those: a descendant must not be able to re-enable an action its group disabled by passing a prop.
 
 **State does not travel either.** `checked`, `selected`, a field's value, a business datum: those belong to the component that holds them. A visual context that also carried state would make every container a place state can leak from.
 
-## Control presentation — `ControlSurface`
+## Control presentation — `BloomScope`
 
-`@oxy.so/bloom/control-surface`
+`@oxy.so/bloom/appearance`
 
-What a container tells the controls inside it about presentation, and nothing else. Two fields, both visual configuration:
-
-| field | values | meaning |
-| --- | --- | --- |
-| `material` | `'solid'` \| `'glass'` | the surface a control CONTAINER paints |
-| `density` | `'md'` \| `'sm'` (also `'medium'` \| `'small'`) | the size controls default to |
-
-```tsx
-import { ControlSurface } from '@oxy.so/bloom/control-surface';
-
-<ControlSurface material="glass">
-  <ButtonGroup accessibilityLabel="Playback">…</ButtonGroup>
-</ControlSurface>
-```
-
-It renders no node of its own, so it can be dropped anywhere without moving anything. Bloom's own containers mount it for you — `glass/GlassIsland` does, which is why a `ButtonGroup` inside a floating `PageHeader` is glass with no prop written on it.
-
-A field left `undefined` inherits rather than resetting: `<ControlSurface density="small">` inside a glass island stays glass.
-
-**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` accepts `'medium' | 'small'` alongside `'md' | 'sm'`; legacy form sizes retain their public spellings — so a filter row can ask for `small` once instead of writing it on five controls:
+One visual environment supplies `size="xs|sm|md|lg"` and `tone`. It renders no layout node. Each control resolves explicit props first, then the nearest scope, then its own defaults. An omitted field inherits from the enclosing scope independently of the other fields.
 
 ```tsx
-<ControlSurface density="small">
-  <TextFieldInput label="Search" value={q} onChangeText={setQ} />
-  <Textarea label="Notes" />
-  <TimeField accessibilityLabel="From" value={from} onChange={setFrom} />
-</ControlSurface>
+import { BloomScope } from '@oxy.so/bloom/appearance';
+
+<BloomScope size="sm" tone="neutral">
+  <Button>Apply</Button>
+  <TextFieldInput label="Search" value={query} onValueChange={setQuery} />
+  <BloomScope tone="danger">
+    <Button>Delete</Button>
+  </BloomScope>
+</BloomScope>
 ```
 
-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.
+Button, Switch, Select, Checkbox, ButtonGroup and text controls consume the same scope. Domain components may expose a separate content density; it must not become a competing control-size context. Each family documents any supported subset of sizes.
 
-Which families read it, which are exempt and why: [Adoption matrix](/docs/adoption-matrix).
+Selection, actions and disabled state do not travel through visual scopes. A disabled `Field` constrains its controls; a component cannot re-enable itself by overriding a visual default. Surface nesting remains independent of control size.
 
-Precedence is gated in both directions by `src/__tests__/ControlSurface.test.tsx`, including the assertion that the context carries exactly two fields.
+See the generated [Adoption matrix](/docs/adoption-matrix) for participation and reasoned exceptions. `ControlSizeScope.test.tsx` verifies nesting and explicit overrides.
 
 ## Field membership — `Field`
 
@@ -214,7 +197,7 @@ The contracts are worth nothing if they only work in the screen they were built
 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.
+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 `BloomScope size="sm"` 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`.

package/docs/content-panel.mdx

@@ -251,3 +251,7 @@ top/bottom gutter pixels and header bounds in both modes, at 8/16/40/72px insets
 and multiple scroll positions. `scripts/verify-storybook-document-scroll.mjs`
 checks real wheel gestures over each column, sticky navigation and reachable
 last content without nested vertical scroll containers.
+
+### Shared surface paint
+
+The painted host delegates its fill to Surface: a 90%-opacity body with a subtle refracted edge on web, plus the shared sheen and rim. The host itself stays transparent to avoid painting twice. Explicit alpha colours retain their alpha; descendants receive the corresponding composited fill. Plain or unframed content keeps its existing layout behavior.

package/docs/date-picker.mdx

@@ -185,7 +185,7 @@ 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
+`BloomScope 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`.
 

package/docs/dialog.mdx

@@ -312,6 +312,10 @@ Bottom-sheet on small screens, left drawer on `md` and wider:
 
 Removed exports: `CenteredDialog`, `CenteredDialogProps`, `BLOOM_CENTERED_DIALOG_CSS`, `CENTERED_DIALOG_BACKDROP_TESTID`, `ResponsiveSheet`, `@oxy.so/bloom/responsive-sheet` subpath.
 
-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 nominal surface color still 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 composited painted color supplies descendant tokens; the default body has 90% opacity and only its edge refracts the backdrop on web.
 
-Dialog panels publish level 0 with the exact opaque fill sent to SurfacePaint. Explicit style backgrounds are resolved against the page backing once and shared by paint, descendant context and web surface variables; opening inside a card does not leak its level into the dialog.
+Dialog panels publish level 0 with the painted tint composited against the page backing. Explicit style backgrounds are resolved against the page backing once and shared by paint, descendant context and web surface variables; opening inside a card does not leak its level into the dialog.
+
+### Shared surface paint
+
+The painted host delegates its fill to Surface: a 90%-opacity body with a subtle refracted edge on web, plus the shared sheen and rim. The host itself stays transparent to avoid painting twice. Explicit alpha colours retain their alpha; descendants receive the corresponding composited fill. Plain or unframed content keeps its existing layout behavior.

package/docs/eviction.mdx

@@ -88,7 +88,7 @@ draws a hollow marker. The list is named "Case history" (`accessibilityLabel`).
 There is no list component — compose the cards with a `SegmentedControl`:
 
 ```tsx
-<SegmentedControl label="Show evictions" type="tabs" size="large" value={tab} onChange={setTab}>
+<SegmentedControl label="Show evictions" type="tabs" size="lg" value={tab} onChange={setTab}>
   <SegmentedControlItem value="upcoming"><SegmentedControlItemText>Upcoming</SegmentedControlItemText></SegmentedControlItem>
   <SegmentedControlItem value="past"><SegmentedControlItemText>Past</SegmentedControlItemText></SegmentedControlItem>
 </SegmentedControl>

package/docs/fab.mdx

@@ -46,6 +46,6 @@ Remove `placement`, `offset`, `zIndex`, and `minimizeBehavior`. Position the act
 through `AppShell`/`BottomBar`; the bottom accessory hides on downward scroll
 and returns upward by default. Set `actionBehavior="visible"` on `BottomBar`
 or `bottomActionBehavior="visible"` on `AppShell` to keep it visible. Replace `variant="primary"` with `tone="action"` for the main task (or `accent` when retaining brand emphasis), `variant="surface"`
-with `tone="neutral" appearance="subtle"`. The shared `support` and `action` roles resolve the secondary and tertiary color pairs. Choose them by intent: contextual support or the main task. Replace `small/medium/large` with `sm/md/lg`, and numeric size
+with `tone="neutral" appearance="subtle"`. The shared `support` and `action` roles resolve the secondary and tertiary color pairs. Choose them by intent: contextual support or the main task. Replace `small/medium/large` with `xs/md/lg` (40/50/64px respectively), and numeric size
 with a preset plus a deliberate style override if needed. Replace icon elements
 with icon components and remove the `children` alias.

package/docs/field.mdx

@@ -71,7 +71,7 @@ no name prop inside a field:
 
 ```tsx
 <Field label="Notify members">
-  <Switch value={notify} onValueChange={setNotify} />
+  <Switch checked={notify} onCheckedChange={setNotify} />
 </Field>
 ```
 

package/docs/glass.mdx

@@ -5,7 +5,7 @@ description: Lightweight button optics and safe overlay blur boundaries.
 
 # Glass
 
-Surface defaults to an opaque fill with the shared gradient and rim. Button, Card, Sidebar, Dialog and Bottom Sheet use this solid material with no backdrop blur or refraction. Explicit `Surface material="glass"` remains available for comparison: it adds a translucent tint and a shared web displacement filter. Native glass uses tint/sheen without refraction. See [Surface](./surface.mdx) and [Button](./button.mdx).
+Surface provides one shared glass material: a 90%-opaque body, gradient and narrow refracted rim on web. Explicit caller alpha is preserved. Native uses the same fill and sheen without refraction. See [Surface](./surface.mdx) and [Button](./button.mdx).
 
 The previous standalone `GlassSurface`, `GlassSurfaceProps` and `theme/glass-colors.ts` material have been removed. There is no replacement wrapper to mount around a Button. Existing overlay blur infrastructure remains under `@oxy.so/bloom/glass`: `GlassBlurTargetProvider`, `GlassBlurWindow`, and `useWindowedBlurTarget`.
 
@@ -23,10 +23,12 @@ SVG stops require separate `stopColor` and `stopOpacity`: native SVG can discard
 
 ## Floating islands
 
-`GlassIsland` keeps its grouping and geometry and paints with the same Surface material. Explicit glass groups share one translucent pane with flush controls. Plain sidebar surfaces and navigation rails keep their existing semantics.
+`GlassIsland` keeps its grouping and geometry and paints with the same Surface material. Groups share one translucent pane with flush controls. Plain sidebar surfaces and navigation rails keep their existing semantics.
 
-GlassIsland defaults to shared solid material and publishes its actual fill and contextual level. `material="glass"` explicitly enables translucent optics and publishes the tint composited against its parent as an estimate. Its ControlSurface material matches the selected material; glass groups pass that option explicitly.
+GlassIsland uses this same glass material and publishes its tint composited against the parent as an estimate for descendants. BloomScope carries density only.
 
 ## Shared geometry
 
 SurfacePaint replaces GlassSurface and accepts `shape` plus `direction` for logical corners. The host and material share the same Shapes policy, including CSS smooth corners, native continuous curves where supported, clipped paint and the rim. GlassIsland exposes `cornerCurve` for non-capsule shapes; capsules remain round. There is no separate glass geometry implementation.
+
+GlassIsland uses the same material resolver as Surface and Card. Radius precedence is explicit prop, then resolved `style.borderRadius`, then its capsule default; host and paint use the same result.

package/docs/input-group.mdx

@@ -84,7 +84,7 @@ text-field group itself.
     <InputGroupAddon>https://</InputGroupAddon>
     <TextFieldInput value={domain} onChangeText={setDomain} />
     <InputGroupAddon divider>
-      <Button size="small" variant="ghost" onPress={check}>Check</Button>
+      <Button size="sm"  onPress={check} tone="accent" appearance="subtle">Check</Button>
     </InputGroupAddon>
   </InputGroup>
 </Field>

package/docs/map-controls.mdx

@@ -30,7 +30,7 @@ Every group in the stack is a [`GlassIsland`](/docs/glass) and every control ins
 
 - the island paints rung 1 of the surface ladder at the chrome alpha, with the material's
   own hairline and shadow, so the stack moves with a preset change like everything else;
-- the island mounts a `ControlSurface` with `material: 'glass'`, so the items inside paint
+- the island mounts a `BloomScope` with `material: 'glass'`, so the items inside paint
   FLUSH with no `variant` written on any of them — the contract in
   [composition](/docs/composition);
 - `ButtonGroupItem` is Bloom's island-aware control. It carries a toggle's `aria-pressed`

package/docs/material-composition.mdx

@@ -5,7 +5,7 @@ description: Shared component bases, migrated surfaces and intentional exception
 
 # Material composition
 
-The default material is opaque: resolved fill, shared gradient and rim, without backdrop blur or refraction. A component keeps its layout, interaction and accessibility semantics; only its paint is shared. Explicit glass remains an opt-in experiment on Surface and Card. BottomBar is intrinsically translucent and shares the glass paint; it has no material variant. Its optional blur band remains independent.
+Surface has one shared material: a 90%-opaque body, gradient and rim, with subtle backdrop refraction on web. There is no solid/glass selector. A component keeps its layout, interaction and accessibility semantics; only its paint is shared. Semantic actions keep their fill and foreground pairs with the same subtle transparency. BottomBar's optional blur band remains independent.
 
 ## Choose the existing base
 
@@ -20,9 +20,9 @@ The default material is opaque: resolved fill, shared gradient and rim, without
 | Anchored overlay behavior | FloatingPanel | Web Popover, DropdownMenu, ContextMenu, Menubar, Select and HoverCard |
 | Modal/sheet behavior | Dialog / BottomSheet / SheetShell | AlertDialog, Command and existing native overlay adapters |
 
-`SurfacePaint` can own a supplied fill, or omit `fill` to add only the gradient and rim over a host-owned background. This preserves explicit consumer backgrounds and existing surface-level colors without painting a second opaque layer. Native uses one SVG, one base rectangle when needed and one sheen gradient; stop opacity remains explicit. Its IDs use the shared SSR-safe SVG helper. The web host hook adds a pseudo-element, not a wrapper, observer or per-frame work.
+`SurfacePaint` can own a supplied fill, or omit `fill` to add only the gradient and rim over a host-owned background. Hosts that hand their fill to the material stay transparent so they do not hide the backdrop. Explicit alpha is preserved; default fills retain 90% opacity. Native uses one SVG, one base rectangle when needed and one sheen gradient; stop opacity remains explicit. Its IDs use the shared SSR-safe SVG helper. The web host hook adds shared pseudo-elements, without a wrapper or a per-frame JavaScript loop. Backdrop filtering still incurs compositor cost per painted surface.
 
-Surface and painted Card resolve depth from the actual parent and publish the resolved backing through both React context and the web CSS variable. Plain transparent containers inherit; a plain explicit background publishes that backing without increasing the level. Material does not own padding, dimensions, geometry, elevation or state. Foreground/fill pairs stay with the semantic palette. A surface-level context must continue to describe the fill its descendants actually sit on. Never replace the parent's layout node just to paint material.
+Surface and painted Card resolve depth from the actual parent and publish the fill composited against that backing through both React context and the web CSS variable. Plain transparent containers inherit; a plain explicit background publishes that backing without increasing the level. Material does not own padding, dimensions, geometry, elevation or state. Foreground/fill pairs stay with the semantic palette. A surface-level context must continue to describe the fill its descendants actually sit on. Never replace the parent's layout node just to paint material.
 
 ## Intentional exceptions
 

package/docs/media-controls.mdx

@@ -47,7 +47,7 @@ The English defaults below are localised: each is drawn in the app's language vi
 | -------------------- | --------------------------------------------------------------------------------------------- |
 | `playing`            | draws the pause glyph and is named "Pause"; otherwise the play glyph and "Play"               |
 | `onPress`            | called on press — the button toggles nothing itself                                           |
-| `size`               | `'small'` 32, `'medium'` 48 (default), `'large'` 56 — the circle's diameter                    |
+| `size`               | `'sm'` 32, `'md'` 48 (default), `'lg'` 56 — the circle's diameter                    |
 | `variant`            | `'accent'` (default) filled accent; `'inverse'` filled in the text colour; `'plain'` the glyph alone, for rows |
 | `loading`            | a spinning ring replaces the glyph and `aria-busy` is set; the button still presses          |
 | `subject`            | appended to the name: "Play Night Drive"                                                      |
@@ -72,7 +72,7 @@ measures both paths rather than pinning a remembered number.
 | prop                        | decides                                                                  |
 | --------------------------- | ------------------------------------------------------------------------ |
 | `liked`, `onLikedChange`    | the state, and the callback with the next state                          |
-| `size`                      | glyph `'small'` 16 / `'medium'` 20 (default) / `'large'` 24; hit area 32 / 32 / 40 |
+| `size`                      | glyph `'sm'` 16 / `'md'` 20 (default) / `'lg'` 24; hit area 32 / 32 / 40 |
 | `activeColor`               | the liked heart's colour, default the theme accent                       |
 | `accessibilityLabel`        | the name, default "Save to Your Library" — fixed in both states         |
 | `disabled`, `style`, `testID` |                                                                        |
@@ -124,3 +124,5 @@ The speaker glyph follows the level: muted or 0, under 50%, and above. While mut
 ## `formatDuration(seconds)`
 
 `m:ss` under an hour, `h:mm:ss` from an hour. Fractions are floored; negative, `NaN` and infinite input give `0:00`.
+
+Control sizes inherit `BloomScope` when omitted; explicit sizes override it. Controls with `sm`/`md`/`lg` geometry map scoped `xs` to `sm`.

package/docs/media-header.mdx

@@ -184,4 +184,4 @@ Hover states (the edit overlay, underlined links, row washes) are web affordance
 paints on. As `neutral-500` it measured 4.38:1 on the light card. See
 [Styles → Quiet text](/docs/bloom/main/styles).
 
-`FollowButton` composes Bloom `Button` with a subtle surface. `tone="support"` (the default) uses the secondary palette; `tone="action"` uses the tertiary palette shared with FAB. `iconOnly` shows follow/following icons while retaining the accessible name and pressed state. Its two labels (or icons) slide and fade over 180 ms without changing width. Holding the control nudges the current label 2 px toward the next slide with a damped spring, without crossfading the labels. Releasing or cancelling springs back; activation alone requests the toggle and starts the label transition. Reduced motion skips the preview and switches state immediately. `loading` uses the shared Button spinner and blocks interaction while keeping both labels measured. `size` accepts `small`, `medium`, or `large`; `textStyle` applies to the labels and their measurement copies. The accessible name is `label` in both states unless you pass `accessibilityLabel`; pass a state-aware one ("Following @nate") with `accessibilityHint` ("Unfollows @nate") when the surface knows who the button is for, because TalkBack reads the pressed state as "selected", which does not say following.
+`FollowButton` composes Bloom `Button` with a subtle surface. `tone="support"` (the default) uses the secondary palette; `tone="action"` uses the tertiary palette shared with FAB. `iconOnly` shows follow/following icons while retaining the accessible name and pressed state. Its two labels (or icons) slide and fade over 180 ms without changing width. Holding the control nudges the current label 2 px toward the next slide with a damped spring, without crossfading the labels. Releasing or cancelling springs back; activation alone requests the toggle and starts the label transition. Reduced motion skips the preview and switches state immediately. `loading` uses the shared Button spinner and blocks interaction while keeping both labels measured. `size` accepts `sm`, `md`, or `lg` and inherits `BloomScope` when omitted; `textStyle` applies to the labels and their measurement copies. The accessible name is `label` in both states unless you pass `accessibilityLabel`; pass a state-aware one ("Following @nate") with `accessibilityHint` ("Unfollows @nate") when the surface knows who the button is for, because TalkBack reads the pressed state as "selected", which does not say following.

package/docs/media-player.mdx

@@ -70,9 +70,9 @@ A list of artists makes each credit a link when `onArtistPress(artist, index)` i
 
 | | play | glyphs | previous / next | hit box | gap |
 | --- | --- | --- | --- | --- | --- |
-| `compact` | 32 | 16 | 20 | 32 | 8 |
-| `regular` (default) | 48 | 20 | 24 | 32 | 16 |
-| `large` | 56 | 24 | 32 | 40 | 24 |
+| `sm` | 32 | 16 | 20 | 32 | 8 |
+| `md` (default) | 48 | 20 | 24 | 32 | 16 |
+| `lg` | 56 | 24 | 32 | 40 | 24 |
 
 - **music** — shuffle · previous · play · next · repeat. **podcast** — speed · back N · play · forward N · `trailing`.
 - The play button is `PlayButton` `inverse`, named "Play <subject>" / "Pause <subject>".
@@ -117,7 +117,7 @@ The desktop bar, full width at the bottom of the window.
 
 - **80 tall**, 16 side inset, the page background and a 1px neutral-200 (dark neutral-800) top rule.
 - **Left** — 56 cover (8 corner), title (a link with `onTitlePress`) with the explicit badge, artists, and the like button (with `onLikedChange`).
-- **Centre** (≤ 722) — `compact` transport over `PlaybackProgress` with times beside it.
+- **Centre** (≤ 722) — `sm` transport over `PlaybackProgress` with times beside it.
 - **Right** — lyrics (`RiMicLine`) and queue (`RiPlayListLine`) toggles, the device button, `VolumeControl`, fullscreen. Each shows when its handler is given.
 - **Device button** — with `devicePicker` it opens a `Popover` above itself holding that content (`devicePickerOpen` / `onDevicePickerOpenChange` to control it); otherwise it calls `onDevicePress`. It is lit (accent + dot) while `deviceName` is set, and its name adds the device.
 - **Collapse** — the bar measures its OWN width (seeded from the window): under **1024** the fullscreen button goes and the volume slider shortens to 64; under **768** lyrics, volume and the scrubber times go, the device button stays only while casting, and the actions column shrinks to what it draws.
@@ -191,7 +191,7 @@ The phone's expanded player and the desktop's immersive view. It **fills its par
 ```
 
 - **Top bar** — collapse chevron, "PLAYING FROM PLAYLIST" over "Night Drive", more.
-- **Narrow** — square artwork (16 corner, ≤ 480) over title + artists + like, the scrubber with times below it, the `large` transport spread to the column's width, and a row of device (with the device name while casting), share and queue.
+- **Narrow** — square artwork (16 corner, ≤ 480) over title + artists + like, the scrubber with times below it, the `lg` transport spread to the column's width, and a row of device (with the device name while casting), share and queue.
 - **Wide (≥ 900, measured)** — artwork and details side by side, 64 apart.
 - **The first screen is exactly the parent's height**, painted with a vertical gradient from the contrast-safe artwork tint to neutral-950. **Below the fold**, in the same scroll, a lyrics preview card (earlier lines dimmed up to `activeIndex`; a button when `onPress` is given) and the `aboutArtist` slot — side by side when wide.
 - **It is always dark.** Its content renders under the dark theme whatever the app's mode. A light app on a named preset gets that preset's dark accent; an app whose accent is a seed or scope keeps its accent as given.

package/docs/motion.mdx

@@ -103,3 +103,21 @@ polyfill as side-effectful but not that bridge. Storybook narrowly marks the rea
 `expo-modules-core/src/ensureNativeModulesAreInstalled.ts` module as side-effectful;
 it neither mocks Expo nor creates a replacement global. A minimal production
 bundle confirmed the installer precedes the first NativeModule read.
+
+### Intent recipes
+
+`MOTION_RECIPES` and `animateMotion(value, target, intent, reducedMotion?)` share
+press, select, expand, present and dismiss behavior. The helper retargets the
+existing shared value without resetting its position; selection and expansion
+use springs so rapid reversals remain interruptible. All recipes respect the
+system reduced-motion setting, and a true override settles immediately.
+Components retain geometry, gesture velocity and completion callbacks. Overlay
+presentation can retain its existing duration while sharing the accessibility
+policy; callbacks still run when Reanimated settles immediately.
+
+Screen collapse and TabBar minimization share the expansion recipe. Selected
+capsules share selection motion. Retained tab entries and ScreenTransition omit
+spatial transitions under reduced motion. Native Screen initializes keyboard
+visibility before reserving bottom chrome, including inherited shell clearance.
+Portaled overlays isolate screen navigation state while preserving theme and
+locale; scrolling their content cannot collapse the navigation behind them.

package/docs/navigation-banner.mdx

@@ -53,8 +53,8 @@ underneath is a night satellite tile or a white street map.
 It is asked for `radius: 16` rather than its default capsule. A banner is a
 surface; the pill rung belongs to button-like controls.
 
-The island also mounts the `ControlSurface` the controls inside it read, which
-is why nothing here writes `variant="glass"` on anything.
+The island also mounts the `BloomScope` the controls inside it read, which
+uses the shared Surface material without a material variant.
 
 ## The row
 

package/docs/note-editor.mdx

@@ -107,7 +107,7 @@ the label, the glyph and whether the state is on.
 
 ## Traps
 
-- **Toolbar items are 34px tall (`medium`) or 30 (`small`)**, which is below the
+- **Toolbar items are 34px tall (`md`) or 30 (`sm`)**, which is below the
   44 a touch target wants. That is `ButtonGroup`'s scale, not this family's;
   `hitSlop` is not the answer for adjacent items, because slop on one overlaps
   its neighbour and the press lands on whichever the platform hit-tests first.
@@ -116,3 +116,5 @@ the label, the glyph and whether the state is on.
   the base layer's spelling and this family does not work around it.
 - **`accessibilityLabel` on the toolbar is required in substance.** A row of
   glyphs has no name of its own, and each item is named by its `label`.
+
+Control sizes use `sm` and `md`. When omitted, they inherit `BloomScope`; `xs` maps to the compact rung and `lg` to the regular rung. An explicit size overrides the scope.

package/docs/page-header.mdx

@@ -44,7 +44,7 @@ Three things that used to be one flag are three props now:
 
 ### The islands are yours to declare
 
-The header never infers grouping from its children's types. The `actions` slot is wrapped in a `ControlSurface` with `material: 'glass'`, so a `ButtonGroup` placed there becomes one island with no prop written on it, two `ButtonGroup`s become two islands, and a `Button` keeps its own chrome — which is what a primary action in its own accent capsule should do.
+The header never infers grouping from its children's types. The `actions` slot is wrapped in a `BloomScope` with shared control defaults, so a `ButtonGroup` placed there becomes one island with no prop written on it, two `ButtonGroup`s become two islands, and a `Button` keeps its own chrome — which is what a primary action in its own accent capsule should do.
 
 ```tsx
 actions={
@@ -90,7 +90,7 @@ Leaving both at their defaults over a hero photo is the one combination that rea
 | `placement` | `'inline'` | `'overlay'` positions the header over the content and claims the top edge. |
 | `onBack` / `backLabel` | — / `"Back"` | `backLabel` is the button's accessible name — localise it. |
 | `leading` | — | After the back capsule, before the title (an avatar, a logo). |
-| `actions` | — | End of the bar. Floating: wrapped in a glass `ControlSurface`. |
+| `actions` | — | End of the bar. Floating: wrapped in a glass `BloomScope`. |
 | `scrim` | `'auto'` | `presentation="floating"` only. `auto` \| `always` \| `none`. |
 | `scrimColor` | `theme.colors.background` | The opaque colour the edge effect fades from. Pass it when the screen paints a background the theme does not know about. |
 | `border` | `'auto'` | `presentation="bar"` only. `auto` fades the separator in with scroll; `always`; `none`. |
@@ -104,7 +104,7 @@ Leaving both at their defaults over a hero photo is the one combination that rea
 
 - Bar min-height 56; side inset 16 below `sm`, 24 from `sm` — measured against the header's **container**, not the window, so a narrow desktop panel gets the narrow inset.
 - Islands are 36 tall (a 34 control plus the hairline), 8 apart. The back capsule carries 4px of hit slop on every side, which makes it a 44pt target with nothing beside it to steal from. **A grouped item is 34 × 34 with no slop** — items in a group are adjacent, and slop on one overlaps its neighbour. Where the 44pt floor matters for every action, give each one its own island instead of grouping them.
-- Island material: rung 1 of the surface ladder (the fill a card and a menu panel paint) at the chrome alpha — 0.72 light, 0.80 dark. See [Glass](/docs/glass) for what those two numbers buy and cost.
+- Island material: the shared Surface body, sheen and rim. Default fills use 90% opacity; web refraction is visible around the edge. See [Glass](/docs/glass).
 - Title `headline-medium` text-primary, subtitle `body-2-regular` secondary. Both truncate to one line.
 - `bar`: background `background/full` (card; dark neutral-925), separator 1px (neutral-200; dark neutral-800), shadow `shadow-xs` once scrolled.
 - No press scale. Every fade is scroll-linked, not timed, so there is no motion to reduce.
@@ -172,41 +172,12 @@ The context is what makes a desktop panel work: `window.scrollY` never moves ins
 - The container carries no landmark role. `role="banner"` would be one banner per header, and an app shell already owns the page's banner; a page header inside `main` is not a landmark in HTML either.
 - The back button is named by `backLabel`. Its island carries no `role="group"` — a group of one is a container a screen reader steps into for nothing.
 - The gradient is `pointerEvents: none` and is not in the accessibility tree. The bar and the actions row are `box-none`, so the gaps between islands stay transparent to touch — a floating header covers content it does not own, and an invisible rectangle that swallowed presses across the screen would be total and silent.
-- **Reduced transparency is not yet wired.** The islands are translucent on every device. Where the platform reports a reduce-transparency preference, Bloom does not currently read it; the material is legible over both ends of the backdrop range (see [Glass](/docs/glass)), but that is a legibility argument, not the preference being honoured.
+- Reduced-transparency preferences are not currently read. Default island bodies use 90% opacity; explicit alpha remains a caller choice.
 
 ## Platform notes
 
-- **Web.** The material is `backdrop-filter` through `expo-blur`'s real web build; the gradient is `react-native-svg`. A browser without `backdrop-filter` still gets the tint and the hairline — the island keeps its geometry and its legibility, it just stops blurring.
-- **iOS.** `expo-blur` provides the radius. `expo-glass-effect` is NOT used here; the tab bar is the only family on it.
-- **Android.** The islands paint tint, hairline, sheen and rim with **no blur**, deliberately. `expo-blur` needs a `blurTarget` pointing at a `BlurTargetView` wrapping the content to blur, and a `BlurView` that is a descendant of the view it points at takes the process down with SIGSEGV — which is the only topology available to a surface that fills its own caller. The mechanism is in [Glass](/docs/glass); it has not changed for this header.
-
-## What was measured, and where
-
-Everything about a translucent surface that matters is a property of **painted pixels**, and jest sees markup. `scripts/verify-header-islands.mjs` drives a real Chrome over the Storybook stories, screenshots them, reloads the PNG into the page and samples a canvas — the round trip being the only way to read the composited result of a `backdrop-filter`, which exists nowhere in the DOM.
-
-```bash
-bun run storybook
-node scripts/verify-header-islands.mjs --out docs/page-header-islands.png
-```
-
-Measured at 900 × 780, device scale 1, on the `teal` preset:
-
-| property | how | result |
-| --- | --- | --- |
-| islands, not a strip | runs of chrome ≥20px along a line through the bar | **2** light (48, 126), **3** dark (36, 70, 36) |
-| the island is translucent | the same back capsule over the page and over a photograph | moved **35** of 255 |
-| the edge ends in nothing | the ramp against a deliberately mismatched scrim colour | travelled **67** of 255 |
-| no horizontal cut | the largest single-row step down that ramp | **2** of 255 |
-| a matched scrim is invisible | the same ramp with `scrimColor` = the page colour | travelled **0** |
-| control | the same row sampler on `presentation="bar"` | **0** runs — a strip is one colour |
-
-Three of those readings deserve their real explanation rather than a round number.
-
-The ramp is measured against a **deliberately mismatched** `scrimColor`, because that is the only configuration in which its shape is visible at all: a correctly configured scrim is the page's own colour, so over the page it paints nothing and its profile is a flat line. The row below it measures exactly that — the same header, the same `scrim="always"`, the colour handed over, travelling 0.
-
-In **light** mode the sampler reports two island runs, not three: the two action islands are 8px apart and their drop shadows meet in the gap, so at a 1-level tolerance the gap is not backdrop. The gap is visible; it is not *measurably* backdrop. In **dark** mode, where the shadow is weaker against a dark page, all three separate cleanly.
-
-And the island fill in light mode is the card fill over a near-white page — the same relation a `Card` has to the page, read by its hairline and shadow rather than by its fill. That is deliberate, and it is why an island reads as Bloom chrome rather than as a new material.
+- **Web.** Shared Surface CSS uses backdrop blur and SVG displacement at the rim, with a 90%-opaque body and sheen. Without filter support, the body and decorative rim remain.
+- **iOS and Android.** Shared SurfacePaint draws the body, sheen and rim without refraction or inline blur. Outer shadows remain unclipped.
 
 ![The floating header over a list, light](./page-header-islands.png)
 
@@ -216,7 +187,7 @@ And the island fill in light mode is the card fill over a near-white page — th
 
 ![The islands over a photograph, title held back](./page-header-islands-photo.png)
 
-**Not verified on a device.** Every number above is Chrome on Linux. iOS and Android have not been run for this change: the material is `expo-blur` on both and is unchanged from the `GlassSurface` the library already shipped, but the geometry, the safe-area padding, the top-edge claim and the scroll linkage have only been exercised in jest and in a browser. Android additionally paints **no blur at all** here, by the design described above, so what a device would show is the tint, the hairline, the sheen and the rim.
+**Not verified on a device.** The historical measurements above are Chrome on Linux. Native geometry, safe-area padding and scroll linkage still need device verification; native SurfacePaint does not refract the backdrop.
 
 ## Not included
 
@@ -234,7 +205,7 @@ And the island fill in light mode is the card fill over a near-white page — th
 
 **`border` and `transparent` apply to `presentation="bar"` only.** They are ignored by the floating presentation, which has no strip and no separator; `scrim` is its counterpart.
 
-**Icon actions want `ButtonGroupItem`.** A `Button appearance="outline" tone="neutral"` in a floating header's actions paints its own opaque fill, which reads as a card floating over the content. It still works; it is just not the shape the islands are for.
+**Icon actions want `ButtonGroupItem`.** A `Button appearance="outline" tone="neutral"` in a floating header's actions paints its own shared translucent Surface. It still works; it is just not the shape the islands are for.
 
 ## Migrating from app headers
 

package/docs/payment-status.mdx

@@ -10,10 +10,10 @@ order: 139
 import { PaymentStatusBar, PaymentStatusBlock } from '@oxy.so/bloom/payment-status';
 
 <PaymentStatusBar state="failed" amount="€48.00" detail="Your bank turned this one down."
-  action={<Button size="sm" variant="outline" onPress={retry}>Retry</Button>} />
+  action={<Button size="sm"  onPress={retry} tone="neutral" appearance="outline">Retry</Button>} />
 
 <PaymentStatusBlock state="paid" amount="€48.00" detail="Aurora •••• 4417"
-  reference="8F2K-41QD-7T" actions={<Button variant="outline" onPress={open}>View receipt</Button>} />
+  reference="8F2K-41QD-7T" actions={<Button  onPress={open} tone="neutral" appearance="outline">View receipt</Button>} />
 ```
 
 ## Five states, and they are the five you DRAW

package/docs/phone-input.mdx

@@ -109,5 +109,5 @@ list operable.
 ```
 
 `size` is passed straight to the `TextField` inside, which inherits density from a
-`ControlSurface` — so a small filter row makes the phone field small without a
+`BloomScope` — so a small filter row makes the phone field small without a
 prop here. See [Composition](/docs/composition).

package/docs/popover.mdx

@@ -27,7 +27,7 @@ import { Button } from '@oxy.so/bloom/button';
 
 <Popover>
   <PopoverTrigger asChild label="What is this?">
-    <Button variant="secondary">What is this?</Button>
+    <Button  tone="neutral" appearance="outline">What is this?</Button>
   </PopoverTrigger>
 
   <PopoverContent label="Two-factor authentication" align="start">

package/docs/queue-panel.mdx

@@ -125,3 +125,7 @@ In `panel` variant the family wraps its content in `SurfaceLevelProvider level={
 ([Styles → Ambient level](/docs/bloom/main/styles)), so a control inside steps off
 the PANEL rather than off the page. Without it a `Tabs` strip inside painted its
 rail `neutral-800` — the panel's own fill, ΔE 0.
+
+### Shared surface paint
+
+The painted host delegates its fill to Surface: a 90%-opacity body with a subtle refracted edge on web, plus the shared sheen and rim. The host itself stays transparent to avoid painting twice. Explicit alpha colours retain their alpha; descendants receive the corresponding composited fill. Plain or unframed content keeps its existing layout behavior.

package/docs/radio.mdx

@@ -116,3 +116,8 @@ Both the row's dot ring and `RadioCard`'s ring take their 2px gap from
 `var(--bloom-ring-offset)`, set inline from the surface behind the control. It
 was a hardcoded `#FFFFFF` — a white halo in dark mode. See
 [Styles → The focus ring gap](/docs/bloom/main/styles).
+
+
+`Radio` and `RadioCard` use `checked` and `onValueChange`: choosing an option reports its value, never a false toggle. `RadioGroup` accepts controlled `value` or uncontrolled `defaultValue`. The duplicate `selected` and `onSelect` props have been removed.
+
+An explicitly supplied `value={undefined}` is a controlled empty selection. Omit `value` to opt into uncontrolled state with `defaultValue`; callbacks do not commit a controlled selection until its parent updates the prop.

package/docs/rating.mdx

@@ -108,7 +108,7 @@ while nothing is chosen, and `onChange` fires with the star that was chosen.
 | `value`              | the chosen rating, or `null` for nothing chosen yet                                          |
 | `onChange`           | called with the chosen rating; never called with the value already chosen                    |
 | `max`                | how many stars, default `5`                                                                  |
-| `size`               | `'small'` (24px star), `'medium'` (default, 32) or `'large'` (40)                            |
+| `size`               | `'sm'` (24px star), `'md'` (default, 32) or `'lg'` (40)                            |
 | `disabled`           | no press, no keyboard, the group at `DISABLED_OPACITY`                                       |
 | `accessibilityLabel` | **required** — the name of what is being rated ("Overall rating")                            |
 | `formatStarLabel`    | each star's own name, English `"1 star"` / `"4 stars"`, localised via `BloomProvider locale` |
@@ -156,3 +156,5 @@ prop is optional:
 ```
 
 The field's `disabled` freezes the whole row, including the hover preview.
+
+Control sizes inherit `BloomScope` when omitted; explicit sizes override it. Controls with `sm`/`md`/`lg` geometry map scoped `xs` to `sm`.

package/docs/screen.mdx

@@ -88,3 +88,10 @@ Full-screen stories that demonstrate document scrolling declare
 uses a minimum viewport height, allowing the document to grow. Contained demos
 keep a bounded height. This is a preview host choice, not an application prop;
 consumer roots must likewise allow the document to grow.
+
+Native keyboard visibility is read on mount, so a screen opened while the
+keyboard is already visible does not briefly reserve bottom navigation. While
+visible, both owned and inherited bottom chrome leave only content clearance.
+`ScreenScope` also isolates navigation progress and scroll ownership; overlays
+mount this shared boundary automatically while retaining theme, locale and
+`BloomScope` appearance.

package/docs/segmented-control.mdx

@@ -127,6 +127,6 @@ Taps and keyboard activation preserve radio/tab semantics. Settling respects the
 system reduced-motion preference. Native apps mount `GestureHandlerRootView` at
 the application root, as for BottomBar. The plain variant also accepts dragging.
 
-## 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).

package/docs/select.mdx

@@ -210,3 +210,8 @@ The web option reserves a 30px indicator gutter and paints the indicator into it
 Composing would mean flattening one of those two, and both are visible: the first as a label that jumps sideways on selection, the second as a selected row painted in a colour no other menu row uses. So select keeps its own row, and `radio-indicator` stays the one indicator both it and `Radio` draw.
 
 Inside a required Field, the trigger announces the localized required constraint through a description on web and a native accessibility hint. It remains a menu button; `aria-required` is reserved for roles that support it.
+
+
+`value` controls selection; `defaultValue` initializes uncontrolled selection. `onValueChange` reports changes in either mode. Size inherits from the nearest `BloomScope`; an explicit `size` wins.
+
+An explicitly supplied `value={undefined}` is a controlled empty selection. Omit `value` to opt into uncontrolled state with `defaultValue`; callbacks do not commit a controlled selection until its parent updates the prop.

package/docs/shipment-request.mdx

@@ -21,7 +21,7 @@ import {
   photos={{ photos, onReorder, onRemove, onAdd }}
   options={{ extras, selectedExtras, onExtrasChange, accessOptions, access, onAccessChange }}
   price={{ lines, total }}
-  footer={<Button variant="primary" size="large" fullWidth onPress={submit}>Ask for quotes</Button>}
+  footer={<Button  size="lg" fullWidth onPress={submit} tone="accent" appearance="solid">Ask for quotes</Button>}
 />
 ```
 

package/docs/sidebar.mdx

@@ -281,4 +281,8 @@ which also moves its footer. The default `start` preserves existing placement.
 
 ## Shared material
 
-Card and docked sidebar surfaces paint the shared opaque Surface material with its gradient and rim beneath their contents; plain surfaces and the navigation rail retain their existing fill. The current logo, modes, scoped sizes, tree, custom content, RTL layout, safe edges and scroll behavior are unchanged. Storybook: **Blocks / Sidebar / Glass Panel**.
+Card and docked sidebar surfaces paint the shared Surface material at 90% body opacity with its gradient and rim beneath their contents; plain surfaces and the navigation rail retain their existing fill. The current logo, modes, scoped sizes, tree, custom content, RTL layout, safe edges and scroll behavior are unchanged. Storybook: **Blocks / Sidebar / Glass Panel**.
+
+### Shared surface paint
+
+The painted host delegates its fill to Surface: a 90%-opacity body with a subtle refracted edge on web, plus the shared sheen and rim. The host itself stays transparent to avoid painting twice. Explicit alpha colours retain their alpha; descendants receive the corresponding composited fill. Plain or unframed content keeps its existing layout behavior.