@signalflare-ai/ui 1.1.0 → 1.3.0

package/ai/component-registry.md

@@ -26,6 +26,25 @@ Container for a row of AI message action buttons.
 
 `text-sf-default`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<AiActions>
+  <AiAction tooltip="Copy">
+    <CopyIcon className="size-4" />
+  </AiAction>
+  <AiAction tooltip="Retry">
+    <ArrowCounterClockwiseIcon className="size-4" />
+  </AiAction>
+  <AiAction tooltip="Thumbs up">
+    <ThumbsUpIcon className="size-4" />
+  </AiAction>
+  <AiAction tooltip="Thumbs down">
+    <ThumbsDownIcon className="size-4" />
+  </AiAction>
+</AiActions>
+```
+
 ---
 
 ### AiAgentCard
@@ -75,6 +94,105 @@ Container for a row of AI message action buttons.
 
 `bg-sf-brand`, `bg-sf-danger`, `bg-sf-elevated`, `bg-sf-fill`, `bg-sf-recessed`, `bg-sf-success`, `bg-sf-tint`, `border-sf-line`, `ring-sf-ring`, `text-sf-brand`, `text-sf-danger`, `text-sf-default`, `text-sf-inactive`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<div className="flex flex-wrap gap-3">
+  <AiAgentCard
+    name="Explore"
+    agentType="explore"
+    status="running"
+    modelId="claude-haiku-3.5"
+    currentTask="Scanning auth files for deprecated patterns..."
+    duration={4200}
+    toolCallCount={3}
+  />
+  <AiAgentCard
+    name="Execute"
+    agentType="execute"
+    status="running"
+    modelId="claude-sonnet-4"
+    currentTask="Rewriting jwt.ts using jose library..."
+    duration={8700}
+    toolCallCount={1}
+  />
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap gap-3">
+  <AiAgentCard
+    name="Explore"
+    agentType="explore"
+    status="idle"
+    modelId="claude-haiku-3.5"
+  />
+  <AiAgentCard
+    name="Plan"
+    agentType="plan"
+    status="running"
+    modelId="claude-sonnet-4"
+    currentTask="Drafting migration steps..."
+    duration={2100}
+    toolCallCount={0}
+  />
+  <AiAgentCard
+    name="Execute"
+    agentType="execute"
+    status="completed"
+    modelId="claude-sonnet-4"
+    currentTask="Rewrote 4 files successfully."
+    duration={12_400}
+    toolCallCount={7}
+  />
+  <AiAgentCard
+    name="Test"
+    agentType="test"
+    status="error"
+    modelId="claude-haiku-3.5"
+    currentTask="3 tests failed: auth.spec.ts"
+    duration={3200}
+    toolCallCount={2}
+  />
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap gap-3">
+  <AiAgentCard
+    name="Explore"
+    agentType="explore"
+    status="completed"
+    modelId="claude-haiku-3.5"
+    duration={4200}
+    toolCallCount={5}
+  />
+  <AiAgentCard
+    name="Execute"
+    agentType="execute"
+    status="running"
+    modelId="claude-sonnet-4"
+    currentTask="Patching consumers..."
+    duration={6100}
+    toolCallCount={3}
+    selected
+  />
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  {[
+    { name: "Explore", agentType: "explore", status: "completed" as const },
+    { name: "Plan", agentType: "plan", status: "completed" as const },
+    { name: "Execute", agentType: "execute", status: "running" as const },
+    { name: "Review", agentType: "review", status: "idle" as const },
+  ].map((agent) => (
+    <AiAgentCard key={agent.name} size="sm" {...agent} />
+  ))}
+</div>
+```
+
 ---
 
 ### AiApproval
@@ -119,11 +237,47 @@ Approval card for tool calls and plan submissions. Maps to harness events: `tool
 
 `bg-sf-base`, `bg-sf-brand`, `bg-sf-elevated`, `border-sf-line`, `border-sf-ring`, `text-sf-brand`, `text-sf-danger`, `text-sf-default`, `text-sf-inactive`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<div className="w-full max-w-md">
+  <AiApproval
+    kind="tool"
+    status={status}
+    title="Execute shell command"
+    description="rm -rf /tmp/cache"
+    onApprove={() => setStatus("approved")}
+    onReject={() => setStatus("rejected")}
+  />
+</div>
+```
+
+```tsx
+<div className="w-full max-w-md">
+  <AiApproval
+    kind="plan"
+    status={status}
+    title="Deployment plan"
+    description="The agent proposes the following steps:"
+    items={[
+      { id: "1", label: "Run test suite", description: "All 142 tests" },
+      { id: "2", label: "Build production bundle" },
+      { id: "3", label: "Deploy to staging", description: "us-east-1" },
+      { id: "4", label: "Run smoke tests" },
+      { id: "5", label: "Promote to production" },
+    ]}
+    showFeedback
+    onApprove={() => setStatus("approved")}
+    onReject={() => setStatus("rejected")}
+  />
+</div>
+```
+
 ---
 
 ### AiCodeBlock
 
-Displays a code block with monospace formatting and an optional copy button. Does not include a syntax highlighter — avoids the heavy `react-syntax-highlighter` dependency. Wrap with `AiCodeBlockCopyButton` for clipboard support.
+AiCodeBlock component
 
 **Type:** component
 
@@ -149,6 +303,32 @@ Displays a code block with monospace formatting and an optional copy button. Doe
 
 `bg-sf-recessed`, `border-sf-line`, `text-sf-default`, `text-sf-inactive`, `text-sf-subtle`
 
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### AiCodeBlock.CopyButton
+
+CopyButton sub-component
+
+Props:
+
+- `timeout`: number
+
+**Examples:**
+
+```tsx
+<AiCodeBlock code={CODE} language="tsx">
+  <AiCodeBlockCopyButton />
+</AiCodeBlock>
+```
+
+```tsx
+<AiCodeBlock code="npm install @signalflare-ai/ui">
+  <AiCodeBlockCopyButton />
+</AiCodeBlock>
+```
+
 ---
 
 ### AiConversation
@@ -169,6 +349,24 @@ Outer scroll container for a conversation. Sticks to the bottom as new messages
 - `lang`: string
 - `title`: string
 
+**Examples:**
+
+```tsx
+<div className="h-80 w-full overflow-hidden rounded-lg border border-sf-line">
+  <AiConversation>
+    <AiConversationContent>
+      {MESSAGES.map((m) => (
+        <AiMessage key={m.id} from={m.from}>
+          <AiMessageContent>
+            <AiResponse>{m.text}</AiResponse>
+          </AiMessageContent>
+        </AiMessage>
+      ))}
+    </AiConversationContent>
+  </AiConversation>
+</div>
+```
+
 ---
 
 ### AiInfoBanner
@@ -199,6 +397,18 @@ Inline conversation banner for system notices. Renders as a compact, horizontall
 
 `border-sf-danger`, `border-sf-info`, `border-sf-line`, `text-sf-danger`, `text-sf-info`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<div className="flex w-full flex-col gap-3">
+  <AiInfoBanner level="info">
+    Follow-up message queued — will send after current response completes
+  </AiInfoBanner>
+  <AiInfoBanner level="change">Switched to claude-opus-4-6</AiInfoBanner>
+  <AiInfoBanner level="error">Connection lost. Retrying in 3s…</AiInfoBanner>
+</div>
+```
+
 ---
 
 ### AiMessage
@@ -227,6 +437,37 @@ Root message container. Sets layout, group class, and role context.
 
 `bg-sf-control`, `bg-sf-overlay`, `bg-sf-tint`, `text-sf-default`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<div className="flex w-full flex-col gap-2 p-4">
+  <AiMessage from="user">
+    <AiMessageContent>What is the capital of France?</AiMessageContent>
+  </AiMessage>
+  <AiMessage from="assistant">
+    <AiMessageContent>
+      <AiResponse>{"The capital of France is **Paris**."}</AiResponse>
+    </AiMessageContent>
+    <AiMessageToolbar>
+      <AiMessageActions>
+        <AiMessageAction tooltip="Copy">
+          <CopyIcon className="size-4" />
+        </AiMessageAction>
+        <AiMessageAction tooltip="Retry">
+          <ArrowCounterClockwiseIcon className="size-4" />
+        </AiMessageAction>
+      </AiMessageActions>
+    </AiMessageToolbar>
+  </AiMessage>
+</div>
+```
+
+```tsx
+<AiMessage from="user">
+  <AiMessageContent>Can you summarise this document?</AiMessageContent>
+</AiMessage>
+```
+
 ---
 
 ### AiMissionHeader
@@ -269,6 +510,116 @@ Root message container. Sets layout, group class, and role context.
 
 `bg-sf-base`, `bg-sf-brand`, `bg-sf-danger`, `bg-sf-fill`, `border-sf-line`, `ring-sf-ring`, `text-sf-brand`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<AiMissionHeader
+  title="Refactor auth module"
+  taskList={{
+    title: "Refactor auth module",
+    tasks: [
+      {
+        id: "t1",
+        content: "Explore authentication codebase",
+        status: "completed",
+        priority: "high",
+      },
+      {
+        id: "t2",
+        content: "Identify deprecated patterns",
+        status: "completed",
+        priority: "high",
+      },
+      {
+        id: "t3",
+        content: "Write updated auth helpers",
+        status: "in_progress",
+        priority: "medium",
+      },
+      {
+        id: "t4",
+        content: "Update all consumers",
+        status: "pending",
+        priority: "medium",
+      },
+      {
+        id: "t5",
+        content: "Update tests",
+        status: "pending",
+        priority: "low",
+      },
+    ],
+  }}
+  usage={{
+    inputTokens: 12_480,
+    outputTokens: 3256,
+    totalTokens: 15_736,
+    cost: 0.04,
+  }}
+  activeAgentCount={2}
+  totalAgentCount={4}
+  startedAt={startedAt}
+  isRunning
+/>
+```
+
+```tsx
+<AiMissionHeader
+  title="Deploy to production"
+  taskList={{
+    tasks: [
+      {
+        id: "t1",
+        content: "Run tests",
+        status: "completed",
+        priority: "high",
+      },
+      {
+        id: "t2",
+        content: "Build artifacts",
+        status: "completed",
+        priority: "high",
+      },
+      {
+        id: "t3",
+        content: "Deploy to staging",
+        status: "completed",
+        priority: "medium",
+      },
+      {
+        id: "t4",
+        content: "Smoke test",
+        status: "completed",
+        priority: "medium",
+      },
+      {
+        id: "t5",
+        content: "Deploy to production",
+        status: "completed",
+        priority: "high",
+      },
+    ],
+  }}
+  usage={{ totalTokens: 28_400, cost: 0.12 }}
+  activeAgentCount={0}
+  totalAgentCount={3}
+  startedAt={startedAt}
+  endedAt={endedAt}
+  isRunning={false}
+/>
+```
+
+```tsx
+<AiMissionHeader
+  title="Analyze codebase"
+  activeAgentCount={1}
+  totalAgentCount={2}
+  startedAt={startedAt}
+  isRunning
+  variant="compact"
+/>
+```
+
 ---
 
 ### AiPartGroup
@@ -298,6 +649,49 @@ Groups streaming ephemeral activity (tool calls + reasoning) into a single rolli
 
 `bg-sf-tint`, `border-sf-line`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center justify-between gap-3">
+    <Text variant="secondary" size="sm">
+      Rolling window of 3 rows while streaming. Collapses to a single frozen
+      line when complete.
+    </Text>
+    <Button onClick={() => setRunId((n) => n + 1)} size="sm" variant="ghost">
+      Run again
+    </Button>
+  </div>
+  <div className="min-h-[6rem] rounded-md border border-sf-line/40 bg-sf-base/40 p-3">
+    <AiPartGroup
+      complete={complete}
+      groupKey={`activity-demo-${runId}`}
+      max={3}
+      title="Investigating failing auth tests"
+    >
+      {steps.map((s) =>
+        s.kind === "tool" ? (
+          <AiToolCall
+            duration={s.duration}
+            key={s.part.toolCallId}
+            part={s.part}
+            variant="ephemeral"
+          />
+        ) : (
+          <AiReasoning
+            duration={s.duration}
+            isStreaming={s.isStreaming}
+            key={s.id}
+            part={{ text: s.text }}
+            variant="ephemeral"
+          />
+        )
+      )}
+    </AiPartGroup>
+  </div>
+</div>
+```
+
 ---
 
 ### AiQuestion
@@ -338,6 +732,55 @@ Agent question card. Renders when the agent uses the `ask_user` built-in tool an
 
 `bg-sf-base`, `bg-sf-brand`, `bg-sf-tint`, `border-sf-brand`, `border-sf-line`, `border-sf-ring`, `text-sf-brand`, `text-sf-default`, `text-sf-inactive`, `text-sf-inverse`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<div className="w-full max-w-md">
