@oxy.so/bloom 3.6.0 → 4.1.0

package/docs/directions.mdx

@@ -0,0 +1,109 @@
+---
+title: Directions
+description: Getting there — the chosen route as a figure with its alternates, the turn list grouped by leg with a maneuver glyph and a current step, and a transit line's own badge.
+order: 135
+---
+
+# Directions
+
+```tsx
+import { DirectionsSummary, DirectionsSteps } from '@oxy.so/bloom/directions';
+
+<DirectionsSummary
+  routes={routes}
+  selectedRouteId={chosen}
+  onSelectRoute={setChosen}
+  stops={stops}
+  onSwapStops={swap}
+  modes={['drive', 'transit', 'walk', 'cycle']}
+  mode={mode}
+  onModeChange={setMode}
+  onStart={navigate}
+/>
+<DirectionsSteps legs={legs} currentStepId={current} />
+```
+
+## What this family does NOT draw
+
+- **The origin and the destination.** They are [`RouteStops`](/docs/route-stops), which
+  already owns the marker column, the connector, the swap and the reached/current/pending
+  states. `DirectionsSummary` renders it from `stops` and draws no second header. Without
+  `stops` it draws no header at all, for an app whose screen already shows them.
+- **The mode switcher.** A switcher of views is `SegmentedControl`. The four modes are
+  data (`DIRECTIONS_MODE_LABELS`, `DIRECTIONS_MODE_ICON`), not four components.
+- **A row.** Every route alternate and every turn step is an
+  [`AddressRow`](/docs/address) — the row, the glyph tile, the press target, the density
+  rungs, the trailing `meta` and the disabled opacity are `Item`'s, through it. This
+  family adds a glyph table and the words.
+- **A map.** There is no engine, no projection and no tile here.
+
+## The duration is the figure
+
+Nobody leaves the house because a place is 8.2 km away. `DirectionsSummary` leads with the
+DURATION at `title-1`, tabular, under a quiet label — the figure block
+[`ai-profile-card`](/docs/ai-profile-card) uses — with the distance as a `Chip` and the
+traffic as a `Badge` on its tone beside it. The arrival time and the via line follow as two
+quiet readings, each a 16 glyph and a line of secondary text.
+
+`traffic: 'light'` is `success`, not `default`. A clear road is good news and the reader is
+scanning for it; a neutral pill beside a red one reads as "no information" rather than as
+"clear".
+
+## The chosen route is not in the alternates
+
+It is drawn in full above them, and a route shown twice is a reader wondering whether they
+are two. That is also why the alternates are a `list` of pressable rows and not a
+`radiogroup`: a radio group whose checked member is missing announces a choice with nothing
+chosen. A press on a row CHOOSES it, which swaps it into the figure.
+
+## The maneuver glyphs, and the two that are mirrored
+
+A maneuver set is symmetric — a right turn IS a left turn seen from the other side — and
+Bloom's icon set carries one side of each pair. `right` is `RiCornerUpLeftLine` mirrored
+about its own centre (`scaleX: -1`), and `slight-left` is `RiArrowRightUpLine` mirrored.
+
+**Mirroring is the correct answer here, not a shortcut.** The alternative is picking a
+different glyph that happens to point the right way, and it does not share the partner's
+stroke weight, arrowhead or corner radius — the pair then reads as coming from two icon
+sets. A mirror moves nothing and needs no offset.
+
+Each mirrored component is built ONCE at module scope. Built inside a render it would be a
+new component type on every frame, and React would unmount and remount the SVG each time.
+
+The table is `DIRECTIONS_MANEUVER_ICON`; the words are `DIRECTIONS_MANEUVER_LABELS`, and
+they are announced BEFORE the instruction because a glyph says nothing aloud. That is the
+same hole `RouteStops` fills for its marker shapes.
+
+## The current step
+
+It wears the accent's own `subtle` wash, painted through the row's `style` — **not through
+`selected`**. `Item` maps `selected` on a row with no role to `aria-pressed`, and a turn
+instruction is not a toggle: a screen reader would announce every step as "not pressed".
+
+The state a step carries is "this is where you are", which ARIA has no attribute for on a
+list row, so it travels in the NAME instead (`currentLabel`, default "Current step"),
+where it is certain to be heard.
+
+## Where a step's name goes
+
+Exactly as in `RouteStops`, and for the same reason: a pressable step is a button and
+carries its own name; a read-only one renders `role="none"`, which assistive technology is
+told to ignore, so the name goes on the `listitem` around it. Naming both would read every
+step twice.
+
+## Transit
+
+A leg header carries its mode glyph, its title at the section rung, its line badge and its
+reading. `TransitLineBadge` is Bloom's `Badge` with two colours overridden and nothing
+else — the same construction `listing-card`'s status pill uses, because an operator's line
+colour is DATA the app owns and only the fill and the label may come from outside the
+palette.
+
+**The label is measured, not derived.** `readableOn` picks whichever end of the theme's own
+reading pair clears more contrast against the operator's fill, in both modes — a derived
+label (lighten the fill until it clears AA) invents a colour that is in no palette, and on
+a saturated operator red it lands on pink. A line with no colour is the plain neutral
+badge, which is the right answer for an operator that publishes none.
+
+The badge shows two characters and says a sentence: `describeTransitLine` gives it
+"Line L4, towards Pla del Bosc".

