@appinternalleads/ui 0.2.0

package/src/core/Text.tsx

@@ -0,0 +1,114 @@
+import type { ReactNode } from 'react';
+import { Platform, Text as RNText, type StyleProp, type TextStyle } from 'react-native';
+import { type as typeScale, useDs } from '../tokens';
+import { inkFor, type InkToken } from './roles';
+
+/**
+ * **Tabular figures need both spellings, and finding that out is what C0.4 was for.**
+ *
+ * `react-native-web@0.21` DROPS `fontVariant: ['tabular-nums']` — it emits no CSS at all for it,
+ * silently. The web property is `font-variant-numeric`, which RNW passes through under its own
+ * name. So the RN spelling is correct on native and inert on web, and the web spelling is
+ * correct on web and inert on native; both are needed and neither warns.
+ *
+ * This is not cosmetic. The widget contract makes tabular figures load-bearing — *ranked scores
+ * and stats values sit in columns and proportional figures make columns wobble* — and
+ * `packages/ds/src/values.tsx` in the app uses the RN spelling alone. Every numeric column in
+ * that file loses its alignment the moment it renders on web, with nothing to report it.
+ */
+const TABULAR = Platform.select({
+  web: { fontVariantNumeric: 'tabular-nums' } as unknown as TextStyle,
+  default: { fontVariant: ['tabular-nums' as const] } as TextStyle,
+});
+
+export type TextVariant = keyof typeof typeScale;
+
+export type TextProps = {
+  children?: ReactNode;
+  /** A rung on the type scale. There is no `fontSize` prop — that is the whole point. */
+  variant?: TextVariant;
+  /** Ink only. A ground token does not compile here — see `roles.ts`. */
+  color?: InkToken;
+  /**
+   * **A number a human typed is Switzer; a number the system computed is mono.**
+   *
+   * So this is not "is it a number" — a stepper's value is a number and stays sans, because it
+   * is the user's own answer. It is *did the machine produce this*: ids, counts, timestamps,
+   * durations, triggers.
+   */
+  mono?: boolean;
+  /**
+   * Tabular figures. Required wherever values stack into a column, because proportional
+   * figures make a column wobble — and useful on any value that changes in place, so the
+   * layout does not twitch as a digit changes width.
+   */
+  numeric?: boolean;
+  align?: TextStyle['textAlign'];
+  numberOfLines?: number;
+  uppercase?: boolean;
+  style?: StyleProp<TextStyle>;
+  nativeID?: string;
+  role?: 'heading' | 'link';
+  /**
+   * The heading's depth, 1–6. **Required alongside `role="heading"`**, because without it
+   * `react-native-web` renders every heading as `<h1>` — so a card with a title and three section
+   * titles silently emits four top-level headings and destroys the page's outline.
+   *
+   * An embedded card is not the top of the document, so its own title is normally level 2 and
+   * anything nested inside it level 3.
+   */
+  'aria-level'?: number;
+  /**
+   * Present only where the text itself is the target — a link value. A tappable Text inside an
+   * already-pressable row steals the row's tap area, which is why `LinkValue` can turn it off.
+   */
+  onPress?: () => void;
+  'aria-label'?: string;
+  'aria-labelledby'?: string;
+  accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
+  accessibilityElementsHidden?: boolean;
+  importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants';
+};
+
+/**
+ * The text primitive.
+ *
+ * Every glyph in the product goes through here, and it takes a scale rung rather than a size so
+ * that the eight-font-size drift `widgetPart` was created after cannot happen in the type layer
+ * too.
+ */
+export function Text({
+  children, variant = 'body', color = 'textPrimary', mono, numeric,
+  align, numberOfLines, uppercase, style, nativeID, role, onPress,
+  'aria-level': ariaLevel,
+  'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy,
+  accessibilityLiveRegion, accessibilityElementsHidden, importantForAccessibility,
+}: TextProps) {
+  const { colors, fonts } = useDs();
+  return (
+    <RNText
+      nativeID={nativeID}
+      role={role}
+      aria-level={ariaLevel}
+      onPress={onPress}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      accessibilityLiveRegion={accessibilityLiveRegion}
+      accessibilityElementsHidden={accessibilityElementsHidden}
+      importantForAccessibility={importantForAccessibility}
+      numberOfLines={numberOfLines}
+      style={[
+        {
+          ...typeScale[variant],
+          fontFamily: mono ? fonts.mono : fonts.sans,
+          color: inkFor(colors, color),
+          textAlign: align,
+          textTransform: uppercase ? 'uppercase' : undefined,
+        },
+        numeric && TABULAR,
+        style,
+      ]}>
+      {children}
+    </RNText>
+  );
+}

