@krapwoo/ds-viewer 0.1.0 → 0.2.0

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

@@ -0,0 +1,96 @@
+import React from 'react';
+import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { Badge } from './Badge';
+import type { BadgeVariant } from './Badge.types';
+
+// Grid comparisons: each cell is a real instance with exactly the props its row and column name.
+// Never build these by multiplying `variants` with `states` — those are pre-rendered nodes and
+// cannot combine.
+function grid(
+  rowLabel: string,
+  columnLabel: string,
+  rows: { key: string; label: string }[],
+  columns: { key: string; label: string }[],
+  cell: (row: string, column: string) => React.ReactNode,
+  size?: ComparisonDef['size'],
+): ComparisonDef {
+  return {
+    rowLabel,
+    columnLabel,
+    rows,
+    columns,
+    cells: rows.flatMap((row) => columns.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
+    size,
+  };
+}
+
+// Badge: Tone × Icon layout. One icon per tone, matching the Variants examples.
+const BADGE_TONES: { key: BadgeVariant; label: string; text: string; icon: React.ComponentProps<typeof Badge>['leadingIcon'] }[] = [
+  { key: 'neutral', label: 'Neutral', text: 'Local', icon: 'pin' },
+  { key: 'info', label: 'Info', text: 'Notice', icon: 'info-circle' },
+  { key: 'positive', label: 'Positive', text: 'On time', icon: 'circle-check' },
+  { key: 'warning', label: 'Warning', text: 'Delayed', icon: 'triangle-alert' },
+  { key: 'negative', label: 'Negative', text: 'Suspended', icon: 'circle-slash' },
+];
+const BADGE_COMPARISON = grid(
+  'Tone',
+  'Icon',
+  BADGE_TONES.map(({ key, label }) => ({ key, label })),
+  [
+    { key: 'label-only', label: 'Label only' },
+    { key: 'leading-icon', label: 'Leading icon' },
+    { key: 'trailing-icon', label: 'Trailing icon' },
+    { key: 'icon-only', label: 'Icon-only' },
+  ],
+  (row, column) => {
+    const tone = BADGE_TONES.find((t) => t.key === row)!;
+    if (column === 'icon-only') return <Badge variant={tone.key} leadingIcon={tone.icon} accessibilityLabel={tone.text} />;
+    return (
+      <Badge
+        variant={tone.key}
+        label={tone.text}
+        leadingIcon={column === 'leading-icon' ? tone.icon : undefined}
+        trailingIcon={column === 'trailing-icon' ? tone.icon : undefined}
+      />
+    );
+  },
+  'compact',
+);
+
+export default defineCatalogPage({
+  component: 'Badge',
+  group: 'Surfaces',
+  specimenSize: 'compact',
+  comparison: BADGE_COMPARISON,
+  description: 'A small status chip — five semantic variants, with optional leading/trailing icons or icon-only.',
+  whenToUse: "Read-only and inline, not tappable — for one row's data point. For a tappable chip with a selected state, use Pill; for a message about the whole screen, use Toast or Banner.",
+  a11y: 'A plain View with text; the label carries the meaning, so avoid encoding status by color alone.',
+  variants: {
+    items: [
+      { key: 'neutral', name: 'Neutral', props: { variant: 'neutral' }, node: <Badge variant="neutral" label="Local" /> },
+      { key: 'info', name: 'Info', props: { variant: 'info' }, node: <Badge variant="info" label="Notice" leadingIcon="info-circle" /> },
+      { key: 'positive', name: 'Positive', props: { variant: 'positive' }, node: <Badge variant="positive" label="On time" leadingIcon="circle-check" /> },
+      { key: 'warning', name: 'Warning', props: { variant: 'warning' }, node: <Badge variant="warning" label="Delayed" leadingIcon="triangle-alert" /> },
+      { key: 'negative', name: 'Negative', props: { variant: 'negative' }, node: <Badge variant="negative" label="Suspended" leadingIcon="circle-slash" /> },
+    ],
+  },
+  states: {
+    items: [
+      {
+        key: 'leading-icon',
+        name: 'Leading icon',
+        node: <Badge variant="positive" label="On time" leadingIcon="circle-check" />,
+      },
+      {
+        key: 'trailing-icon',
+        name: 'Trailing icon',
+        node: <Badge variant="positive" label="On time" trailingIcon="circle-check" />,
+      },
+      {
+        key: 'icon-only',
+        name: 'Icon-only',
+        node: <Badge variant="info" leadingIcon="info-circle" accessibilityLabel="Notice" />,
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,56 @@
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { DS_RADIUS, DS_SPACING, DS_TYPOGRAPHY, DS_ICON_SIZE } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import { STATUS_BG, STATUS_FG } from '../statusColors';
+import type { BadgeProps } from './Badge.types';
+
+/**
+ * A small status pill. Composable: label-only, icon-only (a single icon, no label), or a label with
+ * a leading and/or trailing icon. Text + icons sit on the variant background in the variant's own
+ * emphasis colour.
+ */
+export function Badge({ variant = 'neutral', label, leadingIcon, trailingIcon, accessibilityLabel, style }: BadgeProps) {
+  const hasLabel = label != null && label !== '';
+  // Dev-console check (same policy as ButtonGroup's checkConsistency): the docs require an
+  // accessible name for an icon-only badge, but the type can't enforce it — warn instead of
+  // silently rendering an unnameable status glyph.
+  if (__DEV__ && !hasLabel && !accessibilityLabel) {
+    console.warn('[Badge] Icon-only badge (no `label`) needs an `accessibilityLabel` — without one it has no accessible name.');
+  }
+  const fg = STATUS_FG[variant];
+
+  return (
+    <View
+      style={[styles.badge, !hasLabel && styles.iconOnly, { backgroundColor: STATUS_BG[variant] }, style]}
+      accessibilityRole="text"
+      accessibilityLabel={accessibilityLabel}
+    >
+      {leadingIcon ? <Icon name={leadingIcon} size={DS_ICON_SIZE.xs} color={fg} /> : null}
+      {hasLabel ? (
+        <Text style={[styles.label, { color: fg }]} numberOfLines={1}>
+          {label}
+        </Text>
+      ) : null}
+      {trailingIcon ? <Icon name={trailingIcon} size={DS_ICON_SIZE.xs} color={fg} /> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  badge: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[100],
+    paddingVertical: DS_SPACING[200],
+    paddingHorizontal: DS_SPACING[400],
+    borderRadius: DS_RADIUS.round,
+    alignSelf: 'flex-start',
+  },
+  iconOnly: {
+    paddingHorizontal: DS_SPACING[200],
+  },
+  label: {
+    ...DS_TYPOGRAPHY.labelXs,
+  },
+});

package/starter-kit/components/Badge/Badge.types.ts

@@ -0,0 +1,18 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../../icons';
+
+export type BadgeVariant = 'neutral' | 'info' | 'positive' | 'warning' | 'negative';
+
+export interface BadgeProps {
+  /** Semantic color scheme. */
+  variant?: BadgeVariant;
+  /** Label text. Omit (with a single icon) for an icon-only chip. */
+  label?: string;
+  /** Icon before the label. */
+  leadingIcon?: IconName;
+  /** Icon after the label. */
+  trailingIcon?: IconName;
+  /** Accessible name — required for an icon-only badge (no `label`) so it can be announced. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+}

package/starter-kit/components/Badge/index.ts

@@ -0,0 +1,2 @@
+export { Badge } from './Badge';
+export type { BadgeProps, BadgeVariant } from './Badge.types';

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

@@ -0,0 +1,87 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Banner } from './Banner';
+
+export default defineCatalogPage({
+  component: 'Banner',
+  group: 'Surfaces',
+  description: 'An inline callout for status/announcements — five semantic variants, optional collapsible body, inline link, and action button.',
+  whenToUse: "Persistent and in-flow, describing a standing condition about the screen's content. For a transient, self-contained event notification, use Toast instead.",
+  a11y: 'When onPress/action is set the header/button are Pressables; the collapsible header toggles the description with a chevron affordance.',
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'neutral', name: 'Neutral', props: { variant: 'neutral' }, node: <Banner variant="neutral" title="Schedule notice" description="Holiday schedule in effect Monday." /> },
+      { key: 'info', name: 'Info', props: { variant: 'info' }, node: <Banner variant="info" title="Weekend service change" description="The 6 runs express in both directions this weekend." /> },
+      { key: 'positive', name: 'Positive', props: { variant: 'positive' }, node: <Banner variant="positive" title="Service restored" description="All lines are running on a normal schedule." /> },
+      { key: 'warning', name: 'Warning', props: { variant: 'warning' }, node: <Banner variant="warning" title="Delays" description="Signal problems near 14 St." /> },
+      { key: 'negative', name: 'Negative', props: { variant: 'negative' }, node: <Banner variant="negative" title="Line suspended" description="No service between 96 St and 137 St until further notice." /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'tappable',
+        name: 'Tappable',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Alert preferences"
+            description="Tap to manage which alerts you receive."
+            onPress={() => {}}
+          />
+        ),
+      },
+      {
+        key: 'collapsible-expanded',
+        name: 'Collapsible (expanded)',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Trip details"
+            description="Board at the front car for a faster transfer at Union Sq."
+            collapsible
+          />
+        ),
+      },
+      {
+        key: 'collapsible-collapsed',
+        name: 'Collapsible (collapsed)',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Trip details"
+            description="Board at the front car for a faster transfer at Union Sq."
+            collapsible
+            defaultExpanded={false}
+          />
+        ),
+      },
+      {
+        key: 'action',
+        name: 'With action',
+        node: (
+          <Banner
+            variant="info"
+            title="App update available"
+            description="Version 4.2 adds live bus tracking."
+            action={{ label: 'Update', onPress: () => {} }}
+          />
+        ),
+      },
+      {
+        key: 'link',
+        name: 'With link',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Fare increase"
+            description="New fares start March 1."
+            link={{ label: 'Learn more', onPress: () => {} }}
+          />
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,257 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { View, Text, Pressable, Animated, Easing, StyleSheet, type LayoutChangeEvent } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS, DS_SPACING, DS_TYPOGRAPHY, DS_ICON_SIZE, DS_MOTION_DURATION, DS_MOTION_EASING } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import type { IconName } from '../../icons';
+import { AnimatedChevron } from '../AnimatedChevron';
+import { STATUS_BG, STATUS_FG } from '../statusColors';
+import type { BannerProps, BannerVariant } from './Banner.types';
+
+// Shared with Badge (see ../statusColors) so a banner reads as the same status identity as a
+// badge of the same variant — one map, matched by construction.
+
+const BANNER_ICONS: Record<BannerVariant, IconName> = {
+  neutral: 'info-circle',
+  info: 'info-circle',
+  positive: 'circle-check',
+  warning: 'triangle-alert',
+  negative: 'alert-circle',
+};
+
+const COLLAPSE_ANIM_MS = DS_MOTION_DURATION.base;
+
+/**
+ * A status callout in two layouts, chosen by props:
+ *   • collapsible callout — the whole card toggles the description open/closed;
+ *   • standard callout    — leading icon + title, optional description/link/action.
+ */
+export function Banner({
+  variant = 'warning',
+  title = 'Banner title',
+  description = 'Description text goes here',
+  collapsible = false,
+  defaultExpanded = true,
+  backgroundColor,
+  onPress,
+  trailingIcon,
+  textColor,
+  icon,
+  link,
+  action,
+  style,
+}: BannerProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+  // Real layout height + opacity via the core `Animated` API (`useNativeDriver: false`) — not
+  // `LayoutAnimation`, which is unreliable on the New Architecture (Fabric) and a total no-op on
+  // web, so the collapse used to just snap instantly there. Same measure-once-then-animate
+  // technique used elsewhere in this DS: render in normal flow only on the very first pass while
+  // already expanded (shows instantly, no flash, and captures the real height); every other pass —
+  // including the very first while starting collapsed — positions the content absolutely so it can
+  // self-measure without affecting layout, then animates between 0 and that measured height.
+  const [measuredHeight, setMeasuredHeight] = useState(0);
+  const collapseAnim = useRef(new Animated.Value(defaultExpanded ? 1 : 0)).current;
+
+  useEffect(() => {
+    const anim = Animated.timing(collapseAnim, {
+      toValue: expanded ? 1 : 0,
+      duration: COLLAPSE_ANIM_MS,
+      // `standard` — an in-place expand/collapse (a toggle), per DS_MOTION_EASING_USE.
+      easing: Easing.bezier(...DS_MOTION_EASING.standard),
+      useNativeDriver: false,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [expanded, collapseAnim]);
+
+  const bg = backgroundColor ?? STATUS_BG[variant];
+  const contentTextColor = textColor ?? STATUS_FG[variant];
+  const iconName = icon ?? BANNER_ICONS[variant];
+
+  // ── Collapsible callout: the whole banner toggles the description ─────────────
+  if (collapsible) {
+    const toggle = () => setExpanded(e => !e);
+    const flowMeasure = measuredHeight === 0 && expanded;
+    const onDescriptionLayout = (e: LayoutChangeEvent) => {
+      const h = e.nativeEvent.layout.height;
+      if (h > 0 && h !== measuredHeight) setMeasuredHeight(h);
+    };
+    return (
+      <Pressable
+        style={[styles.calloutContainer, { backgroundColor: bg }, style]}
+        onPress={toggle}
+        accessibilityRole="button"
+        accessibilityState={{ expanded }}
+      >
+        {({ pressed }) => (
+          <>
+            {pressed && <View style={styles.pressOverlay} pointerEvents="none" />}
+            <View style={styles.headerRow}>
+              <Icon name={iconName} size={DS_ICON_SIZE.xs} color={contentTextColor} />
+              <Text style={[styles.title, styles.titleFlex, { color: contentTextColor, marginBottom: 0 }]}>
+                {title}
+              </Text>
+              <AnimatedChevron expanded={expanded} size={DS_ICON_SIZE.xs} color={contentTextColor} />
+            </View>
+            {!!description && (
+              <Animated.View
+                style={[
+                  styles.collapseClip,
+                  measuredHeight === 0
+                    ? expanded
+                      ? null
+                      : styles.collapseHidden
+                    : { height: Animated.multiply(collapseAnim, measuredHeight), opacity: collapseAnim },
+                ]}
+              >
+                <View style={flowMeasure ? undefined : styles.collapseAbsolute} onLayout={onDescriptionLayout}>
+                  <Text style={[styles.description, styles.descriptionPad, { color: contentTextColor }]}>
+                    {description}
+                  </Text>
+                </View>
+              </Animated.View>
+            )}
+          </>
+        )}
+      </Pressable>
+    );
+  }
+
+  // ── Standard callout (title + description) ────────────────────────────────────
+  const body = (pressed: boolean) => (
+    <>
+      {onPress && pressed && <View style={styles.pressOverlay} pointerEvents="none" />}
+      <View style={styles.headerRow}>
+        <Icon name={iconName} size={DS_ICON_SIZE.xs} color={contentTextColor} />
+        <Text style={[styles.title, styles.titleFlex, { color: contentTextColor, marginBottom: 0 }]}>
+          {title}
+        </Text>
+        {trailingIcon ? <Icon name={trailingIcon} size={DS_ICON_SIZE.xs} color={contentTextColor} /> : null}
+      </View>
+      {description || link ? (
+        <Text style={[styles.description, styles.descriptionPad, { color: contentTextColor }]}>
+          {description ?? ''}
+          {description && link ? ' ' : null}
+          {link ? (
+            <Text style={styles.linkText} onPress={link.onPress} accessibilityRole="link">
+              {link.label}
+            </Text>
+          ) : null}
+        </Text>
+      ) : null}
+      {action ? (
+        <View style={[styles.actionRow, { paddingHorizontal: DS_SPACING[800] }]}>
+          <Pressable
+            style={({ pressed }) => [styles.actionButton, pressed && styles.actionButtonPressed]}
+            // Pads the compact text button's visual ~26px height out to the 44pt touch-target minimum.
+            hitSlop={10}
+            onPress={action.onPress}
+            accessibilityRole="button"
+            accessibilityLabel={action.label}
+          >
+            <Text style={[styles.actionLabel, { color: contentTextColor }]}>{action.label}</Text>
+          </Pressable>
+        </View>
+      ) : null}
+    </>
+  );
+
+  if (onPress) {
+    return (
+      <Pressable
+        style={[styles.calloutContainer, { backgroundColor: bg }, style]}
+        onPress={onPress}
+        accessibilityRole="button"
+        accessibilityLabel={title}
+      >
+        {({ pressed }) => body(pressed)}
+      </Pressable>
+    );
+  }
+
+  return (
+    <View style={[styles.calloutContainer, { backgroundColor: bg }, style]}>{body(false)}</View>
+  );
+}
+
+const styles = StyleSheet.create({
+  actionRow: {
+    flexDirection: 'row',
+    justifyContent: 'flex-end',
+    marginTop: DS_SPACING[400],
+  },
+  actionButton: {
+    borderRadius: DS_RADIUS.xs,
+    paddingVertical: DS_SPACING[200],
+    paddingHorizontal: DS_SPACING[600],
+  },
+  actionButtonPressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+  actionLabel: {
+    ...DS_TYPOGRAPHY.labelSm,
+  },
+  // Was undistinguished from the surrounding description text (just inherited its color via
+  // nested-Text color inheritance) — underline alone with no color difference is easy to miss at a
+  // glance and gives nothing to fall back on if the underline is ever dropped.
+  linkText: {
+    textDecorationLine: 'underline',
+    color: DS_SEMANTIC.text.link,
+  },
+  // Callout: the header carries the top + horizontal padding so the pressed state fills it; the
+  // bottom padding lives on the container (constant) so nothing jumps when toggling — only the
+  // description mounts/unmounts. overflow:hidden keeps the rounded corners.
+  calloutContainer: {
+    borderRadius: DS_RADIUS.medium,
+    width: '100%',
+    overflow: 'hidden',
+    paddingBottom: DS_SPACING[800],
+  },
+  headerRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: DS_SPACING[400],
+    paddingTop: DS_SPACING[800],
+    paddingHorizontal: DS_SPACING[800],
+  },
+  title: {
+    ...DS_TYPOGRAPHY.labelSm,
+    color: DS_SEMANTIC.text.regular,
+    marginBottom: DS_SPACING[200],
+  },
+  titleFlex: {
+    flex: 1,
+  },
+  description: {
+    ...DS_TYPOGRAPHY.bodySm,
+    color: DS_SEMANTIC.text.regular,
+  },
+  descriptionPad: {
+    // Start-aligns with the title: headerRow padding (800) + icon + gap (400). Logical start/end
+    // (not left/right) so the indent follows the icon+title when the layout mirrors in RTL.
+    paddingStart: DS_SPACING[800] + DS_ICON_SIZE.xs + DS_SPACING[400],
+    paddingEnd: DS_SPACING[800],
+    paddingTop: DS_SPACING[200],
+  },
+  // Translucent pressed overlay — sits above the banner bg so the tinted bg shows through.
+  pressOverlay: {
+    ...StyleSheet.absoluteFillObject,
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+    borderRadius: DS_RADIUS.medium,
+  },
+  // Collapsible description — clips the animated height; the child is pinned absolute (except on
+  // its very first in-flow measuring pass) so shrinking the parent never re-measures/corrupts it.
+  collapseClip: {
+    overflow: 'hidden',
+    width: '100%',
+  },
+  collapseHidden: {
+    height: 0,
+  },
+  collapseAbsolute: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: 0,
+  },
+});

package/starter-kit/components/Banner/Banner.types.ts

@@ -0,0 +1,38 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../../icons';
+
+export type BannerVariant = 'neutral' | 'info' | 'positive' | 'warning' | 'negative';
+
+export interface BannerProps {
+  /** Semantic color scheme. */
+  variant?: BannerVariant;
+  /** Header text. */
+  title?: string;
+  /** Body text. */
+  description?: string;
+  /** When true, the header row (title + chevron) toggles the description open/closed. */
+  collapsible?: boolean;
+  /** Initial expanded state when collapsible. Defaults to true (description shown). */
+  defaultExpanded?: boolean;
+  /** Override the variant background color. */
+  backgroundColor?: string;
+  /** Makes the whole banner tappable, with a pressed state — the tap target is the whole card. */
+  onPress?: () => void;
+  /** Trailing icon in the header, right-aligned (e.g. 'chevron-right'). */
+  trailingIcon?: IconName;
+  /** Override the icon/text color (defaults to the variant's emphasis color). */
+  textColor?: string;
+  /** Override the leading icon for the standard callout layout. */
+  icon?: IconName;
+  /** Inline tappable link appended to the description text. */
+  link?: {
+    label: string;
+    onPress: () => void;
+  };
+  /** Action button rendered below the description, right-aligned. */
+  action?: {
+    label: string;
+    onPress: () => void;
+  };
+  style?: StyleProp<ViewStyle>;
+}

package/starter-kit/components/Banner/index.ts

@@ -0,0 +1,2 @@
+export { Banner } from './Banner';
+export type { BannerProps, BannerVariant } from './Banner.types';

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

@@ -0,0 +1,77 @@
+import React, { useState } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { Button } from '../Button';
+import { Dock } from '../Dock';
+import { TopNav } from '../TopNav';
+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: {},
+  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 [visible, setVisible] = useState(false);
+  return (
+    <PhoneFrame>
+      {!visible && <Button label="Open sheet" onPress={() => setVisible(true)} />}
+      <BottomSheet
+        visible={visible}
+        onDismiss={() => setVisible(false)}
+        header={
+          <TopNav
+            title="Trip details"
+            trailing={
+              <Button
+                variant="secondary"
+                size="small"
+                showIcon
+                showLabel={false}
+                iconName="clear"
+                accessibilityLabel="Close"
+                onPress={() => setVisible(false)}
+              />
+            }
+          />
+        }
+        footer={
+          <Dock>
+            <Button label="Confirm" onPress={() => setVisible(false)} />
+          </Dock>
+        }
+      >
+        <View style={styles.sheetContent}>
+          <Text style={styles.cardTitle}>Uptown & 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>
+        </View>
+      </BottomSheet>
+    </PhoneFrame>
+  );
+}
+
+export default defineCatalogPage({
+  component: 'BottomSheet',
+  group: 'Navigation',
+  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 />,
+});