package/docs/dropdown-menu.mdx

@@ -28,7 +28,7 @@ import { Button } from '@oxy.so/bloom/button';
 
 <DropdownMenu>
   <DropdownMenuTrigger asChild label="Open menu">
-    <Button variant="secondary">Open menu</Button>
+    <Button appearance="outline" tone="neutral">Open menu</Button>
   </DropdownMenuTrigger>
 
   <DropdownMenuContent>
@@ -40,7 +40,7 @@ import { Button } from '@oxy.so/bloom/button';
     </DropdownMenuItem>
     <DropdownMenuItem disabled>Billing</DropdownMenuItem>
     <DropdownMenuSeparator />
-    <DropdownMenuItem variant="destructive" onPress={signOut}>
+    <DropdownMenuItem tone="danger" onPress={signOut}>
       Sign out
     </DropdownMenuItem>
   </DropdownMenuContent>
@@ -55,7 +55,7 @@ A row dismisses the menu after it fires. Pass `keepOpen` to a row that should no
 
 ```tsx
 <DropdownMenuTrigger asChild label="Actions">
-  <Button variant="icon" onPress={track}>…</Button>
+  <Button onPress={track} appearance="outline" tone="neutral">…</Button>
 </DropdownMenuTrigger>
 ```
 

package/docs/earnings.mdx

