@oxyhq/bloom 0.79.1 → 0.81.0

package/src/tabs/expo-router/RouterTabs.tsx

@@ -0,0 +1,268 @@
+/**
+ * expo-router bindings for the in-screen tab strip.
+ *
+ * This subpath (`@oxyhq/bloom/tabs/expo-router`) is the ONLY place in the tabs
+ * feature allowed to import `expo-router`, which is why it is a separate entry:
+ * the core `@oxyhq/bloom/tabs` stays usable in an app with a different router,
+ * or none, and the optional peer is never pulled into a bundle that does not
+ * ask for it. Same split as `tab-bar` / `tab-bar/expo-router` and
+ * `scroll` / `scroll/expo-router`.
+ *
+ * Everything routing-shaped lives here on purpose: which tab the route means,
+ * what a committed swipe navigates to, and which links to warm. The strip
+ * itself stays presentational and knows only about measured geometry.
+ */
+import { useCallback, useEffect, useMemo, useRef, type ReactNode } from 'react';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import { runOnJS } from 'react-native-reanimated';
+import { router, usePathname, type Href } from 'expo-router';
+
+import { Tabs, TabsTrigger, type TabsDragController } from '../Tabs';
+import type { TabsProps } from '../types';
+
+export interface RouterTabItem {
+  /** Stable id for the tab. Used as a React key and a callback argument. */
+  value: string;
+  /** Tab label text. */
+  label: string;
+  /** The route this tab shows. Must be the tab's EXACT path. */
+  href: Href;
+  /** Icon rendered before the label. */
+  icon?: ReactNode;
+  /** Optional tally beside the label; `0` or omitted renders nothing. */
+  count?: number;
+  disabled?: boolean;
+}
+
+export type RouterTabsProps = Omit<
+  TabsProps,
+  // All three describe a selection the ROUTE already answers, so accepting them
+  // here would let a caller contradict the router.
+  'value' | 'onValueChange' | 'hasSelection' | 'children'
+> & {
+  items: RouterTabItem[];
+  /**
+   * Called instead of navigating when the ALREADY-active tab is pressed.
+   *
+   * Without it a re-tap would push a second history entry for the route the
+   * user is already on, so Back would appear to do nothing. Re-tapping the
+   * active tab conventionally means "refresh" or "scroll to top", and that is
+   * the caller's to define.
+   */
+  onReselect?: (value: string) => void;
+  /**
+   * Enable the horizontal swipe between neighbouring tabs. Defaults to `true`.
+   *
+   * The gesture is INDICATOR-LED: the underline tracks the finger toward the
+   * neighbour and commits on release past a threshold, while the content stays
+   * where it is. That asymmetry is deliberate — the underline has somewhere
+   * real to go and can complete its journey, whereas under a `<Slot/>` there is
+   * no neighbouring screen mounted to bring in, so translating the content
+   * would only open a blank gutter on the trailing edge.
+   */
+  swipeEnabled?: boolean;
+};
+
+/**
+ * Resolve which item the current route belongs to.
+ *
+ * LONGEST matching prefix, on a segment boundary — not an exact match. All
+ * three properties matter:
+ *
+ * - A prefix is needed because a tab may own a subtree (`/feeds/1/topics` and
+ *   anything under it), and an exact match would drop the underline the moment
+ *   the user goes one level deeper.
+ * - LONGEST is needed because the default tab's href is a prefix of every
+ *   sibling's (`/@ana` vs `/@ana/replies`), so a first-match rule would light
+ *   up the default tab on every tab.
+ * - The segment boundary is what stops `/feeds/12` from matching `/feeds/1`.
+ *
+ * Returns `undefined` when nothing matches, which is a real state — a strip
+ * rendered by a LAYOUT keeps rendering while a child route outside the tab set
+ * is showing — and leaves the underline hidden rather than parked on a lie.
+ */
+function matchActiveValue(items: RouterTabItem[], pathname: string): string | undefined {
+  let best: { value: string; length: number } | undefined;
+  for (const item of items) {
+    // `Href` is a string or an object; only a string form can be compared to a
+    // pathname, and an object form describes params we cannot resolve here.
+    if (typeof item.href !== 'string') continue;
+    // Compare paths only: a query string describes what the tab shows, not
+    // which tab it is, and a trailing slash is the same route either way.
+    const [path = ''] = item.href.split('?');
+    const href = path.replace(/\/$/, '');
+    const isMatch = pathname === href || pathname.startsWith(`${href}/`);
+    if (!isMatch) continue;
+    if (!best || href.length > best.length) {
+      best = { value: item.value, length: href.length };
+    }
+  }
+  return best?.value;
+}
+
+/**
+ * A tab strip whose selection IS the route.
+ *
+ * Render it in the LAYOUT that owns the tabs, above the `<Slot/>` that renders
+ * them — not inside the tab screens themselves. That placement is the whole
+ * point, and it is load-bearing twice over: a strip inside the screens is
+ * unmounted and rebuilt by every navigation, so its underline has nothing to
+ * animate from and the chrome blanks while the incoming route's chunk loads;
+ * and a GESTURE inside the screens would be destroyed by the very navigation it
+ * commits, mid-release.
+ *
+ * ```tsx
+ * // app/(app)/[username]/_layout.tsx
+ * <RouterTabs
+ *   items={[
+ *     { value: 'posts', label: 'Posts', href: `/${username}` },
+ *     { value: 'replies', label: 'Replies', href: `/${username}/replies` },
+ *   ]}
+ * />
+ * <Slot />
+ * ```
+ */
+export function RouterTabs({
+  items,
+  onReselect,
+  swipeEnabled = true,
+  ...tabsProps
+}: RouterTabsProps) {
+  const pathname = usePathname();
+  const activeValue = useMemo(() => matchActiveValue(items, pathname), [items, pathname]);
+  const dragRef = useRef<TabsDragController>(null);
+  // What releasing right now would commit. A ref rather than state: it is
+  // written on every frame of the drag and read once, and re-rendering the
+  // strip mid-gesture would fight the animation the gesture is driving.
+  const pendingRef = useRef<string | null>(null);
+
+  const navigateTo = useCallback(
+    (value: string) => {
+      const target = items.find((item) => item.value === value);
+      if (!target) return;
+      // PUSH, not replace: a history entry per tab is what makes Back return to
+      // the tab the reader came from instead of leaving the screen entirely.
+      router.push(target.href);
+    },
+    [items],
+  );
+
+  const handlePress = useCallback(
+    (item: RouterTabItem) => {
+      if (item.value === activeValue) {
+        onReselect?.(item.value);
+        return;
+      }
+      navigateTo(item.value);
+    },
+    [activeValue, onReselect, navigateTo],
+  );
+
+  const onDrag = useCallback((translationX: number) => {
+    pendingRef.current = dragRef.current?.drag(translationX) ?? null;
+  }, []);
+
+  // `onEnd` does not fire for every terminated gesture, and `onFinalize` fires
+  // for all of them — including after `onEnd`. Guarding on the ref being
+  // non-null is what makes the second call a no-op instead of a double commit.
+  const releasedRef = useRef(true);
+  const onRelease = useCallback(() => {
+    if (releasedRef.current) return;
+    releasedRef.current = true;
+    const committed = pendingRef.current;
+    pendingRef.current = null;
+    // The underline commits first and instantly: it lives in the layout, it
+    // survives the swap, and it is the honest signal the gesture was accepted.
+    // The content area arrives when its chunk does.
+    dragRef.current?.release(committed);
+    if (committed !== null) navigateTo(committed);
+  }, [navigateTo]);
+
+  const onBegin = useCallback(() => {
+    releasedRef.current = false;
+  }, []);
+
+  const panGesture = useMemo(
+    () =>
+      Gesture.Pan()
+        // Horizontal intent only. This is a hint to the gesture system and is
+        // NOT what protects vertical scrolling on web — see `touchAction` below.
+        .activeOffsetX([-12, 12])
+        .failOffsetY([-12, 12])
+        .onBegin(() => {
+          runOnJS(onBegin)();
+        })
+        .onUpdate((event) => {
+          runOnJS(onDrag)(event.translationX);
+        })
+        .onFinalize(() => {
+          runOnJS(onRelease)();
+        }),
+    [onBegin, onDrag, onRelease],
+  );
+
+  // Warm every OTHER tab's async chunk. That fetch is the ~300ms the content
+  // area would otherwise spend empty after a commit, and a swipe offers no
+  // hover to warm on, so it is done up front rather than on interaction.
+  //
+  // `router.prefetch` — the public imperative API (declared in expo-router's
+  // `global-state/router.d.ts`) — rather than wrapping each trigger in
+  // `<Link prefetch asChild>`. Both reasons are about the WRAPPER, not about
+  // prefetching: `asChild` is Radix's `Slot`, which COMPOSES event handlers, so
+  // the trigger's own `onPress` and the link's navigation would both run — and
+  // the link's push knows nothing about `onReselect`, so re-tapping the active
+  // tab would push a duplicate entry and make Back appear to do nothing. It
+  // also injects an `href` a `Pressable` ignores. The prefetching itself is
+  // identical: `<Link prefetch>` renders `<Prefetch href/>` beside its element
+  // and does nothing else.
+  //
+  // Known trade: a real `<Link>` would render a web anchor, which is what gives
+  // middle-click and open-in-new-tab. A tab strip arguably wants that; getting
+  // both needs the trigger to render an anchor itself, which is a change to the
+  // core rather than to this file.
+  useEffect(() => {
+    for (const item of items) {
+      if (item.value === activeValue || item.disabled) continue;
+      router.prefetch(item.href);
+    }
+  }, [items, activeValue]);
+
+  const strip = (
+    // `hasSelection` is what stops the underline asserting a tab while a
+    // NON-TAB sibling route is showing — the layout that renders this strip
+    // renders those too (a profile's `/followers` beside its tab routes).
+    <Tabs {...tabsProps} ref={dragRef} hasSelection={activeValue !== undefined}>
+      {items.map((item) => (
+        <TabsTrigger
+          key={item.value}
+          value={item.value}
+          label={item.label}
+          icon={item.icon}
+          count={item.count}
+          disabled={item.disabled}
+          // Focus, never a press, is what drives the underline — so a deep
+          // link, a browser Back and a back gesture animate exactly like a tap.
+          isFocused={item.value === activeValue}
+          onPress={() => handlePress(item)}
+        />
+      ))}
+    </Tabs>
+  );
+
+  if (!swipeEnabled) return strip;
+
+  return (
+    // `touchAction="pan-y"` is MANDATORY and is the landmine of this file.
+    // RNGH sets the detector's view to `touch-action: none` on web
+    // (`GestureHandlerWebDelegate.js`), which disables browser-native VERTICAL
+    // scrolling on that element. `failOffsetY` above does not protect against
+    // it: that is a JS decision taken after `touch-action` has already told the
+    // browser not to scroll. Removing this prop is silent on native and breaks
+    // scrolling on mobile web.
+    <GestureDetector gesture={panGesture} touchAction="pan-y">
+      {strip}
+    </GestureDetector>
+  );
+}
+
+RouterTabs.displayName = 'RouterTabs';

