@hzblj/kara-components 0.9.0 → 0.11.0

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

@@ -1,13 +1,13 @@
 import type { ReactNode } from 'react';
 import type { MenuAction } from '../menu';
 /**
- * A list of actions to pick one from: SwiftUI's confirmation dialog on iOS, a `Sheet` of Material rows — icon and label
- * — under the title on Android. A native atom — it renders inside `<Screen>` or `<Island>`.
+ * A list of actions to pick one from: SwiftUI's confirmation dialog on iOS, a `Sheet` of Material rows (icon and label)
+ * under the title on Android. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type ActionSheetProps = {
     /** The choices, top to bottom. Picking one closes the sheet. */
     actions: MenuAction[];
-    /** The sheet closed — after a pick too — so turn `visible` off. */
+    /** The sheet closed (after a pick too), so turn `visible` off. */
     onDismiss: () => void;
     /** The heading above the actions. Android always shows it; on iOS the system decides, and may hide it. */
     title: string;

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

@@ -1,18 +1,18 @@
 import type { ReactNode } from 'react';
 /**
  * A modal alert with a confirm button and Cancel: SwiftUI's alert on iOS, Material's `AlertDialog` on Android. A native
- * atom — it renders inside `<Screen>` or `<Island>`.
+ * atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type AlertProps = {
     /** The confirm button's label. `OK` by default. */
     confirmLabel?: string;
-    /** Marks the confirm button destructive — the system's destructive role on iOS, the destructive colour on Android. */
+    /** Marks the confirm button destructive: the system's destructive role on iOS, the destructive colour on Android. */
     destructive?: boolean;
     /** The body text, under the title. */
     message?: string;
     /** The confirm button was pressed. `onDismiss` follows, as it does for every way the alert closes. */
     onConfirm?: () => void;
-    /** The alert closed — either button, or on Android a tap outside or back — so turn `visible` off. */
+    /** The alert closed (either button, or on Android a tap outside or back), so turn `visible` off. */
     onDismiss: () => void;
     /** The alert's heading. */
     title: string;

package/lib/typescript/organisms/context-menu/context-menu.types.d.ts

@@ -2,7 +2,7 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 import type { MenuAction } from '../menu';
 /**
- * A context menu on a React Native subtree — a card in a list, say — opened by a long press. iOS: a
+ * A context menu on a React Native subtree (a card in a list, say), opened by a long press. iOS: a
  * `UIContextMenuInteraction`, with an optional React Native `preview` lifted while the menu is open and a callback for
  * a tap on it. Android, where Material has no lifted preview: a ripple and the long-press haptic, then a Material
  * dropdown where the finger is, with the trigger highlighted while it is open. The trigger is ordinary React Native layout, so it
@@ -13,33 +13,33 @@ export type ContextMenuProps = ResponsiveViewSx & {
     actions: MenuAction[];
     /** The trigger, laid out as usual. */
     children: ReactNode;
-    /** iOS: the user tapped the lifted preview, committing to it — open the detail the card stands for. */
+    /** iOS: the user tapped the lifted preview, committing to it. Open the detail the card stands for. */
     onPreviewPress?: () => void;
     /**
-     * iOS: lifted in place of the trigger while the menu is open — a larger version of the card, say. A snapshot of the
+     * iOS: lifted in place of the trigger while the menu is open (a larger version of the card, say). A snapshot of the
      * trigger when unset. Mounted only once a finger has rested on the trigger, so a list of cards does not pay for
      * every preview up front.
      */
     preview?: ReactNode;
     /**
      * iOS: how the preview leaves once tapped, before `onPreviewPress`. `zoom`: its photo grows straight into the pushed
-     * screen, the way the App Store expands a preview — needs a `ZoomTransition.Source` (`@hzblj/kara-ui/router`) in the
-     * trigger, a `preview` and iOS 18, and shrinks back like `dismiss` otherwise. `pop`: UIKit's default, the preview
+     * screen, the way the App Store expands a preview. It needs a `ZoomTransition.Source` (`@hzblj/kara-ui/router`) in
+     * the trigger, a `preview` and iOS 18, and shrinks back like `dismiss` otherwise. `pop`: UIKit's default, the preview
      * flies out. `dismiss`: it shrinks back onto the trigger first. Default: `zoom` when the trigger holds a
      * `ZoomTransition.Source`, `pop` otherwise.
      */
     previewTransition?: 'dismiss' | 'pop' | 'zoom';
