/state-machine

name: state-machine
description: Document UI component states (current vs expected) with transitions

State Machine Skill

Document the state machine for UI components, comparing current behavior to expected behavior and mapping all state transitions.

When to Use

• During Ask mode CONVERGE loop for stateful components
• When refactoring existing components with complex state
• Before implementing new interactive UI components

Instructions

Phase 1: Identify States

List all possible states for the component:

| State | Current Behavior | Expected Behavior | |-------|------------------|-------------------| | Initial | [What happens now] | [What should happen] | | Loading | [Current loading UX] | [Expected loading UX] | | Success | [Current success display] | [Expected success display] | | Error | [Current error handling] | [Expected error handling] | | Empty | [Current empty state] | [Expected empty state] |

**Common States to Consider:**

| State Type | Examples | |------------|----------| | Data states | Initial, Loading, Success, Error, Empty, Stale | | Interaction states | Idle, Hover, Focus, Active, Disabled | | Visibility states | Hidden, Visible, Collapsed, Expanded | | Selection states | Unselected, Selected, Partially selected | | Validation states | Valid, Invalid, Pending validation |

Phase 2: Map Transitions

Define what triggers each state change:

| From | To | Trigger | Side Effects | |------|----|---------|--------------| | Initial | Loading | User action / Mount | Start fetch | | Loading | Success | Data received | Populate UI | | Loading | Error | Request failed | Show error message | | Loading | Empty | Empty response | Show empty state | | Error | Loading | Retry clicked | Restart fetch | | Success | Loading | Refresh clicked | Refetch data |

Phase 3: State Diagram

Create a Mermaid state diagram:

stateDiagram-v2
    [*] --> Initial
    Initial --> Loading : fetch
    Loading --> Success : data received
    Loading --> Error : request failed
    Loading --> Empty : no data
    Error --> Loading : retry
    Success --> Loading : refresh
    Empty --> Loading : refresh
    Success --> [*] : unmount

Phase 4: Data Requirements

For each state, define what data is needed:

| State | Required Data | UI Elements | |-------|---------------|-------------| | Initial | None | Placeholder or skeleton | | Loading | None | Spinner, skeleton, progress | | Success | [List required fields] | Full component | | Error | Error message, retry action | Error banner, retry button | | Empty | Empty message, CTA | Empty illustration, CTA button |

Phase 5: Edge Cases

Identify edge cases and how to handle:

| Edge Case | Current | Expected | |-----------|---------|----------| | Network timeout | [Current] | Show timeout message, retry option | | Partial data | [Current] | Graceful degradation, show available | | Stale data | [Current] | Show stale indicator, background refresh | | Concurrent updates | [Current] | Optimistic update, rollback on conflict | | Auth expired | [Current] | Redirect to login, preserve state |

Output Format

## State Machine: [Component Name]

### State Table

| State | Current | Expected | Data Required |
|-------|---------|----------|---------------|
| Initial | [Behavior] | [Behavior] | [Data] |
| Loading | [Behavior] | [Behavior] | [Data] |
| Success | [Behavior] | [Behavior] | [Data] |
| Error | [Behavior] | [Behavior] | [Data] |
| Empty | [Behavior] | [Behavior] | [Data] |

### Transition Diagram

[Mermaid stateDiagram]

### Edge Cases

| Case | Handling |
|------|----------|
| [Case] | [How to handle] |

### Summary
- States: [N] identified
- Transitions: [N] mapped
- Edge cases: [N] documented

Invocation

Invoke manually with "use state-machine skill" or follow Ask mode CONVERGE loop which references this skill.

Related Skills

• `qa-planning` - Uses states to define test coverage
• `design-context` - Check existing component states in Storybook