Disclose complexity slowly

Show the common path first; reveal advanced options only when asked.

Guillermo Rauch@rauchg
Some engineering principles I live by: ✓ Make it work, make it right, make it fast ✓ Progressive disclosure of complexity ✓ Minimize the number of concepts & modes
Nov 3, 2024View on X ↗
Guillermo Rauch@rauchg
It’s impressive from a technology standpoint that you’ve built so many “screens” and distinct states to represent data, but ultimately this kind of complexity is overwhelming for customers. Unsustainable.
Jul 21, 2024View on X ↗

Demo 1 is a project import form with detected defaults; the repo is made up.

1 · Same options, fewer asks

Deploy the repo from each form. Open the rows you need.

Every option up frontBad
Defaults, rest on askGood
<form action={deploy}>
  <RepoCard repo={repo} framework={detected.name} />
  <Input name="name" defaultValue={repo.name} />
  <details>
    <summary>Build settings <span>{detected.build} · {detected.output}</span></summary>
    <BuildSettings defaults={detected} />
  </details>
  <details>
    <summary>Environment variables <span>{env.length} set</span></summary>
    <EnvEditor initial={env} />
  </details>
  <Button type="submit">Deploy</Button>
</form>

2 · One mode beats three

Rename “Ship v2” and tick “Fix CLS” in both lists.

View, Edit, SelectBad
ModelessGood
<li>
  <Checkbox checked={task.done} onCheckedChange={toggle} />
  <input className="inline-title" defaultValue={task.title} onBlur={rename} />
</li>

Why it matters, pros and cons

Why it matters

Every visible field is a question. Detect what you can, answer the rest with defaults, and let experts open the rows they care about.

Pros

  • The first run is one click; nothing is taken away from experts.
  • Summary lines show the current values, so collapsed isn't hidden.
  • Fewer modes means fewer “it did nothing” clicks.

Cons

  • Bad detection hides a wrong default; show it in the summary.
  • Power users repeat a flow daily; remember which rows they open.
  • Don't bury what's required. Only optional things fold away.