@krapwoo/ds-viewer 0.1.1 → 0.2.0

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

@@ -0,0 +1,113 @@
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { Button } from './Button';
+import type { ButtonVariant } from './Button.types';
+import { DS_SEMANTIC } from '../../tokens';
+
+const styles = StyleSheet.create({
+  // `white` is documented as "solid light (for dark/photo backgrounds)" — invisible on this
+  // catalog's own white card, so it needs a dark backdrop to read as a real button.
+  darkBackdrop: {
+    backgroundColor: DS_SEMANTIC.text.regular,
+    borderRadius: 12,
+    padding: 16,
+    alignItems: 'center',
+  },
+});
+
+// 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,
+  };
+}
+
+// Button: Variant × State. `white` keeps the dark backdrop its variant requires.
+const BUTTON_COMPARISON = grid(
+  'Variant',
+  'State',
+  [
+    { key: 'primary', label: 'Primary' },
+    { key: 'secondary', label: 'Secondary' },
+    { key: 'tertiary', label: 'Tertiary' },
+    { key: 'white', label: 'White' },
+    { key: 'ghost', label: 'Ghost' },
+  ],
+  [
+    { key: 'default', label: 'Default' },
+    { key: 'disabled', label: 'Disabled' },
+    { key: 'loading', label: 'Loading' },
+  ],
+  (row, column) => {
+    const button = (
+      <Button
+        label="Continue"
+        variant={row as ButtonVariant}
+        disabled={column === 'disabled'}
+        loading={column === 'loading'}
+        onPress={() => {}}
+      />
+    );
+    return row === 'white' ? <View style={styles.darkBackdrop}>{button}</View> : button;
+  },
+);
+
+export default defineCatalogPage({
+  component: 'Button',
+  group: 'Actions',
+  comparison: BUTTON_COMPARISON,
+  description:
+    'The primary tap target. Five visual weights, three sizes, optional leading/trailing icon, plus loading and icon-only modes.',
+  whenToUse: 'An action — something happens on tap. For a tappable chip that just flips a persistent selected state, use Pill instead.',
+  a11y: 'Renders a Pressable with accessibilityRole="button"; pass accessibilityLabel for icon-only buttons where the label is hidden.',
+  variants: {
+    items: [
+      { key: 'primary', name: 'Primary', props: { variant: 'primary', size: 'large' }, node: <Button label="Primary" variant="primary" onPress={() => {}} /> },
+      { key: 'secondary', name: 'Secondary', props: { variant: 'secondary', size: 'large' }, node: <Button label="Secondary" variant="secondary" onPress={() => {}} /> },
+      { key: 'tertiary', name: 'Tertiary', props: { variant: 'tertiary', size: 'large' }, node: <Button label="Tertiary" variant="tertiary" onPress={() => {}} /> },
+      {
+        key: 'white',
+        name: 'White',
+        props: { variant: 'white', size: 'large' },
+        node: (
+          <View style={styles.darkBackdrop}>
+            <Button label="White" variant="white" onPress={() => {}} />
+          </View>
+        ),
+      },
+      { key: 'ghost', name: 'Ghost', props: { variant: 'ghost', size: 'large' }, node: <Button label="Ghost" variant="ghost" onPress={() => {}} /> },
+    ],
+  },
+  states: {
+    items: [
+      { key: 'with-icon', name: 'With icon', props: { iconPosition: 'leading' }, node: <Button label="Add stop" showIcon iconName="add" onPress={() => {}} /> },
+      {
+        key: 'trailing-icon',
+        name: 'Trailing icon',
+        props: { iconPosition: 'trailing' },
+        node: <Button label="Continue" showIcon iconName="chevron-right" iconPosition="trailing" onPress={() => {}} />,
+      },
+      { key: 'icon-only', name: 'Icon-only', node: <Button label="Add stop" showIcon showLabel={false} iconName="add" onPress={() => {}} /> },
+      { key: 'loading', name: 'Loading', node: <Button label="Loading" loading onPress={() => {}} /> },
+      { key: 'disabled', name: 'Disabled', node: <Button label="Disabled" disabled onPress={() => {}} /> },
+      { key: 'full-width', name: 'Full width', fill: true, node: <Button label="Confirm trip" fullWidth onPress={() => {}} /> },
+      { key: 'medium', name: 'Medium size', props: { size: 'medium' }, node: <Button label="Add stop" size="medium" onPress={() => {}} /> },
+      { key: 'small', name: 'Small size', props: { size: 'small' }, node: <Button label="Add stop" size="small" onPress={() => {}} /> },
+    ],
+  },
+});

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

