@olympusoss/canvas 4.0.0 → 5.0.0

package/src/organisms/row-menu/row-menu.shared.tsx

@@ -0,0 +1,105 @@
+import { useState } from "react";
+import { View, Pressable, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { anchorLifted, type RowMenuItem, type RowMenuSkin } from "./row-menu.styles.js";
+
+// Shared RowMenu shell. The structure (the self-start anchor, the ⋯ icon-button
+// trigger, and the floating card of an optional section label plus the item
+// rows), the public boolean-prop API, the controlled/uncontrolled open state, the
+// select/close handlers, the overlay open-close behavior, the per-row destructive
+// tint, the link/action role, and accessibility all live here once. A platform
+// file supplies only its skin (the trigger and card shape/fill/shadow, whether
+// separators are drawn, the row text scale, and the press feedback mode) and
+// calls createRowMenu.
+//
+// Overlay note: a real row menu portals its card over the page and dismisses on
+// outside click. Here, for the docs playground (which has no portal/Modal), the
+// open menu renders INLINE directly below the trigger as a floating card so the
+// preview is never covered. The `open` boolean keeps it shown; this behavior is
+// identical across platforms.
+
+export type { RowMenuItem };
+
+export interface RowMenuProps {
+  /** The menu rows, top to bottom. */
+  items: RowMenuItem[];
+  /** Controlled open state. Omit for uncontrolled (the trigger toggles it). */
+  open?: boolean;
+  /** Fired when the open state changes. */
+  onOpenChange?: (open: boolean) => void;
+  /** Render rows as navigation links rather than action buttons. */
+  links?: boolean;
+  /** Show a muted section label heading the menu. */
+  sectionLabel?: string;
+  /** Fired with the selected item and its index when a row is pressed. */
+  onSelect?: (item: RowMenuItem, index: number) => void;
+  /** Escape hatch for layout/positioning composition. */
+  style?: StyleProp<ViewStyle>;
+}
+
+/** Build a RowMenu component from a platform skin. */
+export function createRowMenu(skin: RowMenuSkin) {
+  return function RowMenu(props: RowMenuProps) {
+    const { items, links = false, sectionLabel, onSelect, onOpenChange, style } = props;
+    const { tokens, dark } = useTheme();
+    // Uncontrolled by default: the ⋯ trigger toggles the menu (closed), a select
+    // closes it; a controlled `open` prop overrides this.
+    const [internalOpen, setInternalOpen] = useState(false);
+    const open = props.open ?? internalOpen;
+    const setOpen = (next: boolean) => {
+      if (props.open === undefined) setInternalOpen(next);
+      onOpenChange?.(next);
+    };
+
+    const ripple = skin.ripple ? skin.ripple(tokens) : undefined;
+
+    return (
+      // self-start keeps the trigger from stretching; relative anchors the menu.
+      <View style={[skin.anchor, open ? anchorLifted : null, style]}>
+        <Pressable
+          style={({ pressed }) => [
+            skin.trigger,
+            // Android ripples; iOS dims via opacity; web tints the fill.
+            skin.triggerPressedOpacity != null && pressed ? { opacity: skin.triggerPressedOpacity } : null,
+            skin.ripple == null && skin.triggerPressedOpacity == null && pressed
+              ? skin.triggerPressed(tokens)
+              : null,
+          ]}
+          onPress={() => setOpen(!open)}
+          android_ripple={ripple}
+          accessibilityRole="button"
+        >
+          <Text style={skin.triggerGlyph(tokens)}>⋯</Text>
+        </Pressable>
+
+        {open ? (
+          <View style={skin.menuCard(tokens)}>
+            {sectionLabel ? <Text style={skin.menuLabel(tokens)}>{sectionLabel}</Text> : null}
+            {items.map((item, index) => (
+              <View key={`${item.label}-${index}`}>
+                {item.separatorBefore && skin.showSeparators ? <View style={skin.separator(tokens)} /> : null}
+                <Pressable
+                  style={({ pressed }) => [
+                    skin.itemRow,
+                    // Web/iOS tint the row on press here; Android uses the ripple instead.
+                    skin.ripple == null && pressed ? skin.itemPressed(tokens) : null,
+                  ]}
+                  onPress={() => {
+                    onSelect?.(item, index);
+                    setOpen(false);
+                  }}
+                  android_ripple={ripple}
+                  accessibilityRole={links ? "link" : "menuitem"}
+                >
+                  {item.icon ? (
+                    <Text style={[skin.rowTextSize, skin.rowTextColor(item, links, tokens, dark)]}>{item.icon}</Text>
+                  ) : null}
+                  <Text style={[skin.rowTextSize, skin.rowTextColor(item, links, tokens, dark)]}>{item.label}</Text>
+                </Pressable>
+              </View>
+            ))}
+          </View>
+        ) : null}
+      </View>
+    );
+  };
+}

package/src/organisms/row-menu/row-menu.styles.ts

@@ -0,0 +1,262 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, palette, shadow, alpha } from "../../style/index.js";
+
+// Co-located RowMenu skins, one per platform, all driven by the brand tokens
+// (passed in from useTheme so they follow light/dark and the glass surface, since
+// tokens.popover is swapped translucent at the theming level). The BRAND survives
+// on every platform (the destructive red is a fixed Tailwind hue, the trigger and
+// rows take the brand foreground/popover tokens, never a platform default); only
+// the native SHAPE, sizing, structure, and interaction feedback change per OS:
+//   iOS (HIG context menu): the floating card is a rounded popover (~13 radius)
+//     over `popover` with a soft shadow, NO border; rows are ~44pt tall with a
+//     LEADING icon, groups split by hairline `separator` lines; destructive rows
+//     are red; pressed = a `secondary` highlight (no ripple). The ⋯ trigger dims
+//     to ~0.8 opacity on press.
+//   Android (Material 3 menu): the card is an elevated surface (4 radius,
+//     `popover`, soft shadow), NO border and NO separators between rows; rows are
+//     ~48dp tall with a LEADING icon; press = an android_ripple (alpha(primary,
+//     0.12) state layer). Destructive rows are red. The ⋯ trigger uses the same
+//     ripple.
+//   Web: the established Canvas look (the current row menu, lifted verbatim) — a
+//     bordered popover card (6 radius, `border`, shadow-lg, min-w 180), rounded-sm
+//     rows (px-2 py-1.5), hairline `border` separators, destructive red, and an
+//     `accent` fill on press for both the trigger and the rows.
+
+export interface RowMenuItem {
+  label: string;
+  /** Optional leading glyph rendered before the label (a single character). */
+  icon?: string;
+  /** Red-tinted row for destructive actions (e.g. Delete). */
+  destructive?: boolean;
+  /** Draw a hairline separator above this row to start a new group. */
+  separatorBefore?: boolean;
+}
+
+// The contract a platform skin fulfills. The shell owns the structure (anchor +
+// ⋯ trigger + floating card of section label and item rows) and the open/close
+// state; the skin maps tokens and the active row state to RN style objects, and
+// declares its press-feedback mode (iOS/web dim or tint inline, Android ripples).
+export interface RowMenuSkin {
+  /** The relative anchor: keeps the trigger from stretching, positions the card. */
+  anchor: ViewStyle;
+  /** The ⋯ icon-button surface (square, centered, platform radius). */
+  trigger: ViewStyle;
+  /** The ⋯ glyph text. */
+  triggerGlyph: (t: ColorTokens) => TextStyle;
+  /** The fill applied to the trigger on press (web/iOS tint via this; Android ripples). */
+  triggerPressed: (t: ColorTokens) => ViewStyle;
+  /** The floating menu card surface (shape, fill, border, shadow, placement). */
+  menuCard: (t: ColorTokens) => ViewStyle;
+  /** The muted section heading above the rows. */
+  menuLabel: (t: ColorTokens) => TextStyle;
+  /** A single action/link row layout. */
+  itemRow: ViewStyle;
+  /** The fill applied to a row on press (web/iOS tint via this; Android ripples). */
+  itemPressed: (t: ColorTokens) => ViewStyle;
+  /** Whether this platform draws hairline separators between groups (iOS/web yes, Android no). */
+  showSeparators: boolean;
+  /** The hairline separator above a row that sets `separatorBefore`. */
+  separator: (t: ColorTokens) => ViewStyle;
+  /** The shared icon/label text size, so they line up in a row. */
+  rowTextSize: TextStyle;
+  /** The per-row text color (destructive red, link foreground, action popover fg). */
+  rowTextColor: (item: RowMenuItem, links: boolean, t: ColorTokens, dark: boolean) => TextStyle;
+  /** iOS/web dim the trigger on press; Android ripples instead (null). */
+  triggerPressedOpacity: number | null;
+  /** Android ripple over the trigger and rows; null on iOS/web. */
+  ripple: ((t: ColorTokens) => { color: string; borderless: boolean }) | null;
+}
+
+// When the menu is open, the anchor is lifted into its own stacking context above
+// sibling content. react-native-web gives every positioned View an implicit
+// stacking context, so the card's own `zIndex` is scoped INSIDE the `relative`
+// anchor and cannot rise above a later sibling. Raising the anchor's zIndex while
+// open lifts the whole control — trigger and card together — above everything
+// painted after it. Shared across platforms (the anchor shape is identical).
+export const anchorLifted: ViewStyle = { zIndex: 50 };
+
+// ---------- Web: the established Canvas look (lifted verbatim) ----------
+// A bordered popover card (min-w 180, 6 radius, 1px `border`, `popover` fill,
+// p-1, shadow-lg) placed inline below the trigger; rounded-sm rows (px-2 py-1.5)
+// with a 2-radius corner; hairline `border` separators split groups; destructive
+// rows are red-600/red-400; the trigger and rows tint with `accent` on press.
+export const webSkin: RowMenuSkin = {
+  anchor: { position: "relative", alignSelf: "flex-start" },
+  trigger: {
+    width: 32,
+    height: 32,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 6,
+  },
+  triggerGlyph: (t) => ({ fontSize: 16, lineHeight: 24, color: t.foreground }),
+  triggerPressed: (t) => ({ backgroundColor: t.accent }),
+  menuCard: (t) => ({
+    minWidth: 180,
+    borderRadius: 6,
+    borderWidth: 1,
+    borderColor: t.border,
+    backgroundColor: t.popover,
+    padding: 4,
+    ...shadow("lg"),
+    position: "absolute",
+    top: "100%",
+    left: 0,
+    zIndex: 50,
+    marginTop: 4,
+  }),
+  menuLabel: (t) => ({
+    paddingHorizontal: 8,
+    paddingVertical: 6,
+    fontSize: 12,
+    lineHeight: 16,
+    fontWeight: "500",
+    color: t["muted-foreground"],
+  }),
+  itemRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    borderRadius: 2,
+    paddingHorizontal: 8,
+    paddingVertical: 6,
+  },
+  itemPressed: (t) => ({ backgroundColor: t.accent }),
+  showSeparators: true,
+  separator: (t) => ({ marginVertical: 4, height: 1, backgroundColor: t.border }),
+  rowTextSize: { fontSize: 14, lineHeight: 20 },
+  rowTextColor: (item, links, t, dark) => {
+    if (item.destructive) return { color: dark ? palette["red-400"] : palette["red-600"] };
+    return { color: links ? t.foreground : t["popover-foreground"] };
+  },
+  triggerPressedOpacity: null,
+  ripple: null,
+};
+
+// ---------- iOS 27 (Liquid Glass context menu): big-radius popover, leading icons, hairlines ----------
+// Apple's iOS 26+/iOS 27 context menu: a floating, deeply rounded card (~28pt
+// continuous corner, up from the old ~13pt) over `popover` with a soft shadow and
+// NO border; rows are ~44pt tall with comfortable horizontal padding and a LEADING
+// glyph; groups are split by full-bleed hairline separators; a destructive row is
+// red; the pressed row tints with the `secondary` system fill (not a ripple). The
+// ⋯ trigger dims to ~0.8 opacity on press. The larger radius is what reads as the
+// modern Liquid Glass menu; the rest of the structure (leading icons, hairlines,
+// destructive red, section titles) is unchanged from the HIG layout.
+const IOS_RADIUS = 28;
+export const iosSkin: RowMenuSkin = {
+  anchor: { position: "relative", alignSelf: "flex-start" },
+  trigger: {
+    width: 32,
+    height: 32,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 8,
+  },
+  triggerGlyph: (t) => ({ fontSize: 17, lineHeight: 22, color: t.foreground }),
+  // iOS dims the whole trigger on press (pressedOpacity); no fill tint.
+  triggerPressed: () => ({}),
+  menuCard: (t) => ({
+    minWidth: 250,
+    borderRadius: IOS_RADIUS,
+    backgroundColor: t.popover,
+    // The deep corner clips the first/last row fills cleanly; vertical inset keeps
+    // the top/bottom rows clear of the rounded corners.
+    paddingVertical: 6,
+    overflow: "hidden",
+    ...shadow("lg"),
+    position: "absolute",
+    top: "100%",
+    left: 0,
+    zIndex: 50,
+    marginTop: 8,
+  }),
+  menuLabel: (t) => ({
+    paddingHorizontal: 16,
+    paddingTop: 10,
+    paddingBottom: 6,
+    fontSize: 13,
+    lineHeight: 18,
+    fontWeight: "600",
+    color: t["muted-foreground"],
+  }),
+  itemRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+    paddingHorizontal: 16,
+    paddingVertical: 11,
+    minHeight: 44,
+  },
+  // The selected/pressed row uses the iOS system highlight (the `secondary` fill).
+  itemPressed: (t) => ({ backgroundColor: t.secondary }),
+  showSeparators: true,
+  // A full-bleed hairline divider (no horizontal inset) splitting menu groups.
+  separator: (t) => ({ height: 1, backgroundColor: t.border, marginVertical: 4 }),
+  rowTextSize: { fontSize: 17, lineHeight: 22 },
+  rowTextColor: (item, links, t, dark) => {
+    if (item.destructive) return { color: dark ? palette["red-400"] : palette["red-600"] };
+    return { color: links ? t.foreground : t["popover-foreground"] };
+  },
+  triggerPressedOpacity: 0.8,
+  ripple: null,
+};
+
+// ---------- Android (Material 3 menu): elevated surface, ripple rows, no dividers ----------
+// M3 dropdown/context menu: an elevated surface (4dp radius, `popover` fill, soft
+// shadow) with NO border; rows are ~48dp tall with a LEADING icon and a brand
+// ripple on press (alpha(primary, 0.12) state layer); M3 menus do NOT draw
+// dividers between every group, so separators are suppressed. Destructive rows
+// are red. The ⋯ trigger shares the ripple.
+const ANDROID_RADIUS = 4;
+export const androidSkin: RowMenuSkin = {
+  anchor: { position: "relative", alignSelf: "flex-start" },
+  trigger: {
+    width: 40,
+    height: 40,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 20,
+  },
+  triggerGlyph: (t) => ({ fontSize: 20, lineHeight: 24, color: t.foreground }),
+  // Android tints the trigger via the ripple, not a fill.
+  triggerPressed: () => ({}),
+  menuCard: (t) => ({
+    minWidth: 200,
+    borderRadius: ANDROID_RADIUS,
+    backgroundColor: t.popover,
+    paddingVertical: 8,
+    ...shadow("md"),
+    position: "absolute",
+    top: "100%",
+    left: 0,
+    zIndex: 50,
+    marginTop: 2,
+  }),
+  menuLabel: (t) => ({
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+    fontSize: 12,
+    lineHeight: 16,
+    fontWeight: "500",
+    color: t["muted-foreground"],
+  }),
+  itemRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+    paddingHorizontal: 16,
+    paddingVertical: 12,
+    minHeight: 48,
+  },
+  // The M3 pressed state layer: the brand primary at ~12% alpha (the ripple tint).
+  itemPressed: (t) => ({ backgroundColor: alpha(t.primary, 0.12) }),
+  showSeparators: false,
+  separator: (t) => ({ height: 1, backgroundColor: t.border, marginVertical: 4 }),
+  rowTextSize: { fontSize: 16, lineHeight: 24 },
+  rowTextColor: (item, links, t, dark) => {
+    if (item.destructive) return { color: dark ? palette["red-400"] : palette["red-600"] };
+    return { color: links ? t.foreground : t["popover-foreground"] };
+  },
+  triggerPressedOpacity: null,
+  ripple: (t) => ({ color: alpha(t.primary, 0.12), borderless: false }),
+};

