@krapwoo/ds-viewer 0.4.2 → 0.4.4

package/README.md

@@ -96,6 +96,12 @@ npm run check:catalog    # the same headless check CI runs — every page, zero
 documenting the viewer framework's own pieces (`CatalogShell`, `SectionBlock`, `ComparisonGrid`,
 …), shown under a "Viewer" group alongside the starter kit's own pages.
 
+## Contributing
+
+Found a bug or an improvement while using ds-viewer in your app? Open an issue or a pull request:
+[CONTRIBUTING.md](CONTRIBUTING.md) explains how to try a change in your own app before opening
+one, and what every pull request needs.
+
 ## Picking the right component
 
 Several components look alike but solve different problems (InputField vs. SearchField vs.
@@ -184,8 +190,28 @@ actually apply:
   within what fits a 1280px laptop: 5 compact, 3 regular, or 2 wide columns. `states` items whose
   key matches a row or column key are not repeated below the grid.
 - `specimenSize: 'compact' | 'regular' | 'wide'` — the page's specimen width class.
+- `specimenSurface: 'neutral' | 'white' | 'dark' | 'transparent'` — the catalog-owned background
+  behind every live specimen on this page (list/grouped/grid cells, and a non-token `render()`
+  preview). Defaults to `'neutral'` (a light gray stage, visibly distinct from the surrounding
+  white card) — reach for `'dark'` to check a low-contrast component against a dark background, or
+  `'transparent'` when the surface itself would be misleading (e.g. a component whose own
+  elevation/shadow needs to read against the page, not a chip). Token galleries and sections always
+  keep their current, unstaged presentation regardless of this setting.
+- `variants`/`states`' own `maxColumns: 1 | 2 | 3 | 4 | 5` — caps how many columns that slot's list
+  ever wraps into (e.g. a 3-item size scale that should always read as one row of exactly 3, never
+  more just because a laptop is wide). A narrow window still drops below the cap when it has to —
+  `maxColumns` only ever lowers the natural, width-based column count, never raises it.
 - `group` on a `states` item — the `variants` key it belongs to (a size that only exists for one
   variant). Grouped states render one row per variant; ungrouped ones go to "Other configurations".
+- `composedOf: [{ component, role, relationship }]` — what this component is built from or
+  composed with, shown as a "Composition" subsection in Quick reference. `relationship` is
+  `'built-in'` for a component always present inside this one (e.g. Toast is built from a Banner),
+  `'slot'` for an optional caller-supplied child (e.g. a `leadingIcon` prop), or `'related'` for a
+  component commonly used alongside this one without either containing the other. `component` should be
+  a real component or page id: while you browse the catalog in development, an unknown name logs a
+  `[Catalog]` warning in the browser console. `doctor` doesn't check it, and it never fails a
+  build — e.g.
+  `composedOf: [{ component: 'Icon', role: 'Leading glyph', relationship: 'slot' }]`.
 - `previewWidths: [402, 320]` — extra preview widths for a `render()` page (each capped at 402).
   `CatalogShell`'s `defaultPreviewWidths="full"` keeps a catalog's previews full width.
 - `variants: { desc?, align?, itemsFill?, items: [{ key, name, node }] }` — one item per prop enum
@@ -204,7 +230,91 @@ renders in a Preview card (phone width for components). For a token-gallery sect
 data, not a component — see `ColorsGallery`/`SpacingGallery`/`TypographyGallery`), set
 `tokenGallery: true` instead of `props`/`a11y`/`states` — `SectionBlock` then renders `render()`'s
 output full width under a "Tokens" label and shows only a Quick reference card with the source
