@krapwoo/ds-viewer 0.4.2 → 0.4.4

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,8 +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.
@@ -45,23 +47,27 @@ export interface SectionPager<TId extends string> {
   previousId: TId | null;
   nextId: TId | null;
   onNavigate: (id: TId) => void;
+  /** Display title for a page id, for the buttons' accessible names. */
+  labelOf?: (id: TId) => string;
 }
 
 function PagerButton<TId extends string>({
   direction,
   targetId,
   onNavigate,
+  labelOf,
 }: {
   direction: 'previous' | 'next';
   targetId: TId | null;
   onNavigate: (id: TId) => void;
+  labelOf?: (id: TId) => string;
 }) {
   const [hovered, setHovered] = useState(false);
   const [focused, setFocused] = useState(false);
   const disabled = targetId == null;
   const label = disabled
     ? direction === 'previous' ? 'No previous page' : 'No next page'
-    : `${direction === 'previous' ? 'Previous' : 'Next'}: ${targetId}`;
+    : `${direction === 'previous' ? 'Previous' : 'Next'}: ${labelOf ? labelOf(targetId) : targetId}`;
   return (
     <Pressable
       onPress={() => {
@@ -95,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}>
@@ -109,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>
@@ -117,16 +125,20 @@ 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:
       return (
         <View style={styles.previewCard}>
@@ -138,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;
 }
 
 /**
@@ -147,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');
@@ -180,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');
@@ -191,12 +203,12 @@ function Blocks<TId extends string>({ blocks, def }: { blocks: PresentationBlock
     <View onLayout={onContainerLayout} style={[styles.blocks, side && styles.blocksSide]}>
       {blocks.map((block, i) => (
         <View
-          key={block.title}
+          key={block.title || block.kind}
           onLayout={onBlockLayout(i)}
           style={side ? (i === 0 ? { width: blockWidth(block, available), flexShrink: 0 } : styles.blockFill) : undefined}
         >
-          <Text style={styles.blockLabel}>{block.title}</Text>
-          <BlockContent block={block} def={def} />
+          {block.title ? <Text style={styles.blockLabel}>{block.title}</Text> : null}
+          <BlockContent block={block} def={def} surface={surface} />
         </View>
       ))}
     </View>
@@ -234,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>;
 
@@ -247,19 +260,24 @@ export function SectionBlock<TId extends string>({
         <View style={styles.titleText}>
           {/* The focus target is the heading itself, so assistive tech announces its role and level. */}
           <View ref={headingRef} tabIndex={-1} role="heading" {...headingLevelProps} style={styles.headingTarget}>
-            <Text style={styles.title}>{def.id}</Text>
+            <Text style={styles.title}>{def.title ?? def.id}</Text>
           </View>
+          {def.osComponent && (
+            <View style={styles.osBadge}>
+              <Text style={styles.osBadgeText}>{def.osComponent === 'full' ? 'OS component' : 'Partly OS component'}</Text>
+            </View>
+          )}
           <Text style={styles.desc}>{def.description}</Text>
         </View>
         {pager && (
           <View style={styles.pager}>
-            <PagerButton direction="previous" targetId={pager.previousId} onNavigate={pager.onNavigate} />
-            <PagerButton direction="next" targetId={pager.nextId} onNavigate={pager.onNavigate} />
+            <PagerButton direction="previous" targetId={pager.previousId} onNavigate={pager.onNavigate} labelOf={pager.labelOf} />
+            <PagerButton direction="next" targetId={pager.nextId} onNavigate={pager.onNavigate} labelOf={pager.labelOf} />
           </View>
         )}
       </View>
 
-      {blocks.length > 0 && <Blocks blocks={blocks} def={def} />}
+      {blocks.length > 0 && <Blocks blocks={blocks} def={def} surface={surface} />}
 
       <ReferenceDetails def={def} />
     </View>
@@ -278,6 +296,17 @@ const styles = StyleSheet.create({
   },
   titleText: { flex: 1 },
   headingTarget: { alignSelf: 'flex-start' },
+  osBadge: {
+    alignSelf: 'flex-start',
+    marginBottom: CATALOG_SPACE.sm,
+    paddingHorizontal: CATALOG_SPACE.sm,
+    paddingVertical: 3,
+    borderRadius: CATALOG_RADIUS.control,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.borderStrong,
+    backgroundColor: CATALOG_COLOR.surface,
+  },
+  osBadgeText: { fontSize: CATALOG_TYPE.xs, fontWeight: '700', letterSpacing: 0.4, color: CATALOG_COLOR.text },
   title: { fontSize: CATALOG_TYPE.pageTitle, fontWeight: '700', color: CATALOG_COLOR.text, marginBottom: 5 },
   desc: { fontSize: CATALOG_TYPE.md, lineHeight: 20, color: CATALOG_COLOR.textMuted, maxWidth: 700 },
   pager: { flexDirection: 'row', gap: 6, flexShrink: 0 },

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/TokenLayouts.tsx

@@ -0,0 +1,92 @@
+import React, { useState } from 'react';
+import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { sectionColumns, tileGeometry, TOKEN_LAYOUT_GAP } from './tokenLayout';
+import type { TokenSection } from './types';
+
+/** Measures its own width; renders nothing inside until the width is known. */
+function useWidth(): [number, (event: LayoutChangeEvent) => void] {
+  const [width, setWidth] = useState(0);
+  return [width, (event) => {
+    const next = Math.round(event.nativeEvent.layout.width);
+    if (next > 0 && next !== width) setWidth(next);
+  }];
+}
+
+/**
+ * A token page's sections (`SectionDef.tokenSections`): one titled card per kind of token, flowing
+ * in up to `columns` columns. A `wide` section takes a full row; the page drops to fewer columns
+ * rather than squeeze a section under its minimum width.
+ */
+export function TokenSections({ sections, columns }: { sections: TokenSection[]; columns: 1 | 2 | 3 }) {
+  const [width, onLayout] = useWidth();
+  const perRow = sectionColumns(width, columns);
+  const columnWidth = perRow === 1 ? width : (width - TOKEN_LAYOUT_GAP * (perRow - 1)) / perRow;
+  return (
+    <View onLayout={onLayout} style={styles.sections}>
+      {width > 0 && sections.map((section) => (
+        <View key={section.title} style={{ width: section.wide || perRow === 1 ? width : columnWidth }}>
+          <Text style={styles.sectionLabel}>{section.title}</Text>
+          {section.desc ? <Text style={styles.sectionDesc}>{section.desc}</Text> : null}
+          <View style={styles.card}>{section.render()}</View>
+        </View>
+      ))}
+    </View>
+  );
+}
+
+/**
+ * Tokens as tiles in columns — for tokens whose preview is small and self-contained (radius,
+ * shadow, colour, control height). As many equal tiles per row as keep `minTileWidth`.
+ */
+export function TokenGrid({ children, minTileWidth = 140, maxColumns }: { children: React.ReactNode; minTileWidth?: number; maxColumns?: number }) {
+  const [width, onLayout] = useWidth();
+  const { tileWidth } = tileGeometry(width, minTileWidth, maxColumns);
+  return (
+    <View onLayout={onLayout} style={styles.grid}>
+      {width > 0 && React.Children.map(children, (child) => (child ? <View style={{ width: tileWidth }}>{child}</View> : null))}
+    </View>
+  );
+}
+
+/**
+ * One token in a `TokenGrid`: its preview, then its name and value, then its role. `note` says
+ * where or why the token is used (from its comments or real usages) — omit it when there is none.
+ */
+export function TokenTile({ name, value, note, children }: { name: string; value?: string; note?: string; children: React.ReactNode }) {
+  return (
+    <View style={styles.tile}>
+      <View style={styles.tilePreview}>{children}</View>
+      <Text style={styles.tileName}>{name}</Text>
+      {value ? <Text style={styles.tileValue}>{value}</Text> : null}
+      {note ? <Text style={styles.tileNote}>{note}</Text> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  sections: { flexDirection: 'row', flexWrap: 'wrap', gap: TOKEN_LAYOUT_GAP, rowGap: CATALOG_LAYOUT.blockGap, alignItems: 'flex-start' },
+  sectionLabel: {
+    fontSize: CATALOG_TYPE.sm,
+    fontWeight: '700',
+    letterSpacing: 0.72,
+    textTransform: 'uppercase',
+    color: CATALOG_COLOR.text,
+  },
+  sectionDesc: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: CATALOG_SPACE.xs },
+  card: {
+    marginTop: CATALOG_LAYOUT.blockLabelGap,
+    backgroundColor: CATALOG_COLOR.surface,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.borderStrong,
+    borderRadius: CATALOG_RADIUS.card,
+    padding: CATALOG_SPACE.xl,
+    gap: CATALOG_SPACE.md,
+  },
+  grid: { flexDirection: 'row', flexWrap: 'wrap', gap: TOKEN_LAYOUT_GAP },
+  tile: { gap: CATALOG_SPACE.xs },
+  tilePreview: { minHeight: 56, justifyContent: 'center', marginBottom: CATALOG_SPACE.xs },
+  tileName: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.text },
+  tileValue: { fontSize: CATALOG_TYPE.xs, color: CATALOG_COLOR.textMuted },
+  tileNote: { fontSize: CATALOG_TYPE.xs, color: CATALOG_COLOR.textMuted, lineHeight: 16 },
+});

package/native/catalog/TokenRow.tsx

@@ -11,21 +11,46 @@ 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, use, last = false }: { children: React.ReactNode; use: string; last?: boolean }) {
+export function TokenRow({
+  children,
+  use,
+  last = false,
+  notePlacement = 'below',
+  sampleWidth = 280,
+}: {
+  children: React.ReactNode;
+  use: string;
+  last?: boolean;
+  /** `'right'` puts the note beside a narrow sample (icon sizes, spacing, control heights) so each
+   *  token is one line; the sample keeps `sampleWidth` and the note takes the rest. */
+  notePlacement?: 'below' | 'right';
+  sampleWidth?: number;
+}) {
+  if (notePlacement === 'right') {
+    return (
+      <View style={[styles.itemRight, !last && styles.itemDivider]}>
+        <View style={{ width: sampleWidth, flexShrink: 0 }}>{children}</View>
+        {use ? <Text style={[styles.use, styles.useRight]}>{use}</Text> : null}
+      </View>
+    );
+  }
   return (
     <View style={[styles.item, !last && styles.itemDivider]}>
       {children}
-      <Text style={styles.use}>{use}</Text>
+      {use ? <Text style={styles.use}>{use}</Text> : null}
     </View>
   );
 }
 
 const styles = StyleSheet.create({
-  item: { gap: CATALOG_SPACE.xs },
+  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,
   },