@krapwoo/ds-viewer 0.4.2 → 0.4.4

package/native/catalog/catalogNavigation.ts

@@ -48,12 +48,17 @@ export function neighbors<TId extends string>(
 }
 
 /** Sidebar filter: case-insensitive substring match, sorted ids, empty groups removed. */
-export function filterGroups<TId extends string>(groups: readonly NavGroup<TId>[], query: string): NavGroup<TId>[] {
+export function filterGroups<TId extends string>(
+  groups: readonly NavGroup<TId>[],
+  query: string,
+  /** Display titles by id; a page matches on its id or its title. */
+  labels?: ReadonlyMap<string, string>,
+): NavGroup<TId>[] {
   const q = query.trim().toLowerCase();
   return groups
     .map((group) => ({
       label: group.label,
-      ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q)) : group.ids),
+      ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q) || (labels?.get(id)?.toLowerCase().includes(q) ?? false)) : group.ids),
     }))
     .filter((group) => group.ids.length > 0);
 }

package/native/catalog/comparison.ts

@@ -8,7 +8,7 @@
  * It also decides whether two blocks sit side by side (choosePlacement) and how many columns the
  * Props box uses (propsColumns). ComparisonGrid, ComparisonGroups, and ComparisonList render it.
  */
-import type { ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenSize, VariantSlot } from './types.ts';
+import type { ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenSize, TokenSection, VariantSlot } from './types.ts';
 import type React from 'react';
 
 /** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
@@ -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,8 +233,9 @@ 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 };
 
 export interface PresentationOptions {
@@ -280,6 +286,10 @@ function groupStates(variants: VariantSlot, states: VariantSlot): { groups: List
  *  never shows an empty block next to a real one; with nothing documented at all it shows one
  *  "No examples documented." block. */
 export function presentationBlocks<TId extends string>(def: SectionDef<TId>, options: PresentationOptions = {}): PresentationBlock[] {
+  if (def.tokenSections && def.tokenSections.length > 0) {
+    // Each section carries its own label, so the block itself has none.
+    return [{ kind: 'tokenSections', title: '', sections: def.tokenSections, columns: def.tokenColumns ?? 1 }];
+  }
   if (def.tokenGallery) {
     const title = def.fullWidthLabel ?? 'Tokens';
     return [def.render ? { kind: 'preview', title, widths: 'full' } : { kind: 'empty', title, message: 'Nothing to preview.' }];
@@ -303,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) });
     }
@@ -316,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 } : {}),
     });
   }
 
@@ -331,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;
@@ -346,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,10 @@ 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';
 export { PhoneFrame } from './PhoneFrame';
