@krapwoo/ds-viewer 0.1.0 → 0.2.0

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

@@ -0,0 +1,195 @@
+import React, { useEffect, useRef, useState, type ReactNode } from 'react';
+import { View, Text, StyleSheet, useWindowDimensions, type LayoutChangeEvent, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_SHADOW, DS_TYPOGRAPHY } from '../../tokens';
+
+export interface TooltipProps {
+  /** Whether the bubble is shown. Fully controlled — drive this from the wrapped trigger's own
+   *  onLongPress/onPressIn, since mobile has no hover. */
+  visible: boolean;
+  /** The tooltip text. */
+  label: string;
+  /** Which side of the trigger the bubble appears on. @default 'top' */
+  placement?: 'top' | 'bottom';
+  /** Which edge of the trigger the bubble prefers to anchor to horizontally: `'center'` (default)
+   *  centers the bubble on the trigger; `'left'`/`'right'` aligns the bubble's respective edge with
+   *  the trigger's — useful when the trigger sits near a screen edge and a centered bubble would
+   *  extend past it. This is only a *preference*: the bubble is always clamped to stay fully within
+   *  the screen regardless, and the arrow is always computed to point at the trigger's true center,
+   *  never a decorative fixed corner offset. */
+  align?: 'left' | 'center' | 'right';
+  /** The trigger content the bubble is anchored to. */
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+const GAP = DS_SPACING[200];
+const MIN_WIDTH = 60;
+const MAX_WIDTH_RATIO = 0.8;
+const ARROW_SIZE = 6;
+// How close the bubble (and the arrow within it) may come to the screen's own edge.
+const EDGE_MARGIN = DS_SPACING[400];
+// For align='left'/'right': how far the bubble extends *past* the trigger's own edge, instead of
+// aligning flush with it. This gives the arrow (still always computed from the trigger's true
+// center — see below) breathing room from the bubble's rounded corner by shifting the bubble
+// itself, never by clamping the arrow away from accuracy the way a min-inset-on-the-arrow approach
+// would (that approach was tried and reverted: it silently mis-pointed the arrow for any trigger
+// narrower than the inset).
+const EDGE_OVERHANG = DS_SPACING[400];
+// Same colour as the bubble's own background, referenced directly (not via a resolved variable)
+// since — unlike Toast — Tooltip has only the one dark surface, no variant/light-background mode.
+// surface.inverse, not text.regular — it's a dark PANEL fill, not ink (same reasoning as Toast).
+const BUBBLE_COLOR = DS_SEMANTIC.surface.inverse;
+
+/**
+ * A small floating label anchored above or below its wrapped trigger, with a small triangular arrow
+ * pointing back at it. Measures the trigger's real position (`measureInWindow`, since a plain
+ * onLayout only gives a position relative to the trigger's own parent, not the screen) and the
+ * bubble's own rendered width (onLayout), then computes the bubble's horizontal offset itself
+ * instead of just flexbox-centering it — this is what makes it possible to (a) clamp the bubble so
+ * it never runs past the screen's left/right edge and (b) always place the arrow at the trigger's
+ * true horizontal center, even when the bubble itself had to shift away from `align`'s preferred
+ * position to stay on screen. No `numberOfLines` cap on the label — it wraps to however many lines
+ * it needs rather than truncating; `maxWidth` (80% of the screen width, via `useWindowDimensions` so
+ * it tracks rotation/resize) is what keeps a long label from ever running edge-to-edge. The arrow is
+ * the classic CSS border-triangle trick (a zero-size box with one transparent-adjacent border side
+ * coloured in) — RN's View supports per-side border colours, so this needs no SVG.
+ */
+export function Tooltip({ visible, label, placement = 'top', align = 'center', children, style }: TooltipProps) {
+  const { width: windowWidth } = useWindowDimensions();
+  const maxWidth = Math.round(windowWidth * MAX_WIDTH_RATIO);
+
+  const wrapRef = useRef<View>(null);
+  const [trigger, setTrigger] = useState<{ x: number; width: number } | null>(null);
+  const [bubbleWidth, setBubbleWidth] = useState(0);
+
+  // Re-measures whenever the bubble becomes visible or the window is resized — the trigger's own
+  // on-screen position can only be read once it (and any layout change causing it) has settled.
+  useEffect(() => {
+    if (!visible) return undefined;
+    const raf = requestAnimationFrame(() => {
+      wrapRef.current?.measureInWindow((x, _y, width) => setTrigger({ x, width }));
+    });
+    return () => cancelAnimationFrame(raf);
+  }, [visible, windowWidth]);
+
+  // Falls back to plain flex-centering (the old behavior) for the one frame before the trigger/
+  // bubble have been measured, so there's no flash of an unpositioned bubble at 0,0.
+  let bubbleOffsetStyle: ViewStyle = styles.bubbleWrapCentered;
+  let arrowLeft: number | null = null;
+
+  if (trigger && bubbleWidth > 0) {
+    const triggerCenterAbs = trigger.x + trigger.width / 2;
+    const idealLeftAbs =
+      align === 'left'
+        ? trigger.x - EDGE_OVERHANG
+        : align === 'right'
+          ? trigger.x + trigger.width + EDGE_OVERHANG - bubbleWidth
+          : triggerCenterAbs - bubbleWidth / 2;
+    const minLeftAbs = EDGE_MARGIN;
+    const maxLeftAbs = windowWidth - bubbleWidth - EDGE_MARGIN;
+    // maxLeftAbs can be < minLeftAbs for a bubble wider than the screen minus margins — clamp the
+    // clamp range itself so a too-wide bubble still lands at minLeftAbs instead of NaN/garbage.
+    const clampedLeftAbs = Math.min(Math.max(idealLeftAbs, minLeftAbs), Math.max(maxLeftAbs, minLeftAbs));
+    bubbleOffsetStyle = { alignSelf: 'flex-start', marginLeft: clampedLeftAbs - trigger.x };
+    // Always derived from the trigger's real position — never clamped/overridden — so the arrow is
+    // guaranteed accurate regardless of how far the bubble above just shifted for `align` or screen
+    // clamping. EDGE_OVERHANG (baked into idealLeftAbs) is what gives it breathing room from the
+    // bubble's corner; this line doesn't need its own inset logic on top of that.
+    arrowLeft = Math.min(Math.max(triggerCenterAbs - clampedLeftAbs, 0), bubbleWidth);
+  }
+
+  return (
+    <View style={styles.wrap} ref={wrapRef}>
+      {children}
+      {visible && (
+        <View pointerEvents="none" style={[styles.overlay, placement === 'top' ? styles.overlayTop : styles.overlayBottom]}>
+          <View style={[styles.bubbleWrap, bubbleOffsetStyle]}>
+            <View
+              style={[styles.bubble, { maxWidth }, style]}
+              onLayout={(e: LayoutChangeEvent) => setBubbleWidth(e.nativeEvent.layout.width)}
+              // Announce the hint when it appears — without this, a screen-reader user gets no
+              // signal the tooltip exists unless they stumble onto it by swiping.
+              accessibilityLiveRegion="polite"
+            >
+              <Text style={styles.label}>{label}</Text>
+            </View>
+            <View
+              style={[
+                styles.arrow,
+                placement === 'top' ? styles.arrowTop : styles.arrowBottom,
+                arrowLeft != null ? { left: arrowLeft, marginLeft: -ARROW_SIZE } : styles.arrowCenter,
+              ]}
+            />
+          </View>
+        </View>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Shrinks to the trigger's own content width, so the overlay below (left:0/right:0) matches it —
+  // without this, a Tooltip inside a wider flex row would stretch and mis-centre the bubble.
+  wrap: { alignSelf: 'flex-start' },
+  overlay: { position: 'absolute', left: 0, right: 0, zIndex: 10 },
+  overlayTop: { bottom: '100%', marginBottom: GAP },
+  overlayBottom: { top: '100%', marginTop: GAP },
+  // Shrink-wraps to `bubble`'s own real width (the only in-flow child; `arrow` is absolutely
+  // positioned so it doesn't affect this) — the shared positioning context the computed
+  // `marginLeft`/arrow offsets above are both relative to.
+  bubbleWrap: { alignItems: 'center' },
+  // Pre-measurement fallback only — matches the old always-centered look.
+  bubbleWrapCentered: { alignSelf: 'center' },
+  bubble: {
+    // Flexbox's implicit `min-width: auto` would otherwise let this shrink down to its longest
+    // single word (collapsing "Tap to add a stop" into a tall, narrow, multi-line sliver) since it's
+    // a flex child of `overlay`, a column container whose own width matches the (often much
+    // narrower) trigger — `flexShrink: 0` alone doesn't stop that on web; `width: 'max-content'`
+    // (a web-only CSS value, harmlessly ignored by RN's own layout engine on native, where this
+    // shrink-to-longest-word quirk doesn't occur) forces the natural single-line width instead.
+    flexShrink: 0,
+    width: 'max-content' as unknown as number,
+    minWidth: MIN_WIDTH,
+    backgroundColor: BUBBLE_COLOR,
+    borderRadius: DS_RADIUS.small,
+    paddingHorizontal: DS_SPACING[400],
+    paddingVertical: DS_SPACING[200],
+    ...DS_SHADOW.card,
+  },
+  label: {
+    ...DS_TYPOGRAPHY.bodyXs,
+    color: DS_SEMANTIC.text.inverse,
+    textAlign: 'center',
+    // The actual node that was collapsing to its min-content (longest word) width — `flexShrink: 0`
+    // on `bubble` alone wasn't enough, since this Text is itself a shrinkable flex child one level in.
+    flexShrink: 0,
+  },
+  // A zero-size box with only one border side coloured in draws as a triangle — the classic CSS
+  // trick, which RN's per-side border-color/width props support natively too. Horizontal position
+  // is applied separately above (a computed `left`, or `arrowCenter` before the first measurement).
+  arrow: {
+    position: 'absolute',
+    width: 0,
+    height: 0,
+    borderLeftWidth: ARROW_SIZE,
+    borderRightWidth: ARROW_SIZE,
+    borderLeftColor: 'transparent',
+    borderRightColor: 'transparent',
+  },
+  arrowCenter: { left: '50%', marginLeft: -ARROW_SIZE },
+  // Bubble sits above the trigger (placement="top") — the arrow hangs off the bubble's bottom edge,
+  // pointing down at the trigger below it. `bottom: 0` on the overlay-relative arrow lines its own
+  // top edge up with the bubble's bottom edge exactly, since the bubble itself sits flush at the
+  // overlay's bottom (overlayTop's `marginBottom: GAP` already reserves the gap between the two).
+  arrowTop: {
+    bottom: -ARROW_SIZE,
+    borderTopWidth: ARROW_SIZE,
+    borderTopColor: BUBBLE_COLOR,
+  },
+  // Mirror of the above — bubble sits below the trigger, arrow hangs off its top edge pointing up.
+  arrowBottom: {
+    top: -ARROW_SIZE,
+    borderBottomWidth: ARROW_SIZE,
+    borderBottomColor: BUBBLE_COLOR,
+  },
+});

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

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

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

@@ -0,0 +1,71 @@
+import React from 'react';
+import { Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Button } from '../Button';
+import { TopNav } from './TopNav';
+import { DS_SEMANTIC, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  cardTitle: { ...DS_TYPOGRAPHY.labelMd, color: DS_SEMANTIC.text.regular },
+});
+
+export default defineCatalogPage({
+  component: 'TopNav',
+  group: 'Navigation',
+  description: 'A screen\'s top bar — fixed-width leading/trailing slots flanking a centered title (or custom center content). Slots reserve their layout space even when empty, so the title stays centered no matter which sides are populated.',
+  a11y: 'The title renders with accessibilityRole="header". Slot content (typically icon-only Buttons) carries its own accessibilityLabel.',
+  // No `variant` prop exists on TopNav — its "Variants" column just shows the one default look,
+  // with both slots populated; the individual slot combinations live under "States".
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'default',
+        name: 'Default',
+        node: (
+          <TopNav
+            title="Trip planner"
+            leading={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="chevron-left" accessibilityLabel="Back" onPress={() => {}} />}
+            trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="search" accessibilityLabel="Search" onPress={() => {}} />}
+          />
+        ),
+      },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      { key: 'title-only', name: 'Title only', node: <TopNav title="Settings" /> },
+      {
+        key: 'leading-only',
+        name: 'Leading only',
+        node: (
+          <TopNav
+            title="Trip details"
+            leading={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="chevron-left" accessibilityLabel="Back" onPress={() => {}} />}
+          />
+        ),
+      },
+      {
+        key: 'trailing-only',
+        name: 'Trailing only',
+        node: (
+          <TopNav
+            title="Saved trips"
+            trailing={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="add" accessibilityLabel="Add" onPress={() => {}} />}
+          />
+        ),
+      },
+      {
+        key: 'custom-center',
+        name: 'Custom center',
+        node: (
+          <TopNav
+            leading={<Button variant="secondary" size="small" showIcon showLabel={false} iconName="clear" accessibilityLabel="Close" onPress={() => {}} />}
+            center={<Text style={styles.cardTitle}>Custom center content</Text>}
+          />
+        ),
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,77 @@
+import React, { isValidElement, type ReactNode } from 'react';
+import { View, Text, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY, DS_A11Y_MIN_TOUCH_TARGET } from '../../tokens';
+import { Button, type ButtonProps } from '../Button';
+
+// Both slots reserve this width whether populated or empty, so the title stays centered
+// regardless of which side(s) actually have content.
+const SLOT_SIZE = DS_A11Y_MIN_TOUCH_TARGET;
+
+/** Dev-time consistency check (same policy as ButtonGroup's `checkConsistency`) — a nav bar's own
+ *  leading/trailing actions read as one quiet, uniform family (back arrow, close, overflow menu),
+ *  never as a prominent CTA. Warns (never throws) if a slot's Button doesn't follow that: `small`
+ *  size, and not `ghost` (which reads as an inline text action, not a nav icon — see Button's own
+ *  variant-choice doc). */
+function checkSlotButton(node: ReactNode, slotName: 'leading' | 'trailing'): void {
+  if (!isValidElement(node) || node.type !== Button) return;
+  const props = node.props as ButtonProps;
+  if (props.size && props.size !== 'small') {
+    console.warn(`[TopNav] ${slotName} button uses size="${props.size}" — TopNav slot buttons should use size="small".`);
+  }
+  if (props.variant === 'ghost') {
+    console.warn(
+      `[TopNav] ${slotName} button uses variant="ghost" — that reads as an inline text action, not a nav icon. Use variant="secondary" (TopNav's default) instead.`,
+    );
+  }
+}
+
+export interface TopNavProps {
+  /** Centered title text. Ignored when `center` is set. */
+  title?: string;
+  /** Custom content overriding the centered title — e.g. a search field or segmented toggle. */
+  center?: ReactNode;
+  /** Leading slot — typically a back/close icon Button. Keep it `size="small"` and
+   *  `variant="secondary"` (TopNav's default) unless there's a specific reason to deviate — never
+   *  `ghost`, which reads as an inline text action rather than a nav icon. */
+  leading?: ReactNode;
+  /** Trailing slot — typically an action icon Button. Same size/variant guidance as `leading`. */
+  trailing?: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** A screen's top bar: fixed-width leading/trailing slots flanking a centered title (or custom
+ *  `center` content). Slots reserve their layout space even when empty, so the title stays
+ *  centered whether one, both, or neither side has content. */
+export function TopNav({ title, center, leading, trailing, style }: TopNavProps) {
+  checkSlotButton(leading, 'leading');
+  checkSlotButton(trailing, 'trailing');
+  return (
+    <View style={[styles.row, style]}>
+      <View style={styles.slot}>{leading}</View>
+      <View style={styles.center}>
+        {center ?? (title != null && (
+          <Text style={styles.title} numberOfLines={1} accessibilityRole="header">
+            {title}
+          </Text>
+        ))}
+      </View>
+      <View style={[styles.slot, styles.slotTrailing]}>{trailing}</View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    width: '100%',
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingHorizontal: DS_SPACING[800],
+    paddingTop: DS_SPACING[800],
+    paddingBottom: DS_SPACING[400],
+    backgroundColor: DS_SEMANTIC.surface.white,
+  },
+  slot: { width: SLOT_SIZE, height: SLOT_SIZE, alignItems: 'flex-start', justifyContent: 'center' },
+  slotTrailing: { alignItems: 'flex-end' },
+  center: { flex: 1, alignItems: 'center' },
+  title: { ...DS_TYPOGRAPHY.labelMd, color: DS_SEMANTIC.text.regular },
+});

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

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

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

@@ -0,0 +1,30 @@
+import React, { useState } from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { UnderlineTabs } from './UnderlineTabs';
+
+function UnderlineTabsDemo() {
+  const [value, setValue] = useState('all');
+  return (
+    <UnderlineTabs
+      value={value}
+      onChange={setValue}
+      options={[
+        { value: 'all', label: 'All' },
+        // Leading-icon tab — the layout every other option (icon-less) would otherwise hide.
+        { value: 'nearby', label: 'Nearby', iconName: 'pin' },
+        { value: 'favorites', label: 'Favorites', badge: 2 },
+      ]}
+    />
+  );
+}
+
+export default defineCatalogPage({
+  component: 'UnderlineTabs',
+  group: 'Selection',
+  // Phone width plus a small phone, where long labels truncate.
+  previewWidths: [402, 320],
+  description: 'A quieter tab switcher — left-aligned labels over a hairline rule, with a sliding underline indicator. Same options/value/onChange API as SegmentedToggle.',
+  whenToUse: "Quiet, secondary navigation within a screen that already has a clear primary focus. For a prominent, primary choice, use SegmentedToggle.",
+  a11y: 'Each tab is a Pressable label; the underline is a visual indicator only, so selection is also conveyed by the active label weight.',
+  render: () => <UnderlineTabsDemo />,
+});

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

@@ -0,0 +1,156 @@
+import React, { useState } from 'react';
+import { View, Text, Pressable, Animated, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_TYPOGRAPHY, DS_ICON_SIZE, DS_A11Y_MIN_TOUCH_TARGET } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import type { IconName } from '../../icons';
+import { useSlideAnim } from '../SegmentedToggle/useSlideAnim';
+
+export interface UnderlineTabOption {
+  value: string;
+  label: string;
+  /** Optional leading icon (16px) shown before the label. */
+  iconName?: IconName;
+  /** Optional count shown in a circular badge after the label (hidden when 0/undefined). */
+  badge?: number;
+}
+
+export interface UnderlineTabsProps {
+  /** The tabs. */
+  options: UnderlineTabOption[];
+  /** The currently-selected option `value`. */
+  value: string;
+  /** Selection handler. */
+  onChange: (value: string) => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+const INDICATOR_HEIGHT = 2;
+
+/**
+ * Low-prominence tab switcher — left-aligned text labels over a hairline rule, with a thin underline
+ * indicator that slides to the selected tab. A quieter stand-in for SegmentedToggle: same
+ * options/value/onChange API, but no filled track or lifted thumb. Two or more options.
+ */
+export function UnderlineTabs({ options, value, onChange, style }: UnderlineTabsProps) {
+  // -1 when `value` matches no option (e.g. stale state after the options list changed). The
+  // indicator is hidden entirely in that case — clamping to tab 0 would underline a tab whose own
+  // label doesn't render as selected, a visibly contradictory state.
+  const matchedIndex = options.findIndex(o => o.value === value);
+  const hasSelection = matchedIndex !== -1;
+  const selectedIndex = Math.max(0, matchedIndex);
+  // Per-tab measured geometry (x offset + width within the row), so the indicator can size and slide to
+  // each variable-width label.
+  const [layouts, setLayouts] = useState<Record<number, { x: number; width: number }>>({});
+  // Which tab currently holds keyboard focus (null = none).
+  const [focusedValue, setFocusedValue] = useState<string | null>(null);
+  // translateX + width animate together; width can't use the native driver, so neither does.
+  const anim = useSlideAnim(selectedIndex, false);
+  const measured = options.every((_, i) => layouts[i] != null);
+
+  // Unlike SegmentedToggle's analytically-computed thumb position, this indicator slides to each
+  // tab's real measured `x` (from onLayout) — already RTL-correct as-is, since onLayout reports actual
+  // post-mirroring screen position, not an index-based LTR assumption.
+  const indices = options.map((_, i) => i);
+  const indicatorX = measured
+    ? anim.interpolate({ inputRange: indices, outputRange: indices.map(i => layouts[i].x) })
+    : 0;
+  const indicatorW = measured
+    ? anim.interpolate({ inputRange: indices, outputRange: indices.map(i => layouts[i].width) })
+    : 0;
+
+  return (
+    <View style={[styles.row, style]} accessibilityRole="tablist">
+      {options.map((opt, i) => {
+        const selected = opt.value === value;
+        const color = selected ? DS_SEMANTIC.text.regular : DS_SEMANTIC.text.muted;
+        return (
+          <Pressable
+            key={opt.value}
+            onPress={() => onChange(opt.value)}
+            onLayout={e => {
+              const { x, width } = e.nativeEvent.layout;
+              setLayouts(prev =>
+                prev[i] && prev[i].x === x && prev[i].width === width ? prev : { ...prev, [i]: { x, width } },
+              );
+            }}
+            onFocus={() => setFocusedValue(opt.value)}
+            onBlur={() => setFocusedValue(prev => (prev === opt.value ? null : prev))}
+            accessibilityRole="tab"
+            accessibilityLabel={opt.badge != null && opt.badge > 0 ? `${opt.label}, ${opt.badge}` : opt.label}
+            accessibilityState={{ selected }}
+            // Keyboard focus shows the same highlight as a press (same policy as SegmentedToggle/ListItem).
+            style={({ pressed }) => [styles.tab, (pressed || focusedValue === opt.value) && styles.tabPressed]}
+          >
+            {opt.iconName && <Icon name={opt.iconName} size={DS_ICON_SIZE.sm} color={color} />}
+            <Text style={[styles.label, { color }]}>{opt.label}</Text>
+            {opt.badge != null && opt.badge > 0 && (
+              <View style={[styles.badge, { backgroundColor: color }]}>
+                <Text style={[styles.badgeText, { color: DS_SEMANTIC.surface.white }]}>{opt.badge}</Text>
+              </View>
+            )}
+          </Pressable>
+        );
+      })}
+      {measured && hasSelection && (
+        <Animated.View
+          pointerEvents="none"
+          style={[styles.indicator, { width: indicatorW, transform: [{ translateX: indicatorX }] }]}
+        />
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    alignItems: 'flex-end',
+    gap: DS_SPACING[800],
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    borderBottomColor: DS_SEMANTIC.element.divider,
+  },
+  tab: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[200],
+    paddingTop: DS_SPACING[400],
+    paddingBottom: DS_SPACING[600],
+    // A fixed floor (not a spacing token — this is an accessibility guideline number, not a design
+    // choice) so the tab's compact visual padding still guarantees a touch target.
+    minHeight: DS_A11Y_MIN_TOUCH_TARGET,
+  },
+  tabPressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+    borderRadius: DS_RADIUS.small,
+  },
+  label: {
+    // Matches the section-header label size (labelXs) it stands in for.
+    ...DS_TYPOGRAPHY.labelXs,
+    // Pin the line box to the badge height (18) so a tab is the same height with or without a count
+    // badge — otherwise the taller badged tab grows the row and shifts the divider/content below it.
+    lineHeight: 18,
+  },
+  // The sliding underline, sat on the hairline rule beneath the selected tab.
+  indicator: {
+    position: 'absolute',
+    left: 0,
+    bottom: -StyleSheet.hairlineWidth,
+    height: INDICATOR_HEIGHT,
+    borderRadius: INDICATOR_HEIGHT / 2,
+    backgroundColor: DS_SEMANTIC.text.regular,
+  },
+  // Fixed-diameter circle so the count badge stays round. 18 doesn't match a DS_SPACING/DS_ICON_SIZE
+  // step (16/20 are the neighbors) — sized to comfortably fit a 1-2 digit count at labelXs.
+  badge: {
+    width: 18,
+    height: 18,
+    borderRadius: DS_RADIUS.round,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  badgeText: {
+    ...DS_TYPOGRAPHY.labelXs,
+    // Pinned to the badge's own 18px diameter (above) so the count sits centered in the circle.
+    lineHeight: 18,
+  },
+});

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

@@ -0,0 +1,2 @@
+export { UnderlineTabs } from './UnderlineTabs';
+export type { UnderlineTabsProps, UnderlineTabOption } from './UnderlineTabs';

package/starter-kit/components/index.ts

@@ -0,0 +1,36 @@
+/** Barrel for the React Native component tree. */
+export * from './AnimatedChevron';
+export * from './Avatar';
+export * from './Badge';
+export * from './Banner';
+export * from './BottomSheet';
+export * from './Button';
+export * from './ButtonGroup';
+export * from './Card';
+export * from './Checkbox';
+export * from './Dialog';
+export * from './Divider';
+export * from './Dock';
+export * from './Dropdown';
+export * from './EmptyState';
+export * from './FieldContainer';
+export * from './InputClearButton';
+export * from './InputField';
+export * from './List';
+export * from './ListItem';
+export * from './Loading';
+export * from './Pill';
+export * from './PillRow';
+export * from './ProgressDots';
+export * from './Radio';
+export * from './SearchField';
+export * from './SectionHeader';
+export * from './SegmentedToggle';
+export * from './Shimmer';
+export * from './Surface';
+export * from './Switch';
+export * from './TextArea';
+export * from './Toast';
+export * from './Tooltip';
+export * from './TopNav';
+export * from './UnderlineTabs';

package/starter-kit/components/statusColors.ts

@@ -0,0 +1,27 @@
+import { DS_SEMANTIC } from '../tokens';
+
+/**
+ * The one shared status→color lookup behind every status-tinted component (Badge, Banner): a light
+ * tinted fill (`shade`) paired with a saturated foreground (`emphasis`), so a badge and a banner of
+ * the same status always read as the same color identity. Previously each component maintained its
+ * own identical copy of this map — one place to change now keeps them matched by construction.
+ * (Toast's variant map lives separately: its variant names differ (`success`/`informational`) and it
+ * bundles per-variant icons, so it's a different shape, not a third copy of this one.)
+ */
+export type StatusVariant = 'neutral' | 'info' | 'positive' | 'warning' | 'negative';
+
+export const STATUS_BG: Record<StatusVariant, string> = {
+  neutral: DS_SEMANTIC.shade.neutral,
+  info: DS_SEMANTIC.shade.info,
+  positive: DS_SEMANTIC.shade.positive,
+  warning: DS_SEMANTIC.shade.warning,
+  negative: DS_SEMANTIC.shade.negative,
+};
+
+export const STATUS_FG: Record<StatusVariant, string> = {
+  neutral: DS_SEMANTIC.emphasis.neutral,
+  info: DS_SEMANTIC.emphasis.info,
+  positive: DS_SEMANTIC.emphasis.positive,
+  warning: DS_SEMANTIC.emphasis.warning,
+  negative: DS_SEMANTIC.emphasis.negative,
+};