@olympusoss/canvas 3.2.1 → 5.0.0

package/src/atoms/spinner/spinner.styles.tsx

@@ -0,0 +1,115 @@
+import { ActivityIndicator, Animated } from "react-native";
+import Svg, { Circle, Line } from "react-native-svg";
+import { type ColorTokens } from "../../style/index.js";
+import { type SpinnerSkin } from "./spinner.shared.js";
+
+// Co-located Spinner skins, one per platform. The BRAND survives on every
+// platform (the arc/spoke color is a semantic token, never a platform default),
+// and only the native SHAPE of the loader changes per OS:
+//   iOS (UIActivityIndicatorView): a ring of 12 short rounded SPOKES arranged
+//     radially around the center, each with a graduated opacity (a fading
+//     "clock" of lines), the whole ring rotating continuously. Color = the tone
+//     token (default the muted/foreground arc color).
+//   Android (M3 CircularProgressIndicator, indeterminate): a SINGLE ARC, a ~270deg
+//     stroke of a ring with a rounded cap, in the brand color, sweeping
+//     continuously around the circle.
+//   Web: the established Canvas look, a React Native ActivityIndicator driven by
+//     the same tone/size props, lifted verbatim from the original component.
+
+export type Tone = "primary" | "muted" | "foreground";
+
+// Arc/spoke color token per tone: reads from the active brand tokens (via
+// useTheme) so it follows light/dark and the glass surface.
+export const TONE_TOKEN: Record<Tone, keyof ColorTokens> = {
+  primary: "primary",
+  muted: "muted-foreground",
+  foreground: "foreground",
+};
+
+// react-native-svg's Circle/Line aren't Animated components; wrapping the SVG in
+// the shell's Animated.View and spinning that is enough, but the rotation has to
+// live on an Animated.View. The skins below return a static SVG; the shell's
+// Animated.View carries the spin. To make the *shape itself* rotate (not just the
+// bounding box), each spinning skin wraps its SVG in an Animated.View whose
+// transform interpolates the shared 0..1 value to 0..360deg.
+
+const AnimatedSvg = Animated.createAnimatedComponent(Svg);
+
+// iOS: 12 spokes laid out every 30deg around the center, each a short rounded
+// line from an inner radius to the rim. Opacity steps down around the ring so the
+// leading spoke is solid and the trailing ones fade, the classic iOS look. The
+// whole SVG rotates via the shared spin value.
+const SPOKE_COUNT = 12;
+
+export const iosSkin: SpinnerSkin = {
+  render: ({ size, color, rotate }) => {
+    const c = size / 2;
+    const outer = size / 2;
+    const inner = size * 0.28;
+    const strokeWidth = Math.max(1, size * 0.08);
+    const spin = rotate.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "360deg"] });
+    const spokes = Array.from({ length: SPOKE_COUNT }, (_, i) => {
+      const angle = (i / SPOKE_COUNT) * 2 * Math.PI - Math.PI / 2;
+      const x1 = c + inner * Math.cos(angle);
+      const y1 = c + inner * Math.sin(angle);
+      const x2 = c + outer * Math.cos(angle);
+      const y2 = c + outer * Math.sin(angle);
+      // Leading spoke solid, fading around the ring (min ~0.2).
+      const opacity = 0.2 + (0.8 * i) / (SPOKE_COUNT - 1);
+      return (
+        <Line
+          key={i}
+          x1={x1}
+          y1={y1}
+          x2={x2}
+          y2={y2}
+          stroke={color}
+          strokeWidth={strokeWidth}
+          strokeLinecap="round"
+          opacity={opacity}
+        />
+      );
+    });
+    return (
+      <AnimatedSvg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ transform: [{ rotate: spin }] }}>
+        {spokes}
+      </AnimatedSvg>
+    );
+  },
+};
+
+// Android (M3): one ~270deg arc of a ring, rounded cap, brand color, sweeping
+// continuously. Drawn as a stroked circle whose dash covers 3/4 of the
+// circumference; the whole SVG rotates via the shared spin value.
+export const androidSkin: SpinnerSkin = {
+  render: ({ size, color, rotate }) => {
+    const strokeWidth = Math.max(2, size * 0.1);
+    const r = (size - strokeWidth) / 2;
+    const c = size / 2;
+    const circumference = 2 * Math.PI * r;
+    const arc = circumference * 0.75; // 270deg sweep
+    const spin = rotate.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "360deg"] });
+    return (
+      <AnimatedSvg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ transform: [{ rotate: spin }] }}>
+        <Circle
+          cx={c}
+          cy={c}
+          r={r}
+          stroke={color}
+          strokeWidth={strokeWidth}
+          strokeLinecap="round"
+          fill="none"
+          strokeDasharray={`${arc} ${circumference}`}
+        />
+      </AnimatedSvg>
+    );
+  },
+};
+
+// Web: the current Canvas look, a React Native ActivityIndicator driven by the
+// same tone/size props (numeric size + token color), lifted verbatim from the
+// original single-file component. It animates itself, so it ignores the shared
+// rotate value.
+export const webSkin: SpinnerSkin = {
+  render: ({ size, color }) => <ActivityIndicator size={size} color={color} />,
+};

