All docs

Protocol Spec

UIXDocument, UIXNode, UIXToken — the core types and their relationships.

Overview

UIX Protocol defines a universal schema for user interfaces. Every UI — regardless of platform — is described as a UIXDocument containing a tree of UIXNode objects with shared UIXToken design tokens.

UIXDocument

The top-level container for a UI definition:

typescript
interface UIXDocument {
  id: string;
  name: string;
  version: string;
  root: string;                        // root node ID
  nodes: Record<string, UIXNode>;      // all nodes by ID
  tokens: Record<string, UIXToken>;    // design tokens
  components?: Record<string, UIXComponent>;
  canonical?: UIXCanonicalRegistry;    // full self-describing registry
  soul?: UIXDocumentSoul;              // WHY this document exists
  mind?: UIXMind;                      // pre-computed AI reasoning surface
  qa?: UIXDocumentQA;                  // Immune System — QA status
  ci?: UIXDocumentCI;                  // Deployment health
}

UIXNode

A single UI element in the document tree:

typescript
interface UIXNode {
  id: string;
  type: 'Button' | 'Text' | 'Image' | 'Frame' | 'List' | 'Component' | 'Input' | ...;
  name?: string;
  props?: Record<string, unknown>;
  layout?: UIXLayout;
  style?: UIXStyle;
  children?: string[];                 // child node IDs
  extensions?: Record<string, unknown>;
  soul?: UIXNodeSoul;
}

Supported node types

Button, Text, Image, Frame, List, Component, Input, ScrollView, Icon, Badge, Divider, Spacer, Card, Toggle, Checkbox, Radio, Select, Slider, Switch, Tab, Chip, Avatar, Tooltip, Modal, Drawer, Menu, ProgressBar, Skeleton, Alert, and more.

UIXToken

Design tokens are the atomic design decisions shared across all nodes:

typescript
interface UIXToken {
  id: string;
  type: 'color' | 'spacing' | 'radius' | 'typography' | 'shadow' | 'gradient' | 'blur' | 'duration' | 'easing' | 'elevation' | 'motion';
  value: string | number | object;
  description?: string;
}

Tokens are referenced in node styles using {category.name} syntax:

json
{ "background": "{color.primary}", "radius": "{radius.md}" }

UIXLayout

Layout properties for positioning and sizing:

typescript
interface UIXLayout {
  width?: number | 'fill' | 'hug';
  height?: number | 'fill' | 'hug';
  direction?: 'horizontal' | 'vertical';
  gap?: number;
  padding?: number | { top: number; right: number; bottom: number; left: number };
  alignment?: 'center' | 'start' | 'end' | 'stretch';
  mode?: 'flex' | 'absolute' | 'grid';
}

UIXStyle

Visual styling properties:

typescript
interface UIXStyle {
  background?: string;
  foreground?: string;
  border?: { color: string; width: number; style?: string };
  radius?: number;
  shadow?: string | object;
  opacity?: number;
}

Diff format

UIX provides a structured diff engine for comparing documents:

typescript
interface UIXDiff {
  added: string[];           // IDs of new nodes
  removed: string[];         // IDs of deleted nodes
  modified: Array<{
    id: string;
    path: string;            // e.g., "style.padding"
    oldValue: unknown;
    newValue: unknown;
  }>;
}

Protocol messages

All messages use the UIX/1.0 envelope format:

json
{
  "protocol": "UIX/1.0",
  "id": "msg-001",
  "type": "request",
  "method": "document.get",
  "params": { "documentId": "login-screen" }
}