@krapwoo/ds-viewer 0.4.2 → 0.4.3

package/README.md

@@ -204,7 +204,58 @@ 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
+
+- **Two sidebar groups: `Tokens`, then `Components`** (`groupOrder: ['Tokens', 'Components']`).
+  Pages sort A–Z inside each group. Category groups ("Actions", "Status") make readers guess
+  where a component lives; search and A–Z already find it.
+- **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…) |
+
+- **`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.
 
 ## 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,6 +4,7 @@ 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 };
 }
@@ -35,6 +36,8 @@ function toSectionDef(page) {
         states: page.statesItems ? { itemsFill: page.statesItemsFill, 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,
     };
 }
@@ -64,6 +67,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

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;

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

@@ -213,6 +213,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.' }];

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/SectionBlock.tsx

@@ -5,6 +5,7 @@ import { ComparisonGrid } from './ComparisonGrid';
 import { ComparisonGroups } from './ComparisonGroups';
 import { ComparisonList } from './ComparisonList';
 import { ReferenceDetails } from './ReferenceDetails';
+import { TokenSections } from './TokenLayouts';
 import { choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
 import type { PreviewWidths, SectionDef } from './types';
 
@@ -45,23 +46,27 @@ export interface SectionPager<TId extends string> {
   previousId: TId | null;
   nextId: TId | null;
   onNavigate: (id: TId) => void;
+  /** Display title for a page id, for the buttons' accessible names. */
+  labelOf?: (id: TId) => string;
 }
 
 function PagerButton<TId extends string>({
   direction,
   targetId,
   onNavigate,
+  labelOf,
 }: {
   direction: 'previous' | 'next';
   targetId: TId | null;
   onNavigate: (id: TId) => void;
+  labelOf?: (id: TId) => string;
 }) {
   const [hovered, setHovered] = useState(false);
   const [focused, setFocused] = useState(false);
   const disabled = targetId == null;
   const label = disabled
     ? direction === 'previous' ? 'No previous page' : 'No next page'
-    : `${direction === 'previous' ? 'Previous' : 'Next'}: ${targetId}`;
+    : `${direction === 'previous' ? 'Previous' : 'Next'}: ${labelOf ? labelOf(targetId) : targetId}`;
   return (
     <Pressable
       onPress={() => {
@@ -127,6 +132,8 @@ function BlockContent<TId extends string>({ block, def }: { block: PresentationB
       return <ComparisonList items={block.items} size={block.size} label={`${def.id}: ${block.title}`} />;
     case 'preview':
       return def.render ? <Preview render={def.render} widths={block.widths} /> : null;
+    case 'tokenSections':
+      return <TokenSections sections={block.sections} columns={block.columns} />;
     default:
       return (
         <View style={styles.previewCard}>
@@ -191,11 +198,11 @@ function Blocks<TId extends string>({ blocks, def }: { blocks: PresentationBlock
     <View onLayout={onContainerLayout} style={[styles.blocks, side && styles.blocksSide]}>
       {blocks.map((block, i) => (
         <View
-          key={block.title}
+          key={block.title || block.kind}
           onLayout={onBlockLayout(i)}
           style={side ? (i === 0 ? { width: blockWidth(block, available), flexShrink: 0 } : styles.blockFill) : undefined}
         >
-          <Text style={styles.blockLabel}>{block.title}</Text>
+          {block.title ? <Text style={styles.blockLabel}>{block.title}</Text> : null}
           <BlockContent block={block} def={def} />
         </View>
       ))}
@@ -247,14 +254,19 @@ export function SectionBlock<TId extends string>({
         <View style={styles.titleText}>
           {/* The focus target is the heading itself, so assistive tech announces its role and level. */}
           <View ref={headingRef} tabIndex={-1} role="heading" {...headingLevelProps} style={styles.headingTarget}>
-            <Text style={styles.title}>{def.id}</Text>
+            <Text style={styles.title}>{def.title ?? def.id}</Text>
           </View>
+          {def.osComponent && (
+            <View style={styles.osBadge}>
+              <Text style={styles.osBadgeText}>{def.osComponent === 'full' ? 'OS component' : 'Partly OS component'}</Text>
+            </View>
+          )}
           <Text style={styles.desc}>{def.description}</Text>
         </View>
         {pager && (
           <View style={styles.pager}>
-            <PagerButton direction="previous" targetId={pager.previousId} onNavigate={pager.onNavigate} />
-            <PagerButton direction="next" targetId={pager.nextId} onNavigate={pager.onNavigate} />
+            <PagerButton direction="previous" targetId={pager.previousId} onNavigate={pager.onNavigate} labelOf={pager.labelOf} />
+            <PagerButton direction="next" targetId={pager.nextId} onNavigate={pager.onNavigate} labelOf={pager.labelOf} />
           </View>
         )}
       </View>
@@ -278,6 +290,17 @@ const styles = StyleSheet.create({
   },
   titleText: { flex: 1 },
   headingTarget: { alignSelf: 'flex-start' },
+  osBadge: {
+    alignSelf: 'flex-start',
+    marginBottom: CATALOG_SPACE.sm,
+    paddingHorizontal: CATALOG_SPACE.sm,
+    paddingVertical: 3,
+    borderRadius: CATALOG_RADIUS.control,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.borderStrong,
+    backgroundColor: CATALOG_COLOR.surface,
+  },
+  osBadgeText: { fontSize: CATALOG_TYPE.xs, fontWeight: '700', letterSpacing: 0.4, color: CATALOG_COLOR.text },
   title: { fontSize: CATALOG_TYPE.pageTitle, fontWeight: '700', color: CATALOG_COLOR.text, marginBottom: 5 },
   desc: { fontSize: CATALOG_TYPE.md, lineHeight: 20, color: CATALOG_COLOR.textMuted, maxWidth: 700 },
   pager: { flexDirection: 'row', gap: 6, flexShrink: 0 },

package/native/catalog/TokenLayouts.tsx

@@ -0,0 +1,92 @@
+import React, { useState } from 'react';
+import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { sectionColumns, tileGeometry, TOKEN_LAYOUT_GAP } from './tokenLayout';
+import type { TokenSection } from './types';
+
+/** Measures its own width; renders nothing inside until the width is known. */
+function useWidth(): [number, (event: LayoutChangeEvent) => void] {
+  const [width, setWidth] = useState(0);
+  return [width, (event) => {
+    const next = Math.round(event.nativeEvent.layout.width);
+    if (next > 0 && next !== width) setWidth(next);
+  }];
+}
+
+/**
+ * A token page's sections (`SectionDef.tokenSections`): one titled card per kind of token, flowing
+ * in up to `columns` columns. A `wide` section takes a full row; the page drops to fewer columns
+ * rather than squeeze a section under its minimum width.
+ */
+export function TokenSections({ sections, columns }: { sections: TokenSection[]; columns: 1 | 2 | 3 }) {
+  const [width, onLayout] = useWidth();
+  const perRow = sectionColumns(width, columns);
+  const columnWidth = perRow === 1 ? width : (width - TOKEN_LAYOUT_GAP * (perRow - 1)) / perRow;
+  return (
+    <View onLayout={onLayout} style={styles.sections}>
+      {width > 0 && sections.map((section) => (
+        <View key={section.title} style={{ width: section.wide || perRow === 1 ? width : columnWidth }}>
+          <Text style={styles.sectionLabel}>{section.title}</Text>
+          {section.desc ? <Text style={styles.sectionDesc}>{section.desc}</Text> : null}
+          <View style={styles.card}>{section.render()}</View>
+        </View>
+      ))}
+    </View>
+  );
+}
+
+/**
+ * Tokens as tiles in columns — for tokens whose preview is small and self-contained (radius,
+ * shadow, colour, control height). As many equal tiles per row as keep `minTileWidth`.
+ */
+export function TokenGrid({ children, minTileWidth = 140, maxColumns }: { children: React.ReactNode; minTileWidth?: number; maxColumns?: number }) {
+  const [width, onLayout] = useWidth();
+  const { tileWidth } = tileGeometry(width, minTileWidth, maxColumns);
+  return (
+    <View onLayout={onLayout} style={styles.grid}>
+      {width > 0 && React.Children.map(children, (child) => (child ? <View style={{ width: tileWidth }}>{child}</View> : null))}
+    </View>
+  );
+}
+
+/**
+ * One token in a `TokenGrid`: its preview, then its name and value, then its role. `note` says
+ * where or why the token is used (from its comments or real usages) — omit it when there is none.
+ */
+export function TokenTile({ name, value, note, children }: { name: string; value?: string; note?: string; children: React.ReactNode }) {
+  return (
+    <View style={styles.tile}>
+      <View style={styles.tilePreview}>{children}</View>
+      <Text style={styles.tileName}>{name}</Text>
+      {value ? <Text style={styles.tileValue}>{value}</Text> : null}
+      {note ? <Text style={styles.tileNote}>{note}</Text> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  sections: { flexDirection: 'row', flexWrap: 'wrap', gap: TOKEN_LAYOUT_GAP, rowGap: CATALOG_LAYOUT.blockGap, alignItems: 'flex-start' },
+  sectionLabel: {
+    fontSize: CATALOG_TYPE.sm,
+    fontWeight: '700',
+    letterSpacing: 0.72,
+    textTransform: 'uppercase',
+    color: CATALOG_COLOR.text,
+  },
+  sectionDesc: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: CATALOG_SPACE.xs },
+  card: {
+    marginTop: CATALOG_LAYOUT.blockLabelGap,
+    backgroundColor: CATALOG_COLOR.surface,
+    borderWidth: 1,
+    borderColor: CATALOG_COLOR.borderStrong,
+    borderRadius: CATALOG_RADIUS.card,
+    padding: CATALOG_SPACE.xl,
+    gap: CATALOG_SPACE.md,
+  },
+  grid: { flexDirection: 'row', flexWrap: 'wrap', gap: TOKEN_LAYOUT_GAP },
+  tile: { gap: CATALOG_SPACE.xs },
+  tilePreview: { minHeight: 56, justifyContent: 'center', marginBottom: CATALOG_SPACE.xs },
+  tileName: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.text },
+  tileValue: { fontSize: CATALOG_TYPE.xs, color: CATALOG_COLOR.textMuted },
+  tileNote: { fontSize: CATALOG_TYPE.xs, color: CATALOG_COLOR.textMuted, lineHeight: 16 },
+});

package/native/catalog/TokenRow.tsx

@@ -13,17 +13,41 @@ import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
  * 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.
  */
-export function TokenRow({ children, use, last = false }: { children: React.ReactNode; use: string; last?: boolean }) {
+export function TokenRow({
+  children,
+  use,
+  last = false,
+  notePlacement = 'below',
+  sampleWidth = 280,
+}: {
+  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. */
+  notePlacement?: 'below' | 'right';
+  sampleWidth?: number;
+}) {
+  if (notePlacement === 'right') {
+    return (
+      <View style={[styles.itemRight, !last && styles.itemDivider]}>
+        <View style={{ width: sampleWidth, flexShrink: 0 }}>{children}</View>
+        {use ? <Text style={[styles.use, styles.useRight]}>{use}</Text> : null}
+      </View>
+    );
+  }
   return (
     <View style={[styles.item, !last && styles.itemDivider]}>
       {children}
-      <Text style={styles.use}>{use}</Text>
+      {use ? <Text style={styles.use}>{use}</Text> : null}
     </View>
   );
 }
 
 const styles = StyleSheet.create({
   item: { gap: CATALOG_SPACE.xs },
+  itemRight: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.xl },
+  useRight: { flex: 1 },
   itemDivider: {
     paddingBottom: CATALOG_SPACE.md,
     borderBottomWidth: 1,

package/native/catalog/catalogNavigation.ts

@@ -48,12 +48,17 @@ export function neighbors<TId extends string>(
 }
 
 /** Sidebar filter: case-insensitive substring match, sorted ids, empty groups removed. */
-export function filterGroups<TId extends string>(groups: readonly NavGroup<TId>[], query: string): NavGroup<TId>[] {
+export function filterGroups<TId extends string>(
+  groups: readonly NavGroup<TId>[],
+  query: string,
+  /** Display titles by id; a page matches on its id or its title. */
+  labels?: ReadonlyMap<string, string>,
+): NavGroup<TId>[] {
   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/native/catalog/comparison.ts

@@ -8,7 +8,7 @@
  * It also decides whether two blocks sit side by side (choosePlacement) and how many columns the
  * Props box uses (propsColumns). ComparisonGrid, ComparisonGroups, and ComparisonList render it.
  */
-import type { ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenSize, VariantSlot } from './types.ts';
+import type { ComparisonAxisItem, ComparisonDef, GridAxis, PreviewWidths, SectionDef, SpecimenSize, TokenSection, VariantSlot } from './types.ts';
 import type React from 'react';
 
 /** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
@@ -230,6 +230,7 @@ export type PresentationBlock =
   | { kind: 'grouped'; title: string; size: SpecimenSize; groups: ListGroup[] }
   | { kind: 'list'; title: string; size: SpecimenSize; items: ListItem[] }
   | { kind: 'preview'; title: string; widths: PreviewWidths }
+  | { kind: 'tokenSections'; title: string; sections: TokenSection[]; columns: 1 | 2 | 3 }
   | { kind: 'empty'; title: string; message: string };
 
 export interface PresentationOptions {
@@ -280,6 +281,10 @@ function groupStates(variants: VariantSlot, states: VariantSlot): { groups: List
  *  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<TId extends string>(def: SectionDef<TId>, options: PresentationOptions = {}): PresentationBlock[] {
+  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.' }];

package/native/catalog/index.ts

@@ -24,6 +24,7 @@ export { ReferenceDetails } from './ReferenceDetails';
 export { PropsTable } from './PropsTable';
 export { VariantGroup } from './VariantGroup';
 export { TokenRow } from './TokenRow';
+export { TokenSections, TokenGrid, TokenTile } from './TokenLayouts';
 export { DividedStack } from './DividedStack';
 export { Swatch } from './Swatch';
 export { PhoneFrame } from './PhoneFrame';
@@ -33,7 +34,7 @@ export { buildComponentManifest } from './manifest';
 export type { ComponentManifestEntry, ManifestExample } from './manifest';
 export { defineCatalogPage, buildCatalogSections } from './pageApi';
 export type { CatalogPage, CatalogPageInput, GeneratedComponent, GeneratedPropRecord } from './pageApi';
-export type { PropDef, SectionDef, NavGroup, SpecimenSize, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis, PreviewWidths } from './types';
+export type { PropDef, SectionDef, NavGroup, SpecimenSize, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis, PreviewWidths, TokenSection } from './types';
 export { UpdatePanel } from './UpdatePanel';
 export { UPDATE_PAGE_ID } from './catalogNavigation';
 export type { UpdateNotice } from './types';

package/native/catalog/pageApi.ts

@@ -1,5 +1,5 @@
 import type React from 'react';
-import type { ComparisonDef, NavGroup, PreviewWidths, PropDef, SectionDef, SpecimenSize, VariantSlot } from './types';
+import type { ComparisonDef, NavGroup, PreviewWidths, PropDef, SectionDef, SpecimenSize, TokenSection, VariantSlot } from './types';
 
 /** `SectionDef` without the derived fields (`id`/`path`/`props` come from detection and
  *  generated props), plus the three fields design §1 "Page shape" adds. */
@@ -9,6 +9,14 @@ export interface CatalogPageInput<TId extends string = string> {
    *  default when writing the generated page index, so an authored page never has to repeat a name
    *  already implied by its file. */
   id?: TId;
+  /** Display name; see `SectionDef.title`. */
+  title?: string;
+  /** Project-relative file shown as the page's Source when the page documents something other
+   *  than a component, e.g. a token page pointing at `src/design-system/tokens.ts`. A component's
+   *  own file always wins. */
+  source?: string;
+  /** See `SectionDef.osComponent`. */
+  osComponent?: 'full' | 'partial';
   description: string;
   whenToUse?: string;
   a11y?: string;
@@ -16,6 +24,8 @@ export interface CatalogPageInput<TId extends string = string> {
   states?: VariantSlot;
   render?: () => React.ReactNode;
   tokenGallery?: boolean;
+  tokenSections?: TokenSection[];
+  tokenColumns?: 1 | 2 | 3;
   fullWidthLabel?: string;
   comparison?: ComparisonDef;
   specimenSize?: SpecimenSize;
@@ -121,15 +131,20 @@ export function buildCatalogSections<TId extends string>(
     // to the page's own file as its Source instead of an empty path.
     return {
       id: page.id,
+      title: page.title,
+      osComponent: page.osComponent,
       description: page.description,
-      path: component?.file ?? page.file,
+      path: component?.file ?? page.source ?? page.file,
       whenToUse: page.whenToUse,
       props: component ? mergePropNotes(component, page.propNotes) : undefined,
       a11y: page.a11y,
       variants: page.variants,
       states: page.states,
       render: page.render,
-      tokenGallery: page.tokenGallery,
+      // `tokenSections` makes a page a token gallery by itself.
+      tokenGallery: page.tokenGallery || (page.tokenSections !== undefined && page.tokenSections.length > 0) || undefined,
+      tokenSections: page.tokenSections,
+      tokenColumns: page.tokenColumns,
       fullWidthLabel: page.fullWidthLabel,
       comparison: page.comparison,
       specimenSize: page.specimenSize,

package/native/catalog/tokenLayout.ts

@@ -0,0 +1,29 @@
+/**
+ * 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: number, requested: number): number {
+  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: number, minTileWidth: number, maxColumns = Infinity): { columns: number; tileWidth: number } {
+  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/types.ts

@@ -102,6 +102,13 @@ export interface ComparisonDef {
  *  typed to the app's real section list without this file needing to know what they are. */
 export interface SectionDef<TId extends string = string> {
   id: TId;
+  /** Display name for the heading, sidebar and search (e.g. "Control heights"). Defaults to `id`,
+   *  which stays the page's address (`#ControlHeights`) and its name in `explain`. */
+  title?: string;
+  /** Marks a component that is, or contains, a native platform control rather than a custom one:
+   *  `'full'` shows an "OS component" badge under the title, `'partial'` "Partly OS component".
+   *  Say in `description` which part is native and how it differs on web. */
+  osComponent?: 'full' | 'partial';
   description: string;
   path: string;
   /** One sentence disambiguating this component from its closest look-alike(s) — the deciding
@@ -163,6 +170,14 @@ export interface SectionDef<TId extends string = string> {
    *  configurations list, and shows only a Quick reference card with the source path (there's no
    *  component behavior to document). */
   tokenGallery?: boolean;