-path.
+path. For anything beyond a single list of tokens, use the token-page layouts below.
+
+### Organising the catalog
+
+- **`group`/`groupOrder` accept any semantic category you want** — not just `Tokens` and
+  `Components`. A page's `group` is a plain string shown as its sidebar section label;
+  `groupOrder` (e.g. `['Tokens', 'Components', 'Patterns', 'Recipes', 'Experiences']`) only
+  controls which order those sections appear in, top to bottom — any group not listed sorts
+  alphabetically after the ones that are. This starter kit's own two groups (`Tokens`, then
+  `Components`) are one valid shape, not the only one: a larger catalog might add `Patterns`
+  (reusable combinations like a settings row), `Recipes` (worked end-to-end screens), or
+  `Experiences` (full flows) alongside them. Pages sort A–Z inside each group regardless of how
+  many groups you have. Avoid splitting `Components` into finer categories such as "Actions" or
+  "Status" purely to browse by — that makes readers guess where a component lives; search and A–Z
+  already find it. A distinct semantic group (Tokens vs. Components vs. Patterns) is a different
+  decision from that, since it changes what the reader expects to find there.
+- **Wide components at 3 columns.** Give block-level components (Banner, Card, Toast,
+  InputField) `specimenSize: 'regular'`, so Variants and States sit 3 across on a laptop
+  (about 316px each). `'wide'` (2 columns, phone width) is only for pages where the full phone
+  width is what you're checking, such as truncation or full-screen sheets. 4 columns is too narrow
+  for these components.
+- **Mark OS components.** When a component is, or contains, a native platform control rather than
+  a custom one (a native date picker, iOS Liquid Glass), set `osComponent: 'full'` or
+  `'partial'`. The page shows an "OS component" or "Partly OS component" badge under its title;
+  say in `description` which part is native and how it differs on web, where the native part
+  usually can't render. Custom replacements styled after a platform control (a custom switch or
+  spinner) are not OS components.
+- **Readable titles.** The page id is its address (`#ControlHeights`) and comes from the file
+  name; set `title: 'Control heights'` for the heading, sidebar and search. Pages still sort by id.
+- **Point token pages at their token file.** A token page has no component, so its Source would be
+  the page file; set `source: 'src/design-system/tokens.ts'` (project-relative) instead.
+- **Coverage only counts the component's own options.** `doctor`'s `option-not-covered` checks
+  string-literal unions declared in the component's own folder or a token folder. A union
+  declared in another component's folder, such as a shared `IconName`, is that component's
+  options, so a Banner page never needs one example per icon.
+
+### Token pages
+
+A token page shows each token at its real value with its role. Pick the layout by the token's
+shape:
+
+| Token shape | Layout | Example |
+|---|---|---|
+| Small, self-contained preview (radius, shadow, control height, a single colour) | `TokenGrid` of `TokenTile`s: equal tiles in as many columns as fit | Radius, Shadow, ControlHeights |
+| Narrow sample with a long note (icon size, spacing) | `TokenRow` with `notePlacement="right"`: one line per token | IconSizes |
+| Several kinds of token on one page | `tokenSections`: one titled card per kind | Colors (semantic vs palette) |
+| A scale with families (type) | `tokenSections` with `tokenColumns: 2` or `3`, one section per family | Typography (label, body, emphasis…) |
+| A duration/easing or spring value | `MotionSpecimen` next to the token's value | Motion (duration, easing, spring) |
+
+- **`tokenSections: [{ title, desc?, wide?, render }]`** replaces `render`. Each section is its
+  own titled card. Keep different kinds of token in different sections, never mixed: semantic roles
+  apart from raw palette ramps, each type family apart.
+- **`tokenColumns: 1 | 2 | 3`** places sections side by side. Use 2–3 for narrow sections (type
+  families); the page drops a column rather than squeeze a section under 280px. `wide: true`
+  gives a section its own full row, for wide content such as palette ramps.
+- **Show each token's role, not its category.** The note says where or why the token is used, in
+  that order of preference: the token file's own comments, then a usage scan of the code (name the
+  main components and how many files use it, and say so when a token is unused). Never invent
+  advice, and never write a generic category such as "Regular reading text" when the name and
+  value already say it. If there's nothing grounded to say, leave the note out.
+- **Label each sample with its name and real value** (`bodyMd · 16/22 · 400`, `medium · 12px`).
+  Use realistic sample text from the product, short enough to fit its column at the largest size.
+- **`MotionSpecimen`** demonstrates a duration/easing or spring token as a real, bounded
+  start-to-end slide — a dot travels a fixed track once when it mounts, with a named Replay button
+  to play it again. Give it `kind: 'timing'` with `duration` (and optionally a real `Easing`
+  function, e.g. `Easing.bezier(...DS_MOTION_EASING.standard)`) for a duration/easing token, or
+  `kind: 'spring'` with a `spring` config shaped for `Animated.spring` (e.g. `DS_MOTION_SPRING`) for
+  a spring token. It respects the platform's reduce-motion preference automatically — with it on,
+  every play (including the initial one) shows the end state immediately instead of animating, so
+  it never needs its own per-page reduce-motion handling:
+  ```tsx
+  <MotionSpecimen kind="timing" duration={DS_MOTION_DURATION.base} easing={Easing.bezier(...DS_MOTION_EASING.standard)} />
+  <MotionSpecimen kind="spring" spring={DS_MOTION_SPRING} />
+  ```
+  A spring's `valueRange` says which domain its `spring` config's rest thresholds are scaled for,
+  so the specimen animates the same domain the real config does rather than always normalizing to
+  0–1. `'distance'` (default) is for a config tuned for pixel-space points, e.g. a `BottomSheet`'s
+  snap-point spring — the `Animated.Value` animates directly from `0` to the track's pixel
+  distance. `'unit'` is for a config whose production value is a normalized 0-to-1 progress or
+  blend factor — the `Animated.Value` animates `0` to `1` and is interpolated to the pixel
+  distance; `'distance'`'s pixel-scale thresholds would otherwise end a unit-valued spring before
+  it ever moves:
+  ```tsx
+  <MotionSpecimen kind="spring" spring={UNIT_SPRING_CONFIG} valueRange="unit" />
+  ```
 
 ## Keeping the catalog current
 

