@krapwoo/ds-viewer 0.4.6 → 0.4.8

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,10 @@ 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' },
+  ],
   comparison: BUTTON_COMPARISON,
   description:
     'The primary tap target. Five visual weights, three sizes, optional leading/trailing icon, plus loading and icon-only modes.',

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,13 @@ 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' },
+    { component: 'TopNav', role: "The sheet's header, titled with the field's label.", relationship: 'built-in' },
+    { component: 'Button', role: "The icon-only Close button in the sheet header.", relationship: 'built-in' },
+  ],
   description: 'A labelled field that opens a BottomSheet picker on tap — the "bottom sheet picker" interaction: tap the trigger, pick an option from the sheet, it closes.',
   whenToUse: 'The answer is one of a small, known set of choices — never free text. For free-text filtering, use SearchField; for a named field with a fixed identity, use InputField.',
   a11y: 'The trigger is a Pressable (via FieldContainer) with accessibilityRole="button". Options render as accessibilityRole="radio" inside a "radiogroup", with accessibilityState.checked reflecting the current selection.',

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

@@ -5,7 +5,13 @@ 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' },
+    { component: 'Button', role: "The action button, plus a tertiary secondaryAction button when set.", relationship: 'built-in' },
+  ],
   description: 'A centred placeholder for a screen or section with nothing to show yet — no results, no saved items, a first-run state.',
   whenToUse: "Fills the entire content area because there's nothing else to show. For a note that sits alongside other real content, use Banner instead.",
   a11y: 'A plain View with text; the action(s) render as real Buttons inside a ButtonGroup, which carry their own accessibility.',

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,7 +17,12 @@ 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.',
   a11y: 'The editable mode is a live TextInput; the picker mode is a Pressable row. Either mode shows a clear button while active (focused, or active for a picker) with a value set. Provide a meaningful label.',

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

@@ -8,7 +8,11 @@ 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' },
+  ],
   description: 'Stacks ListItem rows on a rounded white surface, with a Divider automatically inserted between each consecutive pair — never after the last.',
   a11y: 'A plain View; each ListItem child carries its own accessibility.',
   variants: {

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,10 @@ 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' },
+  ],
   specimenSize: 'compact',
   comparison: PILL_COMPARISON,
   description: 'A compact selectable chip — selected/unselected states with an optional leading icon.',

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

@@ -4,7 +4,10 @@ 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' },
+  ],
   description: 'A horizontally-scrolling row of Pill chips, with an optional trailing icon-only add pill — keeps the selected pill scrolled into view automatically.',
   whenToUse: 'A scrollable row of selection chips (e.g. saved-place shortcuts) — for a fixed row of action buttons instead, use ButtonGroup.',
   a11y: 'The row itself carries no accessibility role; each Pill (including the add pill) keeps its own accessibilityLabel/role from the Pill component.',

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,12 @@ 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' },
+  ],
   description: 'Single-line search input on the shared field chrome — leading search icon, a border that darkens on focus, and a clear button while active with text.',
   whenToUse: 'Free-text filtering/searching only — never a named field with a fixed value. For that, use InputField; for a small known set of choices, use Dropdown.',
   a11y: 'Forwards a ref to the underlying TextInput; all TextInputProps pass through, so pass accessibilityLabel/placeholder as needed.',

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

