@hzblj/kara-components 0.16.0 → 0.18.0

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

package/src/atoms/list/list.android.tsx

@@ -1,8 +1,11 @@
 import {LazyColumn, PullToRefreshBox} from '@expo/ui/jetpack-compose'
+import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
 import {useSxModifiers} from '@hzblj/kara-sx'
-import {Children, Fragment, isValidElement} from 'react'
+import {spacing} from '@hzblj/kara-theme'
+import {Children, Fragment, isValidElement, useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import {useRefreshState} from '../../use-refresh-state'
+import {Card} from '../card'
 import {Divider} from '../divider'
 import type {ListComponent, ListProps} from './list.types'
 
@@ -15,12 +18,31 @@ const withSeparators = (children: ListProps['children']) =>
     </Fragment>
   ))
 
-export const List: ListComponent = ({children, onRefresh}: ListProps) => {
+/** The card's inset from the column's edges, as `Form` keeps its cards off the screen's. */
+const INSET = {bottom: spacing.s16, end: spacing.s16, start: spacing.s16, top: spacing.s16}
+
+/**
+ * `plain` is the column as it always was. `insetGrouped` sets the rows in one `Card`, the way `Form` draws a section,
+ * inset by the column's content padding: the card is a single item of the column, so its rows are composed together
+ * rather than as they scroll in. A long list that wants laziness stays `plain`.
+ */
+export const List: ListComponent = ({children, onRefresh, separators = true, testID, variant = 'plain'}: ListProps) => {
   useHostGuard('List')
-  const modifiers = useSxModifiers({wide: true})
+  const sxModifiers = useSxModifiers({wide: true})
+  // On the column, not the refresh box around it: the column is what scrolls.
+  const modifiers = useMemo(
+    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
+    [sxModifiers, testID]
+  )
   const {isRefreshing, refresh} = useRefreshState(onRefresh)
+  const rows = separators ? withSeparators(children) : children
+  const grouped = variant === 'insetGrouped'
 
-  const column = <LazyColumn modifiers={modifiers}>{withSeparators(children)}</LazyColumn>
+  const column = (
+    <LazyColumn contentPadding={grouped ? INSET : undefined} modifiers={modifiers}>
+      {grouped && Children.toArray(children).length > 0 ? <Card wide>{rows}</Card> : rows}
+    </LazyColumn>
+  )
 
   if (!onRefresh) {
     return column

package/src/atoms/list/list.ios.tsx

@@ -1,18 +1,33 @@
-import {List as SwiftUIList} from '@expo/ui/swift-ui'
-import {type ModifierConfig, refreshable} from '@expo/ui/swift-ui/modifiers'
+import {Group, List as SwiftUIList} from '@expo/ui/swift-ui'
+import {listRowSeparator, listStyle, type ModifierConfig, refreshable} from '@expo/ui/swift-ui/modifiers'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {ListComponent, ListProps} from './list.types'
 
-export const List: ListComponent = ({children, onRefresh, testID}: ListProps) => {
+/**
+ * `listRowSeparator` is a row's preference, not the list's: set on the `List` it reaches no row. A `Group` hands a
+ * modifier to each of its children, so the rows go in one, and each of them hides its own separator.
+ */
+const NO_SEPARATORS = [listRowSeparator('hidden')]
+
+export const List: ListComponent = ({
+  children,
+  onRefresh,
+  separators = true,
+  testID,
+  variant = 'insetGrouped',
+}: ListProps) => {
   useHostGuard('List')
 
-  const modifiers = useMemo<ModifierConfig[]>(() => (onRefresh ? [refreshable(onRefresh)] : []), [onRefresh])
+  const modifiers = useMemo<ModifierConfig[]>(
+    () => [listStyle(variant), ...(onRefresh ? [refreshable(onRefresh)] : [])],
+    [onRefresh, variant]
+  )
 
   return (
     <SwiftUIList modifiers={modifiers} testID={testID}>
-      {children}
+      {separators ? children : <Group modifiers={NO_SEPARATORS}>{children}</Group>}
     </SwiftUIList>
   )
 }

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

@@ -1,5 +1,8 @@
 import type {ReactNode} from 'react'
 
+/** How the rows are laid out: in a rounded card inset from the edges, or edge to edge. */
+export type ListVariant = 'insetGrouped' | 'plain'
+
 /**
  * A scrolling list: SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
  * a `Screen`, or an `Island` with `matchContents={false}` and a height. In an island that sizes itself to its content
@@ -17,8 +20,20 @@ export type ListProps = {
    * until the promise settles, so neither platform needs a `refreshing` flag kept in sync by hand.
    */
   onRefresh?: () => Promise<void>
-  /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
+  /**
+   * Draws a line between rows. On by default. Off, iOS hides SwiftUI's row separators and Android draws no `Divider`,
+   * for rows that carry their own spacing (cards, media).
+   */
+  separators?: boolean
+  /** Test identifier, forwarded to the native view. */
   testID?: string
+  /**
+   * The layout. Each platform's own list by default: `insetGrouped` on iOS, `plain` on Android. `insetGrouped` sets
+   * the rows in a rounded card inset from the edges (SwiftUI's `insetGrouped` list style; on Android a `Card` inside the
+   * column, the way `Form` draws its sections). `plain` runs the rows edge to edge (SwiftUI's `plain` style; Android's
+   * column as it is).
+   */
+  variant?: ListVariant
 }
 
 export type ListComponent = (props: ListProps) => ReactNode

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

@@ -1,6 +1,12 @@
 import {Picker as NativePicker} from '@expo/ui/community/picker'
-import {Picker as SwiftUIPicker, Text as SwiftUIText} from '@expo/ui/swift-ui'
-import {disabled as disabledModifier, foregroundStyle, pickerStyle, tag} from '@expo/ui/swift-ui/modifiers'
+import {Host, Picker as SwiftUIPicker, Text as SwiftUIText} from '@expo/ui/swift-ui'
+import {
+  disabled as disabledModifier,
+  foregroundStyle,
+  pickerStyle as pickerStyleModifier,
+  tag,
+  tint,
+} from '@expo/ui/swift-ui/modifiers'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useCallback, useMemo} from 'react'
 
@@ -8,30 +14,54 @@ import {useInsideHost} from '../../host-context'
 import type {PickerComponent, PickerProps} from './picker.types'
 
 /**
- * A SwiftUI wheel. On its own it is `@expo/ui`'s community picker, which brings a host of its own. Inside a `Screen` or
- * `Island` it is the same wheel rendered into that host instead (see `useInsideHost`): a host nested in the island's
- * stack is given no height there, and the wheel spills over the views around it.
+ * A SwiftUI picker: a wheel, or with `pickerStyle="menu"` a button with the selection that opens the options as a
+ * menu, in the accent. On its own the wheel is `@expo/ui`'s community picker, which brings a host of its own, and the
+ * menu sits in a host sized to its button on both axes, as the date picker's pill does, so it drops into a row the way
+ * a `Text` does. Inside a `Screen` or `Island` either renders into that host instead (see `useInsideHost`): a host
+ * nested in the island's stack is given no height there, and the wheel spills over the views around it.
  */
-export const Picker: PickerComponent = ({disabled = false, onValueChange, options, testID, value}: PickerProps) => {
+export const Picker: PickerComponent = ({
+  disabled = false,
+  onValueChange,
+  options,
+  pickerStyle = 'wheel',
+  testID,
+  value,
+}: PickerProps) => {
   const theme = useAppTheme()
   const insideHost = useInsideHost()
   const color = theme.colorString('content.primary')
+  const menu = pickerStyle === 'menu'
 
   const onChange = useCallback((next: string | number | null) => onValueChange?.(String(next)), [onValueChange])
-  const wheelModifiers = useMemo(
-    () => [pickerStyle('wheel'), ...(disabled ? [disabledModifier(true)] : [])],
-    [disabled]
+  const modifiers = useMemo(
+    () => [
+      pickerStyleModifier(pickerStyle),
+      ...(menu ? [tint(theme.color('fill.accent.primary'))] : []),
+      ...(disabled ? [disabledModifier(true)] : []),
+    ],
+    [disabled, menu, pickerStyle, theme]
+  )
+
+  const picker = (
+    <SwiftUIPicker modifiers={modifiers} onSelectionChange={onChange} selection={value} testID={testID}>
+      {options.map(option => (
+        <SwiftUIText key={option.value} modifiers={[tag(option.value), foregroundStyle(color)]}>
+          {option.label}
+        </SwiftUIText>
+      ))}
+    </SwiftUIPicker>
   )
 
   if (insideHost) {
+    return picker
+  }
+
+  if (menu) {
     return (
-      <SwiftUIPicker modifiers={wheelModifiers} onSelectionChange={onChange} selection={value} testID={testID}>
-        {options.map(option => (
-          <SwiftUIText key={option.value} modifiers={[tag(option.value), foregroundStyle(color)]}>
-            {option.label}
-          </SwiftUIText>
-        ))}
-      </SwiftUIPicker>
+      <Host colorScheme={theme.dark ? 'dark' : 'light'} matchContents>
+        {picker}
+      </Host>
     )
   }
 

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

@@ -8,10 +8,13 @@ export type PickerOption = {
   value: string
 }
 
+/** How SwiftUI shows the picker: a wheel, or a button that opens the options as a menu. */
+export type PickerStyleName = 'menu' | 'wheel'
+
 /**
- * A single choice from a list: a SwiftUI wheel picker on iOS, Material's exposed dropdown on Android. It brings its
- * own host, so it renders outside `Screen` and `Island` as well. Inside one it renders into that host instead, so it
- * can share a stack with other native views.
+ * A single choice from a list: a SwiftUI picker on iOS (a wheel, or a menu with `pickerStyle`), Material's exposed
+ * dropdown on Android. It brings its own host, so it renders outside `Screen` and `Island` as well. Inside one it
+ * renders into that host instead, so it can share a stack with other native views.
  */
 export type PickerProps = {
   /** Stops the user changing the selection, and dims the picker. */
@@ -20,6 +23,12 @@ export type PickerProps = {
   onValueChange?: (value: string) => void
   /** The choices, in order. */
   options: PickerOption[]
+  /**
+   * SwiftUI's picker style. `wheel` by default: the options on a wheel, always in view. `menu` is a button with the
+   * selection, in the accent, that opens the options as a menu: what a screen with more than one picker, or a picker
+   * in a row, wants. iOS only. Android ignores it: its exposed dropdown is a menu already.
+   */
+  pickerStyle?: PickerStyleName
   /**
    * Android: the dropdown field's test tag. iOS: the wheel's, inside a `Screen` or `Island` only; on its own,
    * `@expo/ui`'s wheel picker drops it.

package/src/atoms/progress/progress.android.tsx

@@ -1,19 +1,45 @@
 import {CircularProgressIndicator, LinearProgressIndicator} 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 {useAppTheme, withOpacity} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
 import type {ProgressComponent, ProgressProps} from './progress.types'
 
-export const Progress: ProgressComponent = ({accessibilityLabel, circular = false, value}: ProgressProps) => {
+/**
+ * Material draws the track in the seeded scheme's `secondaryContainer`, a pale accent: under a red or a green bar it
+ * would read as a second colour. Any other colour gets its own faded track instead, the way the accent's is pale; the
+ * accent keeps Material's. An indeterminate ring has no track in Material, so it is left without one.
+ */
+export const Progress: ProgressComponent = ({
+  accessibilityLabel,
+  circular = false,
+  color = 'fill.accent.primary',
+  testID,
+  value,
+}: ProgressProps) => {
   useHostGuard('Progress')
   const theme = useAppTheme()
-  const color = theme.color('fill.accent.primary')
-  const modifiers = useAccessibilityModifiers({accessibilityLabel})
+  const indicator = theme.color(color)
+  // The website reads the default above from the source, so it stays a literal rather than a shared constant.
+  const track = color === 'fill.accent.primary' ? undefined : withOpacity(String(indicator), 'o20')
+  const accessibilityModifiers = useAccessibilityModifiers({accessibilityLabel})
+  const modifiers = useMemo(
+    () => (testID ? [testIdModifier(testID), ...accessibilityModifiers] : accessibilityModifiers),
+    [accessibilityModifiers, testID]
+  )
 
   if (circular) {
-    return <CircularProgressIndicator color={color} modifiers={modifiers} progress={value} />
+    return (
+      <CircularProgressIndicator
+        color={indicator}
+        modifiers={modifiers}
+        progress={value}
+        trackColor={value === undefined ? undefined : track}
+      />
+    )
   }
 
-  return <LinearProgressIndicator color={color} modifiers={modifiers} progress={value} />
+  return <LinearProgressIndicator color={indicator} modifiers={modifiers} progress={value} trackColor={track} />
 }

package/src/atoms/progress/progress.ios.tsx

@@ -7,7 +7,13 @@ import {useMemo} from 'react'
 import {useHostGuard} from '../../host-context'
 import type {ProgressComponent, ProgressProps} from './progress.types'
 
-export const Progress: ProgressComponent = ({accessibilityLabel, circular = false, value}: ProgressProps) => {
+export const Progress: ProgressComponent = ({
+  accessibilityLabel,
+  circular = false,
+  color = 'fill.accent.primary',
+  testID,
+  value,
+}: ProgressProps) => {
   useHostGuard('Progress')
   const theme = useAppTheme()
   const accessibilityModifiers = useAccessibilityModifiers({accessibilityLabel})
@@ -16,16 +22,16 @@ export const Progress: ProgressComponent = ({accessibilityLabel, circular = fals
   const modifiers = useMemo(
     () => [
       ring ? gaugeStyle('circularCapacity') : progressViewStyle(circular ? 'circular' : 'linear'),
-      tint(theme.color('fill.accent.primary')),
+      tint(theme.color(color)),
       ...accessibilityModifiers,
     ],
-    [accessibilityModifiers, circular, ring, theme]
+    [accessibilityModifiers, circular, color, ring, theme]
   )
 
   // SwiftUI's circular `ProgressView` ignores its value on iOS and spins; a ring that fills is a capacity `Gauge`.
   return ring ? (
-    <Gauge modifiers={modifiers} value={value} />
+    <Gauge modifiers={modifiers} testID={testID} value={value} />
   ) : (
-    <ProgressView modifiers={modifiers} value={value ?? null} />
+    <ProgressView modifiers={modifiers} testID={testID} value={value ?? null} />
   )
 }

package/src/atoms/progress/progress.types.ts

@@ -1,14 +1,25 @@
+import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 /**
- * A progress bar or ring, tinted `fill.accent.primary`: SwiftUI `ProgressView` (a capacity `Gauge` for a ring with a
- * value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and `CircularProgressIndicator`.
+ * A progress bar or ring, tinted `fill.accent.primary` unless `color` names another: SwiftUI `ProgressView` (a capacity
+ * `Gauge` for a ring with a value, which `ProgressView` cannot draw on iOS) / Compose's `LinearProgressIndicator` and
+ * `CircularProgressIndicator`.
  */
 export type ProgressProps = {
   /** What is in progress, for VoiceOver and TalkBack: "Uploading". They read how far along it is themselves. */
   accessibilityLabel?: string
   /** A circular indicator instead of a bar. Off by default. */
   circular?: boolean
+  /**
+   * Its colour: `fill.destructive.primary` for storage nearly full, `fill.success.primary` for a goal reached.
+   * `fill.accent.primary` by default. iOS tints the bar or ring with it. Android draws the indicator in it and, for any
+   * colour but the accent, the track in the same colour faded (Material's own track stays under the accent, and an
+   * indeterminate ring has none).
+   */
+  color?: ColorToken
+  /** Test identifier, forwarded to the native view. */
+  testID?: string
   /** Between `0` and `1`. Leave it unset for an indeterminate indicator. */
   value?: number
 }