@krapwoo/ds-viewer 0.9.1 → 0.11.0

package/dist/native/catalog/pageApi.js

@@ -0,0 +1,408 @@
+export function defineCatalogPage(page) {
+    return { ...page, __dsViewerPage: true };
+}
+function mergePropNotes(component, propNotes) {
+    const own = component.props.map((prop) => ({
+        name: prop.name,
+        type: prop.type,
+        required: prop.required,
+        default: prop.default,
+        desc: propNotes?.[prop.name] ? `${prop.desc} ${propNotes[prop.name]}`.trim() : prop.desc,
+    }));
+    // Design §3: props inherited from node_modules (e.g. `extends TextInputProps`) are summarised as
+    // one row per source instead of being listed individually.
+    const inherited = component.inheritedFrom.map((source) => ({
+        name: `${source} props`,
+        type: 'inherited',
+        required: true,
+        desc: `Plus all ${source} props, not listed individually.`,
+    }));
+    return [...own, ...inherited];
+}
+/** Human-readable problems with a page's (or, V2d, a family member's own) `composedOf`, in
+ *  declaration order: one line per entry whose `component` isn't in `knownNames` (every real
+ *  component name, documented or not, plus every page id and family member id — the full catalog
+ *  inventory `buildCatalogSections` already has on hand). Empty when every name resolves,
+ *  including when `composedOf` itself is omitted. Takes only the `component` field (never the
+ *  narrower `ComposedOfEntry[]` type) so `cli/doctor.ts`'s own statically-read `{ component:
+ *  string }[]` shape — which never carries `role`/`relationship` — satisfies it too. */
+export function validateComposedOf(composedOf, knownNames) {
+    if (!composedOf)
+        return [];
+    return composedOf
+        .filter((entry) => !knownNames.has(entry.component))
+        .map((entry) => `composedOf references unknown component "${entry.component}".`);
+}
+/** Validates a family page (spec §5.1): exactly one whole belonging to no section; every other
+ *  member in exactly one section; every parent resolving within the page with no cycles; member
+ *  and alias ids unique catalog-wide and never colliding with a page id, except the whole (whose
+ *  id equals its own page's id). Returns `[]` for a page without `members`. `allPageIds` and
+ *  `otherMemberIds` are the ids used by every *other* page/member in the catalog. */
+export function validateFamily(page, allPageIds, otherMemberIds) {
+    const { members } = page;
+    if (!members || members.length === 0)
+        return [];
+    const issues = [];
+    if (!page.whole || !page.sections) {
+        issues.push(`Family "${page.id}": "members" requires both "whole" and "sections".`);
+        return issues;
+    }
+    const whole = page.whole;
+    const byId = new Map(members.map((m) => [m.id, m]));
+    if (!byId.has(whole)) {
+        issues.push(`Family "${page.id}": whole "${whole}" is not one of its members.`);
+    }
+    if (whole !== page.id) {
+        issues.push(`Family "${page.id}": whole "${whole}" must have the same id as the page.`);
+    }
+    // V2c item 2: a section listing an id that is not one of the page's own members — reported
+    // here, rather than left to crash the renderer or silently occupy authored order in `numberFor`.
+    // N6: a `list`-section member authored with a specimen — `FoldedRow` never renders one, so this
+    // degrades to a silently dropped specimen rather than a crash, same as the unknown-id case.
+    for (const section of page.sections) {
+        for (const id of section.members) {
+            const resolved = byId.get(id);
+            if (!resolved) {
+                issues.push(`Family "${page.id}": section "${section.label}" lists "${id}", which is not a member of this page.`);
+                continue;
+            }
+            if (section.kind === 'list' && resolved.hasSpecimens) {
+                issues.push(`Family "${page.id}": "${id}" has specimens, but list sections show members as folded rows without specimens.`);
+            }
+        }
+    }
+    const sectionCountById = new Map();
+    for (const section of page.sections) {
+        for (const id of section.members)
+            sectionCountById.set(id, (sectionCountById.get(id) ?? 0) + 1);
+    }
+    if (sectionCountById.has(whole)) {
+        issues.push(`Family "${page.id}": the whole "${whole}" must not appear in any section.`);
+    }
+    for (const m of members) {
+        if (m.id === whole)
+            continue;
+        const count = sectionCountById.get(m.id) ?? 0;
+        if (count === 0)
+            issues.push(`Family "${page.id}": member "${m.id}" is not in any section.`);
+        else if (count > 1)
+            issues.push(`Family "${page.id}": member "${m.id}" is in more than one section.`);
+    }
+    for (const m of members) {
+        if (m.parent === undefined)
+            continue;
+        if (!byId.has(m.parent)) {
+            issues.push(`Family "${page.id}": member "${m.id}" has an unknown parent "${m.parent}".`);
+            continue;
+        }
+        const seen = new Set([m.id]);
+        let current = m.parent;
+        let cycle = false;
+        while (current !== undefined) {
+            if (seen.has(current)) {
+                cycle = true;
+                break;
+            }
+            seen.add(current);
+            current = byId.get(current)?.parent;
+        }
+        if (cycle)
+            issues.push(`Family "${page.id}": member "${m.id}" has a parent cycle.`);
+    }
+    const seenInPage = new Set();
+    const checkId = (id, isWhole) => {
+        if (seenInPage.has(id))
+            issues.push(`Family "${page.id}": id "${id}" is used more than once on this page.`);
+        seenInPage.add(id);
+        if (isWhole)
+            return;
+        if (allPageIds.has(id))
+            issues.push(`Family "${page.id}": id "${id}" collides with another page's id.`);
+        if (otherMemberIds.has(id))
+            issues.push(`Family "${page.id}": id "${id}" collides with another member or alias elsewhere in the catalog.`);
+    };
+    for (const m of members) {
+        checkId(m.id, m.id === whole);
+        for (const alias of m.aliases ?? [])
+            checkId(alias, false);
+    }
+    for (const alias of page.aliases ?? [])
+        checkId(alias, false);
+    // Slice D1 item 3: an anatomy `member` item must name a real, non-whole member of this page, and
+    // each member may be pinned to the picture's legend at most once.
+    // D2 item A2: a member item whose member has no number — outside every `inWhole` section, or
+    // under a parent that isn't itself numbered — must also be reported; left unchecked, it renders
+    // a blank 34px pin slot in the legend and nothing at all from `AnatomyPin` in the picture.
+    if (page.anatomy) {
+        const numbered = numberFor(page);
+        const seenAnatomyMembers = new Set();
+        for (const group of page.anatomy.groups) {
+            for (const item of group.items) {
+                if (!('member' in item))
+                    continue;
+                if (item.member === whole) {
+                    issues.push(`Family "${page.id}": anatomy item "${item.member}" names the whole.`);
+                    continue;
+                }
+                if (!byId.has(item.member)) {
+                    issues.push(`Family "${page.id}": anatomy item "${item.member}" is not a member of this page.`);
+                    continue;
+                }
+                if (seenAnatomyMembers.has(item.member)) {
+                    issues.push(`Family "${page.id}": anatomy lists member "${item.member}" more than once.`);
+                    continue;
+                }
+                seenAnatomyMembers.add(item.member);
+                if (!numbered.has(item.member)) {
+                    issues.push(`Family "${page.id}": anatomy item "${item.member}" has no number.`);
+                }
+            }
+        }
+    }
+    return issues;
+}
+/** Slice D1 item 2: anatomy-first numbering — the only numbering rule for every family page (not
+ *  only one with `anatomy` set; it superseded the earlier whole-and-letters rule outright). The
+ *  whole gets no number. A **top-level part** is any member of an `inWhole` section whose `parent`
+ *  is the whole, or who has no `parent` at all (an in-whole root with no Swift parent edge is still
+ *  top-level) — numbered `1`, `2`, `3`… in authored order (the order a member first appears
+ *  scanning `inWhole` sections, in section order). A child takes its parent's number plus `.1`,
+ *  `.2`, … in authored order. Members outside any `inWhole` section (Related) get no number at
+ *  all. Returns an empty map for a page without members. */
+export function numberFor(page) {
+    const outline = new Map();
+    const { whole, sections, members } = page;
+    if (!whole || !sections || !members)
+        return outline;
+    const memberIds = new Set(members.map((m) => m.id));
+    // Only `inWhole` sections contribute to numbering — a Related section's members are never
+    // top-level parts, and never occupy authored order (so they can't be skipped-over roots either).
+    const authoredOrder = [];
+    const seen = new Set();
+    for (const section of sections) {
+        if (!section.inWhole)
+            continue;
+        for (const id of section.members) {
+            if (!seen.has(id) && memberIds.has(id)) {
+                seen.add(id);
+                authoredOrder.push(id);
+            }
+        }
+    }
+    const parentOf = new Map(members.map((m) => [m.id, m.parent]));
+    const childrenOf = new Map();
+    for (const id of authoredOrder) {
+        const parent = parentOf.get(id);
+        if (parent === undefined)
+            continue;
+        childrenOf.set(parent, [...(childrenOf.get(parent) ?? []), id]);
+    }
+    // V2c item 14's cycle guard: bad data already reported by `validateFamily` must degrade to a
+    // partial outline, never an infinite recursion.
+    const assignChildren = (parentId, parentNumber, level, visited) => {
+        const kids = childrenOf.get(parentId) ?? [];
+        kids.forEach((childId, index) => {
+            if (visited.has(childId))
+                return;
+            visited.add(childId);
+            const number = `${parentNumber}.${index + 1}`;
+            outline.set(childId, { number, level: level + 1 });
+            assignChildren(childId, number, level + 1, visited);
+        });
+    };
+    const visited = new Set([whole]);
+    const topLevel = authoredOrder.filter((id) => {
+        const parent = parentOf.get(id);
+        return parent === undefined || parent === whole;
+    });
+    let next = 0;
+    for (const id of topLevel) {
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        next += 1;
+        const number = String(next);
+        outline.set(id, { number, level: 2 });
+        assignChildren(id, number, 2, visited);
+    }
+    return outline;
+}
+function orderGroups(groupIds, groupOrder) {
+    const listed = groupOrder ?? [];
+    const labels = [...groupIds.keys()];
+    const ordered = [...listed.filter((label) => groupIds.has(label)), ...labels.filter((label) => !listed.includes(label)).sort()];
+    return ordered.map((label) => ({ label, ids: groupIds.get(label) ?? [] }));
+}
+/**
+ * Builds the viewer's `sections`/`groups` from authored pages plus generated component data — the
+ * logic the generated entry file (Task 12) runs on every bundle. A documented component's page
+ * supplies everything page-authored; its props always come from `components` (never authored by
+ * hand). A component with no page still appears, with "No examples documented." (design §2).
+ */
+export function buildCatalogSections(
+// The generated page index (Task 9) always fills in `id` (`id ?? component ?? file stem`) and
+// `file` (the page's own project-relative path), so pages arriving here have both even though
+// authors may omit them.
+pages, components, groupOrder) {
+    const componentByName = new Map(components.map((c) => [c.name, c]));
+    // A page with `members` documents every member's own `component` instead of `page.component ??
+    // page.id` — that fallback never applies to a family page (spec §5.1).
+    const documented = new Set();
+    for (const page of pages) {
+        if (page.members && page.members.length > 0) {
+            for (const member of page.members)
+                if (member.component)
+                    documented.add(member.component);
+        }
+        else {
+            documented.add(page.component ?? page.id);
+        }
+    }
+    const groupIds = new Map();
+    const addToGroup = (group, id) => groupIds.set(group, [...(groupIds.get(group) ?? []), id]);
+    // Every name a page's (or, V2d, a family member's own) `composedOf` could legitimately point
+    // at: every real component (documented or not — an undocumented one is still a real part of the
+    // design system), every page id (token pages, standalone recipes, …), every family member id
+    // (a member's composedOf may point at a sibling member, or a member of another family), and —
+    // N8 — every member alias and page-level alias: `FamilyPage`'s own `resolvesAddress` already
+    // treats these as working links (`aliasTargets`), so this warning must accept the same names.
+    const knownComposedOfNames = new Set([
+        ...componentByName.keys(),
+        ...pages.map((page) => page.id),
+        ...pages.flatMap((page) => (page.members ?? []).map((member) => member.id)),
+        ...pages.flatMap((page) => (page.members ?? []).flatMap((member) => member.aliases ?? [])),
+        ...pages.flatMap((page) => page.aliases ?? []),
+    ]);
+    // Every id/alias a family page's own `members` and `aliases` use, keyed by page id — gathered up
+    // front so `validateFamily` (above) can check catalog-wide uniqueness against every *other*
+    // page's ids.
+    const allPageIds = new Set(pages.map((page) => page.id));
+    const familyIdsByPage = new Map();
+    for (const page of pages) {
+        if (!page.members)
+            continue;
+        const ids = new Set();
+        for (const member of page.members) {
+            ids.add(member.id);
+            for (const alias of member.aliases ?? [])
+                ids.add(alias);
+        }
+        for (const alias of page.aliases ?? [])
+            ids.add(alias);
+        familyIdsByPage.set(page.id, ids);
+    }
+    // Design §4 "duplicate-page-id" rule's viewer-side equivalent — this is the one place in the
+    // whole viewer that already resolves every page's id to build sections/groups, so it costs
+    // nothing extra to also notice two pages claiming the same one (`sectionsById` in
+    // `CatalogShell.tsx` would otherwise just let the last one silently win).
+    const seenIds = new Set();
+    const sections = pages.map((page) => {
+        // N2: `seenIds` must be populated (and consulted, below in the undocumented-component loop)
+        // regardless of `__DEV__` — only the `console.warn` calls are development-only diagnostics;
+        // a production bundle (Metro's `__DEV__ = false`) still needs the stub-skip to work.
+        if (seenIds.has(page.id)) {
+            if (globalThis.__DEV__) {
+                console.warn(`[Catalog] Page id "${page.id}" is used by more than one page; only the last one will show. Give one of them its own "id".`);
+            }
+        }
+        seenIds.add(page.id);
+        if (globalThis.__DEV__) {
+            for (const issue of validateComposedOf(page.composedOf, knownComposedOfNames))
+                console.warn(`[Catalog] ${page.id}: ${issue}`);
+            // V2d item 4: the same validation, per family member's own `composedOf`.
+            for (const member of page.members ?? []) {
+                for (const issue of validateComposedOf(member.composedOf, knownComposedOfNames)) {
+                    console.warn(`[Catalog] ${page.id}.${member.id}: ${issue}`);
+                }
+            }
+        }
+        const isFamily = page.members !== undefined && page.members.length > 0;
+        const componentName = isFamily ? undefined : (page.component ?? page.id);
+        const component = componentName ? componentByName.get(componentName) : undefined;
+        addToGroup(page.group, page.id);
+        let family;
+        if (isFamily) {
+            const otherPageIds = new Set([...allPageIds].filter((id) => id !== page.id));
+            const otherMemberIds = new Set();
+            for (const [id, ids] of familyIdsByPage)
+                if (id !== page.id)
+                    for (const memberId of ids)
+                        otherMemberIds.add(memberId);
+            // `hasSpecimens` is computed here, as doctor does, so the list-section rule also fires in
+            // the development console, not only in `ds-viewer doctor`.
+            const members = page.members.map((member) => ({
+                ...member,
+                hasSpecimens: Boolean(member.variants?.items?.length || member.states?.items?.length || member.comparison),
+            }));
+            const issues = validateFamily({ ...page, members, anatomy: page.anatomy }, otherPageIds, otherMemberIds);
+            if (globalThis.__DEV__) {
+                for (const issue of issues)
+                    console.error(`[Catalog] ${issue}`);
+            }
+            family = {
+                whole: page.whole,
+                sections: page.sections,
+                outline: numberFor(page),
+                notShown: page.notShown,
+                aliases: page.aliases,
+                apiLabel: page.apiLabel,
+                anatomy: page.anatomy,
+                members: page.members.map((member) => {
+                    const memberComponent = member.component ? componentByName.get(member.component) : undefined;
+                    return {
+                        ...member,
+                        props: memberComponent ? mergePropNotes(memberComponent, undefined) : undefined,
+                        path: memberComponent?.file ?? member.source,
+                    };
+                }),
+            };
+        }
+        // Important finding 4: a standalone page (no matching component record) has no props to show
+        // and nothing to say "This component takes no props" about — hide the Props box, and fall back
+        // 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.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,
+            // `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,
+            specimenSurface: page.specimenSurface,
+            previewWidths: page.previewWidths,
+            previewLayout: page.previewLayout,
+            hide: component ? page.hide : { ...page.hide, props: true },
+            composedOf: page.composedOf,
+            internalProps: page.internalProps,
+            intentionalStaticPreview: page.intentionalStaticPreview,
+            family,
+        };
+    });
+    const undocumented = components.filter((component) => !documented.has(component.name)).sort((a, b) => a.name.localeCompare(b.name));
+    for (const component of undocumented) {
+        const id = component.name;
+        // V2c item 7: a component with no page of its own, whose name happens to collide with an
+        // authored page's own id (most likely a family page, which never resolves `documented` via the
+        // `page.component ?? page.id` fallback) — its stub must never win that id in `sections`.
+        if (seenIds.has(id)) {
+            if (globalThis.__DEV__) {
+                console.warn(`[Catalog] Component "${id}" has no catalog page of its own, and "${id}" is already used by another page's id; skipping its stub.`);
+            }
+            continue;
+        }
+        sections.push({ id, description: 'No examples documented.', path: component.file, props: mergePropNotes(component, undefined) });
+        addToGroup('Components', id);
+    }
+    return { sections, groups: orderGroups(groupIds, groupOrder) };
+}

