UX Patterns Guide
UI + UX Disclosure And Attention Management standard

Disclosure / details

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.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • One short supporting explanation belongs in place beside the content it clarifies.
  • The explanation is useful for some users but not required reading for most users.
  • The summary can clearly name what is hidden.
  • Opening the content will not interrupt the main task or require a separate workflow.

Avoid when

  • The content is required to make the right decision.
  • The page has several related revealable sections that need headings or expand-all behavior.
  • The information is feedback that must stay visible until resolved.
  • The content is a separate destination, help article, file, or service.
  • The hidden content contains a long form, multi-step task, comparison table, or primary action.

Problem it prevents

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.

Pattern anatomy

What a strong implementation has to make clear

User need

A form field, policy sentence, calculation, document request, or content paragraph has one supporting explanation that only some users need.

Pattern promise

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.

Required state

Closed state with a specific summary label and hidden supporting content.

Recovery path

Users miss required content because the summary does not reveal its importance.

Access contract

Use native summary behavior or a button that exposes expanded and collapsed state.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • 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.
  • 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.
Weak implementation

Vague, hidden, hard to recover from

  • 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.
  • 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.
UI guidance
  • 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.
UX guidance
  • 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.
Implementation contract

What the implementation must handle

States

  • 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.

Interaction

  • 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.

Accessibility

  • Use native summary behavior or a button that exposes expanded and collapsed state.
  • Keep the summary text visible and descriptive in both states.
  • Place revealed content immediately after the trigger in DOM and reading order.
  • Do not rely on the triangle, chevron, color, or animation alone to communicate state.

Review

  • 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?
Interactive lab

Inspect the states before you copy the pattern

Reveal one optional explanation

Open and close one details disclosure, trigger a validation link that opens hidden help, preserve a nearby answer while toggling, and compare vague summary, hidden requirement, navigation-link, fake-control, state-loss, and overstuffed-content failures.

Disclosure / details
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Closed state with a specific summary label and hidden supporting content.

Keyboard / Access

Tab moves to the summary or disclosure button in normal page order.

Avoid Generating

Using vague summaries such as More, Details, or Click here.
Evidence trail

Source-backed claims behind this guidance

WAI-ARIA APG Disclosure Pattern

W3C WAI-ARIA Authoring Practices - checked

APG defines the disclosure show-hide widget, button state, and Enter or Space activation.

GOV.UK Design System Details

GOV.UK Design System - checked

GOV.UK details guidance supports one-section less-prominent revealable content and distinguishes details from accordions.

Full agent/debug reference

Problem Context

  • 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.

Selection Rules

  • 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.

Required States

  • 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.

Interaction Contract

  • 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.

Implementation Checklist

  • 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.

Common Generated-UI Mistakes

  • 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.

Critique Questions

  • 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?
Accessibility
  • Use native summary behavior or a button that exposes expanded and collapsed state.
  • Keep the summary text visible and descriptive in both states.
  • Place revealed content immediately after the trigger in DOM and reading order.
  • Do not rely on the triangle, chevron, color, or animation alone to communicate state.
  • Ensure keyboard users can toggle with Enter or Space and continue into revealed content in normal order.
  • If hidden content contains an error target, open it before moving focus or linking to the target.
  • Avoid excessive nested disclosures that make headings and landmarks harder to scan.
Keyboard Behavior
  • Tab moves to the summary or disclosure button in normal page order.
  • Enter toggles the disclosure when focus is on the summary or button.
  • Space toggles the disclosure when focus is on the summary or button.
  • After toggling, focus remains on the trigger unless the user followed a validation or deep link to revealed content.
  • Tab moves from the open trigger into any links or fields inside the revealed content.
  • Escape is not required to close or leave the disclosure.
Variants
  • Native details element
  • Button disclosure
  • Help text disclosure
  • Eligibility-note disclosure
  • Calculation-example disclosure
  • Validation-opened disclosure
  • Inline policy disclosure

Verification

Last verified: