@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/queue-panel.mdx

@@ -0,0 +1,125 @@
+---
+title: Queue Panel
+description: The play queue — now playing, what the listener added, what follows from the context — with drag, keyboard and menu reordering, and a recently played tab.
+order: 64
+---
+
+# Queue Panel
+
+The play queue as a side panel on web and as bottom-sheet content on native.
+
+```tsx
+import { moveQueueItem, QueuePanel } from '@oxy.so/bloom/queue-panel';
+
+<QueuePanel
+  nowPlaying={current}
+  playing={isPlaying}
+  queue={queue}
+  context={upNext}
+  contextName="Night Drive"
+  recentlyPlayed={history}
+  onReorder={(section, from, to) => {
+    const set = section === 'queue' ? setQueue : setUpNext;
+    set((list) => moveQueueItem(list, from, to));
+  }}
+  onRemove={(section, index) => removeAt(section, index)}
+  onPlay={(section, index, track) => playFrom(section, index, track)}
+  onClearQueue={() => setQueue([])}
+  onClose={closeQueue}
+  style={{ height: '100%' }}
+/>
+```
+
+Every list is a prop and every change is a callback. The panel reorders, removes and clears nothing itself; it draws what it is given, so the player stays the one owner of the queue.
+
+## Layout
+
+| part | what it shows |
+| --- | --- |
+| header | `Tabs` — Queue / Recently played — and a close button when `onClose` is set |
+| Now playing | `nowPlaying` with an accent title and `NowPlayingIndicator` (still while `playing` is false) |
+| Next in queue | `queue`, the tracks the listener added, with "Clear queue" when `onClearQueue` is set |
+| Next from: *context* | `context`, what follows from the playing album, playlist or radio (`contextName` names it; without one the heading is "Next up") |
+| Recently played | `recentlyPlayed` through `RecentlyPlayedList`; the loaded track is marked there too |
+
+A section with no rows is not drawn. With no now-playing track and both lists empty the panel shows an empty state.
+
+`variant="panel"` (the web default) is a rounded-8 surface `width` wide (360) with a hairline, in the same surface colours as a menu. `variant="sheet"` (the native default) is flat and full width. Give either a height — the list scrolls inside it.
+
+## Rows
+
+Each row is 56 tall: a 40px cover, the title (`body-medium`) over the artists (`caption-1-regular`, with the explicit badge when `explicit`), and the track's `meta` string — a duration in the queue, a "when" in the history. The cover and text are one button named "Play *title*"; the controls sit beside it, never inside it.
+
+| control | when | web | native |
+| --- | --- | --- | --- |
+| remove (×) | `onRemove`, `panel` only | revealed on hover or keyboard focus | — (use the menu) |
+| more (⋯) | `onReorder` or `onRemove` | revealed on hover or keyboard focus | always |
+| drag handle | `onReorder` | revealed on hover or keyboard focus | always |
+
+On a device without hover (`(hover: none)`) web draws the controls all the time, like native.
+
+`QueueTrack` is `{ id, title, artists?, cover?, explicit?, meta? }`. `cover` is a URL or an id your `ImageResolver` turns into one. `id` must be stable: rows are keyed by it.
+
+## Reordering
+
+Three ways, one callback — `onReorder(section, from, to)`, with indices inside that section (`'queue'` or `'context'`). A row never moves between sections.
+
+- **Drag** the handle. The row lifts under the pointer or finger, and its neighbours slide to show where it will land. Rows are a fixed 56 tall, so the landing slot is `from + round(dy / 56)` (`queueDragTarget`) with no measuring; the row cannot be dragged past its section's first or last slot. The panel's scroll view stops scrolling while a drag is live.
+- **Keyboard**: focus a handle and press <kbd>↑</kbd> / <kbd>↓</kbd>. Focus stays on the handle as the row moves — the panel puts it back once your new list arrives. On native the handle offers "Move up" and "Move down" as accessibility actions.
+- **Menu**: "Move up", "Move down" (disabled at the ends) and "Remove from queue".
+
+Every move is announced: "Slow Tide moved to position 2 of 3" — through a polite live region on web and `AccessibilityInfo.announceForAccessibility` on native.
+
+`moveQueueItem(list, from, to)` applies a move to your array (a new array, target clamped; an out-of-range `from` is refused rather than clamped, so a stale index cannot move the wrong row). `queueDragTarget` and `queueDragShift` are the arithmetic the drag uses, exported for anything that wants to draw the same preview.
+
+All three are re-exports of `moveItem` / `dragTarget` / `dragShift` from [`@oxy.so/bloom/hooks`](/docs/bloom/main/hooks), which the track list and the sortable photo grid share. `queueDragTarget` used to answer slot `0` when the row height was not measured; it now answers `from`, i.e. "it has not moved".
+
+## `RecentlyPlayedList`
+
+```tsx
+import { RecentlyPlayedList } from '@oxy.so/bloom/queue-panel';
+
+<RecentlyPlayedList items={history} currentId={current.id} onPlay={(index, track) => play(track)} />
+```
+
+The same rows, without reordering. `currentId` marks the loaded track.
+
+## `QueuePanelRow`
+
+The row on its own, for a list of your own: `track`, `onPress`, `current`, `playing`, `trailing` (your controls), `highlighted` (keep the hover paint, e.g. while your menu is open), `accessibilityLabel`.
+
+## Labels
+
+Every string is in `labels` — pass any subset to translate. The ones that name a track are functions:
+
+```tsx
+<QueuePanel
+  labels={{
+    queueTab: 'Cola',
+    recentTab: 'Escuchado',
+    nextFrom: (context) => `A continuación de: ${context}`,
+    moreOptions: (title) => `Más opciones para ${title}`,
+    reorder: (title) => `Reordenar ${title}`,
+    moved: (title, position, total) => `${title}, posición ${position} de ${total}`,
+  }}
+/>
+```
+
+`DEFAULT_QUEUE_PANEL_LABELS` holds the English defaults.
+
+## Accessibility
+
+- Section titles are `role="heading"`; each section is a `list` of `listitem`s.
+- The row's play area, the handle, remove, more and close are all buttons with names that include the track ("Reorder Slow Tide", "More options for Slow Tide").
+- Moves are announced (above). The tabs are `Tabs`, so they carry `role="tab"` and `aria-selected`.
+
+## Colours
+
+From the theme only, light and dark: the panel is the menu surface and hairline, a row under the pointer takes the menu row highlight, the glyph buttons one neutral step above it, and the playing title the accent. Hover and press change colour only; nothing scales.
+
+## The panel publishes its surface
+
+In `panel` variant the family wraps its content in `SurfaceLevelProvider level={1}`
+([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.

package/docs/radio.mdx

@@ -93,3 +93,10 @@ right.
 `value` may be `undefined`. Prefer that over pre-selecting an option the user
 did not choose: a default that happens to be first is indistinguishable from an
 answer, and it silently becomes the submitted value.
+
+## The focus ring's gap
+
+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).

package/docs/rating.mdx

@@ -46,6 +46,10 @@ apps in other languages pass `accessibilityLabel`.
 | `display`    | the text on the right ("4.9", "86%"), also the bar's `aria-valuetext`      |
 | `labelWidth` | without it the label flexes and the bar is 96 wide (a category list); with it the bar flexes (a distribution) |
 
-The track is 4 tall with a 2px radius, neutral-200 (dark neutral-800), filled
-with text-primary. The bar is a `progressbar` carrying `aria-valuemin`,
-`aria-valuemax` and `aria-valuenow`.
+The bar is a [`Meter`](/docs/stat-bar): 4 tall with a 2px radius, the shared
+neutral-200 (dark neutral-700) track, filled with the ACCENT. It used to be
+filled with text-primary — a near-black bar reading as ink rather than as a
+measurement — and a rating breakdown is not a chart: the rows do not encode
+different categories by colour, they all say "how good is this, out of 5". It is
+a `progressbar` carrying `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and
+`aria-valuetext` (from `display`).

package/docs/settings-list.mdx

@@ -88,26 +88,112 @@ When `rightElement` is set, the chevron is hidden automatically (you can overrid
 />
 ```
 
-## On a card-coloured surface
+## The group knows what it is sitting on
 
 A group paints the `card` colour, which reads as a raised card on a page painted
-in `background`. Inside something that is already `card` — a `ContentPanel`, a
-Dialog body — that same group has no edge left and its rows float on the page.
-`variant="filled"` paints the group in `backgroundSecondary` instead, the same
-surface `Card variant="filled"` uses:
+in `background`. Inside something *already* painted `card` — a `ContentPanel` —
+that same group has no edge left: the rows float, and the group is there,
+correct, and invisible.
+
+**You do not tell it which.** A container that paints a surface publishes the
+colour it painted (the surface ladder in [Styles](/docs/bloom/main/styles)), and
+the group resolves off that colour:
+
+- on the **page**, `theme.colors.card` — what these groups have always painted;
+- on **anything else**, one ladder step off the fill the container published.
+
+So this is the whole of it, on a page and in a panel alike:
 
 ```tsx
 <ContentPanel>
-  <SettingsListGroup variant="filled" title="Account">
+  <SettingsListGroup title="Account">
     <SettingsListItem title="Privacy" onPress={openPrivacy} />
   </SettingsListGroup>
 </ContentPanel>
 ```
 
-| `variant` | Surface | Use on |
-| --- | --- | --- |
-| `plain` (default) | `card` | a page painted in `background` |
-| `filled` | `backgroundSecondary` | a surface painted in `card` |
+This used to be a `variant="filled"` at every call site — ~75 of them in one app
+with a settings tree, each one a chance to forget, and forgetting produced no
+error and no visible control. A question about the PARENT is not something a call
+site should have to answer.
+
+| `variant` | Surface |
+| --- | --- |
+| *(unset — the normal case)* | `card` on the page; one step off the container's own fill anywhere else |
+| `plain` | `card` |
+| `filled` | `backgroundSecondary` |
+
+**A step, rather than `backgroundSecondary`, because `backgroundSecondary` is
+calibrated against `card` and nothing else.** On a `ContentPanel` it works (dark
+1.378–1.404 across all 64 presets); on the menu surface `FloatingPanel` and
+`QueuePanel` publish it measures **1.086–1.106 in dark, failing the ladder's 1.1
+just-noticeable floor on 52 of the 64 presets** — the disappearance this default
+exists to prevent, one container over. The step measures 1.296–1.312 there, on
+all 64. In light both clear it, which is why this is only visible if you look in
+dark.
+
+### Every container this changes
+
+Anything that publishes a surface now decides what a group inside it paints, not
+just `ContentPanel`:
+
+| Container | What a group inside it paints now |
+| --- | --- |
+| a bare screen | `card` — unchanged |
+| `ContentPanel` | a step off the panel's fill (was `card` unless you passed `variant="filled"`) |
+| `FloatingPanel` — `Popover`, `DropdownMenu`, `ContextMenu`, `HoverCard`, `Select`, menu flyouts | a step off the menu surface (was `card`) |
+| `QueuePanel` (as a panel) | a step off the panel surface (was `card`) |
+| `Dialog`, `BottomSheet` and the sheet-backed surfaces | `card` — unchanged; they publish `colors.background` |
+
+The first row and the last are the ones to notice: nothing on a plain screen and
+nothing in a dialog moves. A group that was ALREADY passing `variant="filled"`
+inside a panel keeps painting `backgroundSecondary` until the prop comes off.
+
+### When to pass `variant` anyway
+
+For a surface Bloom does not paint and so cannot publish a fill for — your own
+coloured section, a third-party container. An explicit `variant` always wins over
+the ambient one.
+
+```tsx
+<View style={{ backgroundColor: colors.card }}>
+  <SettingsListGroup variant="filled" title="Account">…</SettingsListGroup>
+</View>
+```
+
+The alternative, if that container is yours and holds more than a settings list,
+is to publish the surface once instead of annotating everything inside it.
+`SurfaceLevelProvider` ships on the **`styles` subpath**, not the root barrel:
+
+```tsx
+import { SurfaceLevelProvider } from '@oxy.so/bloom/styles';
+
+<View style={{ backgroundColor: mySectionColour }}>
+  <SurfaceLevelProvider level={1} fill={mySectionColour}>
+    <SettingsListGroup title="Account">…</SettingsListGroup>
+  </SurfaceLevelProvider>
+</View>
+```
+
+Pass `fill` as well as `level`: the level says how deep you are, the fill says
+what you actually painted, and it is the fill the group steps off.
+
+### Overlays do not inherit the panel
+
+A dialog, a bottom sheet or a menu opened from inside a `ContentPanel` starts its
+own painting context, so a group inside a dialog is a `card` again whether the
+trigger lived on a bare screen or inside a panel. That takes a deliberate reset:
+React context reaches through a portal and through an RN `<Modal>` even though
+neither paints anything. `Dialog` and the bottom-sheet shell publish
+`colors.background`, `FloatingPanel` publishes the menu surface, and
+`overlay/OverlayRoot` resets the ambient surface for anything portaled that does
+neither.
+
+Two portaled surfaces paint something they do not publish — `SettingsModal`
+(`resolveSettingsPalette(theme).full`) and `Tooltip` (the menu palette) — so a
+group inside either reads the page rung and paints `card`. That is inherited from
+before the ladder existed, and the fix is for each of them to publish its own
+fill.
 
 ## Footer / header text
 
@@ -134,7 +220,7 @@ surface `Card variant="filled"` uses:
 | `footer?` | `string` | Section footer. |
 | `children` | `React.ReactNode` | `Item`, `Divider`. |
 | `style?` | `StyleProp<ViewStyle>` | Override group container style. |
-| `variant?` | `'plain' \| 'filled'` | The group's surface: `card` (default) or `backgroundSecondary`, for a group on a card-coloured surface. |
+| `variant?` | `'plain' \| 'filled'` | Overrides the surface the group would resolve from the container's published fill — `card` or `backgroundSecondary`. Normally left unset; see [above](#the-group-knows-what-it-is-sitting-on). |
 
 ### `SettingsListItem`
 

package/docs/sidebar.mdx

@@ -108,7 +108,39 @@ The logo leads the header beside the collapse (or close) control; `account`, if
 - A folder row is p 8 with a 20px folder glyph (open while expanded) and the label; its rows are py 5 / pr 8 / pl 36 with the label and a `meta` chip (radius 4, background-tertiary, px 4 / py 1, caption-1-medium), background-secondary-hover while selected or hovered. A curved 1px icon-quaternary connector drops from the folder glyph into each row. The rows' height and opacity ease open and shut together over 300ms; collapsed rows leave the tab order.
 - Quick search filters the tree too: a folder whose label matches keeps every row, otherwise only its matching rows, held open while the query is set. "No results" counts the tree.
 - The tree hides while collapsed.
-- `plan` replaces the team card: radius 12, background-tertiary (the panel colour when `flat`), py 8 / pr 12 / pl 10, a 32px avatar (initials 18.8/22.6 medium), the name (body-medium) over the plan (body-regular text-secondary), and a small secondary button (`actionLabel`, default "Upgrade"). Collapsed, only the avatar.
+- `plan` replaces the team card: radius 12, background-tertiary (the panel colour on a `plain` surface), py 8 / pr 12 / pl 10, a 32px avatar (initials 18.8/22.6 medium), the name (body-medium) over the plan (body-regular text-secondary), and a small secondary button (`actionLabel`, default "Upgrade"). Collapsed, only the avatar.
+
+## Surface and size: the app's identity
+
+Two apps with the same rows should not look like the same app. That difference is two props, not a fork of this component.
+
+```tsx
+<Sidebar surface="card" />                    {/* default: the floating panel */}
+<Sidebar surface="plain" size="large" />      {/* a social reader's nav */}
+<Sidebar surface="docked" size="small" />     {/* a workspace column */}
+```
+
+`surface` is the panel's EDGE:
+
+| surface  | what it draws                                                      |
+| -------- | ------------------------------------------------------------------ |
+| `card`   | radius 24, a hairline and the panel shadow, on the panel fill       |
+| `plain`  | no radius, no border, no shadow — the rows sit straight on the page |
+| `docked` | the panel fill, square corners, ONE hairline on the inner edge, full height |
+
+The docked edge is not the card's border: that one is white in light mode, a highlight that reads as an edge only because the card's shadow sits beneath it. A docked column has no shadow, so it takes a real hairline stepped off its own fill (`hairlineOn`).
+
+`size` moves the rows and the panel together — one rung, every measurement, in `SIDEBAR_METRICS`:
+
+| size     | square | glyph | label            | expanded | collapsed |
+| -------- | ------ | ----- | ---------------- | -------- | --------- |
+| `small`  | 30     | 18    | `body-2-medium`  | 232      | 46        |
+| `medium` | 36     | 20    | `body-medium`    | 260      | 52        |
+| `large`  | 44     | 24    | `title-3-medium` | 300      | 60        |
+
+The collapsed width is never an independent number: it is the square plus the panel's collapsed padding on both sides plus its two borders, so the icon column stays centred at every size. A row outside a sidebar takes `size` itself; inside one it inherits the panel's.
+
+`AppShell` passes both through (`sidebar={{ surface, size }}`) and treats `docked` as what it is — it gives up its left and vertical padding around that column and lets it run the full height, so the hairline is the separator instead of a gutter.
 
 ## Navigation
 
@@ -117,7 +149,7 @@ The logo leads the header beside the collapse (or close) control; `account`, if
 
 ## Collapse
 
-`collapsed` / `defaultCollapsed` / `onCollapsedChange`. The panel morphs 260 → 52 in 300ms while labels, badges and the shortcut hint collapse (max-width, opacity, 3px blur on web) and the icons stay put. `mobile` is always expanded and shows a close button; `flat` removes the panel chrome for a rail revealed under the page (and moves the search into the header). `fluid` fills the container while expanded. Reduced motion snaps.
+`collapsed` / `defaultCollapsed` / `onCollapsedChange`. The panel morphs between the size's two widths (260 → 52 at `medium`) in 300ms while labels, badges and the shortcut hint collapse (max-width, opacity, 3px blur on web) and the icons stay put. `mobile` is always expanded and shows a close button. `fluid` fills the container while expanded. Reduced motion snaps.
 
 After expanding, the account trigger's hover pill stays off until the pointer leaves it, so a stationary pointer does not light it up.
 

package/docs/slider.mdx

@@ -89,3 +89,11 @@ throwing; an empty or whitespace-only string counts as missing, because
   [`Radio`](/docs/bloom/main/radio) group — they name the options.
 - **The range is huge and non-linear.** A slider over 1–1,000,000 gives most of
   its travel to values nobody wants.
+
+## The thumb's focus ring
+
+The ring around a focused thumb is the `box-shadow` form (an outline on the
+focusable ancestor would draw round the wrong box), and its gap takes
+`var(--bloom-ring-offset)` from the surface behind the control. It was a
+hardcoded `#FFFFFF`, which in dark mode was a white halo. See
+[Styles → The focus ring gap](/docs/bloom/main/styles).

package/docs/sortable-media.mdx

@@ -0,0 +1,68 @@
+---
+title: Sortable Media
+description: SortablePhotoGrid — an editable grid of uploaded photos with a cover, drag to reorder on web, move buttons everywhere, per-photo upload progress, errors with retry and an add tile.
+order: 115
+---
+
+# Sortable Media
+
+`SortablePhotoGrid` is the photo step of an editor: the photos the user has
+added, in order, the first one marked as the cover.
+
+```tsx
+import { SortablePhotoGrid, type SortablePhoto } from '@oxy.so/bloom/sortable-media';
+
+const [photos, setPhotos] = useState<SortablePhoto[]>([
+  { id: 'living', uri: 'https://…/living.jpg', alt: 'Living room' },
+  { id: 'kitchen', uri: localPreviewUri, status: 'uploading', progress: 42 },
+  { id: 'bath', uri: localPreviewUri2, status: 'error', error: 'File too large' },
+]);
+
+<SortablePhotoGrid
+  photos={photos}
+  onReorder={setPhotos}
+  onRemove={(id) => setPhotos((list) => list.filter((p) => p.id !== id))}
+  onRetry={(id) => restartUpload(id)}
+  onAdd={openPicker}
+  maxPhotos={20}
+  addHint="JPG or PNG"
+/>
+```
+
+## Data
+
+The list is controlled. Each photo is `{ id, uri, status?, progress?, error?, alt? }`:
+
+- `uri` is an absolute URL (a local `file:` or `blob:` preview works while the
+  upload runs) or an `ImageResolver` id, resolved with `photoVariant`.
+- `status` is `uploading`, `uploaded` (the default) or `error`. While uploading,
+  `progress` (0..100) draws a percentage and a bar over a scrim; without it, a
+  spinner.
+- `onReorder` receives the WHOLE list in its new order — after a drag, and after
+  every move-button press — so the app stores it as is.
+
+## Reordering
+
+- **Web, mouse or pen:** press a tile and drag. After 5px of travel the tile
+  lifts and follows the pointer, the other tiles make room live, and releasing
+  commits. Escape cancels. Buttons inside a tile never start a drag.
+- **Everywhere else — touch, native, keyboard and screen readers:** each tile
+  has "Move photo 2 earlier" / "Move photo 2 later" buttons. After a move the
+  focus stays on the moved photo's button (or its other one, if it reached an
+  end) and the new position is announced politely.
+
+On a web pointer that can hover, the tile's buttons appear while the tile is
+hovered or holds focus; on touch screens and native they are always shown.
+
+## Layout
+
+Square tiles, 3 columns below 640 wide and 4 from there (`columns` fixes it),
+12 apart (8 below 480). The add tile follows the photos until `maxPhotos` is
+reached.
+
+## Accessibility
+
+The grid is a `list` named by `accessibilityLabel` (default "Photos"); each tile
+is a `listitem` named "Photo 1 of 6, Cover, Living room" (the error is added
+to a failed photo). The upload overlay is a `progressbar` named "Uploading photo
+3". Every string is in `labels` for localisation.