+  /** Token pages with more than one kind of token: one titled card per section (e.g. "Semantic"
+   *  and "Palette", or "Body" and "Title"), instead of a single "Tokens" card. When set, `render`
+   *  is not used and the page counts as a token gallery. See `TokenSection`. */
+  tokenSections?: TokenSection[];
+  /** How many sections sit side by side (1–3, default 1). Narrow sections such as type families
+   *  use 2–3; the page drops columns rather than squeeze a section under 280px. A section with
+   *  `wide: true` always takes a full row. */
+  tokenColumns?: 1 | 2 | 3;
   /** Overrides the `tokenGallery` block's label (default `'Tokens'`) — e.g. `'Preview'` for a page
    *  that's a composed, realistic usage example rather than a list of raw token values. Ignored
    *  unless `tokenGallery` is also set. */
@@ -206,3 +221,14 @@ export interface UpdateNotice {
   summary: string[];
   releasedAt?: string;
 }
+
+/** One titled card on a token page (`SectionDef.tokenSections`). */
+export interface TokenSection {
+  /** The kind of token this card holds, e.g. "Semantic colours", "Palette", "Body". */
+  title: string;
+  /** One line under the title: what this kind of token is for. */
+  desc?: string;
+  /** Take a full row even when the page sets `tokenColumns` (e.g. palette ramps). */
+  wide?: boolean;
+  render: () => React.ReactNode;
+}

package/package.json

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