package/src/core/blockMotion.ts

@@ -0,0 +1,152 @@
+import { useEffect, useRef, useState } from 'react';
+import { Animated, Easing } from 'react-native';
+import { motionFor, type MotionTokens } from '../tokens';
+import { useReduceMotion } from './platform';
+
+/**
+ * **Solarium block motion — the Solarium 0.2.0 set, on one duration.**
+ *
+ * 0.2.0: *"one duration, one easing, state transitions only, no entrance sequences"* — every
+ * transition is `--motion-state` (160ms, `cubic-bezier(.2,0,0,1)`), with three allowed exceptions:
+ * progress fill (M6), value cross-fade (M5) and list add/remove (M14, `--motion-list` 240ms).
+ * M1 (enter) and M12 (celebration) are dropped. Every number comes from `motionFor()`
+ * (`src/tokens/profile.ts`); nothing in this file is a timing.
+ *
+ * | Hook | Motions | Shape |
+ * |---|---|---|
+ * | `usePresence` | M14 list add/remove · M2 exit · M10 overlay | animate out → unmount; animate in only when asked (M14 add) |
+ * | `useTween` | M3 expand · M6 fill · M7 select · M13 micro | one value eased to a target |
+ * | `useSwap` | M4 swap · M8 press label · M9 status | content keyed; a new key fades in |
+ * | `useTick` | M5 value cross-fade | the old value fades out while the new one fades in, one cell |
+ *
+ * **Reduced motion is decided here, once:** opacity only, M5 and M6 jump to the final value, M14
+ * adds and removes instantly.
+ *
+ * `useNativeDriver: false` throughout: react-native-web has no native driver, and height/colour
+ * cannot use one on native either. The RN animation driver is still an open 0.2.0 decision; these
+ * hooks stay on `Animated`, the engine the library already ships.
+ */
+
+/** The 0.2.0 motion tokens, flagged under reduced motion. The one read every block makes. */
+export function useBlockMotion(): MotionTokens {
+  return motionFor(useReduceMotion());
+}
+
+export function easingFor(m: MotionTokens): (t: number) => number {
+  return Easing.bezier(m.ease[0], m.ease[1], m.ease[2], m.ease[3]);
+}
+
+type Speed = 'state' | 'list';
+
+/**
+ * **M14 list add/remove · M2 exit · M10 overlay.** Keeps a child mounted through its exit.
+ *
+ * `visible` false → fades out (and lifts `distance` px), then `mounted` goes false, so the caller
+ * removes the node only after the motion. `appear` animates the FIRST mount too — only for a row
+ * added to a list (M14); 0.2.0 has no entrance animation, so the default is to appear at rest.
+ * Reduced motion: an exit unmounts at once and nothing ever moves.
+ */
+export function usePresence(
+  visible: boolean,
+  opts: { distance?: number; speed?: Speed; appear?: boolean } = {},
+): { mounted: boolean; opacity: Animated.Value; translateY: Animated.Value } {
+  const { distance = 6, speed = 'state', appear = false } = opts;
+  const m = useBlockMotion();
+  const [mounted, setMounted] = useState(visible);
+  const opacity = useRef(new Animated.Value(visible && !appear ? 1 : 0)).current;
+  const translateY = useRef(new Animated.Value(visible && !appear ? 0 : -distance)).current;
+  const first = useRef(true);
+
+  useEffect(() => {
+    /* No entrance sequence (0.2.0): a node that mounts visible is simply there. */
+    if (first.current) { first.current = false; if (visible && !appear) return; }
+    if (visible) setMounted(true);
+    if (!visible && m.reduced) {
+      opacity.setValue(0);
+      setMounted(false);
+      return;
+    }
+    const move = m.reduced ? 0 : -distance;
+    if (visible && m.reduced) translateY.setValue(0);
+    const anim = Animated.parallel([
+      Animated.timing(opacity, { toValue: visible ? 1 : 0, duration: m[speed], easing: easingFor(m), useNativeDriver: false }),
+      Animated.timing(translateY, { toValue: visible ? 0 : move, duration: m[speed], easing: easingFor(m), useNativeDriver: false }),
+    ]);
+    anim.start(({ finished }) => {
+      if (finished && !visible) setMounted(false);
+    });
+    return () => anim.stop();
+  }, [visible, m.reduced, m[speed], distance]);
+
+  return { mounted, opacity, translateY };
+}
+
+/**
+ * **M3 expand · M6 fill · M7 select · M13 micro.** One value eased toward `target` at
+ * `--motion-state`. A tween is state made visible, so under reduced motion it jumps.
+ */
+export function useTween(target: number): Animated.Value {
+  const m = useBlockMotion();
+  const value = useRef(new Animated.Value(target)).current;
+  useEffect(() => {
+    if (m.reduced) {
+      value.setValue(target);
+      return;
+    }
+    const anim = Animated.timing(value, { toValue: target, duration: m.state, easing: easingFor(m), useNativeDriver: false });
+    anim.start();
+    return () => anim.stop();
+  }, [target, m.reduced, m.state]);
+  return value;
+}
+
+/**
+ * **M4 swap · M8 press label · M9 status.** Content identified by `key`; a new key fades in at
+ * `--motion-state`. The old content is replaced, not kept beside it — "in one grid cell" — so
+ * layout never holds two copies and a screen reader never reads both.
+ */
+export function useSwap(key: string): Animated.Value {
+  const m = useBlockMotion();
+  const opacity = useRef(new Animated.Value(1)).current;
+  const first = useRef(true);
+  useEffect(() => {
+    if (first.current) { first.current = false; return; }
+    opacity.setValue(m.reduced ? 1 : 0);
+    if (m.reduced) return;
+    const anim = Animated.timing(opacity, { toValue: 1, duration: m.state, easing: easingFor(m), useNativeDriver: false });
+    anim.start();
+    return () => anim.stop();
+  }, [key]);
+  return opacity;
+}
+
+/**
+ * **M5 — a value cross-fade (Solarium 0.2.0).** Returns the value on its way out and a 0→1
+ * progress at `--motion-state`: the caller stacks the two in one cell, the old at `1 - progress`, the
+ * new at `progress`. No travel — the Building Blocks handoff's ±100% slide was retired by 0.2.0.
+ * Reduced motion: `previous` is null and the new value is simply there.
+ */
+export function useTick<T>(value: T): { previous: T | null; progress: Animated.Value } {
+  const m = useBlockMotion();
+  const progress = useRef(new Animated.Value(1)).current;
+  const [state, setState] = useState<{ previous: T | null; shown: T }>({ previous: null, shown: value });
+  useEffect(() => {
+    if (Object.is(value, state.shown)) return;
+    if (m.reduced) {
+      progress.setValue(1);
+      setState({ previous: null, shown: value });
+      return;
+    }
+    progress.setValue(0);
+    setState({ previous: state.shown, shown: value });
+    const anim = Animated.timing(progress, { toValue: 1, duration: m.state, easing: easingFor(m), useNativeDriver: false });
+    anim.start(({ finished }) => { if (finished) setState(s => ({ ...s, previous: null })); });
+    return () => anim.stop();
+  }, [value]);
+  return { previous: state.previous, progress };
+}
+
+/** `Animated.Value` has no public getter in its types; RN's own internals use this one. */
+export function readValue(v: Animated.Value): number {
+  return (v as unknown as { __getValue(): number }).__getValue();
+}

