@appinternalleads/ui 0.2.0

package/src/core/Gesture.tsx

@@ -0,0 +1,184 @@
+import { useEffect, useRef, type ReactNode } from 'react';
+import { PanResponder, View, type ViewStyle } from 'react-native';
+
+/**
+ * **One drag primitive, for every control that has a position.**
+ *
+ * A slider, a two-handle range and a dial are the same gesture with different arithmetic: a
+ * finger lands somewhere inside a box, and the control decides what that means. So this reports
+ * the raw position and computes nothing — `fraction` is offered because a horizontal track wants
+ * it, and the arc ignores it and uses `x`/`y`.
+ *
+ * It lives in `core/` because `PanResponder` is a platform API, and `src/core/` and `src/tokens/`
+ * are the only layers allowed to import one. It is one file rather than a platform split because
+ * `react-native-web` implements `PanResponder` on pointer events — the same gesture works in a
+ * browser, which is what the widget family needs since its cards render on both surfaces.
+ */
+export type DragPoint = {
+  /** Relative to the area's own top-left, in points. */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** `x / width`, clamped to 0–1. What a horizontal track wants and nothing else needs. */
+  fraction: number;
+  /** `true` on the first touch, `false` for every move that follows. */
+  first: boolean;
+};
+
+export type DragAreaProps = {
+  onDrag: (p: DragPoint) => void;
+  /** Fired once when the finger lifts — for committing a value the drag was only previewing. */
+  onRelease?: () => void;
+  disabled?: boolean;
+  children?: ReactNode;
+  style?: ViewStyle;
+  testID?: string;
+  accessible?: boolean;
+  accessibilityRole?: 'adjustable' | 'none';
+  'aria-label'?: string;
+  accessibilityValue?: { min?: number; max?: number; now?: number; text?: string };
+  accessibilityActions?: { name: string }[];
+  onAccessibilityAction?: (e: { nativeEvent: { actionName: string } }) => void;
+};
+
+const clamp01 = (n: number) => (n < 0 ? 0 : n > 1 ? 1 : n);
+
+export function DragArea({
+  onDrag, onRelease, disabled, children, style, testID,
+  accessible, accessibilityRole, 'aria-label': ariaLabel,
+  accessibilityValue, accessibilityActions, onAccessibilityAction,
+}: DragAreaProps) {
+  const ref = useRef<View>(null);
+
+  /**
+   * **Every changing value goes through one ref, and this is the bug that made it necessary.**
+   *
+   * `PanResponder.create` has to run once — recreating it mid-gesture drops the responder and the
+   * drag dies under the finger. But a responder created once closes over the FIRST render's
+   * props, so the previous slider called a stale `onChange` and read a stale `disabled`. Reading
+   * everything from a ref that each render updates is what makes "create once" and "see the
+   * current props" both true.
+   */
+  const latest = useRef({ onDrag, onRelease, disabled, box: { x: 0, y: 0, w: 0, h: 0 } });
+  latest.current.onDrag = onDrag;
+  latest.current.onRelease = onRelease;
+  latest.current.disabled = disabled;
+
+  const measure = () => {
+    ref.current?.measureInWindow((x, y, w, h) => {
+      latest.current.box = { x, y, w, h };
+    });
+  };
+  /* Layout is not the only thing that moves a control: a scroll does too, and `onLayout` does not
+     fire for that. Measuring again on each touch-down costs nothing and keeps a dragged handle
+     under the finger in a scrolling card. */
+  useEffect(measure, []);
+
+  const responder = useRef(
+    PanResponder.create({
+      onStartShouldSetPanResponder: () => true,
+      onMoveShouldSetPanResponder: () => true,
+      /* Claim the gesture so a parent ScrollView does not steal it the moment the finger moves. */
+      onPanResponderTerminationRequest: () => false,
+      onStartShouldSetPanResponderCapture: () => true,
+
+      onPanResponderGrant: e => {
+        const s = latest.current;
+        if (s.disabled) return;
+        measure();
+        const { locationX, locationY } = e.nativeEvent;
+        const { w, h } = s.box;
+        s.onDrag({
+          x: locationX,
+          y: locationY,
+          width: w,
+          height: h,
+          fraction: clamp01(locationX / (w || 1)),
+          first: true,
+        });
+      },
+
+      onPanResponderMove: (_e, g) => {
+        const s = latest.current;
+        if (s.disabled) return;
+        const { x, y, w, h } = s.box;
+        /* `moveX`/`moveY` are window coordinates; the box's own origin turns them into local
+           ones. Without that a handle jumps to wherever the track happens to sit on screen. */
+        const localX = g.moveX - x;
+        const localY = g.moveY - y;
+        s.onDrag({
+          x: localX,
+          y: localY,
+          width: w,
+          height: h,
+          fraction: clamp01(localX / (w || 1)),
+          first: false,
+        });
+      },
+
+      onPanResponderRelease: () => latest.current.onRelease?.(),
+      onPanResponderTerminate: () => latest.current.onRelease?.(),
+    }),
+  ).current;
+
+  return (
+    <View
+      ref={ref}
+      testID={testID}
+      onLayout={measure}
+      accessible={accessible}
+      accessibilityRole={accessibilityRole}
+      accessibilityLabel={ariaLabel}
+      accessibilityValue={accessibilityValue}
+      accessibilityActions={accessibilityActions}
+      onAccessibilityAction={onAccessibilityAction}
+      {...responder.panHandlers}
+      style={style}>
+      {children}
+    </View>
+  );
+}
+
+/**
+ * Snap a 0–1 fraction onto a stepped range.
+ *
+ * Pure, exported and tested on its own, because **a gesture is the one thing a unit test cannot
+ * press**. The arithmetic is where sliders are actually wrong — off-by-one at the ends, values
+ * between steps — and that part does not need a finger.
+ */
+export function valueFromFraction(
+  fraction: number,
+  min: number,
+  max: number,
+  step = 1,
+): number {
+  const raw = min + clamp01(fraction) * (max - min);
+  const snapped = Math.round((raw - min) / step) * step + min;
+  const bounded = Math.min(max, Math.max(min, snapped));
+  /* Floating-point step arithmetic leaves 0.30000000000000004 on a 0.1 step. */
+  return Number(bounded.toFixed(10));
+}
+
+/**
+ * The fraction around an arc, for a dial.
+ *
+ * `startAngle` and `sweep` are degrees clockwise from 12 o'clock — `Arc`'s convention, so a
+ * handoff value transfers to both the drawing and the gesture without conversion.
+ */
+export function fractionFromAngle(
+  x: number,
+  y: number,
+  cx: number,
+  cy: number,
+  startAngle: number,
+  sweep: number,
+): number {
+  /* atan2 measured from 12 o'clock, clockwise, so it matches how the arc is drawn. */
+  const deg = (Math.atan2(x - cx, cy - y) * 180) / Math.PI;
+  const fromStart = (((deg - startAngle) % 360) + 360) % 360;
+  /* Past the end of the sweep, the nearer end wins — dragging off a half-dial should stick to
+     whichever extreme the finger left from, not wrap round to the other one. */
+  if (fromStart > sweep) return fromStart - sweep > (360 - sweep) / 2 ? 0 : 1;
+  return clamp01(fromStart / sweep);
+}

