Initial commit

skills/fluxwing-component-creator/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-creator/docs/06-ascii-patterns.md

@@ -0,0 +1,792 @@
+# 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
+
+**CRITICAL FOR SCREEN RENDERING**: These rules prevent alignment issues in `.rendered.md` files.
+
+### 1. Boundary Alignment - Content MUST Stay Inside Borders
+
+**Golden Rule**: All text and content MUST be contained within component borders. Nothing floats outside.
+
+**❌ INCORRECT - Text outside borders:**
+```
+╔════════════════════════════════════════╗
+║                                        ║
+║        Video Title Here                ║
+║                            ┌─────────┐ ║
+║                            │  12:34  │ ║
+╚════════════════════════════└─────────┘═╝
+
+Video Title Here                            ← WRONG: Outside the box!
+MrBeast ✓                                   ← WRONG: Floating metadata!
+24M views · 2 days ago
+```
+
+**✅ CORRECT - All content inside borders:**
+```
+╔════════════════════════════════════════╗
+║                                        ║
+║        Video Title Here                ║
+║                            ┌─────────┐ ║
+║                            │  12:34  │ ║
+║                                        ║
+║  Video Title Here                      ║
+║  MrBeast ✓                             ║
+║  24M views · 2 days ago                ║
+╚════════════════════════════════════════╝
+```
+
+**Rule**: If a box has borders, ALL related content must appear between those borders.
+
+### 2. Vertical Spacing - Consistent Gaps Between Components
+
+**Standard vertical gaps:**
+- **1 line** - Tight spacing (related items within same section)
+- **2 lines** - Standard spacing (between different components)
+- **3 lines** - Section dividers (major layout breaks)
+
+**❌ INCORRECT - Inconsistent spacing:**
+```
+╭────────────╮
+│ Button 1   │
+╰────────────╯
+╭────────────╮
+│ Button 2   │
+╰────────────╯
+
+
+╭────────────╮
+│ Button 3   │
+╰────────────╯
+```
+
+**✅ CORRECT - Consistent 2-line gaps:**
+```
+╭────────────╮
+│ Button 1   │
+╰────────────╯
+
+╭────────────╮
+│ Button 2   │
+╰────────────╯
+
+╭────────────╮
+│ Button 3   │
+╰────────────╯
+```
+
+**Nested component spacing:**
+```
+╭─────────────────────────────────╮
+│ Outer Container                 │
+│                                 │  ← 1 line padding
+│  ╭─────────────────────────╮   │
+│  │ Inner Component         │   │
+│  ╰─────────────────────────╯   │
+│                                 │  ← 1 line padding
+╰─────────────────────────────────╯
+```
+
+### 3. Horizontal Alignment - Consistent Padding and Text Columns
+
+**Standard left padding:**
+- **2 characters** - Minimum readable padding (compact layouts)
+- **4 characters** - Standard padding (default for most screens)
+- **6 characters** - Generous padding (spacious layouts)
+
+**❌ INCORRECT - No padding, text against border:**
+```
+╭────────────────────╮
+│Title               │  ← No space after │
+│Content here        │
+╰────────────────────╯
+```
+
+**✅ CORRECT - Consistent 2-char padding:**
+```
+╭────────────────────╮
+│  Title             │  ← 2 spaces after │
+│  Content here      │
+╰────────────────────╯
+```
+
+**Text column alignment:**
+```
+╭──────────────────────────────────╮
+│  Label:        Value             │  ← Aligned columns
+│  Name:         Sarah Johnson     │
+│  Email:        sarah@example.com │
+│  Status:       Active            │
+╰──────────────────────────────────╯
+```
+
+**Center alignment for titles:**
+```
+╭──────────────────────────────────╮
+│                                  │
+│         Welcome Back             │  ← Centered
+│      Sign in to continue         │  ← Centered
+│                                  │
+╰──────────────────────────────────╯
+```
+
+**Right alignment for metadata:**
+```
+╭──────────────────────────────────╮
+│  Post Title                      │
+│  u/username · 3h ago       [123] │  ← Right-aligned vote count
+╰──────────────────────────────────╯
+```
+
+### 4. Grid Layouts - Multi-Column Screens
+
+**2-column grid with proper spacing:**
+
+**❌ INCORRECT - Inconsistent gaps, misaligned:**
+```
+╭──────────╮╭──────────╮  ← No gap
+│ Card 1   ││ Card 2   │
+╰──────────╯╰──────────╯
+
+╭──────────╮   ╭──────────╮  ← Different gap
+│ Card 3   │   │ Card 4   │
+╰──────────╯   ╰──────────╯
+```
+
+**✅ CORRECT - Consistent 2-char gaps, aligned columns:**
+```
+╭──────────╮  ╭──────────╮
+│ Card 1   │  │ Card 2   │
+╰──────────╯  ╰──────────╯
+
+╭──────────╮  ╭──────────╮
+│ Card 3   │  │ Card 4   │
+╰──────────╯  ╰──────────╯
+```
+
+**3-column grid:**
+```
+╭────────╮  ╭────────╮  ╭────────╮
+│ Card 1 │  │ Card 2 │  │ Card 3 │
+╰────────╯  ╰────────╯  ╰────────╯
+
+╭────────╮  ╭────────╮  ╭────────╮
+│ Card 4 │  │ Card 5 │  │ Card 6 │
+╰────────╯  ╰────────╯  ╰────────╯
+```
+
+**Sidebar + main layout:**
+```
+╭─────────╮  ╭──────────────────────────────╮
+│ Sidebar │  │ Main Content                 │
+│         │  │                              │
+│ • Home  │  │  ╭─────────────────────╮     │
+│ • Users │  │  │ Content Card        │     │
+│ • Data  │  │  ╰─────────────────────╯     │
+│         │  │                              │
+╰─────────╯  ╰──────────────────────────────╯
+```
+
+### 5. Screen Composition Rules
+
+**Full screen example combining all rules:**
+
+```
+╔══════════════════════════════════════════════════════╗
+║                                                      ║
+║                   Screen Title                       ║  ← Centered, 1 line padding
+║                                                      ║
+╠══════════════════════════════════════════════════════╣
+║  Navigation Bar                                      ║  ← 2-char padding
+╠══════════════════════════════════════════════════════╣
+║                                                      ║  ← 1 line section gap
+║  ╭────────────────────────╮  ╭────────────────────╮ ║
+║  │  Left Card             │  │  Right Card        │ ║  ← 2-col grid, 2-char gap
+║  │                        │  │                    │ ║
+║  │  Content with 2-char   │  │  Aligned content   │ ║  ← All content inside borders
+║  │  left padding          │  │  stays in bounds   │ ║
+║  │                        │  │                    │ ║
+║  ╰────────────────────────╯  ╰────────────────────╯ ║
+║                                                      ║  ← 2 line component gap
+║                                                      ║
+║  ╭──────────────────────────────────────────────╮   ║
+║  │  Full-width Component                        │   ║  ← Centered in parent
+║  │                                              │   ║
+║  │  Text content properly padded                │   ║
+║  │                                              │   ║
+║  ╰──────────────────────────────────────────────╯   ║
+║                                                      ║
+╚══════════════════════════════════════════════════════╝
+```
+
+### 6. Common Patterns - Feed Layouts
+
+**YouTube-style feed (CORRECT):**
+```
+╔═══════════════════════════╗  ╔═══════════════════════════╗
+║                           ║  ║                           ║
+║     Thumbnail Area        ║  ║     Thumbnail Area        ║
+║                           ║  ║                           ║
+║               ┌────────┐  ║  ║               ┌────────┐  ║
+║               │ 12:34  │  ║  ║               │ 8:45   │  ║
+║               └────────┘  ║  ║               └────────┘  ║
+║                           ║  ║                           ║
+║  DON'T TRY THIS           ║  ║  Watermelon Candy VS REAL ║
+║                           ║  ║                           ║
+║  MrBeast ✓                ║  ║  Crafty Panda ✓           ║
+║  24M views · 2 days ago   ║  ║  543K views · 1 day ago   ║
+╚═══════════════════════════╝  ╚═══════════════════════════╝
+```
+
+**Reddit-style post feed (CORRECT):**
+```
+╭──────────────────────────────────────────────────────╮
+│  ▲  Which bank offers best savings in 2025?         │
+│ 342                                                  │
+│  ▼  Posted by u/financeguru · 3h ago                │
+│                                                      │
+│      I've been researching high-yield savings        │
+│      accounts and comparing rates...                 │
+│                                                      │
+│      💬 156 comments  📤 Share  🔖 Save              │
+╰──────────────────────────────────────────────────────╯
+
+╭──────────────────────────────────────────────────────╮
+│  ▲  PSA: Chase added Zelle fraud protection          │
+│ 289                                                  │
+│  ▼  Posted by u/bankwatcher · 5h ago                │
+│                                                      │
+│      Just got an email that Chase is now offering    │
+│      Zelle fraud reimbursement...                    │
+│                                                      │
+│      💬 87 comments  📤 Share  🔖 Save               │
+╰──────────────────────────────────────────────────────╯
+```
+
+### 7. Overflow Handling
+
+**When content is too long:**
+
+**❌ INCORRECT - Breaking borders:**
+```
+╭──────────────╮
+│ This is a very long title that goes past the border │
+╰──────────────╯
+```
+
+**✅ CORRECT - Truncate with ellipsis:**
+```
+╭──────────────────────────╮
+│ This is a very long ti...│
+╰──────────────────────────╯
+```
+
+**✅ CORRECT - Wrap within bounds:**
+```
+╭──────────────────────────╮
+│ This is a very long      │
+│ title that wraps to      │
+│ multiple lines           │
+╰──────────────────────────╯
+```
+
+### 8. Alignment Checklist for Screen Composition
+
+Before saving any `.rendered.md` file, verify:
+
+- [ ] **Boundary**: All text is inside component borders (no floating text)
+- [ ] **Vertical**: Consistent gaps between components (1-3 lines)
+- [ ] **Horizontal**: Consistent left padding (2-4 chars minimum)
+- [ ] **Grid**: Multi-column layouts have aligned columns and consistent gaps
+- [ ] **Overflow**: Long content is truncated or wrapped, never breaking borders
+- [ ] **Nested**: Inner components have proper padding from outer containers
+- [ ] **Metadata**: Related info (timestamps, counts) aligned consistently
+
+### Quick Reference - Standard Measurements
+
+```
+Padding (horizontal):   2-4 chars (standard)
+Gaps (vertical):        1-2 lines (standard)
+Grid gaps:              2 chars (between columns)
+Section breaks:         3 lines
+Border padding:         1 line top/bottom
+```
+
+## 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!

