@krapwoo/ds-viewer 0.6.10 → 0.7.0

package/README.md

@@ -72,6 +72,29 @@ loser then serves a workspace that no longer describes it, which Expo reports as
 with `--workspace-dir .ds-viewer-second`. A lock left behind by a crashed `dev` never blocks the
 next one.
 
+`.ds-viewer/` belongs to the running server, and it repairs it. If something outside the server
+deletes the generated files while it is serving, it says so and writes them back, rather than
+leaving Expo to report an unresolvable `main` field — which names your project's `package.json`, a
+file that is fine and that you never touched:
+
+```
+Something outside this server deleted package.json, app.json, tsconfig.json, metro.config.js,
+entry.tsx from .ds-viewer/. Rewriting them — your project is fine, this is the catalog's own
+generated workspace. If the catalog looks broken, reload the page.
+Restarting Metro so the catalog picks the files back up — the page reloads itself in a few seconds.
+```
+
+Metro is restarted as part of the repair, because rewriting the files is not enough on its own: it
+keeps serving the module map it cached before they went missing, and answers every request with
+`Unable to resolve "expo" from "entry.tsx"` until it starts again. The server stays up and the page
+reloads itself.
+
+The repair is capped at five per run: if something is deleting continuously, repairing forever
+would only hide it, so past the cap the server stops and keeps reporting. If you ever see that
+message, what else was running at the time would be useful on
+[issue #41](https://github.com/krapwoo/design-system-viewer/issues/41) — the cause is not yet
+identified.
+
 `ds-viewer.config.ts` fields: `name`, `logo` (optional — a path to an image asset, shown in the
 sidebar beside the name, or in place of it for a wide wordmark; validated at `sync`/`dev` time
 and bundled into the preview workspace), `components`, `exclude`, `tokens`, `pages`, `groupOrder`, `starterKit` (new-project only —
@@ -544,12 +567,28 @@ and adds what only a real render shows:
   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.
+- `specimen-clipped` (warning): an example in a list card painting past the left or right of its
+  cell, where it is cut off rather than contained. Content the specimen holds itself is not
+  reported — anything inside something that scrolls (`auto`/`scroll`, so the reader can reach it)
+  or clips (`hidden`/`clip`) is treated as the specimen's own containment. That last one is a
+  trade-off worth knowing: a full-width component clipping its own corners hides a genuinely
+  too-narrow cell from this rule, so `hidden` buys quiet for carousels and shimmer sweeps at the
+  cost of that case. Only horizontal crossings in `role=list` cells are measured — a cell's width
+  is what the page allocates, while its height grows with content, and matrix (`ComparisonGrid`)
+  cells are not visited at all. Usually fixed with a wider `specimenSize`, by stacking the blocks so
+  the example gets the full row, or by dropping `itemsFill` from a small instance that should sit
+  centered.
 - `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
 install a browser. It takes about two minutes for 50 pages and works with `--json` (progress
 goes to stderr), `--ci` and `doctor.strict`, so CI can run `npx ds-viewer doctor --render --ci`.
 
+It starts its own catalog on the first free port from 5181. `--port <n>` pins it instead, which
+you want when something else already holds that range — another project's catalog, or a second
+`dev`. The check cannot tell a stranger's server on its port from its own, so a collision reports
+that server's pages as your project's failures.
+
 It starts its own `dev` server, with `--no-update-endpoint` and its own generated directory
 (`.ds-viewer-render/`, gitignored by `init` alongside `.ds-viewer/`). Nothing it generates touches
 the workspace a running `dev` owns, so you can run it beside a catalog you already have open and

package/dist/cli/dev.js

@@ -6,7 +6,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { resolveConfig } from "./config.js";
 import { sync } from "./sync.js";
-import { clearDevLock, liveDevLock, workspacePath, writeDevLock, writeWorkspace } from "./workspace.js";
+import { clearDevLock, liveDevLock, missingWorkspaceFiles, workspacePath, writeDevLock, writeWorkspace } from "./workspace.js";
 import { findFreePort } from "./port.js";
 import { globBaseFolder } from "./glob.js";
 import { buildVersionStatus, createVersionController, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck, runUpdateCheck, statusFromCheck, writeUpdateFile, writeVersionFile, } from "./updateCheck.js";
@@ -326,6 +326,42 @@ export async function performRestart(handoff, deps = {}) {
  *  component/token/page changes to re-run `sync`. Metro's own HMR updates the rendered component
  *  when its source changes, but not the generated props table or page list (Task 17 Step 4 relies
  *  on this: editing `Button.tsx` must update its props table, not just hot-reload the component). */
+/** How often a running `dev` checks that its own workspace still exists. Cheap (five `existsSync`
+ *  calls), and slow enough to be invisible: the failure it covers is rare, and noticing within a
+ *  few seconds is soon enough to repair before the next page load. */
+const WORKSPACE_WATCH_INTERVAL_MS = 4000;
+/** How many times one `dev` run will rewrite a workspace that keeps losing files. Past this,
+ *  something is deleting continuously and repairing again would only hide it. */
+const WORKSPACE_REPAIR_LIMIT = 5;
+/** One pass of the workspace integrity check. Returns what it did, so the caller owns the repair
+ *  budget and the tests can drive it without a timer.
+ *
+ *  `updateEndpoint` is the caller's own, passed through unchanged: rebuilding it here from the
+ *  Metro port would point the repaired catalog at the wrong server, silently breaking the update
+ *  panel while telling the developer everything is fine. */
+export function repairWorkspaceIfMissing(deps) {
+    const { config, updateEndpoint, versionStatus, sync, reclaimLock, log = console.warn } = deps;
+    const missing = missingWorkspaceFiles(config);
+    if (missing.length === 0)
+        return { missing, repaired: false };
+    log(`Something outside this server deleted ${missing.join(', ')} from ${config.workspaceDir ?? DEFAULT_WORKSPACE_DIR}/. ` +
+        "Rewriting them — your project is fine, this is the catalog's own generated workspace. " +
+        'If the catalog looks broken, reload the page.');
+    writeWorkspace(config, updateEndpoint);
+    // `entry.tsx` imports both of these, so a rewrite that skips them resolves nothing. Both come
+    // from one status, the way `refreshUpdateFile` writes them, so a repair cannot leave
+    // `version.json` announcing an update that `update.json` denies.
+    const status = versionStatus();
+    if (!existsSync(workspacePath(config, 'update.json'))) {
+        const update = status.update ? { ...status.update, checkedAt: status.lastCheckedAt ?? new Date().toISOString() } : undefined;
+        writeUpdateFile(config.projectRoot, update, config.workspaceDir);
+    }
+    if (!existsSync(workspacePath(config, 'version.json')))
+        writeVersionFile(config.projectRoot, status, config.workspaceDir);
+    reclaimLock();
+    sync(config);
+    return { missing, repaired: true };
+}
 export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
     const ownVersion = readOwnVersion(import.meta.dirname);
@@ -499,23 +535,122 @@ export async function dev(initialConfig, devOptions = {}) {
     for (const watcher of watchers) {
         watcher.on('error', (error) => console.warn(`File watcher error: ${error.message}`));
     }
-    child = spawn('npx', ['expo', 'start', '--web', '--host', 'localhost', '--port', String(port)], {
+    const spawnMetro = () => spawn('npx', ['expo', 'start', '--web', '--host', 'localhost', '--port', String(port)], {
         cwd: workspace,
         stdio: 'inherit',
         shell: process.platform === 'win32',
         detached: true,
     });
-    child.on('error', (error) => console.warn(`Could not start Expo: ${error.message}`));
-    child.on('exit', (code) => {
-        for (const watcher of watchers)
-            watcher.close();
-        endpointServer?.close();
-        // Released so the next `dev` is not refused by a lock naming a process that has gone.
-        // `liveDevLock` already ignores a dead pid, so this is tidiness, not correctness — it keeps a
-        // stale file out of a directory a developer may well read.
-        clearDevLock(config);
-        process.exitCode = code ?? 0;
-    });
+    // Set while this process is deliberately replacing Metro, so the exit handler below respawns it
+    // instead of running the shutdown path. Restoring the files is not enough on its own: Metro has
+    // already cached a module map that no longer matches the directory, and it answers every request
+    // with `Unable to resolve "expo" from "entry.tsx"` until it is restarted. Observed four times —
+    // the files came back and the catalog stayed blank.
+    let restartingMetro = false;
+    child = spawnMetro();
+    // This process owns its workspace: nothing else should remove the files that define it. When
+    // they vanish anyway, Metro reports it as `Cannot resolve entry file: the 'main' field defined
+    // in your package.json points to an unresolvable or non-existent path` — which names the
+    // *project's* package.json, a file that is fine and that the developer did not touch. The cause
+    // is still unidentified (issue #41), so this does not pretend to prevent it; it notices, says
+    // plainly what happened, and writes the files back, because `writeWorkspace` is idempotent and
+    // already knows how.
+    //
+    // Capped rather than endless: if something is deleting continuously, rewriting forever would
+    // hide it behind a repair loop. After the cap this stops repairing and keeps saying so, which
+    // leaves the evidence visible.
+    let repairs = 0;
+    const workspaceWatch = setInterval(() => {
+        if (watchersPaused)
+            return; // an update is rewriting the workspace on purpose.
+        if (repairs >= WORKSPACE_REPAIR_LIMIT) {
+            const missing = missingWorkspaceFiles(config);
+            if (missing.length > 0) {
+                console.warn(`The catalog workspace is still losing files (missing ${missing.join(', ')}). Not rewriting them again — ` +
+                    'something outside this server is deleting them. Please report what else was running at https://github.com/krapwoo/design-system-viewer/issues/41');
+            }
+            return;
+        }
+        // Counted as an attempt, not a success: a workspace that cannot be rewritten (a permission
+        // error, a sync failure) would otherwise retry every four seconds forever.
+        if (missingWorkspaceFiles(config).length > 0)
+            repairs += 1;
+        try {
+            // `updateEndpoint` is passed through, never rebuilt: the endpoint listens on its own
+            // ephemeral port, so deriving one from Metro's port here would repair the files and break
+            // the update panel in the same breath.
+            const { repaired } = repairWorkspaceIfMissing({
+                config, updateEndpoint, versionStatus: version.getVersionStatus, sync,
+                // Only if no one else took it meanwhile: between losing the lock and this tick, a second
+                // `dev` can legitimately have started and be serving the directory. Overwriting its lock
+                // would leave two servers each believing they own it.
+                reclaimLock: () => {
+                    const other = liveDevLock(config);
+                    if (other && other.pid !== process.pid) {
+                        console.warn(`Not reclaiming ${config.workspaceDir ?? DEFAULT_WORKSPACE_DIR}/: pid ${other.pid} owns it now.`);
+                        return;
+                    }
+                    writeDevLock(config, { pid: process.pid, port });
+                },
+            });
+            // Rewritten files are not enough: Metro keeps serving the module map it cached before they
+            // went missing. Restarting it is the only thing that gets the catalog back, and the repair
+            // cap bounds how often this can happen.
+            if (repaired && !restartingMetro) {
+                console.warn('Restarting Metro so the catalog picks the files back up — the page reloads itself in a few seconds.');
+                restartingMetro = true;
+                killGroup(child, 'SIGTERM');
+            }
+        }
+        catch (error) {
+            console.warn(`Could not rewrite the workspace: ${error.message}`);
+        }
+    }, WORKSPACE_WATCH_INTERVAL_MS);
+    workspaceWatch.unref?.();
+    const bindChild = () => {
+        child.on('error', (error) => console.warn(`Could not start Expo: ${error.message}`));
+        child.on('exit', (code) => {
+            // A Metro we killed on purpose: respawn it on the same port rather than tearing the server
+            // down, once the port it held is actually free again.
+            if (restartingMetro) {
+                // The flag stays set for the whole restart, not just until this handler returns. Clearing
+                // it before the wait left a window where the repair timer could ask for another restart,
+                // find no live child to kill, and leave the flag set with nothing pending — after which
+                // the next genuine Metro crash would be mistaken for a deliberate restart and silently
+                // respawn, skipping the shutdown path that releases the watchers and the dev lock.
+                // `repairWorkspaceIfMissing`'s caller already checks this flag, so holding it also stops a
+                // second repair stacking a restart on top of this one.
+                //
+                // The port is not free the instant this child exits: `performRestart` waits for the same
+                // reason, and Errata 7c records that Metro listens on `[::1]`, so a naive probe reports
+                // free while it is still bound. Respawning early lets Expo find its own port taken and
+                // either prompt — giving up with "Skipping dev server" in a non-interactive shell — or move
+                // to another port, leaving the catalog where the dev lock does not name.
+                void waitForPortFree(port, defaultProbePortFree)
+                    .catch(() => {
+                    // Still spawn: a catalog that tried and failed to come back is recoverable, one that
+                    // silently never tries is not. Expo reports the port conflict itself if there is one.
+                    console.warn(`Port ${port} was still held after the wait; starting Metro anyway.`);
+                })
+                    .then(() => {
+                    child = spawnMetro();
+                    bindChild();
+                    restartingMetro = false;
+                });
+                return;
+            }
+            clearInterval(workspaceWatch);
+            for (const watcher of watchers)
+                watcher.close();
+            endpointServer?.close();
+            // Released so the next `dev` is not refused by a lock naming a process that has gone.
+            // `liveDevLock` already ignores a dead pid, so this is tidiness, not correctness — it keeps a
+            // stale file out of a directory a developer may well read.
+            clearDevLock(config);
+            process.exitCode = code ?? 0;
+        });
+    };
+    bindChild();
     // Node's default SIGTERM/SIGINT/SIGHUP behavior exits this process without touching its
     // children — left alone, a signal sent only to `dev`'s own pid (not its process group) would
     // leave the spawned `expo start` running, still bound to its port (Important finding, Fable

package/dist/cli/main.js

@@ -34,6 +34,8 @@ Commands:
            --json          print the machine-readable report instead
            --ci            exit 1 when any error was found (never on a warning alone)
            --render        also open every page in a headless browser (needs puppeteer)
+           --port <n>      pin the render server's port (with --render), for when something
+                           else already holds the range it would pick from
   explain <Page>
            Print why a page's specimens are laid out the way they are
            --heights <first>,<second>  check side-by-side placement with these measured heights
@@ -128,7 +130,23 @@ export async function runDoctorCommand(projectRoot, rest, options = {}) {
     // Progress goes to stderr, so `--json` output stays pure JSON.
     if (rest.includes('--render')) {
         const files = result.pageFiles;
-        const rendered = await (options.renderCheck ?? renderCheck)(config.projectRoot, { files, log: (line) => process.stderr.write(`${line}\n`) });
+        // `--port <n>`: pin the render server instead of taking the first free port from 5181. Needed
+        // when something else already holds that range (another project's catalog, a second `dev`),
+        // because the check cannot tell a stranger's server on its port from its own and would report
+        // that server's pages as this project's failures.
+        const portFlag = rest.indexOf('--port');
+        let renderPort;
+        if (portFlag !== -1) {
+            const raw = rest[portFlag + 1];
+            renderPort = Number(raw);
+            if (!raw || !Number.isInteger(renderPort) || renderPort < 1 || renderPort > 65535) {
+                // Refused rather than quietly falling back to a port it picked itself: a check that
+                // ignores the port you gave it would render against whatever else is there and report a
+                // stranger's pages as this project's failures.
+                return { output: `doctor --render --port needs a port between 1 and 65535, not ${raw ?? '(nothing)'}.`, exitCode: 1 };
+            }
+        }
+        const rendered = await (options.renderCheck ?? renderCheck)(config.projectRoot, { files, log: (line) => process.stderr.write(`${line}\n`), ...(renderPort ? { port: renderPort } : {}) });
         result = withExtraIssues(result, rendered, Boolean(config.doctor?.strict));
     }
     // Design §4 "`--ci`: ... no update check." — `--ci` skips this whole block even when

package/dist/cli/render.js

@@ -121,6 +121,79 @@ export function identicalVariantIssues(page, pairs) {
         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.",
     }));
 }