package/src/core/Icon.tsx

@@ -0,0 +1,376 @@
+/**
+ * **Every import here is a deep path, and collapsing them into one barrel costs 5.3 MB.**
+ *
+ * `phosphor-react-native`'s root entry is `export * from './icons/X'` over 1,512 icons, each
+ * with six weight definitions, and Metro does not tree-shake. The package declares
+ * `"./src/icons/*"` in its `exports` map, so this is a supported path rather than a reach into
+ * private files — but it resolves to `.tsx` SOURCE, which is why `tsconfig.json` maps the same
+ * specifier to `lib/typescript/icons/*`.
+ *
+ * The lesson is carried over verbatim from `canvas-app/packages/ds/src/Icon.tsx`. Adding a
+ * glyph means adding a deep import here, and that is the entire trade.
+ */
+import { ArrowDownIcon } from 'phosphor-react-native/src/icons/ArrowDown';
+import { ArrowDownRightIcon } from 'phosphor-react-native/src/icons/ArrowDownRight';
+import { ArrowLeftIcon } from 'phosphor-react-native/src/icons/ArrowLeft';
+import { ArrowRightIcon } from 'phosphor-react-native/src/icons/ArrowRight';
+import { ArrowUpRightIcon } from 'phosphor-react-native/src/icons/ArrowUpRight';
+import { ArrowsClockwiseIcon } from 'phosphor-react-native/src/icons/ArrowsClockwise';
+import { ArrowFatUpIcon } from 'phosphor-react-native/src/icons/ArrowFatUp';
+import { BackspaceIcon } from 'phosphor-react-native/src/icons/Backspace';
+import { GlobeIcon } from 'phosphor-react-native/src/icons/Globe';
+import { KeyboardIcon } from 'phosphor-react-native/src/icons/Keyboard';
+import { SmileyIcon } from 'phosphor-react-native/src/icons/Smiley';
+import { CaretDownIcon } from 'phosphor-react-native/src/icons/CaretDown';
+import { CaretLeftIcon } from 'phosphor-react-native/src/icons/CaretLeft';
+import { CaretRightIcon } from 'phosphor-react-native/src/icons/CaretRight';
+import { CaretUpIcon } from 'phosphor-react-native/src/icons/CaretUp';
+import { ChatCircleIcon } from 'phosphor-react-native/src/icons/ChatCircle';
+import { CheckIcon } from 'phosphor-react-native/src/icons/Check';
+import { CheckCircleIcon } from 'phosphor-react-native/src/icons/CheckCircle';
+import { ClipboardIcon } from 'phosphor-react-native/src/icons/Clipboard';
+import { DatabaseIcon } from 'phosphor-react-native/src/icons/Database';
+import { DotsThreeIcon } from 'phosphor-react-native/src/icons/DotsThree';
+import { FilePdfIcon } from 'phosphor-react-native/src/icons/FilePdf';
+import { FunnelIcon } from 'phosphor-react-native/src/icons/Funnel';
+import { GearSixIcon } from 'phosphor-react-native/src/icons/GearSix';
+import { GraphIcon } from 'phosphor-react-native/src/icons/Graph';
+import { HouseIcon } from 'phosphor-react-native/src/icons/House';
+import { ImageIcon } from 'phosphor-react-native/src/icons/Image';
+import { InfoIcon } from 'phosphor-react-native/src/icons/Info';
+import { LayoutIcon } from 'phosphor-react-native/src/icons/Layout';
+import { LightningIcon } from 'phosphor-react-native/src/icons/Lightning';
+import { LinkSimpleIcon } from 'phosphor-react-native/src/icons/LinkSimple';
+import { ListIcon } from 'phosphor-react-native/src/icons/List';
+import { MagnifyingGlassIcon } from 'phosphor-react-native/src/icons/MagnifyingGlass';
+import { MicrophoneIcon } from 'phosphor-react-native/src/icons/Microphone';
+import { MinusIcon } from 'phosphor-react-native/src/icons/Minus';
+import { PaperPlaneTiltIcon } from 'phosphor-react-native/src/icons/PaperPlaneTilt';
+import { PaperclipIcon } from 'phosphor-react-native/src/icons/Paperclip';
+import { PencilSimpleIcon } from 'phosphor-react-native/src/icons/PencilSimple';
+import { PlayIcon } from 'phosphor-react-native/src/icons/Play';
+import { PlusIcon } from 'phosphor-react-native/src/icons/Plus';
+import { PushPinIcon } from 'phosphor-react-native/src/icons/PushPin';
+import { ShareNetworkIcon } from 'phosphor-react-native/src/icons/ShareNetwork';
+import { TrashIcon } from 'phosphor-react-native/src/icons/Trash';
+import { EnvelopeIcon } from 'phosphor-react-native/src/icons/Envelope';
+import { PhoneIcon } from 'phosphor-react-native/src/icons/Phone';
+import { ShieldCheckIcon } from 'phosphor-react-native/src/icons/ShieldCheck';
+import { SparkleIcon } from 'phosphor-react-native/src/icons/Sparkle';
+import { SpeakerHighIcon } from 'phosphor-react-native/src/icons/SpeakerHigh';
+import { StopIcon } from 'phosphor-react-native/src/icons/Stop';
+import { TextAlignLeftIcon } from 'phosphor-react-native/src/icons/TextAlignLeft';
+import { TreeStructureIcon } from 'phosphor-react-native/src/icons/TreeStructure';
+import { WarningIcon } from 'phosphor-react-native/src/icons/Warning';
+import { XIcon } from 'phosphor-react-native/src/icons/X';
+import { XCircleIcon } from 'phosphor-react-native/src/icons/XCircle';
+import { BellIcon } from 'phosphor-react-native/src/icons/Bell';
+import { BriefcaseIcon } from 'phosphor-react-native/src/icons/Briefcase';
+import { BuildingsIcon } from 'phosphor-react-native/src/icons/Buildings';
+import { CalendarBlankIcon } from 'phosphor-react-native/src/icons/CalendarBlank';
+import { CameraIcon } from 'phosphor-react-native/src/icons/Camera';
+import { MoneyIcon } from 'phosphor-react-native/src/icons/Money';
+import { ChartBarIcon } from 'phosphor-react-native/src/icons/ChartBar';
+import { ClockIcon } from 'phosphor-react-native/src/icons/Clock';
+import { CodeIcon } from 'phosphor-react-native/src/icons/Code';
+import { CompassIcon } from 'phosphor-react-native/src/icons/Compass';
+import { AddressBookIcon } from 'phosphor-react-native/src/icons/AddressBook';
+import { FileTextIcon } from 'phosphor-react-native/src/icons/FileText';
+import { DownloadSimpleIcon } from 'phosphor-react-native/src/icons/DownloadSimple';
+import { EyeIcon } from 'phosphor-react-native/src/icons/Eye';
+import { FileIcon } from 'phosphor-react-native/src/icons/File';
+import { FlameIcon } from 'phosphor-react-native/src/icons/Flame';
+import { FlaskIcon } from 'phosphor-react-native/src/icons/Flask';
+import { SquaresFourIcon } from 'phosphor-react-native/src/icons/SquaresFour';
+import { HeadsetIcon } from 'phosphor-react-native/src/icons/Headset';
+import { HourglassIcon } from 'phosphor-react-native/src/icons/Hourglass';
+import { TrayIcon } from 'phosphor-react-native/src/icons/Tray';
+import { KeyIcon } from 'phosphor-react-native/src/icons/Key';
+import { StackIcon } from 'phosphor-react-native/src/icons/Stack';
+import { LifebuoyIcon } from 'phosphor-react-native/src/icons/Lifebuoy';
+import { MegaphoneIcon } from 'phosphor-react-native/src/icons/Megaphone';
+import { MonitorIcon } from 'phosphor-react-native/src/icons/Monitor';
+import { PaletteIcon } from 'phosphor-react-native/src/icons/Palette';
+import { PenNibIcon } from 'phosphor-react-native/src/icons/PenNib';
+import { ChartPieIcon } from 'phosphor-react-native/src/icons/ChartPie';
+import { AirplaneIcon } from 'phosphor-react-native/src/icons/Airplane';
+import { PulseIcon } from 'phosphor-react-native/src/icons/Pulse';
+import { ReceiptIcon } from 'phosphor-react-native/src/icons/Receipt';
+import { RocketIcon } from 'phosphor-react-native/src/icons/Rocket';
+import { HardDrivesIcon } from 'phosphor-react-native/src/icons/HardDrives';
+import { ShieldIcon } from 'phosphor-react-native/src/icons/Shield';
+import { TableIcon } from 'phosphor-react-native/src/icons/Table';
+import { TagIcon } from 'phosphor-react-native/src/icons/Tag';
+import { TargetIcon } from 'phosphor-react-native/src/icons/Target';
+import { ListChecksIcon } from 'phosphor-react-native/src/icons/ListChecks';
+import { TicketIcon } from 'phosphor-react-native/src/icons/Ticket';
+import { TrendUpIcon } from 'phosphor-react-native/src/icons/TrendUp';
+import { UploadSimpleIcon } from 'phosphor-react-native/src/icons/UploadSimple';
+import { UserIcon } from 'phosphor-react-native/src/icons/User';
+import { UsersIcon } from 'phosphor-react-native/src/icons/Users';
+import { ForkKnifeIcon } from 'phosphor-react-native/src/icons/ForkKnife';
+import { VideoCameraIcon } from 'phosphor-react-native/src/icons/VideoCamera';
+import { WalletIcon } from 'phosphor-react-native/src/icons/Wallet';
+import { MapPinIcon } from 'phosphor-react-native/src/icons/MapPin';
+import { CopyIcon } from 'phosphor-react-native/src/icons/Copy';
+import { QrCodeIcon } from 'phosphor-react-native/src/icons/QrCode';
+import { BellRingingIcon } from 'phosphor-react-native/src/icons/BellRinging';
+import { BookOpenIcon } from 'phosphor-react-native/src/icons/BookOpen';
+import { PackageIcon } from 'phosphor-react-native/src/icons/Package';
+import { CreditCardIcon } from 'phosphor-react-native/src/icons/CreditCard';
+import { ShoppingCartIcon } from 'phosphor-react-native/src/icons/ShoppingCart';
+import { FlagIcon } from 'phosphor-react-native/src/icons/Flag';
+import { FolderIcon } from 'phosphor-react-native/src/icons/Folder';
+import { GitBranchIcon } from 'phosphor-react-native/src/icons/GitBranch';
+import { HandshakeIcon } from 'phosphor-react-native/src/icons/Handshake';
+import { HardDriveIcon } from 'phosphor-react-native/src/icons/HardDrive';
+import { LaptopIcon } from 'phosphor-react-native/src/icons/Laptop';
+import { MapTrifoldIcon } from 'phosphor-react-native/src/icons/MapTrifold';
+import { QuestionIcon } from 'phosphor-react-native/src/icons/Question';
+import { CardsIcon } from 'phosphor-react-native/src/icons/Cards';
+import { TerminalWindowIcon } from 'phosphor-react-native/src/icons/TerminalWindow';
+import { TruckIcon } from 'phosphor-react-native/src/icons/Truck';
+import { WebhooksLogoIcon } from 'phosphor-react-native/src/icons/WebhooksLogo';
+import { ArrowSquareOutIcon } from 'phosphor-react-native/src/icons/ArrowSquareOut';
+import { LockIcon } from 'phosphor-react-native/src/icons/Lock';
+import { WifiHighIcon } from 'phosphor-react-native/src/icons/WifiHigh';
+import { PrinterIcon } from 'phosphor-react-native/src/icons/Printer';
+import { CloudArrowUpIcon } from 'phosphor-react-native/src/icons/CloudArrowUp';
+import { ReceiptXIcon } from 'phosphor-react-native/src/icons/ReceiptX';
+import { TrophyIcon } from 'phosphor-react-native/src/icons/Trophy';
+import { StarIcon } from 'phosphor-react-native/src/icons/Star';
+import { StarHalfIcon } from 'phosphor-react-native/src/icons/StarHalf';
+import { ThumbsUpIcon } from 'phosphor-react-native/src/icons/ThumbsUp';
+import { UserCheckIcon } from 'phosphor-react-native/src/icons/UserCheck';
+import { IdentificationCardIcon } from 'phosphor-react-native/src/icons/IdentificationCard';
+import { CircleNotchIcon } from 'phosphor-react-native/src/icons/CircleNotch';
+import { ExclamationMarkIcon } from 'phosphor-react-native/src/icons/ExclamationMark';
+import { View } from 'react-native';
+import { useDs } from '../tokens';
+import { useReduceMotion } from './platform';
+
+/**
+ * Only what the field renderers need. This is not the app's full 37-glyph map — a library
+ * shipping glyphs nothing imports is the barrel problem again, one level up.
+ */
+const GLYPHS = {
+  home: HouseIcon,
+  canvas: LayoutIcon,
+  autos: TreeStructureIcon,
+  shortcuts: LightningIcon,
+  links: LinkSimpleIcon,
+  clips: ClipboardIcon,
+  data: DatabaseIcon,
+  settings: GearSixIcon,
+  admin: ShieldCheckIcon,
+  'chev-l': CaretLeftIcon,
+  'chev-r': CaretRightIcon,
+  'chev-d': CaretDownIcon,
+  'chev-u': CaretUpIcon,
+  'arrow-d': ArrowDownIcon,
+  'arrow-l': ArrowLeftIcon,
+  back: ArrowLeftIcon,
+  plus: PlusIcon,
+  bolt: LightningIcon,
+  close: XIcon,
+  'x-circle': XCircleIcon,
+  edit: PencilSimpleIcon,
+  search: MagnifyingGlassIcon,
+  funnel: FunnelIcon,
+  refresh: ArrowsClockwiseIcon,
+  play: PlayIcon,
+  pin: PushPinIcon,
+  share: ShareNetworkIcon,
+  /* Delete as an icon — the collection screen's top-right control (14 Sep 2026). */
+  trash: TrashIcon,
+  mail: EnvelopeIcon,
+  phone: PhoneIcon,
+  more: DotsThreeIcon,
+  menu: ListIcon,
+  mic: MicrophoneIcon,
+  chat: ChatCircleIcon,
+  send: PaperPlaneTiltIcon,
+  sound: SpeakerHighIcon,
+  stop: StopIcon,
+  spark: SparkleIcon,
+  tick: CheckIcon,
+  check: CheckCircleIcon,
+  alert: WarningIcon,
+  'file-pdf': FilePdfIcon,
+  'file-other': PaperclipIcon,
+  text: TextAlignLeftIcon,
+  action: LightningIcon,
+  flow: GraphIcon,
+  media: ImageIcon,
+  minus: MinusIcon,
+  /* A link that goes somewhere, a before → after, and a delta's direction — each was a typed arrow (14 Sep 2026). */
+  'arrow-r': ArrowRightIcon,
+  'trend-up': ArrowUpRightIcon,
+  'trend-down': ArrowDownRightIcon,
+  info: InfoIcon,
+  /* App 1's Keyboard tab and its mock keyboard (14 Sep 2026): the tab's own mark, and the standard controls the mock
+     draws. The real keyboards use the platform's glyphs for these; the app has only this set. */
+  keyboard: KeyboardIcon,
+  shift: ArrowFatUpIcon,
+  backspace: BackspaceIcon,
+  globe: GlobeIcon,
+  emoji: SmileyIcon,
+  caretDown: CaretDownIcon,
+  caretLeft: CaretLeftIcon,
+  /* The onboarding components' glyphs (Solarium onboarding handoff `ICONS`, 24 Sep 2026) — the handoff's
+     24-grid set mapped to their Phosphor equivalents. No brand logos: providers are a tile plus a name. */
+  bell: BellIcon,
+  briefcase: BriefcaseIcon,
+  building: BuildingsIcon,
+  calendar: CalendarBlankIcon,
+  camera: CameraIcon,
+  cash: MoneyIcon,
+  chart: ChartBarIcon,
+  clock: ClockIcon,
+  code: CodeIcon,
+  compass: CompassIcon,
+  contacts: AddressBookIcon,
+  doc: FileTextIcon,
+  download: DownloadSimpleIcon,
+  eye: EyeIcon,
+  file: FileIcon,
+  flame: FlameIcon,
+  flask: FlaskIcon,
+  grid: SquaresFourIcon,
+  headset: HeadsetIcon,
+  hourglass: HourglassIcon,
+  inbox: TrayIcon,
+  key: KeyIcon,
+  layers: StackIcon,
+  layout: LayoutIcon,
+  lifebuoy: LifebuoyIcon,
+  megaphone: MegaphoneIcon,
+  monitor: MonitorIcon,
+  palette: PaletteIcon,
+  pen: PenNibIcon,
+  pie: ChartPieIcon,
+  plane: AirplaneIcon,
+  pulse: PulseIcon,
+  receipt: ReceiptIcon,
+  rocket: RocketIcon,
+  server: HardDrivesIcon,
+  shield: ShieldIcon,
+  table: TableIcon,
+  tag: TagIcon,
+  target: TargetIcon,
+  tasks: ListChecksIcon,
+  ticket: TicketIcon,
+  trend: TrendUpIcon,
+  upload: UploadSimpleIcon,
+  user: UserIcon,
+  users: UsersIcon,
+  utensils: ForkKnifeIcon,
+  video: VideoCameraIcon,
+  wallet: WalletIcon,
+  'map-pin': MapPinIcon,
+  copy: CopyIcon,
+  qr: QrCodeIcon,
+  link: LinkSimpleIcon,
+  /* The onboarding batch-2 glyphs (24 Sep 2026). `external` is the handoff's ExternalLink and closes
+     its open decision §5.2 together with `shield`, already here. */
+  'bell-ringing': BellRingingIcon,
+  book: BookOpenIcon,
+  box: PackageIcon,
+  card: CreditCardIcon,
+  cart: ShoppingCartIcon,
+  flag: FlagIcon,
+  folder: FolderIcon,
+  git: GitBranchIcon,
+  handshake: HandshakeIcon,
+  'hard-drive': HardDriveIcon,
+  laptop: LaptopIcon,
+  map: MapTrifoldIcon,
+  question: QuestionIcon,
+  template: CardsIcon,
+  terminal: TerminalWindowIcon,
+  truck: TruckIcon,
+  webhook: WebhooksLogoIcon,
+  external: ArrowSquareOutIcon,
+  lock: LockIcon,
+  wifi: WifiHighIcon,
+  printer: PrinterIcon,
+  'cloud-up': CloudArrowUpIcon,
+  'receipt-x': ReceiptXIcon,
+  /* The batch-3 glyphs (notification + verification, 25 Sep 2026). With `key`, `wallet`, `file`,
+     `download`, `upload`, `shield` and `clock` already here, they close that handoff's open
+     decision §5.4 — every placeholder SVG it names is in the registry. `spinner` is the 16px arc
+     the handoff turns at 900ms (the caller rotates it; see the onboarding `Spinner`); `exclamation`
+     is the "!" of a failed job or check, drawn inside its own apricot circle. */
+  trophy: TrophyIcon,
+  star: StarIcon,
+  /* Batch 6 (reviews & insight): the half star of a 4.5 rating, and Feed's Helpful. */
+  'star-half': StarHalfIcon,
+  'thumbs-up': ThumbsUpIcon,
+  'user-check': UserCheckIcon,
+  'id-card': IdentificationCardIcon,
+  spinner: CircleNotchIcon,
+  exclamation: ExclamationMarkIcon,
+} as const;
+
+export type IconName = keyof typeof GLYPHS;
+
+export type IconProps = {
+  name: IconName;
+  size?: number;
+  color?: string;
+  /**
+   * Phosphor's Fill weight. **Reserved for the active tab glyph** — regular everywhere else,
+   * because Phosphor is drawn as an optical set and its Regular holds at small sizes.
+   */
+  filled?: boolean;
+  /** A continuous rotation, for a glyph that means *working*. Honours Reduce Motion. */
+  spin?: boolean;
+  /**
+   * What the glyph SAYS, when it carries meaning on its own.
+   *
+   * A tick standing in for `true` is content, not decoration — without this a screen reader
+   * reaches the cell and finds nothing there. Omit it when the glyph is beside its own label,
+   * where reading it out loud would say everything twice.
+   */
+  label?: string;
+  /**
+   * Weight is a material decision, so it is fixed here rather than exposed. The system draws
+   * regular; a heavier glyph beside body text reads as emphasis nobody asked for.
+   */
+};
+
+/**
+ * A glyph. **Never a character** — `✓` and `✗` in a `Text` node are a defect in this codebase,
+ * not a shorthand, and that rule is why the stepper's controls cost an SVG dependency.
+ */
+export function Icon({ name, size = 16, color, label, filled, spin }: IconProps) {
+  const { colors } = useDs();
+  const reduced = useReduceMotion();
+  const Glyph = GLYPHS[name];
+  const glyph = (
+    <Glyph size={size} color={color ?? colors.textSecondary} weight={filled ? 'fill' : 'regular'} />
+  );
+
+  /* A spinner that ignores Reduce Motion is the one animation users most often turn it off FOR. */
+  if (spin && !reduced) {
+    return (
+      <View
+        accessible={label !== undefined}
+        accessibilityLabel={label}
+        style={{ transform: [{ rotate: '0deg' }] }}>
+        {glyph}
+      </View>
+    );
+  }
+
+  /* Phosphor's own props do not include the accessibility fields, so the label goes on a wrapper
+     rather than on the glyph. Unlabelled, the icon stays out of the accessibility tree entirely —
+     a decorative mark that announces itself is noise, and most icons here sit beside their own
+     text. */
+  if (label === undefined) return glyph;
+  return (
+    <View accessible accessibilityRole="image" accessibilityLabel={label} aria-label={label}>
+      {glyph}
+    </View>
+  );
+}

package/src/core/Image.tsx

@@ -0,0 +1,31 @@
+import { Image as RNImage, type ImageResizeMode, type StyleProp, type ImageStyle } from 'react-native';
+import { radiusFor, type RadiusToken } from './roles';
+
+export type ImageProps = {
+  source: { uri: string } | number;
+  width?: number;
+  height?: number;
+  radius?: RadiusToken;
+  resizeMode?: ImageResizeMode;
+  /**
+   * Required, and not optional with a default of `''`.
+   *
+   * A decorative image passes `alt=""` deliberately; the type will not let it be forgotten,
+   * because a forgotten alt and an intentionally empty one are indistinguishable afterwards.
+   */
+  alt: string;
+  style?: StyleProp<ImageStyle>;
+};
+
+export function Image({ source, width, height, radius, resizeMode = 'cover', alt, style }: ImageProps) {
+  return (
+    <RNImage
+      source={source}
+      resizeMode={resizeMode}
+      alt={alt}
+      accessibilityLabel={alt || undefined}
+      accessibilityElementsHidden={alt === ''}
+      style={[{ width, height, borderRadius: radius ? radiusFor(radius) : undefined }, style]}
+    />
+  );
+}