@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/stay-filters.mdx

@@ -7,7 +7,9 @@ order: 111
 # Stay Filters
 
 The filters surface of a search results page, as parts the app composes inside
-Bloom's `Dialog`. Data is props: the app owns the filter state, the result
+Bloom's `Dialog`. They cover stays and every other housing mode: the housing
+parts (property type, area, features, energy rating, availability, floor, and a
+log-scale sale price) sit alongside the stay ones. Data is props: the app owns the filter state, the result
 count and every label.
 
 ```tsx
@@ -133,6 +135,7 @@ last row.
 | --- | --- |
 | `buckets` | listing counts per price bucket, lowest first; they split `min`..`max` evenly. Omit for no histogram |
 | `min` / `max` / `step` | the slider's bounds and granularity |
+| `scale` | `linear` (default) or `log`, for sale prices — see below |
 | `value` / `onValueChange` | the controlled `[low, high]` |
 | `onValueCommit` | once per drag end, or per committed field |
 | `formatPrice` | how a field shows a price at rest, e.g. `(n) => (n >= max ? '$620+' : '$' + n)` |
@@ -143,14 +146,28 @@ last row.
 This one **computes** prices — bucket bounds, clamping, snapping — so they are
 numbers, and `formatPrice` is where the app's currency and locale come in.
 
-- **The histogram** draws equal-width bars 2 apart with 2px top corners. A
-  bucket whose midpoint is inside the range is text-primary; the rest are
+- **The histogram** draws equal-width bars 2 apart with 3px top corners, in the
+  chart cards' visual language: a bucket whose midpoint is inside the range
+  takes the chart series tone (`chart-6`, the blue hue re-anchored on the
+  theme's primary, so it also matches the range slider); the rest are
   neutral-300 (dark neutral-700). It is hidden from assistive technology: the
   slider announces the same range as numbers. `PriceHistogram` is exported on
   its own for a custom layout.
 - **The slider** is Bloom's `RangeSlider` without value bubbles, pulled up so
   its rail sits on the bars' baseline. Both map `min`..`max` across the full
   width, so each bar sits over the prices it counts.
+- **`scale="log"` for sale prices.** A linear slider over €50K – €2M spends
+  nearly all of its width above what most people search. With `scale="log"`,
+  the same slider distance is the same **ratio**: the midpoint of 50,000 –
+  2,000,000 is about 316,000, not 1,025,000. The slider then runs over 200
+  positions (`PRICE_SCALE_POSITIONS`), and every price it reports is snapped to
+  `step` in price space, so pass a round step (5,000). `buckets` then split the
+  **position** span evenly, so bucket your counts in log space. With `min > 0`
+  the scale is geometric; with `min` of 0 it is offset by one (`log(1 + p)`) so
+  0 stays reachable. The fields are unchanged. Known gap: on a log scale the
+  thumbs' `aria-valuenow` is the position (0–200), not the price —
+  `RangeSlider` has no value text yet — so screen-reader users should rely on
+  the Minimum and Maximum fields.
 - **The fields** are floating-label `TextField`s. Focused, a field shows the
   bare number; the typed text is a draft until blur or submit, when it is
   parsed ("$1,200" reads as 1200), snapped, clamped to its own side of the
@@ -195,6 +212,78 @@ component. The selection is reported in `options` order. It needs an
 (`showMoreLabel`, `showLessLabel`, `defaultExpanded`). A selected option past
 the fold stays visible while collapsed.
 
+### `PropertyTypeFilter`
+
+Multi-select icon tiles for the property type: Apartment, House, Room, Studio,
+Duplex / Penthouse, Coliving, Hostel, Land / Other (`PROPERTY_TYPE_OPTIONS`).
+`value` / `onValueChange` (in option order; empty means any type), `options`,
+`labels` (override by key), `columns` (default: as many as fit, 2 to 4, at 120
+wide), `accessibilityLabel` (default "Property type"). Tiles have radius 12,
+are at least 100 tall with 16 inset, and have a hairline at rest. Selected is a
+2px text-primary border on a neutral tint. Each tile is a toggle `button` with
+`aria-pressed`. The search panel's `PropertyTypePicker`
+(`@oxy.so/bloom/home-search`) is the same grid, compact.
+
+### `AreaRangeFilter`
+
+Floor area in m²: a Minimum / Maximum pair of fields, and with `slider` a
+`RangeSlider` above them. `value: [min | null, max | null]` — `null` is
+open-ended. An emptied field commits `null`, and a thumb resting on `min` or
+`max` reports `null`, so dragging back to an end removes that bound. `min`
+(0), `max` (500), `step` (5), `formatArea` (default `` `${n} m²` ``),
+`minLabel`, `maxLabel`, `onValueCommit`, and `accessibilityLabel` (default
+"Area", naming the group and the slider).
+
+### `FeatureFilter`
+
+What the home must have: Elevator, Parking, Terrace, Garden, Pool, Furnished,
+Pets allowed, Air conditioning, Heating, Accessible, Storage room
+(`HOUSING_FEATURE_OPTIONS`, each with an icon). `variant="chips"` (default)
+draws the filter pills, a `group` of `aria-pressed` toggles. `variant="checkboxes"`
+draws two columns of Bloom `Checkbox`es, which read better as a long list.
+`value`, `onValueChange` (in option order), `options`, `labels`,
+`accessibilityLabel` (default "Features").
+
+### `EnergyRatingFilter`
+
+Seven small coloured letter pills, A (best) to G (worst), 32 tall.
+
+**"And better" semantics:** `value` is the **worst** rating accepted. `'C'`
+matches A, B and C. The pills from A to the chosen letter keep their colour,
+the rest turn neutral, the chosen one has a 2px text-primary ring, and the line
+underneath reads "C and better". `null` means any rating, and every pill is
+coloured. Pressing the chosen letter again clears it.
+
+Colours come from the theme's `success` → `warning` → `error`: A, D and G are
+those colours, and the letters between each pair are mixed at thirds. The letter
+is white or near-black, whichever has more contrast with its fill. It is a
+`radiogroup` (default name "Energy rating"); each pill is a `radio` with
+`aria-checked`, named by the summary it would set ("C and better", "A only").
+`formatSummary` changes both.
+
+### `AvailabilityFilter`
+
+An "Available now" `SwitchFilterRow`, then "Available from" with Bloom's
+`DatePicker`. While `availableNow` is on, the picker is disabled and its day is
+ignored. The app keeps `date`, so switching off brings it back. Props:
+`availableNow`, `onAvailableNowChange`, `date`, `onDateChange`, the four labels,
+`minDate`, `locale`.
+
+### `FloorFilter`
+
+Multi-select pills: Ground, Middle, Top, With elevator (`FLOOR_OPTIONS`).
+Nothing selected means any floor. "With elevator" combines with the floor
+choices rather than replacing them. `value`, `onValueChange`, `options`,
+`labels`, `accessibilityLabel` (default "Floor").
+
+### Housing dialogs
+
+The stories compose a **Buy** dialog (property type, a log-scale price, rooms,
+area with a slider, feature chips, energy rating, floor, new builds only) and a
+**Rent** dialog (property type, monthly rent, rooms, area fields, availability,
+feature checkboxes, energy rating, floor). Both use the same `Dialog`,
+`FilterSection` and `FilterFooter` setup shown above.
+
 ### `SwitchFilterRow`
 
 `title`, `description`, `value`, `onValueChange`, `disabled`. The switch is
@@ -228,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`.
@@ -251,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

@@ -62,6 +62,11 @@ is the guest rule below.
 
 ## StaySearchBar
 
+`StaySearchBar` is the vacation-rental preset of `HomeSearchBar` from
+[`@oxy.so/bloom/home-search`](/docs/bloom/main/home-search), which draws the bar for every
+housing mode (rent, buy, swap). The API below is unchanged; use `HomeSearchBar`
+directly for other segments.
+
 | prop                                               | decides                                                                                          |
 | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
 | `activeSegment` / `onActiveSegmentChange`          | the open segment — `destination`, `checkIn`, `checkOut`, `dates` or `guests` — or `null`   |
@@ -140,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.