gh-trabian-fluxwing-skills/skills/fluxwing-component-viewer/docs/02-core-concepts.md

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)

{
  "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

{
  "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)

"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:

"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

/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

/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:

"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:

{
  "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!