@studio-piot/native-ui 0.1.0

package/docs/superpowers/specs/2026-09-24-field-design.md

@@ -0,0 +1,205 @@
+# Field (FieldText / FieldTextarea) — design
+
+Date: 2026-09-24  
+Package: `@studio-piot/native-ui`  
+Status: approved
+
+## Goal
+
+Add presentational form controls **FieldText** and **FieldTextarea**. Apps own colours, clear icons, and form state. The package renders label, input chrome (including focus and error borders), optional clear affordance, and error text. No brand names, theme role catalogues, or icon libraries live in this package.
+
+Replace the current example `src/components/Field/` files (app-coupled imports) with this contract.
+
+## Decisions
+
+| Topic | Choice |
+|---|---|
+| API shape | Single controls: `FieldText`, `FieldTextarea` with optional `label` / `error` |
+| Internals | Shared chrome helper (label, border, focus, error, clear) |
+| Colours | Required colour props (same pattern as `Button` / `LinkBlocks`) |
+| Focus | Resting `borderWidth: 1`; focused `borderWidth: 2` with padding compensation so layout does not jump |
+| Error | Message under the control; border uses `errorColor` when `error` is a non-empty string |
+| Focus + error | Error colour wins; double stroke still applies while focused |
+| Clear | Shown when `value` is non-empty **and** `clearIcon` is provided. Optional `onClear`; default clears via `onChangeText("")` |
+| Radius | Reuse `ButtonRadius` / `buttonRadiusValue`. Default `"xl"` |
+| Width | Always full width of the parent |
+| Disabled | `editable={false}` → opacity `0.4` on the control (same treatment as `Button`) |
+| Brand coupling | None |
+
+## Architecture
+
+```
+FieldText ──┐
+            ├── fieldChrome (shared layout + border/focus/error/clear)
+FieldTextarea ─┘
+```
+
+- Public exports: `FieldText`, `FieldTextarea` only (no compound `Field` / `FieldLabel` / `FieldError` in the public API).
+- Shared helper is package-internal; not required to be a public export.
+- Controlled only: `value` + `onChangeText` required.
+
+## Colour props (required)
+
+| Prop | Role |
+|---|---|
+| `borderColor` | Resting border |
+| `focusedBorderColor` | Focused border (when not in error) |
+| `errorColor` | Error border and error text |
+| `textColor` | Input value text |
+| `labelColor` | Label above the input |
+| `placeholderColor` | Placeholder |
+| `backgroundColor` | Input fill |
+
+Callers typically resolve these with `useThemeColor` (package or app) before passing them in. The Field components do not call theme hooks themselves.
+
+## Props
+
+### Shared (`FieldText` and `FieldTextarea`)
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `value` | `string` | yes | Controlled |
+| `onChangeText` | `(text: string) => void` | yes | |
+| `borderColor` | `string` | yes | |
+| `focusedBorderColor` | `string` | yes | |
+| `errorColor` | `string` | yes | |
+| `textColor` | `string` | yes | |
+| `labelColor` | `string` | yes | |
+| `placeholderColor` | `string` | yes | |
+| `backgroundColor` | `string` | yes | |
+| `label` | `string` | no | Above the input |
+| `error` | `string` | no | Under the input; truthy drives error border |
+| `placeholder` | `string` | no | |
+| `radius` | `ButtonRadius` | no | Default `"xl"` |
+| `editable` | `boolean` | no | Default `true` |
+| `clearIcon` | `React.ReactNode` | no | Clear shown only with non-empty `value` and this prop |
+| `onClear` | `() => void` | no | Default: `() => onChangeText("")` |
+| `style` | `StyleProp<ViewStyle>` | no | Outer column wrapper |
+| `inputStyle` | `StyleProp<TextStyle>` | no | Extra styles on `TextInput` |
+| Common `TextInput` passthroughs | — | no | e.g. `secureTextEntry`, `keyboardType`, `autoCapitalize`, `autoComplete`, `textContentType`, `onFocus` / `onBlur`, `ref` |
+
+Do **not** invert `editable` (the Ribe example’s `editable={!editable}` bug must not be copied).
+
+### `FieldTextarea` extras
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `numberOfLines` | `number` | no | Default `4` |
+| — | — | — | Always multiline; `textAlignVertical: "top"`; min height derived from line count |
+
+## Layout and behaviour
+
+### Column
+
+Vertical stack with a small gap (~6):
+
+1. Optional label — caption-sized (13), weight 600, colour `labelColor`
+2. Input shell — full width
+3. Optional error text — size 13, colour `errorColor`
+
+### Input shell
+
+- `backgroundColor`, `borderRadius` from `radius`
+- Resting: `borderWidth: 1`, colour `borderColor`
+- Focused (no error): `borderWidth: 2`, colour `focusedBorderColor`; reduce horizontal padding by 1 so the control does not grow
+- Error (with or without focus): border colour `errorColor`; if also focused, keep `borderWidth: 2`
+- Value text: `textColor`; placeholder: `placeholderColor`
+- Single-line (`FieldText`): min height ~48–50, vertical padding aligned with package Button density
+- Textarea: taller min height from `numberOfLines`; top-aligned text
+
+### Clear
+
+- Absolute position at the trailing end of the input
+- Extra right padding on the `TextInput` when the clear control is visible
+- `TouchableOpacity` / `Pressable` with adequate hitSlop
+- Package does not import icon libraries; `clearIcon` is opaque `ReactNode`
+
+### Accessibility
+
+- Associate label with the input where practical (`accessibilityLabel` from `label` when present)
+- Error text available to assistive tech (e.g. announced with the field or as related text)
+- Clear control has an accessibility label (e.g. "Clear")
+
+## Out of scope (v1)
+
+- Uncontrolled mode (`defaultValue`)
+- Validation / form libraries
+- Left adornments, prefixes, floating labels
+- Built-in clear glyph without `clearIcon`
+- Looking up theme roles inside Field
+- Migrating Ribe or Optimum forms onto these components (consumers can follow later)
+
+## Package layout
+
+| Path | Job |
+|---|---|
+| `src/components/Field/FieldText.tsx` | Single-line public component |
+| `src/components/Field/FieldTextarea.tsx` | Multiline public component |
+| `src/components/Field/fieldChrome.tsx` | Shared label / border / focus / error / clear (name flexible) |
+| `src/components/Field/types.ts` | Shared props types |
+| `src/components/Field/index.ts` | Barrel |
+| Remove | App-coupled example files (`Field.tsx`, `FieldLabel.tsx`, `FieldInput.tsx`, `FieldError.tsx`, and the old `FieldTextarea.tsx` if replaced) |
+| `src/components/index.ts` | Re-export |
+| `src/index.ts` | Public export |
+| `docs/components/field.md` | Usage doc (linked from README) |
+
+Reuse `ButtonRadius` / `buttonRadiusValue` from the Button module.
+
+## Example (app)
+
+```tsx
+import { FieldText, FieldTextarea, useThemeColor } from "@studio-piot/native-ui";
+import Ionicons from "@expo/vector-icons/Ionicons";
+
+const border = useThemeColor("border");
+const focused = useThemeColor("tint");
+const error = useThemeColor("danger");
+const text = useThemeColor("text");
+const textSecondary = useThemeColor("textSecondary");
+const surface = useThemeColor("surface");
+
+<FieldText
+  label="Email"
+  value={email}
+  onChangeText={setEmail}
+  placeholder="you@example.com"
+  error={emailError}
+  borderColor={border}
+  focusedBorderColor={focused}
+  errorColor={error}
+  textColor={text}
+  labelColor={textSecondary}
+  placeholderColor={textSecondary}
+  backgroundColor={surface}
+  keyboardType="email-address"
+  autoCapitalize="none"
+  clearIcon={<Ionicons name="close-circle" size={20} color={textSecondary} />}
+/>
+
+<FieldTextarea
+  label="Notes"
+  value={notes}
+  onChangeText={setNotes}
+  borderColor={border}
+  focusedBorderColor={focused}
+  errorColor={error}
+  textColor={text}
+  labelColor={textSecondary}
+  placeholderColor={textSecondary}
+  backgroundColor={surface}
+/>
+```
+
+Colour role names above are illustrative; the app chooses its own map keys.
+
+## Verification
+
+- `npm test` and `npm run build` in the package succeed.
+- Typecheck a consumer that renders labelled `FieldText` (with `error` and `clearIcon`) and `FieldTextarea`.
+- Manual: focus doubles stroke without layout jump; error colour + message; clear only when icon + value; disabled opacity; `editable` is not inverted.
+
+## Related
+
+- Button + theme: `docs/superpowers/specs/2026-09-24-theme-provider-button-design.md`
+- LinkBlocks: `docs/superpowers/specs/2026-09-24-link-blocks-design.md`
+- Usage (after implementation): `docs/components/field.md`

