@oxy.so/bloom 2.10.0 → 2.11.0

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/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/stay-filters.mdx

@@ -317,17 +317,24 @@ becomes "Filters, 3 applied" (`accessibilityLabel` overrides it). `size`,
   a text-primary fill with the page background as the label, the page's own
   reading pair turned over, legible in both modes and every preset. Hover
   darkens the border; press fills neutral-100 (dark neutral-800). Colour only —
-  nothing scales. They are not `Chip`: that tops out at 28 tall and selects in
-  the brand tone.
+  nothing scales. That IS `Chip` now: the `2xl` rung and the `inverted` fill
+  (see [`Chip`](/docs/bloom/main/chip)). It used not to be — `Chip` topped out
+  at 28 tall and selected in the brand tone — so `FilterChip` had its own
+  stylesheet, its own hover and press colours and its own focus ring; it is now
+  a preset over the two.
 - **Text actions** ("Clear all", "Show more") are underlined `body-semibold` in
   text-primary, text-secondary on hover.
-- Keyboard focus draws a 2px accent ring outside a 2px white offset.
+- Keyboard focus draws `Chip`'s own 2px accent ring, offset 2px. It used to be
+  a box-shadow ring outside a hardcoded WHITE offset, which is a white halo on a
+  dark page.
 
 ## Accessibility
 
 - `FilterSection`: a named `group` with a level-3 `heading`.
 - `CountFilter`: a named `radiogroup` of `radio`s with `aria-checked`
-  (`accessibilityState.checked` on native). Every pill is in the tab order.
+  (`accessibilityState.checked` on native). Every pill is in the tab order. The
+  row is a `ChipRow`, so it scrolls sideways with an edge fade and keeps room
+  for each pill's focus ring.
 - `ToggleChipGroup`: a named `group` of toggle `button`s with `aria-pressed`
   (`accessibilityState.selected` on native).
 - "Show more" carries `aria-expanded`.
@@ -340,3 +347,11 @@ becomes "Filters, 3 applied" (`accessibilityLabel` overrides it). `size`,
 - On native the `center` placement always scrolls its content: a tablet sees
   the footer scroll with the sections. Phones take the `bottom` placement,
   which keeps it fixed.
+
+## Web CSS
+
+`FilterChip`, `FilterTextButton` and the property tiles build their stylesheets
+with `interactiveWebCss()` (`reset: 'none'`, `focus: { mode: 'ring' }`) rather
+than hand-writing them — see [Styles](/docs/bloom/main/styles). Each ring's gap
+takes the surface colour; it used to be a hardcoded white, which in dark mode was
+a halo.

package/docs/stay-search.mdx

@@ -145,7 +145,7 @@ can apply it to its own controls: `minimumAdults(value)` and
 
 ### DateFlexibilityChips
 