-    /** Test identifier — on the native view around the trigger on iOS, on the trigger's `Pressable` on Android. */
+    /** Test identifier: on the native view around the trigger on iOS, on the trigger's `Pressable` on Android. */
     testID?: string;
 };
-/** A region of a `ContextMenu`'s trigger that keeps its own long press — see `ContextMenu.Exclusion`. */
+/** A region of a `ContextMenu`'s trigger that keeps its own long press (see `ContextMenu.Exclusion`). */
 export type ContextMenuExclusionProps = {
-    /** The region — a button inside the card, say. */
+    /** The region: a button inside the card, say. */
     children: ReactNode;
 };
 export type ContextMenuComponent = ((props: ContextMenuProps) => ReactNode) & {
     /**
-     * A region of the trigger that must not open the menu — a button inside the card. On iOS the interaction covers the
+     * A region of the trigger that must not open the menu: a button inside the card. On iOS the interaction covers the
      * whole trigger, so a long press on that button would otherwise open the card's menu.
      */
     Exclusion: (props: ContextMenuExclusionProps) => ReactNode;

package/lib/typescript/organisms/fab-menu/fab-menu.types.d.ts

@@ -2,16 +2,21 @@ import type { ReactNode } from 'react';
 import type { IconName } from '../../atoms/icon';
 import type { MenuAction } from '../menu';
 /**
- * A floating action button that unfolds into its actions. Android: Material 3 Expressive's `FloatingActionButtonMenu`
- * — the button turns into a close and the actions rise above it as labelled pills. iOS: the same button as the label
- * of a SwiftUI `Menu`. A native atom — it renders inside `<Screen>` or `<Island>`.
+ * A floating action button that unfolds into its actions. Android: Material 3 Expressive's `FloatingActionButtonMenu`,
+ * where the button turns into a close and the actions rise above it as labelled pills. iOS: the same button as the
+ * label of a SwiftUI `Menu`. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type FabMenuProps = {
+    /**
+     * What VoiceOver and TalkBack say for the button, since an icon has no words of its own: "Create". Required for that
+     * reason.
+     */
+    accessibilityLabel: string;
     /** The actions the button unfolds into. */
     actions: MenuAction[];
-    /** The closed button's icon — one of the app's. A plus by default. */
+    /** The closed button's icon, one of the app's. A plus by default. */
     icon?: IconName;
-    /** Test identifier, forwarded to the SwiftUI `Menu`. iOS only — Android ignores it. */
+    /** Test identifier, forwarded to the SwiftUI `Menu`. iOS only; Android ignores it. */
     testID?: string;
 };
 export type FabMenuComponent = (props: FabMenuProps) => ReactNode;

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

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 /**
- * A settings form — SwiftUI `Form` with its grouped sections, Material cards on Android. On iOS it scrolls like a
+ * A settings form: SwiftUI `Form` with its grouped sections, Material cards on Android. On iOS it scrolls like a
  * `List`, so it needs a height from outside: a `Screen`, or an `Island` with `matchContents={false}` and a height. In
  * an island that sizes itself to its content it has no height and shows nothing.
  */

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

