@krapwoo/ds-viewer 0.9.1 → 0.10.0

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,10 @@ export const CATALOG_COLOR = {
     accentSubtle: '#e9efff',
     /** 3px keyboard focus ring on every catalog control. */
     focusRing: '#c9d7ff',
-    code: 'Menlo',
+    /** @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 },
 });

package/native/catalog/CatalogShell.tsx

@@ -1,7 +1,7 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { AccessibilityInfo, Platform, Pressable, ScrollView, StyleSheet, Text, View, findNodeHandle } from 'react-native';
 import type { ImageSourcePropType } from 'react-native';
-import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_MAX_CONTENT_WIDTH, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TEXT } from './tokens';
 import { CatalogSidebar } from './CatalogSidebar';
 import { SectionBlock } from './SectionBlock';
 import { UpdatePanel } from './UpdatePanel';
@@ -101,11 +101,11 @@ const bannerStyles = StyleSheet.create({
     paddingHorizontal: 14,
     marginBottom: 18,
   },
-  text: { flex: 1, fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.warning },
-  bold: { fontWeight: '700' },
-  link: { color: CATALOG_COLOR.warning, fontWeight: '700', textDecorationLine: 'underline' },
+  text: { flex: 1, ...CATALOG_TEXT.body, color: CATALOG_COLOR.warning },
+  bold: { ...CATALOG_TEXT.bodyStrong },
+  link: { ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.warning, textDecorationLine: 'underline' },
   close: { width: 32, height: 32, borderRadius: CATALOG_RADIUS.sm, alignItems: 'center', justifyContent: 'center' },
-  closeGlyph: { fontSize: CATALOG_TYPE.xl, color: CATALOG_COLOR.warning },
+  closeGlyph: { ...CATALOG_TEXT.icon, color: CATALOG_COLOR.warning },
 });
 
 /**
@@ -327,7 +327,7 @@ const styles = StyleSheet.create({
   // A `BoundedOverlayViewport` child document's own root: no sidebar/chrome, just the one
   // addressed node — sized by whatever that node itself renders, not the catalog's own layout.
   overlayDocumentRoot: { flex: 1 },
-  overlayUnavailable: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted, padding: CATALOG_SPACE.lg },
+  overlayUnavailable: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted, padding: CATALOG_SPACE.lg },
   main: { flex: 1 },
   mainContent: {
     width: '100%',
@@ -336,5 +336,5 @@ const styles = StyleSheet.create({
     paddingHorizontal: CATALOG_LAYOUT.mainPaddingX,
     paddingBottom: CATALOG_SPACE['3xl'],
   },
-  empty: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted },
+  empty: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/CatalogSidebar.tsx

@@ -1,7 +1,7 @@
 import { useState } from 'react';
 import { View, Text, ScrollView, Pressable, StyleSheet, Image } from 'react-native';
 import type { ImageSourcePropType, LayoutChangeEvent, NativeSyntheticEvent, ImageLoadEventData } 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';
 import { logoLayout } from './logoLayout';
 import { filterGroups, hashForId, UPDATE_PAGE_ID } from './catalogNavigation';
 import type { NavGroup } from './types';
@@ -153,8 +153,8 @@ export function CatalogSidebar<TId extends string>({
   const onLogoError = () => setLogoFailed(true);
   // Wrap detection for the "mark" row: the name Text's own measured height, not `onTextLayout`
   // (react-native-web's `Text` doesn't implement it) and not a character-count heuristic (wraps at
-  // a different length per name). More than one line of `CATALOG_TYPE.brand` means it wrapped.
-  const NAME_LINE_HEIGHT = Math.round(CATALOG_TYPE.brand * 1.3);
+  // a different length per name). More than one line of `CATALOG_TEXT.heading2` means it wrapped.
+  const NAME_LINE_HEIGHT = CATALOG_TEXT.heading2.lineHeight;
   const onNameLayout = (e: LayoutChangeEvent) => {
     setNameWrapped(e.nativeEvent.layout.height > NAME_LINE_HEIGHT * 1.5);
   };
@@ -235,8 +235,8 @@ const styles = StyleSheet.create({
     paddingBottom: CATALOG_LAYOUT.sidebarPaddingTop,
   },
   header: { marginBottom: 20 },
-  logo: { fontSize: CATALOG_TYPE.brand, fontWeight: '800', color: CATALOG_COLOR.text },
-  subtitle: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 2 },
+  logo: { ...CATALOG_TEXT.heading2, color: CATALOG_COLOR.text },
+  subtitle: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted, marginTop: 2 },
   subtitleAfterWordmark: { marginTop: CATALOG_LAYOUT.logoCaptionGap },
   mark: { width: CATALOG_LAYOUT.logoMark, height: CATALOG_LAYOUT.logoMark },
   wordmark: { height: CATALOG_LAYOUT.logoWordmarkHeight, alignSelf: 'flex-start' },
@@ -244,13 +244,12 @@ const styles = StyleSheet.create({
   inlineHeader: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md },
   inlineHeaderTop: { alignItems: 'flex-start' },
   inlineText: { flex: 1, minWidth: 0 },
-  empty: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, paddingHorizontal: CATALOG_LAYOUT.navItemPaddingX, paddingVertical: 8 },
+  empty: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted, paddingHorizontal: CATALOG_LAYOUT.navItemPaddingX, paddingVertical: 8 },
   footerContainer: {
     borderTopWidth: 1,
     borderTopColor: CATALOG_COLOR.borderHairline,
     paddingHorizontal: CATALOG_LAYOUT.sidebarPaddingX,
-    paddingTop: 10,
-    paddingBottom: 14,
+    paddingVertical: CATALOG_SPACE.md,
   },
   footerLink: {
     flexDirection: 'row',
@@ -263,13 +262,10 @@ const styles = StyleSheet.create({
   footerLinkHover: { backgroundColor: CATALOG_COLOR.surfacePressed },
   footerLinkActive: { backgroundColor: CATALOG_COLOR.accentSubtle },
   footerDot: { width: 8, height: 8, borderRadius: 4, backgroundColor: CATALOG_COLOR.accent, flexShrink: 0 },
-  footerLabel: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
-  footerLabelActive: { color: CATALOG_COLOR.accent, fontWeight: '700' },
+  footerLabel: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
+  footerLabelActive: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.accent },
   groupLabel: {
-    fontSize: CATALOG_TYPE.xs,
-    fontWeight: '800',
-    letterSpacing: 1,
-    textTransform: 'uppercase',
+    ...CATALOG_TEXT.microLabel,
     color: CATALOG_COLOR.text,
     marginTop: 22,
     marginBottom: 7,
@@ -285,6 +281,6 @@ const styles = StyleSheet.create({
   itemHover: { backgroundColor: CATALOG_COLOR.surfacePressed },
   itemActive: { backgroundColor: CATALOG_COLOR.accentSubtle },
   focusRing: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing },
-  label: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted },
-  labelActive: { color: CATALOG_COLOR.accent, fontWeight: '700' },
+  label: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted },
+  labelActive: { ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.accent },
 });

package/native/catalog/ComparisonGrid.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
-import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TEXT } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, axisItems, cellKey, gridMinWidth, indexCells, validateComparison } from './comparison';
 import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
 import { SpecimenAddressProvider } from './SpecimenAddress';
@@ -108,7 +108,7 @@ const styles = StyleSheet.create({
   headerCell: { backgroundColor: CATALOG_COLOR.surfaceMuted, justifyContent: 'center' },
   bodyRow: { minHeight: MATRIX_LAYOUT.rowMinHeight },
   specimenCell: { alignItems: 'center', justifyContent: 'center' },
-  headerText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
-  rowHeaderText: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
-  unavailable: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', textAlign: 'center', color: CATALOG_COLOR.textMuted },
+  headerText: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
+  rowHeaderText: { ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.text },
+  unavailable: { ...CATALOG_TEXT.caption, textAlign: 'center', color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/ComparisonGroups.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
-import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TEXT } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, type ListGroup } from './comparison';
 import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
 import { SpecimenAddressProvider } from './SpecimenAddress';
@@ -90,7 +90,7 @@ const styles = StyleSheet.create({
     borderRightWidth: 1,
     borderRightColor: CATALOG_COLOR.border,
   },
-  rowHeaderText: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
+  rowHeaderText: { ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.text },
   cells: { flex: 1, flexDirection: 'row' },
   cell: { flex: 1, borderRightWidth: 1, borderRightColor: CATALOG_COLOR.border },
   lastColumn: { borderRightWidth: 0 },
@@ -100,7 +100,7 @@ const styles = StyleSheet.create({
     borderBottomWidth: 1,
     borderBottomColor: CATALOG_COLOR.border,
   },
-  captionText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
+  captionText: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
   specimen: {
     flexGrow: 1,
     minHeight: MATRIX_LAYOUT.rowMinHeight,

package/native/catalog/ComparisonList.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
-import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TEXT } from './tokens';
 import { MATRIX_LAYOUT, listGeometry, type ListItem } from './comparison';
 import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
 import { SpecimenAddressProvider } from './SpecimenAddress';
@@ -107,7 +107,7 @@ const styles = StyleSheet.create({
     borderBottomWidth: 1,
     borderBottomColor: CATALOG_COLOR.border,
   },
-  captionText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
+  captionText: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
   specimen: {
     flexGrow: 1,
     minHeight: MATRIX_LAYOUT.rowMinHeight,

package/native/catalog/MotionSpecimen.tsx

@@ -1,6 +1,6 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { Animated, AccessibilityInfo, Pressable, StyleSheet, Text, View } from 'react-native';
-import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TEXT } from './tokens';
 import { motionReplayLabel, motionTranslatesDirectly, motionValueTarget, type MotionValueRange } from './motionValueDomain';
 
 /** `Animated.spring`'s physics fields — the same shape as a design system's own spring-config
@@ -137,7 +137,7 @@ const styles = StyleSheet.create({
     backgroundColor: CATALOG_COLOR.accent,
   },
   footer: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md },
-  label: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  label: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
   labelSpacer: { flex: 1 },
   replayButton: {
     paddingHorizontal: CATALOG_SPACE.md,
@@ -148,5 +148,5 @@ const styles = StyleSheet.create({
     backgroundColor: CATALOG_COLOR.surface,
   },
   replayButtonPressed: { backgroundColor: CATALOG_COLOR.surfacePressed },
-  replayText: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.text },
+  replayText: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
 });

package/native/catalog/PhoneFrame.tsx

@@ -1,6 +1,6 @@
 import React, { useState, useRef } from 'react';
 import { Platform, StyleSheet, Text, View, type LayoutChangeEvent } from 'react-native';
-import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TEXT } from './tokens';
 import { DEVICE_FRAME, DEVICE_SCALE_WARN_BELOW, deviceFrameScale } from './deviceFrame';
 import { resolveOverlayViewport } from './overlayViewport';
 import { useSpecimenAddress } from './SpecimenAddress';
@@ -149,5 +149,5 @@ const styles = StyleSheet.create({
     justifyContent: 'center',
     overflow: 'hidden',
   },
-  status: { position: 'absolute', fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  status: { position: 'absolute', ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/PropsTable.tsx

@@ -1,5 +1,5 @@
 import { View, Text, StyleSheet } from 'react-native';
-import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
+import { CATALOG_TEXT, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 import { PROPS_COLUMN_GAP } from './comparison';
 import type { PropDef } from './types';
 
@@ -86,14 +86,14 @@ const styles = StyleSheet.create({
   rowFirst: { paddingTop: 0 },
   rowLast: { borderBottomWidth: 0, paddingBottom: 0 },
   header: { width: 140, gap: 2 },
-  name: { fontSize: CATALOG_TYPE.sm, fontFamily: CATALOG_COLOR.code, fontWeight: '700', color: CATALOG_COLOR.text },
-  optionalMark: { fontWeight: '400', color: CATALOG_COLOR.textMuted },
-  type: { fontSize: CATALOG_TYPE.xs, fontFamily: CATALOG_COLOR.code, color: CATALOG_COLOR.accent },
+  name: { ...CATALOG_TEXT.codeSmallStrong, color: CATALOG_COLOR.text },
+  optionalMark: { ...CATALOG_TEXT.codeSmall, color: CATALOG_COLOR.textMuted },
+  type: { ...CATALOG_TEXT.codeMicro, color: CATALOG_COLOR.accent },
   // The second column — description + default — sized by the row's remaining width.
   body: { flex: 1, gap: 2 },
-  desc: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, lineHeight: 17 },
-  default: { fontSize: CATALOG_TYPE.xs, color: CATALOG_COLOR.textMuted },
-  defaultVal: { fontFamily: CATALOG_COLOR.code, color: CATALOG_COLOR.textMuted },
+  desc: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
+  default: { ...CATALOG_TEXT.micro, color: CATALOG_COLOR.textMuted },
+  defaultVal: { ...CATALOG_TEXT.codeMicro, color: CATALOG_COLOR.textMuted },
   gridRow: { flexDirection: 'row', gap: PROPS_COLUMN_GAP },
   cell: { flex: 1, minWidth: 0, paddingVertical: CATALOG_SPACE.md, gap: 4 },
   cellDivider: { borderBottomWidth: 1, borderBottomColor: CATALOG_COLOR.border },

package/native/catalog/ReferenceDetails.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from 'react';
 import { View, Text, StyleSheet, type LayoutChangeEvent, type TextStyle } 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';
 import { PropsTable } from './PropsTable';
 import { propsColumns, referenceColumns } from './comparison';
 import type { ComposedOfEntry, SectionDef } from './types';
@@ -8,9 +8,12 @@ import type { ComposedOfEntry, SectionDef } from './types';
 // react-native-web reads `aria-level`; React Native's prop types do not declare it.
 const HEADING_LEVEL_2 = { 'aria-level': 2 } as Record<string, unknown>;
 
-function Fact({ label, value, mono = false }: { label: string; value: string; mono?: boolean }) {
+/** `last` drops the trailing divider and its padding, the same convention `TokenRow`'s `last` and
+ *  `PropsTable`'s `rowLast` already use. Without it the final fact's bottom padding stacks on the
+ *  card's own `panelPadding`, so a card's contents sat ~10px lower than centred. */
+function Fact({ label, value, mono = false, last = false }: { label: string; value: string; mono?: boolean; last?: boolean }) {
   return (
-    <View style={styles.fact}>
+    <View style={[styles.fact, last && styles.factLast]}>
       <Text style={styles.factLabel}>{label}</Text>
       <Text style={[styles.factValue, mono && styles.mono]}>{value}</Text>
     </View>
@@ -47,11 +50,16 @@ function compositionLabel(entry: ComposedOfEntry): string {
   return entry.relationship === 'built-in' ? entry.component : `${entry.component} · ${entry.relationship}`;
 }
 
-function CompositionFacts({ composedOf }: { composedOf: ComposedOfEntry[] }) {
+function CompositionFacts({ composedOf, lastIsFlush = false }: { composedOf: ComposedOfEntry[]; lastIsFlush?: boolean }) {
   return (
     <>
       {composedOf.map((entry, i) => (
-        <Fact key={`${entry.component}-${entry.relationship}-${i}`} label={compositionLabel(entry)} value={entry.role} />
+        <Fact
+          key={`${entry.component}-${entry.relationship}-${i}`}
+          label={compositionLabel(entry)}
+          value={entry.role}
+          last={lastIsFlush && i === composedOf.length - 1}
+        />
       ))}
     </>
   );
@@ -91,11 +99,11 @@ export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<
     return (
       <View style={styles.card}>
         <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
-        {def.path && <Fact label="Source" value={def.path} mono />}
+        {def.path && <Fact label="Source" value={def.path} mono last={!(def.composedOf && def.composedOf.length > 0)} />}
         {def.composedOf && def.composedOf.length > 0 && (
           <>
             <Text style={styles.subheading}>Composition</Text>
-            <CompositionFacts composedOf={def.composedOf} />
+            <CompositionFacts composedOf={def.composedOf} lastIsFlush />
           </>
         )}
       </View>
@@ -117,19 +125,25 @@ export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<
           </View>
           <View style={columnStyle}>
             <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
-            {def.path && <Fact label="Source" value={def.path} mono />}
-            {!hide.accessibility && <Fact label="Accessibility" value={def.a11y ?? 'No accessibility notes documented.'} />}
+            {def.path && <Fact label="Source" value={def.path} mono last={hide.accessibility && !(!compositionIsOwnColumn && hasComposition)} />}
+            {!hide.accessibility && (
+              <Fact
+                label="Accessibility"
+                value={def.a11y ?? 'No accessibility notes documented.'}
+                last={!(!compositionIsOwnColumn && hasComposition)}
+              />
+            )}
             {!compositionIsOwnColumn && hasComposition && def.composedOf && (
               <>
                 <Text style={styles.subheading}>Composition</Text>
-                <CompositionFacts composedOf={def.composedOf} />
+                <CompositionFacts composedOf={def.composedOf} lastIsFlush />
               </>
             )}
           </View>
           {compositionIsOwnColumn && def.composedOf && (
             <View style={columnStyle}>
               <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Composition</Text>
-              <CompositionFacts composedOf={def.composedOf} />
+              <CompositionFacts composedOf={def.composedOf} lastIsFlush />
             </View>
           )}
         </View>
@@ -153,17 +167,13 @@ const styles = StyleSheet.create({
   column: { flex: 1, minWidth: 0 },
   columnStacked: { minWidth: 0 },
   heading: {
-    fontSize: CATALOG_TYPE.panelHeading,
-    fontWeight: '700',
-    letterSpacing: 0.52,
-    textTransform: 'uppercase',
+    ...CATALOG_TEXT.label,
     color: CATALOG_COLOR.text,
     marginBottom: 10,
   },
-  body: { fontSize: CATALOG_TYPE.md, lineHeight: 20, color: CATALOG_COLOR.textMuted },
+  body: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted },
   subheading: {
-    fontSize: CATALOG_TYPE.sm,
-    fontWeight: '700',
+    ...CATALOG_TEXT.captionStrong,
     color: CATALOG_COLOR.text,
     marginTop: CATALOG_SPACE.md,
     marginBottom: CATALOG_SPACE.xs,
@@ -175,14 +185,15 @@ const styles = StyleSheet.create({
     borderBottomWidth: 1,
     borderBottomColor: CATALOG_COLOR.borderSubtle,
   },
-  factLabel: { flexShrink: 1, minWidth: 0, fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
-  factValue: { minWidth: 0, fontSize: CATALOG_TYPE.md, lineHeight: 20, textAlign: 'left', color: CATALOG_COLOR.textMuted },
+  factLast: { paddingBottom: 0, borderBottomWidth: 0 },
+  factLabel: { flexShrink: 1, minWidth: 0, ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.text },
+  factValue: { minWidth: 0, ...CATALOG_TEXT.body, textAlign: 'left', color: CATALOG_COLOR.textMuted },
   // `wordBreak` isn't in the installed `TextStyle` type (RN's own, not RNW's — RNW's own
   // `Text/types.js` declares it; a browser applies any valid CSS property name it recognizes
   // regardless), so a bare literal here would report an unknown property under `--noEmit` even
   // though it genuinely works: a long unbroken token (a source path with no spaces, e.g.
   // `AnimatedChevron.tsx`) has no space for the browser's default line-breaking to use, so without
   // this it stays one unbroken run and overflows a narrow card instead of wrapping at its '/'s.
-  mono: { fontFamily: CATALOG_COLOR.code, wordBreak: 'break-word' } as TextStyle,
-  empty: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', color: CATALOG_COLOR.textMuted },
+  mono: { ...CATALOG_TEXT.code, wordBreak: 'break-word' } as TextStyle,
+  empty: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/SectionBlock.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useMemo, useState } from 'react';
 import { View, Text, Pressable, StyleSheet, type LayoutChangeEvent } 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';
 import { ComparisonGrid } from './ComparisonGrid';
 import { ComparisonGroups } from './ComparisonGroups';
 import { ComparisonList } from './ComparisonList';
@@ -334,7 +334,7 @@ export function SectionBlock<TId extends string>({
 }
 
 const styles = StyleSheet.create({
-  breadcrumb: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  breadcrumb: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
   titlebar: {
     flexDirection: 'row',
     alignItems: 'flex-start',
@@ -355,9 +355,9 @@ const styles = StyleSheet.create({
     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 },
+  osBadgeText: { ...CATALOG_TEXT.microLabel, color: CATALOG_COLOR.text },
+  title: { ...CATALOG_TEXT.pageTitle, color: CATALOG_COLOR.text, marginBottom: 5 },
+  desc: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted, maxWidth: 700 },
   pager: { flexDirection: 'row', gap: 6, flexShrink: 0 },
   pagerButton: {
     width: CATALOG_LAYOUT.controlSize,
@@ -372,7 +372,7 @@ const styles = StyleSheet.create({
   pagerButtonActive: { backgroundColor: CATALOG_COLOR.surfacePressed },
   pagerButtonDisabled: { backgroundColor: CATALOG_COLOR.pageBackground },
   focusRing: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing },
-  pagerGlyph: { fontSize: CATALOG_TYPE.lg, color: CATALOG_COLOR.text },
+  pagerGlyph: { ...CATALOG_TEXT.icon, color: CATALOG_COLOR.text },
   pagerGlyphDisabled: { color: CATALOG_COLOR.textMuted },
   blocks: { gap: CATALOG_LAYOUT.blockGap, marginBottom: CATALOG_LAYOUT.blockGap },
   blocksSide: { flexDirection: 'row', alignItems: 'flex-start' },
@@ -381,17 +381,11 @@ const styles = StyleSheet.create({
   frames: { flexDirection: 'row', flexWrap: 'wrap', gap: CATALOG_SPACE.xl, alignItems: 'flex-start', justifyContent: 'center' },
   frame: { maxWidth: '100%', gap: CATALOG_SPACE.sm },
   frameLabel: {
-    fontSize: CATALOG_TYPE.tableHeader,
-    fontWeight: '800',
-    letterSpacing: 0.44,
-    textTransform: 'uppercase',
+    ...CATALOG_TEXT.label,
     color: CATALOG_COLOR.textMuted,
   },
   blockLabel: {
-    fontSize: CATALOG_TYPE.sm,
-    fontWeight: '700',
-    letterSpacing: 0.72,
-    textTransform: 'uppercase',
+    ...CATALOG_TEXT.label,
     color: CATALOG_COLOR.text,
     marginBottom: CATALOG_LAYOUT.blockLabelGap,
   },
@@ -423,10 +417,10 @@ const styles = StyleSheet.create({
     borderBottomWidth: 1,
     borderBottomColor: CATALOG_COLOR.border,
   },
-  tableCaptionText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
+  tableCaptionText: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
   // Same cell padding `ComparisonList` uses: the requested width instead reaches the live demo
   // untouched through `tableBodyViewport`, the inner width-qualified group nested inside this body.
   tableBody: { padding: MATRIX_LAYOUT.cellPadding, flexGrow: 1, alignItems: 'center', justifyContent: 'flex-start' },
   tableBodyViewport: { maxWidth: '100%' },
-  emptyText: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', color: CATALOG_COLOR.textMuted },
+  emptyText: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/SpacingScaleGallery.tsx

@@ -1,6 +1,6 @@
 import { View, Text, StyleSheet } from 'react-native';
 import { TokenRow, TokenRowGroup } from './TokenRow';
-import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS } from './tokens';
+import { CATALOG_TEXT, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS } from './tokens';
 
 /**
  * Renders a spacing scale as a stack of `TokenRow`s, each showing a step's name, a bar sized to its
@@ -39,7 +39,7 @@ const styles = StyleSheet.create({
   // Wider gap than a plain gap-only stack — one row's use-note shouldn't crowd the next row's label.
   tokenStack: { gap: CATALOG_SPACE.lg },
   row: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md },
-  label: { width: 48, fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.text },
+  label: { width: 48, ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
   bar: { height: 12, borderRadius: CATALOG_RADIUS.sm, backgroundColor: CATALOG_COLOR.accent },
-  value: { fontSize: CATALOG_TYPE.xs, color: CATALOG_COLOR.textMuted },
+  value: { ...CATALOG_TEXT.micro, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/Swatch.tsx

@@ -1,5 +1,5 @@
 import { View, Text, StyleSheet } from 'react-native';
-import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS } from './tokens';
+import { CATALOG_TEXT, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS } from './tokens';
 
 /** One token swatch: its rendered value (a colour chip) plus name/value as data — the shared shape
  *  behind every Colors gallery (this framework's own, and any host app's, e.g. the Native App DS
@@ -35,6 +35,6 @@ const styles = StyleSheet.create({
     borderWidth: StyleSheet.hairlineWidth,
     borderColor: CATALOG_COLOR.border,
   },
-  name: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.text },
-  value: { fontSize: CATALOG_TYPE.xs, color: CATALOG_COLOR.textMuted },
+  name: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
+  value: { ...CATALOG_TEXT.micro, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/TokenLayouts.tsx

@@ -1,6 +1,6 @@
 import React, { useRef, 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 { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TEXT } from './tokens';
 import { sectionColumns, tileGeometry, TOKEN_LAYOUT_GAP, TOKEN_SECTION_MIN_WIDTH } from './tokenLayout';
 import type { TokenSection } from './types';
 
@@ -78,13 +78,10 @@ export function TokenTile({ name, value, note, children }: { name: string; value
 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',
+    ...CATALOG_TEXT.label,
     color: CATALOG_COLOR.text,
   },
-  sectionDesc: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: CATALOG_SPACE.xs },
+  sectionDesc: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted, marginTop: CATALOG_SPACE.xs },
   card: {
     marginTop: CATALOG_LAYOUT.blockLabelGap,
     backgroundColor: CATALOG_COLOR.surface,
@@ -97,7 +94,7 @@ const styles = StyleSheet.create({
   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 },
+  tileName: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
+  tileValue: { ...CATALOG_TEXT.micro, color: CATALOG_COLOR.textMuted },
+  tileNote: { ...CATALOG_TEXT.micro, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/TokenRow.tsx

@@ -1,6 +1,6 @@
 import React, { createContext, useCallback, useContext, useMemo, useState } from 'react';
 import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
-import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
+import { CATALOG_TEXT, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 
 type Lane = { width: number; report: (width: number) => void };
 
@@ -104,5 +104,5 @@ const styles = StyleSheet.create({
     borderBottomWidth: 1,
     borderBottomColor: CATALOG_COLOR.border,
   },
-  use: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  use: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/TypeScaleGallery.tsx

@@ -1,6 +1,6 @@
 import { View, Text, StyleSheet, type TextStyle } from 'react-native';
 import { TokenRow, TokenRowGroup } from './TokenRow';
-import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
+import { CATALOG_TEXT, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 
 /**
  * Renders a type scale as a stack of `TokenRow`s, each showing a step's name (rendered at its own
@@ -44,5 +44,5 @@ const styles = StyleSheet.create({
   // two read as one unit at a glance.
   row: { flexDirection: 'row', alignItems: 'baseline', gap: CATALOG_SPACE.sm },
   sample: { color: CATALOG_COLOR.text },
-  meta: { fontSize: CATALOG_TYPE.xs, color: CATALOG_COLOR.textMuted },
+  meta: { ...CATALOG_TEXT.micro, color: CATALOG_COLOR.textMuted },
 });

package/native/catalog/UpdatePanel.tsx

@@ -1,6 +1,6 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { ActivityIndicator, Platform, Pressable, ScrollView, StyleSheet, Switch, Text, 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';
 import { CatalogButton } from './CatalogButton';
 import { DS_VIEWER_SECRET_HEADER } from './catalogNavigation';
 import {
@@ -1080,9 +1080,9 @@ const styles = StyleSheet.create({
   resultNote: { borderRadius: CATALOG_RADIUS.md, padding: 14, marginTop: 12, marginBottom: 18, gap: 4 },
   resultNoteOk: { backgroundColor: CATALOG_COLOR.successSubtle },
   resultNoteErr: { backgroundColor: CATALOG_COLOR.dangerSubtle, borderWidth: 1, borderColor: CATALOG_COLOR.dangerBorder },
-  resultTitle: { fontSize: CATALOG_TYPE.lg, fontWeight: '800' },
-  resultDescription: { fontSize: CATALOG_TYPE.panelHeading, lineHeight: 19 },
-  resultDetail: { fontSize: CATALOG_TYPE.sm, lineHeight: 18 },
+  resultTitle: { ...CATALOG_TEXT.heading3 },
+  resultDescription: { ...CATALOG_TEXT.caption },
+  resultDetail: { ...CATALOG_TEXT.caption },
   resultRow: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md, marginTop: 8 },
   // The catalog's smallest control size (the major banner's close button), filled in the note's colour.
   resultButton: { height: 32, paddingHorizontal: 14, borderRadius: 16, alignItems: 'center', justifyContent: 'center' },
@@ -1091,15 +1091,14 @@ const styles = StyleSheet.create({
   // uses, so "unavailable" doesn't read as merely "pressed" (the note's own full-colour fill at
   // reduced opacity).
   resultButtonDisabled: { backgroundColor: CATALOG_COLOR.controlDisabled },
-  resultButtonText: { color: '#ffffff', fontSize: CATALOG_TYPE.sm, fontWeight: '700' },
+  resultButtonText: { ...CATALOG_TEXT.captionStrong, color: '#ffffff' },
   resultButtonTextDisabled: { color: CATALOG_COLOR.controlDisabledText },
-  resultLink: { fontSize: CATALOG_TYPE.panelHeading, fontWeight: '700', textDecorationLine: 'underline' },
-  crumb: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  resultLink: { ...CATALOG_TEXT.captionStrong, textDecorationLine: 'underline' },
+  crumb: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
   headingTarget: { marginTop: 4, marginBottom: 6 },
-  title: { fontSize: CATALOG_TYPE.pageTitle, fontWeight: '800', color: CATALOG_COLOR.text },
+  title: { ...CATALOG_TEXT.pageTitle, color: CATALOG_COLOR.text },
   code: {
-    fontFamily: 'Menlo, monospace',
-    fontSize: CATALOG_TYPE.sm,
+    ...CATALOG_TEXT.codeSmall,
     backgroundColor: CATALOG_COLOR.surfaceMuted,
     borderWidth: 1,
     borderColor: CATALOG_COLOR.border,
@@ -1108,39 +1107,39 @@ const styles = StyleSheet.create({
     paddingVertical: 2,
   },
   versionsRow: { flexDirection: 'row', alignItems: 'center', gap: 10 },
-  versionsText: { fontSize: CATALOG_TYPE['2xl'], fontWeight: '800', color: CATALOG_COLOR.text },
-  arrow: { fontSize: CATALOG_TYPE['2xl'], color: CATALOG_COLOR.textMuted },
+  versionsText: { ...CATALOG_TEXT.heading1, color: CATALOG_COLOR.text },
+  arrow: { ...CATALOG_TEXT.heading1, color: CATALOG_COLOR.textMuted },
   pill: { paddingHorizontal: 8, paddingVertical: 2, borderRadius: 10, backgroundColor: CATALOG_COLOR.accentSubtle },
   pillMajor: { backgroundColor: CATALOG_COLOR.warningSubtle },
   pillSuccess: { backgroundColor: CATALOG_COLOR.successSubtle },
-  pillText: { fontSize: CATALOG_TYPE.sm, fontWeight: '700', color: CATALOG_COLOR.accent },
+  pillText: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.accent },
   pillTextMajor: { color: CATALOG_COLOR.warning },
   pillTextSuccess: { color: CATALOG_COLOR.success },
   pillOff: { backgroundColor: CATALOG_COLOR.chip },
   pillTextOff: { color: CATALOG_COLOR.textMuted },
   facts: { marginTop: 18, borderTopWidth: 1, borderTopColor: CATALOG_COLOR.border },
   factRow: { flexDirection: 'row', alignItems: 'center', justifyContent: 'space-between', gap: CATALOG_SPACE.md, paddingVertical: 10, borderBottomWidth: 1, borderBottomColor: CATALOG_COLOR.border },
-  factLabel: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted },
-  factValue: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text },
+  factLabel: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted },
+  factValue: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.text },
   switchText: { flex: 1, gap: 2 },
-  switchLabel: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
+  switchLabel: { ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.text },
   switch: { width: 44, height: 26 },
-  switchHelp: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
-  muted: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 4 },
+  switchHelp: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
+  muted: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted, marginTop: 4 },
   block: { marginTop: 18 },
-  h3: { fontSize: CATALOG_TYPE.panelHeading, textTransform: 'uppercase', letterSpacing: 0.5, color: CATALOG_COLOR.text, marginBottom: 8 },
-  bullet: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text, marginVertical: 2 },
+  h3: { ...CATALOG_TEXT.label, color: CATALOG_COLOR.text, marginBottom: 8 },
+  bullet: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.text, marginVertical: 2 },
   filesBox: { borderWidth: 1, borderColor: CATALOG_COLOR.border, borderRadius: CATALOG_RADIUS.md },
   fileRow: { flexDirection: 'row', justifyContent: 'space-between', paddingVertical: 8, paddingHorizontal: 12 },
   fileRowBorder: { borderTopWidth: 1, borderTopColor: CATALOG_COLOR.border },
-  filePath: { fontFamily: 'Menlo, monospace', fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.text },
-  fileReason: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
-  fileReasonDirty: { color: CATALOG_COLOR.warning, fontWeight: '700' },
+  filePath: { ...CATALOG_TEXT.codeSmall, color: CATALOG_COLOR.text },
+  fileReason: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
+  fileReasonDirty: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.warning },
   actions: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md, marginTop: 20 },
   noteBox: { borderRadius: CATALOG_RADIUS.md, padding: 12, marginTop: 18 },
   noteBoxRow: { flexDirection: 'row', alignItems: 'flex-start', gap: 9 },
-  noteBoxText: { fontSize: CATALOG_TYPE.md, flexShrink: 1 },
-  noteBoxBold: { fontWeight: '700' },
+  noteBoxText: { ...CATALOG_TEXT.body, flexShrink: 1 },
+  noteBoxBold: { ...CATALOG_TEXT.bodyStrong },
   steps: { marginTop: 12 },
   stepRow: { flexDirection: 'row', alignItems: 'center', gap: 10, paddingVertical: 6 },
   stepIcon: { width: 20, height: 20, borderRadius: 10, alignItems: 'center', justifyContent: 'center' },
@@ -1151,10 +1150,10 @@ const styles = StyleSheet.create({
   stepIconNow: { borderWidth: 2, borderColor: CATALOG_COLOR.accent },
   stepIconTodo: { borderWidth: 2, borderColor: CATALOG_COLOR.borderStrong },
   stepIconFail: { backgroundColor: CATALOG_COLOR.dangerSubtle },
-  stepIconGlyph: { fontSize: CATALOG_TYPE.sm, fontWeight: '800', color: CATALOG_COLOR.text },
-  stepLabel: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.textMuted },
-  stepLabelNow: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text, fontWeight: '700' },
-  stepLabelFail: { fontSize: CATALOG_TYPE.md, color: CATALOG_COLOR.text, fontWeight: '700' },
+  stepIconGlyph: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
+  stepLabel: { ...CATALOG_TEXT.body, color: CATALOG_COLOR.textMuted },
+  stepLabelNow: { ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.text },
+  stepLabelFail: { ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.text },
   logBox: { backgroundColor: '#1d1d1f', borderRadius: CATALOG_RADIUS.md, padding: 12, marginTop: 8, maxHeight: 240 },
-  logText: { color: '#e8e8e8', fontSize: CATALOG_TYPE.sm, fontFamily: 'Menlo, monospace' },
+  logText: { ...CATALOG_TEXT.codeSmall, color: '#e8e8e8' },
 });

package/native/catalog/VariantGroup.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { View, Text, StyleSheet } from 'react-native';
-import { CATALOG_TYPE, CATALOG_COLOR } from './tokens';
+import { CATALOG_TEXT, CATALOG_COLOR } from './tokens';
 
 /** Labels one example (or small group of examples) inside a section's Examples card — a bold
  *  uppercase name plus a one-line description stacked below it, sitting above whatever demo content
@@ -39,10 +39,7 @@ const styles = StyleSheet.create({
   group: { gap: 6 },
   groupCenter: { alignItems: 'center' },
   groupLeft: { alignItems: 'flex-start' },
-  name: {
-    fontSize: CATALOG_TYPE.xs, fontWeight: '700', color: CATALOG_COLOR.text,
-    textTransform: 'uppercase', letterSpacing: 0.4,
-  },
-  desc: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted },
+  name: { ...CATALOG_TEXT.microLabel, color: CATALOG_COLOR.text },
+  desc: { ...CATALOG_TEXT.caption, color: CATALOG_COLOR.textMuted },
   textCenter: { textAlign: 'center' },
 });

package/native/catalog/index.ts

@@ -55,6 +55,9 @@ export type { ListGroup, ListItem } from './comparison';
 export {
   CATALOG_TYPE,
   CATALOG_TYPE_USE,
+  CATALOG_FONT,
+  CATALOG_TEXT,
+  CATALOG_TEXT_USE,
   CATALOG_SPACE,
   CATALOG_SPACE_USE,
   CATALOG_RADIUS,

package/native/catalog/tokens.ts

@@ -28,6 +28,32 @@ export const CATALOG_TYPE = {
   '4xl': 40,
 } as const;
 
+export const CATALOG_FONT = { code: 'Menlo, monospace' } as const;
+
+/** 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 },
+} as const;
+
 export const CATALOG_SPACE = {
   xs: 4,
   sm: 8,
@@ -75,22 +101,44 @@ export const CATALOG_LAYOUT = {
 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: Record<keyof typeof CATALOG_TYPE, string> = {
-  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: Record<keyof typeof CATALOG_TEXT, string> = {
+  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: Record<keyof typeof CATALOG_SPACE, string> = {
@@ -135,7 +183,10 @@ export const CATALOG_COLOR = {
   accentSubtle: '#e9efff',
   /** 3px keyboard focus ring on every catalog control. */
   focusRing: '#c9d7ff',
-  code: 'Menlo',
+  /** @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/package.json

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