package/src/core/focusVisible.ts

@@ -0,0 +1,33 @@
+/**
+ * **`:focus-visible` for React Native Web — which input moved focus last.**
+ *
+ * react-native-web cannot express the `:focus-visible` pseudo-class in a style object, and a ring on
+ * every mouse click is the thing `:focus-visible` exists to prevent. So the same heuristic the browser
+ * uses is kept here: a key press puts the page in keyboard modality, a pointer press takes it out.
+ * `Pressable` shows the focus ring only when it is focused AND the modality is keyboard — which also
+ * covers roving focus (arrow keys move focus with `.focus()` right after a keydown).
+ *
+ * On native there is no `document`; focus only moves by keyboard or switch access there, so a focused
+ * control always shows its ring.
+ */
+let keyboard = false;
+let installed = false;
+
+function install() {
+  if (installed || typeof document === 'undefined') return;
+  installed = true;
+  document.addEventListener('keydown', e => {
+    if (!e.metaKey && !e.ctrlKey && !e.altKey) keyboard = true;
+  }, true);
+  for (const type of ['mousedown', 'pointerdown', 'touchstart']) {
+    document.addEventListener(type, () => { keyboard = false; }, true);
+  }
+}
+
+install();
+
+export function isKeyboardModality(): boolean {
+  if (typeof document === 'undefined') return true;
+  install();
+  return keyboard;
+}

