API Reference — UIX Docs

Package Overview

UIX Protocol ships as a monorepo of focused packages. The three foundational packages documented here are:

Package	Purpose	Exports
`@uix/protocol`	Core types, validation, diff engine, tokens, canonical registry, animation	40+ modules
`@uix/codegen`	Multi-platform code generation (9 renderers, 6 token writers, 2 test generators)	20+ exports
`@uix/runtime`	9-step deterministic interpretation pipeline	15+ exports

Additional packages: @uix/auth, @uix/server, @uix/qa-engine, @uix/devtools, @uix/mcp, @uix/image-codec, @uix/figma-plugin, @uix/vscode, @uix/canvas, @uix/catalyst, @uix/kernel, @uix/console, @uix/dashboard, @uix/e2e, @uix/website, @uix/mobile.

---

@uix/protocol

The foundation package. Pure functions, TypeScript types, Zod validation schemas. No side effects, no I/O.

Document Operations

typescript

import { createDocument, generateId, computeDocumentDiff, applyDiff } from '@uix/protocol';

// Create a new document
const doc = createDocument({
  name: 'My App',
  nodes: {
    root: { id: 'root', type: 'Frame', children: ['btn'] },
    btn: { id: 'btn', type: 'Button', props: { label: 'Click' } },
  },
});

// Generate unique IDs
const nodeId = generateId(); // "n_8f3a2b..."

// Diff two documents
const diff = computeDocumentDiff(docA, docB);
// { added: ['new-node'], removed: [], modified: [...] }

// Apply a diff
const updated = applyDiff(doc, diff);

Token System

typescript

import { resolveToken, resolveAllTokens, createTheme } from '@uix/protocol';

// Resolve a single token reference
const color = resolveToken(doc, '{color.primary}'); // "#6366F1"

// Resolve all tokens in a document
const resolved = resolveAllTokens(doc);

// Create a theme from token values
const theme = createTheme('dark', { 'color.primary': '#818CF8' });

Canonical Registry

typescript

import {
  createBuiltInRegistry,
  resolveBlueprint,
  resolveRenderer,
  deriveNode,
  registerDerived,
  getDefaultProps,
  getSupportedPlatforms,
} from '@uix/protocol';

// Create the standard registry (21 built-in blueprints)
const registry = createBuiltInRegistry();

// Resolve a blueprint by node type
const bp = resolveBlueprint(registry, 'Button');

// Get a platform-specific renderer template
const flutterRenderer = resolveRenderer(registry, 'Button', 'flutter');

// Derive a custom type from an existing blueprint
const derived = deriveNode(registry, 'Button', 'PrimaryButton', {
  defaultProps: { variant: 'primary', label: 'Submit' },
});
const extendedRegistry = registerDerived(registry, derived);

// Get default props (base merged with overrides)
const defaults = getDefaultProps(extendedRegistry, 'PrimaryButton');

// Check supported platforms for a blueprint
const platforms = getSupportedPlatforms(bp); // ['react', 'flutter', ...]

Mind + Soul

typescript

import {
  buildMind, rebuildMind, annotateSoul, annotateNodeSoul,
  getMindContext, getNodeMeta, getNodesByRole, getNodesAtDepth,
} from '@uix/protocol';

// Add semantic purpose (immutable, returns new doc)
const withSoul = annotateSoul(doc, {
  purpose: 'Authenticates existing users',
  userGoal: 'Get back to work quickly',
  journey: 'onboarding.step-1',
  emotion: 'trust',
});

// Build the AI reasoning surface
const mind = buildMind(withSoul);
mind.screenType;       // 'authentication'
mind.summary;          // 'Authenticates existing users'
mind.dataRequirements; // ['auth.email', 'auth.password']
mind.intents;          // ['auth.login', 'auth.setEmail']

// Get focused context for a single node
const ctx = getMindContext(mind, 'submit-btn');
// { node, children, relationships, screenType, documentSummary }

// Embed mind in document
const selfDescribing = rebuildMind(withSoul);

Validation

typescript

import { validateDocument, validateAnimations } from '@uix/protocol';

// Validate a document with Zod schemas
const result = validateDocument(doc);
if (!result.success) {
  console.error(result.error.issues);
}

// Validate animation definitions
const animResult = validateAnimations(doc);

Animation

typescript

import {
  resolveEasing, easingToCSS, resolveAnimation,
  generateCSSKeyframes, generateCSSStylesheet,
  adaptAnimationForMotion, checkAnimationA11y,
  computeAnimationDuration, interpolateKeyframes,
} from '@uix/protocol';