package/src/atoms/spinner/spinner.tsx

@@ -0,0 +1,7 @@
+import { createSpinner } from "./spinner.shared.js";
+import { webSkin } from "./spinner.styles.js";
+
+// Web Spinner (the base; Metro falls back to it on native, web bundlers resolve
+// it). Keeps the original ActivityIndicator look verbatim.
+export const Spinner = createSpinner(webSkin);
+export type { SpinnerProps } from "./spinner.shared.js";

package/src/atoms/switch/switch.android.tsx

@@ -0,0 +1,6 @@
+import { createSwitch } from "./switch.shared.js";
+import { androidSkin } from "./switch.styles.js";
+
+// Material 3 Switch. Metro resolves this file on Android; the docs import it for preview.
+export const Switch = createSwitch(androidSkin);
+export type { SwitchProps } from "./switch.shared.js";

package/src/atoms/switch/switch.ios.tsx

@@ -0,0 +1,6 @@
+import { createSwitch } from "./switch.shared.js";
+import { iosSkin } from "./switch.styles.js";
+
+// iOS (HIG) Switch. Metro resolves this file on iOS; the docs import it for preview.
+export const Switch = createSwitch(iosSkin);
+export type { SwitchProps } from "./switch.shared.js";

package/src/atoms/switch/switch.md

