@oxy.so/bloom 2.9.0 → 2.11.0

package/lib/module/styles/surface-levels.js

@@ -0,0 +1,364 @@
+"use strict";
+
+/**
+ * The surface LADDER: one answer to "what colour is the thing I am sitting on,
+ * and what colour is the thing I put on top of it".
+ *
+ * Thirty families had each resolved that themselves, and the result was four
+ * different dark "card on a page" fills in one tree — `#14171c` (chart cards),
+ * `#23262b` (menus, fields, tab rails), `#2e353e` (`theme.colors.card`) and a
+ * per-family mix — plus two light ones. Two of those collisions are not a
+ * cosmetic drift but a disappearing act: a dark text field painted `n[800]`
+ * inside a menu painted `n[800]` measured 1.000:1, and a tab rail painted
+ * `n[800]` inside a queue panel painted `n[800]` measured ΔE 0. In both cases
+ * the control had no shell at all.
+ *
+ * The fix is not another table of hexes. A control cannot know its own parent,
+ * so the only durable form of the answer is RELATIVE: every step is computed
+ * from the fill it lands on.
+ *
+ *   surfaceFillOn(theme, parent)   the next surface up — a field, a track, a tile
+ *   hairlineOn(theme, parent)      the line that separates them
+ *   surfaceTextOn(theme, parent)   text rungs that clear AA *on that fill*
+ *
+ * A step moves the parent fill toward the theme's own `text` colour by a fixed
+ * alpha. That is deliberately the same move the neutral ramp makes, so nothing
+ * new enters the palette — but it is anchored on the ACTUAL parent instead of a
+ * ramp stop that happens to match one page colour.
+ *
+ * **Light and dark are one rule here, not two.** Moving toward `text` darkens a
+ * light surface and lightens a dark one, which is what each mode wants; the
+ * alphas differ only because a dark page has more headroom above it than a light
+ * page has below white.
+ *
+ * ## The named rungs
+ *
+ * `resolveSurfaceLevel(theme, level)` names the four rungs a screen actually
+ * uses, and the first two land on what Bloom already paints, so adopting the
+ * API is not a repaint:
+ *
+ *   0  page          `theme.colors.background`
+ *   1  card on page  light `theme.colors.card` (white), dark one step off the
+ *                    page — `#212327` against the `#23262b` that
+ *                    `floating/menu-palette` has always used, 1.03:1 apart
+ *   2  card on card  one step off level 1 — a popover's inner tile, a field
+ *   3  deep          one step off level 2
+ *
+ * The ladder is NOT monotonic in lightness. In light mode the first step goes
+ * UP to white and every step after goes down; in dark every step goes up. What
+ * is monotonic — and what the gate pins — is the SEPARATION between neighbours:
+ * measured on `blue`, every adjacent pair separates by fill alone (light 1.11 /
+ * 1.15 / 1.15, dark 1.23 / 1.30 / 1.30).
+ *
+ * 1.11:1 is a thin margin, and that is why every rung ALSO carries the `border`
+ * that separates it from its parent (light 1.21 / 1.53 / 1.50). A surface either
+ * separates by fill or it draws its hairline, and on a light page a card needs
+ * the hairline. `surface-levels.test.ts` pins both mechanisms over every preset,
+ * so losing either one goes red.
+ *
+ * ## Ambient level
+ *
+ * `SurfaceLevelProvider` publishes "the fill my children are sitting on", and
+ * `useSurfaceLevel()` reads it. A container that paints a surface raises it;
+ * everything inside then steps off the right parent without being told.
+ * Defaulting to level 0 keeps every unwrapped consumer on the page rung, which
+ * is what it was already assuming.
+ *
+ * ## The rung is a derivation; `fill` is the fact
+ *
+ * A rung ANSWERS the question from the page down, and for a control that only
+ * needs a legible step off its parent that is enough. 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 case: it paints `bg-card`, and in DARK mode
+ * `theme.colors.card` is not rung 1 (which is a computed step off the page,
+ * pinned within 1.03:1 of the menu surface). A sticky header that took the rung
+ * would sit a visible shade off the column it is supposed to disappear into.
+ *
+ * So a container that knows exactly what it painted publishes it —
+ * `<SurfaceLevelProvider level={1} fill={colors.card}>` — and `useSurfaceFill()`
+ * returns that colour verbatim. Everything derived (the hairline, the raised
+ * fill, the text rungs) 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.
+ *
+ * ## The same answer on web, for CSS that cannot call a hook
+ *
+ * {@link SURFACE_FILL_VAR} (`--bloom-surface`) carries the published fill down
+ * the DOM, so a stylesheet, a `::after` seam or an arbitrary Tailwind value can
+ * follow the surface without the consumer threading a colour through props.
+ * It is set by the same containers, on the element they paint, with
+ * {@link surfaceFillVars} — never at `:root`, which would resolve once for the
+ * whole document and defeat both this and `BloomColorScope` (a subtree scoped
+ * to another preset paints its own `--background`; a root-computed alias keeps
+ * the app-wide one — `theme/color-scope/seed-scope.ts` has the mechanism).
+ *
+ * It is WEB-ONLY, and deliberately: propagating a custom property to a native
+ * subtree means react-native-css's `VariableContextProvider`, i.e. the
+ * `nativewind` OPTIONAL peer, and a panel's own surface must not depend on
+ * whether a consumer installed it. Native's answer is the hook, which is also
+ * the only form that is correct on both platforms — so cross-platform code
+ * reads `useSurfaceFill()` and a web-only fork may read the variable.
+ */
+import { createContext, createElement, useContext, useMemo } from 'react';
+import { Platform } from 'react-native';
+import { useTheme } from "../theme/use-theme.js";
+import { mixColors, quietText } from "./color-contrast.js";
+import { RING_OFFSET_VAR } from "./interactive-web-css.js";
+/** WCAG AA for body-size text. */
+export const AA_TEXT = 4.5;
+/** WCAG AAA-ish: the rung a SECONDARY label sits at, clearly quieter than the primary one. */
+export const AA_TEXT_STRONG = 7;
+/** WCAG AA for large text, icons and graphical objects (gridlines, tracks, rules). */
+export const AA_GRAPHICAL = 3;
+
+/**
+ * How far one surface step moves its parent toward `theme.colors.text`.
+ *
+ * Tuned so that the step off the PAGE reproduces what Bloom already painted
+ * there: light `#f3f3f7` → `#e6e6ea` (today's `n[200]`, 1.12:1) and dark
+ * `#0c0e11` → `#21232a` (today's `n[800]`, 1.86:1). Dark takes the larger alpha
+ * because a near-black page has the whole range above it while a light page has
+ * only the sliver below white.
+ */
+const FILL_STEP = {
+  light: 0.07,
+  dark: 0.1
+};
+
+/** The same move, further: a hairline has to read AS a line, not as another fill. */
+const HAIRLINE_STEP = {
+  light: 0.14,
+  dark: 0.2
+};
+
+/**
+ * The next surface up from `parent` — a text field's fill, a progress track, a
+ * stat tile, a hovered row. Always a visible step off whatever it is given.
+ */
+export function surfaceFillOn(theme, parent) {
+  return mixColors(parent, theme.colors.text, FILL_STEP[theme.isDark ? 'dark' : 'light']);
+}
+
+/** The hairline that reads on `parent` — a divider, a card edge, a tab rail. */
+export function hairlineOn(theme, parent) {
+  return mixColors(parent, theme.colors.text, HAIRLINE_STEP[theme.isDark ? 'dark' : 'light']);
+}
+
+/** The text rungs legible on one fill. Every member is floored against that fill. */
+
+/**
+ * The three text rungs plus the graphical one, resolved against `parent`.
+ *
+ * A ramp stop cannot do this job: `n[400]` clears AA on the page and measures
+ * 2.42:1 on a chart card, because the card is not the page. Reading the rungs
+ * off the fill they land on is the whole difference.
+ */
+export function surfaceTextOn(theme, parent) {
+  const text = theme.colors.text;
+  return {
+    text,
+    textSecondary: quietText(parent, text, AA_TEXT_STRONG),
+    textTertiary: quietText(parent, text, AA_TEXT),
+    textGraphical: quietText(parent, text, AA_GRAPHICAL)
+  };
+}
+
+/** The four rungs a screen stacks. See the module comment for what each one is. */
+
+export const SURFACE_LEVELS = [0, 1, 2, 3];
+/** The fill of one rung. Levels 0 and 1 are pinned to what Bloom already paints. */
+function levelBackground(theme, level) {
+  const page = theme.colors.background;
+  if (level === 0) return page;
+  // Level 1 is `card` in light (white) and a step off the page in dark, which is
+  // byte-for-byte the surface `floating/menu-palette` has always used.
+  const card = theme.isDark ? surfaceFillOn(theme, page) : theme.colors.card;
+  if (level === 1) return card;
+  const inner = surfaceFillOn(theme, card);
+  return level === 2 ? inner : surfaceFillOn(theme, inner);
+}
+
+/** Everything a surface paints, given the fill it actually has. */
+function paintOn(theme, level, background) {
+  return {
+    level,
+    background,
+    border: hairlineOn(theme, background),
+    raised: surfaceFillOn(theme, background),
+    ...surfaceTextOn(theme, background)
+  };
+}
+
+/** Everything one rung paints. Pure, so it can be walked over every preset × mode. */
+export function resolveSurfaceLevel(theme, level) {
+  return paintOn(theme, level, levelBackground(theme, level));
+}
+
+/**
+ * The CSS custom property carrying the published surface fill to a web subtree.
+ *
+ * Named like `--bloom-ring-offset` (its opposite number: a CONTAINER publishes
+ * this one, a CONTROL consumes that one, and they are the same colour) rather
+ * than like a palette token — it is not one. `--surface` is already a token, and
+ * this deliberately does not shadow it.
+ */
+export const SURFACE_FILL_VAR = '--bloom-surface';
+
+/**
+ * How to REFERENCE the published fill from CSS or an arbitrary Tailwind value:
+ *
+ * ```
+ * background-color: var(--bloom-surface, var(--background));
+ * className="bg-[var(--bloom-surface,var(--background))]"   // web-only
+ * ```
+ *
+ * The fallback is what makes it safe: the variable exists only where a container
+ * published one, so outside every surface — and in a `BloomColorScope` subtree
+ * that owns no surface of its own — this resolves to the page. Both halves
+ * substitute at the USING element, so a scoped subtree gets the scope's
+ * `--background`, not the document root's.
+ */
+export const SURFACE_FILL_CSS = `var(${SURFACE_FILL_VAR}, var(--background))`;
+
+/**
+ * The style a surface OWNER puts on the element it paints, so web CSS below it
+ * can read {@link SURFACE_FILL_CSS}. `undefined` on native, where the variable
+ * has no propagation mechanism that does not go through an optional peer (see
+ * the module comment) — the hook is native's answer, and the owner passes this
+ * unconditionally either way.
+ *
+ * It belongs on the SAME element that carries the fill, so the two can never
+ * disagree, and a container that publishes the context publishes this with it.
+ *
+ * `undefined` in, `undefined` out: a container that cannot name its own colour
+ * (see `content-panel/shared.ts`) publishes no variable rather than a wrong one,
+ * and the call site stays one unconditional expression.
+ */
+export function surfaceFillVars(fill) {
+  if (fill === undefined || Platform.OS !== 'web') return undefined;
+  // A custom property has no key on RN's `ViewStyle`, and on web it does not
+  // need one: react-native-web compiles every own key of a style object into an
+  // atomic rule, so `--bloom-surface` lands on the element and inherits from
+  // there. `WebCssStyle` is the annotation for exactly that crossing (it is what
+  // keeps this from being an `as ViewStyle`, which silences typos instead of
+  // widening — `styles/web-view-style.ts`).
+  const vars = {
+    [SURFACE_FILL_VAR]: fill
+  };
+  return vars;
+}
+
+/** What a container publishes: the rung, and the fill if it knows it exactly. */
+
+const NO_AMBIENT_SURFACE = {
+  level: 0,
+  fill: null
+};
+const SurfaceLevelContext = /*#__PURE__*/createContext(NO_AMBIENT_SURFACE);
+/**
+ * Publish the rung this subtree sits on.
+ *
+ * A container that paints a surface wraps its content in this; every descendant
+ * then steps off the right parent. Without it a control assumes level 0, which
+ * is what it assumed before this existed — so adopting it is additive.
+ *
+ * On web, publish {@link surfaceFillVars} on the painted element in the same
+ * breath: the DOM inherits the variable independently of React context, so a
+ * container that sets one and not the other leaves CSS below it reading the
+ * ENCLOSING surface's colour — which is the wrong colour, silently.
+ */
+export function SurfaceLevelProvider({
+  level,
+  fill,
+  children
+}) {
+  const value = useMemo(() => ({
+    level,
+    fill: fill ?? null
+  }), [level, fill]);
+  return /*#__PURE__*/createElement(SurfaceLevelContext.Provider, {
+    value
+  }, children);
+}
+
+/** The ambient rung, as a number. `0` when nothing published one. */
+export function useSurfaceLevelValue() {
+  return useContext(SurfaceLevelContext).level;
+}
+
+/**
+ * The ambient rung's paint, optionally `delta` rungs above it.
+ *
+ * `useSurfaceLevel()` is "the surface I am on"; `useSurfaceLevel(1)` is "the
+ * surface one level above the current one" — the question every one of those
+ * thirty families was answering by hand.
+ *
+ * When the container published an exact `fill`, every rung above it is STEPPED
+ * off that colour instead of read from the ladder: one step above a real panel
+ * is a step above what the panel actually painted, not a rung that assumed a
+ * different parent.
+ *
+ * Two edges, both resolved by counting the steps the CLAMPED rung actually
+ * costs rather than the delta that was asked for:
+ *
+ *  - a delta that runs off the top asks for the rung it landed on, not for more
+ *    steps than the ladder has (`level 1 + 3` is rung 3, i.e. two steps);
+ *  - a NEGATIVE delta is a question about what is BELOW the published surface,
+ *    and an exact fill says nothing about that — the ladder is the only thing
+ *    that can answer, so it does, instead of clamping to the fill and labelling
+ *    it with a rung it is not.
+ */
+export function useSurfaceLevel(delta = 0) {
+  const theme = useTheme();
+  const {
+    level,
+    fill
+  } = useContext(SurfaceLevelContext);
+  const next = Math.min(3, Math.max(0, level + delta));
+  const steps = next - level;
+  return useMemo(() => {
+    if (fill === null || steps < 0) return resolveSurfaceLevel(theme, next);
+    let background = fill;
+    for (let i = 0; i < steps; i += 1) background = surfaceFillOn(theme, background);
+    return paintOn(theme, next, background);
+  }, [theme, next, fill, steps]);
+}
+
+/**
+ * Just the ambient fill — for a control that only needs to know what is behind
+ * it, and for chrome that has to BE that colour (an opaque sticky header over a
+ * scrolling column, a tab bar, a search field's backing).
+ *
+ * This is the one to reach for over `theme.colors.card`: `card` is a palette
+ * token — the colour a CARD paints — and it is right only for as long as the
+ * surface you happen to be inside is a card. This answers what the surface
+ * around you actually painted, whatever that surface turns out to be, so the
+ * app does not repeat a guess at every call site and does not have to be swept
+ * when a container changes what it paints.
+ */
+export function useSurfaceFill() {
+  const theme = useTheme();
+  const {
+    level,
+    fill
+  } = useContext(SurfaceLevelContext);
+  return useMemo(() => fill ?? levelBackground(theme, level), [theme, level, fill]);
+}
+
+/**
+ * The inline style that gives a focus ring's GAP the colour of the surface
+ * behind the control.
+ *
+ * `styles/interactive-web-css.ts` `RING_OFFSET_VAR` explains why the gap is a
+ * variable at all: as the literal `#FFFFFF` it drew a 2px white halo around
+ * every focused chip, stepper and slider thumb in dark mode. Spread it into the
+ * control's own `style` alongside its accent ring variable.
+ */
+export function useRingOffsetStyle() {
+  const surface = useSurfaceFill();
+  return useMemo(() => ({
+    [RING_OFFSET_VAR]: surface
+  }), [surface]);
+}
+//# sourceMappingURL=surface-levels.js.map