package/src/core/index.ts

@@ -0,0 +1,77 @@
+/**
+ * **The core primitives — twelve, and the set is closed at any moment rather than forever.**
+ *
+ * `Box` · `Text` · `Input` · `Pressable` · `Icon` · `Image` · `Scroll` · `Slider` · `DatePicker`
+ * · `Switch` · `Sheet` · `RemoteImage`. A component JSON naming anything
+ * else fails schema validation, and that is what keeps a generated component composable with a
+ * hand-written one: both bottom out in the same six things.
+ *
+ * Two properties the layer exists to hold, and everything above it stays unaware of both:
+ *
+ * 1. **Props are token names, never values.** There is no `fontSize`, no `borderWidth`, no hex.
+ *    The no-hex rule is not enforced up here; it is unexpressible.
+ * **The set has grown three times, each time for the same reason.** SPEC §4.2 fixed it at six
+ *    before any field existed. `Input` was needed because none of the six can express a text
+ *    box; `Slider` and `DatePicker` because RN ships neither; `Switch` and `Sheet` because
+ *    `EnumField` and `ToggleField` were otherwise importing `react-native` directly, which
+ *    quietly costs the property below.
+ *
+ *    **That property is the point: `react-native` is imported HERE and in the token layer, and
+ *    nowhere else.** It is what keeps a platform split cheap, and it is worth more than a fixed
+ *    count — so the set closes at any given moment rather than forever.
+ *
+ * 2. **This is where a platform split would go.** SPEC §3.1 accepts a real cost in routing web
+ *    through `react-native-web` and reserves `.web.tsx` files as the escape hatch. That hatch is
+ *    only cheap while it lives at this layer alone.
+ */
+export { Box, type BoxProps } from './Box';
+export { Text, type TextProps, type TextVariant } from './Text';
+export { Input, type InputProps } from './Input';
+export { Pressable, type PressableProps } from './Pressable';
+export { Icon, type IconName, type IconProps } from './Icon';
+export { Arc, type ArcProps, type ArcSegment } from './Arc';
+export { Radar, type RadarDot, type RadarProps, type RadarShape } from './Radar';
+export { MotionView, useLoop, type Loop } from './Motion';
+export { useBlockMotion, usePresence, useTween, useSwap, useTick, easingFor, readValue } from './blockMotion';
+export {
+  DragArea, fractionFromAngle, valueFromFraction,
+  type DragAreaProps, type DragPoint,
+} from './Gesture';
+export { Image, type ImageProps } from './Image';
+export { Scroll, type ScrollProps } from './Scroll';
+export { Switch, type SwitchProps } from './Switch';
+export { Sheet, type SheetProps } from './Sheet';
+export { Layer, useAnchor, placeAbove, placeBelow, LAYER_MARGIN, type LayerPlacement, type LayerRect } from './Layer';
+export { openURL } from './linking';
+export { SafeArea, useInsets, useKeyboardOverlap, useReduceMotion } from './platform';
+export type { Insets, KeyboardOverlap, SafeAreaProps } from './platform.types';
+/**
+ * **The two platform-split primitives, and the only two.**
+ *
+ * Neither has a React Native built-in: native takes an optional community peer, web takes a real
+ * `<input type="range">` / `type="date">`. The `.web.tsx` file wins in a web bundler and the
+ * `.tsx` file is the native one, so the default belongs to the platform without an override.
+ *
+ * This is SPEC §3.1's escape hatch used as specified — **at the primitive layer and nowhere
+ * else**. `NumberField` and `DateField` are each one file and know nothing about platforms,
+ * which is the property that makes the hatch cheap rather than the first crack in the core.
+ */
+export { Slider } from './Slider';
+export type { SliderProps } from './Slider.types';
+export { DatePicker } from './DatePicker';
+export { Select } from './Select';
+export { ColorSwatch } from './ColorSwatch';
+export type { ColorSwatchProps } from './ColorSwatch.types';
+export { FileDrop, checkFile, extOf, formatFileSize } from './FileDrop';
+export type { FileCheck, FileDropApi, FileDropProps, PickedFile } from './FileDrop.types';
+export type { SelectOption, SelectProps } from './Select.types';
+export { RemoteImage } from './RemoteImage';
+export type { RemoteImageProps } from './RemoteImage.types';
+export type { DatePickerProps } from './DatePicker.types';
+export {
+  INK_TOKENS, GROUND_TOKENS, LINE_TOKENS,
+  inkFor, inkFor as inkHex, groundFor, lineFor, radiusFor,
+  type InkToken, type GroundToken, type LineToken, type RadiusToken,
+} from './roles';
+export { isKeyboardModality } from './focusVisible';
+export { ExternalLink } from './ExternalLink';

