fluxwing-enhancer

trabian's avatarfrom trabian

Enhance uxscii components from sketch to production fidelity. Use when working with .uxm files marked as "fidelity: sketch" or when user wants to add detail and polish to components.

⭐9stars🔀0forks📁View on GitHub🕐Updated Nov 30, 2025⬇️2downloads

When & Why to Use This Skill

Fluxwing Enhancer is a specialized Claude skill designed to automate the progressive refinement of uxscii components. It transitions UI elements from low-fidelity 'sketches' to 'production-ready' assets by enriching metadata, polishing ASCII art, adding interactive states (hover, focus, error), and incorporating accessibility details. By utilizing a versioned copy-on-update pattern, it ensures a non-destructive workflow for UI/UX designers and developers looking to bridge the gap between rapid prototyping and production-grade documentation.

Use Cases

  • Transforming rapid wireframe sketches into detailed UI components with consistent ASCII styling and enriched metadata.
  • Automating the generation of multiple interaction states (hover, focus, disabled, active) for a library of UI elements to ensure design system completeness.
  • Enriching component documentation with accessibility labels, keyboard shortcuts, and usage examples to meet production standards.
  • Managing large-scale component upgrades through parallel agent execution, allowing for the simultaneous enhancement of entire UI screen libraries.
nameFluxwing Enhancer
descriptionEnhance uxscii components from sketch to production fidelity. Use when working with .uxm files marked as "fidelity: sketch" or when user wants to add detail and polish to components.
version0.0.1
authorTrabian
allowed-toolsRead, Write, Edit, Glob, Grep, Task, TodoWrite

Fluxwing Enhancer

Progressively enhance uxscii components from sketch to production quality.

Data Location Rules

READ from:

  • ./fluxwing/components/ - User components to enhance
  • {SKILL_ROOT}/../fluxwing-component-creator/templates/state-additions/ - State templates
  • {SKILL_ROOT}/docs/ - Enhancement documentation

LOAD for copy-on-update logic:

  • {SKILL_ROOT}/../shared/docs/copy-versioning.md - Versioning pattern for fidelity enhancements

WRITE to:

  • ./fluxwing/components/ - New versioned components (copy-on-update: {id}-v{N+1})
  • ./fluxwing/screens/ - Updated screen .rendered.md (if applicable)

IMPORTANT: Enhancer creates NEW versions instead of overwriting originals. Each fidelity enhancement creates a new -v{N} copy.

Fidelity Levels

sketch (Fast Scaffold Output)

  • Basic .uxm with minimal metadata
  • May lack .md file or have simple .md
  • Single "default" state
  • Creation time: ~10 seconds

Characteristics:

  • Minimal description
  • Generic tags
  • No examples
  • Basic props only

basic (First Enhancement)

  • Enriched metadata (better description, tags)
  • Simple .md with clean ASCII
  • Default state only
  • Enhancement time: ~30 seconds

Improvements over sketch:

  • Detailed description
  • Specific tags
  • Clean ASCII art
  • Documented variables

detailed (Second Enhancement)

  • Rich metadata with usage examples
  • Polished .md with careful ASCII art
  • 2-3 interaction states (hover, focus)
  • Enhancement time: ~90 seconds

Improvements over basic:

  • Usage examples in metadata
  • Hover + focus states
  • Polished ASCII
  • Props.examples array

production (Final Polish)

  • Complete metadata with accessibility details
  • Publication-quality ASCII
  • All relevant states (hover, focus, disabled, active, error)
  • Full documentation
  • Enhancement time: ~180 seconds

Improvements over detailed:

  • All applicable states
  • Complete accessibility metadata
  • Keyboard shortcuts
  • Publication-quality ASCII
  • Edge case documentation

Your Task

Help users enhance components from current fidelity to target fidelity.

Workflow

Step 1: Inventory Components

Check what components exist and their current fidelity:

ls ./fluxwing/components/*.uxm

For each component, read fidelity level:

python3 -c "import json; print(json.load(open('./fluxwing/components/button.uxm'))['metadata'].get('fidelity', 'detailed'))"

List components by fidelity:

  • sketch: [component-ids]
  • basic: [component-ids]
  • detailed: [component-ids]
  • production: [component-ids]

Step 2: Determine Target Fidelity

Ask user or use defaults:

User specifies:

  • "Enhance to basic"
  • "Upgrade to detailed"
  • "Make production-ready"

Auto-select (if not specified):

  • sketch → detailed (most common, best balance)
  • basic → detailed
  • detailed → production

Step 3: Spawn Enhancement Agents

If enhancing multiple components (3+):

  • Spawn agents in parallel (one per component)
  • Each agent enhances independently
  • Wait for all to complete

If enhancing single component:

  • Spawn single agent
  • Focus on quality

Enhancement Agent Prompt:

Task({
  subagent_type: "general-purpose",
  model: "sonnet", // Quality matters for enhancement
  description: "Enhance ${componentId} to ${targetFidelity} (copy)",
  prompt: `Enhance uxscii component from ${currentFidelity} to ${targetFidelity} using copy-on-update pattern.

Component: ${componentId}
Current fidelity: ${currentFidelity}
Target fidelity: ${targetFidelity}

COPY-ON-UPDATE MODE:
- Read existing component
- Find highest version (check ${componentId}-v2, -v3, etc.)
- Create NEW versioned copy: ${componentId}-v{N+1}
- DO NOT overwrite original
- Preserve metadata.created, update metadata.modified

Your task:
1. Read ./fluxwing/components/${componentId}.uxm
2. Read ./fluxwing/components/${componentId}.md (if exists)
3. Load copy-versioning docs: {SKILL_ROOT}/../shared/docs/copy-versioning.md
4. Find highest version of ${componentId} (original is v1)
5. Calculate next version number: v{N+1}
6. Load enhancement patterns: {SKILL_ROOT}/docs/enhancement-patterns.md
7. Load state templates: {SKILL_ROOT}/../fluxwing-component-creator/templates/state-additions/

8. Create versioned copy with enhancements:

   **Update version metadata:**
   - id: "${componentId}-v{N+1}" (add -v{N+1} suffix)
   - version: Increment minor (e.g., 1.0.0 → 1.1.0)
   - metadata.created: PRESERVE from source
   - metadata.modified: SET to current timestamp
   - metadata.fidelity: UPDATE to "${targetFidelity}"

   ${targetFidelity === 'basic' ? `
   For "basic" fidelity:
   - Improve metadata.description (1-2 sentences, specific)
   - Add specific tags (not just generic type)
   - Create/improve .md with clean ASCII art
   - Keep single default state
   - Update fidelity field to "basic"
   ` : ''}

   ${targetFidelity === 'detailed' ? `
   For "detailed" fidelity:
   - All "basic" enhancements (if not already done)
   - Add hover state (use {SKILL_ROOT}/../fluxwing-component-creator/templates/state-additions/hover.json)
   - Add focus state (use {SKILL_ROOT}/../fluxwing-component-creator/templates/state-additions/focus.json)
   - Polish ASCII art (smooth alignment, consistent spacing)
   - Add props.examples array (2-3 usage examples)
   - Update fidelity field to "detailed"
   ` : ''}

   ${targetFidelity === 'production' ? `
   For "production" fidelity:
   - All "detailed" enhancements (if not already done)
   - Add disabled state (if applicable for component type)
   - Add error state (if applicable for component type)
   - Complete accessibility metadata:
     - aria-label templates
     - keyboard shortcuts
     - screen reader descriptions
   - Add behavior.keyboardShortcuts (if interactive)
   - Publication-quality ASCII (pixel-perfect alignment)
   - Document edge cases in description
   - Update fidelity field to "production"
   ` : ''}

9. Save NEW versioned files:
   - ./fluxwing/components/${componentId}-v{N+1}.uxm
   - ./fluxwing/components/${componentId}-v{N+1}.md
   - DO NOT overwrite original ${componentId}.uxm

10. Verify JSON is valid
11. Return enhancement summary with version info

Target time: ${targetTime[targetFidelity]} seconds

Return format:
"Enhanced ${componentId} → ${componentId}-v{N+1}: ${currentFidelity} → ${targetFidelity}
- Version: {old version} → {new version}
- Added X states
- Improved metadata
- Polished ASCII
- Original preserved at ${componentId}.uxm"
`
})

Step 4: Regenerate Screen (If Applicable)

If components belong to a screen, regenerate .rendered.md:

# Find which screen uses this component
grep -l "${componentId}" ./fluxwing/screens/*.uxm

If found, respawn composer to regenerate .rendered.md with enhanced components.

Step 5: Report Results

# Enhancement Complete ✓

## Components Enhanced

${enhancedComponents.map(c => `
### ${c.id}
- Before: ${c.oldFidelity}
- After: ${c.newFidelity}
- Time: ${c.time}s
- Changes:
  - ${c.changes.join('\n  - ')}
`).join('\n')}

## Total Time: ${totalTime}s

## Screens Updated
${updatedScreens.length > 0 ? updatedScreens.map(s => `- ${s}.rendered.md regenerated`).join('\n') : 'None'}

## Next Steps
1. Review enhanced components: \`ls ./fluxwing/components/\`
2. View updated screen: \`cat ./fluxwing/screens/${screenName}.rendered.md\`
3. Customize as needed

Example Usage

User: "Enhance all components in banking-chat to detailed"

Enhancer:

  1. Finds 6 sketch components
  2. Spawns 6 enhancement agents (parallel)
  3. Each agent: sketch → detailed (~90s)
  4. Regenerates banking-chat.rendered.md
  5. Total time: ~120 seconds

User: "Make submit-button production-ready"

Enhancer:

  1. Finds submit-button (detailed fidelity)
  2. Spawns 1 enhancement agent
  3. Agent: detailed → production (~180s)
  4. Updates screen if applicable
  5. Total time: ~180 seconds

Success Criteria

  • ✓ Components upgraded to target fidelity
  • ✓ All states added as specified
  • ✓ ASCII art improved
  • ✓ Metadata enriched
  • ✓ Screen .rendered.md regenerated (if applicable)
  • ✓ All files validate against schema

You are building a progressive enhancement system for maximum flexibility!