+/**
+ * Runs in the browser: finds specimen content that paints outside its cell and cannot be reached.
+ *
+ * A cell is the width the page gives an example. Content wider than it is either clipped — the
+ * reader sees a cut-off component and no indication anything is missing — or drawn over its
+ * neighbour. Either way the page is showing something other than the component.
+ *
+ * Scrollable content is deliberately not reported, and so is content a component clips itself:
+ * both are decisions the specimen made, not width the page failed to give it. `PillRow`'s "Many
+ * pills (scrollable)" paints 220px outside its cell at 1280 and is correct; a shimmer sweep or a
+ * carousel that hides its own overflow is equally deliberate.
+ *
+ * The containment walk stops at the cell. Looking past it was wrong: `ComparisonGroups` wraps every
+ * grouped card in a horizontal `ScrollView`, which react-native-web renders as `overflow-x: auto`,
+ * so a walk to the document root found that scroller above every grouped cell and exempted all of
+ * them — the rule covered plain list blocks only, while its calibration claimed the whole corpus.
+ * What matters is whether the *specimen* contains its own overflow, which is a question about the
+ * ancestors inside the cell.
+ *
+ * Only horizontal crossings are measured. A cell's width is what the page allocates and what
+ * `specimenSize` controls; its height grows with content.
+ */
+export const CLIPPED_SPECIMEN_SCRIPT = `(() => {
+  const doc = document;
+  const CONTAINS = /^(auto|scroll|hidden|clip)$/;
+  const out = [];
+  for (const card of doc.querySelectorAll('[role=list][aria-label]')) {
+    if (!/^[^:]+: .+/.test(card.getAttribute('aria-label') || '')) continue;
+    for (const cell of card.querySelectorAll('[role=listitem]')) {
+      if (cell.closest('[role=list]') !== card) continue;
+      const box = cell.getBoundingClientRect();
+      if (box.width < 2) continue;
+      let worst = 0;
+      let side = 'right';
+      for (const el of cell.querySelectorAll('*')) {
+        const r = el.getBoundingClientRect();
+        if (r.width < 2 || r.height < 2) continue;
+        const over = Math.max(box.left - r.left, r.right - box.right);
+        if (over <= worst) continue;
+        // Invisible content, including anything inside an invisible or offscreen wrapper: an exit
+        // animation mid-flight, or a visually-hidden node parked at a large negative offset.
+        let hidden = false;
+        let contained = false;
+        for (let p = el; p && p !== cell; p = p.parentElement) {
+          const style = getComputedStyle(p);
+          if (style.visibility === 'hidden' || style.opacity === '0' || style.display === 'none') { hidden = true; break; }
+          // Anything between the content and the cell that handles its own overflow — scrolling it
+          // or clipping it — is the specimen's own decision, not the page denying it width.
+          if (p !== el && CONTAINS.test(style.overflowX)) { contained = true; break; }
+        }
+        if (hidden || contained) continue;
+        worst = over;
+        side = box.left - r.left >= r.right - box.right ? 'left' : 'right';
+      }
+      if (worst > 1) {
+        const caption = cell.children[0] ? (cell.children[0].textContent || '') : '';
+        out.push({ name: caption.trim(), overflow: Math.round(worst), side });
+      }
+    }
+  }
+  return out;
+})()`;
+/** Turns the browser's findings into doctor issues, one per clipped example. */
+export function clippedSpecimenIssues(page, clipped) {
+    const ref = { page: page.id, ...(page.file ? { file: page.file } : {}) };
+    return clipped.map((c) => ({
+        id: 'specimen-clipped',
+        severity: 'warning',
+        ...ref,
+        message: `${c.name ? `"${c.name}"` : 'An example'} paints ${c.overflow}px past the ${c.side} of its cell, where it is cut off rather than scrollable.`,
+        fix: 'Give the page a wider specimenSize, stack the blocks so the example gets the full row, or drop `itemsFill` if the example is a small instance that should sit centered.',
+    }));
+}
 /** The project's own puppeteer, or `undefined` when it isn't installed. */
 export function loadProjectPuppeteer(projectRoot) {
     try {
@@ -195,14 +268,14 @@ async function waitForServer(port, timeoutMs = DEV_START_TIMEOUT_MS) {
         await new Promise((resolve) => setTimeout(resolve, 250));
     }
 }
-function startDev(projectRoot, onSpawn) {
+function startDev(projectRoot, onSpawn, pinnedPort) {
     const main = path.join(path.dirname(fileURLToPath(import.meta.url)), 'main.js');
     return new Promise((resolve, reject) => {
         // Its own workspace directory and no update endpoint: this server exists to render pages, and
         // every file it generates would otherwise overwrite the ones an already-running `dev` is
         // serving — including that developer's endpoint, pointing their open catalog at a port that
         // dies with this check.
-        const child = spawn(process.execPath, [main, 'dev', '--no-update-endpoint', '--workspace-dir', RENDER_WORKSPACE_DIR], {
+        const child = spawn(process.execPath, [main, 'dev', '--no-update-endpoint', '--workspace-dir', RENDER_WORKSPACE_DIR, ...(pinnedPort ? ['--port', String(pinnedPort)] : [])], {
             cwd: projectRoot,
             env: { ...process.env, CI: '1', DS_VIEWER_NO_UPDATE_CHECK: '1' },
             detached: process.platform !== 'win32',
@@ -289,7 +362,7 @@ export async function renderCheck(projectRoot, options = {}) {
         }
         ({ port } = await (deps.startDev ?? startDev)(projectRoot, (child) => {
             devChild = child;
-        }));
+        }, options.port));
         const home = await browser.newPage();
         const deadline = Date.now() + FIRST_LOAD_TIMEOUT_MS;
         for (;;) {
@@ -352,6 +425,17 @@ export async function renderCheck(projectRoot, options = {}) {
                 }
                 if (Array.isArray(identical))
                     issues.push(...identicalVariantIssues({ id, file: options.files?.get(id) }, identical));
+                // Advisory for the same reason as the pass above, and kept separate so one failing script
+                // does not cost the other its findings.
+                let clipped;
+                try {
+                    clipped = (await page.evaluate(CLIPPED_SPECIMEN_SCRIPT));
+                }
+                catch {
+                    clipped = undefined;
+                }
+                if (Array.isArray(clipped))
+                    issues.push(...clippedSpecimenIssues({ id, file: options.files?.get(id) }, clipped));
                 await page.close();
             }
             catch (error) {

package/dist/cli/workspace.js

@@ -151,6 +151,18 @@ export function liveDevLock(config, ownPid = process.pid) {
         return undefined;
     return lock;
 }
+/** The files `writeWorkspace` always writes: the ones that define the workspace to Expo and Metro.
+ *  `babel.config.js` is conditional and the update files are written separately, so neither counts
+ *  as missing here. */
+export const WORKSPACE_DEFINING_FILES = ['package.json', 'app.json', 'tsconfig.json', 'metro.config.js', 'entry.tsx'];
+/** Which of those a workspace has lost. A running `dev` owns these files and nothing else should
+ *  remove them, so a non-empty answer means something outside this process deleted them — see
+ *  issue #41, where the cause is still unidentified. Reported rather than diagnosed: the point is
+ *  that the server can say what happened instead of leaving Expo to blame the project's own
+ *  `package.json` with `Cannot resolve entry file`. */
+export function missingWorkspaceFiles(config) {
+    return WORKSPACE_DEFINING_FILES.filter((name) => !existsSync(workspacePath(config, name)));
+}
 /** Writes the self-contained Expo web workspace at `.ds-viewer/` (design §2 "The preview
  *  workspace and `npx ds-viewer dev`"). Rewritten freely on every `dev` run — nothing here is
  *  user-owned.
@@ -158,9 +170,9 @@ export function liveDevLock(config, ownPid = process.pid) {
  *  `updateEndpoint` is the caller's own, inlined into `entry.tsx`. Without one (a render check's
  *  throwaway server, `--no-update-endpoint`) the catalog is served with no endpoint at all, so it
  *  makes no calls: the shell polls `/version` from every page, so inlining a *different* server's
- *  endpoint here would have every page call it from the wrong origin. Two `dev` servers share this
- *  one directory, so the last writer decides — see the README on running a render check beside an
- *  open catalog. */
+ *  endpoint here would have every page call it from the wrong origin. Each `dev` owns its own
+ *  workspace directory (`dev-lock.json`), so a render check beside an open catalog writes to
+ *  `.ds-viewer-render/` rather than this one — see the README. */
 export function writeWorkspace(config, updateEndpoint) {
     const workspace = workspacePath(config);
     mkdirSync(workspace, { recursive: true });

package/dist/native/catalog/comparison.js

@@ -337,16 +337,49 @@ function heightAtWidth(block, width, available) {
     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. */
+/** Whether a block still fits on a single row in half the width. Deliberately stricter than "the
+ *  same number of rows as a full row would give": a column cap can already force a block to wrap
+ *  at full width, and two wrapped rows staying two wrapped rows is not a reason to halve every
+ *  specimen on the page. One row is the case where sharing genuinely costs nothing. */
+function fitsOneRow(block, half) {
+    if (block.kind !== 'list' || !block.itemCount || !block.size)
+        return true;
+    return listGeometry(block.itemCount, half, block.size, block.maxColumns).rows <= 1;
+}
+/** Side by side or stacked, for a page with exactly two blocks.
+ *
+ *  **Stacked is the default.** A page reads top to bottom, each block gets the whole row, and every
+ *  specimen keeps the width its component is actually used at. Side by side halves that width, so
+ *  it has to earn the space rather than be taken whenever it happens to save height — which is how
+ *  `Banner` ended up showing five full-width banners in a 462px column.
+ *
+ *  Two things earn it:
+ *
+ *  - **A single tall specimen.** One specimen taller than the column is wide leaves a long empty
+ *    strip beside it (an open `Dropdown` is 738px tall in a 462px column), and the other block
+ *    fits there for free.
+ *  - **Both still fit one row.** Specimens small enough that each block is a single row in half
+ *    the width lose nothing by sharing it.
+ *
+ *  Both still require each block to keep its minimum width in half a row, and the result to save
+ *  at least `PLACEMENT_MIN_SAVING` of height — side by side that saves nothing is just a narrower
+ *  page. */
 export function choosePlacement({ available, gap, first, second }) {
     const half = Math.floor((available - gap) / 2);
     if (half <= 0)
         return 'stacked';
     if ((first.minWidth ?? Infinity) > half || (second.minWidth ?? Infinity) > half)
         return 'stacked';
+    // Measured at the width it would have: a specimen is "tall" when it runs longer than the column
+    // it would sit in, which is what leaves room beside it.
+    // Either block can be the tall one. Checking `first` alone made placement depend on the order the
+    // page happens to declare its blocks in, so the same two blocks laid out variants-then-states and
+    // states-then-variants got different answers — and the rule says "a single specimen taller than
+    // its column", which says nothing about order.
+    const singleTallSpecimen = (first.itemCount === 1 && first.height > half) || (second.itemCount === 1 && second.height > half);
+    const bothFitOneRow = fitsOneRow(first, half) && fitsOneRow(second, half);
+    if (!singleTallSpecimen && !bothFitOneRow)
+        return 'stacked';
     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/native/catalog/SpacingScaleGallery.tsx

@@ -1,5 +1,5 @@
 import { View, Text, StyleSheet } from 'react-native';
-import { TokenRow } from './TokenRow';
+import { TokenRow, TokenRowGroup } from './TokenRow';
 import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS } from './tokens';
 
 /**
@@ -18,11 +18,11 @@ export function SpacingScaleGallery<TStep extends string | number>({
   useNotes: Record<TStep, string>;
 }) {
   return (
-    <View style={styles.tokenStack}>
+    <TokenRowGroup><View style={styles.tokenStack}>
       {steps.map((step, i) => {
         const px = values[step];
         return (
-          <TokenRow key={String(step)} use={useNotes[step]} last={i === steps.length - 1}>
+          <TokenRow key={String(step)} use={useNotes[step]} last={i === steps.length - 1} notePlacement="right">
             <View style={styles.row}>
               <Text style={styles.label}>{String(step)}</Text>
               <View style={[styles.bar, { width: Math.max(px, 1) }]} />
@@ -31,7 +31,7 @@ export function SpacingScaleGallery<TStep extends string | number>({
           </TokenRow>
         );
       })}
-    </View>
+    </View></TokenRowGroup>
   );
 }
 

package/native/catalog/TokenRow.tsx

@@ -1,18 +1,45 @@
-import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
+import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 
+type Lane = { width: number; report: (width: number) => void };
+
+const LaneContext = createContext<Lane | undefined>(undefined);
+
 /**
- * Wraps one token's rendered example with a grounded "when to use this" note beneath it — the
- * shared shape behind every token-gallery row (Spacing, Type Scale, …) in both the starter kit's
- * own token pages and the catalog framework's own `kit-host/viewer-pages/` pages. The row's own
- * content (a spacing bar, a type sample, …) is
- * freeform `children`; only the value-plus-use-note stacking is standardized here.
+ * Gives a stack of `notePlacement="right"` rows one shared sample column, measured from the widest
+ * sample actually in the stack.
+ *
+ * A fixed column has to be wide enough for the biggest sample a page might hold, which strands
+ * every smaller one: a `normal 400` weight sample is ~110px, and in a column sized for an 88px
+ * display sample its note sat 700px away from it. Measuring instead means the Font page's column
+ * is as wide as a font weight, and the Type scale's is as wide as `display` — each page tight to
+ * its own content, with the notes still aligned in a single column to read down.
  *
- * Draws a 1px `CATALOG_COLOR.border` bottom divider by default (the same divider PropsTable's rows use) so a stack of TokenRows
- * reads as a list, not a loose pile of paragraphs. Pass `last` on the final row in a stack to drop
- * the divider, matching PropsTable's own `rowLast` convention. Balanced `CATALOG_SPACE.md` padding
- * sits above and below both the content and its use-note, so a stack of rows breathes evenly
+ * The width only ever grows, so it settles after the first layout: once the column is the widest
+ * natural sample, no sample can report wider than it and nothing re-measures. Rows sit at their
+ * natural width for that first frame.
+ */
+export function TokenRowGroup({ children }: { children: React.ReactNode }) {
+  const [width, setWidth] = useState(0);
+  const report = useCallback((next: number) => {
+    setWidth((current) => (next > current ? next : current));
+  }, []);
+  const value = useMemo(() => ({ width, report }), [width, report]);
+  return <LaneContext.Provider value={value}>{children}</LaneContext.Provider>;
+}
+
+/**
+ * Wraps one token's rendered example with a grounded "when to use this" note — the shared shape
+ * behind every token-gallery row (Spacing, Type Scale, …) in both the starter kit's own token pages
+ * and the catalog framework's own `viewer-pages/` pages. The row's own content (a spacing bar, a
+ * type sample, …) is freeform `children`; only the value-plus-use-note arrangement is standardized
+ * here.
+ *
+ * Draws a 1px `CATALOG_COLOR.border` bottom divider by default (the same divider PropsTable's rows
+ * use) so a stack of TokenRows reads as a list, not a loose pile of paragraphs. Pass `last` on the
+ * final row in a stack to drop the divider, matching PropsTable's own `rowLast` convention.
+ * Balanced `CATALOG_SPACE.md` padding sits above and below, so a stack of rows breathes evenly
  * instead of only the divider-adjacent gap existing.
  */
 export function TokenRow({
@@ -25,15 +52,36 @@ export function TokenRow({
   children: React.ReactNode;
   use: string;
   last?: boolean;
-  /** `'right'` puts the note beside a narrow sample (icon sizes, spacing, control heights) so each
-   *  token is one line; the sample keeps `sampleWidth` and the note takes the rest. */
+  /** `'right'` puts the note beside the sample (font weights, spacing, type sizes) so each token is
+   *  one line. Inside a `TokenRowGroup` the sample column is measured from the widest sample in the
+   *  stack; a `TokenRowGroup`'s measured column wins when there is one, and `sampleWidth`
+   *  (default 280) is the fallback for a row standing on its own. Keeping the default matters for
+   *  rows outside a group: without it every row sizes to its own sample and the notes stop lining
+   *  up in a column, which is the thing `notePlacement="right"` exists to do. */
   notePlacement?: 'below' | 'right';
   sampleWidth?: number;
 }) {
+  const lane = useContext(LaneContext);
+
   if (notePlacement === 'right') {
+    const measured = lane && lane.width > 0 ? lane.width : undefined;
+    // Inside a group the lane governs, and only the lane: falling back to `sampleWidth` on the
+    // first frame would pin the sample to 280 before anything is measured, and the measurement
+    // taken through that constraint can never report wider than 280 — capping a lane that exists
+    // precisely to grow to the widest sample (a type scale's `display` needs ~470).
+    // `sampleWidth` is for a row standing on its own, where there is nothing to measure against.
+    const column = lane ? measured : sampleWidth;
+    const onLayout = lane
+      ? (event: LayoutChangeEvent) => lane.report(Math.ceil(event.nativeEvent.layout.width))
+      : undefined;
     return (
       <View style={[styles.itemRight, !last && styles.itemDivider]}>
-        <View style={{ width: sampleWidth, flexShrink: 0 }}>{children}</View>
+        {/* While measuring, the inner view sits at its natural width so it reports what the sample
+            actually takes. Standing alone there is nothing to report, so it stretches to the column
+            instead — otherwise a sample sized as a percentage would collapse to nothing. */}
+        <View style={[styles.sample, column !== undefined && { width: column }]}>
+          <View style={onLayout ? styles.natural : undefined} onLayout={onLayout}>{children}</View>
+        </View>
         {use ? <Text style={[styles.use, styles.useRight]}>{use}</Text> : null}
       </View>
     );
@@ -49,6 +97,8 @@ export function TokenRow({
 const styles = StyleSheet.create({
   item: { gap: CATALOG_SPACE.xs, paddingVertical: CATALOG_SPACE.md },
   itemRight: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.xl, paddingVertical: CATALOG_SPACE.md },
+  sample: { flexShrink: 0 },
+  natural: { alignSelf: 'flex-start' },
   useRight: { flex: 1 },
   itemDivider: {
     borderBottomWidth: 1,

package/native/catalog/TypeScaleGallery.tsx

@@ -1,5 +1,5 @@
 import { View, Text, StyleSheet, type TextStyle } from 'react-native';
-import { TokenRow } from './TokenRow';
+import { TokenRow, TokenRowGroup } from './TokenRow';
 import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 
 /**
@@ -22,9 +22,9 @@ export function TypeScaleGallery<TStep extends string>({
   useNotes: Record<TStep, string>;
 }) {
   return (
-    <View style={styles.tokenStack}>
+    <TokenRowGroup><View style={styles.tokenStack}>
       {steps.map((step, i) => (
-        <TokenRow key={String(step)} use={useNotes[step]} last={i === steps.length - 1}>
+        <TokenRow key={String(step)} use={useNotes[step]} last={i === steps.length - 1} notePlacement="right">
           <View style={styles.row}>
             <Text style={[sampleStyle(step), styles.sample]} numberOfLines={1}>
               {String(step)}
@@ -33,7 +33,7 @@ export function TypeScaleGallery<TStep extends string>({
           </View>
         </TokenRow>
       ))}
-    </View>
+    </View></TokenRowGroup>
   );
 }
 

package/native/catalog/comparison.ts

@@ -437,14 +437,48 @@ function heightAtWidth(block: PlacementBlock, width: number, available: number):
   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. */
+/** Whether a block still fits on a single row in half the width. Deliberately stricter than "the
+ *  same number of rows as a full row would give": a column cap can already force a block to wrap
+ *  at full width, and two wrapped rows staying two wrapped rows is not a reason to halve every
+ *  specimen on the page. One row is the case where sharing genuinely costs nothing. */
+function fitsOneRow(block: PlacementBlock, half: number): boolean {
+  if (block.kind !== 'list' || !block.itemCount || !block.size) return true;
+  return listGeometry(block.itemCount, half, block.size, block.maxColumns).rows <= 1;
+}
+
+/** Side by side or stacked, for a page with exactly two blocks.
+ *
+ *  **Stacked is the default.** A page reads top to bottom, each block gets the whole row, and every
+ *  specimen keeps the width its component is actually used at. Side by side halves that width, so
+ *  it has to earn the space rather than be taken whenever it happens to save height — which is how
+ *  `Banner` ended up showing five full-width banners in a 462px column.
+ *
+ *  Two things earn it:
+ *
+ *  - **A single tall specimen.** One specimen taller than the column is wide leaves a long empty
+ *    strip beside it (an open `Dropdown` is 738px tall in a 462px column), and the other block
+ *    fits there for free.
+ *  - **Both still fit one row.** Specimens small enough that each block is a single row in half
+ *    the width lose nothing by sharing it.
+ *
+ *  Both still require each block to keep its minimum width in half a row, and the result to save
+ *  at least `PLACEMENT_MIN_SAVING` of height — side by side that saves nothing is just a narrower
+ *  page. */
 export function choosePlacement({ available, gap, first, second }: { available: number; gap: number; first: PlacementBlock; second: PlacementBlock }): 'side' | 'stacked' {
   const half = Math.floor((available - gap) / 2);
   if (half <= 0) return 'stacked';
   if ((first.minWidth ?? Infinity) > half || (second.minWidth ?? Infinity) > half) return 'stacked';
+
+  // Measured at the width it would have: a specimen is "tall" when it runs longer than the column
+  // it would sit in, which is what leaves room beside it.
+  // Either block can be the tall one. Checking `first` alone made placement depend on the order the
+  // page happens to declare its blocks in, so the same two blocks laid out variants-then-states and
+  // states-then-variants got different answers — and the rule says "a single specimen taller than
+  // its column", which says nothing about order.
+  const singleTallSpecimen = (first.itemCount === 1 && first.height > half) || (second.itemCount === 1 && second.height > half);
+  const bothFitOneRow = fitsOneRow(first, half) && fitsOneRow(second, half);
+  if (!singleTallSpecimen && !bothFitOneRow) return 'stacked';
+
   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/native/catalog/index.ts

@@ -23,7 +23,7 @@ export { ComparisonList } from './ComparisonList';
 export { ReferenceDetails } from './ReferenceDetails';
 export { PropsTable } from './PropsTable';
 export { VariantGroup } from './VariantGroup';
-export { TokenRow } from './TokenRow';
+export { TokenRow, TokenRowGroup } from './TokenRow';
 export { MotionSpecimen } from './MotionSpecimen';
 export type { MotionSpecimenProps, MotionSpecimenSpringConfig } from './MotionSpecimen';
 export { SpecimenSurface } from './SpecimenSurface';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.6.10",
+  "version": "0.7.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",

package/starter-kit/components/Tooltip/Tooltip.catalog.tsx

@@ -51,7 +51,10 @@ export default defineCatalogPage({
     ],
   },
   states: {
-    itemsFill: true,
+    // No `itemsFill`: these specimens are a small icon trigger with a floating bubble, not a
+    // block-level component that wants the row's width. Filling pins the trigger to the cell's
+    // left edge (a filled specimen aligns to start, which is right for a Banner and wrong here),
+    // and the bubble — which centres on its trigger — then overflows the cell and is clipped.
     items: [
       {
         key: 'bottom',

package/starter-kit/pages/Motion.catalog.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View, Text, StyleSheet, Easing } from 'react-native';
-import { defineCatalogPage, DividedStack, VariantGroup, TokenRow, MotionSpecimen } from '@krapwoo/ds-viewer';
+import { defineCatalogPage, TokenRow, TokenRowGroup, MotionSpecimen } from '@krapwoo/ds-viewer';
 import {
   DS_MOTION_DURATION,
   DS_MOTION_DURATION_STEPS,
@@ -26,98 +26,127 @@ const styles = StyleSheet.create({
   previewLabel: { minWidth: 64, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
   previewValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted },
   durationBar: { height: 12, borderRadius: DS_RADIUS.small, backgroundColor: DS_SEMANTIC.emphasis.info },
-  // Spring config — a wrapping grid of key/value fields, since DS_MOTION_SPRING has 6 fields, too
-  // many to lay out as a single previewRow.
-  springGrid: { flexDirection: 'row', flexWrap: 'wrap', gap: DS_SPACING[600] },
-  springField: { width: 168, gap: DS_SPACING[100] },
   easingValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted, fontFamily: 'Menlo' },
+
+  // A spring is a config object, not a step on a scale: six named fields that only mean anything
+  // together. Laid out with the fields down the side and each spring token as its own column, so a
+  // second spring adds a column instead of repeating all six names, and `damping` reads across
+  // tokens on one line. The field vocabulary is fixed; the number of tokens is what grows.
+  springRow: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: DS_SPACING[600],
+    paddingVertical: DS_SPACING[400],
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    borderColor: DS_SEMANTIC.border.light,
+  },
+  springRowLast: { borderBottomWidth: 0 },
+  // Wide enough that `restDisplacementThreshold` sits on one line instead of breaking mid-word,
+  // which is what the previous fixed 168px field did to it.
+  springField: { width: 210, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
+  springCell: { flex: 1, minWidth: 130 },
+  springValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.regular },
+  springNote: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted },
 });
 
-function MotionGallery() {
-  const maxDuration = Math.max(...Object.values(DS_MOTION_DURATION));
-  const maxLoopDuration = Math.max(...Object.values(DS_MOTION_LOOP_DURATION));
+/** Every spring token on the page. One today — the shape is what lets a second arrive without
+ *  redesigning the section. */
+const SPRINGS: Record<string, typeof DS_MOTION_SPRING> = { snappy: DS_MOTION_SPRING };
+const SPRING_NOTES: Record<string, string> = { snappy: DS_MOTION_SPRING_USE };
+const SPRING_FIELDS = Object.keys(DS_MOTION_SPRING) as (keyof typeof DS_MOTION_SPRING)[];
+
+function SpringTable() {
+  const names = Object.keys(SPRINGS);
+  const cells = (render: (name: string) => React.ReactNode) =>
+    names.map((name) => (
+      <View key={name} style={styles.springCell}>
+        {render(name)}
+      </View>
+    ));
   return (
-    <DividedStack>
-      <VariantGroup name="Duration" desc="one-shot transitions — reach for base (240ms) first" align="left">
-        <View style={styles.tokenStack}>
-          {DS_MOTION_DURATION_STEPS.map((step, i) => (
-            <TokenRow key={step} use={DS_MOTION_DURATION_USE[step]} last={i === DS_MOTION_DURATION_STEPS.length - 1}>
-              <View style={styles.rowContent}>
-                <View style={styles.previewRow}>
-                  <Text style={styles.previewLabel}>{step}</Text>
-                  <View style={[styles.durationBar, { width: (DS_MOTION_DURATION[step] / maxDuration) * 120 }]} />
-                  <Text style={styles.previewValue}>{DS_MOTION_DURATION[step]}ms</Text>
-                </View>
-                <MotionSpecimen
-                  kind="timing"
-                  duration={DS_MOTION_DURATION[step]}
-                  easing={Easing.bezier(...DS_MOTION_EASING.standard)}
-                  label={`${DS_MOTION_DURATION[step]}ms · standard easing`}
-                />
-              </View>
-            </TokenRow>
-          ))}
+    <View>
+      {/* A single spring needs no column header — the section title is already its name. */}
+      {names.length > 1 ? (
+        <View style={styles.springRow}>
+          <Text style={styles.springField}>field</Text>
+          {cells((name) => <Text style={styles.previewLabel}>{name}</Text>)}
         </View>
-      </VariantGroup>
-      <VariantGroup name="Loop duration" desc="continuous, indeterminate loops — a spinner or a shimmer pulse, not a one-shot transition" align="left">
-        <View style={styles.tokenStack}>
-          {DS_MOTION_LOOP_DURATION_STEPS.map((step, i) => (
-            <TokenRow key={step} use={DS_MOTION_LOOP_DURATION_USE[step]} last={i === DS_MOTION_LOOP_DURATION_STEPS.length - 1}>
-              <View style={styles.rowContent}>
-                <View style={styles.previewRow}>
-                  <Text style={styles.previewLabel}>{step}</Text>
-                  <View style={[styles.durationBar, { width: (DS_MOTION_LOOP_DURATION[step] / maxLoopDuration) * 120 }]} />
-                  <Text style={styles.previewValue}>{DS_MOTION_LOOP_DURATION[step]}ms</Text>
-                </View>
-                <MotionSpecimen
-                  kind="timing"
-                  duration={DS_MOTION_LOOP_DURATION[step]}
-                  easing={Easing.bezier(...DS_MOTION_EASING.standard)}
-                  label={`${DS_MOTION_LOOP_DURATION[step]}ms · one cycle`}
-                />
-              </View>
-            </TokenRow>
-          ))}
+      ) : null}
+      {SPRING_FIELDS.map((field) => (
+        <View key={String(field)} style={styles.springRow}>
+          <Text style={styles.springField}>{String(field)}</Text>
+          {cells((name) => <Text style={styles.springValue}>{String(SPRINGS[name][field])}</Text>)}
         </View>
-      </VariantGroup>
-      <VariantGroup name="Easing" desc="cubic-bezier curves — convert with Easing.bezier(...DS_MOTION_EASING.x)" align="left">
-        <View style={styles.tokenStack}>
-          {DS_MOTION_EASING_STEPS.map((step, i) => (
-            <TokenRow key={step} use={DS_MOTION_EASING_USE[step]} last={i === DS_MOTION_EASING_STEPS.length - 1}>
-              <View style={styles.rowContent}>
-                <View style={styles.previewRow}>
-                  <Text style={styles.previewLabel}>{step}</Text>
-                  <Text style={styles.easingValue}>cubic-bezier({DS_MOTION_EASING[step].join(', ')})</Text>
-                </View>
-                <MotionSpecimen
-                  kind="timing"
-                  duration={DS_MOTION_DURATION.base}
-                  easing={Easing.bezier(...DS_MOTION_EASING[step])}
-                  label={`${DS_MOTION_DURATION.base}ms · ${step}`}
-                />
+      ))}
+      <View style={styles.springRow}>
+        <Text style={styles.springField}>preview</Text>
+        {cells((name) => (
+          <MotionSpecimen kind="spring" spring={SPRINGS[name]} label="Animated.spring(value, DS_MOTION_SPRING)" />
+        ))}
+      </View>
+      <View style={[styles.springRow, styles.springRowLast]}>
+        <Text style={styles.springField}>when to use</Text>
+        {cells((name) => <Text style={styles.springNote}>{SPRING_NOTES[name]}</Text>)}
+      </View>
+    </View>
+  );
+}
+
+/** A millisecond scale: a bar for the relative length, then the real animation at that duration. */
+function DurationRows({ steps, values, notes, label }: {
+  steps: readonly string[];
+  values: Record<string, number>;
+  notes: Record<string, string>;
+  label: (ms: number) => string;
+}) {
+  const max = Math.max(...steps.map((step) => values[step]));
+  return (
+    <TokenRowGroup>
+      <View style={styles.tokenStack}>
+        {steps.map((step, i) => (
+          <TokenRow key={step} use={notes[step]} last={i === steps.length - 1} notePlacement="right">
+            <View style={styles.rowContent}>
+              <View style={styles.previewRow}>
+                <Text style={styles.previewLabel}>{step}</Text>
+                <View style={[styles.durationBar, { width: (values[step] / max) * 120 }]} />
+                <Text style={styles.previewValue}>{values[step]}ms</Text>
               </View>
-            </TokenRow>
-          ))}
-        </View>
-      </VariantGroup>
-      <VariantGroup name="Spring" desc="for Animated.spring(value, DS_MOTION_SPRING) — snap-point transitions, not fixed-duration timing">
-        <View style={styles.tokenStack}>
-          <TokenRow use={DS_MOTION_SPRING_USE} last>
+              <MotionSpecimen
+                kind="timing"
+                duration={values[step]}
+                easing={Easing.bezier(...DS_MOTION_EASING.standard)}
+                label={label(values[step])}
+              />
+            </View>
+          </TokenRow>
+        ))}
+      </View>
+    </TokenRowGroup>
+  );
+}
+
+function EasingRows() {
+  return (
+    <TokenRowGroup>
+      <View style={styles.tokenStack}>
+        {DS_MOTION_EASING_STEPS.map((step, i) => (
+          <TokenRow key={step} use={DS_MOTION_EASING_USE[step]} last={i === DS_MOTION_EASING_STEPS.length - 1} notePlacement="right">
             <View style={styles.rowContent}>
-              <View style={styles.springGrid}>
-                {(Object.entries(DS_MOTION_SPRING) as [string, number | boolean][]).map(([key, value]) => (
-                  <View key={key} style={styles.springField}>
-                    <Text style={styles.previewLabel}>{key}</Text>
-                    <Text style={styles.previewValue}>{String(value)}</Text>
-                  </View>
-                ))}
+              <View style={styles.previewRow}>
+                <Text style={styles.previewLabel}>{step}</Text>
+                <Text style={styles.easingValue}>cubic-bezier({DS_MOTION_EASING[step].join(', ')})</Text>
               </View>
-              <MotionSpecimen kind="spring" spring={DS_MOTION_SPRING} label="Animated.spring(value, DS_MOTION_SPRING)" />
+              <MotionSpecimen
+                kind="timing"
+                duration={DS_MOTION_DURATION.base}
+                easing={Easing.bezier(...DS_MOTION_EASING[step])}
+                label={`${DS_MOTION_DURATION.base}ms · ${step}`}
+              />
             </View>
           </TokenRow>
-        </View>
-      </VariantGroup>
-    </DividedStack>
+        ))}
+      </View>
+    </TokenRowGroup>
   );
 }
 
@@ -125,5 +154,44 @@ export default defineCatalogPage({
   group: 'Tokens',
   description: 'Duration (one-shot transitions), loop duration (continuous, indeterminate loops like Loading/Shimmer), easing, and spring tokens for transitions/animations. Easings are cubic-bezier tuples, not Easing objects, so the token file stays free of any react-native import. The spring config is grounded in the metro-native app this template was extracted from, where the same values drive its BottomSheet\'s snap-point transitions.',
   tokenGallery: true,
-  render: () => <MotionGallery />,
+  // A card per kind of token. Durations are a scale in milliseconds, easings are bezier curves and
+  // a spring is a config object: four different things that read as one long box when they share a
+  // single card. One column, because every section's rows want the full width.
+  tokenColumns: 1,
+  tokenSections: [
+    {
+      title: 'Duration',
+      desc: 'one-shot transitions — reach for base (240ms) first',
+      render: () => (
+        <DurationRows
+          steps={DS_MOTION_DURATION_STEPS}
+          values={DS_MOTION_DURATION}
+          notes={DS_MOTION_DURATION_USE}
+          label={(ms) => `${ms}ms · standard easing`}
+        />
+      ),
+    },
+    {
+      title: 'Loop duration',
+      desc: 'continuous, indeterminate loops — a spinner or a shimmer pulse, not a one-shot transition',
+      render: () => (
+        <DurationRows
+          steps={DS_MOTION_LOOP_DURATION_STEPS}
+          values={DS_MOTION_LOOP_DURATION}
+          notes={DS_MOTION_LOOP_DURATION_USE}
+          label={(ms) => `${ms}ms · one cycle`}
+        />
+      ),
+    },
+    {
+      title: 'Easing',
+      desc: 'cubic-bezier curves — convert with Easing.bezier(...DS_MOTION_EASING.x)',
+      render: () => <EasingRows />,
+    },
+    {
+      title: 'Spring',
+      desc: 'for Animated.spring(value, DS_MOTION_SPRING) — snap-point transitions, not fixed-duration timing',
+      render: () => <SpringTable />,
+    },
+  ],
 });

package/starter-kit/pages/Radius.catalog.tsx

@@ -1,29 +1,33 @@
 import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, TokenRow } from '@krapwoo/ds-viewer';
-import { DS_RADIUS, DS_RADIUS_STEPS, DS_RADIUS_USE, DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../tokens';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage, TokenGrid, TokenTile } from '@krapwoo/ds-viewer';
+import { DS_RADIUS, DS_RADIUS_STEPS, DS_RADIUS_USE, DS_SEMANTIC } from '../tokens';
 
 const styles = StyleSheet.create({
-  tokenStack: { gap: DS_SPACING[800] },
-  previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
-  previewLabel: { minWidth: 64, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
-  previewValue: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted },
-  radiusBox: { width: 40, height: 40, backgroundColor: DS_SEMANTIC.emphasis.info, borderWidth: StyleSheet.hairlineWidth, borderColor: DS_SEMANTIC.border.light },
+  // Square, so the corner is read as a corner rather than as the end of a bar. Large enough that
+  // 4px and 8px are still telling apart at a glance.
+  radiusBox: {
+    width: 64,
+    height: 64,
+    backgroundColor: DS_SEMANTIC.emphasis.info,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: DS_SEMANTIC.border.light,
+  },
 });
 
 function RadiusGallery() {
   return (
-    <View style={styles.tokenStack}>
-      {DS_RADIUS_STEPS.map((step, i) => (
-        <TokenRow key={step} use={DS_RADIUS_USE[step]} last={i === DS_RADIUS_STEPS.length - 1}>
-          <View style={styles.previewRow}>
-            <Text style={styles.previewLabel}>{step}</Text>
-            <View style={[styles.radiusBox, { borderRadius: DS_RADIUS[step] }]} />
-            <Text style={styles.previewValue}>{DS_RADIUS[step]}px</Text>
-          </View>
-        </TokenRow>
+    // Tiles, not rows: a radius preview is small and self-contained, so the steps belong side by
+    // side where `xs` can be compared against `large` directly — which is the only way to read a
+    // scale. A row each would put them 100px apart vertically and leave the right half of every
+    // row empty.
+    <TokenGrid minTileWidth={150}>
+      {DS_RADIUS_STEPS.map((step) => (
+        <TokenTile key={step} name={step} value={`${DS_RADIUS[step]}px`} note={DS_RADIUS_USE[step]}>
+          <View style={[styles.radiusBox, { borderRadius: DS_RADIUS[step] }]} />
+        </TokenTile>
       ))}
-    </View>
+    </TokenGrid>
   );
 }
 

package/starter-kit/pages/Shadow.catalog.tsx

@@ -1,28 +1,40 @@
 import React from 'react';
-import { View, Text, StyleSheet } from 'react-native';
-import { defineCatalogPage, TokenRow } from '@krapwoo/ds-viewer';
-import { DS_RADIUS, DS_SEMANTIC, DS_SHADOW, DS_SHADOW_USE, DS_SPACING, DS_TYPOGRAPHY, type ShadowToken } from '../tokens';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage, TokenGrid, TokenTile } from '@krapwoo/ds-viewer';
+import { DS_RADIUS, DS_SEMANTIC, DS_SHADOW, DS_SHADOW_USE, DS_SPACING, type ShadowToken } from '../tokens';
 
 const styles = StyleSheet.create({
-  tokenStack: { gap: DS_SPACING[800] },
-  previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
-  previewLabel: { minWidth: 64, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
-  shadowBox: { width: 56, height: 40, borderRadius: DS_RADIUS.medium, backgroundColor: DS_SEMANTIC.surface.white },
+  // A shadow is cast *onto* something. On the catalog's own white card the elevated surface is
+  // white on white and the token reads as an empty space, so each tile gives it a tinted backdrop
+  // to fall on — the same reason a product screen sits a card on a page colour, not on paper.
+  stage: {
+    backgroundColor: DS_SEMANTIC.surface.main,
+    borderRadius: DS_RADIUS.small,
+    paddingVertical: DS_SPACING[800],
+    alignItems: 'center',
+  },
+  surface: {
+    width: 76,
+    height: 48,
+    borderRadius: DS_RADIUS.medium,
+    backgroundColor: DS_SEMANTIC.surface.white,
+  },
 });
 
 function ShadowGallery() {
   const steps = Object.keys(DS_SHADOW) as ShadowToken[];
   return (
-    <View style={styles.tokenStack}>
-      {steps.map((step, i) => (
-        <TokenRow key={step} use={DS_SHADOW_USE[step]} last={i === steps.length - 1}>
-          <View style={styles.previewRow}>
-            <Text style={styles.previewLabel}>{step}</Text>
-            <View style={[styles.shadowBox, DS_SHADOW[step]]} />
+    // Tiles: an elevation preview is small and self-contained, and seeing `resting` beside
+    // `bottomSheet` is the only way to judge how much stronger one lift is than another.
+    <TokenGrid minTileWidth={170}>
+      {steps.map((step) => (
+        <TokenTile key={step} name={step} note={DS_SHADOW_USE[step]}>
+          <View style={styles.stage}>
+            <View style={[styles.surface, DS_SHADOW[step]]} />
           </View>
-        </TokenRow>
+        </TokenTile>
       ))}
-    </View>
+    </TokenGrid>
   );
 }