state-machine
Map UI component states and transitions to ensure consistent, documented interaction logic.
Install
mkdir -p .claude/skills/state-machine && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/5100" && unzip -o skill.zip -d .claude/skills/state-machine && rm skill.zipInstalls to .claude/skills/state-machine
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Document UI component states (current vs expected) with transitionsKey capabilities
- →Map UI state transition tables
- →Identify state side effects and triggers
- →Generate Mermaid diagrams for state machines
- →Document state-specific UI behaviors
How it works
Systematically iterates through state categories to map triggers and expected outputs into a standard documentation format.
Inputs & outputs
When to use state-machine
- →Refactor legacy UI components
- →Define state machine for new interactive features
- →Compare actual vs expected UI states
- →Document visibility and selection flows
About this skill
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
When not to use it
- →Simple, stateless components
- →High-velocity prototyping with no documentation requirements
Limitations
- →Requires manual identification of states by the developer
- →Does not enforce state machine logic in actual code
How it compares
Formalizes UX logic into state machines rather than descriptive prose.
Compared to similar skills
state-machine side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| state-machine (this skill) | 1 | 7mo | No flags | Beginner |
| draw-io | 41 | 6mo | Review | Intermediate |
| ui-design-system | 29 | 7mo | Review | Beginner |
| design-md | 27 | 4mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by WellApp-ai
View all by WellApp-ai →You might also like
draw-io
davila7
draw.io diagram creation, editing, and review. Use for .drawio XML editing, PNG conversion, layout adjustment, and AWS icon usage.
ui-design-system
davila7
UI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use for creating design systems, maintaining visual consistency, and facilitating design-dev collaboration.
design-md
sickn33
Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files
brief
educlopez
Write or update the project's durable design brief at .ui-craft/brief.md. Invoke when the user asks for brief on their UI, or mentions 'brief' alongside design / UI / frontend work.
update-design-audits
meshtastic
Use this skill when asked to update the cross-platform design audit documents in `standards/audits/` with recent pull request activity from the `meshtastic/Meshtastic-Apple` and/or `meshtastic/Meshtastic-Android` repositories. Typical triggers:
validate-screenshots
OutSystems
>-