@krapwoo/ds-viewer 0.4.3 → 0.4.4

package/README.md

@@ -96,6 +96,12 @@ npm run check:catalog    # the same headless check CI runs — every page, zero
 documenting the viewer framework's own pieces (`CatalogShell`, `SectionBlock`, `ComparisonGrid`,
 …), shown under a "Viewer" group alongside the starter kit's own pages.
 
+## Contributing
+
+Found a bug or an improvement while using ds-viewer in your app? Open an issue or a pull request:
+[CONTRIBUTING.md](CONTRIBUTING.md) explains how to try a change in your own app before opening
+one, and what every pull request needs.
+
 ## Picking the right component
 
 Several components look alike but solve different problems (InputField vs. SearchField vs.
@@ -184,8 +190,28 @@ actually apply:
   within what fits a 1280px laptop: 5 compact, 3 regular, or 2 wide columns. `states` items whose
   key matches a row or column key are not repeated below the grid.
 - `specimenSize: 'compact' | 'regular' | 'wide'` — the page's specimen width class.
+- `specimenSurface: 'neutral' | 'white' | 'dark' | 'transparent'` — the catalog-owned background
+  behind every live specimen on this page (list/grouped/grid cells, and a non-token `render()`
+  preview). Defaults to `'neutral'` (a light gray stage, visibly distinct from the surrounding
+  white card) — reach for `'dark'` to check a low-contrast component against a dark background, or
+  `'transparent'` when the surface itself would be misleading (e.g. a component whose own
+  elevation/shadow needs to read against the page, not a chip). Token galleries and sections always
+  keep their current, unstaged presentation regardless of this setting.
+- `variants`/`states`' own `maxColumns: 1 | 2 | 3 | 4 | 5` — caps how many columns that slot's list
+  ever wraps into (e.g. a 3-item size scale that should always read as one row of exactly 3, never
+  more just because a laptop is wide). A narrow window still drops below the cap when it has to —
+  `maxColumns` only ever lowers the natural, width-based column count, never raises it.
 - `group` on a `states` item — the `variants` key it belongs to (a size that only exists for one
   variant). Grouped states render one row per variant; ungrouped ones go to "Other configurations".
+- `composedOf: [{ component, role, relationship }]` — what this component is built from or
+  composed with, shown as a "Composition" subsection in Quick reference. `relationship` is
+  `'built-in'` for a component always present inside this one (e.g. Toast is built from a Banner),
+  `'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. `component` should be
+  a real component or page id: while you browse the catalog in development, an unknown name logs a
+  `[Catalog]` warning in the browser console. `doctor` doesn't check it, and it never fails a
+  build — e.g.
+  `composedOf: [{ component: 'Icon', role: 'Leading glyph', relationship: 'slot' }]`.
 - `previewWidths: [402, 320]` — extra preview widths for a `render()` page (each capped at 402).
   `CatalogShell`'s `defaultPreviewWidths="full"` keeps a catalog's previews full width.
 - `variants: { desc?, align?, itemsFill?, items: [{ key, name, node }] }` — one item per prop enum
@@ -208,9 +234,18 @@ path. For anything beyond a single list of tokens, use the token-page layouts be
 
 ### Organising the catalog
 
-- **Two sidebar groups: `Tokens`, then `Components`** (`groupOrder: ['Tokens', 'Components']`).
-  Pages sort A–Z inside each group. Category groups ("Actions", "Status") make readers guess
-  where a component lives; search and A–Z already find it.
+- **`group`/`groupOrder` accept any semantic category you want** — not just `Tokens` and
+  `Components`. A page's `group` is a plain string shown as its sidebar section label;
+  `groupOrder` (e.g. `['Tokens', 'Components', 'Patterns', 'Recipes', 'Experiences']`) only
+  controls which order those sections appear in, top to bottom — any group not listed sorts
+  alphabetically after the ones that are. This starter kit's own two groups (`Tokens`, then
+  `Components`) are one valid shape, not the only one: a larger catalog might add `Patterns`
+  (reusable combinations like a settings row), `Recipes` (worked end-to-end screens), or
+  `Experiences` (full flows) alongside them. Pages sort A–Z inside each group regardless of how
+  many groups you have. Avoid splitting `Components` into finer categories such as "Actions" or
+  "Status" purely to browse by — that makes readers guess where a component lives; search and A–Z
+  already find it. A distinct semantic group (Tokens vs. Components vs. Patterns) is a different
+  decision from that, since it changes what the reader expects to find there.
 - **Wide components at 3 columns.** Give block-level components (Banner, Card, Toast,
   InputField) `specimenSize: 'regular'`, so Variants and States sit 3 across on a laptop
   (about 316px each). `'wide'` (2 columns, phone width) is only for pages where the full phone
@@ -242,6 +277,7 @@ shape:
 | Narrow sample with a long note (icon size, spacing) | `TokenRow` with `notePlacement="right"`: one line per token | IconSizes |
 | Several kinds of token on one page | `tokenSections`: one titled card per kind | Colors (semantic vs palette) |
 | A scale with families (type) | `tokenSections` with `tokenColumns: 2` or `3`, one section per family | Typography (label, body, emphasis…) |
+| A duration/easing or spring value | `MotionSpecimen` next to the token's value | Motion (duration, easing, spring) |
 
 - **`tokenSections: [{ title, desc?, wide?, render }]`** replaces `render`. Each section is its
   own titled card. Keep different kinds of token in different sections, never mixed: semantic roles
@@ -256,6 +292,29 @@ shape:
   value already say it. If there's nothing grounded to say, leave the note out.
 - **Label each sample with its name and real value** (`bodyMd · 16/22 · 400`, `medium · 12px`).
   Use realistic sample text from the product, short enough to fit its column at the largest size.
+- **`MotionSpecimen`** demonstrates a duration/easing or spring token as a real, bounded
+  start-to-end slide — a dot travels a fixed track once when it mounts, with a named Replay button
+  to play it again. Give it `kind: 'timing'` with `duration` (and optionally a real `Easing`
+  function, e.g. `Easing.bezier(...DS_MOTION_EASING.standard)`) for a duration/easing token, or
+  `kind: 'spring'` with a `spring` config shaped for `Animated.spring` (e.g. `DS_MOTION_SPRING`) for
+  a spring token. It respects the platform's reduce-motion preference automatically — with it on,
+  every play (including the initial one) shows the end state immediately instead of animating, so
+  it never needs its own per-page reduce-motion handling:
+  ```tsx
+  <MotionSpecimen kind="timing" duration={DS_MOTION_DURATION.base} easing={Easing.bezier(...DS_MOTION_EASING.standard)} />
+  <MotionSpecimen kind="spring" spring={DS_MOTION_SPRING} />
+  ```
+  A spring's `valueRange` says which domain its `spring` config's rest thresholds are scaled for,
+  so the specimen animates the same domain the real config does rather than always normalizing to
+  0–1. `'distance'` (default) is for a config tuned for pixel-space points, e.g. a `BottomSheet`'s
+  snap-point spring — the `Animated.Value` animates directly from `0` to the track's pixel
+  distance. `'unit'` is for a config whose production value is a normalized 0-to-1 progress or
+  blend factor — the `Animated.Value` animates `0` to `1` and is interpolated to the pixel
+  distance; `'distance'`'s pixel-scale thresholds would otherwise end a unit-valued spring before
+  it ever moves:
+  ```tsx
+  <MotionSpecimen kind="spring" spring={UNIT_SPRING_CONFIG} valueRange="unit" />
+  ```
 
 ## Keeping the catalog current
 

package/dist/cli/explain.js

@@ -11,10 +11,8 @@ function placeholderItem(item) {
 /** A throwaway `SectionDef` built from a `StaticPage` (Task 3) — every specimen's `node` is `null`
  *  (design §4: specimen nodes are never evaluated), since none of the layout functions below ever
  *  look at it; only the counts/keys/sizes they do look at are carried over. Every field Task 3
- *  reads is carried through here, including `previewWidths`/`fullWidthLabel`/`hide`/`itemsFill` —
- *  an earlier draft dropped these four, so `explain` reported different geometry than the real
- *  viewer for any page that set one of them (25 kit pages set `itemsFill`; every `kit-host`
- *  Viewer page sets `hide`). */
+ *  reads is carried through here, including `previewWidths`/`fullWidthLabel`/`hide`/`itemsFill`/
+ *  `maxColumns` — dropping any of them makes `explain` report different geometry than the viewer. */
 function toSectionDef(page) {
     const comparison = page.comparison && {
         rowLabel: page.comparison.rowLabel ?? '',
@@ -32,8 +30,8 @@ function toSectionDef(page) {
         fullWidthLabel: page.fullWidthLabel,
         specimenSize: page.specimenSize,
         previewWidths: page.previewWidths,
-        variants: page.variantsItems ? { itemsFill: page.variantsItemsFill, items: page.variantsItems.map(placeholderItem) } : undefined,
-        states: page.statesItems ? { itemsFill: page.statesItemsFill, items: page.statesItems.map(placeholderItem) } : undefined,
+        variants: page.variantsItems ? { itemsFill: page.variantsItemsFill, maxColumns: page.variantsMaxColumns, items: page.variantsItems.map(placeholderItem) } : undefined,
+        states: page.statesItems ? { itemsFill: page.statesItemsFill, maxColumns: page.statesMaxColumns, items: page.statesItems.map(placeholderItem) } : undefined,
         comparison,
         render: page.hasRender ? () => null : undefined,
         tokenSections: page.tokenSectionTitles?.map((title, i) => ({ title, wide: page.tokenSectionWide?.[i] || undefined, render: () => null })),
@@ -53,7 +51,7 @@ function explainBlock(block) {
         };
     }
     if (block.kind === 'list') {
-        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, block.size);
+        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, block.size, block.maxColumns);
         return {
             kind: 'list', title: block.title,
             reason: `${block.items.length} items (${block.size}) → ${geometry.columns} columns × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
@@ -89,7 +87,14 @@ function explainBlock(block) {
  *  computed uniformly here for either role, since setting it on `second` is simply unused, not wrong. */
 function toPlacementBlock(block, height, available) {
     if (block.kind === 'list') {
-        return { kind: 'list', height, itemCount: block.items.length, size: block.size, width: listGeometry(block.items.length, available, block.size).containerWidth };
+        return {
+            kind: 'list',
+            height,
+            itemCount: block.items.length,
+            size: block.size,
+            maxColumns: block.maxColumns,
+            width: listGeometry(block.items.length, available, block.size, block.maxColumns).containerWidth,
+        };
     }
     return { kind: block.kind, height };
 }

package/dist/cli/staticPage.js

@@ -146,6 +146,7 @@ function readStaticPage(file) {
     else {
         page.variantsItems = variants.items;
         page.variantsItemsFill = variants.itemsFill;
+        page.variantsMaxColumns = variants.maxColumns;
     }
     const states = readSlotItems(findProp(pageObject, 'states'), consts);
     if (!states.checkable)
@@ -153,6 +154,7 @@ function readStaticPage(file) {
     else {
         page.statesItems = states.items;
         page.statesItemsFill = states.itemsFill;
+        page.statesMaxColumns = states.maxColumns;
     }
     return page;
 }
@@ -357,11 +359,12 @@ function readLiteralProps(node, consts) {
     }
     return result;
 }
-/** A `variants`/`states` field: `{ itemsFill?, items: [...] }`, `items` read by `readListItems`.
- *  Distinguishes "field absent" (always checkable, everything undefined) from "field present but
- *  not literal" (not checkable). `itemsFill` is read only if present and literal — like
- *  `previewWidths`/`fullWidthLabel`, it isn't in design §4's literal-checkable list, so a
- *  non-literal `itemsFill` is simply left unset, never a reason to reject the whole slot. */
+/** A `variants`/`states` field: `{ itemsFill?, maxColumns?, items: [...] }`, `items` read by
+ *  `readListItems`. Distinguishes "field absent" (always checkable, everything undefined) from
+ *  "field present but not literal" (not checkable). `itemsFill` is read only if present and
+ *  literal — like `previewWidths`/`fullWidthLabel`, it isn't in the original literal-checkable
+ *  list, so a non-literal `itemsFill` is simply left unset. `maxColumns` does affect the geometry
+ *  `explain` reports, so it must be a literal integer from 1–5 or the page is not checkable. */
 function readSlotItems(prop, consts) {
     if (!prop)
         return { checkable: true };
@@ -374,5 +377,16 @@ function readSlotItems(prop, consts) {
         return { checkable: false };
     const itemsFillProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'itemsFill') : undefined;
     const itemsFill = itemsFillProp ? resolve(itemsFillProp.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword : undefined;
-    return { items, itemsFill, checkable: true };
+    const maxColumnsProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'maxColumns') : undefined;
+    let maxColumns;
+    if (maxColumnsProp) {
+        const value = resolve(maxColumnsProp.initializer, consts, new Set());
+        if (!ts.isNumericLiteral(value))
+            return { checkable: false };
+        const parsed = Number(value.text);
+        if (!Number.isInteger(parsed) || parsed < 1 || parsed > 5)
+            return { checkable: false };
+        maxColumns = parsed;
+    }
+    return { items, itemsFill, maxColumns, checkable: true };
 }

package/dist/native/catalog/comparison.js

@@ -75,13 +75,18 @@ export function gridWidthBounds(columnCount, size) {
 /** 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, availableWidth, size) {
+ *  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, availableWidth, size, columnCap) {
     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);
@@ -241,7 +246,13 @@ export function presentationBlocks(def, options = {}) {
             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) });
@@ -254,6 +265,7 @@ export function presentationBlocks(def, options = {}) {
             title: secondary ? 'Other configurations' : 'States / configurations',
             size: slotSize(def, states),
             items: slotItems(states),
+            ...(states.maxColumns !== undefined ? { maxColumns: states.maxColumns } : {}),
         });
     }
     if (blocks.length === 0 && !hide.variants && !hide.states) {
@@ -274,8 +286,8 @@ export function choosePlacement({ available, gap, first, second }) {
     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/ComparisonGrid.tsx

@@ -2,14 +2,26 @@ import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, axisItems, cellKey, gridWidthBounds, indexCells, validateComparison } from './comparison';
-import type { ComparisonDef, SpecimenSize } from './types';
+import { SpecimenSurface } from './SpecimenSurface';
+import type { ComparisonDef, SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
  * A grid of two props that combine freely, rendered as an accessible table inside one card.
  * Columns grow with the window up to 402px and never shrink below the specimen size's minimum;
- * a grid wider than its container scrolls horizontally inside the card, never the page.
+ * a grid wider than its container scrolls horizontally inside the card, never the page. `surface`
+ * is the page's `specimenSurface` behind each cell's example.
  */
-export function ComparisonGrid({ def, size, sectionId }: { def: ComparisonDef; size: SpecimenSize; sectionId: string }) {
+export function ComparisonGrid({
+  def,
+  size,
+  sectionId,
+  surface = 'neutral',
+}: {
+  def: ComparisonDef;
+  size: SpecimenSize;
+  sectionId: string;
+  surface?: SpecimenSurfaceKind;
+}) {
   if (__DEV__) {
     for (const issue of validateComparison({ ...def, size })) console.warn(`[Catalog] ${sectionId}: ${issue}`);
   }
@@ -53,7 +65,9 @@ export function ComparisonGrid({ def, size, sectionId }: { def: ComparisonDef; s
               return (
                 <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
                   {cell?.node !== undefined ? (
-                    <View style={cell.fill ? styles.fill : styles.center}>{cell.node}</View>
+                    <SpecimenSurface surface={surface} style={cell.fill && styles.fill}>
+                      {cell.node}
+                    </SpecimenSurface>
                   ) : (
                     <Text style={styles.unavailable}>
                       {cell?.unavailableReason ? `Not supported — ${cell.unavailableReason}` : 'Missing example'}
@@ -88,7 +102,6 @@ const styles = StyleSheet.create({
   headerCell: { backgroundColor: CATALOG_COLOR.surfaceMuted, justifyContent: 'center' },
   bodyRow: { minHeight: MATRIX_LAYOUT.rowMinHeight },
   specimenCell: { alignItems: 'center', justifyContent: 'center' },
-  center: { alignItems: 'center' },
   fill: { alignSelf: 'stretch' },
   headerText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
   rowHeaderText: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },

package/native/catalog/ComparisonGroups.tsx

@@ -2,15 +2,27 @@ import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, type ListGroup } from './comparison';
-import type { SpecimenSize } from './types';
+import { SpecimenSurface } from './SpecimenSurface';
+import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
  * Grouped rows: one row per variant, headed by the variant's name, holding that variant's own
  * configurations. Each cell keeps its own caption because the rows do not share column meanings
  * (a circle's size is not a bar's thickness). Each row is its own labeled list. Shorter rows end
- * in blank cells; a card wider than its container scrolls horizontally inside itself.
+ * in blank cells; a card wider than its container scrolls horizontally inside itself. `surface` is
+ * the page's `specimenSurface` behind each item.
  */
-export function ComparisonGroups({ groups, size, label }: { groups: ListGroup[]; size: SpecimenSize; label: string }) {
+export function ComparisonGroups({
+  groups,
+  size,
+  label,
+  surface = 'neutral',
+}: {
+  groups: ListGroup[];
+  size: SpecimenSize;
+  label: string;
+  surface?: SpecimenSurfaceKind;
+}) {
   const columns = Math.max(1, ...groups.map((g) => g.items.length));
   const min = COLUMN_MIN_WIDTH[size];
   const minWidth = MATRIX_LAYOUT.rowHeaderWidth + columns * min + 2;
@@ -35,7 +47,9 @@ export function ComparisonGroups({ groups, size, label }: { groups: ListGroup[];
                       <Text style={styles.captionText}>{item.label}</Text>
                     </View>
                     <View style={styles.specimen}>
-                      <View style={item.fill ? styles.fill : styles.center}>{item.node as React.ReactNode}</View>
+                      <SpecimenSurface surface={surface} style={item.fill && styles.fill}>
+                        {item.node as React.ReactNode}
+                      </SpecimenSurface>
                     </View>
                   </View>
                 );
@@ -88,6 +102,5 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
-  center: { alignItems: 'center' },
   fill: { alignSelf: 'stretch' },
 });

package/native/catalog/ComparisonList.tsx

@@ -2,16 +2,31 @@ import React, { useState } from 'react';
 import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { MATRIX_LAYOUT, listGeometry, type ListItem } from './comparison';
-import type { SpecimenSize } from './types';
+import { SpecimenSurface } from './SpecimenSurface';
+import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
  * One-axis examples inside ONE shared card. Cells wrap into balanced rows (listGeometry); each cell
  * has its own caption strip so labels stay attached when rows wrap. Blank cells complete an uneven
- * last row. Wide specimens use fixed 402px cells and the card hugs its columns.
+ * last row. Wide specimens use fixed 402px cells and the card hugs its columns. `maxColumns` caps
+ * how many columns a row ever wraps into (from `VariantSlot.maxColumns`); `surface` is the page's
+ * `specimenSurface` behind each item.
  */
-export function ComparisonList({ items, size, label }: { items: ListItem[]; size: SpecimenSize; label: string }) {
+export function ComparisonList({
+  items,
+  size,
+  label,
+  maxColumns,
+  surface = 'neutral',
+}: {
+  items: ListItem[];
+  size: SpecimenSize;
+  label: string;
+  maxColumns?: 1 | 2 | 3 | 4 | 5;
+  surface?: SpecimenSurfaceKind;
+}) {
   const [available, setAvailable] = useState<number>(MATRIX_LAYOUT.laptopContentWidth);
-  const geometry = listGeometry(items.length, available, size);
+  const geometry = listGeometry(items.length, available, size, maxColumns);
   const onLayout = (event: LayoutChangeEvent) => {
     const width = Math.round(event.nativeEvent.layout.width);
     if (width > 0 && width !== available) setAvailable(width);
@@ -46,7 +61,9 @@ export function ComparisonList({ items, size, label }: { items: ListItem[]; size
                     <Text style={styles.captionText}>{item.label}</Text>
                   </View>
                   <View style={styles.specimen}>
-                    <View style={item.fill ? styles.fill : styles.center}>{item.node as React.ReactNode}</View>
+                    <SpecimenSurface surface={surface} style={item.fill && styles.fill}>
+                      {item.node as React.ReactNode}
+                    </SpecimenSurface>
                   </View>
                 </View>
               );
@@ -84,6 +101,5 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
-  center: { alignItems: 'center' },
   fill: { alignSelf: 'stretch' },
 });

package/native/catalog/MotionSpecimen.tsx

@@ -0,0 +1,152 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { Animated, AccessibilityInfo, Pressable, StyleSheet, Text, View } from 'react-native';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { motionReplayLabel, motionTranslatesDirectly, motionValueTarget, type MotionValueRange } from './motionValueDomain';
+
+/** `Animated.spring`'s physics fields — the same shape as a design system's own spring-config
+ *  token (e.g. `DS_MOTION_SPRING`), kept local here rather than imported from any app's tokens so
+ *  this stays an app-agnostic catalog piece. */
+export interface MotionSpecimenSpringConfig {
+  stiffness?: number;
+  damping?: number;
+  mass?: number;
+  overshootClamping?: boolean;
+  restDisplacementThreshold?: number;
+  restSpeedThreshold?: number;
+}
+
+export type MotionSpecimenProps =
+  | {
+      kind: 'timing';
+      /** Duration in ms, e.g. a page's own `DS_MOTION_DURATION.base`. */
+      duration: number;
+      /** A real `Easing` function, e.g. `Easing.bezier(...DS_MOTION_EASING.standard)`. Defaults to
+       *  `Animated.timing`'s own ease-in-out when omitted; pass `Easing.linear` for linear. */
+      easing?: (value: number) => number;
+      /** Track length in px the dot travels, start to end. @default 160 */
+      distance?: number;
+      label?: string;
+    }
+  | {
+      kind: 'spring';
+      spring: MotionSpecimenSpringConfig;
+      /** Which domain `spring`'s rest thresholds are scaled for (see `motionValueDomain.ts`):
+       *  `'distance'` (default) for a config tuned for pixel-space points, e.g. a `BottomSheet`'s
+       *  snap-point spring; `'unit'` for a config tuned for a normalized 0-to-1 progress/blend
+       *  value — `'distance'`'s pixel-scale thresholds would otherwise end a unit-valued spring
+       *  before it ever moves. Does not change the track's own pixel length (`distance`), only
+       *  which domain the `Animated.Value` itself animates in. */
+      valueRange?: MotionValueRange;
+      distance?: number;
+      label?: string;
+    };
+
+const DOT_SIZE = 20;
+const DEFAULT_DISTANCE = 160;
+
+/**
+ * A reusable, bounded start-to-end motion demo for a duration/easing or spring token: a dot slides
+ * once across a fixed track when the specimen mounts, and a "Replay" button plays it again on
+ * demand. Respects the platform's reduce-motion preference — when enabled, every play (including
+ * the initial one) jumps straight to the end state instead of animating, exactly as the real
+ * product components built on these tokens should. Uses only `Animated`/`AccessibilityInfo` from
+ * `react-native`, already a peer dependency — no new runtime dependency.
+ */
+export function MotionSpecimen(props: MotionSpecimenProps) {
+  const { label, distance = DEFAULT_DISTANCE } = props;
+  const valueRange: MotionValueRange = props.kind === 'spring' ? props.valueRange ?? 'distance' : 'distance';
+  const target = motionValueTarget(valueRange, distance);
+  const progress = useRef(new Animated.Value(0)).current;
+  const activeAnim = useRef<Animated.CompositeAnimation | null>(null);
+  const [reduceMotion, setReduceMotion] = useState(false);
+
+  const play = useCallback(
+    (instant: boolean) => {
+      activeAnim.current?.stop();
+      progress.setValue(0);
+      if (instant) {
+        progress.setValue(target);
+        return;
+      }
+      const anim =
+        props.kind === 'timing'
+          ? Animated.timing(progress, { toValue: target, duration: props.duration, easing: props.easing, useNativeDriver: true })
+          : Animated.spring(progress, { toValue: target, useNativeDriver: true, ...props.spring });
+      activeAnim.current = anim;
+      anim.start();
+    },
+    // `props` covers every field `play` reads (duration/easing/spring differ per kind); `target`
+    // is derived from `props` (distance, kind, valueRange), not independent state.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [progress, props, target],
+  );
+
+  useEffect(() => {
+    let mounted = true;
+    AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {
+      if (!mounted) return;
+      setReduceMotion(enabled);
+      play(enabled);
+    });
+    const subscription = AccessibilityInfo.addEventListener('reduceMotionChanged', (enabled: boolean) => setReduceMotion(enabled));
+    return () => {
+      mounted = false;
+      subscription.remove();
+      activeAnim.current?.stop();
+    };
+    // Plays exactly once on mount; `play` only needs to be re-created, never re-run, when props change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const translateX = motionTranslatesDirectly(valueRange)
+    ? progress
+    : progress.interpolate({ inputRange: [0, target], outputRange: [0, distance] });
+
+  return (
+    <View style={styles.wrap}>
+      <View style={[styles.track, { width: distance + DOT_SIZE }]}>
+        <Animated.View style={[styles.dot, { transform: [{ translateX }] }]} />
+      </View>
+      <View style={styles.footer}>
+        {label ? <Text style={styles.label}>{label}</Text> : <View style={styles.labelSpacer} />}
+        <Pressable
+          onPress={() => play(reduceMotion)}
+          accessibilityRole="button"
+          accessibilityLabel={motionReplayLabel({ kind: props.kind, duration: props.kind === 'timing' ? props.duration : undefined, label })}
+          style={({ pressed }) => [styles.replayButton, pressed && styles.replayButtonPressed]}
+        >
+          <Text style={styles.replayText}>Replay</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: { gap: CATALOG_SPACE.sm, alignItems: 'flex-start' },
+  track: {
+    height: DOT_SIZE,
+    borderRadius: DOT_SIZE / 2,
+    backgroundColor: CATALOG_COLOR.border,
+    justifyContent: 'center',
+  },
+  dot: {
+    width: DOT_SIZE,
+    height: DOT_SIZE,
+    borderRadius: DOT_SIZE / 2,
+    backgroundColor: CATALOG_COLOR.accent,
+  },
+  footer: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md },
+  label: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  labelSpacer: { flex: 1 },
+  replayButton: {
+    paddingHorizontal: CATALOG_SPACE.md,
+    paddingVertical: CATALOG_SPACE.xs,
+    borderRadius: CATALOG_RADIUS.control,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.borderStrong,
+    backgroundColor: CATALOG_COLOR.surface,
+  },
+  replayButtonPressed: { backgroundColor: CATALOG_COLOR.surfacePressed },
+  replayText: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.text },
+});

package/native/catalog/ReferenceDetails.tsx

@@ -67,6 +67,14 @@ export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<
             <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
             {def.path && <Fact label="Source" value={def.path} mono />}
             {!hide.accessibility && <Fact label="Accessibility" value={def.a11y ?? 'No accessibility notes documented.'} />}
+            {def.composedOf && def.composedOf.length > 0 && (
+              <>
+                <Text style={styles.subheading}>Composition</Text>
+                {def.composedOf.map((entry, i) => (
+                  <Fact key={`${entry.component}-${entry.relationship}-${i}`} label={`${entry.component} · ${entry.relationship}`} value={entry.role} />
+                ))}
+              </>
+            )}
           </View>
         </View>
       </View>
@@ -95,6 +103,13 @@ const styles = StyleSheet.create({
     marginBottom: 10,
   },
   body: { fontSize: CATALOG_TYPE.md, lineHeight: 20, color: CATALOG_COLOR.textMuted },
+  subheading: {
+    fontSize: CATALOG_TYPE.sm,
+    fontWeight: '700',
+    color: CATALOG_COLOR.text,
+    marginTop: CATALOG_SPACE.md,
+    marginBottom: CATALOG_SPACE.xs,
+  },
   fact: {
     flexDirection: 'row',
     justifyContent: 'space-between',

package/native/catalog/SectionBlock.tsx

@@ -5,9 +5,10 @@ import { ComparisonGrid } from './ComparisonGrid';
 import { ComparisonGroups } from './ComparisonGroups';
 import { ComparisonList } from './ComparisonList';
 import { ReferenceDetails } from './ReferenceDetails';
+import { SpecimenSurface } from './SpecimenSurface';
 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,9 +101,11 @@ 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 }) {
+  const stage = (node: React.ReactNode) => (surface ? <SpecimenSurface surface={surface}>{node}</SpecimenSurface> : node);
+  if (widths === 'full') return <View style={styles.previewCard}>{stage(render())}</View>;
   return (
     <View style={styles.previewCard}>
       <View style={styles.frames}>
@@ -114,7 +117,7 @@ function Preview({ render, widths }: { render: () => React.ReactNode; widths: Pr
             style={[styles.frame, { width }]}
           >
             {widths.length > 1 && <Text style={styles.frameLabel}>{frameLabel(width)}</Text>}
-            {render()}
+            {stage(render())}
           </View>
         ))}
       </View>
@@ -122,16 +125,18 @@ function Preview({ render, widths }: { render: () => React.ReactNode; widths: Pr
   );
 }
 
-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 +150,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 +159,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 +192,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 +208,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 +246,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 ?? 'neutral';
   // 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 +277,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,46 @@
+import React from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_SPACE } from './tokens';
+import { SPECIMEN_SURFACE_WIDTH_STYLE } from './specimenSurfaceStyle';
+import type { SpecimenSurfaceKind } from './types';
+
+/**
+ * The catalog-owned background directly behind a live component specimen — shared by
+ * `ComparisonList`, `ComparisonGroups`, `ComparisonGrid`, and `SectionBlock`'s component preview,
+ * so a page's `specimenSurface` renders identically everywhere a specimen appears. Purely a fixed
+ * backdrop: it never reads the wrapped component's own colors, never adds a border, and is never
+ * used for token galleries/sections (those keep their existing full-width presentation). Always
+ * stretches to its parent's width (see `specimenSurfaceStyle.ts`) rather than shrink-wrapping to
+ * its content, centering that content itself — so a percentage-width specimen resolves against
+ * the real comparison-cell width instead of collapsing to 0px.
+ */
+export function SpecimenSurface({
+  surface = 'neutral',
+  style,
+  children,
+}: {
+  surface?: SpecimenSurfaceKind;
+  style?: StyleProp<ViewStyle>;
+  children: React.ReactNode;
+}) {
+  return <View style={[styles.base, SURFACE_FILL[surface], style]}>{children}</View>;
+}
+
+// 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token) rather than adding a new
+// background-specific color — the catalog chrome has no existing dark-surface token to reach for.
+const SURFACE_FILL: Record<SpecimenSurfaceKind, ViewStyle> = {
+  neutral: { backgroundColor: CATALOG_COLOR.surfaceMuted },
+  white: { backgroundColor: CATALOG_COLOR.surface },
+  dark: { backgroundColor: CATALOG_COLOR.text },
+  transparent: { backgroundColor: 'transparent' },
+};
+
+const styles = StyleSheet.create({
+  base: {
+    ...SPECIMEN_SURFACE_WIDTH_STYLE,
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: CATALOG_RADIUS.sm,
+    padding: CATALOG_SPACE.md,
+  },
+});

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/specimenSurfaceStyle.ts

@@ -0,0 +1,15 @@
+/**
+ * `SpecimenSurface`'s width policy, kept free of any `react-native` import so `node --test` can
+ * assert on it directly (see `native/catalog/__tests__/specimenSurfaceStyle.test.ts`).
+ *
+ * The surface 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;

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,28 @@ export type SpecimenSize = 'compact' | 'regular' | 'wide';
  *  content that is not a phone component (catalog chrome, token galleries). */
 export type PreviewWidths = readonly number[] | 'full';
 
+/** Background behind a live component specimen (the list/grouped/grid cell, or the preview frame)
+ *  — a neutral (default), explicit white, dark, or transparent catalog-owned stage, so a specimen
+ *  reads as visibly separate from the surrounding white card rather than floating on it, which
+ *  matters most for a low-contrast or motion-only component that could otherwise blend into a
+ *  plain white background. Purely a fixed catalog-chrome backdrop: it never inspects or infers the
+ *  wrapped component's own colors, and is never applied to token galleries/sections, which keep
+ *  their current full-width, unstaged presentation regardless of this setting. */
+export type SpecimenSurfaceKind = '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 +217,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 `'neutral'`. 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 +235,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"). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",
@@ -8,6 +8,10 @@
     "type": "git",
     "url": "https://github.com/krapwoo/design-system-viewer.git"
   },
+  "bugs": {
+    "url": "https://github.com/krapwoo/design-system-viewer/issues"
+  },
+  "homepage": "https://github.com/krapwoo/design-system-viewer#readme",
   "engines": {
     "node": ">=20.19.0"
   },
@@ -57,6 +61,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
     "test": "node --experimental-strip-types --test 'cli/**/*.test.ts' 'config/**/*.test.ts' 'native/catalog/__tests__/*.test.ts'",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "kit:dev": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",

package/starter-kit/pages/Motion.catalog.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, DividedStack, VariantGroup, TokenRow } from '@krapwoo/ds-viewer';
+import { View, Text, StyleSheet, Easing } from 'react-native';
+import { defineCatalogPage, DividedStack, VariantGroup, TokenRow, MotionSpecimen } from '@krapwoo/ds-viewer';
 import {
   DS_MOTION_DURATION,
   DS_MOTION_DURATION_STEPS,
@@ -21,6 +21,7 @@ import {
 
 const styles = StyleSheet.create({
   tokenStack: { gap: DS_SPACING[800] },
+  rowContent: { gap: DS_SPACING[400] },
   previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
   previewLabel: { minWidth: 64, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
   previewValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted },
@@ -41,10 +42,18 @@ function MotionGallery() {
         <View style={styles.tokenStack}>
           {DS_MOTION_DURATION_STEPS.map((step, i) => (
             <TokenRow key={step} use={DS_MOTION_DURATION_USE[step]} last={i === DS_MOTION_DURATION_STEPS.length - 1}>
-              <View style={styles.previewRow}>
-                <Text style={styles.previewLabel}>{step}</Text>
-                <View style={[styles.durationBar, { width: (DS_MOTION_DURATION[step] / maxDuration) * 120 }]} />
-                <Text style={styles.previewValue}>{DS_MOTION_DURATION[step]}ms</Text>
+              <View style={styles.rowContent}>
+                <View style={styles.previewRow}>
+                  <Text style={styles.previewLabel}>{step}</Text>
+                  <View style={[styles.durationBar, { width: (DS_MOTION_DURATION[step] / maxDuration) * 120 }]} />
+                  <Text style={styles.previewValue}>{DS_MOTION_DURATION[step]}ms</Text>
+                </View>
+                <MotionSpecimen
+                  kind="timing"
+                  duration={DS_MOTION_DURATION[step]}
+                  easing={Easing.bezier(...DS_MOTION_EASING.standard)}
+                  label={`${DS_MOTION_DURATION[step]}ms · standard easing`}
+                />
               </View>
             </TokenRow>
           ))}
@@ -54,10 +63,18 @@ function MotionGallery() {
         <View style={styles.tokenStack}>
           {DS_MOTION_LOOP_DURATION_STEPS.map((step, i) => (
             <TokenRow key={step} use={DS_MOTION_LOOP_DURATION_USE[step]} last={i === DS_MOTION_LOOP_DURATION_STEPS.length - 1}>
-              <View style={styles.previewRow}>
-                <Text style={styles.previewLabel}>{step}</Text>
-                <View style={[styles.durationBar, { width: (DS_MOTION_LOOP_DURATION[step] / maxLoopDuration) * 120 }]} />
-                <Text style={styles.previewValue}>{DS_MOTION_LOOP_DURATION[step]}ms</Text>
+              <View style={styles.rowContent}>
+                <View style={styles.previewRow}>
+                  <Text style={styles.previewLabel}>{step}</Text>
+                  <View style={[styles.durationBar, { width: (DS_MOTION_LOOP_DURATION[step] / maxLoopDuration) * 120 }]} />
+                  <Text style={styles.previewValue}>{DS_MOTION_LOOP_DURATION[step]}ms</Text>
+                </View>
+                <MotionSpecimen
+                  kind="timing"
+                  duration={DS_MOTION_LOOP_DURATION[step]}
+                  easing={Easing.bezier(...DS_MOTION_EASING.standard)}
+                  label={`${DS_MOTION_LOOP_DURATION[step]}ms · one cycle`}
+                />
               </View>
             </TokenRow>
           ))}
@@ -67,9 +84,17 @@ function MotionGallery() {
         <View style={styles.tokenStack}>
           {DS_MOTION_EASING_STEPS.map((step, i) => (
             <TokenRow key={step} use={DS_MOTION_EASING_USE[step]} last={i === DS_MOTION_EASING_STEPS.length - 1}>
-              <View style={styles.previewRow}>
-                <Text style={styles.previewLabel}>{step}</Text>
-                <Text style={styles.easingValue}>cubic-bezier({DS_MOTION_EASING[step].join(', ')})</Text>
+              <View style={styles.rowContent}>
+                <View style={styles.previewRow}>
+                  <Text style={styles.previewLabel}>{step}</Text>
+                  <Text style={styles.easingValue}>cubic-bezier({DS_MOTION_EASING[step].join(', ')})</Text>
+                </View>
+                <MotionSpecimen
+                  kind="timing"
+                  duration={DS_MOTION_DURATION.base}
+                  easing={Easing.bezier(...DS_MOTION_EASING[step])}
+                  label={`${DS_MOTION_DURATION.base}ms · ${step}`}
+                />
               </View>
             </TokenRow>
           ))}
@@ -78,13 +103,16 @@ function MotionGallery() {
       <VariantGroup name="Spring" desc="for Animated.spring(value, DS_MOTION_SPRING) — snap-point transitions, not fixed-duration timing">
         <View style={styles.tokenStack}>
           <TokenRow use={DS_MOTION_SPRING_USE} last>
-            <View style={styles.springGrid}>
-              {(Object.entries(DS_MOTION_SPRING) as [string, number | boolean][]).map(([key, value]) => (
-                <View key={key} style={styles.springField}>
-                  <Text style={styles.previewLabel}>{key}</Text>
-                  <Text style={styles.previewValue}>{String(value)}</Text>
-                </View>
-              ))}
+            <View style={styles.rowContent}>
+              <View style={styles.springGrid}>
+                {(Object.entries(DS_MOTION_SPRING) as [string, number | boolean][]).map(([key, value]) => (
+                  <View key={key} style={styles.springField}>
+                    <Text style={styles.previewLabel}>{key}</Text>
+                    <Text style={styles.previewValue}>{String(value)}</Text>
+                  </View>
+                ))}
+              </View>
+              <MotionSpecimen kind="spring" spring={DS_MOTION_SPRING} label="Animated.spring(value, DS_MOTION_SPRING)" />
             </View>
           </TokenRow>
         </View>