@krapwoo/ds-viewer 0.4.7 → 0.4.9

package/native/catalog/updatePanelState.ts

@@ -32,7 +32,7 @@ export type UpdateStatusView =
   | { phase: 'updating'; steps: { label: string; state: 'done' | 'now' | 'todo' }[] }
   | { phase: 'restarting' }
   | { phase: 'success'; doctorSummary: string; files: string[]; latest: string }
-  | { phase: 'failure'; log: string; failedStep: string };
+  | { phase: 'failure'; log: string; failedStep: string; step?: 'install' | 'migrate' | 'doctor' | 'other' };
 
 export type UpdatePhase = 'checking' | 'ready' | 'dirty' | 'offline' | 'updating' | 'restarting' | 'success' | 'failure';
 
@@ -144,3 +144,70 @@ export function bumpLabel(current: string, latest: string, breaking: boolean): '
   if (!a || !b) return 'Minor';
   return a[0] === b[0] && a[1] === b[1] ? 'Patch' : 'Minor';
 }
+
+export interface ResultNote {
+  tone: 'ok' | 'err';
+  title: string;
+  description: string;
+  detail: string;
+  /** The terminal fallback, shown as code inside `detail` (failures only). */
+  command?: string;
+  /** At most two words. `dismiss` clears the note; `retry` runs the whole update again; `resume`
+   *  continues from the failed migrate or doctor step. */
+  action: { label: string; kind: 'dismiss' | 'retry' | 'resume' };
+  hasLog: boolean;
+}
+
+/** The note shown at the top of the update page after an update finished (approved mockup
+ *  2026-10-11): a header, a description, one detail line, and a bottom-left button. */
+export function resultNote(
+  status: Extract<UpdateStatusView, { phase: 'success' | 'failure' }>,
+  current: string,
+  latest?: string,
+): ResultNote {
+  if (status.phase === 'success') {
+    return {
+      tone: 'ok',
+      title: `Updated to ${status.latest}`,
+      description: "The changes aren't committed yet, so review them in your editor.",
+      // Doctor's own summary line continues after an em dash with component counts; the note keeps
+      // only the error and warning counts.
+      detail: `Changed: ${status.files.join(', ') || 'nothing'} · Doctor: ${status.doctorSummary.split(' — ')[0]}`,
+      action: { label: 'Got it', kind: 'dismiss' },
+      hasLog: false,
+    };
+  }
+  const failure = (title: string, description: string, command: string, action: ResultNote['action']): ResultNote => ({
+    tone: 'err', title, description, detail: `You can also run ${command} in your terminal.`, command, action, hasLog: true,
+  });
+  switch (status.step) {
+    case 'migrate':
+      return failure(
+        'The update installed, but migrating failed',
+        `Your package is on ${latest ?? 'the new version'}, but your files still match ${current}.`,
+        `npx ds-viewer migrate --from ${current}`,
+        { label: 'Finish migration', kind: 'resume' },
+      );
+    case 'doctor':
+      return failure(
+        'The update installed, but doctor failed to run',
+        'The update itself is done. Only the page check is missing.',
+        'npx ds-viewer doctor',
+        { label: 'Rerun doctor', kind: 'resume' },
+      );
+    case 'install':
+      return failure(
+        'The update stopped while installing',
+        'Nothing was migrated. Retrying starts again from the download.',
+        'npx ds-viewer update',
+        { label: 'Retry update', kind: 'retry' },
+      );
+    default:
+      return failure(
+        'The update stopped',
+        'Something unexpected went wrong. Retrying starts again from the download.',
+        'npx ds-viewer update',
+        { label: 'Retry update', kind: 'retry' },
+      );
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",
@@ -65,9 +65,10 @@
     "test": "node --experimental-strip-types --test 'cli/**/*.test.ts' 'config/**/*.test.ts' 'native/catalog/__tests__/*.test.ts'",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "kit:dev": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",
-    "check:catalog": "npm run build && node scripts/checkCatalogConsole.mjs kit-host",
-    "check:doctor": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci",
-    "check:types": "tsc --noEmit -p kit-host",
+    "viewer:dev": "npm run build && cd viewer-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",
+    "check:catalog": "npm run build && node scripts/checkCatalogConsole.mjs kit-host && node scripts/checkCatalogConsole.mjs viewer-host",
+    "check:doctor": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci && cd ../viewer-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci",
+    "check:types": "tsc --noEmit -p kit-host && tsc --noEmit -p viewer-host",
     "release": "node scripts/release.mjs"
   }
 }

