@krapwoo/ds-viewer 0.1.0 → 0.2.0

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

@@ -0,0 +1,68 @@
+import React from 'react';
+import { Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Card } from './Card';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  cardTitle: { ...DS_TYPOGRAPHY.labelMd, color: DS_SEMANTIC.text.regular },
+  cardBody: { ...DS_TYPOGRAPHY.bodySm, color: DS_SEMANTIC.text.muted, marginTop: DS_SPACING[200] },
+});
+
+export default defineCatalogPage({
+  component: 'Card',
+  group: 'Surfaces',
+  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.',
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'default',
+        name: 'Default',
+        node: (
+          <Card>
+            <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
+            <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min</Text>
+          </Card>
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'plain',
+        name: 'Plain',
+        node: (
+          <Card>
+            <Text style={styles.cardTitle}>Uptown & The Bronx</Text>
+            <Text style={styles.cardBody}>Next train in 4 min · every 6–8 min</Text>
+          </Card>
+        ),
+      },
+      {
+        key: 'pressable',
+        name: 'Pressable',
+        node: (
+          <Card onPress={() => {}}>
+            <Text style={styles.cardTitle}>Crosstown Bus M14</Text>
+            <Text style={styles.cardBody}>Tap to view live arrivals</Text>
+          </Card>
+        ),
+      },
+      {
+        key: 'disabled',
+        name: 'Disabled',
+        node: (
+          <Card onPress={() => {}} disabled>
+            <Text style={styles.cardTitle}>Franklin Ave Shuttle</Text>
+            <Text style={styles.cardBody}>Temporarily unavailable</Text>
+          </Card>
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,133 @@
+import React, { type ReactNode } from 'react';
+import {
+  View,
+  Pressable,
+  StyleSheet,
+  type StyleProp,
+  type ViewStyle,
+  type AccessibilityState,
+} from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS, DS_SPACING, DS_SHADOW } from '../../tokens';
+
+// Dev-only fill for the Figma slot placeholders (shown when no `children` are passed). Deliberately
+// vivid so it always reads as scaffolding, never as a real surface — not a themed token.
+const DEV_PLACEHOLDER_BG = '#f4c3ff';
+
+interface CardBaseProps {
+  /** Card content. */
+  children?: ReactNode;
+  /** Figma slot visibility toggles — prefer `children` for real content. */
+  showSlot1?: boolean;
+  showSlot2?: boolean;
+  showSlot3?: boolean;
+  showSlot4?: boolean;
+  showSlot5?: boolean;
+  accessibilityLabel?: string;
+  accessibilityState?: AccessibilityState;
+  style?: StyleProp<ViewStyle>;
+}
+
+// `disabled` only means something on a pressable card — a plain (non-`onPress`) card can't be
+// disabled, so that combination is a type error here instead of a silently-ignored prop.
+export type CardProps =
+  | (CardBaseProps & {
+      /** Makes the whole card a tappable button. */
+      onPress: () => void;
+      /** Only valid on a pressable card. */
+      disabled?: boolean;
+    })
+  | (CardBaseProps & { onPress?: undefined; disabled?: undefined });
+
+/**
+ * The primary content surface: a rounded white card with a soft resting shadow. Pass `children`
+ * for real content, or `onPress` to make the whole card a tappable button (pressed + focus states).
+ */
+export function Card({
+  children,
+  showSlot1 = true,
+  showSlot2 = true,
+  showSlot3 = true,
+  showSlot4 = true,
+  showSlot5 = true,
+  onPress,
+  disabled = false,
+  accessibilityLabel,
+  accessibilityState,
+  style,
+}: CardProps) {
+  const [focused, setFocused] = React.useState(false);
+  const cardStyle = ({ pressed }: { pressed: boolean }) => [
+    styles.card,
+    pressed && !disabled && styles.cardOnTap,
+    focused && !disabled && styles.cardFocused,
+    disabled && styles.cardDisabled,
+    style,
+  ];
+
+  const inner = children ?? renderSlots(showSlot1, showSlot2, showSlot3, showSlot4, showSlot5);
+
+  if (onPress) {
+    return (
+      <Pressable
+        onPress={onPress}
+        disabled={disabled}
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel}
+        accessibilityState={{ ...accessibilityState, disabled }}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        style={cardStyle}
+      >
+        {inner}
+      </Pressable>
+    );
+  }
+
+  return (
+    <View
+      style={[styles.card, style]}
+      accessible={!!accessibilityLabel}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityState={accessibilityState}
+    >
+      {inner}
+    </View>
+  );
+}
+
+function renderSlots(
+  showSlot1: boolean,
+  showSlot2: boolean,
+  showSlot3: boolean,
+  showSlot4: boolean,
+  showSlot5: boolean,
+) {
+  const slots = [showSlot1, showSlot2, showSlot3, showSlot4, showSlot5].filter(Boolean);
+  return slots.map((_, index) => <View key={index} style={styles.placeholder} />);
+}
+
+const styles = StyleSheet.create({
+  card: {
+    backgroundColor: DS_SEMANTIC.surface.white,
+    borderRadius: DS_RADIUS.medium,
+    padding: DS_SPACING[800],
+    width: '100%',
+    ...DS_SHADOW.resting,
+  },
+  cardOnTap: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+  cardFocused: {
+    borderWidth: 2,
+    borderColor: DS_SEMANTIC.interaction.focused,
+  },
+  cardDisabled: {
+    opacity: DS_SEMANTIC.interaction.disabledOpacity,
+  },
+  placeholder: {
+    height: 59,
+    backgroundColor: DEV_PLACEHOLDER_BG,
+    borderRadius: DS_RADIUS.xs,
+    width: '100%',
+  },
+});

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

@@ -0,0 +1,2 @@
+export { Card } from './Card';
+export type { CardProps } from './Card';

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

@@ -0,0 +1,28 @@
+import React, { useState } from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Checkbox } from './Checkbox';
+
+function CheckboxDemo() {
+  const [checked, setChecked] = useState(true);
+  return <Checkbox checked={checked} onChange={setChecked} label="Remember this trip" />;
+}
+
+export default defineCatalogPage({
+  component: 'Checkbox',
+  group: 'Controls',
+  specimenSize: 'compact',
+  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.',
+  variants: {
+    items: [{ key: 'default', name: 'Default (tap to toggle)', node: <CheckboxDemo /> }],
+  },
+  states: {
+    items: [
+      { key: 'unchecked', name: 'Unchecked', node: <Checkbox checked={false} onChange={() => {}} label="Remember this trip" /> },
+      { key: 'checked', name: 'Checked', node: <Checkbox checked={true} onChange={() => {}} label="Remember this trip" /> },
+      { key: 'no-label', name: 'No label', node: <Checkbox checked={true} onChange={() => {}} /> },
+      { key: 'disabled', name: 'Disabled', node: <Checkbox checked={true} onChange={() => {}} disabled label="Remember this trip" /> },
+    ],
+  },
+});

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

@@ -0,0 +1,104 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { Pressable, Text, View, Animated, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_TYPOGRAPHY, DS_A11Y_MIN_TOUCH_TARGET, DS_MOTION_DURATION, DS_ICON_SIZE } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import { usePressScale } from '../Radio/usePressScale';
+
+export interface CheckboxProps {
+  /** Whether the box is checked. */
+  checked: boolean;
+  /** Called with the new value on tap. */
+  onChange: (checked: boolean) => void;
+  /** Optional inline label rendered to the right of the box. */
+  label?: string;
+  /** Non-interactive, dimmed. */
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+const BOX_SIZE = 20;
+const ANIM_MS = DS_MOTION_DURATION.fast;
+// Pads the tappable area out to the accessibility minimum without growing the visual box — same
+// reasoning as Button's own `iconOnlyHitSlop` and Radio's `HIT_SLOP`.
+const HIT_SLOP = Math.max(0, Math.ceil((DS_A11Y_MIN_TOUCH_TARGET - BOX_SIZE) / 2));
+
+/** A square selection control — the box fills with the accent colour and the checkmark pops in
+ *  (scale + opacity) when checked, and back out when unchecked — kept JS-driven
+ *  (`useNativeDriver: false`) since the box's own border/background colour animate too. The box
+ *  also grows slightly while pressed, before release — the same tactile feedback Radio and Switch
+ *  already give, so all three selection controls feel consistent. */
+export function Checkbox({ checked, onChange, label, disabled = false, style }: CheckboxProps) {
+  const checkAnim = useRef(new Animated.Value(checked ? 1 : 0)).current;
+  const { pressScale, onPressIn, onPressOut } = usePressScale(disabled);
+  const [focused, setFocused] = useState(false);
+
+  useEffect(() => {
+    const anim = Animated.timing(checkAnim, { toValue: checked ? 1 : 0, duration: ANIM_MS, useNativeDriver: false });
+    anim.start();
+    return () => anim.stop();
+  }, [checked, checkAnim]);
+
+  const boxBackground = checkAnim.interpolate({ inputRange: [0, 1], outputRange: ['rgba(0,0,0,0)', DS_SEMANTIC.emphasis.info] });
+  const boxBorderColor = checkAnim.interpolate({ inputRange: [0, 1], outputRange: [DS_SEMANTIC.border.dark, DS_SEMANTIC.emphasis.info] });
+
+  return (
+    <Pressable
+      onPress={() => !disabled && onChange(!checked)}
+      onPressIn={onPressIn}
+      onPressOut={onPressOut}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      disabled={disabled}
+      accessibilityRole="checkbox"
+      accessibilityState={{ checked, disabled }}
+      accessibilityLabel={label}
+      hitSlop={HIT_SLOP}
+      style={[styles.row, disabled && styles.disabled, style]}
+    >
+      <Animated.View style={[styles.box, { backgroundColor: boxBackground, borderColor: boxBorderColor, transform: [{ scale: pressScale }] }]}>
+        <Animated.View style={{ opacity: checkAnim, transform: [{ scale: checkAnim }] }}>
+          <Icon name="check" size={DS_ICON_SIZE.xs} color={DS_SEMANTIC.surface.white} strokeWidth={3} />
+        </Animated.View>
+        {/* Keyboard-focus ring — the same interaction.focused treatment Button/Pill use, drawn as a
+            zero-layout absolute overlay around the box so focusing never shifts layout. */}
+        {focused && !disabled && <View pointerEvents="none" style={styles.focusRing} />}
+      </Animated.View>
+      {!!label && <Text style={styles.label}>{label}</Text>}
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[400],
+  },
+  box: {
+    width: BOX_SIZE,
+    height: BOX_SIZE,
+    borderRadius: DS_RADIUS.xs,
+    borderWidth: 2,
+    borderColor: DS_SEMANTIC.border.dark,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  label: {
+    ...DS_TYPOGRAPHY.bodyMd,
+    color: DS_SEMANTIC.text.regular,
+  },
+  disabled: {
+    opacity: DS_SEMANTIC.interaction.disabledOpacity,
+  },
+  // 2px air + 2px ring outside the box, radius grown by the same offset to stay concentric.
+  focusRing: {
+    position: 'absolute',
+    top: -4,
+    bottom: -4,
+    left: -4,
+    right: -4,
+    borderWidth: 2,
+    borderColor: DS_SEMANTIC.interaction.focused,
+    borderRadius: DS_RADIUS.xs + 4,
+  },
+});

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

@@ -0,0 +1,2 @@
+export { Checkbox } from './Checkbox';
+export type { CheckboxProps } from './Checkbox';

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

@@ -0,0 +1,41 @@
+import React, { useState } from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { Button } from '../Button';
+import { ButtonGroup } from '../ButtonGroup';
+import { Dialog } from './Dialog';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  cardTitle: { ...DS_TYPOGRAPHY.labelMd, color: DS_SEMANTIC.text.regular },
+  cardBody: { ...DS_TYPOGRAPHY.bodySm, color: DS_SEMANTIC.text.muted, marginTop: DS_SPACING[200] },
+  dialogActions: { marginTop: DS_SPACING[800] },
+});
+
+function DialogDemo() {
+  const [visible, setVisible] = useState(false);
+  return (
+    <PhoneFrame>
+      {!visible && <Button label="Open dialog" onPress={() => setVisible(true)} />}
+      <Dialog visible={visible} onDismiss={() => setVisible(false)}>
+        <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={() => setVisible(false)} />
+            <Button label="Delete" onPress={() => setVisible(false)} />
+          </ButtonGroup>
+        </View>
+      </Dialog>
+    </PhoneFrame>
+  );
+}
+
+export default defineCatalogPage({
+  component: 'Dialog',
+  group: 'Overlays',
+  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 />,
+});

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