package/dist/native/catalog/tokens.js

@@ -26,6 +26,30 @@ export const CATALOG_TYPE = {
     '3xl': 32,
     '4xl': 40,
 };
+export const CATALOG_FONT = { code: 'Menlo, monospace' };
+/** The catalog's fixed set of typography roles, each a complete `fontSize`/`fontWeight`/
+ *  `lineHeight` (plus `letterSpacing`/`textTransform`/`fontFamily` where the role needs them)
+ *  built on `CATALOG_TYPE`. Every catalog-chrome text style spreads one of these rather than
+ *  setting its own typography properties directly (enforced by
+ *  `__tests__/textRoles.test.ts`). */
+export const CATALOG_TEXT = {
+    pageTitle: { fontSize: CATALOG_TYPE.pageTitle, fontWeight: '700', lineHeight: 34 },
+    heading1: { fontSize: CATALOG_TYPE['2xl'], fontWeight: '700', lineHeight: 30 },
+    heading2: { fontSize: CATALOG_TYPE.xl, fontWeight: '700', lineHeight: 24 },
+    heading3: { fontSize: CATALOG_TYPE.lg, fontWeight: '700', lineHeight: 22 },
+    icon: { fontSize: CATALOG_TYPE.lg, fontWeight: '400', lineHeight: 22 },
+    body: { fontSize: CATALOG_TYPE.md, fontWeight: '400', lineHeight: 20 },
+    bodyStrong: { fontSize: CATALOG_TYPE.md, fontWeight: '700', lineHeight: 20 },
+    caption: { fontSize: CATALOG_TYPE.sm, fontWeight: '400', lineHeight: 18 },
+    captionStrong: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', lineHeight: 18 },
+    label: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', lineHeight: 18, letterSpacing: 0.72, textTransform: 'uppercase' },
+    micro: { fontSize: CATALOG_TYPE.xs, fontWeight: '400', lineHeight: 14 },
+    microLabel: { fontSize: CATALOG_TYPE.xs, fontWeight: '700', lineHeight: 14, letterSpacing: 0.6, textTransform: 'uppercase' },
+    code: { fontSize: CATALOG_TYPE.md, fontWeight: '400', lineHeight: 20, fontFamily: CATALOG_FONT.code },
+    codeSmall: { fontSize: CATALOG_TYPE.sm, fontWeight: '400', lineHeight: 18, fontFamily: CATALOG_FONT.code },
+    codeSmallStrong: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', lineHeight: 18, fontFamily: CATALOG_FONT.code },
+    codeMicro: { fontSize: CATALOG_TYPE.xs, fontWeight: '400', lineHeight: 14, fontFamily: CATALOG_FONT.code },
+};
 export const CATALOG_SPACE = {
     xs: 4,
     sm: 8,
@@ -69,21 +93,42 @@ export const CATALOG_LAYOUT = {
 /** 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. */
+ *  Scale page. Every size is now consumed through a `CATALOG_TEXT` role (see `CATALOG_TEXT_USE`)
+ *  rather than directly. */
 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: "The major-update banner's close (×) glyph.",
-    '2xl': "The update page's version numbers and the arrow between them.",
-    pageTitle: 'The selected page\'s title.',
+    xs: 'Backs the `micro`, `microLabel` and `codeMicro` roles: token values and meta captions; sidebar group labels and OS badges (uppercase); a prop\'s type and default value (monospace).',
+    tableHeader: 'Reserved — no current consumer; grid column headers and list cell captions now use the `captionStrong` role (built on `sm`).',
+    sm: 'Backs the `caption`, `captionStrong`, `label`, `codeSmall` and `codeSmallStrong` roles: breadcrumbs, block/prop descriptions, swatch/token names, table captions, monospace prop names and file paths.',
+    panelHeading: 'Reserved — no current consumer; reference-panel and update-page headings now use the `label` role (built on `sm`).',
+    md: 'Backs the `body`, `bodyStrong` and `code` roles: descriptions, nav links, the filter field, switch labels, a long unbroken value that needs to wrap at its \'/\'s (monospace).',
+    lg: 'Backs the `heading3` and `icon` roles: a result note\'s title; pager arrows and the filter field\'s clear (×) glyph.',
+    brand: 'Reserved — no current consumer; the sidebar app name now uses the `heading2` role (built on `xl`).',
+    xl: 'Backs the `heading2` role: the app name at the top of the sidebar.',
+    '2xl': 'Backs the `heading1` role: the update page\'s version numbers and the arrow between them.',
+    pageTitle: 'Backs the `pageTitle` role: the selected page\'s title, including the update page\'s own title.',
     '3xl': 'Reserved — no current consumer.',
     '4xl': 'Reserved — no current consumer.',
 };
+/** When to reach for each catalog-chrome typography role. Rendered in the framework catalog's
+ *  Type Scale page. */
+export const CATALOG_TEXT_USE = {
+    pageTitle: 'The selected page\'s title, including the update page\'s own title.',
+    heading1: 'The update page\'s version numbers and the arrow between them.',
+    heading2: 'The app name at the top of the sidebar.',
+    heading3: 'A result note\'s title (the update page\'s success/failure banner).',
+    icon: 'Glyph-only controls: pager arrows, the filter field\'s clear (×) glyph, the update banner\'s close (×) glyph.',
+    body: 'Default body text: descriptions, nav links, the filter field, update-page facts/notes/steps.',
+    bodyStrong: 'Emphasised body text: grid/list row headers, switch and step labels, inline-bold notice text.',
+    caption: 'Secondary text: breadcrumbs, status captions, block/prop descriptions, sidebar subtitle/footer, update-page captions.',
+    captionStrong: 'Emphasised secondary text: grid column headers, grid/list/table captions, reference-panel subheadings, swatch/token names, replay and result links, step-icon glyphs.',
+    label: 'Uppercase labels and headings: block and preview-frame labels, token-section labels, reference-panel and update-page headings.',
+    micro: 'The smallest text: token values and meta captions, a prop\'s default-value label.',
+    microLabel: 'Uppercase micro labels: variant-group names, sidebar group labels, OS badges.',
+    code: 'Monospace body text: a long unbroken value that needs to wrap at its \'/\'s.',
+    codeSmall: 'Monospace secondary text: a prop\'s optional marker, the update page\'s inline code, file paths and log lines.',
+    codeSmallStrong: 'Emphasised monospace secondary text: a prop\'s own name.',
+    codeMicro: 'Monospace micro text: a prop\'s type and default value.',
+};
 /** When to reach for each catalog-chrome spacing step. Rendered in the framework catalog's
  *  Spacing page. */
 export const CATALOG_SPACE_USE = {
@@ -127,7 +172,17 @@ export const CATALOG_COLOR = {
     accentSubtle: '#e9efff',
     /** 3px keyboard focus ring on every catalog control. */
     focusRing: '#c9d7ff',
-    code: 'Menlo',
+    /** Family-page Part tree connector line (Slice D1/D2) — the approved reference's own line color
+     *  has no match among the other tokens above. */
+    treeLine: '#a9bdf0',
+    /** Family-page API code block: a dark surface and its text, the one place the catalog shows a
+     *  member's raw API signature. Dark on purpose so it reads as code, not as catalog chrome. */
+    codeSurface: '#1d1d1f',
+    codeOnSurface: '#e8e8e8',
+    /** @deprecated kept for the public API; re-points at `CATALOG_FONT.code` so there is one source
+     *  of truth. New code should reach for `CATALOG_FONT.code` (or a `CATALOG_TEXT` `code*` role)
+     *  instead. */
+    code: CATALOG_FONT.code,
     /** Major-update banner background/border/text (design §5 "Viewer notice"). */
     warning: '#8a4b00',
     warningSubtle: '#fff4e0',

package/native/catalog/BoundedOverlayViewport.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { Platform, StyleSheet, Text, View } from 'react-native';
-import { CATALOG_COLOR, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_TEXT } from './tokens';
 import { isFiniteOverlaySize, overlayStageDimensions, resolveOverlayViewport, type OverlaySlot } from './overlayViewport';
 
 function isWeb(): boolean {
@@ -108,5 +108,5 @@ const styles = StyleSheet.create({
     height: '100%',
     borderWidth: 0,
   },
-  status: { position: 'absolute', fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  status: { position: 'absolute', ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/CatalogButton.tsx

@@ -1,6 +1,6 @@
 import React, { forwardRef, useState } from 'react';
 import { ActivityIndicator, Pressable, StyleSheet, Text, type View } from 'react-native';
-import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TEXT } from './tokens';
 
 /** The viewer's own button, for catalog chrome and demo triggers (not an app component): a rounded
  *  rectangle, primary in the accent blue, secondary outlined. `disabled` greys it and stops the
@@ -77,7 +77,7 @@ const styles = StyleSheet.create({
   disabled: { backgroundColor: CATALOG_COLOR.controlDisabled, borderColor: CATALOG_COLOR.controlDisabled },
   // Same ring as the sidebar's: an outline, so focusing never shifts the layout.
   focus: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing } as object,
-  label: { fontSize: CATALOG_TYPE.md, fontWeight: '700' },
+  label: { ...CATALOG_TEXT.bodyStrong },
   labelPrimary: { color: '#ffffff' },
   labelSecondary: { color: CATALOG_COLOR.text },
   labelBusy: { color: CATALOG_COLOR.textMuted },

package/native/catalog/CatalogSearchInput.tsx

@@ -1,6 +1,6 @@
 import { useRef, useState } from 'react';
 import { View, Text, TextInput, Pressable, StyleSheet } from 'react-native';
-import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS, CATALOG_LAYOUT } from './tokens';
+import { CATALOG_TEXT, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS, CATALOG_LAYOUT } from './tokens';
 
 /**
  * Plain search input for filtering the catalog's own sidebar nav. Deliberately built from bare
@@ -74,7 +74,7 @@ const styles = StyleSheet.create({
     backgroundColor: CATALOG_COLOR.surfaceMuted,
   },
   boxFocused: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing },
-  input: { flex: 1, fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text, padding: 0 },
+  input: { flex: 1, ...CATALOG_TEXT.body, color: CATALOG_COLOR.text, padding: 0 },
   // A full 44×44 target: react-native-web does not honor hitSlop for pointer or keyboard.
   clearButton: {
     width: CATALOG_LAYOUT.controlSize, height: CATALOG_LAYOUT.controlSize,
@@ -82,5 +82,5 @@ const styles = StyleSheet.create({
   },
   focusRing: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing },
   clearButtonActive: { backgroundColor: CATALOG_COLOR.surfacePressed },
-  clear: { fontSize: CATALOG_TYPE.lg, color: CATALOG_COLOR.textMuted, paddingHorizontal: 2 },
+  clear: { ...CATALOG_TEXT.icon, color: CATALOG_COLOR.textMuted, paddingHorizontal: 2 },
 });