@@ -3,7 +3,7 @@ import type { IconName } from '../../atoms/icon';
 /** One action of a `Menu`, an `ActionSheet`, a `ContextMenu` or a `FabMenu`. */
 export type MenuAction = {
     /**
-     * Draws the action in the destructive colour — the system's destructive role on iOS. `FabMenu` ignores it on
+     * Draws the action in the destructive colour (the system's destructive role on iOS). `FabMenu` ignores it on
      * Android.
      */
     destructive?: boolean;
@@ -19,7 +19,7 @@ export type MenuAction = {
 };
 /**
  * A text button that opens a list of actions: a SwiftUI `Menu` on iOS, a Material dropdown anchored to it on Android.
- * A native atom — it renders inside `<Screen>` or `<Island>`.
+ * A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type MenuProps = {
     /** The menu's actions, top to bottom. */

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

@@ -1,16 +1,49 @@
-import type { ReactNode } from 'react';
+import type { SpaceSize } from '@hzblj/kara-theme';
+import type { ComponentProps, ReactNode } from 'react';
+import type Animated from 'react-native-reanimated';
+type LayoutAnimation = ComponentProps<typeof Animated.View>['entering'];
+/** How it comes and goes. */
+export type SnackbarAnimation = 'fade' | 'scale' | 'slide';
+/** How long it stays: Material's short (4 s) and long (10 s), never, or a number of milliseconds. */
+export type SnackbarDuration = 'indefinite' | 'long' | 'short' | number;
+/** The edge of its parent it sits on. */
+export type SnackbarPosition = 'bottom' | 'top';
 /**
- * A short message laid over the bottom of its parent, with an optional action. The React Native tier, drawn the same on
- * both platforms: it needs no host, and it never hides itself.
+ * A short message laid over an edge of its parent, with an optional action at its trailing end. The React Native tier,
+ * drawn the same on both platforms (iOS has no snackbar of its own), so it needs no host. Material's options are all
+ * here: a duration, a dismiss button, the action on a line of its own. It is announced to VoiceOver and TalkBack when
+ * it appears.
  */
 export type SnackbarProps = {
-    /** The action button's text, on the trailing side. No button without it. */
+    /** The action button's text, at the trailing end. No button without it. */
     actionLabel?: string;
+    /** Puts the action under the message, at its trailing end: Material's layout for a long message or action. */
+    actionOnNewLine?: boolean;
+    /**
+     * How it comes and goes. `scale` is Material's own (a fade and a scale from 80 %), `slide` rises from its edge as it
+     * fades in, `fade` only fades. `scale` on Android and `slide` on iOS by default. With motion reduced, it fades.
+     */
+    animation?: SnackbarAnimation;
+    /** A close button at the trailing end, Material's dismiss action; it calls `onDismiss`. */
+    dismissible?: boolean;
+    /** How long it stays up before `onDismiss` is called. `indefinite` by default: it never hides itself. */
+    duration?: SnackbarDuration;
+    /** A Reanimated entering animation of your own, e.g. `FadeInDown.springify()`. It wins over `animation`. */
+    entering?: LayoutAnimation;
+    /** A Reanimated exiting animation of your own. It wins over `animation`. */
+    exiting?: LayoutAnimation;
     /** The message. */
     message: string;
-    /** The action was pressed. The snackbar stays up — turn `visible` off to hide it. */
+    /** Between the snackbar and its edge, a space token. `s24` by default; raise it above a tab bar. */
+    offset?: SpaceSize;
+    /** 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. */
+    /** It asks to go: its `duration` ran out, or its dismiss button was pressed. Turn `visible` off to hide it. */
+    onDismiss?: () => void;
+    /** The edge of its parent it sits on. `bottom` by default, Material's place for it. */
+    position?: SnackbarPosition;
+    /** Shows the snackbar while true, animating it in and out. */
     visible: boolean;
 };
 export type SnackbarComponent = (props: SnackbarProps) => ReactNode;
+export {};

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/lib/typescript/use-stack-modifiers.d.ts

@@ -1,8 +1,9 @@
 import { type ModifierConfig } from '@expo/ui/jetpack-compose/modifiers';
-import { type ResponsiveSx } from '@hzblj/kara-sx';
+import { type AccessibilityProps, type ResponsiveSx } from '@hzblj/kara-sx';
 /**
- * A Compose stack's modifiers in the order a pressable one needs: its frame, shape and background, then the press,
- * then its padding. Compose clips a `clickable` to what comes after it, so with the padding first the ripple would stop
- * at the padding and a row pressed by its edge would light up only in the middle.
+ * A Compose stack's modifiers in the order a pressable one needs: its frame, shape and background, then the press, its
+ * semantics, then its padding. Compose clips a `clickable` to what comes after it, so with the padding first the ripple
+ * would stop at the padding and a row pressed by its edge would light up only in the middle. The semantics come after
+ * the click, because a label that replaces the children's clears whatever semantics are inside it.
  */
-export declare const useStackModifiers: (sx: ResponsiveSx, onPress?: () => void, testID?: string) => ModifierConfig[];
+export declare const useStackModifiers: (props: ResponsiveSx & AccessibilityProps, onPress?: () => void, testID?: string) => ModifierConfig[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.9.0",
+  "version": "0.11.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.9.0",
-    "@hzblj/kara-sx": "^0.9.0",
-    "@hzblj/kara-theme": "^0.9.0",
+    "@hzblj/kara-native": "^0.11.0",
+    "@hzblj/kara-sx": "^0.11.0",
+    "@hzblj/kara-theme": "^0.11.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {

package/src/atoms/activity-indicator/activity-indicator.android.tsx

@@ -1,5 +1,6 @@
 import {Host, LoadingIndicator} from '@expo/ui/jetpack-compose'
 import {fillMaxSize, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useAccessibilityModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {StyleSheet} from 'react-native'
@@ -17,12 +18,17 @@ const styles = StyleSheet.create({
  * anywhere and takes its place in the first frame.
  */
 export const ActivityIndicator: ActivityIndicatorComponent = ({
+  accessibilityLabel,
   color = 'fill.accent.primary',
   size = 'small',
   testID,
 }: ActivityIndicatorProps) => {
   const theme = useAppTheme()
-  const modifiers = useMemo(() => (testID ? [fillMaxSize(), testIdModifier(testID)] : [fillMaxSize()]), [testID])
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityLabel})
+  const modifiers = useMemo(
+    () => [fillMaxSize(), ...(testID ? [testIdModifier(testID)] : []), ...accessibilityModifiers],
+    [accessibilityModifiers, testID]
+  )
 
   return (
     <Host colorScheme={theme.dark ? 'dark' : 'light'} seedColor={theme.materialSeed} style={styles[size]}>

package/src/atoms/activity-indicator/activity-indicator.ios.tsx

@@ -5,11 +5,19 @@ import type {ActivityIndicatorComponent, ActivityIndicatorProps} from './activit
 
 /** React Native's spinner, which on iOS is UIKit's own `UIActivityIndicatorView`. */
 export const ActivityIndicator: ActivityIndicatorComponent = ({
+  accessibilityLabel,
   color = 'fill.accent.primary',
   size = 'small',
   testID,
 }: ActivityIndicatorProps) => {
   const theme = useAppTheme()
 
-  return <RNActivityIndicator color={theme.color(color)} size={size} testID={testID} />
+  return (
+    <RNActivityIndicator
+      accessibilityLabel={accessibilityLabel}
+      color={theme.color(color)}
+      size={size}
+      testID={testID}
+    />
+  )
 }

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

@@ -4,11 +4,13 @@ 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`.
  */
 export type ActivityIndicatorProps = {
+  /** What is loading, for VoiceOver and TalkBack: "Loading photos". Unset, the platform's own word ("In progress"). */
+  accessibilityLabel?: string
   /** Its colour. `fill.accent.primary` by default. */
   color?: ColorToken
   /** `small` sits in a row or a button, `large` holds a screen that is loading. `small` by default. */

package/src/atoms/avatar/avatar.tsx

@@ -17,11 +17,15 @@ const VARIANT = {
   sm: 'caption',
 } as const
 
-export const Avatar: AvatarComponent = ({initials, size = 'md', source, testID}: AvatarProps) => {
+export const Avatar: AvatarComponent = ({accessibilityLabel, initials, size = 'md', source, testID}: AvatarProps) => {
   const diameter = DIAMETER[size]
 
   return (
     <Box
+      aria-hidden={accessibilityLabel === undefined}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole={accessibilityLabel === undefined ? undefined : 'image'}
+      accessible={accessibilityLabel !== undefined}
       align="center"
       bg="fill.tertiary"
       borderRadius="full"

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

@@ -3,11 +3,16 @@ 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 = {
+  /**
+   * Who it is, for VoiceOver and TalkBack: "Jan Blazej". Unset, the avatar is decorative and hidden from them, as one
+   * beside the person's name should be.
+   */
+  accessibilityLabel?: string
   /** 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-tokens.ts

@@ -9,7 +9,7 @@ type ButtonTokens = {
 }
 
 const TOKENS = {
-  accent: {content: 'content.on.bg', fill: 'fill.accent.primary', shadow: 'btn.accent'},
+  accent: {content: 'content.on.accent', fill: 'fill.accent.primary', shadow: 'btn.accent'},
   destructive: {content: 'content.on.destructive', fill: 'fill.destructive.primary', shadow: 'btn.destructive'},
   glass: {content: 'content.primary', fill: 'btn.bg.glass.base', shadow: 'btn.glass'},
   secondary: {content: 'content.primary', fill: 'btn.bg.secondary.base', shadow: 'btn.secondary'},
@@ -81,4 +81,4 @@ const currentHex = (token: ColorToken, theme: Theme): unknown => {
  * content colour over a pale one (`fill.accent.base`) — the light container tokens pair with it in both appearances.
  */
 export const contentOnTint = (tint: ColorToken, theme: Theme): ColorToken =>
-  (luminance(currentHex(tint, theme)) ?? 0) > 0.4 ? 'content.primary' : 'content.on.bg'
+  (luminance(currentHex(tint, theme)) ?? 0) > 0.4 ? 'content.primary' : 'content.on.accent'

package/src/atoms/button/button.android.tsx

@@ -1,6 +1,6 @@
 import {Button as ComposeButton, Text as ComposeText, OutlinedButton} from '@expo/ui/jetpack-compose'
 import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
-import {useSxModifiers} from '@hzblj/kara-sx'
+import {useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
@@ -16,6 +16,7 @@ import {buttonTokens, contentOnTint} from './button-tokens'
  * colour, as a prominent style does on iOS. `buttonStyle` and `controlSize` are SwiftUI's alone.
  */
 export const Button: ButtonComponent = ({
+  accessibilityHint,
   disabled = false,
   label,
   onPress,
@@ -28,9 +29,10 @@ export const Button: ButtonComponent = ({
   const theme = useAppTheme()
   const tokens = buttonTokens(variant, disabled, theme)
   const sxModifiers = useSxModifiers({wide})
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint}, accessibilityHint !== undefined)
   const modifiers = useMemo(
-    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
-    [sxModifiers, testID]
+    () => [...sxModifiers, ...(testID ? [testIdModifier(testID)] : []), ...accessibilityModifiers],
+    [accessibilityModifiers, sxModifiers, testID]
   )
   const style = theme.typography.body
   const outlined = variant === 'glass' && !tint

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

@@ -6,6 +6,7 @@ import {
   glassEffect as glassEffectModifier,
   tint as tintModifier,
 } from '@expo/ui/swift-ui/modifiers'
+import {useAccessibilityModifiers} from '@hzblj/kara-sx'
 import {type ColorToken, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
@@ -29,6 +30,7 @@ const TINT_BY_VARIANT = {
 } as const satisfies Record<ButtonVariant, ColorToken | undefined>
 
 export const Button: ButtonComponent = ({
+  accessibilityHint,
   buttonStyle,
   controlSize = 'large',
   disabled = false,
@@ -59,8 +61,14 @@ export const Button: ButtonComponent = ({
   // A prominent style — and tinted glass — is coloured by the tint, so a caller's own tint picks the label on it.
   const content = tint && filled && !disabled ? contentOnTint(tint, theme) : tokens.content
 
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint})
+
   const modifiers = useMemo(() => {
-    const list = [buttonStyleModifier(glassTint ? 'plain' : style), controlSizeModifier(controlSize)]
+    const list = [
+      buttonStyleModifier(glassTint ? 'plain' : style),
+      controlSizeModifier(controlSize),
+      ...accessibilityModifiers,
+    ]
 
     if (glassTint) {
       list.push(
@@ -75,7 +83,7 @@ export const Button: ButtonComponent = ({
     }
 
     return list
-  }, [controlSize, disabled, glassTint, resolvedTint, style, theme])
+  }, [accessibilityModifiers, controlSize, disabled, glassTint, resolvedTint, style, theme])
 
   return (
     <SwiftUIButton modifiers={modifiers} onPress={onPress} testID={testID}>