@hzblj/kara-components 0.9.0 → 0.11.0

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,21 @@ 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 = {
+  /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
+  accessibilityHint?: string
   /**
-   * 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 +44,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.android.tsx

@@ -1,16 +1,18 @@
 import {Column} from '@expo/ui/jetpack-compose'
 import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
-import {useSxModifiers} from '@hzblj/kara-sx'
+import {splitAccessibility, useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {CardComponent, CardProps} from './card.types'
 
-export const Card: CardComponent = ({children, testID, ...sx}: CardProps) => {
+export const Card: CardComponent = ({children, testID, ...props}: CardProps) => {
   useHostGuard('Card')
+  const [accessibility, sx] = splitAccessibility(props)
   const sxModifiers = useSxModifiers({bg: 'surface.primary', borderRadius: 'large', p: 's16', shadow: 'card', ...sx})
+  const accessibilityModifiers = useAccessibilityModifiers(accessibility)
   const modifiers = useMemo(
-    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
-    [sxModifiers, testID]
+    () => [...sxModifiers, ...(testID ? [testIdModifier(testID)] : []), ...accessibilityModifiers],
+    [accessibilityModifiers, sxModifiers, testID]
   )
 
   return <Column modifiers={modifiers}>{children}</Column>

package/src/atoms/card/card.ios.tsx

@@ -1,11 +1,15 @@
 import {VStack} from '@expo/ui/swift-ui'
-import {useSxModifiers} from '@hzblj/kara-sx'
+import {splitAccessibility, useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
+import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {CardComponent, CardProps} from './card.types'
 
-export const Card: CardComponent = ({children, testID, ...sx}: CardProps) => {
+export const Card: CardComponent = ({children, testID, ...props}: CardProps) => {
   useHostGuard('Card')
-  const modifiers = useSxModifiers({bg: 'surface.primary', borderRadius: 'large', p: 's16', shadow: 'card', ...sx})
+  const [accessibility, sx] = splitAccessibility(props)
+  const sxModifiers = useSxModifiers({bg: 'surface.primary', borderRadius: 'large', p: 's16', shadow: 'card', ...sx})
+  const accessibilityModifiers = useAccessibilityModifiers(accessibility)
+  const modifiers = useMemo(() => [...sxModifiers, ...accessibilityModifiers], [accessibilityModifiers, sxModifiers])
 
   return (
     <VStack alignment="leading" modifiers={modifiers} testID={testID}>

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

@@ -1,15 +1,16 @@
-import type {ResponsiveSx} from '@hzblj/kara-sx'
+import type {AccessibilityProps, 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 & {
-  /** Native views, stacked vertically from the leading edge. */
-  children?: ReactNode
-  /** Test identifier, forwarded to the native view. */
-  testID?: string
-}
+export type CardProps = ResponsiveSx &
+  AccessibilityProps & {
+    /** Native views, stacked vertically from the leading edge. */
+    children?: ReactNode
+    /** Test identifier, forwarded to the native view. */
+    testID?: string
+  }
 
 export type CardComponent = (props: CardProps) => ReactNode

package/src/atoms/checkbox/checkbox.android.tsx