package/docs/stat-bar.mdx

@@ -1,12 +1,94 @@
 ---
-title: StatBar
-description: A labelled bar in two shapes — progress toward a maximum, or a split between two sides.
+title: Meter and StatBar
+description: The one determinate bar and ring behind every progress bar in Bloom, and the labelled bar built on it.
 order: 63
 ---
 
+# Meter
+
+`Meter` is the determinate bar. Every progress bar in Bloom is this one —
+seventeen families used to hand-roll it, and they disagreed about both colours.
+
+```tsx
+import { Meter, MeterRing } from '@oxy.so/bloom/stat-bar';
+
+<Meter value={4} max={5} accessibilityLabel="Cleanliness" valueText="4 of 5" />
+
+<MeterRing value={72} max={100} size={72} thickness={6} accessibilityLabel="Listing quality">
+  <Text variant="headline-semibold">72</Text>
+</MeterRing>
+```
+
+It draws nothing but the rail and the fill: no label, no value, no footer. A bar
+with a label is `StatBar`; a bar inside a card is that card's business.
+
+## Props
+
+| prop                  | decides                                                       |
+| --------------------- | ------------------------------------------------------------- |
+| `value` / `max`       | how far along; clamped into `[0, max]`, `max` defaults to 1    |
+| `height`              | 6 by default; `radius` follows it unless you set one           |
+| `width`               | a fixed width; without one the bar fills its parent            |
+| `fill` / `track`      | the two colours — see below before you pass either             |
+| `transitionMs`        | ease the fill on WEB; native snaps, reduced motion snaps       |
+| `accessibilityLabel`  | what the bar measures — REQUIRED                               |
+| `valueText`           | `aria-valuetext`, the reading ("4 of 5" rather than "80%")     |
+| `decorative`          | no role at all, for one segment of a larger progressbar        |
+| `fillTestID`          | the fill's own `testID`; defaults to `` `${testID}-fill` ``    |
+
+`MeterRing` takes `size` (56) and `thickness` (5) instead of `height`/`width`,
+plus `cap` and centred `children`.
+
+## The fill is the accent
+
+Three families used to paint the fill `theme.colors.text` — `RatingBar`,
+`WizardProgress` and the lease bar in `tenancy` — while six others used the
+accent. A near-black fill reads as **ink**, not as a measurement: on a neutral
+rail it is the highest-contrast thing on the row, so a fifth-full bar shouts
+louder than the text beside it. The accent is the one colour in the theme that
+means "this is the quantity", so that is the default, and `fill` stays
+overridable for a status tone.
+
+## The track is `neutral-200`, `neutral-700` in dark
+
+Measured before the fold: seven families at `200/700`, two at `200/800`, one at
+`300/700` and one at `100/800`. The majority won on numbers and it is also the
+one that holds in both modes — `neutral-100` is invisible on a card, and
+`neutral-800` against a `neutral-900` surface is a rail you have to look for.
+
+## A chart is not a meter
+
+If the bars in a group encode **which datum** each one is rather than **how much
+of one thing** there is, it is a chart: colour it from `chart-cards/palette.ts`
+(`chartHueTone`, `resolveMonoTone`), not from the meter's defaults.
+`PricePerAreaComparison` is the case — its rows are a home against its street,
+neighbourhood and city, so the highlighted row takes the brand-anchored data hue
+and the comparators the single-ink neutral. Painting them with the accent would
+have said each row was progress toward something.
+
+## `Meter` is determinate only
+
+There is no `indeterminate` prop. An indeterminate bar is a sweeping segment —
+reanimated on native, a keyframe on web, a layout measurement for the sweep
+distance — and none of that is shared with a determinate fill. `creator-studio`
+owns the one indeterminate bar in the library; a second caller is the moment to
+move it here, not before.
+
+## Accessibility
+
+A `progressbar` named by `accessibilityLabel`, with the FLAT `aria-value*`
+attributes. react-native-web drops the `accessibilityValue` object entirely, so
+a bar setting only that announces its role and no value at all; React Native
+folds the flat props back, so native is unchanged. ARIA never computes a name
+for `progressbar` from its contents and the bar draws no text of its own, which
+is why the label is required rather than optional.
+
+A bar that is one segment of a larger progressbar passes `decorative` and is
+hidden: two nested progressbars announce the same measurement twice.
+
 # StatBar
 
