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:

• hover:

  • border: "heavy"
  • background: slightly darker than default
  • triggers: ["mouseenter"]

• focus:

  • border: "double"
  • background: same as default
  • textColor: "primary"
  • triggers: ["focus"]

• active:

  • border: "heavy"
  • background: "filled"
  • triggers: ["mousedown"]

• disabled:

  • border: "dashed"
  • opacity: 0.5
  • cursor: "not-allowed"

• error:

  • border: "heavy"
  • borderColor: "red"
  • textColor: "error"

• success:

  • border: "heavy"
  • borderColor: "green"
  • textColor: "success"

• loading:

  • opacity: 0.7
  • cursor: "wait"

• checked (checkbox/radio):

  • border: "heavy"
  • background: "filled"
  • textColor: "primary"

• selected:

  • border: "heavy"
  • background: "highlight"
  • textColor: "primary"

• open (modal/select):

  • visible: true
  • triggers: ["click"]

• visited (link):

  • textColor: "visited"

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

...