Voce IR

AI-native intermediate representation for user interfaces.

The code is gone. The experience remains.

Voce IR is a binary IR format, like SPIR-V for graphics but for UI. AI generates typed IR from natural language, a validator enforces quality rules, and a compiler emits optimized output across 7 targets:

Pipeline

Natural Language
    → [AI Bridge] → JSON IR
    → [Validator] → 9 quality passes (46 rules)
    → [Compiler] → Optimized output
    → [Deploy]   → Vercel / Cloudflare / Netlify / Static

Quick Start

# Install
cargo install voce-validator

# Validate an IR file
voce validate my-page.voce.json

# Compile to HTML
voce compile my-page.voce.json

# Deploy
voce deploy my-page.voce.json --adapter static

Three Pillars

Every design decision in Voce IR is anchored to three non-negotiable pillars:

1. Stability — Security is a compile error, not a configuration option. CSRF required on mutations, HTTPS enforced, auth routes need redirects.

2. Experience — Zero-runtime output. No framework JS shipped. Spring physics solved at compile time. Every byte serves the user.

3. Accessibility — Missing SemanticNode is a validation error, not a warning. Keyboard equivalents required on every gesture. Heading hierarchy enforced.

Learn More

• Getting Started — install and compile your first IR
• Schema Reference — every node type documented
• Architecture — how the pipeline works
• Contributing — help build Voce IR

Installation

This guide walks you through installing the Voce IR toolchain.

Prerequisites

• Rust 1.85 or later – Voce IR uses Rust edition 2024. Install Rust via rustup if you don’t have it:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  

• A terminal – All Voce commands run from the command line.

Install the CLI

The voce binary ships as part of the voce-validator crate. Install it with Cargo:

cargo install voce-validator

This compiles and installs the voce binary to your Cargo bin directory (typically ~/.cargo/bin/).

Verify the installation

voce --version

You should see output like:

voce 1.0.0

If the command is not found, ensure ~/.cargo/bin is in your PATH:

export PATH="$HOME/.cargo/bin:$PATH"

Add that line to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

Available commands

Run voce --help to see all available subcommands:

Usage: voce <COMMAND>

Commands:
  validate   Validate a .voce.json IR file
  compile    Compile IR to a target output (HTML, WebGPU, etc.)
  inspect    Print a summary of an IR file
  preview    Compile and open in a browser
  json2bin   Convert JSON IR to binary FlatBuffers format
  bin2json   Convert binary FlatBuffers IR back to JSON
  help       Print this message or the help of the given subcommand(s)

Updating

To update to the latest version:

cargo install voce-validator --force

Building from source

If you want to work with the development version:

git clone https://github.com/nicholasgriffintn/voce-ir.git
cd voce-ir
cargo build --workspace

The compiled binary will be at target/debug/voce.

Next steps

Now that you have the CLI installed, continue to Your First IR File to create a minimal Voce IR document by hand.

Your First IR File

Voce IR documents are JSON files with a .voce.json extension. In this guide you will create a minimal “Hello World” IR file by hand and validate it.

The minimal document

Create a file called hello.voce.json with the following content:

{
  "schema_version_major": 1,
  "schema_version_minor": 0,
  "root": {
    "node_id": "root",
    "viewport_width": { "value": 1024, "unit": "Px" },
    "children": [
      {
        "value_type": "TextNode",
        "value": {
          "node_id": "greeting",
          "content": "Hello, world!",
          "heading_level": 1,
          "font_size": { "value": 36, "unit": "Px" },
          "font_weight": "Bold",
          "color": { "r": 0, "g": 0, "b": 0, "a": 255 }
        }
      }
    ],
    "metadata": {
      "title": "Hello World",
      "description": "A minimal Voce IR document."
    }
  },
  "metadata": {
    "title": "Hello World",
    "description": "A minimal Voce IR document.",
    "language": "en"
  }
}

Structure breakdown

Top-level fields

The ViewRoot (root)

The root node represents the top-level viewport:

• node_id – A unique string identifier. The root is conventionally called "root".
• viewport_width – The design viewport width. Uses a value/unit pair (e.g., 1024 pixels).
• children – An array of child nodes. Each child is a tagged union with value_type and value.
• metadata – Page metadata used for SEO and document identification.

Child nodes (the tagged union)

Every child in the children array has two fields:

• value_type – The node kind. Common types include TextNode, Container, Surface, MediaNode, FormNode, and many others.
• value – The node’s data, whose shape depends on the value_type.

The TextNode

The simplest visible node. In our example:

• node_id – Unique identifier for this node ("greeting").
• content – The text string to display.
• heading_level – Semantic heading level (1-6). Setting this makes the compiler emit an <h1>-<h6> tag. Omit it for body text.
• font_size – Size with unit. Supports Px, Rem, Em, Vw, Vh, Percent.
• font_weight – One of Thin, Light, Regular, Medium, SemiBold, Bold, ExtraBold, Black.
• color – RGBA color with values 0-255.

Validate your file

Run the validator to confirm your IR is structurally correct:

voce validate hello.voce.json

If everything is valid, you will see:

hello.voce.json: VALID (1 node, 0 warnings)

If there are problems – say you forgot the node_id – the validator reports the exact issue:

hello.voce.json: INVALID
  [STR001] root.children[0]: TextNode missing required field "node_id"

Adding more nodes

Here is the same document with a subtitle added below the heading:

{
  "schema_version_major": 1,
  "schema_version_minor": 0,
  "root": {
    "node_id": "root",
    "viewport_width": { "value": 1024, "unit": "Px" },
    "children": [
      {
        "value_type": "TextNode",
        "value": {
          "node_id": "heading",
          "content": "Hello, world!",
          "heading_level": 1,
          "font_size": { "value": 36, "unit": "Px" },
          "font_weight": "Bold",
          "color": { "r": 0, "g": 0, "b": 0, "a": 255 }
        }
      },
      {
        "value_type": "TextNode",
        "value": {
          "node_id": "subtitle",
          "content": "This page was built with Voce IR.",
          "font_size": { "value": 18, "unit": "Px" },
          "color": { "r": 100, "g": 100, "b": 100, "a": 255 }
        }
      }
    ],
    "metadata": {
      "title": "Hello World",
      "description": "A minimal Voce IR document."
    }
  },
  "metadata": {
    "title": "Hello World",
    "description": "A minimal Voce IR document.",
    "language": "en"
  }
}

Note that the subtitle omits heading_level – it will render as a paragraph, not a heading.

Next steps

Your IR file is ready. Continue to Compiling to HTML to turn it into a working web page.

Compiling to HTML

Once you have a valid .voce.json file, the Voce compiler transforms it into production-ready output. This guide covers the DOM compile target, which produces a single-file HTML page.

Validate first

Always validate before compiling. The compiler assumes valid input:

voce validate hello.voce.json

hello.voce.json: VALID (2 nodes, 0 warnings)

Compile

Run the compile command:

voce compile hello.voce.json

By default this writes output to the dist/ directory:

Compiling hello.voce.json → dist/hello.html
  2 nodes compiled
  Output: dist/hello.html (4.2 KB)

What the compiler produces

The output is a single self-contained HTML file. Open dist/hello.html in any browser and you will see your rendered page.

Key properties of the compiled output:

• Zero runtime dependencies. No JavaScript frameworks, no CSS libraries, no CDN links. The HTML file contains everything it needs inline.
• Semantic markup. A TextNode with heading_level: 1 becomes an <h1>. Containers become appropriate structural elements. Accessibility attributes are wired automatically from SemanticNode references.
• Surgical DOM updates. When the IR includes state machines, the compiler emits minimal JavaScript that performs targeted DOM mutations – similar to what Svelte or SolidJS produce, but generated from binary IR rather than a component DSL.
• No supply chain risk. Because there are zero external dependencies in the output, there is no attack surface from third-party packages.

Output options

Custom output directory

voce compile hello.voce.json --output ./build

JSON output mode

For debugging, you can emit a JSON representation of the compile plan:

voce compile hello.voce.json --format json

Preview in the browser

The preview command compiles and immediately opens the result in your default browser:

voce preview hello.voce.json

This is the fastest way to iterate. It compiles to a temporary directory and launches the browser in one step.

Compile targets

The DOM/HTML target is the default. Voce supports multiple compile targets:

For example, to compile for email:

voce compile hello.voce.json --target email

Inspecting the IR

Before compiling, you can get a quick summary of what is in your IR file:

voce inspect hello.voce.json

Document: Hello World
Schema:   v1.0
Nodes:    2 (1 TextNode, 1 ViewRoot)
Language: en
Warnings: 0

A complete workflow

Putting it all together, a typical workflow looks like this:

# 1. Create or generate the IR file
#    (by hand, via AI, or from an existing tool)

# 2. Validate
voce validate my-page.voce.json

# 3. Compile
voce compile my-page.voce.json

# 4. Preview
voce preview my-page.voce.json

# 5. Deploy the output
#    dist/my-page.html is a static file -- serve it from anywhere

Next steps

Writing IR by hand works for learning, but Voce is designed for AI authorship. Continue to AI Generation to learn how to generate IR from natural language.

AI Generation

Voce IR is designed from the ground up for AI authorship. Rather than having an AI write framework code, the AI generates typed IR directly and a compiler handles the output. There are two ways to generate IR with AI: the TypeScript SDK and the MCP server.

Approaches

TypeScript SDK

The @voce-ir/ai-bridge package provides a high-level API for generating IR from natural language prompts. It handles schema context, validation, and iterative refinement automatically.

MCP Server

The Voce MCP (Model Context Protocol) server exposes IR generation as a tool that any MCP-compatible client can call – including Claude Desktop, Claude Code, and other AI assistants. This lets you generate and compile IR through conversation without writing any integration code.

SDK quickstart

Install

npm install @voce-ir/ai-bridge

Set your API key

The SDK uses the Anthropic API to generate IR. Export your key:

export ANTHROPIC_API_KEY=sk-ant-...

Generate IR from a prompt

import { VoceGenerator } from "@voce-ir/ai-bridge";