@@ -0,0 +1,91 @@
+# Toggles
+
+On / off switch, isolated or grouped in a settings list.
+
+## Usage
+
+```tsx
+<Switch checked>Available to chat</Switch>
+```
+
+## Variants
+
+### State - off
+
+```tsx
+<Switch>Available to chat</Switch>
+```
+
+### With description
+
+```tsx
+<Switch checked description="Show your availability to teammates.">Available to chat</Switch>
+```
+
+### Disabled
+
+```tsx
+<Switch checked disabled>Available to chat</Switch>
+```
+
+## Do & Don't
+
+### Off
+
+**Do** — Keep the standard bg-input off track so off stays clearly interactive and distinct from a disabled control.
+
+```tsx
+<Switch style={{ maxWidth: 280 }}>Two-factor auth</Switch>
+```
+
+**Don't** — A washed-out off track reads as disabled, so users can't tell the switch is simply off versus locked.
+
+```tsx
+<Pressable style={{ maxWidth: 280, flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 16 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Two-factor auth</Text>
+  <View style={{ position: "relative", flexShrink: 0, borderRadius: 9999, width: 36, height: 20, backgroundColor: alpha(tokens.muted, 0.3) }}>
+    <View style={{ position: "absolute", top: 2, left: 2, borderRadius: 9999, width: 16, height: 16, backgroundColor: tokens.muted }} />
+  </View>
+</Pressable>
+```
+
+### On
+
+**Do** — Reserve the on switch for instantly reversible settings; route irreversible actions through a button plus confirmation.
+
+```tsx
+<View style={{ maxWidth: 280, flexDirection: "column", gap: 12 }}>
+  <Switch checked>Auto-save drafts</Switch>
+  <Button destructive small style={{ alignSelf: "flex-start" }}>Delete account…</Button>
+</View>
+```
+
+**Don't** — A switch applies instantly; wiring an on toggle to an irreversible action invites accidental, unconfirmed data loss.
+
+```tsx
+<Pressable style={{ maxWidth: 280, flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 16 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.destructive }}>Permanently delete account</Text>
+  <View style={{ position: "relative", flexShrink: 0, borderRadius: 9999, width: 36, height: 20, backgroundColor: tokens.primary }}>
+    <View style={{ position: "absolute", top: 2, right: 2, borderRadius: 9999, width: 16, height: 16, backgroundColor: tokens.background, ...shadow() }} />
+  </View>
+</Pressable>
+```
+
+**Do** — Label the setting, not the state; the switch communicates on or off.
+
+```tsx
+<Switch checked style={{ maxWidth: 280 }}>Notifications</Switch>
+```
+
+**Don't** — An On/Off label duplicates what the switch position already shows.
+
+```tsx
+<View style={{ maxWidth: 280, flexDirection: "row", alignItems: "center", justifyContent: "space-between" }}>
+  <Text style={{ fontSize: 13 }}>Notifications</Text>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+    <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>Off</Text>
+    <Switch />
+    <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>On</Text>
+  </View>
+</View>
+```

package/src/atoms/switch/switch.shared.tsx

@@ -0,0 +1,97 @@
+import { type ReactNode } from "react";
+import { type GestureResponderEvent } from "react-native";
+import { Pressable, View, Text, useTheme, type ColorTokens, type ViewStyle } from "../../style/index.js";
+
+// Shared Switch shell. Uses React Native's primitives DIRECTLY (no engine className
+// layer) and reads the active brand tokens via useTheme, so colors follow light/dark.
+// The shared structure (label/description row, accessibility, toggle, sizing) lives
+// here once; a platform file supplies only its track + thumb styles (a SwitchSkin)
+// and calls createSwitch. Styles are plain RN objects, which work on iOS, Android,
+// and web alike (a real .css file would only work on the web).
+
+export interface SwitchProps {
+  /** Controlled on/off state. The component renders exactly this value. */
+  checked?: boolean;
+  /** Fired with the next checked value when the switch is toggled. */
+  onChange?: (next: boolean) => void;
+  /** Alias of onChange, for parity with RN's value-style callbacks. */
+  onValueChange?: (next: boolean) => void;
+  // Size (pick one; default is the standard track).
+  small?: boolean;
+  large?: boolean;
+  // State.
+  disabled?: boolean;
+  /** Optional label, rendered to the left of the track. */
+  children?: ReactNode;
+  /** Optional muted description line, rendered under the label. */
+  description?: ReactNode;
+  /** Extra style on the row, applied last. */
+  style?: ViewStyle;
+}
+
+export type Size = "small" | "base" | "large";
+
+function sizeOf(p: SwitchProps): Size {
+  if (p.large) return "large";
+  if (p.small) return "small";
+  return "base";
+}
+
+// The only thing a platform skin owns: the track and thumb styles for a given
+// on/off state and size, built from the active tokens. Everything else is the shell.
+export interface SwitchSkin {
+  track: (tokens: ColorTokens, checked: boolean, size: Size) => ViewStyle;
+  thumb: (tokens: ColorTokens, checked: boolean, size: Size) => ViewStyle;
+}
+
+const LABEL_FONT: Record<Size, number> = { small: 12, base: 14, large: 16 };
+const DESC_FONT: Record<Size, number> = { small: 11, base: 12, large: 14 };
+
+/** Build a Switch component from a platform skin. */
+export function createSwitch(skin: SwitchSkin) {
+  return function Switch(props: SwitchProps) {
+    const { checked = false, onChange, onValueChange, disabled, children, description, style } = props;
+    const { tokens } = useTheme();
+    const size = sizeOf(props);
+
+    const handlePress = (_event: GestureResponderEvent) => {
+      const next = !checked;
+      onChange?.(next);
+      onValueChange?.(next);
+    };
+
+    return (
+      <Pressable
+        onPress={handlePress}
+        disabled={disabled}
+        accessibilityRole="switch"
+        accessibilityState={{ checked, disabled: !!disabled }}
+        style={({ pressed }) => [
+          {
+            flexDirection: "row",
+            justifyContent: "space-between",
+            gap: 16,
+            alignItems: description != null ? "flex-start" : "center",
+          },
+          disabled ? { opacity: 0.5 } : null,
+          pressed ? { opacity: 0.9 } : null,
+          style,
+        ]}
+      >
+        {children != null || description != null ? (
+          <View>
+            {children != null ? (
+              <Text style={{ fontWeight: "500", color: tokens.foreground, fontSize: LABEL_FONT[size] }}>{children}</Text>
+            ) : null}
+            {description != null ? (
+              <Text style={{ color: tokens["muted-foreground"], fontSize: DESC_FONT[size] }}>{description}</Text>
+            ) : null}
+          </View>
+        ) : null}
+        <View style={skin.track(tokens, checked, size)}>
+          <View style={skin.thumb(tokens, checked, size)} />
+        </View>
+      </Pressable>
+    );
+  };
+}

