@krapwoo/ds-viewer 0.1.1 → 0.2.0

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

@@ -0,0 +1,165 @@
+import React, { useState, type ReactNode } from 'react';
+import { View, Text, Pressable, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY, DS_A11Y_MIN_TOUCH_TARGET } from '../../tokens';
+
+export interface ListItemProps {
+  /** Primary text. */
+  title: string;
+  /** Small secondary line below the title. */
+  subtitle?: string;
+  /** A third block below subtitle — for lower-priority extra content (a timestamp, a count, or a
+   *  Badge/Button) that shouldn't compete with subtitle for attention. A plain string renders in the
+   *  same small muted style as before; pass a Badge/Button/other node directly for anything richer. */
+  footer?: ReactNode;
+  /** Leading slot — typically an Avatar or Icon. */
+  leading?: ReactNode;
+  /** Compact right-aligned value shown before the trailing slot — e.g. a settings row's current
+   *  value ("English") ahead of its chevron. */
+  trailingText?: string;
+  /** A second, more muted right-aligned line below `trailingText` — e.g. a unit or a status caption
+   *  under the primary value. Only meaningful alongside `trailingText`. */
+  trailingSubtext?: string;
+  /** Trailing slot — typically a chevron Icon, a Switch, a Button, or a value label. */
+  trailing?: ReactNode;
+  /** Makes the whole row tappable. */
+  onPress?: () => void;
+  /** Non-interactive, dimmed. */
+  disabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** A single row: optional leading/trailing slots flanking a title (+ optional subtitle/footer).
+ *  Stack several inside a {@link List} for a settings screen, menu, or search-results list. */
+export function ListItem({
+  title,
+  subtitle,
+  footer,
+  leading,
+  trailingText,
+  trailingSubtext,
+  trailing,
+  onPress,
+  disabled = false,
+  style,
+}: ListItemProps) {
+  const [focused, setFocused] = useState(false);
+  const inner = (
+    <>
+      {leading && <View style={styles.slot}>{leading}</View>}
+      <View style={styles.textGroup}>
+        <Text style={[styles.title, disabled && styles.disabledText]} numberOfLines={1}>{title}</Text>
+        {!!subtitle && (
+          <Text style={[styles.subtitle, disabled && styles.disabledText]} numberOfLines={1}>{subtitle}</Text>
+        )}
+        {footer != null &&
+          (typeof footer === 'string' ? (
+            <Text style={[styles.footerText, disabled && styles.disabledText]} numberOfLines={1}>{footer}</Text>
+          ) : (
+            <View style={styles.footerNode}>{footer}</View>
+          ))}
+      </View>
+      {(trailingText || trailing) && (
+        <View style={styles.trailingGroup}>
+          {!!trailingText && (
+            <View style={styles.trailingTextGroup}>
+              <Text style={[styles.trailingText, disabled && styles.disabledText]} numberOfLines={1}>{trailingText}</Text>
+              {!!trailingSubtext && (
+                <Text style={[styles.trailingSubtext, disabled && styles.disabledText]} numberOfLines={1}>{trailingSubtext}</Text>
+              )}
+            </View>
+          )}
+          {trailing && <View style={styles.slot}>{trailing}</View>}
+        </View>
+      )}
+    </>
+  );
+
+  if (onPress) {
+    return (
+      <Pressable
+        onPress={disabled ? undefined : onPress}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        disabled={disabled}
+        accessibilityRole="button"
+        accessibilityLabel={[title, subtitle].filter(Boolean).join(', ')}
+        accessibilityState={{ disabled }}
+        // Keyboard focus shows the same highlight as a press — a full-width row has no border to
+        // recolor, so focus mirrors the pressed treatment (same policy as SegmentedToggle/UnderlineTabs).
+        style={({ pressed }) => [styles.row, (pressed || focused) && !disabled && styles.pressed, style]}
+      >
+        {inner}
+      </Pressable>
+    );
+  }
+
+  return <View style={[styles.row, style]}>{inner}</View>;
+}
+
+const styles = StyleSheet.create({
+  row: {
+    width: '100%',
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[600],
+    minHeight: DS_A11Y_MIN_TOUCH_TARGET,
+    paddingVertical: DS_SPACING[800],
+    paddingHorizontal: DS_SPACING[400],
+    backgroundColor: DS_SEMANTIC.surface.white,
+  },
+  pressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+  slot: {
+    flexShrink: 0,
+  },
+  textGroup: {
+    flex: 1,
+    minWidth: 0,
+    gap: DS_SPACING[100],
+  },
+  title: {
+    ...DS_TYPOGRAPHY.bodyMd,
+    color: DS_SEMANTIC.text.regular,
+  },
+  subtitle: {
+    ...DS_TYPOGRAPHY.bodyXs,
+    color: DS_SEMANTIC.text.muted,
+  },
+  footerText: {
+    ...DS_TYPOGRAPHY.labelXs,
+    color: DS_SEMANTIC.text.muted,
+  },
+  // A node footer (Badge/Button) brings its own sizing/color — just a top nudge so it doesn't sit
+  // flush against subtitle.
+  footerNode: {
+    marginTop: DS_SPACING[100],
+    alignItems: 'flex-start',
+  },
+  trailingGroup: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[300],
+    flexShrink: 0,
+  },
+  trailingTextGroup: {
+    alignItems: 'flex-end',
+    gap: DS_SPACING[100],
+  },
+  trailingText: {
+    ...DS_TYPOGRAPHY.bodySm,
+    color: DS_SEMANTIC.text.muted,
+    flexShrink: 1,
+  },
+  trailingSubtext: {
+    ...DS_TYPOGRAPHY.labelXs,
+    color: DS_SEMANTIC.text.muted,
+    flexShrink: 1,
+  },
+  // Disabled text — a step lighter than `text.muted` (which the subtitle/footer already use for
+  // ordinary secondary text), so a disabled row reads as inactive rather than just secondary —
+  // same reasoning as InputField/SearchField (see DS_SEMANTIC.text.disabled's own doc comment).
+  disabledText: {
+    color: DS_SEMANTIC.text.disabled,
+  },
+});

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

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

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

