@signalflare-ai/ui 0.5.0

package/ai/component-registry.md

@@ -0,0 +1,3046 @@
+# SF Component Registry
+
+> Auto-generated component metadata for AI/agent consumption.
+
+---
+
+### AiActions
+
+Container for a row of AI message action buttons.
+
+**Type:** component
+
+**Import:** `import { AiActions } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`text-sf-default`, `text-sf-subtle`
+
+---
+
+### 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.
+
+**Type:** component
+
+**Import:** `import { AiAgentCard } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `name`: string (required)
+- `agentType`: string
+  Agent type ID — used for icon mapping.
+- `status`: enum [default: idle]
+  - `"idle"`: Agent is idle, not yet started
+  - `"running"`: Agent is actively working
+  - `"completed"`: Agent finished successfully
+  - `"error"`: Agent encountered an error
+- `modelId`: string
+  Model ID being used (e.g. "claude-haiku-3.5").
+- `currentTask`: string
+  What the agent is currently doing.
+- `duration`: number
+  Total elapsed duration in ms.
+- `toolCallCount`: number
+  Number of tool calls made.
+- `selected`: boolean
+  Whether this card is currently selected/active.
+- `icon`: React.ElementType
+  Custom icon override.
+- `size`: enum [default: md]
+  - `"sm"`: Compact card for dense grids
+  - `"md"`: Default card size
+- `disabled`: boolean
+- `type`: enum
+- `value`: string | string[] | number
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### AiApproval
+
+Approval card for tool calls and plan submissions.  Maps to harness events: `tool_approval_required`, `plan_approval_required`, `plan_approved`.
+
+**Type:** component
+
+**Import:** `import { AiApproval } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `kind`: enum [default: tool]
+  - `"tool"`: Tool call approval
+  - `"plan"`: Plan approval
+- `status`: enum [default: pending]
+  - `"pending"`: Awaiting user decision
+  - `"approved"`: Approved by user
+  - `"rejected"`: Rejected by user
+- `title`: string (required)
+  Title text shown in the header.
+- `description`: string
+  Optional description below the title.
+- `icon`: React.ElementType
+  Custom icon. Defaults to shield (tool) or list (plan).
+- `items`: AiApprovalItem[]
+  For plan approvals: list of steps/items in the plan. For tool approvals: can show tool name, parameters, etc.
+- `approveLabel`: string
+  Label for the approve button. Default: `"Approve"`.
+- `rejectLabel`: string
+  Label for the reject button. Default: `"Reject"`.
+- `showFeedback`: boolean
+  Show a text input for rejection feedback. Default: `false`.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### AiCodeBlock
+
+Displays a code block with monospace formatting and an optional copy button. Does not include a syntax highlighter — avoids the heavy `react-syntax-highlighter` dependency. Wrap with `AiCodeBlockCopyButton` for clipboard support.
+
+**Type:** component
+
+**Import:** `import { AiCodeBlock } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `code`: string (required)
+  The raw code string to display and make copyable.
+- `language`: string
+  Language identifier for syntax highlighting (display only, no highlighting applied).
+- `showLineNumbers`: boolean
+  Show line numbers.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`bg-sf-recessed`, `border-sf-line`, `text-sf-default`, `text-sf-inactive`, `text-sf-subtle`
+
+---
+
+### AiConversation
+
+Outer scroll container for a conversation. Sticks to the bottom as new messages are added. Pair with `AiConversationContent` and optionally `AiConversationScrollButton`.
+
+**Type:** component
+
+**Import:** `import { AiConversation } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { AiInfoBanner } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `level`: enum [default: info]
+  - `"info"`: Informational notice
+  - `"error"`: Error notice
+  - `"change"`: State change notice (model/mode switch)
+- `icon`: React.ElementType
+  Custom icon override.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`border-sf-danger`, `border-sf-info`, `border-sf-line`, `text-sf-danger`, `text-sf-info`, `text-sf-subtle`
+
+---
+
+### AiLoader
+
+Spinning radial loader for AI streaming states.
+
+**Type:** component
+
+**Import:** `import { AiLoader } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+- `size`: enum [default: base]
+  - `"sm"`: Small — 12px
+  - `"base"`: Default — 16px
+  - `"lg"`: Large — 20px
+
+**Colors (sf tokens used):**
+
+`text-sf-subtle`
+
+---
+
+### AiMessage
+
+Root message container. Sets layout, group class, and role context.
+
+**Type:** component
+
+**Import:** `import { AiMessage } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `from`: enum (required) [default: assistant]
+  - `"user"`: User message — right-aligned with max width
+  - `"assistant"`: Assistant message — full width left-aligned
+  - `"system"`: System message — full width
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`bg-sf-control`, `bg-sf-overlay`, `bg-sf-tint`, `text-sf-default`, `text-sf-subtle`
+
+---
+
+### 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.
+
+**Type:** component
+
+**Import:** `import { AiMissionHeader } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `title`: string
+  The mission goal or title.
+- `taskList`: AgentTaskList
+  Task list for progress calculation.
+- `usage`: AgentUsage
+  Token/cost usage summary.
+- `activeAgentCount`: number
+  Number of agents currently active.
+- `totalAgentCount`: number
+  Total number of agents that have run or are running.
+- `startedAt`: number
+  Wall-clock ms when the mission started.
+- `endedAt`: number
+  Wall-clock ms when the mission ended. Undefined while still running.
+- `isRunning`: boolean
+  Whether the mission is currently running.
+- `variant`: enum [default: default]
+  - `"default"`: Full header with all stats
+  - `"compact"`: Single-row compact header
+- `className`: string
+- `id`: string
+- `lang`: string
+- `children`: ReactNode
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { AiQuestion } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `questionId`: string (required)
+  Unique identifier for this question (maps to harness `questionId`).
+- `question`: string (required)
+  The question text.
+- `header`: string
+  Optional header/context label.
+- `status`: enum [default: pending]
+  - `"pending"`: Waiting for answer
+  - `"answered"`: User has answered
+- `options`: AiQuestionOption[]
+  Available choice options.
+- `allowCustom`: boolean
+  Allow freeform text input (custom answer). Default: `true`. When options are provided, this adds a text field below them.
+- `icon`: React.ElementType
+  Custom icon for the question header.
+- `answeredWith`: string
+  The answer that was submitted (shown when `status="answered"`).
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### AiReasoning
+
+Collapsible reasoning block. Supports three display variants: - `"default"` — expandable card with auto-open on stream start - `"inline"` — compact single-line with left accent border - `"minimal"` — pill-shaped status badge
+
+**Type:** component
+
+**Import:** `import { AiReasoning } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `variant`: enum [default: default]
+  - `"default"`: Expandable card with collapsible reasoning text and duration
+  - `"inline"`: Compact single-line display with left accent border
+  - `"minimal"`: Pill-shaped status badge
+- `isStreaming`: boolean
+  Whether reasoning is currently streaming.
+- `duration`: number
+  Duration in seconds (passed in or self-tracked when streaming).
+- `defaultExpanded`: boolean
+  Default expanded state.
+- `open`: boolean
+  Controlled open state.
+- `autoCloseDelay`: number
+  Delay in ms before auto-closing after streaming ends. Set to 0 to disable.
+- `icon`: React.ElementType
+  Custom icon override. Defaults to `SparkleIcon` (streaming) or `BrainIcon` (done). Use to distinguish observation/reflection blocks from standard reasoning.
+- `label`: string
+  Custom label override. Defaults to `"Thinking..."` (streaming) or `"Reasoning"` (done). Use to label observational memory blocks: `"Observing..."`, `"Reflecting..."`, etc.
+- `streamingLabel`: string
+  Custom streaming label. When provided, used instead of `label` while `isStreaming` is true. Falls back to `label`, then to the default `"Thinking..."`.
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+- `children`: ReactNode
+
+**Colors (sf tokens used):**
+
+`bg-sf-tint`, `border-sf-line`, `text-sf-subtle`
+
+---
+
+### 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.
+
+**Type:** component
+
+**Import:** `import { AiResponse } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes
+- `children`: ReactNode
+  Child elements
+
+**Colors (sf tokens used):**
+
+`text-sf-default`
+
+---
+
+### AiShimmer
+
+AiShimmer component
+
+**Type:** component
+
+**Import:** `import { AiShimmer } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: string (required)
+  Text content to animate.
+- `as`: React.ElementType
+  HTML element or component to render as.
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `duration`: number
+  Animation duration in seconds.
+- `spread`: number
+  Shimmer width multiplier relative to text length.
+
+---
+
+### AiStatusBadge
+
+Compact pill-shaped badge showing an icon, label, and a status indicator. Used by minimal variants of AiToolCall and AiReasoning.
+
+**Type:** component
+
+**Import:** `import { AiStatusBadge } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `icon`: React.ElementType
+  Icon component rendered on the left.
+- `label`: string (required)
+  Label text displayed in the badge.
+- `status`: enum [default: idle]
+  - `"idle"`: Default idle state — no status icon shown
+  - `"running"`: Actively running — spinner icon shown
+  - `"success"`: Completed successfully — check icon shown
+  - `"error"`: Failed with an error — X icon shown
+- `info`: string
+  Additional info text (e.g. "2/3") shown after the label.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`bg-sf-tint`, `text-sf-brand`, `text-sf-danger`, `text-sf-subtle`, `text-sf-success`
+
+---
+
+### AiStreamingText
+
+AiStreamingText component
+
+**Type:** component
+
+**Import:** `import { AiStreamingText } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes
+- `children`: ReactNode
+  Child elements
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { AiSubagent } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `agentType`: string
+  Subagent type ID (e.g. `"explore"`, `"execute"`).
+- `name`: string
+  Human-readable name for this subagent.
+- `status`: enum [default: running]
+  - `"running"`: Subagent is actively processing
+  - `"completed"`: Subagent finished successfully
+  - `"error"`: Subagent encountered an error
+- `modelId`: string
+  Current model ID being used (e.g. `"claude-haiku-3.5"`).
+- `duration`: number
+  Duration in milliseconds.
+- `icon`: React.ElementType
+  Custom icon. Defaults to `RobotIcon`.
+- `defaultExpanded`: boolean
+  Whether the subagent content is expanded by default.
+- `open`: boolean
+  Controlled open state.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`bg-sf-tint`, `text-sf-brand`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`, `text-sf-success`
+
+---
+
+### AiSuggestions
+
+Horizontally scrollable container for suggestion pills. Position it relative to your prompt input (e.g. `bottom-full`).
+
+**Type:** component
+
+**Import:** `import { AiSuggestions } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { AiTaskList } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `tasks`: AiTaskItem[] (required)
+  List of tasks.
+- `title`: string
+  Optional title above the task list.
+- `icon`: React.ElementType
+  Custom icon for the title area.
+- `showProgress`: boolean
+  Show a progress summary (e.g. "3 / 7 done"). Default: `true`.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+
+**Colors (sf tokens used):**
+
+`bg-sf-brand`, `bg-sf-danger`, `bg-sf-subtle`, `bg-sf-tint`, `bg-sf-warning`, `text-sf-brand`, `text-sf-default`, `text-sf-subtle`, `text-sf-success`
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { AiTimeline } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `timeOrigin`: number
+  Wall-clock ms for the timeline origin (t=0). Defaults to the startMs of the first block across all lanes.
+- `pixelsPerSecond`: number
+  Pixels per second of elapsed time. Controls horizontal zoom level.
+- `showNowMarker`: boolean
+  Whether to show a pulsing "now" marker at the live edge.
+- `nowMs`: number
+  Current timestamp in ms. Used to render the "now" marker and open-ended block widths. Pass a stable `useState` value to prevent hydration shifts. When omitted, `Date.now()` is called at render time (fine for live views driven by a ticking parent, not suitable for SSR).
+- `density`: enum [default: comfortable]
+  - `"comfortable"`: Taller lanes with more padding
+  - `"compact"`: Tight lanes for dense views
+- `children`: ReactNode
+  Children should be `AiTimelineLane` components.
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### AiToolCall
+
+Renders a single tool call. Supports three display variants: - `"default"` — expandable card with collapsible input/output - `"inline"` — compact single-line with left accent border - `"minimal"` — pill-shaped status badge
+
+**Type:** component
+
+**Import:** `import { AiToolCall } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `variant`: enum [default: default]
+  - `"default"`: Expandable card with collapsible input/output sections
+  - `"inline"`: Compact single-line display with left accent border
+  - `"minimal"`: Pill-shaped status badge
+- `duration`: number
+  Duration in milliseconds.
+- `summary`: string
+  Summary text shown alongside the tool name.
+- `icon`: React.ElementType
+  Custom icon override.
+- `approvalState`: enum
+  Approval state for tools requiring confirmation.
+- `defaultExpanded`: boolean
+  Default expanded state for the collapsible.
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+- `children`: ReactNode
+
+**Colors (sf tokens used):**
+
+`bg-sf-brand`, `bg-sf-danger`, `bg-sf-line`, `bg-sf-recessed`, `bg-sf-success`, `bg-sf-tint`, `bg-sf-warning`, `border-sf-elevated`, `border-sf-line`, `text-sf-brand`, `text-sf-danger`, `text-sf-subtle`, `text-sf-success`, `text-sf-warning`
+
+---
+
+### AiUsageBar
+
+Compact token usage display bar. Shows input/output token counts, total, optional cost, and model identifier.  Maps to harness event: `usage_update`.
+
+**Type:** component
+
+**Import:** `import { AiUsageBar } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `inputTokens`: number
+  Input/prompt token count.
+- `outputTokens`: number
+  Output/completion token count.
+- `totalTokens`: number
+  Total token count. Computed from input + output if not provided.
+- `cost`: number
+  Estimated cost in USD.
+- `modelId`: string
+  Model ID being used (shown as label).
+- `icon`: React.ElementType
+  Custom icon. Defaults to `LightningIcon`.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+
+**Colors (sf tokens used):**
+
+`text-sf-inactive`, `text-sf-subtle`
+
+---
+
+### Badge
+
+Small status label for categorizing or highlighting content. Supports icons, loading state, status dots, dismiss, tooltip, and interactive (button/link) modes.
+
+**Type:** component
+
+**Import:** `import { Badge } from "@signalflare-ai/ui";`
+
+**Category:** Display
+
+**Props:**
+
+- `variant`: enum [default: primary]
+  - `"primary"`: Default high-emphasis badge for important labels
+  - `"secondary"`: Subtle badge for secondary information
+  - `"destructive"`: Error or danger state indicator
+  - `"outline"`: Bordered badge with transparent background
+  - `"beta"`: Indicates beta or experimental features
+  - `"success"`: Positive status indicator
+  - `"warning"`: Caution or attention indicator
+  - `"info"`: Informational badge
+  - `"ghost"`: Text-only badge with no background or border
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `children`: ReactNode
+  Content rendered inside the badge.
+- `icon`: React.ElementType
+  Icon component rendered alongside the text.
+- `iconPosition`: enum
+  Position of the icon relative to the text.
+- `loading`: boolean
+  Shows a loading spinner, replacing the icon slot.
+- `dot`: enum
+  Renders a small colored status dot before the text.
+- `tooltip`: ReactNode
+  Wraps the badge in a Tooltip with this content. Requires a TooltipProvider ancestor.
+- `href`: string
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### Banner
+
+Full-width message bar for informational, warning, or error notices.
+
+**Type:** component
+
+**Import:** `import { Banner } from "@signalflare-ai/ui";`
+
+**Category:** Feedback
+
+**Props:**
+
+- `icon`: ReactNode
+  Icon element rendered before the banner text (e.g. from `@phosphor-icons/react`).
+- `text`: string
+- `children`: ReactNode
+  Banner message content. Accepts strings or custom React elements.
+- `variant`: enum [default: default]
+  - `"default"`: Informational banner for general messages
+  - `"alert"`: Warning banner for cautionary messages
+  - `"error"`: Error banner for critical issues
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### Breadcrumbs
+
+Breadcrumbs component
+
+**Type:** component
+
+**Import:** `import { Breadcrumbs } from "@signalflare-ai/ui";`
+
+**Category:** Display
+
+**Props:**
+
+- `size`: enum [default: base]
+  - `"sm"`: Compact breadcrumbs for dense UIs
+  - `"base"`: Default breadcrumbs size
+- `children`: ReactNode
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+
+**Colors (sf tokens used):**
+
+`text-sf-inactive`, `text-sf-subtle`, `text-sf-success`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Breadcrumbs.Link
+
+Link sub-component
+
+Props:
+- `href`: string (required)
+- `icon`: React.ReactNode
+
+#### Breadcrumbs.Current
+
+Current sub-component
+
+Props:
+- `loading`: boolean
+- `icon`: React.ReactNode
+
+#### Breadcrumbs.Separator
+
+Separator sub-component
+
+#### Breadcrumbs.Clipboard
+
+Clipboard sub-component
+
+Props:
+- `text`: string (required)
+
+
+---
+
+### Button
+
+Primary action trigger. Supports multiple variants, sizes, shapes, icons, and loading state.
+
+**Type:** component
+
+**Import:** `import { Button } from "@signalflare-ai/ui";`
+
+**Category:** Action
+
+**Props:**
+
+- `shape`: enum [default: base]
+  - `"base"`: Default rectangular button shape
+  - `"square"`: Square button for icon-only actions
+  - `"circle"`: Circular button for icon-only actions
+- `size`: enum [default: base]
+  - `"xs"`: Extra small button for compact UIs
+  - `"sm"`: Small button for secondary actions
+  - `"base"`: Default button size
+  - `"lg"`: Large button for primary CTAs
+- `variant`: enum [default: secondary]
+  - `"primary"`: High-emphasis button for primary actions
+  - `"secondary"`: Default button style for most actions
+  - `"ghost"`: Minimal button with no background
+  - `"destructive"`: Danger button for destructive actions like delete
+  - `"secondary-destructive"`: Secondary button with destructive text for less prominent dangerous actions
+  - `"outline"`: Bordered button with transparent background
+
+  **State Classes:**
+  - `"primary"`:
+    - `hover`: `hover:bg-sf-brand-hover`
+    - `focus`: `focus:bg-sf-brand-hover`
+    - `disabled`: `disabled:bg-sf-brand/50`
+  - `"secondary"`:
+    - `not-disabled`: `not-disabled:hover:border-secondary! not-disabled:hover:bg-sf-control`
+    - `disabled`: `disabled:bg-sf-control/50 disabled:!text-sf-default/70`
+    - `data-state`: `data-[state=open]:bg-sf-control`
+  - `"ghost"`:
+    - `hover`: `hover:bg-sf-tint`
+  - `"destructive"`:
+    - `hover`: `hover:bg-sf-danger/70`
+  - `"secondary-destructive"`:
+    - `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
+  Icon from `@phosphor-icons/react` or a React element. Rendered before children.
+- `loading`: boolean
+  Shows a loading spinner and disables interaction.
+- `id`: string
+- `lang`: string
+- `title`: string
+- `disabled`: boolean
+- `name`: string
+- `type`: enum
+- `value`: string | string[] | number
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### Checkbox
+
+Checkbox component
+
+**Type:** component
+
+**Import:** `import { Checkbox } from "@signalflare-ai/ui";`
+
+**Category:** Input
+
+**Props:**
+
+- `variant`: enum [default: default]
+  - `"default"`: Default checkbox appearance
+  - `"error"`: Error state for validation failures
+
+  **State Classes:**
+  - `"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
+  Tooltip content to display next to the label via an info icon
+- `controlFirst`: boolean
+  When true (default), checkbox appears before label. When false, label appears before checkbox.
+- `checked`: boolean
+  Whether the checkbox is checked (controlled)
+- `indeterminate`: boolean
+  Whether the checkbox is in indeterminate state
+- `disabled`: boolean
+  Whether the checkbox is disabled
+- `name`: string
+  Name for form submission
+- `required`: boolean
+  Whether the field is required
+- `className`: string
+  Additional class name
+- `onValueChange`: (checked: boolean) => void
+  Callback when checkbox value changes
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `bg-sf-contrast`, `border-sf-line`, `ring-sf-contrast`, `ring-sf-danger`, `ring-sf-line`, `ring-sf-ring`, `text-sf-danger`, `text-sf-default`, `text-sf-inverse`, `text-sf-subtle`
+
+**Styling:**
+
+- **Dimensions:** `h-4 w-4`
+- **Border Radius:** `rounded-sm`
+- **Base Tokens:** `bg-sf-base`, `ring-sf-line`
+- **States:**
+  - `checked`: `bg-sf-contrast`, `text-sf-inverse`
+  - `indeterminate`: `bg-sf-contrast`, `text-sf-inverse`
+  - `error`: `ring-sf-danger`
+  - `hover`: `ring-sf-ring`
+  - `focus`: `ring-sf-ring`
+  - `disabled`: `opacity-50`, `cursor-not-allowed`
+- **Icons:**
+  - `ph-check` (checked) size 12
+  - `ph-minus` (indeterminate) size 12
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Checkbox.Item
+
+Item sub-component
+
+#### Checkbox.Group
+
+Group sub-component
+
+Props:
+- `legend`: string (required)
+- `children`: ReactNode (required)
+- `error`: string
+- `description`: ReactNode
+- `value`: string[]
+- `allValues`: string[]
+- `disabled`: boolean
+- `controlFirst`: boolean
+- `className`: string
+
+
+---
+
+### ClipboardText
+
+Read-only text field with a one-click copy-to-clipboard button.
+
+**Type:** component
+
+**Import:** `import { ClipboardText } from "@signalflare-ai/ui";`
+
+**Category:** Action
+
+**Props:**
+
+- `size`: enum [default: lg]
+  - `"sm"`: Small clipboard text for compact UIs
+  - `"base"`: Default clipboard text size
+  - `"lg"`: Large clipboard text for prominent display
+- `text`: string (required)
+  The text to display and copy to clipboard.
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `tooltip`: object
+  Tooltip config. Shows tooltip on hover, anchored toast on click.
+- `labels`: object
+  Accessible labels for i18n.
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `border-sf-line`, `outline-sf-fill`, `text-sf-default`
+
+**Styling:**
+
+- **Base Tokens:** `bg-sf-base`, `text-sf-default`, `ring-sf-line`, `border-sf-fill`
+- **States:**
+  - `input`: `bg-sf-control`, `text-sf-default`, `ring-sf-line`
+  - `text`: `bg-sf-base`, `font-mono`
+  - `button`: `border-sf-fill`
+- **Icons:**
+  - `ph-clipboard` (default) size 16
+  - `ph-check` (copied) size 16
+- **Input Styles:**
+  - Base: `bg-sf-control text-sf-default ring ring-sf-line`
+  - Sizes:
+    - `xs`: `h-5 gap-1 rounded-sm px-1.5 text-xs`
+    - `sm`: `h-6.5 gap-1 rounded-md px-2 text-xs`
+    - `base`: `h-9 gap-1.5 rounded-lg px-3 text-base`
+    - `lg`: `h-10 gap-2 rounded-lg px-4 text-base`
+- **Size Variants:**
+  - `sm`:
+    - Height: 26px
+    - Classes: `text-xs`
+    - Button Size: `sm`
+    - Dimensions:
+      - paddingX: 8
+      - gap: 1
+      - borderRadius: 6
+      - fontSize: 12
+  - `base`:
+    - Height: 36px
+    - Classes: `text-sm`
+    - Button Size: `base`
+    - Dimensions:
+      - paddingX: 12
+      - gap: 6
+      - borderRadius: 8
+      - fontSize: 14
+  - `lg`:
+    - Height: 40px
+    - Classes: `text-sm`
+    - Button Size: `lg`
+    - Dimensions:
+      - paddingX: 16
+      - gap: 8
+      - borderRadius: 8
+      - fontSize: 14
+
+---
+
+### Code
+
+Code component
+
+**Type:** component
+
+**Import:** `import { Code } from "@signalflare-ai/ui";`
+
+**Category:** Display
+
+**Props:**
+
+- `lang`: enum [default: ts]
+  - `"ts"`: TypeScript code
+  - `"tsx"`: TypeScript JSX code
+  - `"jsonc"`: JSON with comments
+  - `"bash"`: Shell/Bash commands
+  - `"css"`: CSS styles
+- `code`: string (required)
+  The code string to display.
+- `values`: Record<string, { value: string; highlight?: boolean }>
+  Template values for `{{key}}` interpolation. Values with `highlight: true` are visually emphasized.
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+
+**Colors (sf tokens used):**
+
+`bg-sf-recessed`, `border-sf-line`, `text-sf-default`
+
+**Styling:**
+
+- **Dimensions:** `[object Object]`
+- **Base Tokens:** `text-sf-default`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Code.Block
+
+Block sub-component
+
+Props:
+- `code`: string (required)
+- `lang`: CodeLang
+
+
+---
+
+### 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
+
+**Type:** component
+
+**Import:** `import { Collapsible } from "@signalflare-ai/ui";`
+
+**Category:** Display
+
+**Props:**
+
+- `children`: ReactNode
+- `label`: string (required)
+  Text label displayed in the trigger button
+- `open`: boolean
+  Whether the collapsible content is visible
+- `className`: string
+  Additional CSS classes for the content panel
+- `onOpenChange`: (open: boolean) => void
+  Callback when collapsed state changes
+
+**Colors (sf tokens used):**
+
+`border-sf-fill`, `text-sf-link`
+
+---
+
+### Combobox
+
+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
+
+**Import:** `import { Combobox } from "@signalflare-ai/ui";`
+
+**Category:** Input
+
+**Props:**
+
+- `inputSide`: enum [default: right]
+  - `"right"`: Input positioned inline to the right of chips
+  - `"top"`: Input positioned above chips
+- `items`: T[] (required)
+  Array of items to display in the dropdown
+- `value`: T | T[]
+  Currently selected value(s)
+- `children`: ReactNode
+  Combobox content (trigger, content, items)
+- `className`: string
+  Additional CSS classes
+- `label`: ReactNode
+  Label content for the combobox (enables Field wrapper) - can be a string or any React node
+- `required`: boolean
+  Whether the combobox is required
+- `labelTooltip`: ReactNode
+  Tooltip content to display next to the label via an info icon
+- `description`: ReactNode
+  Helper text displayed below the combobox
+- `error`: string | object
+  Error message or validation error object
+- `onValueChange`: (value: T | T[]) => void
+  Callback when selection changes
+- `multiple`: boolean
+  Allow multiple selections
+- `isItemEqualToValue`: (item: T, value: T) => boolean
+  Custom equality function for comparing items
+
+**Colors (sf tokens used):**
+
+`bg-sf-control`, `bg-sf-fill-hover`, `bg-sf-overlay`, `fill-sf-ring`, `ring-sf-line`, `text-sf-default`, `text-sf-subtle`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Combobox.Content
+
+Content sub-component
+
+Props:
+- `className`: string
+- `align`: ComboboxBase.Positioner.Props["align"]
+- `alignOffset`: ComboboxBase.Positioner.Props["alignOffset"]
+- `side`: ComboboxBase.Positioner.Props["side"]
+- `sideOffset`: ComboboxBase.Positioner.Props["sideOffset"]
+
+#### Combobox.TriggerValue
+
+TriggerValue sub-component
+
+#### Combobox.TriggerInput
+
+TriggerInput sub-component
+
+#### Combobox.TriggerMultipleWithInput
+
+TriggerMultipleWithInput sub-component
+
+#### Combobox.Chip
+
+Chip sub-component
+
+#### Combobox.Item
+
+Item sub-component
+
+#### Combobox.Input
+
+Input sub-component
+
+#### Combobox.Empty
+
+Empty sub-component
+
+#### Combobox.GroupLabel
+
+GroupLabel sub-component
+
+#### Combobox.Group
+
+Group sub-component
+
+#### Combobox.List
+
+List sub-component
+
+#### Combobox.Collection
+
+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) => (
+    <Combobox.Item key={index} value={item}>
+      {item.label}
+    </Combobox.Item>
+  )}
+</Combobox.Collection>
+```
+
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { CommandPalette } from "@signalflare-ai/ui";`
+
+**Category:** Navigation
+
+**Props:**
+
+- `open`: boolean (required)
+  Whether the dialog is open
+- `children`: ReactNode
+  Child content - typically one or more Panel components
+
+**Colors (sf tokens used):**
+
+`bg-sf-elevated`, `bg-sf-overlay`, `bg-sf-warning`, `ring-sf-line`, `text-sf-default`, `text-sf-strong`, `text-sf-subtle`
+
+---
+
+### DataGrid
+
+DataGrid component
+
+**Type:** component
+
+**Import:** `import { DataGrid } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `layout`: enum [default: auto]
+  - `"auto"`: Auto column sizing - columns resize based on content
+  - `"fixed"`: Fixed column sizing - columns have equal width
+- `className`: string
+  Additional CSS classes
+- `children`: ReactNode
+  Child elements
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `bg-sf-brand`, `bg-sf-line`, `bg-sf-overlay`, `bg-sf-tint`, `border-sf-line`, `text-sf-brand`, `text-sf-subtle`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### DataGrid.Toolbar
+
+Toolbar sub-component
+
+#### DataGrid.Content
+
+Content sub-component
+
+#### DataGrid.Pagination
+
+Pagination sub-component
+
+#### DataGrid.ColumnToggle
+
+ColumnToggle sub-component
+
+#### DataGrid.Empty
+
+Empty sub-component
+
+
+---
+
+### DatePicker
+
+DatePicker — a date selection calendar.  Built on [react-day-picker](https://daypicker.dev) with SF styling. Supports three selection modes: single, multiple, and range.
+
+**Type:** component
+
+**Import:** `import { DatePicker } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes
+- `children`: ReactNode
+  Child elements
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`
+
+---
+
+### 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.
+
+**Type:** component
+
+**Import:** `import { DateRangePicker } from "@signalflare-ai/ui";`
+
+**Category:** Input
+
+**Props:**
+
+- `size`: enum [default: base]
+  - `"sm"`: Compact calendar for tight spaces
+  - `"base"`: Default calendar size
+  - `"lg"`: Large calendar for prominent date selection
+- `variant`: enum [default: default]
+  - `"default"`: Default calendar appearance
+  - `"subtle"`: Subtle calendar with minimal background
+- `timezone`: string
+  Display timezone string shown in the footer.
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `onStartDateChange`: (date: Date | null) => void
+  Callback when start date changes
+- `onEndDateChange`: (date: Date | null) => void
+  Callback when end date changes
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `bg-sf-contrast`, `bg-sf-fill`, `bg-sf-interact`, `bg-sf-overlay`, `text-sf-default`, `text-sf-inverse`, `text-sf-strong`, `text-sf-subtle`
+
+**Styling:**
+
+- **Size Variants:**
+  - `sm`:
+    - Classes: `p-3 gap-2`
+    - Dimensions:
+      - calendarWidth: 168
+      - cellHeight: 22
+      - cellWidth: 24
+      - textSize: 12
+      - iconSize: 14
+      - padding: 12
+      - gap: 8
+  - `base`:
+    - Classes: `p-4 gap-2.5`
+    - Dimensions:
+      - calendarWidth: 196
+      - cellHeight: 26
+      - cellWidth: 28
+      - textSize: 14
+      - iconSize: 16
+      - padding: 16
+      - gap: 10
+  - `lg`:
+    - Classes: `p-5 gap-3`
+    - Dimensions:
+      - calendarWidth: 252
+      - cellHeight: 32
+      - cellWidth: 36
+      - textSize: 16
+      - iconSize: 18
+      - padding: 20
+      - gap: 12
+
+---
+
+### Dialog
+
+Dialog component
+
+**Type:** component
+
+**Import:** `import { Dialog } from "@signalflare-ai/ui";`
+
+**Category:** Overlay
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `children`: ReactNode
+  Dialog content (typically Title, Description, Close, and action buttons).
+- `size`: enum [default: base]
+  - `"base"`: Default dialog width
+  - `"sm"`: Small dialog for simple confirmations
+  - `"lg"`: Large dialog for complex content
+  - `"xl"`: Extra large dialog for detailed views
+
+**Colors (sf tokens used):**
+
+`bg-sf-elevated`, `bg-sf-overlay`, `text-sf-default`, `text-sf-subtle`
+
+**Styling:**
+
+- **Dimensions:** `[object Object]`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Dialog.Root
+
+Root sub-component
+
+#### Dialog.Trigger
+
+Trigger sub-component
+
+#### Dialog.Title
+
+Title sub-component
+
+#### Dialog.Description
+
+Description sub-component
+
+#### Dialog.Close
+
+Close sub-component
+
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { DropdownMenu } from "@signalflare-ai/ui";`
+
+**Category:** Overlay
+
+**Props:**
+
+- `variant`: enum [default: default]
+  - `"default"`: Default dropdown item appearance
+  - `"danger"`: Destructive action item
+
+**Colors (sf tokens used):**
+
+`bg-sf-control`, `bg-sf-danger`, `bg-sf-line`, `bg-sf-overlay`, `bg-sf-tint`, `ring-sf-line`, `text-sf-danger`, `text-sf-default`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### DropdownMenu.Trigger
+
+Trigger sub-component
+
+#### DropdownMenu.Portal
+
+Portal sub-component (wraps DropdownMenuPrimitive)
+
+#### DropdownMenu.Sub
+
+Sub sub-component (wraps DropdownMenuPrimitive)
+
+#### DropdownMenu.SubTrigger
+
+SubTrigger sub-component
+
+#### DropdownMenu.SubContent
+
+SubContent sub-component
+
+#### DropdownMenu.Content
+
+Content sub-component
+
+#### DropdownMenu.Item
+
+Item sub-component
+
+#### DropdownMenu.CheckboxItem
+
+CheckboxItem sub-component
+
+#### DropdownMenu.RadioGroup
+
+RadioGroup sub-component (wraps DropdownMenuPrimitive)
+
+#### DropdownMenu.RadioItem
+
+RadioItem sub-component
+
+#### DropdownMenu.RadioItemIndicator
+
+RadioItemIndicator sub-component
+
+#### DropdownMenu.Label
+
+Label sub-component
+
+#### DropdownMenu.Separator
+
+Separator sub-component
+
+#### DropdownMenu.Shortcut
+
+Shortcut sub-component
+
+#### DropdownMenu.Group
+
+Group sub-component (wraps DropdownMenuPrimitive)
+
+
+---
+
+### Empty
+
+Placeholder shown when a list, table, or page has no content to display.
+
+**Type:** component
+
+**Import:** `import { Empty } from "@signalflare-ai/ui";`
+
+**Category:** Display
+
+**Props:**
+
+- `size`: enum [default: base]
+  - `"sm"`: Compact empty state for smaller containers
+  - `"base"`: Default empty state size
+  - `"lg"`: Large empty state for prominent placement
+- `icon`: ReactNode
+  Decorative icon displayed above the title (e.g. from `@phosphor-icons/react`).
+- `title`: string (required)
+  Primary heading text for the empty state.
+- `description`: string
+  Secondary description text displayed below the title.
+- `commandLine`: string
+  Shell command displayed in a copyable code block.
+- `contents`: ReactNode
+  Additional content (buttons, links) rendered below the description.
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### Field
+
+Form field wrapper that provides a label, optional description, and error display around any form control. Built on Base UI Field primitives.
+
+**Type:** component
+
+**Import:** `import { Field } from "@signalflare-ai/ui";`
+
+**Category:** Input
+
+**Props:**
+
+- `controlFirst`: boolean
+  When `true`, places the control before the label (for checkbox/switch layouts).
+- `children`: ReactNode
+  The form control element(s) to wrap (Input, Select, Checkbox, etc.).
+- `label`: ReactNode
+  The label content — can be a string or any React node.
+- `required`: boolean
+  When explicitly `false`, shows gray "(optional)" text after the label. When `true` or `undefined`, no indicator is shown.
+- `labelTooltip`: ReactNode
+  Tooltip content displayed next to the label via an info icon.
+- `error`: object
+  Validation error with a message and a browser `ValidityState` match key.
+- `description`: ReactNode
+  Helper text displayed below the control (hidden when `error` is present).
+
+**Colors (sf tokens used):**
+
+`text-sf-danger`, `text-sf-default`, `text-sf-subtle`
+
+---
+
+### 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.
+
+**Type:** component
+
+**Import:** `import { Filters } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `filters`: Filter[] (required)
+  Active filters array
+- `fields`: FilterFieldConfig[] (required)
+  Available field configurations
+- `size`: enum [default: default]
+  - `"sm"`: Small filter items
+  - `"default"`: Default filter items
+  - `"lg"`: Large filter items
+- `trigger`: ReactNode
+  Custom trigger element (replaces default "Add Filter" button)
+- `showSearchInput`: boolean
+  Whether to show a search input in the add filter menu
+- `allowMultiple`: boolean
+  Whether to allow multiple filters on the same field
+- `enableShortcut`: boolean
+  Whether to enable keyboard shortcut (Cmd/Ctrl + K) to open add filter
+- `shortcutKey`: string
+  Keyboard shortcut key (default: "k")
+- `shortcutLabel`: string
+  Label shown in the shortcut tooltip
+- `i18n`: Partial<FilterI18nConfig>
+  i18n configuration for labels
+- `className`: string
+  Additional CSS classes
+- `menuPopupClassName`: string
+  CSS classes for the filter menu popup
+
+**Colors (sf tokens used):**
+
+`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`
+
+---
+
+### Grid
+
+Responsive CSS grid layout container with preset column configurations.
+
+**Type:** component
+
+**Import:** `import { Grid } from "@signalflare-ai/ui";`
+
+**Category:** Layout
+
+**Props:**
+
+- `children`: ReactNode
+  Grid items to render.
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `id`: string
+- `lang`: string
+- `title`: string
+- `mobileDivider`: boolean
+  Show dividers between grid items on mobile (only works with `"4up"` variant).
+- `gap`: enum [default: base]
+  - `"none"`: No gap between grid items
+  - `"sm"`: Small gap between grid items
+  - `"base"`: Default responsive gap between grid items
+  - `"lg"`: Large gap between grid items
+- `variant`: enum
+  - `"2up"`: Grid items stack on small screens, display side-by-side on medium screens and up
+  - `"side-by-side"`: Grid items always displayed side-by-side
+  - `"2-1"`: Two-thirds / one-third split (66%/33%) on medium screens and up
+  - `"1-2"`: One-third / two-thirds split (33%/66%) on medium screens and up
+  - `"1-3up"`: Grid items stack on small screens, expand to 3 across on large screens
+  - `"3up"`: Grid items stack on small screens, 2 across on medium, 3 across on large
+  - `"4up"`: Grid items stack on small screens, progressively increase columns at larger breakpoints
+  - `"6up"`: Grid items start at 2 across, expand to 6 across on XL
+  - `"1-2-4up"`: Grid items stack on small screens, 2 across on medium, 4 across on large
+
+**Colors (sf tokens used):**
+
+`border-sf-line`
+
+---
+
+### Input
+
+Input component
+
+**Type:** component
+
+**Import:** `import { Input } from "@signalflare-ai/ui";`
+
+**Category:** Input
+
+**Props:**
+
+- `label`: ReactNode
+  Label content for the input (enables Field wrapper) - can be a string or any React node
+- `labelTooltip`: ReactNode
+  Tooltip content to display next to the label via an info icon
+- `description`: ReactNode
+  Helper text displayed below the input
+- `error`: string | object
+  Error message or validation error object
+- `size`: enum [default: base]
+  - `"xs"`: Extra small input for compact UIs
+  - `"sm"`: Small input for secondary fields
+  - `"base"`: Default input size
+  - `"lg"`: Large input for prominent fields
+- `variant`: enum [default: default]
+  - `"default"`: Default input appearance
+  - `"error"`: Error state for validation failures
+
+  **State Classes:**
+  - `"default"`:
+    - `focus`: `focus:ring-sf-ring`
+  - `"error"`:
+    - `focus`: `focus:ring-sf-danger`
+
+**Colors (sf tokens used):**
+
+`bg-sf-control`, `ring-sf-danger`, `ring-sf-line`, `ring-sf-ring`, `text-sf-default`, `text-sf-subtle`
+
+**Styling:**
+
+- **Dimensions:** `[object Object]`
+
+---
+
+### 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
+
+**Type:** component
+
+**Import:** `import { Label } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: ReactNode
+  The label content — can be a string or any React node.
+- `showOptional`: boolean
+  When `true`, shows gray "(optional)" text after the label.
+- `tooltip`: ReactNode
+  Tooltip content displayed next to the label via an info icon.
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `htmlFor`: string
+  The id of the form element this label is associated with
+- `asContent`: boolean
+  When true, only renders the inline content (indicators, tooltip) without the outer label element with font styling. Useful when composed inside another label element that already provides the text styling.
+
+**Colors (sf tokens used):**
+
+`text-sf-default`, `text-sf-strong`
+
+---
+
+### LayerCard
+
+LayerCard component
+
+**Type:** component
+
+**Import:** `import { LayerCard } from "@signalflare-ai/ui";`
+
+**Category:** Display
+
+**Props:**
+
+- `children`: ReactNode
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `bg-sf-elevated`, `ring-sf-fill`, `ring-sf-line`, `text-sf-strong`
+
+**Styling:**
+
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### LayerCard.Primary
+
+Primary sub-component
+
+#### LayerCard.Secondary
+
+Secondary sub-component
+
+
+---
+
+### Link
+
+Link component
+
+**Type:** component
+
+**Import:** `import { Link } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `variant`: enum [default: inline]
+  - `"inline"`: Inline text link that flows with content
+  - `"current"`: Link that inherits color from parent text
+  - `"plain"`: Link without underline decoration
+
+  **State Classes:**
+  - `"plain"`:
+    - `hover`: `hover:text-primary/70`
+- `to`: string
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+- `download`: unknown
+- `href`: string
+- `hrefLang`: string
+- `media`: string
+- `ping`: string
+- `target`: React.HTMLAttributeAnchorTarget
+- `type`: string
+- `referrerPolicy`: enum
+- `render`: ReactNode
+  Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
+
+Accepts a `ReactElement` or a function that returns the element to render.
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Link.ExternalIcon
+
+ExternalIcon sub-component
+
+
+---
+
+### Loader
+
+Animated circular spinner for indicating loading states. Uses CSS keyframe animations for broad compatibility.
+
+**Type:** component
+
+**Import:** `import { Loader } from "@signalflare-ai/ui";`
+
+**Category:** Feedback
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `size`: enum [default: base]
+  - `"sm"`: Small loader for inline use
+  - `"base"`: Default loader size
+  - `"lg"`: Large loader for prominent loading states
+
+---
+
+### 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.
+
+**Type:** component
+
+**Import:** `import { MenuBar } from "@signalflare-ai/ui";`
+
+**Category:** Navigation
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `isActive`: number | boolean | string
+  The currently active option value — matched against option index or `id`.
+- `options`: MenuOptionProps[] (required)
+  Array of menu option configurations.
+- `optionIds`: boolean
+  When true, each option's `id` field is used for matching instead of its array index.
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `bg-sf-fill`, `border-sf-fill`
+
+**Styling:**
+
+
+---
+
+### Meter
+
+Progress bar showing a measured value within a known range (e.g. quota usage).
+
+**Type:** component
+
+**Import:** `import { Meter } from "@signalflare-ai/ui";`
+
+**Category:** Display
+
+**Props:**
+
+- `customValue`: string
+  Custom formatted value text (e.g. "750 / 1,000") displayed instead of percentage.
+- `label`: string (required)
+  Label text displayed above the meter track.
+- `showValue`: boolean
+  Whether to display the percentage value next to the label.
+- `trackClassName`: string
+  Additional CSS classes for the track (background bar).
+- `indicatorClassName`: string
+  Additional CSS classes for the indicator (filled bar).
+- `value`: number
+  Current value of the meter
+- `max`: number
+  Maximum value of the meter (default: 100)
+- `min`: number
+  Minimum value of the meter (default: 0)
+
+**Colors (sf tokens used):**
+
+`bg-sf-fill`, `text-sf-default`, `text-sf-strong`
+
+---
+
+### Pagination
+
+Page navigation controls with page count display.
+
+**Type:** component
+
+**Import:** `import { Pagination } from "@signalflare-ai/ui";`
+
+**Category:** Navigation
+
+**Props:**
+
+- `controls`: enum [default: full]
+  - `"full"`: Full pagination controls with first, previous, page input, next, and last buttons
+  - `"simple"`: Simple pagination controls with only previous and next buttons
+- `setPage`: (page: number) => void (required)
+  Callback when page changes
+- `page`: number
+  Current page number (1-indexed).
+- `perPage`: number
+  Number of items displayed per page.
+- `totalCount`: number
+  Total number of items across all pages.
+- `text`: object
+  Method to provide custom pagination text
+
+**Colors (sf tokens used):**
+
+`text-sf-strong`
+
+**Styling:**
+
+
+---
+
+### Popover
+
+Popover component for displaying accessible popup content anchored to a trigger.
+
+**Type:** component
+
+**Import:** `import { Popover } from "@signalflare-ai/ui";`
+
+**Category:** Overlay
+
+**Props:**
+
+- `side`: enum [default: bottom]
+  - `"top"`: Popover appears above the trigger
+  - `"bottom"`: Popover appears below the trigger
+  - `"left"`: Popover appears to the left of the trigger
+  - `"right"`: Popover appears to the right of the trigger
+
+**Colors (sf tokens used):**
+
+`bg-sf-elevated`, `fill-sf-elevated`, `fill-sf-tip-shadow`, `fill-sf-tip-stroke`, `outline-sf-fill`, `text-sf-default`, `text-sf-subtle`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Popover.Trigger
+
+Trigger sub-component
+
+#### Popover.Content
+
+Content sub-component
+
+#### Popover.Title
+
+Title sub-component
+
+#### Popover.Description
+
+Description sub-component
+
+#### Popover.Close
+
+Close sub-component
+
+
+---
+
+### PromptInput
+
+Prompt input form. Can be self-managed or controlled via `PromptInputProvider`.
+
+**Type:** component
+
+**Import:** `import { PromptInput } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `globalDrop`: boolean
+  When true, accept drops anywhere on document. Default false.
+- `maxFiles`: number
+  Maximum number of attached files.
+- `maxFileSize`: number
+  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"`.
+- `backLayerOpen`: boolean
+  Controls whether the back layer is visible. Pair with `onBackLayerOpenChange` for a controlled pattern.
+- `autoOpenBackLayerWhen`: boolean
+  Automatically opens the back layer when this condition is true. Useful for showing pending approvals/questions without manual toggle.
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+- `children`: ReactNode
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `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`
+
+---
+
+### 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
+
+**Import:** `import { Radio } from "@signalflare-ai/ui";`
+
+**Category:** Input
+
+**Props:**
+
+- `legend`: string (required)
+  Legend text for the group (required for accessibility)
+- `children`: ReactNode
+  Child Radio.Item components
+- `orientation`: enum
+  Layout direction of the radio items
+- `error`: string
+  Error message for the group
+- `description`: ReactNode
+  Helper text for the group
+- `value`: string
+  Value of the radio that should be selected (controlled)
+- `disabled`: boolean
+  Whether all radios in the group are disabled
+- `controlPosition`: enum
+  Position of radio control relative to label: "start" (default) puts radio before label, "end" puts label before radio
+- `name`: string
+  Form submission name for the radio group
+- `className`: string
+  Additional CSS classes
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `bg-sf-contrast`, `border-sf-line`, `ring-sf-danger`, `ring-sf-line`, `ring-sf-ring`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`
+
+---
+
+### Select
+
+Select component
+
+**Type:** component
+
+**Import:** `import { Select } from "@signalflare-ai/ui";`
+
+**Category:** Input
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `label`: ReactNode
+  Label content for the select (enables Field wrapper) — can be a string or any React node.
+- `hideLabel`: boolean
+  Visually hide the label while keeping it accessible to screen readers. Set to `false` to show a visible label above the select via the Field wrapper.
+- `placeholder`: string
+  Placeholder text shown when no value is selected.
+- `loading`: boolean
+  When `true`, shows a skeleton loader in place of the selected value.
+- `disabled`: boolean
+  Whether the select is disabled.
+- `required`: boolean
+  Whether the select is required. When `false`, shows "(optional)" text.
+- `labelTooltip`: ReactNode
+  Tooltip content displayed next to the label via an info icon.
+- `value`: string
+  Currently selected value (controlled mode).
+- `children`: ReactNode
+  `Select.Option` elements to render in the dropdown.
+- `description`: ReactNode
+  Helper text displayed below the select.
+- `error`: string | object
+  Error message string or validation error object with `match` key.
+- `onValueChange`: (value: string) => void
+  Callback when selection changes
+- `defaultValue`: string
+  Initial value for uncontrolled mode
+
+**Colors (sf tokens used):**
+
+`bg-sf-control`, `bg-sf-overlay`, `ring-sf-line`, `ring-sf-ring`, `text-sf-default`
+
+**Styling:**
+
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Select.Option
+
+Option sub-component
+
+
+---
+
+### SensitiveInput
+
+Password/secret input that masks its value by default and reveals on click. Includes a built-in copy-to-clipboard button on hover.
+
+**Type:** component
+
+**Import:** `import { SensitiveInput } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `alt`: string
+- `autoComplete`: React.HTMLInputAutoCompleteAttribute
+- `checked`: boolean
+- `disabled`: boolean
+- `height`: number | string
+- `list`: string
+- `name`: string
+- `placeholder`: string
+- `readOnly`: boolean
+- `required`: boolean
+- `width`: number | string
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+- `children`: ReactNode
+- `value`: string
+  Controlled value
+- `size`: enum [default: base]
+  Size of the input.
+- `"xs"` — Extra small for compact UIs
+- `"sm"` — Small for secondary fields
+- `"base"` — Default input size
+- `"lg"` — Large for prominent fields
+- `variant`: enum [default: default]
+  Style variant of the input.
+- `"default"` — Default input appearance
+- `"error"` — Error state for validation failures
+- `label`: ReactNode
+  Label content for the input (enables Field wrapper and sets masked state label) - can be a string or any React node
+- `labelTooltip`: ReactNode
+  Tooltip content to display next to the label via an info icon
+- `description`: ReactNode
+  Helper text displayed below the input
+- `error`: string | object
+  Error message or validation error object
+
+**Colors (sf tokens used):**
+
+`bg-sf-brand`, `bg-sf-control`, `outline-sf-ring`, `text-sf-default`, `text-sf-subtle`
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { Sidebar } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `defaultOpen`: boolean
+  Initial open state when uncontrolled.
+- `open`: boolean
+  Controlled open state.
+- `variant`: enum [default: sidebar]
+  - `"sidebar"`: Standard sidebar with border separator
+  - `"floating"`: Floating sidebar with shadow and rounded corners
+  - `"inset"`: Inset sidebar within the content area
+- `side`: enum [default: left]
+  - `"left"`: Left-aligned sidebar
+  - `"right"`: Right-aligned sidebar
+- `collapsible`: enum [default: icon]
+  - `"icon"`: Collapses to show icons only
+  - `"offcanvas"`: Slides off screen when collapsed
+  - `"none"`: Cannot be collapsed
+- `resizable`: boolean
+  Enable drag-to-resize on the sidebar edge.
+- `defaultWidth`: number
+  Initial width in pixels when resizable.
+- `minWidth`: number
+  Minimum width in pixels when resizing.
+- `maxWidth`: number
+  Maximum width in pixels when resizing.
+- `children`: ReactNode
+  Content — typically `<Sidebar>` + main content.
+- `className`: string
+  Additional CSS classes for the wrapper div.
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `bg-sf-brand`, `bg-sf-line`, `bg-sf-overlay`, `bg-sf-recessed`, `bg-sf-tint`, `border-sf-line`, `ring-sf-line`, `ring-sf-ring`, `text-sf-default`, `text-sf-strong`, `text-sf-subtle`
+
+**Styling:**
+
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Sidebar.Provider
+
+Provider sub-component
+
+Props:
+- `defaultOpen`: boolean
+- `open`: boolean
+- `variant`: SidebarVariant
+- `side`: SidebarSide
+- `collapsible`: "icon" | "offcanvas" | "none"
+- `resizable`: boolean
+- `defaultWidth`: number
+- `minWidth`: number
+- `maxWidth`: number
+- `children`: ReactNode (required)
+- `className`: string
+
+#### Sidebar.Header
+
+Header sub-component
+
+#### Sidebar.Content
+
+Content sub-component
+
+#### Sidebar.Footer
+
+Footer sub-component
+
+#### Sidebar.Group
+
+Group sub-component
+
+#### Sidebar.GroupLabel
+
+GroupLabel sub-component
+
+#### Sidebar.GroupContent
+
+GroupContent sub-component
+
+#### Sidebar.Menu
+
+Menu sub-component
+
+#### Sidebar.MenuItem
+
+MenuItem sub-component
+
+#### Sidebar.MenuButton
+
+MenuButton sub-component
+
+#### Sidebar.MenuAction
+
+MenuAction sub-component
+
+#### Sidebar.MenuBadge
+
+MenuBadge sub-component
+
+#### Sidebar.MenuSub
+
+MenuSub sub-component
+
+#### Sidebar.MenuSubItem
+
+MenuSubItem sub-component
+
+#### Sidebar.MenuSubButton
+
+MenuSubButton sub-component
+
+#### Sidebar.Separator
+
+Separator sub-component
+
+#### Sidebar.Input
+
+Input sub-component
+
+#### Sidebar.Trigger
+
+Trigger sub-component
+
+#### Sidebar.Rail
+
+Rail sub-component
+
+#### Sidebar.ResizeHandle
+
+ResizeHandle sub-component
+
+#### Sidebar.MenuChevron
+
+MenuChevron sub-component
+
+#### Sidebar.Collapsible
+
+Collapsible sub-component
+
+#### Sidebar.CollapsibleTrigger
+
+CollapsibleTrigger sub-component
+
+#### Sidebar.CollapsibleContent
+
+CollapsibleContent sub-component
+
+
+---
+
+### SignalFlareAILogo
+
+SignalFlare AI logo component.
+
+**Type:** component
+
+**Import:** `import { SignalFlareAILogo } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: ReactNode
+- `className`: string
+- `height`: number | string
+- `id`: string
+- `lang`: string
+- `media`: string
+- `method`: string
+- `name`: string
+- `target`: string
+- `type`: string
+- `width`: number | string
+- `accentHeight`: number | string
+- `accumulate`: enum
+- `additive`: enum
+- `alignmentBaseline`: enum
+- `allowReorder`: enum
+- `alphabetic`: number | string
+- `amplitude`: number | string
+- `arabicForm`: enum
+- `ascent`: number | string
+- `attributeName`: string
+- `attributeType`: string
+- `autoReverse`: Booleanish
+- `azimuth`: number | string
+- `baseFrequency`: number | string
+- `baselineShift`: number | string
+- `baseProfile`: number | string
+- `bbox`: number | string
+- `begin`: number | string
+- `bias`: number | string
+- `by`: number | string
+- `calcMode`: number | string
+- `capHeight`: number | string
+- `clip`: number | string
+- `clipPath`: string
+- `clipPathUnits`: number | string
+- `clipRule`: number | string
+- `colorInterpolation`: number | string
+- `colorInterpolationFilters`: enum
+- `colorProfile`: number | string
+- `colorRendering`: number | string
+- `contentScriptType`: number | string
+- `contentStyleType`: number | string
+- `cursor`: number | string
+- `cx`: number | string
+- `cy`: number | string
+- `d`: string
+- `decelerate`: number | string
+- `descent`: number | string
+- `diffuseConstant`: number | string
+- `direction`: number | string
+- `display`: number | string
+- `divisor`: number | string
+- `dominantBaseline`: enum
+- `dur`: number | string
+- `dx`: number | string
+- `dy`: number | string
+- `edgeMode`: number | string
+- `elevation`: number | string
+- `enableBackground`: number | string
+- `end`: number | string
+- `exponent`: number | string
+- `externalResourcesRequired`: Booleanish
+- `fill`: string
+- `fillOpacity`: number | string
+- `fillRule`: enum
+- `filter`: string
+- `filterRes`: number | string
+- `filterUnits`: number | string
+- `floodColor`: number | string
+- `floodOpacity`: number | string
+- `focusable`: Booleanish | string
+- `fontFamily`: string
+- `fontSize`: number | string
+- `fontSizeAdjust`: number | string
+- `fontStretch`: number | string
+- `fontStyle`: number | string
+- `fontVariant`: number | string
+- `fontWeight`: number | string
+- `format`: number | string
+- `fr`: number | string
+- `from`: number | string
+- `fx`: number | string
+- `fy`: number | string
+- `g1`: number | string
+- `g2`: number | string
+- `glyphName`: number | string
+- `glyphOrientationHorizontal`: number | string
+- `glyphOrientationVertical`: number | string
+- `glyphRef`: number | string
+- `gradientTransform`: string
+- `gradientUnits`: string
+- `hanging`: number | string
+- `horizAdvX`: number | string
+- `horizOriginX`: number | string
+- `href`: string
+- `ideographic`: number | string
+- `imageRendering`: number | string
+- `in2`: number | string
+- `in`: string
+- `intercept`: number | string
+- `k1`: number | string
+- `k2`: number | string
+- `k3`: number | string
+- `k4`: number | string
+- `k`: number | string
+- `kernelMatrix`: number | string
+- `kernelUnitLength`: number | string
+- `kerning`: number | string
+- `keyPoints`: number | string
+- `keySplines`: number | string
+- `keyTimes`: number | string
+- `lengthAdjust`: number | string
+- `letterSpacing`: number | string
+- `lightingColor`: number | string
+- `limitingConeAngle`: number | string
+- `local`: number | string
+- `markerEnd`: string
+- `markerHeight`: number | string
+- `markerMid`: string
+- `markerStart`: string
+- `markerUnits`: number | string
+- `markerWidth`: number | string
+- `mask`: string
+- `maskContentUnits`: number | string
+- `maskUnits`: number | string
+- `mathematical`: number | string
+- `mode`: number | string
+- `numOctaves`: number | string
+- `offset`: number | string
+- `opacity`: number | string
+- `operator`: number | string
+- `order`: number | string
+- `orient`: number | string
+- `orientation`: number | string
+- `origin`: number | string
+- `overflow`: number | string
+- `overlinePosition`: number | string
+- `overlineThickness`: number | string
+- `paintOrder`: number | string
+- `panose1`: number | string
+- `path`: string
+- `pathLength`: number | string
+- `patternContentUnits`: string
+- `patternTransform`: number | string
+- `patternUnits`: string
+- `pointerEvents`: number | string
+- `points`: string
+- `pointsAtX`: number | string
+- `pointsAtY`: number | string
+- `pointsAtZ`: number | string
+- `preserveAlpha`: Booleanish
+- `preserveAspectRatio`: string
+- `primitiveUnits`: number | string
+- `r`: number | string
+- `radius`: number | string
+- `refX`: number | string
+- `refY`: number | string
+- `renderingIntent`: number | string
+- `repeatCount`: number | string
+- `repeatDur`: number | string
+- `requiredExtensions`: number | string
+- `requiredFeatures`: number | string
+- `restart`: number | string
+- `result`: string
+- `rotate`: number | string
+- `rx`: number | string
+- `ry`: number | string
+- `scale`: number | string
+- `seed`: number | string
+- `shapeRendering`: number | string
+- `slope`: number | string
+- `spacing`: number | string
+- `specularConstant`: number | string
+- `specularExponent`: number | string
+- `speed`: number | string
+- `spreadMethod`: string
+- `startOffset`: number | string
+- `stdDeviation`: number | string
+- `stemh`: number | string
+- `stemv`: number | string
+- `stitchTiles`: number | string
+- `stopColor`: string
+- `stopOpacity`: number | string
+- `strikethroughPosition`: number | string
+- `strikethroughThickness`: number | string
+- `string`: number | string
+- `stroke`: string
+- `strokeDasharray`: string | number
+- `strokeDashoffset`: string | number
+- `strokeLinecap`: enum
+- `strokeLinejoin`: enum
+- `strokeMiterlimit`: number | string
+- `strokeOpacity`: number | string
+- `strokeWidth`: number | string
+- `surfaceScale`: number | string
+- `systemLanguage`: number | string
+- `tableValues`: number | string
+- `targetX`: number | string
+- `targetY`: number | string
+- `textAnchor`: enum
+- `textDecoration`: number | string
+- `textLength`: number | string
+- `textRendering`: number | string
+- `to`: number | string
+- `transform`: string
+- `u1`: number | string
+- `u2`: number | string
+- `underlinePosition`: number | string
+- `underlineThickness`: number | string
+- `unicode`: number | string
+- `unicodeBidi`: number | string
+- `unicodeRange`: number | string
+- `unitsPerEm`: number | string
+- `vAlphabetic`: number | string
+- `values`: string
+- `vectorEffect`: number | string
+- `version`: string
+- `vertAdvY`: number | string
+- `vertOriginX`: number | string
+- `vertOriginY`: number | string
+- `vHanging`: number | string
+- `vIdeographic`: number | string
+- `viewBox`: string
+- `viewTarget`: number | string
+- `visibility`: number | string
+- `vMathematical`: number | string
+- `widths`: number | string
+- `wordSpacing`: number | string
+- `writingMode`: number | string
+- `x1`: number | string
+- `x2`: number | string
+- `x`: number | string
+- `xChannelSelector`: string
+- `xHeight`: number | string
+- `xlinkActuate`: string
+- `xlinkArcrole`: string
+- `xlinkHref`: string
+- `xlinkRole`: string
+- `xlinkShow`: string
+- `xlinkTitle`: string
+- `xlinkType`: string
+- `xmlBase`: string
+- `xmlLang`: string
+- `xmlns`: string
+- `xmlnsXlink`: string
+- `xmlSpace`: string
+- `y1`: number | string
+- `y2`: number | string
+- `y`: number | string
+- `yChannelSelector`: string
+- `z`: number | string
+- `zoomAndPan`: string
+- `variant`: enum [default: full]
+  - `"glyph"`: Map pin icon only (logomark)
+  - `"full"`: Full logo with icon, wordmark, and decorative element
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `ring-sf-line`, `text-sf-default`
+
+---
+
+### Surface
+
+Surface component
+
+**Type:** component
+
+**Import:** `import { Surface } from "@signalflare-ai/ui";`
+
+**Category:** Layout
+
+**Props:**
+
+- `as`: React.ElementType
+  The HTML element type to render as (e.g. `"div"`, `"section"`, `"article"`).
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `children`: ReactNode
+  Content rendered inside the surface.
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `ring-sf-line`
+
+---
+
+### Switch
+
+Switch component
+
+**Type:** component
+
+**Import:** `import { Switch } from "@signalflare-ai/ui";`
+
+**Category:** Input
+
+**Props:**
+
+- `variant`: enum [default: default]
+  - `"default"`: Default switch appearance
+  - `"error"`: Error state for validation failures
+- `label`: ReactNode
+  Label content for the switch (Field wrapper is built-in) - can be a string or any React node. Optional when used standalone for visual-only purposes.
+- `labelTooltip`: ReactNode
+  Tooltip content to display next to the label via an info icon
+- `required`: boolean
+  Whether the switch is required. When explicitly false, shows "(optional)" text after the label.
+- `controlFirst`: boolean
+  When true (default), switch appears before label. When false, label appears before switch.
+- `size`: enum [default: base]
+  - `"sm"`: Small switch for compact UIs
+  - `"base"`: Default switch size
+  - `"lg"`: Large switch for prominent toggles
+- `checked`: boolean
+- `disabled`: boolean
+- `transitioning`: boolean
+- `name`: string
+- `type`: enum
+- `value`: string | string[] | number
+- `className`: string
+- `id`: string
+- `lang`: string
+- `title`: string
+- `onClick`: (event: React.MouseEvent) => void (required)
+  Callback when switch is clicked
+
+**Colors (sf tokens used):**
+
+`bg-sf-brand`, `bg-sf-brand-hover`, `bg-sf-danger`, `bg-sf-interact`, `bg-sf-recessed`, `border-sf-line`, `ring-sf-danger`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Switch.Item
+
+Item sub-component
+
+#### Switch.Group
+
+Group sub-component
+
+Props:
+- `legend`: string (required)
+- `children`: ReactNode (required)
+- `error`: string
+- `description`: ReactNode
+- `disabled`: boolean
+- `controlFirst`: boolean
+- `className`: string
+
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { Table } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `layout`: enum [default: auto]
+  - `"auto"`: Auto table layout - columns resize based on content
+  - `"fixed"`: Fixed table layout - columns have equal width, controlled via colgroup
+- `variant`: enum [default: default]
+  - `"default"`: Default row variant
+  - `"selected"`: Selected row variant
+- `className`: string
+  Additional CSS classes
+- `children`: ReactNode
+  Child elements
+
+**Colors (sf tokens used):**
+
+`bg-sf-base`, `bg-sf-ring`, `bg-sf-tint`, `border-sf-fill`, `text-sf-default`
+
+**Sub-Components:**
+
+This is a compound component. Use these sub-components:
+
+#### Table.Header
+
+Header sub-component
+
+#### Table.Head
+
+Head sub-component
+
+#### Table.Row
+
+Row sub-component
+
+#### Table.Body
+
+Body sub-component
+
+#### Table.Cell
+
+Cell sub-component
+
+#### Table.CheckCell
+
+CheckCell sub-component
+
+#### Table.CheckHead
+
+CheckHead sub-component
+
+#### Table.Footer
+
+Footer sub-component
+
+#### Table.ResizeHandle
+
+ResizeHandle sub-component
+
+
+---
+
+### Tabs
+
+Tab navigation component with segmented, underline, or pill style. Built on Base UI Tabs with animated active indicator.
+
+**Type:** component
+
+**Import:** `import { Tabs } from "@signalflare-ai/ui";`
+
+**Category:** Navigation
+
+**Props:**
+
+- `tabs`: TabsItem[]
+  Array of tab items to render.
+- `value`: string
+  Controlled value. When set, component becomes controlled.
+- `selectedValue`: string
+  Default selected value for uncontrolled mode. Ignored when `value` is set.
+- `activateOnFocus`: boolean
+  When `true`, tabs are activated immediately upon receiving focus via arrow keys. When `false` (default), tabs receive focus but require Enter/Space to activate.
+- `className`: string
+  Additional CSS classes for the root element.
+- `listClassName`: string
+  Additional CSS classes for the tab list element.
+- `indicatorClassName`: string
+  Additional CSS classes for the indicator element.
+- `variant`: enum [default: segmented]
+  Tab style.
+- `"segmented"` — Pill-shaped indicator on a filled track
+- `"underline"` — Underline indicator below tab text
+- `"pill"` — Fully rounded tabs, only selected has background
+- `onValueChange`: (value: string) => void
+  Callback when active tab changes
+
+**Colors (sf tokens used):**
+
+`bg-sf-brand`, `bg-sf-overlay`, `bg-sf-tint`, `border-sf-line`, `border-sf-tint`, `ring-sf-fill-hover`, `ring-sf-ring`, `text-sf-default`, `text-sf-strong`, `text-sf-subtle`
+
+**Styling:**
+
+
+---
+
+### Text
+
+Text component
+
+**Type:** component
+
+**Import:** `import { Text } from "@signalflare-ai/ui";`
+
+**Category:** Display
+
+**Props:**
+
+- `variant`: enum [default: body]
+  - `"heading1"`: Large heading for page titles
+  - `"heading2"`: Medium heading for section titles
+  - `"heading3"`: Small heading for subsections
+  - `"body"`: Default body text
+  - `"secondary"`: Muted text for secondary information
+  - `"success"`: Success state text
+  - `"error"`: Error state text
+  - `"mono"`: Monospace text for code
+  - `"mono-secondary"`: Muted monospace text
+- `size`: enum [default: base]
+  - `"xs"`: Extra small text
+  - `"sm"`: Small text
+  - `"base"`: Default text size
+  - `"lg"`: Large text
+- `bold`: boolean
+  Whether to use bold font weight (only applies to body variants).
+- `as`: React.ElementType
+  The HTML element type to render as (e.g. `"span"`, `"p"`, `"h1"`). Auto-selected based on variant if omitted.
+- `children`: ReactNode
+  Text content.
+
+**Colors (sf tokens used):**
+
+`text-sf-danger`, `text-sf-default`, `text-sf-link`, `text-sf-subtle`
+
+**Styling:**
+
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { ThemeToggle } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+- `mode`: enum [default: system]
+  - `"light"`: Light mode
+  - `"dark"`: Dark mode
+  - `"system"`: Follow system preference
+- `cycle`: SFThemeMode[]
+  Cycle order for clicking. Defaults to `["light", "dark", "system"]`. Remove `"system"` to limit to a simple light/dark toggle.
+- `tooltip`: boolean
+  Show a tooltip labelling the current action. Defaults to true.
+
+**Colors (sf tokens used):**
+
+`text-sf-default`, `text-sf-subtle`
+
+---
+
+### 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`.
+
+**Type:** component
+
+**Import:** `import { Toasty } from "@signalflare-ai/ui";`
+
+**Category:** Feedback
+
+**Props:**
+
+- `variant`: enum [default: default]
+  - `"default"`: Default toast style
+  - `"error"`: Error toast for critical issues
+  - `"warning"`: Warning toast for cautionary messages
+- `className`: string
+  Additional CSS classes
+- `children`: ReactNode
+  Child elements
+
+**Colors (sf tokens used):**
+
+`bg-sf-contrast`, `bg-sf-control`, `bg-sf-fill-hover`, `border-sf-fill`, `text-sf-default`, `text-sf-strong`, `text-sf-subtle`
+
+**Styling:**
+
+
+---
+
+### Tooltip
+
+Accessible popup that shows additional information on hover/focus. Wrap your app or section with `<TooltipProvider>` to enable delay grouping.
+
+**Type:** component
+
+**Import:** `import { Tooltip } from "@signalflare-ai/ui";`
+
+**Category:** Overlay
+
+**Props:**
+
+- `side`: enum [default: top]
+  - `"top"`: Tooltip appears above the trigger
+  - `"bottom"`: Tooltip appears below the trigger
+  - `"left"`: Tooltip appears to the left of the trigger
+  - `"right"`: Tooltip appears to the right of the trigger
+- `className`: string
+  Additional CSS classes
+- `children`: ReactNode
+  Child elements
+- `content`: ReactNode (required)
+  Content to display in the tooltip
+
+**Colors (sf tokens used):**
+
+`bg-sf-elevated`, `fill-sf-elevated`, `fill-sf-tip-shadow`, `fill-sf-tip-stroke`, `outline-sf-fill`, `text-sf-default`
+
+---
+
+### InputArea
+
+Multi-line textarea input with Input variants and InputArea-specific dimensions
+
+**Type:** component
+
+**Import:** `import { InputArea } from "@signalflare-ai/ui (synthetic - uses Input component)";`
+
+**Category:** Input
+
+**Props:**
+
+
+**Styling:**
+
+- **Size Variants:**
+  - `xs`:
+  - `sm`:
+  - `base`:
+  - `lg`:
+
+## Quick Reference
+
+**Components by Category:**
+- **Other:** AiActions, AiAgentCard, AiApproval, AiCodeBlock, AiConversation, AiInfoBanner, AiLoader, AiMessage, AiMissionHeader, AiQuestion, AiReasoning, AiResponse, AiShimmer, AiStatusBadge, AiStreamingText, AiSubagent, AiSuggestions, AiTaskList, AiTimeline, AiToolCall, AiUsageBar, DataGrid, DatePicker, Filters, Label, Link, PromptInput, SensitiveInput, Sidebar, SignalFlareAILogo, Table, ThemeToggle, AgentHarness, Commander, DeleteResource, Map
+- **Display:** Badge, Breadcrumbs, Code, Collapsible, Empty, LayerCard, Meter, Text
+- **Feedback:** Banner, Loader, Toasty
+- **Action:** Button, ClipboardText
+- **Input:** Checkbox, Combobox, DateRangePicker, Field, Input, Radio, Select, Switch
+- **Navigation:** CommandPalette, MenuBar, Pagination, Tabs
+- **Overlay:** Dialog, DropdownMenu, Popover, Tooltip
+- **Layout:** Grid, Surface, PageHeader, ResourceListPage