Initial commit

skills/fluxwing-component-expander/docs/03-component-creation.md

@@ -0,0 +1,294 @@
+# Component Creation - Step-by-Step Workflow
+
+Complete guide for creating uxscii components from scratch.
+
+## Before You Start
+
+1. **Understand the concept** - Read `02-core-concepts.md` if you haven't
+2. **Check examples** - Browse `../examples/` for similar components
+3. **Plan your component** - Know what you're building
+
+## Step-by-Step Process
+
+### Step 1: Plan Your Component
+
+Answer these questions:
+- **What is it?** Button, input, card, modal, etc.
+- **What does it do?** Primary purpose and use case
+- **What's configurable?** Props users can change
+- **What states does it have?** Default, hover, focus, disabled, error, success
+- **How will it look?** Sketch ASCII layout
+
+### Step 2: Create the .uxm File
+
+Start with required fields:
+
+```json
+{
+  "id": "my-component",
+  "type": "button",
+  "version": "1.0.0",
+  "metadata": {
+    "name": "My Component",
+    "created": "2024-10-11T12:00:00Z",
+    "modified": "2024-10-11T12:00:00Z"
+  },
+  "props": {},
+  "ascii": {
+    "templateFile": "my-component.md",
+    "width": 20,
+    "height": 3
+  }
+}
+```
+
+**Tips:**
+- ID must be kebab-case, 2-64 characters
+- Version must be semantic (major.minor.patch)
+- Timestamps should be ISO 8601 format
+- Template file must end with `.md`
+
+### Step 3: Add Props and Variables
+
+Define what users can configure:
+
+```json
+{
+  "props": {
+    "text": "Click me",          // Default values
+    "variant": "primary",
+    "disabled": false
+  },
+  "ascii": {
+    "templateFile": "my-component.md",
+    "width": 20,
+    "height": 3,
+    "variables": [
+      {
+        "name": "text",
+        "type": "string",
+        "required": true,
+        "description": "Button label text",
+        "validation": {
+          "min": 1,
+          "max": 20
+        }
+      },
+      {
+        "name": "variant",
+        "type": "string",
+        "defaultValue": "primary",
+        "validation": {
+          "enum": ["primary", "secondary", "outline"]
+        }
+      }
+    ]
+  }
+}
+```
+
+### Step 4: Define Default State and Behaviors
+
+Components are created with **default state only** for fast MVP prototyping:
+
+```json
+{
+  "behavior": {
+    "states": [
+      {
+        "name": "default",
+        "properties": {
+          "border": "solid",
+          "background": "primary"
+        }
+      }
+    ],
+    "interactions": [
+      {
+        "trigger": "click",
+        "action": "emit-click-event"
+      }
+    ],
+    "accessibility": {
+      "role": "button",
+      "ariaLabel": "{{text}}",
+      "focusable": true,
+      "keyboardSupport": ["Enter", "Space"]
+    }
+  }
+}
+```
+
+**Adding more states**: After MVP validation, use `/fluxwing-expand-component` to add hover, focus, disabled states. The command will automatically add appropriate states based on component type.
+
+### Step 5: Add Metadata (Recommended)
+
+Help others discover and understand your component:
+
+```json
+{
+  "metadata": {
+    "name": "My Component",
+    "description": "A customizable button component with multiple variants and states",
+    "author": "Your Name",
+    "created": "2024-10-11T12:00:00Z",
+    "modified": "2024-10-11T12:00:00Z",
+    "tags": ["button", "interactive", "form"],
+    "category": "input"
+  }
+}
+```
+
+### Step 6: Create the .md Template
+
+Basic structure:
+
+````markdown
+# My Component
+
+Brief description of what this component does.
+
+## Default State
+
+```
+╭──────────────────╮
+│   {{text}}       │
+╰──────────────────╯
+```
+
+## Variables
+
+- `text` (string, required): Button label text. Max 20 characters.
+- `variant` (string): Visual style - "primary", "secondary", or "outline"
+
+## Accessibility
+
+- **Role**: button
+- **Focusable**: Yes
+- **Keyboard**: Enter or Space to activate
+
+## Usage Examples
+
+### Primary Button
+```
+╭──────────────────╮
+│   Submit Form    │
+╰──────────────────╯
+```
+
+### Secondary Button
+```
+┌──────────────────┐
+│   Cancel         │
+└──────────────────┘
+```
+````
+
+**Tips:**
+- Start with default state only (fast MVP creation)
+- Document ALL variables used in template
+- Include usage examples with real data
+- Add accessibility notes for interactive components
+
+**Adding more states**: After creating the component, run `/fluxwing-expand-component my-component` to add hover, focus, disabled states automatically.
+
+### Step 7: Save Files
+
+Save both files together:
+```
+./fluxwing/components/my-component.uxm
+./fluxwing/components/my-component.md
+```
+
+Create the directory if it doesn't exist:
+```bash
+mkdir -p ./fluxwing/components
+```
+
+## Common Patterns
+
+### Form Input
+```json
+{
+  "id": "text-input",
+  "type": "input",
+  "props": {
+    "placeholder": "Enter text",
+    "value": "",
+    "error": "",
+    "disabled": false
+  },
+  "behavior": {
+    "states": ["default", "focus", "error", "disabled"],
+    "interactions": [
+      {"trigger": "focus", "action": "highlight-field"},
+      {"trigger": "blur", "action": "validate-field"}
+    ]
+  }
+}
+```
+
+### Data Card
+```json
+{
+  "id": "metric-card",
+  "type": "card",
+  "props": {
+    "title": "Metric",
+    "value": "1,234",
+    "change": "+12%",
+    "trend": "up"
+  }
+}
+```
+
+### Modal Dialog
+```json
+{
+  "id": "confirm-dialog",
+  "type": "modal",
+  "props": {
+    "title": "Confirm",
+    "message": "Are you sure?",
+    "confirmText": "Yes",
+    "cancelText": "No"
+  },
+  "behavior": {
+    "states": ["open", "closed"],
+    "interactions": [
+      {"trigger": "click", "action": "close-modal", "target": "backdrop"},
+      {"trigger": "keydown", "action": "close-modal", "condition": "key === 'Escape'"}
+    ]
+  }
+}
+```
+
+## Troubleshooting
+
+### "Template file not found"
+**Fix**: Ensure `.md` file exists and `templateFile` path is correct
+
+### "Variable not defined"
+**Fix**: Add variable to `ascii.variables` array in `.uxm`
+
+### "Invalid JSON"
+**Fix**: Validate JSON syntax (no trailing commas, proper quotes)
+
+### "ASCII art looks broken"
+**Fix**: Use monospace font, check for consistent character width
+
+## Quick Reference
+
+**Required .uxm fields**: id, type, version, metadata (name, created, modified), props, ascii (templateFile, width, height)
+
+**Required .md sections**: Title, default state, variables documentation
+
+**Recommended additions**: Multiple states, accessibility attributes, usage examples, detailed metadata
+
+## Next Steps
+
+- **Compose screens**: Use `/fluxwing-scaffold` to build complete screens
+- **Browse library**: Use `/fluxwing-library` to see all components
+- **Learn patterns**: Check `06-ascii-patterns.md` for ASCII art reference
+
+You can now create production-ready uxscii components!

