ux

Files (1)

• SKILL.md

SKILL.md (first lines)

# Poka-Yoke for Interfaces

Shingo built jigs so an assembly worker could not seat a part backwards. A form is a jig. The
same ladder applies, and the design literature arrived at the same place independently, Don
Norman's *forcing functions* and Nielsen's *error prevention* heuristic describe the same move
from a different tradition.

The single reframing that does most of the work here: **an error message is a failure of the
design, not a feature of it.** If your interface can tell the user they did something wrong,
it usually could have stopped them doing it. Validation that fires after submission is rung 3.
An input that cannot hold the wrong value is rung 1.

## Building, not reviewing

Most of the time this mode is reached *while someone is building the thing*, not afterwards.
That changes the deliverable. They asked for the interface, so produce the interface, working, complete,
in their stack. Do not hand back a severity table when the person is mid-feature; a list of
findings about code they have not written yet is not useful to them.

Then add a short closing note, three or four lines, covering:

- which misuses the shape you chose makes impossible, and at which rung,
- what you left possible on purpose, and why that tradeoff is the right one here.

That closing note is what stops the device being undone in six months by someone who cannot
see why it is there. It is also the difference between mistake-proofing and a code generator:
the reasoning travels with the code.

When the code already exists and they are asking what is wrong with it, switch to the audit
voice, ranked findings with the mistake, the consequence, and the device. Match the mode to
where they are in the work, not to this file's default.

## The ladder, applied to interfaces

| Rung | In a UI | Example |
|---|---|---|
| **1 Control** | The wrong action cannot be taken | Date picker that excludes unavailable dates · quantity capped at stock · Submit that does not exist until the form is valid · destructive action absent for users without permission |
| **2 Warning** | Possible, but flagged at the moment it happens | Inline field validation on blur · a live character counter turning red · a banner warning that this will affect 4,312 users |
| **3 Detection** | Caught after submission | Error summary at the top of the page · server rejects it · support ticket |
| **0** | Relies on reading | Helper text · tooltips · a warning in a modal that everyone dismisses |

## The rule that separates good UX poka-yoke from bad: undo beats confirm

A confirmation dialog a user sees fifty times a day stops being a decision point. They develop
click-through blindness and press "Confirm" with the same reflex they press "OK", which means
the dialog protects nobody while adding friction to every legitimate action. It is the
interface equivalent of a comment saying "be careful": present, visible, and inert.

The preference order for destructive actions, strongest first:

1. **Make it reversible.** Soft-delete, trash with a retention period, version history. Now the
   mistake has no permanent consequence and needs no gate at all. This is the real answer and
   it is under-used because it is a backend change, not a UI change.
2. **Grace-period undo.** Perform it immediately, show "Deleted. Undo" for several seconds.
   No friction on the happy path, full recovery on the mistaken one. Its close cousin is
   delayed commit, hold the action for N seconds and drop it if undone, which is what Gmail's
   undo-send does, and that is the easier build when the operation cannot be reversed once
   performed.
3. **Require an action proportional to the consequence.** Typing the resource's name to
   confirm, GitHub's repository deletion, works because it cannot be done reflexively. Use
   it only for genuinely irreversible, high-blast-radius actions; used everywhere it becomes
   theater and people copy-paste through it.
4. **A confirmation dialog that states the specific consequence.** "Delete 3 projects and 1,204
   files permanently?" is a real check. "Are you sure?" is not. It asks about resolve, not
   about facts, and the user's resolve is not the thing in question.

A dialog that names the exact object and the exact count is doing fixed-value inspection. A
dialog that says "This action cannot be undone" is doing nothing.

## Designing an interface: enumerate the mistakes first

Same ritual as API design, different failure modes. Before laying out a screen, ask:

1. **What can the user enter that is wrong?** Can they even enter it? Free text where a
   constrained choice exists is a hazard: every free-text field is a place to be wrong.
2. **What is irreversible here?** Delete, send, publish, pay, cancel a subscription, rotate a
   key. Each needs a device from the list above, sized to its blast radius.
3. **What is adjacent to something dangerous?** "Save" beside "Delete" produces mis-clicks
   forever. Separate destructive actions spatially, style them differently, and never make
   them the default focus or the primary button.
4. **What does the user have to remember or carry between steps?** Anything they must hold in
   their head across a page transition will be dropped.
5. **What happens if they double-click, refresh mid-submit, or hit back?** Double submission
   is the UI's version of a non-idempotent retry, and it double-charges people.
6. **What is the state of this control when the data is missing, huge, or slow?** Empty,
   loading, error, and overflow states are where interfaces improvise.

## The devices

**Constrain the input rather than validate it.** A picker instead of a text field, a stepper
instead of a number input, a mask that only accepts a valid shape, `inputmode` and `type` so
mobile keyboards offer the right keys, `max`/`min` that the control actually enforces. Every
value the field cannot hold is a validation rule you never have to write and a user who never
sees an error.

**Disable the action until it can succeed**, but always show *why*. A greyed-out Submit with
no explanation is its own dead end; pair it with the specific unmet requirement. Pick between
the two shapes deliberately: native `disabled`, which takes the button out of the tab order,
so the reason has to live in adjacent text a screen reader will reach anyway; or
`aria-disabled` with the handler refusing the submit, which keeps the button focusable so the
reason is announced on the control itself.

**Validate at the right moment.** On blur for the field just left, never on every keystroke
while someone is still typing, validating a half-typed email as invalid trains people to
ignore your validation. Re-validate on submit, and put focus on the first offending field.

**Preserve the user's work.** Losing entered data to a validation error, a session timeout, or
a back button is one of the most common and most infuriating mistakes an interface permits.
Draft autosave, restore-on-return, and never clear a form on a failed submit.

**Make defaults safe rather than convenient.** The preselected option should be the one whose
consequences are smallest if chosen inattentively, least-privilege, narrowest scope, private
rather than public, opt-in rather than opt-out. Many users never change a default, so a
default is a decision you are making for most of your users.

**Prevent double submission structurally.** Disable the control on submit *and* carry an
idempotency key on the request, because the button is not the only path, refresh, back, and
a flaky network all retry. The UI device and the API device are the same hazard (M2 in the
hazard catalog) seen from two sides.

From rainmanjam/poka-yoke, MIT.

More from rainmanjam/poka-yoke