> ## Documentation Index
> Fetch the complete documentation index at: https://smithers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Docs by Type

> One page that maps every kind of Smithers UI documentation, from the shadcn-based component library and agent-native components to run-aware widgets, hooks, adapters, and authoring guides.

Agents build every Smithers UI surface by composing the shared component
library, never by hand-rolling markup and CSS. The library has two layers:
`@smithers-orchestrator/ui` ports [shadcn/ui](https://ui.shadcn.com) component
anatomy (`data-slot` attributes, CVA variants, `asChild` via Radix Slot) and
adds agent-native components built specifically for Smithers (reasoning, tool
calls, plans, queues, approvals, checkpoints, context usage), while
`@smithers-orchestrator/gateway-ui` supplies run-aware widgets composed over
the `smithers-orchestrator/gateway-react` hooks. A custom workflow UI at
`.smithers/ui/<workflow>.tsx` imports from those subpaths and nothing else.

## Doc types at a glance

| Doc type                  | What it covers                                                                                                                                                                                                                                                                                                                     | Start at                                                           |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Base component library    | Buttons, cards, dialogs, tabs, tables, status pills, tokens, theming rules                                                                                                                                                                                                                                                         | [UI Component Library](/reference/ui)                              |
| Chat components           | [MessageScroller](/reference/ui/message-scroller), [Bubble](/reference/ui/bubble), [Attachment](/reference/ui/attachment), [Marker](/reference/ui/marker), [Shimmer](/reference/ui/shimmer)                                                                                                                                        | [UI Component Library](/reference/ui)                              |
| Agentic components        | The agent-native catalog plus per-component pages: [Reasoning](/reference/ui/reasoning), [ToolCall](/reference/ui/tool-call), [ChainOfThought](/reference/ui/chain-of-thought), [Plan](/reference/ui/plan), [TaskItem](/reference/ui/task-item), [Sources](/reference/ui/sources), [InlineCitation](/reference/ui/inline-citation) | [Agentic UI Components](/reference/ui/agentic-ui)                  |
| Heavy-dependency adapters | Chart (recharts), Terminal (xterm), PierreDiffView, MarkdownEditor; each ships behind an `adapters/*` subpath so the base barrel stays lightweight                                                                                                                                                                                 | [Chart](/reference/ui/chart)                                       |
| Run-aware widgets         | RunTree, RunEventLog, ApprovalPanel, NodeOutputView, WorkflowGraph, SimpleWorkflowDashboard                                                                                                                                                                                                                                        | [Gateway UI](/reference/gateway-ui)                                |
| Live data hooks           | useGatewayRun, useGatewayRunEvents, useGatewayNodeOutput, useGatewayApprovals, useGatewayActions                                                                                                                                                                                                                                   | [Gateway React](/reference/gateway-react)                          |
| Workflow UI authoring     | The end-to-end guide for building and serving `.smithers/ui/<workflow>.tsx`                                                                                                                                                                                                                                                        | [Custom Workflow UIs](/guides/custom-workflow-ui)                  |
| Theming and design        | Theme tokens, light and dark correctness, reduced motion, the design contract                                                                                                                                                                                                                                                      | [Workflow UI Design](/guides/workflow-ui-design)                   |
| Migration                 | Moving a hand-rolled workflow UI onto the shared libraries                                                                                                                                                                                                                                                                         | [Workflow-Owned UI Migration](/guides/workflow-owned-ui-migration) |
| Terminal surfaces         | The full-screen TUI monitor                                                                                                                                                                                                                                                                                                        | [TUI](/guides/tui)                                                 |

## How the layers stack

1. `react` renders.
2. `smithers-orchestrator/ui` provides the components: shadcn anatomy, the
   agent-native families, and tokens that make light and dark correct by
   construction. Heavy renderers live behind `smithers-orchestrator/ui/adapters/*`.
3. `smithers-orchestrator/gateway-ui` provides run-aware widgets that already
   know how to render runs, events, approvals, and node output.
4. `smithers-orchestrator/gateway-react` provides the live hooks those widgets
   (and your custom panels) read runs through.
5. Your workflow UI composes the three subpaths and calls
   `createGatewayReactRoot(<App />)`. The Gateway bundles and serves it at
   `/workflows/<key>`.

## Where these docs live in the agent bundle

The core agent bundle (`llms-core.txt`) carries the base library page, the
gateway-ui widget catalog, the chat component pages, and the custom workflow UI
guide. The UI fragment of [/llms-full.txt](/llms-full.txt) adds this page, the
per-component agentic pages, the adapter pages, the gateway-react hook
reference, and the design guide.