@@ -0,0 +1,87 @@
+---
+title: Earnings
+description: What the work paid — the period's figure and its bars through the earnings chart card, the readings under it, the breakdown by kind, and the next payout with its date and state.
+order: 138
+---
+
+# Earnings
+
+```tsx
+import { EarningsSummary } from '@oxy.so/bloom/earnings';
+
+<EarningsSummary periods={[day, week, month]} defaultPeriod="week" formatAxisValue={euros} />
+```
+
+`EarningsSummary` is the whole panel. `EarningsBreakdown` and `EarningsPayoutRow` are two of its four parts, published because a screen often wants one of them alone.
+
+## It is built AROUND the chart card, not beside it
+
+`chart-cards`' `EarningsChartCard` is already four of the five things a courier's earnings screen needs: the period's figure, the change on the period before, the Day / Week / Month switch and the bars of the last weeks. Drawing a second figure and a second switch above it would have put two of everything on one panel and left the reader to work out which one was authoritative.
+
+So this family draws none of that. It hands the chart card the selected period's data and adds the three things the chart card has no opinion about:
+
+```
+EarningsChartCard    the switch, the figure, the delta chip, the bars
+tiles                the period's other readings
+EarningsBreakdown    where the money came from
+EarningsPayoutRow    when it reaches the bank
+```
+
+The tiles are `ai-profile-card`'s stat tile exactly — radius 10, padding 10, the reading over its label, one row from 640 and two columns below. A courier's "68 jobs done" and a profile's "9B lifetime tokens" are the same object, and a second tile geometry would be a second answer to one question.
+
+The breakdown is `price-breakdown`'s `PriceSummary` under a heading, for the same reason. A courier's earnings are an ITEMISATION — jobs, tips, bonuses, adjustments, each a label and an amount the app formatted — which is a fare's itemisation seen from the other side. Writing a second list of label-and-amount rows here would give Bloom two of those, and only one of them would know about `estimated`, `pending`, the discount tone and the info popover.
+
+## No total under the breakdown
+
+Inside `EarningsSummary` the figure above the chart already IS the total, so `EarningsBreakdown` is given no `total` and draws the kinds with no rule. Pass `total` when you use the breakdown on its own.
+
+## The money is never computed, and the headline is the proof
+
+A bar carries BOTH a number and an amount, and they are not the same fact:
+
+```tsx
+{ label: 'Fri', value: 132.4, amount: '€132.40' }
+```
+
+`value` is GEOMETRY — how tall the bar is — and is never drawn. `amount` is what the reader sees.
+
+`EarningsChartCard` formats its headline from a number, which is exactly what this family must not do. So the headline is CHOSEN rather than produced: the panel owns the chart's active bar, and `format` returns the period's own `total` at rest and the hovered bar's own `amount` over a bar. `earningsHeadline` is that choice, and it is a pure function so its boundaries — no bars, an index past the end, an index that outlived its data — are reachable by a test.
+
+Two consequences, both deliberate:
+
+- **The headline does not roll.** `ChartHeadline` counts a number up over 320ms; a pre-formatted amount has nothing to count. The 220ms fade still plays, so the change is still visible.
+- **The Y axis prints a number.** A tick is a position on a scale the chart chose, not a sum the app made, so no string exists for it to have formatted. The default prints the rounded number with nobody's currency on it; **`formatAxisValue` is where an app puts its own**, and an app that forgets it gets a bare axis rather than a wrong currency.
+
+## What jest cannot see, and where it is checked instead
+
+`earningsHeadline` is pure, so the CHOICE is pinned in `src/__tests__/Earnings.test.tsx` at every boundary. The other half — that the panel actually owns the chart's active bar and re-reads the headline from it — is driven by pointer events on a plot surface that only exists after `onLayout`, and jsdom fires no layout. Measured: gutting `setActiveIndex` to a no-op left that whole suite green.
+
+So it is `scripts/verify-earnings-headline.mjs`: a real Chrome, `page.mouse.move` over three bars of different value, reading the emitted headline. It also runs the case the pure test cannot reach — that no reading is ever the raw number the bar was SIZED by, which is what a `format` falling back to its argument would produce and what would still look plausible on screen. The axis words are checked the same way, and for the same reason.
+
+## The period is controlled here, and the chart is remounted to follow it
+
+`useChartRange` inside `chart-cards` is uncontrolled: it takes a `defaultRange` and there is no `range`. A period changed from outside the panel therefore cannot reach the chart card's own segmented control, and the switch and the panel would disagree with nothing to say so.
+
+The chart is keyed on the period id, which remounts it with the new default. The cost is that the bars grow in again instead of morphing across the switch. **This is a gap in `chart-cards`, recorded rather than worked around silently** — the fix is a controlled `range` prop on `useChartRange`, and it is not made here.
+
+## Payout states
+
+Five, because "not in the account yet" is four different situations and a courier acts differently on each.
+
+| state | tone | means |
+| --- | --- | --- |
+| `scheduled` | default | waiting; nothing to do |
+| `processing` | info | already moving; nothing to do |
+| `paid` | success | done |
+| `held` | warning | the reader has to do something, and the money is still coming |
+| `failed` | error | the reader has to fix something |
+
+**The state is said in words, not only in colour.** The badge carries the word and the tone is a second channel on top of it. `note` is drawn only for `held` and `failed` — a sentence on a scheduled payout is one nobody has to read.
+
+The row is an `item`, not a card: `item` already owns the press target, the density, the slots and the disabled wash, and what this component decides is what goes in them.
+
+## Traps
+
+- **A period carries everything it says.** `total`, `bars`, `lines`, `stats` and `payout` are all the period's own, so switching the segment replaces the whole panel. A payout that does not change with the period is written once, at the panel level.
+- **`deltaRatio` is a RATIO, not money.** `0.148` is up 14.8%. A percentage is not somebody's currency, so it is the one number here that is allowed to be formatted downstream.
+- **A period id that names nothing falls back to the FIRST period**, never to nothing. An empty figure reads as "you earned nothing" rather than as "this app asked for a period that is not on the list".

package/docs/empty-state.mdx