@@ -4,7 +4,11 @@ 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' },
+  ],
   description: 'An uppercase muted section label with an optional inline icon and a right-aligned ghost button.',
   whenToUse: "A label above a group of related rows within a screen (e.g. above a List) — for the screen's own top bar, use TopNav.",
   a11y: 'Title renders as plain Text — no heading role. A tappable labelIcon (onPress set) becomes accessibilityRole="button" with accessibilityLabel falling back to the section\'s own title; a non-interactive labelIcon has no accessibility node of its own. The trailing button is a real Button, so it carries Button\'s own accessibility for free.',

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,11 @@ 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' },
+  ],
   description: 'A multi-line input that grows with its content from a minimum height.',
   a11y: 'A multiline TextInput; pass accessibilityLabel via inputProps when there is no visible label beside it.',
   variants: {

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

@@ -28,10 +28,18 @@ 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.',
+  // Confirmed from Toast.tsx's own JSX, not inferred from its imports: it renders a Button itself
+  // (not a caller-supplied child) whenever `action` is set. Toast.tsx also renders an Icon for its
+  // status glyph, but Icon has no catalog page/known component name of its own to confirm against
+  // yet, so that entry is left out rather than logging an unknown-component warning.
+  composedOf: [
+    { component: 'Button', role: 'Renders the optional action button when action is set.', relationship: 'built-in' },
+  ],
   variants: {
     itemsFill: true,
     items: [

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',

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

@@ -27,10 +27,11 @@ const styles = StyleSheet.create({
   // fixed TopNav header and Dock footer around a scrollable middle, the same fixed-header/
   // scrollable-body/fixed-footer shape a real screen would use.
   savedTripsScreen: { flex: 1, alignSelf: 'stretch' },
-  // A fixed cap (not `flex: 1`) — sidesteps a web-only flexbox quirk where a `flex: 1` ScrollView
-  // nested inside PhoneFrame's own fixed height doesn't actually shrink to the space left after
-  // TopNav/Dock, and grows PhoneFrame itself past its intended 480px instead of scrolling.
-  savedTripsScroll: { maxHeight: 320 },
+  // Takes the space between the TopNav and the Dock and scrolls (`minHeight: 0` lets a flex child
+  // shrink below its content on the web).
+  savedTripsScroll: { flex: 1, minHeight: 0 },
+  // The muted area between TopNav and Dock takes the remaining height, so the list scrolls there.
+  savedTripsBody: { flex: 1, minHeight: 0 },
   savedTripsScrollContent: { padding: DS_SPACING[800], gap: DS_SPACING[600] },
   // Shared by SavedTrips' small inline rows — the "Updating arrival times…" loading row and each
   // list row's trailing badge+button cluster (identical layout, one key).
@@ -127,7 +128,7 @@ function SavedTripsDemo() {
             </Tooltip>
           }
         />
-        <Surface tone="muted">
+        <Surface tone="muted" style={styles.savedTripsBody}>
           <ScrollView style={styles.savedTripsScroll} contentContainerStyle={styles.savedTripsScrollContent}>
             <SearchField value={query} onChangeText={setQuery} placeholder="Search stations" />
             <SegmentedToggle
@@ -239,7 +240,27 @@ function SavedTripsDemo() {
 }
 
 export default defineCatalogPage({
-  group: 'Recipes',
+  group: 'Patterns',
+  composedOf: [
+    { component: 'TopNav', role: "The screen header, titled Saved trips, with a Filters button.", relationship: 'built-in' },
+    { component: 'Tooltip', role: "The Filter by mode hint on the Filters button.", relationship: 'built-in' },
+    { component: 'Surface', role: "The muted background behind the search, toggles and list.", relationship: 'built-in' },
+    { component: 'SearchField', role: "Searches stations.", relationship: 'built-in' },
+    { component: 'SegmentedToggle', role: "Switches between List and Map views.", relationship: 'built-in' },
+    { component: 'UnderlineTabs', role: "The All, Nearby and Favorites tabs.", relationship: 'built-in' },
+    { component: 'PillRow', role: "Mode filter pills.", relationship: 'built-in' },
+    { component: 'Loading', role: "The small spinner beside Updating arrival times.", relationship: 'built-in' },
+    { component: 'Dropdown', role: "The Sort by picker.", relationship: 'built-in' },
+    { component: 'SectionHeader', role: "The Nearby stations heading.", relationship: 'built-in' },
+    { component: 'List', role: "Holds the saved-trip rows with dividers.", relationship: 'built-in' },
+    { component: 'ListItem', role: "Each saved trip row.", relationship: 'built-in' },
+    { component: 'Avatar', role: "Each row's mode icon.", relationship: 'built-in' },
+    { component: 'Badge', role: "Each row's status, e.g. delays.", relationship: 'built-in' },
+    { component: 'Button', role: "The Filters button, each row's remove button, and Plan a new trip.", relationship: 'built-in' },
+    { component: 'EmptyState', role: "Shown instead of the list on an empty tab (Favorites, or after removing every row).", relationship: 'built-in' },
+    { component: 'Toast', role: "Confirms a removed trip, with Undo.", relationship: 'built-in' },
+    { component: 'Dock', role: "The bottom bar holding Plan a new trip.", relationship: 'built-in' },
+  ],
   description: 'A composed real screen — a saved-trips list with a search bar, tab switcher, mode filter pills, a sort Dropdown, and a bottom action bar. Switch to the "Favorites" tab (or remove every row) to see the EmptyState alternative to the list; tap the header icon to see its Tooltip; tap a row\'s trailing × to see the Toast, which only appears after that real action and auto-dismisses (or Undo) — remove two rows back-to-back and each removal gets its own stacked toast on its own clock.',
   tokenGallery: true,
   fullWidthLabel: 'Preview',

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

@@ -40,7 +40,13 @@ function TripPlannerFormDemo() {
 }
 
 export default defineCatalogPage({
-  group: 'Recipes',
+  group: 'Patterns',
+  composedOf: [
+    { component: 'Card', role: "Frames the whole form.", relationship: 'built-in' },
+    { component: 'InputField', role: "The From and To fields.", relationship: 'built-in' },
+    { component: 'Divider', role: "Separates the fields from the actions.", relationship: 'built-in' },
+    { component: 'Button', role: "Add stop (tertiary) and Continue (primary, disabled until To is filled).", relationship: 'built-in' },
+  ],
   description: 'A composed real screen — not one component in isolation — showing how Card, InputField, Divider, and Button actually fit together: a From/To trip form with a secondary "Add stop" action and a primary "Continue" that\'s disabled until a destination is entered.',
   tokenGallery: true,
   fullWidthLabel: 'Preview',