package/src/atoms/switch/switch.styles.ts

@@ -0,0 +1,79 @@
+import { type ViewStyle } from "react-native";
+import { type SwitchSkin, type Size } from "./switch.shared.js";
+
+// Co-located Switch styles, one skin per platform, all driven by the brand tokens
+// (passed in from useTheme so they follow light/dark). Plain RN style objects, so
+// they apply on iOS, Android, and web alike. The on-track is always the brand
+// `primary`, never the platform default, so the control reads native but stays yours.
+
+const NATIVE_TRACK: Record<Size, { width: number; height: number }> = {
+  small: { width: 44, height: 24 },
+  base: { width: 48, height: 28 },
+  large: { width: 56, height: 32 },
+};
+
+const WEB_TRACK: Record<Size, { width: number; height: number }> = {
+  small: { width: 32, height: 20 },
+  base: { width: 36, height: 20 },
+  large: { width: 44, height: 24 },
+};
+
+const WEB_THUMB: Record<Size, number> = { small: 14, base: 16, large: 20 };
+
+const PILL: ViewStyle = { borderRadius: 999, position: "relative" };
+const ABS: ViewStyle = { position: "absolute", borderRadius: 999 };
+const IOS_SHADOW: ViewStyle = {
+  shadowColor: "#000000",
+  shadowOffset: { width: 0, height: 1 },
+  shadowOpacity: 0.2,
+  shadowRadius: 2,
+  elevation: 2,
+};
+
+// iOS (HIG): a solid pill with a near-full white thumb.
+export const iosSkin: SwitchSkin = {
+  track: (t, checked, size) => ({
+    ...PILL,
+    width: NATIVE_TRACK[size].width,
+    height: NATIVE_TRACK[size].height,
+    backgroundColor: checked ? t.primary : t.input,
+  }),
+  thumb: (_t, checked, size) => {
+    const d = NATIVE_TRACK[size].height - 4;
+    return { ...ABS, ...IOS_SHADOW, top: 2, width: d, height: d, backgroundColor: "#ffffff", ...(checked ? { right: 2 } : { left: 2 }) };
+  },
+};
+
+// Material 3: an outlined track with a small dot when off; a filled brand track with
+// a larger white thumb when on.
+export const androidSkin: SwitchSkin = {
+  track: (t, checked, size) => ({
+    ...PILL,
+    width: NATIVE_TRACK[size].width,
+    height: NATIVE_TRACK[size].height,
+    ...(checked ? { backgroundColor: t.primary } : { backgroundColor: t.muted, borderWidth: 2, borderColor: t.border }),
+  }),
+  thumb: (t, checked, size) => {
+    const h = NATIVE_TRACK[size].height;
+    if (checked) {
+      const d = h - 8;
+      return { ...ABS, top: (h - d) / 2, right: 4, width: d, height: d, backgroundColor: "#ffffff" };
+    }
+    const d = Math.round(h / 2.6);
+    return { ...ABS, top: (h - 4 - d) / 2, left: 4, width: d, height: d, backgroundColor: t["muted-foreground"] };
+  },
+};
+
+// Web: the current Canvas look, a compact pill with a surface-colored thumb.
+export const webSkin: SwitchSkin = {
+  track: (t, checked, size) => ({
+    ...PILL,
+    width: WEB_TRACK[size].width,
+    height: WEB_TRACK[size].height,
+    backgroundColor: checked ? t.primary : t.input,
+  }),
+  thumb: (t, checked, size) => {
+    const d = WEB_THUMB[size];
+    return { ...ABS, top: 2, width: d, height: d, backgroundColor: t.background, ...(checked ? { right: 2 } : { left: 2 }) };
+  },
+};