+  <AiQuestion
+    questionId="q-demo-1"
+    question="How should I handle the failing tests?"
+    header="Decision needed"
+    status={status}
+    answeredWith={answer}
+    options={[
+      {
+        label: "Fix them",
+        description: "Update the test expectations to match new behavior",
+      },
+      {
+        label: "Skip them",
+        description: "Mark as skipped for now and create a ticket",
+      },
+      {
+        label: "Delete them",
+        description: "Remove outdated tests entirely",
+      },
+    ]}
+    allowCustom
+    onAnswer={(_id, ans) => {
+      setAnswer(ans);
+      setStatus("answered");
+    }}
+  />
+</div>
+```
+
+```tsx
+<div className="w-full max-w-md">
+  <AiQuestion
+    questionId="q-demo-2"
+    question="What should the commit message be for these changes?"
+    status={status}
+    answeredWith={answer}
+    allowCustom
+    onAnswer={(_id, ans) => {
+      setAnswer(ans);
+      setStatus("answered");
+    }}
+  />
+</div>
+```
+
 ---
 
 ### AiReasoning
@@ -387,6 +830,73 @@ Collapsible reasoning block. Supports three display variants: - `"default"` —
 
 `bg-sf-tint`, `border-sf-line`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<AiReasoning
+  part={{ text: SAMPLE_REASONING }}
+  isStreaming={false}
+  duration={3}
+  defaultExpanded
+/>
+```
+
+```tsx
+<AiReasoning
+  part={{ text: "Analysing context and forming a response..." }}
+  isStreaming
+/>
+```
+
+```tsx
+<AiReasoning
+  variant="inline"
+  part={{ text: SAMPLE_REASONING }}
+  isStreaming={false}
+/>
+```
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center justify-between gap-3">
+    <Text variant="secondary" size="sm">
+      Reasoning row evaporates 800ms after streaming ends.
+    </Text>
+    <Button onClick={() => setRunId((n) => n + 1)} size="sm" variant="ghost">
+      Think again
+    </Button>
+  </div>
+  <div
+    className={
+      "min-h-[3.5rem] rounded-md border border-sf-line/40 bg-sf-base/40 p-3"
+    }
+  >
+    <AiReasoning
+      // `key` ensures each replay re-mounts to reset the dismiss state.
+      key={runId}
+      variant="ephemeral"
+      part={{
+        text: "**Reviewing diff** — checking for breaking changes in the migration.",
+      }}
+      isStreaming={isStreaming}
+    />
+  </div>
+</div>
+```
+
+```tsx
+<AiReasoningGroup
+  parts={[
+    { text: "**Step 1** — Understood the user intent and context." },
+    { text: "**Step 2** — Reviewed relevant data and constraints." },
+    { text: "**Step 3** — Formulated the final response structure." },
+  ]}
+  isStreaming={false}
+  totalDuration={7}
+  defaultExpanded
+/>
+```
+
 ---
 
 ### AiResponse
@@ -410,6 +920,39 @@ Renders AI-generated markdown using Streamdown. Supports streaming animation, sy
 
 `text-sf-default`
 
+**Examples:**
+
+```tsx
+<AiResponse>{MARKDOWN_LIKE}</AiResponse>
+```
+
+```tsx
+<AiResponse isAnimating={isAnimating}>{text}</AiResponse>
+```
+
+```tsx
+<div className="flex w-full flex-col gap-4">
+  <AiResponse
+    components={{ a: LinkComponent } as Components}
+    linkSafety={{ enabled: false }}
+  >
+    {DEEP_LINK_MARKDOWN}
+  </AiResponse>
+  {activeFile && (
+    <div className="rounded-lg border border-sf-brand/30 bg-sf-brand/10 px-3 py-2 text-sm text-sf-default">
+      <span className="text-sf-subtle">Opened file:</span>{" "}
+      <code className="font-mono text-sf-brand">{activeFile}</code>
+      <button
+        onClick={() => setActiveFile(null)}
+        className="ml-3 text-xs text-sf-subtle hover:text-sf-default"
+      >
+        Dismiss
+      </button>
+    </div>
+  )}
+</div>
+```
+
 ---
 
 ### AiShimmer
@@ -435,6 +978,26 @@ AiShimmer component
 - `spread`: number
   Shimmer width multiplier relative to text length.
 
+**Examples:**
+
+```tsx
+<AiShimmer>Thinking...</AiShimmer>
+```
+
+```tsx
+<p className="text-sf-default text-sm">
+  The AI is{" "}
+  <AiShimmer as="span" duration={1.5}>
+    generating a response
+  </AiShimmer>
+  .
+</p>
+```
+
+```tsx
+<AiShimmer duration={4}>Analysing your request...</AiShimmer>
+```
+
 ---
 
 ### AiStatusBadge
@@ -470,6 +1033,45 @@ Compact pill-shaped badge showing an icon, label, and a status indicator. Used b
 
 `bg-sf-tint`, `text-sf-brand`, `text-sf-danger`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<AiStatusBadge icon={MagnifyingGlassIcon} label="web_search" status="idle" />
+```
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  <AiStatusBadge icon={GlobeIcon} label="search_web" status="idle" />
+  <AiStatusBadge icon={GlobeIcon} label="search_web" status="running" />
+  <AiStatusBadge icon={GlobeIcon} label="search_web" status="success" />
+  <AiStatusBadge icon={GlobeIcon} label="search_web" status="error" />
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  <AiStatusBadge
+    icon={DatabaseIcon}
+    label="query_db"
+    info="3/5"
+    status="running"
+  />
+  <AiStatusBadge
+    icon={BrainIcon}
+    label="analyse"
+    info="done"
+    status="success"
+  />
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  <AiStatusBadge label="processing" status="running" />
+  <AiStatusBadge label="complete" status="success" />
+</div>
+```
+
 ---
 
 ### AiStreamingText
@@ -489,6 +1091,17 @@ AiStreamingText component
 - `children`: ReactNode
   Child elements
 
+**Examples:**
+
+```tsx
+<p className="max-w-sm text-sf-default text-sm">
+  {displayed}
+  {streaming && (
+    <span className="ml-0.5 inline-block h-4 w-0.5 animate-pulse bg-sf-brand" />
+  )}
+</p>
+```
+
 ---
 
 ### AiSubagent
@@ -529,7 +1142,92 @@ Collapsible wrapper for nested subagent activity. Shows the subagent name, statu
 
 **Colors (sf tokens used):**
 
-`bg-sf-tint`, `text-sf-brand`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`, `text-sf-success`
+`bg-sf-tint`, `text-sf-brand`, `text-sf-danger`, `text-sf-subtle`, `text-sf-success`
+
+**Examples:**
+
+```tsx
+<div className="w-full max-w-lg">
+  <AiSubagent
+    name="Explore"
+    agentType="explore"
+    status="running"
+    modelId="claude-haiku-3.5"
+    defaultExpanded
+  >
+    <div className="flex flex-col gap-1.5 text-sm text-sf-subtle">
+      <p>Searching codebase for authentication patterns...</p>
+      <div className="flex items-center gap-2 border-l-2 border-sf-fill py-1 pl-2 text-xs">
+        <span className="text-sf-brand">Glob</span>
+        <span className="text-sf-subtle">src/**/*auth*</span>
+      </div>
+      <div className="flex items-center gap-2 border-l-2 border-sf-fill py-1 pl-2 text-xs">
+        <span className="text-sf-brand">Read</span>
+        <span className="text-sf-subtle">src/middleware/auth.ts</span>
+      </div>
+    </div>
+  </AiSubagent>
+</div>
+```
+
+```tsx
+<div className="w-full max-w-lg">
+  <AiSubagent
+    name="Execute"
+    agentType="execute"
+    status="completed"
+    modelId="claude-sonnet-4"
+    duration={12400}
+    defaultExpanded={false}
+  >
+    <div className="text-sm text-sf-subtle">
+      <p>Refactored 3 files, added 2 new tests. All tests passing.</p>
+    </div>
+  </AiSubagent>
+</div>
+```
+
+```tsx
+<div className="w-full max-w-lg">
+  <AiSubagent
+    name="Plan"
+    agentType="plan"
+    status="completed"
+    modelId="claude-sonnet-4"
+    duration={28000}
+    defaultExpanded
+  >
+    <div className="flex flex-col gap-2">
+      <p className="text-sm text-sf-subtle">
+        Breaking down the migration into subtasks...
+      </p>
+      <AiSubagent
+        name="Explore"
+        agentType="explore"
+        status="completed"
+        modelId="claude-haiku-3.5"
+        duration={4200}
+        defaultExpanded={false}
+      >
+        <p className="text-sm text-sf-subtle">
+          Found 12 files using deprecated API.
+        </p>
+      </AiSubagent>
+      <AiSubagent
+        name="Execute"
+        agentType="execute"
+        status="running"
+        modelId="claude-sonnet-4"
+        defaultExpanded
+      >
+        <p className="text-sm text-sf-subtle">
+          Updating import paths in batch 1/3...
+        </p>
+      </AiSubagent>
+    </div>
+  </AiSubagent>
+</div>
+```
 
 ---
 
@@ -582,6 +1280,14 @@ Task progress list. Renders structured tasks from the harness `task_write` tool.
 
 `bg-sf-brand`, `bg-sf-danger`, `bg-sf-subtle`, `bg-sf-success`, `bg-sf-tint`, `bg-sf-warning`, `text-sf-default`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<div className="w-full max-w-sm">
+  <AiTaskList title="Agent tasks" tasks={tasks} />
+</div>
+```
+
 ---
 
 ### AiTimeline
@@ -618,6 +1324,95 @@ Task progress list. Renders structured tasks from the harness `task_write` tool.
 
 `bg-sf-base`, `bg-sf-brand`, `bg-sf-danger`, `bg-sf-elevated`, `bg-sf-fill`, `bg-sf-info`, `bg-sf-line`, `bg-sf-recessed`, `bg-sf-warning`, `border-sf-line`, `ring-sf-ring`, `text-sf-brand`, `text-sf-danger`, `text-sf-default`, `text-sf-inactive`, `text-sf-inverse`, `text-sf-strong`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<AiTimeline timeOrigin={T0} pixelsPerSecond={25} showNowMarker nowMs={nowMs}>
+  <AiTimelineLane
+    label="Main"
+    agentType="main"
+    status="running"
+    modelId="claude-sonnet-4"
+    blocks={mainBlocks}
+    timeOrigin={T0}
+    nowMs={nowMs}
+    pxPerMs={pxPerMs}
+  />
+  <AiTimelineLane
+    label="Explore"
+    agentType="explore"
+    status="completed"
+    modelId="claude-haiku-3.5"
+    blocks={exploreBlocks}
+    timeOrigin={T0}
+    nowMs={nowMs}
+    pxPerMs={pxPerMs}
+  />
+  <AiTimelineLane
+    label="Plan"
+    agentType="plan"
+    status="completed"
+    modelId="claude-sonnet-4"
+    blocks={planBlocks}
+    timeOrigin={T0}
+    nowMs={nowMs}
+    pxPerMs={pxPerMs}
+  />
+  <AiTimelineLane
+    label="Execute"
+    agentType="execute"
+    status="running"
+    modelId="claude-sonnet-4"
+    blocks={executeBlocks}
+    timeOrigin={T0}
+    nowMs={nowMs}
+    pxPerMs={pxPerMs}
+  />
+</AiTimeline>
+```
+
+```tsx
+<AiTimeline timeOrigin={T0} pixelsPerSecond={25} showNowMarker nowMs={nowMs}>
+  <AiTimelineLane
+    label="Explore"
+    agentType="explore"
+    status="completed"
+    blocks={exploreBlocks}
+    timeOrigin={T0}
+    nowMs={nowMs}
+    pxPerMs={pxPerMs}
+    density="compact"
+  />
+  <AiTimelineLane
+    label="Execute"
+    agentType="execute"
+    status="running"
+    blocks={executeBlocks}
+    timeOrigin={T0}
+    nowMs={nowMs}
+    pxPerMs={pxPerMs}
+    density="compact"
+  />
+</AiTimeline>
+```
+
+```tsx
+<AiTimeline
+  timeOrigin={t}
+  pixelsPerSecond={30}
+  showNowMarker={false}
+  nowMs={nowMs}
+>
+  <AiTimelineLane
+    label="Agent"
+    blocks={allTypeBlocks}
+    timeOrigin={t}
+    nowMs={nowMs}
+    pxPerMs={pxPerMs}
+  />
+</AiTimeline>
+```
+
 ---
 
 ### AiToolCall
@@ -697,6 +1492,25 @@ Compact token usage display bar. Shows input/output token counts, total, optiona
 
 `text-sf-inactive`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<div className="w-full max-w-md rounded-lg border border-sf-line">
+  <AiUsageBar
+    inputTokens={12480}
+    outputTokens={3256}
+    cost={0.04}
+    modelId="claude-sonnet-4"
+  />
+</div>
+```
+
+```tsx
+<div className="w-full max-w-sm rounded-lg border border-sf-line">
+  <AiUsageBar inputTokens={850} outputTokens={124} />
+</div>
+```
+
 ---
 
 ### Badge
@@ -741,6 +1555,116 @@ Small status label for categorizing or highlighting content. Supports icons, loa
 
 `bg-sf-brand`, `bg-sf-contrast`, `bg-sf-danger`, `bg-sf-fill`, `bg-sf-info`, `bg-sf-subtle`, `bg-sf-success`, `bg-sf-warning`, `border-sf-brand`, `border-sf-fill`, `text-sf-default`, `text-sf-inverse`, `text-sf-link`, `text-sf-strong`, `text-sf-success`, `text-sf-warning`
 
+**Examples:**
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  <Badge variant="primary">Primary</Badge>
+  <Badge variant="secondary">Secondary</Badge>
+  <Badge variant="destructive">Destructive</Badge>
+  <Badge variant="outline">Outline</Badge>
+  <Badge variant="beta">Beta</Badge>
+  <Badge variant="success">Success</Badge>
+  <Badge variant="warning">Warning</Badge>
+  <Badge variant="info">Info</Badge>
+  <Badge variant="ghost">Ghost</Badge>
+</div>
+```
+
+```tsx
+<Badge variant="primary">Primary</Badge>
+```
+
+```tsx
+<p className="flex items-center gap-2">
+  Workers
+  <Badge variant="beta">Beta</Badge>
+</p>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  <Badge variant="success" icon={CheckCircleIcon}>
+    Verified
+  </Badge>
+  <Badge variant="secondary" icon={LightningIcon}>
+    Boosted
+  </Badge>
+  <Badge variant="outline" icon={TagIcon} iconPosition="right">
+    Tagged
+  </Badge>
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  {tags.map((tag) => (
+    <Badge
+      key={tag}
+      variant="secondary"
+      onDismiss={() => setTags((t) => t.filter((v) => v !== tag))}
+    >
+      {tag}
+    </Badge>
+  ))}
+  {tags.length === 0 && (
+    <span className="text-sm text-sf-subtle">All tags removed</span>
+  )}
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  <Badge variant="secondary" loading>
+    Syncing
+  </Badge>
+  <Badge variant="info" loading>
+    Deploying
+  </Badge>
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  <Badge variant="outline" dot="green">
+    Online
+  </Badge>
+  <Badge variant="outline" dot="red">
+    Offline
+  </Badge>
+  <Badge variant="outline" dot="yellow">
+    Degraded
+  </Badge>
+  <Badge variant="outline" dot="blue">
+    Deploying
+  </Badge>
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  <Badge variant="secondary" onClick={handleBadgeClick}>
+    Clickable
+  </Badge>
+  <Badge variant="info" href="https://example.com">
+    Link badge
+  </Badge>
+</div>
+```
+
+```tsx
+<TooltipProvider>
+  <div className="flex flex-wrap items-center gap-2">
+    <Badge variant="success" tooltip="Deployed 2 hours ago" dot="green">
+      Production
+    </Badge>
+    <Badge variant="outline" tooltip="3 of 5 tasks complete">
+      3/5
+    </Badge>
+  </div>
+</TooltipProvider>
+```
+
 ---
 
 ### Banner
@@ -771,6 +1695,38 @@ Full-width message bar for informational, warning, or error notices.
 
 `bg-sf-danger`, `bg-sf-danger-tint`, `bg-sf-info`, `bg-sf-info-tint`, `bg-sf-warning`, `bg-sf-warning-tint`, `border-sf-danger`, `border-sf-info`, `border-sf-warning`, `text-sf-danger`, `text-sf-link`, `text-sf-warning`
 
+**Examples:**
+
+```tsx
+<div className="space-y-3">
+  <Banner>This is an informational banner.</Banner>
+  <Banner variant="alert">This is an alert banner.</Banner>
+  <Banner variant="error">This is an error banner.</Banner>
+</div>
+```
+
+```tsx
+<Banner>This is an informational banner.</Banner>
+```
+
+```tsx
+<Banner variant="alert">Your session will expire soon.</Banner>
+```
+
+```tsx
+<Banner icon={<WarningCircleIcon />} variant="alert">
+  Review your billing information.
+</Banner>
+```
+
+```tsx
+<Banner icon={<InfoIcon />}>
+  <Text DANGEROUS_className="text-inherit">
+    This banner supports <strong>custom content</strong> with Text.
+  </Text>
+</Banner>
+```
+
 ---
 
 ### Breadcrumbs
@@ -830,6 +1786,47 @@ Props:
 
 - `text`: string (required)
 