-One bar, two meanings.
+`Meter` plus the text around it — one bar, two meanings.
 
 ```tsx
 import { StatBar } from '@oxy.so/bloom/stat-bar';
@@ -27,7 +109,7 @@ import { StatBar } from '@oxy.so/bloom/stat-bar';
 | `minLabel` / `maxLabel`   | progress: the ends of the range                     |
 | `label`                   | what the bar is about — required                    |
 | `icon`                    | a glyph beside the label                            |
-| `fillColor` / `trackColor`| the colours                                         |
+| `fillColor` / `trackColor`| the colours — default to the meter's                |
 
 The two variants are one component because they are the same object visually,
 and one prop rather than two components because a row often switches between

package/docs/stat-cards.mdx

@@ -67,6 +67,17 @@ Surfaces are built on Bloom's ramps (`button/shared`): the card is `neutral-100`
 - **Deltas.** `lime` / `rose` / `neutral`. The plain card's `Chip` reads `success` / `error` / `default`. The footer pill uses a status recipe on the theme's `success` and `negative` ramps: light `200` fill with `800` text, dark `950` at 60% over the band with `500` text.
 - **Tile tones.** `blue` is the accent ramp, `orange` the `warning` ramp, `sky` the `info` ramp and `emerald` the `success` ramp — so a preset that moves a status colour moves the tile with it. `purple` and `pink` have no theme role: they keep Tailwind's offset from `blue-500` (lightness step, chroma ratio, hue distance), measured from the theme's `primary`. Stops are fixed (`500 → 600`, `orange`/`sky` `400 → 500`), always opaque (react-native-svg drops alpha in `stopColor`).
 
+## Accessory
+
+`accessory` (plain only) puts a node at the top right of the card, level with the icon tile — a `Sparkline` from `@oxy.so/bloom/chart-cards` is the usual one. It shrinks before the tile does and is right-aligned; without it the card renders exactly as before.
+
+```tsx
+import { Sparkline } from '@oxy.so/bloom/chart-cards';
+
+{ icon: RiHeadphoneLine, label: 'Listeners', value: '48,210', delta: '+12%', deltaColor: 'lime',
+  accessory: <Sparkline data={[3, 4, 4, 6, 5, 7, 9]} tone="positive" /> }
+```
+
 ## Info tooltip
 
 `hint` adds a 20px info glyph (named `` `About ${label}` ``, or `hintLabel`). The tooltip opens on hover after 200ms, on keyboard focus, and on press — a glyph this small reads as a button and gets tapped.