@krapwoo/ds-viewer 0.4.3 → 0.4.5

package/native/catalog/SectionBlock.tsx

@@ -5,9 +5,11 @@ import { ComparisonGrid } from './ComparisonGrid';
 import { ComparisonGroups } from './ComparisonGroups';
 import { ComparisonList } from './ComparisonList';
 import { ReferenceDetails } from './ReferenceDetails';
+import { SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import { TokenSections } from './TokenLayouts';
 import { choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
-import type { PreviewWidths, SectionDef } from './types';
+import type { PreviewWidths, SectionDef, SpecimenSurfaceKind } from './types';
 
 // Matches a quoted-string-literal union type, e.g. "'primary' | 'secondary' | 'tertiary'" — anything
 // else (string, boolean, IconName, () => void, …) has no fixed enum to sweep and is skipped.
@@ -100,38 +102,44 @@ function frameLabel(width: number): string {
 }
 
 /** A component preview: one frame per width (each at most phone width), or full width for catalog
- *  chrome and token galleries. Every frame is its own live instance with its own state. */
-function Preview({ render, widths }: { render: () => React.ReactNode; widths: PreviewWidths }) {
-  if (widths === 'full') return <View style={styles.previewCard}>{render()}</View>;
+ *  chrome and token galleries. Every frame is its own live instance with its own state. `surface`
+ *  is omitted for token galleries, which keep their current, unstaged presentation. */
+function Preview({ render, widths, surface }: { render: () => React.ReactNode; widths: PreviewWidths; surface?: SpecimenSurfaceKind }) {
+  // Token galleries pass no surface: their card stays white.
+  const kind = surface ?? 'transparent';
+  if (widths === 'full') return <SpecimenSurface surface={kind} style={styles.previewCard}>{render()}</SpecimenSurface>;
   return (
     <View style={styles.previewCard}>
       <View style={styles.frames}>
         {widths.map((width, i) => (
-          <View
+          <SpecimenSurface
             key={`${width}-${i}`}
+            surface={kind}
             // Two live instances of the same component: name each so assistive tech can tell them apart.
             {...(widths.length > 1 ? ({ role: 'group', 'aria-label': frameLabel(width) } as Record<string, unknown>) : null)}
             style={[styles.frame, { width }]}
           >
             {widths.length > 1 && <Text style={styles.frameLabel}>{frameLabel(width)}</Text>}
             {render()}
-          </View>
+          </SpecimenSurface>
         ))}
       </View>
     </View>
   );
 }
 
-function BlockContent<TId extends string>({ block, def }: { block: PresentationBlock; def: SectionDef<TId> }) {
+function BlockContent<TId extends string>({ block, def, surface }: { block: PresentationBlock; def: SectionDef<TId>; surface: SpecimenSurfaceKind }) {
   switch (block.kind) {
     case 'grid':
-      return <ComparisonGrid def={block.comparison} size={block.size} sectionId={def.id} />;
+      return <ComparisonGrid def={block.comparison} size={block.size} sectionId={def.id} surface={surface} />;
     case 'grouped':
-      return <ComparisonGroups groups={block.groups} size={block.size} label={def.id} />;
+      return <ComparisonGroups groups={block.groups} size={block.size} label={def.id} surface={surface} />;
     case 'list':
-      return <ComparisonList items={block.items} size={block.size} label={`${def.id}: ${block.title}`} />;
+      return <ComparisonList items={block.items} size={block.size} label={`${def.id}: ${block.title}`} maxColumns={block.maxColumns} surface={surface} />;
     case 'preview':
-      return def.render ? <Preview render={def.render} widths={block.widths} /> : null;
+      // A token gallery's `preview` block shows full-width raw token data, not a component
+      // specimen — it keeps its current, unstaged presentation.
+      return def.render ? <Preview render={def.render} widths={block.widths} surface={def.tokenGallery ? undefined : surface} /> : null;
     case 'tokenSections':
       return <TokenSections sections={block.sections} columns={block.columns} />;
     default:
@@ -145,7 +153,7 @@ function BlockContent<TId extends string>({ block, def }: { block: PresentationB
 
 /** Width a block's card occupies: lists hug their columns; everything else fills the row. */
 function blockWidth(block: PresentationBlock, available: number): number {
-  return block.kind === 'list' ? listGeometry(block.items.length, available, block.size).containerWidth : available;
+  return block.kind === 'list' ? listGeometry(block.items.length, available, block.size, block.maxColumns).containerWidth : available;
 }
 
 /**
@@ -154,7 +162,7 @@ function blockWidth(block: PresentationBlock, available: number): number {
  * are never recorded while side by side, so the decision never feeds on its own result; a width
  * change returns to stacked and decides again.
  */
-function Blocks<TId extends string>({ blocks, def }: { blocks: PresentationBlock[]; def: SectionDef<TId> }) {
+function Blocks<TId extends string>({ blocks, def, surface }: { blocks: PresentationBlock[]; def: SectionDef<TId>; surface: SpecimenSurfaceKind }) {
   const [available, setAvailable] = useState(0);
   const [heights, setHeights] = useState<number[]>([]);
   const [placement, setPlacement] = useState<'side' | 'stacked'>('stacked');
@@ -187,7 +195,7 @@ function Blocks<TId extends string>({ blocks, def }: { blocks: PresentationBlock
       gap: CATALOG_LAYOUT.blockGap,
       first: { kind: first.kind, width: blockWidth(first, available), height: heights[0] },
       second: second.kind === 'list'
-        ? { kind: 'list', height: heights[1], itemCount: second.items.length, size: second.size }
+        ? { kind: 'list', height: heights[1], itemCount: second.items.length, size: second.size, maxColumns: second.maxColumns }
         : { kind: second.kind, height: heights[1] },
     });
     if (decision === 'side') setPlacement('side');
@@ -203,7 +211,7 @@ function Blocks<TId extends string>({ blocks, def }: { blocks: PresentationBlock
           style={side ? (i === 0 ? { width: blockWidth(block, available), flexShrink: 0 } : styles.blockFill) : undefined}
         >
           {block.title ? <Text style={styles.blockLabel}>{block.title}</Text> : null}
-          <BlockContent block={block} def={def} />
+          <BlockContent block={block} def={def} surface={surface} />
         </View>
       ))}
     </View>
@@ -241,6 +249,7 @@ export function SectionBlock<TId extends string>({
   checkCompleteness(def);
   // Memoized so Blocks' placement effect runs on real changes, not on every render.
   const blocks = useMemo(() => presentationBlocks(def, { defaultPreviewWidths }), [def, defaultPreviewWidths]);
+  const surface = def.specimenSurface ?? DEFAULT_SPECIMEN_SURFACE;
   // react-native-web reads `aria-level`; React Native's prop types do not declare it.
   const headingLevelProps = { 'aria-level': headingLevel } as Record<string, unknown>;
 
@@ -271,7 +280,7 @@ export function SectionBlock<TId extends string>({
         )}
       </View>
 
-      {blocks.length > 0 && <Blocks blocks={blocks} def={def} />}
+      {blocks.length > 0 && <Blocks blocks={blocks} def={def} surface={surface} />}
 
       <ReferenceDetails def={def} />
     </View>

package/native/catalog/SpecimenSurface.tsx

@@ -0,0 +1,84 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { CATALOG_COLOR } from './tokens';
+import { DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE } from './specimenSurfaceStyle';
+import { blendsIntoCell, measurePaintedBoxes } from './specimenFill';
+import type { SpecimenSurfaceKind } from './types';
+
+type Browser = {
+  getComputedStyle?: (element: unknown) => never;
+  Element?: new () => unknown;
+  requestAnimationFrame?: (callback: () => void) => number;
+};
+
+/**
+ * An example's whole cell area — shared by `ComparisonList`, `ComparisonGroups`,
+ * `ComparisonGrid`, and `SectionBlock`'s preview frames, so a page's `specimenSurface` fills every
+ * example cell the same way. With `'auto'` (the default) the cell measures its example after it
+ * draws and turns gray only when the example would vanish against white (a white card, sheet or
+ * neutral banner; see `specimenFill.ts`). Explicit kinds fill the cell without measuring. Adds no
+ * padding or border of its own: pass the cell's own layout in `style`. Measuring needs the
+ * browser's DOM; elsewhere `'auto'` leaves the cell white. Extra props (e.g. `role`) go to the View.
+ */
+export function SpecimenSurface({
+  surface = DEFAULT_SPECIMEN_SURFACE,
+  style,
+  children,
+  ...viewProps
+}: {
+  surface?: SpecimenSurfaceKind;
+  style?: StyleProp<ViewStyle>;
+  children: React.ReactNode;
+  [prop: string]: unknown;
+}) {
+  const ref = useRef<View>(null);
+  const [blends, setBlends] = useState(false);
+
+  const measure = useCallback(() => {
+    if (surface !== 'auto') return;
+    const browser = globalThis as unknown as Browser;
+    const node = ref.current as unknown;
+    if (!browser.getComputedStyle || !browser.Element || !(node instanceof browser.Element)) return;
+    const { boxes, cellArea } = measurePaintedBoxes(node as Parameters<typeof measurePaintedBoxes>[0], (element) => browser.getComputedStyle!(element));
+    setBlends(blendsIntoCell(boxes, cellArea));
+  }, [surface]);
+
+  useEffect(() => {
+    const raf = (globalThis as unknown as Browser).requestAnimationFrame;
+    if (surface !== 'auto' || !raf) return;
+    // Two frames, so the example's own styles and fonts have applied before measuring.
+    let cancelled = false;
+    raf(() => raf(() => {
+      if (!cancelled) measure();
+    }));
+    return () => {
+      cancelled = true;
+    };
+  }, [surface, measure]);
+
+  const fill = surface === 'auto' ? (blends ? FILL.neutral : undefined) : FILL[surface];
+  return (
+    <View ref={ref} onLayout={surface === 'auto' ? measure : undefined} style={[style, fill]} {...viewProps}>
+      {children}
+    </View>
+  );
+}
+
+/** Wraps one example inside its cell: full cell width (so a percentage-width example resolves
+ *  against the cell), centered unless the example fills the cell. */
+export function SpecimenContent({ fill, children }: { fill?: boolean; children: React.ReactNode }) {
+  return <View style={fill ? styles.fill : styles.center}>{children}</View>;
+}
+
+// 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token); there is no dark-surface token.
+const FILL = StyleSheet.create({
+  neutral: { backgroundColor: CATALOG_COLOR.specimenStage },
+  white: { backgroundColor: CATALOG_COLOR.surface },
+  dark: { backgroundColor: CATALOG_COLOR.text },
+  transparent: {},
+});
+
+const styles = StyleSheet.create({
+  center: { ...SPECIMEN_SURFACE_WIDTH_STYLE, alignItems: 'center' },
+  fill: { ...SPECIMEN_SURFACE_WIDTH_STYLE },
+});

package/native/catalog/TokenRow.tsx

@@ -11,7 +11,9 @@ import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
  *
  * Draws a 1px `CATALOG_COLOR.border` bottom divider by default (the same divider PropsTable's rows use) so a stack of TokenRows
  * reads as a list, not a loose pile of paragraphs. Pass `last` on the final row in a stack to drop
- * the divider, matching PropsTable's own `rowLast` convention.
+ * the divider, matching PropsTable's own `rowLast` convention. Balanced `CATALOG_SPACE.md` padding
+ * sits above and below both the content and its use-note, so a stack of rows breathes evenly
+ * instead of only the divider-adjacent gap existing.
  */
 export function TokenRow({
   children,
@@ -45,11 +47,10 @@ export function TokenRow({
 }
 
 const styles = StyleSheet.create({
-  item: { gap: CATALOG_SPACE.xs },
-  itemRight: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.xl },
+  item: { gap: CATALOG_SPACE.xs, paddingVertical: CATALOG_SPACE.md },
+  itemRight: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.xl, paddingVertical: CATALOG_SPACE.md },
   useRight: { flex: 1 },
   itemDivider: {
-    paddingBottom: CATALOG_SPACE.md,
     borderBottomWidth: 1,
     borderBottomColor: CATALOG_COLOR.border,
   },

package/native/catalog/comparison.ts

@@ -115,12 +115,17 @@ export interface ListGeometry {
 /** Balanced wrapping for a one-axis list inside a single bordered card (1px outer border). Each
  *  cell's 1px divider sits inside its own width, so no cell is ever wider than 402px. Uses as few
  *  rows as fit, then spreads items evenly across them so a short last row leaves as little empty
- *  space as possible. `fillers` blank cells complete the last row. */
-export function listGeometry(itemCount: number, availableWidth: number, size: SpecimenSize): ListGeometry {
+ *  space as possible. `fillers` blank cells complete the last row. `columnCap` (from
+ *  `VariantSlot.maxColumns`) only ever lowers the natural, width-based column count — a narrow
+ *  container still drops below it when it has to, so the cap can never widen a row past what the
+ *  available width actually fits. */
+export function listGeometry(itemCount: number, availableWidth: number, size: SpecimenSize, columnCap?: number): ListGeometry {
   if (itemCount <= 0) return { columns: 0, rows: 0, fillers: 0, cellWidth: 0, containerWidth: 0 };
   const inner = Math.max(0, availableWidth - 2);
   const min = COLUMN_MIN_WIDTH[size];
-  const maxColumns = Math.max(1, Math.min(itemCount, Math.floor(inner / min)));
+  const widthLimit = Math.floor(inner / min);
+  const limit = columnCap !== undefined ? Math.min(widthLimit, columnCap) : widthLimit;
+  const maxColumns = Math.max(1, Math.min(itemCount, limit));
   const rows = Math.ceil(itemCount / maxColumns);
   const columns = Math.ceil(itemCount / rows);
   const fitted = Math.floor(inner / columns);
@@ -228,7 +233,7 @@ export interface ListGroup {
 export type PresentationBlock =
   | { kind: 'grid'; title: string; size: SpecimenSize; comparison: ComparisonDef }
   | { kind: 'grouped'; title: string; size: SpecimenSize; groups: ListGroup[] }
-  | { kind: 'list'; title: string; size: SpecimenSize; items: ListItem[] }
+  | { kind: 'list'; title: string; size: SpecimenSize; items: ListItem[]; maxColumns?: 1 | 2 | 3 | 4 | 5 }
   | { kind: 'preview'; title: string; widths: PreviewWidths }
   | { kind: 'tokenSections'; title: string; sections: TokenSection[]; columns: 1 | 2 | 3 }
   | { kind: 'empty'; title: string; message: string };
@@ -308,7 +313,13 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
       blocks.push({ kind: 'grouped', title: 'Variant × configuration', size: def.specimenSize ?? 'regular', groups: grouped.groups });
       states = grouped.leftovers;
     } else if (def.variants) {
-      blocks.push({ kind: 'list', title: 'Variants', size: slotSize(def, def.variants), items: slotItems(def.variants) });
+      blocks.push({
+        kind: 'list',
+        title: 'Variants',
+        size: slotSize(def, def.variants),
+        items: slotItems(def.variants),
+        ...(def.variants.maxColumns !== undefined ? { maxColumns: def.variants.maxColumns } : {}),
+      });
     } else if (def.render) {
       blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
     }
@@ -321,6 +332,7 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
       title: secondary ? 'Other configurations' : 'States / configurations',
       size: slotSize(def, states),
       items: slotItems(states),
+      ...(states.maxColumns !== undefined ? { maxColumns: states.maxColumns } : {}),
     });
   }
 
@@ -336,9 +348,11 @@ export interface PlacementBlock {
   width?: number;
   /** Measured height of the whole block, label included, while stacked. */
   height: number;
-  /** For a list: item count and specimen size, so its side-by-side height can be predicted. */
+  /** For a list: item count, specimen size, and any explicit column cap, so its side-by-side
+   *  height can be predicted from the same geometry the rendered list uses. */
   itemCount?: number;
   size?: SpecimenSize;
+  maxColumns?: 1 | 2 | 3 | 4 | 5;
 }
 
 /** Side by side or stacked, for a page with exactly two blocks. Tries both and keeps the shorter;
@@ -351,8 +365,8 @@ export function choosePlacement({ available, gap, first, second }: { available:
   const room = available - firstWidth - gap;
   const minCell = second.size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : COLUMN_MIN_WIDTH[second.size];
   if (room < minCell + 2) return 'stacked';
-  const stackedRows = listGeometry(second.itemCount, available, second.size).rows;
-  const sideRows = listGeometry(second.itemCount, room, second.size).rows;
+  const stackedRows = listGeometry(second.itemCount, available, second.size, second.maxColumns).rows;
+  const sideRows = listGeometry(second.itemCount, room, second.size, second.maxColumns).rows;
   const rowHeight = second.height / Math.max(1, stackedRows);
   const sideHeight = Math.max(first.height, sideRows * rowHeight);
   const stackedHeight = first.height + gap + second.height;

package/native/catalog/index.ts

@@ -24,6 +24,9 @@ export { ReferenceDetails } from './ReferenceDetails';
 export { PropsTable } from './PropsTable';
 export { VariantGroup } from './VariantGroup';
 export { TokenRow } from './TokenRow';
+export { MotionSpecimen } from './MotionSpecimen';
+export type { MotionSpecimenProps, MotionSpecimenSpringConfig } from './MotionSpecimen';
+export { SpecimenSurface } from './SpecimenSurface';
 export { TokenSections, TokenGrid, TokenTile } from './TokenLayouts';
 export { DividedStack } from './DividedStack';
 export { Swatch } from './Swatch';
@@ -34,7 +37,10 @@ export { buildComponentManifest } from './manifest';
 export type { ComponentManifestEntry, ManifestExample } from './manifest';
 export { defineCatalogPage, buildCatalogSections } from './pageApi';
 export type { CatalogPage, CatalogPageInput, GeneratedComponent, GeneratedPropRecord } from './pageApi';
-export type { PropDef, SectionDef, NavGroup, SpecimenSize, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis, PreviewWidths, TokenSection } from './types';
+export type {
+  PropDef, SectionDef, NavGroup, SpecimenSize, SpecimenSurfaceKind, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis,
+  PreviewWidths, TokenSection, ComposedOfEntry,
+} from './types';
 export { UpdatePanel } from './UpdatePanel';
 export { UPDATE_PAGE_ID } from './catalogNavigation';
 export type { UpdateNotice } from './types';

package/native/catalog/motionValueDomain.ts

@@ -0,0 +1,37 @@
+/**
+ * Pure value-domain model for `MotionSpecimen`'s spring kind, kept free of any `react-native`
+ * import so `node --test` can assert on it directly (see
+ * `native/catalog/__tests__/motionValueDomain.test.ts`).
+ *
+ * A spring's `restDisplacementThreshold`/`restSpeedThreshold` are in the units of the value being
+ * animated — a config built for pixel-space points (e.g. a bottom sheet's snap-point spring) stops
+ * within a fraction of a pixel of its target, which is invisible; the same thresholds applied to a
+ * normalized 0-to-1 progress would end the animation before it ever emits a frame. `MotionSpecimen` must animate the domain the config was
+ * actually tuned for, rather than always normalizing to 0–1, or it misrepresents any spring whose
+ * production value is pixel-space.
+ *
+ * 'distance': the `Animated.Value` IS the pixel distance (0 → `distance`); `translateX` reads it
+ * directly, with no interpolation. 'unit': the value is a normalized 0-to-1 progress; `translateX`
+ * interpolates it to the pixel distance. Timing specimens always use 'distance' because their
+ * easing and duration are independent of the animated value's units.
+ */
+export type MotionValueRange = 'distance' | 'unit';
+
+/** The Replay button's accessible name. A motion page shows many specimens, so each name must say
+ *  which one it replays: the specimen's visible label, else its duration (timing) or "spring". */
+export function motionReplayLabel(specimen: { kind: 'timing' | 'spring'; duration?: number; label?: string }): string {
+  if (specimen.label) return `Replay ${specimen.label}`;
+  return specimen.kind === 'timing' ? `Replay ${specimen.duration}ms timing` : 'Replay spring';
+}
+
+/** The `Animated.Value` target to animate toward — and the value a reduced-motion replay jumps to
+ *  instantly — for a given domain and pixel distance. */
+export function motionValueTarget(valueRange: MotionValueRange, distance: number): number {
+  return valueRange === 'distance' ? distance : 1;
+}
+
+/** Whether `translateX` reads the animated value directly (true, 'distance') or must interpolate
+ *  it from a 0-to-1 progress to the pixel distance (false, 'unit'). */
+export function motionTranslatesDirectly(valueRange: MotionValueRange): boolean {
+  return valueRange === 'distance';
+}

package/native/catalog/pageApi.ts

@@ -1,5 +1,5 @@
 import type React from 'react';
-import type { ComparisonDef, NavGroup, PreviewWidths, PropDef, SectionDef, SpecimenSize, TokenSection, VariantSlot } from './types';
+import type { ComparisonDef, ComposedOfEntry, NavGroup, PreviewWidths, PropDef, SectionDef, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot } from './types';
 
 /** `SectionDef` without the derived fields (`id`/`path`/`props` come from detection and
  *  generated props), plus the three fields design §1 "Page shape" adds. */
@@ -29,8 +29,10 @@ export interface CatalogPageInput<TId extends string = string> {
   fullWidthLabel?: string;
   comparison?: ComparisonDef;
   specimenSize?: SpecimenSize;
+  specimenSurface?: SpecimenSurfaceKind;
   previewWidths?: PreviewWidths;
   hide?: SectionDef['hide'];
+  composedOf?: ComposedOfEntry[];
   /** Export name this page documents; defaults to `id` for component pages. */
   component?: string;
   /** Sidebar group label. */
@@ -87,6 +89,17 @@ function mergePropNotes(component: GeneratedComponent, propNotes: Record<string,
   return [...own, ...inherited];
 }
 
+/** Human-readable problems with a page's `composedOf`, in declaration order: one line per entry
+ *  whose `component` isn't in `knownNames` (every real component name, documented or not, plus
+ *  every page id — the full catalog inventory `buildCatalogSections` already has on hand). Empty
+ *  when every name resolves, including when `composedOf` itself is omitted. */
+export function validateComposedOf(composedOf: ComposedOfEntry[] | undefined, knownNames: ReadonlySet<string>): string[] {
+  if (!composedOf) return [];
+  return composedOf
+    .filter((entry) => !knownNames.has(entry.component))
+    .map((entry) => `composedOf references unknown component "${entry.component}".`);
+}
+
 function orderGroups<TId extends string>(groupIds: Map<string, TId[]>, groupOrder: string[] | undefined): NavGroup<TId>[] {
   const listed = groupOrder ?? [];
   const labels = [...groupIds.keys()];
@@ -112,6 +125,10 @@ export function buildCatalogSections<TId extends string>(
   const documented = new Set(pages.map((page) => page.component ?? page.id));
   const groupIds = new Map<string, TId[]>();
   const addToGroup = (group: string, id: TId) => groupIds.set(group, [...(groupIds.get(group) ?? []), id]);
+  // Every name a page's `composedOf` could legitimately point at: every real component (documented
+  // or not — an undocumented one is still a real part of the design system) plus every page id
+  // (token pages, standalone recipes, …).
+  const knownComposedOfNames = new Set<string>([...componentByName.keys(), ...pages.map((page) => page.id)]);
 
   // Design §4 "duplicate-page-id" rule's viewer-side equivalent — this is the one place in the
   // whole viewer that already resolves every page's id to build sections/groups, so it costs
@@ -122,6 +139,7 @@ export function buildCatalogSections<TId extends string>(
     if ((globalThis as { __DEV__?: boolean }).__DEV__) {
       if (seenIds.has(page.id)) console.warn(`[Catalog] Page id "${page.id}" is used by more than one page; only the last one will show. Give one of them its own "id".`);
       seenIds.add(page.id);
+      for (const issue of validateComposedOf(page.composedOf, knownComposedOfNames)) console.warn(`[Catalog] ${page.id}: ${issue}`);
     }
     const componentName = page.component ?? page.id;
     const component = componentByName.get(componentName);
@@ -148,8 +166,10 @@ export function buildCatalogSections<TId extends string>(
       fullWidthLabel: page.fullWidthLabel,
       comparison: page.comparison,
       specimenSize: page.specimenSize,
+      specimenSurface: page.specimenSurface,
       previewWidths: page.previewWidths,
       hide: component ? page.hide : { ...page.hide, props: true },
+      composedOf: page.composedOf,
     };
   });
 

package/native/catalog/specimenFill.ts

@@ -0,0 +1,102 @@
+/**
+ * Automatic cell fill for `specimenSurface: 'auto'` (the default): decides whether an example
+ * blends into its white comparison cell, so that one cell can turn gray. Kept free of any runtime
+ * import so `node --test` can assert on it directly (see `__tests__/specimenFill.test.ts`).
+ *
+ * The rule looks only at the example's largest painted box (the element with a background that
+ * covers the most area): if that box is near-white (every channel close to 255, so pale tints
+ * don't count) and has no visible border, the example's edges
+ * vanish against the white cell. A shadow alone doesn't count as an edge. Small boxes (under a
+ * tenth of the cell) and text-only examples never trigger it.
+ */
+
+export interface Rgba { r: number; g: number; b: number; a: number }
+
+/** One element inside an example, as measured in the browser. */
+export interface PaintedBox {
+  area: number;
+  background: Rgba | null;
+  /** The top border's colour when its width is above 0, else null. */
+  border: Rgba | null;
+}
+
+/** A fill is near-white when every channel (after compositing over the white cell) is at least
+ *  this. #fafafa and #f8f8f8 qualify; #f4f4f4 already reads as gray, and pale tints such as a
+ *  positive banner's rgb(240, 255, 244) read as colour, even when they're as bright as white. */
+const NEAR_WHITE_CHANNEL = 247;
+/** At or above this, a border draws the edge itself (#e4e4e4 is 1.27:1). */
+const VISIBLE_BORDER_CONTRAST = 1.2;
+/** A box smaller than this share of the cell is a detail, not the example's body. */
+const MIN_AREA_SHARE = 0.1;
+
+/** Parses a computed CSS colour (`rgb(…)`/`rgba(…)`). Fully transparent or unknown values are null. */
+export function parseCssColor(value: string): Rgba | null {
+  const match = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/.exec(value.trim());
+  if (!match) return null;
+  const alphaText = match[4];
+  const a = alphaText === undefined ? 1 : alphaText.endsWith('%') ? Number(alphaText.slice(0, -1)) / 100 : Number(alphaText);
+  if (!(a > 0)) return null;
+  return { r: Number(match[1]), g: Number(match[2]), b: Number(match[3]), a };
+}
+
+function channel(value: number): number {
+  const s = value / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+}
+
+/** True when every channel of `color`, composited over white, is at least `NEAR_WHITE_CHANNEL`. */
+export function isNearWhite(color: Rgba): boolean {
+  const over = (c: number) => color.a * c + (1 - color.a) * 255;
+  return Math.min(over(color.r), over(color.g), over(color.b)) >= NEAR_WHITE_CHANNEL;
+}
+
+/** WCAG contrast ratio against white, after compositing a translucent colour over the white cell. */
+export function contrastWithWhite(color: Rgba): number {
+  const over = (c: number) => color.a * c + (1 - color.a) * 255;
+  const luminance = 0.2126 * channel(over(color.r)) + 0.7152 * channel(over(color.g)) + 0.0722 * channel(over(color.b));
+  return 1.05 / (luminance + 0.05);
+}
+
+/** True when the example's body is near-white with no visible border, so it vanishes on a white cell. */
+export function blendsIntoCell(boxes: readonly PaintedBox[], cellArea: number): boolean {
+  let largest: PaintedBox | undefined;
+  for (const box of boxes) {
+    if (!box.background || box.area < cellArea * MIN_AREA_SHARE) continue;
+    if (!largest || box.area > largest.area) largest = box;
+  }
+  if (!largest?.background) return false;
+  if (!isNearWhite(largest.background)) return false;
+  return !(largest.border && contrastWithWhite(largest.border) >= VISIBLE_BORDER_CONTRAST);
+}
+
+/** Minimal DOM shapes, so this file needs no DOM lib types. */
+interface MeasurableElement {
+  getBoundingClientRect(): { width: number; height: number };
+  querySelectorAll(selector: string): ArrayLike<MeasurableElement>;
+}
+type ComputedStyleReader = (element: MeasurableElement) => {
+  backgroundColor: string;
+  borderTopColor: string;
+  borderTopWidth: string;
+  visibility: string;
+  opacity: string;
+};
+
+/** Measures every element inside `cell` (up to `limit`) in the browser. */
+export function measurePaintedBoxes(cell: MeasurableElement, readStyle: ComputedStyleReader, limit = 300): { boxes: PaintedBox[]; cellArea: number } {
+  const cellRect = cell.getBoundingClientRect();
+  const elements = cell.querySelectorAll('*');
+  const boxes: PaintedBox[] = [];
+  for (let i = 0; i < Math.min(elements.length, limit); i++) {
+    const element = elements[i];
+    const style = readStyle(element);
+    if (style.visibility === 'hidden' || Number(style.opacity) === 0) continue;
+    const rect = element.getBoundingClientRect();
+    boxes.push({
+      area: rect.width * rect.height,
+      background: parseCssColor(style.backgroundColor),
+      border: parseFloat(style.borderTopWidth) > 0 ? parseCssColor(style.borderTopColor) : null,
+    });
+  }
+  return { boxes, cellArea: cellRect.width * cellRect.height };
+}

package/native/catalog/specimenSurfaceStyle.ts

@@ -0,0 +1,21 @@
+import type { SpecimenSurfaceKind } from './types.ts';
+
+/**
+ * The example wrapper's width policy inside a cell, kept free of any `react-native` import so
+ * `node --test` can assert on it directly (see `__tests__/specimenSurfaceStyle.test.ts`).
+ *
+ * The wrapper always stretches to the full cross-axis width of whatever wraps it (a comparison
+ * cell, typically centered) rather than shrink-wrapping to its own content — `alignSelf: 'stretch'`
+ * overrides a centered parent's `alignItems` for this one child. A compact specimen (e.g. Button)
+ * still reads as centered, via `SpecimenSurface`'s own `alignItems`/`justifyContent: 'center'` on
+ * the now-full-width surface. Before this, a percentage-width child (Divider's `width: '100%'`, a
+ * phone mockup's percentage-width content) resolved against the surface's own shrink-wrapped,
+ * intrinsic width inside a centered comparison cell, and rendered at 0px.
+ */
+export const SPECIMEN_SURFACE_WIDTH_STYLE = {
+  alignSelf: 'stretch',
+} as const;
+
+/** Each example's cell turns gray only when its example would vanish against white (see
+ *  `specimenFill.ts`). A page can force a fill with `specimenSurface`. */
+export const DEFAULT_SPECIMEN_SURFACE: SpecimenSurfaceKind = 'auto';

package/native/catalog/tokens.ts

@@ -119,6 +119,8 @@ export const CATALOG_COLOR = {
   surfaceMuted: '#fafafa',
   /** Hover and pressed feedback on nav rows and buttons. */
   surfacePressed: '#f1f3f8',
+  /** An example's cell when the example itself is white (`specimenSurface`), darker than surfaceMuted so a white card's edges show. */
+  specimenStage: '#f2f2f2',
   pageBackground: '#f6f6f4',
   chip: '#eeeeee',
   /** Active nav label, prop types, scale bars. */

package/native/catalog/types.ts

@@ -48,6 +48,12 @@ export interface VariantSlot {
    *  content width — for wide block-level components (Banner, Card, Toast, InputField) rather than
    *  small instances meant to sit centered (Button, Badge, Pill). @default false */
   itemsFill?: boolean;
+  /** Caps how many columns this slot's `ComparisonList` ever wraps into — e.g. a size scale that
+   *  must read as one row of exactly 3, never more, regardless of how much laptop width is free.
+   *  `listGeometry` still drops to fewer columns than this when the available width requires it;
+   *  it only ever lowers the natural, width-based column count, never raises it. Omit to let the
+   *  slot's specimen size and available width decide alone (today's behavior, unchanged). */
+  maxColumns?: 1 | 2 | 3 | 4 | 5;
   items: VariantExample[];
 }
 
@@ -59,6 +65,26 @@ export type SpecimenSize = 'compact' | 'regular' | 'wide';
  *  content that is not a phone component (catalog chrome, token galleries). */
 export type PreviewWidths = readonly number[] | 'full';
 
+/** Fill of each example's cell. `'auto'` (default): a cell turns gray (#f2f2f2) only when its own
+ *  example would vanish against white — a near-white body with no visible border, like a white
+ *  card, sheet or neutral banner — so neighbouring examples keep a white cell. `'neutral'` makes
+ *  every example cell gray, `'white'` and `'transparent'` keep them white, `'dark'` checks light
+ *  components on a dark fill. Never applied to token galleries or sections. */
+export type SpecimenSurfaceKind = 'auto' | 'neutral' | 'white' | 'dark' | 'transparent';
+
+/** One real component this page's component is built from or composed with — rendered as a
+ *  "Composition" subsection in Quick reference. `relationship` is `'built-in'` for a component
+ *  always present (e.g. Toast is built from a Banner internally), `'slot'` for an optional
+ *  caller-supplied child (e.g. a `leadingIcon` prop), or `'related'` for a component commonly used
+ *  alongside this one without either containing the other. In development, `buildCatalogSections`
+ *  warns in the browser console when `component` isn't a known component or page id. `doctor`
+ *  doesn't check it, and it never fails a build. */
+export interface ComposedOfEntry {
+  component: string;
+  role: string;
+  relationship: 'built-in' | 'slot' | 'related';
+}
+
 /** One row or column heading in a grid. */
 export interface ComparisonAxisItem {
   key: string;
@@ -189,6 +215,10 @@ export interface SectionDef<TId extends string = string> {
   /** Width class for this page's specimens. Without it, full-width (`itemsFill`) slots are 'wide'
    *  and everything else is 'regular'. */
   specimenSize?: SpecimenSize;
+  /** Background stage behind every live component specimen on this page (list/grouped/grid cells,
+   *  and a `render()` preview that isn't a token gallery). Defaults to `'auto'`. See
+   *  `SpecimenSurfaceKind`. */
+  specimenSurface?: SpecimenSurfaceKind;
   /** Widths for this page's `render()` preview, e.g. `[402, 320]` to add a small-phone example.
    *  Defaults to the catalog's default (CatalogShell `defaultPreviewWidths`), else `[402]`. */
   previewWidths?: PreviewWidths;
@@ -203,6 +233,10 @@ export interface SectionDef<TId extends string = string> {
     props?: boolean;
     accessibility?: boolean;
   };
+  /** What this component is built from or composed with — shown as a "Composition" subsection in
+   *  Quick reference. See `ComposedOfEntry`. Omit when the component has no meaningful composition
+   *  to disclose (most leaf components). */
+  composedOf?: ComposedOfEntry[];
 }
 
 /** A labeled group of section ids in the sidebar (e.g. "Components" vs "Tokens"). */