+**Examples:**
+
+```tsx
+<Breadcrumbs>
+  <Breadcrumbs.Link href="#">Home</Breadcrumbs.Link>
+  <Breadcrumbs.Separator />
+  <Breadcrumbs.Link href="#">Docs</Breadcrumbs.Link>
+  <Breadcrumbs.Separator />
+  <Breadcrumbs.Current>Breadcrumbs</Breadcrumbs.Current>
+</Breadcrumbs>
+```
+
+```tsx
+<Breadcrumbs>
+  <Breadcrumbs.Link href="#" icon={<HouseIcon size={16} />}>
+    Home
+  </Breadcrumbs.Link>
+  <Breadcrumbs.Separator />
+  <Breadcrumbs.Link href="#">Projects</Breadcrumbs.Link>
+  <Breadcrumbs.Separator />
+  <Breadcrumbs.Current>Current Project</Breadcrumbs.Current>
+</Breadcrumbs>
+```
+
+```tsx
+<Breadcrumbs>
+  <Breadcrumbs.Current icon={<HouseIcon size={16} />}>
+    Worker Analytics
+  </Breadcrumbs.Current>
+</Breadcrumbs>
+```
+
+```tsx
+<Breadcrumbs>
+  <Breadcrumbs.Link href="#">Home</Breadcrumbs.Link>
+  <Breadcrumbs.Separator />
+  <Breadcrumbs.Current>Breadcrumbs</Breadcrumbs.Current>
+  <Breadcrumbs.Clipboard text="#" />
+</Breadcrumbs>
+```
+
 ---
 
 ### Button
@@ -897,6 +1894,59 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
 
 `bg-sf-base`, `bg-sf-brand`, `bg-sf-brand-hover`, `bg-sf-control`, `bg-sf-danger`, `bg-sf-tint`, `ring-sf-line`, `ring-sf-ring`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  <Button variant="secondary">Button</Button>
+  <Button variant="secondary" shape="square" icon={PlusIcon} aria-label="Add" />
+</div>
+```
+
+```tsx
+<Button variant="primary">Primary</Button>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-3">
+  <Button size="xs" variant="secondary">
+    Extra Small
+  </Button>
+  <Button size="sm" variant="secondary">
+    Small
+  </Button>
+  <Button size="base" variant="secondary">
+    Base
+  </Button>
+  <Button size="lg" variant="secondary">
+    Large
+  </Button>
+</div>
+```
+
+```tsx
+<Button variant="secondary" icon={PlusIcon}>
+  Create Worker
+</Button>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-3">
+  <Button
+    variant="secondary"
+    shape="square"
+    icon={PlusIcon}
+    aria-label="Add item"
+  />
+  <Button
+    variant="secondary"
+    shape="circle"
+    icon={PlusIcon}
+    aria-label="Add item"
+  />
+</div>
+```
+
 ---
 
 ### Checkbox
@@ -985,6 +2035,66 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
+**Examples:**
+
+```tsx
+<Checkbox
+  label="Accept terms and conditions"
+  checked={checked}
+  onCheckedChange={setChecked}
+/>
+```
+
+```tsx
+<Checkbox
+  label="Select all"
+  indeterminate={indeterminate}
+  onCheckedChange={setIndeterminate}
+/>
+```
+
+```tsx
+<Checkbox
+  label="Remember me"
+  controlFirst={false}
+  checked={checked}
+  onCheckedChange={setChecked}
+/>
+```
+
+```tsx
+<Checkbox label="Disabled option" disabled />
+```
+
+```tsx
+<Checkbox label="Invalid option" variant="error" />
+```
+
+```tsx
+<Checkbox.Group
+  legend="Email preferences"
+  description="Choose how you'd like to receive updates"
+  value={preferences}
+  onValueChange={setPreferences}
+>
+  <Checkbox.Item value="email" label="Email notifications" />
+  <Checkbox.Item value="sms" label="SMS notifications" />
+  <Checkbox.Item value="push" label="Push notifications" />
+</Checkbox.Group>
+```
+
+```tsx
+<Checkbox.Group
+  legend="Required preferences"
+  error="Please select at least one notification method"
+  value={[]}
+  onValueChange={() => {}}
+>
+  <Checkbox.Item value="email" label="Email" variant="error" />
+  <Checkbox.Item value="sms" label="SMS" variant="error" />
+</Checkbox.Group>
+```
+
 ---
 
 ### ClipboardText
@@ -1062,6 +2172,19 @@ Read-only text field with a one-click copy-to-clipboard button.
       - borderRadius: 8
       - fontSize: 14
 
+**Examples:**
+
+```tsx
+<ClipboardText text="0c239dd2" />
+```
+
+```tsx
+<ClipboardText
+  text="npx sf add button"
+  tooltip={{ copiedText: "Copied!", side: "top", text: "Copy" }}
+/>
+```
+
 ---
 
 ### Code
@@ -1108,6 +2231,26 @@ Props:
 - `code`: string (required)
 - `lang`: CodeLang
 
+**Examples:**
+
+```tsx
+<CodeBlock
+  lang="tsx"
+  code={`const greeting = "Hello, World!";
+console.log(greeting);`}
+/>
+```
+
+```tsx
+<Code
+  lang="bash"
+  code="export API_KEY={{apiKey}}"
+  values={{
+    apiKey: { highlight: true, value: "sk_live_123" },
+  }}
+/>
+```
+
 ---
 
 ### Collapsible
@@ -1136,6 +2279,30 @@ Collapsible component for showing/hiding content. Features: - Animated chevron i
 
 `border-sf-fill`, `text-sf-link`
 
+**Examples:**
+
+```tsx
+<div className="w-full">
+  <Collapsible label="What is SF?" open={isOpen} onOpenChange={setIsOpen}>
+    A minimal, composable component library for building modern interfaces.
+  </Collapsible>
+</div>
+```
+
+```tsx
+<div className="w-full space-y-2">
+  <Collapsible label="What is SF?" open={open1} onOpenChange={setOpen1}>
+    A minimal, composable component library for building modern interfaces.
+  </Collapsible>
+  <Collapsible label="How do I use it?" open={open2} onOpenChange={setOpen2}>
+    Install the components and import them into your project.
+  </Collapsible>
+  <Collapsible label="Is it open source?" open={open3} onOpenChange={setOpen3}>
+    Check the repository for license information.
+  </Collapsible>
+</div>
+```
+
 ---
 
 ### Combobox
@@ -1258,6 +2425,161 @@ Usage:
 </Combobox.Collection>
 ```
 
+**Examples:**
+
+```tsx
+<Combobox
+  value={value}
+  onValueChange={(v) => setValue(v as string | null)}
+  items={fruits}
+>
+  <Combobox.TriggerInput placeholder="Please select" />
+  <Combobox.Content>
+    <Combobox.Empty />
+    <Combobox.List>
+      {(item: string) => (
+        <Combobox.Item key={item} value={item}>
+          {item}
+        </Combobox.Item>
+      )}
+    </Combobox.List>
+  </Combobox.Content>
+</Combobox>
+```
+
+```tsx
+<Combobox
+  value={value}
+  onValueChange={(v) => setValue(v as Language)}
+  items={languages}
+>
+  <Combobox.TriggerValue className="w-[200px]" />
+  <Combobox.Content>
+    <Combobox.Input placeholder="Search languages" />
+    <Combobox.Empty />
+    <Combobox.List>
+      {(item: Language) => (
+        <Combobox.Item key={item.value} value={item}>
+          {item.emoji} {item.label}
+        </Combobox.Item>
+      )}
+    </Combobox.List>
+  </Combobox.Content>
+</Combobox>
+```
+
+```tsx
+<Combobox
+  value={value}
+  onValueChange={(v) => setValue(v as ServerLocation | null)}
+  items={servers}
+>
+  <Combobox.TriggerInput className="w-[200px]" placeholder="Select server" />
+  <Combobox.Content>
+    <Combobox.Empty />
+    <Combobox.List>
+      {(group: ServerLocationGroup) => (
+        <Combobox.Group key={group.value} items={group.items}>
+          <Combobox.GroupLabel>{group.value}</Combobox.GroupLabel>
+          <Combobox.Collection>
+            {(item: ServerLocation) => (
+              <Combobox.Item key={item.value} value={item}>
+                {item.label}
+              </Combobox.Item>
+            )}
+          </Combobox.Collection>
+        </Combobox.Group>
+      )}
+    </Combobox.List>
+  </Combobox.Content>
+</Combobox>
+```
+
+```tsx
+<div className="flex gap-2">
+  <Combobox
+    value={value}
+    onValueChange={setValue}
+    items={bots}
+    isItemEqualToValue={(bot: BotItem, selected: BotItem) =>
+      bot.value === selected.value
+    }
+    multiple
+  >
+    <Combobox.TriggerMultipleWithInput
+      className="w-[400px]"
+      placeholder="Select bots"
+      renderItem={(selected: BotItem) => (
+        <Combobox.Chip key={selected.value}>{selected.label}</Combobox.Chip>
+      )}
+      inputSide="right"
+    />
+    <Combobox.Content className="max-h-[200px] min-w-auto overflow-y-auto">
+      <Combobox.Empty />
+      <Combobox.List>
+        {(item: BotItem) => (
+          <Combobox.Item key={item.value} value={item}>
+            <div className="flex gap-2">
+              <Text>{item.label}</Text>
+              <Text variant="secondary">{item.author}</Text>
+            </div>
+          </Combobox.Item>
+        )}
+      </Combobox.List>
+    </Combobox.Content>
+  </Combobox>
+  <Button variant="primary">Submit</Button>
+</div>
+```
+
+```tsx
+<div className="w-80">
+  <Combobox
+    items={databases}
+    value={value}
+    onValueChange={setValue}
+    label="Database"
+    description="Select your preferred database"
+  >
+    <Combobox.TriggerInput placeholder="Select database" />
+    <Combobox.Content>
+      <Combobox.Empty />
+      <Combobox.List>
+        {(item: DatabaseItem) => (
+          <Combobox.Item key={item.value} value={item}>
+            {item.label}
+          </Combobox.Item>
+        )}
+      </Combobox.List>
+    </Combobox.Content>
+  </Combobox>
+</div>
+```
+
+```tsx
+<div className="w-80">
+  <Combobox
+    items={databases}
+    value={value}
+    onValueChange={setValue}
+    label="Database"
+    error={{ match: true, message: "Please select a database" }}
+  >
+    <Combobox.TriggerInput placeholder="Select database" />
+    <Combobox.Content>
+      <Combobox.Empty />
+      <Combobox.List>
+        {(item: DatabaseItem) => (
+          <Combobox.Item key={item.value} value={item}>
+            {item.label}
+          </Combobox.Item>
+        )}
+      </Combobox.List>
+    </Combobox.Content>
+  </Combobox>
+</div>
+```
+
 ---
 
 ### CommandPalette
@@ -1281,6 +2603,216 @@ CommandPalette — accessible command palette / spotlight search overlay. Compou
 
 `bg-sf-elevated`, `bg-sf-overlay`, `bg-sf-warning`, `ring-sf-line`, `text-sf-default`, `text-sf-strong`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<div className="flex flex-col items-start gap-4">