package/src/core/linking.ts

@@ -0,0 +1,15 @@
+import { Linking } from 'react-native';
+
+/**
+ * Open a URL, swallowing the rejection.
+ *
+ * In `core/` because it touches `react-native`, and that import lives here and in the token layer
+ * and nowhere else — the property that keeps a platform split cheap.
+ *
+ * **The failure is swallowed on purpose.** `openURL` rejects when no handler exists for the
+ * scheme, and there is nothing useful to say about that at a value's tap target: the user pressed
+ * a link and nothing opened, which they can see. Throwing would take the screen down with it.
+ */
+export function openURL(url: string): void {
+  void Linking.openURL(url).catch(() => {});
+}

package/src/core/platform.tsx

@@ -0,0 +1,101 @@
+import { useEffect, useState } from 'react';
+import { AccessibilityInfo, Dimensions, Keyboard, Platform, type EmitterSubscription } from 'react-native';
+import { SafeAreaView, useSafeAreaInsets } from 'react-native-safe-area-context';
+import type { Insets, KeyboardOverlap, SafeAreaProps } from './platform.types';
+
+export type { Insets, KeyboardOverlap, SafeAreaProps };
+
+/**
+ * **The NATIVE half of the platform capabilities.** `platform.web.tsx` is the other, and it
+ * imports no safe-area package — a browser has none of these concepts, and that package's entry
+ * drags in Flow-typed native source no web bundler can read.
+ *
+ * They live in `core/` with every other `react-native` import.
+ *
+ * These are not UI — they are the device answering questions — but they touch the same module,
+ * and the invariant is about the import, not about whether the thing draws. Keeping them here is
+ * what leaves `ds/` and `fields/` free of `react-native` entirely.
+ */
+
+/**
+ * **How much of the screen the software keyboard is covering.**
+ *
+ * Reported on BOTH platforms, and the caller pays for it on both. Android 15+ is edge-to-edge by
+ * default and `adjustResize` no longer resizes the window — the IME arrives as an inset the app
+ * must consume itself, and the system quietly ignores the manifest. The symptom is nothing like a
+ * crash: the composer sits at the bottom of a window that never shrank, so **the keyboard covers
+ * the field you are typing into.**
+ *
+ * iOS listens to `keyboardWillShow` so padding moves on the same frame the keyboard does; Android
+ * has no `will` events, and `did` is the only honest signal there.
+ */
+export function useKeyboardOverlap(): KeyboardOverlap {
+  const [overlap, setOverlap] = useState<KeyboardOverlap>({ height: 0, shown: false });
+  useEffect(() => {
+    const ios = Platform.OS === 'ios';
+    const subs: EmitterSubscription[] = [
+      Keyboard.addListener(ios ? 'keyboardWillShow' : 'keyboardDidShow', e =>
+        setOverlap({ height: e.endCoordinates.height, shown: true }),
+      ),
+      Keyboard.addListener(ios ? 'keyboardWillHide' : 'keyboardDidHide', () =>
+        setOverlap({ height: 0, shown: false }),
+      ),
+    ];
+    /**
+     * **iOS also follows the keyboard's frame while it is up** (14 Sep 2026, measured with the Padki keyboard on an iPhone).
+     * A custom keyboard resizes itself without hiding — Padki's grows when an automation form opens over its keys — and
+     * `keyboardWillShow` alone kept the first height, so a field padded by it ended up under the taller keyboard. The
+     * overlap is read from where the keyboard's top edge lands, not its height: a frame sliding off-screen measures 0.
+     */
+    if (ios) {
+      subs.push(
+        Keyboard.addListener('keyboardWillChangeFrame', e => {
+          const height = Math.max(0, Dimensions.get('screen').height - e.endCoordinates.screenY);
+          setOverlap({ height, shown: height > 0 });
+        }),
+      );
+    }
+    return () => subs.forEach(s => s.remove());
+  }, []);
+  return overlap;
+}
+
+/**
+ * The system's Reduce Motion setting.
+ *
+ * **Every animation in the system is required to honour it.** A hook rather than a one-off read
+ * because the setting can change while the app is open, and an animation that only checked at
+ * mount would keep moving after the user turned it off.
+ */
+export function useReduceMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+  useEffect(() => {
+    let alive = true;
+    /**
+     * **Both calls are guarded, because `react-native-web` does not implement either the same
+     * way.** `addEventListener` returns `undefined` there rather than a subscription, so an
+     * unguarded `sub.remove()` throws on unmount — and since this hook now runs inside `Icon`,
+     * that was every icon on every screen. It surfaced the moment a web test rendered one.
+     */
+    void AccessibilityInfo.isReduceMotionEnabled?.()
+      ?.then(v => {
+        if (alive) setReduced(v);
+      })
+      .catch(() => {});
+    const sub = AccessibilityInfo.addEventListener?.('reduceMotionChanged', setReduced);
+    return () => {
+      alive = false;
+      sub?.remove?.();
+    };
+  }, []);
+  return reduced;
+}
+
+export function useInsets(): Insets {
+  return useSafeAreaInsets();
+}
+
+/** The safe area, as a container. Applies its insets as padding rather than as a clip. */
+export function SafeArea({ children, edges = ['top', 'left', 'right'] }: SafeAreaProps) {
+  return <SafeAreaView style={{ flex: 1 }} edges={edges}>{children}</SafeAreaView>;
+}

