@krapwoo/ds-viewer 0.5.0 → 0.6.1

package/README.md

@@ -175,13 +175,18 @@ when the card is too narrow even for two. The specimens use one of four layouts:
 - **Preview** — `render()` content. Component previews render at phone width (402px), optionally
   with more widths such as a 320px small phone; token galleries and catalog chrome stay full width.
 
-When a page has two blocks, the catalog places them side by side if that makes the page at least
-120px shorter (e.g. Dropdown), and stacks them otherwise. A block with nothing to show is omitted.
-
-Grid columns and list cells are at most 402px wide with 16px padding. A page's `specimenSize`
-(`compact` 160px, `regular` 240px, `wide` 402px) sets the minimum width; full-width (`itemsFill`)
-slots default to `wide`. The catalog's own look comes from `native/catalog/tokens.ts`, never from
-the host app's tokens.
+When a page has two blocks, the catalog places them side by side — the row split into two equal
+columns, each block filling its own — if both keep their minimum width there and it makes the page
+at least 120px shorter (e.g. Dropdown); otherwise they stack, each filling the whole row. A block
+with nothing to show is omitted.
+
+Every card fills the column it is given, and its columns or cells share that width equally: a
+two-column grid is as wide as a five-column one, and a two-item list is as wide as a six-item one.
+Phone width (402px, 370px of content) caps the specimen inside a cell, not the cell. A page's
+`specimenSize` (`compact` 160px, `regular` 240px, `wide` 402px) sets the minimum column width — a
+card narrower than its minimum scrolls inside itself rather than squeezing its cells. Full-width
+(`itemsFill`) slots default to `wide`. The catalog's own look comes from `native/catalog/tokens.ts`,
+never from the host app's tokens.
 
 ## Adding a component (the recipe)
 
@@ -201,7 +206,9 @@ actually apply:
   combination does not exist. Never multiply `variants` by `states` to fill it. Keep the column axis
   within what fits a 1280px laptop: 5 compact, 3 regular, or 2 wide columns. `states` items whose
   key matches a row or column key are not repeated below the grid.
-- `specimenSize: 'compact' | 'regular' | 'wide'` — the page's specimen width class.
+- `specimenSize: 'compact' | 'regular' | 'wide' | 'page'` — the page's specimen width class. `'page'`
+  is for components wider than a phone (a whole screen layout, a catalog page): cells are at least
+  512px and share the row, with no 402px cap.
 - `specimenSurface: 'auto' | 'neutral' | 'white' | 'dark' | 'transparent'` — the fill of each
   example's cell (list, grouped and grid cells, and a non-token `render()` preview). Defaults to
   `'auto'`: after the page draws, a cell turns light gray only when its own example would vanish
@@ -481,6 +488,17 @@ Button
     or `x`/`onXChange`) but every example that renders it passes a fixed value with no working
     callback. Add `intentionalStaticPreview: { reason: '...' }` to the page to suppress it when the
     static examples are deliberate.
+  - `preview-only-component-page` — a component page's only examples are a free-form `render()`
+    preview, so nothing is named and the checks above have no example to read. Give the page
+    `variants` (and `states`, where they differ) naming each real configuration. Token galleries
+    and a declared `intentionalStaticPreview` are exempt; `render()` stays right for a token
+    gallery or a whole-page layout.
+  - `internal-prop-unknown` — `internalProps` names something that is not a prop of the component,
+    so the exemption it was written for is not in effect. Correct the spelling or delete the entry.
+  A page's `internalProps: { size: 'why' }` exempts a named prop from `option-not-covered` — for
+  plumbing a parent passes (a layout size, an internal surface kind) rather than a value the
+  reader picks. It needs a reason per prop, so the exemption is a visible declaration in the page;
+  when the reader really does choose the value, tag an example with `props` instead.
   The analyzer follows supported aliases and resolved exports, but uncertain wrappers or
   dynamically-constructed references remain uncheckable rather than being guessed at. A
   declared `intentionalStaticPreview` is taken as the author's own call, not independently
@@ -498,6 +516,11 @@ and adds what only a real render shows:
 - `render-error` / `render-no-heading` (errors): a console error, or a page that didn't render.
 - `render-layout` (warning): an example wider than its cell (the viewer's own check), with the
   page and file. `render-catalog-warning` (warning): any other `[Catalog]` warning, reported once.
+- `identical-variants` (warning): two examples in the same card whose specimens render identically,
+  so the difference their names claim isn't visible — usually a cell too narrow to show it, or a
+  prop that was never wired up. The fingerprint reads each specimen's whole subtree (including a
+  PhoneFrame's child document and a field's value) but not the caption carrying the variant's own
+  name, so two examples differing only in colour are not reported.
 - `render-unavailable` / `render-failed` (errors): no browser, or the catalog didn't start.
 
 It needs `puppeteer` in your project (`npm install --save-dev puppeteer`); ds-viewer doesn't

