Voce IR

The code is gone. The experience remains.

Voce IR is an open-source, AI-native intermediate representation for user interfaces. Instead of AI writing framework code that humans then maintain, Voce IR is a binary, typed, machine-optimized format that AI generates directly and a compiler consumes -- like SPIR-V for UI instead of shaders.

Named from sotto voce -- quiet input, extraordinary output.

Why Voce IR?

Every AI coding tool today (v0, bolt.new, Cursor, Copilot) uses AI to write code faster in systems designed for humans. Voce IR asks a different question:

If AI is the only author and the end-user experience is the only output that matters, what does the optimal system look like?

The answer: remove the human-readable layer entirely.

Natural Language -> [AI Bridge] -> Binary IR -> [Validator] -> [Compiler] -> Output

No React. No CSS cascade. No dependency tree. Just a typed IR that compiles to optimized output across 7 targets.

Comparison

Features

7 Compile Targets

9 Validation Passes (46 Rules)

Every IR document is validated before compilation:

27 Node Types

Layout, state machines, animations, gestures, navigation, routing, accessibility semantics, theming, data binding, forms, SEO metadata, internationalization -- all as first-class IR primitives defined across 12 FlatBuffers schema files.

Anti-Vibe-Coding

This is not "generate fast and iterate." The AI bridge implements a conversational design system:

• Asks one question at a time to build context
• Maintains a readiness score (0-100) before generating
• Pushes back on anti-patterns
• Enforces the project brief across sessions
• No TODOs, no half-implementations, no placeholders

Production Pipeline

voce validate page.voce.json    # 9 validation passes
voce compile page.voce.json     # Compile to HTML (7.6KB output)
voce deploy page.voce.json      # Deploy to Vercel/Cloudflare/Netlify

Quick Start

Prerequisites

• Rust 1.85 or later

Install

cargo install voce-validator

Or build from source:

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

Your First IR File

Create hello.voce.json:

{
  "schema_version_major": 1,
  "schema_version_minor": 0,
  "root": {
    "node_id": "root",
    "viewport_width": { "value": 1024, "unit": "Px" },
    "metadata": {
      "title": "Hello World",
      "description": "My first Voce IR page."
    },
    "children": [
      {
        "value_type": "TextNode",
        "value": {
          "node_id": "greeting",
          "content": "Hello, World!",
          "heading_level": 1,
          "font_size": { "value": 48, "unit": "Px" },
          "font_weight": "Bold"
        }
      }
    ]
  }
}

Validate, Compile, Preview

# Validate against all 46 quality rules
voce validate hello.voce.json

# Compile to a single HTML file (output: dist/hello.html)
voce compile hello.voce.json

# Open in browser
voce preview hello.voce.json

# Deploy
voce deploy hello.voce.json --adapter static
voce deploy hello.voce.json --adapter cloudflare --dry-run

CLI Reference

voce validate <file>     Validate IR (9 passes, 46 rules)
voce compile <file>      Compile to HTML [--minify] [--skip-fonts] [--no-cache] [--debug]
voce deploy <file>       Deploy [--adapter static|vercel|cloudflare|netlify] [--dry-run]
voce inspect <file>      IR summary (node counts, types, features)
voce preview <file>      Compile and open in browser
voce report <file>       Quality report (a11y, security, performance)
voce manifest <file>     Application manifest
voce json2bin <file>     JSON to FlatBuffers binary
voce bin2json <file>     FlatBuffers binary to JSON

Global flags: --verbose, --json-errors

Architecture

                        ┌─────────────────────────┐
                        │      FlatBuffers IR      │
                        │   (12 .fbs, 27 types)    │
                        └────────────┬────────────┘
                                     │
┌──────────────┐     ┌──────────┐    │    ┌───────────┐     ┌──────────┐
│  Natural     │     │  JSON    │    │    │           │     │ DOM      │
│  Language    │────>│  IR      │────┼───>│ Validator │────>│ WebGPU   │
│  (AI Bridge) │     │ (.voce)  │    │    │ (9 passes)│     │ WASM     │
└──────────────┘     └──────────┘    │    └───────────┘     │ iOS      │
                                     │                      │ Android  │
                                     │                      │ Email    │
                                     │                      │ Hybrid   │
                                     │                      └─────┬────┘
                                     │                            │
                                     │     ┌──────────────────────┘
                                     │     │
                                     │  ┌──┴───────┐
                                     │  │ Deploy   │
                                     │  │ Adapters │
                                     │  └──────────┘
                                     │  Vercel, Cloudflare,
                                     │  Netlify, Static
                                     │
                              ┌──────┴──────┐
                              │  Inspector  │
                              │  Playground │
                              └─────────────┘

The IR is defined as FlatBuffers tables. The JSON canonical format (.voce.json) is the primary development format; binary .voce files use FlatBuffers zero-copy deserialization for production.

See ARCHITECTURE.md for the full technical design.

Three Pillars

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

1. Stability -- Security is a compile error, not configuration. CSRF required on mutations, HTTPS enforced, auth routes need redirects. Zero runtime dependencies = zero supply chain risk.