package/src/core/platform.types.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+
+export type KeyboardOverlap = { height: number; shown: boolean };
+export type Insets = { top: number; right: number; bottom: number; left: number };
+export type SafeAreaProps = {
+  children?: ReactNode;
+  edges?: ('top' | 'bottom' | 'left' | 'right')[];
+};

package/src/core/platform.web.tsx

@@ -0,0 +1,46 @@
+import { useEffect, useState } from 'react';
+import { View } from 'react-native';
+import type { Insets, KeyboardOverlap, SafeAreaProps } from './platform.types';
+
+export type { Insets, KeyboardOverlap, SafeAreaProps };
+
+/**
+ * **The web half of the platform capabilities — and it imports no safe-area package at all.**
+ *
+ * `react-native-safe-area-context`'s entry pulls in its native spec, which imports
+ * `react-native/Libraries/Utilities/codegenNativeComponent` — Flow-typed source that no web
+ * bundler can parse. Aliasing around that is a running battle; a browser simply has none of these
+ * concepts, so the honest answer is a separate file rather than a shim.
+ *
+ * The one thing here that is genuinely BETTER than the native path is Reduce Motion:
+ * `prefers-reduced-motion` is the real web signal, where RN's `AccessibilityInfo` on
+ * `react-native-web` returns an undefined subscription and no value.
+ */
+
+/** A browser has no notch and no home indicator. */
+export function useInsets(): Insets {
+  return { top: 0, right: 0, bottom: 0, left: 0 };
+}
+
+/** Nothing to avoid: a software keyboard on the web does not overlay the viewport. */
+export function useKeyboardOverlap(): KeyboardOverlap {
+  return { height: 0, shown: false };
+}
+
+export function useReduceMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia?.('(prefers-reduced-motion: reduce)');
+    if (!mq) return;
+    setReduced(mq.matches);
+    const on = (e: MediaQueryListEvent) => setReduced(e.matches);
+    mq.addEventListener('change', on);
+    return () => mq.removeEventListener('change', on);
+  }, []);
+  return reduced;
+}
+
+/** No insets to apply, so this is the container and nothing more. */
+export function SafeArea({ children }: SafeAreaProps) {
+  return <View style={{ flex: 1 }}>{children}</View>;
+}

package/src/core/roles.ts