@@ -0,0 +1,34 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Loading } from './Loading';
+import { DS_SEMANTIC } from '../../tokens';
+
+export default defineCatalogPage({
+  component: 'Loading',
+  group: 'Feedback',
+  description: 'An indeterminate loader — the shape fills up, empties out, then fills again, seamlessly. Two variants: circle (used internally by Button and Pill for their own loading states) and linear.',
+  a11y: 'Exposed to assistive tech as accessibilityRole="progressbar" with accessibilityLabel="Loading" — no extra wiring needed at the call site.',
+  // One example per `variant` enum value — `circle` is the default, so it comes first.
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'circle', name: 'Circle', props: { variant: 'circle' }, node: <Loading variant="circle" /> },
+      { key: 'linear', name: 'Linear', props: { variant: 'linear' }, node: <Loading variant="linear" /> },
+    ],
+  },
+  // `size` (circle) and `height` (linear) are continuous numbers, not enums — small/medium/large
+  // and thin/default/thick are explicit, labeled sweeps across each. Each sweep names its variant
+  // through `group`, so the page shows one row per variant; Accent colour applies to both and
+  // stays in "Other configurations".
+  states: {
+    items: [
+      { key: 'small-circle', group: 'circle', name: 'Small circle', node: <Loading variant="circle" size={14} /> },
+      { key: 'medium-circle', group: 'circle', name: 'Medium circle (default)', node: <Loading variant="circle" size={20} /> },
+      { key: 'large-circle', group: 'circle', name: 'Large circle', node: <Loading variant="circle" size={40} /> },
+      { key: 'thin-linear', group: 'linear', fill: true, name: 'Thin linear', node: <Loading variant="linear" height={2} /> },
+      { key: 'default-linear', group: 'linear', fill: true, name: 'Default linear', node: <Loading variant="linear" height={4} /> },
+      { key: 'thick-linear', group: 'linear', fill: true, name: 'Thick linear', node: <Loading variant="linear" height={8} /> },
+      { key: 'accent', name: 'Accent colour', node: <Loading variant="circle" color={DS_SEMANTIC.emphasis.info} /> },
+    ],
+  },
+});

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