-A single-select row of Bloom `Chip`s (`large`, `outlined`; the selected one in
+A single-select row of Bloom `Chip`s (`xl` — 32 tall, 12px sides — `outlined`; the selected one in
 the brand tone): Exact dates, ± 1 day, ± 2 days, ± 3 days, ± 7 days, with values
 `exact`, `1`, `2`, `3`, `7`. Pass `options` to change them. It draws no calendar —
 put it under `RangeCalendar` or `DateRangePicker` from

package/docs/stepper.mdx

@@ -71,3 +71,11 @@ the `adjustable` element (`role="slider"` on web) carrying `aria-valuenow`,
 The label is required in the type because nothing else can name the control:
 it draws a number and two glyphs, and a title beside it is a sibling element.
 An empty or missing label also warns once in development.
+
+## Web CSS
+
+The value's focus ring is built by `interactiveWebCss()`
+([Styles](/docs/bloom/main/styles)) with `reset: 'none'` — it is a focusable
+readout, not a button, so it takes no `<button>` reset, no hover rule and no
+press scale. Its ring gap takes the surface colour rather than the white it used
+to hardcode.

package/docs/styles.mdx

@@ -9,7 +9,24 @@ order: 74
 `@oxy.so/bloom/styles` holds the style primitives Bloom itself uses.
 
 ```tsx
-import { atoms as a, tokens, BREAKPOINTS, web, native, select } from '@oxy.so/bloom/styles';
+import {
+  atoms as a,
+  tokens,
+  BREAKPOINTS,
+  web,
+  native,
+  select,
+  resolveSurfaceLevel,
+  useSurfaceLevel,
+  useSurfaceFill,
+  SurfaceLevelProvider,
+  surfaceFillVars,
+  surfaceFillOn,
+  hairlineOn,
+  surfaceTextOn,
+  quietText,
+  contrastRatio,
+} from '@oxy.so/bloom/styles';
 ```
 
 ## `atoms`
@@ -44,6 +61,68 @@ Platform-conditional style helpers. Use them for a genuine platform difference
 — a shadow, a font smoothing, a scrollbar — and not to work around something
 that should be the same on both.
 
+## `webDataSet`
+
+The web-only `dataSet` hook an adopted sheet's selectors hang off, as spread
+props. On web react-native-web turns it into a `data-*` attribute; on native it
+spreads nothing.
+
+```tsx
+<Pressable {...webDataSet({ bloomTrackRow: 'true' })} />
+// web:    <div data-bloom-track-row="true">
+// native: nothing
+```
+
+This is how a component reaches a CSS rule it cannot express inline — a hover
+state, a focus ring, a transition. A class never reaches the DOM here, so a
+`data-*` attribute is the only hook an
+[adopted sheet](/docs/bloom/main/styles) can select on.
+
+## `clamp` / `clamp01`
+
+```ts
+clamp(value, min, max)   // held inside [min, max]
+clamp01(value)           // held inside [0, 1]; undefined / NaN / ±Infinity → 0
+```
+
+Two edges worth knowing, because the copies these replaced disagreed about
+them:
+
+- `clamp` resolves an INVERTED range (`min > max`) to `min`. That is what pins
+  a dropdown taller than the viewport to the top gutter, so its first rows stay
+  reachable instead of its start going off-screen.
+- `clamp01` answers `0` for a non-finite value, including `Infinity`, where
+  `clamp(v, 0, 1)` would answer `1`. A non-finite share means "not measured
+  yet", and a full bar is the wrong thing to draw for that.
+
+## `contrastRatio` / `relativeLuminance` / `readableOn` / `darken` / `darkenUntilContrast`
+
+WCAG maths and the two decisions every surface painted from a computed colour
+has to make. `AA_TEXT_CONTRAST` (4.5), `AA_LARGE_TEXT_CONTRAST` (3) and
+`AAA_TEXT_CONTRAST` (7) are the bars, named once.
+
+```ts
+readableOn(background, ['#ffffff', '#141414'])       // which ink reads on it
+darkenUntilContrast(artworkColor, '#ffffff', 7)      // { color, amount } | null
+```
+
+`readableOn` takes one surface or several, and picks the candidate whose WORST
+contrast across them is highest — text over a gradient has to read at both ends.
+
+`darkenUntilContrast` returns the LIGHTEST shade of a colour on which every
+given foreground clears the ratio: the colour itself when it already does, else
+pulled toward black in 5% steps. `null` for a colour that does not parse, so a
+caller falls back to its own neutral rather than being handed one it did not ask
+for.
+
+**Darken the colour; never walk its ramp.** A generated ramp re-derives every
+stop's lightness and chroma from the hue, so a near-black input comes back ten
+times lighter than it went in and a vivid one has a channel zeroed. Scaling
+every channel by the same factor keeps their ratio, which is why a darkened teal
+is still teal. Four music surfaces — the lyrics pane, the immersive player, a
+generated cover and a browse tile — had five implementations of this between
+them, under four names for 4.5.
+
 ## `Z_INDEX`
 
 **Within-context values only.** Which overlay paints on top is decided by the
@@ -53,6 +132,244 @@ surface *is*, which leaves some pairings permanently inverted.
 
 Never give an overlay surface a `zIndex` of its own.
 
+## Surface levels
+
+**The answer to "what colour is the thing I am sitting on, and what do I put on
+top of it".** Before this existed every family resolved it alone, and the tree
+carried four different dark "card on a page" fills and two light ones. Two of
+those collisions were not drift: a dark `TextField` painted `neutral-800` inside
+a menu painted `neutral-800` measured **1.000:1**, and a tab rail painted
+`neutral-800` inside a queue panel measured **ΔE 0**. Both controls simply were
+not there.
+
+A control cannot know its parent, so the answer is relative. Three primitives,
+all pure, all taking the fill they land on:
+
+| | what it answers |
+| --- | --- |
+| `surfaceFillOn(theme, parent)` | the next surface up — a field, a track, a tile, a hovered row |
+| `hairlineOn(theme, parent)` | the line that separates them — a divider, a card edge, a tab rail |
+| `surfaceTextOn(theme, parent)` | `text` / `textSecondary` / `textTertiary` / `textGraphical`, each floored on that fill |
+
+A step moves the parent toward `theme.colors.text` by a fixed alpha, so nothing
+new enters the palette. Light and dark are ONE rule: moving toward the text
+colour darkens a light surface and lightens a dark one.
+
+### The named rungs
+
+`resolveSurfaceLevel(theme, level)` names the four a screen stacks, and levels 0
+and 1 land on what Bloom already painted, so adopting the API is not a repaint.
+
+| level | light | dark |
+| --- | --- | --- |
+| 0 page | `theme.colors.background` | `theme.colors.background` |
+| 1 card on page | `theme.colors.card` (white) | a step off the page — within 1.03:1 of the menu surface |
+| 2 card on card | a step off level 1 — a popover's inner tile, a field | ditto |
+| 3 deep | a step off level 2 | ditto |
+
+The ladder is **not monotonic in lightness**: in light the first step goes up to
+white and every step after goes down. What is monotonic is the SEPARATION —
+measured on `blue`, 1.11 / 1.15 / 1.15 in light and 1.23 / 1.30 / 1.30 in dark.
+1.11 is thin, which is why every rung also carries the `border` that separates it
+from its parent (1.21 / 1.53 / 1.50 in light). `surface-levels.test.ts` pins both
+mechanisms over all 64 presets, so losing either goes red.
+
+### Ambient level
+
+A container that PAINTS a surface publishes it, and everything inside steps off
+the right parent without being told:
+
+```tsx
+<SurfaceLevelProvider level={1} fill={colors.card}>{children}</SurfaceLevelProvider>
+```
+
+`ContentPanel`, `FloatingPanel` (so every menu, popover, select and tooltip),
+`QueuePanel`, and every sheet and dialog surface do this. `useSurfaceLevel()`
+reads the current rung's paint, `useSurfaceLevel(1)` the one above it,
+`useSurfaceFill()` just the fill. Nothing published means level 0 — the page —
+which is what every unwrapped consumer already assumed.
+
+`useSurfaceLevel(1)` is the one a component reaches for when it draws a surface
+of its own on top of whatever it landed on: it is "one legible step off my
+parent", in both modes, whether the parent is the page or a panel.
+`SettingsListGroup` paints its card that way when no `variant` is passed — with
+one exception it documents itself, that on the PAGE it takes the palette's own
+`card` token instead, which in dark separates further than the step does.
+
+**A component drawing a step should call `surfaceFillOn(theme, useSurfaceFill())`
+rather than `useSurfaceLevel(1)` when landing on its own parent would be fatal.**
+`useSurfaceLevel(1)` clamps at rung 3, so inside a rung-3 container it hands back
+rung 3 — the parent's own colour, 1.000:1. The primitive always steps.
+
+An overlay that paints the page colour publishes `level={0}`, which RESETS the
+ambient surface rather than inheriting it. That matters because a portal keeps
+React context from where it was rendered: without the reset, a dialog opened
+from inside a `ContentPanel` would tell its own content it is sitting on the
+panel's card.
+
+`OverlayRoot` publishes that reset for every portaled surface, and it publishes
+the rung ALONE — no `fill`. It paints nothing itself, so it has no fill to
+report; what it can say truthfully is "you are not on the surface your trigger
+was on". A surface inside it that knows its own colour then says so and wins:
+`Dialog` and the sheet shell publish `fill={colors.background}`, `FloatingPanel`
+publishes the menu rung. Two surfaces still paint something Bloom does not
+publish — `SettingsModal` (`resolveSettingsPalette(theme).full`) and `Tooltip`
+(the menu palette) — so content inside those reads the page rung rather than
+their real fill. That is an approximation, not a claim: they have published
+nothing since before the ladder existed, and the fix is for each to publish its
+own `fill`.
+
+### `fill` — the rung is a derivation, the fill is a fact
+
+A rung answers from the page down, which is all a control needs to find a
+legible step off its parent. It is not enough for the other question a surface
+gets asked — **"paint yourself the same colour as me"** — because a container
+may paint something the ladder would not have chosen. `ContentPanel` is exactly
+that: it paints `bg-card`, and in dark mode `theme.colors.card` is not rung 1
+(the rung is a computed step off the page, pinned within 1.03:1 of the menu
+surface). Chrome that took the rung would sit a visible shade off the column it
+is supposed to disappear into.
+
+So a container that knows what it painted says so, and `useSurfaceFill()`
+returns that colour verbatim. Everything derived from it — the hairline, the
+raised fill, the text rungs, `useSurfaceLevel(1)` — is then computed off the
+REAL parent, which is what the relative primitives always wanted and could not
+have while the parent was inferred. A provider with no `fill` behaves exactly as
+it did.
+
+### `useSurfaceFill()` or `colors.card`?
+
+**`colors.card` is a palette token: the colour a CARD paints.** It is the right
+answer when you are drawing a card — an object that is genuinely separate from
+what is behind it.
+
+**`useSurfaceFill()` is a question about position: the colour of the surface
+underneath you.** It is the right answer for chrome that has to be OPAQUE in its
+container's own colour and otherwise not be seen — a sticky header over a
+scrolling feed, a tab bar, a search field's backing, a reply bar pinned to the
+bottom of a column. Those are the ones that were written as `bg-card` at every
+call site, and they were only ever right for as long as the container's surface
+stayed `card`; the hook is right afterwards too, and it is right inside a sheet,
+a menu or a scoped subtree where `card` never was.
+
+### `--bloom-surface` (web), for CSS that cannot call a hook
+
+The same containers write the published fill onto the element they paint:
+
+```tsx
+<View style={[surfaceFillVars(colors.card), …]}>   {/* no-op on native */}
+```
+
+so web CSS below it can follow the surface:
+
+```css
+background-color: var(--bloom-surface, var(--background));
+```
+
+```tsx
+className="bg-[var(--bloom-surface,var(--background))]"   /* web only */
+```
+
+`SURFACE_FILL_VAR` and `SURFACE_FILL_CSS` are the exported spellings. Three
+things about it are deliberate:
+
+- **The fallback is part of the reference.** The variable exists only where a
+  container published one, so outside every surface it resolves to the page.
+- **It is never declared at `:root`.** A custom property whose value is a
+  `var()` substitutes where it is DECLARED, so a root-level
+  `--bloom-surface: var(--background)` would answer for the whole document and
+  a `BloomColorScope` subtree — which paints its own `--background` — would keep
+  reading the app-wide one. Both halves of the reference above substitute at the
+  USING element, so a scope gets its own.
+- **It is web-only, and the hook is not.** Propagating a custom property to a
+  native subtree means react-native-css's `VariableContextProvider`, i.e. the
+  `nativewind` OPTIONAL peer, and a panel's surface must not depend on whether a
+  consumer installed it. Cross-platform code reads `useSurfaceFill()`; a
+  `.web.tsx` fork or a consumer stylesheet may read the variable. A
+  `var(--bloom-surface)` class in shared code would be right on web and
+  quietly wrong on native.
+
+It is the opposite number of `--bloom-ring-offset` below: a CONTAINER publishes
+this one, a CONTROL consumes that one, and they are the same colour.
+
+### Quiet text is not a ramp stop
+
+`quietText(surface, text, minRatio)` returns the QUIETEST blend of the theme's
+text over the theme's surface that still clears `minRatio` **as rendered** (the
+8-bit colour is re-checked, because a nominal 4.50 quantizes to 4.49).
+`quietTextOver([surfaces], text, min)` does it for a label that lands on more
+than one fill.
+
+This is the only way to build a caption grey in Bloom. A ramp stop cannot do the
+job: `neutral-400` clears AA on the page and measured **2.42:1** on a chart card,
+because the card is not the page. The floors are `AA_TEXT` (4.5, body text),
+`AA_TEXT_STRONG` (7, the secondary rung) and `AA_GRAPHICAL` (3, gridlines, rules
+and disabled glyphs).
+
+## Interactive web CSS — the one recipe
+
+`interactiveWebCss()` builds the stylesheet for a raw-DOM fork or a
+`dataSet`-hooked react-native-web control. **It is THE way to write one.** It
+existed before and nobody called it — thirty-odd families used only the
+`useInteractiveWebCss()` adopter and hand-wrote the sheet, which is exactly why
+rings, hovers and disabled states drifted apart.
+
+```tsx
+const CSS = interactiveWebCss({
+  selector: '[data-bloom-filter-chip]',
+  varPrefix: 'bloom-filter-chip',
+  reset: 'none',            // react-native-web: no <button> reset, no press scale
+  transition: 'background-color 120ms ease, border-color 120ms ease',
+  focus: { mode: 'ring' },  // gap colour from the surface
+  disabled: { opacity: null }, // this family fades in its inline style, for native parity
+});
+useInteractiveWebCss(STYLE_ID, CSS);
+```
+
+- **`reset`** — `button` (default) emits the `<button>` reset. A react-native-web
+  caller passes `none`: RNW lays a `View` out with `display: flex`, so
+  `inline-flex` from a stylesheet silently changes how the control participates
+  in its parent's layout.
+- **`focus`** — `outline` (default) is the canonical 2px outline at
+  `outline-offset`. `ring` is the `box-shadow` form, for a control whose ring
+  must sit on a CHILD element (a slider thumb, a checkbox glyph).
+- **`hover`** is optional. An RNW control gets `onHoverIn` in JS and paints hover
+  through its inline style; a CSS rule would be a second source of truth.
+- **`disabled`** defaults to `cursor: default` plus `DISABLED_OPACITY`.
+
+### The focus ring gap
+
+**One mechanism.** The gap is `var(--bloom-ring-offset)`, set inline from the
+surface behind the control with `useRingOffsetStyle()`. It used to be the literal
+`#FFFFFF` — Tailwind's `ring-offset-color` default, never overridden — so in DARK
+mode a focused filter chip, filter text button, stepper value, slider thumb,
+checkbox, radio, radio card, property tile, energy-rating pill and sortable photo
+tile each drew a 2px white halo against a near-black page. A gap is a hole in the
+ring, and a hole is the colour of what is behind it.
+
+Three families (`sidebar`, `select`, `settings-modal`) name their own offset
+variable. Each is already surface-derived and each knows its surface exactly, so
+they stay — as a written list in `interactive-recipe.test.ts`, not as a
+threshold.
+
+## Disabled
+
+**Recolour if you can; fade only if you cannot.**
+
+A control with a token pair to swap to swaps to it and keeps opacity 1 — that is
+what `Button` does. A fade multiplies against whatever is behind the control, so
+over a coloured card a 0.5 label goes muddy rather than quiet, and fades stack
+when a disabled control sits inside a disabled group.
+
+Opacity is the fallback, for a control with no pair to swap to: an icon drawn in
+`currentColor`, a `Pressable` that paints nothing of its own, a row of mixed
+children. When it is used it is `tokens.DISABLED_OPACITY` (**0.5**) — one value,
+because three were in the tree (0.5 in twenty-five places, 0.4 in six, 0.6 in
+one) and nothing distinguished them. A disabled control is exempt from the WCAG
+contrast floors, which is what makes one blanket value defensible at all; it is
+not licence to pick a new one per family. Gate:
+`interactive-recipe.test.ts`.
+
 ## `flatten`
 
 `StyleSheet.flatten` re-exported for code that already depends on the RN