// Resolve named easing to cubic-bezier values
const easing = resolveEasing('ease-in-out');
const css = easingToCSS(easing); // "cubic-bezier(0.42, 0, 0.58, 1)"

// Resolve animation for a node
const anim = resolveAnimation(doc, 'fade-in-btn');

// Generate CSS @keyframes
const keyframes = generateCSSKeyframes(anim);
const stylesheet = generateCSSStylesheet(doc);

// Accessibility: adapt for reduced motion preference
const reduced = adaptAnimationForMotion(anim, 'reduce');
const a11yReport = checkAnimationA11y(anim);

Diff Engine

typescript

import { computeDocumentDiff, computeSemanticDiff, applyDiff } from '@uix/protocol';

// Structural diff
const diff = computeDocumentDiff(before, after);
// { added, removed, modified: [{ id, path, oldValue, newValue }] }

// Semantic diff (categorized changes)
const semantic = computeSemanticDiff(before, after);
// { layout: [...], style: [...], content: [...], structural: [...] }

Sync Engine

typescript

import { SyncEngine, designToCode, codeToDesign } from '@uix/protocol';

// Design-to-code sync
const codeChanges = designToCode(doc, { target: 'react' });

// Code-to-design sync
const docChanges = codeToDesign(sourceCode, { language: 'tsx' });

App Flow DAG

typescript

import {
  createAppFlowDAG, createScreenNode, createTransition,
  addNode, addTransition, validateDAG, computeGenerationOrder,
  addDefaultStates, addDefaultPopups, getDAGStats,
} from '@uix/protocol';

// Create a new app flow DAG
const dag = createAppFlowDAG({ name: 'My App' });

// Add screens and transitions
const home = createScreenNode('home', 'dashboard', 'Home');
const login = createScreenNode('login', 'authentication', 'Login');
const flow = addTransition(
  addNode(addNode(dag, home), login),
  createTransition('login', 'home', 'auth.success'),
);

// Validate structure
const validation = validateDAG(flow);

// Topological sort for generation order
const order = computeGenerationOrder(flow);

// Auto-add loading/error/empty states
const withStates = addDefaultStates(flow);

QA Immune System

typescript

import {
  annotateNodeQA, annotateDocumentQA, annotateDocumentCI,
  getNodeQAStatus, clearNodeQA,
} from '@uix/protocol';

// Add QA metadata to a node
const withQA = annotateNodeQA(doc, 'submit-btn', {
  coverageStatus: 'covered',
  testIds: ['test-login-submit'],
  regressionRisk: 'low',
});

// Document-level QA summary
const withDocQA = annotateDocumentQA(doc, {
  lastReport: { total: 50, high: 0, medium: 2, low: 1, passed: 47 },
  coveragePercent: 94,
});

---

@uix/codegen

Multi-platform code generation from UIXDocuments.

Basic Usage

typescript

import { UIXCodegen } from '@uix/codegen';

const codegen = new UIXCodegen();
const result = codegen.generate(doc, { target: 'react' });
// result.files — array of generated files
// result.manifest — version, checksums, warnings

Multi-Platform Generation

typescript

const results = codegen.generateMulti(doc, ['react', 'flutter', 'swiftui']);
// Generates for all 3 platforms at once

Platform Renderers

Renderer	Output	Import
`ReactRenderer`	.tsx functional components	`@uix/codegen`
`VueRenderer`	.vue Single File Components	`@uix/codegen`
`FlutterRenderer`	.dart StatelessWidgets	`@uix/codegen`
`SwiftUIRenderer`	.swift Views	`@uix/codegen`
`AngularRenderer`	.ts @Component classes	`@uix/codegen`
`HTMLRenderer`	.html semantic markup	`@uix/codegen`
`ReactNativeRenderer`	.tsx RN components	`@uix/codegen`
`ReactTailwindRenderer`	.tsx with Tailwind classes	`@uix/codegen`
`ComposeRenderer`	.kt Jetpack Compose	`@uix/codegen`

Token Writers

Writer	Output	Import
`TailwindTokenWriter`	tailwind.config.ts	`@uix/codegen`
`CssVarsTokenWriter`	variables.css	`@uix/codegen`
`DartTokenWriter`	tokens.dart	`@uix/codegen`
`SwiftTokenWriter`	Tokens.swift	`@uix/codegen`
`KotlinTokenWriter`	Tokens.kt	`@uix/codegen`