package/src/tabs/expo-router/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Entry for `@oxyhq/bloom/tabs/expo-router`. The component lives in a sibling
+ * module because this file is the published entry path and must stay stable;
+ * the split also keeps the router binding in one place, which is what the
+ * optional-peer allowlist asserts about.
+ */
+export { RouterTabs } from './RouterTabs';
+export type { RouterTabItem, RouterTabsProps } from './RouterTabs';

package/src/tabs/types.ts

@@ -3,10 +3,38 @@ import type { StyleProp, ViewStyle, TextStyle } from 'react-native';
 export type TabsVariant = 'underline' | 'filled' | 'outlined';
 
 export interface TabsProps {
-  /** The currently selected tab value. */
-  value: string;
-  /** Called when a tab is selected. */
-  onValueChange: (value: string) => void;
+  /**
+   * The currently selected tab value — the CONTROLLED path, where the bar owns
+   * the underline and reports presses through {@link TabsProps.onValueChange}.
+   *
+   * OMIT it for the focus-driven path, where each trigger supplies its own
+   * {@link TabsTriggerProps.isFocused} and performs its own navigation. That is
+   * how `@oxyhq/bloom/tabs/expo-router` keeps the underline correct through
+   * deep links, browser Back and back gestures — none of which pass through a
+   * press handler. Providing both would put two writers on one shared value.
+   */
+  value?: string;
+  /** Called when a tab is selected. Controlled path only. */
+  onValueChange?: (value: string) => void;
+  /**
+   * Focus-driven path only: whether ANY trigger is currently focused.
+   *
+   * `false` fades the underline out where it stands. This is not the same as
+   * "the selection moved", and it is not hypothetical: a strip rendered by a
+   * LAYOUT keeps rendering while the layout's other, non-tab children are
+   * showing — a profile's `/followers` sits beside its tab routes under one
+   * layout — and without this the underline stays parked on whichever tab was
+   * last visited, asserting a selection that is not there.
+   *
+   * Fading is the whole response; the underline is deliberately NOT moved,
+   * because there is no position that means "nowhere" and travelling to a
+   * sentinel would drag it across every tab on the way out.
+   *
+   * `RouterTabs` sets it, so an app author never passes it by hand. Defaults to
+   * `true`, which is correct for the controlled path (a `value` naming no
+   * trigger simply leaves the underline where it was, as it always has).
+   */
+  hasSelection?: boolean;
   /** Visual variant for the tab bar. */
   variant?: TabsVariant;
   /**
@@ -29,8 +57,24 @@ export interface TabsTriggerProps {
   label: string;
   /** Icon rendered before the label. */
   icon?: React.ReactNode;
+  /**
+   * Optional tally rendered as a small muted number beside the label. Omitted
+   * (or `0`) renders nothing. The underline tracks the trigger's measured
+   * width, so a count never changes where it sits.
+   */
+  count?: number;
+  /**
+   * Whether the ROUTER considers this tab focused — the focus-driven path.
+   * Supplying it makes this trigger, not the bar, the writer of the shared
+   * underline, and suppresses {@link TabsProps.onValueChange} on press because
+   * navigation is then the caller's job. Leave it `undefined` on the controlled
+   * path.
+   */
+  isFocused?: boolean;
   /** Whether this tab is disabled. */
   disabled?: boolean;
+  /** Extra press handler. Runs on both paths, before any selection is reported. */
+  onPress?: () => void;
   style?: StyleProp<ViewStyle>;
   textStyle?: StyleProp<TextStyle>;
 }

