Fluxwing Screen Scaffolder

Fluxwing Screen Scaffolder

Create complete screen designs using the uxscii standard by orchestrating specialized agents.

Data Location Rules

READ from (bundled templates - reference only):

• {SKILL_ROOT}/../uxscii-component-creator/templates/ - 11 component templates
• {SKILL_ROOT}/templates/ - 2 screen examples
• {SKILL_ROOT}/docs/ - Documentation

INVENTORY sources (check all for available components):

• ./fluxwing/components/ - User-created components (FIRST PRIORITY)
• ./fluxwing/library/ - Customized template copies
• {SKILL_ROOT}/../uxscii-component-creator/templates/ - Bundled templates (READ-ONLY)

WRITE to (project workspace):

• ./fluxwing/screens/ - Your created screens (via composer agent)

NEVER write to skill directories - they are read-only!

LOAD for copy-on-update logic:

• {SKILL_ROOT}/../shared/docs/copy-versioning.md - Versioning pattern for existing screens

Your Task

⚠️ YOU ARE AN ORCHESTRATOR - DO NOT DO THE WORK YOURSELF! ⚠️

Your role is to spawn agents using the Task tool. You coordinate agents, you don't create components directly.

Help the user scaffold a complete screen by orchestrating agents in two phases:

1. Phase 1 (Parallel): Spawn multiple designer agents - one per missing component using multiple Task tool calls in ONE message
2. Phase 2 (Sequential): After all components exist, spawn composer agent

Concurrency Model:

• If 6 components are missing → spawn 6 agents in parallel using 6 Task tool calls in ONE message (~6x faster)
• Then wait for all to complete before composing screen

CRITICAL: Use the Task tool to spawn agents. Do NOT use TodoWrite and work through tasks yourself. Do NOT create files yourself.

MULTI-SCREEN SCENARIOS:

If user requests N screens (N > 1):

• ⚠️ DO NOT create TodoWrite list with N screen tasks and work through them
• ⚠️ DO NOT use Write/Edit tools to create screen files yourself
• ⚠️ DO NOT "help" composer agents by pre-creating any files
• ✅ DO spawn N composer agents in parallel (one per screen)
• ✅ DO send ONE message with ALL Task calls (parallel execution)
• ✅ DO let each composer agent independently create all 3 files (.uxm, .md, .rendered.md)

Example: 6 screens = ONE message with 6 Task tool calls → 18 files created by agents

You are an ORCHESTRATOR. Your job is to spawn agents, not do their work.

Quality Presets

Scaffolder supports different quality levels for speed vs fidelity tradeoffs:

fast (60-90s)

• Create components (sketch fidelity)
• Compose screen
• Skip enhancement
• Use when: Rapid prototyping, early iteration

Output:

• Components: sketch fidelity (.uxm only initially, .md by composer)
• Screen: .rendered.md with basic quality
• Time: ~60-90s for 6 components

balanced (90-150s)

• Create components (sketch fidelity)
• Compose screen
• Enhance to basic fidelity
• Use when: Quick iteration with decent quality

Output:

• Components: basic fidelity (.uxm + improved .md)
• Screen: .rendered.md with good quality
• Time: ~90-150s for 6 components

detailed (180-240s) [DEFAULT]

• Create components (sketch fidelity)
• Compose screen
• Enhance to detailed fidelity (hover + focus states)
• Use when: Production-ready screens, demos

Output:

• Components: detailed fidelity (.uxm + polished .md + states)
• Screen: .rendered.md with high quality
• Time: ~180-240s for 6 components

production (300-400s)

• Create components (sketch fidelity)
• Compose screen
• Enhance to production fidelity (all states + full a11y)
• Use when: Final polish, publication

Output:

• Components: production fidelity (complete)
• Screen: .rendered.md with publication quality
• Time: ~300-400s for 6 components

Default: detailed (best balance of quality and speed)

Workflow

Step 1: Understand the Screen

Ask about the screen they want to create:

Screen details:

• Screen name and purpose: login, dashboard, profile, settings, checkout, etc.
• Required components: forms, navigation, cards, modals, lists, etc.
• Layout structure: vertical, horizontal, grid, sidebar+main, etc.

Quality preset (optional):

• fast - Quick prototype (60-90s)
• balanced - Good quality (90-150s)
• detailed - High quality (180-240s) [DEFAULT]
• production - Publication ready (300-400s)

If user doesn't specify, use detailed preset.

Detect multi-screen requests:

If the user's request indicates multiple screens, detect by:

• Plural language: "screens", "pages", "all of them"
• Multiple file references: Glob results showing multiple screenshots or files
• Explicit numbers: "5 screens", "all these", "create pages for..."

When multiple screens detected, confirm with the user:

I see you want to create [N] screens:
- [screen-name-1]
- [screen-name-2]
- [screen-name-3]
- ...

I'll create these in parallel using one composer agent per screen.
Each screen will get all 3 files (.uxm, .md, .rendered.md).

Quality preset: [preset] (default: detailed)
Estimated time: ~[X-Y] seconds

Proceed? [Yes/No]

Purpose:

• Sets clear expectations upfront
• Emphasizes .rendered.md is included for ALL screens
• Provides time estimate
• Prevents surprises

After confirmation, use Path B workflow (see below).

Step 2: Component Inventory

Check what components are available in this order:

1. User-created: ./fluxwing/components/ (FIRST PRIORITY)
2. Library: ./fluxwing/library/ (customized templates)
3. Bundled examples: {SKILL_ROOT}/../uxscii-component-creator/templates/ (READ-ONLY)

List what exists vs what needs to be created.

// Example inventory check
const userComponents = glob('./fluxwing/components/*.uxm');
const libraryComponents = glob('./fluxwing/library/*.uxm');
const bundledComponents = glob('{SKILL_ROOT}/../uxscii-component-creator/templates/*.uxm');

const available = [...userComponents, ...libraryComponents, ...bundledComponents];
const missing = requiredComponents.filter(c => !available.includes(c));

Step 2.5: Pre-Scaffolding Validation (Check for Existing Screen)

IMPORTANT: Before creating any screen, check if it already exists to prevent data loss.

1. Convert screen name to kebab-case ID:

`` "Login Screen" → "login-screen" "User Dashboard" → "user-dashboard" ``

1. Check if screen exists:

``bash # Check for existing screen test -f ./fluxwing/screens/{screen-id}.uxm ``

1. If screen EXISTS:

Inform user and offer choices: ``` Screen '{screen-id}' already exists (version {current-version}).

Options: (a) Create new version (copy-on-update: {screen-id}-v{N+1}) (b) Create with different name (c) Cancel operation

What would you like to do? ```

Handle user response:

• Choice (a) - Create new version:

1. Load copy-versioning logic from {SKILL_ROOT}/../shared/docs/copy-versioning.md
2. Read existing {screen-id}.uxm
3. Find highest version (check for {screen-id}-v2, -v3, etc.)
4. Calculate next version: v{N+1}
5. Pass to composer agent with versioning parameters:

• baseScreenId: Original ID (e.g., "login-screen")
• newScreenId: Versioned ID (e.g., "login-screen-v2")
• baseOnExisting: true
• sourceVersion: Highest existing version

1. Composer creates THREE files:

• {screen-id}-v{N+1}.uxm
• {screen-id}-v{N+1}.md
• {screen-id}-v{N+1}.rendered.md

1. Metadata: Increment minor version (1.0.0 → 1.1.0), update modified, preserve created

• Choice (b) - Different name:

1. Ask: "What would you like to name this screen?"
2. Wait for user response
3. Use new name for screen ID
4. Proceed with normal scaffolding

• Choice (c) - Cancel:

1. Do not create any files
2. Inform user: "Operation cancelled. No files were created."
3. Exit workflow

1. If screen DOES NOT exist:

• Proceed with normal scaffolding workflow (no versioning needed)
• Screen will be created as {screen-id}.uxm (no version suffix)
• Initial version: 1.0.0

Workflow Branching: Single vs Multi-Screen

After completing the component inventory, choose the appropriate workflow path:

Path A: Single Screen (1 screen requested)

• Step 3: Create missing components (parallel)
• Step 4: Spawn ONE composer agent
• Step 5: Enhancement

Path B: Multiple Screens (2+ screens requested)

• Step 3: Create missing components across ALL screens (deduplicated, parallel)
• Step 4: Spawn ONE composer agent PER screen (parallel)
• Step 5: Enhancement

Key distinction: Path B spawns N composer agents in parallel (one per screen) instead of one.

Example scenarios:

• "Create a login screen" → Path A (1 screen, 1 composer)
• "Create pages for these 6 screenshots" → Path B (6 screens, 6 composers in parallel)
• "Build dashboard and settings screens" → Path B (2 screens, 2 composers in parallel)

Follow the appropriate path based on screen count. Instructions below apply to Path A (single screen). For Path B modifications, see notes in Steps 3 and 4.

Step 3: Create Missing Components (Fast Mode)

If missing components exist, spawn designer agents in FAST MODE - one agent per component:

CRITICAL ORCHESTRATION RULES:

1. ⚠️ DO NOT create TodoWrite list and work through it yourself
2. ⚠️ DO NOT create components yourself using Write/Edit tools
3. ✅ DO use Task tool to spawn one agent per missing component
4. ✅ DO send ONE message with ALL Task calls (parallel execution)
5. ✅ DO use FAST MODE (creates .uxm only, ✓ ${c}.uxm (sketch fidelity, ~10s)).join('\n')}

Time: ~${missingComponents.length * 10}s

Phase 2: Smart Composition 🎨

Component .md files generated: ${componentList.map(c => ✓ ${c}.md (by composer)).join('\n')}

Screen files created: ✓ ${screenName}.uxm ✓ ${screenName}.md (template) ✓ ${screenName}.rendered.md

Time: ~60-90s

${qualityPreset !== 'fast' ? `

Phase 3: Auto-Enhancement ✨

Components enhanced to ${targetFidelity} fidelity: ${componentList.map(c => ✓ ${c}: sketch → ${targetFidelity}).join('\n')}

Enhancements applied: ${targetFidelity === 'basic' ? '- Improved descriptions\n- Added specific tags\n- Polished ASCII' : ''} ${targetFidelity === 'detailed' ? '- Improved descriptions\n- Added hover + focus states\n- Polished ASCII\n- Added usage examples' : ''} ${targetFidelity === 'production' ? '- All detailed enhancements\n- Added disabled + error states\n- Complete accessibility\n- Pixel-perfect ASCII' : ''}

Screen .rendered.md regenerated with enhanced components

Time: ~${enhancementTime[targetFidelity]}s ` : ''}

Total Time: ~${totalTime}s (${Math.round(totalTime/60)} minutes)

Performance

• Target: ${targetTime[qualityPreset]}
• Actual: ${totalTime}s
• Status: ${totalTime <= targetTime[qualityPreset] ? '✓ ON TARGET' : '⚠ OVER TARGET'}

Files Created

Components (./fluxwing/components/):

• ${componentList.length} .uxm files (${finalFidelity} fidelity)
• ${componentList.length} .md files

Screen (./fluxwing/screens/):

• ${screenName}.uxm
• ${screenName}.md
• ${screenName}.rendered.md

**Total: ${componentList.length 2 + 3} files*

Quality Assessment

• Component fidelity: ${finalFidelity}
• Screen .rendered.md: ${qualityPreset === 'production' ? 'Publication-ready' : qualityPreset === 'detailed' ? 'High quality' : qualityPreset === 'balanced' ? 'Good quality' : 'Basic quality'}
• States included: ${statesCount} states per component
• Accessibility: ${qualityPreset === 'production' ? 'Complete' : qualityPreset === 'detailed' ? 'Good' : 'Basic'}

Next Steps

1. Review rendered screen:

\cat ./fluxwing/screens/${screenName}.rendered.md\

1. Further enhancement (optional):

${qualityPreset !== 'production' ? Use /fluxwing-enhance to upgrade to ${nextFidelity} fidelity : 'Already at maximum fidelity'}