Test Generators

typescript

import { generatePlaywrightTests, generateA11yTests } from '@uix/codegen';

// Playwright integration tests
const playwrightCode = generatePlaywrightTests(doc);

// Accessibility tests
const a11yCode = generateA11yTests(doc);

Router Functions

typescript

import { resolveRenderer, resolveTokenWriter, getSupportedTargets } from '@uix/codegen';

// Resolve the right renderer for a target
const renderer = resolveRenderer('flutter');

// Get all supported code generation targets
const targets = getSupportedTargets();
// ['react', 'vue', 'flutter', 'swiftui', 'angular', 'html', 'react-native', ...]

// Resolve a token writer for a platform
const writer = resolveTokenWriter('tailwind');

---

@uix/runtime

Deterministic 9-step interpretation pipeline: UIXDocument x UIXEnvironment -> UIXInterpretedTree.

Basic Usage

typescript

import { UIXRuntime, interpret } from '@uix/runtime';

// Quick interpret (convenience function)
const tree = interpret(doc, { platform: 'web', theme: 'dark' });

// Full runtime with events and configuration
const runtime = new UIXRuntime({ strict: true });
runtime.on('step:complete', (step) => console.log(step.name));
const tree = runtime.interpret(doc, {
  platform: 'web',
  screenSize: { width: 1440, height: 900 },
  theme: 'dark',
  motionPreference: 'no-preference',
  locale: 'en-US',
});

Pipeline Steps

The runtime executes 9 steps in order. Each step is independently importable:

Step	Function	Purpose
1	`validateEnvironment(env)`	Validate UIXEnvironment
2	`resolveTokens(doc, env)`	Resolve all token references
3	`selectVariant(doc, env)`	Choose active variant
4	`adaptPhysics(doc, env)`	Apply physics adaptations
5	`adaptChemistry(doc, env)`	Apply chemistry bonds
6	`resolveLayout(doc, env)`	Compute final layout
7	`adaptInteractions(doc, env)`	Map interactions to platform
8	`validateBindings(doc, env)`	Validate data bindings
9	`resolveAnimations(doc, env)`	Resolve all animations

Events

typescript

import { UIXRuntime } from '@uix/runtime';

const runtime = new UIXRuntime();

runtime.on('step:start', ({ step }) => { /* ... */ });
runtime.on('step:complete', ({ step, duration }) => { /* ... */ });
runtime.on('step:skip', ({ step, reason }) => { /* ... */ });
runtime.on('pipeline:complete', ({ tree, totalDuration }) => { /* ... */ });
runtime.on('pipeline:error', ({ error, step }) => { /* ... */ });
runtime.on('warning', ({ message, step }) => { /* ... */ });
runtime.on('animation-resolved', ({ nodeId, animation }) => { /* ... */ });

Error Handling

typescript

import { UIXRuntimeError } from '@uix/runtime';

try {
  const tree = runtime.interpret(doc, env);
} catch (err) {
  if (err instanceof UIXRuntimeError) {
    console.error(err.step);    // which step failed
    console.error(err.code);    // error code
    console.error(err.context); // structured context
  }
}

---

Type Quick Reference

Core Types (from @uix/protocol)

Type	Description
`UIXDocument`	Top-level document container
`UIXNode`	Single UI element
`UIXToken`	Design token (color, spacing, etc.)
`UIXLayout`	Layout properties (width, height, padding, gap)
`UIXStyle`	Visual properties (background, foreground, border)
`UIXDiff`	Document diff result
`UIXComponent`	Reusable component definition
`UIXCanonicalRegistry`	Blueprint + renderer registry
`UIXNodeBlueprint`	Canonical node type definition
`UIXMind`	AI reasoning surface
`UIXDocumentSoul`	Document-level semantic purpose
`UIXNodeSoul`	Node-level semantic purpose
`UIXDocumentQA`	Document QA metadata
`UIXNodeQA`	Node QA metadata
`UIXDocumentCI`	CI/CD pipeline status
`UIXEnvironment`	Platform/screen/theme context (runtime input)
`UIXInterpretedTree`	Resolved tree (runtime output)

Codegen Types (from @uix/codegen)

Type	Description
`CodegenResult`	Generated files + manifest
`CodegenTarget`	Platform target identifier
`CodegenManifest`	Version, file checksums, warnings
`FormatOptions`	Code formatting configuration

Runtime Types (from @uix/runtime)

