AI Native UI Patterns

AI-Native UI Patterns

A conventional interface renders state that already exists. An AI-native interface renders work in progress, the evidence behind it, and how sure the model is — then asks permission before it changes anything. Those four things are the whole job. A surface that has them feels like a colleague; a surface that skips them feels like a slot machine.

This skill owns behaviour and structure. It does not own taste — pair it with a visual-direction skill (high-end-visual-design, minimalist-ui, industrial-brutalist-ui) and with the host's design system.

1. The seven laws

1. Never show an unqualified spinner. Latency is the dominant interaction. Every wait states what phase it is in and how long it has run ("Reading exports · 2.4s"). A bare spinner is a bug report waiting to happen.
2. Show the work, collapsed. Reasoning steps, tool calls, retrieved chunks and search queries are always available and never in the way. Collapsed by default, one click to open, and the collapsed header carries a summary ("4 tool calls, 2 messages") so the user can decide without opening.
3. A claim without provenance is a defect. Any generated statement that asserts a fact carries an inline citation to the chunk, row, file, or URL it came from, and that citation is clickable through to the source.
4. Uncertainty is a visual, not a disclaimer. Confidence is rendered — a meter, a band ("High confidence" / "Needs review" / "No signal") — next to the recommendation it qualifies. Never a paragraph of hedging prose.
5. Nothing with a side effect happens without a gate. Writes, sends, purchases, deletes, and external calls go through an approval card that names the exact action and its parameters. Reads may proceed freely.
6. Propose, don't apply. Agent edits arrive as a reviewable diff — per-row, per-line, per-field, each independently acceptable and rejectable. The accepted set is applied in one explicit commit.
7. Output is a starting point. Every answer ends in affordances: copy, retry, edit, rate, follow-up questions, and selection-level actions on any passage. Treat generated text as material, never as a final render.

2. Token layer

tokens.css is copy-paste ready for both themes. The shape matters more than the values:

• Four surface levels — --page (backdrop), --canvas (rail/column), --surface (card), --inset (well inside a card). Agent UIs nest deeply: a trace inside a message inside a thread. Without a ladder, everything flattens into noise.
• Three ink levels — --ink for content, --ink-2 for metadata and labels, --ink-3 for placeholders and not-yet-arrived text. Streaming text starts at --ink-3 and resolves to --ink.
• Hairlines carry structure, shadows only lift overlays. Every elevation token starts with a 0 0 0 1px ring. Dense agent surfaces have many adjacent containers; drop shadows on all of them turns the page to mud.
• Four semantic hues, each with a tint. --accent (agent/active), --green (completed/verified), --orange (running/needs review), --red (failed/destructive). The -tint variant is the chip fill; the solid is the text and icon. On dark, tints are alpha so they compose over any level.
• Mono means machine-authored. Code, tool arguments, IDs, elapsed time, and token counts use --font-mono. Prose is sans. The reader should be able to tell what the model wrote from three metres away.

3. Motion contract

Exact values live in tokens.css. The rules:

• Animate opacity and transform only. Never height directly; expand with grid-template-rows: 0fr → 1fr, which animates on the compositor and needs no measured height.
• Do not animate arriving tokens individually. A per-token transition at 60 tokens/s produces a strobe. Animate the block on first paint, then let text land.
• Reduced motion keeps the information. prefers-reduced-motion removes movement, not signal: the loader keeps its phase label and elapsed counter, the trace still expands, streaming still streams.

4. Primitive catalogue

Nineteen primitives cover most agent surfaces. Each one is defined by the states it must handle — that column is where implementations actually fail.

Agent activity

Answer surfaces

Human in the loop

Input and retrieval

Data and navigation

5. Streaming mechanics

The single hardest part to get right, and where most implementations break:

• Reserve the block before the first token. The answer container gets its final width and a minimum height up front. Text growing into a correctly-sized box costs no layout shift; text growing into an auto-collapsing box reflows the page on every frame.
• Announce once, not per token. Wrap the answer in aria-live="polite" aria-atomic="false" and update a text node. Do not append announced elements per token — screen readers will read the answer dozens of times.
• Autoscroll is conditional. Follow the stream only while the user is at the bottom. The moment they scroll up, stop, and show a "jump to latest" affordance. Yanking the viewport away from someone who is reading is the worst bug in this category.
• Never steal focus mid-stream. Focus moves on user action only. The composer stays focused and usable while the answer streams.
• A stop control exists and works. Streaming is cancellable, the partial answer is kept, and it is labelled as partial.
• Errors mid-stream keep what arrived. Show the partial text, an error row, and retry. Never blank out an answer the user was already reading.

6. Accessibility contract

• Approval cards and recommendation actions are reachable and operable by keyboard, with a visible focus ring. An approval reachable only by mouse is a broken gate.
• Status is never colour alone: every state chip pairs its hue with a label or icon (running/failed/completed are the ones most often failed).
• Confidence meters carry a text equivalent — aria-valuenow plus the band name. A bar with no number is decoration.
• Traces and collapsibles use real <button aria-expanded>, not a clickable div.
• Contrast: --ink-2 on --surface must clear 4.5:1, --ink-3 is for non-essential text only. Verify both themes.

7. Banned

• A spinner with no phase label and no elapsed time.
• A generated fact with no source, or a "sources" affordance that does not link to anything.
• Prose hedging ("I think, but I could be wrong…") standing in for a rendered confidence signal.
• Any write, send, or delete performed without an approval gate.
• Agent edits applied directly to the user's data with an undo as the only escape.
• Fake determinate progress bars for work of unknown length. Use elapsed time.
• A chat transcript as the only interface to structured work — if the output is a table, a diff, or a task list, render it as one.
• Typing-dot animations that convey nothing while a real phase label is available.
• Layout that reflows on every token.
• Emoji as status icons.

8. Pre-flight

Before calling an AI-native surface done:

• Every wait shows a phase and elapsed time
• Every trace is collapsed by default with a meaningful summary
• Every asserted fact links to its source
• Confidence is rendered visually and available as text
• Every side effect passes through an approval gate that names its parameters
• Every agent edit is a reviewable, per-item acceptable diff
• Streaming: reserved block, single live region, conditional autoscroll, working stop control, partial text kept on error
• All nineteen relevant states have a designed empty/failed variant
• Reduced-motion and both themes verified
• Keyboard path through approval, retry, and stop

Reference

Pattern set and token shape derived from the public component gallery Beautiful UI — crafted primitives for AI-native interfaces (https://beautiful-ui-five.vercel.app/, Turbo product design studio), reviewed 2026-08-11. Guidance and token file here are original; no upstream code is vendored. Consult the gallery for live, interactive references.