@hzblj/kara-components 0.7.0 → 0.8.0

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}

package/src/atoms/pressable/pressable.types.ts

@@ -4,13 +4,15 @@ import type {ReactNode} from 'react'
 import type {Haptic} from '../../haptics'
 
 /**
- * React Native's `Pressable`, styled through `sx` like a `Box`: it springs down to 96% while pressed and takes
- * touches 8 points past its edges. The React Native tier — it needs no host.
+ * React Native's `Pressable`, styled through `sx` like a `Box`, taking touches 8 points past its edges. The press is
+ * each platform's own: iOS springs it down to 96%; Android draws Material's ripple over the content, clipped to the
+ * pressable's shape — give it the `borderRadius` of what it wraps (`full` around a `GlassView`). The React Native
+ * tier — it needs no host.
  */
 export type PressableProps = ResponsiveViewSx & {
   /** The pressable content. */
   children?: ReactNode
-  /** Ignores presses — no `onPress`, no haptic, no spring. */
+  /** Ignores presses — no `onPress`, no haptic, no spring or ripple. */
   disabled?: boolean
   /** Played on press. `true` is a `light` impact; a name picks the haptic, e.g. `selection` for a choice. */
   haptic?: boolean | Haptic

package/src/atoms/rn-text/rn-text.tsx

@@ -1,5 +1,6 @@
+import {useSplitSx} from '@hzblj/kara-sx'
 import {MAX_FONT_SCALE, useAppTheme} from '@hzblj/kara-theme'
-import {Text as RNText, useWindowDimensions} from 'react-native'
+import {Text as RNText, type TextStyle, useWindowDimensions} from 'react-native'
 
 import type {RnTextComponent, RnTextProps} from './rn-text.types'
 
@@ -10,6 +11,8 @@ export const RnText: RnTextComponent = ({
   ...props
 }: RnTextProps) => {
   const theme = useAppTheme()
+  // A view style, which a text accepts whole — only React Native's types disagree, on `userSelect`'s width.
+  const [sx, rest] = useSplitSx(props) as [TextStyle, Record<string, unknown>]
   const {fontScale} = useWindowDimensions()
   const style = theme.typography[variant]
 
@@ -26,8 +29,8 @@ export const RnText: RnTextComponent = ({
   return (
     <RNText
       maxFontSizeMultiplier={MAX_FONT_SCALE}
-      style={[style, {color: theme.color(color), lineHeight, textAlign: align}]}
-      {...props}
+      style={[style, sx, {color: theme.color(color), lineHeight, textAlign: align}]}
+      {...rest}
     />
   )
 }

package/src/atoms/rn-text/rn-text.types.ts

@@ -1,15 +1,21 @@
+import type {ResponsiveViewSx} from '@hzblj/kara-sx'
 import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 import type {TextProps as RNTextProps} from 'react-native'
 
-/** React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. */
-export type RnTextProps = Omit<RNTextProps, 'style'> & {
-  /** Horizontal alignment, as React Native's `textAlign`. */
-  align?: 'center' | 'left' | 'right'
-  /** The text's colour. `content.primary` by default. */
-  color?: ColorToken
-  /** The typography variant. `body` by default. */
-  variant?: TextVariant
-}
+/**
+ * React Native's `Text` in a theme typography variant — the React Native tier, for text outside a native host. It takes
+ * `Box`'s `sx` surface for its own box — margins, flex, padding, a background — all but `align`, which here aligns the
+ * lines.
+ */
+export type RnTextProps = Omit<RNTextProps, 'style'> &
+  Omit<ResponsiveViewSx, 'align'> & {
+    /** Horizontal alignment, as React Native's `textAlign`. */
+    align?: 'center' | 'left' | 'right'
+    /** The text's colour. `content.primary` by default. */
+    color?: ColorToken
+    /** The typography variant. `body` by default. */
+    variant?: TextVariant
+  }
 
 export type RnTextComponent = (props: RnTextProps) => ReactNode

package/src/atoms/skeleton/skeleton.tsx

@@ -5,7 +5,7 @@ import {useAnimatedStyle, useSharedValue, withRepeat, withTiming} from 'react-na
 import {ABox} from '../box'
 import type {SkeletonComponent, SkeletonProps} from './skeleton.types'
 
-export const Skeleton: SkeletonComponent = ({borderRadius = 'small', height, testID, width}: SkeletonProps) => {
+export const Skeleton: SkeletonComponent = ({borderRadius = 'small', h, testID, w}: SkeletonProps) => {
   const pulse = useSharedValue<number>(opacity.o40)
 
   useEffect(() => {
@@ -18,11 +18,11 @@ export const Skeleton: SkeletonComponent = ({borderRadius = 'small', height, tes
     <ABox
       bg="fill.quaternary"
       borderRadius={borderRadius}
-      h={height}
+      h={h}
       style={rStyle}
       testID={testID}
-      w={width}
-      wide={width === undefined}
+      w={w}
+      wide={w === undefined}
     />
   )
 }

package/src/atoms/skeleton/skeleton.types.ts

@@ -1,16 +1,20 @@
+import type {SxDimension} from '@hzblj/kara-sx'
 import type {RadiiSize} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
-/** A loading placeholder that pulses in `fill.quaternary` — a React Native view, so it needs no host. */
+/**
+ * A loading placeholder that pulses in `fill.quaternary` — a React Native view, so it needs no host. Sized with the
+ * `sx` names: `w`, `h`, `borderRadius`.
+ */
 export type SkeletonProps = {
   /** The corner radius. `small` by default. */
   borderRadius?: RadiiSize
   /** In points. */
-  height: number
+  h: number
   /** Test identifier, forwarded to the view. */
   testID?: string
-  /** In points. Leave it unset and it fills the available width. */
-  width?: number
+  /** In points, or a percentage of the row (`60%` for a line that ends early). Unset, it fills the row. */
+  w?: SxDimension
 }
 
 export type SkeletonComponent = (props: SkeletonProps) => ReactNode

package/src/atoms/text/text.android.tsx

@@ -1,5 +1,6 @@
 import {Text as ComposeText} from '@expo/ui/jetpack-compose'
 import {testID as testIdModifier} from '@expo/ui/jetpack-compose/modifiers'
+import {useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
@@ -32,11 +33,16 @@ export const Text: TextComponent = ({
   testID,
   transform,
   variant = 'body',
+  ...sx
 }: TextProps) => {
   useHostGuard('Text')
   const theme = useAppTheme()
   const style = theme.typography[variant]
-  const modifiers = useMemo(() => (testID ? [testIdModifier(testID)] : undefined), [testID])
+  const sxModifiers = useSxModifiers(sx)
+  const modifiers = useMemo(
+    () => (testID ? [...sxModifiers, testIdModifier(testID)] : sxModifiers),
+    [sxModifiers, testID]
+  )
 
   return (
     <ComposeText

package/src/atoms/text/text.ios.tsx

@@ -10,11 +10,12 @@ import {
   underline,
 } from '@expo/ui/swift-ui/modifiers'
 import {scaledFont} from '@hzblj/kara-native/swift-ui'
+import {type FrameAlignment, useSxModifiers} from '@hzblj/kara-sx'
 import {useAppTheme} from '@hzblj/kara-theme'
 import {useMemo} from 'react'
 
 import {useHostGuard} from '../../host-context'
-import type {TextComponent, TextProps} from './text.types'
+import type {TextAlign, TextComponent, TextProps} from './text.types'
 
 const ALIGNMENT = {
   center: 'center',
@@ -22,6 +23,13 @@ const ALIGNMENT = {
   right: 'trailing',
 } as const
 
+/** Where a frame larger than the text — `wide`, `w`, `h` — puts it: on the side its lines align to, centred vertically. */
+const FRAME_ALIGNMENT = {
+  center: 'center',
+  left: 'leading',
+  right: 'trailing',
+} as const satisfies Record<TextAlign, FrameAlignment>
+
 export const Text: TextComponent = ({
   align,
   children,
@@ -31,10 +39,13 @@ export const Text: TextComponent = ({
   testID,
   transform,
   variant = 'body',
+  ...sx
 }: TextProps) => {
   useHostGuard('Text')
   const theme = useAppTheme()
   const style = theme.typography[variant]
+  // After the text's own modifiers: the font and colour belong to the glyphs, the padding and frame to the box around.
+  const sxModifiers = useSxModifiers(sx, FRAME_ALIGNMENT[align ?? 'left'])
 
   const modifiers = useMemo(() => {
     const list: ModifierConfig[] = [
@@ -65,8 +76,8 @@ export const Text: TextComponent = ({
       list.push(lineLimit(numberOfLines))
     }
 
-    return list
-  }, [align, color, decoration, numberOfLines, style, theme, transform])
+    return [...list, ...sxModifiers]
+  }, [align, color, decoration, numberOfLines, style, sxModifiers, theme, transform])
 
   return (
     <SwiftUIText modifiers={modifiers} testID={testID}>

package/src/atoms/text/text.types.ts

@@ -1,3 +1,4 @@
+import type {ResponsiveSx} from '@hzblj/kara-sx'
 import type {ColorToken, TextVariant} from '@hzblj/kara-theme'
 import type {ReactNode} from 'react'
 
@@ -7,8 +8,12 @@ export type TextDecoration = 'none' | 'strikethrough' | 'underline'
 
 export type TextTransform = 'lowercase' | 'uppercase'
 
-/** SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. */
-export type TextProps = {
+/**
+ * SwiftUI `Text` / Compose `Text` in a theme typography variant — a native atom; outside a host, use `RnText`. It takes
+ * the native `sx` surface too: padding, a frame (`wide` lines it up by `align`), a background, and the `ios` bucket's
+ * `contentTransition`, `animation` and `monospacedDigit` for a number that changes in place.
+ */
+export type TextProps = ResponsiveSx & {
   /**
    * How its lines align. iOS reads `left` and `right` as leading and trailing, so they flip in a right-to-left
    * layout; Android keeps them as they are.