@signalflare-ai/ui 1.0.0 → 1.2.0

package/ai/component-registry.md

@@ -26,11 +26,31 @@ 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
 
-`AiAgentCard` — compact card showing one agent's status in a commander dashboard. Displays: agent icon, name, status indicator, current task, model, duration, and tool call count. Clickable for selection.
+`AiAgentCard` — compact card showing one agent's status in a commander dashboard.  Displays: agent icon, name, status indicator, current task, model, duration, and tool call count. Clickable for selection.
 
 **Type:** component
 
@@ -75,11 +95,111 @@ 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
 
-Approval card for tool calls and plan submissions. Maps to harness events: `tool_approval_required`, `plan_approval_required`, `plan_approved`.
+Approval card for tool calls and plan submissions.  Maps to harness events: `tool_approval_required`, `plan_approval_required`, `plan_approved`.
 
 **Type:** component
 
@@ -119,6 +239,43 @@ 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
@@ -149,6 +306,21 @@ 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`
 
+**Examples:**
+
+```tsx
+<AiCodeBlock code={CODE} language="tsx">
+      <AiCodeBlockCopyButton />
+    </AiCodeBlock>
+```
+
+```tsx
+<AiCodeBlock code="npm install @signalflare-ai/ui">
+      <AiCodeBlockCopyButton />
+    </AiCodeBlock>
+```
+
+
 ---
 
 ### AiConversation
@@ -169,11 +341,30 @@ 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
 
-Inline conversation banner for system notices. Renders as a compact, horizontally centered divider-like notice rather than a chat bubble. Maps to harness events: `error`, `info`, `mode_changed`, `model_changed`.
+Inline conversation banner for system notices. Renders as a compact, horizontally centered divider-like notice rather than a chat bubble.  Maps to harness events: `error`, `info`, `mode_changed`, `model_changed`.
 
 **Type:** component
 
@@ -199,6 +390,21 @@ 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,11 +433,43 @@ 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
 
-`AiMissionHeader` — top bar for the Commander dashboard. Shows: mission title, progress bar (from task list), agent count, live elapsed time, token usage, and an abort button while running.
+`AiMissionHeader` — top bar for the Commander dashboard.  Shows: mission title, progress bar (from task list), agent count, live elapsed time, token usage, and an abort button while running.
 
 **Type:** component
 
@@ -269,11 +507,122 @@ 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
 
-Groups streaming ephemeral activity (tool calls + reasoning) into a single rolling window during streaming, then collapses to a frozen summary line once the parent message completes. Behavior: - **Streaming:** shows the most recent `max` (default 3) ephemeral children. Pinned rows (errors / user-expanded) sit above the live window. - **Completed:** writes a snapshot keyed by `groupKey`, unmounts ephemeral children entirely, and renders a static `▸ {title} · N steps` line. - **Re-mount after completion:** always renders the cached snapshot — no animations, no `useEffect` re-runs, no tool re-execution risk.
+Groups streaming ephemeral activity (tool calls + reasoning) into a single rolling window during streaming, then collapses to a frozen summary line once the parent message completes.  Behavior: - **Streaming:** shows the most recent `max` (default 3) ephemeral children. Pinned rows (errors / user-expanded) sit above the live window. - **Completed:** writes a snapshot keyed by `groupKey`, unmounts ephemeral children entirely, and renders a static `▸ {title} · N steps` line. - **Re-mount after completion:** always renders the cached snapshot — no animations, no `useEffect` re-runs, no tool re-execution risk.
 
 **Type:** component
 
@@ -298,11 +647,59 @@ 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
 
-Agent question card. Renders when the agent uses the `ask_user` built-in tool and needs a response before continuing. Maps to harness event: `ask_question`.
+Agent question card. Renders when the agent uses the `ask_user` built-in tool and needs a response before continuing.  Maps to harness event: `ask_question`.
 
 **Type:** component
 
@@ -338,6 +735,56 @@ 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,11 +834,83 @@ 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
 
-Renders AI-generated markdown using Streamdown. Supports streaming animation, syntax-highlighted code, tables, and more. Pass `isAnimating={true}` while streaming and `false` once complete to get character-by-character reveal animation.
+Renders AI-generated markdown using Streamdown. Supports streaming animation, syntax-highlighted code, tables, and more.  Pass `isAnimating={true}` while streaming and `false` once complete to get character-by-character reveal animation.
 
 **Type:** component
 
@@ -410,6 +929,17 @@ 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>
+```
+
+
 ---
 
 ### AiShimmer
