@hzblj/kara-components 0.9.0 → 0.10.0

package/lib/typescript/atoms/card/card.types.d.ts

@@ -1,7 +1,7 @@
 import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 /**
- * A raised container — SwiftUI `VStack` / Compose `Column` on `surface.primary`, with a large radius, `s16` padding and
+ * A raised container: SwiftUI `VStack` / Compose `Column` on `surface.primary`, with a large radius, `s16` padding and
  * the `card` shadow. Any `sx` prop overrides its default.
  */
 export type CardProps = ResponsiveSx & {

package/lib/typescript/atoms/checkbox/checkbox.types.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-/** Material's `Checkbox` on Android. iOS has none, so there it is a SwiftUI `Toggle` — the same switch as `Switch`. */
+/** Material's `Checkbox` on Android. iOS has none, so there it is a SwiftUI `Toggle`, the same switch as `Switch`. */
 export type CheckboxProps = {
     /** Dims the control and ignores taps. */
     disabled?: boolean;
@@ -7,7 +7,7 @@ export type CheckboxProps = {
     label?: string;
     /** Called with the new value when the user toggles it. */
     onValueChange?: (value: boolean) => void;
-    /** Whether it is checked. Controlled — update it from `onValueChange`. */
+    /** Whether it is checked. Controlled: update it from `onValueChange`. */
     value: boolean;
 };
 export type CheckboxComponent = (props: CheckboxProps) => ReactNode;

package/lib/typescript/atoms/chip/chip.types.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-/** A filter pill on a `Pressable`, not a native control — the React Native tier, so it needs no host. */
+/** A filter pill on a `Pressable`, not a native control. It belongs to the React Native tier, so it needs no host. */
 export type ChipProps = {
     /** The text in the pill. */
     label: string;

package/lib/typescript/atoms/color-picker/color-picker.types.d.ts

@@ -1,10 +1,11 @@
 import type { ReactNode } from 'react';
 /**
- * The system colour picker. iOS only — Compose ships no equivalent, so on Android this
- * renders nothing and says so in dev. Branch on `Platform.OS` if the screen needs a fallback.
+ * A row with a label and a colour well that opens a picker: SwiftUI's `ColorPicker` on iOS. Compose ships none, so on
+ * Android it is kara's own, in the same shape: a well with a rainbow ring, and a sheet with a grid of swatches, a
+ * spectrum and RGB sliders.
  */
 export type ColorPickerProps = {
-    /** Text beside the colour well. */
+    /** Text beside the colour well, and the Android sheet's title. */
     label?: string;
     /** Called with the colour the user picks. */
     onValueChange?: (color: string) => void;

package/lib/typescript/atoms/date-picker/date-picker.types.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 export type DatePickerMode = 'date' | 'datetime' | 'time';
 /**
- * A date or time picker — SwiftUI's compact `DatePicker` on iOS, a field that opens Material's picker dialog on a tap
+ * 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`.
  */
@@ -15,11 +15,11 @@ export type DatePickerProps = {
      * `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. */
     onValueChange?: (date: Date) => void;
-    /** Test identifier — on the native picker on iOS, on the tappable field on Android. */
+    /** Test identifier, on the native picker on iOS and on the tappable field on Android. */
     testID?: string;
-    /** The selected date. Controlled — update it from `onValueChange`. */
+    /** The selected date. Controlled: update it from `onValueChange`. */
     value: Date;
 };
 export type DatePickerComponent = (props: DatePickerProps) => ReactNode;

package/lib/typescript/atoms/divider/divider.types.d.ts

@@ -1,10 +1,10 @@
 import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
-/** A horizontal hairline — SwiftUI `Divider` / Compose `HorizontalDivider`. */
+/** A horizontal hairline: SwiftUI `Divider` / Compose `HorizontalDivider`. */
 export type DividerProps = {
     /** 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 on iOS. Android ignores it. */
     testID?: string;
 };
 export type DividerComponent = (props: DividerProps) => ReactNode;

package/lib/typescript/atoms/fab/fab.types.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 import type { IconName } from '../icon';
 /**
- * A floating action button — Material's `FloatingActionButton` on Android, a 56pt accent circle (a plain SwiftUI
+ * 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.
  */
 export type FabProps = {
@@ -9,7 +9,7 @@ export type FabProps = {
     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 on iOS. Android ignores it. */
     testID?: string;
 };
 export type FabComponent = (props: FabProps) => ReactNode;

package/lib/typescript/atoms/glass-view/glass-view.types.d.ts

@@ -2,13 +2,13 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { ColorToken } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 /**
- * 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.
+ * Glass around a React Native subtree, shaped as a capsule. It belongs to the React Native tier, so it needs no host.
+ * iOS 26: Liquid Glass. Android: frosted glass, made of 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.
+ * 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`. */

package/lib/typescript/atoms/h-stack/h-stack.types.d.ts

@@ -2,13 +2,13 @@ import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 export type HStackAlign = 'center' | 'end' | 'start';
-/** A horizontal stack — SwiftUI `HStack` / Compose `Row`. */
+/** A horizontal stack: SwiftUI `HStack` / Compose `Row`. */
 export type HStackProps = ResponsiveSx & {
-    /** How the children line up vertically — `start` is the top, `end` the bottom. `start` by default. */
+    /** How the children line up vertically: `start` is the top, `end` the bottom. `start` by default. */
     align?: HStackAlign;
     /** Native views, laid out from the leading edge. */
     children?: ReactNode;
-    /** Makes the stack pressable — a tap gesture on iOS, a `clickable` with Material's ripple on Android. */
+    /** Makes the stack pressable: a tap gesture on iOS, a `clickable` with Material's ripple on Android. */
     onPress?: () => void;
     /** The gap between children. Unset, SwiftUI puts its default spacing between them and Compose none. */
     spacing?: SpaceSize;

package/lib/typescript/atoms/icon/icon.types.d.ts

@@ -11,12 +11,12 @@ declare global {
 }
 type DeclaredIconName = keyof KaraIcons & string;
 /**
- * One of the app's icons. Once the plugin has written `kara-icons.d.ts` only those names type-check — an icon removed
+ * One of the app's icons. Once the plugin has written `kara-icons.d.ts` only those names type-check: an icon removed
  * from the folder fails at every call site. Before that, any string, so a project can adopt icons gradually.
  */
 export type IconName = [DeclaredIconName] extends [never] ? string : DeclaredIconName;
 /**
- * One of the app's icons, in a host — SwiftUI `Image` from the asset catalog on iOS, Material's `Icon` with the vector
+ * One of the app's icons, in a host: SwiftUI `Image` from the asset catalog on iOS, Material's `Icon` with the vector
  * drawable on Android. `RnIcon` draws the same asset outside one.
  */
 export type IconProps = {
@@ -24,11 +24,11 @@ export type IconProps = {
     accessibilityLabel?: string;
     /** The icon's tint. `content.primary` by default. */
     color?: ColorToken;
-    /** Which of the app's icons — a key of `KaraIcons`. */
+    /** Which of the app's icons, a key of `KaraIcons`. */
     name: IconName;
     /** Its width and height, a spacing token. `s24` by default. */
     size?: SpaceSize;
-    /** Test identifier, forwarded to the native view on iOS — Android ignores it. */
+    /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
     testID?: string;
 };
 export type IconComponent = (props: IconProps) => ReactNode;

package/lib/typescript/atoms/icon-button/icon-button.types.d.ts

@@ -1,14 +1,18 @@
 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. */
+/**
+ * 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.
+ */
 export type IconButtonProps = {
-    /** Draws the icon in `btn.content.disabled` and stops the button responding to presses. */
+    /** 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 on iOS. Android ignores it. */
     testID?: string;
 };
 export type IconButtonComponent = (props: IconButtonProps) => ReactNode;

package/lib/typescript/atoms/island/island.types.d.ts

@@ -2,7 +2,7 @@ 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. It
+ * 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 & {
@@ -14,15 +14,15 @@ export type IslandProps = ResponsiveViewSx & {
      * 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 height, `h` — 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, merged over the `sx` props — for what they cannot say. */
+    /** 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. */
+    /** Test identifier, forwarded to the host view on iOS. Android ignores it. */
     testID?: string;
 };
 export type IslandComponent = (props: IslandProps) => ReactNode;

package/lib/typescript/atoms/list/list.types.d.ts

@@ -1,22 +1,22 @@
 import type { ReactNode } from 'react';
 /**
- * A scrolling list — SwiftUI `List`, Compose `LazyColumn`. It has no height of its own, so it needs one from outside:
+ * 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
  * Compose measures it against an infinite height and throws ("Vertically scrollable component was measured with an
  * infinity maximum height"); SwiftUI shows nothing. For a handful of rows that should not scroll, use a `VStack`.
  *
- * Rows are separated for you — SwiftUI's own separators, a `Divider` between rows on Android — so a `Divider` among
+ * Rows are separated for you (SwiftUI's own separators, a `Divider` between rows on Android), so a `Divider` among
  * the children is one too many: on iOS it becomes an empty row of its own.
  */
 export type ListProps = {
-    /** The rows — native views, one row each. */
+    /** The rows: native views, one row each. */
     children: ReactNode;
     /**
-     * Enables pull-to-refresh. Async on purpose — see `ScrollViewProps.onRefresh`: the spinner runs
+     * Enables pull-to-refresh. Async on purpose (see `ScrollViewProps.onRefresh`): the spinner runs
      * 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. */
+    /** Test identifier, forwarded to the native view on iOS. Android ignores it. */
     testID?: string;
 };
 export type ListComponent = (props: ListProps) => ReactNode;

package/lib/typescript/atoms/picker/picker.types.d.ts

@@ -7,7 +7,7 @@ export type PickerOption = {
     value: string;
 };
 /**
- * A single choice from a list — a SwiftUI wheel picker on iOS, Material's exposed dropdown on Android. It brings its
+ * 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.
  */
 export type PickerProps = {

package/lib/typescript/atoms/pressable/pressable.types.d.ts

@@ -1,21 +1,37 @@
 import type { ResponsiveViewSx } from '@hzblj/kara-sx';
+import type { OpacitySize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 import type { Haptic } from '../../haptics';
+/** How the content answers a press: it springs down, it dims, or it stays still. */
+export type PressEffect = 'none' | 'opacity' | 'scale';
 /**
- * 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.
+ * React Native's `Pressable`, styled through `sx` like a `Box`, taking touches 8 points past its edges. Each platform
+ * presses its own way by default: iOS springs the content down to 96%, Android draws Material's ripple over it,
+ * clipped to the pressable's shape. `pressEffect` picks the same answer on both, and Android keeps its ripple on top
+ * unless `ripple` is off. 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 or ripple. */
+    /** Ignores presses: no `onPress`, no haptic, no press effect 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;
     /** Called when the press is released, after the `haptic` plays. */
     onPress?: () => void;
+    /**
+     * How the content answers while it is held. `scale` springs it down to `pressedScale`, `opacity` dims it to
+     * `pressedOpacity`, `none` leaves it still. `scale` on iOS and `none` on Android by default, where the ripple is the
+     * press.
+     */
+    pressEffect?: PressEffect;
+    /** What `opacity` dims to, an opacity token. `o60` by default. */
+    pressedOpacity?: OpacitySize;
+    /** What `scale` springs down to. `0.96` by default. */
+    pressedScale?: number;
+    /** Android's ripple: Material's pressed state layer over the content, clipped to the shape. On by default. iOS has none. */
+    ripple?: boolean;
     /** Test identifier, forwarded to the view. */
     testID?: string;
 };

package/lib/typescript/atoms/progress/progress.types.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 /**
- * A progress bar or ring, tinted `fill.accent.primary` — SwiftUI `ProgressView` (a capacity `Gauge` for a ring with a
+ * 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`.
  */
 export type ProgressProps = {

package/lib/typescript/atoms/rn-flat-list/rn-flat-list.types.d.ts

@@ -2,10 +2,10 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { FlatListProps as RNFlatListProps } from 'react-native';
 /**
  * Top-level `sx` styles the viewport; `content` styles the scrolling content container, so padding and
- * gap belong there — the same split as `RnScrollView`. `removeClippedSubviews` is off unless you turn it on:
+ * gap belong there (the same split as `RnScrollView`). `removeClippedSubviews` is off unless you turn it on:
  * Android's default would detach a row's host before it has measured itself, and the row would stay empty.
  */
 export type RnFlatListProps<TItem> = ResponsiveViewSx & Omit<RNFlatListProps<TItem>, 'contentContainerStyle' | 'style'> & {
-    /** Styles the scrolling content container — padding and gap belong here. */
+    /** Styles the scrolling content container; padding and gap belong here. */
     content?: ResponsiveViewSx;
 };

package/lib/typescript/atoms/rn-icon/rn-icon.types.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
 import type { IconProps } from '../icon';
-/** The same contract as `Icon`, for the React Native tier — anywhere, no `Screen` or `Island` needed. */
+/** The same contract as `Icon`, for the React Native tier: anywhere, no `Screen` or `Island` needed. */
 export type RnIconProps = IconProps;
 export type RnIconComponent = (props: RnIconProps) => ReactNode;

package/lib/typescript/atoms/rn-scroll-view/rn-scroll-view.types.d.ts

@@ -3,7 +3,7 @@ import type { ReactNode } from 'react';
 import type { ScrollViewProps as RNScrollViewProps } from 'react-native';
 import type { ScrollViewAxis } from '../scroll-view';
 /**
- * React Native tier scroll container — the sibling of `RnView`/`RnText`. Use it when the
+ * React Native tier scroll container, the sibling of `RnView`/`RnText`. Use it when the
  * subtree is React Native and native atoms are embedded through `Island`. For a screen that
  * is native all the way down, reach for the `ScrollView` atom instead.
  *
@@ -15,7 +15,7 @@ export type RnScrollViewProps = ResponsiveViewSx & Omit<RNScrollViewProps, 'cont
     axis?: ScrollViewAxis;
     /** The scrolling content. */
     children?: ReactNode;
-    /** Styles the scrolling content container — padding and gap belong here. */
+    /** Styles the scrolling content container; padding and gap belong here. */
     content?: ResponsiveViewSx;
     /** Shows the scroll indicators. On by default. */
     showsIndicators?: boolean;

package/lib/typescript/atoms/rn-section-list/rn-section-list.types.d.ts

@@ -2,10 +2,10 @@ import type { ResponsiveViewSx } from '@hzblj/kara-sx';
 import type { DefaultSectionT, SectionListProps as RNSectionListProps } from 'react-native';
 /**
  * Top-level `sx` styles the viewport; `content` styles the scrolling content container, so padding and
- * gap belong there — the same split as `RnScrollView` and `RnFlatList`. `removeClippedSubviews` is off unless
+ * gap belong there (the same split as `RnScrollView` and `RnFlatList`). `removeClippedSubviews` is off unless
  * you turn it on, as in `RnFlatList`: Android's default would leave rows with hosts in them empty.
  */
 export type RnSectionListProps<TItem, TSection = DefaultSectionT> = ResponsiveViewSx & Omit<RNSectionListProps<TItem, TSection>, 'contentContainerStyle' | 'style'> & {
-    /** Styles the scrolling content container — padding and gap belong here. */
+    /** Styles the scrolling content container; padding and gap belong here. */
     content?: ResponsiveViewSx;
 };

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

@@ -3,8 +3,8 @@ 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. It takes
- * `Box`'s `sx` surface for its own box — margins, flex, padding, a background — all but `align`, which here aligns the
+ * 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'> & {

package/lib/typescript/atoms/rn-view/rn-view.types.d.ts

@@ -1,11 +1,11 @@
 import type { ReactElement, ReactNode } from 'react';
-/** Carries a React Native view into a SwiftUI or Compose tree — `@expo/ui`'s `RNHostView` on both platforms. */
+/** Carries a React Native view into a SwiftUI or Compose tree: `@expo/ui`'s `RNHostView` on both platforms. */
 export type RnViewProps = {
     /**
      * A single React Native *view*. It may not contain React Native text: a bare string becomes a
      * `RawText` node, which has no component view, so mounting it across the SwiftUI host boundary
      * fails the `RCTComponentViewFactory` assertion and takes the whole app down. `@expo/ui` states
-     * the rule itself in `ListItem.ios.tsx` — "SwiftUI hosts can't render bare strings" — and wraps
+     * the rule itself in `ListItem.ios.tsx` ("SwiftUI hosts can't render bare strings") and wraps
      * every raw string in a SwiftUI `Text` before it reaches a host. Do the same: use the `Text` atom
      * inside the host, and keep `RnText` outside it.
      */
@@ -15,7 +15,7 @@ export type RnViewProps = {
      * intrinsic size and would otherwise stretch to fill the SwiftUI parent.
      */
     matchContents?: boolean;
-    /** Not forwarded on either platform — give the child its own `testID`. */
+    /** Not forwarded on either platform: give the child its own `testID`. */
     testID?: string;
 };
 export type RnViewComponent = (props: RnViewProps) => ReactNode;

package/lib/typescript/atoms/scroll-view/scroll-view.types.d.ts

@@ -3,7 +3,7 @@ import type { SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 export type ScrollViewAxis = 'horizontal' | 'vertical';
 /**
- * The `sx` props style the scrolling *content* container, not the viewport — `p` behaves
+ * The `sx` props style the scrolling *content* container, not the viewport: `p` behaves
  * like React Native's `contentContainerStyle` padding and scrolls with the content.
  */
 export type ScrollViewProps = ResponsiveSx & {
@@ -13,13 +13,13 @@ export type ScrollViewProps = ResponsiveSx & {
     children?: ReactNode;
     /**
      * Enables pull-to-refresh. Async on purpose: the spinner runs until the promise settles, which is
-     * what SwiftUI's `refreshable` expects and what Compose's controlled indicator is driven from — so
+     * what SwiftUI's `refreshable` expects and what Compose's controlled indicator is driven from, so
      * neither platform needs a separate `refreshing` flag to be kept in sync by the caller.
      *
      * Only a vertical scroll view can be pulled; on a horizontal one both platforms ignore it.
      */
     onRefresh?: () => Promise<void>;
-    /** iOS only — Compose exposes no indicator toggle, so Android always shows the native one. */
+    /** iOS only: Compose exposes no indicator toggle, so Android always shows the native one. */
     showsIndicators?: boolean;
     /** The space between children. */
     spacing?: SpaceSize;

package/lib/typescript/atoms/segmented-control/segmented-control.types.d.ts

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 /**
- * A row of mutually exclusive segments, the selected one in the accent — kara's own `UISegmentedControl` on iOS,
+ * A row of mutually exclusive segments, the selected one in the accent: kara's own `UISegmentedControl` on iOS,
  * Material's single-choice segmented buttons on Android. It needs no `Screen` or `Island`: iOS is a plain view, Android
  * brings its own host. It takes the width it is given; the height is the platform's.
  */
@@ -8,13 +8,13 @@ export type SegmentedControlProps = {
     /** Stops the user changing the segment, and dims the control. */
     disabled?: boolean;
     /**
-     * Called with the index and label of the segment the user picked — never for a tap on the one already selected.
+     * Called with the index and label of the segment the user picked, never for a tap on the one already selected.
      * Android plays `selection`; iOS's control plays its own feedback.
      */
     onChange?: (index: number, value: string) => void;
     /** The selected segment. Controlled: pass back what `onChange` reports. */
     selectedIndex: number;
-    /** Test identifier, on the whole control — reach a segment by its label. */
+    /** Test identifier, on the whole control. Reach a segment by its label. */
     testID?: string;
     /** The segments' labels, in order. */
     values: string[];

package/lib/typescript/atoms/skeleton/skeleton.types.d.ts

@@ -2,8 +2,8 @@ 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. Sized with the
- * `sx` names: `w`, `h`, `borderRadius`.
+ * A loading placeholder that pulses in `fill.quaternary`. It is 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. */

package/lib/typescript/atoms/spacer/spacer.types.d.ts

@@ -1,6 +1,6 @@
 import type { SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
-/** Takes up the free space in a stack — SwiftUI `Spacer` / Compose `Spacer` with `weight(1)`. */
+/** Takes up the free space in a stack: SwiftUI `Spacer` / Compose `Spacer` with `weight(1)`. */
 export type SpacerProps = {
     /** The least room it takes. iOS holds it along the stack's axis; Android as a minimum height only. */
     min?: SpaceSize;

package/lib/typescript/atoms/surface/surface.types.d.ts

@@ -1,7 +1,7 @@
 import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 /**
- * A container on `surface.primary`, padded `s16` and rounded `large` unless told otherwise — a SwiftUI `VStack` on
+ * A container on `surface.primary`, padded `s16` and rounded `large` unless told otherwise: a SwiftUI `VStack` on
  * iOS, Material's `Surface` around a `Column` on Android.
  */
 export type SurfaceProps = ResponsiveSx & {

package/lib/typescript/atoms/switch/switch.types.d.ts

@@ -4,7 +4,7 @@ export type SwitchProps = {
     /** Stops the user flipping it, and dims it. */
     disabled?: boolean;
     /**
-     * Shown beside the switch. On Android it makes a full-width row — label at the start, switch at the end — that
+     * Shown beside the switch. On Android it makes a full-width row (label at the start, switch at the end) that
      * toggles wherever it is tapped.
      */
     label?: string;

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

@@ -5,7 +5,7 @@ export type TextAlign = 'center' | 'left' | 'right';
 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`. It takes
+ * 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.
  */

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

@@ -1,16 +1,16 @@
 import type { ReactNode } from 'react';
 /**
- * An uncontrolled text field with an optional label above it — SwiftUI `TextField` (`SecureField` when `secure`) /
+ * An uncontrolled text field with an optional label above it: SwiftUI `TextField` (`SecureField` when `secure`) /
  * Compose `OutlinedTextField`.
  */
 export type TextFieldProps = {
-    /** The text it starts with. Read once, on mount — the field is uncontrolled. */
+    /** The text it starts with. Read once, on mount: the field is uncontrolled. */
     defaultValue?: string;
     /** Stops editing and dims the field. On iOS it outranks `error`. */
     disabled?: 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
+     * 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;

package/lib/typescript/atoms/v-stack/v-stack.types.d.ts

@@ -2,7 +2,7 @@ import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 export type VStackAlign = 'center' | 'end' | 'start';
-/** Stacks its children top to bottom — SwiftUI `VStack` / Compose `Column`. */
+/** Stacks its children top to bottom: SwiftUI `VStack` / Compose `Column`. */
 export type VStackProps = ResponsiveSx & {
     /** The children's horizontal alignment. `start` by default. */
     align?: VStackAlign;

package/lib/typescript/atoms/z-stack/z-stack.types.d.ts

@@ -1,7 +1,7 @@
 import type { ResponsiveSx } from '@hzblj/kara-sx';
 import type { ReactNode } from 'react';
 export type ZStackAlign = 'bottom' | 'center' | 'top';
-/** Layers its children on one another — SwiftUI `ZStack` / Compose `Box`. */
+/** Layers its children on one another: SwiftUI `ZStack` / Compose `Box`. */
 export type ZStackProps = ResponsiveSx & {
     /** Where the children sit vertically; they are always centred horizontally. `center` by default. */
     align?: ZStackAlign;

package/lib/typescript/glyph/glyph-button.types.d.ts

@@ -1,6 +1,6 @@
 import type { GlyphName } from '@hzblj/kara-native';
 import type { ReactNode } from 'react';
-/** An icon button over one of kara's glyphs — for the controls its own components build (a stepper, a bar). */
+/** An icon button over one of kara's glyphs, for the controls its own components build (a stepper, a bar). */
 export type GlyphButtonProps = {
     accessibilityLabel?: string;
     disabled?: boolean;

package/lib/typescript/glyph/glyph.types.d.ts

@@ -2,7 +2,7 @@ import type { GlyphName } from '@hzblj/kara-native';
 import type { ColorToken, SpaceSize } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 /**
- * One of the few glyphs kara's own components draw — a search field's magnifier, a row's chevron. Internal: apps draw
+ * One of the few glyphs kara's own components draw: a search field's magnifier, a row's chevron. Internal: apps draw
  * their own icons with `Icon` / `RnIcon`.
  */
 export type GlyphProps = {

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

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 /**
  * A row that shows and hides its content: SwiftUI's `DisclosureGroup` on iOS; on Android a pressable row with a
- * chevron over an animated reveal. A native atom — it renders inside `<Screen>` or `<Island>`.
+ * chevron over an animated reveal. A native atom: it renders inside `<Screen>` or `<Island>`.
  */
 export type CollapsibleProps = {
     /** Shown while `expanded`. */

package/lib/typescript/molecules/empty-state/empty-state.types.d.ts

@@ -5,7 +5,7 @@ import type { IconName } from '../../atoms/icon';
  * `action` takes a `Button` so the state can offer a way out.
  */
 export type EmptyStateProps = {
-    /** Under the text — a `Button`, say. */
+    /** Under the text: a `Button`, say. */
     action?: ReactNode;
     /** A second line under the title, in the secondary colour. */
     description?: string;

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

@@ -2,7 +2,7 @@ import type { ColorToken, SpaceSize, TextVariant } from '@hzblj/kara-theme';
 import type { ReactNode } from 'react';
 import type { IconName } from '../../atoms/icon';
 /**
- * An inline icon + text pair — the thing you put inside a button, a menu row or a section
+ * An inline icon + text pair: the thing you put inside a button, a menu row or a section
  * header. For a full tappable row with a subtitle and chevron, use `ListItem`.
  */
 export type LabelProps = {