package/dist/cli/doctor.js

@@ -279,6 +279,22 @@ function findControlledPair(component) {
  *   - no example directly renders the component at all, or any direct example's value/callback is
  *     `'unknown'` — genuinely uncheckable, and "uncheckable" must never be reported as "inert".
  *  Never a newly-fatal gate: always a warning, same as every other advisory in this file. */
+/** A component page whose only examples are a free-form `render()` preview: nothing is named, so
+ *  the reader sees one picture instead of the component's real variants and states, and several
+ *  other rules here (`missing-working-preview`, the option-coverage rules) are skipped because
+ *  they have no named example to read. A token gallery is exempt — raw token data has no variants
+ *  — and so is a page that says `intentionalStaticPreview` with a reason. */
+function checkPreviewOnlyPages(pages) {
+    return pages
+        .filter((page) => page.component !== undefined && page.checkable && page.hasRender === true && !page.tokenGallery
+        && !page.intentionalStaticPreviewReason
+        && !page.comparison && !page.variantsItems?.length && !page.statesItems?.length && !page.tokenSectionTitles?.length)
+        .map((page) => issue({
+        id: 'preview-only-component-page', severity: 'warning', ...pageRef(page),
+        message: `"${page.component}" is documented by a render() preview alone, with no named variants, states or comparison.`,
+        fix: 'Give the page variants (and states, where they differ) naming each real configuration, so every example has a caption and the other checks can read them. Keep render() for token galleries and whole-page layouts.',
+    }));
+}
 function checkMissingWorkingPreview(pages, components) {
     const componentsByName = new Map(components.map((c) => [c.name, c]));
     const issues = [];
@@ -409,8 +425,25 @@ function checkComponentPages(pages, components) {
                 }));
             }
         }
+        // Props the page declares as plumbing the reader never picks (with a reason) are not expected
+        // to have an example per option; see `internalProps`.
+        const internalProps = new Set(page.internalProps ?? []);
+        // A misspelled key silently exempts nothing, so the author sees the warnings it was meant to
+        // settle and no reason why — the same reasoning as propNotes' own key check.
+        for (const name of internalProps) {
+            // `component.props` deliberately omits a node_modules-declared prop (cli/props.ts), so an
+            // inherited name such as `autoCapitalize` is expected to be absent rather than misspelled —
+            // the same exemption the tagged-item check above makes.
+            if (!propsByName.has(name) && component.inheritedFrom.length === 0) {
+                issues.push(issue({
+                    id: 'internal-prop-unknown', severity: 'warning', ...ref,
+                    message: `internalProps names "${name}", which is not a prop of ${component.name}.`,
+                    fix: `Correct the spelling, or delete the "${name}" entry — it exempts nothing as written.`,
+                }));
+            }
+        }
         for (const prop of component.props) {
-            if (!prop.options)
+            if (!prop.options || internalProps.has(prop.name))
                 continue;
             const covered = new Set();
             if (page.comparison) {
@@ -456,10 +489,15 @@ function checkComponentPages(pages, components) {
                 fix: 'Add a one-sentence whenToUse note disambiguating this component from its closest look-alike(s), or omit it only when there genuinely is none.',
             }));
         }
