gh-trabian-fluxwing-skills/skills/fluxwing-component-creator/docs/07-schema-reference.md

Schema Reference

Pointer to the definitive uxscii component schema and how to use it.

The Schema File

Location: ../schema/uxm-component.schema.json

This is the definitive source of truth for the uxscii .uxm file format.

What the Schema Defines

The schema specifies:

• All valid field names and types
• Required vs optional fields
• Validation rules (min/max, patterns, enums)
• Nested object structures
• Field descriptions

How to Use the Schema

For Reference

When creating components, refer to the schema to understand:

• What fields are available
• What values are allowed
• What's required vs optional

For Autocompletion

Many editors can use the schema for:

• Field suggestions
• Type checking
• Documentation on hover

Add to your .uxm file:

{
  "$schema": "../data/schema/uxm-component.schema.json",
  ...
}

Key Schema Sections

Required Root Fields

id          - Component identifier (kebab-case, 2-64 chars)
type        - Component type (enum or "custom")
version     - Semantic version (X.Y.Z)
metadata    - Component metadata object
props       - Component properties object
ascii       - ASCII template reference

Metadata Object (required fields)

name        - Human-readable name (1-100 chars)
created     - ISO 8601 timestamp
modified    - ISO 8601 timestamp

Metadata Object (optional fields)

description - Component description (max 500 chars)
author      - Creator name (max 100 chars)
tags        - Array of search tags (max 10)
category    - Component category (enum)

ASCII Object (required)

templateFile - Template filename (must end in .md)
width        - Character width (1-120)
height       - Character height (1-50)

ASCII Object (optional)

variables    - Array of template variable definitions

Behavior Object (optional)

states       - Array of component states
interactions - Array of user interactions
animations   - Array of animation definitions
accessibility- Accessibility attributes

Component Types (Enum)

Valid type values:

button, input, card, navigation, form, list, modal,
table, badge, alert, container, text, image, divider, custom

Categories (Enum)

Valid metadata.category values:

layout, input, display, navigation, feedback,
utility, overlay, custom

Variable Types (Enum)

Valid ascii.variables[].type values:

string, number, boolean, color, size, array, object

Quick Reference Examples

Minimal Valid Component

{
  "id": "simple",
  "type": "button",
  "version": "1.0.0",
  "metadata": {
    "name": "Simple",
    "created": "2024-01-01T00:00:00Z",
    "modified": "2024-01-01T00:00:00Z"
  },
  "props": {},
  "ascii": {
    "templateFile": "simple.md",
    "width": 10,
    "height": 3
  }
}

Complete Component

See ../examples/primary-button.uxm for a fully-featured example using all available fields.

Schema Version

Current schema version: 1.1.0

Schema follows semantic versioning:

• Major: Breaking changes to structure
• Minor: New optional fields
• Patch: Documentation or validation updates

Validation Rules Summary

ID Rules

• Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
• Length: 2-64 characters
• Format: kebab-case only

Version Rules

• Pattern: ^\d+\.\d+\.\d+(?:-[a-zA-Z0-9-]+)?$
• Examples: 1.0.0, 2.1.3, 1.0.0-beta

Timestamp Rules

• Format: ISO 8601 date-time
• Example: 2024-10-11T12:00:00Z

Variable Name Rules

• Pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
• Format: camelCase recommended
• Examples: text, userName, isDisabled

Common Schema Errors

"Additional property not allowed"

• You used a field name that doesn't exist in the schema
• Check field spelling and location in object hierarchy

"Missing required property"

• You omitted a required field
• Add the field with a valid value

"Value does not match pattern"

• Field value doesn't match regex pattern
• Check format requirements (kebab-case, semver, etc.)

"Value not in enum"

• You used a value not in the allowed list
• Use one of the valid enum values

Deep Dive

For comprehensive schema documentation, see:

• Full guide: UXSCII_SCHEMA_GUIDE.md (detailed explanations)
• Agent guide: UXSCII_AGENT_GUIDE.md (practical examples)

Next Steps

• View schema: Open ../schema/uxm-component.schema.json
• See examples: Browse ../examples/*.uxm

The schema ensures all uxscii components are compatible and machine-readable!