UXSCII Specification v1.0.0

Status: Stable
Last Updated: 2025-01-13
Authors: UXSCII Working Group

Abstract

UXSCII (pronounced "you-ex-ski") is a text-based markup language for defining user interface components in a format optimized for both human readability and machine parsing. It uses a two-file system combining structured JSON metadata (.uxm files) with ASCII visual templates (.md files) to represent UI components in a way that is version-control friendly, tool-independent, and particularly well-suited for AI agent consumption and generation.

This specification defines the syntax, semantics, and validation rules for UXSCII version 1.0.0.

1. Introduction

1.1 Purpose

UXSCII provides a standardized format for representing UI components that:

1.2 Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1.3 Namespace

UXSCII files use the following conventions:

2. Design Goals

UXSCII is designed with the following priorities:

  1. AI-Native: Optimized for machine parsing and generation by AI agents
  2. Human-Readable: ASCII representations understandable without special tools
  3. Version Control Friendly: Text-based format with meaningful diffs
  4. Tool Independent: Open specification, no vendor lock-in
  5. Extensible: Clear extension points for custom types and behaviors
  6. Accessible: ASCII representation readable by screen readers

3. File Format Overview

3.1 The Two-File System

A UXSCII component consists of two files:

.uxm file (Required):

.md file (Optional):

3.2 File Naming

Component files MUST follow these naming conventions:

4. UXM File Specification

4.1 File Format

UXM files MUST be valid JSON conforming to the UXSCII JSON Schema at https://uxscii.org/schema/v1.0.0.json.

4.2 Required Fields

Every UXM file MUST contain the following top-level fields:

{
  "id": "component-name",
  "type": "component-type",
  "version": "1.0.0",
  "metadata": { /* metadata object */ },
  "props": { /* properties object */ },
  "ascii": { /* ASCII configuration object */ }
}

4.3 Component Identity

4.3.1 id Field

4.3.2 type Field

4.3.3 version Field

4.4 Metadata Object

The metadata object MUST contain the following fields:

Field Type Description Required
name String Human-readable component name Yes
created String ISO 8601 timestamp of creation Yes
modified String ISO 8601 timestamp of last modification Yes
description String Component purpose and usage No
author String Author or organization name No
tags Array Searchable tags (max 10) No
category String Component category No

4.5 Properties Object

The props object contains component properties used for configuration and template variable substitution. Property values MAY be any valid JSON type.

4.6 ASCII Configuration Object

The ascii object configures the ASCII template and its variables:

Field Type Description Required
templateFile String Template file name (must end with .md) Yes
width Number Component width in characters (1-120) Yes
height Number Component height in characters (1-50) Yes
variables Array Template variable definitions with validation No

5. Template File Specification

5.1 File Format

Template files MUST be valid Markdown files using ASCII characters (hex 0x20-0x7E) in code blocks for visual representations.

5.2 Structure

A template file SHOULD contain the following sections:

5.3 ASCII Art Sections

ASCII art MUST be contained within Markdown code blocks (triple backticks).

5.4 ASCII Character Guidelines

Templates SHOULD use ASCII characters (0x20-0x7E) for maximum compatibility. Recommended patterns:

6. Variable Interpolation

6.1 Syntax

Variables in template files use double-brace syntax: {{variableName}}

Rules:

6.2 Example

Template:
```
┌──────────────────┐
│ {{text}}         │
│ Size: {{size}}   │
└──────────────────┘
```

Props:
{
  "props": {
    "text": "Hello World",
    "size": "medium"
  }
}

Rendered:
```
┌──────────────────┐
│ Hello World      │
│ Size: medium     │
└──────────────────┘
```

6.3 Type Conversion

Values are converted to strings using these rules:

7. Validation Rules

7.1 UXM File Validation

A UXM file is valid if:

  1. It contains valid JSON
  2. All required fields are present
  3. Field types match schema definitions
  4. String patterns conform to regex requirements
  5. Enum values are from allowed lists
  6. Numbers are within specified ranges

7.2 Template File Validation

A template file is valid if:

  1. It exists and is readable (if referenced)
  2. It contains valid Markdown
  3. Variable syntax is well-formed: {{variableName}}
  4. Variables use camelCase naming
  5. ASCII art primarily uses printable ASCII characters

7.3 Cross-File Validation

A component is fully valid if:

  1. Both UXM and template files are individually valid
  2. The ascii.templateFile path resolves to an existing file
  3. All variables used in the template are defined in props or ascii.variables
  4. Template dimensions approximately match declared width and height

8. Versioning

8.1 Specification Versioning

UXSCII uses semantic versioning (MAJOR.MINOR.PATCH):

This document describes version 1.0.0.

8.2 Component Versioning

Components MUST use semantic versioning in the version field. Components MAY use pre-release identifiers (e.g., 2.1.0-beta.1).

9. Extension Points

9.1 Custom Types

The type field supports a custom value for domain-specific component types.

9.2 Custom Properties

The props object accepts any valid JSON, allowing custom properties.

9.3 Extension Prefix

Custom extensions SHOULD use an x- prefix or vendor-specific prefix to avoid conflicts with future specification versions.

10. Conformance

10.1 UXSCII Consumer

A conformant consumer MUST:

10.2 UXSCII Producer

A conformant producer MUST:

10.3 UXSCII Validator

A conformant validator MUST:

References

Copyright © 2024 UXSCII Working Group

Licensed under MIT License

← Back to Home | View Examples →