@@ -0,0 +1,89 @@
+---
+title: Empty state
+description: Nothing to show, said once — a glyph or an illustration, a title, a line of explanation and up to two actions, at a screen rung and a panel rung.
+order: 48
+---
+
+# Empty state
+
+A list with nothing in it still has to say something, and until this family existed every
+list in Bloom said it differently. Twelve components had each drawn their own block: five
+of them the same glyph-over-headline-over-line, at five paddings and four maximum widths,
+under six spellings of the same two strings — `emptyTitle`/`emptyDescription`,
+`emptyMessage`, `emptyQueueHint`, `emptyLabel`, `emptyText`, `noResultsLabel`.
+
+```tsx
+import { EmptyState } from '@oxy.so/bloom/empty-state';
+import { RiInbox2Line } from '@oxy.so/bloom/icons/RiInbox2Line';
+
+<EmptyState
+  icon={RiInbox2Line}
+  title="Nothing in this folder"
+  description="Mail you file here will show up in this list."
+  action={{ label: 'Write a message', onPress: compose }}
+/>;
+```
+
+## The two rungs are about WHERE, not about how much there is to say
+
+`comfortable` is the screen: a 32 glyph, a headline, 48 of air above and below, and the
+text capped at 360. `compact` is the panel — a side panel, a popover, a card that is
+already inside something: a 24 glyph, a body title, 24 of air, capped at 280. Nothing
+else changes, so a list that moves from a screen into a panel changes a prop and not a
+component.
+
+The 360 is the number worth defending. The five hand-rolled blocks this family replaces
+used 280, 260, 360, 340 and none, and the one with none is the reason: a centred line of
+explanation that runs the full width of a 1440 page needs a second fixation per line, and
+every author who noticed picked a different cap. 360 is roughly sixty characters at
+`body-regular`.
+
+## The mark: three ways, and when each is right
+
+- **`icon` + `media="glyph"`** (the default) is the bare mark in the GRAPHICAL rung —
+  `textGraphical`, the ladder stop sized for a line rather than for text, so it clears
+  3:1 on whatever surface the block was dropped on. It is the quiet answer, right when
+  the empty state is REPORTING (a filter matched nothing, a folder is empty).
+- **`icon` + `media="circle"`** is `IconCircle`, the tinted disc. Louder; right when the
+  block is the whole screen, or when it is INVITING rather than reporting.
+- **`illustration`** is an arbitrary node and wins over `icon`, drawn exactly as it comes
+  with no tile of its own. It is read for PRESENCE, so `illustration={null}` draws no
+  mark at all even when an `icon` arrived from a default two levels up.
+
+There is no fourth. A neutral "well" and a tinted disc side by side were two answers to
+one question, and both shipped in this repo.
+
+## The actions are DATA, and there are at most two
+
+A node would have worked — the six blocks this replaces each passed one, which is how
+three of them ended up with three different button sizes for the same button. As
+`EmptyStateAction` the family owns the size (medium, or small at the panel rung), the
+order and the wrap; the caller owns the words and the handler. Anything that is not a
+button — a row of suggestion pills, a link, a note — goes in `footer`, under them.
+
+`children` is the third slot, between the explanation and the actions. It is stretched to
+the block's full width and left to lay itself out, because what goes there is a strip, a
+fact box or a list rather than centred text. `order-confirmation` is built on exactly
+that: a "done" screen is the same object as a "nothing here" screen with a different
+reason for existing.
+
+## It is ONE named group
+
+The whole block carries `role="group"` named by the title and the description joined. A
+screen reader that reaches an empty list should be told the situation; a heading, a
+paragraph and a button with nothing joining them are three stops that each say a third of
+it. The glyph is hidden from assistive technology — it repeats what the title says, and
+an unnamed image between a heading and its paragraph is a stop that announces nothing.
+
+## `minHeight` is for holding a band open
+
+A table body, a panel that must not collapse. The content centres in it. Without it the
+block is exactly as tall as what it contains, which is what a list wants.
+
+## Migrating a hand-rolled one
+
+Not done yet, and deliberately: this family is designed to cover the existing call sites
+as they stand, and moving them is a separate change with its own screenshots. The ones it
+was measured against are `cart-panel`'s `EmptyBasket`, `carrier-quote`'s empty offers
+list, `mail-list`, `chat-list`, `address`'s `AddressList` and `data-table`'s empty band —
+six shapes between them, from a 32-glyph column to a text-only 160-tall band.

package/docs/fab.mdx

@@ -1,79 +1,51 @@
----
-title: Fab
-description: The floating action button — one per screen, for the screen's primary action.
-order: 43
----
-
 # Fab
 
-A floating button for the **one** thing a screen is mostly for: compose on a
-feed, add on a list, new message in an inbox.
+`Fab` is a prominent action built on `Button`. It shares color, focus, loading,
+press and accessibility behavior. Its parent owns placement.
 
 ```tsx
 import { Fab } from '@oxy.so/bloom/fab';
+import * as Icons from '@oxy.so/bloom/icons';
 
-<Fab
-  icon={<PencilIcon />}
-  accessibilityLabel="New post"
-  onPress={compose}
-/>
-
-<Fab
-  icon={<PencilIcon />}
-  label="New post"
-  placement="bottom-right"
-  onPress={compose}
-/>
+<Fab icon={Icons.RiAddLine} accessibilityLabel="Create post" onPress={createPost} />
+<Fab icon={Icons.RiAddLine} label="Compose" tone="action" appearance="solid" />
 ```
 
