@krapwoo/ds-viewer 0.6.3 → 0.6.5

package/package.json

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

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

@@ -6,6 +6,7 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'AnimatedChevron',
   group: 'Components',
+  whenToUse: 'An expand/collapse affordance that should animate its own state change — it flips vertically in place, so it never points sideways mid-transition. Where a chevron never changes state, a plain icon is enough.',
   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

@@ -32,6 +32,7 @@ const AVATAR_COMPARISON = grid(
 export default defineCatalogPage({
   component: 'Avatar',
   group: 'Components',
+  whenToUse: 'A person or place\'s identity in a circle. Pass whatever you have: image, icon, or initials are tried in that order, so a missing image degrades to initials without leaving a gap.',
   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/BottomSheet/BottomSheet.catalog.tsx

@@ -8,48 +8,41 @@ import { BottomSheet } from './BottomSheet';
 import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
 
 const styles = StyleSheet.create({
-  // BottomSheet/Dropdown demos render inside the shared `PhoneFrame` (./PhoneFrame.tsx) so their
-  // absolute overlays stay contained instead of covering the whole catalog page. No padding here —
-  // BottomSheet's own content area already supplies the standard 16px.
-  sheetContent: {},
+  // No padding here — BottomSheet's own content area already supplies the standard 16px.
   cardTitle: { ...DS_TYPOGRAPHY.labelMd, color: DS_SEMANTIC.text.regular },
   cardBody: { ...DS_TYPOGRAPHY.bodySm, color: DS_SEMANTIC.text.muted, marginTop: DS_SPACING[200] },
 });
 
-function BottomSheetDemo() {
+const EXTRA_PARAGRAPHS = [
+  'Board at the front car for a faster transfer at Union Sq.',
+  'This line runs express between 96 St and 168 St during rush hours, skipping local stops in between. Weekend service runs local along the full route, with some stations closed for planned maintenance.',
+  'Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible entrances before you travel.',
+];
+
+/** Every example is a real sheet inside a phone: the trigger opens it, the backdrop dismisses it.
+ *  `OverlayDemo` supplies the phone, so the sheet's absolute overlay stays in its own cell. */
+function Sheet({
+  header,
+  footer,
+  /** Extra paragraphs; enough of them and the content area passes 90% height and starts scrolling. */
+  paragraphs = 0,
+}: {
+  header?: (close: () => void) => React.ReactNode;
+  footer?: (close: () => void) => React.ReactNode;
+  paragraphs?: number;
+}) {
   return (
-    <OverlayDemo triggerLabel="Open sheet">
+    // Open from the start: closed, every example is the same empty phone behind the same trigger,
+    // and what each one is named for — the header, the footer, the scrolling — is invisible.
+    <OverlayDemo triggerLabel="Open sheet" initiallyOpen>
       {({ open, close }) => (
-        <BottomSheet
-          visible={open}
-          onDismiss={close}
-          header={
-            <TopNav
-              title="Trip details"
-              trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={close} />}
-            />
-          }
-          footer={
-            <Dock>
-              <Button label="Confirm" onPress={close} />
-            </Dock>
-          }
-        >
-          <View style={styles.sheetContent}>
-            <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
+        <BottomSheet visible={open} onDismiss={close} header={header?.(close)} footer={footer?.(close)}>
+          <View>
+            <Text style={styles.cardTitle}>Uptown &amp; The Bronx</Text>
             <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min.</Text>
-            {/* Long enough to overflow the phone frame's fixed height — demonstrates the Dock footer's
-                `elevated` shadow turning on automatically once this content area actually scrolls. */}
-            <Text style={styles.cardBody}>Board at the front car for a faster transfer at Union Sq.</Text>
-            <Text style={styles.cardBody}>
-              This line runs express between 96 St and 168 St during rush hours, skipping local stops in
-              between. Weekend service runs local along the full route, with some stations closed for
-              planned maintenance.
-            </Text>
-            <Text style={styles.cardBody}>
-              Elevators are available at 168 St, 137 St, and 125 St — check the map for accessible
-              entrances before you travel.
-            </Text>
+            {EXTRA_PARAGRAPHS.slice(0, paragraphs).map((line) => (
+              <Text key={line} style={styles.cardBody}>{line}</Text>
+            ))}
           </View>
         </BottomSheet>
       )}
@@ -57,6 +50,18 @@ function BottomSheetDemo() {
   );
 }
 
+const topNav = (close: () => void) => (
+  <TopNav
+    title="Trip details"
+    trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={close} />}
+  />
+);
+const dock = (close: () => void) => (
+  <Dock>
+    <Button label="Confirm" onPress={close} />
+  </Dock>
+);
+
 export default defineCatalogPage({
   component: 'BottomSheet',
   group: 'Components',
@@ -67,5 +72,19 @@ export default defineCatalogPage({
   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").',
-  render: () => <BottomSheetDemo />,
+  variants: {
+    items: [
+      // Both slots empty: the sheet is only as tall as its content, above its own drag handle.
+      { key: 'content-only', name: 'Content only', node: <Sheet /> },
+      { key: 'header', name: 'With a TopNav header', node: <Sheet header={topNav} /> },
+      { key: 'header-footer', name: 'Header and a Dock footer', node: <Sheet header={topNav} footer={dock} /> },
+    ],
+  },
+  states: {
+    items: [
+      // Past 90% of the phone's height the content area scrolls, which is what turns on the Dock
+      // footer's shadow — overflowing it is the only way to see that happen.
+      { key: 'scrolling', name: 'Content long enough to scroll', node: <Sheet header={topNav} footer={dock} paragraphs={3} /> },
+    ],
+  },
 });

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

@@ -6,6 +6,7 @@ import { Button } from '../Button';
 export default defineCatalogPage({
   component: 'ButtonGroup',
   group: 'Components',
+  whenToUse: 'Two or three Buttons that should read as one family — horizontal for a trailing-aligned pair (a dialog\'s Cancel and Confirm), vertical for up to three stretched full width. Keep one variant tier and one size across the group. For a screen\'s bottom action area, use Dock.',
   composedOf: [
     { component: 'Button', role: "Its children: up to two Buttons side by side, or three stacked.", relationship: 'slot' },
   ],

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

@@ -12,19 +12,18 @@ const styles = StyleSheet.create({
   dialogActions: { marginTop: DS_SPACING[800] },
 });
 
-function DialogDemo() {
+/** Every example is a real dialog inside a phone, so the backdrop covers the screen it belongs to
+ *  rather than the catalog page. `OverlayDemo` supplies the phone and the trigger. */
+function Demo({ title, body, actions }: { title: string; body?: string; actions: (close: () => void) => React.ReactNode }) {
   return (
-    <OverlayDemo triggerLabel="Open dialog">
+    // Open from the start: a closed dialog is just a trigger, so the card each example is named
+    // for would never be on screen.
+    <OverlayDemo triggerLabel="Open dialog" initiallyOpen>
       {({ open, close }) => (
         <Dialog visible={open} onDismiss={close}>
-          <Text style={styles.cardTitle}>Delete this trip?</Text>
-          <Text style={styles.cardBody}>This can't be undone.</Text>
-          <View style={styles.dialogActions}>
-            <ButtonGroup>
-              <Button label="Cancel" variant="tertiary" onPress={close} />
-              <Button label="Delete" onPress={close} />
-            </ButtonGroup>
-          </View>
+          <Text style={styles.cardTitle}>{title}</Text>
+          {body ? <Text style={styles.cardBody}>{body}</Text> : null}
+          <View style={styles.dialogActions}>{actions(close)}</View>
         </Dialog>
       )}
     </OverlayDemo>
@@ -34,8 +33,58 @@ function DialogDemo() {
 export default defineCatalogPage({
   component: 'Dialog',
   group: 'Components',
+  composedOf: [
+    { component: 'ButtonGroup', role: "Lays out the dialog's actions; a dialog's own children decide this, not Dialog.", relationship: 'related' },
+  ],
   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.',
-  render: () => <DialogDemo />,
+  variants: {
+    items: [
+      {
+        key: 'confirm',
+        name: 'A confirmation, two actions',
+        node: (
+          <Demo
+            title="Delete this trip?"
+            body="This can't be undone."
+            actions={(close) => (
+              <ButtonGroup>
+                <Button label="Cancel" variant="tertiary" onPress={close} />
+                <Button label="Delete" onPress={close} />
+              </ButtonGroup>
+            )}
+          />
+        ),
+      },
+      {
+        key: 'acknowledge',
+        name: 'One action to acknowledge',
+        node: (
+          <Demo
+            title="Trip saved"
+            body="You'll find it under Saved trips."
+            actions={(close) => <Button label="Got it" onPress={close} />}
+          />
+        ),
+      },
+      {
+        // Title alone: Dialog adds no body of its own, so a question that needs no explanation
+        // keeps the card to two lines.
+        key: 'title-only',
+        name: 'Title and actions only',
+        node: (
+          <Demo
+            title="Discard changes?"
+            actions={(close) => (
+              <ButtonGroup>
+                <Button label="Keep editing" variant="tertiary" onPress={close} />
+                <Button label="Discard" onPress={close} />
+              </ButtonGroup>
+            )}
+          />
+        ),
+      },
+    ],
+  },
 });

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

@@ -12,6 +12,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'Divider',
   group: 'Components',
+  whenToUse: 'A single hairline between two pieces of content you are laying out yourself. List already puts one between each pair of its rows, so adding your own there would double them.',
   specimenSize: 'regular',
   description: 'A 1px hairline separator at the divider token colour.',
   a11y: 'A plain, non-interactive View — purely decorative.',

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

@@ -6,6 +6,7 @@ import { Dock } from './Dock';
 export default defineCatalogPage({
   component: 'Dock',
   group: 'Components',
+  whenToUse: 'A screen\'s bottom action area: up to three full-width buttons above the home indicator, with an optional caption. It is not positioned absolutely itself — the composing screen decides whether to pin it or lay it out inline at the end of a column. For actions inside a card or dialog, use ButtonGroup.',
   composedOf: [
     { component: 'Button', role: "Its children: up to three full-width Buttons, stacked.", relationship: 'slot' },
   ],

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

@@ -13,6 +13,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'FieldContainer',
   group: 'Components',
+  whenToUse: 'Building a new kind of field. It carries the shared field chrome and reads the ambient Surface tone, so it stays visible on white and on muted backgrounds alike. For the fields that already exist, use InputField or TextArea instead of wrapping this yourself.',
   composedOf: [
     { component: 'Surface', role: "Reads the surrounding Surface tone: a recessed fill on white, opaque white inside a muted Surface.", relationship: 'related' },
   ],

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

@@ -5,6 +5,7 @@ import { InputClearButton } from './InputClearButton';
 export default defineCatalogPage({
   component: 'InputClearButton',
   group: 'Components',
+  whenToUse: 'The clear control inside a text field. InputField and SearchField already include one, so reach for it directly only when building another field type that needs the same affordance.',
   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/List/List.catalog.tsx

@@ -9,6 +9,7 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'List',
   group: 'Components',
+  whenToUse: 'A set of ListItem rows as one rounded surface, with dividers between rows and never after the last. For a single row standing on its own, use ListItem directly.',
   specimenSize: 'regular',
   composedOf: [
     { component: 'Divider', role: "The hairline between consecutive items (none after the last).", relationship: 'built-in' },

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

@@ -6,6 +6,7 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'Loading',
   group: 'Components',
+  whenToUse: 'An indeterminate wait of unknown length — `circle` inline, `linear` where a bar suits the layout better. Button and Pill already show this in their own loading states, so don\'t nest one inside them. For a known number of steps, use ProgressDots.',
   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.',

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

@@ -5,6 +5,7 @@ import { ProgressDots } from './ProgressDots';
 export default defineCatalogPage({
   component: 'ProgressDots',
   group: 'Components',
+  whenToUse: 'A short sequence of steps whose length is known, with the current step widened into a pill. For a wait of unknown length, use Loading.',
   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/SegmentedToggle/SegmentedToggle.catalog.tsx

@@ -1,29 +1,50 @@
 import React, { useState } from 'react';
 import { defineCatalogPage } from '@krapwoo/ds-viewer';
-import { SegmentedToggle } from './SegmentedToggle';
+import { SegmentedToggle, type SegmentedToggleOption } from './SegmentedToggle';
 
-function SegmentedToggleDemo() {
-  const [value, setValue] = useState('map');
-  return (
-    <SegmentedToggle
-      value={value}
-      onChange={setValue}
-      options={[
-        { value: 'map', label: 'Map', iconName: 'map' },
-        { value: 'list', label: 'List', iconName: 'menu' },
-        { value: 'saved', label: 'Saved', iconName: 'bell', badge: 3 },
-        // Label-only segment (no iconName) — the layout every other option's icon would otherwise hide.
-        { value: 'settings', label: 'Settings' },
-      ]}
-    />
-  );
+/** Each example owns its own selection, so the thumb really slides when a segment is pressed. */
+function Demo({ options, initial }: { options: SegmentedToggleOption[]; initial?: string }) {
+  const [value, setValue] = useState(initial ?? options[0].value);
+  return <SegmentedToggle value={value} onChange={setValue} options={options} />;
 }
 
+const TWO: SegmentedToggleOption[] = [
+  { value: 'map', label: 'Map' },
+  { value: 'list', label: 'List' },
+];
+const ICONS: SegmentedToggleOption[] = [
+  { value: 'map', label: 'Map', iconName: 'map' },
+  { value: 'list', label: 'List', iconName: 'menu' },
+  { value: 'saved', label: 'Saved', iconName: 'bell' },
+];
+const MIXED: SegmentedToggleOption[] = [
+  { value: 'map', label: 'Map', iconName: 'map' },
+  { value: 'list', label: 'List', iconName: 'menu' },
+  { value: 'saved', label: 'Saved', iconName: 'bell', badge: 3 },
+  // Label-only, beside segments that have icons: the row keeps one height either way.
+  { value: 'settings', label: 'Settings' },
+];
+
 export default defineCatalogPage({
   component: 'SegmentedToggle',
   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.',
-  render: () => <SegmentedToggleDemo />,
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'two', name: 'Two options', node: <Demo options={TWO} /> },
+      { key: 'icons', name: 'An icon per segment', node: <Demo options={ICONS} /> },
+      { key: 'badge', name: 'A badge, and a label-only segment', node: <Demo options={MIXED} /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      // Where the thumb sits is the component's whole job, so show both ends of the track.
+      { key: 'first', name: 'First segment selected', node: <Demo options={ICONS} initial="map" /> },
+      { key: 'last', name: 'Last segment selected', node: <Demo options={ICONS} initial="saved" /> },
+    ],
+  },
 });

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

@@ -11,6 +11,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'Breathing',
   group: 'Components',
+  whenToUse: 'The raw pulsing block behind Shimmer, exported so a composite skeleton can pulse in lockstep with plain Shimmers off the one shared clock. For an ordinary loading placeholder, use Shimmer.',
   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.",

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

@@ -12,6 +12,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'Surface',
   group: 'Components',
+  a11y: 'No semantics of its own: it renders a plain filled View and passes its tone down through context, so it adds nothing to the accessibility tree and neither groups nor labels what sits inside it.',
   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.",

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

@@ -10,6 +10,7 @@ function TextAreaDemo() {
 export default defineCatalogPage({
   component: 'TextArea',
   group: 'Components',
+  whenToUse: 'Multiline free text that grows from a minimum height. For a single-line labelled row use InputField — both share FieldContainer\'s chrome.',
   specimenSize: 'regular',
   composedOf: [
     { component: 'FieldContainer', role: "The field frame around the multi-line input.", relationship: 'built-in' },

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

@@ -32,6 +32,7 @@ function TooltipDemo() {
 export default defineCatalogPage({
   component: 'Tooltip',
   group: 'Components',
+  whenToUse: 'A brief floating label for a control whose purpose an icon alone doesn\'t carry. It measures the trigger\'s real screen position, so the bubble stays inside the screen\'s edges and the arrow still points at the trigger\'s true centre. For something the reader must acknowledge, use Dialog.',
   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.',

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

@@ -12,6 +12,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'TopNav',
   group: 'Components',
+  whenToUse: 'A screen\'s top bar, and BottomSheet\'s header slot. Its leading and trailing slots reserve their width even when empty, so the title stays centred whether one, both, or neither side has content. For actions at the bottom of a screen, use Dock.',
   composedOf: [
     { component: 'Button', role: "The leading and trailing slots, typically small icon Buttons (back, close, an action).", relationship: 'slot' },
   ],

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

@@ -1,28 +1,50 @@
 import React, { useState } from 'react';
 import { defineCatalogPage } from '@krapwoo/ds-viewer';
-import { UnderlineTabs } from './UnderlineTabs';
+import { UnderlineTabs, type UnderlineTabOption } from './UnderlineTabs';
 
-function UnderlineTabsDemo() {
-  const [value, setValue] = useState('all');
-  return (
-    <UnderlineTabs
-      value={value}
-      onChange={setValue}
-      options={[
-        { value: 'all', label: 'All' },
-        // Leading-icon tab — the layout every other option (icon-less) would otherwise hide.
-        { value: 'nearby', label: 'Nearby', iconName: 'pin' },
-        { value: 'favorites', label: 'Favorites', badge: 2 },
-      ]}
-    />
-  );
+/** Each example owns its own selection, so the underline really slides when a tab is pressed. */
+function Demo({ options, initial }: { options: UnderlineTabOption[]; initial?: string }) {
+  const [value, setValue] = useState(initial ?? options[0].value);
+  return <UnderlineTabs value={value} onChange={setValue} options={options} />;
 }
 
+const LABELS: UnderlineTabOption[] = [
+  { value: 'all', label: 'All' },
+  { value: 'nearby', label: 'Nearby' },
+  { value: 'favorites', label: 'Favorites' },
+];
+const WITH_ICON: UnderlineTabOption[] = [
+  { value: 'all', label: 'All' },
+  // A leading icon beside tabs that have none: the row still aligns on one baseline.
+  { value: 'nearby', label: 'Nearby', iconName: 'pin' },
+  { value: 'favorites', label: 'Favorites' },
+];
+const WITH_BADGE: UnderlineTabOption[] = [
+  { value: 'all', label: 'All' },
+  { value: 'nearby', label: 'Nearby', iconName: 'pin' },
+  { value: 'favorites', label: 'Favorites', badge: 2 },
+];
+
 export default defineCatalogPage({
   component: 'UnderlineTabs',
   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.',
-  render: () => <UnderlineTabsDemo />,
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'labels', name: 'Labels only', node: <Demo options={LABELS} /> },
+      { key: 'icon', name: 'A leading icon on one tab', node: <Demo options={WITH_ICON} /> },
+      { key: 'badge', name: 'A badge on a tab', node: <Demo options={WITH_BADGE} /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      // The underline's position is the selection, so show it at both ends of the row.
+      { key: 'first', name: 'First tab selected', node: <Demo options={LABELS} initial="all" /> },
+      { key: 'last', name: 'Last tab selected', node: <Demo options={LABELS} initial="favorites" /> },
+    ],
+  },
 });