package/docs/superpowers/specs/2026-09-24-link-blocks-design.md

@@ -0,0 +1,167 @@
+# LinkBlocks — design
+
+Date: 2026-09-24  
+Package: `@studio-piot/native-ui`  
+Status: approved
+
+## Goal
+
+Add a presentational **LinkBlocks** component: one or more rounded groups of tappable rows (optional icon, label, trailing chevron), driven by a config object. Section titles sit outside and above each group. The parent app owns colours, icons, and navigation (`onPress` per item). No brand names, role catalogues, or router dependencies in the package.
+
+## Decisions
+
+| Topic | Choice |
+|---|---|
+| API shape | Config-driven `LinkBlocks` with `blocks: LinkBlockGroup[]` |
+| Navigation | `onPress` per item only. Package does not import Expo Router or Linking |
+| Icons | Optional `React.ReactNode` per item. Package does not depend on icon libraries |
+| Colours | Required colour props on the component (same pattern as `Button`) |
+| Chevron | Drawn by the package (text chevron). Colour from `chevronColor` |
+| Radius | Same Tailwind-style steps as `Button`. Default `"xl"` |
+| Width | Always full width of the parent |
+| Brand coupling | None |
+
+## Data
+
+```ts
+type LinkBlockItem = {
+  key: string;
+  label: string;
+  onPress: () => void;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+};
+
+type LinkBlockGroup = {
+  key: string;
+  title?: string;
+  items: LinkBlockItem[];
+};
+```
+
+- `items` must be a non-empty array for a group to render. Empty groups are skipped (no empty surface, no orphan title).
+- `key` is stable for React lists; the parent chooses the string.
+
+## Props
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `blocks` | `LinkBlockGroup[]` | yes | One or more groups |
+| `surfaceColor` | `string` | yes | Rounded container fill |
+| `labelColor` | `string` | yes | Row label |
+| `dividerColor` | `string` | yes | Hairline between rows |
+| `chevronColor` | `string` | yes | Trailing chevron |
+| `titleColor` | `string` | no | Section title above a block. Required in practice when any group has `title`; if a titled group is rendered without `titleColor`, fall back to `labelColor` |
+| `radius` | `ButtonRadius` | no | Default `"xl"` (reuse `buttonRadiusValue`) |
+| `style` | `StyleProp<ViewStyle>` | no | Outer stack wrapper |
+
+Reuse `ButtonRadius` / `buttonRadiusValue` from the Button module so radius stays consistent across components.
+
+## Layout and behaviour
+
+### Stack
+
+- Vertical stack of groups with a fixed gap (16).
+- Each group: optional title, then the rounded surface.
+
+### Title
+
+- Outside the surface, above it.
+- Caption-sized type (13), weight 600.
+- Colour: `titleColor` if provided, else `labelColor`.
+
+### Surface
+
+- `backgroundColor: surfaceColor`.
+- `borderRadius` from `radius`.
+- Full width of the parent.
+- Overflow hidden so row presses respect the radius.
+
+### Row
+
+- `TouchableOpacity` (or `Pressable`) with `accessibilityRole="button"`.
+- Min height 52, horizontal padding 16, horizontal row: optional icon slot, flex label, chevron.
+- Icon slot: fixed width (~28) when any item in that group has an icon; otherwise no leading gutter. If only some items have icons, keep the slot so labels align.
+- Label: font size 17, colour `labelColor`.
+- Chevron: package-owned `›` (or equivalent), colour `chevronColor`, not selectable.
+- `disabled`: non-interactive, opacity `0.4` (same treatment as `Button`).
+
+### Dividers
+
+- Between consecutive items only (not above the first or below the last).
+- Hairline height (`StyleSheet.hairlineWidth`), colour `dividerColor`.
+- Leading inset so the line starts after the icon column (when present) plus a small gap — not full-bleed to the left edge. Trailing edge can meet the padding.
+
+### Out of scope (v1)
+
+- Premium / gradient / locked row variants
+- Swipe actions, badges, or trailing custom accessories (chevron only)
+- Built-in navigation or `href`
+- Looking up theme roles inside the package
+- Migrating Ribe Profile onto LinkBlocks (consumer can do that later)
+
+## Package layout
+
+| Path | Job |
+|---|---|
+| `src/components/LinkBlocks/LinkBlocks.tsx` | Component |
+| `src/components/LinkBlocks/types.ts` | `LinkBlockItem`, `LinkBlockGroup`, props |
+| `src/components/LinkBlocks/index.ts` | Barrel |
+| `src/components/index.ts` | Re-export |
+| `src/index.ts` | Public export |
+| `docs/components/link-blocks.md` | Usage doc (linked from README) |
+
+## Example (app)
+
+```tsx
+import { LinkBlocks } from "@studio-piot/native-ui";
+import { useThemeColor } from "@/hooks/useThemeColor";
+import Ionicons from "@expo/vector-icons/Ionicons";
+import { router } from "expo-router";
+
+const surface = useThemeColor("surface");
+const text = useThemeColor("text");
+const textSecondary = useThemeColor("textSecondary");
+const border = useThemeColor("border");
+
+<LinkBlocks
+  surfaceColor={surface}
+  labelColor={text}
+  dividerColor={border}
+  chevronColor={textSecondary}
+  titleColor={textSecondary}
+  blocks={[
+    {
+      key: "settings",
+      title: "Settings",
+      items: [
+        {
+          key: "units",
+          label: "Units of Measure",
+          icon: <Ionicons name="options-outline" size={22} color={text} />,
+          onPress: () => router.push("/settings/units"),
+        },
+        {
+          key: "notifications",
+          label: "Notification Settings",
+          icon: <Ionicons name="notifications-outline" size={22} color={text} />,
+          onPress: () => router.push("/settings/notifications"),
+        },
+      ],
+    },
+  ]}
+/>
+```
+
+On a Stone (or grey) page background, the app passes a lighter `surface` (e.g. white). On a white page, the app chooses a contrasting surface — the package does not compute “lighter than background”.
+
+## Verification
+
+- `npm test` and `npm run build` in the package succeed.
+- Typecheck a consumer that renders one titled multi-item block and one untitled single-item block.
+- Manual: pressed row fires `onPress`; disabled row does not; dividers and title placement match the reference layout.
+
+## Related
+
+- Button + theme: `docs/superpowers/specs/2026-09-24-theme-provider-button-design.md`
+- Usage (after implementation): `docs/components/link-blocks.md`

