# AI Patterns

> A pattern library for AI product UI — tool approval, confidence indicators, agent handoff, error recovery, streaming answers and more. Each pattern is a UX spec (when to use, anatomy, behavior, content, accessibility) plus a copy-paste React implementation (Next.js, TypeScript, Tailwind v4, Motion, Radix).

Each pattern is a portable UX contract. Read its spec before implementing it — the "When not to use" and "Accessibility" sections are the contract; the Tailwind/Radix/Motion code is one default expression of it and can be re-expressed in any design system. Every pattern link below is the Markdown version: spec followed by the full `component.tsx`.

## For agents

- [llms.txt](https://ai-patterns.app/llms.txt): this index.
- [llms-full.txt](https://ai-patterns.app/llms-full.txt): every pattern's full spec in one file (code omitted).
- Markdown: append `.md` to any page URL (e.g. `/patterns.md`, `/patterns/buttons/shiny-button.md`).
- JSON API: [`GET /api/patterns`](https://ai-patterns.app/api/patterns) lists every pattern; `GET /api/patterns/<category>/<slug>` returns its spec, source code and npm dependencies.
- MCP server (Streamable HTTP, no auth): `https://ai-patterns.app/mcp` with tools `list_patterns` (filter by category or job), `search_patterns` and `get_pattern`.
- Claude Code skill — recommends and scaffolds patterns into a project:

```
/plugin marketplace add carlosmarch/ai-patterns
/plugin install ai-patterns@ai-patterns
```

## Patterns by job

Every pattern also has one job — what it does for the user, across categories. Use it to shortlist by need.

- **Start** (`start`, "I don't know what to ask"): Help people take the first step: onboarding, starter prompts and suggested next steps. — `create-agent`, `shiny-button`, `prompt-template`, `clarifying-questions`, `follow-up-list`, `invite-members`, `setup-checklist`, `prompt-onboarding`, `agent-setup-pill`
- **Ask** (`ask`, "Do this for me"): Get intent into the AI: composers, voice, attachments and asking in context. — `instruction-tools`, `prompt-bar`, `prompt-bar-pro`, `quick-chat-dock`, `message-queue`, `attachment-chip`, `selection-actions`, `voice-waveform`, `listening-state`, `live-transcript`, `command-palette`, `describe-filters`, `ai-fill-drawer`, `natural-language-query`
- **Steer** (`steer`, "Do it this way"): Shape how the AI works: models, sources, triggers, procedures and refinements. — `agent-triggers`, `procedure-builder`, `model-picker`, `prompt-enhancer`, `trigger-condition`, `conversation-branches`, `connector-panel`, `refinement-controls`
- **Oversee** (`oversee`, "What is it doing, and can I step in?"): Show progress and reasoning while the AI works, and let people approve, pause or stop it. — `human-in-the-loop`, `background-tasks`, `task-list`, `agent-run-card`, `wait-time-handoff`, `plan-review`, `multi-agent-trace`, `thinking-loader`, `drawing-icon`, `expandable-trace`, `stream-of-thought`, `streaming-text`, `tool-approval`, `tool-call-chip`, `stop-generation-button`, `terminal-stream`, `cost-estimate`, `context-usage`, `voice-orb`, `collaborative-presence`, `analysis-list`
- **Trust** (`trust`, "Can I believe it, and what does it keep?"): Check results against sources, diffs and confidence, and make AI content and data handling visible. — `incognito-toggle`, `diff-summary`, `diff-tabs`, `code-preview`, `chat-bubble`, `memory-panel`, `image-peek`, `inline-citation`, `sources-stack`, `source-trust-card`, `response-compare`, `confidence-indicator`, `ai-disclosure-badge`, `ai-review-panel`
- **Recover** (`recover`, "Something went wrong"): Explain failures and limits, keep partial work, and offer a way forward. — `rate-limit`, `partial-response`, `generation-error`, `console-error-card`, `connectivity-error`

## agents

- [Create Agent](https://ai-patterns.app/patterns/agents/create-agent.md): A two-step wizard card for naming an agent, picking its icon, and selecting which event sources activate it.
- [Agent Triggers](https://ai-patterns.app/patterns/agents/agent-triggers.md): A configuration panel for listing and toggling the external events that activate an agent, with a manual run control.
- [Human in the Loop Question](https://ai-patterns.app/patterns/agents/human-in-the-loop.md): A compact dialog that pauses an agent mid-task to collect a structured choice — radio options, a free-text fallback, skip/continue controls, and multi-step pagination.
- [Background Tasks Drawer](https://ai-patterns.app/patterns/agents/background-tasks.md): A side drawer that tracks an agent's background work live — running tasks with elapsed time, stats, and stop controls, plus an expandable history of finished commands and output.
- [Instruction Tool Insert](https://ai-patterns.app/patterns/agents/instruction-tools.md): A numbered instruction editor where typing / opens a two-step inline picker — choose a tool, then its connector or target — inserting an atomic, editable chip into the prose.
- [Procedure Builder](https://ai-patterns.app/patterns/agents/procedure-builder.md): A doc-style editor for an agent's step-by-step procedure — a / step picker, IF / ELSE branches with plain-language or code conditions, section jumps, and escalate / switch actions.
- [Task List](https://ai-patterns.app/patterns/agents/task-list.md): A live, agent-authored plan — an ordered list of steps marked pending, in progress, or completed as the agent works through them.
- [Agent Run Card](https://ai-patterns.app/patterns/agents/agent-run-card.md): A compact run card with the agent's current step and a timer, a segmented progress bar, and a list of finished steps that stacks up as it reads, edits, tests and pushes.
- [Wait Time Handoff](https://ai-patterns.app/patterns/agents/wait-time-handoff.md): A collapsible settings card for what an agent does when the customer goes quiet — a wait duration, a Team / Workflow handoff target, the handoff message, and a working-hours option.
- [Plan Review](https://ai-patterns.app/patterns/agents/plan-review.md): An editable plan shown before an agent runs — reword, reorder, remove or add steps, or ask for a new plan — that locks once approved.

## traces

- [Multi-Agent Trace](https://ai-patterns.app/patterns/traces/multi-agent-trace.md): A tree of parallel sub-agent tasks, each with its own status and step list.
- [Expandable Trace](https://ai-patterns.app/patterns/traces/expandable-trace.md): A collapsible "Thought for Xs" summary that expands into a step-by-step trace.
- [Stream of Thought](https://ai-patterns.app/patterns/traces/stream-of-thought.md): A live, timed header over reasoning that streams in as a step timeline, then folds into a "Thought for Ns" trace when the answer starts.

## buttons

- [Shiny Button](https://ai-patterns.app/patterns/buttons/shiny-button.md): A button with an animated light sweep across its surface.
- [Stop Generation Button](https://ai-patterns.app/patterns/buttons/stop-generation-button.md): A send button that morphs into a stop control mid-stream and back on completion.

## loaders

- [Thinking Loader](https://ai-patterns.app/patterns/loaders/thinking-loader.md): A loader with a shimmering label and a live elapsed-time counter.
- [Drawing Icon](https://ai-patterns.app/patterns/loaders/drawing-icon.md): A line icon that draws itself stroke by stroke while the step it stands for is running.
- [Tool Call Chip](https://ai-patterns.app/patterns/loaders/tool-call-chip.md): An inline pill naming an in-flight tool call that resolves into a result summary.
- [Analysis List](https://ai-patterns.app/patterns/loaders/analysis-list.md): A full-width indeterminate progress bar over a list whose items resolve from skeletons one by one.

## text

- [Streaming Text](https://ai-patterns.app/patterns/text/streaming-text.md): A streamed answer with inline sources, actions, and follow-ups.
- [Inline Citation](https://ai-patterns.app/patterns/text/inline-citation.md): A hoverable, clickable footnote-style source marker inline within text.
- [Sources Stack](https://ai-patterns.app/patterns/text/sources-stack.md): An overlapping stack of source favicons with a count, expanding into a linked source list.
- [Source Trust Card](https://ai-patterns.app/patterns/text/source-trust-card.md): A paginated single-source card with a trust badge and domain pills for jumping between sources.
- [Follow-Up List](https://ai-patterns.app/patterns/text/follow-up-list.md): A vertical list of suggested next questions shown after a response, each sendable with a tap.
- [Selection Actions](https://ai-patterns.app/patterns/text/selection-actions.md): A floating toolbar on text selection for describing edits, explaining, or improving a passage.
- [Refinement Controls](https://ai-patterns.app/patterns/text/refinement-controls.md): One-tap adjustments (Rephrase, Shorten, More formal, Bulletize…) and a free-form instruction field docked under an AI output, with every result kept as a steppable version.

## composer

- [Prompt Bar](https://ai-patterns.app/patterns/composer/prompt-bar.md): A composer with @ sources, / commands, a model picker, and dictation.
- [Prompt Bar Pro](https://ai-patterns.app/patterns/composer/prompt-bar-pro.md): A first-run composer with suggestion chips, @ sources, / commands, an environment picker, and an orchestrator picker.
- [Quick Chat Dock](https://ai-patterns.app/patterns/composer/quick-chat-dock.md): A hidden bottom-edge handle that wakes into an action dock on hover and summons a floating prompt bar.
- [Message Queue](https://ai-patterns.app/patterns/composer/message-queue.md): A composer that keeps working mid-turn: ⌘Enter queues follow-ups above the input to send now, edit, or auto-send when the agent finishes.
- [Model Picker](https://ai-patterns.app/patterns/composer/model-picker.md): A composer chip that opens a list of models, each with a one-line description, plan-locked options that lead to an upgrade, and an extended-thinking switch.
- [Incognito Toggle](https://ai-patterns.app/patterns/composer/incognito-toggle.md): A header control that starts a temporary chat, with a persistent banner stating exactly what won't be saved, remembered or used for training.
- [Prompt Enhancer](https://ai-patterns.app/patterns/composer/prompt-enhancer.md): An Enhance button that rewrites a short prompt into a specific one in place, highlighting what it added, with one-click undo.
- [Prompt Template](https://ai-patterns.app/patterns/composer/prompt-template.md): A prompt written as a sentence with inline blanks — free-text slots that grow as you type and choice slots — that runs once the blanks are filled.

## code

- [Diff Summary Card](https://ai-patterns.app/patterns/code/diff-summary.md): A collapsed summary of a batch of file edits, with undo and an overflow list.
- [Diff Tabs](https://ai-patterns.app/patterns/code/diff-tabs.md): Per-file chips that switch an inline diff viewer between a batch of changed files.
- [Code Preview Block](https://ai-patterns.app/patterns/code/code-preview.md): A code block that flips between the source and a sandboxed live rendering of it.
- [Terminal Stream](https://ai-patterns.app/patterns/code/terminal-stream.md): An auto-scrolling, collapsible panel streaming raw command output line by line.

## flowcharts

- [Flowchart](https://ai-patterns.app/patterns/flowcharts/trigger-condition.md): Workflow trigger and condition steps on a dotted canvas.

## messages

- [Chat Bubble with Actions](https://ai-patterns.app/patterns/messages/chat-bubble.md): A message bubble with feedback thumbs, edit-and-resubmit, retry/regenerate, and a version stepper.
- [Clarifying Questions](https://ai-patterns.app/patterns/messages/clarifying-questions.md): A short card of questions before an ambiguous task, each pre-filled with the assistant's suggested answer, that collapses into a summary once started.
- [Conversation Branches](https://ai-patterns.app/patterns/messages/conversation-branches.md): Editing a sent message creates a new branch instead of overwriting it, with a ‹ 2 / 3 › switcher that swaps the message and its reply together.

## permissions

- [Tool Approval](https://ai-patterns.app/patterns/permissions/tool-approval.md): A pending tool-call prompt with allow, always-allow, and deny actions.
- [Connector Panel](https://ai-patterns.app/patterns/permissions/connector-panel.md): A settings panel for connecting an app or MCP server — shows capabilities overview, groups tools by type, and lets users set per-tool permission levels.
- [Memory Panel](https://ai-patterns.app/patterns/permissions/memory-panel.md): A panel listing what the assistant remembers about the user — edit or forget each memory with undo, switch memory off, forget all — plus a memory-updated notice for the chat.

## uploads

- [Attachment Chip](https://ai-patterns.app/patterns/uploads/attachment-chip.md): A composer's file/image attachment tray with drag-drop, upload progress, and inline preview.

## media

- [Image Peek](https://ai-patterns.app/patterns/media/image-peek.md): A row of tiny image thumbnails that grows into an anchored preview card with a label, counter, and prev/next stepping.

## errors

- [Rate Limit](https://ai-patterns.app/patterns/errors/rate-limit.md): A quota-exceeded state with a live countdown to when the user can send again.
- [Partial Response](https://ai-patterns.app/patterns/errors/partial-response.md): A cut-short assistant reply with Continue and Retry actions.
- [Generation Error](https://ai-patterns.app/patterns/errors/generation-error.md): A console-style error card for a failed generation, with details and retry.
- [Console Error Card](https://ai-patterns.app/patterns/errors/console-error-card.md): A structured card surfacing a browser console error with a code frame, call stack, and navigation.
- [Connectivity Error](https://ai-patterns.app/patterns/errors/connectivity-error.md): A dismissible card surfacing a network connection failure with a description and retry/details actions.

## compare

- [Response Compare](https://ai-patterns.app/patterns/compare/response-compare.md): A side-by-side pair of response panels with independent regenerate and a single preferred pick.

## indicators

- [Confidence Indicator](https://ai-patterns.app/patterns/indicators/confidence-indicator.md): A badge or inline dot signaling how sure an AI answer or extraction is.
- [AI Disclosure Badge](https://ai-patterns.app/patterns/indicators/ai-disclosure-badge.md): An AI-generated label in chip, image-overlay and inline forms that opens a provenance card: model, time, and whether a person edited it.
- [Cost Estimate](https://ai-patterns.app/patterns/indicators/cost-estimate.md): A pre-run estimate of what a task will cost, with a live balance meter, a low-balance warning, a top-up when the balance can't cover it and a breakdown.
- [Context Usage](https://ai-patterns.app/patterns/indicators/context-usage.md): A context-window meter: tokens used against the limit, a segmented bar of what fills it, a legend to inspect each source and a Compact action to free space.

## voice

- [Voice Waveform](https://ai-patterns.app/patterns/voice/voice-waveform.md): A live amplitude waveform while the AI listens or speaks.
- [Voice Orb](https://ai-patterns.app/patterns/voice/voice-orb.md): A 3D particle sphere that breathes and spins with the voice conversation.
- [Listening State](https://ai-patterns.app/patterns/voice/listening-state.md): A pulsing mic indicator showing the AI is actively listening.
- [Live Transcript](https://ai-patterns.app/patterns/voice/live-transcript.md): A streaming, speaker-labeled transcription of a voice conversation.

## navigation

- [Command Palette](https://ai-patterns.app/patterns/navigation/command-palette.md): A searchable ⌘K overlay for jumping to sessions or running quick actions.
- [Setup Checklist](https://ai-patterns.app/patterns/navigation/setup-checklist.md): A stepped onboarding card with circular arc progress, dashed-circle pending states, and strikethrough for completed steps.

## collaboration

- [Collaborative Presence](https://ai-patterns.app/patterns/collaboration/collaborative-presence.md): An avatar stack showing who has access to a shared record and who is actively viewing it right now.

## access

- [Invite Members](https://ai-patterns.app/patterns/access/invite-members.md): A two-step modal for searching or emailing people to a record and assigning each a role, with a live current-members list.

## onboarding

- [Prompt-Driven Onboarding](https://ai-patterns.app/patterns/onboarding/prompt-onboarding.md): A setup screen that hands users a pre-filled prompt to paste into their AI coding agent, with a snippet fallback and a live listener that confirms the first event.
- [Agent Setup Pill](https://ai-patterns.app/patterns/onboarding/agent-setup-pill.md): A floating pill that copies a setup prompt for the user's AI coding agent in one click — outcome label, a row of supported agents, a tooltip that says what the click does, and a separate dismiss button.

## tables

- [Describe Filters](https://ai-patterns.app/patterns/tables/describe-filters.md): A Describe button in a table toolbar that turns a plain-language request into removable filter chips — column filters where a column exists, marked semantic matches where none does.
- [AI Fill Drawer](https://ai-patterns.app/patterns/tables/ai-fill-drawer.md): A record drawer of key/value fields where the model fills the empty values — each arrives as a sourced suggestion to accept, edit or reject.
- [Natural Language Query](https://ai-patterns.app/patterns/tables/natural-language-query.md): A SQL-first query bar that also takes plain language — the mode badge flips to Ask, and Enter translates the request into a visible, editable WHERE clause before running it.

## review

- [AI Review Panel](https://ai-patterns.app/patterns/review/ai-review-panel.md): A side panel for checking extracted values one by one — each field shows its value, the model's reasoning and verbatim evidence that highlights in the source, with accept, dismiss and apply-all-pending.

## Optional

- [Home](https://ai-patterns.app/index.md): what the catalogue is.
- [Claude Code skill](https://ai-patterns.app/skill.md): install and use the skill.
- [Source on GitHub](https://github.com/carlosmarch/ai-patterns): the registry lives in `src/registry/<category>/<slug>/` (MIT).