package/src/organisms/row-menu/row-menu.tsx

@@ -0,0 +1,6 @@
+import { createRowMenu } from "./row-menu.shared.js";
+import { webSkin } from "./row-menu.styles.js";
+
+// Web RowMenu (the base; Metro falls back to it on native, web bundlers resolve it).
+export const RowMenu = createRowMenu(webSkin);
+export type { RowMenuProps, RowMenuItem } from "./row-menu.shared.js";

package/src/organisms/sidebar/sidebar.android.tsx

@@ -0,0 +1,6 @@
+import { createSidebar } from "./sidebar.shared.js";
+import { androidSkin } from "./sidebar.styles.js";
+
+// Material 3 (navigation drawer) Sidebar. Metro resolves this file on Android; the docs import it for preview.
+export const Sidebar = createSidebar(androidSkin);
+export type { SidebarProps, SidebarItem, SidebarSection } from "./sidebar.shared.js";

package/src/organisms/sidebar/sidebar.ios.tsx

@@ -0,0 +1,6 @@
+import { createSidebar } from "./sidebar.shared.js";
+import { iosSkin } from "./sidebar.styles.js";
+
+// iOS (HIG sidebar) Sidebar. Metro resolves this file on iOS; the docs import it for preview.
+export const Sidebar = createSidebar(iosSkin);
+export type { SidebarProps, SidebarItem, SidebarSection } from "./sidebar.shared.js";

