Quick Start

What You Need to Know

UXSCII is a two-file system for AI-native component design:

• .uxm files: JSON metadata defining component behavior, props, states
• .md files: ASCII visual templates with variable substitution

30-Second Component Creation

# 1. Create the JSON metadata file
cat > simple-button.uxm << 'EOF'
{
  "id": "simple-button",
  "type": "button",
  "version": "1.0.0",
  "metadata": {
    "name": "Simple Button",
    "created": "2024-01-15T10:00:00Z",
    "modified": "2024-01-15T10:00:00Z"
  },
  "props": {
    "text": "Click me"
  },
  "ascii": {
    "templateFile": "simple-button.md",
    "width": 12,
    "height": 3
  }
}
EOF

# 2. Create the ASCII template
cat > simple-button.md << 'EOF'
```
▓▓▓▓▓▓▓▓▓▓▓▓
▓ {{text}} ▓
▓▓▓▓▓▓▓▓▓▓▓▓
```
EOF

# 3. Validate
uxscii validate simple-button.uxm

Essential Commands

# Validate component
uxscii validate component.uxm

# Lint for best practices
uxscii lint component.uxm --strict

# Test template rendering
uxscii template component.md --validate

# Get component with template
uxscii uxm get component

Core Concepts

The UXSCII Philosophy

1. AI-Native Design: Components designed for machine parsing and generation
2. Human-Readable: ASCII representations anyone can understand
3. Version Control Friendly: Text-based, meaningful diffs
4. Tool Independent: Open specification, not tied to specific software

Key Principles for Agents

1. Start Simple: Begin with minimal required fields, add complexity incrementally
2. Be Consistent: Follow naming conventions and pattern libraries
3. Think States: Design for default, hover, focus, disabled states
4. Document Everything: Include descriptions, examples, and usage notes
5. Validate Early: Use CLI tools to catch issues immediately

Component Creation Workflow

Step 1: Plan Your Component

Ask Yourself:

• What is the component's primary purpose?
• What states will it have? (default, hover, focus, disabled)
• What properties should be configurable?
• How should it look in ASCII form?

Step 2: Create the .uxm File

{
  "id": "kebab-case-name",
  "type": "component-type",
  "version": "1.0.0",
  "metadata": {
    "name": "Human Readable Name",
    "description": "What this component does",
    "created": "ISO-8601-timestamp",
    "modified": "ISO-8601-timestamp"
  },
  "props": {
    "configurableProperty": "defaultValue"
  },
  "ascii": {
    "templateFile": "component-name.md",
    "width": 20,
    "height": 3
  }
}

Step 3: Design ASCII Templates

# Component Name

Brief description.

## Default State

```
Your ASCII art here with {{variables}}
```

## Variables

- `variableName` (type): Description

## Usage Examples

```
Example with real values
```

Step 4: Add Behavior and Interactivity

{
  "behavior": {
    "states": [
      {"name": "default", "properties": {...}},
      {"name": "hover", "properties": {...}, "triggers": ["mouseenter"]}
    ],
    "interactions": [
      {
        "trigger": "click",
        "action": "emit-click-event"
      }
    ],
    "accessibility": {
      "role": "button",
      "focusable": true,
      "keyboardSupport": ["Enter", "Space"]
    }
  }
}

Step 5: Validate and Test

# Check schema compliance
uxscii validate your-component.uxm

# Check quality and best practices
uxscii lint your-component.uxm --strict

# Validate template syntax
uxscii template your-component.md

# Test the complete component
uxscii uxm get your-component

Template Design Patterns

ASCII Character Patterns

Borders and Containers:
┌─────┐  ╭─────╮  ▓▓▓▓▓▓▓  ═══════
│ Box │  │ Box │  ▓ Box ▓  ║ Box ║
└─────┘  ╰─────╯  ▓▓▓▓▓▓▓  ═══════
 Light    Rounded   Filled   Double

State Representations:
Default:  ┌─────┐    Hover:   ┏━━━━━┓    Focus:   ┏━━━━━┓✨
          │ Click│             ┃ Click┃             ┃ Click┃
          └─────┘             ┗━━━━━┛             ┗━━━━━┛

Disabled: ┌ ─ ─ ┐    Active:  ░▓▓▓▓▓░    Error:   ┌─────┐
          │ Click│             ░▓Click▓░            │⚠Click│
          └ ─ ─ ┘             ░▓▓▓▓▓░            └─────┘

