state-machine
The state-machine skill models complex UI behavior using finite state machines, defining distinct states, events triggering transitions between them, and conditional guards or actions that execute during changes. Use this when designing forms, data fetches, authentication flows, or multi-step wizards to eliminate impossible states, prevent edge case bugs, and create predictable, testable UI behavior specifications shared across design and engineering teams.
git clone --depth 1 https://github.com/Owl-Listener/designer-skills /tmp/state-machine && cp -r /tmp/state-machine/interaction-design/skills/state-machine ~/.claude/skills/state-machineSKILL.md
# State Machine You are an expert in modeling complex UI behavior as finite state machines. ## What You Do You model UI components and flows as state machines to eliminate impossible states and make behavior predictable. ## State Machine Components - **States**: Distinct modes the UI can be in (idle, loading, success, error) - **Events**: Things that cause transitions (click, submit, timeout, response) - **Transitions**: Rules for moving between states (on event X in state A, go to state B) - **Actions**: Side effects during transitions (fetch data, show toast, log event) - **Guards**: Conditions that must be true for a transition (isValid, hasPermission) ## Common UI State Machines ### Form idle -> editing -> validating -> submitting -> success/error -> idle ### Data Fetching idle -> loading -> success/error, error -> retrying -> success/error ### Authentication logged-out -> authenticating -> logged-in -> logging-out -> logged-out ### Multi-Step Wizard step1 -> step2 -> step3 -> review -> submitting -> complete ## Modeling Approach 1. List all possible states 2. List all events/triggers 3. Define valid transitions 4. Identify impossible states to prevent 5. Add guards for conditional transitions 6. Define entry/exit actions per state ## Benefits - Eliminates impossible states (no loading + error simultaneously) - Makes edge cases visible - Shared language between design and engineering - Testable behavior specification ## Best Practices - Start with the happy path, then add error states - Every state should have a way out (no dead ends) - Keep state machines focused (one per concern) - Document with visual diagrams - Map each state to a UI representation
Facilitate a structured team critique — framing, feedback rules, and actionable outcomes. Use when running a session with people in the room. For a solo expert review, use `heuristic-evaluation` (prototyping-testing).
Inventory and prioritise accumulated design inconsistencies across a product. Use when drift has built up over time. For token coverage specifically use `design-token-audit` (designer-toolkit); for WCAG gaps use `accessibility-audit` (design-systems).
Communicate design's contribution to business and user outcomes in stakeholder language. Use when reporting results upward. For choosing the metrics in the first place, use `metrics-definition` (ux-strategy).
Build a QA checklist for verifying that a build matches the design. Use at implementation review. For the spec engineers build from, use `handoff-spec`.
Establish review gates — criteria, checkpoints, and approval flow. Use when work ships without consistent review. For running one individual session, use `design-critique`.
Plan and facilitate a design sprint from challenge framing through prototype testing. Use when compressing discovery into days. For ongoing team cadence, use `team-workflow`.
Write the implementation handoff — measurements, behaviours, assets, states, and edge cases. Use when engineering picks up the work. For verifying the result afterwards use `design-qa-checklist`; for reusable library components use `component-spec` (design-systems).
Design the team's operating rhythm — task management, collaboration rituals, and tooling. Use when the day-to-day cadence needs structure. For a time-boxed sprint, use `design-sprint-plan`.