Initial commit

2025-11-30 09:02:33 +08:00
commit 0c40192593
82 changed files with 18699 additions and 0 deletions
--- a/skills/fluxwing-enhancer/SKILL.md
+++ b/skills/fluxwing-enhancer/SKILL.md
@@ -0,0 +1,291 @@
+---
+name: Fluxwing Enhancer
+description: Enhance uxscii components from sketch to production fidelity. Use when working with .uxm files marked as "fidelity: sketch" or when user wants to add detail and polish to components.
+version: 0.0.1
+author: Trabian
+allowed-tools: Read, Write, Edit, Glob, Grep, Task, TodoWrite
+---
+
+# Fluxwing Enhancer
+
+Progressively enhance uxscii components from sketch to production quality.
+
+## Data Location Rules
+
+**READ from:**
+- `./fluxwing/components/` - User components to enhance
+- `{SKILL_ROOT}/../fluxwing-component-creator/templates/state-additions/` - State templates
+- `{SKILL_ROOT}/docs/` - Enhancement documentation
+
+**LOAD for copy-on-update logic:**
+- `{SKILL_ROOT}/../shared/docs/copy-versioning.md` - Versioning pattern for fidelity enhancements
+
+**WRITE to:**
+- `./fluxwing/components/` - New versioned components (copy-on-update: {id}-v{N+1})
+- `./fluxwing/screens/` - Updated screen .rendered.md (if applicable)
+
+**IMPORTANT**: Enhancer creates NEW versions instead of overwriting originals. Each fidelity enhancement creates a new `-v{N}` copy.
+
+## Fidelity Levels
+
+### sketch (Fast Scaffold Output)
+- Basic .uxm with minimal metadata
+- May lack .md file or have simple .md
+- Single "default" state
+- Creation time: ~10 seconds
+
+**Characteristics:**
+- Minimal description
+- Generic tags
+- No examples
+- Basic props only
+
+### basic (First Enhancement)
+- Enriched metadata (better description, tags)
+- Simple .md with clean ASCII
+- Default state only
+- Enhancement time: ~30 seconds
+
+**Improvements over sketch:**
+- Detailed description
+- Specific tags
+- Clean ASCII art
+- Documented variables
+
+### detailed (Second Enhancement)
+- Rich metadata with usage examples
+- Polished .md with careful ASCII art
+- 2-3 interaction states (hover, focus)
+- Enhancement time: ~90 seconds
+
+**Improvements over basic:**
+- Usage examples in metadata
+- Hover + focus states
+- Polished ASCII
+- Props.examples array
+
+### production (Final Polish)
+- Complete metadata with accessibility details
+- Publication-quality ASCII
+- All relevant states (hover, focus, disabled, active, error)
+- Full documentation
+- Enhancement time: ~180 seconds
+
+**Improvements over detailed:**
+- All applicable states
+- Complete accessibility metadata
+- Keyboard shortcuts
+- Publication-quality ASCII
+- Edge case documentation
+
+## Your Task
+
+Help users enhance components from current fidelity to target fidelity.
+
+### Workflow
+
+#### Step 1: Inventory Components
+
+Check what components exist and their current fidelity:
+
+```bash
+ls ./fluxwing/components/*.uxm
+```
+
+For each component, read fidelity level:
+```bash
+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:**
+
+```typescript
+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:
+
+```bash
+# 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
+
+```markdown
+# Enhancement Complete ✓
+
+## Components Enhanced
+
+${enhancedComponents.map(c => `
+### ${c.id}
+- Before: ${c.oldFidelity}
+- After: ${c.newFidelity}
+- Time: ${c.time}s
+- Changes:
+  - ${c.changes.join('\n  - ')}
+`).join('\n')}
+
+## Total Time: ${totalTime}s
+
+## Screens Updated
+${updatedScreens.length > 0 ? updatedScreens.map(s => `- ${s}.rendered.md regenerated`).join('\n') : 'None'}
+
+## Next Steps
+1. Review enhanced components: \`ls ./fluxwing/components/\`
+2. View updated screen: \`cat ./fluxwing/screens/${screenName}.rendered.md\`
+3. Customize as needed
+```
+
+## Example Usage
+
+**User:** "Enhance all components in banking-chat to detailed"
+
+**Enhancer:**
+1. Finds 6 sketch components
+2. Spawns 6 enhancement agents (parallel)
+3. Each agent: sketch → detailed (~90s)
+4. Regenerates banking-chat.rendered.md
+5. Total time: ~120 seconds
+
+**User:** "Make submit-button production-ready"
+
+**Enhancer:**
+1. Finds submit-button (detailed fidelity)
+2. Spawns 1 enhancement agent
+3. Agent: detailed → production (~180s)
+4. Updates screen if applicable
+5. Total time: ~180 seconds
+
+## Success Criteria
+
+- ✓ Components upgraded to target fidelity
+- ✓ All states added as specified
+- ✓ ASCII art improved
+- ✓ Metadata enriched
+- ✓ Screen .rendered.md regenerated (if applicable)
+- ✓ All files validate against schema
+
+You are building a progressive enhancement system for maximum flexibility!
--- a/skills/fluxwing-enhancer/docs/enhancement-patterns.md
+++ b/skills/fluxwing-enhancer/docs/enhancement-patterns.md
@@ -0,0 +1,355 @@
+# Enhancement Patterns
+
+How to enhance components from sketch to production fidelity.
+
+## Fidelity Progression Matrix
+
+| Aspect | sketch | basic | detailed | production |
+|--------|--------|-------|----------|------------|
+| **Description** | Generic | Specific (1-2 sent) | Detailed (3-4 sent) | Complete with edge cases |
+| **Tags** | Type only | Type + context | Type + context + features | All applicable tags |
+| **ASCII Art** | Missing or minimal | Clean and aligned | Polished with spacing | Pixel-perfect, publication-quality |
+| **States** | default only | default only | default + hover + focus | All applicable states |
+| **Props** | Minimal | Standard | + examples array | + validation rules |
+| **Accessibility** | Basic role | + focusable | + aria-label | + keyboard shortcuts + full a11y |
+| **Time** | 10s | 30s | 90s | 180s |
+
+## Enhancement Checklist by Fidelity
+
+### sketch → basic (30s)
+
+**Metadata:**
+- [ ] Improve description from generic to specific
+- [ ] Add relevant tags beyond just type
+- [ ] Keep created/modified timestamps
+
+**ASCII:**
+- [ ] Create .md if missing
+- [ ] Add clean ASCII art using box-drawing characters
+- [ ] Match dimensions from .uxm (ascii.width, ascii.height)
+- [ ] Basic alignment (don't need perfect)
+
+**Props:**
+- [ ] Document all variables in .md
+- [ ] No need to add examples yet
+
+**States:**
+- [ ] Keep default state only
+
+**Example:**
+
+Before (sketch):
+```json
+{
+  "metadata": {
+    "description": "Button component",
+    "tags": ["button"]
+  }
+}
+```
+
+After (basic):
+```json
+{
+  "metadata": {
+    "description": "Submit button for form submission with primary action styling",
+    "tags": ["button", "submit", "form", "primary-action"],
+    "fidelity": "basic"
+  }
+}
+```
+
+### basic → detailed (90s)
+
+**Metadata:**
+- [ ] Expand description with usage context
+- [ ] Add props.examples array (2-3 examples)
+
+**ASCII:**
+- [ ] Polish alignment (consistent spacing)
+- [ ] Smooth corners and borders
+- [ ] Add visual details
+
+**States:**
+- [ ] Add hover state (use hover.json template)
+- [ ] Add focus state (use focus.json template)
+- [ ] Document state behavior in .md
+
+**Props:**
+- [ ] Add examples showing different prop combinations
+
+**Example:**
+
+Before (basic):
+```json
+{
+  "props": {
+    "label": "Submit"
+  },
+  "behavior": {
+    "states": [
+      {"name": "default", "properties": {}}
+    ]
+  }
+}
+```
+
+After (detailed):
+```json
+{
+  "props": {
+    "label": "Submit",
+    "examples": [
+      {"label": "Submit", "context": "Form submission"},
+      {"label": "Sign In", "context": "Login form"},
+      {"label": "Continue", "context": "Multi-step process"}
+    ]
+  },
+  "behavior": {
+    "states": [
+      {"name": "default", "properties": {}},
+      {"name": "hover", "properties": {
+        "backgroundColor": "#e0e0e0",
+        "cursor": "pointer"
+      }},
+      {"name": "focus", "properties": {
+        "outline": "2px solid #0066cc",
+        "backgroundColor": "#f0f8ff"
+      }}
+    ]
+  },
+  "metadata": {
+    "fidelity": "detailed"
+  }
+}
+```
+
+### detailed → production (180s)
+
+**Metadata:**
+- [ ] Add edge case documentation
+- [ ] Complete all optional fields
+- [ ] Add keywords for searchability
+
+**ASCII:**
+- [ ] Pixel-perfect alignment
+- [ ] Publication-quality rendering
+- [ ] Consider printing/export appearance
+
+**States:**
+- [ ] Add disabled state (if applicable)
+- [ ] Add error state (if applicable for forms)
+- [ ] Add active/pressed state (for buttons)
+- [ ] Add loading state (if async action)
+
+**Accessibility:**
+- [ ] Add keyboard shortcuts
+- [ ] Add screen reader descriptions
+- [ ] Add ARIA label templates
+- [ ] Document keyboard navigation
+
+**Props:**
+- [ ] Add validation rules
+- [ ] Document prop constraints
+- [ ] Add deprecation notices if needed
+
+**Example:**
+
+Before (detailed):
+```json
+{
+  "behavior": {
+    "states": [
+      {"name": "default", "properties": {}},
+      {"name": "hover", "properties": {...}},
+      {"name": "focus", "properties": {...}}
+    ],
+    "accessibility": {
+      "role": "button",
+      "focusable": true
+    }
+  }
+}
+```
+
+After (production):
+```json
+{
+  "behavior": {
+    "states": [
+      {"name": "default", "properties": {}},
+      {"name": "hover", "properties": {...}},
+      {"name": "focus", "properties": {...}},
+      {"name": "disabled", "properties": {
+        "opacity": 0.5,
+        "cursor": "not-allowed",
+        "interactive": false
+      }},
+      {"name": "active", "properties": {
+        "backgroundColor": "#c0c0c0",
+        "transform": "translateY(1px)"
+      }}
+    ],
+    "accessibility": {
+      "role": "button",
+      "focusable": true,
+      "ariaLabel": "{{label}} - {{context}}",
+      "keyboardShortcuts": [
+        {"key": "Enter", "action": "activate"},
+        {"key": "Space", "action": "activate"}
+      ]
+    }
+  },
+  "metadata": {
+    "fidelity": "production",
+    "description": "Submit button for form submission with primary action styling. Supports keyboard navigation (Enter/Space), shows visual feedback on hover and focus, and provides disabled state for form validation. Use for primary actions like 'Submit', 'Sign In', 'Continue'."
+  }
+}
+```
+
+## State Addition Guide
+
+### When to Add Each State
+
+**hover:**
+- All interactive components (button, input, link)
+- Cards if clickable
+- Navigation items
+
+**focus:**
+- All focusable components
+- Required for keyboard navigation
+- WCAG AA compliance
+
+**disabled:**
+- Form controls (button, input, checkbox, select)
+- Actions that may be unavailable
+- Not needed for display-only components
+
+**error:**
+- Form inputs (text, email, password)
+- Validation feedback required
+- Not needed for buttons or display components
+
+**active/pressed:**
+- Buttons
+- Links
+- Interactive cards
+- Shows immediate feedback
+
+**loading:**
+- Buttons triggering async actions
+- Forms submitting data
+- Components fetching data
+
+## ASCII Art Enhancement
+
+### sketch → basic
+
+Focus: Functionality over beauty
+- Use basic box-drawing characters (─│┌┐└┘)
+- Align text roughly
+- Match dimensions
+
+Example:
+```
+┌──────────────────┐
+│ Submit           │
+└──────────────────┘
+```
+
+### basic → detailed
+
+Focus: Polish and consistency
+- Use rounded corners (╭╮╰╯) for friendly feel
+- Careful spacing (center-align text)
+- Smooth visual flow
+
+Example:
+```
+╭──────────────────╮
+│     Submit       │
+╰──────────────────╯
+```
+
+### detailed → production
+
+Focus: Pixel-perfect publication quality
+- Perfect alignment (character-level precision)
+- Consider all states (how hover/focus changes appearance)
+- Professional appearance for screenshots
+
+Example:
+```
+╭──────────────────╮
+│      Submit      │
+╰──────────────────╯
+
+Hover:
+╔══════════════════╗
+║      Submit      ║
+╚══════════════════╝
+```
+
+## Common Patterns
+
+### Button Enhancement
+
+sketch → basic:
+- Add clean box ASCII
+- Specific description
+
+basic → detailed:
+- Add hover + focus states
+- Polish ASCII with rounded corners
+- Add usage examples
+
+detailed → production:
+- Add disabled + active states
+- Add keyboard shortcuts
+- Pixel-perfect ASCII
+
+### Input Enhancement
+
+sketch → basic:
+- Add input box ASCII with placeholder
+- Specific description
+
+basic → detailed:
+- Add focus state
+- Add label positioning
+- Add usage examples
+
+detailed → production:
+- Add error state
+- Add disabled state
+- Add validation rules
+- Full accessibility
+
+### Card Enhancement
+
+sketch → basic:
+- Add card box with title/content areas
+- Specific description
+
+basic → detailed:
+- Polish layout and spacing
+- Add examples (different content)
+
+detailed → production:
+- Add hover state (if interactive)
+- Perfect alignment
+- Complete metadata
+
+## Performance Targets
+
+| Enhancement | Components | Time Target |
+|-------------|-----------|-------------|
+| 1 component to basic | 1 | 30s |
+| 1 component to detailed | 1 | 90s |
+| 1 component to production | 1 | 180s |
+| 6 components to basic (parallel) | 6 | 30s |
+| 6 components to detailed (parallel) | 6 | 90s |
+| 6 components to production (parallel) | 6 | 180s |
+
+Parallel execution: Multiple agents working simultaneously, so total time ≈ single component time!