@@ -0,0 +1,82 @@
+import React, { type ReactNode, useEffect, useRef, useState } from 'react';
+import { View, Pressable, Animated, Easing, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_SHADOW, DS_MOTION_DURATION, DS_MOTION_EASING } from '../../tokens';
+
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+
+export interface DialogProps {
+  /** Whether the dialog (and its backdrop) are mounted and shown. */
+  visible: boolean;
+  /** Called when the backdrop is tapped — the dialog doesn't close itself; the caller decides. */
+  onDismiss: () => void;
+  /** The dialog's content. */
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * A card centred on screen over a dismissible backdrop — fades and scales in, distinct from
+ * {@link BottomSheet}'s bottom-anchored slide. Named `Dialog` (not `Modal`) to avoid shadowing React
+ * Native's own built-in `Modal`. Like BottomSheet, not portaled through RN's `Modal` — a plain
+ * absolutely-positioned overlay that fills whichever parent View hosts it.
+ */
+export function Dialog({ visible, onDismiss, children, style }: DialogProps) {
+  const progress = useRef(new Animated.Value(0)).current;
+  const [mounted, setMounted] = useState(visible);
+
+  useEffect(() => {
+    if (visible) setMounted(true);
+    const anim = Animated.timing(progress, {
+      toValue: visible ? 1 : 0,
+      duration: visible ? DS_MOTION_DURATION.base : DS_MOTION_DURATION.fast,
+      // `decelerate` — something entering the screen, per DS_MOTION_EASING_USE.
+      easing: Easing.bezier(...DS_MOTION_EASING.decelerate),
+      useNativeDriver: false,
+    });
+    anim.start(({ finished }) => {
+      if (finished && !visible) setMounted(false);
+    });
+    return () => anim.stop();
+  }, [visible, progress]);
+
+  if (!mounted) return null;
+
+  const scale = progress.interpolate({ inputRange: [0, 1], outputRange: [0.92, 1] });
+
+  return (
+    <View style={styles.overlay} pointerEvents={visible ? 'auto' : 'none'}>
+      <AnimatedPressable
+        style={[styles.backdrop, { opacity: progress }]}
+        onPress={onDismiss}
+        accessibilityRole="button"
+        accessibilityLabel="Dismiss"
+      />
+      <Animated.View
+        style={[styles.card, style, { opacity: progress, transform: [{ scale }] }]}
+        // Contain assistive-tech focus while open (iOS) — without this, content behind the scrim
+        // stays reachable by screen readers even though it's visually blocked.
+        accessibilityViewIsModal
+      >
+        {children}
+      </Animated.View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: DS_SPACING[800],
+  },
+  backdrop: { ...StyleSheet.absoluteFillObject, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
+  card: {
+    width: '100%',
+    maxWidth: 400,
+    backgroundColor: DS_SEMANTIC.surface.white,
+    borderRadius: DS_RADIUS.large,
+    padding: DS_SPACING[800],
+    ...DS_SHADOW.card,
+  },
+});

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

@@ -0,0 +1,2 @@
+export { Dialog } from './Dialog';
+export type { DialogProps } from './Dialog';

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

@@ -0,0 +1,35 @@
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Divider } from './Divider';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  cardBody: { ...DS_TYPOGRAPHY.bodySm, color: DS_SEMANTIC.text.muted, marginTop: DS_SPACING[200] },
+  dividerDemo: { width: '100%', gap: DS_SPACING[400] },
+});
+
+export default defineCatalogPage({
+  component: 'Divider',
+  group: 'Layout',
+  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
+  // whole component, shown here between two lines of content to demonstrate real placement.
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'default',
+        name: 'Default',
+        node: (
+          <View style={styles.dividerDemo}>
+            <Text style={styles.cardBody}>Section one</Text>
+            <Divider />
+            <Text style={styles.cardBody}>Section two</Text>
+          </View>
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,20 @@
+import React from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC } from '../../tokens';
+
+export interface DividerProps {
+  style?: StyleProp<ViewStyle>;
+}
+
+/** A 1px hairline separator at the divider token colour. */
+export function Divider({ style }: DividerProps) {
+  return <View style={[styles.line, style]} />;
+}
+
+const styles = StyleSheet.create({
+  line: {
+    height: 1,
+    width: '100%',
+    backgroundColor: DS_SEMANTIC.element.divider,
+  },
+});

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

@@ -0,0 +1,2 @@
+export { Divider } from './Divider';
+export type { DividerProps } from './Divider';

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

@@ -0,0 +1,71 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Button } from '../Button';
+import { Dock } from './Dock';
+
+export default defineCatalogPage({
+  component: 'Dock',
+  group: 'Navigation',
+  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,
+  // at its max button count; the caption/count variations live under "States".
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'default',
+        name: 'Default',
+        node: (
+          <Dock caption="3 stops · 24 min total">
+            <Button label="Start trip" onPress={() => {}} />
+            <Button label="Save for later" variant="secondary" onPress={() => {}} />
+            <Button label="Share" variant="tertiary" onPress={() => {}} />
+          </Dock>
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'no-caption',
+        name: 'No caption',
+        node: (
+          <Dock>
+            <Button label="Confirm" onPress={() => {}} />
+            <Button label="Cancel" variant="tertiary" onPress={() => {}} />
+          </Dock>
+        ),
+      },
+      {
+        key: 'caption-hidden',
+        name: 'Caption hidden',
+        node: (
+          <Dock caption="3 stops · 24 min total" showCaption={false}>
+            <Button label="Start trip" onPress={() => {}} />
+          </Dock>
+        ),
+      },
+      {
+        key: 'single-button',
+        name: 'Single button',
+        node: (
+          <Dock>
+            <Button label="Got it" onPress={() => {}} />
+          </Dock>
+        ),
+      },
+      {
+        key: 'elevated',
+        name: 'Elevated',
+        node: (
+          <Dock elevated caption="3 stops · 24 min total">
+            <Button label="Start trip" onPress={() => {}} />
+          </Dock>
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,58 @@
+import React, { type ReactNode } from 'react';
+import { View, Text, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY, DS_SHADOW } from '../../tokens';
+
+const MAX_BUTTONS = 3;
+const TOP_PAD = DS_SPACING[800];
+const BOTTOM_PAD = DS_SPACING[400];
+const H_PAD = DS_SPACING[800];
+
+export interface DockProps {
+  /** Up to three full-width Button elements, stacked vertically. Extra children are dropped. */
+  children: ReactNode;
+  /** Small caption shown above the top button — e.g. a trip summary. */
+  caption?: ReactNode;
+  /** Hides the caption row without unmounting `caption`. @default true */
+  showCaption?: boolean;
+  /** Shows the upward-cast `bottomSheet` shadow, visually separating the Dock from scrollable
+   *  content sitting above it. Off by default — turn it on when that content actually overflows
+   *  (is scrolled/scrollable), since Dock has no visibility into sibling content on its own; the
+   *  caller (e.g. BottomSheet, which measures its own content area) decides when that's true.
+   *  @default false */
+  elevated?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * 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 that can be shown or
+ * hidden independently of whether `caption` content is passed. Not absolutely positioned itself —
+ * the screen composing this decides whether to pin it (`position: 'absolute', bottom: 0`) or lay
+ * it out inline at the end of a flex column, which also keeps it usable inside a bounded container
+ * like this catalog's own example cards.
+ */
+export function Dock({ children, caption, showCaption = true, elevated = false, style }: DockProps) {
+  const insets = useSafeAreaInsets();
+  const buttons = React.Children.toArray(children).slice(0, MAX_BUTTONS);
+
+  return (
+    <View style={[styles.dock, elevated && styles.dockElevated, { paddingBottom: BOTTOM_PAD + insets.bottom }, style]}>
+      {caption != null && showCaption && <Text style={styles.caption}>{caption}</Text>}
+      <View style={styles.buttons}>{buttons}</View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  dock: {
+    width: '100%',
+    backgroundColor: DS_SEMANTIC.surface.white,
+    paddingTop: TOP_PAD,
+    paddingHorizontal: H_PAD,
+    gap: DS_SPACING[300],
+  },
+  dockElevated: { ...DS_SHADOW.bottomSheet },
+  caption: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted, textAlign: 'center' },
+  buttons: { gap: DS_SPACING[400] },
+});

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

@@ -0,0 +1,2 @@
+export { Dock } from './Dock';
+export type { DockProps } from './Dock';