
fluxwing-skills
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-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add trabian/fluxwing-skills.
Contents
Discovered from sourceSkills 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:
-
Single component request:
- "Create a submit button"
- "I need a card component"
- Proceed with single-component workflow (Steps 2-4)
-
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:
-
Convert to kebab-case ID:
"Submit Button" → "submit-button" "User Profile Card" → "user-profile-card" -
Check if component exists:
# Check for existing component test -f ./fluxwing/components/{component-id}.uxm -
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:
- Load copy-versioning logic from
{SKILL_ROOT}/../shared/docs/copy-versioning.md - Read existing
{component-id}.uxm - Find highest version (check for
{component-id}-v2,-v3, etc.) - Calculate next version:
v{N+1} - Pass to designer agent with versioning parameters:
baseComponentId: Original ID (e.g., "submit-button")newComponentId: Versioned ID (e.g., "submit-button-v2")baseOnExisting: truesourceVersion: Highest existing version
- Designer creates
{component-id}-v{N+1}.uxmand.md - Metadata: Increment minor version (1.0.0 → 1.1.0), update modified, preserve created
- Load copy-versioning logic from
-
Choice (b) - Different name:
- Ask: "What would you like to name this component?"
- Wait for user response
- Use new name for component ID
- Proceed with normal creation
-
Choice (c) - Cancel:
- Do not create any files
- Inform user: "Operation cancelled. No files were created."
- Exit workflow
-
-
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:
- Read the error messages carefully
- Fix the issues in the .uxm or .md files
- 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}.uxmwith 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.modifiedtimestamp (set to current ISO 8601 timestamp)behavior.statesarray (add new states to end).mdfile (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:
- Read the error messages
- Fix the issues in the .uxm or .md files
- 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:
-
Project Components:
./fluxwing/components/[name].uxm- User/agent-created custom components
- Fully editable
- Tag as: "Your Component"
-
Project Library:
./fluxwing/library/[name].uxm- Customized copies of bundled templates
- Fully editable
- Tag as: "Your Library"
-
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.descriptionfield from .uxm file - Keep it concise (1-2 lines)
Component Details:
- Type: Direct from .uxm
typefield - Props: List prop names with types in parentheses
- Format:
propName (type) - Example:
text (string), disabled (boolean)
- Format:
- 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:
- Count total states/sections in template
- Show first 2-3 states completely
- Add summary line:
[... N more states] - 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.mdfor 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:
- Finds 6 sketch components
- Spawns 6 enhancement agents (parallel)
- Each agent: sketch → detailed (~90s)
- Regenerates banking-chat.rendered.md
- Total time: ~120 seconds
User: "Make submit-button production-ready"
Enhancer:
- Finds submit-button (detailed fidelity)
- Spawns 1 enhancement agent
- Agent: detailed → production (~180s)
- Updates screen if applicable
- 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:
- Bundled Templates - 11 curated examples from skill templates (read-only reference)
- Project Components - User/agent-created reusable components in
./fluxwing/components/(editable) - Project Library - Customized template copies in
./fluxwing/library/(editable) - 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.mdfor 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
- Read-only templates: Bundled templates cannot be modified directly
- Copy before customize: Copy templates to
./fluxwing/library/to customize - Search: Use Glob and Grep to find components by name or pattern
- Organization: Keep components in
./fluxwing/components/, customized templates in./fluxwing/library/ - 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:
- Phase 1 (Parallel): Spawn multiple designer agents - one per missing component using multiple Task tool calls in ONE message
- 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:
- User-created:
./fluxwing/components/(FIRST PRIORITY) - Library:
./fluxwing/library/(customized templates) - 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.
-
Convert screen name to kebab-case ID:
"Login Screen" → "login-screen" "User Dashboard" → "user-dashboard" -
Check if screen exists:
# Check for existing screen test -f ./fluxwing/screens/{screen-id}.uxm -
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:
- Load copy-versioning logic from
{SKILL_ROOT}/../shared/docs/copy-versioning.md - Read existing
{screen-id}.uxm - Find highest version (check for
{screen-id}-v2,-v3, etc.) - Calculate next version:
v{N+1} - Pass to composer agent with versioning parameters:
baseScreenId: Original ID (e.g., "login-screen")newScreenId: Versioned ID (e.g., "login-screen-v2")baseOnExisting: truesourceVersion: Highest existing version
- Composer creates THREE files:
{screen-id}-v{N+1}.uxm{screen-id}-v{N+1}.md{screen-id}-v{N+1}.rendered.md
- Metadata: Increment minor version (1.0.0 → 1.1.0), update modified, preserve created
- Load copy-versioning logic from
-
Choice (b) - Different name:
- Ask: "What would you like to name this screen?"
- Wait for user response
- Use new name for screen ID
- Proceed with normal scaffolding
-
Choice (c) - Cancel:
- Do not create any files
- Inform user: "Operation cancelled. No files were created."
- Exit workflow
-
-
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:
- ⚠️ DO NOT create TodoWrite list and work through it yourself
- ⚠️ DO NOT create components yourself using Write/Edit tools
- ✅ DO use Task tool to spawn one agent per missing component
- ✅ DO send ONE message with ALL Task calls (parallel execution)
- ✅ DO use FAST MODE (creates .uxm only, <10s per component)
Path B (Multi-screen): Component Deduplication
When creating components for multiple screens:
- Inventory ALL screens first: Collect component requirements from all N screens
- 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
- Example: 6 screens might need
- 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:
- Generates missing component .md files
- Loads documentation ONCE (not per component)
- Creates screen .uxm + .md + .rendered.md
- 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:
- Detect how many screens are needed
- Spawn that many composer agents in ONE message
- Wait for results
- 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:
- Vision Coordinator Agent - Spawns 3 parallel vision agents (layout + components + properties)
- Component Generator Agents - Generate component files in parallel (atomic + composite)
- 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:
- screenshot-vision-coordinator - Orchestrates parallel analysis
- screenshot-component-detection - Finds UI elements
- screenshot-layout-discovery - Understands structure
- screenshot-visual-properties - Extracts styling
- 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:
- Interactive Mode: User invocation with menu and minimal output
- 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:
- Everything in this project - Validates all components and screens
- Just components - Validates
./fluxwing/components/*.uxm - Just screens - Validates
./fluxwing/screens/*.uxm - 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 validatedpassed: Number of valid filesfailed: Number of failed fileswarnings: 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:
- Yes - Display full validation output
- 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 valid1: One or more files invalid2: Missing dependencies or invalid arguments
Validator Scripts
Available scripts:
validate-component.js- Validate single component filevalidate-screen.js- Validate single screen file (with screen-specific checks)validate-batch.js- Validate multiple files with glob patternstest-validator.js- Test component templatestest-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