const generator = new VoceGenerator({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// Describe what you want in natural language
const result = await generator.generate(
  "A landing page with a bold headline that says 'Ship faster with Voce', " +
  "a subtitle explaining the product, and a blue call-to-action button."
);

// result.ir contains the validated .voce.json document
console.log(JSON.stringify(result.ir, null, 2));

// result.warnings contains any validation warnings
if (result.warnings.length > 0) {
  console.warn("Warnings:", result.warnings);
}

Generate and compile in one step

import { VoceGenerator } from "@voce-ir/ai-bridge";
import { writeFileSync } from "fs";

const generator = new VoceGenerator({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const result = await generator.generateAndCompile(
  "A contact form with name, email, and message fields. " +
  "Include proper validation and a submit button.",
  { target: "dom" }
);

// result.html contains the compiled single-file HTML
writeFileSync("dist/contact.html", result.html);

Iterative refinement

The SDK supports multi-turn refinement. The AI asks clarifying questions when the prompt is ambiguous, and you can provide follow-up instructions:

const session = generator.createSession();

// Initial generation
let result = await session.generate(
  "A pricing page with three tiers"
);

// Refine based on the result
result = await session.refine(
  "Make the middle tier visually prominent and add a 'Most Popular' badge"
);

// Further refinement
result = await session.refine(
  "Add a toggle to switch between monthly and annual pricing"
);

// The final IR incorporates all refinements
writeFileSync("pricing.voce.json", JSON.stringify(result.ir, null, 2));

MCP server

Setup with Claude Desktop

Add the Voce MCP server to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "voce-ir": {
      "command": "npx",
      "args": ["@voce-ir/mcp-server"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Once configured, you can ask Claude to generate Voce IR through normal conversation. The MCP server exposes tools for generating, validating, compiling, and previewing IR.

Available MCP tools

The playground

Try Voce IR without installing anything at voce-ir.xyz. The playground provides:

• A prompt input for natural language descriptions
• Live IR preview with syntax highlighting
• One-click compilation to HTML
• A visual preview of the compiled output

Note that the playground requires an API key for generation features. Compilation and validation work without one.

How generation works

Under the hood, the AI generation pipeline works as follows:

1. Schema context. The SDK provides the AI model with the full Voce IR schema – all node types, their fields, valid values, and constraints.
2. Generation. The model generates a .voce.json document from your natural language prompt.
3. Validation. The generated IR is run through the full validator (structural checks, accessibility, security, SEO, forms, i18n).
4. Auto-repair. If validation fails, the SDK sends the errors back to the model for automatic correction. This loop runs up to 3 times.
5. Output. The validated IR is returned, ready for compilation.

This pipeline ensures that AI-generated IR is always valid and meets all quality gates – accessibility, security, and SEO checks are compile errors, not optional linting.

Next steps

• Explore the Schema Reference to understand all available node types
• Read about Validation Passes to understand what the validator checks
• See the CLI Reference for all command options

voce validate

Run the full Voce IR validation suite against a .voce.json file. The validator executes 9 independent passes covering structural integrity, accessibility, security, SEO, and more. Any failing pass causes a non-zero exit.

Usage

voce validate <FILE> [OPTIONS]

Arguments

Options

Validation Passes

The validator runs the following passes in order:

Exit Codes

Examples

Validate a file with colored terminal output:

voce validate examples/landing-page.voce.json

Validate and get JSON output (useful for CI or piping to jq):

voce validate examples/landing-page.voce.json --format json

Fail the build on any warning:

voce validate my-app.voce.json --warn-as-error

Combine with other tools:

# Validate, then compile only if valid
voce validate app.voce.json && voce compile app.voce.json

JSON Output Schema

When --format json is used, the output is a JSON object:

{
  "valid": false,
  "errors": [
    { "pass": "A11Y", "code": "A11Y003", "message": "Image node missing alt text", "node_id": "img-hero" }
  ],
  "warnings": [
    { "pass": "MOT", "code": "MOT005", "message": "Animation duration exceeds 5s", "node_id": "fade-in" }
  ]
}

voce compile

Compile a validated Voce IR file into a single-file HTML document. The compiler runs the full validation suite first – if validation fails, compilation is aborted and errors are printed.

Usage

voce compile <FILE> [OPTIONS]

Arguments

Options

How It Works

1. Validate – all 9 validation passes run. Any error aborts compilation.
2. Resolve layout – Taffy computes flexbox/grid geometry at compile time.
3. Emit HTML – a single self-contained .html file is written. All styles are inlined. There are zero runtime dependencies.

The compiled output follows the SolidJS/Svelte pattern of surgical DOM construction – no virtual DOM, no framework runtime.

Exit Codes

Examples

Compile with default output path:

voce compile examples/landing-page.voce.json
# writes dist/landing-page.html

Compile to a specific output file:

voce compile app.voce.json -o build/index.html

Compile with debug attributes for development:

voce compile app.voce.json --debug
# Each element gets: <div data-voce-id="container-main">...</div>

Validate and compile in sequence:

voce validate app.voce.json --format json && voce compile app.voce.json

Debug Mode

When --debug is passed, every emitted HTML element receives a data-voce-id attribute containing the IR node ID it was generated from. This is useful for:

• Tracing compiled output back to the source IR
• Browser DevTools inspection
• Integration with voce inspect for cross-referencing

Do not ship debug builds to production – the extra attributes increase file size and expose internal structure.

Output Format

The compiled HTML file is fully self-contained:

• Inline <style> block with all computed styles
• Inline <script> block for state machines and event handlers (if present)
• No external dependencies, CDN links, or network requests
• Valid HTML5 with lang attribute and semantic structure

voce deploy

Validate, compile, and prepare a deployment bundle for a target hosting platform. Wraps the full pipeline (validate, compile) and adds platform-specific configuration files.

Usage

voce deploy <FILE> [OPTIONS]

Arguments

Options

Adapters

Each adapter produces a deployment-ready bundle in dist/:

Configuration

The deploy command reads defaults from .voce/config.toml if present:

[deploy]
adapter = "vercel"
output_dir = "dist"

Command-line flags override config file values.

Exit Codes

Examples

Deploy as static files (default):

voce deploy app.voce.json
# writes dist/app.html

Deploy to Vercel:

voce deploy app.voce.json --adapter vercel
# writes dist/app.html and dist/vercel.json

Preview what a Cloudflare deploy would produce:

voce deploy app.voce.json --adapter cloudflare --dry-run

Deploy with config file defaults:

# With .voce/config.toml setting adapter = "netlify"
voce deploy app.voce.json
# uses netlify adapter from config

Dry Run

The --dry-run flag prints the list of files that would be written and their approximate sizes, without creating or modifying anything on disk. Use this to verify adapter output before committing to a deploy.

$ voce deploy app.voce.json --adapter vercel --dry-run
[dry-run] dist/app.html (12.4 KB)
[dry-run] dist/vercel.json (0.3 KB)

Pipeline

The deploy command runs the full pipeline internally:

1. voce validate <FILE> – abort on errors
2. voce compile <FILE> – produce HTML
3. Generate adapter-specific files
4. Write all files to the output directory

voce inspect

Display a human-readable summary of a Voce IR file. Shows node counts, type distribution, state machines, and feature usage without compiling or validating.

Usage

voce inspect <FILE>

Arguments

Output

The inspect command prints a structured summary to stdout. There are no output format options – the output is always a human-readable table.

Summary Sections

Document overview – total node count, document-level metadata (title, locale, auth configuration).

Node type distribution – count of each node type present in the IR (e.g., Container: 5, TextNode: 12, MediaNode: 3).

State machines – names, state counts, and transition counts for each StateMachine node.

Features detected – which optional IR features are in use: animations, forms, navigation/routing, i18n, SEO metadata, theming, accessibility annotations, data/backend bindings.

Exit Codes

Examples

Inspect a landing page IR:

voce inspect examples/landing-page.voce.json

Example output:

Voce IR Summary
===============

Document: landing-page
Nodes:    37
Types:    11 distinct

Node Distribution:
  Container      8
  Surface        4
  TextNode      12
  MediaNode      3
  FormNode       1
  FormField      4
  StateMachine   1
  SemanticNode   2
  PageMetadata   1
  AnimationTransition 1

State Machines:
  form-states    3 states, 4 transitions

Features:
  [x] Accessibility
  [x] Forms
  [x] SEO metadata
  [x] Animation
  [ ] Navigation
  [ ] Internationalization
  [ ] Theming
  [ ] Data bindings

Use Cases

• Quick audit – understand what an IR file contains before validating or compiling it.
• CI reporting – log IR complexity metrics alongside build output.
• Debugging – verify that AI-generated IR includes the expected node types and features.
• Diffing – compare inspect output across versions to spot structural changes.

Notes

The inspect command does not validate the IR. A file with structural errors can still be inspected as long as it is parseable JSON. To check correctness, use voce validate.

voce preview

Compile a Voce IR file and open the result in the default web browser. A convenience command that combines voce compile with a platform-aware browser launch.

Usage

voce preview <FILE>

Arguments

How It Works

1. Validate – runs the full 9-pass validation suite.
2. Compile – produces a self-contained HTML file in a temporary location (or dist/ if it exists).
3. Open – launches the compiled HTML in the default browser using the platform-appropriate command.

Platform Commands

Exit Codes

Examples

Preview a landing page:

voce preview examples/landing-page.voce.json

Preview after making changes to the IR:

# Edit the IR (or regenerate via AI), then preview
voce preview app.voce.json

Chain with validation for verbose feedback:

voce validate app.voce.json && voce preview app.voce.json

Comparison with compile

For production builds, use voce compile. For quick iteration during development, use voce preview.

Notes

• The preview command always compiles a fresh copy. It does not cache previous builds.
• Debug attributes (data-voce-id) are not included in preview builds. Use voce compile --debug if you need them, then open the output file manually.
• If no default browser is configured on Linux, xdg-open may fail silently. Set the BROWSER environment variable as a fallback.
• The compiled HTML is fully self-contained with no external dependencies, so it renders correctly when opened as a local file.

Schema Overview

Voce IR uses FlatBuffers as its binary serialization format. Every UI is represented as a VoceDocument containing a tree of typed nodes spanning 11 domains: layout, state, motion, navigation, accessibility, theming, data, forms, SEO, and i18n.

Binary Format

FlatBuffers provides zero-copy deserialization, schema evolution with forward/backward compatibility, and a compact binary representation. Voce IR files use the VOCE file identifier and the .voce extension.

The binary format is immutable by design. Runtime mutable state lives in a separate reactive layer managed by the compiler output, not in the buffer itself.

JSON Canonical Representation

Every Voce IR binary round-trips losslessly to and from JSON. The JSON representation serves as:

• AI generation target – LLMs emit JSON, which is then compiled to binary
• Debugging format – human-inspectable when needed
• Version control diffing – text diffs for review workflows
• Escape hatch – interop with tools that cannot read FlatBuffers

The JSON form is not intended for hand-authoring. It is a machine-readable text serialization of the IR.

ChildUnion Pattern

FlatBuffers does not support vectors of unions directly in Rust codegen. Voce IR works around this with a wrapper table:

{
  "children": [
    { "value_type": "Container", "value": { "node_id": "c1", "layout": "Flex" } },
    { "value_type": "TextNode", "value": { "node_id": "t1", "content": "Hello" } }
  ]
}

The ChildUnion is a union of all 27 node types across all domains. Each child entry is wrapped in a ChildNode table containing a single value field of type ChildUnion.

ChildUnion Members

VoceDocument

The root table of every Voce IR file.

Minimal Example

{
  "schema_version_major": 0,
  "schema_version_minor": 1,
  "root": {
    "node_id": "root",
    "document_language": "en",
    "children": [
      {
        "value_type": "TextNode",
        "value": {
          "node_id": "greeting",
          "content": "Hello, world",
          "heading_level": 1
        }
      }
    ]
  }
}

Foundation Types

These shared types appear throughout the schema.

LengthUnit Values

Px, Rem, Em, Percent, Vw, Vh, Dvh, Svh, Auto, FitContent, MinContent, MaxContent, Fr

EasingType Values

Linear, CubicBezier, Spring, Steps, CustomLinear

Layout Nodes

Layout nodes define the spatial composition of a Voce IR document. There are five layout node types: ViewRoot (the document root), Container (grouping and layout), Surface (visual rectangles), TextNode (styled text), and MediaNode (images, video, audio).

ViewRoot

Top-level container for a document or route. One ViewRoot per page. Defines viewport bounds, document language, and holds the flat semantic node list.

{
  "node_id": "root",
  "document_language": "en",
  "text_direction": "Ltr",
  "background": { "r": 255, "g": 255, "b": 255, "a": 255 },
  "children": []
}

Container

Groups children with a layout strategy. The primary structural node for composition.

{
  "node_id": "hero-row",
  "layout": "Flex",
  "direction": "Row",
  "gap": { "value": 16, "unit": "Px" },
  "padding": {
    "top": { "value": 24, "unit": "Px" },
    "right": { "value": 24, "unit": "Px" },
    "bottom": { "value": 24, "unit": "Px" },
    "left": { "value": 24, "unit": "Px" }
  },
  "main_align": "Center",
  "cross_align": "Center",
  "children": []
}

Surface

A visible rectangular region used for cards, backgrounds, dividers, and decorative elements.

{
  "node_id": "card",
  "fill": { "r": 248, "g": 248, "b": 248, "a": 255 },
  "corner_radius": {
    "top_left": { "value": 8, "unit": "Px" },
    "top_right": { "value": 8, "unit": "Px" },
    "bottom_right": { "value": 8, "unit": "Px" },
    "bottom_left": { "value": 8, "unit": "Px" }
  },
  "shadow": [{
    "offset_x": { "value": 0, "unit": "Px" },
    "offset_y": { "value": 2, "unit": "Px" },
    "blur": { "value": 8, "unit": "Px" },
    "spread": { "value": 0, "unit": "Px" },
    "color": { "r": 0, "g": 0, "b": 0, "a": 25 }
  }],
  "decorative": false,
  "children": []
}

TextNode

Styled text content. All typography properties are explicit with no cascade.

{
  "node_id": "page-title",
  "content": "Welcome to Voce",
  "heading_level": 1,
  "font_size": { "value": 3, "unit": "Rem" },
  "font_weight": "Bold",
  "color": { "r": 17, "g": 24, "b": 39, "a": 255 }
}

MediaNode

Image, video, audio, or SVG with explicit dimensions, loading strategy, and format negotiation.

{
  "node_id": "hero-image",
  "media_type": "Image",
  "src": "/images/hero.webp",
  "alt": "Product dashboard showing analytics overview",
  "width": { "value": 100, "unit": "Percent" },
  "aspect_ratio": 1.778,
  "above_fold": true,
  "loading": "Eager"
}

State & Logic Nodes

All state in Voce IR is modeled as explicit, typed finite state machines. There are no implicit closures, dependency arrays, or hook ordering. The compiler can statically analyze every possible state transition.

StateMachine

A named finite state machine with typed states, transitions, guards, and effects. Every component’s behavior is a state machine. The validator checks reachability (no dead states) and deadlock freedom.

State

Transition

StateMachine

{
  "node_id": "btn-state",
  "name": "button-state",
  "states": [
    { "name": "idle", "initial": true },
    { "name": "hovered" },
    { "name": "pressed" },
    { "name": "disabled", "terminal": true }
  ],
  "transitions": [
    { "event": "hover", "from": "idle", "to": "hovered" },
    { "event": "unhover", "from": "hovered", "to": "idle" },
    { "event": "press", "from": "hovered", "to": "pressed" },
    { "event": "release", "from": "pressed", "to": "idle", "effect": "submit-effect" }
  ]
}

DataNode

Declares an external data dependency. The compiler emits fetch code with caching, error handling, and loading states.

DataSource

{
  "node_id": "user-data",
  "name": "current-user",
  "source": {
    "provider": "Rest",
    "endpoint": "/api/users/me",
    "method": "GET"
  },
  "cache_strategy": "StaleWhileRevalidate",
  "stale_time": 60000,
  "auth_required": true
}

ComputeNode

A pure function from inputs to output. Referentially transparent, so the compiler can memoize or pre-compute at build time.

ComputeInput

{
  "node_id": "total-compute",
  "name": "order-total",
  "inputs": [
    { "name": "price", "source_node_id": "product-data", "field_path": "price" },
    { "name": "qty", "source_node_id": "cart-ctx", "field_path": "quantity" }
  ],
  "expression": "price * qty",
  "output_type": "number"
}

EffectNode

A side effect triggered by a state transition. Effects attach to transitions, never to states, eliminating mount/unmount ambiguity.

{
  "node_id": "track-click",
  "name": "analytics-click",
  "effect_type": "Analytics",
  "config": [
    { "key": "event", "value": "button_click" },
    { "key": "category", "value": "cta" }
  ]
}

ContextNode

Shared state scoped to a subtree. Replaces React Context, Redux, and prop drilling. Typed with explicit read/write boundaries.

{
  "node_id": "cart-ctx",
  "name": "shopping-cart",
  "initial_value": "{ \"items\": [], \"quantity\": 0 }",
  "global": true
}

Motion & Interaction Nodes

Animation is a first-class IR concern in Voce IR. Every motion declaration includes a reduced-motion fallback, which the validator enforces as required. The compiler uses a tiered output strategy: CSS transitions, Web Animations API, then minimal requestAnimationFrame JavaScript.

AnimationTransition

Animates property changes between state machine states. The compiler chooses the optimal output technique based on the trigger type and interruptibility requirements.

AnimatedProperty

Easing

The Easing table supports multiple timing function types.

{
  "node_id": "fade-in",
  "target_node_id": "hero-section",
  "trigger_state_machine": "page-state",
  "trigger_event": "enter",
  "properties": [
    { "property": "opacity", "from": "0", "to": "1" },
    { "property": "transform.translateY", "from": "20px", "to": "0px" }
  ],
  "duration": { "ms": 300 },
  "easing": { "easing_type": "Spring", "stiffness": 300, "damping": 25, "mass": 1 },
  "reduced_motion": { "strategy": "Remove" }
}

Sequence

Choreographed animation timeline. Multiple AnimationTransitions played in sequence or parallel with stagger offsets.

SequenceStep

{
  "node_id": "entrance-seq",
  "steps": [
    { "transition_id": "fade-in-title" },
    { "transition_id": "fade-in-subtitle", "delay": { "ms": 100 } },
    { "transition_id": "fade-in-cta", "delay": { "ms": 100 } }
  ],
  "stagger": { "ms": 50 },
  "reduced_motion": { "strategy": "Remove" }
}

GestureHandler

Maps touch, mouse, and keyboard input to state transitions or continuous property updates. The validator requires a keyboard_key for accessibility.

{
  "node_id": "card-tap",
  "target_node_id": "card-surface",
  "gesture_type": "Tap",
  "trigger_event": "select",
  "trigger_state_machine": "card-state",
  "keyboard_key": "Enter"
}

ScrollBinding

Binds node properties to scroll position. Compiled to CSS scroll-driven animations where supported, with IntersectionObserver fallback.

{
  "node_id": "parallax-bg",
  "target_node_id": "bg-image",
  "scroll_trigger": "ViewProgress",
  "properties": [
    { "property": "transform.translateY", "from": "0px", "to": "-50px" }
  ],
  "reduced_motion": { "strategy": "Remove" }
}

PhysicsBody

Attaches physics simulation to a node for spring animations, momentum scrolling, and procedural motion. Non-interruptible springs are compiled to CSS linear() at build time.

{
  "node_id": "spring-body",
  "target_node_id": "draggable-card",
  "stiffness": 400,
  "damping": 30,
  "mass": 1,
  "interruptible": true
}

ReducedMotion

Every animation must reference a ReducedMotion alternative. The validator rejects IR where any AnimationTransition, Sequence, or ScrollBinding lacks one.

Strategy values:

• Remove – snap to final state, no animation
• Simplify – replace with a simpler animation (e.g., fade instead of slide)
• ReduceDuration – keep the animation but make it near-instant
• Functional – animation serves a functional purpose (spinner, progress); simplify but do not remove

Navigation & Routing Nodes

Routing in Voce IR is modeled as a state machine where states are views and transitions are navigation events. The schema supports nested routes, guards for auth checks, data preloading, and sitemap generation.

RouteMap

Top-level routing configuration for a multi-route application. Referenced from VoceDocument.routes.

{
  "node_id": "app-routes",
  "routes": [
    { "path": "/", "name": "home", "view_root_id": "home-root" },
    { "path": "/about", "name": "about", "view_root_id": "about-root" }
  ],
  "not_found_route": "/404"
}

RouteEntry

Defines a single route mapping a URL path to a ViewRoot.

{
  "path": "/dashboard",
  "name": "dashboard",
  "view_root_id": "dashboard-root",
  "guard": {
    "requires_auth": true,
    "required_roles": ["user"],
    "redirect_on_fail": "/login"
  },
  "preload_data": ["user-data", "dashboard-stats"],
  "sitemap_priority": 0.3,
  "exclude_from_sitemap": true
}

RouteGuard

Access control for a route. The compiler emits authentication and authorization checks before rendering.

{
  "requires_auth": true,
  "required_roles": ["admin"],
  "redirect_on_fail": "/login"
}

RouteTransitionConfig

Configures the animation played when navigating between routes.

SharedElementPair

{
  "transition_type": "Crossfade",
  "duration": { "ms": 200 },
  "easing": { "easing_type": "CubicBezier", "x1": 0.4, "y1": 0, "x2": 0.2, "y2": 1 },
  "reduced_motion": { "strategy": "Remove" }
}

Accessibility & Semantics Nodes

Accessibility in Voce IR is structurally required, not opt-in. Every interactive visual node must reference a SemanticNode. The validator rejects IR where interactive elements lack semantic annotations. Explicit opt-outs (decorative: true, presentation: true) are supported for valid exceptions.

SemanticNode

Parallel semantic tree entry for a visual node. Carries ARIA role, label, relationships, and keyboard focus configuration. Visual nodes reference SemanticNodes via the semantic_node_id field. All SemanticNodes live in a flat list on ViewRoot.

The validator enforces that interactive roles (“button”, “link”, “textbox”, etc.) have either label or labelled_by set.

{
  "node_id": "sem-cta-btn",
  "role": "button",
  "label": "Get started with Voce IR",
  "tab_index": 0
}

LiveRegion

Declares a region whose content changes are announced by screen readers. Used for toast notifications, form errors, cart updates, and status messages.

Politeness values:

• Polite – wait for the user to be idle before announcing
• Assertive – interrupt current speech to announce immediately
• Off – region is silent

{
  "node_id": "toast-live",
  "target_node_id": "toast-container",
  "politeness": "Assertive",
  "atomic": true,
  "role_description": "Notification"
}

FocusTrap

Constrains keyboard focus to a subtree. Used for modals, drawers, and dialogs. The compiler emits focus management JavaScript.

{
  "node_id": "modal-trap",
  "container_node_id": "modal-container",
  "initial_focus_node_id": "modal-close-btn",
  "escape_behavior": "CloseOnEscape",
  "restore_focus": true
}

ReducedMotion

Every animation in the IR must reference a ReducedMotion alternative. The validator rejects any AnimationTransition, Sequence, or ScrollBinding that lacks one. See the Motion chapter for the full ReducedMotion reference.

Strategy values:

Theming & Personalization Nodes

Design tokens, multi-theme support, responsive breakpoints, and personalization slots. Theme switching is modeled as a state machine transition (e.g., light to dark).

ThemeNode

A named set of design tokens. Multiple themes can coexist (light, dark, high-contrast). Referenced from VoceDocument.theme and VoceDocument.alternate_themes.

ColorPalette

Semantic color tokens. Each token is a Color struct (r, g, b, a).

TypographyScale

SpacingScale

{
  "node_id": "theme-light",
  "name": "light",
  "colors": {
    "primary": { "r": 59, "g": 130, "b": 246, "a": 255 },
    "primary_foreground": { "r": 255, "g": 255, "b": 255, "a": 255 },
    "background": { "r": 255, "g": 255, "b": 255, "a": 255 },
    "foreground": { "r": 17, "g": 24, "b": 39, "a": 255 }
  },
  "spacing": {
    "base": { "value": 4, "unit": "Px" },
    "multipliers": [0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32]
  }
}

PersonalizationSlot

A point in the IR that adapts based on user context: locale, device type, color scheme preference, A/B test cohort, or custom conditions.

PersonalizationVariant

PersonalizationCondition

{
  "node_id": "mobile-variant",
  "name": "mobile-layout",
  "variants": [
    {
      "conditions": [
        { "condition_type": "DeviceType", "operator": "eq", "value": "mobile" }
      ],
      "hide_nodes": ["desktop-sidebar"],
      "show_nodes": ["mobile-nav"]
    }
  ],
  "default_variant_index": 0
}

ResponsiveRule

Adapts layout based on viewport dimensions using explicit breakpoints with property overrides. Unlike CSS media queries, there is no cascading.

Breakpoint

ResponsiveOverride

PropertyOverride

{
  "node_id": "responsive-grid",
  "breakpoints": [
    { "name": "sm", "min_width": { "value": 640, "unit": "Px" } },
    { "name": "lg", "min_width": { "value": 1024, "unit": "Px" } }
  ],
  "responsive_overrides": [
    {
      "breakpoint_name": "sm",
      "overrides": [
        { "target_node_id": "content-grid", "property": "grid_columns", "value": "1" }
      ]
    },
    {
      "breakpoint_name": "lg",
      "overrides": [
        { "target_node_id": "content-grid", "property": "grid_columns", "value": "3" }
      ]
    }
  ]
}

Data & Backend Nodes

The data layer covers mutations (ActionNode), real-time subscriptions (SubscriptionNode), authentication (AuthContextNode), CMS content (ContentSlot), and structured rich text (RichTextNode). Data reads are handled by DataNode in the State chapter.

ActionNode

Declares a server mutation with optimistic update strategy, cache invalidation, and error handling. The compiler emits mutation calls with rollback support.

OptimisticConfig

ErrorHandling

{
  "node_id": "add-to-cart",
  "name": "add-item",
  "source": {
    "provider": "Rest",
    "endpoint": "/api/cart/items"
  },
  "method": "POST",
  "optimistic": {
    "strategy": "MirrorInput",
    "target_data_node_id": "cart-data",
    "rollback": "Revert"
  },
  "invalidates": ["cart-data"],
  "csrf_protected": true
}

SubscriptionNode

Real-time data via WebSocket, Server-Sent Events, or polling. Keeps a DataNode updated with live changes.

ConnectionConfig

{
  "node_id": "chat-sub",
  "name": "chat-messages",
  "source": {
    "provider": "Supabase",
    "endpoint": "wss://project.supabase.co/realtime/v1"
  },
  "transport": "WebSocket",
  "channel": "messages",
  "update_strategy": "Append",
  "target_data_node_id": "messages-data"
}

AuthContextNode

Application-level auth configuration. Provider-agnostic; the compiler adapts output to the chosen provider.

{
  "node_id": "app-auth",
  "provider": "Supabase",
  "session_strategy": "JwtCookie",
  "role_field": "user_metadata.role",
  "login_action_id": "login-action",
  "logout_action_id": "logout-action"
}

ContentSlot

Declares a CMS content dependency. The cache strategy determines compiler behavior: static content is baked in at build time, ISR adds revalidation, and dynamic content is fetched at runtime.

{
  "node_id": "hero-content",
  "content_key": "homepage-hero",
  "source": {
    "provider": "sanity",
    "endpoint": "https://project.api.sanity.io/v2023-01-01"
  },
  "cache_strategy": "Isr",
  "content_type": "RichText"
}

RichTextNode

Structured rich text with paragraphs, headings, lists, images, code blocks, and more. Maps directly from Sanity Portable Text, Contentful Rich Text JSON, and Payload Lexical JSON.

RichTextBlock

RichTextSpan

{
  "node_id": "article-body",
  "blocks": [
    {
      "block_type": "Heading",
      "level": 2,
      "children": [{ "text": "Getting Started" }]
    },
    {
      "block_type": "Paragraph",
      "children": [
        { "text": "Voce IR uses " },
        { "text": "FlatBuffers", "marks": ["Bold"] },
        { "text": " for zero-copy deserialization." }
      ]
    }
  ]
}

Forms Nodes

Declarative forms with compiler-generated validation, progressive enhancement, and accessible markup. The compiler emits native <form> elements that work without JavaScript, then layers on client-side validation and enhanced submission handling.

FormNode

Top-level form declaration containing fields, validation, and submission configuration.

ValidationMode Values

{
  "node_id": "contact-form",
  "name": "contact",
  "fields": [
    {
      "name": "email",
      "field_type": "Email",
      "label": "Email address",
      "autocomplete": "Email",
      "validations": [
        { "rule_type": "Required", "message": "Email is required" },
        { "rule_type": "Email", "message": "Enter a valid email" }
      ]
    },
    {
      "name": "message",
      "field_type": "Textarea",
      "label": "Message",
      "validations": [
        { "rule_type": "Required", "message": "Message is required" },
        { "rule_type": "MinLength", "value": "10", "message": "At least 10 characters" }
      ]
    }
  ],
  "validation_mode": "OnBlurThenChange",
  "submission": {
    "action_node_id": "submit-contact",
    "encoding": "Json",
    "progressive": true,
    "success_redirect": "/thank-you"
  }
}

FormField

Individual form field with type, label, validation, and accessibility attributes.

AutocompleteHint Values

Off, On, Name, GivenName, FamilyName, Email, Username, NewPassword, CurrentPassword, Tel, StreetAddress, City, State, PostalCode, Country, CreditCardNumber, CreditCardExp, CreditCardCsc

{
  "name": "password",
  "field_type": "Password",
  "label": "Password",
  "autocomplete": "NewPassword",
  "validations": [
    { "rule_type": "Required", "message": "Password is required" },
    { "rule_type": "MinLength", "value": "8", "message": "At least 8 characters" },
    { "rule_type": "Pattern", "value": "[A-Z]", "message": "Must contain an uppercase letter" }
  ]
}

ValidationRule

A single client-side validation constraint applied to a FormField.

{ "rule_type": "MaxLength", "value": "500", "message": "Maximum 500 characters" }

FormSubmission

Configures how the form is submitted and what happens on success or failure.

FormFieldGroup

Logical grouping of fields, rendered as <fieldset> with <legend>.

CrossFieldValidation

Validation spanning multiple fields (e.g., password confirmation).

{
  "field_names": ["password", "confirm_password"],
  "expression": "password == confirm_password",
  "message": "Passwords must match",
  "target_field": "confirm_password"
}

SEO Nodes

Search engine optimization metadata for Voce IR documents. The compiler emits <head> meta tags, JSON-LD structured data, and generates sitemap.xml and robots.txt. SEO metadata is attached per-page via the metadata field on ViewRoot.

PageMetadata

Per-page SEO configuration. One per ViewRoot. The validator warns if title exceeds 60 characters or description exceeds 160 characters.

{
  "title": "Voce IR Documentation",
  "title_template": "%s | Voce IR",
  "description": "Schema reference and guide for the Voce IR intermediate representation.",
  "canonical_url": "https://voce-ir.xyz/docs",
  "robots": { "index": true, "follow": true },
  "open_graph": {
    "title": "Voce IR Documentation",
    "description": "Schema reference and guide for the Voce IR intermediate representation.",
    "og_type": "Website",
    "site_name": "Voce IR"
  }
}

OpenGraphData

Open Graph protocol metadata for social sharing previews.

{
  "title": "Introducing Voce IR",
  "description": "An AI-native UI intermediate representation.",
  "image": "https://voce-ir.xyz/og-image.png",
  "image_alt": "Voce IR logo and tagline",
  "image_width": 1200,
  "image_height": 630,
  "og_type": "Website",
  "site_name": "Voce IR"
}

StructuredData

JSON-LD structured data block for search engine rich results. The validator checks basic conformance to the declared Schema.org type.

{
  "schema_type": "Article",
  "properties_json": "{\"headline\":\"Getting Started with Voce IR\",\"author\":{\"@type\":\"Person\",\"name\":\"Voce Team\"},\"datePublished\":\"2025-01-15\"}"
}

TwitterCardData

Twitter (X) Card metadata for link previews on the platform.

RobotsDirective

Controls search engine crawling and indexing behavior for the page.

AlternateLink

Hreflang link for international SEO, connecting pages across locales.

[
  { "hreflang": "en-US", "href": "https://voce-ir.xyz/en/docs" },
  { "hreflang": "fr-FR", "href": "https://voce-ir.xyz/fr/docs" },
  { "hreflang": "x-default", "href": "https://voce-ir.xyz/docs" }
]

MetaTag

Custom meta tag for cases not covered by the structured fields above.

Internationalization Nodes

Voce IR supports two i18n compilation modes. In static mode (default), the compiler resolves all LocalizedStrings against the target locale’s MessageCatalog and emits fully resolved HTML per locale with zero runtime i18n code. In runtime mode, a single output is emitted with locale switching and on-demand translation loading (~1KB runtime).

LocalizedString

A reference to a translated message, used in TextNode content, FormField labels, PageMetadata, and anywhere user-visible text appears. The validator checks that every message_key exists in all declared locale catalogs.

MessageParameter

{
  "message_key": "cart.item_count",
  "default_value": "{count, plural, one {# item} other {# items}} in your cart",
  "parameters": [
    { "name": "count", "param_type": "PluralParam" }
  ],
  "description": "Shopping cart item count displayed in the header"
}

MessageCatalog

A collection of translated messages for a single locale. Stored as a companion file alongside the IR, not embedded in the main binary.

Message

ICU MessageFormat supports plurals, select, and nested expressions:

• Simple: "Hello {name}"
• Plural: "{count, plural, one {# item} other {# items}}"
• Select: "{gender, select, female {She} male {He} other {They}} commented"

{
  "locale": "fr-FR",
  "messages": [
    { "key": "hero.title", "value": "Bienvenue sur Voce" },
    { "key": "hero.subtitle", "value": "Representation intermediaire pour l'IA" },
    { "key": "cart.item_count", "value": "{count, plural, one {# article} other {# articles}} dans votre panier" }
  ],
  "fallback_locale": "en"
}

FormatOptions

Locale-aware formatting configuration for number, date, and currency parameters.

{
  "number_style": "Currency",
  "currency_code": "EUR",
  "min_fraction_digits": 2,
  "max_fraction_digits": 2
}

I18nConfig

Application-level internationalization configuration. Added to VoceDocument.i18n.

Compilation modes:

• static – one output per locale. All LocalizedStrings resolved at compile time. Zero runtime cost. Best for SEO and performance.
• runtime – single output with locale switching. Translations loaded on demand. Adds ~1KB of i18n runtime. Best for SPAs with in-app language switching.

{
  "default_locale": "en-US",
  "supported_locales": ["en-US", "fr-FR", "de-DE", "ja-JP"],
  "mode": "static"
}

Pipeline Overview

Voce IR follows a SPIR-V-inspired pipeline: a binary intermediate representation flows through validation and compilation stages before reaching the end user. No human-readable source code exists in the pipeline. The AI generates IR directly, the validator enforces correctness, and the compiler emits optimized output for each target platform.

Pipeline Stages

Natural Language
       |
       v
 +-----------+
 | AI Bridge |   LLM generates JSON IR from conversation
 +-----------+
       |
       v
 +-----------+
 | JSON IR   |   Machine-readable text (.voce.json)
 +-----------+
       |
       v
 +-----------+
 | Validator |   9 passes, 46 rules — errors block compilation
 +-----------+
       |
       v
 +-----------+
 | Compiler  |   7 targets — DOM, WebGPU, WASM, Hybrid, iOS, Android, Email
 +-----------+
       |
       v
 +-----------+
 | Deployer  |   4 adapters — Static, Cloudflare, Netlify, Vercel
 +-----------+
       |
       v
   End User

Stage 1: AI Bridge

The AI bridge (packages/ai-bridge/) is a TypeScript layer that sits between the LLM and the rest of the pipeline. It manages the conversation, applies style packs, and produces valid JSON IR. The bridge uses structured output to ensure the LLM emits well-formed IR conforming to the FlatBuffers schema.

Key responsibilities:

• Conversation management (anti-vibe-coding: the AI asks questions, pushes back)
• Style pack selection and token injection
• Schema-aware JSON generation
• Intent-IR pair matching via RAG

Stage 2: JSON IR

The JSON representation is the canonical text form of the binary IR. It is not source code – it is a machine-readable serialization used for AI generation, debugging, and version control diffing. Files use the .voce.json extension. The voce json2bin command converts JSON to the binary FlatBuffers format (.voce), and voce bin2json reverses the process.

Stage 3: Validator

The validator (packages/validator/) runs 9 ordered passes over the IR, checking 46 rules across structural integrity, reference resolution, state machines, accessibility, security, SEO, forms, internationalization, and motion safety. Validation errors block compilation entirely – there is no “build with warnings” mode for critical rules.

Passes execute in dependency order:

1. Structural (STR) – document shape, required fields, node nesting
2. References (REF) – all ID references resolve to existing nodes
3. State Machine (STA) – valid transitions, initial states, no orphans
4. Accessibility (A11Y) – keyboard equivalents, heading hierarchy, alt text
5. Security (SEC) – CSRF on mutations, auth redirects, HTTPS enforcement
6. SEO – title, description, h1 count, Open Graph completeness
7. Forms (FRM) – field labels, unique names, validation rules
8. Internationalization (I18N) – localized key presence, default values
9. Motion (MOT) – ReducedMotion required, physics constraints, duration limits

Stage 4: Compiler

Seven compile targets live in separate crates under packages/. Each compiler reads validated IR and emits platform-specific output with zero runtime dependencies:

Stage 5: Deploy

Four deploy adapters handle the last mile, packaging compiler output for specific hosting environments:

Design Principles

• No human-readable code in the pipeline. The IR is the source of truth, not a stepping stone to hand-editable files.
• Accessibility is a compile error. Missing semantic information blocks the build, not just produces a warning.
• Zero runtime dependencies. Compiled output has no npm packages, no CDN links, no framework bundles. This eliminates the supply chain attack surface.
• Binary IR is not human-readable by design. JSON exists for AI generation and debugging, not for human authorship.

IR Format

Voce IR uses FlatBuffers as its binary wire format. FlatBuffers provide zero-copy deserialization, schema evolution, and compact binary encoding – properties borrowed from GPU shader pipelines (SPIR-V) rather than traditional web frameworks.

File Extensions

The two formats are interchangeable. The CLI provides round-trip conversion:

voce json2bin input.voce.json -o output.voce
voce bin2json input.voce -o output.voce.json

Internally, both commands delegate to flatc (the FlatBuffers compiler) with the Voce schema. The JSON form is what AI models emit; the binary form is what the validator and compilers consume.

Schema Organization

FlatBuffers schemas live in packages/schema/schemas/. Each .fbs file covers one domain:

The master file voce.fbs includes all domain files and defines the document root. This is the single compilation target for flatc.

The ChildUnion Wrapper Pattern

FlatBuffers unions allow heterogeneous node types in a single tree. However, the Rust codegen does not support vectors of unions directly. Voce solves this with a wrapper table:

union ChildUnion {
  Container,
  Surface,
  TextNode,
  MediaNode,
  StateMachine,
  // ... 27 total node types
  FormNode
}

table ChildNode {
  value: ChildUnion;
}

Parent nodes store children as [ChildNode] – a vector of wrapper tables, each containing one union variant. This pattern adds one level of indirection but preserves type safety and allows the full 27-type union to appear anywhere in the tree.

VoceDocument Root

Every IR file has a VoceDocument at its root:

table VoceDocument {
  schema_version_major: int32 = 0;
  schema_version_minor: int32 = 1;
  root: ViewRoot (required);
  routes: RouteMap;
  theme: ThemeNode;
  alternate_themes: [ThemeNode];
  auth: AuthContextNode;
  i18n: I18nConfig;
}

The root field is the visual tree entry point (always a ViewRoot). Top-level configuration – routing, theming, authentication, and internationalization – lives alongside the root rather than nested inside it.

The binary file uses the FlatBuffers file identifier "VOCE" (4 bytes at offset 4), enabling quick format detection without parsing.

Schema Versioning

The schema_version_major and schema_version_minor fields follow semver conventions:

• Minor bump: New optional fields, new union members. Old validators and compilers can still read the IR (FlatBuffers forward-compatibility).
• Major bump: Removed fields, changed semantics, breaking structural changes. Requires matching validator/compiler versions.

FlatBuffers’ wire format naturally supports forward compatibility – unknown fields are silently ignored by older readers. This means minor version bumps require no coordination between the AI bridge and the compiler.

JSON Canonical Form

The JSON representation mirrors the FlatBuffers schema exactly. Field names match the schema, enums use string names, and nested tables become nested objects. This is not a separate format – it is the standard FlatBuffers JSON encoding produced by flatc --json.

A minimal valid document in JSON:

{
  "schema_version_major": 0,
  "schema_version_minor": 1,
  "root": {
    "id": "root",
    "children": []
  }
}

The JSON form exists for three reasons: AI generation (LLMs produce text, not binary), debugging (humans can inspect the IR during development), and version control (text diffs are meaningful, binary diffs are not). It is never the primary runtime format.

Compiler Architecture

Voce IR supports seven compile targets. Each compiler lives in its own Rust crate under packages/, reads validated IR, and emits platform-specific output with zero runtime dependencies. The compiler selection happens at build time – the same IR can be compiled to any supported target without modification.

Compiler Crates

DOM Compiler

The DOM compiler (packages/compiler-dom/) is the primary compile target and the most mature. It emits a single self-contained HTML file with inlined CSS and JavaScript. No framework, no bundler, no CDN dependencies.

Internal pipeline stages:

1. Lower – Transform IR nodes into a compiler-internal representation (compiler_ir.rs) optimized for code generation
2. Animation – Process motion nodes into CSS keyframes and JS animation code
3. Assets – Resolve and inline media references
4. Emit – Generate the final HTML string with embedded styles and scripts

The output follows patterns from SolidJS and Svelte compiled output: surgical DOM mutations rather than virtual DOM diffing. State changes produce direct element.textContent = value assignments, not tree reconciliation.

WebGPU Compiler

The WebGPU compiler targets GPU-accelerated rendering using the WebGPU API. It produces WGSL (WebGPU Shading Language) shader programs alongside a JavaScript harness that manages the render pipeline.

Key capabilities:

• PBR (Physically Based Rendering) material support
• Scene3D, MeshNode, and ShaderNode compilation
• Particle system emission as compute shaders
• Automatic fallback annotations for non-WebGPU browsers

WASM Compiler

The WASM compiler translates StateMachine and ComputeNode logic into WebAssembly Text Format (WAT), which can then be assembled into .wasm binaries. This target is used when state logic needs to run at near-native speed in the browser.

The compiler maps Voce state machines to WASM function tables: each state becomes a function, transitions become conditional branches, and data bindings become memory load/store operations.

Hybrid Compiler

The hybrid compiler performs per-component target analysis. Rather than compiling the entire document to one target, it examines each subtree and selects the optimal compiler:

• Static content with no interactivity routes to DOM (minimal output)
• Heavy animation or 3D content routes to WebGPU
• Complex state logic routes to WASM
• The final output stitches the pieces together with a thin coordination layer

This allows a single page to mix GPU-rendered hero sections with lightweight DOM content sections, optimizing both performance and payload size.

iOS Compiler

The iOS compiler emits SwiftUI view code. IR layout nodes map to SwiftUI’s VStack, HStack, ZStack, and LazyVGrid. Theming tokens become SwiftUI Color and Font definitions. Navigation maps to NavigationStack and NavigationLink.

Accessibility semantics translate directly – Voce’s SemanticNode maps to SwiftUI’s .accessibilityLabel, .accessibilityHint, and role modifiers.

Android Compiler

The Android compiler targets Jetpack Compose, emitting Kotlin composable functions. IR containers become Column, Row, and Box composables. Theming maps to Material 3 MaterialTheme with custom color schemes generated from the IR’s ThemeNode.

State machines compile to Compose State holders with LaunchedEffect for side effects, matching the IR’s reactive model.

Email Compiler

The email compiler produces HTML that renders correctly across email clients – a notoriously constrained environment. It uses table-based layouts (not flexbox or grid), inline styles (not CSS classes), and conservative markup that passes Litmus and Email on Acid testing.

Key constraints the compiler handles:

• All layout via nested <table> elements
• All styles inlined on each element
• No JavaScript (email clients strip it)
• Image references as absolute URLs (no inlining)
• MSO conditional comments for Outlook compatibility

Shared Architecture

All seven compilers share common patterns:

• Input: Validated VoceIr (the serde model, not raw FlatBuffers)
• Output: A string or file bundle representing the compiled artifact
• No runtime dependencies: Every compiler produces self-contained output
• Snapshot testing: Compiler output is tested with insta snapshots to catch regressions
• Accessibility preservation: Semantic information from the IR must appear in the compiled output – compilers cannot silently drop it

The compiler selection is exposed through the CLI:

voce compile input.voce.json --target dom -o output.html
voce compile input.voce.json --target ios -o OutputView.swift
voce compile input.voce.json --target email -o newsletter.html

Validation Passes

The Voce validator runs 9 ordered passes over the IR, enforcing 46 rules that span structural correctness, accessibility, security, and more. Validation errors block compilation – there is no way to skip or suppress critical failures. This is by design: accessibility and security are compile errors, not warnings.

The ValidationPass Trait

Every pass implements the ValidationPass trait defined in packages/validator/src/passes/mod.rs:

#![allow(unused)]
fn main() {
pub trait ValidationPass {
    fn name(&self) -> &'static str;
    fn run(&self, ir: &VoceIr, index: &NodeIndex, result: &mut ValidationResult);
}
}

The VoceIr is a serde-based IR model, separate from the FlatBuffers generated types. This decoupling is intentional – the validator works with JSON- deserialized data, not raw FlatBuffers buffers. The NodeIndex provides pre-built lookup tables (ID-to-node maps, parent chains) so passes can resolve references without redundant traversals.

Passes execute in dependency order. Structural checks run first because later passes assume the document shape is valid. Reference resolution runs second because domain passes may follow reference chains.

Error Code Taxonomy

Each rule has a unique error code with a prefix identifying its pass:

STR – Structural (5 rules)

REF – References (9 rules)

STA – State Machine (4 rules)

A11Y – Accessibility (5 rules)

SEC – Security (4 rules)

SEO (7 rules)

FRM – Forms (4 rules)

I18N – Internationalization (3 rules)

MOT – Motion (5 rules)

Output Formats

The validator reports diagnostics in two formats, controlled by CLI flags:

• Colored terminal output (default) – human-readable with error codes, node paths, and descriptions
• JSON output (--format json) – machine-readable array of diagnostics for integration with CI pipelines and editor tooling

voce validate my-page.voce.json              # colored terminal output
voce validate my-page.voce.json --format json # JSON diagnostics

Serde IR Model

The validator does not read FlatBuffers binary directly. Instead, it deserializes JSON into a parallel serde-based IR model defined in packages/validator/src/ir.rs. This model mirrors the FlatBuffers schema but uses standard Rust types (String, Vec, Option) rather than FlatBuffers accessors. The separation keeps validation logic clean and testable without requiring binary serialization in test fixtures.

Style Packs

Style packs are design presets for AI-generated output – think of them as LoRA adapters for UI. Instead of describing colors, fonts, and spacing from scratch in every conversation, you select a style pack and the AI bridge applies its design tokens to the generated IR.

What a Style Pack Contains

Each pack defines a complete visual identity:

• Color palette – background, foreground, primary, surface, muted, and optional accent colors (as RGB values)
• Typography – heading and body font families, sizes, weights, and line height
• Spacing – base unit and a scale array for consistent rhythm
• Border radii – small, medium, and large values for component rounding
• Component patterns – example IR files showing how the pack’s tokens apply to common UI patterns (hero sections, pricing cards, forms)

The type definitions live in packages/ai-bridge/src/packs/types.ts:

export interface StylePack {
  id: string;
  name: string;
  description: string;
  tags: string[];
  tokens: DesignTokens;
  examples: PackExample[];
}

Built-in Packs

Voce ships with three built-in style packs:

minimal-saas

A clean, utilitarian design for SaaS dashboards and landing pages. High contrast, generous whitespace, and a neutral palette with a single accent color. Typography uses a system font stack for fast loading.

Tags: saas, landing, clean, dashboard

editorial

A content-first design for blogs, documentation, and long-form reading. Serif headings, generous line height, narrow content column, and muted colors that keep attention on the text.

Tags: blog, editorial, content, documentation

ecommerce

A conversion-oriented design for product pages and storefronts. Bold primary colors, tight spacing for product grids, prominent call-to-action buttons, and image-heavy layouts.

Tags: ecommerce, product, store, conversion

How the AI Bridge Uses Packs

When a user starts a conversation, the AI bridge can select a style pack based on the user’s description (or the user can request one explicitly). The bridge then:

1. Loads the pack’s design tokens
2. Injects token values into the IR’s ThemeNode during generation
3. Uses the pack’s example IR files for RAG (retrieval-augmented generation) matching – if the user asks for a “pricing section,” the bridge retrieves the pack’s pricing example as context for the LLM

The pack’s tags field enables automatic matching. When a user says “build me a SaaS landing page,” the bridge scores packs by tag overlap and selects the best fit.

Pack Examples and RAG

Each pack includes PackExample entries:

export interface PackExample {
  filename: string;
  description: string;
  tags: string[];
  irJson?: string;
}

The description and tags fields are indexed for similarity search. When the AI bridge receives a user intent, it retrieves the most relevant examples from the active pack and includes them as few-shot context for the LLM. This grounds generation in concrete, validated IR rather than relying solely on schema knowledge.

Creating a Custom Pack

To add a new style pack:

1. Create a new directory under packages/ai-bridge/src/packs/ with your pack ID as the name
2. Define a StylePack object with your design tokens
3. Add example IR files that demonstrate your pack’s visual language
4. Register the pack in the loader (packages/ai-bridge/src/packs/loader.ts)

The pack’s tokens must use RGB values (0-255 per channel). The spacing scale is an array of multipliers applied to the base unit – for example, a base of 8 with scale [0.5, 1, 2, 3, 4, 6, 8] produces 4, 8, 16, 24, 32, 48, 64 pixel values.

Packs vs. Themes

Style packs and IR themes (ThemeNode) serve different roles:

• Style packs are an AI bridge concept. They guide generation by providing design tokens and examples. They exist at authoring time.
• Themes are an IR concept. They are embedded in the generated document and survive compilation. They exist at runtime.

The AI bridge translates pack tokens into theme nodes during generation. A single pack can produce multiple theme variants (light/dark) stored as alternate_themes in the VoceDocument.

Contributing

This guide covers development setup, code conventions, the working pattern for new features, and the process for adding a new compile target.

Development Setup

Prerequisites

• Rust 1.85+ (edition 2024 support required)
• FlatBuffers compiler (flatc) for schema regeneration
• Node.js 18+ and npm (for the TypeScript AI bridge)

Clone and Build

git clone https://github.com/fireburnsup/voce-ir.git
cd voce-ir

# Build the entire workspace
cargo build --workspace

# Run all tests
cargo test --workspace

# Lint (must pass with zero warnings)
cargo clippy --workspace -- -D warnings

# Format check
cargo fmt --check

If all four commands pass, your environment is ready.

Regenerating FlatBuffers Bindings

After editing any .fbs file in packages/schema/schemas/:

# Rust bindings
flatc --rust -o packages/schema/src/generated/ packages/schema/schemas/voce.fbs

# TypeScript bindings (for AI bridge)
flatc --ts -o packages/ai-bridge/src/generated/ packages/schema/schemas/voce.fbs

Code Conventions

Rust

• Edition 2024 (latest stable). Fall back to edition 2021 per-crate only if a dependency requires it (e.g., FlatBuffers codegen).
• Error handling: thiserror for library error types, anyhow for CLI entry points. No unwrap() in library code – propagate errors with ?.
• CLI arguments: clap derive API.
• Naming: snake_case for files and functions, PascalCase for types and enums.
• Documentation: Every public function and type has a /// doc comment.
• Formatting: cargo fmt with default settings. Run before every commit.
• Linting: cargo clippy -- -D warnings enforces a zero-warnings policy. CI will reject PRs with clippy warnings.

Testing

• Unit tests live in-file under #[cfg(test)] modules.
• Integration tests live in tests/.
• Every new node type needs valid and invalid test IR in tests/schema/.
• Compiler output uses insta snapshot testing to catch regressions.

Working Pattern

When implementing a new feature, follow this sequence:

1. Schema – If new IR types are needed, add or modify .fbs files in packages/schema/schemas/. Update the ChildUnion in voce.fbs if adding a new node type.

2. Bindings – Regenerate Rust and TypeScript bindings with flatc.

3. Validation – Add a validation pass (or extend an existing one) in packages/validator/src/passes/. Implement the ValidationPass trait and register the pass in all_passes().

4. Compiler – Add codegen support in the relevant compiler crate(s). At minimum, the DOM compiler (packages/compiler-dom/) should handle the new node type.

5. Tests – Write tests for each layer: schema validity, validator acceptance/rejection, and compiler snapshot output.

6. Verify – Run the full suite before submitting:

   cargo test --workspace && cargo clippy --workspace -- -D warnings
   

7. Commit – Use conventional commit messages:

   feat(validator): add FRM005 rule for phone field validation
   fix(compiler-dom): correct heading level output for nested sections
   

Adding a New Compile Target

To add a new compiler (e.g., Flutter, React Native):

1. Create a new crate: cargo new --lib packages/compiler-flutter

2. Add it to the workspace Cargo.toml members list.

3. Depend on the schema crate for IR types and the validator’s serde IR model for input deserialization.

4. Implement a compile function that accepts validated VoceIr and returns the target output (string, file bundle, or byte stream).

5. Follow the shared compiler patterns:

   • Zero runtime dependencies in output
   • Accessibility semantics must be preserved (never silently drop them)
   • Use insta for snapshot testing

6. Register the new target in the CLI’s --target enum (packages/cli/ or the relevant binary crate).

7. Add integration tests that compile the reference landing page IR and verify the output.

Pull Request Process

1. Fork the repository and create a feature branch.
2. Follow the working pattern above.
3. Ensure cargo test --workspace and cargo clippy --workspace -- -D warnings both pass.
4. Write a clear PR description explaining what changed and why.
5. Link any related issues.

PRs that introduce new validation rules should include both positive tests (valid IR that passes) and negative tests (invalid IR that triggers the expected error code).

Project Structure Reference

Key directories: packages/schema/ (FlatBuffers schema + bindings), packages/validator/ (9-pass validator), packages/compiler-*/ (7 compile targets), packages/ai-bridge/ (TypeScript AI layer), packages/adapter-*/ (4 deploy adapters), tests/ (integration tests), examples/ (reference IR).