hatch3r-ai-ux-patterns

AI/Agentic UX Patterns (2026)

Pillars: P2 (Scientific & Practical Quality), CQ2 (UX Quality)

Scope

This rule applies when the end-user project ships LLM-driven UI — chat, assistant, copilot, agent dashboards, generative UI surfaces. It does NOT govern the LLM backend itself (model selection, prompt engineering, retrieval pipeline). For non-AI UX rules (loading, empty, error, partial states; form patterns; microcopy), cross-reference rules/hatch3r-ux-states-and-flows.md. When both rules apply to the same surface, the non-AI rule sets the baseline and this rule layers AI-specific behavior on top.

Backend companion: rules/hatch3r-ai-evals.md defines eval harness, prompt versioning, cost telemetry, prompt caching, model fallback, and hallucination-as-SLI. Apply both rules for any LLM-driven feature.

Detection: this rule activates when the project imports an AI SDK (ai, @ai-sdk/*, openai, @anthropic-ai/sdk, @google/generative-ai), or contains files under ai/, chat/, assistant/, agents/, llm/, copilot/. Adding any of these to a project that previously had no AI surface triggers the full ruleset on the next agent run.

Streaming-First Defaults

• Every LLM-driven surface uses framework-agnostic streaming hooks: useChat, useCompletion, or useObject from Vercel AI SDK UI (or equivalent for non-React stacks). Hand-rolled SSE or fetch against the model endpoint is a regression in 2026.
• Render progressive tokens from the moment the request starts. Pair with a skeleton state during the pre-token window (request-sent, first-token-pending). A blank surface during model latency is a regression.
• Render markdown incrementally without re-parsing the whole buffer on every chunk (Vercel AI Elements MessageResponse pattern). Use a streaming-safe markdown renderer that tracks last-rendered offset and appends from there.
• Emit chunk-level error boundaries. If a stream fails mid-flight, retain prior tokens, render an inline retry control adjacent to the truncated response, and do not blank the surface or reset the message body.
• Indicate completion explicitly via a final-token marker or onFinish callback transition. Stale "thinking" indicators after stream-end erode trust and waste user attention.
• Non-streaming responses on LLM-driven surfaces are a regression. The narrow exception is structured-output endpoints that must return a single validated JSON payload (useObject already streams partial objects — prefer that).
• Typing indicator policy: show only while no token has arrived; switch to streamed content the moment the first delta lands. Two-second indicator timeouts that linger past first-token are a regression.
• Backpressure: when the model emits faster than the renderer can paint, batch deltas to one paint per animation frame (requestAnimationFrame) rather than dropping tokens or queuing into an unbounded buffer.
• Message model — AI SDK 6+ breaking change (verify before pinning a version): since AI SDK 6 (GA 2025-12-22) and retained in AI SDK 7 (current stable major, GA 2026-06-25), every useChat message is an ordered parts array, not a flat content string, and handleSubmit / handleInputChange are replaced by sendMessage({ text }). Part types: text, reasoning, file, source-url/source-document, and — for tools — tool-${toolName} (static tools) or dynamic-tool (tools unknown at compile time, e.g. MCP); a tool invocation is one part whose state field transitions input-streaming → input-available → output-available/output-error, not separate tool-call/tool-result entries — switching on those strings matches nothing. Render by iterating message.parts; code that reads message.content silently drops the cards the §Tool-Call UI Cards section mandates — text still renders but the tool call never appears. Re-check ai-sdk.dev/docs/ai-sdk-ui for the current major before adopting a pinned version (part typing verified against ai-sdk.dev/docs/ai-sdk-ui/chatbot-tool-usage, accessed 2026-07-12).