# AI UX Cheat Sheet

Course: [AI UX & Generative UI](https://www.devtutorials.ai/learn/ai-ux) · Section: Reference
Source: https://www.devtutorials.ai/learn/ai-ux/reference/cheat-sheet

> Every pattern from the course on one page: surfaces, streaming, trust cues, controls, risk and confirmation, designed states, the generative UI spectrum, A2UI, MCP App sandboxing, AG-UI events, feedback events, accessibility and the check list.

## How to Use This Page

This page is for coming back to. Every lesson's main idea is here, as a table, a rule or a short snippet. The last sections list every check from the lab, and a glossary.

The A2UI, AG-UI and MCP Apps specs moved quickly through 2026. The versions and names on this page were checked when the course was written. Check each spec's own docs again before you rely on a detail.

## The One-Line Version

**The interface is where AI earns or loses trust.** A good model behind a bad interface is a bad product.

| AI is different because… | So the interface must… | Lesson |
|---|---|---|
| It is slow | Show progress from the first second | 2 |
| It can be wrong and sound sure | Show sources, doubt and limits | 3 |
| It can change | Let users stop, edit, retry and undo | 4 |
| It can act | Ask before acting, by risk | 5 |
| It fails in new ways | Show a designed state for each failure | 6 |

## Surfaces (Lesson 1)

Ask in order; stop at the first yes.

| Question | Surface |
|---|---|
| Does the user need to explore, with many follow-ups? | Full chat |
| Is it one known action on the thing on screen? | Inline action |
| Is it help with the thing on screen, with a few turns? | Side panel |

## Section 1 Patterns

| Pattern | Rule | Lesson |
|---|---|---|
| Tool steps | Show each step when it starts; tick it when done | 2 |
| Streaming | Show tokens as they arrive; first words within 1 s of the first token | 2 |
| Stop | Abort the request (`AbortController`); nothing may run later | 2 |
| Citation chips | Link only to retrieved passages; otherwise "No source found" | 3 |
| "Not sure" banner | On low confidence; say what to check | 3 |
| Scope note | When the question is outside the app | 3 |
| Edit, Retry | Fix the question in place; Retry adds a version, never replaces | 4 |
| Undo | Back to a snapshot from before the AI change | 4 |
| Risk | Money, reach outside, or no way back = high | 5 |
| Preview card | Action and amount, order, recipient; the button names the action | 5 |
| Confirm | Ask for high risk only; low risk just happens, with undo | 5 |
| Undo window | A few seconds to reverse an action | 5 |
| Designed state | What happened, what is safe, what to do next | 6 |

### Designed States

| Failure | Title | Next step |
|---|---|---|
| Timeout | This is taking too long | Try again; the question is saved |
| Tool failure | We could not open the order | Try again; nothing was changed |
| Refusal | I can't share that | Ask about something it can help with |
| Rate limit | The assistant is busy | Retry after the wait, and say how long |
| "I don't know" | I couldn't find that order | Check the input, or search another way |

## The Generative UI Spectrum (Lessons 7 to 9)

| Pattern | Who decides the UI | Guard | Risk |
|---|---|---|---|
| Controlled | You build it; the agent picks | Typed registry, prop validation, safe fallback | Lowest |
| Declarative (A2UI) | The agent arranges your parts | Allow-list + schema, render as it streams, events with IDs | Medium |
| Open-ended (MCP Apps) | Someone else sends HTML | `sandbox="allow-scripts"`, CSP, message checks | Highest |

### Never

- Let the agent write HTML into your page.
- Pass unknown props through to a component.
- Put an HtmlBlock (raw HTML) in your A2UI catalogue.
- Combine `allow-scripts` and `allow-same-origin` for untrusted HTML.
- Let a message from a frame trigger a risky action without a preview.

## Protocol Layers (Lesson 10)

| Layer | Job |
|---|---|
| MCP | Agent ↔ tools |
| AG-UI | Agent ↔ your app (the event channel) |
| A2UI / MCP Apps | What to render |

| AG-UI event | Meaning | Client rule |
|---|---|---|
| `RUN_STARTED` / `RUN_FINISHED` | Start and end of a run | Show and clear the working state |
| `TEXT_MESSAGE_CONTENT` | More words | Append; announce per sentence |
| `TOOL_CALL_START` / `TOOL_CALL_END` | Tool activity | Show a step chip |
| `STATE_DELTA` | Shared state changed | Merge; keep fields the user is editing |
| Interrupt request | The agent needs a person | Show it; send the answer back |

## Feedback Events (Lesson 11)

```ts
interface FeedbackEvent {
  trace_id: string;
  output_version: number;
  signal: "thumbs-up" | "thumbs-down" | "correction" | "regenerate";
  comment?: string;
  correction?: string;
}
```

Explicit: thumbs, comments, edits. Implicit: regenerate, copy, close. Corrections are the best labels.

## Accessibility (Lesson 12)

| Need | Rule |
|---|---|
| Hear the answer | `aria-live="polite"`, updated per sentence |
| Reach the controls | Real buttons in tab order; Escape stops, Ctrl+Z undoes |
| Less motion | `@media (prefers-reduced-motion: reduce)` turns off decoration |
| Readable citations | `aria-label="Source 1, Refund policy §2"` |

## The Checks

Every check from the lab. The Build tab runs them on your settings, and the Code tab runs them on your React component's real page. The same rules are in your exported Playwright tests.

| Lesson | Checks |
|---|---|
| 2 | First words within 1 s of the first token · each tool step shown when it starts · never a blank screen or bare spinner for more than 1 s · Stop cancels the work with no later side effects |
| 3 | Every claim with a source has a chip · no chip links to an unretrieved passage · low confidence shows "not sure" · out-of-scope gets a scope note |
| 4 | Stop ends the answer · Edit gives a new answer · Retry keeps both versions · Undo restores the exact prior state |
| 5 | No high-risk effect before an explicit confirm · preview shows amount, order and recipient · low risk does not ask · undo window reverses · saying no stops it |
| 6 | Every failure shows a designed state with a next step |
| 7 | Tool calls render the matching component · invalid or unknown requests never render · rejected requests fall back safely |
| 8 | Invalid and unlisted components never render · valid payloads render in full · parts render as they arrive · events carry surface and component IDs · no payload code runs |
| 9 | No access to parent page, cookies or storage · no top navigation · no data sent out · only validated messages · the real app still works |
| 10 | Deltas keep user edits · interrupts abort cleanly · human-in-the-loop requests are shown and resumed |
| 11 | Signals captured as events · each with trace ID and output version · corrections keep the fixed text |
| 12 | Screen reader hears the answer · announcements per sentence · Stop and Undo by keyboard · reduced motion respected · readable citation chips |

## The Lab's Agent API

What your component gets in the Code tab. The capstone maps each line to a real stack.

| Call or event | Job | Lesson |
|---|---|---|
| `agent.on(cb)` | Get events: `token`, `tool-start`, `cite`, `done`, `error`, `propose`… | 2 to 12 |
| `agent.cancel()` | Stop the run | 2, 4, 10 |
| `agent.send(text)` · `agent.retry()` | A fixed question · another version | 4 |
| `agent.perform(action)` | Run a side effect; returns `undo()` | 5 |
| `agent.retrieved` | The passages the app really fetched | 3 |
| `agent.sendEvent({ surfaceId, componentId, action })` | Tell the agent what was pressed | 8 |
| `agent.state` · `agent.respond(yes)` | Shared state · the answer to a question | 10 |
| `agent.feedback(row)` | One feedback event | 11 |

## Glossary

| Term | Meaning |
|---|---|
| A2UI | An open JSON protocol for agents to describe UI as data |
| AG-UI | An open event protocol between an agent and an app's UI |
| Allow-list | The component types a renderer will draw |
| Citation chip | A label linking a claim to its source |
| Confirm fatigue | People approve without reading because the app asks too often |
| CSP | Content Security Policy: where a page may load from and send to |
| Designed state | A planned screen for a failure |
| Effects ledger | A record of every side effect, with its time |
| Generative UI | UI the agent picks, fills or describes at run time |
| Human-in-the-loop | The agent pauses for a person's decision |
| Live region | Page content a screen reader reads when it changes |
| MCP App | A small web app returned by an MCP tool, shown in a sandboxed iframe |
| Perceived wait | How long a wait feels |
| Registry | Names the agent can say, mapped to your components and prop types |
| Sandbox | iframe attribute that turns powers off by default |
| Side effect | A change outside the screen: money, email, delete |
| Snapshot | A saved copy of the user's work before an AI change |
| State delta | An event with only the fields of shared state that changed |
| Surface | Where the user meets the AI: chat, side panel or inline |
| Token | A small piece of text the model writes |
| Trace ID | The ID of the agent run that made an answer |

## Further Reading

- [Guidelines for Human-AI Interaction, by Microsoft Research](https://www.microsoft.com/en-us/research/project/guidelines-for-human-ai-interaction/)
- [People + AI Guidebook, by Google PAIR](https://pair.withgoogle.com/guidebook/)
- [A2UI v0.9, by Google Developers Blog](https://developers.googleblog.com/en/a2ui-v0-9-generative-ui/)
- [AG-UI core concepts](https://docs.ag-ui.com/concepts)
- [MCP Apps, by the Model Context Protocol team](https://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/)
- [The Developer's Guide to Generative UI in 2026, by CopilotKit](https://copilotkit.ai/blog/the-developer-s-guide-to-generative-ui-in-2026)