| UI or UX | UI + UX - Short noninteractive description tied to a trigger | UI + UX - Small anchored contextual overlay | UI + UX - Contextual in-flow feedback | UI + UX - Ambiguous action anti-pattern |
| UI guidance | Render a tooltip as a small text-only bubble visually tied to a focusable trigger, with concise copy, readable contrast, stable placement, and an optional arrow that points to the target. | Render a popover as a compact surface visually tied to the trigger, field, selection, or object that opened it, with a clear title or labelled content when the body is more than a short sentence. | Render the message inside the same row, card, panel, form section, or task region that it describes, with a clear tone, concise title, body text, and at most one local action or detail disclosure. | Replace ambiguous symbol-only controls with visible text or icon-plus-text actions that name the verb and affected object. |
| UX guidance | Use tooltips to add a brief description on focus or hover without asking users to open a separate layer or change task mode. | Use a popover when users need local context, clarification, or a small edit without losing their place in the page. | Use inline messages when users need contextual feedback while continuing nearby work, such as a row-level warning, section-level success, local policy note, or task-specific next step. | Make users confident about what will happen before activation instead of forcing recognition, memorization, or trial-and-error. |
| Good UI | A labelled Archive icon button receives focus and shows a short tooltip that says Moves this report to archived reports. | A Due date button in a task row opens a small popover beside the field with Today, Tomorrow, Friday, a custom date field, and a visible close control. | An invoice row shows Missing billing contact directly beneath the affected customer with Add contact as the only action. | A report row shows Archive report, Download report, and Share report as labeled controls with matching accessible names. |
| Bad UI | A mystery icon has no label and the only explanation is a hover-only tooltip that never appears for touch users. | A large floating panel appears in the middle of the screen with no arrow, no title, no trigger relationship, and hidden controls below the fold. | A vague Important message appears above the whole page with no object reference. | A row exposes !, tray, and arrow buttons with no visible label and unclear consequences. |
| Good UX | Tabbing to Archive keeps focus on the button, shows a short description, Escape hides it, and focus remains on Archive. | Opening the due-date popover moves focus to the first date option, choosing Tomorrow updates the field, closes the layer, and returns focus to the Due date trigger. | Users can reveal why export is limited, add the missing contact, and see the local message resolve without losing table context. | Users can identify the action before activation and receive confirmation, undo, or result status after consequential actions. |
| Bad UX | A user presses Escape to hide the tooltip and focus jumps to the top of the page. | The user scrolls and the popover stays in the old position, so it appears to describe the wrong field. | The message disappears like a toast even though users still need the invoice reference. | Hover-only tooltip is the only explanation for a destructive action. |
| Best fit | A compact control needs a brief supplemental explanation. | A local control needs brief explanatory content or light editing while page context remains visible. | A visible object or section has local status, warning, success, or next-step information. | Use this anti-pattern entry to audit toolbars, row actions, cards, command bars, mobile action sheets, and generated UIs with symbol-only controls. |
| Avoid when | The text is the only label or action name. | The content is essential instruction that must remain visible for task completion. | The message is a one-field validation correction. | The icon is paired with visible text that names the action. |
| Required state | Resting trigger state with a visible or accessible name that works without the tooltip. | Closed trigger state with visible label, icon name, or field relationship. | Neutral local context with no message. | Default state where the action name is visible or programmatically exposed before activation. |
| Accessibility burden | Use tooltip text as a description with aria-describedby when it supplements the trigger. | Use a real button or equivalent control as the trigger whenever possible. | Keep the message in the reading order near the context it describes. | Every interactive icon control needs an accessible name that describes the action and, when useful, the affected object. |
| Common misuse | Using hover-only tooltip text as the only label for an icon button. | Using a popover as a hidden modal, drawer, sheet, command menu, or full workflow. | Using an inline message for a single field error that should be connected to that input. | Using a trash, tray, box, arrow, or exclamation icon for archive, delete, download, export, and warning actions without visible words. |