Principles

Rules for the pit

The short version of the whole system. Concise on purpose; each idea gets its full argument, with live demos, in the chapters below.

Philosophy

  • Agents run laps; humans work the pit. Design effort goes to the sync moments: approval, inspection, handoff, recovery.
  • Interface, not architecture. This system covers what people see, approve, interrupt, and trust, not how the agent is orchestrated.
  • Evidence over opinion. A principle that can't be demonstrated with a working component isn't done being designed.
  • Built to be copied. Single-file components, three dependencies, MIT. Take the code and own it.
  • One system for humans and agents. The registry is machine-readable, so AI assistants install these components the same way you do.

The rules

  1. 01Show intent before action, state during, evidence on demand.
  2. 02Never communicate state by color alone; icon and label, always.
  3. 03Render the plan before execution; done stays visible, failed stays in place.
  4. 04Itemize scope before consent; mark what can't be undone.
  5. 05Gate irreversible actions only; never ask permission to read.
  6. 06Stop is always visible and never destructive; the receipt says what survived.
  7. 07Acknowledge every steer the moment it lands.
  8. 08Confidence comes in bands, never decimals; claims travel with their basis.
  9. 09Verification is one tap away and cheaper than redoing.
  10. 10Failure is a rendered state; keep the inputs attached, bound the retries.

Don't

  • Dump raw chain-of-thought and call it transparency. Structure beats volume; that's Legible Thinking.
  • Fake a progress bar over indeterminate work. An honest pulse beats a lying percentage.
  • Offer blanket “always allow.” Scope a remembered choice as narrowly as the choice.
  • Show “87.3% confident.” Decimal confidence is theater; use bands.
  • Narrate (“Let me search…”) instead of showing. Narration is prose about work; legibility is the work.
  • Discard partial work on failure or stop. Three done steps are three done steps.
  • Retry silently. Show the attempt count and the bound.
  • Hide the stop control in a menu. A brake you have to find is not a brake.

The design language: headlights

A night race. The interface is dark and calm; light is spent only on what matters right now. Attention is the scarcest resource in an agent product, so the visual system is built to spend it deliberately.

  • One bright thing per surface. The current element renders at full strength; supporting context ghosts back to ~45–60%. If everything is lit, nothing is.
  • The past dims, the present glows, the future is outlined. Completed work fades to smoke, the active step holds chalk with a pit-orange pulse, pending work is drawn in ash outlines. Time is rendered as light.
  • Large calm containers. Feature surfaces use 24px radius, generous padding, hairline borders one step above their background, and a whisper of dot-grid texture. Components inside stay tighter at 12px.
  • Pit-lane orange is earned. The accent marks the live thing: the running dot, the agent car, the primary action. It never decorates. Caution is yellow, success is green, danger is red, and none of them ever speak through color alone.

Motion

  • Motion is state change, never decoration. Every animation answers one question: what just happened, or where should I look?
  • Three speeds. Micro-feedback at ~150ms, element entrances and collapses at 250–400ms with the house ease (0.32, 0.72, 0, 1), ambient pulses at 1.2–1.4s. Nothing else.
  • Arrive rising, leave collapsing. New information enters with a small rise and settle; resolved information collapses to a receipt. Closing is always faster than opening.
  • Ambient means honest. Pulses mark genuinely live processes only; no fake progress, no decorative loops. All motion respects prefers-reduced-motion.

The essentials

The minimum kit for any agent interface. If your product has an agent and is missing one of these, that's the next thing to design.

Going deeper