+  <Button onClick={() => setOpen(true)}>Open Command Palette</Button>
+  {selectedItem && (
+    <p className="text-sm text-sf-subtle">
+      Last selected: <span className="text-sf-default">{selectedItem}</span>
+    </p>
+  )}
+
+  <CommandPalette.Root
+    open={open}
+    onOpenChange={setOpen}
+    items={sampleGroups}
+    value={search}
+    onValueChange={setSearch}
+    itemToStringValue={(group) => group.label}
+    onSelect={(item, { newTab }) => {
+      console.log("Selected:", item.title, newTab ? "(new tab)" : "");
+      handleSelect(item);
+    }}
+    getSelectableItems={getSelectableItems}
+  >
+    <CommandPalette.Input placeholder="Type a command or search..." />
+    <CommandPalette.List>
+      <CommandPalette.Results>
+        {(group: CommandGroup) => (
+          <CommandPalette.Group key={group.id}>
+            <CommandPalette.GroupLabel>{group.label}</CommandPalette.GroupLabel>
+            <CommandPalette.Items>
+              {(item: CommandItem) => (
+                <CommandPalette.Item
+                  key={item.id}
+                  value={item}
+                  onClick={() => handleSelect(item)}
+                >
+                  <span className="flex items-center gap-3">
+                    {item.icon && (
+                      <span className="text-sf-subtle">{item.icon}</span>
+                    )}
+                    <span>{item.title}</span>
+                  </span>
+                </CommandPalette.Item>
+              )}
+            </CommandPalette.Items>
+          </CommandPalette.Group>
+        )}
+      </CommandPalette.Results>
+      <CommandPalette.Empty>No commands found</CommandPalette.Empty>
+    </CommandPalette.List>
+    <CommandPalette.Footer>
+      <span className="flex items-center gap-2">
+        <kbd className="rounded border border-sf-line bg-sf-base px-1.5 py-0.5 text-[10px]">
+          ↑↓
+        </kbd>
+        <span>Navigate</span>
+      </span>
+      <span className="flex items-center gap-2">
+        <kbd className="rounded border border-sf-line bg-sf-base px-1.5 py-0.5 text-[10px]">
+          ↵
+        </kbd>
+        <span>Select</span>
+      </span>
+    </CommandPalette.Footer>
+  </CommandPalette.Root>
+</div>
+```
+
+```tsx
+<div>
+  <Button onClick={() => setOpen(true)}>Open Simple Palette</Button>
+
+  <CommandPalette.Root
+    open={open}
+    onOpenChange={setOpen}
+    items={simpleItems}
+    value={search}
+    onValueChange={setSearch}
+    itemToStringValue={(item) => item.title}
+    onSelect={(item) => {
+      console.log("Selected:", item.title);
+      setOpen(false);
+    }}
+    getSelectableItems={(items) => items}
+  >
+    <CommandPalette.Input placeholder="Search actions..." />
+    <CommandPalette.List>
+      <CommandPalette.Results>
+        {(item: SimpleItem) => (
+          <CommandPalette.Item
+            key={item.id}
+            value={item}
+            onClick={() => {
+              console.log("Clicked:", item.title);
+              setOpen(false);
+            }}
+          >
+            {item.title}
+          </CommandPalette.Item>
+        )}
+      </CommandPalette.Results>
+      <CommandPalette.Empty>No actions found</CommandPalette.Empty>
+    </CommandPalette.List>
+  </CommandPalette.Root>
+</div>
+```
+
+```tsx
+<div>
+  <Button onClick={handleOpen}>Open with Loading</Button>
+
+  <CommandPalette.Root
+    open={open}
+    onOpenChange={setOpen}
+    items={loading ? [] : sampleGroups}
+    value={search}
+    onValueChange={setSearch}
+    itemToStringValue={(group) => group.label}
+    getSelectableItems={getSelectableItems}
+  >
+    <CommandPalette.Input placeholder="Search..." />
+    <CommandPalette.List>
+      {loading ? (
+        <CommandPalette.Loading />
+      ) : (
+        <>
+          <CommandPalette.Results>
+            {(group: CommandGroup) => (
+              <CommandPalette.Group key={group.id}>
+                <CommandPalette.GroupLabel>
+                  {group.label}
+                </CommandPalette.GroupLabel>
+                <CommandPalette.Items>
+                  {(item: CommandItem) => (
+                    <CommandPalette.Item
+                      key={item.id}
+                      value={item}
+                      onClick={() => setOpen(false)}
+                    >
+                      <span className="flex items-center gap-3">
+                        {item.icon && (
+                          <span className="text-sf-subtle">{item.icon}</span>
+                        )}
+                        <span>{item.title}</span>
+                      </span>
+                    </CommandPalette.Item>
+                  )}
+                </CommandPalette.Items>
+              </CommandPalette.Group>
+            )}
+          </CommandPalette.Results>
+          <CommandPalette.Empty>No results found</CommandPalette.Empty>
+        </>
+      )}
+    </CommandPalette.List>
+  </CommandPalette.Root>
+</div>
+```
+
+```tsx
+<div>
+  <Button onClick={() => setOpen(true)}>Open with ResultItem</Button>
+
+  <CommandPalette.Root
+    open={open}
+    onOpenChange={setOpen}
+    items={searchResults}
+    value={search}
+    onValueChange={setSearch}
+    itemToStringValue={(item) => item.title}
+    getSelectableItems={(items) => items}
+  >
+    <CommandPalette.Input placeholder="Search documentation..." />
+    <CommandPalette.List>
+      <CommandPalette.Results>
+        {(item: SearchResult) => (
+          <CommandPalette.ResultItem
+            key={item.id}
+            value={item}
+            title={item.title}
+            breadcrumbs={item.breadcrumbs}
+            icon={item.icon}
+            onClick={() => {
+              console.log("Navigate to:", item.title);
+              setOpen(false);
+            }}
+          />
+        )}
+      </CommandPalette.Results>
+      <CommandPalette.Empty>No pages found</CommandPalette.Empty>
+    </CommandPalette.List>
+    <CommandPalette.Footer>
+      <span className="flex items-center gap-2">
+        <kbd className="rounded border border-sf-line bg-sf-base px-1.5 py-0.5 text-[10px]">
+          ↑↓
+        </kbd>
+        <span>Navigate</span>
+      </span>
+      <span className="flex items-center gap-2">
+        <kbd className="rounded border border-sf-line bg-sf-base px-1.5 py-0.5 text-[10px]">
+          ⌘↵
+        </kbd>
+        <span>Open in new tab</span>
+      </span>
+    </CommandPalette.Footer>
+  </CommandPalette.Root>
+</div>
+```
+
 ---
 
 ### DataGrid
@@ -1331,6 +2863,137 @@ ColumnToggle sub-component
 
 Empty sub-component
 
+**Examples:**
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <DataGrid data={sampleUsers} columns={columns} enableSorting>
+      <DataGrid.Content />
+    </DataGrid>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <DataGrid
+      data={paginatedData}
+      columns={columns.slice(0, 3)}
+      pageSize={pageSize}
+      pageIndex={pageIndex}
+      onPaginationChange={({ pageIndex: newPage }) => setPageIndex(newPage)}
+      totalCount={totalCount}
+      manualPagination
+    >
+      <DataGrid.Content />
+      <DataGrid.Pagination />
+    </DataGrid>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <DataGrid
+      data={sampleUsers.slice(0, 4)}
+      columns={columns}
+      enableRowSelection
+      rowSelection={rowSelection}
+      onRowSelectionChange={setRowSelection}
+    >
+      <DataGrid.Content />
+    </DataGrid>
+    <div className="border-t border-sf-line p-3 text-sm">
+      <p className="text-sf-subtle">
+        Selected: {Object.keys(rowSelection).length} rows
+      </p>
+    </div>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <DataGrid
+      data={sampleUsers.slice(0, 4)}
+      columns={columns}
+      columnVisibility={columnVisibility}
+      onColumnVisibilityChange={setColumnVisibility}
+    >
+      <DataGrid.Toolbar className="p-3">
+        <DataGrid.ColumnToggle />
+      </DataGrid.Toolbar>
+      <DataGrid.Content />
+    </DataGrid>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <DataGrid data={sampleUsers} columns={columns} enableSorting>
+      <DataGrid.Toolbar className="flex items-center justify-between p-3">
+        <span className="text-sm font-medium">Users</span>
+        <DataGrid.ColumnToggle />
+      </DataGrid.Toolbar>
+      <DataGrid.Content />
+    </DataGrid>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <DataGrid
+      data={[]}
+      columns={columns.slice(0, 3)}
+      emptyState={
+        <div className="flex flex-col items-center justify-center py-12 text-center">
+          <p className="text-sf-strong font-medium">No users found</p>
+          <p className="text-sf-subtle mt-1 text-sm">
+            Try adjusting your filters or add new users
+          </p>
+        </div>
+      }
+    >
+      <DataGrid.Content />
+    </DataGrid>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <DataGrid data={[]} columns={columns.slice(0, 3)} loading loadingRows={3}>
+      <DataGrid.Content />
+    </DataGrid>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <DataGrid
+      data={sampleUsers}
+      columns={resizableColumns}
+      enableSorting
+      enableColumnResizing
+      columnResizeMode="onEnd"
+    >
+      <DataGrid.Content />
+    </DataGrid>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
 ---
 
 ### DatePicker
@@ -1354,6 +3017,154 @@ DatePicker — a date selection calendar. Built on [react-day-picker](https://da
 
 `bg-sf-base`
 
+**Examples:**
+
+```tsx
+<div className="flex flex-col gap-4">
+  <DatePicker
+    mode="single"
+    selected={date}
+    onChange={(d) => {
+      if (d) {
+        setDate(d);
+      }
+    }}
+  />
+  <p className="text-sm text-sf-subtle">
+    Selected: {date ? date.toLocaleDateString() : "None"}
+  </p>
+</div>
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+  <DatePicker mode="multiple" selected={dates} onChange={setDates} max={5} />
+  <p className="text-sm text-sf-subtle">
+    Selected: {dates?.length ?? 0} date(s)
+  </p>
+</div>
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+  <DatePicker
+    mode="range"
+    selected={range}
+    onChange={setRange}
+    numberOfMonths={2}
+  />
+  <p className="text-sm text-sf-subtle">
+    Range:{" "}
+    {range?.from
+      ? `${range.from.toLocaleDateString()} - ${range.to?.toLocaleDateString() ?? "..."}`
+      : "None"}
+  </p>
+</div>
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+  <DatePicker
+    mode="range"
+    selected={range}
+    onChange={setRange}
+    min={3}
+    max={7}
+    footer={<span className="text-xs text-sf-subtle">Select 3-7 nights</span>}
+  />
+</div>
+```
+
+```tsx
+<Popover>
+  <Popover.Trigger asChild>
+    <Button variant="outline" icon={CalendarDotsIcon}>
+      {date ? date.toLocaleDateString() : "Pick a date"}
+    </Button>
+  </Popover.Trigger>
+  <Popover.Content className="p-3">
+    <DatePicker mode="single" selected={date} onChange={setDate} />
+  </Popover.Content>
+</Popover>
+```
+
+```tsx
+<Popover>
+  <Popover.Trigger asChild>
+    <Button variant="outline" icon={CalendarDotsIcon}>
+      {formatRange()}
+    </Button>
+  </Popover.Trigger>
+  <Popover.Content className="p-3">
+    <DatePicker
+      mode="range"
+      selected={range}
+      onChange={setRange}
+      numberOfMonths={2}
+    />
+  </Popover.Content>
+</Popover>
+```
+
+```tsx
+<Popover>
+  <Popover.Trigger asChild>
+    <Button variant="outline" icon={CalendarDotsIcon}>
+      {formatRange()}
+    </Button>
+  </Popover.Trigger>
+  <Popover.Content className="p-0">
+    <div className="flex">
+      <div className="flex flex-col gap-1 border-r border-sf-line p-2 text-sm">
+        {presets.map((preset) => {
+          const isActive = isPresetActive(preset);
+          return (
+            <button
+              key={preset.label}
+              type="button"
+              onClick={() => handlePresetClick(preset)}
+              className={`rounded-md px-3 py-1.5 text-left whitespace-nowrap ${
+                isActive
+                  ? "bg-sf-bg-inverse text-sf-text-inverse"
+                  : "text-sf-strong hover:bg-sf-control"
+              }`}
+            >
+              {preset.label}
+            </button>
+          );
+        })}
+      </div>
+      <div className="p-3">
+        <DatePicker
+          mode="range"
+          selected={range}
+          onChange={setRange}
+          month={month}
+          onMonthChange={setMonth}
+          numberOfMonths={2}
+        />
+      </div>
+    </div>
+  </Popover.Content>
+</Popover>
+```
+
+```tsx
+<DatePicker
+  mode="multiple"
+  selected={dates}
+  onChange={setDates}
+  max={maxDays}
+  disabled={unavailableDates}
+  fixedWeeks
+  footer={
+    <p className="text-xs text-sf-subtle pt-2 w-full">
+      {selectedCount}/{maxDays} days selected. Grayed dates are unavailable.
+    </p>
+  }
+/>
+```
+
 ---
 
 ### DateRangePicker
@@ -1478,6 +3289,228 @@ Description sub-component
 
 Close sub-component
 
+**Examples:**
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger render={(p) => <Button {...p}>Click me</Button>} />
+  <Dialog className="p-8">
+    <div className="mb-4 flex items-start justify-between gap-4">
+      <Dialog.Title className="text-2xl font-semibold">
+        Modal Title
+      </Dialog.Title>
+      <Dialog.Close
+        aria-label="Close"
+        render={(props) => (
+          <Button
+            {...props}
+            variant="secondary"
+            shape="square"
+            icon={<XIcon />}
+            aria-label="Close"
+          />
+        )}
+      />
+    </div>
+    <Dialog.Description className="text-sf-subtle">
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+      tempor incididunt ut labore et dolore magna aliqua.
+    </Dialog.Description>
+  </Dialog>
+</Dialog.Root>
+```
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger render={(p) => <Button {...p}>Delete</Button>} />
+  <Dialog className="p-8">
+    <div className="mb-4 flex items-start justify-between gap-4">
+      <Dialog.Title className="text-2xl font-semibold">
+        Modal Title
+      </Dialog.Title>
+      <Dialog.Close
+        aria-label="Close"
+        render={(props) => (
+          <Button
+            {...props}
+            variant="secondary"
+            shape="square"
+            icon={<XIcon />}
+            aria-label="Close"
+          />
+        )}
+      />
+    </div>
+    <Dialog.Description className="text-sf-subtle">
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+      tempor incididunt ut labore et dolore magna aliqua.
+    </Dialog.Description>
+    <div className="mt-8 flex justify-end gap-2">
+      <Dialog.Close
+        render={(props) => (
+          <Button variant="secondary" {...props}>
+            Cancel
+          </Button>
+        )}
+      />
+      <Dialog.Close
+        render={(props) => (
+          <Button variant="destructive" {...props}>
+            Delete
+          </Button>
+        )}
+      />
+    </div>
+  </Dialog>
+</Dialog.Root>
+```
+
+```tsx
+<Dialog.Root disablePointerDismissal>
+  <Dialog.Trigger
+    render={(p) => (
+      <Button {...p} variant="destructive">
+        Delete Project
+      </Button>
+    )}
+  />
+  <Dialog className="p-8">
+    <div className="mb-4 flex items-center gap-3">
+      <div className="flex h-10 w-10 items-center justify-center rounded-full bg-sf-danger/20">
+        <WarningIcon size={20} className="text-sf-danger" />
+      </div>
+      <Dialog.Title className="text-xl font-semibold">
+        Delete Project?
+      </Dialog.Title>
+    </div>
+    <Dialog.Description className="text-sf-subtle">
+      This action cannot be undone. This will permanently delete the project and
+      all associated data.
+    </Dialog.Description>
+    <div className="mt-8 flex justify-end gap-2">
+      <Dialog.Close
+        render={(props) => (
+          <Button variant="secondary" {...props}>
+            Cancel
+          </Button>
+        )}
+      />
+      <Dialog.Close
+        render={(props) => (
+          <Button variant="destructive" {...props}>
+            Delete
+          </Button>
+        )}
+      />
+    </div>
+  </Dialog>
+</Dialog.Root>
+```
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger render={(p) => <Button {...p}>Open Form</Button>} />
+  <Dialog className="p-8">
+    <div className="mb-4 flex items-start justify-between gap-4">
+      <Dialog.Title className="text-2xl font-semibold">
+        Create Resource
+      </Dialog.Title>
+      <Dialog.Close
+        aria-label="Close"
+        render={(props) => (
+          <Button
+            {...props}
+            variant="secondary"
+            shape="square"
+            icon={<XIcon />}
+            aria-label="Close"
+          />
+        )}
+      />
+    </div>
+    <Dialog.Description className="mb-4 text-sf-subtle">
+      Select a region for your new resource.
+    </Dialog.Description>
+    <Select
+      className="w-full"
+      renderValue={(v) =>
+        regions.find((r) => r.value === v)?.label ?? "Select region..."
+      }
+    >
+      {regions.map((region) => (
+        <Select.Option key={region.value} value={region.value}>
+          {region.label}
+        </Select.Option>
+      ))}
+    </Select>
+    <div className="mt-8 flex justify-end gap-2">
+      <Dialog.Close
+        render={(props) => (
+          <Button variant="secondary" {...props}>
+            Cancel
+          </Button>
+        )}
+      />
+      <Button variant="primary">Create</Button>
+    </div>
+  </Dialog>
+</Dialog.Root>
+```
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger render={(p) => <Button {...p}>Open Form</Button>} />
+  <Dialog className="p-8">
+    <div className="mb-4 flex items-start justify-between gap-4">
+      <Dialog.Title className="text-2xl font-semibold">
+        Create Resource
+      </Dialog.Title>
+      <Dialog.Close
+        aria-label="Close"
+        render={(props) => (
+          <Button
+            {...props}
+            variant="secondary"
+            shape="square"
+            icon={<XIcon />}
+            aria-label="Close"
+          />
+        )}
+      />
+    </div>
+    <Dialog.Description className="mb-4 text-sf-subtle">
+      Search and select a region for your new resource.
+    </Dialog.Description>
+    <Combobox value={value} onValueChange={setValue} items={regions}>
+      <Combobox.TriggerInput
+        className="w-full"
+        placeholder="Search regions..."
+      />
+      <Combobox.Content>
+        <Combobox.Empty>No regions found</Combobox.Empty>
+        <Combobox.List>
+          {(item: { value: string; label: string }) => (
+            <Combobox.Item key={item.value} value={item}>
+              {item.label}
+            </Combobox.Item>
+          )}
+        </Combobox.List>
+      </Combobox.Content>
+    </Combobox>
+    <div className="mt-8 flex justify-end gap-2">
+      <Dialog.Close
+        render={(props) => (
+          <Button variant="secondary" {...props}>
+            Cancel
+          </Button>
+        )}
+      />
+      <Button variant="primary">Create</Button>
+    </div>
+  </Dialog>
+</Dialog.Root>
+```
+
 ---
 
 ### DropdownMenu
@@ -1599,6 +3632,91 @@ Placeholder shown when a list, table, or page has no content to display.
 
 `bg-sf-control`, `bg-sf-overlay`, `border-sf-fill`, `border-sf-interact`, `text-sf-brand`, `text-sf-default`, `text-sf-inactive`, `text-sf-strong`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<Empty
+  icon={<PackageIcon size={48} />}
+  title="No packages found"
+  description="Get started by installing your first package."
+  commandLine="npm install @signalflare-ai/ui"
+  contents={
+    <div className="flex items-center gap-2">
+      <Button icon={<CodeIcon />}>See examples</Button>
+      <Button icon={<GlobeIcon />} variant="primary">
+        View documentation
+      </Button>
+    </div>
+  }
+/>
+```
+
+```tsx
+<div className="flex flex-col gap-8">
+  <div>
+    <p className="mb-2 text-sm text-sf-subtle">Small</p>
+    <Empty
+      size="sm"
+      icon={<DatabaseIcon size={32} className="text-sf-inactive" />}
+      title="No data available"
+      description="There is no data to display."
+    />
+  </div>
+  <div>
+    <p className="mb-2 text-sm text-sf-subtle">Base</p>
+    <Empty
+      size="base"
+      icon={<DatabaseIcon size={48} className="text-sf-inactive" />}
+      title="No data available"
+      description="There is no data to display."
+    />
+  </div>
+  <div>
+    <p className="mb-2 text-sm text-sf-subtle">Large</p>
+    <Empty
+      size="lg"
+      icon={<DatabaseIcon size={64} className="text-sf-inactive" />}
+      title="No data available"
+      description="There is no data to display."
+    />
+  </div>
+</div>
+```
+
+```tsx
+<Empty
+  icon={<FolderOpenIcon size={48} className="text-sf-inactive" />}
+  title="No projects found"
+  description="Get started by creating your first project using the command below."
+  commandLine="npm create sf-project"
+/>
+```
+
+```tsx
+<Empty
+  icon={<CloudSlashIcon size={48} className="text-sf-inactive" />}
+  title="No connection"
+  description="Unable to connect to the server. Please check your connection and try again."
+  contents={
+    <div className="flex gap-2">
+      <Button variant="primary">Retry</Button>
+      <Button variant="secondary">Go Back</Button>
+    </div>
+  }
+/>
+```
+
+```tsx
+<Empty title="Nothing here" />
+```
+
+```tsx
+<Empty
+  title="No results found"
+  description="Try adjusting your search or filter to find what you're looking for."
+/>
+```
+
 ---
 
 ### Field
