@hzblj/kara-components 0.7.0 → 0.9.0

package/lib/typescript/atoms/text-field/text-field.types.d.ts

@@ -8,8 +8,12 @@ export type TextFieldProps = {
     defaultValue?: string;
     /** Stops editing and dims the field. On iOS it outranks `error`. */
     disabled?: boolean;
-    /** Marks the field invalid: a destructive outline and label. */
-    error?: boolean;
+    /**
+     * Marks the field invalid: a destructive outline and label. A message is shown under the field as well — on Android
+     * as Material's supporting text, beside its error icon — so the error never rests on colour alone; Material's error
+     * colour is a pale red in dark mode. `true` marks it without a message.
+     */
+    error?: boolean | string;
     /** Shown above the field, in `labelMedium`. */
     label?: string;
     /** Wraps the text and grows the field to fit it. iOS ignores it when `secure`. */

package/lib/typescript/molecules/scroll-edge-container/scroll-edge-container.types.d.ts

@@ -3,8 +3,10 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ReactElement, ReactNode } from 'react';
 export type { ScrollEdgeEffect, ScrollEdgeScrollableProps } from '@hzblj/kara-native/swift-ui';
 /**
- * Bars over one React Native scroll view, with the iOS 26 scroll edge effect under them — the system's progressive
- * blur where content scrolls past a bar. The React Native tier: it needs no host.
+ * Bars over one React Native scroll view, with each platform's scroll edge under them — on iOS 26 the system's
+ * progressive blur where content scrolls past a bar; on Android a Material top app bar's behaviour, the bars stacked
+ * around the scroll view and filling with `surface.secondary` once content scrolls under them. The React Native tier:
+ * it needs no host.
  *
  * A screen-level container: wrap the screen's scroll view with it. Mounted inside a cell of a virtualized list on iOS
  * it draws only its bottom bar — the hosted scroll view and the top bar stay blank.
@@ -15,7 +17,7 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
      * content begins below the top bar and scrolls under it. On by default.
      */
     automaticInsets?: boolean;
-    /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, where it wants a background. */
+    /** Laid over the scroll view's bottom edge on iOS; stacked below it on Android, filled while content continues below. */
     bottomBar?: ReactNode;
     /** Exactly one React Native scroll view — `RnScrollView`, `RnFlatList`, `RnSectionList`. */
     children: ReactElement<ScrollEdgeScrollableProps>;
@@ -23,7 +25,7 @@ export type ScrollEdgeContainerProps = ResponsiveViewSx & {
     effect?: ScrollEdgeEffect;
     /** Test identifier, forwarded to the container view. */
     testID?: string;
-    /** Laid over the scroll view's top edge on iOS; stacked above it on Android, where it wants a background. */
+    /** Laid over the scroll view's top edge on iOS; stacked above it on Android, filled once content scrolls under it. */
     topBar?: ReactNode;
 };
 export type ScrollEdgeContainerComponent = (props: ScrollEdgeContainerProps) => ReactNode;

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

@@ -1,2 +1,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.
+ */
 export declare const Stepper: StepperComponent;

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

@@ -4,10 +4,7 @@ import type { ReactNode } from 'react';
  * two icon buttons in a row. A native atom — it renders inside `<Screen>` or `<Island>`.
  */
 export type StepperProps = {
-    /**
-     * The leading text. iOS shows only the label, not the value — put the value in it if it should be seen. Android
-     * shows the value between its buttons.
-     */
+    /** 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`. */
     max?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzblj/kara-components",
-  "version": "0.7.0",
+  "version": "0.9.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",
@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/hzblj/kara-ui/issues"
   },