@@ -0,0 +1,93 @@
+import type { Colors, Kind, Status } from '../tokens';
+import { radii, widgetPart } from '../tokens';
+
+/**
+ * **The palette, partitioned by role — and this is the load-bearing idea in the core.**
+ *
+ * SPEC §5.2 makes colour resolution role-scoped so that a generator cannot put a ground token on
+ * a text colour. Expressing the partition as a TYPE moves the same guarantee to hand-written
+ * code, which the generator's resolver could never reach.
+ *
+ * The rule it enforces is the widget contract's one ⚠ hard rule, locked decision 79:
+ *
+ * > `#C1502E` is 3.1:1 on white and **fails as text**. Every numeral, label and value rendered
+ * > in accent takes `#A8421F`. The fill is for backgrounds and bars only.
+ *
+ * `accentFill` is a GROUND. It is absent from `InkToken`, so `<Text color="accentFill">` does
+ * not compile — the mistake is unavailable rather than merely reviewable.
+ */
+
+/** Legal as a text colour. */
+export const INK_TOKENS = [
+  'textPrimary', 'textSecondary', 'textTertiary', 'textDisabled', 'textOnAccent',
+  'accentInk', 'accentOnFill', 'brandOnPrimary', 'alertInk',
+] as const;
+
+/** Legal as a background. */
+export const GROUND_TOKENS = [
+  'surfacePage', 'surface1', 'surface2', 'surface3', 'surfaceSunken', 'band',
+  'accentFill', 'accentTint', 'accentPressed', 'brandPrimary', 'brandSubtle', 'alertSoft',
+] as const;
+
+/** Legal as a hairline or a rule. Never as a fill, never as text. */
+export const LINE_TOKENS = ['hairline', 'hairlineStrong', 'dashed'] as const;
+
+/**
+ * The dotted forms reach the `Record`-shaped slots — `status.error`, `kind.flow`.
+ *
+ * They exist so a caller never has to drop to `useDs().colors` and pass a resolved string,
+ * which is the hole every escape hatch of this kind leaks through: a resolved string is
+ * indistinguishable from a hex at the prop boundary.
+ */
+export type InkToken =
+  | (typeof INK_TOKENS)[number]
+  | `status.${Status}`
+  | `kind.${Kind}`
+  | 'reference'
+  | 'capability';
+
+export type GroundToken =
+  | (typeof GROUND_TOKENS)[number]
+  | `statusBg.${Status}`
+  | `kindBg.${Kind}`
+  | 'referenceBg'
+  | 'capabilityBg';
+
+export type LineToken = (typeof LINE_TOKENS)[number];
+
+/** `radii` rungs, plus `widgetPart` under a `part.` prefix. */
+export type RadiusToken = keyof typeof radii | `part.${keyof typeof widgetPart}`;
+
+export function inkFor(colors: Colors, token: InkToken): string {
+  if (token === 'reference') return colors.reference.fg;
+  if (token === 'capability') return colors.capability.fg;
+  if (token.startsWith('status.')) return colors.status[token.slice(7) as Status];
+  if (token.startsWith('kind.')) return colors.kind[token.slice(5) as Kind].fg;
+  return colors[token as (typeof INK_TOKENS)[number]];
+}
+
+export function groundFor(colors: Colors, token: GroundToken): string {
+  if (token === 'referenceBg') return colors.reference.bg;
+  if (token === 'capabilityBg') return colors.capability.bg;
+  if (token.startsWith('statusBg.')) return colors.statusBg[token.slice(9) as Status];
+  if (token.startsWith('kindBg.')) return colors.kind[token.slice(7) as Kind].bg;
+  return colors[token as (typeof GROUND_TOKENS)[number]];
+}
+
+export function lineFor(colors: Colors, token: LineToken): string {
+  return colors[token];
+}
+
+/**
+ * `widgetPart` is checked first, per SPEC §5.1.
+ *
+ * It wins because it exists precisely to stop the drift it was created after — the widget layer
+ * had reached seven radii and eight font sizes before it was introduced. A part of a widget's
+ * interior names its rung through `part.*` and never reaches into `radii` directly.
+ */
+export function radiusFor(token: RadiusToken): number {
+  if (typeof token === 'string' && token.startsWith('part.')) {
+    return widgetPart[token.slice(5) as keyof typeof widgetPart];
+  }
+  return radii[token as keyof typeof radii];
+}