@hzblj/kara-components 0.17.0 → 0.18.0

package/src/atoms/date-picker/date-picker.ios.tsx

@@ -1,5 +1,10 @@
 import {Host, DatePicker as SwiftUIDatePicker} from '@expo/ui/swift-ui'
-import {datePickerStyle, labelsHidden, tint} from '@expo/ui/swift-ui/modifiers'
+import {
+  datePickerStyle as datePickerStyleModifier,
+  disabled as disabledModifier,
+  labelsHidden,
+  tint,
+} from '@expo/ui/swift-ui/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
@@ -13,13 +18,15 @@ const COMPONENTS = {
 } as const satisfies Record<DatePickerMode, ('date' | 'hourAndMinute')[]>
 
 /**
- * The system's compact date picker: the value in a pill, and a tap on it opens the calendar popover UIKit owns. Its own
- * host, sized to the pill on both axes — a host that took the width it was given would lay the pill out against the
- * far edge of it, or past its container's — so it drops into a row the way a `Text` does. The label is the caller's,
- * beside it; the calendar is in the accent. Inside a `Screen` or `Island` it renders into that host instead (see
- * `useInsideHost`).
+ * The system's date picker, in the accent. `compact` by default: the value in a pill, and a tap on it opens the
+ * calendar popover UIKit owns. `graphical` is that calendar in place, `wheel` the value on wheels. Its own host, sized
+ * to the picker on both axes (a host that took the width it was given would lay the pill out against the far edge of
+ * it, or past its container's), so it drops into a row the way a `Text` does. The label is the caller's, beside it.
+ * Inside a `Screen` or `Island` it renders into that host instead (see `useInsideHost`).
  */
 export const DatePicker: DatePickerComponent = ({
+  datePickerStyle = 'compact',
+  disabled = false,
   max,
   min,
   mode = 'date',
@@ -31,8 +38,13 @@ export const DatePicker: DatePickerComponent = ({
   const insideHost = useInsideHost()
 
   const modifiers = useMemo(
-    () => [datePickerStyle('compact'), labelsHidden(), tint(theme.color('fill.accent.primary'))],
-    [theme]
+    () => [
+      datePickerStyleModifier(datePickerStyle),
+      labelsHidden(),
+      tint(theme.color('fill.accent.primary')),
+      ...(disabled ? [disabledModifier(true)] : []),
+    ],
+    [datePickerStyle, disabled, theme]
   )
 
   const picker = (

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

@@ -2,24 +2,48 @@ import type {ReactNode} from 'react'
 
 export type DatePickerMode = 'date' | 'datetime' | 'time'
 
+/** How SwiftUI shows the picker: a pill that opens the calendar, the calendar in place, or wheels. */
+export type DatePickerStyleName = 'compact' | 'graphical' | 'wheel'
+
 /**
- * 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`. Inside a `Screen` or `Island` it joins that host instead, beside a native `Text` label.
+ * A date or time picker: SwiftUI's `DatePicker` on iOS (a pill by default, a calendar or wheels with
+ * `datePickerStyle`), a field that opens Material's picker dialog on a tap on Android, or Material's calendar in place
+ * with `datePickerStyle="graphical"`. 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`. Inside a `Screen` or `Island` it joins that host instead, beside a
+ * native `Text` label.
  */
 export type DatePickerProps = {
+  /**
+   * SwiftUI's date picker style. `compact` by default: the value in a pill, which opens the calendar in a popover.
+   * `graphical` is the calendar in place, a month at a time, with the time under it in `datetime` mode: what a screen
+   * built around picking a day wants. `wheel` puts the value on wheels. Android shows Material's calendar in place for
+   * `graphical` in `date` and `datetime` modes (without its title and headline); otherwise it keeps its field and
+   * dialog, since Material has no wheel.
+   */
+  datePickerStyle?: DatePickerStyleName
+  /**
+   * Stops the user changing the date, and dims the picker. Material's calendar has no disabled state of its own, so a
+   * `graphical` picker on Android is dimmed and offers only the selected day.
+   */
+  disabled?: boolean
   /** The latest date that can be picked. Android ignores it in `time` mode. */
   max?: Date
   /** The earliest date that can be picked. Android ignores it in `time` mode. */
   min?: Date
   /**
-   * What it picks. `date` by default. Android has no combined dialog, so there `datetime` picks the date and keeps
-   * `value`'s time of day.
+   * What it picks. `date` by default. Android has no combined dialog or calendar, so there `datetime` picks the date
+   * and keeps `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 or a day in the calendar
+   * is tapped.
+   */
   onValueChange?: (date: Date) => void
-  /** Test identifier, on the native picker on iOS and on the tappable field on Android. */
+  /**
+   * Test identifier, on the native picker on iOS and on Android's calendar, and on the tappable field elsewhere on
+   * Android.
+   */
   testID?: string
   /** The selected date. Controlled: update it from `onValueChange`. */
   value: Date

package/src/atoms/divider/divider.android.tsx

@@ -1,12 +1,23 @@
-import {HorizontalDivider} from '@expo/ui/jetpack-compose'
+import {HorizontalDivider, VerticalDivider} 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 {DividerComponent, DividerProps} from './divider.types'
 
-export const Divider: DividerComponent = ({color = 'border.tertiary'}: DividerProps) => {
+/**
+ * Compose's dividers. Unlike SwiftUI's, a Compose divider does not turn with its stack, so `axis` picks the one:
+ * `VerticalDivider` fills the height of the `Row` around it.
+ */
+export const Divider: DividerComponent = ({axis = 'horizontal', color = 'border.tertiary', testID}: DividerProps) => {
   useHostGuard('Divider')
   const theme = useAppTheme()
+  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
 
-  return <HorizontalDivider color={theme.color(color)} />
+  return axis === 'vertical' ? (
+    <VerticalDivider color={theme.color(color)} modifiers={modifiers} />
+  ) : (
+    <HorizontalDivider color={theme.color(color)} modifiers={modifiers} />
+  )
 }

package/src/atoms/divider/divider.ios.tsx

@@ -6,6 +6,10 @@ import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {DividerComponent, DividerProps} from './divider.types'
 
+/**
+ * SwiftUI's divider, which turns with its stack: vertical in an `HStack`, horizontal anywhere else. So `axis`, which
+ * Android needs to pick its divider, has nothing to do here.
+ */
 export const Divider: DividerComponent = ({color = 'border.tertiary', testID}: DividerProps) => {
   useHostGuard('Divider')
   const theme = useAppTheme()

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

@@ -1,11 +1,23 @@
 import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
-/** A horizontal hairline: SwiftUI `Divider` / Compose `HorizontalDivider`. */
+/** Which way the line runs. */
+export type DividerAxis = 'horizontal' | 'vertical'
+
+/**
+ * A hairline between views: SwiftUI `Divider` / Compose `HorizontalDivider`, or `VerticalDivider` with
+ * `axis="vertical"`.
+ */
 export type DividerProps = {
+  /**
+   * Which way the line runs. `horizontal` by default: across a `VStack`. `vertical` stands it up between the children
+   * of an `HStack`, as tall as the stack, so give the stack a height (`h`). iOS ignores it: SwiftUI's divider turns by
+   * itself, vertical in an `HStack` and horizontal anywhere else. Set it anyway, so Android draws the same.
+   */
+  axis?: DividerAxis
   /** 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. */
   testID?: string
 }
 

package/src/atoms/fab/fab.android.tsx

@@ -1,23 +1,73 @@
-import {FloatingActionButton} from '@expo/ui/jetpack-compose'
+import {
+  ExtendedFloatingActionButton,
+  FloatingActionButton,
+  LargeFloatingActionButton,
+  SmallFloatingActionButton,
+} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAccessibilityModifiers} from '@hzblj/kara-sx'
-import {useAppTheme} from '@hzblj/kara-theme'
+import {type SpaceSize, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import {Icon} from '../icon'
-import type {FabComponent, FabProps} from './fab.types'
+import {Text} from '../text'
+import type {FabComponent, FabProps, FabSize} from './fab.types'
 
-export const Fab: FabComponent = ({accessibilityHint, accessibilityLabel, name, onPress}: FabProps) => {
+/** Material's three FABs, and the icon each draws (`FloatingActionButtonDefaults.LargeIconSize` is 36dp). */
+const SIZES = {
+  large: {icon: 's36', Material: LargeFloatingActionButton},
+  regular: {icon: 's24', Material: FloatingActionButton},
+  small: {icon: 's24', Material: SmallFloatingActionButton},
+} as const satisfies Record<FabSize, {Material: unknown; icon: SpaceSize}>
+
+export const Fab: FabComponent = ({
+  accessibilityHint,
+  accessibilityLabel,
+  label,
+  name,
+  onPress,
+  size = 'regular',
+  testID,
+}: FabProps) => {
   useHostGuard('Fab')
 
   const theme = useAppTheme()
-  const modifiers = useAccessibilityModifiers({accessibilityHint}, accessibilityHint !== undefined)
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint}, accessibilityHint !== undefined)
+  const modifiers = useMemo(
+    () => (testID ? [testIdModifier(testID), ...accessibilityModifiers] : accessibilityModifiers),
+    [accessibilityModifiers, testID]
+  )
+  const containerColor = theme.color('fill.accent.primary')
+
+  /*
+   * `@expo/ui`'s FABs are slot-based: content outside `.Icon` (and the extended one's `.Text`) is not composed at all.
+   * The label rides on the icon, as for every FAB, and the text beside it is hidden from TalkBack so the button is not
+   * read twice; a label on the FAB itself would clear the click inside it, which Material's FAB composes after our
+   * modifiers.
+   */
+  if (label) {
+    return (
+      <ExtendedFloatingActionButton containerColor={containerColor} modifiers={modifiers} onClick={onPress}>
+        <ExtendedFloatingActionButton.Icon>
+          <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} />
+        </ExtendedFloatingActionButton.Icon>
+        <ExtendedFloatingActionButton.Text>
+          <Text accessibilityHidden color="content.on.accent" variant="body">
+            {label}
+          </Text>
+        </ExtendedFloatingActionButton.Text>
+      </ExtendedFloatingActionButton>
+    )
+  }
+
+  const {icon, Material} = SIZES[size]
 
   return (
-    <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 accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} />
-      </FloatingActionButton.Icon>
-    </FloatingActionButton>
+    <Material containerColor={containerColor} modifiers={modifiers} onClick={onPress}>
+      <Material.Icon>
+        <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} size={icon} />
+      </Material.Icon>
+    </Material>
   )
 }

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

@@ -1,23 +1,49 @@
 import {Button} from '@expo/ui/swift-ui'
 import {buttonStyle} from '@expo/ui/swift-ui/modifiers'
-import {useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
+import {type ResponsiveSx, useAccessibilityModifiers, useSxModifiers} from '@hzblj/kara-sx'
+import type {SpaceSize} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
+import {HStack} from '../h-stack'
 import {Icon} from '../icon'
-import type {FabComponent, FabProps} from './fab.types'
+import {Text} from '../text'
+import type {FabComponent, FabProps, FabSize} from './fab.types'
 
-export const Fab: FabComponent = ({accessibilityHint, accessibilityLabel, name, onPress, testID}: FabProps) => {
+/** Material's sizes, in points: the circle across and the icon in it. */
+const SIZES = {
+  large: {icon: 's36', side: 96},
+  regular: {icon: 's24', side: 56},
+  small: {icon: 's24', side: 40},
+} as const satisfies Record<FabSize, {icon: SpaceSize; side: number}>
+
+const SURFACE = {bg: 'fill.accent.primary', borderRadius: 'full', shadow: 'btn.accent'} as const satisfies ResponsiveSx
+
+/**
+ * Material's extended FAB in kara's iOS language: the regular FAB's height, accent and shadow, drawn as a capsule (the
+ * shape a round button takes once it has words), 16 before the icon and 20 after the text, as Material pads it.
+ */
+const EXTENDED = {...SURFACE, h: SIZES.regular.side, pl: 's16', pr: 's20'} as const satisfies ResponsiveSx
+
+export const Fab: FabComponent = ({
+  accessibilityHint,
+  accessibilityLabel,
+  label,
+  name,
+  onPress,
+  size = 'regular',
+  testID,
+}: FabProps) => {
   useHostGuard('Fab')
-  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint})
+  const extended = Boolean(label)
+  const {icon, side} = SIZES[size]
+
+  // An icon alone carries the label; beside text, the button does, in place of what the text would say.
+  const accessibilityModifiers = useAccessibilityModifiers(
+    extended ? {accessibilityHint, accessibilityLabel} : {accessibilityHint}
+  )
 
-  const sxModifiers = useSxModifiers({
-    bg: 'fill.accent.primary',
-    borderRadius: 'full',
-    h: 56,
-    p: 's16',
-    shadow: 'btn.accent',
-    w: 56,
-  })
+  // The frame centres the icon, so one circle serves every size: `regular` is the 56pt one it always was.
+  const sxModifiers = useSxModifiers(extended ? EXTENDED : {...SURFACE, h: side, w: side}, 'center')
   const modifiers = useMemo(
     () => [buttonStyle('plain'), ...sxModifiers, ...accessibilityModifiers],
     [accessibilityModifiers, sxModifiers]
@@ -25,7 +51,16 @@ export const Fab: FabComponent = ({accessibilityHint, accessibilityLabel, name,
 
   return (
     <Button modifiers={modifiers} onPress={onPress} testID={testID}>
-      <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} />
+      {extended ? (
+        <HStack align="center" spacing="s12">
+          <Icon color="content.on.accent" name={name} />
+          <Text color="content.on.accent" variant="body">
+            {label}
+          </Text>
+        </HStack>
+      ) : (
+        <Icon accessibilityLabel={accessibilityLabel} color="content.on.accent" name={name} size={icon} />
+      )}
     </Button>
   )
 }

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

@@ -2,23 +2,41 @@ import type {ReactNode} from 'react'
 
 import type {IconName} from '../icon'
 
+/** Material's three floating action buttons: 40, 56 and 96 across. */
+export type FabSize = 'large' | 'regular' | 'small'
+
 /**
- * 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.
+ * A floating action button: Material's `FloatingActionButton` on Android, an accent circle (a plain SwiftUI `Button`)
+ * on iOS. With a `label` it is the extended one, the icon and the text side by side: Material's
+ * `ExtendedFloatingActionButton`, an accent capsule on iOS. It renders inline; pinning it to a corner is up to the
+ * screen.
  */
 export type FabProps = {
   /**
    * 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.
+   * favourites". Required for that reason. With a `label` it is still what they say, in place of the label, so give
+   * it the label's words (or words that start with them), and Voice Control finds the button by what it shows.
    */
   accessibilityLabel: string
   /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
   accessibilityHint?: string
+  /**
+   * Text beside the icon, which makes it an extended FAB: "Compose", "New post". For a screen whose main action needs
+   * its words. Material's `ExtendedFloatingActionButton` on Android; on iOS the same accent, 56pt tall, as a capsule.
+   */
+  label?: 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. */
+  /**
+   * `regular` by default, 56 across. `small` is 40, for a secondary action beside a regular one; `large` is 96, with a
+   * 36 icon, for a screen built around one action. Material's `SmallFloatingActionButton` and
+   * `LargeFloatingActionButton` on Android, the same sizes of circle on iOS. A FAB with a `label` has one size and
+   * ignores it.
+   */
+  size?: FabSize
+  /** Test identifier, forwarded to the native view. */
   testID?: string
 }
 

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

@@ -1,28 +1,78 @@
-import {IconButton as ComposeIconButton} from '@expo/ui/jetpack-compose'
+import {
+  IconButton as ComposeIconButton,
+  FilledIconButton,
+  FilledTonalIconButton,
+  OutlinedIconButton,
+} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useAccessibilityModifiers} from '@hzblj/kara-sx'
+import {type ColorToken, useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
+import {buttonTokens, contentOnTint} from '../button/button-tokens'
 import {Icon} from '../icon'
-import type {IconButtonComponent, IconButtonProps} from './icon-button.types'
+import type {IconButtonComponent, IconButtonProps, IconButtonVariant} from './icon-button.types'
+
+/** Material has no glass: `glass` is the tonal button, a contained one that still reads over a photo or a map. */
+const MATERIAL_BY_VARIANT = {
+  filled: FilledIconButton,
+  glass: FilledTonalIconButton,
+  outlined: OutlinedIconButton,
+  plain: ComposeIconButton,
+  tonal: FilledTonalIconButton,
+} as const satisfies Record<IconButtonVariant, unknown>
+
+/** Which `Button` variant's tokens fill the container: the same accent and secondary fills a `Button` draws. */
+const FILL_BY_VARIANT = {
+  filled: 'accent',
+  glass: 'secondary',
+  outlined: undefined,
+  plain: undefined,
+  tonal: 'secondary',
+} as const satisfies Record<IconButtonVariant, 'accent' | 'secondary' | undefined>
 
 export const IconButton: IconButtonComponent = ({
   accessibilityHint,
   accessibilityLabel,
+  color,
   disabled = false,
   name,
   onPress,
+  testID,
+  variant = 'plain',
 }: IconButtonProps) => {
   useHostGuard('IconButton')
+  const theme = useAppTheme()
   // 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)
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint}, accessibilityHint !== undefined)
+  const modifiers = useMemo(
+    () => (testID ? [testIdModifier(testID), ...accessibilityModifiers] : accessibilityModifiers),
+    [accessibilityModifiers, testID]
+  )
+  const MaterialIconButton = MATERIAL_BY_VARIANT[variant]
+  const fillVariant = FILL_BY_VARIANT[variant]
+  const tokens = fillVariant ? buttonTokens(fillVariant, disabled, theme) : undefined
+
+  // `filled` takes the colour as its fill and picks the icon's on it, as a tinted `Button` does; the rest colour the icon.
+  const filled = variant === 'filled'
+  const fill = filled && color && !disabled ? color : tokens?.fill
+  let iconColor: ColorToken = color ?? 'content.primary'
+
+  if (disabled) {
+    iconColor = 'btn.content.disabled'
+  } else if (filled) {
+    iconColor = color ? contentOnTint(color, theme) : 'content.on.accent'
+  }
 
   return (
-    <ComposeIconButton enabled={!disabled} modifiers={modifiers} onClick={onPress}>
-      <Icon
-        accessibilityLabel={accessibilityLabel}
-        color={disabled ? 'btn.content.disabled' : 'content.primary'}
-        name={name}
-      />
-    </ComposeIconButton>
+    <MaterialIconButton
+      colors={fill ? {containerColor: theme.color(fill), disabledContainerColor: theme.color(fill)} : undefined}
+      enabled={!disabled}
+      modifiers={modifiers}
+      onClick={onPress}
+    >
+      <Icon accessibilityLabel={accessibilityLabel} color={iconColor} name={name} />
+    </MaterialIconButton>
   )
 }

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

@@ -1,46 +1,115 @@
 import {Button} from '@expo/ui/swift-ui'
-import {buttonStyle, contentShape, disabled as disabledModifier, shapes} from '@expo/ui/swift-ui/modifiers'
+import {
+  buttonBorderShape,
+  buttonStyle,
+  contentShape,
+  disabled as disabledModifier,
+  shapes,
+  tint as tintModifier,
+} from '@expo/ui/swift-ui/modifiers'
+import {isLiquidGlassAvailable} from '@hzblj/kara-native'
 import {useAccessibilityModifiers} from '@hzblj/kara-sx'
+import {type ColorToken, useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
+import type {ButtonStyleName} from '../button/button.types'
+import {contentOnTint} from '../button/button-tokens'
 import {Icon} from '../icon'
 import {ZStack} from '../z-stack'
-import type {IconButtonComponent, IconButtonProps} from './icon-button.types'
+import type {IconButtonComponent, IconButtonProps, IconButtonVariant} from './icon-button.types'
 
 /** Apple's least tap target. Android's `IconButton` is Material's 48dp; this is the same idea in points. */
 const TARGET = 44
 
+/** Material's 40dp container, the ring an `outlined` button draws inside its tap target. */
+const RING = 40
+
 /** The whole square takes the tap, not only the glyph's own pixels. */
 const WHOLE_TARGET = {modifiers: [contentShape(shapes.circle())]}
 
+/**
+ * The SwiftUI style behind each variant. `outlined` has none (SwiftUI draws no ring around a button), so it is a plain
+ * button whose label draws the ring.
+ */
+const STYLE_BY_VARIANT = {
+  filled: 'borderedProminent',
+  glass: 'glass',
+  outlined: 'plain',
+  plain: 'plain',
+  tonal: 'bordered',
+} as const satisfies Record<IconButtonVariant, ButtonStyleName>
+
 export const IconButton: IconButtonComponent = ({
   accessibilityHint,
   accessibilityLabel,
+  color,
   disabled = false,
   name,
   onPress,
   testID,
+  variant = 'plain',
 }: IconButtonProps) => {
   useHostGuard('IconButton')
+  const theme = useAppTheme()
   const accessibilityModifiers = useAccessibilityModifiers({accessibilityHint})
+  // Below iOS 26 `@expo/ui` turns `.glass` into `.automatic`, a bare icon; the tonal circle is what Android draws too.
+  const style = variant === 'glass' && !isLiquidGlassAvailable() ? 'bordered' : STYLE_BY_VARIANT[variant]
+  const bezel = style !== 'plain'
+
+  /**
+   * `filled` takes the colour as its fill, and the icon a colour that reads on it. `tonal` passes it as the tint too,
+   * which SwiftUI's bordered style draws its pale circle in. SwiftUI dims a disabled button's label itself, and greys a
+   * prominent one's fill, so a disabled filled icon goes back to the primary content colour rather than white on grey.
+   */
+  const fill: ColorToken | undefined = variant === 'filled' ? (color ?? 'fill.accent.primary') : undefined
+  const tint = fill ?? (variant === 'tonal' ? color : undefined)
+  const iconColor: ColorToken = fill
+    ? disabled
+      ? 'content.primary'
+      : color
+        ? contentOnTint(color, theme)
+        : 'content.on.accent'
+    : (color ?? 'content.primary')
 
   const modifiers = useMemo(() => {
-    const list = [buttonStyle('plain'), ...accessibilityModifiers]
+    const list = [buttonStyle(style)]
+
+    if (bezel) {
+      list.push(buttonBorderShape('circle'))
+    }
+
+    if (tint) {
+      list.push(tintModifier(theme.color(tint)))
+    }
+
+    list.push(...accessibilityModifiers)
 
     if (disabled) {
       list.push(disabledModifier(true))
     }
 
     return list
-  }, [accessibilityModifiers, disabled])
+  }, [accessibilityModifiers, bezel, disabled, style, theme, tint])
+
+  // A bezel style sizes its circle around the icon itself; a plain button's label is the whole target.
+  const icon = <Icon accessibilityLabel={accessibilityLabel} color={iconColor} name={name} />
 
   return (
     <Button modifiers={modifiers} onPress={onPress} testID={testID}>
-      <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>
+      {bezel ? (
+        icon
+      ) : (
+        <ZStack h={TARGET} ios={WHOLE_TARGET} w={TARGET}>
+          {variant === 'outlined' ? (
+            <ZStack borderColor="border.secondary.base" borderRadius="full" borderWidth={1} h={RING} w={RING}>
+              {icon}
+            </ZStack>
+          ) : (
+            icon
+          )}
+        </ZStack>
+      )}
     </Button>
   )
 }

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

@@ -1,11 +1,18 @@
+import type {ColorToken} from '@hzblj/kara-theme'
 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. 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.
+ * How much the button stands out: just the icon (`plain`), on a fill in the accent (`filled`), on a muted fill
+ * (`tonal`), in a ring (`outlined`) or on Liquid Glass (`glass`).
+ */
+export type IconButtonVariant = 'filled' | 'glass' | 'outlined' | 'plain' | 'tonal'
+
+/**
+ * A button that is just an icon: a SwiftUI `Button` on iOS, one of Material's icon buttons on Android. A `plain` one
+ * 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; the other variants draw a circle around the icon.
  */
 export type IconButtonProps = {
   /**
@@ -15,14 +22,27 @@ export type IconButtonProps = {
   accessibilityLabel: string
   /** What pressing it does, when the label alone does not say. See `AccessibilityProps`. */
   accessibilityHint?: string
+  /**
+   * The icon's colour, `content.primary` by default. On `filled` it is the fill instead (`fill.accent.primary` by
+   * default) and the icon picks a colour that reads on it, as a `Button`'s `tint` does on a prominent style. On iOS a
+   * `tonal` button's circle takes a pale shade of it too.
+   */
+  color?: ColorToken
   /** 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. */
   testID?: string
+  /**
+   * The look. `plain` by default. iOS draws the others as SwiftUI button styles in a circle: `borderedProminent` for
+   * `filled`, `bordered` for `tonal`, `glass` for `glass` (`bordered` below iOS 26), and `outlined` as a plain button
+   * in a hairline ring. Android draws Material's `IconButton`, `FilledIconButton`, `FilledTonalIconButton` and
+   * `OutlinedIconButton`; Material has no glass, so there `glass` is the tonal one.
+   */
+  variant?: IconButtonVariant
 }
 
 export type IconButtonComponent = (props: IconButtonProps) => ReactNode