package/docs/tabs.mdx

@@ -119,3 +119,14 @@ differently?
 
 `@oxy.so/bloom/tabs/expo-router` binds the strip to the router so `value` comes
 from the current route and a press navigates, instead of a local `useState`.
+
+## The rail reads on whatever the strip sits on
+
+`resolveTabsPaint(theme, variant, surface)` takes the fill the strip lands on;
+the component reads it from the ambient `SurfaceLevelProvider`
+([Styles → Surface levels](/docs/bloom/main/styles)). The underline rail, the
+hover row and the `filled` thumb are steps off that surface.
+
+The rail used to be `neutral-800` in dark — the exact fill `QueuePanel` (and
+every other menu-surface family) paints its panel with, **ΔE 0**. A tab strip
+inside one had no rail. On the page the rail lands within 0.04 of its old colour.

package/docs/tenancy.mdx

@@ -86,7 +86,7 @@ the theme in both modes. The maps are exported (`LEASE_PAYMENT_STATUS`,
 | `LeaseSummaryCard` next payment | `upcoming` info · `due` warning · `overdue` error · `paid` success |
 | `RentPaymentList` row | `paid` success · `pending` warning · `overdue` error · `partial` info |
 | `MaintenanceRequestCard` stage | `reported` warning · `acknowledged` info · `scheduled` primary · `resolved` success |
-| `MaintenanceRequestCard` priority chip | `low` neutral · `medium` info · `high` warning · `urgent` error |
+| `MaintenanceRequestCard` priority badge | `low` neutral · `medium` info · `high` warning · `urgent` error |
 | `DocumentList` row | `signed` success · `pending` warning · `expired` error |
 
 ## Layout from the part's own width
@@ -127,8 +127,10 @@ tint halo and a semibold title, `upcoming` draws a hollow marker and secondary t
 - The timeline is a `list` of `listitem`s; each marker is an `img` named by its state
   ("Done", "In progress", "Not yet" — `stateLabels`), so the state is announced before
   the title.
-- The lease bar is a `progressbar` named by `periodLabel`, with flat `aria-value*`
-  (0–100) and `aria-valuetext` from `remainingLabel`.
+- The lease bar is a [`Meter`](/docs/stat-bar) — the shared neutral track and the
+  ACCENT fill; it used to fill with the text colour, a near-black bar reading as ink
+  rather than as a measurement. It is a `progressbar` named by `periodLabel`, with
+  flat `aria-value*` (0–100) and `aria-valuetext` from `remainingLabel`.
 - Icon-only buttons are named after what they act on: "Download receipt for August
   2026" (`receiptLabel`), "View Tenancy agreement.pdf" (`viewLabel`,
   `downloadLabel`). A photo is "Pipe under the sink, photo 1 of 3" (`photoLabel`).