package/starter-kit/components/AnimatedChevron/AnimatedChevron.catalog.tsx

@@ -5,7 +5,7 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'AnimatedChevron',
-  group: 'Sub-Parts',
+  group: 'Components',
   description: 'A chevron that morphs between down (collapsed) and up (expanded) — flipping vertically in place instead of rotating through a sideways-pointing angle, and instead of swapping icons. The morph Banner\'s own collapsible header uses for its disclosure indicator. Not commonly used on its own; exported for building a custom disclosure/accordion toggle.',
   a11y: 'Purely decorative — no accessibility role of its own. Wrap it in an accessible parent (the way Banner\'s own header Pressable does) if the toggle needs to be announced.',
   variants: {

package/starter-kit/components/Avatar/Avatar.catalog.tsx

@@ -31,7 +31,7 @@ const AVATAR_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Avatar',
-  group: 'Surfaces',
+  group: 'Components',
   specimenSize: 'compact',
   comparison: AVATAR_COMPARISON,
   description: 'A circular image, or an initials fallback on a solid fill when there\'s no image (or it fails to load).',

package/starter-kit/components/Badge/Badge.catalog.tsx

@@ -51,7 +51,7 @@ const BADGE_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Badge',
-  group: 'Surfaces',
+  group: 'Components',
   specimenSize: 'compact',
   comparison: BADGE_COMPARISON,
   description: 'A small status chip — five semantic variants, with optional leading/trailing icons or icon-only.',

package/starter-kit/components/Banner/Banner.catalog.tsx

@@ -4,7 +4,8 @@ import { Banner } from './Banner';
 
 export default defineCatalogPage({
   component: 'Banner',
-  group: 'Surfaces',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'AnimatedChevron', role: "The expand/collapse chevron in the header of a collapsible banner.", relationship: 'built-in' },
   ],

package/starter-kit/components/BottomSheet/BottomSheet.catalog.tsx

@@ -69,7 +69,11 @@ function BottomSheetDemo() {
 
 export default defineCatalogPage({
   component: 'BottomSheet',
-  group: 'Navigation',
+  group: 'Components',
+  composedOf: [
+    { component: 'TopNav', role: "The header slot, typically a TopNav with a close or back action.", relationship: 'slot' },
+    { component: 'Dock', role: "The footer slot, typically a Dock with the sheet's primary actions; a Dock footer gets its shadow once the content scrolls.", relationship: 'slot' },
+  ],
   description: 'A sheet that slides up over a dismissible backdrop. Height is driven by its content (not fixed snap points) up to 90% of the available height, then the content area scrolls. Compose header with TopNav and footer with Dock.',
   whenToUse: 'For longer, browsable content, or anything that benefits from a TopNav/Dock header-footer structure. For a short, focused decision that interrupts the flow, use Dialog.',
   a11y: 'The backdrop is a Pressable with accessibilityRole="button" and accessibilityLabel="Dismiss"; header/content/footer carry their own accessibility (e.g. TopNav\'s title as accessibilityRole="header").',

package/starter-kit/components/Button/Button.catalog.tsx

@@ -55,7 +55,7 @@ const BUTTON_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Button',
-  group: 'Actions',
+  group: 'Components',
   composedOf: [
     { component: 'Loading', role: "The spinner that replaces the label and icon while loading is true.", relationship: 'built-in' },
   ],

package/starter-kit/components/ButtonGroup/ButtonGroup.catalog.tsx

@@ -5,7 +5,11 @@ import { Button } from '../Button';
 
 export default defineCatalogPage({
   component: 'ButtonGroup',
-  group: 'Actions',
+  group: 'Components',
+  composedOf: [
+    { component: 'Button', role: "Its children: up to two Buttons side by side, or three stacked.", relationship: 'slot' },
+  ],
+  specimenSize: 'regular',
   description: 'Groups Button elements in one of two layouts: horizontal (up to two, auto-width, trailing-aligned) or vertical (up to three, stretched full width — the same layout Dock\'s own button area uses). Every button in a group should read as one family — the same variant tier (primary/secondary/tertiary/white, never ghost), the same size, and either all icon+label or all label-only, never a mix. Dev-console warns if two or more children disagree.',
   a11y: 'A plain View; each Button child carries its own accessibility role and label.',
   variants: {
@@ -15,6 +19,9 @@ export default defineCatalogPage({
         key: 'horizontal',
         name: 'Horizontal',
         props: { variant: 'horizontal' },
+        // Shown at its own width, centred: stretched, its trailing alignment pushes it to the
+        // cell's edge, which reads as a misplaced example rather than as trailing alignment.
+        fill: false,
         node: (
           <ButtonGroup variant="horizontal">
             <Button label="Cancel" variant="tertiary" onPress={() => {}} />

package/starter-kit/components/Card/Card.catalog.tsx

@@ -11,7 +11,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Card',
-  group: 'Surfaces',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'The primary content surface — a rounded white card with a soft resting shadow. Pass children, or onPress to make the whole card a button.',
   whenToUse: 'A standalone, self-contained unit with its own shadow. For a row in a homogeneous stack of peers (with dividers between them), use ListItem inside a List instead.',
   a11y: 'When onPress is set, renders a Pressable with accessibilityRole="button" and a visible focus ring; a plain card is a non-interactive View.',

package/starter-kit/components/Checkbox/Checkbox.catalog.tsx

@@ -9,8 +9,8 @@ function CheckboxDemo() {
 
 export default defineCatalogPage({
   component: 'Checkbox',
-  group: 'Controls',
-  specimenSize: 'compact',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A square selection control — the box fills with the accent colour and a checkmark when checked.',
   whenToUse: 'An independent on/off fact about this one item — any number can be checked at once. For a setting that takes effect immediately, use Switch; for one-of-many exclusive selection, use Radio.',
   a11y: 'Renders a Pressable with accessibilityRole="checkbox" and accessibilityState.checked; the optional label doubles as its accessibilityLabel.',

package/starter-kit/components/Dialog/Dialog.catalog.tsx

@@ -33,7 +33,7 @@ function DialogDemo() {
 
 export default defineCatalogPage({
   component: 'Dialog',
-  group: 'Overlays',
+  group: 'Components',
   description: 'A card centred on screen over a dismissible backdrop — fades and scales in, distinct from BottomSheet\'s bottom-anchored slide. Named Dialog (not Modal) to avoid shadowing React Native\'s own built-in Modal.',
   whenToUse: 'A short, focused decision that interrupts the flow (confirm/cancel, a single form). For anything longer, browsable, or that needs its own internal scrolling, use BottomSheet.',
   a11y: 'The backdrop is a Pressable with accessibilityRole="button" and accessibilityLabel="Dismiss"; content you pass as children carries its own accessibility.',

package/starter-kit/components/Divider/Divider.catalog.tsx

@@ -11,7 +11,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Divider',
-  group: 'Layout',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A 1px hairline separator at the divider token colour.',
   a11y: 'A plain, non-interactive View — purely decorative.',
   // No `variant` prop and no other real configuration exists on Divider — a single hairline is the

package/starter-kit/components/Dock/Dock.catalog.tsx

@@ -5,7 +5,10 @@ import { Dock } from './Dock';
 
 export default defineCatalogPage({
   component: 'Dock',
-  group: 'Navigation',
+  group: 'Components',
+  composedOf: [
+    { component: 'Button', role: "Its children: up to three full-width Buttons, stacked.", relationship: 'slot' },
+  ],
   description: 'Pinned to the bottom of the screen, above the home indicator — holds up to three full-width Buttons stacked vertically, with an optional small caption area above them.',
   a11y: 'A plain View; each Button child carries its own accessibility role and label.',
   // No `variant` prop exists on Dock — its "Variants" column just shows the one default look,

package/starter-kit/components/Dropdown/Dropdown.catalog.tsx

@@ -38,7 +38,7 @@ function DropdownDemo() {
 
 export default defineCatalogPage({
   component: 'Dropdown',
-  group: 'Inputs',
+  group: 'Components',
   composedOf: [
     { component: 'FieldContainer', role: "The field frame around the label, value and chevron (the trigger).", relationship: 'built-in' },
     { component: 'BottomSheet', role: "The sheet listing the options while the dropdown is open.", relationship: 'built-in' },

package/starter-kit/components/EmptyState/EmptyState.catalog.tsx

@@ -5,7 +5,8 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'EmptyState',
-  group: 'Layout',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'Avatar', role: "The icon circle above the title (iconName, default 'users').", relationship: 'built-in' },
     { component: 'ButtonGroup', role: "Stacks the action buttons when action is set.", relationship: 'built-in' },

package/starter-kit/components/FieldContainer/FieldContainer.catalog.tsx

@@ -12,7 +12,11 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'FieldContainer',
-  group: 'Sub-Parts',
+  group: 'Components',
+  composedOf: [
+    { component: 'Surface', role: "Reads the surrounding Surface tone: a recessed fill on white, opaque white inside a muted Surface.", relationship: 'related' },
+  ],
+  specimenSize: 'regular',
   description: 'The shared field chrome — white surface, medium radius, a 1px border that darkens on focus and mutes when disabled — behind InputField, TextArea, Dropdown, and SearchField, so all four share one visually-consistent field look instead of each re-implementing it.',
   a11y: 'Renders a plain View by default. Passing onPress (without disabled) makes it a Pressable with accessibilityRole="button" and the given accessibilityLabel — a consumer building a real editable field (InputField\'s editable mode) relies on its own inner TextInput for accessibility instead.',
   variants: {

package/starter-kit/components/InputClearButton/InputClearButton.catalog.tsx

@@ -4,7 +4,7 @@ import { InputClearButton } from './InputClearButton';
 
 export default defineCatalogPage({
   component: 'InputClearButton',
-  group: 'Sub-Parts',
+  group: 'Components',
   description: 'The clear (×) button InputField and SearchField both show once a field is active and holds a value — a filled circle-x icon sized to reach the 44pt touch target via hitSlop, not visual size.',
   a11y: 'A Pressable with accessibilityRole="button" and the given (or default "Clear field") accessibilityLabel; hitSlop of 10 on every side pads its 24×24 visual size out to the 44pt minimum.',
   variants: {

package/starter-kit/components/InputField/InputField.catalog.tsx

@@ -17,9 +17,11 @@ function InputFieldDemo() {
 
 export default defineCatalogPage({
   component: 'InputField',
-  group: 'Inputs',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'InputClearButton', role: "The clear (\u00d7) button, shown while the field has a value and is focused (or active, when not editable).", relationship: 'built-in' },
+    { component: 'Surface', role: 'Reads the surrounding Surface tone so the field stays visible on a muted Surface.', relationship: 'related' },
   ],
   description: 'A floating-label field. Resting: a centred, body-sized label with no border. Active (focused, or picker with active set) or filled: the label floats to a small top caption, row 2 shows the value/input, and a border fades in while active.',
   whenToUse: 'A named field with a fixed identity ("To", "Arrive by") across the interaction. For free-text search with no floating label, use SearchField; for one of a small known set of choices, use Dropdown.',

package/starter-kit/components/List/List.catalog.tsx

@@ -8,7 +8,8 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'List',
-  group: 'Layout',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'Divider', role: "The hairline between consecutive items (none after the last).", relationship: 'built-in' },
   ],

package/starter-kit/components/ListItem/ListItem.catalog.tsx

@@ -9,7 +9,13 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'ListItem',
-  group: 'Layout',
+  group: 'Components',
+  composedOf: [
+    { component: 'Avatar', role: "The leading slot, typically an Avatar (or an icon).", relationship: 'slot' },
+    { component: 'Switch', role: "A trailing-slot option, e.g. a settings toggle.", relationship: 'slot' },
+    { component: 'Button', role: "A trailing-slot option, e.g. an Accept action.", relationship: 'slot' },
+  ],
+  specimenSize: 'regular',
   description: 'A single row: optional leading/trailing slots flanking a title (+ optional subtitle/footer). Stack several inside a List for a settings screen, menu, or search-results list.',
   whenToUse: "A row in a set of visually-light peers sharing a List's own surface and dividers. For a standalone unit with its own shadow, use Card instead.",
   a11y: 'A tappable row (onPress set) renders as a Pressable with accessibilityRole="button" and an accessibilityLabel built from title + subtitle; a plain row is a non-interactive View.',

package/starter-kit/components/Loading/Loading.catalog.tsx

@@ -5,7 +5,8 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'Loading',
-  group: 'Feedback',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'An indeterminate loader — the shape fills up, empties out, then fills again, seamlessly. Two variants: circle (used internally by Button and Pill for their own loading states) and linear.',
   a11y: 'Exposed to assistive tech as accessibilityRole="progressbar" with accessibilityLabel="Loading" — no extra wiring needed at the call site.',
   // One example per `variant` enum value — `circle` is the default, so it comes first.

package/starter-kit/components/Pill/Pill.catalog.tsx

@@ -40,7 +40,7 @@ const PILL_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Pill',
-  group: 'Actions',
+  group: 'Components',
   composedOf: [
     { component: 'Loading', role: "The spinner shown instead of the label and icon while loading is true.", relationship: 'built-in' },
   ],

package/starter-kit/components/PillRow/PillRow.catalog.tsx

@@ -4,7 +4,7 @@ import { PillRow } from './PillRow';
 
 export default defineCatalogPage({
   component: 'PillRow',
-  group: 'Actions',
+  group: 'Components',
   composedOf: [
     { component: 'Pill', role: "Each item in pills, plus the trailing icon-only Edit pill when shown.", relationship: 'built-in' },
   ],

package/starter-kit/components/ProgressDots/ProgressDots.catalog.tsx

@@ -4,7 +4,7 @@ import { ProgressDots } from './ProgressDots';
 
 export default defineCatalogPage({
   component: 'ProgressDots',
-  group: 'Feedback',
+  group: 'Components',
   description: 'A row of dots for a stepped flow; the active dot widens into a pill.',
   a11y: 'Decorative progress indicator; convey the "step X of Y" position in text for screen readers.',
   // No `variant` prop exists on ProgressDots — its "Variants" column just shows the one default

package/starter-kit/components/Radio/Radio.catalog.tsx

@@ -20,8 +20,8 @@ function RadioGroupDemo() {
 
 export default defineCatalogPage({
   component: 'Radio',
-  group: 'Controls',
-  specimenSize: 'compact',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A single circular selection control — a filled dot appears in the ring when selected. A group of mutually-exclusive Radios is just multiple instances sharing one selected value in the consumer.',
   whenToUse: 'One selection from a mutually-exclusive set — checking one should un-check another. For an independent on/off fact, use Checkbox; for a setting that takes effect immediately, use Switch.',
   a11y: 'Renders a Pressable with accessibilityRole="radio" and accessibilityState.selected; the optional label doubles as its accessibilityLabel.',

package/starter-kit/components/SearchField/SearchField.catalog.tsx

@@ -9,7 +9,8 @@ function SearchFieldDemo() {
 
 export default defineCatalogPage({
   component: 'SearchField',
-  group: 'Inputs',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'FieldContainer', role: "The field frame around the search icon, input and clear button.", relationship: 'built-in' },
     { component: 'InputClearButton', role: "The clear (\u00d7) button, shown while focused with text.", relationship: 'built-in' },

package/starter-kit/components/SectionHeader/SectionHeader.catalog.tsx

@@ -4,7 +4,8 @@ import { SectionHeader } from './SectionHeader';
 
 export default defineCatalogPage({
   component: 'SectionHeader',
-  group: 'Layout',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'Button', role: "The trailing button, rendered when trailingButtonLabel is set.", relationship: 'built-in' },
   ],

package/starter-kit/components/SegmentedToggle/SegmentedToggle.catalog.tsx

@@ -21,9 +21,7 @@ function SegmentedToggleDemo() {
 
 export default defineCatalogPage({
   component: 'SegmentedToggle',
-  group: 'Selection',
-  // Phone width plus a small phone, where long labels truncate.
-  previewWidths: [402, 320],
+  group: 'Components',
   description: 'A row of mutually-exclusive options on a recessed track, with a white thumb that slides to the selected segment. Two or more options.',
   whenToUse: 'A filled, heavier-weight control for a primary, prominent choice on the screen. For quieter secondary navigation, use UnderlineTabs.',
   a11y: 'The row is accessibilityRole="tablist"; each segment is a "tab" with accessibilityState.selected reflecting the current value.',

package/starter-kit/components/Shimmer/Breathing.catalog.tsx

@@ -10,7 +10,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Breathing',
-  group: 'Feedback',
+  group: 'Components',
+  specimenSize: 'regular',
   description:
     "The shared animated primitive behind Shimmer — a solid block that breathes between a low and high colour on one shared, module-level clock, so every Breathing/Shimmer instance on screen stays phase-locked instead of drifting out of sync. Exported so a custom composite skeleton can reuse the same pulse directly instead of going through Shimmer's fixed text/circle/container shapes.",
   a11y: 'Renders a plain Animated.View with no role by default — pass accessibilityRole="progressbar" and accessibilityLabel yourself, the same way Shimmer does internally for its own standalone (non-grouped) blocks.',

package/starter-kit/components/Shimmer/Shimmer.catalog.tsx

@@ -11,7 +11,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Shimmer',
-  group: 'Feedback',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'Loading placeholders that breathe while content loads. `text` stands in for one line of text (an element with 3 lines gets 3 stacked `text` Shimmers, not one tall one), `circle` is always for a circular element, and `container` covers everything else (Card, Banner, image, …) — sized to match the real element it replaces, not an arbitrary block. When several stand in for one element, wrap them in `SkeletonGroup`.',
   whenToUse: 'A composite skeleton (several Shimmers standing in for one element) → wrap them in SkeletonGroup so it announces "Loading" once, not once per block. A single lone Shimmer needs no wrapper — it announces on its own.',
   a11y: 'A standalone Shimmer is exposed as accessibilityRole="progressbar" + accessibilityLabel="Loading". Inside a SkeletonGroup, each block goes silent and the group carries one busy "Loading" announcement for the whole skeleton — so a screen reader says "Loading" once, not once per block.',

package/starter-kit/components/Shimmer/SkeletonGroup.catalog.tsx

@@ -11,7 +11,11 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'SkeletonGroup',
-  group: 'Sub-Parts',
+  group: 'Components',
+  composedOf: [
+    { component: 'Shimmer', role: 'Its children: the stacked Shimmers that stand in for one element, announced once as a single Loading region.', relationship: 'slot' },
+  ],
+  specimenSize: 'regular',
   description: 'An accessibility wrapper for a composite skeleton — several Shimmers standing in for one real element (e.g. a list row: an avatar + a two-line label). It announces the whole thing as one "Loading" region and silences the individual blocks, so a screen reader says "Loading" once instead of once per Shimmer. Adds no layout of its own — pass your own flexDirection/gap via style.',
   whenToUse: 'Wrap 2+ Shimmers that together stand in for one element. A single lone Shimmer already announces on its own and needs no wrapper.',
   a11y: 'Carries accessibilityRole="progressbar" + accessibilityLabel (default "Loading") + accessibilityState={{ busy: true }} for the whole region; provides a context that makes every descendant Shimmer drop its own announcement. Net effect: one "Loading" announcement per skeleton, not one per block.',

package/starter-kit/components/Surface/Surface.catalog.tsx

@@ -11,7 +11,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Surface',
-  group: 'Surfaces',
+  group: 'Components',
+  specimenSize: 'regular',
   description:
     "Declares \"this subtree's background is tone\" — renders a plain View filled with the matching token (surface.white or surface.main) and provides that tone to descendants via context, so a tone-aware component inside (e.g. FieldContainer/InputField) can automatically pick a fill that contrasts with it instead of assuming white.",
   whenToUse:

package/starter-kit/components/Switch/Switch.catalog.tsx

@@ -14,8 +14,8 @@ function SwitchLabelDemo() {
 
 export default defineCatalogPage({
   component: 'Switch',
-  group: 'Controls',
-  specimenSize: 'compact',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A boolean on/off toggle. The thumb slides and the track crossfades colour, sharing SegmentedToggle/UnderlineTabs\' own slide-animation hook for a consistent motion feel.',
   whenToUse: 'A setting that takes effect immediately, no separate save step. For recording a fact a future action (like a form submit) will act on, use Checkbox; for one-of-many exclusive selection, use Radio.',
   a11y: 'Renders a Pressable with accessibilityRole="switch" and accessibilityState.checked — pass accessibilityLabel to say what it controls.',

package/starter-kit/components/TextArea/TextArea.catalog.tsx

@@ -9,7 +9,8 @@ function TextAreaDemo() {
 
 export default defineCatalogPage({
   component: 'TextArea',
-  group: 'Inputs',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'FieldContainer', role: "The field frame around the multi-line input.", relationship: 'built-in' },
   ],

package/starter-kit/components/Toast/Toast.catalog.tsx

@@ -28,7 +28,8 @@ function ToastDemo() {
 
 export default defineCatalogPage({
   component: 'Toast',
-  group: 'Feedback',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A transient confirmation bar. Without a variant it renders the dark surface with inverse text; a variant shifts to a pastel status color.',
   whenToUse: "Transient and self-contained, floating over the screen, expected to go away on its own or via its own action. For a persistent, in-flow message about a standing condition, use Banner.",
   a11y: 'Rendered with accessibilityRole="alert" so screen readers announce it when it appears.',

package/starter-kit/components/Tooltip/Tooltip.catalog.tsx

@@ -31,7 +31,8 @@ function TooltipDemo() {
 
 export default defineCatalogPage({
   component: 'Tooltip',
-  group: 'Overlays',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A small floating label anchored above or below its wrapped trigger. Fully controlled — drive `visible` from the trigger\'s own onLongPress/onPressIn, since mobile has no hover.',
   a11y: 'The bubble is a plain, non-interactive View; the trigger you wrap it around carries its own accessibility.',
   variants: {

package/starter-kit/components/TopNav/TopNav.catalog.tsx

@@ -11,7 +11,10 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'TopNav',
-  group: 'Navigation',
+  group: 'Components',
+  composedOf: [
+    { component: 'Button', role: "The leading and trailing slots, typically small icon Buttons (back, close, an action).", relationship: 'slot' },
+  ],
   description: 'A screen\'s top bar — fixed-width leading/trailing slots flanking a centered title (or custom center content). Slots reserve their layout space even when empty, so the title stays centered no matter which sides are populated.',
   a11y: 'The title renders with accessibilityRole="header". Slot content (typically icon-only Buttons) carries its own accessibilityLabel.',
   // No `variant` prop exists on TopNav — its "Variants" column just shows the one default look,

package/starter-kit/components/UnderlineTabs/UnderlineTabs.catalog.tsx

@@ -20,9 +20,7 @@ function UnderlineTabsDemo() {
 
 export default defineCatalogPage({
   component: 'UnderlineTabs',
-  group: 'Selection',
-  // Phone width plus a small phone, where long labels truncate.
-  previewWidths: [402, 320],
+  group: 'Components',
   description: 'A quieter tab switcher — left-aligned labels over a hairline rule, with a sliding underline indicator. Same options/value/onChange API as SegmentedToggle.',
   whenToUse: "Quiet, secondary navigation within a screen that already has a clear primary focus. For a prominent, primary choice, use SegmentedToggle.",
   a11y: 'Each tab is a Pressable label; the underline is a visual indicator only, so selection is also conveyed by the active label weight.',

package/starter-kit/pages/ReportIssue.catalog.tsx

@@ -140,7 +140,24 @@ function ReportIssueDemo() {
 }
 
 export default defineCatalogPage({
-  group: 'Recipes',
+  group: 'Patterns',
+  composedOf: [
+    { component: 'BottomSheet', role: "Holds the whole report flow, opened from the Report an issue button.", relationship: 'built-in' },
+    { component: 'TopNav', role: "The sheet header with a Close button.", relationship: 'built-in' },
+    { component: 'ProgressDots', role: "The step indicator.", relationship: 'built-in' },
+    { component: 'Banner', role: "The Delays reported near 14 St service alert.", relationship: 'built-in' },
+    { component: 'PillRow', role: "The issue-type and line pickers.", relationship: 'built-in' },
+    { component: 'TextArea', role: "Free-text details.", relationship: 'built-in' },
+    { component: 'Checkbox', role: "Marks the report urgent.", relationship: 'built-in' },
+    { component: 'Radio', role: "Chooses between sharing publicly and reporting anonymously.", relationship: 'built-in' },
+    { component: 'Switch', role: "Notify me when resolved.", relationship: 'built-in' },
+    { component: 'SkeletonGroup', role: "Groups the loading lines for Recent reports near you into one loading region.", relationship: 'built-in' },
+    { component: 'Shimmer', role: "The loading lines themselves.", relationship: 'built-in' },
+    { component: 'Dock', role: "The sheet footer holding Submit report.", relationship: 'built-in' },
+    { component: 'Dialog', role: "Confirms discarding the report on close.", relationship: 'built-in' },
+    { component: 'ButtonGroup', role: "The dialog's Keep editing and Discard buttons.", relationship: 'built-in' },
+    { component: 'Button', role: "Report an issue, Close, Submit report, and the dialog's actions.", relationship: 'built-in' },
+  ],
   description: 'A composed real screen — a "report an issue" flow opened from a BottomSheet, combining a step indicator, a service-alert banner, a Pill-based issue-type and line picker (a data choice, not a view switch, so Pill rather than SegmentedToggle), free-text and toggle inputs, and a loading skeleton for recent reports. Dismissing with unsaved changes opens a confirmation Dialog.',
   tokenGallery: true,
   fullWidthLabel: 'Preview',