@@ -0,0 +1,173 @@
+import React, { useMemo, useState } from 'react';
+import { Pressable, Text, View, StyleSheet, type ViewStyle, type TextStyle } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS, DS_SPACING, DS_TYPOGRAPHY, DS_FONT_WEIGHT, DS_A11Y_MIN_TOUCH_TARGET } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import { Loading } from '../Loading';
+import type { ButtonProps, ButtonVariant, ButtonSize } from './Button.types';
+
+type SizeTokens = { paddingVertical: number; paddingHorizontal: number; fontSize: number; lineHeight: number; iconSize: number };
+
+// The icon size tracks the label's line box so the icon stays proportionate to the text at every size.
+const SIZE_TOKENS: Record<ButtonSize, SizeTokens> = {
+  large:  { paddingVertical: DS_SPACING[800], paddingHorizontal: DS_SPACING[1200], fontSize: DS_TYPOGRAPHY.labelMd.fontSize, lineHeight: 20, iconSize: 20 },
+  medium: { paddingVertical: DS_SPACING[600], paddingHorizontal: DS_SPACING[800],  fontSize: DS_TYPOGRAPHY.labelSm.fontSize, lineHeight: 18, iconSize: 18 },
+  small:  { paddingVertical: DS_SPACING[400], paddingHorizontal: DS_SPACING[800],  fontSize: DS_TYPOGRAPHY.labelXs.fontSize, lineHeight: 16, iconSize: 16 },
+};
+
+type VariantStyles = { container: ViewStyle; containerPressed: ViewStyle; containerDisabled: ViewStyle; label: TextStyle };
+
+const VARIANT_STYLES: Record<ButtonVariant, VariantStyles> = {
+  primary: {
+    container: { backgroundColor: DS_SEMANTIC.text.regular },
+    containerPressed: { backgroundColor: DS_SEMANTIC.emphasis.neutral },
+    containerDisabled: { backgroundColor: DS_SEMANTIC.border.light },
+    label: { color: DS_SEMANTIC.text.inverse },
+  },
+  secondary: {
+    container: { backgroundColor: DS_SEMANTIC.surface.recessed },
+    // Not DS_SEMANTIC.interaction.pressed/disabledOpacity — this variant's resting background is
+    // already the translucent surface.recessed overlay, so its pressed/disabled states are their own
+    // tuned darker/lighter versions of that same overlay (recessedPressed/recessedDisabled) rather
+    // than a second, independently-chosen overlay stacked on top.
+    containerPressed: { backgroundColor: DS_SEMANTIC.surface.recessedPressed },
+    containerDisabled: { backgroundColor: DS_SEMANTIC.surface.recessedDisabled },
+    label: { color: DS_SEMANTIC.text.regular },
+  },
+  tertiary: {
+    container: { backgroundColor: 'transparent' },
+    containerPressed: { backgroundColor: DS_SEMANTIC.interaction.pressed },
+    containerDisabled: { backgroundColor: 'transparent' },
+    label: { color: DS_SEMANTIC.text.regular },
+  },
+  white: {
+    container: { backgroundColor: DS_SEMANTIC.surface.white },
+    containerPressed: { backgroundColor: DS_SEMANTIC.surface.main },
+    containerDisabled: { backgroundColor: DS_SEMANTIC.surface.muted },
+    label: { color: DS_SEMANTIC.text.regular },
+  },
+  ghost: {
+    container: { backgroundColor: 'transparent' },
+    containerPressed: { backgroundColor: DS_SEMANTIC.interaction.pressed },
+    containerDisabled: { backgroundColor: 'transparent' },
+    label: { color: DS_SEMANTIC.text.regular },
+  },
+};
+
+function ButtonImpl({
+  label = 'Button',
+  variant = 'primary',
+  size = 'large',
+  showIcon = false,
+  iconName = 'add',
+  iconPosition = 'leading',
+  showLabel = true,
+  onPress,
+  disabled = false,
+  loading = false,
+  fullWidth = false,
+  style,
+  textStyle,
+  testID,
+  accessibilityLabel,
+}: ButtonProps) {
+  const variantStyle = VARIANT_STYLES[variant];
+  const isGhost = variant === 'ghost';
+  const isIconOnly = showIcon && !showLabel;
+  const sizeTokens = SIZE_TOKENS[size];
+  const isDisabled = disabled || loading || !onPress;
+  // Ghost reads text-first, so its icon is sized to the label's line box rather than the larger standard.
+  const renderedIconSize = isGhost ? Math.min(sizeTokens.iconSize, sizeTokens.lineHeight) : sizeTokens.iconSize;
+  const iconColor = variant === 'primary' ? DS_SEMANTIC.text.inverse : DS_SEMANTIC.text.regular;
+  const spinnerColor = iconColor;
+  // Match the loader to the resting content height so swapping in the spinner never changes the height.
+  const loaderSize = Math.max(showIcon ? sizeTokens.iconSize : 0, showLabel ? sizeTokens.lineHeight : 0) || sizeTokens.iconSize;
+  // small/medium icon-only buttons render under the touch-target minimum — pad the tap area out
+  // with hitSlop rather than growing the visual button itself.
+  const iconOnlyVisualSize = sizeTokens.paddingVertical * 2 + sizeTokens.iconSize;
+  const iconOnlyHitSlop = Math.max(0, Math.ceil((DS_A11Y_MIN_TOUCH_TARGET - iconOnlyVisualSize) / 2));
+  // Ghost has zero padding (`baseGhost`) — its visual height is just the content's own line box, so
+  // every ghost button (label-only or icon-only alike — the icon is itself capped to this same
+  // line-box height, see `renderedIconSize` above) needs hitSlop to reach the touch-target minimum,
+  // not just the icon-only case the other variants need it for.
+  const ghostHitSlop = Math.max(0, Math.ceil((DS_A11Y_MIN_TOUCH_TARGET - sizeTokens.lineHeight) / 2));
+
+  const [focused, setFocused] = useState(false);
+  const accessibilityState = useMemo(() => ({ disabled: isDisabled, busy: loading }), [isDisabled, loading]);
+
+  const renderInner = () => (
+    <View style={[styles.content, isGhost && styles.contentGhost, disabled && styles.contentDisabled]}>
+      {showIcon && iconPosition === 'leading' && (
+        <Icon name={iconName} size={renderedIconSize} color={iconColor} />
+      )}
+      {showLabel && (
+        <Text
+          style={[styles.label, { fontSize: sizeTokens.fontSize, lineHeight: sizeTokens.lineHeight }, variantStyle.label, textStyle]}
+        >
+          {label}
+        </Text>
+      )}
+      {showIcon && iconPosition === 'trailing' && (
+        <Icon name={iconName} size={renderedIconSize} color={iconColor} />
+      )}
+    </View>
+  );
+
+  return (
+    <Pressable
+      testID={testID}
+      onPress={onPress}
+      disabled={isDisabled}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel ?? label}
+      accessibilityState={accessibilityState}
+      hitSlop={isGhost ? ghostHitSlop : isIconOnly ? iconOnlyHitSlop : undefined}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      style={({ pressed }) => [
+        styles.base,
+        isGhost ? styles.baseGhost : {
+          paddingVertical: sizeTokens.paddingVertical,
+          paddingHorizontal: isIconOnly ? sizeTokens.paddingVertical : sizeTokens.paddingHorizontal,
+        },
+        variantStyle.container,
+        fullWidth && styles.fullWidth,
+        pressed && !isDisabled && variantStyle.containerPressed,
+        isDisabled && !loading && variantStyle.containerDisabled,
+        focused && !isDisabled && styles.focused,
+        style,
+      ]}
+    >
+      {loading ? <Loading color={spinnerColor} size={loaderSize} /> : renderInner()}
+    </Pressable>
+  );
+}
+
+/** Skips re-rendering when this button's own props are unchanged. */
+export const Button = React.memo(ButtonImpl);
+
+const styles = StyleSheet.create({
+  base: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: DS_RADIUS.round,
+    borderWidth: 2,
+    borderColor: 'transparent',
+  },
+  baseGhost: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: DS_RADIUS.small,
+    borderWidth: 0,
+    padding: 0,
+  },
+  focused: { borderColor: DS_SEMANTIC.interaction.focused },
+  fullWidth: { alignSelf: 'stretch' },
+  content: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[200] },
+  contentGhost: { gap: DS_SPACING[100] },
+  // Dims the whole content (icon + label together) so an icon-only disabled button is still visibly
+  // disabled, not just a disabled button with no label to dim.
+  contentDisabled: { opacity: DS_SEMANTIC.interaction.disabledOpacity },
+  label: { fontWeight: DS_FONT_WEIGHT.semibold, textAlign: 'center' },
+});

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

@@ -0,0 +1,52 @@
+import type { StyleProp, ViewStyle, TextStyle } from 'react-native';
+import type { IconName } from '../../icons';
+
+/** Which one this is in its screen/modal/sheet — a decision about the action's importance, not
+ *  just a visual pick:
+ *  - `primary` — *the* primary action to take on this surface (the one thing it wants you to do).
+ *    Only one per screen/modal/sheet.
+ *  - `secondary` — worth considering in context, but not the primary action.
+ *  - `tertiary` — fine if the user never notices it; a low-stakes, easy-to-skip action.
+ *  - `white` — the same weight/role as `primary`, for a dark or photo background instead of a
+ *    light one (never mix the two — pick whichever reads on the surface behind it).
+ *  - `ghost` — for an action inline within a large, word-heavy area (body text, a toast's "Undo") —
+ *    not a nav-bar icon or a standalone CTA; see TopNav's own leading/trailing slot guidance
+ *    (`size="small"`, `variant="secondary"` by default) for that case instead. */
+export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'white' | 'ghost';
+export type ButtonSize = 'large' | 'medium' | 'small';
+export type ButtonIconPosition = 'leading' | 'trailing';
+
+export interface ButtonProps {
+  /** Button text. */
+  label?: string;
+  /** Which action this is, not just a look: primary = the one main action here; secondary = worth
+   *  considering, not primary; tertiary = fine if the user skips it; white = primary on a dark/photo
+   *  bg; ghost = inline within word-heavy text, not a nav icon or standalone CTA. */
+  variant?: ButtonVariant;
+  /** Control size. */
+  size?: ButtonSize;
+  /** Show the icon named by `iconName`. */
+  showIcon?: boolean;
+  /** Which icon to render. */
+  iconName?: IconName;
+  /** Which side of the label the icon sits on. */
+  iconPosition?: ButtonIconPosition;
+  /** Hide the label (with showIcon) for an icon-only, square button. */
+  showLabel?: boolean;
+  /** Tap handler. */
+  onPress?: () => void;
+  /** Non-interactive, dimmed. */
+  disabled?: boolean;
+  /** Swaps the label for a spinner and disables presses. Turn on right after the tap that
+   *  triggered it, for as long as the background task it kicked off is still running — not a
+   *  general "busy" flag unrelated to a real in-flight action following this exact tap. */
+  loading?: boolean;
+  /** Stretch to fill the available width. Use for the main CTA(s) pinned to the bottom of a
+   *  screen/modal/sheet (e.g. inside a Dock); leave off (the default, dynamic/content-hugging
+   *  width) for a button placed within surrounding context — a card, a row, inline actions. */
+  fullWidth?: boolean;
+  style?: StyleProp<ViewStyle>;
+  textStyle?: StyleProp<TextStyle>;
+  testID?: string;
+  accessibilityLabel?: string;
+}

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

@@ -0,0 +1,2 @@
+export { Button } from './Button';
+export type { ButtonProps, ButtonVariant, ButtonSize, ButtonIconPosition } from './Button.types';

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

@@ -0,0 +1,39 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { ButtonGroup } from './ButtonGroup';
+import { Button } from '../Button';
+
+export default defineCatalogPage({
+  component: 'ButtonGroup',
+  group: 'Actions',
+  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: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'horizontal',
+        name: 'Horizontal',
+        props: { variant: 'horizontal' },
+        node: (
+          <ButtonGroup variant="horizontal">
+            <Button label="Cancel" variant="tertiary" onPress={() => {}} />
+            <Button label="Confirm" onPress={() => {}} />
+          </ButtonGroup>
+        ),
+      },
+      {
+        key: 'vertical',
+        name: 'Vertical',
+        props: { variant: 'vertical' },
+        node: (
+          <ButtonGroup variant="vertical">
+            <Button label="Start trip" onPress={() => {}} />
+            <Button label="Save for later" variant="secondary" onPress={() => {}} />
+            <Button label="Share" variant="tertiary" onPress={() => {}} />
+          </ButtonGroup>
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,84 @@
+import React, { type ReactNode } from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SPACING } from '../../tokens';
+import type { ButtonProps, ButtonVariant } from '../Button';
+
+export type ButtonGroupVariant = 'horizontal' | 'vertical';
+
+export interface ButtonGroupProps {
+  /** Which layout to use.
+   *  @default 'horizontal' */
+  variant?: ButtonGroupVariant;
+  /** Button elements. Horizontal holds up to two; vertical holds up to three. Extra children are dropped. */
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+const MAX_BUTTONS: Record<ButtonGroupVariant, number> = { horizontal: 2, vertical: 3 };
+
+// `ghost` reads as a quiet, text-only, link-like action — placed beside a "real" (filled/outlined)
+// button it reads as mismatched weight, as if one of the two isn't really a button. Every other
+// variant reads as a standalone action of comparable weight, so those are safe to group.
+const ALLOWED_VARIANTS: ButtonVariant[] = ['primary', 'secondary', 'tertiary', 'white'];
+
+/** Opt-in-style consistency check (same policy as SectionBlock's own `checkCompleteness`): every
+ *  button in a group should read as one family — same variant tier, same size, and either all
+ *  icon+label or all label-only, never a mix (a lone icon+label button beside label-only siblings
+ *  draws the eye as "the different one" instead of as an equally-weighted option). Warns in the
+ *  console rather than throwing, since a mismatch is a design inconsistency to fix, not a crash. */
+function checkConsistency(buttons: ReactNode[]): void {
+  const props = buttons
+    .filter((b): b is React.ReactElement<ButtonProps> => React.isValidElement(b))
+    .map((b) => b.props);
+  if (props.length < 2) return;
+
+  for (const p of props) {
+    if (p.variant && !ALLOWED_VARIANTS.includes(p.variant)) {
+      console.warn(
+        `[ButtonGroup] "${p.label ?? '(no label)'}" uses variant="${p.variant}" — grouped buttons should use one of ${ALLOWED_VARIANTS.join('/')}, not ${p.variant}.`,
+      );
+    }
+  }
+
+  const sizes = new Set(props.map((p) => p.size ?? 'large'));
+  if (sizes.size > 1) {
+    console.warn(`[ButtonGroup] Buttons have mismatched sizes (${[...sizes].join(', ')}) — every button in a group should use the same size.`);
+  }
+
+  // Keyed on the (showIcon, showLabel) pair, not showIcon alone — an icon-only button
+  // (showIcon + showLabel={false}) next to an icon+label one is exactly the visually-mismatched
+  // pairing this check exists to catch, and both have showIcon true.
+  const configs = new Set(
+    props.map((p) => {
+      const icon = p.showIcon ?? false;
+      const label = p.showLabel ?? true;
+      return icon && label ? 'icon+label' : icon ? 'icon-only' : 'label-only';
+    }),
+  );
+  if (configs.size > 1) {
+    console.warn(
+      `[ButtonGroup] Buttons mix configurations (${[...configs].join(', ')}) — every button in a group should use the same configuration.`,
+    );
+  }
+}
+
+/**
+ * Groups Button elements in one of two layouts:
+ *  - `horizontal` (default, up to two): auto-width, trailing-aligned — a dialog's Cancel/Confirm pair.
+ *  - `vertical` (up to three): stretched full width, stacked — 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`, which reads as a different, lower weight), the same size, and
+ * either all icon+label or all label-only, never a mix. Dev-console warns if two or more children
+ * disagree.
+ */
+export function ButtonGroup({ variant = 'horizontal', children, style }: ButtonGroupProps) {
+  const buttons = React.Children.toArray(children).slice(0, MAX_BUTTONS[variant]);
+  checkConsistency(buttons);
+  return <View style={[variant === 'vertical' ? styles.vertical : styles.horizontal, style]}>{buttons}</View>;
+}
+
+const styles = StyleSheet.create({
+  horizontal: { flexDirection: 'row', justifyContent: 'flex-end', gap: DS_SPACING[400] },
+  vertical: { flexDirection: 'column', gap: DS_SPACING[400], width: '100%' },
+});

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

@@ -0,0 +1,2 @@
+export { ButtonGroup } from './ButtonGroup';
+export type { ButtonGroupProps, ButtonGroupVariant } from './ButtonGroup';

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