06. Progressive disclosure¶
Error UX handles when things go wrong. Progressive disclosure handles how much to show when things go right. The discipline is to reveal capability, detail, and control in layers — so the novice is not overwhelmed and the expert is not constrained.
A platform engineer at a Hyderabad fintech ships an AI assistant that summarises portfolio risk. The first design dumps everything on screen: model confidence, source documents, intermediate reasoning, raw numbers, risk decomposition, peer comparisons, and a "ask follow-up" box. Novice users freeze — too much to read, no clear primary answer. Expert users complain the opposite — the summary is too vague, they want the breakdown immediately. The team redesigns: the summary lands first, two sentences and a single number; "show reasoning" expands the chain; "show sources" expands citations; "show breakdown" expands the analytics. Novices read the summary and stop. Experts click through to depth. Adoption rises across both segments.
This chapter is the disclosure discipline.
What progressive disclosure is¶
Progressive disclosure is the UX pattern of presenting AI output in layers — a primary answer up front, deeper detail available on demand — so the surface stays readable and the depth stays accessible.
Three layers in most AI surfaces:
| Layer | What lives here | Who reads it |
|---|---|---|
| Surface | The headline answer, one or two sentences, the single number | every user |
| Support | Reasoning, citations, confidence, alternatives | engaged users |
| Depth | Raw context, tool calls, parameters, traces | experts, auditors |
The wrong design puts everything on the surface, or hides the surface inside the depth.
Why disclosure matters more for AI than for traditional UX¶
Traditional UX hides complexity for ergonomics. AI UX hides complexity for trust and comprehension. The reader of an AI response is doing three jobs at once: reading the answer, judging whether to trust it, and deciding what to do next. If the surface is cluttered, judgement degrades and the user defaults to either blind trust or full abandonment.
Two examples:
- A medical-coding assistant shows the code, the confidence, the rationale, three alternatives, the source guideline, and the appeal path on one screen. The coder reads the code; ignores the rest; the rest may as well not be there.
- A legal-research tool shows only the answer. Lawyers do not click. They do not trust an answer with no visible source.
Both fail. The first overwhelms; the second under-supports. Progressive disclosure threads the needle.
The default-expanded mistake¶
Many teams over-correct from "too hidden" by making everything default-expanded. The result is the original clutter problem with extra clicks. The rule: expand by default only what every user needs every time. Everything else is one click away, clearly labelled.
A useful test: ask "what does the user need to do first?" If the answer is "read the headline," that is the only thing the surface needs.
Disclosure patterns¶
Pattern 1 — Headline + drawer¶
The answer lands at full readability. A drawer below holds reasoning, sources, alternatives. The drawer is closed by default. The label says what is inside ("Show reasoning", not "Details").
Use when: the user usually reads the surface and only sometimes needs depth.
Pattern 2 — Inline citation, expandable¶
The answer includes citation markers — [1], [2], hyperlinked spans. Hovering or clicking reveals the source. The surface stays prose; the depth is one interaction away.
Use when: every claim needs traceability but the prose must read cleanly.
Pattern 3 — Tabs¶
The surface is one tab. Reasoning, sources, history live in sibling tabs. Useful for dense outputs (legal briefs, code reviews) where each layer is large.
Use when: each depth layer is itself an artefact, not just an annotation.
Pattern 4 — Staged conversation¶
The first AI turn gives the headline. A follow-up affordance prompts the user to drill in. "Want me to explain why?" or "Show the breakdown?"
Use when: the depth is structured enough that drilling-in is a natural conversation turn.
Pattern 5 — Expert mode¶
A toggle (per user, per session, per workspace) inverts defaults — the depth is expanded, the surface is shorter. Pairs with role-based defaults (analyst vs. executive view).
Use when: the user population is bimodal and the cost of clicking-through is high for the expert side.
What lives at each layer¶
Surface — the absolute minimum to act on:
- The answer (sentence, number, code, decision).
- Confidence if it changes the action ("high confidence" or "low confidence — verify").
- The primary action affordance.
Support — what an engaged user needs to trust the answer:
- The reasoning summary (one paragraph, not the full chain).
- The citations (linked, count visible).
- Alternatives the AI considered.
- The correction path.
Depth — what an expert or auditor needs:
- The full reasoning trace.
- The raw source documents.
- Tool calls and parameters.
- The model and prompt version.
- The decision timestamp and session ID.
A common error is putting the model version on the surface (irrelevant for the action) or putting the correction affordance in the depth (the user gives up before finding it).
When not to use progressive disclosure¶
- Safety-critical disclosures. If the user must see a warning before acting (drug interaction, irreversible deletion, financial commitment), do not hide it. The surface carries it.
- Legal or compliance text. "By proceeding, you accept..." cannot be a drawer.
- Confidence that flips the action. If low confidence means the user should not act, that signal is surface, not support.
The rule: anything that would change the user's decision not to proceed is surface.
The disclosure decision per element¶
| Element | Default location |
|---|---|
| Answer | Surface |
| Single confidence indicator | Surface (if it changes action) |
| Reasoning summary | Support |
| Reasoning chain (full) | Depth |
| Citations (count) | Surface |
| Citations (content) | Support |
| Alternatives | Support |
| Tool calls | Depth |
| Model / prompt version | Depth |
| Correction affordance | Surface |
| Escalation affordance | Surface |
| Safety warnings | Surface (always) |
The defaults are starting points, not laws. A compliance product may pull citations up; an executive dashboard may push everything below the headline.
Common mistakes¶
Everything on surface. Cluttered, no clear primary answer, novice users freeze.
Everything hidden. Surface is too thin; expert users distrust; novice users have no anchors.
Default-expanded depth. All the clutter of "everything on surface" with extra DOM.
Mystery labels. "Details" and "More" tell the user nothing. "Show reasoning" or "Show sources" tells them what they will see.
Hidden corrections. The "this is wrong" affordance is buried two clicks deep; the user gives up.
Hidden escalations. Same as above; users who need a human cannot find one.
How to design the layers¶
Write the surface first, on the smallest screen you support, with no scroll. If it does not fit, the surface is too heavy.
Then write the support layer for the user who is uncertain about the surface. What would they want to see next?
Then write the depth layer for the user who is auditing. What would they need to reconstruct the decision?
If you cannot articulate who reads each layer, the layer is wrong.
Interview Q&A¶
Q1. The team's AI dumps everything on screen — answer, reasoning, sources, alternatives, model version. Adoption is poor. What is the diagnosis? Cluttered surface. Novice users do not know which line is the answer. Expert users do not know what is hidden because nothing is. The fix is a layered design: headline on the surface, reasoning and citations one click away, model and prompt version in a depth layer. Test by asking "what does the user need to do first?" — the answer to that is the only thing the surface needs. Wrong-answer note: "users will learn to scan" misses that scanning cost is paid every interaction.
Q2. When should a confidence indicator be on the surface vs. hidden in support? On the surface when it changes the user's action. If low confidence means "do not act yet, verify," the user must see it before deciding. In the support layer when it is decorative — the user would proceed either way. The rule is action-dependence, not aesthetic preference. Wrong-answer note: "always show confidence" pulls noise to the surface.
Q3. The team is debating whether to default-expand reasoning. What is your view? Default-collapsed unless the user population is overwhelmingly expert and skips the surface anyway. For the typical mixed audience, surface stays minimal; reasoning is one click away. Default-expand pulls back to the clutter problem the layering was meant to solve. Use an expert-mode toggle if both populations are real. Wrong-answer note: "transparency means showing everything" conflates availability with visibility.
Q4. A compliance team insists every citation must be on the screen at all times. How do you reconcile with progressive disclosure? Treat citations as inline markers on the surface — count visible, content one click away. The compliance need is traceability, which the markers satisfy. If they need full source text always rendered, accept that for that product class and let the surface grow; do not pretend disclosure can override compliance. The discipline is to find the smallest surface that meets the compliance bar. Wrong-answer note: "fight the compliance requirement" loses; "expand everything" loses readability. The middle path is markers + drawers.
Q5. The depth layer is rarely opened. Should it be deleted to simplify the codebase? No. Rare-use does not mean low-value. Auditors, support engineers, and incident responders need the depth layer when something has gone wrong. The depth layer pays its cost in the postmortem, not in the average session. Delete only if no audit, support, or debug path needs it. Wrong-answer note: "if no one reads it, kill it" optimises for the wrong workload.
What to do differently after reading this¶
- Write the surface first, on the smallest screen, with no scroll.
- Default-collapse the support and depth layers.
- Pull anything that changes the user's action up to the surface.
- Label drawers by what is inside, not "Details" or "More."
- Keep the correction and escalation affordances on the surface, always.
- Build the depth layer for auditors and incident responders, even if it is rarely opened.
Bridge. Progressive disclosure controls what the AI shows. Handoff to human controls what the AI does when it cannot or should not act. The next chapter is the discipline of escalation — when, how, and to whom. → 07-handoff-to-human.md