@olympusoss/canvas 3.2.1 → 5.0.0

package/src/organisms/navbars/navbars.md

@@ -0,0 +1,144 @@
+# Navbars
+
+Topbars with navigation links, search, and action buttons. Used as the primary app-level navigation.
+
+## Usage
+
+```tsx
+<Navbar
+  brand="Canvas"
+  links={["Dashboard", "Users", "Settings"]}
+  active={0}
+  actionLabel="New"
+  avatar="RC"
+  bordered
+/>
+```
+
+## Variants
+
+### Layout - search
+
+```tsx
+<Navbar
+  brand="Canvas"
+  links={["Dashboard", "Users", "Settings"]}
+  active={0}
+  avatar="RC"
+  bordered
+/>
+```
+
+### Layout - mobile
+
+```tsx
+<Navbar
+  brand="Canvas"
+  links={["Dashboard", "Users", "Settings"]}
+  active={0}
+  actionLabel="New"
+  avatar="RC"
+/>
+```
+
+## Do & Don't
+
+### Standard topbar
+
+**Do** — Keep a few primary links inline and fold the rest behind a More menu.
+
+```tsx
+<Navbar bordered brand="Canvas" active={0} links={["Dashboard", "Users", "Settings"]} actionLabel="New" avatar="RC" />
+```
+
+**Don't** — Cramming every destination into the bar wraps the row and buries the primary links.
+
+```tsx
+<Navbar bordered brand="Canvas" active={0} links={[
+    "Dashboard",
+    "Users",
+    "Settings",
+    "Billing",
+    "Reports",
+    "Integrations",
+    "Audit",
+    "Webhooks"
+  ]} avatar="RC" />
+```
+
+### With search bar
+
+**Do** — Use a button that opens the command palette and advertise the ⌘K shortcut.
+
+```tsx
+<View style={{ width: "100%", overflow: "hidden", borderRadius: 8, borderWidth: 1, borderColor: tokens.border }}>
+  <View style={{ flexDirection: "row", height: 56, alignItems: "center", gap: 8, backgroundColor: tokens.card, paddingHorizontal: 16 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.foreground }}>Canvas</Text>
+    <View style={{ marginHorizontal: 16, maxWidth: 400, flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+      <Pressable style={({ pressed }) => [{ flexDirection: "row", height: 34, width: "100%", alignItems: "center", gap: 8, borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, paddingHorizontal: 10 }, pressed ? { opacity: 0.9 } : null]}>
+        <Icon search muted size={13} />
+        <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", textAlign: "left", fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Search…</Text>
+        <Kbd>⌘K</Kbd>
+      </Pressable>
+    </View>
+  </View>
+</View>
+```
+
+**Don't** — A live text field in the bar reads as a form input and offers no keyboard affordance.
+
+```tsx
+<View style={{ width: "100%", overflow: "hidden", borderRadius: 8, borderWidth: 1, borderColor: tokens.border }}>
+  <View style={{ flexDirection: "row", height: 56, alignItems: "center", gap: 8, backgroundColor: tokens.card, paddingHorizontal: 16 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.foreground }}>Canvas</Text>
+    <View style={{ marginHorizontal: 16, maxWidth: 400, flexGrow: 1, flexShrink: 1, flexBasis: "0%" }}>
+      <TextInput placeholder="Search…" style={{ height: 36, width: "100%", borderRadius: 6, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.background, paddingHorizontal: 12, paddingVertical: 4, fontSize: 14, lineHeight: 20, color: tokens.foreground }} />
+    </View>
+  </View>
+</View>
+```
+
+### Mobile
+
+**Do** — Collapse the links into a hamburger and keep only the logo and avatar in the bar.
+
+```tsx
+<View style={{ width: "100%", maxWidth: 360, overflow: "hidden", borderRadius: 8, borderWidth: 1, borderColor: tokens.border }}>
+  <View style={{ flexDirection: "row", height: 56, alignItems: "center", gap: 8, backgroundColor: tokens.card, paddingHorizontal: 12 }}>
+    <Pressable style={({ pressed }) => [{ height: 36, width: 36, alignItems: "center", justifyContent: "center", borderRadius: 6 }, pressed ? { backgroundColor: tokens.accent } : null]}>
+      <View style={{ width: 18, gap: 4 }}>
+        <View style={{ height: 2, width: "100%", borderRadius: 9999, backgroundColor: tokens["muted-foreground"] }} />
+        <View style={{ height: 2, width: "100%", borderRadius: 9999, backgroundColor: tokens["muted-foreground"] }} />
+        <View style={{ height: 2, width: "100%", borderRadius: 9999, backgroundColor: tokens["muted-foreground"] }} />
+      </View>
+    </Pressable>
+    <Text style={{ fontSize: 13, fontWeight: "600", color: tokens.foreground }}>Canvas</Text>
+    <View style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%" }} />
+    <Avatar small src="/rachel-chen.jpg" name="RC" />
+  </View>
+</View>
+```
+
+**Don't** — A full horizontal nav at phone width wraps onto a second row and crowds out the logo.
+
+```tsx
+<View style={{ width: "100%", maxWidth: 360, overflow: "hidden", borderRadius: 8, borderWidth: 1, borderColor: tokens.border }}>
+  <View style={{ flexDirection: "row", height: 56, alignItems: "center", gap: 4, backgroundColor: tokens.card, paddingHorizontal: 12 }}>
+    <Text style={{ fontSize: 13, fontWeight: "600", color: tokens.foreground }}>Canvas</Text>
+    <View style={{ marginLeft: 8, flexDirection: "row", flexWrap: "wrap", gap: 4 }}>
+      <Pressable style={({ pressed }) => [{ borderRadius: 6, backgroundColor: tokens.accent, paddingHorizontal: 12, paddingVertical: 6 }, pressed ? { opacity: 0.9 } : null]}>
+        <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Dashboard</Text>
+      </Pressable>
+      <Pressable style={({ pressed }) => [{ borderRadius: 6, paddingHorizontal: 12, paddingVertical: 6 }, pressed ? { opacity: 0.9 } : null]}>
+        <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["muted-foreground"] }}>Users</Text>
+      </Pressable>
+      <Pressable style={({ pressed }) => [{ borderRadius: 6, paddingHorizontal: 12, paddingVertical: 6 }, pressed ? { opacity: 0.9 } : null]}>
+        <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["muted-foreground"] }}>Settings</Text>
+      </Pressable>
+      <Pressable style={({ pressed }) => [{ borderRadius: 6, paddingHorizontal: 12, paddingVertical: 6 }, pressed ? { opacity: 0.9 } : null]}>
+        <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["muted-foreground"] }}>Billing</Text>
+      </Pressable>
+    </View>
+  </View>
+</View>
+```

