state-machine
owl-listener/designer-skills
Model UI behavior as explicit states, events, and transitions to eliminate impossible states.
What is state-machine?
A skill for designing finite state machines that govern component behavior. Use this when a component has many interacting states that must be exhaustive and predictable. For single-interaction feel and feedback, use micro-interaction-spec instead.
- Define distinct states (idle, loading, success, error) that a UI component can occupy
- Specify events and triggers that cause transitions between states
- Create transition rules with guards and conditions to prevent invalid state combinations
- Eliminate impossible states by making all valid paths explicit
- Document entry and exit actions (side effects) for each state
- Provide a shared language between design and engineering teams
How to install state-machine
npx skills add https://github.com/owl-listener/designer-skills --skill state-machineHow to use state-machine
- 1.List all possible states your component can occupy
- 2.Enumerate all events or triggers that can occur
- 3.Define valid transitions: which events move between which states
- 4.Identify and prevent impossible state combinations using guards
- 5.Add entry and exit actions for side effects (fetch data, show notifications, log events)
- 6.Create a visual diagram of the state machine for team reference
- 7.Map each state to its corresponding UI representation
Use cases
- Model form behavior from idle through editing, validation, submission, and success/error states
- Design data-fetching flows with loading, success, error, and retry states
- Specify authentication flows from logged-out through authenticating to logged-in
- Define multi-step wizard navigation across sequential steps to completion
- Handle complex modal or dialog state transitions with entry/exit conditions
- UI/UX designers modeling component behavior
- Frontend engineers implementing predictable state-driven components
- Product teams documenting interaction specifications
- QA engineers writing exhaustive test cases for state transitions
state-machine FAQ
Use state machines when a component has multiple interacting states that must be exhaustive and predictable. For single interactions with just feel and feedback, use micro-interaction-spec instead.
Ensure every state has at least one outgoing transition. Review your state diagram to confirm users can always progress or return to a previous state.
Events are triggers that cause transitions (user clicks, API response). Guards are conditions that must be true for a transition to occur (form is valid, user has permission).
Keep state machines focused on one concern each. Multiple smaller machines are easier to test, understand, and maintain than one monolithic machine.
Create visual diagrams showing states as nodes and transitions as labeled arrows. Include guards and actions on transitions. Use consistent naming and share with both design and engineering.
Full instructions (SKILL.md)
Source of truth, from owl-listener/designer-skills.
name: state-machine
description: Model component behaviour as explicit states, events, and transitions. Use when a component has many interacting states that must be exhaustive. For the feel and feedback of a single interaction, use micro-interaction-spec.
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
- List all possible states
- List all events/triggers
- Define valid transitions
- Identify impossible states to prevent
- Add guards for conditional transitions
- 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
Related skills
More from owl-listener/designer-skills and the wider catalog.
summarize-interview
Turn interview transcripts into structured themes, quotes, and action items for immediate research insights.
survey-design
Design unbiased surveys to measure attitudes and prevalence at scale with sound methodology.
team-workflow
Design your team's operating rhythm—task management, rituals, and collaboration tooling.
test-scenario
Write realistic usability test scenarios with success criteria and observation guides.
theming-system
Design multi-brand and multi-mode theming architectures using token layers.
typography-scale
Create modular type scales with harmonious size, weight, and line-height relationships for consistent digital typography.