-## Which prop decides what
-
-| prop               | decides                                                    |
-| ------------------ | ---------------------------------------------------------- |
-| `icon`             | the glyph                                                   |
-| `label`            | makes it an extended FAB with visible text                  |
-| `variant`          | `primary` · `secondary` · `tertiary` · `surface`            |
-| `size`             | `small` · `medium` · `large`, or a number                   |
-| `placement`        | which corner it floats in, or `static` to place it yourself |
-| `offset`           | distance from the edges                                     |
-| `minimizeBehavior` | `none` · `hide` · `collapse` with the nearest Bloom tab bar |
-
-## An icon-only FAB needs `accessibilityLabel`
-
-Without it the button announces as "button" and nothing else. A pencil is not
-self-describing to a screen reader, and it is not always self-describing on
-screen either — which is what `label` is for.
+`size` is `xs | sm | md | lg` (40, 48, 50, 64 points; default `md`). The corresponding glyphs are20,24,26,32points. The default50/26 geometry is shared by standalone, sidebar, Screen and BottomBar actions. `iconSize` optionally sets the glyph dimensions independently; for example, `size={50} iconSize={26}`. The collapsed circle keeps its requested diameter and adjusts its padding around the glyph.
+`size` and `tone` inherit from `BloomScope`. `tone` defaults to `action`;
+`appearance` defaults to `solid` and also accepts `subtle`, `outline`, `plain`.
+Icon props take a component, which receives its size and foreground color.
+Icon-only actions require `accessibilityLabel`; labeled actions use their label.
 
-## One per screen
+An explicit tone wins over `BloomScope`, which wins over the `action` default. A utility such as “Back to top” can use `tone="neutral" appearance="subtle"`. The Color roles prototype demonstrates an action Fab alongside accent navigation and subtle support surfaces.
 
-A FAB claims the corner and floats above the content. Two of them are two
-primary actions, which means neither is primary, and they compete for the same
-thumb position. If a screen has several important actions, the FAB takes the
-most common one and the rest go in the content or a menu.
+Use `AppShell.primaryAction` to coordinate a screen action with navigation, or
+`BottomBar.action` for a custom bottom composition. A standalone Fab stays in
+normal flow and accepts the usual `style` and `className` layout overrides.
 
-On web, a bottom placement stays inside the content column with sticky
-positioning. The column must fill the available height, use flex-column layout,
-and render the FAB last. This keeps it at the bottom with short content and in
-view while the document scrolls, without escaping over a side rail. Top
-placements remain absolute within their positioned container.
-
-## Following a Bloom tab bar
-
-The FAB automatically clears the bottom-edge footprint claimed by Bloom's tab
-bar and follows its compact height when it minimizes. An extended FAB can also
-react to that state:
+## Controlled collapse
 
 ```tsx
-<Fab label="Compose" minimizeBehavior="collapse" {...props} />
-<Fab label="Compose" minimizeBehavior="hide" {...props} />
+<Fab icon={Icons.RiAddLine} label="New post" collapsed={compact} onPress={createPost} />
 ```
 
-`collapse` smoothly retracts the label and horizontal space while retaining the
-icon-only action. `hide` removes the whole action. The default is `none`, which
-preserves the full FAB.
-
-## `placement="static"` when something else owns the position
-
-A FAB inside a custom positioned container can use `static` to turn off Bloom's
-anchoring. Do not use it merely to avoid a Bloom tab bar; bottom-edge clearance
-and `minimizeBehavior` already cover that case.
+`collapsed` defaults to `false`. It contracts the measured label width and opacity
+with Bloom's 300ms motion timing, reverses from the current position, and respects
+reduced motion. The same Button stays mounted: focus, accessible name, loading
+and disabled behavior remain available when only the icon is visible. Parent
+`style` widths remain authoritative, so an extended full-width action can follow
+a collapsing sidebar without another animated button or duplicated label.
+
+The existing `minimizeBehavior="collapse"` compatibility prop uses the same label
+transition when its minimization context requests it. Explicit `collapsed` also
+works independently, without a navigation or Sidebar provider.
+
+## Migration
+
+Remove `placement`, `offset`, `zIndex`, and `minimizeBehavior`. Position the action
+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 a preset plus a deliberate style override if needed. Replace icon elements
+with icon components and remove the `children` alias.

package/docs/field.mdx

@@ -21,7 +21,7 @@ import { TextField, TextFieldInput } from '@oxy.so/bloom/text-field';
   required
 >
   <TextField>
