AI / Guide
Designing AI Interfaces
Patterns & behaviourA useful AI interface makes the task, context, progress, and next action clear. Design the whole interaction around the answer.
01 / Interaction
Choose a surface that fits the task
Start with what someone is trying to accomplish. A rewrite, a question about a document, and a task that runs across several tools need different amounts of interface.
Inline assistance
For a bounded task such as rewriting a paragraph, keep the action and suggestion beside the original. Let the person edit, accept, or dismiss it without leaving their work.
Document editorFocused conversation
For questions and follow-ups, use a conversation panel with the current context visible. A compact thread can sit alongside a record, document, or support case.
Agent conversationAgent workspace
When people manage several conversations and inspect tool output, give history, the active thread, and results their own space. Collapse secondary panes on smaller screens.
Agent workspace demo02 / Before sending
Make the input and its context visible
A composer should show what will be sent: the draft, attached files, selected records, and any relevant scope. Give people a way to remove context before submitting. If a file is still uploading or could not be read, show that state beside the file.
Use a specific suggestion such as “Summarise the selected meeting notes” to explain the available task. Keep suggestions editable, preserve an unsent draft when switching views, and label the send action. Make the Enter and newline behaviour clear.
DomTextareaComposer provides an autosizing field with attachment and action slots. The application supplies the attachment records, upload progress, and context selection.
03 / Feedback & recovery
Design every stage of a response
Use these as product states when designing the flow. They are example labels, rather than a required API enum. Each state should explain what is happening and what the person can do next.
- Ready
What would you like to change?
Show the selected context and a useful starting prompt. Keep the draft editable.
- Waiting
Request sent. Waiting for a response.
Acknowledge submission immediately. Keep the submitted prompt visible and offer cancellation where supported.
- Working
Searching the selected documents…
Name the work reported by the application. Use measured progress only; an indeterminate activity indicator is enough when the total is unknown.
- Streaming
Writing the draft…
Update the same response as content arrives. Keep Stop available, preserve partial output, and allow people to read earlier messages.
- Needs review
Three edits are ready to review.
Show the proposed change and its destination. Offer specific actions such as Apply edits, Edit draft, or Discard.
- Complete
Draft saved.
Only claim the result that the application has confirmed. A generated answer, an approved change, and a saved record are separate events.
- Stopped or failed
The connection ended. Your draft is still here.
Retain useful work, explain what happened, and provide the next step. Distinguish a deliberate stop from a failure; check the saved result before retrying an action.
Keep following new content while the reader is at the end of the conversation. Once they scroll back, preserve their position and offer a jump to the latest response. Connect the chat component’s stop event to cancellation in your application; changing a button alone does not stop a remote task.
04 / Results & review
Turn tool output into something people can use
Show the result in its own shape
Render search results as links, a booking as a summary, and a proposed edit as a diff. Keep the tool’s label, progress, and outcome together. The conversation’s renderer map lets the application supply Vue components for known tools.
Keep sources close to the claims they support, with names and links people can inspect. Identify missing evidence or a failed lookup directly. A source link should come from the retrieved record; avoid inventing references or displaying an uncalibrated confidence percentage.
Explore tool renderers ↗Make changes reviewable
For an action that needs approval, show the exact proposed change, destination, and consequence before asking. Use a concrete button label such as “Apply three edits”. Keep approval, execution, and successful persistence as separate states.
Pair a text diff with application-owned accept and discard actions. If the action fails after approval, keep the proposal available and show the actual result. Offer undo when your application can reliably reverse the change.
Describe observable work, such as “Read two documents”, using events your application actually received. Keep user-facing progress summaries concise.
05 / Voice & camera
Separate device activity from the AI session
A moving waveform shows input activity. It does not establish that speech was recognised, sent, or understood. Show microphone capture and the remote session separately: connecting, listening, processing, speaking, or disconnected, as supported by your integration.
DomAudioControls combines start, stop, mute, input selection, and a live waveform. DomAudioInput and DomCameraInput provide separate setup surfaces. Each capture component owns its stream; pass that stream to DomAudioVisualizer for another display.
Start capture from an explicit user action, explain whether input will be transmitted, and keep stopping easy. Provide a text path if permission is declined or a device is unavailable. Camera and microphone access require a secure context and browser permission; embedded experiences also need the appropriate permissions policy. Read the browser capture requirements.
Your application implements recording, transcription, playback, and interruption of a remote response. A local microphone mute and a request to stop the assistant are different controls with different effects.
06 / Access & mobile
Keep the interface usable as it changes
Announce meaningful changes
Expose waiting, completion, and error messages to assistive technology without moving focus. Avoid announcing every streamed token. Use text alongside colour or animation, preserve keyboard focus as results arrive, and test the announcement frequency with a screen reader.
W3C guidance on status messages ↗Give the conversation room
On a phone, give the thread the main screen and move history or context into a drawer. Keep the composer reachable when the keyboard opens, give long results their own scroll behaviour, and keep Stop and review actions within reach.
Use the mobile shell guidance for scroll ownership, safe areas, and keyboard layout. Check the full-screen view on a target device as well as the embedded docs preview.
07 / Integration
Connect the interface to application state
Components
Render controlled records, messages, inputs, tool cards, and local capture state. Emit submit, stop, selection, and tool-action events.
Application state
Track the active conversation and draft. Merge stream events by stable message and part IDs, preserve partial results, and keep request state separate from saved state.
Server and tools
Own model calls, credentials, authorisation, tool execution, persistence, and cancellation. Validate every requested action and return the outcome the interface should display.
Treat generated content and tool arguments as untrusted input. Map known result types to your own renderers, validate actions on the server, and keep credentials there. The agent workspace demo shows message parts and a store with a mock API you can replace.
Browse all AI components →