Type	Description
`UIXInterpretedTree`	Fully resolved node tree
`ResolvedAnimation`	Resolved animation with keyframes
`ResolvedKeyframe`	Single keyframe in resolved animation

const derived = deriveNode(registry, 'Button', 'PrimaryButton', {

defaultProps: { variant: 'primary', label: 'Submit' },

});

const extendedRegistry = registerDerived(registry, derived);

// Get default props (base merged with overrides)

const defaults = getDefaultProps(extendedRegistry, 'PrimaryButton');

// Check supported platforms for a blueprint

const platforms = getSupportedPlatforms(bp); // ['react', 'flutter', ...]


### Mind + Soul

import {

buildMind, rebuildMind, annotateSoul, annotateNodeSoul,

getMindContext, getNodeMeta, getNodesByRole, getNodesAtDepth,

} from '@uix/protocol';

// Add semantic purpose (immutable, returns new doc)

const withSoul = annotateSoul(doc, {

purpose: 'Authenticates existing users',

userGoal: 'Get back to work quickly',

journey: 'onboarding.step-1',

emotion: 'trust',

});

// Build the AI reasoning surface

const mind = buildMind(withSoul);

mind.screenType; // 'authentication'

mind.summary; // 'Authenticates existing users'

mind.dataRequirements; // ['auth.email', 'auth.password']

mind.intents; // ['auth.login', 'auth.setEmail']

// Get focused context for a single node

const ctx = getMindContext(mind, 'submit-btn');

// { node, children, relationships, screenType, documentSummary }

// Embed mind in document

const selfDescribing = rebuildMind(withSoul);


### Validation

import { validateDocument, validateAnimations } from '@uix/protocol';

// Validate a document with Zod schemas

const result = validateDocument(doc);

if (!result.success) {

console.error(result.error.issues);

}

// Validate animation definitions

const animResult = validateAnimations(doc);


### Animation

import {

resolveEasing, easingToCSS, resolveAnimation,

generateCSSKeyframes, generateCSSStylesheet,

adaptAnimationForMotion, checkAnimationA11y,

computeAnimationDuration, interpolateKeyframes,

} from '@uix/protocol';

// Resolve named easing to cubic-bezier values

const easing = resolveEasing('ease-in-out');

const css = easingToCSS(easing); // "cubic-bezier(0.42, 0, 0.58, 1)"

// Resolve animation for a node

const anim = resolveAnimation(doc, 'fade-in-btn');

// Generate CSS @keyframes

const keyframes = generateCSSKeyframes(anim);

const stylesheet = generateCSSStylesheet(doc);

// Accessibility: adapt for reduced motion preference

const reduced = adaptAnimationForMotion(anim, 'reduce');

const a11yReport = checkAnimationA11y(anim);


### Diff Engine

import { computeDocumentDiff, computeSemanticDiff, applyDiff } from '@uix/protocol';

// Structural diff

const diff = computeDocumentDiff(before, after);

// { added, removed, modified: [{ id, path, oldValue, newValue }] }

// Semantic diff (categorized changes)

const semantic = computeSemanticDiff(before, after);

// { layout: [...], style: [...], content: [...], structural: [...] }


### Sync Engine

import { SyncEngine, designToCode, codeToDesign } from '@uix/protocol';

// Design-to-code sync

const codeChanges = designToCode(doc, { target: 'react' });

// Code-to-design sync

const docChanges = codeToDesign(sourceCode, { language: 'tsx' });


### App Flow DAG

import {

createAppFlowDAG, createScreenNode, createTransition,

addNode, addTransition, validateDAG, computeGenerationOrder,

addDefaultStates, addDefaultPopups, getDAGStats,

} from '@uix/protocol';

// Create a new app flow DAG

const dag = createAppFlowDAG({ name: 'My App' });

// Add screens and transitions

const home = createScreenNode('home', 'dashboard', 'Home');

const login = createScreenNode('login', 'authentication', 'Login');

const flow = addTransition(

addNode(addNode(dag, home), login),

createTransition('login', 'home', 'auth.success'),

);

// Validate structure

const validation = validateDAG(flow);

// Topological sort for generation order

const order = computeGenerationOrder(flow);

// Auto-add loading/error/empty states

const withStates = addDefaultStates(flow);


### QA Immune System

import {

annotateNodeQA, annotateDocumentQA, annotateDocumentCI,

getNodeQAStatus, clearNodeQA,

} from '@uix/protocol';

// Add QA metadata to a node

const withQA = annotateNodeQA(doc, 'submit-btn', {

coverageStatus: 'covered',

testIds: ['test-login-submit'],

regressionRisk: 'low',

});

// Document-level QA summary

const withDocQA = annotateDocumentQA(doc, {

lastReport: { total: 50, high: 0, medium: 2, low: 1, passed: 47 },

coveragePercent: 94,

});


---

## @uix/codegen

Multi-platform code generation from UIXDocuments.

### Basic Usage

import { UIXCodegen } from '@uix/codegen';

const codegen = new UIXCodegen();

const result = codegen.generate(doc, { target: 'react' });

// result.files — array of generated files

// result.manifest — version, checksums, warnings


### Multi-Platform Generation

const results = codegen.generateMulti(doc, ['react', 'flutter', 'swiftui']);

// Generates for all 3 platforms at once


### Platform Renderers

| Renderer | Output | Import |
|----------|--------|--------|
| `ReactRenderer` | .tsx functional components | `@uix/codegen` |
| `VueRenderer` | .vue Single File Components | `@uix/codegen` |
| `FlutterRenderer` | .dart StatelessWidgets | `@uix/codegen` |
| `SwiftUIRenderer` | .swift Views | `@uix/codegen` |
| `AngularRenderer` | .ts @Component classes | `@uix/codegen` |
| `HTMLRenderer` | .html semantic markup | `@uix/codegen` |
| `ReactNativeRenderer` | .tsx RN components | `@uix/codegen` |
| `ReactTailwindRenderer` | .tsx with Tailwind classes | `@uix/codegen` |
| `ComposeRenderer` | .kt Jetpack Compose | `@uix/codegen` |

### Token Writers

| Writer | Output | Import |
|--------|--------|--------|
| `TailwindTokenWriter` | tailwind.config.ts | `@uix/codegen` |
| `CssVarsTokenWriter` | variables.css | `@uix/codegen` |
| `DartTokenWriter` | tokens.dart | `@uix/codegen` |
| `SwiftTokenWriter` | Tokens.swift | `@uix/codegen` |
| `KotlinTokenWriter` | Tokens.kt | `@uix/codegen` |

### Test Generators

import { generatePlaywrightTests, generateA11yTests } from '@uix/codegen';

// Playwright integration tests

const playwrightCode = generatePlaywrightTests(doc);

// Accessibility tests

const a11yCode = generateA11yTests(doc);


### Router Functions

import { resolveRenderer, resolveTokenWriter, getSupportedTargets } from '@uix/codegen';

// Resolve the right renderer for a target

const renderer = resolveRenderer('flutter');

// Get all supported code generation targets

const targets = getSupportedTargets();

// ['react', 'vue', 'flutter', 'swiftui', 'angular', 'html', 'react-native', ...]

// Resolve a token writer for a platform

const writer = resolveTokenWriter('tailwind');


---

## @uix/runtime

Deterministic 9-step interpretation pipeline: `UIXDocument x UIXEnvironment -> UIXInterpretedTree`.

### Basic Usage

import { UIXRuntime, interpret } from '@uix/runtime';

// Quick interpret (convenience function)

const tree = interpret(doc, { platform: 'web', theme: 'dark' });

// Full runtime with events and configuration

const runtime = new UIXRuntime({ strict: true });

runtime.on('step:complete', (step) => console.log(step.name));

const tree = runtime.interpret(doc, {

platform: 'web',

screenSize: { width: 1440, height: 900 },

theme: 'dark',

motionPreference: 'no-preference',

locale: 'en-US',

});


### Pipeline Steps

The runtime executes 9 steps in order. Each step is independently importable:

| Step | Function | Purpose |
|------|----------|---------|
| 1 | `validateEnvironment(env)` | Validate UIXEnvironment |
| 2 | `resolveTokens(doc, env)` | Resolve all token references |
| 3 | `selectVariant(doc, env)` | Choose active variant |
| 4 | `adaptPhysics(doc, env)` | Apply physics adaptations |
| 5 | `adaptChemistry(doc, env)` | Apply chemistry bonds |
| 6 | `resolveLayout(doc, env)` | Compute final layout |
| 7 | `adaptInteractions(doc, env)` | Map interactions to platform |
| 8 | `validateBindings(doc, env)` | Validate data bindings |
| 9 | `resolveAnimations(doc, env)` | Resolve all animations |

### Events

import { UIXRuntime } from '@uix/runtime';

const runtime = new UIXRuntime();

runtime.on('step:start', ({ step }) => { /* ... */ });

runtime.on('step:complete', ({ step, duration }) => { /* ... */ });