2. Experience -- Zero framework overhead. Spring physics solved at compile time via ODE solver to CSS linear(). Every byte in the output serves the user.

3. Accessibility -- Missing SemanticNode is a validation error, not a warning. Keyboard equivalents required on every gesture handler. Heading hierarchy enforced. ReducedMotion mandatory on all animations.

Repository Structure

voce-ir/
├── packages/
│   ├── schema/              FlatBuffers IR schema (12 .fbs files, 27 node types)
│   ├── validator/           Validator + voce CLI binary (9 passes, 46 rules)
│   ├── compiler-dom/        DOM compiler (HTML/CSS/JS, image pipeline, font pipeline)
│   ├── compiler-webgpu/     WebGPU compiler (WGSL, PBR, particles)
│   ├── compiler-wasm/       WASM compiler (state machines -> WAT)
│   ├── compiler-hybrid/     Hybrid compiler (DOM + WebGPU + WASM)
│   ├── compiler-ios/        iOS compiler (SwiftUI)
│   ├── compiler-android/    Android compiler (Jetpack Compose)
│   ├── compiler-email/      Email compiler (table layouts, inline CSS)
│   ├── adapter-core/        Deployment adapter trait and types
│   ├── adapter-static/      Static file deployment
│   ├── adapter-vercel/      Vercel Build Output API v3
│   ├── adapter-cloudflare/  Cloudflare Pages + Workers
│   ├── adapter-netlify/     Netlify + Functions
│   ├── playground-wasm/     WASM bindings for browser playground
│   ├── playground/          Browser-based "try it" playground (Vite + TS)
│   ├── ai-bridge/           Multi-agent AI generation (TypeScript)
│   ├── mcp-server/          MCP server for Claude/AI tool integration
│   ├── sdk/                 Programmatic TypeScript SDK
│   └── inspector/           Visual debugging tools (TypeScript)
├── tests/
│   ├── schema/              Valid + invalid IR fixtures (12 invalid, 1 valid)
│   └── fixtures/            Per-node-type test IR files (12 fixtures)
├── examples/
│   ├── landing-page/        Reference 37-node landing page
│   ├── production/          Production voce-ir.xyz site (IR + compiled output)
│   └── intents/             Natural language -> IR training pairs
├── docs/
│   ├── site/                mdBook documentation site (30 pages)
│   ├── plans/               Sprint plans (S01-S60)
│   ├── research/            9 deep research documents
│   └── ARCHITECTURE.md      Technical architecture & key decisions
└── scripts/
    └── regenerate-schema.sh FlatBuffers codegen

15 Rust crates | 4 TypeScript packages | 172 tests | 30 documentation pages

Performance

Measured with criterion on Apple Silicon:

Production landing page output: 7.6KB (unminified), 7.3KB (minified).

Development

# Build everything
cargo build --workspace

# Run all tests (172 tests)
cargo test --workspace

# Lint (zero warnings policy)
cargo clippy --workspace -- -D warnings

# Format check
cargo fmt --check

# Benchmarks
cargo bench -p voce-compiler-dom --bench compile_bench

# Build WASM playground
cd packages/playground-wasm && wasm-pack build --target web

# Build documentation site
cd docs/site && mdbook build

Documentation

• Documentation Site -- Getting started, CLI reference, full schema reference, architecture guide
• ARCHITECTURE.md -- Technical architecture, crate dependency graph, key decisions
• Schema Reference -- Every node type with field tables and JSON examples
• Playground -- Try Voce IR in the browser (WASM-powered)

Build docs locally:

cd docs/site && mdbook serve

Contributing

Contributions are welcome! Whether it's a bug fix, new compile target, validation rule, or documentation improvement.

Please read CONTRIBUTING.md for development setup, code conventions, and the PR process.

Areas for Contribution

• New validation rules -- add passes in packages/validator/src/passes/
• Compiler improvements -- better HTML output, new CSS features
• New compile targets -- Flutter, React Native, etc.
• Schema extensions -- new node types for new UI patterns
• Test fixtures -- more IR examples covering edge cases
• Documentation -- tutorials, guides, API reference improvements
• Playground -- CodeMirror/Monaco editor integration, more examples

Roadmap

Voce IR is at v1.0.0 with all core functionality complete. The current focus (Phase 7) is production readiness:

• S51: Real image processing pipeline (WebP, JPEG, BlurHash)
• S52: Deployment adapters (Vercel, Cloudflare, Netlify, static)
• S53: Browser playground (WASM-powered)
• S54: Integration test suite (172 tests)
• S55: Documentation site (mdBook, 30 pages)
• S56: Font subsetting and optimization
• S57: Production error handling and structured errors
• S58: Production demo site (voce-ir.xyz)
• S59: Performance optimization and benchmarks
• S60: Community launch and v1.1.0

See MASTER_PLAN.md for the full 60-sprint breakdown.

License

Apache-2.0

Links

• Website: voce-ir.xyz
• Docs: voce-ir.xyz/docs
• Playground: voce-ir.xyz/playground
• Issues: github.com/marcpelland/voce-ir/issues

Created by Marc Pelland.