@@ -33,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 } 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, 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. */
@@ -9,6 +9,14 @@ export interface CatalogPageInput<TId extends string = string> {
    *  default when writing the generated page index, so an authored page never has to repeat a name
    *  already implied by its file. */
   id?: TId;
+  /** Display name; see `SectionDef.title`. */
+  title?: string;
+  /** Project-relative file shown as the page's Source when the page documents something other
+   *  than a component, e.g. a token page pointing at `src/design-system/tokens.ts`. A component's
+   *  own file always wins. */
+  source?: string;
+  /** See `SectionDef.osComponent`. */
+  osComponent?: 'full' | 'partial';
   description: string;
   whenToUse?: string;
   a11y?: string;
@@ -16,11 +24,15 @@ export interface CatalogPageInput<TId extends string = string> {
   states?: VariantSlot;
   render?: () => React.ReactNode;
   tokenGallery?: boolean;
+  tokenSections?: TokenSection[];
+  tokenColumns?: 1 | 2 | 3;
   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. */
@@ -77,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()];
@@ -102,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
@@ -112,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);
@@ -121,20 +149,27 @@ export function buildCatalogSections<TId extends string>(
     // to the page's own file as its Source instead of an empty path.
     return {
       id: page.id,
+      title: page.title,
+      osComponent: page.osComponent,
       description: page.description,
-      path: component?.file ?? page.file,
+      path: component?.file ?? page.source ?? page.file,
       whenToUse: page.whenToUse,
       props: component ? mergePropNotes(component, page.propNotes) : undefined,
       a11y: page.a11y,
       variants: page.variants,
       states: page.states,
       render: page.render,
-      tokenGallery: page.tokenGallery,
+      // `tokenSections` makes a page a token gallery by itself.
+      tokenGallery: page.tokenGallery || (page.tokenSections !== undefined && page.tokenSections.length > 0) || undefined,
+      tokenSections: page.tokenSections,
+      tokenColumns: page.tokenColumns,
       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/tokenLayout.ts

@@ -0,0 +1,29 @@
+/**
+ * Pure layout maths for token pages — no React or React Native runtime imports, so it is unit
+ * tested directly (`__tests__/tokenLayout.test.ts`).
+ *
+ * Token pages lay out in two levels:
+ *  - sections (one titled card per kind of token, e.g. "Semantic" vs "Palette") flow in up to
+ *    `tokenColumns` columns, dropping to fewer rather than squeezing a section under its minimum;
+ *  - inside a section, `TokenGrid` tiles as many equal tiles per row as keep their minimum width.
+ */
+
+/** Narrowest a side-by-side token section may get before the page drops a column. */
+export const TOKEN_SECTION_MIN_WIDTH = 280;
+/** Gap between side-by-side sections and between tiles. */
+export const TOKEN_LAYOUT_GAP = 20;
+
+/** How many section columns fit in `available` px, at most `requested`, never below 1. */
+export function sectionColumns(available: number, requested: number): number {
+  const fit = Math.floor((available + TOKEN_LAYOUT_GAP) / (TOKEN_SECTION_MIN_WIDTH + TOKEN_LAYOUT_GAP));
+  return Math.max(1, Math.min(requested, fit));
+}
+
+/** Equal tiles per row for a `TokenGrid`: as many as keep `minTileWidth` (capped by `maxColumns`),
+ *  sized so the row is filled exactly. */
+export function tileGeometry(available: number, minTileWidth: number, maxColumns = Infinity): { columns: number; tileWidth: number } {
+  const fit = Math.floor((available + TOKEN_LAYOUT_GAP) / (minTileWidth + TOKEN_LAYOUT_GAP));
+  const columns = Math.max(1, Math.min(maxColumns, fit));
+  const tileWidth = columns === 1 ? available : (available - TOKEN_LAYOUT_GAP * (columns - 1)) / columns;
+  return { columns, tileWidth };
+}

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;
@@ -102,6 +130,13 @@ export interface ComparisonDef {
  *  typed to the app's real section list without this file needing to know what they are. */
 export interface SectionDef<TId extends string = string> {
   id: TId;
+  /** Display name for the heading, sidebar and search (e.g. "Control heights"). Defaults to `id`,
+   *  which stays the page's address (`#ControlHeights`) and its name in `explain`. */
+  title?: string;
+  /** Marks a component that is, or contains, a native platform control rather than a custom one:
+   *  `'full'` shows an "OS component" badge under the title, `'partial'` "Partly OS component".
+   *  Say in `description` which part is native and how it differs on web. */
+  osComponent?: 'full' | 'partial';
   description: string;
   path: string;
   /** One sentence disambiguating this component from its closest look-alike(s) — the deciding
@@ -163,6 +198,14 @@ export interface SectionDef<TId extends string = string> {
    *  configurations list, and shows only a Quick reference card with the source path (there's no
    *  component behavior to document). */
   tokenGallery?: boolean;
+  /** Token pages with more than one kind of token: one titled card per section (e.g. "Semantic"
+   *  and "Palette", or "Body" and "Title"), instead of a single "Tokens" card. When set, `render`
+   *  is not used and the page counts as a token gallery. See `TokenSection`. */
+  tokenSections?: TokenSection[];
+  /** How many sections sit side by side (1–3, default 1). Narrow sections such as type families
+   *  use 2–3; the page drops columns rather than squeeze a section under 280px. A section with
+   *  `wide: true` always takes a full row. */
+  tokenColumns?: 1 | 2 | 3;
   /** Overrides the `tokenGallery` block's label (default `'Tokens'`) — e.g. `'Preview'` for a page
    *  that's a composed, realistic usage example rather than a list of raw token values. Ignored
    *  unless `tokenGallery` is also set. */
@@ -174,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;
@@ -188,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"). */
@@ -206,3 +257,14 @@ export interface UpdateNotice {
   summary: string[];
   releasedAt?: string;
 }
+
+/** One titled card on a token page (`SectionDef.tokenSections`). */
+export interface TokenSection {
+  /** The kind of token this card holds, e.g. "Semantic colours", "Palette", "Body". */
+  title: string;
+  /** One line under the title: what this kind of token is for. */
+  desc?: string;
+  /** Take a full row even when the page sets `tokenColumns` (e.g. palette ramps). */
+  wide?: boolean;
+  render: () => React.ReactNode;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.2",
+  "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>