runtime.on('step:skip', ({ step, reason }) => { /* ... */ });

runtime.on('pipeline:complete', ({ tree, totalDuration }) => { /* ... */ });

runtime.on('pipeline:error', ({ error, step }) => { /* ... */ });

runtime.on('warning', ({ message, step }) => { /* ... */ });

runtime.on('animation-resolved', ({ nodeId, animation }) => { /* ... */ });


### Error Handling

import { UIXRuntimeError } from '@uix/runtime';

try {

const tree = runtime.interpret(doc, env);

} catch (err) {

if (err instanceof UIXRuntimeError) {

console.error(err.step); // which step failed

console.error(err.code); // error code

console.error(err.context); // structured context

}


---

## Type Quick Reference

### Core Types (from @uix/protocol)

| Type | Description |
|------|-------------|
| `UIXDocument` | Top-level document container |
| `UIXNode` | Single UI element |
| `UIXToken` | Design token (color, spacing, etc.) |
| `UIXLayout` | Layout properties (width, height, padding, gap) |
| `UIXStyle` | Visual properties (background, foreground, border) |
| `UIXDiff` | Document diff result |
| `UIXComponent` | Reusable component definition |
| `UIXCanonicalRegistry` | Blueprint + renderer registry |
| `UIXNodeBlueprint` | Canonical node type definition |
| `UIXMind` | AI reasoning surface |
| `UIXDocumentSoul` | Document-level semantic purpose |
| `UIXNodeSoul` | Node-level semantic purpose |
| `UIXDocumentQA` | Document QA metadata |
| `UIXNodeQA` | Node QA metadata |
| `UIXDocumentCI` | CI/CD pipeline status |
| `UIXEnvironment` | Platform/screen/theme context (runtime input) |
| `UIXInterpretedTree` | Resolved tree (runtime output) |

### Codegen Types (from @uix/codegen)

| Type | Description |
|------|-------------|
| `CodegenResult` | Generated files + manifest |
| `CodegenTarget` | Platform target identifier |
| `CodegenManifest` | Version, file checksums, warnings |
| `FormatOptions` | Code formatting configuration |

### Runtime Types (from @uix/runtime)

| Type | Description |
|------|-------------|
| `UIXInterpretedTree` | Fully resolved node tree |
| `ResolvedAnimation` | Resolved animation with keyframes |
| `ResolvedKeyframe` | Single keyframe in resolved animation |
const derived = deriveNode(registry, 'Button', 'PrimaryButton', {
  defaultProps: { variant: 'primary', label: 'Submit' },
});
const extendedRegistry = registerDerived(registry, derived);

// Get default props (base merged with overrides)
const defaults = getDefaultProps(extendedRegistry, 'PrimaryButton');

// Check supported platforms for a blueprint
const platforms = getSupportedPlatforms(bp); // ['react', 'flutter', ...]

Mind + Soul

typescript

import {
  buildMind, rebuildMind, annotateSoul, annotateNodeSoul,
  getMindContext, getNodeMeta, getNodesByRole, getNodesAtDepth,
} from '@uix/protocol';

// Add semantic purpose (immutable, returns new doc)
const withSoul = annotateSoul(doc, {
  purpose: 'Authenticates existing users',
  userGoal: 'Get back to work quickly',
  journey: 'onboarding.step-1',
  emotion: 'trust',
});

// Build the AI reasoning surface
const mind = buildMind(withSoul);
mind.screenType;       // 'authentication'
mind.summary;          // 'Authenticates existing users'
mind.dataRequirements; // ['auth.email', 'auth.password']
mind.intents;          // ['auth.login', 'auth.setEmail']

// Get focused context for a single node
const ctx = getMindContext(mind, 'submit-btn');
// { node, children, relationships, screenType, documentSummary }

// Embed mind in document
const selfDescribing = rebuildMind(withSoul);

Validation

typescript

import { validateDocument, validateAnimations } from '@uix/protocol';

// Validate a document with Zod schemas
const result = validateDocument(doc);
if (!result.success) {
  console.error(result.error.issues);
}

// Validate animation definitions
const animResult = validateAnimations(doc);

Animation

typescript

import {
  resolveEasing, easingToCSS, resolveAnimation,
  generateCSSKeyframes, generateCSSStylesheet,
  adaptAnimationForMotion, checkAnimationA11y,
  computeAnimationDuration, interpolateKeyframes,
} from '@uix/protocol';

// Resolve named easing to cubic-bezier values
const easing = resolveEasing('ease-in-out');
const css = easingToCSS(easing); // "cubic-bezier(0.42, 0, 0.58, 1)"

// Resolve animation for a node
const anim = resolveAnimation(doc, 'fade-in-btn');

// Generate CSS @keyframes
const keyframes = generateCSSKeyframes(anim);
const stylesheet = generateCSSStylesheet(doc);

// Accessibility: adapt for reduced motion preference
const reduced = adaptAnimationForMotion(anim, 'reduce');
const a11yReport = checkAnimationA11y(anim);

Diff Engine

typescript

import { computeDocumentDiff, computeSemanticDiff, applyDiff } from '@uix/protocol';

// Structural diff
const diff = computeDocumentDiff(before, after);
// { added, removed, modified: [{ id, path, oldValue, newValue }] }

// Semantic diff (categorized changes)
const semantic = computeSemanticDiff(before, after);
// { layout: [...], style: [...], content: [...], structural: [...] }

Sync Engine

typescript

import { SyncEngine, designToCode, codeToDesign } from '@uix/protocol';

// Design-to-code sync
const codeChanges = designToCode(doc, { target: 'react' });

// Code-to-design sync
const docChanges = codeToDesign(sourceCode, { language: 'tsx' });

App Flow DAG

typescript

import {
  createAppFlowDAG, createScreenNode, createTransition,
  addNode, addTransition, validateDAG, computeGenerationOrder,
  addDefaultStates, addDefaultPopups, getDAGStats,
} from '@uix/protocol';

// Create a new app flow DAG
const dag = createAppFlowDAG({ name: 'My App' });

// Add screens and transitions
const home = createScreenNode('home', 'dashboard', 'Home');
const login = createScreenNode('login', 'authentication', 'Login');
const flow = addTransition(
  addNode(addNode(dag, home), login),
  createTransition('login', 'home', 'auth.success'),
);

// Validate structure
const validation = validateDAG(flow);

// Topological sort for generation order
const order = computeGenerationOrder(flow);

// Auto-add loading/error/empty states
const withStates = addDefaultStates(flow);

QA Immune System

typescript

import {
  annotateNodeQA, annotateDocumentQA, annotateDocumentCI,
  getNodeQAStatus, clearNodeQA,
} from '@uix/protocol';

// Add QA metadata to a node
const withQA = annotateNodeQA(doc, 'submit-btn', {
  coverageStatus: 'covered',
  testIds: ['test-login-submit'],
  regressionRisk: 'low',
});

// Document-level QA summary
const withDocQA = annotateDocumentQA(doc, {
  lastReport: { total: 50, high: 0, medium: 2, low: 1, passed: 47 },
  coveragePercent: 94,
});

---

@uix/codegen

Multi-platform code generation from UIXDocuments.

Basic Usage

typescript

import { UIXCodegen } from '@uix/codegen';

const codegen = new UIXCodegen();
const result = codegen.generate(doc, { target: 'react' });
// result.files — array of generated files
// result.manifest — version, checksums, warnings

Multi-Platform Generation

typescript

const results = codegen.generateMulti(doc, ['react', 'flutter', 'swiftui']);
// Generates for all 3 platforms at once

Platform Renderers

Renderer	Output	Import
`ReactRenderer`	.tsx functional components	`@uix/codegen`
`VueRenderer`	.vue Single File Components	`@uix/codegen`
`FlutterRenderer`	.dart StatelessWidgets	`@uix/codegen`
`SwiftUIRenderer`	.swift Views	`@uix/codegen`
`AngularRenderer`	.ts @Component classes	`@uix/codegen`
`HTMLRenderer`	.html semantic markup	`@uix/codegen`
`ReactNativeRenderer`	.tsx RN components	`@uix/codegen`
`ReactTailwindRenderer`	.tsx with Tailwind classes	`@uix/codegen`
`ComposeRenderer`	.kt Jetpack Compose	`@uix/codegen`

Token Writers

Writer	Output	Import
`TailwindTokenWriter`	tailwind.config.ts	`@uix/codegen`
`CssVarsTokenWriter`	variables.css	`@uix/codegen`
`DartTokenWriter`	tokens.dart	`@uix/codegen`
`SwiftTokenWriter`	Tokens.swift	`@uix/codegen`
`KotlinTokenWriter`	Tokens.kt	`@uix/codegen`

Test Generators

typescript

import { generatePlaywrightTests, generateA11yTests } from '@uix/codegen';

// Playwright integration tests
const playwrightCode = generatePlaywrightTests(doc);

// Accessibility tests
const a11yCode = generateA11yTests(doc);

Router Functions

typescript

import { resolveRenderer, resolveTokenWriter, getSupportedTargets } from '@uix/codegen';

// Resolve the right renderer for a target
const renderer = resolveRenderer('flutter');

// Get all supported code generation targets
const targets = getSupportedTargets();
// ['react', 'vue', 'flutter', 'swiftui', 'angular', 'html', 'react-native', ...]

// Resolve a token writer for a platform
const writer = resolveTokenWriter('tailwind');

---

@uix/runtime

Deterministic 9-step interpretation pipeline: UIXDocument x UIXEnvironment -> UIXInterpretedTree.

Basic Usage

typescript

import { UIXRuntime, interpret } from '@uix/runtime';

// Quick interpret (convenience function)
const tree = interpret(doc, { platform: 'web', theme: 'dark' });

// Full runtime with events and configuration
const runtime = new UIXRuntime({ strict: true });
runtime.on('step:complete', (step) => console.log(step.name));
const tree = runtime.interpret(doc, {
  platform: 'web',
  screenSize: { width: 1440, height: 900 },
  theme: 'dark',
  motionPreference: 'no-preference',
  locale: 'en-US',
});

Pipeline Steps

The runtime executes 9 steps in order. Each step is independently importable:

Step	Function	Purpose
1	`validateEnvironment(env)`	Validate UIXEnvironment
2	`resolveTokens(doc, env)`	Resolve all token references
3	`selectVariant(doc, env)`	Choose active variant
4	`adaptPhysics(doc, env)`	Apply physics adaptations
5	`adaptChemistry(doc, env)`	Apply chemistry bonds
6	`resolveLayout(doc, env)`	Compute final layout
7	`adaptInteractions(doc, env)`	Map interactions to platform
8	`validateBindings(doc, env)`	Validate data bindings
9	`resolveAnimations(doc, env)`	Resolve all animations

Events

typescript

import { UIXRuntime } from '@uix/runtime';

const runtime = new UIXRuntime();

runtime.on('step:start', ({ step }) => { /* ... */ });
runtime.on('step:complete', ({ step, duration }) => { /* ... */ });
runtime.on('step:skip', ({ step, reason }) => { /* ... */ });
runtime.on('pipeline:complete', ({ tree, totalDuration }) => { /* ... */ });
runtime.on('pipeline:error', ({ error, step }) => { /* ... */ });
runtime.on('warning', ({ message, step }) => { /* ... */ });
runtime.on('animation-resolved', ({ nodeId, animation }) => { /* ... */ });

Error Handling

typescript

import { UIXRuntimeError } from '@uix/runtime';

try {
  const tree = runtime.interpret(doc, env);
} catch (err) {
  if (err instanceof UIXRuntimeError) {
    console.error(err.step);    // which step failed
    console.error(err.code);    // error code
    console.error(err.context); // structured context
  }
}

---

Type Quick Reference

Core Types (from @uix/protocol)

Type	Description
`UIXDocument`	Top-level document container
`UIXNode`	Single UI element
`UIXToken`	Design token (color, spacing, etc.)
`UIXLayout`	Layout properties (width, height, padding, gap)
`UIXStyle`	Visual properties (background, foreground, border)
`UIXDiff`	Document diff result
`UIXComponent`	Reusable component definition
`UIXCanonicalRegistry`	Blueprint + renderer registry
`UIXNodeBlueprint`	Canonical node type definition
`UIXMind`	AI reasoning surface
`UIXDocumentSoul`	Document-level semantic purpose
`UIXNodeSoul`	Node-level semantic purpose
`UIXDocumentQA`	Document QA metadata
`UIXNodeQA`	Node QA metadata
`UIXDocumentCI`	CI/CD pipeline status
`UIXEnvironment`	Platform/screen/theme context (runtime input)
`UIXInterpretedTree`	Resolved tree (runtime output)

Codegen Types (from @uix/codegen)

Type	Description
`CodegenResult`	Generated files + manifest
`CodegenTarget`	Platform target identifier
`CodegenManifest`	Version, file checksums, warnings
`FormatOptions`	Code formatting configuration

Runtime Types (from @uix/runtime)

Type	Description
`UIXInterpretedTree`	Fully resolved node tree
`ResolvedAnimation`	Resolved animation with keyframes
`ResolvedKeyframe`	Single keyframe in resolved animation