JOANNA OIKAWA
← All notes

Developer Ergonomic Design Principles

Six principles for building tools that preserve a developer’s momentum—not merely tools that are easy to use.

Note ·

The thesis

“Easy to use” is too low a bar.

A tool can be learnable and still interrupt you, make you wait, or force you to reconstruct context. I think developer ergonomics should be measured by how little momentum the tool takes away. As software becomes more capable, attention—not functionality—is the scarce resource.

01 · Responsiveness

First, it has to work. Fast.

Every repeated delay becomes part of the interface. Reliability creates trust; responsiveness preserves rhythm. The more often a workflow repeats, the more aggressively we should remove seconds, eye movement, and uncertainty.

  • Make performance a shared design constraint, not an engineering afterthought.
  • Measure perceived speed, too: motion, noise, and shifting layouts all add latency.

02 · First run

Prove value before asking for commitment.

The first-run experience should be a result, not a tour. Developers evaluate a tool by trying it, so give them an obvious, low-risk path to something real before requiring setup, configuration, or a new mental model.

  • Start with strong defaults; teach only when the next action needs explanation.
  • If setup is unavoidable, offer a runnable example or sandbox first.

03 · Attention

Focus over features.

A useful interruption at the wrong moment is still an interruption. Functionality creates value only when it arrives at a moment someone can act on it. Deep-work surfaces should pull information on demand; proactive information can wait for a boundary.

  • Suppress nonessential pushes while someone is coding.
  • Return deferred information at natural boundaries: test, commit, review, or deploy.

04 · Density

Make every option earn its space.

Customization is debt until a real workflow proves otherwise. Every control spends attention whether or not it gets used. Flexibility should emerge from observed needs—not from our inability to choose a default.

  • Begin with an opinionated default, then learn from repeated workarounds.
  • Review additions in the full workflow, where their cumulative cost is visible.

05 · Input

Match input to the moment.

The best input asks the least of your hands, eyes, and memory. Keyboard and voice solve different physical constraints. Efficient tools understand what the developer is already doing—and avoid making them switch modes.

  • Use standard shortcuts, visible hints, and customization for frequent actions.
  • Use voice when hands or eyes are occupied; show interpretation and make recovery easy.

06 · Architecture

Organize around intent, not product anatomy.

The task is the unit of organization. Developers think “fix the bug” or “ship the change”—not “open the place where this product stores commands.” Files, tools, context, and results should gather around that intent.

  • Group information around the task someone is trying to complete.
  • Use unified search when product categories would force a needless decision.

A working framework

Protect the thread.

These principles reduce to one question: does the tool help a developer hold onto the thread of their work? My team and I are still testing that question in real workflows. Tell me where it holds up—and where it doesn’t—on LinkedIn or X.