ui-state-design

UI State Design

Purpose

Prevent polished happy paths surrounded by ambiguous loading, failure, empty, disabled, permission, and recovery behavior.

When to use it

• For any interface with asynchronous data, mutations, permissions, or forms.

Instructions

1. Enumerate relevant states: initial, loading, incremental loading, empty, populated, stale, offline, permission denied, validation error, server error, partial success, success, disabled, destructive pending, and cancelled.
2. For each state define what the user sees, can do, hears through assistive technology, and how focus/state is preserved.
3. Keep actions named consistently from control through pending and result copy.
4. Prefer specific recovery instructions over generic error messages.
5. Prevent duplicate submission and destructive ambiguity without trapping users.
6. Test slow, failed, empty, and long-content cases—not only mocked success.

Output format

A state matrix with trigger, visible UI, available actions, announcement/focus, recovery, persistence, and verification for every applicable state.

Anti-patterns

• Empty blank panels, indefinite spinners, success-only stories, or errors with no recovery.
• Using disabled controls where an explanation or read-only state is needed.
• Toast-only feedback for errors requiring user correction.

Verification checklist

• Every reachable state has clear status, next action, and recovery behavior.
• State transitions preserve user input, navigation context, and accessibility.

Apply context-discovery before broad scanning: use a supplied context capsule first; otherwise check context frontmatter freshness, read .agent/context/routing.md, load only relevant summaries, and verify critical claims against source.