-  "homepage": "https://kara.janblazej.dev/docs/components",
+  "homepage": "https://www.kara.janblazej.dev/docs/components",
   "keywords": [
     "react-native",
     "expo",
@@ -59,9 +59,9 @@
     ]
   },
   "dependencies": {
-    "@hzblj/kara-native": "^0.7.0",
-    "@hzblj/kara-sx": "^0.7.0",
-    "@hzblj/kara-theme": "^0.7.0",
+    "@hzblj/kara-native": "^0.9.0",
+    "@hzblj/kara-sx": "^0.9.0",
+    "@hzblj/kara-theme": "^0.9.0",
     "sf-symbols-typescript": "^2.2.0"
   },
   "peerDependencies": {

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

@@ -0,0 +1,32 @@
+import {Host, LoadingIndicator} from '@expo/ui/jetpack-compose'
+import {fillMaxSize, testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
+
+import type {ActivityIndicatorComponent, ActivityIndicatorProps} from './activity-indicator.types'
+
+/** Material's 48dp for a screen; half of it in a row, about where React Native's small spinner sat. */
+const styles = StyleSheet.create({
+  large: {height: 48, width: 48},
+  small: {height: 24, width: 24},
+})
+
+/**
+ * Material 3's expressive `LoadingIndicator` in a host of its own, sized here rather than measured, so it renders
+ * anywhere and takes its place in the first frame.
+ */
+export const ActivityIndicator: ActivityIndicatorComponent = ({
+  color = 'fill.accent.primary',
+  size = 'small',
+  testID,
+}: ActivityIndicatorProps) => {
+  const theme = useAppTheme()
+  const modifiers = useMemo(() => (testID ? [fillMaxSize(), testIdModifier(testID)] : [fillMaxSize()]), [testID])
+
+  return (
+    <Host colorScheme={theme.dark ? 'dark' : 'light'} seedColor={theme.materialSeed} style={styles[size]}>
+      <LoadingIndicator color={theme.color(color)} modifiers={modifiers} />
+    </Host>
+  )
+}

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

@@ -0,0 +1,15 @@
+import {useAppTheme} from '@hzblj/kara-theme'
+import {ActivityIndicator as RNActivityIndicator} from 'react-native'
+
+import type {ActivityIndicatorComponent, ActivityIndicatorProps} from './activity-indicator.types'
+
+/** React Native's spinner, which on iOS is UIKit's own `UIActivityIndicatorView`. */
+export const ActivityIndicator: ActivityIndicatorComponent = ({
+  color = 'fill.accent.primary',
+  size = 'small',
+  testID,
+}: ActivityIndicatorProps) => {
+  const theme = useAppTheme()
+
+  return <RNActivityIndicator color={theme.color(color)} size={size} testID={testID} />
+}

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

@@ -0,0 +1,20 @@
+import type {ColorToken} from '@hzblj/kara-theme'
+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
+ * `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 = {
+  /** 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. */
+  size?: ActivityIndicatorSize
+  /** Test identifier, forwarded to the view. */
+  testID?: string
+}
+
+export type ActivityIndicatorComponent = (props: ActivityIndicatorProps) => ReactNode

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

@@ -1 +1,2 @@
 export * from './activity-indicator'
+export * from './activity-indicator.types'

package/src/atoms/avatar/avatar.tsx

@@ -32,7 +32,7 @@ export const Avatar: AvatarComponent = ({initials, size = 'md', source, testID}:
       w={diameter}
     >
       {source ? (
-        <Image source={source} style={{height: diameter, width: diameter}} />
+        <Image h={diameter} source={source} w={diameter} />
       ) : (
         <RnText color="content.secondary" variant={VARIANT[size]}>
           {initials ?? ''}

package/src/atoms/blur-view/blur-view.android.tsx

@@ -0,0 +1,68 @@
+import {BackdropBlurView} from '@hzblj/kara-native/jetpack-compose'
+import {useSx} from '@hzblj/kara-sx'
+import {type ColorToken, type OpacitySize, useAppTheme, withOpacity} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
+
+import type {BlurMaterial, BlurViewComponent, BlurViewProps} from './blur-view.types'
+
+type MaterialSpec = {
+  /** dp. */
+  blur: number
+  /** A Material tonal surface — the thicker the material, the higher the container. */
+  fill: ColorToken
+  /**
+   * How much of the surface covers the blur, light and dark. A dark material covers more, as iOS's do: a dark surface
+   * over a bright backdrop otherwise leaves light content on light colour.
+   */
+  opacity: {dark: OpacitySize; light: OpacitySize}
+  /** iOS's materials lift the colour of what they blur; a plain blur greys it into mud. */
+  saturation: number
+}
+
+const MATERIALS: Record<BlurMaterial, MaterialSpec> = {
+  regular: {blur: 28, fill: 'surface.secondary', opacity: {dark: 'o75', light: 'o60'}, saturation: 1.6},
+  thick: {blur: 30, fill: 'surface.secondary', opacity: {dark: 'o85', light: 'o80'}, saturation: 1.4},
+  thin: {blur: 24, fill: 'surface.primary', opacity: {dark: 'o60', light: 'o40'}, saturation: 1.7},
+  ultraThick: {blur: 32, fill: 'fill.quaternary', opacity: {dark: 'o90', light: 'o90'}, saturation: 1.2},
+  ultraThin: {blur: 20, fill: 'surface.base', opacity: {dark: 'o50', light: 'o25'}, saturation: 1.8},
+}
+
+/**
+ * The materials in Android's terms: kara's `BackdropBlurView` — what lies behind, blurred and saturated — under a
+ * Material tonal surface that gets higher and more opaque as the material thickens. Pinned to the appearance the app
+ * is not in, the surface is Material's inverse one. `vibrancy` has no Android counterpart and is left out.
+ */
+export const BlurView: BlurViewComponent = ({
+  appearance,
+  children,
+  material = 'regular',
+  testID,
+  vibrancy: _vibrancy,
+  ...sx
+}: BlurViewProps) => {
+  const theme = useAppTheme()
+  const resolved = useSx(sx)
+  const spec = MATERIALS[material]
+  const inverted = appearance !== undefined && (appearance === 'dark') !== theme.dark
+  const dark = appearance ? appearance === 'dark' : theme.dark
+  const base = String(theme.color(inverted ? 'surface.high.contrast' : spec.fill))
+  const {cornerRadius, style} = useMemo(() => {
+    const {borderRadius, ...rest} = StyleSheet.flatten(resolved) ?? {}
+    return {cornerRadius: typeof borderRadius === 'number' ? borderRadius : 0, style: rest}
+  }, [resolved])
+
+  return (
+    <BackdropBlurView
+      blurRadius={spec.blur}
+      cornerRadius={cornerRadius}
+      fallbackTint={withOpacity(base, 'o95')}
+      glassTint={withOpacity(base, spec.opacity[dark ? 'dark' : 'light'])}
+      saturation={spec.saturation}
+      style={style}
+      testID={testID}
+    >
+      {children}
+    </BackdropBlurView>
+  )
+}

package/src/atoms/blur-view/blur-view.ios.tsx

@@ -0,0 +1,37 @@
+import {BlurView as NativeBlurView} from '@hzblj/kara-native/swift-ui'
+import {useSx} from '@hzblj/kara-sx'
+import {useAppTheme} from '@hzblj/kara-theme'
+import {useMemo} from 'react'
+import {StyleSheet} from 'react-native'
+
+import type {BlurViewComponent, BlurViewProps} from './blur-view.types'
+
+/** `borderRadius` is the material's shape, so it goes to the effect view — the one that clips — not the layout box. */
+export const BlurView: BlurViewComponent = ({
+  appearance,
+  children,
+  material = 'regular',
+  testID,
+  vibrancy,
+  ...sx
+}: BlurViewProps) => {
+  const theme = useAppTheme()
+  const resolved = useSx(sx)
+  const {cornerRadius, style} = useMemo(() => {
+    const {borderRadius, ...rest} = StyleSheet.flatten(resolved) ?? {}
+    return {cornerRadius: typeof borderRadius === 'number' ? borderRadius : 0, style: rest}
+  }, [resolved])
+
+  return (
+    <NativeBlurView
+      colorScheme={appearance ?? (theme.dark ? 'dark' : 'light')}
+      cornerRadius={cornerRadius}
+      material={material}
+      style={style}
+      testID={testID}
+      vibrancy={vibrancy}
+    >
+      {children}
+    </NativeBlurView>
+  )
+}

package/src/atoms/blur-view/blur-view.types.ts

@@ -0,0 +1,34 @@
+import type {BlurMaterial, BlurVibrancy} from '@hzblj/kara-native/swift-ui'
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
+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
+ * 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
+ * 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.
+   */
+  appearance?: 'dark' | 'light'
+  /** React Native content, over the material. */
+  children?: ReactNode
+  /** How much of what lies behind shows through, from `ultraThin` (most) to `ultraThick` (least). `regular` by default. */
+  material?: BlurMaterial
+  /** 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
+   * colour becomes the material's vibrant one and their alpha the mask. Android has no vibrancy: the children keep
+   * their colours there.
+   */
+  vibrancy?: BlurVibrancy
+}
+
+export type BlurViewComponent = (props: BlurViewProps) => ReactNode

package/src/atoms/blur-view/index.ts

@@ -0,0 +1,2 @@
+export * from './blur-view'
+export * from './blur-view.types'

package/src/atoms/glass-view/glass-view.android.tsx

@@ -1,5 +1,43 @@
-import {GlassFallback} from './glass-fallback'
+import {BackdropBlurView} from '@hzblj/kara-native/jetpack-compose'
+import {useSx} from '@hzblj/kara-sx'
+import {radii, useAppTheme, withOpacity} from '@hzblj/kara-theme'
+
 import type {GlassViewComponent, GlassViewProps} from './glass-view.types'
 
-/** Android has no Liquid Glass, so this is always the fallback capsule. */
-export const GlassView: GlassViewComponent = (props: GlassViewProps) => <GlassFallback {...props} />
+/** dp. Strong enough that a photo behind reads as colour and light, not as detail. */
+const BLUR_RADIUS = 16
+
+/**
+ * Frosted glass, Android's way: what lies behind the capsule, blurred (Android 12+), under a tonal Material surface
+ * and a light hairline — the blurred surfaces Android 16 gives its own system UI, not a copy of iOS's lens. Without a
+ * tint it is the surface colour, translucent, so the content keeps its usual colours on it; a tint fills it with that
+ * colour instead. Below Android 12, with nothing to blur, the same colours are drawn near-opaque. Android has no swell,
+ * so `interactive` changes nothing here — the `Pressable` around it gives the press its feedback.
+ */
+export const GlassView: GlassViewComponent = ({
+  children,
+  interactive: _interactive,
+  testID,
+  tint,
+  ...sx
+}: GlassViewProps) => {
+  const theme = useAppTheme()
+  const style = useSx(sx)
+  const base = String(theme.color(tint ?? 'surface.primary'))
+
+  return (
+    <BackdropBlurView
+      blurRadius={BLUR_RADIUS}
+      cornerRadius={radii.full}
+      fallbackTint={withOpacity(base, 'o95')}
+      glassTint={withOpacity(base, tint ? 'o85' : 'o50')}
+      hairlineColor={withOpacity(String(theme.color('content.on.bg')), theme.dark ? 'o20' : 'o60')}
+      hairlineWidth={1}
+      saturation={1.6}
+      style={style}
+      testID={testID}
+    >
+      {children}
+    </BackdropBlurView>
+  )
+}

package/src/atoms/glass-view/glass-view.types.ts

@@ -3,18 +3,25 @@ import type {ColorToken} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
 /**
- * iOS 26 Liquid Glass around a React Native subtree, shaped as a capsule — the React Native tier, so it needs no host
- * and costs next to nothing in a list cell. Where there is no Liquid Glass (Android, and iOS before 26) it draws a
- * capsule of `tint` instead, or of the glass buttons' translucent fill (`btn.bg.glass.base`) when there is none.
+ * Glass around a React Native subtree, shaped as a capsule — the React Native tier, so it needs no host. iOS 26:
+ * Liquid Glass. Android: frosted glass — what lies behind, blurred on Android 12+, under a translucent tonal surface
+ * (or `tint`) and a hairline. iOS before 26 has no Liquid Glass and draws a capsule of `tint` instead, or of the glass
+ * buttons' translucent fill (`btn.bg.glass.base`) when there is none.
+ *
+ * On Android each glass re-records what lies behind it before every frame: a few buttons cost nothing, but keep it out
+ * of the cells of a long list — a plain `tint` reads as well there.
  */
 export type GlassViewProps = ResponsiveViewSx & {
   /** React Native views. Give them `pointerEvents="none"` when `interactive`, so the press reaches the `Pressable`. */
   children?: ReactNode
-  /** Swells toward the finger on touch, carrying the children with it. Wrap the view in a `Pressable` for the press. */
+  /**
+   * iOS 26: swells toward the finger on touch, carrying the children with it. Android has no swell: wrap the view in a
+   * `Pressable` with `borderRadius="full"`, whose ripple then keeps to the capsule. The press is always the `Pressable`'s.
+   */
   interactive?: boolean
   /** Test identifier, forwarded to the view. */
   testID?: string
-  /** Tints the material. Unset leaves it clear. */
+  /** Tints the material. Unset leaves it clear on iOS, and the translucent surface colour on Android. */
   tint?: ColorToken
 }
 

package/src/atoms/image/image.tsx

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

package/src/atoms/image/image.types.ts

@@ -0,0 +1,6 @@
+import type {ComponentProps} from 'react'
+
+import type {Image} from './image'
+
+/** Derived from the component itself, so it cannot drift from what `sx(Image)` actually accepts. */
+export type ImageProps = ComponentProps<typeof Image>

package/src/atoms/image/index.ts

@@ -1 +1,2 @@
 export * from './image'
+export * from './image.types'

package/src/atoms/index.ts

@@ -1,6 +1,7 @@
 export * from './activity-indicator'
 export * from './avatar'
 export * from './badge'
+export * from './blur-view'
 export * from './box'
 export * from './button'
 export * from './card'

package/src/atoms/island/island.android.tsx

@@ -1,4 +1,5 @@
 import {Host} from '@expo/ui/jetpack-compose'
+import {useSx} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 
 import {HostBoundary} from '../../host-context'
@@ -8,15 +9,22 @@ const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
 
 const MATCH_NEITHER = {horizontal: false, vertical: false}
 
-export const Island: IslandComponent = ({children, matchContents = true, style}: IslandProps) => {
+export const Island: IslandComponent = ({
+  children,
+  matchContents = true,
+  style,
+  testID: _testID,
+  ...sx
+}: IslandProps) => {
   const theme = useAppTheme()
+  const resolved = useSx(sx)
 
   return (
     <Host
       colorScheme={theme.dark ? 'dark' : 'light'}
       matchContents={matchContents ? MATCH_HEIGHT_ONLY : MATCH_NEITHER}
       seedColor={theme.materialSeed}
-      style={style}
+      style={style ? [resolved, style] : resolved}
     >
       <HostBoundary>{children}</HostBoundary>
     </Host>

package/src/atoms/island/island.ios.tsx

@@ -1,5 +1,6 @@
 import {Host} from '@expo/ui/swift-ui'
 import {dynamicTypeSize} from '@expo/ui/swift-ui/modifiers'
+import {useSx} from '@hzblj/kara-sx'
 import {MAX_DYNAMIC_TYPE_SIZE, useAppTheme} from '@hzblj/kara-theme'
 
 import {HostBoundary} from '../../host-context'
@@ -11,8 +12,9 @@ const MATCH_HEIGHT_ONLY = {horizontal: false, vertical: true}
 
 const MATCH_NEITHER = {horizontal: false, vertical: false}
 
-export const Island: IslandComponent = ({children, matchContents = true, style, testID}: IslandProps) => {
+export const Island: IslandComponent = ({children, matchContents = true, style, testID, ...sx}: IslandProps) => {
   const theme = useAppTheme()
+  const resolved = useSx(sx)
 
   return (
     <Host
@@ -20,7 +22,7 @@ export const Island: IslandComponent = ({children, matchContents = true, style,
       matchContents={matchContents ? MATCH_HEIGHT_ONLY : MATCH_NEITHER}
       modifiers={DYNAMIC_TYPE_CAP}
       seedColor={theme.materialSeed}
-      style={style}
+      style={style ? [resolved, style] : resolved}
       testID={testID}
     >
       <HostBoundary>{children}</HostBoundary>

package/src/atoms/island/island.types.ts

@@ -1,8 +1,12 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
 import type {ReactNode} from 'react'
 import type {StyleProp, ViewStyle} from 'react-native'
 
-/** A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. */
-export type IslandProps = {
+/**
+ * A host for native atoms in a React Native layout — the SwiftUI / Compose `Host` an `@expo/ui` tree mounts into. It
+ * sits in that layout like a `Box`, and takes `Box`'s `sx` props for it: `h`, `flex`, margins.
+ */
+export type IslandProps = ResponsiveViewSx & {
   /** The native views it hosts. */
   children?: ReactNode
   /**
@@ -11,13 +15,13 @@ export type IslandProps = {
    * width maps to `fixedSize(horizontal: true)`, so the native side ignores the proposed width and
    * resolves a `wide` stack's ideal width as unbounded.
    *
-   * Turn it off — and give the island an explicit size via `style` — when the subtree contains an
+   * Turn it off — and give the island an explicit height, `h` — when the subtree contains an
    * `RnView`: that host drives its SwiftUI frame from the child's Yoga-laid-out bounds while this one
    * writes its measured size back into the Yoga style, and the two together spin a layout loop that
    * hangs the main thread as soon as the views lay out on screen.
    */
   matchContents?: boolean
-  /** A React Native style for the host view — its size and placement. It needs a height when `matchContents` is off. */
+  /** A React Native style for the host view, merged over the `sx` props — for what they cannot say. */
   style?: StyleProp<ViewStyle>
   /** Test identifier, forwarded to the host view on iOS — Android ignores it. */
   testID?: string

package/src/atoms/pressable/pressable.tsx

@@ -1,9 +1,11 @@
 import {useSplitSx} from '@hzblj/kara-sx'
-import {useCallback} from 'react'
-import {Pressable as RNPressable} from 'react-native'
+import {useAppTheme, withOpacity} from '@hzblj/kara-theme'
+import {useCallback, useMemo} from 'react'
+import {Platform, Pressable as RNPressable, View, type ViewStyle} from 'react-native'
 import Animated, {useAnimatedStyle, useSharedValue, withSpring} from 'react-native-reanimated'
 
 import {haptics} from '../../haptics'
+import {splitForRipple} from '../../ripple-clip'
 import type {PressableComponent, PressableProps} from './pressable.types'
 
 const SPRING = {damping: 20, stiffness: 400}
@@ -22,20 +24,39 @@ export const Pressable: PressableComponent = ({
   const scale = useSharedValue(1)
   const feedback = haptic === true ? 'light' : haptic || undefined
 
+  const theme = useAppTheme()
+  const isAndroid = Platform.OS === 'android'
+
   const rStyle = useAnimatedStyle(() => ({transform: [{scale: scale.value}]}), [])
 
+  // Android's press is Material's: a ripple over the content — the pressed state layer, `onSurface` at 10 % — clipped to
+  // the shape by an outer view (`splitForRipple`), and nothing moves. iOS springs down.
+  const ripple = useMemo(
+    () =>
+      isAndroid ? {color: withOpacity(String(theme.color('content.primary')), 'o10'), foreground: true} : undefined,
+    [isAndroid, theme]
+  )
+  const androidStyle = useMemo(
+    () => (isAndroid ? splitForRipple(resolved as ViewStyle) : undefined),
+    [isAndroid, resolved]
+  )
+
   // The finger is down: the Taptic Engine has until the release to wake, so the haptic lands with the press.
   const onPressIn = useCallback(() => {
-    scale.value = withSpring(0.96, SPRING)
+    if (!isAndroid) {
+      scale.value = withSpring(0.96, SPRING)
+    }
 
     if (feedback) {
       haptics.prepare(feedback)
     }
-  }, [feedback, scale])
+  }, [feedback, isAndroid, scale])
 
   const onPressOut = useCallback(() => {
-    scale.value = withSpring(1, SPRING)
-  }, [scale])
+    if (!isAndroid) {
+      scale.value = withSpring(1, SPRING)
+    }
+  }, [isAndroid, scale])
 
   const onPressWithHaptic = useCallback(() => {
     if (feedback) {
@@ -45,6 +66,25 @@ export const Pressable: PressableComponent = ({
     onPress?.()
   }, [feedback, onPress])
 
+  if (androidStyle) {
+    return (
+      <View style={androidStyle.outer}>
+        <RNPressable
+          android_ripple={ripple}
+          disabled={disabled}
+          hitSlop={8}
+          onPress={onPressWithHaptic}
+          onPressIn={onPressIn}
+          style={androidStyle.inner}
+          testID={testID}
+          {...rest}
+        >
+          {children}
+        </RNPressable>
+      </View>
+    )
+  }
+
   return (
     <AnimatedPressable
       disabled={disabled}