@hzblj/kara-components 0.16.0 → 0.18.0

package/lib/typescript/molecules/search-bar/search-bar.types.d.ts

@@ -1,11 +1,21 @@
 import type { ReactNode } from 'react';
+import type { TextFieldAutoCapitalize } from '../../atoms/text-field';
 /**
  * A search field drawn the same on both platforms: a rounded box with a magnifier, a `TextInput` and a clear button
- * while there is text. The React Native tier: it needs no host.
+ * while there is text. The keyboard's return key reads Search, and a query is taken as typed: no capitals and no
+ * corrections unless asked for. The React Native tier: it needs no host.
  */
 export type SearchBarProps = {
+    /** When the keyboard turns Shift on by itself. `none` by default: a query is not a sentence. */
+    autoCapitalize?: TextFieldAutoCapitalize;
+    /** Lets the keyboard correct words as they are typed. Off by default, so a query is searched as typed. */
+    autoCorrect?: boolean;
+    /** Takes focus, and brings up the keyboard, as soon as the field appears. Off by default. */
+    autoFocus?: boolean;
     /** Every edit, and `''` when the clear button is pressed. */
     onChangeText?: (text: string) => void;
+    /** Called with the query when the keyboard's Search key is pressed. The keyboard goes down after it. */
+    onSubmit?: (text: string) => void;
     /** Shown while the field is empty. `Search` by default. */
     placeholder?: string;
     /** Test identifier, put on the field's container view rather than on the `TextInput`. */

package/lib/typescript/molecules/stepper/stepper.ios.d.ts

@@ -2,6 +2,7 @@ import type { StepperComponent } from './stepper.types';
 /**
  * SwiftUI's `Stepper` at the end of a row, the label leading and the value just before the control — the way iOS's own
  * settings show a stepped value. The value rolls to the next one (`numericText`), up or down with the change, in
- * monospaced digits so the row does not jump. With motion reduced it cross-fades instead.
+ * monospaced digits so the row does not jump. With motion reduced it cross-fades instead. Its buttons are labelled by
+ * the system, so `decrementLabel` and `incrementLabel` are Android's alone.
  */
 export declare const Stepper: StepperComponent;

package/lib/typescript/molecules/stepper/stepper.types.d.ts

@@ -4,6 +4,18 @@ import type { ReactNode } from 'react';
  * two icon buttons in a row. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type StepperProps = {
+    /**
+     * What TalkBack says for the minus button. `Decrement` by default: pass the app's own words, in its language.
+     * Android only. iOS ignores it: its native stepper labels its buttons itself, in the device's language.
+     */
+    decrementLabel?: string;
+    /** Stops the user changing the value, and dims the row. */
+    disabled?: boolean;
+    /**
+     * What TalkBack says for the plus button. `Increment` by default: pass the app's own words, in its language. Android
+     * only. iOS ignores it: its native stepper labels its buttons itself, in the device's language.
+     */
+    incrementLabel?: string;
     /** The leading text. The value is shown too: before the control on iOS, between the buttons on Android. */
     label: string;
     /** The highest value. When unset, Android has no upper limit and iOS stops at `100`. */
@@ -14,6 +26,11 @@ export type StepperProps = {
     onValueChange: (value: number) => void;
     /** How much one press adds or takes away. `1` by default. */
     step?: number;
+    /**
+     * Test identifier, on the control rather than the row: SwiftUI's `Stepper` on iOS, the minus and plus buttons with
+     * the value between them on Android. Reach a button by what screen readers say for it.
+     */
+    testID?: string;
     /** The current value. Update it from `onValueChange`. iOS's native stepper counts in whole numbers. */
     value: number;
 };

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

@@ -1,2 +1,6 @@
 import type { ActionSheetComponent } from './action-sheet.types';
+/**
+ * `titleVisibility="visible"`: left to `automatic`, SwiftUI drops the title of a dialog presented as an action sheet,
+ * and the actions lose what they are about.
+ */
 export declare const ActionSheet: ActionSheetComponent;

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

@@ -2,14 +2,19 @@ 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>`.
+ * under the title and message on Android. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type ActionSheetProps = {
-    /** The choices, top to bottom. Picking one closes the sheet. */
+    /** The choices, top to bottom. Picking one closes the sheet. A `disabled` one stays in the list, greyed. */
     actions: MenuAction[];
+    /**
+     * A line under the title saying what the choice is about: "The photo will be removed from all your devices." Unset,
+     * the title stands alone.
+     */
+    message?: string;
     /** 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. */
+    /** The heading above the actions, shown on both platforms. */
     title: string;
     /** Presents the sheet while true. */
     visible: boolean;

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

@@ -1,9 +1,14 @@
 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>`.
+ * A modal alert with a confirm button and a cancel button (or the confirm button alone): SwiftUI's alert on iOS,
+ * Material's `AlertDialog` on Android. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type AlertProps = {
+    /**
+     * The cancel button's label, in the app's language: "Zrušit". `Cancel` by default. `null` leaves the button out, for
+     * an alert that only informs and is closed by its confirm button alone ("OK").
+     */
+    cancelLabel?: string | null;
     /** 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. */
@@ -12,7 +17,7 @@ export type AlertProps = {
     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 (any of its buttons, or on Android a tap outside or back), so turn `visible` off. */
     onDismiss: () => void;
     /** The alert's heading. */
     title: string;

package/lib/typescript/organisms/menu/menu-parts.d.ts

@@ -0,0 +1,14 @@
+import type { ColorToken } from '@hzblj/kara-theme';
+import type { IconName } from '../../atoms/icon';
+import type { MenuAction, MenuProps } from './menu.types';
+/**
+ * An action's colour in a row kara draws itself (the Android menus and sheets): greyed when disabled, as `IconButton`
+ * greys, red when destructive. A Compose `DropdownMenuItem` cannot grey its own text here, since the text sets its
+ * colour explicitly.
+ */
+export declare const menuActionColor: ({ destructive, disabled }: MenuAction) => ColorToken;
+/** A trigger with no text: the props' union guarantees its icon and the words a screen reader says for it. */
+export declare const isIconOnly: (props: MenuProps) => props is MenuProps & {
+    accessibilityLabel: string;
+    icon: IconName;
+};

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

@@ -8,8 +8,13 @@ export type MenuAction = {
      */
     destructive?: boolean;
     /**
-     * One of the app's icons, before the label. `ContextMenu` and `FabMenu` show it on both platforms, `Menu` and
-     * `ActionSheet` on Android only.
+     * Greys the action out and stops it responding, for one that does not apply right now: "Paste" with nothing copied.
+     * Off by default. `FabMenu` ignores it on Android, where Material's FAB menu items have no disabled state.
+     */
+    disabled?: boolean;
+    /**
+     * One of the app's icons, before the label. `Menu`, `ContextMenu` and `FabMenu` show it on both platforms,
+     * `ActionSheet` on Android only: an iOS confirmation dialog draws text alone.
      */
     icon?: IconName;
     /** The action's text. Rows are keyed by it, so keep labels unique within one list. */
@@ -17,14 +22,37 @@ export type MenuAction = {
     /** Called when the action is chosen; the menu closes by itself. */
     onPress: () => void;
 };
+/** What the trigger needs: its text, or an icon and the words a screen reader says for it. */
+type MenuTrigger = {
+    label: string;
+} | {
+    accessibilityLabel: string;
+    icon: IconName;
+};
 /**
- * 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 button that opens a list of actions: a SwiftUI `Menu` on iOS, a Material dropdown anchored to it on Android. The
+ * trigger is text, an icon and text, or an icon alone. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
-export type MenuProps = {
+export type MenuProps = MenuTrigger & {
+    /**
+     * What VoiceOver and TalkBack say for the trigger: "More options". Required with an `icon` and no `label`, since an
+     * icon has no words of its own. With a label, it replaces the label for screen readers.
+     */
+    accessibilityLabel?: string;
     /** The menu's actions, top to bottom. */
     actions: MenuAction[];
-    /** The trigger's text. Android draws it in the accent colour, with a chevron. */
-    label: string;
+    /**
+     * One of the app's icons on the trigger. Before the `label`, in the same colour, when there is one; alone, the
+     * trigger is drawn as an `IconButton` (`content.primary`, in a 44pt target on iOS and 48dp on Android) and needs an
+     * `accessibilityLabel`.
+     */
+    icon?: IconName;
+    /**
+     * The trigger's text. Android draws it in the accent colour, with a chevron. Required unless there is an `icon`.
+     */
+    label?: string;
+    /** Test identifier, forwarded to the trigger. Reach an action by its label once the menu is open. */
+    testID?: string;
 };
 export type MenuComponent = (props: MenuProps) => ReactNode;
+export {};

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

@@ -46,7 +46,7 @@ export type SheetRef = {
  * one; native atoms in its content go in an `Island`.
  */
 export type SheetProps = {
-    /** The sheet's colour. `surface.primary` by default. */
+    /** The sheet's colour. `surface.primary` by default; ignored on iOS with `systemBackground`. */
     bg?: ColorToken;
     /** The content. A `<Sheet.Header>` among the direct children becomes the native header instead. */
     children: ReactNode;
@@ -75,6 +75,12 @@ export type SheetProps = {
      * and a header scrolls with the iOS 26 edge effect. Off by default; set it with a scrolling body.
      */
     scrollable?: boolean;
+    /**
+     * iOS: the system's own sheet background instead of `bg` — untinted Liquid Glass on iOS 26, a material blur before
+     * it — for a sheet that floats over content it should let through, like a map. Keep the content free of fills. Android
+     * keeps `bg`. Off by default.
+     */
+    systemBackground?: boolean;
     /** Test identifier, forwarded to the native sheet. */
     testID?: string;
     /** Presents the sheet while true; going false dismisses it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.16.0",
+  "version": "0.18.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",
@@ -61,9 +61,9 @@
   "dependencies": {
     "@hzblj/expo-native-icons": "^0.1.0",
     "@hzblj/expo-rich-haptics": "^0.1.0",
-    "@hzblj/kara-native": "^0.16.0",
-    "@hzblj/kara-sx": "^0.16.0",
-    "@hzblj/kara-theme": "^0.16.0",
+    "@hzblj/kara-native": "^0.18.0",
+    "@hzblj/kara-sx": "^0.18.0",
+    "@hzblj/kara-theme": "^0.18.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {

package/src/atoms/badge/badge.android.tsx

@@ -1,17 +1,24 @@
 import {Badge as ComposeBadge, Text as ComposeText} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {BadgeComponent, BadgeProps} from './badge.types'
 import {BADGE_TOKENS} from './badge-tokens'
 
 /** Material's badge. Its content is a Compose `Text` — `@expo/ui`'s badge takes composable content, not a string. */
-export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) => {
+export const Badge: BadgeComponent = ({label, testID, tone = 'neutral'}: BadgeProps) => {
   useHostGuard('Badge')
   const theme = useAppTheme()
   const tokens = BADGE_TOKENS[tone]
+  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
 
   return (
-    <ComposeBadge containerColor={theme.color(tokens.fill)} contentColor={theme.color(tokens.content)}>
+    <ComposeBadge
+      containerColor={theme.color(tokens.fill)}
+      contentColor={theme.color(tokens.content)}
+      modifiers={modifiers}
+    >
       <ComposeText color={theme.colorString(tokens.content)} style={theme.typography.captionMedium}>
         {label}
       </ComposeText>

package/src/atoms/badge/badge.ios.tsx

@@ -5,13 +5,13 @@ import {Text} from '../text'
 import type {BadgeComponent, BadgeProps} from './badge.types'
 import {BADGE_TOKENS} from './badge-tokens'
 
-export const Badge: BadgeComponent = ({label, tone = 'neutral'}: BadgeProps) => {
+export const Badge: BadgeComponent = ({label, testID, tone = 'neutral'}: BadgeProps) => {
   useHostGuard('Badge')
   const tokens = BADGE_TOKENS[tone]
   const modifiers = useSxModifiers({bg: tokens.fill, borderRadius: 'full', px: 's8', py: 's2'})
 
   return (
-    <HStack modifiers={modifiers}>
+    <HStack modifiers={modifiers} testID={testID}>
       <Text color={tokens.content} variant="labelMedium">
         {label}
       </Text>

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

@@ -6,6 +6,8 @@ export type BadgeTone = 'accent' | 'destructive' | 'neutral' | 'success'
 export type BadgeProps = {
   /** The text inside. */
   label: string
+  /** Test identifier, forwarded to the native view. */
+  testID?: string
   /** The fill and text colours. `neutral` by default. */
   tone?: BadgeTone
 }

package/src/atoms/button/button-tokens.ts

@@ -2,16 +2,18 @@ import type {ColorToken, ShadowName, Theme} from '@hzblj/kara-theme'
 
 import type {ButtonVariant} from './button.types'
 
+/** `fill` and `shadow` are unset for `plain`: a text button has no container to fill or lift. */
 type ButtonTokens = {
   content: ColorToken
-  fill: ColorToken
-  shadow: ShadowName
+  fill: ColorToken | undefined
+  shadow: ShadowName | undefined
 }
 
 const TOKENS = {
   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'},
+  plain: {content: 'content.accent', fill: undefined, shadow: undefined},
   secondary: {content: 'content.primary', fill: 'btn.bg.secondary.base', shadow: 'btn.secondary'},
 } as const satisfies Record<ButtonVariant, ButtonTokens>
 
@@ -26,8 +28,9 @@ export const buttonTokens = (variant: ButtonVariant, disabled: boolean, theme: T
     accent: 'fill.accent.disabled',
     destructive: 'fill.destructive.disabled',
     glass: 'btn.bg.glass.disabled',
+    plain: undefined,
     secondary: 'btn.bg.secondary.disabled',
-  } as const satisfies Record<ButtonVariant, ColorToken>
+  } as const satisfies Record<ButtonVariant, ColorToken | undefined>
 
   void theme
 

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

@@ -1,23 +1,43 @@
-import {Button as ComposeButton, Text as ComposeText, OutlinedButton} from '@expo/ui/jetpack-compose'
-import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {
+  Button as ComposeButton,
+  Spacer as ComposeSpacer,
+  Text as ComposeText,
+  OutlinedButton,
+  TextButton,
+} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier, width as widthModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {spacing, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
+import {Icon} from '../icon'
 import type {ButtonComponent, ButtonProps} from './button.types'
 import {buttonTokens, contentOnTint} from './button-tokens'
 
+/** Material's `ButtonDefaults.IconSpacing`: the gap between a button's icon and its label. */
+const ICON_GAP = [widthModifier(spacing.s8)]
+
+/**
+ * Material's padding for a button with a leading icon (`ButtonWithIconContentPadding`,
+ * `TextButtonWithIconContentPadding`): the icon side a step tighter than the label's. Top and bottom keep the defaults.
+ */
+const WITH_ICON_PADDING = {end: spacing.s24, start: spacing.s16}
+const TEXT_WITH_ICON_PADDING = {end: spacing.s16, start: spacing.s12}
+
 /**
  * Material's filled button, in its own stadium shape. No `borderRadius` or `shadow` from the tokens: those shape the
  * SwiftUI button's glossy ring, and laid over a Compose button they clip and outline a rounded rectangle around the
- * pill Material draws. The label is a Compose `Text` — `@expo/ui`'s button takes composable content, not a string.
+ * pill Material draws. The label is a Compose `Text` — `@expo/ui`'s button takes composable content, not a string —
+ * after the `icon`, when there is one, in the same row.
  *
- * Material has no glass, so `glass` is its outlined button — and a `tint` makes any variant a filled button in that
- * colour, as a prominent style does on iOS. `buttonStyle` and `controlSize` are SwiftUI's alone.
+ * Material has no glass, so `glass` is its outlined button — and a `tint` makes any variant but `plain` a filled
+ * button in that colour, as a prominent style does on iOS. `plain` is Material's `TextButton`, and a `tint` colours its
+ * label. `buttonStyle` and `controlSize` are SwiftUI's alone.
  */
 export const Button: ButtonComponent = ({
   accessibilityHint,
   disabled = false,
+  icon,
   label,
   onPress,
   testID,
@@ -35,27 +55,31 @@ export const Button: ButtonComponent = ({
     [accessibilityModifiers, sxModifiers, testID]
   )
   const style = theme.typography.body
+  const text = variant === 'plain'
   const outlined = variant === 'glass' && !tint
   const fill = tint && !disabled ? tint : tokens.fill
-  const content = tint && !disabled ? contentOnTint(tint, theme) : tokens.content
-  const MaterialButton = outlined ? OutlinedButton : ComposeButton
+  const content = !tint || disabled ? tokens.content : text ? tint : contentOnTint(tint, theme)
+  const MaterialButton = text ? TextButton : outlined ? OutlinedButton : ComposeButton
 
   return (
     <MaterialButton
       colors={
-        outlined
-          ? {contentColor: theme.color(content), disabledContentColor: theme.color(content)}
-          : {
+        fill && !text && !outlined
+          ? {
               containerColor: theme.color(fill),
               contentColor: theme.color(content),
               disabledContainerColor: theme.color(fill),
               disabledContentColor: theme.color(content),
             }
+          : {contentColor: theme.color(content), disabledContentColor: theme.color(content)}
       }
+      contentPadding={icon ? (text ? TEXT_WITH_ICON_PADDING : WITH_ICON_PADDING) : undefined}
       enabled={!disabled}
       modifiers={modifiers}
       onClick={onPress}
     >
+      {icon ? <Icon color={content} name={icon} size="s20" /> : null}
+      {icon ? <ComposeSpacer modifiers={ICON_GAP} /> : null}
       <ComposeText
         color={theme.colorString(content)}
         style={{

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

@@ -1,15 +1,19 @@
-import {Button as SwiftUIButton} from '@expo/ui/swift-ui'
+import {Button as SwiftUIButton, Label as SwiftUILabel} from '@expo/ui/swift-ui'
 import {
   buttonStyle as buttonStyleModifier,
+  contentShape,
   controlSize as controlSizeModifier,
   disabled as disabledModifier,
   glassEffect as glassEffectModifier,
+  labelStyle,
+  shapes,
   tint as tintModifier,
 } from '@expo/ui/swift-ui/modifiers'
 import {useAccessibilityModifiers} from '@hzblj/kara-sx'
-import {type ColorToken, useAppTheme} from '@hzblj/kara-theme'
+import {type ColorToken, type Theme, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
+import {Icon} from '../icon'
 import {Text} from '../text'
 import {VStack} from '../v-stack'
 import type {ButtonComponent, ButtonProps, ButtonStyleName, ButtonVariant} from './button.types'
@@ -19,6 +23,7 @@ const STYLE_BY_VARIANT = {
   accent: 'borderedProminent',
   destructive: 'borderedProminent',
   glass: 'glass',
+  plain: 'borderless',
   secondary: 'bordered',
 } as const satisfies Record<ButtonVariant, ButtonStyleName>
 
@@ -26,14 +31,56 @@ const TINT_BY_VARIANT = {
   accent: 'fill.accent.primary',
   destructive: 'fill.destructive.primary',
   glass: undefined,
+  plain: undefined,
   secondary: undefined,
 } as const satisfies Record<ButtonVariant, ColorToken | undefined>
 
+/** Both, wherever the button sits: a toolbar or a menu would otherwise show the icon alone. */
+const TITLE_AND_ICON = [labelStyle('titleAndIcon')]
+
+/**
+ * `borderless` draws nothing around the label, so the label is the button: padding takes it to a 44pt tap target,
+ * and a rectangle content shape makes the whole of it (the padding, and the width `wide` gives it) take the tap,
+ * not only the glyphs.
+ */
+const TEXT_BUTTON_TARGET = {modifiers: [contentShape(shapes.rectangle())]}
+
+/**
+ * A prominent style (and tinted glass) is coloured by the tint, so a caller's own tint picks the label on it. A text
+ * style has nothing to fill, so there the tint is the label's own colour.
+ */
+const labelColor = ({
+  disabled,
+  filled,
+  textOnly,
+  theme,
+  tint,
+  tokens,
+}: {
+  disabled: boolean
+  filled: boolean
+  textOnly: boolean
+  theme: Theme
+  tint: ColorToken | undefined
+  tokens: {content: ColorToken}
+}): ColorToken => {
+  if (!tint || disabled) {
+    return tokens.content
+  }
+
+  if (filled) {
+    return contentOnTint(tint, theme)
+  }
+
+  return textOnly ? tint : tokens.content
+}
+
 export const Button: ButtonComponent = ({
   accessibilityHint,
   buttonStyle,
   controlSize = 'large',
   disabled = false,
+  icon,
   label,
   onPress,
   testID,
@@ -58,8 +105,10 @@ export const Button: ButtonComponent = ({
    */
   const glassTint = style === 'glass' && resolvedTint ? theme.color(resolvedTint) : undefined
   const filled = Boolean(glassTint) || style === 'borderedProminent' || style === 'glassProminent'
-  // 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 textOnly = style === 'borderless' || style === 'plain'
+  // Only the `plain` variant's own text button is padded out; another variant restyled `plain` keeps its layout.
+  const textButton = variant === 'plain' && textOnly
+  const content = labelColor({disabled, filled, textOnly, theme, tint, tokens})
 
   const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint})
 
@@ -85,12 +134,27 @@ export const Button: ButtonComponent = ({
     return list
   }, [accessibilityModifiers, controlSize, disabled, glassTint, resolvedTint, style, theme])
 
+  const text = (
+    <Text color={content} variant="body">
+      {label}
+    </Text>
+  )
+
   return (
     <SwiftUIButton modifiers={modifiers} onPress={onPress} testID={testID}>
-      <VStack align="center" py={glassTint ? 's16' : undefined} wide={wide}>
-        <Text color={content} variant="body">
-          {label}
-        </Text>
+      <VStack
+        align="center"
+        ios={textButton ? TEXT_BUTTON_TARGET : undefined}
+        py={glassTint ? 's16' : textButton ? 's12' : undefined}
+        wide={wide}
+      >
+        {icon ? (
+          <SwiftUILabel icon={<Icon color={content} name={icon} size="s20" />} modifiers={TITLE_AND_ICON}>
+            {text}
+          </SwiftUILabel>
+        ) : (
+          text
+        )}
       </VStack>
     </SwiftUIButton>
   )

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

@@ -1,7 +1,9 @@
 import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
-export type ButtonVariant = 'accent' | 'destructive' | 'glass' | 'secondary'
+import type {IconName} from '../icon'
+
+export type ButtonVariant = 'accent' | 'destructive' | 'glass' | 'plain' | 'secondary'
 
 /**
  * SwiftUI `ButtonStyle`. iOS only: Compose has no equivalent, so Android ignores it and keeps
@@ -22,19 +24,28 @@ export type ButtonStyleName =
  */
 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 on Android (outlined for `glass`, a `TextButton`
+ * for `plain`).
+ */
 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.
+   * `secondary`, `glass` for `glass`, `borderless` for `plain`. iOS only. Android ignores it.
    */
   buttonStyle?: ButtonStyleName
   /** 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
+  /**
+   * One of the app's icons, before the label and in the label's colour. iOS sets the two as a SwiftUI `Label`; Android
+   * puts the icon in the button's content row, as Material's buttons with an icon do. Screen readers read the label
+   * only.
+   */
+  icon?: IconName
   /** The button's text. */
   label: string
   /** Called when the button is pressed. */
@@ -44,10 +55,14 @@ 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). `plain` has no fill, so there it colours the label.
    */
   tint?: ColorToken
-  /** The look. `accent` by default. Material has no glass, so on Android `glass` is an outlined button. */
+  /**
+   * The look. `accent` by default. Material has no glass, so on Android `glass` is an outlined button. `plain` is a
+   * text button in the accent, with no fill or border, for a lesser action beside a prominent one ("Skip", "Forgot
+   * password?"): SwiftUI's `borderless` style, Material's `TextButton`.
+   */
   variant?: ButtonVariant
   /** Stretches the button to the full width it is offered. On by default. */
   wide?: boolean

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

@@ -1,5 +1,5 @@
 import {Checkbox as ComposeCheckbox, Row, Text} from '@expo/ui/jetpack-compose'
-import {clickable, fillMaxWidth} from '@expo/ui/jetpack-compose/modifiers'
+import {clickable, fillMaxWidth, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {spacing, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
@@ -14,17 +14,20 @@ const NOOP = () => undefined
  * gets a handler, so a disabled or read-only box keeps the touch target an enabled one has, and lines up with it;
  * `enabled` is what stops the input.
  */
-export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueChange, value}: CheckboxProps) => {
+export const Checkbox: CheckboxComponent = ({disabled = false, label, onValueChange, testID, value}: CheckboxProps) => {
   useHostGuard('Checkbox')
   const theme = useAppTheme()
   const rowModifiers = useMemo(
     () => (disabled || !onValueChange ? [fillMaxWidth()] : [fillMaxWidth(), clickable(() => onValueChange(!value))]),
     [disabled, onValueChange, value]
   )
+  // On the box, not the row: the box is its own toggleable node inside the row, and the one a test reads.
+  const controlModifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
   const control = (
     <ComposeCheckbox
       colors={{checkedColor: theme.color('fill.accent.primary'), checkmarkColor: theme.color('content.on.accent')}}
       enabled={!disabled}
+      modifiers={controlModifiers}
       onCheckedChange={onValueChange ?? NOOP}
       value={value}
     />