@olympusoss/canvas 4.0.0 → 5.0.0

package/src/molecules/alert-dialog/alert-dialog.shared.tsx

@@ -0,0 +1,187 @@
+import { useState } from "react";
+import { View, Text, Pressable, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Button } from "../../atoms/button/button.js";
+import { Input } from "../../atoms/input/input.js";
+import * as s from "./alert-dialog.styles.js";
+import { type Width, type AlertDialogSkin } from "./alert-dialog.styles.js";
+
+// Shared AlertDialog shell. The structure (optional trigger + dim backdrop +
+// centered card + title/description + optional confirmation field + action row),
+// the uncontrolled/controlled open state, the width/destructive precedence, and
+// the confirm/cancel handlers live here once; a platform file supplies only its
+// skin (card shape, type, action layout, press feedback) and calls
+// createAlertDialog.
+//
+// AlertDialog: a terse yes/no confirmation modal, the compact sibling of Dialog.
+// It poses a question (title), an optional short description, and an action row of
+// a Cancel plus a single confirm. Reserve it for decisions that must block the
+// rest of the app, especially irreversible ones (pass `destructive` to render the
+// confirm as a red, destructive action).
+//
+// In the docs preview the overlay is rendered INLINE: a contained dim backdrop
+// View wraps the centered card, so it reads as a modal within the preview area
+// rather than a full-screen portal that would cover it.
+//
+// Boolean-prop API: one boolean per option, grouped by axis, first-match
+// precedence within an axis (mirrors Button's intentOf). Axes:
+//
+// - Width: `narrow` < `small` < (default medium) < `large`, the panel max-width.
+//   Pass at most one; first match wins in that order (narrow, small, large).
+// - Confirm intent: `destructive` renders the confirm action as a destructive
+//   action (for an irreversible action); omit for the default primary confirm.
+
+export interface AlertDialogProps {
+  // Content (strings).
+  title?: string;
+  description?: string;
+  // Trigger button label. When set, the dialog renders the button and opens
+  // itself on press (uncontrolled). Omit when you drive `open` yourself.
+  trigger?: string;
+  // Action labels.
+  confirmLabel?: string;
+  cancelLabel?: string;
+  // Controlled open state. Omit for uncontrolled (the trigger opens it).
+  open?: boolean;
+  // Fired when the open state changes (trigger press, confirm, cancel).
+  onOpenChange?: (open: boolean) => void;
+  // Width (pick one; default is the medium panel).
+  narrow?: boolean;
+  small?: boolean;
+  large?: boolean;
+  // Body: render a confirmation field ("Type DELETE to confirm") in the panel.
+  withInput?: boolean;
+  // Confirm intent (default is a primary confirm).
+  destructive?: boolean;
+  // Action handlers.
+  onConfirm?: () => void;
+  onCancel?: () => void;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Width precedence when more than one is passed: first match wins.
+function widthOf(p: AlertDialogProps): Width {
+  if (p.narrow) return "narrow";
+  if (p.small) return "small";
+  if (p.large) return "large";
+  return "medium";
+}
+
+/** Build an AlertDialog component from a platform skin. */
+export function createAlertDialog(skin: AlertDialogSkin) {
+  return function AlertDialog(props: AlertDialogProps) {
+    const {
+      title,
+      description,
+      confirmLabel = "Continue",
+      cancelLabel = "Cancel",
+      trigger,
+      open: openProp,
+      onOpenChange,
+      withInput,
+      destructive,
+      onConfirm,
+      onCancel,
+      style,
+    } = props;
+
+    const { tokens } = useTheme();
+
+    // Uncontrolled by default: the trigger opens the dialog and an action closes
+    // it; a controlled `open` prop overrides this.
+    const [internalOpen, setInternalOpen] = useState(false);
+    const open = openProp ?? internalOpen;
+    const setOpen = (next: boolean) => {
+      if (openProp === undefined) setInternalOpen(next);
+      onOpenChange?.(next);
+    };
+
+    const width = widthOf(props);
+
+    const handleConfirm = () => {
+      onConfirm?.();
+      setOpen(false);
+    };
+    const handleCancel = () => {
+      onCancel?.();
+      setOpen(false);
+    };
+
+    // The action row. iOS renders two capsule buttons side by side (no divider)
+    // drawn by the skin; web/Android render a right-aligned row of the shell's
+    // Buttons.
+    const ripple = skin.ripple ? skin.ripple(tokens) : undefined;
+    const actionRow =
+      skin.actionLayout === "capsule" ? (
+        <View style={skin.capsuleRow!}>
+          <Pressable
+            onPress={handleCancel}
+            accessibilityRole="button"
+            android_ripple={ripple}
+            style={({ pressed }) => [
+              skin.capsuleCell!,
+              skin.cancelFill!(tokens),
+              skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+            ]}
+          >
+            <Text style={skin.cancelLabelStyle!(tokens)}>{cancelLabel}</Text>
+          </Pressable>
+          <Pressable
+            onPress={handleConfirm}
+            accessibilityRole="button"
+            android_ripple={ripple}
+            style={({ pressed }) => [
+              skin.capsuleCell!,
+              skin.confirmFill!(tokens, !!destructive),
+              skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+            ]}
+          >
+            <Text style={skin.confirmLabelStyle!(tokens, !!destructive)}>{confirmLabel}</Text>
+          </Pressable>
+        </View>
+      ) : (
+        <View style={skin.actions}>
+          <Button {...skin.cancelButton} small={skin.buttonSmall} onPress={handleCancel}>
+            {cancelLabel}
+          </Button>
+          {destructive ? (
+            <Button destructive small={skin.buttonSmall} onPress={handleConfirm}>
+              {confirmLabel}
+            </Button>
+          ) : (
+            <Button primary small={skin.buttonSmall} onPress={handleConfirm}>
+              {confirmLabel}
+            </Button>
+          )}
+        </View>
+      );
+
+    // Optional trigger button plus the modal. The modal is a contained dim
+    // backdrop: a centered, rounded scrim with presence in the preview (explicit
+    // minHeight) so the card reads as a modal within the area.
+    return (
+      <View style={s.root}>
+        {trigger != null ? (
+          <Button outline small onPress={() => setOpen(true)}>
+            {trigger}
+          </Button>
+        ) : null}
+        {open ? (
+          <View style={[skin.backdrop, trigger != null ? s.triggerGap : null, { minHeight: 200 }]}>
+            <View style={[s.cardBase, skin.card(tokens), s.panelWidth[width], style]}>
+              {title != null ? <Text style={skin.title(tokens)}>{title}</Text> : null}
+              {description != null ? <Text style={skin.description(tokens)}>{description}</Text> : null}
+              {withInput ? (
+                <View style={skin.inputBlock}>
+                  <Text style={skin.inputLabel(tokens)}>Type DELETE to confirm</Text>
+                  <Input placeholder="DELETE" />
+                </View>
+              ) : null}
+              {actionRow}
+            </View>
+          </View>
+        ) : null}
+      </View>
+    );
+  };
+}

package/src/molecules/alert-dialog/alert-dialog.styles.ts

@@ -0,0 +1,248 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens, shadow, alpha } from "../../style/index.js";
+
+// Co-located AlertDialog skins, one per platform, all driven by the brand tokens
+// (passed in from useTheme so they follow light/dark and read as glass when
+// tokens.popover is swapped translucent at the theming level). The BRAND survives
+// on every platform (the `primary` confirm and the `destructive` red); only the
+// native SHAPE, sizing, title alignment, action layout, and press feedback change
+// per OS:
+//   iOS (iOS 27 / Liquid Glass alert): a rounded card (~28 radius, `popover`
+//     fill, soft shadow, no border), a LEFT-aligned bold title and a left-aligned
+//     `muted-foreground` message; exactly two actions rendered as two CAPSULES
+//     side by side (no divider) — a gray Cancel capsule (`secondary` fill) and a
+//     filled Confirm capsule (`primary`, or `destructive` when destructive) with
+//     a white label. Press = opacity dim (~0.85).
+//   Android (Material 3 AlertDialog): an elevated surface (28 radius, `popover`
+//     fill, soft shadow), a LEFT-aligned title and left-aligned body; two M3 TEXT
+//     buttons bottom-right (Cancel then Confirm/Delete), the confirm tinted with
+//     the brand `primary` and a destructive confirm in the `destructive` red.
+//     Press = android_ripple (brand state layer).
+//   Web: the established Canvas look (the current alert-dialog, lifted verbatim) —
+//     a bordered, dim-backed card (8 radius, 1px `border`, `popover` fill,
+//     shadow-xl, padding 24), a left-aligned 16pt/600 title and 14pt
+//     `muted-foreground` description, with a right-aligned action row of an
+//     `outline` Cancel Button plus a `primary`/`destructive` confirm Button.
+
+export type Width = "narrow" | "small" | "medium" | "large";
+
+// Panel max-width per width axis (mirroring Tailwind's max-w-xs..lg). Shared by
+// every platform; the native skins narrow the medium/large footprint a touch but
+// the axis mapping is one source of truth.
+export const panelWidth: Record<Width, ViewStyle> = {
+  narrow: { maxWidth: 320 },
+  small: { maxWidth: 384 },
+  medium: { maxWidth: 448 },
+  large: { maxWidth: 512 },
+};
+
+// How the action row is structured. "buttons" renders the shell's Button-based
+// right-aligned row (web/Android); "capsule" renders the iOS side-by-side pair of
+// pill buttons drawn by the skin's own action styles (no divider).
+export type ActionLayout = "buttons" | "capsule";
+
+// The contract a platform skin fulfills. The shell renders the wrapper, the dim
+// backdrop, the card, the title/description, the optional confirmation field, and
+// the action row; the skin maps the active platform's shape/fill/sizing/type/
+// feedback onto each piece.
+export interface AlertDialogSkin {
+  /** The contained dim scrim that centers the card within the preview area. */
+  backdrop: ViewStyle;
+  /** The card base: shape, border (or lack of), padding, shadow. tokens drive fill. */
+  card: (t: ColorTokens) => ViewStyle;
+  /** Title type + alignment (centered on iOS, left on Android/web). */
+  title: (t: ColorTokens) => TextStyle;
+  /** Description type + alignment + color. */
+  description: (t: ColorTokens) => TextStyle;
+  /** The confirmation-field block container ("Type DELETE to confirm" + input). */
+  inputBlock: ViewStyle;
+  /** The confirmation-field label. */
+  inputLabel: (t: ColorTokens) => TextStyle;
+  /** Which action structure the shell renders. */
+  actionLayout: ActionLayout;
+  // --- "buttons" layout (web/Android): a right-aligned row of shell Buttons ----
+  /** The right-aligned Button row container (the "buttons" layout). */
+  actions: ViewStyle;
+  /** The size prop passed to the shell's Cancel/Confirm Buttons. */
+  buttonSmall: boolean;
+  /** The intent props for the Cancel Button (web = outline; Android = ghost/text). */
+  cancelButton: { outline?: boolean; ghost?: boolean };
+  // --- "capsule" layout (iOS): two side-by-side pill buttons, no divider --------
+  /** The action row that holds the two equal-width capsules with a gap. */
+  capsuleRow: ViewStyle | null;
+  /** A single capsule cell base (shape/sizing); fill comes from the *Fill helpers. */
+  capsuleCell: ViewStyle | null;
+  /** The Cancel (gray) capsule fill. */
+  cancelFill: ((t: ColorTokens) => ViewStyle) | null;
+  /** The Confirm capsule fill; `destructive` swaps `primary` for `destructive`. */
+  confirmFill: ((t: ColorTokens, destructive: boolean) => ViewStyle) | null;
+  /** The Cancel capsule label (regular weight, on-secondary color). */
+  cancelLabelStyle: ((t: ColorTokens) => TextStyle) | null;
+  /** The Confirm capsule label (weight 600, on-fill foreground). */
+  confirmLabelStyle: ((t: ColorTokens, destructive: boolean) => TextStyle) | null;
+  /** iOS/web dim on press; Android uses a ripple instead (null). */
+  pressedOpacity: number | null;
+  /** Android ripple over the action cells; null on iOS/web. */
+  ripple: ((t: ColorTokens) => { color: string; borderless: boolean }) | null;
+}
+
+// --- shared layout fragments (identical across platforms) -------------------
+
+// The outer wrapper aligns the dialog (and its optional trigger) to the start.
+export const root: ViewStyle = { alignSelf: "flex-start" };
+
+// Gap between the trigger button and the modal when the trigger renders above it.
+export const triggerGap: ViewStyle = { marginTop: 12 };
+
+// The card is full-width within its max-width; the per-platform skin supplies the
+// shape/fill/padding/shadow on top of this.
+export const cardBase: ViewStyle = { width: "100%" };
+
+// ---------- Web: the established Canvas look (lifted verbatim) ----------
+// The current alert-dialog: a contained dim scrim (rounded-md, black/50) centering
+// a bordered card (rounded-md border bg-popover p-6 shadow-xl); a left-aligned
+// 16pt/600 title and 14pt muted description; a right-aligned action row (gap-2,
+// mt-6) of an outline Cancel Button plus a primary/destructive confirm Button.
+export const webSkin: AlertDialogSkin = {
+  backdrop: {
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 8,
+    backgroundColor: alpha("#000000", 0.5),
+    padding: 32,
+  },
+  card: (t) => ({
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: t.border,
+    backgroundColor: t.popover,
+    padding: 24,
+    ...shadow("xl"),
+  }),
+  title: (t) => ({ fontSize: 16, lineHeight: 24, fontWeight: "600", color: t["popover-foreground"] }),
+  description: (t) => ({ marginTop: 8, fontSize: 14, lineHeight: 20, color: t["muted-foreground"] }),
+  inputBlock: { marginTop: 16 },
+  inputLabel: (t) => ({ marginBottom: 6, fontSize: 14, lineHeight: 20, fontWeight: "500", color: t.foreground }),
+  actionLayout: "buttons",
+  actions: { flexDirection: "row", justifyContent: "flex-end", gap: 8, marginTop: 24 },
+  buttonSmall: true,
+  cancelButton: { outline: true },
+  capsuleRow: null,
+  capsuleCell: null,
+  cancelFill: null,
+  confirmFill: null,
+  cancelLabelStyle: null,
+  confirmLabelStyle: null,
+  pressedOpacity: null,
+  ripple: null,
+};
+
+// ---------- iOS 27 (Liquid Glass alert): rounded card, left text, capsule actions ----------
+// iOS 26+/27 alert (per Apple's design kit): a rounded card (~28pt radius) over the
+// `popover` fill with a soft shadow and NO border; a LEFT-aligned bold title and a
+// LEFT-aligned `muted-foreground` message. The two actions are CAPSULES side by
+// side (no hairline divider): a gray Cancel capsule (`secondary` fill,
+// `secondary-foreground` text) and a filled Confirm capsule (`primary`, or
+// `destructive` when destructive) with white/`*-foreground` label. The brand
+// survives: the iOS system blue becomes the indigo `primary` token. Press = opacity
+// dim (~0.85).
+const IOS_RADIUS = 28;
+const IOS_CAPSULE_RADIUS = 999;
+export const iosSkin: AlertDialogSkin = {
+  backdrop: {
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 8,
+    backgroundColor: alpha("#000000", 0.4),
+    padding: 32,
+  },
+  // Rounded card with content padding; no border, soft shadow.
+  card: (t) => ({
+    borderRadius: IOS_RADIUS,
+    backgroundColor: t.popover,
+    padding: 24,
+    ...shadow("lg"),
+  }),
+  title: (t) => ({
+    fontSize: 20,
+    lineHeight: 25,
+    fontWeight: "700",
+    color: t["popover-foreground"],
+  }),
+  description: (t) => ({
+    marginTop: 8,
+    fontSize: 16,
+    lineHeight: 21,
+    color: t["muted-foreground"],
+  }),
+  inputBlock: { marginTop: 16 },
+  inputLabel: (t) => ({ marginBottom: 6, fontSize: 14, lineHeight: 18, fontWeight: "600", color: t.foreground }),
+  actionLayout: "capsule",
+  // Unused in the capsule layout, but the contract requires concrete values.
+  actions: { flexDirection: "row" },
+  buttonSmall: true,
+  cancelButton: {},
+  // Two equal-width capsules side by side, separated by a gap (no divider).
+  capsuleRow: { flexDirection: "row", gap: 12, marginTop: 24 },
+  capsuleCell: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    paddingVertical: 14,
+    paddingHorizontal: 16,
+    minHeight: 50,
+    borderRadius: IOS_CAPSULE_RADIUS,
+  },
+  cancelFill: (t) => ({ backgroundColor: t.secondary }),
+  confirmFill: (t, destructive) => ({ backgroundColor: destructive ? t.destructive : t.primary }),
+  cancelLabelStyle: (t) => ({ fontSize: 17, lineHeight: 22, fontWeight: "600", color: t["secondary-foreground"] }),
+  confirmLabelStyle: (t, destructive) => ({
+    fontSize: 17,
+    lineHeight: 22,
+    fontWeight: "700",
+    color: destructive ? t["destructive-foreground"] : t["primary-foreground"],
+  }),
+  pressedOpacity: 0.85,
+  ripple: null,
+};
+
+// ---------- Android (Material 3 AlertDialog): elevated surface, text buttons ----------
+// M3 basic dialog: an elevated surface (28dp radius) over `popover` with a soft
+// shadow; a LEFT-aligned 24sp/headline-small title and a left-aligned 14sp body in
+// `muted-foreground`. Two M3 TEXT buttons sit bottom-right (Cancel then Confirm/
+// Delete) — the confirm carries the brand `primary`, a destructive confirm the
+// `destructive` red. The shell renders these with its ghost (text) Buttons; press =
+// android_ripple, supplied here as the brand state layer.
+export const androidSkin: AlertDialogSkin = {
+  backdrop: {
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 8,
+    backgroundColor: alpha("#000000", 0.32),
+    padding: 32,
+  },
+  card: (t) => ({
+    borderRadius: 28,
+    backgroundColor: t.popover,
+    padding: 24,
+    ...shadow("md"),
+  }),
+  title: (t) => ({ fontSize: 24, lineHeight: 32, fontWeight: "400", color: t["popover-foreground"] }),
+  description: (t) => ({ marginTop: 16, fontSize: 14, lineHeight: 20, color: t["muted-foreground"] }),
+  inputBlock: { marginTop: 16 },
+  inputLabel: (t) => ({ marginBottom: 6, fontSize: 14, lineHeight: 20, fontWeight: "500", color: t.foreground }),
+  actionLayout: "buttons",
+  // M3 places the action buttons bottom-right with 8dp gap and 24dp above.
+  actions: { flexDirection: "row", justifyContent: "flex-end", gap: 8, marginTop: 24 },
+  buttonSmall: true,
+  // M3 dialog actions are text (ghost) buttons, not outlined.
+  cancelButton: { ghost: true },
+  capsuleRow: null,
+  capsuleCell: null,
+  cancelFill: null,
+  confirmFill: null,
+  cancelLabelStyle: null,
+  confirmLabelStyle: null,
+  pressedOpacity: null,
+  ripple: (t) => ({ color: alpha(t.primary, 0.12), borderless: false }),
+};