@@ -1677,6 +3795,61 @@ Filters component for building and managing active filter conditions. Supports m
 
 `bg-sf-fill`, `bg-sf-line`, `bg-sf-overlay`, `bg-sf-tint`, `border-sf-line`, `text-sf-brand`, `text-sf-danger`, `text-sf-default`, `text-sf-strong`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<div className="w-full rounded-lg border border-sf-line bg-sf-base p-4">
+  <Filters filters={filters} fields={filterFields} onChange={setFilters} />
+  <div className="mt-4 rounded bg-sf-elevated p-3 font-mono text-xs">
+    <p className="text-sf-subtle mb-1">Active filters:</p>
+    <pre className="text-sf-strong overflow-x-auto">
+      {JSON.stringify(filters, null, 2)}
+    </pre>
+  </div>
+</div>
+```
+
+```tsx
+<div className="w-full rounded-lg border border-sf-line bg-sf-base p-4">
+  <Filters
+    filters={filters}
+    fields={filterFields.slice(0, 3)}
+    onChange={setFilters}
+    size="sm"
+  />
+</div>
+```
+
+```tsx
+<div className="w-full rounded-lg border border-sf-line bg-sf-base p-4">
+  <Filters
+    filters={filters}
+    fields={filterFields}
+    onChange={setFilters}
+    showSearchInput
+  />
+  <p className="text-sf-subtle mt-3 text-xs">
+    Open the "Add Filter" menu to see grouped fields (General, User Details)
+  </p>
+</div>
+```
+
+```tsx
+<div className="w-full rounded-lg border border-sf-line bg-sf-base p-4">
+  <Filters
+    filters={filters}
+    fields={filterFields.slice(0, 3)}
+    onChange={setFilters}
+    enableShortcut
+    shortcutKey="k"
+    shortcutLabel="Cmd+K"
+  />
+  <p className="text-sf-subtle mt-3 text-xs">
+    Press Cmd+K (or Ctrl+K) to quickly open the add filter menu
+  </p>
+</div>
+```
+
 ---
 
 ### Grid
@@ -1720,6 +3893,229 @@ Responsive CSS grid layout container with preset column configurations.
 
 `border-sf-line`
 
+**Examples:**
+
+```tsx
+<Grid variant="2up" gap="base">
+  <GridItem>
+    <Tile>
+      <div>Item 1</div>
+      <div className="mt-1">First grid item</div>
+    </Tile>
+  </GridItem>
+  <GridItem>
+    <Tile>
+      <div>Item 2</div>
+      <div className="mt-1">Second grid item</div>
+    </Tile>
+  </GridItem>
+</Grid>
+```
+
+```tsx
+<div className="flex flex-col gap-8">
+  <div>
+    <p className="mb-2 text-sf-subtle">variant="2up"</p>
+    <Grid variant="2up" gap="sm">
+      <GridItem>
+        <Tile>
+          <span className="block text-center">1</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">2</span>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+
+  <div>
+    <p className="mb-2 text-sf-subtle">variant="3up"</p>
+    <Grid variant="3up" gap="sm">
+      <GridItem>
+        <Tile>
+          <span className="block text-center">1</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">2</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">3</span>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+
+  <div>
+    <p className="mb-2 text-sf-subtle">variant="4up"</p>
+    <Grid variant="4up" gap="sm">
+      <GridItem>
+        <Tile>
+          <span className="block text-center">1</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">2</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">3</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">4</span>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+</div>
+```
+
+```tsx
+<div className="flex flex-col gap-8">
+  <div>
+    <p className="mb-2 text-sf-subtle">variant="2-1" (66% / 33%)</p>
+    <Grid variant="2-1" gap="sm">
+      <GridItem>
+        <Tile>
+          <div>Main Content</div>
+          <div className="mt-1">Two-thirds width</div>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <div>Sidebar</div>
+          <div className="mt-1">One-third width</div>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+
+  <div>
+    <p className="mb-2 text-sf-subtle">variant="1-2" (33% / 66%)</p>
+    <Grid variant="1-2" gap="sm">
+      <GridItem>
+        <Tile>
+          <div>Sidebar</div>
+          <div className="mt-1">One-third width</div>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <div>Main Content</div>
+          <div className="mt-1">Two-thirds width</div>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+</div>
+```
+
+```tsx
+<div className="flex flex-col gap-8">
+  <div>
+    <p className="mb-2 text-sf-subtle">gap="none"</p>
+    <Grid variant="side-by-side" gap="none">
+      <GridItem>
+        <Tile>
+          <span className="block text-center">1</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">2</span>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+
+  <div>
+    <p className="mb-2 text-sf-subtle">gap="sm"</p>
+    <Grid variant="side-by-side" gap="sm">
+      <GridItem>
+        <Tile>
+          <span className="block text-center">1</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">2</span>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+
+  <div>
+    <p className="mb-2 text-sf-subtle">gap="base" (default, responsive)</p>
+    <Grid variant="side-by-side" gap="base">
+      <GridItem>
+        <Tile>
+          <span className="block text-center">1</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">2</span>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+
+  <div>
+    <p className="mb-2 text-sf-subtle">gap="lg"</p>
+    <Grid variant="side-by-side" gap="lg">
+      <GridItem>
+        <Tile>
+          <span className="block text-center">1</span>
+        </Tile>
+      </GridItem>
+      <GridItem>
+        <Tile>
+          <span className="block text-center">2</span>
+        </Tile>
+      </GridItem>
+    </Grid>
+  </div>
+</div>
+```
+
+```tsx
+<Grid variant="4up" gap="base" mobileDivider>
+  <GridItem>
+    <Tile>
+      <div>Item 1</div>
+      <div className="mt-1">Has divider on mobile</div>
+    </Tile>
+  </GridItem>
+  <GridItem>
+    <Tile>
+      <div>Item 2</div>
+      <div className="mt-1">Has divider on mobile</div>
+    </Tile>
+  </GridItem>
+  <GridItem>
+    <Tile>
+      <div>Item 3</div>
+      <div className="mt-1">Has divider on mobile</div>
+    </Tile>
+  </GridItem>
+  <GridItem>
+    <Tile>
+      <div>Item 4</div>
+      <div className="mt-1">Has divider on mobile</div>
+    </Tile>
+  </GridItem>
+</Grid>
+```
+
 ---
 
 ### Input
@@ -1765,6 +4161,87 @@ Input component
 
 - **Dimensions:** `[object Object]`
 
+**Examples:**
+
+```tsx
+<Input
+  label="Email"
+  placeholder="you@example.com"
+  description="We'll never share your email"
+/>
+```
+
+```tsx
+<Input
+  label="Email"
+  placeholder="you@example.com"
+  value="invalid-email"
+  variant="error"
+  error="Please enter a valid email address"
+/>
+```
+
+```tsx
+<Input
+  label="Password"
+  type="password"
+  value="short"
+  variant="error"
+  error={{
+    match: "tooShort",
+    message: "Password must be at least 8 characters",
+  }}
+  minLength={8}
+/>
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Input size="xs" label="Extra Small" placeholder="Extra small input" />
+  <Input size="sm" label="Small" placeholder="Small input" />
+  <Input label="Base" placeholder="Base input (default)" />
+  <Input size="lg" label="Large" placeholder="Large input" />
+</div>
+```
+
+```tsx
+<Input label="Disabled field" placeholder="Cannot edit" disabled />
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Input type="email" label="Email" placeholder="you@example.com" />
+  <Input type="password" label="Password" placeholder="••••••••" />
+  <Input type="number" label="Age" placeholder="18" />
+  <Input type="tel" label="Phone" placeholder="+1 (555) 000-0000" />
+</div>
+```
+
+```tsx
+<Input label="Phone Number" required={false} placeholder="+1 (555) 000-0000" />
+```
+
+```tsx
+<Input
+  label="API Key"
+  labelTooltip="Find this in your dashboard under Settings > API Keys"
+  placeholder="sk_live_..."
+/>
+```
+
+```tsx
+<Input
+  label={
+    <span>
+      Email for <strong>billing</strong>
+    </span>
+  }
+  required
+  placeholder="billing@company.com"
+  type="email"
+/>
+```
+
 ---
 
 ### Label
@@ -1796,6 +4273,56 @@ Label component for form fields. Provides a standardized way to display labels w
 
 `text-sf-default`, `text-sf-strong`
 
+**Examples:**
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Label>Default Label</Label>
+  <Label showOptional>Optional Label</Label>
+  <Label tooltip="More information about this field">Label with Tooltip</Label>
+</div>
+```
+
+```tsx
+<Input label="Phone Number" required={false} placeholder="+1 555-0000" />
+```
+
+```tsx
+<Input
+  label="API Key"
+  labelTooltip="Find this in your dashboard settings under API > Keys"
+  placeholder="sk_live_..."
+/>
+```
+
+```tsx
+<Checkbox
+  label={
+    <span>
+      I agree to the <strong>Terms of Service</strong>
+    </span>
+  }
+/>
+```
+
+```tsx
+<div className="flex max-w-md flex-col gap-4">
+  <Input label="Full Name" placeholder="John Doe" />
+  <Input
+    label="Email"
+    labelTooltip="We'll send your receipt here"
+    placeholder="john@example.com"
+    type="email"
+  />
+  <Input label="Company" required={false} placeholder="Acme Inc." />
+  <Select label="Country" hideLabel={false} placeholder="Select a country">
+    <Select.Option value="us">United States</Select.Option>
+    <Select.Option value="uk">United Kingdom</Select.Option>
+    <Select.Option value="ca">Canada</Select.Option>
+  </Select>
+</div>
+```
+
 ---
 
 ### LayerCard
@@ -1828,10 +4355,64 @@ This is a compound component. Use these sub-components:
 
 Primary sub-component
 
+Props:
+
+- `className`: string
+
 #### LayerCard.Secondary
 
 Secondary sub-component
 
+Props:
+
+- `className`: string
+
+**Examples:**
+
+```tsx
+<LayerCard>
+  <LayerCard.Secondary className="flex items-center justify-between">
+    <div>Next Steps</div>
+    <Button
+      variant="ghost"
+      size="sm"
+      shape="square"
+      aria-label="Go to next steps"
+    >
+      <ArrowRightIcon size={16} />
+    </Button>
+  </LayerCard.Secondary>
+
+  <LayerCard.Primary>Get started with SF</LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard className="w-[250px]">
+  <LayerCard.Secondary>Getting Started</LayerCard.Secondary>
+  <LayerCard.Primary>
+    <p className="text-sm text-sf-subtle">Quick start guide for new users</p>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<div className="flex gap-4">
+  <LayerCard className="w-[200px]">
+    <LayerCard.Secondary>Components</LayerCard.Secondary>
+    <LayerCard.Primary>
+      <p className="text-sm">Browse all components</p>
+    </LayerCard.Primary>
+  </LayerCard>
+  <LayerCard className="w-[200px]">
+    <LayerCard.Secondary>Examples</LayerCard.Secondary>
+    <LayerCard.Primary>
+      <p className="text-sm">View code examples</p>
+    </LayerCard.Primary>
+  </LayerCard>
+</div>
+```
+
 ---
 
 ### Link
@@ -1882,6 +4463,69 @@ This is a compound component. Use these sub-components:
 
 ExternalIcon sub-component
 
+**Examples:**
+
+```tsx
+<div className="grid gap-x-6 gap-y-4 text-base md:grid-cols-3">
+  <Link href="#">Default inline link</Link>
+  <Link href="#" variant="current">
+    Current color link
+  </Link>
+  <Link href="#" variant="plain">
+    Plain inline link
+  </Link>
+</div>
+```
+
+```tsx
+<p className="mx-auto max-w-md text-base leading-relaxed text-sf-default">
+  This is a paragraph with an <Link href="#">inline link</Link> that flows
+  naturally with the surrounding text. Links maintain proper underline offset
+  for readability.
+</p>
+```
+
+```tsx
+<Link
+  href="https://cloudflare.com"
+  target="_blank"
+  rel="noopener noreferrer"
+  className="text-base"
+>
+  Visit Cloudflare <Link.ExternalIcon />
+</Link>
+```
+
+```tsx
+<p className="text-base text-sf-danger">
+  This error message contains a{" "}
+  <Link href="#" variant="current">
+    link
+  </Link>{" "}
+  that inherits the red color from its parent.
+</p>
+```
+
+```tsx
+<div className="flex flex-col gap-x-6 gap-y-4 text-base md:flex-row">
+  <Link render={<CustomRouterLink href="/dashboard" />} variant="inline">
+    Dashboard (via render)
+  </Link>
+  <Link
+    render={
+      <CustomRouterLink
+        href="https://developers.cloudflare.com"
+        target="_blank"
+        rel="noopener noreferrer"
+      />
+    }
+    variant="inline"
+  >
+    Cloudflare Docs <Link.ExternalIcon />
+  </Link>
+</div>
+```
+
 ---
 
 ### Loader
@@ -1903,6 +4547,20 @@ Animated circular spinner for indicating loading states. Uses CSS keyframe anima
   - `"base"`: Default loader size
   - `"lg"`: Large loader for prominent loading states
 
