@vvedantb/native-ui 0.13.0 → 0.17.0

package/src/primitives/swipe-row-gesture.tsx

@@ -0,0 +1,290 @@
+import { useContext, useRef, useState } from "react";
+import { Pressable, StyleSheet, View } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+  cancelAnimation,
+  ReduceMotion,
+  runOnJS,
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  withTiming,
+  type SharedValue,
+} from "react-native-reanimated";
+import { impactHaptic } from "../haptics";
+import { InsidePagerContext } from "../Pager";
+import { EASE_OUT } from "../motion";
+import { palette } from "../palette";
+import type { SwipeableRowProps } from "../SwipeableRow";
+import {
+  closeSwipeRows,
+  isSwipeRowOpen,
+  markSwipeRowClosed,
+  markSwipeRowOpen,
+  SWIPE_ACTION_WIDTH,
+  SWIPE_FAIL_OFFSET_Y,
+  swipeRowActivation,
+  swipeRowArmed,
+  swipeRowOffset,
+  swipeRowSettle,
+  type SwipeAction,
+  type SwipeRowHandle,
+  type SwipeSide,
+} from "../swipeRow";
+import { tokens } from "../tokens";
+import { useScheme } from "../useScheme";
+import { useWebClickGuard } from "./web-click-guard";
+
+// The swipeable row on Gesture Handler: the track phase and the release run
+// as worklets on the UI thread, so the row never lags the finger. The rules
+// are plain worklets in `swipeRow`.
+
+/** The release: springs on at the finger's speed, no bounce (a row overshooting rest would flash the other side). */
+const ROW_SPRING = { duration: 250, dampingRatio: 1, reduceMotion: ReduceMotion.System } as const;
+
+/** The armed full swipe: the first action's icon grows a little, with the haptic, so the commit shows without it. */
+const ARMED_SCALE = 1.15;
+const ARMED_TIMING = { duration: 150, easing: EASE_OUT, reduceMotion: ReduceMotion.System } as const;
+
+const ICON_SIZE = 20;
+
+/** Each tone's fill and the icon colour on it. */
+const TONES = {
+  default: { fill: palette.primary, icon: palette.primaryForeground },
+  warning: { fill: palette.warning, icon: palette.warningForeground },
+  danger: { fill: palette.danger, icon: palette.dangerForeground },
+} as const;
+
+export function GestureSwipeableRow({
+  leadingActions = [],
+  trailingActions = [],
+  enabled = true,
+  backgroundColor,
+  children,
+}: SwipeableRowProps) {
+  const scheme = useScheme();
+  const x = useSharedValue(0);
+  const width = useSharedValue(0);
+  // Where the row was when the finger caught it.
+  const start = useSharedValue(0);
+  const dragging = useSharedValue(false);
+  const armed = useSharedValue<SwipeSide | null>(null);
+  const armedScale = useSharedValue(1);
+  // Plain values for the worklets: they must not capture the actions' functions.
+  const leading = leadingActions.length * SWIPE_ACTION_WIDTH;
+  const trailing = trailingActions.length * SWIPE_ACTION_WIDTH;
+  const leadingExits = leadingActions[0]?.exits === true;
+  const trailingExits = trailingActions[0]?.exits === true;
+  const [handle] = useState<SwipeRowHandle>(() => ({ close: () => x.set(withSpring(0, ROW_SPRING)) }));
+
+  // Whether this touch began while a row was open, so its release only closes that row. Nothing renders from it.
+  const closesOnRelease = useRef(false);
+  const webClicks = useWebClickGuard(isSwipeRowOpen);
+  const insidePager = useContext(InsidePagerContext);
+  const opened = () => {
+    closesOnRelease.current = false;
+    webClicks.swallowNext();
+    markSwipeRowOpen(handle);
+  };
+  const closed = () => markSwipeRowClosed(handle);
+  const firstOf = (side: SwipeSide) => (side === "leading" ? leadingActions[0] : trailingActions[0]);
+  /** Runs an action once the row slid out: if it fails, the row comes back. */
+  const runExited = (action: SwipeAction | undefined) => {
+    const result = action?.onPress();
+    if (result instanceof Promise) result.catch(() => x.set(withSpring(0, ROW_SPRING)));
+  };
+  // The worklets take sides, never the actions (their functions stay on the JavaScript thread).
+  const runFirstExited = (side: SwipeSide) => runExited(firstOf(side));
+  const runFirstInPlace = (side: SwipeSide) => void firstOf(side)?.onPress();
+  /** A tapped button: the row closes, or slides out for an action that exits, then the action runs. */
+  const press = (action: SwipeAction, side: SwipeSide) => {
+    closed();
+    if (!action.exits) {
+      x.set(withSpring(0, ROW_SPRING));
+      void action.onPress();
+      return;
+    }
+    const run = () => runExited(action);
+    x.set(
+      withSpring(side === "leading" ? width.get() : -width.get(), { ...ROW_SPRING, overshootClamping: true }, (finished) => {
+        "worklet";
+        if (finished) runOnJS(run)();
+      }),
+    );
+  };
+
+  // The full swipe arms and disarms as the row crosses the point: the icon
+  // grows, and a light haptic fires as it arms under the finger.
+  useAnimatedReaction(
+    () => swipeRowArmed(x.get(), { leading, trailing, width: width.get() }),
+    (side, previous) => {
+      if (side === previous) return;
+      armed.set(side);
+      armedScale.set(withTiming(side ? ARMED_SCALE : 1, ARMED_TIMING));
+      if (side && dragging.get()) runOnJS(impactHaptic)("light");
+    },
+    [leading, trailing],
+  );
+
+  // Built on each render (for `enabled` and the actions): the detector keeps
+  // the same handler, and a drag in flight, and only takes the new config.
+  const activation = swipeRowActivation({ leading, trailing }, insidePager);
+  const pan = Gesture.Pan()
+    .enabled(enabled && leading + trailing > 0)
+    // Sideways intent first; a drag that goes vertical first is the list's scroll.
+    .activeOffsetX(activation.activeOffsetX)
+    .failOffsetY([-SWIPE_FAIL_OFFSET_Y, SWIPE_FAIL_OFFSET_Y]);
+  if (activation.failOffsetX !== undefined) pan.failOffsetX(activation.failOffsetX);
+  pan
+    .onStart(() => {
+      cancelAnimation(x);
+      start.set(x.get());
+      dragging.set(true);
+      runOnJS(opened)();
+    })
+    // Track phase: one shared value write per frame, on the UI thread.
+    .onUpdate((event) => {
+      x.set(swipeRowOffset(start.get() + event.translationX, { leading, trailing, width: width.get() }));
+    })
+    .onEnd((event, success) => {
+      dragging.set(false);
+      const rowWidth = width.get();
+      const settle = swipeRowSettle(x.get(), event.velocityX, { leading, trailing, width: rowWidth });
+      const velocity = event.velocityX;
+      if (success && settle.kind === "commit") {
+        // Armed by the fling rather than the position: the haptic fires now, with the commit.
+        if (armed.get() === null) runOnJS(impactHaptic)("light");
+        runOnJS(closed)();
+        const side = settle.side;
+        if (side === "leading" ? leadingExits : trailingExits) {
+          x.set(
+            withSpring(side === "leading" ? rowWidth : -rowWidth, { ...ROW_SPRING, velocity, overshootClamping: true }, (finished) => {
+              "worklet";
+              if (finished) runOnJS(runFirstExited)(side);
+            }),
+          );
+        } else {
+          x.set(withSpring(0, { ...ROW_SPRING, velocity }));
+          runOnJS(runFirstInPlace)(side);
+        }
+        return;
+      }
+      if (settle.kind === "open") {
+        x.set(withSpring(settle.side === "leading" ? leading : -trailing, { ...ROW_SPRING, velocity }));
+        return;
+      }
+      x.set(withSpring(0, { ...ROW_SPRING, velocity }));
+      runOnJS(closed)();
+    })
+    .onFinalize(() => {
+      dragging.set(false);
+    });
+
+  const rowStyle = useAnimatedStyle(() => ({ transform: [{ translateX: x.get() }] }));
+  return (
+    <View onLayout={(event) => width.set(event.nativeEvent.layout.width)} style={styles.clip}>
+      {leadingActions.length > 0 ? (
+        <ActionStrip side="leading" actions={leadingActions} x={x} armedScale={armedScale} onPress={press} />
+      ) : null}
+      {trailingActions.length > 0 ? (
+        <ActionStrip side="trailing" actions={trailingActions} x={x} armedScale={armedScale} onPress={press} />
+      ) : null}
+      <GestureDetector gesture={pan}>
+        <Animated.View style={[{ backgroundColor: backgroundColor ?? tokens.color.background[scheme] }, rowStyle]}>
+          <View
+            ref={webClicks.ref}
+            // While a row is open, a tap on any row only closes it: the row
+            // takes the touch from the pressables inside.
+            onStartShouldSetResponderCapture={() => {
+              closesOnRelease.current = isSwipeRowOpen();
+              return closesOnRelease.current;
+            }}
+            onResponderRelease={() => {
+              if (closesOnRelease.current) closeSwipeRows();
+            }}
+          >
+            {children}
+          </View>
+        </Animated.View>
+      </GestureDetector>
+    </View>
+  );
+}
+
+/**
+ * One side's actions behind the row, the first at the screen edge, on the
+ * first action's fill (which stretches with a full swipe). Shown only while
+ * the row moves toward that side. Hidden from screen readers: they reach the
+ * actions on the row itself (`swipeActionsAccessibility`).
+ */
+function ActionStrip({
+  side,
+  actions,
+  x,
+  armedScale,
+  onPress,
+}: {
+  side: SwipeSide;
+  actions: readonly SwipeAction[];
+  x: SharedValue<number>;
+  armedScale: SharedValue<number>;
+  onPress: (action: SwipeAction, side: SwipeSide) => void;
+}) {
+  const scheme = useScheme();
+  const reveal = actions.length * SWIPE_ACTION_WIDTH;
+  const direction = side === "leading" ? 1 : -1;
+  const stripStyle = useAnimatedStyle(() => ({ opacity: x.get() * direction > 0 ? 1 : 0 }));
+  // Past its slot the first icon keeps beside the row's edge, so it stays in view.
+  const firstIconStyle = useAnimatedStyle(() => ({
+    transform: [
+      { translateX: direction * Math.max(0, Math.abs(x.get()) - reveal) },
+      { scale: armedScale.get() },
+    ],
+  }));
+  return (
+    <Animated.View
+      aria-hidden
+      importantForAccessibility="no-hide-descendants"
+      style={[
+        StyleSheet.absoluteFill,
+        { flexDirection: side === "leading" ? "row" : "row-reverse" },
+        { backgroundColor: TONES[actions[0]?.tone ?? "default"].fill[scheme] },
+        stripStyle,
+      ]}
+    >
+      {actions.map((action, index) => {
+        const tone = TONES[action.tone ?? "default"];
+        const Icon = action.icon;
+        return (
+          <Pressable
+            key={action.key}
+            accessibilityRole="button"
+            accessibilityLabel={action.label}
+            onPress={() => onPress(action, side)}
+            style={[styles.action, { backgroundColor: tone.fill[scheme] }]}
+          >
+            {index === 0 ? (
+              <Animated.View style={firstIconStyle}>
+                <Icon size={ICON_SIZE} color={tone.icon[scheme]} />
+              </Animated.View>
+            ) : (
+              <Icon size={ICON_SIZE} color={tone.icon[scheme]} />
+            )}
+          </Pressable>
+        );
+      })}
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  clip: {
+    overflow: "hidden",
+  },
+  action: {
+    width: SWIPE_ACTION_WIDTH,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+});

package/src/primitives/toast-drag-gesture.tsx

@@ -0,0 +1,92 @@
+import { View } from "react-native";
+import { Gesture, GestureDetector, GestureHandlerRootView } from "react-native-gesture-handler";
+import Animated, {
+  cancelAnimation,
+  interpolate,
+  ReduceMotion,
+  runOnJS,
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+} from "react-native-reanimated";
+import { impactHaptic } from "../haptics";
+import {
+  TOAST_DRAG_ACTIVE_OFFSET_Y,
+  toastDragDismisses,
+  toastDragOffset,
+  type ToastDragProps,
+} from "../toastDrag";
+import { useWebClickGuard } from "./web-click-guard";
+
+// The toast drag on Gesture Handler: the track phase and the release run as
+// worklets on the UI thread. The rules are plain worklets in `toastDrag`.
+
+/** Back home after a short drag: a little bounce, as the finger applied force. */
+const HOME_SPRING = { duration: 250, dampingRatio: 0.8, reduceMotion: ReduceMotion.System } as const;
+/** Away up the screen: no overshoot back into view. */
+const AWAY_SPRING = { duration: 250, dampingRatio: 1, overshootClamping: true, reduceMotion: ReduceMotion.System } as const;
+
+export function GestureToastDrag({ onDismiss, onHoldChange, children }: ToastDragProps) {
+  const y = useSharedValue(0);
+  const height = useSharedValue(0);
+  // Where the toast was when the finger caught it, and the finger's travel then.
+  const start = useSharedValue(0);
+  const startY = useSharedValue(0);
+  const webClicks = useWebClickGuard();
+  const dismissed = () => {
+    impactHaptic("light");
+    onDismiss();
+  };
+
+  // Built on each render: the detector keeps the same handler, and a drag in flight.
+  const pan = Gesture.Pan()
+    .activeOffsetY([-TOAST_DRAG_ACTIVE_OFFSET_Y, TOAST_DRAG_ACTIVE_OFFSET_Y])
+    // The timer holds from the touch, a tap included (a tap closes the toast anyway).
+    .onBegin(() => {
+      runOnJS(onHoldChange)(true);
+    })
+    .onStart((event) => {
+      cancelAnimation(y);
+      start.set(y.get());
+      // Count from here, so the toast does not jump by the slop the drag needed to start.
+      startY.set(event.translationY);
+      runOnJS(webClicks.swallowNext)();
+    })
+    // Track phase: one shared value write per frame, on the UI thread.
+    .onUpdate((event) => {
+      y.set(toastDragOffset(start.get() + event.translationY - startY.get()));
+    })
+    .onEnd((event) => {
+      const position = y.get();
+      if (toastDragDismisses(position, event.velocityY, height.get())) {
+        // Up past its own height, fading on the way (`toastStyle`), at the finger's speed.
+        y.set(
+          withSpring(-height.get() * 1.5, { ...AWAY_SPRING, velocity: event.velocityY }, (finished) => {
+            "worklet";
+            if (finished) runOnJS(dismissed)();
+          }),
+        );
+        return;
+      }
+      y.set(withSpring(0, { ...HOME_SPRING, velocity: event.velocityY }));
+    })
+    .onFinalize(() => {
+      runOnJS(onHoldChange)(false);
+    });
+
+  // Linked to the same value: the toast fades as it rises, gone one height up.
+  const toastStyle = useAnimatedStyle(() => ({
+    opacity: height.get() > 0 ? interpolate(y.get(), [-height.get(), 0], [0, 1], "clamp") : 1,
+    transform: [{ translateY: y.get() }],
+  }));
+  return (
+    // Its own root: on iOS the toasts draw in a separate window (`FullWindowOverlay`).
+    <GestureHandlerRootView>
+      <GestureDetector gesture={pan}>
+        <Animated.View style={toastStyle} onLayout={(event) => height.set(event.nativeEvent.layout.height)}>
+          <View ref={webClicks.ref}>{children}</View>
+        </Animated.View>
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+}

package/src/primitives/web-click-guard.ts

@@ -0,0 +1,50 @@
+import { useRef } from "react";
+import { Platform, type View } from "react-native";
+
+/** The part of a DOM element the web click guard uses: on the web a `View` is a DOM element. */
+type DomNode = {
+  addEventListener: (type: string, listener: (event: DomEvent) => void, capture: boolean) => void;
+  removeEventListener: (type: string, listener: (event: DomEvent) => void, capture: boolean) => void;
+};
+type DomEvent = { stopPropagation: () => void; preventDefault: () => void };
+
+function isDomNode(node: object): node is DomNode {
+  return "addEventListener" in node && typeof node.addEventListener === "function";
+}
+
+/**
+ * On the web a pressable presses on the DOM click, which neither the touch
+ * responder nor Gesture Handler cancels (it captures the pointer on the
+ * element pressed). So, in the capture phase on the dragged content, this
+ * drops the click that ends a drag (`swallowNext`, at the drag's start).
+ * `swallowOnDown` decides afresh at each touch whether its click is dropped
+ * (a tap made while a swiped row is open). On Android and iOS it does
+ * nothing: there the drag cancels the press.
+ */
+export function useWebClickGuard(swallowOnDown: () => boolean = () => false) {
+  const swallow = useRef(false);
+  return {
+    swallowNext: () => {
+      swallow.current = true;
+    },
+    ref: (node: View | null) => {
+      if (Platform.OS !== "web" || !node || !isDomNode(node)) return;
+      const onClick = (event: DomEvent) => {
+        if (!swallow.current) return;
+        swallow.current = false;
+        event.stopPropagation();
+        event.preventDefault();
+      };
+      // Each touch starts afresh (a touch drag clicks nothing, so its flag must not outlive it).
+      const onPointerDown = () => {
+        swallow.current = swallowOnDown();
+      };
+      node.addEventListener("click", onClick, true);
+      node.addEventListener("pointerdown", onPointerDown, true);
+      return () => {
+        node.removeEventListener("click", onClick, true);
+        node.removeEventListener("pointerdown", onPointerDown, true);
+      };
+    },
+  };
+}

package/src/relativeTime.ts

@@ -0,0 +1,94 @@
+// The twin of `@vvedantb/ui`'s `formatCompactRelativeTime`
+// (`ui/app/src/time/compactRelativeTime.ts`), which `RelativeDateTime` shows.
+// The web file pulls no DOM, but the web package does, so this is a copy;
+// tests/relativeTime.test.ts checks both give the same strings.
+
+export type CompactRelativeTimeOptions = {
+  /** Clock in ms. Defaults to `Date.now()`. */
+  now?: number;
+  /**
+   * Returned for anything under a minute old, including future times. When
+   * unset the result is whole seconds (`"42s"`), and a future time gives zero
+   * or a negative count (`"0s"`, `"-300s"`).
+   */
+  justNow?: string;
+  /**
+   * `false` (default): elapsed time only. A day is 24 hours, a month 30 days,
+   * a year 12 of those months.
+   * `true`: days count local calendar days across a DST change, and months and
+   * years are calendar months, as `dayjs().diff(date, unit)` counts them.
+   */
+  calendar?: boolean;
+};
+
+const MS_PER_MINUTE = 60_000;
+const MS_PER_DAY = 86_400_000;
+
+/** Rounds toward zero; `-0` becomes `0`. */
+function truncate(n: number): number {
+  return n < 0 ? Math.ceil(n) || 0 : Math.floor(n);
+}
+
+/** Local UTC offset in minutes, rounded to 15 minutes. */
+function utcOffset(ms: number): number {
+  return -Math.round(new Date(ms).getTimezoneOffset() / 15) * 15;
+}
+
+/** Adds calendar months in local time and clamps the day to the target month. */
+function addMonths(ms: number, months: number): number {
+  const date = new Date(ms);
+  const day = date.getDate();
+  date.setDate(1);
+  date.setMonth(date.getMonth() + months);
+  const daysInMonth = new Date(date.getFullYear(), date.getMonth() + 1, 0).getDate();
+  date.setDate(Math.min(day, daysInMonth));
+  return date.getTime();
+}
+
+/** Fractional calendar months from `a` to `b`, negated (the moment.js formula). */
+function monthDiff(a: number, b: number): number {
+  if (new Date(a).getDate() < new Date(b).getDate()) return -monthDiff(b, a);
+  const from = new Date(a);
+  const to = new Date(b);
+  const whole = (to.getFullYear() - from.getFullYear()) * 12 + (to.getMonth() - from.getMonth());
+  const anchor = addMonths(a, whole);
+  const before = b - anchor < 0;
+  const anchor2 = addMonths(a, whole + (before ? -1 : 1));
+  return +(-(whole + (b - anchor) / (before ? anchor - anchor2 : anchor2 - anchor)) || 0);
+}
+
+/**
+ * Time since `date` as one compact unit: `"now"` or `"42s"`, then `"5m"`,
+ * `"3h"`, `"2d"`, `"4mo"`, `"1y"`. Strings are parsed with `new Date(string)`.
+ * An invalid date gives `"NaNy"`, or `"0mo"` with `calendar`.
+ */
+export function formatCompactRelativeTime(
+  date: string | number | Date,
+  options: CompactRelativeTimeOptions = {},
+): string {
+  const now = options.now ?? Date.now();
+  const then = new Date(date).getTime();
+  const diff = now - then;
+
+  const seconds = truncate(diff / 1000);
+  if (seconds < 60) return options.justNow ?? `${seconds}s`;
+  const minutes = truncate(diff / MS_PER_MINUTE);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = truncate(diff / (60 * MS_PER_MINUTE));
+  if (hours < 24) return `${hours}h`;
+
+  if (!options.calendar) {
+    const days = Math.floor(hours / 24);
+    if (days < 30) return `${days}d`;
+    const months = Math.floor(days / 30);
+    if (months < 12) return `${months}mo`;
+    return `${Math.floor(months / 12)}y`;
+  }
+
+  const zoneDelta = (utcOffset(then) - utcOffset(now)) * MS_PER_MINUTE;
+  const days = truncate((diff - zoneDelta) / MS_PER_DAY);
+  if (days < 30) return `${days}d`;
+  const months = monthDiff(now, then);
+  if (truncate(months) < 12) return `${truncate(months)}mo`;
+  return `${truncate(months / 12)}y`;
+}

package/src/router/RouterStackPageHeader.tsx

@@ -1,4 +1,4 @@
-import { useRouter, type Href, type Router } from "expo-router";
+import { useRouter, type Href } from "expo-router";
 import { StackPageHeader, type StackPageHeaderProps } from "../StackPageHeader";
 
 export type RouterStackPageHeaderProps = Omit<StackPageHeaderProps, "onBack"> & {
@@ -7,7 +7,7 @@ export type RouterStackPageHeaderProps = Omit<StackPageHeaderProps, "onBack"> &
 };
 
 /** Goes back when the stack has a screen below, else replaces the route with `fallbackHref`. */
-export function goBackOrReplace(router: Pick<Router, "canGoBack" | "back" | "replace">, fallbackHref: Href = "/") {
+export function goBackOrReplace(router: Pick<ReturnType<typeof useRouter>, "canGoBack" | "back" | "replace">, fallbackHref: Href = "/") {
   if (router.canGoBack()) router.back();
   else router.replace(fallbackHref);
 }

package/src/settings/SettingsEmptyState.tsx

@@ -1,10 +1,11 @@
 import type { ComponentType, ReactNode } from "react";
 import { Text, View } from "react-native";
 import type { IconProps } from "@tabler/icons-react-native";
-import { textStyle, typeStyle } from "../controlStyles";
+import { sizeStyle, textStyle, typeStyle } from "../controlStyles";
 import { useLargerText } from "../theme";
 import { tokens } from "../tokens";
 import { useScheme } from "../useScheme";
+import { relaxedSizeStyle } from "./relaxedSizeStyle";
 
 export type SettingsEmptyStateProps = {
   title: string;
@@ -17,28 +18,37 @@ export type SettingsEmptyStateProps = {
 };
 
 /**
- * A compact empty note for the inside of a `SettingsSection` (web
- * `SettingsEmptyState`): centred title, muted description and an optional
- * action, with no large icon. Use `EmptyState` for a whole screen.
+ * The empty note for the inside of a `SettingsSection` (web
+ * `SettingsEmptyState`): an optional muted icon (28, half opacity), a centred
+ * `text-sm` medium title (14 / 20 / 500), a muted `text-xs leading-relaxed`
+ * description (12 / 19.5) and an optional action, in `px-4 py-16`. Use
+ * `EmptyState` for a whole screen.
  */
 export function SettingsEmptyState({ title, description, icon: Icon, action, testID }: SettingsEmptyStateProps) {
   const scheme = useScheme();
   const largerText = useLargerText();
   return (
-    <View testID={testID} className="items-center gap-1 px-2 py-4">
-      {Icon ? <Icon size={largerText ? 24 : 20} color={tokens.color.muted[scheme]} /> : null}
+    <View testID={testID} className="items-center justify-center px-4 py-16">
+      {Icon ? (
+        <View className="mb-5 opacity-50">
+          <Icon size={largerText ? 32 : 28} color={tokens.color.muted[scheme]} />
+        </View>
+      ) : null}
       <Text
-        className="text-center font-instrument-sans-semibold text-base"
-        style={[textStyle("foreground", scheme), typeStyle("semibold")]}
+        className="text-center font-instrument-sans-medium text-sm"
+        style={[textStyle("foreground", scheme), sizeStyle("text-sm"), typeStyle("medium")]}
       >
         {title}
       </Text>
       {description ? (
-        <Text className="text-center font-instrument-sans text-sm" style={textStyle("muted", scheme)}>
+        <Text
+          className="mt-2 max-w-sm text-center font-instrument-sans text-xs leading-relaxed"
+          style={[textStyle("muted", scheme), relaxedSizeStyle("text-xs")]}
+        >
           {description}
         </Text>
       ) : null}
-      {action ? <View className="mt-2">{action}</View> : null}
+      {action ? <View className="mt-6">{action}</View> : null}
     </View>
   );
 }

package/src/settings/SettingsField.tsx

@@ -1,7 +1,13 @@
 import { View, Text } from "react-native";
-import { textStyle, typeStyle } from "../controlStyles";
+import { sizeStyle, textStyle, typeStyle } from "../controlStyles";
 import { useScheme } from "../useScheme";
+import { relaxedSizeStyle } from "./relaxedSizeStyle";
 
+/**
+ * One labelled control in a `SettingsSection` body, the web stacked
+ * `SettingsField`: label `text-sm` medium (14 / 20 / 500) above the control,
+ * help text `text-xs leading-relaxed` (12 / 19.5), muted, below it.
+ */
 export function SettingsField({
   label,
   description,
@@ -16,8 +22,8 @@ export function SettingsField({
     <View>
       {typeof label === "string" ? (
         <Text
-          className="mb-2 text-base font-instrument-sans-semibold"
-          style={[textStyle("foreground", scheme), typeStyle("semibold")]}
+          className="mb-2 text-sm font-instrument-sans-medium"
+          style={[textStyle("foreground", scheme), sizeStyle("text-sm"), typeStyle("medium")]}
         >
           {label}
         </Text>
@@ -28,8 +34,8 @@ export function SettingsField({
       {description != null ? (
         typeof description === "string" ? (
           <Text
-            className="mt-1.5 text-sm font-instrument-sans"
-            style={textStyle("muted", scheme)}
+            className="mt-1.5 text-xs leading-relaxed font-instrument-sans"
+            style={[textStyle("muted", scheme), relaxedSizeStyle("text-xs")]}
           >
             {description}
           </Text>

package/src/settings/SettingsSection.tsx

@@ -1,8 +1,9 @@
 import { View, Text } from "react-native";
 import { cn } from "../cn";
-import { cardStyle, textStyle, typeStyle } from "../controlStyles";
+import { cardStyle, sizeStyle, textStyle, typeStyle } from "../controlStyles";
 import { tokens } from "../tokens";
 import { useScheme } from "../useScheme";
+import { relaxedSizeStyle } from "./relaxedSizeStyle";
 
 type SettingsSectionBodyVariant = "form" | "list" | "compact";
 
@@ -32,10 +33,11 @@ export function SettingsSection({
       <View className="flex-row items-start justify-between gap-4 px-4">
         <View className="min-w-0 flex-1">
           {typeof title === "string" ? (
+            // Web `text-sm font-semibold`: 14 / 20, 600.
             <Text
               accessibilityRole="header"
-              className="text-lg font-instrument-sans-semibold"
-              style={[textStyle("foreground", scheme), typeStyle("semibold")]}
+              className="text-sm font-instrument-sans-semibold"
+              style={[textStyle("foreground", scheme), sizeStyle("text-sm"), typeStyle("semibold")]}
             >
               {title}
             </Text>
@@ -44,9 +46,10 @@ export function SettingsSection({
           )}
           {description != null ? (
             typeof description === "string" ? (
+              // Web `text-sm leading-relaxed`: 14 / 22.75, muted.
               <Text
-                className="mt-0.5 text-base font-instrument-sans"
-                style={textStyle("muted", scheme)}
+                className="mt-0.5 text-sm leading-relaxed font-instrument-sans"
+                style={[textStyle("muted", scheme), relaxedSizeStyle("text-sm")]}
               >
                 {description}
               </Text>