| name | Fluxwing Component Expander |
| description | Add interaction states like hover, focus, disabled, active, error to existing uxscii components. Use when working with .uxm files, when user wants to expand, enhance, or add states to .uxm components. |
| version | 0.0.1 |
| author | Trabian |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash |
Fluxwing Component Expander
Expand existing uxscii components by adding interaction states.
Data Location Rules
READ from:
./fluxwing/components/ - User-created components to expand./fluxwing/library/ - User library components to expand{SKILL_ROOT}/docs/ - Documentation for state definitions
WRITE to:
./fluxwing/components/ - Updated components (overwrite existing)./fluxwing/library/ - Updated library components (overwrite existing)
Your Task
Expand an existing uxscii component by adding interaction states.
Workflow
1. Locate Component
Ask for the component name if not provided:
- "Which component do you want to expand?"
- Search in
./fluxwing/components/ and ./fluxwing/library/
- Display current states if component found
2. Determine States to Add
Default behavior (no instructions): Add ALL standard states for component type
Smart defaults by type:
- button: hover, active, disabled
- input: focus, error, disabled
- checkbox/radio: checked, disabled
- select: open, disabled
- link: hover, visited, active
- card: hover, selected
- modal: open, closing
- alert: success, warning, error, info
- badge: active, inactive
- navigation: active, hover
- toggle: on, off, disabled
- slider: dragging, disabled
- tab: selected, hover
- list: selected, hover
- table: sorted, hover
User can override: "Only add hover and focus" or "Add error state only"
3. Read Existing Component Files
Read both files:
{component-name}.uxm - Current JSON metadata{component-name}.md - Current ASCII template
Extract:
- Current states (from behavior.states array)
- Component type (from type field)
- Visual properties (from ascii section)
- Variables (from ascii.variables array)
- Border style from default state (from behavior.states[0].properties.border)
4. Generate New States
For each new state to add:
A. Add state definition to .uxm file
Insert into the behavior.states array. Each state needs:
{
"name": "hover",
"properties": {
"border": "heavy",
"background": "primary-dark",
"textColor": "default"
},
"triggers": ["mouseenter"]
}
State property patterns by state name:
B. Generate ASCII for new state in .md file
Use appropriate box-drawing characters for each state:
- hover: Heavy border
┏━┓┃┗━┛
- focus: Double border
╔═╗║╚═╝
- active: Heavy filled
┏━┓┃┗━┛ with darker interior
- disabled: Dashed border
┌┄┄┐┆└┄┄┘
- error: Heavy border with indicator
┏━┓┃┗━┛ ⚠
- success: Heavy border with indicator
┏━┓┃┗━┛ ✓
- checked: Box with checkmark
[✓] or filled indicator
- selected: Heavy border with highlight background
- loading: Spinner or progress indicator
Template for new state section in .md file:
## {State Name} State
\`\`\`
{ASCII art using appropriate border style}
\`\`\`
5. Update Files
Write updated files:
- Overwrite
{component-name}.uxm with expanded states array
- Append new state sections to
{component-name}.md
Preserve:
- All existing metadata (name, description, author, created, tags, category)
- All existing variables
- All existing states
- All existing props
- Component ID and version
Update:
metadata.modified timestamp (set to current ISO 8601 timestamp)behavior.states array (add new states to end).md file (append new state sections before Variables section if it exists, otherwise at end)
Important: When updating the .md file, insert new state sections AFTER existing state sections but BEFORE the Variables, Accessibility, and Usage sections.
5a. Validate Expanded Component
After updating the files, validate the expanded component to ensure quality:
uv run {SKILL_ROOT}/../uxscii-component-creator/scripts/quick_validate.py \\
./fluxwing/components/{component-name}.uxm \\
{SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
Validation checks:
- ✓ JSON schema compliance
- ✓ All states have valid properties
- ✓ Variables match between .uxm and .md
- ✓ Accessibility requirements met
- ✓ No duplicate states
If validation fails:
- Read the error messages
- Fix the issues in the .uxm or .md files
- Re-validate before confirming to user
Performance: ~100ms (very fast!)
6. Confirm Expansion
Show summary:
✓ Expanded: ./fluxwing/components/{component-name}
✓ Added states: hover, active, disabled
✓ Total states: 4 (default, hover, active, disabled)
Preview of hover state:
┏━━━━━━━━━━━━━━━━━━━━┓
┃ {{text}} ┃
┗━━━━━━━━━━━━━━━━━━━━┛
Resources Available
- State patterns:
{SKILL_ROOT}/docs/06-ascii-patterns.md - Box-drawing characters
- Component creation:
{SKILL_ROOT}/docs/03-component-creation.md - Component structure
Example Interaction
User: Expand submit-button with hover state
Skill: I found `submit-button` in ./fluxwing/components/
Current states: default
I'll add the hover state to make the button interactive.
[Reads submit-button.uxm and submit-button.md]
[Generates hover state]
[Updates both files]
✓ Expanded: ./fluxwing/components/submit-button
✓ Added states: hover
✓ Total states: 2 (default, hover)
Preview of hover state:
┏━━━━━━━━━━━━━━━━━━━━┓
┃ Submit Form ┃
┗━━━━━━━━━━━━━━━━━━━━┛
Next steps:
- Add more states (active, disabled)
- Use this button in a screen
- View all components
Example with Custom States
User: Add focus and error states to email-input
Skill: I found `email-input` in ./fluxwing/components/
Current states: default
I'll add the requested states: focus, error
[Generates only focus and error states]
✓ Expanded: ./fluxwing/components/email-input
✓ Added states: focus, error
✓ Total states: 3 (default, focus, error)
Note: Standard input states also include 'disabled'.
Let me know if you want to add it!
Quality Standards
Ensure expanded components include:
- ✓ Valid JSON schema compliance (no breaking changes)
- ✓ All new states have definitions in .uxm behavior.states array
- ✓ All new states have ASCII sections in .md
- ✓ State properties match component type conventions
- ✓ Consistent box-drawing character usage
- ✓ Updated modification timestamp
- ✓ Preserved existing data (no data loss)
- ✓ No duplicate states (check before adding)
Important Notes
- Always preserve existing states (never remove or modify existing ones)
- Detect duplicate states (skip if state already exists in behavior.states array)
- Validate component after expansion (ensure valid JSON)
- Use appropriate border styles per state (refer to patterns doc)
- Match visual style of existing default state (consistent dimensions and layout)
- Test keyboard navigation for new interactive states
- Insert .md sections in correct location (after states, before Variables section)
- Update only the modified timestamp (preserve created timestamp)
Error Handling
If component not found:
✗ Component '{component-name}' not found.
Searched in:
- ./fluxwing/components/
- ./fluxwing/library/
Available components:
[List first 10 components found]
Please check the component name and try again.
If state already exists:
⚠ State 'hover' already exists in {component-name}.
Skipping duplicate state.
Current states: default, hover
Adding: active, disabled
If file write fails:
✗ Failed to update {component-name}.
Error: [specific error message]
The component files remain unchanged.
Please check file permissions and try again.
You're helping users create fully interactive uxscii components!