+**Examples:**
+
+```tsx
+<div className="flex items-center gap-4">
+  <Loader size="sm" />
+  <Loader size="base" />
+  <Loader size="lg" />
+</div>
+```
+
+```tsx
+<Loader size={24} />
+```
+
 ---
 
 ### MenuBar
@@ -1932,6 +4590,29 @@ MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation. E
 
 **Styling:**
 
+**Examples:**
+
+```tsx
+<MenuBar
+  isActive="bold"
+  optionIds
+  options={[
+    {
+      icon: <TextBolderIcon />,
+      id: "bold",
+      onClick: () => {},
+      tooltip: "Bold",
+    },
+    {
+      icon: <TextItalicIcon />,
+      id: "italic",
+      onClick: () => {},
+      tooltip: "Italic",
+    },
+  ]}
+/>
+```
+
 ---
 
 ### Meter
@@ -1967,6 +4648,28 @@ Progress bar showing a measured value within a known range (e.g. quota usage).
 
 `bg-sf-fill`, `text-sf-default`, `text-sf-strong`
 
+**Examples:**
+
+```tsx
+<Meter label="Storage used" value={65} />
+```
+
+```tsx
+<Meter label="API requests" value={75} customValue="750 / 1,000" />
+```
+
+```tsx
+<Meter label="Progress" value={40} showValue={false} />
+```
+
+```tsx
+<Meter
+  label="Upload progress"
+  value={80}
+  indicatorClassName="from-green-500 via-green-500 to-green-500"
+/>
+```
+
 ---
 
 ### Pagination
@@ -2001,6 +4704,32 @@ Page navigation controls with page count display.
 
 **Styling:**
 
+**Examples:**
+
+```tsx
+<Pagination page={page} setPage={setPage} perPage={10} totalCount={100} />
+```
+
+```tsx
+<Pagination
+  page={page}
+  setPage={setPage}
+  perPage={10}
+  totalCount={100}
+  controls="simple"
+/>
+```
+
+```tsx
+<Pagination
+  text={({ perPage }) => `Page ${page} - showing ${perPage} per page`}
+  page={page}
+  setPage={setPage}
+  perPage={25}
+  totalCount={100}
+/>
+```
+
 ---
 
 ### Popover
@@ -2033,10 +4762,22 @@ This is a compound component. Use these sub-components:
 
 Trigger sub-component
 
+Props:
+
+- `asChild`: boolean
+
 #### Popover.Content
 
 Content sub-component
 
+Props:
+
+- `align`: PopoverAlign
+- `sideOffset`: number
+- `alignOffset`: number
+- `className`: string
+- `children`: ReactNode
+
 #### Popover.Title
 
 Title sub-component
@@ -2049,6 +4790,150 @@ Description sub-component
 
 Close sub-component
 
+Props:
+
+- `asChild`: boolean
+
+**Examples:**
+
+```tsx
+<Popover>
+  <Popover.Trigger asChild>
+    <Button shape="square" icon={BellIcon} aria-label="Notifications" />
+  </Popover.Trigger>
+  <Popover.Content>
+    <Popover.Title>Notifications</Popover.Title>
+    <Popover.Description>You are all caught up. Good job!</Popover.Description>
+  </Popover.Content>
+</Popover>
+```
+
+```tsx
+<Popover>
+  <Popover.Trigger asChild>
+    <Button>Open Popover</Button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <Popover.Title>Popover Title</Popover.Title>
+    <Popover.Description>
+      This is a basic popover with a title and description.
+    </Popover.Description>
+  </Popover.Content>
+</Popover>
+```
+
+```tsx
+<Popover>
+  <Popover.Trigger asChild>
+    <Button>Open Settings</Button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <Popover.Title>Settings</Popover.Title>
+    <Popover.Description>Configure your preferences below.</Popover.Description>
+    <div className="mt-3">
+      <Popover.Close asChild>
+        <Button variant="secondary" size="sm">
+          Close
+        </Button>
+      </Popover.Close>
+    </div>
+  </Popover.Content>
+</Popover>
+```
+
+```tsx
+<div className="flex flex-wrap gap-4">
+  <Popover>
+    <Popover.Trigger asChild>
+      <Button variant="secondary">Bottom</Button>
+    </Popover.Trigger>
+    <Popover.Content side="bottom">
+      <Popover.Title>Bottom</Popover.Title>
+      <Popover.Description>Popover on bottom (default).</Popover.Description>
+    </Popover.Content>
+  </Popover>
+
+  <Popover>
+    <Popover.Trigger asChild>
+      <Button variant="secondary">Top</Button>
+    </Popover.Trigger>
+    <Popover.Content side="top">
+      <Popover.Title>Top</Popover.Title>
+      <Popover.Description>Popover on top.</Popover.Description>
+    </Popover.Content>
+  </Popover>
+
+  <Popover>
+    <Popover.Trigger asChild>
+      <Button variant="secondary">Left</Button>
+    </Popover.Trigger>
+    <Popover.Content side="left">
+      <Popover.Title>Left</Popover.Title>
+      <Popover.Description>Popover on left.</Popover.Description>
+    </Popover.Content>
+  </Popover>
+
+  <Popover>
+    <Popover.Trigger asChild>
+      <Button variant="secondary">Right</Button>
+    </Popover.Trigger>
+    <Popover.Content side="right">
+      <Popover.Title>Right</Popover.Title>
+      <Popover.Description>Popover on right.</Popover.Description>
+    </Popover.Content>
+  </Popover>
+</div>
+```
+
+```tsx
+<Popover>
+  <Popover.Trigger asChild>
+    <Button>User Profile</Button>
+  </Popover.Trigger>
+  <Popover.Content className="w-64">
+    <div className="flex items-center gap-3">
+      <div className="size-10 rounded-full bg-sf-recessed" />
+      <div>
+        <Popover.Title>Jane Doe</Popover.Title>
+        <p className="text-sm text-sf-subtle">jane@example.com</p>
+      </div>
+    </div>
+    <div className="mt-3 flex gap-2 border-t border-sf-line pt-3">
+      <Button variant="secondary" size="sm" className="flex-1">
+        Profile
+      </Button>
+      <Popover.Close asChild>
+        <Button variant="ghost" size="sm" className="flex-1">
+          Sign Out
+        </Button>
+      </Popover.Close>
+    </div>
+  </Popover.Content>
+</Popover>
+```
+
+```tsx
+<Popover>
+  <Popover.Trigger openOnHover delay={200} asChild>
+    <Button variant="secondary">Hover Me</Button>
+  </Popover.Trigger>
+  <Popover.Content>
+    <Popover.Title>Hover Triggered</Popover.Title>
+    <Popover.Description>
+      This popover opens on hover with a 200ms delay. It can still contain
+      interactive content like buttons and links.
+    </Popover.Description>
+    <div className="mt-3">
+      <Popover.Close asChild>
+        <Button variant="secondary" size="sm">
+          Got it
+        </Button>
+      </Popover.Close>
+    </div>
+  </Popover.Content>
+</Popover>
+```
+
 ---
 
 ### PromptInput
@@ -2071,8 +4956,10 @@ Prompt input form. Can be self-managed or controlled via `PromptInputProvider`.
   Maximum file size in bytes.
 - `backLayer`: ReactNode
   Content rendered in the collapsible back layer (e.g. HITL approvals, task lists). When provided the prompt input is wrapped in a LayerCard shell with a header row containing a chevron toggle. Use `PromptInputBackLayer` to compose structured content for this slot.
-- `backLayerTitle`: string
-  Title shown in the back layer header row. Defaults to `"Context"`.
+- `backLayerTitle`: ReactNode
+  Header content shown in the back layer header row. Strings render as plain text; pass JSX to compose with icons/spinners/badges. Defaults to `"Context"`.
+- `backLayerStatus`: enum
+  Optional status indicator rendered next to the title. `"running"` shows a small spinner; `"error"` shows an inline error icon. Use this instead of composing JSX into `backLayerTitle` for the common case of an agent doing work.
 - `backLayerOpen`: boolean
   Controls whether the back layer is visible. Pair with `onBackLayerOpenChange` for a controlled pattern.
 - `autoOpenBackLayerWhen`: boolean
@@ -2085,7 +4972,7 @@ Prompt input form. Can be self-managed or controlled via `PromptInputProvider`.
 
 **Colors (sf tokens used):**
 
-`bg-sf-base`, `bg-sf-control`, `bg-sf-elevated`, `bg-sf-info-tint`, `bg-sf-overlay`, `bg-sf-tint`, `border-sf-info`, `ring-sf-line`, `ring-sf-ring`, `text-sf-brand`, `text-sf-default`, `text-sf-inactive`, `text-sf-strong`, `text-sf-subtle`
+`bg-sf-base`, `bg-sf-control`, `bg-sf-elevated`, `bg-sf-info-tint`, `bg-sf-overlay`, `bg-sf-tint`, `border-sf-info`, `ring-sf-line`, `ring-sf-ring`, `text-sf-brand`, `text-sf-danger`, `text-sf-default`, `text-sf-inactive`, `text-sf-strong`, `text-sf-subtle`
 
 **Sub-Components:**
 
@@ -2095,6 +4982,10 @@ This is a compound component. Use these sub-components:
 
 BackLayer sub-component
 
+Props:
+
+- `className`: string
+
 #### PromptInput.Textarea
 
 Textarea sub-component
@@ -2127,10 +5018,18 @@ AddTagButton sub-component
 
 Tags sub-component
 
+Props:
+
+- `children`: (tag: PromptInputTagData) => ReactNode (required)
+
 #### PromptInput.Tag
 
 Tag sub-component
 
+Props:
+
+- `data`: PromptInputTagData (required)
+
 #### PromptInput.AttachButton
 
 AttachButton sub-component
@@ -2139,10 +5038,17 @@ AttachButton sub-component
 
 Attachments sub-component
 
+Props:
+
+- `children`: (attachment: AttachmentFile) => ReactNode (required)
+
 #### PromptInput.Attachment
 
 Attachment sub-component
 
+Props:
+
+- `data`: AttachmentFile (required)
 
 ---
 