-    <TextFieldInput label="Email" value={email} onChangeText={setEmail} />
+    <TextFieldInput label="Email" value={email} onValueChange={setEmail} />
   </TextField>
 </Field>
 ```

package/docs/file-upload.mdx

@@ -71,7 +71,7 @@ The "Upload file" / "Upload in progress" frames, pixel-matched on web.
 | | |
 | --- | --- |
 | zone | 164 tall, full width, radius 16 |
-| idle | secondary fill (neutral-100, dark neutral-900), 2px **dashed** border (neutral-300 / 700) that darkens on hover or drag-over (neutral-400 / 600); 40px disc with a 24px upload-cloud icon that darkens on hover; 14 below it the Body/Medium prompt with the action word in accent-500, 8 below that the Body 2 hint |
+| idle | shared secondary surface, 2px **dashed** semantic border that uses primary on hover or drag-over; 40px disc with a 24px upload-cloud icon that darkens on hover; 14 below it the Body/Medium prompt with the action word in accent-500, 8 below that the Body 2 hint |
 | uploading | surface fill; the dashed border fades out and a 2px neutral outline fades in with an accent-400 stroke running **clockwise from top-centre**; an accent-400 `42%` pill (Caption 1/Medium, tabular figures) drops in over the top edge; bordered 40px disc with a file-type icon (spreadsheet / image / document, or `renderFileIcon`), the name (Body/Medium, truncated at 90%) and "Uploading 2.4 MB..." |
 | complete | the ring closes and the status line cross-fades to "Uploaded successfully!" |
 

package/docs/frosted-icon-button.mdx

@@ -14,19 +14,23 @@ mute toggle on a video, a back button over a hero image.
 import { FrostedIconButton } from '@oxy.so/bloom/frosted-icon-button';
 
 <FrostedIconButton
-  icon={<CloseIcon />}
+  icon={CloseIcon}
   accessibilityLabel="Close"
   onPress={close}
 />
 ```
 
+The icon is a component receiving `width`, `height` and `fill`; `children` is not an icon alias. Size and tone inherit from `BloomScope`; `tone` controls the solid active state.
+
+For a controlled toggle, pass `checked` and `onCheckedChange`. The callback receives the next boolean. `onPress` remains available for ordinary actions and runs alongside the toggle callback when both are supplied; disabled controls call neither.
+
 ## Which prop decides what
 
 | prop       | decides                                             |
 | ---------- | ---------------------------------------------------- |
 | `icon`     | the glyph                                            |
-| `size`     | `sm` · `md`, or a number                             |
-| `active`   | a persistent on state, for a toggle                  |
+| `size`     | `xs` · `sm` · `md` · `lg`, or a number                             |
+| `checked`   | a persistent on state, for a toggle                  |
 | `disabled` | dims and disables                                    |
 | `hitSlop`  | the touch target beyond the drawn circle             |
 

package/docs/glass.mdx

@@ -14,16 +14,16 @@ order: 90
 
 The glass is the sheen, not the wash. What reads as glass is the rim, the vertical gradient and the hairline; the 15% of the backdrop that shows through is a hint of depth, not the effect itself.
 
-**One measured cost, stated because it is real.** The 15% bleed moves the pane toward the surface under it, which in light mode means lighter — the one direction a white label cannot afford. Of `primary`'s 640 preset × mode × surface combinations, **73 fall below WCAG AA**, in the band 4.17–4.50, all in light mode, on `acid-canopy`, `arctic-signal`, `blue`, `bronze-neon`, `clay-current`, `copper-field`, `electric-tide`, `faircoin`, `green`, `lagoon`, `lavender`, `malachite-rush`, `midnight-citrus`, `mint`, `olive`, `orange`, `pacific-flare`, `pine`, `plum`, `pumpkin`, `reef-pulse`, `rose`, `saffron-depth`, `sky`, `solar-flux`, `viridian-orbit` and `yellow`. Both solid Button fills pass all 1,280 rows; glass `destructive` is also unaffected (0/640, worst 5.32). The alpha at which the failures reach zero remains 0.89.
+**One measured cost, stated because it is real.** The 15% bleed moves the pane toward the surface under it, which in light mode means lighter — the one direction a white label cannot afford. Of `primary`'s 640 preset × mode × surface combinations, **67 fall below WCAG AA**, in the band 4.21–4.50, all in light mode, on `acid-canopy`, `arctic-signal`, `blue`, `bronze-neon`, `clay-current`, `copper-field`, `electric-tide`, `faircoin`, `green`, `lagoon`, `lavender`, `malachite-rush`, `midnight-citrus`, `mint`, `olive`, `orange`, `pacific-flare`, `pine`, `plum`, `pumpkin`, `reef-pulse`, `rose`, `saffron-depth`, `sky`, `solar-flux`, `viridian-orbit` and `yellow`. Both solid Button fills pass all 1,280 rows; glass `destructive` is also unaffected (0/640, worst 5.32). The earlier low-chroma sweep reached zero failures at alpha 0.89; that historical sweep is retained below. The approved tonal surfaces improve the alpha 0.85 count from 73 to 67; the exact 67 row names are pinned in `tonal-glass-primary-failures.json`.
 