package/src/organisms/navbars/navbars.shared.tsx

@@ -0,0 +1,137 @@
+import { type ReactNode } from "react";
+import { View, Pressable, Text, useTheme, type ColorTokens, type StyleProp, type ViewStyle, type TextStyle } from "../../style/index.js";
+import { Button } from "../../atoms/button/button.js";
+import { Avatar } from "../../atoms/avatar/avatar.js";
+import { type Surface } from "./navbars.styles.js";
+
+// Shared Navbar shell. The structure (the left brand + links cluster, the right
+// action + avatar cluster), the surface-axis precedence, the active-link
+// selection, the accessibility, and the press handlers live here once; a
+// platform file supplies only its skin (the native bar height/padding, the
+// surface treatment, the brand type, the link tile/label, and the press
+// feedback) and calls createNavbar.
+//
+// The navbar is the primary app-level topbar: a brand on the left, a row of
+// navigation links in the middle with one active, and actions on the right (a
+// primary action button and/or an account avatar). It is a fixed-height
+// horizontal bar, laid out desktop-first.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf). The surface axis sets
+// how the bar sits on the page: the default rests flush with a bottom hairline,
+// `bordered` boxes it on all four sides with a rounded outline, and `floating`
+// lifts it as a rounded, shadowed card detached from the page edge. Each
+// platform skin renders that axis in its own native idiom (iOS keeps a slim
+// hairline-separated bar; Android keeps a flat borderless top app bar).
+
+// The platform-varying surface. Everything color/shape-bearing the bar needs
+// lives here, built from the active tokens (so each follows light/dark/glass).
+export interface NavbarSkin {
+  /** iOS/web dim a pressed link; Android uses a ripple instead (null). */
+  pressedOpacity: number | null;
+  /** Android ripple over a pressed link; null on iOS/web. */
+  ripple: ((t: ColorTokens) => { color: string; borderless: boolean }) | null;
+
+  /** The bar row: height, padding, and flex layout. */
+  bar: (t: ColorTokens) => ViewStyle;
+  /** The token-driven background fill (follows the scheme/glass surface). */
+  surface: (t: ColorTokens) => ViewStyle;
+  /** The surface-axis treatment (hairline / outline / floating card). */
+  surfaceContainer: (t: ColorTokens, surface: Surface) => ViewStyle;
+
+  /** The left cluster row (brand + links). */
+  leftGroup: (t: ColorTokens) => ViewStyle;
+  /** The brand wordmark type. */
+  brand: (t: ColorTokens) => TextStyle;
+  /** The links row. */
+  linksRow: (t: ColorTokens) => ViewStyle;
+  /** A nav link tile (padding + active fill). */
+  linkTile: (t: ColorTokens, active: boolean) => ViewStyle;
+  /** A nav link label (weight + active/inactive color). */
+  linkLabel: (t: ColorTokens, active: boolean) => TextStyle;
+
+  /** The right cluster row (action + avatar). */
+  rightGroup: (t: ColorTokens) => ViewStyle;
+}
+
+export interface NavbarProps {
+  /** Brand or product name shown at the left, in a semibold face. */
+  brand: string;
+  /** Ordered navigation link labels rendered in the middle row. */
+  links: string[];
+  /** Index of the active link (its label reads in the foreground color). */
+  active?: number;
+  /** Optional primary action; renders a <Button primary small> on the right. */
+  actionLabel?: string;
+  /** Called when the action button is pressed. */
+  onAction?: () => void;
+  /** Optional account initials/name; renders an <Avatar small> on the right. */
+  avatar?: string;
+  /** Called when a nav link is pressed, with its index. */
+  onSelect?: (index: number) => void;
+  // Surface (pick one; default is the flush bottom-hairline bar).
+  bordered?: boolean;
+  floating?: boolean;
+  children?: ReactNode;
+  /** Escape hatch for layout/positioning composition (width, margins). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Surface precedence when more than one is passed: first match wins.
+function surfaceOf(p: NavbarProps): Surface {
+  if (p.bordered) return "bordered";
+  if (p.floating) return "floating";
+  return "default";
+}
+
+/** Build a Navbar component from a platform skin. */
+export function createNavbar(skin: NavbarSkin) {
+  return function Navbar(props: NavbarProps) {
+    const { brand, links, active = 0, actionLabel, onAction, avatar, onSelect, style } = props;
+    const { tokens } = useTheme();
+    const surface = surfaceOf(props);
+
+    const container: StyleProp<ViewStyle> = [
+      skin.bar(tokens),
+      skin.surface(tokens),
+      skin.surfaceContainer(tokens, surface),
+      style,
+    ];
+
+    return (
+      <View style={container}>
+        <View style={skin.leftGroup(tokens)}>
+          <Text style={skin.brand(tokens)}>{brand}</Text>
+          <View style={skin.linksRow(tokens)}>
+            {links.map((link, index) => {
+              const isActive = index === active;
+              return (
+                <Pressable
+                  key={`${link}-${index}`}
+                  onPress={onSelect ? () => onSelect(index) : undefined}
+                  android_ripple={skin.ripple ? skin.ripple(tokens) : undefined}
+                  accessibilityRole="link"
+                  accessibilityState={{ selected: isActive }}
+                  style={({ pressed }) => [
+                    skin.linkTile(tokens, isActive),
+                    skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+                  ]}
+                >
+                  <Text style={skin.linkLabel(tokens, isActive)}>{link}</Text>
+                </Pressable>
+              );
+            })}
+          </View>
+        </View>
+        <View style={skin.rightGroup(tokens)}>
+          {actionLabel ? (
+            <Button primary small onPress={onAction}>
+              {actionLabel}
+            </Button>
+          ) : null}
+          {avatar ? <Avatar small name={avatar} /> : null}
+        </View>
+      </View>
+    );
+  };
+}

package/src/organisms/navbars/navbars.styles.ts

@@ -0,0 +1,251 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, shadow, alpha } from "../../style/index.js";
+import { type NavbarSkin } from "./navbars.shared.js";
+
+// Co-located Navbar skins, one per platform. The shell resolves the surface axis
+// (default / bordered / floating), the brand + link cluster, and the action +
+// avatar cluster; the skin supplies only the native SHAPE, sizing, label weight,
+// fill, separator, and press feedback. The BRAND survives on every platform (the
+// indigo `primary` token and the semantic tokens, never a platform default), so
+// each follows light/dark and the glass surface.
+//
+//   iOS (iOS 26+ / Liquid Glass navigation bar): a slim 44pt bar with a 1px
+//     hairline bottom separator (no heavy shadow); the brand reads as a ~17pt
+//     weight-600 SF title. Bar-button items are CIRCULAR tinted toolbar buttons
+//     (a translucent neutral `secondary` circle), the glyph/label tints the
+//     brand `primary`; the active item reads as a brand-FILLED circle. Press =
+//     opacity dim 0.8.
+//   Android (M3 top app bar): a ~56dp bar with a ~22sp weight-500 LEADING title;
+//     no hairline border, a flat `background` surface (soft elevation only when
+//     `floating`); nav links use a tonal `primary` active fill; press =
+//     android_ripple.
+//   Web: the established Canvas look (h-14 bar, bottom hairline / rounded outline
+//     / floating shadowed card), lifted verbatim from the original file.
+
+export type Surface = "default" | "bordered" | "floating";
+
+// =============================================================================
+// Web: the established Canvas look (lifted verbatim from the original file).
+// =============================================================================
+
+export const webSkin: NavbarSkin = {
+  // The original bar dims links on press (active:opacity-90); no ripple.
+  pressedOpacity: 0.9,
+  ripple: null,
+
+  // flex-row items-center justify-between h-14 px-4
+  bar() {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "space-between",
+      height: 56,
+      paddingHorizontal: 16,
+    };
+  },
+  // bg-background fill (token-driven, follows the scheme/glass surface).
+  surface(tokens) {
+    return { backgroundColor: tokens.background };
+  },
+  // The surface axis. default rests flush with a bottom hairline; bordered boxes
+  // it in a rounded outline; floating lifts it as a rounded, shadowed card.
+  surfaceContainer(tokens, surface) {
+    switch (surface) {
+      case "default":
+        return { borderBottomWidth: 1, borderColor: tokens.border };
+      case "bordered":
+        return { borderRadius: 8, borderWidth: 1, borderColor: tokens.border };
+      case "floating":
+        return { borderRadius: 8, borderWidth: 1, borderColor: tokens.border, ...shadow("md") };
+    }
+  },
+
+  // flex-row items-center gap-4
+  leftGroup() {
+    return { flexDirection: "row", alignItems: "center", gap: 16 };
+  },
+  // text-base font-semibold text-foreground
+  brand(tokens) {
+    return { fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground };
+  },
+  // flex-row items-center gap-1
+  linksRow() {
+    return { flexDirection: "row", alignItems: "center", gap: 4 };
+  },
+  // rounded-md px-3 py-1.5; the active tile fills bg-accent.
+  linkTile(tokens, active) {
+    return {
+      borderRadius: 6,
+      paddingHorizontal: 12,
+      paddingVertical: 6,
+      backgroundColor: active ? tokens.accent : "transparent",
+    };
+  },
+  // text-sm font-medium; active reads in the foreground, inactive in muted.
+  linkLabel(tokens, active) {
+    return {
+      fontSize: 14,
+      lineHeight: 20,
+      fontWeight: "500",
+      color: active ? tokens.foreground : tokens["muted-foreground"],
+    };
+  },
+
+  // flex-row items-center gap-2
+  rightGroup() {
+    return { flexDirection: "row", alignItems: "center", gap: 8 };
+  },
+};
+
+// =============================================================================
+// iOS (iOS 26+ / Liquid Glass): a slim navigation bar. A 44pt bar with a 1px
+// hairline bottom separator and no heavy shadow; the brand is a ~17pt weight-600
+// SF title. Bar-button items are CIRCULAR tinted toolbar buttons: a translucent
+// neutral `secondary` circle that the brand `primary` glyph/label sits on; the
+// active destination reads as a brand-FILLED circle. Press = opacity dim 0.8.
+// =============================================================================
+
+export const iosSkin: NavbarSkin = {
+  pressedOpacity: 0.8, // HIG: dim on press
+  ripple: null,
+
+  // Slim 44pt bar. iOS navigation bars are shorter than the Canvas web bar.
+  bar() {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "space-between",
+      height: 44,
+      paddingHorizontal: 16,
+    };
+  },
+  surface(tokens) {
+    return { backgroundColor: tokens.background };
+  },
+  // default: a 1px hairline bottom separator only (no shadow). bordered keeps the
+  // rounded outline; floating lifts a light card (HIG keeps elevation subtle).
+  surfaceContainer(tokens, surface) {
+    switch (surface) {
+      case "default":
+        return { borderBottomWidth: 1, borderColor: tokens.border };
+      case "bordered":
+        return { borderRadius: 10, borderWidth: 1, borderColor: tokens.border };
+      case "floating":
+        return { borderRadius: 10, borderWidth: 1, borderColor: tokens.border, ...shadow("sm") };
+    }
+  },
+
+  leftGroup() {
+    return { flexDirection: "row", alignItems: "center", gap: 16 };
+  },
+  // ~17pt SF title, weight 600 (iOS inline navigation title).
+  brand(tokens) {
+    return { fontSize: 17, lineHeight: 22, fontWeight: "600", color: tokens.foreground };
+  },
+  linksRow() {
+    return { flexDirection: "row", alignItems: "center", gap: 8 };
+  },
+  // iOS 26 bar-button items are CIRCULAR tinted toolbar buttons. Each chip is a
+  // 32pt fully-rounded pill on a translucent neutral `secondary` fill; the active
+  // destination flips to a solid brand `primary` fill (the filled-circle state).
+  // minWidth == height keeps a single short label reading as a true circle while
+  // a longer label grows the pill horizontally, matching the iOS capsule.
+  linkTile(tokens, active) {
+    return {
+      height: 32,
+      minWidth: 32,
+      borderRadius: 9999,
+      paddingHorizontal: 12,
+      alignItems: "center",
+      justifyContent: "center",
+      backgroundColor: active ? tokens.primary : alpha(tokens.secondary, 0.9),
+    };
+  },
+  // The glyph/label tints the brand `primary` on the neutral chip; on the active
+  // filled circle it reads in the contrasting `primary-foreground`.
+  linkLabel(tokens, active) {
+    return {
+      fontSize: 15,
+      lineHeight: 20,
+      fontWeight: "600",
+      textAlign: "center",
+      color: active ? tokens["primary-foreground"] : tokens.primary,
+    };
+  },
+
+  rightGroup() {
+    return { flexDirection: "row", alignItems: "center", gap: 8 };
+  },
+};
+
+// =============================================================================
+// Android (Material 3): a top app bar. A ~56dp bar with a ~22sp weight-500
+// LEADING title and no hairline border; the surface is flat `background` (soft
+// elevation only when floating). Nav links use a tonal `primary` active fill.
+// Press = android_ripple.
+// =============================================================================
+
+export const androidSkin: NavbarSkin = {
+  pressedOpacity: null, // Android uses a ripple instead
+  ripple: (tokens) => ({ color: alpha(tokens.primary, 0.12), borderless: false }),
+
+  // ~56dp small top app bar.
+  bar() {
+    return {
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "space-between",
+      height: 56,
+      paddingHorizontal: 16,
+    };
+  },
+  surface(tokens) {
+    return { backgroundColor: tokens.background };
+  },
+  // M3 small top app bar is borderless and flat at rest; we rely on the
+  // background fill. bordered/floating keep a container so those layouts still
+  // box (floating gets the M3 elevated-surface shadow on scroll).
+  surfaceContainer(tokens, surface) {
+    switch (surface) {
+      case "default":
+        return {}; // flat, no hairline; the background fill carries the bar
+      case "bordered":
+        return { borderRadius: 12, borderWidth: 1, borderColor: tokens.border };
+      case "floating":
+        return { borderRadius: 12, ...shadow("md") };
+    }
+  },
+
+  leftGroup() {
+    return { flexDirection: "row", alignItems: "center", gap: 16 };
+  },
+  // M3 titleLarge ~22sp, weight 500, leading.
+  brand(tokens) {
+    return { fontSize: 22, lineHeight: 28, fontWeight: "500", color: tokens.foreground };
+  },
+  linksRow() {
+    return { flexDirection: "row", alignItems: "center", gap: 4 };
+  },
+  // M3 active destination carries a tonal `primary` fill (secondaryContainer ~
+  // alpha(primary, .12)); inactive sits flat with a muted label.
+  linkTile(tokens, active) {
+    return {
+      borderRadius: 9999,
+      paddingHorizontal: 16,
+      paddingVertical: 6,
+      backgroundColor: active ? alpha(tokens.primary, 0.12) : "transparent",
+    };
+  },
+  linkLabel(tokens, active) {
+    return {
+      fontSize: 14,
+      lineHeight: 20,
+      fontWeight: "500",
+      color: active ? tokens.primary : tokens["muted-foreground"],
+    };
+  },
+
+  rightGroup() {
+    return { flexDirection: "row", alignItems: "center", gap: 8 };
+  },
+};