package/lib/module/styles/surface-levels.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["createContext","createElement","useContext","useMemo","Platform","useTheme","mixColors","quietText","RING_OFFSET_VAR","AA_TEXT","AA_TEXT_STRONG","AA_GRAPHICAL","FILL_STEP","light","dark","HAIRLINE_STEP","surfaceFillOn","theme","parent","colors","text","isDark","hairlineOn","surfaceTextOn","textSecondary","textTertiary","textGraphical","SURFACE_LEVELS","levelBackground","level","page","background","card","inner","paintOn","border","raised","resolveSurfaceLevel","SURFACE_FILL_VAR","SURFACE_FILL_CSS","surfaceFillVars","fill","undefined","OS","vars","NO_AMBIENT_SURFACE","SurfaceLevelContext","SurfaceLevelProvider","children","value","Provider","useSurfaceLevelValue","useSurfaceLevel","delta","next","Math","min","max","steps","i","useSurfaceFill","useRingOffsetStyle","surface"],"sourceRoot":"../../../src","sources":["styles/surface-levels.ts"],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,aAAa,EAAEC,aAAa,EAAEC,UAAU,EAAEC,OAAO,QAAwB,OAAO;AACzF,SAASC,QAAQ,QAAwB,cAAc;AAGvD,SAASC,QAAQ,QAAQ,uBAAoB;AAC7C,SAASC,SAAS,EAAEC,SAAS,QAAQ,qBAAkB;AACvD,SAASC,eAAe,QAAQ,0BAAuB;AAGvD;AACA,OAAO,MAAMC,OAAO,GAAG,GAAG;AAC1B;AACA,OAAO,MAAMC,cAAc,GAAG,CAAC;AAC/B;AACA,OAAO,MAAMC,YAAY,GAAG,CAAC;;AAE7B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMC,SAAS,GAAG;EAAEC,KAAK,EAAE,IAAI;EAAEC,IAAI,EAAE;AAAI,CAAU;;AAErD;AACA,MAAMC,aAAa,GAAG;EAAEF,KAAK,EAAE,IAAI;EAAEC,IAAI,EAAE;AAAI,CAAU;;AAEzD;AACA;AACA;AACA;AACA,OAAO,SAASE,aAAaA,CAACC,KAAY,EAAEC,MAAc,EAAU;EAClE,OAAOZ,SAAS,CAACY,MAAM,EAAED,KAAK,CAACE,MAAM,CAACC,IAAI,EAAER,SAAS,CAACK,KAAK,CAACI,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AACzF;;AAEA;AACA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","ignoreList":[]}

