@krapwoo/ds-viewer 0.1.1 → 0.3.0

package/dist/cli/workspace.js

@@ -1,6 +1,8 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-const METRO_CONFIG = `const path = require('path');
+import { globBaseFolder } from "./glob.js";
+function metroConfigJs(extraWatchFolders) {
+    return `const path = require('path');
 const fs = require('fs');
 const workspace = __dirname;
 const projectRoot = path.resolve(workspace, '..');
@@ -16,7 +18,18 @@ if (typeof config !== 'object') {
 config.projectRoot = workspace;
 // Expo sets the server root to the folder the config was built for; bundle URLs must resolve from the workspace.
 config.server = { ...(config.server || {}), unstable_serverRoot: workspace };
-config.watchFolders = Array.from(new Set([...(config.watchFolders || []), projectRoot]));
+// Every configured components/tokens/pages glob's base folder — not just projectRoot itself — so a
+// host whose kit lives in a sibling folder (e.g. kit-host/ds-viewer.config.ts reaching
+// ../starter-kit/components) still gets its files watched and bundled. Resolved from projectRoot at
+// runtime, not baked in as an absolute path, so the generated file stays portable across machines.
+const EXTRA_WATCH_FOLDERS = ${JSON.stringify(extraWatchFolders)};
+const extraWatchFolders = EXTRA_WATCH_FOLDERS;
+// A configured components/tokens/pages glob can point at a folder that doesn't exist yet (e.g. a
+// standalone-pages folder before its first file is added) — Metro refuses to watch a nonexistent
+// folder, which otherwise makes every single bundle request fail with HTTP 500. Filtered here, at
+// workspace-generation time, not above at config-resolution time, because a folder created after
+// \`dev\` starts should start being watched on its own next run, same as every other glob folder.
+config.watchFolders = Array.from(new Set([...(config.watchFolders || []), projectRoot, ...extraWatchFolders.map((f) => path.resolve(projectRoot, f)).filter((f) => fs.existsSync(f))]));
 config.resolver.nodeModulesPaths = [path.join(projectRoot, 'node_modules')];
 // A standalone page can read generated data with \`import { components, tokens } from '@krapwoo/ds-viewer/generated'\`
 // (design §3) — redirect that one specifier to this workspace's own generated/index.ts.
@@ -31,17 +44,28 @@ config.resolver.resolveRequest = (context, moduleName, platform) => {
 };
 module.exports = config;
 `;
+}
 /** Decided here, not inside the viewer: Metro resolves `react-native-safe-area-context` statically
  *  at bundle time, so a runtime try/catch `require` cannot skip it when the optional peer is
  *  missing. Importing and wrapping must instead be baked into the generated entry (design §1
  *  "Three parts", Viewer row). */
-function entryTsx(name, hasSafeArea, groupOrder) {
+function entryTsx(name, hasSafeArea, groupOrder, logoRequirePath) {
     const safeAreaImport = hasSafeArea ? "import { SafeAreaProvider } from 'react-native-safe-area-context';\n" : '';
-    const viewer = `<CatalogShell appName={${JSON.stringify(name)}} title="Component Catalog" groups={groups} sections={sections} />`;
+    // A literal `require(...)` with a path computed at generation time: Metro resolves every import
+    // statically, so the logo's actual (arbitrary, user-configured) location must already be baked
+    // into this generated file, the same reasoning `hasSafeArea` above already follows for the
+    // optional SafeAreaProvider import.
+    // `JSON.stringify`, not a plain single-quoted template literal: `logoRequirePath` carries the
+    // user's own logo file name, which may contain a `'` (e.g. `assets/it's.png`) — a bare
+    // `'${logoRequirePath}'` breaks the generated file's syntax the moment it does (Minor finding,
+    // Fable's implementation review, cli/workspace.ts:65).
+    const logoImport = logoRequirePath ? `const logoSource = require(${JSON.stringify(logoRequirePath)});\n` : '';
+    const logoProp = logoRequirePath ? ' logoImageSource={logoSource}' : '';
+    const viewer = `<CatalogShell appName={${JSON.stringify(name)}} title="Component Catalog" groups={groups} sections={sections}${logoProp} />`;
     const root = hasSafeArea ? `<SafeAreaProvider>${viewer}</SafeAreaProvider>` : viewer;
     return `import { registerRootComponent } from 'expo';
 import { CatalogShell, buildCatalogSections } from '@krapwoo/ds-viewer';
-${safeAreaImport}import pages from './generated/pages';
+${safeAreaImport}${logoImport}import pages from './generated/pages';
 import components from './generated/components.json';
 
 function App() {
@@ -52,25 +76,22 @@ function App() {
 registerRootComponent(App);
 `;
 }
-/** The folder a glob pattern varies under — the part of the pattern before its first wildcard
- *  segment (or, for a pattern with no wildcard, its own containing folder). Same logic as
- *  `cli/sync.ts`'s `globBaseFolder` (Task 10), kept local here since it's one line and this module
- *  has no other reason to depend on `sync.ts`. */
-function globBaseFolder(pattern) {
-    const segments = pattern.split('/');
-    const wildcardIndex = segments.findIndex((segment) => segment.includes('*'));
-    const baseSegments = wildcardIndex === -1 ? segments.slice(0, -1) : segments.slice(0, wildcardIndex);
-    return baseSegments.join('/') || '.';
+/** Every configured components/tokens/pages glob's base folder, deduplicated and sorted — shared by
+ *  `projectIncludeGlobs` (tsconfig `include`, below) and `metroConfigJs`'s extra watch folders
+ *  (above). Kept as the raw relative folder (e.g. `"../starter-kit/components"`), not yet turned
+ *  into either a tsconfig glob or an absolute path — each caller does that its own way. */
+function configGlobFolders(config) {
+    const folders = new Set();
+    for (const pattern of [...config.components, ...(config.tokens ?? []), ...(config.pages ?? [])]) {
+        folders.add(globBaseFolder(pattern));
+    }
+    return [...folders].sort();
 }
 /** Folders the workspace's own `tsconfig.json` needs to type-check — derived from the config's own
  *  globs (the spike used `../src/**\/*`), instead of `../**\/*`, which would pull in the whole
  *  project, including `node_modules`. */
 function projectIncludeGlobs(config) {
-    const folders = new Set();
-    for (const pattern of [...config.components, ...(config.tokens ?? []), ...(config.pages ?? [])]) {
-        folders.add(globBaseFolder(pattern));
-    }
-    return [...folders].sort().map((folder) => `../${folder}/**/*`);
+    return configGlobFolders(config).map((folder) => `../${folder}/**/*`);
 }
 /** 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
@@ -88,12 +109,19 @@ export function writeWorkspace(config) {
     if (existsSync(projectTsconfig))
         workspaceTsconfig.extends = '../tsconfig.json';
     writeFileSync(path.join(workspace, 'tsconfig.json'), `${JSON.stringify(workspaceTsconfig, null, 2)}\n`);
-    writeFileSync(path.join(workspace, 'metro.config.js'), METRO_CONFIG);
+    writeFileSync(path.join(workspace, 'metro.config.js'), metroConfigJs(configGlobFolders(config)));
     const projectBabelConfig = path.join(config.projectRoot, 'babel.config.js');
     if (existsSync(projectBabelConfig)) {
         writeFileSync(path.join(workspace, 'babel.config.js'), "module.exports = require('../babel.config.js');\n");
     }
     const hasSafeArea = existsSync(path.join(config.projectRoot, 'node_modules', 'react-native-safe-area-context', 'package.json'));
-    writeFileSync(path.join(workspace, 'entry.tsx'), entryTsx(config.name, hasSafeArea, config.groupOrder ?? []));
+    // `config.logo` is already validated by `cli/config.ts`'s `resolveConfig` (Step 3 above) — by the
+    // time `writeWorkspace` sees it, it's either a real, existing file or undefined. Computed relative
+    // to `workspace` (one level deeper than `projectRoot`), with forward slashes so the generated
+    // `require()` string is portable across machines.
+    const logoRequirePath = config.logo
+        ? path.relative(workspace, path.resolve(config.projectRoot, config.logo)).split(path.sep).join('/')
+        : undefined;
+    writeFileSync(path.join(workspace, 'entry.tsx'), entryTsx(config.name, hasSafeArea, config.groupOrder ?? [], logoRequirePath));
     return workspace;
 }

package/dist/native/catalog/comparison.js

@@ -0,0 +1,283 @@
+/** Approved geometry. `cellPadding` equals CATALOG_SPACE.lg (asserted in tests). The laptop
+ *  content width is a 1280px viewport minus the 264px sidebar and 32px side padding. */
+export const MATRIX_LAYOUT = {
+    rowHeaderWidth: 120,
+    columnMaxWidth: 402,
+    cellPadding: 16,
+    rowMinHeight: 150,
+    laptopContentWidth: 952,
+};
+/** Component previews never render wider than a phone. */
+export const PREVIEW_MAX_WIDTH = 402;
+/** Two blocks share a row only when that saves at least this much page height. */
+export const PLACEMENT_MIN_SAVING = 120;
+/** A Props column is never narrower than this; below it the Props box uses one column. */
+export const PROPS_MIN_COLUMN_WIDTH = 360;
+/** Gap between the two Props columns (CATALOG_SPACE['2xl']). */
+export const PROPS_COLUMN_GAP = 32;
+/** Smallest column or cell width per specimen size. Wide specimens are fixed at phone width. */
+export const COLUMN_MIN_WIDTH = { compact: 160, regular: 240, wide: 402 };
+/** `Array.isArray`'s built-in type guard narrows to a mutable `any[]`, which a `readonly T[]`
+ *  union member is never assignable to — so the `else` branch of `Array.isArray(axis) ? ... :
+ *  ...` keeps `axis`'s full union type instead of narrowing away the array member. This explicit
+ *  predicate sidesteps that (never caught before Task 4: this file had never been typechecked by
+ *  `tsc` until `cli/doctor.ts`'s import pulled it into the root `tsconfig.json`'s program). */
+function isBoundAxis(axis) {
+    return !Array.isArray(axis);
+}
+/** A `GridAxis`'s own items, whether it's a plain array or bound to a prop — every reader of
+ *  `ComparisonDef.rows`/`columns` goes through this (never `Array.isArray` directly), so a future
+ *  third axis shape only needs to change this one function. */
+export function axisItems(axis) {
+    return isBoundAxis(axis) ? [...axis.items] : [...axis];
+}
+/** The prop name a `GridAxis` is bound to, or undefined for a plain, unbound axis. */
+export function axisProp(axis) {
+    return isBoundAxis(axis) ? axis.prop : undefined;
+}
+/**
+ * Shared page-authoring helper (design §1 "Page shape", §4 "Binding examples to props"). Every
+ * grid comparison in the starter kit builds its `ComparisonDef` with this instead of its own local
+ * copy, so `cli/staticPage.ts`'s static reader has exactly one call shape to recognize anywhere a
+ * page's `comparison` field is produced by a function call rather than written as a plain object
+ * literal. `rows`/`columns` accept either a plain item array (unbound) or `{ prop, items }` (bound)
+ * — the cell grid itself is unaffected either way, since cells are always keyed by each axis's own
+ * items regardless of whether that axis names a prop. Lives here, beside `axisItems`/`axisProp`,
+ * rather than in its own `grid.ts` — every other file in this module has only *type-only* relative
+ * imports; a bare, no-extension value import would be the first of its kind in `native/catalog`.
+ *
+ * Each cell is a real instance with exactly the props its row and column name. Never build these by
+ * multiplying `variants` with `states` — those are pre-rendered nodes and cannot be combined.
+ */
+export function grid(rowLabel, columnLabel, rows, columns, cell, size) {
+    const rowItems = axisItems(rows);
+    const columnItems = axisItems(columns);
+    return {
+        rowLabel,
+        columnLabel,
+        rows,
+        columns,
+        cells: rowItems.flatMap((row) => columnItems.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
+        size,
+    };
+}
+/** How many grid columns fit beside the row header on a 1280px laptop without scrolling. */
+export function gridColumnLimit(size) {
+    return Math.floor((MATRIX_LAYOUT.laptopContentWidth - MATRIX_LAYOUT.rowHeaderWidth) / COLUMN_MIN_WIDTH[size]);
+}
+export function gridWidthBounds(columnCount, size) {
+    const n = Math.max(0, columnCount);
+    return {
+        minWidth: MATRIX_LAYOUT.rowHeaderWidth + n * COLUMN_MIN_WIDTH[size],
+        maxWidth: MATRIX_LAYOUT.rowHeaderWidth + n * MATRIX_LAYOUT.columnMaxWidth,
+    };
+}
+/** 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) {
+    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 rows = Math.ceil(itemCount / maxColumns);
+    const columns = Math.ceil(itemCount / rows);
+    const fitted = Math.floor(inner / columns);
+    const cellWidth = size === 'wide' ? MATRIX_LAYOUT.columnMaxWidth : Math.max(min, Math.min(MATRIX_LAYOUT.columnMaxWidth, fitted));
+    return {
+        columns,
+        rows,
+        fillers: rows * columns - itemCount,
+        cellWidth,
+        containerWidth: columns * cellWidth + 2,
+    };
+}
+export function cellKey(rowKey, columnKey) {
+    return `${rowKey}\u0000${columnKey}`;
+}
+export function indexCells(def) {
+    const index = new Map();
+    for (const cell of def.cells) {
+        const key = cellKey(cell.rowKey, cell.columnKey);
+        if (!index.has(key))
+            index.set(key, cell);
+    }
+    return index;
+}
+/** Human-readable problems in a stable order: axis duplicates, column fit, each cell in
+ *  declaration order, then missing coordinates in row-major order. Empty when valid. */
+export function validateComparison(def) {
+    const rowItems = axisItems(def.rows);
+    const columnItems = axisItems(def.columns);
+    if (rowItems.length === 0 || columnItems.length === 0) {
+        return ['Comparison needs at least one row and one column.'];
+    }
+    const issues = [];
+    const rowKeys = new Set();
+    for (const row of rowItems) {
+        if (rowKeys.has(row.key))
+            issues.push(`Duplicate row key "${row.key}".`);
+        rowKeys.add(row.key);
+    }
+    const columnKeys = new Set();
+    for (const column of columnItems) {
+        if (columnKeys.has(column.key))
+            issues.push(`Duplicate column key "${column.key}".`);
+        columnKeys.add(column.key);
+    }
+    const size = def.size ?? 'regular';
+    const limit = gridColumnLimit(size);
+    if (columnKeys.size > limit) {
+        issues.push(`Grid has ${columnKeys.size} columns; at most ${limit} ${size} columns fit a 1280px laptop. Swap the axes or use two lists.`);
+    }
+    const seen = new Set();
+    for (const cell of def.cells) {
+        const key = cellKey(cell.rowKey, cell.columnKey);
+        if (seen.has(key)) {
+            issues.push(`Duplicate cell for row "${cell.rowKey}" and column "${cell.columnKey}".`);
+            continue;
+        }
+        seen.add(key);
+        if (!rowKeys.has(cell.rowKey)) {
+            issues.push(`Cell references undeclared row "${cell.rowKey}".`);
+            continue;
+        }
+        if (!columnKeys.has(cell.columnKey)) {
+            issues.push(`Cell references undeclared column "${cell.columnKey}".`);
+            continue;
+        }
+        const hasNode = cell.node !== undefined;
+        const hasReason = typeof cell.unavailableReason === 'string' && cell.unavailableReason.length > 0;
+        if (hasNode === hasReason) {
+            issues.push(`Cell for row "${cell.rowKey}" and column "${cell.columnKey}" must provide exactly one of node or unavailableReason.`);
+        }
+    }
+    for (const rowKey of rowKeys) {
+        for (const columnKey of columnKeys) {
+            if (!seen.has(cellKey(rowKey, columnKey))) {
+                issues.push(`Missing cell for row "${rowKey}" and column "${columnKey}".`);
+            }
+        }
+    }
+    return issues;
+}
+/** `states` minus items whose key is already a grid row or column. */
+export function remainingStates(states, comparison) {
+    if (!states)
+        return undefined;
+    if (!comparison)
+        return states;
+    const covered = new Set([...axisItems(comparison.rows).map((row) => row.key), ...axisItems(comparison.columns).map((column) => column.key)]);
+    const items = states.items.filter((item) => !covered.has(item.key));
+    return items.length > 0 ? { ...states, items } : undefined;
+}
+/** Specimen size for a one-axis slot: the section's explicit size, else wide for full-width
+ *  (itemsFill) slots, else regular. */
+export function slotSize(def, slot) {
+    return def.specimenSize ?? (slot.itemsFill ? 'wide' : 'regular');
+}
+function slotItems(slot) {
+    return slot.items.map((item) => ({ key: item.key, label: item.name, node: item.node, fill: item.fill || slot.itemsFill }));
+}
+/** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
+function previewWidths(requested, fallback) {
+    const widths = requested ?? fallback ?? [PREVIEW_MAX_WIDTH];
+    return widths === 'full' ? 'full' : widths.map((w) => Math.min(w, PREVIEW_MAX_WIDTH));
+}
+/** Grouped rows when at least one state names a variant through `group`. Every variant gets a row:
+ *  its grouped states, or the variant's own example when it has none. States without a matching
+ *  group are returned as leftovers for "Other configurations". */
+function groupStates(variants, states) {
+    const variantKeys = new Set(variants.items.map((v) => v.key));
+    if (!states.items.some((s) => s.group !== undefined && variantKeys.has(s.group)))
+        return undefined;
+    const fill = (item, slot) => item.fill || slot.itemsFill;
+    const groups = variants.items.map((variant) => {
+        const own = states.items.filter((s) => s.group === variant.key);
+        const items = own.length > 0
+            ? own.map((s) => ({ key: s.key, label: s.name, node: s.node, fill: fill(s, states) }))
+            : [{ key: variant.key, label: variant.name, node: variant.node, fill: fill(variant, variants) }];
+        return { key: variant.key, label: variant.name, items };
+    });
+    const rest = states.items.filter((s) => s.group === undefined || !variantKeys.has(s.group));
+    for (const s of rest) {
+        if (s.group !== undefined && globalThis.__DEV__) {
+            console.warn(`[Catalog] state "${s.key}" names group "${s.group}", which matches no variant key; it is shown under "Other configurations".`);
+        }
+    }
+    return { groups, leftovers: rest.length > 0 ? { ...states, items: rest } : undefined };
+}
+/** The visual blocks of one page, in reading order. Reference details are not included. A page
+ *  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.tokenGallery) {
+        const title = def.fullWidthLabel ?? 'Tokens';
+        return [def.render ? { kind: 'preview', title, widths: 'full' } : { kind: 'empty', title, message: 'Nothing to preview.' }];
+    }
+    const hide = def.hide ?? {};
+    const blocks = [];
+    let states = hide.states ? undefined : remainingStates(def.states, def.comparison);
+    if (!hide.variants) {
+        const grouped = !def.comparison && def.variants && states ? groupStates(def.variants, states) : undefined;
+        if (def.comparison) {
+            blocks.push({
+                kind: 'grid',
+                title: `${def.comparison.rowLabel} × ${def.comparison.columnLabel}`,
+                size: def.comparison.size ?? def.specimenSize ?? 'regular',
+                comparison: def.comparison,
+            });
+        }
+        else if (grouped && def.variants) {
+            // Grouped rows place several cells beside a row header, so full-width (itemsFill) slots do
+            // not force 402px cells here; a cell's own `fill` still stretches its specimen.
+            blocks.push({ kind: 'grouped', title: 'Variant × configuration', size: def.specimenSize ?? 'regular', groups: grouped.groups });
+            states = grouped.leftovers;
+        }
+        else if (def.variants) {
+            blocks.push({ kind: 'list', title: 'Variants', size: slotSize(def, def.variants), items: slotItems(def.variants) });
+        }
+        else if (def.render) {
+            blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
+        }
+    }
+    if (states) {
+        const secondary = blocks.length > 0 && blocks[0].kind !== 'list';
+        blocks.push({
+            kind: 'list',
+            title: secondary ? 'Other configurations' : 'States / configurations',
+            size: slotSize(def, states),
+            items: slotItems(states),
+        });
+    }
+    if (blocks.length === 0 && !hide.variants && !hide.states) {
+        blocks.push({ kind: 'empty', title: 'Examples', message: 'No examples documented.' });
+    }
+    return blocks;
+}
+/** Side by side or stacked, for a page with exactly two blocks. Tries both and keeps the shorter;
+ *  stays stacked unless side by side saves at least PLACEMENT_MIN_SAVING. Only a list can move
+ *  beside a first block that hugs its content, and only when its cells keep their minimum width. */
+export function choosePlacement({ available, gap, first, second }) {
+    if (second.kind !== 'list' || !second.itemCount || !second.size)
+        return 'stacked';
+    const firstWidth = first.width ?? available;
+    if (firstWidth > available * 0.7)
+        return 'stacked';
+    const room = available - firstWidth - gap;
+    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 rowHeight = second.height / Math.max(1, stackedRows);
+    const sideHeight = Math.max(first.height, sideRows * rowHeight);
+    const stackedHeight = first.height + gap + second.height;
+    return sideHeight <= stackedHeight - PLACEMENT_MIN_SAVING ? 'side' : 'stacked';
+}
+/** Props box columns: two, filled across first, for 4+ props when each column keeps its minimum. */
+export function propsColumns(count, width) {
+    return count >= 4 && width >= 2 * PROPS_MIN_COLUMN_WIDTH + PROPS_COLUMN_GAP ? 2 : 1;
+}

package/dist/native/catalog/tokens.js

@@ -0,0 +1,119 @@
+/**
+ * Catalog-only design tokens — the visual system of the catalog interface itself.
+ *
+ * Deliberately independent of any host app's design-system tokens (DS_SEMANTIC / DS_PALETTE /
+ * DS_SPACING): the catalog documents a design system, it does not consume one. Keeping its chrome
+ * on its own tokens means a change to the host app's tokens never restyles the catalog, and this
+ * folder can be copied into another app's repo unchanged.
+ *
+ * Values match the approved Studio Matrix references
+ * (docs/design/2026-10-06-catalog-studio-matrix-*.html), with one deliberate exception:
+ * `textMuted` stays #666666 because the references' #777777 fails WCAG AA contrast.
+ */
+export const CATALOG_TYPE = {
+    xs: 10,
+    tableHeader: 11,
+    sm: 12,
+    panelHeading: 13,
+    md: 14,
+    lg: 16,
+    brand: 17,
+    xl: 20,
+    '2xl': 24,
+    pageTitle: 28,
+    '3xl': 32,
+    '4xl': 40,
+};
+export const CATALOG_SPACE = {
+    xs: 4,
+    sm: 8,
+    md: 12,
+    lg: 16,
+    xl: 24,
+    '2xl': 32,
+    '3xl': 40,
+};
+export const CATALOG_RADIUS = {
+    sm: 8,
+    control: 9,
+    md: 12,
+    card: 14,
+};
+/** Exact chrome measurements from the approved references that are not spacing-scale steps. */
+export const CATALOG_LAYOUT = {
+    sidebarWidth: 264,
+    sidebarPaddingTop: 24,
+    sidebarPaddingX: 18,
+    mainPaddingTop: 28,
+    mainPaddingX: 32,
+    controlSize: 44,
+    focusRingWidth: 3,
+    navItemPaddingY: 8,
+    navItemPaddingX: 10,
+    panelPadding: 20,
+    factPaddingY: 9,
+    blockLabelGap: 14,
+    blockGap: 28,
+    /** Sidebar logo header (design `docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html`,
+     *  "C · Adaptive", approved 2026-10-08) — see `native/catalog/logoLayout.ts`. */
+    logoMark: 32,
+    logoWordmarkHeight: 28,
+    logoCaptionGap: 6,
+};
+/** Max width of the main content column. */
+export const CATALOG_MAX_CONTENT_WIDTH = 1200;
+/** When to reach for each catalog-chrome type size. Rendered in the framework catalog's Type
+ *  Scale page. */
+export const CATALOG_TYPE_USE = {
+    xs: 'Sidebar group labels (uppercase); a prop\'s type annotation.',
+    tableHeader: 'Grid column headers and list cell captions (uppercase).',
+    sm: 'Breadcrumb, catalog caption, block labels, prop names and descriptions.',
+    panelHeading: 'Reference-panel headings: Guidance, Quick reference, Props (uppercase).',
+    md: 'Default body text: descriptions, nav links, grid row headers, quick-reference rows, the filter field.',
+    lg: 'Pager arrows and the filter field\'s clear (×) glyph.',
+    brand: 'The app name at the top of the sidebar.',
+    xl: 'Reserved — no current consumer.',
+    '2xl': 'Reserved — no current consumer.',
+    pageTitle: 'The selected page\'s title.',
+    '3xl': 'Reserved — no current consumer.',
+    '4xl': 'Reserved — no current consumer.',
+};
+/** When to reach for each catalog-chrome spacing step. Rendered in the framework catalog's
+ *  Spacing page. */
+export const CATALOG_SPACE_USE = {
+    xs: 'Tight gap — e.g. between a token\'s rendered value and its use-note.',
+    sm: 'Small gap — below the filter field; between a preview frame\'s label and its demo.',
+    md: 'Medium gap — between a card\'s contents; token-row divider padding.',
+    lg: 'Grid and list cell padding (16px); row gap in scale galleries.',
+    xl: 'Preview-card padding; gap between preview frames.',
+    '2xl': 'Gap between the reference panel\'s Guidance and Quick reference columns.',
+    '3xl': 'Bottom padding of the main column.',
+};
+export const CATALOG_COLOR = {
+    text: '#181818',
+    // #666666, not the references' #777777: #777 is 4.14–4.48:1 on this file's surfaces (WCAG AA
+    // needs 4.5:1); #666 is 5.3–5.7:1.
+    textMuted: '#666666',
+    /** Dividers inside grids, lists, props tables, token rows. */
+    border: '#e4e4e4',
+    /** Sidebar edge, reference card, filter field. */
+    borderHairline: '#dddddd',
+    /** Grid, list, and preview cards; pager buttons. */
+    borderStrong: '#d7d7d7',
+    /** Quick-reference row dividers. */
+    borderSubtle: '#eeeeee',
+    surface: '#ffffff',
+    /** Table headers, row headers, cell captions, filter field. */
+    surfaceMuted: '#fafafa',
+    /** Hover and pressed feedback on nav rows and buttons. */
+    surfacePressed: '#f1f3f8',
+    pageBackground: '#f6f6f4',
+    chip: '#eeeeee',
+    /** Active nav label, prop types, scale bars. */
+    accent: '#174dc6',
+    /** Active nav row background. */
+    accentSubtle: '#e9efff',
+    /** 3px keyboard focus ring on every catalog control. */
+    focusRing: '#c9d7ff',
+    code: 'Menlo',
+};

package/dist/native/catalog/types.js

@@ -0,0 +1 @@
+export {};

package/native/catalog/CatalogShell.tsx

@@ -1,5 +1,6 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { AccessibilityInfo, Platform, ScrollView, StyleSheet, Text, View, findNodeHandle } from 'react-native';
+import type { ImageSourcePropType } from 'react-native';
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
 import { CatalogSidebar } from './CatalogSidebar';
 import { SectionBlock } from './SectionBlock';
@@ -43,6 +44,7 @@ function resetMainScroll(scrollView: ScrollView | null): void {
  */
 export function CatalogShell<TId extends string>({
   appName,
+  logoImageSource,
   title,
   groups,
   sections,
@@ -50,6 +52,9 @@ export function CatalogShell<TId extends string>({
 }: {
   /** Short product/app name — the sidebar logo and the breadcrumb root. */
   appName: string;
+  /** Optional logo image, validated and bundled by `cli/workspace.ts` from the project's `logo`
+   *  config field. See `CatalogSidebar`'s own doc comment for the approved layout rule. */
+  logoImageSource?: ImageSourcePropType;
   /** What this catalog is (e.g. "Component Catalog") — the sidebar caption. */
   title: string;
   groups: NavGroup<TId>[];
@@ -122,7 +127,7 @@ export function CatalogShell<TId extends string>({
 
   return (
     <View style={styles.root}>
-      <CatalogSidebar logo={appName} caption={title} groups={groups} active={active} onPress={select} />
+      <CatalogSidebar logo={appName} logoImageSource={logoImageSource} caption={title} groups={groups} active={active} onPress={select} />
       <ScrollView ref={scrollRef} style={styles.main} contentContainerStyle={styles.mainContent}>
         {activeDef ? (
           <SectionBlock