package/docs/text-field.mdx

@@ -262,3 +262,18 @@ const [show, setShow] = useState(false);
 ### Search
 
 Reach for `Search` rather than rebuilding it: it is a `TextField` at the pill radius with the magnifier, the clear button and the keyboard settings a query field wants.
+
+## The fill is a step off the surface, not a ramp stop
+
+`resolveTextFieldPalette(theme, surface)` takes the fill the field lands on, and
+every fill and quiet text colour it returns is a step off THAT — see
+[Styles → Surface levels](/docs/bloom/main/styles). `useTextFieldPalette()` reads
+the surface from the ambient `SurfaceLevelProvider`, which `FloatingPanel` and
+`QueuePanel` publish, so a field inside a menu or a popover steps off the panel
+rather than off the page.
+
+It used to be `neutral-800` in dark — byte for byte the colour
+`floating/menu-palette` paints a menu, a popover, a select and a tooltip with.
+Measured **1.000:1**: a field dropped into any of them had no shell at all, and
+one inside a `card` had 1.225:1. On the page the fill lands within 0.04 of the
+colour it always had. Gate: `surface-level-adoption.test.ts`.

package/docs/textarea.mdx

@@ -88,3 +88,9 @@ Accepts React Native's `TextInputProps` (except `multiline`, which is always on)
 - The name is `label`, else `accessibilityLabel`, else `placeholder`. A placeholder is a poor name — give the field a label.
 - Invalid and disabled reach the input as `aria-invalid` / `aria-disabled`, the spellings react-native-web reads.
 - Invalid is also shown as text when you pass a `hint`; colour alone is not an announcement.
+
+## The fill is a step off the surface
+
+`Textarea` shares `text-field`'s palette, so its shell steps off whatever surface
+it lands on — see [TextField](/docs/bloom/main/text-field) and
+[Styles → Surface levels](/docs/bloom/main/styles).