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 coveragedesign-context - Check existing component states in Storybook
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: state-machine3description: Document UI component states (current vs expected) with transitions Use when this capability is needed.4---56# State Machine Skill78Document the state machine for UI components, comparing current behavior to expected behavior and mapping all state transitions.910## When to Use1112- During Ask mode CONVERGE loop for stateful components13- When refactoring existing components with complex state14- Before implementing new interactive UI components1516## Instructions1718### Phase 1: Identify States1920List all possible states for the component:2122| State | Current Behavior | Expected Behavior |23|-------|------------------|-------------------|24| Initial | [What happens now] | [What should happen] |25| Loading | [Current loading UX] | [Expected loading UX] |26| Success | [Current success display] | [Expected success display] |27| Error | [Current error handling] | [Expected error handling] |28| Empty | [Current empty state] | [Expected empty state] |2930**Common States to Consider:**3132| State Type | Examples |33|------------|----------|34| Data states | Initial, Loading, Success, Error, Empty, Stale |35| Interaction states | Idle, Hover, Focus, Active, Disabled |36| Visibility states | Hidden, Visible, Collapsed, Expanded |37| Selection states | Unselected, Selected, Partially selected |38| Validation states | Valid, Invalid, Pending validation |3940### Phase 2: Map Transitions4142Define what triggers each state change:4344| From | To | Trigger | Side Effects |45|------|----|---------|--------------|46| Initial | Loading | User action / Mount | Start fetch |47| Loading | Success | Data received | Populate UI |48| Loading | Error | Request failed | Show error message |49| Loading | Empty | Empty response | Show empty state |50| Error | Loading | Retry clicked | Restart fetch |51| Success | Loading | Refresh clicked | Refetch data |5253### Phase 3: State Diagram5455Create a Mermaid state diagram:5657```mermaid58stateDiagram-v259 [*] --> Initial60 Initial --> Loading : fetch61 Loading --> Success : data received62 Loading --> Error : request failed63 Loading --> Empty : no data64 Error --> Loading : retry65 Success --> Loading : refresh66 Empty --> Loading : refresh67 Success --> [*] : unmount68```6970### Phase 4: Data Requirements7172For each state, define what data is needed:7374| State | Required Data | UI Elements |75|-------|---------------|-------------|76| Initial | None | Placeholder or skeleton |77| Loading | None | Spinner, skeleton, progress |78| Success | [List required fields] | Full component |79| Error | Error message, retry action | Error banner, retry button |80| Empty | Empty message, CTA | Empty illustration, CTA button |8182### Phase 5: Edge Cases8384Identify edge cases and how to handle:8586| Edge Case | Current | Expected |87|-----------|---------|----------|88| Network timeout | [Current] | Show timeout message, retry option |89| Partial data | [Current] | Graceful degradation, show available |90| Stale data | [Current] | Show stale indicator, background refresh |91| Concurrent updates | [Current] | Optimistic update, rollback on conflict |92| Auth expired | [Current] | Redirect to login, preserve state |9394## Output Format9596```markdown97## State Machine: [Component Name]9899### State Table100101| State | Current | Expected | Data Required |102|-------|---------|----------|---------------|103| Initial | [Behavior] | [Behavior] | [Data] |104| Loading | [Behavior] | [Behavior] | [Data] |105| Success | [Behavior] | [Behavior] | [Data] |106| Error | [Behavior] | [Behavior] | [Data] |107| Empty | [Behavior] | [Behavior] | [Data] |108109### Transition Diagram110111[Mermaid stateDiagram]112113### Edge Cases114115| Case | Handling |116|------|----------|117| [Case] | [How to handle] |118119### Summary120- States: [N] identified121- Transitions: [N] mapped122- Edge cases: [N] documented123```124125## Invocation126127Invoke manually with "use state-machine skill" or follow Ask mode CONVERGE loop which references this skill.128129## Related Skills130131- `qa-planning` - Uses states to define test coverage132- `design-context` - Check existing component states in Storybook133134---135> Converted and distributed by [TomeVault](https://tomevault.io/claim/wellapp-ai) — claim your Tome and manage your conversions.136<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io