@@ -2183,6 +5089,77 @@ Radio — radio button group for single-select choices. Compound component: `Rad
 
 `bg-sf-base`, `bg-sf-contrast`, `border-sf-line`, `ring-sf-danger`, `ring-sf-interact`, `ring-sf-ring`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<Radio.Group
+  legend="Notification preference"
+  value={value}
+  onValueChange={setValue}
+>
+  <Radio.Item label="Email" value="email" />
+  <Radio.Item label="SMS" value="sms" />
+  <Radio.Item label="Push notification" value="push" />
+</Radio.Group>
+```
+
+```tsx
+<Radio.Group
+  legend="Size"
+  orientation="horizontal"
+  value={value}
+  onValueChange={setValue}
+>
+  <Radio.Item label="Small" value="sm" />
+  <Radio.Item label="Medium" value="md" />
+  <Radio.Item label="Large" value="lg" />
+</Radio.Group>
+```
+
+```tsx
+<Radio.Group
+  legend="Shipping method"
+  description="Choose how you'd like to receive your order"
+  value={value}
+  onValueChange={setValue}
+>
+  <Radio.Item label="Standard (5-7 days)" value="standard" />
+  <Radio.Item label="Express (2-3 days)" value="express" />
+  <Radio.Item label="Overnight" value="overnight" />
+</Radio.Group>
+```
+
+```tsx
+<Radio.Group
+  legend="Payment method"
+  error="Please select a payment method to continue"
+>
+  <Radio.Item label="Credit Card" value="card" variant="error" />
+  <Radio.Item label="PayPal" value="paypal" variant="error" />
+  <Radio.Item label="Bank Transfer" value="bank" variant="error" />
+</Radio.Group>
+```
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Radio.Group legend="Disabled group" disabled defaultValue="a">
+    <Radio.Item label="Option A" value="a" />
+    <Radio.Item label="Option B" value="b" />
+  </Radio.Group>
+  <Radio.Group legend="Individual disabled" defaultValue="available">
+    <Radio.Item label="Available" value="available" />
+    <Radio.Item label="Unavailable" value="unavailable" disabled />
+  </Radio.Group>
+</div>
+```
+
+```tsx
+<Radio.Group legend="Preferences" controlPosition="end" defaultValue="a">
+  <Radio.Item label="Label before radio" value="a" />
+  <Radio.Item label="Another option" value="b" />
+</Radio.Group>
+```
+
 ---
 
 ### Select
@@ -2240,6 +5217,105 @@ This is a compound component. Use these sub-components:
 
 Option sub-component
 
+**Examples:**
+
+```tsx
+<Select
+  className="w-[200px]"
+  value={value}
+  onValueChange={(v) => setValue(v ?? "apple")}
+  items={{ apple: "Apple", banana: "Banana", cherry: "Cherry" }}
+>
+  <Select.Option value="apple">Apple</Select.Option>
+  <Select.Option value="banana">Banana</Select.Option>
+  <Select.Option value="cherry">Cherry</Select.Option>
+</Select>
+```
+
+```tsx
+<Select
+  className="w-[200px]"
+  renderValue={(v) => (
+    <span>
+      {v.emoji} {v.label}
+    </span>
+  )}
+  value={value}
+  onValueChange={(v) => setValue(v as (typeof languages)[0])}
+>
+  {languages.map((language) => (
+    <Select.Option key={language.value} value={language}>
+      {language.emoji} {language.label}
+    </Select.Option>
+  ))}
+</Select>
+```
+
+```tsx
+<Select className="w-[200px]" loading />
+```
+
+```tsx
+<Select
+  className="w-[200px]"
+  loading={loading}
+  value={value}
+  onValueChange={(v) => setValue(v as string | null)}
+  placeholder="Please select"
+>
+  {data?.map((item) => (
+    <Select.Option key={item} value={item}>
+      {item}
+    </Select.Option>
+  ))}
+</Select>
+```
+
+```tsx
+<Select
+  className="w-[250px]"
+  multiple
+  renderValue={(value) => {
+    if (value.length > 3) {
+      return (
+        <span className="line-clamp-1">
+          {value.slice(2).join(", ") + ` and ${value.length - 2} more`}
+        </span>
+      );
+    }
+    return <span>{value.join(", ")}</span>;
+  }}
+  value={value}
+  onValueChange={(v) => setValue(v as string[])}
+>
+  <Select.Option value="Name">Name</Select.Option>
+  <Select.Option value="Location">Location</Select.Option>
+  <Select.Option value="Size">Size</Select.Option>
+  <Select.Option value="Read">Read</Select.Option>
+  <Select.Option value="Write">Write</Select.Option>
+  <Select.Option value="CreatedAt">Created At</Select.Option>
+</Select>
+```
+
+```tsx
+<Select
+  className="w-[200px]"
+  onValueChange={(v) => setValue(v as (typeof authors)[0] | null)}
+  value={value}
+  isItemEqualToValue={(item, value) => item?.id === value?.id}
+  renderValue={(author) => author?.name ?? "Please select author"}
+>
+  {authors.map((author) => (
+    <Select.Option key={author.id} value={author}>
+      <div className="flex w-[300px] items-center justify-between gap-2">
+        <Text>{author.name}</Text>
+        <Text variant="secondary">{author.title}</Text>
+      </div>
+    </Select.Option>
+  ))}
+</Select>
+```
+
 ---
 
 ### SensitiveInput
@@ -2295,6 +5371,76 @@ Password/secret input that masks its value by default and reveals on click. Incl
 
 `bg-sf-brand`, `bg-sf-control`, `outline-sf-ring`, `text-sf-default`, `text-sf-subtle`
 
+**Examples:**
+
+```tsx
+<div className="w-80">
+  <SensitiveInput label="API Key" defaultValue="sk_live_abc123xyz789" />
+</div>
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+  {sizes.map((size) => (
+    <div key={size} className="flex items-center gap-2">
+      <span className="w-12 text-sm text-sf-subtle">{size}</span>
+      <SensitiveInput
+        label={`${size} size`}
+        size={size}
+        defaultValue="secret-api-key-123"
+      />
+    </div>
+  ))}
+</div>
+```
+
+```tsx
+<div className="flex w-80 flex-col gap-4">
+  <SensitiveInput
+    label="Controlled Secret"
+    value={value}
+    onValueChange={setValue}
+  />
+  <div className="text-sm text-sf-subtle">
+    Current value: <code className="text-sf-default">{value}</code>
+  </div>
+  <div className="flex gap-2">
+    <Button
+      onClick={() => setValue("new-secret-" + Date.now())}
+      variant="primary"
+      size="sm"
+    >
+      Change value
+    </Button>
+    <Button onClick={() => setValue("")} variant="secondary" size="sm">
+      Clear
+    </Button>
+  </div>
+</div>
+```
+
+```tsx
+<div className="flex w-80 flex-col gap-4">
+  <SensitiveInput
+    label="Error State"
+    variant="error"
+    defaultValue="invalid-key"
+    error="This API key is not valid"
+  />
+  <SensitiveInput label="Disabled" defaultValue="cannot-edit" disabled />
+  <SensitiveInput
+    label="Read-only"
+    defaultValue="view-only-secret-key"
+    readOnly
+  />
+  <SensitiveInput
+    label="With Description"
+    defaultValue="my-secret-value"
+    description="Keep this value secure and don't share it"
+  />
+</div>
+```
+
 ---
 
 ### Sidebar
@@ -2457,6 +5603,283 @@ CollapsibleTrigger sub-component
 
 CollapsibleContent sub-component
 
+**Examples:**
+
+```tsx
+<DemoContainer>
+  <Sidebar.Provider defaultOpen className="min-h-0! h-full">
+    <Sidebar>
+      <Sidebar.Content>
+        <Sidebar.Group>
+          <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
+          <Sidebar.Menu>
+            <Sidebar.MenuButton icon={HouseIcon} active>
+              Home
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={ChartBarIcon}>
+              Analytics
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={GlobeIcon}>Domains</Sidebar.MenuButton>
+          </Sidebar.Menu>
+        </Sidebar.Group>
+
+        <Sidebar.Group>
+          <Sidebar.GroupLabel>Build</Sidebar.GroupLabel>
+          <Sidebar.Menu>
+            <Sidebar.MenuItem>
+              <Sidebar.Collapsible defaultOpen>
+                <Sidebar.CollapsibleTrigger
+                  render={
+                    <Sidebar.MenuButton icon={CodeIcon}>
+                      Compute
+                      <Sidebar.MenuChevron />
+                    </Sidebar.MenuButton>
+                  }
+                />
+                <Sidebar.CollapsibleContent>
+                  <Sidebar.MenuSub>
+                    <Sidebar.MenuSubButton>Workers</Sidebar.MenuSubButton>
+                    <Sidebar.MenuSubButton>
+                      Durable Objects
+                    </Sidebar.MenuSubButton>
+                  </Sidebar.MenuSub>
+                </Sidebar.CollapsibleContent>
+              </Sidebar.Collapsible>
+            </Sidebar.MenuItem>
+            <Sidebar.MenuButton icon={DatabaseIcon}>Storage</Sidebar.MenuButton>
+          </Sidebar.Menu>
+        </Sidebar.Group>
+      </Sidebar.Content>
+    </Sidebar>
+    <DemoMain />
+  </Sidebar.Provider>
+</DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+  <Sidebar.Provider defaultOpen className="min-h-0! h-full">
+    <Sidebar>
+      <Sidebar.Content>
+        <Sidebar.Group collapsible defaultOpen>
+          <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
+          <Sidebar.GroupContent>
+            <Sidebar.Menu>
+              <Sidebar.MenuButton icon={HouseIcon} active>
+                Home
+              </Sidebar.MenuButton>
+              <Sidebar.MenuButton icon={ChartBarIcon}>
+                Analytics
+              </Sidebar.MenuButton>
+              <Sidebar.MenuButton icon={GlobeIcon}>Domains</Sidebar.MenuButton>
+            </Sidebar.Menu>
+          </Sidebar.GroupContent>
+        </Sidebar.Group>
+
+        <Sidebar.Group collapsible defaultOpen={false}>
+          <Sidebar.GroupLabel>Settings</Sidebar.GroupLabel>
+          <Sidebar.GroupContent>
+            <Sidebar.Menu>
+              <Sidebar.MenuButton icon={ShieldCheckIcon}>
+                Security
+              </Sidebar.MenuButton>
+              <Sidebar.MenuButton icon={LockIcon}>
+                Access Control
+              </Sidebar.MenuButton>
+            </Sidebar.Menu>
+          </Sidebar.GroupContent>
+        </Sidebar.Group>
+      </Sidebar.Content>
+    </Sidebar>
+    <DemoMain />
+  </Sidebar.Provider>
+</DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+  <Sidebar.Provider defaultOpen className="min-h-0! h-full">
+    <Sidebar>
+      <Sidebar.Header>
+        <BrandLogo />
+      </Sidebar.Header>
+      <Sidebar.Content>
+        <Sidebar.Group>
+          <Sidebar.Menu>
+            <Sidebar.MenuButton icon={HouseIcon} tooltip="Home" active>
+              Home
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={ChartBarIcon} tooltip="Analytics">
+              Analytics
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={CodeIcon} tooltip="Compute">
+              Compute
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={DatabaseIcon} tooltip="Storage">
+              Storage
+            </Sidebar.MenuButton>
+          </Sidebar.Menu>
+        </Sidebar.Group>
+      </Sidebar.Content>
+      <Sidebar.Footer>
+        <Sidebar.Trigger />
+      </Sidebar.Footer>
+    </Sidebar>
+    <DemoMain>
+      <ToggleButton />
+      <p className="text-sm">
+        Click the button or the sidebar trigger to toggle
+      </p>
+    </DemoMain>
+  </Sidebar.Provider>
+</DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+  <Sidebar.Provider defaultOpen className="min-h-0! h-full">
+    <Sidebar>
+      <Sidebar.Header>
+        <BrandLogo />
+      </Sidebar.Header>
+
+      <Sidebar.Content>
+        <div className="px-1 pb-2">
+          <Sidebar.Input placeholder="Quick search..." shortcut="⌘K" />
+        </div>
+
+        <Sidebar.Group>
+          <Sidebar.GroupLabel>Overview</Sidebar.GroupLabel>
+          <Sidebar.Menu>
+            <Sidebar.MenuButton icon={HouseIcon} active>
+              Home
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={ChartBarIcon}>
+              Analytics
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={GlobeIcon}>Domains</Sidebar.MenuButton>
+          </Sidebar.Menu>
+        </Sidebar.Group>
+
+        <Sidebar.Separator />
+
+        <Sidebar.Group>
+          <Sidebar.GroupLabel>Build</Sidebar.GroupLabel>
+          <Sidebar.Menu>
+            <Sidebar.MenuItem>
+              <Sidebar.Collapsible defaultOpen>
+                <Sidebar.CollapsibleTrigger
+                  render={
+                    <Sidebar.MenuButton icon={CodeIcon}>
+                      Compute
+                      <Sidebar.MenuChevron />
+                    </Sidebar.MenuButton>
+                  }
+                />
+                <Sidebar.CollapsibleContent>
+                  <Sidebar.MenuSub>
+                    <Sidebar.MenuSubButton>Workers</Sidebar.MenuSubButton>
+                    <Sidebar.MenuSubButton>
+                      Durable Objects
+                    </Sidebar.MenuSubButton>
+                    <Sidebar.MenuSubButton>
+                      Containers
+                      <Sidebar.MenuBadge>Beta</Sidebar.MenuBadge>
+                    </Sidebar.MenuSubButton>
+                  </Sidebar.MenuSub>
+                </Sidebar.CollapsibleContent>
+              </Sidebar.Collapsible>
+            </Sidebar.MenuItem>
+            <Sidebar.MenuButton icon={DatabaseIcon}>Storage</Sidebar.MenuButton>
+          </Sidebar.Menu>
+        </Sidebar.Group>
+
+        <Sidebar.Group>
+          <Sidebar.GroupLabel>Security</Sidebar.GroupLabel>
+          <Sidebar.Menu>
+            <Sidebar.MenuButton icon={ShieldCheckIcon}>
+              Firewall
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={LockIcon}>
+              Access
+              <Sidebar.MenuBadge>Beta</Sidebar.MenuBadge>
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={BellIcon}>
+              Notifications
+            </Sidebar.MenuButton>
+          </Sidebar.Menu>
+        </Sidebar.Group>
+      </Sidebar.Content>
+
+      <Sidebar.Footer>
+        <Sidebar.MenuButton icon={GearIcon}>Settings</Sidebar.MenuButton>
+      </Sidebar.Footer>
+    </Sidebar>
+    <DemoMain />
+  </Sidebar.Provider>
+</DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+  <Sidebar.Provider
+    defaultOpen
+    resizable
+    defaultWidth={240}
+    minWidth={180}
+    maxWidth={400}
+    className="min-h-0! h-full"
+  >
+    <Sidebar>
+      <Sidebar.Header>
+        <BrandLogo />
+      </Sidebar.Header>
+      <Sidebar.Content>
+        <Sidebar.Group>
+          <Sidebar.Menu>
+            <Sidebar.MenuButton icon={HouseIcon} active>
+              Home
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={ChartBarIcon}>
+              Analytics
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={GlobeIcon}>Domains</Sidebar.MenuButton>
+          </Sidebar.Menu>
+        </Sidebar.Group>
+      </Sidebar.Content>
+      <Sidebar.ResizeHandle />
+    </Sidebar>
+    <DemoMain>
+      <p className="text-sm">Drag the sidebar edge to resize</p>
+    </DemoMain>
+  </Sidebar.Provider>
+</DemoContainer>
+```
+
+```tsx
+<DemoContainer>
+  <Sidebar.Provider defaultOpen side="right" className="min-h-0! h-full">
+    <DemoMain>
+      <p className="text-sm">Sidebar on the right</p>
+    </DemoMain>
+    <Sidebar>
+      <Sidebar.Content>
+        <Sidebar.Group>
+          <Sidebar.GroupLabel>Details</Sidebar.GroupLabel>
+          <Sidebar.Menu>
+            <Sidebar.MenuButton icon={GearIcon} active>
+              Properties
+            </Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={ChartBarIcon}>Metrics</Sidebar.MenuButton>
+            <Sidebar.MenuButton icon={BellIcon}>Alerts</Sidebar.MenuButton>
+          </Sidebar.Menu>
+        </Sidebar.Group>
+      </Sidebar.Content>
+    </Sidebar>
+  </Sidebar.Provider>
+</DemoContainer>
+```
+
 ---
 
 ### SignalFlareAILogo
@@ -2732,6 +6155,127 @@ SignalFlare AI logo component.
 
 `bg-sf-base`, `ring-sf-line`, `text-sf-default`
 
+**Examples:**
+
+```tsx
+<SignalFlareAILogo className="w-72" />
+```
+
+```tsx
+<SignalFlareAILogo variant="glyph" className="w-16" />
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-8">
+  <SignalFlareAILogo className="w-32" color="brand" />
+  <SignalFlareAILogo className="w-32" color="mono" />
+  <div className="rounded-lg bg-white p-4">
+    <SignalFlareAILogo className="w-32" color="black" />
+  </div>
+  <div className="rounded-lg bg-black p-4">
+    <SignalFlareAILogo className="w-32" color="white" />
+  </div>
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-8">
+  <SignalFlareAILogo variant="glyph" className="w-10" color="brand" />
+  <SignalFlareAILogo variant="glyph" className="w-10" color="mono" />
+  <div className="rounded-lg bg-white p-4">
+    <SignalFlareAILogo variant="glyph" className="w-10" color="black" />
+  </div>
+  <div className="rounded-lg bg-black p-4">
+    <SignalFlareAILogo variant="glyph" className="w-10" color="white" />
+  </div>
+</div>
+```
+
+```tsx
+<div className="flex flex-wrap items-end gap-6">
+  <SignalFlareAILogo className="w-24" />
+  <SignalFlareAILogo className="w-36" />
+  <SignalFlareAILogo className="w-52" />
+</div>
+```
+
+```tsx
+<div className="flex items-center gap-4">
+  <DropdownMenu>
+    <DropdownMenu.Trigger>
+      <button
+        type="button"
+        className="flex items-center gap-2 rounded-lg bg-[#4188ff] px-4 py-3 text-white transition-opacity hover:opacity-80"
+      >
+        <SignalFlareAILogo variant="glyph" color="white" className="w-6" />
+        <span className="font-medium">Logo</span>
+      </button>
+    </DropdownMenu.Trigger>
+    <DropdownMenu.Content>
+      <DropdownMenu.Item
+        icon={MapPinIcon}
+        onSelect={() =>
+          copyToClipboard(
+            generateSignalFlareAILogoSvg({ variant: "glyph" }),
+            "glyph"
+          )
+        }
+      >
+        {copied === "glyph" ? "Copied!" : "Copy icon as SVG"}
+      </DropdownMenu.Item>
+      <DropdownMenu.Item
+        icon={CodeIcon}
+        onSelect={() =>
+          copyToClipboard(
+            generateSignalFlareAILogoSvg({ variant: "full" }),
+            "full"
+          )
+        }
+      >
+        {copied === "full" ? "Copied!" : "Copy full logo as SVG"}
+      </DropdownMenu.Item>
+      <DropdownMenu.Separator />
+      <DropdownMenu.Item
+        icon={ArrowSquareOutIcon}
+        onSelect={() =>
+          window.open("https://signalflare.ai", "_blank", "noopener")
+        }
+      >
+        Visit SignalFlare AI
+      </DropdownMenu.Item>
+    </DropdownMenu.Content>
+  </DropdownMenu>
+
+  <span className="text-sm text-sf-subtle">
+    Click to open the brand assets menu
+  </span>
+</div>
+```
+
+```tsx
+<PoweredBySignalFlareAI />
+```
+
+```tsx
+<div className="flex flex-wrap items-center gap-4">
+  <PoweredBySignalFlareAI color="brand" />
+  <PoweredBySignalFlareAI color="mono" />
+  <PoweredBySignalFlareAI color="black" />
+  <div className="rounded-lg bg-black p-3">
+    <PoweredBySignalFlareAI color="white" />
+  </div>
+</div>
+```
+
+```tsx
+<footer className="flex w-full items-center justify-between rounded-lg border border-sf-line bg-sf-elevated px-6 py-4">
+  <span className="text-sm text-sf-subtle">
+    &copy; 2026 Your Company. All rights reserved.
+  </span>
+  <PoweredBySignalFlareAI />
+</footer>
+```
+
 ---
 
 ### Sparkline
@@ -2751,11 +6295,26 @@ Sparkline — a tiny inline chart intended for embedding in cards, tables, or ro
 - `children`: ReactNode
   Child elements
 
+**Examples:**
+
+```tsx
+<Sparkline echarts={echarts} data={sample} isDarkMode={isDarkMode} />
+```
+
+```tsx
+<Sparkline
+  echarts={echarts}
+  data={sample}
+  variant="area"
+  isDarkMode={isDarkMode}
+/>
+```
+
 ---
 
 ### StatCard
 
-StatCard — compact KPI tile displaying a label, a primary value, and an optional delta + trend sparkline.
+StatCard — compact KPI tile displaying a label, a primary value, and an optional delta + trend sparkline. Uses pretext-driven `Text` for consistent spacing and wrapping: - Labels use `wrap="balance"` for even multiline breaks - Values use `wrap="shrink"` so sparklines tuck tight against numbers - Hints use `wrap="natural"` (numeric content rarely wraps)
 
 **Type:** component
 
@@ -2786,6 +6345,24 @@ StatCard — compact KPI tile displaying a label, a primary value, and an option
 
 `bg-sf-elevated`, `bg-sf-fill`, `text-sf-danger`, `text-sf-default`, `text-sf-strong`, `text-sf-subtle`, `text-sf-success`
 
+**Examples:**
+
+```tsx
+<StatCard
+  label="Active users"
+  value="12,384"
+  delta={{ value: 0.12, label: "vs last week" }}
+/>
+```
+
+```tsx
+<StatCard size="sm" label="MRR" value="$128,420" hint="30-day avg" />
+```
+
+```tsx
+<StatCard label="Signups" value="—" loading />
+```
+
 ---
 
 ### Surface
@@ -2811,6 +6388,44 @@ Surface component
 
 `bg-sf-base`, `ring-sf-line`
 
+**Examples:**
+
+```tsx
+<Surface className="rounded-lg p-6">
+  <Text size="lg" bold>
+    Surface Component
+  </Text>
+  <div className="mt-2">
+    <Text variant="secondary">
+      A container with consistent elevation and border styling.
+    </Text>
+  </div>
+</Surface>
+```
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Surface as="section" className="rounded-lg p-4">
+    <Text bold>As section element</Text>
+  </Surface>
+  <Surface as="article" className="rounded-lg p-4">
+    <Text bold>As article element</Text>
+  </Surface>
+  <Surface as="aside" className="rounded-lg p-4">
+    <Text bold>As aside element</Text>
+  </Surface>
+</div>
+```
+
+```tsx
+<Surface className="rounded-lg p-6">
+  <Text bold>Outer Surface</Text>
+  <Surface className="mt-4 rounded-md bg-sf-elevated p-4">
+    <Text variant="secondary">Nested Surface</Text>
+  </Surface>
+</Surface>
+```
+
 ---
 
 ### Switch
