Create UI components and screens through natural language using ASCII art and structured metadata. Includes 6 specialized skills for component creation, screen scaffolding, library browsing, state expansion, component viewing, and screenshot importing.

version
0.0.2
GitHub stars
18

Install

/plugin install fluxwing-skills@fluxwing-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add trabian/fluxwing-skills.

Contents

Discovered from source

Skills 8

Fluxwing Component Creator

You are helping the user create uxscii component(s) using the uxscii standard by orchestrating the designer agent.

Data Location Rules

READ from (bundled templates - reference only):

  • {SKILL_ROOT}/templates/ - 11 component templates
  • {SKILL_ROOT}/docs/ - Documentation

INVENTORY sources:

  • ./fluxwing/components/ - User components
  • ./fluxwing/library/ - Customized templates
  • {SKILL_ROOT}/templates/ - Bundled templates (READ-ONLY)

WRITE to (project workspace - via designer agent):

  • ./fluxwing/components/ - Your created components

NEVER write to skill directory - it's read-only!

LOAD for copy-on-update logic:

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

Your Task

Help the user create uxscii component(s) by gathering requirements and spawning designer agent(s).

Supports both single and multi-component creation:

  • Single: "Create a submit button"
  • Multiple: "Create submit-button, cancel-button, and email-input" (agents run in parallel)

Speed Modes

Fluxwing supports two creation modes optimized for different use cases:

Fast Mode (Scaffolding)

When: Scaffolder creates multiple components in parallel Speed: ~10 seconds per component Output: .uxm only (fidelity: sketch) Method: Template-based variable substitution

Fast mode skips:

  • Documentation loading
  • ASCII art generation
  • Detailed metadata

Detailed Mode (Standalone)

When: User explicitly creates single component Speed: ~60-90 seconds per component Output: .uxm + .md (fidelity: detailed) Method: Full docs, careful ASCII generation

Detailed mode includes:

  • Complete documentation reference
  • Hand-crafted ASCII art
  • Rich metadata with examples

Default: Fast mode when called by scaffolder, detailed mode otherwise

Workflow

Step 1: Determine Creation Mode & Parse Request

First, determine creation mode:

Check context to decide fast vs detailed mode:

Use Fast Mode if:

  • Called by scaffolder skill (check for "screen context" in request)
  • User explicitly requests "fast" or "quick" component
  • Creating multiple components (6+ components)

Use Detailed Mode if:

  • User creating single component interactively
  • User requests "detailed" or "production" quality
  • No screen context provided

Default: Detailed mode (safer, better quality)

Then, detect if user wants single or multiple components:

  1. Single component request:

    • "Create a submit button"
    • "I need a card component"
    • Proceed with single-component workflow (Steps 2-4)
  2. Multiple component request:

    • "Create submit-button, cancel-button, and email-input"
    • "I need a button, input, and card"
    • "Create these components: [list]"
    • Proceed with multi-component workflow (see Step 3b)

For each component, gather:

  • Component name (will be converted to kebab-case, e.g., "Submit Button" → "submit-button")
  • Component type: button, input, card, navigation, form, list, modal, table, badge, alert, container, text, image, divider, or custom
  • Key properties: What should be configurable? (text, colors, sizes, etc.)
  • Visual style preferences: rounded, sharp, minimal, detailed, etc.

If details are missing: Make reasonable assumptions based on component type and common patterns. Don't over-ask.

Note: Components are created with default state only for fast MVP prototyping. Users can expand components later to add interactive states (hover, focus, disabled, etc.).

Step 2: Check for Similar Templates

Browse available templates to offer starting points:

// Check bundled templates
const bundledTemplates = glob('{SKILL_ROOT}/templates/*.uxm');
// Check user library
const libraryTemplates = glob('./fluxwing/library/*.uxm');

// Suggest similar templates if found
if (similarTemplates.length > 0) {
  console.log(`Similar templates found: ${similarTemplates.join(', ')}`);
  console.log('Would you like to base this on an existing template or create from scratch?');
}

Step 3: Pre-Creation Validation (Check for Existing Component)

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