package/src/theme/__tests__/__fixtures__/golden-resolved-tokens.json

@@ -1558,5 +1558,125 @@
     "--info-foreground": "rgb(255 255 255)",
     "--info-text": "rgb(173 198 255)",
     "--info-subtle": "rgba(59, 130, 246, 0.24)"
+  },
+  "mono/light": {
+    "--background": "rgb(243 243 243)",
+    "--foreground": "rgb(27 27 27)",
+    "--surface": "rgb(243 243 243)",
+    "--surface-foreground": "rgb(27 27 27)",
+    "--popover": "rgb(238 238 238)",
+    "--popover-foreground": "rgb(27 27 27)",
+    "--primary": "rgb(31 31 31)",
+    "--primary-foreground": "rgb(255 255 255)",
+    "--secondary": "rgb(85 85 85)",
+    "--secondary-foreground": "rgb(255 255 255)",
+    "--tertiary": "rgb(31 31 31)",
+    "--tertiary-foreground": "rgb(255 255 255)",
+    "--muted": "rgb(232 232 232)",
+    "--muted-foreground": "rgb(71 71 71)",
+    "--accent": "rgb(232 232 232)",
+    "--accent-foreground": "rgb(71 71 71)",
+    "--destructive": "rgb(186 26 26)",
+    "--border": "rgb(198 198 198)",
+    "--input": "rgb(198 198 198)",
+    "--ring": "rgb(0 0 0)",
+    "--sidebar": "rgb(243 243 243)",
+    "--card": "rgb(255 255 255)",
+    "--card-foreground": "rgb(27 27 27)",
+    "--chart-1": "rgb(193 193 193)",
+    "--chart-2": "rgb(158 158 158)",
+    "--chart-3": "rgb(124 124 124)",
+    "--chart-4": "rgb(92 92 92)",
+    "--chart-5": "rgb(62 62 62)",
+    "--content-area": "rgb(249 249 249)",
+    "--sidebar-foreground": "rgb(27 27 27)",
+    "--sidebar-primary": "rgb(0 0 0)",
+    "--sidebar-primary-foreground": "rgb(226 226 226)",
+    "--sidebar-accent": "rgb(212 212 212)",
+    "--sidebar-accent-foreground": "rgb(27 27 27)",
+    "--sidebar-border": "rgb(198 198 198)",
+    "--sidebar-ring": "rgb(0 0 0)",
+    "--primary-text": "rgb(0 0 0)",
+    "--primary-subtle": "rgba(145, 145, 145, 0.13)",
+    "--secondary-text": "rgb(94 94 94)",
+    "--secondary-subtle": "rgba(145, 145, 145, 0.13)",
+    "--tertiary-text": "rgb(94 94 94)",
+    "--tertiary-subtle": "rgba(145, 145, 145, 0.13)",
+    "--success": "rgb(0 122 83)",
+    "--success-foreground": "rgb(255 255 255)",
+    "--success-text": "rgb(0 108 73)",
+    "--success-subtle": "rgba(16, 185, 129, 0.13)",
+    "--error": "rgb(203 41 46)",
+    "--error-foreground": "rgb(255 255 255)",
+    "--error-text": "rgb(167 55 53)",
+    "--error-subtle": "rgba(239, 68, 68, 0.13)",
+    "--warning": "rgb(150 94 0)",
+    "--warning-foreground": "rgb(255 255 255)",
+    "--warning-text": "rgb(133 83 0)",
+    "--warning-subtle": "rgba(245, 158, 11, 0.13)",
+    "--info": "rgb(5 102 217)",
+    "--info-foreground": "rgb(255 255 255)",
+    "--info-text": "rgb(1 90 194)",
+    "--info-subtle": "rgba(59, 130, 246, 0.13)"
+  },
+  "mono/dark": {
+    "--background": "rgb(14 14 14)",
+    "--foreground": "rgb(226 226 226)",
+    "--surface": "rgb(27 27 27)",
+    "--surface-foreground": "rgb(226 226 226)",
+    "--popover": "rgb(31 31 31)",
+    "--popover-foreground": "rgb(226 226 226)",
+    "--primary": "rgb(238 238 238)",
+    "--primary-foreground": "rgb(0 0 0)",
+    "--secondary": "rgb(176 176 176)",
+    "--secondary-foreground": "rgb(0 0 0)",
+    "--tertiary": "rgb(238 238 238)",
+    "--tertiary-foreground": "rgb(0 0 0)",
+    "--muted": "rgb(42 42 42)",
+    "--muted-foreground": "rgb(198 198 198)",
+    "--accent": "rgb(42 42 42)",
+    "--accent-foreground": "rgb(198 198 198)",
+    "--destructive": "rgb(255 180 171)",
+    "--border": "rgb(71 71 71)",
+    "--input": "rgb(71 71 71)",
+    "--ring": "rgb(255 255 255)",
+    "--sidebar": "rgb(27 27 27)",
+    "--card": "rgb(31 31 31)",
+    "--card-foreground": "rgb(226 226 226)",
+    "--chart-1": "rgb(94 94 94)",
+    "--chart-2": "rgb(127 127 127)",
+    "--chart-3": "rgb(160 160 160)",
+    "--chart-4": "rgb(196 196 196)",
+    "--chart-5": "rgb(232 232 232)",
+    "--content-area": "rgb(19 19 19)",
+    "--sidebar-foreground": "rgb(226 226 226)",
+    "--sidebar-primary": "rgb(255 255 255)",
+    "--sidebar-primary-foreground": "rgb(27 27 27)",
+    "--sidebar-accent": "rgb(71 71 71)",
+    "--sidebar-accent-foreground": "rgb(226 226 226)",
+    "--sidebar-border": "rgb(71 71 71)",
+    "--sidebar-ring": "rgb(255 255 255)",
+    "--primary-text": "rgb(255 255 255)",
+    "--primary-subtle": "rgba(145, 145, 145, 0.24)",
+    "--secondary-text": "rgb(198 198 198)",
+    "--secondary-subtle": "rgba(145, 145, 145, 0.24)",
+    "--tertiary-text": "rgb(198 198 198)",
+    "--tertiary-subtle": "rgba(145, 145, 145, 0.24)",
+    "--success": "rgb(0 133 91)",
+    "--success-foreground": "rgb(255 255 255)",
+    "--success-text": "rgb(59 224 161)",
+    "--success-subtle": "rgba(16, 185, 129, 0.24)",
+    "--error": "rgb(218 52 55)",
+    "--error-foreground": "rgb(255 255 255)",
+    "--error-text": "rgb(255 179 173)",
+    "--error-subtle": "rgba(239, 68, 68, 0.24)",
+    "--warning": "rgb(163 103 0)",
+    "--warning-foreground": "rgb(255 255 255)",
+    "--warning-text": "rgb(255 185 95)",
+    "--warning-subtle": "rgba(245, 158, 11, 0.24)",
+    "--info": "rgb(33 112 228)",
+    "--info-foreground": "rgb(255 255 255)",
+    "--info-text": "rgb(173 198 255)",
+    "--info-subtle": "rgba(59, 130, 246, 0.24)"
   }
 }