package/dist/cli/doctor.js

@@ -55,7 +55,7 @@ function checkComponentExportRemoved(pages, components) {
  *  `description` — in which case the viewer shows the exact same "No examples documented." an
  *  undocumented component would. */
 function pageHasExamples(page) {
-    return Boolean(page.comparison) || Boolean(page.variantsItems?.length) || Boolean(page.statesItems?.length) || page.hasRender === true;
+    return Boolean(page.comparison) || Boolean(page.variantsItems?.length) || Boolean(page.statesItems?.length) || page.hasRender === true || Boolean(page.tokenSectionTitles?.length);
 }
 function checkComponentNoExamples(pages, components) {
     const byComponent = new Map();

package/dist/cli/explain.js

@@ -4,16 +4,15 @@ import { discoverAllPageFiles, resolvePageId } from "./pageIndex.js";
 import { resolveGlob } from "./glob.js";
 import { axisItems, choosePlacement, gridColumnLimit, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
 import { CATALOG_LAYOUT } from "../native/catalog/tokens.js";
+import { sectionColumns } from "../native/catalog/tokenLayout.js";
 function placeholderItem(item) {
     return { key: item.key, name: item.name, node: null, group: item.group };
 }
 /** A throwaway `SectionDef` built from a `StaticPage` (Task 3) — every specimen's `node` is `null`
  *  (design §4: specimen nodes are never evaluated), since none of the layout functions below ever
  *  look at it; only the counts/keys/sizes they do look at are carried over. Every field Task 3
- *  reads is carried through here, including `previewWidths`/`fullWidthLabel`/`hide`/`itemsFill` —
- *  an earlier draft dropped these four, so `explain` reported different geometry than the real
- *  viewer for any page that set one of them (25 kit pages set `itemsFill`; every `kit-host`
- *  Viewer page sets `hide`). */
+ *  reads is carried through here, including `previewWidths`/`fullWidthLabel`/`hide`/`itemsFill`/
+ *  `maxColumns` — dropping any of them makes `explain` report different geometry than the viewer. */
 function toSectionDef(page) {
     const comparison = page.comparison && {
         rowLabel: page.comparison.rowLabel ?? '',
@@ -31,10 +30,12 @@ function toSectionDef(page) {
         fullWidthLabel: page.fullWidthLabel,
         specimenSize: page.specimenSize,
         previewWidths: page.previewWidths,
-        variants: page.variantsItems ? { itemsFill: page.variantsItemsFill, items: page.variantsItems.map(placeholderItem) } : undefined,
-        states: page.statesItems ? { itemsFill: page.statesItemsFill, items: page.statesItems.map(placeholderItem) } : undefined,
+        variants: page.variantsItems ? { itemsFill: page.variantsItemsFill, maxColumns: page.variantsMaxColumns, items: page.variantsItems.map(placeholderItem) } : undefined,
+        states: page.statesItems ? { itemsFill: page.statesItemsFill, maxColumns: page.statesMaxColumns, items: page.statesItems.map(placeholderItem) } : undefined,
         comparison,
         render: page.hasRender ? () => null : undefined,
+        tokenSections: page.tokenSectionTitles?.map((title, i) => ({ title, wide: page.tokenSectionWide?.[i] || undefined, render: () => null })),
+        tokenColumns: page.tokenColumns === 2 || page.tokenColumns === 3 ? page.tokenColumns : undefined,
         hide: (page.hideVariants || page.hideStates) ? { variants: page.hideVariants, states: page.hideStates } : undefined,
     };
 }
@@ -50,7 +51,7 @@ function explainBlock(block) {
         };
     }
     if (block.kind === 'list') {
-        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, block.size);
+        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, 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'}` +
@@ -64,6 +65,19 @@ function explainBlock(block) {
         const widths = block.widths === 'full' ? 'full width' : `${block.widths.join('/')}px`;
         return { kind: 'preview', title: block.title, reason: `render() content at ${widths}.` };
     }
+    if (block.kind === 'tokenSections') {
+        const n = block.sections.length;
+        const titles = block.sections.every((s) => s.title) ? ` (${block.sections.map((s) => s.title).join(', ')})` : '';
+        const wide = block.sections.filter((s) => s.wide).length;
+        const narrow = n - wide;
+        const fit = sectionColumns(MATRIX_LAYOUT.laptopContentWidth, block.columns);
+        const parts = [];
+        if (narrow > 0)
+            parts.push(narrow > 1 && fit > 1 ? `${Math.min(fit, narrow)} side by side on a 1280px laptop` : 'one per row');
+        if (wide > 0)
+            parts.push(`${wide} full width`);
+        return { kind: 'tokenSections', title: 'Token sections', reason: `${n} section${n === 1 ? '' : 's'}${titles}: ${parts.join('; ')}.` };
+    }
     return { kind: 'empty', title: block.title, reason: block.message };
 }
 /** Mirrors `native/catalog/SectionBlock.tsx`'s own `blockWidth` helper: a list block's width is its
@@ -73,7 +87,14 @@ function explainBlock(block) {
  *  computed uniformly here for either role, since setting it on `second` is simply unused, not wrong. */
 function toPlacementBlock(block, height, available) {
     if (block.kind === 'list') {
-        return { kind: 'list', height, itemCount: block.items.length, size: block.size, width: listGeometry(block.items.length, available, block.size).containerWidth };
+        return {
+            kind: 'list',
+            height,
+            itemCount: block.items.length,
+            size: block.size,
+            maxColumns: block.maxColumns,
+            width: listGeometry(block.items.length, available, block.size, block.maxColumns).containerWidth,
+        };
     }
     return { kind: block.kind, height };
 }

package/dist/cli/props.js

@@ -97,7 +97,7 @@ export function createComponentReader(entryFiles, options = {}) {
             const type = checker.getTypeOfSymbolAtLocation(resolved, declaration);
             if (!isComponentType(checker, type))
                 continue;
-            records.push(readComponentRecord(checker, exportSymbol.getName(), type, declaration, options.optionRoots ?? []));
+            records.push(readComponentRecord(checker, exportSymbol.getName(), type, declaration, options.optionRoots ?? [], options.componentRoots ?? []));
         }
         return records.sort((a, b) => a.name.localeCompare(b.name));
     };
@@ -151,7 +151,7 @@ function isComponentType(checker, type) {
         return true;
     return COMPONENT_TYPE_HINT.test(checker.typeToString(type));
 }
-function readComponentRecord(checker, name, type, declaration, optionRoots) {
+function readComponentRecord(checker, name, type, declaration, optionRoots, componentRoots = []) {
     const sourceFile = declaration.getSourceFile();
     const signature = type.getCallSignatures()[0];
     const propsType = signature && signature.parameters.length > 0 ? checker.getTypeOfSymbolAtLocation(signature.parameters[0], declaration) : undefined;
@@ -180,7 +180,7 @@ function readComponentRecord(checker, name, type, declaration, optionRoots) {
                 required: !isPartial && merged.requiredInEvery,
                 default: implementationDefaults.get(prop.getName()) ?? (jsDocDefault ? ts.displayPartsToString(jsDocDefault.text) : undefined),
                 desc: isPartial ? `${baseDesc} Only with some variants of this prop's type.`.trim() : baseDesc,
-                options: readOptions(checker, propType, propFile, optionRoots),
+                options: readOptions(checker, propType, propFile, optionRoots, componentRoots),
             });
         }
     }