@@ -0,0 +1,121 @@
+import React, { useEffect, useRef } from 'react';
+import { View, Animated, Easing, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import Svg, { Path, type PathProps } from 'react-native-svg';
+import { DS_SEMANTIC, DS_MOTION_LOOP_DURATION } from '../../tokens';
+
+// `Animated.createAnimatedComponent` forces `collapsable: false` onto the wrapped component's
+// props (so the native view isn't flattened out from under the native driver) — react-native-svg's
+// web shim doesn't recognize `collapsable` and passes it straight through to the DOM, so an
+// animated Path would otherwise log "Received `false` for a non-boolean attribute `collapsable`."
+// This wrapper drops it before it reaches the real Path; native platforms never read it off Path.
+const AnimatedPath = Animated.createAnimatedComponent(
+  React.forwardRef<unknown, PathProps & { collapsable?: boolean }>(({ collapsable: _collapsable, ...rest }, ref) => (
+    <Path ref={ref as never} {...rest} />
+  )),
+);
+
+// A 20×20 viewBox, ~292° arc (radius 9, centre 10,10), 2px stroke. The arc is a single stroke whose
+// dash exactly covers its length, so animating the dash offset draws it on (fills) then off (empties).
+const ARC_PATH =
+  'M19 10C19 11.9289 18.3803 13.8067 17.2323 15.3567C16.0843 16.9067 14.4687 18.0468 12.6236 18.6091C10.7785 19.1714 8.8016 19.126 6.98426 18.4797C5.16692 17.8334 3.6053 16.6203 2.52959 15.0193C1.45388 13.4182 0.920996 11.514 1.00948 9.58714C1.09796 7.66032 1.80313 5.81291 3.02105 4.3172C4.23897 2.8215 5.9052 1.75664 7.77412 1.2796C9.64305 0.802556 11.6158 0.938564 13.4016 1.66758';
+const ARC_LEN = 45.9;
+
+export type LoadingVariant = 'circle' | 'linear';
+
+export interface LoadingProps {
+  /** Which shape to render. @default 'circle' */
+  variant?: LoadingVariant;
+  /** Diameter in px — circle only. @default 20 */
+  size?: number;
+  /** Track width — linear only. @default '100%' */
+  width?: number | `${number}%`;
+  /** Track/bar thickness — linear only. @default 4 */
+  height?: number;
+  /** Stroke (circle) / fill (linear) colour. Defaults to the regular text colour. */
+  color?: string;
+  /** Track (background) colour — linear only. */
+  trackColor?: string;
+  /** One fill→empty cycle duration in ms. @default DS_MOTION_LOOP_DURATION.spinner (1200) */
+  duration?: number;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Indeterminate loader — the shape fills up, empties out, then fills again, seamlessly, in either of
+ * two variants:
+ *  - `circle` (default): a dash slides across the arc's own length over a 2× period, so a single
+ *    continuous timing produces the fill→empty→fill motion.
+ *  - `linear`: a bar's width animates 0→100%→0% explicitly (two phases — there's no dash-slide
+ *    equivalent for a plain width fill).
+ * Both are JS-driven (`useNativeDriver: false`), so Fabric-safe: a continuous loop on an
+ * always-mounted view, no imperative setValue. Used internally by Button and Pill for their own
+ * loading states (circle).
+ */
+export function Loading({
+  variant = 'circle',
+  size = 20,
+  width = '100%',
+  height = 4,
+  color = DS_SEMANTIC.text.regular,
+  trackColor = DS_SEMANTIC.surface.muted,
+  duration = DS_MOTION_LOOP_DURATION.spinner,
+  style,
+}: LoadingProps) {
+  // Circle drives this directly as a dash offset (ARC_LEN..-ARC_LEN); linear reads it as 0..1 and
+  // interpolates to a width percentage. Different ranges, same underlying value — each variant's own
+  // effect below sets up the animation appropriate to it.
+  const progress = useRef(new Animated.Value(variant === 'circle' ? ARC_LEN : 0)).current;
+
+  useEffect(() => {
+    const loop =
+      variant === 'circle'
+        ? Animated.loop(
+            Animated.timing(progress, {
+              toValue: -ARC_LEN,
+              duration,
+              easing: Easing.inOut(Easing.ease),
+              useNativeDriver: false,
+            }),
+          )
+        : Animated.loop(
+            Animated.sequence([
+              Animated.timing(progress, { toValue: 1, duration, easing: Easing.inOut(Easing.ease), useNativeDriver: false }),
+              Animated.timing(progress, { toValue: 0, duration, easing: Easing.inOut(Easing.ease), useNativeDriver: false }),
+            ]),
+          );
+    loop.start();
+    return () => loop.stop();
+  }, [variant, duration, progress]);
+
+  if (variant === 'linear') {
+    const fillWidth = progress.interpolate({ inputRange: [0, 1], outputRange: ['0%', '100%'] });
+    return (
+      <View
+        style={[styles.track, { width, height, backgroundColor: trackColor, borderRadius: height / 2 }, style]}
+        accessible
+        accessibilityRole="progressbar"
+        accessibilityLabel="Loading"
+      >
+        <Animated.View
+          style={[styles.fill, { height, backgroundColor: color, width: fillWidth, borderRadius: height / 2 }]}
+        />
+      </View>
+    );
+  }
+
+  return (
+    // The accessibility props live on this wrapping View, not the Svg: react-native-svg's web shim
+    // forwards unrecognized props straight to the DOM, and `accessible`/`accessibilityRole` would
+    // otherwise log "Received `true`/`\"progressbar\"` for a non-boolean/non-standard attribute."
+    <View style={style} accessible accessibilityRole="progressbar" accessibilityLabel="Loading">
+      <Svg width={size} height={size} viewBox="0 0 20 20" fill="none">
+        <AnimatedPath d={ARC_PATH} stroke={color} strokeWidth={2} strokeDasharray={ARC_LEN} strokeDashoffset={progress} />
+      </Svg>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  track: { overflow: 'hidden' },
+  fill: { position: 'absolute', left: 0, top: 0 },
+});

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

@@ -0,0 +1,2 @@
+export { Loading } from './Loading';
+export type { LoadingProps, LoadingVariant } from './Loading';

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

@@ -0,0 +1,93 @@
+import React from 'react';
+import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { Pill } from './Pill';
+
+// 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,
+  };
+}
+
+// Pill: Selection × State.
+const PILL_COMPARISON = grid(
+  'Selection',
+  'State',
+  [
+    { key: 'selected', label: 'Selected' },
+    { key: 'not-selected', label: 'Not selected' },
+  ],
+  [
+    { key: 'icon-text', label: 'Icon + Text' },
+    { key: 'icon-only', label: 'Icon-only' },
+    { key: 'disabled', label: 'Disabled' },
+    { key: 'loading', label: 'Loading' },
+  ],
+  (row, column) => (
+    <Pill
+      label="Home"
+      variant={row === 'selected' ? 'selected' : 'not_selected'}
+      iconName="home"
+      showText={column !== 'icon-only'}
+      accessibilityLabel="Home"
+      disabled={column === 'disabled'}
+      loading={column === 'loading'}
+      onPress={() => {}}
+    />
+  ),
+  'compact',
+);
+
+export default defineCatalogPage({
+  component: 'Pill',
+  group: 'Actions',
+  specimenSize: 'compact',
+  comparison: PILL_COMPARISON,
+  description: 'A compact selectable chip — selected/unselected states with an optional leading icon.',
+  whenToUse: "A selection toggle, not an action — tapping it flips a persistent selected state. If tapping it should instead make something happen, use Button.",
+  a11y: 'Pressable with accessibilityLabel; an icon-only pill (showText={false}) needs an explicit accessibilityLabel so it is announced.',
+  variants: {
+    items: [
+      { key: 'selected', name: 'Selected', props: { variant: 'selected' }, node: <Pill label="Home" variant="selected" iconName="home" onPress={() => {}} /> },
+      { key: 'not-selected', name: 'Not selected', props: { variant: 'not_selected' }, node: <Pill label="Work" variant="not_selected" iconName="briefcase" onPress={() => {}} /> },
+    ],
+  },
+  states: {
+    items: [
+      {
+        key: 'icon-text',
+        name: 'Icon + Text',
+        node: <Pill label="Nearby" variant="not_selected" iconName="pin" onPress={() => {}} />,
+      },
+      {
+        key: 'icon-only',
+        name: 'Icon-only',
+        node: <Pill label="Saved" variant="not_selected" iconName="bell" showText={false} onPress={() => {}} />,
+      },
+      {
+        key: 'disabled',
+        name: 'Disabled',
+        node: <Pill label="Sold out" variant="not_selected" iconName="clock" disabled onPress={() => {}} />,
+      },
+      {
+        key: 'loading',
+        name: 'Loading',
+        node: <Pill label="Saving" variant="not_selected" iconName="clock" loading onPress={() => {}} />,
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,181 @@
+import React, { useState } from 'react';
+import { Pressable, Text, StyleSheet, View } from 'react-native';
+import { DS_SEMANTIC, DS_RADIUS, DS_SPACING, DS_TYPOGRAPHY, DS_SHADOW } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import { Loading } from '../Loading';
+import type { PillProps } from './Pill.types';
+
+function PillIcon({
+  name,
+  selected,
+  size = 16,
+}: {
+  name: NonNullable<PillProps['iconName']>;
+  selected: boolean;
+  size?: number;
+}) {
+  return (
+    <Icon name={name} size={size} color={selected ? DS_SEMANTIC.text.inverse : DS_SEMANTIC.text.regular} />
+  );
+}
+
+/**
+ * A single-line selection chip. `selected` fills solid dark with inverse content; `not_selected`
+ * sits on white with a resting shadow. Leading slot holds an `iconName`, a custom `icon` node
+ * (sizes naturally), or the default menu icon; the label can be hidden for an icon-only pill.
+ */
+export function Pill({
+  label = 'Text',
+  variant = 'selected',
+  accessibilityLabel,
+  showText = true,
+  iconName,
+  iconSize = 16,
+  icon,
+  onPress,
+  disabled = false,
+  loading = false,
+  style,
+}: PillProps) {
+  const isSelected = variant === 'selected';
+  const isDisabled = disabled || loading;
+  const [focused, setFocused] = useState(false);
+
+  // A custom `icon` node (e.g. a badge) is taller than a plain icon. The pill keeps a fixed
+  // height regardless, so the badge centers in the same height as an icon+label pill; its horizontal
+  // padding is then reduced to equal the (smaller) vertical breathing room around the taller badge.
+  const isBadge = !iconName && icon != null;
+
+  // The leading slot sizes to its content, so it holds an `iconName` (at `iconSize`), a custom `icon`
+  // node of any size, or the default menu icon.
+  const iconNode = iconName ? (
+    <PillIcon name={iconName} selected={isSelected} size={iconSize} />
+  ) : (
+    icon ?? <PillIcon name="menu" selected={isSelected} size={iconSize} />
+  );
+
+  const content = loading ? (
+    <Loading
+      size={16}
+      color={isSelected ? DS_SEMANTIC.text.inverse : DS_SEMANTIC.text.regular}
+    />
+  ) : (
+    <>
+      <View style={styles.iconSlot}>{iconNode}</View>
+      {showText && label ? (
+        <Text
+          // Pills are single-line chips — never wrap (a sub-pixel-tight equal width would otherwise
+          // fold the label onto two lines and grow the pill).
+          numberOfLines={1}
+          style={[
+            styles.label,
+            { color: isSelected ? DS_SEMANTIC.text.inverse : DS_SEMANTIC.text.regular },
+          ]}
+        >
+          {label}
+        </Text>
+      ) : null}
+    </>
+  );
+
+  // Icon-only pills are forced to a fixed width equal to the pill's own fixed height (not left to
+  // emerge from padding + the icon's own width, which only happens to land on a square at the
+  // default iconSize=16 — passing a different `iconSize` would otherwise stretch it into a
+  // rounded rect instead of a true circle) — a fixed square, with content centred inside it via the
+  // container's own `alignItems`/`justifyContent: center`, keeps it circular at any icon size.
+  const containerStyle = [
+    styles.container,
+    showText ? { paddingHorizontal: isBadge ? DS_SPACING[400] : DS_SPACING[600] } : styles.iconOnly,
+    isSelected ? styles.selected : styles.notSelected,
+    isDisabled && styles.disabled,
+    style,
+  ];
+
+  // A selected pill is the current state — tapping it is a no-op, so it renders as a plain View
+  // (no pressed feedback) even when an onPress is wired up.
+  if (onPress && !isSelected) {
+    return (
+      <Pressable
+        onPress={onPress}
+        disabled={isDisabled}
+        // Extends the 40pt-tall pill to the 44pt minimum touch target. An icon-only pill is also only
+        // ~40pt wide (no label to widen it), so it needs the same padding on left/right too.
+        hitSlop={showText ? { top: 2, bottom: 2 } : { top: 2, bottom: 2, left: 2, right: 2 }}
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel ?? label}
+        accessibilityState={{ disabled: isDisabled, busy: loading, selected: isSelected }}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        style={({ pressed }) => [
+          containerStyle,
+          pressed && !isDisabled && styles.pressed,
+          focused && !isDisabled && styles.focused,
+        ]}
+      >
+        {content}
+      </Pressable>
+    );
+  }
+
+  return <View style={containerStyle}>{content}</View>;
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: DS_SPACING[200],
+    // Fixed height so a tall leading node doesn't grow the pill past an icon+label one.
+    // Horizontal padding is applied per-instance (equal to the vertical breathing room): normal pills
+    // use 12, badge pills 8; icon-only pills get a fixed width instead (see `iconOnly` below).
+    height: DS_SPACING[2000],
+    borderRadius: DS_RADIUS.round,
+  },
+  // Fixed width equal to `container`'s own fixed height — a true circle regardless of the leading
+  // icon's size, rather than letting width emerge from padding + icon width (see the containerStyle
+  // comment above).
+  iconOnly: {
+    width: DS_SPACING[2000],
+  },
+  selected: {
+    // surface.inverse, not text.regular — this is a dark panel FILL, not ink; the two tokens share a
+    // value today but must be free to diverge in a rebrand.
+    backgroundColor: DS_SEMANTIC.surface.inverse,
+    // Transparent border matching not_selected's 2px, so both variants have identical layout boxes
+    // (otherwise unselected pills render taller and the row looks uneven). Reserved at the focus
+    // ring's own width (not 1px) so focusing only swaps the border colour, never its width — a
+    // width change on focus would otherwise shift the pill's layout, same fix as Button's border.
+    borderWidth: 2,
+    borderColor: 'transparent',
+  },
+  notSelected: {
+    backgroundColor: DS_SEMANTIC.surface.white,
+    // No border — the resting shadow alone separates the pill from the surface. Keep a transparent
+    // border (matching selected's reserved focus-ring width) so the box matches its height.
+    borderWidth: 2,
+    borderColor: 'transparent',
+    ...DS_SHADOW.resting,
+  },
+  pressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+  },
+  focused: {
+    borderColor: DS_SEMANTIC.interaction.focused,
+  },
+  // Dims the WHOLE pill — container opacity multiplies down through every child in RN, so the
+  // label/icon dim with it; there is no way for a child to opt back out of an ancestor's opacity.
+  disabled: {
+    opacity: DS_SEMANTIC.interaction.disabledOpacity,
+  },
+  // Sizes to its content so the leading slot can hold an icon of any size or a custom node.
+  iconSlot: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  // No pinned lineHeight — the pill's height follows the label typography (padding + natural line
+  // height), so a type-scale change resizes the pill instead of rattling inside a fixed box.
+  label: {
+    ...DS_TYPOGRAPHY.labelSm,
+  },
+});

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

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../../icons';
+
+/** Selection state of the pill. */
+export type PillVariant = 'selected' | 'not_selected';
+
+export interface PillProps {
+  /** Chip text. */
+  label?: string;
+  /** Selection state. */
+  variant?: PillVariant;
+  /** Screen-reader name. Strongly recommended for an icon-only pill (`showText={false}`) — it is not
+   *  enforced, so omitting it means the placeholder `label` default gets announced instead. Defaults
+   *  to `label` for text pills. */
+  accessibilityLabel?: string;
+  /** Hide the label for an icon-only pill. */
+  showText?: boolean;
+  /** Renders in the inverse/regular color based on selection (preferred over `icon`). */
+  iconName?: IconName;
+  /** Render size for `iconName` (default 16). */
+  iconSize?: number;
+  /** Custom leading node — sizes naturally; takes precedence over the default menu icon. */
+  icon?: ReactNode;
+  /** Tap handler. */
+  onPress?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  style?: StyleProp<ViewStyle>;
+}

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

@@ -0,0 +1,2 @@
+export { Pill } from './Pill';
+export type { PillProps, PillVariant } from './Pill.types';