For each component you plan to create:

  1. Convert to kebab-case ID:

    "Submit Button" → "submit-button"
    "User Profile Card" → "user-profile-card"
    
  2. Check if component exists:

    # Check for existing component
    test -f ./fluxwing/components/{component-id}.uxm
    
  3. If component EXISTS:

    Inform user and offer choices:

    Component '{component-id}' already exists (version {current-version}).
    
    Options:
    (a) Create new version (copy-on-update: {component-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 {component-id}.uxm
      3. Find highest version (check for {component-id}-v2, -v3, etc.)
      4. Calculate next version: v{N+1}
      5. Pass to designer agent with versioning parameters:
        • baseComponentId: Original ID (e.g., "submit-button")
        • newComponentId: Versioned ID (e.g., "submit-button-v2")
        • baseOnExisting: true
        • sourceVersion: Highest existing version
      6. Designer creates {component-id}-v{N+1}.uxm and .md
      7. 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 component?"
      2. Wait for user response
      3. Use new name for component ID
      4. Proceed with normal creation
    • Choice (c) - Cancel:

      1. Do not create any files
      2. Inform user: "Operation cancelled. No files were created."
      3. Exit workflow
  4. If component DOES NOT exist:

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

For multiple components: Check existence for EACH component individually. Some may need versioning, others may not.

Agent Prompts

Fast Mode Agent (For Scaffolder)

Use this when creating multiple components quickly:

Task({
  subagent_type: "general-purpose",
  // Note: model parameter not yet supported by Task tool
  description: "Create ${componentName} (fast)",
  prompt: `Create sketch-fidelity uxscii component from template.

Component: ${componentName}
Type: ${componentType}
Screen context: ${screenContext}
${baseOnExisting ? `
VERSIONING MODE:
- Base on existing: ${baseComponentId}
- New component ID: ${newComponentId}
- Source version: ${sourceVersion}
- Copy-on-update: Increment minor version, preserve created timestamp
` : ''}

FAST MODE - Speed is critical! <10 seconds target.

Your task:
1. ${baseOnExisting ? `Load existing: ./fluxwing/components/${sourceVersion}.uxm` : `Load minimal template: {SKILL_ROOT}/templates/minimal/${componentType}.uxm.template`}
2. ${baseOnExisting ? `Read current version number and metadata.created timestamp` : `If template not found, FAIL with error: "No template found for type: ${componentType}"`}
3. Replace template variables (component type specific):

   **Common variables (all types):**
   - {{id}} = "${componentId}"
   - {{name}} = "${componentName}"
   - {{description}} = "${description || 'Component for ' + screenContext}"
   - {{timestamp}} = "${new Date().toISOString()}"

   **Component-specific variables:**
   | Type       | Variables                                  |
   |------------|-------------------------------------------|
   | button     | {{label}}, {{variant}}                    |
   | input      | {{placeholder}}, {{type}}, {{value}}      |
   | text       | {{content}}, {{align}}                    |
   | heading    | {{text}}, {{level}}                       |
   | card       | {{title}}, {{content}}                    |
   | modal      | {{title}}, {{content}}                    |
   | container  | {{content}}, {{direction}}                |
   | navigation | {{items}}, {{orientation}}                |
   | form       | {{fields}}, {{action}}                    |
   | table      | {{headers}}, {{rows}}                     |
   | list       | {{items}}, {{type}}                       |

   Use component name as default value if variable not provided.

4. CRITICAL: Set metadata.fidelity = "sketch"

   **REQUIRED FIELD**: The fidelity field is MANDATORY in the schema and tracks progressive enhancement.
   Fast mode MUST set fidelity to "sketch" to indicate initial scaffolding quality.

   This field enables progressive fidelity workflow:
   - sketch (fast mode) → basic → detailed → production

5. ${baseOnExisting ? `Update version metadata:
   - id: "${newComponentId}" (versioned ID)
   - version: Increment minor from source (e.g., 1.0.0 → 1.1.0)
   - metadata.created: PRESERVE from ${sourceVersion}
   - metadata.modified: SET to current timestamp
` : `Verify JSON is well-formed (quick syntax check)`}
6. Save to ./fluxwing/components/${componentId}.uxm
7. DO NOT create .md file
8. DO NOT load documentation
9. DO NOT generate ASCII art

VERIFICATION CHECKLIST:
- [ ] metadata.fidelity field is set to "sketch"
- [ ] All required fields are present (name, description, created, modified, tags, category, fidelity)
- [ ] JSON is valid and well-formed

Return message: "Created ${componentId}.uxm (sketch fidelity)"

Target: <10 seconds
`
})

Detailed Mode Agent (For User)

Use this when creating single component with full quality:

Task({
  subagent_type: "general-purpose",
  // Note: model parameter not yet supported by Task tool
  description: "Create ${componentName} (detailed)",
  prompt: `Create production-ready uxscii component with full documentation.

Component: ${componentName}
Type: ${componentType}
${baseOnExisting ? `
VERSIONING MODE:
- Base on existing: ${baseComponentId}
- New component ID: ${newComponentId}
- Source version: ${sourceVersion}
- Copy-on-update: Increment minor version, preserve created timestamp
` : ''}

DETAILED MODE - Quality is priority.

Your task:
1. ${baseOnExisting ? `Load existing: ./fluxwing/components/${sourceVersion}.uxm` : `Load schema: {SKILL_ROOT}/schemas/uxm-component.schema.json`}
2. ${baseOnExisting ? `Read copy-versioning docs: {SKILL_ROOT}/../shared/docs/copy-versioning.md` : `Load docs: {SKILL_ROOT}/docs/03-component-creation.md`}
3. Load ASCII patterns: {SKILL_ROOT}/docs/06-ascii-patterns.md
4. Create rich .uxm with:
   - Detailed metadata.description
   - Relevant tags
   - Complete props with examples
   - Default + hover states
   - Full accessibility metadata

5. CRITICAL: Set metadata.fidelity = "detailed"

   **REQUIRED FIELD**: The fidelity field is MANDATORY in the schema and tracks progressive enhancement.
   Detailed mode MUST set fidelity to "detailed" to indicate high-quality production-ready components.

   This field enables progressive fidelity workflow:
   - sketch → basic → detailed (detailed mode) → production

6. ${baseOnExisting ? `Update version metadata:
   - id: "${newComponentId}" (versioned ID with -v{N} suffix)
   - version: Increment minor from source (e.g., 1.0.0 → 1.1.0)
   - metadata.created: PRESERVE from ${sourceVersion}
   - metadata.modified: SET to current timestamp
   - metadata.fidelity: Update if enhancing (preserve or upgrade)
` : `Verify JSON is well-formed`}

7. Create polished .md with:
   - Clean ASCII art using box-drawing characters
   - All variables documented
   - State examples
   - ${baseOnExisting ? `Filename: ${newComponentId}.md (versioned)` : `Filename: ${componentId}.md`}

8. Validate against schema
9. Save both files to ./fluxwing/components/
   - ${baseOnExisting ? `${newComponentId}.uxm and ${newComponentId}.md` : `${componentId}.uxm and ${componentId}.md`}

VERIFICATION CHECKLIST:
- [ ] metadata.fidelity field is set to "detailed"
- [ ] All required fields are present (name, description, created, modified, tags, category, fidelity)
- [ ] Both .uxm and .md files are created
- [ ] ${baseOnExisting ? `Version incremented and ID has -v{N} suffix` : `Component ID is kebab-case`}
- [ ] ${baseOnExisting ? `metadata.created preserved from source` : `metadata.created set to current timestamp`}
- [ ] JSON is valid and well-formed

Return: Component summary with preview ${baseOnExisting ? `- Mention version created` : ``}

Target: 60-90 seconds
`
})

Step 3a: Spawn Designer Agent (Single Component)

For SINGLE component requests, spawn one designer agent:

Task({
  subagent_type: "general-purpose",
  description: "Create single uxscii component",
  prompt: `You are a uxscii component designer creating production-ready components.

Component requirements:
- Name: ${componentName}
- Type: ${componentType}
- Key properties: ${keyProperties}
- Visual style: ${visualStyle}

Your task:
1. Load schema from {SKILL_ROOT}/schemas/uxm-component.schema.json
2. Load documentation from {SKILL_ROOT}/docs/03-component-creation.md and 06-ascii-patterns.md
3. Check {SKILL_ROOT}/templates/ for similar examples
4. Create .uxm file (valid JSON with default state only)
5. Create .md file (ASCII template with default state only)
6. Save both files to ./fluxwing/components/
7. Validate using: node {SKILL_ROOT}/../fluxwing-validator/validate-component.js ./fluxwing/components/${componentId}.uxm {SKILL_ROOT}/schemas/uxm-component.schema.json
8. Use TodoWrite to track progress
9. Return component summary with ASCII preview

Component creation guidelines:
- Create default state only for fast MVP prototyping
- Use consistent box-drawing characters (see docs/06-ascii-patterns.md)
- Include complete accessibility attributes (ARIA roles, keyboard support)
- Follow naming conventions: kebab-case IDs, camelCase variables
- Ensure all template variables in .md are defined in .uxm props
- Keep ASCII dimensions reasonable (width: 1-120, height: 1-50)

Data locations:
- READ templates from: {SKILL_ROOT}/templates/ (reference only)
- WRITE components to: ./fluxwing/components/ (your output)
- NEVER write to skill directory

Follow the uxscii standard strictly for production quality.`
})

Wait for designer agent to complete.

Step 3b: Spawn Designer Agents (Multiple Components - IN PARALLEL)

For MULTIPLE component requests, spawn ALL designer agents in a SINGLE message for maximum parallelism:

CRITICAL: You MUST send ONE message with multiple Task calls to achieve parallel execution.

DO THIS: One message with N Task calls (one per component) DON'T DO THIS: Separate messages for each component (runs sequentially)

// Example: User wants submit-button, cancel-button, email-input

Task({
  subagent_type: "general-purpose",
  description: "Create submit-button component",
  prompt: `You are a uxscii component designer creating production-ready components.

Component requirements:
- Name: submit-button
- Type: button
- Key properties: text, variant
- Visual style: rounded, filled

Your task:
1. Load schema from {SKILL_ROOT}/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/03-component-creation.md and 06-ascii-patterns.md
3. Create .uxm file (valid JSON with default state only)
4. Create .md file (ASCII template with default state only)
5. Save to ./fluxwing/components/
6. Validate using: node {SKILL_ROOT}/../fluxwing-validator/validate-component.js
7. Return component summary

Follow uxscii standard strictly. Create default state only for fast MVP.`
})

Task({
  subagent_type: "general-purpose",
  description: "Create cancel-button component",
  prompt: `You are a uxscii component designer creating production-ready components.

Component requirements:
- Name: cancel-button
- Type: button
- Key properties: text, variant
- Visual style: rounded, outlined

Your task:
1. Load schema from {SKILL_ROOT}/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/03-component-creation.md and 06-ascii-patterns.md
3. Create .uxm file (valid JSON with default state only)
4. Create .md file (ASCII template with default state only)
5. Save to ./fluxwing/components/
6. Validate using: node {SKILL_ROOT}/../fluxwing-validator/validate-component.js
7. Return component summary

Follow uxscii standard strictly. Create default state only for fast MVP.`
})

Task({
  subagent_type: "general-purpose",
  description: "Create email-input component",
  prompt: `You are a uxscii component designer creating production-ready components.

Component requirements:
- Name: email-input
- Type: input
- Key properties: placeholder, value
- Visual style: light border, minimal

Your task:
1. Load schema from {SKILL_ROOT}/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/03-component-creation.md and 06-ascii-patterns.md
3. Create .uxm file (valid JSON with default state only)
4. Create .md file (ASCII template with default state only)
5. Save to ./fluxwing/components/
6. Validate using: node {SKILL_ROOT}/../fluxwing-validator/validate-component.js
7. Return component summary

Follow uxscii standard strictly. Create default state only for fast MVP.`
})

... all Task calls in the SAME message for parallel execution ...

Wait for ALL designer agents to complete.

Performance Benefit: Creating 3 components in parallel is ~3x faster than sequential creation!

Step 3c: Validate Created Components (Optional but Recommended)

After the designer agent(s) complete, validate the created components using the fast validation script:

# For single component
node {SKILL_ROOT}/../fluxwing-validator/validate-component.js \\
  ./fluxwing/components/${componentId}.uxm \\
  {SKILL_ROOT}/schemas/uxm-component.schema.json

# For multiple components, validate each one
node {SKILL_ROOT}/../fluxwing-validator/validate-component.js \\
  ./fluxwing/components/submit-button.uxm \\
  {SKILL_ROOT}/schemas/uxm-component.schema.json

node {SKILL_ROOT}/../fluxwing-validator/validate-component.js \\
  ./fluxwing/components/cancel-button.uxm \\
  {SKILL_ROOT}/schemas/uxm-component.schema.json

Validation output:

  • ✓ If valid: Shows component summary (type, states, props)
  • ✗ If invalid: Shows specific errors that need fixing

Performance: ~80ms per component (very fast!)

If validation fails:

  1. Read the error messages carefully
  2. Fix the issues in the .uxm or .md files
  3. Re-validate before reporting to user

Note: The validation script checks:

  • JSON schema compliance
  • .md file exists
  • Variables match between .uxm and .md
  • Accessibility requirements
  • Dimension constraints

Step 4: Report Success

For SINGLE component, present the results:

# Component Created ✓

## ${componentName}

**Type**: ${componentType}
**Files**:
- ./fluxwing/components/${componentId}.uxm
- ./fluxwing/components/${componentId}.md

**States**: default (created)
**Detected states**: ${detectedStates.join(', ')}

## Preview

${asciiPreview}

## Next Steps

1. Add interaction states using the component expander skill
2. Use in a screen with the screen scaffolder skill
3. View all components with the library browser skill
4. Customize: Edit files in ./fluxwing/components/

For MULTIPLE components, present a summary:

# Components Created ✓

Created ${componentCount} components in parallel:

## submit-button (button)
**Files**:
- ./fluxwing/components/submit-button.uxm
- ./fluxwing/components/submit-button.md

**Preview**:
╭──────────────────╮
│   Submit Form    │
╰──────────────────╯

## cancel-button (button)
**Files**:
- ./fluxwing/components/cancel-button.uxm
- ./fluxwing/components/cancel-button.md

**Preview**:
┌──────────────────┐
│   Cancel         │
└──────────────────┘

## email-input (input)
**Files**:
- ./fluxwing/components/email-input.uxm
- ./fluxwing/components/email-input.md

**Preview**:
┌────────────────────────────┐
│ Email: [________________]  │
└────────────────────────────┘

---

**Total**: 6 files created (3 .uxm + 3 .md)
**Performance**: Created in parallel (~3x faster than sequential)

## Next Steps

1. Add interaction states to components
2. Use components in screens
3. View all components
4. Customize: Edit files in ./fluxwing/components/

Example Interactions

Example 1: Single Component

User: Create a submit button

Skill: I'll create a submit button component! Let me check for similar templates...

[Checks bundled templates]

I found a primary-button template. Would you like me to:
1. Base it on the primary-button template (faster)
2. Create a custom design from scratch

[User responds: custom, rounded corners, filled]

Perfect! Creating submit-button component with the designer agent...

[Spawns designer agent]

✓ Component created successfully!

Files:
- ./fluxwing/components/submit-button.uxm
- ./fluxwing/components/submit-button.md

Preview (default state):
╭──────────────────╮
│   Submit Form    │
╰──────────────────╯

Next steps:
- Add states: Ask me to "add hover state to submit-button"
- Use in screen: Ask me to "create a login screen"

Example 2: Multiple Components (Parallel)

User: Create submit-button, cancel-button, and email-input

Skill: I'll create all 3 components in parallel! This will be much faster.

Based on the component types, I'll use these defaults:
- submit-button: button type, rounded, filled style
- cancel-button: button type, rounded, outlined style
- email-input: input type, light border, minimal style

[Spawns 3 designer agents in a SINGLE message]

✓ All 3 components created successfully in parallel!

## submit-button (button)
Files: submit-button.uxm + submit-button.md

## cancel-button (button)
Files: cancel-button.uxm + cancel-button.md

## email-input (input)
Files: email-input.uxm + email-input.md

Total: 6 files created
Performance: ~3x faster than sequential creation

Next steps:
- Add states to components
- Use in a screen
- View all components

Benefits of Using Designer Agent

  • Consistent quality: Agent follows quality standards
  • Complete metadata: Proper tags, descriptions, accessibility
  • Best practices: Schema compliance, naming conventions
  • Reusable logic: Same creation workflow across all skills
  • Parallel execution: Multiple components created simultaneously (not sequentially)

Performance Benefits

Single vs Multi-Component Creation:

  • Sequential (old): Component 1 → wait → Component 2 → wait → Component 3

    • Time: 3 × agent_time
  • Parallel (new): Component 1 + Component 2 + Component 3 → all at once

    • Time: 1 × agent_time (3x faster!)

When to use multi-component creation:

  • Creating multiple components for a single screen (e.g., login form components)
  • Building a component library in bulk
  • Prototyping quickly with several variations

Example speedup:

  • 1 component: ~30 seconds
  • 3 components sequential: ~90 seconds
  • 3 components parallel: ~30 seconds (3x faster!) ⚡

Error Handling

If single designer agent fails:

  • Report specific error from agent
  • Suggest fixes or alternatives
  • User can retry with adjusted requirements

If multiple designer agents fail:

  • Report which components succeeded and which failed
  • Keep successfully created components (partial success is OK)
  • User can retry failed components individually or as a group

Example partial failure:

✓ submit-button created successfully
✓ cancel-button created successfully
✗ email-input failed: Invalid component type specified

2 of 3 components created. You can:
1. Retry email-input with corrected parameters
2. Use the 2 successful components as-is
3. Manually create email-input

Success Criteria

For single component:

  • ✓ Designer agent created component successfully
  • ✓ Both .uxm and .md files exist in ./fluxwing/components/
  • ✓ Component follows uxscii standard
  • ✓ User can immediately use or expand the component

For multiple components:

  • ✓ All designer agents launched in parallel (single message)
  • ✓ Each component has both .uxm and .md files in ./fluxwing/components/
  • ✓ All components follow uxscii standard
  • ✓ Clear report showing which succeeded/failed (if any failures)
  • ✓ User can immediately use all successful components

You are helping build AI-native designs with production-quality components at maximum speed!

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 compliance
  • ✓ All states have valid properties
  • ✓ Variables match between .uxm and .md
  • ✓ Accessibility requirements met
  • ✓ No duplicate states

If validation fails:

  1. Read the error messages
  2. Fix the issues in the .uxm or .md files
  3. 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!

Fluxwing Component Viewer

View detailed information about a specific uxscii component from any source.

Data Location Rules

READ from (bundled templates - reference only):

  • {SKILL_ROOT}/../uxscii-component-creator/templates/ - 11 component templates
  • {SKILL_ROOT}/../uxscii-screen-scaffolder/templates/ - 2 screen examples (if available)

READ from (project workspace):

  • ./fluxwing/components/ - Your created components
  • ./fluxwing/library/ - Customized template copies
  • ./fluxwing/screens/ - Your created screens

NEVER write - this is a read-only viewer!

Your Task

Display comprehensive details about a single uxscii component, including metadata, ASCII template preview, and context-appropriate actions.

Component Lookup Process

1. Parse Component Name

  • Extract component name from user request
  • If no name provided: Ask "Which component would you like to view?"
  • Normalize name to lowercase with hyphens

2. Search Priority Order (Stop at First Match)

Search these locations in order and stop at the first match:

  1. Project Components: ./fluxwing/components/[name].uxm

    • User/agent-created custom components
    • Fully editable
    • Tag as: "Your Component"
  2. Project Library: ./fluxwing/library/[name].uxm

    • Customized copies of bundled templates
    • Fully editable
    • Tag as: "Your Library"
  3. Bundled Templates: {SKILL_ROOT}/../uxscii-component-creator/templates/[name].uxm

    • Read-only reference templates
    • Must be copied to edit
    • Tag as: "Bundled Template"

Important: Stop searching after first match. If found in bundled templates, check if it also exists in user's project and add a note: "💡 You also have a customized version in ./fluxwing/library/"

3. Read Component Files

For the matched component, read both files:

  • [name].uxm - JSON metadata
  • [name].md - ASCII template

Display Format

Concise View (Default)

Present component information in a clean, scannable format:

📄 PRIMARY-BUTTON
─────────────────────────────────────────────────────
📦 Source: Bundled Template
📍 Location: Component Creator Templates
⏱️  Modified: 2024-10-11 10:30:00
🔖 Version: 1.0.0

Description:
Standard clickable button with hover, focus, and disabled states

Component Details:
• Type: button
• Props: text (string), variant (string), disabled (boolean)
• States: default, hover, focus, disabled
• Accessibility: ✓ Role (button), ✓ Focusable, ✓ Keyboard (Space, Enter)

ASCII Template Preview (first 20 lines):

Default State:
▓▓▓▓▓▓▓▓▓▓▓▓
▓ {{text}} ▓
▓▓▓▓▓▓▓▓▓▓▓▓

Hover State:
░▓▓▓▓▓▓▓▓▓▓▓░
░▓ {{text}} ▓░
░▓▓▓▓▓▓▓▓▓▓░

Disabled State:
┌ ─ ─ ─ ─ ─┐
│ {{text}} │
└ ─ ─ ─ ─ ─┘

[... 1 more state]

Template has 4 states total. View full template?
─────────────────────────────────────────────────────

Format Guidelines

Header Section:

  • Component name in CAPS
  • Emoji indicators:
    • 📦 = Bundled Template
    • ✏️ = Your Library
    • 🎨 = Your Component
  • Full file path for clarity
  • Last modified timestamp (if available)
  • Version from metadata

Description:

  • Use the metadata.description field from .uxm file
  • Keep it concise (1-2 lines)

Component Details:

  • Type: Direct from .uxm type field
  • Props: List prop names with types in parentheses
    • Format: propName (type)
    • Example: text (string), disabled (boolean)
  • States: Comma-separated list of state names
  • Accessibility: Show checkmarks for present features
    • Role, Focusable, Keyboard shortcuts, ARIA labels

ASCII Template Preview:

  • Show first 20 lines by default
  • If template has multiple states, show state labels
  • If template exceeds 20 lines, add: [... N more states/lines]
  • Preserve exact spacing and box-drawing characters
  • Show variables as {{variableName}}

Truncation Logic

If .md template exceeds 20 lines:

  1. Count total states/sections in template
  2. Show first 2-3 states completely
  3. Add summary line: [... N more states]
  4. Offer: "View full template?" as interactive option

Interactive Options

After displaying the component, offer context-appropriate actions:

For Bundled Templates (read-only)

What would you like to do?

1️⃣ Copy to project library (makes it editable)
2️⃣ View full template file (all states)
3️⃣ View full metadata (complete .uxm)
4️⃣ Browse all components

Action Details:

  • Copy: Copy both .uxm and .md to ./fluxwing/library/
  • View full template: Display complete .md file (no truncation)
  • View full metadata: Display complete .uxm JSON
  • Browse: Return to library browser

For Project Files (./fluxwing/library/ or ./fluxwing/components/)

What would you like to do?

1️⃣ Edit component (modify .uxm and .md)
2️⃣ View full template file (all states)
3️⃣ View full metadata (complete .uxm)
4️⃣ Delete component (manual: remove files from filesystem)
5️⃣ Browse all components

Action Details:

  • Edit: Open both .uxm and .md for editing
  • Delete: Don't automatically delete - instruct user:
    To delete this component, remove these files from your filesystem:
      • ./fluxwing/components/[name].uxm
      • ./fluxwing/components/[name].md
    

Error Handling

No Component Name Provided

Which component would you like to view?

Example:
  "Show me primary-button"
  "View details for user-card"

View all available components: Ask me to "show me all components"

Component Not Found

✗ Component '[name]' not found.

Searched in:
- ./fluxwing/components/
- ./fluxwing/library/
- Bundled templates

Available components:
[List first 10 components found]

Did you mean one of these?
- primary-button
- submit-button
- user-card

Fuzzy search: If component name is close to an existing component, suggest it:

✗ Component 'primry-button' not found.

Did you mean 'primary-button'?

File Read Errors

✗ Found component but couldn't read files.

Location: ./fluxwing/components/[name].uxm
Error: [specific error message]

Please check file permissions and try again.

Example Interactions

Example 1: View Bundled Template

User: Show me the primary-button

Skill: 📄 PRIMARY-BUTTON
─────────────────────────────────────────────────────
📦 Source: Bundled Template
📍 Location: Component Creator Templates

Description:
Standard clickable button with hover, focus, and disabled states

Component Details:
• Type: button
• Props: text (string), variant (string), disabled (boolean)
• States: default, hover, focus, disabled
• Accessibility: ✓ Full support

[ASCII preview shown...]

What would you like to do?
1️⃣ Copy to project library
2️⃣ View full template
3️⃣ View metadata
4️⃣ Browse all components

Example 2: View User Component

User: What's in my submit-button component?

Skill: 📄 SUBMIT-BUTTON
─────────────────────────────────────────────────────
🎨 Source: Your Component
📍 Location: ./fluxwing/components/submit-button.uxm
⏱️  Modified: 2024-10-15 14:23:00

Description:
Custom submit button for forms

Component Details:
• Type: button
• Props: text (string)
• States: default
• Accessibility: ✓ Basic support

[ASCII preview shown...]

💡 Tip: Add more states with "expand submit-button with hover and disabled"

Resources

  • Core Concepts: See {SKILL_ROOT}/docs/02-core-concepts.md for component fundamentals

You're helping users understand their uxscii components in detail!

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!

Fluxwing Library Browser

Browse all available uxscii components: bundled templates, user-created components, and complete screens.

Data Location Rules

READ from (bundled templates - reference only):

  • {SKILL_ROOT}/../uxscii-component-creator/templates/ - 11 component templates
  • {SKILL_ROOT}/../uxscii-screen-scaffolder/templates/ - 2 screen examples (if available)
  • {SKILL_ROOT}/docs/ - Documentation

READ from (project workspace):

  • ./fluxwing/components/ - Your created components
  • ./fluxwing/screens/ - Your created screens
  • ./fluxwing/library/ - Customized template copies

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

Your Task

Show the user what uxscii components are available across four sources:

  1. Bundled Templates - 11 curated examples from skill templates (read-only reference)
  2. Project Components - User/agent-created reusable components in ./fluxwing/components/ (editable)
  3. Project Library - Customized template copies in ./fluxwing/library/ (editable)
  4. Project Screens - Complete screen compositions in ./fluxwing/screens/ (editable)

Key Distinction: Bundled templates are READ-ONLY reference materials. To customize them, copy to your project workspace first.

Fast Browsing with Pre-Built Index

IMPORTANT: Use the pre-built template index for instant browsing (10x faster than globbing):

// Load the pre-built index (1 file read = instant results!)
const index = JSON.parse(read('{SKILL_ROOT}/data/template-index.json'));

// Browse by type
const buttons = index.by_type.button; // ["primary-button", "secondary-button"]
const inputs = index.by_type.input; // ["email-input"]

// Search by tag
const formComponents = index.by_tag.form; // All form-related components
const interactiveComponents = index.by_tag.interactive; // All interactive components

// Get component info instantly (no file reads needed!)
const buttonInfo = index.bundled_templates.find(t => t.id === "primary-button");
console.log(buttonInfo.name); // "Primary Button"
console.log(buttonInfo.description); // Full description
console.log(buttonInfo.preview); // ASCII preview already extracted!
console.log(buttonInfo.states); // ["default", "hover", "active", "disabled"]
console.log(buttonInfo.props); // ["text", "variant", "size"]
console.log(buttonInfo.tags); // ["button", "primary", "action", "interactive"]

Performance Benefits:

  • ✅ 1 file read vs 11+ file reads (10x faster!)
  • ✅ Instant type/tag filtering (no parsing needed)
  • ✅ Pre-extracted ASCII previews (show immediately)
  • ✅ Metadata summary (no JSON parsing per component)

Index Structure:

{
  "version": "1.0.0",
  "generated": "2025-10-18T12:00:00Z",
  "template_count": 11,
  "bundled_templates": [ /* array of component metadata */ ],
  "by_type": { /* components grouped by type */ },
  "by_tag": { /* components grouped by tags */ }
}

When to use full file reads:

  • User requests detailed view of a specific component
  • User wants to copy a template (need full .uxm and .md content)
  • User searches for a very specific property not in the index

Display Format

Present in a clear, hierarchical structure:

🎁 BUNDLED TEMPLATES
📁 Component Creator Templates
─────────────────────────────────────────────────────
These are starter templates you can copy and customize.

Buttons (2 variants)
  ├─ primary-button.uxm
  │  └─ Standard clickable button with hover, focus, and disabled states
  │     ▓▓▓▓▓▓▓▓▓▓▓▓
  │     ▓ Click Me ▓
  │     ▓▓▓▓▓▓▓▓▓▓▓▓
  │
  └─ icon-button.uxm
     └─ Button with icon support for visual emphasis
        [🔍 Search]

Inputs (2 variants)
  ├─ text-input.uxm
  │  └─ Basic text input with validation states
  │     [________________]
  │
  └─ email-input.uxm
     └─ Email-specific input with format validation
        [user@example.com  ]

Cards (1 variant)
  └─ card.uxm
     └─ Container for grouping related content
        ╭─────────────╮
        │ Card Title  │
        ├─────────────┤
        │ Content...  │
        ╰─────────────╯

Modals (1 variant)
  └─ modal.uxm
     └─ Overlay dialog for focused interactions
        ╔═══════════════╗
        ║ Modal Title   ║
        ╠═══════════════╣
        ║ Content...    ║
        ╚═══════════════╝

Navigation (1 variant)
  └─ navigation.uxm
     └─ Primary navigation menu
        • Home  • About  • Contact

Feedback (2 variants)
  ├─ alert.uxm
  │  └─ User notification with severity levels
  │     ⚠️ Warning: Action required
  │
  └─ badge.uxm
     └─ Small status indicator or label
        ● New

Lists (1 variant)
  └─ list.uxm
     └─ Vertical list for displaying data
        • Item 1
        • Item 2
        • Item 3

─────────────────────────────────────────────────────

🎨 YOUR COMPONENTS
📁 ./fluxwing/components/
─────────────────────────────────────────────────────
Components you've created for your project.

✓ submit-button.uxm
  └─ Custom submit button for forms
     Modified: 2024-10-11 14:23:00
     [    Submit Form    ]

✓ password-input.uxm
  └─ Password input with show/hide toggle
     Modified: 2024-10-11 14:25:00
     [••••••••] 👁️

✓ user-card.uxm
  └─ Card displaying user profile information
     Modified: 2024-10-11 15:10:00
     ╭──────────────────╮
     │ John Doe         │
     │ @johndoe         │
     ╰──────────────────╯

─────────────────────────────────────────────────────

🖥️ YOUR SCREENS
📁 ./fluxwing/screens/
─────────────────────────────────────────────────────
Complete screen compositions.

✓ login-screen.uxm
  └─ User authentication screen
     Components used: email-input, password-input, submit-button, error-alert
     Modified: 2024-10-11 15:45:00

✓ dashboard.uxm
  └─ Main application dashboard
     Components used: navigation, metric-card, data-table, sidebar
     Modified: 2024-10-11 16:20:00

─────────────────────────────────────────────────────
Total: 10 templates, 3 components, 2 screens

Interactive Options

After displaying the library, offer these actions:

What would you like to do?

1️⃣ View component details (ask me to "show me [name]")
2️⃣ Copy a template to your project
3️⃣ Create a new component (ask me to "create a [type]")
4️⃣ Scaffold a new screen (ask me to "build a [screen type] screen")
5️⃣ Search for a specific pattern (e.g., "button", "input", "card")

Detailed View

If user wants to see details of a specific component:

User: Show me primary-button

You: 📄 PRIMARY-BUTTON.UXM
─────────────────────────────────────────────────────
ID: primary-button
Type: button
Version: 1.0.0
Description: Standard clickable button with hover, focus, and disabled states

Props:
  - text: "Click me"
  - variant: "primary"
  - disabled: false

States:
  - default (solid border, white background)
  - hover (highlighted background)
  - focus (outline indicator)
  - disabled (grayed out)

Accessibility:
  - Role: button
  - Focusable: true
  - Keyboard: Space, Enter

ASCII Preview:

Default State:
▓▓▓▓▓▓▓▓▓▓▓▓
▓ Click Me ▓
▓▓▓▓▓▓▓▓▓▓▓▓

Hover State:
█████████████
█ Click Me █
█████████████

Location: {SKILL_ROOT}/../uxscii-component-creator/templates/primary-button.uxm

To customize: Copy to ./fluxwing/library/ for editing

Copy Template to Project

If user wants to customize a bundled template:

User: Copy primary-button to my project

You: I'll copy primary-button to your library for customization.

[Copies .uxm and .md files]

✓ Copied to ./fluxwing/library/
  - primary-button.uxm
  - primary-button.md

You can now edit these files safely. Changes won't affect the original template.

Next steps:
- Edit: Modify ./fluxwing/library/primary-button.uxm
- Expand: Ask me to "add hover state to primary-button"
- Use: Reference it in screens or other components

Search Functionality

Support component search:

User: Find all button components

You: Found 3 button components:

🎁 Bundled Templates:
  - primary-button.uxm (standard clickable button)
  - icon-button.uxm (button with icon support)

🎨 Your Components:
  - submit-button.uxm (custom submit button for forms)

Would you like details on any of these?

Empty Library Handling

If user has no components yet:

🎁 BUNDLED TEMPLATES
📁 Component Creator Templates
─────────────────────────────────────────────────────
11 starter templates available

🎨 YOUR COMPONENTS
📁 ./fluxwing/components/
─────────────────────────────────────────────────────
No components yet. Create your first component!

Try: "Create a submit button" or "Create an email input"

🖥️ YOUR SCREENS
📁 ./fluxwing/screens/
─────────────────────────────────────────────────────
No screens yet. Scaffold your first screen!

Try: "Build a login screen" or "Create a dashboard"

─────────────────────────────────────────────────────
Total: 11 templates, 0 components, 0 screens

Resources

  • Examples Guide: See {SKILL_ROOT}/docs/07-examples-guide.md for detailed template documentation
  • Component Creator: Use when you want to create new components
  • Screen Scaffolder: Use when you want to build complete screens
  • Component Viewer: Use for detailed component information

Important Notes

  1. Read-only templates: Bundled templates cannot be modified directly
  2. Copy before customize: Copy templates to ./fluxwing/library/ to customize
  3. Search: Use Glob and Grep to find components by name or pattern
  4. Organization: Keep components in ./fluxwing/components/, customized templates in ./fluxwing/library/
  5. Screens: Screen files include .uxm, .md, and .rendered.md (three files)

You're helping users discover and navigate their uxscii component library!

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"
    
  2. Check if screen exists:

    # Check for existing screen
    test -f ./fluxwing/screens/{screen-id}.uxm
    
  3. 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
      6. Composer creates THREE files:
        • {screen-id}-v{N+1}.uxm
        • {screen-id}-v{N+1}.md
        • {screen-id}-v{N+1}.rendered.md
      7. 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
  4. 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, <10s per component)

Path B (Multi-screen): Component Deduplication

When creating components for multiple screens:

  1. Inventory ALL screens first: Collect component requirements from all N screens
  2. Deduplicate: Create a unique list of missing components
    • Example: 6 screens might need sidebar-nav, but create it only once
    • Shared components across screens = created once, reused everywhere
  3. Spawn one agent per UNIQUE component: Not one per screen × component

Example:

  • Screen 1 needs: [sidebar-nav, button-primary, input-email]
  • Screen 2 needs: [sidebar-nav, button-primary, input-password]
  • Screen 3 needs: [sidebar-nav, card-metric]

Don't spawn: 3 × 3 = 9 agents (wasteful duplicates) Do spawn: 5 unique agents (sidebar-nav, button-primary, input-email, input-password, card-metric)

Fast Mode Creates:

  • Component .uxm files (sketch fidelity)
  • NO .md files (composer will create these)

Example: 6 missing components for banking-chat

Task({
  subagent_type: "general-purpose",
  model: "haiku", // Fast model
  description: "Create message-bubble (fast)",
  prompt: "Create sketch-fidelity uxscii component from template.

Component: message-bubble
Type: container
Screen context: banking-chat

FAST MODE - Speed is critical! <10 seconds target.

Your task:
1. Load minimal template: {SKILL_ROOT}/../fluxwing-component-creator/templates/minimal/container.uxm.template
2. Replace variables:
   - {{id}} = 'message-bubble'
   - {{name}} = 'Message Bubble'
   - {{description}} = 'Chat message container for banking-chat'
   - {{timestamp}} = '${new Date().toISOString()}'
   - {{screenContext}} = 'banking-chat'

3. CRITICAL: Set metadata.fidelity = "sketch"

   **REQUIRED FIELD**: The fidelity field is MANDATORY in the schema and tracks progressive enhancement.
   Fast mode MUST set fidelity to "sketch" to indicate initial scaffolding quality.

4. Verify JSON is well-formed
5. Save to ./fluxwing/components/message-bubble.uxm
6. DO NOT create .md file
7. DO NOT load documentation

VERIFICATION:
- [ ] metadata.fidelity = "sketch"
- [ ] All required fields present (name, description, created, modified, tags, category, fidelity)

Return: 'Created message-bubble.uxm (sketch fidelity)'

Target: <10 seconds"
})

Task({
  subagent_type: "general-purpose",
  model: "haiku",
  description: "Create message-input (fast)",
  prompt: "Create sketch-fidelity uxscii component from template.

Component: message-input
Type: input
Screen context: banking-chat

FAST MODE - Speed is critical! <10 seconds target.

Your task:
1. Load minimal template: {SKILL_ROOT}/../fluxwing-component-creator/templates/minimal/input.uxm.template
2. Replace variables:
   - {{id}} = 'message-input'
   - {{name}} = 'Message Input'
   - {{description}} = 'Chat input field for banking-chat'
   - {{timestamp}} = '${new Date().toISOString()}'
   - {{placeholder}} = 'Type a message...'
   - {{label}} = 'Message'
   - {{screenContext}} = 'banking-chat'

3. CRITICAL: Set metadata.fidelity = "sketch"

   **REQUIRED FIELD**: The fidelity field is MANDATORY in the schema and tracks progressive enhancement.
   Fast mode MUST set fidelity to "sketch" to indicate initial scaffolding quality.

4. Verify JSON is well-formed
5. Save to ./fluxwing/components/message-input.uxm
6. DO NOT create .md file
7. DO NOT load documentation

VERIFICATION:
- [ ] metadata.fidelity = "sketch"
- [ ] All required fields present (name, description, created, modified, tags, category, fidelity)

Return: 'Created message-input.uxm (sketch fidelity)'

Target: <10 seconds"
})

// ... spawn ONE Task per missing component in SAME message ...

Performance: 6 components × 10s = ~60 seconds (was 120-180s)

Wait for ALL component agents to complete before Step 4.

Step 4: Compose Screen with Component .md Generation

Once all components exist, spawn the composer agent:

Path A (Single Screen): Spawn ONE composer agent Path B (Multi-screen): Spawn ONE composer agent PER screen (parallel)

Example Path B:

  • 6 screens requested → spawn 6 composer agents in ONE message
  • Each agent creates 3 files for its assigned screen (.uxm, .md, .rendered.md)
  • All 6 agents run in parallel (~90s total, not 540s sequential)
  • Result: 18 files (6 screens × 3 files)

CRITICAL: Composer generates .md files for ALL components!

This is the "smart composer" - it:

  1. Generates missing component .md files
  2. Loads documentation ONCE (not per component)
  3. Creates screen .uxm + .md + .rendered.md
  4. Focuses quality on .rendered.md (main deliverable)
Task({
  subagent_type: "general-purpose",
  model: "sonnet", // Smart model for quality composition
  description: "Compose ${screenName} with components",
  prompt: `You are a uxscii screen composer creating production-ready screens.

Screen: ${screenName}
Components: ${componentList}
Layout: ${layoutStructure}
${baseOnExisting ? `
VERSIONING MODE:
- Base on existing: ${baseScreenId}
- New screen ID: ${newScreenId}
- Source version: ${sourceVersion}
- Copy-on-update: Increment minor version, preserve created timestamp
- Create THREE files with -v{N} suffix
` : ''}

YOUR PRIMARY DELIVERABLE: ${screenName}.rendered.md
This is what the user will see. Everything else supports this.

MANDATORY OUTPUTS (all 3 required):
1. ${screenName}.uxm (metadata)
2. ${screenName}.md (template with {{placeholders}})
3. ${screenName}.rendered.md (REAL data, ACTUAL ASCII) ⚠️ CRITICAL

If you complete without creating .rendered.md, you have FAILED.

Your task has TWO parts:

═══════════════════════════════════════
PART 1: Generate Component .md Files
═══════════════════════════════════════

For each component in [${componentList}]:

1. Read component .uxm from ./fluxwing/components/
2. Check if .md exists:
   - If EXISTS: Skip to next component
   - If MISSING: Generate .md file (steps 3-5)

3. Load ASCII patterns (ONCE for all components):
   {SKILL_ROOT}/../fluxwing-component-creator/docs/06-ascii-patterns.md

4. Generate simple ASCII art based on component type:
   - button: Rounded box with label
   - input: Rectangular box with placeholder
   - card: Box with title and content area
   - container: Large box for children
   - Use dimensions from .uxm (ascii.width, ascii.height)
   - Keep it simple (sketch quality, not detailed)

5. Create .md file with:
   - Component description
   - ASCII art in code block
   - Variables from .uxm props
   - Save to ./fluxwing/components/\${componentId}.md

Example .md for button:
\`\`\`markdown
# \${componentName}

\${description}

## ASCII

\`\`\`
╭──────────────────╮
│  {{label}}       │
╰──────────────────╯
\`\`\`

## Variables
- label (string): Button text
\`\`\`

═══════════════════════════════════════
PART 2: Compose Screen
═══════════════════════════════════════

1. Load schema: {SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json
2. Load screen docs: {SKILL_ROOT}/docs/04-screen-composition.md

3. Create screen .uxm:
   - ${baseOnExisting ? `Load existing: ./fluxwing/screens/${sourceVersion}.uxm` : `type: "container"`}
   - ${baseOnExisting ? `Base structure on source version` : `props.components: [${componentList}]`}
   - layout: ${layoutStructure}
   - ${baseOnExisting ? `id: "${newScreenId}" (with -v{N} suffix)` : `id: "${screenId}"`}
   - ${baseOnExisting ? `version: Increment minor from source (e.g., 1.0.0 → 1.1.0)` : `version: "1.0.0"`}
   - ${baseOnExisting ? `metadata.created: PRESERVE from ${sourceVersion}` : `metadata.created: current timestamp`}
   - ${baseOnExisting ? `metadata.modified: SET to current timestamp` : `metadata.modified: current timestamp`}

   CRITICAL: Set metadata.fidelity = "detailed"

   **REQUIRED FIELD**: Screen fidelity tracks the screen's completion level.
   Even if components are sketch fidelity, the screen itself is detailed (it's a composition).
   This enables tracking progressive fidelity at both component and screen levels.

4. Create screen .md (template):
   - Use {{component:id}} syntax for component references
   - Show layout structure with placeholders
   - ${baseOnExisting ? `Filename: ${newScreenId}.md (versioned)` : `Filename: ${screenId}.md`}

5. Create screen .rendered.md (MAIN DELIVERABLE):
   - Embed ACTUAL component ASCII (read from .md files you just created)
   - Use REAL example data (names: "Sarah Johnson", emails: "sarah@example.com", etc.)
   - Show all screen states (idle, loading, error if applicable)
   - High visual quality - this is what user will see!
   - Make it publication-ready
   - ${baseOnExisting ? `Filename: ${newScreenId}.rendered.md (versioned)` : `Filename: ${screenId}.rendered.md`}

6. Save all 3 files to ./fluxwing/screens/
   - ${baseOnExisting ? `${newScreenId}.uxm, ${newScreenId}.md, ${newScreenId}.rendered.md` : `${screenId}.uxm, ${screenId}.md, ${screenId}.rendered.md`}

═══════════════════════════════════════
Performance Notes:
═══════════════════════════════════════

- Load ASCII patterns ONCE, reuse for all components
- Keep component .md simple (detailed version comes with enhancement)
- Focus quality effort on screen .rendered.md
- Target: 60-90 seconds total

═══════════════════════════════════════
VERIFICATION CHECKLIST (before returning):
═══════════════════════════════════════

- [ ] .uxm file created and saved to ./fluxwing/screens/
- [ ] .md template created and saved to ./fluxwing/screens/
- [ ] .rendered.md created with REAL data and ACTUAL component ASCII
- [ ] All 3 files are in ./fluxwing/screens/
- [ ] .rendered.md uses realistic example data (not placeholders)
- [ ] .rendered.md embeds actual ASCII from component .md files

Return: "Created ${screenName}: .uxm ✓, .md ✓, .rendered.md ✓"
`
})

Step 5: Auto-Enhancement (Based on Quality Preset)

After screen composition, optionally enhance components based on quality preset.

Determine enhancement level:

  • fast → Skip (no enhancement)
  • balanced → Enhance to "basic"
  • detailed → Enhance to "detailed" [DEFAULT]
  • production → Enhance to "production"

If enhancement needed:

Task({
  subagent_type: "general-purpose",
  model: "sonnet", // Quality model for enhancement
  description: "Enhance screen components to ${targetFidelity}",
  prompt: `Enhance all components in ${screenName} to ${targetFidelity} fidelity.

Screen: ${screenName}
Components: ${componentList}
Current fidelity: sketch
Target fidelity: ${targetFidelity}

Use fluxwing-enhancer patterns:

Your task:
1. Load enhancement patterns: {SKILL_ROOT}/../fluxwing-enhancer/docs/enhancement-patterns.md
2. Load state templates: {SKILL_ROOT}/../fluxwing-component-creator/templates/state-additions/

3. For EACH component (process in parallel if possible):

   Read: ./fluxwing/components/\${componentId}.uxm
   Read: ./fluxwing/components/\${componentId}.md

   Enhance based on target:

   ${targetFidelity === 'basic' ? `
   basic fidelity:
   - Improve metadata.description (specific, 1-2 sentences)
   - Add relevant tags
   - Polish .md ASCII (clean, aligned)
   - Keep default state only
   - CRITICAL: Update metadata.fidelity = "basic" (REQUIRED FIELD)
   ` : ''}

   ${targetFidelity === 'detailed' ? `
   detailed fidelity:
   - All "basic" enhancements
   - Add hover state (use templates/state-additions/hover.json)
   - Add focus state (use templates/state-additions/focus.json)
   - Polish ASCII art (rounded corners, smooth)
   - Add props.examples array (2-3 examples)
   - CRITICAL: Update metadata.fidelity = "detailed" (REQUIRED FIELD)
   ` : ''}

   ${targetFidelity === 'production' ? `
   production fidelity:
   - All "detailed" enhancements
   - Add disabled state (if applicable)
   - Add error state (if form component)
   - Complete accessibility metadata
   - Add keyboard shortcuts
   - Pixel-perfect ASCII
   - CRITICAL: Update metadata.fidelity = "production" (REQUIRED FIELD)
   ` : ''}

   Save: Updated .uxm and .md to ./fluxwing/components/

4. After ALL components enhanced:

   Regenerate screen .rendered.md:
   - Read enhanced component .md files
   - Embed improved ASCII in .rendered.md
   - Maintain real example data
   - Save to ./fluxwing/screens/

5. Return summary:
   - Components enhanced: [list with changes]
   - Total time: Xs
   - Screen .rendered.md regenerated

Target time:
- basic: 30s (parallel for all components)
- detailed: 90s (parallel for all components)
- production: 180s (parallel for all components)

Note: Process components in parallel when possible for maximum speed!
`
})

Enhancement is parallel: All 6 components enhanced simultaneously, so time ≈ single component time!

Step 5.5: Validate Screen

REQUIRED: Validate the screen file against the schema after composition.

# Validate the screen
node {SKILL_ROOT}/../fluxwing-validator/validate-screen.js \
  ./fluxwing/screens/${screenId}.uxm \
  {SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json

Expected behavior:

  • ✅ If validation passes: Continue to Step 6 (Report Results)
  • ❌ If validation fails: Report errors clearly and stop execution

Screen-specific checks:

  • Validates against uxscii schema (same as components)
  • Checks for .rendered.md file (warning if missing)
  • Checks if composed components exist (warnings for missing components)

Example output (success):

✓ Valid: login-screen
  Type: container
  Version: 1.0.0
  States: 3
  Props: 3

⚠ Warnings:
  Warning 1: Referenced component not found: custom-input
  Location: composed

If validation fails, show errors to user:

✗ Validation Failed

  Error 1: must have required property 'fidelity'
  Location: metadata

Step 6: Report Results

Create comprehensive summary including enhancement details:

# Screen Scaffolding Complete ✓

## Screen: ${screenName}
## Quality Preset: ${qualityPreset}

### Phase 1: Fast Component Creation ⚡
${missingComponents.map(c => `✓ ${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\`

2. **Further enhancement (optional):**
   ${qualityPreset !== 'production' ? `Use /fluxwing-enhance to upgrade to ${nextFidelity} fidelity` : 'Already at maximum fidelity'}

3. **Customize components:**
   Edit ./fluxwing/components/ files as needed

4. **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)
  • ✓ Agents ran efficiently (parallel when possible)
  • ✓ User can immediately use the screen design

You are building complete, production-ready screen designs with maximum agent concurrency!

Fluxwing Screenshot Importer

Import UI screenshots and convert them to the uxscii standard by orchestrating specialized vision agents.

Data Location Rules

READ from (bundled templates - reference only):

  • {SKILL_ROOT}/../uxscii-component-creator/templates/ - 11 component templates (for reference)
  • {SKILL_ROOT}/docs/ - Screenshot processing documentation

WRITE to (project workspace):

  • ./fluxwing/components/ - Extracted components (.uxm + .md)
  • ./fluxwing/screens/ - Screen composition (.uxm + .md + .rendered.md)

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

Your Task

Import a screenshot of a UI design and automatically generate uxscii components and screens by orchestrating specialized agents:

  1. Vision Coordinator Agent - Spawns 3 parallel vision agents (layout + components + properties)
  2. Component Generator Agents - Generate component files in parallel (atomic + composite)
  3. Screen Scaffolder Skill - Delegates to fluxwing-screen-scaffolder for screen composition

⚠️ ORCHESTRATION RULES:

YOU CAN (as orchestrator):

  • ✅ Spawn vision analysis agents
  • ✅ Spawn component generator agents
  • ✅ Invoke fluxwing-screen-scaffolder skill
  • ✅ Read screenshots
  • ✅ Validate vision data

YOU CANNOT (worker mode - forbidden):

  • ⚠️ Create screen files yourself using Write/Edit tools
  • ⚠️ Generate .uxm, .md, or .rendered.md files for screens
  • ⚠️ "Help" the scaffolder by pre-creating screen files
  • ⚠️ Use TodoWrite to work through screen creation tasks yourself

For screen composition: ALWAYS delegate to fluxwing-screen-scaffolder skill. It will spawn composer agents that create all screen files (.uxm, .md, .rendered.md).

Workflow

Phase 1: Get Screenshot Path

Ask the user for the screenshot path if not provided:

  • "Which screenshot would you like to import?"
  • Validate file exists and is a supported format (PNG, JPG, JPEG, WebP, GIF)
// Example
const screenshotPath = "/path/to/screenshot.png";

Phase 2: Spawn Vision Coordinator Agent

CRITICAL: Spawn the screenshot-vision-coordinator agent to orchestrate parallel vision analysis.

This agent will:

  • Spawn 3 vision agents in parallel (layout discovery + component detection + visual properties)
  • Wait for all agents to complete
  • Merge results into unified component data structure
  • Return JSON with screen metadata, components array, and composition
Task({
  subagent_type: "general-purpose",
  description: "Analyze screenshot with vision analysis",
  prompt: `You are a UI screenshot analyzer extracting component structure for uxscii.

Screenshot path: ${screenshotPath}

Your task:
1. Read the screenshot image file
2. Analyze the UI layout structure (vertical, horizontal, grid, sidebar+main)
3. Detect all UI components (buttons, inputs, navigation, cards, etc.)
4. Extract visual properties (colors, spacing, borders, typography)
5. Identify component hierarchy (atomic vs composite)
6. Merge all findings into a unified data structure
7. Return valid JSON output

CRITICAL detection requirements:
- Do NOT miss navigation elements (check all edges - top, left, right, bottom)
- Do NOT miss small elements (icons, badges, close buttons, status indicators)
- Identify composite components (forms, cards with multiple elements)
- Note spatial relationships between components

Expected output format (valid JSON only, no markdown):
{
  "success": true,
  "screen": {
    "id": "screen-name",
    "type": "dashboard|login|profile|settings",
    "name": "Screen Name",
    "description": "What this screen does",
    "layout": "vertical|horizontal|grid|sidebar-main"
  },
  "components": [
    {
      "id": "component-id",
      "type": "button|input|navigation|etc",
      "name": "Component Name",
      "description": "What it does",
      "visualProperties": {...},
      "isComposite": false
    }
  ],
  "composition": {
    "atomicComponents": ["id1", "id2"],
    "compositeComponents": ["id3"],
    "screenComponents": ["screen-id"]
  }
}

Use your vision capabilities to analyze the screenshot carefully.`
})

Wait for the vision coordinator to complete and return results.

Phase 3: Validate Vision Data

Check the returned data structure:

const visionData = visionCoordinatorResult;

// Required fields
if (!visionData.success) {
  throw new Error(`Vision analysis failed: ${visionData.error}`);
}

if (!visionData.components || visionData.components.length === 0) {
  throw new Error("No components detected in screenshot");
}

// Navigation check (CRITICAL)
const hasNavigation = visionData.components.some(c =>
  c.type === 'navigation' || c.id.includes('nav') || c.id.includes('header')
);

if (visionData.screen.type === 'dashboard' && !hasNavigation) {
  console.warn("⚠️ Dashboard detected but no navigation found - verify all nav elements were detected");
}

Phase 4: Spawn Component Generator Agents (Parallel)

CRITICAL: YOU MUST spawn ALL component generator agents in a SINGLE message with multiple Task tool calls. This is the ONLY way to achieve true parallel execution.

DO THIS: Send ONE message containing ALL Task calls for all components DON'T DO THIS: Send separate messages for each component (this runs them sequentially)

For each atomic component, create a Task call in the SAME message:

Task({
  subagent_type: "general-purpose",
  description: "Generate email-input component",
  prompt: "You are a uxscii component generator. Generate component files from vision data.

Component data: {id: 'email-input', type: 'input', visualProperties: {...}}

Your task:
1. Load schema from {SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/screenshot-import-helpers.md
3. Generate .uxm file (valid JSON with default state only)
4. Generate .md file (ASCII template matching visual properties)
5. Save to ./fluxwing/components/
6. Return success with file paths

Follow uxscii standard strictly."
})

Task({
  subagent_type: "general-purpose",
  description: "Generate password-input component",
  prompt: "You are a uxscii component generator. Generate component files from vision data.

Component data: {id: 'password-input', type: 'input', visualProperties: {...}}

Your task:
1. Load schema from {SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/screenshot-import-helpers.md
3. Generate .uxm file (valid JSON with default state only)
4. Generate .md file (ASCII template matching visual properties)
5. Save to ./fluxwing/components/
6. Return success with file paths

Follow uxscii standard strictly."
})

Task({
  subagent_type: "general-purpose",
  description: "Generate submit-button component",
  prompt: "You are a uxscii component generator. Generate component files from vision data.

Component data: {id: 'submit-button', type: 'button', visualProperties: {...}}

Your task:
1. Load schema from {SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
2. Load docs from {SKILL_ROOT}/docs/screenshot-import-helpers.md
3. Generate .uxm file (valid JSON with default state only)
4. Generate .md file (ASCII template matching visual properties)
5. Save to ./fluxwing/components/
6. Return success with file paths

Follow uxscii standard strictly."
})

... repeat for ALL atomic components in the SAME message ...

... then for composite components in the SAME message:

Task({
  subagent_type: "general-purpose",
  description: "Generate login-form composite",
  prompt: "You are a uxscii component generator. Generate composite component from vision data.

Component data: {id: 'login-form', type: 'form', components: [...], visualProperties: {...}}

IMPORTANT: Include component references in props.components array.

Your task:
1. Load schema from {SKILL_ROOT}/../uxscii-component-creator/schemas/uxm-component.schema.json
2. Generate .uxm with components array in props
3. Generate .md with {{component:id}} references
4. Save to ./fluxwing/components/
5. Return success

Follow uxscii standard strictly."
})

Remember: ALL Task calls must be in a SINGLE message for parallel execution!

Phase 5: Delegate Screen Composition to Scaffolder

CRITICAL: YOU ARE AN ORCHESTRATOR - delegate screen creation to the screen-scaffolder skill!

⚠️ DO NOT create screen files yourself using Write/Edit tools!

After all components are created, use the fluxwing-screen-scaffolder to compose screens:

Single Screen Import:

// Invoke screen-scaffolder skill
Skill({ command: "fluxwing-skills:fluxwing-screen-scaffolder" })

// The scaffolder will:
// 1. See all components already exist (you just created them)
// 2. Skip component creation (Step 3)
// 3. Spawn ONE composer agent (Step 4)
// 4. Composer creates .uxm + .md + .rendered.md

Multiple Screenshots Import (N > 1):

// After analyzing ALL screenshots and creating ALL components
// Invoke screen-scaffolder skill ONCE
Skill({ command: "fluxwing-skills:fluxwing-screen-scaffolder" })

// Tell it about the screens:
// "I've imported N screenshots and created X components.
//  Please compose these N screens: [list screen names and component lists]"

// The scaffolder will:
// 1. Detect multi-screen scenario (N > 1)
// 2. Confirm with user
// 3. Skip component creation (all exist)
// 4. Spawn N composer agents in parallel (one per screen)
// 5. Each composer creates 3 files (.uxm, .md, .rendered.md)
// Result: 3N files created by scaffolder agents

What you provide to scaffolder:

  • Screen name and type (from vision analysis)
  • Component list (what components the screen needs)
  • Layout structure (from vision data)
  • Screenshot path (for .rendered.md generation)

Phase 6: Report Results

Create comprehensive summary:

# Screenshot Import Complete ✓

## Screenshot Analysis
- File: ${screenshotPath}
- Screen type: ${screenData.type}
- Layout: ${screenData.layout}

## Components Generated

### Atomic Components (${atomicCount})
${atomicComponents.map(c => `✓ ${c.id} (${c.type})`).join('\n')}

### Composite Components (${compositeCount})
${compositeComponents.map(c => `✓ ${c.id} (${c.type})`).join('\n')}

### Screen
✓ ${screenId}

## Files Created

**Components** (./fluxwing/components/):
- ${totalComponentFiles} files (.uxm + .md)

**Screen** (./fluxwing/screens/):
- ${screenId}.uxm
- ${screenId}.md
- ${screenId}.rendered.md

**Total: ${totalFiles} files created**

## Performance
- Vision analysis: Parallel (3 agents) ⚡
- Component generation: Parallel (${atomicCount + compositeCount} agents) ⚡
- Total time: ~${estimatedTime}s

## Next Steps

1. Review screen: `cat ./fluxwing/screens/${screenId}.rendered.md`
2. Add interaction states to components
3. Customize components as needed
4. View all components

Vision Agents Used

This skill orchestrates 5 specialized vision agents:

  1. screenshot-vision-coordinator - Orchestrates parallel analysis
  2. screenshot-component-detection - Finds UI elements
  3. screenshot-layout-discovery - Understands structure
  4. screenshot-visual-properties - Extracts styling
  5. screenshot-component-generator - Creates .uxm/.md files

Example Interaction

User: Import this screenshot at /Users/me/Desktop/login.png

Skill: I'll import the UI screenshot and generate uxscii components!

[Validates screenshot exists]

Step 1: Analyzing screenshot with vision agents...
[Spawns vision coordinator]

✓ Vision analysis complete:
  - Detected 5 components
  - Screen type: login
  - Layout: vertical-center

Step 2: Generating component files in parallel...
[Spawns 5 component generator agents in parallel]

✓ All components generated!

# Screenshot Import Complete ✓

## Components Generated
✓ email-input (input)
✓ password-input (input)
✓ submit-button (button)
✓ cancel-link (link)
✓ login-form (form)

## Files Created
- 10 component files
- 3 screen files
Total: 13 files

Performance: ~45s (5 agents in parallel) ⚡

Next steps:
- Review: cat ./fluxwing/screens/login-screen.rendered.md
- Add states to make components interactive

Quality Standards

Ensure imported components include:

  • ✓ Valid JSON schema compliance
  • ✓ Complete metadata (name, description, tags)
  • ✓ Proper component types
  • ✓ ASCII art matches detected visual properties
  • ✓ All detected components extracted
  • ✓ Screen composition includes all components
  • ✓ Rendered example with realistic data

Important Notes

  • Parallel execution is critical: All agents must be spawned in a single message
  • Navigation elements: Verify top nav, side nav, footer nav are detected
  • Small elements: Don't miss icons, badges, close buttons, status indicators
  • Composite components: Forms, cards with multiple elements
  • Screen files: Always create 3 files (.uxm, .md, .rendered.md)
  • Validation: Check vision data before generating components

Error Handling

If vision analysis fails:

✗ Vision analysis failed: [error message]

Please check:
- Screenshot file exists and is readable
- File format is supported (PNG, JPG, JPEG, WebP, GIF)
- Screenshot contains visible UI elements

If component generation fails:

⚠️ Partial success: 3 of 5 components generated

Successful:
✓ email-input
✓ password-input
✓ submit-button

Failed:
✗ cancel-link: [error]
✗ login-form: [error]

You can retry failed components or create them manually.

If no components detected:

✗ No components detected in screenshot.

This could mean:
- Screenshot is blank or unclear
- UI elements are too small to detect
- Screenshot is not a UI design

Please try a different screenshot or create components manually.

Resources

See {SKILL_ROOT}/docs/ for detailed documentation on:

  • screenshot-import-ascii.md - ASCII generation patterns
  • screenshot-import-examples.md - Example imports
  • screenshot-import-helpers.md - Helper functions
  • screenshot-data-merging.md - Data structure merging
  • screenshot-screen-generation.md - Screen file creation
  • screenshot-validation-functions.md - Data validation

You're helping users rapidly convert visual designs into uxscii components!

Fluxwing Validator

Validate uxscii components and screens against JSON Schema with interactive workflows.

Overview

This skill provides two modes of operation:

  1. Interactive Mode: User invocation with menu and minimal output
  2. Direct Mode: Script calls from other skills with verbose output

When to Use This Skill

User says:

  • "Validate my components"
  • "Check if everything is valid"
  • "Run validation on my screens"
  • "Validate the project"

Other skills: Call validator scripts directly (see Technical Reference below)

Interactive Validation Workflow

Step 1: Present Validation Options

Use AskUserQuestion to present menu:

What would you like to validate?

Options:

  1. Everything in this project - Validates all components and screens
  2. Just components - Validates ./fluxwing/components/*.uxm
  3. Just screens - Validates ./fluxwing/screens/*.uxm
  4. Let me specify a file or pattern - Custom path/glob pattern

Step 2: Check What Exists

Before running validation, check if directories exist:

# Check for components
test -d ./fluxwing/components

# Check for screens
test -d ./fluxwing/screens

If neither exists:

  • Inform user: "No components or screens found. Create some first!"
  • Exit cleanly

If option 4 (custom) selected:

  • Ask user for the pattern/file path
  • Validate it's not empty
  • Proceed with user-provided pattern

Step 3: Run Validation

Based on user selection:

Option 1: Everything

# Validate components
node {SKILL_ROOT}/validate-batch.js \
  "./fluxwing/components/*.uxm" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --json

# Validate screens
node {SKILL_ROOT}/validate-batch.js \
  "./fluxwing/screens/*.uxm" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --screens \
  --json

Option 2: Just components

node {SKILL_ROOT}/validate-batch.js \
  "./fluxwing/components/*.uxm" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --json

Option 3: Just screens

node {SKILL_ROOT}/validate-batch.js \
  "./fluxwing/screens/*.uxm" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --screens \
  --json

Option 4: Custom pattern

# Use user-provided pattern
node {SKILL_ROOT}/validate-batch.js \
  "${userPattern}" \
  "{SKILL_ROOT}/../fluxwing-component-creator/schemas/uxm-component.schema.json" \
  --json

Step 4: Parse Results and Show Minimal Summary

Parse JSON output from validator to extract:

  • total: Total files validated
  • passed: Number of valid files
  • failed: Number of failed files
  • warnings: Total warning count

Display minimal summary:

✓ 12/14 components valid
✗ 2/14 components failed
⚠ 3 warnings total

If all passed:

✓ All 14 components valid
⚠ 3 warnings

If everything failed:

✗ All 14 components failed

If nothing to validate:

No files found matching pattern

Step 5: Ask About Details

Use AskUserQuestion to ask:

Show error details?

Options:

  1. Yes - Display full validation output
  2. No - Clean exit

Step 6: Display Details (if requested)

If user selects "Yes", show full validation output including:

Failed files section:

Failed Files:

  ✗ broken-button (./fluxwing/components/broken-button.uxm)
    Errors: 2
      1. must have required property 'fidelity'
      2. ASCII template file not found

  ✗ old-card (./fluxwing/components/old-card.uxm)
    Errors: 1
      1. invalid version format

Passed with warnings section:

Passed with Warnings:

  ✓ login-screen (2 warnings)
  ✓ dashboard (1 warning)

Fully passed section (optional, only if not too many):

Fully Passed:

  ✓ primary-button
  ✓ secondary-button
  ✓ email-input
  ...

Edge Cases

No fluxwing directory exists

No components or screens found. Create some first!

Empty directories

✓ 0/0 components valid

Invalid glob pattern (option 4)

No files found matching pattern: ${pattern}

Validation script fails to execute

Error: Cannot execute validator. Node.js required.

Technical Reference (For Other Skills)

Direct Script Calls

Other skills (component-creator, screen-scaffolder) call validator scripts directly:

Validate single component:

node {SKILL_ROOT}/../fluxwing-validator/validate-component.js \
  ./fluxwing/components/button.uxm \
  {SKILL_ROOT}/schemas/uxm-component.schema.json

Validate single screen:

node {SKILL_ROOT}/../fluxwing-validator/validate-screen.js \
  ./fluxwing/screens/login-screen.uxm \
  {SKILL_ROOT}/schemas/uxm-component.schema.json

Batch validate:

node {SKILL_ROOT}/../fluxwing-validator/validate-batch.js \
  "./fluxwing/components/*.uxm" \
  {SKILL_ROOT}/schemas/uxm-component.schema.json

Output modes:

  • Default: Human-readable (verbose, full errors/warnings)
  • --json: Machine-readable JSON

Exit codes:

  • 0: All files valid
  • 1: One or more files invalid
  • 2: Missing dependencies or invalid arguments

Validator Scripts

Available scripts:

  • validate-component.js - Validate single component file
  • validate-screen.js - Validate single screen file (with screen-specific checks)
  • validate-batch.js - Validate multiple files with glob patterns
  • test-validator.js - Test component templates
  • test-screen-validator.js - Test screen templates

npm Scripts (for testing)

cd {SKILL_ROOT}

# Run tests
npm test                    # Test component templates
npm run test:screens       # Test screen templates

# Batch validation
npm run validate:components  # Validate all components
npm run validate:screens     # Validate all screens
npm run validate:all         # Validate everything

Example Interactions

Example 1: Validate Everything

User: "Validate my components"

Skill:

What would you like to validate?

1. Everything in this project
2. Just components
3. Just screens
4. Let me specify a file or pattern

User selects: Option 1

Skill runs validation and shows:

✓ 12/14 components valid
✗ 2/14 components failed
⚠ 3 warnings total

✓ 2/2 screens valid
⚠ 1 warning

Show error details?

User: "yes"

Skill shows full error details for failed files

Example 2: Validate Specific Pattern

User: "Validate my components"

Skill: (presents menu)

User selects: Option 4 (custom pattern)

Skill: "What file or pattern would you like to validate?"

User: "./fluxwing/components/*-button.uxm"

Skill validates and shows:

✓ 3/3 files valid

Show error details?

Implementation Notes

Parse JSON output:

const result = JSON.parse(bashOutput);
const total = result.total;
const passed = result.passed;
const failed = result.failed;
const warnings = result.warnings;

Summary formatting:

  • Show passed/failed ratio for quick scan
  • Highlight failures prominently
  • Warnings shown but not intrusive
  • Clean, minimal output by default

Error detail formatting:

  • Group by status (failed, warnings, passed)
  • Show file path and error count
  • Display first 2-3 errors per file
  • Indicate if more errors exist

Skill Status: Ready for use Version: 1.0.0

Sponsors

Details

Marketplace
trabian/fluxwing-skills
Author
Trabian
Category
Community
License
MIT
Keywords
fluxwing, uxscii, ui-design, ux-design, components, screens, ascii-art, design-system