package/lib/module/styles/tokens.js

@@ -139,4 +139,30 @@ export const gradients = {
     hover_value: '#0A7AFF'
   }
 };
+
+/**
+ * How far a disabled control fades.
+ *
+ * ONE value, because three were in the tree: 0.5 in twenty-five places, 0.4 in
+ * six (`listing-actions`, `track-list`, `accordion`, `composer-panel`,
+ * `agent-chat`) and 0.6 in one (`listing-card`'s favourite button). Nothing
+ * distinguished them — the same kind of icon button faded to three different
+ * depths depending on which family drew it.
+ *
+ * **The convention.** A control that can RECOLOUR when disabled recolours: it
+ * swaps to the theme's own disabled fill and foreground and keeps opacity 1.
+ * That is what `Button` does, and it is preferred, because a fade multiplies
+ * against whatever is behind the control — over a coloured card a 0.5 label goes
+ * muddy rather than quiet, and a fade stacks when a disabled control sits inside
+ * a disabled group.
+ *
+ * Opacity is the fallback, for a control with NO token pair to swap to — an icon
+ * drawn in `currentColor`, a `Pressable` painting nothing of its own, a row of
+ * mixed children. When it is used, it is this number. A disabled control is
+ * exempt from the WCAG contrast floors, which is what makes a single blanket
+ * value defensible at all; it is not licence to pick a new one per family.
+ *
+ * Gate: `disabled-convention.test.ts`.
+ */
+export const DISABLED_OPACITY = 0.5;
 //# sourceMappingURL=tokens.js.map

