Defines an undo affordance that is perceivable without stealing focus, operable by keyboard and assistive technology, and truthful about the reversible action and its expiry.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Apply the change immediately, then expose a single-action undo status message for a configurable window. Preserve focus, announce concise status text, and provide a non-timed recovery path when loss would be serious.
Scope
- Focus, keyboard activation, live-region announcements, expiry, repeated actions, and recovery.
- Undo for one completed user action with a durable operation identity.
- Visual and assistive-technology behavior of the status message.
Outside this block
- Replacing confirmation for irreversible, high-impact actions.
- A general command-history architecture or collaborative rollback.
Contract
- Completing the action does not move keyboard focus to the status message.
- A polite status announcement names the result and the available Undo action once; countdown ticks are not announced.
- Undo is a native button in the tab order and has an accessible name that identifies the action when ambiguity exists.
- Activation is idempotent and targets the exact operation ID, not simply the most recent matching record.
- Expiry removes or disables the action consistently; assistive technology receives one concise expiry/result update.
- Repeated actions remain individually attributable or are deliberately collapsed with a documented rule.
Implementation guidance
- Use a persistent operation ID returned by the mutation and send it with undo.
- Keep the live region mounted so announcements are reliable; update its text rather than recreating the node.
- Pause visual expiry when product policy requires it, or provide an activity/history recovery route for consequential changes.
- Test keyboard-only, common screen readers, reduced motion, and high zoom.
Failure handling and safeguards
- If undo conflicts with a later edit, do not overwrite the later state; return an explanatory conflict and recovery route.
- If the undo request times out, keep status uncertain until operation lookup resolves it.
- If the action is already undone, return the same successful final state.
Verification and operations
- Track undo attempts, success, expiry, conflicts, and duplicate activation.
- Verify focus position and live-region output in automated accessibility tests plus manual assistive-technology review.
- Reassess the time window using observed completion and recovery needs, not a hard-coded universal value.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.