Form Elements:
Text Input:    [________________]    Select:      [Option ▼]
               │cursor here      │

Checkbox:      [✓] Checked       Radio:       ◉ Selected
               [□] Unchecked                  ○ Unselected

Slider:        ├────●─────────┤    Progress:  ████▓▓▓▓▓▓ 40%

Variable Substitution

• Use {{variableName}} for direct substitution
• Keep variable names short and descriptive
• Use camelCase for consistency
• Provide sensible defaults in .uxm file
• Document all variables in template

Complete Examples

Example: Contact Card

.uxm file:

{
  "id": "contact-card",
  "type": "card",
  "version": "1.0.0",
  "metadata": {
    "name": "Contact Card",
    "description": "Display contact information in a card format",
    "created": "2024-01-15T10:00:00Z",
    "modified": "2024-01-15T10:00:00Z",
    "tags": ["card", "contact", "profile"],
    "category": "display"
  },
  "props": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+1 555-0123",
    "title": "Software Engineer"
  },
  "ascii": {
    "templateFile": "contact-card.md",
    "width": 30,
    "height": 8,
    "variables": [
      {"name": "name", "type": "string", "required": true},
      {"name": "email", "type": "string", "required": true},
      {"name": "phone", "type": "string"},
      {"name": "title", "type": "string"}
    ]
  }
}

.md file:

# Contact Card

Display contact information in a professional card format.

## Default Layout

```
┌────────────────────────────┐
│ {{name}}                   │
│ {{title}}                  │
├────────────────────────────┤
│ 📧 {{email}}               │
│ 📞 {{phone}}               │
└────────────────────────────┘
```

## Variables

- `name` (string, required): Full name
- `email` (string, required): Email address
- `phone` (string): Phone number
- `title` (string): Job title

Validation & Quality

Essential Validation Checklist

Schema Compliance:

• All required fields present (id, type, version, metadata, props, ascii)
• Valid ID format (kebab-case, 2-64 chars)
• Semantic version format (major.minor.patch)
• Template file has .md extension
• ASCII dimensions within limits (1-120 width, 1-50 height)

Content Quality:

• Component has meaningful name and description
• All template variables defined in .uxm file
• ASCII art uses printable characters only
• Template file exists and is readable
• Variables use consistent naming (camelCase)

Accessibility:

• ARIA role specified for interactive components
• Focusable state defined for interactive elements
• Keyboard support documented
• Screen reader labels provided

Common Validation Errors

# Schema Errors:
❌ Missing required field: id
❌ Invalid ID format: 'MyComponent' (should be 'my-component')
❌ Version must follow semantic versioning: '1.0' → '1.0.0'
❌ Template file not found: 'template.md'

# Template Errors:
❌ Malformed variable syntax: '{text}' → '{{text}}'
❌ Undefined variable in template: '{{undefinedVar}}'
❌ Non-ASCII characters detected in line 5

# Quality Warnings:
⚠️ Missing component description
⚠️ No accessibility configuration
⚠️ Template variable lacks validation

Best Practices

Before Creating

• Plan component purpose and states
• Sketch ASCII layout on paper/text editor
• Identify required vs optional properties
• Consider accessibility requirements

During Creation

• Start with minimal required fields
• Add one feature at a time
• Validate frequently with CLI
• Test template variable substitution

Before Committing

• Full validation passes
• Linting passes with --strict
• Template renders correctly
• All variables documented
• Usage examples included
• Accessibility considered

Component Categories

Naming Conventions

# Component IDs: kebab-case
primary-button, text-input, contact-card

# Variable names: camelCase
text, buttonText, isDisabled, maxLength

# File names: kebab-case.extension
primary-button.uxm, primary-button.md

Quick Reference

Minimal Component Template

{
  "id": "component-name",
  "type": "button",
  "version": "1.0.0",
  "metadata": {
    "name": "Component Name",
    "created": "2024-01-15T10:00:00Z",
    "modified": "2024-01-15T10:00:00Z"
  },
  "props": {},
  "ascii": {
    "templateFile": "component-name.md",
    "width": 20,
    "height": 3
  }
}

CLI Command Reference

# Validation
uxscii validate file.uxm           # Validate component
uxscii template file.md            # Validate template
uxscii lint file.uxm --strict      # Quality check

# Component Operations
uxscii uxm get component           # Get component + template
uxscii compress file.uxm           # Generate compressed format

# Stdin Support
cat file.uxm | uxscii validate -
echo '{}' | uxscii validate -

← Schema Guide | View Examples →