package/lib/module/styles/tokens.js.map

@@ -1 +1 @@
-{"version":3,"names":["RADIUS","SPACING","space","_2xs","xs","sm","md","lg","xl","_2xl","_3xl","_4xl","_5xl","fontSize","lineHeight","tight","snug","normal","relaxed","borderRadius","full","animation","duration","instant","fast","slow","spring","snappy","friction","tension","gentle","bouncy","pressScale","gradients","primary","values","hover_value","sky"],"sourceRoot":"../../../src","sources":["styles/tokens.ts"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["RADIUS","SPACING","space","_2xs","xs","sm","md","lg","xl","_2xl","_3xl","_4xl","_5xl","fontSize","lineHeight","tight","snug","normal","relaxed","borderRadius","full","animation","duration","instant","fast","slow","spring","snappy","friction","tension","gentle","bouncy","pressScale","gradients","primary","values","hover_value","sky","DISABLED_OPACITY"],"sourceRoot":"../../../src","sources":["styles/tokens.ts"],"mappings":"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","ignoreList":[]}

package/lib/module/styles/web-data.js

@@ -0,0 +1,25 @@
+"use strict";
+
+import { Platform } from 'react-native';
+const IS_WEB = Platform.OS === 'web';
+
+/**
+ * The web-only `dataSet` hook an adopted sheet's selectors hang off, as spread
+ * props: react-native-web's channel to a `data-*` attribute (a class never
+ * reaches the DOM here), and nothing on native.
+ *
+ * ONE copy for the whole package — thirteen families had grown their own,
+ * byte for byte the same, under two names (`webDataSet` and `webDataSet`).
+ *
+ * ```tsx
+ * <Pressable {...webDataSet({ 'bloom-track-row': 'true' })} />
+ * // web:    <div data-bloom-track-row="true">
+ * // native: nothing
+ * ```
+ */
+export function webDataSet(entries) {
+  return IS_WEB ? {
+    dataSet: entries
+  } : {};
+}
+//# sourceMappingURL=web-data.js.map

package/lib/module/styles/web-data.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["Platform","IS_WEB","OS","webDataSet","entries","dataSet"],"sourceRoot":"../../../src","sources":["styles/web-data.ts"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,cAAc;AAEvC,MAAMC,MAAM,GAAGD,QAAQ,CAACE,EAAE,KAAK,KAAK;;AAEpC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,UAAUA,CAACC,OAA+B,EAA2B;EACnF,OAAOH,MAAM,GAAG;IAAEI,OAAO,EAAED;EAAQ,CAAC,GAAG,CAAC,CAAC;AAC3C","ignoreList":[]}

package/lib/module/tabs/Tabs.js

@@ -8,7 +8,9 @@ import { Text } from "../typography/index.js";
 import { TYPE_SCALE } from "../typography/scale.js";
 import { useInteractionState } from "../hooks/use-interaction-state.js";
 import { borderRadius } from "../styles/tokens.js";
+import { hairlineOn, surfaceFillOn, useSurfaceFill } from "../styles/surface-levels.js";
 import { interactiveWebCss, useInteractiveWebCss } from "../styles/interactive-web-css.js";
+import { webDataSet } from "../styles/web-data.js";
 import { mixColor, resolveButtonRamps } from "../button/shared.js";
 
 /**
@@ -118,20 +120,27 @@ function resolveVariant(variant) {
  * Every colour a strip paints, per variant. Pure — takes the theme rather than
  * calling `useTheme()`, so it can be walked over presets and modes.
  */
-export function resolveTabsPaint(theme, variant) {
+export function resolveTabsPaint(theme, variant, surface = theme.colors.background) {
   const {
     accent,
     neutral: n
   } = resolveButtonRamps(theme);
   const c = theme.colors;
   const dark = theme.isDark;
+  // The rail, the hover row and the filled thumb are STEPS OFF the strip's own
+  // surface, not ramp stops. As `neutral-800` the dark rail was byte for byte
+  // the fill `queue-panel` (and every other menu-surface family) paints its
+  // panel with — ΔE 0, so a tab strip inside one had no rail at all. On the page
+  // these land within 0.04 of the colours they replaced.
+  const hairline = hairlineOn(theme, surface);
+  const raised = surfaceFillOn(theme, surface);
   const count = {
     countSelectedBackground: dark ? mixColor(c.background, accent[800], 0.6) : accent[100],
     countSelectedForeground: accent[600],
     // `bg-black/10` in both modes.
     countIdleBackground: 'rgba(0, 0, 0, 0.1)',
     countIdleForeground: c.text,
-    separator: dark ? n[800] : n[200],
+    separator: hairline,
     underline: accent[600],
     ring: accent[500]
   };
@@ -150,7 +159,7 @@ export function resolveTabsPaint(theme, variant) {
       return {
         ...count,
         thumb: dark ? mixColor(c.background, accent[950], 0.6) : accent[50],
-        hover: dark ? n[800] : n[100],
+        hover: raised,
         selectedLabel: accent[500],
         selectedIcon: accent[500],
         idleLabel: n[500],
@@ -160,8 +169,8 @@ export function resolveTabsPaint(theme, variant) {
     default:
       return {
         ...count,
-        thumb: dark ? n[800] : n[200],
-        hover: dark ? mixColor(c.background, n[700], 0.6) : n[100],
+        thumb: raised,
+        hover: dark ? mixColor(surface, n[700], 0.6) : surfaceFillOn(theme, raised),
         selectedLabel: c.text,
         selectedIcon: c.text,
         idleLabel: n[500],
@@ -201,11 +210,6 @@ const GEOMETRY = {
 /** The strip's gap between triggers (`gap-1`), both variants. */
 const STRIP_GAP = 4;
 const IS_WEB = Platform.OS === 'web';
-function webData(data) {
-  return IS_WEB ? {
-    dataSet: data
-  } : {};
-}
 
 // ---------------------------------------------------------------------------
 //  Web: keyboard focus ring, colour transitions, disabled cursor
@@ -292,7 +296,8 @@ const TabsBarComponent = /*#__PURE__*/forwardRef(function TabsBar({
   useInteractiveWebCss(STYLE_ID, BLOOM_TABS_CSS);
   const resolvedVariant = resolveVariant(variant);
   const isUnderline = resolvedVariant === 'underline';
-  const paint = useMemo(() => resolveTabsPaint(theme, variant), [theme, variant]);
+  const surface = useSurfaceFill();
+  const paint = useMemo(() => resolveTabsPaint(theme, variant, surface), [theme, variant, surface]);
   const reducedMotion = useReducedMotion();
   const slideTiming = isUnderline ? UNDERLINE_TIMING : PILL_TIMING;
 
@@ -728,7 +733,7 @@ const TabComponent = ({
     color: labelColor
   }), [isUnderline, isSelected, labelColor]);
   const renderedIcon = LeadingIcon ? /*#__PURE__*/_jsx(View, {
-    ...webData({
+    ...webDataSet({
       bloomTabsIcon: ''
     }),
     style: {
@@ -757,7 +762,7 @@ const TabComponent = ({
       flex: 1
     } : undefined,
     children: /*#__PURE__*/_jsxs(Pressable, {
-      ...webData({
+      ...webDataSet({
         bloomTabsTrigger: variant
       }),
       style: [triggerStyle, fullWidth && {
@@ -787,7 +792,7 @@ const TabComponent = ({
       "aria-selected": isSelected,
       children: [showHoverLayer ? /*#__PURE__*/_jsx(View, {
         pointerEvents: "none",
-        ...webData({
+        ...webDataSet({
           bloomTabsHover: ''
         }),
         style: {
@@ -807,7 +812,7 @@ const TabComponent = ({
           gap: geometry.labelGap
         },
         children: [renderedIcon, /*#__PURE__*/_jsx(Text, {
-          ...webData({
+          ...webDataSet({
             bloomTabsLabel: ''
           }),
           numberOfLines: 1,