Spec Streaming and Progressive-Disclosure Behavior

Workflow area: AX Patterns · Tier: Advanced · Hands-on time: ~40 minutes

Static mockups can't answer the questions AI features raise: does the answer stream token-by-token or land whole? Does the user watch the reasoning or a spinner? Can they stop generation, and what remains if they do? Left unspecced, these become engineering defaults — usually "stream everything, always" — and the product feels frantic where it should feel considered. Perceived performance research is clear: a stream that starts instantly feels faster than a faster response that arrives complete, but streaming the wrong content (tables, code, prices) forces users to read a document that's still moving. This playbook makes each call explicit and hands engineering a spec instead of a shrug.

When to use — and when not to

• Use it at handoff for any generative surfacestreaming behavior is exactly the kind of decision that gets made in a pull request if design doesn't make it first.
• Use it when the feature mixes content typesprose plus tables plus actions in one response is where "stream everything" visibly breaks.
• Use it for long-running operationsanything over ~10 seconds needs designed progress disclosure, or users assume it's hung and leave.
• Skip it for sub-second responsesautocomplete and inline suggestions should just appear; specifying streaming for them is ceremony.
• Skip thinking-visibility debates when stakes are lowa caption generator doesn't need visible reasoning; save that decision for surfaces where users must judge the answer.

The recipe

1. 1.

   Inventory response types, not screens. List every distinct thing the surface returns: short prose, long prose, structured data, code, action proposals, mixed documents. Each type gets its own row in the spec — streaming is decided per type, never globally.

2. 2.

   Decide stream vs. appear-complete per type. The rule of thumb: stream content users read linearly (prose, explanations) — it starts fast and reads naturally. Appear complete content users scan or verify (tables, prices, code diffs, anything with a total) — a number that might still change is a number users can't trust. Skeleton first, then complete for structured layouts, so the shape arrives before the data. Write down the decision and the reason for each row.

3. 3.

   Spec thinking visibility in three tiers. Decide what the wait shows: silent (spinner or skeleton — right when reasoning adds nothing), status verbs ("Searching your docs… Comparing versions…" — right for multi-step tool use, because it sets accurate expectations of duration and source), or full reasoning stream (collapsed by default, expandable — right when experts audit the answer). Status verbs must be honest: a fake "Thinking deeply…" while a queue waits is trust spent on theater.

4. 4.

   Generate the annotated spec with AI, then correct it.

   Copy

   You are writing a front-end behavior spec for an AI feature.
   Response types and my decisions:
   [PASTE TABLE: type → stream/complete/skeleton → thinking tier]
   
   For each type, produce a spec block with:
   - TRIGGER: what the user did
   - T+0ms: what renders immediately (be exact: skeleton shape,
     status verb, disabled states)
   - DURING: streaming granularity (token/word/block), scroll
     behavior (pin to bottom? user-scroll cancels pinning?),
     what is interactive vs. locked
   - STOP: stop-button placement, and EXACTLY what remains after
     stop (partial kept + labeled? discarded?)
   - COLLAPSE: what arrives collapsed (reasoning, sources, long
     quotes) and the expand affordance
   - FAILURE MID-STREAM: what the user sees if generation dies at 60%
   Format as a table engineering can implement without asking me
   anything. Mark ambiguities [DESIGNER DECISION].
   

   Sample block worth stealing:

   Copy

   TYPE: long prose answer
   T+0: status verb "Reading 3 sources…" within 200ms
   DURING: word-level stream; auto-scroll pinned; any user scroll
   unpins; input stays enabled for follow-up typing
   STOP: persistent while streaming; on stop, partial output kept,
   labeled "Stopped early", regenerate offered
   FAILURE: partial kept + inline error "Generation failed partway —
   retry from start or keep partial"
   

5. 5.

   Motion-spec the two moments that sell quality. In Figma (with Figma Motion or prototype settings), spec the stream cadence — a slight ease on block arrival reads as composed; raw token jitter reads as nervous — and the complete transition: how the response settles (sources slide in, actions fade up) when generation ends. These two animations are most of "feels polished" for AI surfaces.

6. 6.

   Walk the spec against a slow day. Re-read every row assuming 5x normal latency. Does the status verb still make sense after 20 seconds? Is there a "still working" escalation? A spec that only works at demo speed is a demo, not a spec.

Make it yours

• Figma Make for a feelable prototype: build the streaming behavior with realistic timing and put both variants (stream vs. complete) in front of teammates — perceived-speed opinions change fast when people feel the difference.
• Claude Project as spec librarian: keep the response-type table in a Project and run every new surface through it, asking "which existing rows does this reuse, and which decisions are genuinely new?" — consistency across surfaces is the compounding win.
• Voice or embedded surfaces: replace visual streaming decisions with audio pacing ones — what interrupts speech, what earns a chime, and how "stop" works hands-free; the spec structure holds, the channels change.

Quality check

• Every response type has an explicit stream/complete decision with a reason"default" appearing anywhere in the table means the spec isn't finished.
• Numbers, totals and code never streamnothing a user might act on is shown while it can still change.
• Status verbs match real system activityeach one traces to an actual step; no theater.
• Stop behavior defines what remainsa stop button whose aftermath is unspecced will discard user-visible work in someone's implementation.
• Mid-stream failure is designedpartial output has a labeled state, not a silent vanish.
• The spec survives 5x latencythe slow-day walkthrough produced at least one escalation state.