@krapwoo/ds-viewer 0.4.9 → 0.6.0

package/native/catalog/CatalogShell.tsx

@@ -52,7 +52,7 @@ function resetMainScroll(scrollView: ScrollView | null): void {
  *  with only `onPress` (as `CatalogSidebar.tsx`'s own finding already documents) never activates on
  *  Enter under react-native-web unless the element is a genuine anchor. `role="status"` (not
  *  `"alert"`, the mockup's own choice) — a non-urgent notice should not interrupt assistive tech. */
-function MajorBanner({ update, onReviewUpdate, onDismiss }: { update: UpdateNotice; onReviewUpdate: () => void; onDismiss: () => void }) {
+function MajorBanner({ update, onReviewUpdate, onDismiss, keepDocumentUrl = false }: { update: UpdateNotice; onReviewUpdate: () => void; onDismiss: () => void; keepDocumentUrl?: boolean }) {
   const releaseUrl = `https://github.com/krapwoo/design-system-viewer/releases/tag/v${update.latest}`;
   return (
     <View style={bannerStyles.banner} role="status">
@@ -68,7 +68,16 @@ function MajorBanner({ update, onReviewUpdate, onDismiss }: { update: UpdateNoti
           Migration guide
         </Text>
         {' · '}
-        <Text role="link" style={bannerStyles.link} onPress={onReviewUpdate} {...({ href: hashForId(UPDATE_PAGE_ID) } as Record<string, unknown>)}>
+        <Text
+          role="link"
+          style={bannerStyles.link}
+          onPress={(event?: { preventDefault?: () => void }) => {
+            // An embedded shell opens its own update page; the host page's address stays put.
+            if (keepDocumentUrl) event?.preventDefault?.();
+            onReviewUpdate();
+          }}
+          {...({ href: hashForId(UPDATE_PAGE_ID) } as Record<string, unknown>)}
+        >
           Review update
         </Text>
       </Text>
@@ -96,7 +105,7 @@ const bannerStyles = StyleSheet.create({
   bold: { fontWeight: '700' },
   link: { color: CATALOG_COLOR.warning, fontWeight: '700', textDecorationLine: 'underline' },
   close: { width: 32, height: 32, borderRadius: CATALOG_RADIUS.sm, alignItems: 'center', justifyContent: 'center' },
-  closeGlyph: { fontSize: 18, color: CATALOG_COLOR.warning },
+  closeGlyph: { fontSize: CATALOG_TYPE.xl, color: CATALOG_COLOR.warning },
 });
 
 /**
@@ -115,9 +124,16 @@ export function CatalogShell<TId extends string>({
   update,
   versionStatus,
   updateEndpoint,
+  embedded = false,
+  initialPage,
 }: {
   /** Short product/app name — the sidebar logo and the breadcrumb root. */
   appName: string;
+  /** A shell shown inside another page (a catalog demo): it keeps its selected page in its own
+   *  state, never reads or writes the URL, and doesn't treat the page's address as its own. */
+  embedded?: boolean;
+  /** The page an embedded shell opens on (defaults to the first page). */
+  initialPage?: TId;
   /** Optional logo image, validated and bundled by `cli/workspace.ts` from the project's `logo`
    *  config field. See `CatalogSidebar`'s own doc comment for the approved layout rule. */
   logoImageSource?: ImageSourcePropType;
@@ -150,14 +166,16 @@ export function CatalogShell<TId extends string>({
   // recognizing itself as the selected address) would otherwise render alongside it for nothing.
   // Read once per mount, like `active`'s own initial read below: this mode is only ever entered by
   // a fresh document load, never a same-document transition.
-  const overlayAddress = useMemo(() => (isWeb() ? overlayAddressFromSearch(window.location.search) : undefined), []);
+  // An embedded shell never owns the URL (hash routing, the overlay child-document address).
+  const routesByUrl = isWeb() && !embedded;
+  const overlayAddress = useMemo(() => (routesByUrl ? overlayAddressFromSearch(window.location.search) : undefined), [routesByUrl]);
   const overlayNode = useMemo(() => (overlayAddress ? findOverlayNode(sections, overlayAddress) : undefined), [overlayAddress, sections]);
 
   const sectionsById = useMemo(() => new Map(sections.map((def) => [def.id, def])), [sections]);
   const labels = useMemo(() => new Map(sections.filter((def) => def.title).map((def) => [def.id as string, def.title as string])), [sections]);
   const order = useMemo(() => orderedIds(groups, new Set(sectionsById.keys())), [groups, sectionsById]);
   const [active, setActive] = useState<ShellPageId<TId> | undefined>(() =>
-    isWeb() ? resolveActiveFromHash(window.location.hash, order) : order[0],
+    embedded ? initialPage ?? order[0] : isWeb() ? resolveActiveFromHash(window.location.hash, order) : order[0],
   );
 
   const scrollRef = useRef<ScrollView>(null);
@@ -179,7 +197,7 @@ export function CatalogShell<TId extends string>({
 
   // Back/forward and manual fragment edits.
   useEffect(() => {
-    if (!isWeb()) return;
+    if (!routesByUrl) return;
     const onHashChange = () => {
       const id = resolveActiveFromHash(window.location.hash, order);
       if (id === undefined) return;
@@ -193,7 +211,7 @@ export function CatalogShell<TId extends string>({
     };
     window.addEventListener('hashchange', onHashChange);
     return () => window.removeEventListener('hashchange', onHashChange);
-  }, [order]);
+  }, [order, routesByUrl]);
 
   // After every page change: sync the fragment, return to the top, and move focus when the user
   // navigated (never on first load).
@@ -203,7 +221,7 @@ export function CatalogShell<TId extends string>({
     const focus = focusHeadingNext.current;
     pushHistoryNext.current = false;
     focusHeadingNext.current = false;
-    if (isWeb()) {
+    if (routesByUrl) {
       const expected = hashForId(active);
       if (window.location.hash !== expected) {
         if (push) window.location.hash = expected;
@@ -212,7 +230,7 @@ export function CatalogShell<TId extends string>({
     }
     resetMainScroll(scrollRef.current);
     if (focus) focusElement(headingRef.current);
-  }, [active]);
+  }, [active, routesByUrl]);
 
   const activeDef = active !== undefined && active !== UPDATE_PAGE_ID ? sectionsById.get(active) : undefined;
 
@@ -266,7 +284,7 @@ export function CatalogShell<TId extends string>({
 
   return (
     <View style={styles.root}>
-      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} labels={labels} active={active} onPress={select} footer={footer} />
+      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} labels={labels} active={active} onPress={select} footer={footer} keepDocumentUrl={embedded} />
       <ScrollView ref={scrollRef} style={styles.main} contentContainerStyle={styles.mainContent}>
         {active === UPDATE_PAGE_ID ? (
           <UpdatePanel
@@ -286,7 +304,7 @@ export function CatalogShell<TId extends string>({
             // The approved mockup's own `PAGE_BG` order: crumb, then banner, then title — the
             // banner used to render above the breadcrumb instead (Important finding, Fable
             // correction pass).
-            banner={showBanner && effectiveUpdate ? <MajorBanner update={effectiveUpdate} onReviewUpdate={() => select(UPDATE_PAGE_ID)} onDismiss={dismissMajorBanner} /> : undefined}
+            banner={showBanner && effectiveUpdate ? <MajorBanner update={effectiveUpdate} onReviewUpdate={() => select(UPDATE_PAGE_ID)} onDismiss={dismissMajorBanner} keepDocumentUrl={embedded} /> : undefined}
             pager={{
               previousId: neighbors(order, activeDef.id).previous,
               nextId: neighbors(order, activeDef.id).next,

package/native/catalog/CatalogSidebar.tsx

@@ -13,12 +13,21 @@ function webLinkProps(id: string, active: boolean) {
 
 /** One nav link. Hover via onHoverIn/onHoverOut (react-native-web fires them; native never does);
  *  keyboard focus draws the catalog focus ring because react-native-web removes the browser's. */
-function NavItem<TId extends string>({ id, label, active, onPress }: { id: TId; label: string; active: boolean; onPress: () => void }) {
+/** In an embedded shell, a link's own navigation would change the host page's address; the shell
+ *  handles the press itself, so the browser's default is cancelled. */
+function pressHandler(onPress: () => void, keepDocumentUrl: boolean) {
+  return (event?: { preventDefault?: () => void }) => {
+    if (keepDocumentUrl) event?.preventDefault?.();
+    onPress();
+  };
+}
+
+function NavItem<TId extends string>({ id, label, active, onPress, keepDocumentUrl = false }: { id: TId; label: string; active: boolean; onPress: () => void; keepDocumentUrl?: boolean }) {
   const [hovered, setHovered] = useState(false);
   const [focused, setFocused] = useState(false);
   return (
     <Pressable
-      onPress={onPress}
+      onPress={pressHandler(onPress, keepDocumentUrl)}
       onHoverIn={() => setHovered(true)}
       onHoverOut={() => setHovered(false)}
       onFocus={() => setFocused(true)}
@@ -43,12 +52,12 @@ function NavItem<TId extends string>({ id, label, active, onPress }: { id: TId;
   );
 }
 
-function FooterLink({ label, kind, active, onPress }: { label: string; kind: 'update' | 'version'; active: boolean; onPress: () => void }) {
+function FooterLink({ label, kind, active, onPress, keepDocumentUrl = false }: { label: string; kind: 'update' | 'version'; active: boolean; onPress: () => void; keepDocumentUrl?: boolean }) {
   const [hovered, setHovered] = useState(false);
   const [focused, setFocused] = useState(false);
   return (
     <Pressable
-      onPress={onPress}
+      onPress={pressHandler(onPress, keepDocumentUrl)}
       onHoverIn={() => setHovered(true)}
       onHoverOut={() => setHovered(false)}
       onFocus={() => setFocused(true)}
@@ -84,8 +93,11 @@ export function CatalogSidebar<TId extends string>({
   active,
   onPress,
   footer,
+  keepDocumentUrl = false,
 }: {
   logo: string;
+  /** For a shell embedded in another page: links never change the document's address. */
+  keepDocumentUrl?: boolean;
   /** Optional logo image, validated and bundled by `cli/workspace.ts` from the project's `logo`
    *  config field. Visual spec: docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html
    *  ("C · Adaptive", approved 2026-10-08) — a mark (aspect ratio ≤ 2) sits beside the name; a
@@ -195,14 +207,14 @@ export function CatalogSidebar<TId extends string>({
           <View key={group.label}>
             <Text style={styles.groupLabel}>{group.label}</Text>
             {group.ids.map((id) => (
-              <NavItem key={id} id={id} label={labels?.get(id) ?? id} active={active === id} onPress={() => onPress(id)} />
+              <NavItem key={id} id={id} label={labels?.get(id) ?? id} active={active === id} onPress={() => onPress(id)} keepDocumentUrl={keepDocumentUrl} />
             ))}
           </View>
         ))}
       </ScrollView>
       {footer && (
         <View style={styles.footerContainer}>
-          <FooterLink label={footer.label} kind={footer.kind ?? 'update'} active={footer.active} onPress={footer.onPress} />
+          <FooterLink label={footer.label} kind={footer.kind ?? 'update'} active={footer.active} onPress={footer.onPress} keepDocumentUrl={keepDocumentUrl} />
         </View>
       )}
     </View>

package/native/catalog/ComparisonGrid.tsx

@@ -1,7 +1,7 @@
 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 { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, axisItems, cellKey, gridMinWidth, indexCells, validateComparison } from './comparison';
 import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
 import { SpecimenAddressProvider } from './SpecimenAddress';
 import { comparisonCellItemKey } from './overlayViewport';
@@ -10,9 +10,11 @@ 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. `surface`
- * is the page's `specimenSurface` behind each cell's example.
+ * The card fills its container and its columns share that width equally, never shrinking below the
+ * specimen size's minimum; a grid narrower than that scrolls horizontally inside the card, never
+ * the page. Phone width (402px) caps the specimen inside a cell, not the column, so a two-column
+ * grid is as wide as a five-column one. `surface` is the page's `specimenSurface` behind each
+ * cell's example.
  */
 export function ComparisonGrid({
   def,
@@ -31,13 +33,12 @@ export function ComparisonGrid({
   const cells = indexCells(def);
   const rows = axisItems(def.rows);
   const columns = axisItems(def.columns);
-  const bounds = gridWidthBounds(columns.length, size);
+  const minWidth = gridMinWidth(columns.length, size);
   const column = {
     flexGrow: 1,
     flexShrink: 1,
     flexBasis: COLUMN_MIN_WIDTH[size],
     minWidth: COLUMN_MIN_WIDTH[size],
-    maxWidth: MATRIX_LAYOUT.columnMaxWidth,
   };
   const lastColumn = columns.length - 1;
 
@@ -46,7 +47,7 @@ export function ComparisonGrid({
       <View
         role="table"
         aria-label={`${sectionId}: ${def.rowLabel} by ${def.columnLabel}`}
-        style={[styles.card, { minWidth: bounds.minWidth, maxWidth: bounds.maxWidth }]}
+        style={[styles.card, { minWidth }]}
       >
         <View role="row" style={styles.row}>
           <View role="columnheader" style={[styles.cell, styles.rowHeader, styles.headerCell]}>
@@ -69,7 +70,7 @@ export function ComparisonGrid({
                 cell?.node !== undefined ? (
                   <SpecimenSurface key={c.key} role="cell" surface={cell.surface ?? surface} style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
                     <SpecimenAddressProvider address={{ pageId: sectionId, slot: 'comparison', itemKey: comparisonCellItemKey(row.key, c.key) }}>
-                      <SpecimenContent fill={cell.fill} align={cell.align}>{cell.node}</SpecimenContent>
+                      <SpecimenContent fill={cell.fill} align={cell.align} capped={size !== 'page'}>{cell.node}</SpecimenContent>
                     </SpecimenAddressProvider>
                   </SpecimenSurface>
                 ) : (

package/native/catalog/ComparisonGroups.tsx

@@ -10,9 +10,10 @@ 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. `surface` is
- * the page's `specimenSurface` behind each item.
+ * (a circle's size is not a bar's thickness). Each row is its own labeled list. Cells share the
+ * card's width equally, the way a grid's columns do, and shorter rows end in blank cells; a card
+ * narrower than its minimum scrolls horizontally inside itself. `surface` is the page's
+ * `specimenSurface` behind each item.
  */
 export function ComparisonGroups({
   groups,
@@ -53,7 +54,7 @@ export function ComparisonGroups({
                     </View>
                     <SpecimenSurface surface={item.surface ?? surface} style={styles.specimen}>
                       <SpecimenAddressProvider address={pageId && item.slot ? { pageId, slot: item.slot, itemKey: item.key } : undefined}>
-                        <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
+                        <SpecimenContent fill={item.fill} align={item.align} capped={size !== 'page'}>{item.node as React.ReactNode}</SpecimenContent>
                       </SpecimenAddressProvider>
                     </SpecimenSurface>
                   </View>
@@ -91,7 +92,7 @@ const styles = StyleSheet.create({
   },
   rowHeaderText: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
   cells: { flex: 1, flexDirection: 'row' },
-  cell: { flex: 1, maxWidth: MATRIX_LAYOUT.columnMaxWidth, borderRightWidth: 1, borderRightColor: CATALOG_COLOR.border },
+  cell: { flex: 1, borderRightWidth: 1, borderRightColor: CATALOG_COLOR.border },
   lastColumn: { borderRightWidth: 0 },
   caption: {
     padding: MATRIX_LAYOUT.cellPadding,

package/native/catalog/ComparisonList.tsx

@@ -10,7 +10,7 @@ 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. `maxColumns` caps
+ * last row. Wide specimens keep 402px as a minimum and share the container above it. `maxColumns` caps
  * how many columns a row ever wraps into (from `VariantSlot.maxColumns`); `surface` is the page's
  * `specimenSurface` behind each item.
  */
@@ -42,7 +42,7 @@ export function ComparisonList({
   for (let r = 0; r < geometry.rows; r += 1) rows.push(slots.slice(r * geometry.columns, (r + 1) * geometry.columns));
 
   return (
-    <View onLayout={onLayout}>
+    <View onLayout={onLayout} style={styles.measure}>
       <View role="list" aria-label={label} style={[styles.card, { width: geometry.containerWidth }]}>
         {rows.map((row, ri) => (
           <View key={ri} role="none" style={[styles.row, ri === rows.length - 1 && styles.lastRow]}>
@@ -67,7 +67,7 @@ export function ComparisonList({
                   </View>
                   <SpecimenSurface surface={item.surface ?? surface} style={styles.specimen}>
                     <SpecimenAddressProvider address={pageId && item.slot ? { pageId, slot: item.slot, itemKey: item.key } : undefined}>
-                      <SpecimenContent fill={item.fill} align={item.align}>{item.node as React.ReactNode}</SpecimenContent>
+                      <SpecimenContent fill={item.fill} align={item.align} capped={size !== 'page'}>{item.node as React.ReactNode}</SpecimenContent>
                     </SpecimenAddressProvider>
                   </SpecimenSurface>
                 </View>
@@ -81,7 +81,16 @@ export function ComparisonList({
 }
 
 const styles = StyleSheet.create({
+  // The wrapper that measures the space the list has. It must stretch: left to hug its own card it
+  // would keep reporting the card's width, so a list inside a narrower container (a specimen cell)
+  // would never learn to shrink and would overflow. `alignItems` keeps the card centred, the
+  // position it had when the wrapper hugged it.
+  measure: { alignSelf: 'stretch', alignItems: 'center' },
   card: {
+    // The width below is computed from the last measured space; until the first measurement lands
+    // it is a laptop-sized guess, so the card is also clamped to whatever space it really has —
+    // a list has no scroller of its own, and a too-wide guess would be cut off for a frame.
+    maxWidth: '100%',
     backgroundColor: CATALOG_COLOR.surface,
     borderWidth: 1,
     borderColor: CATALOG_COLOR.borderStrong,

package/native/catalog/OverlayDemo.tsx

@@ -0,0 +1,52 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { PhoneFrame } from './PhoneFrame';
+import { CatalogButton } from './CatalogButton';
+import { overlayTrigger } from './overlayDemoState';
+
+// Not `StyleSheet.absoluteFill`: React Native 0.81's types reject spreading it.
+const FILL = { position: 'absolute' as const, top: 0, right: 0, bottom: 0, left: 0 };
+
+/**
+ * A phone with a catalog button that opens an overlay: a sheet, a dialog, a toast. The overlay
+ * (`children`) fills the device above the centred trigger and gets `{ open, close }`; keep it
+ * mounted and drive its own `visible` from `open`, so its open and close animations play.
+ */
+export function OverlayDemo({
+  triggerLabel,
+  initiallyOpen = false,
+  keepTrigger = false,
+  children,
+}: {
+  triggerLabel: string | ((open: boolean) => string);
+  initiallyOpen?: boolean;
+  /** Keep the trigger visible while open, as a toggle. @default false */
+  keepTrigger?: boolean;
+  children: (state: { open: boolean; close: () => void }) => React.ReactNode;
+}) {
+  const [open, setOpen] = useState(initiallyOpen);
+  const trigger = overlayTrigger(open, { triggerLabel, keepTrigger });
+  // When the overlay closes, keyboard focus returns to the trigger instead of the page body.
+  const triggerRef = useRef<View>(null);
+  const wasOpen = useRef(open);
+  useEffect(() => {
+    if (wasOpen.current && !open) (triggerRef.current as unknown as { focus?: () => void } | null)?.focus?.();
+    wasOpen.current = open;
+  }, [open]);
+  return (
+    <PhoneFrame>
+      <View style={styles.screen}>
+        {trigger.visible && (
+          <CatalogButton ref={triggerRef} label={trigger.label} onPress={() => setOpen((value) => (keepTrigger ? !value : true))} />
+        )}
+        <View style={FILL} pointerEvents="box-none">
+          {children({ open, close: () => setOpen(false) })}
+        </View>
+      </View>
+    </PhoneFrame>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: { flex: 1, alignSelf: 'stretch', alignItems: 'center', justifyContent: 'center' },
+});

package/native/catalog/PhoneScreen.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { ScrollView, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+
+/**
+ * A whole app screen inside a `PhoneFrame`: `header` pinned to the top, `footer` to the bottom,
+ * and the children in a body between them that scrolls instead of pushing the footer off the
+ * device. `floating` is a layer over the top of the screen for toasts; it adds no inset of its
+ * own, so the app positions its content. `bodyWrapper` lets the app put its own surface or
+ * context provider around the scrolling body; give its root `flex: 1, minHeight: 0`.
+ */
+export function PhoneScreen({
+  header,
+  footer,
+  floating,
+  bodyWrapper,
+  scroll = true,
+  contentContainerStyle,
+  children,
+}: {
+  header?: React.ReactNode;
+  footer?: React.ReactNode;
+  floating?: React.ReactNode;
+  bodyWrapper?: (body: React.ReactNode) => React.ReactNode;
+  /** Scroll the body (default), or lay it out to fit. */
+  scroll?: boolean;
+  contentContainerStyle?: StyleProp<ViewStyle>;
+  children?: React.ReactNode;
+}) {
+  const body = scroll ? (
+    <ScrollView style={styles.flex} contentContainerStyle={contentContainerStyle}>{children}</ScrollView>
+  ) : (
+    <View style={[styles.flex, contentContainerStyle]}>{children}</View>
+  );
+  return (
+    <View style={styles.screen}>
+      {header}
+      <View style={styles.flex}>{bodyWrapper ? bodyWrapper(body) : body}</View>
+      {footer}
+      {floating ? (
+        <View style={styles.floating} pointerEvents="box-none">{floating}</View>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Fills the device; `minHeight: 0` lets a flex child shrink below its content on the web.
+  screen: { flex: 1, alignSelf: 'stretch', minHeight: 0 },
+  flex: { flex: 1, minHeight: 0 },
+  floating: { position: 'absolute', top: 0, left: 0, right: 0, zIndex: 20 },
+});

package/native/catalog/SectionBlock.tsx

@@ -9,7 +9,7 @@ import { SpecimenSurface } from './SpecimenSurface';
 import { SpecimenAddressProvider } from './SpecimenAddress';
 import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import { TokenSections } from './TokenLayouts';
-import { MATRIX_LAYOUT, choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
+import { MATRIX_LAYOUT, PREVIEW_CARD_CHROME, blockMinWidth, choosePlacement, presentationBlocks, type PlacementBlock, type PresentationBlock } from './comparison';
 import type { PreviewWidths, SectionDef, SpecimenSurfaceKind } from './types';
 
 // Matches a quoted-string-literal union type, e.g. "'primary' | 'secondary' | 'tertiary'" — anything
@@ -184,7 +184,7 @@ function BlockContent<TId extends string>({ block, def, surface }: { block: Pres
         </SpecimenAddressProvider>
       ) : null;
     case 'tokenSections':
-      return <TokenSections sections={block.sections} columns={block.columns} />;
+      return <TokenSections sections={block.sections} columns={block.columns} label={def.id} />;
     default:
       return (
         <View style={styles.previewCard}>
@@ -195,8 +195,13 @@ function BlockContent<TId extends string>({ block, def, surface }: { block: Pres
 }
 
 /** 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, block.maxColumns).containerWidth : available;
+
+
+/** What `choosePlacement` needs about a block: how narrow it can get, and (for a list) the geometry
+ *  that predicts its height in half a row. */
+function placementBlock(block: PresentationBlock, height: number): PlacementBlock {
+  const base = { kind: block.kind, height, minWidth: blockMinWidth(block) };
+  return block.kind === 'list' ? { ...base, itemCount: block.items.length, size: block.size, maxColumns: block.maxColumns } : base;
 }
 
 /**
@@ -236,10 +241,8 @@ function Blocks<TId extends string>({ blocks, def, surface }: { blocks: Presenta
     const decision = choosePlacement({
       available,
       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, maxColumns: second.maxColumns }
-        : { kind: second.kind, height: heights[1] },
+      first: placementBlock(first, heights[0]),
+      second: placementBlock(second, heights[1]),
     });
     if (decision === 'side') setPlacement('side');
   }, [available, blocks, heights, placement]);
@@ -251,7 +254,8 @@ function Blocks<TId extends string>({ blocks, def, surface }: { blocks: Presenta
         <View
           key={block.title || block.kind}
           onLayout={onBlockLayout(i)}
-          style={side ? (i === 0 ? { width: blockWidth(block, available), flexShrink: 0 } : styles.blockFill) : undefined}
+          // Side by side, each block fills its own half: a card always fills the column it is given.
+          style={side ? styles.blockFill : undefined}
         >
           {block.title ? <Text style={styles.blockLabel}>{block.title}</Text> : null}
           <BlockContent block={block} def={def} surface={surface} />
@@ -394,10 +398,11 @@ const styles = StyleSheet.create({
   },
   previewCard: {
     backgroundColor: CATALOG_COLOR.surface,
-    borderWidth: 1,
+    // From comparison.ts, which adds the same numbers to a preview's minimum width.
+    borderWidth: PREVIEW_CARD_CHROME.border,
     borderColor: CATALOG_COLOR.borderStrong,
     borderRadius: CATALOG_RADIUS.card,
-    padding: CATALOG_SPACE.xl,
+    padding: PREVIEW_CARD_CHROME.padding,
     gap: CATALOG_SPACE.md,
   },
   // `ComparisonList`'s own card/caption tokens, reused so a 'table' preview reads as the same shared

package/native/catalog/SpecimenSurface.tsx

@@ -3,7 +3,7 @@ import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
 import { CATALOG_COLOR } from './tokens';
 import {
   DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE, overflowsCell, paintedExtent, shouldCenterFilledContent, specimenContentAlignItems,
-  specimenContentBoundedStyle, visibleBoxes, type LayoutBox,
+  specimenContentBoundedStyle, visibleBoxes, filledContentStyle, type LayoutBox,
 } from './specimenSurfaceStyle';
 import { useSpecimenAddress } from './SpecimenAddress';
 import { blendsIntoCell, measurePaintedBoxes } from './specimenFill';
@@ -115,7 +115,7 @@ function readTree(root: MeasurableNode, browser: Browser): LayoutBox {
   return read(root);
 }
 
-export function SpecimenContent({ fill, align, children }: { fill?: boolean; align?: SpecimenAlign; children: React.ReactNode }) {
+export function SpecimenContent({ fill, align, capped = true, children }: { fill?: boolean; align?: SpecimenAlign; /** Phone-width cap for a filled example; off for page-width cells. */ capped?: boolean; children: React.ReactNode }) {
   // After layout (browser only): a `fill` example whose visible content is narrower than the cell
   // (a fixed-width skeleton, a tooltip around a small trigger) is centred instead of sitting
   // against the leading edge; an explicit `align` always wins. And in development, an example
@@ -134,13 +134,13 @@ export function SpecimenContent({ fill, align, children }: { fill?: boolean; ali
     if ((globalThis as { __DEV__?: boolean }).__DEV__ && !warned.current && overflowsCell(visible, wrapperWidth)) {
       warned.current = true;
       console.warn(
-        `[Catalog] ${address ? `${address.pageId} (${address.itemKey})` : 'An example'} is ${Math.round(visible)}px wide in a ${Math.round(wrapperWidth)}px cell, so it's cut off. Give the page a wider specimenSize ('regular' or 'wide').`,
+        `[Catalog] ${address ? `${address.pageId} (${address.itemKey})` : 'An example'} is ${Math.round(visible)}px wide in a ${Math.round(wrapperWidth)}px cell, so it's cut off. Give the page a wider specimenSize ('regular', 'wide', or 'page' for components wider than a phone).`,
       );
     }
   }, [fill, align, centerNarrow, address]);
   if (fill) {
     const alignItems = centerNarrow ? 'center' : specimenContentAlignItems(fill, align);
-    return <View ref={ref} onLayout={measure} style={[SPECIMEN_SURFACE_WIDTH_STYLE, { alignItems }]}>{children}</View>;
+    return <View ref={ref} onLayout={measure} style={[SPECIMEN_SURFACE_WIDTH_STYLE, filledContentStyle(capped), { alignItems }]}>{children}</View>;
   }
   return <View ref={ref} onLayout={measure} style={specimenContentBoundedStyle(align)}>{children}</View>;
 }

package/native/catalog/TokenLayouts.tsx

@@ -1,7 +1,7 @@
-import React, { useState } from 'react';
+import React, { useRef, 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 { sectionColumns, tileGeometry, TOKEN_LAYOUT_GAP, TOKEN_SECTION_MIN_WIDTH } from './tokenLayout';
 import type { TokenSection } from './types';
 
 /** Measures its own width; renders nothing inside until the width is known. */
@@ -18,9 +18,20 @@ function useWidth(): [number, (event: LayoutChangeEvent) => void] {
  * 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 }) {
+export function TokenSections({ sections, columns, label }: { sections: TokenSection[]; columns: 1 | 2 | 3; label?: string }) {
   const [width, onLayout] = useWidth();
   const perRow = sectionColumns(width, columns);
+  // Degrading quietly is how a page ends up claiming a column count it never renders: the author
+  // reads `columns={3}`, the reader sees one column, and nothing says the space was the reason.
+  // Once per transition, not once per render: a resize re-renders continuously.
+  const warned = useRef('');
+  if (width > 0 && perRow < columns && (globalThis as { __DEV__?: boolean }).__DEV__) {
+    const key = `${columns}:${perRow}`;
+    if (warned.current !== key) {
+      warned.current = key;
+      console.warn(`[Catalog] ${label ?? 'TokenSections'}: asked for ${columns} columns but only ${perRow} fit in ${width}px; sections never go below ${TOKEN_SECTION_MIN_WIDTH}px.`);
+    }
+  }
   const columnWidth = perRow === 1 ? width : (width - TOKEN_LAYOUT_GAP * (perRow - 1)) / perRow;
   return (
     <View onLayout={onLayout} style={styles.sections}>

package/native/catalog/UpdatePanel.tsx

@@ -663,8 +663,8 @@ const styles = StyleSheet.create({
     paddingVertical: 2,
   },
   versionsRow: { flexDirection: 'row', alignItems: 'center', gap: 10 },
-  versionsText: { fontSize: 22, fontWeight: '800', color: CATALOG_COLOR.text },
-  arrow: { fontSize: 22, color: CATALOG_COLOR.textMuted },
+  versionsText: { fontSize: CATALOG_TYPE['2xl'], fontWeight: '800', color: CATALOG_COLOR.text },
+  arrow: { fontSize: CATALOG_TYPE['2xl'], color: CATALOG_COLOR.textMuted },
   pill: { paddingHorizontal: 8, paddingVertical: 2, borderRadius: 10, backgroundColor: CATALOG_COLOR.accentSubtle },
   pillMajor: { backgroundColor: CATALOG_COLOR.warningSubtle },
   pillSuccess: { backgroundColor: CATALOG_COLOR.successSubtle },
@@ -714,10 +714,10 @@ const styles = StyleSheet.create({
   stepIconNow: { borderWidth: 2, borderColor: CATALOG_COLOR.accent },
   stepIconTodo: { borderWidth: 2, borderColor: CATALOG_COLOR.borderStrong },
   stepIconFail: { backgroundColor: CATALOG_COLOR.dangerSubtle },
-  stepIconGlyph: { fontSize: 12, fontWeight: '800', color: CATALOG_COLOR.text },
+  stepIconGlyph: { fontSize: CATALOG_TYPE.sm, fontWeight: '800', color: CATALOG_COLOR.text },
   stepLabel: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted },
   stepLabelNow: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text, fontWeight: '700' },
   stepLabelFail: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text, fontWeight: '700' },
   logBox: { backgroundColor: '#1d1d1f', borderRadius: CATALOG_RADIUS.md, padding: 12, marginTop: 8, maxHeight: 240 },
-  logText: { color: '#e8e8e8', fontSize: 12, fontFamily: 'Menlo, monospace' },
+  logText: { color: '#e8e8e8', fontSize: CATALOG_TYPE.sm, fontFamily: 'Menlo, monospace' },
 });