# Agent UI/UX Decision Guide Use this guide before coding. Select patterns from the user's task and risk profile, then design the required states and interaction contract. ## User must make or recover from a risky action ### Undo Use for: Users need to recover from common reversible actions after acting quickly, without being blocked by confirmation prompts before every low-risk command. Selection rules: - Choose undo when the product can restore the exact prior state without data loss or unrecoverable side effects. - Use undo for frequent archive, dismiss, move, reorder, delete-to-trash, bulk cleanup, and formatting changes where users benefit from acting first. - Use a persistent restore location instead of a short recovery notice when the consequence is important or users may need more time. - Use confirmation before the action when money, permissions, production data, emails, webhooks, or permanent deletion cannot be recalled. - Do not offer undo unless the system has already captured enough state to restore object identity, order, relationships, and visible counts. - Do not hide undo in a disappearing message if assistive technology users, keyboard users, or distracted users cannot reasonably reach it. - Use clear feedback when the undo window expires or when the action has been committed permanently. Must include: - Capture the prior object, value, position, relationship, and selection state before applying the action. - Display a recovery notice close to the action result or in a consistent status region. - Label the action with the object or operation, such as Undo delete or Restore report. - Keep the undo control keyboard reachable and visible long enough to use. - Provide a committed or expired state so users know when recovery is no longer available. - Restore focus, counts, ordering, and selection predictably after undo. - Avoid combining undo with pre-action confirmation for the same low-risk routine action. - Escalate to persistent history, trash, version rollback, or admin recovery when a short recovery window is insufficient. - Do not claim undo support until integration, storage, notifications, and external effects can actually be reversed. ### Confirmation dialog Use for: Users can accidentally start consequential actions that are costly, security-sensitive, externally visible, or impossible to recover after commitment. Selection rules: - Choose confirmation when the action has a clear reason not to proceed and the user may change their mind after seeing the consequence. - Prefer undo when the exact prior state can be restored reliably after a frequent low-risk action. - Prefer prevention when the action is dangerous mainly because it is placed too close to routine controls. - Use a typed confirmation or equivalent extra step for broad account, workspace, production-data, or permission deletion. - Do not confirm ordinary save, archive, dismiss, filter, navigation, or low-risk edits that users perform repeatedly. - Do not use confirmation copy to teach users about a feature; use inline education, preview, or feedback instead. - Use a regular modal task when the user needs to edit values, not merely decide whether the consequence should happen. Must include: - Name the affected object, count, or scope in the title or main instruction. - Explain the consequence once, including whether recovery, audit, billing, permissions, or external recipients are affected. - Use a safe cancel label that explains the safe outcome, such as Keep archive or Cancel deletion. - Use a destructive action label that contains the verb and object, such as Delete archive. - Avoid OK, Yes, No, and Cancel-only button pairs when they force users to reinterpret the question. - Keep the safe action reachable by default and avoid committing destruction from an accidental Enter key. - Require typed text or a deliberate extra step for severe or broad-scope deletion. - Return focus predictably after cancel, Escape, and completion. - Track whether frequent prompts are being dismissed unread and replace them with undo or prevention when possible. ### Toast-only critical error Use for: A blocking or high-consequence failure is announced only in a transient toast, so users can miss what failed and lose the path to recover. Selection rules: - Flag this anti-pattern when a failure blocks progress, affects money or data, changes account or security state, or requires a repair action after the message appears. - Replace the toast-only treatment with a persistent inline, section-level, modal, or page-level error surface that names the failed task and keeps recovery controls visible. - Allow a toast for non-blocking confirmation, background status, or a supplemental announcement only when the same critical recovery remains reachable elsewhere. - For payment or save failures, keep the invoice, draft, form, or affected record visible and show a next action such as Retry, Update card, Edit details, Restore, or Contact support. - Do not auto-dismiss the only explanation for a failure that users may need to reference, report, copy, or act on later. Must include: - Classify errors by consequence before choosing the feedback surface: low-risk status can be transient, but blocking, financial, destructive, permission, and data-loss failures need persistence. - Render the persistent error near the affected button, form, record, or page section and include the exact failed action in the heading. - Keep retry, correction, undo, support, or alternate-path actions visible and keyboard reachable after any toast closes. - Use a toast only as a duplicate announcement for urgent awareness, and link it to the persistent place where the user can recover. - Preserve entered data, selected items, payment context, and reference IDs so users can retry or ask for help without reconstructing the task. - Test the flow after the toast expires, with screen reader timing, reduced-motion settings, zoom, keyboard navigation, and delayed attention. ## User must narrow or recover search results ### Faceted search Use for: Users need to narrow a large result set using multiple meaningful attributes. Selection rules: - Choose faceted search when users need to progressively narrow a large set by multiple attributes. - Prefer basic search when users usually know the exact item or query. - Prefer category browse when users are exploring broad groups rather than combining constraints. Must include: - Show applied filters near the results. - Provide clear-one and clear-all actions. - Keep the result count visible after filtering. - Prevent combinations from becoming dead ends without recovery. ### No-results recovery Use for: A search or filter returns nothing, leaving users without a path forward. Selection rules: - Choose no-results recovery whenever search or filters can produce an empty set. - Prefer an error state when the absence is caused by system failure rather than valid criteria. - Prefer an empty-state onboarding pattern when the user has not created or received any data yet. Must include: - Show the query or filters that caused zero results. - Offer at least one direct recovery action. - Do not erase the user's input without consent. - Distinguish zero results from network or permission errors. ## User needs focused temporary attention ### Modal dialog Use for: Users sometimes need a short focused task layer that temporarily blocks the current page without sending them into a separate workflow. Selection rules: - Choose a modal dialog for a short contained task that must temporarily suspend interaction with the page behind it. - Use a full page when the task needs multiple steps, complex reading, saved progress, deep links, or durable browser history. - Use inline disclosure, a popover, or a drawer when users must continue comparing or editing background content while the layer is visible. - Use a confirmation dialog only when the dialog's main job is protecting a consequential action. - Use nonblocking feedback such as a banner, toast, or inline message when users only need status information. - Avoid nested modal stacks unless the second layer is unavoidable and focus return can still be made predictable. Must include: - Give the dialog a visible title and wire it to the dialog's accessible name. - Keep the task compact enough that users can complete it without page navigation. - Make the rest of the page inert or otherwise unavailable while the modal is open. - Move focus into the dialog on open and restore focus after every close path. - Implement contained Tab and Shift+Tab movement for keyboard users. - Support Escape for dismissible tasks and provide an explicit cancel or close affordance. - Keep critical actions visible when dialog content scrolls. - Prevent nested modal chains in ordinary workflows. - Test pointer, keyboard, screen reader, reduced viewport, and long-content behavior. ### Confirmation dialog Use for: Users can accidentally start consequential actions that are costly, security-sensitive, externally visible, or impossible to recover after commitment. Selection rules: - Choose confirmation when the action has a clear reason not to proceed and the user may change their mind after seeing the consequence. - Prefer undo when the exact prior state can be restored reliably after a frequent low-risk action. - Prefer prevention when the action is dangerous mainly because it is placed too close to routine controls. - Use a typed confirmation or equivalent extra step for broad account, workspace, production-data, or permission deletion. - Do not confirm ordinary save, archive, dismiss, filter, navigation, or low-risk edits that users perform repeatedly. - Do not use confirmation copy to teach users about a feature; use inline education, preview, or feedback instead. - Use a regular modal task when the user needs to edit values, not merely decide whether the consequence should happen. Must include: - Name the affected object, count, or scope in the title or main instruction. - Explain the consequence once, including whether recovery, audit, billing, permissions, or external recipients are affected. - Use a safe cancel label that explains the safe outcome, such as Keep archive or Cancel deletion. - Use a destructive action label that contains the verb and object, such as Delete archive. - Avoid OK, Yes, No, and Cancel-only button pairs when they force users to reinterpret the question. - Keep the safe action reachable by default and avoid committing destruction from an accidental Enter key. - Require typed text or a deliberate extra step for severe or broad-scope deletion. - Return focus predictably after cancel, Escape, and completion. - Track whether frequent prompts are being dismissed unread and replace them with undo or prevention when possible. ## User needs primary mobile destinations ### Bottom navigation Use for: Mobile users need one-tap access to a small set of primary app destinations without stretching to a top menu or losing section context. Selection rules: - Choose bottom navigation for three to five top-level mobile destinations of similar importance. - Keep destinations at the same hierarchy level and make each item navigate to a stable app section. - Use visible labels or very familiar labels plus accessible names; do not rely on ambiguous icons alone. - Preserve each destination's nested navigation, scroll position, filters, and drafts when users switch away and return. - Adapt to a navigation rail or drawer on wider screens or when the destination count exceeds what the bottom bar can hold. - Use a toolbar, floating action button, menu, or local button for commands instead of putting actions in the navigation bar. Must include: - Limit the bar to three to five primary destinations for compact mobile layouts. - Give every destination a text label or accessible name, plus an icon that reinforces the label. - Expose the active destination with aria-current="page" or the platform equivalent selected state. - Keep the bar outside the routed content area so it can persist while destinations change. - Store per-destination navigation and UI state when users switch sections. - Respect bottom safe areas, system gestures, and touch target sizing. - Move extra destinations to rail, drawer, More, or another primary navigation model instead of shrinking labels. ## User needs help asking an AI system ### Prompt suggestions Use for: Users often do not know what an AI surface can do, what context it has, or how to write a useful request without over-trusting the system. Selection rules: - Choose prompt suggestions when the user needs help discovering useful AI requests, not when the task can be captured by a fixed form. - Make each suggestion specific to the current object, workspace, agent capability, or role so it does not read like generic filler. - Load the selected suggestion into editable input before sending when the request can affect data, people, permissions, or consequential decisions. - Suppress or rewrite suggestions when the system lacks the required data, grounding, language support, tool access, or permission to satisfy them. - Prefer search suggestions when the goal is to phrase a retrieval query, and prefer a command palette when the row executes an app command or navigation action. Must include: - Derive suggestions from the current task, selected object, available tools, and known data sources. - Show short action labels, full editable prompt text, and a boundary note such as needs selected text or uses open tickets only. - Provide an explicit send action after selection and keep the draft prompt editable. - Expose selected, focused, unavailable, stale, loading, and no-suggestion states. - Avoid suggestions that imply hidden data access, guaranteed correctness, unsupported languages, or unavailable tool actions. - Measure which suggestions are selected, edited, sent, dismissed, saved, or shared without turning analytics into required user workflow.