@hzblj/kara-components 0.8.0 → 0.10.0

package/lib/typescript/organisms/sheet/sheet.types.d.ts

@@ -7,12 +7,12 @@ import type { NavigationBarItem, NavigationBarSearch } from '../../molecules/nav
 export type SheetDetent = 'auto' | number;
 /**
  * `center` is iOS's own, `leading` Material's. `large` puts the title above the content in a large face, and once
- * that scrolls under the bar the bar's own title fades in — centred on iOS, leading on Android.
+ * that scrolls under the bar the bar's own title fades in (centred on iOS, leading on Android).
  */
 export type SheetTitleStyle = 'center' | 'large' | 'leading';
 /**
  * The sheet's header: a `NavigationBar` with the title and items, and anything else that should stay put above the
- * content (`children` — a segmented control, a search hint). On iOS 26 a scrollable sheet's content scrolls under it
+ * content (`children`: a segmented control, a search hint). On iOS 26 a scrollable sheet's content scrolls under it
  * with the system's scroll edge effect; elsewhere it sits above the content.
  */
 export type SheetHeaderProps = {
@@ -24,24 +24,24 @@ export type SheetHeaderProps = {
     leadingItems?: NavigationBarItem[];
     /** A search field in place of the title (iOS). */
     search?: NavigationBarSearch;
-    /** The title — in the bar, or above the content with a `large` `titleStyle`. */
+    /** The title: in the bar, or above the content with a `large` `titleStyle`. */
     title?: string;
     /** `center` by default. */
     titleStyle?: SheetTitleStyle;
-    /** In screen order, toward the trailing edge — the close item, by convention. */
+    /** In screen order, toward the trailing edge: the close item, by convention. */
     trailingItems?: NavigationBarItem[];
 };
 /** Imperative control of a `Sheet`, through its `ref`. */
 export type SheetRef = {
     /** Dismisses it without calling `onDismiss`, which reports the user's dismissals only. */
     dismiss: () => Promise<void>;
-    /** Presents at a detent — the first by default. */
+    /** Presents at a detent, the first by default. */
     present: (detentIndex?: number) => Promise<void>;
     /** Moves to another detent. */
     resize: (detentIndex: number) => Promise<void>;
 };
 /**
- * A native sheet — `UISheetPresentationController` on iOS, Material's bottom sheet on Android — with an optional
+ * A native sheet (`UISheetPresentationController` on iOS, Material's bottom sheet on Android) with an optional
  * native header (`<Sheet.Header>` as a direct child). The React Native tier: it needs no host, and must not sit inside
  * one; native atoms in its content go in an `Island`.
  */
@@ -50,7 +50,7 @@ export type SheetProps = {
     bg?: ColorToken;
     /** The content. A `<Sheet.Header>` among the direct children becomes the native header instead. */
     children: ReactNode;
-    /** Where the sheet can rest, smallest first. `['auto']` — fit the content — by default. */
+    /** Where the sheet can rest, smallest first. `['auto']` (fit the content) by default. */
     detents?: SheetDetent[];
     /** Dims what is behind. On by default. */
     dimmed?: boolean;
@@ -62,9 +62,9 @@ export type SheetProps = {
     footer?: ReactElement;
     /** The drag handle. On by default. */
     grabber?: boolean;
-    /** The user dismissed it — `visible` going false does not call this. */
+    /** The user dismissed it; `visible` going false does not call this. */
     onDismiss: () => void;
-    /** The sheet moved to another detent — its index in `detents`. */
+    /** The sheet moved to another detent: its index in `detents`. */
     onDetentChange?: (detentIndex: number) => void;
     /** The sheet finished presenting. */
     onPresent?: () => void;
@@ -72,7 +72,7 @@ export type SheetProps = {
     ref?: Ref<SheetRef>;
     /**
      * The content is a scroll view (`<Sheet.ScrollView>`) the sheet drives: dragging past its top resizes the sheet,
-     * and a header scrolls with the iOS 26 edge effect. Off by default — set it with a scrolling body.
+     * and a header scrolls with the iOS 26 edge effect. Off by default; set it with a scrolling body.
      */
     scrollable?: boolean;
     /** Test identifier, forwarded to the native sheet. */
@@ -85,7 +85,7 @@ export type SheetScrollHandler = (event: NativeSyntheticEvent<NativeScrollEvent>
 export type SheetScrollContextValue = {
     /** Render it first in the content. `null` unless the header's `titleStyle` is `large`. */
     largeTitle: ReactNode;
-    /** Forward the scroll view's scroll events to it — it tracks the large title. Unset when there is none. */
+    /** Forward the scroll view's scroll events to it; it tracks the large title. Unset when there is none. */
     onScroll?: SheetScrollHandler;
     /** The room an overlaid header takes, to add to the content's top padding. `0` where the header sits above it. */
     topInset: number;
@@ -97,7 +97,7 @@ export type SheetScrollContextValue = {
 export type SheetScrollViewProps = Pick<ScrollViewProps, 'keyboardShouldPersistTaps'> & {
     /** The scrolling content, after the large title if there is one. */
     children: ReactNode;
-    /** Styles the scrolling content — padding and gap belong here, as with `RnScrollView`. */
+    /** Styles the scrolling content: padding and gap belong here, as with `RnScrollView`. */
     content?: ResponsiveViewSx;
     /** Called on every scroll event, after the sheet's own listener. */
     onScroll?: SheetScrollHandler;

package/lib/typescript/organisms/snackbar/snackbar.types.d.ts

@@ -8,7 +8,7 @@ export type SnackbarProps = {
     actionLabel?: string;
     /** The message. */
     message: string;
-    /** The action was pressed. The snackbar stays up — turn `visible` off to hide it. */
+    /** The action was pressed. The snackbar stays up; turn `visible` off to hide it. */
     onAction?: () => void;
     /** Shows the snackbar while true, fading it in and out. It sets no timer of its own. */
     visible: boolean;

package/lib/typescript/organisms/swipe-actions/swipe-actions.types.d.ts

@@ -5,25 +5,25 @@ import type { IconName } from '../../atoms/icon';
 export type SwipeAction = {
     /** Fills the button with `fill.destructive.primary` unless `tint` says otherwise. */
     destructive?: boolean;
-    /** One of the app's icons, on the button — a round one on iOS 26, as in Mail, a filled stadium on Android. */
+    /** One of the app's icons, on the button: a round one on iOS 26, as in Mail, a filled stadium on Android. */
     icon: IconName;
     /**
-     * The action's name, written under the button — before iOS 26 a row of the usual height shows the icon alone and
+     * The action's name, written under the button; before iOS 26 a row of the usual height shows the icon alone and
      * keeps the label for VoiceOver. Actions are keyed by it, so keep labels unique within one row.
      */
     label: string;
     /** Called when the button is pressed. The row closes by itself. */
     onPress: () => void;
     /**
-     * The button's fill — `fill.destructive.primary` for a destructive action, `fill.accent.primary` otherwise. The icon
+     * The button's fill: `fill.destructive.primary` for a destructive action, `fill.accent.primary` otherwise. The icon
      * on it is white, so pick a fill that holds white in both appearances.
      */
     tint?: ColorToken;
 };
 /**
- * A list row with buttons behind it, uncovered by a swipe — SwiftUI's `swipeActions` on iOS, and on Android, where
+ * A list row with buttons behind it, uncovered by a swipe. SwiftUI's `swipeActions` on iOS, and on Android, where
  * Compose has none, kara's own: the row slides on an anchored drag and the buttons show in the strip it leaves. One
- * row is open at a time on both; a tap on an open row closes it. A native organism — it belongs inside a `List`.
+ * row is open at a time on both; a tap on an open row closes it. A native organism: it belongs inside a `List`.
  */
 export type SwipeActionsProps = {
     /**

package/lib/typescript/templates/screen/screen.types.d.ts

@@ -1,7 +1,7 @@
 import type { Sx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 /**
- * The full-bleed native host a screen starts with — a SwiftUI or Compose `Host` filling its parent, so native atoms
+ * The full-bleed native host a screen starts with: a SwiftUI or Compose `Host` filling its parent, so native atoms
  * render anywhere inside it. The background runs to the edges; the content keeps clear of the status bar where the
  * screen covers it (no navigation bar above), on Android as SwiftUI's safe area does on iOS.
  */
@@ -12,7 +12,7 @@ export type ScreenProps = {
     children?: ReactNode;
     /** Keeps the content where it is when the keyboard opens, instead of avoiding it. Android reads it once, on mount. */
     ignoreKeyboardInset?: boolean;
-    /** Test identifier — on the host view on iOS, on the view around it on Android. */
+    /** Test identifier, on the host view on iOS and on the view around it on Android. */
     testID?: string;
 };
 export type ScreenComponent = (props: ScreenProps) => ReactNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "The atoms, molecules, organisms and templates of @hzblj/kara-ui — real SwiftUI and Jetpack Compose views through @expo/ui.",
   "author": "Jan Blazej",
   "license": "MIT",
@@ -59,9 +59,9 @@
     ]
   },
   "dependencies": {
-    "@hzblj/kara-native": "^0.8.0",
-    "@hzblj/kara-sx": "^0.8.0",
-    "@hzblj/kara-theme": "^0.8.0",
+    "@hzblj/kara-native": "^0.10.0",
+    "@hzblj/kara-sx": "^0.10.0",
+    "@hzblj/kara-theme": "^0.10.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {

package/src/atoms/activity-indicator/activity-indicator.types.ts

@@ -4,7 +4,7 @@ import type {ReactNode} from 'react'
 export type ActivityIndicatorSize = 'large' | 'small'
 
 /**
- * That something is loading, for as long as it takes — UIKit's spinner on iOS, Material 3's expressive
+ * That something is loading, for as long as it takes: UIKit's spinner on iOS, Material 3's expressive
  * `LoadingIndicator` on Android, its shapes morphing as it turns. A React Native view on iOS and a host of its own on
  * Android, so it renders anywhere. For how far along something is, use `Progress`.
  */

package/src/atoms/avatar/avatar.types.ts

@@ -3,11 +3,11 @@ import type {ImageSourcePropType} from 'react-native'
 
 export type AvatarSize = 'lg' | 'md' | 'sm'
 
-/** A round avatar: the image in `source`, or `initials` without one. The React Native tier — it needs no host. */
+/** A round avatar: the image in `source`, or `initials` without one. The React Native tier: it needs no host. */
 export type AvatarProps = {
   /** Shown in place of the image when there is no `source`. */
   initials?: string
-  /** The diameter — `sm` is `s24`, `md` `s40`, `lg` `s64`. `md` by default. */
+  /** The diameter: `sm` is `s24`, `md` `s40`, `lg` `s64`. `md` by default. */
   size?: AvatarSize
   /** The image, cropped to the circle. */
   source?: ImageSourcePropType

package/src/atoms/badge/badge.types.ts

@@ -2,7 +2,7 @@ import type {ReactNode} from 'react'
 
 export type BadgeTone = 'accent' | 'destructive' | 'neutral' | 'success'
 
-/** A small status label in a capsule — a SwiftUI `HStack` in the tone's fill on iOS, Material's `Badge` on Android. */
+/** A small status label in a capsule: a SwiftUI `HStack` in the tone's fill on iOS, Material's `Badge` on Android. */
 export type BadgeProps = {
   /** The text inside. */
   label: string

package/src/atoms/blur-view/blur-view.types.ts

@@ -5,16 +5,16 @@ import type {ReactNode} from 'react'
 export type {BlurMaterial, BlurVibrancy} from '@hzblj/kara-native/swift-ui'
 
 /**
- * One of the system's materials behind React Native content — what sheets, bars, menus and HUDs are made of, in
+ * One of the system's materials (what sheets, bars, menus and HUDs are made of) behind React Native content, in
  * SwiftUI's five thicknesses. iOS: UIKit's `system*Material` blur, with optional vibrancy for the content. Android:
- * what lies behind, blurred and saturated (Android 12+), under a Material tonal surface as thick as the material —
- * `surface` at `ultraThin` up to `surfaceContainerHighest` at `ultraThick`; below Android 12 the surface alone. The
+ * what lies behind, blurred and saturated (Android 12+), under a Material tonal surface as thick as the material
+ * (`surface` at `ultraThin` up to `surfaceContainerHighest` at `ultraThick`); below Android 12 the surface alone. The
  * React Native tier: it needs no host, so it suits a list cell. Shape it with `borderRadius`; it clips its children.
  */
 export type BlurViewProps = ResponsiveViewSx & {
   /**
-   * Pins the material to light or dark whatever the app's appearance — a dark HUD over a light screen. Unset, it follows
-   * the app theme. Android draws the opposite appearance with Material's inverse surface.
+   * Pins the material to light or dark whatever the app's appearance (a dark HUD over a light screen). Unset, it
+   * follows the app theme. Android draws the opposite appearance with Material's inverse surface.
    */
   appearance?: 'dark' | 'light'
   /** React Native content, over the material. */
@@ -24,7 +24,7 @@ export type BlurViewProps = ResponsiveViewSx & {
   /** Test identifier, forwarded to the view. */
   testID?: string
   /**
-   * iOS: draws the children vibrant at this level, the way iOS draws its own labels and fills on a material — their
+   * iOS: draws the children vibrant at this level, the way iOS draws its own labels and fills on a material. Their
    * colour becomes the material's vibrant one and their alpha the mask. Android has no vibrancy: the children keep
    * their colours there.
    */

package/src/atoms/button/button.types.ts

@@ -4,7 +4,7 @@ import type {ReactNode} from 'react'
 export type ButtonVariant = 'accent' | 'destructive' | 'glass' | 'secondary'
 
 /**
- * SwiftUI `ButtonStyle`. iOS only — Compose has no equivalent, so Android ignores it and keeps
+ * SwiftUI `ButtonStyle`. iOS only: Compose has no equivalent, so Android ignores it and keeps
  * rendering the variant's tokens.
  */
 export type ButtonStyleName =
@@ -17,19 +17,19 @@ export type ButtonStyleName =
   | 'plain'
 
 /**
- * SwiftUI `ControlSize`. iOS only, and it has no `automatic` member — leave it unset to inherit
+ * SwiftUI `ControlSize`. iOS only, and it has no `automatic` member: leave it unset to inherit
  * whatever the surrounding SwiftUI environment provides.
  */
 export type ButtonControlSize = 'extraLarge' | 'large' | 'mini' | 'regular' | 'small'
 
-/** A text button — SwiftUI `Button` on iOS, Material's filled button (outlined for `glass`) on Android. */
+/** A text button: SwiftUI `Button` on iOS, Material's filled button (outlined for `glass`) on Android. */
 export type ButtonProps = {
   /**
-   * Replaces the style the variant picks — `borderedProminent` for `accent` and `destructive`, `bordered` for
-   * `secondary`, `glass` for `glass`. iOS only — Android ignores it.
+   * Replaces the style the variant picks: `borderedProminent` for `accent` and `destructive`, `bordered` for
+   * `secondary`, `glass` for `glass`. iOS only. Android ignores it.
    */
   buttonStyle?: ButtonStyleName
-  /** SwiftUI's control size. `large` by default. iOS only — Android ignores it. */
+  /** SwiftUI's control size. `large` by default. iOS only. Android ignores it. */
   controlSize?: ButtonControlSize
   /** Draws the button in its disabled colours and stops it responding to presses. */
   disabled?: boolean
@@ -42,7 +42,7 @@ export type ButtonProps = {
   /**
    * Overrides the variant's own tint. A prominent style takes it as the fill and picks a contrasting
    * label. `glass` has to reach the material through `glassEffect` instead, so tinting one costs it
-   * the stock `.glass` style — see the iOS implementation.
+   * the stock `.glass` style (see the iOS implementation).
    */
   tint?: ColorToken
   /** The look. `accent` by default. Material has no glass, so on Android `glass` is an outlined button. */

package/src/atoms/card/card.types.ts

@@ -2,7 +2,7 @@ import type {ResponsiveSx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 
 /**
- * A raised container — SwiftUI `VStack` / Compose `Column` on `surface.primary`, with a large radius, `s16` padding and
+ * A raised container: SwiftUI `VStack` / Compose `Column` on `surface.primary`, with a large radius, `s16` padding and
  * the `card` shadow. Any `sx` prop overrides its default.
  */
 export type CardProps = ResponsiveSx & {

package/src/atoms/checkbox/checkbox.types.ts

@@ -1,6 +1,6 @@
 import type {ReactNode} from 'react'
 
-/** Material's `Checkbox` on Android. iOS has none, so there it is a SwiftUI `Toggle` — the same switch as `Switch`. */
+/** Material's `Checkbox` on Android. iOS has none, so there it is a SwiftUI `Toggle`, the same switch as `Switch`. */
 export type CheckboxProps = {
   /** Dims the control and ignores taps. */
   disabled?: boolean
@@ -8,7 +8,7 @@ export type CheckboxProps = {
   label?: string
   /** Called with the new value when the user toggles it. */
   onValueChange?: (value: boolean) => void
-  /** Whether it is checked. Controlled — update it from `onValueChange`. */
+  /** Whether it is checked. Controlled: update it from `onValueChange`. */
   value: boolean
 }
 

package/src/atoms/chip/chip.types.ts

@@ -1,6 +1,6 @@
 import type {ReactNode} from 'react'
 
-/** A filter pill on a `Pressable`, not a native control — the React Native tier, so it needs no host. */
+/** A filter pill on a `Pressable`, not a native control. It belongs to the React Native tier, so it needs no host. */
 export type ChipProps = {
   /** The text in the pill. */
   label: string

package/src/atoms/color-picker/color-picker.android.tsx

@@ -1,9 +1,29 @@
-import {warnUnsupported} from '../../platform-support'
-import type {ColorPickerComponent} from './color-picker.types'
+import {ColorWell} from '@hzblj/kara-native/jetpack-compose'
 
-/** Compose has no colour picker, and there is nothing sane to degrade a colour wheel into. */
-export const ColorPicker: ColorPickerComponent = () => {
-  warnUnsupported('ColorPicker', 'Android')
+import {useHostGuard} from '../../host-context'
+import {HStack} from '../h-stack'
+import {Spacer} from '../spacer'
+import {Text} from '../text'
+import type {ColorPickerComponent, ColorPickerProps} from './color-picker.types'
 
-  return null
+/**
+ * The row SwiftUI's `ColorPicker` lays out on iOS, the label leading and the well trailing, around kara's own Compose
+ * well: Compose ships no colour picker, so the sheet behind it draws the iOS picker's grid, spectrum and sliders.
+ */
+export const ColorPicker: ColorPickerComponent = ({
+  label,
+  onValueChange,
+  supportsOpacity = false,
+  testID,
+  value,
+}: ColorPickerProps) => {
+  useHostGuard('ColorPicker')
+
+  return (
+    <HStack align="center" spacing="s12" testID={testID} wide>
+      {label ? <Text>{label}</Text> : null}
+      <Spacer />
+      <ColorWell onValueChange={onValueChange} supportsOpacity={supportsOpacity} title={label} value={value} />
+    </HStack>
+  )
 }

package/src/atoms/color-picker/color-picker.types.ts

@@ -1,11 +1,12 @@
 import type {ReactNode} from 'react'
 
 /**
- * The system colour picker. iOS only — Compose ships no equivalent, so on Android this
- * renders nothing and says so in dev. Branch on `Platform.OS` if the screen needs a fallback.
+ * A row with a label and a colour well that opens a picker: SwiftUI's `ColorPicker` on iOS. Compose ships none, so on
+ * Android it is kara's own, in the same shape: a well with a rainbow ring, and a sheet with a grid of swatches, a
+ * spectrum and RGB sliders.
  */
 export type ColorPickerProps = {
-  /** Text beside the colour well. */
+  /** Text beside the colour well, and the Android sheet's title. */
   label?: string
   /** Called with the colour the user picks. */
   onValueChange?: (color: string) => void

package/src/atoms/date-picker/date-picker.types.ts

@@ -3,7 +3,7 @@ import type {ReactNode} from 'react'
 export type DatePickerMode = 'date' | 'datetime' | 'time'
 
 /**
- * A date or time picker — SwiftUI's compact `DatePicker` on iOS, a field that opens Material's picker dialog on a tap
+ * A date or time picker: SwiftUI's compact `DatePicker` on iOS, a field that opens Material's picker dialog on a tap
  * on Android. The React Native tier: it brings its own host and sizes itself to the value, so it sits in a row beside
  * its label like a `Text`.
  */
@@ -17,11 +17,11 @@ export type DatePickerProps = {
    * `value`'s time of day.
    */
   mode?: DatePickerMode
-  /** Called with the new date — on iOS as it changes, on Android when the dialog is confirmed. */
+  /** Called with the new date: on iOS as it changes, on Android when the dialog is confirmed. */
   onValueChange?: (date: Date) => void
-  /** Test identifier — on the native picker on iOS, on the tappable field on Android. */
+  /** Test identifier, on the native picker on iOS and on the tappable field on Android. */
   testID?: string
-  /** The selected date. Controlled — update it from `onValueChange`. */
+  /** The selected date. Controlled: update it from `onValueChange`. */
   value: Date
 }
 

package/src/atoms/divider/divider.types.ts

@@ -1,11 +1,11 @@
 import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
-/** A horizontal hairline — SwiftUI `Divider` / Compose `HorizontalDivider`. */
+/** A horizontal hairline: SwiftUI `Divider` / Compose `HorizontalDivider`. */
 export type DividerProps = {
   /** The line's colour. `border.tertiary` by default. */
   color?: ColorToken
-  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

package/src/atoms/fab/fab.types.ts

@@ -3,7 +3,7 @@ import type {ReactNode} from 'react'
 import type {IconName} from '../icon'
 
 /**
- * A floating action button — Material's `FloatingActionButton` on Android, a 56pt accent circle (a plain SwiftUI
+ * A floating action button: Material's `FloatingActionButton` on Android, a 56pt accent circle (a plain SwiftUI
  * `Button`) on iOS. It renders inline; pinning it to a corner is up to the screen.
  */
 export type FabProps = {
@@ -11,7 +11,7 @@ export type FabProps = {
   name: IconName
   /** Called when the button is pressed. */
   onPress?: () => void
-  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

package/src/atoms/glass-view/glass-view.types.ts

@@ -3,13 +3,13 @@ import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 /**
- * Glass around a React Native subtree, shaped as a capsule — the React Native tier, so it needs no host. iOS 26:
- * Liquid Glass. Android: frosted glass — what lies behind, blurred on Android 12+, under a translucent tonal surface
- * (or `tint`) and a hairline. iOS before 26 has no Liquid Glass and draws a capsule of `tint` instead, or of the glass
- * buttons' translucent fill (`btn.bg.glass.base`) when there is none.
+ * Glass around a React Native subtree, shaped as a capsule. It belongs to the React Native tier, so it needs no host.
+ * iOS 26: Liquid Glass. Android: frosted glass, made of what lies behind, blurred on Android 12+, under a translucent
+ * tonal surface (or `tint`) and a hairline. iOS before 26 has no Liquid Glass and draws a capsule of `tint` instead, or
+ * of the glass buttons' translucent fill (`btn.bg.glass.base`) when there is none.
  *
  * On Android each glass re-records what lies behind it before every frame: a few buttons cost nothing, but keep it out
- * of the cells of a long list — a plain `tint` reads as well there.
+ * of the cells of a long list. A plain `tint` reads as well there.
  */
 export type GlassViewProps = ResponsiveViewSx & {
   /** React Native views. Give them `pointerEvents="none"` when `interactive`, so the press reaches the `Pressable`. */

package/src/atoms/h-stack/h-stack.types.ts

@@ -4,13 +4,13 @@ import type {ReactNode} from 'react'
 
 export type HStackAlign = 'center' | 'end' | 'start'
 
-/** A horizontal stack — SwiftUI `HStack` / Compose `Row`. */
+/** A horizontal stack: SwiftUI `HStack` / Compose `Row`. */
 export type HStackProps = ResponsiveSx & {
-  /** How the children line up vertically — `start` is the top, `end` the bottom. `start` by default. */
+  /** How the children line up vertically: `start` is the top, `end` the bottom. `start` by default. */
   align?: HStackAlign
   /** Native views, laid out from the leading edge. */
   children?: ReactNode
-  /** Makes the stack pressable — a tap gesture on iOS, a `clickable` with Material's ripple on Android. */
+  /** Makes the stack pressable: a tap gesture on iOS, a `clickable` with Material's ripple on Android. */
   onPress?: () => void
   /** The gap between children. Unset, SwiftUI puts its default spacing between them and Compose none. */
   spacing?: SpaceSize

package/src/atoms/icon/icon.types.ts

@@ -13,13 +13,13 @@ declare global {
 type DeclaredIconName = keyof KaraIcons & string
 
 /**
- * One of the app's icons. Once the plugin has written `kara-icons.d.ts` only those names type-check — an icon removed
+ * One of the app's icons. Once the plugin has written `kara-icons.d.ts` only those names type-check: an icon removed
  * from the folder fails at every call site. Before that, any string, so a project can adopt icons gradually.
  */
 export type IconName = [DeclaredIconName] extends [never] ? string : DeclaredIconName
 
 /**
- * One of the app's icons, in a host — SwiftUI `Image` from the asset catalog on iOS, Material's `Icon` with the vector
+ * One of the app's icons, in a host: SwiftUI `Image` from the asset catalog on iOS, Material's `Icon` with the vector
  * drawable on Android. `RnIcon` draws the same asset outside one.
  */
 export type IconProps = {
@@ -27,11 +27,11 @@ export type IconProps = {
   accessibilityLabel?: string
   /** The icon's tint. `content.primary` by default. */
   color?: ColorToken
-  /** Which of the app's icons — a key of `KaraIcons`. */
+  /** Which of the app's icons, a key of `KaraIcons`. */
   name: IconName
   /** Its width and height, a spacing token. `s24` by default. */
   size?: SpaceSize
-  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

package/src/atoms/icon-button/icon-button.ios.tsx

@@ -1,11 +1,18 @@
 import {Button} from '@expo/ui/swift-ui'
-import {buttonStyle, disabled as disabledModifier} from '@expo/ui/swift-ui/modifiers'
+import {buttonStyle, contentShape, disabled as disabledModifier, shapes} from '@expo/ui/swift-ui/modifiers'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import {Icon} from '../icon'
+import {ZStack} from '../z-stack'
 import type {IconButtonComponent, IconButtonProps} from './icon-button.types'
 
+/** Apple's least tap target. Android's `IconButton` is Material's 48dp; this is the same idea in points. */
+const TARGET = 44
+
+/** The whole square takes the tap, not only the glyph's own pixels. */
+const WHOLE_TARGET = {modifiers: [contentShape(shapes.circle())]}
+
 export const IconButton: IconButtonComponent = ({disabled = false, name, onPress, testID}: IconButtonProps) => {
   useHostGuard('IconButton')
 
@@ -21,7 +28,10 @@ export const IconButton: IconButtonComponent = ({disabled = false, name, onPress
 
   return (
     <Button modifiers={modifiers} onPress={onPress} testID={testID}>
-      <Icon color={disabled ? 'btn.content.disabled' : 'content.primary'} name={name} />
+      <ZStack h={TARGET} ios={WHOLE_TARGET} w={TARGET}>
+        {/* SwiftUI dims a disabled button's label itself; a disabled colour on top of that dimmed it twice. */}
+        <Icon color="content.primary" name={name} />
+      </ZStack>
     </Button>
   )
 }

package/src/atoms/icon-button/icon-button.types.ts

@@ -2,15 +2,19 @@ import type {ReactNode} from 'react'
 
 import type {IconName} from '../icon'
 
-/** A button that is just an icon — a plain SwiftUI `Button` on iOS, Material's `IconButton` on Android. */
+/**
+ * A button that is just an icon: a plain SwiftUI `Button` on iOS, Material's `IconButton` on Android. The icon sits
+ * centred in a tap target the size each platform asks for, 44pt on iOS and 48dp on Android, so a row of them spaces
+ * itself the same way on both.
+ */
 export type IconButtonProps = {
-  /** Draws the icon in `btn.content.disabled` and stops the button responding to presses. */
+  /** Dims the icon (iOS's own disabled look, `btn.content.disabled` on Android) and stops the button responding. */
   disabled?: boolean
   /** The icon, one of the app's. */
   name: IconName
   /** Called when the button is pressed. */
   onPress?: () => void
-  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

package/src/atoms/island/island.types.ts

@@ -3,7 +3,7 @@ import type {ReactNode} from 'react'
 import type {StyleProp, ViewStyle} from 'react-native'
 
 /**
- * A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. It
+ * A host for native atoms in a React Native layout: the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. It
  * sits in that layout like a `Box`, and takes `Box`'s `sx` props for it: `h`, `flex`, margins.
  */
 export type IslandProps = ResponsiveViewSx & {
@@ -15,15 +15,15 @@ export type IslandProps = ResponsiveViewSx & {
    * width maps to `fixedSize(horizontal: true)`, so the native side ignores the proposed width and
    * resolves a `wide` stack's ideal width as unbounded.
    *
-   * Turn it off — and give the island an explicit height, `h` — when the subtree contains an
+   * Turn it off (and give the island an explicit height, `h`) when the subtree contains an
    * `RnView`: that host drives its SwiftUI frame from the child's Yoga-laid-out bounds while this one
    * writes its measured size back into the Yoga style, and the two together spin a layout loop that
    * hangs the main thread as soon as the views lay out on screen.
    */
   matchContents?: boolean
-  /** A React Native style for the host view, merged over the `sx` props — for what they cannot say. */
+  /** A React Native style for the host view, merged over the `sx` props, for what they cannot say. */
   style?: StyleProp<ViewStyle>
-  /** Test identifier, forwarded to the host view on iOS — Android ignores it. */
+  /** Test identifier, forwarded to the host view on iOS. Android ignores it. */
   testID?: string
 }
 

package/src/atoms/list/list.types.ts

@@ -1,23 +1,23 @@
 import type {ReactNode} from 'react'
 
 /**
- * A scrolling list — SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
+ * A scrolling list: SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
  * a `Screen`, or an `Island` with `matchContents={false}` and a height. In an island that sizes itself to its content
  * Compose measures it against an infinite height and throws ("Vertically scrollable component was measured with an
  * infinity maximum height"); SwiftUI shows nothing. For a handful of rows that should not scroll, use a `VStack`.
  *
- * Rows are separated for you — SwiftUI's own separators, a `Divider` between rows on Android — so a `Divider` among
+ * Rows are separated for you (SwiftUI's own separators, a `Divider` between rows on Android), so a `Divider` among
  * the children is one too many: on iOS it becomes an empty row of its own.
  */
 export type ListProps = {
-  /** The rows — native views, one row each. */
+  /** The rows: native views, one row each. */
   children: ReactNode
   /**
-   * Enables pull-to-refresh. Async on purpose — see `ScrollViewProps.onRefresh`: the spinner runs
+   * Enables pull-to-refresh. Async on purpose (see `ScrollViewProps.onRefresh`): the spinner runs
    * until the promise settles, so neither platform needs a `refreshing` flag kept in sync by hand.
    */
   onRefresh?: () => Promise<void>
-  /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
+  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
   testID?: string
 }
 

package/src/atoms/picker/picker.types.ts

@@ -9,7 +9,7 @@ export type PickerOption = {
 }
 
 /**
- * A single choice from a list — a SwiftUI wheel picker on iOS, Material's exposed dropdown on Android. It brings its
+ * A single choice from a list: a SwiftUI wheel picker on iOS, Material's exposed dropdown on Android. It brings its
  * own host, so it renders outside `Screen` and `Island` as well.
  */
 export type PickerProps = {