@oxy.so/bloom 2.9.0 → 2.11.0

package/src/app-shell/types.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 
+import type { ContentPanelFramedBreakpoint } from '../content-panel/types';
 import type { NotificationCenterItem, NotificationCenterTab } from '../notification-center/types';
 import type { SidebarProps } from '../sidebar/types';
 
@@ -13,13 +14,67 @@ import type { SidebarProps } from '../sidebar/types';
  */
 export type AppShellDrawer = 'overlay' | 'reveal';
 
+/**
+ * The layout SHAPE, all drawn by the same engine — the same nav, the same
+ * drawer, the same pinned regions, the same slots.
+ *
+ * - `dashboard` (default) — nav, then one fluid content column capped at
+ *   `contentMaxWidth`, with an optional `aside`. The shape this shell shipped
+ *   with; unchanged in every measurement.
+ * - `feed` — nav, then the routed content CENTRED in a reading column of
+ *   `contentWidth`, with the optional `aside` beside it and the pair centred in
+ *   what the nav leaves. Wrap the column in a `ContentPanel` with `panel` and
+ *   the page background reads as a gutter around it.
+ * - `split` — a list pane, a detail pane and an optional info pane, each
+ *   scrolling on its own, with a draggable divider. One screen, never a
+ *   document scroll (see `scroll`). Below `splitFrom` exactly one pane renders,
+ *   chosen by `pane`.
+ * - `focus` — a single centred column of `contentWidth` and NO nav: sign-in,
+ *   onboarding, a reader. It keeps the header, `topBar`, `bottomBar` and
+ *   `floatingAction` slots, so a sign-up flow still gets its footer CTA.
+ */
+export type AppShellVariant = 'dashboard' | 'feed' | 'split' | 'focus';
+
+/** Which single pane a `split` shell shows below `splitFrom`. */
+export type AppShellPane = 'list' | 'detail' | 'info';
+
+/** A tier from `BREAKPOINTS`, the one source of truth for widths. */
+/**
+ * Where a region changes shape: one of Bloom's named tiers, or a WIDTH IN
+ * PIXELS for an app whose own layout does not land on them — a feed whose side
+ * column earns its place at 990, a rail that goes in flow at 500. The named
+ * tiers stay the default vocabulary; a number is the escape hatch, resolved by
+ * `breakpointPx`.
+ */
+export type AppShellBreakpoint = 'sm' | 'md' | 'lg' | 'xl' | number;
+
+/** What scrolls the page. See `AppShellProps['scroll']`. */
+export type AppShellScroll = 'document' | 'container' | 'fixed';
+
+/**
+ * When a bar slot is drawn: `compact` (the default) only while the nav is a
+ * drawer — the phone case the slot exists for — or `always`, for a bar that is
+ * part of the app at every width (a player, a status strip).
+ */
+export type AppShellBarVisibility = 'compact' | 'always';
+
 export interface AppShellProps {
+  /**
+   * The layout shape. Defaults to `dashboard` — the behaviour this component
+   * had before variants existed, down to the pixel.
+   */
+  variant?: AppShellVariant;
   /**
    * The rail. Rendered in flow at `lg` and up (`sm` and up with
    * `variant: 'rail'`); below it, the same props drive the drawer (`mobile`,
    * and `flat` for `reveal`), always as the panel.
    */
-  sidebar?: Omit<SidebarProps, 'mobile' | 'onClose' | 'flat'>;
+  sidebar?: Omit<SidebarProps, 'mobile' | 'onClose'>;
+  /**
+   * How the rail arrives below `navFrom`. `reveal` slides the WHOLE page
+   * sideways, which only reads on a one-column page — so it applies to
+   * `variant: 'dashboard'` and the other three always take the overlay drawer.
+   */
   drawer?: AppShellDrawer;
   /**
    * Heading over the content. Optional: without it (and without `breadcrumb` /
@@ -35,6 +90,11 @@ export interface AppShellProps {
   /**
    * Replaces the whole header. Put an `AppShellMenuButton` in it to keep the
    * drawer reachable on narrow screens.
+   *
+   * `null` means NO header — the shell draws nothing at all, not even the
+   * menu button it would otherwise render for a drawer, because the page has
+   * said it owns that corner. Leave the prop off (or `undefined`) to get the
+   * default header.
    */
   header?: ReactNode;
   /**
@@ -47,7 +107,7 @@ export interface AppShellProps {
   /** The aside column's width. Defaults to 320. */
   asideWidth?: number;
   /** The breakpoint the aside sits beside the content from. Defaults to `xl` (1280). */
-  asideFrom?: 'md' | 'lg' | 'xl';
+  asideFrom?: AppShellBreakpoint;
   /** Below `asideFrom`: `stack` (default) renders it after the content, `hidden` drops it. */
   asideCollapse?: 'stack' | 'hidden';
   children?: ReactNode;
@@ -73,7 +133,108 @@ export interface AppShellProps {
    *   so the page owns its own scrolling — a chat, a map, a board. On web the
    *   frame is `100dvh`; on native it fills its parent.
    */
-  scroll?: 'document' | 'container' | 'fixed';
+  scroll?: AppShellScroll;
+
+  // -- sizes and breakpoints -------------------------------------------------
+  /**
+   * `feed` / `focus`: the reading column's width. Default 600 — the measure a
+   * single column of body text stays readable at. It is a MAXIMUM on a narrow
+   * screen: the column shrinks to the space it has rather than overflowing.
+   */
+  contentWidth?: number;
+  /**
+   * The space between the shell's edge and its regions. Default 12 for
+   * `dashboard` (which also keeps its historical 16 column gap, so existing
+   * pages do not move) and 16 for the other variants, where one number drives
+   * both.
+   */
+  gutter?: number;
+  /**
+   * The width the nav sits in FLOW from; below it the same nav is a drawer.
+   * Defaults to the tier the sidebar's own variant implies — `sm` for a rail
+   * (80px fits early), `lg` for the full panel — and to `sm` whenever
+   * `navExpandedFrom` is set, because below that tier the nav IS a rail.
+   */
+  navFrom?: AppShellBreakpoint;
+  /**
+   * Icons below, labels from here up: the shell swaps `sidebar.variant` between
+   * `rail` and `panel` at this width. Unset (the default) the sidebar keeps
+   * whatever variant it was given at every width.
+   */
+  navExpandedFrom?: AppShellBreakpoint;
+
+  // -- feed ------------------------------------------------------------------
+  /**
+   * `feed`: wrap the centre column in a `ContentPanel`, so the page background
+   * reads as a gutter around a framed surface. The shell renders the panel —
+   * a page that renders its own inside this one trips `ContentPanel`'s nesting
+   * guard. The panel's content is inset by `gutter`, so `contentWidth` stays
+   * the COLUMN's width and the reading measure inside it is that minus two
+   * gutters.
+   */
+  panel?: boolean;
+  /** Forwarded to that `ContentPanel`: the width it starts being framed at. */
+  framedFrom?: ContentPanelFramedBreakpoint;
+
+  // -- split -----------------------------------------------------------------
+  /** `split`: the first pane. `children` is the detail pane beside it. */
+  list?: ReactNode;
+  /** `split`: an optional third pane, from `infoFrom`. */
+  info?: ReactNode;
+  /** `split`: which single pane renders below `splitFrom`. Default `list`. */
+  pane?: AppShellPane;
+  /** `split`: the list pane's resting width (360); a drag moves it in range. */
+  listWidth?: number;
+  /** `split`: the range a drag may reach. Defaults 280 and 520. */
+  listMinWidth?: number;
+  listMaxWidth?: number;
+  /** `split`: reports the width a drag settled on. */
+  onListWidthChange?: (width: number) => void;
+  /** `split`: the info pane's width. Default 320. */
+  infoWidth?: number;
+  /** `split`: the width two panes fit from. Default `md` (768). */
+  splitFrom?: AppShellBreakpoint;
+  /** `split`: the width the third pane fits from. Default `xl` (1280). */
+  infoFrom?: AppShellBreakpoint;
+  /** `split`: whether the divider drags. Default `true`. */
+  resizable?: boolean;
+  /** `split`: names the divider. Default `"Resize panes"`. */
+  resizeLabel?: string;
+  /**
+   * `split`: the shell gives each pane its own `ScrollView` (default). Turn it
+   * off when the pane's own content scrolls — a `FlatList`, a virtualizer —
+   * rather than nesting two scrollers.
+   */
+  paneScroll?: boolean;
+
+  // -- pinned slots ----------------------------------------------------------
+  /**
+   * The phone header: a sibling ABOVE the shell's columns, spanning it edge to
+   * edge, pinned to the top (sticky with document scroll). Nothing a consumer
+   * writes needs `position: fixed` or a negative margin to be a top bar.
+   *
+   * `header` is the in-column page heading and is unaffected; a shell may have
+   * both. NOT drawn under `drawer="reveal"`: that drawer slides the whole page
+   * 272px sideways, and a bar pinned to the frame would stay behind while the
+   * page it belongs to left it — so `reveal` keeps its in-column `header`.
+   */
+  topBar?: ReactNode;
+  /** `compact` (default): only while the nav is a drawer. */
+  topBarVisibility?: AppShellBarVisibility;
+  /**
+   * The bottom bar: pinned to the bottom of the viewport (or of the frame when
+   * the shell does not own the page), with the bottom safe-area inset applied
+   * as its own padding. The content column reserves its MEASURED height, so the
+   * last item is never hidden behind it.
+   */
+  bottomBar?: ReactNode;
+  /** `compact` (default): only while the nav is a drawer. */
+  bottomBarVisibility?: AppShellBarVisibility;
+  /** The compose/FAB corner — above the bottom bar when there is one. */
+  floatingAction?: ReactNode;
+  /** Which corner. Default `end` (the right in a left-to-right layout). */
+  floatingActionPlacement?: 'start' | 'end';
+
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }
@@ -94,6 +255,12 @@ export interface AppShellHeaderProps {
   onMenuPress?: () => void;
   /** Swaps the hamburger for a close glyph while the drawer is open. */
   menuOpen?: boolean;
+  /**
+   * Whether the hamburger has anything to open. `AppShell` passes its own
+   * answer, taken from the shell's MEASURED width and `navFrom`; standalone the
+   * header falls back to the window being narrower than `lg`.
+   */
+  showMenu?: boolean;
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }

package/src/app-shell/use-shell-width.ts

@@ -0,0 +1,29 @@
+import type { LayoutChangeEvent } from 'react-native';
+import { useWindowDimensions } from 'react-native';
+
+import { useContainerWidth } from '../hooks/use-container-width';
+
+/**
+ * The width `AppShell` lays itself out from: its OWN measured box, falling back
+ * to the window until the first layout arrives.
+ *
+ * The shell is usually the page, so the two agree — but not always. A shell
+ * mounted in a preview pane, in one half of a split view, or inside a desktop
+ * app's own chrome is narrower than the window, and a window-width decision
+ * puts three columns into a 480px box. Measuring the shell is the only reading
+ * that is right in both cases.
+ *
+ * The fallback is the window rather than `0` on purpose: the first paint would
+ * otherwise be a phone layout for every shell, and the correction would be a
+ * visible reflow on every page load. A shell that spans the page therefore
+ * renders correctly on frame one, and only an embedded one pays a single
+ * layout pass.
+ *
+ * (`useContainerWidth` lives in `listing-details/` today. If it moves to
+ * `src/hooks/use-container-width.ts` this import is the only line to change.)
+ */
+export function useShellWidth(): { width: number; onLayout: (event: LayoutChangeEvent) => void } {
+  const { width: windowWidth } = useWindowDimensions();
+  const { width: measured, onLayout } = useContainerWidth();
+  return { width: measured ?? windowWidth, onLayout };
+}

package/src/avatar/Avatar.tsx

@@ -6,6 +6,7 @@ import Svg, { ClipPath, Defs, Image as SvgImage, Path } from 'react-native-svg';
 import { useTheme } from '../theme/use-theme';
 import { useInteractionState } from '../hooks/use-interaction-state';
 import { useImageResolver } from '../image-resolver/context';
+import { isImageUrl } from '../image-resolver/is-image-url';
 import { Z_INDEX } from '../styles/z-index';
 import { useAvatarPlaceholder } from './context';
 import { LiveBadge } from './LiveBadge';
@@ -239,17 +240,16 @@ const AvatarComponent: React.FC<AvatarProps> = ({
   const imageResolver = useImageResolver();
 
   // Resolve source prop: string → uri, object → ImageSourcePropType.
-  // HTTP/data URLs pass through directly. Non-URL strings (e.g. Oxy file
-  // IDs) are resolved via the app-provided ImageResolver if available, with the
-  // requested `variant` forwarded so the resolver (the single URL chokepoint)
-  // can build the right rendition. `variant` defaults to `'thumb'` (see prop
-  // default) so a bare-id avatar never accidentally requests the full-size
-  // original; callers wanting the full image pass an explicit variant.
+  // A URL passes through directly (`isImageUrl`, the package's one answer to
+  // "URL or id"). Non-URL strings (e.g. Oxy file IDs) are resolved via the
+  // app-provided ImageResolver if available, with the requested `variant`
+  // forwarded so the resolver (the single URL chokepoint) can build the right
+  // rendition. `variant` defaults to `'thumb'` (see prop default) so a bare-id
+  // avatar never accidentally requests the full-size original; callers wanting
+  // the full image pass an explicit variant.
   const resolvedUri = useMemo(() => {
     if (typeof source === 'string') {
-      if (source.startsWith('http://') || source.startsWith('https://') || source.startsWith('data:')) {
-        return source;
-      }
+      if (isImageUrl(source)) return source;
       return imageResolver?.(source, variant);
     }
     return uri;

package/src/avatar/initials.ts

@@ -1,6 +1,15 @@
 import type { TextStyle } from 'react-native';
 
-import { ACCENT_TABLE, colorRamp, resolveButtonRamps, type RampTable } from '../button/shared';
+import {
+  ACCENT_TABLE,
+  colorRamp,
+  resolveButtonRamps,
+  type Ramp,
+  type RampStop,
+  type RampTable,
+} from '../button/shared';
+import { contrastRatio } from '../styles/color-contrast';
+import { AA_TEXT } from '../styles/surface-levels';
 import { TYPE_SCALE } from '../typography/scale';
 import { parseRgba } from '../theme/color-utils';
 import { srgbToOklch } from '../theme/color-space';
@@ -16,14 +25,23 @@ import type { AvatarColor, AvatarSizeToken } from './types';
  *   md     32   headline-semibold (16/22)
  *   lg     36   18/24 semibold
  *
- *   tint      disc                 initials
- *   neutral   neutral-300          text-secondary (neutral-500)
+ *   tint      disc                 initials (preferred stop)
+ *   neutral   neutral-300          neutral-500      ← the neutral ramp
  *             (dark: neutral-800)
  *   blue      blue-300             blue-900         ← theme `primary`
  *   lime      lime-200             lime-700         ← theme `success`
  *   pink      pink-200             pink-500         ← theme `negative`
  *
- * The hue tints are not repainted in dark mode.
+ * The hue tints are not repainted in dark mode — the DISC is the same colour in
+ * both, so only the letter has to move, and {@link legibleStop} moves it.
+ *
+ * The preferred stop is a preference, not the answer. A tint's ramp is rebuilt
+ * around a THEME role whose lightness moves with the mode, so a stop pair chosen
+ * in light can collapse in dark: `pink` measured **1.24:1** there
+ * (`#ffb4ab` on `#ecd8d6`) because dark `negative` is a bright red and the 500
+ * stop went pale, `lime` 4.29:1 and `neutral` 3.19:1 — and the name hash sends
+ * a quarter of all fallback avatars to the worst of them. The disc keeps its
+ * hue; the letter walks outward along its own ramp until it clears AA.
  */
 export const AVATAR_SIZES: Record<AvatarSizeToken, number> = {
   xs: 20,
@@ -89,28 +107,56 @@ export interface AvatarTint {
   foreground: string;
 }
 
+const STOP_ORDER: readonly RampStop[] = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+
+/**
+ * The stop nearest `preferred` whose colour clears AA on `background`.
+ *
+ * Nearest, not darkest: the tint has to stay recognisable, so the letter moves
+ * the smallest distance along its OWN ramp that buys legibility. Ties go to the
+ * lighter stop, which is the one that reads as the same hue on a pale disc.
+ *
+ * The fallback is black or white — whichever the disc can carry. It is
+ * unreachable for every built-in preset (an 11-stop ramp always has a legible
+ * member of a mid-tone disc) and exists so the function is total rather than
+ * because a preset needs it.
+ */
+function legibleStop(ramp: Ramp, background: string, preferred: RampStop): string {
+  const home = STOP_ORDER.indexOf(preferred);
+  const order = STOP_ORDER.map((stop, i) => ({ stop, distance: Math.abs(i - home) })).sort(
+    (a, b) => a.distance - b.distance,
+  );
+  for (const { stop } of order) {
+    if (contrastRatio(ramp[stop], background) >= AA_TEXT) return ramp[stop];
+  }
+  const white = 'rgb(255 255 255)';
+  const black = 'rgb(0 0 0)';
+  return contrastRatio(background, black) >= contrastRatio(background, white) ? black : white;
+}
+
 /** Every colour one tint paints. Pure, so it can be walked over presets. */
 export function resolveAvatarTint(theme: Theme, color: AvatarColor): AvatarTint {
   switch (color) {
     case 'blue': {
       const ramp = colorRamp(theme.colors.primary, ACCENT_TABLE);
-      return { background: ramp[300], foreground: ramp[900] };
+      return { background: ramp[300], foreground: legibleStop(ramp, ramp[300], 900) };
     }
     case 'lime': {
       const ramp = absoluteRamp(theme.colors.success, LIME_TABLE);
-      return { background: ramp[200], foreground: ramp[700] };
+      return { background: ramp[200], foreground: legibleStop(ramp, ramp[200], 700) };
     }
     case 'pink': {
       // `negative`, not `tertiary`: a preset's tertiary can be a pale yellow,
       // which leaves no legible initial on its own 200 stop. Rose is pink's
       // nearest theme role. The 500 stop IS the theme colour.
       const ramp = absoluteRamp(theme.colors.negative, PINK_TABLE);
-      return { background: ramp[200], foreground: ramp[500] };
+      return { background: ramp[200], foreground: legibleStop(ramp, ramp[200], 500) };
     }
     case 'neutral':
     default: {
       const { neutral: n } = resolveButtonRamps(theme);
-      return { background: theme.isDark ? n[800] : n[300], foreground: n[500] };
+      const background = theme.isDark ? n[800] : n[300];
+      return { background, foreground: legibleStop(n, background, 500) };
     }
   }
 }

package/src/badge/Badge.tsx

@@ -1,37 +1,43 @@
 import React, { memo, useMemo } from 'react';
 import { View, type ViewStyle, type TextStyle } from 'react-native';
 
+import { bloomShadowStyle } from '../design-tokens/shadows';
 import { useTheme } from '../theme/use-theme';
 import { Text } from '../typography/Typography';
-import type { TypeScaleVariant } from '../typography/scale';
-import { resolveAccentColors } from '../theme/accent-colors';
 import { borderRadius } from '../styles/tokens';
 import { Z_INDEX } from '../styles/z-index';
+import { BADGE_GEOMETRY, resolveBadgePaint } from './shared';
 import type { BadgeProps } from './types';
 
 /**
- * The counter badge and status dot, with colours from Bloom's accent recipe
- * (`resolveAccentColors`).
+ * The counter badge, the status dot and the label pill, with colours from
+ * Bloom's accent recipe (`resolveAccentColors`) and geometry from
+ * `shared.ts`'s rung table — five rungs in two families:
  *
- *            text                            padding-x  height  (py 1)
- *   small    caption-2-semibold, tracking 0  4          17
- *   medium   caption-1-semibold, tracking 0  4          18      ← default size
- *   large    body-semibold,      tracking 0  6          24
+ *                   height  padding-x  icon  text
+ *   small           17      4          10    caption-2-semibold
+ *   medium          18      4          11    caption-1-semibold   ← default
+ *   large           24      6          14    body-semibold
+ *   label-small     20      8          12    caption-1-semibold
+ *   label-medium    24      10         14    body-2-semibold
  *
- * Bloom uses the full pill radius, like `Button`, rather than a 4px corner,
- * and keeps a `minWidth` of the height so a single digit is a circle rather
- * than a pill narrower than it is tall.
+ * Bloom uses the full pill radius, like `Button`, rather than a 4px corner. A
+ * COUNTER rung keeps a `minWidth` of its height, so a single digit is a circle
+ * rather than a pill narrower than it is tall, and never shrinks. A LABEL rung
+ * shrinks and truncates instead — it carries a word, and a word must yield
+ * before the card around it does.
+ *
+ * `icon` is a leading glyph drawn at the rung's size in the LABEL's colour and
+ * hidden from assistive technology: the badge reads as its text, never as
+ * "image, key". An icon tucks the leading padding in by 2, optically.
  *
  * A standalone `dot` is a status dot: a solid centre on a tinted halo
  * (12 / 6 at `medium`). An attached dot stays a plain presence marker — a halo
  * over the child's corner would read as a second ring on the icon.
+ *
+ * `variant="onMedia"` is the over-a-photograph pill: a light fill with
+ * shadow-s, the same in both modes because the photograph is.
  */
-const SIZE_CONFIG = {
-  small: { height: 17, type: 'caption-2-semibold', paddingHorizontal: 4, dotSize: 6, halo: 8, core: 4 },
-  medium: { height: 18, type: 'caption-1-semibold', paddingHorizontal: 4, dotSize: 8, halo: 12, core: 6 },
-  large: { height: 24, type: 'body-semibold', paddingHorizontal: 6, dotSize: 10, halo: 16, core: 8 },
-} as const satisfies Record<string, { height: number; type: TypeScaleVariant; paddingHorizontal: number; dotSize: number; halo: number; core: number }>;
-
 const PLACEMENT_CONFIG = {
   'top-right': { top: -4, right: -4 },
   'top-left': { top: -4, left: -4 },
@@ -44,6 +50,7 @@ const BadgeComponent: React.FC<BadgeProps> = ({
   variant = 'solid',
   color = 'error',
   size = 'medium',
+  icon: Icon,
   dot = false,
   max,
   invisible = false,
@@ -57,11 +64,14 @@ const BadgeComponent: React.FC<BadgeProps> = ({
   // A dot has no label to make legible, so it always paints the tone's FILL. It
   // used to follow the variant, which made `dot variant="outlined"` a fully
   // transparent circle — visually absent, with markup that looks correct.
-  const colors = resolveAccentColors(theme.colors, color, dot ? 'solid' : variant);
+  const paint = useMemo(
+    () => resolveBadgePaint(theme, color, dot ? 'solid' : variant),
+    [theme, color, dot, variant],
+  );
   // The status dot's halo is the same tone's tint — the recipe's `subtle` pair,
   // so it follows the preset and mode exactly as a subtle badge does.
-  const halo = resolveAccentColors(theme.colors, color, 'subtle').background;
-  const sizeConfig = SIZE_CONFIG[size];
+  const halo = useMemo(() => resolveBadgePaint(theme, color, 'subtle').background, [theme, color]);
+  const geometry = BADGE_GEOMETRY[size];
   const attached = Boolean(children);
 
   const displayContent = useMemo(() => {
@@ -76,16 +86,16 @@ const BadgeComponent: React.FC<BadgeProps> = ({
   const badgeStyle = useMemo((): ViewStyle => {
     if (dot && attached) {
       return {
-        width: sizeConfig.dotSize,
-        height: sizeConfig.dotSize,
+        width: geometry.dotSize,
+        height: geometry.dotSize,
         borderRadius: borderRadius.full,
-        backgroundColor: colors.background,
+        backgroundColor: paint.background,
       };
     }
     if (dot) {
       return {
-        width: sizeConfig.halo,
-        height: sizeConfig.halo,
+        width: geometry.halo,
+        height: geometry.halo,
         borderRadius: borderRadius.full,
         backgroundColor: halo,
         alignItems: 'center',
@@ -95,46 +105,79 @@ const BadgeComponent: React.FC<BadgeProps> = ({
     }
 
     const base: ViewStyle = {
-      minWidth: sizeConfig.height,
-      height: sizeConfig.height,
+      height: geometry.height,
       borderRadius: borderRadius.full,
-      paddingHorizontal: sizeConfig.paddingHorizontal,
-      backgroundColor: colors.background,
+      // LONGHANDS, not `paddingHorizontal`: react-native-web maps the shorthand
+      // to `padding-inline`, which its atomic sheet ranks above `padding-left`
+      // whatever the array order — so a caller's `paddingLeft` override would
+      // drop on web and land on native. An icon also needs the two sides to
+      // differ. Overrides must use these same longhands.
+      paddingLeft: Icon ? Math.max(0, geometry.paddingHorizontal - 2) : geometry.paddingHorizontal,
+      paddingRight: geometry.paddingHorizontal,
+      backgroundColor: paint.background,
+      flexDirection: 'row',
       alignItems: 'center',
       justifyContent: 'center',
-      flexShrink: 0,
+      ...(Icon ? { gap: geometry.gap } : null),
+      // A word shrinks and truncates; a digit is a fixed token that keeps its
+      // circle. See `BadgeGeometry.word`.
+      ...(geometry.word
+        ? { alignSelf: 'flex-start', flexShrink: 1, minWidth: 0 }
+        : { minWidth: geometry.height, flexShrink: 0 }),
+      ...(paint.shadow ? bloomShadowStyle(paint.shadow) : null),
     };
 
     if (variant === 'outlined') {
       base.borderWidth = 1;
-      base.borderColor = colors.border;
+      base.borderColor = paint.border;
     }
 
     return base;
-  }, [dot, attached, sizeConfig, colors, halo, variant]);
+  }, [dot, attached, geometry, paint, halo, variant, Icon]);
 
   const badgeTextStyle = useMemo(
     (): TextStyle => ({
       // `tracking-normal` overrides the caption scale's 0.15px.
       letterSpacing: 0,
-      color: colors.foreground,
+      color: paint.foreground,
       textAlign: 'center',
+      ...(geometry.word ? { flexShrink: 1, minWidth: 0 } : null),
     }),
-    [sizeConfig, colors],
+    [geometry, paint],
   );
 
   const core =
     dot && !attached ? (
       <View
         style={{
-          width: sizeConfig.core,
-          height: sizeConfig.core,
+          width: geometry.core,
+          height: geometry.core,
           borderRadius: borderRadius.full,
-          backgroundColor: colors.background,
+          backgroundColor: paint.background,
         }}
       />
     ) : null;
 
+  // The icon is a glyph OF the label, so it is hidden: a badge announces its
+  // text, never "image, key" beside it.
+  const iconNode =
+    Icon && !dot ? (
+      <View
+        aria-hidden
+        importantForAccessibility="no-hide-descendants"
+        testID={testID ? `${testID}-icon` : undefined}
+      >
+        <Icon width={geometry.icon} height={geometry.icon} fill={paint.foreground} />
+      </View>
+    ) : null;
+
+  const label =
+    displayContent != null ? (
+      <Text variant={geometry.type} numberOfLines={1} style={[badgeTextStyle, textStyle]}>
+        {displayContent}
+      </Text>
+    ) : null;
+
   // Standalone badge (no children)
   if (!attached) {
     if (invisible) return null;
@@ -142,11 +185,8 @@ const BadgeComponent: React.FC<BadgeProps> = ({
     return (
       <View style={[badgeStyle, style]} testID={testID}>
         {core}
-        {displayContent != null && (
-          <Text variant={sizeConfig.type} numberOfLines={1} style={[badgeTextStyle, textStyle]}>
-            {displayContent}
-          </Text>
-        )}
+        {iconNode}
+        {label}
       </View>
     );
   }
@@ -167,11 +207,8 @@ const BadgeComponent: React.FC<BadgeProps> = ({
             style,
           ]}
         >
-          {displayContent != null && (
-            <Text variant={sizeConfig.type} numberOfLines={1} style={[badgeTextStyle, textStyle]}>
-              {displayContent}
-            </Text>
-          )}
+          {iconNode}
+          {label}
         </View>
       )}
     </View>

package/src/badge/index.ts

@@ -1,2 +1,4 @@
 export { Badge } from './Badge';
-export type { BadgeProps, BadgeSize, BadgePlacement } from './types';
+export { BADGE_GEOMETRY, resolveBadgePaint } from './shared';
+export type { BadgeGeometry, BadgePaint } from './shared';
+export type { BadgeProps, BadgeSize, BadgeVariant, BadgeIcon, BadgePlacement } from './types';