1. Customize components:

Edit ./fluxwing/components/ files as needed

1. View components:

Use /fluxwing-view to inspect individual components

## Parallel Execution Strategy

**Two-phase concurrency model:**

**Phase 1 - Component Creation (Parallel)**:
- If N components are missing → spawn N agents in parallel (one per component)
- All component agents run simultaneously (~Nx faster than sequential)
- Each agent independently creates its component files and tracks progress

**Phase 2 - Screen Composition (Sequential)**:
- After ALL component agents complete → spawn composer agent
- Composer reads all created components and assembles screen
- Cannot run in parallel with Phase 1 (needs components to exist first)

**Performance Example**:
- 6 missing components + screen composition
- Old way (sequential): ~180 seconds (6 × 30s)
- New way (parallel Phase 1): ~30 seconds (6 agents at once) + ~30s composer = ~60 seconds total
- **3x faster!**

## Example Interaction

User: Create a login screen

Skill: I'll help you create a login screen! Let me check what components we have...

[Checks ./fluxwing/components/, ./fluxwing/library/, bundled templates]

I found: ✓ email-input (exists in ./fluxwing/components/) ✗ password-input (needs to be created) ✗ submit-button (needs to be created)

I'll use a two-phase approach:

• Phase 1: Spawn 2 agents in parallel (one per missing component)
• Phase 2: After components complete, spawn composer agent

[Spawns 2 component agents in parallel]

✓ password-input agent completed ✓ submit-button agent completed

[Now spawns composer agent]

✓ Composer agent created login screen

Total: 7 files created in ./fluxwing/ Performance: ~2x faster with parallel component creation!

## Error Handling

**If designer agent fails:**
- Report which components failed
- User can create manually or retry
- Composer agent cannot proceed without components

**If composer agent fails:**
- Components are still created and usable
- User can manually compose screen
- Provide specific error context

## Common Rationalizations That Mean You're Failing

If you catch yourself thinking ANY of these thoughts, STOP. You are rationalizing. Use the Task tool to spawn agents instead.

**About creating files directly:**
- "I'll just create the files directly, it's faster" → WRONG. Spawn agents.
- "Write is simpler than Task for this" → WRONG. You're an orchestrator, not a worker.
- "I'll create .uxm and .md myself, agents can do .rendered later" → WRONG. Agents do ALL 3 files.
- "Let me help by pre-creating some files first" → WRONG. Agents are self-sufficient.
- "The user wants it fast, no time for agents" → WRONG. Parallel agents ARE faster.

**About multi-screen scenarios:**
- "Orchestration is overkill for this batch" → WRONG. Batches are exactly when you orchestrate.
- "I'll do the first screen to show progress" → WRONG. Spawn all agents in parallel.
- "Let me create a todo list and work through screens" → WRONG. TodoWrite + sequential work = slowest path.
- "11 screens is too many for parallel agents" → WRONG. That's the perfect use case.

**About the .rendered.md file:**
- "I'll skip .rendered.md for now" → WRONG. It's the PRIMARY deliverable.
- "Template (.md) is enough" → WRONG. User needs to SEE the actual layout.
- ".rendered.md can be added later" → WRONG. Composer creates it NOW.

**Why these rationalizations happen:**
- Write/Edit tools feel more direct than Task tool
- Creating files yourself feels productive
- Spawning agents feels abstract
- But: You're an ORCHESTRATOR. Your job is coordination, not execution.

**What to do instead:**
1. Detect how many screens are needed
2. Spawn that many composer agents in ONE message
3. Wait for results
4. Report completion

STOP. Use the Task tool. You are an orchestrator, not a worker.

## Success Criteria

- ✓ All required components exist (created or found)
- ✓ Screen has 3 files (.uxm + .md + .rendered.md)
-

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [trabian](https://github.com/trabian)
- **Source:** [trabian/fluxwing-skills](https://github.com/trabian/fluxwing-skills)
- **License:** MIT
- **Homepage:** https://www.fluxwing.com

Install and usage instructions live in the source repository linked above.