package/src/atoms/switch/switch.tsx

@@ -0,0 +1,6 @@
+import { createSwitch } from "./switch.shared.js";
+import { webSkin } from "./switch.styles.js";
+
+// Web Switch (the base; Metro falls back to it on native, web bundlers resolve it).
+export const Switch = createSwitch(webSkin);
+export type { SwitchProps } from "./switch.shared.js";

package/src/atoms/textarea/textarea.android.tsx

@@ -0,0 +1,6 @@
+import { createTextarea } from "./textarea.shared.js";
+import { androidSkin } from "./textarea.styles.js";
+
+// Material 3 filled Textarea. Metro resolves this file on Android; the docs import it for preview.
+export const Textarea = createTextarea(androidSkin);
+export type { TextareaProps } from "./textarea.shared.js";

package/src/atoms/textarea/textarea.ios.tsx

@@ -0,0 +1,6 @@
+import { createTextarea } from "./textarea.shared.js";
+import { iosSkin } from "./textarea.styles.js";
+
+// iOS (HIG text view) Textarea. Metro resolves this file on iOS; the docs import it for preview.
+export const Textarea = createTextarea(iosSkin);
+export type { TextareaProps } from "./textarea.shared.js";

package/src/atoms/textarea/textarea.md

@@ -0,0 +1,140 @@
+# Textareas
+
+Multi-line input, with character count, with toolbar.
+
+## Usage
+
+```tsx
+<Textarea rows={4} placeholder="A few words about this project" />
+```
+
+## Variants
+
+### Character counter
+
+```tsx
+<View style={{ maxWidth: 400 }}>
+  <Text style={{ marginBottom: 6, fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Description</Text>
+  <Textarea rows={4} placeholder="A few words about this project…" />
+  <View style={{ marginTop: 4, flexDirection: "row", justifyContent: "flex-end" }}>
+    <Text style={{ fontSize: 11, color: tokens["muted-foreground"] }}>0 / 280</Text>
+  </View>
+</View>
+```
+
+### Formatting toolbar
+
+```tsx
+<View style={{ maxWidth: 400, overflow: "hidden", borderRadius: 6, borderWidth: 1, borderColor: tokens.border }}>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 4, borderBottomWidth: 1, borderColor: tokens.border, backgroundColor: alpha(tokens.muted, 0.3), paddingHorizontal: 12, paddingVertical: 8 }}>
+    <Button ghost small style={{ minWidth: 32, paddingHorizontal: 8 }}>B</Button>
+    <Button ghost small style={{ minWidth: 32, paddingHorizontal: 8 }}>I</Button>
+    <Button ghost small style={{ minWidth: 32, paddingHorizontal: 8 }}>{"</>"}</Button>
+    <View style={{ marginHorizontal: 4, height: 16, width: 1, backgroundColor: tokens.border }} />
+    <Button ghost small style={{ paddingHorizontal: 12 }}>Comment</Button>
+  </View>
+  <Textarea rows={4} placeholder="Leave a comment…" style={{ minHeight: 104, width: "100%", borderRadius: 0, borderWidth: 0 }} />
+</View>
+```
+
+### Disabled
+
+```tsx
+<Textarea rows={4} disabled placeholder="A few words about this project" />
+```
+
+## Do & Don't
+
+### With label
+
+**Do** — Give a sensible min-height and allow vertical resize so users can see and grow their text.
+
+```tsx
+<View style={{ maxWidth: 400, flexDirection: "column", gap: 6 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Description</Text>
+  <Textarea rows={3} value="This is a longer description that runs past one line and stays readable." />
+</View>
+```
+
+**Don't** — A locked, single-line textarea hides long content with no way to expand.
+
+```tsx
+<View style={{ maxWidth: 400, flexDirection: "column", gap: 6 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Description</Text>
+  <TextInput numberOfLines={1} value="This is a longer description that runs past one line and gets clipped." style={{ height: 32, width: "100%", borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background, paddingHorizontal: 12, paddingVertical: 4, fontSize: 14, lineHeight: 20, color: tokens.foreground }} />
+</View>
+```
+
+### Character counter
+
+**Do** — Show the live count against the cap and turn it destructive past the limit so the overage is precise.
+
+```tsx
+<View style={{ maxWidth: 400, flexDirection: "column", gap: 6 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Bio</Text>
+  <Textarea rows={3} invalid value="I have been building things on the web for fifteen years and counting, across teams large and small, shipping product end to end." />
+  <View style={{ marginTop: 4, flexDirection: "row", justifyContent: "flex-end" }}>
+    <Text style={{ fontSize: 11, color: tokens.destructive }}>123 / 120</Text>
+  </View>
+</View>
+```
+
+**Don't** — A vague "over limit" message gives no number, so users cannot tell how much to trim.
+
+```tsx
+<View style={{ maxWidth: 400, flexDirection: "column", gap: 6 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Bio</Text>
+  <Textarea rows={3} value="I have been building things on the web for fifteen years and counting, across teams large and small, shipping product end to end." />
+  <View style={{ marginTop: 4, flexDirection: "row", justifyContent: "flex-end" }}>
+    <Text style={{ fontSize: 11, color: tokens["muted-foreground"] }}>over limit</Text>
+  </View>
+</View>
+```
+
+### Formatting toolbar
+
+**Do** — Make each control a real focusable button that toggles an active state when pressed.
+
+```tsx
+<View style={{ maxWidth: 400, overflow: "hidden", borderRadius: 6, borderWidth: 1, borderColor: tokens.border }}>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 4, borderBottomWidth: 1, borderColor: tokens.border, backgroundColor: alpha(tokens.muted, 0.3), paddingHorizontal: 12, paddingVertical: 8 }}>
+    <Button ghost small style={{ fontWeight: "700" }}>B</Button>
+    <Button ghost small style={{ fontStyle: "italic" }}>I</Button>
+    <Button ghost small style={{ fontFamily: "monospace", fontSize: 11 }}>{"</>"}</Button>
+  </View>
+  <Textarea rows={4} placeholder="Leave a comment" style={{ borderRadius: 0, borderWidth: 0, ...shadow("none") }} />
+</View>
+```
+
+**Don't** — Static, unclickable glyphs look like a toolbar but cannot be pressed or focused.
+
+```tsx
+<View style={{ maxWidth: 400, overflow: "hidden", borderRadius: 6, borderWidth: 1, borderColor: tokens.border }}>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 4, borderBottomWidth: 1, borderColor: tokens.border, backgroundColor: alpha(tokens.muted, 0.3), paddingHorizontal: 12, paddingVertical: 8 }}>
+    <Text style={{ paddingHorizontal: 8, fontSize: 14, lineHeight: 20, fontWeight: "700" }}>B</Text>
+    <Text style={{ paddingHorizontal: 8, fontSize: 14, lineHeight: 20, fontStyle: "italic" }}>I</Text>
+    <Text style={{ paddingHorizontal: 8, fontFamily: "monospace", fontSize: 11 }}>{"</>"}</Text>
+  </View>
+  <Textarea rows={4} placeholder="Leave a comment" style={{ borderRadius: 0, borderWidth: 0, ...shadow("none") }} />
+</View>
+```
+
+### Disabled
+
+**Do** — Use the disabled attribute so the field blocks editing and focus, matching its dimmed look.
+
+```tsx
+<View style={{ maxWidth: 400, flexDirection: "column", gap: 6 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Description</Text>
+  <Textarea rows={3} disabled value="Read-only content the user must not change." />
+</View>
+```
+
+**Don't** — Dimming a textarea while leaving it editable looks disabled but still accepts input.
+
+```tsx
+<View style={{ maxWidth: 400, flexDirection: "column", gap: 6 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Description</Text>
+  <TextInput multiline editable textAlignVertical="top" value="Read-only content the user must not change." style={{ minHeight: 80, width: "100%", borderRadius: 6, borderWidth: 1, borderColor: tokens.input, backgroundColor: tokens.background, paddingHorizontal: 12, paddingVertical: 8, fontSize: 14, lineHeight: 20, color: tokens.foreground, opacity: 0.5 }} />
+</View>
+```