-        if (!page.tokenGallery && page.hasA11y === false && !page.hidesAccessibility) {
+        // `hide: { accessibility: true }` is a display choice, not an exemption from documenting the
+        // component: hiding the section only removes the visible placeholder, so without this the gap
+        // becomes invisible to both the reader and the doctor.
+        if (!page.tokenGallery && page.hasA11y === false) {
             issues.push(issue({
                 id: 'missing-guidance-or-a11y', severity: 'warning', ...ref,
-                message: 'No "a11y" notes documented.',
+                message: page.hidesAccessibility
+                    ? 'No "a11y" notes documented, and the page hides the accessibility section.'
+                    : 'No "a11y" notes documented.',
                 fix: 'Add a one-sentence a11y note, grounded in the component\'s real behavior — even "no explicit handling beyond defaults" is better than leaving it blank.',
             }));
         }
@@ -480,6 +518,7 @@ export function collectIssues(pages, components) {
         ...checkComponentPages(pages, components),
         ...checkMissingComposition(pages, components),
         ...checkMissingWorkingPreview(pages, components),
+        ...checkPreviewOnlyPages(pages),
     ];
 }
 /** Issues that aren't tied to one page: `sync`'s own "Could not read" warnings, and a configured

package/dist/cli/explain.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { readStaticPages } from "./staticPage.js";
 import { discoverAllPageFiles, resolvePageId } from "./pageIndex.js";
 import { resolveGlob } from "./glob.js";
-import { axisItems, choosePlacement, gridColumnLimit, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
+import { axisItems, blockMinWidth, choosePlacement, gridColumnLimit, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
 import { CATALOG_LAYOUT } from "../native/catalog/tokens.js";
 import { sectionColumns } from "../native/catalog/tokenLayout.js";
 function placeholderItem(item) {
@@ -113,23 +113,14 @@ function explainBlock(block) {
     }
     return { kind: 'empty', title: block.title, reason: block.message };
 }
-/** Mirrors `native/catalog/SectionBlock.tsx`'s own `blockWidth` helper: a list block's width is its
- *  own natural, content-hugging width (`listGeometry`'s `containerWidth`) — the real viewer only
- *  ever moves a *second* block beside a *first* one when that first block doesn't already fill the
- *  whole row, so `choosePlacement` only reads `first.width` (never `second.width`) — but it's
- *  computed uniformly here for either role, since setting it on `second` is simply unused, not wrong. */
-function toPlacementBlock(block, height, available) {
-    if (block.kind === 'list') {
-        return {
-            kind: 'list',
-            height,
-            itemCount: block.items.length,
-            size: block.size,
-            maxColumns: block.maxColumns,
-            width: listGeometry(block.items.length, available, block.size, block.maxColumns).containerWidth,
-        };
-    }
-    return { kind: block.kind, height };
+/** Mirrors `native/catalog/SectionBlock.tsx`'s own `placementBlock` helper: side by side splits the
+ *  row in two and each block fills its half, so the decision needs each block's narrowest width
+ *  plus, for a list, the geometry that predicts its height in half a row. */
+function toPlacementBlock(block, height) {
+    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;
 }
 /** Finds `pageId` among every page `cli/doctor.ts`'s own `discoverAllPageFiles` would find, builds
  *  its throwaway `SectionDef`, and asks the viewer's own pure layout functions for each block's
@@ -163,8 +154,8 @@ export function explainPage(config, pageId, options = {}) {
             const decision = choosePlacement({
                 available: MATRIX_LAYOUT.laptopContentWidth,
                 gap: CATALOG_LAYOUT.blockGap,
-                first: toPlacementBlock(blocks[0], firstHeight, MATRIX_LAYOUT.laptopContentWidth),
-                second: toPlacementBlock(blocks[1], secondHeight, MATRIX_LAYOUT.laptopContentWidth),
+                first: toPlacementBlock(blocks[0], firstHeight),
+                second: toPlacementBlock(blocks[1], secondHeight),
             });
             placement = {
                 decision,

package/dist/cli/render.js

@@ -40,6 +40,85 @@ export function issuesFromPage(page, messages, hasHeading, seen = new Set()) {
     }
     return issues;
 }
+/**
+ * Runs in the browser: finds any two examples in the same list card whose specimens render
+ * identically. A variant's name is a claim that something differs; two cells that render the same
+ * teach the reader nothing and usually mean the difference needs a wider cell (a column count in a
+ * cell too narrow to show it) or was never wired up.
+ *
+ * The fingerprint covers each specimen's whole subtree — tag, box size, colours, radius and text —
+ * but never the caption strip that carries the variant's own name, which always differs. Colour is
+ * part of it, so a "default vs disabled" pair that differs only in tone is not reported.
+ */
+export const IDENTICAL_VARIANTS_SCRIPT = `(() => {
+  const doc = document;
+  const fingerprint = (root) => {
+    const out = [];
+    const base = root.getBoundingClientRect();
+    const walk = (el) => {
+      // PhoneFrame renders its example into a same-origin child document, so without reaching in
+      // every phone looks like an identical empty box.
+      if (el.tagName === 'IFRAME') {
+        try {
+          const body = el.contentDocument && el.contentDocument.body;
+          if (body) { out.push('IFRAME'); walk(body); return; }
+        } catch (error) { out.push('IFRAME|unreadable'); return; }
+      }
+      const box = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      out.push([
+        el.tagName,
+        Math.round(box.width), Math.round(box.height),
+        Math.round(box.left - base.left), Math.round(box.top - base.top),
+        style.color, style.backgroundColor, style.borderColor, style.borderRadius,
+        style.fontSize, style.fontWeight, style.opacity, style.visibility,
+        // An icon page's variants are same-sized SVGs that differ only in geometry; a card page's
+        // in shadow; a text page's in style, decoration or alignment.
+        style.fill, style.stroke, style.boxShadow, style.fontStyle, style.textDecorationLine, style.textAlign,
+        el.getAttribute && (el.getAttribute('d') || el.getAttribute('points') || ''),
+        el.currentSrc || (el.getAttribute && el.getAttribute('src')) || '',
+        el.children.length === 0 ? (el.textContent || '') : '',
+        // A field's visible text is its value, not its textContent, which is always empty.
+        el.value === undefined ? '' : String(el.value),
+        el.placeholder || '', el.disabled ? 'disabled' : '',
+      ].join('|'));
+      for (const child of el.children) walk(child);
+    };
+    walk(root);
+    return out.join('\\n');
+  };
+  const pairs = [];
+  for (const card of doc.querySelectorAll('[role=list][aria-label]')) {
+    // ComparisonList and ComparisonGroups label their card "<page id>: <block title>". Anything
+    // else with role=list is a consumer's own component inside a specimen, not a card of examples.
+    if (!/^[^:]+: .+/.test(card.getAttribute('aria-label') || '')) continue;
+    const cells = [...card.querySelectorAll('[role=listitem]')].filter((c) => c.closest('[role=list]') === card);
+    const byPrint = new Map();
+    for (const cell of cells) {
+      // children[0] is the caption strip (the variant's own name); the specimen follows it.
+      const specimen = cell.children.length > 1 ? cell.children[1] : cell.children[0];
+      if (!specimen) continue;
+      const name = (cell.children[0] ? cell.children[0].textContent : '') || '';
+      const print = fingerprint(specimen);
+      if (!print.trim()) continue;
+      const first = byPrint.get(print);
+      if (first === undefined) byPrint.set(print, name);
+      else pairs.push({ card: card.getAttribute('aria-label') || '', names: [first, name] });
+    }
+  }
+  return pairs;
+})()`;
+/** Turns the browser's findings into doctor issues, one per identical pair. */
+export function identicalVariantIssues(page, pairs) {
+    const ref = { page: page.id, ...(page.file ? { file: page.file } : {}) };
+    return pairs.map((pair) => ({
+        id: 'identical-variants',
+        severity: 'warning',
+        ...ref,
+        message: `"${pair.names[0]}" and "${pair.names[1]}" render identically in ${pair.card || 'the same card'}.`,
+        fix: "Make the difference visible — a wider specimenSize when the cell is too narrow to show it, or the prop the name claims — or drop one of the two examples.",
+    }));
+}
 /** The project's own puppeteer, or `undefined` when it isn't installed. */
 export function loadProjectPuppeteer(projectRoot) {
     try {
@@ -221,6 +300,18 @@ export async function renderCheck(projectRoot, options = {}) {
                     return Boolean(doc.querySelector('[role="heading"]')?.textContent?.trim());
                 });
                 issues.push(...issuesFromPage({ id, file: options.files?.get(id) }, messages, hasHeading, seen));
+                // Advisory: a script failure (a detached child document mid-navigation, an element whose
+                // `value` getter throws) must not become this page's render-error, so it has its own catch
+                // rather than falling into the one below.
+                let identical;
+                try {
+                    identical = (await page.evaluate(IDENTICAL_VARIANTS_SCRIPT));
+                }
+                catch {
+                    identical = undefined;
+                }
+                if (Array.isArray(identical))
+                    issues.push(...identicalVariantIssues({ id, file: options.files?.get(id) }, identical));
                 await page.close();
             }
             catch (error) {

package/dist/cli/staticPage.js

@@ -170,6 +170,23 @@ function readStaticPage(file) {
                 page.intentionalStaticPreviewReason = stringLiteral(resolve(reasonProp.initializer, consts, new Set()));
         }
     }
+    const internalPropsProp = findProp(pageObject, 'internalProps');
+    if (internalPropsProp) {
+        const resolved = resolve(internalPropsProp.initializer, consts, new Set());
+        if (ts.isObjectLiteralExpression(resolved)) {
+            const names = [];
+            for (const prop of resolved.properties) {
+                if (!ts.isPropertyAssignment(prop))
+                    continue;
+                const name = ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name) ? prop.name.text : undefined;
+                const reason = stringLiteral(resolve(prop.initializer, consts, new Set()));
+                if (name && reason)
+                    names.push(name);
+            }
+            if (names.length > 0)
+                page.internalProps = names;
+        }
+    }
     return page;
 }
 /** A literal array of `ComposedOfEntry`-shaped object literals, read down to just `component`

package/dist/native/catalog/comparison.js

@@ -2,7 +2,6 @@
  *  content width is a 1280px viewport minus the 264px sidebar and 32px side padding. */
 export const MATRIX_LAYOUT = {
     rowHeaderWidth: 120,
-    columnMaxWidth: 402,
     cellPadding: 16,
     rowMinHeight: 150,
     laptopContentWidth: 952,
@@ -21,8 +20,9 @@ export const REFERENCE_MIN_COLUMN_WIDTH = 280;
 /** Gap between reference columns (CATALOG_SPACE['2xl'], the same token the card's columns already
  *  use). */
 export const REFERENCE_COLUMN_GAP = 32;
-/** Smallest column or cell width per specimen size. Wide specimens are fixed at phone width. */
-export const COLUMN_MIN_WIDTH = { compact: 160, regular: 240, wide: 402 };
+/** Smallest column or cell width per specimen size. `wide` is phone width as a minimum, not a
+ *  maximum: cells share their container equally above it. */
+export const COLUMN_MIN_WIDTH = { compact: 160, regular: 240, wide: 402, page: 512 };
 /** `Array.isArray`'s built-in type guard narrows to a mutable `any[]`, which a `readonly T[]`
  *  union member is never assignable to — so the `else` branch of `Array.isArray(axis) ? ... :
  *  ...` keeps `axis`'s full union type instead of narrowing away the array member. This explicit
@@ -71,15 +71,15 @@ export function grid(rowLabel, columnLabel, rows, columns, cell, size) {
 export function gridColumnLimit(size) {
     return Math.floor((MATRIX_LAYOUT.laptopContentWidth - MATRIX_LAYOUT.rowHeaderWidth) / COLUMN_MIN_WIDTH[size]);
 }
-export function gridWidthBounds(columnCount, size) {
-    const n = Math.max(0, columnCount);
-    return {
-        minWidth: MATRIX_LAYOUT.rowHeaderWidth + n * COLUMN_MIN_WIDTH[size],
-        maxWidth: MATRIX_LAYOUT.rowHeaderWidth + n * MATRIX_LAYOUT.columnMaxWidth,
-    };
+/** The narrowest a grid card may be: the row header plus every column at its minimum. A card wider
+ *  than its container scrolls inside itself; above this width the columns share the container
+ *  equally, because the phone-width cap belongs to the specimen inside a cell, not to the column. */
+export function gridMinWidth(columnCount, size) {
+    return MATRIX_LAYOUT.rowHeaderWidth + Math.max(0, columnCount) * COLUMN_MIN_WIDTH[size];
 }
 /** Balanced wrapping for a one-axis list inside a single bordered card (1px outer border). Each
- *  cell's 1px divider sits inside its own width, so no cell is ever wider than 402px. Uses as few
+ *  cell's 1px divider sits inside its own width. Cells share the container equally — phone width
+ *  caps the specimen inside a cell, not the cell. Uses as few
  *  rows as fit, then spreads items evenly across them so a short last row leaves as little empty
  *  space as possible. `fillers` blank cells complete the last row. `columnCap` (from
  *  `VariantSlot.maxColumns`) only ever lowers the natural, width-based column count — a narrow
@@ -96,7 +96,7 @@ export function listGeometry(itemCount, availableWidth, size, columnCap) {
     const rows = Math.ceil(itemCount / maxColumns);
     const columns = Math.ceil(itemCount / rows);
     const fitted = Math.floor(inner / columns);
-    const cellWidth = size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : Math.max(min, Math.min(MATRIX_LAYOUT.columnMaxWidth, fitted));
+    const cellWidth = Math.max(min, fitted);
     return {
         columns,
         rows,
@@ -198,10 +198,11 @@ function slotColumnCap(slot) {
         return { maxColumns: slot.maxColumns };
     return slot.itemsFill ? { maxColumns: FILLED_SLOT_MAX_COLUMNS } : {};
 }
-function slotItems(slot, from) {
+function slotItems(slot, from, fillByDefault = false) {
     // Nullish, not `||`: an item's own explicit `fill: false` must override an inherited
     // `itemsFill: true`, which `false || slot.itemsFill` would silently discard.
-    return slot.items.map((item) => ({ key: item.key, slot: from, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill, surface: item.surface, align: item.align }));
+    // Page-width examples (layouts wider than a phone) fill their cell unless they say otherwise.
+    return slot.items.map((item) => ({ key: item.key, slot: from, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill ?? (fillByDefault || undefined), surface: item.surface, align: item.align }));
 }
 /** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
 function previewWidths(requested, fallback) {
@@ -269,12 +270,12 @@ export function presentationBlocks(def, options = {}) {
                 kind: 'list',
                 title: 'Variants',
                 size: slotSize(def, def.variants),
-                items: slotItems(def.variants, 'variants'),
+                items: slotItems(def.variants, 'variants', def.specimenSize === 'page'),
                 ...slotColumnCap(def.variants),
             });
         }
         else if (def.render) {
-            blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
+            blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths), ...(def.previewLayout ? { layout: def.previewLayout } : {}) });
         }
     }
     if (states) {
@@ -283,7 +284,7 @@ export function presentationBlocks(def, options = {}) {
             kind: 'list',
             title: secondary ? 'Other configurations' : 'States / configurations',
             size: slotSize(def, states),
-            items: slotItems(states, 'states'),
+            items: slotItems(states, 'states', def.specimenSize === 'page'),
             ...slotColumnCap(states),
         });
     }
@@ -292,23 +293,61 @@ export function presentationBlocks(def, options = {}) {
     }
     return blocks;
 }
-/** Side by side or stacked, for a page with exactly two blocks. Tries both and keeps the shorter;
- *  stays stacked unless side by side saves at least PLACEMENT_MIN_SAVING. Only a list can move
- *  beside a first block that hugs its content, and only when its cells keep their minimum width. */
+/** The narrowest a block renders at. Every card fills the column it is given, so this is a floor,
+ *  not the width it will take: below it a grid scrolls inside itself and a list would push its
+ *  cells under their minimum. `Infinity` means the block can only have a whole row. */
+/** What a preview card adds around its frames: `padding` (CATALOG_SPACE.xl) and a 1px border on
+ *  each side. `blockMinWidth` must add it, or a preview is offered a half-row that fits its frame
+ *  only after the card has taken its share, and the frame silently renders under phone width.
+ *  SectionBlock's `previewCard` style is built from these, so the two cannot drift. */
+export const PREVIEW_CARD_CHROME = { padding: 24, border: 1 };
+/** The same for a `previewLayout: 'table'` card: no outer padding, a 1px border, and each cell
+ *  carries `cellPadding` on both sides of its frame. */
+export const TABLE_PREVIEW_CHROME = { padding: MATRIX_LAYOUT.cellPadding, border: 1 };
+/** Total horizontal chrome for one preview frame in either card. */
+export function previewChrome(layout) {
+    const chrome = layout === 'table' ? TABLE_PREVIEW_CHROME : PREVIEW_CARD_CHROME;
+    return 2 * chrome.padding + 2 * chrome.border;
+}
+export function blockMinWidth(block) {
+    switch (block.kind) {
+        case 'grid':
+            return gridMinWidth(axisItems(block.comparison.columns).length, block.size);
+        case 'grouped':
+            return MATRIX_LAYOUT.rowHeaderWidth + Math.max(1, ...block.groups.map((g) => g.items.length)) * COLUMN_MIN_WIDTH[block.size] + 2;
+        case 'list':
+            // One column: a list always wraps further rather than going below its size's minimum.
+            return COLUMN_MIN_WIDTH[block.size] + 2;
+        case 'preview':
+            // A 'full' preview is the row. Otherwise the *widest* frame sets the minimum: the frames wrap,
+            // so each one sits on its own row and `maxWidth: '100%'` would squeeze any frame wider than
+            // the card. The card's own chrome counts too — a frame keeps its width only if the row also
+            // covers the padding and border around it.
+            return block.widths === 'full' ? Infinity : Math.max(...block.widths) + previewChrome(block.layout);
+        default:
+            return Infinity;
+    }
+}
+/** The height a block takes at `width`, from the height measured while stacked at `available`.
+ *  Only a list reflows: its rows change with the width, and every row is the same height. */
+function heightAtWidth(block, width, available) {
+    if (block.kind !== 'list' || !block.itemCount || !block.size)
+        return block.height;
+    const stackedRows = listGeometry(block.itemCount, available, block.size, block.maxColumns).rows;
+    const rows = listGeometry(block.itemCount, width, block.size, block.maxColumns).rows;
+    return (block.height / Math.max(1, stackedRows)) * rows;
+}
+/** Side by side or stacked, for a page with exactly two blocks. Side by side splits the row into
+ *  two equal columns and each block fills its own, so it is only possible when both blocks keep
+ *  their minimum width in half a row; it is only taken when it saves at least PLACEMENT_MIN_SAVING
+ *  against stacking, measuring each block at the width it would actually have. */
 export function choosePlacement({ available, gap, first, second }) {
-    if (second.kind !== 'list' || !second.itemCount || !second.size)
-        return 'stacked';
-    const firstWidth = first.width ?? available;
-    if (firstWidth > available * 0.7)
+    const half = Math.floor((available - gap) / 2);
+    if (half <= 0)
         return 'stacked';
-    const room = available - firstWidth - gap;
-    const minCell = second.size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : COLUMN_MIN_WIDTH[second.size];
-    if (room < minCell + 2)
+    if ((first.minWidth ?? Infinity) > half || (second.minWidth ?? Infinity) > half)
         return 'stacked';
-    const stackedRows = listGeometry(second.itemCount, available, second.size, second.maxColumns).rows;
-    const sideRows = listGeometry(second.itemCount, room, second.size, second.maxColumns).rows;
-    const rowHeight = second.height / Math.max(1, stackedRows);
-    const sideHeight = Math.max(first.height, sideRows * rowHeight);
+    const sideHeight = Math.max(heightAtWidth(first, half, available), heightAtWidth(second, half, available));
     const stackedHeight = first.height + gap + second.height;
     return sideHeight <= stackedHeight - PLACEMENT_MIN_SAVING ? 'side' : 'stacked';
 }

package/dist/native/catalog/tokens.js

@@ -10,15 +10,17 @@
  * (docs/design/2026-10-06-catalog-studio-matrix-*.html), with one deliberate exception:
  * `textMuted` stays #666666 because the references' #777777 fails WCAG AA contrast.
  */
+/** Owner decision 2026-10-11: only 10, 12, 14, 16, 18, 24, 28, 32 and 40. Named roles share a
+ *  step (tableHeader and panelHeading are 12, brand is 18). */
 export const CATALOG_TYPE = {
     xs: 10,
-    tableHeader: 11,
+    tableHeader: 12,
     sm: 12,
-    panelHeading: 13,
+    panelHeading: 12,
     md: 14,
     lg: 16,
-    brand: 17,
-    xl: 20,
+    brand: 18,
+    xl: 18,
     '2xl': 24,
     pageTitle: 28,
     '3xl': 32,
@@ -76,8 +78,8 @@ export const CATALOG_TYPE_USE = {
     md: 'Default body text: descriptions, nav links, grid row headers, quick-reference rows, the filter field.',
     lg: 'Pager arrows and the filter field\'s clear (×) glyph.',
     brand: 'The app name at the top of the sidebar.',
-    xl: 'Reserved — no current consumer.',
-    '2xl': 'Reserved — no current consumer.',
+    xl: "The major-update banner's close (×) glyph.",
+    '2xl': "The update page's version numbers and the arrow between them.",
     pageTitle: 'The selected page\'s title.',
     '3xl': 'Reserved — no current consumer.',
     '4xl': 'Reserved — no current consumer.',
@@ -111,6 +113,10 @@ export const CATALOG_COLOR = {
     surfaceMuted: '#fafafa',
     /** Hover and pressed feedback on nav rows and buttons. */
     surfacePressed: '#f1f3f8',
+    /** A disabled control's surface, and its label. Approved with the update page's buttons
+     *  (docs/design/2026-10-10-ds-viewer-update-page-always-approved.html). */
+    controlDisabled: '#e6e6e6',
+    controlDisabledText: '#8a8a8a',
     /** An example's cell when the example itself is white (`specimenSurface`), darker than surfaceMuted so a white card's edges show. */
     specimenStage: '#f2f2f2',
     pageBackground: '#f6f6f4',

package/native/catalog/CatalogButton.tsx

@@ -1,46 +1,85 @@
 import React, { forwardRef, useState } from 'react';
-import { Pressable, StyleSheet, Text, type View } from 'react-native';
-import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_TYPE } from './tokens';
+import { ActivityIndicator, Pressable, StyleSheet, Text, type View } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 
-/** The viewer's own button, for catalog chrome and demo triggers (not an app component). Same look
- *  as the update page's buttons. */
+/** The viewer's own button, for catalog chrome and demo triggers (not an app component): a rounded
+ *  rectangle, primary in the accent blue, secondary outlined. `disabled` greys it and stops the
+ *  press; `busy` keeps its own colours while the action it started is still running, with a
+ *  spinner before the label. */
 export const CatalogButton = forwardRef<View, {
   label: string;
-  onPress: () => void;
+  /** Optional, because a permanently unavailable button still renders (see `disabled`). */
+  onPress?: () => void;
   variant?: 'primary' | 'secondary';
+  /** Not pressable, and visibly unavailable. */
+  disabled?: boolean;
+  /** Pressed already, still working: a spinner and a muted label. Also stops a second press. */
+  busy?: boolean;
   accessibilityLabel?: string;
-}>(function CatalogButton({ label, onPress, variant = 'primary', accessibilityLabel }, ref) {
+}>(function CatalogButton({ label, onPress, variant = 'primary', disabled = false, busy = false, accessibilityLabel }, ref) {
   const [focused, setFocused] = useState(false);
   const primary = variant === 'primary';
+  // Busy stops the press like disabled does — the action is already running — but keeps the
+  // button's own colours, because it is working rather than unavailable.
+  const off = disabled || busy;
   return (
     <Pressable
       ref={ref}
-      onPress={onPress}
+      onPress={off ? undefined : onPress}
+      disabled={off}
       onFocus={() => setFocused(true)}
       onBlur={() => setFocused(false)}
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel ?? label}
+      accessibilityState={{ disabled: off, busy }}
       style={({ pressed }) => [
         styles.base,
         primary ? styles.primary : styles.secondary,
-        pressed && (primary ? styles.primaryPressed : styles.secondaryPressed),
+        pressed && !off && (primary ? styles.primaryPressed : styles.secondaryPressed),
+        disabled && styles.disabled,
         focused && styles.focus,
       ]}
     >
-      <Text style={[styles.label, primary ? styles.labelPrimary : styles.labelSecondary]}>{label}</Text>
+      {busy ? <ActivityIndicator size="small" color={CATALOG_COLOR.textMuted} /> : null}
+      <Text
+        style={[
+          styles.label,
+          primary ? styles.labelPrimary : styles.labelSecondary,
+          busy && styles.labelBusy,
+          disabled && styles.labelDisabled,
+        ]}
+      >
+        {label}
+      </Text>
     </Pressable>
   );
 });
 
 const styles = StyleSheet.create({
-  base: { height: CATALOG_LAYOUT.controlSize, paddingHorizontal: 18, borderRadius: 22, alignItems: 'center', justifyContent: 'center', alignSelf: 'center' },
-  primary: { backgroundColor: CATALOG_COLOR.text },
+  // A rounded rectangle (owner decision 2026-10-11); primary in the catalog's accent blue.
+  // A row, so `busy` can put a spinner before the label without the label moving.
+  base: {
+    height: CATALOG_LAYOUT.controlSize,
+    paddingHorizontal: 18,
+    borderRadius: CATALOG_RADIUS.control,
+    flexDirection: 'row',
+    gap: CATALOG_SPACE.sm,
+    alignItems: 'center',
+    justifyContent: 'center',
+    alignSelf: 'center',
+  },
+  primary: { backgroundColor: CATALOG_COLOR.accent },
   primaryPressed: { opacity: 0.85 },
   secondary: { borderWidth: 1, borderColor: CATALOG_COLOR.borderStrong, backgroundColor: CATALOG_COLOR.surface },
   secondaryPressed: { backgroundColor: CATALOG_COLOR.surfacePressed },
+  // One flat grey for both variants, so a disabled primary and a disabled secondary read the same:
+  // what stops the press is the state, not which button it is.
+  disabled: { backgroundColor: CATALOG_COLOR.controlDisabled, borderColor: CATALOG_COLOR.controlDisabled },
   // Same ring as the sidebar's: an outline, so focusing never shifts the layout.
   focus: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing } as object,
   label: { fontSize: CATALOG_TYPE.md, fontWeight: '700' },
   labelPrimary: { color: '#ffffff' },
   labelSecondary: { color: CATALOG_COLOR.text },
+  labelBusy: { color: CATALOG_COLOR.textMuted },
+  labelDisabled: { color: CATALOG_COLOR.controlDisabledText },
 });