Update to Poka-Yoke

{
  "description": "Forms, destructive actions and flows users get wrong. Use when \"users keep deleting the wrong thing\", \"add a confirmation dialog\", \"this flow is error-prone\", or building a delete, bulk action, checkout or settings page. Covers undo over confirmation, type-to-confirm, safe defaults, input constraints, double-submit. For the server-side rules behind the screen use authz.",
  "included_files": [],
  "name": "ux",
  "skill_md_contents": "---\nname: ux\ndescription: >-\n  Forms, destructive actions and flows users get wrong. Use when \"users keep deleting the wrong thing\", \"add a confirmation dialog\", \"this flow is error-prone\", or building a delete, bulk action, checkout or settings page. Covers undo over confirmation, type-to-confirm, safe defaults, input constraints, double-submit. For the server-side rules behind the screen use authz.\n---\n\n# Poka-Yoke for Interfaces\n\nShingo built jigs so an assembly worker could not seat a part backwards. A form is a jig. The\nsame ladder applies, and the design literature arrived at the same place independently, Don\nNorman's *forcing functions* and Nielsen's *error prevention* heuristic describe the same move\nfrom a different tradition.\n\nThe single reframing that does most of the work here: **an error message is a failure of the\ndesign, not a feature of it.** If your interface can tell the user they did something wrong,\nit usually could have stopped them doing it. Validation that fires after submission is rung 3.\nAn input that cannot hold the wrong value is rung 1.\n\n## Building, not reviewing\n\nMost of the time this mode is reached *while someone is building the thing*, not afterwards.\nThat changes the deliverable. They asked for the interface, so produce the interface, working, complete,\nin their stack. Do not hand back a severity table when the person is mid-feature; a list of\nfindings about code they have not written yet is not useful to them.\n\nThen add a short closing note, three or four lines, covering:\n\n- which misuses the shape you chose makes impossible, and at which rung,\n- what you left possible on purpose, and why that tradeoff is the right one here.\n\nThat closing note is what stops the device being undone in six months by someone who cannot\nsee why it is there. It is also the difference between mistake-proofing and a code generator:\nthe reasoning travels with the code.\n\nWhen the code already exists and they are asking what is wrong with it, switch to the audit\nvoice, ranked findings with the mistake, the consequence, and the device. Match the mode to\nwhere they are in the work, not to this file's default.\n\n## The ladder, applied to interfaces\n\n| Rung | In a UI | Example |\n|---|---|---|\n| **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 |\n| **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 |\n| **3 Detection** | Caught after submission | Error summary at the top of the page · server rejects it · support ticket |\n| **0** | Relies on reading | Helper text · tooltips · a warning in a modal that everyone dismisses |\n\n## The rule that separates good UX poka-yoke from bad: undo beats confirm\n\nA confirmation dialog a user sees fifty times a day stops being a decision point. They develop\nclick-through blindness and press \"Confirm\" with the same reflex they press \"OK\", which means\nthe dialog protects nobody while adding friction to every legitimate action. It is the\ninterface equivalent of a comment saying \"be careful\": present, visible, and inert.\n\nThe preference order for destructive actions, strongest first:\n\n1. **Make it reversible.** Soft-delete, trash with a retention period, version history. Now the\n   mistake has no permanent consequence and needs no gate at all. This is the real answer and\n   it is under-used because it is a backend change, not a UI change.\n2. **Grace-period undo.** Perform it immediately, show \"Deleted. Undo\" for several seconds.\n   No friction on the happy path, full recovery on the mistaken one. Its close cousin is\n   delayed commit, hold the action for N seconds and drop it if undone, which is what Gmail's\n   undo-send does, and that is the easier build when the operation cannot be reversed once\n   performed.\n3. **Require an action proportional to the consequence.** Typing the resource's name to\n   confirm, GitHub's repository deletion, works because it cannot be done reflexively. Use\n   it only for genuinely irreversible, high-blast-radius actions; used everywhere it becomes\n   theater and people copy-paste through it.\n4. **A confirmation dialog that states the specific consequence.** \"Delete 3 projects and 1,204\n   files permanently?\" is a real check. \"Are you sure?\" is not. It asks about resolve, not\n   about facts, and the user's resolve is not the thing in question.\n\nA dialog that names the exact object and the exact count is doing fixed-value inspection. A\ndialog that says \"This action cannot be undone\" is doing nothing.\n\n## Designing an interface: enumerate the mistakes first\n\nSame ritual as API design, different failure modes. Before laying out a screen, ask:\n\n1. **What can the user enter that is wrong?** Can they even enter it? Free text where a\n   constrained choice exists is a hazard: every free-text field is a place to be wrong.\n2. **What is irreversible here?** Delete, send, publish, pay, cancel a subscription, rotate a\n   key. Each needs a device from the list above, sized to its blast radius.\n3. **What is adjacent to something dangerous?** \"Save\" beside \"Delete\" produces mis-clicks\n   forever. Separate destructive actions spatially, style them differently, and never make\n   them the default focus or the primary button.\n4. **What does the user have to remember or carry between steps?** Anything they must hold in\n   their head across a page transition will be dropped.\n5. **What happens if they double-click, refresh mid-submit, or hit back?** Double submission\n   is the UI's version of a non-idempotent retry, and it double-charges people.\n6. **What is the state of this control when the data is missing, huge, or slow?** Empty,\n   loading, error, and overflow states are where interfaces improvise.\n\n## The devices\n\n**Constrain the input rather than validate it.** A picker instead of a text field, a stepper\ninstead of a number input, a mask that only accepts a valid shape, `inputmode` and `type` so\nmobile keyboards offer the right keys, `max`/`min` that the control actually enforces. Every\nvalue the field cannot hold is a validation rule you never have to write and a user who never\nsees an error.\n\n**Disable the action until it can succeed**, but always show *why*. A greyed-out Submit with\nno explanation is its own dead end; pair it with the specific unmet requirement. Pick between\nthe two shapes deliberately: native `disabled`, which takes the button out of the tab order,\nso the reason has to live in adjacent text a screen reader will reach anyway; or\n`aria-disabled` with the handler refusing the submit, which keeps the button focusable so the\nreason is announced on the control itself.\n\n**Validate at the right moment.** On blur for the field just left, never on every keystroke\nwhile someone is still typing, validating a half-typed email as invalid trains people to\nignore your validation. Re-validate on submit, and put focus on the first offending field.\n\n**Preserve the user's work.** Losing entered data to a validation error, a session timeout, or\na back button is one of the most common and most infuriating mistakes an interface permits.\nDraft autosave, restore-on-return, and never clear a form on a failed submit.\n\n**Make defaults safe rather than convenient.** The pre-selected option should be the one whose\nconsequences are smallest if chosen inattentively, least-privilege, narrowest scope, private\nrather than public, opt-in rather than opt-out. Many users never change a default, so a\ndefault is a decision you are making for most of your users.\n\n**Prevent double submission structurally.** Disable the control on submit *and* carry an\nidempotency key on the request, because the button is not the only path, refresh, back, and\na flaky network all retry. The UI device and the API device are the same hazard (M2 in the\nhazard catalog) seen from two sides.\n\n**Show scale before a bulk action.** \"This will email 12,400 people\" is fixed-value inspection\nand it stops the mistake that a confirmation dialog does not.\n\n## Auditing an existing interface\n\nRead the actual component code, forms, buttons, modals, mutation handlers: not just\nscreenshots. What to look for, in priority order:\n\n1. **Every irreversible action.** Find the delete, send, publish, pay, and cancel handlers.\n   For each: what device guards it, at what rung, and is the action recoverable at all? An\n   irreversible action with only a generic confirm is the highest-value finding you will make.\n2. **Every free-text input.** Could it be a constrained control instead? What happens with\n   empty, whitespace-only, very long, pasted-with-formatting, or unicode input?\n3. **Adjacency and defaults.** Is a destructive button next to a benign one, styled the same,\n   or the default focus? Is any default the risky option?\n4. **Submission paths.** Double-click, refresh mid-flight, back button, slow network. Is the\n   mutation idempotent?\n5. **Error handling.** When validation fails, is the user's input preserved, is focus moved to\n   the problem, and does the message say how to fix it rather than what is wrong?\n6. **Permissions.** Is a dangerous action merely hidden, or actually unavailable? Hiding a\n   button is not a device: the endpoint is still there. Check that the server enforces it.\n\nReport using the same structure as `audit`: mistake, consequence, current rung,\nproposed device and rung. Propose before editing.\n\n## Restraint\n\nFriction is a cost paid by every user on every legitimate use, and the mistake is made rarely.\nConfirmations on reversible actions, validation on optional fields, and are-you-sure dialogs\non ordinary saves make an interface exhausting without preventing anything, and they train\nusers to dismiss the dialogs that matter. Aim devices at what is irreversible and\nconsequential; let everything else be fast, and make it undoable instead.\n\nThe pattern reference at `../../references/ux-patterns.md` has the concrete\nforms of each device and the standard destructive-action patterns. The hazard catalog at\n`../../references/hazard-catalog.md` still applies to the code behind the\nscreen: a mistake-proof form in front of a non-idempotent endpoint is only half a device.\n"
}