{ "counts": { "complete": 298, "stub": 0 }, "patterns": [ { "id": "accordion", "completionStatus": "complete", "name": "Accordion", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Grouped show-hide sections for related page content", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Long pages with several related sections can become hard to scan, but hiding content without clear headings, state, and keyboard behavior can make important information harder to find or compare.", "solution": "Group related content under explicit expandable section headings, expose each button's expanded state and controlled panel, preserve open-panel state intentionally, and only collapse content when selective reading helps more than always-visible content.", "uiGuidance": [ "Render each section title as a real button inside an appropriate heading, expose expanded or collapsed state, and connect the button to the panel it controls.", "Keep section labels specific and scannable, show whether each section is open, and provide expand-all or collapse-all only when users often need to inspect several sections together." ], "uxGuidance": [ "Use an accordion when a page has several related sections that users may inspect selectively while still needing an overview of all section labels.", "Do not use accordions to hide required sequential tasks, critical errors, primary actions, or content that users must compare side by side." ], "uiExamples": { "good": [ "A product policy page shows Shipping, Returns, Warranty, and Contact sections as heading buttons with clear expanded states and one open panel.", "A form uses Billing address, Shipping address, and Contact details section buttons, with changed or error counts visible while sections are collapsed." ], "bad": [ "A page hides every required instruction behind plus icons with no headings, state, or expand-all route.", "Collapsed rows look like navigation links, but clicking them only reveals hidden page text." ] }, "uxExamples": { "good": [ "A user opens Returns, then Warranty, scans both sections, collapses Returns, and the page keeps focus and open-state feedback stable.", "A keyboard user moves across section buttons, toggles with Enter or Space, and reaches the revealed content in the expected reading order." ], "bad": [ "A user misses eligibility requirements because the only required step is hidden inside a collapsed section by default.", "Opening one section unexpectedly closes another section that contained partially entered form values." ] }, "problemContext": [ "A page contains multiple related sections under one topic, form, policy, help article, settings group, or result detail.", "Users may need an overview of section labels before choosing which detail to read.", "Some sections may be optional, reference-heavy, or repeated enough that always showing all content would bury the page's main task.", "The product can keep headings, content order, open state, focus, and validation or status indicators synchronized." ], "selectionRules": [ "Choose accordion when multiple related page sections can be independently shown or hidden without changing route, page context, or selected mode.", "Use a single details disclosure when there is only one less-prominent revealable section.", "Use tabs when only one peer panel should be active and users are switching between sibling sections rather than scanning many section headings.", "Use side navigation when sections are separate pages or a persistent local hierarchy, not content panels on one page.", "Use filter panel when the collapsed groups contain controls that narrow a result set and need active-filter counts, applied summaries, and result synchronization.", "Use process list when expandable items are ordered journey steps with task links, costs, and branch guidance.", "Keep required errors, submit buttons, urgent warnings, and primary instructions visible or summarized outside collapsed sections.", "Allow several panels to remain open when comparison or form editing across sections is common; if only one panel can stay open, explain and preserve data before closing another section.", "Use expand-all or collapse-all for long accordion groups when users commonly need to scan or print several panels.", "Do not use accordion labels as page navigation unless the interaction actually navigates and exposes current-page state." ], "requiredStates": [ "All collapsed state with every section title visible.", "One section expanded state with button and controlled panel synchronized.", "Multiple sections expanded state when the accordion supports independent panels.", "Expand all and collapse all state when group controls are present.", "Collapsed section with error, changed, selected, or required-count summary when hidden content affects completion.", "Focused section header state that remains visible during keyboard navigation.", "Disabled or unavailable section state with explanation when expansion is blocked.", "Responsive state where long labels and panel content remain readable." ], "interactionContract": [ "Activating a section header toggles only the panel it owns unless the component is explicitly single-open.", "The header button exposes expanded or collapsed state and stays in the heading order.", "Revealed content appears immediately after its heading in reading and focus order.", "Enter or Space toggles the focused header; optional arrow, Home, and End support must not break normal Tab movement.", "Expand all opens every section and Collapse all closes every closable section without losing form values or scroll context.", "Collapsed sections that contain errors, active filters, changed values, or selected options expose a concise summary at the header.", "Deep links, validation, search hits, or find-in-page targets inside a panel open that panel or provide a clear route to it." ], "implementationChecklist": [ "Use button elements for section headers and place them inside semantic headings that match the page outline.", "Connect each button to its panel with stable identifiers and keep expanded state synchronized with visibility.", "Decide whether multiple panels can be open and implement that rule consistently.", "Keep content in source order so headings and panels make sense when styles or scripts fail.", "Expose hidden-error counts, selected-count summaries, or changed-state badges on collapsed headers when users need them.", "Avoid overusing landmark regions for every panel on pages with many sections.", "Test Enter, Space, Tab order, optional arrows, Home, End, screen reader announcements, print, no-JavaScript fallback, deep links, and mobile wrapping." ], "commonMisuses": [ "Using divs or links as section toggles without button semantics or expanded state.", "Hiding content users must read sequentially before completing a task.", "Making collapsed section labels too vague, such as More, Details, or Information.", "Removing form values or validation messages when another section opens.", "Showing errors only inside collapsed panels without a header summary or error link.", "Using an accordion as local navigation to separate pages.", "Forcing one panel open at a time when users need to compare multiple sections." ], "critiqueQuestions": [ "Are these sections related content on one page, or are they separate destinations?", "Can users understand every collapsed section from its label and summary?", "What important content, errors, or changed values are hidden when panels collapse?", "Should users be able to open multiple panels at once?", "Does keyboard focus move predictably from heading button to revealed content?", "Would always-visible headings, a details disclosure, tabs, side navigation, or a process list better match the task?" ], "relatedPatterns": [ "tabs", "side-navigation", "filter-panel", "process-list", "in-page-anchor-navigation" ], "comparisons": [ "accordion-vs-tabs-vs-side-navigation-vs-filter-panel" ], "sourceIds": [ "wai-aria-apg-accordion", "uswds-accordion-component", "govuk-accordion-component", "govuk-details-component" ] }, { "id": "account-creation", "completionStatus": "complete", "name": "Account creation", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Persistent account establishment flow", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Accounts can help users return, manage data, and protect access, but unnecessary or confusing account creation adds friction, duplicates accounts, exposes account existence, and can block users before they know whether the service meets their need.", "solution": "Ask users to create an account only when persistence is needed, explain the reason, reuse information already entered, separate new-account creation from sign-in, verify contact routes safely, avoid enumeration and unnecessary challenges, and land users back where the account helps them continue.", "uiGuidance": [ "Render account creation as a focused task with a clear reason for the account, one identifier path, new-credential fields, verification or activation state, existing-account route, and post-creation destination.", "Use labels such as Create an account, Create a password, and Email address for this account; keep sign-in, profile setup, marketing preferences, and optional personalization visually and semantically separate." ], "uxGuidance": [ "Use account creation only when a persistent account is necessary for repeated access, saved data, updates, security, or legal accountability.", "Delay account creation until it is required, avoid repeated data entry, protect against account enumeration, and route users who already have accounts toward sign-in or recovery without blocking the main service unnecessarily." ], "uiExamples": { "good": [ "A service lets users draft an application, then asks them to create an account to save and return later with email, new password, terms acknowledgement, and a clear activation message.", "A workspace app explains that an account stores projects across devices, uses Create an account as the heading, separates Already have an account? Sign in, and sends a verification email without revealing duplicate-account status." ], "bad": [ "A checkout asks for account registration before showing shipping cost or guest checkout even though the purchase can complete without an account.", "A registration screen has Sign in and Sign up side by side with identical email and password fields, plus newsletter, profile photo, and referral-code fields." ] }, "uxExamples": { "good": [ "A user completes most of a one-hour permit application, chooses to save progress, creates an account using the email already entered, verifies the email, and returns to the same draft.", "A user enters an email that may already exist and receives a neutral message that a link has been sent, with sign-in and recovery routes in the email rather than account-existence disclosure on the page." ], "bad": [ "A user must create an account before learning whether the service is suitable, then abandons because registration feels unnecessary.", "A user who already has an account accidentally creates a second account because the page never separates new-account creation from sign-in." ] }, "problemContext": [ "Users need to regularly access, update, save, resume, manage, or protect data in a service or product.", "The service may need an account for drafts, history, status checks, notifications, recovery, payments, permissions, auditability, or collaboration.", "A one-off transaction may be possible without an account and should not force one unless policy, security, or later management requires it.", "Users may already have an account, may be using a password manager, may need email or phone verification, or may be vulnerable to enumeration if responses reveal account existence.", "Account creation often touches email entry, password creation, terms acceptance, MFA setup, profile setup, and onboarding, but should not absorb those tasks unless they are necessary to establish the account." ], "selectionRules": [ "Choose account creation when a persistent account is required for repeated access, saved data, account management, security, authorization, legal accountability, or returning to drafts.", "Avoid account creation when a one-off service can use a reference number, email link, receipt, guest checkout, or existing identity route.", "Let users use as much of the service as practical before account creation when the account is only needed for save, return, submit, or manage-later behavior.", "Use Create an account language rather than ambiguous Register or Sign up copy when the task is establishing a new account.", "Label new credentials clearly, such as Create a password, so users do not think they are entering an existing password.", "Separate account creation from sign-in through page title, copy, route, and recovery link; do not rely only on two adjacent buttons.", "Reuse email, name, phone, address, or other data already entered rather than asking users to repeat it for the account.", "Use neutral messages for duplicate or existing accounts where enumeration risk matters, and route users through email, sign-in, or recovery.", "Ask for verification, MFA, terms, or consent only when needed for the account; defer profile setup, preferences, marketing opt-ins, and onboarding until after creation.", "Avoid CAPTCHAs and similar cognitive tests as the default abuse defense; prefer rate limits, risk controls, email verification, or other accessible security measures.", "Do not use National Insurance numbers or similarly high-risk identifiers as default account verification shortcuts.", "After successful creation, return users to the draft, task, dashboard, or next account-security step that explains why the account was created." ], "requiredStates": [ "Need-for-account state explaining why an account is required or beneficial at this point.", "New-account entry state with clear identifier and new credential labels.", "Already-have-account state with sign-in and recovery routes separated from creation.", "Duplicate or existing-account neutral response state that avoids exposing account existence.", "Verification pending state for email, phone, magic link, or activation code.", "Verification failed or expired state with resend, change contact, and support routes.", "Password-manager and autofill state supporting email, username, and new-password fields.", "Save-and-return state that lands back on a draft or interrupted task after creation.", "Optional setup deferred state where profile, preferences, MFA, or onboarding are offered without blocking unnecessary progress.", "Unavailable, rate-limited, or abuse-protection state with accessible recovery and no CAPTCHA-only dead end." ], "interactionContract": [ "The flow states why the account is needed before asking for credentials.", "Submitting account details validates required fields, preserves entered values except secrets when appropriate, and never displays raw passwords later.", "Existing-account detection does not reveal account existence on sensitive surfaces; users receive a neutral next step or are routed through email, sign-in, or recovery.", "Create-account and sign-in routes cannot silently switch modes while keeping the same field values in a misleading state.", "Verification links or codes identify the service, expire predictably, support resend, and allow users to change the target email or phone.", "Successful creation establishes an authenticated or pending account state and returns to the task or account area promised by the page.", "Security controls such as rate limits, bot defenses, and MFA setup are explained and accessible without turning into unrelated profile setup.", "Account creation records required consent or terms separately from optional marketing, personalization, or notification preferences." ], "implementationChecklist": [ "Decide whether an account is truly required; document the saved data, repeated access, authorization, legal, security, or collaboration need.", "Choose the account identifier, verification channel, credential method, recovery route, existing-account response, and post-creation destination before designing screens.", "Use native email, username, and new-password fields with correct autocomplete values and password-manager compatibility.", "Reuse information already entered in the service and clearly show when it will become part of the account.", "Design neutral duplicate-account, activation-link, expired-link, resend, change-contact, sign-in, recovery, and rate-limited states.", "Separate required account setup from profile details, notification preferences, consent choices, onboarding, and marketing opt-ins.", "Test new user, existing user, duplicate email, password manager, paste, verification timeout, mobile, keyboard, screen reader, slow network, translated copy, and abuse-control states.", "Monitor account-creation abandonment, duplicate-account creation, activation completion, recovery after duplicate attempts, and downstream return-to-task success." ], "commonMisuses": [ "Forcing accounts before users can evaluate a service or complete a one-off transaction.", "Using account creation to collect profile, marketing, or preference data that is not needed to establish the account.", "Presenting create account and sign in as identical forms with unclear labels.", "Revealing This email already exists on a public registration page.", "Asking users to retype information they already entered earlier in the service.", "Adding CAPTCHA as the only abuse defense or making it block assistive-technology users.", "Treating password creation, profile setup, onboarding, and account creation as one undifferentiated flow.", "Landing users on a blank account dashboard instead of returning to the draft or task that required the account." ], "critiqueQuestions": [ "Why is a persistent account needed here, and could a reference number or email link satisfy the user need?", "Can users do useful service work before account creation becomes necessary?", "How does the page make Create an account different from Sign in?", "What happens if the email or username already belongs to an account?", "Which entered information is reused, and which fields are unnecessary at this point?", "Where does the user land after creation, verification, expiration, or failure?" ], "relatedPatterns": [ "start-page", "onboarding", "password-creation", "email-address-entry", "password-input" ], "comparisons": [ "account-creation-vs-start-page-vs-onboarding-vs-password-creation" ], "sourceIds": [ "govuk-create-accounts-pattern", "owasp-authentication-account-enumeration", "owasp-wstg-account-enumeration", "nist-sp-800-63b-authentication-lifecycle", "mdn-html-autocomplete-password" ] }, { "id": "action-menu", "completionStatus": "complete", "name": "Action menu", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Contextual command list for a resource or selection", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Contextual commands often need to stay compact, but generic overflow menus become junk drawers when they mix unrelated actions, hide scope, omit disabled reasons, and place destructive commands beside safe actions.", "solution": "Design the action menu as a scoped command list: name the resource or selection, group related commands, label each item by verb and object, explain unavailable actions, separate high-risk commands, and route consequential actions through review or recovery.", "uiGuidance": [ "Render a compact menu of verb-led actions scoped to one resource, row, card, selected set, or page object, with clear section headings, object-aware labels, disabled reasons, and separated dangerous commands.", "Use icons, shortcuts, descriptions, and external-link markers only to clarify text labels; avoid making the menu a mixed panel of forms, filters, field values, navigation, and unrelated controls." ], "uxGuidance": [ "Use an action menu when users need several contextual commands without keeping every command visible, and the list itself must explain scope, availability, risk, and outcome.", "Make the current object or selection count explicit, update actions when scope changes, and route destructive or privacy-sensitive commands into confirmation, undo, restore, or review instead of running silently." ], "uiExamples": { "good": [ "A Customer actions menu has Manage customer, Data requests, and Account risk sections, with Edit customer, Merge customer, Request data export, and Delete customer separated at the end.", "A bulk selection menu changes labels from Archive customer to Archive 3 customers and disables Merge because it only applies to one customer.", "A report row menu shows Duplicate report, Download CSV, Share link, and Archive report with disabled Export unavailable because the report is still processing." ], "bad": [ "A More menu contains Open, Edit, View, Delete, Settings, Filter, Owner, and a search box with no sections or object names.", "A Delete action sits between Rename and Duplicate with the same style and no consequence preview.", "Every row menu uses identical labels such as Open and Delete, so screen reader users cannot tell which record will change." ] }, "uxExamples": { "good": [ "A user opens Customer actions, chooses Duplicate customer, and receives status that names the customer and keeps focus anchored to the action context.", "A user changes from one selected customer to three, sees single-object actions disabled with reasons, and can run Export selected customers.", "A user chooses Delete customer and is moved to a review state that names the affected customer before commitment." ], "bad": [ "A user chooses Delete from a generic row menu and cannot tell whether it deletes the row, account, attached files, or selected customers.", "A user opens a menu to export selected items but the action is disabled with no reason or next step.", "A user activates a menu item that looks like a command but navigates away and loses unsaved context." ] }, "problemContext": [ "A row, card, table, selected set, page resource, or toolbar has more contextual commands than should be visible at once.", "The command list changes according to object state, permissions, processing state, or selection count.", "Users need to distinguish safe commands, links, disabled commands, bulk actions, and dangerous commands before activation.", "The trigger pattern already exists, but the menu content still needs taxonomy, labels, grouping, state, and outcome rules.", "The interaction must work for pointer, keyboard, touch, and assistive technology users without losing object context." ], "selectionRules": [ "Choose an action menu when commands are contextual to one object, selected set, resource, row, card, or local page surface.", "Use a menu button pattern when the primary problem is trigger labelling, open state, popup ownership, focus movement, dismissal, and focus return.", "Use a button group when there are only a few important related commands that should remain visible.", "Use a command palette when commands are broad, searchable, shortcut-driven, cross-product, or not tied to the current object.", "Use a menubar when the product has a persistent application command hierarchy with stable top-level command groups.", "Use select, listbox, radio group, checkbox group, multi-select, or chip selection when the user is choosing values rather than invoking commands.", "Use confirmation dialog, typed confirmation, undo, or restore after a dangerous action is selected, not as a substitute for clear menu item labels.", "Use action sheet, context menu, drawer, or bottom sheet for platform-specific presentation when the same contextual command-list rules apply." ], "requiredStates": [ "Closed trigger or contextual entry point with resource scope.", "Open menu with accessible name that includes the object or selection scope.", "Sectioned menu state with headings or separators.", "Safe command item state with verb and object label.", "Disabled or unavailable command state with visible reason.", "External link or navigation item state when links are allowed.", "Destructive command state separated from safe commands.", "Bulk selection state that updates labels, disabled rules, and result copy.", "Processing or recently completed command status.", "Dangerous command review handoff state.", "Empty or no-applicable-actions state.", "Long label, narrow viewport, and high-zoom wrapping state." ], "interactionContract": [ "Every item has a clear verb, object, and outcome category: command, navigation link, checkable command, disabled command, or destructive command.", "The menu title, trigger label, aria-label, or nearby context identifies which resource or selected set the actions affect.", "Sections group commands by user intent or risk, not by implementation owner.", "Disabled actions cannot run and explain the blocker when users need that knowledge.", "Bulk selection changes item labels, disabled state, and result status so commands cannot silently affect the wrong scope.", "Dangerous commands are visually separated and either open review, confirmation, undo, restore, or another recovery path.", "Links disclose navigation or new-tab behavior when they can leave the current task.", "The menu closes after safe command activation and reports what changed.", "Focus return, keyboard movement, and dismissal follow the trigger pattern or platform action-sheet behavior.", "The compact action menu does not contain forms, complex editors, large previews, filters, or unrelated content." ], "implementationChecklist": [ "Inventory commands by resource state, permission, selected count, frequency, risk, and recovery path.", "Name the menu by object or scope, such as Customer actions or Actions for 3 selected invoices.", "Write each item as a verb phrase with enough object context for repeated rows and screen readers.", "Group related commands under headings or separators when there are different scopes or risk levels.", "Separate destructive actions and define confirmation, undo, restore, or review behavior before implementation.", "Decide when unavailable actions should remain visible with a reason versus be omitted because they never apply.", "Update the menu when selection count, object state, permission, processing, or ownership changes.", "Keep icons optional, consistent, and secondary to text; give icon-only triggers precise accessible names.", "Avoid embedding form controls, search boxes, sliders, calendars, rich previews, and editable tables inside the action menu.", "Test row context, bulk context, disabled reasons, destructive handoff, keyboard focus, screen reader names, touch target size, zoom, forced colors, clipping, and portal placement." ], "commonMisuses": [ "Treating the action menu as a junk drawer for every command that does not fit elsewhere.", "Using vague labels such as Open, Manage, More, or Delete without naming the object or result.", "Mixing commands, links, field values, filters, toggles, and form fields without role or visual distinction.", "Leaving disabled actions greyed out with no reason or recovery path.", "Letting a bulk action menu run single-object commands against multiple selected items.", "Putting destructive actions in the middle of safe commands with the same emphasis.", "Hiding primary or emergency recovery commands inside a menu while low-value buttons stay visible.", "Using icons as the only action names inside the menu.", "Failing to update menu content after object state changes, such as archived, locked, processing, or permission-limited records." ], "critiqueQuestions": [ "Can users tell exactly which object or selected set the menu will affect?", "Are commands grouped by meaningful user intent and risk rather than dumped into one list?", "Do item labels name the action and object well enough for repeated row menus?", "Are disabled actions either explained or omitted according to whether the user can recover?", "Does the menu update when selection count, permission, processing state, or ownership changes?", "Are destructive commands separated and routed through confirmation, undo, restore, or review?", "Is any menu content actually a form, filter panel, settings page, or value selector that needs a different pattern?" ], "relatedPatterns": [ "menu-button", "menu-menubar", "button-group", "command-palette", "confirmation-dialog", "icon-only-ambiguous-action", "disabled-button-no-explanation", "undo", "select", "listbox" ], "comparisons": [ "action-menu-vs-menu-button-vs-button-group-vs-command-palette" ], "sourceIds": [ "shopify-polaris-menu", "adobe-spectrum-menu", "wai-aria-apg-menu-menubar", "atlassian-dropdown-menu" ] }, { "id": "action-sheet", "completionStatus": "complete", "name": "Action sheet", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Platform-presented action choice sheet", "maturity": "standard", "platforms": [ "mobile", "web", "desktop" ], "problem": "Users sometimes initiate an action that has several legitimate outcomes, but a single confirmation dialog is too narrow and a full sheet or page is too heavy for the immediate choice.", "solution": "Present a concise action sheet from the initiating control or task, name the affected object, show only the few relevant choices, separate cancel and destructive roles, support keyboard and assistive technology dismissal, and return focus or state to the correct origin after a choice.", "uiGuidance": [ "Render an action sheet as a short platform-style list of choices tied to the action the user just initiated, with a visible title or message when context is needed, clear action roles, a distinct cancel route, and destructive choices visually separated.", "Keep action-sheet content to immediate action choices; do not turn it into a detented bottom sheet, rich preview, form, navigation drawer, picker, or long menu." ], "uxGuidance": [ "Use an action sheet when users intentionally start an action and need to choose among a few valid outcomes before the product continues, such as Save draft, Discard draft, Share, Report, or Cancel.", "Make the source task, affected object, safe escape, destructive consequence, dismissal behavior, focus movement, and post-choice outcome explicit so the sheet resolves the initiated action without surprising users." ], "uiExamples": { "good": [ "A mail composer Cancel button opens an action sheet titled Save this draft? with Save draft, Discard draft in destructive styling, and Cancel separated at the bottom.", "A photo card Action button opens a share sheet with Copy link, Share image, Save to album, Report image, and Cancel, with Report visually separated from safe actions." ], "bad": [ "A bottom overlay opens with navigation links, filters, a preview image, a text field, and a Delete button all in one scrollable sheet.", "A destructive Discard option sits between safe choices with no object name, no cancel button, and no explanation of whether the draft is saved." ] }, "uxExamples": { "good": [ "A user taps Cancel while editing Message draft 18, chooses Save draft, the sheet closes, and focus returns to the composer with a saved-draft status.", "A user opens photo actions, chooses Report image, receives a consequence preview before commitment, and can cancel without changing the photo." ], "bad": [ "A sheet appears on app launch with promotional choices even though the user did not initiate an action.", "A user tries to scroll through many actions and accidentally taps Delete because the sheet is overloaded and lacks destructive separation." ] }, "problemContext": [ "The user has already tapped, clicked, or invoked a control such as Cancel, Share, More, Remove, or Report.", "There are several immediate outcomes rather than a single yes-or-no confirmation.", "The choice is short-lived and should resolve without a route change, long form, or durable panel.", "The product can clearly distinguish safe choices, cancel, destructive choices, and follow-up review when risk is high." ], "selectionRules": [ "Choose action sheet when an intentional user action needs a small set of immediate choices related to the current object, draft, page, document, or selected item.", "Use action menu when the broader problem is organizing many contextual commands with grouping, disabled reasons, bulk scope, or repeated object menus.", "Use bottom sheet when the surface needs mobile bottom-edge reach, richer contextual detail, detents, scroll coordination, or persistent orientation to background content.", "Use confirmation dialog when there is one primary consequence decision and the user needs focused review rather than several possible action paths.", "Use alert dialog for urgent system or safety conditions that require response and are not simply choices related to a user-started action.", "Use popover or menu button on larger screens when platform conventions present the same choices as an anchored popover rather than a bottom action sheet.", "Use a full page or flow when choices require forms, previews, authentication, multiple steps, history, or saved progress.", "Use visible buttons instead of an action sheet for one or two frequent low-risk choices that should remain directly available." ], "requiredStates": [ "Resting state with an initiating control or task context.", "Opening state that ties the sheet to the action the user just invoked.", "Visible title, message, or object label when needed to clarify the scope.", "Safe action choice state.", "Cancel or keep-current-state choice state.", "Destructive choice state with visual and semantic separation.", "Unavailable or permission-blocked choice state with omission or explanation.", "Follow-up review state for high-risk choices that exceed simple action-sheet commitment.", "Dismissed state that preserves or returns focus to the initiating task.", "Large-screen adapted state that uses platform popover or anchored presentation while keeping the same action roles." ], "interactionContract": [ "The sheet opens only after a user-initiated action, not as unsolicited promotion, onboarding, or error display.", "Every choice directly answers the initiated action and names the object when ambiguity is possible.", "Cancel leaves the task unchanged and is visually or structurally distinct from action choices.", "Destructive choices are separated, styled by role, and named by consequence.", "The sheet contains only a few choices; it does not require ordinary users to scroll to inspect actions.", "Choosing a safe action closes the sheet and reports the result.", "Choosing a high-risk action either commits a clearly named reversible action or moves to stronger review before commitment.", "Scrim tap, Escape, back, drag, or Cancel all follow the same safe-dismissal rule.", "Focus moves into the sheet on open and returns to the initiating control, object, or logical successor after close.", "The same action roles remain understandable when the platform adapts the presentation to a popover on larger screens." ], "implementationChecklist": [ "Define the initiating control, current object, and exact user question the sheet answers.", "Limit choices to the few immediate outcomes of that initiated action.", "Write labels as concrete verbs and objects, such as Save draft, Discard draft, Share photo, or Report message.", "Provide Cancel or Keep editing when abandonment or backing out is a meaningful safe path.", "Assign destructive role styling and separate destructive choices from safe choices.", "Escalate severe irreversible actions to confirmation, typed confirmation, restore, or undo rather than relying on color alone.", "Avoid scrollable action sheets; reduce, group elsewhere, or move to a richer surface when choices multiply.", "Implement focus placement, Escape or back dismissal, scrim or drag behavior, result status, and focus return.", "Test touch targets, screen reader order, large text, landscape, keyboard access, platform popover adaptation, and accidental-tap prevention." ], "commonMisuses": [ "Showing an action sheet before the user starts an action.", "Using an action sheet as an alert for information that has no choice set.", "Adding many options until the sheet scrolls and users can accidentally tap while inspecting.", "Mixing commands with forms, previews, navigation links, search, filters, and settings.", "Omitting Cancel when leaving the current task unchanged is important.", "Styling a destructive option like an ordinary safe choice.", "Using an action sheet for a long workflow that needs progress, validation, or save recovery.", "Treating a detented bottom sheet or share activity view as the same pattern without checking the additional behavior." ], "critiqueQuestions": [ "What intentional user action opened this sheet?", "What exact question is the sheet asking, and can every choice answer that question?", "Can users safely cancel without losing the current task or object context?", "Is there any choice that needs confirmation, undo, restore, or stronger review before commitment?", "Would the content become clearer as an action menu, bottom sheet, confirmation dialog, popover, or page?", "Does the sheet still work with keyboard, screen reader, large text, landscape, and platform popover adaptation?" ], "relatedPatterns": [ "action-menu", "bottom-sheet", "sheet", "confirmation-dialog", "alert-dialog", "popover", "menu-button", "undo", "destructive-action-confirmation" ], "comparisons": [ "action-sheet-vs-action-menu-vs-bottom-sheet-vs-confirmation-dialog" ], "sourceIds": [ "apple-hig-action-sheets", "apple-hig-activity-views", "material-bottom-sheets", "nng-bottom-sheets" ] }, { "id": "activity-feed", "completionStatus": "complete", "name": "Activity feed", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Catch-up stream of recent collaboration and work events with actor, verb, object, type, destination, and triage controls", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Teams need a lightweight way to catch up on what happened, but products often blur activity feeds with broad content feeds, notification inboxes, audit logs, timelines, and live presence streams, causing noisy, unactionable, or misleading activity surfaces.", "solution": "Provide a typed activity feed with actor-verb-object event anatomy, source and timestamp, meaningful preview, filters, unread or clear behavior, grouping, deep links, retention limits, and boundaries that route conversations, audit evidence, notifications, and live status to the right surfaces.", "uiGuidance": [ "Render activity feed as a typed event stream where each item names the actor or source app, action, object, workspace or channel, timestamp, preview, event type, read or cleared state when supported, and a stable destination for follow-up.", "Expose activity-type filters, unread or cleared state, dense and detailed layouts, grouped repeated events, retention or expiry limits, notification settings, and suppressed/noisy-source controls instead of treating all work events as identical feed cards." ], "uxGuidance": [ "Use activity feed when users need to catch up on recent work or collaboration activity across channels, projects, repositories, tasks, apps, or people without opening every underlying object.", "Protect attention by grouping low-value repetition, preserving meaningful actors and destinations, distinguishing mention/reply/reaction/app/reminder/project-change types, and routing audit evidence, long-form content, and live status elsewhere." ], "uiExamples": { "good": [ "A team activity feed shows Priya mentioned you in #refunds, Build bot marked release-128 failed, Maya reacted to your handoff note, and Rahul merged PR #742, each with icon, timestamp, preview, type filter, and Open action.", "An organization repository feed shows who opened, closed, merged, commented, pushed, or released, grouped by repository and filtered to issues, pull requests, branches, releases, comments, or pushes." ], "bad": [ "A page titled Activity shows Update happened cards with no actor, object, type, timestamp, or destination.", "A feed includes every presence heartbeat and typing event, making mentions and failed deployment events impossible to find." ] }, "uxExamples": { "good": [ "A user filters Activity to mentions and replies, answers one thread inline, clears low-value reactions, saves a custom view for VIPs, and opens a deployment failure in the source app.", "A developer opens an organization activity feed, filters to pull-request activity, sees who merged and commented, and jumps to the relevant repository without using the audit log." ], "bad": [ "A user clears a notification in Activity but the notification center badge stays out of sync and the same event reappears as unread.", "A compliance analyst exports an activity feed expecting audit proof, but it lacks immutable event IDs, IP addresses, retention policy, and complete actor data." ] }, "problemContext": [ "Events may come from people, channels, repositories, projects, tasks, apps, bots, automations, meetings, reminders, comments, mentions, reactions, shares, merges, deployments, assignments, or approvals.", "Users open the feed to catch up, triage, scan, reply, clear, mark read, filter, jump to source objects, or personalize which activity types deserve attention.", "Events may be personal to the user, workspace-wide, organization-scoped, repository-scoped, channel-scoped, object-scoped, or app-generated.", "The surface may overlap with notification center, feed, timeline, activity log, comments, mentions, presence, and following/subscription behavior, so event ownership and lifecycle rules must be explicit." ], "selectionRules": [ "Choose activity feed when the primary task is catching up on recent collaboration or system activity across work objects rather than reading broad content or managing audit evidence.", "Use feed when the stream is primarily article-like posts, stories, media, recommendations, or content consumption.", "Use notification center when the item lifecycle depends on unseen badges, unread state, mark-read, preferences, cleanup, and retained notification history.", "Use activity log when users need searchable, exportable, retained evidence of actor/action/object records with compliance or investigation detail.", "Use timeline when the user needs a bounded chronological history for one case, process, project, object, or order.", "Use comments, mentions, and threaded discussion for the underlying conversation; activity feed should preview and route to them rather than becoming the conversation system.", "Use presence for current online, viewing, typing, or availability state; only surface presence in activity feed when it becomes a meaningful event such as joined, assigned, or started presenting.", "Include actor, verb, object, source, timestamp, event type, preview, scope, and destination before adding visual density or ranking controls.", "Offer filters for meaningful activity types such as unread, mentions, replies, reactions, channel activity, app events, reminders, repository events, and cleared items.", "Suppress, group, or collapse noisy repeated events such as many reactions, automated sync churn, duplicate app posts, cursor movement, and frequent status changes." ], "requiredStates": [ "Default feed state with actor, verb, object, timestamp, source, type icon, preview, scope, and destination for each activity item.", "Unread, read, cleared, selected, replied, opened, muted, hidden, grouped, collapsed, and expanded item states.", "Filters for all activity, unread, mentions, replies, reactions, channel or project activity, app events, reminders, repository events, and cleared items where supported.", "Dense layout, detailed layout, custom saved view, and mobile compact states.", "New activity waiting, live refresh paused, refresh failed, stale feed, offline, loading, empty, no matching filter, and retention-expired states.", "Inline reply, open in source, set reminder, mute thread, turn off noisy type, mark all read, clear one, clear selected, and restore cleared states.", "Grouped repeated activity, bot activity, external app activity, VIP or priority activity, private/no-disclosure activity, and permission-limited activity states.", "Synchronization state with notification center so cleared, read, and opened events do not contradict the badge or inbox.", "Responsive state where actor, verb, object, type, timestamp, and action destination remain readable." ], "interactionContract": [ "Each item represents one meaningful work activity or a grouped set with stable actor, action, object, source, timestamp, type, preview, scope, and destination.", "Opening an activity routes to the underlying channel, message, thread, repository, task, meeting, app, file, or object and updates read or cleared state according to product policy.", "Reply, clear, mark read, set reminder, mute, and open-source actions apply to the named activity item or group only.", "Filters change visible items without deleting events; clear and mark-read actions provide immediate feedback and preserve recoverability where supported.", "Dense and detailed layouts preserve the same activity identity and actions, only changing how much preview context is shown.", "Saved views preserve filter combinations and do not silently change notification eligibility or underlying subscription settings.", "Activity feed state synchronizes with notification center, mention surfaces, thread views, and related-object state when the same event appears in multiple places.", "No-disclosure and permission-limited events hide restricted object names, previews, or actors while still explaining why the item cannot be opened." ], "implementationChecklist": [ "Define event schema for actor, actor type, verb, object, object type, source app, workspace, channel or project, timestamp, event type, preview, destination URL, read state, clear state, priority, grouping key, and retention.", "Separate activity-feed records from notification records, audit-log records, timeline milestones, comments, mentions, reactions, presence heartbeats, and broad content feed items in the data model.", "Build activity-type filters, unread filter, cleared filter, source filter, custom saved views, dense/detail toggle, mark-read, clear, bulk clear, inline reply, reminder, mute, and open-source actions.", "Group repeated reactions, bot updates, deployment churn, bulk repository events, and high-volume channel posts without hiding high-priority mentions or failures.", "Model retention and expiry, stale feed refresh, offline fallback, permission-limited destinations, deleted objects, private channels, blocked users, and external app failures.", "Synchronize activity state with notification center, thread views, mentions, related object pages, and preferences so items do not reappear unexpectedly.", "Test mobile compact layout, keyboard navigation, screen-reader item names, long actor names, localization of actor-verb-object text, grouped event expansion, filter empty states, and deep-link return behavior." ], "commonMisuses": [ "Using activity feed as an audit log without evidence fields, export, or retention guarantees.", "Using activity feed as a notification center without clear unread, badge, preference, or cleanup semantics.", "Dumping every low-level system event, presence update, typing event, or cursor movement into the feed.", "Hiding actor, object, event type, source app, or timestamp until users open the item.", "Making clear, reply, or mute actions affect a thread or channel different from the visible item.", "Mixing algorithmic content recommendations with work events without labels.", "Letting private or permission-limited activity reveal object titles, channel names, or actors.", "Providing filters that only hide items visually while badge and saved-view state still count them." ], "critiqueQuestions": [ "What events are meaningful enough for catch-up, and which belong only in audit logs, notifications, comments, or live presence?", "Can users tell who did what, to which object, in which source, and when?", "Which activity types can users filter, clear, mark read, mute, or save as views?", "What happens when the user opens the underlying object from another route?", "How are repeated reactions, bot events, deployment churn, and noisy app updates grouped or suppressed?", "Which items expire from the activity feed, and where can users find durable evidence afterward?", "How are permission-limited or private-channel events represented without leaking restricted context?" ], "relatedPatterns": [ "feed", "activity-log", "notification-center", "timeline", "comments", "mentions", "threaded-discussion", "presence", "filter-panel", "saved-view" ], "comparisons": [ "activity-feed-vs-feed-vs-activity-log-vs-notification-center" ], "sourceIds": [ "microsoft-teams-explore-activity-feed", "slack-activity-view", "github-organization-news-feed", "microsoft-graph-teams-activity-feed-notifications", "microsoft-teams-activity-feed-notifications", "wai-aria-apg-feed" ] }, { "id": "activity-log", "completionStatus": "complete", "name": "Activity log", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Searchable and exportable record of system, user, or administrative events", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Organizations and power users need to understand who did what, to which object, from where, and when, but ordinary timelines, feeds, notifications, and history pages often omit the evidence, scope, retention, and export behavior required for investigation.", "solution": "Provide an activity log with structured event records, actor/action/object anatomy, powerful filtering and search, visible scope and retention limits, event details, redaction and delay states, export behavior, and clear distinctions from summaries, notifications, and user-controlled history.", "uiGuidance": [ "Render activity logs as evidence-oriented records with event time, actor, action, object, source system, scope, result, and technical context such as IP address or location when available.", "Expose filters, query syntax, retention window, permission scope, redaction, export, and timezone state directly beside the results so users know what the visible log does and does not prove." ], "uxGuidance": [ "Use activity log when users need to investigate, audit, verify, or troubleshoot actions across accounts, objects, systems, settings, or security boundaries.", "Protect trust by showing provenance and limitations: delayed ingestion, redacted fields, duplicated streamed events, retention cutoffs, scoped access, export range, and whether records are immutable or corrected." ], "uiExamples": { "good": [ "An organization audit log table shows timestamp, actor, action, target object, app, IP address, result, and a Details drawer with before and after fields.", "A filtered security log displays 'admin role changes, last 7 days, UTC, 42 records, 3 redacted by scope' with Export CSV and Save query controls." ], "bad": [ "A page titled Activity shows vague entries such as Changed settings with no actor, target, timestamp, or source.", "An export button downloads a different date range and timezone than the on-screen filtered log." ] }, "uxExamples": { "good": [ "An admin filters to failed SSO events, expands one entry, copies the event ID, exports the filtered range, and sees that records older than 180 days require a different archive.", "A support lead opens a user-access event and sees actor, object, changed role, IP address, source app, timestamp in UTC, and redacted fields caused by permission scope." ], "bad": [ "A user marks a notification read and the corresponding activity evidence disappears from the only log.", "A security analyst searches for a deleted repository event but the UI hides that Git events have shorter retention." ] }, "problemContext": [ "Events may come from users, admins, service accounts, automation, integrations, or system processes.", "Users inspect the log for troubleshooting, security review, compliance, incident response, permission review, billing disputes, change review, or operational proof.", "Records may have retention windows, role-gated access, redacted fields, delayed ingestion, duplicate delivery, timezone normalization, or export constraints.", "The surface often spans multiple apps, workspaces, objects, groups, locations, devices, and event types." ], "selectionRules": [ "Choose activity log when the task is evidence review, investigation, compliance, security monitoring, or operational troubleshooting.", "Use timeline when users only need a readable summary of important events for one object or process.", "Use feed when users consume a live or personalized stream and reading position matters more than evidence completeness.", "Use notification center when users need personal triage, unread state, badge behavior, and notification preferences.", "Use search history when users manage their own stored query activity and deletion or pause controls are the primary need.", "Use table or data grid when event records need dense column comparison, sortable fields, column selection, or export-ready row structure.", "Include actor, action, object, timestamp, source, result, and event ID before adding visual summaries.", "Show active filters, query, timezone, retention window, permission scope, and result count near the log.", "Provide detail expansion for changed fields, request metadata, IP/location, source app, raw payload, or related records where appropriate.", "Label redacted, delayed, duplicate, corrected, archived, failed-ingestion, unavailable, and out-of-retention states.", "Do not promise deletion, completeness, or legal proof unless the retention and backend record model support that claim.", "Design export and API access as first-class behavior when the log supports investigation beyond the UI." ], "requiredStates": [ "Default log state with event records, result count, visible timezone, retention window, and permission scope.", "Filtered and searched states by actor, action, object, app, date range, result, IP, location, or event ID.", "Expanded event detail state with changed fields, source, event ID, request context, and related object route.", "Export queued, export ready, export failed, and export range mismatch states.", "No results, empty log, loading, delayed ingestion, offline, failed-load, and retry states.", "Redacted, permission-limited, out-of-retention, archived, corrected, duplicate, and deleted-object states.", "Saved query or copied query state when investigation workflows support reuse.", "Responsive state where event identity and critical metadata remain readable without hiding scope." ], "interactionContract": [ "Each log row identifies one recorded event and keeps actor, action, object, timestamp, and event ID stable across filtering, sorting, expansion, export, and refresh.", "Filters narrow visible records without deleting or mutating log evidence.", "Search and date range controls state the timezone and included endpoints used by the query.", "Opening details reveals additional evidence for the same event and does not summarize multiple events as one record.", "Export uses the same query, range, timezone, fields, and permission scope shown on screen or explains the difference before export.", "Redacted or unavailable fields explain whether data is hidden by permissions, policy, retention, ingestion delay, or source-system loss.", "Records are not removed by notification read state, user-facing dismissal, or personal history deletion unless the backend policy explicitly allows it.", "After refresh, export, expansion, or filter changes, focus remains near the triggering control or updated result summary." ], "implementationChecklist": [ "Define event schema: event ID, timestamp, timezone, actor, actor type, action, object, object type, source app, result, IP, location, request ID, before and after fields, retention class, and export eligibility.", "Separate activity-log records from feeds, notification records, search history, analytics events, and timeline summaries in the data model.", "Build filters for actor, action, object, app, result, event type, date range, IP/location, and event ID according to real investigative tasks.", "Display active query, scope, result count, timezone, retention window, ingestion freshness, and permission limitations near the log.", "Implement details, copy event ID, copy query, saved query, export, retry, and archive routes with explicit status feedback.", "Model redaction, retention cutoff, duplicates, corrected timestamps, delayed ingestion, failed export, deleted objects, and scoped administrator access.", "Test long actor names, service accounts, missing IPs, redacted fields, partial exports, timezone changes, virtualized rows, keyboard expansion, screen-reader row identity, and mobile metadata wrapping.", "Audit telemetry so sensitive log contents are not leaked into unrelated analytics while still recording use of log controls." ], "commonMisuses": [ "Calling a social feed or notification drawer an activity log without event evidence.", "Using vague activity labels that omit actor, action, object, timestamp, or result.", "Hiding retention limits, permission scope, or redaction until after users fail to find records.", "Letting mark-read, dismiss, archive, or personal-history deletion remove administrative evidence.", "Showing local browser time in the UI while export uses UTC without disclosure.", "Exporting a different field set, date range, or filter query than the visible results.", "Treating streamed duplicate events as separate confirmed actions without duplicate indicators.", "Using activity log as a timeline summary when users need searchable, exportable records." ], "critiqueQuestions": [ "What question does this log answer: who, what, when, where, before and after, or whether the record exists at all?", "Which event fields are required for investigation, and which are unavailable, redacted, delayed, or out of retention?", "Can users tell the active query, date range, timezone, result count, permission scope, and retention window?", "Does export exactly match the on-screen query and field set, and does the UI say when it does not?", "What happens to log records when notifications are read, objects are deleted, users leave, or personal history is cleared?", "Would timeline, feed, notification center, search history, table, or data grid better fit this surface?" ], "relatedPatterns": [ "timeline", "notification-center", "search-history", "feed", "table", "data-grid", "filter-panel", "sort-controls", "pagination", "details-panel" ], "comparisons": [ "activity-log-vs-timeline-vs-notification-center-vs-search-history" ], "sourceIds": [ "atlassian-view-audit-log-activities", "github-organization-audit-log", "github-enterprise-audit-log-api", "microsoft-purview-audit-search", "microsoft-purview-audit-solutions" ] }, { "id": "adaptive-defaults", "completionStatus": "complete", "name": "Adaptive defaults", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "Context-aware starting values for fields, filters, scopes, layouts, schedules, channels, or workflow options", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Repeated setup, forms, filters, scheduling, and workflow choices slow users down, but unlabelled adaptive defaults can cause wrong submissions, privacy leaks, accidental persistence, or loss of trust when users cannot see why a value appeared.", "solution": "Provide context-aware starting values that are visible, explainable, reversible, scoped, and easy to correct, while keeping durable settings, consent choices, recommendations, and required workflow state separate.", "uiGuidance": [ "Render adaptive defaults as visible starting values with source labels, confidence or rule basis, scope, freshness, and a nearby way to change, reset, or stop using the signal.", "Separate adapted starting values from persisted settings, user preferences, recommendations, and required values by showing that the value is only a proposed starting point until the user confirms or edits it." ], "uxGuidance": [ "Use adaptive defaults when the product can reduce repetitive setup by proposing values from current context, recent use, prior correction, locale, role, organization policy, device, or task history.", "Keep user agency clear: make corrections cheap, remember explicit corrections where appropriate, avoid silently changing durable settings, and never use adaptive defaults to hide high-impact choices." ], "uiExamples": { "good": [ "A case export form defaults to Current queue and CSV because the user exported the same queue yesterday, labels the basis, and lets them switch scope before export.", "A booking form defaults to the user's local time zone and next available workday, shows Detected from device and Team calendar, and provides Change and remember controls.", "A dashboard filter starts with My region and Last 30 days because of role and recent use, but Reset to system default and Do not adapt this filter remain visible." ], "bad": [ "A payment form preselects the highest donation amount because it predicts generosity and hides the source.", "A privacy setting is switched on by an adaptive rule and saved account-wide without review.", "A form keeps defaulting to the wrong office even after the user changes it on every submission." ] }, "uxExamples": { "good": [ "A user opens a recurring report, sees Project: Acme and Range: Last month already filled from the previous run, changes the range to Quarter, and the system asks whether to remember that correction.", "A mobile app detects roaming and defaults uploads to Wi-Fi only for this session while showing that the account setting is unchanged.", "A workspace admin sees a policy-provided retention default, understands that it is inherited, and can request an exception instead of fighting a disabled field." ], "bad": [ "A user submits a form without noticing that an adaptive default changed the external recipient.", "A manager changes an adapted value once and accidentally changes the saved default for the whole organization.", "A personalized default uses sensitive search history on a shared screen and reveals private activity." ] }, "problemContext": [ "The user repeatedly fills similar fields, chooses similar scopes, opens similar filters, schedules similar work, exports similar data, or applies similar layout and channel choices.", "The product has signals such as recent use, current object, role, locale, device, calendar, organization policy, saved setting, explicit preference, previous correction, or aggregate common value.", "The proposed value affects the current task, but may also touch permissions, privacy, external communication, money, scheduling, compliance, or shared workspace behavior.", "Users need to distinguish a helpful starting value from a saved preference, system requirement, recommendation, or hidden automation." ], "selectionRules": [ "Choose adaptive defaults when the system proposes a starting value inside the current task based on context or learned behavior.", "Use static defaults when the same representative value is best for most users and no personal or contextual signal is involved.", "Use settings management when users need to inspect or change durable configuration that persists beyond the current task.", "Use preference center when the value represents communication, consent, privacy, topic, personalization, language, or required-message choices.", "Use recommendations when the system ranks optional items or actions rather than filling a value the user must review or edit.", "Expose the default source in user-facing terms such as Last used, From your role, From device time zone, From workspace policy, From previous correction, or Most common for this form.", "Show whether the adapted value applies only now, to this object, to this workspace, to this device, or as a remembered future default.", "Require review before accepting adaptive defaults that send data externally, change access, move money, alter legal state, update privacy choices, delete data, or affect other people.", "Capture explicit corrections as feedback only after making the scope clear; do not infer durable preference from one correction in a high-risk context.", "Fall back to a neutral value when signals are stale, low confidence, sensitive, conflicting, permission-restricted, or policy-managed." ], "requiredStates": [ "Neutral default state with no personal signal", "Adaptive default state with proposed value, source, scope, and reason", "User-edited state that distinguishes one-time correction from remember-for-next-time", "Remembered correction state", "Reset to system default or stop adapting state", "Low-confidence, stale, conflicting-signal, or unavailable-signal fallback state", "Policy-managed or inherited default state", "High-impact review state before submit or apply", "Mobile narrow-screen state where source and change controls remain visible" ], "interactionContract": [ "Opening the task shows the proposed value and why it was chosen before the user submits, exports, sends, schedules, or applies anything.", "Editing an adaptive default changes the current task first; remembering the correction is a separate, clearly scoped action.", "Reset restores the named default source or system value without clearing unrelated preferences, saved filters, history, or settings.", "When the source signal changes, the displayed reason and value update together or the UI asks the user to refresh before submit.", "Adaptive defaults never override explicit saved settings, consent choices, policy restrictions, or user-authored preferences without explanation.", "Dismissal, reset, correction, and remember outcomes are confirmed through visible status text and used as feedback only within the stated scope." ], "implementationChecklist": [ "Inventory each adaptable field by default source, confidence, freshness, scope, effect, risk, fallback value, and reset behavior.", "Model adaptive defaults separately from saved settings, user preferences, recommendation items, hidden autofill, validation, and required workflow state.", "Store user-facing reason metadata for each source, including recent use, role, locale, device, policy, current object, prior correction, or common value.", "Define when a correction is one-time, remembered for this field, remembered for this workflow, or ignored because the field is high risk.", "Gate high-impact adapted values behind review, confirmation, or explicit apply before side effects occur.", "Add controls for change, reset, stop adapting, remember correction, and inspect source where risk or surprise is likely.", "Test stale signals, conflicting signals, shared devices, privacy-sensitive history, policy-managed values, low confidence, mobile wrapping, keyboard flow, and screen-reader announcements." ], "commonMisuses": [ "Preselecting values to increase conversion, spend, sharing, or consent rather than to reduce honest user effort.", "Saving an adapted value as a durable setting without asking.", "Using private history, location, or team behavior as a default source on a shared or public surface without explanation.", "Showing an adaptive value with no source label, no reset path, and no distinction from a required value.", "Treating repeated corrections as user error instead of updating the default rule or asking whether to remember the change.", "Letting stale project, recipient, time zone, currency, or permission defaults survive after context changes.", "Replacing clear settings or preference controls with hidden learning behavior." ], "critiqueQuestions": [ "What exact signal or rule produced this default value?", "Can the user see whether this is a one-time starting value, a saved setting, a policy value, or a remembered preference?", "What happens when the user changes the value once, changes it repeatedly, resets it, or asks the product to stop adapting?", "Could this default send data, spend money, expose private activity, change access, or affect another person?", "Is the default source fresh, permitted, and appropriate for shared devices, shared workspaces, and sensitive categories?", "What neutral fallback appears when the signal is weak, stale, conflicting, or unavailable?" ], "relatedPatterns": [ "settings-management", "preference-center", "recommendations", "saved-filter", "recently-used", "autocomplete", "inline-validation", "review-before-submit" ], "comparisons": [ "adaptive-defaults-vs-settings-management-vs-preference-center-vs-recommendations" ], "sourceIds": [ "nng-power-of-defaults", "microsoft-human-ai-guidelines", "microsoft-windows-app-settings-guidelines", "android-developers-settings", "material-design-settings" ] }, { "id": "address-entry", "completionStatus": "complete", "name": "Address entry", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Structured postal or contact address capture flow", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Addresses vary by country, building type, delivery route, and verification data, so simplistic fields, forced lookup, or silent normalization can lose critical delivery and contact information.", "solution": "Provide address lookup where useful, always include an editable manual path, capture address parts with country-appropriate labels and validation, preserve secondary details, expose verification corrections, and submit a reviewable structured payload.", "uiGuidance": [ "Render address capture as a labelled fieldset or page section with address line, locality, region when needed, postal code, country, and an address lookup only when its coverage is clear.", "Keep lookup suggestions, manual entry fields, address-not-found status, field-specific errors, apartment or unit details, country selector, and reviewable structured summary visible as separate states rather than hiding the address in one opaque field." ], "uxGuidance": [ "Use address entry when the service needs a complete address for delivery, billing, correspondence, identity, eligibility, routing, tax, or account records and downstream systems need reliable address parts.", "Let users search, choose, edit, enter manually, change country, and keep a real but unverified address through an explicit review path when lookup or validation data is incomplete." ], "uiExamples": { "good": [ "A benefits claim asks for postcode lookup, lists matching addresses, includes Enter address manually, and then shows editable address line 1, address line 2, town or city, postcode, and country.", "A shipping checkout expands a selected suggestion into separate fields and keeps Apartment, suite, or unit editable before address validation." ], "bad": [ "A form has one full-width Address field with placeholder-only instructions and no country, postcode, apartment, or manual recovery path.", "A lookup silently chooses the first postcode match and shows only a map pin, so the user cannot confirm flat number, locality, or delivery details." ] }, "uxExamples": { "good": [ "A user enters SW1A1AA, sees several addresses, selects Flat 2, adds an organization name, and reviews the stored line, town, postcode, and country parts before continuing.", "A user with an address missing from lookup chooses manual entry, switches country, sees validation rules adapt, and can submit an unverified but reviewed address." ], "bad": [ "A user in a new building cannot proceed because the lookup cannot find the postcode and there is no manual entry option.", "A checkout removes Apartment 4B after validation and the parcel is delivered to the wrong household." ] }, "problemContext": [ "The address may be used for delivery, billing, correspondence, jurisdiction, eligibility, tax, identity proofing, emergency routing, or service availability.", "Users may have flats, suites, rural routes, military addresses, new builds, international addresses, post-office boxes, care-of details, organization names, or addresses not present in lookup data.", "Address lookup, autocomplete, geocoding, and validation services can be incomplete, region-limited, stale, or capable of suggesting corrections that still need user confirmation.", "Downstream systems often need address components for shipping labels, postal validation, fraud checks, official notices, matching, and customer support." ], "selectionRules": [ "Choose address entry when the product needs a complete postal, delivery, billing, contact, or official address rather than one short freeform value.", "Use address lookup as an accelerator for covered regions, not as the only valid path.", "Use multiple text inputs when the product needs separate address parts for validation, delivery, reporting, or integration.", "Use a textarea only when the system genuinely stores an address block and does not need separate parts.", "Use autocomplete as a lookup mechanism only when users still choose a suggestion and can edit the populated address parts.", "Use dependent fields for country-to-state or country-to-postal-code rules inside address entry, not as a replacement for the complete address flow.", "Accept common postal-code spacing, casing, and punctuation variations before showing an error.", "Make optional county, province, state, organization, and line 2 fields truly optional unless the selected country or delivery method requires them.", "Do not force UK, U.S., or domestic address structure on international users.", "Preserve secondary unit, flat, suite, room, floor, care-of, and organization information through lookup, validation, edit, and review.", "Show validation corrections as proposed changes that users can accept, edit, or override when their real address cannot be verified.", "Treat an address change as consequential when it affects delivery, eligibility, taxes, payment, identity, or official correspondence, and route it through review before submit." ], "requiredStates": [ "Initial state with country or domestic coverage explained and lookup or manual entry available.", "Lookup query state accepting postal-code spacing, casing, and common punctuation variations.", "Lookup results state showing multiple distinguishable addresses and requiring user selection.", "Address not found state with manual entry and support guidance instead of a dead end.", "Selected address state expanded into editable structured fields.", "Manual entry state with address line, town or city, region when needed, postal code, and country fields.", "Country changed state where labels, required fields, and validation rules adapt and stale region values are cleared or reviewed.", "Secondary unit present state preserving apartment, flat, suite, room, or organization details.", "Field-specific error state for missing line, locality, postal code, or unsupported country.", "Validation correction state showing suggested normalized address and original user entry.", "Override or unverified state that records user confirmation when validation data cannot prove a real address.", "Submitted structured payload state with address parts ready for review or downstream integration." ], "interactionContract": [ "Users can start with lookup or choose manual entry before providing a postal code.", "Lookup results are not committed until the user chooses a specific address.", "Selecting a suggestion populates editable fields rather than locking the address.", "Manual entry preserves any previously entered lookup query and address parts where they still apply.", "Changing country updates labels, required fields, postal-code rules, autocomplete tokens, and stale region values together.", "Validation errors identify the exact address part that needs correction and preserve all other typed fields.", "Verification suggestions are shown as review choices, not silent replacements.", "Submitting the address stores structured parts and any verification status needed for review, fulfillment, or support." ], "implementationChecklist": [ "Define which address parts are required for each supported country, delivery method, and downstream integration before designing the form.", "Use stable names and browser autocomplete tokens such as address-line1, address-line2, address-level2, postal-code, and country-name for structured fields.", "Provide an address lookup only for regions where its data is suitable, and state that coverage near the lookup control.", "Add a visible Enter manually option before and after failed lookup results.", "Do not store only the display label returned by a lookup provider; map selected or typed values into canonical address parts.", "Keep apartment, suite, flat, unit, floor, building, organization, and care-of details editable after lookup and validation.", "Normalize casing, spacing, and postal-code punctuation only when the user can still see and correct the result.", "Validate line, locality, postal code, region, and country according to the selected country and server-side rules.", "Record validation confidence, correction choice, override reason, and original user entry when address verification can affect fulfillment.", "Test keyboard use, screen reader labels, browser autofill, mobile address keyboards, long addresses, international addresses, address-not-found paths, saved drafts, browser Back, and review-before-submit flows." ], "commonMisuses": [ "Forcing every address through a domestic postcode or ZIP lookup.", "Using one single-line text input when the business process needs city, postal code, country, or delivery line separately.", "Discarding apartment, suite, flat, unit, room, floor, or organization details after lookup selection.", "Automatically choosing the first lookup result without explicit selection.", "Treating autocomplete as proof that an address is valid or deliverable.", "Silently replacing user-entered address parts with a geocoded or validated suggestion.", "Making county, state, or region required even when the selected country or postal authority does not require it.", "Rejecting valid postal-code spacing, casing, punctuation, rural route, military, or new-build addresses without override.", "Hiding manual entry until after several failed lookup attempts.", "Using placeholder text as the only field label for address lines." ], "critiqueQuestions": [ "Which downstream system needs each captured address part, and which parts are required by country?", "Can users complete the task if the lookup service is unavailable or their address is missing?", "Does the UI preserve apartment, suite, organization, rural route, or care-of details through every state?", "Are lookup suggestions distinguishable enough that users can choose the correct property?", "What happens when validation proposes a correction that conflicts with the user's real address?", "Does changing country update labels, autocomplete tokens, required fields, and validation together?", "Will the captured address be reviewed before a consequential submit action?" ], "relatedPatterns": [ "text-input", "autocomplete", "dependent-fields", "multi-step-form", "review-before-submit", "inline-validation", "error-summary" ], "comparisons": [ "address-entry-vs-text-input-vs-autocomplete-vs-dependent-fields" ], "sourceIds": [ "govuk-addresses-pattern", "uswds-address-form", "mdn-html-autocomplete-address", "google-address-validation-checkout", "usps-publication-28-addressing" ] }, { "id": "advanced-search", "completionStatus": "complete", "name": "Advanced search", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Structured query builder for fielded, Boolean, grouped, or syntax-backed searches", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to retrieve a precise set of records, messages, files, citations, issues, or code results, but ordinary keyword search and visible filters cannot express fielded conditions, Boolean logic, grouping, or expert syntax safely.", "solution": "Provide an advanced search builder or syntax surface that exposes field/operator/value clauses, Boolean joining, query preview, validation, result-count preview, history, and recovery from unsupported syntax before users commit to a search.", "uiGuidance": [ "Render advanced search as a labelled query-construction surface with visible field, operator, value, and Boolean join controls, plus a readable query preview that shows what will run.", "Show parse errors, incompatible field/operator combinations, generated syntax, result-count preview, and clear actions near the clause they affect rather than only after a failed result page." ], "uxGuidance": [ "Use advanced search when users need precise retrieval across multiple fields, date ranges, exact phrases, exclusions, functions, prior searches, or grouped Boolean conditions.", "Preserve the query while users switch between builder and raw syntax views, and provide a safe path back to basic search without silently discarding expert clauses." ], "uiExamples": { "good": [ "A research database builder lets users choose Title/Abstract, enter a term, add it with AND or OR, preview the generated query, and see a count before leaving the page.", "A work item search page shows clauses for Project equals Benefits, Status not Done, and Assignee equals current user, with the JQL preview visible below the builder.", "A mail search dialog exposes From, Subject, Has attachment, Date range, and exact phrase fields while also showing the operator query it will run." ], "bad": [ "A button named Advanced search opens the same one-line keyword input with a larger border.", "The builder shows unlabeled dropdowns for fld1, op2, and val without explaining the user-facing field or allowed values.", "A raw syntax box accepts unmatched quotes and invalid field names, then returns no results with no parse error." ] }, "uxExamples": { "good": [ "A user adds Author contains Patel OR Journal equals Pediatrics, previews 28 matches, and saves the finished query after confirming the generated syntax.", "A user enters an unsupported operator for Date and gets an inline repair message that offers Before, After, or Between without losing the date value.", "A user combines search history entries #1 AND #2, edits the query preview, and returns to results with the same clauses encoded in the URL." ], "bad": [ "A user changes AND to OR but the UI does not show grouping, causing a much broader query than intended.", "A user switches from raw syntax to form mode and the product drops the NOT clause because the form cannot represent it.", "A user previews a query count, changes the scope selector, and the stale count remains as if the same corpus was searched." ] }, "problemContext": [ "The search backend supports fielded queries, operators, Boolean logic, exact phrases, date ranges, functions, history references, qualifiers, regular expressions, or other expert syntax.", "Users need precision, repeatability, auditing, or shareability that cannot be achieved with one keyword box and a few post-result filters.", "Small syntax mistakes can return no results, too many results, or confidentially broad results, so the interface must help users inspect and repair the query." ], "selectionRules": [ "Choose advanced search when users must combine multiple search clauses before execution, such as field plus operator plus value joined by AND, OR, or NOT.", "Use a builder when users know the concepts but not the exact query syntax; use raw syntax when expert users need full control that a form cannot represent.", "Show generated syntax or a readable query preview for every builder state so users can verify field names, grouping, phrase matching, exclusions, and date ranges.", "Validate field/operator compatibility before running the query, especially for dates, numeric ranges, controlled values, functions, and exact-phrase syntax.", "Offer result-count preview or add-to-history actions when users need to compare query alternatives before opening a full result page.", "Keep search scope, filters, sort order, and saved query identity separate from advanced clauses so changing one does not silently mutate the others.", "Use filter panel instead when all criteria are visible controls that narrow an already returned result set without Boolean grouping or query syntax.", "Use saved search when the primary task is naming, sharing, rerunning, or alerting on a query that already exists.", "Use query correction when the main failure is a misspelled term, not a malformed fielded query.", "Use browse by category when users are exploring a known taxonomy rather than constructing a precise retrieval expression." ], "requiredStates": [ "Empty builder state with field, operator, value, and Boolean controls labelled.", "Partially built query state with a generated preview and clear next action.", "Valid query state with result-count preview or ready-to-search status.", "Invalid syntax state for unmatched quotes, unsupported operators, missing values, or broken grouping.", "Unsupported field/operator state with suggested alternatives.", "Builder-to-raw-syntax state that preserves representable clauses and warns about clauses the builder cannot represent.", "Search history state where previous queries can be combined or copied.", "No-results state that keeps the full query visible and offers clause-level repair.", "Deep-linked or saved state that restores clauses, raw syntax, scope, filters, and sort separately." ], "interactionContract": [ "Adding a clause appends a visible field, operator, value, and joiner to the canonical query state.", "Removing a clause updates the generated query, result-count preview, and validation state without clearing unrelated clauses.", "Changing Boolean joiners or grouping updates the preview immediately so users can see whether the query became broader or narrower.", "The product must not execute malformed syntax as a silent zero-result query when it can detect a missing value, unmatched quote, invalid field, or unsupported operator.", "Switching between builder and raw syntax preserves all query meaning that both modes can represent and explicitly warns before dropping anything.", "Submitting an advanced query includes its clauses in the URL, history entry, saved search, export, or audit trail when those features exist.", "Result-count preview belongs to the same query, scope, and filters currently shown; stale previews must be marked pending or cleared." ], "implementationChecklist": [ "Define the searchable fields, user-facing labels, allowed operators, value types, autocomplete sources, and backend syntax for each clause type.", "Model the query as structured data first, then serialize to backend syntax so the UI can validate, preview, restore, and edit clauses reliably.", "Provide explicit controls for AND, OR, NOT, grouping, exact phrase, date range, field selection, and value entry only where the backend supports them.", "Show generated syntax or a plain-language query summary before submission.", "Validate missing values, unsupported field/operator pairs, unmatched quotes, malformed dates, unsafe wildcards, and grouping errors before running.", "Add a result-count preview or add-to-history option when users compare query variants.", "Preserve raw query text when parsing fails so users can repair rather than retype.", "Keep advanced search state shareable through URL parameters, saved searches, or history when users need to resume or collaborate.", "Test expert syntax, builder mode, invalid syntax, history combination, mobile layout, keyboard order, screen reader labels, and no-results repair." ], "commonMisuses": [ "Calling a simple filter drawer advanced search without supporting clauses, Boolean logic, or query preview.", "Hiding generated syntax so users cannot inspect exactly what the builder will submit.", "Returning zero results for parse errors instead of showing the broken clause.", "Mixing search scope, filters, sort, and advanced clauses into one opaque text string with no recoverable controls.", "Using backend-only field names in the UI without user-facing labels.", "Discarding raw syntax when switching to a builder that cannot represent the query." ], "critiqueQuestions": [ "What makes this search advanced: fields, operators, Boolean logic, grouping, history, syntax, or result-count preview?", "Can users inspect the exact query before it runs?", "How does the UI distinguish malformed syntax from a valid query that has no results?", "Which field/operator combinations are allowed, and where are invalid combinations blocked or repaired?", "What happens when users switch between basic, builder, and raw syntax modes?", "Are scope, filters, sort, saved-search name, and advanced clauses stored separately enough to avoid stale counts or lost criteria?" ], "relatedPatterns": [ "basic-search", "filter-panel", "search-scope-selector", "saved-search", "saved-filter", "search-result-highlighting", "filter-chips", "no-results-recovery", "sort-controls" ], "comparisons": [ "advanced-search-vs-basic-search-vs-filter-panel-vs-search-scope-selector" ], "sourceIds": [ "pubmed-advanced-search-builder", "jira-cloud-advanced-search-jql", "github-code-search-syntax", "gmail-search-operators" ] }, { "id": "age-gate", "completionStatus": "complete", "name": "Age gate", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Eligibility and safety boundary that asks for age, age band, date of birth, verified age, or parent authorization before age-sensitive access, data collection, or content exposure", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Age-sensitive products can expose children to unsuitable content, collect child data without the right route, overcollect identity evidence, or deny legitimate users when age checks are vague, easy to game, irreversible, or blended with unrelated consent.", "solution": "Provide a risk-proportionate age gate with clear reason, threshold, input format, data-minimization copy, underage or adult outcomes, parent or guardian route, age-assurance handoff where needed, correction and appeal paths, and content protection before eligibility is known.", "uiGuidance": [ "Render the age gate as a clear eligibility boundary that states why age is needed, what threshold or age band applies, which answer format is required, and what happens next.", "Use the least intrusive age evidence that matches the risk, with separate states for declared age, age band, verified age, parent or guardian consent, underage denial, and age-assurance handoff." ], "uxGuidance": [ "Use an age gate when the product must adapt, restrict, or verify access because of age-sensitive content, child data protection, app-store rating, regulated features, or parent authorization.", "Help users recover honestly by explaining underage outcomes, correction rules, parent or guardian routes, privacy treatment of age evidence, regional thresholds, and appeal or support paths." ], "uiExamples": { "good": [ "A video service asks for date of birth before showing mature content, explains that age is needed for content eligibility, and blocks access without previewing restricted media when the user is under the threshold.", "A family app asks a child for an age band, switches to a parent-consent flow for under-13 users, and says which information is collected for the age check." ], "bad": [ "A modal asks Are you 18? with the Yes button preselected, no explanation, and mature content visible behind the overlay.", "A low-risk forum demands a government ID scan before showing a text discussion, with no data-minimization, deletion, or fallback explanation." ] }, "uxExamples": { "good": [ "A user enters a birth date, sees that they meet the age threshold for the current region, and can continue without seeing repeated checks during the same signed-in session.", "An underage user is shown a child-safe version, parent consent route, correction support, and privacy note rather than a dead end that encourages guessing a different birth date." ], "bad": [ "A user denied by an age check can immediately retry unlimited times until they guess an adult birth year.", "A parent-consent step bundles age authorization with marketing, tracking, and terms acceptance, so users cannot understand what is being authorized." ] }, "problemContext": [ "Age gates may be used for child privacy, mature content, gambling, alcohol, social features, app-store ratings, regional legal thresholds, account creation, creator content, or family settings.", "Evidence strength varies by risk: self-declared age, age band, date of birth, signed-in account age, parental consent, third-party age assurance, document check, payment-card check, or organization-managed birth date.", "The gate itself can create privacy risk when it collects exact birth dates, identity documents, parent contact information, or verification provider data that is not needed for the decision.", "Underage, unknown-age, verified-adult, parent-consent, regional-threshold, retry, and unavailable-verification outcomes need different UI states." ], "selectionRules": [ "Choose age gate when age or age band controls whether content, features, data collection, contact, commerce, or personalization is available.", "Use a declared age or age band when the risk is low and the product only needs coarse adaptation, such as child-safe defaults or content filtering.", "Use stronger age assurance when regulated content, adult features, child-data collection, payments, gambling, or platform policy requires higher confidence.", "Use parent or guardian consent when a child may continue only through an adult authorization route.", "Use consent prompt when the user is already eligible and the question is whether to allow a specific data use or action.", "Use permission request when the boundary is access to camera, location, microphone, contacts, files, or another device or account resource.", "Use sensitive-data reveal when age is already known and the user must intentionally expose hidden information.", "Use privacy settings for durable age-related defaults, child profiles, family controls, or data-sharing settings after the eligibility step." ], "requiredStates": [ "Age prompt state with reason, threshold, and input format.", "Neutral date-of-birth or age-band entry state without adult-default bias.", "Adult allowed state with session or account recognition where appropriate.", "Underage denied or adapted state that does not leak restricted content.", "Parent or guardian consent required state.", "Age assurance handoff state with provider, data, and return status.", "Data-minimization explanation state.", "Region-specific threshold state.", "Retry, correction, appeal, signed-in known age, expired session, verification unavailable, and mobile compact states." ], "interactionContract": [ "The gate appears before restricted content, restricted actions, or child-data collection are exposed.", "The UI states why age is needed and does not ask for exact birth date or identity evidence when an age band would satisfy the decision.", "Age choices are neutral: no preselected adult answer, no highlighted lie path, no mature-content preview, and no reward copy for passing.", "Underage results explain the threshold, available child-safe route, parent route, correction or appeal policy, and what data is retained or deleted.", "Parent consent, legal acceptance, marketing consent, cookie consent, and device permissions remain separate decisions with separate labels.", "Retry and correction rules prevent easy guessing while allowing genuine mistakes to be corrected through a clear route.", "Verification provider handoffs preserve return state, explain data sharing, and handle canceled, failed, unavailable, and pending results without claiming success.", "Known-age signed-in sessions avoid repeated prompts while still refreshing when policy, region, account state, or session risk changes." ], "implementationChecklist": [ "Map age-sensitive surfaces, age thresholds, regions, risk levels, required confidence, parent routes, and allowed child-safe alternatives before designing the gate.", "Choose the minimum age evidence needed for each surface and document retention, deletion, verification-provider, and audit behavior.", "Write separate copy for adult allowed, underage denied, child-safe adaptation, parent consent required, verification pending, verification failed, unavailable provider, correction, and appeal states.", "Block restricted content previews, search snippets, recommendations, notifications, and deep links until eligibility is known.", "Keep age-gate decisions separate from terms acceptance, cookie consent, marketing consent, payment consent, and device permission prompts.", "Test long localized threshold copy, low vision, keyboard entry, date formatting, screen readers, mobile numeric keyboards, regional thresholds, family accounts, and locked or managed profiles.", "Audit logs and analytics so age, birth date, parent contact, identity evidence, and failed checks are minimized and protected." ], "commonMisuses": [ "Preselecting Yes, I am over 18 or styling the adult path as the obvious safe answer.", "Showing restricted content behind or before the age gate.", "Collecting identity documents when only an age band is needed.", "Letting users retry unlimited birth dates until one passes.", "Bundling parent consent with marketing, tracking, legal acceptance, or cookie consent.", "Giving an underage user a dead end with no child-safe alternative, parent route, correction, or appeal.", "Treating a device permission denial as an age gate result.", "Remembering a failed or sensitive age answer forever without explaining retention or correction." ], "critiqueQuestions": [ "What exact content, feature, data collection, or action requires age gating?", "Which age threshold, region, and policy source controls this surface?", "Is exact date of birth necessary, or would an age band or declared age be enough?", "What does an underage user see, and does it leak restricted content?", "Can a genuine mistake be corrected without allowing unlimited guessing?", "What parent, guardian, family, or managed-account route exists?", "What age evidence is collected, where is it stored, and when is it deleted?" ], "relatedPatterns": [ "consent-prompt", "permission-request", "sensitive-data-reveal", "privacy-settings", "cookie-banner", "account-creation", "password-creation", "two-factor-authentication", "session-timeout", "security-warning" ], "comparisons": [ "age-gate-vs-consent-prompt-vs-permission-request-vs-sensitive-data-reveal-vs-privacy-settings-vs-cookie-banner" ], "sourceIds": [ "ftc-coppa-faq-age-screening", "ftc-coppa-rule", "ico-childrens-code-introduction", "google-play-families-policy", "apple-age-ratings-values" ] }, { "id": "agent-plan-preview", "completionStatus": "complete", "name": "Agent plan preview", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Pre-execution preview of an AI agent's proposed multi-step plan, tools, data access, and expected outputs", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI agents can perform multi-step work with tools and side effects, but users often see only a summary or prompt response before execution, leaving them unable to inspect the plan, correct unsafe steps, understand data access, or consent to what will happen.", "solution": "Show the proposed plan before execution with objective, steps, tools, inputs, assumptions, data access, permissions, risks, approval gates, expected outputs, and edit/run/cancel controls, then validate that the executed plan matches the reviewed plan.", "uiGuidance": [ "Render agent plan preview as a pre-run plan with objective, ordered steps, planned tools, data sources, permissions, assumptions, dependencies, approval gates, expected outputs, and controls to edit, approve, run, save, or cancel.", "Label each step's execution status before run, such as proposed, editable, fixed, optional, conditional, blocked, approval required, permission-limited, stale, or unsupported, without implying those steps have already executed." ], "uxGuidance": [ "Use agent plan preview when users need to understand and shape what an AI agent will do before it starts calling tools, changing records, sending messages, spending budget, or making external side effects.", "Keep plan preview distinct from runtime progress: before execution it should support inspection, correction, scoping, and consent; after execution starts, hand off to progress trace, tool-use visibility, approval gates, and audit trail." ], "uiExamples": { "good": [ "A sales assistant previews a six-step account-research plan with CRM lookup, web search, draft email, approval gate before send, estimated sources, and editable recipient scope.", "A support agent shows a refund investigation plan with required policy lookup, order check, customer-message draft, approval gate before refund, and blocked step for missing invoice.", "A code assistant previews files it plans to inspect, tests it plans to run, commands needing permission, and an editable step order before starting." ], "bad": [ "The UI says I have a plan and immediately starts executing without showing steps, tools, data access, or external side effects.", "A list of completed tool events is titled Plan preview, confusing proposed work with already executed work.", "A plan preview shows friendly step names but hides that one step sends customer email and another edits billing records." ] }, "uxExamples": { "good": [ "A manager removes the Send email step, narrows the data source to approved knowledge, approves the remaining plan, and sees execution start from the revised version.", "A user sees the plan is stale after changing the objective, regenerates it, and reviews the new tool list before running.", "A mobile user expands a compact plan preview, sees approval gates and permission-limited steps, and cancels before the agent starts." ], "bad": [ "Users approve a plan that says Research account but the agent also updates the opportunity stage.", "The agent executes an earlier plan after the user edited step order.", "A blocked plan still shows Run now even though a required source permission is missing." ] }, "problemContext": [ "The product can generate, infer, or assemble a plan before running an agent, workflow, tool sequence, research task, code task, content operation, or customer action.", "The plan can include tool calls, data retrieval, edits, messages, payments, deployments, scheduling, deletes, external integrations, or other side effects.", "Users need to know what the agent will do before work starts, especially when plan steps affect other people, systems, money, security, compliance, or public output.", "A plan may become stale after the user changes the objective, source scope, permissions, model instructions, selected record, or available tools.", "Some steps may be editable while others are fixed by policy, required by dependency, conditional, blocked, or gated by human approval." ], "selectionRules": [ "Choose agent plan preview when an AI agent's proposed multi-step execution needs review before it starts.", "Use task list when users are choosing from known tasks they own, not reviewing an agent-generated run plan.", "Use recommended next action when the system proposes one immediate action rather than a sequence of planned steps.", "Use human approval gate when a running automation is paused at a specific step and needs authorization to continue.", "Use step navigation when users move through a fixed human-driven sequence instead of shaping an agent run.", "Use prompt box when the main task is composing the initial request; show agent plan preview after the request produces a proposed plan.", "Use agent progress trace after execution starts and tool-use visibility while tools run; do not use plan preview as the runtime log.", "Expose planned tools, data sources, permissions, assumptions, approval gates, external side effects, and expected outputs before Run.", "Allow edits only for plan fields the system can honor, and label fixed or policy-required steps as fixed.", "Invalidate or regenerate the plan when objective, context, source scope, permissions, tool availability, or model instructions change." ], "requiredStates": [ "Draft plan state with objective, ordered steps, planned tools, and expected output.", "Editable step state with edit, remove, reorder, or scope controls where safe.", "Fixed or required step state where policy or dependency prevents editing.", "Optional and conditional step states.", "Permission-limited or missing-input blocked step state.", "Risk warning state for external side effects, destructive actions, money movement, or public communication.", "Human approval gate marker state for steps that will pause during execution.", "Plan changed, regenerated, stale, or out-of-date state after context changes.", "Run-ready state with visible run, save, cancel, and review controls.", "Run-started handoff state that preserves the reviewed plan version.", "Mobile compact plan preview state." ], "interactionContract": [ "The preview names the objective, plan version, source context, model or workflow instructions, planned tools, and expected output before run.", "Each plan step explains what the agent will do, what data it will access, what side effect may occur, and whether the user can edit it.", "Editing, removing, reordering, or scoping steps updates the plan version and validation state before execution.", "Fixed, required, permission-limited, blocked, stale, and approval-required states change available actions before Run.", "Run starts only the reviewed plan version, or warns that the plan changed and asks the user to review again.", "When execution starts, the UI preserves the reviewed plan and hands off to progress trace, tool-use visibility, human approval gate, and audit trail surfaces.", "Canceling or saving the preview does not silently run tools or commit side effects.", "Keyboard and touch users can inspect, edit, reorder where allowed, approve, run, save, or cancel without losing the plan context." ], "implementationChecklist": [ "Model plan ID, plan version, objective, source scope, assumptions, steps, dependencies, tools, permissions, expected outputs, side effects, approval gates, risk level, editability, and stale triggers as structured data.", "Separate proposed plan state from execution progress, tool-call events, human approval gates, recommended next actions, task rows, and audit history.", "Render each step with title, purpose, tool, input, output, side effect, editability, dependency, and status before run.", "Add controls for edit step, remove step, reorder step, change source scope, regenerate plan, save plan, cancel, and run reviewed plan.", "Require explicit review before high-impact steps such as sending messages, changing records, spending money, deleting data, deploying, or publishing.", "Revalidate plan version, permissions, available tools, source scope, objective, and selected record immediately before run.", "Log reviewed plan version, user edits, run-start decision, plan diff, and later execution result for audit where outcomes matter.", "Test hidden tool calls, stale plan, edited step, fixed step, optional step, conditional step, blocked permission, approval gate marker, mobile wrapping, keyboard reordering, and screen-reader status updates." ], "commonMisuses": [ "Showing a vague plan summary while hiding planned tool calls, data access, and side effects.", "Calling execution history a plan preview after the work has already run.", "Letting the agent execute a different plan than the one the user reviewed.", "Making every step editable even when policy, dependency, or safety requires fixed steps.", "Showing Run when required inputs, permissions, or approval gates are unresolved.", "Treating one recommended action as a full plan.", "Using task list row status for agent plan steps even though the agent, not the user, owns execution.", "Hiding stale-plan state after objective, context, source scope, or tool availability changes." ], "critiqueQuestions": [ "What exact plan version will run if the user selects Run?", "Can users see every planned tool call, data source, side effect, approval gate, and expected output?", "Which steps are editable, fixed, optional, conditional, blocked, or stale, and why?", "What context changes invalidate the plan before execution?", "How does the UI prove that execution followed the reviewed plan version?", "Would task list, recommended next action, human approval gate, step navigation, or progress trace solve the actual problem instead?" ], "relatedPatterns": [ "task-list", "recommended-next-action", "human-approval-gate", "step-navigation", "prompt-box", "activity-log", "confidence-uncertainty-display" ], "comparisons": [ "agent-plan-preview-vs-task-list-vs-recommended-next-action-vs-human-approval-gate-vs-step-navigation" ], "sourceIds": [ "openai-prompt-engineering-guide", "openai-conversation-state", "openai-responses-streaming-events", "microsoft-copilot-studio-prompt-assistant", "microsoft-human-ai-guidelines", "wcag-status-messages" ] }, { "id": "agent-progress-trace", "completionStatus": "complete", "name": "Agent progress trace", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Live execution trace for an AI agent or automation run after work has started", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI agents and automations can run several steps, tools, approvals, retries, and side effects after a user starts work, but ordinary spinners, progress bars, generated responses, and audit logs often fail to show the live run state users need to monitor, interrupt, or trust the process.", "solution": "Show a live ordered trace tied to one run and reviewed plan version, with current step, completed steps, queued work, tool and gate milestones, elapsed state, retry and blocked recovery, final outcome, and a handoff to detailed tool visibility or audit history when needed.", "uiGuidance": [ "Render an agent progress trace as a live, ordered run timeline with run ID, plan version, current step, queued steps, active tool or task, elapsed time, last event time, step status, blocked gates, retry state, and final outcome.", "Separate proposed plan, active execution, tool details, generated output, human approval checkpoints, and durable audit records so users can tell what is planned, what is currently running, what already happened, and what still needs attention." ], "uxGuidance": [ "Use agent progress trace when an AI agent or automation has started multi-step work and users need to monitor progress, intervene on stalls or gates, understand partial completion, and know whether the reviewed plan is still being followed.", "Keep the trace useful during uncertainty: show pending, running, waiting, blocked, retried, skipped, failed, cancelled, completed, and handed-off states without pretending every step is measurable or exposing unsafe private tool payloads." ], "uiExamples": { "good": [ "An account research agent trace shows Run A-204, reviewed plan P-18, completed CRM lookup, active policy search, queued draft email, approval gate pending before send, elapsed time, and a View tool details control.", "A code assistant run shows inspected files, running tests, retrying one command after a timeout, blocked permission for a write command, and a final handoff to results and audit.", "A support automation trace shows customer lookup complete, refund eligibility failed, fallback message drafting skipped, and the run ending with a recoverable error." ], "bad": [ "A spinner says Working on it while an agent calls several tools with no step identity, elapsed time, blocked state, or recovery path.", "A trace displays raw tool JSON and private tokens as the only progress feedback.", "The UI marks a run complete when generated text appears even though one queued side-effect step is still pending." ] }, "uxExamples": { "good": [ "A user watches the active step move from searching policies to drafting the email, opens the blocked permission item, grants access, and sees the run continue from the same step.", "A manager sees that a run is waiting at a human approval gate, opens the gate, rejects the email-send step, and the trace records the stopped outcome.", "On mobile, a user sees a compact trace with current step, last completed step, next blocked step, elapsed time, and a details path without losing the run." ], "bad": [ "Users cannot tell whether the agent is stuck, waiting for approval, or finished because all states use the same animated progress label.", "A trace restarts from the top after a retry and makes users think earlier completed steps ran twice.", "A cancelled run disappears from the workspace before users can see which steps completed and which side effects happened." ] }, "problemContext": [ "The product starts an AI agent, workflow, tool sequence, background automation, code task, research task, content operation, support action, deployment, or customer-facing side effect.", "The run can include generated text, tool calls, data retrieval, approval gates, retries, skipped steps, blocked permissions, failures, cancellations, and final artifacts.", "Users need to know whether the agent is still working, waiting, blocked, retrying, safe to leave, safe to cancel, or finished.", "Some details may be sensitive or too verbose for the trace and should move to tool-use visibility, logs, or audit history instead of overwhelming the progress view.", "The trace may start from a reviewed agent plan preview and later produce durable audit records after completion." ], "selectionRules": [ "Choose agent progress trace when an agent or automation run has started and users need live status across multiple steps or tools.", "Use agent plan preview before execution starts; use agent progress trace after Run begins.", "Use streaming response when the primary observable work is generated output arriving in chunks, not a multi-step run lifecycle.", "Use activity log when users need retained investigative records after the run, not live execution monitoring.", "Use progress bar when one bounded system operation has measurable percent, byte, row, or item progress.", "Use human approval gate when the run is paused at one authorization checkpoint; keep the trace responsible for showing where that gate sits in the larger run.", "Use tool-use visibility when users must inspect exact tool names, inputs, outputs, permissions, or payloads; keep the progress trace as the run-level timeline.", "Show current step, last completed step, queued next step, blocked step, retry, skip, cancel, and final outcome states before adding decorative motion.", "Preserve trace identity across refresh, route change, mobile handoff, retry, cancellation, and final result.", "Do not title raw logs, hidden tool events, or post-hoc audit rows as a progress trace unless they support live run monitoring." ], "requiredStates": [ "Run started state tied to run ID, plan version, objective, and user who started the run.", "Queued, active, completed, skipped, waiting, blocked, retrying, failed, cancelled, and completed run states.", "Current step state with label, purpose, owner, elapsed time, and last event time.", "Tool call pending, tool call running, tool call succeeded, tool call failed, and tool detail available states.", "Human approval gate waiting state linked to the canonical gate.", "Permission blocked, missing input, rate limited, offline, timeout, stale plan, and fallback route states.", "Partial result and generated output available states without confusing output streaming with step progress.", "Run resumed, retried, cancelled, rolled back, and final handoff to result or audit states.", "Mobile compact trace state with current, previous, next, blocked, and final outcome visibility." ], "interactionContract": [ "The trace belongs to one run ID, reviewed plan version, objective, actor, start time, current state, and final state.", "Each trace item identifies a step or event, its status, time, owner, and whether details are available, hidden, redacted, blocked, or unsafe to expose.", "The trace differentiates queued, active, completed, failed, skipped, blocked, waiting, cancelled, and final states in text, not color alone.", "Opening step details reveals scoped information for that step and does not replace the trace with an unfiltered raw log.", "Cancel, stop, retry, resume, grant permission, open gate, view details, and view audit actions only appear when the run state supports them.", "Retries append or mark retry attempts without making completed earlier steps look newly completed unless they actually reran.", "If the run diverges from the reviewed plan, the trace shows the divergence, reason, and whether user review or approval is required.", "When the run completes, fails, or is cancelled, the trace remains available long enough to inspect outcome and links to durable audit or activity history." ], "implementationChecklist": [ "Model run ID, plan version, objective, started by, start time, step IDs, event IDs, statuses, timestamps, active tool, queued work, blockers, retry attempts, cancellation state, final outcome, and audit link as structured data.", "Separate trace events from plan-preview records, streamed response chunks, raw tool payloads, human approval gate decisions, activity-log records, and telemetry events.", "Render a stable ordered list or timeline with active item, completed items, queued items, gates, blockers, retry attempts, final state, and details disclosure.", "Add actions for stop, cancel, retry failed step, resume, grant permission, open approval gate, view tool details, copy run ID, view result, and open audit according to state.", "Throttle live updates and assistive announcements to meaningful milestones rather than every low-level event.", "Redact or summarize sensitive tool inputs, private data, secrets, and payloads while linking to permissioned detail surfaces where appropriate.", "Persist the trace through refresh and background execution, and reconcile client state with canonical server run state.", "Test slow steps, duplicate events, out-of-order events, retry after failure, blocked permission, missing input, approval gate wait, cancelled run, stale plan divergence, final audit handoff, mobile wrapping, keyboard details, and screen-reader updates." ], "commonMisuses": [ "Using one spinner or vague Thinking label for a multi-step agent run.", "Showing a progress bar percentage when the run has no honest measurable total.", "Dumping raw tool logs instead of a user-readable run trace.", "Calling a pre-run plan preview a progress trace before any work has started.", "Calling a post-run activity log a progress trace when users cannot monitor or intervene.", "Hiding approval gates, permission blockers, retries, skipped steps, and partial failures.", "Letting duplicate or out-of-order events make steps appear to run twice.", "Removing the trace immediately after failure, cancellation, or completion." ], "critiqueQuestions": [ "What run ID, plan version, and objective does this trace represent?", "Can users tell what is queued, active, completed, blocked, failed, skipped, cancelled, and final?", "Which tool details are safe to show inline, and which belong in tool-use visibility or audit history?", "What actions are available when the run stalls, waits for approval, needs permission, fails, or diverges from the reviewed plan?", "How does the trace handle duplicate, delayed, out-of-order, redacted, or retried events?", "Would agent plan preview, streaming response, progress bar, human approval gate, activity log, or tool-use visibility better fit the actual need?" ], "relatedPatterns": [ "agent-plan-preview", "streaming-response", "activity-log", "progress-bar", "human-approval-gate", "timeline", "loading-spinner", "source-grounding-display", "confidence-uncertainty-display" ], "comparisons": [ "agent-progress-trace-vs-agent-plan-preview-vs-streaming-response-vs-activity-log-vs-progress-bar-vs-human-approval-gate" ], "sourceIds": [ "openai-responses-streaming-events", "openai-streaming-responses", "w3c-aria-log-role-chat", "wcag-status-messages", "microsoft-human-ai-guidelines", "carbon-progress-bar-component" ] }, { "id": "ai-agent-acts-without-approval", "completionStatus": "complete", "name": "AI agent acts without approval", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Anti-pattern for agentic side effects executed before human authorization", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI agents can execute real-world side effects before users understand or authorize them, especially when plan previews, progress traces, chat messages, or notifications blur proposed actions with completed actions.", "solution": "Treat unapproved agent execution as an anti-pattern: classify high-impact steps, pause them at authorization gates, show exact payload and consequences before execution, validate approver eligibility and freshness, and provide stop, rollback, audit, and escalation paths when approval was bypassed.", "uiGuidance": [ "Do not show an agent as merely thinking, drafting, or preparing when it has already sent, changed, purchased, deployed, revoked, deleted, or externally committed something.", "Before a high-impact agent step can run, show the proposed action, target, payload, tool, approver rule, side effect, risk, expiry, and explicit approve, edit, reject, cancel, or stop controls." ], "uxGuidance": [ "Protect users from surprise agent side effects by separating proposed work from executed work, pausing risky steps, and requiring authorization that is valid only for the displayed payload.", "If an agent already acted without approval, surface the executed action, rollback or recovery path, audit trail, affected target, and reason the approval gate was bypassed instead of presenting the result as routine progress." ], "uiExamples": { "good": [ "A support agent pauses before issuing a refund, shows customer, order, amount, policy source, approver role, and Approve refund, Edit amount, Reject, and Stop run controls.", "A sales agent drafts a customer email but labels the send step Requires approval and keeps Send disabled until the reviewer opens the exact message and recipient list.", "A deployment agent reaches production release, shows environment, commit, checks, required reviewer, self-review block, timeout, and the job that will resume after approval." ], "bad": [ "A chat message says I handled it and reveals the agent already issued a refund without any review screen.", "The plan preview says Draft email, but the agent also sends it to customers when the user taps Run.", "An approval notification appears after the database change already executed, making approval only a recordkeeping step." ] }, "uxExamples": { "good": [ "A manager sees the agent is armed to change account access, edits the target group, approves the revised payload, and the run resumes only that step.", "A user rejects a customer-email gate, the run stops the send step, keeps the draft visible, and records the rejection reason.", "A mobile approver opens the canonical gate from a notification and the UI refuses approval because the payload changed after the notification was sent." ], "bad": [ "A user asks an agent to research an account and later discovers it changed the opportunity stage.", "A reviewer approves a stale email notification and the agent applies the decision to a different customer state.", "The activity log shows an unauthorized access change but offers no rollback, cancel, report, or escalation path." ] }, "problemContext": [ "The agent can call tools, send external messages, spend money, issue refunds, change access, update customer records, deploy code, delete data, submit forms, publish content, or trigger downstream workflows.", "The UI may describe the agent as preparing, researching, drafting, or working while side effects are already committed.", "Users may have approved a broad prompt, plan, or recommendation but not the exact payload, target, timing, or downstream consequence that executed.", "Approval can be required by policy, confidence, source gaps, cost, permissions, customer impact, legal risk, security risk, or separation of duties.", "The agent may need different treatment for safe read-only steps, reversible draft steps, gated side-effect steps, emergency bypass, and post-action recovery." ], "selectionRules": [ "Flag this anti-pattern when an AI agent or automation executes a high-impact side effect without showing and requiring approval for the exact action and payload first.", "Flag it when a broad Run, Continue, or Looks good control authorizes hidden tool calls, sends, edits, purchases, deletes, deployments, or access changes.", "Use human approval gate for the corrected runtime checkpoint when the agent is paused before an armed step and needs an eligible human decision.", "Use agent plan preview when users need to inspect proposed steps before execution starts; plan review does not authorize unlisted future side effects.", "Use agent progress trace when users need live monitoring after execution starts; progress visibility does not replace approval for risky steps.", "Use tool-use visibility when users must inspect exact tool names, inputs, outputs, permissions, and payloads; tool detail supports approval but is not the gate itself.", "Use dangerous-action review when a single high-impact manual action needs payload review outside an agent run.", "Use automation rule builder when users are authoring reusable future behavior rather than approving one armed runtime step.", "Allow low-risk read-only agent steps to run without approval only when the UI clearly scopes them as read-only and they cannot create external side effects.", "If emergency bypass is allowed, show who can bypass, why, what will execute, how rollback works, and how the bypass is audited." ], "requiredStates": [ "Read-only step allowed state with no external side effect.", "Approval required before side effect state.", "Payload preview state with target, action, tool, data, cost, recipients, environment, or access scope.", "Eligible approver and self-review blocked state.", "Approve and resume state that revalidates the displayed payload.", "Edit before approve state that creates a new payload version.", "Reject, cancel, stop run, and rollback available states.", "Stale approval refused state for changed input, target, source, model, policy, or payload.", "Emergency bypass state with elevated permission and required reason.", "Bad silent execution, broad consent, hidden tool call, post-action approval, stale approval, self-approval, no rollback, and audit-only states." ], "interactionContract": [ "The agent distinguishes read-only steps, draft steps, reversible local changes, and external side-effect steps before execution.", "Side-effect steps cannot run until the interface shows the action, target, payload version, tool, approver rule, risk, and resume consequence.", "A broad instruction, plan acceptance, confidence score, progress trace, or notification does not authorize hidden future side effects.", "Approval is valid only for the displayed payload and expires when target, input, source, model, policy, tool permission, or threshold changes.", "Approve resumes only the named gated step unless the UI explicitly lists additional authorized steps.", "Reject, cancel, edit, stop, rollback, and escalation outcomes leave the run in a named state with reason and recovery path.", "Post-action audit records must say the action already happened and provide rollback, report, or escalation controls when possible.", "The audit trail records what the user saw before approval, who approved or bypassed, what executed, and whether recovery was attempted." ], "implementationChecklist": [ "Inventory all agent tools and mark read-only, draft-only, reversible, externally visible, money-moving, access-changing, destructive, deployment, publication, and customer-impact steps.", "Define which steps require approval by policy, risk, confidence, source status, cost, data sensitivity, target environment, recipient scope, or separation-of-duties rule.", "Render proposed side-effect steps with payload preview, diff, target, tool, evidence, risk, approver eligibility, timeout, and downstream consequence before execution.", "Require explicit approve, edit, reject, cancel, stop, or bypass controls for gated steps, and block self-approval where policy requires independent review.", "Revalidate payload hash, target, source freshness, model version, policy version, approver role, and tool permission immediately before resuming the gated step.", "Separate plan preview, progress trace, tool-use visibility, approval gate, dangerous-action review, and audit trail data so users can tell proposed, armed, executing, and completed actions apart.", "Provide post-action recovery for bypassed or unauthorized execution: stop future steps, rollback, revoke, notify affected users, report incident, and inspect audit trail.", "Test hidden side-effect tools, broad prompt consent, stale notification approval, self-approval, edited payload, emergency bypass, failed resume, rollback, mobile approval, keyboard flow, and high-zoom payload wrapping." ], "commonMisuses": [ "Treating Run agent as permission to execute every hidden side-effect step.", "Sending a customer message or issuing a refund while the UI still says the agent is drafting.", "Showing an approval card after the tool already executed.", "Letting the requester approve their own high-impact automation step.", "Using high confidence, source grounding, or a green progress state as a substitute for authorization.", "Hiding the exact tool input, recipient list, amount, access target, deployment environment, or deletion scope.", "Providing no stop, rollback, cancel, report, or escalation path after unauthorized execution." ], "critiqueQuestions": [ "Which agent steps are read-only, draft-only, reversible, externally visible, destructive, money-moving, access-changing, or customer-impacting?", "What exact action, target, payload, tool, and version will execute after approval?", "Can the user distinguish proposed work, armed gated work, running work, completed work, and audit history?", "Who is eligible to approve, who is blocked from self-review, and what happens if the approval becomes stale?", "What recovery exists if the agent already acted without approval?", "Would human approval gate, agent plan preview, agent progress trace, tool-use visibility, dangerous-action review, or automation rule builder solve the actual problem?" ], "relatedPatterns": [ "human-approval-gate", "agent-plan-preview", "agent-progress-trace", "tool-use-visibility", "dangerous-action-review", "automation-rule-builder", "confidence-uncertainty-display", "ai-output-audit-trail" ], "comparisons": [ "ai-agent-acts-without-approval-vs-human-approval-gate-vs-agent-plan-preview-vs-agent-progress-trace-vs-tool-use-visibility-vs-dangerous-action-review" ], "sourceIds": [ "microsoft-agent-responsible-ai", "microsoft-human-ai-guidelines", "github-actions-deployment-protection-rules", "microsoft-power-automate-approvals", "servicenow-ask-for-approval-action", "openai-conversation-state", "wcag-status-messages" ] }, { "id": "ai-answer-without-sources", "completionStatus": "complete", "name": "AI answer without sources", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Unsourced AI answer anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Users receive a confident-looking AI answer that includes factual claims or recommendations but no usable source, source scope, retrieval status, unsupported-claim label, or verification path.", "solution": "Treat unsourced AI answers as an anti-pattern for evidence-dependent tasks: show citations or source grounding when evidence was used, show not searched or no supporting source found when evidence is absent, and gate copy, publish, apply, or external use until users can verify or explicitly continue without sources.", "uiGuidance": [ "Do not present evidence-dependent AI answers as final when no citations, grounding, source scope, or no-source status is visible.", "Show sourced, pending, not searched, retrieval failed, no supporting source found, permission-limited, and draft-only states beside the answer and preserve them through copy, apply, export, and handoff actions." ], "uxGuidance": [ "Help users know whether they can rely on an AI answer by exposing its evidence state before they act.", "When sources are missing, provide recovery routes such as search sources, upload documents, choose source scope, retry retrieval, request access, ask a human, or continue only as a draft." ], "uiExamples": { "good": [ "A support answer says Not sourced: source search was not run, offers Search help center and Ask human, and keeps Send to customer disabled until a source or override is chosen.", "A policy summary says No supporting source found for the refund exception claim and links to the unsupported claim before copy.", "A generated draft from model knowledge is labelled Draft without sources and copied with that label attached." ], "bad": [ "A confident policy answer has no citations, no source scope, and no explanation that retrieval was skipped.", "A retrieval failure is hidden and the model returns an answer from prior knowledge.", "A Learn more list appears under the answer and looks like evidence even though none of the links were used." ] }, "uxExamples": { "good": [ "A user sees that a customer-facing answer is unsourced, runs source search, reviews one unsupported claim, then sends only after the source state changes.", "A reviewer copies an answer as a draft and the copied text retains Not sourced so it cannot be mistaken for verified guidance.", "A user with missing document permission requests access rather than trusting an incomplete answer." ], "bad": [ "A user sends an unsourced renewal-policy answer to a customer because the fluent answer looked complete.", "A user assumes related links are citations and misses that the answer was never grounded in the policy source.", "A mobile user cannot see that copy is gated because the no-source warning is hidden below the fold." ] }, "problemContext": [ "The answer may be generated from web search, file search, enterprise knowledge sources, selected documents, uploaded files, chat history, model prior knowledge, tool outputs, or no retrieval at all.", "The answer contains claims users may rely on for policy, compliance, support, operations, money, safety, medicine, law, customer communication, product decisions, or public publication.", "The system may have skipped retrieval, failed retrieval, hidden permission-limited sources, mixed model knowledge with retrieved evidence, or returned a no-source answer after a source-backed request.", "Users need to know whether the answer is sourced, not searched, unsupported, permission-limited, stale, or draft-only before acting on it." ], "selectionRules": [ "Flag this anti-pattern when an AI answer makes evidence-dependent claims and provides no source link, citation marker, grounding panel, source scope, or verification action.", "Flag it when the UI presents a polished answer as final even though source search was not run, failed, or returned no supporting source.", "Use source grounding display when the answer needs answer-wide source scope, searched/retrieved/used evidence, and unsupported-claim coverage.", "Use citation display when individual claims need inline citation markers and source previews.", "Use confidence / uncertainty display when the issue is model reliability or calibrated uncertainty; confidence is not a replacement for sources.", "Use streaming response when source events are still pending during generation; keep the answer labelled pending until sources settle.", "Use correction feedback when users need to report that an answer is wrong, unsupported, or uses the wrong source after the answer is shown.", "Use AI limitation onboarding when users need upfront expectations about what the system can and cannot source before they ask.", "Do not show related links, suggested reading, or a generic Learn more list as if those links were evidence used by the answer.", "If no source is available, label the answer as not sourced, not searched, no supporting source found, or draft from model knowledge, and provide a path to search, upload, cite, ask a human, or continue with explicit risk." ], "requiredStates": [ "Sourced answer state with citations or grounding visible.", "Not searched state where retrieval was not run and the answer is labelled accordingly.", "No supporting source found state with unsupported claims separated from answer text.", "Retrieval failed state with retry source search path.", "Permission-limited source state that explains an access gap without pretending the answer is verified.", "Pending source search state while streaming or retrieval is still resolving.", "Draft from model knowledge state that blocks source-dependent apply or publish actions.", "User-provided source needed state with upload, connect, or choose source action.", "Human verification state for high-stakes answers that remain unsourced.", "Copy/apply gated state when sources are missing.", "Bad confident answer state with no source route.", "Bad related links as evidence state.", "Bad hidden retrieval failure state.", "Bad permission omission state.", "Bad citation promised but missing state.", "Bad stale source claim state.", "Bad copy final state that strips no-source warning." ], "interactionContract": [ "Evidence-dependent answers must expose whether sources were searched, retrieved, used, unavailable, permission-limited, failed, or not required.", "Copy, publish, apply, send, export, and automate controls must preserve or surface no-source status when the answer lacks evidence.", "No-source answers must offer at least one recovery path when possible: search sources, choose corpus, upload file, request access, retry retrieval, ask a human, or mark as draft.", "When users intentionally continue without sources, the UI records the no-source state and does not convert it into a verified answer.", "If sources arrive after streaming, answer status updates from pending to sourced, unsupported, permission-limited, or no supporting source found.", "Related links are clearly separated from evidence used by the answer.", "Accessible names and status text include the source state, not only a visual badge." ], "implementationChecklist": [ "Track answer provenance as structured state: source mode, source scope, retrieval status, used evidence, unsupported claims, permissions, freshness, and no-source reason.", "Render no-source and not-searched labels beside the answer summary, not only in hidden metadata or logs.", "Provide search, retry, source selection, upload, request access, ask human, and draft-only actions when those routes can change the source state.", "Block or warn before copy, publish, apply, send, or automate when evidence-dependent claims remain unsourced.", "Preserve source state in copied text, exports, audit logs, handoffs, and regenerated answer versions.", "Do not replace missing sources with confidence percentages, related links, generic disclaimers, or decorative citation numbers.", "Test no retrieval, retrieval failure, zero results, permission-limited sources, stale sources, streaming pending, mobile layout, high zoom, keyboard flow, and screen reader status." ], "commonMisuses": [ "Showing a polished answer with no citations or grounding after the user asked for a policy-backed answer.", "Adding a generic disclaimer while still letting users copy or send the unsourced answer as if it were verified.", "Hiding retrieval failure and returning an answer from model memory.", "Showing related links below the answer without saying they were not used as evidence.", "Promising citations in the prompt or product copy and then returning an answer with no source state.", "Letting regenerated or edited output drop citations without changing the answer status.", "Treating high confidence as a substitute for source evidence." ], "critiqueQuestions": [ "Which claims in this answer require evidence before users act?", "Were sources searched, retrieved, used, unavailable, permission-limited, or not searched?", "Can users tell whether the answer came from retrieved evidence or model prior knowledge?", "What happens when retrieval fails or finds no supporting source?", "Does copy, publish, apply, or send preserve the no-source warning?", "Would source grounding display, citation display, confidence / uncertainty display, streaming response, or correction feedback be the precise pattern?" ], "relatedPatterns": [ "source-grounding-display", "citation-display", "confidence-uncertainty-display", "streaming-response", "correction-feedback", "ai-limitation-onboarding", "chat-interface", "related-links" ], "comparisons": [ "ai-answer-without-sources-vs-source-grounding-display-vs-citation-display-vs-confidence-uncertainty-display-vs-streaming-response-vs-correction-feedback" ], "sourceIds": [ "openai-web-search-citations", "openai-file-search-citations", "openai-retrieval", "microsoft-copilot-studio-knowledge-sources", "microsoft-365-copilot-linked-citations", "microsoft-365-copilot-web-references", "wcag-status-messages" ] }, { "id": "ai-confidence-shown-as-fake-precision", "completionStatus": "complete", "name": "AI confidence shown as fake precision", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Anti-pattern for uncalibrated or over-exact AI confidence displays", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Users over-trust AI output when the interface presents raw, uncalibrated, stale, or out-of-scope model scores as exact confidence percentages, decimals, probabilities, or certainty levels.", "solution": "Treat fake precision as an anti-pattern: remove misleading exactness, disclose calibration status and operating scope, show qualitative uncertainty or calibrated ranges only when valid, and gate high-impact actions with review, source verification, missing-input recovery, or fallback routes.", "uiGuidance": [ "Do not render model uncertainty as exact percentages, decimals, star ratings, gauges, or ranked certainty labels unless the score is calibrated, scoped, fresh, and tied to a decision threshold users can understand.", "When calibration is unavailable, show a qualitative reliability state, uncertainty reason, missing input, stale model, out-of-distribution, or review-required label instead of a probability-looking number." ], "uxGuidance": [ "Protect users from automation bias by making confidence limits actionable: explain what the number means, where it is valid, what threshold changes the workflow, and what safe action follows.", "If the displayed number cannot support a real decision, replace it with review, source verification, collect more input, explain uncertainty, or hold-for-human paths before apply, send, approve, deny, or publish." ], "uiExamples": { "good": [ "A claim classifier says Calibration unavailable, explains that the model is outside its monitored scope, hides the 0.873 raw score, and routes to reviewer triage.", "A support reply shows Medium confidence, calibrated range 71 to 78 percent, review threshold 80 percent, source coverage separate, and Apply disabled until review.", "A document extraction field says Low confidence because the scan is blurred, shows the required invoice field is missing, and offers Open source page instead of a precise percentage." ], "bad": [ "A generated legal answer says 97.42 percent confident with no calibration scope, threshold, freshness, evidence, or review path.", "A red-yellow-green confidence meter labels an AI decision as 0.91 certain even though the model has never been calibrated for that task.", "A stale confidence score remains on a regenerated answer after the source, model, and threshold changed." ] }, "uxExamples": { "good": [ "A reviewer sees that exact confidence is unavailable, opens the uncertainty reason, requests missing evidence, and avoids auto-denying a claim.", "A user edits the prompt and the prior confidence disappears until the system recomputes the scoped reliability state.", "A mobile user sees the review threshold and calibration caveat before the primary action, so the exact-looking number does not drive the decision." ], "bad": [ "Users trust a confident-looking 98.7 percent label and send an unsupported answer to a customer.", "A team treats ranking decimals as probability of correctness and automates approvals below the review threshold.", "A user cannot tell that the number is a raw model score, not a calibrated probability, source proof, or policy permission." ] }, "problemContext": [ "The UI displays model output, retrieval ranking, classifier score, extractor score, recommendation rank, generated-answer score, or risk estimate as if it were a calibrated probability.", "The number may come from a raw model logit, internal rank, heuristic score, embedding similarity, confidence token, stale assessment, or population-level metric that does not map to user-facing correctness.", "Users may act on the number by approving, denying, sending, publishing, escalating, triaging, applying an extraction, or trusting a generated answer.", "The product may need uncertainty, threshold, source grounding, warning text, or review controls, but the exact-looking number is doing that work instead." ], "selectionRules": [ "Flag this anti-pattern when an AI or automated surface shows a precise score without calibration scope, decision threshold, freshness, uncertainty reason, or safe next action.", "Flag it when decimals, percentages, color bands, stars, gauges, or ranking scores imply correctness that the system cannot honestly support.", "Use confidence / uncertainty display for the corrected pattern when calibrated reliability, review threshold, reason, stale state, and apply gating can be shown honestly.", "Use source grounding display when users need evidence coverage; confidence is not source proof.", "Use citation display when users need claim-level source inspection instead of a reliability score.", "Use meter only for a read-only bounded scalar value with a meaningful range, not a raw AI certainty score.", "Use warning text when the issue is a known severe consequence before an action rather than uncertain model reliability.", "If confidence cannot be calibrated for this task, show qualitative states such as calibration unavailable, insufficient evidence, out-of-distribution, stale model, or review required.", "If a numeric range is valid, show it as an approximate calibrated range with scope, threshold, and freshness rather than an exact-looking single value.", "Do not let high precision unlock copy, apply, approve, deny, send, or automate without matching threshold rules and audit state." ], "requiredStates": [ "Raw score hidden state where an internal score is withheld from the user-facing decision.", "Calibration unavailable state with qualitative reliability label and review path.", "Calibrated range state with task scope, review threshold, and caveat.", "Insufficient evidence state where no numeric confidence is shown because required inputs are missing.", "Out-of-distribution state where confidence is invalid outside monitored scope.", "Stale score state after model, threshold, source, input, or policy changes.", "Threshold changed state that invalidates an old allow or block decision.", "Ranking score not probability state for retrieval or recommendation lists.", "Bad exact percent, decimal certainty, color-only precision, gauge precision, hidden caveat, confidence as source proof, stale precision, and copied score states." ], "interactionContract": [ "The interface distinguishes raw internal scores from user-facing calibrated confidence.", "A visible confidence value must name its calibration scope, task population, threshold, freshness, and action consequence.", "Uncalibrated, stale, out-of-distribution, insufficient, or ranking-only scores are replaced with qualitative state and recovery actions.", "Changes to prompt, source scope, input, model version, threshold, or policy invalidate the visible score before users act.", "Copy, export, audit, and handoff preserve calibration caveats or omit raw scores that would mislead downstream users.", "High-impact actions below threshold or outside calibration scope route to review, source verification, collect-more-input, escalation, or fallback.", "Accessible labels state uncertainty meaning in words rather than relying on numeric precision, color, or gauge fill." ], "implementationChecklist": [ "Trace each displayed confidence number to its source: calibrated probability, raw score, rank, similarity, heuristic, model confidence, or stale stored value.", "Define whether the number is valid for the current task, population, model version, input quality, source scope, threshold, and consequence.", "Hide or relabel raw scores that cannot be interpreted as user-facing probability.", "Model calibration unavailable, insufficient evidence, out-of-distribution, stale model, threshold changed, ranking-only, copied-score, and review-required states.", "Place uncertainty reason, threshold, freshness, and gated action near the AI output before any commit control.", "Prevent copy, apply, approve, deny, send, publish, or automation from stripping calibration caveats.", "Test exact percent, decimal score, color-only score, gauge score, stale score, source-proof misuse, mobile layout, keyboard flow, high zoom, and status messaging." ], "commonMisuses": [ "Formatting an uncalibrated model score as 97.42 percent sure.", "Showing 0.873 certainty without saying it is a raw rank, similarity, or heuristic score.", "Using a confidence meter or color band to imply correctness without threshold, calibration, or explanation.", "Keeping old confidence after the user edits input, changes source scope, or the model updates.", "Treating confidence as source evidence, policy approval, legal correctness, or permission.", "Copying the exact-looking score into an audit note without the caveat that made it interpretable." ], "critiqueQuestions": [ "What exactly does this number measure, and can users interpret it as probability of correctness?", "Is the score calibrated for this task, population, model version, data source, threshold, and current input?", "Would a qualitative uncertainty state be more honest than a precise percentage or decimal?", "What changes invalidate the displayed score before the user acts?", "Does the UI separate confidence from source grounding, citations, warning text, policy permission, and severe consequence copy?", "Can the user review, verify sources, collect missing input, escalate, or fallback when confidence is unavailable or below threshold?" ], "relatedPatterns": [ "confidence-uncertainty-display", "source-grounding-display", "citation-display", "ai-answer-without-sources", "meter", "warning-text", "human-approval-gate", "correction-feedback" ], "comparisons": [ "ai-confidence-shown-as-fake-precision-vs-confidence-uncertainty-display-vs-meter-vs-source-grounding-display-vs-warning-text-vs-human-approval-gate" ], "sourceIds": [ "google-pair-explainability-trust", "microsoft-human-ai-guidelines", "microsoft-azure-openai-transparency-note", "mdn-aria-meter-role", "wcag-status-messages" ] }, { "id": "ai-limitation-onboarding", "completionStatus": "complete", "name": "AI limitation onboarding", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "First-use or new-feature onboarding that teaches AI capabilities, limits, uncertainty, user control, and recovery paths", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Users may form fragile mental models of AI features, over-trust confident output, under-trust useful assistance, expect human-like understanding, disclose too much, or abandon the feature after failures when limits are not explained early.", "solution": "Provide a concise onboarding experience that sets the AI's benefit, capability boundary, data scope, uncertainty behavior, review requirement, feedback path, and non-AI fallback before users rely on the feature.", "uiGuidance": [ "Render AI limitation onboarding as a short benefit-and-boundary surface that names what the AI can help with, what it cannot do, what data it uses, where uncertainty appears, when human review is needed, and how to recover if the AI fails.", "Use concrete examples, safe trial actions, capability cards, limitation chips, fallback buttons, feedback links, and review gates rather than long legal disclaimers or human-like claims." ], "uxGuidance": [ "Use AI limitation onboarding when users are first encountering an AI feature, a changed AI capability, or an agent with enough autonomy that users may over-trust, under-trust, anthropomorphize, or misuse it.", "Calibrate trust before risky use: let users try a reversible example, see what inputs improve the AI, understand confidence and source limits, choose manual fallback, and know which outputs require review." ], "uiExamples": { "good": [ "A contract assistant opens with I can summarize clauses and flag missing dates, but I may miss legal nuance; review source text before sending, then offers a sample contract to try safely.", "A support triage agent shows Can do, Cannot do, Needs your review, Data used, and Recovery path cards before the first automated routing suggestion." ], "bad": [ "A chat widget says Meet your expert teammate and starts answering customer questions with no limits, source scope, review warning, or fallback.", "A modal lists every model policy in dense text, blocks the task, and gives no safe first action or route to recover when output is wrong." ] }, "uxExamples": { "good": [ "A new analyst sees that the AI can draft summaries from selected reports, cannot verify private spreadsheets unless attached, should not be used as final approval, and can be corrected after each answer.", "A returning user sees re-onboarding after a capability change: the assistant now uses ticket history, still cannot access billing notes, and high-impact replies require human review." ], "bad": [ "A user assumes the assistant has read all company documents because onboarding says Ask me anything, then acts on an answer missing restricted policy files.", "A user stops using the AI after one failure because the product never explained uncertainty, feedback, or manual fallback." ] }, "problemContext": [ "The feature uses AI, machine learning, recommendations, prediction, natural-language generation, tool use, or agent behavior that users may misunderstand.", "Users need to know what the AI can do, what it cannot do, what data it has and lacks, what it may get wrong, and what responsibility remains with them.", "The product is anthropomorphic, conversational, autonomous, personalized, safety-sensitive, or likely to invite Ask me anything expectations.", "The AI may fail because of missing data, low confidence, unsupported input, unstable context, permission limits, outdated sources, policy filters, or unavailable tools.", "The onboarding must be short enough to preserve momentum while still giving users a mental model they can use during the real task." ], "selectionRules": [ "Choose AI limitation onboarding when the user needs first-use or changed-capability orientation about AI benefits, limits, data scope, uncertainty, feedback, human responsibility, and fallback.", "Use regular onboarding when the experience teaches product setup or first value without needing AI-specific capability and limitation calibration.", "Use inline message when a specific screen or field needs contextual AI guidance after onboarding, not the initial mental model.", "Use warning text when the user is about to take one risky action and needs consequence copy near that action.", "Use confidence / uncertainty display when one AI output needs reliability context; use AI limitation onboarding when users need broad expectations before using the feature.", "Use source grounding display when one answer needs evidence coverage; use AI limitation onboarding when users need to understand source scope and missing data before asking.", "Use scope clarification when the AI must ask a question before acting on an ambiguous request; use AI limitation onboarding to teach why the AI may ask and what it cannot infer.", "Use human approval gate when execution must pause for approval; use AI limitation onboarding to explain ahead of time which future actions require review.", "Do not hide capability limits in terms of service, release notes, or help docs when users must understand them before using the AI.", "Do not present limitations as blame-shifting disclaimers; pair each limit with safe next steps, examples, feedback, or fallback." ], "requiredStates": [ "First-run welcome state with user benefit, AI role, and plain-language capability boundary.", "Can do and cannot do state with examples matched to the user's task.", "Data scope state showing included sources, excluded sources, permission limits, and stale data risk.", "Uncertainty state explaining low confidence, missing data, unsupported input, and when output may be wrong.", "Human review state naming high-impact outputs, approval needs, and user responsibility.", "Safe trial state with reversible sample task, sandbox data, or preview-only action.", "Feedback and correction state showing how users can correct, opt out, or improve future behavior.", "Manual fallback state that completes the task without AI when the model cannot help.", "Re-onboarding state for changed AI capabilities, new data use, new autonomy, or degraded capability.", "Skipped, later, remembered, expired reminder, mobile compact, and accessibility states." ], "interactionContract": [ "The onboarding explains what the AI can help with and what it is not able to do before the first risky use.", "The AI role is not framed as a human, expert, teammate, or authority unless the limits and user responsibility are equally visible.", "Users can skip or defer noncritical teaching, but required safety boundaries remain discoverable before high-impact use.", "Safe trial actions do not commit production changes, send messages, expose private data, or teach the model without consent.", "Data-use disclosures distinguish selected user input, connected sources, historical activity, personalization signals, and unavailable data.", "Users can find correction, feedback, human review, and manual fallback without leaving the task.", "Re-onboarding appears when capability, data access, autonomy, policy, or failure behavior changes enough to affect user expectations.", "The experience supports keyboard navigation, readable status text, non-color-only signals, and focus return after details or trial actions." ], "implementationChecklist": [ "Inventory AI capability, unsupported tasks, data sources, missing data, permissions, policy filters, confidence behavior, review needs, feedback use, personalization, retention, and manual alternatives.", "Write benefit-led copy that says what users can accomplish, then name concrete limits and recovery paths in the same flow.", "Provide a short safe trial using sample data or preview-only output so users can learn behavior without production risk.", "Separate AI limitation onboarding from privacy consent, notification banners, release notes, and legal disclaimers.", "Add re-onboarding triggers for capability expansion, data-source change, model behavior change, automation increase, policy restriction, or repeated user failure.", "Track viewed, skipped, reminder scheduled, trial completed, feedback sent, fallback used, and re-onboarding acknowledged events without treating view count as success.", "Test with new and returning users for over-trust, under-trust, misunderstanding of source scope, failure recovery, and whether users know when to apply judgment." ], "commonMisuses": [ "Using charming human-like copy that implies broad expertise while hiding actual AI limits.", "Showing a one-time disclaimer that users dismiss before they understand what changes in the task.", "Listing broad safety policy text without task-specific examples, safe trial, feedback, or fallback.", "Treating confidence scores, citations, or model names as a replacement for explaining capability boundaries.", "Forcing a long tour that delays first value and teaches features users do not need yet.", "Failing to re-onboard after the AI gains autonomy, loses a data source, or changes behavior." ], "critiqueQuestions": [ "Can a first-time user say what this AI can and cannot do for their task?", "Does the onboarding explain what data the AI has, what data it lacks, and how that affects answers?", "Can users try the AI safely before relying on it?", "Do users know when to review, correct, approve, or switch to manual work?", "Is limitation copy paired with recovery instead of only legal caution?", "What re-onboarding appears after capability, data, or autonomy changes?" ], "relatedPatterns": [ "onboarding", "inline-message", "warning-text", "confidence-uncertainty-display", "source-grounding-display", "scope-clarification", "human-approval-gate", "correction-feedback", "onboarding" ], "comparisons": [ "ai-limitation-onboarding-vs-onboarding-vs-inline-message-vs-warning-text-vs-confidence-uncertainty-display-vs-source-grounding-display-vs-scope-clarification-vs-human-approval-gate" ], "sourceIds": [ "google-pair-mental-models-ai", "google-pair-explainability-trust", "google-pair-errors-graceful-failure", "microsoft-agent-responsible-ai", "microsoft-azure-openai-transparency-note" ] }, { "id": "ai-output-audit-trail", "completionStatus": "complete", "name": "AI output audit trail", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Inspectable record of generated AI output, prompt context, model, sources, tools, user actions, versions, and downstream use", "maturity": "emerging", "platforms": [ "web", "desktop", "mobile", "ai" ], "problem": "Generated AI outputs can influence customer communication, approvals, code, policy, security investigations, and business decisions, but without a durable output-level trail teams cannot prove prompt context, source use, model behavior, edits, approvals, or downstream use.", "solution": "Provide an AI output audit trail that preserves generated-output lineage, evidence snapshots, user actions, model and tool context, retention limits, redaction state, and exportable investigation detail without exposing sensitive content beyond the user's permission.", "uiGuidance": [ "Render AI output audit trail as an answer-level evidence record that connects prompt snapshot, response snapshot, model version, source snapshot, retrieved context, tool calls, safety events, user actions, approvals, edits, exports, and retention state.", "Show immutable identifiers, timestamps, actor, workspace, model, conversation or thread ID, response ID, source IDs, tool-call IDs, version chain, redaction status, permission scope, and downstream use directly in the trail." ], "uxGuidance": [ "Use AI output audit trail when users must investigate, prove, review, dispute, export, or comply with how a generated AI output was created and used.", "Make the trail answer the questions who asked, what context was used, what the model returned, what changed after generation, who saw it, who applied it, what was redacted, and how long evidence remains available." ], "uiExamples": { "good": [ "A policy answer drawer shows prompt snapshot, model version, response ID, retrieved sources, tool calls, safety filter result, generated text, user edits, approval, copy, export, and retention window.", "A compliance reviewer filters AI responses by user, model, source file, approval status, and copied-to-customer action, then opens one answer to compare original and applied versions." ], "bad": [ "A chat transcript shows only the final answer with no prompt, source snapshot, model, tool calls, user actions, or applied output history.", "A system stores raw prompts and responses with secrets visible to every admin and no redaction, permission scope, or retention notice." ] }, "uxExamples": { "good": [ "A support lead opens a disputed customer reply, sees the exact AI draft, prompt, source article versions, editor changes, approver, sent timestamp, and retention status, then exports the evidence bundle.", "An AI platform owner investigates a hallucinated answer by following the response ID to retrieved sources, unavailable files, safety events, regenerated versions, and the downstream object where the output was applied." ], "bad": [ "A user regenerates an answer and the product overwrites the previous version, leaving no way to prove which output was copied.", "An audit view says AI used sources but links to the current source pages rather than the source versions available when the output was generated." ] }, "problemContext": [ "AI outputs may be generated inside chat, assistants, agents, document editors, support tools, code tools, search answers, workflow automation, or admin consoles.", "The output may include prompt-response pairs, multiple response messages, retrieved resources, tool calls, model transparency metadata, thread IDs, message IDs, response IDs, source IDs, and downstream object IDs.", "The trail may be used by end users, managers, compliance teams, security analysts, support leads, auditors, admins, or incident responders.", "Records may be permission-limited, redacted, retained for a fixed window, exported to SIEM or compliance systems, or unavailable because audit capture was disabled.", "AI output audit trail must distinguish generated content from user edits, approvals, actions taken by agents, and ordinary activity events." ], "selectionRules": [ "Choose AI output audit trail when the task is to inspect or prove how a specific AI-generated output was produced, changed, approved, copied, applied, exported, or retained.", "Use activity log when users need a broader event stream across objects or systems, not the complete lineage of one generated output.", "Use source grounding display when the user needs evidence coverage for one current answer; use AI output audit trail when the user needs durable source snapshots and later investigation.", "Use confidence / uncertainty display when one output needs reliability context before action; use AI output audit trail when confidence, threshold, or review state must be preserved after generation.", "Use editable AI output when users are revising generated text; use AI output audit trail when the product must preserve original, edited, applied, and reviewed versions.", "Use regenerate / retry when users create another answer version; use AI output audit trail to link all versions and prove which version was viewed, copied, or applied.", "Use agent progress trace for live runtime monitoring; use AI output audit trail after or during completion to preserve prompt, response, tool, source, approval, and downstream-use evidence.", "Use human approval gate when execution must pause for a person; use AI output audit trail to prove what the approver saw and what executed afterward.", "Do not replace output-level audit with a chat transcript, current source links, plain activity feed, or raw server log when users need answer lineage and permission-aware evidence.", "Do not expose raw prompts, responses, secrets, or sensitive retrieved content to users without matching permission, redaction, and retention controls." ], "requiredStates": [ "Generated output state with response ID, timestamp, user, conversation or thread ID, and model version.", "Prompt snapshot state showing the user prompt, system or instruction reference, selected context, and redaction status.", "Response snapshot state preserving the generated content exactly as returned before edits.", "Source snapshot state showing searched, retrieved, used, unavailable, stale, and permission-limited sources as of generation time.", "Tool-call record state with tool name, input summary, output summary, permission, side effect, error, retry, and redacted payload handling.", "Safety and policy event state showing blocked, filtered, reviewed, or policy-limited output.", "Confidence or review state preserving confidence, threshold, review-required flag, reviewer, and decision at the time.", "User action state for viewed, copied, downloaded, inserted, sent, applied, approved, rejected, edited, regenerated, restored, or deleted actions.", "Version chain state linking original, regenerated, edited, applied, and restored output versions.", "Export, retention, legal hold, deletion request, redacted view, permission-limited view, tamper-evident, and mobile compact states." ], "interactionContract": [ "Users can open the trail from the generated output, applied object, activity record, or investigation result without losing the answer identity.", "The trail separates prompt snapshot, response snapshot, source snapshot, tool activity, user edits, approvals, and downstream actions.", "Every record shows timestamp, actor, actor type, output ID, version, model, context scope, and retention state where available.", "The trail preserves source and prompt context as-of generation time instead of silently resolving to current source content.", "Permission-limited and redacted records explain what is hidden and why without implying the evidence does not exist.", "Regenerate, edit, approve, apply, copy, export, and delete actions create linked records rather than overwriting the prior output.", "Exported evidence matches the on-screen filters, redactions, timezone, and retention scope.", "Mobile and narrow layouts keep output identity, action history, and evidence status readable without losing critical metadata." ], "implementationChecklist": [ "Capture immutable IDs for prompt, response, conversation, thread, model, source, tool call, user action, approval, applied object, and export job.", "Store prompt and response snapshots according to privacy, retention, security, and policy requirements; redact sensitive content in views that lack permission.", "Record source IDs, source versions, retrieval query, retrieved chunks, used evidence, inaccessible sources, stale sources, and source-grounding state at generation time.", "Record tool calls with input and output summaries, permissions, side effects, errors, retries, and raw payload access gates.", "Preserve output versions across regeneration, edits, copy, insertion, approval, rejection, sent state, rollback, and deletion requests.", "Expose filters for user, model, source, tool, approval state, applied object, risk flag, date range, workspace, and retention state.", "Test export, redaction, timezone, permission-limited access, retention expiry, legal hold, SIEM handoff, and tamper-evidence behavior." ], "commonMisuses": [ "Calling a chat transcript an audit trail when it does not preserve source, tool, model, action, approval, or version evidence.", "Linking to current sources instead of the source snapshot used when the answer was generated.", "Overwriting prior answers during regeneration or edit flows.", "Showing raw sensitive prompt, response, or tool payload data to users without matching permissions.", "Recording only post-action activity and not the AI output that motivated the action.", "Exporting a different range, timezone, redaction level, or permission scope than the visible trail." ], "critiqueQuestions": [ "Can reviewers prove which exact AI output was generated, viewed, copied, edited, approved, and applied?", "Does the trail distinguish prompt, response, source, tool, model, safety, user action, and downstream object records?", "Are source snapshots preserved as of generation time?", "Can permission-limited users understand what evidence is hidden without seeing sensitive content?", "Does regeneration preserve earlier versions and show which version was used?", "Can exports, SIEM handoffs, and retention messages be trusted to match the visible trail?" ], "relatedPatterns": [ "activity-log", "source-grounding-display", "confidence-uncertainty-display", "editable-ai-output", "regenerate-retry", "agent-progress-trace", "tool-use-visibility", "human-approval-gate", "correction-feedback", "version-history" ], "comparisons": [ "ai-output-audit-trail-vs-activity-log-vs-source-grounding-display-vs-confidence-uncertainty-display-vs-editable-ai-output-vs-regenerate-retry-vs-agent-progress-trace-vs-human-approval-gate" ], "sourceIds": [ "microsoft-purview-copilot-ai-audit-logs", "microsoft-copilot-interaction-schema", "microsoft-security-copilot-audit-log", "github-copilot-agentic-audit-log-events", "openai-admin-audit-logs-api" ] }, { "id": "alert", "completionStatus": "complete", "name": "Alert", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Urgent current-task status message", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need immediate notice of a time-sensitive task condition, but moving focus into a dialog or hiding the message in a transient notification would either over-interrupt the task or make the condition too easy to miss.", "solution": "Show a concise persistent alert in the current task context, choose urgency semantics from consequence, provide one direct next step or safe dismissal, and update or remove the alert when the condition resolves.", "uiGuidance": [ "Render an alert as a visible message in the current task area with a clear severity cue, short title, consequence-focused body, and one direct action or safe dismissal when appropriate.", "Use assertive alert semantics only when an urgent message appears dynamically and needs immediate notice; use calmer status or region semantics for advisory, success, or already-visible page-load information." ], "uxGuidance": [ "Use alerts when the user must notice a time-sensitive condition that affects their current task, such as session expiry, lost connection, unsaved work risk, failed submission, or a security-sensitive hold.", "Keep alerts tied to the current task outcome: name what changed, why it matters, what happens if the user does nothing, and which one next step resolves or clarifies the condition." ], "uiExamples": { "good": [ "A session alert appears above the active editor, says the session expires in 2 minutes, and offers Save draft while keeping the editor usable.", "A connection alert stays near the workspace header and says changes are stored locally until the server reconnects." ], "bad": [ "A vague red strip says Warning with no object, consequence, or next step.", "A payment hold alert opens as a modal with only OK even though no decision is needed." ] }, "uxExamples": { "good": [ "Users can renew the session, save a draft, or inspect details without losing typed work.", "When the connection returns, the alert downgrades to a success status and then can be dismissed safely." ], "bad": [ "The only warning that unsaved work will be lost disappears after five seconds.", "A routine saved message interrupts screen reader output with assertive alert semantics on every keystroke." ] }, "problemContext": [ "A system, validation, connection, security, payment, save, or submission condition affects the user's current task now.", "The message is more urgent than routine status but does not require the user to answer a modal decision.", "The affected scope is the current page, workspace, step, or task flow rather than one table row, one input value, or the whole product.", "Users can understand the situation from a short title and body, with optional detail routed elsewhere." ], "selectionRules": [ "Choose alert when a time-sensitive warning, error, or important status change must be noticed immediately without moving focus.", "Use inline message instead when the message belongs directly beside one visible object, row, card, panel, or form section.", "Use toast notification instead when the message can expire safely and does not need to remain in the task layout.", "Use confirmation dialog instead when the user must explicitly choose before a consequential action proceeds.", "Use error state instead when an expected content region failed and needs retry, fallback, support, or preserved-task recovery.", "Use banner or site alert instead when the message applies across the product, service, account, or multiple pages.", "Use role alert only for dynamically updated urgent text, and use status or region for less urgent messages.", "Allow dismissal only when the underlying condition is resolved, recoverable elsewhere, or purely informational." ], "requiredStates": [ "No-alert state with the task operating normally.", "Urgent warning or error alert that appears dynamically and is announced without taking focus.", "Advisory or success state that uses calmer status semantics rather than assertive alert semantics.", "Actionable alert with one direct next step such as Save draft, Renew session, Retry sync, or Update payment.", "Detail-revealed state for a short consequence explanation without expanding into a full recovery workflow.", "Dismissed state when hiding the alert is safe.", "Resolved state where the alert updates, downgrades, or disappears when the condition changes.", "Escalated state where the condition moves to inline message, error state, banner, notification center, or confirmation dialog." ], "interactionContract": [ "The alert appears close to the task area whose outcome it affects and before the controls users need next.", "The alert title names the condition or affected process, not only the severity.", "The body states the consequence and the most useful next step in one or two short sentences.", "The alert does not steal focus, but its action and dismiss controls are reachable in normal tab order.", "Urgent dynamic text is announced with alert semantics; advisory updates use status or region semantics.", "Dismissal does not hide an unresolved critical condition with no alternate route.", "When the condition resolves, the alert is removed, converted to lower-urgency status, or replaced by the correct recovery surface." ], "implementationChecklist": [ "Classify the condition by urgency, affected scope, user consequence, and whether a user response is required.", "Place the alert in the current task region, not in a detached corner or global header unless the scope truly spans the product.", "Write a title that names the issue, such as Session expires soon or Connection lost.", "Write body text that explains what will happen and what the user can do next.", "Limit actions to one direct command or one detail route; move multi-step recovery into a dedicated flow.", "Choose role alert for urgent dynamic text, role status for lower-urgency status, and alertdialog when closure or response is required.", "Do not create several assertive alerts at once; queue, merge, or prioritize them by consequence.", "Test repeated alerts, dismissal, resolved state, screen reader announcement, keyboard reachability, zoom, and narrow layouts." ], "commonMisuses": [ "Using a disappearing toast for warnings users must act on before continuing.", "Using a modal dialog for a message that only needs immediate notice and one optional next step.", "Using alert semantics for routine success messages, progress ticks, or page-load content.", "Putting product-wide maintenance or outage messages inside one task alert.", "Showing several assertive alerts at the same time.", "Writing severity-only copy such as Error or Attention without consequence or action.", "Letting users dismiss a critical unresolved condition with no way to rediscover it." ], "critiqueQuestions": [ "Is the condition urgent enough to interrupt assistive technology output, or should it be a calmer status message?", "Can users tell which current task, process, or page condition the alert affects?", "Does the alert say what will happen if users do nothing?", "Is one direct action enough, or does this need an error state, dialog, page, or panel?", "Can the alert be dismissed safely, and how can users rediscover unresolved conditions?", "What happens when the condition resolves, repeats, or coexists with another warning?" ], "relatedPatterns": [ "inline-message", "toast-notification", "confirmation-dialog", "error-state", "toast-only-critical-error", "error-summary" ], "comparisons": [ "alert-vs-inline-message-vs-toast-notification-vs-confirmation-dialog" ], "sourceIds": [ "uswds-alert-component", "mdn-aria-alert-role", "carbon-notification-component", "wcag-status-messages" ] }, { "id": "alert-dialog", "completionStatus": "complete", "name": "Alert dialog", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Blocking urgent-response modal", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Some urgent conditions require users to read a message and choose a response before they can safely continue the current workflow.", "solution": "Open a modal alert dialog with a specific title, consequence-focused description, contained focus, inactive background content, response-labelled actions, and predictable cancellation or focus return.", "uiGuidance": [ "Render an alert dialog as a modal response surface with a condition-specific title, consequence text, role alertdialog or platform equivalent, inactive background, and buttons labelled by outcome.", "Keep the dialog compact enough for immediate decision-making while routing longer recovery or troubleshooting detail to a separate page, panel, or support flow." ], "uxGuidance": [ "Interrupt only when a current-workflow condition needs an explicit response before users can safely continue.", "Make each response predictable: name the affected workflow, describe what is blocked, explain what happens next, and return users to a clear recovery point after the dialog closes." ], "uiExamples": { "good": [ "A Session locked alert dialog says the editor is paused because the account opened elsewhere, offers Stay signed in and Sign out, and keeps the background editor unavailable.", "A payment authorization alert dialog explains that checkout cannot continue until users Retry payment or Choose another method." ], "bad": [ "A popup says Warning with only OK while the page behind it still accepts input.", "A non-modal alert asks users to choose Stay signed in but lets them continue editing expired-session content." ] }, "uxExamples": { "good": [ "Tab stays inside the dialog, Escape follows the safe cancel path, Stay signed in returns focus to the editor, and Sign out moves to the signed-out state.", "The interruption appears only when the session lock occurs, not every time the page loads." ], "bad": [ "Users can click Delete, navigate away, or keep typing behind a blocking security message.", "The same OK-only interruption appears for routine success and warning messages until users close it reflexively." ] }, "problemContext": [ "A security, privacy, session, data-loss, permission, billing, or safety condition blocks the current workflow.", "The user must acknowledge, cancel, continue, sign out, retry, review, or choose another response before returning to the page.", "A non-modal alert would be too easy to miss or would leave users able to continue into an unsafe state.", "A generic modal task would understate the urgency or fail to communicate that a response is required." ], "selectionRules": [ "Choose an alert dialog when an important message interrupts the current workflow and requires an immediate user response.", "Use a non-modal alert when users only need urgent notice and can continue working without answering the message.", "Use a modal dialog when the surface is a short contained task such as editing a field, choosing an object, or entering settings.", "Use a confirmation dialog when the alert-style decision is caused by a user-initiated consequential action that has not yet committed.", "Use warning text when the severe consequence can be explained inline before the risky action without blocking the whole page.", "Use a site alert or banner when the message applies across a service, account, product, or many pages rather than one current workflow.", "Do not use an alert dialog for page-load announcements, routine success messages, marketing notices, low-risk confirmations, or educational copy that does not need a response.", "Do not open several alert dialogs in a row; prioritize the highest consequence and route secondary detail to the dialog body or a recovery flow." ], "requiredStates": [ "Normal workflow state with a visible invoking event or system condition.", "Opening state that moves focus into the alert dialog and marks background content inactive.", "Urgent message state with accessible title, associated description, consequence copy, and response-labelled actions.", "Contained keyboard state where Tab and Shift+Tab stay within the dialog until it closes.", "Safe cancellation or escape state when cancellation is allowed.", "Positive response state that commits the user's chosen continuation, retry, acknowledgement, or sign-out path.", "Closed state that returns focus to the invoker or next logical recovery location.", "Escalated state for conditions that need a page, support route, or longer recovery task after the response." ], "interactionContract": [ "The alert dialog appears only for a condition that genuinely requires a response before continuation.", "The dialog has alertdialog semantics or the platform equivalent, an accessible name from the visible title, and a description connected to the consequence text.", "Opening the dialog moves focus to the safest useful element: often a non-destructive response, a detail link, or the message text when reading comes first.", "Background page controls cannot be clicked, focused, or changed while the alert dialog is open.", "Tab and Shift+Tab cycle through only the dialog controls.", "Escape cancels only when cancellation is safe; otherwise the available actions explain what response is required.", "Buttons use response labels such as Stay signed in, Sign out, Retry payment, or Keep editing rather than OK-only labels.", "Closing after any response returns focus to the trigger or a clear outcome state without losing the user's task context." ], "implementationChecklist": [ "Classify the condition by urgency, affected workflow, user consequence, and whether a response is mandatory.", "Write a visible title that names the condition, such as Session locked or Payment authorization failed.", "Describe why the interruption is happening, what is blocked, and what each response changes.", "Use role alertdialog with aria-modal true where appropriate, and connect aria-labelledby and aria-describedby to visible content.", "Move focus into the dialog on open and contain focus until a response closes it.", "Make the page behind the dialog inert or otherwise unavailable to pointer and keyboard interaction.", "Prefer a safe or explanatory initial focus target unless the urgent condition has only one safe response.", "Provide Escape and an explicit safe action when cancellation is allowed.", "Return focus to the opener, the blocked control, or the next recovery location after close.", "Log and review alert-dialog frequency so users are not trained to dismiss critical interruptions." ], "commonMisuses": [ "Using an alert dialog as a dramatic version of a routine non-modal alert.", "Showing a vague Warning dialog with only OK and no consequence or next step.", "Letting users interact with background controls while the response-required message is visible.", "Opening the dialog automatically on every page load for content that can be shown inline.", "Using alertdialog semantics for marketing, onboarding tips, or passive informational copy.", "Hiding the safe response or making the destructive response the accidental default.", "Failing to return focus after close, leaving keyboard users at the start of the page." ], "critiqueQuestions": [ "What unsafe or impossible state would occur if the user ignored this message?", "Does the message require a user response, or would a visible alert be enough?", "Is the interruption caused by a system condition, or by a user-initiated consequence that belongs to confirmation guidance?", "Does the title name the affected workflow or condition?", "Can users predict what each response button will do without rereading the whole body?", "Where does focus move on open, Tab wrap, Escape, response, and close?" ], "relatedPatterns": [ "alert", "modal-dialog", "confirmation-dialog", "warning-text", "site-alert" ], "comparisons": [ "alert-dialog-vs-alert-vs-modal-dialog-vs-confirmation-dialog" ], "sourceIds": [ "wai-aria-apg-alertdialog", "wai-aria-apg-dialog-modal", "apple-hig-alerts", "microsoft-windows-confirmations" ] }, { "id": "ambiguous-destructive-action-copy", "completionStatus": "complete", "name": "Ambiguous destructive action copy", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Destructive copy anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can commit destructive or high-consequence actions because the final labels do not say the real outcome, target, scope, or safe alternative.", "solution": "Treat ambiguous destructive copy as an anti-pattern: rewrite titles, primary actions, secondary actions, and status copy so each control names the outcome it causes, the target it affects, and whether the action destroys, preserves, cancels the operation, or cancels an existing service.", "uiGuidance": [ "Replace vague destructive controls with labels that name the verb, target, count, and outcome, such as Delete workspace, Keep workspace, Revoke Maya's access, or Cancel subscription.", "Disambiguate overloaded words like Cancel, Remove, Continue, Confirm, Clear, Reset, and Close whenever they sit near irreversible, external, or costly outcomes." ], "uxGuidance": [ "Make the copy carry the decision boundary: users should know which choice destroys, which preserves, which closes the surface, and which continues review.", "Keep destructive copy synchronized across trigger, title, body, final action, safe action, receipt, accessible name, and compact/mobile variants." ], "uiExamples": { "good": [ "A dialog title says Delete Payments project?, the safe action says Keep project, and the final action says Delete Payments project.", "A subscription dialog uses Keep Pro plan and Cancel Pro subscription instead of OK and Cancel.", "A bulk action says Permanently delete 12 files and updates when the selected count changes." ], "bad": [ "A destructive prompt says Are you sure? with OK and Cancel.", "A permission dialog uses Remove for both removing a row from a list and revoking account access.", "A dangerous action review uses Continue as the button that actually sends the customer email." ] }, "uxExamples": { "good": [ "A user reads Keep subscription and Cancel subscription and correctly chooses the path that preserves billing.", "A user reviewing access removal sees Revoke Maya's editor access and understands the user is not deleted.", "A user on mobile sees Delete 12 files because the compact label still includes count and object type." ], "bad": [ "A user presses OK because it looks like a neutral acknowledgement and accidentally deletes the workspace.", "A user presses Cancel intending to close the dialog but cancels the paid plan.", "A screen reader user hears Confirm and cannot tell whether it confirms review, deletion, or sending." ] }, "problemContext": [ "A dialog, sheet, action menu, toast, command palette, mobile action sheet, or review page includes a destructive command.", "The interface uses vague labels such as OK, Yes, No, Continue, Confirm, Submit, Remove, Done, or Cancel near a destructive or externally visible action.", "The same word can mean different outcomes, such as cancel the dialog versus cancel the subscription, remove from view versus delete permanently, or continue review versus execute the dangerous action.", "Users need to distinguish the destructive commit, the safe preserve path, reversible cleanup, typed target verification, and high-impact action review." ], "selectionRules": [ "Flag this anti-pattern when the destructive or safe action label does not name what will happen.", "Use destructive action confirmation when the whole final review needs target, scope, consequence, dependency, acknowledgement, and commit states; this entry focuses on the wording defect inside those surfaces.", "Use typed confirmation when severe wrong-target risk requires reproducing a visible target phrase; typed confirmation still needs unambiguous final button copy.", "Use dangerous-action review when the action is high impact because of money, access, production, legal, customer, external recipient, or agent-tool effects; this entry flags vague Run, Continue, or Approve labels that hide execution.", "Use confirmation fatigue when the problem is repeated low-value prompts and habituation; this entry applies even to one prompt if the destructive labels are unclear.", "Use warning text when consequence copy belongs before the command; warning text cannot repair a final button labelled OK or Yes.", "Name the destructive verb and target in the final action, such as Delete workspace, Revoke Maya's access, Cancel Pro subscription, or Permanently delete 12 files.", "Name the safe path as the preserved outcome, such as Keep workspace, Keep subscription, Keep access, or Cancel deletion.", "Avoid Cancel when both the dialog and the underlying service can be cancelled; use Back, Keep plan, Close review, or Cancel subscription according to the real outcome." ], "requiredStates": [ "Clear destructive title state with verb, target, and consequence.", "Clear final action state with destructive verb plus target or count.", "Clear safe action state that names the preserved outcome.", "Ambiguous Cancel state where cancel could mean cancel dialog or cancel service.", "Reversible cleanup state where Archive, Move to trash, or Hide is not mislabeled as Delete permanently.", "Bulk scope state where the label includes selected count and object type.", "Permission or access removal state where Remove distinguishes from delete object.", "External-effect state where Send, publish, charge, revoke, or run labels reveal the side effect.", "Mobile compact state where shortened labels still preserve outcome meaning.", "Bad OK or Yes state that hides destruction.", "Bad Continue state that hides execution.", "Bad Remove state that hides whether data is deleted or detached.", "Bad Cancel state that reverses user intent.", "Bad same-copy state where every prompt uses the same labels.", "Bad color-only danger state where red styling carries the only destructive signal.", "Bad post-commit copy state where the UI clarifies the outcome only after the destructive action runs." ], "interactionContract": [ "Every destructive control label must answer what action will happen and what object or scope it affects.", "Every safe action label must answer what will be preserved or where the user returns.", "Dialog titles, body copy, final buttons, secondary buttons, menu items, and status text must use the same verb and target model.", "If a word has domain ambiguity, such as Cancel, Remove, Close, Disable, Reset, Revoke, Clear, or Dismiss, the UI adds the object and outcome.", "Copy changes must update accessible names, not only visible helper text or color.", "Short mobile labels may abbreviate object names only when nearby text keeps the full target and consequence in reading order." ], "implementationChecklist": [ "Inventory every destructive prompt and record the trigger label, title, final action, safe action, status message, object, count, and consequence.", "Replace OK, Yes, No, Continue, Confirm, Submit, and Done with outcome-specific labels.", "Replace ambiguous Cancel with Keep plan, Close dialog, Cancel subscription, Stop deletion, or Do not delete according to intent.", "Disambiguate Remove by naming whether the object is deleted, detached, hidden, unshared, revoked, or moved to trash.", "Include counts for bulk destructive actions and rerender labels when selection changes.", "Keep copy synchronized with disabled states, dependency blockers, typed confirmation, and post-action receipts.", "Test localization, truncation, keyboard focus, screen reader names, compact width, and action-sheet layouts so labels remain specific." ], "commonMisuses": [ "A delete prompt uses OK and Cancel without naming what OK will delete.", "A subscription flow has a Cancel button that could mean close the dialog or cancel the subscription.", "A permission dialog uses Remove without saying whether access is revoked or the person is deleted from the workspace.", "A dangerous agent tool review uses Continue for both the next review step and actual execution.", "A mobile action sheet shortens Delete account to Delete when the account name and scope are offscreen.", "A red button relies on color to signal destruction while its text says Confirm." ], "critiqueQuestions": [ "Would the final action label still be clear if read without color or icon?", "Does the label name the destructive verb and affected target?", "Could Cancel, Remove, Continue, or Done mean more than one outcome in this context?", "Does the safe action say what remains unchanged?", "Does bulk copy update when selected count or object type changes?", "Does assistive technology receive the same outcome-specific label as sighted users?" ], "relatedPatterns": [ "destructive-action-confirmation", "typed-confirmation", "dangerous-action-review", "confirmation-fatigue", "warning-text", "confirmation-dialog", "undo", "restore-from-trash", "delete-account" ], "comparisons": [ "ambiguous-destructive-action-copy-vs-destructive-action-confirmation-vs-typed-confirmation-vs-dangerous-action-review-vs-confirmation-fatigue-vs-warning-text" ], "sourceIds": [ "apple-hig-alerts", "microsoft-windows-confirmations", "atlassian-forge-danger-modal", "maersk-dialog-component", "wai-aria-apg-alertdialog" ] }, { "id": "approval-workflow", "completionStatus": "complete", "name": "Approval workflow", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Routed decision workflow for requests that require authorized approval", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "High-impact work stalls or proceeds unsafely when products hide who must approve, which rule applies, whether approval is sequential or parallel, what approvers are deciding, how rejection or changes return to the requester, and how the final decision is audited.", "solution": "Provide a durable approval record that routes a submitted request to eligible decision makers, shows the active rule and gate, collects decisions and comments, handles changes, delegation, expiry, cancellation, and bypass, and records the final outcome before downstream work proceeds.", "uiGuidance": [ "Render approval workflow as a routed request record with requester, object, requested action, approver eligibility, required rule, current gate, due date, decision controls, comment history, and outcome consequences.", "Separate requester view, approver decision view, pending route, delegated or reassigned route, change-requested route, final approved or rejected outcome, timeout, cancellation, and bypass audit states." ], "uxGuidance": [ "Use approval workflow when a submitted request cannot proceed until an authorized person, group, threshold, sequence, or external policy gate explicitly approves or rejects it.", "Make the approval route understandable over time: who has the request, what decision is needed, what happens on approval or rejection, what blocks self-review, and where the requester can revise or withdraw." ], "uiExamples": { "good": [ "A production deployment request shows requester, service, environment, change summary, required reviewer group, self-review restriction, wait timer, Approve and Reject with reason controls, and a timeline of route changes.", "A purchase request shows manager approval complete, finance approval pending, legal approval next, due dates, comments, attachments, and the final action that will run after all required approvals." ], "bad": [ "A request page says Waiting without naming the approver, required count, due date, or escalation path.", "An approver receives Approve and Reject buttons in email with no request summary, impact, attachment, policy reason, or link to the canonical record." ] }, "uxExamples": { "good": [ "A requester submits a deployment, sees it is waiting for Release managers, cannot self-approve, receives a change request with a required comment, edits the change summary, and resubmits to the same route.", "A finance approval requires both manager and controller approval; the first approval advances the sequence, a rejection stops downstream processing, and the requester sees the exact rejection reason and revise action." ], "bad": [ "The first approver clicks Approve and the system marks the whole request approved even though policy required everyone to approve.", "A rejection returns the requester to a blank form, loses attachments, and leaves no audit trail showing who rejected or why." ] }, "problemContext": [ "A request has already been drafted or submitted and a policy, workflow, governance, financial, release, access, procurement, content, or compliance rule requires human or external approval.", "The approval route may be one approver, any one of several approvers, every assigned approver, a threshold, a percentage, a named sequence, a group, a code owner, a manager chain, or a custom external gate.", "Approvers need enough context to make a decision without leaking unnecessary data or acting on stale versions.", "Requesters need status, ownership, due date, comments, revise or withdraw paths, and final consequences.", "The product must preserve audit evidence for approve, reject, request changes, delegate, reassign, cancel, timeout, revoke, bypass, and resubmit events." ], "selectionRules": [ "Choose approval workflow when the core job is routing a submitted request through one or more authorized decisions before work can continue.", "Use review before submit when the requester is still checking their own inputs before the request enters an approval route.", "Use permission recovery when the user is blocked by missing access and is requesting authorization for themselves.", "Use invite user when another person is being invited into a workspace, organization, team, repository, channel, or shared resource.", "Use confirmation dialog for an immediate local confirmation, not for long-running approval routes with status, approvers, comments, and audit trail.", "Use activity log for the historical trail of approval events, not as the primary decision interface.", "Show whether the rule is everyone must approve, first to respond, threshold, percentage, sequential, code-owner, group, or custom policy gate.", "Block or clearly flag self-review when policy requires a separate approver.", "Expose rejection, requested changes, timeout, cancellation, delegation, bypass, and resubmission as specific states with different next actions.", "Keep approver notifications deep-linked to the canonical approval record so decisions are made against current request context." ], "requiredStates": [ "Draft or submit-ready request handoff state", "Submitted and awaiting route calculation state", "Pending approver state with current owner or group", "Approver decision state with Approve, Reject, and comment controls", "Sequential next-approver state", "Parallel approval progress state", "Requested changes state", "Rejected state with reason and revise or close path", "Approved state with downstream action or release", "Delegated or reassigned approver state", "Due soon, expired, or timed-out state", "Canceled or withdrawn state", "Bypassed or admin override state with audit reason" ], "interactionContract": [ "Submitting creates a durable approval record with requester, target, requested action, version, approver rule, due date, and route state.", "Approver controls are available only to eligible approvers and must show the current request version and required context before decision.", "Approve, reject, request changes, delegate, reassign, withdraw, cancel, revoke approval, bypass, and resubmit actions update the same record and timeline.", "Sequential routes move to the next required approver only after the current approver responds.", "Parallel routes compute completion according to the configured rule, such as everyone approves, first response, threshold, percentage, or any rejection stops.", "Rejected and change-requested outcomes preserve requester inputs and comments so revisions do not start from an empty request.", "Notifications and email actions must verify the record is still current before accepting a decision.", "Final approval triggers the downstream operation only after all required gates pass; final rejection, expiry, or cancellation blocks it.", "The audit trail records actor, role, decision, comment, timestamp, route rule, delegation, bypass, and version context." ], "implementationChecklist": [ "Model approval record, request version, requester, target object, requested action, approval rule, approver eligibility, due date, decision states, comments, attachments, and audit events separately from the drafted request form.", "Define route semantics for one approver, first response, everyone must approve, threshold, percentage, sequential chain, code owner, manager chain, group, manual approver, custom policy, timeout, and bypass.", "Design requester, approver, admin, and observer views with the same canonical state but role-appropriate actions.", "Show enough request detail, risk, attachment, diff, cost, access, release, or publication impact for a decision, and hide restricted details from ineligible viewers.", "Require rejection and change-request comments when the requester needs an actionable next step.", "Preserve request data, comments, attachments, route history, and return context through revision, resubmission, browser Back, reload, and notification deep links.", "Prevent stale decisions by checking version, eligibility, current status, and route membership before accepting approval from email, mobile, or background notifications.", "Implement escalation, due date, reminder, delegate, reassign, withdraw, cancel, and admin bypass paths with audit reasons.", "Test everyone-approves, first-to-respond, sequential, threshold, self-review block, duplicate decision, late decision after timeout, rejection with reason, requested changes, delegation, cancellation, bypass, mobile decision controls, keyboard navigation, and screen reader status updates." ], "commonMisuses": [ "Showing a generic pending message without the approver, gate, rule, or due date.", "Treating the first approval as final when the rule requires more approvers.", "Letting requesters approve their own protected work without an explicit bypass rule.", "Collecting Approve or Reject without showing the current request version or impact.", "Dropping requester inputs after rejection or requested changes.", "Using a notification as the only approval surface and losing the canonical record.", "Conflating approval workflow with review before submit, review queue, assignment, or activity log.", "Failing to audit delegation, reassignment, cancellation, timeout, revocation, and bypass." ], "critiqueQuestions": [ "Who requested the approval, what object or action is being approved, and what version is the approver deciding on?", "Which rule applies: one approver, everyone, first response, threshold, percentage, sequence, group, manager, code owner, or custom policy?", "Who can approve, who is blocked from self-review, and how are unavailable approvers handled?", "What happens after approval, rejection, requested changes, timeout, cancellation, or bypass?", "Can the requester revise without losing context, and can approvers see what changed since the last route?", "Does the audit trail explain every decision, comment, route change, delegation, and override?" ], "relatedPatterns": [ "review-before-submit", "permission-recovery", "invite-user", "confirmation-dialog", "activity-log", "notification-center", "success-confirmation", "conflict-state" ], "comparisons": [ "approval-workflow-vs-review-before-submit-vs-permission-recovery-vs-invite-user" ], "sourceIds": [ "github-actions-deployment-protection-rules", "gitlab-merge-request-approvals", "microsoft-power-automate-approvals", "microsoft-power-automate-everyone-must-approve", "servicenow-ask-for-approval-action" ] }, { "id": "assignment", "completionStatus": "complete", "name": "Assignment", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Responsibility control for assigning a work item to eligible people, teams, roles, bots, or no owner", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Work loses accountability when products blur assignee, owner, reviewer, approver, watcher, mention, collaborator, and permission roles, or when assignment changes hide eligibility, notification, workload, unassigned, bulk, and reassignment consequences.", "solution": "Provide a clear assignment surface that identifies the accountable owner or assignees, constrains candidate choices by eligibility and policy, separates assignment from related roles, previews notification and access effects, supports self-assign, reassign, unassign, automatic default assignment, bulk preview, and records changes in activity.", "uiGuidance": [ "Render assignment as a responsibility field on a specific work item with current assignee, unassigned state, eligibility-filtered candidate picker, self-assign affordance, reassign and clear controls, notification outcome, and visible responsibility wording.", "Expose assignment limits and context such as one owner versus multiple assignees, team or bot assignment, automatic default owner, due date or next-action expectation, current workload signal, permission eligibility, and handoff note when reassignment changes accountability." ], "uxGuidance": [ "Use assignment when users need to decide who is accountable for doing or owning a work item, not merely who should be notified, mentioned, approved, invited, or granted access.", "Make assignment changes traceable and reversible enough for teamwork: explain who owns the item now, who was notified, whether the assignee can act, what changed in assigned-to-me views, and what happens to existing watchers, reviewers, collaborators, or queues." ], "uiExamples": { "good": [ "An issue sidebar shows Assignee: Maya Chen, Assign to me, Change assignee, Clear, eligible teammate search, reviewer separate from assignee, and a note that the new assignee will be notified.", "A document comment action item shows the assigned person, due date, done state, reassign control, and unresolved comment context." ], "bad": [ "A comment field says @Rahul please handle this but does not create an assignment record or appear in Rahul's assigned work.", "A ticket bulk action says Assign without showing selected count, current owners, hidden filtered tickets, or users who cannot access the queue." ] }, "uxExamples": { "good": [ "A triager changes a support ticket from unassigned to Priya, adds a handoff note, sees that Priya has access and capacity warning, and the ticket appears in Priya's assigned-to-me queue.", "A developer assigns a pull request to themselves for follow-up while keeping reviewers separate, then reassigns it to the release owner with the previous owner visible in activity." ], "bad": [ "A user assigns a confidential issue to a teammate who cannot open the project, and the UI reports success without warning.", "An automatic assignment silently routes every new component issue to a former maintainer and leaves the team with stale ownership." ] }, "problemContext": [ "Assignment may appear on issues, pull requests, tasks, tickets, comments, documents, forms, cases, approvals, incidents, projects, or queue rows.", "Assignable targets may include one person, several people, a team, a role, a bot, an automatic default owner, or an explicit unassigned state depending on product policy.", "The assignee may be responsible for doing the work, taking the next action, shepherding completion, merging, responding, or coordinating a handoff.", "The assignment change may notify the assignee, update assigned-to-me views, change queue membership, affect workload dashboards, or fail if permissions or membership are missing.", "Assignment often sits near mentions, reviewers, approvers, watchers, collaborators, owners, and permission grants, so the difference must be visible." ], "selectionRules": [ "Choose assignment when the primary action is setting or changing who is accountable for a specific work item.", "Use mentions when the user only needs attention in a comment or discussion and no responsibility record should be created.", "Use review queue when assignment is one action inside a larger workload triage surface with queue counts, reasons, stale-row checks, and next-item behavior.", "Use approval workflow when the person is asked to make an approve/reject decision under a route rule rather than own the work item.", "Use task list when users are scanning fixed service tasks and statuses; an assignee may appear in each row but does not define the list.", "Use object picker for the reusable search-and-select control, but add assignment-specific eligibility, responsibility, notification, and reassignment rules around it.", "Use permission sharing when the change grants access; assignment should either require existing access or explicitly handle access-grant side effects.", "Use activity feed and notification center to communicate assignment changes, but keep the source of truth on the assigned item.", "Show current assignee and unassigned state before asking users to choose a new person.", "Distinguish single-owner accountability from multi-assignee collaboration and state the product's limit or policy.", "Preview bulk assignment scope, current owners, hidden selected items, ineligible items, and notification count before applying.", "Prefer explicit automatic assignment labels when defaults come from component, team, project, or space settings rather than a user's direct choice." ], "requiredStates": [ "Unassigned item state.", "Assigned to one person state.", "Assigned to multiple people state where product policy allows it.", "Assigned to team, role, bot, or automatic default owner state.", "Self-assign state.", "Reassign state with previous assignee visible.", "Clear or unassign state.", "Eligible candidate search and no matching eligible assignee state.", "Ineligible candidate due to permission, membership, workload, availability, or policy.", "Bulk assignment preview with selected count and exceptions.", "Notification sent, notification suppressed, and notification failed states.", "Assigned-to-me view synchronization state.", "Handoff note or reason-required state.", "Assignment conflict or stale item changed since load state.", "Mobile compact assignment row state." ], "interactionContract": [ "Opening assignment shows the current assignee, candidate eligibility, and whether the item supports one assignee, multiple assignees, teams, bots, or automatic assignment.", "Selecting an assignee updates the work item's assignment record and any assigned-to-me, queue, activity, and notification surfaces governed by the product.", "Self-assign, reassign, clear, and bulk assign controls apply to the named item or previewed item set only.", "The product refuses or warns before assignment to people who cannot access, cannot act, are outside policy, or are not valid candidates.", "Reassignment preserves previous owner, time, actor, and optional handoff note in activity or history.", "Bulk assignment previews selected count, hidden filtered rows, existing owners, ineligible rows, notification recipients, and partial failures.", "Assignment does not silently grant permissions, invite users, approve requests, request review, or mention people unless the UI says so.", "A stale assignment save checks whether the item owner changed since the picker opened and offers refresh or override recovery." ], "implementationChecklist": [ "Define assignment semantics for each object type: single responsible owner, multiple assignees, team assignment, role assignment, bot assignment, automatic owner, or unassigned allowed.", "Model assignment separately from creator, reporter, reviewer, approver, watcher, subscriber, mention, collaborator, and permission roles.", "Build an eligibility query for candidates based on membership, permissions, role, team, availability, workload, project scope, blocked users, external guests, and automation accounts.", "Add controls for self-assign, search/select, reassign, clear, automatic default, handoff note, notification toggle when allowed, and bulk assignment preview.", "Synchronize assignment changes with assigned-to-me lists, review queues, activity feeds, notifications, object history, workload views, and API responses.", "Handle no eligible candidates, stale assignment conflicts, partial bulk failure, permission loss, deleted users, suspended users, team removal, automatic default drift, and notification failure.", "Test keyboard search and selection, screen-reader names, duplicate display names, long team names, multiple assignee wrapping, mobile layout, high zoom, bulk preview, and assignment updates from another user." ], "commonMisuses": [ "Treating a mention as an assignment.", "Using assignment as an access grant without explaining permission changes.", "Hiding whether the product supports one assignee or many.", "Mixing assignee, reviewer, approver, owner, watcher, and collaborator in one unlabeled people list.", "Allowing assignment to people who cannot open or act on the item.", "Silently auto-assigning work without naming the default rule.", "Bulk assigning hidden rows without count, current-owner, or exception preview.", "Removing prior owner and handoff context during reassignment." ], "critiqueQuestions": [ "What responsibility does the assignee take on, and how is that different from a mention, reviewer, approver, watcher, or collaborator?", "Who is eligible to be assigned, and what happens when a candidate lacks access or is outside policy?", "Does the product support one owner, many assignees, teams, bots, or automatic defaults?", "What notification, assigned-to-me, queue, workload, and activity changes happen after assignment?", "Can users see previous owner and handoff context after reassignment?", "How are bulk assignment, stale owner changes, deleted users, no eligible candidates, and notification failures handled?" ], "relatedPatterns": [ "task-list", "review-queue", "approval-workflow", "mentions", "object-picker", "notification-center", "activity-feed", "permission-sharing", "invite-user", "saved-view" ], "comparisons": [ "assignment-vs-task-list-vs-review-queue-vs-approval-workflow" ], "sourceIds": [ "github-assigning-issues-pull-requests", "github-rest-issue-assignees", "atlassian-jira-automatic-assignee", "asana-assign-tasks-teammates", "microsoft-planner-connector-assignees", "google-docs-comments-action-items" ] }, { "id": "audit-log", "completionStatus": "complete", "name": "Audit log", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Governed audit evidence surface for security, compliance, forensic, and administrative review", "maturity": "established", "platforms": [ "web", "desktop", "mobile", "ai" ], "problem": "Audit-log surfaces fail when they look like ordinary activity histories, hide retention and access boundaries, omit stable evidence fields, allow privileged deletion, or export records that do not match the reviewed scope.", "solution": "Provide an audit log with stable audit records, explicit evidence schema, governed retention, scoped access, redaction reasons, export/API/SIEM behavior, custody and tamper indicators, and clear coverage gaps for security, compliance, and forensic review.", "uiGuidance": [ "Render audit logs as governed evidence records with audit ID, effective time, actor, actor type, action, protected object, result, source system, IP or session context, retention class, export status, and permission scope.", "Show coverage, custody, retention, legal hold, redaction, administrative-unit scope, API or SIEM handoff, and tamper-evidence state close to the audit records so reviewers know what the log can prove." ], "uxGuidance": [ "Use audit log when the product must support security review, compliance obligations, forensic investigation, privileged-action review, or administrator accountability with retained evidence.", "Help reviewers trust and challenge the record: make gaps, delayed ingestion, retention limits, scoped access, redaction, export mismatch, duplicate ingestion, and tamper checks visible rather than treating the log as a normal activity list." ], "uiExamples": { "good": [ "A security audit log shows a role escalation with audit ID, UTC effective time, actor session, target account, old role, new role, source IP, retention class, legal-hold badge, and Export evidence action.", "A compliance search result says Restricted admin scope, 48 records visible, 7 records redacted, 10-year retention policy active, and SIEM stream healthy before the reviewer exports." ], "bad": [ "A settings page lists Admin changed something with no stable audit ID, actor session, object, result, retention policy, or export trail.", "A log viewer lets admins delete sensitive audit records from the UI without retention policy, legal-hold status, or tamper evidence." ] }, "uxExamples": { "good": [ "An investigator filters privileged actions, opens one audit record, verifies the chain of custody, exports the exact scoped result set, and sees which fields are redacted by administrative-unit scope.", "A compliance owner checks that API-key updates stream to the SIEM, that skipped records are marked, and that retention policy covers the required period before closing an investigation." ], "bad": [ "A reviewer assumes no event happened because their restricted scope hides system-account records without saying so.", "An export contains more records than the screen, uses another timezone, and has no evidence hash or export job ID." ] }, "problemContext": [ "Events may include role changes, login policy changes, API key updates, project archival, data export, file access, admin setting changes, AI prompt-response audit, sharing policy changes, and system or service-account activity.", "Reviewers may be security analysts, compliance teams, legal investigators, restricted administrators, enterprise owners, incident responders, auditors, or platform administrators.", "The log may be subject to retention policies, legal hold, role-gated access, administrative-unit scoping, redaction, API rate limits, SIEM streaming, export caps, and licensing differences.", "The design must show whether missing records are outside scope, outside retention, delayed, redacted, not generated by license, deleted by policy, or unavailable because ingestion failed." ], "selectionRules": [ "Choose audit log when the record must support governed security, compliance, forensic, or administrator-accountability review.", "Use activity log when users need broad product-event inspection but not retention policy, legal hold, chain-of-custody, SIEM handoff, or compliance-grade evidence.", "Use AI output audit trail when the audit target is one generated AI output with prompt, response, model, source, tool, approval, and downstream-use lineage.", "Use version history when the primary task is restoring or comparing prior content versions rather than proving privileged event evidence.", "Use notification center when the main workflow is personal triage; reading or dismissing notifications must not remove audit records.", "Show audit ID, actor, actor type, effective time, action, object, result, source, request or session context, retention class, permission scope, and export eligibility for each record.", "State coverage limits such as retention period, license tier, event families, API-only records, delayed ingestion, redacted fields, and restricted administrator scope.", "Make export, API query, SIEM stream, legal hold, and evidence package states explicit and reconcile them with the visible query.", "Do not offer delete, edit, mark-read, or dismiss actions on audit evidence unless the backend policy supports that action and the log records the action itself.", "Represent tamper evidence, hash mismatch, missing sequence, duplicate event, corrected record, and ingestion failure as first-class states." ], "requiredStates": [ "Default audit-log search state with visible query, result count, scope, timezone, retention class, and evidence coverage.", "Privileged action record with audit ID, actor session or API key, target object, before and after values, result, and source IP.", "Restricted administrator scope state with hidden or redacted counts and reason.", "Retention policy state showing default, extended, legal hold, expired, and archive-needed boundaries.", "Export queued, export ready, export failed, export cap reached, and export mismatch states.", "API query, pagination, rate limit, and SIEM stream healthy or delayed states.", "Tamper evidence, hash mismatch, duplicate ingestion, corrected event, and missing sequence states.", "System actor, service account, automation, integration, and human actor distinctions.", "Permission-limited, redacted, license-limited, delayed-ingestion, out-of-retention, and unavailable record states.", "Mobile compact state where audit ID, action, actor, scope, retention, and export status remain readable." ], "interactionContract": [ "Each audit row represents one governed audit record and keeps audit ID, actor, action, object, effective time, result, and retention metadata stable across filters, details, export, and API retrieval.", "Filters narrow the visible evidence without mutating, deleting, or acknowledging records.", "Opening a record shows before/after fields, actor session or API-key context, request ID, source IP, location, administrative scope, and redaction reasons when available.", "Export uses the visible query, timezone, redaction level, field set, retention scope, and permission scope or explains any difference before the export starts.", "Restricted-scope reviewers see that records are hidden or redacted without gaining access to protected values.", "SIEM, API, legal hold, and evidence-package handoffs expose job ID, cursor or page state, hash or integrity status, and failure or retry state.", "Audit evidence is not cleared by notification read state, dashboard dismissal, object deletion, or ordinary activity-feed cleanup.", "Any correction, deletion, retention expiry, legal-hold change, or export action creates its own audit record when the backend supports that event." ], "implementationChecklist": [ "Define audit schema with audit ID, immutable event ID, effective timestamp, ingestion timestamp, actor, actor type, action, object, object type, result, source system, request ID, session or API key context, IP, location, before and after fields, retention class, and integrity state.", "Map event families to retention policies, licensing requirements, access roles, administrative-unit scopes, export caps, SIEM destinations, and legal-hold behavior.", "Expose query, filters, timezone, result count, hidden count, redacted count, retention window, ingestion freshness, and permission scope next to the record list.", "Implement details, copy audit ID, export evidence, API query, SIEM stream status, legal hold, retention archive, request access, and incident note actions with visible status.", "Model restricted admin access, no-permission fields, redacted values, out-of-retention records, delayed ingestion, failed export, rate limit, duplicate events, corrected events, and tamper-check failures.", "Prevent UI actions that imply audit evidence can be casually edited, dismissed, or deleted.", "Test privileged role changes, API-key updates, failed logins, data export events, object deletion, system actor events, restricted-scope review, export caps, legal hold, SIEM delay, mobile wrapping, keyboard expansion, and screen reader row identity." ], "commonMisuses": [ "Rebranding a recent-activity feed as an audit log without retention, custody, or governed evidence fields.", "Omitting audit ID, actor type, effective time, result, scope, retention, or source system from the visible record.", "Letting privileged users edit, delete, dismiss, or mark audit evidence read without policy and self-auditing.", "Hiding restricted-scope or redacted records so reviewers think no event happened.", "Exporting a different query, timezone, field set, redaction level, or record range than the screen shows.", "Logging raw secrets, tokens, private files, or sensitive AI prompts into broad audit views without redaction.", "Treating delayed ingestion, duplicate delivery, rate limits, or missing sequences as normal empty results." ], "critiqueQuestions": [ "What compliance, security, forensic, or administrator-accountability question must this audit log prove?", "Which event families are captured, retained, licensed, delayed, API-only, or out of coverage?", "Can reviewers see audit ID, actor, actor type, action, object, effective time, result, source, scope, retention, and export eligibility?", "What is hidden by role, administrative unit, legal hold, redaction, or retention policy?", "Does export, API access, or SIEM streaming match the visible query and explain caps or delays?", "How does the UI reveal tamper checks, hash mismatch, duplicate ingestion, missing sequence, or corrected records?" ], "relatedPatterns": [ "activity-log", "ai-output-audit-trail", "version-history", "permission-sharing", "security-warning", "table", "data-grid", "notification-center", "change-review", "details-panel" ], "comparisons": [ "audit-log-vs-activity-log-vs-ai-output-audit-trail-vs-version-history-vs-notification-center" ], "sourceIds": [ "microsoft-purview-audit-solutions", "microsoft-purview-audit-search", "github-enterprise-audit-log-api", "atlassian-view-audit-log-activities", "openai-admin-audit-logs-api" ] }, { "id": "autocomplete", "completionStatus": "complete", "name": "Autocomplete", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Input widget with suggestion behavior", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to enter a known value quickly without memorizing exact spelling, codes, or names.", "solution": "Let users type into an input and choose from matching known values, while keeping typed input visible and editable.", "uiGuidance": [ "Render a labeled text field, suggestion popup, highlighted option, selected value, and no-match state.", "Expose clear visual states for expanded, focused, highlighted, and selected options." ], "uxGuidance": [ "Help users complete a known value faster without forcing an incorrect suggestion.", "Preserve typed input and make selection reversible before submission." ], "uiExamples": { "good": [ "Persistent label above the input, readable text size, clear popup alignment, and visible highlighted option.", "Suggestions include enough secondary text or spacing to distinguish similar values without crowding." ], "bad": [ "Placeholder-only label that disappears after typing.", "Popup visually detached from the field, tiny options, or highlight shown only by low-contrast color." ] }, "uxExamples": { "good": [ "Typing filters suggestions while preserving the exact typed value.", "Clicking or pressing Enter on a suggestion commits it and keeps the final value editable." ], "bad": [ "Automatically forcing the first suggestion into the field.", "Submitting a stale hidden ID after the user edits the visible text." ] }, "problemContext": [ "The accepted values come from a known or searchable dataset.", "Typing part of the value is faster than browsing the whole list." ], "selectionRules": [ "Choose autocomplete for constrained or semi-constrained values.", "Keep free text valid only when the domain permits it.", "Show enough context to distinguish similar suggestions." ], "requiredStates": [ "Empty input state.", "Suggestion popup state.", "Highlighted option state.", "Selected value state.", "No matching option state." ], "interactionContract": [ "Typed text remains under user control.", "Selecting an option updates the input and selected value consistently.", "The popup state is exposed to keyboard and assistive technology users." ], "implementationChecklist": [ "Use native datalist where sufficient or an accessible combobox implementation.", "Expose active option and expanded state.", "Handle slow remote results and stale responses.", "Validate final value according to domain rules." ], "commonMisuses": [ "Forcing the first suggestion when the user did not choose it.", "Using autocomplete where users expect broad search results.", "Showing identical labels without disambiguating context." ], "critiqueQuestions": [ "Is the user completing a known value rather than discovering unknown content?" ], "relatedPatterns": [ "search-suggestions", "select" ], "comparisons": [ "search-suggestions-vs-autocomplete" ], "sourceIds": [ "ontario-design-system-autocomplete", "wai-aria-apg" ] }, { "id": "automation-rule-builder", "completionStatus": "complete", "name": "Automation rule builder", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Rule authoring surface for defining event triggers, conditions, actions, tests, activation, and runtime safeguards", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Automation rules can create repeated side effects long after authoring, but builder UIs often hide trigger scope, condition logic, action targets, permissions, test evidence, activation state, conflicts, and runtime safeguards.", "solution": "Provide a rule authoring flow that separates trigger, condition, branch, action, scope, permission, test, activation, and monitoring state, then require validation and preview evidence before users enable the rule.", "uiGuidance": [ "Render automation rule builder as a structured authoring surface with rule name, trigger, scope, conditions, branch logic, actions, recipients or targets, test data, previewed matching records, activation state, run history, and owner.", "Separate trigger configuration from condition logic and action effects, and show plain-language summaries so users can inspect exactly when the automation runs and what it will change before enabling it." ], "uxGuidance": [ "Use automation rule builder when users need to create or edit reusable if/when-then rules that run later without them being present.", "Make automation safe to activate: validate missing pieces, preview matches, test with sample events, disclose permissions and side effects, handle conflicting rules, and provide pause, draft, rollback, and audit paths." ], "uiExamples": { "good": [ "A support admin creates a rule: When priority is high and sentiment is negative, assign to Escalations, notify the manager, and pause if the customer is VIP; the builder previews matching tickets and lets the admin run a dry test.", "A workflow rule builder shows trigger, filters, branch, action, target, permission warning, owner, last edited time, and Enable rule only after validation passes." ], "bad": [ "A page has one text box labelled Automation instructions and an Enable button, with no trigger, condition, action, or test preview.", "A rule says Send notification on update but hides the fields, recipients, repeat limits, and whether it will run on existing records." ] }, "uxExamples": { "good": [ "A team lead edits an assignment rule, sees that 18 current tickets would match, tests one sample ticket, notices a conflict with an older VIP rule, resolves priority order, and activates the rule with run logging enabled.", "A user drafts a reminder rule, leaves it disabled while legal reviews recipient scope, then returns to the same draft with validation errors and unsaved changes preserved." ], "bad": [ "A rule activates immediately while the user is still choosing conditions and sends messages to hundreds of customers.", "Two overlapping automations both update owner fields and the UI never warns about order, loop risk, or duplicate actions." ] }, "problemContext": [ "Users may be configuring automations for support routing, notifications, reminders, approvals, assignments, deployments, content publishing, lifecycle state changes, data sync, lead routing, or AI-assisted actions.", "Rules typically combine a trigger event, one or more conditions, optional branches, one or more actions, target objects, timing, repeat limits, owner, permissions, and runtime state.", "The builder may be no-code, low-code, natural-language assisted, YAML-backed, or form-based, but users still need inspectable semantics before activation.", "Automation can cause messages, assignments, external calls, status changes, approvals, tickets, alerts, or data updates, so side effects need preview, confirmation, and observability.", "Rules can overlap, conflict, loop, exceed limits, run outside business hours, fail due to permissions, or become stale after schemas, fields, integrations, or recipient lists change." ], "selectionRules": [ "Choose automation rule builder when the primary job is authoring a reusable rule with trigger, condition, action, activation, and future runtime behavior.", "Use human approval gate when automation is already paused at runtime and a human must authorize a specific armed step before it continues.", "Use approval workflow when a submitted request moves through approver decisions over time rather than defining the rule that creates or routes those requests.", "Use settings management when users are changing persistent preferences or configuration values, not composing event-condition-action automation.", "Use complete complex form when the task is a one-time configuration object with dependencies but no future autonomous run behavior.", "Use recommended next action when the system suggests one optional action in context; use automation rule builder when users define rules that will repeatedly choose or execute future actions.", "Use notification preferences when users choose delivery channels and frequency; use automation rule builder when they define custom event logic that may send notifications as one action.", "Expose rule ownership, enabled or disabled state, draft state, trigger source, condition groups, action targets, execution order, and last run before activation.", "Require preview or test behavior for high-impact actions, broad scope, new rules, edited active rules, natural-language generated rules, or rules that affect external users.", "Do not use automation rule builder as a broad prompt box, static settings page, hidden cron editor, or opaque AI instruction field." ], "requiredStates": [ "Empty draft state with rule name, trigger picker, condition builder, action picker, owner, and disabled activation.", "Trigger selected state showing event source, scope, supported fields, repeat behavior, and sample event payload.", "Condition builder state with groups, AND/OR logic, operators, field types, null handling, and plain-language summary.", "Action configured state showing target, payload, recipients, permission requirement, side effects, and rollback or undo availability.", "Validation error state for missing trigger, invalid operator, unreachable branch, missing permission, dangerous action, or incompatible field.", "Test run or preview state showing sample input, matched records, branch taken, action preview, skipped action, and expected output.", "Conflict state showing overlapping rules, priority order, loop risk, duplicate action, rate limit, or stale field dependency.", "Draft, active, paused, scheduled, failed, disabled, archived, versioned, and last-run states.", "Natural-language generated rule review state with parsed trigger, conditions, actions, assumptions, and editable structured fields.", "Mobile compact builder state with rule summary, validation, activation, and run status visible without hiding dangerous effects." ], "interactionContract": [ "The rule cannot be activated until trigger, condition, action, owner, permissions, and required validation pass.", "Every rule has a plain-language summary that updates as users edit structured trigger, condition, branch, and action fields.", "Users can test the rule against sample or real read-only events before activation and see why the rule matched or did not match.", "Activation is distinct from saving a draft, and edited active rules show whether changes create a new version or update the live rule.", "The builder warns about broad scope, external recipients, destructive actions, high-frequency triggers, missing permissions, loops, duplicate actions, and conflicts with other rules.", "Users can pause, disable, clone, archive, roll back, or inspect run history according to their permission level.", "Natural-language or AI-authored rules must be converted into inspectable trigger, condition, and action fields before enabling.", "Runtime failures link back to the rule version, input event, skipped branch, failed action, and recovery path." ], "implementationChecklist": [ "Model rule name, owner, trigger source, event type, scope, condition groups, operators, values, branches, actions, targets, permissions, enabled state, version, priority, schedule, and run history separately.", "Provide field-aware condition editors with type-specific operators, null handling, validation, and plain-language summaries.", "Implement a test runner or dry-run preview that shows sample event input, matched records, branch decisions, actions that would run, and actions skipped.", "Detect conflicts such as overlapping conditions, priority clashes, loops, duplicate notifications, repeated assignments, broad recipient scope, and stale schema fields.", "Separate save draft, enable rule, pause rule, disable rule, clone, archive, rollback, and publish changes.", "Log rule creation, edits, activation, deactivation, test runs, runtime failures, permission failures, and manual overrides.", "Check accessibility for grouped condition controls, dynamic rows, operator menus, validation summaries, status messages, keyboard reordering, and focus preservation after adding branches or actions." ], "commonMisuses": [ "Treating a natural-language automation prompt as complete without showing parsed trigger, conditions, and actions.", "Activating a rule immediately after save without a separate enabled state or preview.", "Hiding which existing records or future events will match the rule.", "Using one broad settings toggle for behavior that needs trigger, condition, action, and scope review.", "Ignoring conflicts between active rules that update the same object or send duplicate notifications.", "Showing run history without a way to edit, pause, test, or fix the rule." ], "critiqueQuestions": [ "Can users explain exactly when the rule runs and what it will do before enabling it?", "Does the builder distinguish save draft from activate rule?", "Can users test the rule with sample input and inspect why it matched or skipped?", "Are broad scope, external side effects, permission limits, conflicts, and loop risks visible?", "Does an active rule have version, owner, run history, pause, rollback, and failure recovery paths?" ], "relatedPatterns": [ "human-approval-gate", "approval-workflow", "settings-management", "complete-complex-form", "recommended-next-action", "notification-preferences", "tool-use-visibility", "agent-plan-preview", "review-before-submit", "activity-log" ], "comparisons": [ "automation-rule-builder-vs-human-approval-gate-vs-approval-workflow-vs-settings-management-vs-complete-complex-form-vs-recommended-next-action" ], "sourceIds": [ "microsoft-power-automate-triggers-actions", "microsoft-power-automate-trigger-conditions", "microsoft-power-automate-add-condition", "github-actions-workflow-syntax", "github-actions-job-conditions", "microsoft-teams-emoji-reaction-workflows", "wcag-status-messages" ] }, { "id": "autosave-form", "completionStatus": "complete", "name": "Autosave form", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Background-saving form progress", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Long or interruption-prone forms lose trust when users cannot tell whether their latest progress is pending, saved, failed, recoverable, or merely stored as a draft awaiting final submission.", "solution": "Persist safe form changes automatically with visible status, per-field or per-section ownership, delayed typing saves, immediate safe toggles, retryable failure, leave-page protection, and clear separation between autosaved draft progress and final submit or activation.", "uiGuidance": [ "Render a clear autosave message before users start, then keep a persistent status surface for Pending, Saving, Saved with timestamp, Failed, Retry, and unsafe-to-leave states.", "Show which field or section is pending when only part of the form has changed; do not claim the whole form is saved until every autosave request needed for progress preservation has succeeded." ], "uxGuidance": [ "Use autosave when losing progress would hurt and background persistence is safer than making users hunt for a distant Save button.", "Treat autosave as a contract: preserve progress reliably, warn before users leave with pending or failed saves, and keep final Submit or Review separate when autosave only stores a draft." ], "uiExamples": { "good": [ "A long application step says the application is saved on every change, shows Saving after an edited title blurs, then shows Draft saved just now with a timestamp.", "A content editor saves a changed description as a draft in the background and keeps a visible Retry action when the latest autosave fails." ], "bad": [ "A form removes the Save button and shows no save status, leaving users unsure whether typed answers are safe.", "A green Saved toast appears after one field saves, while another changed field is still pending or failed." ] }, "uxExamples": { "good": [ "A user writes a long answer, pauses, sees Saving, then sees Draft saved just now and can leave knowing the draft is recoverable.", "A network failure occurs after a field change; the form keeps the typed value, shows Failed to autosave with Retry, and warns before the user navigates away." ], "bad": [ "A user leaves after seeing an old saved message, but the newest field was never persisted.", "A password or permission field autosaves immediately and takes effect before the user reviewed the consequence." ] }, "problemContext": [ "The form is long, time-consuming, interruption-prone, or likely to be completed over multiple sessions.", "Losing typed answers, comments, descriptions, uploads, or application progress would be costly.", "The system can persist partial progress safely without treating the draft as final submitted data.", "Users are authenticated or otherwise have a reliable place where saved progress can be restored." ], "selectionRules": [ "Choose autosave form when background progress preservation is safer than relying only on a final Save button.", "Use single-page form instead when the task is short and users should intentionally submit one related set of fields.", "Use multi-step form when the larger requirement is a page sequence with Back, Continue, saved step state, and final review.", "Use inline edit when one visible value changes locally with explicit Save and Cancel.", "Treat autosave as draft/progress preservation unless the product clearly states that each change is the final committed state.", "Autosave only safe, reversible, user-owned progress by default; require review or manual save for financial, security, privacy, permission, destructive, or externally visible changes.", "Save each field or section with its own pending and failed state when dependencies allow; do not say all changes are saved because one request succeeded.", "Use blur and short debounce timing for typing fields; use immediate autosave for safe toggle or selection changes only when users can undo or recover.", "Keep a persistent retryable error when autosave fails and warn users before they leave with pending or failed changes.", "Show a timestamp or equivalent recency cue so users can tell whether the message refers to the latest change." ], "requiredStates": [ "Initial state that explains progress will be saved automatically.", "Clean saved state with timestamp or recent-saved wording.", "Dirty pending state after a field changes but before the autosave request starts.", "Saving state with visible background activity.", "Saved state after the latest changed field or section succeeds.", "Failed autosave state with manual Retry and preserved draft value.", "Offline or unavailable state that explains progress is not currently saved.", "Leave-page warning state for pending or failed changes.", "Undo or restore state when a recent autosaved change can be reversed.", "Final submit or review state when the autosaved draft still needs intentional completion." ], "interactionContract": [ "Editing a field marks that field or section pending without clearing the user's value.", "Autosave starts on the defined trigger, such as blur, a short pause after typing, or safe immediate control change.", "Saving feedback remains visible while the background request is in flight.", "Saved feedback is shown only after the latest relevant change succeeds and includes a recency cue.", "Failed autosave keeps the draft editable, identifies the affected field or section, and offers Retry.", "Navigation away is blocked or warned when changes are pending, failed, or not yet recoverable.", "Final Submit, Review, Publish, or Activate remains separate when autosave only stores draft progress." ], "implementationChecklist": [ "Classify fields as safe for autosave, unsafe for autosave, or draft-only before building the form.", "Define autosave triggers per input type: blur or debounce for typing, immediate for safe toggles, and manual save for unsafe changes.", "Track dirty, pending, saving, saved, failed, offline, and last-saved timestamp state separately.", "Store field-level or section-level save ownership so one success cannot mask another failed change.", "Keep typed values in the UI and retry queue after failed saves.", "Add leave-page protection for pending or failed saves.", "Use status text, not color alone, and connect autosave messaging to Continue or submit actions when users might miss it.", "Clarify whether autosave creates a draft, updates an active record, or only preserves progress until final submit.", "Test slow network, failed requests, reload recovery, session expiry, duplicate tabs, undo, retry, screen reader status, and mobile backgrounding." ], "commonMisuses": [ "Removing the Save button while providing no autosave status.", "Showing Saved when only an older change was saved.", "Autosaving sensitive, destructive, financial, password, or permission changes without explicit review.", "Auto-saving the whole form label when validation or persistence is actually field-specific.", "Auto-dismissing failed-save feedback before recovery succeeds.", "Letting users navigate away with pending or failed autosaves and no warning.", "Mixing autosave and manual save on the same fields without labeling the difference.", "Treating an autosaved draft as submitted data without a final user action." ], "critiqueQuestions": [ "Which fields are safe to autosave and which require explicit review?", "Can users tell whether the latest edit, not just an older edit, was saved?", "What happens when autosave fails or the network drops?", "Does leaving the page with pending changes show a warning?", "Is autosave preserving a draft or committing final submitted data?", "Does the form still need a final Submit, Review, Publish, or Activate action?" ], "relatedPatterns": [ "single-page-form", "multi-step-form", "inline-edit", "complete-complex-form", "error-state" ], "comparisons": [ "autosave-form-vs-single-page-form-vs-multi-step-form-vs-inline-edit" ], "sourceIds": [ "gitlab-saving-and-feedback", "va-autosave-component", "sap-fiori-draft-handling" ] }, { "id": "autosave-recovery", "completionStatus": "complete", "name": "Autosave recovery", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Recovery surface for failed or uncertain background saves", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Autosave can fail, stall, expire, conflict, or remain local-only while the interface still suggests progress is safe, causing users to lose text, submit stale data, overwrite versions, or distrust saved-state messaging.", "solution": "Detect uncertain autosave states, preserve the latest local value, expose last saved and local-copy evidence, block unsafe continuation when needed, and provide scoped recovery actions for retry, restore, compare, copy, reauthenticate, or continue after save succeeds.", "uiGuidance": [ "Show a persistent recovery surface when autosave did not protect the latest work, naming the affected field or section, last server-saved time, local copy status, and available recovery actions.", "Keep the user's latest local value visible or copyable until recovery succeeds, and distinguish Retry save, Keep local copy, Restore last saved, Compare versions, Download copy, and Continue after recovery." ], "uxGuidance": [ "Use autosave recovery when users need to preserve effort after background saving fails, stalls, conflicts, expires, or only stores a local copy.", "Treat recovery as a data-integrity workflow: do not allow submit, navigation, or reload to silently discard the latest local work or overwrite a newer server version." ], "uiExamples": { "good": [ "A claim form says Household income answer failed to autosave at 10:42, keeps the typed answer visible, and offers Retry save, Copy answer, Restore last saved, and Continue after saved.", "A content editor detects a local autosave after reload, shows local and server timestamps, and lets the user restore, compare, or discard the local copy." ], "bad": [ "A small toast says Could not save and disappears while the form still shows a green Saved label.", "The app clears the field after a failed autosave and offers only Reload page." ] }, "uxExamples": { "good": [ "A user loses network while writing a long answer, sees it is saved on this device only, reconnects, retries the same value, and continues after the timestamp updates.", "A user returns after session expiry, reauthenticates, compares the local answer with the older server answer, and keeps the local version without retyping." ], "bad": [ "A user submits after seeing Saved, but the newest section was failed and never reached the server.", "A user opens the same draft in two tabs and the later autosave overwrites the first tab without any conflict or recovery choice." ] }, "problemContext": [ "The product already uses autosave or local draft persistence for meaningful form, editor, upload, or configuration work.", "The latest value may differ from the last server-saved value because of network failure, session expiry, offline mode, validation rejection, conflict, duplicate tab editing, or app reload.", "Users need to know whether the newest work is on the server, only on this device, failed, stale, conflicted, or gone.", "Continuing, submitting, publishing, or leaving could discard a local copy or commit an older server value." ], "selectionRules": [ "Choose autosave recovery when a background save did not complete or cannot prove that the latest value is safe.", "Use autosave form for the ordinary save model before failure; autosave recovery begins when the model needs repair or preservation.", "Use draft state when users are managing a durable unpublished object across lists, publish boundaries, or shared draft ownership.", "Use retry for a simple failed operation only when no local unsaved value, timestamp ambiguity, or version choice must be preserved.", "Escalate to conflict state or conflict resolution when local and server versions both changed and users need to compare or merge them.", "Escalate to session timeout warning or reauthentication when recovery depends on restoring an authenticated session.", "Show the last saved timestamp, failed attempt time, affected section, and storage location such as server, this device, or browser storage.", "Keep the local value editable or copyable while recovery actions run; do not clear it before a successful server save or explicit discard.", "Disable or explain Submit, Publish, Continue, and navigation while failed or uncertain autosave would make the next step unsafe.", "After successful recovery, clear stale failed-save warnings and update the visible saved state to the recovered version." ], "requiredStates": [ "Clean saved state with current server timestamp.", "Dirty or pending local state waiting for autosave.", "Failed autosave state with affected field or section named.", "Local-only saved-on-this-device state.", "Retrying same value state with duplicate submission blocked.", "Recovered saved state with updated timestamp.", "Restore last server-saved version state.", "Recovered local copy after reload or return state.", "Version conflict or compare-needed state.", "Expired session or reauthentication-needed recovery state." ], "interactionContract": [ "The recovery surface appears close to the affected form, section, editor, or submit action and remains until the risk is resolved.", "Retry save sends the latest local value with the same field or section identity and prevents duplicate retry requests.", "Copy answer or Download copy lets users preserve local work even if the server remains unavailable.", "Restore last saved names the timestamp and consequence before replacing a newer local value.", "Compare versions shows local and server evidence when overwrite risk exists.", "Submit, Publish, or Continue is blocked or intercepted while latest required work is failed, local-only, conflicted, or unverified.", "Recovery success updates the timestamp and returns focus or status to the affected task without forcing users to retype." ], "implementationChecklist": [ "Track server-saved value, local value, local storage key, field or section owner, save request ID, saved timestamp, failed timestamp, and retry state separately.", "Persist local copies through reload, app restart, backgrounding, and reauthentication when policy allows.", "Keep failed-save messages persistent and attached to the field, section, or submit area until recovery completes.", "Make retry idempotent and scoped to the same local value; disable duplicate Submit and Retry while saving.", "Expose safe manual preservation such as Copy answer, Download draft, or Save local copy when server recovery may fail.", "Handle validation rejection, offline mode, session expiry, duplicate tabs, stale server versions, and storage quota failures as separate recovery states.", "Log recovery outcomes for diagnostics without recording sensitive field values.", "Test slow network, failed request, offline return, reload restore, session expiry, two tabs, conflict, copy fallback, keyboard access, and screen reader status updates." ], "commonMisuses": [ "Leaving a green Saved label visible after a failed or stale autosave.", "Showing only a disappearing toast for work that may be lost.", "Retrying a save after clearing the local value.", "Letting users submit an older server version while the newest local answer failed.", "Overwriting server changes from another tab or collaborator without comparison.", "Treating local browser storage as server-saved progress.", "Forcing reload or sign-in again without preserving a return target and local copy." ], "critiqueQuestions": [ "What exact field, section, upload, or object is not safely saved?", "Where is the newest value now: server, this device, memory, browser storage, another tab, or nowhere?", "What timestamp or version proves the visible Saved message refers to the latest edit?", "Can users retry, copy, restore, compare, or reauthenticate without losing the local value?", "What actions must be blocked until recovery succeeds?", "How does the UI resolve a conflict between local and server-saved values?" ], "relatedPatterns": [ "autosave-form", "draft-state", "retry", "exit-warning", "session-timeout-warning", "offline-state", "conflict-state", "sync-state" ], "comparisons": [ "autosave-recovery-vs-autosave-form-vs-draft-state-vs-retry" ], "sourceIds": [ "gitlab-saving-and-feedback", "va-autosave-component", "sap-fiori-draft-handling", "atlassian-confluence-drafts" ] }, { "id": "back-link", "completionStatus": "complete", "name": "Back link", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Single previous-page return link for a transaction", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users in a multi-page transaction need an explicit, predictable way to return to the previous service page without losing progress or interpreting hierarchy navigation.", "solution": "Provide one Back link at the top of transaction pages that returns to the previous page in its last-seen state, with clear target text when the journey is complex and safe fallback behavior when history or JavaScript is unreliable.", "uiGuidance": [ "Render one unobtrusive Back link near the top-left of a transaction page, before the main content, with a destination that returns to the previous service page.", "Use a normal link when navigating to a known previous URL, and render it as a button only when the control must submit or post current form state back to the previous page." ], "uxGuidance": [ "Use Back links to help users safely move one step back in a multi-page transaction without relying on browser history or losing previously entered information.", "Preserve the previous page in the state the user last saw it; if that cannot be guaranteed, hide the control without JavaScript or use a server-backed route that can restore state." ], "uiExamples": { "good": [ "A question page shows a single 'Back' link above the H1, before the form, and the Continue button remains the only primary action after the fields.", "A complex admin journey labels the control 'Back to eligibility' so users know which page they will return to.", "A dark header variant uses an inverse back link with sufficient contrast and no competing links nearby." ], "bad": [ "A page shows Back, breadcrumbs, a previous button, and pagination controls at the same time.", "The Back link sits next to Continue and looks like a secondary form action rather than navigation.", "A JavaScript-only Back link appears when there is no safe previous page and fails when scripts are unavailable." ] }, "uxExamples": { "good": [ "A user goes back from Review answers to Contact details and sees the email address and phone number they already entered.", "A user who is unsure about an answer can return one page, change it, and continue without re-entering unrelated data.", "A direct-entry page hides the Back link or sends users to a safe service start page instead of calling an empty browser history stack." ], "bad": [ "Clicking Back returns to the browser's previous marketing page instead of the last service page.", "Going back clears the previous page's fields, forcing the user to re-enter information.", "Back jumps to a parent category page even though the user is in a linear question flow." ] }, "problemContext": [ "The journey has multiple pages or questions and users may need to revise a previous answer.", "Users may distrust or misunderstand the browser Back button because some services lose progress when it is used.", "The current page is part of a transaction rather than a hierarchical content structure." ], "selectionRules": [ "Choose a Back link on question pages and other multi-page transaction pages where users may need to return one step.", "Return users to the previous page they were on in the state they last saw it, including pre-populated valid answers.", "Use simple 'Back' text for simple linear services, and use target-specific text such as 'Back to eligibility' when the journey has branching or admin areas.", "Never show a Back link together with breadcrumbs; research which is more useful if both seem plausible.", "Do not use a Back link on ordinary content pages where hierarchy, related links, or breadcrumbs better explain where the page sits.", "Do not rely on JavaScript-only history if there may be no safe previous page; provide a real href, hide the link without JavaScript, or route through server state.", "Use a button only when the back control needs to post form data back; otherwise keep it a navigation link." ], "requiredStates": [ "Default transaction page with one Back link before main content.", "Previous-page restored state with valid entered values pre-populated.", "Complex journey state with target-specific back text.", "No safe previous page or no-JavaScript state where the control is hidden or uses a safe route.", "Button-backed state when current form data must be posted before returning.", "Validation state where returning preserves valid entries and does not silently reuse invalid or unsafe information." ], "interactionContract": [ "Activating the Back link returns one service step or previous transaction page, not a parent hierarchy page.", "The destination page restores the values, filters, or answers the user last saw when those values remain valid.", "The Back link appears before main content in reading order so skip links can bypass it with other navigation.", "The control does not submit the current page unless it is deliberately implemented as a button to preserve posted form data.", "If the destination is ambiguous, the visible text names the target page rather than relying on a generic Back label.", "The control is removed, disabled by routing, or changed to a safe URL when there is no trusted previous transaction page." ], "implementationChecklist": [ "Place the Back link before the main content and away from primary submit or Continue controls.", "Store transaction step state server-side, in the URL, or in form state so the previous page can be restored.", "Use a real href to the previous service URL where possible instead of depending only on window.history.back().", "Pre-populate previous answers when the user goes back, unless the information is invalid, unsafe, or security-sensitive.", "Remove breadcrumbs from pages that use a transaction Back link.", "Choose target-specific copy for non-linear or administrative journeys.", "Test keyboard order, focus visibility, target size, and no-JavaScript fallback." ], "commonMisuses": [ "Using Back as a breadcrumb or parent-category link.", "Combining Back links with breadcrumbs on the same transaction page.", "Putting Back next to Continue so it looks like a secondary form action.", "Calling browser history when the previous page might be outside the service.", "Clearing the previous page's entered values when users go back.", "Showing a Back link on content pages that need hierarchy or related-link navigation instead." ], "critiqueQuestions": [ "What exact page will this Back link return to, and can that page restore its last-seen state?", "Is this page part of a transaction, or would breadcrumbs or related links better fit the user's mental model?", "Will a direct visitor or user without JavaScript see a safe and honest control?", "Does the link text need to name the destination because the journey branches?", "Could the previous values become invalid, unsafe, or security-sensitive when restored?" ], "relatedPatterns": [ "breadcrumbs", "pagination", "undo" ], "comparisons": [ "back-link-vs-breadcrumbs-vs-pagination" ], "sourceIds": [ "govuk-back-link-component", "nhs-back-link-component", "va-link-component" ] }, { "id": "bank-details", "completionStatus": "complete", "name": "Bank details", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Secure bank account identification and verification form", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Bank account details are high-consequence, easy to mistype, and region-specific, so generic fields, silent formatting, or unverified collection can misdirect money or expose sensitive information.", "solution": "Collect bank account parts in a secure grouped form, validate each part with tolerant formatting, support optional account-specific fields, explain verification results, preserve user-entered values, and show a masked review before money moves.", "uiGuidance": [ "Render bank details as a secure grouped form with account holder name, routing identifier, account number, optional roll number or regional equivalent, clear hints, field-specific errors, verification status, and a masked review summary.", "Use widths, grouping, and examples that match the financial identifier being copied, while keeping labels persistent and avoiding placeholder-only instructions." ], "uxGuidance": [ "Use bank details when the service needs an account to pay a user, collect a direct debit, issue a refund, run payroll, initiate a bank payment, or save a payout destination.", "Help users enter, verify, and review the account safely by tolerating spacing, preserving values after errors, explaining verification outcomes, and avoiding unstructured collection channels." ], "uiExamples": { "good": [ "A refund form asks for Name on the account, Sort code, Account number, and Building society roll number (optional), then shows a masked summary before Confirm payout.", "An ACH setup flow asks for Account holder name, Routing number, Account number, account type only when the processor requires it, and then shows pending micro-deposit verification." ], "bad": [ "A form has one field labelled Bank details and asks users to paste name, account number, sort code, and notes together.", "The page asks users to email a bank statement or bank details attachment instead of collecting details securely inside the service." ] }, "uxExamples": { "good": [ "A user types a sort code with spaces, the form normalizes it to 12-34-56, checks the account holder name, warns about a close match, and lets the user review before payout.", "A user with a building society roll number enters it in an optional field; a user without one leaves it blank without being forced to choose an account type." ], "bad": [ "A user mistypes one digit and the service silently accepts the account, then the payment fails days later with no field-level recovery.", "A form rejects a pasted sort code with dashes even though the digits are valid and the user is copying from their bank." ] }, "problemContext": [ "The product needs to pay money to a user, collect money by bank debit, refund to a bank account, set up payroll, save a payout account, or initiate an account-to-account payment.", "Accepted identifiers vary by region and rail, such as UK sort code and account number, U.S. routing and account number, IBAN, roll number, saved account selection, or bank redirection.", "Users may copy from bank apps, cards, statements, checks, employer portals, or building society passbooks and may include spaces, hyphens, or line breaks.", "Verification can produce more than one outcome: format valid, account exists, name match, close match, no match, pending micro-deposit, failed verification, or user override.", "Bank details are sensitive enough to require secure collection, masked display, access control, audit logging, and careful recovery flows." ], "selectionRules": [ "Choose bank details when the service needs financial account identifiers for payout, debit, refund, payroll, account linking, bank transfer, or payment initiation.", "Ask for the fields required by the payment rail and country, not a generic bank details blob.", "Use sort code and account number for UK domestic account details when that is the supported payment route.", "Use routing number and account number for U.S. ACH flows, plus account type only when the processor or rail requires it.", "Use IBAN, BIC, or bank redirection when the selected country, payment rail, or open-banking flow requires those identifiers.", "Do not ask users whether they have a bank account or building society account when an optional roll number field is enough.", "Make roll number, secondary reference, or regional account addenda optional unless the user or payment provider indicates it is required.", "Accept pasted identifiers with spaces, hyphens, and common grouping, then normalize them visibly before validation.", "Validate each part separately and preserve all entered values after a failed check.", "Treat account validation, Confirmation of Payee, instant verification, and micro-deposits as verification states that users can understand and recover from.", "Show enough masked detail on review to let users recognize the account, such as account holder name, sort code, last digits, and verification status.", "Do not collect bank account details by email, chat, free-text attachment, screenshot, or unsupported file upload.", "Route bank-detail changes through review before submit when money, payroll, benefits, refunds, or account ownership will change." ], "requiredStates": [ "Initial secure collection state with purpose, account holder name, routing field, account number, optional roll number or regional equivalent, and hints.", "Focused entry state with persistent labels and widths that match expected identifier lengths.", "Pasted value state where spaces, hyphens, and line breaks are normalized without losing digits.", "Missing account holder name error state.", "Invalid routing identifier state with a field-specific correction.", "Invalid account number state with preserved account number and exact length or digit guidance.", "Optional roll number provided and not provided states.", "Verification pending state for micro-deposit, processor, or bank-response checks.", "Verified account match state with masked account summary.", "Close-match or name-mismatch state requiring user review.", "No-match or failed verification state with correction, alternate verification, or support path.", "Submitted or saved state that stores the account securely and shows only masked details on later pages." ], "interactionContract": [ "Users can paste account details from trusted sources without losing spacing, leading zeros, or roll-number characters.", "Formatting changes are visible and do not silently change the canonical account number.", "Submitting incomplete details highlights the exact missing or invalid field while preserving every typed value.", "Optional roll-number or regional fields never block users who genuinely do not have that value.", "Account validation results are displayed as match, close match, no match, pending, failed, or overridden rather than hidden behind a generic error.", "Verification that takes time creates a pending state with clear next steps and does not pretend the account is ready.", "Saved or review states mask sensitive digits while still giving users enough information to detect the wrong account.", "Changing saved bank details revalidates the new account and invalidates stale payout, debit, or payroll review state." ], "implementationChecklist": [ "Define supported countries, payment rails, required fields, optional fields, validation services, verification outcomes, masking rules, retention policy, and audit logging before designing the form.", "Use native inputs with visible labels, stable names, inputmode settings, autocomplete settings only where appropriate, and aria-describedby for hints and errors.", "Normalize pasted sort codes, routing numbers, account numbers, IBANs, and roll numbers without dropping leading zeros.", "Validate format locally where possible and verify account existence, account name, or ownership through the chosen payment provider or banking rail where required.", "Represent close-match, no-match, pending, failed, and override outcomes explicitly in the UI and backend state.", "Mask stored details on summaries, logs, analytics, notifications, and review pages unless a user is actively editing inside a secure session.", "Avoid sending bank details through email, support tickets, event telemetry, screenshots, or file uploads.", "Test paste, deletion, mobile numeric keyboards, screen readers, zoom, saved drafts, browser Back, validation outage, micro-deposit return, provider timeout, duplicate account, and review-before-submit flows." ], "commonMisuses": [ "Using one freeform field for all account details.", "Collecting bank details by email or uploaded statement when a structured secure form is available.", "Asking users to identify whether their account is a bank or building society account.", "Making building society roll number required for everyone.", "Silently stripping leading zeros or changing account numbers during formatting.", "Treating a syntactically valid account number as verified ownership.", "Showing only a generic payment failed message after a validation error.", "Masking every digit on review so users cannot recognize the account.", "Storing raw bank details in logs, analytics, local storage, or support transcripts.", "Treating bank-login account selection and manual bank-detail entry as the same recovery flow." ], "critiqueQuestions": [ "Which payment rail and country determine the exact account fields required?", "Can users paste details with spaces or hyphens without losing leading zeros?", "How does the UI represent account validation, name-match, pending verification, and failed verification states?", "Are roll numbers or regional addenda optional for users who do not have them?", "What masked details are shown so users can recognize the account before money moves?", "Where are raw bank details stored, logged, transmitted, and removed?", "What happens when a user changes saved bank details after a payout or debit is already in review?" ], "relatedPatterns": [ "text-input", "input-mask", "inline-validation", "error-summary", "review-before-submit" ], "comparisons": [ "bank-details-vs-text-input-vs-input-mask-vs-review-before-submit" ], "sourceIds": [ "govuk-bank-details-pattern", "payuk-sort-code-information", "payuk-confirmation-of-payee-faqs", "nacha-web-debit-account-validation", "plaid-auth-microdeposits", "open-banking-account-selection-pisp" ] }, { "id": "banner", "completionStatus": "complete", "name": "Banner", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Top-of-interface broad-scope message", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to know broad product, service, account, section, or trust information before interpreting several related pages, but task-local messages, toasts, or dialogs would either detach the message from scope or over-interrupt work.", "solution": "Place one scoped banner at the top of the related interface, state the broad condition and next step, persist it across affected routes, allow safe dismissal by message version, and retire or replace it when the condition changes.", "uiGuidance": [ "Render the banner at the top of the interface or content area it governs, below required global chrome and before the page content that should be interpreted with that message.", "Keep the banner concise, visually distinct, and scoped to one broad product, service, account, section, or trust message, with at most one primary action or link and a dismiss control only when hiding it is safe." ], "uxGuidance": [ "Use banners when users need broad context before continuing across several pages or sections, such as maintenance, service delay, account setup, rollout, policy, or official-site identity information.", "Manage banner lifecycle deliberately: define audience, start and end conditions, route scope, priority against other messages, dismissal memory, and what replaces the banner when the issue resolves." ], "uiExamples": { "good": [ "A billing workspace shows Scheduled maintenance Saturday directly below the product header across all billing pages, with View schedule and Dismiss when safe.", "An official service identity banner sits above the service header on every page with consistent trust text and a disclosure for domain and HTTPS details." ], "bad": [ "Three unrelated banners stack above the page heading and push the account task below the fold.", "A banner floats sticky over Save and Continue controls while users scroll the form." ] }, "uxExamples": { "good": [ "A user moves from Overview to Invoices and still sees the same maintenance banner because the outage affects the whole billing workspace.", "After a user dismisses a noncritical rollout banner, it stays hidden until a new message version or audience rule applies." ], "bad": [ "A field validation error appears in a banner, forcing users to hunt for the failing input.", "A resolved service-delay banner remains visible and keeps users from trusting current processing times." ] }, "problemContext": [ "A message applies to a whole product, service, workspace, account, section, or official site identity rather than one object or one immediate task.", "Users may enter affected pages from deep links and need context before reading the page heading or starting work.", "The message may need to persist across routes, sessions, or audiences until a release, maintenance window, identity requirement, or account condition changes.", "The message can be understood from a short title and sentence, with optional details or a link for more information." ], "selectionRules": [ "Choose banner when the message scope spans multiple pages, sections, records, or sessions in the same product, service, account, or workspace.", "Place product or system banners below the main product header or navigation and above the content area they affect.", "Place service or page-flow banners immediately before the page heading when users need the message before interpreting the page.", "Use alert instead when an urgent condition affects the current task now and requires immediate notice.", "Use inline message instead when the message belongs beside one visible object, row, panel, field group, or form section.", "Use toast notification instead when the message is low-consequence feedback that can safely expire.", "Use service navigation or header patterns for identity and movement; use a banner only for the message layered onto that structure.", "Show one highest-priority banner per scope and combine closely related broad messages instead of stacking them.", "Remember dismissal by message version, audience, and scope so users are not forced to close the same noncritical banner on every route." ], "requiredStates": [ "No-banner state when no broad-scope message applies.", "Informational product or service banner at the top of the related interface.", "Warning or error-tone banner for broad service impact that does not block the current task.", "Official identity or trust banner that stays consistent across every page in its scope.", "Expanded detail state for schedule, domain, policy, or rollout explanation.", "Dismissed state for safe noncritical banners, scoped to message version and audience.", "Resolved or expired state after the underlying broad condition ends.", "Priority state where a higher-impact banner replaces lower-priority messages instead of stacking." ], "interactionContract": [ "The banner appears before users encounter content affected by the message.", "The banner title names the broad condition, audience, or trust claim rather than a severity label alone.", "A banner persists while users move among affected sections and disappears outside its defined scope.", "Details, links, and actions are optional, concise, and clearly tied to the broad condition.", "Dismissing a banner hides only safe, noncritical messages and can be reversed through an obvious route when needed.", "The banner does not cover content, trap focus, or stay sticky over primary controls unless that behavior is explicitly required and tested.", "When multiple broad messages compete, the product chooses one visible banner by priority or combines closely related messages." ], "implementationChecklist": [ "Define the banner's scope: product, service, workspace, account, section, official identity, or page-flow.", "Decide whether the banner belongs above global navigation, below global navigation, below service navigation, or immediately before the page heading.", "Write short copy that explains what is happening, who is affected, when it applies, and what users can do next.", "Limit the banner to one link or action unless the message is a formal identity disclosure.", "Store dismissal state by message id, version, audience, and scope rather than a single global hidden flag.", "Set start, expiry, and resolved states so stale banners do not remain after maintenance, rollout, or policy windows end.", "Choose landmark, region, status, or alert semantics according to urgency and whether the banner appears dynamically.", "Test routing, deep links, mobile wrapping, zoom, scroll, dismissal, reappearance after version changes, and interactions with skip links and service navigation." ], "commonMisuses": [ "Using a banner for one field error, one row warning, or one card status.", "Stacking several unrelated banners above the page content.", "Making a banner sticky so it covers navigation, headings, form actions, or reading content.", "Using a banner for a current-task emergency that needs an alert or blocking recovery.", "Letting users dismiss a critical unresolved condition with no later access.", "Showing the same dismissed banner on every route because dismissal is not versioned.", "Keeping an outage, rollout, or deadline banner visible after the condition has ended.", "Customizing official identity banner text until it no longer provides a recognizable trust signal." ], "critiqueQuestions": [ "What exact product, service, account, section, or site scope does this banner govern?", "Should users see this before the page heading, below service navigation, or only inside one task area?", "Is this broad enough for a banner, or should it be an alert, inline message, toast, error summary, or error state?", "What is the single highest-priority banner for this scope right now?", "Can users dismiss it safely, and what message version should make it reappear?", "What event, date, release, or system state removes or replaces the banner?" ], "relatedPatterns": [ "alert", "inline-message", "toast-notification", "service-navigation", "header", "utility-navigation", "error-state" ], "comparisons": [ "banner-vs-alert-vs-inline-message-vs-toast-notification" ], "sourceIds": [ "carbon-notification-pattern", "govuk-notification-banner-component", "atlassian-banner-component", "uswds-banner-component" ] }, { "id": "basic-search", "completionStatus": "complete", "name": "Basic search", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Search input and result list", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to find matching content without browsing every category or page.", "solution": "Provide a labeled search field, run the query against relevant content, and show result count, matches, and recovery paths.", "uiGuidance": [ "Render a labeled search field, result count, matching rows, and clear action.", "Keep result updates visually close to the query that caused them." ], "uxGuidance": [ "Help users find known content without browsing every category.", "Preserve query context while users inspect, refine, or recover from no results." ], "uiExamples": { "good": [ "A clearly labeled search field with result count and results placed directly below.", "Matched rows use calm highlighting and stable spacing so scanning stays easy." ], "bad": [ "Search input hidden behind only an icon with no label.", "Results jump, resize, or use heavy borders that make scanning feel like reading a form." ] }, "uxExamples": { "good": [ "Users can type, revise, clear, and keep context while inspecting results.", "No-results state offers query correction, clearing, or broader search." ], "bad": [ "Search silently changes unrelated filters.", "Opening a result destroys the query and makes returning impossible." ] }, "problemContext": [ "The content set is larger than users can comfortably scan.", "Users can describe what they need with words or identifiers." ], "selectionRules": [ "Choose basic search when the task is content retrieval.", "Show results and counts close to the search input.", "Preserve the query while users inspect or refine results." ], "requiredStates": [ "Empty query state.", "Loading or updating results state.", "Matching results state.", "No matches state with recovery." ], "interactionContract": [ "Typing or submitting a query changes the visible result set predictably.", "The user can clear or revise the query.", "Result labels explain what will open or happen." ], "implementationChecklist": [ "Provide a visible label or accessible name.", "Show result count and matching items.", "Keep filters and sort behavior clear.", "Provide no-results recovery." ], "commonMisuses": [ "Using placeholder text as the only label.", "Returning no feedback while results update.", "Making search change unrelated filters silently." ], "critiqueQuestions": [ "Can users predict what content the search covers?" ], "relatedPatterns": [ "search-suggestions", "command-palette", "faceted-search" ], "comparisons": [ "basic-search-vs-command-palette" ], "sourceIds": [ "moj-design-system-search", "wai-aria-apg", "govuk-design-system-patterns" ] }, { "id": "block-mute", "completionStatus": "complete", "name": "Block / mute", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Personal boundary control for reducing or stopping visibility, interaction, contact, and notification exposure from people, accounts, conversations, channels, apps, bots, words, or threads", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Personal safety and attention controls become untrustworthy when block, mute, hide, restrict, unfollow, report, and notification settings are blended together, effects are unclear, exceptions are hidden, or reversal paths are hard to find.", "solution": "Provide target-scoped block, mute, hide, and restrict controls with plain consequence summaries, confirmation for high-impact actions, status after activation, manageable lists, undo or reversal paths, and adjacent report or emergency actions when personal visibility controls are not enough.", "uiGuidance": [ "Render block and mute controls as scoped personal-boundary actions that name the target, effect, scope, exceptions, confirmation need, reversal path, and related report or safety action.", "Separate block, mute, hide, restrict, report abuse, unfollow, unsubscribe, permission denial, and notification preferences by showing what changes for the current user, what changes for the target, and what remains possible." ], "uxGuidance": [ "Use block / mute when users need immediate control over exposure to a person, account, conversation, channel, app, bot, word, topic, or thread without necessarily asking the platform to enforce a policy.", "Help users choose the least surprising boundary by explaining whether the target is notified, whether contact is blocked, whether content is hidden, what notifications remain, and how to unblock, unmute, unhide, or manage the list later." ], "uiExamples": { "good": [ "A profile menu offers Mute posts, Block account, Report abuse, and Hide mentions as separate actions, each with a short consequence summary before confirmation.", "A channel notification menu says Mute and hide, explains mentions still produce numbered badges, offers one-hour or until-tomorrow temporary mute, and links to muted conversation settings." ], "bad": [ "A single Silence button mutes posts, blocks DMs, unfollows, and reports the account without naming any effect.", "A block confirmation says Are you sure? but never explains whether mentions, profile visits, direct messages, collaboration, or existing content will change." ] }, "uxExamples": { "good": [ "A user mutes a noisy account, sees that the account is not notified and can still send DMs, then uses the muted-account list to unmute later.", "A user blocks a harassing collaborator, adds a private note, sees repository interaction effects, and can still report abuse from a linked safety route." ], "bad": [ "A user mutes a direct message expecting silence everywhere, but the same person keeps triggering alerts in another group conversation because scope was not explained.", "A hidden-person feature hides names and messages but provides no way to reveal one message or unhide the person later." ] }, "problemContext": [ "Targets may be people, accounts, comments, posts, profiles, DMs, group conversations, channels, threads, apps, bots, words, hashtags, topics, repositories, workspaces, or organizations.", "Effects may include hiding posts, hiding names/photos/messages, suppressing notifications, preventing contact, preventing profile visibility, blocking repository collaboration, preserving badge-only alerts, or limiting only one conversation.", "The target may or may not be notified, and the current user may still see mentions, badges, shared-context replies, huddles, hidden-message reveal prompts, or existing content.", "Block and mute often sit next to report abuse, notification preferences, follow or subscribe, unfollow, leave conversation, restrict, remove, and permission controls, but each has a different owner and consequence." ], "selectionRules": [ "Choose block / mute when the user needs a personal boundary that changes visibility, contact, notification, or interaction from a specific target.", "Use block when the intended effect is stronger interaction prevention, such as blocking contact, profile interaction, repository participation, tagging, list addition, or collaboration actions.", "Use mute when the intended effect is reducing visibility or notifications while preserving follow, membership, access, or contact relationships.", "Use hide or restrict when content or identity is visually suppressed but the target may still be present, join spaces, or have messages revealed deliberately.", "Use report abuse when the user wants policy, safety, legal, privacy, or moderation review; offer it adjacent to block or mute without implying block or mute enforces platform rules.", "Use notification preferences when the user is configuring broad event types, channels, quiet hours, digests, OS permissions, or workspace delivery rules.", "Use follow / subscribe when the user opts into future updates from one target; use mute to reduce or pause exposure from one target.", "Use permission denied state when access is unavailable because of authorization, role, policy, or owner decisions rather than personal boundary settings.", "Show the exact target and scope before activation: account, channel, one DM, group DM, app, bot, word, thread, story, repository, organization, or all conversations with a person.", "Show exceptions such as mentions, badges, DMs, huddles, shared conversations, existing replies, protected posts, Slackbot, admin policy, or organization blocks before users assume silence is total.", "Provide unblock, unmute, unhide, manage list, undo, or temporary-duration controls close to the activated state." ], "requiredStates": [ "Block entry point from profile, post, comment, message, repository, or account settings.", "Mute entry point from profile, post, channel, DM, app, bot, thread, word, or notification menu.", "Confirmation state for high-impact block with target identity and consequences.", "Mute without notification to target state.", "Blocked state with visible status, hidden content, and View anyway or profile warning where relevant.", "Muted state with timeline, sidebar, channel, DM, app, bot, or notification scope label.", "Hidden person or hidden message state with reveal one message and unhide paths.", "Restrict or limited-interaction state with who can comment, mention, DM, or see activity.", "Temporary mute state with duration such as one hour, until tomorrow, or custom end time.", "Exceptions state for mentions, badges, DMs, huddles, shared conversations, Slackbot, or repository contributor warnings.", "Undo, unblock, unmute, unhide, manage blocked list, and manage muted list states.", "Report abuse adjacent action, emergency help route, failed action, offline pending, permission-limited, admin-managed, and mobile compact states." ], "interactionContract": [ "The control identifies the exact target before activation and does not infer a broader scope than the visible label states.", "Block, mute, hide, restrict, report, unfollow, unsubscribe, remove, and leave are separate commands with separate confirmation copy.", "High-impact block actions require confirmation and describe consequences that affect contact, profile visibility, collaboration, repository actions, or shared spaces.", "Mute actions state whether they affect posts, stories, channel notifications, DMs, group DMs, apps, bots, words, topics, or one conversation, and whether the target is notified.", "The resulting state is visible near the target and in a management list, with unblock, unmute, unhide, or undo available when policy allows.", "Exceptions are disclosed before or immediately after activation so users know what still appears or notifies them.", "Failed or offline actions preserve the chosen target and intended action and do not claim the boundary applied.", "Private notes, block reasons, hidden-person state, and safety choices are not exposed to the blocked or muted target." ], "implementationChecklist": [ "Inventory target types, available boundary actions, effect scope, notification effects, target-notification behavior, exceptions, undo windows, and management surfaces.", "Model block, mute, hide, restrict, report, unfollow, subscription, notification preference, and permission states separately.", "Write consequence summaries for each action, including what still appears, what still notifies, whether contact is blocked, and how to reverse it.", "Add confirmation for high-impact block or organization-wide actions and immediate status for lower-impact mute or hide actions.", "Provide management lists for blocked accounts, muted accounts, muted words, muted channels, hidden people, and temporary mutes where the product supports them.", "Handle deleted users, renamed channels, blocked-by-target relationships, protected content, shared group conversations, repository ownership, admin-managed blocks, offline failure, and cross-device sync.", "Test screen-reader labels, keyboard activation, mobile overflow menus, long names, private notes, undo, hidden-message reveal, temporary expiry, and report-abuse handoff." ], "commonMisuses": [ "Using one command for block, mute, hide, report, and unfollow.", "Failing to explain whether the target is notified.", "Hiding the unblock or unmute route after activation.", "Letting muted conversations still produce unexplained badges or mention alerts.", "Claiming the user is safe when the setting only hides posts from one timeline.", "Making report abuse the only way to stop seeing someone.", "Showing private block notes, reasons, or hidden-person state to the target.", "Treating admin-enforced restrictions as if the current user can reverse them." ], "critiqueQuestions": [ "What exact person, account, conversation, channel, app, bot, word, or thread is affected?", "Is this action reducing visibility, suppressing notifications, preventing contact, hiding identity, restricting interaction, or reporting abuse?", "What still appears or notifies after activation?", "Does the target know, and is that expectation stated honestly?", "Where can users undo, unblock, unmute, unhide, or review the list later?", "How does this differ from notification preferences, follow / subscribe, report abuse, and permission denial?", "What happens in shared group conversations, mentions, huddles, repository collaboration, and offline failure?" ], "relatedPatterns": [ "report-abuse", "notification-preferences", "follow-subscribe", "permission-denied-state", "comments", "threaded-discussion", "notification-center", "activity-feed", "settings-management" ], "comparisons": [ "block-mute-vs-report-abuse-vs-notification-preferences-vs-follow-subscribe-vs-permission-denied-state-vs-comments" ], "sourceIds": [ "x-blocking-accounts", "x-mute-accounts", "github-block-user-personal-account", "slack-mute-channels-dms", "slack-hide-person" ] }, { "id": "booking", "completionStatus": "complete", "name": "Booking", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Customer-facing flow for reserving an offered slot, service, resource, appointment, class, or seat", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Booking fails when products treat reservation as simple date and time entry, hiding service type, capacity, staff or resource availability, customer requirements, payment, policy, verification, confirmation, and stale-slot recovery.", "solution": "Provide a booking flow that lets users choose an offered service or resource, inspect real availability and capacity, enter required customer and intake details, satisfy policy, verification, and payment requirements, recheck the slot at commit, and receive a durable confirmation with cancel or reschedule paths.", "uiGuidance": [ "Render booking as a reservation contract with service or appointment type, provider or staff, location or delivery mode, available date and time slots, duration, timezone, party size or capacity, price or deposit when applicable, customer details, intake questions, policy acceptance, and confirmation action.", "Show unavailable slots, sold-out capacity, provider closed hours, minimum notice, buffers, payment requirement, email verification, cancellation and reschedule policy, stale availability, and confirmation delivery as explicit states before a slot is held." ], "uxGuidance": [ "Use booking when a customer, invitee, client, patient, guest, student, or attendee reserves a provider-defined appointment, class, room, seat, resource, or service slot.", "Keep users clear about when a slot is only being browsed, temporarily held, awaiting intake, awaiting email verification, awaiting payment, confirmed, canceled, rescheduled, expired, or released back to availability." ], "uiExamples": { "good": [ "A salon booking page shows Haircut, 45 minutes, Zara as stylist, Thu 14:30, two remaining openings, New York timezone, price, intake questions, cancellation policy, and a Book appointment button.", "A class booking flow shows available sessions, sold-out sessions, waitlist state, attendee count, deposit, refund policy, confirmation email, calendar link, and reschedule path before committing." ], "bad": [ "A booking page lists calendar dates but hides service duration, staff, capacity, timezone, price, and cancellation policy until after confirmation.", "A form takes payment first, then reports that the chosen appointment slot is no longer available." ] }, "uxExamples": { "good": [ "A client chooses a 45-minute haircut, sees only available stylist times, enters phone and notes, accepts the late-cancel policy, pays a deposit, receives a reference, and gets cancel and reschedule links.", "A customer tries to book a yoga class for three people, sees only two seats remain, adjusts party size, books one seat, and gets a waitlist option for the rest." ], "bad": [ "A guest books a restaurant table shown in local browser time but the venue expected venue time, so the reservation lands in the wrong slot.", "A patient completes intake questions after selecting a slot, then loses the slot when email verification fails." ] }, "problemContext": [ "The user is reserving a provider-defined appointment, service, room, class, seat, table, equipment, consultation, visit, or pickup window.", "The booking may require service selection, staff or resource selection, location, duration, date, slot, timezone, party size, customer identity, contact details, intake questions, consent, terms, deposit, prepayment, or cancellation policy.", "Availability can depend on business hours, staff calendars, resource capacity, buffers, minimum notice, lead time, service duration, party size, checked calendars, payment status, and concurrent users.", "Confirmation can create a held slot, calendar event, receipt, email or text notification, cancellation link, reschedule link, waitlist entry, or provider-side queue item.", "Booking errors can have external consequences such as double-booked staff, over-capacity classes, unreleased canceled slots, payment without confirmation, or no-show disputes." ], "selectionRules": [ "Choose booking when users reserve an offered appointment, service, class, room, seat, resource, table, or visit from provider-defined availability.", "Use scheduling when the organizer is coordinating people, calendars, recurrence, attendees, and invitations rather than accepting a customer reservation.", "Use checkout when the main commitment is purchase completion; booking may include payment only to hold or confirm the selected appointment, class, or resource.", "Use date picker, time picker, or date range picker as sub-controls only after booking-specific service, capacity, availability, and policy rules are handled.", "Use payment collection inside booking when a deposit, no-show fee, prepaid service, or paid appointment is required before confirmation.", "Use confirmation page after the booking is committed, not as a substitute for slot validation, intake, verification, or payment.", "Expose service, provider or resource, location, duration, timezone, party size, capacity, price, policy, intake requirements, and confirmation delivery before commit.", "Recheck slot availability, capacity, provider/resource state, payment result, and email verification immediately before confirming the booking.", "Show sold-out, unavailable, closed, full, stale, waitlist, email verification, payment required, payment failed, canceled, rescheduled, and released-slot states.", "Keep cancel and reschedule paths tied to the original reference so customer notifications, provider calendars, payments, and released availability stay synchronized." ], "requiredStates": [ "Service or appointment type selection state.", "Provider, staff, resource, room, seat, or location selection state.", "Available date and slot list state with duration and timezone.", "Unavailable, closed, blocked, sold-out, or capacity-full state.", "Party size, attendee count, or quantity state.", "Customer contact and identity state.", "Required intake questions, consent, terms, or policy acceptance state.", "Email verification or identity verification state when required.", "Payment, deposit, or card authorization state when required.", "Temporary hold or pending confirmation state while availability is rechecked.", "Stale slot or slot taken state with alternatives.", "Confirmed booking state with reference, calendar option, notification delivery, and next steps.", "Cancel booking state that releases the slot and explains refund or policy effects.", "Reschedule booking state that preserves customer details and policy context.", "Waitlist or notify-me state when capacity is full." ], "interactionContract": [ "Changing service, staff, resource, party size, date, timezone, location, or duration recomputes available slots before confirmation.", "A selected slot is not treated as confirmed until required intake, policy acceptance, verification, and payment checks have succeeded.", "The final action names the booking consequence, such as Book appointment, Reserve table, Join class, or Confirm reservation.", "Availability is rechecked at commit and stale slots return users to equivalent alternatives without clearing safe customer details.", "Payment, deposit, and refund terms are shown before payment and remain tied to the booking reference after confirmation.", "Canceling or rescheduling updates provider calendars, customer notifications, capacity counts, waitlist state, and released availability consistently.", "Confirmation includes reference, service, time, timezone, location or meeting mode, provider/resource, customer details summary, policy, and manage-booking links." ], "implementationChecklist": [ "Define booking ownership for service catalog, staff/resource calendars, capacity, business hours, buffers, lead time, party size, intake fields, policy, verification, payment, confirmation, cancellation, reschedule, and waitlist.", "Build slot availability from canonical booking services rather than browser-only filtering, including capacity, staff/resource availability, buffers, minimum notice, closed periods, and concurrent holds.", "Expose service, duration, price, location, staff/resource, timezone, available slots, capacity, customer contact, intake, terms, payment, and confirmation action with validation and state text.", "Implement temporary slot hold, stale-slot recheck, sold-out recovery, alternate slot suggestions, waitlist, and release behavior after cancel or timeout.", "Support email verification, payment authorization, deposit, cancellation policy, refund instructions, confirmation email or SMS, calendar attachment, and manage-booking links when required.", "Preserve safe customer and intake details across slot taken, payment failure, verification failure, browser Back, refresh, and reschedule while redacting payment secrets.", "Test sold-out capacity, staff unavailable, closed hours, timezone change, party-size limit, stale slot, payment decline, verification failure, cancellation, refund policy, reschedule, waitlist, mobile, keyboard, and screen reader status updates." ], "commonMisuses": [ "Treating booking as only a date picker and time picker.", "Showing slots without service duration, staff/resource, timezone, price, or capacity context.", "Taking payment before proving the selected slot can be held.", "Confirming a booking before required intake, consent, email verification, or payment completes.", "Losing customer details when a slot becomes stale or payment fails.", "Hiding cancellation, refund, no-show, or reschedule policy until after booking.", "Letting canceled bookings keep the provider calendar blocked or fail to notify the customer.", "Using the customer's local timezone for an in-person venue booking without showing venue time." ], "critiqueQuestions": [ "What service, staff, resource, room, seat, or appointment type is being reserved?", "Which availability, capacity, business-hours, buffers, minimum notice, and party-size rules define bookable slots?", "What customer details, intake questions, consent, policy, verification, or payment must be complete before the slot is held?", "What timezone does the booking page show, and is that correct for remote and in-person bookings?", "When is the slot temporarily held, confirmed, released, canceled, rescheduled, or waitlisted?", "What happens if another user takes the slot between selection and confirmation?" ], "relatedPatterns": [ "scheduling", "checkout", "date-picker", "time-picker", "date-range-picker", "payment-collection", "confirmation-page", "notification-center", "conflict-state", "review-before-submit" ], "comparisons": [ "booking-vs-scheduling-vs-checkout-vs-date-picker" ], "sourceIds": [ "google-calendar-share-appointment-schedule", "google-calendar-cancel-booked-appointment", "google-calendar-appointment-payments", "google-calendar-appointment-email-verification", "microsoft-bookings-create-manage", "microsoft-bookings-shared-booking-page", "calendly-sharing-booking", "squarespace-acuity-appointment-services" ] }, { "id": "bottom-navigation", "completionStatus": "complete", "name": "Bottom navigation", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Persistent mobile primary navigation", "maturity": "established", "platforms": [ "mobile" ], "problem": "Mobile users need one-tap access to a small set of primary app destinations without stretching to a top menu or losing section context.", "solution": "Keep three to five top-level destinations persistently available at the bottom of compact mobile screens, with clear labels, icons, selected state, and preserved state inside each section.", "uiGuidance": [ "Render three to five bottom destinations with stable touch targets, labels or accessible names, reinforcing icons, selected state, optional badges, and safe-area spacing.", "Keep the bar visually attached to the app shell rather than to one section's content, and avoid mixing in commands or deep hierarchy links." ], "uxGuidance": [ "Support rapid switching between top-level mobile sections while preserving each section's local navigation, scroll, filters, and drafts.", "Adapt the same destination model to rail or drawer navigation when window width or destination count makes the bottom bar cramped." ], "uiExamples": { "good": [ "Five labeled destinations stay fixed at the bottom with Home selected, Alerts showing a small badge, and no action button mixed into the bar.", "Selected state uses shape, weight, and text color instead of relying on color alone." ], "bad": [ "Six tiny icon-only items and a center plus button compete for space.", "The active destination is unclear and labels truncate into guesses." ] }, "uxExamples": { "good": [ "Switching from Home to Saved and back preserves each section's scroll count and draft state.", "A badge invites users to check Alerts without changing what the Alerts destination does." ], "bad": [ "Tapping Search clears the Home feed position and opens a one-off command instead of a destination.", "A create action in the middle of the bar surprises users who expect destination switching." ] }, "problemContext": [ "A compact mobile app has a small number of high-frequency primary sections.", "Users switch between sections repeatedly while holding the device one-handed.", "Each destination may have its own nested navigation, scroll position, filters, or draft state that should survive destination switches." ], "selectionRules": [ "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." ], "requiredStates": [ "Default state with all primary destinations visible.", "Selected destination state exposed visually and programmatically.", "Destination changed state with content updated and previous section state preserved.", "Badge or notification state that does not steal focus or shift the bar.", "Overflow or more-destinations decision state where the design changes to rail, drawer, or a More destination instead of cramming items.", "Full-screen or modal task state where hiding the bar is deliberate and reversible." ], "interactionContract": [ "Activating an item switches to its top-level destination rather than performing a transient command.", "The selected item remains visible and stable while users navigate inside that section.", "Each destination has a predictable label, accessible name, and selected/current state.", "Switching destinations does not clear scroll position, filters, drafts, or nested navigation unless the user explicitly resets them.", "Badges communicate status without changing the destination's function." ], "implementationChecklist": [ "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." ], "commonMisuses": [ "Putting too many destinations into the bar.", "Mixing navigation destinations with commands such as create, delete, filter, or submit.", "Using icon-only labels for unfamiliar sections.", "Resetting scroll, filters, or draft state every time users switch destinations.", "Using bottom navigation for deep child pages instead of top-level app areas.", "Combining it with another competing primary navigation model on a narrow screen." ], "critiqueQuestions": [ "Are these items truly top-level destinations users revisit often, or are they actions competing for bottom reach?", "Will the selected state and labels still be understandable at the narrowest supported width?", "What section state must be preserved when users switch away and come back?" ], "relatedPatterns": [ "breadcrumbs", "tabs" ], "comparisons": [ "breadcrumbs-vs-tabs-vs-bottom-navigation" ], "sourceIds": [ "material-bottom-navigation", "android-responsive-navigation", "android-navigation-ui-bottom-nav", "apple-hig-tab-bars" ] }, { "id": "bottom-sheet", "completionStatus": "complete", "name": "Bottom sheet", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Mobile bottom-anchored contextual overlay with detents", "maturity": "standard", "platforms": [ "mobile", "web" ], "problem": "Mobile users need contextual details or controls without leaving the current map, feed, media, object, or task, and the controls should be reachable from the lower part of the screen.", "solution": "Present a bottom-anchored sheet with a clear handle, useful detents, visible title or context label, predictable dismissal, and a defined relationship between sheet dragging, inner scrolling, and the background content it partially covers.", "uiGuidance": [ "Render a bottom sheet as a lower-edge surface with a visible handle, rounded top edge, safe-area spacing, meaningful peek content, and controls that remain reachable from the bottom of the screen.", "Use scrim, elevation, detent height, and background visibility to communicate whether the bottom sheet is modal, standard, collapsed, half-expanded, or full-height." ], "uxGuidance": [ "Use bottom sheets for mobile contextual details or controls that benefit from lower-edge reach while preserving orientation to the current background object.", "Make detents, drag behavior, inner scrolling, dismissal, selected-object preservation, and focus return predictable so the sheet feels like controlled progressive disclosure." ], "uiExamples": { "good": [ "A map pin opens a bottom sheet with a handle, station name, distance, primary route action, half-height service details, and full-height stop list.", "A modal bottom sheet dims the feed, shows grouped quick actions above the safe area, and provides visible close and expand controls." ], "bad": [ "A bottom panel covers the entire map immediately, has no handle, and hides the selected pin.", "A bottom sheet contains a long settings workflow and bottom navigation links, with the primary action below the device safe area." ] }, "uxExamples": { "good": [ "Users open a station sheet from the map, peek at the station identity, expand to half height for next departures, expand to full height for all stops, collapse back to the map, and keep the selected pin visible.", "Dragging the handle changes detents while dragging the departure list scrolls the list only after the sheet is fully expanded." ], "bad": [ "Users drag on the list expecting to scroll, but the whole sheet dismisses and loses the selected map pin.", "The bottom sheet blocks the bottom navigation and leaves keyboard focus behind the modal overlay." ] }, "problemContext": [ "The user is on a mobile screen where the current background context still matters.", "The extra content is contextual, temporary, and easier to use from the bottom edge than in a centered dialog or side panel.", "The sheet may need peek, half, or full heights so users can inspect more detail without losing orientation.", "The product can define scrim behavior, background interaction, gesture handling, focus movement, and safe-area spacing." ], "selectionRules": [ "Choose bottom sheet when contextual details, options, or controls are best reached from the lower edge of a mobile viewport while the background remains useful for orientation.", "Use sheet when the surface is a broader temporary child task that does not depend on bottom-edge anchoring or mobile detents.", "Use drawer when side placement and comparison with a list, table, or chart matter more than thumb reach.", "Use bottom navigation when the bottom surface contains persistent top-level destinations rather than temporary contextual content.", "Use action menu or menu button when the user only needs a short command list near the trigger and no preview, grouping, or detent behavior.", "Use modal dialog or alert dialog when the user must focus on a compact blocking task or urgent response and bottom reach is not the deciding factor.", "Use a full page when the content needs deep reading, multiple steps, route history, saved progress, or durable sharing.", "Use a standard bottom sheet only when background interaction remains intentional; use a modal bottom sheet when background changes would conflict." ], "requiredStates": [ "Closed state with a trigger tied to the current map item, feed card, route, media item, or contextual action.", "Peek state that shows a meaningful title, summary, or first action rather than only a handle.", "Half or medium state that exposes the common controls while leaving enough background context visible.", "Full state for detailed review or longer lists, with clear scroll boundaries.", "Dragging or resizing state that makes the target detent understandable and does not conflict with inner scrolling.", "Modal state with scrim, background inactivation, focus containment, and dismissal behavior.", "Standard state where background content and sheet state remain intentionally coordinated.", "Dismissed or collapsed state that preserves the selected background object and returns focus or touch target context." ], "interactionContract": [ "The sheet enters from the bottom edge and remains visually attached to that edge or device safe area.", "The drag handle, title, and first visible content explain why the sheet appeared.", "Each detent has a useful purpose: peek for identity, half for primary controls, and full for details or list scanning.", "Drag gestures, inner scrolling, and swipe-to-dismiss have explicit priority rules.", "The sheet does not cover persistent bottom navigation or critical device safe-area controls without replacing them intentionally.", "Modal bottom sheets use a scrim and prevent background changes until dismissed.", "Standard bottom sheets keep background interaction meaningful and synchronize selected objects or map/feed state.", "Closing, collapsing, saving, selecting, scrim tap, Escape, and back all return users to the correct background object or control." ], "implementationChecklist": [ "Define whether the sheet is modal or standard and which background controls remain usable.", "Define allowed detents, default detent, expansion limits, and what content appears at each height.", "Provide a visible handle when the sheet can be dragged and a close route when dismissal is allowed.", "Keep primary actions visible above safe-area insets and outside ambiguous scroll traps.", "Decide when dragging moves the sheet, scrolls inner content, changes detent, or dismisses the sheet.", "Preserve selected map pins, feed cards, media items, or route context while the sheet opens and closes.", "Use scrim, inert background, focus containment, and focus return for modal sheets.", "Test one-handed reach, small screens, landscape, keyboard appearance, screen reader order, reduced motion, and large text." ], "commonMisuses": [ "Using a bottom sheet as hidden global navigation or a dumping ground for unrelated commands.", "Opening a bottom sheet at a height that hides the map, feed, or object the user needs for context.", "Providing a peek state with no meaningful content.", "Letting sheet dragging fight inner list scrolling.", "Covering bottom navigation, home indicator, or primary actions without safe-area treatment.", "Putting long multi-step workflows into a bottom sheet with no route, progress, or save recovery.", "Relying only on swipe gestures for close or resize without accessible controls." ], "critiqueQuestions": [ "What background context must remain visible when this bottom sheet is open?", "What useful content appears at peek, half, and full heights?", "Should the sheet be modal, or can users keep interacting with the map, feed, or media behind it?", "When the user drags inside the sheet, does the gesture move the sheet, scroll content, or dismiss it?", "Does the sheet collide with bottom navigation, safe areas, keyboard, or primary actions?", "Would a regular sheet, drawer, modal dialog, action menu, or full page better match this content?" ], "relatedPatterns": [ "sheet", "drawer", "modal-dialog", "bottom-navigation", "action-menu" ], "comparisons": [ "bottom-sheet-vs-sheet-vs-drawer-vs-bottom-navigation" ], "sourceIds": [ "material-bottom-sheets", "android-compose-bottom-sheets", "nng-bottom-sheets", "material-bottom-navigation" ] }, { "id": "breadcrumbs", "completionStatus": "complete", "name": "Breadcrumbs", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Hierarchy orientation navigation", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users land inside a nested information architecture and need to understand where the current page sits without retracing their path.", "solution": "Show a canonical ancestor trail from the broadest relevant parent to the current page, with ancestor links and a clear current-page item.", "uiGuidance": [ "Render a labeled breadcrumb nav as an ordered hierarchy from the broadest relevant ancestor to the current page, with real ancestor links and a distinct current-page item.", "Keep separators decorative, preserve meaningful labels, and collapse only in ways that keep the direct parent reachable on narrow screens." ], "uxGuidance": [ "Orient users who arrive deep in a site by exposing the canonical parent-child relationship for the current page.", "Let users move upward to parent sections without relying on browser Back, click history, or a linear step indicator." ], "uiExamples": { "good": [ "Home, Projects, Migration, and Runbook appear in hierarchy order with ancestor links and Runbook marked current.", "A mobile variant keeps the direct parent link visible instead of hiding every meaningful ancestor." ], "bad": [ "Recent clicks are displayed as if they were the page hierarchy.", "The trail is a row of vague labels such as Back, More, and Current with no current-page semantics." ] }, "uxExamples": { "good": [ "Opening a saved deep link still shows the same parent path and lets users jump to Migration or Projects.", "In a form flow, the breadcrumb stays anchored to the starting page's site hierarchy while progress is shown separately." ], "bad": [ "The breadcrumb changes after every click, so the same page shows different trails for different users.", "Users try to move up to a parent section but the crumb returns them to the previous history entry instead." ] }, "problemContext": [ "The product has a parent-child information architecture deeper than one or two obvious levels.", "Users can arrive at interior pages from search, external links, saved URLs, or notifications.", "The current page title alone does not show which section or parent collection owns the page." ], "selectionRules": [ "Choose breadcrumbs when the current page has meaningful ancestor pages that help users orient and move upward.", "Use the canonical site or product hierarchy, not the user's click path, recent history, or task progress.", "Keep each ancestor crumb tied to a real destination whose page title or label matches the crumb.", "Place breadcrumbs consistently near the top of the page before the main content they orient.", "On small screens, collapse cautiously to the immediate parent only when the full trail would crowd the layout." ], "requiredStates": [ "Interior page with full ancestor trail.", "Ancestor links that navigate to parent levels.", "Current page item identified visually and programmatically.", "Long-label or narrow-screen state that preserves at least the direct parent destination.", "Linear-flow state where the breadcrumb remains tied to the site hierarchy instead of advancing step by step." ], "interactionContract": [ "Activating an ancestor crumb moves to that ancestor page without implying a back-in-history action.", "The trail remains stable for the same URL no matter how the user arrived.", "The current item is not confused with another parent link; when it is a link, it exposes aria-current=\"page\".", "Separators are visual only and are not announced as extra links or destinations." ], "implementationChecklist": [ "Use a navigation landmark with an accessible name such as Breadcrumb.", "Render crumbs as an ordered list in hierarchy order from broad to specific.", "Link ancestor crumbs to real parent destinations and keep labels aligned with destination page titles.", "Expose the current page with aria-current or equivalent current-page text.", "Hide decorative separators from assistive technology.", "Do not replace primary navigation, task progress, or a back link with breadcrumbs." ], "commonMisuses": [ "Showing browsing history instead of hierarchy.", "Using breadcrumbs on a flat app where no ancestor path exists.", "Using breadcrumbs to show steps in a form or checkout journey.", "Duplicating primary navigation with a long list of unrelated destinations.", "Collapsing away the direct parent link users need most." ], "critiqueQuestions": [ "Would this same URL show the same breadcrumb trail if the user arrived from search, a notification, or a saved link?", "Does every crumb represent a parent destination users can understand before activating it?", "Would a tab, step indicator, side navigation, or bottom navigation better represent the relationship being shown?" ], "relatedPatterns": [ "tabs", "bottom-navigation" ], "comparisons": [ "breadcrumbs-vs-tabs-vs-bottom-navigation" ], "sourceIds": [ "wai-aria-apg-breadcrumb", "govuk-breadcrumbs-component", "uswds-breadcrumb-component", "va-breadcrumbs-component" ] }, { "id": "browse-by-category", "completionStatus": "complete", "name": "Browse by category", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Taxonomy-based category navigation for exploring a collection before choosing a destination", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to explore a broad collection of services, articles, products, records, or learning resources, but they may not know the exact term to search for and a flat list is too large to scan.", "solution": "Provide a maintained category taxonomy with clear labels, descriptions, hierarchy, counts, examples, popular destinations, current-location cues, and recovery from empty or confusing categories.", "uiGuidance": [ "Render categories as a scannable list or grid with user-facing names, short descriptions, item counts or example contents, and clear parent-child location cues.", "Show subcategories, popular destinations, sibling categories, and search fallback without making users open every category to understand what it contains." ], "uxGuidance": [ "Use browse by category when users can recognize a topic or service area but may not know the exact query, item name, or filter value.", "Maintain the taxonomy with evidence from content tagging, search terms, analytics, tree testing, support questions, and editorial review so category labels stay distinct and useful." ], "uiExamples": { "good": [ "A services page lists Benefits, Housing and local services, Money and tax, and Driving and transport with one-line descriptions and top tasks for each category.", "A learning catalog shows Products, Roles, Certifications, and Learning paths, each with counts and examples of what users will find inside.", "A help center category page shows the parent topic, child categories, most viewed articles, and a search box for users who do not recognize the taxonomy." ], "bad": [ "A category grid uses internal teams such as Operations, CX, Growth, Platform, and Enablement without saying what users can find there.", "Cards named Support, Help, Resources, and Information overlap and provide no descriptions.", "A category opens to an empty page with no sibling categories, parent link, search fallback, or explanation." ] }, "uxExamples": { "good": [ "A user who does not know the form name chooses Money and tax, sees Self Assessment and VAT subcategories, and reaches the correct service without writing a search query.", "A user opens a category with no current matches and sees a message that the topic was merged into Benefits, with a route to the parent and a search fallback.", "An editor reviews low-click categories, merges overlapping labels, and retags misplaced content after checking search terms and support questions." ], "bad": [ "Users choose Customers because they need customer support, but the category contains only internal CRM configuration articles.", "A category page lists hundreds of links alphabetically without subcategories, most-used tasks, or search recovery.", "A popular-task shortcut is shown as the only path, hiding the full category structure and making less common tasks hard to find." ] }, "problemContext": [ "The collection contains enough destinations that a flat list, global navigation, or single search box would force users to guess terms or scan too much.", "Users can recognize meaningful topic areas, service areas, resource types, or product families if the taxonomy uses their language.", "The category structure needs ongoing content tagging and review because categories can drift, overlap, empty out, or reflect internal ownership rather than user mental models." ], "selectionRules": [ "Choose browse by category when the primary task is exploratory recognition: users know the area but not the exact item name or query.", "Use a category landing page when categories lead to multiple destinations, subcategories, or task pages that need explanation before selection.", "Limit each visible category level enough for scanning; when there are too many children, split, group, prioritize, or add within-category search.", "Name categories by what the content is about, not by the department, owner, content format, or backend index that produced it.", "Add short descriptions or examples when category names could overlap or when users need help predicting the contents.", "Show item counts, most viewed tasks, recently updated content, or representative examples only when they help users choose and stay current.", "Provide a clear parent path, sibling categories, and back route so users can recover from the wrong category.", "Omit or explain empty categories; do not present an empty child page as a valid browse destination.", "Use basic search when users know words or identifiers; use filter panel after users already have a result set; use tabs only for sibling panels in one page context.", "Review tagging accuracy by spot-checking category contents and correcting misplaced items." ], "requiredStates": [ "Top-level category state with clear names, descriptions, and enough examples or counts to choose.", "Category selected state showing parent, current category, children, and relevant destinations.", "Subcategory state with a clear route back to parent and siblings.", "Empty or merged category state with explanation and recovery to parent, search, or replacement category.", "Popular or most-viewed destination state that remains visibly secondary to the taxonomy.", "Long category list state with grouping, prioritization, or search-within-category.", "Mobile compact state where hierarchy and descriptions remain scannable.", "Mis-tagged or stale category review state for editors or maintainers.", "Deep-linked category state that restores location and content." ], "interactionContract": [ "Activating a category navigates to a category view or expands a category hierarchy, not a filter chip on an unrelated result set.", "The selected category, parent path, and available children update together so users know where they are in the taxonomy.", "Category descriptions accurately summarize the content behind the category and are updated when the contents change.", "Most-viewed or popular links do not replace the full category path unless the page explicitly says they are shortcuts.", "Search fallback preserves the selected category only when it genuinely searches within that category and labels that scope.", "Empty categories explain whether content moved, no content exists, or the user lacks permission, and provide a next route.", "Changing category clears stale item selections, counts, and previews that belonged to the previous category." ], "implementationChecklist": [ "Define the category taxonomy, parent-child relationships, category labels, descriptions, item ownership, and tagging rules before building the UI.", "Use analytics, search logs, support queries, card sorting, tree testing, and content audits to validate category names and hierarchy.", "Show category descriptions, example items, counts, or popular links where labels need disambiguation.", "Render category links with normal navigation semantics and preserve the hierarchy in URL, breadcrumb, or page heading.", "Keep categories mutually exclusive enough for discovery, and add cross-links only where users reasonably expect content in more than one place.", "Spot-check category contents after imports, migrations, or automated tagging.", "Design empty, merged, permission-limited, and stale category states before launch.", "Test keyboard navigation, screen reader link lists, mobile wrapping, long labels, and categories with few or many children." ], "commonMisuses": [ "Using the organization chart as the category taxonomy.", "Showing category cards without descriptions when labels overlap.", "Treating categories as filters while navigating away and losing result context.", "Leaving empty categories visible because the schema still has a category record.", "Adding popular links without preserving the complete category path.", "Putting the same content into many parent categories to avoid making taxonomy decisions.", "Using icons or colors as the only way to distinguish category meaning." ], "critiqueQuestions": [ "Can users predict what they will find inside each category without opening it?", "Are category labels based on user language and content meaning rather than team ownership?", "How many choices appear at each level, and does that exceed what users can scan?", "What happens when a category has no content, stale content, or content users cannot access?", "Do category pages show the parent path, sibling choices, and a route back to search?", "How are tagging errors found and corrected after launch?" ], "relatedPatterns": [ "basic-search", "filter-panel", "tabs", "related-links", "breadcrumbs", "side-navigation", "mega-menu", "search-scope-selector" ], "comparisons": [ "browse-by-category-vs-basic-search-vs-filter-panel-vs-tabs" ], "sourceIds": [ "govuk-services-information-browse", "govuk-content-grouping-guidance", "govuk-topic-taxonomy-principles", "microsoft-learn-content-types" ] }, { "id": "bulk-import", "completionStatus": "complete", "name": "Bulk import", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Structured file import workflow with mapping, validation, repair, and result reporting", "maturity": "established", "platforms": [ "web", "desktop" ], "problem": "Bulk imports can save hours of repetitive entry, but they can also corrupt many records at once when requirements, mapping, validation, duplicates, overwrite rules, partial success, and result reporting are unclear.", "solution": "Design bulk import as a guarded, inspectable workflow that starts with templates and limits, validates the uploaded structure, asks users to confirm column mappings and duplicate rules, previews row-level issues, confirms side effects, tracks import progress, and returns a usable report.", "uiGuidance": [ "Show the import as a staged workflow: template or requirements, file upload, detected headers, column mapping, sample row preview, validation results, duplicate review, confirmation, progress, and final report.", "Render mapping status, required fields, unmapped columns, row errors, warnings, duplicate matches, create/update counts, skipped rows, and downloadable error reports as visible tables or summaries rather than hidden upload messages." ], "uxGuidance": [ "Use bulk import when users need to create or update many structured records from a spreadsheet, and make them prove mapping and validation before the product commits data.", "Let users fix mapping, choose duplicate and blank-value behavior, import only valid rows when supported, cancel before commit, and export failed rows after import." ], "uiExamples": { "good": [ "A contacts importer starts with a downloadable CSV template, then shows Email mapped to Email address, Role mapped to Access role, three sample rows, and a warning that Phone is optional and unmapped.", "An inventory import screen shows 1200 rows found, 1138 valid, 42 missing SKU, 20 duplicate matches, Update existing selected, and a disabled Start import button until required columns are mapped." ], "bad": [ "A page has a single Upload spreadsheet button and a spinner, then says Import failed without row numbers, column names, or a corrected-file path.", "A CSV drop area auto-imports immediately and overwrites existing records because blank cells and duplicate identifiers were not previewed." ] }, "uxExamples": { "good": [ "A user uploads contacts.csv, reviews suggested mappings, fixes Department to Team, filters to rows with errors, chooses Import valid rows and export invalid rows, confirms 1138 new and 20 skipped records, then downloads the error report.", "An admin chooses Update existing, sees external_id as the match key, reviews which blank cells will preserve existing data, cancels before commit, fixes the spreadsheet, and reruns validation." ], "bad": [ "A user uploads a file, the product commits immediately, and only afterward shows that 300 rows were skipped with no file explaining which rows failed.", "An importer silently maps Full name into Email because the headers were similar and gives no preview before overwriting customer records." ] }, "problemContext": [ "Users have many records in a spreadsheet or exported system file and cannot reasonably enter each record manually.", "The target system has required fields, typed values, enums, relationships, unique identifiers, ownership rules, and side effects such as notifications or permission changes.", "Column names, date formats, encoding, blank cells, duplicate identifiers, invalid enum values, and missing required values commonly differ between source files and target schema.", "Some imports create records, some update records, and some merge into existing data with different behavior for blank values and duplicates.", "A failed or partially successful import needs a recovery path, because users should not have to rediscover every bad row by trial and error." ], "selectionRules": [ "Choose bulk import when one uploaded file represents many structured records that must be parsed into fields.", "Use ordinary file upload when the uploaded file is evidence or content to store, not data to split into rows and columns.", "Use drag-and-drop upload only as an optional file-selection enhancement inside the import workflow, not as the whole import experience.", "Use multi-step form or complete complex form when a user is creating one record with guided human judgment rather than importing many prepared rows.", "Offer a template, sample file, or clear format rules before upload when users can prepare the file in advance.", "Require mapping review when column headers can differ from target field names or when unmapped columns would be ignored.", "Validate before commit when errors could affect many records, especially required values, type formats, duplicate identifiers, relationships, permissions, and destructive updates.", "Let users choose create-only, update-only, create-and-update, merge, or skip behavior when the same file can affect existing records.", "Support valid-row-only import only when users can see exactly which rows will import, which will be excluded, and how to fix excluded rows.", "Require final confirmation when the import sends notifications, changes permissions, overwrites data, creates many records, or cannot be fully undone." ], "requiredStates": [ "Pre-import requirements state with template, accepted file types, encoding, row limit, column limit, required fields, and side effects.", "File selected state showing filename, size, detected sheet, row count, column count, and parsed headers.", "Mapping state with suggested mappings, required-field gaps, unmapped columns, ignored columns, and sample values.", "Mapping error state for duplicate target fields, missing required mappings, unsupported fields, or ambiguous headers.", "Validation running state with progress and cancel guidance before data commit.", "Validation results state with valid row count, invalid row count, warning count, duplicate count, and row-level details.", "Repair state with filters for errors, warnings, duplicates, and unmapped columns plus links to fix or export issues.", "Duplicate review state with match key, create/update/skip choice, and overwrite behavior for blank values.", "Confirmation state summarizing new, updated, skipped, invalid, warning, notification, and irreversible-change counts.", "Import running state with progress, queued status, safe navigation guidance, and import history link.", "Import complete state with success count, skipped count, failed count, warnings, download report, and next actions.", "Import failed or partially completed state with retry guidance and preserved mapping choices." ], "interactionContract": [ "Uploading parses the file into headers, sample rows, counts, and metadata before any records are created or updated.", "Auto-mapping is a suggestion, not a commit; users can change, clear, ignore, reset, and review mappings before validation.", "A required target field cannot be left unmapped unless the import mode or existing data makes it explicitly safe.", "Each target field can receive at most one source column unless the product intentionally supports a combine-fields operation.", "Validation reports row number, source column, target field, offending value, reason, severity, and recovery action.", "Create/update/merge mode and duplicate matching are visible before final confirmation, including the identifier used to match existing records.", "Blank-value overwrite behavior is explicit for updates and merges.", "Starting the import after confirmation creates an auditable job with progress and results rather than leaving users on an indefinite spinner.", "Users can export invalid rows or an error report that preserves row identifiers and current mappings.", "Cancelling before final confirmation does not create or update records; cancelling after commit follows the product's documented job-cancel or rollback policy." ], "implementationChecklist": [ "Define accepted file types, encoding, max size, max rows, max columns, supported sheets, required fields, optional fields, ignored fields, relationship fields, duplicate keys, import modes, blank-value behavior, and notification side effects.", "Provide templates or sample files that match required headers and data formats.", "Parse files server-side or with a trusted parser and show detected headers, row count, column count, sample rows, and parse warnings before mapping.", "Build a mapping table that supports auto-map, manual map, ignore, reset, required-field indicators, one-source-to-one-target checks, sample values, and unmapped-column review.", "Validate required values, data types, dates, numbers, enums, relationships, duplicates, permissions, row length, unsupported fields, blank overwrites, and file-level limits before commit.", "Provide repair views that filter invalid rows, warnings, duplicates, and unmapped columns, with exportable errors and preserved mapping decisions.", "Show final confirmation for create/update/merge/skipped counts, notifications, irreversible changes, and valid-row-only behavior.", "Run the import as a tracked job with progress, completion, partial failure, retry, import history, and downloadable result report.", "Test small files, max-limit files, empty files, duplicate headers, missing required mappings, invalid dates, unknown enum values, duplicate existing records, blank update cells, network interruption, refresh/back, and permission-limited users." ], "commonMisuses": [ "Treating a spreadsheet import like a generic file attachment with no mapping or row validation.", "Auto-starting the import immediately after upload.", "Hiding duplicate matching, create/update mode, blank overwrite behavior, or notification side effects until after commit.", "Showing only a generic invalid file error instead of row numbers, column names, and fixable reasons.", "Importing valid rows and skipping invalid ones without telling users exactly which rows were excluded.", "Letting similar headers auto-map into destructive target fields without a preview.", "Forcing users to re-upload and remap from scratch after every recoverable validation error." ], "critiqueQuestions": [ "What records can this import create, update, merge, skip, notify, or overwrite?", "Can users see required fields, detected headers, sample values, unmapped columns, and duplicate mappings before validation?", "What row-level errors, warnings, duplicates, and blank-overwrite risks can the user repair before committing?", "Does the final confirmation explain counts and side effects in terms the importing user can verify?", "What report or export helps users fix failed rows without rebuilding a whole file?", "Can the team audit who imported what file, with which mapping, at what time, and with what result?" ], "relatedPatterns": [ "file-upload", "drag-and-drop-upload", "multi-step-form", "complete-complex-form", "inline-validation", "error-summary", "loading-skeleton" ], "comparisons": [ "bulk-import-vs-file-upload-vs-drag-and-drop-upload-vs-multi-step-form" ], "sourceIds": [ "smart-interface-bulk-import-ux", "hubspot-import-tool", "airtable-csv-import-extension", "zendesk-data-importer", "microsoft-viva-file-validation-errors" ] }, { "id": "button-group", "completionStatus": "complete", "name": "Button group", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Grouped visible action buttons", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to choose between a few related commands in one workflow moment, but loose button rows can imply false relationships, create competing primary actions, hide blocked states, and place destructive commands too close to safe progress.", "solution": "Group only related action buttons, name the group when needed, define one local scope, establish clear emphasis order, explain unavailable commands, preserve responsive order, and separate high-risk commands from safe navigation or submission actions.", "uiGuidance": [ "Render a small group of visibly related action buttons with one clear scope, one dominant primary action when needed, lower-emphasis alternatives, consistent labels, visible focus, and stable spacing.", "Keep the group readable across narrow screens by stacking deliberately, preserving source order, keeping hit targets intact, and separating destructive or risky actions from safe forward movement." ], "uxGuidance": [ "Use a button group when users need to choose between a few related commands at the same workflow moment, such as saving, continuing, going back, cancelling, applying, resetting, or exporting in one local task.", "Make hierarchy, availability, result feedback, and risk clear before activation so users do not have to guess which action is recommended or why a command is unavailable." ], "uiExamples": { "good": [ "A form footer shows Save draft, Continue, and Cancel as one named action group, with Continue primary only after required work is saved.", "A filter panel footer groups Apply filters and Reset filters while keeping Export outside the submit path." ], "bad": [ "A footer contains Save, Continue, Delete, Help, View report, and Open settings as identical primary buttons.", "A mobile button row turns actions into unlabeled icons and reorders Cancel before Continue without explanation." ] }, "uxExamples": { "good": [ "A user saves a draft, sees Continue become available, then continues without losing the saved status or action hierarchy.", "A user chooses Reset changes from a separated danger action and receives a clear reset result instead of accidentally resetting beside Continue." ], "bad": [ "A disabled Continue button gives no reason, so the user repeatedly presses Save, Cancel, and Back to find a path forward.", "A destructive Delete button sits beside Continue with the same emphasis and no review, causing input mistakes." ] }, "problemContext": [ "A form, dialog, card, toolbar section, panel footer, wizard step, or result area has multiple commands that belong to one local task.", "Users must distinguish the recommended next action from alternatives such as save draft, cancel, back, skip, reset, export, or delete.", "The actions are visible commands, not selected values, view modes, or hidden menu items.", "The group must survive mobile stacking, high zoom, keyboard focus, processing states, and disabled dependencies without losing action meaning." ], "selectionRules": [ "Choose a button group when two to four actions are contextually related and should be considered together at one workflow moment.", "Use a segmented control when the buttons represent mutually exclusive modes or views and need a persistent selected state.", "Use a menu button when secondary commands are numerous, lower priority, or contextual enough to hide behind a named trigger.", "Use confirmation dialog after a clearly labelled dangerous action is chosen and the consequence needs review before commitment.", "Use text links or navigation patterns when the controls are destinations rather than commands.", "Avoid placing destructive actions directly beside safe forward actions unless visual separation, wording, confirmation, or undo makes the risk clear.", "Keep one primary action unless the workflow intentionally presents equal choices with no recommended path.", "Move low-frequency or unrelated commands out of the group rather than adding more buttons to a crowded row." ], "requiredStates": [ "Default group with a clear label or surrounding context.", "Primary, secondary, tertiary, and danger visual hierarchy when those roles are present.", "Focused state for each button in source order.", "Hover or pressed state for pointer and touch feedback.", "Disabled or unavailable state with visible reason.", "Processing state after activation that prevents duplicate submission.", "Successful action status that names the command that ran.", "Responsive stacked state preserving action order and readable labels.", "Separated destructive action state.", "Long label and high-zoom state without clipped text." ], "interactionContract": [ "Each button performs a command immediately or starts a named flow; buttons in the group do not represent persistent selected values unless the component is intentionally a segmented or toggle group.", "The group has one local scope and a programmatic grouping when surrounding context is insufficient.", "Button labels use verbs and objects that match the result message, accessible name, and logged action.", "The primary action is visually dominant only when it is the recommended next action.", "Disabled commands are either temporarily blocked with a reason or removed until relevant.", "Processing actions prevent duplicate activation and announce progress or completion.", "Destructive actions are visually separated, lower-emphasis unless explicitly primary, and routed to confirmation, undo, or clear recovery when needed.", "Keyboard users tab through buttons in the same order that visual layout implies; Enter and Space activate the focused button.", "Responsive stacking keeps safe progression, cancellation, and danger relationships understandable." ], "implementationChecklist": [ "Inventory each command and remove actions that do not share the same local task scope.", "Choose the primary action and make secondary alternatives lower emphasis.", "Place danger actions away from safe forward actions or put them behind confirmation or undo.", "Use real button elements for commands and reserve links for navigation.", "Wrap the group in a list, role group, or toolbar only when that grouping communicates the relationship accurately.", "Keep visible labels, accessible names, icons, and result status aligned.", "Explain disabled states through helper text, inline status, or dependency messaging.", "Prevent duplicate activation during processing and restore the button state after completion or error.", "Test source order, mobile stacking, high zoom, forced colors, focus rings, touch targets, and localization." ], "commonMisuses": [ "Putting unrelated actions into one row because the layout has space.", "Using two or more high-emphasis buttons that compete for the same next step.", "Mixing destructive and non-destructive actions with identical visual weight.", "Using button groups as page navigation or content links.", "Giving command buttons aria-pressed selected state when they are not toggles or modes.", "Disabling the primary button without explaining the unmet condition.", "Replacing text labels with icons at small widths.", "Letting responsive wrapping reorder actions unpredictably." ], "critiqueQuestions": [ "Do all buttons in the group share one local task scope and workflow moment?", "Is the recommended action visually clear without creating two competing primary commands?", "Can users tell why an unavailable command is blocked and what fixes it?", "Are destructive commands separated from safe progression and backed by confirmation, undo, or recovery?", "Will source order, visible order, and keyboard order remain understandable on mobile and at high zoom?" ], "relatedPatterns": [ "segmented-control", "menu-button", "confirmation-dialog", "icon-only-ambiguous-action", "disabled-button-no-explanation", "undo", "modal-dialog", "single-page-form", "multi-step-form" ], "comparisons": [ "button-group-vs-segmented-control-vs-menu-button-vs-confirmation-dialog" ], "sourceIds": [ "uswds-button-group", "carbon-button-component", "wai-aria-apg", "material-design-buttons" ] }, { "id": "calendar-view", "completionStatus": "complete", "name": "Calendar view", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Date and time grid for scheduled events, availability, and conflicts", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to inspect scheduled events, availability, conflicts, and time ranges in context, but lists, timelines, and date fields hide where items sit on the calendar and how they overlap.", "solution": "Provide a calendar view with date navigation, month/week/day or agenda modes, event blocks, time-axis and all-day placement, overflow disclosure, selected-day detail, availability and conflict states, timezone clarity, and responsive fallback.", "uiGuidance": [ "Render a calendar view around a visible date range, mode switcher, today marker, weekday or time-axis labels, timezone, selected date, and event blocks with start, end, title, status, and all-day or timed placement.", "Show overflow, unavailable time, multi-day events, recurring events, tentative or cancelled status, current-time marker, and empty-day states as explicit visual states rather than relying on color alone." ], "uxGuidance": [ "Use calendar view when users need to understand or manage scheduled items by their position in time: date, weekday, duration, overlap, availability, recurrence, or resource assignment.", "Preserve orientation while users move between month, week, day, and agenda modes; keep visible range, timezone, selection, event detail, conflict handling, and mobile fallback clear before users create or move events." ], "uiExamples": { "good": [ "A clinic schedule shows June 2026 week view, today marker, timezone, business hours, all-day staff training, timed appointments, room labels, overlap warning, and a More link for crowded days.", "A month calendar uses weekday headings, selected date, event color plus text labels, cancelled and tentative status, current month boundaries, and an agenda panel for the selected day." ], "bad": [ "A decorative month grid contains colored dots with no event titles, no timezone, no overflow count, and no selected-day detail.", "A weekly booking calendar lets overlapping appointments stack on top of each other with no duration, conflict, or room label." ] }, "uxExamples": { "good": [ "A dispatcher switches from month to week, opens Wednesday, sees three overlapping room bookings, chooses an available slot, and receives conflict-aware feedback before saving.", "A mobile user lands on agenda mode for the selected day, changes the date from a scrollable day bar, opens an event, and can return to the same date without losing context." ], "bad": [ "A user taps +3 more in a crowded date cell but the calendar navigates away instead of showing the hidden events for that day.", "A scheduler drags an event across a daylight-saving boundary and the saved time silently shifts relative to attendees." ] }, "problemContext": [ "Events belong to specific dates, times, ranges, resources, people, rooms, services, calendars, or availability windows.", "Users compare days, weekdays, work hours, all-day items, multi-day spans, overlapping appointments, recurrence, and open slots.", "Calendar data may include tentative, cancelled, busy, free, out-of-office, unavailable, hidden, recurring, shared, or permission-limited events.", "The same surface may support passive inspection, event creation, slot selection, drag or resize, event details, reminders, export, or subscription.", "Timezone, locale, first day of week, daylight saving changes, and mobile density can change what users believe they are booking." ], "selectionRules": [ "Choose calendar view when the main question is what is scheduled when, how long it lasts, whether it overlaps, and what slots remain open.", "Use date picker when the user is choosing one date for a field and does not need to inspect multiple event blocks.", "Use timeline when users need a readable history or sequence for one object rather than a spatial time grid.", "Use list view or agenda when the interval is narrow and users need fast scanning more than spatial comparison.", "Use table or data grid when users need dense sorting, filtering, export, or column comparison across events.", "Use Kanban board when event items are primarily managed by workflow status rather than date and time position.", "Show active view mode, visible range, timezone, today, selected date, hidden events, and event counts near the calendar.", "Represent all-day, timed, multi-day, recurring, tentative, cancelled, unavailable, busy/free, and conflicting events distinctly.", "Expose overflow through a count and a detail surface instead of clipping events in a date cell.", "Avoid drag and resize behavior unless constraints, conflicts, keyboard alternatives, undo, and save feedback are designed.", "Switch to agenda, day, or selected-date detail on narrow screens when month or week cells cannot preserve event identity.", "Do not imply availability from an empty cell unless hidden calendars, permissions, resource constraints, and working hours are accounted for." ], "requiredStates": [ "Default calendar state with visible range, view mode, timezone, today marker, selected date, and event count.", "Month, week, day, and agenda or selected-day detail states when the product offers multiple modes.", "Previous, next, today, and jump-to-date navigation states.", "Event detail, create event, edit event, drag or resize preview, conflict, save pending, save failed, and undo states when editing is supported.", "Overflow state for crowded days with a visible count and accessible popover or drill-in behavior.", "Empty day, empty range, loading, failed-load, offline, permission-limited, hidden-calendar, and out-of-range states.", "All-day, timed, multi-day, recurring, cancelled, tentative, unavailable, busy, free, and current-time states.", "Responsive agenda or day-bar state where event title, time, status, and selected date stay readable." ], "interactionContract": [ "Calendar navigation changes the visible date range without clearing the selected calendar, selected date, active filters, or opened event unless the user leaves the context.", "Mode switches between month, week, day, and agenda preserve the closest equivalent date and explain when the same event appears differently.", "Each event keeps stable identity, title, start, end, all-day status, calendar/source, and status across navigation, filtering, overflow, and detail views.", "Overflow controls reveal hidden events for the same date without losing the current range or selected day.", "Creating, dragging, or resizing an event previews the target date, time, duration, resource, and conflict before save.", "Conflicts, unavailable slots, permissions, cancelled status, and timezone changes block or warn at the moment the user can still recover.", "Keyboard users can reach date navigation, mode controls, days, event blocks, overflow, and details without tabbing through every empty cell in large grids.", "Mobile or narrow layouts switch to a usable agenda/day pattern rather than hiding event identity in tiny cells." ], "implementationChecklist": [ "Define event schema: id, title, start, end, all-day flag, timezone, calendar/source, owner, resource, recurrence, status, location, conflict state, visibility, and edit permissions.", "Choose supported modes intentionally: month for long-range scanning, week/day for timed placement, agenda/list for narrow screens or dense event lists, resource view for people, rooms, or equipment.", "Implement previous, next, today, jump-to-date, mode switch, selected day, event detail, overflow, and current-time behavior before styling.", "Model crowded days, overlapping timed events, unavailable hours, hidden calendars, permission-limited events, cancelled events, tentative events, recurrence exceptions, and DST boundaries.", "Provide accessible names for dates, event blocks, overflow counts, navigation controls, and mode controls.", "Preserve focus after navigation, mode switch, overflow close, event save, drag failure, and detail close.", "Provide non-drag alternatives for moving or resizing events, including explicit date and time fields.", "Test first-day-of-week locale, timezone display, daylight saving transitions, long event titles, all-day and multi-day events, mobile agenda, and print or export if supported." ], "commonMisuses": [ "Using calendar view as a decorative month card for unscheduled content.", "Showing colored dots without event names, counts, or selected-day details.", "Hiding overflowed events in a crowded date cell.", "Letting drag and resize silently create schedule conflicts.", "Mixing local display time and saved timezone without disclosure.", "Treating empty cells as available when other calendars, permissions, or resources are hidden.", "Forcing users to use a full calendar view for one remembered date.", "Crushing month or week grids on mobile instead of providing an agenda fallback." ], "critiqueQuestions": [ "What does spatial placement answer here: weekday, duration, overlap, availability, resource, or recurrence?", "Can users tell which date range, timezone, view mode, calendars, and filters are visible?", "What happens when a day has too many events to fit?", "Can users inspect all-day, multi-day, recurring, cancelled, tentative, hidden, and unavailable events?", "If events can move, where are conflicts, constraints, keyboard alternatives, undo, and save feedback handled?", "Would date picker, timeline, list view, table, data grid, or Kanban board better fit the task?" ], "relatedPatterns": [ "date-picker", "date-input", "time-picker", "timeline", "list-view", "table", "data-grid", "details-panel", "filter-panel", "sort-controls" ], "comparisons": [ "calendar-view-vs-date-picker-vs-timeline-vs-list-view" ], "sourceIds": [ "fullcalendar-month-view", "fullcalendar-timegrid-view", "fullcalendar-event-popover", "fullcalendar-accessibility", "microsoft-power-apps-calendar-control", "moj-design-system-calendar" ] }, { "id": "camera-capture", "completionStatus": "complete", "name": "Camera capture", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Permission-gated live camera preview for creating and reviewing new photo or video media", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Camera capture can reduce manual entry and prove visual context, but camera access is permission-gated, privacy-sensitive, hardware-dependent, and failure-prone; without explicit preview, quality review, fallback, and stream cleanup, users can capture the wrong media, expose private surroundings, or get blocked by permission denial.", "solution": "Provide a camera capture flow with explicit user invocation, contextual permission rationale, live preview, active-camera indicator, framing and quality guidance, capture feedback, review before upload, retake and edit controls, file or manual fallback, cancel recovery, and guaranteed media-track cleanup.", "uiGuidance": [ "Render camera capture as a deliberate media-acquisition surface with purpose text, camera permission state, selected camera, live preview, privacy indicator, framing guide, capture button, shutter feedback, review preview, retake, crop or rotate, submit, cancel, and upload fallback.", "Show what will happen to the captured image or video before access is requested: target object, required quality, storage or retention, whether the stream is active, and whether users can complete the task without camera access." ], "uxGuidance": [ "Use camera capture when users need to create new visual evidence, scan a document, attach a receipt, capture damage, verify an object, or record a short video from a device camera.", "Design the lifecycle from unsupported state through permission, device choice, preview, framing guidance, capture, frozen result, quality repair, retake, review, upload or attach, cancellation, and stream cleanup." ], "uiExamples": { "good": [ "A receipt scanner asks users to Scan receipt, explains camera use, shows a live preview with document edges, captures a frozen preview, then offers Retake, Crop, Upload file, and Attach to claim.", "A damage report flow labels the rear camera, shows a privacy indicator and steady frame guide, warns when the image is blurry, and keeps Submit disabled until a reviewable photo is captured.", "A profile-photo flow offers Take photo or Upload image, mirrors the user-facing camera preview, lets users crop the captured photo, and clears the stream after cancel." ], "bad": [ "The page opens the camera on load, hides the active-stream indicator, and starts recording before users choose a task.", "The capture button uploads immediately with no frozen preview, retake, crop, or file fallback.", "A denied camera prompt leaves the workflow blank even though manual entry or upload would satisfy the requirement." ] }, "uxExamples": { "good": [ "A user starts Scan receipt, grants camera access, sees Align the whole receipt, captures a photo, reviews blur feedback, retakes, then attaches the corrected image.", "A user denies camera access in a clinic and completes the same identity-document step by uploading a saved image.", "A user switches from front to rear camera for serial-number capture, cancels before submit, and the app stops the stream and clears the unsaved image." ], "bad": [ "A user closes a capture sheet but the camera light stays on and the preview remains active in the background.", "A user captures a child ID photo and the app leaves it visible in recent previews after cancel.", "A user takes a blurry insurance photo and learns it failed only after the whole claim has been submitted." ] }, "problemContext": [ "The task asks users to create new images or video for receipts, documents, identity evidence, damage reports, profile photos, QR-like visual data, support diagnostics, deposits, or field work.", "Users may be on mobile, desktop webcam, tablet, kiosk, assistive technology, low light, poor network, denied permissions, unsupported browsers, shared devices, or privacy-sensitive locations.", "The product may need still images, video snippets, facing-mode choice, resolution constraints, crop, rotation, blur or glare detection, metadata handling, upload progress, redaction, or retention notice.", "Camera capture is often adjacent to file upload, permission request, sensitive-data reveal, full-screen takeover, drag-and-drop upload, and future QR or barcode scanning flows." ], "selectionRules": [ "Choose camera capture when the product must create new camera media and users need live preview, framing, capture, review, and retake behavior.", "Use file upload when existing local files are acceptable and live camera access, active media stream, and shutter feedback are not the main interaction.", "Use permission request for the standalone access rationale and timing; camera capture includes the permission ask only as one state inside the capture lifecycle.", "Use sensitive-data reveal when captured content needs masking, timed reveal, redaction, or audit after acquisition.", "Use full-screen takeover when the capture task needs an immersive temporary mode with its own navigation and exit contract.", "Use drag-and-drop upload when users move existing files into a drop zone rather than create a new photo or video.", "Prefer explicit user action before starting the stream; never activate the camera only because a page, route, carousel, or modal loaded.", "Offer upload, manual entry, skip, or assisted alternatives before or immediately after permission denial.", "Capture is not submission: freeze the frame, show what was captured, and require review for consequential workflows.", "Stop tracks and clear unsaved previews on cancel, close, submit, route change, timeout, or permission revocation." ], "requiredStates": [ "Unsupported browser or insecure-context state with upload or manual alternative.", "Camera permission not requested, granted, denied, and revoked states.", "Start capture state with purpose, target object, and privacy explanation.", "Device selection or front/rear camera switch state when multiple cameras are available.", "Live preview state with active camera indicator, framing guide, and stop control.", "Low light, glare, blur, occlusion, wrong orientation, or missing-subject quality warning state.", "Captured still or recorded clip state with frozen preview.", "Review state with retake, crop, rotate, replace, submit, and cancel controls.", "Upload fallback, file fallback, manual entry, or skip state when camera fails or is denied.", "Upload pending, upload failed, retry, saved, attached, or submitted state.", "Cancel or dirty-exit state that explains whether captured media will be discarded.", "Stream cleanup state after cancel, submit, permission loss, or navigation.", "Sensitive capture state for IDs, faces, addresses, payment cards, private spaces, minors, or location-revealing images." ], "interactionContract": [ "The camera stream starts only after a deliberate user action and contextual permission rationale.", "Users can see whether camera access is inactive, requesting, active, paused, denied, unsupported, or stopped.", "The live preview names the selected camera and shows framing guidance that matches the task's quality requirement.", "Capture freezes the result and moves to review; upload or submit does not happen from the shutter press alone unless the task is explicitly low-risk and reversible.", "Retake, replace with file, cancel, and submit controls are reachable by keyboard and touch.", "Camera denial, unavailable device, unsatisfied constraints, upload failure, and network loss preserve the task and expose alternatives.", "Closing, canceling, leaving the route, submitting, or losing permission stops the media tracks and removes unsaved sensitive previews.", "Captured media metadata, storage, retention, and review boundaries are disclosed when the content is sensitive or externally submitted." ], "implementationChecklist": [ "Define capture purpose, target object, allowed media type, required resolution, facing mode, quality checks, fallback path, retention rule, and downstream validation before requesting camera access.", "Use a secure context and request media only from an explicit capture action; handle permission denied, not found, not readable, overconstrained, and aborted states.", "Show active-stream status, selected camera, switch-camera control, framing overlay, quality feedback, and stop or cancel control while preview is live.", "Freeze the captured frame or clip for review and keep capture state separate from upload, submitted record, file fallback, and sensitive reveal state.", "Provide retake, crop, rotate, replace, upload file, manual entry, submit, cancel, retry upload, and discard-review paths where relevant.", "Stop all media tracks on cancel, close, successful submit, route change, component unmount, permission revocation, and timeout.", "Avoid persisting raw images, EXIF, location metadata, faces, IDs, or private-space previews unless users understand the purpose and retention.", "Test mobile front and rear cameras, desktop webcams, denied permission, no camera, camera in use, low light, high zoom, keyboard, screen reader, file fallback, slow upload, and privacy-sensitive cancellation." ], "commonMisuses": [ "Opening the camera automatically on page load or hover.", "Treating the shutter button as final upload for consequential tasks.", "Hiding the live preview, active camera state, stop control, or selected camera.", "Blocking the workflow when camera permission is denied even though upload or manual entry would work.", "Leaving the camera stream active after close, cancel, navigation, or submit.", "Using camera capture when a normal file upload or text field would be simpler and less invasive.", "Saving sensitive captured media or metadata after users cancel.", "Showing quality errors only after final submission instead of during preview or review." ], "critiqueQuestions": [ "What explicit user action starts the camera, and what purpose text appears before permission?", "What can users do when camera permission is denied, the camera is already in use, or the browser does not support capture?", "Does the preview show active camera state, selected camera, framing guide, and quality guidance?", "Is the shutter action separate from final upload or submission, and can users retake or replace the capture?", "When are media tracks stopped, and how is unsaved sensitive media cleared?", "Which metadata, images, frames, or thumbnails are stored, for how long, and who can access them?", "Is this really camera capture, or would file upload, permission request, full-screen takeover, or sensitive-data reveal own the main problem?" ], "relatedPatterns": [ "file-upload", "permission-request", "sensitive-data-reveal", "full-screen-takeover", "drag-and-drop-upload", "voice-command" ], "comparisons": [ "camera-capture-vs-file-upload-vs-permission-request-vs-sensitive-data-reveal-vs-full-screen-takeover-vs-drag-and-drop-upload" ], "sourceIds": [ "mdn-mediadevices-getusermedia", "mdn-html-capture-attribute", "w3c-mediacapture-streams", "mdn-media-capture-constraints", "mdn-permissions-api", "mdn-html-file-input" ] }, { "id": "card-grid", "completionStatus": "complete", "name": "Card grid", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Responsive multi-column grid of peer object cards", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to browse many peer objects where visual preview, compact metadata, and quick selection matter, but a vertical card list is too slow, a table overemphasizes columns, and a named collection would imply membership management that is not present.", "solution": "Present the objects as a responsive card grid with consistent card anatomy, stable preview dimensions, predictable column reflow, grid-level controls, clear selected and saved states, loading and empty states, keyboard order that matches visual order, and explicit alternatives for dense comparison tasks.", "uiGuidance": [ "Arrange peer object cards in a responsive grid with stable tile widths, predictable gutters, consistent preview aspect ratios, titles, compact metadata, state labels, and one primary action area.", "Keep grid-level controls such as filters, sort, result count, selected count, density, pagination, and loading status outside the cards so each tile stays focused on one object." ], "uxGuidance": [ "Use card grid when users need visual browsing, light comparison, and quick selection across many peer objects that can be understood from compact card summaries.", "Preserve object identity, selected state, saved state, focus, and result position as the grid changes column count, loads more cards, filters, sorts, or switches density." ], "uiExamples": { "good": [ "A course catalog grid shows four cards per row on desktop, each with the same image ratio, course title, provider, level, duration, saved state, and Enroll action.", "A media asset grid shows thumbnail, file type, usage rights, modified date, selected checkbox, and a More actions button in the same place on every card." ], "bad": [ "A grid mixes landscape images, portrait images, text-only cards, and action tiles without reserving preview space or explaining missing media.", "Each card has different metadata order, different action placement, and different height, making the grid look rich but hard to scan." ] }, "uxExamples": { "good": [ "A shopper filters a product grid to In stock, switches from comfortable to compact density, selects three items, and the selected count and item positions remain understandable.", "A keyboard user tabs through card title, Save, checkbox, and More actions while the visual row and column order match the reading order." ], "bad": [ "A user tries to compare course prices, but every card wraps the price under different text lengths and the grid gives no sort or table alternative.", "A user filters to saved assets and loses selection because the product tracked selected cards by visible position rather than object ID." ] }, "problemContext": [ "Items are peer objects such as products, courses, files, templates, assets, locations, people, articles, media, reports, or examples.", "Users choose from visual or semi-visual summaries instead of reading every item in full.", "The result set may be filtered, sorted, searched, selected, saved, paginated, infinitely loaded, or displayed at multiple densities.", "Cards may contain thumbnail, title, short label, rating, price, status, owner, file type, duration, tags, and one or two object actions." ], "selectionRules": [ "Choose card grid when users need to see multiple objects at once and visual preview or compact card identity helps them choose.", "Choose card grid when items are peers with comparable card anatomy and no collection-level membership behavior.", "Choose card grid when the layout can reflow across breakpoints without hiding title, preview, state, selection, or primary actions.", "Use card list when each object requires a longer summary, more metadata, or a stronger single-column reading sequence.", "Use collection when the item set has a title, owner, saved membership, sharing, ordering, sections, or add and remove behavior.", "Use table or data grid when aligned attribute comparison, numeric ranking, row operations, cell editing, or dense scanning is the main task.", "Use browse by category when each card is a topic or taxonomy destination rather than an object card.", "Use carousel only when a small curated subset is sequentially featured and not every card needs simultaneous visibility.", "Avoid card grid when images are decorative, missing, or inconsistent enough to dominate the layout without improving choice.", "Avoid card grid when users need to compare exact values that would be clearer in columns." ], "requiredStates": [ "Default grid with heading or label, result count, active view controls, and at least one full row of peer cards.", "Card default, hover, focus, active, selected, saved, unavailable, loading, failed-thumbnail, missing-thumbnail, disabled, and opened states.", "Grid filtered, sorted, searched, compact density, comfortable density, loading-more, paginated, empty, no-results, and failed-load states.", "Responsive one-column, two-column, three-column, and wide multi-column states with stable gutters and preserved card order.", "Selected-away, hidden selected, bulk action, saved count, item removed, item added, and restored item states when selection or saving is supported.", "Long title, missing image, mixed media type, permission-limited, stale item, duplicate title, and unavailable action states." ], "interactionContract": [ "Each card represents one object and keeps title, preview, key metadata, state, and actions in the same relative positions across cards.", "Visual order, DOM order, keyboard order, and screen-reader order remain consistent after responsive reflow.", "Card activation, selection, save, overflow, and destructive actions have separate hit targets and accessible names that include the object title.", "Grid-level filters, sort controls, density switches, pagination, and load-more controls update counts and preserve object-keyed selected, saved, and focused state.", "Missing images use a reserved fallback area so card height, row alignment, focus position, and action placement do not jump.", "Column-count changes do not convert card grid behavior into a hidden carousel, a masonry layout with confusing order, or a dense table without headers.", "Bulk actions state whether they affect visible cards, selected cards, hidden selected cards, or all matching cards.", "When users need exact comparison, the surface offers a sort, filter, details view, compare mode, table view, or other clear path instead of forcing visual hunting." ], "implementationChecklist": [ "Define card anatomy: thumbnail or icon, title, secondary label, compact metadata, status, price or rating if relevant, primary action, selection control, save control, and overflow action.", "Set grid minimum card width, maximum columns, gutters, row gaps, preview aspect ratio, title line limits, and responsive breakpoints before binding live content.", "Render the card set as a list or grid with accessible labelling, object-keyed IDs, visible result count, selected count, saved count, and active filters.", "Keep interactive descendants separate rather than placing multiple buttons and links inside one wrapping card button.", "Provide stable fallbacks for missing previews, long titles, unavailable items, mixed media, duplicate names, and permission-limited cards.", "Preserve selected, saved, expanded, focused, and recently acted-on cards across sort, filter, density change, breakpoint reflow, pagination, and loading more.", "Offer keyboard operation for selection, save, overflow, bulk actions, load more, and any reorder or compare controls.", "Test screen reader order, zoom, localization, high contrast, long text, reduced width, pointer target spacing, async loading, and virtualized grids." ], "commonMisuses": [ "Using card grid as decorative chrome for rows that need dense scanning or aligned comparison.", "Allowing every card to choose its own image ratio, title placement, metadata order, and action area.", "Treating a grid of result cards as a collection without collection identity, owner, count, or membership rules.", "Hiding important card actions behind hover-only affordances that vanish on touch and keyboard.", "Tracking selected cards by index, so filtering, sorting, or responsive reflow changes which object is selected.", "Using masonry layout for task-critical keyboard navigation without a clear reading order.", "Letting missing thumbnails collapse cards and break row alignment.", "Putting too many visible actions in every card until the grid becomes a tab-stop maze." ], "critiqueQuestions": [ "What does the grid reveal by showing several cards at once that a card list would slow down?", "Are users visually browsing peer objects, managing a named collection, navigating categories, or comparing columns?", "Which fields must appear in the same place on every card for scanning to work?", "How does the grid preserve selected, saved, focused, and acted-on cards after filtering, sorting, loading, and breakpoint changes?", "What fallback keeps missing previews from changing card height or keyboard order?", "When exact comparison becomes important, what route to table, sort, filter, compare, or details view is provided?" ], "relatedPatterns": [ "card-list", "collection", "list-view", "table", "data-grid", "browse-by-category", "filter-panel", "sort-controls", "pagination", "empty-state", "hover-card", "preview-panel" ], "comparisons": [ "card-grid-vs-card-list-vs-collection-vs-table" ], "sourceIds": [ "react-spectrum-cardview", "material-cards-guidelines", "material-responsive-layout-grid", "primer-card", "nng-cards-component" ] }, { "id": "card-list", "completionStatus": "complete", "name": "Card list", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Single-column sequence of bounded rich object summaries", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to browse and act on objects that require more context than a compact row can hold, but a grid would weaken reading order, a table would overemphasize columns, and a named collection would imply set-management behavior that is not present.", "solution": "Present each object as a self-contained card in a vertical list, using consistent anatomy for preview, title, summary, metadata, status, primary activation, secondary actions, selection, expansion, loading, empty, and responsive states.", "uiGuidance": [ "Render each item as a bounded card with a stable anatomy: preview or icon, title, concise summary, metadata, status, and one clear primary action or activation target.", "Keep cards in a single-column sequence when reading order, mobile behavior, and rich per-item summaries matter more than dense rows or multi-column visual browsing." ], "uxGuidance": [ "Use card list when users browse rich object summaries and need enough context to choose or act without opening every item.", "Preserve predictable card anatomy, action ownership, selected state, and visible result counts as users sort, filter, expand, select, or load more cards." ], "uiExamples": { "good": [ "A grant-opportunity card shows program name, eligibility summary, deadline, award range, status, agency, and a labelled Save action in the same position on every card.", "A media review card shows thumbnail, title, transcript excerpt, content type, duration, review status, and an overflow menu with actions named for that item." ], "bad": [ "Every card uses a different layout, so deadline, owner, status, and actions appear in different places.", "A one-line row is wrapped in a large decorative card with no preview, summary, metadata, or additional decision support." ] }, "uxExamples": { "good": [ "A user filters opportunities to Closing soon, saves two cards, expands one summary, changes sort order, and the saved count and card identities remain clear.", "A keyboard user tabs from card title to Save and More actions, and each control names the opportunity it affects." ], "bad": [ "A user clicks inside a card to select text but the whole card opens, while a nearby icon deletes the item with no item name.", "A user tries to compare award amounts across cards, but each amount appears in a different location and some cards hide it behind expansion." ] }, "problemContext": [ "Items are objects such as opportunities, articles, courses, products, files, people, reports, cases, media assets, or search results.", "Each item benefits from multiple information types: image or icon, title, description, metadata, status, owner, date, tags, and actions.", "Users are browsing or triaging rather than doing strict column comparison or spreadsheet-like editing.", "The surface may be filtered, sorted, paginated, infinitely loaded, selectable, expandable, or paired with a preview or detail route." ], "selectionRules": [ "Choose card list when each item needs more context, imagery, or mixed metadata than a dense row can comfortably show.", "Choose card list when a single-column order is important and users should read one rich summary at a time.", "Use list view when compact scanning, aligned row placement, and high item density matter more than rich card summaries.", "Use collection when the item set itself has title, owner, membership, sharing, ordering, or management behavior.", "Use browse by category when cards are topic or category destinations rather than object summaries.", "Use table or data grid when users need aligned comparison, numeric analysis, column sorting, range selection, or cell editing.", "Use details panel or preview panel when the card should remain compact and detailed inspection belongs beside or beyond the list.", "Avoid card list when card chrome does not add decision-making value beyond a simple row.", "Avoid card list when inconsistent card heights and anatomy make scanning or comparison harder than rows.", "Avoid card list when the main task is seeing many thumbnails at once in multiple columns." ], "requiredStates": [ "Default card list with heading or label, result count, and visible card summaries.", "Card default, hover, focus, active, selected, disabled, loading, unavailable, saved, new, updated, and error states.", "Primary card activation state and separate secondary action, overflow menu, save, share, select, and destructive action states.", "Expanded card and collapsed card states when summaries reveal more detail inline.", "Filtered, sorted, searched, paginated, loading-more, no-results, empty, and failed-load states.", "Hidden selected, selected-away, bulk action, and saved-count states when selection or saving is supported.", "Responsive narrow-screen state with stable title, summary, metadata, status, and actions.", "Long title, missing image, missing metadata, mixed media type, permission-limited, and stale item states." ], "interactionContract": [ "Each card represents one object or concept and exposes one primary identity that stays visible across all states.", "The card's primary activation, secondary buttons, menu, selection control, and destructive actions have distinct hit targets and accessible names.", "Card anatomy remains consistent enough that users can predict where title, status, metadata, and actions appear.", "Filtering and sorting update card order or membership without losing selected, saved, expanded, or focused card state unexpectedly.", "Expansion reveals additional summary detail without moving key controls out of reach or hiding the card's primary identity.", "Loading more cards preserves scroll position, focus, card labels, and result counts.", "Missing images or unavailable previews have meaningful fallbacks that do not collapse card dimensions.", "Bulk or saved actions state whether they affect visible cards, selected cards, hidden selected cards, or the whole result set." ], "implementationChecklist": [ "Define the card object, primary title, preview media, summary, metadata fields, status labels, primary action, secondary actions, and optional selection model.", "Use semantic list markup for the card sequence and article, link, button, checkbox, or menu semantics inside each card according to behavior.", "Give the card list a heading or accessible label and expose result count, active filters, selected count, and saved count near the list.", "Keep card anatomy stable across missing media, long text, selected state, hover, focus, and responsive widths.", "Label icon-only card actions with the card title, such as Save Grant opportunity G-2048.", "Separate card click, title link, Save, More actions, selection checkbox, and destructive actions so their hit targets do not overlap.", "Design empty, no-results, loading, failed-load, saved, selected, expanded, unavailable, permission-limited, and missing-preview states.", "Test keyboard order, focus visibility, screen reader card identity, action labels, long text, localization, zoom, mobile wrapping, and missing image fallbacks." ], "commonMisuses": [ "Using cards as decorative wrappers for dense rows.", "Making the entire card clickable while nesting conflicting buttons or links inside it.", "Changing card anatomy item by item until scanning becomes unpredictable.", "Hiding key metadata behind expansion when users need it to choose among cards.", "Using card list for strict price, date, owner, or numeric comparison that needs aligned columns.", "Letting images define the card when missing or low-quality images are common.", "Showing many secondary actions on every card until the list becomes an action maze.", "Failing to preserve selected, saved, or expanded card state after sort, filter, or load more." ], "critiqueQuestions": [ "What extra decision support does the card provide that a compact row cannot?", "Is the user browsing rich summaries, comparing attributes, managing a named set, or navigating categories?", "What is the card's primary activation, and which actions are separate secondary controls?", "Can users predict where title, status, metadata, and actions appear on every card?", "What happens to saved, selected, expanded, and focused cards after sorting, filtering, or loading more?", "Would list view, table, data grid, collection, details panel, preview panel, or browse by category better fit the task?" ], "relatedPatterns": [ "list-view", "collection", "browse-by-category", "details-panel", "preview-panel", "filter-panel", "sort-controls", "pagination", "empty-state", "table" ], "comparisons": [ "card-list-vs-list-view-vs-collection-vs-browse-by-category" ], "sourceIds": [ "material-cards-guidelines", "react-spectrum-card", "nng-cards-component", "fluent-react-card" ] }, { "id": "carousel", "completionStatus": "complete", "name": "Carousel", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Sequential slide viewer for a small peer content set", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Teams often want several pieces of content to occupy one prominent area, but rotating or poorly controlled carousels can hide important content, interrupt reading, trap focus, and make item position unclear.", "solution": "Use a carousel only for a small peer slide set, provide explicit slide navigation and rotation controls, expose current position and slide identity, stop unwanted motion, and use static or list-based layouts when content is important, comparable, or numerous.", "uiGuidance": [ "Render a carousel as a labelled region with one current slide or a small visible subset, clear previous and next controls, named slide picker controls or thumbnails, current slide position, and a pause or play control if rotation exists.", "Keep slide content, controls, and status visually connected; do not rely on hidden dots, timed motion, or swipe-only gestures as the only way to discover or control the slide set." ], "uxGuidance": [ "Use carousel only when several peer slides must share one constrained space and users can browse them safely without missing required information.", "Make user control stronger than motion: avoid auto-advance by default, stop rotation on focus or hover, preserve focus after slide changes, and keep the current slide stable while users read or interact." ], "uiExamples": { "good": [ "A product tour carousel shows one feature slide at a time with Previous, Next, Stop rotation, labelled slide dots, and text announcing Slide 2 of 4.", "A gallery carousel uses named thumbnails, visible captions, and keyboard-operable arrows while keeping the current image stable during focus." ], "bad": [ "A homepage hero rotates every three seconds, hides the pause control, and uses unlabeled dots that do not identify the current promotion.", "A carousel hides required onboarding steps behind swipe-only cards with no next button, position, or way to pause motion." ] }, "uxExamples": { "good": [ "A keyboard user tabs to Stop rotation first, pauses the carousel, moves to Next slide, activates slide 3, and focus remains on the chosen control while the status updates.", "A user hovers a slide to read the offer and rotation stops until they leave or explicitly start rotation again." ], "bad": [ "A user starts reading shipping details and the carousel advances to a different slide before they finish.", "A screen reader user hears Button, Button, Button for slide dots and cannot tell which slide is visible." ] }, "problemContext": [ "Several peer items compete for one constrained display area such as a product tour, media gallery, promotion slot, onboarding preview, or small content rail.", "Only one slide or a small subset should be visible at a time, and users do not need to compare all slides simultaneously.", "The team can keep controls, labels, current position, motion state, and focus behavior synchronized.", "No required decision, warning, or primary action depends on users seeing a hidden slide at the right time." ], "selectionRules": [ "Choose carousel when a small set of peer slides must share a constrained visual slot and users can move through them with explicit controls.", "Use static content, page sections, list view, card grid, or collection when every item matters or comparison is important.", "Use tabs when the labels are meaningful section names and users are switching content panels rather than moving through slides.", "Use pagination when users move through a large ordered set with page numbers, ranges, totals, and result persistence.", "Use recommendations or recently viewed when the underlying job is ranked suggestion or recency history; carousel may only be the rail presentation.", "Avoid auto-advance by default, especially for text-heavy, task-critical, mobile, or assistive-technology contexts.", "If auto-advance exists, put the stop or pause control before slide-changing controls in tab order and stop rotation on focus and hover.", "Do not hide required fields, critical warnings, primary navigation, or irreversible actions on non-visible slides.", "Use named slide picker controls, thumbnails, or tabs when users need direct access to known slides; dots without names are insufficient.", "Keep swipe gestures as an enhancement, not the only control path." ], "requiredStates": [ "Initial slide state with carousel label, slide identity, current position, and previous or next controls.", "Manual next and previous state with focus preserved on the activated control.", "Direct slide picker state with current slide indicated and picker names exposed.", "Paused rotation state when auto-advance is stopped by user command, focus, or hover.", "Playing rotation state only when motion is explicit and controllable.", "Last and first slide boundary state for finite carousels or clear wrap behavior for looping carousels.", "Loading media or failed slide state with stable controls and no skipped focus.", "Reduced motion state where rotation and animated transitions are disabled or minimized.", "Small viewport state with reachable controls and readable slide content." ], "interactionContract": [ "Previous and next controls change the current slide by one step or follow a clearly indicated wrap rule.", "Slide picker controls move directly to a named slide and expose which slide is current.", "If rotation starts automatically, focus entering the carousel stops it and the stop or pause control remains available.", "Hovering or interacting with slide content stops rotation until the user explicitly resumes or leaves according to the documented behavior.", "Changing slides does not move keyboard focus into hidden content or remove focus from the activated control.", "Only the current visible slide or visible subset is exposed as current content; hidden slides are not reachable as if they were visible.", "Slide content links and buttons remain ordinary interactive controls and do not conflict with carousel navigation." ], "implementationChecklist": [ "Decide whether carousel is justified by space constraints or whether a static section, list, grid, tabs, or pagination would be clearer.", "Define slide IDs, names, order, count, current position, and wrap behavior before rendering controls.", "Provide Previous, Next, direct slide picker controls, and a pause or play control when rotation exists.", "Label every control by action and slide target, such as Next slide, Previous slide, Stop slide rotation, or Show Backup checklist slide.", "Stop rotation on focus and hover, respect reduced motion, and avoid starting rotation for text-heavy or task-critical content.", "Preserve keyboard focus after slide changes and prevent hidden slide controls from staying in tab order.", "Announce slide changes through a polite status only for user-initiated changes, not for constant automatic motion.", "Test keyboard, screen reader, pointer hover, swipe enhancement, reduced motion, first and last slide boundaries, mobile layout, and content links." ], "commonMisuses": [ "Auto-advancing slides without a pause or stop control.", "Using unlabeled dots with no current-slide name or state.", "Hiding critical content or required tasks on later slides.", "Using a carousel because multiple stakeholders want homepage priority instead of designing a clear information hierarchy.", "Treating carousel as the whole pattern when the rail actually contains recommendations, recently viewed items, related links, or cards that need their own rules.", "Making swipe the only way to move slides.", "Leaving controls inside hidden slides in the keyboard tab order.", "Letting slide changes steal focus or reset partially read media." ], "critiqueQuestions": [ "Why must these items share one slot instead of being static, listed, or grouped?", "Can users pause motion before the carousel changes content?", "Can users identify the current slide, total count, and target of each slide picker?", "What happens when focus or pointer enters the carousel?", "Is any required information, warning, form field, or primary task hidden on another slide?", "Would tabs, pagination, recommendations, recently viewed, a grid, or a list better match the user's job?" ], "relatedPatterns": [ "tabs", "recommendations", "recently-viewed", "browse-by-category", "pagination", "step-navigation" ], "comparisons": [ "carousel-vs-tabs-vs-recommendations-vs-pagination" ], "sourceIds": [ "wai-aria-apg-carousel", "wai-carousels-tutorial", "nng-auto-forwarding-carousels", "nng-effective-carousels", "chrome-accessible-carousel" ] }, { "id": "carousel-auto-advance-without-pause", "completionStatus": "complete", "name": "Carousel auto-advance without pause", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Anti-pattern where timed carousel rotation changes visible content without user control", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Auto-advancing carousels without a reachable pause or stop path interrupt reading, hide controls, move focused or hovered content, create noisy announcements, and can make users miss critical information.", "solution": "Disable auto-advance by default or make it explicitly user-started; if timed rotation exists, provide a first reachable pause or stop control, stop on focus and hover, respect reduced motion, keep interaction state stable, and use static, tabbed, recommendation, or paginated alternatives when rotation hides real work.", "uiGuidance": [ "Treat automatic slide rotation as motion that must be controlled before it changes content: expose a reachable pause or stop control, current slide position, named slide controls, and a visible motion state.", "Do not let a carousel rotate while users focus controls, hover to read, enter form data, inspect recommendation reasons, or use reduced-motion settings." ], "uxGuidance": [ "Prefer user-started rotation or a static first slide; users should never need to race a timer to read, compare, submit, dismiss, or recover information.", "If the business insists on auto-advance, the pause or stop path must be first, obvious, persistent, keyboard reachable, and honored across focus, hover, background-tab return, mobile interaction, and reduced-motion states." ], "uiExamples": { "good": [ "A campaign carousel loads paused, shows Stop rotation before Next and Previous, names each slide, and changes only after the user chooses Start rotation.", "A recommendation rail pauses when a user focuses a Save button, hovers over a card reason, or opens feedback, and it resumes only through an explicit control." ], "bad": [ "A homepage hero advances every four seconds, hides Pause after the slide dots, and keeps moving while keyboard focus is inside a slide CTA.", "A rotating offer rail changes while the user types in a visible form field, causing the field and recommendation feedback controls to disappear." ] }, "uxExamples": { "good": [ "A keyboard user tabs into the carousel, lands on Pause rotation first, stops motion, opens the visible slide action, and focus remains stable.", "A user with reduced motion enabled receives a static carousel with manual slide controls and no automatic announcements." ], "bad": [ "A reader starts scanning eligibility details and the carousel advances before they finish, with no way to stop or restore the slide.", "A screen reader user hears frequent slide-change announcements that were not initiated by the user and cannot silence them from the carousel." ] }, "problemContext": [ "A carousel, hero, promotion rail, onboarding slider, or recommendation strip changes visible content on a timer.", "The slide can contain text, calls to action, form fields, recommendation reasons, feedback controls, warnings, or decision-support information.", "Users may read slowly, use keyboard or assistive technology, hover for detail, switch tabs, use mobile gestures, or prefer reduced motion.", "The product wants motion for attention, but users need control over timing, focus, announcements, and recovery." ], "selectionRules": [ "Flag the anti-pattern whenever visible carousel content changes automatically and a pause or stop control is missing, delayed, hidden, or unreachable before the moving content.", "Choose a standard carousel only when the slide set is small, supplemental, manually controllable, and safe to browse one slide at a time.", "Use tabs when users are switching among named sibling panels; tab panels should not rotate on a timer.", "Use recommendations when the rail contains ranked or personalized suggestions that need reasons, dismissal, sponsored labels, and feedback controls that must not rotate away mid-action.", "Use pagination, a list, or a grid when users need stable position, large result sets, comparison, or repeated scanning.", "Disable auto-advance for text-heavy, task-critical, form, consent, legal, eligibility, warning, checkout, or assistive-technology sensitive content.", "If auto-advance remains, put Pause or Stop before slide-changing controls in tab order and keep it visible in every responsive layout.", "Stop rotation when keyboard focus enters the carousel, when pointer hover suggests reading, when a slide control opens, and when the page returns from the background.", "Respect reduced-motion preferences by disabling timed rotation and minimizing animated transitions.", "Do not announce automatic slide changes repeatedly; reserve polite status updates for user-initiated changes or explicit motion-state changes." ], "requiredStates": [ "Rotation stopped by default state with visible current slide, total count, and Pause or Start rotation control.", "Pause first state where the stop control is first in the carousel tab order before previous, next, pickers, or slide actions.", "User-start rotation state that begins motion only after an explicit command and exposes how to stop it.", "Focus stop state where keyboard focus inside the carousel stops rotation and preserves focus.", "Hover stop state where pointer hover or slide interaction stops rotation while the user reads.", "Reduced-motion state where automatic rotation and nonessential animation are disabled.", "Resume safely state where rotation resumes only after explicit user action and does not skip unread slides.", "Slide action stable state where activating a slide link, save, dismiss, or feedback control does not trigger a timed advance.", "Reading lock state for long copy, captions, disclosures, warnings, or eligibility details.", "Form entry lock state where typed input, validation, and focus persist without the slide disappearing.", "Background tab return state where a hidden page does not fast-forward slides or restart motion without consent.", "Bad no-pause state with moving slides and no reachable stop control.", "Bad hidden-pause state where pause exists after anonymous dots, in an overflow, or only on hover.", "Bad focus-ignored and hover-ignored states where rotation continues during keyboard or pointer reading.", "Bad constant-announcement state where assistive technology receives unsolicited slide updates." ], "interactionContract": [ "Pause or Stop rotation immediately freezes the visible slide, updates the motion state, and remains available for resume or restart.", "Start rotation is explicit, reversible, and does not remove manual previous, next, picker, or slide action controls.", "Focus entering any carousel control or slide action stops rotation before timed content changes.", "Pointer hover, touch exploration, opened popovers, expanded text, recommendation feedback, and form fields keep the current slide stable.", "Reduced-motion and user-disabled animation settings override any configured auto-advance timer.", "Returning from a background tab, minimized app, or locked mobile screen does not fast-forward through missed slides.", "User-initiated slide changes may update a polite status; timer-driven changes must not create repeated unsolicited announcements." ], "implementationChecklist": [ "Decide whether auto-advance is needed at all; default to paused or static content unless the user starts motion.", "Place Pause or Stop rotation first in the carousel DOM and visible control order when rotation can occur.", "Bind focusin, pointer hover, touch interaction, form input, popover open, and recommendation feedback states to stop or suspend rotation.", "Check prefers-reduced-motion and product-level motion settings before enabling timers or animated transitions.", "Preserve current slide, focused element, typed values, open disclosures, selected recommendation feedback, and live-region behavior while pausing and resuming.", "Use named slide controls and a visible slide count so users can recover the slide that moved.", "Throttle or suppress automatic live-region announcements and announce only user-commanded changes.", "Test keyboard, screen reader, hover, touch, mobile viewport, reduced motion, background tab return, slow reading, form entry, recommendation feedback, and failure recovery." ], "commonMisuses": [ "Hiding Pause behind carousel dots, hover-only controls, or an overflow menu.", "Starting rotation automatically because marketing wants movement without testing reading time or assistive technology impact.", "Continuing to rotate while focus is inside a slide, a form field has text, or the pointer is hovering over details.", "Treating a recommendation rail as a decorative carousel and rotating away reasons, dismiss buttons, sponsored labels, or feedback.", "Announcing every timer-driven slide change to screen readers.", "Ignoring reduced-motion preferences because the slide transition seems slow.", "Fast-forwarding through several slides when the tab regains visibility.", "Using auto-advance to hide stakeholder prioritization problems instead of choosing a static hierarchy." ], "critiqueQuestions": [ "Can users stop the carousel before any automatic change happens?", "What exactly happens when keyboard focus enters the carousel?", "Does hover, touch exploration, or reading a long caption suspend motion?", "Does reduced motion fully disable auto-advance or only shorten the animation?", "Can a user recover a slide that moved while they were reading or typing?", "Are recommendation reasons, feedback, sponsored labels, warnings, or form fields rotating away?", "Would tabs, a static section, a recommendation list, a grid, or pagination better match the content job?" ], "relatedPatterns": [ "carousel", "tabs", "recommendations", "pagination", "touch-gesture", "banner", "notification-banner", "progressive-disclosure", "feed" ], "comparisons": [ "carousel-auto-advance-without-pause-vs-carousel-vs-tabs-vs-recommendations-vs-pagination" ], "sourceIds": [ "wai-aria-apg-carousel", "wai-carousels-tutorial", "nng-auto-forwarding-carousels", "nng-effective-carousels", "chrome-accessible-carousel", "wcag-focus-order" ] }, { "id": "change-review", "completionStatus": "complete", "name": "Change review", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Review surface for proposed edits, diffs, tracked changes, or suggestions before they become accepted content", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Collaborative products lose quality and trust when proposed edits are hard to inspect, scope is unclear, draft feedback is confused with submitted feedback, stale changes remain actionable, and accept or reject controls apply more broadly than users expect.", "solution": "Provide a change review surface that binds each proposed change to original and proposed content, context, author, progress, comments, decision controls, batch scope, stale state, permissions, and final review submission behavior.", "uiGuidance": [ "Render change review around a concrete proposed change with base content, proposed content, changed scope, author, timestamp, reviewer progress, pending comment state, accept, reject, apply, batch, and submit-review actions.", "Separate change review from final answer review, approval routing, review queues, comments, compare-only views, version history, and activity logs by showing that users are deciding the fate of a specific proposed edit or diff." ], "uxGuidance": [ "Use change review when users need to inspect edits from another person or tool, understand impact, discuss or suggest fixes, and decide whether changes are accepted, rejected, requested, batched, or sent back for revision.", "Protect users from accidental broad decisions by naming scope, showing hidden or unresolved changes, preserving rationale, surfacing stale or outdated diffs, and keeping draft review comments distinct from submitted feedback." ], "uiExamples": { "good": [ "A document review pane highlights one suggested sentence, shows original and proposed text, author, comment, Accept, Reject, Previous, Next, and Preview accepted controls.", "A pull request file review shows a diff hunk, pending line comment, suggestion block, Mark viewed, Review changes, Comment, Approve, and Request changes controls." ], "bad": [ "A page lists Changed item with Approve and Reject buttons but no original text, proposed text, author, scope, or consequence.", "An Accept all button sits beside one visible suggestion without saying hidden suggestions will also be accepted." ] }, "uxExamples": { "good": [ "A reviewer moves through tracked changes one by one, accepts a terminology fix, rejects a risky deletion with a reason, sees the next unresolved change, and submits the review summary.", "A merge request author batches three suggested code changes, previews the commit, sees one suggestion is outdated, applies only the valid batch, and leaves the outdated thread open." ], "bad": [ "A reviewer writes several pending comments but never submits the review because the UI makes draft comments look published.", "A user applies a suggestion after new commits changed the same lines, and the product silently creates an incorrect patch." ] }, "problemContext": [ "Proposed changes may come from collaborators, reviewers, editors, code suggestions, AI edits, merge requests, tracked changes, document suggestions, conflict recovery, dependency updates, or automated refactors.", "Reviewers need enough context to understand why the change exists, what it touches, what remains unresolved, and whether accepting it will commit content, create a patch, resolve a thread, or only submit feedback.", "A change can become outdated when the underlying file, branch, paragraph, version, or suggestion thread changes after the reviewer loaded it.", "Review decisions may be individual, batched, file-scoped, visible-only, all-suggestions, pending-review, required-review, permission-limited, or informational depending on product rules." ], "selectionRules": [ "Choose change review when users are inspecting proposed edits, diffs, suggestions, tracked changes, or review comments before accepting, rejecting, applying, or requesting changes.", "Use review before submit when the user checks their own captured answers before a transaction, not when they judge proposed edits.", "Use approval workflow when the primary job is routed authorization with required approvers and downstream blocking.", "Use review queue when the primary job is processing many queued items and choosing what to handle next.", "Use comments when the surface only supports discussion and does not decide whether a change is accepted or rejected.", "Use compare view when there is no proposed-change lifecycle or decision state.", "Use version history when users browse previous accepted states rather than pending or proposed changes.", "Use activity log when users need historical records after change review decisions happen.", "Show original content, proposed content, changed scope, author, status, stale state, and decision consequence before action.", "Make single-change, visible-only, batch, file-level, and all-change actions visually and textually distinct.", "Keep pending review comments, submitted comments, resolved threads, outdated threads, and requested changes distinct.", "Disable or explain accept, reject, apply, approve, and request-change controls when permissions or freshness checks fail." ], "requiredStates": [ "Default change review state with original and proposed content visible.", "Single suggested edit or tracked change state.", "Diff hunk with line comment state.", "Pending review comment state before submission.", "Submitted review state with comment, approve, or request changes outcome.", "Accepted, rejected, applied, or dismissed change state.", "Batch suggestions or accept-all scope preview state.", "Stale, outdated, or changed-since-review state.", "Marked viewed and unviewed file state.", "Unresolved and resolved conversation state.", "Permission-limited or read-only reviewer state.", "Mobile condensed change navigation state." ], "interactionContract": [ "Selecting a change reveals the base content, proposed content, author, context, and exact scope affected by a decision.", "Accept, reject, apply, dismiss, approve, comment, request changes, and mark viewed actions update the same change or review record and expose the resulting status.", "Batch actions preview included changes, excluded hidden changes, conflicts, stale suggestions, and permission exceptions before commit.", "Pending review comments remain private to the reviewer until the review is submitted, and the UI labels that privacy clearly.", "A stale or outdated change cannot be applied silently; the user must refresh, re-review, or resolve conflict.", "A rejected or dismissed change preserves enough rationale, thread status, or activity record for collaborators to understand the decision.", "Keyboard and screen-reader users can move to next and previous changes, understand insertion and deletion text, and submit or abandon a review without losing comments.", "After each decision, focus moves to the next unresolved change, changed status, or review summary rather than resetting the page." ], "implementationChecklist": [ "Define change record fields: base content, proposed content, location, author, timestamp, source, status, reviewer, pending comments, thread state, freshness token, permission scope, and batch eligibility.", "Separate proposed-change records from comments, activity-log events, version snapshots, approval routes, review queues, and final-submit summaries.", "Build diff or redline rendering that labels insertions, deletions, replacements, file names, line ranges, document sections, and hidden unchanged context.", "Implement next and previous navigation, mark viewed, pending comment drafts, submit review, abandon review, accept, reject, apply, batch, and request-change flows.", "Check freshness and permissions before applying or accepting a change, especially after new commits, document edits, branch updates, or conflict resolution.", "Preview batch scope and exceptions for hidden changes, filtered files, stale suggestions, mixed permissions, unresolved conversations, and broad accept-all decisions.", "Preserve decision rationale, thread resolution, audit event, and focus position after individual and batch decisions.", "Test long diffs, whitespace-only changes, image or binary files, mobile line wrapping, high zoom, keyboard diff navigation, screen reader text alternatives, stale suggestions, and permission-limited reviewers." ], "commonMisuses": [ "Showing accept and reject controls without original and proposed content.", "Using approval workflow for every change review even when no routed approver policy exists.", "Calling a review queue change review when reviewers are only choosing which item to open next.", "Making pending comments look submitted.", "Letting broad accept-all controls appear beside a single visible suggestion without scope copy.", "Applying stale suggestions after the underlying content changed.", "Resolving or deleting discussion threads without preserving decision rationale.", "Treating visual compare as enough when users need decision state, comments, and submission." ], "critiqueQuestions": [ "What exact original content and proposed content is the user deciding on?", "Does each control say whether it affects one change, visible changes, a batch, a file, or all changes?", "Can reviewers distinguish pending comments from submitted feedback?", "How does the UI prevent stale, outdated, or permission-limited changes from being applied?", "What happens to comments, threads, viewed state, approvals, and activity records after accept or reject?", "Would review before submit, approval workflow, review queue, comments, compare view, version history, or activity log better fit this surface?" ], "relatedPatterns": [ "review-before-submit", "approval-workflow", "review-queue", "comments", "compare-view", "version-history", "activity-log", "permission-denied-state", "merge-conflict-resolver", "conflict-resolution" ], "comparisons": [ "change-review-vs-review-before-submit-vs-approval-workflow-vs-review-queue" ], "sourceIds": [ "github-reviewing-proposed-changes", "github-commenting-on-pull-request", "gitlab-merge-request-suggestions", "google-docs-suggest-edits", "microsoft-word-accept-reject-tracked-changes", "azure-repos-review-pull-requests" ] }, { "id": "character-count", "completionStatus": "complete", "name": "Character count", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Bounded text-entry length feedback", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to write within a real text limit, but hidden limits, noisy counters, mismatched server rules, or silent truncation make it hard to know whether the draft will be accepted.", "solution": "Expose the limit before entry, update count feedback at a useful pace, associate it with the field, preserve over-limit drafts, and give exact recovery guidance using the same character or word rule enforced by validation.", "uiGuidance": [ "Place count feedback next to the limited input or textarea, associate it with the field description, and show the maximum or remaining amount in the same unit the service validates.", "Use threshold, warning, and error states that expose the limit without turning every keystroke into noisy feedback; preserve readable hint, count, and error text together." ], "uxGuidance": [ "Use character count only when a real character or word limit affects acceptance and users can adjust their answer before submission.", "When users exceed the limit, preserve their full draft, state exactly how many characters or words must be removed, and provide an edit or trim path instead of silently cutting content." ], "uiExamples": { "good": [ "An appeal summary textarea says users can enter up to 120 characters, shows no urgent count while plenty of space remains, then changes to 18 characters remaining near the threshold.", "A short biography field shows 9 words remaining because the editorial policy is word-based, not character-based." ], "bad": [ "A long unrestricted comment box shows a decorative 5000-character counter that makes users think the answer should be shorter.", "A hidden backend limit rejects a submitted explanation without showing any count, preserved draft, or exact amount over the limit." ] }, "uxExamples": { "good": [ "A user pastes a long summary, sees that it is 23 characters over the limit, trims it in place, and submits without losing the original draft.", "A user switches a grant abstract from character limit to word limit and the counter, hint, validation, and submitted status all change units together." ], "bad": [ "A user composes a paragraph and the field silently truncates the last sentence at the maximum length.", "A screen reader user hears a live region announce the remaining count after every character, interrupting the text they are typing." ] }, "problemContext": [ "A legal, editorial, messaging, database, moderation, or downstream-display rule imposes a maximum number of characters or words.", "Users may paste text from another source and need to know whether the full draft fits before submitting.", "The product can validate the same unit it displays and can preserve the draft even when it exceeds the limit.", "Assistive technology users need the limit and count status without disruptive announcements on every keypress.", "If many users hit the backend limit, the product may need a higher limit or redesigned storage rather than count pressure." ], "selectionRules": [ "Choose character count when the limit is real, useful to users, and enforceable in the same unit displayed by the interface.", "Use word count when policy or review standards are expressed in words, not when the server actually enforces characters.", "Use a textarea without count when users need paragraph entry but limits are absent, extremely high, or unlikely to affect real submissions.", "Use text input without count when the expected value is short enough that length is already apparent from the field type or format.", "Use inline validation for length errors that do not require continuous awareness while typing.", "Escalate backend constraints when users regularly exceed a service-imposed limit; do not make the counter compensate for a bad limit.", "Show a static maximum message when JavaScript is unavailable.", "Do not silently truncate pasted or typed content; preserve the draft and explain the exact reduction needed." ], "requiredStates": [ "Empty state with visible label, hint, and static maximum message.", "Typing state before threshold where the limit remains available but does not create urgency.", "Near-limit state showing remaining characters or words.", "At-limit state explaining that no characters or words remain.", "Over-limit state with error styling and exact amount over the limit.", "Trimmed recovery state after the user edits or accepts a trim action.", "Submitted valid state with accepted count and unit.", "No-JavaScript fallback state with a visible maximum message.", "Word-count mode when the actual constraint is word-based.", "Assistive announcement state that avoids excessive live updates." ], "interactionContract": [ "The field accepts typing and paste normally; the counter observes length rather than blocking editing prematurely.", "The count message uses the same character or word unit as validation and submitted payload checks.", "Before the warning threshold, the interface keeps the maximum visible without repeatedly announcing remaining amounts.", "When the remaining amount crosses the threshold, the count changes to a warning message near the field.", "When the user exceeds the limit, the field keeps the full draft and shows exactly how many characters or words must be removed.", "A trim or edit action is explicit and reversible through normal undo instead of automatic truncation.", "Errors, hints, and count messages are associated with the input or textarea through a shared description." ], "implementationChecklist": [ "Define the enforced unit, maximum, warning threshold, validation rule, fallback message, and server-side normalization before adding the counter.", "Associate label, hint, count message, and error text with the field using stable ids and descriptions.", "Use maxlength only when blocking additional input is acceptable; otherwise allow over-limit drafts and validate with a specific recovery message.", "Implement pluralized messages for remaining, at-limit, and over-limit states in character and word modes.", "Throttle or delay assistive announcements so users are not interrupted on every keystroke.", "Keep count, error, and submitted payload checks aligned with server validation for Unicode, whitespace, pasted text, and line breaks.", "Test no-JavaScript fallback, paste over limit, screen readers, mobile keyboards, zoom, translated strings, and server-returned length errors." ], "commonMisuses": [ "Adding a counter to an unrestricted writing field because it looks informative.", "Using a character counter when the server counts bytes, normalized characters, words, or rich-text markup.", "Hiding the limit until after submit.", "Interrupting screen reader users with a live count after every keypress.", "Silently truncating pasted text at the maximum length.", "Using a low backend limit as a reason to pressure users instead of increasing the limit.", "Showing remaining count in one place and a different maximum in validation.", "Letting the counter replace specific required, too-short, or disallowed-content errors." ], "critiqueQuestions": [ "Is there a real acceptance limit, and is it expressed in characters or words?", "Would most users ever approach the limit, or is the counter just adding pressure?", "Does server validation count the same text that the interface counts?", "What happens when users paste text that is far over the limit?", "Are count messages associated with the field without noisy announcements?", "Should the service increase the backend limit instead of exposing it to users?" ], "relatedPatterns": [ "textarea", "text-input", "inline-validation", "error-summary" ], "comparisons": [ "character-count-vs-textarea-vs-text-input-vs-inline-validation" ], "sourceIds": [ "uswds-character-count-component", "govuk-character-count-component", "govuk-textarea-component", "material-design-text-fields" ] }, { "id": "chart-drilldown", "completionStatus": "complete", "name": "Chart drilldown", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Interactive chart hierarchy from aggregate marks to child-level data", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users see an aggregate chart mark that raises a follow-up question, but switching to a separate table, report page, or filter panel can break analytic context and make the parent-to-child relationship unclear.", "solution": "Provide an in-chart drilldown path where activating a drillable mark replaces or expands the chart with its child series while keeping hierarchy path, selected parent, metric, units, filters, return controls, accessible announcements, and exact-value alternatives synchronized.", "uiGuidance": [ "Render a drillable chart with an analytic title, metric, current hierarchy level, selected parent mark, child-level label, axes, units, breadcrumbs or drill-up control, reset control, selected child mark, tooltip, inherited-filter summary, and data table alternative.", "Distinguish drillable marks from ordinary selectable marks through labels, affordance, focus style, hover or focus hint, and disabled state when a mark has no child series." ], "uxGuidance": [ "Use Chart drilldown when users need to start from an aggregate visual pattern and inspect the planned next level of the same hierarchy without losing the original metric, filter scope, or chart question.", "Preserve orientation on every level change: announce the new level, show the path back to the aggregate, keep selected parent context visible, and disclose any change to unit, aggregation, filter, time range, sample, or freshness." ], "uiExamples": { "good": [ "A revenue-by-region bar chart labels Region level, lets users drill into APAC, replaces the bars with APAC countries, shows a Global > APAC breadcrumb, and keeps USD thousands and the date range visible.", "A product defect chart uses focusable bars with drill hints, disables bars with no child data, and provides a synchronized child table after drilldown." ], "bad": [ "A user clicks a tall bar and the whole chart changes to unlabeled smaller bars with no selected parent, no level label, and no way to return.", "A chart drilldown changes from revenue to margin and from monthly to quarterly data but keeps the same title, making users compare incompatible values." ] }, "uxExamples": { "good": [ "An analyst drills from Region to Country, compares child bars, drills back to all regions, and sees the selected parent and inherited filters preserved throughout.", "A keyboard user tabs to APAC, activates drilldown, hears that the chart changed to Country level for APAC, then uses the breadcrumb to return to Region level." ], "bad": [ "A dashboard treats drilldown like a hidden filter: drilling into Sales hides all other departments with no breadcrumb, so users think the whole company dropped.", "A chart lets users drill five asymmetric levels deep without showing totals, peer context, or a reset path." ] }, "problemContext": [ "The chart shows aggregate values whose children are meaningful, such as region to country, year to quarter, product group to SKU, or category to issue type.", "Users need to investigate why an aggregate is high, low, anomalous, or changing without leaving the visual analysis flow.", "The hierarchy is planned and finite; each child series is a real breakdown of the selected parent rather than an unrelated filter or page navigation.", "Users may need to compare child contributors, return to peer aggregates, export context, or switch to a row-level table when visual drilldown is no longer enough.", "Orientation risk grows as depth increases because the current chart can hide peer context, inherited filters, and the original aggregate question." ], "selectionRules": [ "Choose Chart drilldown when a visible chart mark represents an aggregate with a direct child series that answers the next analytic question.", "Use ordinary Data visualization when users only need to read the current encoded pattern and do not need to traverse a hierarchy.", "Use details panel when the user needs descriptive object information beside the chart rather than replacing the chart with child aggregate marks.", "Use table or data grid when exact records, row reconciliation, export, sorting, or editing is the primary need.", "Use drillthrough to a separate page when the detail view needs multiple visuals, richer entity context, or a different layout while preserving a clear Back path.", "Do not use Chart drilldown for arbitrary filtering, surprise page navigation, unrelated metric changes, or decorative click effects.", "Only expose drilldown on marks with available child data; show disabled or terminal state for leaves.", "Limit levels or provide strong breadcrumbs, reset, and summary context when hierarchies are deep, sparse, or asymmetric." ], "requiredStates": [ "Top-level chart with drillable marks, level label, metric, units, date or filter scope, tooltip, legend, and table alternative.", "Drillable mark focused, hovered, selected, activated, loading child data, child data loaded, child data empty, and terminal leaf states.", "Drilled level with selected parent, child-level title, breadcrumb path, drill-up control, reset-to-root control, inherited filters, and synchronized selected child mark.", "Drill-up, breadcrumb jump, reset, failed child load, stale child data, permission-limited child data, no child data, and export-with-path states.", "Mobile state where hierarchy path, selected parent, drill controls, selected child, and table alternative remain reachable without clipped chart labels.", "Keyboard and assistive-technology state where activation announces the new chart level and focus lands on the level heading, breadcrumb, or first child mark predictably." ], "interactionContract": [ "A drillable mark can only reveal data that is a child of that mark under the current filters, metric, unit, time range, aggregation, and permission scope.", "Activating a mark updates chart marks, title, level label, breadcrumb, tooltip, data table, summary copy, and live announcement from the same child dataset.", "Breadcrumbs and drill-up controls return users to a previous level without losing the original filters, selected path, or available peer context.", "If drilldown changes aggregation, sampling, unit, baseline, or freshness, the changed interpretation is disclosed before the user reads the child chart.", "Terminal marks communicate that no deeper child series exists and do not behave like broken buttons.", "Export, share, and copy actions include the full drill path, selected parent, current level, filters, units, and timestamp." ], "implementationChecklist": [ "Define the drill hierarchy, parent-child keys, maximum depth, terminal leaves, child-count thresholds, permission rules, and fallback table route before rendering drillable marks.", "Generate parent aggregate, child marks, breadcrumbs, tooltips, tables, and summary text from the same filtered hierarchy model.", "Implement keyboard activation, focus restoration, live announcements, drill-up, reset, loading, empty child, failed child, stale child, and permission-limited child states.", "Style drillable marks with explicit affordance and focus indicators, and style terminal marks differently so users do not expect deeper data.", "Test deep paths, asymmetric branches, empty children, long labels, metric changes, filters, exports, mobile layout, high contrast, and screen-reader announcements.", "Provide a table or row-level handoff when users need exact child records after reaching the useful visual drill depth." ], "commonMisuses": [ "Replacing a chart with child data without breadcrumbs, selected parent, or drill-up path.", "Using drilldown as a hidden filter that silently narrows the whole dashboard.", "Changing metric, unit, baseline, or time grain during drilldown without disclosure.", "Making every mark look drillable even when some marks have no child data.", "Opening an unrelated detail page and calling it chart drilldown.", "Hiding exact child values behind pointer-only tooltips." ], "critiqueQuestions": [ "What parent-child hierarchy does each drillable mark represent, and can users see that path before and after activation?", "Does the child chart preserve the same metric, unit, filter scope, and analytic question as the parent chart?", "Can users drill up, jump through breadcrumbs, reset to the root, and export with the full path preserved?", "What happens for terminal leaves, empty child series, stale child data, permission-limited data, and failed child loads?", "Would a details panel, table, data grid, filter panel, or drillthrough page better fit the next step?" ], "relatedPatterns": [ "data-visualization", "details-panel", "table", "data-grid", "breadcrumbs", "filter-panel" ], "comparisons": [ "chart-drilldown-vs-data-visualization-vs-details-panel-vs-table" ], "sourceIds": [ "highcharts-drilldown", "highcharts-breadcrumbs", "highcharts-accessible-dynamic-data", "microsoft-power-bi-drill-down-support", "microsoft-power-bi-drillthrough", "tableau-hierarchies-drill", "highcharts-accessibility-module" ] }, { "id": "chat-interface", "completionStatus": "complete", "name": "Chat interface", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Multi-turn conversation surface with transcript, composer, assistant responses, and conversation history", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI chat can look simple while hiding the durable state that makes a conversation work: turn order, role ownership, carried context, tool use, sources, memory, retention, response status, failed turns, and history controls. Without those boundaries, users lose trust, misread follow-ups, cannot recover from failed or changed answers, and confuse chat with comments, feeds, or a single prompt box.", "solution": "Design chat as a stateful conversation surface that makes each turn, transcript order, response lifecycle, carried context, history status, and recovery action visible and inspectable.", "uiGuidance": [ "Render chat as an ordered transcript with visible user and assistant roles, turn boundaries, timestamps or relative position, current draft composer, submitted prompt, response status, source or tool indicators, and conversation-level controls.", "Keep conversation history, new-chat, active conversation title, model or mode, grounding scope, memory or retention state, and transcript controls visually separate from the prompt composer so users can tell what affects the whole chat versus the next message." ], "uxGuidance": [ "Use a chat interface when users need a multi-turn assistant conversation where later prompts can depend on earlier turns, responses can be inspected or continued, and conversation history can be saved, resumed, deleted, or limited by policy.", "Protect the transcript as task evidence: preserve the exact prompt and response per turn, avoid losing scroll or focus during streaming, show what context carries into follow-ups, and support retry, stop, regenerate, copy, cite, export, and history recovery in ways that do not rewrite prior turns silently." ], "uiExamples": { "good": [ "A research assistant chat shows user and assistant bubbles, turn numbers, source chips, streaming status, Stop, Copy answer, Regenerate, New chat, and a conversations list with the active chat title.", "A Copilot-style work chat separates Work mode, Web mode, file references, tool availability, dictation, and chat history settings from the message composer." ], "bad": [ "A chat panel shows one undifferentiated wall of text with no user or assistant roles, no submitted prompt, and no visible conversation identity.", "A conversation auto-scrolls to a new answer while the user is reading an older cited turn, then hides the old prompt after regenerate." ] }, "uxExamples": { "good": [ "A user asks for a policy summary, follows up with Compare that to the renewal clause, sees that the second answer used the first answer and selected file, then exports the two-turn transcript.", "A failed assistant answer remains attached to its user prompt with Retry and Edit follow-up controls; the draft follow-up, scroll position, and active citation are preserved." ], "bad": [ "A follow-up uses prior conversation context after chat history has been switched off, without explaining that current-session context still exists.", "Regenerate overwrites the old answer and citations, so the user cannot tell which version a copied recommendation came from." ] }, "problemContext": [ "A chat can include user messages, assistant messages, system or product notices, tool calls, file references, source citations, streaming deltas, blocked content, and saved history.", "Follow-up prompts may rely on current session context, persisted conversation state, selected files, page context, workspace data, tools, memory, or no carried context.", "Users may start a new chat, resume an old chat, rename or pin a conversation, delete history, export a transcript, copy an answer, stop generation, regenerate, retry, edit a previous turn, or branch a conversation.", "Long conversations introduce scroll anchoring, virtualized message lists, mobile keyboard overlap, transcript search, older-history loading, citation focus, and source availability issues.", "Enterprise and regulated products may have retention, audit, privacy, external-model, sensitive-data, and human-approval requirements that change how chat history is shown." ], "selectionRules": [ "Choose chat interface when the user task depends on turn-taking, follow-up prompts, assistant responses, and conversation history rather than a single request field.", "Use prompt box when only the editable AI request composer is being designed and transcript state belongs elsewhere.", "Use threaded discussion when the conversation is among people and needs nested replies, human authorship, moderation, and unread human activity.", "Use comments when messages are object-level annotations, decisions, or review notes tied to a document section, task, row, or artifact.", "Use feed when users browse chronological updates or content items and do not need a composer anchored to a turn-taking transcript.", "Show a conversation identity when chats can be saved, revisited, renamed, pinned, deleted, exported, or used across sessions.", "Make follow-up context explicit when the next prompt will use previous turns, selected files, work data, web data, tools, memory, or a prior response ID.", "Use a sequential live region or equivalent status strategy for new transcript items so assistive technologies can announce appended messages without moving focus unnecessarily.", "Keep current draft, submitted prompt, assistant response, tool progress, citation state, and copied answer state separate.", "Do not claim chat history is off while still carrying prior turns into model context without a clear current-session explanation." ], "requiredStates": [ "Empty new chat with conversation title, mode, history or retention status, and a labelled composer.", "Typing draft, submitted user message, assistant thinking, streaming response, complete response, stopped generation, failed response, and retry states.", "Follow-up turn that shows whether prior messages, files, tools, memory, selected sources, or web/work mode are included.", "Regenerate, edit follow-up, copy answer, cite source, export transcript, delete chat, and new chat states.", "Long transcript with older-history loading, scroll-to-latest, reading older turn, active citation, and preserved draft behavior.", "History disabled, history unavailable, expired conversation, deleted conversation, signed-out session, offline, rate-limited, sensitive-content, and policy-blocked states.", "Mobile keyboard state with composer anchoring, accessible send and stop controls, transcript reading space, and preserved scroll." ], "interactionContract": [ "Every user-visible answer is tied to the exact user message and visible context that produced it.", "New turns append in reading order and do not interrupt a user who is reading, selecting, copying, or inspecting an older turn.", "The current composer controls the next message only; conversation-level controls such as New chat, Delete history, mode, memory, and export are labelled separately.", "Stop generation leaves a partial-response state rather than pretending the answer completed.", "Retry resends the same turn or clearly shows when the prompt, model, tools, or sources changed.", "Regenerate preserves prior answer identity or makes version replacement explicit.", "History settings explain whether they affect saved history, personalization, current-session context, or future conversations.", "Focus remains predictable after submit, stream complete, stop, retry, copy, delete, history open, or older-history load." ], "implementationChecklist": [ "Model conversation data as ordered turns with stable IDs, role, prompt text, response text, status, sources, tool events, timestamps, copy state, version state, and retention metadata.", "Separate draft composer state from submitted messages, response streaming state, conversation list state, and saved-history state.", "Implement controls for send, stop, retry, regenerate, edit follow-up, copy, cite, export, new chat, rename, pin, delete, and history settings according to risk.", "Validate scroll anchoring, focus return, mobile keyboard behavior, virtualized older messages, long answers, code blocks, citations, tool progress, failed streams, and offline recovery.", "Expose transcript updates, streaming status, errors, copied state, source availability, and history changes to assistive technologies without forced focus jumps.", "Log or audit high-risk assistant actions without treating private draft text or deleted history as retained evidence unless the product explicitly says so." ], "commonMisuses": [ "Treating chat as a large textarea plus latest answer with no durable turn identity.", "Auto-scrolling during streaming while the user is reading an older message.", "Letting regenerate overwrite a response and citations with no version history.", "Showing a history-off toggle while the next turn still uses prior messages without explanation.", "Mixing human comments, task activity, and assistant chat in one transcript without role and purpose boundaries.", "Hiding tool calls, file references, and source scope until after a response fails or produces a risky answer.", "Using chat for a deterministic workflow that needs structured fields, review, or approval." ], "critiqueQuestions": [ "Can users identify the active conversation, each turn's role, the exact prompt for each answer, and what context carries into the next turn?", "What happens to focus, scroll, draft text, copied text, and source inspection when a response streams, fails, stops, or regenerates?", "Are history, retention, memory, grounding, and tool-use settings visible at the level they affect?", "Does this need chat, or would a prompt box, form, command, comments thread, or activity feed better fit the task?", "Can users recover or audit the transcript after weak output, source loss, policy block, deletion, or session expiry?" ], "relatedPatterns": [ "prompt-box", "prompt-suggestions", "threaded-discussion", "comments", "feed", "activity-feed" ], "comparisons": [ "chat-interface-vs-prompt-box-vs-threaded-discussion-vs-comments-vs-feed" ], "sourceIds": [ "openai-conversation-state", "microsoft-365-copilot-chat-start", "microsoft-365-copilot-chat-history", "w3c-aria-log-role-chat", "wcag-status-messages" ] }, { "id": "checkbox-group", "completionStatus": "complete", "name": "Checkbox group", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Multiple-choice form control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to choose zero, one, or several independent options from a short set that should remain visible while they decide.", "solution": "Show native checkboxes in a labeled group with a select-all-that-apply hint, independent checked states, clickable labels, and group validation when a minimum or limit applies.", "uiGuidance": [ "Render visible native checkboxes with labels, checked states, group legend, select-all-that-apply hint, and group validation state.", "Keep all short-list independent options visible for comparison and review." ], "uxGuidance": [ "Let users choose independent options and review the selected set before submitting.", "Communicate minimum, maximum, required, or select-all-that-apply rules before errors occur." ], "uiExamples": { "good": [ "Visible checkboxes with large hit areas, persistent labels, group legend, and aligned helper text.", "Checked, unchecked, focus, disabled, and error states are visually distinct without relying only on color." ], "bad": [ "Tiny custom boxes that are hard to target.", "Checkboxes scattered without a group label or consistent spacing." ] }, "uxExamples": { "good": [ "Clicking the label toggles the checkbox.", "Users can select multiple independent choices and review the selected set before submit." ], "bad": [ "Using checkboxes for mutually exclusive choices.", "Losing checked values after validation or page refresh." ] }, "problemContext": [ "Choices are not mutually exclusive.", "Users need to review all available options and the selected set before submitting." ], "selectionRules": [ "Choose checkboxes for short independent multi-choice sets where every option can remain visible.", "State any minimum, maximum, or select-all-that-apply rule before users submit.", "Use radio groups instead when exactly one option is allowed.", "Use multi-select when the option set is too long, searchable, or dynamic to show as a visible checklist." ], "requiredStates": [ "Unchecked option state.", "One or more checked option states.", "Focused checkbox state.", "Group validation state when required, limited, or left empty." ], "interactionContract": [ "Each option toggles independently without unchecking other selected options.", "The selected set remains visible in the list and in any summary text.", "Validation explains required, minimum, or maximum selection rules without clearing checked values." ], "implementationChecklist": [ "Use native checkbox inputs where possible.", "Group related choices under a clear fieldset legend or equivalent accessible name.", "Add a short hint such as select all that apply when the multi-choice rule may be missed.", "Preserve selections during validation errors.", "Avoid hidden defaults, ambiguous negative labels, and custom toggles without checkbox semantics." ], "commonMisuses": [ "Using checkboxes for mutually exclusive choices.", "Hiding selected values after choice.", "Not explaining max-selection limits until submit.", "Scattering related checkboxes without a shared question or legend." ], "critiqueQuestions": [ "Are these choices truly independent, and should users see them all together?", "Can the user tell how many options may be selected before they submit?" ], "relatedPatterns": [ "multi-select", "radio-group" ], "comparisons": [ "checkbox-group-vs-multi-select" ], "sourceIds": [ "govuk-checkboxes-component", "uswds-checkbox-component", "wai-aria-apg-checkbox" ] }, { "id": "checkout", "completionStatus": "complete", "name": "Checkout", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Purchase commitment and order finalization flow", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Purchase flows fail when users cannot see the true total, are forced through unnecessary account creation, lose cart context during payment or shipping errors, or cannot tell when the order is actually committed.", "solution": "Use a checkout flow that keeps cart summary, customer details, delivery, discounts, tax, payment, final review, processing, and confirmation synchronized while preserving state and giving specific recovery paths for purchase-blocking problems.", "uiGuidance": [ "Render checkout as a purchase commitment flow with order summary, customer contact, shipping or pickup choice, payment handoff, discount and tax state, total due, review, place-order action, payment processing, and confirmation handoff.", "Keep checkout separate from payment-card entry, review before submit, step navigation, address entry, and confirmation page: checkout coordinates the purchase state across those pieces but does not replace their specialized controls." ], "uxGuidance": [ "Use checkout when a user is ready to turn selected items, services, tickets, or subscriptions into a committed order and needs confidence about total cost, delivery, payment, and recovery before placing the order.", "Reduce abandonment by preserving cart state, supporting guest checkout where account creation is not required, keeping totals synchronized, avoiding surprise fees, and recovering from payment, inventory, shipping, and session errors without losing the order." ], "uiExamples": { "good": [ "A checkout shows cart items, shipping address, delivery options, taxes, discount, total, payment state, and a Place order button that disables while authorization is pending.", "A guest checkout keeps email receipt, shipping, payment, and review steps visible and lets the user create an account after the order is placed." ], "bad": [ "A checkout hides shipping costs until after card entry and changes the total at the last moment.", "A payment decline clears the cart and sends the user back to the store with no order recovery." ] }, "uxExamples": { "good": [ "A user changes shipping speed, sees delivery date and total update in the sticky order summary, reviews the final charge, places the order once, and lands on a confirmation page with an order number.", "A user receives a payment decline, sees the card problem, keeps their cart and shipping selection, changes payment method, and retries with the same order reference." ], "bad": [ "A user cannot find guest checkout, creates an unwanted account, then abandons when email confirmation blocks payment.", "A user taps Place order twice during a slow authorization and receives two duplicate orders." ] }, "problemContext": [ "The user has selected products, services, tickets, subscriptions, donations, or billable options and is ready to commit to payment or order placement.", "Checkout may need contact details, shipping or pickup address, delivery option, billing details, payment method, discounts, tax, fees, terms acceptance, inventory reservation, fraud checks, and receipts.", "Users compare total cost, delivery timing, trust signals, return policy, account requirements, and payment options while deciding whether to continue.", "Totals and availability can change when quantity, address, shipping speed, tax location, discount, inventory, or payment method changes.", "Checkout errors can have external effects such as payment authorization, inventory holds, duplicate orders, abandoned carts, or legal acceptance." ], "selectionRules": [ "Choose checkout when the primary task is completing a purchase or order from selected items or priced services.", "Use payment card entry for secure card capture inside checkout; checkout owns when payment is requested, reviewed, authorized, retried, or confirmed.", "Use review before submit for the final editable summary, but add checkout-specific total, shipping, payment, inventory, discount, and terms details before the place-order action.", "Use step navigation only to communicate checkout progress; it must reflect actual validity of contact, delivery, payment, and review steps.", "Use address entry for shipping or billing address capture; checkout owns how address changes update delivery options, tax, fees, and order availability.", "Use confirmation page after the order is committed, not as a substitute for checkout review or payment processing state.", "Offer guest checkout unless account creation is required by the business or regulatory task, and defer account creation until after order placement when possible.", "Keep the order summary, item quantities, shipping cost, discounts, taxes, fees, and total due visible or easily reachable throughout checkout.", "Recalculate and explain total, delivery, tax, or inventory changes before the user places the order.", "Preserve cart, address, shipping, discount, and payment method context across validation errors, payment declines, authentication, redirects, refresh, and browser Back.", "Disable or guard duplicate place-order actions while payment authorization, inventory reservation, or order creation is in flight.", "Route success to a confirmation page with order number, receipt, delivery or pickup expectations, and next steps." ], "requiredStates": [ "Cart summary state with items, quantities, price, shipping, tax, discount, and total due.", "Guest or sign-in choice state that does not block purchase without a clear reason.", "Contact and receipt details state.", "Shipping or pickup address state with delivery eligibility and address-change effects.", "Delivery option state with cost, arrival estimate, unavailable option, and changed total.", "Discount or promotion state with applied, invalid, removed, and expired cases.", "Payment method state with secure card entry, wallet, saved payment, redirect, or alternate route.", "Final review state with charge amount, items, delivery, payment summary, terms, and explicit place-order action.", "Processing state that disables duplicate commit while keeping order reference and recovery context visible.", "Payment declined, authentication required, or authorization failed state with preserved checkout details.", "Inventory, price, or shipping changed state that requires acknowledgement before order placement.", "Abandoned or expired checkout recovery state.", "Order placed handoff state that routes to confirmation with receipt and next steps." ], "interactionContract": [ "Changing quantity, address, delivery method, discount, or payment route updates the order summary and total before commit.", "Users can move between checkout steps without losing valid entered data or hiding newly invalid dependent choices.", "The final action names the purchase consequence, such as Place order or Pay now, and is protected against duplicate activation.", "Payment errors preserve non-sensitive checkout context and return focus to the failing payment or recovery area.", "Shipping, tax, inventory, and price changes are shown near the affected order summary and must be acknowledged when they affect the final charge.", "Guest checkout, sign-in, wallet, payment redirect, and browser Back return to the same checkout context unless security policy requires a fresh start.", "Successful order creation removes editable checkout controls and hands off to a confirmation page." ], "implementationChecklist": [ "Define checkout ownership for cart state, customer identity, guest rules, addresses, delivery, tax, discounts, payment authorization, inventory holds, order creation, receipts, and post-order account creation.", "Design cart summary, guest choice, contact, shipping, delivery, discount, payment, review, processing, decline, changed-total, expired-session, and confirmation handoff states.", "Bind checkout totals to canonical pricing, tax, shipping, discount, and inventory services rather than duplicating calculations only in the browser.", "Use secure payment components or redirects for payment credentials and keep checkout state resumable after authentication or payment-provider returns.", "Use idempotency, duplicate-submit guards, and clear processing states for place-order, payment authorization, and order creation requests.", "Preserve safe checkout data through validation, payment decline, refresh, browser Back, and session timeout while redacting payment secrets.", "Explain final total changes, unavailable items, expired discounts, address-dependent tax or shipping changes, and delivery promise changes before commit.", "Test guest checkout, forced sign-in exceptions, mobile viewport, long order summaries, address changes, delivery changes, discount failure, card decline, wallet cancel, redirect return, duplicate tap, inventory change, abandoned cart return, screen readers, and high zoom." ], "commonMisuses": [ "Forcing account creation before purchase when guest checkout would work.", "Hiding shipping, tax, fees, or total until after payment details are entered.", "Letting totals change after payment capture without a visible review or acknowledgement.", "Clearing the cart, address, discount, or delivery choice after a payment decline.", "Treating all checkout failures as one vague checkout failed message.", "Leaving Place order enabled while authorization or order creation is already running.", "Using step labels that imply payment or shipping is complete before required dependencies are valid.", "Showing a confirmation page before payment, inventory, or order creation is actually committed." ], "critiqueQuestions": [ "What exactly is committed when the user presses the final checkout action?", "Can the user see the current total, shipping cost, taxes, discounts, delivery promise, and payment state before commit?", "Which checkout changes can alter the final charge, delivery eligibility, or inventory state?", "Does guest checkout remain available unless there is a specific reason to require an account?", "How are payment decline, authentication, redirect cancel, duplicate submit, inventory change, and expired session recovered without losing the order?", "Where does checkout stop and the post-order confirmation page begin?" ], "relatedPatterns": [ "payment-card-entry", "review-before-submit", "step-navigation", "address-entry", "confirmation-page", "loading-spinner", "retry", "error-summary", "inline-validation" ], "comparisons": [ "checkout-vs-payment-card-entry-vs-review-before-submit-vs-step-navigation" ], "sourceIds": [ "baymard-checkout-usability", "nng-mobile-checkout-ux", "stripe-checkout-overview", "stripe-idempotent-requests", "google-address-validation-checkout" ] }, { "id": "chip-selection", "completionStatus": "complete", "name": "Chip selection", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Compact selectable chip group for short choice answers", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to make a quick choice from short, visible options, but using chips without a clear selection contract can blur form answers, filters, badges, links, actions, and removable values.", "solution": "Provide a labelled selectable chip group with explicit single or multiple selection rules, stable chip order, visible selected state, keyboard operation, validation, and clear limits on option count and label length.", "uiGuidance": [ "Render a labelled chip group with short chip labels, visible selected and unselected states, focus states, disabled states, optional selected checkmarks, and inline help or error text.", "Keep the chip set compact and scannable: preserve chip order, avoid multi-function chips, use wrapping or horizontal scroll deliberately, and switch to checkbox group, radio group, list picker, or multi-select when labels or option counts grow." ], "uxGuidance": [ "Use chip selection when users answer a lightweight choice question from a small visible set and the labels are short enough to scan as chips.", "Make selection rules explicit before interaction, including whether one or many chips can be selected, whether the question is required, and the maximum number of chips allowed." ], "uiExamples": { "good": [ "An onboarding form asks Choose up to 3 interests and shows compact chips for Design, Data, Research, AI, Accessibility, and Mobile with selected checkmarks.", "A food-preference question uses one row of short selectable chips with a persistent question label, helper text, selected state, and a required error message.", "A mobile setup screen uses horizontally scrollable chips for seven short delivery windows and switches to a picker when more choices are added." ], "bad": [ "A chip row contains selectable answers, removable tags, links, and action chips with identical styling.", "Long chip labels wrap to two or three lines and create uneven hit targets.", "A selected chip can only be identified by a faint color change." ] }, "uxExamples": { "good": [ "A user selects Design, Data, and Accessibility, sees 3 of 3 selected, then receives immediate feedback when trying to add a fourth chip.", "A user clears all chips and Save shows an inline required message while preserving the same chip order for repair.", "A user toggles an already selected chip off and the remaining selected chips stay in place." ], "bad": [ "A user taps a chip expecting to answer a question, but the page filters content instead.", "A user selects too many chips and only learns the maximum at final submit.", "A user removes a chip from the available list because the selected chip uses a close icon instead of toggling selected state." ] }, "problemContext": [ "The answer set is small and each option can be represented by a short word or phrase.", "The product wants a compact, touch-friendly alternative to conventional checkboxes or radio buttons.", "The choice is part of a form, onboarding flow, preference setup, chat decision, or lightweight configuration task.", "The UI must distinguish selected answer chips from filter chips, badges, removable tags, and action chips." ], "selectionRules": [ "Choose chip selection when the chip set itself is the user's answer to a short choice question.", "Use single-selection chips only when exactly one chip in the group can be selected at a time, and state that rule before interaction.", "Use multiple-selection chips when several short options can be selected and the maximum count is small enough to remain readable.", "Use filter chips when selection changes result inclusion rather than storing a form or preference answer.", "Use checkbox group when options need longer labels, descriptions, conventional form affordance, or many visible independent choices.", "Use segmented control when exactly one compact option changes a nearby view, mode, sort, or presentation immediately.", "Use multi-select when the option set is long, searchable, async, grouped, or better managed in a popup with selected-value chips.", "Use badges or read-only tags when the label is informational and cannot be selected.", "Avoid chip selection for more than a small set of short labels; switch to list picker, checkbox group, radio group, or multi-select when wrapping exceeds a few rows." ], "requiredStates": [ "Empty chip group with visible question label and helper text.", "Unselected chip state with visible focus and hit target.", "Selected chip state with checkmark, pressed state, or equivalent selected indicator.", "Single-selection chip group state where selecting one chip deselects the previous chip.", "Multiple-selection chip group state with selected count and maximum count feedback.", "Blocked maximum-selection state when another chip cannot be added.", "Required validation state with no selected chips.", "Disabled unavailable chip state with explanation when needed.", "Overflow, wrapping, or horizontal-scroll state for compact chip rows." ], "interactionContract": [ "Selecting a chip changes only that chip group's answer and does not navigate, run an action, remove the option, or filter unrelated content.", "For single-selection chip groups, selecting one chip clears the previous selection.", "For multiple-selection chip groups, selecting a chip toggles that chip while preserving other selected chips and chip order.", "The group enforces minimum, maximum, required, and disabled rules immediately with inline feedback.", "Selected state is visible and programmatic, not conveyed by color alone.", "Chip labels stay concise and stable; long labels are not allowed to wrap in a way that changes chip shape unpredictably." ], "implementationChecklist": [ "Define whether the chip group is single-select or multi-select before implementation.", "Label the chip group with a visible question and helper text that explains required or maximum selection rules.", "Expose each selectable chip as a button, checkbox-like control, radio-like control, or equivalent with selected or pressed state.", "Use checkmarks, borders, text, icons, or pressed state in addition to color for selected chips.", "Keep chip order stable after selection and avoid moving selected chips to the front.", "Block extra selections immediately when a maximum count is reached and announce the reason.", "Do not place links, delete icons, menus, actions, and selection toggles inside the same chip unless the component pattern explicitly supports that role.", "Test keyboard toggling, focus order, screen reader state, touch target spacing, high zoom, forced colors, wrapping, long labels, localization, required validation, and max-count validation." ], "commonMisuses": [ "Using chip selection to filter result sets without explaining that the chips are filters.", "Mixing selectable chips, removable tags, read-only badges, links, and action chips in one visual group.", "Using chips for long labels that should be checkbox or radio options.", "Letting selected chips reorder or disappear after selection.", "Relying only on color to show selected state.", "Using a close icon on a selectable chip and making users wonder whether it toggles selection or removes the option.", "Allowing more chips to be selected than the submitted value accepts." ], "critiqueQuestions": [ "Is the chip group collecting an answer, filtering content, triggering actions, or merely labelling information?", "Are labels short enough that chips remain compact after localization?", "Can users tell whether the group is single-select or multi-select before they tap?", "What happens when the user selects none, too many, a disabled chip, or a long localized label?", "Does the selected state remain clear without color and in screen reader output?", "Should this become checkbox group, radio group, segmented control, or multi-select because the option set is growing?" ], "relatedPatterns": [ "filter-chips", "checkbox-group", "segmented-control", "multi-select", "radio-group", "select", "inline-validation" ], "comparisons": [ "chip-selection-vs-filter-chips-vs-checkbox-group-vs-segmented-control" ], "sourceIds": [ "sap-fiori-android-chips", "carbon-tag-component", "material-design-chips", "wise-chip-component" ] }, { "id": "citation-display", "completionStatus": "complete", "name": "Citation display", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Inline claim-to-source evidence display for generated or summarized content", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Generated answers and summaries often cite sources, but weak displays make citation numbers look trustworthy even when the source is unresolved, unavailable, stale, or not actually tied to the claim being read.", "solution": "Attach visible citation markers to specific claims, expose a selected source preview with source metadata and excerpt, show unresolved evidence states honestly, and preserve the mapping through answer changes and source-opening flows.", "uiGuidance": [ "Render citation markers beside the claims they support, and connect each marker to a selected source preview with title, source type, excerpt, date or version, permission state, and open source action.", "Differentiate verified, pending, stale, missing, permission-limited, and mismatch citations with text labels and stable source-panel states rather than relying on color or decorative numbering." ], "uxGuidance": [ "Use citation display when users must verify where a generated claim, summary, or recommendation came from without leaving the answer context.", "Keep the claim-to-source mapping durable through streaming, regeneration, copying, mobile layout changes, and permission checks so users can tell what evidence applies to which claim." ], "uiExamples": { "good": [ "A policy assistant places numbered citation chips after each sourced claim; selecting a chip opens a source preview with the document title, section, quoted excerpt, updated date, and Open source action.", "A generated research summary marks two citations on one claim, shows one source as pending until retrieval finishes, and labels an internal source as permission-limited when the user cannot open it." ], "bad": [ "An answer ends with five links under Sources but no marker shows which link supports which claim.", "Superscript numbers appear beside claims but do not open anything, and stale citations remain after the answer is regenerated." ] }, "uxExamples": { "good": [ "A user checks a claim, opens its source preview, compares the quoted excerpt with the answer text, and copies the citation with the source title included.", "During streaming, the answer labels citations as Pending; after final retrieval, verified markers become clickable and one unresolved marker becomes Missing source with a retry path." ], "bad": [ "A user trusts a generated compliance claim because it has a number beside it, but the number points to an unrelated source.", "A mobile user taps a citation and loses their reading position because the full source page replaces the answer with no back context." ] }, "problemContext": [ "The system may generate citations from web search, file search, enterprise retrieval, user-provided documents, code execution outputs, or manually curated references.", "Citations may arrive after answer text, be removed during safety or grounding checks, be blocked by permissions, point to changed documents, or support only part of a sentence.", "Users need to evaluate whether the source supports the claim without losing their place in the answer, especially on mobile or in long chat transcripts.", "Citation display often sits inside a chat interface, streaming response, research workspace, document editor, review queue, or support-answer panel." ], "selectionRules": [ "Choose citation display when the main user need is verifying a generated or summarized claim against the source that supports it.", "Use chat interface when the primary concern is the conversation container, prompt composer, message history, and turn-taking rather than source evidence.", "Use streaming response when the primary concern is partial generated output and response lifecycle; include citation states inside streaming only when evidence arrives asynchronously.", "Use related links when links are optional onward reading or adjacent resources instead of claim-level evidence.", "Use tooltip only for short supplemental descriptions; citation details need persistent, inspectable source records.", "Show a source preview before sending users away from the answer when verifying the evidence is part of the task.", "Use a broader grounding or evidence view when users need coverage across all sources, retrieval steps, or unsupported claims rather than inspecting one selected citation.", "Do not show a citation marker until the system can either resolve the source or label the citation as pending, missing, stale, permission-limited, or mismatched.", "Do not use citation display as a confidence score; a source link can still be incomplete, irrelevant, outdated, or misinterpreted." ], "requiredStates": [ "Default answer with cited claims and inline citation markers.", "Selected citation state with source preview, source title, source type, excerpt, date or version, and open source action.", "Multiple citations supporting one claim with clear source ordering and source preview switching.", "Pending citation state during streaming or retrieval before the source is verified.", "Stale citation state after answer revision, document update, or regenerated text changes the claim-to-source mapping.", "Missing source, unavailable source, and permission-limited source states with recovery or explanation.", "Source mismatch state when the cited excerpt does not support the selected claim.", "Copied citation state that confirms what was copied and keeps source context attached.", "Mobile stacked-panel state that preserves reading position while the source preview opens." ], "interactionContract": [ "Each citation marker opens or focuses the source record that supports the adjacent claim.", "The selected source preview remains associated with the selected claim and marker until the user changes selection or the answer changes.", "Open source, copy citation, retry source, and report mismatch actions operate on the selected citation, not the whole answer.", "Regeneration, editing, or streaming updates invalidate or re-check citation markers whose claim text changed.", "Permission-limited citations explain that a source exists but cannot be opened by the current user.", "Keyboard and touch users can select citations, inspect the source preview, open the source, and return to the claim without losing context.", "Citation status changes are announced as meaningful status messages without moving focus unexpectedly." ], "implementationChecklist": [ "Store citation markers as structured ranges or anchors tied to answer text, source IDs, excerpt IDs, retrieval result IDs, and verification status.", "Render source previews with title, source type, owner or publisher when useful, date or version, excerpt, page or section, permission state, and source-opening action.", "Track pending, verified, stale, missing, permission-limited, mismatch, copied, and reported states separately from the answer text state.", "Revalidate or clear citations after regeneration, editing, translation, summarization, document update, source deletion, or permission changes.", "Preserve selected citation, scroll position, focus, and mobile source-panel state when users open and close previews.", "Make copied output explicit: copy claim, copy citation, copy source title, and copy quoted excerpt should not be ambiguous.", "Test citations in long answers, tables, code blocks, Markdown links, streamed output, virtualized transcripts, mobile viewports, high zoom, keyboard navigation, and screen readers." ], "commonMisuses": [ "Displaying a link dump below the answer instead of mapping sources to specific claims.", "Using decorative numbers that do not open a source preview.", "Keeping citations attached after the cited claim changes.", "Hiding citation details in a tooltip that disappears on blur, touch, or scroll.", "Treating a citation as proof of correctness without checking whether the source supports the claim.", "Showing permission-blocked or missing sources as if they were verified.", "Over-citing every sentence so users cannot identify the evidence that matters." ], "critiqueQuestions": [ "Can users tell exactly which claim each citation supports?", "Does selecting a citation show enough source detail to verify the claim before opening a new page?", "What happens when the cited source is pending, stale, missing, permission-limited, or mismatched?", "Are citation markers updated or invalidated when the answer changes?", "Can keyboard, touch, and screen reader users inspect citations and return to the claim without losing position?", "Would related links, a chat interface, streaming status, tooltip, or a broader evidence view solve the actual user need better?" ], "relatedPatterns": [ "chat-interface", "streaming-response", "related-links", "tooltip", "preview-panel", "details-panel" ], "comparisons": [ "citation-display-vs-chat-interface-vs-streaming-response-vs-related-links-vs-tooltip" ], "sourceIds": [ "openai-citation-formatting", "openai-file-search-citations", "openai-web-search-citations", "microsoft-365-copilot-linked-citations", "microsoft-365-copilot-web-references", "mdn-html-cite-element", "whatwg-html-cite-element", "wcag-status-messages" ] }, { "id": "collection", "completionStatus": "complete", "name": "Collection", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Named, purposeful set of items with collection-level metadata and membership behavior", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to keep, revisit, share, sequence, or manage a purposeful set of items, but a simple list, category page, recommendation rail, or related-links block does not explain the set's purpose, membership, ownership, order, or action scope.", "solution": "Represent the set as a collection with a clear title, description, owner or source, item count, visibility, update state, membership rule, sections or ordering, item identity, collection actions, item actions, and explicit behavior for empty, filtered, unavailable, copied, shared, and deleted states.", "uiGuidance": [ "Render a collection header with the collection title, concise description, item count, owner or source, visibility, last updated state, and primary collection actions before the item surface.", "Show items with stable identity, type, status, section, order, and item-scoped actions, while keeping collection actions such as share, copy, reorder, subscribe, or delete visually separate." ], "uxGuidance": [ "Use collection when the set itself is meaningful and users need to save, curate, share, revisit, sequence, or manage item membership.", "Preserve trust by explaining membership rules, hidden or unavailable items, manual versus sorted order, section purpose, and the difference between filtering the view and changing the collection." ], "uiExamples": { "good": [ "A launch-assets collection shows title, description, 4 items, owner, shared-with-team state, sections for Read first and Assets, and item cards with type, status, and remove actions.", "A government document collection groups related forms and guidance by heading, includes short descriptions under each link, and offers updates about changes to collection items." ], "bad": [ "A page shows cards named Resources, More, Useful, and Links with no collection title, purpose, count, or ownership.", "A collection has Share, Delete, and Remove buttons beside every item without saying whether the action affects the item, the view, or the whole collection." ] }, "uxExamples": { "good": [ "A user adds a training module to a cloud-migration collection, reorders it into the first section, shares the collection link, and sees a confirmation that the item remains in the collection.", "A viewer opens a shared collection and sees that two private items are hidden because they lack permission, while the visible count and owner remain clear." ], "bad": [ "A user filters a collection to videos, removes one visible item, and later discovers the product only cleared the filter instead of removing the item from the collection.", "A copied collection silently keeps the original owner's stale description and shared permissions, so recipients cannot tell which copy they are editing." ] }, "problemContext": [ "Items may be documents, training modules, products, files, assets, articles, records, examples, forms, media, or tasks.", "The set can be manually curated, saved by a user, generated by an editor, published for a topic, shared with a team, copied as a starting point, or maintained as a durable content page.", "Users may need to add, remove, reorder, group, filter, sort, open, copy, share, export, subscribe to, or delete the collection.", "The same item may appear in multiple collections, and permission, localization, availability, or product state can change what each viewer sees." ], "selectionRules": [ "Choose collection when the item set has its own name, purpose, owner, audience, membership, ordering, grouping, or sharing behavior.", "Use collection when users need to save explicit items rather than save criteria.", "Use collection when users need to curate a recommended sequence, reading list, asset kit, form pack, playlist, saved product set, or document bundle.", "Use list view when the primary task is scanning and acting on row summaries, not managing the set as a named object.", "Use browse by category when the user is navigating a taxonomy rather than inspecting a specific curated set.", "Use related links for a short contextual link group tied to one page, especially when there is no independent collection object.", "Use recommendations when the system ranks suggested items from signals or editorial rules rather than preserving explicit collection membership.", "Use saved search or saved filter when the set is regenerated from criteria and membership changes automatically as matching items change.", "Avoid collection when the set has no stable membership rule, no reason to revisit, and no collection-level action or metadata.", "Avoid collection when a table, data grid, map, feed, or timeline better expresses the main task and collection behavior would add false ownership." ], "requiredStates": [ "Default collection state with title, description, owner or source, item count, visibility, updated time, and primary action.", "Item state with stable label, type, status, section, order, preview or summary, and item-scoped actions.", "Manual order, sorted order, sectioned order, filtered view, and no-results states.", "Add item, remove item, reorder item, move between sections, copy collection, share collection, and delete collection states when supported.", "Shared, private, team-visible, read-only, editable, copied, subscribed, and permission-limited states.", "Empty collection, newly created collection, loading, partial-load, failed-load, stale-link, hidden-item, unavailable-item, and archived-item states.", "Bulk selection or multi-item operation state when collection actions can affect more than one item.", "Narrow-screen state that keeps collection identity, item identity, count, and primary actions visible without collapsing into unlabeled cards." ], "interactionContract": [ "Collection actions and item actions have separate labels, placement, confirmation, and post-action feedback.", "Filtering or sorting changes the current view without silently changing collection membership.", "Removing an item, deleting a section, copying a collection, or deleting the whole collection states the affected scope before destructive commit.", "Adding an item confirms which collection received it and whether the item can belong to multiple collections.", "Reordering uses stable item IDs and announces the new position or section without losing focus.", "Shared viewers can tell whether they are seeing all items, a permission-limited subset, localized item labels, or unavailable content.", "Counts distinguish total collection items from visible, selected, hidden, filtered, unavailable, and permission-limited items when those differ.", "Copying or duplicating a collection makes ownership, permissions, and future edits clear." ], "implementationChecklist": [ "Define the collection object: title, description, owner, visibility, membership rule, allowed item types, sections, order model, item count, update policy, and supported actions.", "Separate item actions from collection actions in labels, hit targets, permissions, analytics, and confirmation flows.", "Choose item presentation based on item inspection needs: compact rows for scanning, visual cards for preview, grouped links for documents, or specialized views for media and maps.", "Implement empty, no-results, permission-limited, unavailable-item, loading, failed-load, shared read-only, copy, delete, and stale-link states.", "Persist item identity, order, section, selection, and focus across filtering, sorting, reordering, refresh, and permission changes.", "Expose total count and visible count when filters, permissions, or unavailable items make them differ.", "Label share, copy, remove, delete, reorder, subscribe, and export actions with the collection or item name they affect.", "Test keyboard operation, screen reader names, drag alternatives for reordering, destructive confirmations, shared-link permissions, long titles, localization, and mobile wrapping." ], "commonMisuses": [ "Treating any grid of cards as a collection without collection identity or membership behavior.", "Mixing search results, recommendations, recent history, saved items, and editorial links under one collection heading.", "Letting filters or sorts mutate collection membership without an explicit save step.", "Hiding permission-limited or unavailable items without explaining count differences.", "Using collection when a maintained category taxonomy would better help discovery.", "Making Delete collection, Remove item, and Clear filter look equivalent.", "Copying a collection without clarifying ownership, permissions, and edit independence.", "Depending on drag and drop for reordering without keyboard controls." ], "critiqueQuestions": [ "What makes this set a collection rather than a list, category, recommendation, search result, or related-links block?", "Who owns the collection and who can view, edit, copy, share, or delete it?", "Is membership manual, criteria-driven, editorial, imported, permission-limited, or generated?", "What happens to total count, visible count, and selected items after filtering, sorting, and permission changes?", "Can users distinguish removing an item from deleting the whole collection or clearing the current view?", "Does the ordering communicate a recommended sequence, manual priority, recency, or arbitrary layout?" ], "relatedPatterns": [ "list-view", "browse-by-category", "related-links", "recommendations", "recently-viewed", "saved-search", "saved-filter", "filter-panel", "sort-controls", "pagination", "empty-state" ], "comparisons": [ "collection-vs-list-view-vs-browse-by-category-vs-related-links" ], "sourceIds": [ "microsoft-learn-collections", "govuk-document-collections", "shopify-polaris-resource-list", "apple-hig-collections" ] }, { "id": "combobox", "completionStatus": "complete", "name": "Combobox", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Single-value input widget with owned popup", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to choose one value from a long, dynamic, or partially known option set, but a plain select is slow to scan and a plain text input cannot expose option ownership, active movement, or a selected value contract.", "solution": "Provide a labelled value field with an associated popup, explicit expanded state, active option movement, option acceptance, cancellation, validation, and a clear custom-value policy.", "uiGuidance": [ "Render a persistent label, editable or select-only value surface, popup indicator, collapsed and expanded states, option popup, active option, committed selection, clear action when supported, help text, and error text.", "Keep the text value, active option, selected option ID, popup visibility, and submitted value visibly and programmatically synchronized." ], "uxGuidance": [ "Use a combobox when users need one value from a large or dynamic option set and benefit from opening a popup, typing to narrow it, or copying/editing the displayed value.", "Make acceptance and cancellation explicit: moving through options should not silently commit a value, and Escape should close the popup without changing the previous accepted selection." ], "uiExamples": { "good": [ "An Assignee combobox shows a label, typed text, disclosure button, active option in a listbox, selected-value status, and an error when typed text has no accepted option.", "A Department field opens a list of matching departments, keeps focus in the field while the active option moves, and clearly marks the committed department." ], "bad": [ "A custom dropdown displays matching labels but never exposes expanded state, active option, or the controlled popup.", "A visible assignee name changes after typing while an old hidden user ID remains selected for form submission." ] }, "uxExamples": { "good": [ "A user types Ada, moves the active option with Arrow Down, presses Enter to accept Ada Lovelace, then edits the label and sees the selected ID clear until a new option is accepted.", "A user opens a long office list, explores several options, presses Escape, and the previously selected office remains unchanged." ], "bad": [ "The component automatically commits the first match as soon as a user types one character.", "A user types a custom team name in a field that only accepts known teams and the form submits a stale previous team ID." ] }, "problemContext": [ "The product needs one submitted value, often with both a human-readable label and an internal option ID.", "The option set is too long, dynamic, or filtered to work well as radio buttons or a simple select.", "Users may know part of the value and need typing to narrow options.", "Opening the popup, navigating options, accepting a value, and cancelling exploration have different meanings.", "The typed string may be different from the last committed option and must not submit a stale selected ID." ], "selectionRules": [ "Choose a combobox when a single field controls a popup of allowed or suggested values.", "Use it when users need to type to filter, open the popup to browse, or copy and edit the displayed value.", "Use autocomplete as the behavior inside a combobox when suggestions complete what the user typed.", "Use native select when the choices are few enough to browse directly and typing is unnecessary.", "Use text input when any arbitrary value is valid and there is no popup or selected option to maintain.", "Use multi-select or chip selection when users need more than one committed value.", "Use typeahead or search suggestions when the interaction is open-ended discovery or query formulation rather than choosing one field value.", "Allow custom values only when the domain accepts values outside the list, and show that policy before validation." ], "requiredStates": [ "Collapsed empty state with label, help text, and popup affordance.", "Focused collapsed state with current value and selected option status.", "Expanded popup state with controlled listbox, grid, tree, or dialog.", "Filtered option state after typing.", "Active descendant state distinct from committed selection.", "Accepted option state with visible label and synchronized submitted ID.", "Edited-after-selection state where the selected ID is cleared or marked unresolved.", "No matching option state.", "Custom value allowed state.", "Custom value disallowed validation state.", "Escape-cancelled state that preserves the previous accepted value.", "Disabled and read-only states with readable value." ], "interactionContract": [ "The combobox element owns or controls its popup with aria-controls when the popup is available.", "aria-expanded reflects whether the popup is visible.", "For listbox, grid, or tree popups, DOM focus remains on the combobox while aria-activedescendant identifies the active option.", "Arrow keys move the active option without breaking normal text editing.", "Enter or pointer selection accepts the active option, updates the visible value, and synchronizes the submitted option ID.", "Escape closes the popup without committing an explored option unless the product has a documented clearing behavior.", "Typing after a committed selection clears or invalidates the selected ID until a new valid option or accepted custom value is chosen.", "Validation distinguishes unresolved typed text from an accepted option and announces any required repair." ], "implementationChecklist": [ "Decide whether the combobox is editable or select-only, whether values are restricted to the list, and whether custom values are permitted.", "Define the popup role, option identity, selected-value model, filtering behavior, no-result behavior, and stale-response handling before wiring the component.", "Use a native select when it satisfies the job; build a custom combobox only when popup ownership, filtering, or active option behavior is required.", "Give the field a visible label and ensure its accessible name is distinct from the current value.", "Set aria-expanded, aria-controls, aria-autocomplete when appropriate, and aria-activedescendant for active options in listbox, grid, or tree popups.", "Keep focus management compatible with standard single-line text editing keys and do not capture keys needed for cursor movement, selection, copy, paste, undo, or deletion.", "Clear stale selected IDs whenever typed text diverges from the accepted option unless custom text is explicitly accepted.", "Test pointer, keyboard, screen reader, touch, high zoom, forced colors, slow filtering, no results, invalid text, Escape, Enter, disabled, read-only, and form submission." ], "commonMisuses": [ "Using a custom combobox for a short list where native select, radio buttons, or segmented controls would be simpler.", "Treating highlighted, active, and selected states as the same thing.", "Submitting the last selected option ID after the user changes the visible text.", "Moving DOM focus into popup options for an editable combobox and breaking text editing.", "Forcing the first result before the user accepts it.", "Leaving aria-expanded, aria-controls, or aria-activedescendant stale when the popup opens, closes, or filters.", "Allowing arbitrary custom values in a domain that requires a known record." ], "critiqueQuestions": [ "Does this field need a popup-owning widget, or is the real need autocomplete behavior, select, text input, or multi-select?", "Can users tell the difference between typed text, active option, and committed selected value?", "What happens to the submitted ID when the user edits the visible value after selecting an option?", "Can keyboard users open, move, accept, cancel, clear, and submit without losing text editing behavior?", "Are custom values allowed, rejected, or accepted only after an explicit action?" ], "relatedPatterns": [ "autocomplete", "select", "text-input", "multi-select", "typeahead", "search-suggestions", "inline-validation" ], "comparisons": [ "combobox-vs-autocomplete-vs-select-vs-text-input" ], "sourceIds": [ "wai-aria-apg-combobox", "uswds-combo-box-component", "carbon-combo-box-component", "ontario-design-system-autocomplete" ] }, { "id": "command-palette", "completionStatus": "complete", "name": "Command palette", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Modal command surface", "maturity": "established", "platforms": [ "web", "desktop" ], "problem": "Experienced users need a fast keyboard-first way to jump to actions, destinations, and objects across a large product.", "solution": "Open a searchable modal command surface that lists actions and destinations, supports filtering, and clearly previews what each command does.", "uiGuidance": [ "Render a compact dialog-like command surface with a search input, current scope, typed command mode, active result, command metadata, and empty state.", "Make the visible trigger, shortcut hint, focused input, highlighted row, command type, and destructive confirmation requirement easy to scan." ], "uxGuidance": [ "Accelerate expert navigation and repeated actions across a large product while preserving ordinary navigation for novice and low-frequency users.", "Make command execution predictable by showing scope, consequence, keyboard behavior, dismissal, and recovery before activation." ], "uiExamples": { "good": [ "Centered command surface with input, shortcut hint, scope chip, grouped commands, command type labels, and a visible active row.", "Rows distinguish navigation, creation, settings, and confirmation-required actions without relying on icons alone." ], "bad": [ "Huge branded modal that buries the input below decorative content.", "Commands with identical labels, no scope, no active row, and no indication whether Enter navigates or changes data." ] }, "uxExamples": { "good": [ "Keyboard shortcut or visible trigger opens the palette, focus lands in the command input, arrows move the active row, and Enter activates the highlighted safe command.", "Escape closes and returns focus to the opener; destructive commands open a confirmation-required state." ], "bad": [ "Palette is the only way to reach important navigation.", "Destructive commands execute from fuzzy search with no confirmation or recovery." ] }, "problemContext": [ "The product has many actions spread across menus and pages.", "Users repeat expert workflows and benefit from keyboard acceleration.", "Commands may depend on the current workspace, repository, object, or page scope." ], "selectionRules": [ "Choose a command palette when users need to run commands or jump across destinations faster than the visible navigation allows.", "Use it as an accelerator layered on top of visible navigation, never as the only path to primary workflows.", "Label commands by outcome and scope, such as Open billing or Create report in Workspace, rather than internal feature names.", "Require an additional confirmation or separate flow before irreversible, destructive, or permission-changing commands execute." ], "requiredStates": [ "Closed state with discoverable trigger.", "Open dialog state with focus in the command input.", "Scoped suggested commands state.", "Filtered result state with one active command.", "No matching commands state with query revision.", "Command executed, confirmation-required, or dismissed state." ], "interactionContract": [ "Opening the palette moves focus to the command input.", "Arrow keys move the active command without changing the query.", "Enter activates the active command or opens a required confirmation flow.", "Escape closes and returns focus to the opener.", "Activating a command performs the labeled action or navigates to the labeled destination.", "The visible scope explains what object, workspace, or page the command will affect." ], "implementationChecklist": [ "Provide a visible trigger and a keyboard shortcut hint where appropriate.", "Use dialog semantics for the overlay and listbox or equivalent composite semantics for command results.", "Keep focus inside the palette while open and return focus to the opener after close.", "Show current scope, command type, active row, empty state, and execution feedback.", "Keep destructive commands out of one-keystroke execution unless they open a confirmation step." ], "commonMisuses": [ "Hiding basic navigation behind a keyboard-only palette.", "Mixing irreversible destructive actions into the same low-friction list.", "Returning vague commands such as Settings without context.", "Treating content search results and side-effect commands as the same kind of row." ], "critiqueQuestions": [ "Is this an accelerator for known workflows or a crutch for weak navigation?", "Can users tell whether the highlighted row navigates, changes state, or opens a confirmation?" ], "relatedPatterns": [ "basic-search", "modal-dialog" ], "comparisons": [ "basic-search-vs-command-palette" ], "sourceIds": [ "github-command-palette", "vscode-command-palette", "wai-aria-apg" ] }, { "id": "comments", "completionStatus": "complete", "name": "Comments", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Object-attached comment composer and comment list with authorship, replies, state, permissions, and moderation", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Collaboration breaks down when feedback is stored as loose notes, global feed items, private messages, or overwritten text fields instead of anchored comments with clear authorship, state, permissions, and recovery.", "solution": "Provide anchored comment composition and display with author and time metadata, reply and resolution lifecycle, draft preservation, exact object or selection links, edit and deletion history, permission-aware actions, moderation states, and notification deep links.", "uiGuidance": [ "Render comments as anchored contributions with author identity, timestamp, body, optional attachment or selection context, edited state, reply target, and state labels such as open, resolved, hidden, deleted, or assigned.", "Expose comment actions as item-scoped controls with permission-aware labels for reply, edit, resolve, reopen, assign, copy link, hide, report, or delete, and keep the composer visually tied to the object or selected range being discussed." ], "uxGuidance": [ "Use comments when users need to discuss, question, annotate, review, or leave follow-up notes on a specific object, selection, file line, record, document, or task without changing the primary content directly.", "Preserve comment drafts, anchors, authorship, notifications, edit history, deletion outcomes, and resolved or hidden states so conversation context remains trustworthy across reloads, permissions, moderation, and return visits." ], "uiExamples": { "good": [ "A document margin comment shows the selected paragraph, author, timestamp, body text, Reply, Resolve, Assign, and Copy link actions with the composer focused on that selection.", "A record comment list shows open and resolved comments separately, indicates edited comments, and disables Delete for users without permission while leaving Reply available." ], "bad": [ "A Notes textarea sits under a record and calls itself comments even though every user overwrites the same field.", "Comment actions appear only on hover, Delete has no warning, and resolved comments vanish without a way to find or reopen them." ] }, "uxExamples": { "good": [ "A reviewer comments on a selected line, adds an action item for Dana, receives a reply, resolves the comment, and can reopen it from the resolved filter.", "A moderator hides an off-topic comment with a visible reason, and readers can still tell that moderation happened without seeing the hidden text by default." ], "bad": [ "A user writes a long comment, loses network connection, and the draft disappears when the page reloads.", "A notification says New comment but opens the record top, leaving users to search for the exact comment and replied-to selection." ] }, "problemContext": [ "Users need to discuss or annotate a specific document selection, file line, design frame, issue, ticket, record, image, task, or content item.", "The comment may be public, internal, private, permission-limited, assigned as an action item, resolved, reopened, edited, hidden, redacted, or deleted.", "Comment activity may generate notifications, appear in feeds, affect review queues, or need moderation, but the canonical comment remains attached to its object or selection.", "Users need to understand who said what, when it changed, who can act on it, and whether the conversation still needs attention." ], "selectionRules": [ "Choose comments when the core object needs attached discussion, review feedback, annotation, or follow-up notes that remain separate from the object's primary editable content.", "Use textarea when the only need is a multi-line answer field and there is no authorship, reply, timestamp, resolution, moderation, or notification lifecycle.", "Use feed when the primary experience is consuming a stream of updates from many objects rather than reading discussion anchored to one object.", "Use activity log when entries must represent system events, provenance, or compliance history rather than authored conversational content.", "Use notification center when comment activity must be triaged across objects with unread, retention, and preference behavior.", "Use review queue when many comments need moderation, assignment, bulk triage, or repeated human decisions.", "Keep comment anchors visible or recoverable when the referenced selection, line, object, or attachment changes.", "Separate destructive moderation from everyday reply and resolve actions with permission checks, warnings, and history where appropriate." ], "requiredStates": [ "Empty comment list and first-comment composer.", "Draft comment, saving comment, saved comment, failed save, retry, and discarded draft states.", "Open comment with author, timestamp, body, anchor, and item actions.", "Reply state, reply saved state, and focused return to the affected comment.", "Resolved, reopened, assigned, done, edited, deleted, hidden, reported, and redacted states.", "Permission-limited state where some users can read and reply but cannot edit, delete, hide, or resolve.", "Anchor missing, outdated selection, collapsed conversation, filtered resolved comments, and direct-linked comment states.", "Notification-deep-linked state that scrolls and focuses the exact comment or reply." ], "interactionContract": [ "Submitting a comment creates a durable item with stable ID, author, timestamp, body, anchor, visibility scope, and notification behavior.", "Reply, resolve, reopen, assign, hide, edit, delete, report, and copy-link actions operate on the named comment or conversation, not on the whole object by accident.", "Draft text survives navigation warnings, reload recovery, temporary offline state, validation errors, and permission checks until the user sends or discards it.", "Edits show an edited indicator and, when product policy requires it, expose edit history or moderation reason to eligible users.", "Deletion and redaction clearly communicate reversibility, timeline impact, and who can still see metadata or history.", "Resolved or hidden comments remain discoverable through filters, history, or moderation views when the product promises recoverability.", "Notification links, copied links, and search results open the exact object and comment context, with focus or highlight on the target comment." ], "implementationChecklist": [ "Define comment anchor type, author model, visibility scope, permission rules, draft lifecycle, notification triggers, and moderation states before building the composer.", "Design the composer with clear placeholder text, submit and cancel behavior, attachment or formatting affordances, validation, and failure recovery.", "Render comment items with stable identity, author, timestamp, body, edited state, anchor summary, and item-scoped action menu.", "Support reply, resolve, reopen, assign, hide, edit, delete, report, copy link, and filter behavior only when the product rules require them.", "Preserve comment drafts and comment-list position across reload, route return, failed save, offline retry, object update, and permission changes.", "Add direct-link behavior that scrolls and focuses the referenced comment, including when it is collapsed, resolved, hidden, or attached to changed content.", "Test keyboard access, screen reader labels, touch access to non-hover actions, long comments, deleted users, edited history, moderation, deleted anchors, and mobile wrapping." ], "commonMisuses": [ "Using one shared Notes field as a comment system and overwriting prior contributors.", "Treating a comment as a feed item and losing its object or selection anchor.", "Hiding edit, delete, resolve, or moderation actions behind hover-only controls.", "Deleting or hiding comments without warning, permission checks, reason text, or timeline evidence.", "Sending notifications that do not deep-link to the exact comment or reply.", "Letting resolved or hidden comments disappear with no filter, history, or reopen path.", "Making comments the only audit record for decisions that require durable activity-log evidence.", "Allowing replies or assignments to fail silently when the target user lacks access." ], "critiqueQuestions": [ "What exact object, selection, line, frame, record, or task does this comment belong to?", "Can users tell who wrote each comment, when it changed, and whether it still needs action?", "Which actions are available to author, owner, moderator, assignee, guest, and read-only users?", "What happens to comments when the anchor is edited, deleted, moved, hidden, or permission-limited?", "Can a notification, copied link, or search result take users back to the exact comment context?", "Is deletion reversible, and if not, does the interface warn and leave the right timeline evidence?" ], "relatedPatterns": [ "textarea", "feed", "activity-log", "notification-center", "review-queue", "details-panel", "permission-denied-state", "drawer" ], "comparisons": [ "comments-vs-textarea-vs-feed-vs-activity-log" ], "sourceIds": [ "github-commenting-on-pull-request", "google-docs-comments-action-items", "atlassian-assets-comments", "github-managing-disruptive-comments" ] }, { "id": "compare-view", "completionStatus": "complete", "name": "Compare view", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Selected side-by-side attribute comparison of peer items", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to choose among similar offerings with many attributes, but browsing cards, opening detail pages, or scanning a large table forces memory work and makes tradeoffs between nonadjacent items hard to judge.", "solution": "Provide a bounded Compare view where users intentionally add similar items, see them side by side across consistent grouped attributes, hide or highlight differences, keep item identity visible while scrolling, remove or swap candidates, and act on the chosen item without losing the shortlist.", "uiGuidance": [ "Render compared items as a bounded side-by-side matrix with item identity, thumbnail or icon when useful, price or status, remove controls, action controls, grouped attribute rows, row labels, consistent units, missing-value notation, and difference indicators.", "Keep compared item identity visible during long comparisons through sticky column headers, repeated compact headers, pinned item cards, or a persistent selected-item tray." ], "uxGuidance": [ "Use Compare view when users have selected a small set of similar items and need to weigh several meaningful attributes together before choosing, saving, buying, applying, or discarding options.", "Help users reduce cognitive load by limiting the number of compared items, hiding identical attributes, highlighting differences, grouping related specs, preserving selected items, and offering a route back to browsing." ], "uiExamples": { "good": [ "A laptop compare view shows three selected models as columns, grouped rows for performance, display, portability, and support, a sticky model header with price, and a differences-only switch.", "A plan comparison view keeps plan names, monthly cost, primary action, and remove buttons visible while users scroll through included limits and service features." ], "bad": [ "A comparison page shows seven products in tiny columns with paragraphs in every cell, no row grouping, no sticky headers, and no way to remove one item.", "A side-by-side card layout repeats marketing copy but omits shared row labels, units, missing-value marks, and difference highlighting." ] }, "uxExamples": { "good": [ "A shopper selects three laptops, opens comparison, hides identical specs, highlights battery and memory differences, removes the weakest option, and returns to the same shortlist in the product grid.", "A mobile user compares only two saved plans at a time, switches which item is visible in the second column, and keeps plan identity and price pinned above the attributes." ], "bad": [ "A user must open three product detail pages in separate tabs and remember battery, weight, and warranty values because the site has no comparison view.", "A compare view resets the selected items after sorting or returning to browse, so the user must rebuild the shortlist from memory." ] }, "problemContext": [ "Items are similar enough to share meaningful attributes, such as products, plans, locations, services, courses, vendors, devices, loans, or saved options.", "Users are in a shortlisting phase after search, browse, filtering, or saved-item collection and need to make a compensatory decision across several criteria.", "The attribute set may be longer than a card can show, and some attributes matter only to a subset of users.", "The view may be static with preselected options or dynamic with user-selected candidates from a list, grid, search result, or saved view.", "Mobile and narrow layouts make the full matrix difficult, so the product needs item-count limits, attribute subsets, paired comparison, or a saved shortlist fallback." ], "selectionRules": [ "Choose Compare view when users need to evaluate a small number of similar items across the same attributes.", "Use Compare view after users have narrowed candidates through search, filter, category browsing, recommendations, favorites, or saved items.", "Use table when the main task is scanning many records, auditing values, sorting rows, or exporting the dataset rather than comparing a selected shortlist.", "Use card grid or card list when users are still discovering candidates and do not need aligned attribute tradeoffs.", "Use details panel when users need to inspect one selected item while staying in a list, grid, map, or board.", "Use data grid when users need to edit values, reorder columns extensively, or navigate cells like a spreadsheet.", "Use filters or facets when one nonnegotiable attribute should eliminate items before comparison.", "Avoid Compare view when items are not mutually exclusive, too cheap or simple to justify comparison, mostly aesthetic, or too unique to share useful attributes.", "Limit comparison to a small set, usually two to five items on desktop and fewer on mobile.", "Do not hide important differences behind hover-only cells, collapsed rows, or marketing-only labels." ], "requiredStates": [ "No compared items state with instructions for adding items and a route back to browse.", "One compared item state that explains another item is needed for meaningful comparison.", "Full comparison state with item headers, grouped attribute rows, actions, row labels, and selected-item count.", "Maximum item limit reached state with a clear remove or replace path.", "Differences highlighted, identical rows hidden, attribute group collapsed, attribute group expanded, and all attributes restored states.", "Item removed, item swapped, item unavailable, missing attribute, stale price or status, loading attributes, and failed attribute load states.", "Mobile pair comparison, horizontal-scroll comparison, sticky header, and selected-item tray states.", "Return-to-browse, save comparison, share comparison, export comparison, and choose item states." ], "interactionContract": [ "Compared columns represent user-selected or explicitly preselected peer items, and the view states the item count and comparison limit.", "Each row compares the same attribute across items using consistent labels, units, formatting, and missing-value rules.", "Hide-identical and highlight-differences controls update row visibility or row emphasis without changing the selected items.", "Removing, swapping, saving, or returning to browse preserves the remaining shortlist and the user's place in the originating list or grid when possible.", "Sticky item headers, row labels, and group headings preserve orientation while users scroll vertically or horizontally.", "Mobile comparison either limits columns, lets users choose a pair or subset, or provides a saved-item fallback instead of squeezing the full matrix unreadably.", "Action buttons such as Choose, Buy, Apply, Save, or Contact are tied to the correct compared item and remain distinguishable from remove controls.", "The view explains unavailable, stale, missing, estimated, normalized, or vendor-supplied attributes before users rely on the comparison." ], "implementationChecklist": [ "Define comparable item type, maximum item count, required attributes, optional attributes, groups, units, missing-value notation, primary action, and return-to-browse state.", "Add compare affordances to source cards or rows with persistent labels, keyboard access, and a selected-item reminder or tray.", "Render comparison with item headers as columns, attributes as rows, grouped sections, sticky identity, row separators, and responsive behavior.", "Implement remove, replace, hide-identical, highlight-differences, group collapse, save, share, export, and choose actions with clear focus management.", "Model empty, one-item, max-items, missing attributes, stale attributes, unavailable item, loading, failed-load, mobile, and horizontal overflow states.", "Keep selected items keyed by object ID rather than visible index so filtering, sorting, reordering, and returning to browse do not corrupt the shortlist.", "Test with long item names, long attribute labels, mixed units, missing values, duplicate names, many groups, narrow screens, keyboard, zoom, and high contrast.", "Provide a table, data grid, or details handoff when users need exact row work, many records, editing, or deep per-item inspection." ], "commonMisuses": [ "Allowing too many compared items so columns become unreadable.", "Using inconsistent labels, units, or attribute availability across compared items.", "Showing long marketing paragraphs instead of concise comparable values.", "Hiding compare selection behind hover-only controls.", "Dropping item names, prices, or key status when users scroll.", "Failing to hide or highlight identical rows, forcing users to search manually for differences.", "Treating a general table, details page, or card grid as a Compare view without selected-item management.", "Removing selected items when users return to browse, filter, sort, or change viewport." ], "critiqueQuestions": [ "What decision are users making, and which attributes genuinely influence that decision?", "Are the compared items similar enough for row-by-row comparison and mutually exclusive enough to justify choosing among them?", "Can users see item identity, price or status, row labels, units, and differences while scrolling?", "What is the item limit, and how do users remove, replace, or add candidates?", "How does the view behave with missing attributes, identical attributes, stale values, and mobile width?", "Would a table, card grid, details panel, filter panel, or saved list better match the user's stage?" ], "relatedPatterns": [ "table", "data-grid", "card-grid", "card-list", "details-panel", "filter-panel", "sort-controls", "pagination", "collection" ], "comparisons": [ "compare-view-vs-table-vs-card-grid-vs-details-panel" ], "sourceIds": [ "nng-comparison-tables", "baymard-user-friendly-comparison-tools", "baymard-provide-comparison-features", "nng-mobile-tables", "nng-data-tables-tasks" ] }, { "id": "complete-complex-form", "completionStatus": "complete", "name": "Complete complex form", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Sectioned enterprise configuration form", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Large product settings and policy forms become unsafe when users cannot see section ownership, cross-section dependencies, required fields, validation recovery, or whether the complete configuration is ready to save.", "solution": "Structure related settings into named sections on one inspectable form surface, expose section status, keep fields grouped and labelled, validate dependencies across sections, preserve draft data, summarize errors, and require review before high-risk saves.", "uiGuidance": [ "Render one coherent form surface with a clear title, section navigation or section headings, current section state, grouped controls, persistent labels, helper text, required indicators, error summary, field-level errors, review or summary state, and one save contract.", "Make section status explicit with text such as Current, Complete, Error, Optional, Needs review, or Not checked, and keep those states derived from actual field validity and stale dependency state." ], "uxGuidance": [ "Use a complete complex form when users must edit many related product settings together and need to inspect dependencies across sections before saving.", "Validate cross-section dependencies, preserve every entered value while moving users to the owning section for recovery, and require review again when an upstream field changes a downstream rule." ], "uiExamples": { "good": [ "A policy configuration form has Basics, Rules, Approvals, Notifications, and Review sections; Approvals shows an error because the threshold in Rules requires at least two approvers.", "A workspace settings page marks most fields optional, labels the few required fields explicitly, and shows section status plus a final review summary before Save." ], "bad": [ "A single grid shows Nm, Rule, Appr, Esc, Mail, JSON, Mode, and Owner fields with no labels, fieldsets, section status, or error ownership.", "A long settings page saves invalid combinations because validation checks each field in isolation and ignores dependencies between threshold, approvers, and escalation owner." ] }, "uxExamples": { "good": [ "A user raises a spend threshold, validates the form, is moved to the Approvals section, adds a second approver and escalation owner, reviews the complete policy, and saves without re-entering earlier values.", "A user jumps from Review back to Rules, changes a dependency, and sees Review marked stale until the affected sections pass validation again." ], "bad": [ "A user clicks Save, sees three generic errors somewhere in the page, and must scan many controls to discover which section owns each problem.", "A user opens an advanced area and loses entered values because the form treated hidden settings as disposable UI state instead of saved draft data." ] }, "problemContext": [ "The task configures enterprise software, policies, permissions, automation rules, workspace settings, billing rules, compliance controls, or other related product options.", "Users must compare values across sections, such as a threshold in one section that changes approval requirements in another.", "Most fields may be optional, but a small set of required fields and dependencies still block save.", "The product can preserve a form draft while users move between sections, validation errors, and review." ], "selectionRules": [ "Choose a complete complex form when many related configuration fields need one inspectable surface and cross-section comparison matters.", "Use a single-page form instead when the task is a compact related field set that does not need section status or dependency review.", "Use a multi-step form instead when the task is a long transaction best completed across saved pages with focused recovery per page.", "Use a wizard instead when the product must guide users through a dependent setup or creation assistant with step-specific actions, tests, cancel, and finish behavior.", "Use one-question pages instead when research shows each answer needs focus, branching, mobile-first recovery, or one thing per page.", "Group related inputs under section headings, fieldsets, legends, and helper text rather than relying on columns or visual proximity.", "Expose section status from real validation, dependency, and review state; never mark a section complete simply because it was visited.", "Validate cross-section rules in the owning section and keep all entered values visible or recoverable after validation fails.", "For long product configuration forms where most fields are optional, label the required fields explicitly and keep that convention consistent across the product.", "Require review again when an upstream answer changes a downstream rule, generated summary, approval path, notification effect, or save consequence." ], "requiredStates": [ "Initial draft state with named sections, required-field convention, grouped controls, and save unavailable or clearly pending validation.", "Current section state with visible section heading, fields, helper text, and local actions.", "Edited section state that preserves entered values before validation.", "Section complete state derived from required fields, local validation, and dependencies.", "Section error state with status text, summary link, and field-level messages.", "Cross-section dependency error state where a value in one section changes requirements in another.", "Optional section state that does not block save but remains inspectable.", "Stale review state after a dependency or high-risk field changes.", "Review state that summarizes important values and dependencies before save.", "Saved state that confirms the complete configuration was accepted." ], "interactionContract": [ "Section navigation changes the visible section without discarding draft values.", "Validate all sections reports every save-blocking issue and moves focus or context to the first owning section.", "Error summary entries identify the section and field group responsible for each problem.", "Field-level errors sit next to the owning control and use the same wording as the summary where practical.", "Save is blocked until required fields, cross-section dependencies, and required review are complete.", "Changing a dependency marks affected sections or review stale until validation or review runs again.", "Optional fields and optional sections remain available without being confused with unavailable or disabled states." ], "implementationChecklist": [ "Inventory sections, fields, required rules, optional rules, and dependencies before building the layout.", "Assign each dependency error to one owning section and field group so recovery has a clear destination.", "Use persistent labels, fieldsets, legends, helper text, and simple vertical ordering inside each section.", "Add section status derived from actual validation and review state.", "Implement error summary links that move users to the relevant section and field.", "Preserve draft values across section jumps, failed validation, reload recovery, and server responses.", "Represent stale review or stale dependent sections after upstream changes.", "Avoid dense multi-column grids unless reading order, labels, validation expansion, and responsive behavior remain predictable.", "Test keyboard order, screen reader section names, error summary navigation, zoom, mobile section navigation, draft preservation, dependency validation, and review-before-save behavior." ], "commonMisuses": [ "Calling a dense settings table a complex form without section status, labels, or validation ownership.", "Splitting tightly related settings across pages so dependencies are invisible during editing.", "Using wizard chrome for ordinary configuration edits that do not need guided setup or finish semantics.", "Hiding required fields or save-blocking errors inside advanced disclosure panels.", "Showing generic section errors without field-level messages.", "Marking sections complete because users opened them rather than because data is valid.", "Saving high-risk changes without a review of the combined configuration.", "Making visual column order differ from keyboard and screen-reader order." ], "critiqueQuestions": [ "Which fields or sections depend on values in other sections?", "Can users tell which sections are valid, invalid, optional, not checked, or stale?", "Does each error have an owning section and field-level recovery path?", "Would one-question pages or a multi-step form be easier because the task is public-facing, branched, or mobile-heavy?", "Is this really a guided setup wizard, or is it an editable settings surface?", "What must users review before a high-risk save becomes available?" ], "relatedPatterns": [ "single-page-form", "multi-step-form", "wizard", "error-summary", "inline-validation" ], "comparisons": [ "complete-complex-form-vs-single-page-form-vs-multi-step-form-vs-wizard" ], "sourceIds": [ "carbon-form-component", "uswds-form-templates", "govuk-form-structure-service-manual" ] }, { "id": "complete-multiple-tasks", "completionStatus": "complete", "name": "Complete multiple tasks", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Saved transaction hub for completing several sections or tasks over one or more sessions", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Long transactions fail when users cannot see the sections involved, which ones are complete, which can be done next, what is blocked, whether progress is saved, or when the transaction is ready to submit.", "solution": "Provide a saved task-completion hub that groups meaningful sections, shows task-specific statuses and dependencies, preserves progress across sessions, lets users enter and edit each task, and gates final review or submission until required tasks are complete.", "uiGuidance": [ "Render complete multiple tasks as a transaction hub with a service name, grouped task sections, task rows, short task names, optional concise hints, completion statuses, blocked or unavailable reasons, completed count, resume cue, and a final action that only becomes available when required tasks are complete.", "Show completed, in progress, not started, cannot start yet, needs attention, and changed since last visit states as text tied to each task row, with the row itself acting as the primary link into the task rather than status tags behaving like buttons." ], "uxGuidance": [ "Use complete multiple tasks when users need control over a long or complex transaction, may not finish in one sitting, and can complete meaningful sections in an order that works for them.", "Help returning users resume safely by preserving task progress, naming the first incomplete or changed section, explaining dependencies, allowing completed sections to be reopened for edits, and routing to review before final submission." ], "uiExamples": { "good": [ "An application hub shows Check before you start, Your details, Business information, Upload evidence, Review and send, statuses for Completed, In progress, Not started, Cannot start yet, and a disabled Apply button with the remaining requirement.", "A health registration service groups related tasks under About you, Medical information, and Evidence, shows 3 of 6 sections complete, and provides a skip link to the first incomplete section." ], "bad": [ "A long transaction uses a linear step indicator even though users need to complete independent sections over several sessions.", "A task list shows coloured status pills only, lets users click the pills instead of rows, and enables Submit while required tasks are incomplete." ] }, "uxExamples": { "good": [ "A user completes contact details, leaves work history in progress, returns later, follows Resume work history, edits contact details, uploads evidence, then reaches Review and send only after all required sections are complete.", "A user tries to open Review and send before uploading evidence and sees that the task is locked until Upload evidence is complete." ], "bad": [ "A returning applicant sees six numbered steps but no saved status, so they reopen completed sections to discover what is missing.", "A user reaches the final Apply button even though a required disclosure task is still marked Not started." ] }, "problemContext": [ "The user is completing an application, registration, onboarding, claim, setup, renewal, disclosure, case file, or other transaction made of several sections.", "Some sections may be independent while others depend on eligibility, identity, previous answers, uploaded evidence, payment, review, or approval.", "Users may need to stop, return later, edit completed sections, complete tasks in a personal order, or share work with another contributor.", "The product must store progress and expose the difference between not started, in progress, completed, blocked, changed, stale, and ready to submit.", "The final action may have legal, financial, service, or operational consequences, so completion state must be accurate before review or submit." ], "selectionRules": [ "Choose complete multiple tasks when users need a saved progress hub for several meaningful task sections in a transaction.", "Use the task list component inside this pattern for row-level task names, hints, links, and statuses; the pattern owns grouping, session return, dependency, edit, and submit readiness behavior.", "Use step navigation when the service must be completed in a strict linear order and users should continue one page at a time.", "Use process list when users need public guidance for an ordered journey outside the active saved transaction.", "Use multi-step form when the work is one guided form path rather than independent sections users can complete in different orders.", "Use draft state to describe the persisted incomplete record; use complete multiple tasks to navigate and update the sections inside that record.", "Use review before submit after every required task is complete and users need to check answers before the final action.", "Use confirmation page only after the final action has succeeded.", "Group related actions into tasks that match user goals, not internal data models, and split tasks that are too broad to name clearly.", "Show unavailable task dependencies before users open the task, such as Complete identity check first or Upload evidence before review.", "Keep statuses few and research-backed; completed tasks should draw less attention than tasks needing action.", "Always allow users to reopen completed tasks to edit answers and return to the hub with the updated status." ], "requiredStates": [ "First visit state with task groups, task names, initial statuses, and start guidance.", "Returning session state with saved progress and resume cue.", "Not started task state.", "In progress task state.", "Completed task state.", "Cannot start yet or dependency-blocked task state.", "Needs attention, changed, or stale task state.", "Optional task state that does not block final action.", "Task reopened for edit state.", "Task completion question or explicit return-to-hub state when needed.", "All required tasks complete state.", "Final review available state.", "Final action disabled or blocked state with reasons.", "Submitted handoff state to confirmation page." ], "interactionContract": [ "Selecting a task row opens that task and returns users to the same hub with updated status after save, skip, or completion.", "Task statuses are stored from canonical task data, not inferred only from visited pages or client-side progress.", "Changing an answer in one task updates dependent task statuses, warnings, and final action readiness.", "Blocked tasks remain visible with the reason and the task that unlocks them.", "Completed tasks remain editable, and edits can move dependent tasks back to needs attention when necessary.", "The final review or submit action is disabled or replaced with a clear blocked reason until all required tasks are complete.", "Returning sessions show saved progress, first incomplete task, changed tasks, and any expired or stale evidence." ], "implementationChecklist": [ "Define transaction tasks, task groups, required versus optional tasks, dependencies, completion rules, status vocabulary, resume behavior, edit behavior, review readiness, and final submission rules.", "Build task status from server-side saved answers, uploads, verification, payments, approvals, and dependency state rather than page-visit history.", "Design task rows with short names, optional concise hints, text statuses, whole-row links, unavailable reasons, completed count, and first incomplete shortcut when useful.", "Add return paths from each task to the hub, including saved, skipped, incomplete, completed, changed, error, and edit outcomes.", "Update dependent statuses when an answer changes, evidence expires, a required task becomes optional, or a previously completed section needs attention.", "Gate review and final submission against canonical required task completion and show exact missing or blocked tasks.", "Test first visit, returning session, mobile wrapping, long task names, screen readers, keyboard row activation, completed edit, dependency changes, stale evidence, optional tasks, final gating, browser Back, and saved-progress recovery." ], "commonMisuses": [ "Using complete multiple tasks for a service that can be simplified into a single short flow.", "Using it as an answer summary instead of a progress hub.", "Showing a task list when the user must complete every step in one strict order.", "Letting the final action proceed while required tasks are incomplete or stale.", "Making status tags look like clickable buttons while the task row is the real link.", "Using too many statuses so users cannot remember what each one means.", "Hiding locked tasks or dependencies until after users click them.", "Preventing users from reopening completed tasks to edit answers." ], "critiqueQuestions": [ "Do users need to complete this transaction over more than one sitting or choose the order of sections?", "What are the real task groups, required tasks, optional tasks, dependencies, and final submission rules?", "Which statuses are necessary for users to plan their work, and which create noise?", "How does the hub change when users return, edit a completed task, or change an answer that affects another section?", "What exact task blocks review or submission, and can users see how to fix it?", "Is this page a progress hub, or is it being misused as an answer summary or process guide?" ], "relatedPatterns": [ "step-navigation", "process-list", "multi-step-form", "start-page", "review-before-submit", "draft-state", "confirmation-page", "progress-bar", "error-summary" ], "comparisons": [ "complete-multiple-tasks-vs-step-navigation-vs-process-list-vs-multi-step-form" ], "sourceIds": [ "govuk-complete-multiple-tasks-pattern", "govuk-task-list-component", "nhs-complete-multiple-tasks-pattern", "nhs-task-list-component", "scottish-government-task-list-pattern", "govuk-task-list-iteration-research" ] }, { "id": "conditional-reveal-fields", "completionStatus": "complete", "name": "Conditional reveal fields", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Trigger-owned follow-up form field", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Forms become noisy or misleading when all follow-up fields are always shown, but they become fragile when hidden fields are required, submitted, or revealed without a clear relationship to the triggering answer.", "solution": "Reveal only the short related follow-up field owned by the selected answer, place it under the trigger, announce or describe the change, validate it only while relevant, and clear or exclude values when it becomes hidden.", "uiGuidance": [ "Place the revealed field directly under the radio, checkbox, or select option that triggers it, visually nested enough to show ownership while keeping the label and error text fully visible.", "Show only directly related follow-up questions or support text; avoid revealing unrelated content, complete subforms, independent submit actions, or a hidden journey inside one option." ], "uxGuidance": [ "Use conditional reveal fields when a short follow-up answer is only relevant for users who choose a specific option and should remain in the same decision context.", "Treat reveal and hide as data-state changes: when the trigger is removed, clear or exclude hidden values and validate the revealed field only while it is relevant." ], "uiExamples": { "good": [ "A Contact me by email checkbox reveals an Email address field immediately below that checkbox and hides it when Email is unchecked.", "A Yes radio for Do you have a reference number? reveals one Reference number field directly under Yes, with the error shown on that revealed field." ], "bad": [ "A hidden required email field blocks submit after Email was unchecked, but no visible field explains the error.", "Selecting Other reveals a long nested form with its own Save button and unrelated questions." ] }, "uxExamples": { "good": [ "A user selects Phone, sees the Phone number field appear under Phone, enters the number, then unchecks Phone and sees the number excluded from submission.", "A user submits after choosing Email but leaving Email address blank and gets a clear error on the revealed field while the Email option remains selected." ], "bad": [ "A user changes from Email to No contact and the hidden email address still gets sent.", "A screen reader user chooses an option and is not told that a new follow-up question appeared." ] }, "problemContext": [ "A radio, checkbox, or select answer determines whether one short follow-up field or piece of supporting information is relevant.", "The revealed content belongs to the same question or answer choice rather than a separate task, page, or section.", "The product can remove hidden values from validation and submission when the trigger is no longer selected.", "The implementation can be tested with keyboard and assistive technology so newly revealed fields are discoverable." ], "selectionRules": [ "Choose conditional reveal fields when one option needs a short, directly related follow-up field in the same local context.", "Use dependent fields instead when the later field remains part of the form and its option set or validity changes based on a controlling value.", "Use a plain radio group or checkbox group when no answer needs a follow-up field.", "Use single-question page or multi-step form when the follow-up has multiple questions, branching, submit behavior, or enough reading burden to need its own page.", "Use details or progressive disclosure for optional explanation text that is not part of the answer data.", "Place revealed content immediately after the triggering input, not at the bottom of the form or in a disconnected panel.", "Require revealed fields only while their trigger is selected.", "Clear or omit hidden field values when the trigger becomes unselected, unless the user is explicitly returning to the same selected option and draft restoration is intended.", "Show validation errors on the revealed field and preserve the selected trigger so users can see and fix the missing follow-up.", "Avoid nested reveals unless the branch remains short and easy to understand; otherwise split the flow." ], "requiredStates": [ "Initial state with trigger options visible and no conditional field shown.", "Trigger selected state with the related follow-up field revealed directly under the trigger.", "Revealed field completed state with value included in submission.", "Trigger changed or deselected state where the revealed field hides and its value is cleared or excluded.", "Revealed field required error state while the trigger remains selected.", "Hidden field not required state after the trigger is cleared.", "Multiple checkbox reveal state where more than one selected option can own its own follow-up field.", "Assistive notification or descriptive state that makes the newly revealed field discoverable.", "Error summary state linking to the revealed field when submission fails.", "Oversized branch state where the UI points users to a separate page or flow instead of revealing too much content." ], "interactionContract": [ "Selecting the trigger shows the related field immediately under that trigger.", "Deselecting the trigger hides the related field and removes or marks its value out of scope.", "The revealed field does not steal focus unless the product deliberately moves focus for a validated error or guided step.", "Validation checks revealed required fields only while their trigger is selected.", "Errors on a revealed field identify the revealed field and keep the trigger visible.", "Keyboard users can tab from the trigger into the revealed field in logical order.", "Submission payload excludes hidden stale values unless the user reselects the trigger and intentionally keeps the draft." ], "implementationChecklist": [ "Map each trigger option to exactly which field or short content block it reveals.", "Keep revealed content adjacent to the triggering input in DOM and visual order.", "Use stable IDs and descriptions so the trigger and revealed field relationship can be understood by assistive technology.", "Clear, exclude, or explicitly mark hidden values as inactive when their trigger is deselected.", "Apply required validation conditionally based on the trigger state.", "Ensure error summary links target the revealed field and that the trigger remains selected when errors are shown.", "Test with keyboard, screen reader, browser Back, form reload, saved draft, error summary, mobile layout, multiple selected checkboxes, and deselection.", "Escalate to a separate page, wizard, or multi-step flow when the revealed branch contains several questions or a separate submit action." ], "commonMisuses": [ "Hiding a required field and still validating it after its trigger is unselected.", "Submitting hidden stale values because the field was visually hidden but still active in the model.", "Revealing a complete form or separate task under a single option.", "Placing the revealed field far away from the answer that triggered it.", "Using conditional reveal to hide independent choices users should compare.", "Nesting several levels of reveals until users cannot tell what is required.", "Relying only on visual appearance so assistive technology users miss the newly revealed question." ], "critiqueQuestions": [ "Is the revealed field directly related to the selected answer?", "What happens to the revealed value when the trigger is unselected?", "Is the field required only while visible and relevant?", "Can keyboard and screen reader users discover the newly revealed field?", "Would this branch be clearer as its own question page or step?", "Does the error summary link to the revealed field while keeping the trigger selected?" ], "relatedPatterns": [ "dependent-fields", "radio-group", "checkbox-group", "single-question-page", "error-summary" ], "comparisons": [ "conditional-reveal-fields-vs-dependent-fields-vs-radio-group-vs-single-question-page" ], "sourceIds": [ "govuk-checkboxes-component", "govuk-conditional-reveal-accessibility", "agriculture-design-system-conditional-reveal", "govuk-radios-component" ] }, { "id": "confidence-uncertainty-display", "completionStatus": "complete", "name": "Confidence / uncertainty display", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Calibrated reliability and uncertainty display for AI or automated predictions before user action", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI predictions and automated assessments often look authoritative even when the system is unsure, uncalibrated, out of distribution, stale, missing evidence, or below the threshold for safe action.", "solution": "Show calibrated confidence or honest uncertainty labels with reasons, thresholds, freshness, invalidation rules, and review or fallback actions so users can judge reliability before they apply, publish, send, approve, deny, or escalate.", "uiGuidance": [ "Render confidence and uncertainty as labelled reliability information with confidence band, reason, input scope, calibration status, review threshold, freshness, and the next safe action.", "Use numbers only when the model score is calibrated for the task; otherwise use honest labels such as high confidence, medium confidence, low confidence, insufficient evidence, conflicting signals, or calibration unavailable." ], "uxGuidance": [ "Use confidence / uncertainty display when users need to decide whether an AI prediction, classification, recommendation, extraction, risk assessment, or generated answer is reliable enough to apply.", "Keep uncertainty actionable by showing what the system knows, what it does not know, what threshold applies, and whether the user should apply, review, verify sources, collect more input, or escalate." ], "uiExamples": { "good": [ "A claim classifier says Medium confidence, 71 to 78 percent calibrated range, review threshold 80 percent, conflicting account-age signal, and routes the case to manual review.", "A document extraction panel marks the amount field Low confidence because the scan is blurred, disables Apply all, and offers Open source page and Request reviewer actions.", "A customer reply suggestion shows High confidence from recent policy and matching intent, while still linking to the confidence explanation and source-grounding panel." ], "bad": [ "A generated answer shows 97 percent sure without calibration, threshold, source coverage, or review path.", "A red-yellow-green dot beside an AI suggestion is the only uncertainty signal and users cannot tell what action is safe.", "A low-confidence fraud flag looks identical to a verified rule match and can be applied to the account without review." ] }, "uxExamples": { "good": [ "A reviewer sees low confidence and out-of-distribution input, opens the reason panel, collects the missing invoice, and avoids auto-denying the claim.", "An agent sees that the confidence threshold changed for medical content, so the reply is gated until a specialist reviews it.", "A mobile user can expand a compact uncertainty panel and see the band, reason, stale model warning, and safe fallback before acting." ], "bad": [ "Users treat a high-confidence label as proof even though the answer has no source grounding and the claim still needs evidence.", "A model update invalidates old confidence scores but the UI keeps showing them as current.", "A buried review link makes low-confidence automation feel like the normal primary path." ] }, "problemContext": [ "The product uses model output, rules, retrieval, extraction, classification, ranking, risk scoring, or generated text to support a user decision.", "The system can estimate reliability, uncertainty, missing input, conflicting signals, distribution shift, source weakness, model freshness, or calibration limits.", "The user's action can affect customers, money, access, legal status, safety, operations, compliance, or public communication.", "A confidence display may appear inside chat, work queues, review panels, recommendation cards, form extraction, decision support, incident triage, or content publishing flows.", "A high confidence score is not the same as source proof, policy permission, legal correctness, or a severe consequence warning." ], "selectionRules": [ "Choose confidence / uncertainty display when users need to judge prediction reliability before acting on AI or automation output.", "Use source grounding display when the task is answer-wide source coverage, searched corpora, used evidence, and unsupported claims.", "Use citation display when the task is inspecting one claim-level source, quote, metadata, or source permission state.", "Use meter when the value is a read-only bounded scalar gauge and not an AI reliability state with calibration, threshold, and review implications.", "Use warning text when the message is a known severe consequence before an action rather than a reliability estimate.", "Use recommended next action when the system is proposing the action itself; confidence can appear inside it but should not replace reason, consequence, and review controls.", "Use query correction or adaptive defaults when confidence only gates those specific workflows.", "Expose the threshold that changes behavior, such as auto-apply, review required, source verification required, specialist review, or no automation.", "Do not show a precise percentage unless the number is calibrated, current, scoped to this task, and meaningful to the user's decision.", "Do not let confidence imply correctness, source support, policy approval, permission, or safety beyond the measured reliability dimension." ], "requiredStates": [ "High confidence state with calibration scope, reason, and whether direct apply is allowed.", "Medium confidence state with review recommendation, uncertainty reason, and threshold context.", "Low confidence state with apply gated and a review, verify, collect more input, or fallback action.", "Insufficient evidence state when the model cannot assess the input because required signals are absent.", "Conflicting signals state when evidence or model features disagree and need human judgment.", "Out-of-distribution or unfamiliar input state when the model sees content outside its trained or monitored operating range.", "Stale model, stale data, stale source, or threshold changed state that invalidates previous confidence.", "Calibration unavailable or uncalibrated score state that avoids fake precision.", "Review required, explain confidence, blocked apply, and mobile compact panel states." ], "interactionContract": [ "The display names the task, prediction, source of the confidence estimate, calibration scope, and last calibration or update time when available.", "Confidence labels, bands, and numeric values are tied to threshold rules that determine apply, review, escalation, verification, or fallback behavior.", "Users can open an explanation that identifies the main reliability drivers without exposing sensitive training data or protected signals.", "Low confidence, insufficient evidence, conflicting signals, out-of-distribution input, stale model, and calibration unavailable states change available actions before the user commits.", "Regeneration, edited input, changed source scope, model updates, threshold changes, and new evidence invalidate or recompute the visible confidence state.", "Copy, apply, approve, publish, send, deny, or export actions carry the current uncertainty state or are gated when the threshold is not met.", "Users can report incorrect confidence, override with reason where policy allows, or route the item to a reviewer without losing context." ], "implementationChecklist": [ "Define the prediction, confidence source, calibration method, operating scope, threshold rules, freshness policy, invalidation events, and user actions before rendering the display.", "Model high, medium, low, insufficient evidence, conflict, out-of-distribution, stale, uncalibrated, threshold changed, review required, and gated-action states as structured data.", "Separate model confidence from source grounding, claim citations, policy rules, permission checks, warning text, task status, and user feedback.", "Show the confidence label, calibrated range or caveat, threshold, reason, freshness, and recommended next action close to the AI output.", "Gate high-impact actions below threshold with review, verification, specialist escalation, or fallback, and re-check thresholds immediately before commit.", "Record overrides, reviewer decisions, user feedback, confidence state, threshold version, model version, and input version for audit where outcomes matter.", "Test fake precision, missing calibration, stale model, threshold changes, conflicting signals, no evidence, mobile wrapping, keyboard flow, screen-reader output, and high-zoom layouts." ], "commonMisuses": [ "Showing a fake percent or exact decimal for an uncalibrated model score.", "Using color-only confidence badges without text, threshold, reason, or action guidance.", "Treating high confidence as proof, source support, legal approval, or permission.", "Hiding low confidence, insufficient evidence, conflicting signals, or out-of-distribution states behind an action menu.", "Letting stale confidence persist after source, input, model, threshold, or policy changes.", "Using confidence display to avoid exposing source grounding, citations, warnings, or review workflows.", "Making low-confidence automation look like the normal primary path because the review option is buried." ], "critiqueQuestions": [ "Is the displayed confidence calibrated for this exact task, population, model version, and threshold?", "Can users tell what action is safe at high confidence, medium confidence, low confidence, and insufficient evidence?", "What invalidates the displayed uncertainty after edits, regeneration, source changes, model updates, or threshold changes?", "Does the UI separate model reliability from source grounding, citation evidence, policy approval, permissions, and severe consequence warnings?", "Can users open an explanation, request review, correct feedback, or override with reason where policy permits?", "Does the mobile layout keep uncertainty, threshold, and gated action visible before users commit?" ], "relatedPatterns": [ "source-grounding-display", "citation-display", "meter", "warning-text", "recommended-next-action", "query-correction", "adaptive-defaults" ], "comparisons": [ "confidence-uncertainty-display-vs-source-grounding-display-vs-citation-display-vs-meter-vs-warning-text" ], "sourceIds": [ "microsoft-human-ai-guidelines", "google-people-ai-guidebook", "nist-ai-risk-management-framework", "ibm-carbon-for-ai", "wcag-status-messages" ] }, { "id": "confirm-email", "completionStatus": "complete", "name": "Confirm email", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Mailbox access confirmation loop", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Services often need proof that a user controls an email address, but confirmation loops can block tasks unnecessarily, trap users with mistyped addresses, leak account state, or confuse email access proof with authentication.", "solution": "Use a confirmation loop only when mailbox access matters; show the target address, delivery state, link or code instructions, expiry, resend and change-address actions, pending versus verified status, and safe recovery for expired or already-used messages.", "uiGuidance": [ "Render confirm email as a mailbox-access proof loop with the target address, sent-message status, link or code instructions, expiry, resend timing, change-address route, pending or verified state, and clear blocking or non-blocking behavior.", "Keep email confirmation separate from email address entry, account creation, password reset, and two-factor authentication: it proves access to a specific mailbox, not just syntax, account persistence, password recovery, or an authentication factor." ], "uxGuidance": [ "Use confirm email when the service must know that the user can access the mailbox before activating an account, enabling recovery, sending sensitive notifications, accepting an invitation, or relying on the address for future access.", "Help users recover from delayed, expired, already-used, or mistyped confirmation messages by showing what was sent, where it was sent, how long it lasts, how to resend, and how to change the address." ], "uiExamples": { "good": [ "After account creation, the page says We sent a confirmation link to maya@example.com, explains the link expires in 30 minutes, offers Resend email and Change email address, and returns to the draft after verification.", "A code confirmation page accepts a pasted 6-digit code, shows the pending email address, and lets the user request a new code when the previous one expires." ], "bad": [ "The page says Check your inbox but hides which email address was used and has no resend or change-address action.", "A service blocks a low-risk receipt until the email is confirmed even though the user only needs a one-time copy." ] }, "uxExamples": { "good": [ "A user mistypes the address, notices the pending address on the confirmation page, changes it, receives a fresh link, and continues from the same account-activation step.", "A user opens an expired confirmation link, sees that the link no longer works, requests a new message, and returns to the verified account state after using it." ], "bad": [ "A user never receives the activation email and cannot resend, change the address, or continue in a limited pending state.", "A user clicks an old confirmation link and the page shows a raw token error with no explanation or recovery." ] }, "problemContext": [ "The service has already captured an email address and must decide whether syntactic validity is enough or mailbox access must be proven.", "Confirmation may be needed for account activation, email change, invitation acceptance, recovery eligibility, sensitive notifications, legal notices, or high-impact communication.", "The user may not receive the email immediately, may have entered the wrong address, may be using a shared mailbox, or may open a link after it expires.", "Confirmation links and codes are short-lived artifacts that must not leak through logs, analytics, referrers, screenshots, or support transcripts.", "Some services can continue in a pending or limited state while confirmation is outstanding; others must block until access is proven." ], "selectionRules": [ "Choose confirm email when the service must prove that the user can access the mailbox for account activation, recovery, sensitive notifications, invitation acceptance, or a verified contact route.", "Use email address entry when the task is collecting, formatting, validating, warning about, or reviewing the address before mailbox access is proven.", "Use account creation when the broader task is establishing a persistent account and confirm email is only one verification state inside that flow.", "Use password reset when the email message is a recovery artifact for replacing a forgotten password rather than confirming a normal contact address.", "Use two-factor authentication when an enrolled factor is needed for authentication or authorization; do not present email confirmation as equivalent to MFA.", "Decide whether the loop is blocking, non-blocking, or limited-access before designing the confirmation page.", "Show the exact email address that received the message and provide a direct way to change it when policy allows.", "Explain link or code expiry, resend timing, spam or delivery delay guidance, and what will happen after confirmation.", "Make confirmation links and codes time-limited, bound to the address and pending record, single-use where appropriate, and invalid after address change or successful confirmation.", "Use neutral activation and resend copy where account enumeration matters.", "After confirmation, update verified-email state, clear pending warnings, continue the blocked task, and notify or log according to security policy." ], "requiredStates": [ "Pending sent state with target email address, purpose, next step, expiry, resend, and change-address action.", "Blocking pending state where the task cannot continue until confirmation succeeds.", "Non-blocking pending state where users can continue with limited access while confirmation remains outstanding.", "Code entry state with paste support, autocomplete one-time-code when a short code is used, expiry hint, and submit control.", "Resend-limited state with server-backed wait time.", "Change-address state that invalidates previous confirmation artifacts.", "Expired link or code state with request-new-message action.", "Already-used or revoked link state with safe explanation and restart route.", "Verified state that confirms mailbox access and returns to the original task.", "Delivery trouble or support-needed state for inaccessible mailbox, delayed email, or repeated failed confirmations." ], "interactionContract": [ "The confirmation page states which email address is pending and why access to that mailbox is required.", "Resend, change-address, and support actions preserve the originating task or account context.", "Changing the address invalidates previous confirmation links or codes and sends a fresh confirmation to the new address.", "Expired, already-used, malformed, or revoked artifacts never show raw token values and always offer a safe next step.", "Code entry supports paste, correction, mobile keyboards, and one-time-code autocomplete when the code is short-lived.", "Confirmed state is stored separately from address syntax validity, deliverability, and account authentication.", "The loop does not expose whether another account owns the address unless the user is already in a safer authenticated route." ], "implementationChecklist": [ "Define why email access is required, whether the loop blocks the task, the pending-state permissions, link or code expiry, resend limits, change-address behavior, and support route.", "Design sent, pending, resend-limited, changed-address, expired, already-used, malformed, verified, and delivery-trouble states.", "Bind confirmation artifacts to the email address, pending account or record, purpose, and expiry window; invalidate them after change, use, or account deletion.", "Protect links, codes, address status, and token failure reasons from logs, analytics, referrers, screenshots, support tools, and URLs.", "Use neutral copy for account activation and duplicate-account cases where account enumeration matters.", "Test delayed delivery, wrong address, resend, multiple messages, expired link, already-used link, code paste, mobile email app handoff, browser Back, deep-link return, screen readers, and high zoom." ], "commonMisuses": [ "Forcing email confirmation when the service only needs a low-risk contact or receipt address.", "Hiding the email address that received the confirmation message.", "Providing no resend, change-address, expiry, or support route.", "Treating email syntax validation as verified mailbox access.", "Treating email confirmation as a second authentication factor for future sign-in.", "Letting old confirmation links remain valid after the address changes or confirmation succeeds.", "Showing raw token errors for expired or malformed links.", "Revealing account existence through activation, resend, or duplicate-address messages." ], "critiqueQuestions": [ "Why does this flow need proof of mailbox access rather than only a valid email address?", "Is the loop blocking, non-blocking, or limited-access, and is that visible to the user?", "Can users see and change the email address before waiting for another message?", "What happens when the email is delayed, expired, already used, opened on another device, or sent to a mistyped address?", "How are confirmation artifacts bound, expired, invalidated, and protected from leakage?", "Does any activation or resend path reveal whether an account already exists?" ], "relatedPatterns": [ "email-address-entry", "account-creation", "password-reset", "two-factor-authentication", "inline-validation", "review-before-submit" ], "comparisons": [ "confirm-email-vs-email-address-entry-vs-account-creation-vs-password-reset" ], "sourceIds": [ "govuk-confirm-email-address-pattern", "govuk-email-addresses-pattern", "owasp-authentication-account-enumeration", "nist-sp-800-63b-email-confirmation-codes", "mdn-autocomplete-credentials" ] }, { "id": "confirm-phone", "completionStatus": "complete", "name": "Confirm phone", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Phone reachability confirmation loop", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Services need proof that a captured phone route can receive a code, but phone confirmation can trap users with mistyped numbers, delayed messages, expired codes, SMS-only assumptions, and misplaced confidence in phone-based authentication.", "solution": "Use a short-lived phone-code loop only when phone access matters; show the destination and channel when safe, support paste and OTP autofill, explain expiry and retry limits, provide resend, change-number, voice or support recovery, and store verified-phone state separately from number syntax and authentication strength.", "uiGuidance": [ "Render confirm phone as a code-confirmation loop with the target number when safe, channel, code entry, expiry, resend timing, change-number route, no-phone or no-access support, and verified-phone state.", "Keep phone confirmation separate from phone number entry, confirm email, password reset, and two-factor authentication: it proves reachability of a captured phone route, not number syntax, mailbox access, password recovery, or a complete MFA program." ], "uxGuidance": [ "Use confirm phone only when the service must prove that the user can receive a text-message or voice code at the captured number before relying on it for activation, recovery, notification, or sensitive contact.", "Design for delayed SMS, mistyped numbers, expired codes, repeated failures, landlines, shared phones, inaccessible devices, SIM-swap risk, and users who need a non-phone route." ], "uiExamples": { "good": [ "After account creation, the page says a 5-digit code was sent by text message to 07700 900982, shows the code expiry, accepts pasted digits with one-time-code autocomplete, and offers request-new-code and change-number actions.", "A recovery settings page lets the user request a voice call when SMS is unavailable and records verified-phone state only after the code succeeds." ], "bad": [ "A page says Enter code but hides which number received it and has no way to request another code or correct a typo.", "A service marks a phone number verified because it matches a local number format, before any SMS or voice challenge succeeds." ] }, "uxExamples": { "good": [ "A user realizes the code was sent to a mistyped number, changes it, and receives a fresh code while the previous code can no longer verify the account.", "A user cannot receive SMS, requests a voice call or support route, and still has a recoverable path without exposing account ownership." ], "bad": [ "A user waits for a text that never arrives and cannot resend, change the number, use voice, or contact support.", "A user signs in with SMS as the only second factor and is given no warning or alternative despite PSTN risk." ] }, "problemContext": [ "The product has already collected a phone number and must decide whether number format, dialability, SMS capability, or actual access must be proven.", "Confirmation may be needed for account activation, phone-number change, account recovery, sensitive notifications, high-risk actions, or a verified contact route.", "Users may receive SMS late, enter the wrong number, use a landline, share a phone, lack cellular service, lose access, or face privacy and safety risks from phone contact.", "SMS and voice codes depend on the public telephone network and can be affected by interception, SIM-swap, forwarding, number recycling, roaming, and device access limitations.", "Some flows can show the destination number safely; sign-in and recovery flows may need to mask it or use neutral copy to avoid account or number exposure." ], "selectionRules": [ "Choose confirm phone when the product must prove that the user can receive a time-limited text-message or voice code at an already captured number.", "Use phone number entry when the task is collecting, formatting, validating, warning about, reviewing, or changing the phone number before access is proven.", "Use confirm email when the proof route is a mailbox link or code rather than SMS or voice call.", "Use two-factor authentication when an enrolled factor protects sign-in or authorization; do not present one-time phone confirmation as equivalent to a complete MFA strategy.", "Use password reset when the phone code is part of replacing a forgotten password rather than confirming ordinary phone reachability.", "Show the exact phone number when it is safe and useful; mask or omit it in sign-in recovery contexts where revealing the number could expose account data.", "Explain whether the code was sent by SMS, voice call, or another approved route, and provide an alternative when SMS is unavailable or inappropriate.", "Make codes short-lived, single-purpose, rate-limited, and bound to the number, user or pending record, and flow purpose.", "Invalidate previous codes when the number changes, when confirmation succeeds, or when the pending record is revoked.", "Do not force phone confirmation for low-risk contact collection, receipts, or flows where a review step is enough.", "Treat PSTN-based SMS or voice authentication as risk-bearing; provide notice and unrestricted alternatives when assurance requirements demand them." ], "requiredStates": [ "Sent-code state with target phone number when safe, channel, purpose, code length, expiry, resend, and change-number or support action.", "Blocking pending state where the task cannot continue until phone access is confirmed.", "Non-blocking pending state where users can continue with limited access while verified-phone state remains pending.", "SMS code-entry state with a labelled input, inputmode numeric, one-time-code autocomplete, paste support, and visible expiry.", "Voice code state for users who cannot receive SMS or are confirming a voice-capable number.", "Resend-limited state with server-backed wait time and clear current-code behavior.", "Change-number state that sends a fresh code and invalidates previous codes for the old number.", "Incorrect-code state with specific error copy and preserved input affordances.", "Expired-code state with request-new-code recovery.", "Too-many-attempts or rate-limited state with wait time, support, and abuse-protection copy.", "No access to phone state with voice, backup, support, or alternative-contact route.", "Verified phone state that returns to the originating task and clears pending warnings." ], "interactionContract": [ "The confirmation page states why phone access is required, what channel was used, and what phone number is being confirmed when disclosure is safe.", "Code entry accepts paste, spaces, hyphens, and familiar formatting, then normalizes only for comparison.", "Resend, voice-call, change-number, no-access, and support actions preserve the originating task or pending account context.", "Changing the number invalidates previous codes and sends a fresh code to the new number.", "Expired, incorrect, reused, or rate-limited codes do not expose raw token values and always offer a safe next step.", "Verified phone state is stored separately from phone number syntax validity, dialability, SMS capability, two-factor enrollment, and account authentication.", "Phone confirmation does not reveal whether a number or account exists unless the user is already in a safer authenticated route." ], "implementationChecklist": [ "Define why phone access is required, which channels are allowed, whether the loop blocks the task, code length, expiry, retry limits, resend behavior, change-number behavior, and alternatives.", "Design sent, SMS code, voice code, pending, resend-limited, changed-number, incorrect, expired, rate-limited, no-access, verified, and support-needed states.", "Use a labelled text input with inputmode numeric and autocomplete one-time-code for short code entry rather than a numeric spinbox.", "Allow paste and common separators while validating code length and numeric content with specific messages.", "Bind each code to the phone number, pending record, channel, purpose, expiry, and retry policy; invalidate it after use, number change, or revocation.", "Protect phone numbers, codes, token status, and failure reasons from logs, analytics, referrers, support tools, screenshots, and notification previews.", "Provide voice, backup, support, or non-phone alternatives for landline, no-SMS, inaccessible-device, shared-phone, or no-phone situations.", "Apply abuse controls such as resend throttling, retry limits, monitoring, and progressive delays without trapping legitimate users.", "Test delayed delivery, wrong number, no signal, number change, resend, multiple active messages, expired code, too many attempts, voice fallback, mobile autofill, screen readers, high zoom, and browser Back." ], "commonMisuses": [ "Treating phone-number format validation as proof that the user can receive texts or calls.", "Hiding the destination number when users need it to spot a typo.", "Providing no resend, wait time, change-number, voice, no-phone, or support route.", "Forcing SMS for users with landlines, shared phones, inaccessible devices, no cellular signal, or no phone.", "Using SMS confirmation as the only high-assurance authentication option without risk notice or an unrestricted alternative.", "Letting previous codes remain valid after the phone number changes or confirmation succeeds.", "Logging codes, full phone numbers, token failure reasons, or replayable verification URLs.", "Revealing account or number ownership through request-new-code, activation, or error messages." ], "critiqueQuestions": [ "Why does this flow need proof of phone access rather than only a phone number field and review?", "Does the page make clear whether phone proof stops the task, grants limited pending access, or only verifies a contact route?", "Can users see, mask, or change the target number appropriately for the context?", "What happens when SMS is delayed, the number is wrong, the code expires, too many attempts fail, or the user cannot access the phone?", "Are SMS and voice codes being treated as authentication, and if so, what alternatives and risk notices exist?", "How are codes bound, expired, invalidated, throttled, and protected from leakage?" ], "relatedPatterns": [ "phone-number-entry", "confirm-email", "two-factor-authentication", "password-reset", "account-creation", "inline-validation", "review-before-submit" ], "comparisons": [ "confirm-phone-vs-phone-number-entry-vs-confirm-email-vs-two-factor-authentication" ], "sourceIds": [ "govuk-confirm-phone-number-pattern", "govuk-phone-numbers-pattern", "nist-sp-800-63b-pstn-restricted", "mdn-webotp-api", "mdn-autocomplete-credentials" ] }, { "id": "confirmation-dialog", "completionStatus": "complete", "name": "Confirmation dialog", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Consequential alert decision", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can accidentally start consequential actions that are costly, security-sensitive, externally visible, or impossible to recover after commitment.", "solution": "Interrupt the requested action with an alert-style decision that names the object, scope, and consequence, makes cancellation safe and easy, and requires an explicit confirming action before commitment.", "uiGuidance": [ "Render an alert-style modal decision with a specific title, consequence description, safe cancellation, and a destructive action label that names the object or scope.", "Escalate severe broad-scope actions with typed confirmation or another deliberate step before enabling the destructive action." ], "uxGuidance": [ "Interrupt users only when the action has a meaningful consequence that cannot be safely recovered afterward.", "Use confirmation to create an informed decision point, not a reflexive second click after every routine action." ], "uiExamples": { "good": [ "Delete Research archive? explains that 14 notes and shared links will be permanently removed, offers Keep archive, and labels the danger action Delete archive.", "A typed DELETE field keeps Delete archive disabled until the user deliberately matches the required text." ], "bad": [ "A popup says Are you sure? with OK and Cancel but does not name the project, notes, or irreversible outcome.", "The red destructive action is enabled immediately and sits where users expect the routine primary button." ] }, "uxExamples": { "good": [ "Cancel, Escape, and Keep archive leave the archive unchanged and return focus to Delete archive.", "Typing DELETE enables the final action, then the outcome reports that deletion was deliberately confirmed." ], "bad": [ "Every archive, filter, and dismiss action opens the same confirmation until users click through automatically.", "A one-click OK popup deletes the archive without explaining recovery limits or affected shared links." ] }, "problemContext": [ "The user has already invoked an action and the product must verify intent before committing it.", "The consequence is destructive, costly, privacy-affecting, security-sensitive, externally visible, or difficult to reverse.", "A simple undo path cannot reliably restore the prior state after the action completes.", "The dialog can add information that might reasonably cause the user to cancel." ], "selectionRules": [ "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." ], "requiredStates": [ "Pre-action state with an explicit consequential trigger.", "Decision state that names the affected object, scope, and irreversible or costly consequence.", "Safe cancellation state that leaves the object unchanged and returns focus to the trigger.", "Blocked destructive state before required typed text or safety condition is satisfied.", "Confirmed committing state after the user deliberately activates the destructive action.", "Outcome state that reports deletion, cancellation, or policy-blocked status.", "Repeated-action state that avoids prompting for routine reversible actions." ], "interactionContract": [ "The confirmation appears only after a user-initiated action, not as surprise interruption unrelated to the current command.", "The dialog has alertdialog semantics or equivalent platform behavior when it communicates an urgent decision that requires a response.", "The title, description, and final action label name what will happen, not just ask Are you sure.", "The safe path is always reachable by keyboard and pointer before the destructive path is committed.", "Escape cancels when cancellation is safe and follows the same unchanged-object path as the cancel button.", "The destructive action is disabled or unavailable until any required typed confirmation, checkbox, or acknowledgement is satisfied.", "Closing after cancel or completion returns focus to the trigger or to the next logical outcome location.", "The dialog is not repeated for high-frequency actions where users will learn to dismiss it automatically." ], "implementationChecklist": [ "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." ], "commonMisuses": [ "Asking users to confirm every routine action until they stop reading.", "Using vague Are you sure copy without object, scope, or consequence.", "Making the destructive action the easiest accidental target.", "Using confirmation instead of undo for fast reversible actions.", "Using undo language for irreversible actions that cannot truly be restored.", "Showing an alert dialog that only educates, advertises, or repeats what the trigger already said." ], "critiqueQuestions": [ "What information in this dialog could reasonably make a user cancel?", "Can the action be safely undone instead of blocked beforehand?", "Does the destructive button say exactly what will happen?", "Is the safe path reachable without interpreting a double negative?", "Is the action frequent enough that this prompt will become automatic?", "Does the dialog name the object, count, permission, cost, recipient, or external system affected?" ], "relatedPatterns": [ "modal-dialog", "undo" ], "comparisons": [ "undo-vs-confirmation-dialog", "modal-vs-confirmation-dialog" ], "sourceIds": [ "apple-hig-alerts", "wai-aria-apg-alertdialog", "microsoft-windows-confirmations", "wai-aria-apg-dialog-modal" ] }, { "id": "confirmation-fatigue", "completionStatus": "complete", "name": "Confirmation fatigue", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Anti-pattern where repeated low-value confirmations train users to dismiss real risk prompts automatically", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "When products ask users to confirm too many routine actions, users learn that confirmations are meaningless friction. The prompt no longer creates attention when the consequence is genuinely destructive, costly, external, or hard to undo.", "solution": "Classify actions by reversibility, frequency, consequence, and recoverability; remove confirmations from routine recoverable actions, replace them with undo or feedback, and keep interruptive confirmation rare, specific, and consequence-bearing.", "uiGuidance": [ "Do not present the same modal confirmation for routine, reversible, low-risk, or high-frequency actions; reserve interruptive confirmation for consequences that can reasonably change a user's decision.", "Make the UI distinguish routine action feedback from genuine risk: use inline status, undo, warning text, disabled prevention, review, or clearer command placement instead of another generic Are you sure dialog." ], "uxGuidance": [ "Confirmation should reduce a specific mistake, not create a reflexive second click after every command.", "Audit prompt frequency, dismissal rate, reversibility, and consequence severity so users are not trained to ignore the one confirmation that actually matters." ], "uiExamples": { "good": [ "Archiving a message completes immediately with Message archived and Undo, while permanently deleting a workspace opens a specific destructive confirmation.", "A table separates Delete permanently from Archive and shows warning text near the dangerous command instead of confirming every row action." ], "bad": [ "Every Save, Dismiss, Filter, Archive, and Close action opens the same Are you sure? modal with OK and Cancel.", "A product asks for confirmation after the user already used a clear Delete permanently command, then asks again after the user typed the target name." ] }, "uxExamples": { "good": [ "A user archives ten low-risk notifications quickly, can undo the last archive, and still pauses when the only modal names permanent account deletion.", "A team removes confirmations from reversible cleanup actions and tracks fewer automatic OK clicks on the remaining destructive prompts." ], "bad": [ "A user clicks OK through a production delete prompt because the last 30 prompts all looked identical and protected harmless actions.", "A keyboard user must pass through a modal for every low-risk row action, slowing task completion without improving safety." ] }, "problemContext": [ "A product uses modal confirmations, alert dialogs, browser confirms, action sheets, or extra OK prompts for many commands in the same workflow.", "Many confirmed actions are frequent, reversible, local, low-risk, or already clear from the command label.", "The same prompt style is used for harmless actions and severe actions, so users cannot tell which prompt deserves attention.", "Teams may have added confirmations after incidents without checking whether undo, prevention, command placement, warning text, or review would target the real error better." ], "selectionRules": [ "Flag this anti-pattern when low-risk, reversible, or high-frequency actions repeatedly open modal confirmations.", "Flag it when confirmation copy is identical across different consequences, such as Are you sure? or Continue? for both routine dismiss and permanent deletion.", "Flag it when users see a second prompt after a stronger safeguard already proved intent, such as typed confirmation, high-impact review, or explicit destructive command wording.", "Use confirmation dialog only when the dialog adds object, scope, consequence, or recovery-limit information that could reasonably make the user cancel.", "Use destructive action confirmation when the action is a named destructive final commit with meaningful loss inventory.", "Use typed confirmation only for severe wrong-target risk, not as an extra ritual after every delete.", "Use undo when the action is frequent and the exact prior state can be restored before external effects occur.", "Use warning text when users only need consequence copy before they start the risky action.", "Use dangerous-action review when the issue is inspectable high-impact payload, evidence, side effects, or stale state rather than a yes-or-no confirmation.", "Prefer prevention by better placement, disabled-state explanation, previews, dependency blocking, permissions, or safer defaults when those remove the mistake without a prompt." ], "requiredStates": [ "Prompt inventory state showing which actions are confirmed, how often they occur, and what consequence each confirmation prevents.", "Routine reversible action state using status and undo instead of modal confirmation.", "Meaningful confirmation state reserved for uncommon destructive, costly, external, permission, or security-sensitive actions.", "Prompt suppression state where repeated low-risk confirmations are removed or replaced with less interruptive feedback.", "Escalation state where severe deletion, broad scope, or wrong-target risk routes to destructive or typed confirmation.", "Copy specificity state where remaining prompts name object, scope, consequence, and safe outcome.", "Habit signal state using telemetry or research such as very fast OK clicks, high dismissal rate, or repeated prompt chains.", "Bad spam state where every Save, Close, Filter, Archive, Dismiss, or Navigate command asks Are you sure.", "Bad double-protection state where confirmation, typed phrase, and undo all stack on the same low-risk action.", "Bad false-safety state where prompts remain but the system cannot undo, prevent, or describe the real consequence." ], "interactionContract": [ "Each confirmation must have a documented risk, consequence, and reason it is better than undo, prevention, warning text, review, or clearer command placement.", "The same user path should not show repeated confirmations for the same consequence unless the second step adds materially new information.", "Routine recoverable actions should complete with clear feedback and recovery instead of blocking the action first.", "Remaining confirmations must differ visually and textually by consequence, target, and final action label rather than using generic OK or Continue.", "Suppression rules should consider action frequency, reversibility, role, environment, object scope, and whether the user has already reviewed the consequence.", "When a prompt is removed, the replacement recovery or prevention path must be visible, keyboard reachable, and honest about what can be restored.", "Analytics, usability testing, support reports, and incident reviews should be used to check whether confirmations are read or merely dismissed." ], "implementationChecklist": [ "Inventory all confirmation prompts in the workflow and tag each by action, frequency, reversibility, external effects, consequence severity, and existing recovery.", "Remove modal confirmation from routine save, close, filter, dismiss, archive, hide, reorder, and delete-to-trash actions when undo or status feedback is sufficient.", "Replace low-risk confirmations with object-specific feedback, undo, restore, inline validation, disabled explanation, preview, or better command grouping.", "Keep or add confirmation only where object, count, scope, cost, permission, external recipient, recovery limit, or legal consequence can be shown before commitment.", "Use destructive action confirmation, typed confirmation, dangerous-action review, or human approval gate only when their stronger contract matches the consequence.", "Write remaining prompt copy with the affected object, consequence, safe action, and final action; avoid OK, Yes, No, Continue, and repeated Are you sure wording.", "Measure fast dismissals, prompt chains, repeated confirmations per task, cancellation rate, undo use, support incidents, and whether users can recall what they confirmed.", "Test keyboard and screen-reader flow for both removed prompts and remaining prompts so fewer dialogs do not hide recovery from non-pointer users." ], "commonMisuses": [ "Adding a confirmation after every user mistake without asking whether the mistake was reversible.", "Using one generic confirmation component for every action from closing a panel to deleting a workspace.", "Stacking warning text, confirmation dialog, typed confirmation, and undo for a low-risk action.", "Keeping prompts because they feel safer even though users dismiss them unread.", "Removing prompts without adding the undo, restore, status, or prevention path that made removal safe.", "Treating cancellation rate alone as proof that a prompt is useful without checking task interruption and habituation." ], "critiqueQuestions": [ "What specific mistake does this confirmation prevent?", "How often will a user see this prompt in one normal task?", "Can the exact prior state be restored with undo instead of blocking the action?", "Does the prompt add new consequence information beyond the trigger label?", "Are severe prompts visually and textually distinguishable from routine prompts?", "Are users clicking through so fast that they probably are not reading?", "Can the risk be reduced by command placement, disabled explanations, previews, or safer defaults instead of confirmation?" ], "relatedPatterns": [ "confirmation-dialog", "destructive-action-confirmation", "typed-confirmation", "undo", "warning-text", "dangerous-action-review", "modal-dialog", "toast-notification" ], "comparisons": [ "confirmation-fatigue-vs-confirmation-dialog-vs-destructive-action-confirmation-vs-undo-vs-warning-text-vs-dangerous-action-review" ], "sourceIds": [ "microsoft-windows-confirmations", "apple-hig-alerts", "material-design-snackbar", "wai-aria-apg-alertdialog", "govuk-warning-text-component" ] }, { "id": "confirmation-page", "completionStatus": "complete", "name": "Confirmation page", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Final endpoint page after a transaction is complete", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users finish a transaction but do not know whether it is complete, what reference proves it, what will happen next, how long it will take, who to contact, or how to recover the receipt later.", "solution": "Route successful final submit to a dedicated confirmation page that proves completion, gives any needed reference or submitted details, explains next steps and timing, provides contact or tracking paths, and offers a sensible way to keep or revisit the record.", "uiGuidance": [ "Render a full page after commit with a prominent completion panel, a page heading that names what finished, a reference or receipt when users need one, and a clear section for what happens next.", "Place contact, tracking, save, print, feedback, and related-service links below the completion panel in a restrained hierarchy so the receipt remains the primary page purpose." ], "uxGuidance": [ "Use a confirmation page when the transaction or service journey has ended and users need durable proof, reassurance, next-step timing, or a record they can bookmark, print, quote, or revisit.", "Define the post-commit lifecycle: users should not see pre-submit Change links, but they should know how to track, amend, cancel, contact support, start another transaction, or recover when a bookmarked receipt can no longer be shown." ], "uiExamples": { "good": [ "A grant application page says Application complete, shows reference APP-48291, lists what happens next within 5 working days, and offers Save record, Track application, and feedback links.", "A booking complete page shows the appointment location and time under the success panel, explains that an email was sent, and keeps related links secondary." ], "bad": [ "A submitted application only redirects to a dashboard toast that says Done, with no reference, receipt, or next-step details.", "A green completion page contains six unrelated cards, a marketing banner, edit links, and no clear statement of whether the transaction is finished." ] }, "uxExamples": { "good": [ "A user copies the reference, saves the receipt, follows Track application, and later returns from a bookmark to the same confirmation details or a helpful tracking fallback.", "A user who needs to correct submitted details sees contact or amend guidance that matches the service rules rather than pre-submit Change links." ], "bad": [ "A user closes the page after seeing a transient message and later cannot prove the payment or application happened.", "A permission failure is displayed as a successful confirmation page, so the user waits for a next step that will never happen." ] }, "problemContext": [ "The user has completed a transaction such as applying, booking, paying, submitting a survey, publishing, closing an account, or sending a consequential request.", "The action is committed enough that pre-submit editing is no longer the main model, but the service may still need track, amend, cancel, or contact routes.", "The user may need to show proof later, quote a reference number, wait for a response, prepare for an appointment, or understand that there is nothing more to do.", "The page may be bookmarked, printed, screenshotted, emailed, or reopened from browser history, so the service needs a helpful return behavior." ], "selectionRules": [ "Choose confirmation page when the transaction is finished and the user needs endpoint proof plus what happens next.", "Include a reference number only when it has a real support, tracking, payment, booking, or audit use; explain what it is for and whether users should keep it.", "State the next responsible party, expected timing, and whether the user needs to do anything else.", "Summarize submitted details when they help the user verify an appointment, payment, booking, application, or survey response after commit.", "Provide contact, tracking, amend, cancel, save, print, email receipt, feedback, or related-service links only when they support the completed transaction.", "Use success confirmation instead when the user remains in the same task and the success proof belongs near the changed object.", "Use review before submit instead when users still need Change links and final pre-commit inspection.", "Use notification banner instead when a previous-page action succeeded but the current journey continues.", "Use error state, service unavailable page, permission denied state, or error summary instead when completion did not happen.", "Avoid filling the endpoint with unrelated promotional content or multiple equal calls to action that obscure the completion message." ], "requiredStates": [ "Submitted state immediately after authoritative commit routes to the confirmation page.", "Completion panel state with success heading and reference or receipt details when available.", "Next-step state that names timing, responsible party, contact route, and whether any user action remains.", "Record-keeping state with save, print, email, copy reference, or downloadable receipt when users may need proof.", "Submitted-detail summary state for bookings, payments, survey responses, or applications where details matter after commit.", "Post-commit correction state that replaces pre-submit Change links with amend, cancel, track, or contact guidance.", "Bookmarked-return state that either restores the receipt or provides a helpful tracking or support path.", "Start-again state for users who need to begin another transaction without confusing it with the completed one.", "Failure handoff state where uncommitted, denied, invalid, or unavailable outcomes do not render as completion." ], "interactionContract": [ "The page appears only after the final action succeeds according to the authoritative system of record.", "The H1 or panel title names the finished transaction rather than saying only Success.", "Reference numbers, timestamps, submitted details, and next steps are generated from canonical committed data.", "Pre-submit Change links are removed after commit; any correction path uses explicit amend, cancel, contact, or track rules.", "Save, print, email, copy, feedback, and tracking actions preserve the completion context and keep users on or return them to the receipt when appropriate.", "Starting a new transaction clears the old flow state while leaving the completed reference accessible through tracking or history if supported.", "Returning through a bookmark does not show stale private data without authorization; if the receipt cannot be restored, the page explains how to track or contact the service." ], "implementationChecklist": [ "Identify the authoritative commit event, receipt identifier, user-visible reference, timestamp, submitted details, and next-step owner before rendering the page.", "Write the completion heading as a finished outcome, such as Application complete, Booking complete, Payment sent, or Response submitted.", "Show the reference in a durable readable form and explain why users may need it.", "Add next-step content with concrete timing, responsible organization or system, and what the user should do if nothing happens.", "Provide a record-keeping route such as print, save PDF, email receipt, copy reference, or tracking link when the receipt is useful later.", "Remove review-page editing controls and replace them with post-submit amend, cancel, contact, or support guidance.", "Handle browser Back, reload, refresh, duplicate submit, bookmarked return, expired sessions, and unauthenticated access without creating a second transaction.", "Test mobile layout, print styles, screen reader heading order, focus after submit, long reference numbers, repeated applications, privacy-sensitive receipts, and unavailable tracking." ], "commonMisuses": [ "Showing a toast or local success strip as the only proof of a completed transaction.", "Using a confirmation page before the transaction is committed.", "Leaving Change links active after final submit.", "Showing a reference number without explaining whether users need to keep it.", "Omitting what happens next or when the user should expect a response.", "Using a green completion page for permission denial, service failure, or validation recovery.", "Adding so many unrelated links and cards that the completion message no longer reads as the page purpose.", "Breaking bookmarked returns with a blank or hostile expired-session page." ], "critiqueQuestions": [ "What system event proves the transaction is complete?", "What reference, receipt, timestamp, or submitted details will users need later?", "What exactly happens next, who owns it, and when should the user expect it?", "Is the page still offering pre-submit editing after commit?", "How can users save, print, email, copy, track, amend, cancel, or contact support from this endpoint?", "What happens if users bookmark, refresh, go Back, submit twice, or return after their session expires?" ], "relatedPatterns": [ "success-confirmation", "review-before-submit", "notification-banner", "confirmation-dialog", "error-summary", "inline-message" ], "comparisons": [ "confirmation-page-vs-success-confirmation-vs-review-before-submit-vs-notification-banner" ], "sourceIds": [ "govuk-confirmation-pages-pattern", "nhs-confirmation-page-pattern", "ons-confirmation-page-pattern", "govuk-check-answers-pattern" ] }, { "id": "conflict-resolution", "completionStatus": "complete", "name": "Conflict resolution", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Guided workflow for reviewing and committing conflict decisions", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can make the wrong decision or lose work when a product detects competing valid changes but provides no guided way to inspect every affected value, choose or merge outcomes, defer unsafe cases, and review the final result before commit.", "solution": "Provide a conflict resolution workflow that preserves every version, walks users through each conflict, records a decision per conflicting unit, previews the final resolved value, blocks commit until required decisions are complete, and routes unsupported or high-risk conflicts to manual resolution.", "uiGuidance": [ "Show a durable resolution workspace that lists every unresolved conflict, exposes the current conflict, names each version source, and separates choose-local, choose-remote, merge, save-copy, skip, and commit actions.", "Keep the resolved preview, unresolved count, discarded-change summary, and final commit action visually distinct so users can review the combined result before it replaces, publishes, syncs, or commits anything." ], "uxGuidance": [ "Use conflict resolution after conflict detection when users must make one or more explicit decisions before a record, document, branch, import, or synced object can continue.", "Guide users through conflicts in a stable order, preserve every unchosen value until commit, support safe deferral or manual escalation, and leave an audit trail that explains what was kept, merged, copied, or discarded." ], "uiExamples": { "good": [ "A field report resolver shows 2 of 3 conflicts remaining, displays Your offline value and Mina's server value for the current field, offers Keep local, Keep server, Merge both, Save copy, and shows a reviewed result before Commit resolutions.", "A document conflict review lists conflicting paragraphs in order, highlights only the overlapping text, lets the user accept or reject each recovered change, and shows a final summary before returning to editing.", "An import update resolver groups row conflicts by account, shows incoming and existing values, lets reviewers choose per field, skips unresolved rows, and exports skipped rows after commit." ], "bad": [ "A conflict page has one Accept recommended button for all fields and no way to inspect discarded values.", "A resolver lets users click Commit while some conflicts are still unresolved and hides which side will be lost.", "A merge screen says Ours and Theirs without branch, owner, timestamp, row, or field labels." ] }, "uxExamples": { "good": [ "A user resolves the supervisor comment by merging both versions, keeps the server contact number, saves the local safety note as a copy, reviews the final report, then commits with an audit summary.", "A reviewer opens six import conflicts, filters to high-risk rows, resolves three, exports the remaining unresolved rows, and commits only the reviewed decisions.", "A developer uses a browser merge tool for simple text conflicts, sees one binary file cannot be resolved there, downloads both versions, and leaves the merge blocked until manual resolution returns." ], "bad": [ "The system silently resolves all conflicts by newest timestamp and only shows a success toast.", "Users repeatedly press Retry because the workflow never explains that a choice between valid values is required.", "A bulk resolution commits every conflict before a reviewer sees the final combined value or the discarded data." ] }, "problemContext": [ "A conflict state already exists because two or more valid edits overlap in the same field, paragraph, row, file, branch hunk, draft, or synchronized object.", "More than one conflict may need to be resolved before the user can submit, publish, sync, import, save, or merge.", "The product must preserve local, remote, collaborator, source-branch, target-branch, existing-row, or incoming-row values until a decision is committed.", "Some conflicts are simple choose-one-side decisions, while others require manual merge, save-copy, skip, owner assistance, or a different tool." ], "selectionRules": [ "Choose conflict resolution when users need a workflow for deciding, merging, skipping, or committing one or more conflicts after they have been detected.", "Use conflict state for the persistent status surface that says a conflict exists; conflict resolution is the active review and decision workflow that follows.", "Use autosave recovery when the main issue is preserving local work after failed or uncertain saving and no explicit side-by-side decision has started.", "Use draft state when the main task is managing unpublished work, not deciding between overlapping valid versions.", "Use review-before-submit when users are checking their own captured answers before final submission; use conflict resolution when another source, version, branch, or system has a competing value.", "Resolve at the smallest unit the user can judge: field, row, line, paragraph, file, branch hunk, setting, or record.", "Offer only decisions that are true for the data type: keep local, keep server, accept incoming, keep existing, merge both, save copy, skip, discard, or open manual tool.", "Block final commit when required conflicts remain unresolved, when a resolved preview is invalid, or when unsupported files require a manual route.", "Show a final review summary before destructive commit, including counts resolved, skipped, copied, discarded, and sent to manual resolution.", "After commit, update the source object, clear the conflict badge, and leave a retrievable history or export of decisions where the domain requires it." ], "requiredStates": [ "Conflict list state with unresolved count and current conflict position.", "Side-by-side or inline comparison state for the current conflict.", "Choose local, choose remote, choose existing, or choose incoming state.", "Manual merge edit state with unresolved markers.", "Save copy or keep both state for preserving a rejected version.", "Skip or defer state for conflicts that cannot be decided now.", "Unsupported or manual-tool-required state.", "Resolved preview state showing the value that will be committed.", "Review all decisions state with kept, discarded, copied, skipped, and unresolved counts.", "Committed state with audit trail, version history, or exported resolution report." ], "interactionContract": [ "The resolver opens from a known conflict and keeps users oriented to the affected object, conflict number, and total unresolved count.", "Each decision records which source value survives, which value is copied or discarded, and whether the resolved value is complete.", "Next and Previous conflict controls move through unresolved items without losing decisions already made.", "Manual merge preserves both source values until the merged value passes validation or the user explicitly cancels.", "Save copy or keep both creates a findable artifact and does not claim the conflict is solved unless the primary object has a committed value.", "Final commit is disabled or intercepted while required conflicts remain unresolved, while previews are invalid, or while manual-tool items are open.", "The committed result clears conflict indicators only after the server, repository, import job, or document accepts the resolved version.", "The workflow exposes undo, history, or exported decisions when data loss, collaboration, compliance, publication, or code review risk is high." ], "implementationChecklist": [ "Model conflicts as a list of units with base value, local or incoming value, remote or existing value, owner, timestamp, field or file path, decision, preview, validation, and commit state.", "Keep conflict-state detection separate from the resolver route so users can reopen unfinished decisions.", "Persist in-progress decisions through reload, route changes, reauthentication, and reconnect when policy permits.", "Implement choose-one-side, merge, save-copy, skip, cancel, next, previous, review, and commit controls with explicit labels.", "Validate merged values before commit and keep unresolved markers visible until every required choice is made.", "Handle bulk conflict sets with filters, progress, keyboard navigation, and item-level review rather than only a global accept action.", "Record resolution metadata for collaborative documents, regulated records, imports, source control, and published content.", "Test multi-conflict navigation, partial decisions, reload recovery, unsupported file types, permission changes, validation failure after merge, skipped items, final commit failure, keyboard access, and screen reader status updates." ], "commonMisuses": [ "Marking conflicts resolved before the user reviews the surviving value.", "Using a single Accept all button without showing affected fields or discarded values.", "Letting users commit with required conflicts still unresolved.", "Using ambiguous Ours and Theirs labels without branch, owner, device, or timestamp context.", "Hiding skipped or save-copy artifacts after commit.", "Treating conflict resolution as retry, reload, or last-write-wins.", "Clearing the conflict badge before the resolved version is accepted by the server, repository, or document." ], "critiqueQuestions": [ "How many conflicts remain, and where is the user in the resolution sequence?", "What exact value will be committed if the user chooses each action?", "Which rejected values are copied, exported, discarded, or still recoverable?", "Can users resolve some conflicts and safely defer or export the rest?", "What prevents commit while conflicts remain unresolved or previews are invalid?", "What history, audit trail, or undo path remains after the resolved version is accepted?" ], "relatedPatterns": [ "conflict-state", "autosave-recovery", "review-before-submit", "draft-state", "sync-state", "error-state", "inline-edit", "notification-center" ], "comparisons": [ "conflict-resolution-vs-conflict-state-vs-review-before-submit-vs-autosave-recovery" ], "sourceIds": [ "atlassian-confluence-concurrent-editing", "microsoft-office-coauthoring-conflicts", "gitlab-merge-conflicts" ] }, { "id": "conflict-state", "completionStatus": "complete", "name": "Conflict state", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Competing-version resolution state", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can lose trust and data when two or more valid edits target the same object or location and the product cannot safely decide which change should win, merge, or be discarded.", "solution": "Present a conflict state that preserves every competing value, names the source and time of each version, highlights the exact overlap, offers explicit resolution actions, and shows the resulting value before committing destructive or collaborative changes.", "uiGuidance": [ "Show both competing versions near the affected object, field, paragraph, file, row, or branch with source labels such as Your edit, Server version, Mina's edit, Target branch, and Current published value.", "Expose resolution actions that state their effect, such as Keep mine, Keep theirs, Merge manually, Save a copy, Continue editing, Overwrite, Discard my changes, Accept change, and Reject change." ], "uxGuidance": [ "Use conflict state when multiple valid changes overlap and the system needs a human, rule, or review workflow to decide what survives without losing work silently.", "Preserve each version, explain why automatic merge was unsafe, guide users through the smallest conflicting unit, and make the post-resolution result reviewable before committing." ], "uiExamples": { "good": [ "A field report says Conflict on supervisor comment, shows Your offline edit from 11:06 beside Server edit by Mina at 11:07, and offers Keep mine, Keep server, and Merge comment.", "A document editor highlights the paragraph changed by Alice and Bob, shows last edit times, and offers Continue editing, Overwrite, or Cancel with clear loss copy.", "A code review conflict view labels source and target branch lines, highlights the conflict block, and lets users choose one side or edit the merged result." ], "bad": [ "A save banner says Something went wrong and only offers Retry after another user changed the same field.", "A merge UI uses Ours and Theirs without branch names, timestamps, or a preview of the chosen result.", "A conflict copy appears in a synced folder without explaining which file is current or which copy needs review." ] }, "uxExamples": { "good": [ "A user tries to sync an offline field report, reviews only the two changed fields, merges one comment, keeps the server contact number, and commits a resolved version.", "A coauthoring document preserves local edits, opens conflict review, lets the user navigate each tracked conflict, then returns to the live document after all decisions are made.", "A pull request blocks merge, lists conflicted files, allows simple line conflicts to choose a side, and sends complex files to inline editing or local resolution." ], "bad": [ "The app silently keeps the newest server value and deletes the user's local note.", "A conflict is treated like a network retry, so the user keeps pressing Retry even though a decision is required.", "A bulk accept action resolves every conflict without a review summary or a way to inspect discarded values." ] }, "problemContext": [ "The product supports concurrent editing, offline editing, file sync, branch merging, record updates, draft publishing, import updates, or background sync.", "Two or more actors, devices, branches, jobs, or systems can change the same field, paragraph, file, record, or setting before one change is accepted.", "Automatic merge may be impossible or unsafe because changes overlap, carry business meaning, affect collaborators, or require human judgment.", "Local work, collaborator work, target branch changes, or server values must be preserved until a resolution decision is made." ], "selectionRules": [ "Choose conflict state when two or more valid versions overlap and a choice, merge, save-copy, discard, or policy resolution is required.", "Show the conflict at the smallest understandable unit: field, sentence, paragraph, row, file, setting, branch hunk, or whole record.", "Label each side with source, owner, timestamp, device, branch, version, or system of record instead of ambiguous side names.", "Preserve both versions until resolution is committed, including local work that failed to upload or collaborator work that saved first.", "Offer resolution actions that match the data type: choose one side, combine text, accept or reject tracked changes, save a copy, keep both files, edit manually, or cancel.", "Show a preview or resolved value before committing when the conflict has business, legal, financial, medical, publication, code, or collaboration risk.", "Use sync state when the conflict is only a status inside a broader queue and no side-by-side resolution is required yet.", "Use draft state when the main task is managing an unpublished version rather than deciding between overlapping changes.", "Use error state when a save, load, or validation failed without another valid version to preserve or compare.", "Escalate to manual resolution when automatic or one-click resolution would hide context, discard data, or exceed product limits." ], "requiredStates": [ "No conflict state after automatic safe merge.", "Conflict detected state naming affected object and source versions.", "Side-by-side or inline comparison state for overlapping values.", "Choose mine or choose theirs state with preview.", "Manual merge state for combining text, structured values, or code.", "Save copy or keep both state when overwriting would lose work.", "Discard local change confirmation state.", "Resolved pending review state before commit when risk is high.", "Committed resolved state with audit trail or version history.", "Cannot resolve here state when the conflict requires another tool, permission, file type, or owner." ], "interactionContract": [ "Conflict detection stops silent overwrite and keeps every competing value recoverable.", "The surface states why automatic merge was not performed and what changed after the user started editing or syncing.", "Each resolution action states whose change is kept, whose change is removed, and whether the result will be saved, published, synced, or committed.", "Users can navigate between multiple conflicts, see progress through the list, and return to unresolved items.", "Manual merge preserves editing focus and shows unresolved markers until all required decisions are complete.", "Save copy or keep both keeps local data recoverable without claiming the conflict was resolved.", "After resolution, the product shows the final value, version, or commit before or immediately after the change is applied.", "Permission, file type, binary, branch protection, locked record, and policy limits route users to the correct manual or owner-assisted path." ], "implementationChecklist": [ "Model conflict state separately from failed save, unsaved changes, draft, and sync progress.", "Store source values, base version, local version, remote version, actor, timestamp, device or branch, and resolution decision.", "Determine conflict granularity: field, block, row, document section, file, branch hunk, or full object.", "Provide comparison UI with stable labels, highlighted overlaps, untouched context, and enough surrounding content for judgment.", "Implement explicit actions for keep mine, keep theirs, merge manually, save copy, discard, accept, reject, cancel, and commit where relevant.", "Prevent duplicate submission or background overwrite while a conflict is unresolved.", "Record resolution audit information for collaborative, regulated, financial, code, or published content.", "Test simultaneous edits, offline return, stale browser tabs, autosave conflicts, binary file conflict copies, permission changes, bulk conflict resolution, undo limits, and screen reader navigation." ], "commonMisuses": [ "Treating a conflict as a simple retryable save error.", "Letting newest timestamp win without preserving the losing value.", "Using ambiguous labels such as ours and theirs without explaining source and target.", "Showing a conflict count without the affected fields, values, owners, or timestamps.", "Resolving all conflicts with one default choice before users inspect discarded data.", "Hiding conflict copies or recovered edits in a separate location without linking them from the affected object.", "Merging structured or regulated data automatically when business meaning must be reviewed." ], "critiqueQuestions": [ "What are the competing versions, who created them, and when?", "What exact field, line, paragraph, file, or record overlaps?", "What value will survive after each action?", "Can users save or export their local work before discarding it?", "Can the conflict be safely merged automatically, or must a human review it?", "What audit trail, version history, or undo path remains after resolution?" ], "relatedPatterns": [ "sync-state", "draft-state", "error-state", "inline-edit", "review-before-submit", "autosave-form", "notification-center" ], "comparisons": [ "conflict-state-vs-sync-state-vs-draft-state-vs-error-state" ], "sourceIds": [ "atlassian-confluence-concurrent-editing", "microsoft-office-coauthoring-conflicts", "gitlab-merge-conflicts" ] }, { "id": "consent-prompt", "completionStatus": "complete", "name": "Consent prompt", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Specific opt-in decision for optional data use, participation, communication, sharing, or training", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users are often asked to agree to optional data use, marketing, research, AI training, personalization, or sharing at moments where the purpose, data, consequences, and withdrawal route are unclear, making the recorded agreement weak and the experience untrustworthy.", "solution": "Provide a consent prompt that is specific, informed, freely chosen, affirmative, granular where needed, easy to decline, easy to withdraw, and connected to a durable consent record that matches the visible choice.", "uiGuidance": [ "Render a consent prompt as a focused opt-in decision that names the requester, purpose, data involved, optionality, benefit, consequence of declining, withdrawal route, and consent record before the user chooses.", "Use equal-level accept and decline controls, granular purpose choices when purposes differ, clear affirmative action for opt-in, and a confirmation state that records purpose, version, timestamp, and withdrawal path." ], "uxGuidance": [ "Use consent prompt when the product needs the user to knowingly agree to a specific optional data-processing purpose such as marketing, research participation, AI training, personalization, partner sharing, or sensitive-data use.", "Ask at a moment when the user understands the task and value, keep the service usable when consent is declined where possible, and make withdrawal as visible and easy as the original opt-in." ], "uiExamples": { "good": [ "A research signup screen asks whether the user consents to being contacted for follow-up interviews, names the research team, shows what contact data is used, offers Yes and No thanks buttons, and links to withdrawal.", "An AI writing tool asks whether the user wants workspace snippets used to improve future suggestions, shows included data types, keeps the default off, and records the consent version after opt-in." ], "bad": [ "A modal says By continuing you agree to personalized offers and partner sharing, with a large Continue button and a small privacy policy link.", "A form checkbox is preselected for marketing, research, and product analytics together, with no separate decline or withdrawal route." ] }, "uxExamples": { "good": [ "A user declines partner sharing and can still complete checkout; the service records no partner-sharing consent and shows how to change the choice later.", "A user consents to a beta research study, sees what data will be reviewed, receives a saved confirmation, and later withdraws from the account privacy page with the same purpose label." ], "bad": [ "A user clicks Next to finish onboarding and unknowingly opts into marketing because the consent copy was bundled into the terms paragraph.", "A user accepts a vague improve our service prompt, then discovers their messages were used for AI training and cannot find where to revoke consent." ] }, "problemContext": [ "The prompt may appear during onboarding, checkout, account creation, product settings, research signup, AI feature activation, beta enrollment, marketing signup, partner integration, or sensitive-data workflow.", "The requester may need evidence of who asked, what purpose was presented, what data was named, what version of copy was shown, what the user chose, and whether the user later withdrew.", "Consent may be optional while the core task continues, or it may be necessary for a separate optional feature that stays unavailable after refusal.", "The prompt must not rely on silence, inactivity, preselected choices, hidden refusal, bundled terms, confusing double negatives, or consent collected after processing has already started." ], "selectionRules": [ "Choose consent prompt when the user must actively opt in to a specific optional data use, communication, study, sharing arrangement, personalization feature, AI training use, or sensitive-data processing purpose.", "Use cookie banner when the choice is specifically about non-essential cookies, pixels, local storage, advertising tags, analytics tags, or similar device storage.", "Use preference center when users are reviewing or changing multiple account preferences after the initial consent moment.", "Use notification preferences when users are choosing message channels, topics, frequency, or subscription state rather than consenting to a separate data-processing purpose.", "Use permission sharing when the decision grants another user, guest, team, or link access to an object.", "Use human approval gate when the user approves or rejects a proposed action before execution rather than consenting to ongoing optional processing.", "Use legal acceptance when the task is accepting terms or a contract; do not hide optional consent inside legal acceptance copy.", "Ask close to the feature or data use so the user understands why the choice appears, but before optional processing begins.", "Offer separate granular consent controls for separate purposes such as marketing, research, personalization, partner sharing, and AI training.", "Refresh consent when purpose, data type, requester, partner, retention period, or consequence changes beyond what the user originally agreed to." ], "requiredStates": [ "Pre-consent state with optional processing off and the core task still understandable.", "Specific purpose state naming the requester, data, purpose, benefit, and optionality.", "Accept consent state with clear affirmative action and saved consent record.", "Decline consent state that keeps eligible core workflow available and records refusal without penalty.", "Granular consent state for multiple independent purposes.", "Explicit consent state for high-sensitivity use requiring a clear statement or checkbox next to the statement.", "Confirmation state showing the saved purpose, version, timestamp, and withdrawal route.", "Withdrawal state where users can revoke consent as easily as they gave it.", "Renewal state when purpose, data, requester, or copy version changes.", "Expired or stale consent state where optional processing stops until renewed.", "Permission-limited or under-age state where the user cannot provide consent directly.", "Mobile compact state where purpose, choices, and withdrawal route remain visible." ], "interactionContract": [ "The prompt appears before optional processing begins and states exactly what agreeing enables.", "Accept requires a deliberate action such as pressing a labelled button, checking an unchecked statement, or selecting an opt-in setting.", "Decline is reachable at the same decision level and does not look disabled, hidden, or punitive.", "Independent purposes are not bundled into one broad agreement unless they are truly inseparable.", "The prompt explains whether the core task continues after refusal and what optional feature remains unavailable.", "Saving a choice updates the runtime state and writes a consent record containing purpose, copy version, requester, timestamp, data type, and withdrawal state.", "Withdrawing consent stops future processing based on that consent and leaves a clear record of the withdrawal.", "Keyboard and screen-reader users can read the purpose, compare choices, make or decline a choice, and later find withdrawal controls without losing task context." ], "implementationChecklist": [ "Identify the requester, controller or product area, data type, processing purpose, retention expectation, and whether consent is the correct basis for the decision.", "Write prompt copy in plain language that names the user benefit and the organizational use without vague phrases such as improve your experience.", "Keep optional processing off by default and do not preload the data use before the prompt is answered.", "Provide accept and decline actions with comparable prominence and effort.", "Split independent purposes into granular choices and keep every optional choice off until selected.", "Record purpose, requester, copy version, data type, timestamp, user, action, source surface, and withdrawal state.", "Provide a stable withdrawal route and test that withdrawal changes the same runtime and record used by the prompt.", "Test first ask, decline, accept, granular save, explicit consent, renewal, withdrawal, mobile layout, keyboard order, screen-reader naming, and evidence export." ], "commonMisuses": [ "Treating continued use, scrolling, closing, or inactivity as consent.", "Using preselected checkboxes for optional processing.", "Bundling marketing, research, partner sharing, personalization, and AI training into one broad choice.", "Hiding decline behind a settings link or making refusal look unsafe.", "Starting optional processing before the consent prompt is answered.", "Using a privacy-policy link as the only explanation of purpose.", "Recording only a boolean value without purpose, version, requester, or withdrawal state.", "Making withdrawal harder than giving consent." ], "critiqueQuestions": [ "What specific data use is the user agreeing to, and is it optional?", "Can the user decline with comparable effort and continue the eligible core task?", "Are separate purposes split into separate choices?", "Does the prompt name the requester, data type, purpose, consequence, and withdrawal route?", "Is optional processing blocked until affirmative consent exists?", "What evidence proves which prompt version the user saw and what they chose?", "Can the user withdraw consent later from a stable route, and does withdrawal change runtime behavior?" ], "relatedPatterns": [ "cookie-banner", "preference-center", "notification-preferences", "permission-sharing", "human-approval-gate", "destructive-action-confirmation", "typed-confirmation", "warning-text" ], "comparisons": [ "consent-prompt-vs-cookie-banner-vs-preference-center-vs-notification-preferences-vs-permission-sharing-vs-human-approval-gate" ], "sourceIds": [ "ico-valid-consent", "ico-obtain-record-manage-consent", "edpb-consent-summary-2026", "nng-permission-requests", "android-runtime-permissions" ] }, { "id": "context-menu", "completionStatus": "complete", "name": "Context menu", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Location-invoked contextual command menu", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Objects often have secondary commands that experienced users expect near the object, but hiding commands behind pointer-only right click or stale context can make actions undiscoverable, target-ambiguous, or inaccessible.", "solution": "Provide a compact command menu that opens from the invoked object or selection by pointer and keyboard context-menu requests, keeps the target visibly selected, moves focus into the menu, supports menu keyboard behavior, and returns focus to the target on close.", "uiGuidance": [ "Render a context menu as a compact command menu anchored to the object, selection, pointer position, or focused item that invoked it, with clear item labels, disabled reasons, separators, and destructive separation.", "Keep context-menu content to commands or command-like links that apply to the invoked target; do not turn it into a form, preview panel, navigation drawer, or general overflow bucket." ], "uxGuidance": [ "Use a context menu when users need fast object-specific commands from a secondary invocation path such as right click, long press, context-menu key, or Shift+F10.", "Make the same target, command eligibility, keyboard focus, dismissal, and focus return work for pointer and keyboard invocation, and keep important commands available through visible routes too." ], "uiExamples": { "good": [ "A file row opens a context menu at the selected row with Open, Rename, Duplicate, Download, Archive, and Delete separated at the end.", "A canvas shape opens a context menu at the pointer with Bring forward, Send backward, Duplicate, Lock, and Delete shape, while the selected shape remains highlighted." ], "bad": [ "Right clicking a row opens a menu beside the toolbar and still shows actions for the previously selected row.", "A hidden context menu is the only place to find primary commands such as Save, Submit, or Continue." ] }, "uxExamples": { "good": [ "Right click on Forecast.xlsx opens commands for that file, Arrow keys move through items, Escape closes the menu, and focus returns to the file row.", "Shift+F10 on the focused file opens the same eligible commands at the row, including disabled Export with a reason and Delete routed to review." ], "bad": [ "Keyboard invocation opens at the top-left corner with no visible relationship to the focused object.", "Long press opens commands that differ from right click, so users cannot predict which action set applies." ] }, "problemContext": [ "A file, row, canvas object, map item, text selection, card, or selected set has several commands that are useful but not always worth visible space.", "Users may invoke commands through right click, secondary click, long press, context-menu key, Shift+F10, or another platform-specific request.", "The target object, selected set, pointer location, permission state, and object state determine which commands are available.", "Important commands still need visible or documented access because context menus are secondary and less discoverable." ], "selectionRules": [ "Choose context menu when commands are specific to the object, selection, or location where the user invoked the menu.", "Use action menu when the main work is designing the command taxonomy, grouping, disabled reasons, destructive handoff, and scope labels independent of invocation method.", "Use menu button when users need a visible named trigger for the same short command list.", "Use popover when the anchored layer needs contextual information, controls, or light editing instead of menuitem command activation.", "Use visible buttons for primary, frequent, safety-critical, or onboarding commands that users should not have to discover through secondary invocation.", "Use command palette when commands are product-wide, searchable, shortcut-driven, or not tied to the current object.", "Use native browser or platform context menu when the product does not need custom object-specific commands.", "Use a confirmation dialog, undo, or review flow after high-risk context-menu commands rather than running them silently." ], "requiredStates": [ "Resting object or selection state before invocation.", "Pointer-invoked open state anchored to the object or pointer coordinate.", "Keyboard-invoked open state anchored to the focused object or selection, not stale pointer coordinates.", "Visible target state showing which object or selected set commands will affect.", "Menu focus state with active item, Arrow key movement, Enter or Space activation, and Escape dismissal.", "Disabled or unavailable item state with reason when the user can recover.", "Destructive item state separated from safe commands and routed to review or recovery.", "Dismissed state that returns focus to the invoking object or selected set.", "Target changed or selection changed state that closes or recalculates the command set.", "Touch or long-press state with equivalent command availability where the platform supports it." ], "interactionContract": [ "The menu opens only for the object, selection, or location that invoked it.", "Pointer and keyboard invocation expose the same applicable commands for the same target.", "The invoked target remains highlighted, focused, or otherwise visibly identified while the menu is open.", "Opening moves focus into the menu or sets an active descendant so Arrow keys operate inside the command list.", "Escape, outside click, scroll away, or target removal closes the menu without running a command.", "Safe activation closes the menu and reports what happened to the target.", "High-risk activation moves to confirmation, undo, restore, or review with the affected target named.", "Focus returns to the invoking target or a logical replacement after dismissal or activation.", "The context menu is not the only route to important commands.", "The menu content stays command-like and does not contain forms, pickers, embedded editors, or long explanatory panels." ], "implementationChecklist": [ "Define which objects or selections can invoke a context menu and which commands apply to each state.", "Handle pointer secondary-click, keyboard context-menu key, Shift+F10, and touch or long-press where supported.", "Anchor pointer menus to the invoked object or pointer and keyboard menus to the focused target.", "Keep the target visibly selected or focused while the menu is open.", "Use menu roles and menuitem semantics only when implementing full menu keyboard behavior.", "Implement Arrow keys, Home, End, typeahead when useful, Enter, Space, Escape, outside dismissal, and focus return.", "Recalculate or close the menu if selection, target state, permission, or viewport position changes.", "Expose unavailable commands with reasons when users can act on the reason.", "Keep primary commands visible elsewhere and document advanced shortcuts where appropriate.", "Test repeated rows, stale selection, keyboard invocation placement, touch invocation, zoom, clipping, portal placement, screen readers, and destructive handoff." ], "commonMisuses": [ "Making right click or long press the only way to discover important commands.", "Opening a context menu for the wrong row because selection and pointer target are out of sync.", "Ignoring keyboard context-menu invocation or placing the menu at a stale pointer coordinate.", "Showing different command sets for right click and Shift+F10 on the same object.", "Using a context menu as a catch-all for global navigation, filters, forms, previews, and settings.", "Running destructive commands immediately from the menu without confirmation, undo, or object-specific review.", "Leaving focus behind the menu so Arrow keys scroll the page or move the selected object.", "Letting menus remain open after the target disappears, scrolls away, or changes state." ], "critiqueQuestions": [ "What exact object, selection, or location invoked this context menu?", "Can users access the same important command through a visible route?", "Does keyboard invocation open at the focused object with the same eligible commands as pointer invocation?", "How are stale selection, target removal, viewport collision, and scroll handled?", "Are commands scoped, labelled, grouped, disabled, and risk-separated according to action-menu rules?", "Where does focus go on open, Arrow navigation, Escape, outside click, safe activation, and destructive handoff?" ], "relatedPatterns": [ "action-menu", "menu-button", "menu-menubar", "popover", "command-palette", "confirmation-dialog", "undo" ], "comparisons": [ "context-menu-vs-action-menu-vs-menu-button-vs-popover" ], "sourceIds": [ "mdn-contextmenu-event", "wai-aria-apg-menu-menubar", "fluent-menu-component", "apple-hig-context-menus" ] }, { "id": "cookie-banner", "completionStatus": "complete", "name": "Cookie banner", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Cookie and tracking consent control", "maturity": "standard", "platforms": [ "web", "mobile" ], "problem": "Users need a real, understandable choice about cookies and similar tracking technologies before optional storage is used, but many banners obscure refusal, set tracking before consent, mix legal text with product notices, or make later withdrawal difficult.", "solution": "Show a service-specific cookie banner that explains essential and non-essential purposes, offers accept and reject actions with comparable prominence, supports detailed settings, saves and confirms the choice, blocks optional storage until consent, and keeps withdrawal reachable.", "uiGuidance": [ "Render a clearly labelled cookie banner at the top of the document before ordinary page content, with service-specific copy, essential-cookie information, equal accept and reject actions for non-essential purposes, and a link to detailed cookie settings.", "After a choice, replace the consent prompt with a confirmation message and hide control, then keep a stable settings route available so users can review or withdraw their choice later." ], "uxGuidance": [ "Use a cookie banner to collect or confirm choices for non-essential cookies, local storage, pixels, service-worker storage, analytics, advertising, personalization, or similar device storage technologies.", "Make the privacy choice truthful in the runtime: do not set optional storage until the relevant consent is given, save the preference with version and purpose context, and respect the most recent user choice on the same device." ], "uiExamples": { "good": [ "A service banner says it uses essential cookies and asks to use analytics cookies, with Accept analytics cookies, Reject analytics cookies, and View cookies controls at the same level.", "A category banner lets users manage analytics, personalization, and advertising purposes with all non-essential toggles off until selected.", "A saved-preference message says cookie preferences have been saved and offers Hide this message while a footer Cookies link remains available." ], "bad": [ "A banner has a large Accept all button and a small Manage settings link but no reject action on the first layer.", "A banner says by continuing you accept cookies and fires analytics before any button is clicked.", "A sticky cookie overlay covers page controls and cannot be reached or dismissed reliably with keyboard." ] }, "uxExamples": { "good": [ "A first-time visitor rejects analytics cookies and the site loads without optional analytics, while essential security cookies remain explained.", "A returning visitor does not see the banner because a purpose-level preference was saved, but can reopen settings from the footer.", "A user changes their mind from Accept to Reject in cookie settings and optional tracking stops for future page loads." ], "bad": [ "Reject only closes the banner while ad pixels and analytics continue firing.", "The settings screen contains preselected non-essential options and a Save button that silently accepts them.", "Refusing cookies blocks access to normal service content even though only non-essential tracking is being refused." ] }, "problemContext": [ "The site or service uses cookies, local storage, pixels, analytics, personalization, advertising, service-worker storage, or other technology that stores or accesses information on a user's device.", "Some storage is strictly necessary for security, sessions, basket state, load balancing, or the requested service, while other storage needs consent.", "Users may arrive on public pages, signed-in routes, embedded flows, mobile screens, JavaScript-disabled sessions, or shared devices where the most recent choice should govern.", "The organization needs evidence of what was offered, what purposes were accepted or rejected, and whether the runtime respected the stored preference." ], "selectionRules": [ "Choose cookie banner when a user must be told about cookies or similar technologies and must be able to accept or reject non-essential storage before it is set.", "Do not show a banner only for strictly necessary cookies; instead explain those cookies on a cookies page or privacy route.", "Offer accept and reject actions for non-essential cookies at the same decision level when asking for consent.", "Use manage settings when users need purpose-level choices, but do not hide the only reject path behind multiple steps.", "Show a confirmation after a choice and save the preference by purpose, version, timestamp, and device scope for an appropriate period.", "Keep cookie settings reachable after the banner is hidden so users can withdraw or change consent.", "Use banner, notification banner, or site alert for operational or service messages that do not collect privacy consent.", "Use modal dialog only when a separate, high-consequence decision truly requires blocking interaction; do not make cookie consent a trap.", "Block optional cookies, tracking pixels, analytics, personalization, advertising, and similar storage until the relevant consent is present.", "Use a server-side or no-JavaScript route when optional storage can be set before client code runs." ], "requiredStates": [ "First visit with no saved preference.", "Essential-only service with no banner and a visible cookies page link.", "Accept non-essential cookies state.", "Reject non-essential cookies state.", "Manage purpose-level preferences state.", "Saved preference confirmation message.", "Returning visitor with banner hidden and stored choice applied.", "Changed cookie version or new purpose requiring renewed choice.", "Withdrawal or change-preference state from a stable cookies page link.", "No-JavaScript or server-side submission state.", "Runtime blocked state where optional scripts wait for consent." ], "interactionContract": [ "The banner appears before non-essential storage is set and remains until the user accepts, rejects, or saves preferences.", "Accept, reject, and manage controls are keyboard reachable, clearly labelled by purpose, and visually comparable enough that one choice is not pushed over another.", "Reject means non-essential purposes remain off, not merely that the banner is closed.", "Manage settings shows non-essential purposes off unless the user already saved consent for them.", "Saving a choice updates runtime consent state, records the preference, hides the prompt, and shows a short confirmation that can be closed.", "The cookies page or footer link lets users review, withdraw, or change choices without searching through unrelated privacy copy.", "The banner does not obscure focused content, trap focus, auto-accept on scroll, or make ordinary service access depend on accepting optional tracking." ], "implementationChecklist": [ "Audit and classify each cookie or similar technology as strictly necessary or non-essential before writing banner copy.", "Map each non-essential purpose to a clear user-facing label such as analytics, personalization, advertising, or feedback measurement.", "Block optional tags, pixels, analytics, local storage, service-worker storage, and third-party scripts until the stored consent state permits them.", "Provide equal-level accept and reject actions, plus manage settings when purpose-level choices are needed.", "Persist preference version, purposes, timestamp, and expiry, and refresh consent when purposes or storage behavior change.", "Show a confirmation message after accept, reject, or save, then provide a hide control without losing the settings route.", "Link to a cookies page from the banner and footer, and let that page update the same consent store.", "Test first visit, return visit, reject, accept, manage settings, withdrawal, no JavaScript, shared devices, mobile wrapping, zoom, keyboard order, screen readers, and network proof that optional storage is blocked." ], "commonMisuses": [ "Accept-only banners.", "Reject hidden behind settings while accept is shown as the only button.", "Preselected non-essential categories.", "Firing optional tracking before consent.", "Treating scroll, swipe, close, or continued browsing as consent.", "Using deceptive contrast so reject appears disabled or secondary beyond recognition.", "Blocking service access after a user refuses non-essential cookies.", "Saving one vague consent flag with no purpose, version, or withdrawal route.", "Using cookie banner for outage, marketing, validation, or account notices." ], "critiqueQuestions": [ "Which cookies or similar technologies are strictly necessary, and which need consent?", "Can users reject non-essential purposes with effort comparable to accepting them?", "Does the runtime actually block optional storage until consent exists?", "What preference version, purposes, timestamp, and expiry are saved?", "Where can users change or withdraw the choice after the banner is hidden?", "Does this message belong to cookie consent, or is it a banner, notification banner, site alert, modal dialog, privacy settings, or legal acceptance flow?" ], "relatedPatterns": [ "banner", "notification-banner", "site-alert", "modal-dialog" ], "comparisons": [ "cookie-banner-vs-banner-vs-notification-banner-vs-site-alert" ], "sourceIds": [ "govuk-cookie-banner-component", "ico-cookies-and-similar-technologies", "edpb-cookie-banner-taskforce-report", "cnil-cookies-tracking-guidelines" ] }, { "id": "cookie-consent", "completionStatus": "complete", "name": "Cookie consent", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Purpose-level consent and runtime enforcement model for cookies, local storage, pixels, tags, SDKs, and similar device storage or access", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Cookie consent fails when optional storage runs before choice, accept is easier than reject, categories are preselected, consent is recorded as one vague flag, users cannot withdraw, or runtime tags do not match saved purpose-level choices.", "solution": "Build a cookie consent flow that separates essential and optional purposes, blocks optional storage before consent, provides equal accept and reject routes, records purpose-level evidence, handles region and browser signals, supports withdrawal and renewal, and verifies runtime tags against the stored consent state.", "uiGuidance": [ "Present strictly necessary storage separately from optional cookie purposes such as analytics, advertising, personalization, functional enhancements, pixels, SDKs, and similar technologies.", "Use off-by-default optional controls, comparable accept and reject routes, purpose details, vendor or tag visibility where relevant, and a clear save or withdraw action tied to the runtime state." ], "uxGuidance": [ "Use cookie consent when the user must decide which non-essential storage or tracking purposes can run before optional cookies, tags, pixels, local storage, or SDKs are activated.", "Make the consent durable and reversible by recording purpose, version, region, timestamp, source surface, browser signal, and withdrawal state, then enforcing that record before optional scripts run." ], "uiExamples": { "good": [ "A cookie settings page shows essential cookies locked on, analytics, personalization, and advertising off by default, plus Accept all, Reject all, Save choices, and a vendor details panel.", "A runtime consent inspector shows analytics tags blocked until the analytics purpose is saved and advertising tags blocked because a browser privacy signal is active." ], "bad": [ "A second-layer settings panel has all optional cookie categories preselected and a prominent Save button.", "The service stores cookieConsent=true while analytics, advertising, local storage, and personalization run without purpose-level records." ] }, "uxExamples": { "good": [ "A user rejects all optional cookies, continues using the service, later opens Cookie settings, enables analytics only, receives a saved confirmation, and can withdraw again.", "A new advertising purpose is added, so the service treats the prior consent as stale and asks again before loading advertising tags." ], "bad": [ "The user closes the banner and the product treats inactivity as consent to advertising cookies.", "A user enables Do Not Sell or Global Privacy Control in the browser, but the consent runtime still loads ad pixels." ] }, "problemContext": [ "Cookie consent applies to cookies and similar technologies such as local storage, pixels, tags, analytics SDKs, advertising identifiers, personalization storage, service-worker storage, and device access for tracking purposes.", "The consent mechanism may be launched from a cookie banner, cookies page, privacy settings, preference center, footer link, first-run flow, or regional compliance surface.", "Strictly necessary storage is handled differently from optional analytics, advertising, personalization, functional, social media, and measurement purposes.", "Cookie consent is a runtime contract: the UI, consent record, tag manager, server rendering, and client storage must all agree before optional technologies run." ], "selectionRules": [ "Choose cookie consent when the decision controls cookies, pixels, local storage, tags, SDKs, or similar storage and access on the user's device.", "Use cookie banner for the first-layer notice that introduces cookie choices, not for the entire consent management model.", "Use consent prompt for optional data use that is not specifically cookie or similar device storage.", "Use preference center when the user returns to a durable hub that includes cookies alongside communication, topic, language, and privacy preferences.", "Use privacy settings for broader account, device, data-sharing, and product privacy controls.", "Use legal acceptance for terms or policy agreement; do not bundle legal acceptance with cookie consent.", "Refresh cookie consent when purposes, vendors, region rules, storage types, controller, or consequences materially change.", "Treat browser privacy signals and regional requirements as inputs to consent enforcement, not as decorative status text." ], "requiredStates": [ "Pre-consent state with optional storage blocked.", "Strictly necessary explanation state.", "Accept all optional purposes state.", "Reject all optional purposes state.", "Granular purpose choices state.", "Vendor or tag details state.", "Saved consent record state.", "Return visit state with stored preferences applied.", "Withdrawal or change preferences state.", "Renewal after version or purpose change state.", "Expired consent state.", "Browser privacy signal or Global Privacy Control state.", "No-JavaScript server-side preference state.", "Runtime mismatch or tag blocked state.", "Mobile compact consent state." ], "interactionContract": [ "Optional cookies, pixels, local storage, analytics tags, advertising tags, and similar technologies remain blocked until the matching purpose is accepted.", "Strictly necessary storage is identified separately and is not represented as optional consent.", "Accept all and reject all actions are reachable with comparable effort, prominence, keyboard access, and language clarity.", "Granular choices start off unless a current valid consent record already exists for the same purpose, version, and region.", "Saving consent writes a purpose-level record with version, timestamp, region, source surface, browser signal state, and withdrawal route.", "Withdrawal or reject-all stops future optional storage and updates the consent record rather than only hiding the interface.", "Adding or changing optional purposes triggers a renewal flow before new tags run.", "Runtime enforcement reports blocked, allowed, stale, unknown, failed-write, and signal-conflict states." ], "implementationChecklist": [ "Inventory all cookies, pixels, tags, SDKs, local storage, service-worker storage, and server-set identifiers before designing the UI.", "Classify each item as strictly necessary or optional with purpose, vendor, lifetime, region, source, and runtime owner.", "Block optional technologies before consent in both server-rendered and client-rendered paths.", "Provide accept all, reject all, granular save, purpose details, vendor details, and withdrawal routes with comparable effort.", "Record purpose-level consent version, timestamp, region, controller, source surface, browser signal, and withdrawal state.", "Handle return visits, stale versions, new purposes, browser privacy signals, no-JavaScript submission, failed record writes, and tag-manager mismatches.", "Verify with network or tag inspection that optional storage does not run before consent and stops after withdrawal.", "Keep cookie consent separate from legal acceptance, marketing email opt-in, notification preferences, and broad privacy settings." ], "commonMisuses": [ "Firing analytics or advertising tags before the user chooses.", "Using one accepted flag instead of purpose-level consent records.", "Preselecting optional categories in the settings layer.", "Making Accept all much easier to find than Reject all.", "Treating scrolling, swiping, closing, inactivity, or continued browsing as consent.", "Hiding withdrawal after the banner disappears.", "Claiming advertising cookies are strictly necessary without a defensible classification.", "Letting tag-manager configuration drift away from saved consent choices." ], "critiqueQuestions": [ "Which cookies, storage APIs, tags, SDKs, and server identifiers are strictly necessary versus optional?", "What proves optional storage is blocked before consent and after withdrawal?", "Can users reject all optional purposes with comparable effort to accepting all?", "Are optional purposes off by default and saved separately?", "What consent version, region, timestamp, source surface, and browser signal are recorded?", "How does the product handle new purposes, expired consent, no-JavaScript users, and failed record writes?", "Where can users later withdraw or change cookie consent after the banner is gone?" ], "relatedPatterns": [ "cookie-banner", "consent-prompt", "preference-center", "privacy-settings", "legal-acceptance", "notification-preferences", "permission-request", "settings-management", "sensitive-data-reveal", "data-export" ], "comparisons": [ "cookie-consent-vs-cookie-banner-vs-consent-prompt-vs-preference-center-vs-privacy-settings-vs-legal-acceptance" ], "sourceIds": [ "ico-cookies-and-similar-technologies", "edpb-cookie-banner-taskforce-report", "cnil-cookies-tracking-guidelines", "govuk-cookie-banner-component", "onetrust-cookie-preference-center-config" ] }, { "id": "correction-feedback", "completionStatus": "complete", "name": "Correction feedback", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "AI output correction feedback flow with selected claim, reason, scope, consent, receipt, and review state", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI products need user correction when generated output is wrong, unsafe, unsupported, stale, or mis-scoped, but vague feedback controls often lose the corrected claim, user intent, consent, privacy boundary, and follow-up status.", "solution": "Provide a correction feedback flow that binds feedback to the exact AI output or claim, captures the error reason and expected correction, lets users choose scope and consent, confirms receipt, routes review when needed, and keeps feedback history visible without exposing private notes.", "uiGuidance": [ "Render correction feedback as an AI-output control that anchors feedback to a specific answer, claim, source, recommendation, tool result, or message instead of a detached thumbs signal.", "Show selected claim, feedback reason, expected correction, source correction, privacy note, scope choice, training or review consent, submission state, and follow-up status in the same flow." ], "uxGuidance": [ "Use correction feedback when users need to tell the product that an AI answer is wrong, missing evidence, harmful, outdated, wrongly sourced, irrelevant, or should not be repeated.", "Separate correction capture from regeneration and manual editing: users should know whether their feedback updates this answer, future answers, reviewer queues, model improvement data, or none of those." ], "uiExamples": { "good": [ "An assistant answer lets a user select a suspect claim, choose Wrong answer, add the expected answer and corrected source, opt out of training use, and see Feedback received with review routing.", "A policy answer card shows Missing source and Harmful suggestion feedback choices, keeps the private note out of the shared transcript, and records reviewer outcome in feedback history." ], "bad": [ "A thumbs-down icon accepts feedback with no selected answer, reason, expected correction, privacy choice, receipt, or indication of whether anything will change.", "A correction box secretly rewrites the hidden prompt, trains on private feedback without consent, and never tells the user whether the correction was reviewed." ] }, "uxExamples": { "good": [ "A user flags a wrong eligibility answer, attaches the correct policy source, applies the correction to the current answer only, and receives a reviewer-routed status.", "A support analyst marks an AI suggestion as outdated, keeps the feedback private, opts out of training use, and later sees the correction accepted in the answer history." ], "bad": [ "A user reports that a cited source is wrong, but the feedback is stored as an undifferentiated dislike and future answers keep using the same bad source.", "A user writes sensitive context in a correction note and the product exposes it in the public conversation transcript." ] }, "problemContext": [ "A user may need to correct a factual answer, cited source, generated recommendation, tool-derived value, safety-sensitive suggestion, outdated policy answer, tone, scope, or missing caveat.", "The same feedback can mean apply a fix to this answer, avoid repeating the behavior, route to a reviewer, improve retrieval sources, update prompt instructions, improve model data, or simply record user dissatisfaction.", "Feedback may contain private, sensitive, regulated, customer, patient, legal, financial, or internal business information that must not appear in shared transcripts or training data without consent.", "AI corrections are valuable only when they preserve answer ID, claim span, source ID, conversation context, model response version, user reason, expected answer, and outcome.", "Some corrections require human review, audit trails, appeals, retention limits, or disclosure that the current answer will not change immediately." ], "selectionRules": [ "Choose correction feedback when users need to correct AI output, source use, assumptions, recommendations, safety behavior, or answer quality after an AI response is shown.", "Use query correction when the product rewrites or suggests a search query before results are returned.", "Use inline validation when the product flags a single form field, input value, format, or constraint violation.", "Use comments when the main task is human discussion, annotation, approval, or durable collaboration around an object rather than feeding back to an AI system.", "Use regenerate / retry when users want another AI attempt or response version without necessarily supplying a correction reason.", "Use editable AI output when users directly edit the generated draft itself and need change tracking or apply controls.", "Use source grounding display, citation display, or confidence uncertainty display when the task is inspecting evidence or uncertainty rather than sending a correction.", "Capture selected answer, selected claim, selected source, feedback reason, expected answer, corrected source, privacy note, scope, consent, and receipt before treating correction feedback as actionable.", "Do not use thumbs-only, sentiment-only, star rating, or undifferentiated reaction controls as the only path for correcting materially wrong or unsafe AI output.", "Do not silently train on correction text, rewrite hidden prompts, publicize private notes, or imply the current answer changed unless the user can see the corrected output." ], "requiredStates": [ "Initial AI answer state with feedback entry points attached to the answer, individual claims, citations, recommendations, or tool-derived values.", "Wrong answer, missing source, wrong source, harmful suggestion, outdated answer, irrelevant answer, biased or unsafe answer, hallucinated value, and incomplete answer reasons.", "Selected claim, selected source, expected answer, corrected source, private note, attachment, and reviewer-needed states.", "Scope choices such as apply to this answer, apply to future answers, review only, update source, do not train on this feedback, and keep feedback private.", "Submitting, feedback received, failed to submit, duplicate feedback, queued for review, accepted, rejected, partially applied, appealed, and feedback history states.", "Permission, authentication, rate limit, abuse-prevention, moderation, sensitive-data warning, and retention-disclosure states.", "Mobile correction sheet state that keeps the selected claim, reason, scope, consent, and receipt visible without losing the answer context." ], "interactionContract": [ "A correction feedback action preserves answer ID, response version, claim span, source ID, user reason, expected correction, submitter, timestamp, and chosen scope.", "Reason choices remain specific enough to route feedback: wrong answer, missing source, wrong source, outdated answer, harmful suggestion, unsafe or biased output, irrelevant answer, and other correction.", "Users can add expected answer text, corrected source, or a private note, and the UI states which of those fields may be used for review, source improvement, prompt improvement, model improvement, or current-answer repair.", "Scope controls distinguish this answer, future answers, reviewer triage, source update, and training use; defaults must not hide consequential data use.", "Submission creates an accessible receipt and a visible follow-up path when review or appeal is possible.", "Private feedback does not appear in shared transcripts, public comments, copied output, generated summaries, or source snippets unless the user explicitly publishes it.", "If a correction changes the displayed answer, the UI shows the corrected version, prior version, author or reviewer status, and what changed.", "If the correction cannot change the answer, the UI says so and avoids implying immediate model learning." ], "implementationChecklist": [ "Model correction feedback with answer ID, response version, claim span, source ID, tool output ID, reason, expected answer, corrected source, private note, scope, consent, status, reviewer owner, and history fields.", "Provide claim-level selection and source-level selection so users do not have to describe what the correction refers to in free text alone.", "Route wrong answer, source correction, harmful suggestion, outdated answer, missing source, and sensitive feedback to different handling paths when product risk requires it.", "Persist feedback receipts and outcomes so users and reviewers can see whether a correction is queued, accepted, rejected, partially applied, appealed, or closed.", "Keep training consent, privacy controls, retention language, and shared-transcript behavior explicit before submission.", "Prevent duplicate submissions, lost feedback, cross-answer attribution, public leakage, hidden prompt edits, and unreviewed automatic current-answer changes.", "Test desktop and mobile correction capture, selected claim wrapping, long corrected source titles, private note handling, disabled submit states, failed submission recovery, review status, appeal, keyboard operation, and screen-reader status announcements." ], "commonMisuses": [ "Using a thumbs-down or smiley reaction as the only mechanism for correcting wrong AI output.", "Collecting feedback without tying it to a specific answer, claim, citation, source, tool result, or response version.", "Hiding whether feedback applies to the current answer, future answers, review queues, training data, retrieval sources, or prompt behavior.", "Treating correction text as a new prompt or hidden instruction without showing the user that the answer scope changed.", "Publishing private correction notes in a shared transcript or training on them without consent.", "Confirming receipt with no durable status, reviewer outcome, appeal path, or feedback history for high-risk corrections." ], "critiqueQuestions": [ "What exact answer, claim, source, recommendation, or tool result is being corrected?", "Can the user state whether the problem is wrong answer, missing source, wrong source, harmful suggestion, outdated answer, biased output, or another correction?", "Does the user know whether the correction affects this answer, future answers, review only, source quality, prompt behavior, or training use?", "Where does private correction text appear, and what prevents it from leaking into shared transcripts or generated output?", "What receipt, status, reviewer decision, appeal path, or history can the user inspect after submission?", "Would query correction, inline validation, comments, regenerate / retry, or editable AI output better match the real task?" ], "relatedPatterns": [ "query-correction", "inline-validation", "comments", "regenerate-retry", "editable-ai-output", "source-grounding-display", "citation-display", "confidence-uncertainty-display" ], "comparisons": [ "correction-feedback-vs-query-correction-vs-inline-validation-vs-comments-vs-regenerate-retry-vs-editable-ai-output" ], "sourceIds": [ "microsoft-human-ai-guidelines", "google-people-ai-guidebook", "openai-conversation-state", "wcag-status-messages" ] }, { "id": "create-user-profile", "completionStatus": "complete", "name": "Create user profile", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Visible personal identity and profile presentation setup", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Profile creation turns personal details into visible identity across mentions, directories, comments, assignments, and public pages, so unclear required fields, missing visibility controls, forced optional details, or no preview can expose users or create a misleading profile.", "solution": "Create a small profile setup flow that explains where profile data appears, separates required display identity from optional enrichment, supports safe defaults and managed fields, previews audience-specific visibility, and saves only the information users choose to share.", "uiGuidance": [ "Render profile creation as a focused identity setup surface with required display identity, optional photo or initials, optional role or bio fields, visibility choices, managed-field indicators, and a live preview of how the profile will appear.", "Keep account credentials, security setup, notification preferences, and onboarding tasks separate from the profile form unless they directly affect how the user's profile is shown." ], "uxGuidance": [ "Use create user profile when users need to decide what personal information represents them to other people or public surfaces.", "Ask only for the profile fields needed now, explain where each field appears, make optional fields skippable, protect sensitive information with visibility controls, and return users to the collaboration or public context that needs the profile." ], "uiExamples": { "good": [ "A new workspace member chooses a display name, sees initials as the default avatar, optionally adds pronouns and job title, chooses whether location is visible to the team, and previews a mention card before saving.", "A developer profile asks for public name and bio, warns that the bio and profile photo may be visible publicly, and lets the user leave social links empty." ], "bad": [ "A profile setup screen requires a photo, birthday, location, phone number, biography, and social links before the user can enter a private project.", "A public profile form labels every field Profile info but never shows which values appear in search, mentions, comments, or external pages." ] }, "uxExamples": { "good": [ "A user saves a profile with only display name and initials, sees how it appears to teammates, and adds a bio later from the profile page.", "A user sees that job title is managed by the organization, understands where to request changes, and can still edit their public name and visibility." ], "bad": [ "A user's legal name is shown to external collaborators because the profile creation screen did not distinguish legal name from public display name.", "A user uploads a photo thinking it is private, then discovers it appears in public comments and search results." ] }, "problemContext": [ "Users are entering a collaboration product, community, marketplace, developer platform, employee directory, social surface, or public contribution system.", "Other people need enough profile information to identify, mention, assign, contact, trust, or understand the user.", "Profile details can be visible to teammates, organizations, external collaborators, public pages, search, apps, or marketplaces.", "Some fields may be synced from an identity provider, admin-managed, legally required, or optional self-expression.", "Users may not know the difference between full name, public name, display name, username, handle, bio, status, job title, pronouns, location, local time, and profile photo." ], "selectionRules": [ "Choose create user profile when the user is defining visible identity information that other people or public surfaces will see.", "Require only the smallest set of profile fields needed for recognition or safety, such as display name or public name.", "Make optional fields clearly optional and explain why adding them helps, where they appear, and whether they can be skipped.", "Show safe defaults such as initials, empty bio, hidden location, or organization-only visibility before asking for extra details.", "Preview the profile card, public profile, mention, comment byline, or directory result before saving when profile visibility matters.", "Use visibility choices for fields that can expose personal information, especially photo, full name, pronouns, location, local time, email, bio, and social links.", "Mark organization-managed or identity-provider-synced fields as managed and provide a route to request changes.", "Avoid using profile creation to collect account credentials, marketing preferences, onboarding answers, or broad settings.", "Use account creation when the user is establishing credentials and recovery; use onboarding when the user is learning the product; use profile setup later when users are enriching an existing profile.", "Do not publish profile information to public pages, search, or third-party apps until visibility consequences are explicit." ], "requiredStates": [ "Initial profile purpose state explaining where the profile will appear.", "Required display identity state with clear labels for display name, public name, handle, or full name.", "Optional avatar state with upload, remove, initials fallback, and image-crop or alt-text guidance where relevant.", "Optional bio, role, title, pronouns, location, local time, social link, or status state with skip path.", "Field visibility state showing audience such as Only you, organization, teammates, external collaborators, or anyone.", "Managed field state for values controlled by admin, directory sync, SSO, or identity provider.", "Preview state showing how the profile appears in at least one real destination.", "Save confirmation state that returns users to the context that needed the profile.", "Edit later state explaining where profile details and visibility can be changed.", "Public or external exposure warning state when profile information may be indexed, shared, or accessed by apps." ], "interactionContract": [ "The form states which profile fields are required, optional, managed, hidden, or public before users save.", "Users can skip optional profile enrichment without losing access to the core product unless policy requires it.", "Changing a field updates the preview and any visibility summary tied to that field.", "Photo upload has a fallback path and does not block saving when a photo is optional.", "Visibility controls apply to the actual downstream profile surfaces, not just the setup page.", "Managed fields cannot be edited as if user-controlled; the UI explains the source and change path.", "Saving the profile preserves user-entered fields, records visibility choices, and returns focus to the next useful task or profile preview." ], "implementationChecklist": [ "Inventory where each profile field appears: mentions, cards, directories, search, public pages, apps, comments, assignments, and exports.", "Classify each field as required, optional, managed, derived, private, organization-visible, external-visible, or public.", "Use existing name, email, avatar, locale, and organization data only when users understand how it will be displayed.", "Design initials fallback, missing-photo state, skipped-bio state, invalid link state, long-name state, and translated-label state.", "Show a profile preview for the most important destination, and include audience or visibility labels near sensitive fields.", "Keep account credentials, MFA, notification preferences, marketing consent, and onboarding choices out of the required profile step.", "Test display names with spaces, capitalization, non-English characters, long names, initials, no photo, managed fields, mobile keyboard, screen readers, high contrast, and public/private visibility." ], "commonMisuses": [ "Forcing optional profile completion before users can do the task they came for.", "Publishing profile data without a preview or visibility explanation.", "Confusing legal name, full name, public name, display name, username, and handle.", "Making profile photo mandatory when initials or a neutral avatar would work.", "Letting users edit fields that are later overwritten by directory sync.", "Using profile creation to ask for credentials, security setup, marketing preferences, or product onboarding data.", "Hiding required fields among optional enrichment fields.", "Showing the same profile preview for all audiences when visibility differs." ], "critiqueQuestions": [ "Where will each profile field appear after save?", "Which fields are truly required for recognition, safety, collaboration, or policy?", "Can users skip photo, bio, location, pronouns, and social links?", "What visibility does each sensitive field have by default?", "Which fields are user-controlled versus admin-managed or synced?", "Does the preview match mentions, cards, directories, public pages, and app access?" ], "relatedPatterns": [ "account-creation", "onboarding", "single-page-form", "name-entry", "email-address-entry" ], "comparisons": [ "create-user-profile-vs-account-creation-vs-onboarding-vs-single-page-form" ], "sourceIds": [ "atlassian-profile-visibility-settings", "slack-display-name-profile", "slack-customize-member-profiles", "github-profile-overview", "nng-required-fields-forms" ] }, { "id": "custom-dashboard", "completionStatus": "complete", "name": "Custom dashboard", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "User-configurable dashboard canvas with persisted widget composition", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Different users need different dashboard priorities, but fixed dashboard layouts either bury personally important widgets or make customization risky because users cannot tell what will be saved, who will be affected, or how the layout behaves on smaller screens.", "solution": "Provide a custom dashboard workflow with an explicit edit mode, widget gallery, add remove move and resize controls, personal versus shared save scope, responsive preview, permission-limited widget handling, reset paths, and clear unsaved-change feedback.", "uiGuidance": [ "Expose a customization mode that separates normal dashboard reading from editing, with visible controls for adding widgets, removing widgets, moving widgets, resizing tiles, previewing responsive order, saving changes, canceling edits, and resetting to a default layout.", "Show each dashboard widget with a stable title, source, freshness, permission state, size, edit affordance, and drag or keyboard move target so users can tell what will be persisted before they save." ], "uxGuidance": [ "Use custom dashboard when users need to compose a personal or role-specific dashboard from multiple widgets, data sources, saved views, filters, or shortcuts, then return to that arrangement across sessions.", "Keep customization state distinct from dashboard data filters and from shared dashboard definitions so users know whether a change affects only their view, a team dashboard, or the underlying data." ], "uiExamples": { "good": [ "A team lead opens Customize, sees selected widgets, available widgets, size controls, keyboard move buttons, unsaved changes, and a preview of how the dashboard will stack on mobile.", "A dashboard card labelled SLA risk shows source, last refresh, current size, visible-to-team status, and Move earlier, Resize, Hide, and Remove actions." ], "bad": [ "Dashboard widgets can be dragged around, but there is no edit mode, no saved state, and no indication whether the new order is personal or shared.", "A widget gallery lets users add charts with vague names such as Metric and Overview, no data source, no permission warning, and no preview of responsive placement." ] }, "uxExamples": { "good": [ "A manager adds the Escalations widget, moves it above the revenue chart, previews mobile order, saves as My support dashboard, and can reset to the team default later.", "A user tries to add a restricted finance widget and sees a permission-limited card with a request-access route rather than a blank tile." ], "bad": [ "A user rearranges a shared operations dashboard and accidentally overwrites the layout for the whole team.", "A mobile dashboard keeps desktop widget order and pushes the only actionable queue below several decorative charts." ] }, "problemContext": [ "The product has reusable widgets, charts, KPI cards, saved views, queues, shortcuts, or reports that different roles prioritize differently.", "Users need a persistent personal or role-based arrangement rather than only global filters on a fixed dashboard.", "Dashboard composition may affect shared workspaces, role defaults, navigation shortcuts, alert visibility, or mobile order.", "Widgets can fail, become unavailable, require permission, have different refresh cadences, or be removed from the product catalog.", "Users may customize with a pointer, keyboard, touch, narrow screen, or assistive technology." ], "selectionRules": [ "Choose custom dashboard when users need to choose which widgets appear, where they appear, and how much space they occupy.", "Use dashboard layout when the product team defines one coherent monitoring page and users mainly read, filter, or drill from it.", "Use saved view when users persist the presentation of one data surface rather than composing several dashboard widgets.", "Use preference center when users configure communications, privacy, notification, or account preferences rather than dashboard content.", "Use pinned items or favorites when users only need quick access shortcuts and are not arranging a widget canvas.", "Offer shared-dashboard editing only when ownership, edit permission, audience impact, review, and rollback are explicit.", "Avoid custom dashboard when the widget set is too small, unrelated, or unreliable to support meaningful personal composition.", "Avoid drag-only customization; every widget move, resize, remove, save, cancel, and reset action needs a keyboard-accessible path." ], "requiredStates": [ "Read-only dashboard state with current layout name, owner or scope, active widgets, freshness, and customize entry point.", "Customization mode with selected widgets, available widget gallery, unsaved changes, move, resize, remove, save, cancel, and reset controls.", "Personal save, shared save, save as copy, discard changes, reset to default, and restored default states.", "Widget added, widget removed, widget reordered, widget resized, duplicate-widget blocked, and maximum-widget-count states.", "Unavailable, permission-limited, retired, loading, failed, stale, empty, and source-disconnected widget states.", "Responsive preview and narrow-screen state where critical widgets, edit controls, save status, and reset remain reachable." ], "interactionContract": [ "Entering customization mode freezes dashboard reading interactions and makes layout-editing controls explicit.", "Adding a widget places it in a predictable location, announces the change, and marks the dashboard as unsaved until saved or canceled.", "Moving or resizing a widget updates visual order, keyboard order, and responsive order together.", "Saving states whether changes apply to only this user, a role default, or a shared team dashboard before committing.", "Cancel and reset restore the previous persisted layout without changing dashboard filters, selected data, or saved views inside widgets.", "Permission-limited or retired widgets remain explainable with remove, replace, or request-access paths.", "Responsive preview shows how widget order and size will adapt before users save a desktop arrangement.", "The system records enough metadata to recover from failed saves, conflicting shared edits, and removed widgets." ], "implementationChecklist": [ "Define a dashboard layout model with dashboard ID, owner, scope, widget IDs, widget order, widget sizes, responsive priority, data bindings, and saved timestamp.", "Separate layout state from data filters, query state, saved view definitions, and widget data refresh state.", "Provide add, remove, move earlier, move later, resize, save, cancel, reset, duplicate handling, and shared-impact confirmation.", "Validate every widget against permissions, source availability, retired-widget catalog state, mobile size, and maximum dashboard constraints.", "Persist personal layouts separately from team defaults and provide a way to copy a shared dashboard before editing.", "Announce customization changes through a stable status region and keep focus on the edited widget or next safe control.", "Test pointer drag, keyboard moves, touch reordering, narrow widths, long widget titles, failed saves, conflicting shared edits, and reset recovery." ], "commonMisuses": [ "Treating a fixed dashboard with filters as a custom dashboard even though users cannot choose widgets, order, or size.", "Letting users drag widgets without save, cancel, reset, keyboard movement, or shared-impact confirmation.", "Saving a personal layout over a team default without owner or audience warning.", "Using customization to hide mandatory operational alerts or compliance widgets with no policy explanation.", "Losing widget order on mobile or making keyboard order differ from the visible arrangement.", "Showing blank spaces when a widget is retired, permission-limited, or disconnected from its source." ], "critiqueQuestions": [ "Can users tell whether they are editing layout, filtering data, or changing a saved view inside a widget?", "Which changes are personal, shared, default, temporary, unsaved, or policy locked?", "Can each widget be added, removed, moved, resized, replaced, and restored without pointer-only interactions?", "What happens when a widget becomes unavailable, loses permission, fails refresh, or is removed from the catalog?", "Does responsive order preserve user intent and keep critical widgets before decorative or low-priority widgets?", "Would dashboard layout, saved view, pinned items, favorites, or preference center better match the user task?" ], "relatedPatterns": [ "dashboard-layout", "saved-view", "preference-center", "settings-page", "data-visualization" ], "comparisons": [ "custom-dashboard-vs-dashboard-layout-vs-saved-view-vs-preference-center" ], "sourceIds": [ "microsoft-power-bi-dashboard-tiles", "microsoft-power-bi-dashboard-design-tips", "tableau-dashboard-size-layout", "hubspot-saved-views" ] }, { "id": "dangerous-action-review", "completionStatus": "complete", "name": "Dangerous-action review", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Pre-execution review of high-impact actions that may affect money, access, production systems, legal status, customers, external recipients, or safety", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "High-impact actions fail safely only when users can inspect what is about to happen; generic confirmations, warnings, and post-action logs often hide scope, payload, evidence, external effects, stale state, and safer alternatives until after the dangerous operation has already run.", "solution": "Before execution, present a risk review that binds the exact action, payload, target, actor, evidence, permissions, freshness, side effects, alternatives, and audit record, then let the reviewer run, edit, cancel, defer, or escalate only the displayed action after revalidation.", "uiGuidance": [ "Render dangerous-action review as a pre-execution checkpoint that names the armed action, actor, target, scope, affected systems, external effects, risk reason, evidence, freshness, permissions, alternatives, and exact outcome of Run, Cancel, Edit, or Escalate.", "Show a structured risk inventory before execution: who or what is affected, what leaves the system boundary, what cannot be recalled, what policy or threshold triggered review, what evidence supports the action, and what still needs human attention." ], "uxGuidance": [ "Use dangerous-action review when an action is not necessarily destructive but can create high-impact consequences such as sending money, changing access, executing production commands, contacting customers, publishing content, filing a legal response, or letting an agent use a privileged tool.", "Help users decide whether to run, revise, cancel, defer, or escalate the action by making the action payload inspectable, comparing it with safer alternatives, revalidating stale state, and recording what the reviewer saw before execution." ], "uiExamples": { "good": [ "A production console shows Restart payment workers, affected region, open incidents, customer impact, rollback owner, evidence links, change window, dry-run result, and Run restart only after the reviewer checks the risk inventory.", "An AI support tool proposes Send refund email and issue $480 credit, shows customer, amount, policy match, source gaps, external email preview, account balance, and safer Edit amount or Escalate options before execution." ], "bad": [ "A privileged tool button says Continue and immediately sends a customer email, changes access, and updates billing without showing the payload or external recipients.", "A warning says This may be risky but hides the target, policy trigger, evidence, and whether the action can be undone." ] }, "uxExamples": { "good": [ "A release manager sees that a deploy action affects production EU, has a stale smoke test, cancels execution, refreshes checks, and then runs the action with an audit record.", "A support lead reviews an agent-proposed refund, notices that the evidence is partial, edits the amount, and runs only the revised external action." ], "bad": [ "A user approves a notification from email after the underlying payload changed, and the system executes against a different customer.", "A reviewer sees only a confidence score and a red warning, so they cannot tell whether the action sends a message, changes permissions, or spends money." ] }, "problemContext": [ "The action may send money, issue refunds, change access, publish or delete customer-facing content, run production commands, deploy code, contact external recipients, submit legal or compliance material, launch a physical-world operation, or let an AI agent call a privileged tool.", "The action may not be destructive in the narrow sense; risk comes from external visibility, cost, permissions, security, customer impact, legal effect, production blast radius, or inability to recall the side effect.", "Users may encounter the review inside consoles, agent tool-call previews, workflow builders, admin tools, deployment screens, customer-support workspaces, finance tools, moderation systems, and mobile approval notifications.", "The system can compute or disclose action payload, target, risk reason, evidence, reviewer authority, freshness, alternatives, policy triggers, expected side effects, and execution result." ], "selectionRules": [ "Choose dangerous-action review when the user is about to execute a high-impact action and needs to inspect the exact payload, risk, evidence, and side effects before it leaves the safe preview state.", "Use destructive action confirmation when the central risk is permanent deletion, removal, reset, cancellation, or unrecoverable loss of a named object.", "Use typed confirmation as an escalation when wrong-target risk is severe enough that the user must reproduce a visible target phrase.", "Use human approval gate when automation is already paused and cannot resume until an eligible human approves the next step; dangerous-action review may be initiated by the same user before manual or agent-assisted execution.", "Use review before submit for ordinary user-entered form answers; dangerous-action review is for high-impact side effects, privileged tools, production changes, external recipients, money, access, legal status, or safety-sensitive action.", "Use security warning when the system detected an unsafe destination, malware, phishing, certificate, transport, or file-risk signal.", "Show the action verb, target, payload, side effects, affected people or systems, evidence, uncertainty, policy trigger, freshness, permissions, alternatives, and execution boundary before Run is available.", "Block or re-open review when the action payload, target, permissions, evidence, policy, external state, model output, or run context changes after the review opened.", "Prefer safer alternatives such as dry run, preview, edit, schedule, sandbox, request approval, reduce scope, or cancel when the review exposes unresolved risk." ], "requiredStates": [ "Armed action state with verb, target, payload, actor, source, and exact execution boundary.", "Risk inventory state listing money, access, customer, production, legal, security, external-recipient, data, safety, or physical-world effects.", "Evidence and confidence state with source links, gaps, stale checks, and uncertainty stated in task language.", "Freshness revalidation state before execution when payload, target, permission, policy, or external data may have changed.", "Edit before run state that changes payload or scope and reopens the review summary.", "Dry run or preview state when the system can simulate the operation safely.", "Cancel, defer, escalate, or request approval state when risk remains unresolved.", "Run action state with duplicate-submit protection and one named action boundary.", "Blocked state for missing permission, stale evidence, policy restriction, maintenance freeze, or unresolved dependency.", "Executed state with audit receipt, side-effect result, failure handling, and rollback or follow-up status.", "Mobile compact review state that still exposes action, target, risk, evidence, side effect, and safe alternatives." ], "interactionContract": [ "The review is bound to a specific action ID, payload version, target, actor, permission scope, source context, evidence set, and policy trigger.", "The primary action label names the real operation, such as Send refund, Restart workers, Publish policy, Grant admin access, or Run production command.", "The review exposes what will happen outside the product boundary, including emails, webhooks, payments, permission changes, deployments, records, customer notifications, or irreversible third-party effects.", "Run is unavailable until required risk inventory, evidence freshness, permissions, and acknowledgements pass.", "Editing scope, payload, target, recipients, amount, command, environment, model output, or evidence returns the review to an updated pre-execution state.", "Opening a review from email, mobile, notification, or reopened tab revalidates current state and refuses stale actions.", "Cancel leaves the target unchanged and records no execution; defer, escalate, and request approval preserve the review context.", "Execution produces an audit record of the shown payload, reviewer, decision, timestamp, risk reason, revalidation result, side effects, and downstream outcome." ], "implementationChecklist": [ "Define which operations count as dangerous by consequence: money movement, access changes, production commands, public publication, customer messaging, legal submission, sensitive data mutation, external integrations, safety-sensitive workflows, or privileged agent tool use.", "Capture action ID, actor, target, payload, recipients, environment, permissions, risk reason, policy trigger, evidence, confidence, source freshness, dry-run result, side effects, rollback options, and audit metadata.", "Design the review so the first screen names the action and target, then exposes risk inventory, evidence, alternatives, and execution controls without hiding the payload behind generic warnings.", "Add revalidation for stale payloads, changed recipients, changed permissions, expired evidence, maintenance windows, policy changes, model output changes, and external-state drift.", "Support safe alternatives such as edit, reduce scope, dry run, schedule, sandbox, request approval, escalate, cancel, or open supporting evidence.", "Prevent duplicate execution and make the in-progress boundary clear after the reviewer chooses the dangerous action.", "Record what was visible at review time and what actually executed, without logging secrets or unnecessary sensitive payload details.", "Test stale notification decisions, changed payloads, permission loss, duplicate clicks, mobile wrapping, keyboard flow, screen-reader status, audit receipt, failed execution, and post-run follow-up." ], "commonMisuses": [ "Using vague Are you sure, Continue, or Proceed copy without naming the dangerous operation.", "Showing a risk warning but hiding the action payload, target, recipients, amount, command, environment, or external effect.", "Treating confidence, risk color, or severity score as a substitute for reviewable evidence.", "Allowing stale email or mobile approvals to execute a changed action.", "Combining many dangerous operations under one approval when the UI only described one of them.", "Using dangerous-action review for routine low-impact actions until reviewers stop reading.", "Recording only that a user clicked Run without preserving the shown payload and risk basis." ], "critiqueQuestions": [ "What exact action, target, payload, and side effects will execute if the reviewer continues?", "What makes this action dangerous: money, access, production, customer, legal, security, external recipient, data sensitivity, safety, or physical-world impact?", "What evidence, policy trigger, confidence, or freshness check supports the action, and what is missing?", "Can the reviewer edit, reduce scope, dry run, cancel, defer, request approval, or escalate instead of running?", "What revalidation prevents stale notifications, changed payloads, or lost permissions from executing?", "What audit record proves what the reviewer saw and what actually ran?", "Would destructive action confirmation, typed confirmation, human approval gate, security warning, or review before submit be more precise?" ], "relatedPatterns": [ "destructive-action-confirmation", "typed-confirmation", "human-approval-gate", "review-before-submit", "security-warning", "warning-text", "approval-workflow", "audit-log", "source-grounding-display", "confidence-uncertainty-display" ], "comparisons": [ "dangerous-action-review-vs-destructive-action-confirmation-vs-typed-confirmation-vs-human-approval-gate-vs-review-before-submit-vs-security-warning" ], "sourceIds": [ "microsoft-human-ai-guidelines", "nist-ai-risk-management-framework", "github-actions-deployment-protection-rules", "microsoft-windows-confirmations", "github-reviewing-proposed-changes" ] }, { "id": "dark-pattern-consent", "completionStatus": "complete", "name": "Dark-pattern consent", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Anti-pattern where consent, cookie, marketing, sharing, or data-use choices are shaped to obtain agreement without a fair, informed, reversible decision", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Consent decisions become untrustworthy when the interface steers users toward acceptance through unequal visual weight, more steps to refuse, hidden decline, preselected options, bundled purposes, consent walls, repeated nags, misleading legal bundling, or optional processing that starts before the user chooses.", "solution": "Flag dark-pattern consent as an anti-pattern, then rebuild the flow around freely chosen, specific, informed, affirmative, granular, reversible consent with comparable accept and reject effort, clear withdrawal, purpose-level records, and runtime enforcement that blocks optional processing until the matching choice exists.", "uiGuidance": [ "Do not make acceptance easier, larger, brighter, faster, or less costly than refusal when the user is deciding optional consent, cookie tracking, marketing, research, AI training, partner sharing, personalization, or sensitive-data use.", "Replace manipulative consent with equal-level accept and decline actions, off-by-default optional purposes, clear purpose labels, no processing before choice, visible withdrawal, and evidence records that match the actual visible decision." ], "uxGuidance": [ "Treat consent obtained through obstruction, pressure, confusing copy, hidden refusal, preselected categories, consent walls, repeated prompts, bundled purposes, or continued-browsing assumptions as an anti-pattern, not as a valid completed consent flow.", "Design the flow so users can decline, customize, withdraw, and continue eligible work with comparable effort and without losing task context or being punished for refusal." ], "uiExamples": { "good": [ "A cookie surface shows Accept all, Reject all, and Manage choices at the same level, with analytics and advertising off until selected.", "A research consent prompt has clear Yes and No thanks buttons, names the requester and data, and records refusal without blocking the core service.", "A marketing opt-in during checkout starts unchecked and sits outside the required terms checkbox, with a later unsubscribe or withdrawal route." ], "bad": [ "Accept all is a large primary button while Reject all is a low-contrast link in a second layer.", "A checkout checkbox says I agree to terms and updates but also opts users into marketing and partner sharing.", "The site loads advertising pixels before asking and then records banner acceptance as if it happened first." ] }, "uxExamples": { "good": [ "A user rejects advertising cookies, completes the service, and later opens privacy settings to enable analytics only.", "A user declines AI training for workspace content, sees that the feature still works without training use, and can revisit the choice later.", "A user withdraws research contact consent from the same purpose label used during signup, and future contact stops." ], "bad": [ "A user clicks Continue to dismiss a modal and unknowingly consents to marketing, analytics, and partner sharing.", "A user tries to reject cookies but must open several screens while Accept all remains one click.", "A user declines once and is shown the same consent prompt on every page until they accept." ] }, "problemContext": [ "The surface asks for optional data use, marketing, research contact, AI training, partner sharing, personalization, sensitive-data use, non-essential cookies, local storage, advertising tags, analytics tags, or similar tracking.", "Consent may be presented during onboarding, checkout, account creation, cookie banners, cookie settings, preference centers, privacy settings, app permission explanations, beta enrollment, or legal-acceptance-adjacent flows.", "Users may face misleading hierarchy, disabled-looking refusal, confirmshaming copy, repeated prompts, bundled terms, preselected choices, unavailable service after refusal, or a mismatch between visible choice and runtime processing.", "The organization may later rely on the record as evidence, so the design must prove what the user saw, whether refusal was reachable, and whether optional processing was blocked until consent." ], "selectionRules": [ "Flag this anti-pattern when accepting optional consent is one click but declining, customizing, or withdrawing requires extra pages, hidden links, confusing labels, or repeated confirmation.", "Flag it when optional purposes are preselected, bundled into terms, bundled together despite separable purposes, or hidden behind a broad agree and continue action.", "Flag it when refusal is visually de-emphasized, disabled-looking, below the fold, delayed, shamed, worded as a negative consequence, or absent from the same decision level.", "Flag it when optional processing, tracking, sharing, marketing, AI training, or personalization starts before the user has made the matching choice.", "Flag it when the product blocks eligible service access, repeats prompts, or makes core tasks harder after refusal for an optional purpose.", "Use consent prompt for the corrected active opt-in pattern for optional non-cookie data use.", "Use cookie consent for the corrected purpose-level runtime model for cookies, pixels, tags, SDKs, local storage, and similar technologies.", "Use cookie banner for the first-layer cookie choice surface; a cookie banner can itself contain dark-pattern consent if reject, manage, or withdrawal is manipulated.", "Use legal acceptance for required terms, conditions, policies, or contracts; do not hide optional consent inside legal acceptance.", "Use preference center or privacy settings when users later manage durable choices, withdrawal, purpose toggles, account privacy, or browser signal consequences." ], "requiredStates": [ "Accept-dominant state where accept is easier or more visually prominent than reject.", "Hidden reject state where decline is behind another layer, link, scroll, or misleading label.", "Preselected optional purpose state.", "Bundled purposes state for marketing, research, AI training, personalization, partner sharing, or analytics.", "Consent wall or refusal punishment state.", "Processing-before-choice state where optional tags, sharing, or training start before consent.", "Repeated prompt or nag state after refusal.", "Hard-to-withdraw state where revocation is harder than accepting.", "Corrected equal-choice state with accept, reject, and manage at the same decision level.", "Corrected granular purpose state with optional purposes off until selected.", "Corrected withdrawal state that stops future processing and records the change.", "Mobile compact state where reject, manage, purpose, and withdrawal path remain visible." ], "interactionContract": [ "Acceptance, rejection, customization, and withdrawal must be reachable with comparable effort for optional purposes.", "Optional purposes start off unless a current valid record exists for the same purpose, version, requester, region, and user.", "Consent is not inferred from scrolling, closing, continuing to browse, inactivity, account creation, payment, or unrelated legal acceptance.", "Separate purposes are split into separate choices unless they are truly inseparable.", "Refusal preserves eligible service access and task progress when the purpose is optional.", "Optional processing, tracking, sharing, or training is blocked until the matching consent state exists.", "Withdrawal changes the same runtime and record used by the original prompt.", "The record preserves purpose, copy version, requester or controller, data involved, user, timestamp, source surface, refusal or withdrawal state, and runtime enforcement outcome." ], "implementationChecklist": [ "Inventory every consent surface and record accept path, reject path, manage path, withdrawal path, default state, processing start time, and stored evidence.", "Compare the number of steps, visual prominence, wording, keyboard order, and mobile visibility of accept, reject, customize, and withdraw actions.", "Turn off optional purposes by default and split independent purposes into separate choices.", "Remove consent walls, forced acceptance, repeated nags, confirmshaming, deceptive contrast, hidden reject links, preselected options, and bundled legal or marketing choices.", "Block optional cookies, pixels, tags, SDKs, sharing, marketing, AI training, and personalization until the matching purpose is accepted.", "Record accept, reject, customize, withdrawal, renewal, stale, and failed-write outcomes with purpose and version.", "Test accept, reject, customize, withdrawal, renewal, mobile compact, keyboard order, screen-reader labels, browser privacy signal, no-JavaScript, and runtime proof that optional processing is blocked." ], "commonMisuses": [ "Showing Accept all as the only button and hiding Reject all inside Manage settings.", "Preselecting optional marketing, analytics, personalization, or partner-sharing toggles.", "Treating continued browsing, closing, scrolling, swiping, or inactivity as consent.", "Using shame copy such as No, I do not want privacy or I prefer worse service for refusal.", "Bundling optional marketing or partner sharing inside required terms acceptance.", "Starting tracking, sharing, or AI training before consent is captured.", "Making withdrawal harder to find or complete than the original acceptance.", "Repeating a prompt after refusal until the user accepts." ], "critiqueQuestions": [ "Can users reject or customize with effort comparable to accepting?", "Are any optional purposes preselected or bundled into legal terms or another purpose?", "Does the product process, track, share, market, or train before the matching consent exists?", "Does refusal preserve eligible service access and task progress?", "Can users withdraw later from a stable route using the same purpose labels?", "Does the evidence record prove what prompt version, choices, and runtime behavior existed at the time of the decision?", "Is this a dark-pattern consent issue, or should the corrected surface be consent prompt, cookie consent, cookie banner, legal acceptance, preference center, or privacy settings?" ], "relatedPatterns": [ "consent-prompt", "cookie-consent", "cookie-banner", "legal-acceptance", "preference-center", "privacy-settings", "permission-prompt-with-no-context", "confirmation-fatigue" ], "comparisons": [ "dark-pattern-consent-vs-consent-prompt-vs-cookie-consent-vs-cookie-banner-vs-legal-acceptance-vs-preference-center" ], "sourceIds": [ "ico-valid-consent", "ico-obtain-record-manage-consent", "edpb-consent-summary-2026", "edpb-cookie-banner-taskforce-report", "cnil-cookies-tracking-guidelines", "nng-permission-requests", "ftc-dot-com-disclosures" ] }, { "id": "dashboard-layout", "completionStatus": "complete", "name": "Dashboard layout", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Page-level arrangement of coordinated status, metric, and analysis widgets", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to monitor several related metrics, exceptions, and analyses at once, but unstructured dashboard pages bury priority, hide scope and freshness, and make tiles look independent even when filters, snapshots, and drill paths affect interpretation.", "solution": "Provide a dashboard layout with explicit purpose, hierarchy, responsive grid, named sections, global filter scope, tile-level titles and freshness, coordinated widgets, exception emphasis, drill paths, and failure states for stale, empty, permission-limited, and partially loaded data.", "uiGuidance": [ "Arrange dashboard widgets into a purposeful page hierarchy with a named dashboard, scope, freshness, global filters, primary KPIs, secondary analysis, exceptions, and supporting tables or links placed according to monitoring priority.", "Use a responsive grid, containers, tile sizes, section headings, consistent gutters, widget titles, source/freshness labels, and clear empty, stale, filtered, and permission-limited states so the dashboard remains understandable when cards reflow or resize." ], "uxGuidance": [ "Use dashboard layout when users need one page to monitor several related signals, compare current state against targets, spot exceptions, and decide which detailed view or workflow to open next.", "Keep global controls, cross-filtering, drill paths, and widget dependencies explicit so users can tell whether a tile is a snapshot, a live metric, a filtered visual, a link into detail, or an action-driving exception." ], "uiExamples": { "good": [ "An operations dashboard opens with date range, region filter, last updated time, four KPI cards, an exception panel, a trend chart, and a priority table in a stable grid.", "A sales dashboard groups revenue, pipeline, conversion, and risk widgets into labelled sections with consistent card widths, visible targets, and a detail link from each tile." ], "bad": [ "A dashboard is a wall of same-sized charts with no primary metric, no filter scope, no freshness, and no explanation of which tile matters first.", "A responsive dashboard collapses filters and alerts below the fold while leaving decorative charts above the operational exceptions." ] }, "uxExamples": { "good": [ "A manager changes Region to West, sees every tile show the same filtered scope and updated timestamp, then opens the exception table from the SLA breach card.", "An analyst collapses supporting commentary, expands the risk section, and the dashboard preserves KPI context, global filters, and keyboard focus." ], "bad": [ "A user sees revenue down on one tile but cannot tell whether it is filtered, stale, a pinned snapshot, or live data.", "Clicking a chart tile changes several other widgets without visible cross-filter state, so users make decisions from a silently narrowed dashboard." ] }, "problemContext": [ "The page combines several widgets such as KPI cards, charts, tables, maps, alerts, summaries, filters, saved views, or action queues.", "Users need overview and triage before they choose a deeper report, table, chart, record, or workflow.", "Widgets may share global filters, cross-filter each other, refresh at different times, come from different sources, or represent pinned snapshots.", "The layout must survive responsive breakpoints, role-based permissions, missing data, slow widgets, long labels, and user customization.", "Dashboards often become operational artifacts, so their hierarchy, filters, and freshness need to be auditable and explainable." ], "selectionRules": [ "Choose dashboard layout when the user's task is monitoring or triaging multiple related signals on one page.", "Use data visualization when one chart or analytic question is the main object rather than a page-level arrangement of widgets.", "Use table or data grid when exact row comparison, editing, export, or bulk operations are primary.", "Use saved view when the main object is a named presentation state for one data surface, not a multi-widget overview.", "Use summary box when the page only needs a highlighted text summary or next-step block rather than a full monitoring canvas.", "Use card grid when peer object cards are being browsed, not when widgets with different data roles are composed into a monitoring page.", "Place the most decision-critical and frequently checked indicators before supporting charts, commentary, and long tables.", "Avoid dashboard layout when widgets are unrelated, decorative, or cannot share clear scope, source, freshness, or interpretation rules.", "Avoid making dashboards the default answer for every report; if users need one exact answer, route them to the narrower report or data surface.", "Avoid hiding filters, stale data, permission gaps, or cross-filter state because those determine whether the dashboard can be trusted." ], "requiredStates": [ "Default dashboard with name, purpose, global scope, active filters, freshness, KPI tier, sections, and widget grid.", "Global filtered, cross-filtered, tile-filtered, cleared-filter, stale-widget, partial-refresh, and mixed-refresh states.", "Widget loading, empty, no-access, error, hidden-by-permission, data-delayed, and source-unavailable states.", "Collapsed section, expanded section, pinned or resized widget, customized layout, reset layout, and saved dashboard state when customization exists.", "Drill path from a KPI, chart, exception, or table into the relevant report, saved view, record list, or workflow.", "Mobile and narrow-screen state where dashboard identity, filters, freshness, exceptions, and critical KPIs remain reachable before secondary widgets." ], "interactionContract": [ "Dashboard title, purpose, active filters, and last updated time apply visibly to the widgets they govern.", "Each tile states what it measures, its unit or target, its source or freshness when relevant, and what happens when users select it.", "Global filters update every governed widget or mark exceptions where a widget is not affected.", "Cross-filtering and drill interactions leave visible state, a clear reset path, and do not silently change unrelated widgets.", "Pinned snapshots, live tiles, cached widgets, and manually refreshed cards are labelled differently when users could interpret freshness incorrectly.", "Responsive reflow preserves priority order, section grouping, widget titles, filters, and exceptions instead of merely packing cards into available space.", "Permission-limited widgets explain what is missing without leaking private metrics, names, counts, or report titles.", "Keyboard focus remains predictable after filters, collapse/expand, refresh, drill, or responsive reordering." ], "implementationChecklist": [ "Define dashboard purpose, audience, refresh cadence, data sources, global filters, key metrics, exception rules, target thresholds, and drill destinations before placing widgets.", "Map the page hierarchy: first-read KPIs, operational exceptions, explanatory charts, supporting tables, source notes, and secondary links.", "Use a responsive grid with stable gutters, minimum tile widths, section containers, and priority-based ordering across breakpoints.", "Model widget metadata: title, description, source, scope, unit, target, freshness, permission, loading, error, stale, empty, and drill URL.", "Show active global filters, cross-filter state, last refresh time, partial refresh failures, and reset controls near the dashboard or affected section.", "Test long metric names, missing widgets, slow widgets, role-limited users, mobile width, zoom, keyboard order, screen readers, stale data, and mixed refresh cadence.", "Keep customizable layout state separate from data filters and provide reset, save, and unsaved-change handling when users can rearrange tiles.", "Log dashboard edits, shared changes, and data-source failures when the dashboard drives operational decisions." ], "commonMisuses": [ "Filling a page with charts before defining dashboard purpose, audience, hierarchy, and decisions.", "Making every widget the same size even though only a few metrics drive action.", "Hiding global filters, cross-filter state, source, freshness, or stale data.", "Mixing live tiles, pinned snapshots, cached reports, and manual refresh cards with no freshness distinction.", "Letting responsive reflow push filters, exceptions, or critical KPIs below decorative content.", "Using dashboard layout when a single chart, table, saved view, summary box, or workflow page would answer the task faster.", "Showing permission-limited blank spaces with no explanation or leaking restricted metric names.", "Allowing dashboard customization to break shared layout, keyboard order, or widget relationships." ], "critiqueQuestions": [ "What decision or monitoring task does this dashboard support, and which widgets matter first?", "Can users see active filters, scope, source, freshness, and cross-filter state before trusting the numbers?", "Which widgets are live, cached, pinned snapshots, manually refreshed, partial, empty, or permission-limited?", "Does responsive order preserve the dashboard's priority and section relationships?", "What happens when a widget fails, refreshes later than others, or is unavailable to this user?", "Would one chart, table, saved view, summary box, card grid, or report page serve the task better than a dashboard?" ], "relatedPatterns": [ "data-visualization", "table", "data-grid", "card-grid", "saved-view", "filter-panel", "chart-drilldown", "compare-view", "alert", "loading-skeleton", "empty-state" ], "comparisons": [ "dashboard-layout-vs-data-visualization-vs-table-vs-saved-view" ], "sourceIds": [ "microsoft-power-bi-dashboard-design-tips", "microsoft-power-bi-dashboard-tiles", "tableau-dashboard-size-layout", "material-responsive-layout-grid", "microsoft-power-bi-visualizations-overview" ] }, { "id": "data-export", "completionStatus": "complete", "name": "Data export", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "User or administrator workflow for selecting, preparing, securing, downloading, transferring, and verifying data export packages", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Data export workflows become risky when they hide scope, confuse export with deletion or import, omit format and portability limits, expose sensitive archives through weak links, or provide no recovery when a long-running export is partial, delayed, expired, or failed.", "solution": "Provide a scoped export workflow that explains eligible data, category selection, format, destination, identity or permission checks, job progress, manifest, omissions, package security, expiry, download or transfer actions, retry paths, and completion evidence.", "uiGuidance": [ "Render data export as a job-based workflow with export scope, data categories, format, destination, estimated size, preparation status, expiry, security requirements, and download or transfer actions.", "Show what is included, excluded, redacted, delayed, permission-limited, or unavailable before the export starts; keep package readiness, partial success, failure, and link expiry visible until resolved." ], "uxGuidance": [ "Use data export when users need a portable copy of personal, account, workspace, product, activity, or organization data for reuse, compliance, migration, backup, or review.", "Protect trust by separating export from deletion, import, audit evidence, reporting, and settings changes; make identity checks, sensitive-data handling, package retention, and recovery explicit." ], "uiExamples": { "good": [ "A privacy dashboard lets a user choose activity, profile, files, messages, and billing categories, shows JSON or CSV availability, requires reauthentication, creates archive EXP-2048, then shows download expiry and checksum.", "An admin export page shows workspace data families, estimated size, cloud archive destination, support requirements, preparation progress, partial failures, and a manifest before download." ], "bad": [ "A button says Export all data but does not say which services, formats, accounts, dates, or unavailable records are included.", "The export link stays valid forever, exposes sensitive files to the wrong account, and is presented next to Delete account as though export deletes data." ] }, "uxExamples": { "good": [ "A user requests a machine-readable archive, sees which data categories are eligible for portability, waits for preparation, downloads the package before expiry, and gets a manifest listing omitted records.", "A workspace owner exports organization data to a cloud archive, sees that chat history is delayed, retries the failed category, and verifies that the final package matches the visible scope." ], "bad": [ "A user downloads a huge ZIP with no manifest, cannot tell whether messages or attachments are missing, and assumes export completed because one file downloaded.", "A support admin exports another user's data without role explanation, approval, redaction, audit trail, or notification." ] }, "problemContext": [ "The exported data may include personal information, activity history, files, messages, contacts, billing records, audit records, workspace content, settings, generated outputs, or organization archives.", "Exports may be requested by account holders, admins, compliance staff, support agents, organization owners, or migration operators.", "The export may be synchronous for small tables, asynchronous for archives, category-scoped for privacy dashboards, destination-based for cloud archives, or API-driven for enterprise tools.", "Data may be unavailable because of retention, permission, product support, legal hold, deleted objects, redaction policy, processing delay, or format limits." ], "selectionRules": [ "Choose data export when the user needs a copy or transfer of existing data outside the current product workflow.", "Use bulk import when the task is bringing structured records into the product, including mapping and validation, rather than taking data out.", "Use audit log when the primary task is governed event evidence; data export may package audit records but does not replace audit-log review.", "Use table or data grid export for local row downloads when the scope is one visible dataset; use data export when the workflow needs account, workspace, category, privacy, retention, or package handling.", "Use sensitive-data reveal when the task is briefly exposing one protected value, not preparing a portable archive.", "Require identity, permission, or approval checks when export contains sensitive personal data, organization data, financial data, private files, or another user's records.", "Show data categories, date range, services, account, workspace, format, destination, estimated size, and expected preparation time before starting export.", "State whether export includes deleted, archived, redacted, unavailable, retained, encrypted, or third-party data.", "Provide a manifest, checksum, package ID, or export reference when users need to verify what was produced.", "Keep export distinct from delete account, privacy setting changes, consent withdrawal, notification preferences, and migration import actions." ], "requiredStates": [ "Eligible data categories and unavailable categories state.", "Category selection, date range, account, workspace, format, and destination state.", "Identity verification, permission check, approval required, or policy blocked state.", "Export requested, queued, preparing, estimating size, compressing, and packaging states.", "Large export background job with progress, expected wait, and notification route.", "Partial export with omitted records, redacted fields, failed categories, and retry actions.", "Export ready with package ID, expiry time, size, format, checksum or manifest, and download action.", "Secure download, transfer to another service, copy link, expired link, and regenerate link states.", "Export failed, canceled, rate limited, storage full, unsupported format, and recovery states.", "Post-download state that explains export does not delete source data and records completion where appropriate." ], "interactionContract": [ "Export scope is explicit before the job starts and remains visible through progress, completion, failure, and download.", "The product does not imply that export removes, deletes, imports, transfers, or anonymizes source data unless that separate action is actually happening.", "Start export records selected categories, filters, format, destination, requester, account or workspace, and timestamp.", "Long-running exports can be left and resumed from a status page, notification, email, or job history without losing context.", "Ready packages show expiry, size, format, checksum or manifest, sensitive-data warning, and the account or destination that can download them.", "Partial or failed exports name affected categories and provide retry, regenerate, support, or archive-request paths.", "Export links, API tokens, and package URLs are time-limited, permission-checked, and do not expose data to the wrong account.", "After download or transfer, the UI states whether the package was downloaded, transferred, expired, canceled, or still available." ], "implementationChecklist": [ "Model export jobs with request ID, requester, account/workspace, category set, filters, date range, format, destination, status, package ID, expiry, manifest, checksum, and error details.", "Classify export data by sensitivity, portability eligibility, file size, product support, retention, legal hold, redaction, and permission requirements.", "Add identity verification, role check, approval, or policy gates for sensitive, admin, organization, or cross-user exports.", "Provide progress for queued, preparing, packaging, ready, partial, failed, canceled, expired, and regenerated-link states.", "Generate a manifest that names included categories, omitted categories, redacted fields, unavailable products, file counts, record counts, format, and timestamps.", "Make download links short-lived and account-bound; support link regeneration and clear expired-link recovery.", "Test large archives, many categories, slow packaging, failed category, partial result, expired link, wrong account, mobile download handoff, storage limits, and screen-reader progress updates.", "Log export requests and downloads without logging raw exported contents in unrelated telemetry." ], "commonMisuses": [ "Using one Export all button with no scope, format, account, destination, date range, or size estimate.", "Confusing export with delete account, privacy preference changes, migration import, or audit-log investigation.", "Leaving sensitive export archives available forever or downloadable by any signed-in user with the link.", "Claiming the export is complete when categories failed, were redacted, or were outside retention.", "Exporting only visible table rows while labelling the result as full account data.", "Putting raw secrets, tokens, private files, or AI prompts into export manifests where broad admins can see them.", "Failing silently after a long-running export job expires or hits an archive size limit." ], "critiqueQuestions": [ "What exact data categories, services, date range, account, workspace, and format are included?", "Which data is not eligible, redacted, delayed, deleted, archived, outside retention, or permission-limited?", "What identity, role, approval, or policy check protects the export?", "How does the user verify the package contents: manifest, checksum, file count, record count, or package ID?", "How long is the package available, who can download it, and how can an expired link be regenerated?", "Does the interface clearly say that exporting data does not delete, import, or transfer source data unless a separate action occurs?" ], "relatedPatterns": [ "bulk-import", "audit-log", "activity-log", "table", "data-grid", "file-upload", "sensitive-data-reveal", "permission-denied-state", "notification-center", "settings-management" ], "comparisons": [ "data-export-vs-bulk-import-vs-audit-log-vs-table-vs-sensitive-data-reveal" ], "sourceIds": [ "ico-right-to-data-portability", "dataprotection-ie-right-to-data-portability", "google-workspace-data-export-tool", "microsoft-privacy-dsr-export-msa", "google-takeout-download-data" ] }, { "id": "data-grid", "completionStatus": "complete", "name": "Data grid", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Interactive row-and-column data workspace", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to inspect, select, edit, sort, filter, copy, or operate on many records in rows and columns, but a basic table becomes slow or unsafe when every cell, widget, and row action is placed in normal tab order or when editing has no grid focus contract.", "solution": "Provide a data grid with a labelled dataset, visible column and row identity, one managed entry point in page tab order, arrow-key cell navigation, explicit edit mode, stable selection, truthful row and column metadata, and recovery for sorting, filtering, virtualization, validation, and saving.", "uiGuidance": [ "Render the grid as a named work surface with visible headers, row identifiers, focus location, selection state, dirty and invalid cell markers, column controls, and status text for row count, sort, filter, and save state.", "Keep visual density deliberate: align values for scanability, separate focus from selection, expose readonly and editable cells, and provide a compact but reachable toolbar for grid-level actions." ], "uxGuidance": [ "Use a data grid when cell-level interaction makes users faster and more accurate than opening each record separately.", "Treat focus, edit mode, selection, validation, save, sort, filter, virtual scroll, and pagination as one workflow contract instead of isolated features." ], "uiExamples": { "good": [ "An invoice-review grid shows frozen invoice IDs, column headers for Vendor, Amount, Due, Owner, and Status, one highlighted focused cell, two selected rows, a dirty edited amount, and a status line naming the current cell.", "A virtualized asset grid shows row 41 of 2,000, col 5 of 12, a selected range, and a toolbar with Sort, Filter, Columns, Copy, and Save changes commands." ], "bad": [ "A static report uses role grid even though users only read values and ordinary table semantics would be clearer.", "Every cell is an input or menu in page tab order, so reaching the Save button requires tabbing through hundreds of controls." ] }, "uxExamples": { "good": [ "A user presses Arrow Right to move from Amount to Due, presses Enter to edit the due date, presses Escape to cancel, and focus returns to the same cell in navigation mode.", "A user pastes three invalid amounts, sees each invalid cell marked with a message, fixes them in place, saves, and the grid keeps selection and scroll position after the server responds." ], "bad": [ "A user edits an amount, sorts by status, and the row disappears with no saved or unsaved indication.", "A keyboard user opens a cell menu and cannot return to the same grid cell or leave the grid without reloading the page." ] }, "problemContext": [ "The task involves many records with shared columns, and users repeatedly move across cells or down columns to compare, update, or triage values.", "Cells may contain editable values, links, menus, checkboxes, validation, calculated values, row actions, or status widgets.", "Users need keyboard-efficient navigation that avoids hundreds of tab stops while keeping cell identity and row context clear.", "The product may virtualize rows or columns, hide columns, sort, filter, pin, paginate, copy, paste, or save individual cell changes." ], "selectionRules": [ "Choose data grid when row-and-column data is interactive enough to require managed cell focus, arrow-key movement, selection, editing, or keyboard shortcuts.", "Use a table when records are mainly read-only comparison and ordinary links, buttons, or checkboxes in row order are sufficient.", "Use inline edit when one displayed value or one row enters local edit mode without full spreadsheet-style navigation.", "Use tree grid instead of data grid when rows are hierarchical and expandable while still needing columns.", "Use list view, card list, or card grid when object summaries, imagery, or uneven metadata matter more than column-by-column work.", "Use transfer list when the task is moving items between sets rather than editing cells in place.", "Use pagination, infinite loading, or saved views to control very large row counts, but do not let paging erase grid focus, selection, or edit state.", "Avoid data grid when the task is a form with unrelated fields, section dependencies, or review-before-submit consequences.", "Avoid data grid when the team cannot implement and test keyboard navigation, focus movement, edit mode, row and column metadata, and screen reader behavior.", "Avoid forcing a dense data grid onto mobile when a list-plus-detail or focused edit route would preserve task accuracy better." ], "requiredStates": [ "Default navigation state with labelled grid, column headers, row headers or row identifiers, focused cell, and row count context.", "Focused-cell state that distinguishes focus from selection and survives movement across rows and columns.", "Selected row, selected cell, selected range, and bulk-selected states when selection is supported.", "Edit mode for a cell or row, with clear entry, focused editor, dirty draft, save, cancel, and validation states.", "Readonly or locked-cell state for cells that can be navigated but not changed.", "Sorted, filtered, grouped, hidden-column, and resized-column states with visible and programmatic state feedback.", "Virtualized, paginated, or lazy-loaded state with truthful total row and column counts, visible indices, and loading boundaries.", "Copied, pasted, invalid paste, undo, redo, saving, saved, failed-save, and conflict states when grid editing supports those actions.", "Empty, no-results, permission-restricted, and partial-data states that keep the grid label and recovery path visible.", "Narrow-screen or reduced-column state that preserves row identity, edit safety, and a route to the full task." ], "interactionContract": [ "Tab moves into the grid at one managed focus point and out to the next page control rather than visiting every cell by default.", "Arrow keys move focus between cells; Home, End, Page Up, Page Down, and modified Home or End commands move by row, viewport, or grid boundary according to the documented contract.", "The focused cell, selected cell, selected row, checked row, active editor, hover target, and row action are visually and programmatically distinct.", "Column headers that sort, filter, resize, pin, or open menus are reachable and announce their current state.", "Entering edit mode with Enter, F2, typing, or an explicit Edit command moves focus into the editor and temporarily changes how arrow keys are interpreted.", "Escape cancels editing or returns to grid navigation according to a visible and tested discard contract.", "Saving a cell, row, or pasted range keeps the edited location understandable after sorting, filtering, pagination, refresh, or server validation.", "Virtualization, hidden columns, frozen areas, and pinned rows must not make row or column indices, reading order, or focused-cell restoration untrue." ], "implementationChecklist": [ "Define the grid purpose, row object, primary row identifier, columns, editable fields, readonly fields, selection model, and supported shortcut set.", "Choose native table plus role grid or ARIA row and gridcell structure only when the interaction truly behaves as a grid.", "Expose a label or labelled heading for the grid and a description for keyboard help, row count, filters, or selection status.", "Use row, columnheader, rowheader, and gridcell semantics, and provide aria-rowcount, aria-colcount, aria-rowindex, and aria-colindex when rows or columns are virtualized or hidden.", "Keep only the current managed cell or inner widget in the page tab sequence and update tabIndex as focus moves.", "Separate navigation mode from edit mode, including how Enter, F2, typing, Escape, Tab, arrow keys, and Save behave.", "Associate validation messages, dirty indicators, readonly state, and save errors with the affected cell or row.", "Preserve focused cell, selected rows, expanded detail, dirty edits, and scroll position across sort, filter, pagination, refresh, and column visibility changes where possible.", "Test with keyboard only, screen readers, high contrast, zoom, row virtualization, long values, pasted invalid data, mobile viewports, and assistive-technology reading order." ], "commonMisuses": [ "Using role grid on a static table only to make it sound richer.", "Putting hundreds of inputs, menus, and links into normal tab order instead of implementing managed focus.", "Calling a dense settings form a data grid even though fields do not share row and column meaning.", "Letting arrow keys both navigate cells and operate the active cell editor without an edit-mode boundary.", "Hiding columns or virtualizing rows without row and column counts, indices, or truthful reading order.", "Using color alone for selected, dirty, invalid, readonly, and saved cell states.", "Sorting or filtering while a cell is dirty and moving it out of view before users can confirm the result.", "Packing row actions, nested menus, multiselect widgets, and expandable detail into cells without a tested focus strategy." ], "critiqueQuestions": [ "What does one row represent, and what is the primary row identifier?", "Which cells are navigable, editable, readonly, selected, invalid, dirty, or saving?", "Can a keyboard user enter the grid, move by cell, edit, cancel, save, select, copy, and leave without getting trapped?", "When does focus land on the cell itself versus an element inside the cell?", "What happens to focus, selection, dirty edits, and validation after sort, filter, pagination, virtual scroll, refresh, or save failure?", "Would a table, inline edit, list view, card layout, transfer list, or complex form solve the task with less interaction cost?" ], "relatedPatterns": [ "table", "inline-edit", "pagination", "sort-controls", "filter-panel", "transfer-list", "details-panel", "empty-state" ], "comparisons": [ "data-grid-vs-table-vs-inline-edit-vs-pagination" ], "sourceIds": [ "wai-aria-apg-grid", "wai-aria-apg-data-grid-examples", "mdn-aria-grid-role", "ag-grid-accessibility", "mui-data-grid-accessibility" ] }, { "id": "data-visualization", "completionStatus": "complete", "name": "Data visualization", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Encoded visual analysis of quantitative or categorical data", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to understand patterns, magnitude, trend, distribution, composition, relationship, anomaly, or uncertainty in data, but raw tables and summaries make those patterns slow or impossible to see.", "solution": "Provide an honest data visualization with appropriate chart type, explicit encodings, axes, units, scale, legend, annotation, tooltip or selected-point detail, filter and freshness context, accessible chart interaction, and a synchronized data alternative.", "uiGuidance": [ "Render a chart with a specific analytic question, title, dataset scope, mark type, axis labels, units, tick labels, scale baseline, legend, annotations, source or freshness note, selected mark, tooltip or detail, and data table alternative.", "Map data fields to visual encodings intentionally: position, length, color, size, shape, opacity, grouping, faceting, and order must each have a clear data meaning and a text or pattern backup when color or shape carries state." ], "uxGuidance": [ "Use Data visualization when visual encoding helps users detect trends, comparisons, rankings, distributions, relationships, outliers, part-to-whole composition, or uncertainty faster than reading rows.", "Keep analysis honest: chart type, scale, baseline, aggregation, filters, missing data, sampling, normalization, annotations, and interaction state must stay visible enough that users can judge what the visual does and does not prove." ], "uiExamples": { "good": [ "A revenue trend chart shows month on the x-axis, revenue in USD on the y-axis, a target line, color-coded channels with legend labels, selected month tooltip, annotation for a campaign, and a data table toggle.", "A defect distribution chart uses a histogram with bin labels, count units, median marker, visible filter scope, sample size, and a note explaining excluded test environments." ], "bad": [ "A glossy chart card shows unlabeled bars with no axis, unit, baseline, data range, source, or explanation of what the colors mean.", "A pie chart compares monthly time-series revenue and hides exact values until mouse hover, so users cannot read the trend or inspect values with keyboard." ] }, "uxExamples": { "good": [ "An analyst switches from revenue to conversion rate, the y-axis unit changes, target and annotation stay aligned, and the selected month tooltip and table row update from the same data.", "A manager highlights Enterprise channel, sees its contribution, toggles normalized view, and receives a clear disclosure that values are shown as percent of monthly total." ], "bad": [ "A dashboard truncates the y-axis to exaggerate a small change without indicating the baseline, leading a team to overreact.", "A chart filter removes the low-performing segment but the legend and annotation still describe the full dataset." ] }, "problemContext": [ "The task involves quantitative, categorical, temporal, ordinal, or relational data where visual pattern recognition is useful.", "Users may need to compare categories, spot trends, inspect anomalies, understand distributions, see relationships, or communicate evidence.", "Visualizations can mislead when axes, units, baselines, aggregation, sampling, filters, color meaning, and missing data are hidden.", "Interactive charts may include tooltips, selection, legend filtering, brushing, zooming, drilldown, annotations, and data table exports.", "Charts need alternatives for keyboard users, screen-reader users, low-vision users, and users who need exact values." ], "selectionRules": [ "Choose Data visualization when the user's primary task is seeing a pattern, relationship, trend, distribution, ranking, magnitude, or anomaly.", "Use table when exact values, row comparison, export, auditing, or editing records is primary.", "Use map view when geography, distance, route, or spatial density is the primary organizing axis.", "Use activity log when the question is what happened, when, by whom, and to what object.", "Use summary box or card-like metric when a single number is the main fact and visual pattern across data is secondary.", "Use dashboard layout when multiple coordinated visuals and controls need a page-level monitoring arrangement.", "Use chart drilldown when the user must move from aggregate marks to lower-level data while preserving analytic context.", "Match chart type to question: time trend, category comparison, relationship, distribution, composition, ranking, flow, or uncertainty.", "Disclose scale choices, aggregation, filters, data freshness, missing data, and uncertainty near the chart.", "Avoid Data visualization when the visual encoding is decorative, when data volume is too small to reveal a pattern, or when exact record work is the real task." ], "requiredStates": [ "Default chart with title, question, data scope, axes, units, legend, source or freshness note, visible filters, and data alternative.", "Selected mark, focused mark, tooltip open, tooltip dismissed, annotation visible, legend item highlighted, and table row synchronized states.", "Filtered, grouped, faceted, sorted, normalized, compared-to-target, and highlighted-series states.", "Loading, empty data, no matching data, missing values, partial data, stale data, sampled data, and permission-limited data states.", "Axis baseline visible, non-zero baseline disclosed, log scale disclosed, truncated scale disclosed, and percentage or index normalization disclosed states.", "Small-screen state where axes, labels, legend, selected point, and data alternative remain reachable.", "Keyboard navigation through chart controls, selected marks, legend filters, annotations, and table alternative.", "Export image, export data, copy insight, and share-link states when the chart is used for reporting." ], "interactionContract": [ "Each visible mark is derived from the current dataset, filter scope, aggregation, and scale; visual marks and table values must agree.", "Axes, ticks, labels, legends, and annotations explain the mapping between data fields and visual encodings.", "Tooltip and selected-point detail expose exact value, unit, series, category, time, aggregation, source scope, and missing-data status when relevant.", "Legend filtering, metric switching, normalization, brushing, zooming, and sorting update the marks, axes, annotations, summary, and table alternative together.", "Color is never the only way to communicate category, state, threshold, or anomaly.", "Non-zero baselines, log scales, normalized percentages, samples, excluded outliers, and stale data are disclosed before users interpret magnitude.", "Keyboard and assistive-technology users can move through data points or use a synchronized table/summary to get equivalent information.", "Chart exports preserve title, scope, source, filters, timestamp, axes, legends, and disclosure notes." ], "implementationChecklist": [ "Define dataset schema: fields, types, units, category labels, time grain, aggregation, missing values, sample size, source, update timestamp, and permission scope.", "Define visual encoding: chart type, x field, y field, color field, size field, grouping, sort order, scale type, baseline, legend, annotations, and responsive behavior.", "Implement selected-point detail, tooltip, keyboard-accessible data table, legend highlighting, metric switch, normalization disclosure, filter scope, and export metadata.", "Model empty, no-match, loading, stale, partial, missing-value, inaccessible-color, truncated-scale, and narrow-viewport states.", "Test with long labels, negative values, zero values, outliers, missing months, dense points, small screens, high contrast mode, keyboard navigation, and screen-reader summaries.", "Keep chart, textual summary, tooltip, annotations, and data table generated from the same filtered dataset.", "Include chart source, last updated time, aggregation, filters, unit, and caveats close enough to the visual that they are not lost when shared.", "Use a proven charting or visualization library for production chart scales, axes, legends, responsive layout, and interaction semantics." ], "commonMisuses": [ "Using decorative charts that do not answer a data question.", "Choosing a chart type that mismatches the data relationship.", "Hiding axes, units, baseline, scale type, or aggregation.", "Using color alone for category, status, threshold, or anomaly.", "Truncating an axis or using a log scale without disclosure.", "Providing exact values only in pointer hover tooltips.", "Letting legend, filters, annotations, and table values drift out of sync.", "Showing stale, sampled, missing, or normalized data without caveats." ], "critiqueQuestions": [ "What data question does this visualization answer better than a table, map, activity log, or summary metric?", "Can users identify the chart type, dataset scope, axes, units, scale, baseline, aggregation, filters, and source?", "Do color, size, position, shape, and order each map to a clear data field?", "Can users inspect exact values with keyboard and screen-reader paths, not only hover?", "What happens with outliers, missing data, stale data, no data, long labels, small screens, and high contrast mode?", "Would table, map view, activity log, summary box, dashboard layout, or chart drilldown better fit the task?" ], "relatedPatterns": [ "table", "data-grid", "map-view", "activity-log", "timeline", "filter-panel", "details-panel", "progressive-disclosure", "empty-state", "loading-skeleton" ], "comparisons": [ "data-visualization-vs-table-vs-map-view-vs-activity-log" ], "sourceIds": [ "microsoft-power-bi-visualizations-overview", "tableau-visual-best-practices", "vega-lite-encoding", "vega-lite-axis", "vega-lite-legend", "vega-lite-tooltip", "d3-axis", "highcharts-accessibility-module", "wcag-non-text-contrast" ] }, { "id": "date-input", "completionStatus": "complete", "name": "Date input", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Grouped manual exact-date entry", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users often know an exact date, but a single ambiguous field, rigid mask, long year selector, or calendar widget can make entry slower, harder to correct, or inaccessible.", "solution": "Ask the date question once, group visible day/month/year fields under that question, provide a valid example, accept common month forms, validate parts together, preserve typed values, and submit a canonical date only after validation passes.", "uiGuidance": [ "Render day, month, and year as separate text inputs inside one fieldset with a legend that asks the full date question and a hint containing a valid example date.", "Size day and month fields for short values, year for four digits, keep labels visible for each part, and apply error styling to the group and any failing part." ], "uxGuidance": [ "Use date input when users already know the exact date or can look it up without needing calendar context.", "Preserve every typed part, tolerate common month names, normalize to a canonical date only after validation, and explain exactly which part is missing, impossible, or out of range." ], "uiExamples": { "good": [ "A passport issued question uses a fieldset legend, hint example 27 3 2007, separate Day, Month, and Year labels, numeric input mode, and a group error that names the missing year.", "A date of birth field uses bday-day, bday-month, and bday-year autocomplete attributes and still lets users type 7 Jan 1984." ], "bad": [ "A single date field shows DD/MM/YYYY inside the input and removes the only instruction when users start typing.", "Three tiny boxes auto-advance focus after two characters and announce only Day, Month, Year without the date question." ] }, "uxExamples": { "good": [ "A user types 7 Jan 1984, sees month normalized to 01, submits, and reviews canonical value 1984-01-07.", "A user enters 31 2 2026, sees an impossible-date error, fixes only the day, and keeps the month and year values." ], "bad": [ "A user pastes a known birth date into a masked field and the interface discards separators and jumps focus unpredictably.", "A user must open a calendar and navigate decades to enter a birthday they already know." ] }, "problemContext": [ "The date is exact and already known, memorable, or easy to look up from a document.", "The service needs day, month, and year rather than an approximate period or scheduling availability.", "Users may type numeric dates, month names, leading zeros, pasted values, or partially complete values.", "The form needs precise error recovery for missing day, missing month, missing year, impossible dates, and dates outside allowed ranges.", "Birth-date entry may benefit from browser autocomplete attributes that identify day, month, and year separately." ], "selectionRules": [ "Choose date input for exact dates users already know or can find quickly.", "Use a date picker for scheduling, availability, date-range exploration, or tasks where calendar context helps decision making.", "Use ordinary text input for approximate answers such as Spring 2026, about 10 years ago, or unknown month.", "Use select only when the valid date part values are a small meaningful set, not for arbitrary historic years.", "Do not use an input mask that blocks month names, paste, correction, or part-specific validation.", "Use a single question in the legend and separate labels for Day, Month, and Year.", "Use an example date that is valid for the requested date and follows local order.", "Accept full and abbreviated month names where users may type them.", "Validate complete date semantics, not only numeric field lengths.", "Use birth-date autocomplete attributes only for the user's own date of birth." ], "requiredStates": [ "Empty untouched grouped date fields with legend, hint, and visible part labels.", "Focused day, month, or year field without auto-advancing to the next part.", "Partially filled date that preserves other parts while the user edits one part.", "Month-name typed state normalized for validation and canonical storage.", "Missing day, month, or year error state naming the missing part.", "Impossible date error state for combinations such as 31 February.", "Out-of-range error state when the date violates service bounds.", "Valid submitted state showing canonical ISO date and original visible parts.", "Birth-date autocomplete state when collecting the user's own date of birth.", "Mobile numeric keyboard state for numeric day, month, and year entry." ], "interactionContract": [ "Typing, paste, selection, deletion, undo, and correction happen inside each part without automatic focus movement.", "Tab follows normal page order from day to month to year and then to the next control.", "The legend gives the full date question; Day, Month, and Year labels identify each part.", "Hints and errors are associated with the grouped date control and failing parts where possible.", "Month names and abbreviations are accepted when unambiguous and normalized for validation.", "Submitting validates missing parts, numeric ranges, month names, impossible dates, and service date bounds together.", "A successful submission stores a canonical date such as YYYY-MM-DD while preserving visible local part order." ], "implementationChecklist": [ "Define the date being requested, expected order, allowed range, accepted month names, canonical storage format, and whether birth-date autocomplete applies.", "Build a fieldset with a legend, hint, and three labelled text inputs for day, month, and year.", "Use inputmode numeric for numeric fields while keeping text input behavior flexible enough for editing and paste.", "Do not automatically tab between date parts; let keyboard and assistive technology users control focus.", "Validate missing parts, impossible dates, leap years, range boundaries, and future or past constraints on client and server.", "Keep typed values visible after validation errors and put errors near the group before the part inputs.", "Test screen readers, keyboard tab order, voice input, paste, browser autofill, mobile keyboards, localization, zoom, and server-returned errors." ], "commonMisuses": [ "Using one freeform field with disappearing format instructions.", "Using a date picker for a birthday or document date users already know.", "Auto-tabbing between day, month, and year fields.", "Rejecting month names even though users naturally type Jan or January.", "Validating only field length and accepting impossible dates.", "Showing Invalid date without saying which part needs correction.", "Using a year dropdown with hundreds of options.", "Applying birthday autocomplete attributes to dates that are not the user's own birthday." ], "critiqueQuestions": [ "Does the user already know this exact date, or do they need calendar context?", "Will the example date be valid and unambiguous for this question?", "Can users type month names, paste, and correct one part without focus jumps?", "Which part-specific and semantic date errors can occur?", "What canonical date does the backend receive, and how are local date orders handled?", "Should this be approximate text, a date picker, or a range control instead?" ], "relatedPatterns": [ "text-input", "input-mask", "select", "inline-validation", "error-summary" ], "comparisons": [ "date-input-vs-input-mask-vs-text-input-vs-select" ], "sourceIds": [ "govuk-date-input-component", "nhs-date-input-component", "uswds-memorable-date-component", "microsoft-access-input-masks" ] }, { "id": "date-picker", "completionStatus": "complete", "name": "Date picker", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Single-date text field with attached calendar menu", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Scheduling dates often depend on weekdays, nearby alternatives, booking windows, and unavailable days, but a plain field hides that context and a poorly built calendar can block typing, focus, and recovery.", "solution": "Pair a labelled date field with an accessible calendar menu that exposes month navigation, weekday layout, availability restrictions, selected and focused dates, typed fallback, clear validation, and canonical date output.", "uiGuidance": [ "Render a labelled date text field with a persistent format hint and a calendar button that opens a month grid aligned to the field.", "Show the current month and year, weekday headings, previous and next month controls, selected date, today marker, unavailable dates, and clear focus styling without relying on color alone." ], "uxGuidance": [ "Use a date picker when choosing a date requires calendar context such as weekday, nearby availability, booking windows, deadlines, or recent/future scheduling.", "Let users type a valid date manually, explain blocked dates before submission, preserve the selected value across month navigation, and submit a canonical date only after validation passes." ], "uiExamples": { "good": [ "An appointment booking field shows Appointment date, hint mm/dd/yyyy, a calendar button, July 2026 grid, disabled weekends, today marker, and selected July 14 date.", "A hearing scheduler opens the calendar near the current booking window, announces August 2026 after next-month navigation, and keeps the typed field synchronized with the chosen day." ], "bad": [ "A date of birth field opens today with no text fallback and forces users to page backward month by month through decades.", "A grid of unlabeled numbers uses pale grey for unavailable dates but still lets users click them before showing a late error." ] }, "uxExamples": { "good": [ "A user opens the calendar, sees weekends unavailable, moves to August, chooses Tuesday 11 August 2026, and reviews stored value 2026-08-11.", "A keyboard user types 07/16/2026 into the field, tabs to Submit date, and receives the same canonical value as a calendar click." ], "bad": [ "A user selects a disabled Saturday because it was only dimmed, then loses their previous month when the error appears.", "A user choosing a birthday must repeatedly open year navigation and cannot simply type the known date." ] }, "problemContext": [ "The user is selecting one exact date for an appointment, booking, deadline, publication, reminder, or recent/future event.", "The day of week, closeness to today, or nearby availability affects the user's choice.", "Some dates are unavailable because of weekends, holidays, service windows, min and max dates, or capacity rules.", "Users may prefer either pointer selection from the grid or keyboard entry in the text field.", "The service must synchronize visible local format with a backend-safe canonical date." ], "selectionRules": [ "Choose date picker for single-date scheduling when calendar position, weekday, or availability changes the decision.", "Use date input for birthdays, document dates, and other exact remembered dates that users can type faster than they can navigate.", "Use select when there are only a few meaningful date choices, such as three appointment slots or four reporting periods.", "Use text input when approximate wording is acceptable, such as early July or around the end of the month.", "Do not use a calendar picker when the implementation cannot support keyboard navigation, visible labels, typed entry, and focus return.", "Default the open month near the relevant booking window, not always today.", "Show unavailable dates in the grid and explain the rule that makes them unavailable.", "Keep manual date typing available with a persistent format hint.", "Validate typed and picked values against the same min date, max date, and availability rules.", "Avoid automatic form submission when the user selects a day." ], "requiredStates": [ "Closed labelled text field with visible date-format hint and calendar button.", "Open calendar menu with month and year heading, weekday row, previous and next controls, and active focus.", "Today state that is visually distinct from selected date.", "Selected date state synchronized with the text field.", "Unavailable date state for weekends, holidays, outside-window days, or capacity limits.", "Typed valid date state that updates the same canonical value as a grid selection.", "Typed invalid format state that explains the expected date format.", "Out-of-window error state for dates before the minimum or after the maximum.", "Month-navigation state that preserves selection and announces the new month.", "Submitted state showing the canonical YYYY-MM-DD value." ], "interactionContract": [ "Opening the calendar moves focus to the current, selected, or first available date without losing the labelled input context.", "Previous and next month controls update the grid, heading, available dates, and live status together.", "Clicking or pressing Enter on an available day writes the visible field value and canonical date while leaving the form unsubmitted.", "Unavailable days are skipped or blocked and expose a clear reason such as Weekend unavailable.", "Typing a date in the field is parsed on blur or submit against the same rules as a picked date.", "Escape or a close action returns focus to the input or calendar button without clearing a valid selection.", "Submit validates required value, date format, real calendar date, booking window, and availability before storing the date." ], "implementationChecklist": [ "Define the date purpose, allowed range, unavailable-day rules, local display format, canonical storage format, default open month, and whether manual typing is required.", "Build the labelled input, persistent format hint, calendar button, menu, month heading, weekday headings, previous and next month controls, and day buttons with semantic names.", "Represent selected, today, focused, unavailable, out-of-month, open, closed, empty, invalid, and submitted states in design and code.", "Parse typed values flexibly enough for the locale and validate them with the same service rules used by calendar clicks.", "Keep focus order, arrow-key movement, Page Up and Page Down month movement, Home and End week movement, Escape close, and Tab escape behavior testable.", "Announce month changes, selected dates, disabled restrictions, and validation errors to assistive technology.", "Test keyboard-only operation, screen readers, zoom, small viewports, forced colors, localization, server-returned errors, min and max dates, and unavailable dates." ], "commonMisuses": [ "Using a calendar picker for a date of birth or other remembered historic date.", "Removing manual date typing and forcing pointer-only calendar selection.", "Showing only disabled colors without text explaining why a date cannot be selected.", "Letting unavailable dates be selected and failing late on submit.", "Auto-submitting the form when a day receives focus or selection.", "Opening every picker on today even when the valid booking window starts months later.", "Dropping focus after a month change or date selection.", "Using locale-specific date formatting in the field while storing ambiguous slash dates on the backend." ], "critiqueQuestions": [ "Does the user need weekday or availability context, or would manual date input be faster?", "What month should open first for this task's real booking window?", "Which dates are unavailable and how will the interface explain each restriction?", "Can users type the date, choose it with a pointer, and choose it with the keyboard?", "What happens to focus after opening, navigating months, selecting, closing, and submitting?", "How does the displayed date format map to canonical storage and localization?" ], "relatedPatterns": [ "date-input", "select", "text-input", "inline-validation", "error-summary", "input-mask" ], "comparisons": [ "date-picker-vs-date-input-vs-select-vs-text-input" ], "sourceIds": [ "uswds-date-picker-component", "carbon-date-picker-component", "cms-calendar-picker-component" ] }, { "id": "date-range-picker", "completionStatus": "complete", "name": "Date range picker", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Two date fields with attached range calendar and apply controls", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Range tasks require users to understand two dates as one continuous span, but separate single-date controls hide included days, invalid order, presets, and whether changes have already affected the underlying data.", "solution": "Provide labelled start and end fields tied to one calendar range surface that highlights the span, supports presets and manual entry, validates boundary order and duration, and applies or cancels the complete range deliberately.", "uiGuidance": [ "Render separate labelled start and end date fields with persistent format hints, a calendar trigger, and a shared calendar menu that shows both endpoints and the days between them.", "Show selected start, selected end, in-range days, hover preview, disabled dates, min and max bounds, preset options, Apply, Cancel, and clear focus styling without relying on color alone." ], "uxGuidance": [ "Use a date range picker when users need to select or inspect a continuous period such as a report window, trip, event, booking, campaign, or eligibility span.", "Keep both boundaries editable, explain invalid order or excessive duration, preserve the current range while users explore, and apply changes only after the range is complete for data-changing workflows." ], "uiExamples": { "good": [ "An analytics report control shows Since and Until text fields, quick choices for Today and Last 7 days, a two-week calendar grid, selected August 3 start, selected August 14 end, and a filled band for days inside the range.", "A hotel booking picker displays two adjacent months so a stay that crosses month boundaries can be selected without losing the start date." ], "bad": [ "A report filter has one field labelled Date and silently stores two dates separated by a dash with no start or end labels.", "A calendar highlights only the first and last dates, leaving included days visually indistinguishable from unselected days." ] }, "uxExamples": { "good": [ "A user chooses Last 7 days, sees 2026-08-08 through 2026-08-14 filled in the calendar, reviews both inputs, then applies the range.", "A user types 2026-08-10 as start and 2026-08-05 as end, sees a specific end-before-start error, fixes only the end field, and keeps the start date." ], "bad": [ "A dashboard refreshes on every hovered day while the user is still deciding the end date.", "A booking calendar lets users select a 90-day stay even though the service limit is 14 nights, then fails after payment details." ] }, "problemContext": [ "The user is selecting a period for analytics, booking, scheduling, eligibility, reporting, campaign planning, or event duration.", "The relationship between dates matters: start, end, days included, duration, weekdays, cross-month spans, or blackout dates.", "Common ranges may be faster through presets but custom dates must remain possible.", "The interface may update expensive search results, charts, availability, or pricing after the range changes.", "The service must store unambiguous start and end dates and handle invalid or out-of-window values." ], "selectionRules": [ "Choose date range picker when the answer is a continuous start-to-end period and users need to see the included days.", "Use a single date picker for one appointment, deadline, or booking date.", "Use date input when users already know both dates and calendar adjacency does not affect the answer.", "Use filter panel when the range is one draft criterion among multiple grouped filters that should be applied together.", "Use select or segmented choices for a small set of fixed periods such as Today, This month, or Fiscal Q3 when custom dates are not allowed.", "Keep start and end labels visible and editable instead of hiding both boundaries inside one compound value.", "Show the range band between endpoints so users can verify inclusivity.", "Use Apply and Cancel when selecting the range changes charts, tables, pricing, availability, or other expensive results.", "Validate end date after start date, minimum date, maximum date, blocked dates, and maximum duration before committing.", "Preserve one valid boundary when the other boundary is invalid." ], "requiredStates": [ "Empty start and end fields with visible labels, date-format hints, and a calendar trigger.", "Open calendar with start endpoint active and no end selected.", "Hover or keyboard preview state showing the possible in-range days before end selection.", "Complete selected range with start date, end date, and all included days visibly connected.", "Preset range selected state synchronized to both endpoint fields and the calendar band.", "Manual endpoint typed state that updates the same range model as calendar selection.", "Invalid order error when end date is before start date.", "Too-long duration error when the span exceeds the service limit.", "Out-of-window or disabled-date state for blocked dates.", "Dirty unapplied state with Apply and Cancel actions.", "Applied state showing canonical start and end dates." ], "interactionContract": [ "Opening the picker reveals both endpoint fields, presets when available, and a calendar that keeps the current range visible.", "The first calendar click sets or replaces the start date; the second valid click sets the end date and highlights the full range.", "Hovering or focusing a potential end date previews the included range without committing it.", "Typing in either endpoint field updates only that boundary and validates against the other boundary.", "Preset selection writes both endpoint fields and highlights the matching calendar range before Apply.", "Apply commits the complete valid range; Cancel restores the previously applied range.", "Submitting validates required endpoints, date format, real dates, start-before-end order, blocked dates, service bounds, and maximum span.", "Errors name the failing boundary and keep the other boundary visible for correction." ], "implementationChecklist": [ "Define the range purpose, inclusive or exclusive end semantics, default range, preset ranges, min and max dates, disabled dates, maximum duration, display format, and canonical storage format.", "Build two labelled inputs, persistent hints, calendar trigger, preset list, calendar month heading, weekday headings, start state, end state, in-range state, preview state, and Apply and Cancel controls.", "Store range state as explicit start and end values rather than parsing a display string.", "Synchronize typed endpoints, preset choices, calendar clicks, hover previews, dirty state, and applied state.", "Validate date format, impossible dates, start after end, same-day ranges, minimum date, maximum date, disabled dates, and maximum span on client and server.", "Announce active endpoint, selected start, selected end, in-range dates, disabled reasons, month changes, and validation errors to assistive technology.", "Test keyboard selection of both endpoints, screen readers, zoom, forced colors, mobile layout, cross-month ranges, presets, cancel recovery, server-returned errors, and timezone boundaries." ], "commonMisuses": [ "Using two unrelated single-date pickers that do not validate order or show included days.", "Collapsing the range into one unlabeled field with ambiguous dash-separated dates.", "Refreshing analytics results before the user applies a complete range.", "Hiding custom range entry behind presets only.", "Clearing the valid start date when the end date fails validation.", "Accepting an end date before the start date.", "Failing to show whether endpoints are inclusive.", "Using a range picker for approximate periods that users express in words." ], "critiqueQuestions": [ "Does the task require a continuous period, or is a single date enough?", "Are start and end labels visible and programmatically separate?", "Can users see every day included in the range before applying it?", "Which presets match real user decisions, and can users still enter custom dates?", "When should results update: on hover, on endpoint selection, or only after Apply?", "What happens when the end date is before the start date, blocked, or too far away?" ], "relatedPatterns": [ "date-picker", "date-input", "filter-panel", "select", "inline-validation", "error-summary" ], "comparisons": [ "date-range-picker-vs-date-picker-vs-date-input-vs-filter-panel" ], "sourceIds": [ "uswds-date-range-picker-component", "carbon-date-range-picker-component", "shopify-polaris-date-range-picker-pattern" ] }, { "id": "dead-end-empty-state", "completionStatus": "complete", "name": "Dead-end empty state", "category": "Feedback, Status, And System State", "patternType": "ux", "surfaceType": "Actionless blank-state anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users reach a blank or nearly blank area and cannot tell what is missing, why it is missing, or what they can do next.", "solution": "Treat the blank surface as an anti-pattern: determine the actual cause, then replace it with a legitimate empty state, no-results recovery, error state, permission explanation, setup step, or navigation escape.", "uiGuidance": [ "A dead-end empty state is visible as blank space, vague art, hidden filters, disabled mystery controls, or an empty table body with no object name, cause, or action.", "Replace it with a cause-specific state that keeps surrounding context visible and presents a valid action, recovery path, permission explanation, or safe escape." ], "uxGuidance": [ "Diagnose why the surface is empty before choosing copy or controls: first-use, configured-empty, filtered, permission-limited, failed, loading, deleted, or unavailable.", "Prevent users from getting stranded by ensuring every resolved empty state either changes the system, changes criteria, requests access, retries, restores, or explains why no action exists." ], "uiExamples": { "good": [ "A replacement state names No projects yet, explains the workspace has no projects, and offers Create project or Import CSV only when permitted.", "A filtered blank state keeps filter chips visible and offers Remove archived filter and Clear all filters.", "A failure replacement says Reports could not load and keeps Retry, cached view, or support actions visible." ], "bad": [ "An empty table body with pale placeholder lines and no label.", "A decorative illustration with Nothing here and no action.", "A disabled Create button with no explanation for read-only users." ] }, "uxExamples": { "good": [ "Users can classify the absence and take the correct path: create, import, clear filters, request access, retry, restore, or leave safely.", "When an item is deleted and the list becomes empty, focus moves to a recovery state with undo or next navigation instead of an inert void." ], "bad": [ "Users cannot tell whether content is still loading, filtered out, unavailable, failed, or nonexistent.", "The only visible action fails because the current user lacks permission.", "A failed API request is silently rendered as an empty dashboard." ] }, "problemContext": [ "A list, table, dashboard, workspace, inbox, or panel can render with no visible items.", "The product may not yet know whether the cause is first use, filters, permissions, loading failure, deletion, unavailable data, or a hidden prerequisite.", "Users need enough context to decide whether to create, import, clear criteria, request access, retry, restore, or leave." ], "selectionRules": [ "Flag dead-end empty state when a blank area lacks a specific object name, cause, and reachable next action.", "Flag decorative-only empty states when illustration or friendly copy replaces actionable explanation.", "Flag states that show a primary action the current user cannot perform, because a failed action is still a dead end.", "Replace with empty state when the absence is legitimate and the user has a setup, create, import, sample, or request-access path.", "Replace with no-results recovery when visible search, filter, or sort criteria produced zero matches.", "Replace with error state when expected content failed to load, save, sync, authorize, or compute.", "Do not mark the state resolved until keyboard, focus, screen-reader reading order, and post-action transition all give users a real path out." ], "requiredStates": [ "Unexplained blank state that is being audited as the anti-pattern.", "Diagnosed first-use or legitimate absence state with object-specific copy and valid action.", "Filtered or searched no-results state with visible criteria and recovery controls.", "Permission or prerequisite state with explanation and request/setup path.", "Failure state with retry, fallback, or support path.", "Escaped or recovered state after the user takes a valid next action." ], "interactionContract": [ "A blank or actionless content region is not a valid terminal state.", "The replacement state must name what is absent and why the system believes it is absent.", "The next action must be available to the current user or replaced with a permission/prerequisite explanation.", "If the cause is uncertain, the UI should show loading, retry, or diagnostic recovery instead of pretending the area is empty.", "Focus should not remain on removed content or an inert blank panel after data changes.", "The state must update when content appears, criteria are cleared, access changes, or retry succeeds." ], "implementationChecklist": [ "Track data status separately from rendered item count: loading, empty, no-results, permission, error, and ready.", "Render the surrounding context such as table title, filter chips, workspace, owner, or object type.", "Write a cause-specific heading and short explanation before adding illustration.", "Show one valid primary action or a clear reason no action is available.", "Do not offer create/import/reset/retry controls unless they are permitted and wired to a state change.", "Keep keyboard focus in a useful place after the blank region resolves or changes cause.", "Instrument blank states so repeated dead ends can be found and replaced." ], "commonMisuses": [ "Blank table body with no heading, count, cause, or action.", "Friendly illustration plus vague text such as Nothing here yet with no task path.", "Create button shown to a read-only user and failing after activation.", "No-results caused by filters but active criteria are hidden above the fold.", "Failed load rendered as empty content to avoid showing an error.", "A removed item leaves keyboard focus on a now-empty region with nowhere to go." ], "critiqueQuestions": [ "Can users name what is absent after reading this state?", "Can users tell whether the cause is first-use, filters, permission, setup, deletion, loading, or failure?", "Is the visible next action valid for this user and wired to a meaningful state change?", "Would the same blank copy still appear if the cause changed to error or no-results?" ], "relatedPatterns": [ "empty-state", "no-results-recovery", "error-state", "loading-skeleton" ], "comparisons": [ "dead-end-empty-state-vs-empty-state-vs-no-results-recovery-vs-error-state" ], "sourceIds": [ "carbon-empty-states-pattern", "atlassian-empty-state", "sap-fiori-illustrated-message", "polaris-empty-state", "govuk-design-system-patterns" ] }, { "id": "delete-account", "completionStatus": "complete", "name": "Delete account", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Account-level closure and associated personal data deletion workflow", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Account deletion is high-risk when the path is hidden, confused with deactivation or data export, omits signed-in identity, hides billing and linked-service consequences, gives no retention or recovery explanation, or claims erasure before the deletion request is actually completed.", "solution": "Provide a direct account deletion workflow that verifies identity, explains account and data scope, offers export-before-delete, handles subscriptions and linked services, discloses retained data and timing, requires deliberate confirmation, supports cancellation or recovery where available, and reports request status through completion or refusal.", "uiGuidance": [ "Render delete account as a discoverable account-settings workflow that names the signed-in account, affected services, associated data, retained data, subscriptions, linked sign-in methods, recovery window, and final deletion status.", "Separate account deletion from deactivation, sign out, data export, privacy settings, unsubscribe, service removal, and support contact; use direct labels such as Delete this account or Request account deletion." ], "uxGuidance": [ "Use delete account when users need to close an identity-bearing account and remove or request removal of associated personal, profile, authentication, app, subscription, and service data.", "Protect users from wrong-account and unclear-erasure mistakes by showing identity, consequences, export-before-delete, legal retention, cancellation or recovery windows, and progress until deletion is completed, blocked, or scheduled." ], "uiExamples": { "good": [ "An account settings page shows Delete account for maya.chen@example.com, lists profile, projects, messages, connected apps, subscriptions, and retained invoices, offers Download data first, then schedules deletion with a 14-day cancel window.", "A mobile app links directly from Account settings to a deletion page, explains that the account record and associated data will be deleted except legally retained fraud and billing records, and shows request status until completion." ], "bad": [ "A page offers only Deactivate account, tells users to email support, and never says whether profile data, authentication records, subscriptions, or linked apps are deleted.", "A red Delete button appears beside Data export and Sign out with no account identity, service list, retention explanation, billing warning, or recovery window." ] }, "uxExamples": { "good": [ "A user exports their data, verifies the account email, reviews affected services and subscription handling, types the email to confirm, schedules deletion, and can cancel during the stated recovery window.", "A user requests deletion after uninstalling the app through a public web link, receives a request ID, sees what data is retained for legal reasons, and gets a completion notification." ], "bad": [ "A user deletes an account from the wrong identity provider session because the flow hides which Google, Apple, or email account is signed in.", "A user thinks all data is immediately erased, but backups, public posts, invoices, fraud logs, or third-party recipients remain without explanation." ] }, "problemContext": [ "The account may own profile data, authentication credentials, posts, messages, files, projects, billing records, subscriptions, purchases, app data, linked apps, third-party sign-in tokens, organization memberships, child-account data, and audit records.", "The deletion may be immediate, scheduled, request-based, regulatorily constrained, support-assisted for highly regulated products, or partially blocked by legal, fraud, safety, billing, enterprise, or child-account requirements.", "Users may need to initiate deletion inside an app, through a direct web link after uninstall, or from an account settings surface.", "The product may need to distinguish whole-account deletion from deleting one service, removing an account from a device, signing out, disabling, deactivating, unsubscribing, or changing privacy settings." ], "selectionRules": [ "Choose delete account when the user's goal is account-level closure and associated data deletion or erasure request.", "Use destructive action confirmation for one destructive object command; delete account is broader because it spans identity, personal data, linked services, retention, and account recovery.", "Use typed confirmation as an escalation inside delete account when the account email, username, workspace, or broad scope must be reproduced to prevent wrong-account deletion.", "Use data export before or near delete account when users may want a copy, but do not imply export deletes source data.", "Use settings management for ordinary account or privacy preferences that keep the account active.", "Use restore from trash only when the account or data can be recovered faithfully inside a stated window.", "Make the deletion option easy to find from account settings or an equivalent account-control surface.", "Name the exact account, provider, workspace, or child account before users confirm deletion.", "List affected services, associated data categories, retained data, subscriptions, linked apps, sign-in methods, recovery options, and request timing.", "If deletion cannot be self-serve because of regulated-industry, enterprise, legal, safety, fraud, or billing constraints, explain the required request or support path and status." ], "requiredStates": [ "Discoverable account deletion entry point in account settings or a direct web deletion resource.", "Account identity review state showing email, username, provider, workspace, organization, or child account.", "Data and service scope state listing deleted, retained, public, third-party, subscription, billing, and linked-service effects.", "Download or export data first state that clearly says export does not delete the account.", "Identity verification, reauthentication, or two-factor state before deletion request submission.", "Typed confirmation or acknowledgement state for severe account closure.", "Subscription, billing, purchase, entitlement, or app-store cancellation warning state.", "Legal retention, backup retention, fraud/safety log, public content, recipient notification, or refusal state.", "Scheduled deletion, pending request, processing, completed, canceled, expired recovery window, and failed request states.", "Wrong-account, support-required, enterprise-managed, child-account, and already-deleted recovery states." ], "interactionContract": [ "The product provides a direct, discoverable account deletion path when users can create an account.", "The flow identifies the account being deleted before any irreversible request is submitted.", "Deleting an account is never presented as the same action as sign out, remove from device, unsubscribe, data export, service deletion, or temporary deactivation.", "Users can review or download data before deletion without that export changing the deletion state.", "The final action remains unavailable until identity checks, acknowledgements, typed confirmation, blockers, or support requirements are satisfied.", "The UI states what data will be deleted, what may be retained, why, and whether backup or recipient erasure happens later.", "The account deletion request produces a durable status, request ID, notification, or receipt when completion is not immediate.", "Cancel, recover, or restore paths are shown only when they are genuinely available and include the time window." ], "implementationChecklist": [ "Inventory account-owned data, service memberships, authentication providers, billing records, purchases, subscriptions, linked apps, organizations, public content, backups, and legal retention classes.", "Define whether deletion is immediate, scheduled, request-based, support-required, enterprise-managed, or blocked, and model each state explicitly.", "Provide a direct in-app entry point and public web deletion resource where platform policy or product context requires it.", "Show the signed-in account identity, affected services, retained data, and recovery window before the final confirmation.", "Offer data export before deletion while clearly separating export from erasure.", "Add reauthentication, two-factor, typed confirmation, or approval gates for severe scope or wrong-account risk.", "Handle active subscriptions, unpaid invoices, refunds, app-store billing, legal holds, fraud locks, child accounts, and enterprise ownership before commit.", "Generate a request ID or receipt and status updates for scheduled, pending, refused, partial, or completed deletion.", "Test wrong account, multiple accounts, SSO, deleted email address, app uninstall web path, mobile deep link, expired recovery window, backup retention, and screen-reader progress states." ], "commonMisuses": [ "Offering only deactivate, disable, sign out, remove from device, unsubscribe, or contact support when users need account deletion.", "Hiding account deletion behind unrelated settings, FAQs, email support, a vague privacy page, or an unlabeled Delete button.", "Combining data export and account deletion into one ambiguous control.", "Failing to name the signed-in account, provider, child account, or workspace before deletion.", "Claiming immediate full erasure while retaining backups, legal records, invoices, fraud logs, public copies, or recipient copies without explanation.", "Deleting subscriptions, purchases, entitlements, or third-party tokens without explaining their separate cancellation or revocation path.", "Leaving users with no request ID, status, notification, or recovery information after a long-running deletion request." ], "critiqueQuestions": [ "Can users find the account deletion path from account settings or the required public web resource?", "What exact account, provider, workspace, or child account will be closed?", "Which data and services are deleted, retained, transferred, public, or outside the product's control?", "What billing, subscription, purchase, entitlement, linked-app, or sign-in-token consequences remain?", "Can users export data first without confusing export with deletion?", "What proof shows deletion was scheduled, completed, blocked, refused, canceled, or recoverable?", "What time window applies to request response, scheduled deletion, backup overwrite, and account recovery?" ], "relatedPatterns": [ "destructive-action-confirmation", "typed-confirmation", "data-export", "settings-management", "restore-from-trash", "confirmation-dialog", "session-timeout", "account-creation", "consent-prompt", "audit-log" ], "comparisons": [ "delete-account-vs-destructive-action-confirmation-vs-typed-confirmation-vs-data-export-vs-settings-management-vs-restore-from-trash" ], "sourceIds": [ "apple-account-deletion-in-app", "google-play-account-deletion-requirements", "google-account-delete-help", "ico-right-to-erasure" ] }, { "id": "dependent-fields", "completionStatus": "complete", "name": "Dependent fields", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Controlling and dependent form fields", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Forms with related fields produce invalid, confusing, or stale data when users can choose downstream values before the upstream answer that defines which values are possible.", "solution": "Model the relationship explicitly with a controlling field and a dependent field that updates options, availability, requirement, helper text, validation, and stale-value recovery whenever the controlling answer changes.", "uiGuidance": [ "Place the controlling field before the dependent field, label both clearly, and explain the dependency in helper text such as Choose a category first to see valid subcategories.", "When the controlling value changes, update the dependent options, requirement label, helper text, stale-value status, loading state, and validation message together so the downstream field never looks independently valid." ], "uxGuidance": [ "Use dependent fields to prevent impossible combinations and guide users through valid answer pairs without forcing them to learn backend data rules.", "Treat a changed controlling answer as a data integrity event: clear, preserve-as-stale, or require review of any downstream value that no longer matches the new parent." ], "uiExamples": { "good": [ "An incident form asks Category first, then Subcategory shows only options for that category and says why it was cleared after Category changed.", "A product request form shows Region, then Site; Site is available only after Region is selected and uses helper text instead of a silent disabled select." ], "bad": [ "A Subcategory dropdown appears disabled at page load with no explanation of which Category unlocks it.", "Changing Category from Network to Facilities leaves VPN selected as Subcategory and the form still shows no error." ] }, "uxExamples": { "good": [ "A user chooses Hardware, selects Laptop, switches Category to Network, sees Laptop cleared, and chooses VPN from the new valid list before submitting.", "A user tries to submit before choosing Category and the form points to Category first, explaining that Subcategory depends on it." ], "bad": [ "A user submits a record with Category Facilities and Subcategory VPN because the stale dependent value was hidden but not cleared.", "A user tabs to a disabled dependent field before the controlling field and hears no reason it cannot be used." ] }, "problemContext": [ "A field's valid values, requirement, label, helper text, or validation depend on another answer in the same form or record.", "The downstream field represents a constrained subset such as category/subcategory, country/state, product/model, group/assignee, region/site, or type/detail.", "Changing the upstream answer can make an existing downstream answer invalid, ambiguous, hidden, or no longer required.", "The product can enforce the dependency in the data model or server validation, not only in client-side display logic." ], "selectionRules": [ "Choose dependent fields when one answer controls another field's valid choices, requirement, editability, helper text, or validation.", "Use an ordinary select when all users see the same finite option set and no upstream answer changes that set.", "Use conditional reveal fields when the main behavior is showing an extra related question after an answer, not filtering an always-owned downstream field.", "Use inline validation when the problem is only a single field's own invalid value, not a mismatch between controlling and dependent values.", "Use complete complex form when dependencies span multiple sections, high-risk rules, review state, or several stale downstream fields.", "Make the dependency understandable before users interact with the dependent field.", "Clear the dependent value automatically when the new controlling value makes it invalid, or mark it stale and require an explicit review choice.", "Do not silently keep, hide, or submit a dependent answer that no longer belongs to the controlling answer.", "Avoid true disabled controls unless the prerequisite is stated and the control remains discoverable; consider enabled validation or aria-disabled behavior when users need feedback.", "Keep dependency rules in backend validation, import, API, and saved-draft recovery paths so stale pairs cannot bypass the UI." ], "requiredStates": [ "No controlling answer selected, with dependent field unavailable or empty and prerequisite helper text.", "Controlling answer selected, with dependent options filtered to the valid subset.", "Dependent answer selected and valid for the current controlling answer.", "Controlling answer changed, causing previous dependent value to clear or become explicitly stale.", "Dependent options loading after an async controlling change.", "No valid dependent options for the selected controlling value.", "Required dependency error when the controlling field or dependent field is missing.", "Invalid pair error when a stale dependent value no longer matches the controlling field.", "Submitted valid state that includes both controlling and dependent answers.", "Server-rejected state when persisted data violates the dependency rule." ], "interactionContract": [ "Users encounter the controlling field before the dependent field in reading and tab order.", "Changing the controlling field recomputes the dependent options immediately or shows a loading state until they are ready.", "If the current dependent value is no longer valid, the UI clears it or marks it stale before submit.", "The dependent field communicates which controlling value currently governs it.", "Submitting without a valid pair points first to the controlling field when the dependency cannot be evaluated.", "Errors name both fields when the pair is incompatible.", "Reloading a saved draft revalidates the pair against current dependency rules." ], "implementationChecklist": [ "Define the controlling field, dependent field, valid value matrix, requirement rules, defaults, empty states, and no-options states before building the UI.", "Keep the controlling and dependent values as separate model fields; do not infer one from a display label that can drift.", "Clear, mark stale, or require confirmation when a controlling change invalidates the dependent value.", "Update helper text, required labels, option list, aria descriptions, and validation messages in the same state transition.", "Add loading and retry behavior if dependent options are fetched asynchronously.", "Validate the dependency on submit, save, import, API write, and draft resume.", "Test keyboard order, screen reader descriptions, no-option states, stale clearing, browser Back, saved drafts, API-submitted stale values, and mobile reflow." ], "commonMisuses": [ "Leaving a stale dependent value selected after the controlling field changes.", "Disabling the dependent field with no explanation of the prerequisite.", "Putting the dependent field before its controller in DOM or tab order.", "Using dependent fields to hide independent options that users need to compare.", "Only filtering options client-side while the backend accepts invalid pairs.", "Clearing a user's downstream answer without any status message after a parent change.", "Treating many-to-many or permission-based dependencies as a simple one-parent dropdown without fallback." ], "critiqueQuestions": [ "Which field controls this dependent field, and can users see that relationship?", "What happens to a dependent value when the controlling answer changes?", "Can the backend reject stale or impossible field pairs?", "Does the dependent field need a no-options, loading, permission, or unavailable state?", "Would a simple conditional reveal, ordinary select, or section-level complex form be clearer?", "Are disabled states explained to keyboard and screen reader users?" ], "relatedPatterns": [ "select", "inline-validation", "complete-complex-form", "single-question-page", "multi-step-form" ], "comparisons": [ "dependent-fields-vs-select-vs-inline-validation-vs-complete-complex-form" ], "sourceIds": [ "servicenow-dependent-field", "salesforce-dependent-picklists", "uswds-form-component", "govuk-radios-component" ] }, { "id": "destructive-action-confirmation", "completionStatus": "complete", "name": "Destructive action confirmation", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Final destructive commit review", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can permanently delete, remove, deactivate, reset, or cancel valuable objects without understanding exactly what will be lost, especially when the final prompt uses vague labels, hides affected scope, or treats reversible cleanup like irreversible destruction.", "solution": "After a destructive command is invoked, show a focused destructive confirmation that names the target and destructive verb, inventories the loss, offers a safe keep path, requires any needed acknowledgement, blocks unavailable commits, and reports the final outcome.", "uiGuidance": [ "Render a destructive confirmation after the user invokes a destructive command, with a title and final action button that repeat the destructive verb and target, such as Delete workspace or Cancel subscription.", "Show the affected object, scope, and loss inventory before the final action, including child records, shared links, members, automations, billing, integrations, or external effects when they apply." ], "uxGuidance": [ "Use destructive action confirmation to create one informed stop before permanent or externally visible loss, not to slow every routine cleanup action.", "Make the safe path explicit and easy, keep the destructive action unavailable until required review is satisfied, and report whether the object was kept, blocked, or permanently committed." ], "uiExamples": { "good": [ "Delete Payments project? lists 4 dashboards, 12 saved views, 3 webhooks, and 8 shared links, offers Keep project, and labels the danger action Delete Payments project.", "Cancel Pro subscription? shows the billing date, lost seats, and export deadline before enabling Cancel subscription after an acknowledgement checkbox.", "Deactivate account? names the account, connected integrations, and recovery window, then sends focus to the safe action first." ], "bad": [ "A modal says Are you sure? with OK and Cancel after the user clicks Delete, without naming the project or what disappears.", "A red Delete button is enabled immediately beside a vague statement that cannot be undone.", "A soft archive action opens the same severe deletion confirmation used for permanent account closure." ] }, "uxExamples": { "good": [ "A user opens Delete workspace, reviews the object count and webhooks, cancels, and returns to the same workspace with nothing changed.", "A user acknowledges permanent deletion, commits it, and receives a final status that the workspace and integrations were removed.", "A user tries to delete a project with running jobs and the confirmation blocks commit until jobs are stopped." ], "bad": [ "A user confirms deletion because OK looks like the primary next step, then discovers shared links and child reports were lost.", "A user sees so many confirmations for low-risk cleanup that they skip reading the one that permanently removes production data.", "A user cannot tell whether Cancel means cancel the deletion or cancel the subscription because the labels do not name outcomes." ] }, "problemContext": [ "The user has already selected a destructive command such as Delete, Remove, Cancel, Deactivate, Reset, Revoke, or Permanently erase.", "The action can cause permanent data loss, account loss, subscription cancellation, permission removal, key reset, webhook deletion, public-link breakage, or irreversible external effects.", "The product can enumerate the affected object, child objects, relationships, integrations, billing effects, or recovery limits before committing.", "The team must distinguish permanent destruction from reversible archive, trash, dismiss, hide, or undoable cleanup." ], "selectionRules": [ "Choose destructive action confirmation when a destructive command needs a final commit review before permanent or externally visible loss.", "Use the destructive verb and target in the title and final button; avoid OK, Yes, Continue, Proceed, and Confirm for the final destructive action.", "List the affected scope in concrete terms: object name, count, child records, members, shared links, integrations, billing, audit, or external systems.", "Keep the safe path first or easiest to reach when cancellation leaves everything unchanged.", "Disable the destructive action until required acknowledgement, dependency resolution, or scope review is complete.", "Use ordinary confirmation dialog for high-consequence decisions that are not mainly destructive.", "Use undo or restore when deletion is actually a reversible trash move and the prior state can be restored faithfully.", "Use warning text before the destructive command when the user only needs consequence copy before starting the delete flow.", "Escalate to typed confirmation for severe broad-scope deletion, workspace or account closure, production data deletion, or security-critical reset." ], "requiredStates": [ "Idle state where the destructive command is visible but not committed.", "Review state that names the destructive verb, target object, and affected scope.", "Dependency-blocked state where deletion cannot continue until related jobs, locks, billing, or permissions are resolved.", "Acknowledgement-required state for permanent loss or external effects.", "Safe cancellation state that keeps the object unchanged and returns focus to the destructive trigger or object row.", "Committing state after deliberate confirmation with disabled duplicate submissions.", "Committed outcome state that reports what was permanently removed and where focus or navigation goes next.", "Alternative recovery state where undo, trash restore, archive, or warning text is the more appropriate pattern." ], "interactionContract": [ "The confirmation appears only after a user-initiated destructive command.", "The title, body, and final button all refer to the same target and destructive action.", "The confirmation inventory is specific enough for users to decide whether to cancel.", "The safe path closes the confirmation without changing the target object.", "Escape cancels only when the destructive action has not started and cancellation is safe.", "The destructive button cannot be activated until required acknowledgement or dependency checks pass.", "Committing disables duplicate activation and shows a clear in-progress state.", "After cancel, block, or completion, focus returns to the trigger, the preserved object, or a clear post-deletion status." ], "implementationChecklist": [ "Identify the destructive verb, target object, owner, and exact irreversible boundary before designing the confirmation.", "Inventory child records, relationships, shared links, integrations, billing effects, audit retention, external notifications, and recovery windows.", "Write the title as a destructive question or statement using the target name.", "Write the final action label as the destructive verb plus object type or object name.", "Write the safe action as the preserved outcome, such as Keep project, Keep subscription, or Do not delete.", "Block commit when dependencies make deletion invalid or when required acknowledgement is incomplete.", "Prevent duplicate destructive submissions while the deletion request is committing.", "Record cancellation, blocked, and committed outcomes in a status region or audit trail where appropriate.", "Review whether undo, restore-from-trash, warning text, or command placement would protect users with less interruption." ], "commonMisuses": [ "Using a vague Are you sure prompt that does not name the object, count, or consequence.", "Labelling the destructive commit OK, Yes, Continue, or Confirm.", "Making the destructive action the default Enter target before the user reviews the loss.", "Using the same severe confirmation for reversible archive, hide, dismiss, and move-to-trash actions.", "Omitting child objects, shared links, subscriptions, automations, webhooks, or permissions from the loss inventory.", "Offering undo after an irreversible deletion has already crossed the system boundary.", "Showing the confirmation after the destructive action has already started." ], "critiqueQuestions": [ "What exactly will be gone, revoked, cancelled, reset, or deactivated after commit?", "Can the product list enough affected scope to change the user's decision?", "Is this permanent destruction, a reversible trash move, or a routine archive action?", "Does the final button say the destructive verb and target?", "Is the safe action phrased as the preserved outcome?", "What blocks deletion, and how does the confirmation show that block?", "What state receives focus after cancel, block, and commit?" ], "relatedPatterns": [ "confirmation-dialog", "undo", "warning-text", "modal-dialog", "alert" ], "comparisons": [ "destructive-action-confirmation-vs-confirmation-dialog-vs-undo-vs-warning-text" ], "sourceIds": [ "atlassian-forge-danger-modal", "maersk-dialog-component", "apple-hig-alerts", "microsoft-windows-confirmations", "wai-aria-apg-alertdialog" ] }, { "id": "details-panel", "completionStatus": "complete", "name": "Details panel", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Persistent selected-object inspection panel", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Dense workspaces often show many objects in a list, table, map, board, or feed, and users need to inspect selected-object detail repeatedly without losing the surrounding context or navigating to a full page for every item.", "solution": "Provide a persistent details panel tied to the current selection, keep selected-object identity synchronized with the source region, show concise inspection content and safe secondary actions, and offer collapse, resize, or full-page routes when space or depth exceeds the panel contract.", "uiGuidance": [ "Render a details panel as a persistent side or adjacent region that names the currently selected object, shows high-value metadata, status, and local secondary actions, and keeps the object selection visible in the source list, table, map, board, or feed.", "Keep details panel content structured for inspection and comparison; do not turn it into an unlabeled drawer, a hover preview, a global settings surface, a filter panel, or a long primary editing workflow." ], "uxGuidance": [ "Use a details panel when users need to select and compare nearby objects while keeping a durable inspection area visible, such as reviewing records, tickets, assets, alerts, comments, files, or map locations.", "Make selection updates, empty selection, sorting, filtering, resize, collapse, keyboard movement, and full-page escalation predictable so users never inspect stale or unrelated object details." ], "uiExamples": { "good": [ "A ticket queue keeps TCK-2048 selected in the list and shows a right details panel with requester, severity, SLA, owner, activity, and Open full ticket.", "A map list selection updates a details panel with the selected site name, status, latest reading, and View asset route without covering the map." ], "bad": [ "A panel titled Details shows metrics from the previously selected record after the list selection changes.", "A details panel contains global navigation links, filters, delete actions, and a long edit form unrelated to the selected object." ] }, "uxExamples": { "good": [ "A keyboard user moves down a ticket list, the highlighted row and details panel update together, and focus remains in the list until the user chooses Open full ticket.", "A user filters the queue, the selected ticket remains visible or the panel changes to Select a ticket with a clear explanation." ], "bad": [ "Sorting the list silently clears the highlighted row while the panel continues to show an old ticket.", "Opening the panel steals focus on every row movement, making keyboard review slow and disorienting." ] }, "problemContext": [ "A work surface contains selectable objects such as tickets, records, assets, files, alerts, orders, map markers, comments, or tasks.", "Users benefit from comparing several nearby objects without leaving the current list, table, map, board, or feed.", "The details can be summarized in a durable side or adjacent region without requiring a modal response.", "The product can keep selection, sorting, filtering, empty state, focus, and detail refresh synchronized." ], "selectionRules": [ "Choose details panel when a selected object needs durable side-by-side inspection while users browse neighboring objects.", "Use drawer when the surface is temporary, opened by a discrete command, and needs close behavior and focus movement into the panel.", "Use hover card when the content is a compact transient preview before navigation rather than a durable inspection area.", "Use accordion or disclosure details when the content belongs inline in the page flow rather than to a changing selected object.", "Use table, data grid, or expandable row when the needed detail should remain row-local inside the data surface.", "Use a full object page when users need deep reading, long editing, durable URL state, sharing, comments, history, or browser navigation.", "Use filter panel when the panel contains criteria that narrow results and synchronize active counts, not object details.", "Use preview panel when the panel's primary job is media or document preview rather than structured metadata inspection.", "Do not use a details panel when no stable selected object exists or when selection changes faster than the panel can stay accurate." ], "requiredStates": [ "No selection state with a clear prompt or preserved last-selection rule.", "Selected-object state with source item highlighted and panel title naming the same object.", "Keyboard list-navigation state where focus can move through objects without being stolen by the panel.", "Updated-selection state where metadata, status, activity, and actions refresh together.", "Filtered or sorted state where the panel either remains tied to a visible selected object or explains that selection was cleared.", "Loading or refreshing state that does not show stale details as current.", "Collapsed, resized, or narrow-screen state with a visible way to restore detail or open the full object.", "Full-page escalation state for deep reading, editing, comments, history, or shareable detail." ], "interactionContract": [ "Selecting an object updates both the source selection indicator and the details panel title.", "The panel content describes only the selected object unless a clearly labelled comparison mode is active.", "Keyboard focus remains in the source list, table, map, board, or feed while users move selection for review.", "The panel exposes safe secondary actions such as Open full record, Assign owner, or Copy link without hiding required primary task flows.", "If selection disappears because of filtering, sorting, deletion, permission change, or refresh, the panel updates to a clear empty or unavailable state.", "The panel can be collapsed, resized, or replaced by a full-page route when space is constrained.", "Panel actions preserve or intentionally update the selected object, and the status text confirms the result." ], "implementationChecklist": [ "Define the owning selectable region and stable selected-object ID before rendering panel content.", "Show selected state in the source region and repeat the selected object's name or identifier in the panel heading.", "Separate inspection fields from actions; keep destructive or multi-step actions out of the panel unless routed to review.", "Keep focus in the source region during selection movement, and move focus into the panel only after an explicit panel action.", "Handle loading, stale data, missing permissions, deleted objects, filtered-away objects, and empty selection states.", "Provide collapse, resize, or full-page escalation when the panel competes with the workspace for width.", "Test row selection, keyboard movement, sort, filter, refresh, collapse, narrow viewport, and full-object routing." ], "commonMisuses": [ "Showing a details panel with no selected-object identity.", "Keeping the previous ticket summary in the persistent panel after the highlighted row has moved to a different ticket.", "Stealing focus into the panel on every arrow-key movement through a list.", "Mixing object details with filters, navigation, global settings, and unrelated commands.", "Using a details panel for long primary editing that needs validation, saved progress, or route history.", "Clearing selection after sort or filter without updating the panel.", "Making the panel so wide that it prevents comparison with the source region." ], "critiqueQuestions": [ "Which exact object owns the panel content right now?", "Can users see the selected object and panel title at the same time?", "What happens when users move selection by keyboard, sort, filter, delete, or refresh the source region?", "Does the panel support inspection, or has it become a drawer, form, filter panel, preview panel, or object page?", "Where do users go for full detail, deep editing, comments, history, or sharing?", "How does the panel adapt when the viewport cannot support side-by-side inspection?" ], "relatedPatterns": [ "drawer", "hover-card", "accordion", "popover", "sheet", "disclosure-details", "inline-message" ], "comparisons": [ "details-panel-vs-drawer-vs-hover-card-vs-accordion" ], "sourceIds": [ "ebay-panel", "carbon-ui-shell-right-panel", "apple-hig-panels", "material-side-sheets" ] }, { "id": "disabled-button-no-explanation", "completionStatus": "complete", "name": "Disabled button with no explanation", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Blocked action anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users see an unavailable action but cannot tell which field, permission, prerequisite, system state, or safety rule blocks it.", "solution": "Treat the unexplained disabled button as an anti-pattern: make the blocking requirement visible near the action, keep recovery controls reachable, or allow the action and return actionable validation.", "uiGuidance": [ "Replace a lone greyed-out action with visible requirement text, a checklist, permission message, or enabled validation submit that tells users what blocks progress.", "Keep recovery controls such as edit fields, request access, retry later, contact owner, or use valid details reachable beside the blocked action." ], "uxGuidance": [ "Help users understand whether the block is missing input, invalid data, permission, quota, dependency, safety policy, or temporary processing.", "Turn action availability into a discoverable lifecycle: unavailable with reason, partially eligible, recoverable, eligible, processing, and completed." ], "uiExamples": { "good": [ "Create workspace is paired with visible requirements: enter a workspace name, accept billing terms, and request owner access.", "A form keeps Continue enabled and, after activation, shows inline messages or an error summary that names each missing answer." ], "bad": [ "Create workspace is greyed out with no nearby text, checklist, or request-access route.", "A disabled Continue button has a hover-only tooltip that keyboard and touch users cannot open." ] }, "uxExamples": { "good": [ "Users can satisfy requirements one by one and see the action become available, or submit and receive actionable validation.", "Permission-gated users can request access or contact an owner instead of guessing at form fields." ], "bad": [ "Users change random fields because the unavailable action never states the missing condition.", "The button remains inert after requirements are met because the eligibility state is not updated visibly." ] }, "problemContext": [ "A form, setup flow, permission model, quota, dependency, or safety gate controls whether an action can run.", "The primary action is greyed out, skipped by keyboard focus, or visually present but functionally unavailable.", "The reason may be a missing field, invalid format, unchecked agreement, insufficient permission, pending system state, or locked account.", "Users need to know what to change, who can grant access, or when the action will become available." ], "selectionRules": [ "Flag this anti-pattern when an unavailable action has no visible requirement, cause, owner, or next step near the control.", "Show a requirement checklist or status message for eligibility gates such as missing name, terms acceptance, permission, quota, setup, or dependency state.", "Keep the action enabled and validate on activation when users benefit from seeing exactly which fields failed after an attempted submit.", "Use inline validation when one field has a local correctable problem and the action itself does not need to explain a wider eligibility gate.", "Use an error summary when a submitted page or step returns multiple validation errors that may be spread across the page.", "For permission or system locks, show who can resolve the block, whether the user can request access, and what data remains safe.", "Disable only during short in-progress states such as preventing duplicate submit, and pair that state with visible progress or completion feedback." ], "requiredStates": [ "Unavailable action state with visible reason and affected requirement.", "Partially eligible state that shows which requirements are complete and which remain.", "Actionable recovery state such as edit field, accept terms, request access, retry later, or contact owner.", "Eligible state where the action becomes available or an enabled submit can validate remaining issues.", "Submitted or completed state after the action succeeds.", "Permission-denied or system-locked state with an escalation route." ], "interactionContract": [ "Users can discover why the action is unavailable without hovering a disabled control or guessing from color alone.", "The explanation is adjacent to the action or requirement list, not hidden in a detached tooltip or unrelated help page.", "Keyboard and assistive technology users can reach the requirement text and any recovery controls even if the unavailable action itself cannot receive focus.", "Eligibility changes update the visible requirement state and action state in the same region.", "If submit remains enabled, failed activation preserves user input and moves focus or reading order to actionable validation.", "Permission locks distinguish missing user input from account, role, quota, dependency, or system constraints." ], "implementationChecklist": [ "Name the exact condition blocking the action, such as Enter a workspace name, Accept billing terms, or Ask an admin for owner access.", "Place requirement text, checklist, or field errors before the action or directly beside it.", "Use enabled submit plus validation when disabling would hide field requirements or prevent users from learning what remains.", "Use aria-describedby or equivalent relationships for nearby requirement text when an unavailable control remains in the UI.", "Keep recovery links, request-access controls, edit fields, and support routes keyboard reachable.", "Avoid hover-only explanations on disabled controls because disabled elements may not receive focus or pointer events consistently.", "Update the action label or status during short processing states so users know the button is busy, not permanently unavailable." ], "commonMisuses": [ "Greying out Continue until every field is valid without showing the missing or invalid answers.", "Putting the only explanation in a tooltip attached to a disabled button that keyboard and touch users cannot open.", "Using disabled state to hide permission, quota, account lock, or system dependency problems.", "Changing the button from disabled to enabled silently after a requirement changes elsewhere on the page.", "Disabling a destructive action without explaining the safety prerequisite or alternate route.", "Using low contrast disabled styling as the only signal that an action is unavailable." ], "critiqueQuestions": [ "Can users tell exactly which requirement blocks the action before they try random changes?", "Can keyboard and screen reader users reach the explanation and recovery path?", "Is this a field validation problem, a permission problem, a system state, or a safety lock?", "Would an enabled submit with validation teach the next step better than a disabled button?", "Does the UI distinguish temporary processing from a longer blocked state?" ], "relatedPatterns": [ "inline-validation", "error-summary", "infinite-spinner", "icon-only-ambiguous-action" ], "comparisons": [ "disabled-button-no-explanation-vs-inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-button-component", "va-button-component", "govuk-error-message-component", "govuk-error-summary-component" ] }, { "id": "disabled-controls-without-recovery", "completionStatus": "complete", "name": "Disabled controls without recovery", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Blocked-control anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users encounter disabled buttons, menu items, toggles, form controls, or workflow actions that block progress without a usable route to meet the requirement, request access, resolve a dependency, recover from state, or choose a safe alternate path.", "solution": "Treat unrecoverable disabled controls as an anti-pattern: expose the blocking condition, keep recovery controls reachable, model the prerequisite lifecycle, and provide the next viable action such as edit, request access, unlock dependency, retry after state changes, save draft, contact owner, switch account, use fallback, or stop honestly.", "uiGuidance": [ "Pair unavailable controls with visible requirement maps, state messages, owner routes, and recovery actions that can be reached without interacting with the disabled element.", "Prefer enabled validation, request access, retry after state change, save draft, sign-in recovery, dependency setup, contact owner, or fallback actions over inert controls with hidden causes." ], "uxGuidance": [ "Model disabled controls as a lifecycle: unavailable with cause, recoverable, pending, available, processing, completed, or honestly stopped.", "Separate validation, permission, dependency, offline, session, role, admin, and processing causes so users choose the right recovery path instead of guessing." ], "uiExamples": { "good": [ "An Invite teammate panel shows missing billing setup, owner approval, and team domain checks, with Open billing, Request owner approval, Save draft, and Contact admin actions.", "A disabled Export control is paired with a role message, request access path, read-only fallback, and status showing when permissions refresh." ], "bad": [ "Invite teammate is greyed out with no visible requirement, owner route, or alternate way to keep the draft.", "A disabled Save button says nothing during sync, never times out, and leaves no retry or draft-preservation path." ] }, "uxExamples": { "good": [ "A user sees which prerequisites are complete, opens billing setup for the missing prerequisite, saves the invite draft, requests owner approval, and returns to send once eligibility changes.", "A role-limited user keeps read-only work available and requests editor access instead of being trapped behind an inactive edit button." ], "bad": [ "A user repeatedly edits random fields because the disabled Continue control never names the remaining condition.", "A mobile user cannot reveal the tooltip attached to a disabled command and has no other route to learn the requirement." ] }, "problemContext": [ "The interface gates an action behind form completion, permission, quota, account status, dependency setup, offline state, session expiry, review approval, or safety policy.", "The unavailable control is visible but inert, skipped by focus, or only explained by color, hover, or hidden text.", "Users may not know whether they need to edit fields, ask an admin, wait for processing, reconnect, upgrade a plan, sign in again, finish another step, or use another route.", "The product has enough state to name at least one recovery path or to state that no recovery is possible from this surface." ], "selectionRules": [ "Flag this anti-pattern when a disabled control blocks a task and the surrounding UI does not provide a reachable next step.", "Use disabled-button-no-explanation when the problem is a single unexplained inactive button; use this pattern when the broader control state also lacks recovery, escalation, fallback, retry, or stop conditions.", "Use inline validation when users can correct a specific field locally; use error summary when a submitted page returns linked corrections across multiple fields.", "Use permission recovery when a permission boundary can be resolved through request, approval, account switch, owner contact, policy escalation, or safe fallback.", "Use fallback path when the primary route cannot complete but another method can finish the same user outcome.", "Do not rely on tooltip-only explanations for disabled controls; required recovery information must be visible or reachable without hovering the disabled element.", "Prefer an enabled action that returns actionable validation when disabling hides requirements that users need to discover.", "Disable only for short processing or duplicate-prevention windows, and pair the state with visible progress, preserved input, and a retry or completion outcome." ], "requiredStates": [ "Prerequisite map state that shows each requirement and whether it is met.", "Missing fields state with visible correction targets.", "Permission request state with current account, required role, owner or admin path, and pending outcome.", "Dependency unlock state that names the upstream setup step and link.", "Saving or processing state with retry, cancel, or completion feedback.", "Offline state with local save, reconnect, or alternate route.", "Role-limited state with read-only work preserved and request-access path.", "Admin-managed state with owner contact or policy escalation.", "Expired session state with sign-in recovery that preserves the current work.", "Alternative route state when the primary control cannot become available from this path.", "Support or contact state with a reference when no self-service route exists.", "Bad dead-disabled state with no cause.", "Bad hidden-reason state where the requirement exists but is not visible.", "Bad tooltip-only state where recovery depends on hover or pointer access.", "Bad infinite-disabled state where processing never resolves.", "Bad permission dead-end state where access is blocked but no request or fallback exists.", "Bad stale-disabled state where the control stays unavailable after requirements are met." ], "interactionContract": [ "Users can discover the cause of unavailability without activating or hovering the disabled control itself.", "Every recoverable block has at least one reachable control that changes the state, such as edit field, request access, unlock dependency, retry, sign in, save draft, or use fallback.", "Every unrecoverable block states why progress cannot continue from this surface and gives the safest next step.", "Eligibility changes update the visible prerequisite map and action state in the same region.", "Keyboard and assistive technology users can reach recovery text, links, status messages, and alternate actions even when the primary control remains disabled.", "Processing, permission, validation, offline, and dependency states use different copy so users do not confuse waiting with missing input or missing access." ], "implementationChecklist": [ "Inventory each disabled control and record the exact condition, owner, timeout, retry rule, and recovery path.", "Place prerequisite, permission, offline, dependency, or session recovery text before or next to the disabled control.", "Add visible controls for Edit missing fields, Request access, Open setup step, Retry save, Sign in again, Save draft, Contact admin, or Use alternate route when those actions are valid.", "Use aria-describedby or nearby status regions for unavailable controls that remain visible.", "Avoid hiding the only reason in a disabled element tooltip, disabled menu item title, color, icon, or inaccessible hover card.", "Clear stale disabled state when prerequisites are met, permissions refresh, network returns, session recovery completes, or the dependency unlocks.", "Test keyboard order, screen reader announcement, touch, high zoom, offline, slow save, expired session, role change, admin policy, and reload while blocked." ], "commonMisuses": [ "A Continue button remains disabled until all fields are valid but no field or checklist names the missing work.", "A disabled Invite teammate action hides that billing setup, owner approval, or admin policy is required.", "A disabled menu item has a title tooltip as the only explanation, so touch and keyboard users never see the recovery step.", "A Save button is disabled during processing with no progress, timeout, retry, or draft preservation.", "A role-limited user loses read-only access because the disabled edit control consumes the whole surface.", "A stale disabled state remains after the user fixes the field, reconnects, refreshes permissions, or signs back in." ], "critiqueQuestions": [ "What exact condition makes the control unavailable?", "Can the current user do anything to change that condition from here?", "If another person or system owns the block, is the request, contact, or status route visible?", "Does the UI distinguish missing input from permission, dependency, session, offline, and processing states?", "Can keyboard, touch, and assistive technology users reach the recovery instructions?", "What proves the disabled state clears when recovery succeeds?" ], "relatedPatterns": [ "disabled-button-no-explanation", "inline-validation", "error-summary", "permission-recovery", "permission-denied-state", "fallback-path", "retry", "tooltip-only-required-information" ], "comparisons": [ "disabled-controls-without-recovery-vs-disabled-button-no-explanation-vs-inline-validation-vs-error-summary-vs-permission-recovery-vs-fallback-path" ], "sourceIds": [ "govuk-button-component", "va-button-component", "govuk-error-message-component", "govuk-error-summary-component", "nng-required-fields-forms", "nng-permission-requests", "wcag-status-messages" ] }, { "id": "disclosure-details", "completionStatus": "complete", "name": "Disclosure / details", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Single in-place reveal for optional supporting content", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Some tasks need optional supporting explanation, but showing every note inline can bury the main path while hiding important help behind vague or unstable controls can make users miss the context they need.", "solution": "Use a single in-place disclosure with a specific summary, predictable open and closed states, nearby revealed content, preserved task state, and clear escalation when the content is required, long, repeated, or navigational.", "uiGuidance": [ "Render one clearly labelled disclosure control with a visible summary that predicts the revealed content, followed immediately by the hidden explanation, example, or supporting note.", "Keep the trigger, open state, focus style, and revealed content visually connected to the field, paragraph, or decision it clarifies; do not make the control look like navigation." ], "uxGuidance": [ "Use disclosure details when a short explanation, example, eligibility note, or calculation help is useful to some users but would slow most users if always visible.", "Keep required instructions, validation errors, primary actions, and severe warnings visible by default unless the summary itself exposes the issue and the product opens the disclosure when needed." ], "uiExamples": { "good": [ "A tax form shows a summary labelled How we calculate household income, revealing a short worked example below the income field.", "A support application shows Why we ask for this document, revealing one paragraph and a small list of acceptable evidence." ], "bad": [ "A form hides the only eligibility rule under More details with no hint that it affects the answer.", "A page uses ten Details controls as section navigation, with some triggers revealing text and others opening pages." ] }, "uxExamples": { "good": [ "A user opens the calculation help, reads one example, closes it, and the nearby income field value remains unchanged.", "After validation finds a missing receipt explanation, the page opens Why we need a receipt and leaves focus on the summary before the explanatory text." ], "bad": [ "Users miss a deadline because the deadline is hidden inside a collapsed disclosure with a vague label.", "Opening a help disclosure moves focus to the bottom of the page and clears a partially typed answer." ] }, "problemContext": [ "A form field, policy sentence, calculation, document request, or content paragraph has one supporting explanation that only some users need.", "The explanation is short enough to read in place and does not require a separate task flow, search, comparison, or multi-section structure.", "The main content remains understandable while the disclosure is closed because the summary names what is hidden.", "The product can preserve focus, nearby input values, and validation behavior while the disclosure opens and closes." ], "selectionRules": [ "Choose disclosure details for one short optional explanation that belongs directly beside the content it clarifies.", "Use accordion when there are several related revealable sections with distinct headings, repeated open state, summaries, or expand-all needs.", "Use inline message when the content is status, warning, success, or recovery feedback that must remain visible near the affected object.", "Use related links when the content is an onward destination rather than hidden text on the current page.", "Keep critical deadlines, legal consequences, primary calls to action, and validation errors visible unless the disclosure summary itself states the issue and error recovery opens it.", "Prefer always-visible helper text when nearly every user needs it or when the hidden text is shorter than the disclosure trigger.", "Prefer a details panel, page, modal, or help article when the explanation is long, interactive, contains several branches, or requires separate navigation.", "Do not use disclosure details to collapse whole page structure, replace headings, create menus, or imitate tabs." ], "requiredStates": [ "Closed state with a specific summary label and hidden supporting content.", "Open state with revealed content immediately after the summary in reading order.", "Focused summary state with visible focus indication.", "Validation-opened state where an error or help link opens the disclosure without losing nearby form values.", "Disabled or unavailable state only when the reason is visible and the content cannot be revealed.", "No-JavaScript or native fallback state where the summary and content remain understandable." ], "interactionContract": [ "Activating the summary toggles only the one content region controlled by that disclosure.", "The summary remains visible in both open and closed states and continues to describe the revealed content.", "The revealed content appears directly after the summary and before unrelated controls.", "Opening and closing the disclosure does not clear nearby fields, selected options, or draft text.", "Enter or Space toggles the disclosure when focus is on the summary or button-like trigger.", "Validation links, help links, or deep links that target hidden content open the disclosure and keep focus predictable.", "The disclosure does not navigate unless the trigger is plainly a link and not presented as an in-place reveal." ], "implementationChecklist": [ "Use native details and summary when the platform supports it, or use a real button with expanded state and a controlled content region.", "Write the summary as a question or noun phrase that names the exact hidden explanation.", "Keep the hidden content short, in the same context, and free of primary actions or unrelated controls.", "Place the disclosure beside the field, paragraph, table row, or decision it explains.", "Keep focus on the summary after mouse or keyboard toggling unless the user followed an error link that intentionally targets the revealed content.", "Open disclosures that contain validation targets, search matches, or deep-linked content and expose that state visibly.", "Test closed, open, validation-opened, narrow-screen, keyboard, screen-reader, print, and no-style states." ], "commonMisuses": [ "Using vague summaries such as More, Details, or Click here.", "Hiding content most users must read before continuing.", "Putting validation errors only inside a closed disclosure.", "Using many details controls as an accordion without multi-section structure or summaries.", "Mixing reveal controls with navigation links that leave the page.", "Moving focus unexpectedly or clearing form values when the disclosure toggles.", "Putting long workflows, forms, tables, or several branches inside a small disclosure." ], "critiqueQuestions": [ "Can users decide whether to open this from the summary alone?", "Is the hidden content truly optional for most users?", "Would this be clearer as always-visible helper text, an accordion, inline message, related link, help page, or details panel?", "What happens if validation, search, or a deep link targets content inside the closed disclosure?", "Does opening and closing preserve nearby field values, focus, and scroll context?", "Are there enough disclosures on the page that users now need a different structure?" ], "relatedPatterns": [ "accordion", "inline-message", "related-links", "error-summary", "in-page-anchor-navigation" ], "comparisons": [ "disclosure-details-vs-accordion-vs-inline-message-vs-related-links" ], "sourceIds": [ "wai-aria-apg-disclosure", "mdn-html-details-element", "govuk-details-component" ] }, { "id": "draft-state", "completionStatus": "complete", "name": "Draft state", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Unpublished object version lifecycle", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users lose trust in draft-capable products when they cannot tell whether they are editing a draft or the active version, who can see the changes, how to resume them, and what publish or discard will affect.", "solution": "Expose the draft as a separate recoverable object state with clear labels, last-saved time, resume and discard choices, published-version comparison, collaborator scope, unavailable-draft recovery, and a distinct publish or activation boundary.", "uiGuidance": [ "Label the current version explicitly as Draft, Unpublished changes, Published, Active, Locked, or Unavailable, and place that label near the object title, list row, editor header, and publish actions.", "Render separate actions for Resume editing, Save draft, View published, Compare changes, Discard draft, and Publish or Activate; never rely on one generic Save label for every state." ], "uxGuidance": [ "Use draft state when users need to pause work on an object, return later, and decide whether to publish, activate, discard, or keep editing an unpublished version.", "Treat discarding or publishing a draft as a lifecycle decision: explain visibility, collaborator impact, last-saved time, and whether the active version will change." ], "uiExamples": { "good": [ "A knowledge article header says Draft saved today, shows the currently published title, and offers Resume draft, Compare with published, Discard draft, and Publish.", "A work list has editing-status chips for Own draft, Unpublished changes, Locked by another user, and Published so users know which rows are safe to open." ], "bad": [ "An editor opens directly into draft text but the header only says Saved, so users cannot tell whether viewers see the changes.", "A Delete draft action appears beside Publish without explaining that shared unpublished changes from collaborators will be lost." ] }, "uxExamples": { "good": [ "A user opens a published article that has an unpublished version, chooses Resume draft, reviews a change summary, publishes, and sees the page become visible to viewers.", "A user follows an old draft link after the draft was discarded and gets an unavailable-draft message with a link back to the published item." ], "bad": [ "A user closes an editor after seeing Saved, later discovers the page was never published, and cannot find the draft in the content list.", "A user discards a shared draft and unknowingly removes another editor's unpublished changes." ] }, "problemContext": [ "The product supports creating or editing content, records, rules, pages, policies, listings, workflows, or business objects before they become active.", "Users may pause work, close the editor, follow deep links, return from a dashboard, or collaborate on unpublished changes.", "The draft can differ from a live version that remains visible to viewers, customers, systems, or downstream workflows.", "Discard, delete, publish, or activate can affect collaborators, public visibility, search visibility, locks, or business state." ], "selectionRules": [ "Choose draft state when a recoverable unpublished version exists separately from a published, active, or previously saved version.", "Use autosave form when the main need is reliable background persistence while a user is filling fields, not a separate draft lifecycle.", "Use inline edit when one local value enters edit mode and is saved or canceled immediately without durable unpublished-version management.", "Use complete complex form when many related fields need section ownership, validation, and review; add draft state only if the whole configuration has a separate inactive version.", "Use multi-step form when the work is primarily a sequence of pages with Back, Continue, saved step state, and final review.", "Show whether the current view is draft, published, active, locked, or unavailable before users edit or publish.", "When opening an active object that has a draft, ask users to resume the draft or discard it before silently showing either version.", "Keep Publish, Activate, Submit, or Send visually and semantically distinct from Save draft.", "Before discard, identify whether the draft is personal, shared, includes other contributors, or differs from the active version.", "For draft lists, expose filters or labels for own drafts, shared unpublished changes, locked records, active records, and deleted or unavailable draft links when relevant." ], "requiredStates": [ "Published or active state with no draft.", "Published or active state with an available draft.", "Draft editor state with draft label and last-saved time.", "Unpublished changes state for an already-published object.", "Resume draft confirmation state when an active object has a draft.", "Compare draft with published state before publish or discard.", "Discard draft confirmation with scope of loss.", "Published or activated state after draft promotion.", "Locked or another-user draft state.", "Unavailable draft state for deleted, published, inaccessible, or stale deep-linked drafts." ], "interactionContract": [ "Opening a draft from a list lands in draft edit mode and preserves the unpublished values.", "Opening a published object with an existing draft prompts Resume or Discard with object name and last-saved time.", "Resume shows the latest draft, not the active version, and labels it as draft throughout editing.", "View published or Compare shows what viewers currently see versus what the draft will change.", "Save draft keeps the item unpublished and recoverable without implying viewer visibility.", "Publish or Activate promotes the draft to the active version and updates visibility or downstream effects.", "Discard removes only the stated draft scope and returns users to the active version or draft list.", "Stale draft links explain why the draft is unavailable and offer a path to the active object or list." ], "implementationChecklist": [ "Model active, draft, unpublished-changes, locked, unavailable, and published states separately instead of deriving them from a generic dirty flag.", "Store draft owner, collaborators, last-saved timestamp, source active version, and publish readiness.", "Add labels and filters wherever drafts appear: dashboards, object lists, editor headers, breadcrumbs, recent-work surfaces, and deep-link recovery pages.", "Separate Save draft from Publish, Activate, Submit, or Send in copy, placement, disabled logic, analytics, and permissions.", "Provide Resume, View published, Compare, Discard, and Publish actions only when each action is valid for the current state.", "Warn before discard or delete when the draft is shared, has collaborators, or contains unpublished changes by others.", "Handle missing drafts, stale bookmarks, deleted drafts, published drafts, permission loss, session expiry, locks, and another user's draft.", "Test draft discovery, resume, publish, discard, reload, deep links, permissions, collaboration, mobile return, screen reader labels, and keyboard access." ], "commonMisuses": [ "Using Saved to mean both saved draft and published content.", "Opening the draft silently when users expected to view the active version.", "Hiding draft labels in lists so users cannot find unpublished work later.", "Making Publish and Save draft adjacent buttons with identical visual weight and vague labels.", "Discarding shared unpublished changes without collaborator scope warnings.", "Treating a draft as merely a form dirty state even though it survives navigation and appears in object lists.", "Failing to explain why a bookmarked draft is gone after publish, discard, deletion, or permission change." ], "critiqueQuestions": [ "Can users tell whether they are viewing draft, published, active, locked, or unavailable content?", "Where can users find drafts after closing the editor?", "Does Save draft clearly differ from Publish or Activate?", "What exactly is lost when the user discards this draft?", "Can users compare the draft with the active version before publishing or discarding?", "What happens to collaborators' unpublished changes, locks, and stale draft links?" ], "relatedPatterns": [ "autosave-form", "inline-edit", "complete-complex-form", "multi-step-form", "error-state" ], "comparisons": [ "draft-state-vs-autosave-form-vs-inline-edit-vs-complete-complex-form" ], "sourceIds": [ "sap-fiori-draft-handling", "atlassian-confluence-drafts", "microsoft-sharepoint-publish-draft", "gitlab-saving-and-feedback" ] }, { "id": "drag-and-drop", "completionStatus": "complete", "name": "Drag and drop", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Pointer or touch movement that picks up an object and drops it onto a valid destination", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Drag and drop makes movement feel direct, but it often hides destination rules, conflicts with scroll and selection, fails for keyboard or assistive technology users, and can change data before users understand the destination or consequence.", "solution": "Design drag and drop as a complete movement contract: explicit pickup, drag preview, valid targets, insertion feedback, drop result, cancellation, constraints, recovery, and equivalent non-drag move controls that produce the same outcomes.", "uiGuidance": [ "Render drag and drop with a visible draggable object, pickup affordance, drag preview, valid and invalid drop targets, insertion or placement feedback, cancellation, and a non-drag equivalent move path.", "Show what will change before drop: source, destination, order position, affected count, constraints, and whether the operation moves, copies, links, reorders, assigns, or changes status." ], "uxGuidance": [ "Use drag and drop when direct object movement between destinations is faster and more understandable than choosing source and destination from separate controls.", "Treat dragging as an enhancement, not the only path; keyboard, switch, screen reader, touch, mouse, and users with limited precision need explicit Move, Reorder, or Choose destination controls." ], "uiExamples": { "good": [ "A task card has a visible drag handle, lifts on pickup, highlights valid columns, previews the insertion position, blocks Done with a WIP warning, and offers a Move to column menu.", "A dashboard tile reorder flow shows drag handles, current position, target position, invalid zones, Save layout, Cancel, and keyboard Move up or Move down controls.", "A file move surface shows source folder, destination folder, copy versus move mode, drop confirmation for shared folders, and undo move." ], "bad": [ "Cards move only by pointer drag, with no keyboard move controls or destination menu.", "Every column highlights as valid even when the user cannot drop into locked or full columns.", "Dropping a record immediately changes ownership and triggers notifications with no preview, confirmation, or undo." ] }, "uxExamples": { "good": [ "A user picks up a card, drags it over Review, sees the insertion line and WIP count, drops it, then receives Moved to Review with Undo.", "A keyboard user opens Move, chooses Review, confirms the same WIP warning, and focus returns to the moved card in its new column.", "A user drags outside any target and the card returns to its original source without changing status." ], "bad": [ "A user starts scrolling a board and accidentally drags a card into Done.", "A screen reader user hears only Card but cannot discover available destinations.", "A drop target accepts a card visually but the server rejects it silently after the card disappears." ] }, "problemContext": [ "Users need to move, copy, reorder, assign, group, place, or change status for cards, files, tiles, rows, objects, layers, widgets, or records.", "The interface has one or more source objects and destinations such as columns, lists, folders, groups, positions, canvases, zones, or containers.", "The move can be local, persisted to a server, constrained by permissions, blocked by business rules, or coupled to workflow side effects.", "The same surface may also support click, long press, swipe action, text selection, scroll, multi-select, keyboard movement, and context menus." ], "selectionRules": [ "Choose drag and drop when the design problem is moving an object from a source to a destination, position, group, or order.", "Use touch gesture when the question is the broader gesture vocabulary, target sizing, cancellation, and equivalent controls across many gestures.", "Use long press when sustained contact is only the pickup or secondary-action invocation before drag begins.", "Use drag-and-drop upload when the dragged object comes from the operating system as files and the product needs upload validation and queue states.", "Use kanban board when the primary pattern is workflow columns, WIP limits, card details, filtering, and status mapping; drag may be one input method inside it.", "Use sort controls when users choose a deterministic ordering rule rather than manually positioning individual objects.", "Use list view, table, tree grid, or card grid when object presentation, selection, and row or card action anatomy are the main concerns.", "Provide explicit Move, Reorder, Destination, Position, or Assign controls for every non-essential drag outcome.", "Require confirmation or review when drop changes permissions, ownership, billing, notifications, destructive state, or external side effects.", "Do not use drag and drop for invisible commands, hidden deletion, primary-only workflows, or tasks where destinations cannot be previewed clearly." ], "requiredStates": [ "Idle state with draggable object identity and visible drag handle or move affordance.", "Pickup state that confirms which object or selected set is being moved.", "Dragging state with preview, source placeholder, and object count.", "Valid target hover state with destination name and insertion or placement indicator.", "Invalid target state with reason such as permission, WIP limit, locked folder, unsupported type, or max items.", "Auto-scroll or edge-scroll state for large lists, boards, and canvases.", "Drop preview state showing move, copy, link, reorder, assign, or status-change consequence before commit.", "Successful drop state with status message, stable focus, updated position, and undo where appropriate.", "Canceled drag state that returns the object to source when released outside a valid target or Escape is used.", "Failed drop or server-rejected state that restores the prior model and explains retry or fallback.", "Equivalent keyboard, screen reader, switch, touch, mouse, and explicit move-menu state.", "Multi-select or bulk drag state with selected count and destination constraints.", "Mobile compact and large-text state where handles, targets, and messages remain readable." ], "interactionContract": [ "Dragging starts only from the intended handle, object, or selected set, not from unrelated scroll or text-selection movement.", "The source object remains identifiable during drag through a preview, ghost, placeholder, or selected-set label.", "Targets report whether they are valid, invalid, full, locked, hidden, filtered, or permission-limited before drop.", "The drop location shows exact insertion position, destination, or placement zone before the user releases.", "Releasing outside a valid target, pressing Escape, or cancelling the equivalent move path leaves the model unchanged.", "The product commits the move only after a valid drop or explicit confirmation, and reports success, failure, or pending sync.", "Equivalent controls expose the same destinations, constraints, warnings, confirmation, undo, and error states as drag.", "Drag does not steal vertical scroll, text selection, swipe action, pull-to-refresh, or system gestures without a deliberate handle or threshold." ], "implementationChecklist": [ "Inventory draggable object types, allowed sources, destinations, move modes, constraints, side effects, and equivalent controls.", "Define pickup target, handle size, drag threshold, drag preview, source placeholder, target highlighting, insertion indicator, and drop commit timing.", "Expose invalid target reasons before drop and keep them available as text, not color alone.", "Implement Move to, Reorder, Position, Assign, or destination menus that call the same command handlers as drag.", "Preserve focus, selection, scroll anchor, filters, expanded state, and object identity after move, cancel, undo, and server failure.", "Add undo, confirmation, or pending review for risky moves and any operation with external side effects.", "Resolve conflicts with long press, scroll, swipe action, text selection, nested draggable regions, auto-scroll, and browser-native drag behavior.", "Test keyboard-only movement, screen reader actions, switch control, touch, mouse, trackpad, stylus, mobile landscape, large text, invalid targets, concurrent updates, and server rejection." ], "commonMisuses": [ "Making drag the only way to move, reorder, assign, or change status.", "Showing no valid target, invalid target, insertion, or destination feedback before drop.", "Letting any pointer movement drag when users intended to scroll or select text.", "Dropping into hidden, filtered, full, locked, or permission-denied destinations without explanation.", "Changing workflow state, permissions, ownership, or notifications immediately without confirmation or undo.", "Using drag and drop upload guidance for object movement inside the product.", "Leaving focus behind after a keyboard-equivalent move.", "Persisting a failed server move visually and making the model inconsistent." ], "critiqueQuestions": [ "What object or selected set is being moved, and where is the source shown during drag?", "Which destinations are valid, invalid, full, locked, or permission-limited, and how do users know before drop?", "What exact result happens on drop: move, copy, link, reorder, assign, status change, or external side effect?", "What non-drag control completes the same move for keyboard, screen reader, switch, and low-precision users?", "How can users cancel before drop, recover after drop, and understand server rejection?", "How does drag avoid fighting scroll, long press, swipe action, text selection, nested drag regions, and system gestures?", "Where does focus land after pickup, cancel, drop, undo, failure, and equivalent move?" ], "relatedPatterns": [ "touch-gesture", "long-press", "drag-and-drop-upload", "kanban-board", "sort-controls", "list-view" ], "comparisons": [ "drag-and-drop-vs-touch-gesture-vs-long-press-vs-drag-and-drop-upload-vs-kanban-board-vs-sort-controls" ], "sourceIds": [ "mdn-html-drag-and-drop-api", "wcag-dragging-movements", "w3c-wcag-pointer-cancellation-drag-drop", "trello-board-basics", "w3c-wcag-target-size-minimum" ] }, { "id": "drag-and-drop-upload", "completionStatus": "complete", "name": "Drag-and-drop upload", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Drop-zone file upload enhancement with file input fallback", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Drag-and-drop upload can make desktop attachment workflows faster, but it fails when the target is ambiguous, the page swallows drops, non-file drags are accepted, or the drop zone replaces accessible file selection.", "solution": "Provide a clear drop zone as an enhancement on top of a real file picker, expose drag states, prevent destructive browser defaults, validate dropped files, allow cancellation and removal, and keep upload progress separate from final submission.", "uiGuidance": [ "Render a large labelled drop zone with clear copy that says users can drag files there or activate a normal file picker, plus visible format, size, and count requirements.", "Change border, background, icon, and status text for drag-enter, valid drag-over, invalid drag-over, drag-leave, dropped, uploading, uploaded, and error states without relying on color alone." ], "uxGuidance": [ "Use drag-and-drop upload as an enhancement for users who can drag files from a file manager, while preserving an equivalent click, keyboard, and mobile path.", "Let users cancel by leaving or dropping outside the target, reject non-file or unsupported drags without losing progress, and require review before final submission." ], "uiExamples": { "good": [ "A drop zone says Drag bank statements here or choose files, shows PDF/PNG/JPG up to 10 MB, highlights when files hover over it, lists two dropped filenames, and keeps a Choose files button visible.", "A media uploader thickens the drop-zone border on valid drag-over, shows Not supported for a dragged link, and stacks uploaded filenames below the target with remove controls." ], "bad": [ "A dashed rectangle says Drop here but has no label, no click fallback, no accepted formats, and no state change while files hover over it.", "The whole page becomes a hidden drop target that opens the dropped file in the browser when users miss the box." ] }, "uxExamples": { "good": [ "A user drags two PDFs over the zone, sees the target activate, drops them, reviews both filenames, removes the wrong one, uploads the remaining file, and then continues.", "A keyboard user activates Choose files in the same drop zone and gets the same queued-file, progress, remove, and retry states as pointer users." ], "bad": [ "A user drags a file over the page, misses the small target, and the browser navigates to the file, wiping unsaved answers.", "A mobile user sees only Drag files here and cannot upload because there is no file-picker button or alternate route." ] }, "problemContext": [ "Users are likely to have one or more files visible in a desktop file manager and want to move them into the product quickly.", "The same workflow must still work for keyboard, mobile, assistive technology, public-device, and locked-down desktop users.", "Files can be dragged over the wrong part of the page, leave the target, include unsupported types, or include non-file data such as links or text.", "The browser may try to open dropped files unless the app prevents default handling only when file drags are involved.", "The product needs to show queued, uploading, uploaded, failed, removed, and final submit states after a drop." ], "selectionRules": [ "Choose drag-and-drop upload when dropping files from a desktop file manager is a common, useful shortcut.", "Use ordinary file upload when the task needs dependable attachment selection without extra drop-zone complexity.", "Use text input when users can type the needed value instead of attaching a file.", "Use multi-step form when the upload is one controlled step in a longer saved journey.", "Use bulk import when the dropped file is structured data requiring mapping, row validation, and an import report.", "Do not make drag-and-drop the only upload path.", "Do not turn the entire page into an invisible drop target unless every drop outcome is clear, cancellable, and recoverable.", "Accept only file drags in the drop zone and reject links, text, unsupported formats, too many files, or oversized files with explicit messages.", "Prevent browser default file navigation only for file drags and only where the app can give users a safe outcome.", "Require review or a separate submit action when a dropped file could affect a high-stakes transaction." ], "requiredStates": [ "Idle drop zone with visible label, requirements, and choose-file fallback.", "Drag enter state announcing that files are over the upload area.", "Valid drag-over state showing the target will copy or accept the files.", "Invalid drag-over state for links, text, folders, unsupported formats, or too many files.", "Drag leave or cancelled state that returns the zone to idle without uploading.", "Dropped queue state listing filenames, type, size, and count.", "Uploading state with progress tied to each dropped file or batch.", "Uploaded state with remove or replace controls.", "Rejected drop state with clear recovery and requirements repeated.", "Submitted state that confirms dropped files are included only after final review." ], "interactionContract": [ "Dragenter and dragover make the target visibly active only when the incoming data includes files.", "Dragover cancels the browser default action so the drop event can be handled and the cursor can show copy or none.", "Dropping files reads DataTransfer files or items, validates them, and adds accepted files to the same queue used by the file input fallback.", "Dropping links, text, folders, unsupported formats, or too many files keeps existing queued files intact and explains the rejected data.", "Leaving the target before release cancels the drag affordance and does not upload anything.", "Removing a dropped file affects only that file and keeps other queued files and form answers visible.", "Click, keyboard, and file-input selection produce the same selected-file list, progress, validation, remove, retry, and submit behavior as drag-and-drop." ], "implementationChecklist": [ "Define accepted file kinds, maximum file size, maximum count, folder policy, duplicate policy, non-file drag policy, upload timing, and final submission boundary.", "Implement the drop target with a real file input or accessible button fallback so activation with Enter, Space, click, touch, and screen readers follows the same code path.", "Handle dragenter, dragover, dragleave, and drop events; prevent default file navigation for file drags and set an appropriate drop effect.", "Process DataTransfer files, reject non-file data safely, validate type, size, and count, and add accepted files to a visible queue.", "Show active, invalid, cancelled, queued, uploading, uploaded, failed, removed, and submitted states near the drop zone.", "Provide remove, replace, retry, and final review controls before submission.", "Test desktop file-manager drags, missed targets, browser Back, keyboard fallback, mobile fallback, screen readers, zoom, slow networks, duplicate files, and unsupported file types." ], "commonMisuses": [ "Replacing the normal file chooser with a drop zone that only pointer users can operate.", "Letting dropped files outside the target open in the browser and erase unsaved progress.", "Showing a dashed box that does not change state during drag enter, drag over, or invalid drag.", "Accepting links or text as if they were files.", "Automatically submitting a transaction immediately after drop.", "Clearing all queued files when one dropped file is invalid.", "Using a drop zone for bulk import without mapping, row-level errors, partial success, or import results." ], "critiqueQuestions": [ "Do users actually have files available to drag from a desktop file manager?", "What is the equivalent path for keyboard, mobile, screen reader, public-device, and locked-down desktop users?", "What happens if users drag over the page, leave the target, drop outside it, or drop a link instead of a file?", "Can users see which files were accepted, rejected, uploading, uploaded, removed, or still waiting for final submit?", "Does the implementation prevent destructive browser file navigation without hijacking ordinary links and text?", "When should users be allowed to undo, remove, retry, or confirm after a drop?" ], "relatedPatterns": [ "file-upload", "text-input", "multi-step-form", "inline-validation", "error-summary", "loading-skeleton" ], "comparisons": [ "drag-and-drop-upload-vs-file-upload-vs-multi-step-form-vs-text-input" ], "sourceIds": [ "carbon-file-uploader-component", "mdn-file-drag-and-drop", "govuk-file-upload-component", "w3c-wcag-pointer-cancellation-drag-drop" ] }, { "id": "drawer", "completionStatus": "complete", "name": "Drawer", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Supplemental edge panel for current-context detail or light actions", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need supplemental detail or light actions related to the current page, but a full page would break context and a modal would over-block comparison with the underlying content.", "solution": "Open an edge-aligned drawer that keeps the parent page visible, identifies the selected object or task, supports close and focus return, and optionally allows pinned side-by-side comparison when background context remains useful.", "uiGuidance": [ "Render a drawer as an edge-aligned panel with a visible heading, selected-object identity, close control, stable width, and clear relationship to the page content it supplements.", "Use visual treatment, scrim, pinning, and layout width to communicate whether the drawer is non-modal comparison space, pinned side-by-side content, or a temporary modal overlay." ], "uxGuidance": [ "Use drawers to preserve parent-page context while users inspect supplemental detail or perform simple adjacent actions.", "Keep drawer entry, object switching, close behavior, focus return, and underlying page-state preservation predictable so users do not lose their place." ], "uiExamples": { "good": [ "A right-side case details drawer opens from a table row, names Claim C-1042, shows status, owner, activity, and a close button while the table remains visible.", "A pinned inspector drawer sits beside a chart so users can compare selected segment details with the chart." ], "bad": [ "A panel slides over the table with the title Details, no close control, and no selected record name.", "A drawer contains navigation links, filters, account settings, and destructive commands under one unlabeled heading." ] }, "uxExamples": { "good": [ "Opening the drawer preserves the table filter and selected row, Next item updates the drawer title, Escape closes it, and focus returns to the selected row.", "Pinning the drawer keeps it open side-by-side while users select other rows for comparison." ], "bad": [ "The drawer keeps showing Claim C-1042 after the user selects Claim C-1043 in the table.", "Closing the drawer sends focus to the page header and clears the user's selected row and scroll position." ] }, "problemContext": [ "A table row, card, chart point, activity item, or object summary has more detail than fits inline.", "Users benefit from comparing drawer content with the page behind it.", "The drawer content is supplemental or lightly actionable, not a long independent workflow.", "The product can maintain selected-object state, close behavior, and focus return when the drawer opens and closes." ], "selectionRules": [ "Choose drawer when users need page-adjacent detail, preview, metadata, comments, simple actions, or object inspection without leaving the current page.", "Use modal dialog when the task must block the page until the user completes or cancels it.", "Use navigation drawer when the side surface contains app destinations rather than contextual detail for the current page.", "Use filter panel when the side surface contains criteria that narrow results and require applied-count, result-count, and clear-state synchronization.", "Use inline disclosure, popover, tooltip, or hover card when the information is short, local, or only needed temporarily near one control.", "Use a full page or details panel when the content requires deep reading, shareable URL state, long editing, or durable navigation history.", "Use a pinned or non-modal drawer when users must compare details with the underlying list or chart.", "Use a modal drawer only when background interaction would create conflicting state; provide scrim, Escape behavior, and focus containment in that case." ], "requiredStates": [ "Closed state with a clear opener tied to a specific object or page section.", "Opening state that identifies the selected object and moves focus to the drawer heading or first useful control.", "Open drawer state with visible title, object identity, close control, and supplemental content.", "Pinned or non-modal comparison state when background content remains intentionally usable.", "Modal or temporary state when background interaction must be blocked until close.", "Object-switching state where choosing another row updates the drawer without stale content.", "Dismissed state that returns focus to the opener or selected object and preserves page context.", "Responsive state that adapts drawer width, side, or full-screen behavior without changing the task contract." ], "interactionContract": [ "The opener names or is adjacent to the object whose detail will appear in the drawer.", "Opening the drawer does not unexpectedly navigate away or erase list, filter, selection, scroll, or chart state.", "The drawer title names the current object or supplemental task, not just Drawer.", "A visible close control, Escape behavior, and route/back handling close the drawer predictably.", "Focus moves into the drawer on open and returns to the opener, selected row, or next logical object on close.", "If the drawer is non-modal, background controls that remain usable are intentionally designed and do not conflict with drawer state.", "If the drawer is modal, focus stays inside the drawer and background content is inert until close.", "Changing the selected object while the drawer is open updates the drawer title, content, and status without leaving stale information visible." ], "implementationChecklist": [ "Define whether the drawer is non-modal, pinned, dismissible, or modal for this workflow.", "Anchor the drawer to a page edge and size it so main content remains useful when comparison matters.", "Show the selected object, record, or task name in the drawer heading.", "Provide a labelled close button and Escape/back behavior.", "Move focus into the drawer on open and restore focus after close.", "Preserve underlying page state such as filters, selected rows, scroll position, and drafted inputs.", "Handle object changes while open with an updated heading, status, and content rather than stale details.", "Keep drawer actions light and move long workflows to a page, modal task, or dedicated editor.", "Test narrow viewports, long drawer content, scroll boundaries, pinned state, keyboard order, and screen reader names." ], "commonMisuses": [ "Using a drawer as an unlabeled junk panel for unrelated commands, navigation, filters, and help.", "Opening a drawer with no close control or keyboard dismissal.", "Treating a drawer like a modal while the page behind it remains partly interactive by accident.", "Covering the exact content users need for comparison without a pinned or resized state.", "Leaving stale details visible after the selected object changes.", "Putting a long multi-step workflow in a narrow drawer with hidden primary actions.", "Returning focus to the top of the page instead of the object or opener that launched the drawer." ], "critiqueQuestions": [ "What parent-page context must remain visible while this drawer is open?", "Is the drawer content supplemental, or has it become a separate task needing a page or modal?", "Can users close the drawer by pointer, keyboard, Escape, and route/back behavior?", "Where does focus move on open, close, object switch, and responsive breakpoint changes?", "Does changing the selected object update the drawer immediately and visibly?", "Would a navigation drawer, filter panel, modal dialog, popover, or details panel better match the content?" ], "relatedPatterns": [ "modal-dialog", "navigation-drawer", "filter-panel", "notification-center", "side-navigation" ], "comparisons": [ "drawer-vs-modal-dialog-vs-navigation-drawer-vs-filter-panel" ], "sourceIds": [ "fluent-drawer-component", "nord-drawer-component", "material-navigation-drawer", "wai-aria-apg-dialog-modal" ] }, { "id": "drawer-with-no-close-or-return-path", "completionStatus": "complete", "name": "Drawer with no close or return path", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Unrecoverable drawer anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "A drawer opens from the current page but lacks a reliable way to dismiss it and return to the exact context that launched it.", "solution": "Treat missing drawer close and return paths as an anti-pattern: every temporary drawer needs visible close, keyboard and route dismissal, focus return, state preservation, and responsive back behavior that matches the opener and selected object.", "uiGuidance": [ "Treat a drawer without visible close, Escape, back, scrim, or focus-return behavior as an anti-pattern even when the drawer content itself is useful.", "Provide a labelled close affordance, object title, dismissal status, and responsive back route in the drawer header or persistent action area, not behind hover, gesture-only, or overflow-only controls." ], "uxGuidance": [ "Use this anti-pattern during review when opening a drawer leaves users uncertain how to get back to the row, filter, list, map, chart, or workflow that launched it.", "Design drawer exits as one recovery contract: users can close intentionally, keep or discard unsaved work, return focus locally, and resume with selection, filters, scroll position, and responsive context intact." ], "uiExamples": { "good": [ "A case details drawer names Claim C-1042, has a Close details button in the header, supports Escape, and shows focus will return to the selected row.", "A mobile full-screen drawer has a Back to queue control, selected case title, and keeps the urgent filter when returning.", "A dirty edit drawer intercepts close with a scoped discard review instead of removing every close route." ], "bad": [ "A right drawer slides over a table with no close button and no Escape response.", "The drawer closes visually but sends keyboard focus to the page header and clears the selected row.", "A mobile drawer takes the whole screen and relies on a swipe gesture that keyboard and screen reader users cannot perform." ] }, "uxExamples": { "good": [ "A reviewer opens a drawer, switches rows, presses Escape, and lands back on the current selected row with filters preserved.", "Browser back closes the temporary drawer once and leaves the user in the same result set rather than navigating away unexpectedly.", "If unsaved notes exist, Close opens a discard decision and Keep editing returns focus to the note field." ], "bad": [ "A keyboard user tabs through a drawer repeatedly because there is no close target or documented Escape exit.", "A touch user cannot return from a full-screen inspector without refreshing the page.", "After close, the original row, filter, scroll position, and focus target are lost." ] }, "problemContext": [ "A side drawer, inspector, side sheet, mobile full-screen drawer, or navigation drawer opens over or beside the current page.", "The surface is temporary, contextual, or responsive rather than a permanent workspace pane.", "Users need to return to a specific row, card, filter result, map marker, chart point, or navigation trigger after closing.", "The drawer may include dirty fields, selected-object switching, scrim dismissal, browser back handling, or narrow viewport layout changes." ], "selectionRules": [ "Flag this anti-pattern when a temporary drawer has no visible close control, no Escape path, no back-route dismissal, no equivalent for gesture-only close, or no predictable focus return.", "Flag it when the drawer closes but loses the selected object, scroll position, active filter, draft text, route state, or opener focus.", "Use a standard drawer when the panel is temporary supplemental content with explicit close and return behavior.", "Use a details panel when the content is persistent workspace layout and close is not part of the contract.", "Use a modal dialog when background interaction must be blocked and focus must be contained until users complete or cancel the task.", "Use navigation drawer when the panel changes destinations; still provide dismissal, selected destination state, and focus recovery.", "Use a full page when the drawer needs long editing, history, shareable URL state, or complex return management.", "If unsaved work blocks immediate close, show a discard or save decision rather than trapping users by removing dismissal." ], "requiredStates": [ "Closed state with a clear opener and remembered return target.", "Open state with selected-object title, labelled close button, and visible relationship to the originating context.", "Keyboard dismissal state where Escape closes or opens a scoped discard review.", "Browser back or route dismissal state that closes the drawer without losing page context.", "Scrim or outside-click state where temporary modal drawers either dismiss predictably or explain why dismissal is blocked.", "Focus return state where close restores focus to the opener, selected row, or next logical object.", "Object-switching state where the return target updates when selection changes.", "Dirty-edit state where closing asks whether to keep editing, discard, or save.", "Mobile or narrow viewport state with a visible Back or Close route and preserved list/filter context.", "Bad state showing missing close, missing Escape, lost focus, lost page state, gesture-only close, and no mobile return." ], "interactionContract": [ "Opening the drawer records the opener or selected object as the return target.", "The drawer exposes a labelled close control that remains reachable at the top or in a persistent action area.", "Escape closes dismissible drawers or moves focus into a scoped discard review when dirty state exists.", "Browser back, route changes, scrim clicks, close button, and programmatic close use the same cleanup path.", "Closing preserves filters, selected row, scroll position, draft inputs, and object context unless users explicitly discard them.", "Focus returns to the opener, selected row, active marker, or next logical object rather than the document start.", "Responsive full-screen drawers include a visible Back or Close path and restore the previous layout context.", "Gesture close has pointer, keyboard, and assistive-technology equivalents.", "If close is intentionally blocked during a commit, the drawer explains the temporary lock and re-enables close when safe." ], "implementationChecklist": [ "Inventory every drawer, side sheet, inspector, and mobile drawer that can open temporarily.", "Identify the opener, selected object, route state, filter state, scroll position, and focus target to restore.", "Add a labelled close control in a stable header or sticky action area.", "Implement Escape dismissal or a dirty-state discard review.", "Handle browser back, route changes, scrim click, outside click, close button, and object switch through one close routine.", "Return focus to the current selected object or opener after every dismissal path.", "Preserve underlying page state unless the user explicitly changes or discards it.", "Provide mobile Back or Close controls when the drawer becomes full-screen.", "Test keyboard-only, touch, screen reader, high zoom, route/back, dirty edits, object switching, and repeated open-close cycles." ], "commonMisuses": [ "Hiding close in an overflow menu or offscreen toolbar.", "Relying on swipe-only dismissal for mobile drawers.", "Letting Escape do nothing because the drawer was implemented as a plain div.", "Closing the drawer while focus moves to the page header or disappears.", "Clearing filters or selected rows when the drawer closes.", "Treating browser back as page navigation instead of first closing the temporary drawer.", "Blocking close during unsaved work without offering Keep editing, Discard, or Save choices." ], "critiqueQuestions": [ "What exact element receives focus after each close route?", "Can pointer, keyboard, touch, screen reader, and route/back users all leave the drawer?", "Does the drawer preserve the row, filter, scroll, and draft state that existed before opening?", "What happens if the selected object changes while the drawer is open?", "What happens when the drawer is full-screen on mobile or at high zoom?", "Is close blocked because of dirty state, or because no dismissal contract was designed?" ], "relatedPatterns": [ "drawer", "modal-dialog", "navigation-drawer", "details-panel", "focus-traversal", "bottom-sheet", "sheet" ], "comparisons": [ "drawer-with-no-close-or-return-path-vs-drawer-vs-modal-dialog-vs-navigation-drawer-vs-details-panel" ], "sourceIds": [ "fluent-drawer-component", "nord-drawer-component", "material-navigation-drawer", "wai-aria-apg-dialog-modal", "wcag-no-keyboard-trap", "wcag-focus-order" ] }, { "id": "editable-ai-output", "completionStatus": "complete", "name": "Editable AI output", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Editable generated draft with provenance, review, and apply controls", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Generated output often needs human revision before use, but ordinary editing can erase provenance, hide which claims were generated or user edited, break citations, obscure unsafe or unsupported edits, and make it unclear whether the final output was reviewed before being applied.", "solution": "Provide an editor for generated drafts that tracks generated and user-edited content separately, preserves or invalidates source mappings explicitly, supports accept and reject controls, saves drafts, gates apply when review is required, and offers undo or regeneration paths that do not overwrite manual work without warning.", "uiGuidance": [ "Render editable AI output as a generated draft with a clear boundary between original generated text, user-edited text, tracked changes, source mapping, citation preservation, and final applied output.", "Keep source and review affordances visible while editing so users can tell when an edit is supported, unsupported, unsafe, stale, conflicted, or ready to accept, reject, save, copy, regenerate, or apply." ], "uxGuidance": [ "Use editable AI output when users need to revise generated content after creation while retaining provenance, citations, source coverage, and a deliberate apply or save contract.", "Treat manual edits as a change in evidence state: show which source mappings remain valid, which citations need review, which edits are unsupported, and which final actions are blocked until review is complete." ], "uiExamples": { "good": [ "A policy assistant shows a generated draft answer with citation chips, user-edited spans, tracked change controls, source mapping indicators, and Apply output disabled until unsupported edits are reviewed.", "A support reply drafter lets the agent regenerate from a selected edit, restore the original generated version, copy the edited draft, and preserve citations that still map to unchanged claims." ], "bad": [ "A final-looking answer becomes editable with no generated-versus-user-edited distinction, no citation preservation state, and no undo to the generated draft.", "A product rewrites the prompt when users edit the answer, silently regenerates the visible text, and lets the user apply uncited claims without review." ] }, "uxExamples": { "good": [ "A reviewer changes one sentence, sees it marked as user edited, accepts the tracked change, reviews a stale source warning, and applies the output only after unsupported text is resolved.", "A mobile user opens the source panel from the edited paragraph, sees which citations remain valid, rejects an unsafe edit, and saves the draft for another reviewer." ], "bad": [ "A user edits a generated compliance summary and all citations disappear, leaving no way to know which claims remain source-backed.", "A user taps Regenerate and the system replaces their manual edits without conflict warning or recovery." ] }, "problemContext": [ "An AI system has produced text, table content, code, message copy, policy analysis, customer response, document summary, or another draft artifact.", "Users can improve the generated output directly instead of only changing the original prompt.", "Some generated claims are grounded in citations, retrieved sources, tool outputs, or conversation context that may no longer support the edited text.", "The final output may be copied, saved, applied to a record, sent to another person, or used in a higher-risk workflow.", "Reviewers may need to distinguish model-generated content from human-edited content after the edit is complete." ], "selectionRules": [ "Choose editable AI output when the primary object is generated output after creation and users need to revise, review, save, copy, or apply that output.", "Use prompt box when users are still composing the request before generation rather than editing the generated result.", "Use inline edit when the object is an ordinary record field or table value with no generated provenance, source mapping, citation preservation, or regeneration boundary.", "Use streaming response when users mainly need to monitor partial generated output as it arrives, before the answer has settled into an editable draft.", "Use citation display when users need claim-level source previews; editable AI output should link edited claims to citation display when claims are source-backed.", "Use source grounding display when the task is whole-answer evidence coverage rather than editing one draft.", "Show generated draft, user edited, source mapping, citation preservation, unsupported edit, tracked change, stale source, unsafe edit, review required, and conflict edit states before apply.", "Require deliberate accept edit, reject edit, save draft, copy edited, undo to generated, regenerate from edit, and apply output actions with clear consequences.", "Do not make the generated answer look final while silently accepting edits, dropping citations, rewriting the prompt, or applying output without review.", "Do not let regeneration overwrite manual edits unless the user can compare, keep, discard, or recover the edited version." ], "requiredStates": [ "Generated draft state with original generated content, creation time, model or run reference, and source coverage visible.", "User-edited state that marks changed text separately from original generated text.", "Source mapping state that shows which edited claims still map to citations, retrieved sources, or tool outputs.", "Citation preservation state for unchanged or still-supported claims.", "Unsupported edit, unsafe edit, stale source, and source drift warning states.", "Tracked change state with accept edit and reject edit controls.", "Review required state that blocks apply output until unsupported, unsafe, or stale content is resolved.", "Partial edit and selected-range edit states for revising only part of a generated answer.", "Conflict edit state when regeneration, collaboration, policy update, or source refresh conflicts with manual edits.", "Save draft, copy edited, undo to generated, regenerate from edit, and apply output states.", "Mobile editor state that preserves source access, review status, edit actions, and final apply controls in constrained space." ], "interactionContract": [ "The generated draft, user edits, tracked changes, source mappings, citations, review status, and final output state are modeled as distinct data rather than one mutable text blob.", "Editing text does not silently update the original prompt, erase the generated baseline, or imply that citations still support changed claims.", "Accept edit commits a tracked user change into the draft while retaining its author and evidence state.", "Reject edit restores the affected range to the generated draft or previous accepted text.", "Undo to generated restores the original generated version or a selected range without deleting saved versions.", "Regenerate from edit uses the current accepted draft as context and warns when regeneration may conflict with manual edits.", "Apply output is unavailable or blocked when unresolved unsupported edits, unsafe edits, stale sources, or conflicts remain.", "Copy edited and save draft preserve visible review warnings or metadata when the destination requires provenance.", "Source mapping opens the relevant citation, source grounding, tool output, or evidence panel for the edited claim." ], "implementationChecklist": [ "Store generated baseline text, edited draft text, selected ranges, tracked changes, author, timestamp, source mappings, citation IDs, review status, and apply state separately.", "Represent unsupported, unsafe, stale, conflicted, accepted, rejected, copied, saved, regenerated, and applied states as explicit values.", "Keep citation preservation logic claim-aware so unchanged claims keep citations and changed claims require revalidation.", "Connect edited claims to citation display, source grounding display, tool-use visibility, and audit records where those are the actual evidence surfaces.", "Require review before apply when an edit changes factual claims, removes qualifying language, changes numerical values, or alters policy-sensitive text.", "Add compare controls for generated draft versus edited draft and for edited draft versus regenerated output.", "Protect manual edits from accidental overwrite by regeneration, source refresh, collaboration updates, browser back, or mobile navigation.", "Test long generated text, selected-range edits, pasted content, citation deletion, unsupported claims, stale source warnings, review gating, keyboard editing, screen reader status, copy behavior, and mobile wrapping." ], "commonMisuses": [ "Letting users edit a final-looking AI answer without generated-versus-user-edited status.", "Dropping all citations when one paragraph is edited.", "Preserving citation markers on claims that no longer match the cited source.", "Treating answer editing as prompt editing and hiding the generated baseline.", "Allowing apply output before unsupported edits, unsafe changes, stale sources, or conflicts are reviewed.", "Regenerating over manual edits without compare, warning, version recovery, or undo.", "Using ordinary inline edit for generated content that needs provenance and source review." ], "critiqueQuestions": [ "Can users tell which text is generated draft, user edited, accepted, rejected, unsupported, unsafe, stale, or ready to apply?", "What happens to citations and source mappings when users change a factual claim?", "Can users undo to generated, compare tracked changes, save a draft, copy edited text, and regenerate from an edit without losing work?", "Which edits block apply output and who can clear review required states?", "Does the surface explain when a source is stale, permission-limited, or no longer supports an edited claim?", "Would prompt box, inline edit, streaming response, citation display, or source grounding display better match the task?" ], "relatedPatterns": [ "inline-edit", "prompt-box", "streaming-response", "citation-display", "source-grounding-display", "confidence-uncertainty-display", "human-approval-gate", "change-review" ], "comparisons": [ "editable-ai-output-vs-inline-edit-vs-prompt-box-vs-streaming-response-vs-citation-display-vs-source-grounding-display" ], "sourceIds": [ "microsoft-word-accept-reject-tracked-changes", "google-docs-suggest-edits", "openai-prompt-engineering-guide", "microsoft-365-copilot-linked-citations", "openai-file-search-citations", "microsoft-human-ai-guidelines", "wcag-status-messages" ] }, { "id": "email-address-entry", "completionStatus": "complete", "name": "Email address entry", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Contactable email address capture field", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Email addresses look simple but are easy to mistype, may be long or uncommon, often come from password managers or copy and paste, and can affect account recovery, receipts, notifications, and access confirmation.", "solution": "Use an email-specific field with clear purpose, paste and autofill support, email keyboard and autocomplete, tolerant validation, provider typo warnings, preserved values, review and change, and confirmation loops only when mailbox access is essential.", "uiGuidance": [ "Render email entry as a labelled single-line field with purpose text, type email, autocomplete email, spellcheck disabled, enough visible width for review, field-specific errors, and optional typo warning and review states.", "Keep the full address editable and visible enough to inspect; do not split the address into local-part and domain fields or replace the user's value with an unconfirmed correction." ], "uxGuidance": [ "Use email address entry when the product must contact the user, identify an account, send a receipt, invite someone, or confirm access to a mailbox.", "Help users provide a deliverable address by allowing paste and autofill, preserving valid address forms, explaining format problems, warning about likely provider typos, and confirming back the address before consequential use." ], "uiExamples": { "good": [ "A receipt form asks for Email address, says We will only use this to send your receipt, uses type email and autocomplete email, and shows a review row before submit.", "An account recovery form accepts alex+tax@example.co.uk, warns if the domain looks like gmial.com, and lets the user either change it or keep it." ], "bad": [ "A form uses a plain text field named Contact and later rejects it as not email-shaped after submit.", "A page asks users to type the email twice, blocks paste, and silently changes homtail.com to hotmail.com." ] }, "uxExamples": { "good": [ "A user pastes alex+receipts@example.co.uk, sees it preserved exactly, reviews it on the check page, and changes it only if needed.", "A user types ada@gmial.com, receives a warning that they may have meant gmail.com, and can either fix it or keep the original address." ], "bad": [ "A user with a long work address cannot see enough of it to spot a typo before the service sends a reset link.", "A user enters a valid plus-addressed mailbox and the form rejects it because the validator only allows letters before the at sign." ] }, "problemContext": [ "The service needs to send receipts, status updates, invitations, alerts, reset links, verification messages, or account notifications.", "Users may have multiple addresses and need to know whether to give work, personal, recovery, shared, or temporary email.", "Addresses may include plus tags, subdomains, long domains, uncommon top-level domains, uppercase letters, dots, hyphens, and pasted whitespace.", "A syntactically valid email address does not prove that the user owns or can access the mailbox.", "Wrong addresses can leak information, block recovery, prevent receipts, or send a message to another person." ], "selectionRules": [ "Choose email address entry when the field value must be an email address used for contact, identity, invitation, recovery, notification, or receipt delivery.", "Use type email, autocomplete email, spellcheck false, and a visible label that says Email address or names the mailbox purpose.", "Explain why the address is needed unless the purpose is already obvious in a sign-in context.", "Allow paste, browser autofill, plus addressing, subdomains, long addresses, and uncommon domains.", "Size the field so most users can inspect at least the main part of the address, and support up to 254 characters.", "Validate empty and malformed values after blur or submit, preserve the entered value, and say how to fix it.", "Trim accidental leading and trailing spaces, but do not silently rewrite the local part, domain, or provider.", "Warn on likely provider typos and offer a suggested domain, but let users keep the original address.", "Use the multiple attribute only when the task truly accepts multiple comma-separated addresses; otherwise reject multiple addresses clearly.", "Show the captured address on review or confirmation before sending consequential email.", "Use an email confirmation loop only when the service must know that the user can access the mailbox.", "Do not require repeated email entry, block paste, or force confirmation loops unless research and risk justify the extra friction." ], "requiredStates": [ "Initial state with label, purpose hint, type email, autocomplete email, spellcheck false, and adequate width.", "Focused state with email keyboard and normal typing, paste, selection, undo, and autofill behavior.", "Pasted address state preserving plus tags, case where relevant for display, subdomains, and long domains.", "Missing required email state with field-specific error text.", "Malformed email state with an example such as name@example.com.", "Likely provider typo warning state with change, keep, or suggested-domain action.", "Multiple addresses rejected state when only one address is allowed.", "Long address state where enough of the value can be inspected and no silent truncation occurs.", "Reviewed address state with change action before receipt, notification, recovery, or invitation is sent.", "Email confirmation pending state when access to the mailbox must be proven.", "Delivered or verified state that records contactability separately from syntactic validity." ], "interactionContract": [ "Users can type, paste, autofill, edit, select, undo, and correct the email value through native input behavior.", "Submitting an empty or malformed address keeps the typed value and puts the correction next to the field or in a linked summary.", "Provider typo warnings are advisory and never overwrite the user's value without confirmation.", "Review states show the exact address that will receive messages and provide a direct change path.", "Confirmation loops explain what was sent, where it was sent, how long the code or link lasts, and how to change the address.", "The backend treats syntax validity, deliverability, ownership, and verified access as separate states." ], "implementationChecklist": [ "Use a native input with type email, autocomplete email, spellcheck false, a stable label, purpose hint, and aria-describedby for hint, warning, and error text.", "Support paste, autofill, mobile email keyboard, long values, plus tags, subdomains, uncommon domains, and copied addresses with leading or trailing spaces.", "Validate required and email-format errors on the client and server, and avoid brittle regular expressions that reject real addresses.", "Add provider typo detection for common domains only as a warning with keep and change paths.", "Use a review page, summary row, or confirmation panel before sending important email.", "Use email access confirmation only for account activation, password reset, sensitive notifications, or flows where mailbox access is required.", "Test password managers, browser autofill, paste, mobile keyboard, screen readers, zoom, long addresses, plus tags, multiple-address attempts, provider typos, bounced email, and confirmation timeout." ], "commonMisuses": [ "Using a plain text input without email autocomplete or email keyboard support.", "Blocking paste or browser autofill.", "Rejecting plus-addressed, long, subdomain, or uncommon-domain addresses with a narrow regex.", "Silently correcting a provider typo and sending mail to the changed address.", "Asking users to repeat the email address without evidence that it helps.", "Forcing an email confirmation loop for low-risk contact or receipt fields.", "Hiding the entered address so users cannot review it before a reset link or receipt is sent.", "Treating syntactic validity as proof that the mailbox exists or belongs to the user." ], "critiqueQuestions": [ "What will the service send to this email address and how should users choose which mailbox to provide?", "Does the field use type email, autocomplete email, spellcheck false, and enough visible width?", "Can users paste or autofill plus-tagged, long, or uncommon-domain addresses without rejection?", "What happens when a user enters a likely provider typo such as gmial.com?", "Does the flow need mailbox access confirmation, or is review and change enough?", "How are format validity, deliverability, bounced messages, and verified access represented separately?" ], "relatedPatterns": [ "text-input", "inline-validation", "error-summary", "autocomplete", "review-before-submit" ], "comparisons": [ "email-address-entry-vs-text-input-vs-inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-email-addresses-pattern", "ons-email-addresses-pattern", "mdn-input-email", "whatwg-input-email", "mdn-html-autocomplete-email" ] }, { "id": "empty-state", "completionStatus": "complete", "name": "Empty state", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Resolved no-data content surface", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users encounter a resolved content area where no objects are available and need to know whether that is expected, why it happened, and what action is possible now.", "solution": "Explain the legitimate absence in context, name the missing object or prerequisite, and provide one useful next step such as create, import, configure, request access, or view an example.", "uiGuidance": [ "Render a resolved no-data region with a specific heading, cause text, one primary action when available, optional secondary path, and restrained illustration or icon support.", "Keep surrounding context such as table title, filters, or workspace name visible so users know exactly what is empty." ], "uxGuidance": [ "Help users distinguish legitimate absence from loading, no-results, error, permission, and setup conditions before offering a next step.", "Move users toward the first useful object or prerequisite, and replace unavailable actions with permission or configuration guidance." ], "uiExamples": { "good": [ "No projects yet heading, short explanation, Create project primary button, Import CSV secondary button, and visible workspace context.", "Permission variant explains that projects exist only after an admin grants access and offers Request access instead of Create." ], "bad": [ "A blank white table body with no text, object name, or action.", "Oversized decorative art and vague welcome copy that hides the task." ] }, "uxExamples": { "good": [ "Users can create the first project, import existing work, or request access depending on the actual cause.", "After creating content, the empty state is replaced by the first row and focus moves to the new item." ], "bad": [ "The same empty message appears for loading, search no-results, permission denial, and service failure.", "A primary Create button is shown to a read-only user and fails after activation." ] }, "problemContext": [ "A list, dashboard, workspace, inbox, or collection can legitimately contain no objects.", "The user may be arriving for the first time, after cleanup, before configuration, or without permission to create content.", "The system has already resolved that this is not loading, search no-results, or an unexpected load failure." ], "selectionRules": [ "Choose empty state only after the system knows the area is legitimately empty rather than loading, filtered, or failed.", "Name the exact object, collection, or prerequisite that is absent.", "Offer one primary action only when the user can complete it in the current role or context.", "Use secondary actions for import, sample data, docs, or request access only when they clarify the next path instead of competing.", "Tailor copy to first-use, configured-empty, deleted-all, permission, or setup states instead of using one welcome message everywhere.", "Keep optional illustrations small and explanatory; they must not replace cause, consequence, or action text." ], "requiredStates": [ "First-use empty state before any objects exist.", "Configured but currently empty state after cleanup or deletion.", "Permission-limited state where creation is unavailable and request-access or explanation is shown.", "Prerequisite or setup-empty state where configuration must happen before data appears.", "Post-action state after creating or importing the first object.", "Loading-resolved transition so the empty state appears only after data status is known." ], "interactionContract": [ "The empty state identifies what is absent and why the absence is expected.", "Primary action moves users toward the first meaningful object or prerequisite.", "Unavailable actions are replaced with explanation or request-access paths instead of disabled mystery controls.", "The state disappears or changes once content exists.", "If the absence came from search or filters, the UI switches to no-results recovery rather than first-use empty copy.", "If content should exist but failed to load, the UI switches to an error state with retry or fallback." ], "implementationChecklist": [ "Gate empty-state rendering behind a resolved data status.", "Name the missing object type in the heading.", "Explain the most likely legitimate cause in one short sentence.", "Provide one primary next action when the user has permission.", "Use secondary actions only for clearly distinct paths such as import, sample data, docs, or request access.", "Track first-use, permission, setup, and cleanup variants separately.", "Do not hide table headers, filters, or context users need to understand what is empty." ], "commonMisuses": [ "Showing a blank page with no explanation.", "Using marketing copy instead of a task-specific next step.", "Telling users to create something they do not have permission to create.", "Showing empty state while content is still loading.", "Using first-use onboarding when filters produced zero matches.", "Replacing an error or offline condition with cheerful empty copy." ], "critiqueQuestions": [ "Can users tell what object is missing and whether the absence is expected?", "Is the primary action available to this user right now?", "Would the same surface become no-results, error, loading, or permission messaging under a different cause?" ], "relatedPatterns": [ "no-results-recovery", "error-state", "loading-skeleton" ], "comparisons": [ "empty-state-vs-no-results-recovery-vs-error-state" ], "sourceIds": [ "carbon-empty-states-pattern", "atlassian-empty-state", "sap-fiori-illustrated-message", "polaris-empty-state" ] }, { "id": "error-state", "completionStatus": "complete", "name": "Error state", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Recoverable failure surface", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users expected content, saving, sync, or progress, but the system failed and they need to understand what failed, what remains safe, and how to recover.", "solution": "Keep the failure visible near the affected content or task, explain it in user terms, preserve user context, and offer a recovery path such as retry, edit, fallback, cached data, or support escalation.", "uiGuidance": [ "Render a persistent error region near the affected content with a specific failure heading, plain-language cause, preserved context, and recovery actions.", "Pair visual emphasis with text and iconography, keep diagnostic detail secondary, and distinguish retrying, recovered, cached, and escalated states." ], "uxGuidance": [ "Help users recover when expected loading, saving, validation, sync, permission, or computation fails without losing their work.", "Match the next action to the failure cause: retry transient failures, edit correctable input, use cached fallback for read-only continuity, or provide support reference when recovery is outside the UI." ], "uiExamples": { "good": [ "Reports could not load appears in the report section with the saved filter, Retry, Use cached data, and Contact support actions.", "A failed save state keeps the draft visible and labels the support reference separately from the user-facing explanation." ], "bad": [ "Tiny transient toast for a blocking failure.", "Technical stack trace or vague Something went wrong message as the main UI." ] }, "uxExamples": { "good": [ "User input and filter context are preserved after failure, and retry returns to recovered content or a clear still-failed state.", "Support escalation includes a reference ID while keeping the user's draft intact." ], "bad": [ "Clearing work after save failure.", "Letting users keep interacting with stale content without warning." ] }, "problemContext": [ "Data may fail to load, save, validate, sync, authorize, or compute.", "Users need confidence that the system did not silently lose their work or show stale data as current.", "The product can identify enough of the failure cause to choose a specific recovery path." ], "selectionRules": [ "Choose error state when expected content or task progress is blocked by system, network, permission, validation, save, sync, or computation failure.", "Keep the affected object, form, query, or section context visible whenever it helps users recover.", "Offer recovery that matches the failure cause: retry for transient failures, edit for user-correctable data, cached view for read-only fallback, or support escalation for unrecoverable failures.", "Preserve user-entered data and current criteria unless the recovery action explicitly resets them.", "Use persistent inline or section-level presentation for blocking failures; reserve transient toasts for non-blocking status.", "Expose technical identifiers only as support details, not as the main explanation." ], "requiredStates": [ "Normal expected state before failure.", "Pending or retrying state after recovery action starts.", "Failed state with affected content, cause, and recovery action.", "Recovered state after retry or fallback succeeds.", "Escalated state with support reference or next contact path.", "Preserved-draft or preserved-query state after save/load failure." ], "interactionContract": [ "The error remains visible until resolved, intentionally dismissed, replaced by recovered content, or escalated.", "Recovery controls communicate what they will attempt before activation.", "User-entered data, filters, scroll context, and unsaved work are preserved where possible.", "Retry shows an in-progress state and then either recovered content or a still-failed message.", "Support escalation includes enough reference detail to help without dumping stack traces into the primary UI.", "Users are not allowed to trust stale or partial content unless it is clearly labeled as cached or partial." ], "implementationChecklist": [ "Describe the failed action, object, or content area in the heading.", "Write the cause and next step in user terms before exposing technical detail.", "Provide retry, edit, cached data, offline, or support action according to the failure cause.", "Preserve user input, query, filters, and drafts after failed save or load.", "Render blocking failures persistently near the affected content or in a page-level error region.", "Use alert or status semantics for newly appearing critical errors.", "Keep diagnostic IDs collapsible or secondary for support use." ], "commonMisuses": [ "Using a transient toast for critical errors.", "Showing generic copy such as Something went wrong without recovery.", "Clearing user input after a failed save.", "Replacing failed expected content with an empty state.", "Letting users keep interacting with stale content without warning.", "Showing raw stack traces or service names as the main message." ], "critiqueQuestions": [ "Can the user tell exactly what failed and what remains safe?", "Does the recovery action match the failure cause instead of offering a generic retry for everything?", "Will user work, filters, or draft content survive the failure and recovery attempt?" ], "relatedPatterns": [ "empty-state", "no-results-recovery", "toast-only-critical-error", "loading-skeleton" ], "comparisons": [ "empty-state-vs-no-results-recovery-vs-error-state" ], "sourceIds": [ "atlassian-error-messages", "carbon-notification-component", "va-error-messages", "govuk-error-message-component" ] }, { "id": "error-summary", "completionStatus": "complete", "name": "Error summary", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Form recovery summary", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users submit a page or step with validation errors and need an immediate overview plus a route to each answer that must be fixed.", "solution": "Show a focused summary near the form heading with a clear title and linked error messages, then repeat matching messages at the affected fields.", "uiGuidance": [ "Render a top-of-form summary block with heading, linked error list, and matching field-level error messages.", "Place the summary near the form heading after failed submit, not as an unrelated toast or detached banner." ], "uxGuidance": [ "Help users recover from one or more submitted-form errors without scanning the entire page.", "Move users from the summary to the exact field, group, or first invalid control that needs correction." ], "uiExamples": { "good": [ "Top-of-form summary with a clear heading, linked error list, and matching inline field messages.", "Each error link text names the correction and visually matches the message at the affected field." ], "bad": [ "Red banner saying fix errors with no links.", "Summary and field messages visually disconnected or contradictory." ] }, "uxExamples": { "good": [ "After failed submit, focus or reading order makes the summary discoverable before users scan the form.", "Choosing a summary item moves to the relevant field while preserving the submitted values." ], "bad": [ "Only showing errors below the fold.", "Replacing field-level guidance with only a top summary." ] }, "problemContext": [ "The form can fail after submit, cross-field validation, or server validation.", "Errors may be below the fold, spread across sections, or easy to miss when focus remains on the submit control." ], "selectionRules": [ "Choose an error summary when submit-time validation can leave one or more errors across a page or step.", "Link each summary item to the exact field, first invalid field in a group, or section that contains the failing answer.", "Keep summary wording consistent with field-level messages so the user does not have to reconcile two explanations." ], "requiredStates": [ "Neutral form before submit with no summary.", "Failed-submit state with summary visible near the form heading.", "Summary-link navigation to the affected field or first invalid grouped input.", "Corrected form state with the summary removed or replaced by a success outcome." ], "interactionContract": [ "The summary appears after failed submit where keyboard and screen-reader users can perceive it.", "Each summary item names one error and moves focus or scroll position to the relevant answer.", "Field messages and summary messages use the same correction wording." ], "implementationChecklist": [ "Place the summary near the form heading before the fields that contain errors.", "Move focus to the summary after failed submit unless the platform has an equivalent announcement pattern.", "Link each summary message to the field, group, or first invalid subfield it describes.", "Keep entered values intact so users can edit rather than start again.", "Repeat matching field-level error messages at the affected controls." ], "commonMisuses": [ "Showing a red banner or toast with no links to the invalid answers.", "Replacing field-level messages with only a top-level summary.", "Using vague summary messages that do not identify the answer or correction." ], "critiqueQuestions": [ "Can users recover from the first failed submit without scanning the full page?", "Do summary links land on the same fields whose messages repeat the correction?" ], "relatedPatterns": [ "inline-validation" ], "comparisons": [ "inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-error-summary-component", "govuk-error-message-component" ] }, { "id": "escalate-to-human", "completionStatus": "complete", "name": "Escalate to human", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Control and recovery path that transfers an AI, automation, or self-service case to a human channel or queue", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI and automation can fail, reach policy limits, or encounter situations that need human judgment, but products often hide the path to a person, over-deflect users back to AI, or transfer without explaining destination, wait, context sharing, status, and fallback.", "solution": "Provide an explicit escalation path that detects or accepts human-help requests, explains why human support is appropriate, lets users choose an eligible route, transfers the necessary context with consent and privacy controls, shows queue and acceptance status, and preserves cancellation, fallback, and return paths.", "uiGuidance": [ "Render escalate to human as an explicit route out of AI or automation, with trigger reason, eligibility, destination, expected wait, context shared, privacy boundary, and what happens to the current conversation, task, or run.", "Show the human route choices the product can actually honor, such as live agent, callback, ticket, specialist queue, supervisor review, emergency route, or business-hours fallback, and keep unavailable routes disabled with explanations." ], "uxGuidance": [ "Use escalate to human when the user needs human judgment, empathy, authority, accountability, exception handling, or support beyond what the AI or automation can safely complete.", "Make escalation reversible and understandable: preserve user context, disclose what is transferred, show wait and queue status, support cancel or change route, and avoid trapping users in loops that keep deflecting to AI." ], "uiExamples": { "good": [ "An AI support chat shows Talk to a human after failed self-service, explains that transcript and account context will be shared, offers Live agent or Create ticket, and shows estimated wait.", "A claims assistant blocks automated resolution, routes the user to a specialist queue, shows business hours, transfer status, and lets the user cancel before the handoff starts." ], "bad": [ "A Help button restarts the bot with no human route even after repeated failure.", "The UI says Transfer started but hides destination, queue status, wait time, shared context, and whether a human has actually accepted." ] }, "uxExamples": { "good": [ "A user reports that the AI cannot resolve a locked billing account; the product offers a billing specialist queue, shows two-minute wait, shares the transcript with consent, and updates when a human joins.", "A user requests human review outside business hours; the product creates a ticket, confirms SLA, preserves attachments, and explains how to return to the conversation." ], "bad": [ "A user types human repeatedly, but the assistant keeps asking clarifying questions and never reveals that live support is closed.", "A user is transferred to a person who receives no transcript, so the user has to repeat sensitive details." ] }, "problemContext": [ "Users may need human help because the AI failed repeatedly, confidence is low, sources are missing, policy blocks automation, the user is distressed, a safety issue is present, account access is restricted, or an exception needs authority.", "Escalation destinations may include live chat, phone callback, support ticket, specialist queue, supervisor review, incident route, care team, or human review of an AI decision.", "Human channels may have business hours, capacity limits, SLAs, language support, eligibility rules, authentication requirements, and permission boundaries.", "Escalation can share sensitive context, transcript history, uploaded files, account data, tool results, AI decisions, and user-provided corrections with a human receiver.", "The product may need to preserve the current conversation while creating a ticket, switching first responder, handing back to AI, or resuming automation after human intervention." ], "selectionRules": [ "Choose escalate to human when users need a route from AI, automation, chatbot, self-service, or failed recovery to a human channel or queue.", "Use handoff summary when the human receiver needs a structured transfer packet; escalate to human owns the user-facing route, eligibility, wait, transfer, and fallback path.", "Use chat interface when designing the whole AI conversation; escalate to human is one high-impact path inside or beside that conversation.", "Use review queue when human staff triage many escalated items; escalate to human is the user's request or system transition into that queue.", "Use human approval gate when automation is paused for an eligible reviewer to authorize a specific armed action; escalate to human when the user or system needs human help or takeover.", "Use recommended next action when human escalation is an optional suggestion among other actions; use escalate to human when human help is the primary recovery route.", "Offer escalation after repeated failed AI answers, user request for a person, low-confidence or blocked state, sensitive or regulated topic, unavailable automation, unsafe recommendation, or policy-required human review.", "Show destination, expected wait, business hours, route eligibility, shared context, privacy controls, cancellation, and fallback before transfer when those values affect user trust.", "Do not hide human routes behind infinite bot loops, irrelevant suggestions, disabled buttons with no explanation, or fake transfer states.", "Do not start a human transfer that cannot be staffed, routed, or tracked honestly." ], "requiredStates": [ "Available human route state with reason, destination, estimated wait, and shared context summary.", "User-requested human state after phrases such as talk to a person, agent, representative, supervisor, or human help.", "System-suggested escalation state after repeated failure, low confidence, policy block, high risk, user distress, or unavailable automation.", "Route choice state for live agent, ticket, callback, specialist queue, supervisor review, emergency route, or business-hours fallback.", "Authentication, account verification, permission, language, region, and eligibility states before routing.", "Consent and privacy state showing transcript, files, account data, AI outputs, tool results, and sensitive notes that will be shared.", "Transfer pending, queue position, estimated wait, human joined, ticket created, callback scheduled, and escalation accepted states.", "No agent available, outside business hours, capacity full, failed transfer, timeout, cancelled, handback to AI, and return-to-self-service states.", "Escalation history, reference ID, SLA, notification, and follow-up states.", "Mobile compact escalation state with route choice, wait, shared context, and cancel visible." ], "interactionContract": [ "The escalation action names the human destination and whether it is live, asynchronous, specialist, supervisor, emergency, or review-only.", "The UI states why human help is available or required, and distinguishes user-requested escalation from system-required escalation.", "Users can inspect and, when policy allows, limit what context is shared with the human route before transfer.", "Starting escalation preserves the current conversation, task, attachments, account context, and failed AI attempts unless the UI explicitly says otherwise.", "Transfer status moves through clear states: requested, verifying, queued, assigned, human joined or ticket created, failed, cancelled, or handed back.", "Unavailable routes explain whether the reason is business hours, capacity, eligibility, authentication, language, region, plan, or permission.", "Cancel, change route, continue with AI, create ticket, request callback, or leave safely remain available according to the route state.", "The human receiver gets enough context through a handoff summary, transcript, variables, and source links without exposing redacted details." ], "implementationChecklist": [ "Model escalation reason, trigger source, user request, route type, destination queue, eligibility, verification, business hours, capacity, SLA, expected wait, transfer status, consent, shared context, reference ID, and fallback separately.", "Detect explicit human-help requests and repeated unresolved AI failures without relying only on exact phrase matching.", "Define route policies for live agent, ticket, callback, specialist queue, supervisor review, emergency route, and handback to AI.", "Show the context package that will transfer: transcript, account fields, attachments, AI outputs, tool results, summary, variables, and redacted or withheld fields.", "Prevent fake transfer by requiring a routable destination, staff availability or asynchronous fallback, and a status that can be updated.", "Synchronize escalation with chat transcript, handoff summary, review queue, notification center, assignment, activity log, and support ticket state.", "Log escalation request, consent, route, queue events, human acceptance, cancellation, failed transfer, handback, and final outcome where support accountability matters.", "Test user phrases for human help, repeated bot failure, low-confidence escalation, no-agent availability, outside business hours, authentication required, privacy review, queue updates, mobile layout, keyboard operation, and screen-reader status announcements." ], "commonMisuses": [ "Hiding the human route after the AI fails repeatedly.", "Using Talk to human as a button that only restarts the bot.", "Showing a transfer spinner without destination, queue, wait, or acceptance status.", "Sharing transcript, account data, or sensitive notes with a human route without disclosure or consent where required.", "Transferring users to a person without giving the receiver context.", "Offering unavailable live chat as if it were available.", "Making cancellation, ticket fallback, or return-to-self-service impossible during a long wait.", "Treating human approval gates or review queues as user-facing escalation without showing route status." ], "critiqueQuestions": [ "What exact condition makes human help available, suggested, or required?", "Can users see destination, route type, eligibility, wait, business hours, and fallback before transfer?", "What transcript, data, files, AI outputs, and tool results are shared with the human receiver?", "What happens if no human is available, the user cancels, the transfer fails, or the case is handed back to AI?", "How does the receiver get context without requiring the user to repeat themselves?", "Would handoff summary, review queue, human approval gate, chat interface, notification center, or recommended next action better own this surface?" ], "relatedPatterns": [ "handoff-summary", "chat-interface", "review-queue", "human-approval-gate", "recommended-next-action", "notification-center", "assignment", "activity-log" ], "comparisons": [ "escalate-to-human-vs-handoff-summary-vs-chat-interface-vs-review-queue-vs-human-approval-gate-vs-recommended-next-action" ], "sourceIds": [ "microsoft-copilot-studio-live-agent-handoff", "zendesk-conversation-handoff-handback", "ada-zendesk-chat-handoff-transcript-summaries", "microsoft-human-ai-guidelines", "wcag-status-messages" ] }, { "id": "exit-this-page-quickly", "completionStatus": "complete", "name": "Exit this page quickly", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Persistent safety escape control for sensitive pages where being seen on the current content could put the user at risk", "maturity": "domain-specific", "platforms": [ "web", "mobile" ], "problem": "Sensitive services can endanger users when another person can see the page, when the exit path is hidden, slow, misleading, inaccessible, or routed through sensitive history, or when the product overstates what quick exit can protect.", "solution": "Provide a persistent quick-exit control, alternate accessible activation, immediate content-covering transition, neutral destination, pre-use explanation, safety-content follow-up, tested keyboard/focus behavior, and honest limitations about history, monitoring, malware, and traces outside the page.", "uiGuidance": [ "Place a persistent, visibly distinct Exit this page control where it is reachable before and during sensitive content, and pair it with a secondary activation link for assistive technology users.", "When activated, immediately cover or replace sensitive content with a neutral loading state and navigate to a neutral destination without waiting for analytics, confirmation, animation, or form submission." ], "uxGuidance": [ "Use the pattern when sensitive content could put someone at risk if another person sees the page, such as abuse support, stalking, harassment, sexual assault, child safety, whistleblowing, or plans to escape harm.", "Explain the control before first exposure in a transactional journey, including what it does, where it goes, what it does not protect, and how users can manage browser history or monitored-device risk." ], "uiExamples": { "good": [ "A support-service page keeps a red Exit this page button pinned near the top right, includes a hidden-but-focusable secondary link, and replaces the page with a neutral loading overlay as soon as it is activated.", "An interruption page before a sensitive service previews the exact exit button, names the neutral destination, and explains that the button does not clear browser history or stop device monitoring." ], "bad": [ "A tiny Close link appears only in the footer and sends users back through sensitive previous pages.", "A quick exit button shows a confirmation modal and waits for analytics before changing the page." ] }, "uxExamples": { "good": [ "A user hears someone enter the room, presses the visible exit button, sees sensitive content covered instantly, and lands on a neutral search page while the service avoids sending analytics first.", "A screen-reader user tabs to a secondary Exit this page link, activates it, and receives the same immediate content-covering behavior as pointer users." ], "bad": [ "A user believes the exit button cleared browser history because the service overpromised safety, then the visit is later discovered through history or device monitoring.", "A keyboard user cannot reach the exit control because it is visually fixed but placed after a long page of sensitive content in focus order." ] }, "problemContext": [ "Quick exit is most relevant for pages about domestic abuse, stalking, harassment, sexual assault, child abuse, reporting crime or fraud, whistleblowing, immigration risk, debt coercion, health disclosure, or escape planning.", "The pattern protects mainly against immediate over-the-shoulder or room-entry exposure; it cannot by itself erase browser history, network records, device monitoring, spyware, screenshots, downloaded files, or account logs.", "The exit destination must be neutral enough for the local context and should not reveal the sensitive service through title text, referrer behavior, page copy, or obvious related branding.", "The control may appear inside a larger service journey, but the user should learn what it does before the first sensitive page where they may need it." ], "selectionRules": [ "Choose exit this page quickly when being seen on the current page could cause abuse, retaliation, coercion, stalking, harassment, or discovery of plans to avoid harm.", "Use the standalone component on sensitive content pages where the page itself is the risk and the user needs immediate escape.", "Use a full exit-a-page-quickly pattern with an interruption page and safety content when the user enters a sensitive transactional journey.", "Use security warning when the product is warning about unsafe sites, downloads, phishing, malware, mixed content, or certificate risk.", "Use sensitive-data reveal when the user intentionally exposes a secret value for short-term inspection.", "Use session timeout when inactivity or unattended authenticated access is the core risk.", "Use privacy settings for planned control of sharing, tracking, visibility, retention, and data-use preferences.", "Use back link only for ordinary navigation, not as a safety exit from sensitive material." ], "requiredStates": [ "Persistent visible exit control on sensitive pages.", "Secondary assistive-technology activation link or equivalent reachable control.", "Immediate content-covering loading or transition state.", "Neutral destination redirect state.", "Interruption page explaining what the control does before first sensitive exposure.", "Safety content page explaining limitations and safer browsing steps.", "Keyboard focus and screen-reader label state.", "No-JavaScript or slow-network fallback state.", "Mobile compact persistent control state.", "Exit activated, destination failed, blocked popup, and analytics bypass states." ], "interactionContract": [ "The quick exit control is reachable before the user reaches sensitive content in both visual order and keyboard order.", "Activating the control immediately hides sensitive page content and starts navigation to a neutral destination.", "The exit path does not require confirmation, login, form submission, animation completion, or analytics completion.", "A secondary link or equivalent control provides the same behavior for assistive technology users.", "The interruption page explains the control, its destination, and its limitations before users encounter it in a sensitive transactional journey.", "The safety content explains that quick exit does not clear browser history, stop device monitoring, remove downloaded files, or protect against malicious software.", "The fallback state still gives users a neutral route if scripts fail, navigation is blocked, or the destination cannot load.", "The control avoids using ordinary back navigation as the escape route because history may contain more sensitive pages." ], "implementationChecklist": [ "Identify the sensitive pages, threat model, likely observer scenario, neutral destination, referrer policy, and surfaces where quick exit must be persistent.", "Place the visible control consistently on every sensitive page and ensure it is reachable early in DOM and keyboard order.", "Provide an assistive-technology activation route with the same immediate behavior.", "Implement activation to cover sensitive content immediately before redirecting and bypass nonessential analytics or delayed transitions.", "Create an interruption page before first sensitive exposure and safety content that explains limitations, browser history, monitoring, and safer-device guidance.", "Test mobile compact layout, zoom, keyboard order, screen-reader labels, slow network, failed destination, no-JavaScript fallback, history behavior, and referrer leakage.", "Choose a neutral destination that does not reveal the sensitive service and verify tab title, loading state, and browser history labels.", "Document why the pattern is used, what it does not solve, and what adjacent safety controls handle outside the page." ], "commonMisuses": [ "Using an ordinary Back link or footer Close link as the safety exit.", "Hiding the exit control below sensitive content or making it reachable only after scrolling.", "Showing a confirmation dialog, survey, animation, or analytics wait before hiding content.", "Overpromising that quick exit clears browser history or protects a monitored device.", "Opening a related site, branded page, blank page, or suspicious destination that reveals the sensitive context.", "Forgetting keyboard, screen-reader, no-JavaScript, slow-network, or mobile compact behavior.", "Putting the safety explanation after the user has already entered the sensitive service." ], "critiqueQuestions": [ "What immediate observer risk does this page create, and where does quick exit reduce that risk?", "Can pointer, keyboard, touch, and screen-reader users activate the exit before reaching sensitive content?", "What exactly appears between activation and destination load, and does it hide sensitive content instantly?", "Which neutral destination is used, and could it reveal the sensitive service through title, URL, referrer, or history?", "What does the service tell users about browser history, monitoring, spyware, downloads, and limits of the control?", "What happens if JavaScript fails, navigation stalls, a popup is blocked, or the user is on a compact mobile viewport?", "Is the quick exit pattern paired with other safety content rather than treated as a complete safety solution?" ], "relatedPatterns": [ "security-warning", "sensitive-data-reveal", "session-timeout", "privacy-settings", "back-link", "warning-text", "site-alert", "permission-request", "consent-prompt", "delete-account" ], "comparisons": [ "exit-this-page-quickly-vs-security-warning-vs-sensitive-data-reveal-vs-session-timeout-vs-privacy-settings-vs-back-link" ], "sourceIds": [ "govuk-exit-this-page-component", "govuk-exit-a-page-quickly-pattern", "govuk-design-notes-exit-this-page-fast", "techsafety-exit-from-this-website-quickly", "cambridge-click-here-to-exit" ] }, { "id": "exit-warning", "completionStatus": "complete", "name": "Exit warning", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Attempted-departure safeguard for unrecoverable in-progress work", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users can accidentally leave a page, close a tab, reload, follow a link, sign out, or move to another route while work is dirty, pending, failed, or session-bound, causing data or context loss that cannot be recovered.", "solution": "Track departure-risk state precisely, attach browser leave protection only while needed, intercept in-app navigation with a clear decision surface, identify what is at risk, offer save, discard, and stay choices where possible, and clear the warning immediately after work is safe.", "uiGuidance": [ "Show a warning only when the user attempts to leave with real unsaved, pending, failed, or unrecoverable work; place in-app route warnings at the point of departure with Save and leave, Discard and leave, and Stay editing choices.", "For browser close, reload, or cross-origin navigation, rely on the browser-owned beforeunload dialog and keep an in-page status that already explains what is unsaved because custom dialog text may not be shown." ], "uxGuidance": [ "Use exit warning to interrupt an attempted departure that would lose work, context, payment state, upload progress, or session-bound data the product cannot safely recover.", "Treat exit warning as a last-resort safeguard, not the primary save model: save or draft work when possible, remove the warning as soon as work is safe, and avoid blocking clean navigation." ], "uiExamples": { "good": [ "A grant form user clicks Back with two unsaved answers; a dialog names the changed section and offers Save and leave, Discard and leave, or Stay editing.", "A browser reload attempt on a dirty form triggers the browser's leave-page dialog only while the dirty state exists, with the page already showing Last change not saved." ], "bad": [ "Every navigation shows Are you sure you want to leave? even after the form is saved.", "A vague warning says Changes may be lost but gives only OK and Cancel, with no save, discard, or stay wording." ] }, "uxExamples": { "good": [ "A user starts to close a tab after a failed autosave, sees the risk before leaving, stays on the page, retries the save, and then leaves without another warning.", "A user chooses Discard and leave from an in-app warning and is taken to the intended destination with a clear understanding of what was discarded." ], "bad": [ "A user clicks a sidebar link after typing a long answer and loses it because the product only watched final Submit.", "A user saves a draft but still sees a leave warning on every route change because the dirty flag was never cleared." ] }, "problemContext": [ "The task includes typed answers, selected records, uploads, payment setup, edited content, in-progress review, temporary calculations, or session-bound state.", "The product cannot guarantee recovery through autosave, draft state, server session, local storage, or transaction replay.", "Users may leave through Back, close tab, reload, external link, sidebar navigation, breadcrumb, sign out, idle timeout, or route change.", "Browser-owned unload dialogs have limited custom copy and unreliable mobile behavior, so the product still needs local dirty-state messaging and recovery." ], "selectionRules": [ "Choose exit warning when departure has already been attempted and leaving would lose work or context that is not safely recoverable.", "Do not show exit warnings for clean state, read-only browsing, already-saved drafts, completed submissions, or changes that autosave can reliably restore.", "Use autosave form to reduce the need for warnings by saving progress automatically and warning only while saves are pending or failed.", "Use draft state when the work survives navigation as a durable object with Resume, Discard, Publish, or Compare choices.", "Use confirmation dialog when the trigger is an explicit action such as Cancel application, Delete file, or Discard draft rather than a navigation attempt.", "For in-app navigation, show a custom warning that names the affected section, last saved state, and intended destination.", "For tab close, reload, or browser Back outside app control, attach beforeunload only while dirty state exists and remove it after save or discard.", "Offer Stay editing as the safest default when data loss is likely; offer Discard and leave only with clear loss scope.", "Offer Save and leave only when save can complete safely before navigation or when users understand that leaving waits for save completion.", "If mobile or browser behavior cannot guarantee a warning, preserve local draft state or show earlier in-page risk messaging instead of relying solely on beforeunload." ], "requiredStates": [ "Clean state with no exit warning attached.", "Dirty unsaved state with local unsaved-work status.", "Pending autosave or upload state.", "Failed save state with retry before leaving.", "In-app route change attempted state with destination named.", "Browser close, reload, or external navigation protected state.", "Save and leave in progress state.", "Discard and leave confirmation state.", "Stay editing state that restores focus and preserves values.", "Saved or submitted state that clears the warning." ], "interactionContract": [ "The warning appears only after a departure attempt or immediately before a known session boundary that could cause loss.", "The warning identifies the scope of loss, such as Contact details, uploaded evidence, payment setup, or unsaved section answers.", "Stay editing keeps the user on the current surface with values intact and returns focus to the triggering or first dirty control.", "Discard and leave clears only the stated unsaved work and then completes the intended navigation.", "Save and leave either completes the save before navigation or explains that saving failed and keeps the user on the page.", "The browser beforeunload listener is attached only while dirty state exists and removed after save, submit, discard, or reset.", "A warning never traps users after they explicitly discard or after the work is safely recoverable." ], "implementationChecklist": [ "Define dirty state from actual data changes, pending uploads, failed saves, in-flight payment setup, or unrecoverable session context rather than from page visit alone.", "Track the intended destination for in-app navigation so the warning can continue there after save or discard.", "Keep browser beforeunload protection conditional and remove it as soon as risk clears.", "Use route guards for internal links, Back controls, breadcrumbs, side navigation, sign out, and cancel routes that could lose current work.", "Model Save and leave, Discard and leave, Stay editing, Retry save, and Continue to destination as separate actions.", "Handle pending or failed autosave differently from simple dirty state; do not allow a stale Saved label to suppress the warning.", "Restore focus after Stay editing and announce the preserved state for assistive technology users.", "Test browser reload, tab close, mobile app switch, internal route change, external link, sign out, session expiry, failed save, successful save, discard, Back button, keyboard activation, and screen readers." ], "commonMisuses": [ "Warning on every navigation regardless of whether work is dirty.", "Using exit warnings for retention, growth, ads, or survey prompts instead of preventing user-facing loss.", "Leaving beforeunload listeners attached after save, harming navigation and browser-cache behavior.", "Showing a vague Are you sure? message without naming the affected work or consequence.", "Providing only Leave and Cancel when Save and leave or Stay editing is technically possible.", "Trapping users after they choose to discard or after work is saved.", "Relying only on browser beforeunload even though mobile browsers may not show it reliably." ], "critiqueQuestions": [ "What exact work or context would be lost if the user leaves now?", "Is the loss unrecoverable, or can autosave or draft state make the warning unnecessary?", "Which exit paths are covered: internal links, Back, reload, close tab, external links, sign out, and session expiry?", "Does the warning say what will be lost and where the user was trying to go?", "Can users save before leaving, discard intentionally, and stay editing without losing focus or values?", "Is the browser leave listener removed immediately after save, submit, or discard?" ], "relatedPatterns": [ "autosave-form", "draft-state", "confirmation-dialog", "alert", "inline-edit", "multi-step-form" ], "comparisons": [ "exit-warning-vs-autosave-form-vs-draft-state-vs-confirmation-dialog" ], "sourceIds": [ "mdn-beforeunload-event", "webdev-bfcache", "w3c-wcag-timeouts", "w3c-wcag-reauthenticating" ] }, { "id": "expandable-row", "completionStatus": "complete", "name": "Expandable row", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Row-owned inline detail disclosure inside a table or list", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Dense tables and lists often need row-specific explanation, history, or secondary attributes, but adding every detail as a column makes scanning harder while sending users to separate pages breaks row context for quick triage.", "solution": "Add a row-owned disclosure control that reveals compact detail immediately after the owning row, preserves the table or list context, exposes state and row identity accessibly, and escalates to a panel or full page when the detail is too large or task-heavy.", "uiGuidance": [ "Render an expandable row as a normal data row with a labelled expand control, visible expanded or collapsed state, stable row identity, and an adjacent detail region that visually and programmatically belongs to that row.", "Keep the expanded area compact and row-specific: show detail summaries, exception reasons, recent activity, nested attributes, attachments, or safe secondary actions without breaking table headers, row labels, sort state, or row action alignment." ], "uxGuidance": [ "Use expandable row when users mostly need the compact row list but occasionally need row-local detail to explain, verify, triage, or act on one record in context.", "Preserve expanded state by record ID across sorting, filtering, pagination, refresh, and narrow layouts, and summarize hidden critical states in the collapsed row so users do not have to open every row." ], "uiExamples": { "good": [ "An invoice table shows an expand button labelled Show details for INV-2048; the expanded row reveals line items, exception reason, approval history, and a View invoice link below the owning row.", "An activity log row expands to show the changed fields, actor note, request ID, and Copy audit ID action while the timestamp and event type remain visible in the row." ], "bad": [ "Every table row has a chevron, but some rows open nothing and others reveal unrelated page help.", "Expanded detail appears at the bottom of the table with no row title, so users cannot tell which record it belongs to after scrolling." ] }, "uxExamples": { "good": [ "A reviewer expands a flagged invoice, reads the mismatch reason, copies the audit ID, sorts by amount, and the same invoice remains expanded because state is keyed by invoice ID.", "A keyboard user tabs to Show details for INV-2048, presses Space, hears that the row is expanded, reviews the detail links, collapses the row, and focus returns to the row control." ], "bad": [ "Filtering a queue keeps the third visual row open after the data changes, exposing details for a different customer.", "A user misses a failed payment reason because the collapsed row only says Failed and hides the reason without a summary or visible warning." ] }, "problemContext": [ "Rows represent records such as invoices, orders, payments, events, files, alerts, support tickets, devices, permissions, or audit entries.", "Most users scan the collapsed rows first and open detail only for exceptions, verification, recent history, line items, or secondary actions.", "The detail belongs to one row and should stay near that row rather than becoming a page-level section or global panel.", "The data surface may be sorted, filtered, paginated, virtualized, refreshed, selected, or used on narrow screens.", "Some rows may have no additional detail, stale detail, permission-limited detail, or detail that loads after expansion." ], "selectionRules": [ "Choose expandable row when the main surface is a table or list and the extra content is owned by one row.", "Use a standard table when the content should be visible for many rows at once and compared down a column.", "Use details panel when users repeatedly inspect many records and benefit from a persistent inspector beside the table or list.", "Use accordion when the content is page-level sections rather than row-owned detail.", "Use disclosure details when there is one small optional explanation near text or a form field, not repeated row detail.", "Use tree grid when expansion represents a real hierarchy of parent and child rows with row-and-column semantics.", "Use drawer, sheet, or full page when the expanded content needs long reading, primary editing, comments, history, attachments, or destructive review.", "Do not use expandable rows to hide values users must compare across all rows, such as amount, due date, owner, or status.", "Do not show expand controls for rows with no detail unless the unavailable state and reason are clear.", "Avoid expandable rows when sorting, filtering, or virtualization cannot keep expansion state attached to the correct record ID." ], "requiredStates": [ "Collapsed row with row identity, key values, and a labelled expand control.", "Expanded row with detail region immediately after the owning row and a labelled collapse control.", "Focused expand control, keyboard activated expansion, and focus return after collapse.", "Row with no additional detail or permission-limited detail.", "Loading, loaded, stale, failed-load, and retry states for detail fetched after expansion.", "Expanded row after sort, filter, pagination, refresh, or selection change.", "Collapsed row with hidden error, warning, count, or changed-detail summary.", "Narrow-screen state that preserves row identity and header-to-cell meaning." ], "interactionContract": [ "The expand control names the affected row, exposes expanded state, and controls only that row's detail region.", "Expanded content appears directly after the owning row in visual and reading order, with a heading or label that repeats the row identity.", "The collapsed row summarizes any hidden critical status, validation issue, unread activity, count, or stale detail that users need before opening.", "Sorting, filtering, pagination, refresh, and virtual loading preserve expansion by stable record ID or intentionally collapse with a visible status message.", "Rows without detail do not expose misleading active expand controls.", "Expanded content does not disrupt column alignment, sortable headers, row selection, row actions, or bulk-selection behavior.", "Secondary actions inside the expanded detail clearly apply to the owning row and preserve focus or return to the row control after completion." ], "implementationChecklist": [ "Define which row fields remain visible, which detail fields can be hidden, and which hidden statuses require collapsed-row summaries.", "Key expansion state by stable record ID rather than visual index.", "Use a button or native disclosure control for each expandable row and include the row name or identifier in its accessible name.", "Connect the control to the row detail region with expanded state and a stable region label.", "Place expanded content immediately after the owning row or inside a semantic structure that preserves row ownership.", "Handle no-detail, loading, failed detail, stale detail, permission-limited detail, and deleted-row states.", "Decide whether multiple rows can be open, whether opening a new row closes others, and how that affects selection and focus.", "Test sort, filter, pagination, refresh, virtualization, row selection, bulk actions, keyboard, screen reader table navigation, zoom, and mobile stacking." ], "commonMisuses": [ "Hiding primary columns or required decision data inside collapsed detail.", "Tracking expansion by row index so a different record appears expanded after sorting or filtering.", "Using a chevron-only button with no row identity or expanded state.", "Showing expand controls on rows with no additional content.", "Putting long forms, nested data grids, destructive confirmations, or unrelated navigation inside the expanded area.", "Moving expanded detail away from the owning row.", "Breaking table header associations or row action labels when the detail row is inserted.", "Collapsing an expanded row after refresh without explanation while the user is reviewing it." ], "critiqueQuestions": [ "What exact record owns the expanded content?", "Which hidden details are optional, and which need a collapsed-row warning, count, or summary?", "Can users sort, filter, paginate, refresh, and select rows without expansion moving to the wrong record?", "Would the hidden content work better as a visible column, details panel, drawer, full page, accordion, or tree grid?", "How do rows with no detail, failed detail load, stale detail, or permission-limited detail behave?", "Can keyboard and screen-reader users identify, open, review, act on, and collapse the row detail predictably?" ], "relatedPatterns": [ "table", "data-grid", "tree-grid", "details-panel", "accordion", "disclosure-details", "activity-log", "preview-panel" ], "comparisons": [ "expandable-row-vs-table-vs-details-panel-vs-accordion" ], "sourceIds": [ "carbon-data-table-component", "mui-table-collapsible-table", "wai-aria-apg-disclosure", "wai-tables-tutorial", "mdn-html-table-element" ] }, { "id": "faceted-search", "completionStatus": "complete", "name": "Faceted search", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Filter and results exploration surface", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to narrow a large result set using multiple meaningful attributes.", "solution": "Expose filter dimensions near the result set, let users combine constraints, and make applied filters visible and removable.", "uiGuidance": [ "Render filter controls, active chips, counts, result list, clear controls, and no-results state.", "Keep selected facets visible while results update." ], "uxGuidance": [ "Help users progressively narrow a large result set without losing orientation.", "Support recovery when filter combinations become too restrictive." ], "uiExamples": { "good": [ "Facet groups, counts, selected chips, result count, and clear controls are visually grouped.", "Filters use consistent spacing and avoid heavy borders around every option." ], "bad": [ "Facet panel overwhelms the results with dense unchecked options.", "Selected filters are hidden inside collapsed menus." ] }, "uxExamples": { "good": [ "Users can add, remove, combine, and clear facets while understanding result count changes.", "No-results recovery identifies which filters caused the dead end." ], "bad": [ "Changing filters resets unrelated query or sort silently.", "No way to undo one facet without clearing everything." ] }, "problemContext": [ "A result set is too large to scan directly.", "Items have structured attributes that users understand and can combine." ], "selectionRules": [ "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." ], "requiredStates": [ "Unfiltered state with result count and available facets.", "Filtered state with applied constraints visible.", "Zero-result state with clear recovery actions.", "Facet loading or disabled state when counts are recalculating." ], "interactionContract": [ "Applying or removing a facet updates the result count and preserves visible applied filters.", "Users can remove individual filters and clear all filters.", "Facet labels should be user-facing concepts, not internal system names." ], "implementationChecklist": [ "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." ], "commonMisuses": [ "Using internal database labels as facets.", "Hiding applied filters in a collapsed drawer.", "Letting filters produce zero results without a path to broaden." ], "critiqueQuestions": [ "Can the user see exactly why the current results are being shown or excluded?" ], "relatedPatterns": [ "no-results-recovery" ], "comparisons": [ "faceted-search-vs-no-results-recovery" ], "sourceIds": [ "govuk-publishing-search-filter", "moj-design-system-filter", "carbon-filtering-pattern", "govuk-design-system-patterns" ] }, { "id": "fake-undo", "completionStatus": "complete", "name": "Fake undo", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Anti-pattern where a recovery affordance promises undo but cannot restore the prior state", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Undo creates strong user trust, but products sometimes expose an undo label before they can actually reverse the action. The result is worse than no recovery because users believe a harmful change was undone when data, permissions, order, messages, or external effects remain changed.", "solution": "Only show Undo when exact prior-state recovery is implemented for the committed action; otherwise use a more honest recovery label, durable trash restore, destructive confirmation, autosave recovery, or status explanation that names what cannot be reversed.", "uiGuidance": [ "Do not label an action Undo unless the system has captured enough state to restore the affected object, order, relationships, permissions, counts, focus context, and visible outcome.", "If recovery is partial, delayed, external-effect-limited, permission-limited, or unavailable after a commit boundary, label the action honestly as Restore from trash, Request recovery, Recreate, Retry, or Contact support instead of Undo." ], "uxGuidance": [ "Users should trust that activating Undo returns them to the state before the action, not a best-effort approximation that hides what remains changed.", "Treat undo as an implementation contract: capture state before commit, block or re-label undo after external side effects, and report restored, expired, failed, partial, and final states separately." ], "uiExamples": { "good": [ "Deleting Quarterly report stores the row ID, folder, owner, sort position, labels, shared access, and selected filter, then Undo restores the row to the same list location.", "Sending a customer email does not show Undo; it shows Message sent and View activity because the external recipient cannot be recalled." ], "bad": [ "A toast says Undo after removing a teammate, but Undo only re-adds the name and not the permissions, group memberships, or notification that already went out.", "A bulk archive action offers one Undo button, but a second archive overwrites the first recovery target." ] }, "uxExamples": { "good": [ "A user archives a task by mistake, activates Undo, and the task returns with its original owner, due date, tags, position, and selection state.", "A user sees Undo expired after the local recovery window ends and can still open Trash because the object moved to a durable recovery surface." ], "bad": [ "A user clicks Undo after deleting a shared file and the file name reappears, but collaborators, comments, and folder path are lost.", "A user clicks Undo for a sent refund email and assumes the customer never received it, but the external email was already delivered." ] }, "problemContext": [ "A product shows Undo in a toast, snackbar, activity row, command bar, keyboard shortcut, history stack, or recovery panel after a completed action.", "The action may affect object identity, list order, filters, permissions, relationships, notifications, background jobs, external recipients, payments, webhooks, or audit state.", "The product may capture only part of the prior state or let the recovery window expire while the control still looks available.", "Users may perform multiple actions quickly, change filters, leave the route, reload, go offline, or lose permission before trying to undo." ], "selectionRules": [ "Flag this anti-pattern when an Undo control does not restore the exact object, value, order, relationship, permission, selection, and visible status it claims to reverse.", "Flag it when undo appears after an external side effect such as email, payment, webhook, permission notification, customer message, or production command has already left the system boundary.", "Flag it when several actions overwrite one recovery target without showing which action Undo will reverse.", "Flag it when undo expires silently or remains visible after the recovery window is gone.", "Use undo when the product captures prior state before the action and can restore it faithfully before irreversible side effects occur.", "Use restore from trash when recovery happens later from a durable deleted-items location with retention and restore metadata.", "Use destructive action confirmation when exact recovery is impossible and users need to decide before commitment.", "Use toast notification for disposable feedback only; a toast may carry Undo only when the recovery action remains reachable long enough and works truthfully.", "Use autosave recovery when the recovery target is unsaved or uncertain local work rather than a completed reversible command.", "Use confirmation fatigue to audit overuse of confirmations, but do not replace a broken undo with another prompt unless pre-action review is the right safeguard." ], "requiredStates": [ "Pre-action state with enough identity, relationship, order, permission, and context captured for reversal.", "Completed recoverable state that names the affected action and exact target.", "Undo available state with a visible, keyboard-reachable recovery control.", "Restored state showing the object, values, relationships, counts, selection, and focus context returned.", "Undo expired state that removes or disables the control and explains the final commitment.", "Undo failed state that reports what was not restored and why.", "Partial restore state that is not labelled as full undo.", "External side-effect state where undo is unavailable or truthfully labelled as request, revoke, restore, or follow-up.", "Multiple-action queue state that shows which action each undo reverses.", "Bad fake undo state where the control appears but restoration is absent, partial, stale, overwritten, or misleading." ], "interactionContract": [ "The system captures reversible state before applying the action, not after users request undo.", "The undo label names the action or object when ambiguity is possible.", "Activating Undo restores enough state for the user to trust that the action was reversed.", "If restoration is partial, the UI says partial restore, restore available, request recovery, or open trash instead of Undo.", "Undo remains reachable long enough for pointer, keyboard, screen reader, and distracted users, or the action is routed to durable recovery.", "When the undo window expires, the UI removes or re-labels the control and reports final commitment.", "External effects are called out honestly; undo must not imply recalled email, payment, webhook, or notification unless that recall is actually implemented.", "Multiple recoverable actions are queued, grouped, or scoped so one Undo cannot accidentally refer to a different action." ], "implementationChecklist": [ "Define what exact prior state must be restored for each action: ID, parent, order, labels, ownership, permissions, relationships, counts, draft values, and focus target.", "Capture the restore payload before mutating local, server, and external systems.", "Make undo idempotent and scoped to a stable action ID so duplicate clicks or retries do not corrupt recovery.", "Block or re-label undo for actions with irreversible external effects, or delay those effects until the recovery window closes.", "Keep recovery controls visible, keyboard reachable, and stable while focused; do not auto-remove a focused Undo button.", "Handle multiple actions with an undo stack, per-item undo, grouped undo, or explicit commit boundary.", "Report restored, expired, failed, partial, final, and unavailable states in text, not only by removing the toast.", "Test reload, route changes, filters, pagination, selection, offline, duplicate actions, permissions, external notifications, and screen reader status before claiming undo." ], "commonMisuses": [ "Showing Undo after an action that has already sent email, money, permissions, or webhooks outside the product.", "Restoring only a visible row while losing comments, labels, sharing, order, or ownership.", "Letting a second action overwrite the first action's undo payload.", "Using a disappearing toast as the only recovery path for an important object.", "Keeping Undo visible after the server has already committed a permanent delete.", "Treating rollback failure as success because the item name reappeared.", "Saying Undo when the real action is open trash, recreate from template, request admin restore, or retry save." ], "critiqueQuestions": [ "What exact state is captured before the action, and what proof shows it can be restored?", "Can any external recipient, payment, webhook, permission change, or audit event still observe the action after Undo?", "Does Undo restore identity, order, relationships, labels, permissions, counts, selection, and focus context?", "What happens if the user performs another action before clicking Undo?", "When does the recovery window expire, and how does the UI show final commitment?", "Is this actually trash restore, autosave recovery, retry, confirmation, or support recovery rather than undo?" ], "relatedPatterns": [ "undo", "toast-notification", "restore-from-trash", "destructive-action-confirmation", "autosave-recovery", "confirmation-dialog" ], "comparisons": [ "fake-undo-vs-undo-vs-toast-notification-vs-restore-from-trash-vs-destructive-action-confirmation-vs-autosave-recovery" ], "sourceIds": [ "apple-hig-undo-redo", "material-design-snackbar", "microsoft-windows-confirmations", "gitlab-saving-and-feedback", "wcag-status-messages" ] }, { "id": "fallback-path", "completionStatus": "complete", "name": "Fallback path", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "User-directed alternate route when the primary path cannot complete", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can be blocked by a lookup miss, unavailable dependency, unsupported device, digital exclusion, missing record, file or identity check problem, or channel constraint even though the task still needs a way to complete.", "solution": "Offer an explicit alternate route that names the changed method, preserves useful context, explains tradeoffs and timing, lets users return or continue safely, and proves whether the fallback still completes the same outcome or becomes a support handoff.", "uiGuidance": [ "Place the alternate route beside the blocked primary path with a label that names what changes, such as Enter address manually, Use cached report, Call support with reference, or Continue with paper evidence.", "Show what carries over into the fallback: application reference, entered data, uploaded files, selected filters, eligibility answers, deadline, and which steps still need completion." ], "uxGuidance": [ "Use a fallback path when the primary route is unavailable, unsuitable, unsupported, or repeatedly failing, and users still need a credible way to complete the task.", "Preserve context, explain capability tradeoffs, keep return-to-primary possible where useful, and make the fallback route complete the same user outcome or clearly state the remaining handoff." ], "uiExamples": { "good": [ "An address lookup says We could not find this address, keeps postcode SW1A 1AA visible, and offers Enter address manually, Try another postcode, and Get help with reference APP-2048.", "A service dependency outage panel says Identity check unavailable, shows saved application answers, and offers Upload documents for manual review with expected review time." ], "bad": [ "A lookup returns No matches and only shows Search again, even though manual address entry is supported.", "A download form link is presented as a fallback but does not say whether the user can submit it, track it, or preserve the current application reference." ] }, "uxExamples": { "good": [ "A user whose address is missing from the lookup switches to manual entry with the postcode and application reference retained, completes the same application, and can return to lookup without losing typed fields.", "A user who cannot complete the online flow gets a phone or webchat route with the same reference and a clear list of information needed to finish the service." ], "bad": [ "A user tries the same failed lookup five times because the manual route is hidden until after repeated failure.", "A fallback route clears uploaded evidence and silently restarts the application from the beginning." ] }, "problemContext": [ "The primary route depends on search, lookup, verification, payment, upload, network, JavaScript, device capability, third-party service, account access, or user digital confidence.", "The product has a credible alternate route such as manual entry, evidence upload, phone support, webchat, cached data, branch office, paper form, later handoff, or replacement service.", "Users may have already entered data or gathered evidence that must not be lost when switching paths.", "The alternate route may have different timing, eligibility, tracking, privacy, support, or proof requirements that users need before committing." ], "selectionRules": [ "Choose fallback path when the user needs an alternate way to finish the same task after the primary method is blocked, unsupported, unavailable, or unsuitable.", "Offer fallback before repeated failure traps users; do not require users to fail several times before seeing a manual or assisted route.", "Name the fallback by method and outcome, not vague copy such as Other options or Continue.", "Preserve entered data, selected records, uploads, payment state, application reference, and deadline context across the switch whenever technically and legally possible.", "Explain tradeoffs such as slower review, manual evidence check, limited availability, support hours, offline submission, or missing automatic validation.", "Keep the primary path available to retry or return to when it remains useful, but separate retrying the same action from switching to a different route.", "Use error state to explain the failed condition; use fallback path for the alternate route that changes how users continue.", "Use service unavailable page when an entire service route is closed; include fallback path there only when users can complete by another channel.", "Use offline state when connection loss changes what users can do locally; include fallback path only when cached, local, or alternate-channel completion is actually supported.", "Do not present a link as a fallback unless it has a real completion, submission, tracking, or support contract." ], "requiredStates": [ "Primary path available state.", "Primary path blocked or unsupported state with cause.", "Fallback offered state with method, scope, and tradeoff.", "Fallback selected state showing what data carries over.", "Fallback in-progress state with changed fields, evidence, channel, or support handoff.", "Return-to-primary state when switching back is safe.", "Fallback completed state with confirmation or next step.", "Fallback unavailable state that explains why no alternate route exists.", "Data-loss prevention state before leaving or restarting the current path.", "Assisted-support state with reference, contact route, hours, and information needed." ], "interactionContract": [ "The fallback path is a different route to the same user outcome or an explicitly named support handoff, not another attempt at the same failing operation.", "Users can see what will happen to their current data before switching paths.", "The fallback route carries forward a stable reference or clearly explains why the user must start a separate process.", "The UI distinguishes Try again, edit input, switch to manual entry, contact support, download form, and return later actions.", "If the fallback has reduced validation, slower review, limited hours, or extra evidence, that tradeoff is visible before users choose it.", "If no credible fallback exists, the page says so directly and gives the safest next step instead of inventing a dead-end route.", "Switching paths does not silently clear user work, create duplicate submissions, or change eligibility decisions." ], "implementationChecklist": [ "Map each primary-route dependency to whether a real fallback exists, who owns it, and what outcome it can complete.", "Define the data handoff contract: retained fields, dropped fields, uploaded files, references, timestamps, consents, and audit trail.", "Write fallback labels that name both method and outcome, such as Enter address manually or Upload documents for manual review.", "Store a stable reference before switching to support, paper, offline, or manual review channels.", "Show expected timing, support hours, proof requirements, privacy implications, and tracking behavior for slower or assisted paths.", "Provide a safe return-to-primary control where switching back can preserve work and reduce unnecessary manual processing.", "Instrument fallback selection, completion, abandonment, return-to-primary, and support demand so owners can identify failing primary paths.", "Test no-match lookup, JavaScript failure, unsupported file/device, third-party outage, support closed, duplicate submission, back button, refresh, mobile width, keyboard flow, and screen readers." ], "commonMisuses": [ "Hiding manual entry or support until users repeatedly fail.", "Calling Retry a fallback even though it repeats the same broken operation.", "Offering a download or phone number without an application reference or completion contract.", "Clearing typed data, selected files, or uploaded evidence when users switch paths.", "Using a fallback path to avoid fixing a primary route that fails for many users.", "Giving a fallback that changes eligibility, price, deadline, or privacy without saying so.", "Showing no fallback when a known alternate channel exists." ], "critiqueQuestions": [ "What primary path can fail or be unsuitable, and what exact route lets users continue?", "Does the fallback complete the same task, or is it only a support handoff?", "Which data, uploads, consents, and references carry over when users switch?", "What timing, validation, privacy, deadline, or support-hour tradeoffs change?", "Can users return to the primary path without losing work?", "How will the team know the fallback is being used because the primary path is broken?" ], "relatedPatterns": [ "retry", "error-state", "service-unavailable-page", "offline-state", "address-entry", "no-results-recovery" ], "comparisons": [ "fallback-path-vs-retry-vs-error-state-vs-service-unavailable-page" ], "sourceIds": [ "govuk-addresses-pattern", "govuk-assisted-digital-support", "webdev-offline-fallback-page", "w3c-wcag-multiple-ways" ] }, { "id": "favorites", "completionStatus": "complete", "name": "Favorites", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "User-marked preferred items gathered into a recognizable return-access list", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need a durable way to mark preferred or personally important items for return access, but recency, search ranking, recommendations, and pinned prominence do not reliably express personal affinity.", "solution": "Provide explicit favorite and unfavorite controls, a recognizable saved-favorites list or filter, item context, scope and visibility cues, separate handling from pins, recents, saved views, and subscriptions, plus repair states for moved, restricted, or unavailable items.", "uiGuidance": [ "Show a clearly labelled Favorites or Starred area with item identity, item type, location, ownership or scope, selected favorite state, and an unfavorite control that is visually tied to each item.", "Keep favorite controls available where users encounter eligible items, and show whether the favorite is personal, synced, public, shared, unavailable, or also used by recommendation or popularity systems." ], "uxGuidance": [ "Use favorites when users want to mark affinity, preference, or personal save-for-later access without necessarily changing list order, top placement, notifications, or the underlying object.", "Separate favorites from pinned items, recently viewed, saved views, subscriptions, collections, and recommendations so users can predict whether starring affects quick access, display prominence, delivery, public signals, or only a personal saved list." ], "uiExamples": { "good": [ "A file hub has a Favorites section with file names, file types, folder paths, owner labels, filled star buttons, and an explanation that removing a favorite keeps the file in its folder.", "A repository card has a Star button that shows the selected state, keeps the repository reachable from a stars page, and distinguishes starring from watching or following updates." ], "bad": [ "A star icon appears beside items with no label, no selected state, and no way to tell whether it favorites, rates, pins, recommends, or subscribes.", "Favorited files are mixed with pinned files and recent files in one Important list, so users cannot tell whether order, history, liking, or future delivery controls the result." ] }, "uxExamples": { "good": [ "A user stars three policy folders for personal access, filters the workspace to Favorites, and removes one favorite without deleting or moving the folder.", "A developer stars a repository to return to it later, understands that watching handles notifications separately, and can find all starred repositories from a personal saved list." ], "bad": [ "A user removes a favorite and loses the underlying record because the product treated unfavorite as delete.", "A dashboard automatically favorites every recently opened item, causing users to distrust both favorites and recents." ] }, "problemContext": [ "The product has revisitable objects such as files, folders, repositories, topics, records, reports, saved searches, messages, products, places, or help articles.", "Users may want to mark an item for personal return, preference, or liking without making it the top item for everyone.", "Favorite state can feed a personal list, a quick-access section, public popularity counts, recommendations, or cross-device sync depending on the product.", "Favorite items can be deleted, moved, permission-lost, hidden by policy, duplicated by similar names, or confused with pins, subscriptions, saved views, and collections." ], "selectionRules": [ "Choose favorites when the main user intent is personal preference, affinity, or saved return access for known items.", "Use pinned items when the action changes placement, top-section prominence, stable order, or public profile display.", "Use recently viewed when the list should be automatic history based on actual openings rather than deliberate saves.", "Use saved view when the saved object is a reusable presentation or query configuration such as filters, columns, sort, grouping, or density.", "Use follow / subscribe when users want future update delivery rather than a saved item list.", "Use collection when users are intentionally building a named set with membership, sharing, ordering, notes, or batch actions beyond simple favorite state.", "Expose whether a favorite is personal, synced, shared, public, or counted toward popularity before the mark affects other people or recommendations.", "Keep favorite and unfavorite separate from delete, hide, archive, remove from recents, pin, watch, follow, and unsubscribe.", "Provide a Favorites list, filter, or search facet once favoriting is available so users can reliably retrieve marked items.", "Avoid favorites when users need ranked recommendations, task status, workflow assignment, or a canonical source of truth rather than personal preference." ], "requiredStates": [ "No favorites state with a path to favorite eligible items.", "Favoritable item state, favorited item state, favorite pending, unfavorite pending, and failed-save states.", "Favorites list or filter with item name, type, location, owner, scope, and last-known availability.", "Personal favorite, synced favorite, public or counted favorite, shared favorite, and policy-limited favorite states when those scopes exist.", "Duplicate-name, moved, deleted, archived, permission-lost, restricted, and unavailable favorite states.", "Mobile or narrow-screen state where favorite controls and item context remain reachable." ], "interactionContract": [ "Favoriting records a relationship between the user and the existing item without duplicating, moving, pinning, subscribing to, or changing the item.", "Unfavoriting removes only the favorite relationship and leaves the underlying item, recent history, pins, subscriptions, and saved views intact.", "A favorited item can be found again through a Favorites section, filter, shortcut, or saved-list page with the same identity used on the source item.", "Favorite state is visibly persistent wherever the same item appears, including lists, detail pages, search results, and mobile views.", "If favorites influence recommendations, popularity, or public counts, the product discloses that effect near the control or account setting.", "When a favorite becomes unavailable, the list explains the status and offers remove, request-access, open-location, or replace paths instead of dead links.", "Bulk favorite cleanup, import, or sync actions preserve user intent and do not silently change pins, subscriptions, collections, or recent history." ], "implementationChecklist": [ "Model favorite state separately from pin order, recent history, saved view configuration, collection membership, watch or follow subscriptions, and item deletion.", "Store stable item IDs with type, location, owner, favorite scope, favorited time, and visibility or public-count behavior.", "Provide accessible favorite and unfavorite controls with selected state, text labels, and status messages for saves, failures, and removals.", "Add a Favorites destination, filter, or facet with empty, loading, duplicate-name, unavailable, and permission-limited states.", "Refresh item metadata in the favorite list and mark moved, deleted, archived, or restricted items before navigation.", "Respect account sync, private mode, managed accounts, public profile, recommendation, and popularity-count settings.", "Test long names, similar names, unavailable items, cross-device sync, public versus personal effects, keyboard access, touch targets, and unfavorite-not-delete copy." ], "commonMisuses": [ "Using a star icon with no label or selected state.", "Treating favorites as pins, recents, subscriptions, saved searches, recommendations, ratings, or votes without explaining the effect.", "Removing, archiving, hiding, or deleting the item when users only meant to unfavorite it.", "Offering favorite buttons without any reliable Favorites list or filter.", "Leaking sensitive favorited item names across shared, public, or screen-shared surfaces.", "Automatically favoriting items based on recency, popularity, or algorithmic guesses." ], "critiqueQuestions": [ "What exactly changes when the user favorites this item: personal quick access, public count, recommendation input, or visible placement?", "Where can users reliably find all of their favorited items later?", "Can users unfavorite without deleting, unpinning, unsubscribing, or removing recent history?", "Is favorite state personal, synced across devices, shared with a team, public, or used by ranking systems?", "What happens when a favorite is moved, renamed, deleted, archived, duplicated, or permission-restricted?", "Would a pin, saved view, collection, follow, or recently viewed list better match the user's intent?" ], "relatedPatterns": [ "pinned-items", "recently-viewed", "saved-view", "saved-search", "follow-subscribe", "collection" ], "comparisons": [ "pinned-items-vs-favorites-vs-recently-viewed-vs-saved-view" ], "sourceIds": [ "github-saving-repositories-with-stars", "microsoft-outlook-use-favorites", "microsoft-office-recent-files", "atlassian-jira-save-search-filter" ] }, { "id": "feed", "completionStatus": "complete", "name": "Feed", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Dynamic stream of article-like updates that may load or insert content at either end", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to consume a changing stream of updates, posts, events, or stories, but dynamic insertion, infinite loading, mixed ranking, and unlabeled stream items can destroy orientation and trust.", "solution": "Present updates as a labelled feed with article-like item boundaries, source and timestamp metadata, ordering disclosure, controlled loading, queued-new-item handling, position preservation, accessible feed semantics, and clear labels for recommended, promoted, unread, or stale content.", "uiGuidance": [ "Render the feed as a labelled stream of item boundaries where each item has a source or author, timestamp, title or body summary, type, actions, and enough context to stand alone as an article-like update.", "Expose ordering, loading, unread, inserted, sponsored, recommended, and paused-new-items states in the interface instead of relying on silent automatic insertion." ], "uxGuidance": [ "Use feed when users consume a continuing stream of posts, updates, stories, events, or collaboration activity and need to keep their reading position while new or older content appears.", "Protect orientation by preserving scroll position, announcing new items without moving focus, offering load-more or jump-to-latest controls, and labelling non-chronological, promoted, or personalized insertions." ], "uiExamples": { "good": [ "A project feed shows source avatar, actor, timestamp, object name, excerpt, item type, unread marker, reply and save actions, and a visible queued-new-items banner while the reader is midstream.", "A community feed separates chronological posts from recommended posts with labels and keeps Load older updates after the last rendered item." ], "bad": [ "New posts appear above the current paragraph and shift the page while the user is reading.", "Sponsored stories, recommended posts, and chronological updates use identical cards with no reason, source, or timestamp." ] }, "uxExamples": { "good": [ "A user pauses live updates, reads three older posts, sees 2 new updates waiting, then chooses Jump to latest when ready.", "A keyboard user moves through article items, loads older content, and focus remains near the loading boundary with the new item count announced." ], "bad": [ "A feed keeps loading forever, hides the footer, and gives no way to resume from a saved position.", "A product uses an activity feed as the only notification history, but it has no unread semantics, preferences, or mark-read lifecycle." ] }, "problemContext": [ "Items are posts, stories, comments, collaboration updates, activity cards, status updates, messages, media, or event summaries.", "The stream may be chronological, ranked, personalized, filtered, live, paused, or loaded incrementally.", "Users may read in place for a long time while new content arrives, older content loads, or items are updated, removed, or inserted.", "The surface often mixes browsing, social interaction, lightweight actions, media, and links to related objects." ], "selectionRules": [ "Choose feed when the core experience is consuming a continuing stream rather than managing a fixed set of objects.", "Use card list when the content is a bounded set of object cards with filtering, sorting, and object-management behavior.", "Use list view when users need compact row scanning and row actions instead of rich article-like stream consumption.", "Use timeline when items represent a bounded sequence of milestones or events along an explicit temporal path.", "Use activity log when the surface is durable audit history, provenance, or compliance evidence rather than a consumable stream.", "Use notification center when items need unseen and unread semantics, badge behavior, retention, preferences, and mark-read lifecycle.", "Use recommendations when the surface is a ranked suggestion set requiring reason labels, feedback, dismissal, and personalization controls.", "Label feed order honestly as latest, ranked, following, popular, sponsored, recommended, or mixed.", "Offer a deliberate control for new incoming items when automatic insertion above the viewport would move the reader's place.", "Prefer Load more or explicit page boundaries when users need footer access, comparison, task completion, or resumable position.", "Avoid feed when users need aligned attribute comparison, spreadsheet interaction, named collection management, or exact search result review." ], "requiredStates": [ "Default feed with heading, order label, rendered item count or range, and article-like items.", "New item waiting, live updates paused, jump to latest, loaded newer, and loaded older states.", "Loading more, busy, end-of-feed, failed-load, retry, offline, and partial-load states.", "Unread, read, new, updated, removed, muted, hidden, saved, liked, replied, and shared item states when supported.", "Sponsored, promoted, recommended, following-only, filtered, ranked, chronological, and mixed-order disclosure states.", "Empty feed, no matching updates, first-run follow suggestions, permission-limited, blocked-author, and stale-content states.", "Focused item, focused action, keyboard reading boundary, and restored-position states.", "Responsive state where item identity, source, timestamp, action ownership, and loading controls remain visible." ], "interactionContract": [ "Each feed item has a stable identity, source, timestamp, item boundary, and primary destination or action.", "New items do not move focus or scroll position unless the user explicitly chooses to jump or refresh.", "Loading older or newer items preserves the reader's position and places focus on the triggering control, the newly loaded boundary, or a clear status message.", "The feed communicates whether ordering is chronological, ranked, filtered, or personalized before users rely on recency.", "Dismiss, mute, save, like, reply, share, and report actions affect the named item and give immediate feedback without collapsing unrelated items.", "Sponsored, promoted, recommended, and following content remain distinguishable even when they share the same card anatomy.", "If virtualization removes items from the DOM, article positions, labels, and focus recovery remain stable.", "If the feed is used for work activity, notification or audit obligations are handled by notification center or activity log instead of being implied by the feed alone." ], "implementationChecklist": [ "Define feed item identity, article heading, source or author, timestamp, type, body summary, media, primary route, and item-scoped actions.", "Choose ordering rules and expose them in text: latest first, oldest first, ranked, following, recommended, sponsored, or mixed.", "Use feed and article semantics when automatic reading and loading behavior benefits assistive technology; otherwise use semantic lists with equivalent labels and loading status.", "Maintain aria-busy or loading status while inserting or removing feed items and avoid changing the middle of the stream unexpectedly.", "Add queued-new-item, pause live updates, jump to latest, load newer, load older, end-of-feed, retry, and restored-position behavior.", "Preserve scroll and focus position across refreshes, item updates, media expansion, filters, route return, and incremental loading.", "Label promoted, sponsored, recommended, filtered, muted, hidden, and stale items in the item UI and data model.", "Test keyboard reading order, screen-reader item boundaries, long posts, nested actions, media fallback, virtualization, reduced motion, mobile wrapping, and footer reachability." ], "commonMisuses": [ "Calling any vertical card list a feed even when it is a bounded object collection.", "Auto-prepending new content and moving the reader away from the item they were reading.", "Mixing ranked, sponsored, recommended, and chronological items without labels.", "Using infinite scroll when users need a footer, exact position, task completion, or a known end.", "Hiding timestamps or source labels until hover.", "Letting action buttons in one item affect a different item after virtualization or live insertion.", "Using a feed as audit history or notification history without the required lifecycle semantics.", "Removing article boundaries and loading status from assistive technologies." ], "critiqueQuestions": [ "Is the user consuming a stream, managing a collection, scanning object rows, reviewing audit history, or triaging notifications?", "What order is the feed using, and can users tell whether an item is latest, ranked, recommended, sponsored, or filtered?", "What happens to the reader's position when new content arrives, older content loads, media expands, or the route is reopened?", "How are new-item counts, unread state, loaded boundaries, failures, and end-of-feed communicated?", "Which actions belong to one item, and how does the UI prevent action ownership errors after live updates?", "Would card list, list view, timeline, activity log, notification center, recommendations, pagination, or saved view better fit the task?" ], "relatedPatterns": [ "card-list", "list-view", "recommendations", "notification-center", "pagination", "filter-panel", "sort-controls", "saved-search", "search-history", "empty-state" ], "comparisons": [ "feed-vs-card-list-vs-recommendations-vs-notification-center" ], "sourceIds": [ "wai-aria-apg-feed", "mdn-aria-feed-role", "nng-infinite-scrolling-tips", "microsoft-teams-activity-feed-notifications" ] }, { "id": "file-upload", "completionStatus": "complete", "name": "File upload", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "File selection and attachment control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to attach documents, images, or other files, but upload controls often hide requirements, lose selected files after errors, blur the difference between local selection and completed upload, or block keyboard and mobile users.", "solution": "Provide a labelled file upload control that states requirements up front, uses a reliable file chooser, displays selected file details, validates type and size, shows progress and outcome, supports removal and retry, and preserves the surrounding task state.", "uiGuidance": [ "Render a visible label, persistent hint, native file chooser or equivalent button, accepted file formats, maximum file size, selected filename, uploaded status, remove control, and field-specific error message.", "Distinguish selected, uploading, uploaded, failed, removed, and submitted states visually and in text so users know whether the file is merely chosen locally or actually attached to the service." ], "uxGuidance": [ "Use file upload only when the service needs the original file and make expectations clear before the user opens the file picker.", "Let users select, review, remove, replace, retry, and continue without losing unrelated form answers or confusing upload completion with final submission." ], "uiExamples": { "good": [ "An evidence upload field says Upload bank statement, hints PDF, PNG, or JPG up to 10 MB, shows statement.pdf selected, displays upload progress, and offers Remove.", "A passport photo uploader shows the chosen filename, thumbnail-independent file details, an uploaded badge, and an inline error when the file is too large." ], "bad": [ "A button labelled Browse sits under Documents with no hint about accepted formats, size limit, or whether the selected file was uploaded.", "A custom upload tile hides the real file input, shows only an icon, and gives no selected filename or remove control." ] }, "uxExamples": { "good": [ "A user selects bank-statement.pdf, sees it queued, watches progress reach uploaded, removes it to choose another file, then submits after reviewing the rest of the form.", "A user chooses image.heic, sees a precise wrong-type error, keeps the page state, chooses statement.pdf, retries after a simulated network failure, and continues." ], "bad": [ "A user selects a 28 MB scan, clicks Continue, and the page reloads with File failed but the selected filename and other answers are gone.", "A user thinks the file is submitted because a local filename appears, but the service never uploads it before the final form submit." ] }, "problemContext": [ "The product needs the original file for evidence, identity, compliance, media review, document processing, or support investigation.", "Users may be on mobile devices, public computers, locked-down desktops, or assistive technology where drag-and-drop may not be available.", "The file may fail because of type, size, malware scanning, password protection, interrupted network, duplicate attachment, or expired session.", "The upload may happen immediately after selection or later with the form submit, and users need to understand which model is active.", "The service must validate selected files server-side even when the client limits accepted extensions or MIME types." ], "selectionRules": [ "Choose file upload when the original file itself is needed, not just information from the file.", "Use text input when a typed value, reference number, or explanation can replace the file.", "Use a single-question page before upload when users first need to answer whether they have evidence or which evidence type applies.", "Use a multi-step form when upload depends on earlier answers or is one saved step in a longer journey.", "Use drag-and-drop upload only as an enhancement when button-based file selection remains available.", "Use bulk import when the file contains structured rows that need parsing, mapping, validation, and an import report.", "Avoid asking for an upload unless the file is critical to completing the service.", "State accepted formats, maximum size, count limit, password-protected file policy, and whether photos or scans are acceptable.", "Preserve selected filenames and unrelated answers after recoverable validation or network errors.", "Make the upload-versus-submit boundary explicit when the surrounding form still needs final review." ], "requiredStates": [ "Empty labelled state with requirements hint and choose-file action.", "File chooser invoked state with focus returning to the upload control.", "Selected but not uploaded state showing filename, size, type, and remove action.", "Uploading state with progress or pending indicator tied to the file.", "Uploaded state showing successful attachment and replace or remove controls.", "Wrong file type error state with accepted formats repeated.", "File too large error state with maximum size and current file size.", "Upload failed state with retry and keep-file guidance.", "Removed file state confirming no attachment is queued.", "Submitted state clarifying that the upload is included with the completed form." ], "interactionContract": [ "Activating the choose-file button opens the platform file picker and returns focus to the invoking control or selected file summary afterward.", "Selecting a file records filename, size, type, and local selected state before upload validation starts.", "Client validation can warn about accepted types and size, but server validation remains authoritative.", "Removing a file clears only that attachment and does not erase other form values.", "Retrying a failed upload keeps the selected filename visible while the retry is pending.", "Submitting the surrounding task is blocked until required uploads are valid or the user chooses an allowed no-file path.", "Status changes are announced without repeatedly reading long filenames or progress updates on every small percentage change." ], "implementationChecklist": [ "Define accepted extensions, MIME types, maximum size, count limit, scanning policy, duplicate handling, password-protected file handling, upload timing, and storage outcome before designing the control.", "Use a visible label and persistent hint; connect hint, selected-file summary, status, and error text to the input or upload button.", "Show selected filename, file size, upload state, uploaded result, remove action, retry action, and final included-in-submission state.", "Validate type, size, count, empty required state, duplicate file, interrupted upload, virus scan, and server rejection with specific recoverable messages.", "Keep other answers and selected filenames visible after validation errors and network retries.", "Test keyboard selection, focus return, screen reader announcements, mobile camera/file sources, public-device privacy, browser Back, slow networks, timeout, and unsupported file formats.", "Do not make drag-and-drop the only upload path; keep a normal file chooser available." ], "commonMisuses": [ "Asking for a file when a typed reference number or simple answer would be enough.", "Showing selected filename as if the final service submission has already happened.", "Hiding accepted formats and maximum file size until after the user fails.", "Clearing the selected file and unrelated form answers after a recoverable error.", "Using drag-and-drop as the only interaction path.", "Relying on the accept attribute or filename extension as proof that the file is safe or valid.", "Treating structured spreadsheet imports as ordinary attachments with no row-level feedback." ], "critiqueQuestions": [ "Why does the service need the original file rather than a typed value?", "What file types, sizes, count limits, password policies, and scanning delays will users encounter?", "Can users tell whether the file is selected locally, uploading, uploaded, failed, removed, or included in final submit?", "What happens if upload fails after the user has filled the rest of the form?", "Can keyboard, screen reader, mobile, and public-computer users complete the upload path without drag-and-drop?", "Does the backend validate the same type, size, count, scan, and required-file rules as the UI?" ], "relatedPatterns": [ "text-input", "single-question-page", "multi-step-form", "inline-validation", "error-summary", "loading-skeleton" ], "comparisons": [ "file-upload-vs-text-input-vs-single-question-page-vs-multi-step-form" ], "sourceIds": [ "govuk-file-upload-component", "carbon-file-uploader-component", "mdn-html-file-input", "dwp-file-upload-research" ] }, { "id": "filter-chips", "completionStatus": "complete", "name": "Filter chips", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Compact chip set for toggling or removing result filters", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need quick visibility and control over simple filters, but compact chip UI can become ambiguous, unstable, inaccessible, or confused with decorative tags and badges.", "solution": "Provide a labelled chip set where each chip clearly represents a filter value, selected chips update the result set predictably, applied chips can be removed one at a time, and overflow or complex criteria escalate to a filter panel.", "uiGuidance": [ "Render filter chips as a compact set of short, consistently styled controls near the content they filter, with clear selected, unselected, focused, disabled, and removable states.", "When chips summarize applied filters, include the category and value in the chip label and a clear remove affordance that remains keyboard focusable." ], "uxGuidance": [ "Use filter chips for quick, low-cost filtering when users can understand the available criteria at a glance and combine a few chips without opening a larger panel.", "Keep chip order stable, update result count or active criteria immediately, and let users remove one chip or clear all filters without resetting query, sort, page, or view state." ], "uiExamples": { "good": [ "A search results page shows chips for Open, Urgent, Appeals, and Benefits below the search box, with selected chips using a checkmark and stronger background.", "Applied filters above a table read Status: Open and Team: Benefits, each with a named remove button and a separate Clear all control.", "A horizontally scrollable mobile chip row keeps the most common filters first and shows no more than a few rows before offering More filters." ], "bad": [ "A single pill labelled Filter sits alone and behaves like a vague button.", "Selected chips jump to the front of the row after every click, so the user has to rescan the whole set.", "A non-removable status badge looks identical to removable filter chips." ] }, "uxExamples": { "good": [ "A user taps Urgent and Appeals, sees the result count drop immediately, then removes Appeals without losing the search query or sort order.", "A user tabs to Status: Open, presses Delete, and focus moves to the next applied chip while the result summary updates.", "A no-result chip combination keeps every active chip visible and offers Clear all plus the ability to remove one restrictive chip." ], "bad": [ "Tapping a chip changes the page route and clears the result context.", "Removing a chip clears all filters, search text, and sorting.", "A chip row wraps into six lines and pushes the results out of view." ] }, "problemContext": [ "The page has a result set with a small number of high-frequency filters users often toggle directly.", "Filters may have been selected elsewhere and need a compact active-state summary near the result count.", "The UI must distinguish chips that filter results from decorative tags, status badges, choice chips, action chips, and selected form values." ], "selectionRules": [ "Choose filter chips when there are a few high-frequency filters that can stay visible near the result set without overwhelming scanning.", "Use selected-state chips when each chip itself toggles a filter on or off.", "Use dismissible applied-filter chips when criteria were chosen from search, filter panel, or advanced search and users need a compact way to remove them.", "Include category names in applied chips when values are ambiguous, such as Status: Open instead of only Open.", "Keep chip order stable after selection; do not reorder existing chips to the front or remove unselected options unless the entire model is clearly an applied-chip summary.", "Use a filter panel when filters need categories, ranges, dates, many options, batch apply, or mobile full-screen management.", "Use multi-select when chips represent selected form values that will be submitted or saved rather than filters applied to current results.", "Use choice chips, radio groups, or segmented controls when exactly one option must be active.", "Use badges or read-only tags when labels are informational and cannot be toggled or removed.", "Use sort controls when users need to change order rather than include or exclude items." ], "requiredStates": [ "Unselected chip set state with no active filters and a clear result count.", "Selected chip state with visible selected indicator and updated result count.", "Applied dismissible chip state with category-value label and remove affordance.", "Focused chip or remove-control state for keyboard operation.", "Overflow state for many chips, such as horizontal scrolling, More filters, or escalation to a panel.", "No-result state that preserves active chips and offers clear-one or clear-all recovery." ], "interactionContract": [ "Selecting a filter chip toggles only that filter and updates the result count or result list without changing unrelated query, sort, pagination, or view state.", "Removing an applied chip removes only that criterion and keeps the remaining chip set stable.", "Clear all removes user-applied chip filters as a group while preserving unrelated search and sort controls.", "Selected chips remain discoverable by text and icon or state, not color alone.", "Chip labels stay short, do not wrap, and expose a fuller accessible label when visible text is abbreviated.", "Keyboard users can focus each interactive chip and remove or toggle it with Enter, Space, Backspace, or Delete according to the component contract." ], "implementationChecklist": [ "Place the chip set near the search field, result count, or content region it filters.", "Use button semantics for toggling chips and named remove buttons for dismissible applied chips.", "Show selected state with text, icon, border, or checkmark in addition to color.", "Keep chip labels concise; include category plus value when the value alone is ambiguous.", "Preserve chip order after selection and avoid animated reordering that makes options harder to find.", "Expose clear-one and clear-all controls when more than one filter can be active.", "Set an overflow strategy before chips wrap into many lines, such as horizontal scrolling, a More filters chip, or a filter panel.", "Update a result-count status region when chip filters change and keep focus near the chip set or result summary." ], "commonMisuses": [ "Using a lone chip as a generic Filter button.", "Styling decorative tags, status badges, and removable filters the same way.", "Reordering all selected chips to the front after each click.", "Using vague labels such as New, Hot, 1, or More without category or result meaning.", "Letting chip rows wrap into several lines that hide the content they filter.", "Removing a chip but resetting query, sort, pagination, view density, or saved view.", "Making the visible chip focusable while hiding the actual remove control from keyboard and screen-reader users." ], "critiqueQuestions": [ "Is each chip a filter control, an applied-filter summary, a selected form value, a status badge, or an action?", "Can users tell which chips are selected without relying on color alone?", "Does selecting or removing one chip preserve query, sort, pagination, and remaining filters?", "Does chip order remain stable enough for users to find the same option again?", "Are chip labels short but still specific enough to explain the filtered criterion?", "At what point should this chip row become a filter panel or More filters control?" ], "relatedPatterns": [ "filter-panel", "faceted-search", "multi-select", "checkbox-group", "segmented-control", "no-results-recovery" ], "comparisons": [ "filter-chips-vs-filter-panel-vs-multi-select" ], "sourceIds": [ "material-design-chips", "cms-filter-chip-component", "carbon-tag-component", "wise-chip-component", "visa-product-design-filters" ] }, { "id": "filter-panel", "completionStatus": "complete", "name": "Filter panel", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Grouped filter control panel for narrowing a current result set", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to narrow a visible result set using several criteria, but the controls, applied state, result count, and reset behavior can become disconnected.", "solution": "Provide a labelled filter panel that groups criteria, preserves selected values, makes active filters visible near the results, applies changes predictably, and lets users clear one filter or all filters without losing unrelated search or sort context.", "uiGuidance": [ "Render filter categories as labelled form controls in a panel adjacent to the result set on wide layouts, with a visible result count and active-filter summary near the results.", "When the panel is collapsed, hidden, or moved into a mobile drawer or accordion, show the number of active filters and a nearby clear-all path so users know the result set is constrained." ], "uxGuidance": [ "Use a filter panel to help users narrow the current list or search result set while preserving orientation, search query, sort order, pagination context, and selected values.", "Choose batch apply when users are likely to change several filter categories before reviewing results; choose instant updates only when changes are lightweight and do not disorient users." ], "uiExamples": { "good": [ "A desktop search page shows a left filter panel with Status, Type, and Date groups, while active chips and the result count sit above the results.", "A mobile result page opens filters in a full-screen panel with Back, Apply filters, Clear all, and a badge showing three active filters on the closed trigger.", "A collapsed filter category shows a check or count when it contains selected values." ], "bad": [ "A filter drawer closes with no active count, leaving users unaware that filters are still hiding records.", "A panel mixes filter options, navigation links, sort controls, and saved views under one Filters heading.", "Checkboxes change visually but there is no Apply button, no instant result update, and no indication that the result list is stale." ] }, "uxExamples": { "good": [ "A user selects Status: Open and Type: Appeal, applies the batch, lands back at the result summary, and sees 12 records with both criteria removable.", "A user clears the Date filter chip and keeps the same search query, sort order, and view mode.", "A user returns to the filter panel and finds previous selections retained so they can refine rather than re-enter criteria." ], "bad": [ "Applying a filter silently resets the query, sort order, current page, and view density.", "Instant filtering reloads after every checkbox and repeatedly pushes the result summary out of view.", "The result list says 0 records but the active filters are hidden inside a closed drawer." ] }, "problemContext": [ "The page contains a searchable, browsable, or scannable result set with multiple attributes users can use to narrow it.", "Filter controls may be persistent on desktop but hidden behind a button, accordion, drawer, or full-screen panel on smaller screens.", "Users need to understand whether the displayed results match current filter controls, especially when filters are batch-applied or hidden out of view." ], "selectionRules": [ "Choose a filter panel when users need grouped controls for narrowing the current result set by several criteria.", "Use a persistent side panel when users frequently refine filters while comparing result cards, list rows, or search results.", "Use a collapsed accordion, drawer, or full-screen panel on compact layouts when result scanning needs priority, but keep an active-filter count on the closed trigger.", "Use batch apply when users may change multiple categories together, result refresh is slow, or each instant update would disrupt focus and reading position.", "Use instant filtering only when selections are simple, fast, and the result count or applied-filter summary updates without shifting users away from their task.", "Show active filters and result count near the results, not only inside the panel, so users can understand result state when the panel is hidden or scrolled away.", "Keep sort controls visually and semantically separate because sorting changes order while filters include or exclude records.", "Use filter chips as removable active-state summaries, not as the only way to discover available filter categories.", "Use no-results recovery when the current filter combination produces an empty result set, but preserve the filters that caused the empty state." ], "requiredStates": [ "Default state with no user-applied filters and an explicit result count.", "Draft state where selected filter controls have changed but batch results have not yet updated.", "Applied state with active-filter count, result count, and removable applied criteria near the results.", "Collapsed or mobile-panel state that still exposes the active-filter count and a way back to results.", "No-results state that preserves active filters and offers clear-one or clear-all recovery.", "Loading or recalculating state when applying filters takes noticeable time." ], "interactionContract": [ "Each filter category has a clear label and contains controls appropriate to the value type, such as checkboxes, radios, ranges, date fields, or text fields.", "Applying filters updates the result count, active-filter summary, and result list as one synchronized outcome.", "Clearing one filter removes only that criterion and leaves search query, sort order, view mode, and unrelated filters intact.", "Clear all returns user-applied filters to their default filter state without erasing unrelated query text or navigation context.", "Collapsed panels, drawers, and mobile triggers expose whether filters are active before users reopen the panel.", "Keyboard focus moves predictably after Apply or Clear, preferably to the result summary or the control that changed state." ], "implementationChecklist": [ "Group filter controls under user-facing category headings and use native form controls where possible.", "Place a result count and applied-filter summary immediately before or above the result list.", "Decide explicitly between batch apply and instant updates; do not leave controls visually selected while results still show the previous state without a draft cue.", "Show active counts on collapsed categories, filter buttons, and mobile triggers.", "Provide clear-one controls for each applied criterion and a clear-all control for the full filter set.", "Preserve selected values when users reopen the panel, change a different filter, page results, or recover from zero results.", "Keep sort, search query, saved view, and pagination state separate from filter reset behavior.", "On small screens, return users to the result summary after applying filters and keep an accessible route back to the panel." ], "commonMisuses": [ "Hiding active filters inside a closed panel with no count, chips, or result-state summary.", "Using a filter panel as a navigation drawer that sends users to different pages instead of narrowing the current data set.", "Resetting search query, sort order, page size, or view density when users clear filters.", "Combining pending draft selections with already-applied result counts without explaining the mismatch.", "Putting every possible attribute into one long panel without prioritization, grouping, search within long categories, or progressive disclosure.", "Using instant updates that steal focus, reload the page, or move the result summary after every checkbox selection." ], "critiqueQuestions": [ "Can users tell which filters are applied without opening or scrolling to the filter panel?", "Does applying filters synchronize the controls, result count, active summary, and list together?", "When filters are collapsed or on mobile, where is the active count shown?", "Does Clear all reset only filters, or does it accidentally erase query, sort, pagination, saved view, or layout state?", "Is this panel exposing filter criteria, or is it being misused as navigation, sorting, or advanced search?", "If the panel uses batch apply, how does the UI show that selected controls are drafts until Apply?" ], "relatedPatterns": [ "faceted-search", "no-results-recovery", "basic-search", "multi-select", "checkbox-group", "skip-link" ], "comparisons": [ "filter-panel-vs-faceted-search-vs-no-results-recovery" ], "sourceIds": [ "govuk-publishing-search-filter", "carbon-filtering-pattern", "dwp-filter-component-research", "visa-product-design-filters", "nsw-design-system-filters", "moj-design-system-filter" ] }, { "id": "filter-reset-that-clears-unrelated-search", "completionStatus": "complete", "name": "Filter reset that clears unrelated search", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Over-broad filter reset anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to loosen or remove filters, but the reset action silently clears unrelated search or result state that should remain independent.", "solution": "Treat over-broad filter reset as an anti-pattern: make reset scope explicit, preserve unrelated search and result state, separate query reset from filter reset, and show affected state before any broader clear-all action.", "uiGuidance": [ "Treat Clear filters or Reset filters as scoped to filter criteria only; keep the submitted search query, query field, search scope, saved search identity, sort, pagination policy, and view settings visible and unchanged unless the control explicitly names those states.", "Show separate removable state tokens for query, filters, sort, saved search, and scope so users can predict the blast radius of Clear filters, Clear search, Clear all filters, and broader Start over actions." ], "uxGuidance": [ "Use this anti-pattern during review when users try to loosen filters but lose the search term or saved search context that got them to the result set.", "Design reset behavior as a scoped recovery path: users can remove one filter, clear all filters, clear search, or reset the whole result state deliberately, with wording and undo proportional to the amount of state affected." ], "uiExamples": { "good": [ "A result page shows Query: appeal and filters Status: Open, Date: Last 30 days; Clear filters removes only the filter chips and keeps the query token.", "A no-results state offers Remove Date filter, Clear all filters, and Clear search as separate actions.", "A saved filter applies Status and Team criteria while preserving the current search query and sort order." ], "bad": [ "A Clear filters button removes selected filters and empties the search field without warning.", "Removing one filter chip resets the entire query and sort state.", "A Start over link in a no-results state silently clears search, filters, saved search identity, and view settings." ] }, "uxExamples": { "good": [ "A user searching appeal clears all filters and still sees results for appeal sorted by Newest.", "A keyboard user removes Status: Open, focus stays near remaining applied filters, and the submitted query remains in the result summary.", "A mobile user resets draft filter controls inside the filter drawer without erasing the search already submitted on the results page." ], "bad": [ "A user widens results by clearing filters, then cannot remember the exact search phrase that disappeared.", "A no-results recovery button says Reset filters but removes the saved search the user was editing.", "Clearing one chip also returns sort to default and jumps the user back to page one without saying why." ] }, "problemContext": [ "The result set combines keyword search, filter criteria, sort, scope, saved search, saved filter, pagination, view density, or layout state.", "The UI offers Clear filters, Reset, Clear all, Start over, chip removal, mobile drawer reset, no-results recovery, or saved-filter apply actions.", "Users expect a filter reset to widen results by removing constraints, not to destroy the query or saved context that defines the result universe.", "The page may use batch filter drafts, applied filter chips, saved presets, URL parameters, search history, or mobile drawers that make state ownership hard to see." ], "selectionRules": [ "Flag this anti-pattern when a filter reset clears or changes query text, submitted search, search scope, saved search identity, search history, sort order, page size, view mode, selected rows, or route context that is not visibly part of the filters.", "Use Clear filters for user-applied filter criteria only.", "Use Clear search or Clear query when the action removes search text or submitted search context.", "Use Clear search and filters, Reset all, or Start over only when the label names the broader effect and the UI lists the affected state.", "Use chip removal for one applied criterion and clear-all chips for the filter chip group, preserving query, sort, scope, and view state.", "Use saved filter when only reusable filter criteria are applied; preserve query and sort unless the preset explicitly stores them.", "Use saved search when query text, filters, sort, scope, and alert subscriptions are intentionally bundled into a saved object.", "In no-results recovery, offer scoped loosening actions before broad reset.", "In batch filter panels, distinguish Reset draft from Clear applied filters.", "If broad reset is destructive or hard to reconstruct, provide undo, confirmation, or a visible before/after state list." ], "requiredStates": [ "Default state with visible query, filters, sort, scope, and result count separated by ownership.", "Clear one filter state that removes only one criterion and preserves query and sort.", "Clear all filters state that removes all filter criteria and keeps the submitted query.", "Clear search state that removes query text without pretending it is a filter reset.", "Reset draft state in a batch panel that reverts pending filter controls without changing applied results.", "No-results recovery state with scoped loosen-filter and clear-search actions.", "Saved filter or saved search state showing whether the saved object owns query text.", "Pagination and sort preservation state after filter reset.", "Mobile drawer reset state where returning to results keeps the submitted query.", "Bad state showing query wiped, sort reset, saved identity lost, history deleted, and one-chip removal over-clearing state." ], "interactionContract": [ "Every reset control names the state it changes.", "Clear filters removes only filter criteria and updates the result count without clearing the search query.", "Clear search removes only query text and leaves filters visible unless the action explicitly says it clears both.", "Removing one chip removes one criterion; Clear all filters removes the filter group only.", "Sort order, view density, search scope, selected saved search, and pagination policy are preserved or explicitly listed as affected.", "No-results recovery keeps active state visible while users choose which constraint to loosen.", "Batch filter reset distinguishes draft selections from applied filters.", "Focus remains near the changed control or result summary after scoped reset.", "Undo or confirmation is available when a broad reset would be surprising or hard to reconstruct." ], "implementationChecklist": [ "Model query, filters, sort, scope, saved identity, pagination, and view mode as separate state owners.", "Name reset functions after the state they affect, such as clearFilters, clearQuery, clearSort, or resetAllResultState.", "Render query tokens separately from filter chips.", "Place Clear filters near applied filter chips and Clear search near the search field or query token.", "Keep one-chip removal, clear-all-filters, reset-draft, clear-query, and reset-all code paths separate.", "Preserve URL parameters and history entries for unrelated state when clearing filters.", "Add no-results recovery actions that loosen filters without erasing query text.", "Test saved filter application and saved search reruns to confirm only the intended state bundle changes.", "Test keyboard focus, mobile filter drawer reset, browser back, pagination, sort, and reload after every reset path." ], "commonMisuses": [ "Implementing Clear filters by reinitializing the whole search page state object.", "Using one Reset button for draft filters, applied filters, query, sort, and saved search.", "Treating query text as just another filter chip without showing the difference.", "Clearing search history or saved search identity when only visible filters were reset.", "Resetting sort and pagination without explaining that the result set was re-ranked or repaged.", "Using Start over in no-results recovery when a scoped Remove date filter action would preserve useful context.", "Applying saved filters as if they were saved searches, clearing query and sort accidentally." ], "critiqueQuestions": [ "What state does this reset control actually own?", "If the label says Clear filters, does the search query survive?", "Can users see query, filters, sort, scope, saved identity, and page state as separate tokens or controls?", "Does one-chip removal affect only one criterion?", "Does no-results recovery preserve the query that produced the empty set?", "What happens to saved search identity, search history, sort, pagination, URL parameters, and focus after reset?" ], "relatedPatterns": [ "filter-panel", "filter-chips", "basic-search", "saved-search", "saved-filter", "no-results-recovery", "search-history", "sort-controls" ], "comparisons": [ "filter-reset-that-clears-unrelated-search-vs-filter-panel-vs-basic-search-vs-filter-chips-vs-saved-search" ], "sourceIds": [ "carbon-filtering-pattern", "dwp-filter-component-research", "visa-product-design-filters", "moj-design-system-filter", "moj-design-system-search", "servicenow-save-use-list-filters" ] }, { "id": "focus-traversal", "completionStatus": "complete", "name": "Focus traversal", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Sequential keyboard focus path through interactive controls and state changes", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users who navigate by keyboard, switch, screen reader, or other sequential focus methods can lose their place when focus order disagrees with reading order, focus indicators are hidden, overlays leave hidden controls in the tab sequence, constrained regions create a keyboard trap, or state changes remove the focused element without a recovery target.", "solution": "Design focus traversal as a tested interaction path with logical source order, visible focus, clear entry and exit points, predictable Tab and Shift+Tab movement, focus placement after navigation and validation, correct overlay containment, keyboard trap escape, hidden-content removal, and stable recovery after dynamic changes.", "uiGuidance": [ "Render a visible focus path that follows source order and task meaning: skip link, global controls, page heading or first task control, local controls, form fields, inline help, error links, overlays, and next task actions.", "Show focus indicators, focus-origin context, active step, disabled reasons, hidden-section state, and return targets instead of relying on invisible DOM order or positive tabindex patches." ], "uxGuidance": [ "Use focus traversal design when users must move through a page or workflow with Tab and Shift+Tab and understand where focus will go next, where it came from, and how to recover after state changes.", "Define initial focus, next and previous focus targets, focus return after close or submit, error focus, hidden-content removal, virtualized-content recovery, and modal or composite widget boundaries before implementation." ], "uiExamples": { "good": [ "A checkout form focuses the page heading after route change, tabs through Contact, Delivery, Payment, Review, and Submit in the same order users read the page, then returns focus to the changed section after editing.", "A filter drawer moves focus to its heading when opened, traps focus only while modal, removes hidden drawer controls when closed, and returns focus to the Filter button.", "A validation summary receives focus after failed submit, each error link moves focus to the matching field, and Shift+Tab returns predictably through the prior controls." ], "bad": [ "A two-column form tabs from first name to ZIP code to back link because CSS grid order and DOM order disagree.", "A hidden menu and collapsed accordion panel still receive focus.", "A modal closes and focus jumps to the browser top, leaving keyboard users to restart the page." ] }, "uxExamples": { "good": [ "A keyboard user presses Tab from the skip link to the H1, through visible form controls in reading order, into an opened help popover, then back to the invoker after Escape.", "A user opens a modal, cycles within it using Tab and Shift+Tab, closes with Escape, and focus returns to the button that opened it.", "A user filters a list; the selected row is removed, and focus moves to a status message and then to the next available result action." ], "bad": [ "A keyboard user tabs into an offscreen drawer and cannot see or escape the focused control.", "A screen reader user follows an error link, but focus stays on the summary while the visual page scrolls to the field.", "After responsive reflow, focus order jumps between sidebar, content, footer, and hidden mobile navigation." ] }, "problemContext": [ "The page or workflow has links, buttons, form fields, overlays, disclosures, inline validation, repeated navigation, virtualized content, or responsive reflow.", "Users move sequentially with Tab, Shift+Tab, screen reader next control commands, switch scanning, hardware keyboards, remote controls, or assistive devices.", "Opening, closing, submitting, filtering, sorting, expanding, collapsing, routing, or virtualizing content can change which elements exist and where focus should land.", "The product may also include composite widgets that use roving focus, modal surfaces that contain focus, skip links that bypass blocks, and shortcuts that execute commands." ], "selectionRules": [ "Choose focus traversal when the design problem is the user's sequential path through focusable elements and dynamic state changes.", "Use keyboard shortcut when the goal is accelerating one command with a key chord rather than moving focus through the interface.", "Use skip link when the primary issue is bypassing repeated content before main content or another large repeated block.", "Use modal dialog when focus should be contained temporarily inside a modal surface and background content should be inert.", "Use toolbar, menu menubar, listbox, tabs, data grid, or tree grid when a composite widget owns arrow-key or roving-focus behavior inside one logical control.", "Use in-page anchor navigation when users need visible section jumps, active section state, and URL fragments, not the complete page focus sequence.", "Preserve DOM order, reading order, visual order, and Tab order alignment wherever possible.", "Avoid positive tabindex values except for exceptional controlled cases; prefer native order, tabindex 0 for deliberate custom controls, and tabindex -1 for programmatic focus targets.", "Move focus only when users initiate a navigation, open or close a surface, submit a form, follow an error link, or need confirmation of a meaningful state change.", "Never leave focus on hidden, removed, disabled, offscreen, inert, or unrelated content." ], "requiredStates": [ "Initial page focus state after route change or page load.", "Skip link or bypass entry state where repeated blocks are present.", "Normal forward Tab order state.", "Reverse Shift+Tab order state.", "Visible focus indicator state on every interactive control.", "Hidden, collapsed, disabled, or inert content removed from sequential focus state.", "Programmatic focus target state such as heading, status message, or validation summary.", "Overlay opened state with first focus target and background policy.", "Overlay closed state with focus return to invoker or next logical task.", "Validation error state with summary focus and field-link focus movement.", "Dynamic list update state when focused content is removed, filtered, sorted, or virtualized.", "Responsive layout state where visual and DOM order remain coherent.", "Composite widget boundary state where Tab enters and exits while arrows move inside.", "Keyboard trap escape state for embedded or constrained focus regions." ], "interactionContract": [ "The sequential focus path follows DOM and reading order unless a well-tested component-specific model declares a different internal focus contract.", "Every focusable element is visible, operable, named, and relevant at the moment it receives focus.", "Tab moves forward to the next logical focus target, and Shift+Tab moves backward without losing focus or entering hidden content.", "Focus indicators remain visible and meet the visual design's contrast and spacing expectations.", "Opening a modal, drawer, popover, disclosure, or menu places focus deliberately and defines whether focus is contained, adjacent, or returned to the invoker.", "Closing a surface returns focus to the invoker when it remains available or to the next logical task target when the invoker no longer exists.", "Submitting with errors moves focus to the error summary or first invalid field and error links move focus to the matching control.", "When dynamic content removes the focused item, focus moves to a status message, replacement item, next available result, or stable container with a clear path forward." ], "implementationChecklist": [ "Map the focus path for load, Tab, Shift+Tab, open, close, submit, validation, route change, filter, sort, pagination, virtualization, and responsive layouts.", "Keep DOM order aligned with reading and visual order; fix source order before adding tabindex.", "Use native interactive controls first and add tabindex 0 only to custom controls that are genuinely operable by keyboard.", "Use tabindex -1 for programmatic focus targets such as headings, status containers, and validation summaries that should not be in normal Tab order.", "Remove hidden, collapsed, inert, disabled decorative, or offscreen controls from the sequential focus path.", "Define focus placement and return for dialogs, drawers, sheets, popovers, menus, accordions, route transitions, and async updates.", "Expose visible focus styles for all interactive controls and verify they are not clipped, covered, or color-only.", "Test with keyboard only, Shift+Tab, screen readers, switch control, browser zoom, mobile hardware keyboards, responsive breakpoints, virtualization, and JavaScript failure paths." ], "commonMisuses": [ "Using positive tabindex values to force a visual order instead of fixing DOM order.", "Suppressing outline or focus ring without an equivalent visible indicator.", "Leaving hidden drawers, collapsed panels, or inactive tabs in the tab sequence.", "Moving focus unexpectedly on hover, scroll, animation, autosave, polling, or non-user-initiated updates.", "Closing overlays without returning focus to the invoker or a meaningful replacement.", "Scrolling visually to content while keyboard focus remains elsewhere.", "Placing noninteractive text, cards, status tags, or decorative wrappers in Tab order.", "Letting virtualized or filtered content remove the focused item without a recovery target." ], "critiqueQuestions": [ "What is the first focus target after page load, route change, failed submit, and successful submit?", "Does forward and reverse Tab order match the user's reading and task order?", "Which elements are hidden, collapsed, disabled, inert, virtualized, or offscreen, and can any still receive focus?", "Where does focus go after opening and closing each overlay or disclosure?", "How do error summaries, inline errors, async status messages, and removed results move or preserve focus?", "Are composite widgets using a declared roving-focus model instead of flooding the page tab sequence?", "Can users always see focus and escape constrained focus regions with the keyboard?" ], "relatedPatterns": [ "keyboard-shortcut", "skip-link", "modal-dialog", "toolbar", "data-grid", "menu-menubar" ], "comparisons": [ "focus-traversal-vs-keyboard-shortcut-vs-skip-link-vs-modal-dialog-vs-toolbar-vs-data-grid" ], "sourceIds": [ "wcag-focus-order", "wcag-focus-visible", "wcag-no-keyboard-trap", "mdn-htmlelement-tabindex" ] }, { "id": "follow-subscribe", "completionStatus": "complete", "name": "Follow / subscribe", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Per-object opt-in control for future updates from a thread, page, channel, space, repository, saved view, or topic", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to stay informed about future changes to selected work without repeatedly revisiting it, but follow and subscribe controls become noisy or untrustworthy when they hide target scope, delivery channel, auto-follow reasons, included events, permission limits, digest timing, or the unsubscribe path.", "solution": "Provide a per-object follow / subscribe control that names the watched target, shows current state and scope, previews included events and delivery destination, explains automatic subscriptions, supports immediate and digest modes, handles permission changes, and keeps unfollow or unsubscribe available from the same context.", "uiGuidance": [ "Render follow or subscribe as a stateful control attached to the specific object being watched, with current state, target scope, delivery destination, event types, auto-follow reason when present, and an unfollow path.", "Distinguish following from mentions, notifications, activity feeds, comments, saved views, and favorites by showing that the user is changing future update delivery for one target rather than sending attention, reading history, writing content, or bookmarking access." ], "uxGuidance": [ "Use follow / subscribe when users want future changes to a specific object, channel, thread, repository, page, space, saved view, or topic to come to them without repeatedly checking it.", "Make subscriptions reversible, scoped, and explainable so users understand why updates arrive, where they arrive, which events are included, and how to stop or narrow noisy delivery." ], "uiExamples": { "good": [ "A thread header shows Following, explains replies will appear in the followed-threads list and Activity feed, and offers Unfollow replies from the same menu.", "A Confluence page watch button says Watching page, separates page watch from space watch, and shows that edits and comments are sent by email or in-app notifications according to user settings." ], "bad": [ "A Subscribe button changes to Subscribed without saying whether the user subscribed to a page, all child pages, a space, email, push, or in-app updates.", "A repository is watched automatically after one comment, but the user only finds the unsubscribe action three screens deep in global settings." ] }, "uxExamples": { "good": [ "A user follows a support thread before leaving for a meeting, receives only new replies in the promised destination, then unfollows when the incident closes.", "A team member watches a project space for onboarding updates, sees that daily digest is active, and switches one critical page to immediate notifications." ], "bad": [ "A user receives a stream of update emails from a space but cannot tell which page, mention, reply, or watch setting caused them.", "A followed saved view keeps sending links after the user loses access to the underlying project." ] }, "problemContext": [ "Products may allow users to follow threads, pages, spaces, channels, repositories, issues, pull requests, saved searches, saved views, calendars, authors, topics, or entire workspaces.", "Subscriptions can be created manually by clicking Follow, Subscribe, or Watch, or automatically when the user replies, is mentioned, creates content, owns an object, joins a team, or changes notification settings.", "Delivery may happen through notification center, activity feed, email, push, desktop banners, digests, followed-thread lists, channel badges, or integrations.", "The same word can mean different scopes across products: watching a page differs from watching a space, following a thread differs from following a channel, and subscribing to a saved view differs from saving it.", "Noisy subscriptions often persist longer than the user's original need, so users need narrow scope, visible reasons, and quick cleanup." ], "selectionRules": [ "Choose follow / subscribe when the user is opting into future update delivery from a specific target.", "Use notification center for the retained inbox where delivered subscription updates are triaged, marked read, filtered, and acted on.", "Use activity feed for broad catch-up across many sources; use follow / subscribe to decide which sources or objects are elevated from that stream.", "Use mentions when another person routes attention to the user inside authored content.", "Use threaded discussion when replies and branches need conversation structure; use follow / subscribe to control future reply delivery.", "Use comments when the user is contributing written feedback; subscribing to comments only controls future comment updates.", "Use saved view when the user stores a filtered surface; add follow / subscribe only when future changes to that view trigger delivery.", "Use settings management for global defaults such as email, push, digest, quiet hours, and channel-level notification behavior.", "Use favorites or pinned items for quick return access without update delivery.", "Show whether the subscription target is one item, one thread, one channel, a page and descendants, a space, a repository, a query, or all matching future items.", "Explain automatic follow reasons such as replied, mentioned, author, assigned, owner, or all-new-posts preference.", "Provide unsubscribe, unfollow, mute, reduce frequency, and delivery-channel controls without forcing users to leave the object context." ], "requiredStates": [ "Not following state.", "Following state.", "Watching broader parent scope state.", "Auto-followed because replied, mentioned, authored, assigned, or created state.", "Pending subscription update state.", "Unfollowed or unsubscribed state.", "Muted or delivery disabled state.", "Delivery destination selection state such as Activity feed, notification center, banner, push, email, or digest.", "Event-type selection state such as all updates, replies only, comments, edits, mentions, releases, or status changes.", "Digest or immediate delivery state.", "Permission-limited or inaccessible target state.", "Deleted, archived, completed, closed, or resolved target state.", "Bulk unsubscribe or manage subscriptions state." ], "interactionContract": [ "Activating Follow, Subscribe, or Watch creates or updates a subscription record for the named target, not merely a visual bookmark.", "The control updates its visible label and selected state only after the product can explain the resulting scope and delivery behavior.", "Users can inspect why they are receiving updates from the object context or notification item, including manual, auto-follow, parent-scope, mention, or preference reasons.", "Unfollow or unsubscribe removes that subscription without deleting the target, comment, notification history, saved view, or favorite.", "Delivery settings separate target scope, event type, channel, frequency, digest, and quiet-mode behavior.", "If access is lost or a target is archived, completed, deleted, or closed, future updates are stopped or downgraded and stale subscriptions become explainable.", "Bulk management pages show enough context to unsubscribe without losing track of which target or scope is being changed." ], "implementationChecklist": [ "Define subscription target types, parent-scope inheritance, event types, delivery channels, frequency, auto-follow triggers, unsubscribe behavior, and cleanup policy.", "Store explicit reason metadata such as manual follow, replied, mentioned, created, assigned, team preference, space watch, repository watch, or saved-view subscription.", "Render per-object state with current label, scope, included events, destination, frequency, and unfollow action.", "Support immediate, digest, muted, paused, and delivery-disabled modes without losing the underlying subscription explanation.", "Synchronize subscriptions with notification center, activity feed, email, push, channel badges, and followed-thread lists.", "Handle permission changes, deleted targets, renamed targets, parent-scope changes, duplicate subscriptions, offline toggles, and bulk unsubscribe safely.", "Test keyboard toggling, menu selection, screen-reader labels, mobile long-press or overflow menus, high-volume subscription lists, digest timing, and cross-device state." ], "commonMisuses": [ "Using Follow as a bookmark with no future update delivery.", "Using Subscribe as a mailing-list opt-in without showing which object or event types are included.", "Hiding Unfollow in global notification settings only.", "Automatically following users without showing why they are receiving updates.", "Treating parent-scope watches and item-level watches as the same state.", "Sending both immediate and digest updates for the same event with no deduplication.", "Keeping subscriptions active after target deletion, archive, permission loss, or issue closure.", "Calling a notification center subscription management page the follow control itself." ], "critiqueQuestions": [ "What exact object, scope, or query does this control subscribe the user to?", "Which future events will produce updates, and where will those updates appear?", "Can the user see why they were automatically subscribed?", "Can the user unfollow, mute, reduce frequency, or change delivery without losing object context?", "How are parent-scope watches, item-level watches, and duplicates resolved?", "What happens when the object is archived, closed, deleted, renamed, or no longer accessible?" ], "relatedPatterns": [ "notification-center", "activity-feed", "mentions", "threaded-discussion", "comments", "settings-management", "saved-view", "permission-denied-state" ], "comparisons": [ "follow-subscribe-vs-notification-center-vs-mentions-vs-activity-feed" ], "sourceIds": [ "github-notifications-subscriptions", "github-managing-subscriptions", "atlassian-confluence-watch-content", "atlassian-confluence-manage-watchers", "slack-thread-notifications", "slack-conversation-notification-settings", "microsoft-teams-follow-threads", "microsoft-teams-channel-notifications" ] }, { "id": "full-screen-takeover", "completionStatus": "complete", "name": "Full-screen takeover", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Temporary full-viewport modal task mode", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Some temporary tasks need the whole viewport for focus, capture, dense content, or immersive preview, but ordinary full pages break the return path and compact modals, sheets, or drawers do not provide enough space.", "solution": "Present a full-screen takeover as a named temporary mode with visible exit, internal navigation rules, contained focus, parent-state preservation, unsaved-change protection, and a predictable return to the invoking context.", "uiGuidance": [ "Render a full-screen takeover as a full-viewport modal surface with a visible title, labelled exit control, primary outcome action, and blocked parent content.", "Use layout, top-bar wording, and navigation controls to show that the user is in a temporary mode, not an ordinary page or a partial side surface." ], "uxGuidance": [ "Use the takeover only when full-viewport focus materially improves the temporary task and users must return to the invoking context afterward.", "Make Close, Back, Escape, system back, completion, unsaved-change review, and focus return predictable so users do not lose work or exit the wrong level." ], "uiExamples": { "good": [ "A document scan opens a full-screen capture mode with title Attach receipt, Close, Save scan, internal Review back behavior, and the parent expense row restored after close.", "A media annotation takeover uses the full viewport for zoomed inspection while exposing Done, Cancel, and current item identity." ], "bad": [ "A full-screen layer titled Details hides the page, offers only an X, and behaves differently from browser back.", "A one-field nickname edit takes over the whole screen even though a compact modal or inline edit would fit." ] }, "uxExamples": { "good": [ "A user opens camera capture from an expense row, moves to Review, uses Back to return to Capture, presses Close, sees an unsaved-scan review, keeps editing, saves, and returns to the same row.", "Browser back while dirty opens the same leave-review state as the close button instead of throwing users out of the parent workflow." ], "bad": [ "A user presses the visible X inside a nested takeover and loses the entire product-selection flow rather than only the current detail view.", "Closing the takeover resets the parent search filters and selected record, forcing the user to reconstruct context." ] }, "problemContext": [ "The user starts from a parent page, list, map, editor, object, or setup context that should still be restored after the temporary mode closes.", "The task needs full-viewport space for camera capture, media review, map detail, multi-section setup, dense editing, or focused scanning.", "Background interaction must stop while the takeover is open.", "The takeover can define exact behavior for Close, Back, Escape, system back, route history, unsaved edits, and completion." ], "selectionRules": [ "Choose full-screen takeover when the task is temporary and modal, but needs the whole viewport to be usable.", "Use a modal dialog when the task is compact and does not need full-screen space, internal navigation, or immersive focus.", "Use a sheet when adaptive sizing, edge attachment, partial parent visibility, or detents are part of the interaction.", "Use a drawer or details panel when users need to compare continuously with the parent page.", "Use a full page or single-page form when the task needs its own URL, browser history, saved progress, sharing, or long-form navigation.", "Use a preview panel or full-page preview when the main job is reading or inspecting media rather than completing a temporary task.", "Use alert dialog or confirmation dialog for urgent decisions and high-consequence review rather than expanding a tiny decision to full screen.", "Do not stack full-screen takeovers; route nested content to an internal step, page, sheet, or separate flow with clear navigation.", "Do not make Close, Back, browser back, Escape, and gesture dismissal disagree about whether they leave the takeover or move one level up.", "Protect unsaved work on every exit route, including close button, system back, browser back, Escape, refresh, and gesture dismissal." ], "requiredStates": [ "Closed parent state with the selected object, filters, scroll, and opener visible.", "Opening state that moves focus into the takeover title, first field, camera control, or main task start.", "Open takeover state with full-viewport layout, task title, exit control, primary action, and blocked parent content.", "Internal step or subview state when Back means previous takeover step rather than leaving the entire mode.", "Dirty state when edits, uploads, captures, or selections inside the takeover are not saved.", "Exit-review state when a dismissal route would discard unsaved work.", "Completed state that closes or navigates intentionally and reports what changed.", "Dismissed state that restores focus and parent-page state to the opener or relevant object.", "Responsive and orientation-change state that keeps actions, title, and exit controls reachable." ], "interactionContract": [ "The opener communicates the object or task that will enter a full-screen temporary mode.", "Opening the takeover blocks parent-page pointer and keyboard interaction and places focus inside the takeover.", "The top area includes a clear title and a labelled Close, Exit, Done, or Back control according to the current navigation depth.", "Internal Back returns to the previous takeover view when one exists; Close or Exit leaves the takeover and returns to the parent context.", "Primary completion actions use outcome-specific labels such as Save scan, Attach photo, or Finish setup.", "Escape, browser back, phone back, close button, and gesture dismissal follow the same unsaved-change rule.", "Completion, cancellation, and dismissal preserve or intentionally update the parent selection, scroll, filters, and draft context.", "The takeover avoids nested overlay stacks and routes secondary help, pickers, or confirmations through clear inline or child-surface behavior." ], "implementationChecklist": [ "Define why the task needs the entire viewport and what parent context must be restored afterward.", "Name the takeover with a visible heading and expose it as the modal surface name.", "Provide labelled exit controls and distinguish internal Back from leaving the takeover.", "Make background content inert while the takeover is open and contain focus when implemented as a modal layer.", "Track unsaved edits, captures, selected media, uploads, and partial setup progress.", "Send every exit route through the same save, discard, or continue decision when work is dirty.", "Preserve opener focus, parent scroll, selected object, filters, and drafts on cancel or close.", "Decide whether completion closes back to the parent, moves to a result page, or leaves a receipt state.", "Test keyboard, screen reader, phone back, browser back, Escape, gestures, orientation change, zoom, safe areas, and refresh recovery." ], "commonMisuses": [ "Using a full-screen takeover as a dramatic wrapper for a short confirmation, single text field, or routine message.", "Making the takeover look like a normal page while route history and browser back behave like an overlay.", "Providing both Back and Close controls that exit different amounts of the flow without clear labels.", "Stacking another full-screen overlay, sheet, or browser inside the takeover.", "Discarding scans, uploads, or edits when users press Escape, system back, or browser back.", "Closing the takeover and resetting the parent list, filters, selected object, or scroll position.", "Leaving parent controls focusable or clickable behind the full-screen surface." ], "critiqueQuestions": [ "What capability requires the entire viewport instead of a compact modal, sheet, drawer, or page?", "Is this a temporary mode that returns to a parent context, or should it be a normal route?", "What does Back mean inside the takeover, and how is that different from Close or Exit?", "Which parent state must be preserved after cancel, close, save, and system back?", "What unsaved work can exist, and do all dismissal routes protect it consistently?", "Could stacking or ambiguous close controls cause users to lose work or leave the wrong level?" ], "relatedPatterns": [ "modal-dialog", "sheet", "drawer", "single-page-form", "wizard", "preview-panel", "confirmation-page", "alert-dialog", "confirmation-dialog" ], "comparisons": [ "full-screen-takeover-vs-modal-dialog-vs-sheet-vs-single-page-form" ], "sourceIds": [ "material-full-screen-dialog", "apple-hig-modality", "wai-aria-apg-dialog-modal", "fluent-dialog-component", "nng-accidental-overlay-dismissal" ] }, { "id": "global-navigation", "completionStatus": "complete", "name": "Global navigation", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Persistent top-level navigation shell", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need a stable way to understand where they are and move between the most important product, site, or service sections without losing orientation.", "solution": "Provide persistent, scoped top-level navigation that names the product or service, shows the current section, separates utility actions, and adapts overflow without hiding the user's place.", "uiGuidance": [ "Render product or service identity, a compact set of top-level destination links, current-section state, separate utility controls, and responsive overflow behavior.", "Keep global navigation visually persistent and higher in hierarchy than breadcrumbs, local side navigation, tabs, and page-specific actions." ], "uxGuidance": [ "Help users move between major product or service areas while preserving orientation, local state, and confidence that they are in the right service.", "Use global navigation only for non-linear, repeated top-level movement; simplify the journey or use task progress patterns when users should complete an ordered flow." ], "uiExamples": { "good": [ "A header shows the product name, Dashboard, Projects, Reports, Billing, a More overflow, and separate Help and account controls.", "The active destination has text and semantic current state, while utility controls sit apart from destination links.", "On narrow screens, hidden product links move into a labeled More menu rather than disappearing." ], "bad": [ "A crowded row mixes every page, account action, language selector, and sign-out link.", "The active link says Reports while the page heading is Billing.", "A hamburger hides all primary destinations on desktop with no visible current section." ] }, "uxExamples": { "good": [ "Users switch from Projects to Reports, return to Projects, and find their project draft count preserved.", "If switching away would discard a task, the route warns or saves state before changing sections.", "Deep-linked users can tell which service they are using and move to another top-level area." ], "bad": [ "Switching top-level sections clears filters or drafts without notice.", "Navigation opens external or utility destinations as if they were service sections.", "A linear application journey includes global links that invite users to abandon required steps." ] }, "problemContext": [ "A product, service, or site has multiple top-level areas that users revisit.", "Users may enter deep links and still need to recognize the service and move to another major area.", "The navigation has to share space with account, search, switcher, language, or other utility controls." ], "selectionRules": [ "Choose global navigation when users need repeated access to a small set of top-level product or service sections.", "Keep the link set limited to the most useful top-level destinations; global navigation is not a site map.", "Show a clear current section that remains synchronized with page content and route changes.", "Separate product or service navigation from account, help, search, language, switcher, sign-out, and other utility controls.", "Use responsive overflow, drawer, side panel, or bottom navigation behavior only when the same top-level destinations remain discoverable and current state remains clear.", "Avoid global navigation in a strictly linear transaction where task list, step navigation, or page-level links better preserve the journey." ], "requiredStates": [ "Default state with product or service identity and top-level links.", "Current section state that matches the page or route.", "Overflow or narrow viewport state where hidden links remain reachable.", "Utility state for account, help, search, language, or switcher controls separated from main links.", "External-link state with warning or grouping when navigation leaves the service.", "State-preserved return after switching away and back to a section." ], "interactionContract": [ "Activating a global navigation item changes to the named top-level section and updates current-state semantics.", "The visible navigation state always agrees with the main content heading or route.", "Overflow controls reveal hidden top-level destinations without covering the current page irrecoverably.", "Utility actions do not appear as peer destinations unless they are true top-level sections.", "When switching sections would lose unsaved progress, the UI preserves state, restores state, or warns before leaving.", "Keyboard and screen-reader users can identify the navigation landmark, current section, and overflow state." ], "implementationChecklist": [ "Define the small set of top-level destinations from user tasks, not the organization chart.", "Render global navigation in a labeled navigation landmark with product or service identity nearby.", "Mark the current section using route-driven state and appropriate current-page or current-section semantics.", "Group utility controls separately from primary destinations.", "Design responsive overflow so links move predictably to a menu, drawer, rail, or panel rather than disappearing.", "Preserve or warn about section-specific draft, filter, and scroll state when users pivot across areas.", "Keep breadcrumbs, side navigation, and page-specific links visually subordinate to global navigation." ], "commonMisuses": [ "Listing every page or admin object in the global nav.", "Mixing account settings, sign out, help, and language controls into the same row as product destinations.", "Highlighting a nav item that does not match the displayed content.", "Using a hamburger menu on desktop to hide primary destinations without a strong space or complexity reason.", "Replacing breadcrumbs or local side navigation with global links.", "Losing form drafts, filters, or scroll context when users switch sections and return." ], "critiqueQuestions": [ "Can users identify the product or service and the current top-level section from any page?", "Are these links the most important destinations, or are they a complete site map?", "Are utilities and account actions visually and semantically separated from navigation destinations?", "What happens to the user's local state when they switch sections and come back?" ], "relatedPatterns": [ "breadcrumbs", "bottom-navigation", "tabs", "command-palette" ], "comparisons": [ "global-navigation-vs-breadcrumbs-vs-bottom-navigation" ], "sourceIds": [ "govuk-navigate-service", "carbon-global-header", "uswds-header-component" ] }, { "id": "graceful-degradation", "completionStatus": "complete", "name": "Graceful degradation", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Reduced-capability same-surface experience that preserves the core task", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Modern interfaces often rely on JavaScript, CSS, browser APIs, device sensors, heavy media, third-party widgets, or high network performance, and a single missing layer can block users even when the underlying task has a simpler path.", "solution": "Design the baseline task first, layer enhancements on top, detect unsupported or failed capabilities, expose the reduced-capability state locally, preserve user work, and keep the core submission, selection, reading, or navigation path available whenever it is genuinely possible.", "uiGuidance": [ "Show the baseline controls on the same surface as the failed enhancement: date fields behind a date picker, a location list behind a map, a file input behind drag-and-drop, readable content behind animation, and plain links behind scripted navigation.", "Name the unavailable capability in local status text, then keep the working control, entered values, validation messages, primary action, and saved-work state visible." ], "uxGuidance": [ "Use graceful degradation when a richer layer is unavailable but the user can still complete the core task with a simpler interaction on the current page.", "Separate reduced capability from failure: the enhanced experience may be missing, slower, blocked by policy, unsupported by device, or unavailable through a third party, but the task contract should remain clear and honest." ], "uiExamples": { "good": [ "An appointment date picker says Calendar unavailable, keeps Day, Month, and Year fields with a format hint, and lets users continue after valid entry.", "A branch finder map says Map view unavailable, keeps a searchable list of locations, distance text, and the Select branch action." ], "bad": [ "A failed calendar script leaves an empty rectangle and a disabled Continue button.", "An upload flow requires drag-and-drop and hides the standard file picker from keyboard and touch users." ] }, "uxExamples": { "good": [ "A user on an older browser books an appointment through labeled date fields even though the calendar enhancement never loaded.", "A user blocked from geolocation selects a pickup location from a sorted list without restarting the transaction." ], "bad": [ "A user must enable JavaScript to continue even though the server could accept the same date fields.", "A user loses typed answers when a third-party address widget fails and the page reloads into an error." ] }, "problemContext": [ "The enhanced layer improves convenience, speed, visualization, personalization, or input ergonomics but is not the only way to satisfy the user need.", "Users may have blocked scripts, older browsers, assistive technologies, low-powered devices, strict corporate firewalls, slow networks, disabled motion, missing permissions, or third-party dependencies outside the product team's control.", "The product can submit or complete the core task with ordinary HTML, server validation, text fields, select lists, links, file inputs, static content, or a saved state.", "Some capabilities may be legally, security, or domain required; in those cases the degraded state must explain the blocker rather than pretending the task can continue." ], "selectionRules": [ "Choose graceful degradation when users stay on the same surface and the core task continues with fewer capabilities.", "Prefer baseline controls that are always present in the document or reliably rendered by the server before enhancing them with JavaScript or advanced APIs.", "Use feature detection and dependency health rather than browser labels to decide whether to show enhanced or reduced capability behavior.", "Tell users which capability is unavailable only when it affects their task; avoid alarming technical language for harmless cosmetic loss.", "Keep typed values, selected records, uploaded file names, validation results, references, and saved progress intact while switching between enhanced and reduced modes.", "Allow users to retry or restore the enhancement when it is likely to recover, but do not make retrying the enhancement block the baseline path.", "Use fallback path when the user must switch to another channel or method outside the current surface.", "Use offline state when connectivity loss changes what can be cached, saved locally, queued, or synced.", "Use service unavailable page only when the whole service or transaction route is unavailable, not for a single degraded component.", "If no core path exists, state that honestly, explain why the missing capability is required, save work when possible, and provide the next accountable route." ], "requiredStates": [ "Enhanced available state with the richer control active.", "Reduced-capability state naming the unavailable enhancement.", "Core path available state with baseline controls and primary action enabled.", "Unsupported browser or device capability state.", "JavaScript unavailable or failed enhancement state.", "Third-party dependency degraded state.", "Heavy media, animation, or low-power reduced state.", "Restore or retry enhancement state that does not erase baseline input.", "Saved-work state when capability changes after user input.", "No core path state explaining why completion is blocked and what accountable route remains." ], "interactionContract": [ "The baseline path can complete the same core task or the interface explicitly says why it cannot.", "Enhanced controls mirror their values into baseline controls or share a canonical value so switching modes does not lose work.", "Unavailable capability messages sit next to the affected feature and do not replace the whole page when the rest of the task remains usable.", "The primary action stays enabled when baseline values are valid and only the enhancement is missing.", "Retry enhancement, enable permission, use baseline controls, save work, and contact support are distinct actions with distinct outcomes.", "Reduced mode does not fake success, hide validation, submit partial data, or change eligibility without telling the user." ], "implementationChecklist": [ "Define the core task independently from enhancement layers, including minimum input, validation, submit, review, and confirmation requirements.", "Render semantic HTML controls, links, labels, hints, and server validation before JavaScript enhancement attaches richer behavior.", "Map each enhancement dependency to a reduced-capability behavior: calendar to date fields, map to list, drag-and-drop to file input, geolocation to manual search, animation to static content, and widget to direct form fields.", "Add feature detection, timeout handling, dependency error handling, and low-power or reduced-motion checks before enabling enhanced-only controls.", "Preserve canonical values across enhancement failure, restore, reload, browser back, permission denial, and third-party outage.", "Write local status copy that names the affected capability and the working core path without exposing unnecessary implementation detail.", "Test with JavaScript disabled, CSS partially failed, unsupported APIs, blocked third-party scripts, older browsers, keyboard-only input, screen readers, touch devices, reduced motion, slow network, and low memory.", "Instrument degraded-mode entry, successful core completion, enhancement restore, blocked completion, and support handoff so owners see whether an enhancement is harming task completion." ], "commonMisuses": [ "Treating JavaScript as mandatory for form submission when server-validated fields could submit the task.", "Leaving a blank widget, spinner, disabled button, or invisible error when an enhancement fails.", "Hiding baseline controls after enhancement loads, then failing to restore them when the enhanced layer breaks.", "Calling a separate support route graceful degradation instead of identifying it as a fallback path.", "Using browser sniffing rather than feature detection and real capability checks.", "Discarding user input when moving between enhanced and reduced modes.", "Claiming completion succeeded when the degraded mode omitted required data." ], "critiqueQuestions": [ "What is the smallest working version of this task before enhancements are added?", "Which enhancement dependencies can fail independently, and what remains usable when each one fails?", "Can users complete the same outcome with baseline controls, or does the product need a named fallback path?", "What data must be preserved when enhancement state changes after the user has already interacted?", "Does the UI distinguish unsupported capability, denied permission, slow dependency, offline mode, and whole-service outage?", "How will owners know whether degraded-mode users still complete the task?" ], "relatedPatterns": [ "fallback-path", "offline-state", "service-unavailable-page", "retry", "error-state", "drag-and-drop-upload", "date-picker", "file-upload" ], "comparisons": [ "graceful-degradation-vs-fallback-path-vs-offline-state-vs-service-unavailable-page" ], "sourceIds": [ "govuk-progressive-enhancement", "govuk-design-system-accessibility-strategy", "mdn-graceful-degradation", "mdn-progressive-enhancement", "w3c-wcag-client-side-scripting-techniques" ] }, { "id": "handoff-summary", "completionStatus": "complete", "name": "Handoff summary", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Concise transfer packet for responsibility, conversation, case, or task context", "maturity": "established", "platforms": [ "web", "desktop", "mobile", "ai" ], "problem": "Transfers fail when the receiver gets only an assignment, notification, transcript, or link and must reconstruct status, previous attempts, unresolved questions, risks, and next steps under time pressure.", "solution": "Provide a structured handoff summary that packages the current state, history highlights, receiver role, open work, urgency, risks, source links, privacy boundaries, freshness, and confirmation behavior at the moment responsibility or context changes hands.", "uiGuidance": [ "Render handoff summary as a transfer packet that names sender, receiver, transfer reason, current status, source object, generated or updated time, summary structure, next action owner, urgency, risks, and links back to transcript, ticket, log, case, or source records.", "Separate handoff summary from assignment, summary box, activity log, comments, notifications, approvals, review queues, share dialogs, and permission-denied states by showing that a new receiver is taking over with enough context to continue safely." ], "uxGuidance": [ "Use handoff summary when work, responsibility, or conversation context moves between people, teams, shifts, AI agents, live agents, queues, or tools and the receiver should not need to reconstruct the situation from raw history.", "Make the transfer trustworthy by exposing what is known, what is unresolved, what was attempted, what the receiver must do next, which facts came from source records, what is stale or generated, and which details are hidden by permission or policy." ], "uiExamples": { "good": [ "A support conversation handoff shows customer, issue, AI steps already attempted, account status, reason for escalation, current sentiment, open question, next action, queue, owner, and source transcript link.", "A shift handoff card uses Situation, Background, Assessment, Recommendation, action owner, deadline, contingency, and confirmation controls before transferring responsibility." ], "bad": [ "A ticket says Transferred to Billing with no reason, customer need, previous attempts, blockers, or next action.", "A generated summary says Everything is handled without source links, timestamp, confidence, omissions, or handoff owner." ] }, "uxExamples": { "good": [ "A live agent accepts a bot escalation, reads the handoff summary, sees the customer already tried password reset twice, confirms the account lock risk, and continues without asking the customer to repeat themselves.", "A night-shift operator accepts a case handoff, checks open tasks and contingency notes, asks one clarification question, and confirms responsibility." ], "bad": [ "A receiver gets an assignment notification and must read 80 chat messages to learn why the customer is blocked.", "A handoff summary omits that the account has restricted billing access, so the new owner asks for information they are not allowed to view." ] }, "problemContext": [ "Handoffs can occur between AI and human agents, support representatives, shifts, reviewers, incident commanders, queues, supervisors, care teams, departments, or tools.", "The sender may be a person, automation, bot, AI agent, previous shift, reviewer, triager, or supervisor.", "The receiver needs enough context to act without rereading every message, but also needs access to source transcript, ticket, case, log, attachment, or timeline evidence.", "Some facts may be generated, stale, disputed, redacted, confidential, unavailable, or outside the receiver's permission scope.", "A handoff can be warm, cold, live, asynchronous, temporary, permanent, escalated, declined, reassigned, or handed back." ], "selectionRules": [ "Choose handoff summary when the user's task is to take over work or continue a conversation, case, incident, ticket, patient, workflow, or agent session from someone or something else.", "Use assignment when the primary action is only selecting the accountable owner; add handoff summary when the new owner needs context to continue.", "Use summary box when summarizing a long page for the same reader, not transferring responsibility to a receiver.", "Use activity log when the task is audit or investigation of historical events, not concise operational continuation.", "Use comments when collaborators are discussing details; handoff summary should extract the current state and next action from those details.", "Use notification center when users need to be alerted that a handoff occurred, but link to the summary for actual context.", "Use approval workflow when the receiver must approve or reject a request under route rules, not simply take over context.", "Use review queue when reviewers choose among many items; handoff summary is item-level context for one transferred item.", "Show sender, receiver, transfer reason, source object, generated time, last updated time, current status, urgency, risks, and next owner before the receiver accepts.", "Use structured sections such as Situation, Background, Assessment, Recommendation, action list, open questions, blockers, and source links rather than a vague paragraph.", "Label generated, edited, stale, redacted, permission-limited, and unverified facts.", "Provide accept, ask clarification, update summary, decline, reassign, hand back, or confirm-responsibility behavior when the workflow requires an explicit transfer." ], "requiredStates": [ "Default handoff summary with sender, receiver, reason, status, and source object.", "AI-to-human conversation handoff with transcript link, collected variables, attempted steps, and escalation reason.", "Human-to-human shift or case handoff with open tasks, deadlines, and contingency notes.", "Generated summary state with timestamp, source coverage, and edit or regenerate affordance.", "Receiver accepted and responsibility confirmed state.", "Clarification requested state before accepting ownership.", "Declined, reassigned, or handed-back state.", "Stale summary state after source transcript, ticket, case, or activity changed.", "Missing source, redacted, or permission-limited summary state.", "Long transcript condensed state with source links and omitted-details warning.", "Mobile condensed handoff card state.", "Failed summary generation or failed transfer retry state." ], "interactionContract": [ "A handoff summary is tied to a named source object and transfer event, not an orphan note.", "The receiver can identify who or what is handing off, why, what is currently true, what remains unresolved, and what action is expected next.", "Source links open the exact conversation, ticket, case, log event, attachment, or timeline section behind each major claim.", "Generated summaries disclose generated time, source coverage, and whether a person edited or confirmed them.", "Accepting a handoff updates responsibility, queue, notification, activity, and status surfaces according to the product model.", "Declining, reassigning, or handing back preserves the summary and reason so context does not disappear.", "Stale source data marks the summary stale and prompts refresh or review before acceptance.", "Permission-limited receivers see redaction reasons and request-access or route-recovery options instead of leaked content.", "After accept, decline, clarify, or refresh, focus stays near the status change or next required action." ], "implementationChecklist": [ "Define the handoff record: source object, sender, receiver, route, reason, transfer type, current status, summary sections, generated time, source coverage, next action, risk, permissions, and acceptance state.", "Separate handoff summary data from assignment fields, notification records, comments, activity logs, transcript storage, approval records, and static page summaries.", "Design structured sections for situation, background, assessment, recommendation or request, attempted steps, open questions, action list, blockers, risks, deadlines, source links, and receiver confirmation.", "Implement accept, ask clarification, edit summary, refresh, regenerate, decline, reassign, hand back, copy summary, and source-open actions where the workflow allows them.", "Check source freshness and access before showing or accepting the summary.", "Represent generated, human-edited, stale, redacted, missing-source, failed-generation, failed-transfer, and partial-source states.", "Synchronize acceptance with assignment, queues, notifications, activity log, case status, and conversation first-responder state.", "Test long transcripts, sensitive data redaction, AI hallucination guardrails, missing attachments, mobile wrapping, high zoom, keyboard action order, screen reader section headings, and handoff across teams with different permissions." ], "commonMisuses": [ "Sending only an assignment notification and calling it a handoff.", "Dumping the full transcript without current status, next action, or risk summary.", "Using an ordinary page summary instead of transfer-specific receiver context.", "Omitting who owns the next action after handoff.", "Showing generated summaries as verified facts without source links or freshness.", "Leaking confidential transcript, account, patient, or case details across permission boundaries.", "Letting summaries go stale after the underlying conversation or case changes.", "Failing to provide a way for the receiver to clarify, decline, or hand back." ], "critiqueQuestions": [ "Who or what is handing off, who receives it, and what responsibility changes?", "Can the receiver understand current status, prior attempts, open questions, blockers, risks, and next action without rereading the raw history?", "Which summary claims link to transcript, ticket, case, log, or attachment evidence?", "Is the summary generated, edited, stale, redacted, or permission-limited, and is that visible?", "What happens if the receiver declines, needs clarification, lacks access, or hands the item back?", "Would assignment, summary box, activity log, comments, notification center, approval workflow, review queue, share dialog, or permission-denied state better own this surface?" ], "relatedPatterns": [ "assignment", "summary-box", "activity-log", "comments", "notification-center", "approval-workflow", "review-queue", "share-dialog", "permission-denied-state", "details-panel" ], "comparisons": [ "handoff-summary-vs-assignment-vs-summary-box-vs-activity-log" ], "sourceIds": [ "microsoft-copilot-studio-live-agent-handoff", "microsoft-dynamics-copilot-conversation-summaries", "zendesk-conversation-handoff-handback", "ada-zendesk-chat-handoff-transcript-summaries", "ahrq-teamstepps-handoff", "ahrq-teamstepps-sbar" ] }, { "id": "haptic-feedback", "completionStatus": "complete", "name": "Haptic feedback", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Tactile feedback vocabulary for physical interaction events", "maturity": "standard", "platforms": [ "web", "mobile", "desktop", "game" ], "problem": "Tactile feedback can make digital interactions feel immediate and physical, but haptics are hardware-dependent, settings-dependent, platform-specific, easy to overuse, and inaccessible when they carry meaning without visible or audible backup.", "solution": "Create a small, optional haptic vocabulary mapped to meaningful interaction events; check capability and user settings, synchronize effects with visible states, keep patterns brief, suppress repetition, provide reduced or no-hardware alternatives, and never make haptics the only channel for status, errors, warnings, progress, or confirmation.", "uiGuidance": [ "Render haptic feedback as an optional tactile layer attached to visible interaction states, with labels or settings that explain when vibration, impact, selection, warning, or detent effects happen.", "Keep haptic effects short, event-specific, and synchronized with the visual state they reinforce; use visible text, color, motion, or audio alternatives for any information users must understand." ], "uxGuidance": [ "Use haptic feedback when touch can reinforce direct manipulation, action commitment, selection movement, boundary crossing, snap points, warnings, or successful completion without becoming the only feedback channel.", "Design a small semantic haptic vocabulary, respect platform conventions and user settings, suppress repeated effects, and provide no-hardware or reduced-feedback behavior that still leaves the task complete." ], "uiExamples": { "good": [ "A slider gives a light detent when crossing whole-number stops, shows the value visually, and suppresses repeated vibration while the thumb rests on the same stop.", "A drag-and-drop board gives a short impact when an item crosses the valid drop threshold and shows the target highlight at the same moment.", "A payment review gives no haptic during form entry, then a single confirmation tap after the visible success state appears." ], "bad": [ "Every button press uses the same heavy vibration regardless of whether the action selected, warned, failed, or succeeded.", "A validation error only vibrates the device and leaves no field message or recovery path.", "A long upload vibrates repeatedly as fake progress instead of showing measurable progress and cancel controls." ] }, "uxExamples": { "good": [ "A user drags a reorder handle and feels one detent at each valid slot while the row preview and insertion marker move visibly.", "A user attempts a destructive swipe, feels a warning pulse at the commit threshold, sees Delete revealed, and can cancel before release.", "A user has vibration disabled; the same interaction still shows pressed, threshold, success, and error states visually." ], "bad": [ "A user cannot tell whether a pulse means success or failure because the same pattern plays for all outcomes.", "A user in a quiet meeting gets repeated vibration from decorative hover-like effects.", "A user with motor sensitivity cannot reduce or disable intense haptic patterns." ] }, "problemContext": [ "The product runs on touch, game, wearable, mobile, web, or controller hardware where tactile output may be available.", "Haptic events may reinforce button press, selection movement, snap detent, drag threshold, boundary hit, refresh, success, warning, failed gesture, destructive commit, notification, or game event.", "Users may disable vibration, use assistive technology, hold the device on a table, use desktop hardware, have reduced-motion or sensory preferences, be in quiet contexts, or use unsupported browsers.", "Haptic feedback is adjacent to touch gesture, toast notification, error state, confirmation dialog, progress bar, notification preferences, and sound or motion feedback." ], "selectionRules": [ "Choose haptic feedback when the tactile effect reinforces a visible interaction milestone and improves physical confidence without carrying required information alone.", "Use touch gesture when the main design question is how input is recognized, thresholded, canceled, or made equivalent through controls.", "Use toast notification when a short visible message, undo, or status copy is needed after an action.", "Use error state when users need persistent explanation and recovery; haptics may draw attention but cannot replace visible errors.", "Use confirmation dialog when users must explicitly review and choose before risk; haptics can follow final commit but not replace the decision.", "Use progress bar when duration or percent complete matters; do not use repeated vibration as progress indication.", "Map haptic intensity and pattern to semantic weight: selection and detents should be lighter than warnings or destructive commits.", "Respect system settings and product preferences for vibration, haptics, reduced motion, notification mode, and quiet hours.", "Provide no-hardware and no-permission behavior for web and desktop environments where vibration is unavailable or ignored.", "Avoid haptics for decorative delight, passive page load, hover-only interactions, repeated errors, long waits, or background events users did not initiate." ], "requiredStates": [ "Capability unavailable, unsupported browser, no vibration hardware, or no controller rumble state.", "User haptics disabled, reduced feedback, notification silence, or battery-sensitive state.", "Light press or button down feedback state.", "Selection changed feedback state.", "Drag threshold reached state.", "Snap detent or boundary reached state.", "Invalid gesture, blocked movement, or limit reached state.", "Success or completion feedback state.", "Warning or recoverable-risk feedback state.", "Error reinforcement state paired with visible recovery.", "Destructive commit feedback state after explicit confirmation.", "Repeated-effect suppression or debounce state.", "Cancel current vibration or stop pattern state.", "No-hardware fallback state with visible and audible alternatives.", "Web vibration pattern state with duration and cancellation limits.", "Preference preview and test feedback state.", "Privacy or quiet-context state where vibration is suppressed." ], "interactionContract": [ "A haptic effect plays only for a user-relevant interaction event and stays synchronized with the visible state change it reinforces.", "Users can complete and understand the task when haptics are unavailable, disabled, delayed, unsupported, or suppressed.", "The same haptic pattern does not mean conflicting outcomes such as success and failure.", "Repeated gestures, loops, long waits, and animation frames do not create continuous or fatiguing vibration unless the user explicitly opted into a game/controller effect.", "Warning, error, destructive, and payment-related haptics are paired with visible copy and controls.", "Settings and platform conventions decide whether haptics are enabled, reduced, previewed, or suppressed." ], "implementationChecklist": [ "Inventory all candidate tactile events and remove decorative, redundant, background, or high-frequency effects.", "Define a semantic vocabulary for light tap, selection, detent, threshold, success, warning, error reinforcement, and destructive commit.", "Check platform support and use platform-predefined effects where available before custom vibration patterns.", "Respect user and system settings for haptics, vibration, reduced motion, notification focus, battery saver, and accessibility preferences.", "Synchronize tactile output with visible state changes, not delayed network responses unless the visible state also changes then.", "Debounce repeated effects during drag, scroll, slider, game loop, and validation states.", "Provide visible text, live status, audio, animation, or control state alternatives for every haptic meaning.", "Test unsupported hardware, disabled haptics, reduced settings, long press, drag thresholds, boundary hits, repeated errors, keyboard use, screen readers, and quiet contexts." ], "commonMisuses": [ "Using haptics as the only error, warning, or success message.", "Playing the same strong vibration for every tap and outcome.", "Looping vibration during progress, loading, or background work.", "Ignoring system haptic or vibration preferences.", "Adding decorative pulses that are not tied to interaction meaning.", "Assuming web vibration works on every browser and desktop device.", "Playing warning haptics before users understand the visible consequence." ], "critiqueQuestions": [ "What exact event does each haptic represent, and is that event visible at the same time?", "Can users distinguish selection, threshold, warning, success, and error effects without overloading memory?", "What happens when hardware, browser support, system settings, battery saver, or preferences suppress haptics?", "Is any required information communicated only through touch?", "Are repeated effects debounced during dragging, scrolling, validation, loading, or game loops?", "Is this really haptic feedback, or does touch gesture, toast notification, error state, confirmation dialog, or progress bar own the main problem?" ], "relatedPatterns": [ "touch-gesture", "toast-notification", "error-state", "confirmation-dialog", "progress-bar", "notification-preferences" ], "comparisons": [ "haptic-feedback-vs-touch-gesture-vs-toast-notification-vs-error-state-vs-confirmation-dialog-vs-progress-bar" ], "sourceIds": [ "mdn-vibration-api", "w3c-vibration-api", "android-haptics-principles", "android-haptic-feedback-events", "apple-hig-playing-haptics", "apple-hig-feedback" ] }, { "id": "header", "completionStatus": "complete", "name": "Header / top app bar", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Current-view top bar with title, navigation affordance, actions, and overflow", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to know which screen or view they are in and need fast access to the few navigation and action controls that apply to that current view.", "solution": "Place a consistent top bar above the content that names the current view, gives the correct leading navigation affordance, exposes the highest-priority current-view actions, and moves secondary commands into an accessible overflow.", "uiGuidance": [ "Render a top surface that clearly identifies the current view, provides one leading navigation affordance when needed, exposes a small number of view-level actions, and groups secondary actions behind a labeled overflow control.", "Keep title, leading control, primary action, overflow, and scroll behavior stable enough that users can predict what the bar controls on every screen." ], "uxGuidance": [ "Use the header/top app bar to orient users inside the current view and make the most important safe commands reachable without confusing them with global destinations.", "When selection, search, or editing changes the command set, switch to an explicit contextual bar and provide a clear way back to the normal title/actions." ], "uiExamples": { "good": [ "A project detail screen shows Back, Project Apollo, Search, Share, and a More menu for secondary commands.", "Selecting rows changes the bar to 3 selected with Archive, Move, and Clear selection actions.", "On scroll, a large title collapses to a compact title while the back affordance and critical action remain reachable." ], "bad": [ "A header shows the app brand, five section links, account settings, export, delete, help, and sign out in one row.", "The title says Reports while the content is Billing and the primary action still exports the previous screen.", "The overflow menu contains the only way to save or recover, but the More icon has no label or predictable grouping." ] }, "uxExamples": { "good": [ "Users switch from Details to Files and the title and primary action change together from Share to Upload.", "Opening More reveals secondary view commands without hiding the current title or back affordance.", "Entering selection mode changes the bar label and actions, then Clear selection restores the original view bar." ], "bad": [ "The same Save icon appears in the header on screens where it saves, exports, or opens settings.", "A scroll-collapsing header hides the back control and leaves users trapped deep in a hierarchy.", "A toolbar is used as primary app navigation, so users cannot tell whether buttons are destinations or actions." ] }, "problemContext": [ "The product has deep screens where brand-level navigation alone does not explain the current view.", "Users need a small set of actions that act on the current view or selected content.", "The same app shell may need normal, search, selection, edit, and narrow-width header states." ], "selectionRules": [ "Choose a header/top app bar when each screen needs a current title plus view-level actions such as search, share, edit, save, or overflow.", "Use a leading back, close, menu, or drawer button only when that affordance matches the current navigation structure and will behave consistently.", "Limit visible actions to the most frequent, safe, and screen-specific commands; move lower-priority commands to overflow.", "Use a contextual top app bar when selection or editing changes the available command set for the current content.", "Keep global section links, account utilities, and site-wide navigation visually separate unless the design system explicitly defines a combined shell header.", "Use tabs, segmented controls, side navigation, or global navigation instead when the main job is switching destinations or sibling content rather than acting on the current view." ], "requiredStates": [ "Default state with current view title and correct leading affordance.", "Primary action state with one to three visible current-view commands.", "Overflow open state with secondary commands grouped and keyboard reachable.", "Contextual selection or edit state with changed title and changed command set.", "Narrow viewport state where actions collapse without losing critical navigation.", "Scrolled, sticky, or collapsed state that preserves orientation and recovery." ], "interactionContract": [ "The title in the bar must match the rendered content or current route.", "The leading affordance must have one predictable meaning within the current navigation level.", "Visible actions must operate on the current view or current selection, not a previous screen.", "Overflow opens a menu of secondary commands, returns focus to its trigger when closed, and does not hide critical recovery.", "Entering contextual mode changes the bar label and actions; leaving contextual mode restores the previous title and actions.", "If the bar sticks, collapses, or scrolls away, users still have an obvious way to identify the view and recover navigation." ], "implementationChecklist": [ "Derive the title and leading affordance from route or navigation state rather than static header copy.", "Inventory view-level commands and rank them before deciding which actions are visible versus overflowed.", "Give icon-only actions accessible names and visible labels where the meaning is not universally obvious.", "Implement overflow as a keyboard-accessible menu with Escape dismissal and focus return.", "Define responsive rules for which actions collapse, which remain visible, and how contextual mode behaves.", "Test route changes, scroll collapse, selection mode, and narrow widths for title/action synchronization.", "Keep account, help, product switcher, and global destinations outside the current-view action group." ], "commonMisuses": [ "Using the top app bar as a dumping ground for every global destination and account utility.", "Showing stale titles or actions after route changes.", "Putting destructive or rare commands as unlabeled visible icons.", "Changing the meaning of the leading icon between back, menu, and close without clear context.", "Hiding save, cancel, back, or recovery actions in overflow when they are essential to the current task.", "Duplicating the same destinations in a global nav row, top app bar, and bottom navigation." ], "critiqueQuestions": [ "Does the title in the bar exactly match the current screen or selected mode?", "Which visible actions are truly frequent and specific to this view?", "Can users predict what the leading icon will do before activating it?", "What happens to title and actions when content scrolls, selection mode starts, or the viewport narrows?", "Are global destinations and account utilities separated from current-view commands?" ], "relatedPatterns": [ "global-navigation", "bottom-navigation", "tabs", "command-palette" ], "comparisons": [ "header-vs-global-navigation-vs-bottom-navigation" ], "sourceIds": [ "material-top-app-bar", "android-compose-app-bars", "carbon-global-header", "apple-hig-toolbars" ] }, { "id": "hidden-destructive-account-deletion", "completionStatus": "complete", "name": "Hidden destructive account deletion", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Anti-pattern where account deletion or associated data erasure is hidden, disguised, obstructed, or committed without a fair account-level review", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Account deletion becomes deceptive or unsafe when the product hides the deletion path, substitutes deactivation or export, requires vague support contact without status, omits a web route after uninstall, or commits account-level destruction without naming account identity, affected data, retained data, billing, linked apps, and recovery limits.", "solution": "Flag hidden destructive account deletion as an anti-pattern, then rebuild the route as a discoverable account-deletion workflow with direct entry points, account identity, data and service scope, export-before-delete, retained-data disclosure, billing and linked-app warnings, verification, deliberate confirmation, receipt, status, and truthful recovery or cancellation windows.", "uiGuidance": [ "Do not hide Delete account behind FAQ search, support email, unrelated privacy copy, tiny footer links, inactive controls, deactivation labels, or data-export screens when users need an account deletion route.", "Replace hidden destructive account deletion with a direct account-control entry point that names the account, deleted data, retained data, billing and linked-app effects, export-first route, verification gate, request status, and recovery or cancellation window." ], "uxGuidance": [ "Treat concealed or disguised account deletion as an anti-pattern because it blocks users from closing an identity-bearing account and understanding what happens to associated personal data.", "Design the corrected flow so users can find deletion before and after uninstall, distinguish it from deactivation/export/sign-out, review account scope, verify identity, submit deliberately, and track completion or refusal." ], "uiExamples": { "good": [ "Account settings contains a visible Delete account entry that opens a review naming maya.chen@example.com, affected services, data categories, retained records, linked apps, billing, export first, and the request status.", "A public web deletion page lets an uninstalled mobile-app user sign in, request deletion, see retained-data exceptions, and receive a request ID.", "A regulated product explains why deletion needs assisted identity review, shows case status, expected timing, data scope, retained records, and the support owner." ], "bad": [ "The app offers only Deactivate account and keeps profile data, tokens, messages, and personal data active.", "Delete account is hidden in a privacy policy paragraph and cannot be reached from account settings.", "A data export page is presented as the deletion route, but downloading data does not close the account or erase source records." ] }, "uxExamples": { "good": [ "A user finds Delete account from settings, downloads data, verifies identity, reviews retained invoices and linked apps, submits deletion, and later checks request status.", "A user uninstalls the app, opens the developer's web deletion resource, signs in, requests account and associated data deletion, and receives a receipt by email.", "A user cannot self-delete an enterprise-managed account, sees the admin owner and policy reason, and submits the correct request rather than emailing an unknown inbox." ], "bad": [ "A user searches settings for deletion, finds only Sign out and Deactivate, and leaves personal data in the service because the deletion path is concealed.", "A user clicks Delete from a low-level settings row without seeing which account, data, subscription, linked apps, or retention rules are affected.", "A user downloads their data believing the source account is deleted, then receives billing and login notifications later." ] }, "problemContext": [ "The product lets users create or authenticate an account that owns personal data, app data, profile data, messages, files, subscriptions, linked apps, child-account data, enterprise memberships, or authentication tokens.", "The deletion route may be hidden in support, legal copy, app-store disclosures, search, account deactivation, data export, privacy settings, or a disabled control.", "Users may attempt deletion after uninstall, while signed into the wrong account, while managing a child or enterprise account, or while a subscription, legal hold, fraud review, or billing dependency is active.", "The organization may be required to provide direct deletion initiation or a trackable erasure request, so the interface must prove that account deletion was reachable and not disguised as another task." ], "selectionRules": [ "Flag this anti-pattern when users can create an account but cannot find a direct account deletion or erasure request path from account settings, app settings, or the required public web resource.", "Flag it when the only visible path is Deactivate, Disable, Sign out, Remove from device, Unsubscribe, Download data, Contact support, or Delete service even though users need account-level deletion.", "Flag it when deletion is visually hidden, delayed by unnecessary screens, searchable only by exact terms, buried below unrelated preferences, or made unavailable after app uninstall.", "Flag it when an account-level destructive action can commit without account identity, affected data, retained data, billing, linked apps, export-first option, recovery window, or request status.", "Use delete account for the corrected account closure and associated data deletion workflow.", "Use destructive action confirmation for one object, subscription, key, file, project, or workspace delete rather than an account and personal-data lifecycle.", "Use typed confirmation as an added wrong-account gate inside a corrected deletion flow, not as a substitute for discoverability or data-scope review.", "Use data export when users need a copy before deletion; export does not itself close the account or erase source data.", "Use privacy settings or settings management when users adjust account controls that keep the account active." ], "requiredStates": [ "Hidden settings state where Delete account is absent or buried behind unrelated privacy/support copy.", "Deactivation-only state where login is disabled but account record and associated data remain.", "Support-only state with no direct request URL, expected timing, identity status, case ID, or receipt.", "Export-confusion state where Download data is presented as if it deletes source data.", "Uninstall trap state where users must reinstall the app to request deletion.", "Wrong-account risk state where deletion does not name the signed-in email, provider, workspace, or child account.", "Low-friction destructive commit state where a small setting row deletes the account without review.", "Retention-hidden state where backups, invoices, fraud logs, public posts, recipient copies, or legal holds are not disclosed.", "Subscription surprise state where billing, app-store renewal, entitlement, or workspace ownership is not handled.", "Corrected discoverable entry state with a direct Delete account path.", "Corrected account-scope review state with account identity, deleted data, retained data, linked apps, billing, export, verification, request status, and recovery window.", "Corrected web deletion resource state that works after uninstall." ], "interactionContract": [ "Users can reach account deletion from account settings or an equivalent account-control route without needing exact support-search terms.", "A public or web deletion route exists when users may need to request deletion after uninstall or outside the native app.", "The UI never substitutes deactivation, sign out, export, unsubscribe, or remove-from-device for account deletion.", "The destructive account-level review names the exact account before any request is submitted.", "Deletion cannot commit until users can review account data scope, retained data, billing and linked-app effects, verification, and recovery or cancellation limits.", "Support-required deletion states include reason, owner or route, expected timing, status, case ID, and what data will be reviewed.", "Export-before-delete is offered as a separate optional step and does not imply erasure of source data.", "The submitted deletion or erasure request produces durable status, receipt, or notification rather than disappearing into a hidden queue." ], "implementationChecklist": [ "Inventory account creation routes, account settings, app settings, uninstall support paths, public web resources, support queues, data export pages, deactivation controls, and privacy settings.", "Trace whether a user can request deletion from each supported platform and after uninstall without contacting an unrelated support channel.", "Replace hidden, deactivation-only, export-only, or support-only routes with a direct deletion path or a trackable support-required deletion request.", "Show account identity, affected services, associated data, retained data, subscriptions, linked apps, export-first option, verification, typed confirmation, request status, and recovery window before final submission.", "Separate Delete account from Sign out, Remove from device, Delete one service, Unsubscribe, Download data, Disable profile, and Privacy settings.", "Block wrong-account deletion when the signed-in account, provider, workspace, or child-account context changes.", "Test search, mobile navigation, app uninstall, web deletion URL, multiple accounts, child account, enterprise-managed account, billing owner, legal hold, pending request, failed support case, and compact layouts." ], "commonMisuses": [ "Hiding account deletion in a privacy policy, FAQ, support article, or exact-match help search.", "Offering only deactivation and keeping account data active.", "Presenting data export as the end of the account deletion process.", "Requiring users to email support with no identity check, expected response time, request ID, or status.", "Removing Delete account from the app after users uninstall or sign out.", "Using a small settings-row toggle or vague Delete button for account-level destruction.", "Omitting retained-data, subscription, linked-app, child-account, enterprise-policy, or wrong-account consequences." ], "critiqueQuestions": [ "Can users find account deletion from account settings without searching help?", "Can users request deletion after uninstall or outside the native app when needed?", "Is the visible route truly account deletion, or only deactivation, export, unsubscribe, sign out, or support contact?", "What exact account, provider, workspace, or child account would be closed?", "Which associated data is deleted, retained, transferred, public, backed up, or outside the product's control?", "Does the flow produce a request ID, status, receipt, or completion proof?", "Is this the hidden account-deletion anti-pattern, or should the corrected route be delete account, destructive action confirmation, typed confirmation, data export, privacy settings, or settings management?" ], "relatedPatterns": [ "delete-account", "destructive-action-confirmation", "typed-confirmation", "data-export", "privacy-settings", "settings-management", "disabled-controls-without-recovery", "ambiguous-destructive-action-copy", "dark-pattern-consent" ], "comparisons": [ "hidden-destructive-account-deletion-vs-delete-account-vs-destructive-action-confirmation-vs-typed-confirmation-vs-data-export-vs-privacy-settings" ], "sourceIds": [ "apple-account-deletion-in-app", "google-play-account-deletion-requirements", "google-account-delete-help", "ico-right-to-erasure", "google-takeout-download-data" ] }, { "id": "hover-card", "completionStatus": "complete", "name": "Hover card", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Rich preview surface on hover or focus", "maturity": "standard", "platforms": [ "web", "desktop" ], "problem": "Dense interfaces often contain links, mentions, files, issues, and references that users need to inspect before opening, but navigating away for every object slows comparison and short tooltips cannot carry enough context.", "solution": "Show a compact object preview on hover or focus, keep it anchored to the referenced object, include only high-value metadata and an explicit route to the full object, make the card hoverable and dismissible, and provide non-hover access for users who cannot use pointer hover.", "uiGuidance": [ "Render a hover card as a compact preview visually tied to a link, mention, row, object chip, file, person, or chart mark, with a title, key metadata, optional thumbnail, recent activity, and a clear route to the full object.", "Keep hover-card content preview-oriented and brief; do not turn it into a full popover workflow, command menu, form, tooltip label, or persistent details panel." ], "uxGuidance": [ "Use hover cards to help users inspect an object before navigating, especially in dense lists, mentions, dashboards, file browsers, issue trackers, and relationship-heavy interfaces.", "Make opening, delay, pointer handoff, keyboard focus behavior, Escape dismissal, close delay, collision handling, and alternate access predictable so the preview helps exploration without trapping or surprising users." ], "uiExamples": { "good": [ "Hovering or focusing @Maya Chen opens a card with avatar, role, local time, current project, recent activity, and View profile link.", "A file reference opens a hover card with filename, owner, modified time, sync state, preview thumbnail, and Open file route." ], "bad": [ "A hover card contains a long editable form, delete buttons, filters, and settings controls.", "Hovering a row shows a card for the previously hovered person, with no title or object identity." ] }, "uxExamples": { "good": [ "A user focuses @Maya Chen, reads the profile preview, moves the pointer into the card without it closing, presses Escape, and focus remains on the mention.", "A user scans issue links and the hover card waits briefly before opening, closes after a short delay, and never changes the selected issue or route." ], "bad": [ "The card disappears while the pointer travels from the mention into the preview.", "A keyboard user opens a hover preview but cannot dismiss it without losing focus or tabbing through hidden controls." ] }, "problemContext": [ "A link, mention, row, file, issue, alert source, or relationship reference has useful preview metadata.", "Users repeatedly compare objects before deciding whether to navigate, open a drawer, or switch context.", "The preview can be summarized without requiring interaction, editing, or commitment inside the card.", "The implementation can support pointer hover, keyboard focus, Escape dismissal, pointer handoff, delay timing, collision handling, and alternate access." ], "selectionRules": [ "Choose hover card when users need a richer preview of an object behind a reference before deciding whether to open it.", "Use tooltip when the content is only a short noninteractive description of the trigger.", "Use popover when users intentionally open a stable surface with controls, choices, links, or light editing that must remain available after pointer movement.", "Use disclosure details when the explanation should stay inline and visible after users open it.", "Use drawer or details panel when users need persistent side-by-side inspection, comparison, or actions while continuing work.", "Use preview panel or page navigation when the preview requires large media, long reading, deep metadata, or durable state.", "Use context menu or action menu when the surface is primarily a command list rather than a preview.", "Do not use hover card for required instructions, validation help, destructive decisions, authentication, or primary task actions." ], "requiredStates": [ "Resting trigger state with visible or accessible object identity.", "Pointer hover pending state with a short open delay to avoid flicker while scanning.", "Open hover card state anchored to the current trigger.", "Pointer bridge or hoverable state where moving into the card does not immediately close it.", "Keyboard focus state where the card can appear for the focused trigger and be dismissed with Escape.", "Close delay state that prevents accidental disappearance while the user corrects pointer movement.", "Collision or scroll-container state where the card flips, shifts, or closes instead of clipping or detaching.", "Stale-object prevention state where a changed, removed, or re-rendered trigger closes or refreshes the card.", "Touch or assistive-technology alternate route state with an explicit open link, profile route, or inline equivalent." ], "interactionContract": [ "The card previews only the object represented by the current trigger.", "The card opens on pointer hover and can also open on keyboard focus when the trigger receives focus.", "Open and close delays reduce flicker without hiding the existence of the preview.", "Users can move the pointer from trigger to card without losing the card.", "Escape dismisses the card and keeps focus on the trigger.", "Pointer out, blur, scroll away, or trigger removal closes the card after the defined delay.", "The preview includes an explicit route to the full object when users need durable access.", "The card does not contain primary workflows, destructive choices, or controls that require stable focus management unless it is promoted to a popover or dialog.", "Required information is available outside the hover card.", "The card does not update the selected object, navigate, submit, or commit changes simply by opening." ], "implementationChecklist": [ "Define the object type, trigger identity, preview fields, and full-object route before designing the card.", "Set open and close delays that fit dense scanning without causing flicker or sluggishness.", "Keep the hover card title, metadata, status, activity, and optional thumbnail concise enough to read quickly.", "Implement pointer handoff so the card remains visible while pointer moves from trigger to content.", "Support keyboard focus opening and Escape dismissal, or provide a separate explicit keyboard route to the same preview.", "Close or reanchor when the trigger scrolls, is removed, changes object identity, or moves near viewport edges.", "Avoid hidden-only content: expose profile pages, details links, or inline equivalents for touch and assistive-technology users.", "Test dense list scanning, repeated rows, stale data, slow network preview loading, zoom, scroll containers, collision, pointer jitter, keyboard focus, and screen readers." ], "commonMisuses": [ "Using a hover card as the only place for required instructions or validation help.", "Putting forms, filters, destructive commands, or multi-step workflows inside the card.", "Opening on hover only with no keyboard or explicit route to the same preview.", "Closing as soon as the pointer leaves the trigger, before users can inspect the card.", "Showing stale preview data for the previously hovered row.", "Using long open delays that make the preview feel unreliable.", "Letting the card cover the trigger or nearby content without Escape dismissal.", "Using hover cards on touch-first interfaces where hover cannot be invoked reliably." ], "critiqueQuestions": [ "What exact object does this hover card preview?", "Is the preview useful before navigation, or would a normal link, tooltip, popover, drawer, or page be clearer?", "Can users reach equivalent information without pointer hover?", "Can users move from trigger to card, dismiss with Escape, and keep focus on the trigger?", "What happens when the row recycles, the object changes, the trigger scrolls, or the preview fetch is slow?", "Is any required instruction, destructive action, or multi-step workflow hidden in this transient preview?" ], "relatedPatterns": [ "tooltip", "popover", "disclosure-details", "drawer", "context-menu", "action-menu" ], "comparisons": [ "hover-card-vs-tooltip-vs-popover-vs-disclosure-details" ], "sourceIds": [ "radix-hover-card", "wcag-content-on-hover-or-focus", "material-rich-tooltips", "shiny-fluent-hovercard" ] }, { "id": "human-approval-gate", "completionStatus": "complete", "name": "Human approval gate", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Runtime checkpoint that pauses AI or automation until an eligible human authorizes the next step", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI agents and automations can make high-impact changes faster than users can inspect them, and ordinary approval pages, queues, or logs often fail to show the live step that is armed, the payload that will execute, or the conditions that make approval valid.", "solution": "Pause the automation at a named gate, show the proposed action, evidence, payload, risk, eligibility, timeout, freshness, and resume consequences, then allow an eligible human to approve, reject, edit, cancel, escalate, or bypass with audit before the automation continues.", "uiGuidance": [ "Render a human approval gate as a paused automation checkpoint with the proposed action, tool or workflow step, triggering rule, risk level, payload snapshot, requester or agent, approver eligibility, timeout, and explicit approve, reject, edit, cancel, or bypass controls.", "Show what will happen after each decision: approve resumes the exact gated step, reject stops or routes fallback, edit changes the payload before resume, timeout expires or escalates, and bypass records an authorized override." ], "uxGuidance": [ "Use human approval gate when automation is ready to act but policy, risk, confidence, cost, access, publication, deployment, customer impact, or legal consequence requires a human decision before execution continues.", "Keep the gate tied to the live automation run so users can see why it paused, what is armed to run, what has already happened, what can still change, and whether the snapshot is still fresh." ], "uiExamples": { "good": [ "An AI support agent pauses before issuing a refund, shows the proposed amount, customer, policy match, confidence, source grounding, approver role, timeout, Approve refund, Edit amount, Reject, and Stop run controls.", "A deployment run pauses at production release, shows required reviewer group, commit SHA, environment, wait timer, self-review block, risk checks, and the job that will resume after approval.", "A workflow automation waits before emailing customers, previews the exact message, recipient segment, suppression checks, approver eligibility, stale-data warning, and cancel or approve controls." ], "bad": [ "A banner says Human approval needed but does not show the tool call, payload, approver, timeout, or resume consequence.", "A notification has Approve and Reject buttons for an agent action without opening the current run state or checking whether the payload changed.", "A reviewer can approve an automation run after the action already executed, making the gate only decorative audit text." ] }, "uxExamples": { "good": [ "A billing lead opens the paused refund gate, sees that the amount is under policy but source grounding is partial, edits the refund to the verified amount, approves, and the agent resumes only that step.", "A release manager rejects a deployment gate because the smoke test is stale; the workflow cancels the production step, records the reason, and keeps the pre-production artifacts visible.", "A mobile approver opens the compact gate, sees the proposed action, risk, approver role, timeout, and stale-state warning before approving." ], "bad": [ "A human approves a stale agent action from email and the agent applies it to a different customer state.", "Rejecting the gate leaves an automation run suspended with no cancel, revise, retry, or escalation path.", "An approver sees only the AI recommendation and confidence score, not the actual action that will run after approval." ] }, "problemContext": [ "An agent, workflow, deployment, rule, model, integration, or scheduled automation has reached a step that can send messages, spend money, change access, publish content, run tools, deploy code, delete data, update legal status, or affect customers.", "The system can identify the exact step, payload, run state, prior steps, approver rule, current input version, model or workflow version, freshness, and downstream consequence.", "Approval may be required because of risk threshold, policy, low confidence, source gap, high cost, external side effect, customer impact, compliance, security, or manual separation of duties.", "The human decision must affect whether the next automation step runs now, runs with edits, is canceled, is retried, is escalated, or is overridden.", "The gate can appear in agent consoles, workflow run pages, deployment screens, service desks, content operations, finance tools, and mobile approval notifications." ], "selectionRules": [ "Choose human approval gate when automation is paused at runtime and cannot execute the next step until an eligible human authorizes it.", "Use approval workflow when a submitted request needs a durable multi-state approval route independent of a currently paused automation run.", "Use review queue when users triage many queued items rather than decide one armed automation checkpoint.", "Use review before submit when the initiating user is checking their own answers before committing a transaction.", "Use recommended next action when the system suggests an optional next step; use human approval gate when policy or runtime safety requires human authorization.", "Use confidence / uncertainty display inside the gate when reliability affects the decision, but do not let confidence replace the approval decision.", "Use source grounding display or citation display inside the gate when evidence affects approval, but keep the gate responsible for pause, authorization, and resume.", "Show the exact action, payload, target, prior run context, and resume consequence before the human can approve.", "Block approval when the run state, payload, source scope, model version, permissions, risk threshold, or approver eligibility changed after the gate was opened.", "Do not treat post-action audit, passive notifications, or vague pending labels as an approval gate." ], "requiredStates": [ "Paused gate state with proposed action, payload snapshot, reason for gate, and run context.", "Eligible approver state with role, separation-of-duties rule, and decision controls.", "Not eligible or self-review-blocked state with request-access, delegate, or escalation path.", "Approve and resume state that revalidates freshness before executing the gated step.", "Reject or cancel state that stops the step and records reason and fallback.", "Edit before approve state that changes the proposed payload and requires revalidation.", "Timeout, expired, due soon, and escalated gate states.", "Stale gate state when input, payload, source, model, policy, or workflow version changed.", "Bypass or emergency override state with elevated permission and audit reason.", "Resumed, completed, failed after approval, and rolled-back states.", "Mobile compact approval state that still shows action, risk, payload, approver rule, and timeout." ], "interactionContract": [ "The gate belongs to a specific automation run, step ID, payload version, model or workflow version, target object, and approver rule.", "Approval is valid only for the displayed snapshot and must re-check run state, payload hash, eligibility, source freshness, policy, and threshold immediately before resume.", "Approve resumes the named gated step and does not authorize unrelated future actions unless the UI states that scope explicitly.", "Reject, cancel, timeout, and stop-run outcomes leave the run in a known terminal or fallback state with reason and recovery path.", "Edit-before-approve changes the payload, marks the gate revised, and re-runs validation before the edited action can resume.", "Delegate, reassign, escalate, and bypass actions preserve the original gate context and record actor, role, reason, timestamp, and version.", "Notifications and mobile approvals must deep-link to the canonical gate and refuse stale decisions.", "The audit trail records the gate reason, shown payload, approver eligibility, decision, comment, resume event, failure after approval, and override reason." ], "implementationChecklist": [ "Model automation run ID, gate ID, step ID, proposed action, payload snapshot, payload hash, target object, trigger reason, risk level, evidence, confidence, source scope, approver rule, timeout, and downstream action separately.", "Define which actions require approval by policy, threshold, confidence, cost, data sensitivity, external side effect, deployment target, access scope, publication state, or customer impact.", "Render the paused step with prior completed steps, current gate, next step, action preview, payload diff, approver eligibility, timeout, and decision controls.", "Revalidate run state, payload hash, source freshness, model or workflow version, approver role, and policy before accepting approve, edit, reject, bypass, or mobile decisions.", "Add outcomes for approve and resume, edit and revalidate, reject with reason, cancel run, delegate, escalate, timeout, emergency stop, bypass with reason, failed resume, and rollback.", "Keep confidence, source grounding, citations, warnings, and audit history available as decision inputs without turning them into the gate itself.", "Log gate-visible payload, decision reason, actor, role, timestamp, version, notification source, stale-decision rejection, resume result, and downstream execution result.", "Test stale email approvals, self-review block, missing approver role, edited payload, timeout, delegate, bypass, failed resume, mobile decision, keyboard flow, screen-reader status updates, and high-zoom payload wrapping." ], "commonMisuses": [ "Showing Approve without the exact action, payload, target, risk, or resume consequence.", "Using a post-action audit record as if it were a pre-action human gate.", "Letting stale notifications approve changed automation state.", "Allowing any viewer or the automation requester to approve when policy requires an eligible independent reviewer.", "Treating low confidence, source grounding, or warning text as a substitute for a human decision.", "Leaving rejected or timed-out gates suspended without cancel, fallback, edit, or retry state.", "Approving a whole run when the UI only described one step, or approving one step when future steps also need gates.", "Hiding the failure after approval, rollback, or downstream execution result from the approver." ], "critiqueQuestions": [ "What exact automation run, step, payload, target, and version is the human authorizing?", "Why did this gate trigger, and which policy, threshold, risk, or confidence condition requires human approval?", "Who is eligible to approve, who is blocked from self-review, and what happens if no one responds before timeout?", "What changes after approve, reject, edit, timeout, stop, delegate, escalate, or bypass?", "What revalidation prevents stale email, mobile, notification, or reopened-tab decisions from resuming unsafe automation?", "Does the audit trail prove what the human saw before approval and what actually executed after approval?" ], "relatedPatterns": [ "approval-workflow", "review-queue", "review-before-submit", "recommended-next-action", "confidence-uncertainty-display", "source-grounding-display", "citation-display", "activity-log", "notification-center" ], "comparisons": [ "human-approval-gate-vs-approval-workflow-vs-review-queue-vs-review-before-submit-vs-recommended-next-action" ], "sourceIds": [ "github-actions-deployment-protection-rules", "microsoft-power-automate-approvals", "servicenow-ask-for-approval-action", "gitlab-merge-request-approvals", "microsoft-human-ai-guidelines", "wcag-status-messages" ] }, { "id": "icon-only-ambiguous-action", "completionStatus": "complete", "name": "Icon-only ambiguous action", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Ambiguous action anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users must guess what an icon-only control does, which slows action selection, hides risk, and can leave keyboard and assistive technology users without an action name.", "solution": "Treat ambiguous icon-only actions as an anti-pattern: use visible action text when meaning or risk is not obvious, and reserve icon-only controls for familiar low-risk utilities with a clear accessible name, stable context, and supplemental help.", "uiGuidance": [ "Replace ambiguous symbol-only controls with visible text or icon-plus-text actions that name the verb and affected object.", "Reserve icon-only controls for familiar low-risk utilities and give each one a precise accessible name, visible focus, and focus-or-touch-accessible supplemental help." ], "uxGuidance": [ "Make users confident about what will happen before activation instead of forcing recognition, memorization, or trial-and-error.", "For risky icon actions, combine pre-action clarity with the right consequence handling: confirmation for irreversible intent checks and undo or restore for reversible completed actions." ], "uiExamples": { "good": [ "A report row shows Archive report, Download report, and Share report as labeled controls with matching accessible names.", "A compact Close button remains icon-only only because it is conventional, low risk, and announced as Close panel." ], "bad": [ "A row exposes !, tray, and arrow buttons with no visible label and unclear consequences.", "The same box icon archives reports in one table and deletes folders in another." ] }, "uxExamples": { "good": [ "Users can identify the action before activation and receive confirmation, undo, or result status after consequential actions.", "Keyboard, touch, and screen reader users receive the same action meaning as pointer users." ], "bad": [ "Hover-only tooltip is the only explanation for a destructive action.", "A screen reader announces button or exclamation, and activation archives the report without warning." ] }, "problemContext": [ "A toolbar, table row, card, or compact navigation surface contains icon-only controls.", "The icon is not conventional in the product domain, resembles multiple actions, or changes meaning by context.", "The action can archive, delete, share, expose data, change permissions, spend money, or otherwise create user risk.", "Mouse users may see a tooltip, but touch, keyboard, voice, and screen reader users need the action name before activation." ], "selectionRules": [ "Flag this anti-pattern when the icon meaning is not clear from the visible label, surrounding row, action group, and product convention.", "Use visible text for primary, destructive, financial, security-sensitive, sharing, permission, and low-frequency actions.", "Use icon plus text when a symbol helps scanning but the action still needs explicit meaning.", "Allow icon-only buttons only for familiar low-risk utilities such as search, close, back, or play when each control has a precise accessible name.", "Use confirmation dialog when the user has already chosen a clearly labeled high-risk action and must review consequence before commitment.", "Use undo when a clearly named reversible action has completed and users need a short recovery window.", "Do not use hover-only tooltip text as the only way to understand an action." ], "requiredStates": [ "Default state where the action name is visible or programmatically exposed before activation.", "Hover, focus, and touch-accessible help state for compact actions that still need supplemental explanation.", "Activated state that confirms the named action, affected object, and result.", "Risk review state for destructive or privacy-sensitive actions.", "Recovery state such as undo, restore, or confirmation cancellation when the action has consequences." ], "interactionContract": [ "The visual control, accessible name, and action result use the same verb and object.", "Keyboard focus reveals the same action meaning that pointer users receive, without relying on hover alone.", "Touch users can identify the action without long-press discovery or trial activation.", "Repeated icons in a row or toolbar are differentiated by accessible names such as Archive report, Download report, and Share report.", "The icon does not change meaning across pages unless the surrounding visible label or control text changes with it.", "Risky icon actions provide prevention or recovery through confirmation, preview, undo, or restore." ], "implementationChecklist": [ "Audit every icon-only button for visible action text, accessible name, affected object, and consequence.", "Prefer text labels for primary and high-risk actions; use icon plus text when space allows.", "If icon-only is justified, set a specific accessible name that describes the action, not the icon shape.", "Keep tooltip text supplemental and make sure keyboard and touch users receive equivalent information.", "Avoid reusing the same symbol for different verbs in the same product area.", "Pair destructive icon actions with confirmation, undo, or restore according to consequence and reversibility.", "Test with keyboard navigation, screen reader announcement, touch input, zoom, localization, and first-time users." ], "commonMisuses": [ "Using a trash, tray, box, arrow, or exclamation icon for archive, delete, download, export, and warning actions without visible words.", "Providing an accessible name such as icon, more, or button instead of the action and object.", "Putting the only explanation in a tooltip that appears on hover but not focus or touch.", "Using the same icon for Archive on one page and Delete on another.", "Hiding destructive row actions until hover, then presenting only symbols.", "Relying on color or placement to distinguish icon actions with different consequences." ], "critiqueQuestions": [ "Can a first-time user name the action and consequence before pressing the control?", "Will the screen reader announcement match the visible label or tooltip text?", "Does the icon mean the same thing across this workflow and product area?", "Would a touch or keyboard user receive the same explanation as a mouse user?", "If the action is destructive or exposes data, is there confirmation, preview, undo, or restore?" ], "relatedPatterns": [ "confirmation-dialog", "undo", "toast-only-critical-error", "disabled-button-no-explanation" ], "comparisons": [ "icon-only-ambiguous-action-vs-confirmation-dialog-vs-undo" ], "sourceIds": [ "wai-aria-apg-names-and-descriptions", "wai-aria-apg", "material-design-buttons" ] }, { "id": "in-page-anchor-navigation", "completionStatus": "complete", "name": "In-page anchor navigation", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Same-page section jump links for long content", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users on a long page need to understand what sections are available and jump to the section they need without moving to another page or interpreting the content as hierarchy.", "solution": "Provide an 'On this page' style set of same-page anchor links generated from or aligned to major headings, with active section state and focus behavior that confirms the destination section.", "uiGuidance": [ "Render a labelled navigation landmark with links to major headings on the current page, using labels that match or clearly summarize the destination sections.", "Keep the anchor list visually tied to the current article or page content, and show an active section state when the page is long enough for scrolling context to matter." ], "uxGuidance": [ "Use in-page anchor navigation to help users understand the contents of a long page and jump directly to the section they need without leaving the page.", "After activation, move focus to the destination heading or otherwise make the new section clear, so keyboard and screen-reader users do not remain stranded at the link list." ], "uiExamples": { "good": [ "An article starts with an 'On this page' nav linking to Eligibility, Documents, Fees, and After you apply, each matching an H2 on the same page.", "A sticky right-side in-page nav highlights Fees while the Fees heading is in view.", "A narrow layout keeps the jump links near the top of the article and pairs them with a Back to top link for long pages." ], "bad": [ "A short page with two paragraphs shows a table of contents that adds more navigation than content.", "Anchor labels say Overview, Details, and More while the headings say Requirements, Costs, and Next steps.", "The anchor list mixes same-page sections with external pages and account tools." ] }, "uxExamples": { "good": [ "A user opens a long guidance page, chooses Fees, and lands at the Fees heading with the Fees link marked active.", "A user follows a shared hash link and the page clearly indicates which section is being viewed.", "After reading a deep section, a Back to top control or sticky contents list helps the user return to the page outline." ], "bad": [ "Clicking a jump link scrolls visually but keyboard focus stays in the contents list.", "The active link remains on Eligibility while the visible heading is Fees.", "A link labelled Documents opens another page, breaking the expectation that contents links stay on the current page." ] }, "problemContext": [ "The page is long enough that scanning headings alone is inefficient.", "The content is one coherent page rather than a set of separate pages or transaction steps.", "Users may arrive with a specific section in mind and need a quick way to reach it." ], "selectionRules": [ "Choose in-page anchor navigation when one page has several meaningful sections, usually at least two H2-level destinations and enough length to justify jump links.", "Use only headings or major section destinations on the current page; do not mix external pages, account actions, or local hierarchy pages into the list.", "Keep link labels short, descriptive, and aligned with the destination headings so users can predict the target.", "Move focus to the target heading after activation or ensure the destination is programmatically clear.", "Highlight the current section when the navigation is sticky or when users may lose track during scrolling.", "Avoid in-page anchor navigation on short pages where the list would duplicate visible headings without reducing effort.", "Use side navigation for related pages in a section, breadcrumbs for parent hierarchy, and Back links for transaction return." ], "requiredStates": [ "Default state with a labelled same-page navigation list near or beside long content.", "Active section state that matches the heading currently reached or visible.", "Hash-linked or deep-linked state where the correct section is indicated on load.", "Keyboard activation state where focus lands on or near the destination heading.", "Sticky or scrolling state where active section updates as the viewport changes.", "Short-page or insufficient-heading state where the component is omitted." ], "interactionContract": [ "Activating an anchor link navigates within the current page to the matching section target.", "The destination heading text and anchor link label remain aligned enough for users to confirm they arrived at the expected section.", "Keyboard focus moves to the destination heading or the section receives an equivalent focus target after activation.", "The URL hash, active link, and visible section do not contradict each other.", "Sticky versions update current-section state as users scroll and do not cover the target heading.", "The anchor list remains separate from breadcrumbs, side navigation, global navigation, and page actions." ], "implementationChecklist": [ "Identify the page's major H2 sections and decide whether there is enough content to justify jump links.", "Use a labelled navigation landmark such as 'On this page' or 'Page contents'.", "Generate or maintain anchor hrefs from stable heading IDs and keep labels synchronized with heading text.", "Set scroll-margin or equivalent offset so sticky headers do not hide destination headings.", "Move focus to the destination heading on activation, or make the destination focusable with tabindex when needed.", "Update active state from hash changes and scrolling when the component is sticky.", "Test keyboard, screen-reader, reduced-motion, and narrow-screen behavior." ], "commonMisuses": [ "Using in-page anchors as a substitute for side navigation across different pages.", "Adding a contents list to a short page where all headings are already visible.", "Letting anchor labels drift from destination headings.", "Changing the visible section without moving keyboard focus or active state.", "Mixing same-page anchors with external links, global navigation, or account actions.", "Letting sticky headers cover the target heading after a jump." ], "critiqueQuestions": [ "Is this one long page, or are these actually separate pages that need side navigation or pagination?", "Do anchor labels match the headings users will see after activation?", "What receives focus after a keyboard user activates a jump link?", "Does the component disappear on short pages or when there are too few meaningful headings?", "Can a shared hash URL open the page with the right section and active state?" ], "relatedPatterns": [ "breadcrumbs", "side-navigation", "back-link", "tabs" ], "comparisons": [ "in-page-anchor-navigation-vs-breadcrumbs-vs-side-navigation" ], "sourceIds": [ "uswds-in-page-navigation", "va-on-this-page-component", "california-page-navigation" ] }, { "id": "inaccessible-custom-select", "completionStatus": "complete", "name": "Inaccessible custom select", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Broken custom widget anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "A visual dropdown looks like a select control but lacks the semantics, keyboard support, selected state, focus behavior, or form value exposure users expect.", "solution": "Treat the inaccessible custom select as an anti-pattern: use a native select for simple single-choice lists, or implement a complete accessible listbox, combobox, or multi-select contract when custom behavior is necessary.", "uiGuidance": [ "Replace fake select markup with a native select unless a custom listbox, combobox, or multi-select contract is truly required and fully implemented.", "When custom behavior is required, make the trigger, popup, active option, selected option, validation, and submitted value visible and programmatically exposed." ], "uxGuidance": [ "Let every user complete the same choice with pointer, keyboard, touch, voice, and assistive technology instead of making styling work for only one input method.", "Choose the right control model before styling: compact native select for one known value, autocomplete for search, and multi-select for multiple values." ], "uiExamples": { "good": [ "A native select keeps its persistent label, selected value, required validation, and platform keyboard behavior.", "A custom listbox shows expanded state, active option, selected option, and returns focus to the trigger after dismissal." ], "bad": [ "A div styled like a dropdown opens only on click and exposes no option roles or current value.", "The selected visual label changes but the submitted form value remains empty." ] }, "uxExamples": { "good": [ "Keyboard users can open, navigate, select, dismiss, and continue without losing focus or value.", "Screen reader users hear the label, current value, expanded state, available options, and selected value." ], "bad": [ "Click-only menu traps or loses focus and cannot be completed from the keyboard.", "The component looks complete in screenshots but fails validation or form submission because no real value changed." ] }, "problemContext": [ "A team replaces native select styling with divs, popovers, portals, or JavaScript-only menus.", "The control works for pointer users but fails keyboard, screen reader, voice, form submission, or zoom scenarios.", "The popup may lose focus, clip options, close unexpectedly, or update only visual text instead of the actual form value.", "The product needs a single known value, searchable known value, or multiple values but uses one generic custom dropdown for all cases." ], "selectionRules": [ "Flag this anti-pattern when a custom dropdown cannot be opened, navigated, selected, dismissed, and reviewed by keyboard.", "Use native select when the user chooses one value from a finite known list and platform behavior is sufficient.", "Use an accessible custom listbox only when native select cannot meet product requirements and the implementation exposes label, popup, active option, selected option, value, and expanded state.", "Use autocomplete or combobox when users need to type to filter or complete a long known list.", "Use multi-select when users can choose more than one value and need persistent selected chips, removal, and multi-value form submission.", "Do not ship a visual dropdown until it synchronizes visual value, submitted value, accessible value, and validation state.", "Avoid portal or overlay implementations that break focus return, option clipping, Escape dismissal, or screen-reader discovery." ], "requiredStates": [ "Closed state with persistent label, current value, and collapsed state.", "Open popup state with reachable options and visible active option.", "Selected option state that remains visible after the popup closes.", "Validation state when no valid option has been selected.", "Dismissed state where Escape or outside click preserves the current value and restores focus.", "Synchronized form state where the selected value is submitted and announced consistently." ], "interactionContract": [ "The trigger exposes an accessible name, current value, role, and expanded or collapsed state.", "Keyboard users can open the popup, move through options, select an option, dismiss without change, and continue from a predictable focus position.", "Pointer, keyboard, touch, voice, and assistive technology users can complete the same selection without losing context.", "The active option and selected option are visually and programmatically distinguishable.", "The selected value updates the visible trigger, validation state, and submitted form value together.", "Custom behavior is tested across native browser zoom, mobile viewport constraints, reduced motion, and screen reader modes." ], "implementationChecklist": [ "Start with native select and document why custom behavior is necessary before replacing it.", "If custom, choose the correct pattern: listbox for browseable single choice, combobox for typed filtering, or multi-select for multiple values.", "Expose stable label, popup relationship, expanded state, active option, selected option, and current value.", "Implement keyboard opening, arrow navigation, Home and End where appropriate, Enter or Space selection, Escape dismissal, and focus return.", "Keep options readable and reachable when rendered in portals, scroll containers, small screens, and zoomed layouts.", "Synchronize the selected value with form submission, validation, reset, and server-rendered defaults.", "Test with keyboard only and at least one screen reader before claiming custom select parity." ], "commonMisuses": [ "Using divs with click handlers and no role, label, expanded state, or option semantics.", "Updating the visual label but not the form value that submits to the server.", "Closing the menu before keyboard or assistive technology users can inspect options.", "Losing focus when the popup is rendered in a portal or dismissed with Escape.", "Using a custom select for a long list that needs search or autocomplete.", "Using a single-select-style dropdown for multiple values without chips, removal, or clear selected count.", "Clipping options inside overflow containers or hiding them from screen readers." ], "critiqueQuestions": [ "Can a keyboard-only user open it, inspect options, choose one, dismiss without change, and continue from the trigger?", "Does the screen reader announcement include label, current value, expanded state, option count or option names, active option, and selected state?", "Does the selected value submit, validate, reset, and hydrate like a real form control?", "Is this actually a select, or does the task need autocomplete, combo box, radio group, or multi-select behavior?", "What happens when the popup is clipped, the page zooms, or the user presses Escape?" ], "relatedPatterns": [ "select", "autocomplete", "multi-select", "radio-group" ], "comparisons": [ "inaccessible-custom-select-vs-select-vs-autocomplete-vs-multi-select" ], "sourceIds": [ "wai-aria-apg-listbox", "govuk-select-component", "uswds-select-component", "ontario-design-system-autocomplete", "carbon-dropdown-multiselect" ] }, { "id": "infinite-scroll-with-no-footer-access", "completionStatus": "complete", "name": "Infinite scroll with no footer access", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Endless loading footer-access anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Automatic infinite loading can make the page bottom unreachable, preventing users from reaching footer utilities, legal links, support routes, feedback, language controls, or a reliable end state.", "solution": "Flag the endless-loading trap and provide a deliberate footer-access contract: stop or limit auto-load, expose loaded boundaries, preserve position, provide Load more or pagination when appropriate, and keep essential footer links reachable by keyboard, screen reader, and touch users.", "uiGuidance": [ "Treat infinite scroll with no footer access as an anti-pattern when automatic loading keeps pushing footer, legal, privacy, help, contact, sitemap, language, feedback, or account links out of reach.", "Replace uncontrolled auto-loading with a reachable boundary: Load more, pagination, sticky or repeated footer links, jump-to-footer, end-of-feed status, saved position, or a clear pause/stop loading control." ], "uxGuidance": [ "Use this anti-pattern during review when users try to reach the bottom of a page for help, legal, settings, unsubscribe, feedback, or navigation but more items keep appearing.", "Design long streams with an escape and completion contract: users can stop loading, reach footer utilities, understand how many items loaded, resume position, recover from failure, and choose pagination or load-more when exact position or task completion matters." ], "uiExamples": { "good": [ "A news feed loads two automatic batches, then shows Load more stories, End of latest batch, and a reachable footer with Privacy, Accessibility, Contact, and Cookies links.", "A search result stream offers Jump to footer, Back to top, Load more, and Page 3 of results when users need exact position.", "A mobile product list pauses auto-load before the footer and repeats Help, Returns, Legal, and language links above the next Load more control." ], "bad": [ "A feed appends another batch whenever the user nears the footer, so the footer never becomes reachable.", "A catalog has legal and support links only in the footer, but infinite loading keeps inserting product cards before the footer.", "A scrollable result page has no end state, no loaded count, no pause, no jump to footer, and no saved position after opening an item." ] }, "uxExamples": { "good": [ "A user scrolls through 60 updates, reaches a stable Load more boundary, opens Contact in the footer, then returns to the same feed position.", "A keyboard user can skip from feed results to footer navigation without tabbing through every newly inserted card.", "After a loading failure, the page keeps the footer reachable and offers Retry loading more without moving the user." ], "bad": [ "A user scrolls for the privacy link, but every near-bottom scroll loads another set of cards and pushes the footer away.", "A screen reader user encounters an endless stream of new articles and cannot discover footer links or completion state.", "Opening a feed item and returning resets the infinite stream to the top, so the user cannot resume or reach the footer." ] }, "problemContext": [ "The page uses infinite scroll, auto-load-on-near-bottom, virtualized lists, dynamic feeds, product grids, search results, activity streams, or media streams.", "The page footer contains required or useful destinations such as privacy, terms, accessibility, cookies, contact, language, feedback, account, app download, sitemap, or support.", "Users may be trying to finish a task, compare loaded items, reach help, satisfy a legal requirement, unsubscribe, change privacy settings, or leave the stream.", "The product may also need reading position restoration, loaded-count disclosure, item identity, loading failures, offline retry, and mobile browser chrome behavior." ], "selectionRules": [ "Flag this anti-pattern when automatic loading prevents reliable access to footer links, page end, support routes, legal links, feedback, or other bottom-of-page utilities.", "Flag it when the only route to privacy, terms, contact, language, or cookie settings is below an endlessly extending list.", "Use feed when users intentionally consume a continuing stream and the design preserves reading position, item identity, loaded boundaries, and access to footer or escape controls.", "Use pagination when users need stable page position, shareable page state, exact result review, footer access, or a known end.", "Use card list or list view when users manage a bounded object collection with filtering, sorting, selection, comparison, and object actions rather than passively consuming a stream.", "Use skip link behavior for bypassing repeated page chrome or jumping to a footer target, but do not use skip links as a substitute for fixing endless auto-load.", "Use an explicit Load more boundary when continuous loading is useful for browsing but users still need control over when more content is inserted.", "If auto-load remains, limit the number of automatic batches before showing a deliberate Load more control and a reachable footer.", "When the footer contains legally required controls, repeat those controls near the feed boundary or keep the footer reachable without relying on exact scroll timing.", "Preserve scroll position, focused item, loaded count, and route return state so users can open an item, come back, and still reach the same boundary." ], "requiredStates": [ "Default stream with loaded item count, order label, and visible footer-access plan.", "Auto-load paused after a small number of batches with a Load more control and footer visible.", "Jump to footer or footer utility shortcut state.", "End-of-feed state with footer reachable and no spinner loop.", "Loading more state that does not move focus or hide the footer indefinitely.", "Failed-load state with Retry and footer access still available.", "Return-from-detail state that restores scroll position and loaded boundary.", "Mobile compact state where footer links, back to top, and load-more controls remain reachable.", "Bad state showing auto-load pushing the footer away, keyboard trap through cards, no end state, spinner loop, and lost position." ], "interactionContract": [ "Users can reach footer utilities without racing automatic loading.", "Automatic loading has a bounded policy, a visible count, and a deliberate user-controlled continuation point.", "Load more, Retry, Jump to footer, Back to top, and footer links are keyboard reachable without requiring traversal of every loaded item.", "Newly loaded content is inserted at a predictable boundary and announced without moving focus unexpectedly.", "The interface communicates whether more items exist, loading failed, loading is paused, or the end has been reached.", "Opening an item and returning restores the previous scroll position, focused item, loaded count, and footer-access boundary.", "Essential legal, privacy, support, cookie, language, and feedback links are available outside any unreachable footer if the stream can grow.", "Pagination or explicit Load more replaces infinite scroll when users need exact position, completion, comparison, footer access, or shareable state." ], "implementationChecklist": [ "Identify all footer-only links and decide whether each must also appear near the stream boundary, header, account menu, or help menu.", "Limit automatic batches before requiring an explicit Load more action.", "Render a stable loaded boundary with item count, loading status, end state, failure, and retry.", "Add Jump to footer or skip-to-footer behavior when long feeds precede required footer links.", "Keep footer links in the normal document flow and test them with keyboard and screen reader navigation.", "Preserve scroll and focus position after opening items, applying filters, sorting, navigating back, refreshing, or retrying.", "Avoid auto-loading while a user is keyboard-tabbing near the footer or focused on footer-access controls.", "Test mobile viewport height, virtualized list unmounting, browser back, reduced motion, offline failure, and slow network loading.", "Prefer pagination or load-more controls when the stream supports search, filters, exact review, task completion, or legal footer access." ], "commonMisuses": [ "Putting Privacy, Terms, Accessibility, Contact, Cookies, or language links only in a footer that infinite scroll prevents users from reaching.", "Appending items every time the footer comes into view.", "Using a spinner at the bottom as the only end-of-feed indicator.", "Adding a Back to top control while still making the footer unreachable.", "Telling users to use search to find footer links.", "Letting keyboard users tab through newly inserted cards forever before footer links.", "Virtualizing items without preserving focused item or return position.", "Treating infinite scroll as harmless because analytics show high engagement, while users cannot complete support or legal tasks." ], "critiqueQuestions": [ "Can a mouse, touch, keyboard, and screen reader user reliably reach the footer?", "Which required links are footer-only, and what happens if the footer is pushed away?", "How many batches auto-load before the user must choose Load more?", "Is there a visible loaded count, end state, loading failure, and retry?", "Can users jump to footer, back to top, and return to the same item after opening detail?", "Would pagination, Load more, card list, list view, or a bounded feed better match this task?" ], "relatedPatterns": [ "feed", "pagination", "card-list", "list-view", "skip-link", "page-not-found-page", "filter-panel", "sort-controls" ], "comparisons": [ "infinite-scroll-with-no-footer-access-vs-feed-vs-pagination-vs-card-list-vs-skip-link" ], "sourceIds": [ "nng-infinite-scrolling-tips", "wai-aria-apg-feed", "mdn-aria-feed-role", "govuk-pagination-component", "shopify-polaris-resource-list", "wcag-focus-order" ] }, { "id": "infinite-spinner", "completionStatus": "complete", "name": "Infinite spinner", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Unbounded loading anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users are left in an unbounded busy state when a request, save, import, sync, or report generation may never complete and the UI offers no timeout, fallback, cancellation, retry, or failure explanation.", "solution": "Treat the infinite spinner as an anti-pattern: name the operation, bound the wait, preserve the affected context, and transition to progress, content, cached fallback, cancellation, retry, or persistent error recovery.", "uiGuidance": [ "Replace an unlabeled endless spinner with a bounded loading surface that names the operation, preserves the affected context, and changes state after the wait threshold.", "Expose retry, cancel, cached data, background continuation, progress detail, or support escalation when the system cannot complete quickly." ], "uxGuidance": [ "Help users decide whether to wait, retry, leave safely, use stale data, or escalate instead of forcing them to infer system health from animation alone.", "Design loading as a lifecycle with elapsed, timeout, recovery, cancellation, and failure states, not as a visual loop that can mask broken work." ], "uiExamples": { "good": [ "Billing data is loading shows the affected account, elapsed wait, and actions for Retry, Use cached values, and Contact support after timeout.", "A report job starts with indeterminate progress, then switches to queue position or background completion when the wait becomes long." ], "bad": [ "A centered spinner animates on a blank page for minutes with no label or escape.", "A Save button turns into a spinner forever, leaving the user unable to cancel, retry, or know whether the save happened." ] }, "uxExamples": { "good": [ "The user can wait briefly, see that billing data is delayed, open cached values, retry once, or escalate with a reference.", "If the operation moves to background processing, the UI confirms what will happen next and where to find the result." ], "bad": [ "Users refresh the page because the spinner never explains whether the request is still working or broken.", "Assistive technology remains in a busy state without a loaded, timed-out, failed, or cancelled announcement." ] }, "problemContext": [ "A request can hang, fail silently, be queued for a long time, or lose its completion event.", "The screen or control remains disabled while an indeterminate spinner continues animating.", "Users need to decide whether to wait, retry, cancel, use stale data, leave the flow, or contact support.", "The system can detect elapsed time, retry count, request state, cached data age, or a support reference but does not surface it." ], "selectionRules": [ "Flag this anti-pattern when a spinner or busy overlay can continue without a timeout, elapsed status, retry, cancel, fallback, or failure state.", "Use a short indeterminate spinner only for brief waits where completion is expected and the affected action or region is clearly named.", "Use loading skeleton when predictable content structure is pending and will resolve to content, empty, or error within a bounded path.", "Use a determinate progress indicator, step status, or job queue state when the system can expose percent, stages, item counts, or position.", "Use error state when the operation has failed, timed out, lost authorization, or reached a retry limit that requires user recovery.", "Offer cached data, background continuation, cancellation, or support escalation when the user should not be forced to watch an unknown wait." ], "requiredStates": [ "Initial pending state that names the operation and affected object.", "Extended-wait state after a defined threshold with elapsed context or reason for delay.", "Timed-out or still-working state with retry, cancel, cached fallback, or background continuation.", "Recovered state after the data, save, import, or report resolves.", "Failed state with persistent recovery and support escalation when retry cannot complete.", "Cancelled or leave-safely state when users can stop waiting without losing work." ], "interactionContract": [ "The loading state is tied to a specific region, action, or object instead of freezing the entire interface without explanation.", "The spinner does not remain the only status after the wait threshold; the UI changes copy, available actions, or state.", "Retry, cancel, cached view, background processing, or support controls become available without requiring a page refresh.", "User-entered work, filters, selected files, and billing or report context remain visible or recoverable while the operation waits.", "Assistive technology receives concise status changes and is not left in a permanent busy state.", "A second retry does not loop back to the same endless spinner without changing the recovery options." ], "implementationChecklist": [ "Define timeout thresholds per operation type, such as short inline saves, medium data loads, long imports, and background jobs.", "Pair every spinner with text that names what is loading or processing.", "After the threshold, replace or augment the spinner with elapsed status and actions such as Retry, Cancel, Use cached values, Keep working, or Contact support.", "Switch to determinate progress when the backend can expose stages, percent, item counts, or queue position.", "Preserve the affected task context so users can continue, retry, or report the problem without reconstructing their work.", "Instrument stalled requests and retry outcomes so the UI timeout is connected to real system state.", "Remove busy or disabled state when loading resolves, fails, is cancelled, or moves to background processing." ], "commonMisuses": [ "Animating a full-page spinner forever after a request times out.", "Replacing a failed API response with a loading state because error handling is missing.", "Disabling the only button with a spinner and no explanation, timeout, or alternate action.", "Showing a skeleton and spinner together while neither resolves to content or error.", "Making users refresh the browser to find out whether a payment, upload, report, or save completed.", "Keeping aria-busy set after the operation has failed or moved to the background." ], "critiqueQuestions": [ "What exact UI state appears after the first wait threshold is crossed?", "Can the user safely leave, cancel, retry, or use cached data without losing context?", "Does the spinner name the operation and affected object, or only imply that something somewhere is happening?", "What prevents a failed request from being represented as loading forever?", "Can keyboard and screen reader users discover the timeout and recovery actions?" ], "relatedPatterns": [ "loading-skeleton", "error-state", "toast-only-critical-error", "disabled-button-no-explanation" ], "comparisons": [ "infinite-spinner-vs-loading-skeleton-vs-error-state" ], "sourceIds": [ "carbon-loading-component", "mdn-aria-progressbar", "nord-skeleton-component" ] }, { "id": "inline-edit", "completionStatus": "complete", "name": "Inline edit", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "In-place value or row editing", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Small edits become slow or risky when users must open a separate form for one visible value, or when in-place editing hides whether the value is read-only, changed, saved, invalid, or cancelable.", "solution": "Let a displayed value, table cell, or row switch into a local edit control with a clear edit trigger, Save and Cancel, contextual validation, dirty-state protection, and table refresh or sort behavior that keeps the edited item understandable.", "uiGuidance": [ "Render a read-state value with a visible edit affordance, then replace only that value, cell, or row with the appropriate input and adjacent Save and Cancel controls when edit mode starts.", "Show text states for editable, editing, changed, validation error, saving, saved, and read-only values; do not rely on hover or color alone to reveal editability." ], "uxGuidance": [ "Use inline edit when users need to make frequent, low-impact changes to one visible property while preserving surrounding list, table, or record context.", "Keep the edit local: disable save until the draft differs from the original, validate beside the input, preserve the original for cancel, and protect unsaved changes when users click away or navigate." ], "uiExamples": { "good": [ "A resource table shows an edit icon beside the owner cell; activating it turns that cell into a text field with Save and Cancel buttons while other cells remain read-only.", "A details page shows a visible Edit label next to an editable display name and keeps non-editable fields as plain read-only values." ], "bad": [ "Every table cell is always an input, so users cannot tell which values changed or whether a row is still just being read.", "A displayed value becomes editable only when users click the text, but there is no edit affordance, no cancel button, and no saved state." ] }, "uxExamples": { "good": [ "A user clicks Edit owner, changes the value, sees Save become enabled, enters an invalid short value, fixes it beside the field, saves, and stays on the same row.", "A user starts editing a table cell, clicks another row, sees a dirty-change warning, discards the draft, and the original value is restored." ], "bad": [ "A user types a new value and clicks elsewhere; the product silently discards the draft with no warning.", "A user edits a sorted table cell and the row immediately jumps to a different page before the saved value can be confirmed." ] }, "problemContext": [ "The user is viewing a record, list, table, or details page and needs to update one low-impact property.", "Keeping surrounding context visible helps the user choose the right value or compare rows.", "The edit can be committed or canceled independently without reviewing a larger form.", "The system can preserve the original value and reliably report save, validation, and failed-save states." ], "selectionRules": [ "Choose inline edit for frequent low-impact edits to one displayed value, table cell, table row, or resource property.", "Use text input instead when the user is already inside a normal form and there is no separate read state.", "Use single-page form when several related values should be reviewed and submitted together.", "Use modal dialog when a short edit needs focused explanation or secondary controls but should not become a whole page.", "Use complete complex form when changes span sections, dependencies, or review-before-save consequences.", "Do not use inline edit for irreversible, high-impact, bulk, or cross-record changes without stronger confirmation or review.", "Avoid inline edit where clicking a value already opens drill-down, selects text, expands a row, or triggers row selection.", "In tables, account for sort, filter, pagination, refresh, row selection, and one-row-at-a-time editing before enabling inline edit.", "Make editability visible through an edit button, icon, hover affordance, or row action with an accessible name.", "Keep Save disabled or clearly unavailable until the draft differs from the original value." ], "requiredStates": [ "Read state with displayed value and discoverable edit affordance.", "Read-only or unavailable state for values that cannot be edited.", "Edit mode with focused input and adjacent Save and Cancel controls.", "Unchanged draft state where Save is disabled or explained.", "Dirty draft state where Save is available and Cancel restores the original value.", "Validation error state shown beside the edited input.", "Dirty click-away or navigation state that asks whether to save, discard, or keep editing.", "Saving state that prevents duplicate commit without losing the draft.", "Saved success state that returns to read mode with the new value visible.", "Failed-save state that keeps the input editable and reports recovery." ], "interactionContract": [ "Edit changes only the targeted value, cell, or row into edit mode and leaves unrelated content in read mode.", "Only one table row or one conflicting edit scope can be active at a time unless the product explicitly supports batch editing.", "Save commits the changed draft, reports validation errors in place, and returns to read mode only after success.", "Cancel discards the draft and restores the original displayed value.", "Click-away with no changes can exit edit mode; click-away with changes must save, discard, or keep editing by explicit user choice.", "Sorting, filtering, pagination, and refresh should not make the edited item disappear before users can understand the saved result.", "Keyboard users can enter edit mode, move through editable fields, save, cancel, and recover from errors without relying on hover." ], "implementationChecklist": [ "Identify which values are editable and which are read-only before adding edit affordances.", "Give every edit trigger and icon-only Save or Cancel control an accessible name.", "Store the original value separately from the draft so Cancel and dirty comparison are reliable.", "Disable Save until the draft differs from the original, or explain why save is unavailable.", "Place validation messages directly beside the edited input and keep the draft editable after errors.", "Implement dirty click-away and route-change handling before enabling inline edit in dense tables.", "Decide how active sort, filter, pagination, and refresh behave after a value changes.", "Prevent conflicts with row drill-down, row selection, text selection, bulk actions, and keyboard shortcuts.", "Test keyboard entry, Escape or Cancel, Enter or Save, focus return, screen reader labels, validation, failed save, and mobile hit targets." ], "commonMisuses": [ "Using inline edit for high-impact changes that need a review or confirmation step.", "Making static text secretly editable with no visible affordance.", "Removing Cancel, so users cannot restore the original value.", "Saving every keystroke while presenting the interaction as explicit save/cancel inline edit.", "Letting sorted or filtered rows jump away immediately after the value changes.", "Allowing multiple table rows to enter edit mode when row selection and bulk actions are still active.", "Using inline edit for a large multi-field form that belongs in a page, modal, or complex form.", "Replacing text with an input on hover and blocking users from selecting or copying the displayed text." ], "critiqueQuestions": [ "Is the edit low-impact enough to commit locally without broader review?", "Can users discover which values are editable before clicking them?", "What happens to the original value if the user cancels or clicks away?", "Does Save stay disabled until a real change exists?", "Where does validation appear and can users fix it in place?", "Will sorting, filtering, pagination, row selection, or drill-down conflict with edit mode?" ], "relatedPatterns": [ "text-input", "single-page-form", "modal-dialog", "complete-complex-form", "inline-validation" ], "comparisons": [ "inline-edit-vs-text-input-vs-single-page-form-vs-modal-dialog" ], "sourceIds": [ "atlassian-inline-edit-component", "cloudscape-inline-edit-pattern", "patternfly-inline-edit-pattern" ] }, { "id": "inline-message", "completionStatus": "complete", "name": "Inline message", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Contextual in-flow feedback", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need status, warning, success, or next-step information that belongs to a specific visible object or section, and a transient or page-level message would disconnect it from the affected context.", "solution": "Place a concise persistent message inside the relevant local context, expose the right urgency semantics, offer at most one local action or detail toggle, and remove or update it when that local condition changes.", "uiGuidance": [ "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.", "Keep the message visible until the local condition is resolved, dismissed when safe, or replaced by a more appropriate error state, page-level message, or notification history item." ], "uxGuidance": [ "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.", "Escalate away from inline messages when users must fix a field value, recover a failed content area, review page-wide consequences, or act on a message after leaving the local context." ], "uiExamples": { "good": [ "An invoice row shows Missing billing contact directly beneath the affected customer with Add contact as the only action.", "A report panel shows Export limited to filtered rows next to the export controls, with a small Details disclosure." ], "bad": [ "A vague Important message appears above the whole page with no object reference.", "A section message contains a full support workflow, several links, and unrelated settings controls." ] }, "uxExamples": { "good": [ "Users can reveal why export is limited, add the missing contact, and see the local message resolve without losing table context.", "A successful send message remains beside the invoice long enough to copy the generated reference." ], "bad": [ "The message disappears like a toast even though users still need the invoice reference.", "A field-format error is shown at section level, forcing users to infer which input is wrong." ] }, "problemContext": [ "A row, card, panel, step, table section, or task area has a condition users must understand while working there.", "The information is broader than one input's validation text but narrower than a page, service, or site-wide message.", "Users need the message to remain near the affected object until they inspect, resolve, dismiss, or navigate away from that context.", "The condition can be communicated in a short title and body without opening a modal or replacing the whole content region." ], "selectionRules": [ "Choose inline message when the message's subject is a visible local object or section and the feedback should stay attached to it.", "Use inline validation instead when the message corrects one specific input value or missing field answer.", "Use error state instead when the expected content or action has failed and the affected area needs retry, fallback, preserved context, or support escalation.", "Use toast notification instead when the message can safely expire or be handled from notification history without staying in the local layout.", "Keep the message concise enough for users to scan while working; move long explanations to a detail disclosure, help page, or support flow.", "Include one local action only when it directly resolves or clarifies the local condition.", "Allow dismissal only when the underlying condition is informational or safely recoverable elsewhere.", "Use page-level or global feedback when the issue applies beyond the local row, panel, step, or section." ], "requiredStates": [ "Neutral local context with no message.", "Informational inline message attached to the relevant object or section.", "Warning or error-tone inline message for a local condition that does not replace the whole section.", "Actionable inline message with one local action or disclosure.", "Expanded detail state when the message needs a short explanation without leaving context.", "Resolved state after the local condition changes.", "Escalated state when the message becomes a field validation issue, error state, page message, or notification-center item." ], "interactionContract": [ "The message appears in the visual and reading order near the object or section it describes.", "The message title names the local subject, not only the severity.", "The local context remains usable while the message is visible unless the message explicitly disables a local action with a reason.", "Dynamic message appearance is announced as status or alert according to urgency without stealing focus by default.", "A detail toggle reveals only information required to understand the local condition.", "A local action changes, resolves, or opens the specific object or section referenced by the message.", "The message is removed, updated, or downgraded when the underlying local condition resolves." ], "implementationChecklist": [ "Identify the exact row, card, panel, step, or section the message belongs to before choosing placement.", "Use a short title that names the object or condition, followed by one concise sentence of body text.", "Choose status, warning, success, or error tone from consequence, not visual variety.", "Keep the message in the local layout so zoom, wrapping, and responsive changes do not detach it from the affected object.", "Use role status for routine updates and role alert for urgent local warnings that appear dynamically.", "Connect local controls to the message with description or labelled-by relationships when the message changes whether an action is available.", "Keep action labels specific, such as Add billing contact, View sync details, or Copy reference.", "Test the resolved, dismissed, expanded, repeated, and narrow-screen states." ], "commonMisuses": [ "Using an inline message for a single field error that should be connected to that input.", "Placing a local warning at the top of the page or inside a global banner.", "Using a toast for context users must reference beside an object.", "Replacing a full error state with a small inline note after content fails to load.", "Putting several unrelated actions or long instructions inside the message.", "Relying on color or icon alone to communicate warning, success, or error tone.", "Letting the message persist after the affected object or condition is resolved." ], "critiqueQuestions": [ "Can users tell which row, panel, step, or object this message describes?", "Does the message remain available as long as the local condition matters?", "Would this be clearer as field validation, a section error state, a toast, or a page-level message?", "Is there only one local action, and does it resolve or explain the message?", "Will assistive technology users hear the message without losing their current task position?", "What happens after the user resolves, dismisses, expands, or revisits the affected object?" ], "relatedPatterns": [ "toast-notification", "error-state", "inline-validation", "error-summary", "toast-only-critical-error" ], "comparisons": [ "inline-message-vs-toast-notification-vs-error-state-vs-inline-validation" ], "sourceIds": [ "atlassian-inline-message", "carbon-notification-component", "react-spectrum-inline-alert", "wcag-status-messages" ] }, { "id": "inline-validation", "completionStatus": "complete", "name": "Inline validation", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Field-level validation feedback", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to repair one invalid field while the entered value, label, hint, and correction remain in the same local context.", "solution": "Render a field-adjacent validation message only when it helps correction, keep the typed value editable, and describe the exact acceptable format or missing requirement.", "uiGuidance": [ "Render a labeled field with hint text, field-adjacent error text, invalid styling, preserved value, and corrected state.", "Connect the inline message visually and programmatically to the same input it describes." ], "uxGuidance": [ "Help users correct a specific field without losing or re-entering the value they already typed.", "Time validation after blur, submit, or another useful checkpoint so normal partial input is not punished." ], "uiExamples": { "good": [ "Error text appears next to the field with readable spacing, persistent label, hint text, and the invalid value still visible.", "Invalid state uses field-adjacent text and structure, not color alone." ], "bad": [ "Only a red border with no message.", "Error message appears far from the field it describes." ] }, "uxExamples": { "good": [ "Validation appears after blur or submit when it helps correction.", "User input remains editable and preserved while the error is fixed." ], "bad": [ "Showing errors before users type.", "Focus jumps on every keystroke or validation flicker." ] }, "problemContext": [ "The user is entering structured data into a known form control.", "The system can identify a problem with that exact control and state the correction briefly." ], "selectionRules": [ "Choose inline validation when one field has a correctable format, missing-value, range, or requirement problem.", "Show the message after blur, submit, or another meaningful checkpoint instead of flagging ordinary partial input on every keystroke.", "Use the same field message alongside an error summary when a submitted page has multiple invalid answers." ], "requiredStates": [ "Neutral field with label, hint, and no error.", "Invalid field with preserved user value and adjacent correction text.", "Corrected field with the error removed or replaced by a modest success cue.", "Submitted form where the invalid field remains reachable and editable." ], "interactionContract": [ "The message names the field problem and the correction in plain language.", "The invalid value remains in the input so the user can edit rather than retype it.", "The input exposes invalid state and its descriptive error text to assistive technology." ], "implementationChecklist": [ "Place the error message immediately after the label and hint, or otherwise directly beside the field it describes.", "Use visible text plus an invalid field treatment; do not rely on color, an icon, or a border alone.", "Connect the input to both hint and error text with stable IDs where the platform supports it.", "Keep both passing and failing answers in place when errors are shown.", "Avoid premature validation while users are still entering a value that may become valid." ], "commonMisuses": [ "Showing field errors before users have interacted with the control.", "Using vague labels such as Invalid value instead of naming the required correction.", "Clearing or replacing the user's value when validation fails." ], "critiqueQuestions": [ "Does the message tell users exactly how to fix this field without leaving the field context?", "Can the user edit the failing value directly from the error state?" ], "relatedPatterns": [ "error-summary" ], "comparisons": [ "inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-error-message-component", "govuk-error-summary-component" ] }, { "id": "input-mask", "completionStatus": "complete", "name": "Input mask", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Fixed-format text entry control", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users make avoidable format errors when long codes, numbers, or identifiers require grouping, but rigid masks can also reject valid values, break paste and editing, or obscure what will actually be stored.", "solution": "Use a mask only for stable formats, show persistent format guidance, normalize typed and pasted input into readable groups, preserve correction behavior, validate the canonical value, and provide an escape path when real values do not fit the mask.", "uiGuidance": [ "Show a persistent label, visible example or hint, fixed grouping, literal separators, and field-adjacent error text so users understand which characters are typed and which are supplied by the mask.", "Keep the entered value reviewable as both a formatted display value and, when relevant, a canonical stored value so users can see what will be submitted." ], "uxGuidance": [ "Use an input mask to help users enter data that has a stable character structure, especially when grouping matches the physical document, card, container code, or serial key users are copying from.", "Preserve normal editing behavior: users must be able to paste, delete, select, correct the middle of the value, use undo, and submit without learning the mask implementation." ], "uiExamples": { "good": [ "A container number field shows the example ABCD 123456 7, groups pasted characters into that shape, and displays the raw value ABCD1234567 before submit.", "A card-number field groups digits as users type and keeps helper text visible so the expected length does not disappear with the placeholder." ], "bad": [ "A phone field hard-codes a domestic mask and rejects valid international numbers.", "The field shows underscores and separators as the only instruction, then jumps the cursor unpredictably when users paste or delete." ] }, "uxExamples": { "good": [ "A user pastes abcd1234567, sees ABCD 123456 7, reviews the canonical value, and fixes one middle digit without retyping the whole code.", "A user submits ABCD 123 and receives a precise error that the six-digit serial group and check digit are incomplete." ], "bad": [ "A user pastes a valid value with spaces and the mask discards characters because it only supports one-character-at-a-time typing.", "A user enters an exception value required by a real document, but the mask blocks it with no alternative recovery path." ] }, "problemContext": [ "The field value has known character positions, group lengths, literal separators, or check digits.", "Users often copy the value from a document, card, label, shipment record, serial plate, or system-generated code.", "The grouped display reduces transcription errors and matches the user's source material.", "The product can define whether separators are stored, displayed only, copied, or stripped before backend validation.", "Valid exceptions, localization, alternate lengths, or picker-based entry have been checked before choosing a mask." ], "selectionRules": [ "Choose input mask when the value has a stable, narrow structure with predictable character classes and grouping.", "Use text input when users may need to enter values outside one fixed structure, such as company names, freeform identifiers, or international contact details.", "Use inline validation when normal typing should remain unconstrained and the system can explain a format error after blur or submit.", "Use autocomplete when the typed value should resolve to an existing record instead of merely being shaped into a format.", "Use prefix/suffix when a constant symbol, unit, currency, or domain is separate from the user's typed value.", "Use a date picker, time picker, or domain-specific picker when the picker owns entry and masks would conflict with it.", "Do not mask emails, broad phone-number formats, addresses, names, or values with common legitimate exceptions.", "Keep hint text visible for complex formats; do not rely on placeholder mask characters alone.", "Support paste from both formatted and unformatted values.", "State or reveal whether literals are included in copied and submitted values." ], "requiredStates": [ "Empty untouched state with label and visible format example.", "Focused state that reveals grouping or mask affordance without replacing the label.", "Partially entered state with incomplete groups and stable cursor behavior.", "Pasted unformatted value normalized into the mask.", "Pasted formatted value accepted without duplicating separators.", "Invalid character attempted state with a non-blocking explanation or ignored-character status.", "Incomplete required value error after submit.", "Complete formatted display state with canonical stored value visible or inspectable.", "Deletion or correction state where placeholders do not shift remaining characters unpredictably.", "Exception or unsupported-format state with a fallback path." ], "interactionContract": [ "Typing valid characters fills the next available mask slot and inserts literal separators automatically.", "Typing invalid characters either ignores them with a clear status or leaves the value unchanged without corrupting existing characters.", "Pasting formatted or unformatted content normalizes into the same display value.", "Deleting, selecting, replacing, undoing, and correcting middle groups remain predictable.", "Submitting an incomplete mask keeps the partial value visible and names the missing group or character count.", "The canonical value sent to the backend is derived deterministically and can be validated server-side.", "The mask does not remove browser, keyboard, or assistive technology access to label, hint, and error text." ], "implementationChecklist": [ "Define the canonical value, formatted display value, accepted character classes, group lengths, literals, optional groups, and storage behavior before building the UI.", "Choose native input attributes such as inputmode, autocomplete, autocapitalize, maxlength, spellcheck, and aria-describedby to match the data type.", "Normalize paste from formatted and unformatted sources and test paste with spaces, dashes, parentheses, lowercase letters, and clipboard content longer than the mask.", "Preserve user control over deletion, selection, overwrite, cursor movement, undo, redo, and browser autofill.", "Validate the canonical value on client and server and show incomplete or invalid-group errors next to the field.", "Provide visible helper text for the expected format and do not make placeholder mask characters the only instruction.", "Test localization, right-to-left layouts, screen readers, mobile keyboards, zoom, saved drafts, browser Back, copy behavior, and exception values." ], "commonMisuses": [ "Using a mask because a format exists even though many valid values do not fit it.", "Rejecting pasted values that include spaces, dashes, parentheses, or lowercase characters.", "Letting separators appear in the field but silently storing a different value without user or developer clarity.", "Using underscores or placeholder symbols as the only format guidance.", "Breaking deletion or middle-character correction so users must clear the entire field.", "Combining a mask with a picker or prefix/suffix that should own the format instead.", "Masking data that needs localization or exception handling without a fallback." ], "critiqueQuestions": [ "Is this value truly fixed-format, or are there legitimate exceptions?", "Can users paste the value from the source document and get the same result as typing?", "Can users correct one middle character without retyping the field?", "Are separators stored, displayed only, copied, or stripped before submit?", "Does the hint remain visible after the placeholder disappears?", "Would text input plus inline validation, autocomplete, prefix/suffix, or a picker be less fragile?" ], "relatedPatterns": [ "text-input", "inline-validation", "autocomplete", "error-summary", "select" ], "comparisons": [ "input-mask-vs-text-input-vs-inline-validation-vs-autocomplete" ], "sourceIds": [ "maersk-input-masks", "sap-fiori-mask-input", "microsoft-access-input-masks", "material-design-text-fields" ] }, { "id": "input-prefix-suffix", "completionStatus": "complete", "name": "Input prefix/suffix", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Text input with constant visual affix", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can misunderstand whether a value needs a currency symbol, unit, percentage sign, icon meaning, or domain, while systems often need the stored value without that repeated affix.", "solution": "Show a fixed prefix or suffix outside the editable value, describe its meaning in the label or hint, normalize duplicate typed affixes, validate the clean value, and store a predictable canonical payload.", "uiGuidance": [ "Render the prefix before the input or suffix after the input as a non-editable visual affix, with a persistent label or hint that names the unit or symbol in text.", "Style the input and affix as one field group for focus, error, disabled, and success states while keeping the user's editable value separate from the affix." ], "uxGuidance": [ "Use a prefix or suffix to reduce ambiguity when users must enter only the value and the unit, currency, percentage, or domain is fixed.", "Tolerate users typing the visible affix into the field by normalizing duplicate symbols or units instead of producing an avoidable error." ], "uiExamples": { "good": [ "A Cost, in dollars field shows a dollar prefix outside the input, uses numeric input, and stores only the numeric amount.", "A Weight, in pounds field shows lbs. as a suffix while the label names pounds for people who do not perceive the suffix." ], "bad": [ "A field labeled Amount shows a hidden dollar prefix but the label never says dollars.", "A suffix contains a long phrase that wraps into the input and looks like typed text." ] }, "uxExamples": { "good": [ "A user types $1,250 into a field with a dollar prefix and the form normalizes it to 1250 with a clear status message.", "A user switches from dollars to percent and the suffix, label, input mode, validation message, and submitted unit update together." ], "bad": [ "A user types lbs after a weight value because they missed the suffix, then gets an error instead of normalization.", "A user enters a non-monetary answer in a dispute-resolution field because the dollar prefix wrongly implied all answers are amounts." ] }, "problemContext": [ "The field asks for a value with a fixed unit, symbol, abbreviation, or icon meaning.", "The affix is common enough to clarify the value without a long explanation.", "The user should enter only the value, not the unit or symbol.", "The backend expects a canonical value and unit rather than an arbitrary combined string.", "Screen reader and voice users still need the unit or symbol in the label or hint because the visual affix may be hidden." ], "selectionRules": [ "Choose input prefix/suffix when a common fixed symbol, unit, abbreviation, domain, or icon clarifies what the text input accepts.", "Use ordinary text input when the answer is open-ended or the affix would over-constrain legitimate responses.", "Use input mask when the value itself needs live character grouping, inserted literals, or fixed slots.", "Use inline validation when the field can accept normal text first and only needs a correction message after interaction.", "Use select, radio group, or segmented control when users must choose between multiple units or currencies.", "Use hint text instead of an affix when the explanation requires more than a short, common symbol or abbreviation.", "Keep the affix outside the submitted editable value unless the product explicitly stores a formatted display string.", "Name the unit or symbol in the label or hint because assistive technologies may not announce decorative affixes.", "Allow users to type the visible prefix or suffix and normalize it when unambiguous.", "Place validation state on the whole input group so the affix and text field read as one field." ], "requiredStates": [ "Empty state with descriptive label and visible prefix or suffix.", "Focused state where the input and affix read as one field group.", "Filled state with the user's clean value and visible affix.", "Duplicate affix typed state normalized without an unnecessary error.", "Invalid numeric or missing value state with group-level error styling.", "Success state showing accepted canonical value and unit.", "Disabled or readonly state where the affix remains visually associated with the value.", "Changed-unit state when another control changes which affix is active.", "Mobile state with correct keyboard for the clean value.", "Assistive state where the label or hint communicates the affix meaning." ], "interactionContract": [ "The affix is visible near the input but not editable as part of the field value.", "Typing, paste, selection, undo, and deletion affect only the user's value, not the affix.", "If the user types the same affix, the system normalizes it or preserves the value with a clear, fixable message.", "Submitting validates the canonical value and unit together.", "Errors and success states apply to the input group, not only the inner input border.", "Changing unit mode updates the label, hint, affix, validation, and payload together.", "Copying the field value has a documented behavior: clean value only or formatted value, but not inconsistent by field." ], "implementationChecklist": [ "Define the clean value, affix text or icon, unit metadata, submitted payload, accepted duplicate-affix forms, and copy behavior.", "Put the affix outside the input element and keep it visually grouped with the control.", "Use a visible label or hint that names the unit, currency, percentage, or icon meaning in text.", "Set inputmode, type, pattern, width, autocomplete, and validation for the clean value without the affix.", "Normalize common duplicate inputs such as $1200, 1200 dollars, 12%, or 12 percent when the affix already represents that unit.", "Apply error, success, disabled, readonly, and focus styles to the whole input group.", "Test screen readers, voice input, paste, browser autofill, mobile keyboards, forced colors, zoom, RTL layouts, and backend parsing." ], "commonMisuses": [ "Relying on a visually hidden or decorative affix as the only way users know the unit.", "Rejecting values that include the same prefix or suffix users saw next to the field.", "Using a prefix or suffix for an open-ended answer that may not use that unit.", "Putting long explanatory copy in the affix instead of the hint.", "Storing the affix in one payload but stripping it in another.", "Using a static suffix when users can change the unit elsewhere.", "Making an icon affix ambiguous without a text label or hint." ], "critiqueQuestions": [ "Is the affix a fixed, common symbol or unit that users will understand?", "Does the label or hint communicate the same meaning without relying on the visible affix?", "What happens when users type or paste the affix into the value?", "What exact value and unit does the backend receive?", "Would a mask, picker, unit select, hint, or ordinary text input be less ambiguous?", "Do error and disabled states visually include the affix?" ], "relatedPatterns": [ "text-input", "input-mask", "inline-validation", "select", "error-summary" ], "comparisons": [ "input-prefix-suffix-vs-input-mask-vs-text-input-vs-inline-validation" ], "sourceIds": [ "uswds-input-prefix-suffix-component", "govuk-text-input-prefix-suffix", "material-design-text-fields", "maersk-input-masks" ] }, { "id": "invite-user", "completionStatus": "complete", "name": "Invite user", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Invitation lifecycle for granting another person access", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Inviting users changes access, billing, data exposure, and collaboration context, but products often hide who will receive the invite, what role they get, where they can go, whether approval is required, and how pending invitations can be tracked or revoked.", "solution": "Provide an invitation workflow that verifies recipient identity, previews access scope and role, explains constraints and side effects, sends through a clear delivery channel, tracks pending and accepted outcomes, and supports resend, edit, cancel, expiry, and approval states.", "uiGuidance": [ "Render invite user as an access-granting workflow with recipient identity, role or permission, team or channel scope, optional message, delivery method, expiry, pending status, resend, edit, cancel, and acceptance outcome.", "Keep invitation lifecycle separate from account creation, object picking, permission recovery, bulk import, and profile setup: the inviter is authorizing another person to join or access a space, not creating their account, choosing an existing object alone, recovering their own denied access, importing records, or enriching a profile." ], "uxGuidance": [ "Use invite user when an authorized person needs to bring another person into a workspace, organization, project, channel, repository, team, tenant, or shared object.", "Prevent accidental over-access by confirming recipient identity, access scope, role, billing or guest implications, invite expiry, and what the invited person can do before sending." ], "uiExamples": { "good": [ "A workspace invite form accepts maya@example.com, labels the invite as Workspace member, shows default channels, explains billing impact, lets the inviter add a message, and shows the pending invite with resend and cancel actions.", "An organization invitation asks for GitHub username or verified email, role, optional team, and repository access preview before sending." ], "bad": [ "An Invite button immediately emails every typed address with Admin access and no review of workspace, channel, or billing scope.", "A pending invite disappears after send, so admins cannot tell whether the user accepted, the link expired, or the email bounced." ] }, "uxExamples": { "good": [ "An admin invites an external contractor as a single-channel guest, sees the one-channel limit, adds a note, sends the invite, then extends it when it is still pending after 30 days.", "A repository owner enters an email that already has a pending organization invitation, updates the role, and resends without creating duplicate invites." ], "bad": [ "A member tries to invite a contractor but learns after send that guests require admin approval and no request status is shown.", "An invitation is accepted by the wrong account because the invite page never explained email verification or account matching." ] }, "problemContext": [ "A user with sufficient permission is adding another person to a workspace, organization, project, channel, repository, team, tenant, or shared resource.", "The invite may grant member, guest, admin, viewer, editor, channel, team, repository, enterprise, or external collaborator access.", "Invitations may be sent by email, username, directory lookup, invite link, group sync, or admin request.", "The invited person may need to accept, verify email, create or use an account, choose the correct identity, or wait for admin approval.", "Pending invites may expire, be resent, edited, canceled, extended, duplicated, bounced, accepted, or declined." ], "selectionRules": [ "Choose invite user when the primary action is sending an invitation that grants another person future access after delivery or acceptance.", "Use account creation when the current user is establishing their own credentials or persistent access.", "Use object picker when the user is choosing an existing person or group record without sending a new invitation lifecycle.", "Use permission recovery when the current user is blocked and needs to request access for themselves.", "Use bulk import when admins are creating or updating many user records from structured data rather than sending a small number of trackable invitations.", "Use profile setup when the invited or existing user is completing their visible identity after access exists.", "Require explicit review for elevated roles, external collaborators, billable seats, guests, invite links, broad channels, or organization-wide access.", "Show pending, accepted, expired, failed, approval-needed, duplicate, and canceled states as invitation states rather than generic success or error messages.", "Let authorized inviters edit role or scope, resend or extend, and cancel pending invitations before acceptance where the platform supports it." ], "requiredStates": [ "Recipient entry or directory lookup state", "Role and access scope selection state", "Guest, billing, external, or elevated-access warning state", "Optional invite message state", "Review before send state", "Sent and pending state", "Admin approval requested state", "Duplicate or already invited state", "Expired or bounced invitation state", "Resend, extend, edit, or cancel pending invitation state", "Accepted invitation state" ], "interactionContract": [ "Recipient entry identifies who will receive the invitation and clears or flags unresolved recipients before send.", "The invitation cannot be sent until required role, scope, and policy constraints are resolved.", "The review state summarizes recipient, destination, role, scope, message, expiry, billing or guest implications, and approval requirement.", "Sending creates a trackable invitation record with pending status rather than implying membership is active immediately.", "Duplicate invite attempts reuse, update, or surface the pending invitation instead of silently sending multiple conflicting invitations.", "Resend, extend, edit, cancel, approve, and deny actions update the pending invitation record and preserve audit-relevant context.", "Accepted or expired invitations stop showing unsafe send controls and route to membership, retry, or cleanup actions." ], "implementationChecklist": [ "Define invite target type, recipient identifiers, accepted account matching, role model, scope model, guest limits, billing impact, expiry, approval rules, and audit requirements.", "Validate email, username, domain, duplicate pending invite, existing membership, role eligibility, guest plan support, channel or team constraints, and external sharing policy before send.", "Show role and scope preview before sending, especially for admin, owner, guest, external collaborator, organization-wide, or billable access.", "Implement pending invitation list, accepted state, expired state, resend, extend, edit role or team, cancel, approval request, denial, and notification return paths.", "Do not leak restricted workspace, project, or repository details in invite emails or pending records beyond what the recipient is allowed to know.", "Log inviter, recipient, target, role, scope, source, delivery method, timestamp, expiry, updates, cancelation, and acceptance.", "Test wrong email, unverified email, already member, duplicate pending invite, expired invite, admin approval required, external guest, high-risk role, failed delivery, mobile, keyboard, screen readers, and localization." ], "commonMisuses": [ "Treating invitation sent as if the user is already a member.", "Hiding role, scope, guest, billing, external, or admin implications until after send.", "Sending duplicate invites instead of showing pending status.", "Letting users invite people to roles they cannot grant.", "Using invite links for broad access without expiry, deactivation, or scope explanation.", "Mixing invite user with account creation, profile setup, onboarding, billing, and role administration in one undifferentiated flow.", "Making cancellation, resend, and expiry impossible to find.", "Leaking restricted object names in invitation emails or approval messages." ], "critiqueQuestions": [ "Who will receive the invitation, and how is that identity verified or disambiguated?", "What role, team, channel, repository, workspace, or organization scope will they get?", "Does the invite create billing, guest, external sharing, admin, or data exposure consequences?", "Is approval required, and can the requester track the approval outcome?", "Where can admins find pending, expired, accepted, duplicate, and canceled invitations?", "Can pending invitations be resent, extended, edited, or canceled before acceptance?" ], "relatedPatterns": [ "account-creation", "object-picker", "permission-recovery", "bulk-import", "profile-setup", "review-before-submit", "confirmation-dialog" ], "comparisons": [ "invite-user-vs-account-creation-vs-object-picker-vs-permission-recovery" ], "sourceIds": [ "slack-invite-new-members", "slack-manage-pending-invitations", "slack-guest-roles", "github-invite-users-organization", "github-edit-cancel-organization-invitation" ] }, { "id": "kanban-board", "completionStatus": "complete", "name": "Kanban board", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Workflow-state board for cards moving through columns", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Teams need to coordinate work as it flows through stages, but ordinary lists, tables, and calendars hide WIP pressure, blocked work, stale cards, and the status-change meaning of moving an item.", "solution": "Provide a Kanban board with workflow columns, cards, WIP limits, counts, status mapping, movement controls, blocked and stale states, filters with hidden-card disclosure, card details, and recovery for invalid or accidental moves.", "uiGuidance": [ "Render workflow columns with visible names, status mapping, card counts, WIP limits, overloaded states, empty columns, and cards that show title, owner, priority, age, due date, blocked state, and enough metadata to understand the work.", "Show drag handles or move controls, drop targets, keyboard move actions, swimlanes or grouping, filters, hidden-card counts, and card detail entry points without making the board depend on pointer-only drag." ], "uxGuidance": [ "Use Kanban board when teams pull work through a shared workflow and need to see WIP pressure, bottlenecks, blocked items, stale cards, and status changes at a glance.", "Keep movement honest: changing columns updates workflow status, respects or explains WIP limits, preserves card identity under filters and sorts, and gives recovery when a move is blocked, invalid, or accidental." ], "uiExamples": { "good": [ "A product board shows Backlog, Ready, In progress, Review, and Done columns with card counts, WIP limits, blocked badges, owners, due dates, and visible over-limit styling in Review.", "A support operations board groups incident cards by service lane, shows stale age chips, and includes a Move to Review button on each focused card for keyboard users." ], "bad": [ "A board has columns named Important, Maybe, Later, and Random with no workflow meaning, no status mapping, and cards that never change state.", "A Kanban board hides every card behind colored sticky notes and forces drag-only movement with no card title, count, limit, or blocked state." ] }, "uxExamples": { "good": [ "A developer moves a card from In progress to Review, sees the status update, receives an over-limit warning, and can undo or help clear the bottleneck instead of pulling more work.", "A team filters to High priority, sees that three hidden low-priority cards remain in Review, opens a stale blocked card, and moves it only after resolving its dependency." ], "bad": [ "A user drags a card to Done but the underlying status remains In progress, so reports and automations disagree with the board.", "A filtered board shows one visible card in Review even though seven hidden cards exceed the WIP limit, so the team keeps starting new work." ] }, "problemContext": [ "Work items move through explicit workflow states such as Backlog, Ready, In progress, Review, and Done.", "Teams use the board to limit active work, find bottlenecks, choose what to pull next, and coordinate ownership.", "Cards may represent issues, tasks, incidents, requests, content items, deals, or operational work.", "The board may support drag and drop, keyboard moves, swimlanes, grouping, sorting, filters, automation, detail panels, and reporting.", "WIP limits, hidden filters, stale work, blocked dependencies, and status mappings can make the board misleading if not shown directly." ], "selectionRules": [ "Choose Kanban board when work items progress through shared workflow states and column movement is the primary interaction.", "Use table when the main task is comparing fields, sorting records, editing cells, or exporting structured rows.", "Use list view when users need a compact queue and do not need several workflow states visible at once.", "Use calendar view when date placement, duration, and availability matter more than workflow state.", "Use timeline when users need a chronological history of what happened rather than current workflow control.", "Use activity log when users need evidence of recorded actions rather than a mutable work-management board.", "Use dashboard layout when users need aggregate metrics and charts rather than card-level workflow movement.", "Show WIP limits and counts for active columns; first and final columns may use different rules because they represent not-started and completed work.", "Make filters, slices, sorting, collapsed swimlanes, hidden columns, and permissions visible so counts and WIP signals are not mistaken for the whole board.", "Avoid Kanban board when columns are arbitrary categories without pull rules, status semantics, or flow decisions.", "Use board status changes only when the backend status, automation, and reports update consistently with the visible card movement.", "Provide non-drag move controls before claiming the board supports keyboard and assistive technology workflows." ], "requiredStates": [ "Default board state with columns, card counts, WIP limits, visible filters, selected board, and at least one card per active workflow stage.", "Empty column, empty board, loading, failed-load, offline, permission-limited, filtered, and hidden-card-count states.", "Card detail, selected card, focused card, editing card, and card action menu states.", "Drag preview, keyboard move, move pending, move success, move failed, invalid destination, and undo states.", "WIP under limit, at limit, over limit, and WIP-limit-not-enforced states.", "Blocked, stale, dependency, due soon, overdue, priority, assigned, unassigned, and automation-pending card states.", "Swimlane, grouped, sorted, collapsed group, hidden column, and sliced-by-field states when supported.", "Responsive stacked or lane-switching state where column names, counts, WIP limits, and card identity stay visible." ], "interactionContract": [ "Each column represents a workflow state or selected column field value, and moving a card updates the same value shown in details, reports, and automation.", "Card identity, title, owner, priority, and blocked state remain stable across filters, sorting, grouping, movement, and detail views.", "Moving a card previews the destination, status change, WIP effect, automation side effects, and invalid-destination reason before or immediately after the move.", "When WIP is exceeded, the column count and limit are highlighted and the board explains whether the limit blocks the move or acts as guidance.", "Filters, collapsed groups, and hidden columns disclose hidden-card counts so WIP and throughput signals are not misread.", "Keyboard and assistive-technology users can move cards between valid columns without pointer drag.", "Undo or recovery is available for accidental moves unless the product has a stronger confirmation or audit requirement.", "Completed, blocked, canceled, and unmapped statuses are mapped to appropriate columns so board completion claims match backend truth." ], "implementationChecklist": [ "Define card schema: id, title, workflow status, assignee, priority, due date, age in column, blocked reason, dependencies, labels, source link, and edit permissions.", "Define column schema: id, name, mapped statuses or field values, WIP limit, count, color/category, done semantics, hidden state, and allowed transitions.", "Implement drag and keyboard move paths with the same validation, status update, focus return, undo, and error feedback.", "Model WIP at limit, over limit, hidden filtered cards, stale cards, blocked cards, collapsed swimlanes, sorted boards, and automation-pending moves.", "Keep column headers sticky or repeated enough that wide boards preserve context while horizontally scrolling.", "Show filters, slices, grouping, sorting, hidden columns, and hidden-card counts near the board header.", "Test long card titles, many columns, empty columns, overloaded columns, blocked cards, keyboard movement, mobile lane selection, and screen-reader names.", "Ensure analytics and reports consume the same status mapping as the board, not a separate visual-only column model." ], "commonMisuses": [ "Using Kanban columns as decorative categories rather than workflow states.", "Allowing visible card movement without updating the underlying status field.", "Hiding WIP limits, hidden filtered cards, or collapsed swimlane counts.", "Making drag and drop the only way to move work.", "Treating a sorted board as manually ordered without explaining the sort rule.", "Mapping Done, Blocked, or Canceled statuses to the wrong column and misreporting completion.", "Showing blocked and stale work with no visual or textual distinction.", "Using Kanban board as a dashboard for aggregate metrics without card-level flow decisions." ], "critiqueQuestions": [ "What workflow state does each column represent, and which backend status or field value owns it?", "Can users tell card count, WIP limit, over-limit state, blocked cards, stale cards, and hidden filtered cards?", "Does moving a card update status, reports, automations, and details consistently?", "How do keyboard users move a card and recover from a bad move?", "What happens when sorting, grouping, slicing, or hidden columns change the visible board?", "Would table, list view, calendar view, timeline, activity log, or dashboard layout better fit the task?" ], "relatedPatterns": [ "table", "data-grid", "list-view", "card-list", "calendar-view", "timeline", "activity-log", "filter-panel", "sort-controls", "details-panel" ], "comparisons": [ "kanban-board-vs-table-vs-calendar-view-vs-list-view" ], "sourceIds": [ "github-projects-board-layout", "github-projects-changing-layout", "azure-devops-kanban-overview", "azure-boards-wip-limits", "jira-cloud-configure-columns", "trello-board-basics" ] }, { "id": "keyboard-shortcut", "completionStatus": "complete", "name": "Keyboard shortcut", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Direct key combination that activates a known command, focus target, or mode", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Keyboard shortcuts can make expert workflows fast, but hidden or conflicting key commands can steal text input, override browser or assistive-technology behavior, fire accidental character-key actions, and make important commands undiscoverable to mouse, touch, switch, and screen reader users.", "solution": "Design keyboard shortcuts as documented accelerators bound to visible commands, with platform-aware key chords, clear scope, conflict checks, accessible exposure, disabled state, status feedback, remapping or disable controls for character keys, and confirmation or undo for risky actions.", "uiGuidance": [ "Render keyboard shortcuts as discoverable command hints near the visible command, in shortcut help, in menus or toolbars when space allows, and in platform-specific form such as Command+S on macOS and Control+S on Windows.", "Show the shortcut's command name, key chord, platform variant, scope, enabled or disabled state, conflict warning, and recovery requirement instead of treating the key sequence as hidden behavior." ], "uxGuidance": [ "Use keyboard shortcuts as accelerators for frequent, reversible, well-understood commands that already have visible controls or reachable command surfaces.", "Define where the shortcut works, when it is disabled, what it conflicts with, how users learn it, how they remap or turn off character-key shortcuts, and how risky commands are confirmed or undone." ], "uiExamples": { "good": [ "A document editor Save button shows Command+S on macOS and Control+S on Windows, disables the shortcut while a blocking validation dialog is open, and announces Saved draft.", "A table toolbar lists Export selected with Shift+E only when rows are selected, exposes the same shortcut in shortcut help, and explains why it is unavailable with no selection.", "A video player offers J, K, and L shortcuts only while the player has focus and includes settings to turn single-key shortcuts off." ], "bad": [ "A product hides Submit behind Control+Enter with no visible button, hint, focus rule, or mobile equivalent.", "A global D key deletes records while users type in comments or dictate with speech input.", "The command palette says Control+K, the menu says Command+P, and the toolbar has no shortcut state for the same command." ] }, "uxExamples": { "good": [ "A user presses Command+S in an editor, sees Saving then Saved, focus remains in the editor, and the same Save command remains available in the toolbar and menu.", "A user opens shortcut help, searches Export, sees platform-specific variants and current scope, then remaps a conflicting single-letter shortcut.", "A user presses Delete on a selected file and receives the same confirmation or undo recovery as the visible Delete command." ], "bad": [ "A screen reader user cannot discover the shortcut because it is not exposed in help, command labels, or aria-keyshortcuts.", "A keyboard user presses Control+F expecting browser find but the app opens an unrelated filter with no way to restore standard behavior.", "A speech input user says a sentence containing g and d, triggering global shortcuts that navigate away and delete a draft." ] }, "problemContext": [ "Users repeat commands such as save, search, copy, format, open command palette, move focus, toggle panels, archive, export, or run tools.", "The product runs inside browsers, operating systems, text editors, assistive technologies, and international keyboard layouts that already own many key combinations.", "Commands may be global, page-scoped, editor-scoped, object-scoped, modal-scoped, or active only while a component has focus.", "Some users rely on keyboard-only work, switch control, screen readers, speech input, touch keyboards, remapped hardware keys, or platform shortcuts." ], "selectionRules": [ "Choose keyboard shortcut when the design problem is accelerating one known command with a key combination, not helping users discover commands.", "Use command palette when users need searchable command discovery, ranking, recents, scope filtering, or fuzzy matching before execution.", "Use menu menubar when command organization, submenu hierarchy, disabled or checked state, and persistent desktop-style command grouping are the main concerns.", "Use toolbar when visible repeated commands near a view or selection matter more than memorized activation.", "Use undo or redo when the pattern is about edit-history semantics; keyboard shortcuts can invoke them but do not define their history behavior.", "Use focus traversal when the problem is predictable Tab order, roving focus, landmarks, or moving through interactive elements rather than executing commands.", "Prefer modifier chords for global commands and reserve single-character shortcuts for focused components or user-configurable expert modes.", "Provide visible alternatives for every primary workflow and every non-essential shortcut outcome.", "Avoid overriding browser, operating-system, assistive-technology, text-editing, and common platform shortcuts unless the app has a strong editor-like reason and a recovery path.", "Require confirmation, preview, undo, or delayed execution for shortcuts that delete, publish, send, spend money, change permissions, or affect other people." ], "requiredStates": [ "Visible command with shortcut hint.", "Shortcut help or command list state showing command name, key chord, platform variant, and scope.", "Global shortcut active state.", "Focused-component shortcut active state.", "Text field or editable-content suppression state.", "Enabled command state and disabled shortcut state with reason.", "Conflict detected state with browser, operating system, assistive technology, product, or custom shortcut map.", "Shortcut executed state with status feedback and focus preservation.", "Risky shortcut confirmation, preview, or undo state.", "Remap shortcut state and restore default state.", "Character-key shortcut off or focus-only state.", "International keyboard layout or platform variant state.", "Mobile or touch-keyboard state where shortcuts are supplemental and visible controls remain primary." ], "interactionContract": [ "A shortcut maps to one named command, focus target, or mode and uses the same command handler as visible controls.", "The key chord is platform-aware and formatted consistently wherever the command appears.", "The shortcut fires only in its declared scope and never while text entry, composition, screen reader commands, or browser-reserved behavior should own the key event.", "When the command is disabled, the shortcut is disabled too and the disabled reason is available through the same visible command surface.", "Shortcut activation reports success, pending, failure, undo, confirmation required, or conflict using visible and accessible status messaging.", "Shortcut hints, help, menus, toolbars, and command palette rows stay synchronized with the same command registry.", "Users can turn off, remap, or focus-scope single-character shortcuts that are implemented in web content.", "Risky shortcuts do not bypass review, confirmation, permissions, rate limits, or audit requirements." ], "implementationChecklist": [ "Inventory commands and classify each shortcut by command name, scope, platform chord, risk level, visible fallback, disabled condition, and owner.", "Build shortcuts from a central command registry so menus, toolbars, command palette rows, help pages, and keyboard handlers share one source of truth.", "Check conflicts against browser shortcuts, operating-system shortcuts, screen reader commands, text-editing commands, composition events, and existing product shortcuts.", "Suppress global shortcuts inside inputs, textareas, contenteditable regions, combo boxes, and editing modes unless the shortcut is explicitly owned by that component.", "Expose shortcuts through visible hints, shortcut help, command rows, aria-keyshortcuts where appropriate, and onboarding only for frequent expert accelerators.", "Provide remapping, disable, or focus-only options for single-character shortcuts and preserve user settings across sessions.", "Route destructive, expensive, permission-changing, or external-side-effect shortcuts through confirmation, preview, undo, or approval workflows.", "Test Windows, macOS, Linux, browser variants, screen readers, speech input, international layouts, hardware keyboards on tablets, mobile fallback, high zoom, and focus return." ], "commonMisuses": [ "Making a shortcut the only path to a primary command.", "Binding single-letter global shortcuts that fire during typing, dictation, or screen reader use.", "Showing shortcut hints that do not match the current platform or remapped key.", "Letting disabled commands still run from the keyboard handler.", "Overriding browser find, save, print, back, refresh, or operating-system shortcuts without a strong app-like reason.", "Using one shortcut for different commands in different panels without showing scope.", "Executing destructive, paid, public, or permission-changing commands from a key press without review or recovery.", "Documenting shortcuts in a help page but not exposing them near commands, menus, toolbars, or command search." ], "critiqueQuestions": [ "What visible command does this shortcut invoke, and does the shortcut call the same command handler?", "Where is the shortcut active, and where is it deliberately suppressed?", "Which browser, operating-system, assistive-technology, text-editing, and product shortcuts could conflict?", "How do users discover, search, remap, disable, and restore the shortcut?", "What happens when the command is disabled, pending, failed, risky, or no longer valid?", "Does this shortcut still work with international keyboard layouts, speech input, screen readers, and hardware keyboards on tablets?", "Is a visible button, menu item, toolbar control, command palette row, or focus traversal pattern the real primary pattern?" ], "relatedPatterns": [ "command-palette", "menu-menubar", "toolbar", "undo", "redo", "context-menu" ], "comparisons": [ "keyboard-shortcut-vs-command-palette-vs-menu-menubar-vs-toolbar-vs-undo-vs-redo" ], "sourceIds": [ "wcag-character-key-shortcuts", "mdn-aria-keyshortcuts", "microsoft-windows-keyboard-shortcuts", "vscode-default-keybindings", "apple-hig-keyboards" ] }, { "id": "language-selector", "completionStatus": "complete", "name": "Language selector", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "Visible control for switching current content or product language among available equivalent translations", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Multilingual products need to let people read and act in a language they understand, but automatic language detection, hidden settings, flag-only controls, incomplete translations, and context-losing redirects can leave users trapped in the wrong language or unsure what will change.", "solution": "Provide a visible language selector with native labels, current-language state, equivalent-content rules, explicit override persistence, programmatic language metadata, fallback handling, and task-context preservation.", "uiGuidance": [ "Render language choice as a visible in-context control near global or utility navigation with the current language, native-language labels, script or region disambiguation where needed, and an unavailable or partial-translation state.", "Use a simple two-language switch for exactly two equivalent languages and a menu, list, or searchable selector for larger sets, while keeping labels readable without relying on flags, icons, or the current page language alone." ], "uxGuidance": [ "Use language selector when users may land in the wrong language or prefer another language for the same content, and need to switch without losing page, object, task, draft, session, or route context.", "Respect explicit language choice over browser, device, IP, or account inference, persist it across internal navigation, and explain fallback, missing translation, partial translation, or machine translation before users commit." ], "uiExamples": { "good": [ "A public benefits page shows English as the current language and lets users switch to Español on the same page, with the Spanish label written in Spanish and the page lang updated after selection.", "A product with six languages opens a language menu listing Deutsch, English, Español, Français, 日本語, and Português, marks English current, and labels a partial translation as limited before selection." ], "bad": [ "A header shows only flag icons for language choices, so users cannot distinguish Spanish, Mexican Spanish, or region-specific content.", "A language menu lists every supported product locale even when the current article exists only in English and selecting another option silently redirects home." ] }, "uxExamples": { "good": [ "A user opens a payment-help article in English, chooses Français, stays on the equivalent article, keeps their signed-in session, and sees the choice persist on the next internal page.", "A user whose browser suggests Spanish chooses English once and the site keeps English until they change it again instead of re-detecting on every page." ], "bad": [ "A traveler using a borrowed device sees the wrong auto-detected language and cannot find a manual language control.", "A form user switches language midway through an application and loses every entered field because the selector navigated to a different route." ] }, "problemContext": [ "Users may arrive through search, shared links, bookmarks, redirects, browser language negotiation, account preferences, device locale, or location hints.", "The current page may have complete equivalent translations, partial translated sections, machine-translated content, unavailable translations, or language-specific legal and regional variants.", "Language selection affects comprehension, accessibility, search, support, authentication, forms, legal notices, communication preference, and trust.", "Users may not understand the current page language well enough to discover hidden settings or interpret language names translated into that current language.", "Language, country, region, script, locale, currency, timezone, and communication preference are related but distinct choices." ], "selectionRules": [ "Choose language selector when users need to switch the current page, task, or product interface to another available language.", "Use settings management when language is one durable configuration value inside a broader account or app settings area.", "Use preference center when language controls future communications, consent records, profile data, or marketing topics rather than current content.", "Use adaptive defaults when browser, device, account, or previous behavior only suggests the starting language.", "Use region, country, currency, or timezone controls separately when the user is changing market, legal jurisdiction, money, or scheduling context rather than text language.", "Show a direct two-language switch only when there are exactly two equivalent choices and the alternate label is understandable.", "Use a menu, list, or searchable selector for three or more languages, script variants, regional variants, or long language names.", "Do not list a language as fully available unless the current page or task has an equivalent translation.", "Persist explicit language choice across same-site navigation and do not override it with Accept-Language or IP detection.", "Preserve current page, route, selected item, form draft, authentication state, and return path when switching to an equivalent language." ], "requiredStates": [ "Default detected-language state with visible current language and manual override.", "Two-language switch state for exactly two equivalent translations.", "Three-or-more-language menu or list state with native labels and current selection.", "Selected-language state that updates page language, content language, and selector label.", "Persisted explicit-choice state that survives internal navigation.", "Equivalent translation available, partial translation, unavailable translation, machine translation, and fallback language states.", "Script or region disambiguation state such as Portuguese from Brazil or Chinese simplified versus traditional.", "Task-preservation state for route, object, form draft, authentication, focus, and scroll." ], "interactionContract": [ "The selector names the current language and available alternatives in language labels users can recognize.", "Selecting a language changes language only, not country, currency, timezone, legal market, notification preference, theme, density, or saved view unless stated separately.", "Explicit user selection overrides browser, device, IP, or account inference until the user changes it or clears the saved choice.", "Equivalent translated pages preserve the current route, selected object, draft, session, scroll anchor, and return path wherever technically possible.", "Unavailable or partial translations are labelled before selection, not discovered after redirect.", "The page language and any language names written in another language are programmatically marked for assistive technology.", "Focus moves predictably from the selector to the changed content or remains on the selector with a status message." ], "implementationChecklist": [ "Define language inventory by page or route, including complete, partial, unavailable, machine-translated, fallback, and regional/script variants.", "Store explicit language choice separately from inferred Accept-Language, IP location, country, currency, timezone, and communication preference.", "Use language tags, html lang, Content-Language where appropriate, and lang attributes on language names written in their own language.", "Map equivalent routes before showing a language as available, and provide fallback explanations when no equivalent route exists.", "Preserve form drafts, selected records, authentication, focus, scroll, and query state through language changes.", "Test screen readers, keyboard use, high zoom, long labels, right-to-left scripts, script variants, borrowed devices, private browsing, and no-cookie sessions." ], "commonMisuses": [ "Using country flags as the only language labels.", "Relying only on automatic language negotiation with no visible manual override.", "Redirecting language switches to a homepage and losing current context.", "Listing languages that do not have equivalent content for the current page.", "Mixing language selection with country, currency, timezone, notification, or consent preferences.", "Writing all language names in the current language so users in the wrong language cannot find their own.", "Failing to update lang metadata after changing page or component language." ], "critiqueQuestions": [ "Can users who do not understand the current page language still recognize and use the selector?", "Which languages are equivalent for this exact page or task, and which are partial, missing, fallback, or machine-translated?", "Does selecting a language preserve route, object, form draft, session, focus, and scroll?", "Does explicit choice override Accept-Language, IP, device locale, and account inference consistently?", "Are language, locale, region, script, currency, timezone, and communication preference kept distinct?", "Are page language and language-name changes exposed through correct lang attributes?" ], "relatedPatterns": [ "settings-management", "preference-center", "adaptive-defaults", "global-navigation", "utility-navigation", "select", "menu-button", "notification-preferences" ], "comparisons": [ "language-selector-vs-settings-management-vs-preference-center-vs-adaptive-defaults" ], "sourceIds": [ "uswds-language-selector", "w3c-language-negotiation", "wcag-language-of-page", "wcag-language-of-parts", "mdn-accept-language-header" ] }, { "id": "legal-acceptance", "completionStatus": "complete", "name": "Legal acceptance", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Explicit agreement gate for terms, conditions, contracts, policies, legal disclosures, or updated service rules before access or transaction commitment", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Legal agreements become weak or hostile when terms are hidden, preaccepted, bundled with unrelated consent, shown after commitment, impossible to review on small screens, or recorded without document version and timestamp evidence.", "solution": "Provide a clear legal acceptance gate with explicit unchecked agreement, document identity, version, effective date, full terms access, clear decline and consequence handling, validation, acceptance record, update/reacceptance handling, and accessible review or retention routes.", "uiGuidance": [ "Render legal acceptance as a required agreement control that names the document, owner, version or effective date, scope, linked or embedded full terms, and consequence of accepting or declining.", "Use unchecked explicit acceptance controls, visible legal text or links, clear validation errors, and post-acceptance status records instead of implied agreement through browsing, payment, or account continuation." ], "uxGuidance": [ "Use legal acceptance when users must knowingly agree to terms of service, conditions of sale, workplace terms of use, contract amendments, policy acknowledgements, or other legal documents before proceeding.", "Help users review, retain, decline, reaccept, or recover from the agreement by showing change summaries, document versions, download or print routes, grace periods, audit records, and support paths." ], "uiExamples": { "good": [ "A checkout step shows an unchecked I agree to the conditions of sale checkbox beside linked terms, blocks Place order until checked, and validates the missing agreement next to the checkbox.", "A workplace sign-in gate shows a PDF terms-of-use document, version, effective date, require-expand setting, Accept and Decline actions, and records acceptance before granting cloud-app access." ], "bad": [ "A payment button says By continuing you agree to our terms, but the terms link is hidden below the order summary and no separate acceptance state is recorded.", "A prechecked agreement checkbox also opts the user into marketing emails and partner sharing." ] }, "uxExamples": { "good": [ "A returning user sees updated terms with a change summary, old and new effective dates, a download route, an accept action, and a clear message that access pauses if they decline.", "A buyer misses a required terms checkbox, receives a field-level error, reviews the linked terms, checks the box, and then places the order with the accepted version recorded." ], "bad": [ "A user cannot access an admin app because terms changed, but the gate shows only Access denied and no policy title, version, decline route, or help path.", "A mobile checkout embeds a long legal document in a tiny fixed-height panel with no search, download, print, language, or expand option." ] }, "problemContext": [ "Legal acceptance may appear during checkout, signup, first sign-in, app installation, API onboarding, enterprise access, partner enrollment, policy updates, subscription changes, or high-risk transactions.", "The agreement may be a terms-of-service document, conditions of sale, acceptable-use policy, data-processing addendum, partner agreement, workplace terms of use, liability waiver, or regulatory disclosure.", "The acceptance record may need user identity, organization, document title, version, effective date, locale, source surface, timestamp, IP or device context, and later reacceptance state.", "Legal acceptance frequently sits near consent prompts, cookie choices, age gates, checkout review, payment buttons, and confirmation dialogs, but each decision has a different purpose and evidence requirement." ], "selectionRules": [ "Choose legal acceptance when the user must expressly agree to terms, conditions, contracts, policies, disclosures, or an updated legal document before proceeding.", "Use a required unchecked checkbox when the agreement is low to moderate risk and appears within a larger form or checkout flow.", "Use a dedicated clickwrap or terms-of-use gate when the document blocks product access, has enterprise audit needs, or must be accepted before cloud resource access.", "Use a stronger e-signature workflow when the agreement needs signer identity proof, signature placement, multi-party routing, notarization, or document execution beyond click acceptance.", "Use consent prompt for optional data processing, marketing, research, AI training, or partner sharing; do not bundle it into legal acceptance.", "Use review before submit for checking captured answers; include legal acceptance in the review only when the user can still inspect and change the agreement state.", "Use checkbox group only for ordinary independent choices, not for legal agreement evidence.", "Use age gate before legal acceptance when legal eligibility depends on age or parent authorization." ], "requiredStates": [ "Initial unchecked required agreement state.", "Terms link or embedded document state with document title, version, owner, and effective date.", "Accept enabled state after explicit agreement.", "Missing acceptance validation state.", "Accepted record state with timestamp and document version.", "Decline or cancel state with consequence explanation.", "Updated terms reacceptance state.", "Grace period or access blocked state.", "Download, print, copy, language, and mobile compact review states.", "Enterprise terms-of-use gate, device-specific acceptance, audit report, and failed record-write states." ], "interactionContract": [ "The legal acceptance control starts unchecked unless a current acceptance record already exists for the same user, document, version, and scope.", "The acceptance label names the document and links to the full terms without forcing users to leave or lose the current task.", "The primary commit action is blocked or validates with a specific missing-acceptance error until the required acceptance exists.", "Accepting writes an evidence record tied to document title, version or effective date, user, timestamp, locale, and source surface.", "Declining or canceling explains whether the user can continue in limited mode, leave checkout, contact support, or lose access after a grace period.", "Updated terms show what changed, whether reacceptance is required, and which access or transaction is blocked if declined.", "Optional marketing, tracking, research, AI training, and partner-sharing consent remain separate unchecked choices with their own withdrawal routes.", "Long terms remain reviewable on mobile through expandable, downloadable, printable, searchable, or language-specific routes." ], "implementationChecklist": [ "Identify every agreement document, owner, jurisdiction or region, version, effective date, scope, required surfaces, and evidence retention requirement.", "Decide whether the agreement needs a simple checkbox, full clickwrap gate, recurring terms-of-use access gate, or stronger e-signature workflow.", "Keep legal acceptance copy near the action it qualifies and make material terms clear and conspicuous before commitment.", "Provide full terms access, change summaries for updates, download or print routes, language variants, and mobile-friendly review.", "Record document title, version, effective date, locale, user, organization, timestamp, source surface, and acceptance or decline outcome.", "Validate missing acceptance next to the control and preserve all entered form or checkout data after the validation error.", "Separate legal acceptance from consent prompt, cookie banner, age gate, notification preferences, and marketing opt-ins.", "Test current acceptance, missing acceptance, decline, reacceptance, grace period, blocked access, failed record write, mobile layout, keyboard order, screen-reader labels, and audit export." ], "commonMisuses": [ "Relying on continued browsing, payment, account creation, or a footer link as the only acceptance signal.", "Prechecking a required terms checkbox.", "Bundling legal acceptance with optional marketing, tracking, research, or partner-sharing consent.", "Showing legal terms only after the user commits payment, signup, or access.", "Using a disabled Continue button with no field-level explanation for missing acceptance.", "Recording only a boolean accepted value without the document version or timestamp.", "Forcing users through a tiny scroll box with no way to download, print, expand, or search the terms.", "Blocking users after updated terms without showing what changed, when it takes effect, or how to get help." ], "critiqueQuestions": [ "Which exact legal document is being accepted, and what version or effective date applies?", "What action or access is blocked until acceptance exists?", "Can users review, download, print, search, or change language before accepting?", "What happens if users decline, cancel, or need more time?", "Is optional consent kept separate from legal acceptance?", "What evidence proves who accepted which document from which surface and when?", "How are updated terms, grace periods, device-specific terms, and failed acceptance records handled?" ], "relatedPatterns": [ "consent-prompt", "review-before-submit", "checkbox-group", "confirmation-dialog", "typed-confirmation", "age-gate", "checkout", "account-creation", "sign-in", "privacy-settings" ], "comparisons": [ "legal-acceptance-vs-consent-prompt-vs-review-before-submit-vs-checkbox-group-vs-confirmation-dialog-vs-typed-confirmation-vs-age-gate" ], "sourceIds": [ "stripe-checkout-custom-components-terms", "adobe-commerce-checkout-terms-conditions", "microsoft-entra-terms-of-use", "ftc-dot-com-disclosures", "docusign-clickwrap-agreements" ] }, { "id": "list-view", "completionStatus": "complete", "name": "List view", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Vertical object-summary browsing surface", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to scan, choose, open, and act on a set of objects, but tables overemphasize columns, card layouts waste space or depend on imagery, and dense row actions can make each item hard to identify or operate safely.", "solution": "Present objects as a vertical list of stable row summaries with a clear primary label, supporting text, metadata, status, optional leading media, row-scoped actions, selection and grouping state, and predictable behavior for sorting, filtering, pagination, virtualization, and detail handoff.", "uiGuidance": [ "Render a labelled vertical list where each row has a strong primary label, concise supporting text, metadata, status, optional leading media, and row-scoped actions with clear hit targets.", "Use spacing, dividers, grouping labels, unread or selected markers, and responsive stacking to keep row identity and action ownership clear without turning the list into a table." ], "uxGuidance": [ "Use list view when scanning and opening object summaries is faster than comparing columns or inspecting large visual cards.", "Preserve row identity, selection, active detail context, and scroll position as users sort, filter, paginate, refresh, or act on rows." ], "uiExamples": { "good": [ "A ticket list row shows TCK-2048 Database backup failed, a one-line incident summary, Critical status, owner, updated time, selected state, and a labelled More actions menu.", "A file list row shows a PDF icon, file name, folder path, modified date, sharing status, and a trailing Preview action that names the file." ], "bad": [ "A list row shows columns of owner, amount, due date, and status but no headers or column sort state.", "Every row has five unlabeled icon buttons, and the whole row also navigates." ] }, "uxExamples": { "good": [ "A user filters tickets to Critical, selects two rows, opens the details panel for one ticket, then clears the filter and the selected count and active ticket remain understandable.", "A keyboard user opens a row menu, archives the ticket, and focus moves to a status message naming the archived ticket and the next row." ], "bad": [ "A user selects rows, changes sort order, and the bulk action count still includes hidden rows without saying which rows are affected.", "A user tries to preview a file but the row click opens navigation while the small trailing icon deletes the file." ] }, "problemContext": [ "Items are objects such as tickets, messages, files, tasks, orders, people, alerts, search results, or resources.", "Users need to scan names and short summaries more than compare every item by the same set of columns.", "Rows may include status, metadata, unread state, thumbnail or icon, selection checkbox, trailing action, row menu, swipe action, or open-detail behavior.", "The list may be grouped, sorted, filtered, paginated, virtualized, synced with a details panel, or used as a source for bulk actions." ], "selectionRules": [ "Choose list view when each row is a compact object summary and users scan primarily by name, title, snippet, status, or recency.", "Use table when aligned columns and header-to-cell comparison are central to the task.", "Use data grid when users edit cells, navigate cells with arrow keys, select ranges, copy and paste, or operate on keyboard-managed row widgets.", "Use details panel when the selected row needs durable adjacent detail beyond the row summary.", "Use card list, card grid, or collection when images, previews, varied item sizes, or visual discovery are more important than dense row scanning.", "Use feed or timeline when item order is event-centered and users consume a stream rather than manage a collection.", "Use listbox or select when the list is a form control for choosing values rather than a browsable object surface.", "Avoid list view when every row needs many comparable attributes that would become pseudo-columns.", "Avoid list view when row actions are more important than identifying the item.", "Avoid list view when rows cannot keep labels, metadata, status, and actions readable at the target viewport width." ], "requiredStates": [ "Default list state with label or heading, row count or context, visible row summaries, and primary row identity.", "Focused row or focused row action state with visible focus and accessible row identity.", "Selected row, multi-selected row, bulk-selection count, and selected-away state when selection is supported.", "Active row state when a row controls a details panel, preview panel, route, or selected object context.", "Unread, new, updated, pinned, priority, archived, disabled, unavailable, or locked row states when applicable.", "Row action menu, primary row action, secondary trailing action, swipe action, and destructive action states.", "Grouped, sorted, filtered, searched, paginated, infinite-loaded, virtualized, and loading-more states.", "Empty list, no-results, permission-limited, loading, partial-load, and failed-load states.", "Narrow-screen state with stacked metadata, reachable actions, and preserved row identity.", "Detail-open or preview-open state when list selection drives adjacent or routed detail." ], "interactionContract": [ "Each row has one primary object identity that remains visible across selection, hover, focus, filtering, and responsive states.", "The row's primary action, checkbox, menu, and trailing action have distinct hit targets and accessible names that include the item identity.", "A row click opens, selects, or previews according to one stable rule; secondary actions do not conflict with that rule.", "Selection state is not confused with focus, hover, unread, active-detail, or checked status.", "Sorting and filtering update row order or membership while preserving selected rows, active detail context, and scroll position when possible.", "Grouping labels describe meaningful sets and do not replace row-level identity.", "Virtualized or infinite lists preserve row labels, row positions, loading boundaries, and focus restoration.", "Bulk actions clearly state which visible or hidden selected rows are affected." ], "implementationChecklist": [ "Define the row object, primary label, supporting text, metadata fields, status indicators, leading media, and available row actions.", "Choose list semantics for ordinary object rows, listbox semantics only for option selection, or grid semantics only when row interaction needs grid navigation.", "Give the list a heading or accessible label and expose row count, active filters, and selection count near the list.", "Keep row layout stable: primary text, secondary text, metadata, status, and actions should not jump when rows are selected, updated, or hovered.", "Label icon-only row actions with the object identity, such as Archive ticket TCK-1042.", "Define whether row activation opens detail, toggles selection, previews, expands, or navigates, and keep it consistent.", "Support empty, no-results, loading, error, selected, active, unread, pinned, disabled, sorted, filtered, paginated, and virtualized states deliberately.", "Test keyboard navigation, screen reader row identity, row action labels, selection count, virtualized focus restoration, long labels, localization, zoom, and mobile hit targets." ], "commonMisuses": [ "Using list view as a table without column headers or column-state feedback.", "Putting too many independent controls in every row until the list becomes a keyboard trap.", "Making the entire row, title link, checkbox, and trailing icon all trigger different undocumented actions.", "Using color alone to show unread, selected, active, pinned, or failed rows.", "Hiding status, owner, due date, or selection state on mobile so rows become indistinguishable.", "Letting filters remove selected rows without explaining whether bulk actions still affect hidden selections.", "Virtualizing rows without stable row labels, positions, loading boundaries, or focus recovery.", "Repeating the same row summary in a details panel without adding useful detail." ], "critiqueQuestions": [ "What does one row represent and what text uniquely identifies it?", "Is the user scanning object summaries, comparing columns, editing cells, or inspecting one selected object?", "What is the row's primary action, and which controls are separate secondary actions?", "Can users distinguish focus, selection, active detail, unread, pinned, disabled, and hover states?", "What happens to selected rows and active detail after sort, filter, pagination, refresh, or virtualization?", "Would table, data grid, details panel, card layout, feed, timeline, listbox, or tree grid better fit the task?" ], "relatedPatterns": [ "table", "data-grid", "details-panel", "filter-panel", "sort-controls", "pagination", "empty-state", "listbox" ], "comparisons": [ "list-view-vs-table-vs-data-grid-vs-details-panel" ], "sourceIds": [ "material-lists-guidelines", "apple-hig-lists-tables", "carbon-structured-list", "carbon-contained-list", "fluent-react-list" ] }, { "id": "listbox", "completionStatus": "complete", "name": "Listbox", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Visible selectable option list", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to choose from a visible set of static options, but collapsed selects hide comparison and generic clickable lists do not expose focus, option count, or selected state.", "solution": "Provide a labelled listbox with option roles, managed active focus, selected state, keyboard navigation, optional typeahead, clear selection policy, and no nested interactive controls inside options.", "uiGuidance": [ "Render a labelled listbox container, visible options, active option styling, selected option state, optional grouped labels, empty or disabled states, and nearby help or error text.", "Keep option content concise and non-interactive; use separate controls outside the listbox for actions such as edit, remove, move, select all, or clear." ], "uxGuidance": [ "Use a listbox when users benefit from seeing the available options while moving focus through the list and selecting one or more static values.", "Make the selection model explicit because focus, active option, and selected option may be different states." ], "uiExamples": { "good": [ "A Role listbox has a visible label, five role options, one active row, one selected row, concise option names, and a status line explaining whether focus or selection changed.", "A grouped city listbox uses group labels for countries and short city option names instead of repeating the country in every option." ], "bad": [ "Each option row contains nested Edit and Delete buttons, making the listbox a broken table of actions.", "Every option starts with the same long prefix such as United Kingdom office location, forcing users to listen through repeated text." ] }, "uxExamples": { "good": [ "A user arrows from Analyst to Support, hears the active option change, then presses Select active option to commit Support.", "A user turns on selection-follows-focus for a low-risk preview list and sees that moving focus now updates the selected value immediately." ], "bad": [ "A high-stakes role assignment saves as soon as focus moves while the user is only exploring options.", "A user tries to activate a Delete button inside an option, but assistive technology exposes the row only as one option string." ] }, "problemContext": [ "The available values should remain visible while users choose.", "Options are static enough to be represented as selectable choices rather than interactive row content.", "Users need keyboard movement through options and a perceivable selected state.", "The list may be long enough for typeahead, scrolling, Home and End, or grouping.", "The product must decide whether moving focus only previews an option or also selects it." ], "selectionRules": [ "Choose a listbox when options should remain visible and users select one or more values from the list itself.", "Use a native select when a compact closed single-choice control is sufficient.", "Use a combobox when the list is a popup controlled by an input or button and the field value owns the interaction.", "Use radio buttons or checkbox groups when the set is short and normal form controls communicate the job with less custom keyboard work.", "Use multi-select when the product pattern is a compact searchable picker with selected chips or a selected-set review surface.", "Use a grid, table, menu, or separate action toolbar when rows need buttons, links, checkboxes, toggles, or editable controls.", "Keep option names short and move repeated category context into group labels or separate controls.", "Make selection-follows-focus opt-in for low-risk preview contexts and avoid it for destructive, expensive, or externally visible changes." ], "requiredStates": [ "Empty or initial state with visible label and at least one option.", "Focused listbox state.", "Active option state distinct from selected state.", "Selected option state.", "Selection-follows-focus enabled or disabled policy state.", "Typeahead matched option state.", "First option and last option states for Home and End movement.", "Disabled option state.", "Read-only listbox state.", "Required no-selection validation state.", "Grouped options state when categories are present.", "Scrollable long-list state with preserved active visibility." ], "interactionContract": [ "The listbox has a visible label or accessible name and contains or owns every option.", "Each selectable option exposes one selected state using aria-selected or aria-checked consistently.", "Active focus is represented by DOM focus on an option or by aria-activedescendant on the listbox.", "Arrow keys move the active option; Home and End move to list boundaries when supported.", "Typeahead moves focus to the next option whose name starts with the typed character sequence.", "Single-select listboxes select at most one option; multi-select listboxes set aria-multiselectable and expose state on every selectable option.", "Moving focus changes selection only when the interaction model explicitly uses selection-follows-focus.", "Options are not containers for independent interactive controls." ], "implementationChecklist": [ "Confirm that users need a visible custom option list instead of native select, radio buttons, checkbox groups, combobox, or multi-select picker.", "Choose single-select or multi-select and document whether selection follows focus.", "Use role listbox on the container and role option on each option, or use a native control that exposes equivalent semantics.", "Give the listbox a visible label with aria-labelledby or an accessible name with aria-label.", "Use aria-activedescendant or roving DOM focus consistently and keep the active option in view.", "Expose aria-selected or aria-checked consistently, and set aria-multiselectable for multi-select lists.", "Implement Arrow keys, Home, End, typeahead, Space or Enter selection, required validation, disabled options, and read-only state.", "Move interactive row actions outside the listbox or choose a grid or table pattern.", "Test keyboard, screen reader, touch, high zoom, forced colors, long option names, repeated prefixes, grouping, scrolling, and dynamic option updates." ], "commonMisuses": [ "Using listbox when native select, radio buttons, or checkboxes would do the job with less risk.", "Putting buttons, links, checkboxes, toggles, menus, or form fields inside options.", "Treating focus and selection as identical without deciding whether selection follows focus.", "Using long repeated option labels that hide the distinguishing words.", "Leaving aria-activedescendant pointing to a removed or hidden option.", "Failing to expose unselected state in a multi-select listbox.", "Using a listbox as a command menu where options trigger actions instead of setting a value." ], "critiqueQuestions": [ "Do users need the options visible all the time, or is this really a select or combobox?", "Is focus movement separate from selection, and is that policy visible in the UI?", "Are all option names short enough to be understood as one spoken string?", "Do any options contain interactive controls that require a grid, table, menu, or toolbar instead?", "Can keyboard users reach the first option, last option, a typed prefix, disabled options, and validation errors predictably?" ], "relatedPatterns": [ "select", "combobox", "multi-select", "checkbox-group", "radio-group", "command-palette", "inaccessible-custom-select" ], "comparisons": [ "listbox-vs-select-vs-combobox-vs-multi-select" ], "sourceIds": [ "wai-aria-apg-listbox", "mdn-aria-listbox-role" ] }, { "id": "live-cursors", "completionStatus": "complete", "name": "Live cursors", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Ephemeral collaborator pointer and selection awareness with identity, color, recency, privacy, visibility controls, and stale-state handling", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Real-time collaboration becomes disorienting when people cannot tell where others are pointing, or overwhelming when remote cursors are unlabeled, stale, noisy, privacy-leaking, or mistaken for durable comments and audit evidence.", "solution": "Provide live cursor and selection overlays with identity, color, accessible labels, coordinate anchoring, opt-in or visibility controls, cursor-chat limits, stale and disconnected states, permission boundaries, and clear separation from comments, mentions, notifications, and logs.", "uiGuidance": [ "Render live cursors as lightweight overlays tied to the shared coordinate system, with person label, color, shape, current object or selection, recency, and stale or hidden state that does not obscure primary content.", "Provide controls for showing or hiding the user's pointer, reducing other users' cursor noise, following a collaborator, pinning cursor chat, and distinguishing pointer, text cursor, selection range, viewport, and temporary cursor-attached message states." ], "uxGuidance": [ "Use live cursors when collaborators need immediate spatial awareness of where other people are pointing, selecting, hovering, typing, or presenting in the same shared surface.", "Treat cursor data as ephemeral awareness rather than durable communication; add freshness, permissions, visibility controls, and fallbacks for lag, disconnects, privacy boundaries, and assistive technology." ], "uiExamples": { "good": [ "A whiteboard shows Priya's pointer with a labelled color chip, Dana's text selection range, a stale cursor fading after reconnect loss, and a toggle to hide your pointer.", "A slide editor shows live pointers only while collaborators choose to share them, with a follow-person control and cursor chat that expires after the quick exchange." ], "bad": [ "Remote cursors are unlabeled colored arrows that overlap form controls and stay frozen after users leave.", "Cursor chat looks like a permanent comment even though it is not anchored, timestamped, or retrievable." ] }, "uxExamples": { "good": [ "A presenter enables live pointers during a design review, follows Dana's cursor to a problem area, then hides extra cursors while editing text.", "A collaborator loses connection, their cursor becomes stale with last-updated text, and the app stops showing it as active until awareness resumes." ], "bad": [ "A user is trying to edit a small control while five cursor labels cover the target and there is no reduce-cursors mode.", "A live cursor exposes that an external viewer is hovering over a restricted section they should not be able to see." ] }, "problemContext": [ "Users are co-editing a document, design canvas, slide, diagram, whiteboard, code editor, map, media timeline, spreadsheet, or shared object where spatial attention matters.", "Remote signals may include mouse pointer, touch pointer, text caret, selected object, selection range, viewport focus, temporary cursor chat, and follow-mode target.", "Cursor data changes quickly, may lag or drop during network issues, and should usually remain outside durable document history.", "The surface may have many collaborators, anonymous viewers, external guests, private regions, presentation mode, mobile touch input, or assistive technology users." ], "selectionRules": [ "Choose live cursors when users need immediate spatial awareness of other collaborators' current pointer, caret, selection, viewport, or focus inside the same shared surface.", "Use presence when the user only needs to know who is available, online, viewing, away, or recently active, not exactly where they are pointing.", "Use comments when feedback must persist on a region, line, object, or document with author, timestamp, replies, resolution, and moderation state.", "Use mentions when the user needs to call attention to a person or group inside authored content.", "Use notification center when collaboration events need retained inbox triage; do not notify on ordinary cursor motion.", "Use activity log when a durable event must be recorded; do not treat raw cursor paths as history unless the product explicitly records a session.", "Use sync state and offline state for transport freshness, reconnecting, failed awareness updates, and stale cursor fallbacks.", "Use tooltip only for static help; live cursor labels and cursor chat need identity, motion, recency, and visibility behavior." ], "requiredStates": [ "Local pointer visible, local pointer hidden, remote pointer visible, remote pointer hidden, and reduced-cursor mode.", "Remote text caret, remote selection range, selected object, hover target, viewport-follow, and presentation pointer states.", "Cursor label, avatar, color, name, role, anonymous user, external guest, and duplicate-name states.", "Fresh, delayed, stale, disconnected, reconnecting, permission-hidden, and out-of-viewport cursor states.", "Cursor chat open, typing, sent, expired, dismissed, pinned temporarily, and converted-to-comment states where supported.", "Many collaborators, overlapping cursors, mobile touch pointer, high zoom, low zoom, transformed canvas, and scrolled document states.", "Follow collaborator, stop following, jump to cursor, reveal location, and do-not-follow-presenter states.", "Screen-reader summary, keyboard focus equivalent, privacy-hidden section, and reduced-motion states." ], "interactionContract": [ "Sending cursor data updates ephemeral awareness state with coordinate, target, viewport, selection, identity, color, timestamp, and visibility preference, not the saved document content.", "Remote cursors are anchored to the same transformed coordinate space as the shared content and remain accurate across scroll, zoom, pan, resize, and object transforms.", "Cursor overlays avoid blocking primary controls; users can hide their own pointer, reduce other pointers, or follow one collaborator without losing editing focus.", "Stale cursors fade, label themselves stale, or disappear according to a clear timeout instead of freezing as if live.", "Permission and privacy rules filter cursor location, object names, private regions, anonymous viewer identity, and external collaborator details before broadcasting.", "Cursor chat remains temporary unless the user deliberately converts it to a comment, task, or other durable artifact.", "Assistive technologies receive concise collaborator-location summaries and change announcements without a noisy stream of every pointer movement." ], "implementationChecklist": [ "Define awareness payloads for pointer coordinates, text caret, selection range, user identity, color, timestamp, viewport, target object, visibility preference, and privacy scope.", "Map cursor coordinates through scroll, zoom, pan, transforms, responsive layouts, and canvas scale before rendering remote overlays.", "Design cursor labels, colors, avatars, stale states, hidden states, follow mode, cursor chat, collision behavior, and reduced-cursor controls.", "Throttle and debounce pointer updates so motion feels live without flooding the network, history, notifications, or assistive announcements.", "Respect permissions for private objects, external guests, anonymous viewers, hidden pointers, view-only mode, and restricted canvas regions.", "Test many collaborators, high zoom, mobile touch, keyboard-only editing, screen reader summaries, reconnects, stale state, out-of-viewport cursors, and cursor-chat expiry." ], "commonMisuses": [ "Using live cursors as durable comments, decision records, or audit history.", "Leaving stale cursor arrows frozen after users disconnect.", "Rendering cursor labels that cover the object users are trying to edit.", "Relying only on color to identify collaborators.", "Broadcasting cursor position in private or permission-limited regions.", "Triggering notifications or feed items for ordinary pointer motion.", "Showing every collaborator cursor in dense sessions with no reduce, hide, or follow controls.", "Failing to transform cursor position correctly when the canvas is zoomed, panned, or scrolled." ], "critiqueQuestions": [ "What shared coordinate system anchors each remote cursor?", "Can users identify each cursor without relying only on color?", "What happens when cursor data is delayed, stale, disconnected, or out of viewport?", "Can users hide their own cursor or reduce other cursor overlays?", "Are private regions, anonymous users, and external guests filtered before cursor location is shared?", "Does cursor chat expire or convert deliberately into a durable comment?", "How do keyboard and screen-reader users learn where collaborators are working?" ], "relatedPatterns": [ "presence", "comments", "mentions", "threaded-discussion", "notification-center", "activity-log", "sync-state", "offline-state", "tooltip", "hover-card", "data-grid" ], "comparisons": [ "live-cursors-vs-presence-vs-comments-vs-mentions" ], "sourceIds": [ "liveblocks-live-cursors", "liveblocks-using-presence", "yjs-awareness-presence", "yjs-awareness-api", "google-slides-live-pointers", "figma-cursor-chat", "tiptap-awareness-collaboration" ] }, { "id": "loading-skeleton", "completionStatus": "complete", "name": "Loading skeleton", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Bounded content loading placeholder", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to know that predictable content is still loading while the layout stays stable and placeholders are not mistaken for real, interactive content.", "solution": "Reserve the approximate final content structure with neutral non-interactive placeholders, mark the region busy, then replace the skeleton with loaded content, empty state, or error state on a bounded path.", "uiGuidance": [ "Render neutral skeleton blocks that reserve the final content structure without fake readable text, fake controls, or focusable placeholder elements.", "Keep skeleton dimensions stable, mark the affected region busy, and use subtle or reduced-motion-respecting animation only while loading is unresolved." ], "uxGuidance": [ "Reduce uncertainty and layout shift while predictable content loads, then resolve clearly to real content, empty state, or error state.", "Use skeletons for short bounded waits and switch to explicit progress, cancellation, or error recovery when the wait becomes long or fails." ], "uiExamples": { "good": [ "Three report-card placeholders match the final card heights and are replaced by real cards without shifting the panel.", "The loading region is marked busy and placeholders are plain shapes with no readable fake labels or focusable buttons." ], "bad": [ "Skeleton rows look like clickable report cards and receive focus before content exists.", "A spinner and skeleton compete for the same region while the final content appears in a different layout." ] }, "uxExamples": { "good": [ "Users see that reports are pending, then can switch the demo to loaded, empty, or error outcomes on a bounded path.", "If loading fails, the UI moves to a persistent error state instead of continuing shimmer forever." ], "bad": [ "Skeleton never resolves.", "Keyboard focus enters placeholder-only controls or users tap fake rows that are not real content." ] }, "problemContext": [ "Content loads asynchronously and has a predictable final shape such as cards, rows, profile blocks, charts, or media tiles.", "A blank screen or centered spinner would not show where content will appear or would allow avoidable layout shift.", "The system can distinguish loading from loaded, empty, failed, and timed-out states." ], "selectionRules": [ "Choose skeletons when the final content layout is known enough to reserve stable space.", "Use skeletons for dynamic content regions rather than standalone buttons, inputs, or controls.", "Keep skeletons neutral and abstract so they do not look like real text, fake data, or tappable controls.", "Mark the loading region busy or provide a concise status so assistive technology does not treat placeholders as content.", "Transition to loaded content, empty state, error state, or cancelled state on a bounded timeline.", "Respect reduced-motion preferences when using shimmer or pulse animation.", "Use progress bars, inline loading, or explicit job status instead when progress is measurable or the task blocks action." ], "requiredStates": [ "Initial skeleton placeholder state with region marked busy.", "Loaded state where real content replaces placeholders without layout jump.", "Resolved empty state after successful loading returns no content.", "Failure or timeout state after loading cannot complete.", "Reduced-motion state for animated skeletons.", "Refresh or partial-loading state where existing content remains trustworthy while only new areas are busy." ], "interactionContract": [ "Skeleton placeholders are not focusable, clickable, selectable, or announced as real content.", "The placeholder geometry approximates the loaded content closely enough to reduce layout shift.", "The loading region communicates pending status without announcing every placeholder row.", "Loading cannot continue indefinitely without switching to error, timeout, or support messaging.", "Existing user focus remains stable while new content loads unless focus movement is required after completion.", "When loaded content arrives, busy state is removed and real controls become available." ], "implementationChecklist": [ "Reserve stable dimensions for every skeleton region.", "Match skeleton row, card, media, and text proportions to the final content density.", "Avoid fake readable text and fake interactive controls.", "Use aria-busy or equivalent status for the affected region.", "Remove busy state when content, empty, or error state resolves.", "Add timeout or failure handling so skeletons do not run forever.", "Honor prefers-reduced-motion when animating shimmer or pulse.", "Do not combine skeletons with competing spinners unless each indicator applies to a clearly different region." ], "commonMisuses": [ "Showing skeletons forever.", "Using skeletons for unknown layout shapes.", "Making placeholders look like tappable content.", "Showing skeleton after a no-results or empty response is already known.", "Leaving shimmer animation on for reduced-motion users.", "Loading into a layout that has little relationship to the placeholder." ], "critiqueQuestions": [ "Does this placeholder communicate pending structure without pretending content exists?", "What exact state replaces the skeleton if loading succeeds, returns empty, fails, or times out?", "Can keyboard and screen reader users avoid interacting with placeholder-only content?" ], "relatedPatterns": [ "empty-state", "error-state", "infinite-spinner" ], "comparisons": [ "loading-skeleton-vs-empty-state-vs-error-state" ], "sourceIds": [ "carbon-loading-component", "sap-fiori-skeleton-loading", "nord-skeleton-component", "rei-cedar-skeleton" ] }, { "id": "loading-spinner", "completionStatus": "complete", "name": "Loading spinner", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Bounded indeterminate wait indicator for a named action or region", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need immediate feedback that a specific action or region is processing, but an unlabeled or unbounded spinner can hide scope, progress, failure, and recovery.", "solution": "Show a labeled, scoped spinner only while the named operation is genuinely in flight, prevent duplicate actions, expose busy semantics for the affected region, and transition to a resolved, progress, cancelled, timeout, or error state on a defined path.", "uiGuidance": [ "Render a compact spinner only beside, inside, or over the affected action, component, or page region, and pair it with concise text that names what is loading or processing.", "Size and place the spinner according to scope: inline for a button or small row, centered within a busy component, and overlay only when the whole component or page is temporarily unavailable." ], "uxGuidance": [ "Use a loading spinner for short indeterminate waits where the system is actively working but cannot yet expose progress; resolve it quickly to content, success, cancellation, progress, or error.", "Prevent duplicate or conflicting actions while the operation is in flight, but keep context, status, safe cancellation, and timeout recovery available when the wait exceeds the expected threshold." ], "uiExamples": { "good": [ "A Pay invoice button becomes Processing payment with a small spinner, disables only duplicate payment actions, and leaves the invoice reference visible.", "A report card shows Loading Q2 summary with a spinner centered in the card while the rest of the dashboard remains usable." ], "bad": [ "A blank page shows a large spinner with no text, no affected object, and no idea what is loading.", "A search results panel shows skeleton rows, a spinner, and a progress bar for the same request." ] }, "uxExamples": { "good": [ "After submit, users see payment PAY-2048 processing, can tell the button is temporarily unavailable, and then get either success or retry guidance.", "When a filter refresh becomes slow, the spinner changes to Still loading results with Retry, Cancel, or Use previous results." ], "bad": [ "The spinner blocks the whole workspace for a small table refresh and prevents users from continuing other work.", "The spinner remains active after a failed request, so users refresh and may submit the same transaction twice." ] }, "problemContext": [ "The operation has started and is expected to finish shortly, but the system cannot calculate percent complete or meaningful stages.", "Users need reassurance that the click, submit, refresh, save, sync, or region load was received.", "The spinner belongs to a known control, card, panel, table, dialog, or page region rather than an unknown global wait.", "The product can determine when the operation resolves, times out, fails, moves to background, or should expose cancellation." ], "selectionRules": [ "Choose loading spinner when the wait is indeterminate, short, and tied to a named action or region.", "Place the spinner at the smallest useful scope: button, row, card, panel, dialog, or page region.", "Add nearby text such as Processing payment, Loading invoices, or Saving draft when the spinner is not already inside a clearly labelled control.", "Disable only controls that would duplicate, cancel incorrectly, or corrupt the in-flight operation.", "Use a skeleton instead when the content structure is predictable and layout reservation would reduce uncertainty or layout shift.", "Use determinate progress, queue status, or step progress when the system knows percent complete, item counts, stages, or queue position.", "Use error state when the operation has failed, timed out, or reached a retry limit.", "Treat it as infinite-spinner misuse when the spinner can run with no timeout, retry, cancel, background, cached, or failure path." ], "requiredStates": [ "Idle state with no spinner and the action or region ready.", "Inline processing state for a button or small local action.", "Region loading state with aria-busy or equivalent status on the affected component.", "Overlay loading state when the whole component or page must temporarily block interaction.", "Resolved state after content, save, sync, or submit succeeds.", "Slow-threshold state that changes copy or exposes retry, cancel, previous values, background, or support path.", "Cancelled state when the user can stop a noncritical wait safely.", "Failed state that removes busy state and hands off to persistent recovery." ], "interactionContract": [ "The spinner appears only after the operation starts and disappears or changes state when the operation resolves, fails, is cancelled, or moves to background.", "The spinner is attached to the affected object so users can tell what is busy.", "The loading label names the operation unless the enclosing control already does so unambiguously.", "Duplicate submit, save, payment, import, or refresh actions are temporarily disabled or guarded while the request is in flight.", "Unrelated navigation, reading, editing, or cancellation remains available unless the whole surface is genuinely unavailable.", "Long waits cross a threshold into clearer status and recovery instead of remaining a spinner-only state.", "Assistive technology receives a concise busy or progress announcement and does not remain busy after resolution." ], "implementationChecklist": [ "Define spinner scope, expected wait threshold, timeout threshold, and terminal states for each operation.", "Write a loading label that names the operation and object, such as Processing payment PAY-2048.", "Use aria-busy on the affected region or a named progress/status element for the spinner.", "Guard duplicate submission and double-click cases without hiding all safe alternatives.", "Switch to determinate progress when backend percent, stages, counts, or queue position become available.", "Switch to recovery after timeout with actions such as Retry, Cancel, Use previous results, Move to background, or Contact support.", "Remove disabled and busy states when loading resolves, fails, cancels, or goes to background.", "Respect reduced-motion preferences by reducing animation where platform conventions allow." ], "commonMisuses": [ "Showing an unlabeled spinner on a blank page.", "Using a spinner forever instead of timeout, retry, or error recovery.", "Blocking an entire page for a local row or button operation.", "Leaving the original action enabled so users can submit twice.", "Using a spinner when progress is measurable and should be determinate.", "Showing spinner, skeleton, and progress bar for the same request.", "Keeping aria-busy set after loading succeeds or fails." ], "critiqueQuestions": [ "What exact action or region does the spinner belong to?", "Can users tell what is processing without guessing from animation alone?", "Which controls must be disabled to prevent duplicate work, and which safe actions should remain available?", "When does the spinner become progress, content, success, timeout, cancellation, or error?", "What happens if users press Back, refresh, retry, or submit again during the spinner state?", "Does assistive technology receive a named busy state and a clear resolved or failed state?" ], "relatedPatterns": [ "loading-skeleton", "infinite-spinner", "error-state", "disabled-button-no-explanation" ], "comparisons": [ "loading-spinner-vs-loading-skeleton-vs-infinite-spinner-vs-error-state" ], "sourceIds": [ "carbon-loading-component", "material-design-progress-indicators", "apple-hig-progress-indicators", "mdn-aria-progressbar" ] }, { "id": "location-permission-flow", "completionStatus": "complete", "name": "Location permission flow", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Permission-gated current-location request and recovery flow", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Current-location access can remove manual entry and improve nearby, routing, check-in, safety, and device-context tasks, but it is highly sensitive, permission-gated, precision-dependent, failure-prone, and easy to misuse when prompt timing, fallback, stale coordinates, background access, and retention are unclear.", "solution": "Ask for location only after a clear user action and task rationale, request the least precision and shortest scope that satisfies the task, handle grant, denial, timeout, stale data, unavailable service, and revoked permission, provide manual or saved-location fallback, show active tracking and stop controls, and state storage or retention rules.", "uiGuidance": [ "Render location access as a task-scoped flow with purpose text, current permission state, requested precision, scope, native-prompt handoff, granted fix, denied recovery, manual fallback, stale-coordinate labels, and stop-sharing controls.", "Keep location indicators, accuracy, last-updated time, retention copy, and fallback actions close to the feature that needs location rather than hiding them in generic settings or a map-only surface." ], "uxGuidance": [ "Use a location permission flow when current device coordinates materially reduce effort or improve a location-dependent task and users can understand why location is needed before the browser or OS prompt appears.", "Design the lifecycle from unsupported or insecure context through pre-prompt rationale, permission prompt, one-time or while-using grant, precise or approximate choice, current fix, timeout, stale coordinate, denial, settings recovery, manual location, active tracking, stop sharing, and retention." ], "uiExamples": { "good": [ "A route check-in says Use current location to confirm you are at Gate B, offers Use current location or Enter address, accepts approximate location for city-level help, and labels the returned fix as accurate to 42 m.", "A store finder explains it needs location only to sort nearby stores, lets users continue with a ZIP code, and shows Last updated 2 minutes ago when cached coordinates are reused.", "A safety app shows Location sharing on for this session, visible accuracy, Stop sharing, and a retention note before it starts continuous tracking." ], "bad": [ "The home page triggers the browser location prompt before users choose any location-dependent action.", "A denied prompt leaves a blank map and tells users to refresh without manual entry, saved place, retry, or settings recovery.", "The app asks for precise and background location even though approximate while-using access is enough." ] }, "uxExamples": { "good": [ "A user taps Check in nearby, grants Allow once, sees the current fix and accuracy, confirms the place, and the app discards coordinates after check-in.", "A user denies location in a browser, enters an address manually, and can finish the route search without changing settings.", "A user has previously denied location, sees concise settings instructions plus saved home and manual address options, then retries after enabling access." ], "bad": [ "A user chooses delivery estimate and the app demands precise location even though postal code entry would work.", "A cached coordinate from a previous trip is used for a nearby alert without a stale timestamp.", "A user closes the page after active tracking starts but cannot tell whether sharing stopped or where retained location history lives." ] }, "problemContext": [ "The product wants current coordinates for nearby search, delivery estimate, check-in, route start, location-based support, safety sharing, field work, fraud signals, personalization, or device-local context.", "Users may be on web, mobile, desktop, kiosk, VPN, low signal, disabled location services, approximate-location mode, previously denied permission, background-restricted OS state, offline mode, or a shared device.", "The request may need one-time, while-using, session, background, precise, approximate, watched, or manual-location behavior depending on task risk and accuracy requirements.", "Location permission flow sits near generic permission request, map view, address entry, privacy settings, offline state, sensitive-data reveal, and saved place selection." ], "selectionRules": [ "Choose location permission flow when current device coordinates are the central interaction and the task needs permission timing, precision, grant or denial recovery, and location lifecycle states.", "Use permission request when the resource access pattern is generic and not specifically about current coordinates, stale location, accuracy, tracking, or manual location fallback.", "Use map view when users mainly inspect or manipulate spatial information such as markers, routes, regions, or layers.", "Use address entry when a typed, searched, pasted, or saved postal address is sufficient and device coordinates would add privacy cost.", "Use privacy settings for durable location-history, sharing, analytics, app permission, or account-level controls outside the immediate task.", "Use offline state when connectivity prevents loading or submitting data; do not confuse network loss with location services disabled or permission denied.", "Request the least precision that satisfies the task, and accept approximate location where city, region, store sorting, or content localization is enough.", "Ask at the moment location helps the chosen task, not on app launch, sign-in, page load, hover, or unrelated navigation.", "Preserve task progress and offer manual address, saved place, retry, or settings recovery after denial, timeout, unavailable service, or stale coordinate.", "Expose active tracking, background use, stop sharing, and retention copy whenever location continues beyond a one-time current-position fix." ], "requiredStates": [ "Unsupported browser, blocked iframe, missing permissions policy, insecure context, or disabled location services state.", "Pre-permission rationale state with task purpose, precision need, scope, retention, and fallback.", "Prompt-ready state triggered by a deliberate user action.", "Allow once or one-time current-position state.", "While using or session permission state.", "Precise versus approximate location choice or explanation state.", "Background location denied or not requested state.", "Granted current fix state with coordinates summarized as place, accuracy, and timestamp.", "Permission denied state with manual fallback and retry guidance.", "Permanently denied or settings-required state with concise browser or OS settings recovery.", "Timeout, unavailable, low-accuracy, or position-error state.", "Stale cached coordinate state with last-updated time and refresh option.", "Manual address, ZIP, place search, or saved location fallback state.", "Active tracking or watch-position state with visible indicator.", "Stop sharing, revoke, or end session state.", "Privacy and retention state explaining what location is stored, for how long, and where to delete it.", "Offline state that distinguishes no network from no location permission." ], "interactionContract": [ "The native browser or OS prompt appears only after users understand why location is needed and choose a location-dependent action.", "The UI makes permission state, requested precision, requested scope, active tracking, last-updated time, and fallback status visible in text, not only through icons.", "Denial, timeout, unavailable service, approximate-only result, and stale coordinate states never erase the user's task context.", "Users can complete the task through manual address, saved place, place search, retry, or settings recovery when current location is unavailable.", "One-time or session location ends after the task unless users explicitly choose continued sharing.", "Location retention, sharing, background use, and deletion paths are disclosed before or immediately after sensitive location capture." ], "implementationChecklist": [ "Define the task purpose, required precision, acceptable fallback, permission scope, retention rule, and whether a one-time fix or continuous watch is needed before building the prompt.", "Use secure contexts and platform permission APIs where available; handle prompt, granted, denied, revoked, blocked, timeout, unavailable, and unsupported states explicitly.", "Request location from a user action such as Use current location, Check in, Find near me, or Share trip, not on route load.", "Configure maximumAge, timeout, and high-accuracy options to match the task, then show accuracy and last-updated labels when a result is used.", "Provide manual address entry, saved places, search by ZIP, retry, and settings recovery routes that preserve the original task.", "Separate one-time current-position fixes from watch-position or background sharing, and expose Stop sharing or End session for active tracking.", "Avoid storing raw latitude, longitude, movement history, or inferred home/work locations unless the user understands purpose, duration, and deletion controls.", "Test denied permission, previously denied permission, approximate location, disabled location services, stale cache, low signal timeout, offline mode, keyboard, screen reader, mobile OS prompts, and browser settings recovery." ], "commonMisuses": [ "Prompting for location before users choose a task that needs it.", "Requesting precise or background location when approximate or while-using access is enough.", "Treating permission denial as a dead end instead of offering address entry, saved place, retry, or settings recovery.", "Showing stale cached coordinates as current location.", "Using a map view as if it explained permission, accuracy, retention, or tracking state.", "Continuing to watch or store location after the task without a visible indicator or stop control.", "Mislabeling a permission denial or disabled location service as an offline state." ], "critiqueQuestions": [ "What task action triggers the location prompt, and what rationale appears before the native permission dialog?", "Is precise location necessary, or would approximate, ZIP, address, or saved place satisfy the task?", "What happens after one-time grant, while-using grant, denial, permanent denial, timeout, stale coordinate, unavailable service, and offline state?", "How does the UI show accuracy, age, active tracking, stop sharing, and retention?", "Can users complete the task without changing browser or OS settings?", "Is this really location permission flow, or is the main pattern a generic permission request, map view, address entry, privacy settings, or offline state?" ], "relatedPatterns": [ "permission-request", "map-view", "address-entry", "privacy-settings", "offline-state", "sensitive-data-reveal" ], "comparisons": [ "location-permission-flow-vs-permission-request-vs-map-view-vs-address-entry-vs-privacy-settings-vs-offline-state" ], "sourceIds": [ "mdn-geolocation-api", "mdn-geolocation-getcurrentposition", "w3c-geolocation", "mdn-permissions-api", "w3c-permissions-api", "android-runtime-permissions", "apple-privacy-location-services-settings", "mapbox-gl-js-geolocate-control" ] }, { "id": "login", "completionStatus": "complete", "name": "Login", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Credential-verification attempt lifecycle and login outcome handling", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Login attempts must communicate security-sensitive outcomes without confirming account existence, encouraging brute-force attempts, confusing legitimate users, or turning lockout controls into denial-of-service problems.", "solution": "Model login as a verification lifecycle with safe pending, success, failure, retry, throttling, lockout, unlock, support, and audit states; use neutral messages, policy-accurate attempt and wait-time feedback, password-manager support, and recovery routes that let legitimate users continue safely.", "uiGuidance": [ "Render login as the outcome-sensitive credential verification state: pending verification, neutral failure, remaining attempts or wait time when policy allows, throttling or lockout state, unlock or recovery route, and successful session-created confirmation.", "Keep login outcome handling separate from the broader sign-in journey, account creation, password-field mechanics, profile setup, and session-timeout warnings." ], "uxGuidance": [ "Use login when users have already chosen an authentication route and submitted credentials or an authenticator output, and the product must explain the verification result safely.", "Help legitimate users recover from failed attempts without leaking account status, creating denial-of-service risk, blocking password managers, or hiding the time and route for retry or unlock." ], "uiExamples": { "good": [ "After a failed login, the page keeps the email address, clears the password, shows Check your details and try again, gives 2 attempts remaining, and keeps forgot password and use passkey routes available.", "After too many attempts, a login page says Try again in 10 minutes or unlock your account by email, while avoiding separate wrong-password and locked-account signals for enumeration." ], "bad": [ "The page says Password wrong for one email and No account found for another.", "After failures, the login button silently disables with no wait time, no recovery route, and no accessible challenge alternative." ] }, "uxExamples": { "good": [ "A user mistypes the password twice, sees remaining attempts and a neutral account-details error, uses a passkey instead, and reaches the intended workspace with retry warnings cleared.", "A user is temporarily throttled, sees the wait time, can unlock through verified email, and does not need support for a routine lockout." ], "bad": [ "A user gets locked out after repeated typos with no warning and no explanation of when to retry.", "A bot challenge appears after one failed login but has no accessible alternative, blocking legitimate users." ] }, "problemContext": [ "A user has submitted an account identifier, password, passkey assertion, one-time code, SSO return, or other authenticator output.", "The product must decide whether to establish a session, request another factor, delay the next attempt, lock an authenticator, or route to recovery.", "Incorrect outcome copy can expose whether an account exists, whether a password was wrong, whether an account is disabled, or whether a lockout threshold was hit.", "Security policy may require failed-attempt counters, observation windows, exponential backoff, CAPTCHA or bot checks, risk-based step-up, self-service unlock, or administrator unlock.", "Legitimate users may be typing under stress, using password managers, returning after a failed attempt, or trying to unlock without losing their original destination." ], "selectionRules": [ "Choose login when the user has submitted credentials or an authenticator and the UI must show the result, next retry, lockout, or session-created state.", "Use sign in for the broader entry journey, destination context, method choice, SSO routing, and recovery navigation before or around login attempts.", "Use password input for the individual current-password field and visibility behavior; login owns the attempt lifecycle after submission.", "Use session timeout warning when the user is already authenticated and must extend, save, sign out, or reauthenticate before expiry.", "Use generic failed-login copy that avoids distinguishing unknown account, wrong password, locked account, disabled account, or unverified account unless a safer authenticated support path is available.", "Show remaining attempts, wait time, or unlock route only when doing so does not create a stronger enumeration or denial-of-service vector for the product.", "Clear or hide secrets after failed login, preserve the identifier when appropriate, and keep password-manager and paste behavior available.", "Treat throttling, bot checks, CAPTCHA, risk-based step-up, temporary lockout, permanent lockout, support escalation, and successful login as distinct states.", "After successful login, establish or rotate the session, reset retry counters where policy permits, remove stale warnings, and continue to the authenticated destination.", "Log and monitor failed and successful login events without exposing secrets in analytics, logs, session replay, screenshots, or user-visible URLs." ], "requiredStates": [ "Ready-to-submit login state with chosen identifier and authenticator route.", "Submitting or verifying state that prevents duplicate login attempts without hiding progress.", "Generic failed-login state with retry and recovery.", "Remaining-attempts warning state when policy allows visible counters.", "Throttled state with wait time or retry-after information.", "Temporary lockout state with unlock route or recovery path.", "Permanent or support-required lockout state.", "Bot check, CAPTCHA, or risk challenge state with accessible alternative.", "Successful login state with session-created and destination-continuation behavior.", "Security notice state for unusual or recent login when product policy requires surfacing it." ], "interactionContract": [ "Submitting credentials enters one clear verifying state and prevents duplicate submissions until the login result returns.", "Failed-login copy stays neutral across unknown account, wrong password, disabled account, unverified account, and lockout conditions unless the user has already passed a safer verification route.", "Password or secret values are cleared, hidden, or protected after failure according to policy, while non-secret identifiers can remain editable.", "Retry counters, wait time, and lockout copy match the server-side policy and cannot be faked by a client-only timer.", "Recovery, unlock, passkey, forgot-password, and support routes preserve the originating destination when policy permits.", "Successful login clears failed-attempt state, creates the authenticated session, and continues to the destination supplied by the surrounding sign-in journey.", "Bot checks or CAPTCHA do not become the only route for users who cannot complete the presented challenge." ], "implementationChecklist": [ "Define failed-attempt thresholds, observation windows, throttle delays, lockout duration, retry reset, unlock routes, support routes, and logging with security owners.", "Map every login outcome to safe copy: success, generic failure, throttled, temporary lockout, permanent lockout, password expired, MFA needed, passkey unavailable, SSO failed, bot challenge, and recovery sent.", "Ensure response text, HTTP status, redirect path, error code, timing, analytics, and URL do not reveal account existence or exact failure reason.", "Use server-backed retry-after and lockout state rather than a client-only countdown.", "Keep password managers, paste, autofill, passkeys, and accessible alternatives working through failures, throttling, and recovery.", "Test wrong identifier, wrong password, repeated failures, success after failure, wait-period retry, lockout, unlock email, administrator unlock, CAPTCHA alternative, passkey fallback, browser Back, mobile keyboards, screen readers, high contrast, and deep-link continuation." ], "commonMisuses": [ "Returning different messages for unknown account, wrong password, disabled account, or locked account.", "Silently disabling the login button after failure with no wait time or recovery path.", "Showing a client-only attempt counter that disagrees with server policy.", "Using CAPTCHA as the only route after failed attempts.", "Locking an account permanently without self-service or support escalation where policy permits recovery.", "Leaving stale failure or lockout messages after successful login.", "Logging passwords, one-time codes, passkeys, or detailed failure reasons into analytics or session replay." ], "critiqueQuestions": [ "Which exact login outcomes can the server return, and which are safe to distinguish in the UI?", "Can the visible attempt count, wait time, and unlock route be trusted as server-backed state?", "Does any copy, redirect, status code, error code, timing, URL, analytics event, or support route reveal account existence?", "What happens to the password or authenticator output after failed login, Back, refresh, and session timeout?", "How do legitimate users recover from throttling, lockout, inaccessible CAPTCHA, expired password, SSO failure, or passkey failure?", "Does successful login clear stale warnings and continue to the intended authenticated destination?" ], "relatedPatterns": [ "sign-in", "password-input", "session-timeout-warning", "account-creation", "permission-denied-state" ], "comparisons": [ "login-vs-sign-in-vs-password-input-vs-session-timeout-warning" ], "sourceIds": [ "owasp-authentication-login-throttling", "owasp-wstg-weak-lockout-mechanism", "nist-sp-800-63b-rate-limiting", "owasp-authentication-account-enumeration", "mdn-input-password" ] }, { "id": "long-press", "completionStatus": "complete", "name": "Long press", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Sustained pointer contact that reveals secondary actions, selection, preview, or drag pickup", "maturity": "standard", "platforms": [ "mobile", "web", "desktop", "spatial" ], "problem": "Long press is useful for secondary touch actions, but sustained hidden contact is hard to discover, easy to confuse with tap, scroll, swipe, drag, context menus, and tooltips, and inaccessible when it replaces visible or keyboard-reachable controls.", "solution": "Design long press as an optional sustained-contact shortcut with visible teaching, threshold feedback, movement tolerance, cancellation, equivalent controls, clear destination, and recovery or confirmation for risky outcomes.", "uiGuidance": [ "Show long press as a sustained-contact gesture with a discoverable hint, press progress, hold threshold, cancellation, release behavior, and a visible non-gesture equivalent.", "Use long press for secondary or accelerated item actions such as selection mode, context menu, preview, reorder pickup, or inspect details; never make it the only route to primary or critical work." ], "uxGuidance": [ "Use long press when a touch-first surface needs a secondary action that benefits from deliberate dwell time and can coexist with tap, scroll, swipe, and drag.", "Define the hold duration, movement tolerance, haptic or visual feedback, cancel path, equivalent menu or button, and post-hold destination before implementation." ], "uiExamples": { "good": [ "A file tile shows a short Touch and hold for actions hint, displays a hold ring after press down, opens a context menu at the tile after threshold, and keeps a visible More actions button.", "A task card enters selection mode after a long press, announces 1 task selected, shows a selection toolbar, and lets keyboard users select the same task with a checkbox." ], "bad": [ "A long press silently deletes an item with no hint, progress, confirmation, undo, or visible alternative.", "A press-and-hold tooltip contains required instructions but cannot be reached by keyboard or screen reader users.", "A long press starts drag pickup while users are trying to scroll the list." ] }, "uxExamples": { "good": [ "A user touches and holds a photo, sees the hold progress cross threshold, receives haptic feedback, then a context menu opens with Copy, Share, Favorite, and Delete.", "A user starts holding a row but moves beyond tolerance while scrolling; the hold cancels and the row scrolls normally.", "A screen reader user opens the same item actions through custom actions or More actions instead of needing sustained contact." ], "bad": [ "A user taps a card slowly and accidentally opens a hidden destructive menu.", "A user with tremor cannot keep contact still for the full threshold and has no alternate control.", "A mouse user sees a hover tooltip but the touch user must guess that touch and hold exists." ] }, "problemContext": [ "A touch-first surface has objects, cards, rows, messages, files, canvas items, map markers, or media that support secondary actions.", "The same target may also support tap-to-open, double tap, swipe action, drag pickup, text selection, scroll, context menu, hover tooltip, or popover.", "Users may need selection mode, item actions, preview, inspect details, reorder pickup, copied text actions, or temporary reveal.", "The product must support users who cannot sustain contact, cannot keep a pointer still, use keyboard or switch control, use a screen reader, or interact with a mouse and trackpad." ], "selectionRules": [ "Choose long press when the design problem is a sustained-contact gesture and its threshold, feedback, cancellation, and equivalent action path.", "Use touch gesture when the question is the broader vocabulary and fallback contract across tap, swipe, pinch, drag, and other gestures.", "Use context menu when the main question is the menu surface, command grouping, focus movement, and target-specific command scope after invocation.", "Use tooltip when the surface only supplies short supplemental text and no interactive controls.", "Use popover when the target opens nonmodal contextual content with richer text or controls.", "Use action menu when commands should be opened from a visible trigger instead of relying on sustained contact.", "Use swipe action when a horizontal row gesture reveals or commits an item action.", "Use drag and drop when sustained contact is only the pickup phase for moving an object to a destination.", "Provide a visible More actions button, menu, checkbox, shortcut, or custom action for every long-press-only outcome.", "Do not use long press for primary, urgent, destructive, payment, consent, account, security, or required instructions." ], "requiredStates": [ "Idle target state with visible identity and alternate action path.", "Gesture hint state that teaches touch and hold without relying on hover.", "Press down state that identifies the target before threshold.", "Hold progress state showing duration or affordance before action fires.", "Threshold reached state with haptic, visual, or status feedback.", "Release-before-threshold cancellation state that leaves data unchanged.", "Movement-tolerance cancellation state when the user scrolls, swipes, drags too far, or leaves the target.", "Context menu, preview, selection mode, or drag-pickup destination state after threshold.", "Disabled or unavailable long-press state with explanation.", "Equivalent action-menu, visible control, keyboard, screen reader, switch, and pointer path.", "Destructive or high-impact action handoff to undo, confirmation, or review.", "Mobile compact, large-text, one-handed, landscape, and assistive-touch states." ], "interactionContract": [ "Long press starts only from a target that intentionally supports sustained contact.", "The interface gives press-down feedback immediately and progress or dwell feedback before threshold when the delay is noticeable.", "The gesture cancels cleanly if the user releases before threshold, moves beyond tolerance, begins vertical scroll, starts an incompatible swipe, or presses Escape on an equivalent path.", "Crossing threshold opens a named destination such as context menu, selection mode, preview, inspect panel, or drag pickup rather than performing an unexplained action.", "Tap, double tap, swipe action, pull-to-refresh, drag, and system gestures have explicit priority rules against long press.", "Every outcome is available through a non-gesture equivalent with matching disabled, pending, success, and recovery states.", "Destructive outcomes after long press require explicit tap, confirmation, or undo according to reversibility.", "Status messaging names the target and action when long press changes selection, opens actions, or completes work." ], "implementationChecklist": [ "Inventory each long-press target, purpose, duration threshold, movement tolerance, destination, action scope, and equivalent control.", "Decide whether long press opens a context menu, enters selection mode, shows preview, starts drag pickup, reveals hidden controls, or performs another specific outcome.", "Add visible teaching such as More actions, selection checkbox, handle, hint text, or onboarding only where users need to discover the shortcut.", "Implement press-down feedback, progress feedback, haptic feedback where platform appropriate, threshold reached state, cancellation, and release behavior.", "Resolve conflicts with tap, double tap, scroll, swipe action, pull-to-refresh, drag pickup, text selection, hover tooltip, popover, and system gestures.", "Expose the same actions through buttons, menus, keyboard, screen reader custom actions, context menu key, switch control, or other assistive paths.", "Route destructive or high-impact outcomes through confirmation, undo, delayed commit, or review rather than committing on threshold.", "Test slow tap, tremor, accidental movement, long text selection, nested scrollers, one-handed use, large text, screen reader touch exploration, keyboard, switch, mouse, trackpad, stylus, and mobile landscape." ], "commonMisuses": [ "Hiding required or primary actions behind undiscoverable long press.", "Using long press as a tooltip that contains required or interactive content.", "Committing destructive work as soon as the hold threshold is reached.", "Failing to cancel when users release early or start scrolling.", "Conflicting with swipe action, drag pickup, text selection, or pull-to-refresh on the same target.", "Providing no keyboard, screen reader, switch, mouse, or visible menu equivalent.", "Using hover hints to teach a touch gesture.", "Making the required hold duration too long, too short, or inconsistent across similar targets." ], "critiqueQuestions": [ "What exact outcome happens after the hold threshold: menu, selection, preview, drag pickup, or action?", "How do users discover that touch and hold is available before needing it?", "What hold duration, movement tolerance, and cancellation rules prevent accidental activation?", "What visible or accessible control performs the same outcome without sustained contact?", "How do tap, scroll, swipe action, pull-to-refresh, drag, text selection, context menu, and system gestures avoid conflict?", "What happens if the target becomes disabled, moves, or changes state during the hold?", "Does any destructive outcome require confirmation, undo, or explicit activation after reveal?" ], "relatedPatterns": [ "touch-gesture", "context-menu", "tooltip", "popover", "action-menu", "swipe-action", "drag-and-drop-upload" ], "comparisons": [ "long-press-vs-touch-gesture-vs-context-menu-vs-tooltip-vs-popover-vs-action-menu" ], "sourceIds": [ "material-design-gestures", "android-gesture-detector-common-gestures", "apple-hig-gestures", "w3c-wcag-target-size-minimum", "w3c-wcag-pointer-gestures" ] }, { "id": "map-view", "completionStatus": "complete", "name": "Map view", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Spatial viewport for location-based objects, layers, and routes", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to make decisions from geographic position, distance, route, density, region, or coverage, but list, table, and calendar surfaces flatten location into text and hide spatial relationships.", "solution": "Provide a Map view with coordinate-anchored objects, pan and zoom, marker selection, popups or details, clustering, layers, geolocation recovery, viewport-aware counts, route or radius context, legends, and a synchronized non-map fallback.", "uiGuidance": [ "Render a real spatial viewport with visible map region, zoom state, scale or distance context, markers or shapes anchored to coordinates, selected-place detail, cluster counts, visible layer/filter controls, and a fallback list or table for the same results.", "Show marker states, selected marker, popup or side-detail position, cluster expansion, geolocation permission state, route or radius overlays, legends, empty-region state, and loading or stale-tile states without depending on color or pointer hover alone." ], "uxGuidance": [ "Use Map view when the user's decision depends on where objects are, how far apart they are, what falls inside the current area, which route or coverage applies, or how dense nearby points are.", "Keep spatial interaction honest: panning, zooming, filtering, clustering, geolocation, route preview, and popup selection must update counts, bounds, fallback list, distance context, and focus in ways that preserve the selected place." ], "uiExamples": { "good": [ "A clinic finder map shows visible bounds, zoom level, selected clinic marker, appointment availability markers, a transit layer toggle, cluster counts, distance chips, and a synchronized results list.", "An operations incident map shows sensor markers, outage polygons, a legend, selected incident popup, service-radius overlay, stale-data badge, and keyboard-accessible place list." ], "bad": [ "A decorative map background contains unlabeled pins with no coordinate meaning, no current region, no selected marker, no legend, and no list fallback.", "A store locator uses a full map but every pin overlaps, cluster counts are missing, distance is not shown, and the popup floats away from the selected location." ] }, "uxExamples": { "good": [ "A dispatcher pans to the west district, the result count and list update to the current bounds, a cluster expands at closer zoom, and the selected incident popup remains tied to the marker.", "A traveler denies location permission, enters an address instead, sees nearby stations sorted by distance, toggles bike-lane and transit layers, and previews a route without losing the selected station." ], "bad": [ "A user filters to open locations but the map markers update while the list still shows closed locations, causing the wrong branch to be selected.", "A location permission prompt is rejected and the entire locator becomes unusable even though manual search or a saved address exists." ] }, "problemContext": [ "Locations, assets, incidents, events, service areas, deliveries, rooms, or routes are meaningful because of where they are.", "Users may need to pan, zoom, search within bounds, inspect clusters, choose a nearby item, compare distance, or understand coverage.", "Maps often combine basemap tiles, vector layers, markers, routes, polygons, popups, clustering, filters, and browser geolocation.", "Location permission, stale tiles, dense markers, hidden layers, offscreen popups, and unsynchronized fallback lists can make a map misleading.", "Map view must remain usable for keyboard users, low-vision users, users who deny location, and users who need a structured list instead of visual geography." ], "selectionRules": [ "Choose Map view when spatial relationship, proximity, coverage, route, region, or real-world placement changes the user's decision.", "Use list view when the main task is scanning object summaries and location can be represented as text or a distance sort.", "Use table when users need aligned field comparison, bulk review, or export of records.", "Use calendar view when time placement, duration, availability, or recurrence matters more than geography.", "Use data visualization when the task is aggregate trend, distribution, or metric analysis rather than choosing place-level objects.", "Use search results when ranked matching is primary and map position is secondary.", "Cluster dense markers and disclose cluster counts when markers overlap or density makes individual selection unreliable.", "Show the current area, active layers, filters, location source, selected marker, and result count so the map's scope is not ambiguous.", "Provide a fallback list, table, or accessible result summary that stays synchronized with the map bounds and filters.", "Avoid Map view when coordinates are decorative, approximate without disclosure, or unrelated to the user's decision.", "Avoid Map view as the only control when geolocation permission or map tile loading can fail." ], "requiredStates": [ "Default map state with visible viewport, zoom level or distance context, markers, layer state, result count, and synchronized fallback list.", "Marker selected, marker focused, popup open, popup dismissed, side detail open, and selected item in fallback list.", "Clustered markers, expanded cluster, dense overlap, empty region, filtered region, hidden layer, and hidden-result count states.", "Panning, zooming, search-this-area, fit-to-results, route preview, radius selection, and layer toggle states.", "Geolocation requested, allowed, denied, unavailable, manual-location fallback, and approximate-location disclosure states.", "Loading tiles, failed tiles, stale map data, slow network, offline fallback, and attribution visible states.", "Keyboard marker navigation, list fallback navigation, popup focus return, and non-pointer route or selection states.", "Responsive state where map controls, selected detail, bounds count, and fallback list remain reachable on mobile." ], "interactionContract": [ "Markers, shapes, routes, clusters, and overlays represent explicit coordinates, features, or geographic areas, not decorative positions.", "Panning, zooming, filtering, layer toggling, and search-this-area update visible markers, counts, selected detail, and fallback list from the same result set.", "Selecting a marker opens a popup or detail that names the place, explains relevant distance or status, and provides a keyboard path back to the marker and fallback list.", "Clusters expose count and category composition when useful, and users can expand, zoom, or inspect contained items without losing map context.", "Geolocation is optional unless the task truly requires it; denied or unavailable location provides manual search, saved location, current map area, or list fallback.", "Legends and text labels explain marker color, shape, heat, route, polygon, radius, and layer meaning.", "Distances, routes, travel times, and service areas state origin, unit, mode, approximation, and stale-data status when those affect the decision.", "Keyboard and assistive-technology users can reach layer controls, search, result list, selected place details, and map movement alternatives without pointer-only gestures." ], "implementationChecklist": [ "Define feature schema: id, name, coordinate, geometry type, category, status, distance, availability, popup fields, route metadata, layer, timestamp, and permissions.", "Define viewport model: center, zoom, bounds, selected feature, active filters, active layers, result count, cluster state, and fallback-list ordering.", "Implement marker selection, popup or side detail, fit-to-results, search-this-area, cluster expansion, layer toggles, radius or route preview, and manual location fallback.", "Keep map markers, cluster counts, fallback list, search results, and selected detail synchronized after pan, zoom, filter, layer, and geolocation changes.", "Model empty region, dense cluster, denied location, unavailable geolocation, stale data, failed tiles, hidden layer, offscreen popup, and mobile stacked layouts.", "Show attribution, legends, scale or distance context, location source, and result scope near the map.", "Test keyboard access, popup focus return, marker labels, high marker density, long place names, small screens, slow tiles, and denied browser permissions.", "Use a proven map SDK or service for projection, panning, tile loading, clustering, geolocation, and geometry math in production rather than inventing spatial math." ], "commonMisuses": [ "Using a map as decoration when the positions do not affect the task.", "Showing markers without labels, selected state, popup detail, count, or fallback list.", "Letting dense markers overlap without clustering or zoom guidance.", "Treating geolocation denial as a dead end.", "Changing map filters without updating list results and result counts.", "Showing route, distance, radius, or service area without units, origin, mode, or approximation.", "Hiding layer meaning behind color-only markers with no legend.", "Making panning, zooming, popup opening, or marker selection pointer-only." ], "critiqueQuestions": [ "What spatial decision does the map make easier than a list, table, calendar, or chart?", "Can users tell the current area, zoom, layer state, result count, and selected marker?", "Do markers, clusters, popups, fallback list, filters, and bounds update from the same data?", "What happens when markers overlap, map tiles fail, location permission is denied, or the selected marker moves offscreen?", "Can keyboard and assistive-technology users inspect places and complete the task without dragging or hovering on the map?", "Would a list view, table, calendar view, data visualization, or search result list better fit the task?" ], "relatedPatterns": [ "list-view", "card-list", "card-grid", "table", "data-grid", "calendar-view", "filter-panel", "search-scope-selector", "details-panel", "empty-state" ], "comparisons": [ "map-view-vs-list-view-vs-calendar-view-vs-table" ], "sourceIds": [ "google-maps-info-windows", "google-maps-marker-clustering", "mapbox-gl-js-markers", "mapbox-gl-js-clusters", "mapbox-gl-js-geolocate-control", "leaflet-quick-start-map-markers-popups", "arcgis-javascript-popup", "arcgis-javascript-feature-reduction-cluster" ] }, { "id": "master-detail", "completionStatus": "complete", "name": "Master-detail", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Adaptive source list and detail layout with coordinated selection and navigation state", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to explore a set of items and inspect or work with one item's full detail repeatedly, but separate pages make context switching slow, a small details panel cannot hold the full destination, and a fixed layout can fail across phones, tablets, foldables, and desktop windows.", "solution": "Provide an adaptive master-detail layout with a source list, detail destination, synchronized selected item, empty detail placeholder, stacked detail navigation, Back to list behavior, side-by-side presentation on wider screens, and preserved list, selection, filter, scroll, edit, and route state across layout changes.", "uiGuidance": [ "Render a master-detail layout with a primary list or source pane, a detail pane that names the selected item, a visible selected-item indicator, and a clear empty-detail state when no item owns the detail.", "Adapt the same content relationship between side-by-side panes on wider screens and stacked list/detail navigation on narrower screens, with visible Back to list or equivalent return control in stacked mode." ], "uxGuidance": [ "Use master-detail when users move repeatedly between a collection of items and full detail content, and the detail can act as a navigable destination rather than only a small inspector.", "Preserve selected item, detail scroll or edit state, list position, filters, and return path as users select items, open detail, go back, and resize or rotate the viewport." ], "uiExamples": { "good": [ "An inbox shows conversations in the left pane and the selected message thread in the right pane on desktop, then shows either the conversation list or selected thread with Back to inbox on phone.", "A customer order app keeps the order list, selected order highlight, order detail heading, shipment timeline, and Back to orders path synchronized across side-by-side and stacked layouts." ], "bad": [ "Selecting an order highlights one list item while the detail pane still shows a previous order.", "On mobile, tapping a list item replaces the list with detail but provides no return path, selected-item label, or preserved list position." ] }, "uxExamples": { "good": [ "A user selects a case, scrolls its detail history, narrows the window to stacked mode, goes back to the case list, selects another case, and widening the window shows the new selected case beside the list.", "A keyboard user moves through the master list, opens a detail, returns to the same list position, and the selected row remains tied to the detail heading." ], "bad": [ "A user filters the master list after opening detail and the layout keeps showing a hidden case without saying it no longer matches the filter.", "A user rotates a tablet and the app resets to the first list item, discarding the detail draft and scroll position." ] }, "problemContext": [ "The source items are conversations, orders, tickets, files, contacts, tasks, articles, cases, settings sections, media, or records.", "The detail content is substantial enough to need its own heading, body, local actions, history, comments, edits, or route state.", "Users often switch between adjacent items while keeping enough context to know where the current detail came from.", "The same product must work in narrow stacked mode and wider side-by-side mode without losing selection or navigation history." ], "selectionRules": [ "Choose master-detail when list selection opens or owns a full detail destination and the layout must coordinate source and detail state.", "Choose master-detail when wide screens should show list and detail together while narrow screens should show either list or detail with a return path.", "Use details panel when the detail is a concise adjacent inspector and does not need navigable page-like behavior.", "Use list view when users only need to scan and act on rows without a coordinated detail destination.", "Use window splitter when users need to resize panes; pair it with master-detail only if the list-detail behavior is also defined.", "Use drawer or sheet when detail is temporary, opened by command, and should close after a side task.", "Use preview panel when the detail is primarily rendered document, media, or file preview rather than full object work.", "Use full-page navigation when side-by-side context adds little value or the detail is too deep for a shared layout.", "Avoid master-detail when no stable selected item exists.", "Avoid master-detail when responsive transitions would lose detail state, list position, or back navigation." ], "requiredStates": [ "Wide default state with master list, selected item, and detail pane visible together.", "Wide empty-detail state with a prompt when no item is selected.", "Stacked list state where only the master list is visible.", "Stacked detail state with selected-item heading and Back to list control.", "Selection changed state where list highlight, detail heading, route state, and local actions update together.", "Filtered-away selected item state with explanation, clear-filter path, or selection replacement.", "Viewport widened, narrowed, rotated, or folded state preserving list position, selected item, and detail state.", "Loading, failed detail, deleted item, permission-limited detail, unsaved detail draft, and unavailable detail states.", "Back navigation, browser history, deep link, and no-selection return states.", "Multiple-pane or tertiary detail state when the layout can add supporting content on large screens." ], "interactionContract": [ "Selecting an item in the master list updates the selected marker and detail heading to the same object.", "In side-by-side mode, selection can update detail without hiding the master list.", "In stacked mode, opening detail moves to the detail view and Back to list returns to the same master list position and filters.", "Changing viewport size preserves the current selected object and chooses whether list, detail, or both panes should be visible based on the active navigation state.", "If the selected item becomes filtered, deleted, or unavailable, the detail pane explains the state instead of showing stale content.", "Detail-local actions state which selected item they affect and do not silently act on a different master row.", "Deep links can open the detail directly and still provide a path to the relevant master list when the product supports it.", "Unsaved changes, scroll position, focus, and local detail state survive layout changes or trigger explicit review before being discarded." ], "implementationChecklist": [ "Define the master collection, selected-item ID, detail route or state owner, empty-detail rule, and compact versus expanded layout breakpoints.", "Render a visible selected state in the master list and repeat the selected object name or ID in the detail heading.", "Implement stacked navigation with Back to list, browser history, focus return, and preserved list scroll position.", "Implement side-by-side mode with synchronized selection, detail refresh, and an empty placeholder when no selection exists.", "Persist selected item, filters, sort order, list scroll, detail scroll, local edits, and focus across viewport changes.", "Handle loading, failed detail fetch, deleted item, permission-limited detail, filtered-away item, no results, and direct deep link states.", "Keep resizable splitters, drawers, previews, and inspectors separate from the master-detail ownership model unless deliberately combined.", "Test keyboard selection, screen reader pane names, Back behavior, browser history, mobile rotation, tablet resize, long titles, localization, zoom, and stale-detail prevention." ], "commonMisuses": [ "Calling a small metadata inspector master-detail when the detail cannot act as a destination.", "Forgetting the stacked mobile return path from detail back to the master list.", "Showing stale detail after selection, filter, delete, permission, or refresh changes.", "Resetting selection, filters, draft edits, or scroll position when the viewport crosses a breakpoint.", "Using a splitter as the only implementation while leaving selected-item ownership and navigation history undefined.", "Showing an unrelated default detail on wide screens before the user has selected an item.", "Embedding full primary editing in the detail without unsaved-change protection across selection changes.", "Letting list and detail actions target different objects because they are keyed by visible index instead of stable item ID." ], "critiqueQuestions": [ "What is the master collection, and which exact selected item owns the detail right now?", "Can the detail stand as a navigable destination, or is it only an inspector suited to details panel?", "What happens to selection, list position, detail scroll, and draft state when the layout switches between stacked and side-by-side?", "How do users return from detail to the list on compact screens?", "What should the wide layout show when there is no selection, a hidden selection, or a deleted item?", "Would list view, details panel, preview panel, drawer, window splitter, table, or full-page route better fit the task?" ], "relatedPatterns": [ "details-panel", "list-view", "window-splitter", "drawer", "preview-panel", "back-link", "breadcrumbs", "table", "data-grid", "pagination" ], "comparisons": [ "master-detail-vs-details-panel-vs-list-view-vs-window-splitter" ], "sourceIds": [ "microsoft-list-details-pattern", "android-canonical-list-detail", "material-canonical-layouts", "apple-hig-split-views" ] }, { "id": "mega-menu", "completionStatus": "complete", "name": "Mega menu", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Large grouped disclosure panel under top-level navigation", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users on large sites or products need to understand and choose among many related destinations without drilling through multiple pages or being overwhelmed by an unstructured site map.", "solution": "Provide a scoped mega menu from a top-level navigation trigger when a section has enough child destinations to justify a wide grouped panel, with clear grouping, accessible disclosure behavior, and responsive destination parity.", "uiGuidance": [ "Use a mega menu as a wide disclosure panel attached to a top-level navigation item, with grouped headings, scannable link columns, and a clear relationship to the trigger that opened it.", "Keep the panel focused on one navigation section; separate utilities, account actions, search, and unrelated service links from destination groups." ], "uxGuidance": [ "Use mega menus to expose a deep hierarchy before users commit to a destination, reducing drill-down when a section has many related pages.", "Make opening, closing, and keyboard movement predictable: explicit trigger state, Escape dismissal, outside-click dismissal, visible focus, and no focusable hidden links." ], "uiExamples": { "good": [ "A Products trigger opens a full-width panel with grouped columns for Build, Operate, Analyze, and Govern, each with concise links and one highlighted featured destination.", "A government services header uses a mega menu only for a section with many child pages and keeps search, language, and sign-in controls outside the panel.", "A mobile breakpoint turns each mega-menu section into stacked accordion groups with the same destinations available." ], "bad": [ "A mega menu opens for a section that only has three links, adding a large empty panel instead of a simple dropdown.", "The panel mixes Products, Help, Billing, Sign out, promotional cards, and unrelated external links under one trigger.", "Collapsed panels stay in the tab order, so keyboard users traverse invisible links." ] }, "uxExamples": { "good": [ "A user opens Products, scans grouped links, selects Data pipeline, and the panel closes while the destination becomes the current section.", "A keyboard user opens the panel with Enter, moves through visible links, presses Escape, and focus returns to the Products trigger.", "A pointer user moves diagonally from the trigger to a lower-column link and the panel remains open long enough to avoid accidental closure." ], "bad": [ "The panel appears only on hover, closes while the pointer crosses a gap, and forces the user to restart navigation.", "A user expects the Products trigger to navigate to a landing page, but it only opens a panel with no fallback link.", "Desktop has product links in the mega menu, while mobile hides half of them inside an unlabeled drawer." ] }, "problemContext": [ "The information architecture has a few top-level sections, but at least one section has many child destinations.", "Users need to compare related destinations before navigating.", "The product or site has enough horizontal space on desktop and a planned equivalent interaction on small screens." ], "selectionRules": [ "Choose a mega menu when a top-level section has a deep hierarchy or more links than a basic dropdown can comfortably present.", "Keep the number of top-level triggers small enough that the header still scans as primary navigation.", "Group links by user-understandable categories, not internal ownership or database structure.", "Use a simple dropdown, landing page, side navigation, or search when the section has too few links for a mega menu.", "Keep utility links and account actions outside the panel unless the trigger specifically represents those tools.", "Provide an explicit trigger state with aria-expanded and ensure collapsed panel links are not focusable.", "Close the panel on Escape, outside click, selecting a destination, or activating the trigger again.", "Provide a mobile equivalent that preserves the same destinations in a drawer, accordion, or stacked disclosure structure." ], "requiredStates": [ "Closed state with a clear top-level trigger and visible submenu indicator.", "Open panel state with grouped columns and visible focusable links.", "Active destination state after a link is selected and the panel closes.", "Keyboard dismissal state where Escape closes the panel and returns focus to the trigger.", "Pointer forgiveness state where diagonal movement into the panel does not immediately close it.", "Responsive state where the same groups and links are available in mobile navigation.", "No-JavaScript or fallback state where parent destinations remain reachable." ], "interactionContract": [ "Activating a mega-menu trigger opens the panel and updates aria-expanded on that trigger.", "Only one mega panel is open at a time unless the design deliberately supports side-by-side comparison.", "Hidden panel links are removed from the tab order and accessibility tree or otherwise made unavailable until the panel opens.", "Selecting a destination closes the panel and navigates or updates the current destination state.", "Escape closes the panel and restores focus to the trigger that opened it.", "Hover behavior is forgiving and never the only way to open or use the menu.", "The responsive version exposes the same destination set as desktop." ], "implementationChecklist": [ "Audit the IA first and confirm which top-level sections actually need large grouped panels.", "Write group headings and link labels from user language, keeping repeated words out of every link where a group label can carry the context.", "Use button semantics for triggers that only open panels; use a separate link when the parent also has a destination page.", "Set aria-expanded on the trigger and keep panel visibility synchronized with focus, pointer, route, and viewport changes.", "Hide collapsed-panel links from keyboard focus and screen readers.", "Implement Escape, outside-click, trigger-toggle, destination-selection, and viewport-change closing behavior.", "Test diagonal pointer movement, keyboard order, screen reader announcement, mobile parity, and destination-current state." ], "commonMisuses": [ "Using a mega menu as a complete site map.", "Opening a huge panel for a shallow section.", "Mixing utilities, account actions, and unrelated marketing links with navigation destinations.", "Relying on hover alone for access.", "Leaving hidden links focusable when the panel is closed.", "Dropping or renaming destinations at mobile breakpoints.", "Using ARIA menu roles for ordinary site navigation links." ], "critiqueQuestions": [ "Which top-level section has enough child destinations to justify a mega menu?", "Can users predict what is inside the panel from the trigger label?", "Are group headings based on user tasks rather than internal teams?", "What is the exact keyboard path to open, choose, and dismiss the panel?", "Does mobile expose the same destinations without a second hidden IA?" ], "relatedPatterns": [ "global-navigation", "navigation-drawer", "side-navigation", "service-navigation", "in-page-anchor-navigation" ], "comparisons": [ "mega-menu-vs-global-navigation-vs-navigation-drawer" ], "sourceIds": [ "uswds-header-component", "wai-flyout-menus", "wai-apg-disclosure-navigation", "carbon-global-header" ] }, { "id": "mentions", "completionStatus": "complete", "name": "Mentions", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Inline recipient reference with autocomplete, stable recipient identity, notification routing, access checks, and broad-audience safeguards", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Collaboration breaks when inline @ references are treated as decorative text, notify the wrong audience, ignore access boundaries, fail to disambiguate similar names, or send recipients to a generic page instead of the exact context.", "solution": "Provide inline mention insertion with scoped suggestions, stable recipient IDs, visible recipient type, ambiguity resolution, permission checks, audience warnings, notification routing, preference-aware delivery, and direct return links to the mention context.", "uiGuidance": [ "Render mentions as inline tokens or highlighted text that preserve a stable recipient identity, display name, avatar or team marker, recipient type, and selected state without breaking surrounding editable text.", "Show mention suggestions at the caret with names, handles, avatars, teams, channels, availability or scope hints, permission warnings, and keyboard-highlight state; distinguish exact matches, ambiguous display names, unavailable recipients, and broad-audience mentions." ], "uxGuidance": [ "Use mentions when a user needs to call attention to a person, team, channel, role, or group from inside a message, comment, task, document, issue, or thread while keeping the reference embedded in the authored content.", "Bind each selected mention to notification, permission, assignment, follow-up, or deep-link behavior so recipients know why they were mentioned and can return to the exact context where the mention appeared." ], "uiExamples": { "good": [ "A comment composer opens a suggestion list after @, shows people and teams with avatars, handles, access labels, and keyboard focus, then inserts a mention chip for Priya Rao.", "A broad @channel mention shows audience size, muted-thread limits, and a confirmation warning before the message is sent." ], "bad": [ "The editor highlights every @word as a mention even when it is plain text and has no recipient identity.", "A suggestion list shows three Alex users with identical labels and lets the sender submit without disambiguating which person will be notified." ] }, "uxExamples": { "good": [ "A user mentions @Dana in a private incident note, sees that Dana lacks access, chooses Invite and mention, and the resulting notification opens the exact note.", "A user types @platform-oncall, sees the team size and notification policy, confirms the broad recipient, and the team mention remains searchable and preference-aware." ], "bad": [ "A user mentions someone in a private channel, the person is not notified, and the sender receives no warning or recovery path.", "A mention notification opens the record homepage rather than the exact comment sentence, forcing the recipient to search for why they were pulled in." ] }, "problemContext": [ "Users are composing messages, comments, documents, tasks, issues, pull requests, notes, tickets, or thread replies and need to draw attention to specific people or groups.", "Mentionable targets may include individuals, teams, channels, roles, user groups, on-call rotations, bots, or workspace-wide audiences with different notification and permission rules.", "Mentions can create notifications, action items, task ownership, inbox filters, search handles, or audit events, but they remain embedded in authored content.", "The recipient may lack access, have notifications paused, share a display name with another person, belong to a broad audience, or receive the mention through a team preference." ], "selectionRules": [ "Choose mentions when the interaction begins in prose or rich text and the user needs an inline reference that targets a recipient or audience.", "Use object picker when the user is selecting owners, reviewers, approvers, assignees, or recipients as a structured field rather than writing a message.", "Use comments when the product needs anchored conversation state; mentions can live inside comments but should not carry reply, resolve, edit, or delete behavior by themselves.", "Use threaded discussion when the core task is following a branchable topic conversation; mentions inside replies should notify without changing the thread hierarchy.", "Use notification center for the retained inbox where mention events are read, filtered, muted, or opened after delivery.", "Use typeahead or combobox for the suggestion-list interaction, but add mention-specific recipient identity, access, and notification semantics.", "Warn before broad mentions that reach a channel, team, workspace, or chat, especially when audience size, quiet hours, or admin rules make the effect large.", "Do not send a mention silently when the target cannot see the object, private channel, document, issue, or thread; show invite, request access, remove, or send-without-notify choices according to product policy." ], "requiredStates": [ "Empty composer, @ trigger, loading suggestions, no results, and filtered suggestions.", "Highlighted suggestion, keyboard-selected suggestion, mouse or touch-selected suggestion, and inserted mention token.", "Individual, team, channel, user group, role, bot, and broad-audience mention states where the product supports them.", "Ambiguous display name, duplicate handle, unavailable recipient, deleted user, deactivated account, and external guest states.", "Recipient lacks access, sender lacks permission to mention, admin-restricted broad mention, guest-restricted broad mention, and invite-before-mention states.", "Notification sent, notification suppressed by preferences or paused status, thread-limited mention, failed notification, and retry or remove states.", "Mention edited, mention removed, pasted mention text, copied mention, escaped plain @ text, and serialized mention ID states.", "Direct-linked mention state where the recipient opens the exact message, comment, reply, task, or document location." ], "interactionContract": [ "Typing @ opens a suggestion list scoped to the current workspace, channel, object, permission boundary, and caret location.", "Selecting a suggestion inserts an inline token bound to a stable target ID, not just the visible display name.", "Arrow keys move through suggestions, Enter or Tab commits the highlighted target, Escape closes suggestions without deleting typed text, and Backspace removes or edits the mention predictably.", "Submitting content validates access, broad-audience policy, duplicate recipients, quiet-hour or paused-notification behavior, and notification preferences before delivery.", "If a recipient cannot see the content, the sender gets a clear warning and an allowed recovery path such as invite, request access, remove mention, or send without notifying.", "Mention notifications deep-link to the exact sentence, comment, task, reply, or document location and highlight the mention or its containing item on arrival.", "Editing a mention updates the target identity, display text, notification rules, and audit or activity evidence according to product policy." ], "implementationChecklist": [ "Define mentionable target types, stable IDs, display labels, handles, avatars, membership, visibility, notification policy, broad-audience rules, and serialization format before building the editor.", "Implement caret-aware suggestion positioning, keyboard navigation, loading and empty states, duplicate-name disambiguation, screen-reader labels, touch-safe rows, and mobile viewport behavior.", "Validate access and notification outcomes at submit time, including private spaces, guest users, deactivated users, muted threads, paused notifications, broad mentions, and admin restrictions.", "Design warning and recovery flows for broad mentions, unavailable recipients, missing access, duplicate mentions, failed notification delivery, and mention edits.", "Ensure copied, pasted, edited, deleted, and rendered mentions preserve or intentionally drop target identity with visible feedback.", "Test notification deep links, inbox filtering, search, action-item creation, assignment side effects, audit evidence, localization of display names, and ambiguous names." ], "commonMisuses": [ "Parsing @words after submit without requiring the sender to choose a real recipient.", "Treating a mention suggestion list as a generic people picker and ignoring caret position, inline serialization, and notification side effects.", "Allowing broad mentions with no audience size, policy, quiet-hours, or confirmation warning.", "Mentioning people who cannot access the object and giving neither sender nor recipient a recoverable path.", "Using mentions as the only assignment mechanism without creating task ownership, due state, or completion behavior.", "Letting ambiguous display names, renamed users, deactivated users, or external guests collapse into the same visible token.", "Sending notification links to the top of a page rather than the exact mention context.", "Failing to distinguish person mentions, team mentions, channel mentions, bots, roles, and plain @ text." ], "critiqueQuestions": [ "What stable target ID is bound to each visible mention token?", "Can the sender tell whether they are mentioning a person, team, channel, role, bot, or broad audience?", "What happens when several people match the same display name or handle?", "Can every mentioned recipient see the underlying object or conversation?", "Does the interface warn before broad mentions and respect admin, guest, quiet-hours, and notification-preference rules?", "Where does the recipient land when they open the mention notification?", "Does a mention also create assignment, task, or audit state, and is that state visible outside the prose?" ], "relatedPatterns": [ "comments", "threaded-discussion", "notification-center", "object-picker", "typeahead", "activity-log", "permission-denied-state", "review-queue", "feed" ], "comparisons": [ "mentions-vs-comments-vs-threaded-discussion-vs-notification-center" ], "sourceIds": [ "slack-use-mentions", "slack-channel-workspace-mentions", "microsoft-teams-mentions", "atlassian-confluence-mentions", "github-team-notifications", "github-issues-mentions" ] }, { "id": "menu-menubar", "completionStatus": "complete", "name": "Menu / menubar", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Persistent composite command bar with menus and submenus", "maturity": "standard", "platforms": [ "web", "desktop" ], "problem": "Complex applications may have many stable commands, but scattering those commands across buttons, popovers, and hidden shortcuts makes discovery, grouping, disabled state, and keyboard execution unpredictable.", "solution": "Provide a persistent menu or menubar with top-level command groups, managed composite focus, submenus, checked and disabled command state, predictable keyboard navigation, activation, dismissal, and focus return.", "uiGuidance": [ "Render a labelled command menubar with stable top-level command groups, visible focused item, open submenu, menu items, checked items, disabled items, separators, shortcut hints, and nested submenu indicators.", "Keep the menubar focused on application commands and command state; do not use desktop menu semantics for ordinary site navigation, page link lists, or large promotional panels." ], "uxGuidance": [ "Use a menu or menubar when users benefit from a stable command system that organizes many related functions into predictable groups such as File, Edit, View, Insert, and Format.", "Make command discovery and execution predictable by preserving the command hierarchy, supporting arrow-key movement, showing unavailable commands, exposing checked state, and returning focus to the invoking context." ], "uiExamples": { "good": [ "A document editor exposes File, Edit, View, and Insert as a persistent menubar, with Save, Rename, Export, Undo, Paste unavailable, Show comments checked, and Theme as a nested submenu.", "A data-grid application has a Commands menubar with Row, Column, View, and Tools groups, each using separators and disabled items to explain command availability.", "An enterprise desktop web app uses a vertical menubar for a canvas with command groups and sets aria-orientation to vertical." ], "bad": [ "A marketing site header marks Home, Products, Blog, Pricing, and Sign out as a menubar but behaves like normal links.", "The menu contains search fields, sliders, toggles, and date pickers inside menuitem rows instead of command items or checkable menu items.", "Collapsed submenus remain focusable and aria-expanded says true after the submenu disappears." ] }, "uxExamples": { "good": [ "A user tabs into File, presses Right Arrow to Edit, Down Arrow to open Edit commands, arrows to Undo, activates it, and focus returns to the editor canvas.", "A user opens View, toggles Show comments, and the menuitemcheckbox state remains checked until toggled again.", "A user opens View, moves into Theme, opens the nested submenu, chooses High contrast, and returns to the parent command context predictably." ], "bad": [ "A user expects Right Arrow to move from File to Edit, but the page scrolls because focus is not managed as a composite widget.", "A disabled Paste command is removed entirely, so users cannot tell that paste exists but depends on clipboard content.", "A user presses Escape from a submenu and focus jumps to the browser chrome instead of the parent menu item or editor context." ] }, "problemContext": [ "The product behaves like an application or editor with many stable commands.", "Commands need grouping by intent such as file operations, editing, viewing, insertion, formatting, or tools.", "Users benefit from seeing command categories persistently while the submenu content stays compact.", "Some commands are unavailable, checked, or open nested submenus depending on current context.", "Keyboard users need a desktop-style interaction model that does not require tabbing through every submenu item from the page." ], "selectionRules": [ "Choose a menu or menubar when the interface has a stable, application-like command hierarchy that users revisit frequently.", "Use a menu button when a single local trigger reveals a short command list for one object, row, or toolbar.", "Use command palette when commands need search, ranking, fuzzy matching, recents, or cross-product discovery.", "Use global navigation, tabs, side navigation, or mega menu when the primary job is choosing destinations rather than invoking commands.", "Use select, listbox, radio group, checkbox group, or multi-select when the user is choosing values for data, filters, or preferences rather than executing commands.", "Use menuitemcheckbox or menuitemradio for command state that belongs inside the menu, not a nested checkbox, toggle, or radio control.", "Keep disabled commands visible when their existence matters, expose aria-disabled, and do not allow activation.", "Avoid ARIA menu and menubar roles unless the implementation supports the full composite keyboard model." ], "requiredStates": [ "Persistent closed menubar state with labelled top-level command groups.", "Focused top-level menuitem state.", "Open submenu state connected to its parent menuitem with aria-haspopup and aria-expanded.", "Focused submenu item state.", "Nested submenu open state with parent item focus return.", "Activated command state with menu closed and focus returned to the invoking context.", "Checked menuitemcheckbox or menuitemradio state.", "Disabled but focusable menu item state.", "Separator or group state for command sections.", "Typeahead, Home, and End movement state.", "Escape dismissed state.", "Tab exit state with all menus closed.", "Horizontal and vertical orientation states where applicable." ], "interactionContract": [ "The persistent bar has role menubar and a visible label or accessible name.", "Top-level command items use menuitem, menuitemcheckbox, or menuitemradio roles and are managed with roving tabindex or aria-activedescendant.", "A parent menuitem with a submenu exposes aria-haspopup and synchronized aria-expanded state.", "Submenus use role menu and are labelled by or otherwise connected to the parent item that opened them.", "Right and Left Arrow move between top-level items in a horizontal menubar; Down and Up Arrow open or move inside vertical submenus.", "Enter or Space activates a command, toggles checked state, or opens a submenu according to the item role.", "Escape closes the current menu and returns focus to the parent menuitem, menubar item, or invoking context.", "Tab exits the composite widget and closes open menus rather than moving through every hidden command.", "Disabled menu items remain focusable when following the application-menu model but cannot activate.", "Hidden submenus are not reachable by keyboard or assistive technology while closed." ], "implementationChecklist": [ "Confirm this is an application command system, not ordinary navigation or a one-off overflow menu.", "Inventory command groups and keep top-level labels stable, short, and task-recognizable.", "Use role menubar for the persistent command bar and role menu for submenus only when implementing composite keyboard behavior.", "Implement roving tabindex or aria-activedescendant so one item owns focus at a time.", "Expose aria-haspopup and aria-expanded on items that open submenus and aria-checked on checkable menu items.", "Implement Right, Left, Down, Up, Home, End, printable-character typeahead, Enter, Space, Escape, and Tab exit behavior.", "Keep disabled commands visible when they teach availability, expose aria-disabled, and prevent activation.", "Use separators and groups to keep command sections scannable without creating focus stops.", "Test nested submenus, screen reader announcements, shortcut conflicts, high zoom, forced colors, pointer hover, touch fallback, route changes, and focus return to the editing context." ], "commonMisuses": [ "Using role menubar for a normal website header or product navigation row.", "Using a menubar when one menu button or visible toolbar actions would be simpler.", "Putting form controls, sliders, date pickers, editable fields, or arbitrary cards inside menuitem rows.", "Leaving hidden submenu items in the tab order.", "Letting aria-expanded drift away from the visible submenu state.", "Making disabled commands unfocusable or invisible when users need to understand unavailable capabilities.", "Using hover as the only way to open submenus.", "Overriding browser, operating-system, or assistive-technology shortcuts with custom menu shortcuts." ], "critiqueQuestions": [ "Is this truly a persistent application command system, or is it navigation, a toolbar, or a local overflow?", "Can users move between top-level command groups with Arrow keys without tabbing through every submenu item?", "Do checkable and disabled commands expose state through menu item semantics rather than nested controls?", "Does Escape close the correct level and return focus to the parent command or invoking context?", "Are hidden submenus removed from focus and screen reader reach while closed?" ], "relatedPatterns": [ "menu-button", "mega-menu", "global-navigation", "header", "command-palette", "select", "listbox" ], "comparisons": [ "menu-menubar-vs-menu-button-vs-mega-menu-vs-global-navigation" ], "sourceIds": [ "wai-aria-apg-menu-menubar", "mdn-aria-menubar-role", "mdn-aria-menu-role", "adobe-spectrum-menu" ] }, { "id": "menu-button", "completionStatus": "complete", "name": "Menu button", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Button-controlled popup menu of actions or links", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need access to a short set of contextual commands, but showing every secondary action as a visible button crowds the interface and hiding commands behind unnamed popups breaks predictability.", "solution": "Provide a named button that controls a menu of actions or links, exposes expanded state, moves focus into the menu, supports composite keyboard navigation, activates one command at a time, and returns focus to the trigger on close.", "uiGuidance": [ "Render a named button trigger, visible opened state, controlled popup, menu items, active item styling, disabled item state, separator or section grouping, and a safe way to distinguish destructive commands.", "Keep menu items as clear verbs or destinations, keep the menu compact, and avoid placing arbitrary forms, long content, nested page layouts, or primary task completion inside the popup." ], "uxGuidance": [ "Use a menu button when users need to reveal a short contextual set of commands or links from a single trigger without leaving the current object or toolbar context.", "Make dismissal, activation, focus return, unavailable actions, and high-risk command handoff predictable so the menu behaves like a command chooser rather than a hidden form." ], "uiExamples": { "good": [ "A table row has a Report actions button that opens a compact menu with Open, Rename, Duplicate, Archive, and an unavailable Export item.", "A toolbar has a More actions button with secondary commands grouped after visible primary actions and a separator before destructive commands.", "A navigation menu button opens a short list of destination links and returns focus to the trigger when dismissed." ], "bad": [ "An unlabeled ellipsis opens a loose panel of buttons, inputs, links, toggles, and destructive commands with no active item.", "A primary Save action is hidden behind More while lower-priority icons remain visible.", "Hover opens the menu but keyboard focus stays on the page and aria-expanded remains false." ] }, "uxExamples": { "good": [ "A user opens Report actions, arrows to Duplicate report, activates it, and focus returns to the Report actions trigger with a status update.", "A user arrows to Archive report and the menu closes into a confirmation flow instead of archiving directly.", "A user presses Escape while focus is in the menu and returns to the trigger without losing the current row context." ], "bad": [ "A user tabs into a menu and lands in a text input because the menu contains unrelated form controls.", "A user hovers over an ellipsis, the panel opens visually, but keyboard users cannot reach the first item or dismiss it with Escape.", "A destructive menu item runs immediately from a compact overflow menu without confirmation, undo, or object context." ] }, "problemContext": [ "An object, row, card, toolbar, or header has more actions than should be visible at once.", "The commands are contextual and short enough to scan without search.", "Users need to know whether each item runs an action, opens a destination, is unavailable, or requires a confirmation step.", "The popup should be transient and dismissible without committing a value.", "The interaction must work for pointer, keyboard, touch, and assistive technology users." ], "selectionRules": [ "Choose a menu button when one trigger reveals a short local set of actions or command-like links.", "Use a command palette when the command set is broad, searchable, cross-product, shortcut-driven, or includes navigation across distant areas.", "Use a select, listbox, radio group, or checkbox group when users are choosing values for a form field rather than invoking commands.", "Use a confirmation dialog after a high-risk menu item is chosen when the user must review object, consequence, and recovery before the action runs.", "Use visible buttons instead of a menu when there are only one or two frequent safe actions and hiding them would slow the task.", "Use a header or global navigation pattern when the main design problem is screen orientation or top-level destination switching, not a local trigger-popup widget.", "Do not use an unnamed icon as the only clue for unfamiliar actions; the trigger and every item need an accessible name that explains the target or outcome.", "Keep menu content to menu items, optional sections, separators, shortcuts, descriptions, and selection indicators; move forms, complex editors, tables, and long content into dialogs, popovers, panels, or pages." ], "requiredStates": [ "Closed trigger state with visible or accessible name.", "Open state with aria-expanded true and a controlled menu.", "First active item after opening from Enter, Space, or Down Arrow.", "Last active item after opening from Up Arrow.", "Hover and keyboard focus state for each menu item.", "Activated safe command state with menu closed and focus returned.", "Escape dismissed state with no command committed.", "Outside-click or blur dismissal state.", "Disabled or unavailable menu item state.", "Destructive or high-risk command state that opens confirmation or recovery.", "Grouped section or separator state when commands have different scopes.", "Long label, narrow viewport, and forced-colors states." ], "interactionContract": [ "The trigger is a button or equivalent control with a clear name, aria-haspopup set to menu or true, and aria-expanded synchronized with visibility.", "The popup has role menu, is labelled by the trigger or a clear menu label, and contains only menuitem, menuitemcheckbox, menuitemradio, group, and separator semantics as appropriate.", "Opening the menu moves focus to a menu item or sets aria-activedescendant to the active item.", "Arrow keys move the active item inside the menu and do not scroll the page while the menu owns focus.", "Enter or Space activates the focused menu item or toggles menu item selection according to the item role.", "Escape closes the menu and returns focus to the trigger.", "Tab leaves the transient menu by closing it and continuing in the page focus order.", "Disabled items are perceivable as unavailable and cannot be activated.", "Destructive items either open a confirmation or provide an immediate recovery path instead of running silently from a small menu.", "The menu closes after normal command activation unless the item intentionally opens a submenu or toggles a menuitemcheckbox or menuitemradio state." ], "implementationChecklist": [ "Inventory the commands and keep only a short contextual set in the menu.", "Give the trigger a visible label when possible, or a precise accessible name such as Report actions when space requires an icon.", "Set aria-haspopup, aria-expanded, and aria-controls consistently with the popup state.", "Use role menu plus menuitem roles only when implementing composite menu keyboard behavior; use simpler links or buttons when a normal disclosure list is enough.", "Move focus into the menu on open, track one active item, and return focus to the trigger on Escape, outside dismissal, or activation.", "Implement Arrow Up, Arrow Down, Home, End, typeahead when useful, Enter, Space, Escape, pointer activation, and touch activation.", "Expose disabled, checked, destructive, shortcut, description, and section states in text and semantics, not only color.", "Route destructive menu items into confirmation, undo, or recovery flows with the affected object still visible.", "Test screen reader announcements, keyboard focus, zoom, narrow width, forced colors, touch hit area, portal placement, clipping, and scroll containers." ], "commonMisuses": [ "Using a menu button for long value selection that should be a select, listbox, combobox, or multi-select.", "Using role menu for ordinary page navigation or a simple list of links without implementing menu keyboard behavior.", "Opening only on hover or closing before keyboard users can reach the first item.", "Leaving aria-expanded stale after the menu opens or closes.", "Putting inputs, sliders, date pickers, editable tables, or large explanatory content inside the menu.", "Hiding primary or emergency recovery actions in a compact overflow menu.", "Using identical item labels such as Open, Open, Open without object context.", "Running destructive commands from the menu without confirmation, undo, or object-specific feedback." ], "critiqueQuestions": [ "Is this a short local command set, or does the user need searchable product-wide commands?", "Can users predict what the trigger controls before opening it?", "Are item labels verbs or destinations with enough object context?", "Does keyboard focus move into the menu, move between items, and return to the trigger on close?", "Are disabled, destructive, and selected items exposed without relying on color alone?", "Is any form, editor, long content, or high-risk review hiding inside a widget that should be a dialog, panel, or page?" ], "relatedPatterns": [ "command-palette", "select", "listbox", "modal-dialog", "confirmation-dialog", "header", "global-navigation", "icon-only-ambiguous-action" ], "comparisons": [ "menu-button-vs-command-palette-vs-select-vs-confirmation-dialog" ], "sourceIds": [ "wai-aria-apg-menu-button", "wai-aria-apg-menu-menubar", "mdn-aria-menu-role", "adobe-spectrum-menu" ] }, { "id": "merge-conflict-resolver", "completionStatus": "complete", "name": "Merge conflict resolver", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Source-code branch conflict resolver with file and hunk decisions", "maturity": "standard", "platforms": [ "web", "desktop" ], "problem": "Developers can merge broken code, discard branch work, or become stuck when a source-control conflict resolver hides branch ownership, file paths, conflict markers, validation errors, unsupported files, or the final commit boundary.", "solution": "Provide a merge conflict resolver that works at repository, file, and hunk level; labels target and source branches; preserves both code versions; supports choose-side and inline editing; validates resolved content; blocks commit until conflicts are resolved; and hands unsupported files to local/manual tooling.", "uiGuidance": [ "Show the merge target, source branch, base branch, file path, conflict count, and current hunk before any Use ours, Use theirs, or Edit resolution action.", "Render conflict markers or equivalent side-by-side changed lines with clear branch labels, syntax-aware context, validation status, and a commit message area that stays separate from hunk decision controls." ], "uxGuidance": [ "Use a merge conflict resolver when a source-control merge, rebase, pull request, or merge request cannot continue until developers decide which code survives in one or more conflicted hunks.", "Guide developers through file and hunk decisions, preserve both branch versions until commit, validate the resolved file for remaining markers, and route unsupported or risky files to local/manual resolution instead of pretending the browser can solve them." ], "uiExamples": { "good": [ "A merge request resolver shows Target main and Source feature/billing beside src/billing/rules.ts, lists 2 unresolved hunks, labels Use target and Use source controls, previews the resolved file, and keeps Commit resolution disabled until all conflict markers are gone.", "A browser code resolver highlights only the conflicting lines inside surrounding context, lets the developer edit the resolved block inline, and shows the commit message field after the file validates.", "A resolver shows assets/logo.png as unsupported in browser, links to command-line instructions, and leaves the merge blocked while preserving both file versions." ], "bad": [ "A merge screen has Accept all incoming with no target/source branch labels, file paths, or discarded code preview.", "A resolver lets users commit while <<<<<<< markers remain in the file.", "A code merge page says Ours and Theirs without saying whether Ours is the target branch, source branch, local checkout, or remote branch." ] }, "uxExamples": { "good": [ "A developer opens a merge request conflict, chooses target for the dependency version, edits the feature flag block to keep both checks, reviews the resolved file, enters a commit message, and commits after validation passes.", "A maintainer resolves three text hunks in the browser, sees one generated lockfile exceeds resolver limits, downloads manual commands, and keeps the merge request blocked until the lockfile is resolved locally.", "A reviewer returns to a partially resolved merge conflict and sees previous hunk decisions, remaining files, validation errors, and the exact branch pair unchanged." ], "bad": [ "The tool resolves conflicts by newest commit timestamp and merges without showing the lost branch code.", "A browser resolver removes conflict markers but produces syntax-invalid code and still enables Commit.", "A merge request says conflicts fixed, but the target branch moved and the server rejects the commit after the UI clears the conflict state." ] }, "problemContext": [ "A merge, rebase, pull request, or merge request detected overlapping edits in one or more files.", "The conflict is represented as code hunks, file versions, branch names, conflict markers, or repository metadata rather than ordinary form fields.", "Some conflicts can be resolved in a browser or desktop UI, while binary files, huge files, generated lockfiles, or complex rebases may require a command-line or IDE route.", "Committing the resolution changes repository history or merge request state and may trigger tests, review requirements, or branch protection." ], "selectionRules": [ "Choose merge conflict resolver for source-control branch conflicts with files, hunks, target/source branch labels, conflict markers, and a resolution commit.", "Use conflict resolution for non-code records, documents, imports, or synced objects that need a general decision workflow without repository-specific semantics.", "Use conflict state when the interface only needs to tell users that competing versions exist and route them to a resolver.", "Use inline edit only for editing a value in place; a merge conflict resolver must preserve both branch versions and validate the entire resolved hunk or file.", "Use review-before-submit when users verify their own entered values before a transaction, not when two branches changed the same code.", "Resolve at the smallest source-control unit the developer can judge: hunk, file, generated artifact, rename, delete/modify conflict, or binary asset.", "Provide branch labels that match the repository vocabulary, such as target/source, base/head, main/feature, incoming/current, or ours/theirs with explicit definitions.", "Block commit while conflict markers remain, required files are unresolved, validation fails, unsupported files need local resolution, or the server rejects the new resolution commit.", "Show final commit scope, commit message, files changed, and unresolved count before creating the merge-resolution commit.", "After successful commit, refresh mergeability and preserve a visible audit trail in the merge request, branch history, or review discussion." ], "requiredStates": [ "Repository and branch context state with target branch, source branch, and merge request or pull request identifier.", "Conflict file list state with unresolved count and file paths.", "Current hunk compare state with source and target code labels.", "Use target or ours decision state.", "Use source or theirs decision state.", "Inline edit resolved hunk state.", "Validation failure state for remaining conflict markers, syntax errors, or unresolved hunks.", "Unsupported file or local-tool-required state.", "Review resolved files state with changed-file summary and commit message.", "Committed resolution state after the repository accepts the resolution commit." ], "interactionContract": [ "The resolver opens from a known merge conflict and keeps branch pair, file path, hunk number, and total unresolved count visible.", "Each hunk decision records whether target, source, or edited code survives and keeps both original branch versions available until the resolution commit succeeds.", "Next and Previous hunk controls preserve decisions and move focus to the next conflicted block.", "Inline editing validates that conflict markers are removed and required syntax or repository checks pass before commit is enabled.", "Unsupported files show explicit local or IDE instructions and do not count as resolved until the repository receives a valid resolution.", "The commit action includes the resolved file list and commit message and is disabled or intercepted when conflicts remain unresolved.", "After commit, the interface refreshes mergeability and reports if the target branch moved, branch protection blocks the commit, or CI/review gates still apply.", "The workflow exposes a way to reopen decisions, discard the attempted resolution, or continue locally when browser resolution is not appropriate." ], "implementationChecklist": [ "Model conflicts as repository files with target branch value, source branch value, base context, hunk ranges, conflict markers, decision, resolved text, validation errors, and commit state.", "Use source-control terms consistently and define ours/theirs when those labels appear.", "Render code in monospace blocks with line context, changed-line highlighting, file path, branch labels, and accessible text for inserted, removed, target, and source code.", "Implement choose target, choose source, edit resolved hunk, reset hunk, next file, previous file, review files, open local instructions, and commit resolution controls.", "Detect remaining conflict markers such as <<<<<<<, =======, and >>>>>>> before enabling commit.", "Persist partial decisions through route changes, authentication refresh, target branch refresh, and browser reload when repository policy permits.", "Route binary files, oversized files, submodules, generated lockfiles, rename/delete conflicts, and protected-branch failures to a manual or local tool path.", "Test branch-label clarity, hunk navigation, marker validation, syntax validation, unsupported files, target branch moved, commit failure, keyboard access, screen reader labels, and audit trail output." ], "commonMisuses": [ "Using Accept all incoming without showing file paths, branches, or discarded code.", "Leaving Ours and Theirs undefined in a browser context where repository roles can invert by operation.", "Enabling Commit while conflict markers remain.", "Treating a binary or generated file as editable text.", "Clearing the merge conflict badge before the repository accepts the resolution commit.", "Hiding branch-protection, moved-target, or CI blockers after the browser commit is created.", "Mixing general document conflict copy into a code resolver without hunk, file, branch, and commit semantics." ], "critiqueQuestions": [ "Can the developer tell which branch each side of the hunk comes from?", "Which file and hunk are being resolved, and how many remain?", "Can the developer inspect the code that will be discarded before committing?", "What prevents commit while conflict markers, unsupported files, or validation errors remain?", "How does the resolver handle target branch movement or server rejection after local-looking resolution?", "Where is the resolution commit message, audit trail, and merge request status shown?" ], "relatedPatterns": [ "conflict-resolution", "conflict-state", "review-before-submit", "inline-edit", "error-state", "warning-text", "confirmation-dialog", "notification-center" ], "comparisons": [ "merge-conflict-resolver-vs-conflict-resolution-vs-conflict-state-vs-review-before-submit" ], "sourceIds": [ "gitlab-merge-conflicts", "microsoft-office-coauthoring-conflicts", "atlassian-confluence-concurrent-editing" ] }, { "id": "meter", "completionStatus": "complete", "name": "Meter", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Read-only scalar value gauge within a known range", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to understand the current level of a bounded resource, capacity, score, or risk, but unlabeled gauges and decorative bars often hide the range, unit, threshold meaning, or whether high values are good or bad.", "solution": "Render a read-only meter for scalar values with a meaningful minimum and maximum, visible current value and unit, threshold labels, accessible name and value text, and clear action guidance when the value crosses warning, critical, or optimum boundaries.", "uiGuidance": [ "Show the measured object, current value, unit, minimum and maximum context, and threshold bands close to the gauge so users can interpret the reading without guessing.", "Use native meter semantics or equivalent read-only meter attributes, and pair color bands with text such as Healthy, Warning, Critical, Low, Normal, High, or Over limit." ], "uxGuidance": [ "Use a meter when users need to judge the current level of a bounded resource, score, capacity, or risk, not when they are completing a task or choosing a value.", "Explain whether higher, lower, or middle values are better, what threshold the current value crosses, and what action is available when the meter enters a warning or critical range." ], "uiExamples": { "good": [ "An account storage card says 86 GB of 100 GB used, marks 70 GB as warning and 90 GB as critical, and labels the current state Critical.", "A battery meter shows 50%, 6 hours remaining, low and high threshold labels, and a charging status outside the gauge.", "A credit utilization gauge says 18% used of a 30% recommended ceiling and labels lower values as better." ], "bad": [ "A red-to-green bar says 89% with no unit, minimum, maximum, or explanation of whether high is good.", "A progress bar for uploading evidence.zip is implemented as a meter, so task completion and capacity status are confused.", "A meter has a draggable handle, implying users can edit a read-only storage value." ] }, "uxExamples": { "good": [ "A user sees storage at 86 of 100 GB, understands the account is in the critical band, opens Manage storage, and deletes old exports before uploads are blocked.", "A support admin reviews a risk score at 22 out of 100 where lower is better, sees Low risk, and avoids unnecessary escalation.", "A device dashboard shows battery at 14%, marks Low, estimates remaining time, and offers Turn on power saver." ], "bad": [ "A user watches a meter animate during upload and waits for it to reach full even though it represents remaining quota, not upload progress.", "A score meter says 72 without explaining the range or whether 72 is healthy, risky, passing, or failing.", "A meter changes color at hidden thresholds, so users cannot predict what action is needed before a quota limit blocks them." ] }, "problemContext": [ "The product can name the measured object and provide a current numeric value inside a meaningful range.", "The value represents state such as storage used, battery charge, quota consumed, memory utilization, credit utilization, score, risk, capacity, or health.", "Users need to compare the current value against low, high, optimum, warning, critical, limit, target, or safe bands.", "The value is not directly editable in this context, though an adjacent action may help users improve the state." ], "selectionRules": [ "Choose meter when a read-only scalar value has a meaningful minimum and maximum.", "Use a native meter element when possible for web surfaces, with value, min, max, low, high, and optimum when threshold bands are meaningful.", "Use visible value text such as 86 GB of 100 GB used when a percent alone does not explain the measurement.", "Label whether higher, lower, or middle values are better whenever the direction is not obvious.", "Use progress bar when the value represents completion of an active task that moves toward a finish.", "Use slider when users change the value by dragging or keyboard adjustment.", "Use spinbutton when users type or step an exact numeric value.", "Use ordinary text, stat cards, tables, or charts when the value lacks a meaningful maximum.", "Do not use a meter for identifiers, one-off counts, dates, rankings, or cumulative totals with no bounded scale.", "Do not rely on browser default color alone; add text or icon status for threshold meaning." ], "requiredStates": [ "Normal state inside the acceptable band.", "Warning state near a threshold users can act on.", "Critical or over-limit state with an action or consequence.", "Low-better state where the optimum range is near the minimum.", "High-better state where the optimum range is near the maximum.", "Middle-better state where both extremes are less desirable.", "Unknown or unavailable measurement state that removes the meter instead of showing a fake value.", "Loading or refreshing state before a current value is known, using progress or loading semantics instead of meter." ], "interactionContract": [ "The meter is read-only; users cannot drag, type, increment, or submit the meter itself.", "The visible label identifies the measured object and the value text includes the unit and total range.", "Threshold labels explain the consequence of low, high, optimum, warning, critical, and over-limit bands.", "If the value updates automatically, the product announces meaningful threshold crossings rather than every small change.", "A crossed warning or critical threshold offers an adjacent action such as Manage storage, Turn on power saver, Reduce risk, or View details.", "If max, min, unit, or current value is unknown, the product uses unavailable or loading state rather than a misleading gauge.", "The meter does not replace validation, progress, input, or chart patterns when those better match the task." ], "implementationChecklist": [ "Define the measured object, unit, current value source, minimum, maximum, threshold bands, optimum direction, update frequency, and actions before choosing a meter.", "Use native meter when browser support and styling needs allow; otherwise recreate role, accessible name, current value, minimum, maximum, and useful value text.", "Keep text outside the meter track so labels and values remain readable at any fill amount.", "Pair color bands with text, icons, or labels; ensure low/high/critical meanings are available without color.", "Use aria-valuetext or native fallback text for values where a percent is not enough.", "Test low, normal, high, optimum, over-limit, unavailable, and refreshed-value states.", "Avoid interactive affordances such as thumbs, handles, plus/minus buttons, and editable text inside the meter." ], "commonMisuses": [ "Using a meter to show task progress such as upload completion.", "Using a meter for a value without a meaningful maximum.", "Showing percent without unit, total, or threshold meaning.", "Using color alone for warning and critical ranges.", "Making a read-only meter look draggable or editable.", "Failing to explain whether high, low, or middle values are best.", "Putting headings or important controls inside a custom meter element where descendants may be presentational." ], "critiqueQuestions": [ "What object is being measured, and what are the minimum and maximum?", "Is the value read-only in this context, or should this be an input control?", "Does the value represent current state or completion of a task?", "What unit and value text will users hear and see?", "Which thresholds matter, and what action should users take at each band?", "Is high, low, or middle the optimum range, and is that clear without color?" ], "relatedPatterns": [ "progress-bar", "slider", "spinbutton", "password-creation" ], "comparisons": [ "meter-vs-progress-bar-vs-slider-vs-spinbutton" ], "sourceIds": [ "mdn-html-meter", "mdn-aria-meter-role", "wai-aria-apg-meter-pattern", "whatwg-html-meter-element" ] }, { "id": "modal-dialog", "completionStatus": "complete", "name": "Modal dialog", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Focused modal task layer", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users sometimes need a short focused task layer that temporarily blocks the current page without sending them into a separate workflow.", "solution": "Open a titled dialog above the current page, make background content unavailable, place focus inside the dialog, keep focus contained until close, then return focus to the invoking control or next logical workflow point.", "uiGuidance": [ "Render a titled layer above a dimmed or otherwise unavailable page, with clear task content, named actions, visible close or cancel affordance, and stable scroll boundaries.", "Keep background controls visually present for orientation but unavailable to pointer and keyboard interaction while the modal is open." ], "uxGuidance": [ "Use the modal interruption only for compact tasks that genuinely need temporary focus before the user returns to the page.", "Make entry, completion, cancellation, Escape dismissal, and focus return predictable so users understand they are in a temporary mode." ], "uiExamples": { "good": [ "Account settings opens in a titled dialog with one display-name field, Save, Cancel, close control, and dimmed inactive page context.", "The dialog panel has a clear accessible name, stable width, readable body copy, and actions that remain visible." ], "bad": [ "A vague popup titled Popup floats over active page controls and offers only OK.", "A long settings workflow is squeezed into a small modal where the primary action scrolls out of reach." ] }, "uxExamples": { "good": [ "Opening moves focus to the display-name field, Tab remains inside the layer, Escape cancels, and closing returns focus to Open dialog.", "Save applies the compact task and returns the user to the same page context with a clear status message." ], "bad": [ "Users can click background Delete or Navigate controls while the modal is still open.", "Closing the dialog drops focus at the top of the document or loses the user's previous context." ] }, "problemContext": [ "The user is working in a larger page but must complete a compact task before continuing.", "The task benefits from preserving page context while preventing accidental interaction behind the layer.", "The content can be completed, cancelled, or dismissed without requiring navigation history or a long-lived workspace.", "The product can manage focus, close behavior, and background inactivation reliably." ], "selectionRules": [ "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." ], "requiredStates": [ "Closed page state with an obvious invoking control.", "Opening transition that moves focus into the dialog and marks background content unavailable.", "Open task state with accessible title, concise body, primary action, secondary cancellation, and visible close behavior.", "Keyboard cycling state where Tab and Shift+Tab remain inside the dialog.", "Dismissed state that restores focus to the invoker and leaves the page unchanged.", "Completed state that applies the task, closes the layer, and returns focus to a logical point.", "Overflow state for dialog content that scrolls inside the layer without losing access to actions." ], "interactionContract": [ "Opening the modal moves focus to the best starting element inside the dialog, not to the dimmed page.", "Tab and Shift+Tab cycle through focusable elements in the dialog until the user closes it.", "Escape closes dismissible modal tasks and follows the same cleanup path as cancel.", "Background controls cannot be clicked, focused, or changed while the modal is active.", "Closing through save, cancel, Escape, or close button restores focus to the opener unless the workflow clearly moves elsewhere.", "The dialog has an accessible name from its visible title and a useful description when body copy explains the task.", "Primary and secondary actions describe the task outcome rather than using vague OK-only controls." ], "implementationChecklist": [ "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." ], "commonMisuses": [ "Using a modal as a generic container for routine information that could stay inline.", "Letting users interact with page controls behind the open dialog.", "Opening a long multi-step workflow in a modal without navigation, progress, or saved state.", "Providing only an OK button for a task that can be cancelled or needs a named action.", "Moving focus into the dialog on open but failing to return it on close.", "Stacking modal dialogs until users cannot understand where they are." ], "critiqueQuestions": [ "What page interaction must be blocked while this task is open?", "Can the task be completed in one focused layer without navigation or saved progress?", "Where exactly does focus go on open, on Tab wrap, on Escape, on cancel, and on completion?", "Would a drawer, inline panel, or full page preserve the user's context better than a modal?", "Does the title name the task rather than merely saying dialog or popup?" ], "relatedPatterns": [ "confirmation-dialog", "toast-only-critical-error" ], "comparisons": [ "modal-vs-confirmation-dialog" ], "sourceIds": [ "wai-aria-apg-dialog-modal", "w3c-html-dialog-technique", "atlassian-modal-dialog", "apple-hig-alerts" ] }, { "id": "modal-for-nonblocking-content", "completionStatus": "complete", "name": "Modal for nonblocking content", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Unnecessary modal interruption anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "A page presents routine information in a modal dialog even though users do not need to stop the current task, make a blocking decision, or protect background state.", "solution": "Treat nonblocking informational modals as an anti-pattern: choose an inline, anchored, side, or feedback surface that keeps page context usable, and reserve true modal dialogs for compact tasks that require temporary interruption.", "uiGuidance": [ "Replace read-only status, optional help, preview, release-note, supplemental detail, and low-risk announcements with inline messages, banners, toasts, popovers, drawers, disclosures, or side panels that keep the current task usable.", "Reserve modal styling, inert background behavior, focus containment, and forced dismissal for compact tasks or decisions that genuinely need users to stop using the page behind the layer." ], "uxGuidance": [ "Use this anti-pattern during review when users must press OK, close a popup, or leave a focus trap before continuing a task that did not require a blocking decision.", "Design the corrected flow so information remains available without stealing context: users can keep typing, compare rows, inspect the affected object, dismiss optional material, or recover the message later." ], "uiExamples": { "good": [ "A case review page shows a saved-state banner above the queue while filters and rows remain usable.", "A field help trigger opens a small popover anchored beside the affected field and closes with Escape without blocking the rest of the form.", "A selected record opens supplemental detail in a drawer so reviewers can compare neighboring rows." ], "bad": [ "A Saved successfully dialog blocks the form until users press OK.", "A question-mark help modal hides the field it is explaining.", "A read-only preview modal covers the list users need for comparison." ] }, "uxExamples": { "good": [ "A reviewer can keep selecting cases while a nonblocking update explains why one row changed.", "A keyboard user opens contextual help, presses Escape, and focus returns to the help trigger without leaving the task.", "A mobile user sees the same required status inline instead of losing the screen to a full-height informational dialog." ], "bad": [ "Users press OK through repeated routine status modals and stop reading them.", "A modal file preview prevents side-by-side comparison with nearby records.", "A newsletter modal appears during checkout even though no decision is required for the purchase." ] }, "problemContext": [ "The layer contains read-only help, status, preview, metadata, release notes, success feedback, onboarding tips, marketing, or supplemental explanation.", "The page behind the layer is the context users need for comparison, typing, scanning, filtering, or deciding.", "The modal has only OK, Close, Got it, or Dismiss and no necessary task outcome.", "Users encounter the interruption repeatedly, on mobile, during checkout, while editing, or inside a high-volume review workflow." ], "selectionRules": [ "Flag this anti-pattern when content can be read later, ignored safely, dismissed without consequence, or shown near its object without blocking the rest of the page.", "Use modal dialog only when a compact task or decision must temporarily suspend background interaction.", "Use popover for small anchored help, examples, short reference content, or light controls tied to one trigger.", "Use drawer or details panel for selected-object detail, preview, or supplemental inspection while the parent list remains useful.", "Use inline message for local guidance, validation, warning, or status that should persist near the affected field or object.", "Use banner or toast for page-level or workspace-level feedback that is nonblocking and recoverable.", "Use disclosure details when optional explanation should stay in the page flow after users open it.", "Do not use a modal merely because the information is important; use modality only when background interaction would be unsafe or incoherent." ], "requiredStates": [ "Default page state where the primary task remains visible and usable.", "Inline note state for local nonblocking information.", "Popover help state anchored to the affected field or control.", "Drawer detail or side preview state where selected-object context remains visible.", "Banner or toast status state that does not require an OK-only interruption.", "Dismissed state where optional information can be recovered or the task remains clear.", "Keyboard state where Escape dismisses nonblocking layers and focus returns locally.", "Mobile or narrow viewport state where the information stays inline or in a proportionate surface.", "High zoom state where text wraps without covering the controls it explains.", "Bad modal state showing focus trap, inert background, repeated interruption, and OK-only dismissal for nonblocking content." ], "interactionContract": [ "Users can continue the primary task while reading or ignoring nonblocking information.", "Opening help, preview, or status does not make unrelated background content inert unless a real task decision requires it.", "Nonblocking surfaces are anchored, scoped, titled, or placed near the object they explain.", "Escape and explicit close controls dismiss temporary nonblocking surfaces without losing the user's place.", "Focus returns to the invoking control or stays in the local task flow after dismissal.", "Important but nonblocking information remains recoverable through inline copy, notification history, details, or object metadata.", "Routine success, sync, release-note, and marketing messages do not force an OK-only modal acknowledgement.", "A true modal names the task, contains useful actions, blocks the background for a reason, and restores focus." ], "implementationChecklist": [ "Inventory every modal that contains only information, status, help, preview, release notes, promotion, or success feedback.", "Ask what background interaction must be prevented; if the answer is none, move the content out of a modal.", "Map each nonblocking modal to inline message, banner, toast, popover, drawer, disclosure, side panel, sheet, or full page based on scope and task size.", "Keep field help beside the field, record detail beside the record list, and page status near the affected workspace.", "Provide explicit close controls and Escape behavior for temporary nonblocking layers.", "Restore focus locally after popover, drawer, toast action, or disclosure dismissal.", "Make mobile layouts preserve the affected control or object instead of hiding it behind a full-screen informational modal.", "Track repeated announcements through notification history or release-note surfaces rather than redisplaying modal interruptions." ], "commonMisuses": [ "Showing success confirmation as a modal when an inline message, toast, or confirmation page would fit better.", "Opening help text in a modal that hides the field or table it explains.", "Putting a read-only preview in a modal when users need side-by-side comparison.", "Blocking the page for background sync, autosave, routine update, or informational release note.", "Using a modal for newsletter signup, promotion, or survey before the primary workflow is complete.", "Adding OK-only modals for generated status messages because the component library makes dialogs easy." ], "critiqueQuestions": [ "What action or risk requires background interaction to be blocked?", "Could users keep working safely if this information were inline, in a banner, in a popover, or in a drawer?", "Is the background page the context users need to understand the message?", "Does the layer have a real task outcome, or only OK, Got it, Close, or Dismiss?", "Can users recover the information after dismissing it?", "What happens on mobile, high zoom, keyboard Escape, and repeated visits?" ], "relatedPatterns": [ "modal-dialog", "popover", "drawer", "inline-message", "toast-notification", "notification-banner", "disclosure-details", "sheet", "alert-dialog" ], "comparisons": [ "modal-for-nonblocking-content-vs-modal-dialog-vs-popover-vs-drawer-vs-inline-message" ], "sourceIds": [ "wai-aria-apg-dialog-modal", "atlassian-modal-dialog", "fluent-popover-component", "nord-drawer-component", "fluent-drawer-component", "mdn-popover-api-using" ] }, { "id": "model-update-notice", "completionStatus": "complete", "name": "Model update notice", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Lifecycle notice for AI model version changes, retirement, migration, capability shifts, or replacement behavior", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI model changes can alter or break high-value workflows, but products often announce them as ordinary feature news or hidden release notes, leaving users without impact scope, deadlines, replacements, testing paths, migration ownership, or rollback planning.", "solution": "Provide a dedicated model update notice that connects lifecycle state, model version, deadline, affected usage, replacement, migration requirements, evaluation results, rollout status, and post-change verification in one actionable surface.", "uiGuidance": [ "Render model update notice as a lifecycle-specific communication that names the current model, new or replacement model, affected product surface, effective date, retirement or shutdown date, expected behavior change, migration path, test window, and whether action is required.", "Show affected deployments, prompts, workflows, fine-tunes, evaluations, APIs, quotas, regions, auto-upgrade status, provisioned or manual migration requirements, and owner or admin contact where the change can break or alter AI behavior." ], "uxGuidance": [ "Use model update notice when a model change can affect availability, output quality, latency, pricing, safety behavior, compliance, prompt compatibility, tool use, evaluations, or user trust.", "Make the notice actionable: help teams identify impacted usage, compare replacement behavior, run regression tests, schedule migration, pause risky automation, and verify that the notice is no longer needed after migration or retirement." ], "uiExamples": { "good": [ "An admin console banner says GPT-4o 2024-08-06 retires on 2026-10-01, shows replacement GPT-5.1, lists three affected assistants, links to migration tests, and marks provisioned deployments as manual migration required.", "A model picker marks Legacy model in use, shows Deprecated and Retires in 42 days, compares replacement latency and cost, and lets the owner run an evaluation before switching." ], "bad": [ "A broad New model available banner appears with no current model, replacement model, deadline, impacted flows, or action path.", "A chat product silently changes model behavior overnight and users only discover the update after saved prompts produce different outputs." ] }, "uxExamples": { "good": [ "A developer sees a model retirement notice, opens the affected endpoint list, runs a saved regression set against the replacement model, schedules rollout, and dismisses the notice only after migration is complete.", "A support admin learns that preview deployments may be force-upgraded, reviews high-risk automation, pauses one workflow, and confirms the replacement model has the required region and tool support." ], "bad": [ "The notice says better model coming soon but does not say whether existing API calls will fail, auto-upgrade, or produce different behavior.", "A model deprecation email links to a changelog but the product UI still shows the retired model as healthy." ] }, "problemContext": [ "Model providers may release new versions, mark models legacy or deprecated, retire preview models quickly, auto-upgrade standard deployments, require manual migration for provisioned deployments, or shut down endpoints after a date.", "A model update may change answer style, refusal behavior, safety policy, tool calling, structured output, latency, pricing, context length, region availability, fine-tuning support, prompt compatibility, or evaluation results.", "Users affected by a model update may include admins, developers, support leads, prompt owners, compliance reviewers, automation owners, and end users relying on stable behavior.", "The notice may appear in admin consoles, model pickers, API dashboards, assistant builders, workflow editors, release notes, notification centers, emails, or inline on affected AI surfaces.", "The product must distinguish informational upgrades from required migration, urgent retirement, risky behavior change, preview instability, and post-retirement failure states." ], "selectionRules": [ "Choose model update notice when users need to understand and act on AI model lifecycle, version, capability, deprecation, retirement, replacement, migration, or auto-upgrade changes.", "Use notification banner when the message is a general page-flow notice and not specifically about model lifecycle, replacement, affected AI behavior, or migration.", "Use confidence / uncertainty display when the surface explains reliability of one prediction or output, not a platform model version change.", "Use warning text when the user is about to take a risky action and needs consequence copy, not when the main job is migration planning.", "Use phase / beta banner when signalling service maturity such as alpha or beta; use model update notice when a model version or lifecycle stage changed inside an AI capability.", "Use source grounding display when users inspect evidence behind an answer; use model update notice when model behavior or availability changed regardless of source coverage.", "Use activity log or audit log to record that a migration happened; use model update notice to warn, plan, test, and act before or during the change.", "Show current model, new or replacement model, lifecycle stage, effective date, retirement or shutdown date, affected surfaces, owner, action required, and testing path when the change can affect production behavior.", "Mark no-action, auto-upgrade, manual migration, preview retirement, behavior-only update, blocked deployment, failed migration, and completed migration states separately.", "Do not present model updates as decorative product marketing when users need deadlines, compatibility checks, or migration ownership." ], "requiredStates": [ "Informational model update state with model name, version, capability change, effective date, and no action required.", "Deprecated model state with replacement model, retirement date, affected usage, recommended migration path, and owner.", "Urgent retirement state with shutdown date, unavailable-after behavior, failure mode, support contact, and escalation path.", "Auto-upgrade scheduled state showing rollout window, old model, new model, expected behavior change, and testing option.", "Manual migration required state for provisioned or pinned deployments that will not auto-upgrade.", "Preview model short-notice state with production risk and rapid migration path.", "Behavior change state where model remains available but answer style, safety behavior, tool use, pricing, latency, region, or context support changes.", "Compatibility check state showing prompts, workflows, automations, fine-tunes, evaluations, API calls, or regions affected.", "Test replacement state with regression set, pass/fail results, differences, owner approval, and rollout plan.", "Completed, dismissed, snoozed, failed migration, rollback, stale notice, and post-retirement blocked states.", "Mobile compact notice state with model, deadline, affected count, and primary action visible." ], "interactionContract": [ "The notice identifies the current model and replacement or new model in user-visible text.", "Users can see whether action is required, whether auto-upgrade applies, and what happens if no action is taken.", "The notice links to affected assistants, prompts, workflows, API keys, deployments, fine-tunes, evaluations, or automations rather than only to a broad changelog.", "The product distinguishes lifecycle stage from status: preview, GA, legacy, deprecated, retiring, retired, auto-upgrading, and blocked are not interchangeable.", "Dismissing or snoozing the notice does not hide unresolved required migration from owners or admins.", "Testing, comparison, and migration actions preserve the old model until the user confirms rollout where manual migration is required.", "After migration, the notice records completion, replacement model, date, owner, validation evidence, and any residual behavior changes.", "If the model is already retired, the UI explains the failed call or blocked deployment and routes users to replacement and recovery." ], "implementationChecklist": [ "Model current model ID, version, provider, deployment type, lifecycle stage, replacement, effective date, retirement date, shutdown behavior, affected surfaces, owners, required action, auto-upgrade state, and migration status separately.", "Inventory affected usage from model pickers, API logs, assistants, workflows, automations, fine-tunes, evaluations, prompts, integrations, regions, and quotas.", "Provide model comparison and regression testing using representative prompts, tool calls, structured outputs, safety cases, latency, cost, and source-grounding expectations.", "Separate notice dismissal from migration completion, and keep required notices visible to accountable owners until the work is verified.", "Handle preview short-notice, GA retirement, provisioned manual migration, auto-upgrade, no-replacement retirement, behavior-only update, and post-retirement failure as separate states.", "Log notice sent, viewed, snoozed, migration started, test completed, rollout approved, fallback used, rollback, and final completion.", "Check accessibility for status badges, dates, affected item tables, diff views, test results, countdowns, and live status updates." ], "commonMisuses": [ "Announcing a model change as ordinary release news without affected usage, deadline, replacement, or action requirement.", "Using a dismissible banner that hides required migration before it is complete.", "Showing model deprecated without explaining whether calls still work, when they fail, or what replacement to test.", "Auto-upgrading a model without letting owners compare behavior in high-impact workflows.", "Using confidence or source-grounding signals to explain a model lifecycle change.", "Leaving retired models selectable after calls now fail." ], "critiqueQuestions": [ "Can users tell which model version is changing and when?", "Does the notice say whether action is required, auto-upgrade applies, or no action is needed?", "Can users find every affected prompt, workflow, deployment, or automation from the notice?", "Is there a test or comparison path before migration changes production behavior?", "Does dismissal mean only hidden for now, or verified migration complete?", "What state appears after the model is retired or a migration fails?" ], "relatedPatterns": [ "notification-banner", "warning-text", "phase-beta-banner", "confidence-uncertainty-display", "source-grounding-display", "activity-log", "agent-progress-trace", "human-approval-gate", "automation-rule-builder", "settings-management" ], "comparisons": [ "model-update-notice-vs-notification-banner-vs-warning-text-vs-phase-beta-banner-vs-confidence-uncertainty-display-vs-source-grounding-display" ], "sourceIds": [ "openai-api-deprecations", "microsoft-foundry-models-lifecycle", "microsoft-foundry-model-retirement-schedule", "anthropic-model-deprecation-commitments", "wcag-status-messages" ] }, { "id": "multi-select", "completionStatus": "complete", "name": "Multi-select", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Multi-value picker widget", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to choose several predefined values from a list that is too long, searchable, or dynamic for a visible checkbox group.", "solution": "Provide a filterable multi-value picker with selected chips or tags, checked options in the open list, removable values, clear-all behavior, and validation that preserves selections.", "uiGuidance": [ "Render a filter input, open option list, selected-value chips, remove controls, checked option states, clear-all control, and validation state.", "Keep selected values reviewable outside the open list so closing or filtering the menu does not hide the selection." ], "uxGuidance": [ "Help users choose multiple values from a large, compact, or dynamic option set.", "Preserve selections while users search, add, remove, clear, and submit." ], "uiExamples": { "good": [ "Selected values are shown as removable chips or checked rows with clear labels.", "Search, option list, and selected set are visually distinct." ], "bad": [ "Selected values hidden inside a closed dropdown.", "Tiny removable chips with unclear labels or close buttons." ] }, "uxExamples": { "good": [ "Users can search, add, remove, review, and submit multiple values without losing context.", "Selection limits and duplicates are handled before submit." ], "bad": [ "Removing a value is impossible by keyboard.", "Remote results overwrite existing selections." ] }, "problemContext": [ "The option set may be long, remote, or frequently changing.", "Users need to search, add, remove, and review multiple values before committing." ], "selectionRules": [ "Choose multi-select for long, searchable, or compact multi-choice sets where a visible checkbox group would be too large.", "Show selected values outside the open list as removable chips, tags, or an explicit selected-value summary.", "Keep the option list open while users select several values unless the platform has a clear equivalent review flow.", "Use checkbox groups when the set is short enough to scan and should stay fully visible." ], "requiredStates": [ "No selected values state with empty selected set.", "Open filtered option list state.", "One or more selected values shown outside the option list.", "Validation state for required, minimum, maximum, duplicate, or unavailable selection." ], "interactionContract": [ "Users can search, add, and remove values without losing their current selection.", "Selected values are visible and removable outside the open option list.", "The picker communicates selection limits, unavailable choices, duplicate labels, and no-match states." ], "implementationChecklist": [ "Expose selected values as removable chips or an explicit selected-value surface.", "Show checked state for selected options when the picker list is open.", "Support filtering or grouping for long lists.", "Preserve selections on validation failure and during remote result refreshes.", "Handle duplicate labels with context and avoid custom widgets without listbox or checkbox semantics." ], "commonMisuses": [ "Hiding selected values inside a closed menu.", "Using multi-select for one mandatory choice.", "Building custom widgets without listbox or checkbox semantics.", "Closing the menu after each selection when users commonly need several values." ], "critiqueQuestions": [ "Can users review and remove the selected set before they commit?", "Does filtering preserve existing selected values when the visible result list changes?" ], "relatedPatterns": [ "checkbox-group", "autocomplete" ], "comparisons": [ "checkbox-group-vs-multi-select" ], "sourceIds": [ "carbon-dropdown-multiselect", "calcite-combobox-component", "wai-aria-apg-listbox" ] }, { "id": "multi-step-form", "completionStatus": "complete", "name": "Multi-step form", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Multi-page transaction with saved step state", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Long or conditional transactions become overwhelming, fragile, and error-prone when all fields are shown at once or when page-by-page flows fail to save progress, validate prerequisites, or let users review changes before final submission.", "solution": "Split the transaction into ordered saved steps with focused pages, clear progress context, validation before advancement, answer preservation, review and change behavior, and explicit handling for conditional or stale downstream answers.", "uiGuidance": [ "Render each step as a focused page with a clear heading, progress context when useful, Back and Continue controls, local validation, and a final review page before submission.", "Show step status honestly: current, complete, locked, optional, stale, error, and review states must match saved form data rather than page visits." ], "uxGuidance": [ "Use a multi-step form when a transaction is too long, conditional, high-stakes, or hard to recover from as one page, and users need manageable saved progress.", "Persist answers at each step, let users return and change them without repeating the whole transaction, and recompute later steps when earlier answers alter eligibility or required evidence." ], "uiExamples": { "good": [ "A benefit application has Eligibility, Contact details, Documents, Review, and Submit pages, with the current step named in the heading and completed steps shown from saved data.", "The review page groups captured answers with Change links that return to the right step and then back to review." ], "bad": [ "A five-screen flow shows all steps as complete after users only viewed them.", "A stepper strip is shown without page headings, Back behavior, saved answers, or a final review before submission." ] }, "uxExamples": { "good": [ "A user completes eligibility and contact details, goes Back from documents, sees contact details still filled, continues, and returns to the same documents step.", "A user changes an eligibility answer on review, the documents step is marked needs review, and final submit is blocked until stale evidence is checked." ], "bad": [ "A user changes an early answer and the form silently submits later answers that no longer apply.", "A browser refresh on step 3 clears steps 1 and 2, forcing the user to start again." ] }, "problemContext": [ "The task has enough questions, sections, dependencies, or risk that one page would be hard to scan or recover from.", "Users may need to complete the transaction on mobile, leave and return, or change earlier answers after seeing a review page.", "Later steps may depend on earlier answers, such as eligibility, document requirements, payment amount, or routing." ], "selectionRules": [ "Choose a multi-step form when the transaction has several ordered pages or sections that need saved progress.", "Prefer single-page form when fields are compact, related, low branching, and best reviewed together before one submit.", "Use single-question pages as individual steps when one answer deserves a focused page inside the larger transaction.", "Use a step indicator only when three or more stable high-level steps benefit from progress visibility.", "Include a review step when users need to confirm captured answers before final submission.", "Persist each step before moving forward and preserve values when users go Back, refresh, or return from review.", "Validate prerequisites before unlocking later steps or explain why a future step is unavailable.", "When earlier answers change, mark affected later steps stale or incomplete before final submission." ], "requiredStates": [ "Not-started state with clear start point and expectation of the steps or sections ahead.", "Current step state with heading, saved context, local answer controls, Back, and Continue.", "Completed step state based on saved valid data.", "Locked future step state before prerequisites are complete.", "Validation error state that keeps the user on the current step with answers preserved.", "Back-return state that restores previous answers and the correct step route.", "Review state with sectioned answers and Change links.", "Stale downstream state when an earlier answer changes what later steps require.", "Final submitted state only after review and required steps are complete." ], "interactionContract": [ "Continue validates and saves the current step before unlocking the next required step.", "Back returns to the previous step without clearing the current or previous answers.", "Browser refresh, browser Back, service Back, and review Change links restore the correct page with pre-populated data.", "Completed status means the step's required answers are saved and still compatible with upstream answers.", "Changing an upstream answer recomputes downstream requirements and marks affected steps incomplete or stale.", "Review Change links return users to the changed step and then back to review without forcing them through unrelated steps." ], "implementationChecklist": [ "Define stable step IDs, route ownership, prerequisites, completion rules, optionality, and downstream dependencies before designing screens.", "Keep each step focused on one question or one coherent group of related fields.", "Save step data before route transitions and restore it after Back, refresh, validation, and server errors.", "Use a visible step indicator only when there are at least three stable high-level steps and progress visibility reduces uncertainty.", "Add a check-answers or review step before final submission for medium or high-risk transactions.", "Implement Change links that return to the exact step with pre-populated values and route users back to review when appropriate.", "Invalidate or revalidate downstream steps when earlier answers change requirements.", "Test keyboard flow, focus on route changes, screen reader step announcements, mobile Back behavior, refresh recovery, server validation, and stale-answer paths." ], "commonMisuses": [ "Using a multi-step form to hide a short related form that users should review on one page.", "Treating a step indicator as the form lifecycle instead of modelling saved step data.", "Marking a step complete after visit rather than after validation and save.", "Letting users skip required future steps with no prerequisite check.", "Changing the number of visible steps in a way that makes progress counts dishonest.", "Clearing previous answers when users go Back or refresh.", "Review Change links that force users through every later step again.", "Submitting stale downstream answers after an earlier answer changes." ], "critiqueQuestions": [ "What makes each step complete, and is that based on saved valid data?", "Can users go Back, refresh, and return from review without losing answers?", "Are the steps stable enough for visible progress, or does conditional logic need another representation?", "Which downstream steps become stale when each upstream answer changes?", "Does the review step let users change answers without repeating unrelated steps?", "Would this be simpler and safer as one single-page form?" ], "relatedPatterns": [ "single-page-form", "single-question-page", "step-navigation", "error-summary" ], "comparisons": [ "multi-step-form-vs-single-page-form-vs-single-question-page-vs-step-navigation" ], "sourceIds": [ "govuk-form-structure-service-manual", "govuk-check-answers-pattern", "uswds-step-indicator-component" ] }, { "id": "name-entry", "completionStatus": "complete", "name": "Name entry", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Personal-name capture field or field group", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Names are personal identifiers with cultural, legal, language, script, privacy, and identity implications, so ordinary text fields, split-name assumptions, title lists, and overstrict validation can misidentify people or make a service feel disrespectful.", "solution": "Ask only for the name the service needs, prefer a full-name field when possible, split only for real downstream requirements, support broad characters and scripts, preserve user-entered spelling and case, avoid unnecessary titles, capture preferred address or transcription separately, allow updates, and review exact spelling before use.", "uiGuidance": [ "Render name entry with a visible label that says exactly which name is needed, such as Full name, name on your passport, given names, family name, previous name, or what should we call you.", "Use a single full-name field when the service can store the name as provided, and keep enough width, Unicode-capable text entry, autocomplete, spellcheck false, field-specific errors, review text, and change actions visible." ], "uxGuidance": [ "Use name entry when a product must identify, address, verify, correspond with, or officially record a person by name.", "Make as few assumptions as possible about name parts, order, gender, marital status, script, casing, length, punctuation, or permanence; ask only for the name information the service will actually use." ], "uiExamples": { "good": [ "A profile form asks for Full name, uses autocomplete name and spellcheck false, accepts María-José Carreño Quiñones, and shows the exact value before saving.", "An identity form asks for Name as shown on your passport and separately asks What should we call you? for correspondence." ], "bad": [ "A form forces Title, First name, Middle initial, and Last name before it knows whether those parts exist or are needed.", "A name field rejects accents, apostrophes, hyphens, spaces, native script, or a one-letter name." ] }, "uxExamples": { "good": [ "A user enters 小林康宏, optionally adds Yasuhiro Kobayashi as a Latin transcription for staff, and sees both values reviewed separately.", "A user who changed their name is asked for Previous name where relevant, not Maiden name, and can update stored details without restarting the service." ], "bad": [ "A user with one name cannot continue because Last name is required and enters a period just to pass validation.", "A user enters van der Waals and the system changes it to Van Der Waals in correspondence." ] }, "problemContext": [ "The service may need a name for account display, correspondence, booking, official records, identity checks, payments, school or health records, support queues, legal documents, search, sorting, or relationship management.", "Users may have one name, multiple given names, multiple family names, patronymics, particles, prefixes, suffixes, titles, nicknames, native-script names, Latin transcriptions, changed names, or names that do not fit first-name and last-name order.", "Some flows need the name a person commonly uses, while others need the exact name on a passport, driving licence, bank account, payment card, court document, or government record.", "Name fields can reveal gender, marital status, family structure, religion, caste, migration history, or gender transition, so unnecessary collection and wording can create harm.", "Downstream systems often pressure teams to split, sort, capitalize, or ASCII-normalize names even when the user-facing service does not need those assumptions." ], "selectionRules": [ "Choose name entry when the product must capture a person's name for identification, correspondence, display, official records, booking, payment, verification, support, or relationship handling.", "Do not ask for a name if the service can work with an account identifier, email address, username, customer number, or anonymous flow instead.", "Use a single Full name field when the service can store and use the name as provided.", "Use split fields only when downstream systems genuinely need separate parts, and then label them as Given names and Family name for international audiences rather than relying on first and last order.", "Make it clear whether the service needs a common name, preferred name, official-document name, billing name, cardholder name, previous name, native-script name, or Latin transcription.", "Use autocomplete name for a full-name field, and use given-name, additional-name, family-name, honorific-prefix, honorific-suffix, or nickname only when deliberately collecting those parts.", "Set spellcheck false and avoid automatic casing, ASCII-only filters, title-case transforms, or stripping punctuation unless a hard external constraint is explained.", "Support long names, one-letter names, single-part names, spaces, hyphens, apostrophes, accents, non-Latin scripts, particles, prefixes, suffixes, numbers, and symbols where the service can store them.", "Avoid asking for title; if unavoidable, use an optional text input rather than a fixed dropdown list.", "Ask What should we call you? when the service wants a form of address instead of guessing a given name from the full name.", "Use Previous name instead of maiden name when asking about earlier names.", "Allow users to change stored names and review exact spelling before correspondence, official submission, or identity matching." ], "requiredStates": [ "Initial full-name state with visible label, purpose hint, autocomplete name, spellcheck false, and adequate width for long names.", "Focused state with normal text editing, paste, undo, selection, browser autofill, and no forced capitalization.", "Accented or punctuation state preserving hyphens, apostrophes, spaces, particles, and case.", "Native-script state accepting non-Latin characters with correct display direction and storage.", "Latin transcription state shown only when the service needs staff recognition, search, or back-office processing.", "Official-document state with wording that asks for the name as shown on the relevant document.", "Preferred address state asking what the service should call the user rather than guessing a name part.", "Previous-name state using neutral wording and making the need clear.", "Missing required name error state with the typed value preserved after correction.", "Unsupported character or legacy-system constraint state that explains the external reason and gives a recovery path.", "Reviewed name state showing the exact spelling, script, preferred address, and change action.", "Name update state for stored personal details." ], "interactionContract": [ "Users can type, paste, autofill, edit, select, undo, and correct names through native text behavior.", "The interface preserves the entered spelling, case, accents, punctuation, spacing, and script unless a visible external constraint requires a separate representation.", "Submitting an empty or constrained name preserves the typed value and places correction text next to the field or in a linked summary.", "The product never infers title, gender, marital status, family name, sorting key, or preferred address from the entered name without a designed field or confirmation.", "If multiple name representations are needed, each representation has its own label, purpose text, storage field, and review row.", "Users can change stored names without restarting the whole service when the product stores personal details.", "The backend treats display name, official name, preferred address, previous name, native-script name, Latin transcription, and verified identity match as separate states." ], "implementationChecklist": [ "Decide which name representation the service needs and where it will appear before selecting fields.", "Use a native text input with visible labels, stable ids, autocomplete tokens, spellcheck false, and aria-describedby for hints, errors, and status text.", "Prefer autocomplete name for full name; use component tokens only for intentional split fields.", "Store Unicode text and avoid byte-length assumptions; set database, API, export, search, and display paths to preserve long and multi-script names.", "Validate required presence and documented external constraints without rejecting real names because they are short, single-part, long, accented, hyphenated, punctuated, spaced, or non-Latin.", "Avoid title dropdowns, forced middle initials, forced family-name requirements, automatic capitalization, ASCII-only sanitization, and algorithmic name splitting.", "Provide review, change, and update paths for names used in correspondence, official submissions, identity checks, or payment.", "Test screen readers, browser autofill, mobile keyboards, paste, zoom, right-to-left or native-script names, one-letter names, multiple family names, particles, previous names, and name-change flows." ], "commonMisuses": [ "Requiring first name and last name when a full-name field would work.", "Blocking one-part names or one-letter names.", "Using a title dropdown that forces gender or marital-status disclosure.", "Stripping accents, apostrophes, hyphens, spaces, particles, or native-script characters.", "Automatically changing case or capitalization.", "Asking for maiden name instead of previous name.", "Guessing what to call someone from the first token of their full name.", "Treating a name captured for display as proof of legal identity.", "Making middle names required when the service does not need them.", "Storing only split parts and being unable to display the exact name the user provided." ], "critiqueQuestions": [ "Why does the service need this person's name, and where will it be displayed or used?", "Does the label ask for common name, full name, official-document name, previous name, or preferred address?", "Can the field accept long, single-part, one-letter, accented, punctuated, spaced, and native-script names?", "Does the implementation preserve case and spelling exactly as entered?", "Is any split into name parts required by a real downstream use, or is it a storage habit?", "Can users update their name and review exact spelling before correspondence or official submission?" ], "relatedPatterns": [ "text-input", "autocomplete", "select", "inline-validation", "error-summary", "review-before-submit" ], "comparisons": [ "name-entry-vs-text-input-vs-autocomplete-vs-select-vs-inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-names-pattern", "w3c-personal-names-around-world", "w3c-i18n-specdev-personal-names", "baymard-avoid-splitting-single-input-fields", "mdn-html-autocomplete-name" ] }, { "id": "navigation-drawer", "completionStatus": "complete", "name": "Navigation drawer", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Dismissible slide-in navigation sheet", "maturity": "established", "platforms": [ "mobile", "web", "desktop" ], "problem": "Users need access to app destinations or account sections, but the screen cannot or should not keep every navigation option visible all the time.", "solution": "Provide a controlled navigation drawer that slides in as a sheet, presents grouped destinations with current state, blocks or shares space appropriately, and closes predictably after navigation or dismissal.", "uiGuidance": [ "Render a navigation sheet that enters from the start edge or bottom, is opened by an explicit control, and presents grouped destination items with selected state.", "For modal drawers, dim or block the underlying content with a scrim and provide clear dismissal through item selection, scrim click, Escape, close control, or platform gesture." ], "uxGuidance": [ "Use a navigation drawer for destinations that need to be available but not constantly visible, especially on constrained screens or complex apps with secondary sections.", "After a drawer item is chosen, close the drawer, update the active destination, and return focus or reading position predictably so users see the result of navigation." ], "uiExamples": { "good": [ "A mobile app bar menu button opens a left modal drawer with Inbox selected, grouped labels, account switcher, and a visible scrim behind it.", "The drawer has a clear title, short destination labels, selected item styling, dividers between groups, and a close route.", "On larger screens, the same destinations can become a standard or permanent drawer when persistent access is useful." ], "bad": [ "A hamburger opens a full-height list with no scrim, no close control, and no visible selected destination.", "The drawer mixes folders, account settings, delete account, help, and sign out without grouping or hierarchy.", "A drawer overlays desktop content even though users need to switch between sibling pages repeatedly." ] }, "uxExamples": { "good": [ "Users open the drawer, select Sent, the drawer closes, and Sent becomes the visible destination while Inbox scroll state is preserved.", "Tapping the scrim or pressing Escape dismisses the drawer and returns focus to the menu button.", "A deep link opens content directly without forcing the drawer open, but the drawer still marks the current destination when opened." ], "bad": [ "Selecting a drawer item changes the destination behind the sheet but leaves the drawer covering the new page.", "The drawer steals focus while hidden or leaves keyboard users behind the modal scrim.", "Frequently used primary mobile destinations are hidden in the drawer, forcing repeated open-select-close cycles." ] }, "problemContext": [ "A mobile or constrained layout has more destinations than can fit in bottom navigation or a top app bar.", "Some destinations are secondary, account-related, or less frequent but still need a stable access point.", "The same navigation structure may be modal on phones and persistent or standard on wider screens." ], "selectionRules": [ "Choose a navigation drawer when destinations need occasional access from a constrained layout and can tolerate one extra open step.", "Use a modal drawer when the navigation sheet should temporarily block interaction with the content behind it.", "Use a standard, dismissible, or permanent drawer only when the drawer's relationship to content and layout width is clear.", "Group drawer items by destination type, account, labels, or settings so long lists do not become undifferentiated menus.", "Keep bottom navigation for the most frequent three to five mobile destinations and put overflow or secondary destinations in the drawer only when needed.", "Use persistent side navigation instead of a drawer when desktop users repeatedly navigate within one local section." ], "requiredStates": [ "Closed state with a clear opener such as a menu button.", "Opening or open state with drawer sheet, selected destination, and grouped items.", "Modal scrim state that communicates the underlying content is blocked.", "Dismissed state from scrim, Escape, close button, item selection, or platform gesture.", "Selected destination state after the drawer closes.", "Responsive state that changes between modal, dismissible, standard, or permanent behavior without changing labels unexpectedly." ], "interactionContract": [ "The opener toggles or opens the drawer and exposes expanded or modal state as appropriate.", "A modal drawer prevents interaction with content behind it until dismissed.", "Selecting a drawer destination closes the drawer and updates the active destination.", "Scrim click, Escape, close controls, or platform gestures dismiss the drawer without changing destination.", "Focus moves into the modal drawer when it opens and returns to the opener or new page heading when it closes.", "The selected drawer item must match the current destination when the drawer is opened after a route change." ], "implementationChecklist": [ "Define which destinations belong in the drawer and which deserve persistent bottom, global, or side navigation.", "Provide an explicit opener with an accessible name and consistent placement.", "Render modal drawers with a scrim and dismissal behavior that matches the platform.", "Group long drawer lists with headings or dividers and keep labels short.", "Mark the current destination programmatically and visually.", "Close the drawer after destination activation and verify focus movement.", "Test responsive breakpoints so drawer, side navigation, and bottom navigation do not duplicate the same primary destination set." ], "commonMisuses": [ "Hiding the app's most important destinations in a drawer on mobile.", "Leaving a modal drawer open after a destination is selected.", "Providing no scrim, Escape, close control, or outside-dismiss behavior for a modal drawer.", "Using the menu icon for unrelated actions on different screens.", "Mixing destructive account actions with normal destinations without grouping or confirmation.", "Duplicating the same destinations in bottom navigation and a drawer without clear overflow logic." ], "critiqueQuestions": [ "Which destinations are frequent enough to stay visible, and which belong in the drawer?", "Can users dismiss the drawer without changing destination?", "Does selecting an item close the drawer and reveal the new destination?", "Does keyboard focus move into and out of the modal drawer predictably?", "Will this drawer become persistent side navigation on larger screens, and are labels consistent across variants?" ], "relatedPatterns": [ "side-navigation", "bottom-navigation", "header", "global-navigation" ], "comparisons": [ "navigation-drawer-vs-side-navigation-vs-bottom-navigation" ], "sourceIds": [ "material-navigation-drawer", "android-compose-navigation-drawer", "uswds-side-navigation" ] }, { "id": "no-results-recovery", "completionStatus": "complete", "name": "No-results recovery", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Search recovery state", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "A search or filter returns nothing, leaving users without a path forward.", "solution": "Explain that no matches were found, preserve the user's query or filters, and offer specific ways to broaden or correct the search.", "uiGuidance": [ "Render zero-result copy, active criteria, remove-filter actions, and alternative suggestions.", "Keep query and filters visible so users know what caused the state." ], "uxGuidance": [ "Help users recover when their own search or filters excluded all results.", "Suggest narrower, broader, or reset paths without implying system failure." ], "uiExamples": { "good": [ "Zero-result state shows query/filters, result count, and clear or broaden actions.", "Recovery suggestions are visually close to the empty result area." ], "bad": [ "No results text alone with no criteria shown.", "Huge empty state that hides active filters." ] }, "uxExamples": { "good": [ "Users can remove one filter, clear all, edit query, or try suggested alternatives.", "The system distinguishes no results from load failure." ], "bad": [ "Telling users nothing exists when filters caused the state.", "Resetting all criteria without confirmation when users only meant to remove one." ] }, "problemContext": [ "A valid search, filter, or browse action produces zero visible items.", "The user may be able to broaden, correct, or redirect their task." ], "selectionRules": [ "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." ], "requiredStates": [ "Zero-result state that preserves the user's criteria.", "Recovery state with clear filters, broaden query, or browse alternatives.", "Recovered state after criteria are changed.", "Unavailable state if no alternatives exist." ], "interactionContract": [ "The UI must explain that no matches were found and identify the active constraints.", "Recovery actions must be specific and immediately usable.", "Clearing filters or changing search must update results and count predictably." ], "implementationChecklist": [ "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." ], "commonMisuses": [ "Showing a blank list with no explanation.", "Resetting all criteria automatically.", "Offering generic help that does not change the result set." ], "critiqueQuestions": [ "Does the user have a clear next action that can produce results again?" ], "relatedPatterns": [ "faceted-search", "empty-state", "error-state" ], "comparisons": [ "faceted-search-vs-no-results-recovery", "empty-state-vs-no-results-recovery-vs-error-state" ], "sourceIds": [ "maersk-handling-no-results", "carbon-empty-states-pattern", "scottish-government-search-filters", "govuk-design-system-patterns" ] }, { "id": "notification-banner", "completionStatus": "complete", "name": "Notification banner", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Page-flow service notification before the H1", "maturity": "standard", "platforms": [ "web", "mobile" ], "problem": "Users sometimes need service-context information, a personal deadline, or a previous-page outcome before reading the next page, but ordinary page content, toasts, or broad product banners either make the message too local, too temporary, or too wide in scope.", "solution": "Place one concise notification banner immediately before the page heading, state the service condition or outcome, provide a direct link when useful, choose calm region semantics for page-load notices and alert semantics only for success outcomes that should receive focus, then remove it when the page-flow reason ends.", "uiGuidance": [ "Render one notification banner in the page content column immediately before the page H1, using the same width as the surrounding service content.", "Give the banner a short labelled header such as Important or Success, concise content, and at most one relevant link or action that points to the related service item." ], "uxGuidance": [ "Use notification banners sparingly for information users need before interpreting the page but that is not the main task content on that page.", "Reserve the pattern for service-wide problems, personal deadlines or obligations elsewhere in the service, and outcomes from a previous page when the journey continues rather than ends." ], "uiExamples": { "good": [ "A case-management page shows an Important notification banner immediately before Manage evidence, saying evidence upload may be delayed and linking to service status.", "After a user uploads evidence, the next page shows a Success notification banner before the H1 confirming Evidence uploaded and linking to View evidence." ], "bad": [ "A validation error appears in a notification banner at the top of the page with no links to the invalid fields.", "A success toast appears in the corner after redirect and disappears before the user can verify which evidence was uploaded." ] }, "uxExamples": { "good": [ "A user lands on Evidence overview and sees the upload confirmation before the page heading, then can continue the unfinished service journey.", "A deadline notice tells the user they must respond by 17 June 2026 and links to the exact task elsewhere in the service." ], "bad": [ "The same upload confirmation remains on unrelated pages after the user has already reviewed the evidence record.", "An outage that affects every workspace is repeated as a page-level notification banner instead of one broader service or product banner." ] }, "problemContext": [ "The message is important to the service journey but not directly part of the page's main task content.", "Users may arrive after a redirect from a previous page and need confirmation before continuing the journey.", "A service problem, personal deadline, overdue action, or elsewhere-in-service event affects how users interpret the page.", "The message can be handled with one short banner before the H1 rather than a modal, stacked banner set, or long status panel." ], "selectionRules": [ "Choose notification banner when a service message should be seen immediately before the page heading and before users interpret that page.", "Use the neutral version for service problems, delays, deadlines, overdue actions, or elsewhere-in-service information that is not a direct validation or current-task error.", "Use the success version only to confirm an outcome from the previous page while the user has not finished the overall service journey.", "Use banner instead when the message must persist across a whole product, account, workspace, or multi-section interface rather than one page-flow moment.", "Use alert instead when an urgent condition dynamically affects the current task and needs immediate notice without moving users into a confirmation page.", "Use error summary instead for submitted form validation errors, including multiple field errors that need links to specific inputs.", "Use inline message or warning text instead when the information is directly about content, controls, or a task section already visible on the page.", "Show no more than one notification banner per page; combine closely related messages or show only the highest-priority one." ], "requiredStates": [ "No-banner state when no service-context notice or previous-page outcome applies.", "Neutral Important state for service problem, deadline, overdue action, or elsewhere-in-service information.", "Success state for an outcome from the previous page when users continue the journey.", "Linked action state where a single link or button takes users to the affected application, evidence record, payment, or status details.", "Detail state for a short explanation that clarifies why the message appears before the heading.", "Resolved state after the deadline passes, service delay ends, or the previous-page outcome has been acknowledged through the next step.", "Priority state where a validation error summary replaces the notification banner on failed submit." ], "interactionContract": [ "The banner appears before the page H1 and in the same content width as the heading and body text.", "The banner title communicates category or outcome, while the body names the specific service condition, deadline, or previous-page result.", "The banner does not stack with an error summary; failed-submit pages show the error summary instead.", "The neutral banner uses labelled region semantics so users can navigate to it without being interrupted.", "A success notification that appears after a user action may receive focus or alert treatment only when that helps confirm the previous-page outcome.", "Any link or action in the banner goes directly to the affected service item, status page, deadline task, or uploaded record.", "The banner disappears when the service condition, deadline relevance, or redirect-outcome reason no longer applies." ], "implementationChecklist": [ "Define whether the notice is a service problem, personal obligation, deadline, elsewhere-in-service event, or previous-page outcome.", "Place the component immediately before the H1 in the page template, aligned to the same content grid as headings and body text.", "Select neutral or success presentation from the user consequence, not from brand color preference.", "Write copy that says what happened, who is affected, and the single next step or link if one exists.", "Suppress the notification banner when a form submission on the same page produces an error summary.", "Prevent multiple notification banners on one page by merging related content or applying explicit priority.", "Expire previous-page success banners after the landing page has been read, the linked record is opened, or the user moves outside the related flow.", "Test deep links, redirects, browser back, narrow widths, zoom, heading order, focus movement for success, and screen-reader navigation by region label." ], "commonMisuses": [ "Using a notification banner for field validation errors instead of an error summary and field-level messages.", "Showing several notification banners before the same heading.", "Putting the banner after the H1, in a sidebar, or above unrelated global chrome where users cannot connect it to the page flow.", "Using it as a product-wide outage banner that needs to persist across many sections.", "Leaving a previous-page success banner visible after users navigate to unrelated pages.", "Auto-expiring a confirmation that users need to inspect after a redirect.", "Writing only Important or Success without the affected service item, date, or next step." ], "critiqueQuestions": [ "Does this message need to appear immediately before the page heading, or does it belong in the page content, a broader banner, an alert, or an error summary?", "Is the notice about a service problem, personal deadline, elsewhere-in-service event, or previous-page outcome?", "Would users still need this message after navigating to a different section or returning later?", "Is there already a failed-submit error summary that should replace the notification banner?", "What event removes the banner: condition resolved, deadline passed, landing page viewed, linked record opened, or flow completed?", "Does the banner contain one clear route to the affected item rather than several competing actions?" ], "relatedPatterns": [ "banner", "alert", "error-summary", "inline-message", "toast-notification", "service-navigation" ], "comparisons": [ "notification-banner-vs-banner-vs-alert-vs-error-summary" ], "sourceIds": [ "govuk-notification-banner-component", "carbon-notification-pattern", "carbon-notification-component", "wcag-status-messages" ] }, { "id": "notification-center", "completionStatus": "complete", "name": "Notification center", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Durable user-opened notification history and action drawer", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users receive asynchronous work updates, mentions, background-job results, reminders, and system messages across many objects, but transient toasts, local alerts, or email alone make those messages easy to miss, impossible to triage, or noisy enough to ignore.", "solution": "Create a durable notification center with a stable entry point, explicit unread and unseen semantics, chronological and filterable items, direct routes to related work, preference controls, predictable cleanup, and escalation rules for messages that need immediate in-context treatment.", "uiGuidance": [ "Provide a persistent notification entry point, usually a bell or inbox control, with a count that represents new unseen notifications rather than every unread item forever.", "Render the center as a drawer, panel, page, or tray with chronological items, clear read and unread states, filters, timestamps, source labels, and direct actions or links to the related object." ], "uxGuidance": [ "Use a notification center when users receive enough asynchronous system or collaboration updates that they need a durable place to review, triage, and act later.", "Design the notification lifecycle deliberately: what creates an item, what increments the badge, what marks it read, what clears it after related work is viewed elsewhere, and what preferences reduce noise." ], "uiExamples": { "good": [ "A bell opens a drawer with Unread and All filters, showing comment mentions, approval requests, export results, and background-job failures in newest-first order.", "A notification item shows source, object name, timestamp, read state, one primary action, and a secondary mark-read control." ], "bad": [ "A red badge says 42 forever because opening the drawer, reading items, and viewing related work never update the count.", "Expired toast messages are copied into a center with no timestamps, no source, and no route to the affected object." ] }, "uxExamples": { "good": [ "Opening the notification drawer clears the new-notification badge while unread items remain available for later triage.", "After the user opens the mentioned pull request from another route, the matching notification is marked read or removed from actionable lists." ], "bad": [ "A payment failure that blocks the current checkout is only stored in the notification center and never appears in the task.", "Users mark all notifications read and lose the only record of an export job they still need to download." ] }, "problemContext": [ "Notifications are generated by system events, collaboration activity, background jobs, reminders, approvals, comments, assignments, or policy checks across multiple objects.", "Users may not be present when a notification is created and may need to inspect it later without searching email or activity logs.", "Some notifications are useful only until the related object is viewed or resolved; others are durable evidence users may need later.", "Users need tools to reduce noise without losing important work, such as unread filters, grouping, preferences, and mark-read controls." ], "selectionRules": [ "Choose notification center when messages must be revisitable after toast, push, email, or inline surfaces have disappeared.", "Use it for asynchronous cross-object events such as mentions, review requests, assignment changes, export-ready notices, background-job failures, scheduled reminders, and policy acknowledgements.", "Use toast notification instead for short current-action feedback that can disappear because a durable record is not needed or exists in a job history.", "Use alert instead for urgent current-task conditions that must remain visible until resolved, such as session expiry, unsynced work, or payment hold.", "Use inline message instead when the notification belongs beside one visible object, row, field group, or panel.", "Use banner or site alert instead when the message applies broadly to a product, workspace, service, or public site rather than the user's notification history.", "Separate unseen count from unread state so opening the center can clear the badge without destroying triage state.", "Remove, collapse, or mark notifications read when users view the related object elsewhere, according to the product's cleanup policy." ], "requiredStates": [ "Closed entry-point state with zero, new-unseen, and unread-but-seen counts.", "Open drawer or page state with newest-first notifications.", "Unread, read, selected, and actioned item states.", "Unread-only, all, source, urgency, or type filter states.", "Empty state for no notifications and no unread notifications.", "Suppressed-to-center state where a low-disruption notification arrives without a toast.", "Mark-one-read and mark-all-read states.", "Related-object-viewed cleanup state where stale notifications disappear or become read.", "Preference state for muting noisy sources or changing delivery channels.", "Error or offline state where the center cannot refresh but preserved items remain visible." ], "interactionContract": [ "The entry point opens the notification center without navigating away from the current task unless the product uses a dedicated full page.", "Opening the center clears the unseen badge count but does not automatically mark every item read unless the product explicitly communicates that policy.", "Each item names the source, event, related object, timestamp, current read state, and one direct destination or action.", "Filters never delete notifications; they only change which items are visible.", "Marking an item read, marking all read, archiving, or clearing a notification has immediate visible feedback and can be understood from the current filter.", "Selecting a notification opens the related object in context and updates notification state predictably.", "Muted sources, suppressed delivery, and channel preferences reduce interruptions without hiding critical current-task blockers." ], "implementationChecklist": [ "Define notification types, sources, recipients, delivery channels, retention period, and whether each type increments unseen count.", "Model unseen, unread, read, actioned, archived, suppressed, stale, and expired states separately.", "Design badge behavior for closed center, first open, subsequent opens, and cross-device viewing.", "Sort notifications newest-first by received time and add source, object, timestamp, and urgency metadata.", "Provide filters for unread and high-value sources before adding bulk actions.", "Implement mark one read, mark all read, and optional archive or clear actions with reversible or understandable effects.", "Synchronize notification state when the related object is viewed, resolved, deleted, permission-revoked, or completed elsewhere.", "Provide preferences for noisy sources, delivery channels, digest frequency, and quiet modes while preserving critical in-context alerts.", "Test keyboard opening, focus containment or return, screen-reader labels for badge counts, virtualized long lists, empty filters, offline refresh, and mobile drawer behavior." ], "commonMisuses": [ "Treating the badge count, unread count, and total notification count as one number.", "Clearing all unread items just because the drawer opened.", "Deleting notifications when a filter is applied.", "Using the center as the only surface for critical current-task blockers.", "Repeating the same notification every few minutes when the user has not interacted with it.", "Leaving resolved or inaccessible notifications actionable.", "Offering no notification preferences in products that generate frequent asynchronous messages.", "Letting old notifications accumulate without retention, grouping, search, or cleanup rules." ], "critiqueQuestions": [ "Which notification types deserve a durable center item instead of only a toast, email, inline message, or activity log entry?", "What exact event increments the badge, and what event clears only the unseen count?", "What makes an item read: opening the center, selecting the item, viewing the related object, or explicit mark-read action?", "What happens when the related object is completed, deleted, archived, or no longer accessible?", "Which sources can users mute, and which critical conditions must still surface in context?", "How long should notifications remain, and where can users find older proof if it expires from the center?" ], "relatedPatterns": [ "toast-notification", "alert", "inline-message", "banner", "site-alert", "search-history" ], "comparisons": [ "notification-center-vs-toast-notification-vs-alert-vs-inline-message" ], "sourceIds": [ "carbon-notification-pattern", "carbon-notification-component", "atlassian-cloud-notification-drawer", "microsoft-windows-notification-ux-guidance" ] }, { "id": "notification-preferences", "completionStatus": "complete", "name": "Notification preferences", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "User-controlled rules for notification type, channel, frequency, timing, privacy, and exceptions", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Notification systems overwhelm users or make them miss important work when preferences hide event types, delivery channels, frequency, quiet hours, digest behavior, privacy previews, device permissions, admin overrides, and critical exceptions.", "solution": "Provide a clear notification preferences surface that lets users tune notification types, sources, channels, devices, timing, previews, sounds, digests, quiet hours, keywords, and exceptions while preserving critical delivery and explaining overrides.", "uiGuidance": [ "Render notification preferences as a structured matrix or grouped settings surface that shows notification type, source, delivery channel, device, frequency, quiet-time rule, preview privacy, override, and current saved state.", "Separate notification preferences from notification center, follow / subscribe, and general settings by showing that the user is configuring delivery behavior rather than reading delivered items, opting into one object, or editing unrelated app configuration." ], "uxGuidance": [ "Use notification preferences when users need to reduce noise without missing important mentions, assignments, security notices, incidents, reminders, or followed-object updates.", "Make consequences explicit: what stops, what still arrives, which devices and channels are affected, when changes apply, and which admin, OS, or workspace policies override the user's choice." ], "uiExamples": { "good": [ "A notification preferences page groups Mentions, Assigned work, Followed threads, Security, Digest, and Marketing, with columns for In-app, Email, Push, Banner, and Digest frequency.", "A mobile override row says Push is enabled in app but blocked by iOS settings, with an Open system settings action and a preserved in-app preference." ], "bad": [ "A single Notifications off switch disables email, push, badges, and mention banners without saying whether security alerts or approvals still arrive.", "A page lists All, Some, and None for notifications but never maps those labels to event types, channels, or devices." ] }, "uxExamples": { "good": [ "A user keeps mentions and assigned-work banners on, moves repository watch updates to daily digest, mutes marketing email, and sees a preview of what will still notify them during quiet hours.", "A user turns off mobile push after hours, but urgent incident alerts remain allowed and the UI explains the exception." ], "bad": [ "A user disables email for a noisy project and still receives duplicate push and desktop banners because those channels live in separate hidden settings.", "A user enables digest delivery and misses a time-sensitive mention because the preference did not label mentions as an immediate exception." ] }, "problemContext": [ "Notifications may arrive through in-app centers, activity feeds, badges, banners, desktop notifications, push notifications, email, chat integrations, digests, sounds, previews, or system-level alerts.", "Users may want different rules for mentions, DMs, reactions, followed threads, watched spaces, assignments, approvals, incidents, security alerts, marketing, reminders, and background jobs.", "Preferences may be global, workspace-specific, organization-specific, project-specific, channel-specific, device-specific, or inherited from admin policy.", "Operating-system notification permissions, mobile overrides, browser permissions, quiet hours, do-not-disturb modes, and email routing can contradict in-app choices.", "A preference that reduces noise can create coordination risk if it suppresses mentions, assigned work, approvals, security warnings, or urgent incidents." ], "selectionRules": [ "Choose notification preferences when the user needs to configure which notification events produce which delivery behavior.", "Use settings management when notification preferences are one category inside a larger persistent app configuration surface.", "Use notification center for delivered-item inbox behavior such as unread state, filtering, retention, mark-read, and related-object cleanup.", "Use follow / subscribe when the user opts into future updates from one object, channel, thread, space, repository, saved view, or topic.", "Use activity feed when users need a catch-up stream of work events rather than delivery rules.", "Use toast notification when the product needs transient current-action feedback that should not require user preference before it appears.", "Use alert, inline message, or banner for current-task blockers that must appear regardless of ordinary notification preferences.", "Use mentions when a sender routes attention; use preferences to control delivery channels for those mention events.", "Expose type-by-channel choices for high-volume products instead of one master on/off switch.", "Show critical exceptions, quiet-hour bypass rules, admin-managed settings, OS permission blocks, and unsaved or failed-save state close to the affected preference.", "Let users preview or summarize what will still notify them before they save aggressive muting or digest changes." ], "requiredStates": [ "Default notification preferences state.", "Per-event-type channel matrix state.", "Immediate, daily digest, weekly digest, and never frequency states.", "Quiet hours or quiet days state.", "Critical exception or bypass state.", "Device override state such as mobile push differs from desktop banners.", "OS or browser permission blocked state.", "Admin-managed or workspace policy override state.", "Muted source, channel, project, or conversation state.", "Keyword or custom routing state.", "Preview privacy or sound appearance state.", "Unsaved changes, saved, failed save, and restored defaults state." ], "interactionContract": [ "Opening notification preferences shows current saved values for each notification type and delivery channel.", "Changing a preference names the affected event type, channel, device, frequency, and scope before save or immediate apply.", "Quiet hours and digest settings reveal exceptions for urgent, security, assigned, or mentioned work.", "If operating-system, browser, workspace, or admin policy blocks delivery, the affected control explains the owning layer and links to the right place when possible.", "Muting a source or channel does not silently change global notification preferences unless the UI previews that scope.", "Saving preferences confirms what changed and preserves unsaved choices on failure.", "Reset restores only notification preferences or the named group, not unrelated settings." ], "implementationChecklist": [ "Inventory notification event types, sources, urgency levels, delivery channels, devices, default values, critical exceptions, and legal or security requirements.", "Model user preferences separately from per-object subscriptions, delivered notification records, activity feed items, admin policies, and OS permissions.", "Design channel and event-type controls for in-app, email, push, banner, badge, sound, digest, and integration destinations.", "Support quiet hours, quiet days, digest cadence, preview privacy, keyword alerts, custom routing, mobile overrides, and mute behavior where the product offers them.", "Represent admin-managed values, system permission blocks, browser permission prompts, and unavailable channels without pretending the user choice applied.", "Deduplicate deliveries when one event matches multiple subscriptions, mentions, project rules, or digest rules.", "Test keyboard access, screen-reader names, high zoom, mobile layout, long notification type labels, save failures, cross-device sync, policy overrides, and aggressive mute previews." ], "commonMisuses": [ "Offering one master notification switch for a complex collaboration product.", "Letting users disable critical current-task, security, billing, or incident alerts without an exception model.", "Hiding email, push, in-app, banner, sound, badge, and digest settings in unrelated places.", "Showing a preference as enabled when OS permissions or admin policy prevent delivery.", "Using vague labels such as Important, Some, or Recommended without listing included event types.", "Making quiet hours suppress mentions or assignments that the product later treats as urgent.", "Resetting unrelated app settings from a notification preference reset action.", "Failing to deduplicate notifications across mentions, watched objects, subscriptions, and digests." ], "critiqueQuestions": [ "Which exact event types does each preference control?", "Which delivery channels, devices, and frequencies are affected by this change?", "What still breaks through quiet hours, digest, mute, or master-off states?", "Can users tell whether OS permission, browser permission, admin policy, or workspace rules override their choice?", "How does the product prevent duplicate delivery when multiple rules match the same event?", "Can users recover from over-muting before they miss important work?" ], "relatedPatterns": [ "settings-management", "notification-center", "follow-subscribe", "activity-feed", "toast-notification", "mentions", "permission-denied-state" ], "comparisons": [ "notification-preferences-vs-settings-management-vs-notification-center-vs-follow-subscribe" ], "sourceIds": [ "github-configuring-notifications", "github-managing-organization-notifications", "slack-configure-notifications", "slack-guide-notifications", "microsoft-teams-manage-notifications", "atlassian-jira-personal-notification-settings", "atlassian-confluence-email-notifications" ] }, { "id": "object-picker", "completionStatus": "complete", "name": "Object picker", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Existing-entity lookup and selected-object confirmation", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to link, assign, or reference an existing entity, but names can be duplicated, records can be scoped or restricted, and a text-only autocomplete can submit the wrong hidden object ID.", "solution": "Provide a scoped object lookup that searches permitted entities, displays disambiguating metadata, requires explicit selection of an existing object, shows a selected-object preview, and keeps the visible label synchronized with the submitted identity.", "uiGuidance": [ "Render a labelled lookup field with search text, scoped result list, active result, selected object chip or preview, object type, stable ID or equivalent key, secondary metadata, clear action, no-result state, loading state, and validation text.", "Show enough fields to distinguish same-named objects before selection, and keep the selected object preview visible after the popup closes so the submitted entity can be inspected." ], "uxGuidance": [ "Use an object picker when the user must choose an existing entity whose identity matters beyond the displayed label, such as a record, person, group, account, file, team, project, or workspace.", "Protect users from linking the wrong entity by scoping search, disambiguating duplicate names, clearing stale selected IDs after edits, and requiring explicit selection of a valid object before save." ], "uiExamples": { "good": [ "A Related account field shows two Acme Retail records with account ID, region, status, and owner, then displays a selected-object preview card before saving.", "A people picker shows avatar or initials, full name, email, job title, and presence while preserving the selected account ID.", "A project lookup includes a scope chip for Active projects, a no-results message for the current scope, and a clear control that removes both visible label and submitted ID." ], "bad": [ "A text field accepts Acme Retail as free text even though the backend needs a record ID.", "A result list shows three identical names with no metadata, status, owner, or ID.", "A selected label remains visible after the user edits the text while the hidden submitted object ID still points at the previous record." ] }, "uxExamples": { "good": [ "A user searches Acme, compares two same-named records by region and status, selects the active EMEA account, and reviews the selected account ID before saving.", "A user changes the typed text after selecting a project and the selected object clears until a new result is explicitly chosen.", "A user toggles from Active only to All records, sees archived results labelled as archived, and avoids selecting an inactive object by mistake." ], "bad": [ "A user types a person name and presses Save, but no actual user account was selected.", "A user picks the first Acme result because every row looks identical, then links the case to the wrong account.", "A stale hidden ID is submitted after the visible label has been edited to a different name." ] }, "problemContext": [ "The product stores a stable object identity, not only the label the user typed.", "Different entities may share the same name or have similar labels.", "Users may need to see object type, owner, status, location, email, avatar, account, project, or permission scope before selecting.", "Search results may come from a remote service, directory, graph, CRM, repository, or data table with access controls.", "The selected object may affect assignment, permissions, ownership, billing, workflow routing, or linked records." ], "selectionRules": [ "Choose object picker when users must select an existing record, person, group, file, account, project, team, workspace, or other entity with a stable ID.", "Use combobox when the main requirement is one popup-owned field value and entity identity metadata is not central to the task.", "Use autocomplete when suggestions complete a known text value and the submitted value does not require previewing an object record.", "Use multi-select or chip selection when users choose several simple values; use object picker for one or more entities only when each selected item needs identity, metadata, or permission-aware validation.", "Use transfer list when users move objects into a separate selected destination set with ordering, locked items, or batch review.", "Use tree selection when hierarchy is the primary way to understand and select entities.", "Restrict result scope to the current task when possible, and label any broadened scope such as All records, Archived, External, or Directory.", "Require a selected object ID before submit when free text is not valid.", "Clear the selected ID or mark it unresolved whenever the visible text no longer matches the committed object." ], "requiredStates": [ "Empty object lookup field with label, helper text, and current search scope.", "Focused field with popup available and no committed object.", "Loading remote results state for the current query and scope.", "Filtered result list with active result and disambiguating metadata.", "Duplicate-label result state with distinct type, status, owner, region, email, or ID.", "Selected object state with visible chip, preview card, object type, and stable identity.", "Edited-after-selection unresolved state where the submitted ID is cleared.", "No results in current scope state with a safe way to broaden or change scope.", "Permission-restricted result state that explains why an object is unavailable when the product can disclose it.", "Required valid-object validation state for unresolved text or empty selection.", "Disabled or read-only state with selected object still inspectable." ], "interactionContract": [ "Typing searches or filters permitted objects without committing the first visible result.", "Arrow keys or equivalent controls move the active result independently from the selected object.", "Enter, pointer selection, or an explicit Choose action commits the active object and synchronizes the selected ID, visible label, and preview.", "Editing the visible text after a committed selection clears or invalidates the selected object until another result is chosen.", "Scope changes refresh results while preserving the selected object only if it still belongs to the allowed scope.", "The user can clear the selected object and recover from no-result, loading, unavailable, and validation states without losing form context." ], "implementationChecklist": [ "Define the object type, submitted ID, display label, secondary fields, permission scope, and duplicate-label strategy before building the picker.", "Use an accessible combobox, listbox, dialog, or platform picker structure with labelled input, expanded state, active option, selected state, and validation text.", "Show secondary metadata such as email, owner, status, type, region, path, account, project, or ID in every result row where labels may collide.", "Synchronize visible text, selected object, submitted ID, preview card, clear action, and validation state as one state machine.", "Debounce remote search, cancel stale responses, expose loading and no-result states, and avoid leaking inaccessible object names.", "Test duplicate names, archived or inactive records, permission-denied objects, slow search, scope changes, stale IDs, keyboard selection, screen readers, high zoom, mobile fallback, and localization." ], "commonMisuses": [ "Treating the picker as a free text field when the system requires an existing object ID.", "Displaying only names for entities that commonly share names.", "Submitting a hidden object ID after the visible text changes.", "Searching an unbounded directory when the task has a clear project, account, group, or status scope.", "Using object picker for a short static enum that should be radio, select, listbox, or checkbox group.", "Hiding unavailable or archived status until after the user saves." ], "critiqueQuestions": [ "What exact object ID is submitted, and can the user inspect it before saving?", "Can users distinguish same-named entities without opening another page?", "Does editing the visible label clear the committed object identity?", "Is search limited to the task's relevant scope, and are broadened scopes labelled?", "What happens when results are loading, empty, stale, archived, inaccessible, or duplicated?" ], "relatedPatterns": [ "combobox", "autocomplete", "multi-select", "transfer-list", "tree-selection", "listbox", "select", "inline-validation" ], "comparisons": [ "object-picker-vs-combobox-vs-autocomplete-vs-multi-select" ], "sourceIds": [ "salesforce-lightning-record-picker", "atlassian-forge-user-picker", "microsoft-power-platform-peoplepicker", "mui-autocomplete-object-options", "wai-aria-apg-combobox" ] }, { "id": "official-site-banner", "completionStatus": "complete", "name": "Official-site banner", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Top-of-page official identity and secure-connection disclosure for eligible government or public-authority websites", "maturity": "established", "platforms": [ "web", "mobile" ], "problem": "Users can mistake spoofed, partner, staging, insecure, or unaffiliated sites for official services when official ownership and secure-connection signals are hidden, inconsistent, misleading, or mixed with ordinary announcements.", "solution": "Show a jurisdiction-approved official-site banner at the top of eligible pages with official identity text, symbol, trusted-domain explanation, HTTPS explanation, accessible expandable details, consistent placement, and strict rules preventing misleading use.", "uiGuidance": [ "Place the official-site banner at the very top of every eligible page, before the header, service navigation, alerts, and page content.", "Use the approved jurisdictional identity text, official symbol, domain explanation, HTTPS or lock explanation, and expandable details rather than custom trust copy or marketing language." ], "uxGuidance": [ "Use the banner to help users verify official ownership and secure connection status before they share personal, financial, health, legal, or account information.", "Keep it consistent, non-dismissible where required, and honest about eligibility; do not use official identity treatments on staging, partner, non-government, or insecure surfaces." ], "uiExamples": { "good": [ "A benefits service shows an official government banner above the header with a flag, official-site text, a How you know disclosure, and expanded .gov plus HTTPS explanations.", "An agency site repeats the official banner on every page before the service header, while service navigation and emergency site alerts remain visually separate below it." ], "bad": [ "A private vendor checkout copies government official-site copy while using a commercial domain.", "A real agency site places official identity in a footer seal after users have already entered sensitive data." ] }, "uxExamples": { "good": [ "A user expands the banner before entering a tax ID, reads that .gov belongs to an official government organization, checks the HTTPS guidance, and continues with more confidence.", "A user on a mobile page opens the identity details, sees both domain and secure connection guidance in a compact stack, and returns to the form without losing progress." ], "bad": [ "A staging site uses official banner copy during a user test and participants believe it is a live government service.", "A banner says the site is secure even though the page is served over HTTP and lacks a trusted government domain." ] }, "problemContext": [ "Official-site banners appear on government, public-authority, benefits, tax, health, immigration, identity, veterans, legal, licensing, emergency, and account services where users may share sensitive information.", "The banner teaches users how to verify official status and connection security, but it does not replace phishing detection, browser security warnings, service navigation, agency branding, or content trust.", "Eligibility depends on jurisdiction and platform rules such as official government ownership, approved domain, HTTPS, correct symbols, production status, and non-misleading presentation.", "The banner sits above the header and must stay separate from service navigation, maintenance banners, notification banners, emergency site alerts, phase banners, and marketing messages." ], "selectionRules": [ "Choose official-site banner when a page is eligible to claim official government or public-authority identity and users need to verify domain and secure connection status.", "Use it on every eligible page, including interior service pages, before users enter sensitive information.", "Use banner for broad product messages that are not official identity or secure-connection verification.", "Use site alert for urgent sitewide incidents that require temporary public attention.", "Use notification banner for before-heading service notices such as personal deadlines or previous-page outcomes.", "Use security warning when the system detects a dangerous destination, certificate issue, unsafe download, or phishing risk.", "Use service navigation for named-service movement and current-section state, not for official-ownership proof.", "Do not use official-site banner on non-government, partner, prototype, staging, non-HTTPS, or unapproved-domain pages where it would mislead users." ], "requiredStates": [ "Collapsed official identity state.", "Expanded details state with trusted-domain explanation.", "Expanded details state with HTTPS or lock explanation.", "Every-page top placement state.", "Mobile compact expanded state.", "Agency or jurisdiction identity variant.", "Non-eligible domain blocked or alternate identity state.", "HTTP or insecure connection failure state.", "Staging or prototype warning state.", "Interaction with site alert, service navigation, phase banner, and language selector states." ], "interactionContract": [ "The banner appears before the header, service navigation, site alerts, notification banners, and main content.", "The collapsed label identifies the page as official only when the current domain, protocol, and ownership are eligible.", "The disclosure control expands details without navigating away or moving focus unexpectedly.", "Expanded details explain trusted-domain rules and HTTPS or lock indicators in plain language.", "The banner does not disappear through ordinary dismissal, marketing preference, or local route changes when the standard requires every-page presence.", "If a page is ineligible, insecure, staging, or partner-hosted, the product uses alternate identity copy instead of official-site banner claims.", "Emergency site alerts, product banners, service navigation, phase banners, and notification banners remain separate surfaces below the identity banner.", "The banner is tested on compact widths, high zoom, keyboard, screen reader, no-JavaScript details fallback, and language variants." ], "implementationChecklist": [ "Confirm the site is eligible by jurisdiction, ownership, production status, official domain, HTTPS certificate, and platform policy.", "Use the approved component, official symbol, wording, details structure, and accessibility semantics for the jurisdiction.", "Place the banner at the very top of every eligible page before the header and service navigation.", "Include trusted-domain and HTTPS explanations in an expandable or otherwise accessible details region.", "Keep ordinary maintenance, emergency, phase, validation, marketing, and service-navigation content out of the official identity banner.", "Add guards so staging, prototype, non-HTTPS, partner, and non-government domains cannot render misleading official-site copy.", "Test keyboard toggle behavior, focus order, screen-reader labels, high zoom, compact layout, translated copy, and coexistence with site alerts and service navigation.", "Monitor domain, certificate, and deployment changes so official identity claims stay accurate." ], "commonMisuses": [ "Copying an official government banner onto a private, partner, staging, or prototype site.", "Using the banner without an approved government domain or HTTPS.", "Making the official identity banner dismissible so users cannot later verify domain and secure connection guidance.", "Mixing official identity proof with maintenance notices, outage alerts, campaign messages, or navigation links.", "Replacing the official banner with a logo, footer seal, agency header, or unverified trust badge.", "Showing secure-site language on an insecure page.", "Changing approved official wording into marketing copy that sounds more persuasive but less verifiable." ], "critiqueQuestions": [ "What rule proves this page is eligible to claim official identity?", "Is the banner first on the page before header, alerts, service navigation, and content?", "Does the detail region explain the trusted domain and HTTPS indicators users can actually verify?", "What prevents staging, prototype, partner, non-HTTPS, or non-government pages from rendering this banner?", "Can keyboard and screen-reader users expand the details and return to the page task?", "Are emergency alerts, service navigation, and product messages kept outside the identity banner?", "How will the banner behave under localization, compact viewport, high zoom, and route changes?" ], "relatedPatterns": [ "banner", "site-alert", "notification-banner", "security-warning", "service-navigation", "phase-beta-banner", "header", "global-navigation", "warning-text", "permission-request" ], "comparisons": [ "official-site-banner-vs-banner-vs-site-alert-vs-notification-banner-vs-security-warning-vs-service-navigation" ], "sourceIds": [ "uswds-banner-component", "digitalgov-federal-government-banner", "va-official-gov-banner", "cms-usa-banner", "govuk-service-look-like-govuk" ] }, { "id": "offline-mobile-retry", "completionStatus": "complete", "name": "Offline mobile retry", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Mobile queued-action retry and background replay recovery", "maturity": "standard", "platforms": [ "mobile", "web" ], "problem": "Mobile users often lose connectivity, background the app, switch networks, enter captive portals, hit metered or low-battery constraints, or attach large files while trying to save, send, upload, submit, or check in, and they need to know whether the action is queued, retrying, safe to retry, blocked, or already accepted.", "solution": "Provide an offline mobile retry surface that persists the original action locally, exposes queue and attempt status, retries automatically only when allowed, offers manual retry and cancel controls, guards duplicate side effects with stable request identity, and hands off to sign-in, conflict review, fallback, or support when retry can no longer proceed safely.", "uiGuidance": [ "Render a mobile retry surface that names the queued action, local storage location, last attempt, next retry trigger, manual retry control, background retry eligibility, and duplicate-submit guard instead of using only a global offline banner.", "Show mobile-specific constraints such as app backgrounded, OS background sync unavailable, Wi-Fi-only upload, metered data pause, low battery pause, captive portal, expired sign-in, attachment retry, and server conflict as distinct retry states." ], "uxGuidance": [ "Use offline mobile retry when users need confidence that a mobile save, send, upload, submit, check-in, or payment attempt is preserved locally and will retry safely when connection and policy conditions allow.", "Keep queued work visible and recoverable until it succeeds, fails with a reason, is cancelled, expires, needs reauthentication, enters conflict review, or moves to a fallback path; never make users guess whether tapping again creates a duplicate." ], "uiExamples": { "good": [ "A mobile inspection form says Saved on this device, 2 photos queued, last attempt 10:42, next retry on Wi-Fi, Retry now, and request ID MOB-1842.", "A failed offline message stays in an outbox row with Waiting for connection, manual Send now, cancel, and background retry paused by low battery.", "After reconnect, the card changes to Retrying upload, disables Submit again, then shows Uploaded or Needs review if server validation fails." ], "bad": [ "A phone shows Sent while in airplane mode and gives no queue, request ID, or local-save explanation.", "Retry keeps firing every few seconds on a metered connection with no pause or Wi-Fi-only choice.", "A generic Pull to refresh reloads the page but does not retry the queued photo upload." ] }, "uxExamples": { "good": [ "A user submits a field report in a basement, sees it queued locally with photos and an idempotency reference, closes the app, and later sees background retry complete after reconnect.", "A user regains network through a captive portal and the retry queue explains Sign in to network before retrying rather than looping silently.", "A user taps Retry now after sign-in expires, is routed through reauthentication, then returns to the same queued item without losing attachments." ], "bad": [ "The user repeatedly taps Submit because the app hides the offline queue and creates duplicate reports after reconnect.", "The app clears a queued upload after OS background sync is unavailable instead of keeping it for foreground retry.", "A payment retry starts automatically after reconnect without telling users whether the first authorization reached the server." ] }, "problemContext": [ "The action originates from a phone, tablet, PWA, mobile webview, or native shell where connectivity, app lifecycle, OS background limits, battery, and metered data can change mid-task.", "Users may attach photos, scan codes, send messages, submit forms, save field records, check in, approve work, invite people, or perform payments while offline or intermittently connected.", "The app can store local payloads, queue requests, identify retryable failures, and distinguish foreground retry from background replay.", "Offline mobile retry sits near offline state, retry, sync state, pull to refresh, fallback path, error state, loading spinner, progress bar, draft state, and conflict resolution." ], "selectionRules": [ "Choose offline mobile retry when a mobile action should be preserved and retried after connection loss, flaky network, app backgrounding, or policy-limited connectivity.", "Show whether the action is saved locally, queued, waiting for connection, retrying in foreground, eligible for background retry, paused, failed, expired, or accepted remotely.", "Keep the original request identity, object, attachment list, timestamp, retry count, and idempotency reference visible or recoverable for side-effecting actions.", "Offer manual Retry now when users need control, but disable duplicate submit while the same queued action is pending or retrying.", "Pause or explain retry when the network is metered, battery saver is active, Wi-Fi-only upload is required, captive portal blocks requests, account sign-in expired, or OS background sync is unavailable.", "Use offline state when the main question is what works while disconnected, not one queued mobile action's retry lifecycle.", "Use retry when a single failed operation is retryable without mobile offline, background, or queue constraints.", "Use sync state when several local and remote copies are reconciling and users need accepted, partial, failed, paused, or conflict status across a queue.", "Use pull to refresh for user-requested content refresh, not for hidden retry of pending submissions.", "Use fallback path when retry is exhausted, unsafe, non-retryable, or requires another channel such as export, manual entry, call support, or later return." ], "requiredStates": [ "Online successful action state.", "No connection at submit state with local queue confirmation.", "Queued mobile action state with request ID, timestamp, and stored payload summary.", "Manual retry-ready state that preserves the original action and disables duplicate submit.", "Retry pending state with attempt count and duplicate guard.", "Background retry eligible and background retry unavailable states.", "App backgrounded or returned-to-foreground state with queue still visible.", "Metered data, Wi-Fi-only, low battery, and battery saver paused states.", "Captive portal or server unreachable state distinct from device offline.", "Sign-in expired or permission changed state that routes to recovery before retry.", "Attachment upload failed, partial upload, and retry attachment states.", "Retry succeeded, failed again, retry exhausted, cancelled, expired, and conflict-needs-review states." ], "interactionContract": [ "The UI never reports server success for a mobile action that is only saved locally or queued.", "Retry repeats the preserved queued action rather than creating a new submission unless users explicitly duplicate or edit it.", "A pending queued action suppresses duplicate Submit, Send, Upload, Pay, Check in, or Approve controls for the same scope.", "Automatic background retry respects OS support, connectivity, battery, metered-data, authentication, idempotency, and retry-limit constraints.", "Manual retry reports pending, succeeded, failed again, paused, sign-in required, conflict, exhausted, or fallback outcome.", "Queued work remains visible after app restart, background return, network change, and page refresh until users resolve or cancel it.", "Side-effecting operations expose enough identity for deduplication, support, and user trust without leaking sensitive payload details." ], "implementationChecklist": [ "Classify mobile actions by retry safety, side effects, idempotency needs, attachment size, credential requirements, and allowed network conditions.", "Persist queued payloads in native storage, IndexedDB, Cache API, service-worker queue, upload manager, or another durable local store with stable IDs.", "Store request ID, retry count, last attempt, next retry time, backoff rule, payload summary, attachment status, and user-visible object name.", "Distinguish device offline, server unreachable, captive portal, timeout, sign-in expired, validation failure, conflict, and policy pause.", "Use background sync or native background transfer only when the UI can show eligibility, retention, retry limits, and foreground fallback.", "Disable duplicate submit while a matching queued action exists, and provide cancel, edit, export, retry now, retry on Wi-Fi, and fallback actions as appropriate.", "Announce meaningful queue transitions such as queued, retrying, sent, failed, paused, sign-in required, and conflict needs review.", "Test airplane mode, tunnel or basement loss, flaky connection, captive portal, low battery, metered data, app kill/restart, background return, duplicate tap, attachment failure, auth expiry, and server conflict." ], "commonMisuses": [ "Showing a success toast for an offline submission that is only queued.", "Hiding the queue after users leave the screen or background the app.", "Letting Submit create a second request while a matching queued request is pending.", "Retrying every few seconds on unstable mobile networks with no backoff or pause.", "Treating captive portal, expired auth, validation failure, and offline as the same retryable state.", "Uploading large attachments on metered data without user control.", "Clearing attachments after a background retry fails.", "Using pull to refresh as the only way to recover queued saves or uploads." ], "critiqueQuestions": [ "What exact mobile action is queued, and where is it saved until retry?", "What proves the server accepted the action, and what visible state exists before that proof?", "What prevents duplicate records, messages, payments, uploads, approvals, or check-ins if users tap again?", "Will retry happen in the background, only in foreground, only on Wi-Fi, or only after sign-in or user action?", "How are metered data, low battery, captive portal, auth expiry, partial attachments, and conflicts represented?", "What is the fallback when retry is exhausted, unsafe, expired, or unsupported by the OS?" ], "relatedPatterns": [ "offline-state", "retry", "sync-state", "pull-to-refresh", "fallback-path", "error-state" ], "comparisons": [ "offline-mobile-retry-vs-offline-state-vs-retry-vs-sync-state-vs-pull-to-refresh-vs-fallback-path" ], "sourceIds": [ "webdev-offline-ux-design-guidelines", "mdn-pwa-offline-background-operation", "mdn-background-synchronization-api", "workbox-background-sync", "microsoft-azure-retry-pattern", "material-design-offline-states" ] }, { "id": "offline-state", "completionStatus": "complete", "name": "Offline state", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Connectivity-mode and local-work continuity state", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users lose connection while reading, editing, saving, uploading, or navigating, and need to know what still works, what is only local, what is stale, and what will happen when the app reconnects.", "solution": "Expose an offline state that scopes the connection loss to affected tasks, keeps cached or local work usable, labels stale and queued data honestly, prevents online-only actions from pretending to succeed, and provides reconnect plus sync handoff paths.", "uiGuidance": [ "Show offline status where it changes the current task, naming what remains available such as cached reports, local draft editing, queued saves, or read-only history.", "Visually distinguish online-saved, device-saved, queued, stale, syncing, and failed-sync states with text labels and actions, not only a disconnected icon or color." ], "uxGuidance": [ "Use offline state to preserve trust and task continuity when connection loss changes what users can read, edit, submit, sync, refresh, or share.", "Keep useful cached and local work available, disable only online-only actions, and move users through reconnect, sync, conflict, or failed-sync handoff when connectivity returns." ], "uiExamples": { "good": [ "A field report says Offline: 3 edits saved on this device, cached customer history shown from 10:42, Submit disabled until connection returns, and Retry connection.", "A cached dashboard labels figures Last updated 09:15, allows filtering cached rows, and disables Refresh and Export with no-connection copy.", "A mobile form header shows No internet, local draft saved, 2 photos queued, and Sync when online." ], "bad": [ "A blank page says You are offline even though the app has cached drafts and help content.", "A green Saved label appears while offline without saying the save is local only.", "All navigation and read-only content are disabled because one submit endpoint is unreachable." ] }, "uxExamples": { "good": [ "A user loses connection while editing an inspection note, sees it saved on this device, attaches photos to a queue, and later watches the queue sync after reconnect.", "A user opens a cached case offline, sees stale timestamp and unavailable online actions, then refreshes successfully when the connection returns.", "A reconnect attempt reaches the server but a queued update fails, so the app keeps the draft and offers retry or export instead of deleting it." ], "bad": [ "The app keeps a spinner on Save during airplane mode and never explains that no network request can start.", "A submitted offline form disappears from the screen even though it was neither queued nor accepted by the server.", "After reconnect, the offline banner vanishes while two unsynced edits remain hidden." ] }, "problemContext": [ "The app can detect a missing, intermittent, captive, or unreachable connection that affects current work.", "Some content, drafts, settings, help, forms, or records may remain useful from cache or local storage.", "Users may start or continue work offline and need to understand whether it is local, queued, blocked, stale, or ready to sync.", "Connectivity can return while queued actions still need upload, server validation, conflict handling, or failure recovery." ], "selectionRules": [ "Choose offline state when connection loss changes what users can read, edit, save, submit, refresh, upload, export, or share.", "State the scope of the outage: whole app, current page, one record, one action, one attachment queue, or one data source.", "Label cached data with its last successful update time or source when freshness affects decisions.", "Label local changes as saved on this device, queued, waiting to sync, or sync failed rather than simply Saved.", "Allow safe local actions such as editing drafts, reading cached content, copying text, or exporting a local backup when available.", "Disable or explain online-only actions such as Submit, Refresh, Share, Export, Payment, or Invite when they cannot complete.", "Provide manual reconnect or retry check when users need control, and automatic reachability checks when appropriate.", "Use error state when a specific operation failed even though the broader app may still be online.", "Use loading spinner only while an operation is actively pending and before the app knows it is offline.", "Use sync state after the connection returns and the main question becomes whether queued changes are reconciling, complete, failed, or conflicting." ], "requiredStates": [ "Online normal state with no offline warning.", "Offline banner or local status that names affected scope.", "Cached read-only state with last updated timestamp.", "Local draft saved state that is not yet server-synced.", "Queued action state for saves, photos, messages, uploads, or submissions.", "Online-only action unavailable state with explanation.", "Reconnecting or checking connection state.", "Reconnected and syncing handoff state.", "Sync failed or conflict-ready state that preserves local work.", "No offline fallback state when nothing useful can be shown except a controlled offline page." ], "interactionContract": [ "The offline indicator appears only when connectivity affects the current task or a global app capability users can reasonably act on.", "The UI never claims a server save, upload, payment, invite, or submit has completed while the app is offline.", "Safe local work remains available and clearly local; unsafe online-only actions are disabled, queued, or routed to an explained fallback.", "Retry connection checks update status to still offline, reconnected, server unreachable, syncing, or failed instead of doing nothing.", "Queued work remains visible until it syncs, fails, is cancelled, exported, or enters conflict resolution.", "Stale cached data is labeled with last updated time and does not silently replace current data after reconnect without reconciliation.", "Focus and announcements communicate major connectivity transitions without interrupting every transient network fluctuation." ], "implementationChecklist": [ "Define connectivity sources: browser online state, server reachability, API health, service-worker cache availability, and per-feature offline capability.", "Inventory which content and actions are available online, cached read-only, editable locally, queued for later, or unavailable.", "Write state copy that names the affected object and save location, such as saved on this device or 2 photos queued.", "Persist local drafts and queued actions with stable IDs, timestamps, user-visible status, and retry or cancel options.", "Use service workers, cache storage, local storage, IndexedDB, native storage, or platform queues according to product architecture.", "Keep stale labels, last-updated times, disabled action explanations, and reconnect controls visually close to affected content.", "Announce offline, reconnected, queued, sync failed, and conflict-needed transitions through appropriate status messaging.", "Test airplane mode, flaky network, captive portal, server timeout, refresh while offline, app restart, background return, duplicate queued actions, and multi-device conflicts." ], "commonMisuses": [ "Showing only a browser-style offline page when useful cached or local content exists.", "Using a spinner forever during connection loss.", "Claiming a server save or submit succeeded while the work is only local.", "Disabling every control instead of only online-only actions.", "Hiding stale-data timestamps or presenting cached data as current.", "Clearing queued changes after reconnect failure.", "Treating offline, server outage, permission failure, and validation error as the same message." ], "critiqueQuestions": [ "What can users still do without network, and what must wait?", "Which content is cached, how old is it, and does freshness matter for this decision?", "Where exactly are local edits stored, and how will users know they are not yet synced?", "What does Retry connection test: device network, server reachability, or a specific API?", "What happens after reconnect if queued work fails validation or conflicts with newer server data?", "Can users recover local work by retrying, cancelling, exporting, or contacting support?" ], "relatedPatterns": [ "error-state", "loading-spinner", "progress-bar", "toast-notification", "alert", "draft-state" ], "comparisons": [ "offline-state-vs-error-state-vs-loading-spinner-vs-progress-bar" ], "sourceIds": [ "material-design-offline-states", "webdev-offline-ux-design-guidelines", "webdev-offline-fallback-page", "mdn-pwa-offline-background-operation" ] }, { "id": "onboarding", "completionStatus": "complete", "name": "Onboarding", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "First-run or new-feature orientation that leads to first value", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "New users, returning users after major changes, or users entering a novel workflow may not know how to reach first value, but broad tours, forced setup, and feature promotion can delay the task they came to complete.", "solution": "Provide a short, optional where possible, context-aware onboarding path that explains value, collects only necessary setup, teaches through real actions, preserves progress, and leaves users in the product with a useful next step or configured starting point.", "uiGuidance": [ "Render onboarding as a short purposeful path with a visible benefit, current step, skip or later path when safe, persistent resume point, and the next product action users can take immediately after finishing.", "Keep onboarding surfaces close to the real product context: use welcome panels, contextual spotlights, setup cards, checklists, sample-data previews, or focused steps rather than long abstract slide decks." ], "uxGuidance": [ "Use onboarding only when users need orientation, minimal setup, personalization, or instruction before the normal interface can deliver value, and remove steps that merely market features or repeat what the UI already explains.", "Design the flow around first value: collect only necessary setup data, let users skip optional teaching, preserve progress, support return later, and land users on a configured workspace, sample content, or concrete next action." ], "uiExamples": { "good": [ "A project-management app asks for role and team size, creates a sample board, highlights the first Add task action, and lets users skip the tour while keeping a setup checklist available.", "A redesign introduces a moved Reports filter through one contextual spotlight with Show me later and Learn in context controls." ], "bad": [ "A first launch shows six promotional slides about every feature, requires Next on each slide, and lands on an empty dashboard.", "A new feature tour blocks an urgent invoice workflow and cannot be reopened after the user dismisses it." ] }, "uxExamples": { "good": [ "A new admin selects Invite teammates as their goal, imports two sample users, sees progress saved, skips notification setup, and arrives on the team page with the invite action focused.", "A returning user sees a short contextual note about a redesigned navigation area only after opening the affected page, then can dismiss or reopen it from Help." ], "bad": [ "A user is forced to configure integrations, notifications, billing, and profile details before they know whether the product solves their task.", "A user completes a polished onboarding tour but cannot remember where the shown feature lives because the tour was detached from the actual screen." ] }, "problemContext": [ "The product, feature, role, account, workspace, or workflow is new enough that users need orientation before the regular interface is effective.", "A small amount of setup, personalization, import, permission, or preference data can make the product immediately more useful.", "The first meaningful action is not obvious from the empty product surface alone.", "Existing users may need migration or redesign orientation without being blocked from urgent work.", "The team can measure whether onboarding improves activation, first task completion, setup success, or feature adoption." ], "selectionRules": [ "Choose onboarding when users need a first-run or new-feature path to understand value, configure essentials, or complete the first meaningful action.", "Use empty state when the only problem is a no-content area that needs cause and next action.", "Use wizard when the user is performing a bounded dependent setup with validation, review, and finish.", "Use progressive disclosure when the user needs optional detail inside an existing task rather than a separate first-run flow.", "Use carousel only when users browse peer content slides; do not disguise onboarding as a carousel unless each step supports immediate setup or action.", "Use account creation, sign-in, permission request, payment collection, or profile setup patterns when those tasks are the primary requirement.", "Skip separate onboarding when the interface can teach itself through labels, defaults, examples, and contextual empty states.", "Make onboarding skippable or resumable unless a step is required for legal, safety, identity, or technical reasons.", "Trigger feature onboarding in context when the feature becomes actionable, not at first launch for every user." ], "requiredStates": [ "First-run welcome state with benefit-focused copy and one clear next action.", "Optional skip, later, or resume state for non-required onboarding.", "Minimal setup or personalization state that explains why each answer is needed.", "Contextual teaching state attached to a real feature or empty workspace.", "Progress saved state so users can leave and continue later.", "Completion state that lands on a configured workspace, sample object, checklist, or first task.", "Reopen or help state for users who skipped, forgot, or need the guidance later.", "Returning-user new-feature state that avoids interrupting unrelated urgent work." ], "interactionContract": [ "The flow states its user benefit before asking for setup information.", "Every step either reduces setup friction, configures the product, demonstrates a real action, or routes users to a next step they can do now.", "Optional teaching can be skipped, resumed, and reopened without losing required setup progress.", "Required steps explain why they are required and what remains unavailable until they are complete.", "Onboarding progress is stored separately from permanent product data until the user commits or finishes the relevant setup.", "The completion transition lands users in the real interface with any created sample content, selected goal, checklist, or action focus intact.", "New-feature onboarding appears in or near the affected feature and does not block unrelated workflows." ], "implementationChecklist": [ "Define the activation outcome, first meaningful action, required setup fields, optional teaching, and success metric before designing screens.", "Remove promotional slides that do not help the user act inside the product.", "Use existing profile, organization, device, or account data instead of asking users to repeat it.", "Provide skip, later, and resume controls where policy and functionality allow.", "Show progress only when it reflects real setup or teaching steps users can understand.", "Keep copy short, benefit-focused, and tied to the next real product action.", "Persist partial setup and make the return path visible in the app shell, help menu, or checklist.", "Test first-run, returning-user, skipped, resumed, mobile, slow network, screen reader, reduced motion, and translated-label states.", "Measure whether onboarding improves first task completion rather than only counting views or completions." ], "commonMisuses": [ "Forcing all users through a feature tour before they can do useful work.", "Using onboarding to compensate for unclear navigation, labels, or empty states.", "Asking for role, team, payment, permissions, and notifications before showing value.", "Ending onboarding on a blank workspace with no action, example, or checklist.", "Making skipped onboarding impossible to reopen later.", "Using a carousel of marketing slides as if it were product setup.", "Interrupting existing users with redesign notes while they are trying to finish unrelated work." ], "critiqueQuestions": [ "What first meaningful action does this onboarding help users complete?", "Which steps are required for the product to work, and which are optional teaching?", "Can users skip or resume without losing setup progress?", "Does the flow land users in a configured product state rather than a blank surface?", "Would empty state, wizard, progressive disclosure, contextual help, or account setup be more accurate?", "How will we know the onboarding improved activation or task success?" ], "relatedPatterns": [ "empty-state", "wizard", "progressive-disclosure", "carousel", "prompt-suggestions" ], "comparisons": [ "onboarding-vs-empty-state-vs-wizard-vs-progressive-disclosure" ], "sourceIds": [ "apple-hig-onboarding", "fluent-onboarding-guidance", "material-design-onboarding", "nng-mobile-app-onboarding", "nng-onboarding-tutorials-contextual-help", "atlassian-onboarding-spotlight" ] }, { "id": "page-not-found-page", "completionStatus": "complete", "name": "Page not found page", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Missing-route recovery page", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users arrive at a URL the product cannot resolve and need to understand whether they mistyped an address, followed a broken or removed link, used an expired deep link, or reached a private resource whose existence cannot be disclosed.", "solution": "Show a clear page not found page that keeps orientation, states the page cannot be found, avoids blame and technical jargon, provides useful recovery routes, preserves privacy for protected resources, and records the missing URL as a 404 for repair.", "uiGuidance": [ "Render a full page with site or service identity, a page title and H1 that state the page was not found, concise likely causes, and recovery routes such as search, start page, account dashboard, contact, or report-broken-link.", "Keep standard header and footer navigation when it helps orientation, but avoid breadcrumbs or path trails that imply the missing page has a valid hierarchy." ], "uxGuidance": [ "Use a page not found page when the service is reachable but the requested URL, public page, resource, or deep link cannot be resolved.", "Help users recover without blame: let them check a typed or pasted address, search the service, return to a stable start or dashboard, report a broken link, or continue a current task when a deep link expired." ], "uiExamples": { "good": [ "A benefits service 404 page says Page not found, shows the requested path only if safe, offers Search benefits, Start a new application, Report this link, and Contact support.", "An expired signed-in return link says the page cannot be found and routes the user to their dashboard where current applications are listed.", "A sensitive record URL uses neutral not-found copy and does not reveal the private record title, owner, or whether the record exists." ], "bad": [ "A bare 404 code with a single Home button.", "An automatic homepage redirect that hides the broken URL and leaves users unsure what happened.", "A private report not-found page that displays the report title and owner to a user who should not know the report exists." ] }, "uxExamples": { "good": [ "A user who mistyped a web address sees clear check-the-address advice and can search the service immediately.", "A user follows a removed public help article and is sent to the replacement topic plus a report-broken-link route.", "A user returns from a notification with an expired deep link and can continue from the account dashboard instead of retrying the old URL." ], "bad": [ "Users are sent to the homepage with no explanation and assume their task was lost.", "A missing page is described as a service outage even though the rest of the service works.", "Analytics cannot identify broken links because the not-found page returns a successful status." ] }, "problemContext": [ "Users may arrive from bookmarks, search results, letters, email links, notifications, copied addresses, external referrals, or stale in-product links.", "The missing route may be a public content page, service step, deleted object, expired signed link, renamed resource, or protected object that must not disclose existence.", "The service itself may be healthy, so outage, spinner, or local component error treatment would misrepresent the condition.", "The organization needs operational evidence to find broken links, redirect removed pages, retire stale communications, and improve search recovery." ], "selectionRules": [ "Choose page not found page when the requested route, page, file, object URL, or deep link does not resolve to a valid destination.", "Use typed or pasted address guidance when users may have entered an incorrect or incomplete URL.", "Use moved or removed page guidance when the product knows the old page has a replacement, archive, topic page, or support route.", "Use signed-in dashboard recovery when a deep link expired or an account-scoped task moved to another current state.", "Use neutral no-disclosure copy for protected resources when the product must not reveal whether a private object exists.", "Provide search only when it is available and likely to recover the missing content; otherwise route to a start page, dashboard, sitemap, contact page, or support queue.", "Offer report-broken-link or contact paths when broken internal links, letters, forms, or external references may need correction.", "Use service unavailable page when the valid service route exists but cannot currently handle requests.", "Use error state when a valid page or section failed after loading enough context for in-place recovery.", "Use empty state when the requested page is valid and loaded successfully but the resulting collection contains no objects." ], "requiredStates": [ "Unknown route from typed or pasted URL.", "Broken in-product link.", "Removed public page with a replacement or closest topic route.", "Expired deep link that routes signed-in users to a dashboard or current task list.", "Private or policy-masked resource that uses no-disclosure copy.", "Search recovery state with query entry and useful suggestions.", "Report broken link or contact support state.", "Popular or common task links state for broad public pages.", "Localized or service-scoped not-found page.", "Logged 404 state with missing path, referrer, and safe diagnostic identifier." ], "interactionContract": [ "The page loads as a stable destination instead of redirecting users without explanation.", "The page title, H1, visible copy, HTTP status, and analytics all agree that the requested resource was not found.", "Recovery links lead to valid destinations and are labeled by destination rather than vague escape words.", "Search, if present, accepts keyboard input, submits reliably, and preserves the user's query.", "Private-resource variants avoid disclosing names, owners, counts, or IDs beyond what the user's role is allowed to know.", "The missing path and referrer are captured for diagnostics without exposing sensitive values in the visible UI." ], "implementationChecklist": [ "Configure the route, edge, or server to return a real 404 status for unresolved public URLs.", "Use a page title that includes Page not found and the service or site name.", "Write concise no-blame copy that explains likely address, copied-link, moved-page, or removed-page causes.", "Add search, start-page, dashboard, contact, report-broken-link, replacement-page, or popular-task links according to the product context.", "Keep header and footer navigation when they help orientation, but remove breadcrumbs that imply a valid parent trail for the missing page.", "Avoid technical jargon, humor that obscures the condition, warning colors as the only signal, and raw routing errors.", "Track missing URL, referrer, account state, locale, and recovery link usage so teams can repair broken links and redirects.", "Test external links, bookmarks, old route redirects, unauthenticated and authenticated deep links, protected resources, screen readers, keyboard navigation, zoom, and mobile widths." ], "commonMisuses": [ "Returning a successful status with page-not-found copy.", "Automatically redirecting to the homepage without explaining that the requested page was not found.", "Using page not found for a service outage, form validation problem, submission failure, loading delay, or empty collection.", "Showing only a code, stack trace, route matcher name, or framework error.", "Providing no search, start, dashboard, contact, replacement, or report-broken-link route.", "Revealing private object names or owners in a no-disclosure context.", "Leaving old letters, emails, help pages, and in-product links pointed at missing URLs." ], "critiqueQuestions": [ "Can users tell that the URL did not resolve while the service may still be reachable?", "Does the page give recovery paths that match how this user arrived?", "Is the missing path safe to show, or would it disclose a protected object?", "Are broken links and recovery actions measurable for repair?", "Would this situation be more accurately handled by service unavailable page, error state, empty state, permission denied state, or redirect?" ], "relatedPatterns": [ "service-unavailable-page", "error-state", "empty-state", "permission-denied-state", "global-navigation", "service-navigation", "basic-search", "search-suggestions", "site-alert" ], "comparisons": [ "page-not-found-page-vs-service-unavailable-page-vs-error-state-vs-empty-state" ], "sourceIds": [ "govuk-page-not-found-pages", "mdn-http-404-not-found", "cms-404-page-guidance", "epa-page-not-found-standard" ] }, { "id": "pagination", "completionStatus": "complete", "name": "Pagination", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Paged navigation control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to move through a long ordered collection without loading or scanning everything at once.", "solution": "Split the collection into stable pages with current page, previous, next, and reachable page controls.", "uiGuidance": [ "Render a labeled pagination nav near the affected results with current page, previous, next, nearby pages, optional first/last or ellipsis, and clear disabled edge states.", "Show result range, total count, and preserved query/filter/sort context so users understand what slice they are viewing." ], "uxGuidance": [ "Help users move through an ordered result set with a stable sense of position, progress, and returnability.", "Preserve query, filters, sort, page size, and focus context while changing pages; recover clearly from out-of-range pages." ], "uiExamples": { "good": [ "Current page, previous/next, disabled edges, page numbers, result range, and total count are visually clear.", "Controls stay stable while loading and remain near the results they paginate." ], "bad": [ "Tiny numbers with no current state.", "Pagination jumps around as pages load or separates controls from the result list." ] }, "uxExamples": { "good": [ "Users move through pages while query, filters, and sort persist.", "Current position is clear enough to resume, share, or recover after changing filters." ], "bad": [ "Changing page resets filters.", "Using pagination where users need side-by-side comparison across pages or stable footer access is required." ] }, "problemContext": [ "The collection is too large for one screen or one request.", "Users need a sense of position in a result set.", "Users may need to keep the same query, filters, sort, or page size while moving through results." ], "selectionRules": [ "Choose pagination when result order, bounded position, and resumability matter.", "Show current page, previous, next, first/last or nearby page controls, and disabled or hidden edge behavior clearly.", "Preserve query, filters, sort, and page size while moving between pages.", "Use filtering or search first when users are trying to find a specific item rather than browse positionally.", "Use load more or infinite scroll only when users do not need stable page position, footer access, or shareable page state." ], "requiredStates": [ "First page with disabled previous control.", "Middle page with previous and next available.", "Last page with disabled next control.", "Loading state after requesting another page.", "Current page state exposed with aria-current.", "Out-of-range or empty page recovery after filters change." ], "interactionContract": [ "Changing page updates the collection while preserving the user's query or filters.", "The current page is exposed visually and programmatically.", "Users can move by keyboard without losing context.", "Previous and next move one page relative to the current page and become unavailable at collection edges.", "Result count or range communicates what slice of the collection is visible." ], "implementationChecklist": [ "Persist filters and sort while paging.", "Label previous, next, and numeric page controls.", "Handle empty or out-of-range pages.", "Avoid shifting page controls while content loads.", "Use aria-current=\"page\" on exactly one current page control in a pagination set.", "Keep pagination visually near the content it controls." ], "commonMisuses": [ "Using pagination for a tiny collection.", "Resetting filters when moving pages.", "Hiding the current page or total position.", "Using page numbers for unrelated topics or sibling sections.", "Making previous or next appear available when there is no page in that direction." ], "critiqueQuestions": [ "Does paging help users orient in the collection, or would search and filters solve the task better?", "Can users tell which results they are seeing and whether their filters persisted?" ], "relatedPatterns": [ "tabs", "faceted-search" ], "comparisons": [ "tabs-vs-segmented-control-vs-pagination" ], "sourceIds": [ "govuk-pagination-component", "uswds-pagination-component", "carbon-pagination-component", "mdn-aria-current" ] }, { "id": "pagination-without-current-page", "completionStatus": "complete", "name": "Pagination without current page", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Missing pagination position anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users are given pagination controls but cannot identify the current page or result slice, so page numbers, previous/next actions, and browser history become ambiguous.", "solution": "Flag the missing-current-page treatment and replace it with pagination that exposes one current page, matching result range, edge states, URL/state alignment, and recovery when the requested page is no longer valid.", "uiGuidance": [ "Treat pagination without a visible and programmatic current page as an anti-pattern whenever users are moving through ordered pages of one result set.", "Show exactly one current page in each pagination set, expose it with text and aria-current=\"page\" when page controls are links or buttons, and keep previous, next, result range, total count, and edge states consistent with that current page." ], "uxGuidance": [ "Use this anti-pattern during review when users cannot tell whether page 3 is selected, loading, unavailable, or merely adjacent to the current page.", "Design pagination as orientation, not just movement: after filter, sort, page-size, browser back/forward, reload, or async updates, users should still know which slice of the collection they are viewing and what previous/next will do." ], "uiExamples": { "good": [ "A results list says Showing 21-30 of 118 and the pagination marks Page 3 as Current page with aria-current=\"page\".", "Previous is unavailable on page 1, Next is unavailable on the last page, and the page range updates with the highlighted current page.", "When filters reduce the result count, the page indicator returns to Page 1 of 4 and the result range matches the visible records." ], "bad": [ "Page links 1 2 3 4 are identical, so users cannot tell which page they are on.", "The URL says page=4, the result range says 31-40, and no pagination item is marked current.", "The current page is shown only by a subtle color difference with no text, aria-current, or result-range confirmation." ] }, "uxExamples": { "good": [ "A reviewer returns to search results and sees Page 4, 31-40 of 96, query appeal, and sort Newest still aligned.", "A keyboard user tabs through pagination and hears which page is current and which previous/next controls are unavailable.", "After changing page size, the app explains that it returned to Page 1 and announces the new range." ], "bad": [ "A user clicks Next twice and cannot tell whether the second click loaded, failed, or left them on the same page.", "Screen reader output lists several page numbers but none is announced as the current page.", "Filtering leaves users on an out-of-range empty page with no current page or recovery message." ] }, "problemContext": [ "The interface splits a table, result list, collection, audit log, inbox, resource list, catalog, or search result into multiple pages.", "Users rely on page position to resume work, compare ranges, share URLs, move with previous/next, or confirm that filters and sort persisted.", "The UI may have identical page chips, previous/next-only controls, ellipses, cursor pagination, async loading, page-size changes, filters, sort, or browser back/forward.", "Current-page state may be missing visually, missing from accessibility semantics, out of sync with the result range, or lost after loading." ], "selectionRules": [ "Flag this anti-pattern when a pagination set has no visible current page, no aria-current or equivalent current-state text, or more than one item that appears current.", "Flag it when previous/next controls exist but the page number, result range, total pages, URL, and disabled edge states do not identify where the user is.", "Use standard pagination when users are traversing ordered slices of one collection and need current page, previous, next, result range, total count, and edge states.", "Use breadcrumbs when the issue is hierarchy orientation, not collection page position.", "Use step navigation when the numbers represent task progress through a known workflow, not result pages.", "Use table, list view, or resource-list guidance for row anatomy and collection controls, but keep pagination current-page state near the collection it controls.", "Use feed or load-more behavior only when exact page position is not part of the task; if position matters, pagination needs a current state.", "When filters, sort, search, or page-size changes alter the result set, either preserve a still-valid current page or visibly move to a valid page and announce why.", "For cursor pagination, expose a meaningful current range or position such as Showing 41-60 and disable or hide invalid previous/next actions." ], "requiredStates": [ "Default middle-page state with exactly one visible current page and matching result range.", "First page state with current page 1 and previous unavailable.", "Last page state with current last page and next unavailable.", "Loading state that keeps the old current page understandable until the new page is committed.", "Filter or sort change state that returns to a valid page and announces the new current page.", "Out-of-range recovery state when a bookmarked or stale page no longer exists.", "Previous/next-only or cursor pagination state with current result range instead of ambiguous numbered links.", "Bad state showing identical page numbers, multiple current pages, stale URL/range mismatch, and missing aria-current." ], "interactionContract": [ "Each pagination region has one owner collection and one current page or current range.", "Exactly one page item is marked current in a numbered pagination set.", "The current page is conveyed by text, visual state, and programmatic state rather than color alone.", "Previous and next move relative to the current page and are unavailable at collection edges.", "Result range, total count, current page, URL or route state, and visible records stay synchronized.", "Page changes preserve query, filters, sort, page size, selection policy, and focus context unless the UI explicitly states a reset.", "Loading, errors, and out-of-range recovery do not leave users guessing whether the current page changed.", "Keyboard and screen reader users can identify the current page before activating another page control." ], "implementationChecklist": [ "Render pagination inside a labelled nav or equivalent region near the controlled results.", "Apply aria-current=\"page\" to exactly one current page link or button when numbered pages are rendered.", "Include visible current-page wording or an accessible label such as Page 3, current page.", "Show the result range and total count near the pagination or collection summary.", "Disable, hide, or relabel Previous and Next at the first and last page without making unavailable actions look active.", "Keep page state, URL parameters, server cursor, result range, and visible records from drifting apart.", "Handle filter, sort, search, and page-size changes by moving to a valid current page and announcing the change.", "Test async loading, browser back/forward, reload, narrow layouts, ellipses, page-size selectors, and cursor-only pagination.", "Ensure current state is not indicated only by color, hover, focus ring, or disabled styling." ], "commonMisuses": [ "Showing page numbers as identical chips with no selected state.", "Relying on the browser URL as the only current-page indicator.", "Marking both a page number and Next as current.", "Leaving aria-current on a stale page after async navigation.", "Using disabled styling on the current page without accessible current-page text.", "Showing result range 41-50 while page 2 is highlighted.", "Hiding page numbers on mobile without replacing them with Page x of y or a current range.", "Treating cursor pagination as exempt from current-position feedback." ], "critiqueQuestions": [ "Which page or result range is current right now?", "Can users identify the current page visually, by keyboard, and through assistive technology?", "Do result range, URL, visible records, and page controls agree?", "What happens to current-page state after loading, filtering, sorting, page-size changes, browser back, and reload?", "Are previous and next clearly relative to the current page and unavailable at the edges?", "Is this actually task progress, hierarchy navigation, or a feed rather than pagination?" ], "relatedPatterns": [ "pagination", "breadcrumbs", "step-navigation", "back-link", "table", "sort-controls", "filter-panel", "feed" ], "comparisons": [ "pagination-without-current-page-vs-pagination-vs-breadcrumbs-vs-step-navigation-vs-feed" ], "sourceIds": [ "govuk-pagination-component", "uswds-pagination-component", "carbon-pagination-component", "mdn-aria-current", "shopify-polaris-resource-list", "nng-infinite-scrolling-tips" ] }, { "id": "password-creation", "completionStatus": "complete", "name": "Password creation", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "New authentication secret selection flow", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Creating a password asks users to make a long-term authentication secret under policy pressure, so confusing rules, paste blocking, weak checklist meters, or unsafe reset practices can make accounts weaker while increasing abandonment and recovery burden.", "solution": "Support generated and pasted passwords, explain a small set of real acceptance rules, reject commonly used or compromised secrets with correction reasons, avoid arbitrary composition and rotation rules, and protect the accepted password like a secret throughout setup and reset.", "uiGuidance": [ "Render password creation as a labelled new-password field with visible policy guidance, generator and paste compatibility, show and hide control, field-level rejection reasons, and a confirmation state that never displays the accepted secret later.", "Keep the guidance focused on what actually affects acceptance: length, banned or breached value checks, service-specific terms, and password-manager compatibility rather than a decorative checklist of character classes." ], "uxGuidance": [ "Use password creation when a user is choosing a new reusable secret during registration, password reset, first-time setup, or password change.", "Help users create a strong unique password by allowing generated values, paste, long passphrases, spaces, and printable characters, while rejecting common or compromised secrets with actionable reasons." ], "uiExamples": { "good": [ "A signup form labels the field New password, uses autocomplete new-password, allows password-manager generation, says Use at least 15 characters or a generated password, and rejects Password123 because it is commonly used.", "A password reset page separates Current password from New password, shows one new-password field with Show and Hide, accepts a long passphrase with spaces, and explains when the chosen value appears in breach data." ], "bad": [ "A form requires one uppercase letter, one lowercase letter, one number, one symbol, no spaces, and a 12-character maximum while still accepting Summer2026!", "A reset form asks for a password reminder question and then emails the new password to the user." ] }, "uxExamples": { "good": [ "A user accepts a password-manager suggestion, pastes it into the field, sees that it meets length and is not in the blocked list, and continues without retyping it.", "A user tries Password123, sees This password is commonly used, then switches to a long passphrase and the form accepts it without demanding symbols." ], "bad": [ "A user enters a strong generated password but the site silently cuts it at 16 characters, so the saved password does not match the password manager.", "A user is forced to rotate a password every month and chooses predictable variations that are easier to guess." ] }, "problemContext": [ "The user is registering, setting an initial password, resetting a forgotten password, changing a compromised password, or replacing a password after an account-security event.", "Users may use a password manager, browser-generated password, passphrase, copied value, mobile keyboard, or assistive technology.", "The system may need different rules for single-factor and MFA-backed accounts, but those rules must be clear wherever users create and later enter the password.", "Common-password, breached-password, service-name, username-derived, or organization-specific banned checks can reject a value that otherwise looks long enough.", "Password creation often sits near account recovery, MFA setup, passwordless options, and notification workflows, but it must not expose the new secret through reminders, email, logs, or review pages." ], "selectionRules": [ "Choose password creation when the user must choose or replace a reusable password, passphrase, or memorized secret.", "Use autocomplete new-password for the new password field and current-password only for the old password field in a change flow.", "Encourage password-manager generation and allow paste, autofill, long values, spaces, and printable characters.", "State the minimum length and any true technical restrictions before the user starts typing.", "Do not set a short maximum length; if any upper bound exists, validate it with an error rather than silent truncation.", "Do not require arbitrary mixtures of uppercase, lowercase, numbers, and symbols as a substitute for real strength checks.", "Reject commonly used, expected, breached, service-name, username-derived, or organization-specific weak values with a correction reason.", "Use a strength meter only if it models guessability or known weak patterns; do not use a checklist that can be satisfied by predictable substitutions.", "Do not require routine password changes unless there is evidence of compromise or an authenticator change that requires rotation.", "Do not ask for password reminders, password reset questions, or email delivery of the password.", "If extra protection is needed, offer MFA or passwordless setup rather than piling on password restrictions.", "Never show the accepted password on review, confirmation, receipts, support tools, analytics, screenshots, or account summaries." ], "requiredStates": [ "Initial new-password state with purpose, autocomplete new-password, minimum length, paste support, show and hide control, and no character-class checklist.", "Generated password state where a password-manager value is accepted without blocking paste or truncation.", "Visible password state with matching Hide control and no spellcheck or autocapitalization.", "Too-short state with the entered value preserved and a field-level length message.", "Common password rejected state with a reason such as This password is commonly used.", "Breached password rejected state that explains the value has appeared in exposed-password data without logging the raw value.", "Service-name or username-derived rejected state with a reason that does not reveal the full banned list.", "Strong passphrase accepted state with spaces allowed and no symbol requirement.", "Submitted state where the password is no longer visible and the next step describes account security or MFA setup.", "Password reset state that uses a time-limited link or code and never sends the new password by email." ], "interactionContract": [ "Typing, paste, autofill, password-manager generation, deletion, and selection follow native input behavior.", "Show and Hide change only visibility and do not change the value, cursor, validation status, or autocomplete purpose.", "Validation reasons update after typing, paste, blur, or submit without exposing the raw password in logs or analytics.", "Rejected values remain editable long enough for correction but are not displayed elsewhere.", "Accepted passwords are submitted through protected transport and never appear on review pages or confirmation screens.", "If current password is required in a change flow, it is separate from new password and uses current-password autocomplete.", "Password creation can hand off to MFA, passkey, recovery, or account notification steps without weakening the password rules." ], "implementationChecklist": [ "Define minimum length, maximum supported length, accepted character set, Unicode handling, blocklist source, breached-password check, service-specific banned terms, rate limit, storage hashing, and reset notification policy before designing the UI.", "Use native password inputs with visible labels, autocomplete new-password, spellcheck false, autocapitalize none or off, aria-describedby for guidance and errors, and a show and hide button.", "Allow paste and password-manager generation; test generated passwords longer than 64 characters, spaces, punctuation, Unicode, mobile keyboards, browser suggestions, and password-manager overlays.", "Reject known weak values through common, breached, service-name, username-derived, and organization-specific checks with concise reasons and recovery advice.", "Avoid character-class checklists, short maximum lengths, silent truncation, periodic rotation, reset questions, reminders, emailed passwords, and storage of raw password values.", "Ensure backend submission uses protected transport, rate-limited change and reset attempts, salted password hashing with suitable work factors, and account notifications after reset or security-sensitive changes." ], "commonMisuses": [ "Using uppercase, lowercase, number, and symbol checklists as the main security signal.", "Blocking password-manager paste or generated passwords.", "Silently truncating long generated passwords.", "Rejecting spaces or Unicode without a documented technical reason.", "Accepting Password123 because it satisfies character classes.", "Forcing routine password rotation without compromise evidence.", "Asking for password reset questions or reminders.", "Sending the password by email after reset.", "Displaying the new password on review, logs, analytics, support tools, screenshots, or account summaries." ], "critiqueQuestions": [ "Is the user creating a new reusable secret, or entering an existing one?", "Does the field use autocomplete new-password and allow password-manager generation?", "Can users paste long generated passwords without truncation?", "Which common, breached, service-name, username-derived, or organization-specific values are blocked?", "Does rejection explain what to fix without publishing the banned list or encouraging trivial substitutions?", "Are character-class rules, periodic rotation, reminders, reset questions, and emailed passwords avoided?", "Where could the raw new password leak after submit?" ], "relatedPatterns": [ "password-input", "inline-validation", "error-summary", "text-input" ], "comparisons": [ "password-creation-vs-password-input-vs-inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-passwords-pattern", "nist-sp-800-63b-passwords", "owasp-authentication-password-strength", "microsoft-entra-password-protection", "dropbox-zxcvbn-password-strength", "hibp-pwned-passwords", "mdn-html-autocomplete-password" ] }, { "id": "password-input", "completionStatus": "complete", "name": "Password input", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Authentication secret entry control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Passwords are secrets that users often enter under observation risk, through password managers, and in high-stakes authentication flows, so ordinary text entry, paste blocking, revealing errors, or weak visibility controls can expose credentials or block safe behavior.", "solution": "Use a proper password field that hides the secret by default, supports password managers and paste, offers controlled show and hide, avoids spellcheck and autocapitalization, handles errors without account enumeration, clears failed secrets, and submits through the protected authentication flow.", "uiGuidance": [ "Render password entry as a labelled password field that is hidden by default, uses the correct autocomplete purpose, offers a clear show and hide control, disables spellcheck and automatic capitalization, and keeps helper and error text connected to the input.", "When a password becomes visible, label the state clearly, announce the visibility change where needed, and return the field to password type before submission or after a failed authentication." ], "uxGuidance": [ "Use password input when a user enters an existing secret to sign in, reauthenticate, unlock a protected action, or confirm account ownership.", "Support password managers, paste, autofill, long values, and printable characters, while handling failed login attempts without revealing whether the password alone was wrong." ], "uiExamples": { "good": [ "A sign-in form has Email and Password fields, the password field uses autocomplete current-password, a Show button, no spellcheck, and an account-details error after failed login.", "A reauthentication dialog asks for Current password, lets the user show it temporarily, accepts a pasted manager value, and clears the field after an incorrect attempt." ], "bad": [ "A login form uses a normal text field named Password and leaves the secret visible on screen.", "A page disables paste, adds a custom keyboard trap, and says Password incorrect while keeping the typed password visible." ] }, "uxExamples": { "good": [ "A user pastes a generated password from a password manager, toggles Show to inspect one character, hides it again, and signs in without the value appearing later in review or history.", "A user mistypes credentials, receives Check your email address and password, and the password field is cleared so the secret is not left visible or reusable by another person." ], "bad": [ "A user cannot paste from a password manager and shortens the password to something easier to type.", "A failed login page says the password is wrong, confirming that the username exists." ] }, "problemContext": [ "The user is signing in, reauthenticating before a sensitive action, confirming a current password before a change, entering a PIN-like memorized secret, or unlocking an account recovery step.", "Users may rely on browser autofill, password managers, generated passwords, copy and paste, hardware keyboards, mobile keyboards, or screen readers.", "The UI must balance shoulder-surfing risk with error recovery, especially when users need to inspect the value they typed.", "Authentication failures can leak whether an account exists if the product reports the username and password parts separately.", "Password entry connects to backend concerns such as protected transport, rate limiting, hashing, account lockout, recovery, MFA, and breach response even though the field itself only captures the secret." ], "selectionRules": [ "Choose password input when the value is a password, passphrase, PIN-like memorized secret, current password, reauthentication secret, or credential confirmation value.", "Use autocomplete current-password for existing password entry, new-password for choosing or changing a password, and one-time-code for short-lived codes.", "Hide password values by default and give users a clear show and hide control when the surrounding context allows it.", "Use distinct show and hide labels when multiple password inputs are on one page.", "Disable spellcheck and automatic capitalization for password fields, especially when the value can become visible.", "Allow paste, autofill, and password managers; do not trap keyboard focus or require character-by-character typing.", "Accept long passwords and printable characters unless a documented technical constraint exists, and explain any constraint consistently wherever users create or enter the password.", "After failed sign-in, clear the password field and show a combined account-details message rather than saying the password alone is wrong.", "Move focus to the password error or error summary after submit without leaving the secret visible.", "Return the input type to password before submitting if the user had chosen to show it.", "Do not use password input for non-secret identifiers, email addresses, account labels, security answers, one-time recovery codes, or masked formatting of ordinary text.", "Do not show the password on review pages, receipts, logs, analytics, screenshots, or support tools." ], "requiredStates": [ "Initial hidden state with label, autocomplete purpose, spellcheck off, autocapitalization off, and show control.", "Focused hidden state that preserves native text editing and password-manager affordances.", "Visible state after the user chooses Show, with matching Hide control and visibility announcement.", "Pasted password-manager value state with the value accepted and not truncated.", "Caps Lock or keyboard-warning state that helps the user without changing the secret.", "Missing password error state connected to the field.", "Failed sign-in state with combined email and password error, cleared password value, and recovery link.", "Rate-limited or too many attempts state with next-step guidance and no secret disclosure.", "Successful submit state where the field has returned to type password and the value is not shown in review.", "Browser Back or session timeout state that does not restore a visible password." ], "interactionContract": [ "Typing, paste, selection, deletion, undo, and password-manager autofill work through native input behavior.", "The Show action changes only visibility, not the password value, cursor position, autocomplete purpose, or validation state.", "The Hide action obscures the secret immediately and updates the control label.", "Submitting while visible changes the field back to password type before the request leaves the page.", "A failed authentication clears the password field and does not reveal which credential part was wrong.", "Errors are reachable by keyboard and screen reader without reading the password value aloud.", "The field never stores the raw password in local storage, visible review, analytics events, or reusable page state." ], "implementationChecklist": [ "Use a native input with type password, a visible label, autocomplete current-password for sign-in, spellcheck false, autocapitalize none or off, and aria-describedby for hints and errors.", "Implement Show and Hide as a real button with aria-controls, state-specific accessible labels, and a polite announcement if the visibility change needs to be announced.", "Allow paste, autofill, password-manager overlays, long values, spaces, and printable characters; do not use maxlength unless the user receives an explicit validation error instead of silent truncation.", "Use a combined credential failure message, clear the password after failed authentication, keep recovery links visible, and handle rate limiting without leaking account existence.", "Ensure the backend uses protected transport, rate limits attempts, and stores password verifiers as salted hashes with suitable work factors.", "Test password managers, browser autofill, paste, mobile keyboards, Caps Lock, show/hide, failed login, browser Back, session timeout, zoom, screen readers, high contrast, and multiple password inputs on one page." ], "commonMisuses": [ "Using type text for passwords.", "Blocking paste or password-manager autofill.", "Leaving the password visible after submit, error, or browser Back.", "Showing Password incorrect when the account identifier was valid.", "Adding spellcheck or autocapitalization to a visible password field.", "Using maxlength so pasted manager values are silently truncated.", "Requiring confirm password for an existing-password sign-in field.", "Displaying password values on review pages, logs, support screens, screenshots, or analytics events.", "Using password input for ordinary masked identifiers or non-secret text." ], "critiqueQuestions": [ "Is this value truly an authentication secret, or is it ordinary text being hidden?", "Does the field use current-password, new-password, or one-time-code according to the task?", "Can a user paste or autofill from a password manager without losing characters?", "What happens to the password value after failed login, browser Back, session timeout, and visible submit?", "Does the error message avoid revealing whether the account identifier or password was wrong?", "Are spellcheck, autocapitalization, logs, analytics, screenshots, and support tools prevented from capturing the secret?" ], "relatedPatterns": [ "text-input", "inline-validation", "error-summary", "review-before-submit" ], "comparisons": [ "password-input-vs-text-input-vs-inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-password-input-component", "nist-sp-800-63b-passwords", "mdn-input-password", "mdn-html-autocomplete-password", "owasp-authentication-password-managers" ] }, { "id": "password-reset", "completionStatus": "complete", "name": "Password reset", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Account recovery and reset-token lifecycle", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Password reset must restore access for legitimate users who cannot authenticate while preventing account enumeration, token theft, replay, weak recovery channels, uncontrolled session continuation, and confusing dead ends.", "solution": "Treat password reset as a recovery-token lifecycle: collect an identifier with neutral response, deliver a single-use expiring reset link or code through an enrolled channel, validate the reset session, hand off to secure new-password creation, clean up sessions and tokens, and notify the account after completion.", "uiGuidance": [ "Render password reset as a recovery journey with a neutral request form, reset delivery confirmation, token or code validation, expired and already-used link states, new-password handoff, session cleanup choices, and post-reset notification.", "Keep password reset separate from login outcome handling and password creation: reset proves recovery-channel control and creates a trusted reset session; password creation handles the new secret inside that session." ], "uxGuidance": [ "Use password reset when a user cannot authenticate with the existing password and needs a safe route back into the account without exposing whether the account exists.", "Help legitimate users recover by making the next step visible, preserving privacy with neutral copy, rate-limiting repeated requests, handling expired links cleanly, and explaining what happens to active sessions after the reset." ], "uiExamples": { "good": [ "A forgot-password page asks for email, then always shows If an account uses this email, we sent reset instructions, with resend timing and a support route.", "An expired reset link page explains the link can no longer be used and offers Request a new reset link without revealing whether the account exists." ], "bad": [ "The reset page says No account found for one email and Reset email sent for another.", "A reset link can be reused after the password changes and signs the user in automatically without a security notice." ] }, "uxExamples": { "good": [ "A user enters their email, sees a neutral delivery confirmation, opens a time-limited link, creates a new password, chooses to sign out other sessions, and receives a reset notification.", "A user opens an old reset link, sees that it expired, requests a fresh link, and continues without needing to re-enter unrelated profile data." ], "bad": [ "A user mistypes their email and the form confirms the account does not exist, exposing account registration status.", "A user changes the password but active stolen sessions remain valid and no account notification is sent." ] }, "problemContext": [ "The user has forgotten the password, lost access to the authenticator, reached a failed-login route, or received a security prompt to reset a compromised password.", "The product may know an email, username, phone number, recovery email, administrator channel, or identity-proofing route, but the UI must avoid confirming account existence to unauthenticated users.", "Reset delivery can fail because the identifier is mistyped, the user no longer controls the mailbox, messages are delayed, codes expire, links are already used, or rate limits are active.", "Reset links and codes are authentication artifacts that must be protected from replay, guessing, logs, referrers, screenshots, analytics, and cross-account use.", "After reset, active sessions, remembered devices, app passwords, API tokens, and security notifications may need explicit policy treatment." ], "selectionRules": [ "Choose password reset when an unauthenticated or partially authenticated user needs to regain account access by proving control of a recovery channel and setting a replacement password.", "Use login when the user is submitting a current password or authenticator and the issue is the result of that verification attempt.", "Use password creation for the new-password field and policy feedback after a reset link or code has already established a trusted reset session.", "Use sign in for the entry page that offers password, passkey, SSO, magic-link, account creation, and forgot-password routes.", "Use email address entry when collecting or editing a contact address; password reset must keep request confirmation neutral and should not reveal whether the address has an account.", "Return the same visible request confirmation for known, unknown, locked, disabled, and unverified accounts unless the user is already in a safer authenticated support route.", "Use server-side rate limiting, abuse monitoring, and consistent response timing for reset requests, resend actions, code attempts, and token validation.", "Make reset links and codes single-use, time-limited, sufficiently random, account-bound, request-bound, and invalid after password change or successful use.", "Handle expired, already-used, malformed, and mismatched reset artifacts as recoverable states with a request-new-link route rather than a dead end.", "After successful reset, clear reset artifacts, send a notification, and apply the product policy for revoking other sessions, remembered devices, app passwords, and recovery tokens." ], "requiredStates": [ "Request state with identifier input, neutral copy, rate-limit protection, and a route back to sign in.", "Submitted state with account-neutral delivery confirmation, resend timing, channel hint, and support route.", "Resend-limited state with wait time and no account-existence disclosure.", "Token or code entry state that validates a reset artifact without exposing it in URLs, logs, analytics, or referrers.", "Expired link or code state with request-new-link action.", "Already-used or revoked link state with request-new-link action and security explanation.", "Trusted reset-session state that hands off to password creation with new-password autocomplete and no old-password requirement.", "Password-reset success state that explains sign-in, session revocation, and account notification outcomes.", "Suspicious or support-required recovery state for high-risk accounts, inaccessible channels, or repeated abuse.", "Post-reset notification state sent through the account's registered contact route." ], "interactionContract": [ "Submitting an identifier always leads to the same visible confirmation, regardless of whether an account exists.", "The request form prevents duplicate submissions while pending but keeps status, resend, support, and sign-in routes understandable.", "Resend and code-entry attempts use server-backed wait times and attempt limits rather than client-only counters.", "Opening a reset link validates token freshness, account binding, request binding, and single-use status before showing the new-password form.", "Expired, already-used, revoked, or malformed artifacts never show raw token values and always offer a safe way to restart recovery.", "The new-password step inherits password creation rules, then clears reset artifacts and follows the session-revocation policy.", "Post-reset notification and audit records avoid exposing the new password, token, exact failure reason, or account-enumeration signals." ], "implementationChecklist": [ "Define eligible identifiers, enrolled recovery channels, delivery copy, token entropy, expiry window, single-use behavior, account binding, request binding, resend limits, code-attempt limits, and abuse-monitoring events with security owners.", "Design neutral request confirmation, delayed delivery expectations, spam-folder advice, resend timing, wrong-email correction, support route, and return-to-sign-in route without exposing account existence.", "Protect reset links and codes from leakage through logs, analytics, referrer headers, screenshots, browser history, support transcripts, URL previews, and third-party scripts.", "Map expired, already-used, revoked, malformed, mismatched, too-many-requests, inaccessible-channel, and high-risk-account states to visible recovery actions.", "Use the password creation pattern for new-password acceptance, blocklists, paste, show and hide, autocomplete new-password, and no emailed passwords.", "After success, invalidate reset artifacts, notify the account, apply session and device revocation policy, clear stale failure states, and route users to sign in or a verified session according to policy." ], "commonMisuses": [ "Confirming whether an email, username, phone number, or account exists.", "Using password reset questions, reminders, or emailed passwords as recovery.", "Allowing reset tokens to be reused, guessed, shared across accounts, or used after expiry.", "Displaying raw tokens or codes in logs, analytics, support tools, screenshots, or third-party referrers.", "Dropping expired or already-used links on a blank error page.", "Automatically signing the user in after reset when policy requires fresh login or session review.", "Leaving stolen sessions, remembered devices, app passwords, or API tokens active after a high-risk reset." ], "critiqueQuestions": [ "Does any request, delivery, resend, support, timing, error, status code, redirect, or notification path reveal account existence?", "How are token entropy, expiry, single-use behavior, account binding, request binding, and revocation verified?", "What happens when the user mistypes the identifier, cannot access the recovery channel, opens an expired link, or reuses an old link?", "Which active sessions, remembered devices, API tokens, app passwords, and recovery tokens survive a reset, and is that visible to the user?", "Where could the reset token, code, new password, or exact recovery failure reason leak?" ], "relatedPatterns": [ "login", "sign-in", "password-creation", "password-input", "email-address-entry", "account-creation" ], "comparisons": [ "password-reset-vs-login-vs-password-creation-vs-email-address-entry" ], "sourceIds": [ "owasp-forgot-password-cheat-sheet", "owasp-wstg-weak-password-reset", "govuk-passwords-pattern", "owasp-authentication-account-enumeration", "mdn-html-autocomplete-password", "nist-sp-800-63b-passwords" ] }, { "id": "payment-card-entry", "completionStatus": "complete", "name": "Payment card entry", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Secure card payment capture and verification form", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Card payment details are high-risk, easy to mistype, brand-specific, and regulated, so ordinary text fields or unsafe review screens can cause failed payments, fraud exposure, and card-data leakage.", "solution": "Collect card details through secure hosted or processor-owned fields, format and validate card-specific parts, support paste, autofill, wallets, authentication and decline recovery, tokenize before review, and show only masked card details once captured.", "uiGuidance": [ "Render card entry as a secure grouped checkout surface with processor-hosted or payment-element fields for card number, expiry, CVC or CID, billing postal code when required, clear labels, card brand feedback, field errors, wallet options, and a masked review summary.", "Use card-specific autocomplete tokens, input modes, readable grouping, brand marks, and stable helper text without making placeholders the only instruction or showing raw card details after tokenization." ], "uxGuidance": [ "Use payment card entry when a user needs to pay with a card or add a card-on-file payment method and the product can protect cardholder data through a payment processor or compliant card-data environment.", "Help users complete the payment by tolerating paste and autofill, detecting supported brands, explaining field and processor errors, offering wallet or authentication recovery paths, and showing only masked card details before charging." ], "uiExamples": { "good": [ "A checkout uses hosted fields for Card number, Expiry, CVC, and ZIP code; it detects Visa, accepts pasted spaces, validates expiry, tokenizes the card, and reviews Visa ending 4242 before charge.", "A card-on-file setup offers a wallet button and manual card fields; after tokenization the saved payment method shows brand, last four digits, expiry, and billing ZIP, never the CVC." ], "bad": [ "A page asks users to paste card number, expiry, CVC, and billing address into one notes field.", "A review page shows the full card number and CVC so the user can check them before payment." ] }, "uxExamples": { "good": [ "A user pastes 4242 4242 4242 4242, sees Visa detected, enters 12/30 and 123, tokenizes the card, and reviews Visa ending 4242 before paying.", "A user enters an American Express card and the form expects a four-digit CID while keeping the card number grouping and last-four review accurate." ], "bad": [ "A user enters an expired card and receives only Payment failed after submit with no field-level route back to expiry.", "A user cannot pay because the wallet button is the only available path and their browser does not support that wallet." ] }, "problemContext": [ "The user is paying by card, adding a card for later use, replacing a card-on-file method, or confirming a card payment at checkout.", "The form may need card number, cardholder name, expiry month and year, CVC or CID, billing ZIP or postal code, billing country, wallet selection, supported brand detection, and authentication outcomes.", "Users copy from physical cards, wallet apps, password managers, browser autofill, or bank apps and may paste spaces, hyphens, or cardholder names in different case.", "Card brands and payment processors can impose different number lengths, CVC lengths, supported brands, billing address needs, authentication requirements, and decline responses.", "Cardholder data and sensitive authentication data require careful scope control, redaction, logging discipline, and clear retention limits." ], "selectionRules": [ "Choose payment card entry when the task is to charge a card, verify a card, save a card payment method, or replace a card-on-file credential.", "Use hosted fields, payment elements, or processor-controlled components for PAN and CVC whenever the product does not intentionally own full card-data processing.", "Ask for card number, expiry, and CVC or CID only when needed by the payment flow, and ask for cardholder name or billing postal code when processor, fraud, AVS, tax, or receipt requirements need them.", "Support browser autofill with cc-name, cc-number, cc-exp or month and year tokens, cc-csc, cc-type when exposed, postal-code, transaction-currency, and transaction-amount as appropriate.", "Accept pasted card numbers with spaces or hyphens, then group them for readability without changing the canonical digits.", "Detect card brand and supported brand state from the entered number, but do not use a brand icon as the only validation feedback.", "Validate Luhn or processor-equivalent card number rules, supported length, expiry not in the past, CVC or CID length, and billing postal code before charging.", "Handle unsupported brand, invalid field, requires authentication, declined, processing, tokenized, saved, and succeeded states as distinct user-facing outcomes.", "Offer wallet, Link-style, or payment-request options where available, while keeping manual card entry or another accessible fallback.", "After tokenization or authorization, show only brand, last four digits, expiry when safe, billing postal code, and payment method status on review and receipts.", "Do not store, log, echo, email, chat, screenshot, or analytics-track full card numbers or CVC values.", "Do not treat a card-number mask, expiry date field, or review page as a substitute for secure card capture." ], "requiredStates": [ "Initial secure checkout state with amount, accepted card brands, wallet option, card number, expiry, CVC or CID, and billing postal code if required.", "Focused entry state with persistent labels, autocomplete purpose, and helper text that survives placeholder disappearance.", "Pasted card number state where spaces and hyphens are accepted and grouped for review.", "Brand detected state showing supported brand and expected CVC or CID length.", "Unsupported brand state with a clear alternate payment path.", "Invalid card number state with checksum or length correction guidance.", "Expired or impossible expiry state using month and year guidance rather than a full date picker.", "CVC or CID error state that respects three- and four-digit brand differences.", "Billing postal code required or invalid state where processor or country rules require it.", "Tokenized state where raw PAN and CVC are no longer displayed or retained by the app.", "Wallet selected state with network-token or processor-token summary and manual fallback still available.", "Requires authentication, declined, processing, succeeded, and retry states after payment submission.", "Masked review state with brand, last four digits, expiry, amount, billing context, and explicit charge action." ], "interactionContract": [ "Users can type, paste, autofill, delete, select, and correct card number, expiry, CVC, and postal code fields without losing entered values.", "Card number grouping helps readability but the canonical value is the digit sequence passed to the processor-hosted field or tokenization call.", "Brand feedback updates as enough digits are entered and changes CVC or CID expectations only when the brand is known.", "Submitting incomplete or invalid details keeps the entered safe-to-display values visible and focuses the first actionable error.", "Processor and wallet states are represented explicitly instead of hidden behind one catch-all payment error.", "Tokenized and saved-card states never redisplay the full PAN or CVC, and later screens cannot recover CVC from the UI.", "A final charge action uses masked card details and amount so users can detect the wrong card before payment." ], "implementationChecklist": [ "Select the payment processor, hosted-field or payment-element integration, supported brands, card-on-file rules, wallet support, authentication requirements, billing data, and PCI scope before designing the checkout.", "Use native labels, autocomplete tokens, inputmode values, aria-describedby hints, field-specific errors, and processor-provided accessible states for hosted iframes or embedded elements.", "Normalize paste and display grouping while preserving leading digits and never copying raw PAN or CVC into app-managed state beyond what the processor component requires.", "Implement brand detection, supported-brand decisions, expiry validation, CVC or CID length checks, postal-code requirements, and processor decline or authentication recovery as separate states.", "Redact card details from logs, analytics, replay tools, support transcripts, screenshots, error payloads, local storage, and review pages.", "Show masked review details and amount before charge, and keep receipts or saved methods limited to brand, last four digits, expiry, and billing details that are safe to display.", "Test paste, autofill, mobile keyboards, saved cards, wallets, unsupported brands, American Express CID, variable-length card numbers, expired card, declined card, required authentication, network failure, retry, browser Back, zoom, screen readers, and high contrast." ], "commonMisuses": [ "Using one multiline field for card number, expiry, CVC, and billing details.", "Collecting card details through ordinary app-owned inputs when hosted fields or a payment element are required by the intended compliance model.", "Assuming every card number has sixteen digits or every security code has three digits.", "Displaying or storing CVC after authorization.", "Showing a full card number on review, receipt, admin screens, or support tools.", "Blocking paste, autofill, or password-manager card filling.", "Using a wallet button as the only payment path.", "Reporting every card-entry, authentication, decline, or network issue as Payment failed.", "Saving card details before the user has seen a masked review and explicit save or charge action." ], "critiqueQuestions": [ "Which processor or hosted component owns PAN and CVC collection?", "Which card brands, number lengths, CVC lengths, billing data, wallets, and authentication paths are supported?", "Can users paste or autofill card details without breaking grouping, validation, or browser security controls?", "How does the UI distinguish invalid fields, unsupported brand, expired card, requires authentication, declined, processing, tokenized, and succeeded states?", "Where could raw PAN or CVC appear in logs, analytics, screenshots, support tools, browser storage, or review pages?", "What exact masked details are shown before charge so users can recognize the card without exposing sensitive data?" ], "relatedPatterns": [ "bank-details", "input-mask", "inline-validation", "error-summary", "review-before-submit", "text-input", "date-input" ], "comparisons": [ "payment-card-entry-vs-bank-details-vs-input-mask-vs-review-before-submit" ], "sourceIds": [ "stripe-payment-element-card-details", "adyen-card-component", "braintree-hosted-fields", "pci-dss-payment-card-data", "pci-card-data-storage-faq", "mdn-html-autocomplete-payment-card" ] }, { "id": "payment-collection", "completionStatus": "complete", "name": "Payment collection", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Payment request, authorization, and status lifecycle", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Payment journeys create high anxiety and real financial risk when users cannot see the amount and reference, do not understand provider handoffs, lose context after failure, or accidentally create duplicate charges while status is uncertain.", "solution": "Use a payment collection flow that anchors every attempt to a stable amount and reference, delegates sensitive credential capture to an appropriate provider surface, exposes lifecycle status, guards duplicate submission, preserves context through failure or redirects, and hands successful payments to a receipt or confirmation page.", "uiGuidance": [ "Render payment collection as a money-movement journey with amount due, reference, payer or service context, accepted methods, provider handoff, authorization or processing state, failure and cancel recovery, retry rules, receipt, and reconciliation status.", "Keep payment collection separate from checkout, payment-card entry, bank details, retry, and confirmation page: it owns the payment lifecycle and status, not full order finalization, raw card fields, account identifiers, a retry control alone, or the post-payment receipt." ], "uxGuidance": [ "Use payment collection when the user must pay a bill, fee, invoice, application charge, renewal, subscription, donation, deposit, or balance and the service must make the amount, reference, status, and next action unambiguous.", "Protect users from duplicate charges and uncertainty by preserving the payment reference, explaining provider handoffs, distinguishing pending, failed, canceled, requires action, and succeeded states, and giving safe retry or alternate-method paths." ], "uiExamples": { "good": [ "A permit-fee payment page shows Reference APP-2048, Amount due $84.00, accepted card and wallet methods, Continue to secure payment, and returns to a status page after provider authorization.", "An invoice payment failure keeps invoice INV-1482, amount, method, status, idempotency reference, Retry payment, and Try another method visible." ], "bad": [ "A page says Payment failed after redirect but hides whether the bank declined, the user canceled, the session expired, or money might still be pending.", "The payment button remains active during authorization and a double tap creates two payment attempts with different references." ] }, "uxExamples": { "good": [ "A user returns from bank authentication, sees the payment is processing, waits without retrying, and later sees the receipt once the provider reports success.", "A user receives a decline, keeps the same fee reference and application context, changes method, and retries without creating a duplicate charge." ], "bad": [ "A user closes a hosted payment page and returns to a blank form with no way to check whether the payment was canceled or still pending.", "A user pays the same invoice twice because retry generated a second reference instead of reusing a duplicate-safe payment attempt." ] }, "problemContext": [ "The user needs to pay a known fee, invoice, balance, tax, application charge, renewal, subscription, donation, deposit, or service request.", "The service may collect through card, wallet, bank redirect, payment link, hosted page, embedded payment element, saved method, manual reconciliation, or pay-later route.", "The payment lifecycle can include not started, method selection, requires details, requires action, processing, authorized, requires capture, succeeded, failed, canceled, expired, refunded, or disputed states.", "Users may leave for bank authentication or a hosted provider and then return by redirect, browser Back, webhook update, email link, or support route.", "Payment status affects whether the service can continue, issue a receipt, reserve inventory, submit an application, unlock access, or start fulfillment." ], "selectionRules": [ "Choose payment collection when the main task is taking or reconciling money for a known amount and reference.", "Use checkout when the payment is embedded inside cart, delivery, tax, discount, inventory, and order finalization.", "Use payment-card entry when the primary surface is card number, expiry, CVC, billing postal code, tokenization, and card-specific field recovery.", "Use bank details when collecting account identifiers for payout, direct debit, refund, payroll, or account-to-account transfer rather than collecting money now.", "Use retry when the same failed request is being attempted again; payment collection decides whether retry uses the same attempt, same reference, new method, or support path.", "Use confirmation page only after the payment succeeds or after the service accepts a pending payment state with clear next steps.", "Show amount, currency, reference, description, payer or account context, and what the payment unlocks before the user leaves for a provider or submits details.", "State who processes the payment, what methods are accepted, whether fees apply, and what happens after bank authentication or redirect.", "Use hosted fields, embedded payment elements, hosted pages, or redirects for sensitive payment credentials when the product should not own credential capture.", "Preserve the payment reference, amount, and service context across redirect, browser Back, failure, cancel, timeout, and support handoff.", "Disable or guard duplicate pay actions while authorization, capture, order creation, or status verification is in flight.", "Distinguish not attempted, requires action, processing, failed, canceled, succeeded, refunded, and pending reconciliation states in user-facing copy." ], "requiredStates": [ "Payment request state with amount, currency, reference, description, payer context, accepted methods, and secure provider handoff.", "Method selection state for card, wallet, bank redirect, saved method, payment link, or alternate route.", "Sensitive details state delegated to hosted or compliant payment UI.", "Provider redirect or authentication state with clear return expectations.", "Processing or pending status state that prevents duplicate payment while status is uncertain.", "Requires action state such as bank authentication or mandate acceptance.", "Failed or declined state with reason category, preserved context, and retry or alternate-method route.", "Canceled or abandoned state with safe resume or start-new-payment route.", "Expired payment session state with a new attempt route tied to the same service reference where appropriate.", "Succeeded state with receipt, payment reference, amount paid, date, and next step.", "Refunded, partially refunded, or reversed state when relevant after payment.", "Status lookup or reconciliation state for asynchronous provider updates and support." ], "interactionContract": [ "Every payment attempt is tied to a stable service reference, amount, currency, and payer context that remains visible before and after provider handoff.", "The final pay action names the amount or consequence and becomes busy or disabled while the payment attempt is being created or confirmed.", "Redirect returns restore the same payment context and immediately show the latest known provider status or a status-checking state.", "Failure, cancel, timeout, and retry keep non-sensitive service data while clearing or delegating sensitive payment credentials according to provider rules.", "Retry uses idempotency or a clearly new attempt policy so users cannot accidentally create duplicate charges.", "The interface never claims payment succeeded until the provider or trusted backend status supports that state.", "Successful payment removes editable payment controls and hands off to receipt, confirmation, or the next service step." ], "implementationChecklist": [ "Define payment owner, amount source, reference format, idempotency strategy, provider surface, accepted methods, status model, retry rules, refund rules, and reconciliation source before designing the UI.", "Design request, method selection, provider handoff, authentication, processing, failed, canceled, expired, succeeded, refunded, and status-lookup states.", "Bind amount, currency, reference, description, and payer context to canonical backend records rather than browser-only state.", "Use hosted provider pages, payment elements, or compliant credential capture for sensitive details and avoid storing payment secrets in application state.", "Handle webhooks or backend status polling for asynchronous success, failure, processing, refund, and reconciliation events.", "Add idempotency keys, duplicate-submit guards, and clear busy states for payment creation, confirmation, capture, and retry.", "Preserve payment context across redirect, browser Back, refresh, session timeout, provider cancel, decline, and support handoff.", "Redact payment credentials, provider tokens, full card data, bank details, failure payloads, and personal data from logs, analytics, screenshots, replay tools, and support transcripts.", "Test double submit, redirect return, bank authentication, wallet cancel, decline, processing delay, status polling, provider outage, expired session, refund display, mobile viewport, screen readers, and high zoom." ], "commonMisuses": [ "Showing a Pay button without amount, currency, or reference.", "Letting users submit the same payment twice while the first attempt is processing.", "Clearing the service context after a decline, cancel, or provider redirect.", "Collapsing declined, canceled, expired, processing, and provider-unavailable states into one payment failed message.", "Claiming success before backend or provider status confirms payment.", "Collecting raw card or bank credentials directly when a hosted or compliant provider surface should own them.", "Generating a new reference on every retry without explaining whether a duplicate charge is possible.", "Sending users to a receipt page without payment reference, amount paid, timestamp, and support route." ], "critiqueQuestions": [ "What amount, currency, reference, and service outcome is this payment tied to?", "Which surface owns sensitive payment credentials, and what must never enter product logs or state?", "What exact states can the provider return, and how are they shown to the user?", "Can users safely return from authentication, cancel, refresh, browser Back, or support without losing payment context?", "How does retry avoid duplicate charges or duplicate service submissions?", "When is it safe to show receipt or confirmation, and what evidence proves that status?" ], "relatedPatterns": [ "checkout", "payment-card-entry", "bank-details", "retry", "confirmation-page", "loading-spinner", "error-summary", "review-before-submit" ], "comparisons": [ "payment-collection-vs-checkout-vs-payment-card-entry-vs-bank-details" ], "sourceIds": [ "govuk-pay-take-a-payment", "govuk-pay-api-reference", "stripe-payment-intents-lifecycle", "stripe-payment-element-overview", "stripe-idempotent-requests", "pci-dss-payment-card-data" ] }, { "id": "permission-denied-state", "completionStatus": "complete", "name": "Permission denied state", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Authorization and access-boundary state", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users cannot recover from access boundaries when a product hides the cause, confuses authorization with system failure, leaks sensitive resource details, or gives no owner-assisted path.", "solution": "Present an explicit permission denied state that states the safe-to-reveal boundary, current identity, required access, available fallback, request or owner path, request status, and policy limits without exposing information the user is not allowed to know.", "uiGuidance": [ "Show the blocked object or action, current account, permission level, required role, owner, and request path when revealing that information is allowed.", "Use a no-disclosure variant when policy must hide existence, title, path, owner, count, or collaborator details from the current account." ], "uxGuidance": [ "Use permission denied state when the system knows the user is authenticated but their role, group, share, license, policy, or approval status blocks a specific object or action.", "Help users self-correct through request access, switch account, read-only fallback, contact owner, return to allowed work, or review request status instead of sending them into retry loops." ], "uiExamples": { "good": [ "A report page says Quarterly revenue report requires Finance viewer access, shows the current account, names the report owner, and offers Request access and Switch account.", "A viewer can read a document but the Publish action says Editor access is required and links to the owner rather than disabling the button silently.", "A private repository settings page says Admin role required to manage secrets while preserving read access to permitted repository content." ], "bad": [ "A denial page says Something went wrong and shows Retry even though the user lacks a required group.", "A confidential case page leaks the case title to a user who should not know it exists.", "A toolbar hides the Publish button for non-admins without explaining why the workflow is blocked." ] }, "uxExamples": { "good": [ "A user opens a restricted report, sees which account is signed in, requests viewer access with a reason, then sees that the request is pending with the owner.", "A collaborator with viewer access keeps reading a file while the edit action explains that editor access must be requested from the owner.", "A developer tries to change repository settings, sees Maintain is insufficient for security settings, and contacts an Admin rather than retrying the request." ], "bad": [ "The app returns a blank screen for a restricted file, so the user cannot tell whether the file is gone, private, or opened with the wrong account.", "A request access action submits and immediately says success even though no owner decision exists.", "Every workspace control is disabled after one missing permission, including safe navigation and read-only tasks." ] }, "problemContext": [ "The product has accounts, roles, teams, sharing links, private objects, licenses, compliance policy, or admin-only actions.", "A user is authenticated but cannot view, edit, approve, publish, delete, export, invite, manage, or configure a known object or action.", "The same surface may need different outcomes for wrong account, missing role, read-only access, pending request, declined request, policy block, and no-disclosure security.", "The product must balance recovery and support with privacy, security, and least-privilege rules." ], "selectionRules": [ "Choose permission denied state when the primary cause is missing authorization, role membership, share grant, license entitlement, approval, or organization policy.", "Show the access boundary at the smallest useful scope: whole page, panel, row, file, field, toolbar action, submit step, or admin setting.", "State what the user can still do, such as view read-only content, copy an ID, return to allowed folders, request access, contact owner, or switch account.", "Say which account, workspace, group, or role is currently active when wrong-account recovery is plausible.", "Name the required permission or role in user-facing language, such as Finance viewer, Editor, Publisher, Owner, Maintainer, or Admin.", "Include request state after submission: sent, pending, approved, declined, expired, owner unavailable, or blocked by policy.", "Use a no-disclosure denial when exposing object existence, title, owner, path, or count would leak private information.", "Use error state when the user has access but the operation failed for network, validation, server, timeout, or data reasons.", "Use empty state when there is no safe known object or blocked action to recover, and the main issue is absence of visible items.", "Replace disabled-button-only treatment with explanatory permission text, owner/contact path, and allowed fallback." ], "requiredStates": [ "Whole-object access denied state.", "Action-level denied state for publish, export, delete, invite, approve, manage, or configure actions.", "Read-only state with edit denied but view allowed.", "Request access form with optional reason and requested permission level.", "Request sent or pending state naming the owner or safe recipient.", "Request declined state with safe next steps.", "Approved state that lets users retry or open the resource.", "Wrong-account state with switch-account path.", "Owner unavailable or policy-blocked state.", "No-disclosure state that avoids leaking restricted object details." ], "interactionContract": [ "The denial is durable until the permission, account, role, policy, or request state changes.", "Request access records the requested role, reason, requester account, target object or action, owner destination, and timestamp when policy allows.", "Switch account returns to the intended resource after authentication when possible.", "Read-only fallback preserves allowed viewing and safe navigation while blocking only restricted actions.", "Owner-assisted paths identify a safe contact, team, admin group, or support route instead of exposing private collaborator lists.", "No-disclosure variants use neutral navigation and support paths without confirming whether the private resource exists." ], "implementationChecklist": [ "Model authorization denial separately from not found, unauthenticated, rate limit, network failure, validation failure, and empty result states.", "Capture denial reason codes that map to safe user copy, requestability, current account, current role, required role, owner visibility, and no-disclosure policy.", "Implement request access flows with submission status, owner routing, approval or decline outcomes, expiry, and duplicate request handling.", "Preserve allowed read-only content and navigation when only a specific action is denied.", "Instrument support-safe diagnostics such as request ID, policy name, account, and timestamp without exposing restricted object data.", "Test wrong account, missing role, revoked share, expired link, pending request, declined request, policy block, owner unavailable, private-object no-disclosure, and screen reader recovery." ], "commonMisuses": [ "Treating authorization denial as a generic retryable error.", "Showing an empty state for a known restricted object without any request or account path.", "Disabling controls without explaining missing access.", "Leaking private object titles, owners, counts, comments, or paths in a denial page.", "Claiming request success before an owner approves access.", "Blocking read-only work when only edit, publish, or admin action is restricted." ], "critiqueQuestions": [ "Can the user tell whether this is missing access, wrong account, policy, or system failure?", "What object or action is safe to name, and what must stay hidden?", "Which current account, role, team, or share grant is being evaluated?", "What role or permission is required for the blocked action?", "Who can grant access, and is that owner path safe to reveal?", "What can the user still do while access is pending or denied?" ], "relatedPatterns": [ "error-state", "empty-state", "disabled-button-no-explanation", "inline-message", "alert", "notification-center", "global-navigation" ], "comparisons": [ "permission-denied-state-vs-error-state-vs-empty-state-vs-disabled-button-no-explanation" ], "sourceIds": [ "microsoft-sharepoint-access-requests", "google-drive-file-access-requests", "github-repository-roles" ] }, { "id": "permission-prompt-with-no-context", "completionStatus": "complete", "name": "Permission prompt with no context", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Anti-pattern for platform permission prompts shown without a feature-triggered rationale, fallback, or recovery path", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users are more likely to deny, distrust, or misunderstand permission requests when a product asks before the relevant feature is visible, uses vague benefit copy, requests the wrong resource, bundles multiple resources, or provides no fallback after denial.", "solution": "Classify contextless permission prompts as an anti-pattern, move the ask to the feature-triggered moment, show a resource-specific rationale and fallback before the platform prompt, avoid unrelated or bundled requests, and handle denied, dismissed, limited, revoked, and settings-required states explicitly.", "uiGuidance": [ "Do not trigger camera, microphone, location, photos, contacts, notification, Bluetooth, clipboard, motion, or storage permission prompts on launch, sign-in, onboarding, or unrelated navigation before the feature need is visible.", "Replace a contextless permission prompt with a contextual feature gate that names the resource, task, timing, choices, fallback, denial outcome, and settings recovery before invoking the system prompt." ], "uxGuidance": [ "Treat permission prompts without context as an anti-pattern because users cannot make an informed choice when the resource, benefit, immediate task, and consequence of denial are unclear.", "Ask only when the user starts the resource-dependent feature, request the least powerful resource that works, and preserve eligible work through manual input, picker, limited access, or continue-without routes." ], "uiExamples": { "good": [ "A receipt scanner waits until the user taps Scan receipt, explains camera is needed only for the scan, then offers Scan with camera or Upload file.", "A route check-in shows why current location verifies arrival, offers Enter address instead, then opens the system location prompt only after Use current location.", "A notification opt-in appears after a user follows a shipment and names delivery alerts, frequency, and the continue-without-notifications path." ], "bad": [ "An app opens with location, contacts, photos, and notifications prompts before any feature is selected.", "A modal says Allow access to improve your experience and then triggers microphone permission.", "A denied prompt blocks the whole account even though only one optional feature needed the resource." ] }, "uxExamples": { "good": [ "A user declines camera access for receipt scanning, uploads an image instead, and can keep using expense entry.", "A user dismisses location access at first, later taps Find near me, sees a contextual explanation, grants approximate location, and finishes the task.", "A user previously denied notifications and sees settings instructions plus an email-alert fallback instead of repeated browser prompts." ], "bad": [ "A user denies a first-launch permission prompt because it appears before the app explains the feature, then cannot find how to turn the feature on later.", "A user accepts a vague request believing it is for nearby search, but the app also enables background tracking.", "A user denies contacts access and the onboarding flow loops the same prompt instead of allowing manual invite entry." ] }, "problemContext": [ "The prompt requests an operating-system, browser, or app-level permission for a device resource or powerful feature such as location, camera, microphone, photos, contacts, notifications, Bluetooth, clipboard, motion sensors, or storage access.", "The user has not yet chosen the feature that needs the resource, or the UI does not name the task and benefit before the system prompt appears.", "The product may use first-run onboarding, account creation, a splash screen, a fake setup checklist, or a broad modal to collect permission for speculative future use.", "Denial may be mishandled through repeat nags, blocked flows, settings dead ends, broad consent assumptions, resource mismatch, or loss of unrelated product access." ], "selectionRules": [ "Flag this anti-pattern when a permission prompt appears before the user starts a resource-dependent feature or before the interface explains why the resource is needed now.", "Flag it when vague copy such as improve your experience, stay connected, or enable full functionality hides the resource, task, fallback, or denial outcome.", "Flag it when one action triggers a different permission than the visible feature implies, such as a scan action triggering contacts or a store finder triggering background location.", "Flag it when multiple permissions are requested together without separate feature-specific rationale and separate recovery paths.", "Use permission request for the corrected pattern when the product can ask in context, name the resource, invoke the system prompt deliberately, and handle grant or denial.", "Use location permission flow when the context problem is specifically current coordinates, precision, stale location, active tracking, stop sharing, or location fallback.", "Use consent prompt when the choice is optional data use rather than OS or browser resource access.", "Use permission denied state when the user is authenticated but lacks an account role, license, share, policy, or owner-granted authorization.", "Use notification preferences when the user is managing message topics, channels, digest, quiet hours, or subscription settings after OS-level access is handled.", "Use privacy settings when the user is reviewing durable account-level resource, data, or sharing controls rather than reacting to a just-in-time permission ask." ], "requiredStates": [ "Cold-start prompt state before the user chooses a relevant feature.", "Vague rationale state where the copy hides the resource, task, or fallback.", "Resource mismatch state where the system prompt asks for a different resource than the UI described.", "Bundled permissions state that asks for multiple resources as one broad setup step.", "Feature-triggered correction state showing the exact resource and task before the system prompt.", "Least-access alternative state with picker, upload, manual entry, approximate access, one-time access, or continue-without path.", "Deny without punishment state where unrelated work remains available.", "Previously denied or settings-required state with concise recovery instead of another prompt loop.", "Repeat nag and blocked-on-deny bad states.", "Mobile compact state where context, resource, primary choice, and fallback remain visible." ], "interactionContract": [ "The product must not invoke the platform prompt from page load, app launch, passive onboarding, timers, or unrelated navigation.", "The pre-prompt must name the resource, user-triggered feature, immediate benefit, denial outcome, and fallback before the system prompt is invoked.", "Each permission ask is scoped to one feature or clearly separated feature group; bundled prompts require separate explanation and separate choices.", "The requested resource must match the visible action and copy.", "Dismissing or declining the contextual explanation must not trigger the system prompt.", "Denying the permission must preserve unrelated navigation and eligible non-resource tasks.", "Previously denied, permanently denied, revoked, blocked, or limited states must show a settings route or lower-access fallback rather than loop the same prompt.", "The UI must distinguish permission request from consent, account authorization, notification topic settings, privacy settings, and approval gates." ], "implementationChecklist": [ "Inventory every system permission and map it to the exact feature action that first needs the resource.", "Remove first-run, splash-screen, onboarding, sign-in, page-load, and unrelated-navigation permission triggers unless the feature itself is being started.", "Write resource-specific rationale copy that names the task, resource, benefit, choice, fallback, and settings path.", "Split bundled resource asks into separate feature-triggered requests or lower-access alternatives.", "Add denial, dismissal, previously denied, permanently denied, limited, revoked, unavailable, and settings-required branches.", "Provide fallback routes such as manual address, upload file, paste code, type contact, chat-only mode, continue without notifications, or open settings.", "Test cold start, feature-triggered ask, grant, deny, dismiss, repeat visit, permanent denial, resource mismatch, bundled permissions, compact layout, keyboard order, and status messaging." ], "commonMisuses": [ "Requesting permissions on first launch because analytics show users may need the feature later.", "Asking for location, notifications, contacts, and photos as one setup checklist before explaining any task.", "Using vague benefit copy instead of naming the resource and feature.", "Triggering a system prompt from a custom modal close, page load, hover, timeout, or background script.", "Treating denial as a reason to block the whole product.", "Looping a custom prompt or browser prompt after denial.", "Requesting a more invasive permission than the feature needs." ], "critiqueQuestions": [ "What exact user action made this permission necessary now?", "Can the user understand the resource, task, benefit, fallback, and denial outcome before the system prompt appears?", "Is the requested resource the least powerful option that works for this task?", "What does the product do after deny, dismiss, limited access, revoked permission, or permanent denial?", "Can users complete the core task through a manual or lower-access route?", "Is this a device permission, optional data-use consent, account authorization, notification preference, privacy setting, or human approval decision?" ], "relatedPatterns": [ "permission-request", "location-permission-flow", "consent-prompt", "permission-denied-state", "notification-preferences", "privacy-settings", "sensitive-data-reveal" ], "comparisons": [ "permission-prompt-with-no-context-vs-permission-request-vs-location-permission-flow-vs-consent-prompt-vs-permission-denied-state-vs-notification-preferences" ], "sourceIds": [ "nng-permission-requests", "android-runtime-permissions", "mdn-permissions-api", "w3c-permissions-api" ] }, { "id": "permission-recovery", "completionStatus": "complete", "name": "Permission recovery", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Guided workflow for regaining or routing around missing access", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users cannot complete blocked work when the product stops at access denied, loses the original task, repeats denied requests, hides request ownership or status, or offers request paths that cannot actually change the permission.", "solution": "Provide a permission recovery workflow that preserves the blocked task, identifies the current identity and missing access, gathers the requested role and reason, routes to an authorized owner or admin, tracks pending and final outcomes, supports wrong-account switching, and retries or resumes only after access changes.", "uiGuidance": [ "Show a recovery workspace after denial with the current account, current role, requested role, safe owner or admin destination, request reason, policy limits, status timeline, and original blocked task.", "Separate request submission, pending owner decision, approved access, declined access, wrong-account switch, policy escalation, and safe fallback actions so users do not confuse recovery with repeated retry." ], "uxGuidance": [ "Use permission recovery when users can take a concrete step to regain access, use another identity, request a different role, escalate a policy block, or continue with a safe fallback after an authorization denial.", "Preserve the original intent and return path, avoid duplicate requests, expose request status and outcomes, and retry the original action only after the authorization state has actually changed." ], "uiExamples": { "good": [ "A restricted report recovery panel shows alex@northwind.example lacks Finance viewer access, lets the user request Viewer or Editor with a reason, names Priya as the approver, shows request ACC-2048 as pending, and returns to the report after approval.", "A file access screen detects the file is already shared with another signed-in account and offers Switch to northwind-finance@example.com before sending a new request.", "A repository settings page says Maintain role cannot edit secrets, explains Admin is required, offers Contact admins with the setting path attached, and leaves read-only repository navigation available." ], "bad": [ "A blocked report only has Retry, so the user repeats the same denied request.", "A request access form says Done immediately and never shows whether an owner approved, declined, or even received the request.", "A policy-blocked file keeps offering Request access even though organization policy prevents external sharing." ] }, "uxExamples": { "good": [ "A user requests Finance viewer access with a reason, sees the request is pending with Priya, receives approval, opens the report from the same recovery panel, and lands back on the original report.", "A user tries to request access for the wrong account, switches to a signed-in account that already has the share grant, and returns to the file without creating a duplicate owner request.", "A developer blocked by repository role sees Admin is required for secrets, sends a request to repository admins with the setting path, and keeps using read-only settings while waiting." ], "bad": [ "A user repeatedly clicks Retry on a permission denial because the UI treats authorization as a transient load failure.", "A user submits three access requests because the first request's pending state disappears after reload.", "A user waits for an owner who cannot grant access because the product hid the policy block and escalation path." ] }, "problemContext": [ "The product has already determined that authorization, role membership, sharing, policy, license, or owner approval blocks a known task.", "The user has a viable recovery path such as request access, switch account, choose a lower-risk fallback, contact an owner, ask an admin, join a group, or escalate a policy exception.", "The request may have asynchronous states: sent, pending, duplicate, approved, declined, expired, owner unavailable, or policy blocked.", "The product must preserve least-privilege and no-disclosure rules while giving users enough state to recover without support guesswork." ], "selectionRules": [ "Choose permission recovery when the interface needs to guide users through request, approval, switch-account, policy, fallback, or retry-after-grant steps after a permission denial.", "Use permission denied state for the durable blocked access message itself; permission recovery is the workflow that follows when recovery actions are possible.", "Use session timeout warning when authentication expired or is about to expire; use permission recovery when the user is authenticated but lacks authorization.", "Use retry only after a permission or role change has happened; retrying the same denied request is not recovery.", "Use error state when an operation failed despite adequate authorization, not when the required role or share grant is missing.", "Name the original blocked task and return destination when policy allows, so successful recovery resumes the user's intent.", "Collect only access-relevant information such as requested role, reason, duration, account, workspace, object, owner, and policy exception.", "Show duplicate request, pending request, approved, declined, expired, owner unavailable, and policy-blocked outcomes distinctly.", "Offer wrong-account switching before owner requests when another signed-in account already has access.", "Do not promise access before an authorized owner, admin, policy engine, or entitlement system grants it." ], "requiredStates": [ "Recovery start state with original blocked task and current account.", "Requested role selection state.", "Reason or justification entry state.", "Owner or admin routing state.", "Request sent state with request ID and destination.", "Pending request state that prevents duplicates.", "Approved state with retry or reopen original task.", "Declined state with safe fallback or escalation.", "Wrong-account switch state with return path.", "Policy-blocked or owner-unavailable state with support-safe escalation." ], "interactionContract": [ "The recovery workflow opens from a known permission denial and keeps the original object or action attached when safe to reveal.", "Submitting a request records requester account, requested role, reason, target, owner or admin destination, timestamp, and request ID.", "A duplicate request reopens the existing pending state instead of sending another owner notification.", "Switch account returns to the intended object or action after authentication when possible.", "Approval changes the available actions and lets users retry, reopen, or resume the original task.", "Decline, expiry, policy block, and owner-unavailable states explain what will not change through retry and offer safe alternatives.", "No-disclosure policies suppress restricted object metadata while still allowing neutral account, support, or policy recovery.", "Notification or email outcomes deep-link back to the recovery state instead of losing the request context." ], "implementationChecklist": [ "Model permission recovery separately from unauthenticated, not found, operation failure, validation failure, and empty-content states.", "Store recovery state with denied action, target object, requestability, current account, current role, requested role, owner visibility, policy limit, request ID, status, and return URL.", "Implement role selection, reason entry, request submission, duplicate-request detection, pending status, cancel or update request, approval, decline, expiry, and escalation flows.", "Detect wrong-account cases and preserve the intended resource through account switching.", "Route owner-unavailable and policy-blocked states to admins, support, or allowed fallback instead of resending impossible requests.", "Keep safe fallback tasks such as read-only view, copy ID, open allowed dashboard, or contact manager available while recovery is pending.", "Test owner approval, owner decline, duplicate request, reload during pending, notification return, wrong account, policy block, no-disclosure, request expiration, keyboard access, and screen reader status announcements." ], "commonMisuses": [ "Offering Retry for an unchanged authorization denial.", "Treating request submission as access approval.", "Hiding pending request status and sending duplicate owner notifications.", "Letting users request a role that the target owner cannot grant.", "Losing the original blocked task after approval.", "Exposing restricted object details in request history or notifications.", "Blocking safe read-only or fallback work while access is pending." ], "critiqueQuestions": [ "What exact role, share grant, license, or policy change would recover the task?", "Who can approve it, and is that destination safe to reveal?", "Can the user switch to an account that already has access before requesting new access?", "What prevents duplicate requests while a decision is pending?", "How does the user resume the original blocked task after approval?", "What happens when access is declined, expired, owner-unavailable, or policy-blocked?" ], "relatedPatterns": [ "permission-denied-state", "session-timeout-warning", "retry", "error-state", "notification-center", "warning-text", "confirmation-dialog", "empty-state" ], "comparisons": [ "permission-recovery-vs-permission-denied-state-vs-session-timeout-warning-vs-retry" ], "sourceIds": [ "microsoft-sharepoint-access-requests", "google-drive-file-access-requests", "github-repository-roles" ] }, { "id": "permission-request", "completionStatus": "complete", "name": "Permission request", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Contextual operating-system or browser permission request for device resources, powerful browser features, private user data, or local capabilities", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users distrust and reject permission prompts when products ask too early, ask for the wrong resource, fail to explain the feature need, provide no fallback after denial, or ignore revoked and limited permission states.", "solution": "Ask for the minimum device or browser permission at the moment a feature needs it, explain the resource and user benefit before the system prompt, respect grant and deny outcomes, show permission status, and provide fallback or settings recovery when access is unavailable.", "uiGuidance": [ "Render a permission request as a contextual feature gate that names the resource, user action, immediate benefit, system prompt timing, available choices, and fallback before invoking the OS or browser permission prompt.", "Show the permission status after grant, denial, revocation, limited access, one-time access, or settings-required outcomes, and keep a useful manual path when permission is not available." ], "uxGuidance": [ "Use permission request when a feature needs operating-system or browser authorization for resources such as location, camera, microphone, photos, contacts, notifications, Bluetooth, clipboard, motion sensors, or other powerful features.", "Ask only after the user starts the feature that needs the resource, explain why access is needed in product language, handle grant and deny outcomes cleanly, and degrade the feature without blocking unrelated work." ], "uiExamples": { "good": [ "A field service app asks for location only when the user taps Start route, explains that current location will verify arrival, then opens the system permission prompt and offers manual address entry if declined.", "A video support tool asks for camera and microphone when the user starts a call, shows device test controls, and offers chat-only support if either permission is denied." ], "bad": [ "An app asks for location, contacts, photos, and notifications on first launch before the user knows why any resource is needed.", "A notification opt-in prompt says Enable important updates but triggers an unrelated camera permission prompt." ] }, "uxExamples": { "good": [ "A user taps Scan receipt, sees why camera access is needed for scanning, grants access, scans the receipt, and can later revoke camera access from settings without losing account access.", "A user denies precise location, chooses approximate location instead, and the app still shows nearby pickup points with lower accuracy." ], "bad": [ "A user denies microphone access and the app loops the same system prompt every time they tap anything in the support screen.", "A user previously denied photos access permanently and the product keeps showing Try again instead of explaining the settings route or limited library option." ] }, "problemContext": [ "The permission boundary is controlled by the operating system or browser rather than only the product's own account settings.", "The resource can expose private user data, device sensors, local files, camera, microphone, notifications, location, contacts, Bluetooth devices, clipboard contents, storage access, payment handlers, or other powerful platform features.", "The product may see granted, denied, prompt-ready, previously denied, permanently denied, limited, approximate, while-in-use, one-time, revoked, blocked-by-policy, or unavailable states.", "The user may need a manual fallback such as upload file, enter address, paste code, type contact, use chat-only mode, open settings, or continue without the optional feature." ], "selectionRules": [ "Choose permission request when the user is authorizing an OS, browser, or device resource such as camera, microphone, location, photos, contacts, notifications, clipboard, Bluetooth, motion sensors, storage access, or another powerful feature.", "Ask in context when the user starts the feature that requires the resource rather than during cold start, account creation, or unrelated navigation.", "Explain why the resource is needed, what action triggered the request, what the user can do without granting it, and whether the permission is one-time, while-in-use, limited, approximate, or persistent.", "Use consent prompt when the decision is active opt-in to optional data use such as marketing, research, personalization, partner sharing, AI training, or sensitive-data processing.", "Use permission sharing when a user or admin grants durable access to another person, group, link, service account, key, or role.", "Use permission recovery when a denied user requests access from an owner or admin after an account authorization boundary.", "Use permission denied state when the product is explaining a role, policy, license, or share boundary after authorization fails.", "Use notification preferences when the user already has or does not need OS notification access and is choosing message channels, topics, frequency, quiet hours, digest behavior, or subscriptions.", "Use privacy settings when the task is long-term account-level privacy controls rather than a just-in-time platform permission prompt.", "Do not use a custom pre-prompt to pressure, mislabel, or repeatedly nag after the user has declined the system prompt." ], "requiredStates": [ "Contextual request state tied to the user action that needs the resource.", "Feature-triggered ask state that names the resource, task, benefit, and optional fallback.", "System prompt ready state immediately before invoking the browser or OS permission prompt.", "Grant permission state with enabled feature, saved status, and next step.", "Deny permission state with respectful refusal copy and no unrelated blocking.", "Denied fallback state with manual address entry, file upload, chat-only mode, or another route that does not need the permission.", "Ask again later state when the user dismisses the explanation before the system prompt.", "Previously denied state that explains why the system prompt may not appear again.", "Permanently denied or settings required state with a stable settings route.", "Limited access state for photo library selection, approximate location, or partial resource grant.", "While-in-use and one-time permission states with clear lifetime expectations.", "Permission revoked state detected when the user changes OS or browser settings.", "Permission status check state for granted, denied, prompt, blocked, unavailable, or policy-limited outcomes.", "Manual fallback state that lets the user complete eligible work without the resource.", "Mobile compact state where resource name, reason, choices, and fallback stay visible." ], "interactionContract": [ "The product evaluates whether permission is truly needed before declaring or requesting the platform permission.", "The pre-prompt appears only after a feature-triggering action and can be canceled without accepting the system prompt.", "The system prompt is invoked from the feature action or explicit continue action, not from passive page load or hidden timers.", "The requested permission matches the visible feature; a camera action must not trigger contacts, precise location, or notifications without explanation.", "Granting permission enables only the named feature and updates visible status before continuing.", "Denying permission leaves unrelated navigation, account access, and eligible non-resource work available.", "Previously denied, permanently denied, revoked, blocked, and limited states show a settings route or manual fallback instead of repeating a failing prompt.", "The interface updates when permission status changes and records telemetry without collecting resource data before permission exists." ], "implementationChecklist": [ "Inventory every requested permission, the feature that needs it, the user action that triggers it, and whether a lower-permission alternative exists.", "Minimize permission requests and avoid declaring resources that can be handled with pickers, file uploads, manual entry, transient activation, or feature-specific APIs.", "Write pre-prompt copy that names the resource, task, benefit, choice, fallback, and settings path in the same words used by the feature.", "Implement status checks for granted, denied, prompt, limited, one-time, while-in-use, revoked, unavailable, and blocked-by-policy outcomes where the platform exposes them.", "Provide denial fallbacks such as manual address entry, upload file, choose from limited library, continue without notifications, use chat, or open settings.", "Test first ask, grant, deny, dismiss, previously denied, permanently denied, limited photo access, approximate location, revoked permission, mobile layout, keyboard order, and screen-reader labels." ], "commonMisuses": [ "Asking for multiple resources at launch before the user has attempted the relevant feature.", "Using vague copy such as improve your experience instead of naming the resource and task.", "Blocking an entire product after denial even though only one optional feature needed the permission.", "Looping the same system prompt or custom prompt after the user declines.", "Pretending permission is required when a manual fallback or platform picker would work.", "Providing no settings route after the platform stops showing the prompt.", "Requesting a different permission than the visible feature implies." ], "critiqueQuestions": [ "What specific user action makes this permission necessary now?", "Can the task be completed with less access, a picker, limited library, approximate location, one-time access, or manual entry?", "Does the prompt name the exact resource and feature benefit before the system dialog appears?", "What happens after grant, denial, dismissal, limited access, revocation, or settings-required outcomes?", "Can users continue unrelated work when they decline?", "Is the settings route clear when the platform will not show the prompt again?", "Does the requested permission exactly match the resource described in the UI?" ], "relatedPatterns": [ "consent-prompt", "permission-sharing", "permission-recovery", "permission-denied-state", "notification-preferences", "preference-center", "settings-management", "file-upload", "error-state" ], "comparisons": [ "permission-request-vs-consent-prompt-vs-permission-sharing-vs-permission-recovery-vs-permission-denied-state-vs-notification-preferences" ], "sourceIds": [ "android-runtime-permissions", "mdn-permissions-api", "w3c-permissions-api", "nng-permission-requests" ] }, { "id": "permission-sharing", "completionStatus": "complete", "name": "Permission sharing", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Durable permission administration for users, groups, roles, inherited access, effective access, and revocation", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Permission administration is risky when products hide group inheritance, effective access, role capabilities, connected-team membership, anonymous access, service credentials, or revoke outcomes behind a simple share or remove control.", "solution": "Provide a permission sharing surface that exposes direct and inherited grants, users and groups, role meanings, effective access, pending changes, risky grants, approval or confirmation needs, audit context, and complete revoke paths before access is changed.", "uiGuidance": [ "Render permission sharing as an access-management surface with the protected resource, current direct grants, inherited grants, groups, guests, anonymous or link access, role or permission level, effective access, pending changes, and revoke or save actions.", "Make the permission model visible before saving: users should see whether access comes from a direct grant, group membership, parent scope, connected team, service account, deploy key, anonymous access, or owner/admin role." ], "uxGuidance": [ "Use permission sharing when authorized owners or admins need to grant, change, audit, or revoke durable access to a space, site, repository, folder, project, board, dataset, environment, or sensitive object.", "Protect least privilege by showing what each role allows, why a person or group still has access, what will change after save, which changes require review, and which grants cannot be removed from this surface." ], "uiExamples": { "good": [ "A repository access page lists teams, outside collaborators, deploy keys, and direct users with Read, Triage, Write, Maintain, and Admin roles, showing that only Admin can manage access.", "A space permissions page shows Users, Groups, Guests, and Anonymous access tabs with View, Add, Delete, Export, Restrictions, and Admin columns plus an Effective access summary for selected people." ], "bad": [ "A permissions page shows only individual names and Remove buttons even though group membership and parent folder inheritance still grant access.", "A checkbox matrix lets admins grant Export and Space Admin without explaining the data exposure or requiring a high-risk review." ] }, "uxExamples": { "good": [ "A site owner adds the Finance Reviewers group as Visitors, sees that Members can contribute content, confirms no anonymous access is enabled, and saves with an audit note.", "A space admin removes Maya from a direct grant but sees she still has View through the Contractors group, so they remove the group grant or ask a site admin to update group membership." ], "bad": [ "An owner downgrades a user to Viewer, but the user keeps edit rights through a connected team and the UI never explains effective access.", "A repository admin removes a collaborator but forgets a deploy key with write access because the access page treated machine credentials as unrelated settings." ] }, "problemContext": [ "The resource has durable authorization rules such as roles, groups, teams, guests, anonymous users, parent inheritance, folder scope, repository roles, space permissions, service accounts, or keys.", "The user is an owner, admin, space admin, repository admin, site owner, project maintainer, data steward, or delegated access manager.", "Permission changes may apply to many objects, cascade through inheritance, affect connected services, expose confidential data, or remove a person's only route to work.", "The system may need audit evidence, approval, expiration, policy checks, inherited access explanation, and no-disclosure treatment for sensitive resources." ], "selectionRules": [ "Choose permission sharing when users manage durable access grants, role assignments, group permissions, effective access, inheritance, anonymous access, or revocation for a protected resource.", "Use share dialog for quick object-level sharing with recipients, link scope, notification, and copy-link behavior.", "Use invite user when access starts through a pending workspace, organization, team, or tenant invitation lifecycle.", "Use permission recovery when a denied user asks an owner or admin to grant access; permission sharing is the owner-facing grant and revoke surface.", "Use permission denied state when the user only needs to understand why they cannot access or perform an action.", "Use approval workflow when the permission change requires an approver or policy decision before it is applied.", "Use review before submit or confirmation dialog for public, anonymous, admin, export, delete, inherited-access break, service-account, deploy-key, and bulk-removal changes.", "Include direct access, inherited access, group access, guest access, anonymous access, service credentials, owner/admin roles, and effective access where those routes exist.", "Show role capabilities in task language such as view, comment, add, edit, delete, export, manage access, administer, or approve.", "Do not claim access is revoked until every active route to access is removed or explicitly named as still active." ], "requiredStates": [ "Default access list state with users, groups, guests, anonymous access, roles, and effective access.", "Direct grant, inherited grant, group membership, connected-team membership, service-account, deploy-key, and anonymous-access states.", "Add user or group state with entity lookup, duplicate detection, role selection, and policy checks.", "Role change state with before and after capabilities.", "Pending changes review state that names who gains, loses, or keeps access.", "High-risk grant state for Admin, Owner, Space Admin, Full Control, anonymous access, public access, export, delete, or manage-access permissions.", "Revoke state that detects remaining access through groups, parent scopes, keys, or connected services.", "Approval required, policy blocked, inherited read-only, save failed, audit note required, and saved states.", "Bulk edit, long list, filter, search, sort, empty, loading, and permission-limited states.", "Mobile condensed state where role capability and effective access remain readable." ], "interactionContract": [ "Opening the permission sharing surface loads direct grants, inherited grants, group or team grants, anonymous access, service credentials, and owner or admin constraints before edits are saved.", "Adding a user or group requires a resolved entity, role, scope, and policy check before it creates an access grant.", "Changing a role shows the previous role, new role, key capabilities, and whether the change broadens or narrows access.", "Removing a row checks whether effective access remains through another route and labels any remaining group, parent, service, or anonymous grant.", "High-risk grants and removals require review, confirmation, approval, or audit note according to policy.", "Saving produces a clear result that distinguishes applied, pending approval, blocked, partial, and failed permission changes.", "The access list updates after save and preserves enough context for users to verify who can still access the resource.", "Audit records capture actor, resource, affected principal, old role, new role, source of access, timestamp, reason, approval, and policy outcome." ], "implementationChecklist": [ "Define the permission graph: direct grants, groups, teams, guests, anonymous users, link grants, parent inheritance, service accounts, deploy keys, roles, custom roles, owners, admins, and policy constraints.", "Compute effective access separately from direct rows and expose why each person or group can view, edit, export, delete, manage access, or administer.", "Build role descriptions, capability previews, before/after summaries, duplicate checks, inherited-read-only labels, and remaining-access warnings.", "Implement add, role change, revoke, bulk change, search, filter, sort, save, approval, audit note, cancel, retry, and rollback paths.", "Protect risky operations such as anonymous access, public export, Full Control, Admin, owner transfer, deploy key write access, service-account grants, and group-wide removal with review or approval.", "Test group overlap, inherited folder access, Teams or Microsoft 365 group connection, anonymous access, deploy keys, service accounts, owner-only controls, partial failures, long names, keyboard use, screen readers, and mobile wrapping." ], "commonMisuses": [ "Showing only direct users while group or inherited access remains active.", "Using a share dialog as the only permission administration surface.", "Hiding what a role can actually do until after it is assigned.", "Letting users remove a visible row and believe access is gone when effective access still exists.", "Treating service accounts, deploy keys, anonymous links, or connected teams as separate from human access review.", "Saving high-risk admin, public, export, delete, or anonymous grants with no review, approval, or audit note.", "Making bulk permission changes without before and after counts or rollback guidance." ], "critiqueQuestions": [ "What are all active routes by which a person, group, guest, anonymous user, service account, or key can access this resource?", "Can users tell the difference between direct access and inherited or group access?", "What does each role allow in task terms, and which actions are risky?", "Who gains access, who loses access, and who keeps access after the pending change?", "What happens if the user removes a direct grant but effective access remains?", "Which changes need confirmation, approval, audit note, expiry, or policy review?", "Can the saved access state be proven later in an activity log or audit export?" ], "relatedPatterns": [ "share-dialog", "invite-user", "permission-recovery", "permission-denied-state", "object-picker", "approval-workflow", "review-before-submit", "confirmation-dialog", "activity-log", "data-grid" ], "comparisons": [ "permission-sharing-vs-share-dialog-vs-invite-user-vs-permission-recovery" ], "sourceIds": [ "microsoft-sharepoint-groups-permissions", "microsoft-sharepoint-modern-sharing-permissions", "atlassian-confluence-space-permissions", "github-repository-roles", "google-drive-share-files", "microsoft-onedrive-manage-sharing-permissions" ] }, { "id": "phase-beta-banner", "completionStatus": "complete", "name": "Phase / beta banner", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Service phase and feedback marker", "maturity": "standard", "platforms": [ "web", "mobile" ], "problem": "Users need to know when a service is still being developed and teams need phase-specific feedback, but generic banners, alerts, or badges either overstate urgency, hide service maturity, or detach feedback from the user's current journey.", "solution": "Show a service-wide phase banner with the correct alpha or beta tag, concise maturity copy, and a feedback link that preserves route context; update or remove it when access, assessment, or live status changes.", "uiGuidance": [ "Render a compact phase tag such as Alpha or Beta with a short sentence and feedback link in the service header area, directly after service navigation or the primary header.", "Keep the phase banner visible across all service pages while the service is in that phase, but do not style it as an urgent alert, product announcement, cookie notice, or dismissible marketing banner." ], "uxGuidance": [ "Use a phase banner to set expectations that a service is still being worked on and to invite feedback that helps the team improve it.", "Tie the phase label to the actual delivery stage: alpha for limited prototype testing, private beta for invited users, public beta for wider real users before live, and no phase banner once the service is live." ], "uiExamples": { "good": [ "A private beta benefits service shows a Beta tag directly below service navigation with Help us improve this service and a feedback link that preserves the current route.", "An alpha prototype shown to invited research participants labels the service Alpha and links to a feedback form about the prototype.", "After passing live assessment, the header no longer shows a beta banner and the feedback route moves to ordinary footer and satisfaction mechanisms." ], "bad": [ "A bright sticky Beta pill floats over the form submit button and competes with validation.", "A service outage is announced only through a beta banner, so users miss the current operational problem.", "A production service keeps Beta forever because nobody owns phase removal." ] }, "uxExamples": { "good": [ "A user in public beta sees the service is still improving, reports a problem from the current page, and returns to the same application step.", "A team switches from private beta to public beta only after assessment and updates the banner copy to reflect wider access.", "An alpha research participant understands they are testing a prototype and does not treat the service as a public channel." ], "bad": [ "Users give feedback but the link drops them on a generic contact page with no route context.", "A beta banner is hidden after the first visit, so deep-linked users miss the service maturity signal.", "A live service retains a stale Beta label and users assume important functionality may still be experimental." ] }, "problemContext": [ "The service is in alpha, private beta, public beta, or another clearly governed pre-live phase.", "Users may enter the service through deep links and need the phase signal before reading page-specific content.", "The team needs to collect on-page feedback about the developing service without interrupting the task.", "The service may have service navigation, a GOV.UK-style header, ordinary broad banners, notification banners, site alerts, and footer feedback routes that must remain semantically separate." ], "selectionRules": [ "Choose phase / beta banner when the whole service is in alpha, private beta, or public beta and users need a service-wide maturity signal.", "Use Alpha when the service is a limited prototype or experiment used to test risky assumptions and is not publicly available as a production service.", "Use Beta for private or public beta: invited users first, then wider access after assessment when the team is preparing for live.", "Remove the phase banner when the service passes live assessment or no longer needs a pre-live maturity label.", "Place the banner directly after service navigation or the primary header so it qualifies the service before page content.", "Keep the feedback link short, route-aware, and able to return users to the page they were on.", "Use banner for broad operational context such as maintenance or rollout, not maturity phase.", "Use notification banner for one page-flow notice before the H1, not a service-wide phase marker.", "Use site alert for urgent public status or servicewide disruption that must override normal maturity context.", "Do not make the phase banner sticky, dismissible, modal, or visually dominant enough to obscure forms and current-task messages." ], "requiredStates": [ "No phase banner state for live or phase-not-applicable services.", "Alpha state for limited prototype or research-only service.", "Private beta state for invited users and controlled rollout.", "Public beta state for wider access before live.", "Feedback link state that preserves current page or step context.", "Route persistence state where the same phase banner appears on every service page.", "Transition state when alpha changes to beta, private beta changes to public beta, or beta changes to live.", "Coexistence state with service navigation, ordinary banner, notification banner, or site alert without semantic conflict." ], "interactionContract": [ "The phase banner appears consistently across all pages in the service while the phase applies.", "The tag text, service phase, access model, and feedback copy stay synchronized with delivery status.", "Activating the feedback link opens a feedback route or email that knows the current page, then lets users return without losing progress.", "The banner does not dismiss permanently because users can arrive on any route and still need phase context.", "The phase banner does not replace urgent alerts, form validation, operational outage notices, or cookie consent controls.", "When the service changes phase, the old phase banner is removed or updated in the same release that changes access and feedback handling." ], "implementationChecklist": [ "Confirm the service phase, access model, assessment state, and owner before publishing the banner.", "Place the phase banner in the header area directly after service navigation, or after the primary header when service navigation is absent.", "Write copy that says this is a new or developing service and invites feedback without over-explaining agile delivery.", "Pass current route, service step, locale, and version metadata to the feedback form where appropriate.", "Keep feedback safe for in-progress tasks by preserving drafts, returning to the same step, or opening in a way that does not lose state.", "Define removal rules for moving from alpha to beta, private beta to public beta, public beta to live, and service retirement.", "Test deep links, mobile header wrapping, keyboard order, screen-reader reading order, feedback return flow, and coexistence with urgent site alerts." ], "commonMisuses": [ "Using Beta as a decorative badge for a feature rather than the service phase.", "Leaving a stale Beta banner on a live service.", "Showing an alpha service to the public as if it were production ready.", "Putting phase copy in a sticky overlay, modal, toast, notification banner, or footer-only link.", "Using the phase banner for outage, maintenance, validation, deadline, cookie, or account-status messages.", "Making feedback open a generic contact route that loses the current page context.", "Letting the phase banner disappear after dismissal, so deep-linked users miss the maturity signal." ], "critiqueQuestions": [ "What phase is the whole service actually in, and who owns changing that label?", "Is this an alpha prototype, private beta, public beta, live service, or feature-level experiment?", "Can users give feedback from the current page without losing their place?", "Should this be a phase banner, broad banner, notification banner, site alert, service navigation, tag, or feedback link?", "What event removes or changes this banner?", "Does the banner appear consistently on deep-linked pages, mobile, and routes with service navigation?" ], "relatedPatterns": [ "banner", "notification-banner", "site-alert", "service-navigation", "header" ], "comparisons": [ "phase-beta-banner-vs-banner-vs-notification-banner-vs-site-alert" ], "sourceIds": [ "govuk-phase-banner-component", "govuk-alpha-phase-guidance", "govuk-beta-phase-guidance", "govuk-measuring-user-satisfaction" ] }, { "id": "phone-number-entry", "completionStatus": "complete", "name": "Phone number entry", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Callable telephone contact capture field", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Phone numbers are contact identifiers with regional formats, leading zeros, plus signs, extensions, SMS capability limits, shared-device privacy risks, and accessibility constraints, so treating them as simple numbers can block contact or harm users.", "solution": "Use a telephone-specific field that states why and what type of number is needed, accepts familiar formatting, preserves display values, validates enough to prevent obvious errors, stores a dialable canonical value separately, offers other contact methods, reviews the value before use, and confirms access only for flows that require it.", "uiGuidance": [ "Render phone entry as a labelled single-line field with number type in the label or hint, purpose and contact-timing text, type tel, autocomplete tel, field-specific errors, and review of both the user's displayed number and any dialable backend value.", "Keep the typed value familiar and editable; avoid one-shape masks, numeric spinboxes, silent international reformatting, or SMS-only controls unless the product has designed the matching exception paths." ], "uxGuidance": [ "Use phone number entry when the product genuinely needs to call, text, verify, route, or recover contact with a user through a phone number.", "Respect that not everyone has or can use a phone by explaining why the number is needed, allowing familiar local or international formatting, preserving meaningful characters, offering other contact routes, and confirming access only when the phone itself is part of the assurance requirement." ], "uiExamples": { "good": [ "An appointment service asks for UK mobile or international phone number, says it will call only if the appointment changes, uses type tel and autocomplete tel, and shows the number for review before saving.", "A support form accepts +44 808 157 0192 and 020 7946 0018 ext 204, keeps the user's spacing visible, and records the dialable value separately." ], "bad": [ "A form stores phone as a number, removes the leading zero from 07700 900 982, and offers no way to correct the stored value.", "A sign-in flow accepts only a mobile SMS code even when the user entered a landline, shared phone, or cannot access texts." ] }, "uxExamples": { "good": [ "A user pastes 07700 900 982, sees it preserved, reviews that calls may go to that number, and can choose email instead.", "A user enters +44 808 157 0192, receives a format-specific error only if the number is too short, and is not forced into a domestic mask." ], "bad": [ "A user with an international number cannot type the plus sign because the field uses type number.", "A user enters an extension for a desk phone, but validation strips it and the organization later calls the wrong line." ] }, "problemContext": [ "The service may need a phone number for appointment changes, emergency contact, support callbacks, account recovery, SMS codes, delivery calls, two-way contact, or official records.", "Users may have mobile, landline, VoIP, shared, work, international, relay, extension-based, temporary, or no usable phone access.", "Phone-number formats vary by country and may include leading zeros, plus signs, spaces, parentheses, hyphens, extensions, short codes, and local dialing conventions.", "A callable number, SMS-capable number, reachable person, and phone-access-verified number are separate states.", "Phone contact can expose privacy, cost, accessibility, and safety concerns when the service calls or texts without clear consent." ], "selectionRules": [ "Choose phone number entry when the product genuinely needs a telephone route for calls, SMS messages, identity recovery, service contact, delivery coordination, support callbacks, or account verification.", "Do not collect a phone number merely because it is customary; offer another contact route when the user can complete the task without phone contact.", "State whether the field accepts UK, international, mobile, landline, SMS-capable, extension-bearing, or emergency contact numbers.", "Explain why the organization may call or text and when that contact may happen.", "Use type tel and autocomplete tel for one complete phone number, and use component autocomplete tokens only when the design deliberately splits the number into parts.", "Do not use type number, because phone numbers are identifiers and may need leading zeros, plus signs, spaces, parentheses, or extensions.", "Allow paste and familiar local or international formatting, then normalize only for backend routing while keeping the user's displayed value reviewable.", "Avoid input masks unless the accepted number format is narrow, domestic, and proven to exclude international numbers, extensions, and other valid exceptions.", "Validate missing values, too few digits, unsupported country codes, unsupported SMS capability, and extension rules with specific messages next to the field.", "Do not silently rewrite a local number into an international format in the editable field; if a canonical value is stored, show it in review or developer-facing payloads.", "Show the number and contact method on review before saving, calling, texting, or sending a code.", "Use phone or SMS confirmation only when access to that phone must be proven, and include resend, change-number, and alternative-contact paths." ], "requiredStates": [ "Initial state with label naming the needed number type, purpose hint, type tel, autocomplete tel, and contact-choice wording.", "Focused state with telephone keyboard support and normal typing, paste, selection, undo, and correction behavior.", "Familiar-format state preserving spaces, parentheses, hyphens, leading zero, plus sign, and country code in the displayed value.", "International number state accepting plus and country code without a domestic mask.", "Extension state keeping extension or desk-routing instructions separate from the main dialable number.", "Missing required number state with a field-specific error and alternate contact route if phone is not essential.", "Too-short or malformed number state with examples that match the accepted number type.", "Unsupported SMS-capable state when the flow needs text messages but the number or preference may only support voice calls.", "No phone or cannot use phone state that offers email, post, relay, support contact, or manual assistance.", "Reviewed number state showing what will be called or texted and how to change it.", "Confirmation pending state when a code or link has been sent to prove phone access.", "Verified phone access state recorded separately from syntactic validity and dialability." ], "interactionContract": [ "Users can type, paste, autofill, edit, select, undo, and correct the phone value through native input behavior.", "Submitting an empty or malformed number preserves the typed value and places the correction next to the field or in a linked summary.", "The interface preserves the user's displayed format while the backend derives a separate canonical dialable value when needed.", "Changing the accepted country, contact method, or SMS requirement updates labels, hints, validation, and review copy together.", "Phone entry does not force SMS verification unless the service requires phone access proof and offers change-number, resend, and alternative-contact recovery.", "Review states show the exact value and intended use before phone contact, SMS code, callback, or account recovery is triggered.", "The backend treats format validity, dialability, SMS capability, ownership, and verified access as separate states." ], "implementationChecklist": [ "Decide whether the service needs any phone number, which number types are accepted, and which alternatives are allowed before designing the field.", "Use a native input with type tel, autocomplete tel, a visible label, purpose hint, and aria-describedby for hint, error, and status text.", "Use autocomplete component tokens such as tel-country-code, tel-national, tel-area-code, tel-local, or tel-extension only for intentional split-number designs.", "Preserve leading zeros, plus signs, spaces, hyphens, parentheses, and extension markers in the displayed value.", "Normalize a separate canonical value for backend telephony systems, using international rules such as E.164 only when country context is available.", "Validate on client and server for empty value, too few digits, impossible country code, unsupported extension, and SMS-capability mismatch without rejecting valid familiar formatting.", "Avoid masks and type number; test pasted contact-card values, international numbers, shared phones, landlines, relay numbers, extensions, and users with no phone.", "Provide review, change-number, resend, timeout, and alternative-contact recovery paths for confirmation-code flows.", "Audit privacy, consent, cost, and safety copy for calls and texts, especially when phone contact may reveal sensitive service use." ], "commonMisuses": [ "Using type number and losing leading zeros or plus signs.", "Hard-coding a domestic mask that blocks international numbers or extensions.", "Collecting phone numbers without a genuine service need.", "Failing to explain why the organization may call or text.", "Forcing SMS verification for users with landlines, shared phones, inaccessible devices, or no phone.", "Silently reformatting numbers so users do not recognize what they entered.", "Rejecting pasted values because they include spaces, parentheses, hyphens, or extension text.", "Treating a syntactically plausible number as proof that the user can receive calls or texts." ], "critiqueQuestions": [ "Why does this service need a phone number, and can users choose another contact method?", "Does the label say whether the service needs UK, international, mobile, landline, SMS-capable, or extension-bearing numbers?", "Does the field use type tel and autocomplete tel instead of type number?", "Can users paste and review a number with spaces, plus sign, leading zero, or extension?", "Is the product validating a phone shape, proving dialability, proving SMS capability, or proving access to the device?", "What happens when a user cannot receive SMS or cannot use a phone safely?" ], "relatedPatterns": [ "text-input", "input-mask", "inline-validation", "error-summary", "review-before-submit", "email-address-entry" ], "comparisons": [ "phone-number-entry-vs-text-input-vs-input-mask-vs-inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-phone-numbers-pattern", "ons-phone-numbers-pattern", "mdn-input-tel", "whatwg-input-tel", "mdn-html-autocomplete-tel", "itu-e164-numbering-plan" ] }, { "id": "pinned-items", "completionStatus": "complete", "name": "Pinned items", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "Deliberate user or owner-selected items kept in a stable prominent position", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users repeatedly need a few important items to stay easy to reach or visible to an audience, but automatic recency, broad favorites, and search results move those items around or hide whether prominence is personal, shared, or public.", "solution": "Provide a bounded pinned-items area with explicit pin and unpin controls, stable order, item identity, pin scope, reorder or replace paths, limit handling, permission states, and recovery messaging that does not delete the underlying item.", "uiGuidance": [ "Render pinned items in a clearly labelled section, top zone, or fixed order with item identity, type, owner or scope, pin state, and an unpin path visible near each item.", "When users can edit pins, show pin limit, order controls, add or replace choices, policy-locked pins, and whether the pin is personal, team, public profile, or shared workspace state." ], "uxGuidance": [ "Use pinned items when users or workspace owners deliberately keep a small set of high-priority objects, files, links, repositories, records, or widgets easy to return to.", "Keep pinned items separate from recently viewed, favorites, saved views, subscriptions, and recommendations because a pin changes placement or prominence rather than history, liking, saved criteria, or future update delivery." ], "uiExamples": { "good": [ "A document library has a Pinned section at the top with three highlighted files, each showing file name, type, modified date, owner, Move left, Move right, and Unpin actions.", "A developer profile lets the owner choose up to six repositories or gists to pin, previews the public Pinned section, and distinguishes public profile pins from private favorites." ], "bad": [ "A pin icon appears on cards with no selected state, no top section, no limit, and no explanation of whether the pin is personal or public.", "Pinned files, recent files, favorite files, and subscribed files are mixed in one list labelled Important with no way to predict what unpinning affects." ] }, "uxExamples": { "good": [ "A manager pins the Quarterly review folder, moves it before the Benefits checklist, sees the three-item limit, and can unpin it without deleting the folder.", "A profile owner selects public projects to pin, previews how visitors will see them, and replaces a stale pinned repository with a newer gist." ], "bad": [ "A user unpins a file and thinks it was deleted because the item disappears with no status message or recovery path.", "A team pin can be reordered by anyone, so shared navigation changes unexpectedly for every teammate." ] }, "problemContext": [ "The product has many revisitable objects such as files, folders, repositories, gists, records, reports, channels, dashboards, or project links.", "Users or owners need a small set to remain visible even as recents, search results, or activity order changes.", "Pinned state may be personal, team-owned, public-profile, admin-managed, or policy-locked.", "A pin may control placement in a list, a top section, a profile showcase, a sidebar, a workspace home, or a document library.", "Pinned items can become deleted, moved, inaccessible, stale, over limit, duplicated, or controlled by someone else." ], "selectionRules": [ "Choose pinned items when the user intentionally keeps a small set of known objects in a stable prominent position.", "Use recently viewed when the list should be automatic personal history ordered by what the user opened most recently.", "Use favorites when the user marks affinity or saved preference without necessarily changing item placement or order.", "Use saved view when the saved object is a reusable presentation or criteria state for one data surface.", "Use follow / subscribe when the user's intent is future update delivery rather than quick return access.", "Use custom dashboard when users arrange multiple widgets on a canvas rather than pinning individual objects or shortcuts.", "Expose whether a pin is personal, shared, public, admin-managed, or inherited before users add, remove, or reorder it.", "Cap pinned items to preserve scan speed and provide replace or reorder choices when the cap is reached.", "Keep unpin distinct from delete, archive, hide, unfavorite, unsubscribe, and remove-from-recent-history actions.", "Avoid pinned items when the item set is dynamic, unknown, recommended by an algorithm, or too large to remain meaningfully prominent." ], "requiredStates": [ "No pinned items state with a path to pin an eligible item.", "Pinned section with item identity, type, scope, position, and unpin controls.", "Pin available, pinned, unpin pending, unpinned, reorder, and replace-at-limit states.", "Personal pin, shared pin, public profile pin, inherited pin, and policy-locked pin states.", "Pinned item deleted, moved, permission-lost, stale, duplicate, and inaccessible states.", "Mobile or narrow-screen state where pinned identity, order, and unpin actions remain reachable." ], "interactionContract": [ "Pinning creates a durable placement or prominence record for the selected item without duplicating or changing the underlying item.", "Unpinning removes only the pin relationship and leaves the underlying item, favorite state, recent history, and subscriptions intact.", "Pinned items stay in the declared section or order until the user, owner, or policy changes them.", "Reordering pinned items updates visible order, keyboard order, and mobile order together.", "When the pin limit is reached, the UI asks users to unpin, replace, or reorder instead of silently dropping an existing pin.", "Shared or public pins require ownership, permission, and audience cues before the pin is changed.", "Deleted, moved, or permission-lost pinned items remain explainable with remove, replace, or request-access paths.", "Pin state is announced and reversible from the item context and from the pinned list." ], "implementationChecklist": [ "Define the pin model with item ID, item type, owner, scope, position, pinned by, pinned time, policy lock, and visibility audience.", "Separate pin state from favorite state, recent history, saved view criteria, subscription state, and item deletion.", "Show pin and unpin controls with accessible pressed state or status text wherever pinning is available.", "Provide move earlier, move later, replace, unpin, restore, and limit-reached handling for pinned sections.", "Validate permissions and visibility before exposing shared, team, public profile, or admin-managed pins.", "Refresh pinned item metadata and mark deleted, moved, permission-lost, stale, or unavailable items before navigation.", "Test keyboard reordering, mobile stacking, long names, duplicate item names, pin limit, failed pin saves, and shared-scope conflicts." ], "commonMisuses": [ "Using a pin icon as a favorite without changing placement or explaining selected state.", "Mixing pinned items with automatic recents, favorites, saved searches, subscriptions, and recommendations in one ambiguous list.", "Letting unpin delete or hide the underlying item.", "Allowing unlimited pins until the pinned section becomes another noisy list.", "Changing shared or public pins without owner, audience, permission, or rollback cues.", "Providing drag-only reorder with no keyboard move controls.", "Letting stale or inaccessible pinned items become dead links." ], "critiqueQuestions": [ "What placement, order, or audience changes when this item is pinned?", "Is the pin personal, shared, public, inherited, admin-managed, or policy locked?", "Can users unpin without deleting, unfavoriting, unsubscribing, or removing recent history?", "What is the maximum useful number of pinned items for this surface?", "How can users reorder pins by keyboard and understand mobile order?", "What happens when a pinned item is deleted, moved, renamed, archived, or no longer accessible?" ], "relatedPatterns": [ "recently-viewed", "related-links", "saved-view", "follow-subscribe", "list-view", "collection", "custom-dashboard" ], "comparisons": [ "pinned-items-vs-favorites-vs-recently-viewed-vs-saved-view" ], "sourceIds": [ "microsoft-office-pin-frequently-used-files", "github-profile-pinning-items", "sharepoint-highlight-document-library-pin", "microsoft-office-recent-files" ] }, { "id": "popover", "completionStatus": "complete", "name": "Popover", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Small anchored contextual overlay", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need extra local context or a small set of nearby controls, but interrupting the page with a modal or hiding the content behind hover-only hints makes the task slower and less reliable.", "solution": "Open a small anchored popover from a clear trigger, keep the content brief and local, place it near the anchor with collision handling, allow predictable dismissal, and restore focus to the invoking control or local result.", "uiGuidance": [ "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.", "Keep the layer small enough to remain local: brief copy, a few choices, light controls, optional close action, and placement that flips or shifts before it disconnects from the anchor." ], "uxGuidance": [ "Use a popover when users need local context, clarification, or a small edit without losing their place in the page.", "Make opening, light dismissal, Escape, outside click, anchor scrolling, focus order, and focus return predictable so the surface feels contextual rather than interruptive." ], "uiExamples": { "good": [ "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.", "A billing plan marker opens a short contextual popover with an explanation, one Learn more link, and placement that shifts away from the viewport edge." ], "bad": [ "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 hover-only popover contains required instructions and a form field that touch and keyboard users cannot reliably reach." ] }, "uxExamples": { "good": [ "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.", "Pressing Escape or clicking outside closes a clean popover without changing the task, while reopening preserves the user's current page context." ], "bad": [ "The user scrolls and the popover stays in the old position, so it appears to describe the wrong field.", "A popover is used for a multi-step workflow, then outside click closes it and loses partially entered data." ] }, "problemContext": [ "A field, row, map pin, chart mark, term, or object needs explanation or light editing without navigating away.", "The content is more than a tooltip label but smaller than a dialog, drawer, sheet, or page.", "Users should keep seeing and using the surrounding page unless they are interacting directly inside the popover.", "The implementation can maintain anchor position, focus order, outside dismissal, Escape behavior, and screen reader relationships." ], "selectionRules": [ "Choose popover when a local trigger needs a compact contextual layer with short copy, a few actions, or light controls that belong to that exact anchor.", "Use menu button when the popup is primarily a command list and should use menu item roles, active-item movement, and command activation behavior.", "Use modal dialog when users must complete or cancel a compact blocking task before returning to the page.", "Use sheet when the surface needs more room, sticky actions, adaptive sizing, or protected dirty-state dismissal.", "Use disclosure details when the content can stay inline and should remain part of the page flow after expansion.", "Use inline text, validation, or an inline message for essential instructions that must not disappear on light dismissal.", "Use tooltip-style help only for short noninteractive hints; do not hide required instructions, form controls, or complex content in hover-only behavior.", "Use a full page when the interaction needs routing, long reading, saved progress, or multiple steps." ], "requiredStates": [ "Closed trigger state with visible label, icon name, or field relationship.", "Open anchored state with position tied to the trigger, selected text, field, or object.", "Collision state where the surface flips, shifts, or changes side before it clips or disconnects.", "Interactive focus state when controls inside the popover are reachable after the trigger in the keyboard order.", "Clean light-dismiss state through outside click, Escape, close button, or another trigger.", "Applied state where a local choice updates the anchor value and closes the popover.", "Anchor changed or scrolled state where the popover follows, closes, or clearly reanchors.", "Small-screen state where the same contract still works without becoming an unlabeled modal or hidden sheet." ], "interactionContract": [ "The trigger name and visible placement make clear which object or field the popover belongs to.", "Opening from keyboard moves focus to the first meaningful control inside the popover or keeps focus on the trigger only when the content is purely informational and still reachable.", "Focusable content inside the popover follows the invoker in the tab order and does not trap focus like a modal dialog.", "Escape closes the popover and returns focus to the trigger or local result.", "Outside click or another local trigger closes a clean auto popover without applying a hidden action.", "A manual popover has an explicit close path and a reason to stay open after outside interaction.", "Placement updates with scrolling, viewport edges, zoom, and responsive changes so the surface remains visually tied to its anchor.", "If a control inside the popover changes the anchor value, the update is visible at the anchor after close." ], "implementationChecklist": [ "Identify the exact anchor element and name the relationship in trigger text, aria attributes, or visible copy.", "Choose auto, manual, or hint behavior based on whether light dismissal and one-at-a-time behavior match the task.", "Keep content brief and remove unrelated navigation, long forms, tables, and multi-step workflows.", "Implement Escape, outside click, close button when needed, opener toggling, and focus return consistently.", "Put popover controls in a predictable keyboard order near the invoker and avoid modal focus traps for nonmodal popovers.", "Handle placement collision, scroll containers, clipping, portals, zoom, and small screens without detaching from the anchor.", "Use semantics that match content: ordinary buttons and links for rich popovers, menu roles only for menu behavior, and dialog semantics only for truly dialog-like surfaces.", "Test keyboard, touch, screen readers, high zoom, viewport edges, nested overlays, and anchor changes." ], "commonMisuses": [ "Using a popover as a hidden modal, drawer, sheet, command menu, or full workflow.", "Showing required instructions only in a hover-only layer that cannot be opened or kept open on touch and keyboard.", "Letting the popover appear detached from its trigger after scrolling, collision, or portal rendering.", "Putting long forms or unsaved edits in a surface that can light-dismiss without review.", "Mixing menu roles with arbitrary buttons, links, inputs, and explanatory content.", "Opening several overlapping popovers at once with no ownership, close order, or focus return.", "Failing to restore focus to the invoker after Escape, close, outside click, or applied selection." ], "critiqueQuestions": [ "What exact field, object, or selection anchors this popover?", "Is the content local and brief enough to stay nonmodal?", "Does the surface need command-menu keyboard behavior, dialog modality, a sheet, or inline disclosure instead?", "What happens on Escape, outside click, anchor scroll, viewport collision, and trigger reactivation?", "Where does focus move on open, inside the popover, after applying a choice, and after dismissal?", "Is any required instruction hidden in a dismissible or hover-only layer?" ], "relatedPatterns": [ "menu-button", "modal-dialog", "sheet", "disclosure-details", "inline-message" ], "comparisons": [ "popover-vs-menu-button-vs-modal-dialog-vs-sheet" ], "sourceIds": [ "mdn-popover-api-using", "mdn-popover-attribute", "open-ui-popover-explainer", "fluent-popover-component" ] }, { "id": "preference-center", "completionStatus": "complete", "name": "Preference center", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "Persistent hub for communication, consent, topic, privacy, language, and personalization choices", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Communication, consent, personalization, topic, language, and privacy choices become untrustworthy when they are scattered across email footers, cookie banners, account settings, notification pages, CRM records, and policy-managed systems.", "solution": "Provide a persistent preference center that inventories user-facing preference categories, shows current effective status and ownership, supports granular opt-in and opt-out choices, preserves required messages, handles managed or conflicting values, and confirms save or withdrawal outcomes.", "uiGuidance": [ "Render a preference center as a returnable hub with categories for communications, channels, topics or interests, notification delivery, privacy and data sharing, cookie or tracking consent, personalization, language or locale, required messages, managed values, source-of-truth status, and save feedback.", "Separate preference center from general settings, notification preferences, cookie banner, and notification center by showing that the user is managing the choices an organization must honor across contact, consent, personalization, and subscription systems." ], "uxGuidance": [ "Use a preference center when users need durable control over what they receive, which channels may be used, which topics they want, which consent purposes are active, how personalization uses their data, and which choices cannot be disabled.", "Make the effective result clear before and after save: what changes now, what stays required, which rows are policy-managed, which external system owns the value, and where users can withdraw consent or unsubscribe." ], "uiExamples": { "good": [ "A customer account preference center shows Email, SMS, Push, Topics, Cookies, Data sharing, Language, and Required service messages, each with current status, scope, and last saved time.", "A consent preference page groups analytics, ads, personalization, newsletter topics, and product updates, with a saved summary and a clear withdraw-all route where permitted." ], "bad": [ "A single Receive updates switch hides whether it controls marketing email, SMS, push, product notices, analytics consent, or service messages.", "An unsubscribe page removes the user from one newsletter but still labels all preferences as off and provides no route to change language, topics, cookies, or data sharing." ] }, "uxExamples": { "good": [ "A user turns off promotional email, keeps outage SMS and account security email, changes language to Spanish, withdraws ad personalization, and sees which transactional messages remain required.", "A subscriber chooses Product releases and Learning topics, moves Sales offers to monthly email only, and sees that regional privacy choices are synced from the account profile." ], "bad": [ "A user declines analytics in a cookie banner but later cannot find the preference center needed to withdraw personalization consent after signing in.", "A user saves SMS opt-out and the UI confirms success, but a CRM sync restores SMS marketing because the preference center never explained the conflict." ] }, "problemContext": [ "Users may control email subscriptions, SMS, push, newsletter topics, product interests, notification delivery, cookie purposes, analytics consent, ad personalization, data sharing, language, locale, profile details, and contact frequency.", "Some messages cannot be disabled because they are transactional, legal, security, billing, operational, or required by account ownership.", "Preference data may sync between marketing automation, CRM, identity, consent-management, notification, analytics, and account-profile systems.", "A user's apparent choice can be constrained by region, product plan, organization policy, age or consent rules, administrator ownership, account status, or pending verification.", "Preference changes often originate from email links, in-product account pages, cookie settings links, mobile settings, privacy requests, or customer support actions." ], "selectionRules": [ "Choose preference center when the surface combines communication subscriptions, channel opt-ins, topic interests, consent purposes, personalization choices, privacy/data-sharing controls, and locale or contact preferences.", "Use settings management when the user is changing broad app, account, workspace, integration, display, or product configuration beyond preference and consent choices.", "Use notification preferences when the work is only future notification delivery across event types, channels, devices, frequency, quiet time, digest, and preview behavior.", "Use cookie banner or consent prompt for first-run or first-visit consent collection; link to a preference center for later review, withdrawal, and granular changes.", "Use notification center when the problem is reviewing delivered notifications rather than configuring future communication and consent preferences.", "Expose required, transactional, security, billing, or legal messages separately from optional marketing and engagement communications.", "Show the current effective value, source system, scope, region, and save model for each category before users edit it.", "Provide a clear withdraw, unsubscribe, restore defaults, or disable-category path only for choices the organization can actually honor." ], "requiredStates": [ "Overview with preference categories and current effective status", "Communication channel opt-in and opt-out state for email, SMS, push, or in-app contact", "Topic or interest preference state", "Notification delivery summary state", "Privacy, data sharing, consent, cookie, analytics, and personalization controls state", "Language, locale, or region preference state", "Legal-required or transactional message cannot-opt-out state", "Policy-managed, admin-managed, unavailable, or region-restricted preference state", "Unsaved changes, saved confirmation, save failed, and preserved-draft state", "Withdraw consent, unsubscribe all, disable category, or restore defaults confirmation state", "External source conflict or sync-pending state", "Condensed mobile category navigation state" ], "interactionContract": [ "Opening the preference center shows current effective choices, not blank defaults or only local cached values.", "Each category names what it controls, which channels or purposes are included, which systems consume it, and whether the change is immediate or waits for Save.", "Changing optional communications does not imply required service, security, billing, legal, or transactional messages are disabled.", "Consent, cookie, analytics, and personalization controls include a visible route to withdraw or revise choices where policy allows.", "Managed, unavailable, region-restricted, or externally owned values explain the owning layer and avoid showing false saved success.", "Saving confirms changed categories, preserves unsaved work on failure, and exposes any sync conflict or pending verification.", "Restoring defaults or disabling a broad category lists exactly which preferences will change before the user confirms." ], "implementationChecklist": [ "Inventory preference categories, channels, topics, consent purposes, language choices, required communications, legal constraints, and owner systems before designing the UI.", "Model communication preferences separately from notification inbox records, cookie banner display state, general app settings, profile fields, and administrator policy.", "Define the source of truth for each value, including CRM, marketing platform, identity profile, consent manager, account service, notification service, and regional policy.", "Represent required messages, managed rows, unavailable channels, pending verification, region restrictions, and conflicting sync values without pretending the user changed them.", "Provide granular save feedback, withdraw or unsubscribe confirmation, restore behavior, failed-save recovery, audit timestamps, and mobile category navigation.", "Test email-link entry, signed-in account entry, cookie-settings entry, expired token recovery, long translated labels, high zoom, keyboard navigation, screen readers, and cross-system sync delays.", "Log preference changes with category, old value, new value, source, timestamp, actor, region, and consent or unsubscribe basis where the product has compliance obligations." ], "commonMisuses": [ "Using one master preference switch for communication, privacy, cookies, topics, and required messages.", "Letting marketing opt-out imply that security, billing, transactional, or legal notices are disabled.", "Collecting cookie or analytics consent once and failing to provide a durable place to review or withdraw it.", "Scattering email, SMS, push, topics, language, privacy, and data sharing across unrelated pages with contradictory labels.", "Showing saved success when an administrator policy, CRM sync, region rule, or verification requirement prevents the change.", "Burying unsubscribe-all, withdraw consent, or restore defaults behind ambiguous destructive actions.", "Failing to preserve edited choices when one category fails to save.", "Treating a preference center as a marketing-only form when users also need account, privacy, consent, language, and required-message clarity." ], "critiqueQuestions": [ "Which preferences are communication, consent, personalization, privacy/data sharing, topic, language, notification, or required-message choices?", "What exact channels, systems, audiences, regions, and future messages are affected by this change?", "Can the user tell what remains required after unsubscribe, withdraw, disable, or master-off actions?", "Which values are owned by CRM, identity, marketing automation, consent management, notification service, device permission, region rule, or administrator policy?", "How does the surface recover from failed save, expired preference-link token, sync conflict, or unsupported language?", "Is the mobile experience still category-based and understandable without hiding consent scope?" ], "relatedPatterns": [ "settings-management", "notification-preferences", "cookie-banner", "notification-center", "toggle-switch", "permission-denied-state", "permission-recovery", "account-creation" ], "comparisons": [ "preference-center-vs-settings-management-vs-notification-preferences-vs-cookie-banner" ], "sourceIds": [ "salesforce-marketing-cloud-custom-preference-center", "mailchimp-preferences-center", "braze-preference-center-endpoints", "klaviyo-consent-pages", "onetrust-preference-center-schema", "onetrust-cookie-preference-center-config" ] }, { "id": "presence", "completionStatus": "complete", "name": "Presence", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Person or group availability signal with status label, recency, source, privacy boundary, and action-aware affordances", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Collaboration becomes disruptive or misleading when availability is represented as an unexplained dot, stale activity, hidden privacy state, or surveillance-like signal instead of a contextual, fresh, labelled, and action-aware presence indicator.", "solution": "Provide presence badges and co-viewing summaries with explicit status labels, availability hierarchy, recency, source, manual or automatic origin, privacy boundary, unknown and stale states, and action behavior that respects busy, do-not-disturb, offline, and restricted visibility.", "uiGuidance": [ "Render presence as a labelled availability signal near the person, team, object, or conversation it describes; pair color, shape, text, timestamp, and source so users can distinguish active, away, busy, do not disturb, offline, unknown, viewing, and recently active states.", "Show presence controls and explanations where users act on the signal: status menu, status duration, last updated time, working-hours note, privacy restriction, stale value, co-viewer list, and action changes such as call disabled, message allowed, or notify later." ], "uxGuidance": [ "Use presence when users need to decide whether to interrupt, wait, route work, join a session, assign follow-up, or understand who is currently viewing or recently active in a shared space.", "Treat presence as a transient, privacy-bounded signal, not a proof of productivity or accountability; expose freshness, source, manual overrides, notification effects, and privacy limits before users rely on it." ], "uiExamples": { "good": [ "A reviewer row shows Priya as Busy in a meeting until 14:30, disables Call, keeps Message available, and offers Notify when available.", "A document header shows three current viewers, one anonymous viewer, last updated recency, and a privacy note explaining that external viewer activity is hidden." ], "bad": [ "A green dot appears next to every name with no label, timestamp, or meaning.", "A stale active badge remains after the user has gone offline and the call button still looks primary." ] }, "uxExamples": { "good": [ "A user sees that Dana is in Do not disturb, sends a message without a banner interruption, and schedules a reminder to follow up when Dana is available.", "A file owner sees who has viewed the document within the same domain, respects hidden view-history settings, and uses the signal for follow-up rather than audit proof." ], "bad": [ "A manager treats Away as an attendance record even though it came from device inactivity and privacy-limited activity data.", "A co-editing page shows that someone is present but gives no accessible name, role, location, or privacy reason for unknown viewers." ] }, "problemContext": [ "Users are deciding whether to message, call, assign, review, wait, join, follow up, or interpret another person's current availability in a workspace, document, channel, dashboard, issue, or task.", "Presence may be calculated from app activity, device activity, calendar events, active calls, focus time, working hours, manual overrides, notification pause, file views, or current co-viewing sessions.", "The signal may be delayed, stale, privacy-limited, hidden for external users, unknown, or suppressed by user preference, admin setting, domain boundary, or object permission.", "Presence may affect actions such as call routing, notification delivery, assignment timing, follow-up reminders, co-editing awareness, and escalation paths, but it is not automatically an audit record." ], "selectionRules": [ "Choose presence when the user needs a transient availability, co-attendance, last-seen, or active-viewer signal attached to a person, group, file, channel, task, or conversation.", "Use mentions when the task is to address or notify someone inside authored content; mentions can consult presence but they create an attention event rather than display availability.", "Use notification center when the user needs retained inbox triage, unread state, preference controls, and notification history across objects.", "Use activity log when the product must preserve durable evidence of who viewed, changed, routed, or was notified about something.", "Use comments or threaded discussion when the collaboration unit is authored conversation; presence can show who is reading or available but should not replace conversation state.", "Use profile setup for stable identity and work details; presence should only show time-bound state, recency, and availability source.", "Use settings management for configuring status defaults, working hours, privacy visibility, external sharing, and notification behavior.", "Show restricted, unknown, stale, or hidden presence states instead of guessing when privacy, domain, permission, stale sync, or API limits prevent a reliable signal." ], "requiredStates": [ "Available, active, away, busy, in a meeting, in a call, presenting, focusing, do not disturb, out of office, offline, unknown, and hidden states where supported.", "Manual status, automatic status, status duration, status message, working-hours state, paused-notification state, and calendar-derived state.", "Fresh, stale, reconnecting, delayed, last-updated, last-seen, and source-unavailable states.", "Single-person presence, group summary, co-viewer list, anonymous viewer, external viewer hidden, same-domain activity visible, and privacy-restricted states.", "Action-aware states such as call available, call blocked, message allowed, banner suppressed, notify when available, route to next available, and follow-up scheduled.", "Mobile condensed badge, expanded presence detail, tooltip or popover detail, accessible text label, and screen-reader-only state summary.", "Permission denied, external access hidden, user view-history hidden, admin privacy mode enabled, and activity-dashboard-not-audit states.", "Presence conflict, multiple devices, manual override, automatic reset, and presence unknown fallback states." ], "interactionContract": [ "Presence badges identify the person or group, status label, recency, and source in text, not color alone.", "Selecting or focusing a presence indicator reveals more detail such as status message, last updated time, working-hours note, privacy reason, current object viewers, or action options.", "Actions that depend on presence respect do-not-disturb, busy, offline, privacy, and priority rules; they explain whether messages, calls, banners, or routing will behave differently.", "Stale or delayed presence values show last updated time and fallback behavior rather than staying visually equivalent to live status.", "Privacy settings, external access rules, hidden view history, and domain restrictions are honored before showing viewer names, last-seen times, or status details.", "Presence changes update without moving focus, stealing attention, or rewriting user intent; screen-reader users receive concise state changes only when relevant.", "If presence is used for routing, escalation, or assignment, the system records the actual decision event separately from the transient presence value." ], "implementationChecklist": [ "Define presence states, source priority, stale thresholds, privacy boundaries, external sharing rules, status duration, user override behavior, and action implications before drawing badges.", "Design badge, label, expanded detail, co-viewer list, unknown state, hidden state, stale state, and action affordances for desktop, mobile, keyboard, and screen-reader access.", "Map presence to actions such as call, message, notify later, route, assign, join, or wait without assuming every available-looking person can be interrupted.", "Show status freshness and source when the value comes from calendar, device activity, manual override, co-viewing, file activity, or API updates.", "Respect privacy controls for view history, external access, same-domain limits, hidden users, anonymous users, and admin privacy mode.", "Test delayed updates, multiple devices, manual overrides, do-not-disturb, out-of-office, offline fallback, anonymous viewers, hidden activity, and stale API data." ], "commonMisuses": [ "Using only color dots without text labels, source, or recency.", "Treating presence as employee monitoring or audit evidence.", "Leaving stale active states on screen after disconnects or sync failures.", "Ignoring do-not-disturb, busy, call, meeting, or priority rules when offering interruptive actions.", "Showing viewer names or last-seen times across privacy, domain, guest, or external organization boundaries.", "Conflating presence with unread notifications, mentions, assignments, comments, or activity history.", "Hiding unknown or restricted presence and making users think nobody is present.", "Letting presence animations distract from the primary task or cause layout shifts." ], "critiqueQuestions": [ "What exact person, group, file, channel, task, or object does this presence signal describe?", "What status is shown in text, and when was it last updated?", "Is the signal automatic, manual, calendar-derived, device-derived, activity-derived, or co-viewing-derived?", "What privacy setting, external access rule, or permission boundary controls whether the signal is visible?", "Which actions change when the person is busy, in do-not-disturb, offline, away, or unknown?", "Can users tell the difference between live presence, last-seen activity, file view history, and audit history?" ], "relatedPatterns": [ "mentions", "notification-center", "activity-log", "comments", "threaded-discussion", "profile-setup", "settings-management", "permission-denied-state", "sync-state", "offline-state", "feed" ], "comparisons": [ "presence-vs-mentions-vs-notification-center-vs-activity-log" ], "sourceIds": [ "slack-status-availability", "slack-user-presence-status-api", "microsoft-teams-presence-admins", "microsoft-graph-presence-resource", "google-workspace-activity-dashboard", "google-docs-live-edits-accessibility" ] }, { "id": "preview-panel", "completionStatus": "complete", "name": "Preview panel", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Persistent rendered-content preview pane", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Content-heavy workspaces often list many documents, messages, images, videos, or attachments, and users need to inspect the selected content without losing the surrounding collection or opening a full viewer for every item.", "solution": "Provide a persistent preview panel tied to the current selection, render the content body or media with type-appropriate controls, expose blocked and unsupported states, keep source selection visible, and escalate to a full preview route when reading, annotation, or space needs exceed the panel.", "uiGuidance": [ "Render a preview panel as a durable side-by-side region that shows the selected file, message, media, attachment, or document body while keeping the source list, grid, search result, inbox, or asset browser visible.", "Give the preview panel content-fidelity controls that match the media type, such as page navigation, zoom, fit width, play or pause, transcript, alt text, unsupported-file state, safety warning, download, and open full preview." ], "uxGuidance": [ "Use a preview panel when users need to inspect content across several nearby items without repeatedly opening and closing full viewers.", "Keep preview state, selected source item, loading, blocked content, unsupported type, permission loss, zoom, page, and full-preview escalation synchronized so users never act on the wrong file." ], "uiExamples": { "good": [ "A document repository selects Forecast.pdf in the file list and shows page 2 in a right preview panel with page, zoom, fit width, blocked-file, download, and Open full preview controls.", "An inbox keeps the selected email highlighted and shows the message body in a reading pane with attachment previews and a popout route." ], "bad": [ "A side panel titled Preview shows only owner, modified date, and file size when reviewers need to inspect the contract body.", "A preview pane continues rendering Budget.pdf after the selected row changed to Receipt.png." ] }, "uxExamples": { "good": [ "A reviewer arrows through invoice files, the preview updates in place, page and zoom reset only when appropriate, and focus remains in the file list until a preview control is chosen.", "A downloaded file marked risky shows a blocked preview state with the reason, safer choices, and an open-full route instead of rendering active remote content." ], "bad": [ "The first page of a previous PDF stays visible while a new file is still loading, causing the user to approve the wrong attachment.", "Keyboard focus jumps into the preview every time selection changes, making rapid file triage slow and disorienting." ] }, "problemContext": [ "A source region contains selectable content objects such as files, emails, invoices, contracts, images, videos, audio, or attachments.", "Users must compare or triage multiple nearby items quickly while seeing each selected item's rendered body or media.", "A partial preview is useful enough for review, but deep reading, editing, annotation, or sharing can move to a full viewer.", "The product can detect unsupported formats, risky files, permission loss, loading, stale selection, and preview-render failures." ], "selectionRules": [ "Choose preview panel when users need durable rendered content beside a collection, not only metadata about the selected object.", "Use details panel when the main content is structured fields, status, ownership, and activity rather than the document or media body.", "Use hover card when the preview is small, transient, and appears before a navigation decision.", "Use drawer when the surface is temporarily opened by a command and needs a close path and focus movement into it.", "Use full-page or full-screen preview when users need long reading, annotation, page thumbnails, shareable URL state, or large media controls.", "Use object picker with preview when the preview is part of selecting an entity for a form or workflow.", "Do not use a preview panel when the selected content cannot be rendered safely, quickly, or accurately enough to support user decisions.", "Do not use a preview panel as a dumping ground for filters, global navigation, settings, or unrelated actions." ], "requiredStates": [ "No selection state that asks users to choose a file, message, or media item.", "Selected content state with source row highlighted and preview heading naming the same item.", "Loading preview state that hides or clearly labels old content as no longer current.", "Rendered document state with page, zoom, fit, and open-full-preview controls when the type supports them.", "Rendered image, video, audio, or message state with controls appropriate to that content type.", "Unsupported type state with format, reason, and alternate actions such as download or open with an app.", "Blocked or suspicious file state that explains why inline preview is disabled and offers safer choices.", "Permission lost, deleted item, or filtered-away state that clears the rendered content and returns users to selection.", "Narrow viewport state with collapse, resize, or full preview route." ], "interactionContract": [ "Selecting an item updates both the source selection indicator and the preview panel title.", "The preview panel renders the selected item's content body or media, while metadata remains supporting context.", "Keyboard focus stays in the source list, grid, or inbox while users move selection for rapid review.", "Preview controls update only the current selected item and announce changes such as page, zoom, fit, blocked, or open-full state.", "Loading, unsupported, blocked, stale, permission, and deleted states replace the rendered content rather than letting old content appear current.", "The panel offers a route to full preview or full object view when the content needs more space or deeper interaction.", "Download, open with app, and external viewer actions preserve selected-item identity and communicate risk when relevant." ], "implementationChecklist": [ "Define the selected content ID and preview-render lifecycle before painting preview content.", "Show the selected item in the source region and repeat its name, type, and current preview state in the panel.", "Support media-specific controls such as page, zoom, fit, play, transcript, alt text, rotate, or full preview only when they match the selected type.", "Handle loading, unsupported format, blocked file, suspicious source, permission loss, deleted content, filtered-away selection, and render failure.", "Prevent stale previews by clearing or labelling old rendered content during selection changes and load failures.", "Keep focus in the source region during rapid selection movement; move focus into preview controls only after explicit user action.", "Provide collapse, resize, or full preview when the panel cannot keep both source context and content readable.", "Test row selection, keyboard movement, paging, zoom, fit width, blocked preview, unsupported format, resize, and full preview route." ], "commonMisuses": [ "Showing metadata in a preview panel when users need the document, message, or media body.", "Leaving stale rendered content visible after selection changes or preview loading fails.", "Rendering risky downloaded or remote content without a blocked state or warning.", "Using a preview panel for long editing, annotation, or reading workflows that need a full route.", "Stealing focus into the preview on every source-list movement.", "Making the preview too small to read while hiding the full-preview route.", "Mixing preview, filters, navigation, destructive actions, and settings in one side region." ], "critiqueQuestions": [ "Which selected content item owns the rendered preview right now?", "Can users see the selected source item and the preview title at the same time?", "Does the panel render content body or media, or only metadata better suited to a details panel?", "What happens while a new preview is loading, blocked, unsupported, deleted, or denied by permissions?", "Are page, zoom, fit, play, transcript, and full-preview controls present only when the content type needs them?", "How do users reach a full viewer when the panel is too small or the task becomes deep reading or annotation?" ], "relatedPatterns": [ "details-panel", "hover-card", "drawer", "sheet", "popover", "tooltip", "context-menu", "object-picker" ], "comparisons": [ "preview-panel-vs-details-panel-vs-hover-card-vs-drawer" ], "sourceIds": [ "apple-quick-look", "google-drive-view-open-files", "google-drive-file-types-preview", "microsoft-outlook-reading-pane", "microsoft-file-preview-security" ] }, { "id": "privacy-settings", "completionStatus": "complete", "name": "Privacy settings", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Durable privacy-control surface for account, product, device, app-access, activity, visibility, and sharing settings", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Privacy controls become untrustworthy when users cannot find them, cannot see current effective values, cannot distinguish account, device, app, product, consent, cookie, or export boundaries, or receive success states that hide managed policies, unavailable data, legal restrictions, or sync delays.", "solution": "Provide a dedicated privacy settings surface that groups privacy controls by user mental model, shows current data and exposure state, identifies scope and source of truth, handles unavailable and managed values honestly, supports clear changes and revocation, and reports applied, failed, pending, or restricted status.", "uiGuidance": [ "Render privacy settings as a returnable control surface with current effective values, privacy categories, data types, app or service access, account/device/product scope, source of truth, managed or unavailable reasons, last updated status, and save or immediate-apply feedback.", "Separate privacy settings from privacy policy text, cookie banners, consent prompts, notification preferences, data export, delete account, and broad settings pages by showing concrete controls over data collection, saved activity, visibility, personalization, sharing, and app access." ], "uxGuidance": [ "Use privacy settings when users need to inspect and change ongoing privacy posture for saved activity, profile visibility, app access, device permissions, data sharing, ad personalization, location, connected apps, or product privacy dashboards.", "Help users understand exposure and consequences before changing a privacy control: what data changes, where it applies, what remains required, what is managed elsewhere, and what status proves the setting actually changed." ], "uiExamples": { "good": [ "An account privacy dashboard groups Saved activity, Profile visibility, Ad personalization, Connected apps, Location history, Device permissions, and Data deletion, with current values, scope labels, last updated times, and unavailable reasons.", "A mobile privacy settings page lists Camera, Microphone, Contacts, Photos, Bluetooth, and Location access by app, shows which app requested access, and lets users revoke future access with an immediate status." ], "bad": [ "A Privacy page links only to a legal policy and has no controls for activity history, public profile fields, personalization, app access, or data sharing.", "A single Privacy mode switch claims to turn everything off but leaves ad personalization, public profile visibility, connected apps, and activity retention unchanged." ] }, "uxExamples": { "good": [ "A user pauses saved activity, clears search history for a date range, disables ad personalization, hides birthday visibility, revokes a connected app, and sees which values apply immediately versus after sync.", "A parent opens child-account privacy settings, sees high-privacy defaults, reviews app access, and changes profile visibility only after seeing who can view the information." ], "bad": [ "A user turns off location sharing in account privacy settings, but the device-level location permission remains active and the page never explains the split.", "A user withdraws a consent prompt, but privacy settings still show personalization enabled because the source of truth and sync state are hidden." ] }, "problemContext": [ "Users may be controlling saved activity, search history, browsing history, location history, voice recordings, app and service activity, ad personalization, profile visibility, people and sharing, connected apps, device data permissions, diagnostic data, and data dashboard visibility.", "Privacy controls may live at account, device, app, browser, workspace, child account, product, region, or organization-policy scope.", "Some privacy data may be unavailable because the user is signed out, recently cleared data, turned off collection, is too young, is in an unsupported region, uses a managed account, or the product is legally restricted from displaying it.", "Privacy settings may need to hand off to consent prompts, cookie preferences, permission requests, data export, delete account, or privacy request workflows without pretending those are ordinary toggles." ], "selectionRules": [ "Choose privacy settings when the user needs durable controls over ongoing data collection, saved activity, profile visibility, data sharing, personalization, app access, or device privacy permissions.", "Use settings management when privacy is one part of a broader configuration center and the main pattern is general persistent settings organization.", "Use preference center when the work is mainly communication, topics, language, marketing, consent purposes, or required messages across systems.", "Use consent prompt when a specific optional data use needs an affirmative opt-in moment before processing begins.", "Use permission request when an app asks for one runtime or platform capability in context.", "Use data export when the user is downloading or transferring a copy of data rather than changing future collection or exposure.", "Use delete account for account closure and associated data deletion requests, not ordinary privacy setting changes.", "Show account, device, app, product, workspace, region, and managed-organization scope before users change a privacy value.", "Show data categories, current effective value, last saved or synced time, source system, unavailable reason, and consequence of changing the setting.", "Provide high-privacy defaults and age-appropriate explanations for child or sensitive-data contexts where policy requires extra protection." ], "requiredStates": [ "Privacy settings overview with categories and current effective values.", "Saved activity, search history, browsing history, voice, media, or app/service activity controls state.", "Profile visibility and people-sharing state.", "Ad personalization, recommendations, diagnostics, or product improvement data-use state.", "Location, camera, microphone, contacts, photos, Bluetooth, local network, and device permission state.", "Connected app, third-party access, data sharing, or partner access state.", "Consent, cookie, notification, data export, and delete account handoff state with clear boundaries.", "Immediate apply, staged save, pending sync, saved, failed, reset, and restore previous state.", "Unavailable data, recently cleared, collection off, unsupported product, signed-out, region-restricted, too-young, or managed-policy state.", "Child account, high-privacy default, guardian-managed, enterprise-managed, and mobile compact states." ], "interactionContract": [ "Opening privacy settings shows authoritative current values, not blank defaults, marketing copy, or a privacy-policy-only page.", "Every control states what data, visibility, app access, product, device, or account scope it affects before activation.", "Immediate controls show applied, failed, pending sync, unavailable, and reverted states near the changed row.", "Controls owned by consent, cookies, platform permission, organization policy, child guardian, export, or delete workflows link to the owning flow and do not show false local success.", "Clearing or pausing data explains whether existing data is deleted, future collection stops, dashboard display changes, or only personalization use changes.", "Managed, unavailable, too-young, legal, region, or unsupported states explain why the user cannot see or change a value and what route remains.", "Reset or restore affects only the named privacy group and lists the controls that will change before confirmation.", "The page records successful privacy changes with category, scope, source, timestamp, and effective state where compliance or user trust requires it." ], "implementationChecklist": [ "Inventory privacy controls by data category, source system, account/device/product scope, default value, legal basis, age policy, and owner.", "Map overlaps between privacy settings, consent records, cookie controls, platform permissions, notification preferences, data export, delete account, and privacy request workflows.", "Model current value, effective value, source of truth, last saved time, last synced time, unavailable reason, managed policy, and pending status for each row.", "Separate immediate apply controls from controls that require Save, reauthentication, guardian approval, device settings, or external sync.", "Show clear consequences for pause, clear, hide, share, revoke, reset, and personalization changes.", "Test signed out, multiple accounts, child account, managed account, region restriction, recent deletion, collection off, unavailable dashboard data, device permission mismatch, and mobile layout.", "Avoid collecting privacy-setting changes through analytics or session replay in a way that exposes sensitive choices." ], "commonMisuses": [ "Replacing privacy settings with a privacy policy link or legal notice.", "Using one master privacy switch for unrelated collection, sharing, visibility, permissions, personalization, and retention controls.", "Showing a setting as enabled while the platform permission, organization policy, or source-of-truth system disagrees.", "Failing to explain why data cannot be displayed, cleared, changed, or exported.", "Mixing cookie consent, data export, delete account, and privacy settings into one ambiguous action.", "Resetting privacy controls broadly without naming affected data categories.", "Hiding child, region, legal, managed, or enterprise restrictions behind disabled controls.", "Claiming saved success before sync or policy enforcement completes." ], "critiqueQuestions": [ "What exact data category, app access, visibility, or personalization behavior does each privacy setting control?", "What scope owns the value: account, device, app, product, browser, organization, child account, or region?", "Is the displayed value the current effective value or only a local preference draft?", "What data remains collected, retained, visible, or shared after the user turns a control off?", "Where do consent, cookies, permissions, export, and account deletion handoffs begin and end?", "How does the UI explain unavailable dashboard data, recently cleared data, legal restrictions, or managed policy?", "What evidence proves a privacy change was applied, failed, pending, or reverted?" ], "relatedPatterns": [ "settings-management", "preference-center", "consent-prompt", "permission-request", "cookie-banner", "notification-preferences", "data-export", "delete-account", "sensitive-data-reveal", "permission-denied-state" ], "comparisons": [ "privacy-settings-vs-settings-management-vs-preference-center-vs-consent-prompt-vs-permission-request-vs-data-export" ], "sourceIds": [ "google-account-manage-settings", "microsoft-privacy-dashboard", "apple-privacy-location-services-settings", "ico-data-protection-by-design-default" ] }, { "id": "process-list", "completionStatus": "complete", "name": "Process list / step-by-step navigation", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "End-to-end ordered journey guidance with linked tasks", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users trying to complete a broad journey across several pieces of guidance, transactions, or offline actions need a coherent ordered map without mistaking that map for the current form step or page hierarchy.", "solution": "Provide an end-to-end process list with numbered expandable steps, task links, branch and cost information, and a clear standalone overview that explains the journey order while keeping transaction progress and local navigation separate.", "uiGuidance": [ "Present the process as a numbered ordered list of three to ten high-level steps, each with a short parallel action heading and enough supporting text or links to complete that stage.", "Use expandable sections or a clear vertical process layout when steps need task links, conditions, costs, offline actions, or alternative branches; keep the process visually separate from local navigation and transaction buttons." ], "uxGuidance": [ "Use process lists to help users understand an end-to-end journey that may span guidance pages, transactions, departments, offline actions, or separate sessions.", "Explain the intended order honestly while supporting branches such as 'and' or 'or' only when users can tell which tasks apply to their situation." ], "uiExamples": { "good": [ "A 'Apply for a permit' guide shows numbered steps for Check eligibility, Prepare documents, Submit application, Pay fee, and Track decision, each expanding to relevant links and conditions.", "A process sidebar on a related content page links back to the standalone process overview and highlights the step that contains the current content page.", "A process list step shows 'Pay the application fee - $50' as linked task text with the cost near the link rather than hidden on the destination page." ], "bad": [ "A live form page shows a process list where the Continue button should be, so users leave the transaction to read unrelated guidance.", "A process list uses headings such as Details, More, Things, and Finish, with no parallel action verbs or clear order.", "A numbered list mixes help links, account settings, search filters, and status badges as if they are one process." ] }, "uxExamples": { "good": [ "A user unsure where to start expands 'Prepare documents' and sees both online upload guidance and an offline identity check requirement before starting the application.", "A user returns later to the standalone process page and can understand what they already read without being forced into an active transaction.", "An eligibility branch uses 'or' subheadings so users can choose the path that applies instead of reading every task as mandatory." ], "bad": [ "The process list says 'Complete identity check' but opens another step-by-step page that loops back to the original guide.", "A user clicks a future process step expecting saved progress, but it only opens static guidance and loses the form context.", "A process with no useful order is numbered, causing users to think they must complete arbitrary options in sequence." ] }, "problemContext": [ "The journey has a recognizable start and end but spans multiple pages, services, organizations, or channels.", "Users may need to complete the journey over time, return to guidance, or choose between conditional paths.", "The order is helpful or necessary, but each step may contain several links or pieces of instruction." ], "selectionRules": [ "Choose a process list when users need an ordered overview of an end-to-end journey that combines guidance, service links, offline actions, or external tasks.", "Use a process list when the content has a specific start and end point and the order helps users decide what to do next.", "Keep process steps high-level; split a step when the heading cannot stay short, parallel, and action-oriented.", "Use expandable detail only for essential context, task links, conditions, costs, or alternate routes that help users complete the step.", "Use 'and' branches when users must do multiple parallel activities, and 'or' branches when users choose one applicable path.", "Do not use process lists inside active transactional services where Back, Continue, step navigation, or a task list should own progress.", "Do not use process lists for unordered option sets, site hierarchy, same-page sections, or a single document's table of contents.", "Use a task list when the service stores completion status and users need to choose the order of tasks." ], "requiredStates": [ "Standalone process overview with introduction and ordered high-level steps.", "Collapsed step state showing the step number and action heading.", "Expanded step state showing task links, conditions, costs, or supporting content.", "Contextual page state with a link back to the standalone process overview.", "Branch state using clear 'and' or 'or' subheadings for parallel or alternative tasks.", "External or offline task state that explains what happens outside the current website.", "Mobile state where expanded content remains readable and the process does not become a dense side navigation." ], "interactionContract": [ "Activating a step expands or collapses its supporting task content without changing the user's transaction state.", "Task links open the relevant guidance, transaction, or external/offline instruction and are labeled with the action users will take.", "A process page does not claim completion unless it is backed by a service task-list model that stores status.", "The current content page can point back to the standalone process overview, but the process list itself remains journey guidance.", "Branch labels make it clear whether tasks are cumulative, parallel, alternative, conditional, online, offline, or external.", "The process order remains stable unless content governance deliberately changes the published journey." ], "implementationChecklist": [ "Map the real journey before designing the list: start point, end point, required actions, guidance pages, transactions, external links, offline steps, costs, and conditional branches.", "Write each step heading as a short parallel action phrase and keep the total number of steps between three and ten when possible.", "Use semantic ordered-list structure with correctly leveled headings inside each step.", "Provide a standalone overview page and, when shown contextually, include a clear link back to that overview.", "Keep only essential explanatory text inside steps; move long guidance to linked pages.", "Label costs, offline requirements, external services, and alternate routes close to the task link.", "Test expanded/collapsed behavior, keyboard operation, screen reader heading order, mobile wrapping, and whether users understand which tasks apply to them." ], "commonMisuses": [ "Using a process list as a transactional progress indicator.", "Using it as side navigation for a website section.", "Using it as a table of contents for headings on the same page.", "Numbering a set of unordered options or related links.", "Showing completion statuses without a service model that can prove completion.", "Linking step-by-step journeys in loops that send users back and forth." ], "critiqueQuestions": [ "Does this journey have a clear start, end, and useful order, or is it a set of related options?", "Which tasks are guidance, transactions, offline actions, external services, costs, or conditional branches?", "Would users be inside a transaction when they see this, and if so should progress be owned by step navigation or a task list instead?", "Can each step heading be a short parallel action phrase that users understand without reading the whole step?", "Will screen reader users hear the step number, heading, branch label, and task links in a useful order?" ], "relatedPatterns": [ "step-navigation", "in-page-anchor-navigation", "side-navigation", "service-navigation", "breadcrumbs" ], "comparisons": [ "process-list-vs-step-navigation-vs-in-page-anchor-navigation" ], "sourceIds": [ "govuk-step-by-step-navigation-pattern", "uswds-process-list-component", "govuk-task-list-component" ] }, { "id": "profile-setup", "completionStatus": "complete", "name": "Profile setup", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Existing-profile readiness and enrichment flow", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "After an account or initial profile exists, products often pressure users to fill every profile field, but unclear visibility, managed-field conflicts, and mandatory optional details can expose personal data or delay the user's real task.", "solution": "Provide a guided profile setup surface that shows the current profile, distinguishes required, recommended, optional, private, public, and managed fields, previews visibility, saves partial progress, and lets users return later without blocking unrelated work.", "uiGuidance": [ "Render profile setup as a focused completion surface for an existing account or profile, with current profile preview, missing recommended fields, managed-field notices, visibility controls, skip or do-later paths, and clear save state.", "Keep profile setup separate from account creation, first-run onboarding, generic settings, and initial profile creation: it helps users improve an already established profile without treating every optional profile detail as mandatory." ], "uxGuidance": [ "Use profile setup when a user already has a usable account or profile and needs guided help to make the profile complete enough for collaboration, public identity, trust, or discovery.", "Explain why each missing field matters, where it will appear, which fields are optional, which are managed by an organization, and what the user can safely skip or finish later." ], "uiExamples": { "good": [ "A workspace profile setup checklist shows that display name is complete, photo is optional with initials fallback, title is managed by HR, time zone helps scheduling, and location visibility is set to Team only.", "A developer profile readiness page previews the public profile, recommends a bio and pinned project, warns that public fields are searchable, and lets the user save partial progress." ], "bad": [ "A complete your profile banner blocks the product until the user uploads a photo, birthday, phone number, location, and social links.", "A profile setup page asks for department and job title even though those fields are later overwritten by identity-provider sync." ] }, "uxExamples": { "good": [ "A user adds time zone and pronouns, leaves photo and social links blank, sees the team-card preview update, and returns to the project they were working on.", "A user tries to edit a synced job title, sees who manages it, saves other profile changes, and gets a route to request the title correction." ], "bad": [ "A user provides a personal phone number to dismiss a profile-completion warning, then discovers it is visible to external collaborators.", "A user abandons because profile setup is mixed with account security, onboarding tips, notification preferences, and marketing consent." ] }, "problemContext": [ "The user already has an account, workspace membership, community profile, employee directory entry, developer profile, marketplace identity, or collaboration profile.", "The profile can be improved with optional fields such as photo, bio, pronouns, title, department, time zone, location, social links, skills, languages, or pinned work.", "Some fields may affect recognition, scheduling, trust, discovery, search, assignments, comments, public pages, or third-party app access.", "Some values may be synced from an identity provider, administrator-managed, or visible to different audiences.", "The user may have arrived from an in-product prompt and needs to return to the original task after setup." ], "selectionRules": [ "Choose profile setup when an existing profile is usable but incomplete, stale, or missing recommended details that improve collaboration, discovery, trust, or public presentation.", "Use create user profile when the user is first defining the visible identity required to establish a profile.", "Use account creation when the main task is credentials, verification, persistence, recovery, or authorization.", "Use onboarding when the user needs first-use product orientation or activation rather than profile-field readiness.", "Use inline edit when the user is changing one visible profile value in place rather than working through a guided profile setup surface.", "Use review before submit when profile changes need a final commit gate because they are public, high-risk, regulated, or hard to undo.", "Do not block unrelated product use for optional profile fields unless a field is legally, safety, or access-policy required.", "Show where each requested profile value appears before asking for it, especially for public, external, searchable, or app-visible fields.", "Let users save partial progress and return to the originating task when profile setup is prompted from inside another workflow." ], "requiredStates": [ "Current profile preview with existing values", "Missing required field state", "Recommended but skippable field state", "Optional field intentionally blank state", "Field visibility or audience state", "Managed or synced field state", "Partial save and return later state", "Failed save with preserved draft state" ], "interactionContract": [ "Opening profile setup loads the current saved profile and clearly distinguishes already-complete, missing, recommended, optional, managed, and visibility-sensitive fields.", "Saving updates only the edited profile values and preserves skipped recommended or optional fields as intentional choices rather than validation failures.", "Visibility changes update the preview or audience labels before save and are persisted with the relevant field.", "Managed or synced fields remain read-only or clearly constrained, with source and correction route visible before users try to edit them.", "Skipping profile setup returns the user to the originating workflow without discarding existing profile data or repeatedly blocking unrelated tasks.", "Failed saves preserve typed drafts, uploaded-photo state where possible, visibility choices, and the user's return path.", "Public or external profile changes are not presented as final until the backend confirms the saved profile state." ], "implementationChecklist": [ "Inventory all profile fields and label each as required, recommended, optional, managed, synced, public, organization-visible, team-visible, private, or app-visible.", "Define the minimum profile needed for access separately from recommended profile completeness.", "Show a current profile preview for the most important destination such as team card, directory row, public profile, comment byline, or marketplace listing.", "Keep account security, notification settings, marketing consent, billing, and product onboarding outside the profile setup flow unless directly related to profile visibility.", "Persist partial progress and record skipped recommended fields without nagging users on every unrelated page.", "Provide a managed-field explanation and request-change route for identity-provider or administrator-owned values.", "Test long names, no photo, initials fallback, hidden location, public bio, managed title, skipped recommended fields, failed save, mobile layout, screen readers, keyboard navigation, and high zoom." ], "commonMisuses": [ "Calling every optional field required profile completion.", "Blocking the main product until users add photos, biographies, birthdays, phone numbers, or social links.", "Publishing setup fields without visibility labels or preview.", "Letting users edit synced fields that will be overwritten later.", "Mixing profile setup with onboarding, security setup, notification preferences, marketing consent, or billing.", "Using a percentage-complete meter that pressures users to reveal unnecessary personal information.", "Repeating profile completion prompts after users intentionally skipped optional fields.", "Failing to return users to the task that launched profile setup." ], "critiqueQuestions": [ "Which profile fields are truly required, and which are only recommended?", "Where will each field appear after save?", "Which fields can be seen by public visitors, external collaborators, team members, apps, or only the user?", "Can users skip optional fields and still complete their real task?", "Which fields are synced or admin-managed, and how can users correct them?", "Does the setup surface preserve partial progress and return to the originating workflow?" ], "relatedPatterns": [ "create-user-profile", "account-creation", "onboarding", "inline-edit", "review-before-submit" ], "comparisons": [ "profile-setup-vs-create-user-profile-vs-onboarding-vs-account-creation" ], "sourceIds": [ "atlassian-profile-visibility-settings", "slack-customize-member-profiles", "github-profile-overview", "slack-display-name-profile", "nng-required-fields-forms" ] }, { "id": "progress-bar", "completionStatus": "complete", "name": "Progress bar", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Measurable system-operation progress indicator", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users waiting for uploads, downloads, exports, imports, scans, saves, or batch processing need trustworthy progress, but dishonest or poorly scoped bars can overpromise completion, hide failure, or make users abandon work too early.", "solution": "Show a scoped, accessible progress bar only when progress can be measured against a known operation, keep label and value near the bar, update it monotonically, expose useful units and recovery actions, and transition to success, error, cancellation, or background status when the operation changes state.", "uiGuidance": [ "Show a labeled bar with a track, filled value, and nearby helper text that reports the measurable unit such as percent, bytes, rows, files, records, or stages.", "Keep the label close to the bar, keep the value outside the fill for readability, and use distinct active, success, paused, cancelled, and error states without relying on color alone." ], "uxGuidance": [ "Use a progress bar when the system can honestly report movement toward a known finish and users need to decide whether to wait, cancel, retry, continue elsewhere, or return later.", "Advance the bar monotonically for one operation, resolve it to success or failure, and switch to a spinner, background job, or error state when progress cannot be measured anymore." ], "uiExamples": { "good": [ "A document upload card says Uploading evidence.zip, shows 64%, 32 of 50 MB, a Cancel action, and keeps the rest of the form usable.", "A CSV import job shows Validating rows, 840 of 1200 records checked, a progress bar at 70%, and a View issues action when warnings appear." ], "bad": [ "A blue bar fills across the top of the page with no label, no percent, and no affected object.", "A progress bar reads 100% complete while virus scanning and server acceptance are still pending.", "The same upload jumps from 80% back to 25% after retry without explaining that a new operation started." ] }, "uxExamples": { "good": [ "A user uploads evidence.zip, sees progress move from 12% to 64%, cancels before commit, retries after a network error, and gets a completed receipt only after server processing succeeds.", "A long report export reaches 42%, offers Move to background, then sends users to job history while preserving the current dashboard." ], "bad": [ "A fake progress bar inches to 99% for minutes with no elapsed time, cancel, retry, or background option.", "A download bar jumps to 100%, disappears, and then shows Download failed in a toast with no retry or saved context." ] }, "problemContext": [ "The operation has a known total such as file bytes, records, items, stages, or server-reported completion percentage.", "Users may need to keep working, cancel, retry, move the job to background, or decide whether a wait is acceptable.", "The product must distinguish client transfer, server processing, scanning, validation, commit, and final acceptance.", "Progress may be local, remote, batched, queued, or multi-stage, and each stage may expose different measurement quality." ], "selectionRules": [ "Choose progress bar when the system can report a meaningful value toward a bounded operation.", "Use percent when the total is stable and the value maps cleanly to 0 through 100.", "Use count helper text such as 840 of 1200 rows when counts are more useful than a bare percent.", "Use byte helper text for upload, download, or file transfer when users recognize the file size.", "Use stage text such as Uploading, Scanning, Processing, or Finalizing when one visible bar spans multiple system phases.", "Use loading spinner when the operation is active but progress cannot yet be detected and the expected wait is short.", "Use loading skeleton when users are waiting for predictable content layout rather than monitoring an operation.", "Use step navigation when people move through task milestones and completion depends on user action or validation.", "Use error state when the operation has failed, timed out, or cannot continue from the current value.", "Do not use a progress bar when values are guessed, decorative, manually advanced by user steps, or likely to move backward during one operation." ], "requiredStates": [ "Idle state before the operation starts.", "Active determinate state with label, value, and helper text.", "Indeterminate handoff state only while measurement is not yet available.", "Paused or waiting state when the system needs network, permission, queue, or user action.", "Cancelled state that explains what was stopped and what data remains.", "Success state after the operation is truly complete, including server acceptance when relevant.", "Error state with retained value, reason, retry, cancel, support, or report actions.", "Background state for long work that continues after the current surface is closed." ], "interactionContract": [ "The progress bar appears only after the operation starts and is scoped to the affected file, job, card, dialog, or page region.", "The label identifies the operation and affected object, such as Uploading evidence.zip or Validating 1200 rows.", "The value advances monotonically during one operation unless a new operation clearly starts with a new label or reset explanation.", "The bar does not reach 100% until the user-facing operation is actually complete, including server-side processing when that matters.", "Cancel, retry, pause, resume, or move-to-background actions are available when the operation duration or risk justifies them.", "Unrelated work remains available unless the entire surface depends on the operation.", "Assistive technology receives an accessible name, current value, min/max, useful value text when percent is insufficient, and a resolved or failed state." ], "implementationChecklist": [ "Define the measurable unit, total, stages, ownership of truth, update frequency, timeout threshold, cancellation policy, retry behavior, background behavior, and terminal states before rendering the bar.", "Use native progress where practical or recreate progressbar semantics with accessible name, minimum, maximum, current value, and useful value text.", "Keep label, bar, helper text, status, and actions visually grouped and programmatically related to the affected region.", "Throttle announcements so assistive technology users are not interrupted on every small percentage change.", "Keep progress monotonic within a single operation and explain any reset as a new attempt, resumed job, or new stage.", "Separate upload transfer, server processing, scanning, validation, and final acceptance when 100% transfer is not the same as done.", "Show success, error, cancelled, paused, or background states after progress stops instead of leaving an active bar on screen.", "Test slow network, failed network, retry, page refresh, background job return, multiple simultaneous jobs, reduced motion, and screen reader value announcements." ], "commonMisuses": [ "Fabricating progress values just to make users feel movement.", "Letting a bar reach 100% before server processing, virus scanning, validation, or commit is done.", "Using one page-level bar for several unrelated operations.", "Resetting a bar backward without explaining that a new attempt or stage began.", "Hiding the label or placing it far away from the bar.", "Using a progress bar for user journey steps rather than system operation progress.", "Leaving the bar active after failure instead of showing recovery." ], "critiqueQuestions": [ "What exact operation owns this bar, and what unit is being measured?", "Can the backend or client honestly report the value, or is the bar pretending?", "What does 100% mean: transfer finished, processing finished, scan passed, data committed, or user-visible result ready?", "What should users do if the bar stalls, fails, or takes longer than expected?", "Does the bar belong to the smallest affected region, and can unrelated work continue?", "How will screen reader users hear the label, value, and terminal state without excessive announcements?" ], "relatedPatterns": [ "loading-spinner", "loading-skeleton", "step-navigation", "file-upload", "bulk-import" ], "comparisons": [ "progress-bar-vs-loading-spinner-vs-loading-skeleton-vs-step-navigation" ], "sourceIds": [ "carbon-progress-bar-component", "material-design-progress-indicators", "mdn-aria-progressbar" ] }, { "id": "progressive-disclosure", "completionStatus": "complete", "name": "Progressive disclosure", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Staged reveal of advanced or secondary task complexity", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Complex products often contain advanced, rare, expert, diagnostic, or risky controls that clutter the default path for most users, yet hiding them poorly can make important state, consequences, or recovery paths undiscoverable.", "solution": "Stage complexity by showing the essential path first, revealing secondary controls only after clear intent, preserving the user's context, summarizing revealed changes, and surfacing hidden blockers or consequences before they can surprise the user.", "uiGuidance": [ "Render the default task with the essential controls, status, cost, risk, and primary action visible, then provide clearly named reveal controls for advanced settings, rare commands, diagnostics, expert filters, or optional configuration.", "Make each reveal level preserve context: keep the trigger, changed advanced values, reset path, summary of hidden changes, and route back to the simple path visible enough that users know what the revealed controls affect." ], "uxGuidance": [ "Use progressive disclosure when exposing every option upfront would overwhelm most users, but hiding advanced controls until users ask for them keeps the main path learnable and reduces accidental errors.", "Do not hide required fields, severe consequences, submission blockers, legal duties, safety warnings, or primary recovery paths unless the interface intentionally surfaces them before they become necessary." ], "uiExamples": { "good": [ "A backup setup page shows destination, schedule, retention, estimated storage, and Start backup first, then reveals Advanced retention, encryption, bandwidth limit, and dry-run settings with a visible changed-settings summary.", "A search page starts with query and sort, then offers Advanced filters for file type, owner, date range, and archived content while keeping active advanced filters visible as chips." ], "bad": [ "A payment form hides currency conversion fees, tax treatment, and the final payer under Advanced options until after submission fails.", "A page collapses all sections by default, including required fields and the primary action, so the first task is finding the interface." ] }, "uxExamples": { "good": [ "A novice user completes the default backup with recommended retention while an expert opens Advanced retention, changes encryption, sees Advanced settings changed near Start backup, and can reset to recommended.", "A user opens troubleshooting details only after a sync failure, copies diagnostic logs, then closes the section without losing the main retry path." ], "bad": [ "A user misses a required consent field because it is hidden behind a More options link with no indication it affects submission.", "A user changes an expert setting, collapses Advanced, and later cannot tell why the generated quote changed." ] }, "problemContext": [ "The interface supports both common users who need a clear default path and expert users who need optional control.", "Advanced controls are useful but not required for most successful completions.", "The product can keep hidden state, changed advanced values, summaries, validation, and reset behavior synchronized.", "Users need to understand when a hidden option affects output, cost, permissions, safety, or final commitment." ], "selectionRules": [ "Choose progressive disclosure when the task benefits from a simple default path plus optional advanced controls or details revealed on demand.", "Use disclosure details when there is only one short optional explanation beside a local field or paragraph.", "Use accordion when several peer sections should each be independently opened, scanned, summarized, or expanded together.", "Use conditional reveal fields when a selected form answer owns a short follow-up field that becomes part of submitted data.", "Use wizard when the task has sequenced dependencies, draft preservation, tests, review, cancel, and finish behavior.", "Use details panel, preview panel, or full page when hidden content is selected-object inspection, rendered content preview, or deep reading.", "Do not hide primary completion actions, required answers, severe warnings, or legal consequences behind an advanced reveal.", "Do not hide advanced changes once made; summarize them near the primary action and provide reset or edit access.", "Avoid stacking several reveal levels unless each level has a specific purpose, predictable label, and escape path.", "Prefer defaults, presets, or simpler options over hidden expert settings when most users cannot safely judge the advanced controls." ], "requiredStates": [ "Simple default state with essential controls, visible primary action, and recommended defaults.", "Advanced closed state with a specific trigger that names what is hidden and whether any hidden values differ from defaults.", "Advanced open state with grouped secondary controls, context copy, and reset or restore recommended settings.", "Changed advanced state with visible summary near the primary action.", "Hidden validation blocker state that opens or points to the responsible revealed control before submission fails.", "Troubleshooting or diagnostics revealed state after a problem occurs.", "Collapsed-after-change state where the changed summary remains visible.", "Reset advanced state that returns hidden controls to recommended defaults without clearing essential answers.", "Narrow-screen state that keeps the default path and reveal trigger reachable without burying the primary action." ], "interactionContract": [ "The default path remains usable without opening advanced or secondary sections.", "Reveal triggers use specific labels such as Advanced retention settings or Troubleshooting details, not vague More labels.", "Opening a section reveals controls in place or in a clear secondary route without moving users away from the owning task context.", "Closing a changed advanced section keeps a visible summary of hidden changes and an edit path.", "Submission or commit validation opens, links to, or clearly names any hidden control that blocks progress.", "Reset advanced returns only secondary controls to recommended defaults unless the user explicitly resets the whole task.", "Revealed controls use ordinary form, menu, table, or disclosure semantics rather than a custom invisible interaction model." ], "implementationChecklist": [ "Classify each control as essential, secondary, expert, diagnostic, dangerous, or required before deciding what can be hidden.", "Design recommended defaults so the simple path is genuinely complete for common users.", "Write reveal labels that name the hidden control group and its consequence.", "Track whether hidden values differ from defaults and expose that state near the primary action.", "Open or link to hidden fields when validation, errors, search results, or deep links target them.", "Provide reset, restore recommended, or clear advanced controls without clearing the main task.", "Test novice completion, expert reveal, collapse-after-change, validation on hidden controls, reset behavior, keyboard access, screen-reader announcements, and small viewport layout.", "Measure whether hiding a control increases support, search, abandonment, or wrong submissions before leaving it hidden." ], "commonMisuses": [ "Hiding required fields or primary actions to make a page appear shorter.", "Using vague More or Advanced labels that do not tell users what kind of control is hidden.", "Hiding changed advanced settings after collapse with no summary near the final action.", "Treating progressive disclosure as a substitute for information architecture, section headings, or a wizard.", "Stacking several nested reveals until users cannot predict where an option lives.", "Hiding warnings, consent, destructive scope, or cost changes users must understand before committing.", "Creating a reveal control that looks like a link, menu, tab, or drawer but does not follow that pattern's behavior." ], "critiqueQuestions": [ "Which controls are essential for a common successful completion?", "What advanced, rare, expert, diagnostic, or risky controls can safely wait for user intent?", "Can users tell from the trigger what will appear and what it affects?", "What hidden values are changed, and where are those changes summarized before commit?", "What happens when validation, search, or an error targets a hidden control?", "Would this be clearer as one disclosure detail, an accordion, conditional reveal field, wizard, or separate page?" ], "relatedPatterns": [ "disclosure-details", "accordion", "conditional-reveal-fields", "wizard", "multi-step-form", "details-panel", "popover", "sheet" ], "comparisons": [ "progressive-disclosure-vs-disclosure-details-vs-accordion-vs-wizard" ], "sourceIds": [ "nng-progressive-disclosure", "apple-hig-disclosure-controls", "microsoft-progressive-disclosure-controls", "primer-progressive-disclosure", "microsoft-power-platform-information-architecture" ] }, { "id": "prompt-box", "completionStatus": "complete", "name": "Prompt box", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Primary editable input surface for composing and submitting an AI request", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI features often invite open-ended requests, but a vague or under-instrumented prompt field hides what context, sources, tools, permissions, limits, and side effects will be included, causing accidental sends, weak outputs, privacy mistakes, and confusion with search or command execution.", "solution": "Provide a prompt box that makes the editable draft, included context, source and tool scope, submission behavior, safety limits, blocked states, and recovery paths visible before the request is sent.", "uiGuidance": [ "Render the prompt box as a labelled, editable composer with visible draft area, send control, context chips, attachment controls, model or mode indicator when relevant, character or token boundary feedback, and clear disabled or blocked-send reasons.", "Show exactly what the prompt will include before submission: typed instruction, selected text, attached files, page context, workspace sources, tool access, output format, safety or privacy limits, and whether Enter sends or inserts a newline." ], "uxGuidance": [ "Use a prompt box when users need to author a natural-language request for AI generation, transformation, analysis, or automation and must remain in control of the exact request being submitted.", "Protect users from accidental or misleading submissions by preserving drafts, requiring explicit send for consequential work, validating unavailable context, supporting edit-and-resend, and distinguishing prompt composition from search, command execution, and normal text entry." ], "uiExamples": { "good": [ "An assistant composer labels the selected source as Contract draft, shows Attach file, Use selected text, Format: table, and Send, and blocks sending when the referenced file is no longer available.", "A prompt box expands for a multi-line request, shows Shift+Enter for newline, Enter to send only when configured, and keeps the draft after a failed model request." ], "bad": [ "A blank AI field shows only Ask me anything and sends vague requests with hidden page context.", "A prompt input has attachment and tool icons but no labels, no context summary, and no indication that generated output will need review." ] }, "uxExamples": { "good": [ "A user selects a policy paragraph, writes Summarize risks for a non-lawyer, sees Selected text and Output: bullets chips, submits, then edits and resends the exact prompt after the first answer is too broad.", "A user attaches a spreadsheet, sees that the model can use only the visible sheet, changes the prompt to ask for a CSV-ready summary, and keeps their draft when upload validation fails." ], "bad": [ "A user presses Enter expecting a new line and accidentally sends an unfinished prompt to an external model.", "A user asks the prompt box to update records, but the surface hides that tool access is disabled until after generation fails." ] }, "problemContext": [ "Users may be asking for generation, summarization, extraction, classification, rewrite, planning, data analysis, tool use, or workflow automation.", "A prompt may include typed text, selected page content, files, current object metadata, conversation history, workspace knowledge, external tools, hidden system instructions, or no additional context.", "The AI response can be non-deterministic, incomplete, ungrounded, delayed, blocked, rate-limited, or require user review before use.", "Prompt input often sits near prompt suggestions, generated responses, chat history, citations, approvals, attachments, and model-selection controls.", "Mobile keyboards, IME composition, speech input, paste, file upload, and Enter/newline behavior can change how users submit or edit prompts." ], "selectionRules": [ "Choose prompt box when the central user action is composing and submitting an AI request.", "Use prompt suggestions when the interface provides starter requests that should load into an editable prompt box before send.", "Use command palette when the typed input selects known app commands or routes rather than open-ended AI output.", "Use search suggestions when the input creates or refines a retrieval query and returns matching items.", "Use textarea when the field is ordinary human-authored long text without AI context, sources, model state, or generated-output lifecycle.", "Use chat interface when conversation history, assistant turns, follow-up prompts, streaming responses, and multi-turn memory are the primary surface.", "Require explicit send when a prompt can trigger tool use, publish content, contact people, alter records, reveal sensitive data, or spend money.", "Show context inclusion and repair paths before send when selected text, files, workspace sources, or tools are unavailable, stale, too large, or permission-limited.", "Keep empty-field hint copy instructional but never treat hint text as submitted prompt content.", "Preserve draft text, attachments, selected context, focus, and scroll when send fails, model availability changes, or users navigate back from output review." ], "requiredStates": [ "Empty prompt state with label, helpful instruction, and no implied hidden submission.", "Typing state with expandable multi-line draft, send affordance, newline behavior, and character or token boundary feedback.", "Context-attached state with selected text, current page, file, source, or tool chips.", "Unavailable-context, unsupported-file, over-limit, permission-limited, blocked-safety, and offline states with repair paths.", "Submitted prompt state that records the exact prompt sent and distinguishes it from the editable draft.", "Generation pending, failed request, rate limited, retry, edit-and-resend, cancel, and cleared draft states.", "Sensitive-content warning, external-model disclosure, tool-use review, and human-approval handoff states when relevant.", "Mobile keyboard state with accessible send, attachment, newline, voice input, and draft-preservation behavior." ], "interactionContract": [ "The prompt box always exposes the user's editable draft before submission.", "Send uses the visible draft and the visible context chips; hidden context must be disclosed elsewhere in the same surface.", "Placeholder, suggestion, or hint text never submits as a user prompt unless the user explicitly selects or types it.", "Enter, Shift+Enter, Command+Enter, mobile send, and IME composition behavior are stated or follow platform expectations without accidental sends.", "Context chips can be inspected, removed, repaired, or replaced before the request is sent.", "Blocked send states explain whether the problem is empty prompt, missing context, unsupported file, safety policy, permission, rate limit, model availability, or network state.", "After failed send or blocked send, the draft and attachments remain available and focus stays near the repair control.", "After submit, users can inspect the exact prompt, edit and resend it, or clear the draft without losing the previous output." ], "implementationChecklist": [ "Define prompt payload structure: user text, selected content, files, source IDs, tool permissions, conversation scope, output format, model or mode, and safety flags.", "Keep prompt draft state separate from submitted prompt history, generated answer, command execution state, and search query state.", "Implement labelled controls for send, attach, context source, remove context, clear draft, edit previous prompt, retry, cancel generation, and open safety or privacy details.", "Validate empty prompt, over-limit text, unsupported attachments, unavailable sources, revoked permissions, offline state, rate limits, and blocked content before send.", "Preserve drafts across focus loss, route changes within the task, failed requests, file validation errors, and model availability changes.", "Test keyboard, screen reader, mobile keyboard, paste, IME composition, dictation, long prompts, file attachments, sensitive content, and low-connectivity states." ], "commonMisuses": [ "Showing Ask anything as the only instruction while hiding what sources and tools the model can use.", "Auto-sending prompt suggestions, pasted content, or empty-field hint wording.", "Using a prompt box for deterministic commands that should be explicit buttons or command-palette actions.", "Styling a prompt box like search and implying generated answers are exact retrieved results.", "Letting users attach files or select context without showing whether the model can read them.", "Clearing the draft after a rate limit, upload failure, safety block, or network error.", "Hiding consequential tool use behind conversational phrasing." ], "critiqueQuestions": [ "Can users see the exact request, context, attachments, sources, tools, and output expectation before send?", "What prevents accidental send from Enter, starter prompts, paste, mobile keyboard actions, or empty-field hint text?", "Which failures preserve the draft, and which provide repair before submission?", "Does this surface need a chat interface, prompt suggestions, command palette, search box, or ordinary textarea instead?", "Are privacy, sensitive-data, external-model, and tool-use consequences visible at the prompt box boundary?", "Can users edit and resend the exact prompt after reviewing a weak, failed, or incomplete output?" ], "relatedPatterns": [ "prompt-suggestions", "command-palette", "search-suggestions", "textarea", "text-input" ], "comparisons": [ "prompt-box-vs-prompt-suggestions-vs-command-palette-vs-search-suggestions-vs-textarea" ], "sourceIds": [ "openai-prompt-engineering-guide", "microsoft-365-copilot-writing-prompts", "microsoft-copilot-studio-prompt-assistant", "microsoft-copilot-prompt-gallery" ] }, { "id": "prompt-suggestions", "completionStatus": "complete", "name": "Prompt suggestions", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "AI prompt starter surface", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "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.", "solution": "Offer contextual, truthful prompt starters that reveal useful tasks, load into an editable prompt field, and require the user to intentionally send the final request.", "uiGuidance": [ "Render contextual prompt starter cards or chips with a task label, editable prompt text, capability boundary, selected state, disabled or stale state, and explicit send action.", "Keep suggestion content visually distinct from user-authored prompt text until the user edits or sends it.", "Place the editable prompt editor close to the suggestions so the transition from starter to owned prompt is visible." ], "uxGuidance": [ "Help users discover useful AI requests while preserving control over the exact prompt that is sent.", "Use prompt suggestions to reveal supported capabilities and needed context, not to imply guaranteed correctness or hidden data access.", "Let users revise, combine, ignore, save, or share suggestions without making any suggestion mandatory." ], "uiExamples": { "good": [ "Each prompt starter shows an action label, full prompt preview, and boundary note such as uses selected thread only.", "The selected suggestion appears in an editable prompt field with Send and Clear actions.", "Unavailable suggestions are disabled with a reason tied to missing selection, permission, or source data." ], "bad": [ "Three tiny chips labeled summarize, improve, and more with no context or affordance.", "A suggestion styled like a final AI answer rather than an editable starting point.", "Prompt suggestions remain visible after the selected document or agent capability changes." ] }, "uxExamples": { "good": [ "Selecting a starter loads a draft, moves focus to the prompt editor, and lets the user adjust scope before sending.", "The UI explains when a suggestion needs selected text, available sources, or a new chat session before it will work.", "Users can save or share useful prompts while still adapting them to the current task." ], "bad": [ "Clicking a suggestion immediately runs a consequential task without review.", "A vague prompt such as do everything perfectly is auto-filled and sent.", "Suggestions promise source-grounded or high-confidence output when the AI cannot access the needed source." ] }, "problemContext": [ "An AI feature accepts open-ended natural-language input.", "The system has useful but bounded capabilities that users may not discover from an empty prompt box.", "Suggested prompts may be created by the product, generated from agent configuration, saved by the user, or shared by a team." ], "selectionRules": [ "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." ], "requiredStates": [ "Initial state with contextual prompt starters and capability or source boundary notes.", "Selected suggestion state where the draft prompt is visible, editable, and not yet sent.", "Edited draft state after the user changes the suggested prompt.", "Submitted state that shows the exact prompt sent and preserves recovery if the output is weak.", "Unavailable, stale, or limited-capability state when suggestions should be hidden, refreshed, or clearly labeled." ], "interactionContract": [ "Selecting a suggestion populates or inserts editable prompt text instead of silently running the request.", "The suggestion label explains the task outcome, while the draft prompt contains enough context to be useful after selection.", "Users can ignore, revise, combine, clear, or send suggestions using pointer and keyboard.", "The UI distinguishes system-suggested text from user-authored text until the user edits or sends it.", "The suggestion set updates when the underlying object, agent capability, language, permission, or source context changes." ], "implementationChecklist": [ "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." ], "commonMisuses": [ "Showing generic chips such as summarize, improve, or make better with no object-specific context.", "Auto-submitting a suggested prompt before the user can review or edit it.", "Suggesting work the AI cannot ground, verify, or perform with the current permissions.", "Styling suggestions like final answers or mandatory next steps.", "Leaving old suggestions visible after the user changes file, thread, customer, agent, language, or workspace context." ], "critiqueQuestions": [ "Would a user understand what the AI can do from these suggestions without being misled about data access or reliability?", "After selecting a suggestion, can the user inspect and edit the exact text that will be sent?", "Are these prompts tied to the current task strongly enough that another pattern could not use the same copy unchanged?" ], "relatedPatterns": [ "search-suggestions", "command-palette", "autocomplete" ], "comparisons": [ "prompt-suggestions-vs-search-suggestions-vs-command-palette" ], "sourceIds": [ "microsoft-copilot-prompt-gallery", "microsoft-copilot-studio-suggested-prompts", "microsoft-copilot-studio-prompt-assistant", "microsoft-human-ai-guidelines" ] }, { "id": "publish-workflow", "completionStatus": "complete", "name": "Publish workflow", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Workflow for moving edited material to live, staged, scheduled, or retired state", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Publishing is risky when products hide whether work is saved, staged, scheduled, public, or retired; which target will change; whether validation passed; who has permission; what dependencies will publish; and how to verify or undo a bad release.", "solution": "Provide a publish workflow that checks readiness, previews the exact target, shows visibility and affected scope, supports publish now, schedule, reschedule, cancel, unpublish, rollback, and live verification, and records outcome state separately from draft saving or approval routing.", "uiGuidance": [ "Render publish workflow as a readiness and release surface with content identity, current status, target destination, affected pages or entries, preview, validation, permission, schedule, publish, unpublish, rollback, and live verification.", "Separate saving, submitting for review, approving, scheduling, publishing, unpublishing, and confirming live state so users can tell whether work is only stored, waiting, approved, queued, visible, retired, or failed." ], "uxGuidance": [ "Use publish workflow when a user is moving content, product data, site changes, configuration, release notes, or campaign material from draft, staged, scheduled, or approved state to a selected live or public target.", "Make visibility and blast radius explicit before publication: who can see it, which domain, environment, page, entry, locale, channel, time, dependency, and version will change." ], "uiExamples": { "good": [ "A CMS publish panel shows Draft article, production site, English and French locales, validation complete, preview URL, scheduled time, affected entries, and actions to Publish now, Schedule, or Keep draft.", "A site builder publish dialog lets a user choose staging or production domains, shows unpublished page changes, warns that production is public, then confirms the live URL and offers rollback." ], "bad": [ "A Publish button sends changes live to every domain with no staging/production target, preview, validation, or affected-page list.", "A scheduled product launch silently fails because the workflow accepted missing channel data and did not surface validation before scheduling." ] }, "uxExamples": { "good": [ "A content editor previews a campaign page, fixes a missing hero image, schedules publication and retirement times, sees the job queued, and later verifies the live URL and scheduled unpublish state.", "A merchandiser schedules a product to publish only to Online Store at 09:00, sees other sales channels excluded, edits the schedule, then cancels before launch without changing draft content." ], "bad": [ "A user clicks Save and assumes the page is live because the interface uses Save, Submit, Schedule, and Publish interchangeably.", "An editor updates a live page from an old draft and overwrites newer production copy because the workflow did not compare versions." ] }, "problemContext": [ "The item may be an article, page, product, collection, site branch, release, campaign, locale, configuration, media asset, documentation page, or channel-specific listing.", "Publishing may affect staging, production, public web, selected domains, sales channels, locales, entries, dependencies, cached pages, search indexes, subscribers, social channels, or release bundles.", "The workflow may include draft, pending review, approved, scheduled, queued, validating, publishing, live, failed, missed, canceled, unpublished, retired, or rolled-back states.", "The product must distinguish low-risk save operations from visibility-changing publish operations.", "Users may need scheduled publication, scheduled unpublication, channel selection, permissions, branch approval, preview URLs, validation errors, and post-publish verification." ], "selectionRules": [ "Choose publish workflow when the primary task is making edited material visible, live, scheduled, retired, or no longer visible in a selected destination.", "Use approval workflow when human approval is required before publication but the interface is primarily the decision route, not the live-target release surface.", "Use review queue when many items await editorial, moderation, or code review before individual publish decisions.", "Use draft state when the user is saving unfinished work without selecting target, schedule, preview, publish, or unpublish behavior.", "Use review before submit for final field checking before a publish or schedule action is created.", "Use confirmation page after publish succeeds to show live URL, affected target, time, reference, and next steps.", "Show staging versus production, selected domains, channels, locales, dependencies, and audience before any live-changing action.", "Validate required content, links, media, inventory, permissions, slug, translations, channel eligibility, schedule time, and dependency state before publish or schedule.", "Represent scheduled, rescheduled, canceled, missed, failed, live, unpublished, and rolled-back states distinctly.", "Provide a safe way to unpublish, retire, rollback, or open the live target when the platform supports it." ], "requiredStates": [ "Draft or edited but unpublished state", "Preview state with target URL or destination", "Validation pending state", "Validation blocked state", "Ready to publish state", "Target selection state for staging, production, domain, channel, locale, page, or release", "Publish now confirmation state", "Scheduled publish state", "Reschedule or cancel scheduled publish state", "Publishing in progress state", "Published live verification state", "Failed publish or missed schedule state", "Unpublish or retire state", "Rollback or restore previous live version state", "Permission denied to publish state", "Version conflict or newer live version state" ], "interactionContract": [ "Saving a draft does not imply publication, and publishing cannot proceed until target, readiness, permissions, and validation requirements are resolved.", "The workflow shows the item version, target destination, affected scope, current live state, and side effects before a publish or schedule action.", "Preview opens the same version and target that will be published, or clearly labels where preview differs from production.", "Schedule actions store date, time, timezone, target, actor, item version, and validation result.", "Validation failures block publish or scheduling and point to the exact field, dependency, channel, locale, or permission that must be fixed.", "Publish, schedule, reschedule, cancel schedule, unpublish, retire, and rollback actions update the same release history and visible status.", "Conflicts with newer live content, unsaved edits, changed dependencies, or revoked permissions require refresh, compare, or retry paths before publication.", "After a successful action, the user can open the live target, copy the URL, see affected destinations, and inspect the audit trail." ], "implementationChecklist": [ "Define item type, statuses, target destinations, affected dependencies, permission roles, preview behavior, validation rules, schedule semantics, rollback support, and audit requirements.", "Model save, submit for review, approve, schedule, publish, unpublish, retire, rollback, and confirm-live states separately.", "Show current status and target-selection controls for staging, production, domains, sales channels, locales, releases, pages, or item-only publishing.", "Run validation before publish and again before scheduled jobs execute when content can change between scheduling and launch.", "Expose schedule date, time, timezone, reschedule, cancel schedule, and missed or failed schedule recovery.", "Protect production publish, all-channel publish, dependency publish, unpublish, and rollback with appropriate review or confirmation steps.", "Write publish history with actor, item version, target, action, time, schedule, validation outcome, failure reason, and rollback reference.", "Test draft versus live distinction, staging-only publish, production publish, scheduled publish, scheduled unpublish, invalid content, permission denied, stale version, dependency change, failed publish, rollback, mobile, keyboard, screen reader status updates, and localization." ], "commonMisuses": [ "Using Save, Submit, Schedule, and Publish interchangeably.", "Hiding whether the target is staging, production, one page, whole site, one channel, all channels, or a release bundle.", "Allowing scheduled publishing without validation or later failure reporting.", "Publishing stale draft content over a newer live version.", "Failing to show affected dependencies or locales.", "Treating approval as publication or publication as approval.", "Providing no way to unpublish, retire, rollback, or verify live output.", "Showing success before the live target, cache, search index, or channel actually updates." ], "critiqueQuestions": [ "What is live now, what is changing, and which version will publish?", "Which domain, environment, page, release, locale, sales channel, or audience will be affected?", "What validation checks must pass before publish or schedule?", "Is this saving a draft, submitting for review, scheduling, publishing now, unpublishing, or rolling back?", "Can users preview the exact target and verify the live result?", "What happens if the scheduled job fails, content changes before launch, or permissions are revoked?" ], "relatedPatterns": [ "approval-workflow", "review-queue", "draft-state", "review-before-submit", "confirmation-page", "activity-log", "conflict-state", "notification-center" ], "comparisons": [ "publish-workflow-vs-approval-workflow-vs-review-queue-vs-draft-state" ], "sourceIds": [ "wordpress-post-status", "contentful-scheduled-publishing", "contentful-content-operations", "webflow-publish-unpublish-site", "webflow-enterprise-publishing-workflow", "shopify-future-publishing", "shopify-scheduled-product-publishing" ] }, { "id": "pull-to-refresh", "completionStatus": "complete", "name": "Pull to refresh", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Top-of-scroll vertical drag gesture that refreshes the current data set", "maturity": "standard", "platforms": [ "mobile", "web", "desktop" ], "problem": "Users on scrollable, freshness-sensitive surfaces need a lightweight way to check for newer data, but a hidden vertical gesture can conflict with scrolling, nested views, offline state, duplicate requests, and accessibility unless the refresh contract is explicit.", "solution": "Constrain pull-to-refresh to the top of the relevant scroll container, show pull progress and release threshold, run one scoped refresh request at a time, preserve existing content and position, expose status messages and last-updated copy, and provide an equivalent manual refresh control.", "uiGuidance": [ "Show pull-to-refresh only at the beginning of scrollable content, with a clear pull distance, threshold, release-to-refresh state, refreshing indicator, and completion status tied to the current data set.", "Keep a visible or menu-based manual refresh action for keyboard, switch, assistive pointer, external device, and users who do not discover or cannot perform the gesture." ], "uxGuidance": [ "Use pull-to-refresh when users expect to check for newer content in a feed, inbox, list, dashboard, or status surface without leaving their current place.", "Preserve scroll position, existing content, item identity, focus, and cached data while the refresh runs; never use the gesture as the only path to data freshness or as a hidden destructive action." ], "uiExamples": { "good": [ "A mobile inbox at the top of the message list shows Pull to refresh, Release to refresh, Refreshing, Last updated 10:42, and a Refresh menu item that runs the same request.", "A field dashboard keeps cached cards visible during refresh, disables duplicate refresh, announces No new updates, and shows a Retry refresh action after a failed request." ], "bad": [ "A feed refreshes from any scroll position, causing accidental network calls while users read older content.", "A list clears all rows during refresh, spins forever when offline, and has no manual refresh path.", "A hidden pull gesture resets filters or deletes cached items without a review step." ] }, "uxExamples": { "good": [ "A user reaches the top of a notifications list, drags down, sees the pull distance cross threshold, releases, and the list updates while older items stay in place.", "A keyboard user opens the overflow menu, chooses Refresh, and hears the same refreshing and last-updated status as the touch gesture.", "A user pulls while offline, keeps cached data visible, sees Offline: showing last updated 10:42, and can retry when the connection returns." ], "bad": [ "A user tries to scroll up inside a nested comments panel and accidentally refreshes the whole page.", "A user pulls repeatedly while the previous refresh is still pending, creating duplicate requests and jumping the list.", "A screen reader user never learns that a refresh started or ended because the indicator is purely visual." ] }, "problemContext": [ "The surface is a feed, inbox, notification center, activity list, dashboard, timeline, or status list where users expect newer server data.", "The content already scrolls vertically, and the refresh gesture begins only when the relevant scroll container is at its top boundary.", "The same content may also support nested scrolling, search filters, pagination, offline cache, live updates, load-more, or retry after failure.", "Users may interact through touch, mouse, keyboard, switch control, screen reader, external keyboard, D-pad, or assistive pointer devices." ], "selectionRules": [ "Choose pull to refresh when the design problem is the vertical top-of-scroll drag that refreshes the current data set.", "Use touch gesture when the question is the broader gesture vocabulary, threshold, feedback, and fallback contract across many touch actions.", "Use feed, activity feed, notification center, dashboard layout, or list view when the primary problem is stream structure, ordering, unread state, filtering, or content comprehension.", "Use loading spinner or progress bar when the question is status display for a running operation rather than the user gesture that starts refresh.", "Use offline state when connection loss changes what data is available, and show pull-to-refresh failure or disabled refresh as one state inside that offline contract.", "Use retry when a known refresh request failed and the user is reattempting that same failed request outside the pull gesture.", "Trigger only when the user pulls downward from the beginning of the intended scroll container; do not fire from the middle of a list or inside the wrong nested scroller.", "Provide an equivalent manual refresh action in the toolbar, overflow menu, command menu, or visible control.", "Do not use pull-to-refresh for destructive, reset, submit, payment, account, security, or consent actions.", "Do not replace pagination, live update controls, or stale-data labeling with a hidden gesture." ], "requiredStates": [ "Idle state with current content visible and last updated timestamp when freshness matters.", "Scrolled-not-at-top state where upward scroll does not arm refresh.", "At-top armed state that can begin measuring downward pull distance.", "Pulling-under-threshold state with progress feedback and no request started.", "Threshold reached state with Release to refresh copy.", "Refreshing state with one in-flight refresh, disabled duplicate activation, and status message.", "Success state with refreshed content, stable scroll or focus, and updated timestamp.", "No-new-data state that confirms the refresh completed without changing the list.", "Failed refresh state that preserves existing content and offers retry or manual refresh.", "Offline or cached-data state that labels stale content and avoids endless spinning.", "Nested scroll state where inner content scrolls before the outer refresh container arms.", "Rate-limited or cooldown state with wait reason and next possible refresh time.", "Manual refresh equivalent state reachable without the gesture.", "Mobile compact and large-text states where indicator, controls, and status do not overlap." ], "interactionContract": [ "Pull-to-refresh begins only when the intended scroll container is at its top boundary and the user drags downward beyond normal scroll tolerance.", "The indicator shows progress toward a defined threshold before refresh starts.", "The refresh request starts on release after threshold, not merely on touch down or incidental overscroll.", "Releasing before threshold cancels the gesture and leaves data unchanged.", "Only one refresh runs per data scope at a time; duplicate pulls, manual refresh, and automatic refresh share the same in-flight guard.", "Existing content stays visible during refresh unless the product has a stronger reason to switch to a separate loading state.", "The result announces refreshing, refreshed, no new updates, failed, offline, or rate limited through visible text and programmatic status.", "Nested scroll containers define which scroller owns the gesture before implementation." ], "implementationChecklist": [ "Name the data scope refreshed by the gesture, such as current inbox filter, current feed, selected workspace, or current dashboard cards.", "Detect the top of the intended scroll container and exclude middle-of-list, horizontal swipe, row action, text selection, drag handle, and nested-scroll gestures.", "Set pull distance, threshold, release boundary, cancel behavior, indicator placement, and in-flight duplicate guard.", "Make the manual refresh control call the same refresh method as the pull gesture.", "Preserve scroll anchor, selected item, focus target, filters, read state, expanded rows, and cached data across the refresh.", "Show last updated, refreshing, refreshed, no new updates, failed, offline, retry, and rate-limited states near the affected content.", "Use status messaging so assistive technology can perceive refresh start and result without moving focus unexpectedly.", "Test top-of-scroll detection, nested scrollers, slow network, offline mode, rate limits, duplicate pulls, large text, screen reader, keyboard, switch, mouse wheel, touchpad, and mobile landscape." ], "commonMisuses": [ "Making pull-to-refresh the only way to update the data.", "Triggering refresh from anywhere in the list instead of only from the top of the intended scroll container.", "Providing no pull distance, threshold, release-to-refresh, refreshing, success, failure, or last-updated feedback.", "Clearing existing content during refresh and making the surface feel like a full page reload.", "Letting nested comment panels, maps, carousels, or row actions fight the refresh gesture.", "Starting duplicate refresh requests while one is already in progress.", "Spinning forever while offline or rate limited.", "Using the gesture for hidden reset, delete, submit, or destructive effects." ], "critiqueQuestions": [ "Which exact scroll container owns the pull, and how do you know it is at the top?", "What pull distance and threshold tell users when release will refresh?", "What visible and announced status proves refreshing started, succeeded, found no new data, failed, or was blocked offline?", "Where is the equivalent manual refresh path for users who cannot or do not perform the gesture?", "What happens to scroll position, focus, selected item, filters, and cached content while refresh runs?", "How do nested scrollers, horizontal row actions, touch gesture shortcuts, and browser or OS gestures avoid conflicts?", "What prevents duplicate refresh, rate-limit loops, and destructive side effects?" ], "relatedPatterns": [ "touch-gesture", "feed", "offline-state", "loading-spinner", "retry", "progress-bar" ], "comparisons": [ "pull-to-refresh-vs-touch-gesture-vs-feed-vs-offline-state-vs-loading-spinner-vs-retry" ], "sourceIds": [ "android-swipe-refresh-layout", "android-compose-pull-to-refresh", "w3c-wcag-pointer-gestures", "wcag-status-messages", "w3c-wcag-target-size-minimum" ] }, { "id": "qr-scan", "completionStatus": "complete", "name": "QR scan", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Camera or image-based QR detection, decode, validation, and action preview flow", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "QR codes can speed entry, pairing, tickets, payments, device setup, warehouse work, Wi-Fi sharing, and authenticator enrollment, but the scan is camera-dependent, detector-dependent, visually fragile, and security-sensitive; without explicit scanning state, fallback, payload validation, and action preview, users can scan the wrong code, act on malicious content, or get blocked by camera failure.", "solution": "Provide a QR scan flow that starts from a deliberate user action, checks scanner support, explains camera use, guides alignment and lighting, decodes only supported formats, handles multiple, missing, invalid, duplicate, expired, and unsafe payloads, previews the decoded result before consequential action, offers scan-from-photo or manual-code fallback, and clears frames or secrets after the task.", "uiGuidance": [ "Render QR scan as a detection and decode flow with clear purpose, supported-format check, permission state, camera preview or delegated scanner handoff, aim guide, torch and camera controls, scan feedback, decoded summary, action confirmation, fallback entry, and privacy copy.", "Show scanning state separately from decoded payload state: users need to know whether the system is waiting for a code, focusing, decoding, found multiple codes, rejected an invalid code, warning about a destination, or ready to act." ], "uxGuidance": [ "Use QR scan when users can complete a task faster by pointing a camera or selecting an image that contains a QR code, and the decoded payload can be validated before the product acts on it.", "Design the lifecycle from unsupported detector through permission, camera readiness, alignment, focus, detection, decode, validation, duplicate or expired handling, safe preview, action, fallback, and cleanup." ], "uiExamples": { "good": [ "A device-pairing flow says Scan the QR code on your thermostat, shows a square guide, offers torch and Enter code, then previews Pair thermostat TH-204 before connecting.", "A payment scan reads a QR code, displays merchant name, amount, and domain, and requires Confirm payment before opening the payment app.", "A login setup flow scans an authenticator QR code, hides the secret after pairing, and offers manual key entry if camera access is denied." ], "bad": [ "The scanner opens the camera and immediately follows the first decoded URL without showing the destination.", "A camera permission denial leaves a blank panel even though paste code or scan from photo would work.", "The UI shows a spinner forever when the QR code is too small, poorly lit, expired, or outside supported formats." ] }, "uxExamples": { "good": [ "A user scans a warehouse label, sees the decoded asset ID and item name, confirms it is the intended pallet, and continues to inspection.", "A user points at a sheet with several codes, taps the highlighted target code, and avoids opening the neighboring Wi-Fi code.", "A user cannot use the camera, uploads a photo of the QR code, sees the decoded login issuer, and finishes enrollment without exposing the secret after setup." ], "bad": [ "A scanner silently accepts an expired event ticket and the user learns it failed only at the final gate.", "A QR code opens an external site with a lookalike domain before the user can inspect it.", "The app records decoded Wi-Fi credentials and camera frames after the user cancels the scan." ] }, "problemContext": [ "The product wants to decode a QR or barcode from camera preview, a delegated OS scanner, a static image, or a pasted/manual code.", "Codes may contain URLs, payment intents, Wi-Fi credentials, device-pairing tokens, tickets, one-time login secrets, coupons, inventory IDs, contact cards, or plain text.", "Users may face denied camera permission, unsupported web APIs, missing scanner modules, dim light, glare, motion, tiny codes, damaged labels, multiple visible codes, expired codes, reused codes, or unsafe destinations.", "QR scan is adjacent to camera capture, permission request, file upload, two-factor authentication, security warning, sensitive-data reveal, and payment or device-pairing flows." ], "selectionRules": [ "Choose QR scan when decoding a code and acting on the decoded payload is the central task.", "Use camera capture when the task is creating and reviewing media rather than interpreting a code value.", "Use permission request for the standalone camera-access rationale; QR scan includes permission only as one state inside the scan lifecycle.", "Use file upload when users provide an existing file; scan from photo is a QR fallback only when the file is an image containing a code to decode.", "Use two-factor authentication when the QR code enrolls, verifies, or recovers an identity factor; the scanner must protect secrets and hand results to the auth flow.", "Use security warning when the decoded QR payload is suspicious, external, destructive, payment-related, or credential-related.", "Preview decoded URLs, merchants, device names, account issuers, ticket IDs, or inventory IDs before opening, pairing, paying, submitting, or importing.", "Support scan repair actions such as torch, move closer, hold steady, clean lens, switch camera, choose from photo, paste code, or manual entry.", "Treat multiple visible codes as a selection problem and avoid executing whichever code happens to decode first.", "Clear camera frames, decoded secrets, and temporary payloads after cancel, timeout, successful action, or route change unless the task explicitly saves them." ], "requiredStates": [ "Unsupported detector, missing scanner module, insecure context, or unsupported format state.", "Pre-scan rationale state with task purpose, camera use, payload type, privacy, and fallback.", "Camera permission not requested, requesting, granted, denied, and revoked states.", "Delegated scanner state when the OS or platform scanner handles camera access outside the app.", "Live preview state with aim guide, active camera status, torch, switch camera, and stop control.", "Focusing, too far, too close, glare, low light, motion blur, damaged code, and no code found states.", "Detecting and decoding state with progress or frame feedback.", "Multiple codes found state with target selection before action.", "Decoded payload preview state with format, destination, issuer, merchant, device, or ID summary.", "Invalid, unsupported, malformed, expired, already used, duplicate, or wrong-task payload state.", "Unsafe URL, external destination, payment, credential, or account-change warning state.", "Scan from photo or image import fallback state.", "Manual code, paste key, enter URL, or typed fallback state.", "Successful action state for open, pair, pay, import, check in, redeem, or attach.", "Cancel, timeout, retry, and cleanup state that stops camera and clears transient values.", "Sensitive secret retention state for authenticator seeds, Wi-Fi credentials, payment payloads, and login tokens.", "Offline decode or offline validation state that explains what can be decoded locally and what needs network verification." ], "interactionContract": [ "Scanning starts only after users choose a QR-dependent task and can see purpose, fallback, and privacy impact.", "Users can tell whether the scanner is unsupported, waiting for permission, active, focusing, decoding, blocked, invalid, warning, confirmed, or complete.", "The detected payload is not executed silently when it can navigate, pay, pair, import credentials, join a network, or change account state.", "Poor scan conditions produce actionable repair guidance rather than an endless spinner.", "Camera denial or unsupported detection preserves the task through scan from photo, paste code, manual key entry, or another device path.", "Multiple visible codes require target selection or a stable highlighted target before action.", "Secrets, frames, decoded raw values, and failed payloads are cleared when no longer needed." ], "implementationChecklist": [ "Define payload types, supported code formats, trusted domains, validation endpoints, expiry rules, duplicate handling, fallback paths, and retention before building the scanner.", "Check detector support and supported formats, and provide a platform fallback when BarcodeDetector, scanner modules, or camera APIs are unavailable.", "Use camera access only after explicit user action, and show active camera state, aim guide, torch, switch camera, cancel, and fallback controls while scanning.", "Throttle frame analysis, limit formats to expected values, handle decode errors, and avoid repeated actions from the same payload.", "Parse and validate decoded values before action, including scheme, domain, issuer, merchant, amount, account target, device ID, expiry, and replay status where relevant.", "Show a confirmation or warning for external links, payments, authenticator seeds, Wi-Fi credentials, device pairing, account changes, and irreversible actions.", "Provide scan from photo, paste code, manual key, typed URL, or support path when scanning fails or camera access is denied.", "Stop camera streams, clear decoded secrets, remove transient frames, and avoid logging raw payloads after cancel, timeout, or success." ], "commonMisuses": [ "Opening the first decoded URL without showing the destination or risk.", "Using a camera capture flow that saves images when only the decoded QR value is needed.", "Blocking the task after camera denial despite available manual code or image fallback.", "Showing a scanner with no guidance for distance, light, glare, focus, or damaged codes.", "Executing the wrong code when several codes are visible in one frame.", "Treating an expired, duplicate, unsupported, or wrong-task code as a generic scan failure.", "Persisting authenticator secrets, Wi-Fi passwords, payment payloads, or camera frames after setup." ], "critiqueQuestions": [ "What decoded payload types are accepted, and what happens when the QR contains a URL, payment, credential, device token, ticket, or unknown text?", "Can users understand scan state, repair poor scan conditions, and complete the task without camera access?", "Does the flow preview or confirm consequential payloads before opening, paying, pairing, importing, or changing account state?", "How does the scanner handle multiple codes, repeated detections, expired codes, and unsupported formats?", "What decoded values, frames, or secrets are retained, logged, or cleared?", "Is this really QR scan, or does camera capture, permission request, file upload, two-factor authentication, or security warning own the main problem?" ], "relatedPatterns": [ "camera-capture", "permission-request", "file-upload", "two-factor-authentication", "security-warning", "sensitive-data-reveal" ], "comparisons": [ "qr-scan-vs-camera-capture-vs-permission-request-vs-file-upload-vs-two-factor-authentication-vs-security-warning" ], "sourceIds": [ "mdn-barcode-detection-api", "mdn-barcodedetector", "wicg-shape-detection-api", "google-ml-kit-barcode-scanning-android", "google-ml-kit-code-scanner", "android-qr-scanner-upi", "mdn-mediadevices-getusermedia", "mdn-permissions-api" ] }, { "id": "query-correction", "completionStatus": "complete", "name": "Query correction", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Submitted search query correction and did-you-mean result state", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users often submit searches with misspellings, transposed letters, missing spaces, joined words, or uncertain terminology, and a strict result state can hide relevant content or silently rewrite intent.", "solution": "Expose a reversible correction state that either applies a high-confidence corrected query with disclosure or offers did-you-mean candidates while preserving the original submitted query and exact-search path.", "uiGuidance": [ "Show the original submitted query and the corrected query in the result state, for example Showing results for benefit appeal with a Search instead for benifit appeel control.", "Visually identify changed tokens or phrases near the result count, and keep correction actions close to the search field and result summary rather than hiding them in result cards." ], "uxGuidance": [ "Use query correction to recover from likely spelling, spacing, transposition, or phrase mistakes after a user submits a free-form search.", "Preserve user agency: auto-apply only high-confidence corrections, offer did-you-mean for weaker candidates, and always allow searching the original wording." ], "uiExamples": { "good": [ "A results page says Showing results for benefit appeal, marks benefit and appeal as corrected tokens, and offers Search instead for benifit appeel.", "A did-you-mean banner offers two candidate corrections after a zero-result typo query without overwriting the typed query.", "An exact-code search reports no correction for AB-1047 because codes and quoted terms are configured as exact tokens." ], "bad": [ "The search field silently changes benifit appeel to benefit appeal and the original query is gone.", "A person's name, SKU, or legal reference is corrected into a common word with no confidence, source, or revert path.", "Autocomplete suggestions appear before search and are labelled as spelling corrections even though no query was submitted." ] }, "uxExamples": { "good": [ "A user searches benifit appeel, sees corrected results for benefit appeal, checks the changed tokens, and can switch back to the original query.", "A user edits the query after a correction and the correction banner clears instead of showing stale corrected results.", "A user searches an exact policy code and the system avoids typo correction because the token is in the configured exact-match vocabulary." ], "bad": [ "The product overcorrects a claimant surname and users cannot get back to the exact original search.", "The UI reports zero results for an obvious typo even though a high-confidence correction is available.", "A correction remains applied after the user changes the query, making the result count belong to old text." ] }, "problemContext": [ "The product accepts free-form submitted queries over a large content set.", "Search relevance can compute likely spelling, phrase, split, join, or token corrections.", "Some queries contain names, identifiers, codes, acronyms, legal references, or domain terms that must not be overcorrected." ], "selectionRules": [ "Choose query correction when correction happens after an explicit search submission, not while the user is merely typing.", "Auto-apply a correction only when the corrected query is high confidence and returns useful results; otherwise show a did-you-mean candidate.", "Always show the original query and provide a direct search-original path when corrected results are displayed.", "Highlight only the changed query tokens or phrases, not every result card, so users can understand what changed.", "Clear or recompute correction state when the user edits the query, changes scope, changes language, or submits again.", "Treat fuzzy matching, synonym expansion, semantic matching, token dropping, and query correction as separate behaviors unless the changed text is explicitly disclosed.", "Avoid correction, reduce tolerance, or require confirmation for codes, SKUs, usernames, product numbers, acronyms, quoted exact phrases, numeric tokens, names, legal terms, medical terms, and domain vocabulary.", "Use no-results recovery rather than query correction when spelling is valid but filters, scope, availability, permissions, or empty data caused the zero-result state.", "Use search suggestions when the user needs help forming a future query before submission; use autocomplete when the user must select a constrained known value.", "Localize correction behavior by language, keyboard, script, stemming, plural rules, and domain vocabulary instead of assuming one global dictionary." ], "requiredStates": [ "No correction state when the submitted query is exact or correction confidence is too weak.", "Auto-applied correction state showing corrected results, original query, changed tokens, and search-original action.", "Did-you-mean state showing one or more correction candidates that have not yet been applied.", "Original-query state after the user chooses to search the submitted wording instead of the corrected wording.", "Edited-query state where stale corrections clear and the new submitted query drives the result count.", "Exact-token state where identifiers, codes, quoted phrases, or configured words bypass correction.", "No-results-with-correction state where a correction is offered alongside normal empty-result recovery." ], "interactionContract": [ "Submitting a query records the submitted text separately from any corrected query used for results.", "If corrected results are shown, the result summary states which corrected query is active and offers a reversible action to search the original.", "Choosing Search instead for original reruns or reveals results for the original submitted text without changing the user's typed history into the correction.", "Accepting a did-you-mean candidate applies that candidate as the active corrected query and updates the result count.", "Editing or clearing the search field invalidates stale correction metadata until the next explicit submit.", "Correction candidates must be bounded, ranked, and deduplicated so users are not asked to choose from noisy spelling variants.", "Exact-match and sensitive-token rules must be applied before automatic correction changes user intent." ], "implementationChecklist": [ "Store submittedQuery, correctedQuery, correctionStatus, confidence, changedTokens, and originalResultCount as distinct state fields.", "Define confidence thresholds for auto-applied correction, did-you-mean suggestion, and no-correction fallback.", "Configure dictionaries, exact words, disabled attributes, numeric-token rules, language analyzers, and domain-specific exceptions before launch.", "Display correction copy in the result summary and keep the search field behavior consistent with whether the user is editing original or corrected text.", "Provide Search original, Accept correction, edit query, and clear correction actions where relevant.", "Log overcorrection events, search-original usage, accepted corrections, no-click corrected results, and zero-result typo queries for relevance tuning.", "Test misspellings, transpositions, missing letters, extra letters, split words, joined words, plural forms, names, acronyms, identifiers, quoted phrases, multiple languages, mobile typos, and stale-response races.", "Keep correction independent from autocomplete suggestions, saved searches, recent searches, highlighting, and no-results recovery actions in the data model." ], "commonMisuses": [ "Silently replacing the user's query without saying what changed.", "Treating every fuzzy or semantic match as a corrected query.", "Correcting identifiers, names, acronyms, product codes, or quoted terms that users intended to search exactly.", "Showing only zero results for obvious typos when a strong correction exists.", "Keeping a correction active after the user edits the query or changes scope.", "Labelling pre-submit suggestions as did-you-mean corrections.", "Hiding no-results recovery because a low-confidence correction candidate exists.", "Displaying too many correction candidates with no ranking or explanation." ], "critiqueQuestions": [ "Can users see both the original submitted query and the corrected query?", "Is the correction auto-applied only when confidence and result quality justify it?", "Can users search the original wording, accept a candidate, edit the query, and clear stale correction state?", "Which tokens, fields, languages, codes, acronyms, names, numbers, or quoted phrases bypass correction?", "Does the interface distinguish correction from autocomplete, search suggestions, synonym expansion, fuzzy matching, and no-results recovery?", "What telemetry will reveal overcorrection, false positives, and ignored correction suggestions?" ], "relatedPatterns": [ "basic-search", "search-suggestions", "no-results-recovery", "autocomplete", "advanced-search", "search-result-highlighting", "search-scope-selector", "recently-searched" ], "comparisons": [ "query-correction-vs-search-suggestions-vs-no-results-recovery-vs-autocomplete" ], "sourceIds": [ "algolia-typo-tolerance", "algolia-configure-typo-tolerance", "elasticsearch-search-suggesters", "typesense-typo-tolerance", "google-custom-search-spelling", "microsoft-search-spelling-corrections", "solr-spell-checking" ] }, { "id": "radio-group", "completionStatus": "complete", "name": "Radio group", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Single-choice form control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to make one mutually exclusive choice from a short set while seeing every available option before deciding.", "solution": "Show a labeled group of native radio inputs with visible options, clickable labels, optional hints, one selected value at a time, and group-level validation when required.", "uiGuidance": [ "Render a fieldset/legend with visible native radio options, selected state, focus state, optional hints, and group-level validation.", "Keep short mutually exclusive choices visible instead of collapsing them into a dropdown." ], "uxGuidance": [ "Help users compare the available options and choose exactly one without opening an extra control.", "Avoid biased defaults and do not hide critical short choices inside a collapsed dropdown." ], "uiExamples": { "good": [ "Visible native radio options with a clear legend, selected state, focus state, and helper text.", "Vertical spacing supports comparison and touch selection without making options feel unrelated." ], "bad": [ "Custom circles that do not show focus or selected state clearly.", "Radio options laid out like unrelated buttons with no group label." ] }, "uxExamples": { "good": [ "Exactly one option is selected at a time and labels are clickable.", "Required errors apply to the whole group and do not erase a user's existing selection." ], "bad": [ "Using radios for choices where multiple selections are allowed.", "Defaulting to a consequential choice without user intent." ] }, "problemContext": [ "The option set is short, stable, and mutually exclusive.", "Seeing every choice helps users compare plans, answer a question, or avoid missing a consequential option." ], "selectionRules": [ "Choose radio groups when the user must choose one option from a short visible set.", "Make the group question explicit with a legend and keep each option label directly clickable.", "Avoid pre-selecting a consequential option unless there is strong evidence that a default is safe and expected.", "Use select only when the option list is longer, familiar, or secondary enough to collapse." ], "requiredStates": [ "No selection state for required unanswered groups.", "Exactly one selected option state.", "Focused radio option state.", "Group-level validation error when a required choice is missing." ], "interactionContract": [ "Only one option in the named group can be selected at a time.", "The fieldset legend explains the decision being made.", "Selection, focus, and required error state remain visible and programmatically exposed." ], "implementationChecklist": [ "Use native radio inputs where possible before reaching for a custom radiogroup implementation.", "Group related options with a fieldset and legend or an equivalent accessible name.", "Keep option labels concise, distinct, and large enough to select through the label text.", "List options vertically when comparison or touch selection matters.", "Show required errors at the group level without clearing a user's existing choice." ], "commonMisuses": [ "Using radios for independent choices where several answers can be true.", "Hiding a short critical set inside a select just to save vertical space.", "Omitting the group legend so users hear options without the question.", "Pre-selecting a paid, destructive, or biased option without clear evidence." ], "critiqueQuestions": [ "Is this one mutually exclusive decision with a short enough list to show?", "Would hiding these options in a collapsed control make comparison or error recovery worse?" ], "relatedPatterns": [ "select", "checkbox-group" ], "comparisons": [ "radio-group-vs-select" ], "sourceIds": [ "govuk-radios-component", "uswds-radio-buttons-component", "wai-aria-apg-radio-group" ] }, { "id": "range-slider", "completionStatus": "complete", "name": "Range slider", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Two-boundary numeric range control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to set lower and upper numeric boundaries for one ordered scale, but single sliders, hidden filters, or free text fields make it unclear which endpoints will be applied.", "solution": "Use two separately named thumbs on one bounded scale, keep the endpoints ordered, show the selected range and unit, synchronize exact endpoint fields when precision matters, and explain empty, crossed, disabled, or repaired states.", "uiGuidance": [ "Render two endpoint thumbs on one track with a persistent label, selected range band, visible minimum and maximum endpoint values, unit, min and max labels, focus states, and disabled or read-only states.", "Provide separate accessible names, values, and constraints for lower and upper thumbs; pair with endpoint number fields when exact review or typing matters." ], "uxGuidance": [ "Help users quickly narrow one numeric scale by setting both lower and upper limits while seeing the resulting active range.", "Prevent impossible endpoint order, show result impact, and choose date pickers or typed endpoint fields when range-slider interaction would hide important semantics." ], "uiExamples": { "good": [ "A nightly price range slider shows Minimum $120 and Maximum $280, a selected band between the thumbs, $0 and $500 endpoints, and paired endpoint fields.", "A departure-time filter keeps lower and upper handles separately focusable and displays the resulting time range." ], "bad": [ "A filter labelled Budget has one thumb and stores only a minimum price.", "A dual-thumb rail has no endpoint labels, values, units, or visible selected range." ] }, "uxExamples": { "good": [ "A user raises the minimum price, lowers the maximum price, sees the result count narrow, then widens the range after a few-results warning.", "A user types exact endpoints and both handles move while the submitted minimum and maximum remain ordered." ], "bad": [ "A user drags the lower handle beyond the upper handle and the filter submits an impossible range.", "A user tries to choose travel dates on a numeric rail and cannot see unavailable days or type a date." ] }, "problemContext": [ "The task is one numeric or relative scale with a lower and upper boundary.", "Users understand the scale as price, distance, duration, rating, speed, size, or another ordered numeric quantity.", "The interface can define min, max, step, unit, endpoint gap, and active range feedback.", "Filtering or previewing results benefits from quick coarse adjustment and visible endpoint review.", "The task is not selecting calendar dates, named categories, or a single value." ], "selectionRules": [ "Choose a range slider when users need both a minimum and maximum value on one known numeric scale.", "Use single slider when only one value is adjusted.", "Use paired text or number inputs when exact arbitrary endpoints, pasted values, currency precision, or very large ranges matter more than quick adjustment.", "Use date range picker when endpoints are dates or depend on calendar availability.", "Use filter panel when the range is one of several filters that need grouped apply, reset, saved, or mobile disclosure behavior.", "Keep both endpoints visible and programmatically named.", "Prevent the lower endpoint from passing the upper endpoint, or repair crossed input with explicit feedback.", "Avoid tiny ranges, binary choices, named categories, destructive actions, hidden filters, and scales whose units users cannot interpret." ], "requiredStates": [ "Initial state with visible label, min, max, unit, current lower endpoint, and current upper endpoint.", "Lower thumb focused state.", "Upper thumb focused state.", "Dragging or actively adjusting either endpoint.", "Keyboard increment state for each thumb.", "Exact endpoint typed state.", "Crossed endpoint prevention or repair state.", "Few or zero results state caused by a narrow range.", "Disabled dependency state.", "Read-only range review state.", "Mobile screen-reader interaction checked on both lower and upper thumbs before release." ], "interactionContract": [ "Each thumb controls one endpoint in a related value pair.", "The lower endpoint remains less than or equal to the upper endpoint, with any required minimum gap enforced.", "The visual selected band, text summary, number inputs, and submitted payload stay synchronized.", "Both thumbs remain in a stable tab order regardless of visual proximity.", "Changing one thumb updates the allowed aria minimum or maximum of the other when endpoints depend on each other.", "Warnings, no-results states, disabled state, and repaired crossings are announced without clearing the current range." ], "implementationChecklist": [ "Define min, max, step, unit, default lower endpoint, default upper endpoint, and minimum gap.", "Use an accessible multi-thumb implementation or pair native range inputs with clear labels and synchronized constraints.", "Provide visible endpoint values and paired number inputs when users need exact review.", "Update aria-valuemin and aria-valuemax on dependent thumbs as the opposite endpoint changes.", "Keep tab order lower endpoint then upper endpoint even when thumbs are close.", "Show result count, empty-result warning, reset or widen action, and applied filter summary when the range filters content.", "Test pointer drag, keyboard, touch, screen readers, high zoom, forced colors, RTL, mobile, and backend endpoint validation." ], "commonMisuses": [ "Using only one thumb for a task that needs two boundaries.", "Allowing endpoints to cross without repair or explanation.", "Hiding the exact minimum and maximum values.", "Using a range slider for dates instead of a calendar-aware date range picker.", "Using a range slider for three named choices or binary state.", "Filtering results instantly without showing the active range or a way to widen it.", "Changing tab order when the visual order of thumbs changes.", "Using an extremely large or highly precise range that users cannot control with the rail." ], "critiqueQuestions": [ "Are users setting two boundaries on one numeric scale?", "Can the product define meaningful min, max, step, unit, and endpoint gap?", "Do users need exact values, and if so are endpoint fields provided?", "What happens if a user types a minimum above the maximum?", "Will a narrow range produce few or zero results, and is recovery visible?", "Would a date range picker, paired number fields, filter panel, select, or single slider be clearer?" ], "relatedPatterns": [ "slider", "text-input", "date-range-picker", "filter-panel", "inline-validation" ], "comparisons": [ "range-slider-vs-slider-vs-text-input-vs-date-range-picker" ], "sourceIds": [ "wai-aria-apg-slider-multithumb", "carbon-slider-component", "material-web-slider-component", "uswds-range-slider-component", "visa-slider-component" ] }, { "id": "reactions", "completionStatus": "complete", "name": "Reactions", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Lightweight emoji feedback control anchored to an existing message, comment, issue, document selection, or work item", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Reaction systems become misleading when products hide who reacted, make reactions hover-only, treat informal emoji as approvals or assignments, trigger automations without disclosure, flood activity streams, or fail to expose counts and selected state accessibly.", "solution": "Provide item-anchored reaction chips with clear emoji names, counts, own-state highlighting, add and remove paths, who-reacted disclosure, picker and policy rules, grouped overflow, notification and activity behavior, and explicit boundaries for workflow triggers or consequential decisions.", "uiGuidance": [ "Render reactions as compact chips or controls attached to a specific item, showing emoji or reaction name, count, the current user's selected state, add-reaction access, remove behavior, and a way to inspect who reacted.", "Keep reaction controls distinct from comments, mentions, approvals, assignments, votes, and status tags by naming reaction intent, showing whether reaction counts are informal, and disclosing any workflow automation tied to a specific emoji." ], "uxGuidance": [ "Use reactions when users need a fast, low-friction way to acknowledge, support, celebrate, flag lightly, or express sentiment without creating a new reply.", "Protect interpretation by making add/remove reversible, avoiding overloading one emoji with hidden meaning, grouping noisy reactions in activity feeds, and routing consequential decisions to stronger patterns." ], "uiExamples": { "good": [ "A message row shows 👍 6, 👀 2, and Add reaction; the user's 👍 is highlighted, clicking it removes their reaction, and opening the count reveals who reacted.", "A Docs selection shows an emoji reaction anchored to highlighted text as a lightweight alternative to a comment, while full comments remain available for written feedback." ], "bad": [ "A thumbs-up chip is styled like a formal Approve button and commits a release without approver route, audit, or version context.", "A reaction count appears with no accessible name, no user list, no selected state, and no keyboard path to add or remove a reaction." ] }, "uxExamples": { "good": [ "A teammate adds 👀 to show they are looking at a message, sees their reaction highlighted, removes it after replying, and the activity feed groups the reaction event with other low-priority reactions.", "A team configures ❗ as a Teams workflow trigger and the reaction picker warns that the emoji will create a helpdesk escalation only in selected channels." ], "bad": [ "A user adds ✅ as casual acknowledgement, but an automation silently closes the task.", "A message receives thirty custom emoji and the important comment underneath is pushed out of view with no collapse or grouping." ] }, "problemContext": [ "Reactions can appear on chat messages, comments, pull requests, issues, discussions, document selections, canvas text, meeting chats, posts, files, and work items.", "Users may react to acknowledge, vote lightly, show sentiment, celebrate, signal that they are looking, avoid adding a reply, or trigger a product-defined workflow.", "Emoji choice may include default emoji, custom workspace emoji, skin tone modifiers, gender modifiers, one-click suggestions, recent emoji, restricted emoji, or admin-managed defaults.", "Reaction events may affect activity feeds, notification centers, workflow automation, moderation, analytics, accessibility output, and content density.", "The same emoji may carry different team conventions, so products must avoid implying stronger semantics than the system can enforce." ], "selectionRules": [ "Choose reactions when lightweight feedback can safely remain attached to an existing item and does not require a written reply.", "Use comments when users need text, rationale, evidence, questions, moderation, edit history, resolve state, or a reply thread.", "Use mentions when the job is to notify or route attention to people or groups.", "Use approval workflow when the decision is governed, versioned, audited, and made by eligible approvers.", "Use assignment when someone becomes responsible for doing work; a reaction should not create accountability unless the product explicitly models that side effect.", "Use activity feed to summarize reaction events across work; group repeated low-value reaction activity so it does not hide mentions or failures.", "Use notification center only for reaction events that should create durable unseen or unread items with user preferences.", "Show the current user's own reaction state separately from total count.", "Provide a way to see who reacted and handle privacy or permission-limited names honestly.", "Support add, remove, already-reacted, not-reactable, disabled-by-policy, offline, sync-failed, and custom-emoji-unavailable states.", "Disclose workflow triggers for specific emoji, including trigger scope, frequency, and who can trigger them.", "Collapse or summarize high-volume reaction sets without hiding the user's own reaction or important workflow-trigger emoji." ], "requiredStates": [ "No reactions state.", "One reaction added by current user state.", "Existing reaction by others state.", "Multiple emoji reaction chips with counts.", "Current user's reaction highlighted or selected state.", "Remove own reaction state.", "Add reaction picker open state.", "Who reacted disclosure state.", "Custom emoji, skin tone, and inaccessible emoji name states.", "Reaction overflow or collapsed count state.", "Reaction disabled, not-reactable, already-reacted, or permission-limited state.", "Workflow-trigger reaction warning state.", "Reaction notification or activity-feed grouping state.", "Mobile long-press reaction state.", "Offline or sync-failed reaction state." ], "interactionContract": [ "Each reaction attaches to one named source item and does not create a separate conversation by itself.", "Selecting an existing reaction chip adds the user's reaction if absent or removes their reaction if already selected, according to product policy.", "The count represents unique reaction records for that emoji and updates after add, remove, sync, or server rejection.", "The picker exposes searchable emoji names, recent or suggested reactions, custom emoji policy, and skin tone or identity preferences where supported.", "Who-reacted disclosure lists visible people or explains hidden/private reactors without leaking restricted identities.", "Reaction events synchronize with activity feed and notification center only when configured by product policy.", "Workflow-trigger emoji require a visible warning or configuration surface before casual reactions start automation.", "Keyboard and touch users can add, remove, inspect, and dismiss reactions without hover-only affordances." ], "implementationChecklist": [ "Define reaction target types, allowed emoji set, custom emoji policy, user identity, duplicate prevention, reaction count model, and remove behavior.", "Separate reaction records from comments, mentions, approvals, assignments, votes, statuses, presence, and notification records in the data model.", "Build add picker, one-click suggestions, selected state, remove action, count update, who-reacted disclosure, overflow grouping, and moderation or policy-disabled states.", "Model API errors such as already reacted, item not reactable, access denied, invalid target, deleted item, offline queue, and sync failure.", "Handle workflow-trigger emoji with explicit configuration, scope, frequency, eligibility, preview, and audit or activity output.", "Synchronize reaction events with activity feed, notification preferences, unread rules, analytics, and source-item rendering without flooding catch-up surfaces.", "Test keyboard controls, touch long-press, screen-reader names, custom emoji labels, skin tone modifiers, high counts, overflow collapse, permission-limited reactors, deleted users, and localization." ], "commonMisuses": [ "Using reactions as formal approvals without approver eligibility, audit trail, or version context.", "Treating reactions as assignments or commitments with no responsibility record.", "Hiding add reaction behind pointer hover only.", "Showing counts without who-reacted disclosure or privacy explanation.", "Using color or emoji shape alone without accessible names.", "Triggering workflow automation from a reaction without warning users.", "Letting reaction storms dominate message layout or activity feeds.", "Allowing custom emoji that undermine moderation, privacy, or accessibility policies." ], "critiqueQuestions": [ "What exactly does each reaction mean in this product, and what does it not mean?", "Can users add, remove, and inspect reactions with keyboard, touch, and assistive technology?", "Can users tell which reactions they personally added and who else reacted?", "Does any emoji trigger notifications, activity feed events, workflow automation, assignment, or status changes?", "How are custom emoji, skin tones, hidden reactors, deleted users, and permission-limited items represented?", "How are high-volume reactions grouped so they do not bury comments, mentions, or important work events?" ], "relatedPatterns": [ "comments", "mentions", "threaded-discussion", "activity-feed", "notification-center", "presence", "button-group", "tag" ], "comparisons": [ "reactions-vs-comments-vs-mentions-vs-activity-feed" ], "sourceIds": [ "slack-use-emoji-reactions", "slack-reactions-add-api", "github-rest-reactions", "google-workspace-docs-emoji-reactions", "microsoft-teams-emoji-reaction-workflows" ] }, { "id": "recently-searched", "completionStatus": "complete", "name": "Recently searched", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Passive history of submitted search queries that can be rerun", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users often need to repeat or refine a query they already submitted, but without a clear recent-search history they must remember exact wording or confuse passive query history with saved searches, suggestions, recommendations, or opened items.", "solution": "Provide a scoped, bounded recent-search list that records meaningful submitted queries, orders them by recency, reruns them predictably, and gives users removal, clearing, history-off, and privacy controls.", "uiGuidance": [ "Render recently searched as a labelled list of query strings the current user actually submitted, ordered newest first, with query text, scope or source, timestamp, and a clear affordance to rerun each query.", "Place remove-one, clear-all, and search-history on/off controls near the list, and distinguish recent queries from search suggestions, saved searches, recently viewed items, recommendations, and promoted queries." ], "uxGuidance": [ "Use recently searched to help users recall and repeat prior search paths without recreating exact wording, especially in large search surfaces where the same query may be useful later.", "Treat search history as personal and potentially sensitive; disclose account, browser, workspace, or device scope and let users remove or stop storing it without deleting saved searches or viewed records." ], "uiExamples": { "good": [ "A knowledge search box opens to Recently searched with benefit appeal deadline, housing evidence upload, and debt advice appointment, each showing scope, time, result count, and a remove control.", "A Gmail or Drive search surface shows suggestions from search history only when search history is on for the user.", "A product search autocomplete separates Recent searches from Popular searches and Query suggestions with distinct headings." ], "bad": [ "A list called Recent includes promoted queries, saved searches, recently viewed suppliers, and another user's sensitive query.", "The product records every keystroke in the search box as history before the user submits a query.", "Clear recent searches also deletes named saved searches and saved filters because all search-related lists share one destructive action." ] }, "uxExamples": { "good": [ "A user reruns benefit appeal deadline from recent searches and returns to the current result set without creating or modifying a saved search.", "A user removes housing evidence upload from recent searches, and only that query disappears while saved searches and viewed records remain intact.", "A user turns search history off; new searches still run, but no new queries are added to the recent list." ], "bad": [ "A shared kiosk shows a prior user's health search because the list has no account or device boundary.", "Users think a recent search is a managed saved search and expect it to update dashboard alerts.", "A popular query appears under Recently searched, making users think someone using their account searched for it." ] }, "problemContext": [ "The product has search boxes that users revisit over time, across sessions, or within a long task.", "Query wording matters enough that recalling an earlier submitted query saves effort.", "Search terms can reveal sensitive intent, work, health, finances, legal concerns, customers, or private projects." ], "selectionRules": [ "Choose recently searched when entries should be query strings the current user actually submitted, not possible suggestions or opened objects.", "Capture only meaningful submitted searches such as Enter, Search button, or selected recent-query rerun, not each keystroke or focus event.", "Order by most recent search time, deduplicate by normalized query plus scope, and move repeated searches to the top instead of duplicating them.", "Show enough context to rerun safely, including query text, scope, source, timestamp, and optionally current result count.", "Provide remove-one and clear-all controls that affect recent query history only.", "Expose search-history state and account, browser, device, or workspace scope when history can sync or persist across sessions.", "Hide the list or show an empty history state when no trustworthy recent searches exist rather than substituting popular searches under the same label.", "Use search suggestions when the user needs help forming a future query; use saved search when the user intentionally stores named criteria; use recently viewed when the history is opened items.", "Expire, cap, or avoid storing sensitive queries when the search surface is shared, signed out, regulated, or privacy-sensitive.", "Keep recent searches separate from autocomplete for constrained values such as people, addresses, codes, products, or entities." ], "requiredStates": [ "Empty or hidden state before any qualifying query has been submitted.", "Populated state with newest-first query history, scope, and timestamp.", "Rerun state where selecting a recent query restores query text and search scope.", "Remove-one state that deletes a single query from history only.", "Clear-all state that removes all visible recent queries for the stated scope.", "History off state where searches still run but new queries are not stored.", "Synced or account-scoped state when history can appear across devices or sessions.", "Sensitive or shared-surface state where history is hidden, short-lived, or explicitly disabled." ], "interactionContract": [ "Submitting a qualifying search writes or updates a recent-search entry for the current scope when history is on.", "Selecting a recent search reruns that query and scope, updates recency, and preserves the distinction from saved searches.", "Removing a recent search deletes only the query-history entry, not saved searches, saved filters, viewed items, results, or records.", "Clearing recent searches removes visible query history for the stated account, browser, device, or workspace scope.", "Turning search history off prevents future queries from being stored while still allowing search to run.", "The component must not show another user's queries unless a shared account or sync scope is explicit and controllable.", "Popular searches, recommendations, promoted queries, and query suggestions must not be labelled as recently searched unless they came from the user's submitted history." ], "implementationChecklist": [ "Define the event that stores a recent query, such as explicit search submit or selected recent-query rerun.", "Normalize query text and scope for deduplication while preserving the display string users recognize.", "Store scope, timestamp, and optional result count metadata so users can distinguish similar queries.", "Enforce a visible count limit and retention period appropriate to the device, account, and sensitivity of the surface.", "Provide remove-one and clear-all actions with copy that says search history rather than saved search or results.", "Respect signed-out mode, private browsing, managed-device settings, account sync, consent, and search-history off state.", "Separate Recent searches, Popular searches, Suggestions, Saved searches, and Recently viewed with headings and data-model boundaries.", "Refresh or clearly mark result counts when a recent query is rerun so stale counts do not mislead users.", "Test keyboard selection, removal focus, clear-all recovery, history-off behavior, mobile layout, shared-device privacy, and duplicate query handling." ], "commonMisuses": [ "Recording unsubmitted keystrokes as search history.", "Mixing recent searches with popular searches, promotions, saved searches, recent views, recommendations, or bookmarks.", "Showing private queries on shared devices or signed-out public surfaces.", "Providing no way to remove a single embarrassing or sensitive query.", "Clearing saved searches or saved filters when the user only meant to clear recent search history.", "Duplicating the same query every time it is rerun.", "Hiding search-history settings while using synced account activity.", "Showing old result counts as if they are current." ], "critiqueQuestions": [ "What exact action qualifies a query as recently searched?", "Can users tell whether an entry is passive history, a suggestion, a saved search, or a viewed item?", "What account, browser, device, workspace, or session scope does this history use?", "Can users remove one query and clear all history without deleting saved searches?", "Does turning history off stop future storage while preserving the ability to search?", "How are sensitive, signed-out, shared-device, or managed-account searches handled?", "Does rerunning a recent search restore the right query text, scope, filters, and current result count?" ], "relatedPatterns": [ "basic-search", "search-suggestions", "saved-search", "recently-viewed", "autocomplete", "search-scope-selector", "no-results-recovery", "recommendations" ], "comparisons": [ "recently-searched-vs-search-suggestions-vs-saved-search-vs-recently-viewed" ], "sourceIds": [ "algolia-autocomplete-recent-searches-plugin", "algolia-add-recent-searches", "google-workspace-search-history", "algolia-react-instantsearch-recent-searches" ] }, { "id": "recently-used", "completionStatus": "complete", "name": "Recently used", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "Automatic list of targets the current user meaningfully operated or used recently", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users repeatedly return to tools, files, commands, apps, workspaces, or tasks they actually operated, but broad navigation, search, and favorites can force them to reconstruct recent working context from memory.", "solution": "Provide a bounded, personal recently used list that records meaningful use events, orders targets by most recent use, identifies each target clearly, separates use history from views, favorites, pins, recommendations, and searches, and supports removal, clearing, privacy, sync, and stale-target recovery.", "uiGuidance": [ "Render a labelled Recently used area with target name, type, location or workspace, last-used time, use scope, availability, and a remove-from-recent-use control near each entry.", "Make the qualifying use event clear through context and labels: recently used tools, commands, files, apps, workspaces, or tasks should not be visually mixed with items merely viewed, favorited, pinned, recommended, or searched." ], "uxGuidance": [ "Use recently used when users benefit from returning to the tools, files, commands, apps, workspaces, or tasks they actually operated, especially in products with many possible work surfaces.", "Treat recent-use history as personal behavior data: cap it, expire it, let users remove or clear entries, expose device/account/workspace sync, and never turn it into a saved preference without deliberate user action." ], "uiExamples": { "good": [ "A document editor Insert link flow shows Recently used cloud files with file type, folder, last-used time, and a Browse all files option.", "A workspace launcher shows recently used tools with app name, workspace, last-used time, and a remove-from-recent-use action that leaves the tool installed.", "A mobile task switcher shows recently accessed tasks that can be resumed or removed from the switcher without uninstalling the app." ], "bad": [ "A Recent list contains tools the user hovered over, suggested starters, favorite files, and pinned dashboards with no reason or ordering rule.", "The product labels a list Recently used but fills it with promoted actions the user has never run.", "Removing a recently used workspace deletes the workspace instead of clearing the recency shortcut." ] }, "uxExamples": { "good": [ "A user reopens the Export invoices tool from Recently used after running it yesterday, sees it belongs to Finance, and removes an obsolete workspace shortcut without deleting anything.", "A user on a managed shared laptop clears recently used files before handing off the device and sees that Favorites and pinned files remain unchanged.", "A user selects a recently used cloud file from an insert-link flow instead of browsing the full document library again." ], "bad": [ "A reporting app treats viewing a dashboard as using it, so the recently used tools list fills with dashboards the user only inspected.", "An AI assistant auto-adds recommended actions to Recently used before the user runs them, making the history look like a recommendation rail.", "A recent-use shortcut to a moved file fails with a broken link and no remove or browse-again recovery." ] }, "problemContext": [ "The product has many tools, files, commands, apps, workspaces, forms, starter flows, reports, or task surfaces users may operate repeatedly.", "Use events are stronger than impressions or views because they indicate the user actually ran, selected, edited, inserted, launched, resumed, or completed work with the target.", "Recent-use history can reveal sensitive work, internal projects, customer records, financial files, health contexts, or shared-device behavior.", "Recently used targets can be renamed, moved, removed, restricted, archived, duplicated, superseded, synced across devices, or confused with favorites, pins, recommendations, and search history." ], "selectionRules": [ "Choose recently used when a meaningful use event should create a temporary return shortcut for the current user.", "Use recently viewed when the list should record opened or inspected content, even if the user did not operate a tool or complete work with it.", "Use favorites when users deliberately mark a preferred item for durable saved access.", "Use pinned items when the item should remain in a stable prominent position or user-controlled order.", "Use recommendations when the system proposes next actions based on model, rule, popularity, or context rather than the user's own last use events.", "Use search history when the remembered object is a submitted query, not the target that was used after the query.", "Record only meaningful use events such as launch, insert, run, edit, export, submit, resume, or select; avoid counting hover, preview, impression, suggestion display, or accidental focus.", "Deduplicate by stable target ID, move reused targets to the top, cap visible count, and expire entries according to the task's memory window.", "Expose account, device, workspace, and shared-device scope when recently used entries sync or could appear outside the immediate session.", "Keep remove and clear actions explicitly scoped to recent-use history so users do not fear deleting the target or changing favorites, pins, or subscriptions." ], "requiredStates": [ "Empty or hidden state before any qualifying use event exists.", "Populated state with most-recent-first ordering and recognizable target identity.", "Just-used state that moves the reused target to the top instead of duplicating it.", "Remove-one and clear-all states that affect only recent-use history.", "Device-scoped, account-synced, workspace-scoped, private-mode, and managed-device states when those scopes exist.", "Unavailable, moved, renamed, archived, permission-lost, stale, and duplicate-name target states.", "Mobile or narrow-screen state where target identity, scope, and remove controls remain reachable." ], "interactionContract": [ "A qualifying use event writes or updates a recent-use entry for the current user and declared scope.", "Using the same target again updates recency and moves it to the top instead of creating duplicates.", "Opening a recently used entry resumes or launches that exact target, command, app, file, workspace, or task if still available.", "Removing an entry removes only the recent-use reference and leaves the target, favorite state, pin state, subscription state, and search history intact.", "Clearing recently used entries empties the visible recent-use history for the declared scope and does not clear recently viewed, favorites, pinned items, saved views, or saved searches.", "Unavailable or permission-lost entries remain explainable with remove, request-access, browse-again, or replace paths.", "The component is omitted or privacy-protected when recent-use history is disabled, private, signed out, or unsafe to show on shared screens." ], "implementationChecklist": [ "Define the exact use events that write history for each target type, such as launched tool, inserted file, submitted command, opened app task, edited document, or selected workspace.", "Store stable target ID, target type, display name, location, scope, last-used time, use source, availability, and permissions rather than copied labels alone.", "Deduplicate entries by target ID, update the last-used timestamp, enforce visible count and lifetime limits, and handle least-recently-used removal when limits are reached.", "Label the list by scope, such as Recently used in this workspace, Recently used on this device, or Recently used in your account.", "Provide remove-one, clear-all, pause or disable history, and browse-all alternatives when the list is empty, stale, or privacy-sensitive.", "Refresh target metadata before rendering or navigating and mark moved, deleted, archived, renamed, or restricted targets clearly.", "Test keyboard operation, mobile wrapping, long names, duplicate names, clear scope, sync across devices, shared-device exposure, failed recency writes, and stale-target repair." ], "commonMisuses": [ "Counting views, hovers, previews, suggestions, ads, or recommendations as use.", "Mixing recently used with recently viewed, favorites, pinned items, search history, saved views, subscriptions, or recommendations in one ambiguous list.", "Letting remove or clear delete the underlying file, app, command, workspace, or task.", "Showing sensitive recent-use history on shared, public, signed-out, or screen-shared surfaces without controls.", "Keeping an unlimited history until the list becomes an activity log rather than a return shortcut.", "Leaving stale recently used entries as dead links." ], "critiqueQuestions": [ "What exact action proves the user used this target instead of merely seeing or viewing it?", "Can users tell whether the entry is a file, command, app, workspace, task, or tool before reopening it?", "What scope controls where this recent-use history appears: device, account, workspace, browser, or managed profile?", "Can users remove or clear the shortcut without deleting the target or changing pins and favorites?", "How long should a recent-use shortcut remain useful before it expires?", "What recovery appears when the recently used target has moved, changed permission, or become unavailable?" ], "relatedPatterns": [ "recently-viewed", "recently-searched", "search-history", "favorites", "pinned-items", "recommendations" ], "comparisons": [ "recently-used-vs-recently-viewed-vs-favorites-vs-pinned-items" ], "sourceIds": [ "microsoft-office-recent-files", "microsoft-office-add-links-recent-files", "android-recents-screen", "microsoft-office-pin-frequently-used-files" ] }, { "id": "recently-viewed", "completionStatus": "complete", "name": "Recently viewed", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Automatic list of items the current user opened recently", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users often need to return to a specific item they recently opened, but search, browser Back, and site hierarchy can make them reconstruct the path from memory.", "solution": "Provide a bounded, personal recently viewed list that records actual item views, orders them by recency, gives recognizable item context, and offers removal, clearing, privacy, and unavailable-item handling.", "uiGuidance": [ "Render a labelled list or rail of items the current user actually opened, ordered most recent first, with enough identity to recognize each item such as name, type, thumbnail or icon, location, status, and last-viewed time.", "Include bounded history controls near the list: remove an item, clear the list, hide the section when empty, and disclose account or device sync scope when entries may appear across sessions." ], "uxGuidance": [ "Use recently viewed to reduce re-finding effort when users compare items, pause work, resume documents, or return to records they inspected during the current or recent sessions.", "Treat viewing history as personal and potentially sensitive; keep it short-lived when the task does not need long memory, avoid showing it on shared or public surfaces, and never replace deliberate saved items or recommendations with it." ], "uiExamples": { "good": [ "A procurement dashboard shows Recently viewed records with title, record type, status, project, last-viewed time, and a remove control for each row.", "A commerce product page shows a short Recently viewed rail of products the shopper opened, capped to six items and hidden until at least one product exists.", "A document app separates Recent files from Favorites and shows folder context so files with the same name are not confused." ], "bad": [ "A homepage shows a Recently viewed carousel filled with promoted products the user never opened.", "A shared kiosk displays sensitive applications from previous users with no clear or hide control.", "A recent-items list shows identical titles with no type, location, status, or last-viewed context." ] }, "uxExamples": { "good": [ "A user opens several supplier records, returns to the dashboard, and reopens the most recent record without reconstructing the search.", "A shopper compares products across pages and can jump back to a previously viewed item without using browser Back repeatedly.", "A user on a shared account removes an unexpected document from the recent list and understands that Favorites are stored separately." ], "bad": [ "Users trust a Recently viewed rail as a recommendation and choose an irrelevant item because sponsored content was mixed into history.", "A user clears browser history but the product still displays old local recently viewed entries on a shared device.", "A workflow uses recent items as its only navigation, so users cannot find records they have not opened yet." ] }, "problemContext": [ "The product contains many comparable or revisitable objects such as records, documents, products, cases, media, or projects.", "Users commonly inspect several items before choosing, pausing, resuming, or comparing them.", "Viewing history can reveal user intent, private work, shopping, health, finance, or shared-device activity." ], "selectionRules": [ "Choose recently viewed when the destination set should come from items the current user personally opened, not from editorial curation, hierarchy, popularity, or recommendation models.", "Record only meaningful item views, not every hover, preview, scroll, or page refresh; update an existing item to the top instead of duplicating it.", "Order items most recent first, cap the visible list, and expire entries according to the task's memory window.", "Show enough context to identify the item before navigation, including type, status, location, last-viewed time, thumbnail, or owner when those details prevent mistakes.", "Provide item removal and list clearing when recents are visible outside a private workspace, synced across devices, or likely to reveal sensitive behavior.", "Separate recently viewed from Favorites, saved items, bookmarks, pinned items, related links, and recommendations because those imply different user intent.", "Hide the section when no trustworthy recent items exist instead of filling it with popular or promoted content.", "Handle unavailable, moved, deleted, permission-lost, or out-of-stock items with clear status and recovery rather than dead links." ], "requiredStates": [ "Empty or hidden state before any qualifying item has been viewed.", "Populated state with most-recent-first ordering and recognizable item context.", "Active or just-opened state showing which item was resumed from the list.", "Remove-one state that deletes a single item from recent history without deleting the item itself.", "Clear-all state that empties recent history and explains the effect.", "Unavailable-item state for deleted, moved, permission-lost, or out-of-stock entries.", "Synced or account-scoped state when entries can appear across devices or sessions." ], "interactionContract": [ "Opening an item from the list navigates to that exact item and moves it to the top of the recent list.", "Viewing the same item again updates its recency instead of creating duplicates.", "Removing a recent entry removes only the history reference, not the underlying item.", "Clearing the list removes visible recent history for the defined scope and leaves saved items or favorites intact.", "The component does not show items viewed by another user unless the account or shared-device scope is explicit.", "The list is omitted when there is no valid recent history or when privacy settings disable history capture." ], "implementationChecklist": [ "Define the qualifying event that writes history, such as opening a detail page for a minimum time or completing a load.", "Store a stable item ID with display metadata that can be refreshed, not only copied text that will become stale.", "Deduplicate by item ID, move re-opened items to the top, and enforce a visible count or lifetime cap.", "Label the section with the scope, such as Recently viewed in this workspace or Recently viewed on this device.", "Provide remove and clear controls with copy that distinguishes history removal from item deletion.", "Respect private browsing, signed-out, managed-device, consent, and account-sync settings.", "Refresh or mark unavailable entries before navigation so stale links do not fail without explanation.", "Keep the rail keyboard-accessible and avoid auto-advancing carousels that hide older recent items." ], "commonMisuses": [ "Filling recently viewed with recommendations, ads, popular items, or related content.", "Showing sensitive history on shared screens, public kiosks, or signed-out experiences.", "Making recent items permanent when users expect a short session memory.", "Mixing automatic recents with saved, pinned, or favorite items.", "Duplicating the same item every time it is opened.", "Using browser click path as breadcrumbs or recently viewed as the only wayfinding tool.", "Removing the underlying item when the user only meant to remove it from history." ], "critiqueQuestions": [ "What exact user action qualifies an item as viewed?", "Can users recognize each recent item without reopening it?", "What is the right count, lifetime, and account scope for this task?", "What privacy harm occurs if this list appears on a shared device or screen share?", "How can users remove an unexpected item without deleting the item itself?", "Is the team using recency to mask weak search, filters, saved items, or recommendations?" ], "relatedPatterns": [ "related-links", "breadcrumbs", "back-link", "basic-search", "search-suggestions" ], "comparisons": [ "recently-viewed-vs-related-links-vs-breadcrumbs" ], "sourceIds": [ "uxpin-recently-viewed-pattern", "microsoft-office-recent-files", "android-recents-screen", "adobe-commerce-recently-viewed-products", "w3c-privacy-principles" ] }, { "id": "recommendations", "completionStatus": "complete", "name": "Recommendations", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Ranked suggestions generated from context, behavior, item similarity, popularity, editorial rules, or recommendation models", "maturity": "standard", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Users can struggle to discover useful items in large catalogs, content libraries, workflows, or feeds, but opaque recommendation rails can mislead them when the basis, availability, commercial influence, or personalization control is hidden.", "solution": "Provide recommendations as clearly labelled, bounded suggestions with item-specific reasons, source and sponsorship disclosure, feedback controls, personalization settings, cold-start fallbacks, and filtering for unavailable or inappropriate items.", "uiGuidance": [ "Render recommendations as a labelled set of suggested items with clear item identity, recommendation reason, source or basis, availability, and a visible way to dismiss or tune at least the current item.", "Separate organic, sponsored, editorial, manual, personalized, trending, and fallback recommendations with text labels before users act, and avoid implying that recommended items were viewed, saved, or required." ], "uxGuidance": [ "Use recommendations to reduce discovery effort when the system has evidence that a small set of items, products, services, content, or next actions may be useful in the user's current context.", "Give users agency over personalization by supporting Not interested, hide, feedback reason, history or activity controls, reset, and cold-start fallback states rather than treating model output as an unchallengeable answer." ], "uiExamples": { "good": [ "A benefits dashboard shows Recommended for you with cards labelled Because you saved appeals guidance, Popular with benefits caseworkers, and Editorial fallback for Benefits, each with Not interested and Save controls.", "A commerce product page shows Pairs well with this camera, hides out-of-stock accessories, limits the rail to three visible items, and marks manually selected merchant recommendations separately from generated recommendations.", "A video feed exposes Not interested, Don't recommend channel, and activity controls so users can tune future recommendations." ], "bad": [ "A carousel says You will love this, hides that the first card is sponsored, and gives no reason or dismissal control.", "A recently viewed rail contains predicted items the user never opened.", "A recommendation list keeps showing unavailable, out-of-stock, permission-restricted, or already dismissed items because the UI only validates card shape." ] }, "uxExamples": { "good": [ "A user hides a benefits recommendation as Not interested, chooses a reason, and the list immediately replaces it with a lower-ranked item without changing their recently viewed history.", "A signed-out shopper sees Popular in backpacks rather than fake personalized copy, then gets personalized reasons only after activity exists and consent settings allow it.", "A caseworker turns off recent-activity personalization and the recommendations switch to a labelled generic fallback while saved items remain separate." ], "bad": [ "Users assume recommendations are mandatory next steps because the UI mixes them with required workflow tasks.", "A user repeatedly dismisses a sensitive topic, but the model keeps resurfacing it with new wording.", "A product says Based on your activity but offers no way to inspect, delete, or stop using that activity." ] }, "problemContext": [ "The product has enough content, products, records, services, or actions that manually browsing every option is inefficient.", "The system has useful signals such as current item context, similar-item attributes, aggregate behavior, purchases, saved items, search activity, editorial rules, or user feedback.", "Recommendations can affect user trust, privacy, commercial outcomes, safety, fairness, or task completion, so users need to understand and control what is being suggested." ], "selectionRules": [ "Choose recommendations when the system ranks a small set of likely useful items from behavior, context, similarity, popularity, rules, or model output.", "Use related links instead when the current page only needs a curated, maintained set of onward destinations and no ranking or personalization is involved.", "Use recently viewed instead when the list should contain only items the current user actually opened, ordered by recency.", "Use browse by category instead when users need to inspect a stable taxonomy and choose their own path.", "Show a reason for each recommendation, such as Because you saved this, Frequently bought together, Similar to this product, Trending in this category, or Curated by editors.", "Provide item-level feedback such as Not interested, Don't recommend this source, hide, remove, or tell us why, and make the immediate effect visible.", "Expose personalization scope and controls when recommendations use watch history, search history, saved items, purchases, account activity, location, team behavior, or other personal data.", "Label sponsored, promoted, manually selected, editorial, and model-generated recommendations separately before the click.", "Use cold-start fallbacks honestly, such as popular, trending, category-based, or editorial picks, instead of fabricating personalized explanations.", "Filter or mark unavailable, out-of-stock, permission-restricted, already completed, already in cart, already saved, duplicate, stale, and repeatedly dismissed items.", "Cap repetition, diversify the set, and avoid sensitive or protected-attribute inferences unless the product has an explicit, user-benefiting, compliant reason.", "Measure recommendation quality with user outcomes, feedback, availability, diversity, and trust, not only impressions or clicks." ], "requiredStates": [ "Default recommended state with labelled section, item identity, reason, source, and action controls.", "Personalized state that identifies the activity or preference category used without exposing private raw history unnecessarily.", "Generic or cold-start fallback state labelled as popular, trending, category-based, or editorial.", "Dismissed or Not interested state that removes the item and confirms the feedback effect.", "Feedback reason state for already watched, not relevant, don't like this source, duplicate, sensitive, or wrong category.", "Sponsored or promoted state with visible disclosure separate from organic recommendations.", "Manual or editorial recommendation state when a human has pinned, selected, or overridden model output.", "Unavailable or filtered state for out-of-stock, permission-lost, completed, already-in-cart, stale, or unsafe items.", "Personalization off or reset state that stops using selected activity and explains what fallback remains." ], "interactionContract": [ "Opening a recommendation navigates to that item or action and records the event according to the disclosed analytics and personalization rules.", "Dismissing a recommendation hides that item immediately from the current set and updates future ranking or feedback data within the stated scope.", "Feedback controls affect recommendation behavior only; they do not delete the underlying item, saved item, or recently viewed history unless that action is separately labelled.", "Turning off personalization stops using the selected activity source and switches to a clearly labelled generic or editorial fallback.", "Reason labels must match the actual source of the recommendation and must update when personalization, category, cart, current item, or availability changes.", "Sponsored or promoted recommendations remain distinguishable even when they are also relevant.", "The system must not reinsert dismissed, unavailable, permission-restricted, or sensitive recommendations as if they were new suggestions." ], "implementationChecklist": [ "Define the recommendation source for each slot: current item similarity, frequently bought together, trending, saved-item affinity, user activity, editorial rule, sponsored placement, or fallback.", "Store enough metadata to explain each recommended item in user-facing language without revealing private raw history or unsupported model claims.", "Apply eligibility filters before rendering for availability, permissions, stock, price, cart membership, completion state, safety, duplication, and policy restrictions.", "Add item-level dismissal, feedback reasons, and source-level suppression where users naturally need control.", "Provide personalization settings for the activity sources the recommendation system uses, including reset, history deletion, or turning history off when supported.", "Design cold-start and low-confidence states with honest labels and enough quality guardrails to avoid empty or fake personalized rails.", "Separate generated, manual, editorial, sponsored, and promoted items in the data model so the UI can disclose them consistently.", "Limit count, repetition, and carousel depth; avoid auto-advancing rails that hide feedback controls.", "Log recommendation impressions, opens, dismissals, source labels, availability filters, and feedback outcomes so quality can be audited beyond click rate.", "Test signed-out, new-user, returning-user, personalization-off, dismissed-item, unavailable-item, sponsored, sensitive-topic, and mobile keyboard states." ], "commonMisuses": [ "Counting schema-valid recommendation cards as complete without reasons, controls, or source disclosure.", "Calling promoted or sponsored content recommended without visible disclosure.", "Pretending generated suggestions are recently viewed, saved, or required steps.", "Using vague labels such as For you or You might like without explaining the basis.", "Ignoring dismissals and repeatedly showing the same item under new wording.", "Using personal data for recommendations without a visible control surface.", "Showing stale, unavailable, out-of-stock, permission-restricted, or already completed items.", "Optimizing only for clicks and creating repetitive, sensational, or narrow recommendation loops." ], "critiqueQuestions": [ "What exact signal or rule caused this item to be recommended?", "Can users tell whether the item is organic, sponsored, manual, editorial, personalized, trending, or fallback?", "What happens when the user says Not interested, and how quickly does the list change?", "Can users turn off or reset the activity source used for personalization?", "How are cold-start users handled without fake personalized copy?", "Which unavailable, sensitive, duplicate, completed, or repeatedly dismissed items are filtered before rendering?", "Is this really a recommendation, or would related links, recently viewed, saved items, or browse by category be more honest?" ], "relatedPatterns": [ "related-links", "recently-viewed", "browse-by-category", "basic-search", "saved-search", "prompt-suggestions", "search-suggestions", "filter-panel", "search-result-highlighting" ], "comparisons": [ "recommendations-vs-related-links-vs-recently-viewed-vs-browse-by-category" ], "sourceIds": [ "youtube-recommendation-controls", "youtube-how-recommendations-work", "shopify-search-discovery-product-recommendations", "shopify-complementary-product-recommendations", "algolia-recommend-overview", "microsoft-human-ai-guidelines" ] }, { "id": "recommended-next-action", "completionStatus": "complete", "name": "Recommended next action", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "Context-sensitive workflow action suggested for the user's current record, case, conversation, or task", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Users working in complex cases, records, conversations, or workflows often need to decide what to do next, but raw data, long histories, and broad recommendations can leave the next concrete action ambiguous or risky.", "solution": "Provide a contextual recommended next action that explains why it is suggested now, what evidence or rule triggered it, what will happen if accepted, whether prerequisites and permissions are satisfied, and how users can review, accept, defer, dismiss, or give feedback.", "uiGuidance": [ "Render the recommended next action as a bounded suggestion card or action slot that names the action, trigger context, expected outcome, owner, due time or urgency, eligibility status, and why the system is suggesting it now.", "Place accept, review, defer, dismiss, and feedback controls near the action, and label whether the suggestion came from a rule, AI model, playbook, similar case, customer intent, policy, or business strategy." ], "uxGuidance": [ "Use recommended next action when the user is already working in a case, conversation, record, or workflow and the system can propose the next concrete step that reduces decision effort without removing user judgment.", "Keep recommended next action separate from broad recommendations, task lists, primary buttons, assignments, approvals, and review queues because it is optional, contextual, explainable, and directly tied to the current work state." ], "uiExamples": { "good": [ "A support case sidebar recommends Send refund-policy article because the customer asked about a refund twice, shows confidence, source snippets, and opens a draft for review.", "A sales record suggests Offer retention discount because contract value is high and churn risk is elevated, with Review offer, Defer, Dismiss, and Why this action controls.", "A service workspace card recommends Check similar case after matching product, error code, and environment, but marks it blocked when the similar case is restricted." ], "bad": [ "A large Continue button is labelled Recommended without any trigger, reason, consequence, or alternative.", "An AI suggestion says Close case now without showing stale status, missing customer reply, confidence, or review step.", "Required onboarding tasks and optional suggestions are mixed in one list labelled Next best actions." ] }, "uxExamples": { "good": [ "A representative reviews the suggested reply, sees that it was triggered by customer intent and a matching knowledge article, edits the draft, and sends it.", "A case owner dismisses a recommendation as already handled, and the case remains open while future suggestions avoid repeating the same action.", "A manager sees that an action is blocked by permission and routes the case to an eligible teammate instead of attempting a hidden failure." ], "bad": [ "A user accepts a suggested discount and only afterward learns it changed contract terms.", "A recommendation keeps resurfacing after dismissal because the system never records feedback or current status.", "The system recommends contacting a customer even though the record says they opted out of that channel." ] }, "problemContext": [ "The user is already inside a work object such as a case, conversation, claim, sales record, incident, renewal, lead, approval, or task.", "The system has signals such as customer intent, status changes, similar cases, policy rules, playbooks, churn risk, SLA risk, missing fields, conversation history, or model output.", "The suggested action can have consequences such as sending a message, changing status, applying an offer, opening a workflow, escalating, requesting information, or resolving a case.", "A bad recommendation can cause wrong work, duplicate work, privacy leakage, compliance violations, customer harm, or loss of trust." ], "selectionRules": [ "Choose recommended next action when the system proposes a concrete action that is immediately relevant to the current work object and user role.", "Use recommendations when the surface suggests multiple discoverable items or content options rather than one actionable workflow step.", "Use task list when the steps are known required tasks with persistent completion status rather than inferred or contextual suggestions.", "Use review queue when the user needs to triage many actionable records rather than decide the next step for one current record.", "Use approval workflow when a routed approve or reject decision is required by policy instead of recommended by context.", "Use assignment when the decision is who owns the work rather than what action should happen next.", "Use handoff summary when transfer context and ownership are primary; include next action inside the handoff rather than replacing the summary.", "Show the trigger, evidence, reason, confidence or rule basis, eligibility, consequence, and scope before the user accepts the action.", "Require review or confirmation when the action sends external communication, changes money, closes work, updates legal status, changes permissions, or affects another person.", "Suppress or block suggestions when prerequisites, consent, permissions, freshness, policy, duplicate work, or user role make the action unsafe.", "Let users defer, dismiss, mark already done, give a reason, or choose another action without corrupting required workflow state." ], "requiredStates": [ "No recommendation state with normal workflow controls still available.", "Recommended action state with action title, reason, evidence, trigger, consequence, and accept or review path.", "Review-before-apply state for messages, status changes, offers, escalations, and high-impact actions.", "Accepted, deferred, dismissed, already-done, feedback-submitted, and replacement-suggestion states.", "Low-confidence, rule-based, AI-generated, human-curated, and playbook-driven recommendation states.", "Blocked by permission, missing prerequisite, stale data, duplicate work, policy conflict, consent conflict, and already-completed states.", "Mobile or narrow-screen state where the reason, consequence, and controls remain visible before accept." ], "interactionContract": [ "Accepting or reviewing the recommendation opens the proposed action with context preserved and does not silently commit high-impact changes.", "Dismissing a recommendation removes only the suggestion and records feedback within the stated scope; it does not delete the underlying record or required tasks.", "Deferring keeps the action explainable and returns it at the chosen time or state change without hiding alternatives.", "When the recommendation reason changes, the visible reason and eligibility update before the action can be accepted.", "Blocked suggestions cannot be accepted until the missing permission, prerequisite, consent, or freshness issue is resolved.", "Feedback, dismissal, accept, and failure outcomes are announced through a stable status region and logged for audit where the action has operational consequence.", "Users can always access the ordinary workflow path if no suggestion is safe or useful." ], "implementationChecklist": [ "Define the action model with action ID, source, trigger, evidence, score or rule, owner, role eligibility, consequence, prerequisites, freshness, and audit needs.", "Separate suggested action state from required task state, assignment state, approval state, broad recommendations, notifications, and primary action buttons.", "Provide reason and evidence copy that maps to real signals such as customer intent, similar case, SLA risk, missing field, policy rule, or playbook step.", "Gate high-impact actions behind review, confirmation, or draft editing and show what object, person, amount, channel, or status will change.", "Add controls for accept, review, defer, dismiss, already done, feedback reason, and fallback action.", "Revalidate permissions, prerequisites, consent, duplicate work, and stale data immediately before applying the action.", "Test low confidence, stale recommendation, missing permission, policy conflict, already handled, replacement suggestion, mobile wrapping, keyboard flow, and failure recovery." ], "commonMisuses": [ "Calling a static primary button a recommended next action without context-sensitive logic or reason.", "Hiding why the action was suggested, what evidence was used, or what will change.", "Mixing required tasks, optional suggestions, assignments, approvals, and queue rows in one undifferentiated list.", "Letting dismiss hide a required task or delete the underlying work item.", "Applying high-impact actions instantly without review, confirmation, or undo where appropriate.", "Showing stale, permission-blocked, duplicate, consent-conflicting, or already-completed suggestions as active actions.", "Presenting low-confidence AI output as the only safe path." ], "critiqueQuestions": [ "What exact signal, rule, model, or playbook caused this action to be recommended now?", "Can the user see what will happen if they accept the action before it commits?", "Is this optional guidance, a required task, an approval, an assignment, or a queue item?", "What permissions, prerequisites, consent, freshness checks, and duplicate-work checks gate the action?", "Can users dismiss, defer, mark already done, or give feedback without damaging workflow state?", "What ordinary workflow path remains available when the recommendation is wrong or absent?" ], "relatedPatterns": [ "recommendations", "task-list", "review-queue", "approval-workflow", "assignment", "handoff-summary" ], "comparisons": [ "recommended-next-action-vs-recommendations-vs-task-list-vs-review-queue" ], "sourceIds": [ "microsoft-dynamics-smart-assist", "microsoft-dynamics-view-smart-assist-suggestions", "salesforce-einstein-next-best-action-component", "shopify-search-discovery-product-recommendations" ] }, { "id": "redo", "completionStatus": "complete", "name": "Redo", "category": "Error Prevention And Recovery", "patternType": "ux", "surfaceType": "Forward edit-history replay", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can undo too far, change their mind after an undo, or need to reapply a reversible edit without reconstructing the work manually.", "solution": "Maintain a redo stack after undo, expose Redo only when a valid undone operation exists, replay the latest undone operation against the same target, and clear or branch that stack when new edits invalidate the future history.", "uiGuidance": [ "Show Redo as a visible command, menu item, toolbar control, or command-palette row whose enabled state matches the current redo stack.", "Name the operation or target when possible, such as Redo move heading, and show a disabled or unavailable state when no undone operation can be reapplied." ], "uxGuidance": [ "Use redo to let users recover from undoing too far without recreating work by hand.", "Treat redo as a valid future branch only until the user makes a new edit or the original target can no longer be replayed reliably." ], "uiExamples": { "good": [ "A document toolbar shows Undo and Redo; Redo is disabled until the user undoes Move Summary before Risk.", "After an undo, the history panel lists Redo available: Move Summary before Risk and clears that row when the user makes a new edit." ], "bad": [ "A Redo button remains enabled after the user types new content, with no indication that the old future branch is gone.", "Redo is available only through a keyboard shortcut and gives no visible disabled, unavailable, or target-specific state." ] }, "uxExamples": { "good": [ "A user moves a heading, chooses Undo, sees Redo move heading become available, and redoes the same move against the same document outline.", "A user undoes a move, types a new note, and sees the redo stack cleared because the edit history has branched." ], "bad": [ "A user undoes a move, selects a different heading, presses Redo, and the product applies the old operation to the wrong target.", "A user returns after reload and the interface still implies redo is available even though the in-memory edit stack is gone." ] }, "problemContext": [ "The product supports reversible editing, ordering, formatting, drawing, document, layout, or configuration actions.", "Users can issue repeated undo commands and may need to recover from undoing one step too many.", "The system can store enough operation and target state to replay the undone action accurately.", "New edits after undo create a divergent state unless the product has an explicit branching history model." ], "selectionRules": [ "Choose redo when the user has just undone a reversible operation and may need to reapply it.", "Expose redo next to undo in editor toolbars, menus, command palettes, or keyboard help when editing workflows are central.", "Disable or hide redo when no undone operation exists, but keep the availability discoverable in command-rich desktop-style products.", "Clear the redo stack when the user makes a new edit after undo unless the product provides explicit branch history.", "Replay the latest undone action in last-in-first-out order and preserve target identity, ordering, selection, and scope.", "Use a history panel, revision history, restore from trash, or draft state when users need long-lived recovery across sessions rather than immediate redo.", "Do not offer redo for operations whose external effects, permissions, payments, emails, or webhooks cannot be safely replayed or recalled.", "Do not make keyboard shortcuts the only redo path in interfaces that also support mouse, touch, or assistive technology workflows." ], "requiredStates": [ "No-redo state before any undo has happened.", "Undo-available state after a reversible edit.", "Redo-available state after the user undoes an operation.", "Redone state after the latest undone operation is reapplied.", "Branch-cleared state after a new edit while redo was available.", "Multi-step redo state where repeated Redo replays the redo stack in order.", "Target-invalid state when the original object, selection, or collaborator context can no longer accept replay." ], "interactionContract": [ "Redo is unavailable until an undo places an operation on the redo stack.", "Activating Redo replays the most recent undone operation and returns that operation to the undo stack.", "The command label, tooltip, menu item, status row, or history panel identifies the operation when ambiguity is possible.", "A new edit after undo clears redo or creates an explicit branch that users can see and choose.", "Keyboard shortcuts, toolbar controls, menus, and command palette entries reflect the same enabled or disabled state.", "If the original target is deleted, locked, changed by another user, or otherwise invalid, Redo explains why replay is unavailable.", "Redo does not silently repeat unrelated commands or destructive external effects." ], "implementationChecklist": [ "Represent undo and redo as separate stacks or equivalent operation history with target identity and scope.", "Push operations from undo to redo only after a successful undo, and push them back to undo after successful redo.", "Clear redo on new edits unless the product intentionally supports visible history branches.", "Keep visible controls, menu labels, command palette rows, shortcut help, and disabled states synchronized with the stack.", "Store enough object, ordering, selection, and collaborator context to reject stale redo rather than applying it to the wrong target.", "Announce redo availability, redone outcomes, cleared branch state, and invalid replay states in a status region.", "Test repeated undo and redo, target deletion, route changes, collaboration updates, keyboard shortcuts, and disabled states." ], "commonMisuses": [ "Leaving redo enabled after a new edit invalidates the undone future.", "Applying redo to the current selection instead of the original operation target.", "Treating redo as persistent restore or version rollback without showing durable history.", "Hiding redo behind a shortcut with no visible command state.", "Using Redo to mean repeat last command even when users expect reapply undone change.", "Offering redo for external side effects that cannot be safely replayed." ], "critiqueQuestions": [ "What operation enters the redo stack when the user undoes this action?", "What exact event clears redo, and how does the interface tell users that the branch changed?", "Can Redo identify the original target if selection, ordering, permissions, or collaboration state changed?", "Do visible controls and keyboard shortcuts expose the same availability?", "Does Redo reapply an undone action, or is it actually repeat last command, restore from trash, or version rollback?" ], "relatedPatterns": [ "undo", "draft-state", "command-palette" ], "comparisons": [ "redo-vs-undo-vs-draft-state-vs-command-palette" ], "sourceIds": [ "apple-hig-undo-redo", "vscode-default-keybindings", "microsoft-windows-keyboard-shortcuts" ] }, { "id": "regenerate-retry", "completionStatus": "complete", "name": "Regenerate / retry", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "AI response regeneration and same-turn retry control with version and context preservation", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI users often need to retry a failed answer or ask for another generated version, but a plain retry control can hide whether the same prompt, model, context, sources, tools, citations, and partial output are being reused or changed.", "solution": "Provide explicit regenerate and retry controls that preserve the original prompt and output version, explain what will rerun, distinguish same-prompt retry from new answer regeneration, show attempt and cooldown state, protect prior versions, and connect changed outputs to source, tool, citation, and edit review surfaces.", "uiGuidance": [ "Render regenerate / retry as a response-level control that names whether it will rerun the same prompt, continue after failure, regenerate a new answer version, or retry failed tool and source work.", "Show the prompt snapshot, carried context, source scope, tool scope, model or settings changes, previous output version, new output version, and compare or restore controls so users understand what changed." ], "uxGuidance": [ "Use regenerate / retry when users need another AI attempt for the same submitted request, or need recovery from a failed, stopped, low-quality, stale, blocked, or partially generated response.", "Protect previous work: preserve the prior answer, citations, edits, prompt, partial output, selected sources, and version history unless the user deliberately replaces them." ], "uiExamples": { "good": [ "A chat answer shows Regenerate answer, Retry failed sources, and Compare versions with the original prompt, source scope, model, and tool changes visible.", "A stopped stream shows Retry from start, Continue partial, and Keep partial output so users can choose whether the same prompt repeats or the partial answer is preserved." ], "bad": [ "A Try again button silently changes the prompt, model, sources, and tools, then overwrites the previous answer and citations.", "A failed assistant response can be retried repeatedly with no attempt count, cooldown, failure reason, source state, or previous output recovery." ] }, "uxExamples": { "good": [ "A user sees answer v1 has stale citations, chooses Regenerate with refreshed sources, compares v1 and v2, then restores v1 because v2 lost a required caveat.", "A rate-limited response shows next retry timing and keeps the prompt, draft answer, and selected files intact until Retry same prompt is available." ], "bad": [ "A user taps Regenerate and the product removes the original answer, so copied recommendations and review comments no longer have a version reference.", "A retry after tool failure creates duplicate side effects because the UI does not separate answer regeneration from tool execution retry." ] }, "problemContext": [ "A generated response may fail, stop, stall, be rate-limited, miss sources, produce weak output, use stale context, encounter a tool failure, or need a new variant.", "Retrying an AI answer may mean repeating the same response request, continuing a partial stream, rerunning retrieval, retrying a tool, changing model settings, or generating an alternate version.", "Regeneration may produce materially different conclusions, citations, tone, structure, tool use, or safety decisions even when the visible prompt is unchanged.", "Users may have copied, edited, commented on, cited, approved, or applied the prior answer before regeneration is requested.", "Some retry paths are subject to rate limits, backoff, idempotency, tool side effects, permission gates, or source freshness." ], "selectionRules": [ "Choose regenerate / retry when the task is rerunning an AI response attempt, creating a new answer version, continuing a failed generation, or recovering from failed AI source or tool work.", "Use retry when the task is repeating a non-AI failed operation such as export, upload, payment, save, or sync under the same request scope.", "Use chat interface when the design problem is the full multi-turn transcript, conversation list, history, and composer; regenerate / retry is one response-level action inside that surface.", "Use streaming response when the design problem is the live partial-output lifecycle; regenerate / retry handles the recovery or alternate-version action after stop, stall, failure, or completion.", "Use prompt box when users should edit the request before generation instead of rerunning the submitted prompt.", "Use editable AI output when users directly revise the generated draft; regenerate / retry should not overwrite those manual edits without compare or recovery.", "Use source grounding display or citation display when the key task is evidence inspection rather than requesting another generated version.", "Show same prompt, edited prompt, same context, changed context, same model, changed model, same sources, refreshed sources, same tools, retried tools, and no-tool rerun differences before the user commits.", "Do not hide the prior answer, citations, tool trace, partial output, edits, or version identity when a new answer is generated.", "Do not automatically retry AI work in a tight loop when rate limits, overload, safety review, permission denial, or side-effecting tools make repetition unsafe." ], "requiredStates": [ "Initial answer state with prompt snapshot, response version, source scope, model or mode, and available regenerate or retry controls.", "Failed response retry state with failure reason, attempt count, preserved prompt, and Retry same prompt action.", "Stopped or partial output state with Continue partial, Retry from start, Copy partial, and Discard controls.", "Regenerating state with in-flight status, duplicate activation guard, attempt number, and previous version still available.", "Regenerated version state that shows v1 and v2 identity, changed model, changed context, changed sources, changed tools, and compare versions controls.", "Retry failed sources, retry failed tool, and no-tool rerun states when the answer depends on retrieval or tool calls.", "Rate-limited, cooldown, quota exhausted, offline, permission denied, safety blocked, and non-retryable states.", "Stale context and refreshed source states that make source freshness explicit before regeneration.", "Manual edits present state that blocks overwrite and routes users to compare, keep edited, regenerate from edit, or restore original.", "Mobile compact regeneration state that preserves prior version, prompt snapshot, source status, and retry timing." ], "interactionContract": [ "Retry same prompt repeats the submitted prompt and visible context unless the UI explicitly shows which context changed.", "Regenerate creates a new answer version or clearly replaces the current version with an undo and restore path.", "Previous output, partial output, citations, tool events, copied state, and review comments remain inspectable after regeneration when they affected user decisions.", "Retry failed source work and retry failed tool work are distinct from regenerating answer text.", "If model, mode, source scope, tools, safety policy, or prompt text changes between attempts, the difference is visible before or immediately after the new attempt.", "Retry controls enter a pending state and suppress duplicate activation until the attempt completes, fails, cools down, or is cancelled.", "Rate limits, cooldowns, safety blocks, permission denials, and non-retryable failures replace the action with honest recovery or explanation.", "Regeneration never discards manual edits from editable AI output unless the user chooses a replacement path with version recovery." ], "implementationChecklist": [ "Model prompt snapshot, submitted prompt ID, response ID, response version, attempt number, partial output, previous output, selected context, source scope, tool scope, model settings, and retry status separately.", "Track regenerate reason such as weak answer, user requested variant, failed stream, failed source, failed tool, stale source, safety block, rate limit, or edited draft.", "Represent same-prompt retry, edited-prompt retry, continue partial, retry from start, regenerate alternate, retry sources, retry tools, compare versions, restore previous, and keep both as separate actions.", "Show source, tool, citation, and model differences between attempts in structured rows instead of burying them in final answer text.", "Protect side-effecting tool calls with idempotency, permission gates, or no-tool rerun options before allowing retries that can change external systems.", "Persist old answer versions long enough for copy, citation, audit, review, compare, and rollback tasks.", "Apply cooldown, retry limits, and rate-limit timing for repeated AI retries and automatic retries.", "Test same prompt retry, changed context, changed model, failed source retry, failed tool retry, stopped partial output, rate limit, safety block, manual edits, version compare, mobile wrapping, keyboard operation, and screen-reader status changes." ], "commonMisuses": [ "Using one Try again button for same-prompt retry, prompt edit, tool retry, source refresh, and alternate answer generation.", "Overwriting the previous answer and citations after regeneration.", "Hiding changed model, tools, source scope, or context between attempts.", "Retrying side-effecting tools while presenting the action as harmless answer regeneration.", "Letting users regenerate over manually edited output without conflict handling.", "Using infinite automatic retries during rate limits, overload, safety review, or permission denial.", "Treating a regenerated answer as more correct without showing source, confidence, or review changes." ], "critiqueQuestions": [ "Will this action retry the same prompt, continue partial output, regenerate a new version, retry sources, retry tools, or edit the prompt?", "Can users see the prompt snapshot, version identity, source scope, tool scope, model settings, attempt count, and changed context?", "What happens to the previous answer, citations, copied state, comments, approvals, and manual edits?", "Which failures are retryable, cooled down, blocked, exhausted, or non-retryable?", "Does any retry path repeat side-effecting tools, and what prevents duplicate external effects?", "Would general retry, chat interface, streaming response, prompt box, or editable AI output better match the actual task?" ], "relatedPatterns": [ "retry", "chat-interface", "streaming-response", "prompt-box", "editable-ai-output", "source-grounding-display", "citation-display", "tool-use-visibility" ], "comparisons": [ "regenerate-retry-vs-retry-vs-chat-interface-vs-streaming-response-vs-prompt-box-vs-editable-ai-output" ], "sourceIds": [ "openai-conversation-state", "openai-responses-streaming-events", "openai-prompt-engineering-guide", "microsoft-human-ai-guidelines", "aws-builders-library-retries-backoff-jitter", "stripe-idempotent-requests", "wcag-status-messages" ] }, { "id": "related-links", "completionStatus": "complete", "name": "Related links", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Curated onward links connected to the current content", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users who finish reading or acting on a page may need a small set of adjacent pages, services, or references, but generated or unsorted link lists often distract them with weak, stale, or ambiguous destinations.", "solution": "Provide a curated related-links collection that names the relationship between the current content and each destination, uses descriptive link text, discloses external or file destinations, and stays separate from primary actions and orientation navigation.", "uiGuidance": [ "Render a short, labelled collection of links whose destinations are closely related to the current content, using destination-specific link text and optional relation labels such as service, guidance, external, or PDF.", "Place related links near the end of the relevant content section or page, keep the list scannable, and visually separate it from primary calls to action, breadcrumbs, same-page contents, and global navigation." ], "uxGuidance": [ "Use related links to support users who have finished or understood the current content and need a relevant next page, adjacent service, reference, or follow-up resource.", "Curate links from user need and evidence, not tags alone; remove weak, stale, duplicate, or generic links so users do not interpret the list as a dumping ground." ], "uiExamples": { "good": [ "A benefits guidance page ends with Related links: Check eligibility for support, Upload evidence for your claim, and Appeal a support decision, each with a concise relation label.", "An external calculator link says Find an independent benefits calculator on MoneyHelper and includes an external label.", "A PDF guidance link includes the document type and size beside the link text." ], "bad": [ "A page ends with More information containing Home, Contact us, Apply now, Old 2018 guidance, Help, and an unrelated account settings link.", "A related-link list uses generic labels such as More, Details, Read this, and Click here.", "A same-page Fees anchor, a breadcrumb parent, and a sign-out action are mixed into one related content block." ] }, "uxExamples": { "good": [ "A user reads claim renewal guidance, chooses Upload evidence for your claim, and sees why that destination is the next useful service page.", "A user can distinguish optional supporting guidance from the primary Apply button and does not lose their task path.", "A content editor removes a weakly related link after reviewing click-through and support-query data." ], "bad": [ "Users follow a generic More information link and land on an unrelated policy collection.", "A user expects a related link to open another page, but it jumps to a same-page anchor with no context.", "A generated related-content list includes expired guidance and duplicate links with different labels." ] }, "problemContext": [ "The current page is useful on its own but naturally leads to a few adjacent service, guidance, or reference destinations.", "Users may not know the exact term to search for next, but related destinations are predictable from the current page's task or topic.", "The page also has primary actions, breadcrumbs, in-page anchors, or local navigation that must not be confused with optional onward links." ], "selectionRules": [ "Choose related links when each destination has a clear, evidenced relationship to the current page and is useful after or alongside the current content.", "Keep the set short and curated; when the list grows long, group by relationship or move the navigation responsibility to a hub, contents list, search, or taxonomy page.", "Use descriptive link text that makes sense out of context and usually matches the destination page title or task action.", "Disclose external sites, file downloads, formats, sizes, and different-language destinations when those details affect user expectation.", "Place links at the end of the relevant content block unless a link is needed in context at the exact point of use.", "Do not include primary CTAs, account utilities, global destinations, same-page anchors, or breadcrumb ancestors as related links.", "Review generated or tagged links manually for relevance, freshness, duplicates, and unsafe external destinations.", "Use a contents list or pagination for a small ordered guide; use breadcrumbs for parent hierarchy; use in-page anchors for same-page sections." ], "requiredStates": [ "Default state with a labelled, curated related-links block and descriptive link text.", "Selected or reviewed state showing which related destination was chosen or previewed.", "External-link state with destination context and external disclosure.", "File-link state with file type and size or page-hosted document guidance.", "Empty or insufficient-relevance state where the block is omitted instead of filled with weak links.", "Stale or generated-link review state where content owners remove expired, duplicate, or weak links." ], "interactionContract": [ "Activating a related link navigates to a different page, service, or resource unless the link text explicitly says it is a jump link.", "The current page's primary action, hierarchy, and same-page contents remain visually and semantically separate from related links.", "Link labels and relation labels accurately predict the destination and why it is useful from this page.", "External and file destinations provide enough context before navigation or download.", "Visited, reviewed, or selected styling may help users track which related destination they inspected, but it must not imply current-page state.", "The related-links block is removed when no links are sufficiently relevant." ], "implementationChecklist": [ "Write down the user need for each proposed related link and remove links without a clear relationship.", "Use a labelled region or navigation landmark such as Related links or Related content when the block acts as navigation.", "Keep the first few words of each link meaningful and destination-specific.", "Add relation labels or short supporting text only when they clarify why the link belongs.", "Mark external sites, files, languages, or downloads consistently and check that external destinations are safe and accessible.", "Avoid duplicate destinations with different labels and duplicate labels pointing to different destinations.", "Schedule link review or use content ownership so stale and generated links do not stay complete by accident." ], "commonMisuses": [ "Using related links as a catch-all further-reading dump.", "Adding every tagged page without human curation.", "Putting primary task actions or account utilities into related links.", "Using vague link text such as More, Read this, Click here, or Details.", "Mixing same-page anchors, parent hierarchy links, external links, and file downloads without context.", "Leaving stale or broken links because the list is generated automatically.", "Adding so many related links that users stop scanning them." ], "critiqueQuestions": [ "What user need does each related link satisfy from this exact page?", "Would users expect this link to be a next page, a same-page jump, a parent page, a primary action, or an external resource?", "Can the link text make sense in a screen-reader link list?", "Which links are optional support versus the main task users came to complete?", "Who owns checking that external, file, and generated links stay relevant and safe?" ], "relatedPatterns": [ "in-page-anchor-navigation", "breadcrumbs", "back-link", "basic-search", "process-list" ], "comparisons": [ "related-links-vs-in-page-anchor-navigation-vs-breadcrumbs" ], "sourceIds": [ "va-link-collection", "govuk-effective-links-guidance", "nhs-contents-list-component", "uswds-link-component" ] }, { "id": "report-abuse", "completionStatus": "complete", "name": "Report abuse", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Reporter-facing safety submission flow for harmful, abusive, illegal, spam, impersonation, or policy-violating content and behavior", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Reporting harmful behavior fails when the entry point is hidden, the reported object is ambiguous, reason choices are vague, evidence is lost, status overpromises enforcement, reporter privacy is unclear, or immediate protection actions are missing.", "solution": "Provide a scoped reporting flow that captures the reported object, reason, affected person, supporting context, privacy expectations, route, confirmation, status, and post-report safety actions while separating reporter submission from moderator queue work and everyday block or mute controls.", "uiGuidance": [ "Render report abuse as a scoped safety flow that identifies the reported object, selected reason, affected person, evidence or context, privacy handling, submit action, confirmation ID, review expectation, and immediate safety actions.", "Place the report entry point close to the post, comment, profile, message, repository, ad, listing, live chat item, or conversation being reported without making the reporter keep harmful content in view after submission." ], "uxGuidance": [ "Use report abuse when a user needs to flag harmful content or behavior for review, not when they only want to hide someone, request access, resolve a comment, or read a security warning.", "Help the reporter choose the right route, preserve evidence, understand that review may not equal removal, and take immediate personal-safety actions such as block, mute, hide, leave, save a copy, or contact emergency help where relevant." ], "uiExamples": { "good": [ "A comment menu opens Report abuse with the comment snapshot, author, timestamp, reason choices, affected-person choice, optional context, submit, and confirmation with Block user and View report history actions.", "A direct-message report lets the user choose specific messages, state whether the issue affects them or someone else, opt out of receiving reported text in follow-up notifications, and remove the conversation from the inbox after submission." ], "bad": [ "A red Report button immediately submits with no reason, no content snapshot, no confirmation, and no path to protect the reporter.", "A harassment report requires users to copy the abusive content into a public comment thread before moderators can see it." ] }, "uxExamples": { "good": [ "A user reports a threatening message, selects violent threat, includes two related messages for context, receives a report receipt, gets guidance to contact local emergency services if in immediate danger, and can save a copy for authorities.", "A contributor reports a disruptive pull request comment to repository admins, chooses a code-of-conduct reason, sees that maintainers will review it, and can still report to platform support if needed." ], "bad": [ "A user reports spam and sees the reported account instantly marked banned even though the item has only entered review.", "A user who only wants to stop seeing someone is forced through an abuse report instead of a clear block or mute action." ] }, "problemContext": [ "Reportable targets can include posts, comments, profiles, accounts, direct messages, group conversations, live chat, ads, listings, repositories, issues, pull requests, discussions, apps, contact links, or search predictions.", "Report reasons may include harassment, bullying, violent threat, hate, self-harm, sexual content, child safety, spam, scam, impersonation, privacy violation, copyright, trademark, illegal content, deceptive behavior, or platform-specific policy violations.", "The reporter may be the target, reporting on behalf of someone else, reporting a public safety issue, reporting while signed out, reporting from a blocked relationship, or reporting content they should not need to view again.", "Submitted reports often feed a review queue or specialist route, while reporters need confirmation, expectation-setting, personal-safety actions, follow-up preferences, and privacy protection." ], "selectionRules": [ "Choose report abuse when a user flags content, behavior, an account, or an object as potentially harmful, abusive, spam, illegal, impersonating, privacy-violating, or against community rules.", "Use a local Report action when object identity matters; preserve target type, permalink or snapshot, author when safe, timestamp, and selected content range or messages.", "Ask for a reason using policy language that users can understand, then collect only the context needed to route the report and protect the reporter.", "Use review queue for the internal moderator worklist after reports are submitted, not for the reporter-facing flow.", "Use comments when users are discussing, resolving, editing, or deleting conversation content; report abuse is a separate safety route from ordinary discussion.", "Use security warning when a system threat verdict blocks unsafe navigation, download, submission, or preview before exposure.", "Use permission denied state when the issue is authorization or access, not harmful behavior.", "Use notification center for report updates and follow-up requests, but deep-link to the report receipt, reported object state, or safety center.", "Offer block, mute, hide, restrict, leave, save evidence, emergency, and legal or privacy-reporting routes as adjacent actions without pretending they are the same as an abuse report.", "Make clear when reporting is anonymous to other users, when reported text may appear in follow-up messages, and when report details may be shared with moderators or legal teams." ], "requiredStates": [ "Report entry point near a post, comment, profile, message, conversation, repository, ad, live chat item, or listing.", "Reported object snapshot with target type, author or account when safe, timestamp, selected messages, permalink, and content summary.", "Reason selection for harassment, spam, impersonation, privacy, legal, child safety, violent threat, self-harm, or other policy categories.", "Affected-person state such as myself, someone else, a group, everyone, community, or organization.", "Additional context or evidence state with limits, sensitive-data guidance, and no public disclosure.", "Multiple-content selection state for adding related posts, comments, or messages to one report.", "Route selection state for platform support, repository maintainers, privacy complaint, legal issue, law enforcement guidance, or emergency help.", "Submit pending, submitted, failed, duplicate, rate-limited, and offline draft states.", "Confirmation state with receipt, expectation-setting, report history or status, and post-report safety actions.", "Post-report content hidden or notice state that lets users avoid re-exposure while preserving access when they choose to view it.", "Follow-up state for more information needed, action taken, no violation found, unresolved, resolved, or report reopened.", "Reporter privacy, signed-out or region-specific reporting, blocked-account reporting, and mobile compact states." ], "interactionContract": [ "The Report action is reachable from the object being reported and carries object identity into the flow without asking users to manually re-enter obvious context.", "The flow states who or what is being reported before submission and lets users change the target if the wrong item was selected.", "Reason choices route to the correct specialist path and do not collapse urgent safety, privacy, legal, child safety, spam, and harassment into one vague issue.", "Optional context fields explain what helps review and warn users not to include unnecessary secrets, medical data, payment data, or private third-party information.", "Submission failure preserves the draft report, selected reason, and evidence so the reporter can retry without revisiting harmful content.", "Confirmation says the report was received, not that enforcement has already happened, unless an actual moderation action has completed.", "Post-submit safety actions are scoped: block or mute changes what the reporter sees; review queue actions decide platform enforcement; legal or emergency routes are separate.", "Reporter identity and report contents are not exposed to the reported user, public thread, analytics events, screenshots, or unrelated moderators beyond policy need." ], "implementationChecklist": [ "Inventory reportable object types, source surfaces, policy reasons, specialist routes, required evidence, privacy obligations, and status values before adding the entry point.", "Model report target, reporter, affected person, selected reason, selected evidence, context text, route, receipt ID, status, follow-up preference, and post-report safety actions separately from moderator queue state.", "Preserve report drafts through network failure, mobile navigation, offline retry, blocked-account relationships, deleted content, and removed conversations.", "Provide safe post-submit actions such as block, mute, hide, restrict, leave conversation, save a report copy, open safety center, view report history, or contact emergency help.", "Throttle spammy submissions without blocking urgent safety reports behind inaccessible challenges or silent rate limits.", "Audit who can view report details, redact sensitive evidence in logs, and avoid exposing reporter identity or context to the reported user.", "Test post, comment, profile, direct message, group conversation, ad, repository, signed-out, region-specific, duplicate, failed, urgent threat, privacy/legal route, mobile wrapping, keyboard order, and screen reader announcement states." ], "commonMisuses": [ "Treating Report as an instant takedown or ban action.", "Using one unlabelled report button with no reason, target, evidence, confirmation, or status.", "Forcing reporters to keep viewing harmful content to complete, retry, or check a report.", "Mixing block or mute, permission recovery, comments moderation, legal takedown, privacy request, and abuse reporting into one ambiguous flow.", "Revealing reporter identity, report text, private evidence, or moderator notes to the reported user.", "Hiding urgent threat or child safety routes behind ordinary spam categories.", "Dropping failed reports without preserving the selected reason and evidence." ], "critiqueQuestions": [ "What exact object, account, conversation, or content range is being reported?", "Which policy route owns this reason, and does the reporter understand the difference between reporting, blocking, muting, legal requests, and emergency help?", "Can the reporter complete the flow without re-exposure to harmful content?", "What evidence is captured automatically, and what optional context is truly needed?", "How are reporter privacy, follow-up content, report history, and status expectations explained?", "What immediate safety action remains available after submission?", "What happens when the content is deleted, already reported, blocked, unavailable, or the report fails offline?" ], "relatedPatterns": [ "review-queue", "comments", "threaded-discussion", "notification-center", "security-warning", "permission-denied-state", "sensitive-data-reveal", "activity-log", "alert", "warning-text" ], "comparisons": [ "report-abuse-vs-review-queue-vs-comments-vs-security-warning-vs-permission-denied-state-vs-notification-center" ], "sourceIds": [ "youtube-report-inappropriate-content", "github-reporting-abuse-spam", "github-managing-reported-content", "x-report-abusive-behavior" ] }, { "id": "required-field-hidden-by-conditional-logic", "completionStatus": "complete", "name": "Required field hidden by conditional logic", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Anti-pattern where required form data is hidden or unreachable because conditional state and validation disagree", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Conditional form logic often hides fields to reduce noise, but if hidden fields remain required, stale, submitted, or server-enforced without a visible recovery path, users cannot tell what blocks completion.", "solution": "Keep conditional requirement state synchronized with the visible branch: reveal required follow-ups beside their triggers, clear or exclude hidden answers when triggers change, restore hidden branches before linking errors, and use review or separate pages when branching is too large for same-page reveal.", "uiGuidance": [ "Do not let a required answer be hidden, visually collapsed, disabled, off-screen, or absent from the current branch while validation still blocks submission.", "When a trigger makes a follow-up required, keep the trigger, the revealed required field, the requirement text, and the error summary recovery path visible and connected." ], "uxGuidance": [ "Users should be able to tell which answers are currently required before submit, why they are required, and how to reveal or remove the requirement.", "Treat conditional requirement state as data, not decoration: every hide, reveal, trigger change, saved draft, browser Back, server validation, and review step must recompute whether the hidden field is required or excluded." ], "uiExamples": { "good": [ "A benefits form asks whether the user needs an accommodation; selecting Yes reveals a required Accommodation details field directly below the trigger with helper text and validation.", "After failed submit, the error summary says Accommodation details is required because Yes is selected and links to the visible revealed field." ], "bad": [ "Submit fails with Enter accommodation details, but the accommodation field is hidden because the branch is collapsed and the trigger is off-screen.", "A server requires Partner date of birth from an old draft answer, but the current page shows Single and no partner fields." ] }, "uxExamples": { "good": [ "A user changes Yes to No and the required follow-up is cleared, excluded from validation, and removed from the review page.", "A user returns from review after changing an upstream answer and is asked the newly required question before final submit." ], "bad": [ "A user repeatedly presses Submit because the only missing required field lives in a hidden branch with no link or visible trigger state.", "A screen reader user changes a radio answer and is not told that a new required question appeared below it." ] }, "problemContext": [ "A form has radio, checkbox, select, eligibility, account type, permission, or saved-draft answers that control which later answers are required.", "The required field may be visually hidden, collapsed, disabled, moved to another page, filtered out, or missing from the current route.", "Validation may run on the client, server, saved draft, review step, imported payload, or resumed session.", "Users need recovery after submit, browser Back, review edits, mobile accordions, assistive technology changes, and stale conditional answers." ], "selectionRules": [ "Flag this anti-pattern when a required field can block submit while it is hidden, collapsed, disabled, off-screen, absent from the current route, or disconnected from its trigger.", "Use conditional reveal fields when one selected answer owns a short visible follow-up field directly under the trigger and required only while selected.", "Use dependent fields when an always-owned downstream control changes options, requirement, or validity based on an upstream answer.", "Use error summary when submit-time validation needs a top-of-page list of visible, linked errors with matching field messages.", "Use single-page form when a short set of related fields can remain visible together with clear required indicators and one submit action.", "Use review before submit when changed answers can create newly required branches that must be resolved before final commitment.", "Use a separate question page, multi-step form, or wizard when the conditional branch has multiple required fields, long reading, or enough complexity that same-page hiding becomes hard to recover from.", "Do not mark hidden fields required unless the trigger that makes them required is visible, selected, and recoverable from validation errors.", "When hiding a branch, clear or exclude its values and errors unless draft restoration is explicitly tied to reselecting the same trigger.", "When server validation finds a conditional required error, restore or route to the owning trigger and field before asking users to fix it." ], "requiredStates": [ "Initial state with all currently required fields identified before users submit.", "Trigger selected state where the newly required follow-up is revealed adjacent to the trigger.", "Trigger cleared state where hidden follow-up values and errors are cleared or excluded.", "Failed submit state where the error summary links to a visible field, not a hidden target.", "Server validation state where backend-required conditional fields are restored or routed to before recovery.", "Saved draft return state where trigger and required branch are synchronized.", "Browser Back or review edit state where changed upstream answers recompute required downstream questions.", "Nested branch state where the UI escalates to a page or step instead of hiding several required fields.", "Assistive notification state where newly revealed required fields are discoverable to keyboard and screen reader users.", "Mobile collapsed state where a required field is not trapped inside a closed panel with no error route.", "Bad hidden blocker state where submit fails but the required field remains invisible.", "Bad stale trigger state where old saved values keep a hidden branch required.", "Bad disabled-required state where a disabled or unavailable control is still required.", "Bad error-summary dead link state where the error target is hidden or missing.", "Bad server-only required state where the UI never exposed the field that the backend requires." ], "interactionContract": [ "Selecting a trigger that creates a required follow-up reveals that follow-up immediately in logical DOM and visual order.", "Changing or clearing the trigger removes hidden required state, hidden errors, and hidden payload values unless reselecting the trigger intentionally restores a draft.", "Submit-time errors only point to fields that are visible or are made visible before focus moves.", "Error summary links restore collapsed branches, select or preserve the owning trigger, and move focus to the field or group that can be fixed.", "Server-side validation returns enough branch context for the client to reveal or route to the owning conditional field.", "Review changes that create new required branches send users through those questions before final submit.", "Assistive technology users are informed when a selected answer reveals a new required field." ], "implementationChecklist": [ "Create a requirement map that ties every conditional required field to its owning trigger, active condition, visibility state, payload key, and error target.", "Keep client validation, server validation, saved draft restoration, and review pages using the same condition rules.", "Reveal short required follow-ups beside the trigger; route larger branches to pages or steps with their own required indicators.", "Before submit, validate only fields whose triggers make them active and visible or routeable.", "When hiding a branch, clear or mark inactive its values, errors, dirty state, and review rows.", "When an error is produced for a hidden field, first restore the branch or route to the owning question, then focus the summary or field.", "Test with browser Back, saved drafts, server errors, review edits, mobile collapsed sections, screen readers, keyboard-only navigation, and stale branch values.", "Log or assert when validation references a hidden or missing DOM target so hidden blockers are caught before release." ], "commonMisuses": [ "Keeping a visually hidden input required because the backend schema says the field is required in some cases.", "Showing an error summary that links to an element hidden by CSS, collapsed accordion state, or conditional route logic.", "Using disabled required controls to represent unavailable answers.", "Clearing the trigger visually but leaving the old branch active in saved draft or server payload.", "Only marking required fields after failed submit, forcing users to discover branch rules by trial and error.", "Putting a required conditional field at the bottom of the form far away from its trigger.", "Nesting several required conditional fields inside one local reveal instead of splitting the flow.", "Relying on visual reveal animation without making new required fields discoverable to assistive technology." ], "critiqueQuestions": [ "Which trigger makes this field required, and is that trigger visible when the error appears?", "Can a hidden, disabled, collapsed, or off-route field ever block submit?", "What happens to values and errors when the trigger changes?", "Does the error summary link to a visible recoverable field?", "Does server validation return enough branch context to reveal or route to the missing answer?", "Can review edits or browser Back create newly required questions before final submit?", "Would this branch be clearer as a separate page, step, or review-gated question?" ], "relatedPatterns": [ "conditional-reveal-fields", "dependent-fields", "error-summary", "inline-validation", "single-page-form", "review-before-submit", "multi-step-form", "wizard" ], "comparisons": [ "required-field-hidden-by-conditional-logic-vs-conditional-reveal-fields-vs-dependent-fields-vs-error-summary-vs-single-page-form-vs-review-before-submit" ], "sourceIds": [ "govuk-conditional-reveal-accessibility", "agriculture-design-system-conditional-reveal", "nng-required-fields-forms", "govuk-error-summary-component", "uswds-form-component" ] }, { "id": "responsive-navigation-adaptation", "completionStatus": "complete", "name": "Responsive navigation adaptation", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Navigation model that changes presentation across viewport, posture, and destination-count constraints", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Navigation often changes shape across phone, tablet, desktop, split screen, rotation, keyboard, or foldable states, and users lose orientation when destinations disappear, labels change, current state resets, or competing navigation surfaces appear at breakpoints.", "solution": "Define responsive navigation adaptation rules that keep the same destination model and current state while moving destinations among bottom navigation, rail, drawer, side navigation, header overflow, or labelled More surfaces according to width, destination count, hierarchy, and interaction constraints.", "uiGuidance": [ "Render the same destination model in breakpoint-appropriate surfaces such as compact bottom navigation, medium navigation rail, modal or standard drawer, expanded side navigation, or header overflow without changing destination labels, selected state, or hierarchy.", "Make adaptation rules visible in the interface: preserve current destination, expose overflow with a labelled control, keep safe-area and keyboard insets clear, and avoid duplicating the same primary destinations in competing navigation surfaces." ], "uxGuidance": [ "Use responsive navigation adaptation when users continue the same task across phone, tablet, desktop, split screen, rotation, or resized windows and need orientation to survive layout changes.", "Treat resize, orientation change, fold, keyboard appearance, and destination-count overflow as state transitions that must preserve route, focus, filters, drafts, badges, and open navigation recovery." ], "uiExamples": { "good": [ "A five-destination app shows a labelled bottom bar on phone, a rail with labels on tablet, and persistent side navigation on desktop while Reports remains selected in every layout.", "A seventh destination moves into a labelled More drawer on compact width and returns to the side list on expanded width with the same name and badge.", "When the software keyboard opens, the bottom navigation respects the safe area and does not cover the focused search field." ], "bad": [ "The phone layout calls a destination Work, the tablet rail calls it Projects, and the desktop sidebar calls it Spaces.", "A breakpoint hides Settings entirely instead of placing it in overflow or a drawer.", "The desktop layout shows both a side nav and a drawer opener containing the same primary destinations." ] }, "uxExamples": { "good": [ "A user filters Reports on mobile, rotates to landscape, and the selected Reports route and filters remain intact in the rail layout.", "A keyboard user opens the compact drawer, resizes to desktop, and focus moves to the equivalent side-navigation item instead of staying in a hidden panel.", "A split-screen tablet user sees navigation collapse to a rail without losing badges, selected state, or access to secondary destinations." ], "bad": [ "Resizing from phone to desktop resets the current destination to Home and clears a draft.", "Opening the mobile menu, then rotating the device, leaves focus trapped in an offscreen drawer.", "The compact layout replaces labels with icons only, so users cannot predict which destination moved where." ] }, "problemContext": [ "A product supports compact phones, tablets, desktop browsers, resizable windows, split-screen modes, foldable postures, or embedded webviews.", "The same destination set may need bottom navigation, rail, drawer, side navigation, or top overflow depending on space and destination count.", "Users may be mid-task with filters, drafts, scroll position, selected objects, badges, an open drawer, or keyboard focus when the layout changes.", "Responsive navigation adaptation sits near global navigation, bottom navigation, navigation drawer, side navigation, header, tabs, breadcrumbs, utility navigation, and safe-area handling." ], "selectionRules": [ "Choose responsive navigation adaptation when the navigation surface itself must change across viewport, posture, orientation, or destination-count constraints.", "Keep destination identities, labels, icon meanings, badges, order, and selected state consistent across adapted surfaces.", "Use bottom navigation for three to five compact primary destinations, rail or side navigation for medium and expanded persistent access, and drawer or labelled overflow for secondary or too-many destinations.", "Define what happens when a drawer is open, focus is inside navigation, the keyboard appears, or a user resizes while an unsaved task is in progress.", "Use global navigation, side navigation, bottom navigation, navigation drawer, or header patterns directly when the layout does not need to adapt across surfaces.", "Do not hide destinations, rename labels, reset state, create duplicate primary nav surfaces, or move current-view actions into destination navigation at breakpoints." ], "requiredStates": [ "Compact width with bottom navigation or labelled compact menu.", "Medium width with navigation rail, condensed side surface, or drawer-triggered navigation.", "Expanded width with persistent side navigation or global navigation plus local navigation.", "Destination count overflow state where secondary destinations move into a labelled More or drawer surface.", "Current destination preserved across resize, rotation, split-screen, and back/forward navigation.", "Open drawer or menu state that adapts safely when the viewport changes.", "Keyboard, safe-area, system gesture, and bottom inset state on compact mobile.", "Badge, unread, filter, scroll, draft, and nested route preservation state.", "Focus recovery state when an active control moves, hides, or changes container.", "Failure state for unsupported layout, missing destination, or layout measurement delay." ], "interactionContract": [ "The adapted surface changes presentation, not the user's destination model.", "A selected destination remains selected and reachable after every breakpoint transition.", "Labels, accessible names, badges, and order stay stable unless a documented overflow rule moves lower-priority destinations.", "Opening, closing, resizing, rotating, and keyboard appearance do not trap focus in hidden navigation.", "If a destination moves into overflow, the overflow control is labelled, reachable, and announces where the destination went.", "Navigation adaptation preserves local route state, filters, drafts, scroll position, and unsaved work unless a real route change requires warning or save." ], "implementationChecklist": [ "Inventory destinations, hierarchy, priority, badge needs, frequency, and action-versus-destination ownership before choosing responsive surfaces.", "Map compact, medium, expanded, landscape, split-screen, keyboard-open, and dense-destination states to concrete surfaces.", "Use container or viewport breakpoints tied to available navigation space, not arbitrary device names.", "Keep labels and accessible names consistent across bottom bar, rail, drawer, side nav, and overflow variants.", "Preserve selected destination, nested route, filters, drafts, scroll, and badge state through layout transitions.", "Move focus to the equivalent adapted control or main heading when a focused navigation control disappears.", "Test safe areas, system gestures, software keyboard, high zoom, long localized labels, and screen-reader navigation at every breakpoint.", "Avoid rendering duplicate primary destination sets unless one is clearly an overflow or temporary disclosure surface." ], "commonMisuses": [ "Treating responsive navigation as separate mobile and desktop information architectures.", "Changing destination labels or order across breakpoints.", "Removing low-priority destinations instead of putting them in overflow or a drawer.", "Resetting the selected destination or local state on resize.", "Duplicating primary destinations in bottom navigation, a drawer, and a side nav at the same width.", "Using icon-only compact navigation for unfamiliar destinations.", "Letting safe areas, bottom sheets, or keyboards cover navigation.", "Leaving focus in a hidden drawer after adaptation." ], "critiqueQuestions": [ "What is the single destination model that all responsive surfaces represent?", "Which destinations stay visible at compact width, and where do secondary destinations go?", "How do current state, labels, badges, route, filters, draft state, and focus survive a breakpoint transition?", "Does any breakpoint duplicate or remove destinations rather than adapting them?", "What happens when the drawer is open or focus is inside navigation during rotation or resize?", "Is this really responsive navigation adaptation, or is the problem owned by global navigation, bottom navigation, navigation drawer, side navigation, or header?" ], "relatedPatterns": [ "global-navigation", "bottom-navigation", "navigation-drawer", "side-navigation", "header", "utility-navigation" ], "comparisons": [ "responsive-navigation-adaptation-vs-global-navigation-vs-bottom-navigation-vs-navigation-drawer-vs-side-navigation-vs-header" ], "sourceIds": [ "android-responsive-navigation", "android-navigation-ui", "material-responsive-layout-grid", "material-bottom-navigation", "material-navigation-drawer", "uswds-side-navigation" ] }, { "id": "restore-from-trash", "completionStatus": "complete", "name": "Restore from trash", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Durable deleted-object recovery", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to recover deleted objects after the immediate undo window has passed, but restoration becomes risky when the product hides original location, retention, ownership, permissions, or permanent-deletion status.", "solution": "Provide a durable deleted-items surface that lists recoverable objects with context, supports targeted restore to an original or chosen location, separates permanent deletion, and reports restored, expired, purged, conflict, and permission states.", "uiGuidance": [ "Show deleted objects in a dedicated trash, recycle bin, deleted-files, or recoverable-items surface with object name, type, original location, deletion date, deleted-by actor, and remaining recovery window.", "Place Restore as the primary recovery action and keep permanent delete, empty trash, and purge controls visually separated with stronger review." ], "uxGuidance": [ "Use restore from trash when users may discover a mistaken deletion after leaving the original workflow and need a durable way to recover the object.", "Make restoration trustworthy by explaining where the object will return, what dependencies or permissions will be restored, and what happens when the original location is gone." ], "uiExamples": { "good": [ "A Deleted files table lists Quarterly budget.xlsx with original folder Finance/Q2, deleted yesterday by Maya, 29 days left, and a Restore to Finance/Q2 action.", "A restore panel warns that the original folder was deleted and offers Choose new location before restoring." ], "bad": [ "A trash page lists File 1, File 2, and File 3 with no path, deletion time, owner, or recovery deadline.", "Restore and Delete forever appear as identical adjacent buttons with no final-loss review." ] }, "uxExamples": { "good": [ "A user opens Trash, filters to spreadsheets deleted this week, previews the original folder, restores one file, and gets a link to the restored location.", "A user selects several deleted records, sees that two can restore to their original location and one needs a new parent, then completes only the safe restores." ], "bad": [ "A user restores a shared folder but cannot find it because permissions or parent location changed silently.", "A user expects a file to remain recoverable, but the product hid the retention deadline and the file was purged." ] }, "problemContext": [ "Objects are removed from primary views but intentionally retained for a recovery period.", "Users may realize the deletion was wrong after navigating away, changing devices, or returning days later.", "Deleted objects may have parent folders, collaborators, permissions, versions, dependencies, or references that affect restore.", "Retention periods, admin purges, legal holds, storage quotas, or plan limits determine whether recovery is still possible." ], "selectionRules": [ "Choose restore from trash when the product supports soft deletion and a recoverable deleted-items location.", "Use undo when recovery must happen immediately after a recent low-risk action and no durable deleted-items surface is needed.", "Use destructive action confirmation before permanent delete, empty trash, purge, or any deletion that bypasses recovery.", "Use draft state when users are recovering unpublished changes rather than deleted objects.", "Show original location, deletion time, deleted-by actor, object type, owner, and retention status before restore.", "Offer restore to original location only when that location still exists and the user has permission to restore there.", "Offer choose-location recovery when the parent object is gone, access changed, or a name conflict exists.", "For bulk restore, summarize item count, unavailable locations, conflicts, permission changes, and skipped items before applying the action.", "Avoid using trash as the only safety mechanism for high-risk permanent loss; users still need prevention, warnings, or confirmation when deletion has severe consequences.", "Make expired, purged, admin-only, and legal-hold states explicit instead of showing missing or disabled rows without explanation." ], "requiredStates": [ "Normal active-object state before deletion.", "Deleted-but-recoverable state in Trash or Recycle Bin.", "Trash list state with object metadata and restore actions.", "Restore preview state showing original location and affected permissions or dependencies.", "Restored state with a link to the restored object or location.", "Original-location unavailable state requiring a new destination or administrator help.", "Name conflict state when the original location already contains a replacement object.", "Retention-expiring state with a visible recovery deadline.", "Expired or purged state where recovery is no longer possible.", "Permanent delete or empty-trash confirmation state." ], "interactionContract": [ "Deleting an object removes it from normal views and records enough metadata for later recovery.", "Trash exposes recoverable deleted objects with identity, location, deletion, actor, and retention context.", "Restore returns the object to the original location when valid, or asks the user to choose a location when the original target is unavailable.", "The interface reports restored, skipped, conflicted, expired, purged, and permission-denied outcomes separately.", "Permanent delete and empty-trash actions require deliberate review and cannot be confused with Restore.", "Bulk selection preserves per-item status so users know which deleted objects can be restored safely.", "Restored objects become discoverable through a stable link, parent location, search result, or recent activity state." ], "implementationChecklist": [ "Store deleted object ID, display name, object type, original parent, deleted-at timestamp, deleted-by actor, owner, permissions, version metadata, retention deadline, and purge status.", "Create a deleted-items view with filtering by type, owner, folder, deletion date, and restore availability.", "Validate the original location, permissions, name conflicts, quotas, locks, legal holds, and dependency references before restore.", "Provide restore-to-original and choose-new-location flows when the original parent cannot accept the object.", "Separate Restore, Delete forever, Empty trash, and Admin restore with distinct labels, placement, and confirmation requirements.", "Announce restore outcomes and failed-item details in a status region and preserve selection state for unresolved items.", "Test single restore, bulk restore, expired retention, parent deletion, name conflict, shared permissions, admin-only recovery, mobile access, keyboard access, and screen reader output." ], "commonMisuses": [ "Showing deleted objects without enough metadata to identify the right item.", "Restoring to a hidden or invalid location without telling the user.", "Placing permanent delete beside Restore without visual separation or final-loss confirmation.", "Treating trash as a substitute for confirmation when deletion is severe or externally visible.", "Hiding retention deadlines, plan limits, or administrator-only recovery boundaries.", "Making bulk restore all-or-nothing when some items have conflicts or missing parents." ], "critiqueQuestions": [ "Can users tell which deleted object is which before restoring?", "Where exactly will this object return, and can the user access that location?", "What happens if the parent folder, workspace, owner, or permission scope changed?", "How long is the object recoverable, and how is that deadline shown?", "Which actions permanently remove recovery, and are they separated from Restore?", "Does bulk restore report partial success, skipped items, conflicts, and next steps?" ], "relatedPatterns": [ "undo", "destructive-action-confirmation", "confirmation-dialog", "draft-state" ], "comparisons": [ "restore-from-trash-vs-undo-vs-destructive-action-confirmation-vs-draft-state" ], "sourceIds": [ "google-drive-recover-deleted-file", "dropbox-recover-deleted-files", "microsoft-sharepoint-recycle-bin" ] }, { "id": "retry", "completionStatus": "complete", "name": "Retry", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Scoped failed-operation retry control", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users face a failed load, save, export, upload, payment, sync, or submit operation and need a safe way to attempt the same operation again without losing context or causing duplicate side effects.", "solution": "Expose a scoped Retry control only for retryable failures, preserve the original request context, show attempt and pending states, prevent duplicate activation, use idempotency for side-effecting operations, back off repeated attempts, and stop retrying when correction, fallback, or escalation is more honest.", "uiGuidance": [ "Place Retry next to the failed operation, object, or request summary, and name the exact action being retried such as Retry export or Retry payment authorization.", "Show attempt count, in-flight state, last tried time, cooldown or next retry time, request reference, and the preserved inputs or scope when retry safety depends on context." ], "uxGuidance": [ "Use retry when a specific operation likely failed for a transient reason and the same operation can be attempted again without losing user context or duplicating side effects.", "Cap retry attempts, back off repeated attempts, guard duplicate submission while pending, and route users to correction, fallback, support, or later return when retry no longer fits the failure." ], "uiExamples": { "good": [ "A report export card says Export CSV failed, keeps the saved filters visible, shows Attempt 1 of 3, and offers Retry export with request EXP-2048.", "A payment authorization retry shows the same order, same amount, idempotency reference, disabled duplicate button while sending, and a cooldown before another attempt." ], "bad": [ "A generic Try again button appears after every error, including validation and permission failures users cannot fix by repeating the request.", "Retry and Submit again are both enabled during an in-flight payment request with no idempotency reference or duplicate guard." ] }, "uxExamples": { "good": [ "A user retries the same export after a network timeout, sees the attempt change to sending, and then returns to the recovered download state without re-entering filters.", "A second failure increases the wait before the next attempt and then offers cached export, background notification, or support reference after attempts are exhausted." ], "bad": [ "The app retries aggressively every second during an outage and makes the service harder to recover.", "A user retries a non-retryable permission denial and receives the same failure repeatedly instead of an access request path." ] }, "problemContext": [ "The product can distinguish transient failures from validation, permission, policy, irreversible, or final-state failures.", "The same request, object, inputs, filters, or upload can be preserved and attempted again.", "Repeated attempts can create duplicate records, charges, emails, exports, queue items, or service load unless guarded.", "Users need to know whether a retry is pending, waiting, succeeded, failed again, exhausted, or unavailable." ], "selectionRules": [ "Choose retry when a specific failed operation can plausibly succeed if attempted again under the same scope.", "Name the retried operation and object so users understand what will repeat before they activate it.", "Keep user-entered data, request parameters, selected files, filters, and destination details intact across failed attempts.", "Disable or debounce Retry while an attempt is in flight, and never leave an unsafe duplicate submit path beside it.", "Use idempotency keys, request references, upload IDs, message IDs, or server deduplication for side-effecting operations.", "Use capped backoff, jitter, attempt limits, or server-provided retry timing rather than immediate repeated loops.", "Stop offering retry for validation errors, missing required data, denied permission, final deletion, unsupported state, or policy decisions.", "After repeated failure, switch to fallback, cached data, background completion, export local copy, contact support, or return-later guidance.", "Use error state for the broader persistent failure surface and Retry as one action inside that surface.", "Use offline state when the primary issue is connection mode and local or queued work behavior rather than one failed operation." ], "requiredStates": [ "Retryable failed state with affected operation, object, and preserved request context.", "Retry-ready state with a specific action label and safe scope.", "Retry pending state that disables duplicate attempts and confirms the same request is being sent.", "Retry succeeded state that returns users to recovered content, completed action, or download access.", "Retry failed again state with updated attempt count and cause.", "Cooldown or backoff state with next allowed attempt time or wait reason.", "Retry exhausted state with fallback, background, support, or return-later path.", "Non-retryable state that routes to correction, access request, policy explanation, or support instead of Retry.", "Duplicate-guarded side-effect state with idempotency, request reference, or deduplication visible enough for support." ], "interactionContract": [ "Retry repeats the same failed operation against the same request scope unless users explicitly edit that scope first.", "Activating Retry moves the control into a pending state and prevents a second activation until the attempt resolves or is cancelled.", "The interface reports success, still failed, cooldown, exhausted, or non-retryable outcome after each attempt.", "Retry does not clear forms, filters, selected files, drafts, or destination context unless the user deliberately resets them.", "If retry would create external side effects, the client and server share an idempotency or deduplication contract.", "Automatic retries respect attempt caps and backoff; manual retry does not bypass safety limits that protect the user or service.", "When the failure cause changes to validation, permission, policy, or final state, the UI replaces Retry with the action users can actually take." ], "implementationChecklist": [ "Classify failures into retryable transient, retryable after cooldown, user-correctable, permission-related, final, and unknown categories.", "Persist the original request payload or safe request reference so Retry does not broaden scope or lose user-entered data.", "Add idempotency keys or server-side deduplication for create, update, payment, send, invite, export, import, upload, and queue actions.", "Track attempt count, last attempt time, next allowed attempt, current in-flight request, and terminal exhausted state.", "Show operation-specific copy such as Retry export, Retry upload, or Retry connection check instead of an unexplained Try again.", "Guard against double click, keyboard repeat, back navigation, page refresh, and multi-tab duplicate attempts.", "Apply capped backoff and jitter for automatic or repeated attempts, and respect Retry-After or equivalent server timing when available.", "Announce retry pending, success, repeated failure, cooldown, exhausted, and non-retryable changes in a status region.", "Test success after retry, repeated failure, timeout, cancellation, offline transition, duplicate activation, stale request reference, and support escalation." ], "commonMisuses": [ "Offering Retry for every error regardless of whether the user or system state can change.", "Retrying immediately in a tight loop during service overload.", "Leaving both Retry and the original submit button enabled for the same side-effecting operation.", "Changing filters, selected files, amount, recipient, or destination between attempts without telling users.", "Hiding attempt count and cooldown, making users think the control is broken.", "Using retry to mask validation, permission, or policy errors that need correction or access." ], "critiqueQuestions": [ "What exact operation will run again, and can users see that scope before activating Retry?", "Why is this failure retryable rather than user-correctable, permission-related, final, or a broader outage?", "What prevents duplicate charges, records, messages, uploads, or exports if the first attempt actually reached the server?", "What is the attempt cap, backoff rule, and next path after repeated failure?", "Does the retry preserve forms, filters, files, scroll context, and request identity?", "Can keyboard and assistive technology users tell when retry is pending, cooled down, exhausted, or unavailable?" ], "relatedPatterns": [ "error-state", "loading-spinner", "offline-state", "progress-bar", "toast-only-critical-error" ], "comparisons": [ "retry-vs-error-state-vs-loading-spinner-vs-offline-state" ], "sourceIds": [ "aws-builders-library-retries-backoff-jitter", "stripe-idempotent-requests", "google-sre-addressing-cascading-failures", "microsoft-azure-retry-pattern" ] }, { "id": "review-before-submit", "completionStatus": "complete", "name": "Review before submit", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Final editable answer summary before committing a transaction", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users make mistakes in long or consequential transactions when they cannot inspect what the service captured, correct individual answers, or recognize that the next action will commit the data.", "solution": "Add a final review page that summarizes relevant captured answers, lets users change specific answers without losing progress, handles dependent changes before returning to review, and uses explicit submit copy before the post-submit confirmation page.", "uiGuidance": [ "Render a single review page immediately before commit with a clear title, grouped answer sections, readable key/value rows, per-answer or per-section Change actions, skipped optional answers when meaningful, and a primary button whose label names the committed action.", "Keep Change links close to the answer they affect and add accessible context so repeated links such as Change remain distinguishable to screen reader users." ], "uxGuidance": [ "Use review before submit to give users one final chance to verify and correct captured answers before a transaction is sent, paid, published, applied, or otherwise committed.", "Return users from a Change link to the exact owning question with answers pre-populated, then route them back to review without forcing unrelated pages, while asking any newly required dependent questions first." ], "uiExamples": { "good": [ "A claim review page has Applicant, Contact details, Evidence, and Declaration sections; each row shows the captured answer and a Change link with hidden context such as Change email address.", "A payment review page shows amount, payer, payment method, and billing address, then uses Pay now as the primary action rather than Continue." ], "bad": [ "A final page says Check your answers but shows only a paragraph and a Continue button with no answers, section headings, or change links.", "A review table shows Change repeated in every row with no hidden context and places the action far from the answer it changes." ] }, "uxExamples": { "good": [ "A user changes their phone number from review, lands on the phone page with the old value pre-filled, saves, and returns directly to review with other answers preserved.", "A user changes eligibility from Yes to No, the evidence section is marked needs review, the service asks the new required question, and final submit remains blocked until the review is current." ], "bad": [ "A user selects Change address, edits one field, then has to repeat every later page before finding the review page again.", "A user clicks Continue from a review page thinking there is another step, but the service submits the application immediately." ] }, "problemContext": [ "The user has answered several questions across one or more pages and the next action has legal, financial, account, eligibility, publication, payment, or service-routing consequences.", "Users may need to spot typos, wrong addresses, stale evidence, skipped optional answers, or conditional answers that no longer apply.", "The product can pre-populate previous answer pages and preserve state while users move between review and editing.", "A later confirmation page will provide receipt, reference number, next steps, or status after the irreversible or high-friction action is complete." ], "selectionRules": [ "Choose review before submit when users need to verify multiple captured answers immediately before committing a transaction.", "Use multi-step form for collecting and saving the answers that lead to review, not as a substitute for the final check gate.", "Use complete complex form when users are actively editing many related settings on one surface and need review before save inside that editor.", "Use error summary when the user needs to recover from validation errors, not when all valid answers need a final confirmation before submit.", "Use confirmation page only after submit, when the task should show receipt, reference number, and next steps instead of pre-submit Change links.", "Group answers into sections that match the journey or user mental model, and omit irrelevant conditional branches.", "Show skipped optional answers as Not provided when the absence itself needs review or can affect the outcome.", "Use Change links for individual answers or coherent sections; each link must return users to the correct answer with previous values pre-filled.", "After a changed answer creates new required questions or invalidates downstream answers, resolve that dependency before returning to review.", "Use a submit button label that states the action and consequence, not generic Continue." ], "requiredStates": [ "Initial review state with grouped captured answers, relevant sections, and explicit submit action.", "Answer changed state where the user returns to the owning question with the old value pre-populated.", "Return-to-review state after a changed answer saves without repeating unrelated pages.", "Skipped optional answer state shown as Not provided when meaningful.", "Stale dependent answer state after an upstream change invalidates a downstream answer.", "New dependent question state before returning to review when a change requires extra information.", "Validation blocking state when review cannot submit because a required answer is missing or stale.", "Submit-ready state after all shown answers are current and required declarations are satisfied.", "Submitted handoff state that routes to a confirmation page rather than keeping pre-submit Change links active." ], "interactionContract": [ "Review loads only after required upstream answers are saved or clearly marks missing required sections.", "Each Change action stores return context so saving the edited answer returns to review, not the next ordinary journey page.", "Edited pages show previous values exactly as last saved unless the answer was invalidated by a dependency rule.", "Changing an upstream answer recomputes later relevance and marks affected answers stale, removed, or newly required before submit.", "The review page excludes branches that do not apply, unless showing Not provided helps users verify an optional skipped answer.", "The primary action commits the transaction only after current answers, stale dependencies, and required declarations pass.", "After commit, the user lands on a confirmation page with receipt and next steps; review Change links are no longer the main recovery path." ], "implementationChecklist": [ "Inventory every answer, section heading, display label, stored value, edit route, dependency rule, optional-answer display rule, and final submit consequence.", "Build summary rows from canonical saved answers rather than reformatting ad hoc page text.", "Add Change links with specific accessible text and return-to-review context for each row or section.", "Pre-populate edit pages from saved data and preserve all unrelated answers after edit, validation, browser Back, and server errors.", "Recompute conditional branches after every changed answer and ask newly required questions before returning to review.", "Mark stale sections clearly and block submit until the affected answers are reviewed or corrected.", "Use final action copy that names the consequence, such as Send application, Pay now, Publish listing, or Update account.", "Route successful submit to a confirmation page with reference, receipt, status, or next steps.", "Test keyboard order, screen reader context for repeated Change links, mobile summary wrapping, long addresses, hidden conditional answers, skipped optional answers, browser Back, edit return, stale answers, and double-submit prevention." ], "commonMisuses": [ "Using a review page that contains no captured answers.", "Labelling the final commit button Continue.", "Sending users through every later page after they change one answer.", "Showing irrelevant conditional sections that the user never answered.", "Hiding skipped optional answers even when Not provided affects the outcome.", "Keeping stale downstream answers after an upstream answer changes.", "Putting repeated Change links in a table without accessible context.", "Treating a post-submit confirmation page as if it were the review step." ], "critiqueQuestions": [ "What exactly changes in the system when the user presses the final button?", "Can users see every relevant answer and tell which section each answer belongs to?", "Does each Change link return to the owning question with the current answer pre-populated?", "After saving a changed answer, does the service return to review without repeating unrelated pages?", "Which downstream answers become stale or irrelevant after each possible change?", "Does the page clearly separate pre-submit review from post-submit confirmation?" ], "relatedPatterns": [ "multi-step-form", "complete-complex-form", "single-page-form", "error-summary", "inline-validation" ], "comparisons": [ "review-before-submit-vs-multi-step-form-vs-complete-complex-form-vs-error-summary" ], "sourceIds": [ "govuk-check-answers-pattern", "govuk-summary-list-component", "govuk-form-structure-service-manual", "uswds-summary-box-component" ] }, { "id": "review-queue", "completionStatus": "complete", "name": "Review queue", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Actionable queue for triaging many items that need human review", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Review work becomes slow and unsafe when products show items needing attention as an ordinary list, hide why each item is queued, lose ownership, allow stale decisions, make urgency invisible, or provide bulk actions without clear scope and exceptions.", "solution": "Provide a focused review queue that filters and orders items by review criteria, exposes enough row context to triage safely, supports claim, assign, skip, escalate, inspect, decide, and bulk actions, refreshes counts and stale states, and hands reviewers into the right item detail or next item.", "uiGuidance": [ "Render review queue as an actionable worklist with queue scope, counts, filters, sort order, row reason, owner, priority, age or SLA, status, preview context, selection, and row actions.", "Separate queue-level triage from item-level review: the queue helps reviewers find, claim, prioritize, bulk-process, skip, escalate, or open items, while detailed records carry full evidence and decision history." ], "uxGuidance": [ "Use review queue when a team repeatedly processes a changing set of tickets, comments, pull requests, content items, cases, requests, or records that require human inspection and action.", "Keep the reviewer oriented across the whole workload by showing what changed, what is urgent, what is already claimed, which rows are stale, and what happens after each decision." ], "uiExamples": { "good": [ "A support queue shows New triage, SLA at risk, owner, customer, status, priority, age, preview text, assignment, and next actions without opening every ticket.", "A moderation queue has Held, Likely spam, Reported, and Escalated tabs, row evidence, policy reason, reviewer claim state, approve/remove/escalate actions, and bulk-action preview." ], "bad": [ "A review queue shows a flat list of titles with no reason, age, owner, status, priority, or action controls.", "A bulk Approve button processes every hidden filtered row without showing count, stale rows, or mixed eligibility." ] }, "uxExamples": { "good": [ "A reviewer claims the oldest SLA-at-risk ticket, opens a preview, assigns it to Billing, returns to the queue with the row removed, and lands on the next oldest item.", "A moderator filters held comments by likely spam, bulk removes five visible comments after previewing the count, skips one uncertain row, and sees the queue count update immediately." ], "bad": [ "Two reviewers open the same unclaimed item, both act, and the second decision overwrites the first with no stale-row warning.", "A reviewer marks a pull request reviewed from an old queue row after the author pushed new commits and re-requested review." ] }, "problemContext": [ "Many items can independently enter and leave the queue based on status, assignment, SLA, requested review, moderation hold, reported content, code ownership, customer tier, priority, or workflow state.", "Reviewers often need to choose the next item, scan workload, process visible rows, avoid duplicate work, and recover when the underlying item changes.", "The queue may be personal, shared, team-scoped, role-restricted, saved, filtered, sorted, grouped, or ordered by SLA or priority.", "Actions may be low-risk triage such as assign or skip, or consequential review decisions such as approve, request changes, remove, reject, merge-block, publish-block, or escalate." ], "selectionRules": [ "Choose review queue when the interface is primarily for processing multiple items that need review or triage over time.", "Use approval workflow when the focus is one submitted request and its governed route of required approvers.", "Use saved filter when the product only saves list criteria and does not provide review ownership, queue counts, row reasons, decision actions, or workload handling.", "Use activity log when users need to inspect past events rather than decide which queued item to handle next.", "Use notification center when reviewers need alerts, but route notifications into the queue or item rather than replacing queue state.", "Use table or list view when users are browsing records without review-specific state, assignment, SLA, or actions.", "Show queue membership reason, owner, age, priority, SLA or due state, review status, and source so reviewers can triage without opening every item.", "Support claim or assignment for shared queues when duplicate work is costly.", "Treat stale, already handled, reassigned, permission-limited, blocked, duplicate, and empty states as queue states with clear recovery.", "Require bulk-action previews for selected count, hidden filtered rows, stale rows, mixed eligibility, and irreversible outcomes." ], "requiredStates": [ "Queue loading and count state", "Filtered or grouped queue state", "Empty queue state", "Row preview state", "Claimed or assigned row state", "Unassigned row state", "SLA at risk or overdue row state", "Stale row changed since load state", "Selected rows and bulk-action preview state", "Action succeeded and row removed or moved state", "Skipped or snoozed row state", "Escalated or blocked row state", "Permission-limited row state", "Already reviewed by someone else state" ], "interactionContract": [ "Queue membership is derived from canonical item state and refreshes counts when items enter, leave, or change status.", "Each row exposes why it is in the queue and enough context for safe triage before opening the full record.", "Opening a row preserves queue position, filter, sort, selection, and return context.", "Claim, assign, skip, snooze, escalate, approve, reject, remove, request changes, and mark reviewed actions update the canonical item and the queue row.", "Shared queues prevent or surface duplicate work through claim state, active reviewer state, stale-row warnings, or optimistic conflict checks.", "Bulk actions apply only to the previewed scope and report per-row exceptions for stale, ineligible, hidden, permission-limited, or already processed items.", "After a row action, focus moves to the updated row, next row, or queue status rather than resetting to the top without explanation.", "Notifications, reminders, and direct links open the matching queue, filtered queue, or item detail with current state." ], "implementationChecklist": [ "Define queue sources, membership criteria, personal and shared scopes, row columns, sort order, grouping, count semantics, permissions, and stale-row detection.", "Model queue row state separately from item detail so the list can show reason, status, owner, age, priority, SLA, source, preview, and action eligibility.", "Implement filters, saved queue views, priority ordering, search within queue, selection, bulk preview, row preview, claim, assign, skip, snooze, escalate, and next-item navigation.", "Add conflict checks before row and bulk decisions to detect rows handled by someone else, changed since load, reassigned, or no longer eligible.", "Update counts, empty states, row positions, active filters, and focus after each decision.", "Show per-row failure and retry for failed actions instead of silently removing rows.", "Limit sensitive preview details by reviewer permission and provide safe disclosure when content cannot be shown in a shared queue.", "Test stale rows, concurrent reviewers, hidden filtered selection, mobile row wrapping, long titles, high counts, empty queues, permission-limited rows, keyboard action order, screen reader status updates, and bulk exceptions." ], "commonMisuses": [ "Using an ordinary table with no review reason, urgency, ownership, or decision actions.", "Treating review queue as approval workflow and hiding many-item workload controls.", "Making queue counts stale after a row action.", "Allowing hidden rows to be bulk-processed without preview.", "Letting two reviewers unknowingly work the same row.", "Hiding SLA, age, priority, or source context needed for triage.", "Dropping reviewers back at the top after every item.", "Sending notification links to a generic dashboard instead of the queue or item." ], "critiqueQuestions": [ "Why is each row in this queue, and can reviewers see that reason before opening it?", "What tells reviewers which item should be handled next?", "Can reviewers claim, assign, skip, escalate, or bulk-process without losing scope clarity?", "How does the queue handle rows changed or completed by someone else?", "Do counts, filters, empty states, and focus update immediately after actions?", "Are notifications and saved views aligned with the canonical queue state?" ], "relatedPatterns": [ "approval-workflow", "saved-filter", "activity-log", "notification-center", "table", "filter-panel", "list-view", "details-panel" ], "comparisons": [ "review-queue-vs-approval-workflow-vs-saved-filter-vs-activity-log" ], "sourceIds": [ "atlassian-jira-service-management-queues", "zendesk-ticket-views-workflow", "zendesk-views-api", "github-requesting-pull-request-review", "github-about-pull-request-reviews", "youtube-studio-held-comments-review" ] }, { "id": "saved-filter", "completionStatus": "complete", "name": "Saved filter", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Persisted named filter criteria applied to a list, table, board, or dashboard", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users repeatedly rebuild the same filter criteria for large lists, but ordinary filter controls lose context between sessions and vague saved presets make it unclear what will change when applied.", "solution": "Provide named saved-filter presets that store filter criteria, expose criteria summaries, owner and visibility, apply to current data, preserve unrelated query and sort state by default, and make update versus copy decisions explicit.", "uiGuidance": [ "Place Save filter close to the active filter controls and show a criteria preview that names every stored field, operator, and value before users commit it.", "List saved filters with name, owner, visibility, scope of application, active state, last updated metadata, and actions for Apply, Edit, Duplicate, Update, Share, and Delete." ], "uxGuidance": [ "Use saved filter when users repeatedly apply the same filter values to a changing list and need to reuse those criteria across sessions or teams.", "Keep saved filters criteria-only unless the UI explicitly says it also saves query text, sort order, visible columns, route, view mode, or alert behavior." ], "uiExamples": { "good": [ "A case queue exposes saved filters named High priority benefits and My review queue, each with status, team, priority, and date chips before users apply them.", "An active preset banner says High priority benefits applied, shows that search query appeal and sort Newest are unchanged, and offers Update filter or Save copy.", "A team filter list marks owner, visibility, last updated date, and unavailable criteria when a field was removed." ], "bad": [ "A star button saves the current table rows without showing which filters created them.", "A list called Saved mixes saved filters, saved searches, recent views, pinned tabs, and browser bookmarks.", "Applying a filter preset silently resets query text, sort order, and selected columns with no explanation." ] }, "uxExamples": { "good": [ "A benefits worker applies High priority benefits to the current appeal search; the query stays appeal while status, team, and priority filters change.", "A supervisor edits a shared queue preset and is asked whether to update the team filter or save a private copy.", "A builder sees that a removed field invalidated one criterion and can delete that criterion without losing the rest of the preset." ], "bad": [ "Saving a filter freezes today's 14 rows, so tomorrow's newly urgent benefits cases never appear.", "A private preset and a team preset have the same label, causing users to overwrite the shared operational queue.", "Removing an invalid criterion silently broadens the saved filter and exposes records that should have stayed hidden." ] }, "problemContext": [ "The product has operational lists, record tables, ticket views, case queues, boards, dashboards, or base views with recurring filter criteria.", "Users need personal and team shortcuts for criteria such as status, owner, priority, segment, date range, stage, tag, or assignment group.", "Filter presets may control work queues or limited views, so silent changes can hide urgent work or expose records." ], "selectionRules": [ "Choose saved filter when users need to preserve and reapply a named set of filter values, operators, and fields across sessions.", "Use saved filter when the result set should stay dynamic and include records that match the criteria later.", "Show criteria summaries before Apply, Save, Update, or Share so users can predict exactly which filters will change.", "Preserve query text, sort order, page size, selected columns, and view mode unless the saved object explicitly includes those properties.", "Separate private, team, and global presets with owner and visibility labels before users can overwrite or delete them.", "Use filter panel for the current criteria builder and saved filter for the persisted reusable preset created from it.", "Use filter chips to display and remove active criteria after a saved filter has been applied.", "Use saved search instead when users save query text, search scope, ranking, subscriptions, reports, dashboards, or a full named result view.", "Use sort controls when the saved object only changes ordering, not which records are included.", "Treat invalid or permission-denied criteria as a recoverable preset state instead of silently ignoring them." ], "requiredStates": [ "No saved filter selected while current filters are still visible and saveable.", "Saved filter list with active, private, team, global, owner, and last-updated states.", "Criteria preview that lists each field, operator, and value included in the preset.", "Applied preset state with criteria chips, result count, and separate query and sort summary.", "Modified-from-saved state when current filter values no longer match the active preset.", "Save as new state with name, visibility, and duplicate-name handling.", "Update existing state with shared-filter warning when the preset affects other users.", "Invalid criterion state for removed fields, missing options, permissions, or unsupported operators.", "Empty saved-filter list state with a path to save the current filter criteria.", "Deleted or unavailable preset state that explains why the saved filter cannot be applied." ], "interactionContract": [ "Saving stores filter criteria definitions, not the current result IDs.", "Applying a saved filter replaces the relevant filter fields and leaves unrelated search, sort, column, and view state unchanged unless documented otherwise.", "The UI visibly marks which saved filter is active and whether the current criteria have diverged from it.", "Updating a preset changes future applications of that saved filter and should warn when the preset is shared or drives a queue.", "Duplicating or saving a copy preserves the current criteria while assigning a new owner, name, and visibility.", "Clearing the saved-filter selection removes the active preset identity without clearing all current filters unless the user chooses Clear filters.", "Deleting or losing access to a preset removes it from saved-filter lists and explains any affected queue, tab, dashboard, or shortcut.", "Invalid criteria remain visible with an edit or remove path so users understand why result counts changed." ], "implementationChecklist": [ "Persist canonical filter criteria as field, operator, value, and conjunction data rather than display labels or row IDs.", "Render a human-readable criteria summary in the saved-filter list, active banner, save form, and update confirmation.", "Store owner, visibility, shared audience, applicable object or table, last updated time, and whether the preset is system, private, team, or global.", "Keep query text and sort order in separate state unless the saved-filter model includes them and the UI says so.", "Detect duplicate names within the same visibility scope and require enough disambiguation for private and shared presets.", "Warn before updating, deleting, or broadening a saved filter used by a team queue, default view, dashboard, automation, or report.", "Validate saved criteria against current schema, permissions, and available option values before applying them.", "Announce apply, save, update, copy, invalid-field, and delete outcomes through a stable status region." ], "commonMisuses": [ "Treating the visible table rows as the saved object instead of storing field, operator, and value conditions.", "Treating every saved view as a saved filter even when it also saves columns, sorting, route, chart settings, or query text.", "Applying a preset that clears query text or sort order without warning.", "Using only color, position, or a star icon to show the active saved filter.", "Mixing saved filters with saved searches, recent searches, recently viewed records, and bookmarks.", "Silently dropping invalid criteria and widening the result set." ], "critiqueQuestions": [ "Can users tell which exact field, operator, and value criteria are stored before applying the preset?", "Does applying the saved filter preserve unrelated query, sort, and view state unless the UI explicitly says otherwise?", "Is it clear who owns the preset, who can see it, and whether updating it affects a team queue?", "Can users distinguish temporary filter edits from Update saved filter and Save as new?", "What happens when a saved criterion references a field, option, or record the user can no longer access?", "Are saved filters visually and behaviorally separate from saved searches, filter chips, current filter panels, bookmarks, and recent history?" ], "relatedPatterns": [ "filter-panel", "filter-chips", "saved-search", "sort-controls", "basic-search", "faceted-search", "no-results-recovery", "checkbox-group" ], "comparisons": [ "saved-filter-vs-filter-panel-vs-saved-search-vs-filter-chips" ], "sourceIds": [ "servicenow-save-use-list-filters", "hubspot-saved-views", "zendesk-ticket-views", "airtable-filtering-records-conditions" ] }, { "id": "saved-search", "completionStatus": "complete", "name": "Saved search", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Persisted named search criteria for rerunning a dynamic result set", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users repeatedly reconstruct the same search criteria, but saved-search UI often hides what is stored, whether results are dynamic, who owns it, and whether edits affect a private or shared search.", "solution": "Provide a named saved-search object that stores query criteria rather than result snapshots, exposes ownership and visibility, reruns against current data, supports favorite/share/subscribe/edit/copy/delete lifecycle actions, and clearly separates temporary changes from updates to the saved criteria.", "uiGuidance": [ "Render Save search near the active query and result summary, and show exactly which query text, filters, scope, and sort will be stored.", "List saved searches with names, ownership or visibility, favorite state, last-run or updated metadata, and clear actions for Run, Edit, Copy, Share, Subscribe, and Delete." ], "uxGuidance": [ "Use saved search when users repeatedly need the same dynamic result set and must rerun it without rebuilding query, filters, sort, and scope.", "Preserve the distinction between running a saved search temporarily and updating the saved criteria, especially when a saved search is shared or subscribed to." ], "uiExamples": { "good": [ "A search results page shows Save search beside the result count, opens a naming dialog, and previews query, filters, scope, and sort before saving.", "A saved-search sidebar groups My searches and Shared searches, with favorite stars and private/shared badges.", "An opened saved search displays its name, owner, visibility, criteria summary, result count, and actions to edit, duplicate, subscribe, or delete." ], "bad": [ "A star icon saves an unnamed search with no confirmation or criteria summary.", "Saved searches, recently searched terms, browser bookmarks, and saved filters are mixed in one list called Saved.", "A shared saved search looks identical to a private one and gives no clue who can see or edit it." ] }, "uxExamples": { "good": [ "A user saves a search for Open renewal risks, returns next week, reruns it, and sees newly matching cases included.", "A user edits criteria from a shared saved search and is asked whether to update the shared search or save a copy.", "A user subscribes to a saved search and can see the schedule, owner, and criteria that will drive future alerts." ], "bad": [ "Saving search stores only the current three results, so future matching records are missing.", "A temporary filter change overwrites a team saved search without warning.", "Deleting a saved search leaves dashboard cards, alerts, or sidebar links broken with no explanation." ] }, "problemContext": [ "The product has large search, issue, work item, document, case, ticket, inbox, or audit-log result sets.", "Users return to the same criteria over time, across sessions, or across teams.", "Saved searches can become shared operational artifacts that drive dashboards, alerts, queues, exports, and team workflows." ], "selectionRules": [ "Choose saved search when users need to store and rerun a named query or criteria set across sessions.", "Use saved search when results should remain dynamic and include records that match the saved criteria in the future.", "Show Save search only after there is meaningful criteria to preserve, such as query text, filters, scope, sort, or advanced clauses.", "Use clear names and criteria summaries so users can recognize what will run before they open or subscribe to a saved search.", "Expose owner, privacy, shared audience, favorite state, last updated, and alert subscription state when saved searches can affect teams.", "Ask whether to update the saved search or save a copy when users change criteria after opening an existing saved search.", "Use recently searched for passive query history and recently viewed for opened items; neither should look like an intentionally saved search.", "Use filter panel controls when users are still building current criteria rather than managing a persisted query object.", "Use saved filter as a separate pattern when users save only reusable filter values without query text, result scope, sort, alert, or shared saved-view lifecycle." ], "requiredStates": [ "Unsaved current search with Save search available only when criteria are meaningful.", "Save dialog or inline form with name, criteria summary, visibility, and optional description.", "Saved search selected state with name, result count, criteria summary, owner, visibility, and management actions.", "Modified-from-saved state where current criteria no longer match the saved definition.", "Shared or private state with clear audience and edit permissions.", "Subscribed alert state with schedule and unsubscribe path.", "Deleted or unavailable saved search state with explanation and recovery path.", "Empty saved-search list state with a path back to create one from active search criteria." ], "interactionContract": [ "Saving stores query criteria, filters, sort, and scope as a reusable definition, not just the current result IDs.", "Running a saved search loads its criteria, updates the result count against current data, and visibly marks the active saved search.", "Changing criteria after running a saved search creates a modified state until the user updates the saved search, saves a copy, or discards changes.", "Sharing exposes who can view, run, edit, copy, subscribe to, or delete the saved search.", "Favorites affect quick access only and do not change query criteria or sharing.", "Subscriptions or alerts use the saved criteria and show enough schedule and ownership detail to audit future notifications.", "Deleting or losing permission to a saved search removes it from quick access while preserving understandable recovery or explanation." ], "implementationChecklist": [ "Capture the canonical search representation, including query text, filters, sort, scope, and advanced syntax.", "Show a criteria preview before save and in the saved-search detail header.", "Require a meaningful name and prevent duplicate names from becoming indistinguishable.", "Store owner, visibility, shared audience, favorite state, description, updated time, and alert subscription state.", "Provide explicit Run, Edit, Save copy, Share, Subscribe, Favorite, Rename, and Delete paths where those actions exist.", "Warn before overwriting a shared saved search or changing criteria that drive alerts, dashboards, queues, or exports.", "Use permission-aware lists so private saved search names, criteria, and result counts do not leak.", "Show result counts as current data, and explain when counts differ from the last run because matching records changed." ], "commonMisuses": [ "Saving static result IDs instead of reusable criteria.", "Using a star or bookmark as the only save action without showing name, criteria, owner, or visibility.", "Overwriting a shared search when the user intended a temporary refinement.", "Mixing saved searches with search history, recently viewed items, saved filters, and browser bookmarks.", "Letting subscriptions, dashboards, or exports depend on saved searches without showing the underlying criteria.", "Leaking private saved-search names or result counts in shared sidebars, dashboards, or notification lists." ], "critiqueQuestions": [ "Can users tell exactly which query, filters, sort, and scope will be saved?", "Does rerunning the saved search use current data rather than an old result snapshot?", "Is it clear whether the search is private, shared, favorited, subscribed, or owned by someone else?", "When criteria change, does the UI distinguish update saved search from save copy and temporary run?", "Can users manage stale, deleted, duplicated, or permission-denied saved searches without breaking their workflow?", "Are saved searches visually separate from recent searches, recently viewed records, saved filters, and bookmarks?" ], "relatedPatterns": [ "basic-search", "filter-panel", "sort-controls", "recently-viewed", "search-suggestions", "command-palette", "no-results-recovery" ], "comparisons": [ "saved-search-vs-basic-search-vs-filter-panel-vs-recently-viewed" ], "sourceIds": [ "atlassian-jira-saved-search", "atlassian-jira-save-search-filter", "github-issues-saved-views", "azure-devops-managed-queries" ] }, { "id": "saved-view", "completionStatus": "complete", "name": "Saved view", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Persisted named presentation state for a data workspace", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Data-heavy products let users tune columns, filters, grouping, layouts, and sort order, but without a saved view users must rebuild the same presentation repeatedly and teams cannot tell which shared view is authoritative.", "solution": "Provide a named saved-view object that persists the intended presentation state, rerenders current data through that state, exposes ownership and visibility, separates temporary changes from updates, and handles copies, defaults, permissions, invalid fields, and shared dependencies explicitly.", "uiGuidance": [ "Render saved views as named, selectable workspace presentations with visible owner or visibility, active state, saved layout mode, columns or fields, grouping, sort, filters, and last-updated metadata.", "Show exactly which display settings will be saved before Save, Update, Duplicate, Share, Set default, or Delete actions: layout, visible columns, column order, grouping, filters, sort, density, and tab placement when applicable." ], "uxGuidance": [ "Use saved view when users need to return to a complete operational presentation of a changing dataset rather than rebuilding columns, layout, grouping, filters, and sort every session.", "Keep temporary view tweaks separate from updating the saved definition, especially for shared, default, dashboard-backed, or queue-driving views." ], "uiExamples": { "good": [ "A support queue has saved views named My urgent tickets, Team backlog, and SLA breach risk, each showing columns, sort, filters, owner, and private or team visibility before users apply it.", "A project workspace lets users save a table view with Owner, Status, Due date, and Risk columns, then duplicate it as a board view grouped by Status without overwriting the original." ], "bad": [ "A tab labelled Saved view applies hidden filters, changes columns, and switches layout with no preview or active-state summary.", "A saved view list mixes saved filters, saved searches, static exports, bookmarks, and recent pages under one generic Saved label." ] }, "uxExamples": { "good": [ "A manager opens SLA breach risk, sees the board layout, grouped Status lanes, five saved columns, and current result count, then changes density and saves a private copy instead of overwriting the team view.", "A user opens a shared ticket view, edits columns temporarily, and the UI marks Unsaved changes with Update shared view and Save as new options." ], "bad": [ "A user changes one column while reviewing a team queue and accidentally updates the shared default for everyone.", "A saved view references a removed field, silently drops that field, and changes the queue count without explaining which saved setting failed." ] }, "problemContext": [ "The workspace has a changing data set such as records, tickets, issues, projects, orders, assets, opportunities, tasks, alerts, or audit entries.", "Users can configure several presentation properties, such as table versus board layout, visible fields, column order, grouping, filters, sort, density, or tabs.", "Different roles need different operational views of the same underlying data.", "Saved views may be private, team, global, default, pinned, duplicated, embedded in dashboards, linked from navigation, or used as work queues.", "Schema, permissions, fields, teams, and data change over time, so saved views need stale or invalid-state handling." ], "selectionRules": [ "Choose saved view when users need to persist a named combination of layout, columns, grouping, filters, sort, density, and other display preferences for a data surface.", "Use saved search when the saved object is mainly query criteria, search scope, ranking, subscriptions, or rerunnable search behavior.", "Use saved filter when only reusable filter values should be stored and query, sort, columns, and layout should remain separate.", "Use table, list view, board, calendar, or dashboard layout for the actual current presentation; saved view is the management layer that stores how that presentation is configured.", "Use custom dashboard when users compose multiple widgets, charts, or cross-source summaries rather than one configured result surface.", "Use pinned items or favorites when users only need quick access, not saved display state.", "Use a static export or report when users need a fixed snapshot rather than current records rendered through saved criteria and layout.", "Avoid saved view when users cannot predict which settings will be saved or when shared updates cannot be permissioned or audited.", "Avoid saved view for one-off column hiding that does not need naming, reuse, sharing, defaulting, or recovery.", "Avoid using saved view names, counts, or criteria in shared navigation when they reveal private or unauthorized data." ], "requiredStates": [ "No saved view selected with current display settings visible and saveable.", "Saved view list with active, private, team, shared, pinned, default, owner, last-updated, and result-count states.", "Applied saved view state with view name, layout, columns, filters, sort, grouping, and count summary.", "Modified-from-saved state when current display settings no longer match the saved definition.", "Save as new, update existing, duplicate, rename, share, set default, pin, and delete states.", "Shared-view update warning when changes affect other users, dashboards, queues, or navigation links.", "Invalid saved view state for removed columns, missing fields, permission-denied filters, unavailable grouping, or unsupported layout.", "Empty saved-view list state with a path to save the current presentation.", "Deleted or unavailable saved view state with explanation and replacement route.", "Narrow-screen state that preserves active view identity and access to view actions without hiding critical status." ], "interactionContract": [ "Saving stores a canonical view definition, not a static list of current row IDs.", "Applying a saved view changes only the settings listed in its preview and updates the result set from current data.", "The active saved view name, visibility, and modified state remain visible near the data surface.", "Temporary changes to columns, filters, sort, grouping, density, or layout create a modified state until the user updates, saves a copy, or discards changes.", "Updating a shared or default view confirms audience, dependencies, and edit permission before the saved definition changes.", "Duplicating a saved view preserves the current configuration while assigning a new owner, name, visibility, and optional tab placement.", "Invalid or unavailable saved settings remain visible with repair paths instead of silently broadening results or hiding columns.", "Deleting or losing access to a saved view explains affected shortcuts, dashboards, default routes, or team queues." ], "implementationChecklist": [ "Define the canonical view model: data source, layout mode, visible fields, field order, filters, sort, grouping, density, tab placement, owner, visibility, and default status.", "Show a human-readable view summary before Apply, Save, Update, Duplicate, Share, Set default, or Delete.", "Separate view state from row selection, transient scroll position, temporary search text, and one-off local UI state unless the product explicitly includes those settings.", "Store owner, visibility, editable audience, last updater, updated time, dependency use, and whether the view is private, team, global, system, pinned, or default.", "Detect modified-from-saved state whenever saved columns, filters, sort, layout, grouping, or density differ from the active definition.", "Validate saved columns, filters, grouping fields, and permissions against the current schema before applying the view.", "Warn before updating or deleting a saved view used by dashboards, shared tabs, queues, automations, reports, or default navigation.", "Test duplicate names, private and shared permissions, invalid fields, mobile view action access, keyboard management, and screen-reader announcements." ], "commonMisuses": [ "Saving current rows instead of presentation settings and dynamic criteria.", "Calling a saved filter a saved view while hiding that columns, layout, grouping, and sort are also stored.", "Overwriting a shared or default view when the user intended a temporary personal adjustment.", "Applying a saved view with no preview of changed columns, filters, sort, grouping, or layout.", "Mixing saved views with saved searches, saved filters, recent views, exports, and bookmarks in one list.", "Silently dropping invalid columns or permission-denied filters and changing the visible result set.", "Leaking private view names, criteria, counts, or columns in shared tabs or dashboards.", "Making the active view look like a normal tab without showing modified or unsaved changes." ], "critiqueQuestions": [ "Which display settings are stored in this saved view, and can users inspect them before applying or updating it?", "Does applying the view rerender current data rather than a stale row snapshot?", "Is it clear who owns the view, who can see it, who can edit it, and whether it is a default or shared operational queue?", "What happens when users change columns, filters, sort, grouping, or layout after opening a saved view?", "How are removed fields, unavailable grouping, invalid criteria, or permission changes repaired?", "Would saved search, saved filter, table, dashboard, favorite, pinned item, or static export better match what users are trying to preserve?" ], "relatedPatterns": [ "saved-search", "saved-filter", "filter-panel", "sort-controls", "table", "list-view", "data-grid", "kanban-board" ], "comparisons": [ "saved-view-vs-saved-search-vs-saved-filter-vs-table" ], "sourceIds": [ "hubspot-saved-views", "github-issues-saved-views", "zendesk-ticket-views", "github-projects-changing-layout", "github-projects-board-layout" ] }, { "id": "scheduling", "completionStatus": "complete", "name": "Scheduling", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Workflow for arranging time, attendees, availability, recurrence, and reminders", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Scheduling fails when products reduce the task to date and time fields, hiding availability, attendees, calendars, rooms, recurrence, timezone, buffers, reminders, invitation state, and the difference between saving a draft and sending a scheduled event.", "solution": "Provide a scheduling workflow that gathers event details, checks availability and constraints, previews conflicts and timezone effects, supports recurrence and reminders, distinguishes save versus send, and provides clear reschedule, cancellation, and response states.", "uiGuidance": [ "Render scheduling as a coordinated time-planning workflow with title, calendar, attendees, required and optional people, rooms or resources, location or conference link, date, start and end time, timezone, recurrence, availability, reminders, and save or send outcome.", "Show free/busy conflicts, unavailable resources, hidden calendars, buffer rules, minimum notice, maximum bookings, recurrence scope, attendee response state, and timezone interpretation as explicit states rather than treating scheduling as only date and time entry." ], "uxGuidance": [ "Use scheduling when users arrange a meeting, event, availability rule, or recurring time plan that must account for people, calendars, rooms, buffers, time zones, recurrence, reminders, invitations, or conflicts.", "Keep users clear about whether they are drafting, saving to their own calendar, sending invitations, rescheduling one occurrence, changing a full series, or publishing availability for others to choose." ], "uiExamples": { "good": [ "A meeting scheduler shows required attendees, free/busy bars, suggested times, selected timezone, room availability, video link, recurrence, reminders, and a Send invitation button.", "An availability schedule editor shows working hours, buffers before and after meetings, minimum notice, maximum bookings per day, checked calendars, and start time increments before sharing the scheduling page." ], "bad": [ "A form asks for date and time only, then sends invitations without checking attendee or room conflicts.", "A recurring event editor hides whether changes apply to one occurrence or the whole series." ] }, "uxExamples": { "good": [ "A team lead adds three required attendees, sees one conflict at 10:00, chooses an 11:30 suggested time, adds a room and video link, sends invitations, and sees pending responses.", "A consultant sets availability from 9:00 to 15:00, adds 15-minute buffers, locks the event to Europe/London, limits bookings to four per day, and checks the public scheduling page." ], "bad": [ "A scheduler sees an empty-looking time grid because hidden calendars are not included, books a meeting, and later discovers the host is already busy.", "A user moves one weekly event and unintentionally shifts every event in the series." ] }, "problemContext": [ "The user is arranging time for a meeting, event, availability schedule, class, service window, internal review, reminder, or recurring series.", "The schedule may involve required and optional attendees, rooms, resources, calendars, conferencing, location, agenda, attachments, and reminders.", "Availability can depend on free/busy calendars, hidden calendars, working hours, buffers, minimum notice, maximum bookings, resource capacity, and attendee response.", "Timezone, daylight saving, locale, recurrence expansion, and travel can change what a displayed time means.", "Scheduling may create invitations, reserve calendar time, publish availability, notify people, update a series, or reschedule/cancel existing events." ], "selectionRules": [ "Choose scheduling when users coordinate time across participants, calendars, availability, resources, recurrence, reminders, or invitations.", "Use booking when an invitee or customer reserves an available service, resource, or appointment slot with capacity, confirmation, cancellation, or payment rules.", "Use calendar view when users need to inspect existing scheduled events by spatial placement rather than complete the scheduling workflow.", "Use date picker or time picker for single field entry inside scheduling only when availability and conflict rules are handled elsewhere.", "Use date range picker when selecting a span is the main input, not when attendees, recurrence, reminders, and invitations define the task.", "Use notification center for schedule-related alerts and responses, not as the scheduling editor.", "Expose required attendees, optional attendees, room or resource availability, selected calendar, timezone, duration, recurrence, reminders, and send/save outcome before committing.", "Show conflicts and suggested alternatives when required attendees, rooms, checked calendars, or buffers are unavailable.", "For recurring events, show recurrence pattern, timezone, end condition, exceptions, and edit scope for one occurrence or the whole series.", "Distinguish draft, saved only, invitation sent, pending responses, accepted, declined, tentative, rescheduled, canceled, and failed-send states." ], "requiredStates": [ "Draft event state", "Attendee entry and resolution state", "Availability loading state", "Free/busy conflict state", "Suggested time state", "Room or resource unavailable state", "Timezone selected or changed state", "Recurring series setup state", "Edit one occurrence or full series state", "Reminder and notification setup state", "Save without sending state", "Send invitation state", "Pending attendee response state", "Accepted, declined, or tentative response state", "Reschedule state", "Cancel event state", "Failed send or stale availability state" ], "interactionContract": [ "Changing date, time, duration, attendees, resources, timezone, recurrence, or checked calendars recomputes availability before send.", "Required attendee and resource conflicts block or warn before sending, while optional attendee conflicts are clearly marked as optional.", "Suggested times identify why they are available, which people and rooms are free, and what timezone is displayed.", "Saving to a personal calendar and sending invitations are distinct actions when the platform supports both.", "Recurring events preserve timezone and require users to choose whether edits affect one occurrence, future occurrences, or the full series.", "Rescheduling retains agenda, conferencing, attachments, reminders, attendees, and response history unless the user changes them.", "Cancellation explains whether notifications will be sent and whether rooms, resources, and availability slots are released.", "Notifications and calendar updates deep-link back to the current event state rather than stale draft details." ], "implementationChecklist": [ "Define event fields, attendee roles, room/resource model, availability sources, checked calendars, timezone policy, recurrence rules, reminder rules, save/send semantics, and audit or notification requirements.", "Build availability checks for attendee free/busy, rooms, resources, buffers, working hours, minimum notice, maximum bookings, hidden calendars, and permission-limited calendars.", "Expose date, start time, end time, duration, timezone, recurrence, location, conferencing, calendar selection, reminders, attachments, and description with validation and conflict states.", "Add suggested time logic that names available people/resources and explains why a time is blocked.", "Implement recurrence expansion, exception editing, timezone stability, daylight-saving checks, and series edit scope.", "Support save draft, save without sending, send invitations, reschedule, cancel, remove attendee, change room, and update reminders with clear status messages.", "Test required attendee conflict, optional attendee conflict, room unavailable, hidden calendar, timezone change, recurring series, one-occurrence edit, daylight-saving boundary, stale availability, failed invitation send, mobile, keyboard, and screen reader status updates." ], "commonMisuses": [ "Treating scheduling as only a date field and a time field.", "Hiding attendee or room conflicts until after invitations are sent.", "Sending invitations when users expected to save a draft.", "Changing an entire recurring series when users intended one occurrence.", "Showing times without timezone when attendees are in different regions.", "Ignoring buffers, minimum notice, maximum daily meetings, or checked calendars.", "Treating optional attendee conflicts the same as required attendee conflicts.", "Letting stale availability produce double-booked meetings." ], "critiqueQuestions": [ "Who or what is being scheduled, and which participants or resources are required?", "Which calendars, working hours, buffers, and availability rules are included or hidden?", "What timezone is the user seeing, and will attendees see the same local time?", "Is this a one-time event, recurring series, one occurrence, or availability schedule?", "Does the action save a draft, reserve time, send invitations, publish availability, reschedule, or cancel?", "What happens when availability changes between viewing the schedule and sending it?" ], "relatedPatterns": [ "calendar-view", "date-picker", "time-picker", "date-range-picker", "notification-center", "conflict-state", "review-before-submit", "confirmation-page" ], "comparisons": [ "scheduling-vs-booking-vs-calendar-view-vs-date-picker" ], "sourceIds": [ "google-calendar-create-event", "google-calendar-appointment-schedule", "microsoft-outlook-schedule-meeting-event", "microsoft-outlook-web-scheduling-assistant", "calendly-availability-settings", "calendly-time-zones-overview", "google-calendar-api-recurring-timezone" ] }, { "id": "scope-clarification", "completionStatus": "complete", "name": "Scope clarification", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "AI clarification surface that asks for missing task boundaries before answering, planning, retrieving, or using tools", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI systems often receive requests with missing boundaries, conflicting references, or risky scope, and answering or acting immediately can create irrelevant output, wrong assumptions, privacy exposure, unsafe tool use, or user mistrust.", "solution": "Ask a concise, task-specific clarification question before proceeding, preserve the original request, show the missing boundary, provide bounded choices and defaults when safe, store the chosen scope for the current task, and explain how the answer or action will use that scope.", "uiGuidance": [ "Render scope clarification as a focused question tied to the user's request, with the missing boundary named in plain language: object set, timeframe, audience, source set, authority, output depth, risk limit, or action target.", "Offer constrained choices when possible, preserve the original request, show what will proceed after the answer, and provide safe skip, use default, or cancel paths when ambiguity is acceptable." ], "uxGuidance": [ "Use scope clarification when an AI request is too broad, underspecified, conflicting, high-impact, or likely to produce the wrong answer unless the user narrows the task first.", "Ask the smallest useful clarification before the system answers, plans, retrieves, or acts; avoid turning clarification into a long interview or silently choosing hidden defaults." ], "uiExamples": { "good": [ "An assistant receives Summarize the issues and asks Which issue set should I summarize? with Current sprint, All open issues, and Selected label choices before generating.", "A policy assistant asks Should I answer for contractors, full-time employees, or both? and shows that the original prompt will resume after the user chooses." ], "bad": [ "The assistant guesses all workspaces, creates a long answer, and never reveals that the original request lacked an object boundary.", "The assistant responds with ten open-ended questions even though one scope choice would let the task proceed." ] }, "uxExamples": { "good": [ "A user asks for a customer email draft; the assistant asks whether the audience is trial users, enterprise admins, or all affected accounts before drafting.", "A user asks an agent to clean up records; the agent asks whether to apply changes to visible filtered records or the whole workspace before showing a plan." ], "bad": [ "A user asks to update permissions and the AI acts on every team because the UI did not clarify the target scope.", "A user answers a clarification question, but the assistant forgets the answer on the next step and asks again." ] }, "problemContext": [ "Users may refer to unclear objects, pronouns, dates, audiences, repositories, workspaces, source sets, accounts, policies, regions, files, tools, or authority levels.", "An AI answer may need different evidence, tone, output structure, or safety handling depending on selected scope.", "An AI agent may be able to retrieve data, draft messages, edit records, send notifications, create tickets, delete items, or run tools across multiple possible targets.", "A hidden default may be harmless in low-risk writing tasks but unsafe for permission changes, customer actions, payments, deletes, policy advice, or public publication.", "Clarification answers should become explicit task state, not accidental prompt text that disappears after one model turn." ], "selectionRules": [ "Choose scope clarification when the AI needs a missing boundary before producing a reliable answer, plan, retrieval query, or tool action.", "Use prompt box when the main task is composing the original AI request; use scope clarification after submission when the system detects an important missing boundary.", "Use search scope selector when users are choosing where a search query runs across corpora; use scope clarification when an AI task itself is ambiguous or risky.", "Use agent plan preview when a multi-step plan is ready to inspect; use scope clarification before plan generation when the target, source set, or authority is unclear.", "Use human approval gate when automation is paused at an armed runtime step; use scope clarification before an action is armed or when the user must narrow intent first.", "Use chat interface when the problem is the whole conversation surface; scope clarification is a focused turn or panel inside that conversation.", "Ask one or a small set of clarifying questions only when the answer materially changes result quality, risk, privacy, or action target.", "Provide recognizable options, such as current item, selected items, visible filtered records, entire workspace, last 30 days, this quarter, internal audience, customer audience, cited sources only, or all available sources.", "Let users skip or use a visible default only when the default is low-risk and honestly described.", "Do not answer, plan, retrieve, edit, send, publish, or delete at a broad scope while a consequential scope question is unresolved." ], "requiredStates": [ "Ambiguous request state with original prompt preserved and missing scope named.", "Ambiguous object, audience, timeframe, source set, record set, workspace, permission, output depth, and authority states.", "Clarification question state with bounded choices, custom answer option, recommended default when safe, and cancel path.", "Selected scope state that previews how the answer, plan, retrieval, or tool action will use the scope.", "Skipped clarification or visible default state for low-risk ambiguity.", "High-impact blocked state where the system refuses to proceed until scope is clarified.", "Conflicting scope state where the user request contains incompatible boundaries.", "Permission-limited scope state where some choices are unavailable with explanation.", "Clarification answered, answer resumed, plan regenerated, stale clarification, and change-scope states.", "Mobile compact clarification state with original request, missing boundary, choices, and next step visible." ], "interactionContract": [ "The system identifies what boundary is missing before asking the user to clarify.", "The clarification question references the original request and explains why the answer matters.", "Choosing a clarification updates structured task state such as target objects, timeframe, source set, audience, output depth, or allowed action scope.", "The original request remains visible or recoverable so users can tell what will resume after clarification.", "If a default is used, the UI names the default and lets users change it before high-impact work begins.", "High-risk actions remain blocked until required scope is chosen and permissions are rechecked.", "Clarification answers persist for the current task, plan, answer, or run and are not silently reused across unrelated tasks.", "The UI exposes stale or changed context when a previous clarification no longer applies." ], "implementationChecklist": [ "Model the original request, ambiguity type, missing boundary, candidate scopes, selected scope, default rationale, user answer, confidence, risk level, permissions, stale triggers, and resume target separately.", "Classify ambiguity by object set, timeframe, source set, audience, account, workspace, policy region, output depth, action target, authority, and risk.", "Generate one concise clarification question with bounded choices when the product can enumerate likely scopes.", "Block broad or irreversible actions until target scope, authority, and permissions are explicit.", "Preserve the original request, conversation turn, source context, and pending plan so clarification does not become a new unrelated prompt.", "Show how the chosen scope will affect answer, retrieval, plan, tool call, or output format before continuing.", "Store clarification answers with task or run identity and expire them when the selected object, source, permission, or context changes.", "Test ambiguous pronouns, broad requests, conflicting scopes, permission-limited choices, custom answers, skip defaults, stale clarification, mobile wrapping, keyboard operation, and screen-reader status updates." ], "commonMisuses": [ "Guessing broad scope without revealing the assumption.", "Asking a long questionnaire when one boundary would let the task proceed.", "Using a clarification question to rewrite the user's prompt invisibly.", "Asking for clarification after the system has already acted.", "Forgetting the user's clarification answer in the next response or plan.", "Reusing a scope answer across unrelated tasks without confirmation.", "Showing backend source names or permission IDs as clarification choices." ], "critiqueQuestions": [ "What specific boundary is missing from the user's request?", "Will answering, planning, retrieving, or acting before clarification materially change risk or usefulness?", "Can the product offer bounded scope choices instead of an open-ended question?", "What visible default is safe, and when must the task be blocked until the user chooses?", "Where is the user's clarification answer stored, and when does it expire?", "Would prompt box, search scope selector, agent plan preview, human approval gate, or chat interface better match the actual problem?" ], "relatedPatterns": [ "prompt-box", "search-scope-selector", "agent-plan-preview", "human-approval-gate", "chat-interface", "recommended-next-action", "filter-panel", "confirmation-dialog" ], "comparisons": [ "scope-clarification-vs-prompt-box-vs-search-scope-selector-vs-agent-plan-preview-vs-human-approval-gate-vs-chat-interface" ], "sourceIds": [ "microsoft-human-ai-guidelines", "google-people-ai-guidebook", "openai-conversation-state", "openai-prompt-engineering-guide", "wcag-status-messages" ] }, { "id": "search-history", "completionStatus": "complete", "name": "Search history", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Search activity management surface with deletion and capture controls", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Stored search activity can help recall work and personalize results, but without a clear management surface users cannot see what was saved, where it came from, how long it remains, or how to delete or pause it.", "solution": "Provide a scoped search-history management surface that exposes stored query events, filters them by source and time, lets users delete individual entries or ranges, and separates pausing future capture from deleting existing history.", "uiGuidance": [ "Render search history as a management page or panel with query text, product or source, account/device/workspace scope, timestamp, and clear controls for filtering and deletion.", "Show pause/resume, delete-one, delete-range, and clear-all controls with explicit copy that says whether the action affects search history only, future capture, old entries, saved searches, viewed items, or recommendations." ], "uxGuidance": [ "Use search history when users need to review and control stored search activity across time, products, devices, accounts, or workspaces.", "Treat search history as sensitive activity data: make storage scope, retention, managed-account rules, and deletion consequences explicit before destructive actions." ], "uiExamples": { "good": [ "An account activity page lists Gmail, Drive, and web searches with query text, source, device, time, delete-one controls, product filters, date range, and a pause switch.", "A search history management panel says History is on for this workspace account and Delete last 7 days will remove 14 search events only.", "A YouTube-style history page separates Search history from Watch history and offers pause, clear all, and individual removal." ], "bad": [ "A button labelled Clear history deletes saved searches, viewed records, and recommendations without naming the affected data.", "The history page shows recent, saved, sponsored, and another user's searches in one undated list.", "A pause toggle hides future suggestions but leaves old sensitive queries visible with no explanation." ] }, "uxExamples": { "good": [ "A user filters search history to Drive searches from last week and deletes two entries without deleting saved searches.", "A user pauses future search history capture and sees that old history remains until they delete it.", "A user deletes all account search history and the interface confirms that recent-search shortcuts are cleared while viewed files remain." ], "bad": [ "Users think pausing search history deletes past entries because the interface does not distinguish future capture from stored history.", "A shared kiosk exposes prior user queries because there is no device, account, or session boundary.", "Deleting search history removes named saved searches and saved filters because passive history and intentional saved objects share a destructive action." ] }, "problemContext": [ "Search activity is saved across sessions, products, devices, accounts, workspaces, or managed environments.", "Queries can reveal sensitive work, health, financial, legal, identity, or private intent.", "The product uses search activity for recall, personalization, suggestions, recommendations, analytics, or enterprise productivity." ], "selectionRules": [ "Choose search history when the primary task is reviewing or managing stored query activity, not merely rerunning one recent query.", "Show each history entry as a query event with query text, product or source, timestamp, and account/device/workspace scope.", "Provide delete-one, delete-range, clear-all, pause future capture, and resume capture states where history is persistent.", "Explain that pausing future history capture does not delete existing entries unless the user also deletes them.", "Let users filter by source, product, scope, date range, and optionally device when the history spans multiple surfaces.", "Keep search history deletion separate from saved searches, saved filters, recently viewed items, bookmarks, downloads, recommendations, and underlying results.", "Use recently searched for a short inline recency list near a search box; use search history for the management and privacy surface.", "Use saved search when the user intentionally stores criteria for reuse, sharing, alerting, dashboarding, or subscription.", "Use audit log when the history must be immutable, administrative, actor-oriented, and compliance-grade rather than user-controlled activity data.", "Respect managed-account, legal hold, retention, sync, private browsing, signed-out, and shared-device constraints before promising deletion." ], "requiredStates": [ "Empty history state with storage scope and next steps.", "Populated history state with query, source, timestamp, and scope for each event.", "Filtered state by product, source, date, scope, or device.", "Delete-one state that removes a single search activity entry only.", "Delete-range or clear-all state with confirmation and affected count.", "Paused state where future searches are not stored but previous entries may remain.", "Managed or synced account state explaining retention, administrator, device, or account boundary.", "Error or unavailable state when history cannot be loaded, deleted, or paused." ], "interactionContract": [ "Opening search history shows stored search activity with enough metadata for users to judge sensitivity and scope.", "Deleting one entry removes that history event only and leaves saved searches, viewed items, results, and records intact.", "Deleting a range states the time period, sources, and approximate number of affected entries before confirmation.", "Pausing history affects future capture only and does not imply existing activity has been erased.", "Resuming history makes future capture explicit and should not restore deleted entries.", "Filtering history changes the visible set without changing what will be deleted unless the delete action names the filtered scope.", "History controls must preserve focus, announce deletion and pause outcomes, and avoid hidden hover-only destructive actions." ], "implementationChecklist": [ "Define the data model for search activity events separately from recent searches, saved searches, viewed records, and audit events.", "Capture query text, source product, scope, timestamp, account or device identifier, retention class, and deletion eligibility.", "Add filters for date range, source/product, scope, and device where those dimensions exist.", "Implement delete-one, delete-filtered-range, clear-all, pause capture, and resume capture with explicit affected-data copy.", "Show managed-account, legal hold, retention, sync, and signed-out constraints before promising deletion.", "Keep search-history settings and deletion controls keyboard accessible and announce updates through a polite status region.", "Test sensitive queries, shared devices, account switching, private browsing, offline deletion failure, partial deletion, range deletion, pause/resume, and saved-search separation.", "Log deletion, pause, resume, and failed-history actions without storing the sensitive query text in unnecessary telemetry." ], "commonMisuses": [ "Using search history as a generic label for a short recently searched dropdown.", "Deleting saved searches, viewed records, bookmarks, or filters when the user only chose to delete search history.", "Letting users pause future history but hiding that old entries remain stored.", "Showing another account's or shared device's sensitive queries without a scope label.", "Omitting product, device, or timestamp metadata from account-wide activity.", "Using vague destructive copy such as clear all without naming the data and range.", "Treating search history as an immutable audit log or compliance record.", "Storing or displaying partial keystrokes that were never submitted as search activity." ], "critiqueQuestions": [ "Is this a full management surface or just a short recently searched list?", "Can users tell what account, device, workspace, product, and date each query came from?", "Do delete-one, delete-range, clear-all, pause, and resume actions have different labels and consequences?", "Does pausing history clearly affect only future capture?", "Are saved searches, recently viewed items, and recommendations protected from search-history deletion?", "What retention, managed-account, sync, legal, or shared-device constraints change what deletion means?", "Can users recover from failed deletion or understand partial deletion?" ], "relatedPatterns": [ "recently-searched", "saved-search", "recently-viewed", "basic-search", "search-suggestions", "search-scope-selector", "query-correction", "recommendations" ], "comparisons": [ "search-history-vs-recently-searched-vs-saved-search-vs-recently-viewed" ], "sourceIds": [ "google-account-workspace-search-history", "google-workspace-search-history", "google-search-history-delete", "microsoft-bing-search-history", "youtube-search-history" ] }, { "id": "search-result-highlighting", "completionStatus": "complete", "name": "Search result highlighting", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Highlighted matching terms and snippets inside returned search results", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users can receive plausible search results but still cannot tell where the query matched, which field was relevant, or whether a result deserves attention.", "solution": "Show query-linked highlighted terms inside relevant result fields and snippets, provide enough context and accessible emphasis, and keep the highlights synchronized with the submitted query and backend match data.", "uiGuidance": [ "Render highlighted query matches inside result titles, snippets, or field previews with semantic text markup such as mark and a visible style that does not rely on color alone.", "Pair highlighted fragments with field labels, match counts, result titles, and enough surrounding snippet text that users can understand why the result is present." ], "uxGuidance": [ "Use search result highlighting to explain relevance after a query has returned results, especially when users scan dense documents, records, tickets, messages, or logs.", "Keep the highlight tied to the submitted query and clear or update it whenever the query, scope, filters, or backend highlight response changes." ], "uiExamples": { "good": [ "A result card for Benefits appeal policy highlights Benefits in the title and appeal in the snippet, with a small label saying 2 highlighted fields.", "A document search result shows a compact fragment with ellipses before and after the matching sentence so the highlighted term has readable context.", "A log search page labels matched fields such as title, summary, and body instead of highlighting unknown text blocks with no source field." ], "bad": [ "Every card background turns yellow when a query is submitted, but the matching words are not identified.", "The system highlights a category, ad label, or popularity badge that did not match the query.", "Old highlighted words remain visible after the user clears the query or switches to a zero-result state." ] }, "uxExamples": { "good": [ "A user searches benefits appeal and can immediately see which result matched benefits in the title and appeal in the excerpt.", "A user disables body highlighting to scan title matches only, while the result count and order stay unchanged.", "A user sees a note that semantic highlights are approximate and understands the fragment is an explanation, not a boolean proof." ], "bad": [ "A highlighted synonym looks identical to an exact query match and users assume the document contains words it does not contain.", "A snippet contains only the highlighted word without nearby text, forcing users to open the document to understand relevance.", "Result highlighting is implemented by injecting raw backend HTML into a card, causing unsafe or broken markup." ] }, "problemContext": [ "Search results include long titles, summaries, transcripts, records, documents, tickets, messages, products, logs, or knowledge articles.", "Users need to scan many results quickly and decide which result is worth opening.", "Search logic may match across several fields, synonyms, snippets, or semantic fragments that are not obvious from the result title alone." ], "selectionRules": [ "Choose search result highlighting when returned results need visible evidence of where the submitted query matched.", "Highlight specific terms, phrases, or backend-provided fragments rather than entire result cards.", "Show highlighted snippets only for fields that participated in matching or that the system can explain honestly.", "Use field labels when matches can appear in title, body, metadata, comments, attachments, or hidden indexed fields.", "Show surrounding text and fragment boundaries so a highlighted term has readable context.", "Use mark semantics or equivalent text-level markup for highlighted passages, then style the match with contrast, border, weight, or underline in addition to color.", "Sanitize backend-provided highlight markup or convert it into safe text nodes before rendering result cards.", "Clear stale highlights when users clear the query, change scope, alter filters, or move to a no-results state.", "Explain fuzzy, synonym, semantic, or analyzer-driven highlights when the displayed match is not an exact query-word match.", "Avoid highlighting if the query is empty, sensitive, hidden for privacy, or too broad to produce meaningful match emphasis." ], "requiredStates": [ "No query state with no highlighted terms.", "Submitted query with one or more highlighted result fields.", "Multiple matching fields state with title, snippet, and metadata labels.", "Snippet truncation state with ellipsis or fragment boundaries around removed text.", "No highlighted fragment available state that still explains why the result appears when possible.", "Fuzzy, synonym, or semantic match state with a cue that the highlight may not be an exact word match.", "Updated query state where old highlights are removed before new ones appear.", "No-results state with all previous highlights cleared.", "Unsafe or invalid highlight markup fallback state that renders safe plain text." ], "interactionContract": [ "A highlight represents the submitted query or configured highlight query, not a decorative emphasis chosen independently from search matching.", "Changing the query updates highlighted words, snippets, match counts, and result summaries together.", "Toggling which fields are highlighted changes only the emphasis layer, not the underlying result set or ranking.", "Opening a result preserves the query context or provides a path back to the highlighted result list.", "Highlight styling remains readable in selected, focused, hover, dark, high-contrast, and printed states.", "Screen-reader and keyboard users can understand match location from result text, field labels, counts, and context rather than color alone.", "Backend highlight markup is treated as untrusted content unless it has already been sanitized by the rendering layer.", "If the highlighter is approximate for complex or semantic queries, the UI does not overclaim exact boolean satisfaction." ], "implementationChecklist": [ "Keep a canonical submitted query separate from draft input so highlights match the result set currently shown.", "Tokenize or request highlight fragments from the search service using the same analyzer or highlight configuration as the search query.", "Render matches as safe text nodes and mark elements, or use a trusted highlight component that escapes raw content.", "Include field labels and match counts when more than one result field can contain highlighted fragments.", "Limit snippet length, show ellipses or boundaries, and keep enough surrounding words for comprehension.", "Style mark elements with sufficient contrast and at least one non-color cue such as weight, border, underline, or background shape.", "Test exact, phrase, prefix, fuzzy, synonym, CJK, diacritic, punctuation, and case-insensitive queries against the displayed highlight behavior.", "Remove stale highlight state before showing no-results, error, loading, or empty-query states." ], "commonMisuses": [ "Highlighting whole cards, rows, or table columns instead of the matching terms.", "Using color-only yellow text as the sole signal that a word matched.", "Showing highlights that come from popularity, ads, categories, or business rules instead of the submitted query.", "Injecting backend highlight HTML directly into result cards without sanitization.", "Leaving old highlighted terms visible after the query changed.", "Treating approximate semantic snippets as exact proof that every query condition matched." ], "critiqueQuestions": [ "Can users tell exactly which words, phrases, or fragments caused each result to match?", "Does the highlight map to the submitted query and field labels rather than unrelated metadata or ranking rules?", "Is there enough surrounding snippet text to judge relevance without opening every result?", "Can users distinguish exact, fuzzy, synonym, and semantic highlights when that difference affects trust?", "Does the implementation sanitize backend markup and avoid raw HTML injection?", "Are highlights still understandable without color perception or with assistive technology verbosity disabled?" ], "relatedPatterns": [ "basic-search", "search-suggestions", "autocomplete", "no-results-recovery", "faceted-search", "saved-search", "filter-panel", "sort-controls" ], "comparisons": [ "search-result-highlighting-vs-basic-search-vs-search-suggestions-vs-no-results-recovery" ], "sourceIds": [ "algolia-highlighting-snippeting", "elastic-search-highlighting", "mdn-html-mark-element", "w3c-wcag-use-of-color" ] }, { "id": "search-scope-selector", "completionStatus": "complete", "name": "Search scope selector", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Control that selects which corpus, location, or result source a query searches", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users search the wrong corpus when products have multiple searchable locations, content types, repositories, spaces, conversations, sites, or permission boundaries but the UI hides where the query will run.", "solution": "Provide a visible, labelled scope selector that chooses the searchable corpus, preserves or explicitly clears the query, updates counts and result summaries with each scope, and explains unavailable or permission-limited scopes.", "uiGuidance": [ "Render the active search scope near the search input and result summary, using user-facing corpus names such as Current workspace, All knowledge, This repository, or People.", "Expose scope choices as radios, segmented buttons, a labelled select, or clearly labelled result-source tabs, and show result counts or availability when scope changes affect expected coverage." ], "uxGuidance": [ "Use a search scope selector when the same query can search meaningfully different content sources and users need to control where the system looks.", "Preserve the typed query when scope changes unless the query syntax is incompatible, and explain when a broader or narrower scope is unavailable because of permissions or product rules." ], "uiExamples": { "good": [ "A knowledge search field includes scope buttons for All knowledge, Current workspace, Cases, and People with the active scope repeated above results.", "A repository search box labels the current scope as This repository and offers All repositories without hiding the repo qualifier in placeholder text.", "A site search result page says Results for appeal in Current site and offers Expand to hub or Search organization when those scopes are available." ], "bad": [ "The placeholder says Search this site, but after typing only a generic magnifying glass remains and the result page no longer names the scope.", "The product silently searches the current channel while the user assumes all workspace messages were searched.", "A menu offers index-a, index-b, and tenant without explaining which content each scope contains." ] }, "uxExamples": { "good": [ "A user searches appeal in Current workspace, switches to All knowledge, and sees the same query rerun with a larger result count and broader source summary.", "A user chooses People and the result list changes to people records while the query remains editable and the search input keeps its value.", "A guest user sees Organization unavailable with an explanation instead of a selectable scope that returns empty or unauthorized results." ], "bad": [ "Switching from This repository to All GitHub clears the query and leaves users unsure whether anything ran.", "A Files tab looks selected after the query, but users cannot tell whether future searches will search only files or all content.", "The result summary says All spaces even though filters and breadcrumbs show the search still ran only in the current space." ] }, "problemContext": [ "The product can search across different sites, spaces, repositories, channels, conversations, teams, result types, hubs, tenants, or organization-wide indexes.", "A user's current location creates a useful default scope but may not match the user's intent.", "Broader scopes can expose more results, take longer, change ranking, or be limited by permissions." ], "selectionRules": [ "Choose search scope selector when users need to decide where the search runs before interpreting results.", "Show the active scope before submission when the default could be confused with a broader or narrower corpus.", "Repeat the active scope in the result heading, result count, URL state, or applied criteria summary after submission.", "Preserve the typed query when users switch scope if the query syntax works in the new corpus.", "Reset pagination to the first page when scope changes, because the result set is different even when the query text is the same.", "Use permission-aware scope choices so unavailable broad scopes are disabled with explanations or omitted according to security policy.", "Use user-facing content names rather than backend index, tenant, vertical, or source IDs.", "Distinguish result-type tabs from pre-query search scope when both are present, because switching Messages to Files after search is not always the same as searching only files next time.", "Use filter panel after scope selection when users need attribute constraints within the chosen corpus.", "Use advanced search when users need boolean logic, fielded query syntax, or multiple clauses rather than a small set of named corpora." ], "requiredStates": [ "Default scope state based on current location or product-wide policy.", "Explicitly selected scope state before the query is submitted.", "Submitted query state with scope name and result count.", "Scope changed state where the query is preserved and results rerun.", "Unavailable or permission-limited scope state with explanation.", "No-results-in-this-scope state with path to broaden or change scope.", "Mobile compact state where the active scope remains visible near the search input.", "Deep-linked state where query and scope restore from the URL or saved view.", "Incompatible query syntax state when a qualifier or field only works in one scope." ], "interactionContract": [ "Selecting a scope changes the corpus searched, not merely the visual grouping of existing results.", "The search input, result count, result list, and result summary all update from the same query and scope state.", "Changing scope preserves the current query unless the user confirms clearing it or the query cannot run in the new scope.", "Changing scope resets pagination and clears stale highlights or result selections that belonged to the previous corpus.", "Scope choices remain keyboard reachable and have accessible names that include what content they search.", "Unavailable scopes explain whether the reason is permission, product plan, guest mode, indexing delay, or no content source.", "When a scope is encoded as query syntax, the visible UI still explains it in plain language.", "Deep links, saved searches, and browser history restore both query and scope." ], "implementationChecklist": [ "Define the canonical scope IDs and map each one to a user-facing label, content source, permission rule, and result route.", "Keep query, scope, filters, sort, and result type as separate state so changing one does not silently mutate the others.", "Place the active scope in or next to the search form and repeat it in the result summary.", "Persist scope in URL parameters, route state, or saved search definitions when users need shareable or resumable results.", "Reset pagination and stale selected-result state whenever scope changes.", "Validate whether typed query qualifiers are compatible with the selected scope and offer repair copy when they are not.", "Disable, hide, or explain broad scopes that the current user cannot search.", "Test current-location defaults, broadening actions, mobile presentation, keyboard order, result counts, no-results recovery, and permission-limited users." ], "commonMisuses": [ "Putting scope only in placeholder text, which disappears when users type.", "Using tabs as scope selectors without saying whether future searches will use the selected tab.", "Calling scope choices filters even though they change the corpus before attribute filtering begins.", "Changing scope while leaving the previous result count, highlights, or selected result active.", "Showing broad organization scope to users who cannot search it.", "Using internal source names or index IDs as menu labels." ], "critiqueQuestions": [ "Can users tell where the next search will run before they submit it?", "After results load, does the result summary name both the query and the active scope?", "What happens to query text, pagination, filters, highlights, and selected results when scope changes?", "Are current-location defaults clear enough when users may expect product-wide search?", "Are unavailable broad scopes explained without implying zero results?", "Are result-type tabs, filters, and scope choices visually and semantically distinct?" ], "relatedPatterns": [ "basic-search", "filter-panel", "tabs", "search-result-highlighting", "saved-search", "faceted-search", "no-results-recovery", "sort-controls" ], "comparisons": [ "search-scope-selector-vs-basic-search-vs-filter-panel-vs-tabs" ], "sourceIds": [ "github-repository-search-scope", "slack-search-scope-modifiers", "confluence-cloud-search-scopes", "microsoft-sharepoint-search-box-scope" ] }, { "id": "search-suggestions", "completionStatus": "complete", "name": "Search suggestions", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Suggested-query surface", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need help forming a useful search query before they submit or while they refine it.", "solution": "Show relevant suggested queries or result hints tied to the current input, while preserving user control of the final query.", "uiGuidance": [ "Render a search field with query suggestions, active option, selected suggestion, and no-suggestion state.", "Keep suggestions visually tied to the current input." ], "uxGuidance": [ "Help users formulate better search queries without forcing a choice.", "Preserve free-form typing and avoid submitting suggestions without confirmation." ], "uiExamples": { "good": [ "Suggestions appear directly below the search field with active row, readable labels, and optional matched text.", "Recent, popular, or scoped suggestions are visually distinguished when mixed." ], "bad": [ "Suggestions overlay unrelated content without a dismiss path.", "Promoted results styled the same as typed query suggestions." ] }, "uxExamples": { "good": [ "Users can keep typing, choose a suggestion, dismiss suggestions, or submit their own query.", "Suggestions update with the current input and do not submit until confirmed." ], "bad": [ "Auto-submitting the top suggestion.", "Stale suggestions remain after query changes." ] }, "problemContext": [ "Users may not know the exact wording used by the system.", "The product can produce useful suggestions from content, history, or taxonomy." ], "selectionRules": [ "Choose suggestions when guidance improves query formulation.", "Keep suggestions relevant to the current input and scope.", "Let users ignore suggestions and continue free-form search." ], "requiredStates": [ "No input state.", "Typing state with suggestions.", "Selected suggestion state.", "No suggestion state." ], "interactionContract": [ "Suggestions update from the current input without replacing it unexpectedly.", "Selecting a suggestion makes the resulting query clear.", "Users can dismiss or continue typing." ], "implementationChecklist": [ "Debounce remote suggestions where needed.", "Highlight matching text only when it helps recognition.", "Keep keyboard and pointer selection equivalent.", "Handle stale suggestion responses." ], "commonMisuses": [ "Auto-submitting the top suggestion without confirmation.", "Showing unrelated promoted results as suggestions.", "Overwriting typed text unexpectedly." ], "critiqueQuestions": [ "Do suggestions help users express intent, or are they distracting from the search task?" ], "relatedPatterns": [ "basic-search", "autocomplete", "no-results-recovery" ], "comparisons": [ "search-suggestions-vs-autocomplete" ], "sourceIds": [ "carbon-search-pattern", "wai-aria-apg" ] }, { "id": "security-warning", "completionStatus": "complete", "name": "Security warning", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Security-risk warning and safe interruption before unsafe navigation, download, submission, preview, or sensitive action", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Security warnings fail when they look like ordinary alerts, hide the actual threat, make override too easy, appear after damage is done, or force users to choose without enough destination, evidence, recovery, or reporting context.", "solution": "Intercept the risky step before exposure, state the specific security threat and affected destination or file, make the safe action obvious, require deliberate inspection for override, preserve or discard unsafe task state according to policy, and offer reporting or remediation paths without leaking sensitive data.", "uiGuidance": [ "Render a security warning as a high-clarity interruption that names the detected risk, identifies the destination or object, explains the concrete threat, presents the safest action as the primary path, and separates any override behind deliberate risk detail.", "Use risk-specific labels for phishing, malware, deceptive site, dangerous download, invalid certificate, insecure connection, mixed-content submission, suspicious redirect, file preview blocked, or account-risk states instead of a vague warning banner." ], "uxGuidance": [ "Use security warning when a product, browser, operating system, or service has evidence that proceeding could expose credentials, install harmful software, leak sensitive data, bypass trust, or weaken account protection.", "Help users choose the safe path quickly, make override rare and accountable, preserve task context when returning to safety, and provide report, learn-more, administrator, or site-owner paths without normalizing unsafe continuation." ], "uiExamples": { "good": [ "A browser interstitial says Deceptive site ahead, shows the suspicious domain, explains that attackers may steal passwords, and makes Back to safety the primary action while placing Visit unsafe site behind Details.", "A download shelf says File blocked: malware suspected, names the file, shows the detection source and timestamp, offers Remove file, and routes Keep anyway through a secondary risk detail control." ], "bad": [ "A red page says Security issue with Continue as the only visible action.", "An account app shows a security warning after the user already entered a password into an insecure embedded form." ] }, "uxExamples": { "good": [ "A user clicks a payroll link that visually resembles the company domain, sees the suspicious-domain warning, returns to the trusted site, and reports the link to security.", "A user submits customer data to an HTTP endpoint, sees that the form action is not trustworthy, cancels submission, and keeps the draft intact." ], "bad": [ "A user sees a vague warning, assumes it is routine maintenance, proceeds, and enters credentials into a phishing page.", "A user downloads an unknown installer after the warning hides file reputation, publisher, source URL, and safer alternatives." ] }, "problemContext": [ "The risk may be phishing, social engineering, malware, unwanted software, dangerous download, scareware, invalid certificate, insecure connection, mixed content, unsafe form action, suspicious redirect, file preview risk, compromised site, unknown publisher, or account takeover signal.", "Users may be navigating from email, search, chat, ads, QR codes, embedded links, downloads, file previews, admin consoles, password reset flows, payment forms, or internal tools.", "The product may need different outcomes for block, warn, details, report false positive, report phishing, back to safety, open settings, contact administrator, delete file, keep file, use trusted route, or continue with an audited override.", "Security warnings must be noticeable without becoming habituating; routine warnings, fake security copy, and easy bypasses train users to ignore real risk." ], "selectionRules": [ "Choose security warning when the system has a security-risk signal and proceeding could expose credentials, personal data, payment data, device integrity, account access, or organization assets.", "Use a blocking interstitial when navigation, submission, download, preview, or launch would immediately put the user in a risky context before the normal task can continue.", "Name the risk type in user language: deceptive site, suspected phishing, malware suspected, dangerous download, certificate problem, insecure connection, suspicious redirect, or unsafe form submission.", "Show the destination, file, certificate, publisher, source URL, redirect target, or account event when safe to reveal, and redact sensitive values when the warning itself could leak private information.", "Make the safe action primary, such as Back to safety, Remove download, Cancel submission, Use trusted site, Open settings, Contact admin, or Review activity.", "Place override behind Details, More information, administrator policy, or a secondary action that states the risk; do not present Continue as the default action.", "Use warning text when the issue is a known consequence before a product action rather than a detected active security threat.", "Use alert when a current-task status needs urgent notice but the task can continue safely without a security interstitial.", "Use permission denied state when access is blocked by authorization rather than unsafe trust, malware, phishing, or transport security evidence.", "Use sensitive-data reveal when the main task is controlled exposure of a value already held by the product, not warning about an unsafe destination or object.", "Use site alert when the security message applies across a whole service and does not block one risky navigation, file, form, or action.", "Do not let the warning collect passwords, payment data, recovery codes, or other secrets; route users to a verified destination for remediation." ], "requiredStates": [ "Safe path state with primary Back to safety, Cancel, Remove, Use trusted route, or Contact admin action.", "Detected phishing or deceptive-site state.", "Malware or dangerous-download state.", "Invalid certificate or connection-not-secure state.", "Mixed-content or unsafe form-submission state.", "Suspicious redirect or lookalike-domain state.", "File preview blocked or unknown publisher state.", "Details expanded state with evidence, affected object, and why override is risky.", "Override requested state with deliberate secondary action, policy check, or administrator gate.", "Override blocked by organization policy state.", "False-positive or report-site state that does not require users to visit the unsafe destination.", "Dismissed safe-return state that preserves safe draft context and removes dangerous content from view.", "Mobile compact state where risk, destination, primary safe action, and details remain readable." ], "interactionContract": [ "The warning appears before the risky navigation, submission, download open, file preview, install, or sensitive account action completes.", "The first heading or announcement names the security risk, not only a severity word.", "The safe action is visually and semantically primary, receives the clearest label, and returns users to a safe context without losing recoverable safe work.", "Details disclose evidence such as domain mismatch, certificate problem, file reputation, redirect target, insecure form action, or detection source without exposing raw secrets.", "Override, when allowed, requires an explicit secondary path and may require administrator approval, policy acknowledgement, or audit logging.", "If policy blocks override, the state explains the boundary and provides a support or administrator path instead of a disabled button alone.", "Report false positive, report phishing, and site-owner remediation routes are separated from Visit anyway.", "Security-warning text is not reused for fake urgency, marketing pressure, routine maintenance, validation, or optional consent." ], "implementationChecklist": [ "Classify security warning triggers by threat type, evidence source, confidence, affected object, safe default action, override policy, reporting path, and audit requirement.", "Render risk-specific headings, destination/file identity, consequence copy, primary safe action, details, and any allowed override consistently across web, mobile, and desktop surfaces.", "Use server, browser, operating-system, or security-service verdicts as authoritative signals; avoid client-only cosmetic security warnings for real threats.", "Keep dangerous content, preview, script, download open, form submission, or credential entry blocked until the user chooses a permitted path.", "Log warning shown, safe return, report, override request, override allow or block, policy reason, and affected object without logging secrets.", "Preserve safe drafts and return targets, but clear or quarantine unsafe content according to threat policy.", "Test phishing links, lookalike domains, malware downloads, unknown publishers, invalid certificates, mixed-content submissions, redirects, false-positive reports, admin override policy, mobile wrapping, keyboard access, and screen reader announcement." ], "commonMisuses": [ "Using vague warning copy that does not say phishing, malware, certificate, insecure connection, dangerous download, or suspicious redirect.", "Making Continue the primary or only visible action.", "Showing the warning after credential entry, file execution, form submission, or preview rendering already happened.", "Hiding destination, file, publisher, redirect, or evidence details that users need to make a safe choice.", "Using fake security urgency to pressure consent, upgrade, payment, or marketing decisions.", "Letting every low-risk informational notice use the same severe security-warning treatment.", "Logging raw passwords, tokens, payment data, or private file contents while producing the warning." ], "critiqueQuestions": [ "What concrete security signal caused this warning, and how fresh is it?", "What exact navigation, download, submission, preview, install, or account action is being stopped?", "Can the user identify the unsafe destination or object without exposing private information?", "Is the safe action clearly primary, and does it preserve safe task context?", "Is any override necessary, policy-allowed, deliberate, and auditable?", "Does the warning offer a false-positive, report, administrator, or site-owner remediation path?", "Could this warning train users to ignore real security risk because it is overused or vague?" ], "relatedPatterns": [ "warning-text", "alert", "site-alert", "permission-denied-state", "sensitive-data-reveal", "session-timeout-warning", "confirmation-dialog", "toast-only-critical-error", "error-state" ], "comparisons": [ "security-warning-vs-warning-text-vs-alert-vs-permission-denied-state-vs-sensitive-data-reveal" ], "sourceIds": [ "google-safe-browsing-overview", "google-chrome-unsafe-site-warnings", "microsoft-defender-smartscreen-overview", "microsoft-edge-smartscreen-unexpected-warning", "w3c-mixed-content", "microsoft-file-preview-security" ] }, { "id": "segmented-control", "completionStatus": "complete", "name": "Segmented control", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Compact mode selector", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to switch between a small set of mutually exclusive modes, filters, or views in a compact area.", "solution": "Present adjacent options as a single control with one active segment and immediate local effect.", "uiGuidance": [ "Render a compact horizontal group with two to four adjacent segments, one selected state, visible focus, and stable sizing.", "Keep labels concise, avoid mixed icon/text rhythm, and place the changed local content directly below or beside the control." ], "uxGuidance": [ "Help users switch a local mode, view, filter, sort, or presentation immediately without navigation or form submission.", "Avoid using segments for unrelated pages, hidden content sections, destructive actions, or choices that need long explanation." ], "uiExamples": { "good": [ "Two to four adjacent segments with a clear selected segment, visible focus ring, and readable labels that fit on one row.", "The affected list, chart, or view sits immediately next to the control and visibly changes." ], "bad": [ "Many cramped segments with truncated text.", "Icon-only segments whose meaning changes by context or a group that wraps into multiple rows." ] }, "uxExamples": { "good": [ "Selecting a segment changes a nearby local mode, filter, or view immediately.", "Exactly one segment is active and the previous selection is automatically deselected." ], "bad": [ "Using segments for unrelated destinations.", "Changing distant content without indicating what changed or using a segment to execute an action." ] }, "problemContext": [ "The options alter a local view or setting rather than navigate to separate content sections.", "The choice set is short and benefits from persistent visibility.", "The affected data or view is close enough that users can immediately understand what changed." ], "selectionRules": [ "Choose segmented controls for two to four closely related local modes, filters, sort orders, or view presentations.", "Keep labels concise, preferably one word, because the group should not wrap or become a scrolling navigation strip.", "Use tabs when each option exposes a distinct content panel or section.", "Use radio groups when users need fuller option descriptions, validation, or a form answer instead of an immediate local view change.", "Use pagination when the choices represent position in one ordered result set." ], "requiredStates": [ "Default selected segment.", "Unselected segment state.", "Focused segment state.", "Changed local view state.", "Disabled or rejected overflow state when too many options are proposed." ], "interactionContract": [ "Selecting a segment updates the local mode or filter immediately.", "Exactly one segment is active unless the control is explicitly multi-select.", "The active segment is visually and programmatically clear.", "The affected content sits adjacent to the control and updates without page navigation.", "Keyboard users can move between segments and select a segment without losing context." ], "implementationChecklist": [ "Name the group when the meaning is not obvious.", "Expose selected or pressed state for each segment.", "Keep the affected content adjacent.", "Avoid wrapping segments unpredictably.", "Reject or redesign sets that need more than four or five compact labels.", "Avoid mixing icon-only and text segments unless the meaning remains obvious." ], "commonMisuses": [ "Using segments for unrelated page navigation.", "Packing too many options into a tiny control.", "Using icons without labels for ambiguous modes.", "Using a segmented control to initiate actions such as add, edit, or delete." ], "critiqueQuestions": [ "Is this a compact local mode choice rather than page structure?", "Can users see the affected content change immediately after selecting a segment?" ], "relatedPatterns": [ "tabs", "radio-group" ], "comparisons": [ "tabs-vs-segmented-control-vs-pagination" ], "sourceIds": [ "va-segmented-button", "android-segmented-button", "fluent-ios-segmented-control" ] }, { "id": "select", "completionStatus": "complete", "name": "Select", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Single-choice dropdown control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to choose one value from a known list that is too long or secondary to keep fully expanded on the page.", "solution": "Use a native select with a persistent label, optional hint, visible closed value, an empty option only for no selection, and validation that does not auto-submit on change.", "uiGuidance": [ "Render a persistent label, hint text, native closed value, finite option list, selected option, and validation state.", "Prefer native select unless custom listbox behavior is truly needed and fully accessible." ], "uxGuidance": [ "Help users choose one value from a moderate known list without showing every option permanently.", "Do not hide short critical choices just to save space, and do not auto-submit while users navigate options." ], "uiExamples": { "good": [ "Persistent label, hint text, visible selected value, readable options, and clear required validation state.", "Native select is used when custom presentation is not necessary." ], "bad": [ "Placeholder as the only label.", "Custom dropdown that looks polished but hides focus and selected state." ] }, "uxExamples": { "good": [ "Users can open, scan, choose one value, and review the selected value after close.", "Very long lists use search or autocomplete instead of forcing scrolling." ], "bad": [ "Hiding two obvious critical choices in a dropdown.", "Option labels are ambiguous or duplicated without context." ] }, "problemContext": [ "The option set is known, finite, and moderately sized.", "A compact control is justified because visible comparison of every option is less important than saving space." ], "selectionRules": [ "Choose select sparingly for a single choice from a moderate known list when space or task priority justifies collapsing options.", "Prefer radio groups for fewer visible choices when comparison or consequence matters.", "Use autocomplete or combo box behavior when the list is very long, searchable, or hard to scan manually.", "Do not submit or navigate automatically when the selected option changes." ], "requiredStates": [ "Closed state with empty option or current selected value.", "Open native option menu or equivalent listbox state.", "Selected option state after the menu closes.", "Required validation error state when no valid option is chosen." ], "interactionContract": [ "The selected value remains visible after the menu closes.", "Opening the control reveals the finite options without accepting arbitrary free text.", "Changing selection updates local state without automatically submitting the form.", "A required empty option is not treated as a completed answer." ], "implementationChecklist": [ "Use native select when platform behavior satisfies the design.", "Label the control clearly and keep the label visible after a value is selected.", "Include an empty option only for the no-selection state and validate it as incomplete when required.", "Provide hint or error text through descriptive associations when needed.", "Avoid custom selects unless keyboard, focus, selected state, dismissal, and assistive behavior match the native control." ], "commonMisuses": [ "Custom select with no keyboard support or hidden selected state.", "Using select to hide two or three obvious choices that should be compared.", "Placeholder-only labels that disappear after selection.", "Auto-submitting the form as soon as a user arrows through options." ], "critiqueQuestions": [ "Is collapsing this choice worth the extra interaction cost?", "Would a visible radio group or searchable autocomplete make this list easier to complete?" ], "relatedPatterns": [ "radio-group", "autocomplete" ], "comparisons": [ "radio-group-vs-select" ], "sourceIds": [ "govuk-select-component", "uswds-select-component", "wai-aria-apg-listbox" ] }, { "id": "sensitive-data-reveal", "completionStatus": "complete", "name": "Sensitive-data reveal", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Controlled reveal and re-hiding of masked sensitive values, secrets, tokens, credentials, identifiers, or private records", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Products often need to let users inspect or transfer sensitive values, but uncontrolled reveal exposes secrets to shoulder surfing, screenshots, logs, clipboard leakage, support tools, or accidental persistence.", "solution": "Provide a controlled reveal surface that starts masked, names the sensitive field, gates high-risk access, reveals only the minimum needed scope, gives an immediate hide path, manages copy and timeout behavior, announces state changes, and records auditable access without storing or emitting the raw value in unsafe places.", "uiGuidance": [ "Render sensitive-data reveal as a masked value with an explicit reveal action, visible hide action, clear field identity, safe default state, reveal duration or hold behavior, and status feedback that explains what is visible now.", "Use partial reveal, hold-to-reveal, timed reveal, reauthentication, clipboard warnings, and audit events according to the sensitivity and consequence of the value." ], "uxGuidance": [ "Use sensitive-data reveal when users need to verify, compare, copy, rotate, recover, or transcribe a sensitive value that is normally masked or redacted.", "Keep the user in control of when the value appears, make hiding easy, avoid accidental reveal on focus or hover, and never leak the raw value into logs, URLs, analytics, screenshots, or unrelated UI." ], "uiExamples": { "good": [ "An API key row shows sk_live_****9H2Q by default, requires Reauthenticate before Full reveal, logs the reveal event, and automatically hides after 30 seconds.", "A bank-account review shows only the last 4 digits until the user chooses Reveal full account number, then offers Hide now and warns before copying to clipboard." ], "bad": [ "A dashboard shows API keys in plain text by default and copies them to clipboard without warning or audit.", "A password field reveals after focus leaves the field and has no hide action, so the secret stays visible while the user moves through the form." ] }, "uxExamples": { "good": [ "A developer needs to rotate a webhook secret, reveals it after step-up verification, copies it with a visible clipboard warning, then sees it auto-hide with an audit ID.", "A support agent can partially reveal a customer's phone number for verification but cannot reveal the full tax ID because policy allows only the last four digits." ], "bad": [ "A user opens billing details in a shared office and the full card number appears automatically with no warning.", "A user taps a copied state and the interface silently places a raw token on the clipboard while the token remains hidden on screen." ] }, "problemContext": [ "The value may be a password, API key, token, recovery code, secret variable, certificate, bank account, card number, tax identifier, health identifier, email, phone number, address, or private record excerpt.", "The user may need to check a typed value, compare a stored value, copy a generated secret, verify identity, transcribe a code, rotate a credential, or confirm a financial identifier.", "The surface may need different policies for partial reveal, full reveal, one-character peek, hold-to-reveal, timed reveal, reauthentication, admin approval, audit logging, copy restrictions, and permanent redaction.", "The design must balance entry accuracy and accessibility with the risk of nearby observers, shared screens, screenshots, clipboard history, browser autofill, and telemetry leaks." ], "selectionRules": [ "Choose sensitive-data reveal when a normally masked or redacted value needs a deliberate temporary reveal, hide, peek, copy, partial reveal, reauthentication, or audited access path.", "Use password input when the main task is entering a memorized secret into an authentication form rather than revealing a stored or generated sensitive value.", "Use input mask when the goal is entry formatting for a stable structured value, not privacy masking or secure reveal control.", "Use typed confirmation when users type a visible target phrase to confirm a destructive action; do not mask that phrase as if it were a secret.", "Use permission request when the user grants OS or browser access to a device resource rather than showing an already-held sensitive value.", "Use warning text when the main need is consequence warning before an action, not controlled exposure of a sensitive field.", "Use permission denied state when policy prevents reveal or only allows partial reveal; explain the boundary without leaking the restricted value.", "Use partial reveal for verification tasks where the last four characters, domain, issuer, or masked suffix is enough.", "Use reauthentication, step-up verification, or admin review before full reveal of high-risk secrets such as API keys, recovery codes, financial identifiers, or customer data.", "Do not reveal on page load, hover, focus, validation, copied state, print view, export, analytics event, URL, or console log." ], "requiredStates": [ "Masked state with the field identity, safe suffix or count, and reveal eligibility.", "Reveal action state with an explicit button or toggle that names what will become visible.", "Hide action state while the value is visible.", "Hold-to-reveal or peek state for short-lived inspection.", "Timed reveal state with countdown and automatic re-mask.", "Reauthentication or step-up required state before high-risk full reveal.", "Partial reveal state for last four, prefix plus suffix, or policy-limited values.", "Full reveal state when policy permits complete value display.", "Copy while hidden state with a clear clipboard warning and copied status.", "Clipboard warning state for values that may remain in clipboard history.", "Audit event state showing reveal actor, time, reason, and access ID without raw value.", "Redaction boundary state when the user can never reveal the full value.", "Shoulder-surfing warning or shared-screen state before high-risk reveal.", "Expired reveal state after timeout, blur, navigation, or focus loss.", "Screen reader announcement state for shown, hidden, copied, expired, and denied reveal outcomes.", "Mobile compact state where masked value, reveal, hide, copy, timeout, and policy status remain readable." ], "interactionContract": [ "The value is masked by default unless the user is actively entering it and the platform-specific control intentionally permits display.", "Reveal requires a deliberate keyboard- and pointer-accessible action that names the target value and does not sit so close to unrelated controls that accidental reveal is likely.", "Visible values have an equally reachable hide action and may auto-hide after timeout, blur, navigation, screen lock, or policy-triggered expiry.", "High-risk values require step-up verification, role check, reason capture, approval, or audit recording before full reveal.", "Copy actions work from masked or revealed state only when allowed, warn about clipboard exposure, and confirm copy without showing the raw value in status text.", "Partial reveal and redaction boundaries are enforced by the data returned to the client, not only by CSS or text decoration.", "Logs, analytics, DOM labels, URLs, screenshots, exports, error messages, and support metadata do not contain the raw value unless explicitly designed as a protected evidence export.", "Assistive technology receives accurate state announcements without reading a secret aloud unexpectedly." ], "implementationChecklist": [ "Classify sensitive fields by value type, reveal scope, allowed roles, reauthentication needs, copy policy, audit requirements, timeout, and redaction boundary.", "Fetch only the minimum value needed for the current reveal state; avoid sending full raw values to the browser when policy allows only partial reveal.", "Implement masked, partial, full, hold, timed, copied, expired, denied, policy-limited, and audit-recorded states with explicit state transitions.", "Keep reveal and hide controls keyboard accessible, labelled by the specific field, and separated from adjacent destructive or navigation controls.", "Disable automatic reveal on focus, hover, validation, print, export, preview, screen share, or copied state unless the user explicitly requested it.", "Scrub raw values from telemetry, console logs, error messages, URLs, browser history, client storage, and test snapshots.", "Test shoulder surfing, mobile tap targets, screen readers, copy clipboard behavior, reauthentication failure, audit recording, timeout, focus loss, print/export, and restricted-role redaction." ], "commonMisuses": [ "Showing sensitive values in plain text by default.", "Revealing values on hover, focus, validation error, print preview, copied status, or after blur.", "Providing a reveal action without a hide action.", "Copying a hidden secret to the clipboard without warning or status.", "Logging raw secrets in analytics, console output, support tickets, screenshots, or audit records.", "Masking with CSS while the full value remains exposed in DOM text to unauthorized users.", "Using one broad Show all control for unrelated secrets with different policies." ], "critiqueQuestions": [ "What exact sensitive value is masked, and why does this user need to reveal it?", "Is partial reveal enough for this task?", "What policy, role, reauthentication, reason, or audit event is required before full reveal?", "How does the user hide the value immediately, and when does it auto-hide?", "What happens if the user copies while hidden or while visible?", "Can screen readers announce the state without unexpectedly reading the secret?", "Where could the raw value leak through DOM text, logs, URLs, analytics, screenshots, exports, or clipboard history?" ], "relatedPatterns": [ "password-input", "input-mask", "typed-confirmation", "permission-request", "permission-denied-state", "warning-text", "bank-details", "payment-card-entry", "two-factor-authentication", "review-before-submit", "inline-message" ], "comparisons": [ "sensitive-data-reveal-vs-password-input-vs-input-mask-vs-typed-confirmation-vs-permission-request" ], "sourceIds": [ "nist-sp-800-63b-passwords", "microsoft-edge-password-reveal", "microsoft-windows-password-box", "hashicorp-helios-masked-input", "owasp-mastg-sensitive-data-disclosure-ui" ] }, { "id": "service-navigation", "completionStatus": "complete", "name": "Service navigation", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Service-scoped identity and navigation strip", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users in a named service need to recognize the service they are using and move among its top-level service areas without confusing service-level movement with GOV.UK-wide, product-wide, local, or page-specific navigation.", "solution": "Provide a service navigation strip that shows the service name, links the name to the service home, exposes only the most important service-level destinations and tools, marks the current section, and sits below any general site or platform header.", "uiGuidance": [ "Render the service name, service-home link, a compact set of service-level links, current or active service state, and any service-level tools in a navigation strip below the general site or platform header.", "Keep GOV.UK-wide, product-wide, account-wide, and page-specific elements visually and semantically separate from the service navigation surface." ], "uxGuidance": [ "Use service navigation to reassure users that they are inside the right service and to let repeated or multi-task users move among the most important service areas.", "Avoid adding service navigation to a simple ordered transaction; simplify the journey or use a task list when users need to complete steps in a known order." ], "uiExamples": { "good": [ "A benefits service shows the GOV.UK header above a light service strip with 'Apply for support', Overview, Applications, Messages, and a Welsh language link.", "The service name links to the service home, the current service section is marked with text and semantic state, and GOV.UK-wide sign-in remains in the GOV.UK header.", "On a narrow screen, the same service links move under a Menu button while the service name remains visible." ], "bad": [ "The service strip mixes GOV.UK topics, start-page links, sign out, Help, local page anchors, and admin tools as equal destinations.", "The active service link says Messages while the main heading still shows Applications.", "The service name is hidden in a general product header, so deep-linked users cannot tell which service they are using." ] }, "uxExamples": { "good": [ "A caseworker switches from Applications to Messages and returns to Applications with draft progress and filters preserved.", "An applicant lands from an email link and immediately sees the service name, current section, and language selector before page-specific content.", "External guidance links are grouped after service links or placed in the page body with a warning when they leave the service." ], "bad": [ "A linear eligibility check exposes service navigation that invites users to leave before completing the required questions.", "Clicking a service-level tool changes the highlighted service section while content remains on the previous task.", "A GOV.UK topic menu appears inside the service header and sends users away from the service journey." ] }, "problemContext": [ "A service is used repeatedly or supports several tasks that do not follow one fixed order.", "Users can enter the service from email, search, or saved links and need reassurance that they are in the right service.", "The page also has general header controls, account or login tools, local side navigation, breadcrumbs, or page-specific actions that must not be confused with service-level navigation." ], "selectionRules": [ "Choose service navigation when one named service needs persistent identity and a small set of service-level destinations across multiple pages.", "Show the service name in the service navigation and link it to the service home, GOV.UK start page, or first question when no service home exists.", "Keep navigation links to the most important top-level service sections that help users understand what the service contains and where they can go next.", "Place GOV.UK-wide or platform-wide tools in the general header, then service-wide tools in service navigation, then page-specific elements near the main content.", "Group external links after in-service links, warn when they open a new window when possible, or put them in the page body instead.", "Avoid service navigation for a single end-to-end transaction with a clear task order; use a task list, step navigation, or page-level links instead.", "Use side navigation or in-page anchors when users need hierarchy within one service area rather than top-level movement around the whole service." ], "requiredStates": [ "Default state with general header, visible service name, service-home link, and service navigation links.", "Current page or current section state that matches the main heading and route.", "Active group state for a service area when a child page belongs under that service link.", "Mobile collapsed state with a Menu button connected to the service link list.", "Service-level tool state for language, search-within-service, account, or contact controls placed after the service name.", "External-link state where links leaving the service are grouped, warned, or moved into page content." ], "interactionContract": [ "Activating a service navigation link changes to the named service section and updates current or active service state.", "The service name link returns to the service home, GOV.UK start page, or first service question according to the service's information architecture.", "General site or platform controls do not change the highlighted service section unless they navigate to an actual service section.", "The mobile Menu button exposes the same service links, announces expanded state, and can be dismissed without losing page state.", "Service-level tools such as language selection or service search remain scoped to the service and do not appear as peer sections unless they are true destinations.", "Switching service sections preserves drafts, filters, and case context where possible or warns before losing progress." ], "implementationChecklist": [ "Define the service name and canonical service-home destination before adding navigation links.", "Choose service links from repeated user tasks and top-level service sections, not from the full route table or organization chart.", "Render the general header first, service navigation second, service-level messages or phase banners next, and page-specific navigation near the main content.", "Mark current and active service states from route data and verify that they match the page heading.", "Separate GOV.UK-wide, product-wide, account-wide, and service-wide tools by scope and position.", "Design mobile collapse so the Menu control exposes the same service links and returns focus predictably.", "Review external links and decide whether they belong grouped after service links or inside page content." ], "commonMisuses": [ "Using service navigation as a site map for every page in the service.", "Putting GOV.UK topic menus, whole-product destinations, sign-out, and local page anchors into one service link row.", "Showing a current service link that does not match the content heading.", "Hiding the service name on deep-linked pages.", "Adding service navigation to a short linear transaction where users should complete steps in order.", "Letting mobile service navigation expose fewer links or different labels than desktop." ], "critiqueQuestions": [ "Can a deep-linked user identify the service name before reading the page heading?", "Are these links the most important top-level service areas, or a complete list of routes?", "Which controls are GOV.UK-wide, service-wide, local to one section, or page-specific?", "Would a task list or step indicator better support this journey because the tasks have a clear order?", "What happens to a draft, selected case, or filter when the user switches service sections?" ], "relatedPatterns": [ "global-navigation", "side-navigation", "header", "breadcrumbs" ], "comparisons": [ "service-navigation-vs-global-navigation-vs-side-navigation" ], "sourceIds": [ "govuk-service-navigation-component", "govuk-navigate-service", "govuk-header-component" ] }, { "id": "service-unavailable-page", "completionStatus": "complete", "name": "Service unavailable page", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Whole-service unavailable page", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users lose time, trust, saved work, or deadline paths when a whole service is unavailable but the page hides scope, duration, work-safety, alternate channels, and whether retrying is useful.", "solution": "Show a durable service unavailable page that identifies the affected service, explains planned or unexpected unavailability, gives recovery timing or update cadence, states saved-work impact, provides alternate or urgent routes, and avoids implying active progress when the service is closed.", "uiGuidance": [ "Render a full page with the service name, unavailable scope, status, return time or update promise, saved-work status, alternate route, support contact, and request or incident reference when available.", "Use plain page content rather than spinners, progress bars, modal dialogs, or stacked alerts when the service entry point itself cannot be used." ], "uxGuidance": [ "Use a service unavailable page when the service, transaction, or route is intentionally closed, under maintenance, overloaded, permanently closed, or unable to handle requests at the entry point.", "Tell users what happened, what they can still do, what happens to their work, when to come back, and how to handle urgent or time-sensitive tasks." ], "uiExamples": { "good": [ "A benefits application page says the service is unavailable from 22:00 to 01:00, names the affected transaction, says saved drafts remain for 30 days, and links to urgent phone support.", "A 503 page says account payments cannot be submitted right now, gives a retry-after time, request ID, status page link, and contact path for payment deadlines.", "A closed legacy service page explains that the old report submission service has closed permanently and links to the replacement service and support contact." ], "bad": [ "A blank white page with only 503 in the browser title.", "A full-page spinner implies progress even though the service has been deliberately closed for maintenance.", "A service outage page says Try again later but does not say whether answers were saved or how urgent users can complete the task." ] }, "uxExamples": { "good": [ "A user returns during planned maintenance, sees a precise reopening time, learns their draft is saved, and uses an alternate phone channel for an urgent deadline.", "A user hits overload on tax filing day, sees a request ID and status update link, waits until the retry-after window, then re-enters without duplicate payment risk.", "A user follows an old transaction link, learns the service closed permanently, and moves to the replacement route instead of contacting support blindly." ], "bad": [ "Users repeatedly refresh because the page gives no recovery window or status update path.", "Users restart a long application because the page does not say whether answers were saved.", "Users miss a deadline because urgent offline support is omitted from the outage page." ] }, "problemContext": [ "The service has scheduled maintenance, emergency shutdown, traffic overload, deployment, dependency outage, permanent closure, or an entry route that cannot handle requests.", "Users may arrive from bookmarks, notifications, search results, saved tasks, payment links, or forms already in progress.", "The unavailable state may affect the whole service, one transaction, one region, one identity provider, one payment route, or a permanent legacy endpoint.", "The product needs to coordinate HTTP status, service page copy, incident communication, saved drafts, support channels, and cache behavior." ], "selectionRules": [ "Choose service unavailable page when the user cannot proceed because the service entry point, transaction, or route is closed or server-side capacity is unavailable.", "Use planned-outage copy when the closure is scheduled and the return time, start time, or window is known.", "Use unexpected-outage copy when the service is failing now; include request ID, status page, support route, and update cadence when available.", "State saved-work impact: saved answers, unsaved answers, draft retention, duplicate-submission safety, payment status, or start-again requirement.", "Give urgent alternatives for benefits, health, payments, legal duties, statutory reporting, travel, identity, or deadline-sensitive tasks.", "Use permanent-closure copy when a service is retired; link to replacement service, archived guidance, phone route, or contact path.", "Use error state when only a component, query, upload, or save failed while the surrounding service remains usable.", "Use offline state when the user's connection is the primary problem and local cached work or reconnect behavior is available.", "Use site alert or banner to announce upcoming or partial outages while users can still navigate or complete allowed tasks.", "Avoid automatic refresh loops unless they are rate-limited, announced, and do not duplicate submissions or obscure the recovery time." ], "requiredStates": [ "Planned maintenance page with start or return time.", "Unexpected outage page with status update or request ID.", "Overload page with retry-after guidance.", "Saved draft state that says answers are retained and for how long.", "Unsaved work state that says users must start again.", "Partial outage state that says which task is unavailable and which tasks still work.", "Urgent alternate channel state.", "Permanent closure or replacement-service state.", "Status-page or incident-update link state.", "Post-recovery handoff state that avoids duplicate submission." ], "interactionContract": [ "The page replaces the affected service route until the service can safely handle requests again.", "The HTTP response, cache headers, page title, visible heading, and user copy agree that the condition is temporary or permanently closed.", "Users can reach support, status updates, allowed alternate services, or a safe exit without returning through broken navigation.", "Retry and refresh actions are labeled according to safety: reload page, check status, continue saved draft, start again, or contact support.", "If the unavailable state interrupts a transaction, the page states whether answers, payment, upload, booking, or submission state was preserved." ], "implementationChecklist": [ "Route planned maintenance, overload, unexpected incident, permanent closure, and partial dependency failures to distinct copy variants.", "Set the correct server status for temporary unavailability and configure Retry-After or equivalent recovery timing where possible.", "Prevent caching of temporary outage pages in ways that keep users on stale unavailable content after recovery.", "Include service identity, incident or request ID, support link, status page, saved-work status, and last-updated time when available.", "Provide operational controls to update return time, maintenance window, support contact, replacement service, and saved-work copy without redeploying the application.", "Test bookmarks, deep links, form-in-progress sessions, payment retries, duplicate submissions, mobile widths, screen readers, and post-recovery transitions." ], "commonMisuses": [ "Using a full-page spinner for a closed service.", "Showing only 503 or Something went wrong without service scope, return time, or support route.", "Sending users to a homepage with no explanation of the outage.", "Promising saved work without checking transaction state.", "Telling users to retry immediately when the service is deliberately closed.", "Using a site alert after the affected transaction can no longer be used." ], "critiqueQuestions": [ "Which service, route, or transaction is unavailable?", "Is the outage planned, unexpected, partial, overloaded, or permanent?", "When should users come back, or when will the next update be posted?", "What happened to in-progress answers, payments, uploads, or bookings?", "What urgent or offline route exists for users with deadlines?", "Does retrying create duplicate submissions, payments, or support tickets?" ], "relatedPatterns": [ "error-state", "offline-state", "site-alert", "banner", "notification-banner", "progress-bar", "loading-spinner", "permission-denied-state" ], "comparisons": [ "service-unavailable-page-vs-error-state-vs-offline-state-vs-site-alert" ], "sourceIds": [ "govuk-service-unavailable-pages", "mdn-http-503-service-unavailable", "ons-error-status-pages", "moj-outage-banner" ] }, { "id": "session-timeout", "completionStatus": "complete", "name": "Session timeout", "category": "Trust, Safety, And Privacy", "patternType": "ui-ux", "surfaceType": "Expired authenticated-session state and safe return-to-task recovery", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "After a session expires, products often leak private content, preserve stale authenticated controls, mislabel the state as permission or network failure, lose return context, or force users to restart work that could have been preserved safely.", "solution": "Terminate authenticated interaction, hide sensitive content, explain that the session ended, show only safe recovery evidence, preserve allowed draft or return references, route through sign-in or reauthentication, and restore the intended task only after the new session is confirmed.", "uiGuidance": [ "Show session timeout after the authenticated session has ended, with private content hidden, a clear reason such as inactivity or policy expiry, the last safe activity reference, and a primary sign-in or reauthentication path.", "Separate recoverable task context from protected values: show safe identifiers, saved-draft status, return destination, and support reference without displaying private fields, tokens, account data, or stale authenticated controls." ], "uxGuidance": [ "Use session timeout when the session is no longer valid and the product must protect privacy while helping the user recover safely through sign-in, reauthentication, return-to-task restoration, or a saved-draft route.", "Treat the timeout state as a security and continuity boundary: terminate authenticated actions, hide sensitive content, preserve allowed work references, and return users only after a fresh session is established." ], "uiExamples": { "good": [ "A benefits form replaces private answers with Session ended after inactivity, shows reference SES-2048, says the draft was saved at 10:42, and offers Sign in to continue plus Start again.", "A banking dashboard hides account balances after timeout, names the signed-out reason, clears action buttons, and returns to the transfer review only after reauthentication." ], "bad": [ "A modal says Timeout while the private page remains readable behind it.", "The app shows Access denied with Retry, causing users to retry expired requests instead of signing in again." ] }, "uxExamples": { "good": [ "A user returns from a break, sees that their session ended, signs in again, and lands back on the same saved claim step with private fields restored only after authentication.", "A shared-device user times out; the product hides the case details, clears unsafe actions, and leaves only a safe reference and sign-in route." ], "bad": [ "A user comes back to a timed-out payment form, clicks Submit, and gets repeated server errors because expired controls stayed enabled.", "A user signs in again after timeout and is dumped on a dashboard with no saved-task reference or way back to the interrupted work." ] }, "problemContext": [ "The user had an authenticated session that has already ended because of inactivity, absolute lifetime, logout, reauthentication policy, identity-provider termination, risk event, or session revocation.", "The current surface may contain private records, form answers, payments, admin actions, files, health data, financial data, or sensitive account state.", "The product may be able to preserve a server-side draft, return URL, record reference, transaction reference, or local non-sensitive recovery note without keeping the expired session active.", "The product must prevent stale submissions, stale downloads, stale previews, and privacy leaks while still making recovery understandable." ], "selectionRules": [ "Choose session timeout when the authenticated session has already expired or been terminated and the next valid path is sign-in, reauthentication, restart, or safe task restoration.", "Use session timeout warning before expiry when users can still extend, save, sign out, or reauthenticate before the boundary is crossed.", "Use sign in when the user begins unauthenticated access normally; use session timeout when an existing authenticated task was interrupted and needs a return target or saved-state explanation.", "Use login for the credential-verification attempt and its outcomes; session timeout owns the expired-session screen before and after that attempt.", "Use permission denied state only when the user is authenticated but lacks authorization; do not send expired sessions into request-access flows.", "Use autosave recovery when the main issue is preserving failed or local-only work; session timeout may link to that recovery after reauthentication.", "Hide private content, field values, thumbnails, account balances, comments, files, and action controls until the user reauthenticates.", "Show safe context such as record type, masked account, draft timestamp, reference ID, or return destination when policy allows it.", "Disable or remove stale authenticated controls; do not let Submit, Export, Delete, Approve, Download, or Pay fire against an expired session.", "After successful reauthentication, restore the intended route, step, scroll position, focus target, and recoverable draft where policy permits." ], "requiredStates": [ "Expired session state with private content hidden.", "Inactivity timeout state with safe timestamp or duration explanation.", "Absolute timeout or policy timeout state that requires reauthentication.", "Signed-out recovery state with preserved return destination.", "Saved draft available after timeout state.", "No recoverable work state with honest restart path.", "Reauthentication in progress state that does not reveal private data.", "Reauthentication failed or canceled state that keeps the user signed out.", "Restored task state after successful sign-in.", "Multiple-tab or identity-provider timeout state where another session ended independently." ], "interactionContract": [ "The timeout state is driven by server or identity-provider session validity, not by a cosmetic client-only overlay.", "When session validity fails, authenticated actions are stopped before they submit, download, export, preview, delete, approve, or mutate data.", "Private content is hidden or cleared while preserving only safe recovery metadata such as reference, route, saved timestamp, or masked object name.", "Sign in or reauthenticate creates a fresh session and validates whether the return target is still allowed before restoring content.", "Canceled or failed reauthentication leaves the user in a signed-out state with safe navigation, restart, or support routes.", "Return restoration distinguishes server-saved work, local-only work, unrecoverable work, and policy-cleared work.", "The page does not call the expired state permission denied, network error, not found, or service unavailable." ], "implementationChecklist": [ "Model expired authentication separately from unauthenticated first visit, authorization denial, network failure, and validation failure.", "Store a safe return target, task reference, draft reference, and last confirmed save timestamp outside the expired session where policy allows.", "Clear or hide sensitive DOM content, cached previews, media, inline files, and filled secret fields when session expiration is detected.", "Intercept stale authenticated controls and redirect them to the timeout state instead of letting them retry with expired credentials.", "Validate return targets after reauthentication to avoid open redirects, stale permissions, deleted objects, or cross-account restoration.", "Support multiple tabs and federated identity sessions where one surface expires independently from another.", "Log timeout shown, reauth started, reauth success, return restored, restart chosen, and abandoned recovery without logging private field values.", "Test idle expiry, absolute expiry, identity-provider timeout, revoked session, back-button return, reload, mobile backgrounding, multiple tabs, failed reauth, canceled reauth, and shared-device privacy." ], "commonMisuses": [ "Leaving the private page readable behind a timeout modal.", "Calling an expired session Access denied and offering request access.", "Letting stale Submit, Export, Approve, Delete, Download, or Pay buttons remain active after timeout.", "Dropping users on an unrelated dashboard after reauthentication even when a safe return target exists.", "Promising that work is saved when only an expired client page still holds it.", "Putting session tokens, raw URLs with secrets, form answers, or private object titles into timeout logs or support references." ], "critiqueQuestions": [ "Has the authenticated session already ended, or is this still a pre-expiry warning?", "What private content must disappear immediately from the timed-out page?", "Which safe reference, save timestamp, route, or draft identifier can be shown while signed out?", "Which controls must be disabled or removed because they require an active session?", "After reauthentication, where should the user return and what data can be restored?", "How does the state behave across refresh, back button, mobile backgrounding, and another tab ending the session?" ], "relatedPatterns": [ "session-timeout-warning", "sign-in", "login", "permission-denied-state", "autosave-recovery", "sensitive-data-reveal", "security-warning", "error-state" ], "comparisons": [ "session-timeout-vs-session-timeout-warning-vs-sign-in-vs-permission-denied-state-vs-autosave-recovery" ], "sourceIds": [ "nist-sp-800-63b-session-management", "owasp-session-management-cheat-sheet", "w3c-wcag-reauthenticating", "w3c-wcag-timeouts" ] }, { "id": "session-timeout-warning", "completionStatus": "complete", "name": "Session timeout warning", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Authenticated-session expiry and reauthentication boundary warning", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Authenticated products can expire idle or long-running sessions without enough warning, causing loss of work, privacy exposure, confusing access errors, duplicate submissions, or failed reauthentication recovery.", "solution": "Track server-backed idle and absolute session boundaries, warn users before expiry with remaining time and consequence copy, provide allowed extension, save, sign-out, or reauthentication actions, preserve recoverable work, and restore users to the intended task after reauthentication.", "uiGuidance": [ "Show a visible countdown or clear expiry time before inactivity, absolute session, or reauthentication limits can interrupt work; place the warning near the current task or as a focused dialog when immediate action is required.", "Offer only policy-valid actions such as Stay signed in, Save draft, Finish now, Reauthenticate, or Sign out, and state what work is saved, local-only, pending, or at risk." ], "uxGuidance": [ "Use session timeout warning to balance security, privacy, accessibility, and continuity when an authenticated session is about to expire or require reauthentication.", "Protect user effort by warning before expiry, preserving work where possible, and returning users to the same task after reauthentication instead of treating timeout as a generic failure." ], "uiExamples": { "good": [ "A benefits form shows Your session will end in 2 minutes, says the draft is saved, and offers Stay signed in, Save and sign out, and Sign out.", "A banking session requires reauthentication, keeps entered transfer details hidden but preserved, and returns to review after the user verifies again." ], "bad": [ "The app logs out after 15 minutes with no countdown and clears a long form.", "A banner says Session expiring soon but does not say when, whether work is saved, or how to continue." ] }, "uxExamples": { "good": [ "A user pauses while gathering documents, sees the remaining time, extends the session once, then saves the draft before policy requires reauthentication.", "A public-computer user ignores the warning and the product signs out, hides private content, and offers sign-in that restores only the allowed draft state." ], "bad": [ "A user returns from a phone call to find the form gone and a generic access denied page.", "A user clicks Stay signed in, but the server session is already expired and the next submit fails without preserving the answers." ] }, "problemContext": [ "The product has authenticated sessions with idle timeout, absolute timeout, public-device risk, assurance-level requirements, or reauthentication policy.", "Users may be filling forms, reviewing payments, uploading files, editing content, approving records, or reading private data when inactivity occurs.", "A timeout can affect security and privacy as well as task continuity, especially on shared devices or sensitive data surfaces.", "The product can determine the authoritative session boundary from the server or identity provider rather than from a client-only timer." ], "selectionRules": [ "Choose session timeout warning when the session is approaching an inactivity, absolute, device-lock, or reauthentication boundary that can interrupt authenticated work.", "Show the warning before the boundary, with enough time for users who need more time to respond, save, or reauthenticate.", "State the remaining time or expiry time, the consequence of expiry, and the status of current work.", "Use a modal or alertdialog when expiry is imminent and the next action must be chosen before continuing; use inline or banner status for earlier, less urgent warnings.", "Use exit warning when the user initiates departure; use session timeout warning when the system initiates a session boundary because of time or policy.", "Use autosave form to preserve progress continuously; still warn when pending or failed saves make timeout risky.", "Use permission denied state when the user is authenticated but lacks authorization, not when the session has expired.", "Do not offer Stay signed in when policy requires reauthentication or absolute termination; offer Save draft, Reauthenticate, or Sign out instead.", "After timeout, route users to sign in or reauthenticate and return to the original task with preserved data where policy and architecture allow.", "Treat public-device and high-risk flows carefully: hide private content after expiry, avoid leaking form values on signed-out pages, and disclose what remains recoverable." ], "requiredStates": [ "Active session with no warning.", "Early idle warning with remaining time and current save state.", "Imminent timeout dialog with Stay signed in or policy-valid action.", "Extension in progress state tied to server confirmation.", "Extension succeeded state that resets the displayed timer.", "Extension failed or expired state that routes to reauthentication.", "Absolute timeout or policy-required reauthentication state.", "Saved draft before timeout state.", "Timed-out signed-out state with private content hidden.", "Reauthenticated return state that restores the intended task and preserved work." ], "interactionContract": [ "The warning is driven by the authoritative session or identity state, not only a local countdown.", "Remaining time updates are readable and do not steal focus repeatedly.", "Stay signed in, extend session, or reauthenticate actions make a server-confirmed request and update the warning outcome.", "Save draft keeps recoverable work before expiry and tells users whether the save completed, failed, or remains local.", "If the session expires, private content is hidden and the next path is sign in or reauthenticate, not retrying the expired action blindly.", "After successful reauthentication, users return to the same route, step, record, or review state when policy allows.", "The warning never promises preservation or extension that the security policy cannot deliver." ], "implementationChecklist": [ "Define idle timeout, absolute timeout, reauthentication threshold, extension limits, public-device behavior, and post-timeout retention policy with security owners.", "Use server or identity-provider expiry information to schedule warnings and verify extension success.", "Choose warning thresholds that leave time to read, save, extend, or reauthenticate, including users who need more time.", "Track work state separately from session state: clean, dirty, pending save, save failed, saved draft, submitted, and unrecoverable.", "Make Stay signed in, Save draft, Reauthenticate, and Sign out distinct actions with clear outcomes.", "Hide or clear sensitive UI after expiry while preserving allowed draft references or return targets.", "Announce imminent timeout and extension results without causing repeated screen reader interruptions.", "Test server-expired token, client clock skew, multiple tabs, backgrounded mobile app, failed extension, absolute timeout, saved draft return, reauthentication return, and shared-device sign-out." ], "commonMisuses": [ "Using a client-only timer that disagrees with the server session.", "Showing Session expiring soon without a time, consequence, or action.", "Logging users out without preserving form work that could have been saved.", "Offering unlimited extension where policy requires reauthentication or termination.", "Treating timeout as access denied, not found, generic error, or retryable network failure.", "Leaving private content visible behind a timed-out overlay on shared devices.", "Interrupting users repeatedly with countdown announcements every second." ], "critiqueQuestions": [ "Which boundary is approaching: idle timeout, absolute timeout, reauthentication, or sign-out policy?", "Is the displayed countdown tied to the server or identity provider?", "What work is saved, pending, failed, local-only, submitted, or at risk?", "What action is actually allowed: extend, save, reauthenticate, finish, or sign out?", "What happens after expiry to private content and the user's return target?", "Can users who need more time perceive the warning and respond before the session ends?" ], "relatedPatterns": [ "exit-warning", "autosave-form", "draft-state", "permission-denied-state", "warning-text", "alert" ], "comparisons": [ "session-timeout-warning-vs-exit-warning-vs-autosave-form-vs-permission-denied-state" ], "sourceIds": [ "w3c-wcag-timeouts", "w3c-wcag-reauthenticating", "owasp-session-management-cheat-sheet", "nist-sp-800-63b-session-management" ] }, { "id": "settings-management", "completionStatus": "complete", "name": "Settings management", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Dedicated user or app configuration management surface", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Persistent preferences and configuration become risky when users cannot find the right setting, understand its scope, distinguish immediate from saved changes, see current values, recover defaults, or tell which dependencies and permissions control it.", "solution": "Provide a dedicated settings management surface that groups related settings, displays current values and effects, clarifies scope and ownership, handles immediate and explicit save models consistently, exposes dependencies, preserves changes, and supports search, reset, and recovery for revisited configuration.", "uiGuidance": [ "Render settings management as a durable configuration surface with a clear Settings or Preferences entry point, grouped categories, current values, setting descriptions, ownership or scope labels, dependencies, save or immediate-apply behavior, status feedback, search or section navigation for larger sets, and reset or restore defaults where appropriate.", "Separate settings management from one-off forms, single toggle controls, onboarding, profile setup, and advanced disclosure: it owns the long-term inspect-and-change contract for preferences or configuration that users may revisit." ], "uxGuidance": [ "Use settings management when users need to review and change persistent app, account, workspace, notification, privacy, display, integration, or system behavior outside the immediate task flow.", "Make each setting's scope, current value, effect timing, dependency, save model, reversibility, and downstream consequence clear before users change it." ], "uiExamples": { "good": [ "A notification settings page groups channels, quiet hours, digest frequency, and workspace scope; each row shows current value, effect, dependency, and whether changes save immediately.", "A privacy settings center shows profile visibility, app access, analytics sharing, export, and reset controls with current status and links to system-level permissions when needed." ], "bad": [ "A page called Settings mixes billing invoices, destructive account deletion, onboarding tips, profile setup, search results, and global navigation with no grouping or save model.", "A setting changes immediately, requires Save later, and syncs overnight depending on the row, but the page never explains which model applies." ] }, "uxExamples": { "good": [ "A user turns off weekly digest emails, sees the setting save immediately, keeps urgent security emails enabled, and understands the workspace-level override.", "A user changes measurement units, sees affected pages update, resets display defaults, and can find the same setting later through Settings search." ], "bad": [ "A user changes a privacy setting thinking it affects only one project, but the value applies to the whole account.", "A user closes a settings panel after changing three values and cannot tell whether they were saved, discarded, or pending admin approval." ] }, "problemContext": [ "Users need to change persistent app behavior, account behavior, workspace policy, notification preferences, privacy choices, display preferences, integrations, devices, permissions, or system-like configuration.", "Settings may affect one device, one workspace, one account, all users, a role, an integration, or downstream surfaces.", "Some settings apply immediately while others require Save, approval, restart, sync, or system permission changes.", "Users may revisit settings rarely and need clear labels, categories, current status, search, and reset paths.", "Settings may have dependencies, unavailable states, admin ownership, inherited values, conflicts, audit implications, or high-risk consequences." ], "selectionRules": [ "Choose settings management when users need a durable place to inspect and change persistent preferences or configuration.", "Use toggle switch when the task is one immediate, reversible binary setting rather than a whole settings surface.", "Use complete complex form when many related configuration fields require one edit-and-review form with dependency validation before save.", "Use progressive disclosure when a primary task needs optional advanced controls, not a revisitable settings center.", "Use profile setup when the work is completing an existing profile's readiness, visibility, or enrichment.", "Use onboarding when the work is first-use orientation or activation, not persistent configuration management.", "Separate account, workspace, device, and system-level scope with explicit labels before users change values.", "Make immediate-apply settings visually and verbally distinct from settings that require Save, Apply, Restart, Sync, or admin approval.", "Show current values, unavailable reasons, inherited defaults, and reset routes close to the setting they affect." ], "requiredStates": [ "Settings overview with categories and current values", "Focused section or detail state", "Immediate setting applied state", "Unsaved changes state", "Saved or applied confirmation state", "Unavailable or permission-blocked setting state", "Inherited or admin-managed setting state", "Reset to defaults state", "Search or filter no-result state for larger settings sets", "Failed save or conflict state with preserved changes" ], "interactionContract": [ "Opening settings management shows current persisted values, not empty defaults or stale cached assumptions.", "Each setting communicates its scope, effect, and save model before the user changes it.", "Immediate settings reconcile applied, pending, failed, and reverted states without requiring a hidden Save action.", "Explicit-save settings preserve edited values, show unsaved changes, and let users save, discard, or review before leaving.", "Disabled, inherited, managed, or permission-blocked settings explain who owns the value and where to change it.", "Reset restores only the named settings group or clearly listed defaults, never unrelated account or product data.", "Search and section navigation move users to the owning setting while preserving unsaved-change warnings." ], "implementationChecklist": [ "Inventory settings by scope, owner, data source, dependency, effect timing, risk, default value, and reset behavior.", "Decide whether each setting is immediate, staged with Save, inherited, admin-managed, system-owned, or approval-gated.", "Group settings by user mental model such as Account, Notifications, Privacy, Display, Integrations, Workspace, Billing, or Devices.", "Show current values and short effect descriptions for settings whose labels alone are ambiguous.", "Provide search, section navigation, or deep links when the settings set is large enough that scanning is unreliable.", "Design unsaved-change warnings, failed-save recovery, conflict handling, inherited values, unavailable permissions, and reset defaults.", "Test keyboard navigation, screen readers, mobile layout, high zoom, long labels, localized strings, search no results, permission denial, admin-managed values, and stale server data." ], "commonMisuses": [ "Using settings as a dumping ground for unrelated navigation, billing, help, profile setup, onboarding, or destructive account actions.", "Mixing immediate and explicit-save settings without clear status or grouping.", "Hiding current values behind edit buttons so users cannot inspect configuration quickly.", "Making settings available in multiple places with contradictory values or labels.", "Changing account-wide or workspace-wide behavior from a local page without scope warning.", "Letting disabled or inherited settings appear broken instead of explaining dependency, permission, or admin ownership.", "Resetting too broad a scope from a small reset action.", "Failing to warn about unsaved setting changes before navigation." ], "critiqueQuestions": [ "What scope does each setting affect: device, account, workspace, organization, integration, or system?", "Does the user know whether the change applies immediately or waits for Save, restart, sync, approval, or another device?", "Can users inspect current values without entering edit mode?", "Which settings are inherited, managed, permission-blocked, or dependent on other settings?", "How do users find a rarely changed setting months later?", "What happens to unsaved, failed, conflicting, or reset settings?" ], "relatedPatterns": [ "toggle-switch", "complete-complex-form", "progressive-disclosure", "inline-edit", "profile-setup" ], "comparisons": [ "settings-management-vs-complete-complex-form-vs-toggle-switch-vs-progressive-disclosure" ], "sourceIds": [ "apple-hig-settings", "material-design-settings", "android-developers-settings", "microsoft-windows-app-settings-guidelines" ] }, { "id": "settings-page", "completionStatus": "complete", "name": "Settings page", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "Dedicated page shell and section map for settings destinations", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Settings destinations become disorienting when the page shell hides section hierarchy, current location, entry route, search, responsive section switching, or boundaries between ordinary settings and unrelated account tasks.", "solution": "Provide a dedicated settings page structure with explicit page identity, grouped sections, selected-section state, section summaries, deep-link context, mobile section navigation, search for larger settings sets, separated high-risk destinations, and a return path to the invoking product area.", "uiGuidance": [ "Render a settings page as a stable destination with a clear page title, section list, selected section, section summary, grouped setting rows or links, current-location cues, search or find-in-settings for larger products, and a reliable way back to the product area that opened it.", "Separate the settings page pattern from settings management: the page pattern owns the shell, hierarchy, section navigation, responsive layout, and discoverability of settings destinations, while settings management owns how individual settings are inspected, edited, saved, reset, inherited, or recovered." ], "uxGuidance": [ "Use a settings page when users must orient within many account, app, workspace, security, notification, privacy, billing, device, integration, or display sections before changing a value.", "Make the page answer three questions before interaction: where am I, what settings live in this section, and how do I return to the work area without losing context." ], "uiExamples": { "good": [ "A workspace Settings page has a title, left section list, selected Security section, summary cards for sign-in, members, audit log, and tokens, plus a breadcrumb back to the workspace.", "A mobile Settings screen collapses the section list into a labelled section picker, keeps the selected section title visible, and shows high-risk account actions in a separated area." ], "bad": [ "A page called Settings is a long flat list of unrelated links, invoices, help articles, destructive account actions, and onboarding reminders with no section identity.", "A desktop settings page uses horizontal tabs for 24 categories, hiding Privacy and Security behind scroll and making deep links land without context." ] }, "uxExamples": { "good": [ "A user opens Settings from a project, lands on Workspace notifications, sees the current section highlighted, searches for retention, and can return to the project after editing.", "A user on mobile switches from Account to Security through a labelled section picker and sees that destructive account closure is outside ordinary settings sections." ], "bad": [ "A user follows a settings deep link and cannot tell whether they are changing personal, workspace, or organization settings because the page shell has no section context.", "A user tries to find language settings but scans through mixed billing, support, profile, and integration links because the Settings page has no category map." ] }, "problemContext": [ "Products often have many settings sections across account, profile, workspace, organization, security, notifications, privacy, display, billing-adjacent configuration, integrations, devices, data, and developer tools.", "Settings pages can be reached from global navigation, utility navigation, object context menus, email links, admin links, search results, onboarding prompts, or deep links.", "Users may visit rarely and need orientation even before they inspect or edit any specific setting value.", "Desktop layouts often use a persistent section rail, while mobile layouts need a compact section picker, drawer, or stacked category list that still preserves current section identity.", "Some settings-adjacent destinations, such as invoices, support, account deletion, profile completion, and legal pages, create confusion when placed beside ordinary configurable behavior without separation." ], "selectionRules": [ "Choose settings page when the main design problem is the destination layout, section hierarchy, selected section, and wayfinding for many settings areas.", "Use settings management when the main design problem is how setting values show current state, save behavior, dependencies, permissions, reset behavior, or failed edits.", "Use side navigation for navigation between major product destinations; use settings page navigation for sections inside one Settings destination.", "Use tabs for a small set of peer views inside one setting section, not for the entire settings taxonomy when categories are numerous or unrelated.", "Use navigation drawer when the app shell or mobile layout needs to reveal settings sections temporarily; the drawer should still lead to a settings page with a visible selected section.", "Use preference center when the page is specifically about communication, consent, privacy/data sharing, topics, language, and personalization choices that need consent-style clarity.", "Use profile setup when the task is profile readiness, required profile fields, visibility, or onboarding completion rather than long-term settings navigation.", "Use complete complex form inside a settings page when one section contains interdependent configuration that needs one reviewed save.", "Provide search or a settings index when there are enough sections that users cannot reliably scan the section list.", "Separate high-risk, legal, billing, support, and destructive account destinations from ordinary settings sections with clear labels and spacing." ], "requiredStates": [ "Settings landing or overview state with section groups", "Selected section state with title, summary, and current navigation marker", "Deep-linked section state that preserves location context", "Search or find-in-settings results state", "No-result or unmatched setting search state", "Mobile section picker, drawer, or stacked category state", "Empty, unavailable, or permission-limited section state", "High-risk or destructive destination separated from ordinary settings state", "Return-to-origin state after opening settings from a product area", "Long section labels, localization, and high-zoom wrapping state" ], "interactionContract": [ "Opening a settings page shows the page identity, current section, and whether the scope is personal, workspace, organization, app, device, or system.", "Selecting a section changes the visible section title and content without losing the user's place in the settings destination.", "Deep links land with the section navigation and page title visible, not on an orphaned form with no settings context.", "Search results identify the owning section and move users to that section while preserving a return route to results when appropriate.", "Mobile layouts keep the selected section and available sections reachable without hiding important categories behind unlabeled controls.", "High-risk destinations such as account closure, legal changes, or billing records are visually and semantically separated from ordinary settings sections.", "A return action goes back to the product area or object that opened settings, not always to a default home page." ], "implementationChecklist": [ "Inventory settings sections by user mental model, scope, risk, frequency of change, owner, and entry route before choosing the page structure.", "Define desktop and mobile section navigation patterns, including selected state, section summaries, deep-link behavior, and long-label wrapping.", "Decide which settings-adjacent destinations belong in the page, which need separation, and which should live outside Settings.", "Add search, index, or direct setting lookup when sections are numerous, rarely visited, or named differently across teams.", "Represent unavailable sections, permission-limited sections, empty integrations, and admin-only areas without making the page feel broken.", "Test global entry, object-scoped entry, deep links, browser back, return to origin, mobile section switching, high zoom, localization, keyboard navigation, and screen-reader landmarks." ], "commonMisuses": [ "Treating Settings as a miscellaneous link dump for billing, help, onboarding, profile completion, invoices, support, and destructive account actions.", "Using tabs for too many unrelated settings categories, causing hidden overflow and weak deep-link context.", "Styling settings section navigation exactly like global app navigation, so users cannot tell whether they changed app area or settings section.", "Deep-linking directly to a setting form without page title, section list, or scope label.", "Hiding the selected section on mobile after the user opens a drawer or picker.", "Putting ordinary settings and irreversible account closure in the same visual group.", "Adding search results that jump to a row but do not show the owning section or path.", "Letting long localized section names overlap controls or truncate the only meaningful navigation label." ], "critiqueQuestions": [ "Can users identify the settings scope, selected section, and return path before changing anything?", "Does this page organize sections by user mental model rather than internal service ownership?", "Which destinations are settings-adjacent but should be separated from ordinary configurable behavior?", "Will a deep link, search result, or mobile drawer still show enough section context?", "Is the section navigation distinct from global product navigation and local tabs?", "What happens when a user lacks permission for one settings section?" ], "relatedPatterns": [ "settings-management", "side-navigation", "tabs", "navigation-drawer", "profile-setup", "preference-center", "complete-complex-form", "progressive-disclosure" ], "comparisons": [ "settings-page-vs-settings-management-vs-side-navigation-vs-tabs" ], "sourceIds": [ "apple-hig-settings", "material-design-settings", "android-developers-settings", "microsoft-windows-app-settings-guidelines" ] }, { "id": "share-dialog", "completionStatus": "complete", "name": "Share dialog", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Object-level sharing control for recipients, link scope, roles, delivery, copy-link, native share, and access management", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Sharing an object changes who can see, edit, copy, download, forward, or request access to sensitive material, but many interfaces collapse recipient entry, link copying, native sharing, role changes, and revocation into a single ambiguous Share action.", "solution": "Provide an object-specific dialog that exposes current access, lets users add recipients and groups, choose link scope and role, decide notification and message behavior, copy or send links, use native share only where appropriate, review risky changes, and manage or revoke access after sharing.", "uiGuidance": [ "Render share dialog as an object-specific access panel that names the shared object, current access, recipient entry, link scope, role, notification and message choices, copy-link state, external-domain warnings, expiration, download controls, and revoke or manage-access actions.", "Separate harmless distribution actions from permission-changing actions: copying an already-valid restricted link, sending an email to existing collaborators, widening link scope, adding editors, making content public, and removing access need distinct labels and review states." ], "uxGuidance": [ "Use share dialog when a user is granting, narrowing, distributing, or reviewing access to a concrete object such as a file, folder, document, dashboard, board, recording, report, calendar item, or media asset.", "Prevent accidental exposure by showing who can open the object, what each role can do, whether recipients are inside or outside the organization, what link holders can access, whether notifications are sent, and how the share can be changed or stopped later." ], "uiExamples": { "good": [ "A report share dialog shows the report title, current viewers and editors, a recipient field, role dropdown, Notify people checkbox, message field, link set to Restricted, Copy link, and Manage access.", "A mobile share sheet offers native device targets for an already-public article while keeping product access controls separate for private workspace files." ], "bad": [ "A Share button instantly copies an Anyone with the link can edit URL without showing the current access level or role.", "A dialog asks for an email address but hides whether the person gets viewer, commenter, or editor access and whether an email will be sent." ] }, "uxExamples": { "good": [ "A manager adds finance@example.com as Viewer, keeps the link restricted, writes a notification note, copies the link, and sees that the file can be unshared from Manage access.", "A user changes a folder from restricted to anyone with the link, sees an external exposure warning and an expiration control, then confirms the broader share." ], "bad": [ "A native share sheet sends a private file URL to a chat app, but the recipient cannot open it because the product never granted access.", "A collaborator is removed from a document with no summary of who lost access or how the link behavior changed." ] }, "problemContext": [ "The shared object may be private, organization-only, public, domain-restricted, password-protected, expiring, downloadable, editable, commentable, or view-only.", "Recipients may be people, groups, domains, meeting attendees, chat spaces, external guests, anonymous link holders, or native device share targets.", "The action may create a new grant, update a link, send a notification email, copy an existing URL, open a native share sheet, revoke access, or expose an access request path.", "Policies may restrict external domains, public links, editor sharing, download and copy permissions, link expiration, passwords, ownership, or who can manage access." ], "selectionRules": [ "Choose share dialog when the primary task is sharing a specific object by recipients, groups, link scope, role, notification, copy-link, native share, or access-management controls.", "Use invite user when the user is bringing a person into a workspace, organization, channel, team, repository, or tenant with pending invitation state.", "Use object picker when users only select existing entities without sending access, changing roles, creating links, or notifying people.", "Use permission denied state when the current user lacks access and must request access or switch account before sharing.", "Use review before submit or confirmation dialog when the change is high risk, such as public links, external recipients, editor roles, removal of many people, disabled download protection, or organization-wide exposure.", "Use notification center for retained share events and access-request follow-up after the share action, not as the immediate permission editor.", "Use related links when the UI only navigates to nearby material and does not alter who can access it.", "Offer native Web Share only for device-target distribution of already-shareable content or after product permissions are correct.", "Show current access and pending changes in one place so users can distinguish adding people, changing role, changing link scope, copying a link, and stopping sharing.", "Keep revoke, remove, disable link, stop sharing, expiration, and password changes discoverable from the same access-management path used to share." ], "requiredStates": [ "Object identity and current access summary state", "Recipient entry, group entry, suggested recipient, unresolved recipient, duplicate recipient, and external recipient states", "Role selection states such as Viewer, Commenter, Editor, Owner, Can view, Can edit, and custom product roles", "Link scope states such as Restricted, specific people, organization, team, anyone with link, public, password-protected, and expired link", "Notify people, message, send, copy-link, link-copied, native share available, native share unavailable, and share canceled states", "Expiration date, password, block download, prevent copy, editor-can-share, and advanced owner-control states where the product supports them", "External sharing blocked, policy approval required, too many recipients, inherited access, parent-folder access, and anonymous viewer states", "Manage access, changed permission, removed person, disabled link, stopped sharing, transfer ownership, and failed update states", "Mobile sheet, desktop dialog, keyboard focus, screen-reader summary, loading, retry, offline, and permission-limited states" ], "interactionContract": [ "Opening the dialog identifies the object and fetches current access before presenting share controls.", "Recipient entry resolves people, groups, domains, or spaces before send and labels external, duplicate, unresolved, and already-access states.", "Role and link-scope controls update a pending change summary before the system grants broader access.", "Copy link copies the URL that matches the visible link scope and role; if the user changes link settings first, the copied link uses the updated settings or explains why it cannot.", "Send shares with the selected recipients, role, notification setting, and message, then reports whether access was granted, approval was requested, or delivery failed.", "Native share is triggered by a user action and is treated as distribution to device targets, while product-specific permissions remain visible and enforceable.", "Removing access, disabling a link, changing public access, and stopping sharing require clear affected-party summaries and return focus to the access list after completion.", "Policy restrictions, inherited folder access, organization controls, anonymous access, and owner-only settings explain what users can and cannot change." ], "implementationChecklist": [ "Define the object identity, current access model, direct grants, inherited grants, link grants, roles, group behavior, external-domain policy, notification channel, and audit fields before designing the dialog.", "Implement recipient lookup, duplicate detection, role eligibility, domain warnings, link scope choices, copy-link feedback, notification toggle, message validation, expiration, password, download protection, and revoke paths according to the real backend.", "Distinguish link creation from access granting: copying an existing restricted link should not silently make the object public or editable.", "Add review or confirmation for public, anyone-with-link, editor, external, organization-wide, inherited-access, owner-transfer, and mass-removal changes.", "Support manage-access actions such as change role, remove person, delete link, stop sharing, edit expiration, remove password, and inspect pending access requests.", "Handle native Web Share with feature detection, user activation, permission-policy failures, unsupported file types, cancellation, no targets, and fallback copy-link or email actions.", "Log actor, object, old access, new access, recipients, link scope, role, notification choice, message presence, copied link, expiration, revoke, and failure reasons without leaking secret link tokens.", "Test mobile layout, keyboard navigation, screen-reader labels, long object names, long recipient lists, external domains, anonymous link holders, inherited folders, blocked policy, offline retry, and localization." ], "commonMisuses": [ "Using Share as a one-click public-link generator without showing the link scope.", "Treating native OS share as if it grants product access.", "Hiding current viewers, editors, and link holders from the user who is about to change access.", "Defaulting to broad editor access when most shares should be restricted or view-only.", "Copying a link whose access does not match the visible role or scope.", "Making revoke, delete link, stop sharing, expiration, or password settings harder to find than the initial share action.", "Sending notifications without telling the user which recipients will be emailed.", "Letting inherited parent-folder access look like a removable direct grant." ], "critiqueQuestions": [ "What exact object is being shared, and can users verify it before they change access?", "Who can open the object now, who will gain access, and who will lose access after this action?", "What can recipients do: view, comment, edit, download, copy, reshare, or manage permissions?", "Does the link apply to specific people, an organization, anyone with the link, or the public web?", "Will anyone be notified, and does the message match the role and link being sent?", "Can users revoke access, delete the link, stop sharing, or change expiration after sending?", "What happens when native share is unavailable, canceled, blocked by permission policy, or unable to share the selected data?" ], "relatedPatterns": [ "invite-user", "object-picker", "modal-dialog", "popover", "permission-denied-state", "review-before-submit", "confirmation-dialog", "notification-center", "related-links", "mentions", "activity-log" ], "comparisons": [ "share-dialog-vs-invite-user-vs-object-picker-vs-modal-dialog" ], "sourceIds": [ "google-drive-share-files", "microsoft-onedrive-share-files-folders", "microsoft-onedrive-manage-sharing-permissions", "dropbox-sharing-permissions", "dropbox-create-share-links", "mdn-web-share-api", "mdn-navigator-share" ] }, { "id": "sheet", "completionStatus": "complete", "name": "Sheet", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Adaptive temporary sheet for a context-bound child task", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need a temporary child task related to the current context, but the task needs more room and stronger dismissal rules than a small dialog or popover.", "solution": "Present a titled sheet as an adaptive surface attached to a window, side, or viewport edge, move focus into it, keep the parent context available only as allowed by the sheet mode, and guard dismissal when work inside the sheet is unsaved.", "uiGuidance": [ "Render a sheet as a titled adaptive surface with clear edge or window attachment, visible close or back controls, stable actions, and sizing that matches the task.", "Use scrim, elevation, divider, or shared layout treatment to communicate whether the parent is blocked, visible for orientation, or deliberately usable beside the sheet." ], "uxGuidance": [ "Use sheets for short child tasks that need more room than a dialog while preserving parent context after the task closes.", "Make save, cancel, discard, drag, Escape, back, outside click, size change, and focus return behave consistently so users understand the temporary mode." ], "uiExamples": { "good": [ "A review follow-up sheet opens from a claim row with the title Schedule follow-up for Claim C-1042, fields, close control, compact and expanded sizes, and sticky Save and Cancel actions.", "A modal side sheet shows a scrim over the queue, names the parent claim, and keeps discard-review controls visible when the user tries to close with unsaved edits." ], "bad": [ "A panel titled Sheet opens with no selected object, no close affordance, and hidden actions below an inner scroll area.", "A swipe-dismiss sheet contains unsaved form fields but disappears immediately when the user drags or presses Escape." ] }, "uxExamples": { "good": [ "Opening the sheet focuses the first useful field, expanding the sheet preserves typed notes, Escape triggers discard review when edits are dirty, and Save returns focus to the claim row.", "Users can cancel a clean sheet immediately, but dirty sheets require Keep editing or Discard changes from every close route." ], "bad": [ "A user changes the appointment note, presses back, and loses the work without a decision point.", "The sheet blocks the queue even though the user's main task is comparing records, or it contains full navigation that should belong elsewhere." ] }, "problemContext": [ "A user starts a related form, picker, review, preview, or settings task from an existing page or object.", "The task is short enough to remain a temporary surface but too spatially rich for a compact dialog.", "The product needs adaptive sizing, side placement, drag or detent behavior, or a roomy edge-attached layout.", "Dismissal could discard in-progress edits, so close, Escape, back, drag, and outside-click paths must share one rule." ], "selectionRules": [ "Choose sheet when the user starts a short child task tied to the current page and needs a roomy temporary surface with title, actions, and a controlled close path.", "Use drawer when the surface is mainly supplemental inspection or light action that should preserve side-by-side comparison with the parent page.", "Use modal dialog when the task is compact, centered, and does not need adaptive sheet sizing, edge attachment, or drag-style dismissal.", "Use alert dialog when the user must answer an urgent or consequential interruption before continuing.", "Use a full page when the task needs multiple steps, saved progress, shareable URL state, or long-form reading.", "Use popover, hover card, tooltip, or inline disclosure when the content is local, brief, or does not need a temporary task mode.", "Use a bottom sheet for mobile-first lower-edge contextual controls when reach, detents, and underlying map or feed context define the interaction.", "Use a standard side sheet only when the sheet and parent can share layout intentionally; use a modal sheet when parent interaction must stop." ], "requiredStates": [ "Closed parent state with an opener tied to the object, field, or task that launches the sheet.", "Opening state that moves focus into the sheet and communicates whether the parent is inert or shareable.", "Open sheet state with visible title, optional subtitle or selected-object identity, close affordance, body content, and task actions.", "Dirty state when edits, selections, or uploads inside the sheet have not been saved.", "Dismissal review state when a close, Escape, back, outside click, or drag gesture would discard unsaved work.", "Expanded or compact state when the sheet supports size changes or side placement.", "Completed state that applies the sheet task and returns users to the parent context.", "Responsive state that changes placement or size without changing the task contract." ], "interactionContract": [ "The opener explains why the sheet appears and which parent object or task it belongs to.", "Opening the sheet moves focus to the sheet title, first field, or first useful control according to task risk.", "The sheet title names the child task or selected object rather than saying Sheet.", "All dismissal routes use the same unsaved-change rule, including close button, Escape, back, scrim or outside click, and drag gesture.", "Primary and secondary actions stay visible or predictably reachable when sheet content scrolls.", "Modal sheets make the parent inert and contain focus until the sheet closes.", "Standard side sheets define how focus moves between the sheet and parent when both remain usable.", "Closing the sheet returns focus to the opener or the parent object that launched it and preserves parent filters, scroll, and selection." ], "implementationChecklist": [ "Define whether the sheet is modal, standard, side-attached, window-attached, compact, expanded, or full-screen at each breakpoint.", "Give the sheet a visible title and wire that title to the accessible name of the surface.", "Provide a visible close affordance and consistent Escape, back, outside-click, and drag-dismiss behavior.", "Track dirty state inside the sheet and intercept destructive dismissals with a discard-or-continue decision.", "Keep primary actions visible, sticky, or reachable when content scrolls.", "Set initial focus on open and restore focus after save, cancel, discard, Escape, or gesture dismissal.", "Preserve the parent context that launched the sheet.", "Test small screens, zoom, long content, swipe or drag dismissal, screen readers, keyboard order, and unsaved edits." ], "commonMisuses": [ "Using a sheet as a catch-all panel for navigation, filters, help, settings, and unrelated actions.", "Allowing swipe, Escape, outside click, or back to discard unsaved sheet edits silently.", "Opening a sheet for a tiny sentence of help that belongs in inline text, tooltip, hover card, or popover.", "Using a dismissible sheet for an urgent mandatory response that needs alert-dialog behavior.", "Letting a sheet grow into a full workflow without progress, saved state, route history, or shareable location.", "Leaving background controls focusable behind a modal sheet.", "Changing sheet size or breakpoint behavior in a way that hides actions or changes the meaning of dismissal." ], "critiqueQuestions": [ "What child task does this sheet contain, and why is it not a drawer, compact dialog, or page?", "Which dismissal routes exist, and do they all protect unsaved edits the same way?", "Is the parent view inert, shareable, or partially visible, and does focus behavior match that choice?", "Does the sheet title identify the task or selected object?", "What happens when the sheet is compact, expanded, dragged, closed, or reopened?", "Would bottom sheet, drawer, modal dialog, alert dialog, popover, or full page better match the content?" ], "relatedPatterns": [ "drawer", "modal-dialog", "alert-dialog", "confirmation-dialog", "navigation-drawer" ], "comparisons": [ "sheet-vs-drawer-vs-modal-dialog-vs-alert-dialog" ], "sourceIds": [ "apple-hig-sheets", "material-side-sheets", "material-components-android-side-sheet", "wai-aria-apg-dialog-modal" ] }, { "id": "side-navigation", "completionStatus": "complete", "name": "Side navigation", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Persistent local hierarchy at the side of content", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users working inside a complex area need to see where the current page sits in that area's hierarchy and move to nearby pages without returning to global navigation or search.", "solution": "Provide persistent side navigation scoped to the current area, with short hierarchical labels, expanded active ancestors, an unmistakable current-page state, and predictable behavior across route changes and viewport changes.", "uiGuidance": [ "Render a vertical navigation region beside the main content that exposes the current area's parent, child, and optional grandchild pages with a clear active indicator.", "Keep the side navigation visually subordinate to global navigation and structurally tied to the content section it controls." ], "uxGuidance": [ "Use side navigation to help users move within a complex section without losing the current page's position in that section.", "Keep active ancestors expanded and labels short so users can scan nearby pages without reopening navigation or interpreting a hidden hierarchy." ], "uiExamples": { "good": [ "A settings page shows Account, Billing, Team, and Security in a left rail with Security expanded and Audit log marked as current.", "The active item has a text label, selected border, and semantic current state rather than color alone.", "The page heading matches the active side-nav item while the global header remains separate above it." ], "bad": [ "A sidebar mixes Dashboard, Reports, Sign out, Help, Team, API, Billing, and Marketing with no section grouping.", "The side navigation highlights Settings while the page heading is Audit log.", "A collapsed Security parent hides the current Audit log page." ] }, "uxExamples": { "good": [ "Users open Billing, switch to Invoices, then return to Security and see the Security group still expanded.", "Deep-linked users land on Audit log with Security expanded and Audit log visibly current.", "Keyboard users tab through the side navigation, activate a child page, and land in content whose heading matches the selection." ], "bad": [ "Users must reopen a drawer every time they move between sibling pages in the same desktop section.", "The current page disappears because only top-level parents are shown until hovered.", "Clicking a side-nav item resets local filters and scroll state without warning." ] }, "problemContext": [ "A section has enough related pages that page-level links or tabs become too shallow.", "Users often move among sibling and child pages inside one product area.", "The product already has global navigation, so local hierarchy needs a secondary but persistent place." ], "selectionRules": [ "Choose side navigation when users need persistent access to related pages in one section or area.", "Keep the hierarchy to one to three visible levels; deeper structures need information architecture cleanup, search, or another navigation model.", "Show the current page and expand its parent chain on deep links and route changes.", "Use short labels derived from page titles rather than full marketing or legal headings.", "Keep global destinations, account utilities, and sign-out controls out of local side navigation.", "Use tabs instead when the destinations are shallow sibling panels for one object, and use a drawer when the navigation must be dismissible on constrained screens." ], "requiredStates": [ "Default state with the local section hierarchy visible beside content.", "Current page state that matches the content heading and route.", "Expanded parent state when a child or grandchild page is active.", "Collapsed parent state that does not hide the user's current location.", "Scrollable long-list state with current item still reachable and visible.", "Responsive state that turns into a drawer or menu only when space requires it." ], "interactionContract": [ "Activating a side-nav item changes the local page and updates current-page semantics.", "The current item's parent chain remains visible after navigation and direct deep links.", "Collapsing a parent with the current page either remains blocked, keeps a current summary visible, or clearly indicates the hidden current page.", "Side navigation does not reset unrelated local filters, drafts, or scroll state unless the route change requires it and the user is warned.", "Keyboard focus moves through parent toggles and child links in reading order, then proceeds to main content.", "Responsive drawer variants restore focus to the opener when dismissed and keep the same local hierarchy." ], "implementationChecklist": [ "Derive side-nav structure from the current section's information architecture rather than the full product route table.", "Use a labeled navigation landmark and mark the current page programmatically.", "Expand active ancestors on first render, direct links, and back/forward navigation.", "Limit nesting depth and test whether users can find lower items without excessive scrolling.", "Keep side navigation visually separate from global navigation and page actions.", "Define responsive behavior for when the side nav becomes a drawer, collapses to a menu, or moves below the heading.", "Preserve local page state where appropriate when users move between sibling pages." ], "commonMisuses": [ "Duplicating global navigation links in the side navigation.", "Letting the highlighted item drift from the page heading or route.", "Hiding the active child under a collapsed parent.", "Building a five-level tree that users cannot scan.", "Using side navigation for one or two pages that do not need hierarchy.", "Replacing persistent desktop side navigation with a hamburger drawer that users must reopen for every sibling page." ], "critiqueQuestions": [ "Is this side navigation scoped to one section, or is it a second global nav?", "Can a deep-linked user see the current page and its parent without clicking?", "Are labels short enough to scan in a narrow side column?", "What happens to current state when a parent is collapsed or the viewport narrows?", "Would tabs, breadcrumbs, in-page navigation, or global navigation better match the user's movement?" ], "relatedPatterns": [ "global-navigation", "header", "tabs", "breadcrumbs" ], "comparisons": [ "side-navigation-vs-global-navigation-vs-tabs" ], "sourceIds": [ "uswds-side-navigation", "carbon-ui-shell-left-panel", "material-navigation-drawer" ] }, { "id": "sign-in", "completionStatus": "complete", "name": "Sign in", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Returning-account authentication and session start flow", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Sign-in flows sit at the boundary between public and protected work, so unclear identity choices, password-manager resistance, revealing errors, missing recovery, or lost return destinations can block legitimate users while leaking account information to attackers.", "solution": "Provide a focused returning-access flow that authenticates the user with available credentials or identity provider options, preserves the intended destination, handles failure without enumeration, supports password managers and passkeys, and routes safely to recovery, account creation, or step-up verification only when needed.", "uiGuidance": [ "Render sign in as a focused authentication surface with a clear service or destination name, account identifier field, current-password or passkey path, password-manager-friendly attributes, recovery routes, create-account route, and neutral error area.", "Keep account creation, password creation, profile setup, two-factor enrollment, and broad onboarding separate unless the sign-in decision genuinely needs to route to those flows." ], "uxGuidance": [ "Use sign in when users are returning to an existing account, protected resource, invitation, draft, checkout, or workspace and need to prove control of an authenticator.", "Preserve the intended destination, support saved credentials and passkeys, avoid account enumeration, explain locked or throttled states without exposing account status, and return users to the task they came from after success." ], "uiExamples": { "good": [ "A sign-in page names the workspace, shows email or username, password with current-password autocomplete, passkey option, forgot-password link, create-account link, and a destination reminder such as Continue to Q2 budget review.", "A federated sign-in page shows the organization domain after the identifier step, explains Continue with company SSO, and preserves the original invite after identity-provider return." ], "bad": [ "A sign-in page has four equal buttons for sign in, create account, reset password, and browse plans, with no indication of the protected destination.", "A failed sign-in says This email exists but the password is wrong, exposing account status." ] }, "uxExamples": { "good": [ "A user opens a private document link, signs in with a saved passkey, and lands back on the same document with focus near the access confirmation.", "A user mistypes credentials, sees a generic account-details error, can retry, use forgot password, or switch to SSO without losing the return destination." ], "bad": [ "A user signs in from checkout and lands on a generic account dashboard, losing the cart and payment context.", "A password manager cannot fill the form because the identifier and password fields were renamed and paste was blocked." ] }, "problemContext": [ "Users are trying to access an existing account, protected record, workspace, invitation, checkout, subscription, saved draft, or personal data.", "The product may support password, passkey, SSO, magic link, one-time code, or multi-factor step-up authentication.", "The same surface must serve first-time visitors who need account creation, returning users who need sign in, locked or disabled accounts, and users who forgot their password.", "Security requirements may require generic error messages, throttling, risk-based step-up, protected channels, phishing-resistant authenticators, or reauthentication.", "Users may arrive from deep links and expect the product to preserve the protected destination after authentication." ], "selectionRules": [ "Choose sign in when the user needs to start or restore an authenticated session for an existing account.", "Name the destination or service being accessed so users know why authentication is required.", "Use account creation when the user is establishing a new account, not when they are proving access to an existing one.", "Use password input for the individual secret field behavior; sign in owns the surrounding flow, routing, errors, recovery, and return destination.", "Use session timeout warning when an existing authenticated session is approaching expiry; sign in is the recovery or reauthentication destination after the boundary occurs.", "Support password managers, autofill, passkeys, and paste with standard username, current-password, one-time-code, and webauthn semantics where applicable.", "Provide forgot password, switch account, SSO, passkey, help, and create-account routes with clear priority and explanations.", "Use neutral failure copy that does not reveal whether the account exists, the password was wrong, the account is locked, or the account is disabled.", "Preserve and validate the return URL or originating task so successful authentication returns users to the protected context instead of a generic dashboard.", "Escalate to step-up authentication only when risk, policy, authenticator type, or protected action requires it." ], "requiredStates": [ "Initial sign-in state with service or destination context.", "Identifier entry state for email, username, phone, organization domain, or account name.", "Password, passkey, SSO, magic-link, or authenticator-choice state.", "Password-manager and autofill-ready state using credential autocomplete semantics.", "Generic failed-authentication state that preserves retry and recovery without enumeration.", "Throttled, suspicious, locked, disabled, or support-needed state with safe copy and next steps.", "Forgot-password, create-account, switch-account, and help route state.", "Step-up or one-time-code state when additional verification is required.", "Successful sign-in state that returns to the intended destination.", "Expired or invalid return-destination state with a safe fallback and explanation." ], "interactionContract": [ "The sign-in form identifies the protected service or destination before requesting credentials.", "Credential fields use labels and autocomplete values that let browsers, password managers, and assistive technology understand identifier, current password, passkey, and one-time-code purposes.", "Users can paste and autofill credentials unless a specific security owner approves a narrower exception with an accessible alternative.", "Failure responses do not distinguish unknown account, wrong password, locked account, disabled account, or unverified account in a way that enables enumeration.", "Retry, forgot-password, create-account, passkey, SSO, and help routes keep the return destination when policy allows.", "Successful sign in rotates or establishes the authenticated session and returns users to the protected route, invite, draft, checkout, or action they started from.", "Throttling, CAPTCHA, device challenge, or step-up checks state why more verification is needed without blaming the user or exposing sensitive status." ], "implementationChecklist": [ "Define supported identifiers, authenticators, identity providers, passkeys, magic links, one-time codes, recovery paths, and step-up policies with security owners.", "Add username, current-password, one-time-code, and webauthn autocomplete attributes where applicable, and test browser and password-manager fill behavior.", "Preserve a validated return destination through sign in, SSO redirects, recovery, MFA, throttling, and account switching.", "Use a single generic failed-authentication message and verify HTTP status, response body, redirect behavior, error codes, timing, and analytics do not reveal account existence.", "Separate create-account, forgot-password, passwordless, SSO, passkey, and help links visually and semantically from the primary sign-in action.", "Test wrong identifier, wrong password, unknown account, locked account, disabled account, expired password, rate limit, passkey unavailable, SSO failure, MFA needed, browser Back, mobile keyboard, screen readers, high contrast, and deep-link return." ], "commonMisuses": [ "Using account-specific error messages that reveal whether an identifier exists.", "Blocking paste, password managers, passkeys, or autofill by using nonstandard field names or autocomplete off.", "Sending successful users to a generic dashboard instead of the document, checkout, invite, draft, or action they requested.", "Making create account, forgot password, and sign in look like equal primary actions.", "Forcing profile setup, marketing preferences, or onboarding before completing the sign-in return path.", "Treating expired-session recovery as a brand-new sign-in without preserving private work or explaining timeout.", "Using a CAPTCHA as the only recovery from failed sign-in attempts." ], "critiqueQuestions": [ "What protected destination or task brought the user to sign in?", "Which identifier and authenticator options are actually supported for this account population?", "Can password managers, passkeys, one-time codes, and paste work with the fields as implemented?", "Does the failure response reveal account existence through copy, redirects, timing, status codes, URLs, or analytics?", "Where does the user land after successful sign in, SSO return, MFA, recovery, or account switch?", "Which sign-in failures require support, throttling, step-up, or password recovery rather than another retry?" ], "relatedPatterns": [ "account-creation", "password-input", "password-creation", "email-address-entry", "session-timeout-warning", "permission-denied-state" ], "comparisons": [ "sign-in-vs-account-creation-vs-password-input-vs-session-timeout-warning" ], "sourceIds": [ "owasp-authentication-account-enumeration", "owasp-authentication-password-managers", "nist-sp-800-63b-authentication-lifecycle", "mdn-input-password", "mdn-autocomplete-credentials", "html-autocomplete-webauthn" ] }, { "id": "single-page-form", "completionStatus": "complete", "name": "Single-page form", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Short related multi-field submission page", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Short related data-entry tasks become slower and more error-prone when users must hop across unnecessary pages, cannot compare related values, or lose multiple entered fields after validation.", "solution": "Put a small coherent set of related fields on one page with clear grouping, required and optional labelling, one submit action, linked validation recovery, and preservation of all entered values.", "uiGuidance": [ "Render a clear form heading, short instruction, required or optional indicator explanation, grouped related fields, one primary submit action, and a visible error summary only after failed submit.", "Use a simple vertical field order with fieldsets and legends for related groups, aligning validation messages with the fields they describe and keeping visual order the same as DOM order." ], "uxGuidance": [ "Use a single-page form when users benefit from seeing, comparing, and editing a small related set of fields before one submission.", "Preserve every entered value after validation, let users correct fields in place, and avoid unnecessary page-by-page navigation when the task is short and low branching." ], "uiExamples": { "good": [ "A contact-details form shows one heading, a required-field note, grouped name and contact fields, communication preference radios, aligned field errors, and a Save details button at the end.", "An account profile edit page keeps related fields in one vertical order so users can compare email, phone, and notification preference before saving." ], "bad": [ "A long application with eligibility, address history, uploads, and payment fields is dumped onto one scrolling page.", "Required fields are marked only by color, sections have no headings, and a disabled submit button gives no recovery path." ] }, "uxExamples": { "good": [ "A user edits email and phone together, submits, sees two linked errors, fixes both without losing the preference selection, and saves the whole form once.", "A user reviews all contact details before submitting because the fields are short, related, and visible in one scan." ], "bad": [ "A user submits a mixed form, sees a generic red banner, scrolls through many unrelated fields, and cannot find which answers failed.", "A validation failure clears completed fields, forcing the user to re-enter unrelated information." ] }, "problemContext": [ "The form collects a compact set of related details, such as profile, contact, shipping, sign-in, or preferences.", "Users need to compare or revise multiple answers together before committing them.", "The task has limited branching and can preserve all entered values on one route." ], "selectionRules": [ "Choose a single-page form when the task has a short related set of fields that users should review together.", "Prefer single-question pages when each answer needs focused reading, mobile-first recovery, branching, or per-page autosave.", "Prefer multi-step forms when fields are numerous, high-stakes, logically separated into sections, or too long for reliable one-page recovery.", "Use a wizard only when the sequence is guided, stateful, and dependent on previous answers.", "Group related controls with fieldsets, legends, headings, or section labels rather than presenting one undifferentiated list.", "Explain required and optional conventions before the first field and use native required attributes where appropriate.", "Use an error summary plus field-level messages when failed submit can produce more than one error.", "Preserve all field values after client or server validation and keep the submit action at the end of the reviewed form." ], "requiredStates": [ "Initial empty state with form heading, instruction, required or optional indicator explanation, grouped fields, and submit action.", "Partially completed state where users can compare values across related fields before saving.", "Submitting state that prevents duplicate submit without hiding entered values.", "Failed-submit state with linked error summary and matching field-level messages.", "Corrected state where fixed fields clear their errors while other values remain intact.", "Successful submit state that confirms the whole form was saved or sent.", "Disabled or unavailable-field state with explanation and recovery path when a field cannot be edited." ], "interactionContract": [ "Tab order follows the same top-to-bottom order users see on screen.", "Submit validates the whole form once and reports every actionable error without clearing valid fields.", "Error summary links move users to the affected field, fieldset, or first invalid control in a group.", "Inline messages sit next to the fields they describe and match summary wording.", "Editing one field after submit does not reset unrelated fields or hide their entered values.", "A secondary cancel, reset, or back action is visually and behaviorally distinct from the primary submit." ], "implementationChecklist": [ "Inventory the fields and remove questions that are not needed to complete the service.", "Confirm the remaining fields are related enough to scan and submit together on one page.", "Use a single-column layout unless research proves a different layout does not harm reading or keyboard order.", "Wrap related radio, checkbox, date, or grouped controls in fieldsets with legends.", "Label required and optional fields consistently before users start the form.", "Place one primary submit action after the last field and avoid disabled submit unless the disabled reason is explained.", "Implement an error summary for failed submit and preserve every entered value across client and server validation.", "Test keyboard order, screen reader group labels, zoom, mobile scrolling, validation, browser autofill, reload, and server-error recovery." ], "commonMisuses": [ "Using one page for a long complex application just to avoid designing steps.", "Splitting a compact related edit task into many pages so users cannot compare values.", "Mixing unrelated tasks, such as contact details, payment, uploads, and legal acceptance, under one submit button.", "Using placeholder text instead of persistent labels inside a multi-field form.", "Showing only a generic error banner after submit.", "Clearing all values after one field fails validation.", "Reordering fields visually with CSS so keyboard and screen-reader users encounter a different sequence.", "Disabling submit or required fields without an explanation or recovery path." ], "critiqueQuestions": [ "Are all fields on this page related to one small task outcome?", "Do users need to compare or edit these answers together before submitting?", "Would splitting this into pages reduce error recovery, branching, or mobile effort?", "Are required and optional conventions clear before the first field?", "Does failed submit preserve all values and link each error to the exact field or group?", "Does keyboard and screen-reader order match the visual field order?" ], "relatedPatterns": [ "single-question-page", "text-input", "textarea", "radio-group", "error-summary" ], "comparisons": [ "single-page-form-vs-single-question-page-vs-error-summary-vs-text-input" ], "sourceIds": [ "uswds-form-templates", "govuk-form-structure-service-manual", "govuk-error-summary-component" ] }, { "id": "single-question-page", "completionStatus": "complete", "name": "Single-question page", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Focused form page for one answer or decision", "maturity": "standard", "platforms": [ "web", "mobile" ], "problem": "Users can struggle with dense forms when unrelated questions, unclear headings, hidden progress, early validation, or lost answers make each decision harder than it needs to be.", "solution": "Give one conceptual question its own page with the question as the heading, concise context, the appropriate answer control, predictable Back and Continue actions, focused validation, and preserved answer state.", "uiGuidance": [ "Render one clear question as the page heading, optional explanatory text before the answer, one answer area, a primary Continue action, and a Back link or equivalent return path.", "Keep only controls that answer the same question on the page, such as a radio group with a conditional detail field, and place errors directly in the question area with a page-level summary when needed." ], "uxGuidance": [ "Use a single-question page when users need to focus on one decision, understand one piece of information, or answer one conceptual question before moving on.", "Preserve the selected or typed answer through Back, Continue, validation, and route changes, and validate only the current question before advancing to the next page." ], "uiExamples": { "good": [ "A page heading asks Do you have evidence to upload?, explanatory text sits above a yes/no radio group, Continue follows the answer, and Back returns to the previous service step.", "A date question uses three related fields on the same page because day, month, and year answer one question." ], "bad": [ "One page asks for name, address, evidence status, and payment method under a vague Details heading.", "A focused question page has only a field label inside the input, no page heading, no Back path, and an unlabeled next button." ] }, "uxExamples": { "good": [ "A user chooses Yes, sees a follow-up detail field on the same question page, goes Back, returns, and the answer is still selected.", "A user submits without choosing an answer, sees a specific error, selects an option, and Continue advances without losing prior answers." ], "bad": [ "A user answers three unrelated questions on one screen and submits, but the error only says fix details without naming the question.", "A user goes Back to check the previous step and the question page clears the answer they already gave." ] }, "problemContext": [ "The service is collecting sequential answers, eligibility decisions, or task data where one answer may shape the next screen.", "Users may be on small screens, under stress, using assistive technology, or completing a high-stakes government, finance, health, or support flow.", "The answer may use one field or several related controls, but those controls all answer the same question." ], "selectionRules": [ "Choose a single-question page when one conceptual question deserves focused reading and answering before the next task step.", "Use the question text as the page heading when it is the main task on the page.", "Keep related fields together when they answer one question, such as a date split into day, month, and year.", "Prefer a single-page form for short low-risk data sets that users need to scan, compare, or edit together.", "Use single-question pages inside a multi-step form when the broader journey has several ordered pages or sections.", "Avoid wizard framing unless users need a guided sequential tool with strict branching, step locking, or complex progress management.", "Use the appropriate answer control inside the page, such as radio group, checkbox group, text input, textarea, date input, or file upload.", "Validate on Continue or after interaction, preserve the answer, and keep the user on the same question until it is fixable." ], "requiredStates": [ "Initial unanswered state with question heading, optional explanation, answer control, Back link, and Continue action.", "Answered state showing the selected or typed answer before submission.", "Conditional detail state when an answer reveals another field that still belongs to the same question.", "Missing-answer error state after Continue with the answer control still available.", "Recovered state after correcting the current question.", "Back-return state with the previous answer restored.", "Loading or saving state when Continue persists the answer before moving to the next page." ], "interactionContract": [ "Back returns to the previous page or step without clearing the current answer.", "Continue validates only the current question and moves forward only when the answer is complete enough for the next page.", "Changing an answer updates any related conditional content without navigating unexpectedly.", "Errors identify the question and affected controls, preserve the answer, and keep focus or reading order in a recoverable place.", "The browser Back button and service Back link do not create conflicting histories or duplicate submissions.", "Progress indicators, if present, describe the broader flow without turning the page into a dense wizard dashboard." ], "implementationChecklist": [ "Write the page heading as the exact question users need to answer.", "Place any explanation, eligibility context, or privacy note before the answer control.", "Choose the answer control by the data being collected rather than by the page pattern name.", "Group related controls on the same page when they answer one conceptual question.", "Provide Back and Continue actions with consistent placement and labels across the flow.", "Persist the current answer before navigation and restore it after Back, validation, reload, or server errors.", "Add field-level errors and an error summary when the page is submitted with invalid or missing answers.", "Test the page with keyboard, screen reader, zoom, mobile viewport, browser Back, service Back, validation, and conditional answer changes." ], "commonMisuses": [ "Putting several unrelated questions on one page and still calling it one thing per page.", "Splitting one answer across several pages when the fields need to be understood together.", "Using the pattern as a substitute for choosing the right field control.", "Adding wizard chrome, progress locking, or branching UI to a simple isolated question.", "Clearing the answer after Back, Continue, validation, or reload.", "Using vague headings such as Details or Step 2 instead of the actual question.", "Showing a generic error that does not name the unanswered question.", "Making users continue through many trivial pages when a short single-page form would be faster and lower risk." ], "critiqueQuestions": [ "Is there exactly one conceptual question on this page?", "Does the page heading clearly state the question users are answering?", "Do all controls on the page answer the same question?", "Would users benefit more from scanning these fields together on one page?", "Does Back, browser Back, validation, and Continue preserve the current answer?", "Is the next page determined by this answer, and is that transition understandable?" ], "relatedPatterns": [ "text-input", "textarea", "radio-group", "error-summary", "step-navigation" ], "comparisons": [ "single-question-page-vs-text-input-vs-textarea-vs-error-summary" ], "sourceIds": [ "govuk-question-pages-pattern", "govuk-form-structure-service-manual", "govuk-designing-good-questions" ] }, { "id": "site-alert", "completionStatus": "complete", "name": "Site alert", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Urgent full-width sitewide alert near the top of every page", "maturity": "standard", "platforms": [ "web", "mobile" ], "problem": "Users may enter a site from any page during an urgent public or servicewide condition, and ordinary banners, page alerts, toasts, or home-page announcements can miss deep-linked users or hide the urgency inside local context.", "solution": "Publish one full-width site alert near the top of every affected page, state the urgent condition and public consequence, include the most useful route to details or alternatives, announce dynamic updates with the right ARIA role, and retire or version the alert when the condition changes.", "uiGuidance": [ "Render the site alert as a full-width message near the top of the site, before ordinary navigation or page content users might otherwise start from.", "Use one clear heading, concise body text, restrained severity styling, and a short list of related links or updates when several urgent sitewide facts need to be grouped." ], "uxGuidance": [ "Use a site alert when urgent public or servicewide information must be obvious and findable from any page, including deep links, refreshes, and routes outside the home page.", "Define alert ownership, audience, start and end conditions, update cadence, dismissal policy, and escalation path before publishing it across the whole site." ], "uiExamples": { "good": [ "A public benefits site shows Emergency office closures at the very top of every page, with affected offices, updated time, and a link to alternate service channels.", "A sitewide service outage notice appears full-width above the site header and includes a short related-links list for status, phone service, and appointment rescheduling." ], "bad": [ "The emergency message appears only on the home page, so users who land on Apply or Help do not see it.", "Three large red alerts stack above the header, mixing closure, newsletter, and one form error." ] }, "uxExamples": { "good": [ "A user enters through a bookmarked application-status page and still sees the same closure alert before using the service.", "When a new evacuation update is pushed mid-session, the site alert announces the update and records the new timestamp." ], "bad": [ "Users dismiss a critical emergency alert once and never see a later update because dismissal is not versioned.", "A workspace-only maintenance message is published as a public site alert and alarms users who are not affected." ] }, "problemContext": [ "The message applies to the whole public site, service, agency property, or critical operating channel rather than one workspace, record, form, or route.", "Users can arrive through search, bookmarks, shared links, notifications, or deep links and still need the warning before using the site.", "The condition is urgent, time-sensitive, public, or operationally critical enough to appear above ordinary navigation and page content.", "The message may need updates, timestamps, or grouped related links while the same sitewide condition remains active." ], "selectionRules": [ "Choose site alert when urgent sitewide information must appear by default on every affected page near the top of the site.", "Use emergency treatment for public safety, closures, evacuation, payment suspension, system outage, or other high-consequence service availability messages.", "Use informational site-alert treatment for important sitewide operating status that is not an emergency but still must be seen across the site.", "Use banner instead when the message is broad but limited to a product, account, workspace, section, or official identity scope.", "Use notification banner instead when the message belongs immediately before the H1 in one service page flow.", "Use alert instead when a current task dynamically changes and users need immediate notice inside that task.", "Use error summary and field messages instead for submitted form validation errors.", "Show one site alert per affected site scope; combine related urgent facts into a short list rather than stacking multiple site alerts.", "Let users dismiss only noncritical site alerts or alerts that remain recoverable from a stable status page, and store dismissal by alert id, version, audience, and site scope." ], "requiredStates": [ "No-site-alert state when no urgent sitewide condition applies.", "Emergency site alert visible at the top of every affected page.", "Informational site alert for non-emergency servicewide operating status.", "Slim site alert for a short urgent message with a single detail link.", "Expanded or list state for several related urgent updates inside one alert.", "Dynamic update state with changed timestamp and appropriate alert or status semantics.", "Dismissed state for safe informational alerts, versioned so new urgent updates reappear.", "Resolved state where the alert is removed or replaced by a low-impact status page reference." ], "interactionContract": [ "The site alert appears before ordinary page content and is reachable from any affected route, not just the home page.", "The alert heading names the sitewide condition rather than a generic severity label.", "The body states who is affected, what users should do now, when it was updated, and where to get details.", "Related links are grouped inside the same alert when multiple urgent facts share one sitewide condition.", "The alert does not stack with unrelated marketing, validation, or page-flow messages.", "Dynamic emergency updates use alert semantics sparingly; advisory updates use status or labelled region semantics.", "Dismissal never hides unresolved critical conditions permanently and never suppresses newer alert versions." ], "implementationChecklist": [ "Define the alert's site scope, audience, severity, owner, start time, update cadence, expiry condition, and fallback channel.", "Place the alert in the site shell above page-specific content and test deep-linked pages, not only the home page.", "Write a short heading that names the urgent condition, such as Emergency office closures or Online applications unavailable.", "Include updated time, affected areas, immediate next step, and one stable link to more detail or alternate contact.", "Combine related sitewide facts into one list or expandable detail region instead of stacking separate alerts.", "Choose role alert only for important dynamic changes that need immediate attention; use status or labelled region for advisory updates.", "Version dismissal state by alert id, update version, audience, and site scope, and disable dismissal for unresolved critical conditions.", "Test mobile wrapping, zoom, keyboard reachability, screen-reader landmark labels, skip-link order, route transitions, cache invalidation, and resolution removal." ], "commonMisuses": [ "Showing a sitewide emergency only on the home page.", "Using a site alert for form validation, task success, local workflow feedback, or one account issue.", "Stacking multiple unrelated site alerts at the top of every page.", "Using bright emergency styling for routine announcements, newsletters, or low-impact notices.", "Letting users permanently dismiss a critical unresolved alert.", "Leaving a stale emergency alert after the condition has ended.", "Changing site-alert content mid-session without a programmatic status or alert announcement when the update is important." ], "critiqueQuestions": [ "Does this message truly apply across every affected page, including deep links?", "Is the condition urgent enough to sit above ordinary site navigation and page content?", "Should this be a site alert, a product banner, a before-H1 notification banner, a current-task alert, or an error summary?", "What single highest-priority site alert should users see right now?", "Who owns the update timestamp, expiry, alternate contact route, and resolution notice?", "Can users dismiss it safely, and what update version should make it reappear?" ], "relatedPatterns": [ "banner", "notification-banner", "alert", "error-summary", "inline-message", "toast-notification" ], "comparisons": [ "site-alert-vs-banner-vs-notification-banner-vs-alert" ], "sourceIds": [ "uswds-site-alert-component", "nci-site-alert-component", "uswds-alert-component", "wcag-status-messages" ] }, { "id": "skip-link", "completionStatus": "complete", "name": "Skip link", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Keyboard-visible bypass link to primary page content", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Keyboard and assistive-technology users can be forced through the same repeated navigation and page chrome on every page before reaching the main content.", "solution": "Provide a focusable skip link at the beginning of the page that becomes visible on focus, targets the main content start, and moves keyboard focus past repeated blocks when activated.", "uiGuidance": [ "Render a real link before repeated page chrome, usually as the first focusable control after required cookie or service banners, with destination-oriented text such as Skip to main content.", "Keep the link visually hidden until keyboard focus, then make it prominent, high-contrast, and above surrounding content so sighted keyboard users can see and activate it." ], "uxGuidance": [ "Use skip links to let keyboard, switch, screen-reader, and magnifier users bypass repeated navigation, headers, breadcrumbs, filter panels, or other repeated blocks before reaching the primary task or content.", "After activation, move focus or the browser's focus position to the main content start so the next keyboard action continues from the destination rather than returning users to the repeated block." ], "uiExamples": { "good": [ "The first Tab on a service page reveals a high-contrast Skip to main content link above the header.", "Activating the link moves focus to the H1 or main element and the next Tab reaches the first control in the content.", "A search-results page adds a second bypass link before a long repeated filter panel that jumps directly to results." ], "bad": [ "The skip link is hidden with display none and never receives keyboard focus.", "The skip link appears after the full header, search box, account menu, and navigation list.", "The link says Skip but points to a missing ID, leaving keyboard focus in the header." ] }, "uxExamples": { "good": [ "A keyboard user presses Tab once, activates Skip to main content, and reaches the page heading instead of tabbing through 18 header links.", "A screen-reader user moving across several pages avoids hearing the same service navigation before each page's unique content.", "A switch user bypasses a long filter panel and reaches the result list without dozens of repeated switch activations." ], "bad": [ "Users must tab through global navigation, service navigation, breadcrumbs, and account links on every page before content.", "A visible skip link scrolls the page but the focus order remains in the header, so the next Tab goes to Search.", "A page offers five skip links before content, forcing users to read another mini-navigation before they can start." ] }, "problemContext": [ "Pages share repeated headers, navigation, breadcrumbs, filters, service menus, banners, or advertising before the unique page content.", "Users navigate sequentially by keyboard, switch, screen reader, voice, or magnifier and cannot visually ignore repeated material as easily as mouse users.", "The page still needs structural headings and landmarks, but some users need a direct first-focus bypass control." ], "selectionRules": [ "Choose a skip link when repeated blocks appear before the primary content on pages in a site, service, product shell, or app.", "Place the primary skip link before the repeated block it bypasses, commonly immediately after the opening body tag or after required cookie or notification banners.", "Use a real anchor href that matches one unique target ID on the main content start, page H1, or equivalent first content landmark.", "Make the link keyboard focusable and prominent on focus; never hide it with display none, the hidden attribute, zero-size-only tricks, transparent-only styling, or a background-matching color.", "On activation, ensure the viewport and keyboard focus position both move to the target so subsequent Tab order continues in main content.", "Use one primary skip link in most layouts; add extra bypass links only for substantial repeated blocks such as long filters or sidebars.", "Use in-page anchor navigation for visible section contents, landmarks and headings for structural navigation, and Back links for returning to previous transaction pages.", "Retest skip links whenever layout shells, sticky headers, route transitions, or client-side rendering change the target or focus behavior." ], "requiredStates": [ "Default hidden-but-focusable state before keyboard focus.", "Focused visible state shown as the first or near-first keyboard stop.", "Activated state where viewport and keyboard focus reach the main content target.", "Repeated-block bypass state showing the number or set of navigation controls skipped.", "Broken-target state where missing or duplicate IDs are detected and fixed.", "Long repeated-block state with an additional skip link only when a filter or sidebar block is large enough to justify it." ], "interactionContract": [ "The skip link is reachable before the repeated content it bypasses.", "The link text names the destination, not only the content being skipped.", "Activating the link changes the current focus position to the intended target or a focusable proxy at the content start.", "The target remains unique, present, and not hidden by sticky headers after route changes or template changes.", "The link remains available to keyboard and assistive-technology users even when visually hidden by default.", "Skip-link activation does not submit forms, leave the page, move backward in history, or change application state beyond focus and scroll position." ], "implementationChecklist": [ "Add the skip link near the top of the document before repeated header, navigation, and breadcrumb blocks.", "Use href=\"#main-content\" or an equivalent target that exists exactly once on the page.", "Give the target an appropriate ID on main, H1, or a focusable proxy and handle focus transfer for browsers that only scroll.", "Style the link off-screen or clipped by default but visible, high contrast, and above other content on focus.", "Avoid display none, visibility hidden, hidden, opacity-only, same-color, or zero-size hiding methods that make the link inaccessible or invisible.", "Set scroll margin or focus offset so sticky headers do not cover the target.", "Test with keyboard only: first Tab reveals the link, Enter activates it, and the next Tab continues inside main content.", "Test route changes and layouts with cookie banners, service headers, sidebars, and long filters." ], "commonMisuses": [ "Placing the skip link inside the header or after the navigation it should bypass.", "Hiding the link in a way that removes it from focus order.", "Using vague text such as Skip, Next, Continue, or Jump.", "Pointing to a missing, duplicated, or visually obscured target.", "Only scrolling the viewport while keyboard focus remains in the repeated navigation.", "Adding many skip links that become another repeated navigation block.", "Treating landmarks or headings as a complete substitute when keyboard users still need a direct bypass." ], "critiqueQuestions": [ "What repeated block does this skip link bypass, and is it before that block in focus order?", "Does first Tab reveal a visible, readable link for sighted keyboard users?", "Where does focus land after activation, and what receives the next Tab?", "Is the target unique, present after client-side route changes, and clear of sticky headers?", "Would one skip link be enough, or is there a separate large repeated filter or sidebar that needs its own bypass?", "Is this being confused with same-page section navigation, breadcrumbs, or a transaction Back link?" ], "relatedPatterns": [ "in-page-anchor-navigation", "back-link", "global-navigation", "header", "side-navigation" ], "comparisons": [ "skip-link-vs-in-page-anchor-navigation-vs-back-link" ], "sourceIds": [ "govuk-skip-link-component", "w3c-wcag-bypass-blocks", "webaim-skip-navigation-links", "scottish-government-skip-link" ] }, { "id": "slider", "completionStatus": "complete", "name": "Slider", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Single-value bounded range control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to adjust one bounded value, such as volume, brightness, opacity, or intensity, where relative position matters more than typing a precise number first.", "solution": "Provide a labeled single-thumb slider with a known minimum and maximum, visible current value and unit, sensible step size, keyboard support, and an exact numeric entry path when precision matters.", "uiGuidance": [ "Render one thumb on a track with a persistent label, visible current value, unit, min and max labels, focus state, and disabled or read-only state.", "Use a native range input or fully implement slider semantics, value text, keyboard movement, and touch behavior for custom sliders." ], "uxGuidance": [ "Help users adjust one bounded value quickly when the relative position or intensity matters.", "Provide a precise number input or choose a different control when users need exact, high-stakes, pasted, or named values." ], "uiExamples": { "good": [ "A Brightness slider shows 55%, dim and bright endpoint labels, visible focus, and a paired number input.", "A discrete Volume slider uses 5% steps and shows the selected percentage near the thumb or label." ], "bad": [ "An unlabeled rail has no visible value, min, max, or unit.", "A two-stop slider is styled like a switch but lacks on/off semantics." ] }, "uxExamples": { "good": [ "A user adjusts brightness with arrow keys, types 65 in the number field, sees both controls synchronize, and gets a warning near battery-heavy values.", "A user enters 140, the value is repaired to the allowed maximum, and the interface explains the accepted value." ], "bad": [ "A user tries to enter $812.37 with a huge slider and cannot land on the exact cents.", "A user is asked to choose Small, Medium, or Large through a numeric rail with hidden labels." ] }, "problemContext": [ "The value has a known lower and upper bound.", "Users understand the answer as position, intensity, amount, or coarse adjustment along a scale.", "The product can choose meaningful step increments and expose the current value in text.", "The task controls one value, not a start and end range.", "Users may still need an exact numeric value, warning, disabled state, or server-side range repair." ], "selectionRules": [ "Choose a slider for one adjustable numeric or relative value inside a known range.", "Use a continuous slider for subjective intensity where exact value is not critical.", "Use a discrete slider when each step is meaningful and users can perceive the difference between steps.", "Pair the slider with a number input or value display when users need exactness, screen-reader clarity, or copyable values.", "Use text input when users need to type a precise, large-range, arbitrary, financial, or pasted value.", "Use select, radio group, or segmented control for a small set of named options.", "Use toggle switch for true on/off settings.", "Use range slider when users must set both a lower and upper boundary.", "Avoid sliders for very large ranges, tiny ranges, binary choices, dates, destructive actions, and values with unclear units." ], "requiredStates": [ "Initial value state with visible label, min, max, current value, and unit.", "Focused thumb state.", "Dragging or actively adjusting state.", "Keyboard increment and larger-step state.", "Discrete tick or step state when only certain values are allowed.", "Exact numeric entry state when precision is needed.", "Warning state for risky or unusual values.", "Out-of-range repaired or validation error state.", "Disabled dependency state.", "Read-only review state.", "Touch assistive technology tested state for custom implementations." ], "interactionContract": [ "Moving the thumb changes one value within the declared minimum and maximum.", "The current value remains visible in text and matches the thumb position.", "Keyboard arrows adjust by one step; Home and End move to the range limits; Page Up and Page Down may move by larger steps.", "Typed numeric fallback synchronizes with the thumb and uses the same min, max, and step rules.", "Warnings, errors, disabled state, and repaired values are announced without losing the user's context.", "The slider never hides multiple named choices, binary on/off state, or two-boundary range selection behind one thumb." ], "implementationChecklist": [ "Define min, max, step, initial value, unit, precision, and whether values are continuous or discrete.", "Use native input type range when it satisfies the design and accessibility needs.", "Provide a visible label and current value, and expose min, max, now, and value text to assistive technologies.", "Add min and max labels or icons when the endpoints are meaningful.", "Pair with a number input for exact values, large ranges, or values users may need to copy or paste.", "Clamp, reject, or repair out-of-range values with explicit feedback.", "Test keyboard, pointer, touch, screen reader, high zoom, forced colors, and mobile assistive technology behavior.", "Avoid custom slider implementations unless the thumb, track, value text, focus, keyboard, and touch behavior are fully implemented." ], "commonMisuses": [ "Using a slider for a binary on/off choice.", "Using a slider for exact financial, legal, account, or measurement values without a numeric field.", "Hiding a small set of named options behind a numeric rail.", "Using one slider for lower and upper range boundaries.", "Omitting the label, current value, unit, min, or max.", "Choosing a step size that is too fine to move efficiently or too coarse to match user needs.", "Using sliders for dates or categories that are not numeric or ordered." ], "critiqueQuestions": [ "Is this one value inside a known range?", "Do users care about relative position more than entering an exact number?", "Are min, max, step size, current value, and unit visible and programmatic?", "Would a number field, select, radio group, segmented control, toggle, or range slider make the task clearer?", "Does keyboard and touch assistive technology behavior work on the target devices?" ], "relatedPatterns": [ "text-input", "select", "toggle-switch", "input-prefix-suffix", "inline-validation" ], "comparisons": [ "slider-vs-text-input-vs-select-vs-toggle-switch" ], "sourceIds": [ "wai-aria-apg-slider", "carbon-slider-component", "uswds-range-slider-component", "material-design-sliders", "visa-slider-component" ] }, { "id": "sort-controls", "completionStatus": "complete", "name": "Sort controls", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Control for changing the order of an existing result set", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to change which relevant item appears first, but result ordering is often hidden, confused with filtering, applied only to the current page, or implemented with misleading labels and inaccessible table states.", "solution": "Provide a labelled sort control or sortable header that names the sorted attribute and direction, applies to the full current result set, preserves unrelated search and filter state, communicates the active order, and sorts formatted values by their real underlying values.", "uiGuidance": [ "Place the active sort control above or inside the result region it affects, with a visible label such as Sort by and an option name that includes both the attribute and direction.", "For table sorting, make sortable column headers visibly interactive and show the current sorted column and direction without relying on color alone." ], "uxGuidance": [ "Use sort controls when users need to rearrange the same matching results by a meaningful attribute while preserving the current search query, filters, page size, and view context.", "Apply sorting to the full result set, not only the visible page, and announce the new order or result summary when the order changes." ], "uiExamples": { "good": [ "A search results page shows Sort by with options like Relevance, Due date (oldest first), and Amount (highest first) above the results.", "A data table marks the active Due date column with a descending indicator and keeps unsorted columns visually available as sortable headers.", "A mobile list stacks the Sort by label above a full-width select while keeping active filters and result count nearby." ], "bad": [ "A menu labelled Sort contains Status: Open, Last 30 days, and Owner, which are filters rather than ordering rules.", "A table header changes row order without any active icon, aria-sort state, or result announcement.", "Sort options are labelled only Newest and A-Z when users cannot tell whether date, name, update time, or relevance is being sorted." ] }, "uxExamples": { "good": [ "A user searches for case, changes Sort by from Relevance to Due date (oldest first), and the same filtered records reorder while the query and filters remain.", "A user on page 3 changes the sort order, returns to page 1 with a clear message that the whole result set was reordered, and can page forward in the new order.", "A user sorts a table date column and gets chronological order because the implementation sorts by raw date values rather than display text." ], "bad": [ "Changing sort clears the search box and removes active filters.", "Sorting page 2 only rearranges the visible rows and leaves earlier pages in the previous order.", "Dates sort alphabetically, so 10/1/2024 appears before 2/20/2025 in a newest-first list." ] }, "problemContext": [ "The page already has a result set, list, card grid, table, inbox, history, or search result collection.", "Users can complete different tasks depending on which ordering is most useful, such as newest first, closest first, highest priority first, or alphabetical order.", "Sorting often appears near search, filters, pagination, table headers, and saved views, so the control must make clear that it changes order rather than inclusion." ], "selectionRules": [ "Choose sort controls when the same result set can be usefully ordered by two or more meaningful attributes.", "Use a separate Sort by control for search results, cards, inboxes, histories, and lists where the sortable attributes are not table column headers.", "Use sortable column headers when the sortable attribute is visible as a table column and users compare row values directly.", "Default to the order users expect for the task, such as relevance for search, newest first for activity, nearest first for location, or due soon for deadlines.", "Name each option with both the attribute and method, such as Date updated (newest first) or Amount (highest first), when a direction-only label would be ambiguous.", "Reset to the first page or clearly explain page position when the sort order changes in paginated results.", "Preserve active query, filters, page size, view density, and selected saved view when users change only the sort order.", "Use filters instead when users need to include or exclude records by status, category, date range, team, owner, or other criteria.", "Avoid sort controls when there is only one obvious order or when changing order would not help users understand or act on the list." ], "requiredStates": [ "Default sort state that identifies the initial order and why it is appropriate.", "Active sort state with visible attribute and direction.", "Alternate direction state for reversible attributes such as date, name, amount, priority, or distance.", "Loading or updating state when remote sorting takes noticeable time.", "Unavailable state when a column or option cannot sort the current data.", "Paginated state showing that the new order applies to the whole set and not only the visible page." ], "interactionContract": [ "Changing a Sort by select applies the new order to the full current result set and keeps unrelated query and filter state intact.", "Changing sort in a paginated list returns users to page 1 or announces the new page position in the reordered set.", "A sortable column header toggles between supported directions and updates the visible header state, aria-sort state, and result order together.", "Formatted numbers, dates, file sizes, percentages, and month names sort by raw comparable values rather than by display strings.", "If sorting requires a network request, keep the prior context visible while announcing that results are being reordered." ], "implementationChecklist": [ "Define the default sort attribute and direction for each result type instead of inheriting arbitrary database order.", "Write option labels that include the attribute and ordering method when there is any ambiguity.", "Keep sort controls visually separate from filters and active-filter chips.", "For table sorting, expose the active column and direction through visible icons or text and accessible state.", "Apply sorting before pagination so every page reflects the same global order.", "Use raw sortable values for dates, currencies, percentages, file sizes, and localized labels.", "Announce result order changes in a stable status region or result summary.", "Preserve query, filters, page size, selected view, and view density across sort changes." ], "commonMisuses": [ "Putting filtering criteria such as date ranges, status, category, or owner inside a sort menu.", "Labelling options only Newest, Oldest, A-Z, or Z-A when the attribute being sorted is unclear.", "Sorting only the current visible page instead of the full result set.", "Resetting search query, filters, page size, or view density when users change sort.", "Sorting formatted dates, money, month names, or percentages as plain text.", "Using a segmented control for many sort options or long option labels that need a labelled select." ], "critiqueQuestions": [ "Can users tell what attribute is sorted and in which direction?", "Does the sort change the order of the same records, or is it accidentally filtering membership?", "Does the sort apply before pagination and preserve query, filters, page size, and saved view?", "If this is a table, are sortable headers visible, keyboard reachable, and exposed with current sort state?", "Are dates, numbers, currencies, percentages, and localized labels sorted by raw values rather than display strings?", "Does the result summary or live region announce the changed order without moving focus unexpectedly?" ], "relatedPatterns": [ "filter-chips", "filter-panel", "basic-search", "pagination", "segmented-control", "select", "no-results-recovery" ], "comparisons": [ "sort-controls-vs-filter-chips-vs-filter-panel-vs-pagination" ], "sourceIds": [ "va-sort-component", "uswds-table-component", "carbon-data-table-component", "maersk-table-component" ] }, { "id": "source-grounding-display", "completionStatus": "complete", "name": "Source grounding display", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Whole-answer source coverage and grounding evidence display", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI answers can appear grounded because they contain citations or source links, while the answer as a whole may include unsupported claims, stale sources, unsearched source scopes, permission gaps, or retrieved material that was not actually used.", "solution": "Show answer-wide grounding coverage with source scope, retrieval status, used evidence, unsupported or partially supported claims, and unresolved source states so users can assess evidence before acting.", "uiGuidance": [ "Render source grounding as an answer-wide evidence panel that separates source scope, searched sources, retrieved sources, used sources, supported claims, partially supported claims, unsupported claims, and unresolved source states.", "Use explicit labels for grounded, partially grounded, unsupported, not searched, stale, missing, permission-limited, and retrieval-failed states so a cited answer does not imply full source support." ], "uxGuidance": [ "Use source grounding display when users need to judge whether an AI answer is backed by the right body of evidence, not merely open one citation.", "Let users inspect coverage gaps, source scope, retrieval status, and unsupported claims before they copy, publish, apply, or rely on the answer." ], "uiExamples": { "good": [ "A policy answer includes a Grounding panel showing 4 sources searched, 3 retrieved, 2 used, 5 supported claims, 1 partially supported claim, and 1 unsupported claim with a Review action.", "A support assistant shows Source scope: Help center and release notes, marks one source permission-limited, and labels a pricing claim as No supporting source found." ], "bad": [ "The answer shows a green Grounded badge even though only one citation supports one paragraph.", "The UI lists ten retrieved documents under Sources but never identifies which sources were used or which claims lack support." ] }, "uxExamples": { "good": [ "A reviewer opens the grounding panel, sees that the answer used the current policy but not the outdated FAQ, and flags one unsupported claim before publishing.", "During streaming, source coverage remains Pending until retrieval settles, then the answer shows which sections are grounded, partially grounded, and not found." ], "bad": [ "A user trusts a generated answer because the product says Grounded, but the source scope was only web search and did not include internal policy.", "A permission-limited source is silently omitted, so the answer looks complete even though the system could not inspect the required document." ] }, "problemContext": [ "Grounding can involve web search, file search, vector-store retrieval, enterprise knowledge sources, user-uploaded documents, selected topic sources, or policy-controlled source access.", "Retrieved sources are not always used in the final answer, and cited claims may not cover every answer claim.", "A source can be stale, permission-limited, missing, not searched, low quality, outside the selected scope, or inconsistent with another source.", "Grounding display often appears inside chat, streaming answers, research workspaces, review queues, document editors, and support-agent answer panels.", "Users need to know source coverage before applying generated output to legal, policy, medical, financial, operational, or customer-facing decisions." ], "selectionRules": [ "Choose source grounding display when users need answer-wide evidence coverage, source scope, retrieved-versus-used source status, or unsupported-claim visibility.", "Use citation display when the task is inspecting one claim's citation marker and source preview.", "Use chat interface when the task is managing conversation turns, history, composer behavior, or follow-up context.", "Use streaming response when the task is exposing partial generated output and response lifecycle while text arrives.", "Use related links when destinations are optional onward navigation and not evidence used by the answer.", "Show grounding scope before or beside the answer when source selection materially changes what the answer can prove.", "Show unsupported and partially supported claims when the answer contains claims that are not fully backed by retrieved evidence.", "Do not show a global grounded badge unless all claim-support rules, source scope rules, permissions, and freshness checks used by the product are satisfied.", "Do not replace grounding coverage with a single confidence, quality, or trust score." ], "requiredStates": [ "Default grounded state with source scope, searched sources, retrieved sources, used sources, and supported-claim count.", "Partially grounded state with at least one partially supported claim and explanation.", "Unsupported claim state with claim text, no supporting source found label, and review or regenerate action.", "Pending grounding state while retrieval, web search, file search, or source matching is still resolving.", "Not searched or out-of-scope state when a source corpus was excluded by settings, topic, policy, or user choice.", "Permission-limited source state where a source exists but cannot be opened or quoted by the current user.", "Stale, missing, retrieval failed, conflicting source, and source quality warning states.", "Mobile collapsed grounding panel state that preserves answer position and source coverage counts." ], "interactionContract": [ "The grounding display names the source scope that was available for this answer, not just sources the user might expect.", "Searched, retrieved, used, cited, and unused sources are visually and textually distinct.", "Each unsupported or partially supported claim can be located in the answer and connected to the relevant source status.", "Regeneration, source-scope changes, document updates, permission changes, and answer edits invalidate or re-run grounding status.", "Copy, apply, publish, and export actions can include grounding status or warn when unsupported claims remain.", "Permission-limited sources explain what is hidden without leaking protected excerpts.", "Keyboard and touch users can open grounding coverage, inspect source groups, jump to claims, and return to the answer without losing context.", "Grounding status changes are announced as meaningful status messages without moving focus unexpectedly." ], "implementationChecklist": [ "Model source scope, retrieval calls, searched sources, retrieved sources, used sources, cited sources, unsupported claims, partial support, conflicts, permissions, freshness, and grounding status as separate structured data.", "Track the answer text or claim ranges that each grounding status applies to, and update them after regeneration or editing.", "Render source groups for searched, retrieved, used, unused, permission-limited, stale, missing, and conflicting sources.", "Expose unsupported and partially supported claims with jump-to-claim, review, regenerate, change source scope, and report issue actions.", "Show pending grounding during streaming and only mark answer-wide coverage after source matching and final text settle.", "Preserve selected claim, source group, panel state, focus, and scroll when users expand or collapse the grounding display.", "Test no sources, too many sources, stale sources, private sources, conflicting sources, no supporting source, changed source scope, regenerated answer, mobile layout, high zoom, keyboard, and screen reader paths." ], "commonMisuses": [ "Showing a global Grounded badge when only some claims have evidence.", "Mixing searched, retrieved, used, and related sources into one undifferentiated list.", "Hiding unsupported claims because some citations exist elsewhere in the answer.", "Treating grounding as a confidence score instead of evidence coverage.", "Omitting source scope so users do not know which corpus was searched.", "Making permission-limited sources disappear instead of explaining the access gap.", "Showing source coverage only after users already copied or applied the answer." ], "critiqueQuestions": [ "Can users tell which source scope was searched for this answer?", "Can users distinguish searched, retrieved, used, cited, unused, missing, stale, and permission-limited sources?", "Which claims are unsupported or only partially supported, and can users jump to them?", "What invalidates grounding status after regeneration, editing, source updates, or permission changes?", "Does the UI avoid turning grounding into a single confidence score?", "Would citation display, chat interface, streaming response, related links, or a data visualization solve the actual task better?" ], "relatedPatterns": [ "citation-display", "chat-interface", "streaming-response", "related-links", "data-visualization", "review-before-submit" ], "comparisons": [ "source-grounding-display-vs-citation-display-vs-chat-interface-vs-streaming-response-vs-related-links" ], "sourceIds": [ "openai-retrieval", "openai-file-search-citations", "openai-web-search-citations", "microsoft-copilot-studio-knowledge-sources", "microsoft-copilot-studio-generative-answers", "microsoft-365-copilot-web-references", "wcag-status-messages" ] }, { "id": "spinbutton", "completionStatus": "complete", "name": "Spinbutton / numeric stepper", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Bounded incrementable numeric-value control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to adjust a small bounded numeric quantity, but plain text fields hide allowed increments while sliders and selects either lose exact entry or imply the wrong kind of choice.", "solution": "Provide a labelled editable numeric value with explicit increment and decrement controls, declared min, max, step, unit, keyboard movement, direct typing, validation, and repair feedback.", "uiGuidance": [ "Render a visible label, editable numeric value, unit, lower and upper bounds, plus and minus controls, focus state, and warning, error, disabled, and read-only states.", "Keep the value field directly editable and expose min, max, now, step, invalid state, and human-readable value text when the raw number alone is ambiguous." ], "uxGuidance": [ "Use a spinbutton when users adjust a small count or bounded quantity by one or a few steps and still may need to type the exact number.", "Repair or reject values outside bounds with local feedback, and avoid stepping numbers that behave as identifiers, codes, dates, phone numbers, or high-precision amounts." ], "uiExamples": { "good": [ "A Guests control shows label, value 2, minus and plus buttons, range 0 to 9, and a clear unit beside the field.", "A Copies field lets the user type 12, use arrow keys for one-copy changes, and use Page Up for a larger supported jump." ], "bad": [ "An account ID field has plus and minus buttons, implying the identifier can be stepped.", "A quantity stepper shows only icons and the number 3 with no label, unit, min, max, or disabled-bound explanation." ] }, "uxExamples": { "good": [ "A user adds one guest, types 7, clears the required field, then sees a specific error and restores a valid count without losing context.", "A user enters -3 for guests, the value is repaired to 0, and the interface explains the lower bound before submit." ], "bad": [ "A user tries to set 480 items with one-step buttons and cannot type or jump by larger increments.", "A user scrolls a page while an account number field is focused and accidentally changes the stored account ID." ] }, "problemContext": [ "The value is a real number or count that can be incremented or decremented.", "Most changes are small, such as adding one guest, copy, item, seat, day, night, or minute.", "The product knows the lower bound, upper bound, step size, unit, and default.", "Users may need to type the number directly instead of repeatedly pressing buttons.", "Some numeric-looking values must remain strings and should not become spinbuttons." ], "selectionRules": [ "Choose a spinbutton for one bounded numeric value that changes in predictable increments.", "Use it when a default such as 0 or 1 is meaningful and most users make only a few adjustments.", "Provide direct typing whenever the range has more than a handful of steps or users may already know the exact value.", "Use slider when relative position across a wider range matters more than repeated count changes.", "Use range slider when users set both lower and upper boundaries.", "Use text input for arbitrary numbers, pasted values, precise decimals, financial amounts, or numeric-looking identifiers.", "Use select, radio, or segmented controls for named options that should be compared as labels.", "Avoid spinbuttons for account numbers, payment cards, verification codes, postal codes, phone numbers, dates, and other strings that merely contain digits." ], "requiredStates": [ "Initial state with visible label, default value, unit, min, max, and step.", "Focused value field state.", "Increment and decrement button hover, focus, pressed, and disabled-at-bound states.", "Direct typed valid value state.", "Required empty value state.", "Below-minimum and above-maximum repair or error states.", "Non-step value repair state when the typed value falls between allowed increments.", "Large-step keyboard state when Page Up and Page Down are supported.", "Disabled dependency state with explanation.", "Read-only review state that remains readable and programmatically exposed." ], "interactionContract": [ "Increment and decrement controls change the value by the declared step and stop at the lower and upper bounds.", "The editable field accepts direct numeric entry and preserves standard text-editing behavior.", "Up Arrow and Down Arrow move by one step; Home and End move to known bounds when supported; Page Up and Page Down move by a documented larger step when present.", "Min, max, step, value, unit, and invalid state stay synchronized between visual controls, programmatic state, and submitted value.", "Out-of-range, empty, and non-step values are rejected or repaired with visible feedback before submission.", "Disabled and read-only states explain whether the quantity is unavailable or only reviewable." ], "implementationChecklist": [ "Confirm the value is incrementable, not a numeric string identifier.", "Define min, max, step, default, unit, decimal precision, large-step behavior, and whether immediate commit or form submit applies.", "Use a native number input or implement spinbutton roles and value attributes only when native behavior is insufficient.", "Label the field and give plus and minus controls names that include the affected quantity.", "Keep direct text entry, paste, selection, undo, and keyboard editing available unless the target platform explicitly supports a button-only stepper.", "Disable the minus button at the minimum and the plus button at the maximum without disabling the whole field unnecessarily.", "Validate on blur or submit, clamp only with explanation, and run the same checks server-side.", "Test keyboard, pointer, touch, screen reader, high zoom, forced colors, locale decimal entry, disabled, read-only, and mobile numeric keyboard behavior." ], "commonMisuses": [ "Using a spinbutton for numeric-looking identifiers or codes.", "Using one-step buttons for a large range without direct typing or larger-step movement.", "Omitting the label, unit, min, max, default, or current value.", "Providing plus and minus buttons with accessible names that do not identify the quantity.", "Silently rounding decimals or repairing invalid values without telling the user.", "Disabling the whole control when only one direction is unavailable at a bound.", "Using a workflow stepper or progress indicator when the task needs a numeric value control." ], "critiqueQuestions": [ "Is the value actually incrementable, or is it a string made of digits?", "Will most users change the default by only a few steps?", "Can users type the exact value, paste, undo, and recover from errors?", "Are the min, max, step, unit, current value, and disabled-bound states visible and programmatic?", "Would a slider, range slider, text input, select, or workflow step navigation communicate the job more clearly?" ], "relatedPatterns": [ "slider", "range-slider", "text-input", "select", "input-prefix-suffix", "inline-validation", "step-navigation" ], "comparisons": [ "spinbutton-vs-slider-vs-text-input-vs-select" ], "sourceIds": [ "wai-aria-apg-spinbutton", "carbon-number-input-component", "react-spectrum-numberfield", "mdn-input-number", "govuk-number-input-guidance" ] }, { "id": "start-page", "completionStatus": "complete", "name": "Start page", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Single-service or single-task entry point before a transaction begins", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need a trustworthy entry point for a specific service or task, but without pre-start context they may begin the wrong service, lack required documents, miss costs or eligibility, or fail to recover an existing draft.", "solution": "Provide a focused start page that names the service in user language, explains what it does, who it is for, what users need, what will happen, how long it may take, how to start, how to resume, and what alternatives exist when the service is not right for them.", "uiGuidance": [ "Render the service or task name, short purpose statement, who can use it, what users need, outcome expectation, time or cost where relevant, one primary start action, resume or sign-in route when relevant, and other access routes in a narrow readable page.", "Keep the primary start action visually dominant and put essential pre-start information above it; place optional context, related guidance, and alternative channels below or beside the main path without making them peer calls to action." ], "uxGuidance": [ "Use a start page to help users decide whether they are in the right place and begin a specific service with the right materials, expectations, and recovery routes.", "Keep the page focused on starting the service; move complex eligibility, branching, identity proof, payment, and multi-step progress into the appropriate downstream flow." ], "uiExamples": { "good": [ "A permit application start page states who can apply, the fee, the estimated time, required documents, what happens after submission, a Start now button, and a Resume application link.", "A health-service start page explains the result users will receive, lists information needed before starting, shows a single Start now button, and provides phone access for users who cannot complete the service online." ], "bad": [ "A page titled Start contains a hero carousel, five equal buttons, news cards, and no clear transaction entry point.", "A start page puts required identity documents and fees below the button where most users do not see them before beginning." ] }, "uxExamples": { "good": [ "A user checks that they live in the eligible region, sees they need a reference number and 10 minutes, starts the service, and returns later through Resume application without losing their draft.", "A user arriving from search realizes the service is not for their situation and follows a clearly labeled alternative route before entering the transaction." ], "bad": [ "A user clicks Start now, answers four pages, and only then learns they needed a document that was not mentioned on the start page.", "A returning user who already started must begin again because the entry page has no sign-in, resume, or draft recovery path." ] }, "problemContext": [ "A service, application, booking, check, registration, or request begins after the user clicks a primary start action.", "Users may arrive from search, navigation, email, or another guidance page and need confidence that this is the correct entry point.", "Most users need to know eligibility, required information, documents, costs, time, outcome, or alternative channels before they start.", "Some users may have already started and need to resume rather than create a duplicate transaction.", "The service sits inside a wider information architecture, topic, product, or public website where users need a route back if this task is not for them." ], "selectionRules": [ "Choose a start page when one named service or transaction needs a focused entry point before the first question, form, booking, payment, or authenticated step.", "Use one primary start action with action-specific text such as Start now, Apply now, Book now, Sign in, or Register or update details.", "Provide resume, sign-in, or update routes when returning users can continue an existing application or manage an existing record.", "List only information most users need before starting, such as documents, cost, time, account requirements, region, outcome, or service availability.", "Move complex eligibility checks into the service flow; keep only short eligibility cues or alternative routes on the start page.", "Use browse by category when users still need to choose among many services or topics.", "Use onboarding when users need first-use product activation or teaching rather than a transaction entry point.", "Use step navigation when the user must complete several guidance or transaction tasks in a known order across a wider journey.", "Use service navigation, breadcrumbs, related links, or search to situate the start page, but keep those recovery routes secondary to the start action." ], "requiredStates": [ "Default entry state with service name, purpose, user fit, pre-start requirements, expected outcome, and primary start action.", "Returning-user state with sign-in, resume, or update route distinct from the new-start action.", "Not-for-you state with concise exclusion or alternative route when a common wrong audience arrives.", "Before-you-start state listing documents, account details, time, cost, consent, or device needs that most users must know.", "Alternative access state for phone, paper, assisted digital, offline, or delegated access when available.", "Unavailable or paused state explaining when the service cannot be started and where to go instead.", "Mobile state where the service name, essential requirements, and start action remain visible without burying the needed information." ], "interactionContract": [ "The primary start action moves users into the first service step and does not jump to unrelated marketing, category browsing, or account dashboards.", "Resume or sign-in actions return users to their existing draft, application, account, or record without creating a duplicate transaction.", "Eligibility and requirement text on the start page matches the downstream service validation and business rules.", "Essential information needed before starting appears before the start action or is clearly reachable before commitment.", "Alternative routes explain who should use them and preserve the user's task context where possible.", "Deep-linked users can identify the service, surrounding topic, and route back through breadcrumbs, service navigation, or related links.", "Starting the service sets focus on the first question, form heading, or authenticated step with the service context intact." ], "implementationChecklist": [ "Define the service name, first service step, primary start action text, returning-user route, and destination before writing the page.", "Inventory the information most users need before starting: documents, identifiers, time, cost, eligibility, account, device, region, outcome, and alternatives.", "Decide which information belongs above the start action, below it, in a separate before-you-start page, or inside the transaction.", "Keep surrounding navigation, breadcrumbs, search, and related links available without competing with the primary start action.", "Verify the start page language matches search terms, support questions, and the downstream service name.", "Test new, returning, ineligible, assisted, mobile, keyboard, screen reader, deep-linked, translated-label, and service-unavailable states.", "Instrument start, resume, wrong-service exit, downstream abandonment, and missing-document errors to see whether the start page is setting expectations correctly." ], "commonMisuses": [ "Treating a product homepage, marketing landing page, or category directory as a start page for a specific service.", "Showing several equal calls to action when one service start action should be primary.", "Hiding documents, costs, account requirements, or outcome expectations after the start action.", "Using the start page for long eligibility questionnaires that belong inside the service.", "Making returning users restart because resume or sign-in is absent or visually hidden.", "Disconnecting the page from the wider information architecture so wrong arrivals hit a dead end.", "Changing the start button label to a vague phrase that does not match the action users are about to take." ], "critiqueQuestions": [ "Can a search-arriving user tell whether this is the right service before clicking the start action?", "What must most users know before they begin, and is that information visible before commitment?", "Is there exactly one primary start action, and does its label match the next service step?", "What does a returning user do if they already started?", "Which common wrong users need an alternative route before they enter the service?", "Would browse by category, onboarding, step navigation, question page, or wizard be more accurate?" ], "relatedPatterns": [ "onboarding", "browse-by-category", "step-navigation", "service-navigation", "breadcrumbs" ], "comparisons": [ "start-page-vs-onboarding-vs-browse-by-category-vs-step-navigation" ], "sourceIds": [ "govuk-start-using-service", "nhs-start-page-pattern", "nng-homepage-design-principles", "nng-homepage-usability-guidelines", "govuk-step-by-step-navigation" ] }, { "id": "step-navigation", "completionStatus": "complete", "name": "Step navigation / step indicator", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Linear multistep task progress indicator", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users completing a long task across multiple screens need to understand their current position, what is already complete, and what remains without confusing progress with hierarchy or result paging.", "solution": "Provide a source-backed step indicator for linear tasks with three or more meaningful steps, validated completion states, a matching step heading, and separate Back and Continue controls that preserve entered data.", "uiGuidance": [ "Show a compact ordered list of named steps near the task heading, with visually distinct completed, current, upcoming, optional, and error states.", "Keep labels short and task-specific; pair the indicator with an explicit step heading such as 'Step 2 of 5: Contact details' rather than relying on the strip alone." ], "uxGuidance": [ "Use step navigation to reduce uncertainty in long linear tasks by showing where users are, what is done, and what remains.", "Treat completion as validated task progress, not page visitation; keep Back and Continue controls separate and preserve answers when users revisit completed steps." ], "uiExamples": { "good": [ "A five-step application shows Eligibility complete, Contact details current, Documents upcoming, Review upcoming, and Submit upcoming, with the current step emphasized and a matching page heading.", "A checkout uses short labels such as Cart, Shipping, Payment, Review, and Confirmation with a visible error marker only on the invalid Payment step.", "A vertical progress indicator in a side panel shows completed checkmarks, current half-filled marker, optional helper text, and future steps in lower emphasis." ], "bad": [ "A two-page form adds a large stepper that consumes space without explaining meaningful progress.", "All future steps look clickable and complete even though required earlier fields are blank.", "A breadcrumb trail for Home, Benefits, Apply, and Contact is styled as a stepper, confusing hierarchy with task progress." ] }, "uxExamples": { "good": [ "After a user enters valid contact details and continues, Contact details becomes complete and Documents becomes current.", "A user returns to a completed step, edits an answer, and the later Review step updates without clearing unrelated data.", "An invalid upload marks Documents with an error state and keeps the user on that step until the issue is fixed." ], "bad": [ "Clicking Review skips Documents, clears the contact form, and then blocks final submission without explaining the skipped prerequisite.", "The indicator says Step 4 of 5 while the page content and route still show Step 2.", "A conditional journey inserts a new step after users start, making the fixed step count wrong." ] }, "problemContext": [ "The task spans several screens and users may worry about how much work remains.", "The steps have a stable order that can be explained before or during the task.", "Users must complete or validate information before moving safely to later steps." ], "selectionRules": [ "Choose step navigation when a form, checkout, onboarding, or application has three or more high-level linear steps.", "Use it to communicate completed, current, upcoming, optional, and error states; do not use it as ordinary site navigation.", "Show the current step in the indicator and in the page heading, and keep those labels synchronized with the route or task state.", "Keep Back and Continue controls separate from the indicator unless the product deliberately supports interactive step navigation.", "Allow navigation to completed steps only when previous data can be preserved and revisited safely.", "Lock, disable, or explain future steps until prerequisites are complete; never let users skip required validation silently.", "Avoid a step indicator for fewer than three steps, nonlinear tasks, highly conditional step counts, or same-page content sections.", "Use a task list or process list when users need a detailed overview of many tasks that can be completed out of order." ], "requiredStates": [ "Default state with completed, current, and upcoming steps.", "Current step heading with step number and total step count.", "Validated completion state after the user successfully continues.", "Future step blocked or unavailable state before prerequisites are met.", "Completed step revisit state with previous answers preserved.", "Error state on the affected step when validation fails.", "Responsive compact state with labels shortened or counters used when space is limited." ], "interactionContract": [ "The current indicator segment always matches the visible page, route, and task heading.", "A step becomes complete only after required information for that step is valid or saved.", "Back and Continue move through the linear journey and preserve previously entered answers where valid.", "Completed steps may be revisited if the product supports editing; future steps remain unavailable until prerequisites are satisfied.", "Optional steps are labeled as optional and do not block progress when skipped.", "If a step has an error, the indicator shows the error state and the page provides field-level or inline recovery guidance." ], "implementationChecklist": [ "Model steps as task milestones with stable IDs, labels, route ownership, prerequisites, completion status, and optional or error metadata.", "Render the indicator near the task heading and include a text heading that states the current step number, total, and label.", "Use semantic ordered-list or equivalent step semantics, and apply aria-current to the current labeled step.", "Validate the current step before marking it complete or unlocking later steps.", "Preserve answers when users go back or revisit completed steps, and recompute downstream status when earlier answers change.", "Keep labels short, responsive, and readable; use counters or omitted labels only when the heading still communicates the current step.", "Test keyboard operation, focus order, visible focus, screen reader status text, and mobile wrapping." ], "commonMisuses": [ "Using a step indicator as breadcrumbs, tabs, side navigation, or pagination.", "Marking steps complete because they were visited rather than validated.", "Letting users jump to unavailable future steps without saved prerequisites.", "Showing a fixed step count for a journey whose steps change based on answers.", "Hiding the actual page heading and expecting the indicator to serve as the only title.", "Using vague labels such as Details, More, Next, or Processing that do not explain what the step accomplishes." ], "critiqueQuestions": [ "Are these stable task milestones, or are they hierarchy pages, result pages, or same-page sections?", "What proof marks a step complete, and what happens if a completed answer changes later?", "Can the user revisit completed steps without losing data or invalidating hidden downstream answers?", "Will future-step links be locked, explained, or removed until prerequisites are complete?", "Does the current route, heading, and indicator all name the same step?" ], "relatedPatterns": [ "back-link", "pagination", "breadcrumbs", "in-page-anchor-navigation" ], "comparisons": [ "step-navigation-vs-back-link-vs-pagination" ], "sourceIds": [ "uswds-step-indicator-component", "carbon-progress-indicator-component", "material-design-steppers-component" ] }, { "id": "step-progress", "completionStatus": "complete", "name": "Step progress", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Workflow-stage status indicator", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users in a workflow can lose track of which named stages are accepted, blocked, waiting, skipped, or failed when a simple current page label hides status changes that happen after validation, upload, review, or system checks.", "solution": "Render a step progress indicator that reports the current workflow-stage status from authoritative state, labels every non-default state, identifies the current step with step semantics, explains blocked or failed stages, and updates only when the underlying proof event changes.", "uiGuidance": [ "Show a compact ordered status readout for named stages with distinct completed, current, pending, blocked, skipped, waiting, and failed treatments that include text or icon cues beyond color.", "Pair the visual step strip with a nearby status sentence such as Step 3 of 6, Documents waiting for review, so compact or icon-only variants still communicate the current stage." ], "uxGuidance": [ "Use step progress when users need to monitor how a workflow is advancing across named stages and which proof event changed each stage, especially when some stages depend on validation, review, upload, or approval.", "Keep stage status synchronized with saved data and backend events; never treat visiting a step, scrolling past a section, or clicking Next as completion unless the required work was accepted." ], "uiExamples": { "good": [ "An onboarding status strip shows Profile completed, Documents current, Compliance waiting, Review blocked, and Finish locked with text labels for each state.", "A checkout side rail marks Shipping saved, Payment failed, Review not available, and Confirmation pending while the page heading says Step 3 of 5: Payment.", "A mobile compact header says 2 of 6 complete, current step Documents, next Compliance check, with an All steps button for the full list." ], "bad": [ "All visited steps turn green even though required documents failed server validation.", "Future segments look like active buttons but do nothing or silently jump over prerequisites.", "A five-stage application is replaced by a 60% bar, hiding that Background check is waiting and Review is blocked." ] }, "uxExamples": { "good": [ "After the user uploads a document, Documents changes to Waiting for review instead of Complete until the file scan and reviewer check pass.", "A dependent Tax details step appears only after the user selects self-employed and is announced as an inserted required step without making earlier counts look wrong.", "A failed Payment stage keeps the user on the payment route, exposes Retry card authorization, and prevents Review from appearing available." ], "bad": [ "The step progress says Review ready while the address step contains unsaved edits that would change shipping tax.", "A skipped optional step is hidden from the sequence, so users cannot tell why the total count changed.", "Screen reader users hear only current page text and never receive the failed, blocked, or waiting status shown in the strip." ] }, "problemContext": [ "The workflow has named stages whose statuses matter independently of the current page.", "Some stages may wait on validation, document review, payment authorization, eligibility checks, approval, or background processing.", "Users may return later and need a snapshot of what is done, what is current, what is blocked, and what cannot start yet.", "The product may show the indicator inside a broader form, wizard, checkout, import, onboarding, or approval flow without making the indicator own the whole flow." ], "selectionRules": [ "Choose step progress when users need status for named workflow stages, not only a route position.", "Mark a stage complete only after saved data, accepted upload, passed validation, approved review, or another defined proof event exists.", "Use waiting status when a stage is in progress outside the current page, such as document scan, compliance review, payment authorization, or approval.", "Use blocked or cannot-start status when a future stage depends on a prior answer, upload, permission, or system check, and provide the reason nearby.", "Use skipped status for optional or inapplicable stages so users can distinguish deliberate omission from missing work.", "Use failed status on the stage that owns the failure and keep recovery actions close to the failed stage or current page.", "Use step navigation when the indicator is primarily how users move between pages in a linear journey.", "Use progress bar when the underlying progress is numeric system work with a reliable total.", "Use meter when users need to interpret a current value inside a bounded range.", "Avoid fixed totals when dependent stages can appear or disappear; disclose inserted stages or show required versus optional groups." ], "requiredStates": [ "Not started or pending stage.", "Current stage with aria-current step or equivalent current-step semantics.", "Completed stage with the proof event reflected in text.", "Waiting stage for review, scan, authorization, approval, or another external event.", "Blocked or cannot-start stage with a visible reason.", "Failed stage with recovery route or retry action.", "Skipped or not-applicable stage for deliberate omissions.", "Dynamic dependent stage inserted after a qualifying answer.", "Compact responsive state that preserves current step and total or remaining context." ], "interactionContract": [ "The indicator reads from the same workflow state that controls route availability, validation, saved answers, and submission gates.", "Only one step is current at a time and the current item is exposed with current-step semantics.", "Completed stages retain enough text to explain what proof made them complete, such as Saved, Accepted, Approved, or Authorized.", "Blocked and failed stages expose the reason and recovery path instead of relying on a red segment alone.", "If the indicator is read-only, segments do not look clickable; if segments are navigable, unavailable stages explain why they cannot open.", "Dynamic or conditional stages do not silently rewrite history; newly required stages are introduced with text that explains why they appeared.", "Status changes are announced at meaningful transitions such as failed, ready, waiting, unblocked, or complete." ], "implementationChecklist": [ "Define each stage ID, label, status vocabulary, proof event, owning route, recovery action, and dependency before rendering the indicator.", "Represent steps as an ordered list or equivalent semantic structure and expose the current step with aria-current=\"step\" when appropriate.", "Keep the current step label, page heading, saved state, and route state synchronized after every Continue, Back, retry, upload, review, and background event.", "Pair icons and colors with text labels such as Complete, Current, Waiting, Blocked, Failed, Skipped, or Cannot start yet.", "Make read-only segments visually noninteractive, or implement keyboard focus and activation only for stages that users can actually open.", "Handle conditional stages by grouping them, inserting them with a reason, or excluding them from the total until they are required.", "Test revisiting after refresh, failed server validation, asynchronous completion, optional-stage skipping, inserted dependent stages, narrow layouts, keyboard traversal, and screen-reader announcements." ], "commonMisuses": [ "Treating visited pages as completed stages.", "Using the indicator as the only page heading or only explanation of current status.", "Showing all future stages as clickable when prerequisites are missing.", "Hiding blocked, waiting, skipped, or failed states behind color alone.", "Using a percent progress bar for named workflow stages.", "Changing the total number of steps without explaining the dependent condition.", "Letting the visual step status drift from saved answers, server validation, or route state." ], "critiqueQuestions": [ "What event proves each stage is complete?", "Is this indicator reporting status, enabling navigation, or trying to do both?", "Which stage owns each validation error, failed check, waiting review, and retry action?", "Can users tell the difference between pending, blocked, waiting, skipped, and failed without color?", "How will conditional stages appear without making the total feel dishonest?", "Does the page heading, route, focus target, and current-step status all identify the same stage?" ], "relatedPatterns": [ "step-navigation", "progress-bar", "meter", "multi-step-form", "wizard", "process-list" ], "comparisons": [ "step-progress-vs-step-navigation-vs-progress-bar-vs-meter" ], "sourceIds": [ "uswds-step-indicator-component", "carbon-progress-indicator-component", "agds-progress-indicator-accessibility", "mdn-aria-current", "sap-fiori-android-step-progress-indicator" ] }, { "id": "streaming-response", "completionStatus": "complete", "name": "Streaming response", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Incremental generated-output surface that renders response chunks before final completion", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "Streaming generated output can reduce perceived wait time, but partial text is not necessarily final, cited, safe, valid, or complete. Without explicit stream states and recovery, users may trust unfinished output, lose partial work after interruption, or be overwhelmed by constant visual and assistive updates.", "solution": "Show streaming as a distinct response lifecycle with receiving, first output, partial, stalled, stopped, failed, continued, and complete states; keep partial and final content visually distinct; preserve recoverable output; and gate risky actions until final checks are done.", "uiGuidance": [ "Render streamed output with a visible generation state, partial-answer label, stop control, final-complete state, and clear distinction between text that is still arriving and content that has passed final citation, safety, tool, or format checks.", "Use stable containers for partial text, pending citations, tool-call progress, structured chunks, copy controls, and final metadata so new deltas do not shift controls or make early output look finished." ], "uxGuidance": [ "Use a streaming response when showing partial generated output helps users start reading or monitoring work before the model finishes, and when the product can explain that early chunks may still change, be filtered, or lack final sources.", "Protect users from acting on unfinished output by preserving partial content on interruption, labelling stopped or failed streams, exposing continue or retry, and delaying copy, publish, apply, citation trust, or structured export until the stream reaches a valid terminal state when risk requires it." ], "uiExamples": { "good": [ "A policy assistant shows Answer generating, streams paragraphs into a stable answer region, marks citations pending, exposes Stop generation, then changes to Complete when citations and safety checks finish.", "A code assistant streams a function body inside a code block, keeps Copy disabled until the closing fence and final lint status arrive, and shows Continue after a network interruption." ], "bad": [ "A generated answer appears word by word with no partial label, no stop control, and a Copy button that looks ready before sources arrive.", "A streaming JSON answer is displayed as valid data before the closing braces and schema check have completed." ] }, "uxExamples": { "good": [ "A user sees the first-token state quickly, reads early outline bullets while the answer continues, stops generation after enough detail, and sees the result labelled Partial with Continue and Regenerate options.", "A source-grounded answer streams text immediately but keeps citation chips in Pending until retrieval events resolve, then marks which claims are sourced." ], "bad": [ "A user copies an early legal recommendation before the final paragraph reverses the conclusion after a tool result arrives.", "A stalled event stream leaves a blinking cursor forever and gives no timeout, retry, copy partial, or discard path." ] }, "problemContext": [ "The system may emit output deltas, message events, tool-call events, citation events, moderation events, usage metadata, and final completion events at different times.", "Text, Markdown, tables, JSON, code, citations, and generated files may be invalid or incomplete until the stream closes cleanly.", "Users may want to start reading, stop when enough information arrives, continue after stopping, retry after network failure, copy partial output, or wait for final source verification.", "Streaming can happen inside a chat interface, side panel, document editor, code assistant, workflow run, voice transcript, or background job detail surface.", "Accessibility, reduced motion, mobile scroll, text selection, virtualized transcripts, and screen reader announcement rate all affect whether streaming is usable." ], "selectionRules": [ "Choose streaming response when partial generated output is useful before the full answer is ready and the product can explain partial versus final state.", "Use chat interface when the design problem is the broader conversation transcript, history, turns, and composer rather than one active response lifecycle.", "Use progress bar when the system reports measurable operation completion instead of readable generated output.", "Use loading spinner when the wait is short and neither partial output nor measurable progress can be shown.", "Use feed when users browse finished chronological items rather than watch one answer being generated.", "Delay apply, publish, commit, structured export, final citation trust, and high-risk copy actions until the stream reaches a verified terminal state.", "Show Stop generation when stopping is technically possible and the partial answer can be preserved or explicitly discarded.", "Show Continue or Retry when a stream stops, stalls, times out, or fails while useful partial output remains.", "Use a pending source or pending tool state when text arrives before citations, retrieval, function output, or safety checks.", "Do not stream raw chunks if they will expose unsafe intermediate content, broken syntax, misleading partial conclusions, or private tool data." ], "requiredStates": [ "Queued or receiving state before first output arrives.", "First output state that confirms generation has started.", "Active streaming state with partial-answer label, stop control, and stable output region.", "Pending citation, pending tool call, pending moderation, and pending structured-validation states.", "Stalled or slow-stream state with elapsed status and recovery threshold.", "Stopped-by-user state that labels partial output and offers continue, retry, copy partial, or discard.", "Interrupted, failed, rate-limited, offline, and timeout states that preserve prompt and partial output where safe.", "Complete state with final answer, final citations or source status, copy/apply eligibility, and completion metadata." ], "interactionContract": [ "The UI never presents an active stream as a complete answer until the terminal event or final validation state arrives.", "Partial output remains attached to the prompt, source scope, tool state, and stream status that produced it.", "Stop generation changes the state to stopped or partial instead of silently converting the text into a finished answer.", "Retry clearly states whether it continues from the partial output, restarts the same prompt, or regenerates a new answer.", "Copy, apply, cite, export, and publish actions indicate whether they operate on partial output or final output.", "Streaming updates do not steal focus, break text selection, collapse the composer, or force scroll when users are reading older content.", "Screen reader announcements summarize meaningful stream milestones instead of announcing every token.", "If safety, citation, tool, or structured-output checks revise or remove streamed content, the UI explains the revision." ], "implementationChecklist": [ "Model stream lifecycle separately from prompt draft, submitted prompt, final response, citation resolution, tool execution, and history state.", "Track event types such as response started, output delta, tool call delta, citation pending, moderation hold, error, stopped, completed, and final metadata.", "Render partial output in stable blocks that tolerate incomplete Markdown, code fences, tables, links, JSON, and citations.", "Add Stop, Continue, Retry, Regenerate, Copy partial, Copy final, Discard, View events, and Report issue controls according to product risk.", "Throttle visual updates and live announcements to meaningful chunks, sentence boundaries, or elapsed intervals.", "Preserve prompt, partial output, selected text, scroll position, source panel state, and focus through stream failure and route changes where possible.", "Gate apply, publish, final copy, download, or structured export until final validation passes when early chunks can be misleading.", "Test slow first token, long stream, network interruption, server error event, content-filter hold, citation delay, tool delay, malformed Markdown, malformed JSON, mobile keyboard, reduced motion, and screen reader output." ], "commonMisuses": [ "Showing a blinking cursor with no state, stop control, or elapsed feedback.", "Letting partial output look finished before the final event arrives.", "Copying or applying a streamed answer before citations, tool results, or validation complete.", "Erasing partial output after a network failure.", "Announcing every token through a live region.", "Forcing scroll to the newest token while users are reading or selecting earlier text.", "Using streaming to hide long-running tool work that should have visible steps or approval." ], "critiqueQuestions": [ "Which events prove the response has started, is still partial, has stalled, has stopped, has failed, or is complete?", "Can users tell whether text, citations, tool results, and structured output are pending or final?", "What actions are safe on partial output, and which require final validation?", "What remains available after stop, retry, timeout, offline, rate limit, or moderation hold?", "How does streaming behave when users scroll, select text, copy, inspect citations, use mobile keyboards, or rely on screen readers?", "Would a spinner, progress bar, chat interface, or workflow trace be clearer than streaming partial text?" ], "relatedPatterns": [ "chat-interface", "progress-bar", "loading-spinner", "loading-skeleton", "feed", "retry" ], "comparisons": [ "streaming-response-vs-chat-interface-vs-progress-bar-vs-loading-spinner-vs-feed" ], "sourceIds": [ "openai-streaming-responses", "openai-responses-streaming-events", "azure-openai-content-streaming", "mdn-server-sent-events", "mdn-eventsource", "wcag-status-messages" ] }, { "id": "success-confirmation", "completionStatus": "complete", "name": "Success confirmation", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Durable in-context proof that an action completed", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users complete an action but cannot tell whether it truly succeeded, which object changed, whether a receipt exists, or what to do next, especially when success is reduced to a transient Done message.", "solution": "Show an in-context success confirmation after the action is committed, name the affected object, provide proof such as reference or timestamp when needed, expose one next step, announce the status appropriately, and clear the confirmation when the proof has served its purpose.", "uiGuidance": [ "Render success confirmation near the action result or affected object with a success label, object-specific message, reference or timestamp when useful, and one next step such as View receipt, Continue review, or Copy reference.", "Keep the confirmation visible until users can verify the changed state, copy needed proof, or move intentionally to the next task; use a transient toast only when the success is disposable." ], "uxGuidance": [ "Use success confirmation when users need confidence that a just-finished action has really completed and can identify what changed before continuing.", "Tie the confirmation lifecycle to the confirmed object: remove, collapse, or convert it after the user views the receipt, starts unrelated work, or the success state becomes ordinary page content." ], "uiExamples": { "good": [ "After evidence upload, a success panel beside the evidence checklist says Evidence uploaded, shows receipt EV-2048, timestamp, and View receipt.", "After saving a draft, a confirmation row says Application draft saved at 14:32 and leaves Continue review available." ], "bad": [ "A green strip says Done with no object, reference, or next step.", "A file-upload receipt appears only in a disappearing toast even though the user must quote it later." ] }, "uxExamples": { "good": [ "Users can copy the receipt reference, open the confirmed record, then see the success message collapse into normal completed state.", "If saving fails, no success confirmation appears until the server-confirmed state is available." ], "bad": [ "The UI says Saved before the network request finishes and later silently reverts the draft.", "The same success message remains after users move to a different customer, making the confirmed object ambiguous." ] }, "problemContext": [ "A user has just saved, uploaded, submitted, copied, sent, invited, configured, or otherwise completed an action.", "The action changes an object or process that users may need to verify, quote, inspect, continue, or distinguish from another similar object.", "A full confirmation page would be too heavy because the surrounding task or service journey continues.", "A toast alone would be too temporary because users need proof, next-step orientation, or confidence that the server accepted the action." ], "selectionRules": [ "Choose success confirmation when the user needs durable in-context proof that a just-completed action succeeded.", "Name the affected object, file, record, draft, invitee, payment method, or configuration instead of only saying Success or Done.", "Include a receipt, reference number, timestamp, changed status, or destination link when the user may need to verify or quote the outcome.", "Provide at most one direct next step in the confirmation, such as View receipt, Continue, Copy reference, or Open record.", "Use toast notification instead when the success is low consequence, self-evident, and safe to disappear.", "Use notification banner instead when the success follows navigation from a previous page and must appear before the next page heading.", "Use confirmation page instead when the whole service journey has ended and users need a completion reference plus what happens next.", "Use undo instead when the most important post-action affordance is reliable reversal of a frequent recoverable action." ], "requiredStates": [ "Pre-action state with no success confirmation.", "Pending or saving state that does not claim success before commitment.", "Confirmed success state with object identity, reference or timestamp, and changed status.", "Actionable success state with one next step such as View receipt or Copy reference.", "Copied or acknowledged state after the user uses the confirmation's proof.", "Resolved state after the user views the record, starts a new task, or the confirmation becomes normal content.", "Failure handoff state where unsuccessful completion routes to alert, inline message, error state, or error summary instead of success." ], "interactionContract": [ "The confirmation appears only after the action is committed enough to be truthful.", "The message is placed close to the affected object or task result, unless the product intentionally uses a consistent status region.", "The success label, icon, or color is paired with text so success is not communicated by color alone.", "The confirmation identifies the exact object and outcome users just changed.", "The confirmation remains available long enough for users to verify, copy, or follow the next step.", "Activating the next step changes the confirmation lifecycle, such as marking the receipt viewed or collapsing the panel.", "A new unrelated task clears or scopes the old confirmation so users do not mistake it for the current object." ], "implementationChecklist": [ "Wait for the authoritative success signal before rendering a confirmed state.", "Write success copy with verb, object, and result, such as Evidence uploaded or Draft saved.", "Add reference, timestamp, object name, or changed status when users may compare or quote the outcome.", "Choose placement from where users need proof: near the object, at the top of the task area, or in a consistent in-context status region.", "Expose role status or equivalent announcement for dynamic success without moving focus unless the platform pattern intentionally focuses a success banner after navigation.", "Limit actions to one direct next step and route longer follow-up into the destination record or task.", "Define the event that removes or collapses the confirmation: viewed receipt, copied reference, new task, route change, or timeout only when proof remains elsewhere.", "Test repeated saves, slow server responses, duplicate objects, navigation away and back, screen-reader announcement, keyboard access, zoom, and narrow layouts." ], "commonMisuses": [ "Showing success before the operation is actually committed.", "Writing only Done, Success, or Saved without naming the affected object.", "Auto-expiring the only receipt or reference users need later.", "Leaving stale success visible after users switch records or tasks.", "Using a success confirmation for an urgent warning or failed action.", "Showing a full confirmation page when the user still needs to continue the same task.", "Stacking a toast, banner, and local success panel for the same event." ], "critiqueQuestions": [ "What authoritative event proves the action succeeded?", "Can users tell which object or record was confirmed?", "Do users need a reference, timestamp, link, or copy action before continuing?", "Is this success important enough to remain visible, or should it be a toast?", "Would the next screen need a notification banner, or has the entire journey ended and needs a confirmation page?", "What clears the confirmation so it does not become stale?" ], "relatedPatterns": [ "toast-notification", "notification-banner", "alert", "undo", "inline-message", "notification-center" ], "comparisons": [ "success-confirmation-vs-toast-notification-vs-notification-banner-vs-alert" ], "sourceIds": [ "carbon-notification-component", "govuk-notification-banner-component", "atlassian-flag-component", "wcag-status-messages" ] }, { "id": "summary-box", "completionStatus": "complete", "name": "Summary box", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Highlighted region for key information from a longer page", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Long pages often contain a small set of facts users need immediately, but burying those facts in prose slows scanning while over-highlighting whole sections creates another wall of text.", "solution": "Provide a concise, clearly headed summary region that extracts the essential facts or next steps from the surrounding page, preserves source context, keeps links selective, and avoids alert, warning, validation, and navigation semantics when those patterns would be more accurate.", "uiGuidance": [ "Render a summary box as a labelled region with a specific heading, short body, scannable key points or next steps, and only links that directly support the summarized page task.", "Place the box close to the longer content or decision it summarizes, and keep the visual treatment distinct from warnings, alerts, validation summaries, decorative cards, and navigation link collections." ], "uxGuidance": [ "Use summary box when users need the essential facts, eligibility notes, deadlines, documents, or next steps from a longer page before reading every detail.", "Keep the box selective and source-faithful: it should reduce cognitive load by extracting the few facts users need now, not duplicate the whole page or hide critical content that must remain in the main flow." ], "uiExamples": { "good": [ "A benefits guide has a summary box headed Before you apply with deadline, required documents, and Start application link above the detailed eligibility rules.", "A service page shows What happens next with three short steps, expected timing, and one link to track the case." ], "bad": [ "A pale box repeats the entire page introduction, every related link, and several unrelated policy notes.", "A red box labelled Summary contains validation errors and warnings, making it look like an alert but behave like static guidance." ] }, "uxExamples": { "good": [ "A user scans the box, learns they need photo ID and proof of address, then continues into the detailed instructions with the same terms repeated in context.", "A returning user uses the next-steps box to jump to Track application without rereading the whole guidance page." ], "bad": [ "Users miss an eligibility rule because it appears only inside a sidebar summary and not in the main instructions.", "A summary box lists six links but gives no explanation of which one is the next step." ] }, "problemContext": [ "The page has longer guidance, policy, service instructions, eligibility rules, process detail, or next-step information.", "Users need a compact orientation before deciding whether to continue, gather evidence, start a task, or read the full page.", "The highlighted content is important but not a dynamic urgent status, form error summary, severe warning, or hidden optional explanation.", "The box may contain a heading, short paragraph, bullet list, limited links, and a call to action that belongs to the page task.", "The same facts must remain consistent with the detailed page content and any downstream form or confirmation state." ], "selectionRules": [ "Choose summary box when a longer page needs a compact extract of key facts, next steps, eligibility, documents, dates, or outcomes.", "Use alert when the message is a current urgent status or dynamic condition that users must notice now.", "Use warning text when the content is a severe consequence before an action or omission.", "Use inline message when feedback belongs to one row, card, form section, or local object state.", "Use disclosure details when the content is optional help that can stay hidden behind a specific summary label.", "Use related links when the main job is onward navigation rather than summarizing page content.", "Use error summary when submitted form errors need a linked list of invalid answers.", "Keep summary boxes short enough to scan; move long explanations, branching instructions, and full workflows back into the page body.", "Do not use summary box as decoration around ordinary paragraphs or as a universal card style.", "Do not place facts only in the summary box when users must encounter them in sequence during the task." ], "requiredStates": [ "Default summary box with heading, concise body, key points or next steps, and optional task-specific link.", "Summary with no link, one primary link, and several tightly scoped supporting links.", "Long-page paired state where detailed sections repeat or expand the summarized facts.", "Out-of-date or content-mismatch review state when the summary no longer matches the page body.", "Narrow-screen state where heading, bullets, and links wrap without turning into a card stack or alert.", "Print or no-style state where the summary remains readable as a labelled region." ], "interactionContract": [ "The summary box summarizes content that is present, reachable, or clearly linked from the same task context.", "The heading names the summary's purpose, such as Before you apply or What happens next, not only Summary.", "Every bullet is short, specific, and independently useful.", "Links inside the box are limited to the next action, tracking route, evidence requirement, or directly summarized section.", "The box does not auto-dismiss, announce as urgent, open a modal, or hide details unless another pattern owns that behavior.", "Updating detailed page content requires updating or removing any summary that restates those facts.", "The summary remains visually connected to the page content it summarizes and does not compete with page title, error summary, or primary action." ], "implementationChecklist": [ "Identify the long page content that users repeatedly need to scan first.", "Choose three to five key facts or next steps; remove background explanation, exceptions, and loosely related links.", "Write a purpose-specific heading and short bullets using the same terms as the detailed page.", "Place the summary after the H1 or near the relevant section according to the page task.", "Keep the box as a semantic region or labelled group with proper heading order.", "Check that each summarized fact is still present or expanded in the body content where users need it.", "Test long headings, long links, no links, several links, mobile width, zoom, print, screen readers, and content updates.", "Audit for misuse as alert, warning text, error summary, card grid, related-links list, or disclosure control." ], "commonMisuses": [ "Repeating the whole page in a highlighted box.", "Using a summary box for urgent dynamic status that should be an alert.", "Using a summary box for severe consequence copy that should be warning text.", "Listing unrelated links until the box becomes a navigation dumping ground.", "Putting required facts only in the box and not in the relevant detailed section.", "Using vague headings such as Important or Summary without saying what the box helps users do.", "Letting summarized dates, amounts, eligibility, or next steps drift from the main page content." ], "critiqueQuestions": [ "What exact longer content does this box summarize?", "Can users understand the box from its heading without reading the entire page?", "Are the facts selective enough to reduce scanning effort?", "Would alert, warning text, inline message, disclosure details, related links, or error summary be more accurate?", "Are summarized facts repeated or expanded in the main content where users need them?", "What editorial process keeps the box synchronized with the page body?" ], "relatedPatterns": [ "alert", "inline-message", "warning-text", "disclosure-details", "related-links", "error-summary", "card-list" ], "comparisons": [ "summary-box-vs-alert-vs-warning-text-vs-disclosure-details" ], "sourceIds": [ "uswds-summary-box-component", "va-summary-box-component", "nci-summary-box-component", "govuk-inset-text-component", "nhs-inset-text-component" ] }, { "id": "swipe-action", "completionStatus": "complete", "name": "Swipe action", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Horizontal item-level gesture that reveals or commits row-scoped actions", "maturity": "standard", "platforms": [ "mobile", "web", "desktop" ], "problem": "Swipe actions can make repeated row work fast on touch devices, but hidden horizontal gestures are hard to discover, easy to trigger accidentally, and exclusionary when they replace visible, keyboard, or assistive action paths.", "solution": "Design swipe action as a row-level shortcut with visible affordance or teaching, directional labels, partial reveal, threshold and snap-back behavior, conflict resolution with scroll and navigation, equivalent controls, and recovery or confirmation for risky outcomes.", "uiGuidance": [ "Render swipe action as a row-scoped horizontal gesture with clear direction, action label, background affordance, threshold feedback, cancel behavior, and a visible action-menu or button equivalent.", "Use distinct visual treatment for safe, positive, and destructive swipe actions, and keep destructive outcomes reversible or routed to confirmation when recovery is not reliable." ], "uxGuidance": [ "Use swipe action for frequent item-level actions such as archive, mark read, complete, pin, dismiss, or reveal row commands when the row remains understandable without the gesture.", "Do not make swipe the only way to act; protect vertical scrolling, pull-to-refresh, row navigation, selection, assistive technology, keyboard, and pointer users with equivalent controls and conflict rules." ], "uiExamples": { "good": [ "A message row reveals Archive on left swipe and More actions on right swipe, shows action labels behind the row, snaps back before threshold, and keeps a More menu for the same commands.", "A task row crossing the complete threshold shows Complete task, moves the task to Done, and displays Undo complete with the task name." ], "bad": [ "A hidden swipe deletes a row immediately with no label, threshold feedback, undo, confirmation, or menu equivalent.", "A diagonal scroll inside a list activates a destructive swipe action while the user is trying to read older rows.", "Two icon-only actions appear behind a row with no text, no direction hint, and no screen reader path." ] }, "uxExamples": { "good": [ "A user partially swipes a notification, sees Archive and Mark read labels, releases before threshold, and the row snaps back unchanged.", "A keyboard user opens the row action menu, chooses Archive, and receives the same archived status plus Undo as the swipe path.", "A user swipes a destructive row far enough to reveal Delete, then must tap Delete or confirm because the item cannot be restored safely." ], "bad": [ "A user swipes to scroll a horizontally cramped row and accidentally archives a critical alert.", "A user with switch control cannot find the hidden Archive action because the row has no visible action equivalent.", "A screen reader user hears only the row title, not the available swipe actions or the completed result." ] }, "problemContext": [ "The surface contains repeated list, feed, card, notification, message, task, file, or table rows with row-scoped actions.", "The same row may support tap-to-open, selection, action menu, drag, vertical scrolling, pull-to-refresh, nested horizontal content, or bulk actions.", "Actions can be safe, reversible, positive, destructive, permission-limited, disabled, or unavailable while the object is syncing.", "Users may interact through touch, mouse, trackpad, keyboard, switch control, screen reader, stylus, or assistive pointer devices." ], "selectionRules": [ "Choose swipe action when the design problem is a horizontal item-level gesture that reveals or commits row-scoped commands.", "Use touch gesture when the question is the broader gesture vocabulary, threshold, feedback, cancellation, target sizing, and equivalent controls across many gestures.", "Use list view when the main problem is row anatomy, scanning, selection, sorting, filtering, pagination, or opening objects.", "Use action menu when commands should be explicitly listed from a visible trigger instead of hidden behind horizontal movement.", "Use undo when the core design problem is post-action recovery after a completed reversible action.", "Use confirmation dialog when a destructive or high-impact row action cannot be safely undone.", "Use pull to refresh for a vertical top-of-scroll refresh gesture, not for horizontal item actions.", "Use drag and drop when the gesture moves an object from a source to a destination rather than revealing row commands.", "Reveal destructive actions before committing them unless the outcome is routine, clearly labeled, and reliably recoverable.", "Do not place hidden swipe action as the only path to primary, critical, security, payment, consent, or account actions." ], "requiredStates": [ "Idle row state with visible row identity and discoverable action path.", "Gesture hint state for teaching that the row supports a horizontal swipe action.", "Partial reveal state showing action label, icon, direction, and affected row.", "Below-threshold snap-back state that leaves the row unchanged.", "Threshold reached state with release-to-commit or release-to-reveal feedback.", "Revealed actions state with tappable row-scoped commands and cancel behavior.", "Committed safe action state with status message and stable focus or row position.", "Destructive action state with undo, confirmation, or review according to reversibility.", "Multiple action or bidirectional state that clearly separates left and right swipe outcomes.", "Disabled or permission-limited action state with explanation.", "Conflict state for vertical scroll, pull-to-refresh, row navigation, selection, nested carousel, or system back gesture.", "Keyboard, screen reader, switch, mouse, and action-menu equivalent state.", "Bulk-selection state where row swipe does not conflict with selected-set actions.", "Mobile compact, large text, and landscape states with readable labels and targets." ], "interactionContract": [ "Swipe action starts only from the intended row and horizontal axis; vertical scroll and pull-to-refresh win when movement is primarily vertical.", "The row shows a visible background, label, icon, and progress before any command is committed.", "Releasing before threshold snaps the row back and leaves the model unchanged.", "Crossing threshold either reveals actions for explicit tap or commits one clearly labeled action according to the product's risk rule.", "Destructive or high-impact actions are reversible with undo or require confirmation before final execution.", "Every swipe action has an equivalent visible button, action menu item, keyboard command, or contextual action path with the same disabled, pending, success, and recovery states.", "Only one row remains actively swiped open unless the product deliberately supports multiple open rows.", "Completed actions announce the row name, action name, and recovery path where applicable." ], "implementationChecklist": [ "Inventory each row action, direction, threshold, reveal width, commit rule, reversibility, disabled reason, and equivalent non-gesture control.", "Define whether each swipe reveals action buttons, commits on release, or requires a tap after reveal.", "Write direction-specific labels such as Archive message, Mark read, Pin task, or Delete file instead of relying on color or icons alone.", "Set movement thresholds, angle locks, velocity handling, snap-back animation, and system edge-reservation rules.", "Resolve conflicts with vertical scroll, pull-to-refresh, horizontal carousels, row selection, drag handles, nested scrollers, and browser or OS back gestures.", "Make row action menus, visible buttons, keyboard shortcuts, or context menus trigger the same command handlers as swipe.", "Add undo, confirmation, or delayed finalization for destructive actions according to reversibility and external side effects.", "Test accidental diagonal movement, one-handed use, large text, screen reader, keyboard, switch control, mouse drag, trackpad swipe, pointer cancellation, and bulk selection." ], "commonMisuses": [ "Making a hidden swipe the only way to archive, delete, complete, or reveal row actions.", "Committing a destructive action before users see the label or cross a clear threshold.", "Letting vertical scroll, pull-to-refresh, row navigation, and swipe action trigger at the same time.", "Using unlabeled icon-only action backgrounds or color-only destructive cues.", "Offering different commands in swipe and the visible action menu.", "Leaving multiple rows half-open and visually confusing list state.", "Providing no undo, confirmation, or recovery for a risky swipe result.", "Assuming desktop hover hints teach mobile users the gesture." ], "critiqueQuestions": [ "What exact row action does each swipe direction reveal or commit?", "How does the user learn that the row supports swipe action before they need it?", "What threshold, release boundary, and snap-back behavior prevent accidental activation?", "Where is the non-gesture equivalent for keyboard, screen reader, switch, mouse, and assistive pointer users?", "Which outcomes are reversible with undo, and which require confirmation before execution?", "How do vertical scroll, pull-to-refresh, row open, row selection, drag, and system back gestures avoid fighting each other?", "What status message names the affected row and result after activation?" ], "relatedPatterns": [ "touch-gesture", "list-view", "action-menu", "undo", "confirmation-dialog", "pull-to-refresh" ], "comparisons": [ "swipe-action-vs-touch-gesture-vs-list-view-vs-action-menu-vs-undo-vs-confirmation-dialog" ], "sourceIds": [ "android-compose-swipe-to-dismiss", "material-design-gestures", "apple-hig-lists-tables", "w3c-wcag-pointer-gestures", "w3c-wcag-target-size-minimum", "nng-contextual-swipe-actions" ] }, { "id": "sync-state", "completionStatus": "complete", "name": "Sync state", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Local-and-remote reconciliation status", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users have local changes, downloaded files, queued uploads, or background requests whose server or peer copy may be pending, in progress, accepted, partially accepted, failed, paused, or conflicting.", "solution": "Expose sync state as a scoped reconciliation surface that names the local and remote copy status, keeps per-item progress and failures visible, preserves local data, and provides retry, cancel, export, resume, or review actions.", "uiGuidance": [ "Show sync state close to the object or queue it describes, using labels such as Local saved, Queued, Syncing, Synced, Partially synced, Failed, Paused, and Conflict needs review.", "Separate device-local persistence from remote acceptance; a green synced status is only appropriate after the server or target peer has accepted the change." ], "uxGuidance": [ "Use sync state to keep users confident while local changes, remote copies, attachments, messages, or records reconcile across devices, services, or background workers.", "Make partial progress actionable by exposing per-item status, last successful sync time, retry/cancel/export choices, and a clear handoff when a conflict or validation issue needs review." ], "uiExamples": { "good": [ "A field report queue shows 5 local changes: notes synced, two photos uploading, meter reading queued, signature failed with Retry, and supervisor comment needs review.", "A file list uses separate badges for Available offline, Syncing, Sync error, and Online-only, with details available from the affected row.", "A mobile outbox shows messages saved locally, queued for send, sending, sent, failed, and edit-before-retry states." ], "bad": [ "A single green Saved badge appears while several attachments are still queued.", "An endless spinner says Syncing with no item count, failure details, last sync time, or retry action.", "A percentage bar reaches 100 percent before server validation finishes and later loses a rejected item." ] }, "uxExamples": { "good": [ "A user reconnects after editing offline and sees the queue move from local saved to syncing, then to one failed photo with retry while the accepted notes remain synced.", "A user opens the same record on another device and sees that the server copy is current as of 11:08 while one local edit still needs review.", "A user pauses sync on a metered connection and can resume later without losing local work or confusing paused with failed." ], "bad": [ "The offline banner disappears after reconnect, but hidden queued changes keep failing in the background.", "A sync error toast disappears before the user can identify which file failed.", "The app overwrites a newer server value with a local edit without showing conflict review or preservation choices." ] }, "problemContext": [ "The product stores or edits data locally before remote acceptance, or it downloads remote content for local use.", "Sync can happen after reconnect, in the background, across devices, or after a service worker, native client, or cloud service retries queued work.", "Users need to know whether work is merely local, queued, actively transferring, accepted remotely, stuck, paused, partially synced, or blocked by conflict or validation." ], "selectionRules": [ "Choose sync state when local and remote copies both matter and their reconciliation status affects trust, next action, or data integrity.", "Label local saved separately from remote synced until the server, service, or peer confirms acceptance.", "Show per-item status when different queue items can be queued, in progress, accepted, failed, paused, or conflicting at the same time.", "Show last successful sync time or server version when freshness or cross-device confidence matters.", "Keep failed or conflicting local work visible with retry, edit, cancel, export, or review actions.", "Use offline state when the primary condition is no connection and the question is what still works locally.", "Use progress bar when the measurable percentage is the primary useful signal, not when users need acceptance, queue, or conflict status.", "Use error state when a failed sync item has become a blocking recovery surface rather than one state in an active queue.", "Use draft state when the main concern is unpublished authoring state, even if that draft may later sync.", "Escalate from passive status to persistent recovery when sync failure affects submission, payment, legal records, medical records, file integrity, or collaboration." ], "requiredStates": [ "Local saved state for data persisted on the device but not yet sent.", "Queued state for work waiting for a sync attempt.", "Syncing state with scope, item count, or operation label.", "Synced state after remote acceptance.", "Partially synced state when some queue items succeeded and others did not.", "Failed sync state that preserves local work and exposes recovery.", "Retrying state that differs from idle failure.", "Paused state for user, metered-network, account, battery, or policy pause.", "Conflict-needs-review state that preserves both local and server information.", "Last successful sync timestamp or version state." ], "interactionContract": [ "The sync surface never upgrades local saved or queued work to synced until the remote system confirms acceptance.", "Queue-level status summarizes counts while item-level rows show which object owns each status.", "Retry acts on failed items or a clearly named queue; it does not duplicate already accepted changes.", "Cancel or remove actions explain whether they discard only queued local work or also affect the remote copy.", "Partial success remains visible until every failed, paused, or conflict item is resolved.", "Background sync updates are announced at meaningful boundaries such as queued, syncing, synced, failed, or review needed.", "The user can identify whether a problem is network retry, account sign-in, server validation, unsupported file type, policy block, or conflict." ], "implementationChecklist": [ "Define canonical sync statuses in the data model, not just in display text.", "Store local queue entries with stable IDs, object names, timestamps, retry counts, server request identifiers, and recoverable local payloads.", "Record remote acceptance separately from local persistence and transfer completion.", "Render a compact summary plus expandable item-level rows when queues contain more than one object.", "Expose retry, cancel, export local copy, view details, and review conflict actions according to the item status.", "Use background sync, native sync queues, upload managers, or job workers only when the UI can surface their states honestly.", "Test reconnect, duplicate retry, partial server success, app restart, account sign-out, policy-blocked files, quota failure, server validation failure, and multi-device conflict." ], "commonMisuses": [ "Calling local persistence Synced before remote acceptance.", "Showing only one spinner for a mixed queue of succeeded, failed, and pending items.", "Hiding failed sync work in a transient toast.", "Clearing local data after a failed retry.", "Treating server validation failure, offline mode, account pause, and conflict as the same sync message.", "Using a percentage as proof of save when server acceptance still has not happened.", "Removing the sync indicator immediately after reconnect even though queued work remains." ], "critiqueQuestions": [ "What exactly is local, what exactly is remote, and which copy is current?", "What event proves that this item is synced: transfer complete, server accepted, peer acknowledged, or later validation passed?", "Can users identify which queue item failed and what action fixes it?", "How does the UI represent partial success without implying the whole task is done?", "What happens to local work after app restart, account switch, retry exhaustion, or conflict?", "Does the status explain whether sync is paused, blocked, retrying, failed, or waiting for review?" ], "relatedPatterns": [ "offline-state", "progress-bar", "error-state", "draft-state", "notification-center", "loading-spinner" ], "comparisons": [ "sync-state-vs-offline-state-vs-progress-bar-vs-error-state" ], "sourceIds": [ "mdn-background-synchronization-api", "workbox-background-sync", "microsoft-onedrive-sync-icons" ] }, { "id": "table", "completionStatus": "complete", "name": "Table", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Semantic row-and-column data comparison surface", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to compare records across shared attributes, but tables often lose meaning through missing captions, unlabeled headers, broken responsive layouts, mixed controls, or spreadsheet-like interactions without data-grid behavior.", "solution": "Present records in a semantic table with a caption, clear column and optional row headers, aligned values, declared sort and filter state, responsive header preservation, and a boundary between read-only comparison, row actions, and richer data-grid tasks.", "uiGuidance": [ "Render a table with a specific caption or heading, visible column headers, optional row headers, aligned values, consistent row actions, and enough spacing for scanability.", "Show sort, filter, pagination, selection, and responsive states without breaking the visible relationship between each header and cell." ], "uxGuidance": [ "Use tables when aligned columns help users compare records, find exceptions, audit values, or triage work faster than opening each item.", "Preserve row meaning, focus, selection, sort, filter, pagination, and header labels as users update or inspect the table." ], "uiExamples": { "good": [ "A payment review table has the caption June vendor payments, headers Vendor, Status, Due date, Amount, and Action, right-aligned amounts, and row actions labelled by vendor.", "A narrow layout stacks each payment row while repeating labels such as Status and Amount before values." ], "bad": [ "A div layout looks like columns but has no caption, table semantics, or header associations.", "A mobile table shows only values like Approved, 12 Jun, and $840 without the labels that explain them." ] }, "uxExamples": { "good": [ "A user sorts by Amount descending, filters to Pending, moves to page 2, and the table keeps its caption, active sort, active filter, row count, and selected payment context.", "A keyboard user activates the Due date header, hears the changed order, and focus remains on the header rather than jumping into the first row." ], "bad": [ "Filtering the table removes selected rows without explaining why or offering a clear-filter path.", "A row Edit button says only Edit, so users cannot tell which record will open when tabbing through actions." ] }, "problemContext": [ "The items share a stable set of attributes such as name, status, owner, due date, amount, count, or last updated time.", "Users need to scan down columns, compare values across rows, or find differences between records.", "The table may sit near search, sort, filters, pagination, row actions, expandable detail, or bulk selection controls.", "The product can define which columns matter, how headers map to values, and what happens at narrow widths." ], "selectionRules": [ "Choose table when each row represents one record and each column represents the same attribute for every row.", "Use table for comparison, audit, reconciliation, inventory, queue, billing, status, and report tasks where aligned columns reduce effort.", "Use a data grid when users edit cells, navigate between interactive cells with arrow keys, or perform spreadsheet-like operations.", "Use list view when items are primarily scanned as summaries and shared columns are secondary.", "Use card list or card grid when item imagery, uneven metadata, or rich object previews matter more than column alignment.", "Use sort controls or sortable headers to change row order, but keep sorting separate from filtering and pagination state.", "Use filter panel to change which rows are included, not to rename or hide table columns without clear table-state feedback.", "Use pagination, virtual loading, or a saved view when the row count is too large for one table view.", "Avoid table when there are fewer than two comparable attributes or when every row needs a different layout.", "Avoid layout tables for positioning page content." ], "requiredStates": [ "Default table state with caption, visible headers, row values, and result count or context.", "Sorted table state with current sorted column and direction exposed visually and programmatically.", "Filtered table state with active criteria near the table and updated row count.", "Selected-row state when the table supports row selection or bulk action.", "Row-action state with actions associated to the correct row.", "Empty table state after filters or search remove all rows.", "Loading or updating state while table rows refresh.", "Responsive state that preserves header-to-cell meaning.", "Overflow state for wide tables with visible horizontal scroll or column-priority rules.", "Error state when rows cannot load while table structure and retry path remain visible." ], "interactionContract": [ "The table caption or nearby heading names the dataset and purpose, not just Table.", "Column headers identify the values below them and remain associated with cells in desktop, stacked, and horizontally scrolled layouts.", "Row headers identify each record when the first column is the record name or primary identifier.", "Sortable headers update row order, active indicator, accessible sort state, and result summary together.", "Filtering updates row membership while preserving current sort unless the design explicitly resets it.", "Pagination moves through the same sorted and filtered table without losing row meaning.", "Row actions, links, checkboxes, and expansion controls are labelled with the row they affect.", "Keyboard focus remains stable after sort, filter, pagination, row selection, expansion, or refresh." ], "implementationChecklist": [ "Define the row object, column attributes, primary row header, caption, and optional table description.", "Use table semantics with caption, thead, tbody, th, td, scope, and row or column headers appropriate to the complexity.", "Use id and headers associations for complex grouped headers when scope alone is insufficient.", "Align numeric values, dates, status tags, and row actions consistently.", "Show active sort and filter state near the table and synchronize it with row count and pagination.", "Label row actions and selectable rows with the record identity.", "Choose a responsive strategy: horizontal scroll, stacked rows with labels, reduced columns, or a dedicated detail view.", "Handle empty, loading, error, selected, expanded, sorted, filtered, and paginated states deliberately.", "Test with keyboard, screen reader table navigation, zoom, high contrast, long labels, localized values, and narrow viewports." ], "commonMisuses": [ "Using table markup to create page columns or layout spacing.", "Rendering div rows that visually resemble a table but expose no table, row, column, or header semantics.", "Omitting the caption or visible dataset context.", "Dropping column headers on mobile so values lose meaning.", "Mixing sorting, filtering, search, pagination, and column visibility into one unlabeled control.", "Turning a read-only table into an editable spreadsheet without data-grid keyboard behavior.", "Putting too many columns, long paragraphs, and row actions into a cramped table.", "Sorting formatted values by displayed text instead of raw date, amount, number, or status order." ], "critiqueQuestions": [ "What does one row represent, and what does each column mean?", "Can users compare values down a column and across rows without opening every record?", "Is there a caption or heading that names the dataset and table purpose?", "How are headers preserved in responsive, sorted, filtered, and paginated states?", "Are row actions, selections, and expanded content tied to the correct record?", "Has the table become an editable data grid, card list, or list view instead?" ], "relatedPatterns": [ "sort-controls", "filter-panel", "pagination", "details-panel", "accordion", "basic-search", "empty-state" ], "comparisons": [ "table-vs-sort-controls-vs-filter-panel-vs-pagination" ], "sourceIds": [ "wai-tables-tutorial", "mdn-html-table-element", "uswds-table-component", "carbon-data-table-component", "maersk-table-component" ] }, { "id": "tabs", "completionStatus": "complete", "name": "Tabs", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Section-switching component", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to switch between peer sections without leaving the current page context.", "solution": "Group sibling panels behind labeled tabs, keep one active at a time, and make the active section and panel relationship explicit.", "uiGuidance": [ "Render a tablist with short tab labels, selected tab styling, visible keyboard focus, and a single associated tabpanel that is visually connected to the active tab.", "Show enough panel identity, heading, and preserved state for users to understand what changed when a tab is activated." ], "uxGuidance": [ "Help users switch between sibling sections in the same page context without changing routes or losing local work.", "Avoid tabs when users must compare panels, read panels sequentially, or complete required workflow steps." ], "uiExamples": { "good": [ "Tab labels are short, active tab is obvious, focused tab is distinguishable, and panel content is visually attached to the selected tab.", "The current panel has a heading and stateful controls while inactive panels stay hidden from the visual surface." ], "bad": [ "Tabs wrap unpredictably or look like unrelated buttons.", "Low-contrast active tab that users cannot distinguish from focused or inactive tabs." ] }, "uxExamples": { "good": [ "Users switch between sibling sections without leaving page context or losing panel-local notes.", "Keyboard users can move focus with arrows, activate with Enter or Space, and then reach the selected panel." ], "bad": [ "Using tabs as primary navigation to unrelated pages.", "Hiding required workflow steps or comparison-critical content in mutually exclusive panels." ] }, "problemContext": [ "The content areas are peers under the same parent task.", "Users benefit from quick switching without page navigation.", "Only one section should be visible at a time and hidden sections are not required for sequential reading." ], "selectionRules": [ "Choose tabs for sibling sections at the same hierarchy level that share one surrounding page context.", "Keep tab labels short, stable, and content-specific so users can predict the panel before opening it.", "Use segmented controls when the choice changes a local mode or presentation rather than revealing a content panel.", "Use pagination when users are moving through one ordered collection split into pages.", "Use page navigation, headings, or a table of contents when users need to read content in order or compare sections side by side." ], "requiredStates": [ "Default active tab and visible panel.", "Inactive tab states that remain readable and selectable.", "Focused tab that may differ from the selected tab during manual activation.", "Panel state after a tab is selected.", "Hidden panel state that is not exposed as current content.", "Overflow or small-screen state when labels no longer fit." ], "interactionContract": [ "Changing tabs updates the visible panel without losing the surrounding page context.", "The active tab is programmatically exposed with its controlled panel.", "Keyboard users can move between tabs and reach panel content.", "When activation is manual, arrow keys move focus and Enter or Space activates the focused tab.", "Panel-local inputs, scroll, or draft content are preserved or intentionally reset with clear feedback." ], "implementationChecklist": [ "Use tablist, tab, and tabpanel semantics or equivalent native structure.", "Expose selected state and panel ownership.", "Keep panel content mounted or restore state intentionally.", "Do not overload tabs with unrelated navigation.", "Decide whether activation is automatic or manual based on panel latency.", "Provide a responsive fallback when tab labels wrap or overflow." ], "commonMisuses": [ "Using tabs as a primary site navigation system.", "Hiding required form steps in tabs without completion state.", "Using ambiguous tab labels that force users to inspect every panel.", "Putting content that users must compare into mutually hidden panels." ], "critiqueQuestions": [ "Are these sections truly peers in the same task context?", "Would users miss, forget, or need to compare content hidden in another panel?" ], "relatedPatterns": [ "segmented-control", "pagination" ], "comparisons": [ "tabs-vs-segmented-control-vs-pagination" ], "sourceIds": [ "wai-aria-apg-tabs", "govuk-tabs-component", "carbon-tabs-component" ] }, { "id": "tag", "completionStatus": "complete", "name": "Tag / status tag", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Compact static category or status label attached to an object", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Dense lists, cards, dashboards, and task queues often need small pieces of categorical or status metadata, but full messages, columns, icons, and buttons can overwhelm the layout or imply actions users cannot take.", "solution": "Attach concise static tags to the object they describe, reserve semantic status tags for current state or priority, keep labels consistent and non-interactive unless another chip or control pattern owns the behavior, and provide fuller explanation elsewhere when the tag alone is not enough.", "uiGuidance": [ "Render a tag as a short non-interactive label attached to the object, row, card, heading, count, or result it describes, using stable placement and a visual weight lower than the object's title or primary action.", "Use neutral styling for category tags and semantic styling for status tags only when the text and color both express a consistent current state, progress, urgency, or outcome." ], "uxGuidance": [ "Use tag when a compact label helps users scan, compare, prioritize, or understand an object's state without opening a message, filter control, or detail panel.", "Keep tag meaning synchronized with the underlying object state and route interactive filtering, selection, removal, or recovery work to chips, controls, inline messages, or alerts instead." ], "uiExamples": { "good": [ "A claims table shows status tags such as Pending review, Approved, and Needs evidence in the Status column, with semantic colors and the same text used in detail views.", "A document card shows neutral category tags for Form, Medical record, and Uploaded by you after the title and before secondary metadata." ], "bad": [ "A tag labelled Click to approve looks like a small button but is not keyboard focusable or actionable.", "Every ticket row has nine colorful tags for team, priority, system, phase, age, owner, source, queue, and channel, making the table harder to scan." ] }, "uxExamples": { "good": [ "A reviewer sorts a queue by due date, then uses Needs evidence tags to triage records that require outreach without opening each record first.", "A user sees an Approved status tag beside a claim title and then opens the detail page where the same status and next-step explanation appear in context." ], "bad": [ "A user tries to remove a category tag because it looks like an active filter chip, but the page gives no response.", "A record changes from Pending to Denied but a cached tag still says Pending, so the user starts the wrong follow-up task." ] }, "problemContext": [ "Objects have a small number of categories, states, phases, freshness markers, priorities, counts, or progress labels users need while scanning.", "The label can be expressed in one to three words or a short date without becoming the object's title or full explanation.", "Users need to compare many objects quickly, such as rows in a table, cards in a queue, files in a list, dashboard widgets, or task-list entries.", "Some labels are neutral categories while others are semantic statuses with success, information, warning, or error meaning.", "The system can keep status text, color, sorting, filtering, and detailed object state consistent as records change." ], "selectionRules": [ "Choose tag when the label is compact, read-only, attached to a visible object, and useful for scanning or comparison.", "Use status tag when the label reports the object's current state, condition, progress, urgency, or outcome.", "Use neutral category tags when the label groups objects by type, topic, source, ownership, or freshness without status meaning.", "Use filter chips when the tag represents an active query condition that users can remove or clear.", "Use chip selection when tags are selectable values in an input or preference flow.", "Use inline message when users need explanatory copy, a local action, a warning reason, or recovery guidance near the object.", "Use alert or notification banner when a page-level or task-level condition needs broader context than a compact object label.", "Use a table column, metadata line, or details panel when many tags would crowd every object.", "Do not use tags as links, buttons, toggles, menu triggers, or replacement headings.", "Do not use color-only status; the text and context must still communicate the state." ], "requiredStates": [ "Neutral category tag attached to a row, card, heading, or object summary.", "Status tag with success, information, warning, and error meanings expressed by text plus visual treatment.", "No-tag state where the absence of a tag has a clear implied meaning or is replaced by plain metadata.", "Multiple-tag state with a controlled maximum and wrapping behavior that does not hide title, owner, or actions.", "Dynamic status-update state where the visible tag text changes with the object and non-urgent updates are announced appropriately.", "Overflow or long-label state where copy is shortened, moved to metadata, or explained elsewhere rather than wrapping into a tall badge.", "Misuse state where clickable, removable, filter, or message behavior is routed to another pattern." ], "interactionContract": [ "A read-only tag does not receive focus, show hover affordance, expose pressed or selected state, or claim click behavior.", "The tag's accessible text matches the visible label and includes status context when color or iconography adds semantic meaning.", "The surrounding object makes clear what the tag applies to, such as the current row, card, heading, task, file, claim, or notification.", "Tag updates are driven by canonical object state, not by local decoration copied from stale text.", "If users can remove, select, filter by, or open details from the label, implement the appropriate chip, button, menu, link, or disclosure pattern instead.", "Semantic tag colors use the same meaning across product areas and do not conflict with alerts, warnings, or destructive actions.", "Tags remain secondary to the object title and primary action so scanning helps decision-making without stealing task focus." ], "implementationChecklist": [ "Define the object property, status lifecycle, allowed values, owner system, and update timing before adding a tag.", "Limit labels to one to three words where possible and standardize vocabulary for equivalent states.", "Choose neutral category styling or semantic status styling from meaning, not decorative variety.", "Place tags consistently near the object identity or in a dedicated status column, not randomly across cards or rows.", "Set a maximum visible tag count and an overflow rule before rendering user-generated or imported metadata.", "Check contrast, zoom, text resizing, long translated labels, sentence case, screen-reader text, and mobile wrapping.", "Verify that tag values match filter facets, detail pages, notifications, sorting, exports, and backend state.", "Usability-test layouts where tags appear near buttons so users do not confuse labels with controls." ], "commonMisuses": [ "Making a static tag look clickable or focusable.", "Using tag as the primary title of an object.", "Using vague labels such as New, Hot, or Priority without explaining what they mean in the object's context.", "Mixing neutral category tags and semantic status tags with the same colors.", "Showing many metadata tags when a table column, details panel, or filter would be easier to scan.", "Letting cached status tags drift from the object's current workflow state.", "Using a tag where users need an inline message, alert, validation error, or recovery action." ], "critiqueQuestions": [ "What exact object property does this tag expose, and who owns its truth?", "Is the tag neutral metadata or semantic status, and are color meanings consistent?", "Can users understand the tag without clicking it or relying on color alone?", "Would a filter chip, selectable chip, table column, inline message, alert, or heading be more accurate?", "How many tags can appear before the object becomes harder to scan?", "What happens when the status changes, becomes stale, or differs from the detail page?" ], "relatedPatterns": [ "filter-chips", "chip-selection", "inline-message", "alert", "warning-text", "table", "card-list", "notification-center" ], "comparisons": [ "tag-vs-filter-chips-vs-chip-selection-vs-inline-message" ], "sourceIds": [ "uswds-tag-component", "govuk-tag-component", "carbon-tag-component", "va-tag-status-component", "atlassian-lozenge-component" ] }, { "id": "task-list", "completionStatus": "complete", "name": "Task list", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Component-level list of linked task rows with names, hints, and statuses", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Task lists fail when row names are vague, hint text is too long, statuses look like buttons, unavailable tasks have no reason, status text is not connected to the row link, or the component tries to carry full transaction behavior by itself.", "solution": "Provide task rows with short user-facing names, concise hints only when useful, accessible status text, clear link targets, understandable unavailable reasons, appropriate grouping, and visual emphasis on tasks needing action rather than completed rows.", "uiGuidance": [ "Render a task list as a set of row-level tasks where each row has a short task name, optional single-sentence hint, link target when startable, and status text that indicates whether the task is completed, incomplete, in progress, not started, unavailable, optional, or ready.", "Keep the row or task name as the primary activation target, attach status and hint text to the task link for assistive technology, and keep status tags visually distinct from buttons so users do not mistake statuses for actions." ], "uxGuidance": [ "Use task list when users need to scan a known set of service tasks, understand what each task is, choose a task to start or resume, and see each task's current status.", "Use the component inside a larger transaction hub or service flow, while keeping component concerns focused on task row anatomy, status readability, hint clarity, grouping, and unavailable-task affordance." ], "uiExamples": { "good": [ "A task list row for Upload evidence shows the task name, a short hint, a linked row, and a Needs attention status with the unavailable reason in the row text.", "A grouped task list shows Company details, Financial history, and References with Completed as plain text and Incomplete as a lower-emphasis status tag." ], "bad": [ "A task list uses uppercase button-like status pills and users click the status instead of the row.", "A row contains three inline links, a long explanation, hidden status colour, and no clear target for starting the task." ] }, "uxExamples": { "good": [ "A user scans five task rows, sees that Financial history is incomplete, selects anywhere on that row, completes the section, and returns to find the row status changed to Completed.", "A user cannot start Review yet, but the disabled row explains Upload evidence first and keeps the task visible." ], "bad": [ "A user returns to a list of internal section codes and cannot tell which task relates to evidence upload.", "A completed row has the strongest colour treatment, so users repeatedly revisit it instead of incomplete rows." ] }, "problemContext": [ "The component appears inside a service, application, setup, onboarding, registration, renewal, case, or task hub where users complete a known set of tasks.", "Each task row may represent one page, a section, a group of questions, an upload, a verification, a review task, or a dependent task.", "Users need to scan which rows are complete, which need action, which cannot yet start, and which row to open next.", "Task names, hints, status labels, grouping, and row activation determine whether users can navigate the broader transaction safely.", "The component may be used with a complete-multiple-tasks hub, but the component itself does not define the service's completion model." ], "selectionRules": [ "Choose task list when the interface needs row-level task names, links, hint text, and status labels for a known set of service tasks.", "Use complete multiple tasks when the problem includes saved transaction progress, grouping across sessions, dependencies, final action gating, or review readiness beyond row anatomy.", "Use step navigation when users must move through a strict ordered path and should not choose any task row in any order.", "Use process list when users need public journey guidance rather than live task completion status.", "Use list view when users are browsing or managing arbitrary records with sorting, filtering, pagination, row menus, or bulk selection.", "Use progress bar when progress is continuous or measured as a bounded operation rather than a set of discrete tasks.", "Use tag inside task rows only for status labels that need emphasis; keep Completed lower weight so unfinished tasks remain prominent.", "Use review before submit for answer review after task completion, not inside the task list row itself.", "Include hint text only when users need extra context to decide whether to open the row, and keep it short.", "Hide neither blocked nor unavailable tasks; explain the dependency and route users to the unlocking task.", "Task names should be user-recognizable actions or sections, not internal model names.", "Connect each row's status and hint to its link or accessible description so screen reader users hear the task state before opening it." ], "requiredStates": [ "Linked startable task row.", "Completed task row.", "Incomplete or not started task row.", "In progress task row.", "Unavailable or cannot start yet task row with reason.", "Needs attention task row.", "Optional task row.", "Ready task row.", "Task row with concise hint text.", "Task row without hint text.", "Grouped task list section.", "Updated status after returning from a task.", "Mobile stacked row state.", "Long task name or long status wrapping state.", "Keyboard focus and hover state for the row link." ], "interactionContract": [ "A startable task row opens the represented task; the status label is not a separate primary command.", "Task statuses update when the user returns from the task, using the broader service state as the source of truth.", "Unavailable tasks remain visible with the reason and do not trap focus on disabled links.", "Hint text adds context only to the row it describes and does not contain separate links when the whole row is linked.", "Completed rows remain navigable if the broader service allows editing or review.", "Status labels are text first and colour second, and they do not rely on uppercase styling or button-like treatment.", "Rows wrap cleanly on mobile without detaching the status from the task name." ], "implementationChecklist": [ "Define each task row's user-facing name, route, status source, optional hint, dependency reason, grouping, and completed-row edit behavior.", "Use semantic list markup or equivalent list structure with one focusable row or task link per startable task.", "Associate hint and status text with the task link through visible text and accessible description relationships.", "Keep status vocabulary small and consistent with the broader service, such as Completed, In progress, Not started, Cannot start yet, Needs attention, Optional, and Ready.", "Style Completed with lower emphasis than tasks needing action, and avoid status pills that look like primary buttons.", "Design mobile wrapping so long names, hints, and statuses remain readable without horizontal scrolling.", "Test keyboard activation, screen reader task names and statuses, blocked rows, status updates after return, long labels, grouping, high zoom, mobile, and row hover/focus affordance." ], "commonMisuses": [ "Using task list as the whole service architecture without defining saved progress, dependencies, or final readiness elsewhere.", "Using task list as an answer summary.", "Using it for arbitrary records that need list view features such as sorting, filters, row actions, or selection.", "Using it for a strict linear journey that should use step navigation.", "Making status tags look like buttons or links.", "Putting several links or actions inside one task row.", "Writing long hints that screen reader users must hear every time they focus the task.", "Using colour alone to show status." ], "critiqueQuestions": [ "What task does each row start, and is the name clear enough without internal jargon?", "Does each row need hint text, or can the name carry the task by itself?", "Can users distinguish the row link from the non-interactive status label?", "Is the status text accurate, current, and connected to the row for assistive technology?", "What should users do when a task cannot start yet?", "Is this really a task list component problem, or a complete-multiple-tasks service pattern problem?" ], "relatedPatterns": [ "complete-multiple-tasks", "step-navigation", "process-list", "multi-step-form", "tag", "list-view", "progress-bar", "review-before-submit", "error-summary" ], "comparisons": [ "task-list-vs-complete-multiple-tasks-vs-step-navigation-vs-process-list" ], "sourceIds": [ "govuk-task-list-component", "nhs-task-list-component", "scottish-government-task-list-pattern", "govuk-task-list-iteration-research" ] }, { "id": "text-input", "completionStatus": "complete", "name": "Text input", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Single-line freeform data-entry control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to provide a short answer in their own words, but generic fields often hide labels, imply the wrong answer length, validate too early, or lose typed content during error recovery.", "solution": "Provide a labelled single-line input with stable hint and error association, width that matches expected answer length, normal typing and paste behavior, delayed validation, and preserved user-entered text.", "uiGuidance": [ "Render a persistent label, appropriately sized single-line input, optional hint, visible focus state, and nearby error text that is programmatically associated with the field.", "Size the input to the expected answer length and keep helper, error, disabled, readonly, and success states visually distinct without relying on placeholder text as the instruction." ], "uxGuidance": [ "Use text input for short freeform answers that users can type or paste and that cannot be accurately represented as a fixed option choice.", "Let users edit normally, validate after interaction or attempted submit, preserve their typed value after errors, and explain exactly how to fix invalid or missing text." ], "uiExamples": { "good": [ "A reference-name field has a visible label, hint, medium width, focus ring, and error message beneath the hint when submitted empty.", "A short-code field uses a narrow width while a project-title field uses a wider input, so the visible size matches the expected answer." ], "bad": [ "The only instruction is placeholder text that disappears when the user starts typing.", "A full-width single-line field asks for a detailed explanation, while error text appears far away and is not tied to the field." ] }, "uxExamples": { "good": [ "A user types or pastes a short reference, submits it, and the interface confirms the stored value without changing their wording.", "A user leaves the required field blank, sees an error only after submit, returns to the same field, and their later typed value clears the error." ], "bad": [ "Validation fires on the first focus event and blocks typing before the user has had a chance to answer.", "Pasted text is silently truncated or transformed, so the user cannot trust what will be submitted." ] }, "problemContext": [ "The answer is short, user-authored, and not reliably predictable as a fixed option.", "The field may be required, optional, readonly, disabled, or returned from the server with a validation error.", "Users may rely on keyboard, screen reader, browser autofill, paste, mobile keyboards, and zoomed layouts." ], "selectionRules": [ "Choose text input when the user enters a short freeform value such as a reference, title, identifier, one-line note, or organization name.", "Prefer textarea when line breaks, paragraphs, or long-form review are expected.", "Prefer autocomplete when the typed value should resolve to one known record or constrained option.", "Prefer select or radio group when the valid answer is a finite predetermined choice.", "Use specialized inputs when format-specific behavior matters, such as email, password, phone, date, numeric code, payment card, input mask, prefix, or suffix.", "Show a persistent label; do not rely on placeholder text to communicate the question or required format.", "Match input width to the expected answer length and avoid using field width as decoration.", "Validate after blur or submit, preserve typed content, and associate hint and error text with the input." ], "requiredStates": [ "Empty untouched state with persistent label and optional hint.", "Focused state with visible focus indicator.", "Filled valid state showing the typed value exactly as entered.", "Required missing-value error state after attempted submit.", "Invalid format or too-long state with actionable error text.", "Disabled state when the value cannot be changed.", "Readonly state when the value is shown but not editable.", "Autofilled or pasted-value state that remains reviewable before submit." ], "interactionContract": [ "Typing, deleting, selection, undo, and paste operate like a native single-line text field.", "The visible label remains available before, during, and after text entry.", "Hint and error text are associated through descriptive relationships when present.", "Submitting a required blank field moves the user to a fixable error without clearing other entered values.", "Changing the value after an error updates status without hiding the label or moving focus unexpectedly.", "Browser autocomplete, autocapitalize, spellcheck, and inputmode are configured only when they match the field purpose." ], "implementationChecklist": [ "Use a native input element with a stable id, name, and label element before building a custom field.", "Add hint text near the field and include both hint and error IDs in aria-describedby when they exist.", "Choose type, autocomplete, inputmode, autocapitalize, spellcheck, maxlength, and width based on the specific data being requested.", "Implement required and format validation after interaction or attempted submit, not on initial render.", "Preserve the user's entered value across client validation, server validation, navigation back, and failed submission.", "Test keyboard focus, screen reader label announcement, zoom, mobile orientation, paste, undo, autofill, disabled, readonly, and forced-colors modes.", "Avoid silent trimming, casing, masking, or truncation unless the transformation is previewed and reversible." ], "commonMisuses": [ "Using placeholder text as the only label or instruction.", "Using one single-line field for paragraph answers that need textarea behavior.", "Using text input for predetermined choices that should be select, radio, or autocomplete.", "Showing validation before the user interacts with the field.", "Clearing a user's typed value after an error.", "Silently truncating pasted content.", "Using an input width that implies the wrong answer length.", "Marking a disabled field as the only path to completing the task without explaining why it is locked." ], "critiqueQuestions": [ "Is the answer genuinely short and freeform, or is it a known choice, long answer, or specialized format?", "Does the label remain visible after typing and is the accessible name the same question users see?", "Does the width imply the right answer length?", "When and how does validation appear, and does it preserve the user's value?", "Can users paste, undo, autofill, and return from errors without losing data?" ], "relatedPatterns": [ "autocomplete", "select", "radio-group", "inline-validation", "error-summary" ], "comparisons": [ "text-input-vs-autocomplete-vs-select-vs-radio-group" ], "sourceIds": [ "govuk-text-input-component", "uswds-text-input-component", "wai-aria-apg-names-and-descriptions" ] }, { "id": "textarea", "completionStatus": "complete", "name": "Textarea", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Multi-line freeform writing field", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to provide longer freeform explanations, but cramped fields, hidden limits, vague hints, early validation, or draft loss make long-answer entry risky and hard to review.", "solution": "Provide a labelled multi-line textarea with enough visible rows, stable hint and error text, optional count for real limits, native editing behavior, and preservation of drafted text across validation and navigation.", "uiGuidance": [ "Render a persistent label, enough visible rows for the expected answer, optional hint, readable multiline text, visible focus state, and nearby error or count text associated with the textarea.", "Show line wrapping, vertical review space, disabled and error states, and character-count feedback only when a real content limit or writing constraint exists." ], "uxGuidance": [ "Use textarea when users need to write or paste sentences, paragraphs, explanations, notes, or comments that may wrap across lines.", "Preserve long drafted text through validation, back navigation, and submission errors; validate after interaction or submit with specific empty, too-short, too-long, or disallowed-character messages." ], "uiExamples": { "good": [ "A more-detail field has a visible question, sensitive-data hint, five visible rows, wrapping text, remaining-character count, and an error directly above the textarea when needed.", "A long answer preview keeps multiple lines visible so users can review paragraph structure before submitting." ], "bad": [ "A paragraph question is squeezed into a single-line input that hides most of the answer.", "The only instruction appears inside the field and disappears after typing, while a character limit is revealed only after submit." ] }, "uxExamples": { "good": [ "A user writes two paragraphs, sees remaining characters update, submits, and the exact line breaks and wording are preserved.", "A user submits an empty textarea, sees a specific local error, adds text, and the error state clears without losing the draft." ], "bad": [ "A user writes a long explanation, hits submit, and the product clears the entire draft after a length error.", "A hidden hard limit silently truncates pasted paragraphs, so the submitted explanation is incomplete." ] }, "problemContext": [ "The answer is freeform and may include sentences, paragraphs, pasted text, or line breaks.", "The product may need to warn users about sensitive information, maximum length, minimum detail, or disallowed characters.", "Users may spend significant time composing the answer and expect editing, undo, paste, spellcheck, mobile keyboard, and back navigation to preserve their work." ], "selectionRules": [ "Choose textarea when the expected response is more than a short single-line answer.", "Use enough visible rows for users to review the likely answer without excessive scrolling.", "Prefer text input for short values that should not include line breaks.", "Add a character count only when there is a real limit or users need help staying within a policy constraint.", "Use rich text editing only when formatting, links, headings, lists, or structured content are part of the task.", "Explain sensitive-data restrictions in hint text before users start writing.", "Validate required, too-short, too-long, and disallowed-character states after interaction or attempted submit.", "Preserve text exactly, including line breaks, unless the product previews and explains a transformation." ], "requiredStates": [ "Empty untouched state with visible label and optional hint.", "Focused writing state with caret, wrapping text, and visible focus indicator.", "Filled multi-line state preserving line breaks and pasted content.", "Remaining-count state when a real maximum length is configured.", "Required empty error state after attempted submit.", "Too-long or too-short error state with specific length guidance.", "Disabled state when the textarea cannot be edited.", "Recovered draft state after validation or navigation back." ], "interactionContract": [ "Typing, selection, line breaks, paste, undo, redo, and spellcheck follow native textarea behavior.", "The label remains visible while the user writes and reviews multiple lines.", "Hint, count, and error text are associated with the textarea when present.", "Submitting invalid long text keeps the user's draft in place and explains the exact fix.", "Character count updates as text changes and does not replace specific validation errors.", "Tab leaves the textarea in normal form order unless the product intentionally supports tab insertion and documents it." ], "implementationChecklist": [ "Use a native textarea with id, name, rows, label, and descriptive associations before creating a custom editor.", "Set rows and CSS resizing behavior to suit expected answer length and page layout.", "Add hint text for examples, sensitive information, expected detail, or content restrictions.", "Add maxlength and remaining-count feedback only for real limits; include too-long recovery text on submit.", "Preserve textarea value across client validation, server validation, page reload, browser back, and draft restore paths.", "Configure spellcheck, autocapitalize, autocomplete, and disabled state based on the content being collected.", "Test keyboard editing, screen reader label and description announcement, paste, line breaks, mobile keyboard coverage, zoom, and long-text scrolling." ], "commonMisuses": [ "Using a single-line input for paragraph answers.", "Using textarea for short codes, names, or titles that should stay one line.", "Clearing a long draft after validation fails.", "Showing a hard character limit only after submit.", "Silently truncating pasted paragraphs.", "Using a rich text editor for plain text comments.", "Making the textarea so short that users cannot review what they wrote.", "Leaving sensitive-data instructions until after the user has already written the answer." ], "critiqueQuestions": [ "Does this answer need multiple lines, paragraph review, or pasted long text?", "Can users see enough of their answer to review it before submitting?", "Are character limits real, visible, and recoverable?", "Are hint, count, and error text announced with the textarea?", "Will drafts survive validation failures, reloads, and navigation back?" ], "relatedPatterns": [ "text-input", "inline-validation", "error-summary" ], "comparisons": [ "textarea-vs-text-input-vs-inline-validation-vs-error-summary" ], "sourceIds": [ "govuk-textarea-component", "uswds-text-input-component", "uswds-character-count-component", "wai-aria-apg-names-and-descriptions" ] }, { "id": "threaded-discussion", "completionStatus": "complete", "name": "Threaded discussion", "category": "Collaboration And Social Interaction", "patternType": "ui-ux", "surfaceType": "Topic-centered conversation with parent post, reply branches, unread participation state, and thread-level controls", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Topic conversations become hard to follow when replies flatten into one stream, parent context disappears, notification links lose position, branch depth breaks mobile reading, or answer and unread state are not tied to the right reply branch.", "solution": "Provide a thread surface with persistent parent context, reply targets, branch depth, unread and last-read state, follow or mute controls, answer or resolution state, scoped moderation, pagination or load-more behavior, and direct links to specific replies.", "uiGuidance": [ "Render a threaded discussion around a visible parent topic or parent message, with reply rows that preserve author, timestamp, reply target, branch depth, unread or new state, and thread-scoped actions.", "Show participation controls such as reply, follow, mute, mark read, mark answer, copy thread link, collapse branch, load replies, and moderation as controls scoped to the thread or branch they affect." ], "uxGuidance": [ "Use threaded discussion when users need to follow, contribute to, or resolve a conversation that branches from one topic, question, channel message, or post and must keep replies understandable over time.", "Preserve parent context, reply target, branch position, unread counts, answer state, pagination boundary, and notification return point across route changes, loading, moderation, and mobile layout." ], "uiExamples": { "good": [ "A support topic shows the original question, three top-level replies, one expanded reply branch, an accepted answer badge, unread branch marker, and thread-level Follow and Mute controls.", "A channel message opens a side thread with parent message pinned at the top, reply composer at the bottom, and a checkbox to also share the reply back to the main channel." ], "bad": [ "All replies are rendered as identical flat messages with no indication of which parent or branch they answer.", "Nested replies are indented until they become unreadable on mobile and the answer is hidden below collapsed context." ] }, "uxExamples": { "good": [ "A user opens a notification to a specific unread reply, sees the parent post and branch context, replies, marks the answer, and mutes future replies after resolution.", "A user loads older replies, collapses an off-topic branch, follows only the current thread, and returns later to the exact last-read reply." ], "bad": [ "A user clicks New reply and lands at the top of a long topic with no highlight, branch context, or last-read position.", "A moderator marks an answer but the thread summary still shows unanswered because answer state is stored only on the visible reply card." ] }, "problemContext": [ "Users are discussing one topic, question, announcement, channel message, support issue, forum post, design proposal, or community thread.", "Replies may be top-level, nested under another reply, marked as an answer, collapsed, hidden, moderated, unread, followed, muted, paginated, or broadcast back to a main channel.", "The same activity may also appear in feeds or notifications, but the discussion surface owns the parent topic, branch context, reply relationships, and participation state.", "The conversation may continue over hours or days and users may return through unread lists, direct reply links, search, or notification center." ], "selectionRules": [ "Choose threaded discussion when the core unit is a topic or parent message with replies that need branch context and participation state.", "Use comments when feedback is anchored to a specific object, selection, file line, record, or task rather than a navigable topic conversation.", "Use feed when users primarily browse a stream of many independent posts, not one open discussion with reply hierarchy.", "Use notification center when users need cross-object unread triage, retention, and preference controls rather than the thread's full reply context.", "Use activity log when entries are system facts or audit events, not authored replies that can branch, react, or be marked as answers.", "Use review queue when many threads need moderation, assignment, bulk triage, or SLA processing.", "Avoid deep visual indentation beyond a readable mobile depth; switch to branch cards, quoted parent snippets, or collapse controls.", "Keep answer, resolved, unread, followed, muted, and hidden states attached to the exact branch or reply they describe." ], "requiredStates": [ "Parent topic or parent message with author, timestamp, title or body, category, and reply count.", "Top-level reply, nested reply, quoted parent snippet, and collapsed branch states.", "Unread reply, last-read marker, followed, muted, mentioned, and notification-deep-linked reply states.", "Reply composer, draft reply, saving reply, failed reply, retry, and recovered draft states.", "Accepted answer, unmarked answer, resolved branch, reopened branch, hidden or moderated reply, and deleted reply states.", "Load newer, load older, has more replies, empty branch, access-limited branch, and outdated or moved parent states.", "Mobile stacked state where parent context and reply target remain visible without excessive indentation.", "Direct-linked reply state that scrolls and focuses the target while keeping parent topic context visible." ], "interactionContract": [ "Starting a reply records the exact parent topic or parent reply being answered and shows that target while composing.", "Submitting a reply appends it to the correct branch, updates reply count, unread state, subscribed state, and any notification or broadcast behavior.", "Following or muting a thread changes notifications for that thread without changing channel, feed, or global notification preferences by accident.", "Marking an answer or resolving a branch updates the thread summary and keeps the marked reply findable when the branch is collapsed or paginated.", "Direct links, unread lists, and notifications open the exact reply or branch, highlight it, and preserve parent context.", "Loading more replies preserves the user's position and announces the new reply boundary rather than shifting focus unexpectedly.", "Moderation actions such as hide, delete, lock, or report remain scoped to the selected reply or branch and leave appropriate reason or history evidence." ], "implementationChecklist": [ "Model parent discussion, reply id, parent reply id, branch path, author, timestamp, body, answer state, unread state, subscription state, moderation state, and pagination cursor separately.", "Design parent context, reply cards, nested branch affordance, composer target, branch collapse, load controls, and last-read marker before adding reactions or badges.", "Provide follow, mute, mark read, reply, quote, mark answer, copy link, collapse, load more, report, hide, delete, and lock behavior only where product rules support them.", "Preserve drafts, scroll position, focused branch, and reply target across reload, route return, failed save, offline retry, and permission changes.", "Keep mobile layouts readable by limiting visual indentation and using quoted parent context or branch headers for deep replies.", "Test direct links, unread return, answer marking, collapsed branches, pagination, hidden replies, deleted parent replies, permission-limited threads, and long nested conversations." ], "commonMisuses": [ "Flattening every reply into a chronological stream and losing who replied to whom.", "Using a threaded discussion for simple object comments where the anchor matters more than topic navigation.", "Letting nested indentation consume the viewport on mobile.", "Showing unread count for the whole thread without identifying which branch changed.", "Hiding accepted answers, resolved replies, or moderation state inside collapsed branches.", "Broadcasting every thread reply back to a main channel and recreating the noise threading was meant to reduce.", "Using feed ranking inside a thread so reply order and branch context become unpredictable.", "Treating a thread as an audit log and allowing edited or deleted replies to erase decision evidence." ], "critiqueQuestions": [ "What parent topic or message owns this thread?", "Can users tell which reply each nested reply is answering?", "What happens when a notification points to a reply that is collapsed, hidden, paginated, or deleted?", "How do follow, mute, mention, unread, and last-read states interact?", "Can answer, resolved, hidden, or deleted state be found from the thread summary?", "Does the mobile layout preserve branch context without deep indentation?" ], "relatedPatterns": [ "comments", "feed", "notification-center", "activity-log", "review-queue", "accordion", "pagination", "search-result-highlighting" ], "comparisons": [ "threaded-discussion-vs-comments-vs-feed-vs-notification-center" ], "sourceIds": [ "slack-threads-organize-discussions", "github-discussions-participating", "slack-conversations-replies-api" ] }, { "id": "time-picker", "completionStatus": "complete", "name": "Time picker", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Time input with filtered slot list, period selector, and timezone selector", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Scheduling workflows need precise clock times, but plain text can hide invalid increments and ambiguous periods while oversized dropdowns or masks make nearby time selection slow, inaccessible, or easy to misinterpret.", "solution": "Provide a labelled time picker that filters familiar time strings, presents valid increments, separates AM/PM and timezone when needed, validates range and step rules, blocks unavailable slots, and stores an unambiguous canonical time.", "uiGuidance": [ "Render a labelled time field with persistent hint text, filtered time suggestions, clear selected state, AM/PM control when using 12-hour display, and timezone control when interpretation depends on location.", "Show allowed hours, minute increments, unavailable slots, selected time, invalid field, and canonical stored value without relying on the typed display string alone." ], "uxGuidance": [ "Use a time picker when users are scheduling or choosing a specific clock time from predictable increments such as 15-minute or 30-minute appointments.", "Let users type to filter familiar option strings, choose with keyboard or pointer, correct AM/PM and timezone independently, and submit only after validation confirms range, step, and availability." ], "uiExamples": { "good": [ "An appointment time field shows a label, hint that typing filters 30-minute slots, a 9:30 AM selected option, AM/PM selector, Eastern timezone selector, and canonical value 09:30:00.", "A store pickup time picker disables unavailable 12:00 PM and 12:30 PM slots while preserving visible 30-minute increments around them." ], "bad": [ "A single field labelled Time accepts 930 and silently stores it without AM/PM, timezone, or validation message.", "A dropdown lists 1,440 minute-by-minute options even though appointments are only available every half hour." ] }, "uxExamples": { "good": [ "A user types 9, filters the list to 9:00 AM and 9:30 AM, chooses 9:30 AM, selects Eastern time, and submits canonical value 09:30:00 America/New_York.", "A user enters 09:45 for a 30-minute appointment schedule, sees a step error, fixes only the minutes, and keeps the selected timezone." ], "bad": [ "A user chooses 2:00 from a list and the service books 2:00 AM because no period selector or timezone context was shown.", "A historical time-of-birth field forces a scheduling dropdown even though the user needs to type the exact recorded time." ] }, "problemContext": [ "The user is choosing a specific time for an appointment, meeting, reminder, delivery, pickup, service window, or deadline.", "The product accepts times only in consistent increments such as 5, 15, or 30 minutes.", "The meaning of the time may depend on AM/PM, locale, timezone, store, office, or service location.", "Some time slots may be unavailable because of operating hours, capacity, holidays, or staffing.", "The backend needs a normalized 24-hour value even when the UI uses localized 12-hour display." ], "selectionRules": [ "Choose time picker when users need a specific schedulable clock time from predictable increments.", "Use text input when the answer is approximate, historical, unknown, or naturally written in words.", "Use select or radio controls when the only valid choices are broad windows such as Morning, Afternoon, or Evening.", "Use input mask only when a strict time code is required and the interaction still supports paste, correction, and clear errors.", "Do not use a date picker or date range picker to collect time of day unless date and time are deliberately combined in one workflow.", "Use 12-hour display with an explicit AM/PM control when that is familiar to the audience.", "Use 24-hour display when the domain expects it, such as transportation, operations, healthcare, or international scheduling.", "Show timezone or location whenever the same displayed time could refer to different moments.", "Make increments match real availability, not arbitrary minute lists.", "Validate required value, time format, min time, max time, step increment, unavailable slots, AM/PM, and timezone before submission." ], "requiredStates": [ "Empty labelled time field with persistent hint and optional timezone default.", "Focused typed-query state that filters available time options.", "Open suggestion list with valid increments and unavailable slots distinguished.", "Selected time state synchronized with AM/PM and timezone selectors.", "Manual typed value state that preserves user edits before validation.", "Invalid format error state for values that are not parseable times.", "Off-step error state for times outside the configured increment.", "Out-of-hours error state for times before minimum or after maximum.", "Unavailable slot error state for capacity-blocked times.", "Submitted state showing canonical 24-hour time and timezone." ], "interactionContract": [ "Typing filters option strings without erasing the raw typed value.", "Arrow keys move through filtered options and Enter commits the highlighted option.", "Selecting an option writes the display time but does not submit the surrounding form.", "Changing AM/PM updates the canonical value without changing typed minutes.", "Changing timezone preserves local time unless the workflow explicitly converts across zones.", "Submitting validates format, hour range, minute increment, unavailable slots, AM/PM, timezone, and required state together.", "Errors identify the failing factor, such as minutes must be 00 or 30, time is outside clinic hours, or choose a timezone." ], "implementationChecklist": [ "Define the time purpose, accepted increments, minimum time, maximum time, unavailable slots, locale display, AM/PM policy, timezone policy, and canonical storage format.", "Build a labelled input or combobox with persistent hint text, filtered suggestions, selected option, empty query state, unavailable option state, AM/PM selector, and timezone selector when required.", "Generate option labels with familiar strings such as 9:00 AM while storing canonical leading-zero 24-hour values.", "Validate typed and selected values with the same range, step, availability, timezone, and required-field rules on client and server.", "Keep user-entered values visible after validation errors and mark only the field or selector that caused the error.", "Test keyboard filtering, screen readers, browser autofill, mobile time keyboards, localization, 12-hour and 24-hour formats, timezone changes, unavailable slots, and server-returned errors.", "Avoid automatic submission or result refresh when a user highlights, filters, or selects a time." ], "commonMisuses": [ "Using a minute-by-minute dropdown for a schedule that only accepts 30-minute increments.", "Storing 2:00 without AM/PM or timezone context.", "Using a rigid mask that rejects valid localized entry or paste.", "Auto-submitting when a time option is selected.", "Showing only HH:mm text to users who expect 12-hour time with AM and PM.", "Applying the same error style to every field instead of naming hour, minute, period, timezone, range, or availability failure.", "Forcing a picker for exact historic times that users need to type from a document." ], "critiqueQuestions": [ "Is the user scheduling a future service time, or entering a remembered or historical exact time?", "What increments are actually bookable, and how will unavailable slots be represented?", "Does the audience expect 12-hour time, 24-hour time, or both?", "Which timezone or location gives meaning to this time?", "Can users type, filter, select, correct, paste, and submit without losing their value?", "What canonical time string does the backend receive?" ], "relatedPatterns": [ "text-input", "select", "input-mask", "date-picker", "inline-validation", "error-summary" ], "comparisons": [ "time-picker-vs-text-input-vs-select-vs-input-mask" ], "sourceIds": [ "uswds-time-picker-component", "carbon-time-picker-guidance", "mdn-html-time-input", "shopify-pos-time-picker-component" ] }, { "id": "timeline", "completionStatus": "complete", "name": "Timeline", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Bounded chronological record of past, current, or expected events", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users often need to understand a sequence of important events around a case, order, application, incident, or process, but raw logs, feeds, tables, or step indicators can obscure time order, current state, actor context, and what happened next.", "solution": "Present a bounded chronological timeline with clear event markers, dates, actors, summaries, status, current and future distinctions, grouping, optional expansion, filtering, loading, and routes to detailed records when the timeline summary is not enough.", "uiGuidance": [ "Render the timeline as a labelled chronological sequence where each event has a visible date or time, event title, actor or system source when known, status or type, and a short summary.", "Use a clear connector, marker, grouping label, or range boundary only to reinforce time order; do not let the line or icon replace event text, timestamps, or source labels." ], "uxGuidance": [ "Use timeline when users need to understand what happened, where they are now, and what may happen next in a case, claim, application, order, incident, or process.", "Keep timeline items brief enough for scanning, preserve chronological order under filtering or loading, and route detailed evidence, dense logs, or current-step progress to more appropriate surfaces." ], "uiExamples": { "good": [ "A benefits application timeline groups events by date and shows Application submitted, Evidence requested, Evidence received, Decision pending, and Next review, with actor, timestamp, and status marker.", "An order timeline shows Created, Paid, Packed, Carrier handoff, Delivery exception, and Expected delivery, with current and future markers visually distinct." ], "bad": [ "A vertical line lists Approved, More, Update, and Done with no dates, actors, status, or explanation.", "A dense audit table is squeezed into timeline cards and hides changed fields, exact actor identity, and retention proof." ] }, "uxExamples": { "good": [ "A caseworker filters the timeline to System events, sees two date groups hidden, restores all events, and the event order and current marker stay stable.", "A claimant expands one event for supporting detail, then collapses it without losing their place in the overall timeline." ], "bad": [ "A user sees a future appointment marker styled like completed history and assumes the appointment already happened.", "A timeline replaces a stepper inside a form, so users cannot tell which current step is complete or blocked." ] }, "problemContext": [ "Events belong to one case, claim, order, application, person, incident, project, shipment, or process.", "Users need to understand sequence and causality more than compare columns, consume live updates, or complete current form steps.", "Events may be generated by people, systems, integrations, or scheduled milestones.", "The timeline may include past events, the current event, expected future events, collapsed groups, filters, or links to source records." ], "selectionRules": [ "Choose timeline when the main user question is what happened, when it happened, who or what caused it, and what came next.", "Use feed when items keep arriving as a dynamic stream and reading-position preservation is central.", "Use activity log or audit log when users need exhaustive, immutable, compliance-grade evidence, field-level changes, actor IDs, retention, export, or search across logs.", "Use process list when users need planned journey guidance and task links rather than a record of events.", "Use step navigation when users are inside a current linear task and progress must reflect validated route state.", "Use table or data grid when users need to compare many events by shared columns, sort by multiple fields, or export records.", "Keep timeline items short and link to details instead of turning each event into a full case note.", "Label current and future expected events differently from completed historical events.", "Group long histories by date, phase, month, or status range while preserving visible order and hidden-count context.", "Avoid timeline when event order is uncertain, unimportant, or likely to be misread as causality." ], "requiredStates": [ "Default timeline with heading, order label, date or phase groups, and event markers.", "Past, current, expected future, cancelled, failed, warning, and system-generated event states.", "Expanded and collapsed event detail states.", "Filtered, grouped, searched, paginated, loading-more, no-events, and failed-load states.", "Hidden-range or hidden-filter count state when not all events are visible.", "Unknown time, approximate time, corrected timestamp, timezone, and duplicate-event states when applicable.", "Responsive narrow-screen state where date, title, actor, status, and actions remain readable.", "Linked source-record state when users need deeper case notes, documents, messages, or audit evidence." ], "interactionContract": [ "Each event has one stable identity, timestamp or date label, event title, and actor or system source when known.", "The visual marker and connector reinforce chronological order but do not carry the only meaning.", "Filtering and grouping never reorder events without stating the active order and hidden range.", "Expanding an event reveals supporting detail in place without hiding adjacent dates or changing event identity.", "Opening a source record preserves return context to the same event or date group.", "Current and future items are visually and textually distinct from completed history.", "Corrected, approximate, unknown, or timezone-sensitive times are labelled rather than silently normalized.", "Long timelines expose load, pagination, or range controls that preserve date boundaries and focus." ], "implementationChecklist": [ "Define event identity, timestamp, date granularity, actor, source system, title, summary, status, type, detail route, and whether the item is past, current, or future.", "Choose the default order and state it in the UI, such as newest first, oldest first, grouped by date, or grouped by phase.", "Use semantic list structure with headings or time elements for date groups and event titles.", "Provide text labels for markers such as current, expected, failed, cancelled, system, warning, or corrected time.", "Add expansion only for concise supporting detail; route dense notes, documents, audit evidence, and comments to dedicated records.", "Design filters and range loading with visible hidden counts, active filters, empty results, retry, and order preservation.", "Preserve focus and scroll position when expanding events, filtering, loading older events, or returning from source records.", "Test long titles, missing actors, approximate dates, localization, timezones, keyboard order, screen-reader date grouping, and mobile wrapping." ], "commonMisuses": [ "Using timeline as decorative chrome around a normal list with no meaningful time sequence.", "Omitting dates, actors, or event summaries and expecting icons to communicate the sequence.", "Mixing future tasks and completed events without text that distinguishes expectation from history.", "Replacing audit logs with simplified timeline summaries when users need exact evidence.", "Replacing a feed with timeline visuals while live insertion and ranking behavior remain unresolved.", "Replacing step navigation inside a form with a timeline that cannot validate progress.", "Letting filters or groups hide events without counts or range labels.", "Treating event order as causality when the product only knows timestamps." ], "critiqueQuestions": [ "What object, case, order, application, or process does this timeline belong to?", "Are users trying to understand event sequence, consume a live stream, follow a planned process, or complete current steps?", "Which event fields are required: date, time, actor, source, status, event type, summary, document, or action?", "How are current and future expected events distinguished from completed past events?", "What happens when events are filtered, grouped, corrected, duplicated, missing timestamps, or loaded in ranges?", "Would feed, activity log, audit log, process list, step navigation, table, or data grid better fit the task?" ], "relatedPatterns": [ "feed", "list-view", "process-list", "step-navigation", "notification-center", "filter-panel", "sort-controls", "pagination", "details-panel", "empty-state" ], "comparisons": [ "timeline-vs-feed-vs-process-list-vs-step-navigation" ], "sourceIds": [ "moj-design-system-timeline", "nhs-app-timeline", "dwp-design-system-timeline", "ons-service-manual-timeline", "home-office-design-system-timeline" ] }, { "id": "toast-notification", "completionStatus": "complete", "name": "Toast notification", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Transient non-modal status message", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need brief feedback that an action or background process changed state, but interruptive dialogs or persistent page messages would slow the task.", "solution": "Show a concise non-modal toast in a consistent status region, announce it appropriately, bound its duration and stack behavior, and provide persistent access whenever the message matters after it disappears.", "uiGuidance": [ "Render toast notifications in a consistent non-modal region with short status text, clear severity, an optional close control, and at most one concise action.", "Keep the toast stack bounded, avoid covering current task controls, and provide a durable route such as history, notification center, or contextual status for messages users may need after dismissal." ], "uxGuidance": [ "Use toast notifications for low-risk, short-lived feedback after an action completes or background work changes state without requiring the user to stop the current task.", "Escalate to inline, section, dialog, notification center, undo, or error-state treatment when the message requires repair, proof, long reading time, several actions, or reliable recovery." ], "uiExamples": { "good": [ "Export started appears in the top notification region with a timestamp, close control, and View jobs action that remains available in activity history.", "Saved appears once after a deliberate save action and auto-expires without moving focus from the edited record." ], "bad": [ "Five unrelated toasts pile up over the Save and Continue controls.", "A long payment failure and support code are squeezed into a disappearing corner toast." ] }, "uxExamples": { "good": [ "A completed archive action shows a short toast and a specific Undo action because the prior state can be restored.", "When the export-ready toast expires, the same item remains reachable from the notification history." ], "bad": [ "Every autosave tick triggers a toast, training users to ignore real status changes.", "The only explanation for failed sync disappears while the record still looks current." ] }, "problemContext": [ "A user action succeeds, is queued, or changes low-risk state while the user can keep working.", "A background process such as export, sync, upload, invitation, or archive needs short status feedback.", "The message can be understood quickly and does not need multiple controls, long instructions, or blocking recovery.", "The product has a plan for durable access when the message includes a job, receipt, audit event, undo action, or later result." ], "selectionRules": [ "Choose a toast for short non-blocking confirmation, progress handoff, background-job status, or low-risk warning that does not require users to stop the current task.", "Use a persistent inline notification, error state, dialog, banner, or notification center when the message is critical, long, legally important, requires repair, or must remain available.", "Use undo only when the toast action can restore the exact prior state; otherwise label the action as View, Retry, Open jobs, or another truthful next step.", "Keep toast copy specific enough to name the object or process, such as Export started for April invoices, rather than Done or Success.", "Limit each toast to one primary action and move multi-step workflows into a page, panel, dialog, or notification center.", "Cap the visible stack and place newer messages consistently so users are not forced to manage a wall of notifications.", "Provide close behavior for visible toasts and respect reduced-motion or timing needs when animating entry and exit.", "Preserve important expired toast messages in history when users may need to reference or act on them later." ], "requiredStates": [ "Idle state with no visible toast and a reachable status or history region when applicable.", "New toast state that announces the message without stealing focus from the current task.", "Stacked state with newest and older messages ordered predictably and capped.", "Actionable toast state with one short action and enough persistence to activate it.", "Dismissed state after the user closes one toast.", "Expired state after time-based dismissal, with durable history for messages that remain relevant.", "Escalated state where critical or long feedback is routed to persistent UI instead of a toast." ], "interactionContract": [ "A toast appears because a specific action or system event occurred, not as the only visible structure for the task itself.", "The current page remains operable while the toast is visible.", "The toast does not move keyboard focus unless it contains an action that intentionally receives focus and remains available long enough to use.", "Users can dismiss a visible toast without losing the underlying task state.", "If a toast auto-dismisses, the product either makes the message safely disposable or stores it in a place users can revisit.", "New toasts do not overwrite earlier actionable or important messages without preserving their outcome.", "Critical failures, long instructions, and multi-step recovery are escalated out of the toast layer." ], "implementationChecklist": [ "Classify each candidate message by consequence, required action, and whether users may need to revisit it.", "Use a single notification region per viewport and choose placement that does not cover navigation, form submits, chat input, or primary task controls.", "Write a short title or message that names the object, action, and result.", "Use role status for neutral or success updates and alert only for urgent warnings that still do not need persistent recovery.", "Keep an optional action short, object-scoped, and limited to one command.", "Set sensible duration rules by severity and action presence; actionable toasts should persist until dismissed or acted on.", "Queue or cap simultaneous messages, and send older important items to history instead of hiding them silently.", "Make close controls keyboard reachable and give them accessible names that include the toast subject.", "Test with keyboard, screen reader announcements, zoom, reduced motion, slow reading, and repeated background events." ], "commonMisuses": [ "Using a toast as the only feedback for payment, save, permission, upload, or security failures.", "Showing repeated autosave confirmations so frequently that users ignore every status message.", "Packing long explanations, links, forms, or multiple buttons into a tiny transient surface.", "Stacking messages until they cover primary actions or content.", "Using vague copy such as Done, Failed, or Updated without naming the affected object.", "Auto-dismissing an Undo action before users can perceive and activate it.", "Moving focus to every toast and disrupting keyboard or screen reader workflows." ], "critiqueQuestions": [ "Is this message disposable after a few seconds, or does the user need to revisit it?", "What object, job, or action changed, and does the toast name it?", "Would losing the toast make the current state unsafe, ambiguous, unpaid, unsaved, or unrecoverable?", "Is one concise action enough, or does this need a persistent surface?", "Can keyboard and assistive technology users perceive, dismiss, and act on the toast without a timing trap?", "What happens when several events fire in a row?" ], "relatedPatterns": [ "toast-only-critical-error", "error-state", "undo", "loading-skeleton", "utility-navigation" ], "comparisons": [ "toast-notification-vs-toast-only-critical-error-vs-error-state-vs-undo" ], "sourceIds": [ "carbon-notification-component", "material-design-snackbar", "adobe-spectrum-toast", "wcag-status-messages" ] }, { "id": "toast-only-critical-error", "completionStatus": "complete", "name": "Toast-only critical error", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Transient critical-feedback anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "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.", "solution": "Treat the toast-only critical error as an anti-pattern: keep the failure and recovery controls persistently attached to the affected task, and use any toast as supplemental feedback only.", "uiGuidance": [ "Replace a lone disappearing toast with a persistent failure region attached to the affected task, using a heading that names the failed payment, save, upload, permission, or destructive action.", "If a toast is still useful for awareness, keep it short and supplemental while the full cause, consequence, reference, and recovery controls remain visible elsewhere." ], "uxGuidance": [ "Protect users from losing the only explanation for a high-consequence failure by keeping the problem, affected object, and next action available after the notification times out.", "Design recovery around what users must do next: retry the operation, correct details, restore or undo a change, use an alternate route, or contact support with a retained reference." ], "uiExamples": { "good": [ "A failed invoice payment leaves a persistent alert inside the invoice panel with Retry payment, Update card, and Contact billing actions.", "A short toast says Payment failed, but it links back to the same persistent invoice error that remains after the toast closes." ], "bad": [ "A small Payment failed toast appears at the corner and disappears while the invoice panel shows no recovery action.", "A failed file upload reports Error in a snackbar, clears the selected file, and leaves no support reference." ] }, "uxExamples": { "good": [ "After the notification disappears, users can still see that the invoice is unpaid, why payment failed, and which recovery actions are available.", "Retrying the failed operation preserves the payment or draft context and either returns to success or shows a still-failed state with escalation." ], "bad": [ "Users have to guess whether the payment, save, delete, or upload succeeded after the toast timed out.", "Keyboard and screen reader users hear a brief alert but cannot find the failed task or action afterward." ] }, "problemContext": [ "A payment, save, permission, destructive action, security, or data-integrity operation fails.", "The failed task still needs user action after the message appears.", "The only visible feedback is a toast, snackbar, banner flash, or notification that may auto-dismiss or sit away from the affected control.", "The product cannot guarantee the user saw, read, understood, and acted on the transient message before it disappeared." ], "selectionRules": [ "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." ], "requiredStates": [ "Pre-action state that shows what the user is attempting and what will be affected.", "Failed persistent state with the failed object, plain-language cause, and recovery actions.", "Supplemental notification state that does not replace the persistent failure surface.", "Recovered state after retry, correction, reversal, or support escalation succeeds.", "Still-failed state after a retry does not resolve the issue, with escalation or alternate path." ], "interactionContract": [ "The critical error remains visible until it is resolved, intentionally dismissed from a safe persistent surface, replaced by a recovered state, or escalated.", "The affected task stays connected to the recovery controls instead of making users search for the failed object after a notification disappears.", "A toast may announce that failure happened, but it must not be the only place where the cause, consequence, support reference, or next action appears.", "If the message auto-dismisses, users can still reach the same information and action from the failed task, notification center, activity log, or persistent error region.", "Keyboard and assistive technology users can reach the recovery action without relying on timing, hover, or a temporary live-region announcement." ], "implementationChecklist": [ "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." ], "commonMisuses": [ "Showing Payment failed as a small toast while the invoice page returns to its normal paid-or-unpaid layout with no retry path.", "Using a disappearing snackbar as the only feedback for failed save, failed delete, failed permission change, failed upload, or failed authentication.", "Placing the toast far from the failed form or table row so users cannot connect the message to the affected task.", "Auto-dismissing a technical error code that support needs the user to copy or reference.", "Replacing a contextual error state with a notification because it is easier to trigger from a global event handler." ], "critiqueQuestions": [ "If the user looks away for five seconds, can they still tell what failed and what to do next?", "Does the recovery action remain attached to the invoice, form, file, or account setting that failed?", "Would a screen reader or keyboard user be able to act after the transient announcement has finished?", "Is the toast communicating low-risk status, or is it carrying the only explanation for a high-consequence failure?" ], "relatedPatterns": [ "error-state", "undo", "confirmation-dialog", "error-summary" ], "comparisons": [ "toast-only-critical-error-vs-error-state" ], "sourceIds": [ "carbon-notification-component", "atlassian-error-messages", "va-error-messages" ] }, { "id": "toast-only-success-for-completed-transaction", "completionStatus": "complete", "name": "Toast-only success for completed transaction", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Transient-only completed-transaction anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "A consequential transaction completes, but the only success feedback is a transient toast that can disappear before users can verify the outcome, copy proof, understand next steps, or recover the receipt.", "solution": "Treat toast-only success for completed transaction as an anti-pattern: keep durable proof in a confirmation page or in-context success confirmation, use any toast only as supplemental awareness, and preserve receipt, reference, status, next-step, and support paths after the transient message is gone.", "uiGuidance": [ "Replace a lone success toast for completed transactions with a durable confirmation page or in-context success confirmation that names the completed transaction, reference, receipt, submitted details, and what happens next.", "If a toast is used at all, make it supplemental and link or point back to persistent proof; never let the timed notification be the only visible record of a payment, booking, application, account change, or submitted response." ], "uxGuidance": [ "Use this anti-pattern during review when a completed transaction clears context, redirects, or appears successful while proof, reference, receipt, next steps, and recovery paths are only present in a disappearing message.", "Design the corrected flow around the user's post-commit needs: verify completion, copy or save proof, understand timing, track status, amend or cancel when allowed, contact support, and start another transaction without losing the completed one." ], "uiExamples": { "good": [ "After submitting an application, a confirmation page says Application complete, shows reference APP-48291, explains the response window, and offers Save record and Track application.", "After adding evidence inside an ongoing case, a success confirmation near the evidence checklist says Evidence uploaded, shows receipt EV-2048, and keeps View receipt available.", "A short toast says Receipt ready, but the receipt card remains visible in the page and notification history." ], "bad": [ "A dashboard toast says Application submitted and disappears with no reference, receipt, next steps, or track link.", "A payment flow shows a Paid toast while the checkout form clears and no transaction ID or receipt is shown.", "A booking snackbar says Done, but users cannot verify the appointment time or cancellation path afterward." ] }, "uxExamples": { "good": [ "A user submits a benefits form, copies the reference, saves the receipt, reads that the agency will respond within 5 working days, and can return from a bookmark to a safe tracking route.", "A user finishes a booking, verifies location and time, emails the receipt, and starts another booking without confusing the two transactions." ], "bad": [ "A user looks away while the toast appears and later cannot prove whether the payment completed.", "A screen reader announces a brief success status but no focusable confirmation, receipt, or next-step content remains on the page.", "A submit handler shows success before the server commit finishes and later fails silently." ] }, "problemContext": [ "The user has completed or appears to have completed an application, booking, order, payment, account change, survey response, publication, approval, or service request.", "The transaction may need a reference number, receipt, submitted detail summary, next-step timing, tracking, contact, cancellation, amend, save, print, email, or support path.", "The implementation uses a toast, snackbar, flash, or temporary notification as the only completion proof or redirects users to a dashboard without durable confirmation.", "Users may look away, use assistive technology, close the page, refresh, return from browser history, contact support, or need proof later." ], "selectionRules": [ "Flag this anti-pattern when a committed or high-consequence transaction is confirmed only by a disappearing toast.", "Replace it with confirmation page when the transaction or service journey has ended.", "Replace it with success confirmation when the user stays in the same task but still needs durable object-specific proof.", "Allow toast notification only when success is low consequence, self-evident, and proof is not needed after the toast disappears.", "Show a transaction name, submitted object, reference or timestamp when useful, and what happens next.", "Keep save, print, email receipt, copy reference, track, amend, cancel, contact, or support actions available when they support the completed transaction.", "Do not show success before the authoritative commit, server acceptance, payment authorization, booking creation, or submission record exists.", "Use pending, offline mobile retry, sync state, progress, or error state when the transaction is queued, unaccepted, failed, denied, or still processing.", "Preserve a safe return route for bookmark, refresh, Back, duplicate submit, expired session, and history return scenarios.", "During generated UI review, flag handlers whose final step is only toast.success(...) or equivalent after clearing transaction state." ], "requiredStates": [ "Pre-submit state with the transaction and affected object visible.", "Committed confirmation state with durable proof after authoritative success.", "Receipt/reference state with copy, save, print, email, or tracking where useful.", "What-happens-next state with timing, owner, and user responsibility.", "Supplemental toast state that is not the only proof.", "Toast expired state where the durable confirmation still remains.", "Dashboard or return state that preserves transaction proof or a tracking route.", "Duplicate-submit protection state after commit.", "Failure, pending, queued, denied, or processing state that does not render as success.", "Start another transaction state that does not erase the completed receipt." ], "interactionContract": [ "The completed transaction remains provable after the toast expires.", "The user can identify what completed, when, and what reference or receipt proves it.", "Any transient toast points to or duplicates a durable confirmation surface rather than replacing it.", "The transaction context is not cleared until proof and next steps are rendered or safely reachable.", "Copy, save, print, email, tracking, contact, amend, cancel, and start-again actions preserve the completed transaction's identity.", "The UI prevents duplicate submit, refresh resubmit, or Back resubmit after commit.", "If the authoritative success event is not available, the UI stays pending, queued, retrying, or failed instead of showing completed success." ], "implementationChecklist": [ "Identify which actions are completed transactions rather than disposable status events.", "Define the authoritative commit event, reference, receipt, timestamp, object identity, submitted summary, and next-step content before rendering success.", "Choose confirmation page for journey endpoints and success confirmation for in-context proof.", "Use toast only as secondary notification and provide a route to the persistent confirmation.", "Keep proof visible through toast expiry, refresh, Back, bookmarked return, dashboard redirect, and session recovery where permitted.", "Remove or guard duplicate submit controls after commit and ensure refresh cannot replay the transaction.", "Write success copy with the transaction name and proof, not vague Done or Success.", "Test with screen reader timing, keyboard navigation, slow readers, mobile viewport, support-reference copying, print/save behavior, and interrupted attention." ], "commonMisuses": [ "Redirecting to a dashboard and showing a five-second Application submitted toast with no receipt page.", "Using a generic Done toast for payment, booking, order, application, and profile-change outcomes.", "Clearing the form immediately after submit without rendering a durable success state.", "Showing a toast before the server commit finishes.", "Putting the reference number only inside the toast.", "Hiding next steps, timing, or support path behind notification history.", "Letting users refresh or tap Submit again because no persistent completed state exists.", "Treating a queued offline or pending async action as completed transaction success." ], "critiqueQuestions": [ "If the toast disappears, can users still prove the transaction completed?", "What reference, receipt, timestamp, or submitted details might users need later?", "Does the UI explain what happens next and when?", "What authoritative event proves the transaction completed before success is shown?", "What happens on refresh, Back, duplicate submit, bookmark return, or expired session?", "Should this be a confirmation page, in-context success confirmation, or only a disposable toast?" ], "relatedPatterns": [ "confirmation-page", "success-confirmation", "toast-notification", "notification-banner", "offline-mobile-retry", "sync-state" ], "comparisons": [ "toast-only-success-for-completed-transaction-vs-confirmation-page-vs-success-confirmation-vs-toast-notification" ], "sourceIds": [ "govuk-confirmation-pages-pattern", "nhs-confirmation-page-pattern", "ons-confirmation-page-pattern", "carbon-notification-component", "wcag-status-messages" ] }, { "id": "toggle-switch", "completionStatus": "complete", "name": "Toggle switch", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Immediate binary setting control", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to turn one setting, feature, preference, or hardware-like option on or off and understand whether the change has taken effect.", "solution": "Present one stable label with a binary switch state, immediate reversible application, visible state text when helpful, and explicit pending, unavailable, disabled, or read-only states when the setting cannot simply flip.", "uiGuidance": [ "Render one switch with a stable visible label, clear on/off state, visible focus, accessible state, and optional state text when the effect is not obvious.", "Include pending, failed, unavailable, disabled, and read-only styling so asynchronous or blocked settings are not confused with successful state changes." ], "uxGuidance": [ "Let users change one reversible setting immediately and understand the applied effect.", "Avoid using switches for commands, destructive work, multi-value choices, consent, or staged form answers that should wait for a Save or Continue action." ], "uiExamples": { "good": [ "A notifications switch with a stable Notifications label, On or Off state text, large hit target, visible focus, and immediate applied effect.", "A disabled switch paired with dependency text that explains why the setting is unavailable." ], "bad": [ "A red switch labelled Delete account that behaves like an instant destructive command.", "A switch whose label changes from Enable emails to Disable emails after activation." ] }, "uxExamples": { "good": [ "Turning the switch on immediately enables the setting and announces the applied effect.", "A delayed backend update shows pending state, then either confirms the setting or explains the failure and reconciles the switch." ], "bad": [ "A switch appears to change but requires a hidden Save button before anything happens.", "Off, weekly, and daily notification choices are forced into one binary switch." ] }, "problemContext": [ "The controlled item has clear on/off logic and the label can describe the same object in both states.", "Changing the setting is low risk, reversible, and expected to apply immediately.", "Users benefit from seeing the current state before deciding whether to change it." ], "selectionRules": [ "Choose a toggle switch for a single setting with exactly two states that can be applied immediately.", "Keep the label stable, noun-based, and focused on the object being controlled rather than changing between action verbs.", "Show state text, effect text, or a status announcement when the effect is not obvious from the switch position alone.", "Use a checkbox group when the value is a submitted form answer or one of several independent choices users should review before commit.", "Use a radio group, segmented control, select, or another explicit choice pattern for three or more values.", "Use a button, menu item, or confirmation dialog for commands, destructive actions, and one-time operations." ], "requiredStates": [ "Off state.", "On state.", "Focused state.", "Pending or applying state when activation takes time.", "Disabled or unavailable state when a dependency, permission, or prerequisite blocks changes.", "Read-only state when the value can be reviewed but not changed.", "Failed application state when the service could not apply the requested setting." ], "interactionContract": [ "Activating the switch changes only the named setting between on and off.", "The state applies immediately unless a visible pending state explains the delay.", "The change is reversible without requiring additional confirmation.", "The accessible name remains stable while aria-checked or native checked state communicates the current value.", "Unavailable, disabled, read-only, pending, and failed states do not masquerade as successful on/off changes." ], "implementationChecklist": [ "Use a native checkbox styled as a switch or a button with role switch and aria-checked.", "Associate a visible label and optional description with the switch.", "Keep the visible label stable across state changes.", "Expose on, off, focus, disabled, read-only, pending, and failed states through text, semantics, and visual styling.", "Use Space and, where supported, Enter to toggle custom switch implementations.", "Announce asynchronous changes through status text and reconcile the switch if the backend rejects the update.", "Keep the hit target large enough to activate through either the switch or its associated label." ], "commonMisuses": [ "Using a switch to delete, publish, pay, submit, or trigger another one-time command.", "Hiding three or more options behind a binary-looking control.", "Changing the label after activation so users hear a different control name.", "Using a switch for legal consent, terms agreement, or a form answer that should be reviewed before submit.", "Showing an enabled-looking switch when dependencies, permissions, or service state prevent changes." ], "critiqueQuestions": [ "Can the setting honestly be described as on or off?", "Does the change apply immediately and remain reversible?", "Would users expect to review this value with other form answers before committing it?" ], "relatedPatterns": [ "checkbox-group", "radio-group", "segmented-control" ], "comparisons": [ "toggle-switch-vs-checkbox-group-vs-radio-group-vs-segmented-control" ], "sourceIds": [ "wai-aria-apg-switch", "carbon-toggle-component", "gnome-hig-switches" ] }, { "id": "tool-use-visibility", "completionStatus": "complete", "name": "Tool-use visibility", "category": "AI And Automation UX", "patternType": "ui-ux", "surfaceType": "Inspectable disclosure of AI agent tool calls, inputs, outputs, permissions, and side effects", "maturity": "emerging", "platforms": [ "web", "mobile", "desktop", "ai" ], "problem": "AI agents can call tools, retrieve data, run code, update records, send messages, or trigger integrations, but users often see only a friendly progress message or final answer and cannot tell what was accessed, what changed, what failed, or which permissions and payloads were involved.", "solution": "Expose tool use as structured, permission-aware, redacted, and inspectable cards or detail panels that show tool purpose, inputs, outputs, status, permissions, side effects, failures, and links to progress trace, approval gates, source evidence, and audit records.", "uiGuidance": [ "Render tool-use visibility as an inspectable tool-call surface with tool name, purpose, input summary, output summary, permission scope, data source, side-effect risk, status, timestamps, and redaction state.", "Separate safe summaries from sensitive raw payloads so users can understand what the agent is doing without exposing secrets, private records, hidden prompts, or implementation-only events." ], "uxGuidance": [ "Use tool-use visibility when users need to understand, verify, approve, debug, or audit how an AI agent used tools, data, or integrations during a run.", "Keep the display actionable: show pending, running, succeeded, failed, denied, redacted, permission-limited, rate-limited, retried, and side-effect states with clear controls to open details, grant permission, retry, cancel, report, or view audit where appropriate." ], "uiExamples": { "good": [ "A research agent shows Knowledge search, Web search, and CRM lookup tool cards with purpose, input summary, source scope, output summary, status, and redacted raw request details.", "A support agent pauses before a refund tool call, shows the amount, customer, permission scope, side-effect warning, and approval requirement before execution.", "A code assistant exposes shell command, working directory, files read, files changed, exit status, truncated output, and a View full log action gated by permission." ], "bad": [ "A trace says Using tools but never names the tool, input, source, output, permission, or side effect.", "The UI dumps raw JSON containing secrets and internal system prompts as the only explanation of tool use.", "A tool call that sends an email appears after execution with no preview, permission state, or side-effect warning." ] }, "uxExamples": { "good": [ "A user opens the active CRM lookup, sees it is read-only, verifies the account ID, and continues watching the run.", "A reviewer sees a send-email tool call is permission-limited and opens the human approval gate before it can run.", "A developer expands a failed shell command, sees sanitized stderr, retries with the same working directory, and later opens the audit record." ], "bad": [ "Users cannot tell whether the agent searched the web, read private files, or changed customer data.", "A tool card says Success even though the returned data was partially redacted or stale.", "The product hides tool failures until the final answer quietly omits a required source." ] }, "problemContext": [ "The system can call functions, tools, APIs, retrieval systems, file search, web search, shell commands, data connectors, messaging services, payment systems, workflow actions, or enterprise integrations.", "Tool calls may include sensitive inputs, hidden prompts, private records, credentials, user files, source excerpts, customer data, side effects, rate limits, failed outputs, or partial results.", "Users may need tool visibility before allowing a risky call, during execution to debug a run, after completion to verify evidence, or during review to understand what the agent actually did.", "The same tool call may need different levels of disclosure for end users, admins, reviewers, support, developers, and auditors.", "Tool-use visibility often appears inside an agent progress trace, approval gate, source grounding panel, chat transcript, code task, or activity log." ], "selectionRules": [ "Choose tool-use visibility when users need to inspect exact tool names, purposes, inputs, outputs, permissions, side effects, failures, or redactions.", "Use agent progress trace when users need the run-level sequence of steps; link from the trace to tool-use visibility for detailed tool inspection.", "Use source grounding display when the task is answer-wide evidence coverage, not individual tool-call payloads.", "Use citation display when the task is claim-level source verification rather than inspecting a tool execution.", "Use human approval gate when a tool call is paused for authorization; keep tool-use visibility responsible for showing what the tool will receive and return.", "Use activity log when users need retained evidence after the run rather than live or contextual tool details.", "Expose safe input summary, output summary, permission scope, target object, side-effect risk, status, and redaction reason before exposing raw payloads.", "Show raw request, raw response, stack trace, full command output, or hidden diagnostic detail only to eligible users and only when useful for the task.", "Do not hide tool failures, denied permissions, stale results, partial output, or redacted data behind a plain success label.", "Do not present tool-use visibility as proof of correctness; pair it with citations, grounding, confidence, approval, or audit surfaces when those are the real decision inputs." ], "requiredStates": [ "Pending tool call state with tool name, purpose, requested permission, and side-effect risk.", "Running tool call state with elapsed time, cancellability, and current operation summary.", "Succeeded tool call state with output summary, returned object count, source or target, and safe details.", "Failed, timed out, rate-limited, offline, denied, and retried tool call states.", "Permission-limited, blocked, approval-required, and human-gated tool call states.", "Redacted input, redacted output, hidden raw payload, and eligible raw payload states.", "Side-effect preview, side-effect executed, side-effect skipped, and rollback or compensation states.", "Multiple tool calls, parallel tool calls, duplicate tool events, and stale tool result states.", "Mobile compact tool card state that preserves tool name, status, permission, risk, and details access." ], "interactionContract": [ "Each tool-use item identifies one tool call or tool-call attempt with stable call ID, run ID, step ID, tool name, status, timestamp, and permission scope.", "Input summary, output summary, raw request, raw response, source excerpts, target objects, and side effects are distinct fields with separate visibility rules.", "Users can tell whether a tool is pending, running, succeeded, failed, denied, redacted, retrying, skipped, approval-waiting, or complete.", "Opening details reveals task-relevant payload information without leaking secrets, hidden prompts, credentials, private data, or irrelevant low-level logs.", "Retry, cancel, grant permission, open gate, report issue, copy tool ID, open source, open target, and view audit actions appear only when allowed by tool state and role.", "Tool outputs used in generated answers remain linked to citations or grounding where claims depend on them.", "Redaction explains whether content is hidden by permission, privacy, safety, policy, retention, or technical truncation.", "After completion, failed or side-effecting tool calls remain inspectable and link to durable audit or activity records where needed." ], "implementationChecklist": [ "Model tool call ID, attempt number, run ID, step ID, tool name, purpose, input summary, output summary, raw payload availability, permission scope, target object, side-effect type, status, timestamps, redaction reason, and audit link as structured data.", "Separate tool-use records from progress trace milestones, source grounding results, citation markers, approval decisions, raw telemetry, and activity log records.", "Render compact tool cards with expand-to-details, safe summaries, status labels, permission labels, risk labels, and role-gated raw payload access.", "Add states and actions for pending, running, success, failure, retry, cancel, grant permission, open approval gate, report mismatch, copy tool ID, open source, open target, and view audit.", "Apply redaction and truncation before rendering or copying tool inputs and outputs.", "Connect tool outputs to generated content, source grounding, citations, final artifacts, and audit records when those outputs affect user-facing results.", "Throttle live updates and avoid announcing every low-level tool delta.", "Test hidden tool calls, permission-denied tools, redacted payloads, stale results, failed tool output, side effects, parallel tools, duplicate attempts, long file paths, mobile wrapping, keyboard details, and screen-reader status changes." ], "commonMisuses": [ "Showing a vague Using tools label without names, inputs, outputs, or permissions.", "Dumping raw JSON, stack traces, tokens, secrets, or hidden prompts as the user-facing tool view.", "Showing tool success when returned data was partial, stale, redacted, or unused.", "Hiding a side-effecting tool call until after it already changed data or sent a message.", "Merging all tool calls into one progress step so users cannot inspect which tool failed.", "Letting users retry a side-effecting tool without showing idempotency, target, or duplicate risk.", "Treating tool-use visibility as citation, grounding, approval, or audit evidence when those need their own surfaces.", "Removing failed or denied tool details before users can debug or appeal." ], "critiqueQuestions": [ "Which exact tool call, attempt, run, step, permission scope, and target object is visible?", "Can users see safe input summary, output summary, status, redaction reason, and side-effect risk without raw payload leakage?", "Which tool details are hidden, truncated, permission-limited, or role-gated, and why?", "What happens when a tool call fails, times out, is denied, is retried, or creates a side effect?", "How do tool outputs connect to generated claims, citations, grounding, final artifacts, and audit records?", "Would agent progress trace, source grounding display, citation display, human approval gate, or activity log better fit the actual task?" ], "relatedPatterns": [ "agent-progress-trace", "agent-plan-preview", "source-grounding-display", "citation-display", "human-approval-gate", "activity-log", "confidence-uncertainty-display", "streaming-response" ], "comparisons": [ "tool-use-visibility-vs-agent-progress-trace-vs-source-grounding-display-vs-citation-display-vs-activity-log-vs-human-approval-gate" ], "sourceIds": [ "openai-conversation-state", "openai-responses-streaming-events", "microsoft-human-ai-guidelines", "wcag-status-messages", "openai-file-search-citations", "openai-web-search-citations" ] }, { "id": "toolbar", "completionStatus": "complete", "name": "Toolbar", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "View-scoped command strip for related controls", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Products often need repeated commands near a view or selection, but loose action rows become crowded, unlabeled, hard to navigate by keyboard, and ambiguous about what object or state they affect.", "solution": "Use a labelled toolbar for a cohesive set of view-scoped controls, define command groups and overflow, expose current selection and pressed or disabled states, implement efficient keyboard movement, and route unrelated navigation or primary workflow actions to clearer patterns.", "uiGuidance": [ "Render a toolbar as a labelled command region attached to the view, editor, canvas, table, or selected object it controls, with grouped buttons, toggle buttons, menu buttons, separators, compact inputs, overflow, and current state visible where relevant.", "Keep toolbar controls compact but not mysterious: use predictable order, stable grouping, visible focus, enabled and disabled states, pressed toggle state, current selection summary, and precise accessible names for icon-only controls." ], "uxGuidance": [ "Use a toolbar when users repeatedly apply related commands to the same view or selection and need fast visible access without opening a modal command surface.", "Make scope and keyboard efficiency explicit: users should know what object the toolbar affects, move among controls predictably, activate commands without losing selection, and find overflow without hunting for primary work." ], "uiExamples": { "good": [ "A document editor toolbar labels the current document, groups Undo and Redo, formatting toggles, alignment controls, Insert link, and More, with Bold shown pressed for the selected text.", "A data-table toolbar appears only when rows are selected, shows 3 selected, enables Export and Archive, disables Merge with a reason, and keeps More actions secondary." ], "bad": [ "A toolbar contains Back, Save, Delete, Pricing, Account, Filter, and Help with no shared scope or grouping.", "A row of icon-only buttons has no labels, no pressed state for active formatting, no overflow explanation, and no disabled reason." ] }, "uxExamples": { "good": [ "A keyboard user tabs once into the editor toolbar, uses Right Arrow to move from Bold to Italic, presses Space to toggle Italic, and focus remains in the toolbar while selected text stays selected.", "A user selects three files, sees the toolbar switch to selection scope, exports them, then clears selection and the toolbar disables selection-only commands." ], "bad": [ "A keyboard user must tab through twenty toolbar buttons before reaching the editor body.", "A user clicks Archive in a toolbar but cannot tell whether it affects the selected row, the whole folder, or the current page." ] }, "problemContext": [ "A document, canvas, map, table, list, media viewer, or selected object has several frequent commands that users apply repeatedly.", "The commands share one scope and can remain visible without interrupting the work surface.", "Some commands are compact, stateful, grouped, or lower priority enough to need separators, toggles, menus, or overflow.", "Keyboard users need to move through the command set efficiently without leaving the work context." ], "selectionRules": [ "Choose toolbar when a persistent view-scoped command surface groups several related controls for repeated use.", "Use a button group when there are only a few visible peer actions for one workflow moment and ordinary tab order is sufficient.", "Use a menu button when secondary commands can stay hidden behind one named trigger.", "Use a command palette when commands are broad, searchable, shortcut-driven, or cross-product rather than scoped to the current view.", "Use header, global navigation, side navigation, tabs, or bottom navigation when controls move between destinations instead of applying commands.", "Do not put unrelated actions into one toolbar just because they share horizontal space.", "Do not rely on tooltips as the only names for icon-only toolbar controls.", "Keep primary submit, destructive review, and multi-step decisions outside overflow unless the toolbar is explicitly the correct command surface.", "Define overflow priority before responsive collapse so essential controls remain available and secondary controls move predictably.", "Use toolbar role and composite keyboard behavior only when the implementation provides arrow-key focus movement and predictable nested-control behavior." ], "requiredStates": [ "Default toolbar with label, visible scope, grouped controls, and focusable entry point.", "Keyboard focus inside the toolbar with current roving item or active control indicated.", "Arrow-key movement among toolbar controls.", "Pressed or selected toggle state for stateful commands such as Bold, Filters on, or Preview mode.", "Disabled command state with visible reason or unavailable target.", "Selection-scoped state showing selected object count and enabled contextual commands.", "Overflow state when commands do not fit or are lower priority.", "Nested menu button or compact input state inside the toolbar.", "Command activated state with status feedback and focus preserved.", "Responsive narrow viewport state with stable priority and reachable overflow." ], "interactionContract": [ "The toolbar has a clear accessible name and visual scope tied to the current view, selected objects, or editor surface.", "Controls inside the toolbar share one command context; unrelated navigation and page-level settings stay outside.", "Tab reaches the toolbar in a predictable place, and implementations using composite toolbar behavior let arrow keys move between controls.", "Home and End move to first and last toolbar controls when supported by the implementation.", "Enter or Space activates the focused command, toggles stateful buttons, or opens a nested menu button according to the control role.", "Activation preserves the user's object selection and focus unless the command intentionally opens a dialog, route, or confirmation flow.", "Disabled controls communicate why they are unavailable when the reason is not obvious from selection or context.", "Overflow retains command labels, grouping, and object scope rather than becoming an unnamed dumping ground.", "Nested controls define whether arrow keys move within the control or across toolbar items, avoiding conflicting behavior." ], "implementationChecklist": [ "Inventory the commands and remove actions that do not share the toolbar's current view or selection scope.", "Name the toolbar by the surface it controls, such as Text formatting, Map tools, Selected rows, or File preview actions.", "Group controls by task, add separators where groups change, and order commands by frequency and risk.", "Define which commands are visible, which move to overflow, and which belong in a menu, dialog, footer, or command palette.", "Implement native buttons, toggle buttons, menu buttons, inputs, and labels with synchronized accessible names and states.", "Choose ordinary tab order or composite toolbar keyboard behavior deliberately; if using toolbar role, implement arrow movement and orientation.", "Keep disabled reasons, selected object count, pressed state, command result, and overflow status available to assistive technology.", "Test keyboard, screen reader, high zoom, touch target size, mobile overflow, localization, forced colors, and nested widget key conflicts." ], "commonMisuses": [ "Labelling any horizontal button row as a toolbar without shared scope or keyboard behavior.", "Using a toolbar for primary app navigation or unrelated destinations.", "Packing rare, destructive, and primary submit actions into one dense strip.", "Using icon-only buttons whose names exist only in hover tooltips.", "Forgetting pressed state for toggles such as Bold, Filter on, or Preview.", "Leaving selection-only commands enabled when nothing is selected.", "Putting form fields, tables, or long explanations in toolbar overflow.", "Letting responsive collapse hide important commands behind an unnamed More icon." ], "critiqueQuestions": [ "What surface or selected object does this toolbar control?", "Do all controls share that scope, or are navigation and unrelated commands mixed in?", "Can keyboard users enter once, move between controls efficiently, activate a command, and keep their selection?", "Which controls are stateful, disabled, destructive, or overflowed, and how are those states exposed?", "Would a button group, menu button, command palette, header, or navigation pattern better match the user's job?" ], "relatedPatterns": [ "button-group", "menu-button", "command-palette", "header", "utility-navigation", "icon-only-ambiguous-action", "tooltip", "segmented-control", "undo", "redo" ], "comparisons": [ "toolbar-vs-button-group-vs-menu-button-vs-command-palette" ], "sourceIds": [ "wai-aria-apg-toolbar", "mdn-aria-toolbar-role", "apple-hig-toolbars", "fluent-toolbar-component", "carbon-text-toolbar-pattern" ] }, { "id": "tooltip", "completionStatus": "complete", "name": "Tooltip", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Short noninteractive description tied to a trigger", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Dense controls sometimes need a short supplemental explanation, but visible labels may already exist and richer overlays would add unnecessary interaction or hide important information.", "solution": "Attach a short noninteractive description to the owning trigger, reveal it on keyboard focus and pointer hover, keep focus on the trigger, dismiss it predictably, and keep essential instructions visible elsewhere.", "uiGuidance": [ "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.", "Keep the trigger itself understandable and make tooltip text supplemental, not the only visible or accessible name for an unfamiliar action." ], "uxGuidance": [ "Use tooltips to add a brief description on focus or hover without asking users to open a separate layer or change task mode.", "Make the tooltip appear predictably, stay available long enough to read, dismiss on Escape or leaving the trigger, and never require users to move focus into the tooltip." ], "uiExamples": { "good": [ "A labelled Archive icon button receives focus and shows a short tooltip that says Moves this report to archived reports.", "A dense toolbar shows concise focus and hover tooltips near each icon while keeping every button accessible by name." ], "bad": [ "A mystery icon has no label and the only explanation is a hover-only tooltip that never appears for touch users.", "A tooltip contains a paragraph, a Learn more link, and a checkbox even though the tooltip itself cannot receive focus." ] }, "uxExamples": { "good": [ "Tabbing to Archive keeps focus on the button, shows a short description, Escape hides it, and focus remains on Archive.", "Moving pointer away or tabbing to the next toolbar button hides the previous tooltip and shows the next one without changing the document." ], "bad": [ "A user presses Escape to hide the tooltip and focus jumps to the top of the page.", "Required error-fixing instructions disappear when the field loses focus, forcing the user to remember them." ] }, "problemContext": [ "A toolbar, icon button, compact status marker, data chip, or abbreviated field label needs a little extra explanation.", "The user should not have to click, open a menu, enter a panel, or leave the current task to read the description.", "The content is supplemental and short enough to read while focus remains on the trigger.", "The implementation can support focus and hover triggering, Escape dismissal, pointer movement, zoom, clipping, and assistive technology description relationships." ], "selectionRules": [ "Choose tooltip when the target already has a usable name and needs only a short supplemental description on focus or hover.", "Use popover when the layer needs interactive controls, links, choices, a heading, or user-managed open and close behavior.", "Use inline message when the information is important, required, validation-related, or must stay visible while the user acts.", "Use visible text labels when the action would otherwise be ambiguous before activation.", "Use disclosure details when users need to intentionally open longer optional explanation inside the page flow.", "Use disabled-button explanation patterns when a blocked action needs a reachable reason and next step.", "Do not use a tooltip for instructions users must remember after focus leaves the trigger.", "Do not use tooltip role for a more-info icon that opens a separate explanation; that job belongs to disclosure, popover, or inline help." ], "requiredStates": [ "Resting trigger state with a visible or accessible name that works without the tooltip.", "Keyboard focus state where the tooltip appears and focus remains on the trigger.", "Pointer hover state where the tooltip appears after a brief delay and remains while pointer is over the trigger or tooltip area.", "Escape dismissed state where the tooltip hides without moving focus from the trigger.", "Blur or pointer-out dismissed state where the tooltip hides cleanly.", "Placement collision state where the tooltip shifts or flips without covering the trigger or important content.", "Long-label or zoom state where tooltip text wraps without clipping or overlapping nearby controls.", "Disabled or unavailable target state where the explanation remains reachable by keyboard and touch." ], "interactionContract": [ "The owning element keeps focus while the tooltip is visible.", "The tooltip is associated with the owning element as a description, not as a replacement label.", "The tooltip appears for keyboard focus and pointer hover, not hover alone.", "Escape hides the tooltip and leaves focus on the owning element.", "Blur, pointer out, or moving to another described control hides the old tooltip.", "The tooltip itself contains no focusable elements and does not require Tab navigation.", "The tooltip does not block pointer access to the trigger or nearby task controls.", "Opening and closing the tooltip does not apply a value, submit a command, change route, or alter task state." ], "implementationChecklist": [ "Give the trigger its own accessible name before adding tooltip text.", "Connect descriptive tooltip text to the trigger with aria-describedby when using ARIA tooltip semantics.", "Show the tooltip on focus and hover, and hide it on blur, pointer out, Escape, and trigger removal.", "Keep tooltip copy short, text-only, and supplemental.", "Do not place links, inputs, buttons, menus, or other focusable controls inside the tooltip.", "Position the tooltip close to the trigger while avoiding clipping, viewport edges, and important content.", "Provide a keyboard and touch-reachable alternative when the target is disabled or cannot receive focus.", "Test keyboard, pointer, touch, screen readers, high zoom, forced colors, reduced motion, and dense toolbars." ], "commonMisuses": [ "Using hover-only tooltip text as the only label for an icon button.", "Putting required instructions, validation fixes, or legal terms in a tooltip that disappears during the task.", "Adding buttons, links, or form fields inside a tooltip.", "Triggering a tooltip only with a mouse pointer and not with keyboard focus.", "Letting Escape close the tooltip and also move focus away from the trigger.", "Attaching a tooltip to a disabled native control that keyboard users cannot focus.", "Using long paragraphs that clip, cover nearby controls, or require scrolling inside the tooltip." ], "critiqueQuestions": [ "Does the target already have a usable name without the tooltip?", "Is the tooltip content supplemental and short enough to read while focus stays on the trigger?", "Would a popover, inline message, details disclosure, or visible label better match the information?", "Can keyboard, pointer, and touch users reveal the same information?", "What happens on Escape, blur, pointer out, zoom, collision, and disabled state?", "Is any required instruction hidden in this temporary description?" ], "relatedPatterns": [ "popover", "inline-message", "icon-only-ambiguous-action", "disabled-button-no-explanation", "disclosure-details" ], "comparisons": [ "tooltip-vs-popover-vs-inline-message-vs-icon-only-ambiguous-action" ], "sourceIds": [ "wai-aria-apg-tooltip", "mdn-aria-tooltip-role", "fluent-tooltip-component", "redhat-tooltip-accessibility" ] }, { "id": "tooltip-only-required-information", "completionStatus": "complete", "name": "Tooltip-only required information", "category": "Disclosure And Attention Management", "patternType": "ui-ux", "surfaceType": "Required-content-hidden-in-tooltip anti-pattern", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "A form, checkout, application, account change, or decision flow needs required instructions, but the only copy lives in a temporary tooltip that can disappear before users can apply it.", "solution": "Treat tooltip-only required information as an anti-pattern: put required content in visible or intentionally openable persistent surfaces, use tooltip only for short supplemental descriptions, and keep recovery guidance available through focus, touch, screen reader, zoom, and validation states.", "uiGuidance": [ "Replace tooltip-only required information with visible text, inline message, validation copy, details disclosure, or a stable popover that remains available while users act.", "Keep any tooltip as supplemental repetition only: the task must still expose required format, eligibility, document, deadline, fee, consequence, or recovery information without relying on hover, focus timing, or title attributes." ], "uxGuidance": [ "Use this anti-pattern during review when users must discover hidden tooltip text to answer a field, choose safely, avoid validation failure, understand a legal consequence, or unblock a disabled action.", "Design the corrected flow around uninterrupted task completion: users can read the requirement, type or decide, revisit the explanation, recover from validation, and continue on keyboard, touch, screen reader, zoom, and slow-reading paths." ], "uiExamples": { "good": [ "A tax ID field shows Format: 9 digits, no spaces directly under the label, with a tooltip only repeating where to find it.", "A document upload step lists passport or driving licence as acceptable evidence in visible help text and opens details for examples.", "A disabled Continue button has adjacent text saying Add proof of address before continuing, with a link to the missing section." ], "bad": [ "A question-mark icon beside Tax ID hides the only accepted format in a hover tooltip.", "A password field displays every rule only while the field is focused, then hides the list when users type in the confirmation field.", "A declaration checkbox hides the legal consequence in a tooltip attached to an info icon." ] }, "uxExamples": { "good": [ "A mobile user can read required document rules before selecting files and can reopen optional examples in a details disclosure.", "A keyboard user tabs through the form while the visible requirement remains next to the affected field.", "After validation fails, the required rule is shown inline and focus lands on the field with the rule still visible." ], "bad": [ "A touch user cannot open the hover tooltip and submits the wrong document.", "A screen reader user hears a brief description but cannot revisit it while fixing the field.", "A slow reader opens a tooltip, moves focus to type, and loses the only deadline consequence." ] }, "problemContext": [ "The hidden content is needed to complete a field, understand eligibility, choose an option, avoid a fee, meet a deadline, satisfy a document rule, or recover from a blocked control.", "The implementation uses a question-mark icon, native title attribute, aria-describedby tooltip, hover bubble, focus bubble, disabled-control tooltip, chart cell tooltip, or compact label tooltip as the only explanation.", "Users may be on touch devices, keyboard-only navigation, screen readers, high zoom, slow reading, switch control, or reduced pointer precision.", "The tooltip closes on blur, pointer out, Escape, scroll, validation rerender, viewport collision, route change, or mobile tap." ], "selectionRules": [ "Flag this anti-pattern when the tooltip content is necessary to complete the task correctly or avoid a harmful outcome.", "Use visible helper text when users need the requirement while typing or selecting.", "Use inline message when the requirement is contextual feedback, validation recovery, warning, or a local next step.", "Use disclosure details when the information is optional but longer than a short tooltip and should stay in page flow after opening.", "Use popover when users intentionally open richer anchored help, examples, or light controls and can keep the surface open while acting.", "Use tooltip only when the content is short, noninteractive, supplemental, and safe to dismiss without changing task success.", "Open or reveal hidden required help automatically during validation recovery if it was optional before the error.", "Do not rely on native title attributes for required information.", "Do not attach the only explanation to a disabled native control that keyboard users cannot focus.", "Do not make users memorize a tooltip before moving to the field, checkbox, upload control, payment field, or table row that needs it." ], "requiredStates": [ "Default state with the requirement visible, summarized, or explicitly openable before users act.", "Tooltip-supplement state where the tooltip repeats or clarifies but is not the only copy.", "Keyboard path where Tab reaches the field and requirement without requiring hover.", "Touch path where the same required content is visible or intentionally openable.", "Screen reader path where the requirement is announced and can be revisited in normal reading order.", "Validation recovery state where the exact missing or invalid requirement remains visible.", "Disabled or blocked action state with adjacent reason and next step.", "Details or popover state for longer examples that stay open while users compare or copy.", "High zoom or narrow viewport state where helper text wraps without overlapping the field.", "Tooltip expired or dismissed state where required content is still present elsewhere." ], "interactionContract": [ "Users can complete the task without reading a tooltip.", "If the tooltip disappears, every required rule remains visible or reopenable through an explicit control.", "Required content is available before validation, not only after failure, when the user needs it to avoid mistakes.", "Keyboard, touch, screen reader, and pointer users receive equivalent required information.", "The tooltip contains no focusable controls and never asks users to move focus into it.", "Disabled controls expose the reason and recovery path outside the disabled element.", "Validation messages quote the exact requirement users missed rather than referring back to hidden help.", "Long, structured, legal, or consequence-bearing content moves to inline text, disclosure, popover, page content, or dialog according to task severity." ], "implementationChecklist": [ "Inventory every tooltip, title attribute, help icon, and aria-describedby bubble in the flow.", "Classify each item as supplemental or required for task success, safe choice, validation, eligibility, legal consequence, or recovery.", "Move required text into visible helper text, inline message, validation copy, details disclosure, or popover content.", "Leave tooltips only for short supplemental descriptions tied to triggers that already have names.", "Provide explicit touch and keyboard routes for any help that users must intentionally open.", "Show blocked-action requirements beside the disabled or unavailable action, not only on hover.", "Test blur, Escape, pointer out, scroll, zoom, validation rerender, mobile tap, screen reader reading order, and slow-reader timing.", "Confirm the task can be completed correctly after all tooltips are dismissed." ], "commonMisuses": [ "Putting accepted document types only in a help-icon tooltip.", "Putting password rules only in a field-focus tooltip.", "Putting eligibility thresholds only in a hover card or tooltip beside a question.", "Using a disabled button tooltip as the only explanation for why users cannot continue.", "Relying on native title attributes for required field format.", "Putting legal terms, fees, deadline consequences, or consent scope only in a tooltip.", "Hiding chart values, table definitions, or required column meaning only behind pointer hover.", "Using aria-describedby to hide instructions that disappear before the user can apply them." ], "critiqueQuestions": [ "Could users complete the task correctly if every tooltip disappeared?", "Is any tooltip text required to answer, choose, pay, upload, consent, or recover?", "Can touch users and keyboard users reach the same information before acting?", "Does validation repeat the exact hidden requirement when users miss it?", "Should this content be visible helper text, inline message, disclosure details, popover, warning text, or validation copy?", "What happens when focus leaves the trigger, Escape closes the tooltip, the page scrolls, or the viewport is narrow?" ], "relatedPatterns": [ "tooltip", "inline-message", "disclosure-details", "popover", "disabled-button-no-explanation", "inline-validation", "warning-text" ], "comparisons": [ "tooltip-only-required-information-vs-tooltip-vs-inline-message-vs-disclosure-details-vs-popover" ], "sourceIds": [ "wai-aria-apg-tooltip", "mdn-aria-tooltip-role", "fluent-tooltip-component", "redhat-tooltip-accessibility", "wcag-content-on-hover-or-focus", "material-rich-tooltips" ] }, { "id": "touch-gesture", "completionStatus": "complete", "name": "Touch gesture", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Touch-first gesture vocabulary and fallback contract for taps, swipes, drags, pinches, and multi-touch interactions", "maturity": "standard", "platforms": [ "mobile", "web", "desktop", "spatial" ], "problem": "Touch gestures can make interfaces feel direct and efficient, but hidden, path-based, multipoint, undersized, or scroll-conflicting gestures exclude users and cause accidental activation when the product does not provide equivalent controls, clear thresholds, cancellation, or feedback.", "solution": "Design a gesture contract that uses familiar platform gestures, exposes large enough targets, shows start/move/commit/cancel feedback, separates scroll from action gestures, and provides single-pointer and control-based alternatives for path-based or multipoint functions.", "uiGuidance": [ "Render touch gesture affordances with visible targets, enough spacing, state feedback, and non-gesture controls for the same outcome when a gesture is path-based, multipoint, hidden, or easy to misfire.", "Use platform-standard gesture meanings for tap, double tap, swipe, drag, pinch, spread, rotate, and edge gestures, and show inline hints or handles only where users need to discover a custom gesture." ], "uxGuidance": [ "Use touch gesture when the product needs direct manipulation on a touchscreen, but treat gestures as part of a larger interaction contract rather than the only way to act.", "Make gesture recognition predictable by defining start target, movement threshold, direction, velocity, cancellation, conflict with scroll, feedback while moving, commit boundary, and equivalent tap or button path." ], "uiExamples": { "good": [ "A photo viewer supports pinch to zoom, double tap to zoom, plus and minus buttons, a reset button, zoom percent feedback, and a clear pan boundary after zoom.", "A card carousel supports horizontal swipe but also shows previous and next buttons, page position, touch target spacing, and a drag preview that cancels when released before threshold." ], "bad": [ "A map can only be zoomed with a two-finger pinch and has no plus, minus, or reset controls.", "A hidden edge swipe deletes a message while the user is trying to scroll the list." ] }, "uxExamples": { "good": [ "A user pinches a diagram to zoom, sees the scale change, releases outside the threshold without committing a rotate gesture, then uses visible Zoom in and Reset controls with one finger.", "A user starts swiping a gallery card, sees the next-card preview, changes their mind by moving back under the threshold, and the card snaps back with position unchanged." ], "bad": [ "A user with a head pointer cannot trigger a two-finger gesture and has no single-pointer alternative.", "A user tries to scroll a feed but the product interprets a short diagonal movement as a destructive swipe action." ] }, "problemContext": [ "The interface supports touch input on phones, tablets, kiosks, touch laptops, drawing surfaces, maps, media viewers, carousels, boards, canvases, or spatial controllers.", "The same feature may also be used with mouse, stylus, keyboard, switch control, screen reader touch exploration, head pointer, or assistive pointer devices.", "Gestures can be basic single-pointer actions such as tap and drag, or more demanding path-based and multipoint actions such as swipe, pinch, spread, rotate, two-finger tap, and edge gestures.", "Gesture conflicts often occur between scrolling, panning, selection, reordering, dismissal, navigation, refresh, zoom, drawing, and destructive actions." ], "selectionRules": [ "Choose touch gesture when the design question is the recognition, feedback, fallback, and cancellation behavior of touch input itself.", "Use swipe action when the pattern is specifically a horizontal or directional item action such as archive, delete, complete, or reveal action buttons.", "Use pull to refresh when the vertical drag from scroll top refreshes content.", "Use long press when sustained contact reveals context menus, selection, preview, or drag pickup.", "Use drag and drop when the core task is moving an object from a source to a destination.", "Use bottom sheet when the gesture changes a detented bottom overlay; document the sheet-specific scroll-versus-drag priority there.", "Use carousel, map view, data visualization, or calendar view when the primary pattern is the content surface and gestures are only one input method inside it.", "Provide simple single-pointer controls for any function that otherwise requires a multipoint or path-based gesture unless the gesture is essential to the task.", "Do not hide critical, destructive, security, payment, consent, or account actions behind an undiscoverable gesture-only shortcut." ], "requiredStates": [ "Idle state with visible touch targets, gesture hints when needed, and no reliance on hover.", "Touch down or gesture start state that identifies the active target.", "Move or preview state showing direction, distance, scale, rotation, selected object, or next outcome.", "Threshold-not-met cancellation state that snaps back or leaves content unchanged.", "Commit state after the gesture passes a clear threshold or release boundary.", "Conflict state where scroll, pan, drag, swipe, refresh, or edge navigation wins predictably.", "Single-pointer alternative state for multipoint or path-based functions.", "Equivalent button or menu state for users who cannot or do not discover the gesture.", "Target-size and spacing state for compact controls.", "Disabled, unavailable, or system-reserved gesture state with explanation.", "Undo, reset, or recovery state for reversible gesture outcomes.", "Mobile compact, large-text, landscape, stylus, and assistive-touch states." ], "interactionContract": [ "The gesture starts only from the intended target or gesture region, not from unrelated content.", "Movement thresholds, velocity thresholds, direction locks, and edge zones are defined before implementation.", "Feedback begins early enough for users to know whether they are scrolling, panning, dragging, swiping, zooming, rotating, selecting, or dismissing.", "Users can cancel before the commit boundary by reversing, releasing outside, pressing cancel, or using a visible reset where the platform supports it.", "Multipoint or path-based gestures have simple single-pointer alternatives such as buttons, handles, steppers, menus, or tap targets.", "Gesture shortcuts do not replace keyboard, screen reader, switch, pointer, mouse, stylus, or assistive-device operation.", "Targets meet minimum size or spacing expectations, or equivalent controls are available on the same page.", "System gestures, browser gestures, assistive-technology gestures, and platform navigation gestures are not overridden unless the platform explicitly supports the custom behavior." ], "implementationChecklist": [ "Inventory every touch gesture, target region, affected object, outcome, threshold, pointer count, direction, speed, and commit boundary.", "Define whether each gesture is basic, path-based, multipoint, dragging, system-reserved, or content-specific.", "Add visible controls for zoom, reset, previous, next, move, dismiss, select, refresh, rotate, or recover when the gesture is not enough.", "Set target size and spacing for touch controls and avoid placing dangerous actions near routine scroll or navigation targets.", "Provide live feedback for start, movement, invalid direction, threshold reached, cancellation, commit, undo, and failure.", "Resolve conflicts between vertical scroll, horizontal swipe, nested panning, drag handles, pull-to-refresh, browser back, and screen-reader touch exploration.", "Test one-handed use, thumb reach, tremor, slow movement, accidental diagonal movement, multi-touch failure, stylus, mouse, keyboard, screen reader, zoom, large text, and landscape.", "Record analytics for failed gesture attempts only in aggregate and without logging sensitive path or content data." ], "commonMisuses": [ "Requiring pinch, rotate, two-finger swipe, or shape gestures with no single-pointer alternative.", "Making a hidden gesture the only way to find navigation, delete, refresh, zoom, or edit controls.", "Letting short diagonal scroll movements trigger swipe actions.", "Using tiny targets or placing opposing actions too close together.", "Overriding operating-system, browser, or assistive-technology gestures.", "Committing actions on touch down instead of release or a clear threshold.", "Providing no cancel, undo, reset, or recovery for high-friction gesture mistakes.", "Assuming desktop hover hints will teach mobile users a gesture." ], "critiqueQuestions": [ "Which exact function depends on touch, path, velocity, pointer count, or contact duration?", "What visible control performs the same function for users who cannot do the gesture?", "How do users know when the gesture has started, crossed threshold, canceled, or committed?", "What prevents scroll, pan, swipe, pull-to-refresh, drag, and system back gestures from fighting each other?", "Are targets large enough and spaced far enough to prevent accidental activation?", "What happens for screen reader touch exploration, switch control, head pointer, stylus, mouse, keyboard, large text, and landscape?", "Is this better handled as a named pattern such as swipe action, pull to refresh, long press, drag and drop, bottom sheet, or carousel?" ], "relatedPatterns": [ "carousel", "map-view", "bottom-sheet", "drag-and-drop-upload", "data-visualization", "toolbar" ], "comparisons": [ "touch-gesture-vs-carousel-vs-map-view-vs-bottom-sheet-vs-drag-and-drop-upload-vs-data-visualization" ], "sourceIds": [ "android-touch-gestures", "w3c-wcag-pointer-gestures", "w3c-wcag-target-size-minimum", "w3c-wcag-pointer-cancellation-drag-drop" ] }, { "id": "transfer-list", "completionStatus": "complete", "name": "Transfer list", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Two-pane item transfer and selected-set review", "maturity": "established", "platforms": [ "web", "desktop" ], "problem": "Users need to build and review a selected set from a larger available set, but ordinary multi-select controls hide the destination set, and one listbox does not show what has moved out of the source collection.", "solution": "Provide two labelled list panes with explicit add, remove, bulk, and reorder actions, selected counts, validation, disabled button states, live feedback, and focus management so users can move items reversibly and review the final selected set.", "uiGuidance": [ "Render two clearly labelled panes for available items and selected items, with item counts, selected-row state, disabled move state, and action buttons positioned between or near the panes.", "Show the destination list as the submitted set; include reorder controls, locked required items, validation text, and live status without hiding selected values inside a collapsed field." ], "uxGuidance": [ "Use a transfer list when users must build a selected set by moving items from one visible collection to another and then review what will be submitted.", "Make each move reversible and explicit by preserving selection, keeping focus predictable, announcing completed moves, and disabling impossible add, remove, or reorder actions." ], "uiExamples": { "good": [ "A permissions editor shows Available permissions on the left, Selected permissions on the right, selected counts in both headers, Add and Remove buttons between panes, and Move up and Move down controls for selected permissions.", "A dashboard setup flow shows required selected modules as locked rows in the destination pane and disables Remove for those rows while still allowing optional modules to move.", "At high zoom, a transfer list stacks the two panes vertically and changes right-left arrows to add-remove wording so the move direction remains understandable." ], "bad": [ "A form shows one long source list and a tiny submitted count, so users cannot review which items were moved before saving.", "A dual listbox keeps Add enabled when no item is selected and silently does nothing when activated.", "The selected pane supports drag reordering only, with no buttons, keyboard path, position feedback, or fallback." ] }, "uxExamples": { "good": [ "A user selects Billing and Audit logs, activates Add, hears that two permissions moved to Selected, and focus stays in a useful place for adding another permission.", "A user selects Export in the destination pane, activates Move up, and the status confirms its new position before the set is saved.", "A user tries to save with one selected permission where two are required and receives an inline validation message without losing selected items." ], "bad": [ "A user removes the only required item and the form waits until final submit to reveal the selected set is invalid.", "A user filters the available list and previously selected destination items disappear from the submitted value.", "A keyboard user can select source items but cannot activate the pointer-only drag target needed to move them." ] }, "problemContext": [ "The user must compare available and selected items at the same time.", "Selected items are submitted, persisted, ordered, required, capped, or otherwise treated differently from available items.", "Users may need to add or remove more than one item in a batch.", "The item set is too large or structured for a short checkbox group but the selected set needs more review than compact chips provide.", "Keyboard users need explicit controls for movement and ordering rather than pointer-only drag and drop." ], "selectionRules": [ "Choose transfer list when the interface has a source collection and a destination collection, and moving items between them is the core task.", "Use multi-select when users only need to choose several values from a compact picker and can review selected chips or tags without seeing the full available set.", "Use a standalone listbox when the task is selecting within one visible list, not moving items between two lists.", "Use checkbox group when all options are few enough to remain visible and order does not matter.", "Use data grid, table, or collection management when rows have independent actions, columns, rich metadata, or bulk operations beyond move and reorder.", "Provide filter or search for long source panes, but never let filtering hide or clear the selected destination set.", "Use selected-pane reorder controls only when order is persisted or meaningful; avoid adding reorder chrome to unordered sets.", "Avoid transfer list on mobile unless the two-pane interaction is replaced with a step, stacked panes, or review screen that preserves add, remove, and selected-set review." ], "requiredStates": [ "Available list initial state with label, count, and selectable options.", "Selected list initial state with label, count, empty message, or existing selected items.", "One or more source items selected for transfer.", "One or more destination items selected for removal or reorder.", "Add and remove controls enabled only when a valid selection exists.", "Add all and remove all controls when bulk transfer is supported.", "Destination item first and last states for reorder control disabling.", "Required locked selected item state.", "Minimum, maximum, required, and empty-selected-set validation states.", "Live confirmation after add, remove, bulk move, or reorder.", "Filtered source list state that preserves selected destination items.", "Stacked high-zoom layout state with direction labels that still make sense." ], "interactionContract": [ "Each pane has a visible label and accessible name that describes whether it contains available or selected items.", "Items in each pane expose option selection state, and multi-select panes expose multi-selection semantics when custom listbox roles are used.", "Add moves selected source items to the selected pane and removes them from the available pane unless the product explicitly uses a copy model.", "Remove moves selected destination items back to the available pane unless the item is locked, required, or otherwise non-removable.", "Move-up and move-down controls affect only selected destination items and are disabled at the relevant boundary.", "Disabled controls communicate why no action is available and do not fire silent no-op changes.", "After a move, focus lands on a remaining nearby option or a relevant action button, and a live region announces what changed.", "Validation preserves both panes, selected items, focusable controls, and the user's current selections." ], "implementationChecklist": [ "Confirm that users really need a source and destination model instead of checkbox group, multi-select, listbox, or table management.", "Label both panes, include counts, and make the selected pane read as the final submitted set.", "Use native select multiple or accessible listbox semantics with aria-multiselectable, aria-selected, visible focus, and typeahead where appropriate.", "Implement Add, Remove, optional Add all and Remove all, and optional Move up and Move down controls with disabled states tied to current selection.", "Preserve selected destination items during filtering, validation, async refresh, route changes, and save errors.", "Announce add, remove, and reorder results in a live region and keep focus on the moved item or the nearest useful remaining item.", "Handle min, max, required, locked item, duplicate label, empty source, empty destination, and long-list states.", "Test keyboard, screen reader, high zoom above 200 percent, forced colors, touch fallback, localization, long item names, and bulk move performance." ], "commonMisuses": [ "Using transfer list for a short yes-or-no set that should be checkboxes.", "Using transfer list for one required value that should be select, radio group, or combobox.", "Hiding selected values behind a count instead of showing the destination pane.", "Leaving move buttons enabled when no source or destination item is selected.", "Making drag and drop the only way to transfer or reorder items.", "Clearing selected items when filtering or refreshing the available list.", "Using arrow icons without text or accessible names, especially in stacked or high-zoom layouts.", "Persisting selected order while providing no keyboard-accessible reorder controls." ], "critiqueQuestions": [ "Do users need to see both available and selected sets at the same time?", "Is the selected pane clearly the set that will be saved or submitted?", "Do move buttons, counts, locked items, and validation explain what can and cannot change right now?", "Can keyboard users add, remove, bulk move, and reorder without drag and drop?", "Does filtering or async loading preserve the selected destination list?" ], "relatedPatterns": [ "multi-select", "listbox", "checkbox-group", "combobox", "drag-and-drop-upload" ], "comparisons": [ "transfer-list-vs-multi-select-vs-listbox-vs-checkbox-group" ], "sourceIds": [ "mui-transfer-list", "salesforce-lightning-dual-listbox", "wai-aria-apg-listbox-rearrangeable", "wai-aria-apg-listbox" ] }, { "id": "tree-grid", "completionStatus": "complete", "name": "Tree grid", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Hierarchical interactive row-and-column data workspace", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need to inspect or act on hierarchical records that also have comparable columns, but separate tree and table controls force context switching, while a flat data grid loses parent-child ownership and descendant state.", "solution": "Present the hierarchy as a tree grid with labelled columns, expandable parent rows, indented row headers, truthful level and position metadata, managed row or cell focus, distinct focus and selection, and clear rules for sorting, filtering, editing, lazy loading, and collapsed descendants.", "uiGuidance": [ "Render a labelled tree grid with a persistent hierarchy column, visible column headers, indentation by level, expandable parent rows, leaf rows without fake expand controls, and status text for visible rows, selected descendants, sort, filter, and loading children.", "Show parent, child, focused, selected, mixed, collapsed-with-descendant-state, dirty, invalid, readonly, and loading states with distinct text or programmatic state as well as visual treatment." ], "uxGuidance": [ "Use tree grid when users need to keep hierarchy and column comparison in one workspace, especially for nested operational records that can be expanded, selected, edited, or acted on in context.", "Preserve users' mental model of containment: expansion, collapse, sort, filter, save, lazy load, and virtual scroll must not make descendant state disappear without an explicit explanation." ], "uiExamples": { "good": [ "A project work-breakdown tree grid shows parent rows for phases, child rows for tasks, columns for Owner, Due, Status, and Cost, and a collapsed parent badge that says 2 selected children.", "A folder permission tree grid indents folders and files in the Name column, omits expand buttons from files, and keeps column headers aligned for Owner, Role, Inherited, and Last changed." ], "bad": [ "A flat data grid uses chevron icons in every first cell but no row actually owns children.", "A simple folder picker with one label column is implemented as a tree grid even though users only choose folders." ] }, "uxExamples": { "good": [ "A user expands Design, edits a child task status, collapses Design, sees a dirty-child badge on the parent, re-expands, and focus returns to the edited child row.", "A user filters to overdue tasks; parent rows remain visible only when they contain matching descendants, and collapsed parents show the number of hidden matches." ], "bad": [ "A user collapses a parent and unknowingly hides a selected invalid child row before bulk approval.", "A user sorts by Due date and child tasks scatter away from their parent phases, destroying the hierarchy." ] }, "problemContext": [ "Rows represent nested objects such as folders and files, work breakdown structures, threaded records, accounts and subaccounts, requirements and tasks, or organization units and members.", "Users need to compare values across shared columns such as owner, status, due date, amount, count, permissions, or last activity.", "Parent rows can summarize, contain, select, lock, or expand child rows, and child rows may have independent values or actions.", "The interface may support editable cells, row actions, selection, bulk operations, sorting, filtering, lazy loading, pagination, or virtual scrolling." ], "selectionRules": [ "Choose tree grid when hierarchical rows and tabular columns are both essential to the task.", "Use data grid when rows are flat and expansion is only a detail panel, grouping, or visual section.", "Use tree selection when users choose hierarchical nodes but do not need shared data columns or cell-level interaction.", "Use table when users only compare rows and any hierarchy can be represented by a separate column or grouping label.", "Use details panel or master-detail when a selected object's nested detail is easier to inspect beside the source grid than inline.", "Use accordion or disclosure details for short content groups that are not comparable rows.", "Avoid tree grid when parent-child relationships are decorative indentation rather than real containment.", "Avoid tree grid when sorting, filtering, lazy loading, or bulk selection cannot preserve descendant state truthfully.", "Avoid tree grid on narrow screens unless the product has a tested reduced-column, horizontal-scroll, or drill-in strategy.", "Avoid tree grid if the team cannot implement managed focus, aria-expanded, row levels, row positions, and screen reader verification." ], "requiredStates": [ "Default tree grid state with label, column headers, visible root rows, row hierarchy, row count context, and focused row or cell.", "Expanded parent row state with visible child rows, level indentation, and truthful aria-expanded state.", "Collapsed parent row state with child rows hidden, descendant count or state summary when relevant, and no focus left inside hidden rows.", "Leaf row state without expansion affordance or aria-expanded.", "Focused row or cell state that remains visually distinct from selected rows and checked rows.", "Single-select, multi-select, parent-selected, child-selected, and mixed-descendant states when selection is supported.", "Editable cell, readonly cell, dirty child row, invalid child value, saving, saved, and failed-save states when editing is supported.", "Sorted and filtered states that preserve hierarchy rules and explain hidden or empty parents.", "Lazy-loaded, loading-children, load-failed, virtualized, and paginated states with truthful row counts, levels, positions, and row indices.", "Narrow-screen state that preserves hierarchy, column meaning, expansion, and row actions or routes users to a focused detail view." ], "interactionContract": [ "The first column or row header communicates the hierarchical object name, level, expansion state, and parent-child relationship.", "Expansion and collapse affect only descendant rows and never leave keyboard focus on a hidden row.", "Rows without children do not expose expansion state or an inert disclosure control.", "Arrow keys move by row or cell according to the documented focus model; Right Arrow expands collapsed parents or moves into cells, and Left Arrow collapses expanded parents or moves toward row focus.", "Tab enters and exits the composite predictably and does not force users through every visible cell unless the row has an intentional inner-widget sequence.", "Selection is independent from focus in multi-select tree grids and makes descendant inclusion, exclusion, or mixed state explicit.", "Sorting, filtering, pagination, refresh, and lazy loading preserve expanded state, selected descendants, dirty edits, and focused row whenever possible.", "Parent rows state whether values are aggregates, inherited values, editable values, or actions that apply to descendants." ], "implementationChecklist": [ "Define the hierarchy model, root rows, child rows, leaf rows, row identifiers, parent identifiers, columns, and expansion ownership.", "Choose whether focus is row-first, cell-first, or cell-only and document the keyboard model in the UI.", "Use treegrid, row, columnheader, rowheader, and gridcell semantics, or native table semantics with role treegrid when appropriate.", "Set aria-expanded only on parent rows or the controlling rowheader cell, and remove it from leaves.", "Expose aria-level, aria-posinset, aria-setsize, aria-rowcount, aria-colcount, aria-rowindex, and aria-colindex when rows or columns are dynamic, virtualized, lazy-loaded, or not all present in the DOM.", "Keep expansion icons decorative when their state is already exposed by the parent row or cell.", "Distinguish focus, selection, checked state, mixed descendant state, dirty edits, invalid cells, and loading children with text or programmatic state, not color alone.", "Define how sorting and filtering treat descendants, parent aggregates, collapsed selected children, lazy-loaded children, and empty parent branches.", "Test keyboard navigation, expansion, collapse, selection, editing, screen reader announcements, lazy loading, virtual scroll, high contrast, zoom, and mobile layouts." ], "commonMisuses": [ "Using treegrid for a flat data grid with no expandable parent rows.", "Using treegrid for a simple folder tree that has only one label column and no tabular comparison.", "Putting aria-expanded on leaf rows or every first-column cell.", "Collapsing a parent while focus, validation, or dirty edits remain hidden inside descendants.", "Sorting child rows away from parents without explaining the hierarchy rule.", "Losing selected children when a parent is collapsed, filtered, virtualized, or paged away.", "Rendering nested tables inside expandable rows instead of one coherent row and column model.", "Treating parent rows, aggregate values, inherited values, and editable child values as the same interaction." ], "critiqueQuestions": [ "What parent-child relationship does the first column encode?", "Which rows are parents, which are leaves, and what happens to hidden descendants when a parent collapses?", "Does the task require comparing columns across hierarchical rows, or is a tree selection enough?", "Is focus row-first, cell-first, or cell-only, and can users recover after expansion, collapse, sort, filter, and lazy load?", "Are selected, focused, mixed, dirty, invalid, readonly, and loading states visibly and programmatically distinct?", "Would a flat data grid, table, tree selection, details panel, accordion, or drill-in route be less costly?" ], "relatedPatterns": [ "data-grid", "tree-selection", "table", "details-panel", "filter-panel", "sort-controls", "empty-state" ], "comparisons": [ "tree-grid-vs-data-grid-vs-tree-selection-vs-table" ], "sourceIds": [ "wai-aria-apg-treegrid", "mdn-aria-treegrid-role", "kendo-react-treelist-keyboard", "kendo-react-treelist-aria", "devextreme-treelist-keyboard" ] }, { "id": "tree-selection", "completionStatus": "complete", "name": "Tree selection", "category": "Selection And Choice", "patternType": "ui-ux", "surfaceType": "Hierarchical expandable selection tree", "maturity": "standard", "platforms": [ "web", "desktop" ], "problem": "Users need to select items from a hierarchy, but flat lists hide parent-child context, and ordinary nested checkboxes do not provide expand/collapse state, tree keyboard navigation, focus management, or selected-descendant feedback.", "solution": "Provide a labelled tree selection widget with expandable branches, selectable treeitems, explicit selected or checked state, mixed parent state when needed, focus independent from selection, keyboard navigation, typeahead, and clear rules for branch and leaf selection.", "uiGuidance": [ "Render a labelled tree with visible levels, branch expanders, parent versus leaf styling, active focus, selected or checked state, parent mixed state, and a summary for selected descendants hidden inside collapsed branches.", "Keep tree rows focused on hierarchy and selection state; move row actions, rich metadata, editable fields, and tabular columns to adjacent panels, toolbars, tables, data grids, or tree grids." ], "uxGuidance": [ "Use tree selection when users need to choose one or more items from a meaningful hierarchy and the parent-child structure helps them find, understand, or batch-select nodes.", "Make exploration safe by separating focus from selection, preserving selected descendants when branches collapse, supporting predictable Arrow-key expansion, and explaining whether selecting a branch affects its children." ], "uiExamples": { "good": [ "A permissions picker shows Workspace, Reports, Billing, and Security branches with disclosure controls, selected leaf nodes, a mixed Reports parent, and a selected-count summary on collapsed parents.", "A folder picker marks folders as expandable treeitems and files as leaf treeitems without aria-expanded, while the active row has a distinct focus ring separate from selected rows.", "A taxonomy selector allows leaf-only selection and hides checkboxes on nonselectable category nodes while preserving the tree's level indentation and keyboard model." ], "bad": [ "A nested checkbox list uses indentation but no tree role, no active row, no branch expanded state, and no keyboard model beyond tabbing through every checkbox.", "A collapsed branch hides selected children with no mixed or selected descendant indicator on the parent row.", "Every leaf item exposes aria-expanded=false, causing assistive technology to announce files or products as collapsible folders." ] }, "uxExamples": { "good": [ "A user focuses Reports, presses Right Arrow to open it, moves to Monthly revenue, presses Space to select it, and the Reports parent becomes mixed.", "A user collapses Reports after selecting a child and still sees a selected-descendant badge on the collapsed parent.", "A user types A to jump to Audit logs, selects the node, and the active focus remains visibly separate from the selected set." ], "bad": [ "A user arrows through the permission tree to explore branches and accidentally changes selected permissions because selection follows focus in a multi-select tree.", "A user selects a parent branch but cannot tell whether children were selected, partially selected, or left unchanged.", "A user expands a lazily loaded branch and screen reader users hear new nodes with no level, position, or loading status." ] }, "problemContext": [ "The choices are naturally hierarchical, such as folders, permissions, taxonomy categories, organization units, product groups, or nested settings.", "Users need to expand and collapse branches to control detail while preserving selected nodes.", "Selecting a parent may imply selecting descendants, selecting only the parent, or showing a mixed state; the product must define that rule.", "Users may need to select several nodes while exploring the hierarchy without accidental selection changes.", "The hierarchy can be large enough to require typeahead, lazy loading, selected-count summaries, or dynamic position metadata." ], "selectionRules": [ "Choose tree selection when hierarchy is meaningful to the user's selection task and the parent-child relationship changes how options are found or interpreted.", "Use listbox when options are flat and users only need a visible selectable list without branch expansion.", "Use checkbox group when the option set is short, flat, and independent enough for native checkboxes.", "Use transfer list when users need to move selected items into a separate destination pane for review or ordering.", "Use tree grid when rows need columns, editable cells, row actions, sorting, or tabular comparison.", "Use navigation tree only when selecting a node changes page location rather than choosing values for a form or operation.", "Use aria-selected or aria-checked consistently; choose checkbox-style visual treatment when branch and mixed state are central.", "Avoid tree selection when hierarchy is used only to compress a long flat list; use search, grouping, filters, or autocomplete instead." ], "requiredStates": [ "Initial tree state with visible label and root-level nodes.", "Expanded parent node with visible child group.", "Collapsed parent node with hidden child group.", "Focused active treeitem state distinct from selected state.", "Selected leaf node state.", "Unselected selectable node state.", "Mixed or partially selected parent state.", "Selected collapsed branch summary state.", "Nonselectable branch or leaf state.", "Single-select and multi-select policy states.", "Typeahead matched node state.", "Lazy-loading branch state with loading feedback and eventual level and position metadata.", "Required empty-tree-selection validation state with selected branches and collapsed descendants preserved." ], "interactionContract": [ "The tree container has role tree and a visible label referenced by aria-labelledby or an accessible name.", "Each selectable node has role treeitem and exposes selected state with either aria-selected or aria-checked, used consistently across the tree.", "Parent nodes that own children expose aria-expanded true or false; leaf nodes do not expose aria-expanded.", "Child collections are grouped with role group or an equivalent owned treeitem relationship.", "In multi-select trees, the tree exposes aria-multiselectable and focus movement does not alter selection unless the user explicitly toggles selection.", "Right Arrow opens a closed parent or moves from an open parent to its first child; Left Arrow closes an open parent or moves focus to the parent from a child.", "Up and Down Arrow move through visible treeitems only; hidden collapsed descendants are not reachable.", "Space toggles the focused selectable node, and branch selection rules update child and parent mixed states predictably.", "Typeahead moves focus to the next visible matching node without changing selection.", "Collapsed branches with selected descendants remain visibly marked so users do not lose track of hidden selections." ], "implementationChecklist": [ "Confirm that hierarchy is essential to selection rather than presentation grouping or navigation.", "Define whether users can select branches, leaves only, multiple nodes, ranges, or entire subtrees.", "Choose either aria-selected or aria-checked for selectable treeitems and keep visual state aligned with the accessibility tree.", "Implement role tree, role treeitem, group nesting, accessible labels, aria-expanded only on parents, and aria-multiselectable when multiple nodes can be selected.", "Implement roving tabindex or aria-activedescendant, visible focus, Arrow-key expansion and movement, Home, End, typeahead, Space selection, and optional range selection.", "Show selected-descendant state on collapsed parents and mixed state when a branch has only some selected descendants.", "Preserve selected nodes during collapse, filtering, async loading, validation, route changes, and save errors.", "For dynamically loaded or virtualized trees, maintain aria-level, aria-setsize, aria-posinset, loading status, and stable active descendant IDs.", "Test keyboard, screen reader, high zoom, forced colors, long labels, deep nesting, collapsed selected branches, branch selection, leaf-only policy, and touch fallback." ], "commonMisuses": [ "Using tree selection for a flat list where listbox, checkbox group, or multi-select would be simpler.", "Styling nested checkboxes as a tree without tree keyboard behavior or expanded state.", "Letting focus movement change multi-selection while users are only exploring nodes.", "Putting aria-expanded on leaf nodes.", "Mixing aria-selected and aria-checked with the same meaning in one tree.", "Hiding selected children inside collapsed branches with no parent summary or mixed state.", "Using tree selection for ordinary site navigation or menu commands.", "Putting independent buttons, menus, or editable fields inside treeitems instead of using a tree grid or adjacent actions." ], "critiqueQuestions": [ "Is the hierarchy meaningful to the selection decision, or is this a flat list with indentation?", "Can users tell which row has focus versus which nodes are selected?", "What happens when users select a parent branch: descendants selected, branch only, mixed, or blocked?", "Are selected descendants still visible through parent state after a branch collapses?", "Can keyboard users expand, collapse, move, typeahead, select, and validate without tabbing through every node?" ], "relatedPatterns": [ "listbox", "checkbox-group", "multi-select", "transfer-list", "combobox", "navigation-drawer" ], "comparisons": [ "tree-selection-vs-listbox-vs-checkbox-group-vs-transfer-list" ], "sourceIds": [ "wai-aria-apg-treeview", "mdn-aria-tree-role", "mdn-aria-treeitem-role", "mui-tree-view-selection" ] }, { "id": "two-factor-authentication", "completionStatus": "complete", "name": "Two-factor authentication", "category": "Task And Workflow Patterns", "patternType": "ui-ux", "surfaceType": "Additional-factor challenge and recovery flow", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Two-factor authentication adds security at a high-friction moment, so unclear factor prompts, inaccessible code entry, missing alternatives, weak recovery, bypassable enforcement, or unsafe trusted-device choices can lock out legitimate users or let attackers defeat the second factor.", "solution": "Provide a bounded additional-factor challenge that names the protected action, supports the enrolled factor, gives safe resend and retry states, offers enrolled alternatives and recovery codes, prevents bypass, explains trusted-device scope, protects factor changes, and returns users to the original task after successful verification.", "uiGuidance": [ "Render two-factor authentication as a focused additional-factor challenge with factor name, destination or protected action, delivery hint, code or approval input, resend timing, alternate factor, recovery-code route, trusted-device choice, and safe failure handling.", "Keep the challenge separate from the broader sign-in journey, login attempt outcome, password reset, and ordinary password input so users can understand which proof is being requested." ], "uxGuidance": [ "Use two-factor authentication when the product needs stronger proof after a password, passkey, SSO return, risk signal, new device, or sensitive action.", "Help legitimate users complete the challenge while preserving account security by supporting paste and autofill for codes, explaining wait times, offering enrolled alternatives, protecting recovery codes, and making factor loss recoverable without easy bypass." ], "uiExamples": { "good": [ "A code screen says Enter the 6-digit code from your authenticator app to continue to payroll settings, uses autocomplete one-time-code, shows Try another method, and explains recovery codes.", "A trusted-device option says Do not ask again on this browser for 30 days and links to device management before the user opts in." ], "bad": [ "A page says Security check with one empty field, no factor label, no resend timing, and no recovery route.", "A push approval screen has only Approve on phone and no alternative for a lost or offline device." ] }, "uxExamples": { "good": [ "A user signs in from a new laptop, enters a code from an authenticator app, chooses not to trust the shared browser, and lands back on the requested workspace.", "A user lost the phone, uses a single-use recovery code, receives a notification, and is prompted to add a replacement factor after reauthentication." ], "bad": [ "A user never receives an SMS code and can only keep pressing resend with no wait time, no alternate factor, and no support path.", "An attacker who knows the password changes the enrolled phone number without passing any existing factor or recovery check." ] }, "problemContext": [ "The user has completed or started a primary sign-in step, returned from SSO, triggered a risk rule, opened a new device, or started a sensitive action.", "The product may support authenticator apps, SMS or email codes, push approvals, passkeys, hardware keys, backup codes, trusted devices, remembered browsers, or administrator recovery.", "Second-factor prompts can arrive during ordinary sign in, transaction authorization, account settings, factor enrollment, factor change, or recovery after device loss.", "MFA security depends on server-side enforcement; the UI cannot let users bypass the challenge through navigation, cached pages, API calls, or alternate tabs.", "Users may have no signal, a changed phone, a lost device, a new browser, an inaccessible challenge, or a recovery code stored separately from the device." ], "selectionRules": [ "Choose two-factor authentication when the user must satisfy an additional factor after a primary credential, SSO return, passkey flow, risk signal, new device, or sensitive action.", "Use sign in for the broader authentication entry route that chooses identifiers, passwords, passkeys, SSO, recovery, and return destinations.", "Use login for the submitted credential result before a second factor is requested or after the factor result returns.", "Use password reset when the user cannot authenticate with the existing password and needs to replace it through recovery.", "Use password input only for reusable password entry; second-factor codes and recovery codes need their own autocomplete, expiry, resend, and attempt-limit behavior.", "Name the requested factor, protected destination or action, delivery channel hint, expected code length or approval device, and safe alternative methods.", "Allow paste, autofill, password-manager code fill, and native one-time-code behavior for short-lived codes.", "Show resend wait time, attempt limits, expired-code state, wrong-code state, and rate-limit state from server policy.", "Offer enrolled alternate factors, recovery codes, and support escalation without turning recovery into an easier path than the second factor.", "Make remember-device choices explicit, scoped to a browser or device, time-limited when policy requires, and revocable from account settings.", "Require reauthentication, existing factor proof, recovery-code use, or stronger support verification before disabling MFA, adding a new factor, or changing the recovery channel.", "After success, clear challenge state, record security events, notify when policy requires, and return to the original destination or sensitive action." ], "requiredStates": [ "Initial additional-factor challenge with factor name, destination or protected action, and primary account context.", "One-time-code entry state with autocomplete one-time-code, paste support, expiry hint, and submit control.", "Push approval or hardware-key waiting state with clear device or key instruction and fallback.", "Resend-limited state with wait time and delivery-channel hint.", "Wrong-code state with remaining attempts and no code echo.", "Expired-code state with resend or try-another-method action.", "Alternate-factor selection state limited to enrolled methods.", "Recovery-code state that treats each backup code as single-use and security-sensitive.", "Trusted-device choice state with scope, duration, and revocation explanation.", "Success state that returns to the protected task and clears challenge warnings.", "Lost-factor or support-required state with stronger identity verification.", "Factor-management state for add, remove, replace, or regenerate recovery codes." ], "interactionContract": [ "The challenge appears only when the server requires additional verification and the protected action remains blocked until success.", "The UI names the factor and destination without exposing unnecessary account details on shared screens.", "Code entry supports paste, autofill, correction, and screen-reader announcements without splitting focus into inaccessible traps.", "Wrong, expired, reused, or rate-limited codes are handled as distinct recoverable states without displaying the submitted secret back to the user.", "Alternate methods only list enrolled factors or approved recovery routes, not unverified contact details an attacker can add during the challenge.", "Recovery codes are single-use, rate-limited, treated as secrets, and followed by notification or factor-replacement guidance.", "Remember-device choices do not default on shared or risky contexts and can be reviewed or revoked later.", "Successful verification clears transient challenge state and returns to the sign-in destination or sensitive action." ], "implementationChecklist": [ "Define factor types, assurance requirements, phishing-resistant options, code length, expiry, attempt limits, resend limits, recovery-code format, trusted-device scope, and factor-management policy with security owners.", "Map authenticator app, SMS, email, push, passkey, hardware key, recovery code, lost device, and support-assisted states to clear UI copy and server outcomes.", "Use autocomplete one-time-code for short-lived codes and test paste, autofill, password-manager fill, mobile keyboards, browser Back, refresh, and multiple tabs.", "Enforce MFA on protected endpoints, not only in the UI route, and test direct URL navigation, API access, cached pages, remembered devices, and session fixation cases.", "Protect codes, recovery codes, device identifiers, push details, and failure reasons from analytics, logs, screenshots, support tools, and URLs.", "Test wrong code, expired code, reused recovery code, resend rate limit, alternate method, lost device, disabled factor, factor change, trusted-device revocation, high-risk account, screen reader flow, and mobile layout." ], "commonMisuses": [ "Showing a code field with no factor label, destination, expiry, resend timing, or alternate method.", "Blocking paste or autocomplete for one-time codes.", "Letting users bypass MFA through browser Back, deep links, cached pages, API calls, or another tab.", "Treating SMS as the only possible second factor for all users and all risk levels.", "Allowing recovery codes to be reused, stored like ordinary text, or regenerated without stronger verification.", "Defaulting remember-device on public or shared computers.", "Allowing factor removal, phone change, or authenticator replacement with only the password.", "Logging codes, recovery codes, push details, or exact failure reasons." ], "critiqueQuestions": [ "Which second factor is required here, and why is it being requested for this destination or action?", "Can users complete the challenge with paste, autofill, hardware keys, passkeys, mobile keyboards, and assistive technology?", "What are the server-backed expiry, resend, wrong-code, and rate-limit states?", "Can the challenge be bypassed through navigation, cached pages, API calls, remembered devices, or alternate tabs?", "Which recovery paths are available, and are they at least as protective as the factor they replace?", "How are trusted devices scoped, timed, displayed, and revoked?", "What proof is required before adding, removing, or replacing factors?" ], "relatedPatterns": [ "sign-in", "login", "password-reset", "password-input", "session-timeout-warning", "permission-denied-state" ], "comparisons": [ "two-factor-authentication-vs-sign-in-vs-login-vs-password-reset" ], "sourceIds": [ "owasp-multifactor-authentication-cheat-sheet", "owasp-wstg-mfa-testing", "nist-sp-800-63b-authentication-lifecycle", "mdn-autocomplete-credentials", "html-autocomplete-webauthn" ] }, { "id": "typeahead", "completionStatus": "complete", "name": "Typeahead", "category": "Search, Browse, And Discovery", "patternType": "ui-ux", "surfaceType": "Live search-as-you-type result lookup with incremental result preview", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users often need fast feedback while searching large content sets, but waiting for explicit submit slows exploration and naive every-keystroke search can produce flicker, stale results, accidental selection, and wasted requests.", "solution": "Provide a live typeahead result panel that updates from the current query with clear thresholds, loading, stale-response handling, keyboard support, and distinct actions for selecting a hit or submitting the full query.", "uiGuidance": [ "Render a labelled input with a live result panel that shows matching result hits, result count, active result, source labels, and loading or stalled state while the user types.", "Keep the typed query visually separate from result selection; do not make the top live hit look like it has already replaced or committed the user's text." ], "uxGuidance": [ "Use typeahead when users benefit from immediate result feedback while typing and can either open a result hit or continue to a full submitted search.", "Protect the typing flow with minimum length, debounce, request cancellation or stale-response guards, empty preview copy, keyboard navigation, and a clear final submit path." ], "uiExamples": { "good": [ "Typing ca opens a panel with live case, calendar, and claim results, a 3 results for ca count, active row styling, and source labels.", "A slow network state keeps the typed query visible and shows Searching for case... instead of clearing the panel.", "A short one-character query says Type at least 2 characters before searching so the empty panel is not mistaken for zero results." ], "bad": [ "The input silently becomes Case 104 because the first result was auto-filled while the user was typing ca.", "Rows flicker between old and new results with no loading state or query label.", "Query suggestions, ads, recent searches, and result hits are mixed in one list without source labels." ] }, "uxExamples": { "good": [ "A user types cas, sees matching case records immediately, selects Case 104, and can still edit the query or submit a full search.", "A user types c, sees the two-character threshold message, then types ca and receives live results.", "A user types case quickly and the product ignores stale ca results when the newer case response arrives." ], "bad": [ "Users cannot finish typing because focus jumps into the first result on every keystroke.", "Slow old results overwrite newer query results and users open the wrong record.", "Every typed character sends a remote request, making the panel stutter and increasing cost." ] }, "problemContext": [ "The product has a large searchable result set where users can identify useful hits from partial input.", "The search backend or index can support low-latency prefix or as-you-type matching.", "The interface must balance immediate feedback with network cost, privacy, mobile typing, and keyboard control." ], "selectionRules": [ "Choose typeahead when live result hits should appear as the user types and the result set can update safely before explicit submit.", "Set a minimum query length before searching when short prefixes produce noisy, expensive, or privacy-sensitive results.", "Debounce or pace remote requests and ignore stale responses so older results cannot overwrite newer query state.", "Show a loading, searching, or stalled state when live results are not yet ready.", "Keep typed text under user control; selecting a hit should not be confused with auto-filling the input.", "Let users open a typeahead result directly or submit the typed query for a full result page.", "Use autocomplete when the field must resolve to a known value; use search suggestions when rows are suggested query phrases; use basic search when results should wait for explicit submit.", "Show result type, source, count, and enough secondary metadata to distinguish similar hits.", "Handle no live results, offline or failed lookup, cleared input, input blur, Escape dismissal, and mobile viewport constraints.", "Avoid typeahead for sensitive searches, high-latency backends, costly queries, or domains where every keystroke should not leave the device." ], "requiredStates": [ "Empty state before typing.", "Below-minimum-length state explaining when live lookup begins.", "Loading or stalled state tied to the current query.", "Populated live-result state with result count, source labels, and active result.", "Selected result state where opening a hit is distinct from submitting the query.", "No live results state for the current typed query.", "Stale-response ignored state when older results arrive after a newer query.", "Submitted full-search state after the user explicitly searches the current query." ], "interactionContract": [ "Typing changes the query and schedules live lookup only when the minimum length and privacy rules allow it.", "Each response must be associated with the query that requested it and ignored if the user has typed a newer query.", "The active result can move with arrow keys without replacing the input value.", "Enter opens the active result only when result focus or active option semantics make that explicit; otherwise it submits the query.", "Escape closes the typeahead panel without clearing the typed query.", "Clicking or pressing a result opens that result or previews it, while final search submit runs the typed query.", "Clearing input cancels pending live lookup and resets result, loading, and active-result state." ], "implementationChecklist": [ "Define whether rows are result hits, entities, commands, or query suggestions and label the source accordingly.", "Configure minimum length, debounce interval, maximum visible results, request timeout, and stale-response guard.", "Implement loading, stalled, no-results, error, offline, and cleared states for live lookup.", "Preserve typed query separately from selected result ID and full-search submitted query.", "Expose combobox or listbox semantics when the panel behaves like selectable options, including active descendant or equivalent focus management.", "Provide keyboard behavior for arrow movement, Enter, Escape, Tab, and pointer selection.", "Test rapid typing, deleting text, IME composition, mobile keyboards, screen readers, slow responses, failed responses, privacy-sensitive queries, and result opening.", "Measure request volume, stale response suppression, selected result rate, full-search rate, no-result rate, and abandoned typeahead panels." ], "commonMisuses": [ "Calling a known-value autocomplete field typeahead even though no result set is searched.", "Calling suggested query phrases typeahead when no live result hits are shown.", "Auto-filling the first result into the input while users type.", "Sending a remote request for every keystroke with no debounce or minimum length.", "Letting stale results overwrite the current query's result panel.", "Showing no loading or stalled state during slow lookup.", "Mixing ads, recent searches, query suggestions, and result hits without source labels.", "Moving keyboard focus out of the input unexpectedly." ], "critiqueQuestions": [ "Are rows live result hits for the current typed query, or are they query suggestions or known-value options?", "What minimum length and debounce policy prevents noisy or expensive every-keystroke search?", "How does the UI show loading, stalled, no-result, and stale-response states?", "Can users keep typing without the first result replacing their query?", "Does Enter open an active result or submit the query, and is that contract clear?", "Can users distinguish source, type, and relevance of live hits?", "What privacy, telemetry, or backend-cost constraints apply to sending partial queries?" ], "relatedPatterns": [ "autocomplete", "search-suggestions", "basic-search", "search-result-highlighting", "query-correction", "recently-searched", "command-palette", "no-results-recovery" ], "comparisons": [ "typeahead-vs-autocomplete-vs-search-suggestions-vs-basic-search" ], "sourceIds": [ "algolia-autocomplete-js", "elasticsearch-search-as-you-type", "carbon-search-pattern", "wai-aria-apg" ] }, { "id": "typed-confirmation", "completionStatus": "complete", "name": "Typed confirmation", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Exact target phrase gate before severe commit", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "For severe destructive or irreversible actions, users can still confirm the wrong target if the final review only uses buttons, checkboxes, or generic phrases that do not force them to attend to the exact object or scope.", "solution": "Require users to type a visible, exact target phrase such as a repository path, project slug, workspace name, or short destructive phrase before enabling the final commit, while preserving the broader consequence review and safe cancellation path.", "uiGuidance": [ "Render a visible non-secret text field inside a destructive or high-consequence confirmation, labelled with the exact target phrase the user must type before the final action enables.", "Place the required phrase, match rule, mismatch status, safe cancellation, and final destructive button in the same review surface so users can compare what they type against the actual object." ], "uxGuidance": [ "Use typed confirmation only when reproducing the target phrase meaningfully reduces severe wrong-object or wrong-scope mistakes, such as deleting a repository, project, account, workspace, production dataset, or root credential.", "Treat typed confirmation as an escalation on top of consequence review: it verifies target intent but does not replace loss inventory, dependency checks, permissions, audit, recovery limits, or safe cancellation." ], "uiExamples": { "good": [ "Delete repository acme/payments-api? requires typing acme/payments-api, shows a mismatch until the exact path matches, and then enables Delete repository.", "Delete production dataset ledger-prod? shows the dataset name, region, dependent jobs, and a visible field where users type ledger-prod before final deletion.", "Reset root API key? asks users to type RESET ROOT KEY and keeps the final reset button disabled until the phrase matches exactly." ], "bad": [ "A dialog asks users to type YES before deleting a workspace, so the text does not verify the target object.", "The typed field is masked like a password, making users unable to check the repository name they entered.", "The final destructive button stays enabled after the user switches from one selected project to another." ] }, "uxExamples": { "good": [ "A user starts deleting acme/payments-api, mistypes the repository path, sees the mismatch, and cancels before deleting the wrong repository.", "A user pastes a project path with a trailing space, sees that normalization trimmed whitespace but still requires the exact path text.", "A user cannot type the target phrase while a dependency block is active, so they resolve the block before the exact-match gate can enable deletion." ], "bad": [ "A user types DELETE by habit and passes the gate without checking which workspace will be removed.", "A user on mobile cannot reproduce a hidden Unicode character in the required phrase and cannot finish the legitimate action.", "A user believes typing the phrase is the only safeguard, but the dialog hides forks, members, billing effects, and recovery limits." ] }, "problemContext": [ "The action affects broad, production, security-sensitive, account-level, repository-level, or organization-level scope.", "A wrong-object mistake would be difficult or impossible to recover from even after ordinary destructive confirmation.", "The target has a stable identifier users can read and type, such as owner/name, project slug, dataset name, account email, or a short action phrase.", "The interface already has a destructive action confirmation or high-consequence dialog where typed confirmation can be added without hiding loss information." ], "selectionRules": [ "Choose typed confirmation when exact target reproduction materially lowers the risk of deleting or resetting the wrong object.", "Use a target-specific required phrase such as owner/repository, namespace/project, workspace slug, dataset name, or account email.", "Use a short action phrase only when no stable object identifier exists, and keep it specific to the destructive act.", "Keep typed confirmation visible and unmasked; it is not a password or secret.", "Disable the final action until the match rule passes and any dependency or acknowledgement requirements are satisfied.", "Explain whether matching is case-sensitive, whitespace-normalized, locale-aware, or requires the full path.", "Do not ask for typed confirmation on routine actions, soft delete to trash, reversible cleanup, or high-frequency flows.", "Do not use typed confirmation as the only safeguard for broad deletion; still show scope, loss inventory, permissions, recovery limits, and final status.", "Prefer ordinary destructive action confirmation when the object name is short, low-risk, or already unambiguous enough that typing adds only friction." ], "requiredStates": [ "No-typed-gate state for actions that do not need target-text escalation.", "Required phrase state showing the exact target phrase to reproduce.", "Empty input state with the final action disabled.", "Mismatch state explaining what does not match without committing the action.", "Exact-match state enabling the final action only after all other blockers pass.", "Pasted text and whitespace state that handles trailing spaces, line breaks, and copy errors predictably.", "Target changed state that clears stale typed text when the selected object changes.", "Dependency-blocked state where exact match is not enough until jobs, locks, permissions, or billing blockers resolve.", "Committed outcome state that reports the severe action after deliberate typed confirmation." ], "interactionContract": [ "The required phrase is visible in the same confirmation surface as the input field.", "The input stores ordinary text and must not use password masking or browser password managers.", "The final action starts disabled and remains disabled until the typed value satisfies the documented match rule.", "Changing the target object, selected scope, account, locale, or destructive mode clears the typed value.", "Mismatch feedback updates as users type without announcing every character as an error.", "Pasting is allowed unless policy has a strong reason to block it; pasted values still pass through the same match rule.", "The safe cancel action remains available before and after typing.", "The typed phrase is not logged in analytics unless it is already a non-sensitive public identifier and logging is explicitly safe." ], "implementationChecklist": [ "Select the shortest stable phrase that uniquely identifies the target and can be typed on supported devices.", "Display the required phrase in selectable text near the input label.", "Define match normalization for case, Unicode normalization, leading and trailing whitespace, line breaks, and locale.", "Use an ordinary text input with autocomplete off when appropriate, not a password field.", "Clear the field when target, scope, account, or destructive action changes.", "Pair the typed gate with loss inventory, dependency checks, safe cancellation, and duplicate-submit prevention.", "Show mismatch and exact-match status without relying only on color.", "Test keyboard entry, paste, screen-reader labels, mobile keyboards, zoom, long repository paths, and localized object names.", "Avoid collecting typed confirmation text in analytics, replay, logs, or crash reports when it may contain private identifiers." ], "commonMisuses": [ "Requiring users to type yes, confirm, or delete instead of the target name.", "Masking typed confirmation as if it were a password.", "Accepting partial, stale, or wrong-target text.", "Making typed confirmation the only safeguard while hiding the loss inventory.", "Using typed confirmation for every delete action until users memorize the ritual.", "Blocking paste or mobile entry in ways that make legitimate confirmation harder than the risk warrants.", "Logging typed private object names through analytics or session replay." ], "critiqueQuestions": [ "What exact wrong-object mistake does typing the phrase prevent?", "Is the required phrase stable, visible, unique, and typeable on mobile?", "What normalization rule decides a match, and is it explained to users?", "What clears stale typed text when target or scope changes?", "Does the field behave like visible text rather than a password?", "Would ordinary destructive confirmation, undo, or restore-from-trash be enough?", "What evidence proves the final action stayed disabled until the exact match and other blockers passed?" ], "relatedPatterns": [ "destructive-action-confirmation", "confirmation-dialog", "password-input", "undo", "warning-text" ], "comparisons": [ "typed-confirmation-vs-destructive-action-confirmation-vs-confirmation-dialog-vs-password-input" ], "sourceIds": [ "github-delete-repository-confirmation", "gitlab-delete-project-confirmation", "microsoft-windows-confirmations", "wai-aria-apg-alertdialog" ] }, { "id": "undo", "completionStatus": "complete", "name": "Undo", "category": "Error Prevention And Recovery", "patternType": "ux", "surfaceType": "Post-action recovery behavior", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users need to recover from common reversible actions after acting quickly, without being blocked by confirmation prompts before every low-risk command.", "solution": "Let the action complete, preserve the exact prior state, report what changed, expose a clearly labelled recovery control, and resolve to either restored state or committed final state.", "uiGuidance": [ "Show a named recovery affordance after the completed action, such as Undo delete for a specific task, near the result or in a consistent status region.", "Keep the recovery control visible, keyboard reachable, and paired with clear restored or committed status instead of relying on an ambiguous disappearing message." ], "uxGuidance": [ "Let users move quickly through frequent reversible actions, then recover from mistakes after seeing the result.", "Use undo only when the product can faithfully restore the prior state and clearly communicate when recovery is no longer available." ], "uiExamples": { "good": [ "Deleting Quarterly report removes it from the list and shows a recovery panel saying Quarterly report deleted with an Undo task button.", "The recovery panel also exposes a commit outcome so users can see when the deletion is final." ], "bad": [ "A tiny x removes an item with no object-specific recovery label.", "A toast says Done and vanishes without a keyboard reachable undo control." ] }, "uxExamples": { "good": [ "Undo restores the deleted task to the list and reports Quarterly report restored.", "Committing deletion removes the recovery action and reports that the deletion is final." ], "bad": [ "A second delete overwrites the first recoverable item without explaining which action Undo affects.", "The UI promises undo for a side effect that has already notified external recipients." ] }, "problemContext": [ "The action is frequent enough that pre-action confirmation would slow users down or become automatic.", "Mistakes are plausible because users act quickly, work in lists, use shortcuts, or perform repeated cleanup.", "The system can restore the affected object, value, order, selection, or relationship accurately.", "The action has no irreversible external effect before the recovery window closes." ], "selectionRules": [ "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." ], "requiredStates": [ "Normal state before the user action.", "Completed-but-recoverable state that names what changed and exposes an undo control.", "Restored state after undo returns the exact object, value, order, or selection.", "Committed final state after the recovery window expires or the user confirms finalization.", "Unavailable state when undo cannot be offered because the action has external or irreversible effects.", "Multiple-action state where each recoverable action is either queued, grouped, or clearly scoped." ], "interactionContract": [ "The undo affordance appears after the action completes and names what will be restored.", "Undo restores the affected state exactly enough that the user can trust it.", "The recovery control is keyboard reachable and remains available long enough for users to perceive and activate it.", "The interface reports whether the action is recoverable, restored, expired, or permanently committed.", "Focus is not unexpectedly stolen from the user's workflow when a routine recoverable action completes.", "If multiple actions are recoverable, the UI makes the scope of each undo action clear.", "Undo is not offered for effects that have already left the system boundary and cannot be recalled." ], "implementationChecklist": [ "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." ], "commonMisuses": [ "Offering undo for an action that cannot actually be reversed.", "Showing a recovery control so briefly that users cannot perceive or reach it.", "Restoring only part of the prior state while implying full recovery.", "Using a vague Undo label when several actions could be undone.", "Stealing focus to a transient notice after every routine action.", "Pairing a confirmation dialog and undo for ordinary cleanup actions, adding friction without extra safety." ], "critiqueQuestions": [ "What exact state is stored so the action can be reversed?", "Can any external recipient, payment, permission, notification, or webhook still observe the action after undo?", "How will users know whether the action is recoverable, restored, expired, or committed?", "Is the recovery affordance reachable by keyboard and visible long enough?", "What happens when users perform several recoverable actions in a row?", "Would a persistent trash, version history, or rollback log be safer than a short undo notice?" ], "relatedPatterns": [ "confirmation-dialog", "toast-only-critical-error" ], "comparisons": [ "undo-vs-confirmation-dialog" ], "sourceIds": [ "apple-hig-undo-redo", "material-design-snackbar", "microsoft-windows-confirmations", "apple-hig-alerts" ] }, { "id": "unsaved-changes-prompt", "completionStatus": "complete", "name": "Unsaved changes prompt", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Dirty-editor decision prompt before closing, canceling, switching, or replacing unsaved edits", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users can close an editor, cancel a modal, switch objects, replace selections, or exit edit mode while local changes are dirty, causing accidental loss or uncertainty about whether the latest values were saved.", "solution": "Track the dirty edit buffer, intercept abandonment or replacement actions, present a specific save-discard-stay decision with changed-field evidence, complete or fail saving before continuing, and clear the prompt only when the edit buffer is safe, intentionally discarded, or still preserved.", "uiGuidance": [ "Show a focused prompt when users try to close, cancel, switch records, replace content, or leave edit mode while current edits are dirty and not yet recoverable.", "Name the edited object, summarize what changed, and offer distinct Save changes, Discard changes, Review changes, and Keep editing choices when the system can support them." ], "uxGuidance": [ "Use an unsaved changes prompt to protect local edits at the moment a user is about to abandon or replace them inside the product.", "Treat the prompt as a decision about the current edit buffer: saving must complete before the close or switch continues, discarding must be deliberate, and staying must preserve every typed value." ], "uiExamples": { "good": [ "A profile editor close button opens Save changes to Billing contact?, lists edited phone and department fields, and offers Keep editing, Review changes, Save changes, or Discard changes.", "A report detail page blocks switching to another report while the current report has unsaved title and filter edits, then continues to the requested report only after save or discard succeeds." ], "bad": [ "A modal says Are you sure? when the user clicks Cancel, with OK and Cancel labels that do not say whether edits will be saved or discarded.", "A tab switch silently replaces the dirty editor with a different record and loses the user's typed notes." ] }, "uxExamples": { "good": [ "A user edits two fields, clicks Close, reviews the changed fields in the prompt, saves, and the editor closes only after the saved state is confirmed.", "A user chooses Keep editing from the prompt and returns to the same dirty editor with focus near the close control and all unsaved values intact." ], "bad": [ "A user chooses Save, the request fails, and the editor still closes as though the latest values were safe.", "A prompt appears for every close action even when no field changed, so users stop reading the actual discard warning." ] }, "problemContext": [ "The surface has editable values that can differ from the last saved record.", "A close, cancel, object switch, tab switch, mode switch, replace, or route action can remove the current edit buffer.", "The product can identify the object and at least a useful summary of changed fields.", "Users need to choose whether to keep editing, save first, review changes, or intentionally discard local edits." ], "selectionRules": [ "Choose unsaved changes prompt when a user action inside the product would abandon or replace dirty local edits before they are saved.", "Use exit warning when the trigger is broader page, browser, route, reload, external-link, or sign-out departure rather than a focused editor close or object switch.", "Use autosave form when reliable background saving makes abandonment safe or when the main job is continuous progress persistence.", "Use autosave recovery when saving has already failed or become uncertain and users need retry, copy, compare, or restore evidence.", "Use draft state when the unsaved work is a durable unpublished object that can be resumed later from lists or deep links.", "Use confirmation dialog for explicit consequential commands such as Delete, Cancel application, or Discard draft; an unsaved changes prompt is specifically about dirty edit-buffer loss.", "Show the prompt only when dirty state is real; do not prompt for clean editors, read-only views, or recoverable drafts already saved elsewhere.", "If Save changes is offered, keep the prompt open or show a saving state until the save succeeds; do not close the editor after failed save.", "If Discard changes is offered, label it as discard and identify the affected object or fields.", "Offer Review changes when users may need to inspect field-level differences before deciding." ], "requiredStates": [ "Clean editor state with no prompt.", "Dirty editor state with changed-field tracking.", "Close, cancel, object switch, or mode switch attempted state.", "Prompt open with object name and changed-field summary.", "Review changes state showing before and after values or changed sections.", "Save in progress state that blocks duplicate close or switch actions.", "Save failed state that keeps the editor open with values intact.", "Saved and continue state that closes or switches after success.", "Discarded state that clears the dirty buffer intentionally.", "Keep editing state that returns focus and preserves values." ], "interactionContract": [ "Opening the prompt never clears the dirty values.", "Keep editing closes the prompt, preserves all local values, and returns focus to the editor or triggering control.", "Review changes shows what changed before the user saves or discards.", "Save changes sends the current dirty values once, disables duplicate save and discard while saving, and continues only after success.", "A failed save leaves the prompt or editor visible, explains the failure, and keeps the unsaved values editable.", "Discard changes requires a deliberate action and clears only the named dirty buffer.", "After save, discard, or reset to clean state, the same close or switch action does not prompt again." ], "implementationChecklist": [ "Track dirty state from actual field values, not from opening an editor.", "Store changed field names, original values when safe to show, current values, target close or switch action, and save request state.", "Intercept close, cancel, record switch, tab switch, inline edit exit, modal dismissal, replacement, and route actions that would destroy the dirty buffer.", "Use explicit button labels such as Keep editing, Review changes, Save changes, and Discard changes.", "Make save idempotent or disable repeated save while a request is in flight.", "Keep values in memory and visible after save failure.", "Clear dirty state after confirmed save, explicit discard, reset, or successful autosave that truly covers the latest values.", "Test clean close, dirty close, object switch, failed save, double activation, discard, review, keyboard Escape, focus return, screen reader labels, and mobile dismissal gestures." ], "commonMisuses": [ "Prompting when nothing changed.", "Using OK and Cancel labels that hide whether edits will be saved, discarded, or preserved.", "Closing after Save even when the save request failed.", "Discarding all editor state when only one embedded panel was dirty.", "Showing a warning but omitting a way to keep editing.", "Replacing the dirty object during a tab or record switch without a save or discard decision.", "Relying on a disappearing toast to say edits were not saved." ], "critiqueQuestions": [ "What exact object or fields are dirty?", "Which user actions can destroy or replace the dirty edit buffer?", "Can users inspect changed fields before deciding?", "Does Save complete before close, cancel, or switch continues?", "What happens when Save fails or the user activates Save twice?", "Does Keep editing preserve values and return focus predictably?", "Does the prompt disappear for clean state?" ], "relatedPatterns": [ "exit-warning", "autosave-form", "autosave-recovery", "draft-state", "confirmation-dialog", "inline-edit" ], "comparisons": [ "unsaved-changes-prompt-vs-exit-warning-vs-autosave-form-vs-confirmation-dialog" ], "sourceIds": [ "mdn-beforeunload-event", "gitlab-saving-and-feedback", "microsoft-windows-confirmations", "wai-aria-apg-alertdialog" ] }, { "id": "user-controlled-density", "completionStatus": "complete", "name": "User-controlled density", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "User-selectable compactness for rows, lists, cards, tables, grids, or work surfaces", "maturity": "established", "platforms": [ "web", "mobile", "desktop" ], "problem": "Information-dense products need to support both scanning and comfortable reading, but fixed spacing forces every user into the same tradeoff or lets compact modes break readability, target size, focus, and state preservation.", "solution": "Provide a scoped density control that changes spacing and row height without changing content meaning, preserves task state, respects accessibility constraints, and lets users preview, save, reset, or keep density temporary.", "uiGuidance": [ "Render density as a visible segmented control, menu, or setting with named choices such as Comfortable, Standard, Compact, and Spacious, plus scope, preview, and reset feedback.", "Keep content, order, filters, selection, edits, and row identity stable when density changes; only spacing, row height, padding, and related control sizing should change." ], "uxGuidance": [ "Use user-controlled density when different users or moments call for scanning more items versus reading with more breathing room on the same surface.", "Protect readability and accessibility by maintaining labels, status text, focus indicators, row actions, touch targets, text scaling, and keyboard navigation across every density option." ], "uiExamples": { "good": [ "A case queue toolbar lets users switch Comfortable, Standard, and Compact row density, shows This table only, preserves selected rows, and keeps row actions readable.", "A workspace setting lets each user choose default list density for their account while previewing row height and resetting to organization default.", "A data grid density menu updates header height, row height, checkbox alignment, batch action height, and open detail rows together." ], "bad": [ "A compact toggle removes secondary labels and status chips instead of only reducing spacing.", "Changing density resets filters, selected rows, open rows, and unsaved edits.", "A personal compact choice saves as the shared team default without showing scope." ] }, "uxExamples": { "good": [ "A support agent switches a queue to Compact to scan SLA risk, keeps the focused row and filters intact, then returns to Comfortable before reading long notes.", "A touch-screen user selects Spacious, and row actions remain reachable while the same data, sort, and filters stay in place.", "A user previews Compact in a settings panel, saves it for their account only, and can reset just display density later." ], "bad": [ "A user shrinks density and accidentally clicks the wrong row action because target sizes collapsed.", "A compact table hides validation messages, so users cannot see which row failed.", "A saved view named Compact changes both spacing and filters, making users distrust view switching." ] }, "problemContext": [ "Users scan tables, queues, lists, cards, logs, inboxes, dashboards, or admin records with different preferences, devices, zoom levels, and task urgency.", "The same surface may need compact scanning for triage and comfortable spacing for review, editing, touch, or accessibility.", "Density may be temporary for one table, persisted for one user, inherited from a workspace setting, or unavailable on narrow screens.", "Changing density can affect row height, header height, batch action bars, checkboxes, menus, inline validation, focus rings, and open detail rows." ], "selectionRules": [ "Choose user-controlled density when users need to decide how much vertical or horizontal spacing a surface uses without changing which data is included.", "Use settings management when density is part of a broader durable configuration area rather than the primary pattern.", "Use saved view when users are saving filters, columns, sort, grouping, or dataset scope rather than spacing alone.", "Use data grid when the hard problem is managed cell focus, editing, selection, or row-and-column semantics.", "Use responsive layout when screen size requires a different structure; density should not be the only mobile adaptation.", "Offer compact density only where labels, icons, focus rings, row actions, status, and targets remain perceivable and operable.", "Show whether the density change is temporary, this surface only, this device, account-wide, workspace-wide, or organization-managed.", "Preserve current filters, sort, selected rows, expanded rows, edited values, scroll anchor, and focused item across density changes.", "Provide reset or system default recovery and avoid coupling density reset with unrelated layout, theme, saved view, or filter resets.", "Disable or adapt density choices when content length, touch mode, high zoom, screen width, or accessibility settings make compact spacing unsafe." ], "requiredStates": [ "Default density state", "Comfortable or spacious density state", "Standard density state", "Compact density state", "Preview-before-save state", "Temporary density state for current surface", "Saved personal density state", "Workspace or organization-managed density state", "Reset to system default state", "Unavailable or unsafe compact state", "Mobile or narrow-screen density fallback state", "Focus, selection, expanded-row, and edited-value preservation state" ], "interactionContract": [ "Changing density updates row height, padding, and compatible controls without reordering data, changing filters, clearing selection, or discarding edits.", "The control announces the selected density and scope before and after change.", "Persisting density is a distinct action when the scope is broader than the current surface.", "Reset restores only the density value for the named scope.", "Managed or inherited density values explain who owns them and where to request a change.", "Compact density keeps required labels, status, focus indicators, validation messages, and row actions available." ], "implementationChecklist": [ "Define density tokens for row height, header height, padding, gaps, icon placement, batch actions, expanded content, and touch targets.", "Decide supported scopes: current table, current product area, device, account, workspace, or organization policy.", "Keep density state separate from saved view state, filters, sort, column visibility, layout arrangement, zoom, and text-size settings.", "Preserve focus, scroll anchor, selected rows, expanded rows, drafts, and validation when density changes.", "Provide preview, save, reset, inherited, unavailable, and unsafe-compact states.", "Test keyboard use, screen readers, high zoom, touch, long labels, localized strings, open row details, row actions, validation messages, and virtualized rows in every density." ], "commonMisuses": [ "Treating density as a way to remove metadata, labels, helper text, or status instead of changing spacing.", "Making compact mode the only way to use the product efficiently.", "Saving personal density as a team or organization setting without consent.", "Coupling density to saved filters, columns, theme, layout arrangement, or zoom.", "Shrinking hit targets, focus outlines, or row actions below usable sizes.", "Resetting table state or losing edits when density changes.", "Offering compact density on mobile while forcing horizontal scrolling and hidden row identity." ], "critiqueQuestions": [ "What exactly changes when density changes: row height, padding, gaps, controls, or content?", "What stays invariant: data, filters, sort, selection, focus, edits, row identity, and open details?", "Is this density preference temporary, personal, device-specific, workspace-scoped, or managed by policy?", "Can users preview, save, reset, and recover the density choice without affecting saved views or filters?", "Do compact and spacious modes still meet keyboard, touch, zoom, localization, and screen-reader needs?", "Should the narrow-screen experience use a different layout instead of exposing desktop compact density?" ], "relatedPatterns": [ "settings-management", "data-grid", "saved-view", "table", "list-view", "card-list", "dashboard-layout", "custom-dashboard" ], "comparisons": [ "user-controlled-density-vs-settings-management-vs-data-grid-vs-saved-view" ], "sourceIds": [ "material-design-density", "mui-data-grid-density", "carbon-data-table-component", "cloudscape-content-density" ] }, { "id": "user-controlled-layout", "completionStatus": "complete", "name": "User-controlled layout", "category": "Personalization And Preference", "patternType": "ui-ux", "surfaceType": "User-selectable arrangement of panes, regions, or workspace modes around one active task", "maturity": "emerging", "platforms": [ "web", "desktop", "mobile" ], "problem": "Complex work surfaces often contain lists, details, activity streams, inspectors, previews, and editors, but one fixed arrangement forces every user, device, and task phase into the same layout and can hide state when panes move or collapse.", "solution": "Provide explicit user-controlled layouts that rearrange or reveal panes without changing data scope, preserve active task state, explain persistence and responsive fallbacks, and give users preview, save, reset, and recovery paths.", "uiGuidance": [ "Render layout control as an in-context segmented control, menu, or layout picker with named arrangements such as Split, Focus, Stacked, Inspector, or Reading, plus scope, preview, save, and reset indicators.", "Show affected regions with stable labels, order, visibility, and return paths so users can tell which pane moved, which pane is hidden, and how to restore the prior arrangement without losing work." ], "uxGuidance": [ "Use user-controlled layout when the same task can be done more effectively with different pane arrangements, such as comparing list and detail, focusing on one record, placing an inspector beside content, or stacking regions on narrow screens.", "Preserve task state across layout changes: selected item, active filters, open panels, draft edits, validation state, scroll anchor, focus target, and unsaved-change warnings must survive pane reordering or hiding." ], "uiExamples": { "good": [ "A review workspace lets users switch between Split, Focus, and Stacked layouts, labels the current scope as This workspace, and keeps the selected case and draft visible after each switch.", "A record editor offers a right-inspector layout and a below-content layout with preview thumbnails, reset to default, and an explanation when mobile forces stacked order." ], "bad": [ "A layout icon toggles panes with no names, no reset path, and no visible cue that the notes pane is hidden.", "A focus layout removes the activity pane from the DOM and loses the user's unsaved comment draft." ] }, "uxExamples": { "good": [ "A support agent opens a case in Split layout, switches to Focus to write a long response, returns to Split, and the same case, filters, scroll position, and draft reply remain intact.", "A tablet user chooses Stacked layout, moves between Queue, Case, and Activity regions with labelled controls, and can reset the layout without resetting queue filters." ], "bad": [ "A user saves a personal inspector layout and later discovers it changed the team's default workspace arrangement.", "A responsive breakpoint hides the secondary pane off screen, so keyboard users cannot reach the validation errors inside it." ] }, "problemContext": [ "The interface has multiple regions that support one task, such as a queue, selected record, notes, preview, activity, metadata, or action panel.", "Users alternate between comparing regions side by side, focusing on one region, reading long content, editing details, or using a narrow screen.", "Layout choice may be temporary, personal, device-specific, workspace-specific, inherited from an organization policy, or unavailable on small screens.", "Pane arrangement affects focus order, screen-reader order, keyboard shortcuts, scroll anchoring, unsaved changes, validation visibility, and responsive navigation.", "The product may also offer splitters, saved views, dashboards, density settings, themes, and preferences that must remain separate from layout arrangement." ], "selectionRules": [ "Choose user-controlled layout when users choose the arrangement, visibility, or order of workspace regions around the same task object.", "Use window splitter when users only resize adjacent panes with a separator and the broader region arrangement does not change.", "Use custom dashboard when users compose dashboard widgets, add or remove tiles, and persist a dashboard canvas.", "Use dashboard layout when the product defines a fixed monitoring page with widget hierarchy, filters, and drill paths.", "Use saved view when users persist columns, filters, sort, grouping, density, or display mode for one data surface.", "Use user-controlled density when spacing or row height changes but region arrangement stays the same.", "Offer named layouts only when each arrangement has a real task benefit and can preserve selection, focus, drafts, validation, and scroll position.", "Show whether the layout change is temporary, this workspace only, device-specific, account-wide, workspace-wide, or organization-managed.", "Provide reset to default and avoid resetting filters, density, theme, columns, dashboard widgets, or saved views when only layout is reset.", "On mobile or high zoom, translate side-by-side layouts into explicit stacked or focus navigation rather than forcing horizontal scroll." ], "requiredStates": [ "Default layout state with current layout name, scope, affected regions, and reset availability.", "Split or side-by-side layout state showing primary and secondary regions together.", "Focus layout state that hides secondary regions while preserving their state and return controls.", "Stacked or mobile layout state with labelled navigation between regions.", "Inspector-left, inspector-right, or below-content arrangement state when pane position changes.", "Preview-before-save, saved personal layout, workspace-managed layout, and reset-to-default states.", "Unavailable layout state when screen width, policy, permission, or content length makes an arrangement unsafe.", "State-preservation proof for selected item, filters, draft edit, validation, scroll anchor, and focus target." ], "interactionContract": [ "Changing layout rearranges regions but does not change the active record, dataset, filters, columns, sort, density, theme, or saved view unless the user explicitly chooses those changes.", "The current layout and scope are visible before and after change, and a status region announces the new arrangement.", "Hidden panes remain recoverable and keep their draft, scroll, validation, loading, and permission state.", "Saving layout is a distinct action when persistence goes beyond the current session or current workspace.", "Reset restores only the named layout scope and leaves data filters, density, saved view, and dashboard composition untouched.", "Keyboard order and screen-reader order follow the visible arrangement or provide clear region navigation when stacked.", "Responsive fallback maps each desktop layout to a usable mobile or high-zoom state with no off-screen essential pane." ], "implementationChecklist": [ "Define a layout model with layout ID, region order, region visibility, pane position, scope, persistence, responsive fallback, saved timestamp, and policy owner.", "Keep layout state separate from filters, sort, columns, density, splitter sizes, theme, zoom, dashboard widgets, and saved views.", "Provide named controls for switch layout, preview, save, reset, return to hidden pane, and explain managed or unavailable arrangements.", "Preserve selected item, focused control, draft edits, validation messages, scroll anchor, open panels, loading state, and permission state across layout changes.", "Align DOM order, keyboard order, visible order, and mobile navigation for every supported arrangement.", "Test narrow widths, zoom, long localized pane titles, active form edits, validation errors in hidden panes, keyboard shortcuts, screen readers, and browser back behavior." ], "commonMisuses": [ "Treating layout as a cosmetic preference while losing task state when panes hide or move.", "Combining layout with filters, density, columns, theme, or saved view settings so users cannot reset one without the others.", "Saving a personal layout as a workspace default without scope warning or permission checks.", "Using a side-by-side desktop layout on mobile and creating horizontal scroll or unreachable panes.", "Offering vague icons for layout modes with no labels, preview, current state, or recovery.", "Calling a single resizable splitter a full user-controlled layout when no arrangement or visibility choice exists." ], "critiqueQuestions": [ "Which regions can move, hide, stack, or switch sides, and which task state must survive every change?", "Can users distinguish layout from density, saved view, dashboard customization, and splitter resizing?", "Is the selected layout temporary, personal, device-specific, workspace-wide, inherited, or policy-managed?", "What happens to drafts, validation, scroll, focus, and hidden pane content when the layout changes?", "Does the mobile or high-zoom fallback preserve region order and task completion without horizontal scrolling?", "Can users preview, save, reset, and recover a layout without changing data filters or shared defaults by accident?" ], "relatedPatterns": [ "custom-dashboard", "dashboard-layout", "saved-view", "window-splitter", "user-controlled-density", "settings-management", "master-detail", "details-panel" ], "comparisons": [ "user-controlled-layout-vs-custom-dashboard-vs-dashboard-layout-vs-saved-view-vs-window-splitter" ], "sourceIds": [ "wai-aria-apg-window-splitter", "salt-splitter-accessibility", "servicenow-resizable-panes", "tableau-dashboard-size-layout", "microsoft-windows-app-settings-guidelines" ] }, { "id": "utility-navigation", "completionStatus": "complete", "name": "Utility navigation", "category": "Navigation And Wayfinding", "patternType": "ui-ux", "surfaceType": "Persistent utility controls separated from destination navigation", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Users need persistent access to support, search, session, account, notification, language, and cross-product tools, but those tools are often mixed with primary destinations and make the current navigation state ambiguous.", "solution": "Provide a separate utility navigation group or utility header layer that exposes non-destination tools, opens scoped panels or menus where needed, preserves the current content destination, and communicates utility state such as unread counts or signed-in status.", "uiGuidance": [ "Render utility controls such as search, help, notifications, profile, account settings, language, product switcher, and sign out as a visually distinct utility group rather than as peer primary destinations.", "Use clear labels, accessible names, badges, panel anchors, and responsive overflow so users can identify utility scope without confusing it with the current product, service, or page section." ], "uxGuidance": [ "Use utility navigation to keep session, support, discovery, account, and cross-product tools reachable from many pages without changing the user's current destination or local work state.", "When a utility opens a panel or menu, make the transient state reversible, keyboard reachable, dismissible, and synchronized with badges or session feedback." ], "uiExamples": { "good": [ "A product header shows Dashboard, Projects, and Reports as primary links, while Search, Help, Notifications, Account, and Sign out sit in a separate utility group.", "The notifications utility shows an unread count badge and opens a panel anchored to the icon instead of highlighting Notifications as a primary destination.", "On mobile, utility controls collapse into a labelled Utilities button whose menu keeps Search, Help, Notifications, Account, and Sign out separate from service links." ], "bad": [ "A nav row lists Home, Cases, Help, Sign out, Alerts, Profile, Reports, and Billing as equal section links.", "A bell icon has no label, no unread state text, and no panel or destination when activated.", "The mobile menu puts sign out between service links and page anchors with no account or session grouping." ] }, "uxExamples": { "good": [ "A user opens Notifications, reviews three unread items, the badge clears, and the current Projects section remains selected.", "A user opens Account, chooses Manage sign-in details or Sign out, and receives a clear session outcome without losing unsaved page work unexpectedly.", "A keyboard user opens Help, presses Escape, and focus returns to the Help utility trigger without moving the current page." ], "bad": [ "Clicking Help changes the current nav highlight to Help while the main content remains Projects.", "A sign-out link is hidden in an unlabeled overflow and immediately ends the session without confirming or explaining the account boundary.", "Inspecting notifications leaves the unread badge unchanged, so users cannot tell whether the utility action succeeded." ] }, "problemContext": [ "A product or service has recurring support, account, session, search, language, notification, or switcher controls needed from many pages.", "Primary navigation already represents destinations such as Dashboard, Projects, Reports, or service sections.", "Some utilities open transient panels while others navigate to account or support areas, so scope and state must be explicit." ], "selectionRules": [ "Choose utility navigation for controls whose primary job is session management, account access, support, search entry, notifications, language, product switching, or global tools.", "Keep utility controls out of primary or service navigation unless the label and placement make their different scope obvious.", "Right-align, group, or layer utilities separately from destination links, and give the group a distinct navigation or toolbar label.", "Use badges only for meaningful utility state such as unread notifications, pending approvals, or account attention, and update the badge after inspection.", "Open utility panels from buttons with expanded state when the user needs a quick view; use normal links only when the utility truly goes to a full utility page.", "Preserve the active primary or service destination while utilities open, close, or update.", "For destructive session utilities such as sign out, explain the boundary and confirm or provide a clear final session state.", "On small screens, collapse utilities into a labelled utility overflow or account menu without merging them into service destinations or page anchors." ], "requiredStates": [ "Default state with destination navigation and a separated utility group.", "Utility panel open state for notifications, account, help, search, or switcher controls.", "Badge state before and after inspecting notifications or pending account items.", "Signed-in and signed-out or sign-out-confirmed states.", "Keyboard dismissal state where Escape closes an open utility panel and returns focus to the trigger.", "Mobile utility overflow state that preserves utility labels and grouping.", "Current destination preserved state while a utility is open." ], "interactionContract": [ "Activating a utility button opens the corresponding panel, menu, tray, or inline search surface without changing the current primary destination.", "Only one transient utility panel is open at a time unless the shell explicitly supports pinned utilities.", "The utility trigger exposes expanded state while its panel is open and returns focus on Escape or close.", "Notification, message, and attention badges update when the utility has been inspected or resolved.", "Sign out, account switching, and permission-changing utilities clearly communicate scope and prevent accidental loss of unsaved work.", "Utility links that navigate to full pages do not masquerade as current product or service sections.", "Mobile utility overflow exposes the same utility set or an intentionally reduced, documented signed-out utility set." ], "implementationChecklist": [ "Inventory every header item and classify it as primary destination, service destination, current-view action, local page link, or utility before placing it.", "Give the utility group an accessible label such as Utilities, Account tools, or GOV.UK-wide tools.", "Choose button semantics for utilities that open panels and link semantics for utilities that navigate.", "Implement expanded state, Escape dismissal, outside-click close, and focus return for utility panels.", "Keep badges synchronized with underlying notification or account state.", "Handle sign-out, account switching, and language changes with explicit state preservation, warning, or final confirmation.", "Test desktop and mobile layouts to make sure utilities remain distinct from global, service, and page-level navigation." ], "commonMisuses": [ "Treating help, search, profile, notifications, and sign out as primary navigation destinations.", "Using unlabeled utility icons whose purpose is not obvious.", "Leaving utility panels open across route changes or focus changes with no dismissal path.", "Showing stale unread counts after users inspect notifications.", "Hiding sign out so deeply that users cannot end the session confidently.", "Letting mobile menus merge account utilities, service navigation, breadcrumbs, and page anchors into one undifferentiated list.", "Using utility navigation for rare destructive commands that belong in a settings or confirmation flow." ], "critiqueQuestions": [ "Which header items are destinations, and which are utilities?", "Can users tell whether activating this control will change section, open a panel, search, or affect the session?", "Does opening a utility preserve the current page, form draft, filter, and selected section?", "How do badges, account state, or signed-out state change after the utility is used?", "On mobile, are utilities still grouped and labelled separately from service or primary links?" ], "relatedPatterns": [ "global-navigation", "service-navigation", "header", "basic-search", "command-palette" ], "comparisons": [ "utility-navigation-vs-global-navigation-vs-service-navigation" ], "sourceIds": [ "carbon-global-header", "govuk-one-login-service-header", "govuk-navigate-service", "uswds-header-component" ] }, { "id": "validation-that-clears-user-input", "completionStatus": "complete", "name": "Validation that clears user input", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Anti-pattern where validation or failed submission destroys recoverable user-entered values", "maturity": "anti-pattern", "platforms": [ "web", "mobile", "desktop" ], "problem": "Validation is supposed to help users correct data, but clearing input after errors turns a small correction into rework, loses context, and can make users abandon or mistrust the form.", "solution": "Preserve all safe user-entered values through validation, server rejection, retry, and recovery; show precise field-level errors and summaries, keep raw and formatted values distinguishable, and clear only narrow sensitive values with explicit reason and recovery guidance.", "uiGuidance": [ "Do not clear, replace, mask into emptiness, or reset user-entered values just because validation failed, the server rejected the payload, or a retry is needed.", "Keep the failing value visible and editable beside a precise field error, and preserve valid sibling fields, uploaded file names, selected options, text area drafts, and formatted/raw values unless policy explicitly requires clearing a sensitive secret." ], "uxGuidance": [ "Users should be able to fix the smallest wrong part of their answer without retyping unrelated work.", "Treat value preservation as part of validation: every client rule, server rule, formatter, retry, reload, session return, and masked input path must either preserve the value or explain a narrow, policy-backed exception." ], "uiExamples": { "good": [ "A failed email validation keeps maya@@example visible, shows Enter an email address in the correct format, and leaves the phone and message fields intact.", "A server-side address error returns users to the form with all safe fields restored, the exact failed field focused, and the original apartment line still visible." ], "bad": [ "A checkout form fails cardholder-name validation and reloads with every shipping field blank.", "A textarea exceeds the character limit and the product replaces the draft with an empty field and a generic Invalid message." ] }, "uxExamples": { "good": [ "A user corrects one mistyped character in a preserved phone number after validation instead of re-entering the full number.", "A user retries a failed save and sees the same local value sent again, with a copy fallback before any destructive reset." ], "bad": [ "A user uploads evidence, enters long notes, hits Submit, and loses the notes because one date was invalid.", "A user pastes an account number with spaces and validation clears the input instead of explaining the acceptable format or preserving the raw value." ] }, "problemContext": [ "A form, editor, checkout, upload, import, authentication, or configuration screen validates user-entered values on blur, submit, save, retry, or server response.", "Validation can fail locally, through server-side rules, from normalization or masking, after session expiry, during autosave, or after a network error.", "The user may have entered multiple related fields, long text, uploads, selected options, pasted values, or formatted values that are expensive to recreate.", "Some sensitive values such as passwords, card verification codes, or one-time codes may need special clearing rules, but that exception must not be generalized to ordinary fields." ], "selectionRules": [ "Flag this anti-pattern when validation failure, failed submit, server rejection, formatting, retry, reload, or route return clears safe user-entered values.", "Use inline validation when one field can be corrected locally while its failing value remains visible and editable.", "Use error summary when failed submit produces one or more errors and users need linked recovery without losing values.", "Use single-page form when several related fields are submitted together and all entered values must survive validation.", "Use autosave recovery when a background save failed or became uncertain and the latest local value needs explicit recovery.", "Use error state when a save/load/sync failure blocks progress but the primary task is system failure recovery rather than field correction.", "Preserve invalid values unless they are unsafe to redisplay, impossible to store, or policy requires clearing a specific sensitive secret.", "If a value must be cleared for security, say which value was cleared, why, and how to re-enter only that value.", "Do not normalize by deleting user input silently; show the interpreted value, preserve the raw value when useful, or ask for confirmation.", "Do not clear valid sibling fields, hidden active fields, file selections, filters, or long text because a different field failed validation." ], "requiredStates": [ "Initial typed state with values entered across multiple fields.", "Field-level invalid state with the failing value preserved and editable.", "Submit failed state with error summary, matching field messages, and all safe values preserved.", "Server validation returned state with the submitted payload safely rehydrated into the form.", "Network or retry state where the same local value remains visible until retry succeeds or is explicitly discarded.", "Formatter or mask rejected state where raw input is preserved with correction guidance.", "Long text over-limit state where the draft remains and excess is identified rather than removed.", "File or upload validation state where acceptable uploaded files and filenames remain while failed files are explained.", "Session expired return state where safe local values are restored after reauthentication.", "Sensitive exception state where a password, CVV, or one-time code is cleared with explicit reason while non-sensitive fields remain.", "Bad full-reset state where all fields are blank after one validation error.", "Bad field-wipe state where the invalid field is emptied and users must retype from memory.", "Bad sibling-loss state where unrelated valid fields are cleared.", "Bad formatter-loss state where formatting destroys the raw value.", "Bad upload-loss state where every selected file disappears after one file fails." ], "interactionContract": [ "Validation messages name the problem and leave the user's value in place for editing.", "Submit-time recovery keeps all safe field values, selected options, file names, expanded sections, and scroll context available.", "Server validation responses rehydrate the submitted values before moving focus to the error summary or first invalid field.", "Retry sends the latest preserved local value, not a blank default or stale server value.", "Formatters and masks do not erase raw input; they either preserve it, show the interpreted value, or ask for correction.", "Security-sensitive clearing is scoped to the sensitive field and explained without clearing unrelated values.", "Reset, Clear, Cancel, and Start over are separate deliberate actions and are not triggered by validation." ], "implementationChecklist": [ "Keep form state separate from validation state so adding an error cannot reset field values.", "On failed submit, render the previous submitted values back into every safe control before showing errors.", "Return server validation errors with field keys and the submitted values or preserve the client-side payload until response handling completes.", "Preserve raw and formatted values separately for masks, currency, dates, phone numbers, addresses, and IDs.", "Protect long text and uploads with local draft or temporary object state while validation runs.", "Handle network failure, retry, session expiry, route reload, browser Back, and reauthentication without falling back to blank defaults.", "Define explicit exceptions for passwords, card verification codes, one-time codes, and prohibited file contents; clear only those values and explain the reason.", "Test failed client validation, failed server validation, slow network, reload, reauth, mobile keyboard, pasted input, autofill, uploads, long textarea text, and screen reader recovery." ], "commonMisuses": [ "Calling form reset after submit regardless of success or failure.", "Replacing the user's raw value with an empty string when parsing fails.", "Re-rendering the form from default values after a server validation response.", "Clearing every field because one field was invalid.", "Clearing uploaded files without preserving valid file names or explaining the failed file.", "Using password-clearing rules as an excuse to clear ordinary text fields.", "Showing only a toast after data loss instead of restoring the user's work.", "Combining Reset and Submit controls so users accidentally erase work while fixing validation." ], "critiqueQuestions": [ "Which values survive client validation, server validation, retry, reload, and session return?", "Can the user edit the failing value directly, or must they retype it?", "Are valid sibling fields preserved when one field fails?", "Does formatting preserve raw input or explain how it was interpreted?", "What sensitive fields are deliberately cleared, and is the reason visible?", "Can long text, uploads, and selected options be recovered after an error?", "Does the error summary link to fields without rebuilding the form from defaults?" ], "relatedPatterns": [ "inline-validation", "error-summary", "single-page-form", "autosave-recovery", "error-state", "text-input", "textarea", "input-mask", "password-input" ], "comparisons": [ "validation-that-clears-user-input-vs-inline-validation-vs-error-summary-vs-single-page-form-vs-autosave-recovery-vs-error-state" ], "sourceIds": [ "govuk-error-message-component", "govuk-error-summary-component", "uswds-form-templates", "govuk-text-input-component", "govuk-textarea-component", "govuk-password-input-component" ] }, { "id": "version-history", "completionStatus": "complete", "name": "Version history", "category": "Error Prevention And Recovery", "patternType": "ui-ux", "surfaceType": "Durable snapshot browser for previous document, file, page, object, or configuration versions", "maturity": "established", "platforms": [ "web", "desktop", "mobile" ], "problem": "Collaborative editing, autosave, and configuration changes create many saved states, but users cannot safely recover or reason about prior content when previous versions, current version context, compare behavior, restore consequences, permissions, comments, and retention limits are hidden.", "solution": "Provide a version history surface that exposes current and previous versions, durable snapshot metadata, named and autosaved versions, preview or diff comparison, restore confirmation, permission and retention states, and clear boundaries from logs, timelines, undo, drafts, publishing, and comments.", "uiGuidance": [ "Render version history as a durable snapshot browser with the current version, previous version list, author, timestamp, named version labels, autosaved version labels, changed summary, retention status, compare affordance, preview, and restore action.", "Separate version history from activity log, timeline, undo, draft state, publish workflow, comments, and permission-denied state by showing that users are inspecting saved content states, not only events, milestones, recent action recovery, discussion, or access failure." ], "uxGuidance": [ "Use version history when users need to find a known good state, understand what changed between saved states, recover from bad edits, cite a prior version, name a meaningful milestone, or restore content without guessing.", "Make recovery consequences explicit: what becomes current after restore, what happens to current edits or drafts, whether a restored version creates a new version, which comments or metadata carry forward, and which older versions are hidden by retention or permissions." ], "uiExamples": { "good": [ "A document side panel marks v42 as Current, lists v41, v38 named Pre-launch copy, and v35 autosaved, and opens a compare preview before Restore this version.", "A page history table shows version number, author, timestamp, change summary, named version label, compare action, restore action, and a retention message for older entries." ], "bad": [ "A History panel lists Edited, Edited, Edited with no version number, author, content preview, compare result, or restore consequence.", "A Restore button immediately overwrites current edits from a previous version without saying whether the current version remains recoverable." ] }, "uxExamples": { "good": [ "A designer names the last approved file version, compares it against the current version, confirms restore, and sees that the restore created v43 while keeping v42 available.", "A read-only reviewer opens page history, sees the current version and previous version metadata, but restore controls explain that edit permission is required." ], "bad": [ "A user tries to recover yesterday's copy but only sees a chronological activity log with no previewable previous version.", "A team restores a version from before an active draft and accidentally discards current unsaved edits because the conflict was not surfaced." ] }, "problemContext": [ "Versions may be created by manual saves, autosave, publishing, imports, edits from multiple collaborators, merge operations, or restore actions.", "Users often seek a known good state after accidental edits, content regression, collaborator conflict, approval rollback, deleted section recovery, or configuration drift.", "Prior versions may include comments, author metadata, timestamps, branch or publish state, named milestones, deleted users, redacted content, permission limits, and retention cutoffs.", "Restoring an older version can affect current drafts, published content, collaborators, audit evidence, search indexing, external links, and downstream automations." ], "selectionRules": [ "Choose version history when the user needs durable previous version snapshots with preview, compare, restore, name, or citation behavior.", "Use activity log when the primary task is investigation of actor, action, object, timestamp, source, result, IP, retention, and export evidence rather than restoring content.", "Use timeline when the primary task is reading a human-friendly sequence of events or milestones without exact snapshot comparison.", "Use undo when the action is recent, reversible in place, and does not require a persistent browser of previous versions.", "Use draft state when the current unfinished or unpublished work needs preservation, not when the user is browsing historical snapshots.", "Use publish workflow when the user is moving a selected version to live, scheduled, unpublished, or retired state.", "Use comments when users discuss, annotate, request changes, or resolve review threads attached to content.", "Use permission-denied state when a user cannot open, compare, name, restore, or download a version because access is missing.", "Expose a current version marker before every restore path so users know what will change.", "Provide compare or preview before restore when content loss, published behavior, or collaborator state could change.", "Label named versions, autosaved versions, restored versions, deleted authors, retention-limited rows, and permission-limited rows distinctly.", "Treat restore as creating a new current version unless the backend truly rewrites history, and explain the model." ], "requiredStates": [ "Default state with current version, previous version list, author, timestamp, and change summary.", "Named version state with editable or visible label and reason.", "Autosaved version state with system-created timestamp and author context.", "Version compare or diff state between current version and selected previous version.", "Preview selected previous version state before restore.", "Restore confirmation state that names the selected version and explains what becomes current.", "Restored state that shows the new current version and preserves access to the version restored from.", "View-only or permission-denied state for users who can inspect but cannot restore or compare restricted details.", "Deleted, archived, redacted, or retention-limited previous version state.", "Conflict state when current edits, unsaved draft, or concurrent collaborator changes exist.", "Loading, failed-load, offline, no versions, and mobile condensed-list states." ], "interactionContract": [ "Opening version history identifies the current version and keeps it visible while browsing previous versions.", "Selecting a previous version updates the preview or compare panel without changing the current content.", "Compare uses the same two versions named in the UI and states whether it shows text, layout, metadata, comments, or only a summary.", "Restore requires a confirmation when current edits, publishing state, permissions, or irreversible downstream effects could change.", "A successful restore states whether a new version was created and links back to the version restored from.", "Naming or renaming a version updates only the version label unless the UI explicitly supports editing content.", "Permission-limited rows reveal only metadata and actions the user is allowed to see.", "Retention-limited and deleted-author states explain missing history without implying user error.", "Mobile layouts preserve current version, selected previous version, compare, restore, and permission status without hiding the consequence copy." ], "implementationChecklist": [ "Define the version record model: version ID or number, current flag, created timestamp, author, save source, named label, change summary, restore eligibility, retention class, permission scope, and comment or publish metadata.", "Separate version snapshots from activity events, timeline milestones, draft records, publish states, comment threads, and undo stacks in the backend and UI copy.", "Build a selected-version preview with clear current-versus-selected labels and a compare route for text, structure, metadata, file state, or configuration changes the product can honestly show.", "Implement restore confirmation, restored success state, permission-limited state, draft conflict handling, deleted-author handling, retention cutoff, failed-load retry, and mobile collapsed browsing.", "Preserve current version recoverability after restore when the backend supports append-only versioning, and state when it does not.", "Test long version names, many autosaves, same-minute edits, deleted authors, restricted viewers, comments attached to old versions, concurrent edits, offline retry, keyboard navigation, high zoom, and small screens.", "Log restore and rename actions as activity events without replacing the version history surface with the activity log." ], "commonMisuses": [ "Calling an activity log or audit trail version history when it has no previous content snapshots.", "Using a timeline of milestones as a substitute for previewable or restorable versions.", "Relying on undo for recovery after navigation, collaboration, autosave, or elapsed time.", "Hiding the current version while users inspect previous versions.", "Restoring without preview, compare, confirmation, or conflict handling.", "Mixing named versions, autosaves, restored versions, and deleted-author versions without labels.", "Leaking private diff or author details to users who only have read or limited access.", "Hiding retention limits until after users cannot find a previous version." ], "critiqueQuestions": [ "Can users identify the current version and selected previous version at every point before restore?", "Does the UI show what changed, who changed it, when it changed, and whether the version is named or autosaved?", "What exactly happens to current edits, drafts, comments, publish state, and downstream links after restore?", "Can permission-limited users understand why compare, restore, or metadata is unavailable?", "Are retention cutoffs, deleted authors, archived versions, and failed loads explicit?", "Would an activity log, timeline, undo, draft state, publish workflow, comments, or permission-denied state be the better pattern for this task?" ], "relatedPatterns": [ "activity-log", "timeline", "undo", "draft-state", "publish-workflow", "comments", "permission-denied-state", "compare-view", "review-before-submit", "confirmation-dialog" ], "comparisons": [ "version-history-vs-activity-log-vs-timeline-vs-undo" ], "sourceIds": [ "google-docs-version-history", "microsoft-office-previous-versions", "microsoft-sharepoint-version-history", "atlassian-confluence-page-history", "figma-version-history" ] }, { "id": "voice-command", "completionStatus": "complete", "name": "Voice command", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Spoken command interface that listens, recognizes, confirms, and executes bounded user intents", "maturity": "standard", "platforms": [ "web", "mobile", "desktop", "voice" ], "problem": "Voice commands can make products accessible and hands-free, but speech recognition is uncertain, socially constrained, permission-gated, language-dependent, and easy to confuse with dictation, so invisible listening or unconfirmed side effects can execute the wrong command or block users entirely.", "solution": "Design voice command as a visible, bounded command lifecycle with explicit invocation, permission handling, listening state, transcript review, command matching, confidence and alternatives, disambiguation, confirmation for risky actions, status feedback, cancellation, undo or retry, and equivalent non-voice paths.", "uiGuidance": [ "Render voice command as an explicit listening surface with microphone permission state, wake or push-to-talk trigger, listening indicator, timeout, recognized phrase, confidence, matched command, target object, alternatives, and cancel path.", "Show the exact spoken phrases users can say, keep visible labels aligned with accessible names, and separate dictation text from executable commands so people can speak what they see without triggering hidden side effects." ], "uxGuidance": [ "Use voice command when users benefit from hands-free spoken control, accessibility voice input, or quick command activation and the product can manage recognition uncertainty, privacy, confirmation, recovery, and fallback paths.", "Design the command lifecycle from permission request through listening, partial recognition, final transcript, disambiguation, confirmation, execution, feedback, undo, retry, and non-voice alternatives for noisy, private, unsupported, or denied states." ], "uiExamples": { "good": [ "A mobile reporting app shows Press and say a command, records the transcript 'send report', matches it to Send report, reads back Incident 482, and requires Confirm send before uploading.", "A dashboard voice overlay displays command chips such as Open alerts, Filter critical, and Read summary, shows confidence and alternatives, and offers Tap instead when the microphone is unavailable.", "A hands-free editor distinguishes Dictation mode from Command mode, so saying 'delete that' edits selected text only when the text field is active." ], "bad": [ "A microphone icon starts listening silently and executes the first matched word without a visible transcript.", "The visible button says Export data but the voice command requires 'download CSV', so speech-input users cannot speak the label they see.", "A global voice listener treats dictated prose as commands and navigates away from an unsaved form." ] }, "uxExamples": { "good": [ "A user says 'filter critical alerts', sees the recognized phrase and target list, corrects an alternative before execution, and can undo the applied filter.", "A user in a kitchen denies microphone permission and completes the same timer setup with large touch controls.", "A user says 'delete draft', hears and sees 'Delete draft Budget review?', then cancels before the destructive action runs." ], "bad": [ "A user says 'send it later' while dictating a note and the app immediately sends a message.", "A user with a speech difference gets repeated No match errors with no alternative phrase, tap path, or command list.", "A user in a noisy room cannot tell whether the app heard 'archive case' or 'open case' before it changes the record." ] }, "problemContext": [ "Users may be hands-busy, driving an assistive setup, using switch or speech recognition software, dictating text, controlling a smart device, or using a microphone because touch and keyboard input are difficult.", "The product may need to recognize fixed commands, visible control names, open-ended dictation, text-editing instructions, navigation requests, app actions, or physical-world device controls.", "Microphone permission, offline state, acoustic noise, privacy, accent, language, speech difference, latency, wake-word failure, and confidence thresholds affect whether the command can be recognized safely.", "Voice command surfaces often sit near text input, prompt boxes, command palettes, keyboard shortcuts, touch gestures, screen-reader commands, and platform voice access tools." ], "selectionRules": [ "Choose voice command when the interaction problem is spoken activation or control, not typed search, command browsing, key-chord acceleration, or ordinary dictation alone.", "Use text input when speech is only an optional input method for entering a value and no command execution, matching, or confirmation is owned by the product.", "Use prompt box when the spoken content becomes an AI request that users review and send as natural language rather than a bounded command with a known target.", "Use command palette when users need searchable command discovery, ranking, and selection before execution instead of remembering a spoken phrase.", "Use keyboard shortcut when expert users need a key chord accelerator with scope and conflict rules, not microphone permission and recognition feedback.", "Use touch gesture when movement, pressure, or pointer contact is the primary input; voice command can be an equivalent path but should not hide the gesture's visual affordance.", "Prefer visible command phrases that match visible labels and accessible names, then support aliases only as documented alternatives.", "Require read-back, confirmation, undo, or approval before executing destructive, paid, public, permission-changing, data-export, account, or physical-world actions.", "Provide tap, keyboard, switch, text, or command-palette alternatives for every required task because voice can fail or be inappropriate in many environments.", "Separate dictation mode from command mode so spoken prose does not unexpectedly trigger global commands." ], "requiredStates": [ "Voice unavailable or unsupported state with non-voice alternatives.", "Microphone permission not requested, denied, granted, and revoked states.", "Wake phrase, push-to-talk, or explicit start-listening state.", "Listening state with visible microphone activity, privacy boundary, and timeout.", "Partial transcript and final recognized phrase state.", "Low-confidence, no-match, and alternative command state.", "Disambiguation state when a phrase maps to multiple commands or targets.", "Command matched state with visible command name, target, scope, and consequence.", "Confirmation state for risky or irreversible commands.", "Cancel, stop listening, retry, edit transcript, and choose fallback states.", "Executed command state with status feedback, focus or context preservation, and undo when available.", "Dictation mode, text-editing command mode, and global command mode boundaries.", "Noisy environment, offline, unsupported language, and screen-reader or platform voice-access coexistence states." ], "interactionContract": [ "Voice capture starts only after explicit user invocation, platform voice-access command, or documented wake condition.", "The interface shows when it is listening, what it heard, which command it matched, and what target will be affected before any consequential execution.", "Visible labels, accessible names, and primary spoken command phrases stay aligned so users can speak what they see.", "Dictated text remains text unless the user is in command mode or speaks a documented text-editing command in a focused editing context.", "Low-confidence or ambiguous recognition never executes silently; it asks users to choose, retry, type, tap, or cancel.", "Microphone denial, unsupported browser, offline recognition, language mismatch, or timeout keeps the task available through another input path.", "Risky commands require confirmation that repeats the command and target; cancellation and undo use the same command semantics as visible controls.", "Recognition results, transcript snippets, and command logs respect privacy expectations and do not persist sensitive spoken content unless the user is told." ], "implementationChecklist": [ "Inventory commands by phrase, visible label, accessible name, aliases, target type, scope, risk level, confirmation rule, fallback control, and logging policy.", "Define voice states for permission, unsupported platform, start listening, partial transcript, final result, alternatives, no match, timeout, confirmation, execution, failure, retry, and stop listening.", "Keep voice command state separate from dictation text, AI prompt drafts, search queries, keyboard shortcut handlers, and platform voice access events.", "Expose a visible command list or help surface with exact phrases, examples, aliases, language support, microphone status, and fallback controls.", "Use confidence thresholds and command grammars or bounded command matching where available; route ambiguous or low-confidence results to disambiguation.", "Align visible labels and accessible names for controls that users may activate by speech recognition.", "Confirm or require undo for destructive, paid, public, permission-changing, physical-world, or multi-object actions.", "Test quiet, noisy, private, offline, permission-denied, unsupported-language, screen-reader, platform Voice Access or Voice Control, speech-difference, mobile, desktop, and keyboard fallback scenarios." ], "commonMisuses": [ "Listening without a visible active state or clear stop control.", "Executing commands from partial recognition or low-confidence results.", "Making voice the only route to a required workflow.", "Using hidden command phrases that do not match visible labels or accessible names.", "Mixing dictation and command mode so prose triggers app actions.", "Saving transcripts of sensitive speech without notice or retention controls.", "Treating a voice command like an AI prompt and letting open-ended language run deterministic side effects.", "Skipping confirmation for destructive or physical-world commands." ], "critiqueQuestions": [ "How does the user know the product is listening, what it heard, and which command it matched?", "What happens when microphone permission is denied, recognition is unsupported, the room is noisy, or the language is unavailable?", "Can users speak the visible label of a control, and does that label appear in the accessible name?", "Which phrases are commands, which are dictation, and which require disambiguation or confirmation?", "What prevents low-confidence or partial recognition from executing the wrong target?", "What non-voice path completes the same task, and is it visible before voice fails?", "What transcript or command history is stored, for how long, and can users avoid sensitive capture?" ], "relatedPatterns": [ "keyboard-shortcut", "command-palette", "prompt-box", "text-input", "touch-gesture", "focus-traversal" ], "comparisons": [ "voice-command-vs-keyboard-shortcut-vs-command-palette-vs-prompt-box-vs-text-input-vs-touch-gesture" ], "sourceIds": [ "wcag-label-in-name", "wai-speech-recognition-perspective", "web-speech-api", "microsoft-windows-voice-access", "microsoft-voice-access-command-list", "google-android-voice-access", "apple-voice-control" ] }, { "id": "warning-text", "completionStatus": "complete", "name": "Warning text", "category": "Feedback, Status, And System State", "patternType": "ui-ux", "surfaceType": "Severe-consequence warning copy before an action", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Users may continue through a form, declaration, or risky action without noticing a severe consequence, especially when the consequence is written as ordinary hint text, a vague severity label, or a message that appears only after the decision.", "solution": "Place concise warning text immediately before the related action or instruction, include warning wording and a non-color cue, state the specific consequence in plain language, and escalate only when the consequence requires a stronger interaction contract.", "uiGuidance": [ "Render warning text as a short high-emphasis statement with a warning icon, visible or hidden warning label, and explicit consequence copy placed before the relevant action, declaration, or instruction.", "Keep warning text compact and rare; if the message needs actions, live updates, field links, or long recovery detail, move it to alert, inline message, error summary, confirmation dialog, or a dedicated help surface." ], "uxGuidance": [ "Use warning text when users must understand a serious consequence before acting or failing to act, such as a fine, loss of access, permanent deletion, eligibility impact, or legal responsibility.", "Phrase the warning around the user's decision and consequence, not the system's severity label, so users can change course before the risky outcome happens." ], "uiExamples": { "good": [ "Before Submit declaration, a warning with an exclamation icon says the user may be fined if they provide false information.", "Before deleting an export archive, warning text says the files cannot be recovered after deletion and links to retention rules." ], "bad": [ "A red sentence says Important below the submit button after the user has already acted.", "A warning icon appears beside every hint on the page, making the real legal warning indistinguishable." ] }, "uxExamples": { "good": [ "Users see the fine or eligibility consequence before checking the declaration and can pause to verify their answer.", "An irreversible delete warning escalates to confirmation only when the user starts the destructive action." ], "bad": [ "A benefit-loss warning appears only after submission, so users cannot change the decision it warns about.", "A validation error is written as warning text with no link to the field that needs correction." ] }, "problemContext": [ "A user action or lack of action can cause a fine, legal obligation, eligibility change, permanent data loss, missed deadline, security exposure, or similar high consequence.", "The warning is known before the user acts and should shape the user's decision rather than report a system status after the fact.", "The message can be understood in one short statement without needing a recovery workflow, list of field links, live update, or modal answer.", "The interface already has a nearby action, declaration, checkbox, instruction, or task step that the warning qualifies." ], "selectionRules": [ "Choose warning text when one severe consequence needs to be noticed before the user acts or fails to act.", "Place the warning before the related button, declaration, checkbox, instruction, or risky form section, not after the action.", "Use explicit consequence wording such as may be fined, cannot be recovered, application will be cancelled, or access will be removed.", "Use an icon and warning label or fallback wording so the warning is not communicated by color alone.", "Use alert instead when a dynamic current-task condition appears and must be announced immediately.", "Use inline message instead when the warning belongs to one visible row, card, field group, or section condition that may resolve locally.", "Use error summary instead when the warning is really a submitted-form validation failure that needs links to invalid answers.", "Use confirmation dialog instead when policy or risk requires the user to explicitly choose before the high-consequence action proceeds." ], "requiredStates": [ "No-warning state where the action has no severe consequence.", "Before-action warning state placed immediately before the related control or declaration.", "Legal, financial, eligibility, deletion, or security consequence variant with specific consequence copy.", "Accessible icon state where warning meaning survives color loss and assistive technology output.", "Resolved or reduced-risk state where the warning disappears or downgrades when the consequence no longer applies.", "Escalated state where irreversible action moves from warning text into a confirmation dialog.", "Misuse state where validation, dynamic status, or broad service messaging is routed to a more appropriate pattern." ], "interactionContract": [ "The warning appears in the reading order before the action or answer it qualifies.", "The first word or accessible label identifies the content as a warning before the consequence sentence.", "The warning names the consequence and the condition that triggers it, not only a severity word.", "The warning does not steal focus, open a modal, or interrupt typing by itself.", "If the user changes the answer so the consequence no longer applies, the warning updates or is removed.", "If the user proceeds toward an irreversible action, the next step may be a confirmation dialog with the same consequence restated.", "The warning is not used as the only route to recover from errors after submit." ], "implementationChecklist": [ "Identify the exact action or omission that creates the severe consequence before choosing warning text.", "Write one sentence that names the user-facing consequence and triggering condition in plain language.", "Place the warning directly before the relevant control, declaration, checkbox, instruction, or task step.", "Include a warning icon and warning label or fallback text; do not rely on red or yellow styling alone.", "Limit the page to the warnings that genuinely change user risk; avoid decorating ordinary help or hints as warnings.", "Route dynamic status changes to alert or status semantics and submitted-form failures to error summary with field messages.", "Escalate irreversible or high-cost actions to confirmation when users must actively consent before proceeding.", "Test warning placement, zoom, screen-reader reading order, icon fallback wording, color-independent meaning, and resolved-state behavior." ], "commonMisuses": [ "Using warning text for routine hints, explanations, or mild reminders.", "Placing the warning after the action it is supposed to qualify.", "Writing only Warning or Important without a specific consequence.", "Using red or yellow text as the only warning signal.", "Replacing an error summary or field error with warning text after submit.", "Using warning text for live outage, session, or connection status that needs alert semantics.", "Showing so many warnings that users cannot tell which consequence matters." ], "critiqueQuestions": [ "What exact action or omission triggers the consequence?", "Can users see the warning before they reach the related action?", "Does the sentence say what happens to the user if they continue or fail to continue?", "Would the message be more honest as an alert, inline message, error summary, notification banner, or confirmation dialog?", "Is warning meaning available without color, and does assistive technology hear the warning label before the consequence?", "What event removes, downgrades, or escalates this warning?" ], "relatedPatterns": [ "alert", "inline-message", "error-summary", "confirmation-dialog", "notification-banner", "banner" ], "comparisons": [ "warning-text-vs-alert-vs-inline-message-vs-error-summary" ], "sourceIds": [ "govuk-warning-text-component", "uswds-alert-component", "govuk-error-summary-component", "w3c-wcag-use-of-color" ] }, { "id": "wearable-glance", "completionStatus": "complete", "name": "Wearable glance", "category": "Cross-Device And Physical Interaction", "patternType": "ui-ux", "surfaceType": "Few-second wearable status surface with safe handoff", "maturity": "standard", "platforms": [ "mobile" ], "problem": "Wearable surfaces are glanceable, personal, tiny, battery-sensitive, and often visible to others, so copying mobile pages, dashboards, notifications, or long controls onto a watch can create unreadable, stale, privacy-leaking, or unsafe experiences.", "solution": "Provide a wearable glance that answers one immediate question with minimal text and stable visual hierarchy, labels freshness and privacy, adapts to ambient and slot constraints, limits on-wrist action to safe next steps, and hands complex tasks to the paired app or phone.", "uiGuidance": [ "Render a wearable glance as one compact answer with a clear subject, current value, priority, freshness, privacy state, and tap destination that works in a tiny complication, Wear OS tile, widget, or wearable card.", "Design the always-on, wrist-down, low-power, and unavailable states explicitly so the glance remains legible, honest, and safe when the screen is dim, small, round, or briefly viewed." ], "uxGuidance": [ "Use wearable glance when users need to check a status, cue, or next step in seconds without entering a full app or phone workflow.", "Keep wearable interactions short: one glanceable answer, one safe action when necessary, and a clear handoff to phone or app for complex review, input, destructive choices, payments, or privacy-sensitive detail." ], "uiExamples": { "good": [ "A medication complication shows Next dose 8:30, due in 12 min, taken state, and opens the medication app for details.", "A transit tile shows Stop 4, train in 6 min, updated 1 min ago, and a phone handoff for route changes.", "A workout glance shows pace and heart-rate zone with dimmed ambient mode that keeps only the current zone and elapsed time." ], "bad": [ "A watch tile compresses five dashboard charts, filters, and drill links into tiny unreadable panels.", "A message glance exposes private sender and text even though notification previews are hidden.", "A complication shows yesterday's glucose value as current with no timestamp or stale state." ] }, "uxExamples": { "good": [ "A user raises their wrist, sees that boarding starts in 9 minutes at Gate B12, and taps to open the boarding pass only when needed.", "A user sees a stale delivery ETA, understands it was last updated 18 minutes ago, and opens the phone app to refresh.", "A user in focus mode sees only a private status dot on the watch face and can reveal detail from the app after authentication." ], "bad": [ "A user tries to act from a tiny complication and accidentally dismisses an important alert.", "A user makes a health decision from a stale metric because the glance omits freshness.", "A user cannot tell whether a wearable card is a notification, a live tile, a shortcut, or a frozen widget." ] }, "problemContext": [ "The surface is a smartwatch complication, tile, widget, band screen, wearable card, always-on display, ongoing activity, or quick wrist status.", "Users may be walking, exercising, commuting, working, driving, wearing gloves, in sunlight, in focus mode, under notification privacy, or viewing the watch for only a few seconds.", "Data may be live, cached, sensor-derived, privacy-sensitive, time-critical, battery-sensitive, app-provided, phone-dependent, or unavailable offline.", "Wearable glance sits near notification center, summary box, dashboard layout, progress bar, notification preferences, haptic feedback, and mobile handoff." ], "selectionRules": [ "Choose wearable glance when a wearable surface should answer one immediate question in a few seconds.", "Use notification center when users need a durable, filterable history of many notifications and read states.", "Use summary box when the summary belongs inside a page or workflow rather than on a wrist surface.", "Use dashboard layout when users need multiple coordinated widgets, filters, drill paths, and comparison across metrics.", "Use progress bar when duration, percent, stages, cancellation, or retry is the main information need.", "Use notification preferences when users configure wearable routing, quiet hours, privacy, or channel rules.", "Keep visible content to one primary metric, label, or next step plus minimal context such as unit, source, or time.", "Show freshness or last-updated state whenever the value can be stale, cached, delayed, sensor-derived, or phone-dependent.", "Treat private messages, health values, payment details, location, and account status as sensitive on wrist surfaces.", "Provide handoff to phone or app for details, forms, destructive decisions, payments, account changes, and long reading." ], "requiredStates": [ "Configured and unconfigured complication, tile, or widget state.", "Normal glance state with one primary answer and short label.", "Ambient, dimmed, always-on, or wrist-down state.", "Fresh, stale, cached, unavailable, offline, and phone-disconnected states.", "Privacy-hidden or redacted state for sensitive content.", "Low battery or power-saving state with reduced updates.", "High-priority alert or due-now state with safe cue.", "Upcoming, active, completed, missed, and expired states for time-based events.", "Tap handoff state to app, phone, detail, route, or action review.", "One safe on-wrist action state such as mark done, pause, dismiss, or start.", "Action blocked or requires phone/authentication state.", "Wrong-size, unsupported slot, long text, and overflow handling state.", "Loading, refresh failed, permission-limited, and data-source unavailable state.", "Focus mode, quiet hours, and notification privacy state.", "Haptic or notification cue present but not required state." ], "interactionContract": [ "A wearable glance answers one primary question before any tap, scroll, or phone handoff.", "The glance never depends on tiny hidden controls, long text, dense charts, or multi-step input to be understood.", "Freshness, source, privacy, and unavailable states remain visible enough for a few-second check.", "On-wrist actions are safe, reversible, or clearly confirmed; complex and risky tasks hand off to a larger surface.", "Ambient and dimmed modes reduce detail without changing the meaning of the displayed state.", "Notification privacy, quiet hours, focus mode, and battery constraints can suppress or redact details without breaking the glance." ], "implementationChecklist": [ "Define the one question the wearable surface answers, the update source, freshness rule, privacy level, tap destination, and allowed on-wrist actions.", "Design for the smallest supported slot first, including round screens, clipped corners, ambient mode, large text, and sunlight.", "Keep copy short, use stable units and icons, and test truncation for long names, times, values, and localized strings.", "Expose last updated, stale, cached, unavailable, phone disconnected, and permission-limited states when users could rely on the value.", "Respect notification privacy, focus mode, quiet hours, battery saver, reduced motion, haptics, and always-on display constraints.", "Provide phone/app handoff for details, authentication, forms, destructive actions, payments, and complex settings.", "Avoid frequent background updates unless freshness materially affects the user's decision.", "Test wrist raise, ambient mode, tiny slots, disconnected phone, stale data, privacy settings, one-handed use, screen reader, haptics off, and high-contrast mode." ], "commonMisuses": [ "Shrinking a mobile dashboard or full card list into a watch tile.", "Showing stale data without a timestamp or unavailable state.", "Exposing private messages, health values, or payment details on the wrist.", "Using a wearable glance as a notification inbox.", "Putting complex forms, filters, or destructive controls on a tiny surface.", "Ignoring ambient mode, battery, and always-on display constraints.", "Using tiny unlabeled icons as the only explanation." ], "critiqueQuestions": [ "What single question can users answer after a brief wrist glance?", "What is hidden, reduced, or redacted in ambient mode, focus mode, and notification privacy?", "How fresh is the displayed value, and what does the user see when it is stale or unavailable?", "What happens when users tap the glance, and does it hand off safely for complex work?", "Is any private, health, financial, location, or account information visible to bystanders?", "Is this really wearable glance, or does notification center, summary box, dashboard layout, progress bar, or notification preferences own the main problem?" ], "relatedPatterns": [ "notification-center", "summary-box", "dashboard-layout", "progress-bar", "notification-preferences", "haptic-feedback" ], "comparisons": [ "wearable-glance-vs-notification-center-vs-summary-box-vs-dashboard-layout-vs-progress-bar-vs-notification-preferences" ], "sourceIds": [ "apple-hig-designing-for-watchos", "apple-hig-complications", "apple-watch-smart-stack-widgets", "android-wear-tiles", "android-wear-complications", "android-wear-complications-design", "android-wear-user-interfaces" ] }, { "id": "window-splitter", "completionStatus": "complete", "name": "Window splitter", "category": "Data Display And Exploration", "patternType": "ui-ux", "surfaceType": "Moveable separator for resizing adjacent panes", "maturity": "standard", "platforms": [ "web", "desktop", "mobile" ], "problem": "Complex workspaces often place related panes side by side, but fixed pane sizes waste space for some tasks while unlabeled or pointer-only splitters make resizing inaccessible, unpredictable, and state-destructive.", "solution": "Provide a named moveable separator with defined pane ownership, min and max limits, pointer and keyboard resizing, collapse and restore behavior, status feedback, and responsive fallbacks that preserve pane state.", "uiGuidance": [ "Render a window splitter as a visible, focusable moveable separator between adjacent panes with a clear resize affordance, accessible name, orientation, current value, minimum and maximum pane limits, and preserved pane headings.", "Keep both panes readable and task-relevant while resizing; expose collapse, restore, min/max boundary, and responsive alternatives instead of letting panes disappear or become unusable." ], "uxGuidance": [ "Use a window splitter when users need to tune workspace layout, compare content, inspect detail beside a source, or balance editing and preview space without leaving the current task.", "Make resizing predictable across pointer, keyboard, touch, zoom, and small screens so users can change pane ratios without losing selection, scroll position, focus, or data entry state." ], "uiExamples": { "good": [ "A mail workspace has a message list and reading pane separated by a labelled vertical splitter showing 42 percent list width, with arrow-key resizing and restore from collapse.", "An editor preview has Code and Preview panes with a visible splitter, min widths, keyboard step controls, and a status message when the preview reaches its minimum size." ], "bad": [ "A thin visual line between a table and details pane appears draggable but cannot be focused, named, or moved by keyboard.", "Dragging a splitter can shrink the left pane to 12 pixels and hide the selected row with no restore control." ] }, "uxExamples": { "good": [ "A keyboard user focuses the separator, presses Right Arrow to widen the preview by 5 percent, presses Home to return to the minimum source pane, and focus remains on the splitter.", "A user collapses the activity pane to read a form, restores it, and the form field, selection, and activity scroll position are preserved." ], "bad": [ "A user drags the divider and the selected record disappears because the source pane collapses below its minimum usable width.", "A screen reader user hears Separator with no value or pane names and cannot tell which side will resize." ] }, "problemContext": [ "Two or more adjacent panes must remain visible in one workspace, such as list and reading pane, editor and preview, navigation and content, form and activity, or table and inspector.", "Users have legitimate reasons to allocate more space to one pane at different moments.", "Pane contents have state such as selected rows, scroll positions, text entry, zoom, filters, or preview focus that must survive resizing.", "The product can define minimum usable sizes, collapse behavior, keyboard steps, and narrow-screen alternatives." ], "selectionRules": [ "Choose window splitter when adjacent panes are both part of the same durable workspace and users need control over their relative sizes.", "Use a fixed details panel when the panel's job is selected-object inspection and user-controlled pane ratios are unnecessary.", "Use a drawer when the surface is temporary, edge-aligned, and should close after supplemental detail or light action.", "Use side navigation when the side region contains destination hierarchy rather than resizable content.", "Use tabs, accordion, or full-page routes when the viewport cannot support readable side-by-side panes.", "Do not use a splitter for a purely decorative divider.", "Do not use a splitter when one pane can be safely hidden without restore, orientation, value, or state preservation.", "Do not allow either pane to resize below its minimum useful content width or height.", "Define whether collapse happens by Enter, double-click, a button, or a dedicated command, and provide restore behavior.", "When multiple splitters exist, label each one by the panes it separates." ], "requiredStates": [ "Default split state with two labelled panes and a visible splitter position.", "Keyboard-focused splitter state with accessible name, orientation, value, min, and max.", "Pointer drag or step resize state with live pane size update.", "Arrow-key resize state with predictable increments.", "Home and End or min and max boundary state.", "Collapsed pane state with a clear restore affordance.", "Restored pane state preserving selection, scroll, and input state.", "Minimum and maximum boundary feedback state.", "Responsive narrow-screen state with stacking, route, or collapsed pane alternative.", "Multiple splitter state where each separator has a distinct name and target panes." ], "interactionContract": [ "The splitter separates two named panes and communicates which pane size its value represents.", "Pointer dragging changes pane size within defined min and max limits and does not select text or lose pane state.", "Keyboard focus can land on the splitter when it is moveable.", "Arrow keys resize the panes by an intentional step; larger modified steps may be supported.", "Home and End move to minimum or maximum where those shortcuts are implemented.", "Enter toggles collapse or restore only when the design explicitly supports that behavior.", "The splitter updates aria-valuenow or equivalent value text as the pane size changes.", "Resize, collapse, restore, and responsive changes preserve active selection, scroll, input, and focus unless the user explicitly navigates away.", "When a pane reaches a boundary, the interface communicates the limit without moving focus away from the splitter." ], "implementationChecklist": [ "Name both panes and define which pane the splitter value measures.", "Choose vertical or horizontal orientation and provide matching visual affordance.", "Set initial size, minimum size, maximum size, step size, and collapse threshold.", "Use role separator with aria-valuenow, aria-valuemin, aria-valuemax, orientation, and an accessible name when implementing an ARIA splitter.", "Implement pointer drag, keyboard arrow steps, boundary feedback, collapse, restore, and responsive fallback deliberately.", "Preserve pane state including selected item, scroll position, text entry, preview zoom, and focus after resize.", "Avoid hidden tiny panes by enforcing minimum useful sizes and exposing restore.", "Test keyboard, pointer, touch, screen reader output, zoom, high contrast, localization, nested scroll panes, and narrow breakpoints." ], "commonMisuses": [ "Using a static separator line and calling it a splitter.", "Making resizing pointer-only with no keyboard or assistive-technology value.", "Letting panes collapse to unusable slivers without restore.", "Using a splitter when a drawer, details panel, or responsive layout would better match the task.", "Forgetting min and max limits, causing text clipping and broken controls.", "Resetting form input, selection, or scroll position after resize.", "Adding several unlabeled splitters to one workspace.", "Treating the splitter as the pane content pattern instead of separately designing the table, preview, editor, or navigation pane." ], "critiqueQuestions": [ "Which two panes does the splitter separate, and why must both stay visible?", "Which pane does the current value measure, and what are its minimum and maximum useful sizes?", "Can pointer, keyboard, and assistive-technology users resize, collapse, and restore the panes?", "What happens to selection, scroll, focus, and input while resizing?", "What is the narrow-screen alternative when panes cannot remain side by side?", "Would a fixed details panel, drawer, side navigation, tabs, or full-page route be clearer?" ], "relatedPatterns": [ "details-panel", "drawer", "preview-panel", "side-navigation", "navigation-drawer", "tabs", "accordion", "toolbar" ], "comparisons": [ "window-splitter-vs-details-panel-vs-drawer-vs-side-navigation" ], "sourceIds": [ "wai-aria-apg-window-splitter", "mdn-aria-separator-role", "salt-splitter-accessibility", "servicenow-resizable-panes", "fluent-blazor-multisplitter" ] }, { "id": "wizard", "completionStatus": "complete", "name": "Wizard", "category": "Input And Data Entry", "patternType": "ui-ux", "surfaceType": "Guided sequential setup assistant", "maturity": "standard", "platforms": [ "web", "mobile", "desktop" ], "problem": "Complex setup tasks become risky when users must know the dependency order, test requirements, generated outputs, and final consequences without a guided assistant that keeps each step honest.", "solution": "Guide users through a bounded wizard with explicit step state, prerequisite validation, step-specific actions, generated preview or test feedback, review before finish, safe cancellation, and recomputation of dependent steps after earlier choices change.", "uiGuidance": [ "Render a bounded assistant shell with a clear wizard title, current step heading, step list or progress context, step-specific body content, Back, Next or step-specific primary action, Finish, and Cancel or Close.", "Make future, hidden, optional, current, complete, error, testing, review, and finished states visible from actual setup state; do not make the step list look complete because screens were visited." ], "uxGuidance": [ "Use a wizard when users must be guided through a dependent setup, creation, import, or configuration task where each step prepares the next one and final finish should be gated.", "Validate and save the local draft at each step, run required tests or previews before review, preserve state on Back, and provide a safe cancel path that explains whether the draft is paused, saved, or discarded." ], "uiExamples": { "good": [ "A connector setup wizard shows Choose connector, Configure access, Test connection, Review, and Finish in a side step list, with Configure access current and future steps disabled until prerequisites pass.", "The Test connection step has a primary Run test action, a result panel, and only then unlocks Review and Finish." ], "bad": [ "A generic Step 1, Step 2, Done strip wraps one text field and a Finish button with no dependency, preview, review, or cancel state.", "All steps are visible as visited while hidden required setup is inserted later, so the step count and current heading are dishonest." ] }, "uxExamples": { "good": [ "A user selects Zendesk, enters a token, runs a connection test, reviews generated sync settings, goes Back, and the token and test state are preserved or clearly invalidated when changed.", "A user clicks Cancel halfway through setup and sees a paused draft or discard confirmation instead of losing the partial configuration." ], "bad": [ "A user clicks Finish before the connector was tested and later discovers the integration never ran.", "A user goes Back to change the connector and the wizard silently keeps review answers from the old connector." ] }, "problemContext": [ "The task creates or configures something with dependencies, such as an integration, report, import, automation rule, device setup, or account configuration.", "Later steps depend on earlier selections or credentials and may need tests, generated previews, or external validation.", "Users need a clear path to finish or cancel without accidentally activating an incomplete setup." ], "selectionRules": [ "Choose a wizard when the product must guide users through a strict or mostly strict setup sequence with dependent choices.", "Use multi-step form instead when the task is primarily collecting submitted answers across saved pages.", "Use step navigation only as progress display inside a wizard or multi-step form, not as the wizard logic itself.", "Use a process list when users need to understand or complete a broader process outside one controlled assistant.", "Use a single-page form when all inputs are short, related, and safer to scan together before one save.", "Gate Next, Review, and Finish using real prerequisites such as a valid choice, credential, import mapping, test result, or generated preview.", "Use step-specific primary actions when they describe the real work better than Next, such as Test connection, Map columns, Generate preview, or Confirm review.", "Provide Cancel or Close behavior that preserves, pauses, or explicitly discards setup state rather than silently losing it.", "Retest or mark later steps stale when an earlier connector, template, permission, mapping, or option changes." ], "requiredStates": [ "Not-started state that explains what the wizard will configure and how many major steps follow.", "Current guided step with a clear heading, local controls, and step-specific primary action.", "Disabled future step state before prerequisites pass.", "Completed step state based on saved valid setup data.", "Validation or test-failed state that keeps users on the owning step with recovery guidance.", "Generated preview or test-passed state before review unlocks.", "Review state that summarizes choices and generated consequences before finish.", "Cancel or close state that explains draft preservation or discard.", "Finished state only after required steps, tests, and review are complete.", "Stale dependent step state after an earlier wizard choice changes." ], "interactionContract": [ "Next validates and stores the current step before moving forward.", "Step links can move only to completed or currently available steps unless the wizard explicitly supports non-linear editing.", "Back preserves entered data and returns to the previous guided step without activating finish or rerunning side effects.", "Step-specific actions such as Run test or Generate preview must complete before Review or Finish unlocks.", "Cancel and Close never discard a partial setup without an explicit saved, paused, or discard state.", "Changing an upstream setup choice invalidates or recomputes dependent tests, previews, review summaries, and finish eligibility.", "Finish performs the final commit only once all required steps and review gates are satisfied." ], "implementationChecklist": [ "Model wizard steps with stable IDs, route or panel ownership, prerequisites, completion rules, side effects, and stale-dependency rules.", "Write step-specific footer actions and disable or explain unavailable future steps.", "Persist draft state before navigation and restore it on Back, close, refresh, validation errors, and return from review.", "Separate local step validation from final Finish side effects.", "Provide test, preview, or generated-output states for steps that create external consequences.", "Add a review step for irreversible, high-cost, external, or generated setup changes.", "Confirm cancel or clearly communicate whether the wizard draft is saved, paused, or discarded.", "Move focus to the new step heading or first invalid control after navigation and validation.", "Test keyboard navigation through step list, footer actions, disabled steps, cancel, review change links, and final finish." ], "commonMisuses": [ "Using wizard chrome for a short edit form with no dependent sequence.", "Letting users finish before required tests, previews, or review pass.", "Treating step navigation as the whole wizard while leaving draft state and finish behavior undefined.", "Hiding conditional steps until after users relied on the displayed count.", "Using generic Next on steps whose actual obligation is Test, Map, Preview, or Confirm.", "Discarding partial setup on Cancel without a warning or draft recovery.", "Keeping stale generated settings after an earlier connector or template changes." ], "critiqueQuestions": [ "What dependency makes this a wizard rather than an ordinary multi-step form?", "Which step-specific action proves a step is complete?", "Can users cancel safely without losing work unexpectedly?", "What later steps become stale when each earlier choice changes?", "Is Finish impossible until every required test, preview, and review gate has passed?", "Would a process list or task list be more honest because users can work out of order?" ], "relatedPatterns": [ "multi-step-form", "step-navigation", "process-list", "single-page-form" ], "comparisons": [ "wizard-vs-multi-step-form-vs-step-navigation-vs-process-list" ], "sourceIds": [ "patternfly-wizard-component", "material-design-steppers-component", "govuk-form-structure-service-manual" ] } ] }