Overview

UXSCII uses a two-file system for component definitions:

• .uxm files: JSON metadata defining component structure, behavior, and properties
• .md files: ASCII visual templates with variable interpolation

Required Fields

{
  "id": "component-name",           // kebab-case, 2-64 chars
  "type": "button|input|card|...",  // component type
  "version": "1.0.0",               // semantic version
  "metadata": { ... },              // metadata object
  "props": { ... },                 // component properties
  "ascii": { ... }                  // ASCII template config
}

Metadata Section

The metadata object contains descriptive information about the component:

Example:

{
  "metadata": {
    "name": "Primary Button",
    "description": "A primary action button with emphasis styling",
    "author": "UXSCII Team",
    "created": "2024-01-01T00:00:00Z",
    "modified": "2024-01-15T10:30:00Z",
    "tags": ["button", "primary", "action"],
    "category": "input"
  }
}

Properties Section

The props object contains component configuration values that can be substituted into templates:

{
  "props": {
    "text": "Button",
    "disabled": false,
    "size": "medium",
    "fullWidth": false,
    "ariaLabel": ""
  }
}

Properties can be any valid JSON type: string, number, boolean, array, or object.

Behavior Section (Optional)

Defines component states, interactions, animations, and accessibility:

States

{
  "behavior": {
    "states": [
      {
        "name": "default",
        "properties": {
          "background": "primary",
          "textColor": "white"
        }
      },
      {
        "name": "hover",
        "properties": {
          "background": "primary-dark"
        },
        "triggers": ["mouseenter"]
      }
    ]
  }
}

Interactions

{
  "interactions": [
    {
      "trigger": "click",
      "action": "emit-click-event",
      "target": "parent",
      "condition": "key === 'Enter'"
    }
  ]
}

Accessibility

{
  "accessibility": {
    "role": "button",
    "focusable": true,
    "keyboardSupport": ["Enter", "Space"],
    "ariaLabel": "{{ariaLabel || text}}"
  }
}

Layout Section (Optional)

Defines component layout properties:

{
  "layout": {
    "display": "inline-block",
    "positioning": "static",
    "spacing": {
      "margin": { "top": 1, "right": 2, "bottom": 1, "left": 2 },
      "padding": 16
    },
    "sizing": {
      "width": 200,
      "height": "auto",
      "minWidth": 100,
      "maxWidth": 400
    }
  }
}

ASCII Configuration

The ascii object configures the template file and variables:

Variable Definitions

{
  "ascii": {
    "templateFile": "button.md",
    "width": 16,
    "height": 3,
    "variables": [
      {
        "name": "text",
        "type": "string",
        "defaultValue": "Button",
        "description": "Button text label",
        "required": true,
        "validation": {
          "min": 1,
          "max": 20,
          "pattern": "^[a-zA-Z ]+$"
        }
      }
    ]
  }
}

Template File Format

Basic Structure

# Component Name

Component description.

## Default State

```
ASCII art representation using {{variables}}
```

## Variables

- `variableName` (type): Description

## Usage Examples

```
Example ASCII representations
```

Variable Syntax

Use {{variableName}} for variable interpolation:

• Variables must match those defined in .uxm file
• Use camelCase for variable names
• Whitespace inside braces is optional

ASCII Art Guidelines

Common patterns for visual hierarchy:

• ▓ = Primary/filled elements
• █ = Hover/active states
• ░ = Shadow/pressed effects
• ┌─┐│└─┘ = Light borders
• ┏━┓┃┗━┛ = Emphasized borders
• ┌ ─ ┐─└ ─ ┘ = Dashed/disabled borders

Validation Rules

Schema Validation

• All required fields must be present
• Field types must match definitions
• String patterns must conform to regex
• Enum values must be from allowed lists
• Numbers must be within ranges

Template Validation

• Template file must exist and be readable
• Variable syntax must be well-formed
• Variables should be defined in .uxm
• ASCII content should use printable characters
• Dimensions should match declared width/height

CLI Validation Commands

# Validate component schema
uxscii validate component.uxm

# Validate template syntax
uxscii template component.md

# Quality and best practices check
uxscii lint component.uxm --strict

# Test complete integration
uxscii uxm get component

Component Types

Standard component types:

• button - Interactive action elements
• input - Form input fields
• card - Content containers
• navigation - Navigation elements
• form - Form layouts
• list - List structures
• modal - Overlay dialogs
• table - Data tables
• badge - Status indicators
• alert - Notification messages
• container - Layout containers
• text - Text elements
• image - Image placeholders
• divider - Section separators
• custom - Custom types

Best Practices

1. Use semantic IDs and clear naming
2. Provide comprehensive accessibility configuration
3. Include multiple interaction states
4. Document all template variables
5. Use consistent ASCII visual patterns
6. Follow semantic versioning for updates
7. Validate components before committing
8. Include comprehensive metadata

← Full Specification | Agent Guide →