@krapwoo/ds-viewer 0.5.0 → 0.6.1

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/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
@@ -130,17 +130,21 @@ export function SpecimenContent({ fill, align, children }: { fill?: boolean; ali
     if (!browser.Element || !browser.getComputedStyle || !node?.getBoundingClientRect) return;
     const wrapperWidth = node.getBoundingClientRect().width;
     const visible = paintedExtent(visibleBoxes(readTree(node, browser)));
-    if (fill && align === undefined && !centerNarrow && shouldCenterFilledContent(visible, wrapperWidth)) setCenterNarrow(true);
+    // Only for a phone-width cell. Centring exists for a small control adrift in a wide cell (a
+    // tooltip, a fixed-width skeleton); a 'page' cell holds a layout, whose own content is
+    // supposed to sit at the left of its own measure, and centring it collapses it to the width of
+    // whatever it happens to have painted.
+    if (capped && fill && align === undefined && !centerNarrow && shouldCenterFilledContent(visible, wrapperWidth)) setCenterNarrow(true);
     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]);
+  }, [capped, 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

@@ -1,9 +1,10 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
-import { ActivityIndicator, Platform, Pressable, ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
+import { Platform, Pressable, ScrollView, StyleSheet, Switch, Text, View } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { CatalogButton } from './CatalogButton';
 import { DS_VIEWER_SECRET_HEADER } from './catalogNavigation';
 import {
-  autoCheckHelp, bumpLabel, checkedAgoLabel, resultNote, daysAgoLabel, isAlreadyUpToDateError, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
+  autoCheckHelp, bumpLabel, checkedAgoLabel, resultNote, daysAgoLabel, isAlreadyUpToDateError, isRemoteOrigin, resolvePanelPhase, versionOverview, type UpdatePlanView, type UpdateStatusView,
 } from './updatePanelState';
 import type { UpdateNotice, VersionStatus } from './types';
 
@@ -11,6 +12,13 @@ function isWeb(): boolean {
   return Platform.OS === 'web' && typeof window !== 'undefined';
 }
 
+/** The page is open from somewhere other than the machine running the viewer, so every action will
+ *  be refused however healthy the server is — see `isRemoteOrigin`. */
+function remoteOrigin(endpoint: Endpoint | undefined): boolean {
+  if (!endpoint || !isWeb()) return false;
+  return isRemoteOrigin(window.location.protocol, window.location.hostname);
+}
+
 type Endpoint = { baseUrl: string; secret: string };
 
 async function authedFetch(endpoint: Endpoint, path: string, init: RequestInit = {}): Promise<Response> {
@@ -225,7 +233,12 @@ function VersionDetails({
       setJustChecked(next.lastOutcome === 'ok' && !next.update);
       onStatus(next);
     } catch {
-      setLocalError('Couldn’t reach the viewer’s local server. If this keeps happening, restart npx ds-viewer dev.');
+      setLocalError(remoteOrigin(endpoint)
+        // The endpoint only answers its own origin, and it can install packages and restart the
+        // server — so saying "restart the viewer" here would send the reader after a fault that
+        // isn't there. The page itself is fine over a tunnel; only its actions are local.
+        ? 'This page is open from another address, and the viewer only takes actions from the machine it runs on. Open the catalog on that machine, or run npx ds-viewer update there.'
+        : 'Couldn’t reach the viewer’s local server. If this keeps happening, restart npx ds-viewer dev.');
     } finally {
       setChecking(false);
     }
@@ -304,18 +317,12 @@ function VersionDetails({
       {localError && <NoteBox variant="err">{localError}</NoteBox>}
       {live && (
         <View style={styles.actions}>
-          <Pressable
+          <CatalogButton
+            variant="secondary"
+            busy={checking}
             onPress={checkNow}
-            disabled={checking}
-            accessibilityRole="button"
-            accessibilityState={{ disabled: checking, busy: checking }}
-            style={[styles.secondaryButton, styles.buttonRow, checking && styles.busyButton]}
-          >
-            {checking && <ActivityIndicator size="small" color={CATALOG_COLOR.textMuted} />}
-            <Text style={[styles.secondaryButtonText, checking && styles.busyButtonText]}>
-              {checking ? 'Checking…' : overview.action === 'retry' ? 'Try again' : 'Check now'}
-            </Text>
-          </Pressable>
+            label={checking ? 'Checking…' : overview.action === 'retry' ? 'Try again' : 'Check now'}
+          />
           {unreachable && !checking && <Text style={styles.muted}>or run <Code>npm view @krapwoo/ds-viewer version</Code></Text>}
         </View>
       )}
@@ -504,15 +511,7 @@ export function UpdatePanel({
           <Text style={styles.muted}>Not a git repository, so uncommitted changes couldn’t be checked.</Text>
         )}
         <View style={styles.actions}>
-          <Pressable
-            onPress={startUpdate}
-            disabled={starting}
-            accessibilityRole="button"
-            accessibilityState={{ disabled: starting }}
-            style={[styles.primaryButton, starting && styles.disabledButton]}
-          >
-            <Text style={[styles.primaryButtonText, starting && styles.disabledButtonText]}>Update now</Text>
-          </Pressable>
+          <CatalogButton label="Update now" onPress={startUpdate} disabled={starting} />
           {starting ? <Text style={styles.muted}>Starting…</Text> : <Text style={styles.muted}>or run <Code>npx ds-viewer update</Code></Text>}
         </View>
       </>
@@ -542,17 +541,8 @@ export function UpdatePanel({
         </NoteBox>
         <FilesList files={plan.files} />
         <View style={styles.actions}>
-          <Pressable
-            disabled
-            accessibilityRole="button"
-            accessibilityState={{ disabled: true }}
-            style={[styles.primaryButton, styles.disabledButton]}
-          >
-            <Text style={[styles.primaryButtonText, styles.disabledButtonText]}>Update now</Text>
-          </Pressable>
-          <Pressable onPress={fetchPlan} accessibilityRole="button" style={styles.secondaryButton}>
-            <Text style={styles.secondaryButtonText}>Check again</Text>
-          </Pressable>
+          <CatalogButton label="Update now" disabled />
+          <CatalogButton label="Check again" variant="secondary" onPress={fetchPlan} />
         </View>
       </>
     );
@@ -570,9 +560,7 @@ export function UpdatePanel({
           {' You may be offline, or npm didn’t respond. Nothing was changed.'}
         </NoteBox>
         <View style={styles.actions}>
-          <Pressable onPress={fetchPlan} accessibilityRole="button" style={styles.secondaryButton}>
-            <Text style={styles.secondaryButtonText}>Try again</Text>
-          </Pressable>
+          <CatalogButton label="Try again" variant="secondary" onPress={fetchPlan} />
           <Text style={styles.muted}>or run <Code>npx ds-viewer update</Code></Text>
         </View>
       </>
@@ -663,8 +651,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 },
@@ -681,9 +669,6 @@ const styles = StyleSheet.create({
   switchLabel: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
   switch: { width: 44, height: 26 },
   switchHelp: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
-  buttonRow: { flexDirection: 'row', gap: CATALOG_SPACE.sm },
-  busyButton: { borderColor: CATALOG_COLOR.border },
-  busyButtonText: { color: CATALOG_COLOR.textMuted },
   muted: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 4 },
   block: { marginTop: 18 },
   h3: { fontSize: CATALOG_TYPE.panelHeading, textTransform: 'uppercase', letterSpacing: 0.5, color: CATALOG_COLOR.text, marginBottom: 8 },
@@ -695,12 +680,6 @@ const styles = StyleSheet.create({
   fileReason: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
   fileReasonDirty: { color: CATALOG_COLOR.warning, fontWeight: '700' },
   actions: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md, marginTop: 20 },
-  primaryButton: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: 22, backgroundColor: CATALOG_COLOR.text, alignItems: 'center', justifyContent: 'center' },
-  primaryButtonText: { color: '#fff', fontWeight: '700', fontSize: CATALOG_TYPE.md },
-  secondaryButton: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: 22, borderWidth: 1, borderColor: CATALOG_COLOR.borderStrong, alignItems: 'center', justifyContent: 'center' },
-  secondaryButtonText: { fontWeight: '700', fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text },
-  disabledButton: { backgroundColor: '#e6e6e6', borderColor: '#e6e6e6' },
-  disabledButtonText: { color: '#8a8a8a' },
   noteBox: { borderRadius: CATALOG_RADIUS.md, padding: 12, marginTop: 18 },
   noteBoxText: { fontSize: CATALOG_TYPE.md },
   noteBoxBold: { fontWeight: '700' },
@@ -714,10 +693,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' },
 });