@@ -2879,6 +6494,16 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
+**Examples:**
+
+```tsx
+<Switch label="Switch" checked={checked} onCheckedChange={setChecked} />
+```
+
+```tsx
+<Switch label="Disabled" checked={false} disabled />
+```
+
 ---
 
 ### Table
@@ -2948,6 +6573,234 @@ Footer sub-component
 
 ResizeHandle sub-component
 
+**Examples:**
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <Table>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Subject</Table.Head>
+          <Table.Head>From</Table.Head>
+          <Table.Head>Date</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {emailData.slice(0, 3).map((row) => (
+          <Table.Row key={row.id}>
+            <Table.Cell>{row.subject}</Table.Cell>
+            <Table.Cell>{row.from}</Table.Cell>
+            <Table.Cell>{row.date}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <Table>
+      <Table.Header>
+        <Table.Row>
+          <Table.CheckHead
+            checked={selectedIds.size === rows.length}
+            indeterminate={
+              selectedIds.size > 0 && selectedIds.size < rows.length
+            }
+            onValueChange={toggleAll}
+            aria-label="Select all rows"
+          />
+          <Table.Head>Subject</Table.Head>
+          <Table.Head>From</Table.Head>
+          <Table.Head>Date</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {rows.map((row) => (
+          <Table.Row key={row.id}>
+            <Table.CheckCell
+              checked={selectedIds.has(row.id)}
+              onValueChange={() => toggleRow(row.id)}
+              aria-label={`Select ${row.subject}`}
+            />
+            <Table.Cell>{row.subject}</Table.Cell>
+            <Table.Cell>{row.from}</Table.Cell>
+            <Table.Cell>{row.date}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <Table>
+      <Table.Header>
+        <Table.Row>
+          <Table.CheckHead
+            checked={selectedIds.size === rows.length}
+            indeterminate={
+              selectedIds.size > 0 && selectedIds.size < rows.length
+            }
+            onValueChange={toggleAll}
+            aria-label="Select all rows"
+          />
+          <Table.Head>Subject</Table.Head>
+          <Table.Head>From</Table.Head>
+          <Table.Head>Date</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {rows.map((row) => (
+          <Table.Row
+            key={row.id}
+            variant={selectedIds.has(row.id) ? "selected" : "default"}
+          >
+            <Table.CheckCell
+              checked={selectedIds.has(row.id)}
+              onValueChange={() => toggleRow(row.id)}
+              aria-label={`Select ${row.subject}`}
+            />
+            <Table.Cell>{row.subject}</Table.Cell>
+            <Table.Cell>{row.from}</Table.Cell>
+            <Table.Cell>{row.date}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="p-0">
+    <Table layout="fixed">
+      <colgroup>
+        <col />
+        <col className="w-[150px]" />
+        <col className="w-[150px]" />
+      </colgroup>
+      <Table.Header>
+        <Table.Row>
+          <Table.Head>Subject</Table.Head>
+          <Table.Head>From</Table.Head>
+          <Table.Head>Date</Table.Head>
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {emailData.map((row) => (
+          <Table.Row key={row.id}>
+            <Table.Cell>{row.subject}</Table.Cell>
+            <Table.Cell>{row.from}</Table.Cell>
+            <Table.Cell>{row.date}</Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
+```tsx
+<LayerCard>
+  <LayerCard.Primary className="w-full overflow-x-auto p-0">
+    <Table layout="fixed">
+      <colgroup>
+        <col />{" "}
+        {/* Checkbox column - width handled by Table.CheckHead/CheckCell */}
+        <col />
+        <col style={{ width: "150px" }} />
+        <col style={{ width: "120px" }} />
+        <col style={{ width: "50px" }} />
+      </colgroup>
+      <Table.Header>
+        <Table.Row>
+          <Table.CheckHead
+            checked={selectedIds.size === emailData.length}
+            indeterminate={
+              selectedIds.size > 0 && selectedIds.size < emailData.length
+            }
+            onValueChange={toggleAll}
+            aria-label="Select all rows"
+          />
+          <Table.Head>Subject</Table.Head>
+          <Table.Head>From</Table.Head>
+          <Table.Head>Date</Table.Head>
+          <Table.Head />
+        </Table.Row>
+      </Table.Header>
+      <Table.Body>
+        {emailData.map((row) => (
+          <Table.Row
+            key={row.id}
+            variant={selectedIds.has(row.id) ? "selected" : "default"}
+          >
+            <Table.CheckCell
+              checked={selectedIds.has(row.id)}
+              onValueChange={() => toggleRow(row.id)}
+              aria-label={`Select ${row.subject}`}
+            />
+            <Table.Cell>
+              <div className="flex items-center gap-2">
+                <EnvelopeSimpleIcon size={16} />
+                <span className="truncate">{row.subject}</span>
+                {row.tags && (
+                  <div className="ml-2 inline-flex gap-1">
+                    {row.tags.map((tag) => (
+                      <Badge key={tag}>{tag}</Badge>
+                    ))}
+                  </div>
+                )}
+              </div>
+            </Table.Cell>
+            <Table.Cell>
+              <span className="truncate">{row.from}</span>
+            </Table.Cell>
+            <Table.Cell>
+              <span className="truncate">{row.date}</span>
+            </Table.Cell>
+            <Table.Cell className="text-right">
+              <DropdownMenu>
+                <DropdownMenu.Trigger
+                  render={
+                    <Button
+                      variant="ghost"
+                      size="sm"
+                      shape="square"
+                      aria-label="More options"
+                    >
+                      <DotsThreeIcon weight="bold" size={16} />
+                    </Button>
+                  }
+                />
+                <DropdownMenu.Content>
+                  <DropdownMenu.Item icon={EyeIcon}>View</DropdownMenu.Item>
+                  <DropdownMenu.Item icon={PencilSimpleIcon}>
+                    Edit
+                  </DropdownMenu.Item>
+                  <DropdownMenu.Separator />
+                  <DropdownMenu.Item icon={TrashIcon} variant="danger">
+                    Delete
+                  </DropdownMenu.Item>
+                </DropdownMenu.Content>
+              </DropdownMenu>
+            </Table.Cell>
+          </Table.Row>
+        ))}
+      </Table.Body>
+    </Table>
+  </LayerCard.Primary>
+</LayerCard>
+```
+
 ---
 
 ### Tabs
@@ -2990,6 +6843,114 @@ Tab navigation component with segmented, underline, or pill style. Built on Base
 
 **Styling:**
 
+**Examples:**
+
+```tsx
+<div className="flex flex-col gap-6">
+  <div>
+    <p className="mb-2 text-sm text-sf-subtle">Segmented (default)</p>
+    <Tabs
+      variant="segmented"
+      tabs={[
+        { label: "Tab 1", value: "tab1" },
+        { label: "Tab 2", value: "tab2" },
+        { label: "Tab 3", value: "tab3" },
+      ]}
+      selectedValue="tab1"
+    />
+  </div>
+  <div>
+    <p className="mb-2 text-sm text-sf-subtle">Underline</p>
+    <Tabs
+      variant="underline"
+      tabs={[
+        { label: "Tab 1", value: "tab1" },
+        { label: "Tab 2", value: "tab2" },
+        { label: "Tab 3", value: "tab3" },
+      ]}
+      selectedValue="tab1"
+    />
+  </div>
+  <div>
+    <p className="mb-2 text-sm text-sf-subtle">Pill</p>
+    <Tabs
+      variant="pill"
+      tabs={[
+        { label: "Tab 1", value: "tab1" },
+        { label: "Tab 2", value: "tab2" },
+        { label: "Tab 3", value: "tab3" },
+      ]}
+      selectedValue="tab1"
+    />
+  </div>
+</div>
+```
+
+```tsx
+<Tabs
+  variant="segmented"
+  tabs={[
+    { label: "Tab 1", value: "tab1" },
+    { label: "Tab 2", value: "tab2" },
+    { label: "Tab 3", value: "tab3" },
+  ]}
+  selectedValue="tab1"
+/>
+```
+
+```tsx
+<div className="space-y-4">
+  <Tabs
+    tabs={[
+      { label: "Tab 1", value: "tab1" },
+      { label: "Tab 2", value: "tab2" },
+      { label: "Tab 3", value: "tab3" },
+    ]}
+    value={activeTab}
+    onValueChange={setActiveTab}
+  />
+  <p className="text-sm text-sf-subtle">
+    Active tab: <code className="text-sm">{activeTab}</code>
+  </p>
+</div>
+```
+
+```tsx
+<Tabs
+  tabs={[
+    { label: "Overview", value: "overview" },
+    { label: "Analytics", value: "analytics" },
+    { label: "Reports", value: "reports" },
+    { label: "Notifications", value: "notifications" },
+    { label: "Settings", value: "settings" },
+    { label: "Billing", value: "billing" },
+  ]}
+  selectedValue="overview"
+/>
+```
+
+```tsx
+<Tabs
+  tabs={[
+    {
+      label: "Regular Tab",
+      value: "tab1",
+    },
+    {
+      label: "Link Tab",
+      render: (props) => <a {...props} href="#tab2" />,
+      value: "tab2",
+    },
+    {
+      label: "Another Link",
+      render: (props) => <a {...props} href="#tab3" />,
+      value: "tab3",
+    },
+  ]}
+  selectedValue="tab1"
+/>
+```
+
 ---
 
 ### Text
@@ -3025,6 +6986,14 @@ Text component
   The HTML element type to render as (e.g. `"span"`, `"p"`, `"h1"`). Auto-selected based on variant if omitted.
 - `children`: ReactNode
   Text content.
+- `wrap`: MeasuredTextMode | boolean
+  Text layout strategy using pretext-driven measurement.
+- `"natural"` — No measurement, normal browser wrapping (default for body).
+- `"balance"` — Even wrapping, smallest maxWidth without adding lines (default for headings).
+- `"shrink"` — Hug widest natural line (maxWidth = line width). Good for chat bubbles.
+- `"reserve"` — Reserve height based on line count. Good for streaming text.
+- `reserveLines`: number
+  For `wrap="reserve"`: reserve this many lines of height. If omitted, measures current content to determine line count.
 
 **Colors (sf tokens used):**
 
@@ -3032,6 +7001,71 @@ Text component
 
 **Styling:**
 
+**Examples:**
+
+```tsx
+<div className="grid w-full grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="heading1">Heading 1</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-3xl (30px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="heading2">Heading 2</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-2xl (24px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="heading3">Heading 3</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-lg (16px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text>Body</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-base (14px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text bold>Body bold</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-base (14px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text size="lg">Body lg</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-lg (16px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text size="sm">Body sm</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-sm (13px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text size="xs">Body xs</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-xs (12px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="secondary">Body secondary</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-base (14px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="mono">Monospace</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-sm (13px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="mono" size="lg">
+      Monospace lg
+    </Text>
+    <p className="font-mono text-xs text-sf-subtle">text-base (14px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="mono-secondary">Monospace secondary</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-sm (13px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="success">Success</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-base (14px)</p>
+  </div>
+  <div className="flex flex-col justify-end gap-1 rounded-lg border border-sf-line bg-sf-base p-4">
+    <Text variant="error">Error</Text>
+    <p className="font-mono text-xs text-sf-subtle">text-base (14px)</p>
+  </div>
+</div>
+```
+
 ---
 
 ### TextRoll
@@ -3149,6 +7183,33 @@ Accessible popup that shows additional information on hover/focus. Wrap your app
 
 `bg-sf-elevated`, `fill-sf-elevated`, `fill-sf-tip-shadow`, `fill-sf-tip-stroke`, `outline-sf-fill`, `text-sf-default`
 
+**Examples:**
+
+```tsx
+<TooltipProvider>
+  <Tooltip content="Add new item">
+    <Button shape="square" icon={PlusIcon} aria-label="Add new item" />
+  </Tooltip>
+</TooltipProvider>
+```
+
+```tsx
+<TooltipProvider>
+  <div className="flex gap-2">
+    <Tooltip content="Add">
+      <Button shape="square" icon={PlusIcon} aria-label="Add" />
+    </Tooltip>
+    <Tooltip content="Change language">
+      <Button
+        shape="square"
+        icon={TranslateIcon}
+        aria-label="Change language"
+      />
+    </Tooltip>
+  </div>
+</TooltipProvider>
+```
+
 ---
 
 ### InputArea