-The 1.0.1 catalog remains exactly 38/340, including the original 18-preset oracle at 30/180. The 30 new three-seed combinations contribute 35/300 and do not lower the existing 4.17 floor. These cohorts are asserted independently, so an unchanged total cannot hide a regression moving from one into the other.
+The 1.0.1 cohort now measures 36/340, including the original 18-preset cohort at 28/180; the 30 additions contribute 31/300. Before the approved tonal surfaces these counts were 38/340, 30/180 and 35/300. The current worst ratio improves from 4.17 to 4.21. These cohorts are asserted independently, so an unchanged total cannot hide a regression moving from one into the other.
 
 If your app runs one of those 27 presets in light mode and needs AA on its primary button, use `variant="inverse"` for that call site, or raise `GLASS_FILL_ALPHA`.
 
 Over a retained black/mid-grey/white media sample, **50 of 384** preset × mode × backdrop rows fall below AA, worst 3.61 (`destructive`: 0). The 1.0.1 catalog remains 25/204; the additions contribute 25/180, worst 4.17. That is a sample rather than a promise about arbitrary pixels. If a CTA must be legible over an image, `variant="inverse"` is opaque and backdrop-independent:
 
 ```tsx
-<Button variant="inverse">Comprar</Button>
+<Button appearance="solid" tone="neutral">Comprar</Button>
 ```
 
 `secondary`, `outline`, `ghost`, `text`, `link` and `icon` are unchanged: they have no fill for the tint to replace.
@@ -66,6 +66,8 @@ node scripts/measure-glass-alpha.mjs --url http://localhost:6006 --image docs/gl
 
 Measured in Chrome off painted pixels, with the label removed from the measurement clones so a white glyph cannot be mistaken for backdrop:
 
+**Historical low-chroma surface sweep:** these measurements predate the approved tonal shell. The current alpha 0.85 primary count is 67/640; the other sweep rows have not been remeasured.
+
 | alpha | backdrop response | blur delta over a photo (max/mean) | blur delta on a flat page | `primary` rows < AA | `destructive` rows < AA |
 | --- | --- | --- | --- | --- | --- |
 | 0.91 | 23.0 | 11 / 2.9 | 1 | 0 / 640 | 0 / 640 |
@@ -124,8 +126,8 @@ Measured over 64 presets × 2 modes × 2 endpoints × 2 platforms (512 rows), wi
 
 | | failures below AA | worst ratio |
 | --- | --- | --- |
-| light | 0 / 256 | **8.23** (over black, web) |
-| dark | 0 / 256 | **6.43** (over white, web) |
+| light | 0 / 256 | **7.84** (`sky`, over black, web) |
+| dark | 0 / 256 | **6.47** (`graphite`, over white, web) |
 
 and the pane still moves **49.98–69.97** of 255 between a black and a white backdrop, so it is glass rather than a tinted slab. Web is the worse of the two platforms in both modes: `expo-blur`'s own tint adds body on native that CSS `backdrop-filter` does not.
 
@@ -141,7 +143,7 @@ Internal (`glass/` is not a published subpath). It is reached through `ButtonGro
 
 ### On a device: tint, and no blur
 
-Measured on a **Pixel 8a** over a hard 10dp stripe pattern, sampling the same rows inside a chrome island and on the bare stripes beside it:
+Historical measurement before the tonal-shell native intensity adjustment below, on a **Pixel 8a** over a hard 10dp stripe pattern, sampling the same rows inside a chrome island and on the bare stripes beside it:
 
 | backdrop stripe | bare | inside the island |
 | --- | --- | --- |
@@ -153,3 +155,23 @@ The backdrop contributes **44 of 255** — the pane is translucent — and the s
 The composite works out at ≈**0.83** opacity against the web pane's 0.72 plus sheen. The difference is `expo-blur`'s own tint — one `intensity` drives it together with the radius and a caller cannot decline it — which is the platform gap `GLASS_BLUR_INTENSITY` documents, appearing exactly where it said it would.
 
 The ramp `PageHeader` draws over the same material was checked for the `stopColor` alpha trap at the same time: **0 achromatic rows of 311** in both modes, so the hue survives the SVG renderer.
+
+### Tonal-shell material verification
+
+The approved chroma28 shell retains the web's 10px blur and fill alpha 0.85. Native
+expo-blur intensity is now 30 instead of 50: its unavoidable neutral tint otherwise
+produced a 6.478/255 painted-channel gap against web on saturated surfaces. The
+new maximum is 3.887/255, inside the unchanged <4 gate and still measurably nonzero.
+This reduces native blur strength; it does not claim equal spatial blur across
+platforms. Sheen, fill opacity and hairline remain unchanged. Device blur behavior
+is subject to the Android topology limitations documented above.
+
+Across 3840 preset/mode/tone/surface combinations, on-fill labels now fail AA in 480
+cases and page-text labels in 2577. The earlier catalog contributes 258 and 1377;
+the additional 30 presets contribute 222 and 1200. Exact equality gates retain these
+measured limitations rather than reducing the AA requirement.
+
+Chrome islands retain zero AA failures over the black/white backdrop endpoints:
+the new light minimum is 7.84 (`sky/light/black/web`), and dark 6.47
+(`graphite/dark/white/web`). Previously pinned floors were 8.23 and 6.43. These
+are measured at unchanged chrome alphas 0.72/0.80 and now pin exact named rows.

package/docs/input-group.mdx

@@ -19,13 +19,13 @@ import { InputGroup, InputGroupAddon } from '@oxy.so/bloom/input-group';
 
 <InputGroup>
   <InputGroupAddon>oxy.so/</InputGroupAddon>
-  <TextFieldInput label="Handle" value={handle} onChangeText={setHandle} />
+  <TextFieldInput label="Handle" value={handle} onValueChange={setHandle} />
 </InputGroup>
 
 <InputGroup>
-  <TextFieldInput label="Search" value={query} onChangeText={setQuery} />
+  <TextFieldInput label="Search" value={query} onValueChange={setQuery} />
   <InputGroupAddon divider>
-    <Button size="small" onPress={run}>Search</Button>
+    <Button size="sm" onPress={run}>Search</Button>
   </InputGroupAddon>
 </InputGroup>
 ```