package/src/molecules/alert-dialog/alert-dialog.tsx

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

package/src/molecules/card/card.md

@@ -0,0 +1,190 @@
+# Cards
+
+Three families. `StatCard` = a single metric, big number + delta. `SectionCard` = a labeled content surface with optional header and divider. Generic `card` = bring your own structure. Density: pass `compact` or `comfortable` to tighten or relax the card's own padding and the gap between flat children (`compact` takes precedence, and a density prop pads the surface on its own).
+
+## Usage
+
+```tsx
+<Card style={{ width: 280, padding: 20 }}>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", justifyContent: "space-between" }}>
+    <View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Active identities</Text>
+      <Text style={{ marginTop: 4, fontSize: 24, lineHeight: 32, fontWeight: "700", color: tokens["card-foreground"] }}>12,348</Text>
+      <Text style={{ marginTop: 2, fontSize: 11, color: tokens["muted-foreground"] }}>+142 today</Text>
+    </View>
+    <View style={{ height: 40, width: 40, alignItems: "center", justifyContent: "center", borderRadius: 8, backgroundColor: alpha(palette["blue-500"], 0.1), color: palette["blue-600"] }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: palette["blue-600"] }}>U</Text>
+    </View>
+  </View>
+</Card>
+```
+
+## Variants
+
+### Type - section
+
+```tsx
+<Card
+  title="Recent activity"
+  body="A labeled content surface. Drop fields, a list, or any module of content here."
+/>
+```
+
+### Type - generic
+
+```tsx
+<Card
+  padded
+  title="Anything goes here"
+  body="The card surface gives you the border, radius, and shadow. You bring the content."
+/>
+```
+
+### Icon tone - success
+
+```tsx
+<Card style={{ width: 280, padding: 20 }}>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", justifyContent: "space-between" }}>
+    <View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Active identities</Text>
+      <Text style={{ marginTop: 4, fontSize: 24, lineHeight: 32, fontWeight: "700", color: tokens["card-foreground"] }}>12,348</Text>
+      <Text style={{ marginTop: 2, fontSize: 11, color: tokens["muted-foreground"] }}>+142 today</Text>
+    </View>
+    <View style={{ height: 40, width: 40, alignItems: "center", justifyContent: "center", borderRadius: 8, backgroundColor: alpha(palette["green-500"], 0.1), color: palette["green-600"] }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: palette["green-600"] }}>S</Text>
+    </View>
+  </View>
+</Card>
+```
+
+### Icon tone - purple
+
+```tsx
+<Card style={{ width: 280, padding: 20 }}>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", justifyContent: "space-between" }}>
+    <View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Active identities</Text>
+      <Text style={{ marginTop: 4, fontSize: 24, lineHeight: 32, fontWeight: "700", color: tokens["card-foreground"] }}>12,348</Text>
+      <Text style={{ marginTop: 2, fontSize: 11, color: tokens["muted-foreground"] }}>+142 today</Text>
+    </View>
+    <View style={{ height: 40, width: 40, alignItems: "center", justifyContent: "center", borderRadius: 8, backgroundColor: alpha(palette["purple-500"], 0.1), color: palette["purple-600"] }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: palette["purple-600"] }}>O</Text>
+    </View>
+  </View>
+</Card>
+```
+
+### Icon tone - destructive
+
+```tsx
+<Card style={{ width: 280, padding: 20 }}>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", justifyContent: "space-between" }}>
+    <View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Active identities</Text>
+      <Text style={{ marginTop: 4, fontSize: 24, lineHeight: 32, fontWeight: "700", color: tokens["card-foreground"] }}>12,348</Text>
+      <Text style={{ marginTop: 2, fontSize: 11, color: tokens["muted-foreground"] }}>+142 today</Text>
+    </View>
+    <View style={{ height: 40, width: 40, alignItems: "center", justifyContent: "center", borderRadius: 8, backgroundColor: alpha(tokens.destructive, 0.1), color: tokens.destructive }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: tokens.destructive }}>!</Text>
+    </View>
+  </View>
+</Card>
+```
+
+### Icon tone - amber
+
+```tsx
+<Card style={{ width: 280, padding: 20 }}>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", justifyContent: "space-between" }}>
+    <View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Active identities</Text>
+      <Text style={{ marginTop: 4, fontSize: 24, lineHeight: 32, fontWeight: "700", color: tokens["card-foreground"] }}>12,348</Text>
+      <Text style={{ marginTop: 2, fontSize: 11, color: tokens["muted-foreground"] }}>+142 today</Text>
+    </View>
+    <View style={{ height: 40, width: 40, alignItems: "center", justifyContent: "center", borderRadius: 8, backgroundColor: alpha(palette["amber-500"], 0.1), color: palette["amber-600"] }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: palette["amber-600"] }}>T</Text>
+    </View>
+  </View>
+</Card>
+```
+
+## Do & Don't
+
+### stat
+
+**Do** — One big number, a short label, a small delta. The metric is scannable in a glance.
+
+```tsx
+<Card padded style={{ maxWidth: 280 }}>
+  <View style={{ flexDirection: "row", alignItems: "flex-start", justifyContent: "space-between" }}>
+    <View>
+      <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>Active identities</Text>
+      <Text style={{ marginTop: 4, fontSize: 24, lineHeight: 32, fontWeight: "700", color: tokens["card-foreground"] }}>12,348</Text>
+      <Text style={{ marginTop: 2, fontSize: 11, color: tokens["muted-foreground"] }}>+142 today</Text>
+    </View>
+    <View style={{ height: 40, width: 40, alignItems: "center", justifyContent: "center", borderRadius: 8, backgroundColor: alpha(palette["blue-500"], 0.1) }}>
+      <Text style={{ fontSize: 14, lineHeight: 20, fontWeight: "600", color: palette["blue-600"] }}>U</Text>
+    </View>
+  </View>
+</Card>
+```
+
+**Don't** — Prose where the number should be: the eye has nothing big to land on, so the card stops being a stat.
+
+```tsx
+<Card padded style={{ maxWidth: 280 }}>
+  <Text style={{ fontSize: 12, lineHeight: 16, fontWeight: "500", textTransform: "uppercase", letterSpacing: 0.4, color: tokens["muted-foreground"] }}>This month</Text>
+  <Text style={{ marginTop: 4, fontSize: 14, lineHeight: 20, fontWeight: "500", color: tokens["card-foreground"] }}>We onboarded 12,348 active identities, up 142 today, with churn holding steady.</Text>
+</Card>
+```
+
+### section
+
+**Do** — Keep the divider between header and body; it anchors the title.
+
+```tsx
+<Card style={{ maxWidth: 360 }}>
+  <CardHeader>
+    <CardTitle>Recent activity</CardTitle>
+  </CardHeader>
+  <CardSeparator />
+  <CardContent>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["card-foreground"] }}>Two events today.</Text>
+  </CardContent>
+</Card>
+```
+
+**Don't** — Without the divider the header floats and stops reading as a header.
+
+```tsx
+<Card style={{ maxWidth: 360 }}>
+  <CardHeader>
+    <CardTitle>Recent activity</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["card-foreground"] }}>Two events today.</Text>
+  </CardContent>
+</Card>
+```
+
+### generic
+
+**Do** — Use the surface once and layout the content with plain spacing inside it.
+
+```tsx
+<Card padded style={{ maxWidth: 360 }}>
+  <Text style={{ marginBottom: 4, fontSize: 15, fontWeight: "600", color: tokens["card-foreground"] }}>Anything goes here</Text>
+  <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>The card surface gives you the border, radius, and shadow. You bring the content.</Text>
+</Card>
+```
+
+**Don't** — Nesting one card surface inside another stacks border on border and shadow on shadow; the inner block looks dropped in.
+
+```tsx
+<Card padded style={{ maxWidth: 360 }}>
+  <Card padded>
+    <Text style={{ marginBottom: 4, fontSize: 15, fontWeight: "600", color: tokens["card-foreground"] }}>Nested surface</Text>
+    <Text style={{ fontSize: 14, lineHeight: 20, color: tokens["muted-foreground"] }}>A card inside a card doubles the border and shadow.</Text>
+  </Card>
+</Card>
+```