package/docs/superpowers/specs/2026-09-24-theme-provider-button-design.md

@@ -0,0 +1,178 @@
+# Theme provider and Button — design
+
+Date: 2026-09-24  
+Package: `@studio-piot/native-ui`  
+Status: approved
+
+## Goal
+
+Add a project-agnostic theme layer and the first reusable component, `Button`. Apps own their palettes and semantic roles. The package resolves light/dark from React Native and renders controls from colours the caller passes in. No app-specific brand names, role names, or palettes live in this package.
+
+## Decisions
+
+| Topic | Choice |
+|---|---|
+| Theme injection | Package `ThemeProvider` + `useThemeColor` / `useColorScheme` |
+| Colour ownership | Apps supply `{ light, dark }` maps of string roles → hex (or any colour string) |
+| Button colours | Required props (`backgroundColor`, `labelColor`); not looked up from theme roles |
+| Scheme source | React Native `useColorScheme`; anything other than `"dark"` is light |
+| Disabled | Opacity on the control; no disabled colour roles |
+| Width | Always full width of the parent (`width: "100%"`). Not configurable |
+| Radius | Prop `radius` with Tailwind-style steps (see below). Default `"xl"` |
+| Layout | Package-owned colour-free `StyleSheet` for the button shell and label |
+| Brand coupling | None. No brand colour names or app-named roles in the package |
+
+## Theme
+
+### `ThemeProvider`
+
+```tsx
+type ThemeColors = Record<string, string>;
+
+type ThemeProviderProps<T extends ThemeColors = ThemeColors> = {
+  colors: { light: T; dark: T };
+  children: React.ReactNode;
+};
+```
+
+- Mounts a React context with the `colors` maps.
+- Does not read storage or set `Appearance`. Apps that override the window scheme (for example with `Appearance.setColorScheme`) keep doing that themselves; this provider only supplies maps.
+- Using `useThemeColor` or `useColorScheme` outside the provider throws a clear error.
+
+### `useColorScheme`
+
+Returns `"light" | "dark"`. Reads React Native’s `useColorScheme` and treats every value other than `"dark"` as light (`null`, `undefined`, `"unspecified"`).
+
+### `useThemeColor`
+
+```ts
+function useThemeColor<T extends ThemeColors>(
+  colorName: keyof T & string,
+  overrides?: { light?: string; dark?: string },
+): string
+```
+
+Resolution:
+
+1. Resolved scheme from `useColorScheme()`.
+2. If `overrides` has a string for that scheme, return it.
+3. Otherwise return `colors[scheme][colorName]`.
+
+A missing role is a runtime error (no silent fallback colour). TypeScript narrows `colorName` when the app passes a typed `colors` map into the provider (via generics on the provider / context).
+
+Apps may keep their own theme hooks. The package hook is optional for call sites that want one shared API across Studio native apps.
+
+## Button
+
+Presentational. Theme-aware only in the sense that callers typically resolve colours with `useThemeColor` (package or app) before passing them in.
+
+### Props
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | Visible label |
+| `onPress` | `() => void` | yes | |
+| `backgroundColor` | `string` | yes | Filled: fill. Outline: border and label |
+| `labelColor` | `string` | yes | Filled: label and spinner. Outline: unused for the label (label uses `backgroundColor`) |
+| `disabled` | `boolean` | no | Default `false` |
+| `loading` | `boolean` | no | Default `false`; shows a spinner instead of the label |
+| `variant` | `"filled" \| "outline"` | no | Default `"filled"` |
+| `radius` | `ButtonRadius` | no | Default `"xl"`. See radius table |
+| `style` | `StyleProp<ViewStyle>` | no | Merged after the package shell style |
+| `labelStyle` | `StyleProp<TextStyle>` | no | Merged after the package label style |
+
+`ButtonRadius` = `"none" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "full"`.
+
+### Behaviour
+
+- **Filled:** background `backgroundColor`; label and spinner `labelColor`.
+- **Outline:** transparent fill; border width 1 and label colour `backgroundColor`; spinner uses `backgroundColor`.
+- **Disabled or loading:** control is non-interactive; opacity reduced (for example `0.4`). Same colours as enabled — no separate disabled palette.
+- Accessibility: `accessibilityRole="button"`; `accessibilityState` reflects `disabled` and `busy` when loading.
+- Uses React Native `TouchableOpacity`, `Text`, and `ActivityIndicator`. No app-local text components.
+
+### Layout (package stylesheet)
+
+Colour-free defaults:
+
+- Shell: always `width: "100%"` of its parent, min height `52`, centred content
+- Label: font size `17`, font weight `600`
+
+Radius follows Tailwind’s named scale, mapped to density-independent pixels (same ratios as Tailwind’s rem steps at a 16px root):
+
+| `radius` | Border radius | Tailwind analogue |
+|---|---|---|
+| `none` | `0` | `rounded-none` |
+| `sm` | `2` | `rounded-sm` |
+| `md` | `6` | `rounded-md` |
+| `lg` | `8` | `rounded-lg` |
+| `xl` | `12` | `rounded-xl` (default) |
+| `2xl` | `16` | `rounded-2xl` |
+| `3xl` | `24` | `rounded-3xl` |
+| `full` | `999` | `rounded-full` (pill) |
+
+Call sites may still pass `style` / `labelStyle` for spacing overrides. They must not rely on `style` to change width: the package always stretches to the parent.
+
+### Example (app-side)
+
+```tsx
+import { Button, ThemeProvider, useThemeColor } from "@studio-piot/native-ui";
+import { Colors } from "./config/colors";
+
+function SaveButton({ onPress }: { onPress: () => void }) {
+  return (
+    <Button
+      label="Save"
+      onPress={onPress}
+      backgroundColor={useThemeColor("buttonBackground")}
+      labelColor={useThemeColor("buttonLabel")}
+    />
+  );
+}
+
+// Root
+<ThemeProvider colors={Colors}>
+  <App />
+</ThemeProvider>
+```
+
+Role names such as `buttonBackground` belong to the app’s `Colors` type, not to this package.
+
+## Package layout
+
+| Path | Job |
+|---|---|
+| `src/theme/ThemeProvider.tsx` | Context + provider |
+| `src/theme/useColorScheme.ts` | Light/dark resolution |
+| `src/theme/useThemeColor.ts` | Role → colour |
+| `src/theme/index.ts` | Theme exports |
+| `src/components/Button/Button.tsx` | Button |
+| `src/components/Button/buttonRadius.ts` | Radius name → number |
+| `src/components/Button/index.ts` | Button barrel |
+| `src/components/index.ts` | Component barrel |
+| `src/index.ts` | Public entry (`version`, theme, components) |
+
+Exports:
+
+- `@studio-piot/native-ui` — theme helpers, `Button`, `version`
+- `@studio-piot/native-ui/components` — components only
+
+Peer dependencies remain `react` and `react-native`. No new runtime dependencies.
+
+## Out of scope
+
+- Shipping any brand palette or semantic role catalogue
+- Preference storage or `Appearance.setColorScheme` inside the package
+- Migrating app screens onto the package Button (consumer apps do that separately)
+- Other components (inputs, text, layouts)
+- Visual regression / Storybook
+
+## Verification
+
+- `npm run build` in the package succeeds.
+- Typecheck of a consumer that mounts `ThemeProvider` with a typed `Colors` map and renders `Button` with resolved colour props.
+- Manual: filled and outline, enabled / disabled / loading, light and dark scheme (scheme change via the app’s own preference or the simulator appearance).
+
+## Consumer note (linking)
+
+Local apps may depend on the package via `file:` (or a published version) and must keep Metro `watchFolders` / `nodeModulesPaths` pointed at the package when it lives outside the app root, as already set up for local development.