@@ -383,9 +383,10 @@ function mergeUnionProps(checker, branches) {
  * 2 or more string literals, AND that union is declared inside one of `optionRoots` — checked
  * against the union's alias symbol's declaration file (a named type like `Variant`), or the prop's
  * own declaration file for an inline union with no alias. A single string literal is never
- * options; an out-of-root union (e.g. a 44-member `IconName` from `icons/`) is skipped.
+ * options; an out-of-root union (e.g. a 44-member `IconName` from `icons/`) is skipped, and so is a
+ * union declared in a different component's folder under a component root (a sibling `Icon/`).
  */
-function readOptions(checker, propType, propDeclarationFile, optionRoots) {
+function readOptions(checker, propType, propDeclarationFile, optionRoots, componentRoots = []) {
     if (optionRoots.length === 0)
         return undefined;
     const nonNullable = checker.getNonNullableType(propType);
@@ -397,8 +398,22 @@ function readOptions(checker, propType, propDeclarationFile, optionRoots) {
     const isLocal = optionRoots.some((root) => declarationFile === root || declarationFile.startsWith(`${root}${path.sep}`));
     if (!isLocal)
         return undefined;
+    if (declarationFile !== propDeclarationFile && isInOtherComponent(declarationFile, propDeclarationFile, componentRoots))
+        return undefined;
     return nonNullable.types.map((t) => t.value);
 }
+/** True when `file` sits in a different component subfolder than `ownFile` under the same root. */
+function isInOtherComponent(file, ownFile, componentRoots) {
+    const componentOf = (target, root) => {
+        const rel = path.relative(root, target);
+        return rel.startsWith('..') || path.isAbsolute(rel) ? undefined : rel.split(path.sep)[0];
+    };
+    return componentRoots.some((root) => {
+        const theirs = componentOf(file, root);
+        const ours = componentOf(ownFile, root);
+        return theirs !== undefined && ours !== undefined && theirs !== ours && path.extname(theirs) === '';
+    });
+}
 /** Finds the real implementation function behind a `React.memo(Impl)` / `forwardRef(function
  *  Name(...) {})` wrapper and reads each destructured parameter's default initializer as source
  *  text (design §3: "shown as source text"). Resolving the *value* of a non-literal default

package/dist/cli/staticPage.js

@@ -71,6 +71,28 @@ function readStaticPage(file) {
         page.specimenSize = stringLiteral(resolve(specimenSizeProp.initializer, consts, new Set()));
     if (tokenGalleryProp)
         page.tokenGallery = resolve(tokenGalleryProp.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword;
+    const tokenSectionsProp = findProp(pageObject, 'tokenSections');
+    if (tokenSectionsProp) {
+        const list = resolve(tokenSectionsProp.initializer, consts, new Set());
+        const items = ts.isArrayLiteralExpression(list) ? list.elements.map((element) => resolve(element, consts, new Set())) : [list];
+        const field = (item, name) => (ts.isObjectLiteralExpression(item) ? findProp(item, name) : undefined);
+        page.tokenSectionTitles = items.map((item) => {
+            const title = field(item, 'title');
+            return (title && stringLiteral(resolve(title.initializer, consts, new Set()))) ?? '';
+        });
+        page.tokenSectionWide = items.map((item) => {
+            const wide = field(item, 'wide');
+            return wide ? resolve(wide.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword : false;
+        });
+        if (page.tokenSectionTitles.length > 0)
+            page.tokenGallery = true;
+    }
+    const tokenColumnsProp = findProp(pageObject, 'tokenColumns');
+    if (tokenColumnsProp) {
+        const value = resolve(tokenColumnsProp.initializer, consts, new Set());
+        if (ts.isNumericLiteral(value))
+            page.tokenColumns = Number(value.text);
+    }
     page.hasWhenToUse = findProp(pageObject, 'whenToUse') !== undefined;
     page.hasA11y = findProp(pageObject, 'a11y') !== undefined;
     page.hasRender = findProp(pageObject, 'render') !== undefined;
@@ -124,6 +146,7 @@ function readStaticPage(file) {
     else {
         page.variantsItems = variants.items;
         page.variantsItemsFill = variants.itemsFill;
+        page.variantsMaxColumns = variants.maxColumns;
     }
     const states = readSlotItems(findProp(pageObject, 'states'), consts);
     if (!states.checkable)
@@ -131,6 +154,7 @@ function readStaticPage(file) {
     else {
         page.statesItems = states.items;
         page.statesItemsFill = states.itemsFill;
+        page.statesMaxColumns = states.maxColumns;
     }
     return page;
 }
@@ -335,11 +359,12 @@ function readLiteralProps(node, consts) {
     }
     return result;
 }
-/** A `variants`/`states` field: `{ itemsFill?, items: [...] }`, `items` read by `readListItems`.
- *  Distinguishes "field absent" (always checkable, everything undefined) from "field present but
- *  not literal" (not checkable). `itemsFill` is read only if present and literal — like
- *  `previewWidths`/`fullWidthLabel`, it isn't in design §4's literal-checkable list, so a
- *  non-literal `itemsFill` is simply left unset, never a reason to reject the whole slot. */
+/** A `variants`/`states` field: `{ itemsFill?, maxColumns?, items: [...] }`, `items` read by
+ *  `readListItems`. Distinguishes "field absent" (always checkable, everything undefined) from
+ *  "field present but not literal" (not checkable). `itemsFill` is read only if present and
+ *  literal — like `previewWidths`/`fullWidthLabel`, it isn't in the original literal-checkable
+ *  list, so a non-literal `itemsFill` is simply left unset. `maxColumns` does affect the geometry
+ *  `explain` reports, so it must be a literal integer from 1–5 or the page is not checkable. */
 function readSlotItems(prop, consts) {
     if (!prop)
         return { checkable: true };
@@ -352,5 +377,16 @@ function readSlotItems(prop, consts) {
         return { checkable: false };
     const itemsFillProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'itemsFill') : undefined;
     const itemsFill = itemsFillProp ? resolve(itemsFillProp.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword : undefined;
-    return { items, itemsFill, checkable: true };
+    const maxColumnsProp = ts.isObjectLiteralExpression(resolved) ? findProp(resolved, 'maxColumns') : undefined;
+    let maxColumns;
+    if (maxColumnsProp) {
+        const value = resolve(maxColumnsProp.initializer, consts, new Set());
+        if (!ts.isNumericLiteral(value))
+            return { checkable: false };
+        const parsed = Number(value.text);
+        if (!Number.isInteger(parsed) || parsed < 1 || parsed > 5)
+            return { checkable: false };
+        maxColumns = parsed;
+    }
+    return { items, itemsFill, maxColumns, checkable: true };
 }

package/dist/cli/sync.js

@@ -49,7 +49,8 @@ export function sync(config, resolveOptions) {
     const fallbackPaths = hasEntryOutsideProjectRoot
         ? { '*': [path.join(config.projectRoot, 'node_modules', '@types', '*'), path.join(config.projectRoot, 'node_modules', '*')] }
         : undefined;
-    const readComponent = createComponentReader(componentEntryFiles, { ...resolveOptions, optionRoots, fallbackPaths });
+    const componentRoots = [...new Set(config.components.map((pattern) => path.join(config.projectRoot, globBaseFolder(pattern))))];
+    const readComponent = createComponentReader(componentEntryFiles, { ...resolveOptions, optionRoots, componentRoots, fallbackPaths });
     const warnings = [];
     for (const entryFile of componentEntryFiles) {
         try {

package/dist/native/catalog/catalogNavigation.js

@@ -34,12 +34,14 @@ export function neighbors(order, id) {
     };
 }
 /** Sidebar filter: case-insensitive substring match, sorted ids, empty groups removed. */
-export function filterGroups(groups, query) {
+export function filterGroups(groups, query, 
+/** Display titles by id; a page matches on its id or its title. */
+labels) {
     const q = query.trim().toLowerCase();
     return groups
         .map((group) => ({
         label: group.label,
-        ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q)) : group.ids),
+        ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q) || (labels?.get(id)?.toLowerCase().includes(q) ?? false)) : group.ids),
     }))
         .filter((group) => group.ids.length > 0);
 }

package/dist/native/catalog/comparison.js

@@ -75,13 +75,18 @@ export function gridWidthBounds(columnCount, size) {
 /** Balanced wrapping for a one-axis list inside a single bordered card (1px outer border). Each
  *  cell's 1px divider sits inside its own width, so no cell is ever wider than 402px. Uses as few
  *  rows as fit, then spreads items evenly across them so a short last row leaves as little empty
- *  space as possible. `fillers` blank cells complete the last row. */
-export function listGeometry(itemCount, availableWidth, size) {
+ *  space as possible. `fillers` blank cells complete the last row. `columnCap` (from
+ *  `VariantSlot.maxColumns`) only ever lowers the natural, width-based column count — a narrow
+ *  container still drops below it when it has to, so the cap can never widen a row past what the
+ *  available width actually fits. */
+export function listGeometry(itemCount, availableWidth, size, columnCap) {
     if (itemCount <= 0)
         return { columns: 0, rows: 0, fillers: 0, cellWidth: 0, containerWidth: 0 };
     const inner = Math.max(0, availableWidth - 2);
     const min = COLUMN_MIN_WIDTH[size];
-    const maxColumns = Math.max(1, Math.min(itemCount, Math.floor(inner / min)));
+    const widthLimit = Math.floor(inner / min);
+    const limit = columnCap !== undefined ? Math.min(widthLimit, columnCap) : widthLimit;
+    const maxColumns = Math.max(1, Math.min(itemCount, limit));
     const rows = Math.ceil(itemCount / maxColumns);
     const columns = Math.ceil(itemCount / rows);
     const fitted = Math.floor(inner / columns);
@@ -213,6 +218,10 @@ function groupStates(variants, states) {
  *  never shows an empty block next to a real one; with nothing documented at all it shows one
  *  "No examples documented." block. */
 export function presentationBlocks(def, options = {}) {
+    if (def.tokenSections && def.tokenSections.length > 0) {
+        // Each section carries its own label, so the block itself has none.
+        return [{ kind: 'tokenSections', title: '', sections: def.tokenSections, columns: def.tokenColumns ?? 1 }];
+    }
     if (def.tokenGallery) {
         const title = def.fullWidthLabel ?? 'Tokens';
         return [def.render ? { kind: 'preview', title, widths: 'full' } : { kind: 'empty', title, message: 'Nothing to preview.' }];
@@ -237,7 +246,13 @@ export function presentationBlocks(def, options = {}) {
             states = grouped.leftovers;
         }
         else if (def.variants) {
-            blocks.push({ kind: 'list', title: 'Variants', size: slotSize(def, def.variants), items: slotItems(def.variants) });
+            blocks.push({
+                kind: 'list',
+                title: 'Variants',
+                size: slotSize(def, def.variants),
+                items: slotItems(def.variants),
+                ...(def.variants.maxColumns !== undefined ? { maxColumns: def.variants.maxColumns } : {}),
+            });
         }
         else if (def.render) {
             blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
@@ -250,6 +265,7 @@ export function presentationBlocks(def, options = {}) {
             title: secondary ? 'Other configurations' : 'States / configurations',
             size: slotSize(def, states),
             items: slotItems(states),
+            ...(states.maxColumns !== undefined ? { maxColumns: states.maxColumns } : {}),
         });
     }
     if (blocks.length === 0 && !hide.variants && !hide.states) {
@@ -270,8 +286,8 @@ export function choosePlacement({ available, gap, first, second }) {
     const minCell = second.size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : COLUMN_MIN_WIDTH[second.size];
     if (room < minCell + 2)
         return 'stacked';
-    const stackedRows = listGeometry(second.itemCount, available, second.size).rows;
-    const sideRows = listGeometry(second.itemCount, room, second.size).rows;
+    const stackedRows = listGeometry(second.itemCount, available, second.size, second.maxColumns).rows;
+    const sideRows = listGeometry(second.itemCount, room, second.size, second.maxColumns).rows;
     const rowHeight = second.height / Math.max(1, stackedRows);
     const sideHeight = Math.max(first.height, sideRows * rowHeight);
     const stackedHeight = first.height + gap + second.height;

package/dist/native/catalog/tokenLayout.js

@@ -0,0 +1,26 @@
+/**
+ * Pure layout maths for token pages — no React or React Native runtime imports, so it is unit
+ * tested directly (`__tests__/tokenLayout.test.ts`).
+ *
+ * Token pages lay out in two levels:
+ *  - sections (one titled card per kind of token, e.g. "Semantic" vs "Palette") flow in up to
+ *    `tokenColumns` columns, dropping to fewer rather than squeezing a section under its minimum;
+ *  - inside a section, `TokenGrid` tiles as many equal tiles per row as keep their minimum width.
+ */
+/** Narrowest a side-by-side token section may get before the page drops a column. */
+export const TOKEN_SECTION_MIN_WIDTH = 280;
+/** Gap between side-by-side sections and between tiles. */
+export const TOKEN_LAYOUT_GAP = 20;
+/** How many section columns fit in `available` px, at most `requested`, never below 1. */
+export function sectionColumns(available, requested) {
+    const fit = Math.floor((available + TOKEN_LAYOUT_GAP) / (TOKEN_SECTION_MIN_WIDTH + TOKEN_LAYOUT_GAP));
+    return Math.max(1, Math.min(requested, fit));
+}
+/** Equal tiles per row for a `TokenGrid`: as many as keep `minTileWidth` (capped by `maxColumns`),
+ *  sized so the row is filled exactly. */
+export function tileGeometry(available, minTileWidth, maxColumns = Infinity) {
+    const fit = Math.floor((available + TOKEN_LAYOUT_GAP) / (minTileWidth + TOKEN_LAYOUT_GAP));
+    const columns = Math.max(1, Math.min(maxColumns, fit));
+    const tileWidth = columns === 1 ? available : (available - TOKEN_LAYOUT_GAP * (columns - 1)) / columns;
+    return { columns, tileWidth };
+}

package/native/catalog/CatalogShell.tsx

@@ -136,6 +136,7 @@ export function CatalogShell<TId extends string>({
   updateEndpoint?: { baseUrl: string; secret: string };
 }) {
   const sectionsById = useMemo(() => new Map(sections.map((def) => [def.id, def])), [sections]);
+  const labels = useMemo(() => new Map(sections.filter((def) => def.title).map((def) => [def.id as string, def.title as string])), [sections]);
   const order = useMemo(() => orderedIds(groups, new Set(sectionsById.keys())), [groups, sectionsById]);
   const [active, setActive] = useState<ShellPageId<TId> | undefined>(() =>
     isWeb() ? resolveActiveFromHash(window.location.hash, order) : order[0],
@@ -215,7 +216,7 @@ export function CatalogShell<TId extends string>({
 
   return (
     <View style={styles.root}>
-      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} active={active} onPress={select} footer={footer} />
+      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} labels={labels} active={active} onPress={select} footer={footer} />
       <ScrollView ref={scrollRef} style={styles.main} contentContainerStyle={styles.mainContent}>
         {active === UPDATE_PAGE_ID ? (
           <UpdatePanel update={update ?? null} endpoint={updateEndpoint} appName={appName} headingRef={headingRef} />
@@ -233,6 +234,7 @@ export function CatalogShell<TId extends string>({
               previousId: neighbors(order, activeDef.id).previous,
               nextId: neighbors(order, activeDef.id).next,
               onNavigate: select,
+              labelOf: (id) => labels.get(id) ?? id,
             }}
             headingRef={headingRef}
             defaultPreviewWidths={defaultPreviewWidths}

package/native/catalog/CatalogSidebar.tsx

@@ -13,7 +13,7 @@ function webLinkProps(id: string, active: boolean) {
 
 /** One nav link. Hover via onHoverIn/onHoverOut (react-native-web fires them; native never does);
  *  keyboard focus draws the catalog focus ring because react-native-web removes the browser's. */
-function NavItem<TId extends string>({ id, active, onPress }: { id: TId; active: boolean; onPress: () => void }) {
+function NavItem<TId extends string>({ id, label, active, onPress }: { id: TId; label: string; active: boolean; onPress: () => void }) {
   const [hovered, setHovered] = useState(false);
   const [focused, setFocused] = useState(false);
   return (
@@ -38,7 +38,7 @@ function NavItem<TId extends string>({ id, active, onPress }: { id: TId; active:
         focused && styles.focusRing,
       ]}
     >
-      <Text style={[styles.label, active && styles.labelActive]}>{id}</Text>
+      <Text style={[styles.label, active && styles.labelActive]}>{label}</Text>
     </Pressable>
   );
 }
@@ -79,6 +79,7 @@ export function CatalogSidebar<TId extends string>({
   logoImageSource,
   caption,
   groups,
+  labels,
   active,
   onPress,
   footer,
@@ -91,6 +92,8 @@ export function CatalogSidebar<TId extends string>({
   logoImageSource?: ImageSourcePropType;
   caption: string;
   groups: NavGroup<TId>[];
+  /** Display titles by page id (`SectionDef.title`); pages without one show their id. */
+  labels?: ReadonlyMap<string, string>;
   active: string | undefined;
   onPress: (id: TId) => void;
   /** The quiet update-notice link below the nav list (design §5's footer line), or `undefined`
@@ -112,7 +115,7 @@ export function CatalogSidebar<TId extends string>({
   const [loadedAspect, setLoadedAspect] = useState<number | undefined>(undefined);
   const [logoFailed, setLogoFailed] = useState(false);
   const [nameWrapped, setNameWrapped] = useState(false);
-  const filtered = filterGroups(groups, query);
+  const filtered = filterGroups(groups, query, labels);
 
   const logoAspect = staticAspect ?? loadedAspect;
   const attemptingLogo = Boolean(logoImageSource) && !logoFailed;
@@ -191,7 +194,7 @@ export function CatalogSidebar<TId extends string>({
           <View key={group.label}>
             <Text style={styles.groupLabel}>{group.label}</Text>
             {group.ids.map((id) => (
-              <NavItem key={id} id={id} active={active === id} onPress={() => onPress(id)} />
+              <NavItem key={id} id={id} label={labels?.get(id) ?? id} active={active === id} onPress={() => onPress(id)} />
             ))}
           </View>
         ))}

package/native/catalog/ComparisonGrid.tsx

@@ -2,14 +2,26 @@ import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, axisItems, cellKey, gridWidthBounds, indexCells, validateComparison } from './comparison';
-import type { ComparisonDef, SpecimenSize } from './types';
+import { SpecimenSurface } from './SpecimenSurface';
+import type { ComparisonDef, SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
  * A grid of two props that combine freely, rendered as an accessible table inside one card.
  * Columns grow with the window up to 402px and never shrink below the specimen size's minimum;
- * a grid wider than its container scrolls horizontally inside the card, never the page.
+ * a grid wider than its container scrolls horizontally inside the card, never the page. `surface`
+ * is the page's `specimenSurface` behind each cell's example.
  */
-export function ComparisonGrid({ def, size, sectionId }: { def: ComparisonDef; size: SpecimenSize; sectionId: string }) {
+export function ComparisonGrid({
+  def,
+  size,
+  sectionId,
+  surface = 'neutral',
+}: {
+  def: ComparisonDef;
+  size: SpecimenSize;
+  sectionId: string;
+  surface?: SpecimenSurfaceKind;
+}) {
   if (__DEV__) {
     for (const issue of validateComparison({ ...def, size })) console.warn(`[Catalog] ${sectionId}: ${issue}`);
   }
@@ -53,7 +65,9 @@ export function ComparisonGrid({ def, size, sectionId }: { def: ComparisonDef; s
               return (
                 <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
                   {cell?.node !== undefined ? (
-                    <View style={cell.fill ? styles.fill : styles.center}>{cell.node}</View>
+                    <SpecimenSurface surface={surface} style={cell.fill && styles.fill}>
+                      {cell.node}
+                    </SpecimenSurface>
                   ) : (
                     <Text style={styles.unavailable}>
                       {cell?.unavailableReason ? `Not supported — ${cell.unavailableReason}` : 'Missing example'}
@@ -88,7 +102,6 @@ const styles = StyleSheet.create({
   headerCell: { backgroundColor: CATALOG_COLOR.surfaceMuted, justifyContent: 'center' },
   bodyRow: { minHeight: MATRIX_LAYOUT.rowMinHeight },
   specimenCell: { alignItems: 'center', justifyContent: 'center' },
-  center: { alignItems: 'center' },
   fill: { alignSelf: 'stretch' },
   headerText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
   rowHeaderText: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },