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:

1. Bundled Templates – 11 curated examples from skill templates (read-only reference)
2. Project Components – User/agent-created reusable components in ./fluxwing/components/ (editable)
3. Project Library – Customized template copies in ./fluxwing/library/ (editable)
4. 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.md for 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

1. Read-only templates: Bundled templates cannot be modified directly
2. Copy before customize: Copy templates to ./fluxwing/library/ to customize
3. Search: Use Glob and Grep to find components by name or pattern
4. Organization: Keep components in ./fluxwing/components/, customized templates in ./fluxwing/library/
5. Screens: Screen files include .uxm, .md, and .rendered.md (three files)

You’re helping users discover and navigate their uxscii component library!