@@ -23,7 +23,7 @@ export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueCha
   )
   const control = (
     <ComposeCheckbox
-      colors={{checkedColor: theme.color('fill.accent.primary'), checkmarkColor: theme.color('content.on.bg')}}
+      colors={{checkedColor: theme.color('fill.accent.primary'), checkmarkColor: theme.color('content.on.accent')}}
       enabled={!disabled}
       onCheckedChange={onValueChange ?? NOOP}
       value={value}

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.android.tsx

@@ -1,20 +1,22 @@
 import {FloatingActionButton} from '@expo/ui/jetpack-compose'
+import {useAccessibilityModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 
 import {useHostGuard} from '../../host-context'
 import {Icon} from '../icon'
 import type {FabComponent, FabProps} from './fab.types'
 
-export const Fab: FabComponent = ({name, onPress}: FabProps) => {
+export const Fab: FabComponent = ({accessibilityHint, accessibilityLabel, name, onPress}: FabProps) => {
   useHostGuard('Fab')
 
   const theme = useAppTheme()
+  const modifiers = useAccessibilityModifiers({accessibilityHint}, accessibilityHint !== undefined)
 
   return (
-    <FloatingActionButton containerColor={theme.color('fill.accent.primary')} onClick={onPress}>
+    <FloatingActionButton containerColor={theme.color('fill.accent.primary')} modifiers={modifiers} onClick={onPress}>
       {/* `@expo/ui`'s FAB is slot-based: content outside `.Icon` is not composed at all. */}
       <FloatingActionButton.Icon>
-        <Icon color="content.on.bg" name={name} />
+        <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} />
       </FloatingActionButton.Icon>
     </FloatingActionButton>
   )

package/src/atoms/fab/fab.ios.tsx

@@ -1,13 +1,14 @@
 import {Button} from '@expo/ui/swift-ui'
 import {buttonStyle} from '@expo/ui/swift-ui/modifiers'
-import {useSxModifiers} from '@hzblj/kara-sx'
+import {useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import {Icon} from '../icon'
 import type {FabComponent, FabProps} from './fab.types'
 
-export const Fab: FabComponent = ({name, onPress, testID}: FabProps) => {
+export const Fab: FabComponent = ({accessibilityHint, accessibilityLabel, name, onPress, testID}: FabProps) => {
   useHostGuard('Fab')
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint})
 
   const sxModifiers = useSxModifiers({
     bg: 'fill.accent.primary',
@@ -17,11 +18,14 @@ export const Fab: FabComponent = ({name, onPress, testID}: FabProps) => {
     shadow: 'btn.accent',
     w: 56,
   })
-  const modifiers = useMemo(() => [buttonStyle('plain'), ...sxModifiers], [sxModifiers])
+  const modifiers = useMemo(
+    () => [buttonStyle('plain'), ...sxModifiers, ...accessibilityModifiers],
+    [accessibilityModifiers, sxModifiers]
+  )
 
   return (
     <Button modifiers={modifiers} onPress={onPress} testID={testID}>
-      <Icon color="content.on.bg" name={name} />
+      <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} />
     </Button>
   )
 }

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

@@ -3,15 +3,22 @@ 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 = {
-  /** The icon, one of the app's, drawn in `content.on.bg`. */
+  /**
+   * What VoiceOver and TalkBack say for the button, since an icon has no words of its own: "Share", "Add to
+   * favourites". Required for that reason.
+   */
+  accessibilityLabel: string
+  /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
+  accessibilityHint?: string
+  /** The icon, one of the app's, drawn in `content.on.accent`. */
   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.android.tsx

@@ -31,7 +31,7 @@ export const GlassView: GlassViewComponent = ({
       cornerRadius={radii.full}
       fallbackTint={withOpacity(base, 'o95')}
       glassTint={withOpacity(base, tint ? 'o85' : 'o50')}
-      hairlineColor={withOpacity(String(theme.color('content.on.bg')), theme.dark ? 'o20' : 'o60')}
+      hairlineColor={withOpacity(String(theme.color('content.on.accent')), theme.dark ? 'o20' : 'o60')}
       hairlineWidth={1}
       saturation={1.6}
       style={style}

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.ios.tsx

@@ -1,6 +1,6 @@
 import {HStack as SwiftUIHStack} from '@expo/ui/swift-ui'
 import {onTapGesture} from '@expo/ui/swift-ui/modifiers'
-import {type FrameAlignment, useSxModifiers} from '@hzblj/kara-sx'
+import {type FrameAlignment, splitAccessibility, useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
 import {spacing} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
@@ -24,13 +24,15 @@ export const HStack: HStackComponent = ({
   onPress,
   spacing: gap,
   testID,
-  ...sx
+  ...props
 }: HStackProps) => {
   useHostGuard('HStack')
+  const [accessibility, sx] = splitAccessibility(props)
   const sxModifiers = useSxModifiers(sx, FRAME_ALIGNMENT[align])
+  const accessibilityModifiers = useAccessibilityModifiers(accessibility, onPress !== undefined)
   const modifiers = useMemo(
-    () => (onPress ? [...sxModifiers, onTapGesture(onPress)] : sxModifiers),
-    [onPress, sxModifiers]
+    () => [...sxModifiers, ...(onPress ? [onTapGesture(onPress)] : []), ...accessibilityModifiers],
+    [accessibilityModifiers, onPress, sxModifiers]
   )
 
   return (

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

@@ -1,21 +1,25 @@
-import type {ResponsiveSx} from '@hzblj/kara-sx'
+import type {AccessibilityProps, ResponsiveSx} from '@hzblj/kara-sx'
 import type {SpaceSize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 export type HStackAlign = 'center' | 'end' | 'start'
 
-/** 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. */
-  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. */
-  onPress?: () => void
-  /** The gap between children. Unset, SwiftUI puts its default spacing between them and Compose none. */
-  spacing?: SpaceSize
-  /** Test identifier, forwarded to the native view. */
-  testID?: string
-}
+/** A horizontal stack: SwiftUI `HStack` / Compose `Row`. */
+export type HStackProps = ResponsiveSx &
+  AccessibilityProps & {
+    /** 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. Screen readers
+     * then read the stack as one button.
+     */
+    onPress?: () => void
+    /** The gap between children. Unset, SwiftUI puts its default spacing between them and Compose none. */
+    spacing?: SpaceSize
+    /** Test identifier, forwarded to the native view. */
+    testID?: string
+  }
 
 export type HStackComponent = (props: HStackProps) => ReactNode

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.android.tsx

@@ -1,15 +1,28 @@
 import {IconButton as ComposeIconButton} from '@expo/ui/jetpack-compose'
+import {useAccessibilityModifiers} from '@hzblj/kara-sx'
 
 import {useHostGuard} from '../../host-context'
 import {Icon} from '../icon'
 import type {IconButtonComponent, IconButtonProps} from './icon-button.types'
 
-export const IconButton: IconButtonComponent = ({disabled = false, name, onPress}: IconButtonProps) => {
+export const IconButton: IconButtonComponent = ({
+  accessibilityHint,
+  accessibilityLabel,
+  disabled = false,
+  name,
+  onPress,
+}: IconButtonProps) => {
   useHostGuard('IconButton')
+  // The label rides on the icon, as Material's own icon buttons carry it; the hint labels the click.
+  const modifiers = useAccessibilityModifiers({accessibilityHint}, accessibilityHint !== undefined)
 
   return (
-    <ComposeIconButton enabled={!disabled} onClick={onPress}>
-      <Icon color={disabled ? 'btn.content.disabled' : 'content.primary'} name={name} />
+    <ComposeIconButton enabled={!disabled} modifiers={modifiers} onClick={onPress}>
+      <Icon
+        accessibilityLabel={accessibilityLabel}
+        color={disabled ? 'btn.content.disabled' : 'content.primary'}
+        name={name}
+      />
     </ComposeIconButton>
   )
 }

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

@@ -1,27 +1,46 @@
 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 {useAccessibilityModifiers} from '@hzblj/kara-sx'
 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'
 
-export const IconButton: IconButtonComponent = ({disabled = false, name, onPress, testID}: IconButtonProps) => {
+/** 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 = ({
+  accessibilityHint,
+  accessibilityLabel,
+  disabled = false,
+  name,
+  onPress,
+  testID,
+}: IconButtonProps) => {
   useHostGuard('IconButton')
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint})
 
   const modifiers = useMemo(() => {
-    const list = [buttonStyle('plain')]
+    const list = [buttonStyle('plain'), ...accessibilityModifiers]
 
     if (disabled) {
       list.push(disabledModifier(true))
     }
 
     return list
-  }, [disabled])
+  }, [accessibilityModifiers, disabled])
 
   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 accessibilityLabel={accessibilityLabel} color="content.primary" name={name} />
+      </ZStack>
     </Button>
   )
 }

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

@@ -2,15 +2,26 @@ 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. */
+  /**
+   * What VoiceOver and TalkBack say for the button, since an icon has no words of its own: "Share", "Add to
+   * favourites". Required for that reason.
+   */
+  accessibilityLabel: string
+  /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
+  accessibilityHint?: string
+  /** 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/image/image.tsx

@@ -3,12 +3,12 @@ import {duration} from '@hzblj/kara-theme'
 import {Image as ExpoImage, type ImageProps as ExpoImageProps} from 'expo-image'
 import type {Ref} from 'react'
 
-const FADE = {duration: duration.d100, timing: 'linear'} as const
+const FADE = {duration: duration.quick, timing: 'ease-out'} as const
 
 const FadingImage = (props: ExpoImageProps & {ref?: Ref<ExpoImage>}) => <ExpoImage transition={FADE} {...props} />
 
 /**
- * `expo-image` with the `sx` props, the way `Box` is a `View` with them, and the design system's 100 ms linear fade
- * already applied, so a loaded image never pops in. An explicit `transition` wins, and so does an explicit `style`.
+ * `expo-image` with the `sx` props, the way `Box` is a `View` with them, and the design system's fade (`quick`,
+ * eased out) already applied, so a loaded image never pops in. An explicit `transition` wins, and so does an explicit `style`.
  */
 export const Image = sx(FadingImage)

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
 }