Initial commit

2025-11-30 09:02:33 +08:00
commit 0c40192593
82 changed files with 18699 additions and 0 deletions
--- a/skills/fluxwing-component-viewer/SKILL.md
+++ b/skills/fluxwing-component-viewer/SKILL.md
@@ -0,0 +1,300 @@
+---
+name: Fluxwing Component Viewer
+description: View detailed information about a specific uxscii component including metadata, states, props, and ASCII preview. Use when working with .uxm files, when user wants to see, view, inspect, or get details about a .uxm component.
+version: 0.0.1
+author: Trabian
+allowed-tools: Read, Glob, Grep
+---
+
+# 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:
+
+1. **Project Components**: `./fluxwing/components/[name].uxm`
+   - User/agent-created custom components
+   - Fully editable
+   - Tag as: "Your Component"
+
+2. **Project Library**: `./fluxwing/library/[name].uxm`
+   - Customized copies of bundled templates
+   - Fully editable
+   - Tag as: "Your Library"
+
+3. **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.description` field from .uxm file
+- Keep it concise (1-2 lines)
+
+**Component Details:**
+- **Type**: Direct from .uxm `type` field
+- **Props**: List prop names with types in parentheses
+  - Format: `propName (type)`
+  - Example: `text (string), disabled (boolean)`
+- **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:
+1. Count total states/sections in template
+2. Show first 2-3 states completely
+3. Add summary line: `[... N more states]`
+4. 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.md` for component fundamentals
+
+You're helping users understand their uxscii components in detail!
--- a/skills/fluxwing-component-viewer/docs/02-core-concepts.md
+++ b/skills/fluxwing-component-viewer/docs/02-core-concepts.md
@@ -0,0 +1,292 @@
+# Core Concepts - Understanding uxscii
+
+The fundamental concepts you need to understand the uxscii standard.
+
+## The Philosophy
+
+**uxscii** is an AI-native design markup language that combines:
+- **Human-readable** ASCII art (visual representation)
+- **Machine-parseable** JSON metadata (component definition)
+- **Version-control friendly** text files (meaningful diffs)
+
+## The Two-File System
+
+Every component consists of exactly TWO files that work together:
+
+### File 1: `.uxm` (Component Metadata)
+
+JSON file containing:
+- **Identity**: ID, type, version
+- **Metadata**: Name, description, author, timestamps
+- **Properties**: Configurable props with defaults
+- **Behavior**: States, interactions, accessibility
+- **ASCII Reference**: Template file, dimensions, variables
+
+**Purpose**: Tells agents WHAT the component is and HOW it behaves.
+
+### File 2: `.md` (Visual Template)
+
+Markdown file containing:
+- **ASCII Art**: Visual representation of the component
+- **Variables**: `{{variableName}}` placeholders for dynamic content
+- **States**: Visual variants (default, hover, focus, disabled, etc.)
+- **Documentation**: Usage examples and variable descriptions
+
+**Purpose**: Shows agents WHAT the component looks like.
+
+## How They Connect
+
+```
+submit-button.uxm says:
+  "ascii": {
+    "templateFile": "submit-button.md",  ← Points to template
+    "variables": [
+      {"name": "text", "type": "string"}  ← Defines variables
+    ]
+  }
+
+submit-button.md contains:
+  ╭──────────────────╮
+  │   {{text}}       │  ← Uses the variable
+  ╰──────────────────╯
+```
+
+The `.uxm` **defines** variables, the `.md` **uses** them.
+
+## Component Anatomy
+
+### Minimal Required Fields (.uxm)
+
+```json
+{
+  "id": "kebab-case-name",           // Required: Unique identifier
+  "type": "button|input|card|...",   // Required: Component type
+  "version": "1.0.0",                // Required: Semantic version
+  "metadata": {
+    "name": "Human Name",            // Required: Display name
+    "created": "ISO-timestamp",      // Required: Creation date
+    "modified": "ISO-timestamp"      // Required: Last modified
+  },
+  "props": {},                       // Required: Can be empty object
+  "ascii": {
+    "templateFile": "name.md",       // Required: Template filename
+    "width": 20,                     // Required: Character width
+    "height": 3                      // Required: Character height
+  }
+}
+```
+
+### Optional But Recommended Fields
+
+```json
+{
+  "metadata": {
+    "description": "What this component does",
+    "author": "Your name",
+    "tags": ["searchable", "keywords"],
+    "category": "input|display|layout|..."
+  },
+  "behavior": {
+    "states": [/* multiple states */],
+    "interactions": [/* user interactions */],
+    "accessibility": {/* ARIA attributes */}
+  },
+  "extends": "base-component-id"  // Component inheritance
+}
+```
+
+## Variable Substitution
+
+### In .uxm (Definition)
+```json
+"props": {
+  "text": "Click me",        // Default value
+  "disabled": false
+},
+"ascii": {
+  "variables": [
+    {
+      "name": "text",
+      "type": "string",
+      "required": true,
+      "description": "Button label"
+    }
+  ]
+}
+```
+
+### In .md (Usage)
+```
+╭──────────────────╮
+│   {{text}}       │  ← Replaced with prop value
+╰──────────────────╯
+```
+
+### Result
+```
+╭──────────────────╮
+│   Click me       │  ← Actual rendered output
+╰──────────────────╯
+```
+
+## States and Behaviors
+
+Components can have multiple visual states:
+
+```json
+"behavior": {
+  "states": [
+    {
+      "name": "default",
+      "properties": {"border": "solid"}
+    },
+    {
+      "name": "hover",
+      "properties": {"border": "highlighted"},
+      "triggers": ["mouseenter"]
+    },
+    {
+      "name": "disabled",
+      "properties": {"border": "dashed", "opacity": 0.5}
+    }
+  ]
+}
+```
+
+Each state can have a corresponding ASCII representation in the `.md` file.
+
+## Two-Phase Component Creation
+
+Fluxwing optimizes for fast MVP prototyping with a two-phase approach:
+
+### Phase 1: Create with Default State
+
+When you create a component, it starts with **only the default state**:
+- Fast creation for quick prototyping
+- MVP-ready for early discussions
+- Minimal file size and complexity
+
+```bash
+/fluxwing-create submit-button
+# Creates component with default state only
+```
+
+### Phase 2: Expand with Interactive States
+
+After MVP validation, add interaction states on demand:
+- Adds hover, focus, disabled states
+- Smart defaults based on component type
+- Preserves all existing data
+
+```bash
+/fluxwing-expand-component submit-button
+# Adds hover, active, disabled states
+```
+
+### Why Two Phases?
+
+**Benefits**:
+- **60-80% faster** component creation
+- Focus on core functionality first
+- Add polish when needed, not upfront
+- Cleaner diffs in version control
+
+**Workflow**:
+```
+1. Create → Default state only (fast)
+2. Discuss → Review with stakeholders
+3. Validate → Confirm design works
+4. Expand → Add interactive states (polish)
+```
+
+This approach aligns with agile development: ship fast, iterate based on feedback.
+
+## Component Types
+
+Standard types:
+- **button**: Clickable action triggers
+- **input**: Text entry fields
+- **card**: Content containers
+- **navigation**: Menu and navigation
+- **form**: Multi-field forms
+- **list**: Data displays
+- **modal**: Overlay dialogs
+- **table**: Tabular data
+- **badge**: Small indicators
+- **alert**: Notifications
+- **container**: Layout wrappers
+- **text**: Text displays
+- **image**: Image placeholders
+- **divider**: Visual separators
+- **custom**: Anything else
+
+## Naming Conventions
+
+### Component IDs (kebab-case)
+- ✓ `submit-button`
+- ✓ `email-input`
+- ✓ `user-profile-card`
+- ✗ `submitButton` (camelCase)
+- ✗ `Submit Button` (spaces)
+
+### Variables (camelCase)
+- ✓ `userName`
+- ✓ `isDisabled`
+- ✓ `maxLength`
+- ✗ `user-name` (kebab-case)
+- ✗ `user_name` (snake_case)
+
+### Files (kebab-case + extension)
+- ✓ `submit-button.uxm`
+- ✓ `submit-button.md`
+- ✗ `submitButton.uxm`
+
+## Accessibility
+
+Every interactive component should include accessibility attributes:
+
+```json
+"behavior": {
+  "accessibility": {
+    "role": "button",              // ARIA role
+    "ariaLabel": "Submit form",    // Screen reader label
+    "focusable": true,             // Can receive focus
+    "keyboardSupport": ["Enter", "Space"]  // Key bindings
+  }
+}
+```
+
+## Composition
+
+Components can reference other components to create screens:
+
+```json
+{
+  "id": "login-screen",
+  "type": "container",
+  "props": {
+    "components": [
+      "email-input",    // References another component
+      "password-input",
+      "submit-button"
+    ]
+  }
+}
+```
+
+## Key Takeaways
+
+1. **Two files, one component**: `.uxm` for logic, `.md` for visuals
+2. **Variables bridge them**: Defined in `.uxm`, used in `.md`
+3. **States create interactivity**: Multiple visual representations
+4. **Types organize components**: Standard categories for consistency
+5. **Naming matters**: Conventions ensure compatibility
+6. **Accessibility is essential**: ARIA roles for all interactive elements
+
+## Next Steps
+
+- **See it in action**: Check `../examples/primary-button.{uxm,md}`
+- **Create your own**: Follow `03-component-creation.md`
+- **Learn patterns**: Browse `06-ascii-patterns.md`
+
+You now understand the foundation of uxscii!