@krapwoo/ds-viewer 0.4.3 → 0.4.5

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,30 @@ 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: 'auto' | 'neutral' | 'white' | 'dark' | 'transparent'` — the fill of each
+  example's cell (list, grouped and grid cells, and a non-token `render()` preview). Defaults to
+  `'auto'`: after the page draws, a cell turns light gray only when its own example would vanish
+  against white (its largest coloured box is near-white with no visible border, like a white card,
+  sheet or neutral banner; a shadow alone doesn't count). Neighbouring examples keep a white cell,
+  and most pages need nothing. Override it when the guess is wrong: `'neutral'` makes every example
+  cell gray, `'white'` or `'transparent'` keeps them all white, and `'dark'` checks a light
+  component on a dark fill. Detection runs in the browser viewer; elsewhere cells stay white.
+  Token galleries and sections are never filled.
+- `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 +236,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 +279,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 +294,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/dist/native/catalog/tokens.js

@@ -111,6 +111,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/ComparisonGrid.tsx

@@ -2,14 +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, axisItems, cellKey, gridWidthBounds, indexCells, validateComparison } from './comparison';
-import type { ComparisonDef, SpecimenSize } from './types';
+import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
+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 = DEFAULT_SPECIMEN_SURFACE,
+}: {
+  def: ComparisonDef;
+  size: SpecimenSize;
+  sectionId: string;
+  surface?: SpecimenSurfaceKind;
+}) {
   if (__DEV__) {
     for (const issue of validateComparison({ ...def, size })) console.warn(`[Catalog] ${sectionId}: ${issue}`);
   }
@@ -51,15 +64,17 @@ export function ComparisonGrid({ def, size, sectionId }: { def: ComparisonDef; s
             {columns.map((c, ci) => {
               const cell = cells.get(cellKey(row.key, c.key));
               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>
-                  ) : (
+                cell?.node !== undefined ? (
+                  <SpecimenSurface key={c.key} role="cell" surface={surface} style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
+                    <SpecimenContent fill={cell.fill}>{cell.node}</SpecimenContent>
+                  </SpecimenSurface>
+                ) : (
+                  <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
                     <Text style={styles.unavailable}>
                       {cell?.unavailableReason ? `Not supported — ${cell.unavailableReason}` : 'Missing example'}
                     </Text>
-                  )}
-                </View>
+                  </View>
+                )
               );
             })}
           </View>
@@ -88,8 +103,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 },
   unavailable: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', textAlign: 'center', color: CATALOG_COLOR.textMuted },

package/native/catalog/ComparisonGroups.tsx

@@ -2,15 +2,28 @@ 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 { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
+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 = DEFAULT_SPECIMEN_SURFACE,
+}: {
+  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;
@@ -34,9 +47,9 @@ export function ComparisonGroups({ groups, size, label }: { groups: ListGroup[];
                     <View style={styles.caption}>
                       <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>
-                    </View>
+                    <SpecimenSurface surface={surface} style={styles.specimen}>
+                      <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                    </SpecimenSurface>
                   </View>
                 );
               })}
@@ -88,6 +101,4 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
-  center: { alignItems: 'center' },
-  fill: { alignSelf: 'stretch' },
 });

package/native/catalog/ComparisonList.tsx

@@ -2,16 +2,32 @@ 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 { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
+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 = DEFAULT_SPECIMEN_SURFACE,
+}: {
+  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);
@@ -45,9 +61,9 @@ export function ComparisonList({ items, size, label }: { items: ListItem[]; size
                   <View style={styles.caption}>
                     <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>
-                  </View>
+                  <SpecimenSurface surface={surface} style={styles.specimen}>
+                    <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                  </SpecimenSurface>
                 </View>
               );
             })}
@@ -84,6 +100,4 @@ 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',