Disclosure / details

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?