@krapwoo/ds-viewer 0.1.0 → 0.2.0

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

@@ -0,0 +1,151 @@
+import React, { createContext, type ReactNode, isValidElement, cloneElement, useContext, useEffect, useRef, useState } from 'react';
+import { View, Pressable, ScrollView, Animated, Easing, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS, DS_SHADOW, DS_SPACING, DS_MOTION_DURATION, DS_MOTION_EASING } from '../../tokens';
+import { Dock, type DockProps } from '../Dock';
+
+const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
+const MAX_HEIGHT_PERCENT = '90%';
+
+/** True while rendering inside an already-open BottomSheet's tree (header/children/footer alike).
+ *  Any component that opens its OWN BottomSheet (e.g. Dropdown) reads this via
+ *  `useInsideBottomSheetWarning` to dev-warn against stacking two sheets — a sheet already covers
+ *  the whole screen, so a second one has nowhere sensible to appear and just traps the user between
+ *  two backdrops. Defaults to `false` for anything rendered outside a BottomSheet entirely. */
+const BottomSheetContext = createContext(false);
+
+/** Call this from a component that opens its own BottomSheet (Dropdown, another picker, …) — warns
+ *  once per render if it's currently nested inside a different, already-open BottomSheet. Console
+ *  warning only (never throws), matching this codebase's other dev-time consistency checks (e.g.
+ *  ButtonGroup's `checkConsistency`). */
+export function useInsideBottomSheetWarning(componentName: string): void {
+  const insideBottomSheet = useContext(BottomSheetContext);
+  if (insideBottomSheet) {
+    console.warn(
+      `[${componentName}] is opening a BottomSheet from inside another, already-open BottomSheet. Never stack two sheets — restructure so ${componentName} lives outside the outer sheet (e.g. in the screen that opens it), or replace it with an inline control (e.g. SegmentedToggle/Radio) for use inside a sheet.`,
+    );
+  }
+}
+
+export interface BottomSheetProps {
+  /** Whether the sheet (and its backdrop) are mounted and shown. */
+  visible: boolean;
+  /** Called when the backdrop is tapped — the sheet doesn't close itself; the caller decides. */
+  onDismiss: () => void;
+  /** Top area — typically a TopNav with a close/back action. */
+  header?: ReactNode;
+  /** Middle content area. Grows with its content up to 90% of the available height, then scrolls. */
+  children: ReactNode;
+  /** Bottom area — typically a Dock with the sheet's primary actions. When `footer` is a Dock
+   *  element, its `elevated` prop is driven automatically from whether the content area above it
+   *  actually overflows (needs to scroll) — no need to pass `elevated` yourself. */
+  footer?: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * A sheet that slides up from the bottom over a dismissible backdrop. Height is driven by its
+ * content (not a fixed set of snap points) up to a cap, past which the content area scrolls. Not
+ * portaled through RN's `Modal` — it's a plain absolutely-positioned overlay, so it fills whichever
+ * parent View hosts it (RN Views are positioning contexts by default), which also lets the catalog
+ * contain a live demo inside a bounded preview frame instead of covering the whole page.
+ */
+export function BottomSheet({ visible, onDismiss, header, children, footer, style }: BottomSheetProps) {
+  const progress = useRef(new Animated.Value(0)).current;
+  const [mounted, setMounted] = useState(visible);
+  // The sheet's own rendered height, measured via onLayout — its closed position is "translated
+  // down by exactly its own height" (fully below the visible area), not a small fixed nudge, so the
+  // motion genuinely reads as sliding in from off-screen regardless of how tall the content is.
+  // Falls back to a generous guess before the first measurement lands, to avoid a jump on first open.
+  const [sheetHeight, setSheetHeight] = useState(0);
+  // Drives a Dock footer's `elevated` shadow: on only once the content area's actual measured
+  // height exceeds what it's laid out to show, i.e. it's genuinely scrollable — not just "there is
+  // a Dock", so a short sheet stays flat and only a scrolling one gets the separating shadow.
+  const [scrollLayoutHeight, setScrollLayoutHeight] = useState(0);
+  const [scrollContentHeight, setScrollContentHeight] = useState(0);
+  const contentOverflows = scrollContentHeight > scrollLayoutHeight + 1;
+
+  useEffect(() => {
+    if (visible) setMounted(true);
+    // Backdrop opacity still fades (a scrim has no position to slide from); the sheet itself only
+    // ever moves via translateY below — no opacity animation on the sheet, just the slide.
+    const anim = Animated.timing(progress, {
+      toValue: visible ? 1 : 0,
+      duration: visible ? DS_MOTION_DURATION.base : DS_MOTION_DURATION.fast,
+      // `decelerate` — a sheet entering the screen, per DS_MOTION_EASING_USE (previously left on
+      // RN's default in-out ease, the one enter/exit overlay without an explicit curve).
+      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 translateY = progress.interpolate({ inputRange: [0, 1], outputRange: [sheetHeight || 400, 0] });
+
+  const resolvedFooter =
+    isValidElement(footer) && footer.type === Dock
+      ? cloneElement(footer as React.ReactElement<DockProps>, { elevated: contentOverflows })
+      : footer;
+
+  return (
+    <View style={styles.overlay} pointerEvents={visible ? 'auto' : 'none'}>
+      <AnimatedPressable
+        style={[styles.backdrop, { opacity: progress }]}
+        onPress={onDismiss}
+        accessibilityRole="button"
+        accessibilityLabel="Dismiss"
+      />
+      <Animated.View
+        onLayout={(e) => setSheetHeight(e.nativeEvent.layout.height)}
+        style={[styles.sheet, style, { transform: [{ translateY }] }]}
+        // 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
+      >
+        <View style={styles.handle} />
+        <BottomSheetContext.Provider value>
+          {header}
+          <ScrollView
+            style={styles.content}
+            contentContainerStyle={styles.contentContainer}
+            bounces={false}
+            onLayout={(e) => setScrollLayoutHeight(e.nativeEvent.layout.height)}
+            onContentSizeChange={(_width, height) => setScrollContentHeight(height)}
+          >
+            {children}
+          </ScrollView>
+          {resolvedFooter}
+        </BottomSheetContext.Provider>
+      </Animated.View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: { ...StyleSheet.absoluteFillObject, justifyContent: 'flex-end' },
+  backdrop: { ...StyleSheet.absoluteFillObject, backgroundColor: DS_SEMANTIC.element.overlayBackdrop },
+  sheet: {
+    maxHeight: MAX_HEIGHT_PERCENT,
+    backgroundColor: DS_SEMANTIC.surface.white,
+    borderTopLeftRadius: DS_RADIUS.large,
+    borderTopRightRadius: DS_RADIUS.large,
+    ...DS_SHADOW.bottomSheet,
+  },
+  // Purely a visual affordance (this sheet has no drag-to-dismiss gesture wired up) — signals "you
+  // can swipe this" the same way native sheets do, sized to the common ~36×4 grabber convention.
+  handle: {
+    alignSelf: 'center',
+    width: 36,
+    height: 4,
+    borderRadius: DS_RADIUS.round,
+    backgroundColor: DS_SEMANTIC.border.light,
+    marginTop: DS_SPACING[300],
+    marginBottom: DS_SPACING[100],
+  },
+  content: { flexGrow: 0 },
+  contentContainer: { padding: DS_SPACING[800] },
+});

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

@@ -0,0 +1,2 @@
+export { BottomSheet, useInsideBottomSheetWarning } from './BottomSheet';
+export type { BottomSheetProps } from './BottomSheet';

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