skills/fluxwing-component-expander/docs/06-ascii-patterns.md

@@ -0,0 +1,498 @@
+# ASCII Patterns - Visual Toolkit
+
+Complete library of ASCII characters and patterns for uxscii components.
+
+## Box-Drawing Characters
+
+### Basic Borders
+
+**Light (Default)**
+```
+┌─────┐
+│ Box │
+└─────┘
+```
+Characters: `┌ ─ ┐ │ └ ┘`
+
+**Rounded (Friendly)**
+```
+╭─────╮
+│ Box │
+╰─────╯
+```
+Characters: `╭ ─ ╮ │ ╰ ╯`
+
+**Double (Emphasis)**
+```
+╔═════╗
+║ Box ║
+╚═════╝
+```
+Characters: `╔ ═ ╗ ║ ╚ ╝`
+
+**Heavy (Strong)**
+```
+┏━━━━━┓
+┃ Box ┃
+┗━━━━━┛
+```
+Characters: `┏ ━ ┓ ┃ ┗ ┛`
+
+### Complex Borders
+
+**With Dividers**
+```
+┌─────────┬─────────┐
+│  Col 1  │  Col 2  │
+├─────────┼─────────┤
+│  Data   │  Data   │
+└─────────┴─────────┘
+```
+
+**Nested**
+```
+╭─────────────────╮
+│ Outer           │
+│ ┌─────────────┐ │
+│ │ Inner       │ │
+│ └─────────────┘ │
+╰─────────────────╯
+```
+
+## Component State Patterns
+
+### Buttons
+
+**Default**
+```
+▓▓▓▓▓▓▓▓▓▓
+▓ Click  ▓
+▓▓▓▓▓▓▓▓▓▓
+```
+
+**Hover (Highlighted)**
+```
+░▓▓▓▓▓▓▓▓▓▓░
+░▓ Click  ▓░
+░▓▓▓▓▓▓▓▓▓▓░
+```
+
+**Focus (Ring)**
+```
+┏━━━━━━━━━━┓✨
+┃  Click   ┃
+┗━━━━━━━━━━┛
+```
+
+**Disabled (Grayed)**
+```
+┌ ─ ─ ─ ─ ┐
+│  Click  │
+└ ─ ─ ─ ─ ┘
+```
+
+**Pressed/Active**
+```
+▓▓▓▓▓▓▓▓▓▓
+▓▓Click ▓▓
+▓▓▓▓▓▓▓▓▓▓
+```
+
+### Form Inputs
+
+**Text Input (Empty)**
+```
+[____________________]
+```
+
+**Text Input (Filled)**
+```
+[john@example.com    ]
+```
+
+**Text Input (Focus)**
+```
+┏━━━━━━━━━━━━━━━━━━━━┓
+┃john@example.com│   ┃
+┗━━━━━━━━━━━━━━━━━━━━┛
+```
+
+**Text Input (Error)**
+```
+[invalid-email       ]⚠️
+❌ Please enter valid email
+```
+
+**Text Input (Success)**
+```
+[john@example.com    ]✅
+```
+
+**Text Input (Disabled)**
+```
+[────────────────────]
+```
+
+**Password (Masked)**
+```
+[••••••••            ]
+```
+
+**Password (With Toggle)**
+```
+[••••••••            ]👁️
+```
+
+### Checkboxes & Radios
+
+**Checkbox (Unchecked)**
+```
+[□] Option 1
+```
+
+**Checkbox (Checked)**
+```
+[✓] Option 1
+```
+
+**Checkbox (Indeterminate)**
+```
+[▬] Option 1
+```
+
+**Radio (Unselected)**
+```
+○ Option A
+```
+
+**Radio (Selected)**
+```
+◉ Option A
+```
+
+### Selects & Dropdowns
+
+**Select (Closed)**
+```
+[Choose option ▼]
+```
+
+**Select (Open)**
+```
+[Current option ▼]
+╭────────────────╮
+│ Option 1       │
+│ ● Option 2     │
+│ Option 3       │
+╰────────────────╯
+```
+
+### Sliders
+
+**Slider (Basic)**
+```
+├────────●───────┤
+0%              100%
+```
+
+**Slider (With Value)**
+```
+├────────●───────┤ 45%
+```
+
+**Range Slider**
+```
+├────●────●──────┤
+   20%   80%
+```
+
+## Status Indicators
+
+### Icons
+
+**Success**: ✅ ✓ ●
+**Error**: ❌ ✗ ⚠️ ⛔
+**Warning**: ⚠️ ⚡ △
+**Info**: ℹ️ ⓘ ◉
+**Loading**: ⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏
+
+### Progress Bars
+
+**Loading (40%)**
+```
+████▓▓▓▓▓▓ 40%
+```
+
+**Loading (Indeterminate)**
+```
+▓▓▓░░░░░░░
+```
+
+**Steps**
+```
+● ━━━ ● ━━━ ○ ━━━ ○
+```
+
+### Badges
+
+**Count Badge**
+```
+[Inbox] ●3
+```
+
+**Status Badge**
+```
+● Online
+○ Offline
+```
+
+**Label Badge**
+```
+▓ New ▓
+```
+
+## Data Display
+
+### Lists
+
+**Unordered**
+```
+• Item 1
+• Item 2
+• Item 3
+```
+
+**Ordered**
+```
+1. First
+2. Second
+3. Third
+```
+
+**Nested**
+```
+• Parent
+  ├─ Child 1
+  ├─ Child 2
+  └─ Child 3
+```
+
+### Tables
+
+**Simple**
+```
+┌─────┬─────┬─────┐
+│ A   │ B   │ C   │
+├─────┼─────┼─────┤
+│ 1   │ 2   │ 3   │
+│ 4   │ 5   │ 6   │
+└─────┴─────┴─────┘
+```
+
+**With Header**
+```
+╔═══════╦═══════╦═══════╗
+║ Name  ║ Email ║ Status║
+╠═══════╬═══════╬═══════╣
+║ Alice ║ a@... ║ ✓     ║
+║ Bob   ║ b@... ║ ○     ║
+╚═══════╩═══════╩═══════╝
+```
+
+### Cards
+
+**Basic**
+```
+╭─────────────╮
+│ Title       │
+├─────────────┤
+│ Content...  │
+╰─────────────╯
+```
+
+**With Actions**
+```
+╭─────────────────────╮
+│ Card Title          │
+├─────────────────────┤
+│ Content goes here   │
+│                     │
+│        [Action] ─┐  │
+╰─────────────────────╯
+```
+
+**Metric Card**
+```
+╭───────────╮
+│ Revenue   │
+├───────────┤
+│ $24,567   │
+│ +12.5% ↗  │
+╰───────────╯
+```
+
+## Navigation
+
+### Tabs
+
+**Horizontal**
+```
+[Active] [Tab 2] [Tab 3]
+─────────
+Content for active tab
+```
+
+**Vertical**
+```
+┌─ ● Tab 1
+├─ ○ Tab 2
+└─ ○ Tab 3
+```
+
+### Breadcrumbs
+
+```
+Home > Products > Details
+```
+
+### Pagination
+
+```
+‹ Prev  [1] 2 3 4 5  Next ›
+```
+
+### Menu
+
+**Dropdown**
+```
+File ▼
+╭──────────╮
+│ New      │
+│ Open     │
+│ Save     │
+├──────────┤
+│ Exit     │
+╰──────────╯
+```
+
+**Sidebar**
+```
+╭─────────╮
+│ • Home  │
+│ • Users │
+│ • Data  │
+│ • Info  │
+╰─────────╯
+```
+
+## Modals & Overlays
+
+### Modal
+
+**Simple**
+```
+╔═══════════════════╗
+║ Modal Title       ║
+╠═══════════════════╣
+║ Content here...   ║
+║                   ║
+║     [OK] [Cancel] ║
+╚═══════════════════╝
+```
+
+**With Close**
+```
+╔═══════════════════╗✕
+║ Title             ║
+╠═══════════════════╣
+║ Content...        ║
+╚═══════════════════╝
+```
+
+### Toast/Alert
+
+**Success**
+```
+╭─────────────────╮
+│ ✅ Saved!       │
+╰─────────────────╯
+```
+
+**Error**
+```
+╭─────────────────────╮
+│ ❌ Error: Try again │
+╰─────────────────────╯
+```
+
+**Warning**
+```
+╭────────────────────╮
+│ ⚠️ Warning message │
+╰────────────────────╯
+```
+
+## Arrows & Indicators
+
+### Directional
+```
+↑ ↓ ← →
+↗ ↘ ↙ ↖
+⬆ ⬇ ⬅ ➡
+▲ ▼ ◀ ▶
+```
+
+### Trend
+```
+↗️ Up trend
+→ Flat
+↘️ Down trend
+```
+
+### Expand/Collapse
+```
+▼ Expanded
+▶ Collapsed
+```
+
+## Spacing & Alignment
+
+### Padding Example
+```
+╭──────────────╮
+│              │  ← 1 line padding
+│   Content    │
+│              │  ← 1 line padding
+╰──────────────╯
+```
+
+### Grid Alignment
+```
+╭────╮╭────╮╭────╮  ← No gap
+╭────╮ ╭────╮ ╭────╮  ← 1 char gap
+╭────╮  ╭────╮  ╭────╮  ← 2 char gap
+```
+
+## Tips for Consistent Patterns
+
+1. **Choose one border style per component** - Don't mix light/rounded/heavy
+2. **Use consistent spacing** - Multiples of 4 characters work well
+3. **Align related elements** - Keep boxes at same width when stacked
+4. **Test in monospace** - Always preview in monospace font
+5. **Consider state transitions** - Visual changes should be clear
+
+## Copy-Paste Ready
+
+```
+Light box: ┌─┐│└┘
+Rounded: ╭─╮│╰╯
+Double: ╔═╗║╚╝
+Heavy: ┏━┓┃┗┛
+
+Checkbox: [□] [✓]
+Radio: ○ ◉
+Status: ✅ ❌ ⚠️ ℹ️
+Arrows: ↑↓←→ ↗↘
+```
+
+Use these patterns to create beautiful, consistent uxscii components!