Architecture Overview

Core Concepts

Fluxwing vs uxscii

Think: uxscii is the language. Fluxwing is the designer who speaks that language.

The Two-File System

Every uxscii component consists of exactly two files that work together:

1. The .uxm File (JSON Metadata)

Contains structured data about the component:

{
  "id": "submit-button",
  "type": "button",
  "version": "1.0.0",
  "metadata": {
    "name": "Submit Button",
    "description": "Primary action button",
    "created": "2024-10-11T12:00:00Z",
    "author": "Fluxwing Designer"
  },
  "props": {
    "text": "Submit"
  },
  "behavior": {
    "states": [
      {
        "name": "default",
        "properties": {
          "border": "rounded",
          "background": "primary",
          "textColor": "white"
        }
      }
    ]
  },
  "accessibility": {
    "role": "button",
    "focusable": true,
    "keyboardShortcuts": ["Enter", "Space"]
  },
  "ascii": {
    "templateFile": "submit-button.md",
    "width": 20,
    "height": 3
  }
}

2. The .md File (ASCII Template)

Contains visual representation with variable placeholders:

# Submit Button

## Default State

```
╭──────────────────╮
│   {{text}}       │
╰──────────────────╯
```

## Hover State

```
╔══════════════════╗
║   {{text}}       ║
╚══════════════════╝
```

Why Two Files?

• Separation of concerns: Data (what) vs Presentation (how)
• Human + AI readable: JSON for machines, ASCII for humans
• Progressive fidelity: Start with ASCII, add metadata later
• Version control friendly: Text diffs show meaningful changes

Data Location Philosophy

Understanding where files live and why is critical to using Fluxwing effectively.

Bundled Templates (READ-ONLY)

skills/{skill-name}/         # In plugin or installed location
├── templates/               # 11 component templates
├── schemas/                 # JSON Schema validation
└── docs/                    # Documentation

These are reference materials:

• ✅ Pre-validated and tested
• ✅ Bundled with skill installation
• ❌ NEVER modified by skills or users
• ❌ NEVER written to

Project Workspace (READ-WRITE)

./fluxwing/
├── components/              # Your created components
│   ├── submit-button.uxm
│   ├── submit-button.md
│   └── ...
├── screens/                 # Your created screens
│   ├── login-screen.uxm
│   ├── login-screen.md
│   ├── login-screen.rendered.md
│   └── ...
└── library/                 # Customized template copies
    └── ...

This is YOUR workspace:

• ✅ Fully editable
• ✅ Version controlled with your code
• ✅ Where ALL skill/agent outputs go
• ✅ Never deleted during uninstallation

Component Hierarchy

Atomic Components

Self-contained with no dependencies:

• button
• input
• badge
• icon
• text

Composite Components

Reference other components:

{
  "id": "login-form",
  "type": "form",
  "components": [
    { "ref": "email-input" },
    { "ref": "password-input" },
    { "ref": "submit-button" }
  ]
}

Screens (Top-Level)

Complete UI layouts using type "container":

{
  "id": "login-screen",
  "type": "container",
  "layout": "vertical",
  "components": [
    { "ref": "navigation-header" },
    { "ref": "login-form" },
    { "ref": "footer" }
  ]
}

Screens Add a Third File

Screens include .rendered.md to show visual intent:

login-screen.md          # Template with {{variables}}
login-screen.rendered.md # Example with REAL data

Templates with variables don't show visual intent. Rendered examples use actual names, emails, numbers to show spacing and layout.

Schema Validation

All components must validate against the JSON Schema:

skills/fluxwing-component-creator/schemas/uxm-component.schema.json

Validation Rules

Required Fields

• id, type, version
• metadata (name, created)
• props
• ascii (templateFile, width, height)

Optional Fields

• behavior (states, interactions)
• layout (alignment, spacing)
• extends (parent component)
• slots (content insertion points)

Variable Substitution

Templates use {{variableName}} syntax for dynamic content:

In .md File

```
╭──────────────────╮
│ {{username}}     │
│ {{email}}        │
╰──────────────────╯
```

In .uxm File

"props": {
  "username": "John Doe",
  "email": "john@example.com"
}

Rules

• All template variables MUST be defined in .uxm
• Variables in .uxm but not .md are OK (runtime binding)
• Variables in .md but not .uxm cause validation errors

The Derivation Model

Fluxwing uses inheritance instead of duplication.

Traditional Tools (Duplication)

primary-button (original)
  → Copy to create large-button
  → Copy to create small-button
  → Copy to create danger-button

Result: 4 separate files that drift apart

Fluxwing (Derivation)

primary-button (base)
  ↓
large-button (extends: "primary-button", size: "large")
small-button (extends: "primary-button", size: "small")
danger-button (extends: "primary-button", variant: "danger")

Result: Single source of truth, variations inherit changes

Using extends

{
  "id": "large-button",
  "extends": "primary-button",
  "props": {
    "size": "large"
  }
}

Change the base, all derived components inherit the change automatically.

Accessibility Requirements

All interactive components should include:

"accessibility": {
  "role": "button",
  "ariaLabel": "Submit form",
  "focusable": true,
  "keyboardShortcuts": ["Enter", "Space"]
}

Recommended Fields

Repository Structure

fluxwing-skills/                 # Claude Code Plugin
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest
├── skills/                      # 6 Skills
│   ├── fluxwing-component-creator/
│   │   ├── SKILL.md             # Skill workflow
│   │   ├── templates/           # 11 component templates
│   │   ├── schemas/             # JSON Schema
│   │   └── docs/                # Documentation modules
│   ├── fluxwing-library-browser/
│   ├── fluxwing-component-expander/
│   ├── fluxwing-screen-scaffolder/
│   ├── fluxwing-component-viewer/
│   └── fluxwing-screenshot-importer/
├── scripts/
│   ├── install.sh               # Development installer
│   └── uninstall.sh             # Removal script
├── marketplace.json             # Plugin marketplace catalog
├── README.md                    # User-facing overview
├── INSTALL.md                   # Installation guide
└── CLAUDE.md                    # Architecture guide

Performance Considerations

Documentation Loading

Load docs from skills as needed, not all upfront. Skills include modular documentation (500-800 tokens each).

Schema Validation

Compile schema once, reuse validator across components.

File Operations

Batch reads/writes when possible. Use pre-built indexes (library browser uses template index for 10x speedup).

Agent Spawning

Use parallel Task calls for independent operations. Screen Scaffolder spawns N agents in parallel (one per component).

Design Principles

1. Self-Contained Portability

• All schemas, examples, docs bundled in skills
• No external dependencies at runtime
• Single-script installation

2. Progressive Fidelity

• Start with ASCII layout (fast iteration)
• Add structured metadata (component types, props)
• Enhance with accessibility, interactions, animations

3. AI-Human Collaboration

• AI generates ASCII layouts instantly
• Humans give natural feedback on visuals
• Designs converge through conversation

4. Derivation Not Duplication

• Components extend base components
• Change base once, variations inherit
• Libraries grow organically through references

Next Steps

• Getting Started - Installation and first component
• Command Reference - All 6 skills documented
• How Skills Work - Understanding the agent system
• Back to Home