package/src/organisms/sidebar/sidebar.md

@@ -0,0 +1,188 @@
+# Navigation
+
+Sidebar + Topbar + breadcrumbs + page header. The sidebar you see on the left of this very page is the production sidebar: same component, same width, same drawer behavior.
+
+## Usage
+
+```tsx
+<Sidebar
+  active="Dashboard"
+  sections={[
+    { title: "Main", items: [
+      { label: "Dashboard", icon: "◉" },
+      { label: "Users", icon: "○", badge: "12" },
+      { label: "Settings", icon: "◇" }
+    ] },
+    { title: "Reports", items: [
+      { label: "Analytics", icon: "△" }
+    ] }
+  ]}
+/>
+```
+
+## Do & Don't
+
+### Sidebar
+
+**Do** — Exactly one item carries the accent background; clicking moves it so the active page is always unambiguous.
+
+```tsx
+<Sidebar bordered active="Dashboard" sections={[
+    { title: "Main", items: [
+      { label: "Dashboard", icon: "◉" },
+      { label: "Users", icon: "○", badge: "12" },
+      { label: "Settings", icon: "◇" }
+    ] }
+  ]} />
+```
+
+**Don't** — Click an item: two rows wearing the active background means the nav can't tell you which page you're on.
+
+```tsx
+<View style={{ width: 240, overflow: "hidden", borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.background }}>
+  <View style={{ height: 56, flexDirection: "row", alignItems: "center", borderBottomWidth: 1, borderColor: tokens.border, paddingHorizontal: 16 }}>
+    <Text style={{ fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground }}>Acme</Text>
+  </View>
+  <View style={{ gap: 4, padding: 8 }}>
+    <Pressable style={{ flexDirection: "row", alignItems: "center", gap: 12, borderRadius: 6, backgroundColor: tokens.accent, paddingHorizontal: 12, paddingVertical: 8 }}>
+      <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Dashboard</Text>
+    </Pressable>
+    <Pressable style={{ flexDirection: "row", alignItems: "center", gap: 12, borderRadius: 6, backgroundColor: tokens.accent, paddingHorizontal: 12, paddingVertical: 8 }}>
+      <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Users</Text>
+    </Pressable>
+    <Pressable style={{ flexDirection: "row", alignItems: "center", gap: 12, borderRadius: 6, paddingHorizontal: 12, paddingVertical: 8 }}>
+      <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Settings</Text>
+    </Pressable>
+  </View>
+</View>
+```
+
+### Topbar
+
+**Do** — Push utilities to the right, keep one primary button, and demote the rest to ghost so the New action leads.
+
+```tsx
+<View style={{ height: 56, width: 420, maxWidth: "100%", flexDirection: "row", alignItems: "center", borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, paddingHorizontal: 16 }}>
+  <Text style={{ fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground }}>Dashboard</Text>
+  <View style={{ marginLeft: "auto", flexDirection: "row", gap: 8 }}>
+    <Button ghost small>Search</Button>
+    <Button primary small>New</Button>
+  </View>
+</View>
+```
+
+**Don't** — Four solid primary buttons crammed left-to-right give the topbar no focal action and no breathing room.
+
+```tsx
+<View style={{ height: 56, width: 420, maxWidth: "100%", flexDirection: "row", alignItems: "center", gap: 8, borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.card, paddingHorizontal: 16 }}>
+  <Text style={{ fontSize: 16, lineHeight: 24, fontWeight: "600", color: tokens.foreground }}>Dashboard</Text>
+  <Button primary small>Search</Button>
+  <Button primary small>Filter</Button>
+  <Button primary small>Export</Button>
+  <Button primary small>New</Button>
+</View>
+```
+
+### Page header
+
+**Do** — Page-header titles are 20-22px semibold: clearly the page label, never larger than the topbar brand.
+
+```tsx
+<View style={{ width: 420, maxWidth: "100%" }}>
+  <Typography h4>Users</Typography>
+  <Typography muted style={{ marginTop: 4 }}>Manage your team members.</Typography>
+</View>
+```
+
+**Don't** — A 36px display heading on the page body competes with the topbar and screams louder than the content beneath it.
+
+```tsx
+<View style={{ width: 420, maxWidth: "100%" }}>
+  <Typography h1>Users</Typography>
+  <Typography muted style={{ marginTop: 4 }}>Manage your team members.</Typography>
+</View>
+```
+
+### Breadcrumbs
+
+**Do** — The final crumb is plain current-page text, not a link: it marks where you are, not where you can go.
+
+```tsx
+<Breadcrumb slash items={["Home", "Team", "Rachel Chen"]} />
+```
+
+**Don't** — Making the last crumb a link implies the current page is somewhere else to navigate to.
+
+```tsx
+<View style={{ flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: 6 }}>
+  <Pressable style={({ pressed }) => [pressed ? { opacity: 0.7 } : null]}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Home</Text>
+  </Pressable>
+  <Text style={{ fontSize: 14, lineHeight: 20, color: alpha(tokens["muted-foreground"], 0.6) }}>/</Text>
+  <Pressable style={({ pressed }) => [pressed ? { opacity: 0.7 } : null]}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Team</Text>
+  </Pressable>
+  <Text style={{ fontSize: 14, lineHeight: 20, color: alpha(tokens["muted-foreground"], 0.6) }}>/</Text>
+  <Pressable style={({ pressed }) => [pressed ? { opacity: 0.7 } : null]}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Rachel Chen</Text>
+  </Pressable>
+</View>
+```
+
+### Tabs
+
+**Do** — Click a tab: exactly one carries the primary underline so the active facet is always singular.
+
+```tsx
+<Tabs underline active={0} tabs={["Overview", "Sessions", "Audit log"]} />
+```
+
+**Don't** — Two underlined tabs at once breaks the one-active-facet contract and hides which view you're reading.
+
+```tsx
+<View style={{ width: 420, maxWidth: "100%", flexDirection: "row", alignItems: "center", borderBottomWidth: 1, borderColor: tokens.border }}>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", paddingHorizontal: 16, paddingVertical: 10 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Overview</Text>
+    <View style={{ position: "absolute", bottom: 0, left: 0, right: 0, height: 2, borderRadius: 9999, backgroundColor: tokens.primary }} />
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", paddingHorizontal: 16, paddingVertical: 10 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens.foreground }}>Sessions</Text>
+    <View style={{ position: "absolute", bottom: 0, left: 0, right: 0, height: 2, borderRadius: 9999, backgroundColor: tokens.primary }} />
+  </Pressable>
+  <Pressable style={{ flexDirection: "row", alignItems: "center", justifyContent: "center", paddingHorizontal: 16, paddingVertical: 10 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["muted-foreground"] }}>Audit log</Text>
+    <View style={{ position: "absolute", bottom: 0, left: 0, right: 0, height: 2, borderRadius: 9999, backgroundColor: "transparent" }} />
+  </Pressable>
+</View>
+```
+
+### Command palette
+
+**Do** — A search icon and esc hint signal input, and a single highlighted row shows exactly what Enter will run.
+
+```tsx
+<Command open active={0} placeholder="Type a command or search..." groups={[
+    { heading: "Actions", items: [
+      { label: "Create identity", shortcut: "C" },
+      { label: "Invite teammate" }
+    ] }
+  ]} />
+```
+
+**Don't** — No search affordance and two highlighted rows: nothing tells you to type or which result Enter will run.
+
+```tsx
+<View style={{ width: 420, maxWidth: 480, overflow: "hidden", borderRadius: 8, borderWidth: 1, borderColor: tokens.border, backgroundColor: tokens.popover, ...shadow("xl") }}>
+  <View style={{ flexDirection: "row", alignItems: "center", gap: 8, borderBottomWidth: 1, borderColor: tokens.border, paddingHorizontal: 12, paddingVertical: 12 }}>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>Type a command or search...</Text>
+  </View>
+  <View style={{ padding: 6 }}>
+    <Pressable style={{ flexDirection: "row", alignItems: "center", gap: 12, borderRadius: 6, backgroundColor: tokens.accent, paddingHorizontal: 12, paddingVertical: 8 }}>
+      <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", fontSize: 14, lineHeight: 20, color: tokens.foreground }}>Create identity</Text>
+    </Pressable>
+    <Pressable style={{ flexDirection: "row", alignItems: "center", gap: 12, borderRadius: 6, backgroundColor: tokens.accent, paddingHorizontal: 12, paddingVertical: 8 }}>
+      <Text style={{ flexGrow: 1, flexShrink: 1, flexBasis: "0%", fontSize: 14, lineHeight: 20, color: tokens.foreground }}>Invite teammate</Text>
+    </Pressable>
+  </View>
+</View>
+```