package/docs/superpowers/specs/2026-09-25-radio-field-design.md

@@ -0,0 +1,136 @@
+# RadioField — design
+
+Date: 2026-09-25  
+Package: `@studio-piot/native-ui`  
+Status: approved  
+Apps: Ribe Appearance screen migration in the same pass
+
+## Goal
+
+Add a presentational **RadioField**: one controlled radio group in a LinkBlocks-style rounded card. Label (and optional description) on the left, radio control on the right. Colours follow Field’s `field*` theme roles, plus one new selected-control role. Migrate Ribe’s Appearance (theme preference) screen to use it.
+
+## Decisions
+
+| Topic | Choice |
+|---|---|
+| API shape | Single group: `value` + `onChange` + `options[]` |
+| Layout | LinkBlocks card: rounded surface, hairline dividers, no icon column |
+| Row content | Label + optional description left; radio right |
+| Colours | Theme defaults from Field roles; optional prop overrides (Field pattern) |
+| Selected colour | New theme role `fieldRadioSelected` (not reused from focus/border) |
+| Radio drawing | Package-drawn Views (ring + selected fill/dot); no icon libraries |
+| Radius | Reuse `ButtonRadius` / `buttonRadiusValue`. Default `"xl"` |
+| Width | Always full width of the parent |
+| Disabled | Per-option `disabled` → opacity `0.4` on that row |
+| Multi-group | Out of scope (no RadioBlocks) |
+| Brand coupling | None |
+
+## Architecture
+
+```
+RadioField
+  ├── optional group label (above card)
+  └── card surface
+        └── option rows (divider between)
+              ├── label + description
+              └── RadioMark (selected / unselected)
+```
+
+- Public export: `RadioField` (+ types). Internal mark helper need not be public.
+- Controlled only: `value` and `onChange` required.
+- Resolves colours via `ThemeProvider` when override props are omitted (same approach as current Field).
+
+## Theme roles
+
+| Usage | Theme role |
+|---|---|
+| Card fill | `fieldBackground` |
+| Option label | `fieldText` |
+| Option description | `fieldDescription` |
+| Dividers / unselected ring | `fieldBorder` |
+| Selected radio fill | `fieldRadioSelected` (**new**) |
+| Optional group label above card | `fieldLabel` |
+
+Apps must add `fieldRadioSelected` to light and dark maps. Existing Field `field*` roles are reused.
+
+### Optional colour overrides
+
+| Prop | Default role |
+|---|---|
+| `backgroundColor` | `fieldBackground` |
+| `labelColor` | `fieldText` |
+| `descriptionColor` | `fieldDescription` |
+| `dividerColor` | `fieldBorder` |
+| `radioColor` | `fieldBorder` (unselected ring) |
+| `selectedColor` | `fieldRadioSelected` |
+| `titleColor` | `fieldLabel` (group label above card) |
+
+## Props
+
+```ts
+type RadioOption<T extends string = string> = {
+  value: T;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+};
+
+type RadioFieldProps<T extends string = string> = {
+  value: T | null;
+  onChange: (value: T) => void;
+  options: RadioOption<T>[];
+  label?: string;
+  radius?: ButtonRadius;
+  // optional colour overrides (table above)
+  style?: StyleProp<ViewStyle>;
+};
+```
+
+| Prop | Notes |
+|---|---|
+| `value` | Controlled selection; `null` = none selected |
+| `onChange` | Fires with the tapped option’s `value` |
+| `options` | Stable `value` strings; empty list renders nothing (no empty card) |
+| `label` | Optional caption above the card (LinkBlocks title density) |
+| `radius` | Default `"xl"` (12) |
+
+## Layout
+
+Aligned with LinkBlocks row metrics:
+
+- Card: full width, `overflow: "hidden"`, radius from `buttonRadiusValue`
+- Row: `minHeight` 52, horizontal padding 16, label column `flex: 1`, radio trailing
+- Label: font size 17; description: font size 13 under label, `fieldDescription`
+- Divider: hairline between rows, full width of the card content edge (no icon inset)
+- Radio mark: ~22pt outer diameter; unselected = ring (`fieldBorder`); selected = filled circle (`fieldRadioSelected`) with small center hole in `fieldBackground`
+
+Gap between stacked group label and card: 8 (same as LinkBlocks).
+
+## Accessibility
+
+- Card / list container: `accessibilityRole="radiogroup"`
+- Each row: `accessibilityRole="radio"`, `accessibilityState={{ selected, disabled }}`, `accessibilityLabel` from option label (description may be included in the accessibility label or as hint where platform supports it)
+- Radio mark is decorative (`accessibilityElementsHidden` / `importantForAccessibility="no"`); the row is the hit target
+
+## App work (Ribe)
+
+1. Add `fieldRadioSelected` to `ThemeColors` light/dark (e.g. charcoal light / stone dark — solid control matching the reference).
+2. Replace Appearance’s checkmark `Pressable` list with `RadioField` for `automatic` | `light` | `dark`.
+3. Keep current option labels; optionally add a short description on Automatic for parity with “Use Device Settings” style copy (product choice at implement time; default to no new copy unless already decided).
+4. Ensure Field `field*` roles already present (from Field migration) remain.
+
+## Out of scope
+
+- Multi-group / titled RadioBlocks
+- Leading icons
+- Multi-select
+- Migrating Optimum or other apps
+- Liquid-glass / native UIKit radio controls
+- Keyboard form chrome (Form) changes
+
+## Success criteria
+
+- Package exports `RadioField` with usage docs
+- Theme defaults documented; `fieldRadioSelected` required for selected state
+- Ribe Appearance uses `RadioField` and looks like the LinkBlocks card + radio reference
+- `npm test` / `npm run build` (package) and Ribe `pnpm typecheck` pass