package/src/theme/__tests__/__snapshots__/visual-gallery.test.tsx.snap

@@ -352,6 +352,76 @@ exports[`theme.colors snapshot for all presets (catches unintended palette shift
     "tint": "rgb(0 120 108)",
     "warning": "rgb(150 94 0)",
   },
+  "mono/dark": {
+    "background": "rgb(14 14 14)",
+    "backgroundSecondary": "rgb(27 27 27)",
+    "backgroundTertiary": "rgb(31 31 31)",
+    "border": "rgb(71 71 71)",
+    "borderLight": "rgb(71 71 71)",
+    "card": "rgb(31 31 31)",
+    "contrast50": "rgb(42 42 42)",
+    "error": "rgb(218 52 55)",
+    "icon": "rgb(198 198 198)",
+    "iconActive": "rgb(238 238 238)",
+    "info": "rgb(33 112 228)",
+    "negative": "rgb(255 180 171)",
+    "negativeForeground": "rgb(105 0 5)",
+    "negativeSubtle": "rgba(239, 68, 68, 0.24)",
+    "negativeSubtleForeground": "rgb(255 179 173)",
+    "overlay": "rgba(0, 0, 0, 0.5)",
+    "primary": "rgb(238 238 238)",
+    "primaryDark": "rgb(14 14 14)",
+    "primaryForeground": "rgb(0 0 0)",
+    "primaryLight": "rgb(27 27 27)",
+    "primarySubtle": "rgba(145, 145, 145, 0.24)",
+    "primarySubtleForeground": "rgb(0 0 0)",
+    "secondary": "rgb(176 176 176)",
+    "secondaryForeground": "rgb(0 0 0)",
+    "shadow": "rgba(0, 0, 0, 0.3)",
+    "success": "rgb(0 133 91)",
+    "tertiary": "rgb(238 238 238)",
+    "tertiaryForeground": "rgb(0 0 0)",
+    "text": "rgb(226 226 226)",
+    "textSecondary": "rgb(198 198 198)",
+    "textTertiary": "rgb(145 145 145)",
+    "tint": "rgb(238 238 238)",
+    "warning": "rgb(163 103 0)",
+  },
+  "mono/light": {
+    "background": "rgb(243 243 243)",
+    "backgroundSecondary": "rgb(243 243 243)",
+    "backgroundTertiary": "rgb(238 238 238)",
+    "border": "rgb(198 198 198)",
+    "borderLight": "rgb(198 198 198)",
+    "card": "rgb(255 255 255)",
+    "contrast50": "rgb(232 232 232)",
+    "error": "rgb(203 41 46)",
+    "icon": "rgb(71 71 71)",
+    "iconActive": "rgb(31 31 31)",
+    "info": "rgb(5 102 217)",
+    "negative": "rgb(186 26 26)",
+    "negativeForeground": "rgb(255 255 255)",
+    "negativeSubtle": "rgba(239, 68, 68, 0.13)",
+    "negativeSubtleForeground": "rgb(167 55 53)",
+    "overlay": "rgba(0, 0, 0, 0.5)",
+    "primary": "rgb(31 31 31)",
+    "primaryDark": "rgb(243 243 243)",
+    "primaryForeground": "rgb(255 255 255)",
+    "primaryLight": "rgb(243 243 243)",
+    "primarySubtle": "rgba(145, 145, 145, 0.13)",
+    "primarySubtleForeground": "rgb(255 255 255)",
+    "secondary": "rgb(85 85 85)",
+    "secondaryForeground": "rgb(255 255 255)",
+    "shadow": "rgba(0, 0, 0, 0.1)",
+    "success": "rgb(0 122 83)",
+    "tertiary": "rgb(31 31 31)",
+    "tertiaryForeground": "rgb(255 255 255)",
+    "text": "rgb(27 27 27)",
+    "textSecondary": "rgb(71 71 71)",
+    "textTertiary": "rgb(119 119 119)",
+    "tint": "rgb(31 31 31)",
+    "warning": "rgb(150 94 0)",
+  },
   "orange/dark": {
     "background": "rgb(23 11 5)",
     "backgroundSecondary": "rgb(38 24 17)",

package/src/theme/__tests__/policy-legibility.test.ts

@@ -3,7 +3,7 @@
  *
  * Every accent and status family is generated, not authored, so nothing else in
  * the suite can notice when a tuning change makes a label unreadable. This walks
- * the full matrix — 13 presets x 2 modes x 7 families — and asserts the property
+ * the full matrix — every preset x 2 modes x 7 families — and asserts the property
  * a user actually perceives.
  *
  * Two failure shapes it exists to catch, both of which have already happened:
@@ -124,7 +124,11 @@ describe('colour policy legibility', () => {
   // Each half was individually legible, so nothing else could catch either.
   it('the brand fill keeps light exemption-free and dark budgeted', () => {
     const white = { light: 0, dark: 0 };
-    for (const preset of APP_COLOR_NAMES) {
+    // `mono` is not governed by the budget — it has no chroma to preserve, and its
+    // dark fill is near-WHITE by design, so it takes a black label on purpose.
+    // Counting it here would let a real regression hide inside its slack.
+    const chromatic = APP_COLOR_NAMES.filter((name) => name !== 'mono');
+    for (const preset of chromatic) {
       for (const mode of ['light', 'dark'] as const) {
         if (getResolvedTokens(preset, mode)['--primary-foreground'] === 'rgb(255 255 255)') {
           white[mode] += 1;
@@ -133,7 +137,11 @@ describe('colour policy legibility', () => {
     }
     // Light admits no exemption, so every preset carries white there. Dark keeps
     // the budget, so the seeds that are already light keep their colour instead.
-    expect(white.light).toBe(APP_COLOR_NAMES.length);
-    expect(white.dark).toBeGreaterThan(APP_COLOR_NAMES.length - 4);
+    expect(white.light).toBe(chromatic.length);
+    expect(white.dark).toBeGreaterThan(chromatic.length - 4);
+    // And the monochrome exception itself, stated rather than tolerated: a fill at
+    // each end of the scale, carrying the opposite label.
+    expect(getResolvedTokens('mono', 'light')['--primary-foreground']).toBe('rgb(255 255 255)');
+    expect(getResolvedTokens('mono', 'dark')['--primary-foreground']).toBe('rgb(0 0 0)');
   });
 });

package/src/theme/color-engine/index.ts

@@ -10,7 +10,7 @@
 export { Hct } from './hct';
 export { TonalPalette } from './tonal-palette';
 export { DynamicScheme } from './dynamic-scheme';
-export { buildScheme, schemeVibrant, schemeExpressive, schemeTonalSpot, schemeNeutral } from './scheme-variants';
+export { buildScheme, schemeVibrant, schemeExpressive, schemeTonalSpot, schemeNeutral, schemeMonochrome } from './scheme-variants';
 export type { SchemeVariant, AccentSources } from './scheme-variants';
 export { Roles } from './color-roles';
 export type { RoleName } from './color-roles';

package/src/theme/color-engine/scheme-variants.ts

@@ -13,7 +13,13 @@ import { sanitizeDegreesDouble } from './math-utils';
 import { TonalPalette } from './tonal-palette';
 import { Variant } from './variant';
 
-export type SchemeVariant = 'vivid' | 'vibrant' | 'expressive' | 'tonalSpot' | 'neutral';
+export type SchemeVariant =
+  | 'vivid'
+  | 'vibrant'
+  | 'expressive'
+  | 'tonalSpot'
+  | 'neutral'
+  | 'monochrome';
 
 /**
  * Optional explicit accent seeds for a scheme. When a source HCT is supplied, its
@@ -191,6 +197,36 @@ export function schemeNeutral(
   });
 }
 
+/**
+ * No colour at all: every palette is greyscale, so the seed's hue is irrelevant
+ * and only its tone survives. This is the variant the `isMonochrome` role
+ * branches in `color-roles` were written for — they push `primary` to the far end
+ * of the scale (tone 0 on a light page, 100 on a dark one) rather than the
+ * mid-tone the chromatic curves would pick, which is what keeps a black-and-white
+ * theme from reading as a grey one.
+ *
+ * A pinned accent is ignored on purpose: honouring it would put one coloured
+ * family back into a scheme whose entire point is that nothing is coloured.
+ */
+export function schemeMonochrome(
+  source: Hct,
+  isDark: boolean,
+  contrastLevel: number,
+): DynamicScheme {
+  const grey = (): TonalPalette => TonalPalette.fromHueAndChroma(source.hue, 0);
+  return new DynamicScheme({
+    sourceColorArgb: source.toInt(),
+    variant: Variant.MONOCHROME,
+    contrastLevel,
+    isDark,
+    primaryPalette: grey(),
+    secondaryPalette: grey(),
+    tertiaryPalette: grey(),
+    neutralPalette: grey(),
+    neutralVariantPalette: grey(),
+  });
+}
+
 const BUILDERS: Record<
   SchemeVariant,
   (s: Hct, d: boolean, c: number, accents: AccentSources) => DynamicScheme
@@ -200,6 +236,7 @@ const BUILDERS: Record<
   expressive: schemeExpressive,
   tonalSpot: schemeTonalSpot,
   neutral: schemeNeutral,
+  monochrome: schemeMonochrome,
 };
 
 /**