package/src/organisms/navbars/navbars.tsx

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

package/src/organisms/overlays/overlays.android.tsx

@@ -0,0 +1,6 @@
+import { createOverlay } from "./overlays.shared.js";
+import { androidSkin } from "./overlays.styles.js";
+
+// Material 3 bottom sheet Overlay. Metro resolves this file on Android; the docs import it for preview.
+export const Overlay = createOverlay(androidSkin);
+export type { OverlayProps } from "./overlays.shared.js";

package/src/organisms/overlays/overlays.ios.tsx

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

package/src/organisms/overlays/overlays.md

@@ -0,0 +1,123 @@
+# Overlays
+
+Floating surfaces: drawers, modals, popovers, toasts.
+
+## Usage
+
+```tsx
+<Overlay
+  trigger="Open panel"
+  title="Edit Identity"
+  description="Visible above the parent page so the user can compare."
+  drawer
+/>
+```
+
+## Variants
+
+### Surface - modal
+
+```tsx
+<Overlay
+  trigger="Open panel"
+  title="Edit Identity"
+  description="Visible above the parent page so the user can compare."
+  modal
+/>
+```
+
+### Surface - toast
+
+```tsx
+<Overlay
+  trigger="Open panel"
+  title="Edit Identity"
+  description="Visible above the parent page so the user can compare."
+  sheet
+/>
+```
+
+## Do & Don't
+
+### Drawer (SlideOver)
+
+**Do** — Slide the form in from the edge so the parent page stays visible beneath it.
+
+```tsx
+<Overlay open drawer title="Edit Identity" description="Visible above the parent page so the user can compare." doneLabel="Save" />
+```
+
+**Don't** — A centered, page-blocking modal for a routine edit hides the very record the user wants to reference.
+
+```tsx
+<Dialog open destructive title="Delete identity?" description="This cannot be undone." confirmLabel="Delete" cancelLabel="Cancel" />
+```
+
+### Modal (Confirm)
+
+**Do** — Name the verb (Delete) and flag destructive actions with the danger style.
+
+```tsx
+<Dialog open destructive title="Delete identity?" description="This cannot be undone." confirmLabel="Delete" cancelLabel="Cancel" />
+```
+
+**Don't** — Generic Yes/No on a default-styled button hides both the stakes and what is being confirmed.
+
+```tsx
+<Dialog open title="Delete identity?" confirmLabel="Yes" cancelLabel="No" />
+```
+
+### Toast
+
+**Do** — Keep toasts to passive confirmation of something already done; offer Undo, not a blocking choice.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "flex-start", justifyContent: "space-between", gap: 12, borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, paddingHorizontal: 16, paddingVertical: 12, ...shadow("lg") }}>
+  <View>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["popover-foreground"] }}>Identity deleted</Text>
+    <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>You can undo this for 10 seconds.</Text>
+  </View>
+  <Pressable style={({ pressed }) => [pressed ? { opacity: 0.7 } : null]}>
+    <Text style={{ color: tokens["muted-foreground"] }}>×</Text>
+  </Pressable>
+</View>
+```
+
+**Don't** — A toast that demands a decision can be auto-dismissed before the user acts, and steals focus from a transient surface.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "flex-start", justifyContent: "space-between", gap: 12, borderRadius: 8, borderWidth: 1, borderColor: alpha(tokens.destructive, 0.3), backgroundColor: tokens.popover, paddingHorizontal: 16, paddingVertical: 12, ...shadow("lg") }}>
+  <View>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["popover-foreground"] }}>Delete this identity?</Text>
+    <View style={{ marginTop: 8, flexDirection: "row", gap: 8 }}>
+      <Button outline small>Cancel</Button>
+      <Button destructive small>Delete</Button>
+    </View>
+  </View>
+  <Pressable style={({ pressed }) => [pressed ? { opacity: 0.7 } : null]}>
+    <Text style={{ color: tokens["muted-foreground"] }}>×</Text>
+  </Pressable>
+</View>
+```
+
+### Row menu
+
+**Do** — Collapse per-row actions behind a ··· trigger; keep Delete separated and danger-colored.
+
+```tsx
+<RowMenu open sectionLabel="Actions" items={[
+    { label: "Edit", icon: "✎" },
+    { label: "Duplicate", icon: "⧉" },
+    { label: "Delete", icon: "🗑", destructive: true, separatorBefore: true }
+  ]} />
+```
+
+**Don't** — Splaying every row action inline multiplies visual noise across every table row.
+
+```tsx
+<View style={{ flexDirection: "row", flexWrap: "wrap", gap: 8 }}>
+  <Button ghost small>Edit</Button>
+  <Button ghost small>Duplicate</Button>
+  <Button destructive small>Delete</Button>
+</View>
+```