Fluxwing Component Creator

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!