skills/fluxwing-component-creator/docs/07-schema-reference.md

@@ -0,0 +1,205 @@
+# Schema Reference
+
+Pointer to the definitive uxscii component schema and how to use it.
+
+## The Schema File
+
+**Location**: `../schema/uxm-component.schema.json`
+
+This is the **definitive source of truth** for the uxscii `.uxm` file format.
+
+## What the Schema Defines
+
+The schema specifies:
+- All valid field names and types
+- Required vs optional fields
+- Validation rules (min/max, patterns, enums)
+- Nested object structures
+- Field descriptions
+
+## How to Use the Schema
+
+### For Reference
+
+When creating components, refer to the schema to understand:
+- What fields are available
+- What values are allowed
+- What's required vs optional
+
+### For Autocompletion
+
+Many editors can use the schema for:
+- Field suggestions
+- Type checking
+- Documentation on hover
+
+Add to your `.uxm` file:
+```json
+{
+  "$schema": "../data/schema/uxm-component.schema.json",
+  ...
+}
+```
+
+## Key Schema Sections
+
+### Required Root Fields
+
+```
+id          - Component identifier (kebab-case, 2-64 chars)
+type        - Component type (enum or "custom")
+version     - Semantic version (X.Y.Z)
+metadata    - Component metadata object
+props       - Component properties object
+ascii       - ASCII template reference
+```
+
+### Metadata Object (required fields)
+
+```
+name        - Human-readable name (1-100 chars)
+created     - ISO 8601 timestamp
+modified    - ISO 8601 timestamp
+```
+
+### Metadata Object (optional fields)
+
+```
+description - Component description (max 500 chars)
+author      - Creator name (max 100 chars)
+tags        - Array of search tags (max 10)
+category    - Component category (enum)
+```
+
+### ASCII Object (required)
+
+```
+templateFile - Template filename (must end in .md)
+width        - Character width (1-120)
+height       - Character height (1-50)
+```
+
+### ASCII Object (optional)
+
+```
+variables    - Array of template variable definitions
+```
+
+### Behavior Object (optional)
+
+```
+states       - Array of component states
+interactions - Array of user interactions
+animations   - Array of animation definitions
+accessibility- Accessibility attributes
+```
+
+## Component Types (Enum)
+
+Valid `type` values:
+```
+button, input, card, navigation, form, list, modal,
+table, badge, alert, container, text, image, divider, custom
+```
+
+## Categories (Enum)
+
+Valid `metadata.category` values:
+```
+layout, input, display, navigation, feedback,
+utility, overlay, custom
+```
+
+## Variable Types (Enum)
+
+Valid `ascii.variables[].type` values:
+```
+string, number, boolean, color, size, array, object
+```
+
+## Quick Reference Examples
+
+### Minimal Valid Component
+
+```json
+{
+  "id": "simple",
+  "type": "button",
+  "version": "1.0.0",
+  "metadata": {
+    "name": "Simple",
+    "created": "2024-01-01T00:00:00Z",
+    "modified": "2024-01-01T00:00:00Z"
+  },
+  "props": {},
+  "ascii": {
+    "templateFile": "simple.md",
+    "width": 10,
+    "height": 3
+  }
+}
+```
+
+### Complete Component
+
+See `../examples/primary-button.uxm` for a fully-featured example using all available fields.
+
+## Schema Version
+
+Current schema version: **1.1.0**
+
+Schema follows semantic versioning:
+- Major: Breaking changes to structure
+- Minor: New optional fields
+- Patch: Documentation or validation updates
+
+## Validation Rules Summary
+
+### ID Rules
+- Pattern: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
+- Length: 2-64 characters
+- Format: kebab-case only
+
+### Version Rules
+- Pattern: `^\d+\.\d+\.\d+(?:-[a-zA-Z0-9-]+)?$`
+- Examples: `1.0.0`, `2.1.3`, `1.0.0-beta`
+
+### Timestamp Rules
+- Format: ISO 8601 date-time
+- Example: `2024-10-11T12:00:00Z`
+
+### Variable Name Rules
+- Pattern: `^[a-zA-Z][a-zA-Z0-9_]*$`
+- Format: camelCase recommended
+- Examples: `text`, `userName`, `isDisabled`
+
+## Common Schema Errors
+
+**"Additional property not allowed"**
+- You used a field name that doesn't exist in the schema
+- Check field spelling and location in object hierarchy
+
+**"Missing required property"**
+- You omitted a required field
+- Add the field with a valid value
+
+**"Value does not match pattern"**
+- Field value doesn't match regex pattern
+- Check format requirements (kebab-case, semver, etc.)
+
+**"Value not in enum"**
+- You used a value not in the allowed list
+- Use one of the valid enum values
+
+## Deep Dive
+
+For comprehensive schema documentation, see:
+- **Full guide**: `UXSCII_SCHEMA_GUIDE.md` (detailed explanations)
+- **Agent guide**: `UXSCII_AGENT_GUIDE.md` (practical examples)
+
+## Next Steps
+
+- **View schema**: Open `../schema/uxm-component.schema.json`
+- **See examples**: Browse `../examples/*.uxm`
+
+The schema ensures all uxscii components are compatible and machine-readable!