package/src/atoms/textarea/textarea.shared.tsx

@@ -0,0 +1,74 @@
+import { useState } from "react";
+import { TextInput, useTheme, type StyleProp, type TextStyle } from "../../style/index.js";
+import { type TextareaSkin, type Size, sizeText, minHeight } from "./textarea.styles.js";
+
+// Shared Textarea shell. The structure (a multiline TextInput), the public
+// boolean-prop API, the size precedence, the error/focus state resolution, the
+// accessibility, the handlers, and the disabled dim live here once; a platform
+// file supplies only its skin (fill, shape, border/underline, focus feedback)
+// and calls createTextarea.
+
+export interface TextareaProps {
+  /** Controlled text value. */
+  value?: string;
+  /** Fired with the next text value on each edit. */
+  onChangeText?: (next: string) => void;
+  /** Placeholder shown while the field is empty. */
+  placeholder?: string;
+  /**
+   * Visible rows the field sizes to. Sets the min height (rows * ~22px + 16px
+   * padding); the field still grows with content past this floor.
+   */
+  rows?: number;
+  // State (pick one; orthogonal to size).
+  /** Error/validation state: a destructive cue. `invalid` is an alias. */
+  error?: boolean;
+  invalid?: boolean;
+  // Size (pick one; default is the base text-sm field).
+  small?: boolean;
+  large?: boolean;
+  /** Blocks editing and focus, and dims the field. */
+  disabled?: boolean;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<TextStyle>;
+}
+
+// Size precedence when more than one is passed: first match wins.
+function sizeOf(p: TextareaProps): Size {
+  if (p.large) return "large";
+  if (p.small) return "small";
+  return "base";
+}
+
+/** Build a Textarea component from a platform skin. */
+export function createTextarea(skin: TextareaSkin) {
+  return function Textarea(props: TextareaProps) {
+    const { value, onChangeText, placeholder, rows, disabled, style } = props;
+    const isError = !!props.error || !!props.invalid;
+    const size = sizeOf(props);
+    const [focused, setFocused] = useState(false);
+    const { tokens } = useTheme();
+
+    return (
+      <TextInput
+        multiline
+        value={value}
+        onChangeText={onChangeText}
+        placeholder={placeholder}
+        placeholderTextColor={tokens["muted-foreground"]}
+        selectionColor={tokens.primary} // brand cursor / selection on every platform
+        editable={!disabled}
+        textAlignVertical="top"
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+        style={[
+          skin.field(tokens, { error: isError, focused }),
+          sizeText(size),
+          minHeight(rows),
+          disabled ? { opacity: 0.5 } : null,
+          style,
+        ]}
+      />
+    );
+  };
+}