@@ -35,7 +35,7 @@ import { InputGroup, InputGroupAddon } from '@oxy.so/bloom/input-group';
 | prop        | decides                                                       |
 | ----------- | -------------------------------------------------------------- |
 | `size`      | `sm` 32 · `md` 36 (default) · `lg` 44 — plus a larger rung |
-| `isInvalid` | the error tint on the whole box (and no hover / focus ring)     |
+| `invalid` | the error tint on the whole box (and no hover / focus ring)     |
 | `disabled`  | paints the disabled fill and marks the group `aria-disabled`    |
 | `divider`   | per addon, a rule between it and the input                     |
 | `noPadding` | per addon, for an addon that supplies its own (a button)        |
@@ -44,7 +44,7 @@ import { InputGroup, InputGroupAddon } from '@oxy.so/bloom/input-group';
 
 A `TextFieldInput` (or a `Search`, or any `TextField`) placed in a group renders
 **bare**: it draws no fill or ring of its own, takes no side padding, stretches
-to fill the middle and inherits the group's `size`, `isInvalid` and `disabled`.
+to fill the middle and inherits the group's `size`, `invalid` and `disabled`.
 Before this, the field painted its own shell inside the group's and sized
 itself to the group's full width, pushing a trailing addon out of the clipped
 box.
@@ -56,7 +56,7 @@ in `text-secondary`.
 
 ## Why the state lives on the group
 
-`isInvalid` and `disabled` are properties of the **control**, not of the input
+`invalid` and `disabled` are properties of the **control**, not of the input
 element inside it. Setting them per part is how a box ends up with a red border
 and a normal-coloured button, or an enabled button beside a disabled input.
 

package/docs/input-otp.mdx

@@ -18,10 +18,10 @@ import { InputOtp } from '@oxy.so/bloom/input-otp';
 
 The `InputOtp` look, coloured by Bloom's theme:
 
-- Each box is **48 × 48**, radius 10, a 1px `neutral-200` border (`neutral-700` in dark) on the card surface, with the `shadow-xs` drop shadow.
+- Each box is **48 × 48**, radius 10, a 1px semantic hairline on the shared secondary surface, with the `shadow-xs` drop shadow.
 - Digits are **mono**, 18/26 medium, centred, with tabular numerals, so a row of `1`s and `8`s stays optically even.
 - Boxes sit **8px** apart; `groupEvery={3}` adds **12px** more before each group (`000 000`).
-- **Hover** darkens the border to `neutral-300`. **Focus** paints the border and a 2px ring outside it in the accent (`primary`) — on every focus, since a text input is `:focus-visible` on a click too.
+- **Hover** emphasizes the semantic border. **Focus** paints the border and a 2px ring outside it in the accent (`primary`) — on every focus, since a text input is `:focus-visible` on a click too.
 - **Invalid** gives every box a red border, a red tint and red digits; focus still wins over the red border.
 - **Disabled** dims the fill and the digits and drops the shadow.
 
@@ -47,7 +47,7 @@ Clearing a box removes its digit from the value, so later digits move left.
 | `value?` / `defaultValue?` | `string` | Controlled / initial code. |
 | `onChange?` | `(value: string) => void` | Every change. |
 | `onComplete?` | `(value: string) => void` | Once the last box is filled. |
-| `isInvalid?` | `boolean` | Error paint and `aria-invalid` on every box. |
+| `invalid?` | `boolean` | Error paint and `aria-invalid` on every box. |
 | `isDisabled?` / `disabled?` | `boolean` | Disable every box. |
 | `groupEvery?` | `number` | Gap between groups. |
 | `autoFocus?` | `boolean` | Focus the first box on mount. |