@krapwoo/ds-viewer 0.6.8 → 0.6.10

package/README.md

@@ -65,6 +65,13 @@ npm run ds-viewer doctor   # checks every page for drift and coverage gaps (--js
 npm run ds-viewer explain <Page>   # prints why a page's specimens are laid out the way they are
 ```
 
+Only one `dev` serves a project at a time. A second one refuses, naming the port the first is on,
+because both would generate into the same `.ds-viewer/` and overwrite each other's files — the
+loser then serves a workspace that no longer describes it, which Expo reports as an unresolvable
+`main` field rather than as a second server. To run two deliberately, give one its own directory
+with `--workspace-dir .ds-viewer-second`. A lock left behind by a crashed `dev` never blocks the
+next one.
+
 `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 —
@@ -495,6 +502,22 @@ Button
     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.
+
+  The catalog also warns at render time when a page under-declares the width its examples need.
+  A `PhoneFrame` given a cell narrower than the 375px device scales the whole phone down, and its
+  own body text shrinks with it, so it reports the page, the example and the cell:
+
+      [Catalog] BottomSheet (variants/content-only) is shown at 75% of device size: its cell is
+      283px, narrower than the 375px device. Declare a larger specimenSize so the example keeps
+      the width it is used at.
+
+  `check:catalog` fails on any `[Catalog]` warning, so this is caught in CI. The threshold is 95%,
+  not 100%: a regular cell leaves 370px for a 375px device, and warning about a reduction nobody
+  can see would only train you to ignore the warning. Where the scaling *is* the subject — a page
+  documenting that a narrow cell shrinks the device rather than reflowing it — write
+  `<PhoneFrame intentionalScale>` in that example, so the exemption is visible where the decision
+  was made.
+
   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;

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 { workspacePath, writeWorkspace } from "./workspace.js";
+import { clearDevLock, liveDevLock, 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";
@@ -19,6 +19,11 @@ import { localInstallRefusal } from "./update.js";
 import { DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR } from "./types.js";
 export class LocalInstallMissingError extends Error {
 }
+/** Another `dev` already owns this project's generated workspace. Its own class so `main` can
+ *  print the message plainly, the way it already does for a missing local install, instead of a
+ *  stack trace. */
+export class DevWorkspaceBusyError extends Error {
+}
 const IGNORED_WATCH_SEGMENTS = new Set([DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR, 'node_modules', '.git']);
 /** False for a changed path under `.ds-viewer/` (package-owned output — reacting to it would make
  *  `dev`'s own `sync` retrigger itself), `node_modules/`, or `.git/`; true for everything else, so
@@ -285,6 +290,9 @@ export async function performRestart(handoff, deps = {}) {
         if (!exited)
             killGroup(handoff.child, 'SIGKILL');
         await waitForPortFree(handoff.port, deps.probePortFree ?? defaultProbePortFree);
+        // Released before the replacement starts. This process stays alive as the new `dev`'s
+        // supervisor, so a lock still naming it would make its own replacement refuse the workspace.
+        clearDevLock({ projectRoot: handoff.projectRoot, workspaceDir: handoff.workspaceDir });
         // The old child is gone and the port is free — if a signal arrived in the window above (before
         // there was anything to forward it to), this restart is itself cancelled: the user asked to
         // stop, not to come back up on the new version.
@@ -352,6 +360,22 @@ export async function dev(initialConfig, devOptions = {}) {
         rmSync(statusFile, { force: true });
     }
     const port = await findFreePort(devOptions.pinnedPort ?? 5181, devOptions.pinnedPort ?? 5199);
+    // Refused before anything is written: a second `dev` on the same workspace rewrites entry.tsx,
+    // package.json, app.json, metro.config.js and tsconfig.json underneath the first, and the loser
+    // ends up serving a workspace that no longer describes it — Expo reports that as an unresolvable
+    // `main` field, which names neither the other server nor the shared directory.
+    const existing = liveDevLock(config);
+    if (existing) {
+        throw new DevWorkspaceBusyError([
+            `Another ds-viewer dev (pid ${existing.pid}) is already serving this project at http://localhost:${existing.port}.`,
+            '',
+            `Both would generate into ${config.workspaceDir ?? DEFAULT_WORKSPACE_DIR}/ and overwrite each other's files.`,
+            '',
+            'Stop that one first, or give this run its own directory:',
+            `  npx ds-viewer dev --workspace-dir .ds-viewer-second`,
+        ].join('\n'));
+    }
+    writeDevLock(config, { pid: process.pid, port });
     console.log(`Starting the catalog at http://localhost:${port}`);
     let watchersPaused = false;
     // Metro's own child process doesn't exist yet — assigned below, well before this is ever read
@@ -375,7 +399,7 @@ export async function dev(initialConfig, devOptions = {}) {
             },
             restart: async (result) => {
                 writeFileSync(statusFile, JSON.stringify({ phase: 'success', ...result }));
-                await performRestart({ projectRoot: config.projectRoot, port, child, watchers, endpointServer, doctorSummary: result.doctorSummary, files: result.files });
+                await performRestart({ projectRoot: config.projectRoot, workspaceDir: config.workspaceDir, port, child, watchers, endpointServer, doctorSummary: result.doctorSummary, files: result.files });
             },
         }).catch((error) => {
             // `performUpdate` only reports 'failure' from its own guarded steps; anything thrown outside
@@ -486,6 +510,10 @@ export async function dev(initialConfig, devOptions = {}) {
         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;
     });
     // Node's default SIGTERM/SIGINT/SIGHUP behavior exits this process without touching its
@@ -499,6 +527,7 @@ export async function dev(initialConfig, devOptions = {}) {
             for (const watcher of watchers)
                 watcher.close();
             endpointServer?.close();
+            clearDevLock(config);
             killGroup(child, signal);
             process.exit(0);
         });

package/dist/cli/explain.js

@@ -70,7 +70,7 @@ function toSectionDef(page) {
         hide: (page.hideVariants || page.hideStates) ? { variants: page.hideVariants, states: page.hideStates } : undefined,
     };
 }
-function explainBlock(block) {
+function explainBlock(block, availableWidth) {
     if (block.kind === 'grid') {
         const rows = axisItems(block.comparison.rows).length;
         const columns = axisItems(block.comparison.columns).length;
@@ -82,10 +82,10 @@ function explainBlock(block) {
         };
     }
     if (block.kind === 'list') {
-        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, block.size, block.maxColumns);
+        const geometry = listGeometry(block.items.length, availableWidth, block.size, block.maxColumns);
         return {
             kind: 'list', title: block.title,
-            reason: `${block.items.length} items (${block.size}) → ${geometry.columns} columns × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
+            reason: `${block.items.length} items (${block.size}) → ${geometry.columns} column${geometry.columns === 1 ? '' : 's'} × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
                 (geometry.fillers > 0 ? ` (${geometry.fillers} filler${geometry.fillers === 1 ? '' : 's'})` : '') + '.' +
                 surfaceOverrideNote(block.items) + alignOverrideNote(block.items),
         };
@@ -149,29 +149,40 @@ export function explainPage(config, pageId, options = {}) {
         return { pageId, notCheckable: true, blocks: [] };
     const def = toSectionDef(page);
     const blocks = presentationBlocks(def, { defaultPreviewWidths: [402] });
-    const explained = blocks.map(explainBlock);
+    // Two blocks placed side by side get half the row each, which changes how many columns fit.
+    // Reporting the full-width counts for a page the viewer will halve states the wrong geometry as
+    // fact, so the width every block is measured at follows the placement decision.
+    const full = MATRIX_LAYOUT.laptopContentWidth;
+    const half = Math.floor((full - CATALOG_LAYOUT.blockGap) / 2);
     let placement;
+    let blockWidth = full;
     if (blocks.length === 2) {
         if (options.heights) {
             const [firstHeight, secondHeight] = options.heights;
             const decision = choosePlacement({
-                available: MATRIX_LAYOUT.laptopContentWidth,
+                available: full,
                 gap: CATALOG_LAYOUT.blockGap,
                 first: toPlacementBlock(blocks[0], firstHeight),
                 second: toPlacementBlock(blocks[1], secondHeight),
             });
+            if (decision === 'side')
+                blockWidth = half;
             placement = {
                 decision,
-                reason: `With heights ${firstHeight}px/${secondHeight}px on a 1280px laptop (${MATRIX_LAYOUT.laptopContentWidth}px content width): ${decision}.`,
+                reason: `With heights ${firstHeight}px/${secondHeight}px on a 1280px laptop (${full}px content width): ${decision}` +
+                    (decision === 'side' ? `, so each block gets ${half}px.` : `, so each block gets the full ${full}px.`),
             };
         }
         else {
             placement = {
                 decision: 'decided-in-viewer',
-                reason: "Side-by-side placement depends on each block's measured height — decided in the viewer at runtime. Pass --heights <first>,<second> to check it here.",
+                reason: "Side-by-side placement depends on each block's measured height — decided in the viewer at runtime. " +
+                    `The counts above are for the full ${full}px row; side by side each block gets ${half}px instead, which can fit fewer columns. ` +
+                    'Pass --heights <first>,<second> to resolve it here.',
             };
         }
     }
+    const explained = blocks.map((block) => explainBlock(block, blockWidth));
     return { pageId, blocks: explained, placement, intentionalStaticPreviewReason: page.intentionalStaticPreviewReason };
 }
 export function formatExplain(result) {

package/dist/cli/workspace.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { globBaseFolder } from "./glob.js";
 import { DEFAULT_WORKSPACE_DIR } from "./types.js";
@@ -105,6 +105,52 @@ function projectIncludeGlobs(config) {
 export function workspacePath(config, ...segments) {
     return path.join(config.projectRoot, config.workspaceDir ?? DEFAULT_WORKSPACE_DIR, ...segments);
 }
+const LOCK_FILE = 'dev-lock.json';
+/** Records which `dev` owns this workspace, so a second one can refuse instead of writing over it.
+ *  Two servers sharing one directory both rewrite `entry.tsx`, `package.json`, `app.json`,
+ *  `metro.config.js` and `tsconfig.json`, and the loser is left serving a workspace that no longer
+ *  describes it — reported by Expo as an unresolvable `main` field, which names neither cause. */
+export function writeDevLock(config, lock) {
+    mkdirSync(workspacePath(config), { recursive: true });
+    writeFileSync(workspacePath(config, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`);
+}
+export function clearDevLock(config) {
+    rmSync(workspacePath(config, LOCK_FILE), { force: true });
+}
+/** True when `pid` is a process this user can signal. Signal 0 performs the permission and
+ *  existence checks without delivering anything. EPERM means it exists but belongs to someone
+ *  else, which still counts as alive. */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** The live `dev` already serving this workspace, or undefined when there isn't one.
+ *
+ *  A lock left behind by a crashed process is not live, so it never blocks a restart: the pid is
+ *  gone and the file is ignored. `ownPid` is excluded so a process cannot find itself — `dev`'s own
+ *  restart path re-enters this with the lock it just wrote. */
+export function liveDevLock(config, ownPid = process.pid) {
+    const lockPath = workspacePath(config, LOCK_FILE);
+    if (!existsSync(lockPath))
+        return undefined;
+    let lock;
+    try {
+        lock = JSON.parse(readFileSync(lockPath, 'utf8'));
+    }
+    catch {
+        return undefined; // A partial write from a process that died mid-write owns nothing.
+    }
+    if (typeof lock.pid !== 'number' || typeof lock.port !== 'number')
+        return undefined;
+    if (lock.pid === ownPid || !processAlive(lock.pid))
+        return undefined;
+    return lock;
+}
 /** 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.

package/native/catalog/PhoneFrame.tsx

@@ -1,7 +1,7 @@
-import React, { useState } from 'react';
+import React, { useState, useRef } from 'react';
 import { Platform, StyleSheet, Text, View, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
-import { DEVICE_FRAME, deviceFrameScale } from './deviceFrame';
+import { DEVICE_FRAME, DEVICE_SCALE_WARN_BELOW, deviceFrameScale } from './deviceFrame';
 import { resolveOverlayViewport } from './overlayViewport';
 import { useSpecimenAddress } from './SpecimenAddress';
 
@@ -27,7 +27,16 @@ function isWeb(): boolean {
  * Purely a documentation device: a real app screen never frames itself, so this lives in the
  * catalog framework rather than in an app's component library.
  */
-export function PhoneFrame({ children }: { children: React.ReactNode }) {
+export function PhoneFrame({
+  children,
+  intentionalScale = false,
+}: {
+  children: React.ReactNode;
+  /** This example is *about* the scaling — a page demonstrating that a narrow cell shrinks the
+   *  device rather than reflowing it. Declared here, in the example itself, so the exemption is
+   *  visible where the decision was made instead of hidden in config. */
+  intentionalScale?: boolean;
+}) {
   const address = useSpecimenAddress();
   const [available, setAvailable] = useState(0);
   const [status, setStatus] = useState<'loading' | 'ready' | 'unavailable'>('loading');
@@ -36,6 +45,23 @@ export function PhoneFrame({ children }: { children: React.ReactNode }) {
     if (width > 0 && width !== available) setAvailable(width);
   };
   const scale = deviceFrameScale(available);
+  // A scaled device is a page that under-declared its width: the cell it was given is narrower
+  // than the phone, so the whole viewport shrinks and the example's own text shrinks with it,
+  // which is not the size anyone reads the component at. The scale is already computed, so this
+  // needs no measurement of its own. Guarded to once per transition, like TokenSections' own
+  // degradation warning; `check:catalog` fails on any [Catalog] warning, so this blocks CI.
+  const warnedScale = useRef<string | undefined>(undefined);
+  if (!intentionalScale && available > 0 && scale < DEVICE_SCALE_WARN_BELOW && (globalThis as { __DEV__?: boolean }).__DEV__) {
+    const key = `${available}`;
+    if (warnedScale.current !== key) {
+      warnedScale.current = key;
+      const where = address ? `${address.pageId} (${address.slot}/${address.itemKey})` : 'a PhoneFrame';
+      console.warn(
+        `[Catalog] ${where} is shown at ${Math.round(scale * 100)}% of device size: its cell is ${available}px, ` +
+          `narrower than the ${DEVICE_FRAME.width}px device. Declare a larger specimenSize so the example keeps the width it is used at.`,
+      );
+    }
+  }
   // Until the cell is measured, fit it at the device's proportions rather than drawing at full size
   // for a frame (which would briefly overflow a cell narrower than the device).
   const box = available > 0

package/native/catalog/deviceFrame.ts

@@ -12,3 +12,12 @@ export function deviceFrameScale(availableWidth: number): number {
   if (!(availableWidth > 0)) return 1;
   return Math.min(1, availableWidth / DEVICE_FRAME.width);
 }
+
+/** Below this, a device is scaled enough that its own text is no longer the size a reader sees it
+ *  at, and the page should declare a wider specimen instead.
+ *
+ *  Not exactly 1. A regular cell leaves 370px for a 375px device — a 1.3% reduction nobody can
+ *  see, and warning about it would train authors to ignore the warning. The cases worth a page's
+ *  attention are the ones that shrink a phone by a tenth or more: a 283px cell renders the device
+ *  at 75%, which is the difference between readable body text and not. */
+export const DEVICE_SCALE_WARN_BELOW = 0.95;

package/package.json

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

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

@@ -5,7 +5,9 @@ import { Banner } from './Banner';
 export default defineCatalogPage({
   component: 'Banner',
   group: 'Components',
-  specimenSize: 'regular',
+  // Spans the screen: 'wide' keeps a 402px minimum, so two blocks never share a row and each
+  // specimen keeps a width the component is actually used at.
+  specimenSize: 'wide',
   composedOf: [
     { component: 'AnimatedChevron', role: "The expand/collapse chevron in the header of a collapsible banner.", relationship: 'built-in' },
   ],

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

@@ -65,6 +65,10 @@ const dock = (close: () => void) => (
 export default defineCatalogPage({
   component: 'BottomSheet',
   group: 'Components',
+  // Every example is a phone. At the default size two blocks share the row and each cell falls to
+  // 270px, which squeezes the frame until the sheet's own text is barely readable — 'wide' keeps a
+  // 402px minimum, the width the sheet is actually used at.
+  specimenSize: 'wide',
   composedOf: [
     { component: 'TopNav', role: "The header slot, typically a TopNav with a close or back action.", relationship: 'slot' },
     { component: 'Dock', role: "The footer slot, typically a Dock with the sheet's primary actions; a Dock footer gets its shadow once the content scrolls.", relationship: 'slot' },

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

@@ -33,6 +33,9 @@ function Demo({ title, body, actions }: { title: string; body?: string; actions:
 export default defineCatalogPage({
   component: 'Dialog',
   group: 'Components',
+  // Every example is a phone. The default size left 283px for a 375px device, rendering it at 75%
+  // — small enough that the dialog's own body text stopped being the size a reader sees.
+  specimenSize: 'wide',
   composedOf: [
     { component: 'ButtonGroup', role: "Lays out the dialog's actions; a dialog's own children decide this, not Dialog.", relationship: 'related' },
   ],

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

@@ -13,9 +13,9 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'FieldContainer',
   group: 'Components',
-  whenToUse: 'Building a new kind of field. It carries the shared field chrome and reads the ambient Surface tone, so it stays visible on white and on muted backgrounds alike. For the fields that already exist, use InputField or TextArea instead of wrapping this yourself.',
+  whenToUse: 'Building a new kind of field. It carries the shared field chrome and reads the ambient SurfaceScope tone, so it stays visible on white and on muted backgrounds alike. For the fields that already exist, use InputField or TextArea instead of wrapping this yourself.',
   composedOf: [
-    { component: 'Surface', role: "Reads the surrounding Surface tone: a recessed fill on white, opaque white inside a muted Surface.", relationship: 'related' },
+    { component: 'SurfaceScope', role: "Publishes the tone this reads: a recessed fill on white, opaque white inside a muted SurfaceScope.", relationship: 'related' },
   ],
   specimenSize: 'regular',
   description: 'The shared field chrome — white surface, medium radius, a 1px border that darkens on focus and mutes when disabled — behind InputField, TextArea, Dropdown, and SearchField, so all four share one visually-consistent field look instead of each re-implementing it.',

package/starter-kit/components/FieldContainer/FieldContainer.tsx

@@ -1,16 +1,16 @@
 import React from 'react';
 import { View, Pressable, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
 import { DS_SEMANTIC, DS_RADIUS } from '../../tokens';
-import { useSurfaceTone } from '../Surface';
+import { useSurfaceTone } from '../SurfaceScope';
 import type { FieldContainerProps } from './FieldContainer.types';
 
 /**
  * The shared "field" chrome: medium radius, a 1px subtle border that darkens to border.dark on
  * focus, and a fill that contrasts with whatever it's actually placed on — reads the ambient
- * `useSurfaceTone()` (see `Surface`) rather than assuming one fixed background. On the default
+ * `useSurfaceTone()` (see `SurfaceScope`) rather than assuming one fixed background. On the default
  * white tone it's a translucent recessed fill (the same adaptive-overlay mechanism SegmentedToggle's
  * track and Button's own `secondary` variant use); on a `muted` surface (wrapped in
- * `<Surface tone="muted">`) it flips to opaque white instead, so it never goes invisible against
+ * `<SurfaceScope tone="muted">`) it flips to opaque white instead, so it never goes invisible against
  * whatever's behind it either way. It owns *only* the container look — consumers (InputField,
  * TextArea, SearchField) supply their own layout (height, padding, content) via `style` and
  * children, so a single-line row and a multiline area stay visually consistent.

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

@@ -21,7 +21,7 @@ export default defineCatalogPage({
   specimenSize: 'regular',
   composedOf: [
     { component: 'InputClearButton', role: "The clear (\u00d7) button, shown while the field has a value and is focused (or active, when not editable).", relationship: 'built-in' },
-    { component: 'Surface', role: 'Reads the surrounding Surface tone so the field stays visible on a muted Surface.', relationship: 'related' },
+    { component: 'SurfaceScope', role: 'Publishes the tone this reads, so the field stays visible on a muted background.', relationship: 'related' },
   ],
   description: 'A floating-label field. Resting: a centred, body-sized label with no border. Active (focused, or picker with active set) or filled: the label floats to a small top caption, row 2 shows the value/input, and a border fades in while active.',
   whenToUse: 'A named field with a fixed identity ("To", "Arrive by") across the interaction. For free-text search with no floating label, use SearchField; for one of a small known set of choices, use Dropdown.',

package/starter-kit/components/InputField/InputField.tsx

@@ -12,7 +12,7 @@ import {
   type TextInputProps,
 } from 'react-native';
 import { InputClearButton } from '../InputClearButton';
-import { useSurfaceTone } from '../Surface';
+import { useSurfaceTone } from '../SurfaceScope';
 import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_TYPOGRAPHY, DS_FONT_WEIGHT } from '../../tokens';
 import { Icon } from '../../icons/Icon.native';
 import type { IconName } from '../../icons';

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

@@ -0,0 +1,78 @@
+import React from 'react';
+import { Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { SurfaceScope } from './SurfaceScope';
+import { InputField } from '../InputField';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  surfaceDemo: { height: 96, justifyContent: 'center', alignItems: 'center', padding: DS_SPACING[800] },
+  surfaceText: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.regular },
+  fieldDemo: { padding: DS_SPACING[800], gap: DS_SPACING[400] },
+});
+
+export default defineCatalogPage({
+  component: 'SurfaceScope',
+  group: 'Components',
+  a11y: 'No semantics of its own: it renders a plain filled View and passes its tone down through context, so it adds nothing to the accessibility tree and neither groups nor labels what sits inside it.',
+  specimenSize: 'regular',
+  description:
+    "Declares \"this subtree's background is tone\": renders a plain View filled with the matching token (surface.white or surface.main) and publishes that tone to everything inside it. Publishing is the half a token cannot do — DS_SEMANTIC.surface.* already holds the values, but a value cannot tell a descendant what it is sitting on.",
+  whenToUse:
+    "Wrap a screen (or any region) wherever its background isn't the default white. Reach for it whenever something inside needs to contrast with the background rather than assume white — that is what makes this a component rather than just the surface.* tokens it paints with.",
+  composedOf: [
+    { component: 'InputField', role: 'One of the components that reads the published tone, via useSurfaceTone(), to pick a fill that stays visible on it.', relationship: 'related' },
+    { component: 'FieldContainer', role: 'The shared field chrome that actually does the reading, on behalf of every field built from it.', relationship: 'related' },
+  ],
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'white',
+        name: 'White',
+        props: { tone: 'white' },
+        node: (
+          <SurfaceScope tone="white" style={styles.surfaceDemo}>
+            <Text style={styles.surfaceText}>surface.white</Text>
+          </SurfaceScope>
+        ),
+      },
+      {
+        key: 'muted',
+        name: 'Muted',
+        props: { tone: 'muted' },
+        node: (
+          <SurfaceScope tone="muted" style={styles.surfaceDemo}>
+            <Text style={styles.surfaceText}>surface.main</Text>
+          </SurfaceScope>
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    // The two cells above only show which token gets painted, which a swatch could do. These show
+    // the part that needs a component: the same field, told nothing, picking a different fill
+    // because of the scope it happens to be inside.
+    items: [
+      {
+        key: 'field-on-white',
+        name: 'A field inside tone="white"',
+        node: (
+          <SurfaceScope tone="white" style={styles.fieldDemo}>
+            <InputField label="Name" value="Recessed fill" />
+          </SurfaceScope>
+        ),
+      },
+      {
+        key: 'field-on-muted',
+        name: 'The same field inside tone="muted"',
+        node: (
+          <SurfaceScope tone="muted" style={styles.fieldDemo}>
+            <InputField label="Name" value="Opaque white" />
+          </SurfaceScope>
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/SurfaceScope/SurfaceScope.tsx

@@ -0,0 +1,51 @@
+import React, { createContext, useContext, type ReactNode } from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC } from '../../tokens';
+
+export type SurfaceTone = 'white' | 'muted';
+
+// Defaults to 'white' — a screen with no explicit <SurfaceScope> ancestor is assumed to sit on a
+// white background, the common case (matches e.g. Card's own default fill).
+const SurfaceToneContext = createContext<SurfaceTone>('white');
+
+/** What background tone the nearest ancestor `<SurfaceScope>` declared (or 'white' if there isn't
+ *  one). Components that need to contrast with whatever's actually behind them — FieldContainer/
+ *  InputField today — read this instead of assuming one fixed background. */
+export function useSurfaceTone(): SurfaceTone {
+  return useContext(SurfaceToneContext);
+}
+
+export interface SurfaceScopeProps {
+  /** Which background this scope renders. Descendants read this via `useSurfaceTone()` to
+   *  automatically pick a fill that contrasts with it (e.g. a field goes white on a muted page,
+   *  recessed on a white one) instead of needing to be told individually. */
+  tone: SurfaceTone;
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+}
+
+/**
+ * Declares "this subtree's background is `tone`": renders a plain View filled with the matching
+ * token (`surface.white` or `surface.main`) **and** publishes that tone to everything inside it.
+ *
+ * The second half is the reason this is a component and not just a token. `DS_SEMANTIC.surface.*`
+ * already holds the values; what a value cannot do is tell a descendant what it is sitting on.
+ * `FieldContainer` and `InputField` call `useSurfaceTone()` to choose between a translucent
+ * recessed fill and an opaque white one, so a field stays visible either way — that only works
+ * because something above them declared the tone. This is a scoped background declaration, which
+ * is why it is named for the scope rather than for the surface itself.
+ *
+ * Wrap a screen (or any region) wherever its background isn't the default white.
+ */
+export function SurfaceScope({ tone, style, children }: SurfaceScopeProps) {
+  return (
+    <SurfaceToneContext.Provider value={tone}>
+      <View style={[tone === 'white' ? styles.white : styles.muted, style]}>{children}</View>
+    </SurfaceToneContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  white: { backgroundColor: DS_SEMANTIC.surface.white },
+  muted: { backgroundColor: DS_SEMANTIC.surface.main },
+});

package/starter-kit/components/SurfaceScope/index.ts

@@ -0,0 +1,2 @@
+export { SurfaceScope, useSurfaceTone } from './SurfaceScope';
+export type { SurfaceScopeProps, SurfaceTone } from './SurfaceScope';

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

@@ -28,7 +28,9 @@ function ToastDemo() {
 export default defineCatalogPage({
   component: 'Toast',
   group: 'Components',
-  specimenSize: 'regular',
+  // Spans the screen: 'wide' keeps a 402px minimum, so two blocks never share a row and each
+  // specimen keeps a width the component is actually used at.
+  specimenSize: 'wide',
   description: 'A transient confirmation bar. Without a variant it renders the dark surface with inverse text; a variant shifts to a pastel status color.',
   whenToUse: "Transient and self-contained, floating over the screen, expected to go away on its own or via its own action. For a persistent, in-flow message about a standing condition, use Banner.",
   a11y: 'Rendered with accessibilityRole="alert" so screen readers announce it when it appears.',

package/starter-kit/components/index.ts

@@ -27,7 +27,7 @@ export * from './SearchField';
 export * from './SectionHeader';
 export * from './SegmentedToggle';
 export * from './Shimmer';
-export * from './Surface';
+export * from './SurfaceScope';
 export * from './Switch';
 export * from './TextArea';
 export * from './Toast';

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

@@ -14,7 +14,7 @@ import { PillRow, type PillRowItem } from '../components/PillRow';
 import { SearchField } from '../components/SearchField';
 import { SectionHeader } from '../components/SectionHeader';
 import { SegmentedToggle } from '../components/SegmentedToggle';
-import { Surface } from '../components/Surface';
+import { SurfaceScope } from '../components/SurfaceScope';
 import { Toast } from '../components/Toast';
 import { Tooltip } from '../components/Tooltip';
 import { TopNav } from '../components/TopNav';
@@ -123,7 +123,7 @@ function SavedTripsDemo() {
             }
           />
         }
-        bodyWrapper={(body) => <Surface tone="muted" style={styles.savedTripsBody}>{body}</Surface>}
+        bodyWrapper={(body) => <SurfaceScope tone="muted" style={styles.savedTripsBody}>{body}</SurfaceScope>}
         contentContainerStyle={styles.savedTripsScrollContent}
         // Toasts float over the top of the screen instead of pushing the Dock down. One per
         // pending removal, newest on top; each stays mounted (visible: false) through its exit.
@@ -239,7 +239,7 @@ export default defineCatalogPage({
   composedOf: [
     { component: 'TopNav', role: "The screen header, titled Saved trips, with a Filters button.", relationship: 'built-in' },
     { component: 'Tooltip', role: "The Filter by mode hint on the Filters button.", relationship: 'built-in' },
-    { component: 'Surface', role: "The muted background behind the search, toggles and list.", relationship: 'built-in' },
+    { component: 'SurfaceScope', role: "Declares the muted background behind the search, toggles and list, so the fields inside it pick a fill that stays visible on it.", relationship: 'built-in' },
     { component: 'SearchField', role: "Searches stations.", relationship: 'built-in' },
     { component: 'SegmentedToggle', role: "Switches between List and Map views.", relationship: 'built-in' },
     { component: 'UnderlineTabs', role: "The All, Nearby and Favorites tabs.", relationship: 'built-in' },

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

@@ -1,46 +0,0 @@
-import React from 'react';
-import { Text, StyleSheet } from 'react-native';
-import { defineCatalogPage } from '@krapwoo/ds-viewer';
-import { Surface } from './Surface';
-import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
-
-const styles = StyleSheet.create({
-  surfaceDemo: { height: 96, justifyContent: 'center', alignItems: 'center', padding: DS_SPACING[800] },
-  surfaceText: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.regular },
-});
-
-export default defineCatalogPage({
-  component: 'Surface',
-  group: 'Components',
-  a11y: 'No semantics of its own: it renders a plain filled View and passes its tone down through context, so it adds nothing to the accessibility tree and neither groups nor labels what sits inside it.',
-  specimenSize: 'regular',
-  description:
-    "Declares \"this subtree's background is tone\" — renders a plain View filled with the matching token (surface.white or surface.main) and provides that tone to descendants via context, so a tone-aware component inside (e.g. FieldContainer/InputField) can automatically pick a fill that contrasts with it instead of assuming white.",
-  whenToUse:
-    "Wrap a screen (or any region) wherever its background isn't the default white — a page with a muted/grey background, for instance — so anything inside that needs to contrast with its background picks the right fill automatically.",
-  variants: {
-    itemsFill: true,
-    items: [
-      {
-        key: 'white',
-        name: 'White',
-        props: { tone: 'white' },
-        node: (
-          <Surface tone="white" style={styles.surfaceDemo}>
-            <Text style={styles.surfaceText}>surface.white</Text>
-          </Surface>
-        ),
-      },
-      {
-        key: 'muted',
-        name: 'Muted',
-        props: { tone: 'muted' },
-        node: (
-          <Surface tone="muted" style={styles.surfaceDemo}>
-            <Text style={styles.surfaceText}>surface.main</Text>
-          </Surface>
-        ),
-      },
-    ],
-  },
-});

package/starter-kit/components/Surface/Surface.tsx

@@ -1,45 +0,0 @@
-import React, { createContext, useContext, type ReactNode } from 'react';
-import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
-import { DS_SEMANTIC } from '../../tokens';
-
-export type SurfaceTone = 'white' | 'muted';
-
-// Defaults to 'white' — a screen with no explicit <Surface> ancestor is assumed to sit on a white
-// background, the common case (matches e.g. Card's own default fill).
-const SurfaceToneContext = createContext<SurfaceTone>('white');
-
-/** What background tone the nearest ancestor `<Surface>` declared (or 'white' if there isn't one).
- *  Components that need to contrast with whatever's actually behind them — FieldContainer/
- *  InputField today — read this instead of assuming one fixed background. */
-export function useSurfaceTone(): SurfaceTone {
-  return useContext(SurfaceToneContext);
-}
-
-export interface SurfaceProps {
-  /** Which background this surface renders. Descendants read this via `useSurfaceTone()` to
-   *  automatically pick a fill that contrasts with it (e.g. a field goes white on a muted page,
-   *  recessed on a white one) instead of needing to be told individually. */
-  tone: SurfaceTone;
-  style?: StyleProp<ViewStyle>;
-  children?: ReactNode;
-}
-
-/**
- * Declares "this subtree's background is `tone`" — renders a plain View filled with the matching
- * token (`surface.white` or `surface.main`) and provides that tone to descendants via context.
- * Wrap a screen (or any region) in this wherever its background isn't the default white — a page
- * with a muted/grey background, for instance — so anything inside that needs to contrast with its
- * background picks the right fill automatically rather than assuming white.
- */
-export function Surface({ tone, style, children }: SurfaceProps) {
-  return (
-    <SurfaceToneContext.Provider value={tone}>
-      <View style={[tone === 'white' ? styles.white : styles.muted, style]}>{children}</View>
-    </SurfaceToneContext.Provider>
-  );
-}
-
-const styles = StyleSheet.create({
-  white: { backgroundColor: DS_SEMANTIC.surface.white },
-  muted: { backgroundColor: DS_SEMANTIC.surface.main },
-});

package/starter-kit/components/Surface/index.ts

@@ -1,2 +0,0 @@
-export { Surface, useSurfaceTone } from './Surface';
-export type { SurfaceProps, SurfaceTone } from './Surface';