mcpField
S
state-machine

state-machine

github.com/owl-listenerDesign & UI3.1k2.3k installsUpdated 8w ago
Repository

About state-machine

A design skill for modeling complex UI behavior as finite state machines. It helps designers and engineers define valid transitions, expose edge cases, and specify testable behavior.

Key features

  1. 01Define states, events, and transitions
  2. 02Add guards and transition actions
  3. 03Identify impossible states and edge cases
  4. 04Specify UI flows for common patterns
  5. 05Document behavior with visual diagrams

Use cases

  1. 01Map form submission and validation flows
  2. 02Describe loading, error, and retry behavior
  3. 03Model authentication and multi-step wizards

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/owl-listener/designer-skills --skill state-machine

After installing, type/state-machinein Claude Code to confirm it loaded.

Details

From the project README

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

Comments

Markdown supported