State Machine
Model forms, wizards, and async UI as explicit finite state machines so impossible states and edge cases are visible before you code.
Overview
state-machine is an agent skill most often used in Build (also Validate) that models UI components and flows as finite state machines with states, events, and transitions.
Install
npx skills add https://github.com/owl-listener/designer-skills --skill state-machineWhat is this skill?
- Defines states, events, transitions, guards, and entry/exit actions for UI flows
- Includes reference machines for forms, data fetching, authentication, and multi-step wizards
- Six-step modeling approach from listing states through preventing impossible combinations
- Emphasizes eliminating contradictory UI states such as loading and error at once
- Makes edge cases explicit in a shared vocabulary before implementation
- Six-step modeling approach for UI state machines
- Four reference UI patterns: form, data fetching, authentication, multi-step wizard
Adoption & trust: 591 installs on skills.sh; 1.5k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your UI logic is a tangle of flags that allow impossible combinations and hide edge cases until users hit them in production.
Who is it for?
Indie frontend builders designing multi-step flows, async data surfaces, or auth gates who want a rigorous behavior blueprint first.
Skip if: Purely static marketing pages with no interactive modes, or backend-only state orchestration with no UI surface.
When should I use this skill?
You need to model complex UI behavior, eliminate impossible states, or design transitions for forms, fetching, auth, or wizards.
What do I get? / Deliverables
You get a clear FSM spec with valid transitions and guards that agents or developers can implement without ambiguous concurrent states.
- State list with events, transitions, guards, and entry/exit actions
- Transition diagram or narrative spec agents can implement against
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build → frontend is the primary shelf because the skill targets component and flow behavior in interactive UIs, not infra or distribution. Frontend subphase reflects FSM modeling for forms, fetching, auth, and multi-step wizards—the core examples in the skill body.
Where it fits
You sketch a three-step onboarding wizard and define events before picking a component library.
You refactor a checkout form so validating and submitting cannot overlap with a stale error banner.
You compare implemented screens against the FSM to see if any illegal state snuck in during code review.
How it compares
Use this design methodology instead of piling on boolean isLoading or hasError props without a transition map.
Common Questions / FAQ
Who is state-machine for?
Solo builders and designers pairing with coding agents on interactive products who need predictable UI behavior spelled out before implementation.
When should I use state-machine?
Use it in Validate when prototyping a wizard or checkout flow, and in Build when refactoring a form or fetch screen that keeps accumulating edge-case bugs.
Is state-machine safe to install?
It is documentation-only modeling guidance with no runtime privileges; still review the Security Audits panel on this Prism page before enabling any skill in your agent.
SKILL.md
READMESKILL.md - State Machine
# 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