@@ -435,6 +965,27 @@ 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 +1021,50 @@ 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,11 +1084,23 @@ 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
 
-Collapsible wrapper for nested subagent activity. Shows the subagent name, status, model, and duration in a header, with all subagent output (text, tool calls, etc.) in a collapsible body. Maps to harness events: `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`.
+Collapsible wrapper for nested subagent activity. Shows the subagent name, status, model, and duration in a header, with all subagent output (text, tool calls, etc.) in a collapsible body.  Maps to harness events: `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`.
 
 **Type:** component
 
@@ -529,7 +1136,93 @@ 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>
+```
+
 
 ---
 
@@ -555,7 +1248,7 @@ Horizontally scrollable container for suggestion pills. Position it relative to
 
 ### AiTaskList
 
-Task progress list. Renders structured tasks from the harness `task_write` tool. Typically rendered inside the `PromptInputBackLayer` or inline in conversation. Maps to harness event: `task_updated`.
+Task progress list. Renders structured tasks from the harness `task_write` tool. Typically rendered inside the `PromptInputBackLayer` or inline in conversation.  Maps to harness event: `task_updated`.
 
 **Type:** component
 
@@ -582,11 +1275,20 @@ 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
 
-`AiTimeline` — horizontal swim-lane timeline for commander-level orchestration. Displays multiple `AiTimelineLane` children on a shared time axis. Supports live updating (a "now" marker follows the live edge), panning, and zoom via `pixelsPerSecond`.
+`AiTimeline` — horizontal swim-lane timeline for commander-level orchestration.  Displays multiple `AiTimelineLane` children on a shared time axis. Supports live updating (a "now" marker follows the live edge), panning, and zoom via `pixelsPerSecond`.
 
 **Type:** component
 
@@ -618,6 +1320,106 @@ 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
@@ -665,7 +1467,7 @@ Renders a single tool call. Supports three display variants: - `"default"` — e
 
 ### AiUsageBar
 
-Compact token usage display bar. Shows input/output token counts, total, optional cost, and model identifier. Maps to harness event: `usage_update`.
+Compact token usage display bar. Shows input/output token counts, total, optional cost, and model identifier.  Maps to harness event: `usage_update`.
 
 **Type:** component
 
@@ -697,6 +1499,26 @@ 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 +1563,117 @@ 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 +1704,39 @@ 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
@@ -805,7 +1771,6 @@ This is a compound component. Use these sub-components:
 Link sub-component
 
 Props:
-
 - `href`: string (required)
 - `icon`: React.ReactNode
 
@@ -814,7 +1779,6 @@ Props:
 Current sub-component
 
 Props:
-
 - `loading`: boolean
 - `icon`: React.ReactNode
 
@@ -827,9 +1791,51 @@ Separator sub-component
 Clipboard sub-component
 
 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
@@ -878,7 +1884,6 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
     - `not-disabled`: `not-disabled:hover:border-secondary! not-disabled:hover:bg-sf-control`
     - `disabled`: `disabled:bg-sf-control/50 disabled:!text-sf-danger/70`
     - `data-state`: `data-[state=open]:bg-sf-control`
-
 - `children`: ReactNode
 - `className`: string
 - `icon`: ReactNode
@@ -897,6 +1902,65 @@ 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
@@ -919,7 +1983,6 @@ Checkbox component
   - `"default"`:
     - `focus`: `[&:focus-within>span]:ring-sf-ring`
     - `hover`: `[&:hover>span]:ring-sf-ring`
-
 - `label`: ReactNode
   Label content for the checkbox (enables built-in Field wrapper) - can be a string or any React node
 - `labelTooltip`: ReactNode
@@ -974,7 +2037,6 @@ Item sub-component
 Group sub-component
 
 Props:
-
 - `legend`: string (required)
 - `children`: ReactNode (required)
 - `error`: string
@@ -985,11 +2047,73 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
----
-
-### ClipboardText
 
-Read-only text field with a one-click copy-to-clipboard button.
+**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
+
+Read-only text field with a one-click copy-to-clipboard button.
 
 **Type:** component
 
@@ -1062,6 +2186,20 @@ 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
@@ -1095,6 +2233,7 @@ Code component
 
 **Styling:**
 
+
 **Sub-Components:**
 
 This is a compound component. Use these sub-components:
@@ -1104,15 +2243,36 @@ This is a compound component. Use these sub-components:
 Block sub-component
 
 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
 
-Collapsible component for showing/hiding content. Features: - Animated chevron indicator (rotates 180° when open) - Accessible with aria-expanded and aria-controls - Content panel with left border accent
+Collapsible component for showing/hiding content.  Features: - Animated chevron indicator (rotates 180° when open) - Accessible with aria-expanded and aria-controls - Content panel with left border accent
 
 **Type:** component
 
@@ -1136,11 +2296,44 @@ 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
 
-Combobox — autocomplete input with filterable dropdown list. Compound component: `Combobox` (Root), `.TriggerInput`, `.TriggerValue`, `.TriggerMultipleWithInput`, `.Content`, `.Item`, `.Chip`, `.Input`, `.Empty`, `.GroupLabel`, `.Group`, `.List`, `.Collection`.
+Combobox — autocomplete input with filterable dropdown list.  Compound component: `Combobox` (Root), `.TriggerInput`, `.TriggerValue`, `.TriggerMultipleWithInput`, `.Content`, `.Item`, `.Chip`, `.Input`, `.Empty`, `.GroupLabel`, `.Group`, `.List`, `.Collection`.
 
 **Type:** component
 
@@ -1191,7 +2384,6 @@ This is a compound component. Use these sub-components:
 Content sub-component
 
 Props:
-
 - `className`: string
 - `align`: ComboboxBase.Positioner.Props["align"]
 - `alignOffset`: ComboboxBase.Positioner.Props["alignOffset"]
@@ -1243,11 +2435,9 @@ List sub-component
 Renders filtered list items. Use when you need more control over item rendering.
 
 Props:
-
 - `children`: (item: T, index: number) => ReactNode (required) - Function that receives each filtered item and returns a node
 
 Usage:
-
 ```tsx
 <Combobox.Collection>
   {(item, index) => (
@@ -1258,11 +2448,171 @@ 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
 
-CommandPalette — accessible command palette / spotlight search overlay. Compound component: `CommandPalette.Root` (or `.Dialog` + `.Panel`), `.Input`, `.List`, `.Results`, `.Items`, `.Group`, `.GroupLabel`, `.Item`, `.ResultItem`, `.HighlightedText`, `.Empty`, `.Loading`, `.Footer`. Built on `@base-ui/react/autocomplete` + `@base-ui/react/dialog`.
+CommandPalette — accessible command palette / spotlight search overlay.  Compound component: `CommandPalette.Root` (or `.Dialog` + `.Panel`), `.Input`, `.List`, `.Results`, `.Items`, `.Group`, `.GroupLabel`, `.Item`, `.ResultItem`, `.HighlightedText`, `.Empty`, `.Loading`, `.Footer`.  Built on `@base-ui/react/autocomplete` + `@base-ui/react/dialog`.
 
 **Type:** component
 
@@ -1281,6 +2631,221 @@ 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,11 +2896,149 @@ 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
 
-DatePicker — a date selection calendar. Built on [react-day-picker](https://daypicker.dev) with SignalFlare styling. Supports three selection modes: single, multiple, and range.
+DatePicker — a date selection calendar.  Built on [react-day-picker](https://daypicker.dev) with SignalFlare styling. Supports three selection modes: single, multiple, and range.
 
 **Type:** component
 
@@ -1354,11 +3057,167 @@ 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
 
-DateRangePicker — dual-calendar date range selector. Renders two side-by-side month calendars with click-to-select start/end dates, hover preview of the range, a timezone footer, and a reset button.
+DateRangePicker — dual-calendar date range selector.  Renders two side-by-side month calendars with click-to-select start/end dates, hover preview of the range, a timezone footer, and a reset button.
 
 **Type:** component
 
@@ -1478,11 +3337,235 @@ 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
 
-DropdownMenu — accessible dropdown menu anchored to a trigger. Compound component: `DropdownMenu` (Root), `.Trigger`, `.Content`, `.Item`, `.CheckboxItem`, `.RadioGroup`, `.RadioItem`, `.RadioItemIndicator`, `.Sub`, `.SubTrigger`, `.SubContent`, `.Label`, `.Separator`, `.Shortcut`, `.Group`. Built on `@base-ui/react/menu`.
+DropdownMenu — accessible dropdown menu anchored to a trigger.  Compound component: `DropdownMenu` (Root), `.Trigger`, `.Content`, `.Item`, `.CheckboxItem`, `.RadioGroup`, `.RadioItem`, `.RadioItemIndicator`, `.Sub`, `.SubTrigger`, `.SubContent`, `.Label`, `.Separator`, `.Shortcut`, `.Group`.  Built on `@base-ui/react/menu`.
 
 **Type:** component
 
@@ -1564,6 +3647,7 @@ Shortcut sub-component
 
 Group sub-component (wraps DropdownMenuPrimitive)
 
+
 ---
 
 ### Empty
@@ -1599,6 +3683,92 @@ 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
@@ -1636,7 +3806,7 @@ Form field wrapper that provides a label, optional description, and error displa
 
 ### Filters
 
-Filters component for building and managing active filter conditions. Supports multiple filter types (text, select, multiselect, custom), operators, and an "Add Filter" popover interface. Designed to work standalone or with DataGrid for advanced data filtering.
+Filters component for building and managing active filter conditions.  Supports multiple filter types (text, select, multiselect, custom), operators, and an "Add Filter" popover interface. Designed to work standalone or with DataGrid for advanced data filtering.
 
 **Type:** component
 
@@ -1677,6 +3847,62 @@ 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 +3946,230 @@ 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,11 +4215,97 @@ 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
 
-Label component for form fields. Provides a standardized way to display labels with optional indicators: - Optional indicator: gray "(optional)" text when `showOptional={true}` - Tooltip: info icon with hover tooltip for additional context
+Label component for form fields.  Provides a standardized way to display labels with optional indicators: - Optional indicator: gray "(optional)" text when `showOptional={true}` - Tooltip: info icon with hover tooltip for additional context
 
 **Type:** component
 
@@ -1796,6 +4332,59 @@ 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
@@ -1820,6 +4409,7 @@ LayerCard component
 
 **Styling:**
 
+
 **Sub-Components:**
 
 This is a compound component. Use these sub-components:
@@ -1832,6 +4422,56 @@ Primary sub-component
 
 Secondary sub-component
 
+
+**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
@@ -1854,7 +4494,6 @@ Link component
   **State Classes:**
   - `"plain"`:
     - `hover`: `hover:text-primary/70`
-
 - `to`: string
 - `children`: ReactNode
 - `className`: string
@@ -1882,6 +4521,71 @@ 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,11 +4607,26 @@ 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
 
-MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation. Each option renders as a `<button>` with a Tooltip. The active option is visually highlighted with an elevated background.
+MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation.  Each option renders as a `<button>` with a Tooltip. The active option is visually highlighted with an elevated background.
 
 **Type:** component
 
@@ -1932,6 +4651,31 @@ 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 +4711,29 @@ 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
@@ -1999,7 +4766,35 @@ Page navigation controls with page count display.
 
 `text-sf-strong`
 
-**Styling:**
+**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}
+    />
+```
+
 
 ---
 
@@ -2049,6 +4844,154 @@ Description sub-component
 
 Close sub-component
 
+
+**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 +5014,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,13 +5030,70 @@ 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-overlay`, `bg-sf-tint`, `ring-sf-line`, `ring-sf-ring`, `text-sf-brand`, `text-sf-default`, `text-sf-inactive`, `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:**
+
+This is a compound component. Use these sub-components:
+
+#### PromptInput.BackLayer
+
+BackLayer sub-component
+
+#### PromptInput.Textarea
+
+Textarea sub-component
+
+#### PromptInput.Editor
+
+Editor sub-component
+
+#### PromptInput.Toolbar
+
+Toolbar sub-component
+
+#### PromptInput.Tools
+
+Tools sub-component
+
+#### PromptInput.Submit
+
+Submit sub-component
+
+#### PromptInput.ModeSelector
+
+ModeSelector sub-component
+
+#### PromptInput.AddTagButton
+
+AddTagButton sub-component
+
+#### PromptInput.Tags
+
+Tags sub-component
+
+#### PromptInput.Tag
+
+Tag sub-component
+
+#### PromptInput.AttachButton
+
+AttachButton sub-component
+
+#### PromptInput.Attachments
+
+Attachments sub-component
+
+#### PromptInput.Attachment
+
+Attachment sub-component
+
 
 ---
 
 ### Radio
 
-Radio — radio button group for single-select choices. Compound component: `Radio.Group` (with built-in Fieldset) and `Radio.Item`. Built on `@base-ui/react/radio-group` + `@base-ui/react/radio`.
+Radio — radio button group for single-select choices.  Compound component: `Radio.Group` (with built-in Fieldset) and `Radio.Item`. Built on `@base-ui/react/radio-group` + `@base-ui/react/radio`.
 
 **Type:** component
 
@@ -2126,6 +5128,78 @@ 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
@@ -2175,6 +5249,7 @@ Select component
 
 **Styling:**
 
+
 **Sub-Components:**
 
 This is a compound component. Use these sub-components:
@@ -2183,6 +5258,107 @@ 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
@@ -2238,11 +5414,82 @@ 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
 
-Sidebar — responsive navigation panel with expand/collapse support. Compound component: `Sidebar` (root `<aside>`), `.Provider`, `.Header`, `.Content`, `.Footer`, `.Group`, `.GroupLabel`, `.GroupContent`, `.Menu`, `.MenuItem`, `.MenuButton`, `.MenuAction`, `.MenuBadge`, `.MenuSub`, `.MenuSubItem`, `.MenuSubButton`, `.Separator`, `.Input`, `.Trigger`, `.Rail`, `.MenuChevron`, `.Collapsible`, `.CollapsibleTrigger`, `.CollapsibleContent`. Built on `@base-ui/react/collapsible` + `@base-ui/react/dialog`.
+Sidebar — responsive navigation panel with expand/collapse support.  Compound component: `Sidebar` (root `<aside>`), `.Provider`, `.Header`, `.Content`, `.Footer`, `.Group`, `.GroupLabel`, `.GroupContent`, `.Menu`, `.MenuItem`, `.MenuButton`, `.MenuAction`, `.MenuBadge`, `.MenuSub`, `.MenuSubItem`, `.MenuSubButton`, `.Separator`, `.Input`, `.Trigger`, `.Rail`, `.MenuChevron`, `.Collapsible`, `.CollapsibleTrigger`, `.CollapsibleContent`.  Built on `@base-ui/react/collapsible` + `@base-ui/react/dialog`.
 
 **Type:** component
 
@@ -2286,6 +5533,7 @@ Sidebar — responsive navigation panel with expand/collapse support. Compound c
 
 **Styling:**
 
+
 **Sub-Components:**
 
 This is a compound component. Use these sub-components:
@@ -2295,7 +5543,6 @@ This is a compound component. Use these sub-components:
 Provider sub-component
 
 Props:
-
 - `defaultOpen`: boolean
 - `open`: boolean
 - `variant`: SidebarVariant
@@ -2400,6 +5647,299 @@ 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
@@ -2675,6 +6215,128 @@ 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
@@ -2694,11 +6356,27 @@ 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
 
@@ -2729,6 +6407,25 @@ 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
@@ -2754,6 +6451,45 @@ 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
@@ -2813,7 +6549,6 @@ Item sub-component
 Group sub-component
 
 Props:
-
 - `legend`: string (required)
 - `children`: ReactNode (required)
 - `error`: string
@@ -2822,11 +6557,23 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
+
+**Examples:**
+
+```tsx
+<Switch label="Switch" checked={checked} onCheckedChange={setChecked} />
+```
+
+```tsx
+<Switch label="Disabled" checked={false} disabled />
+```
+
+
 ---
 
 ### Table
 
-Table — semantic HTML table with styled rows, cells, and selection support. Compound component: `Table` (Root), `.Header`, `.Head`, `.Body`, `.Row`, `.Cell`, `.Footer`, `.CheckCell`, `.CheckHead`, `.ResizeHandle`.
+Table — semantic HTML table with styled rows, cells, and selection support.  Compound component: `Table` (Root), `.Header`, `.Head`, `.Body`, `.Row`, `.Cell`, `.Footer`, `.CheckCell`, `.CheckHead`, `.ResizeHandle`.
 
 **Type:** component
 
@@ -2891,6 +6638,236 @@ 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
@@ -2933,6 +6910,116 @@ 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
@@ -2968,6 +7055,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):**
 
@@ -2975,11 +7070,78 @@ 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
 
-Letter-by-letter roll animation. Each character flips on the X axis: the current letter rolls up and out, the new letter rolls in from below. Good for title changes (e.g. a streaming activity group swapping its current-step label) where the text content is short and the change should register visually. Wraps the string in an `aria-hidden` visual stack with a screen-reader-only copy of the full text so a11y tools always read the real content.
+Letter-by-letter roll animation. Each character flips on the X axis: the current letter rolls up and out, the new letter rolls in from below. Good for title changes (e.g. a streaming activity group swapping its current-step label) where the text content is short and the change should register visually.  Wraps the string in an `aria-hidden` visual stack with a screen-reader-only copy of the full text so a11y tools always read the real content.
 
 **Type:** component
 
@@ -3008,7 +7170,7 @@ Letter-by-letter roll animation. Each character flips on the X axis: the current
 
 ### ThemeToggle
 
-Theme toggle button. Cycles through light → dark → system (follows OS) modes. Reads from and writes to `localStorage` under the key `"theme"`. When set to `"system"` the key is removed so the OS preference takes over automatically. Applies the resolved mode to `document.documentElement.dataset.mode`.
+Theme toggle button. Cycles through light → dark → system (follows OS) modes.  Reads from and writes to `localStorage` under the key `"theme"`. When set to `"system"` the key is removed so the OS preference takes over automatically. Applies the resolved mode to `document.documentElement.dataset.mode`.
 
 **Type:** component
 
@@ -3037,7 +7199,7 @@ Theme toggle button. Cycles through light → dark → system (follows OS) modes
 
 ### Toasty
 
-Toasty — toast notification provider and viewport. Renders a `Toast.Provider` with a fixed-position viewport in the bottom-right corner. Toasts stack with smooth enter/exit animations, swipe-to-dismiss, and expand-on-hover. Built on `@base-ui/react/toast`.
+Toasty — toast notification provider and viewport.  Renders a `Toast.Provider` with a fixed-position viewport in the bottom-right corner. Toasts stack with smooth enter/exit animations, swipe-to-dismiss, and expand-on-hover.  Built on `@base-ui/react/toast`.
 
 **Type:** component
 
@@ -3062,6 +7224,7 @@ Toasty — toast notification provider and viewport. Renders a `Toast.Provider`
 
 **Styling:**
 
+
 ---
 
 ### Tooltip
@@ -3092,6 +7255,34 @@ 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
@@ -3106,6 +7297,7 @@ Multi-line textarea input with Input variants and InputArea-specific dimensions
 
 **Props:**
 
+
 **Styling:**
 
 - **Size Variants:**
@@ -3117,7 +7309,6 @@ Multi-line textarea input with Input variants and InputArea-specific dimensions
 ## Quick Reference
 
 **Components by Category:**
-
 - **Other:** AiActions, AiAgentCard, AiApproval, AiCodeBlock, AiConversation, AiInfoBanner, AiMessage, AiMissionHeader, AiPartGroup, AiQuestion, AiReasoning, AiResponse, AiShimmer, AiStatusBadge, AiStreamingText, AiSubagent, AiSuggestions, AiTaskList, AiTimeline, AiToolCall, AiUsageBar, DataGrid, DatePicker, Filters, Label, Link, PromptInput, SensitiveInput, Sidebar, SignalFlareAILogo, Sparkline, StatCard, Table, TextRoll, ThemeToggle, AgentHarness, Commander, DashboardGrid, DeleteResource, Map, MetricsOverview
 - **Display:** Badge, Breadcrumbs, Code, Collapsible, Empty, LayerCard, Meter, Text
 - **Feedback:** Banner, Loader, Toasty