IR Format Specification

The IR (Intermediate Representation) is a stable, versioned JSON format that represents wireframes in normalized form after parsing and validation.

Quick Reference

The IR transforms raw DSL into an unambiguous, renderable format:

Input: Parsed .wire file (AST)
Processing: Apply theme defaults, validate components, normalize values
Output: Complete IR document ready for layout and rendering

Key Characteristics

Deterministic: Same input always produces same output
Versioned: Allows for schema migrations (currently v1.0)
Normalized: All defaults applied, all values validated
Cross-referenceable: Nodes stored in dictionary for easy lookup
AI-friendly: Regular, predictable structure

Basic Structure

{
  "irVersion": "1.0",
  "project": {
    "id": "proj_dashboard",
    "name": "Admin Dashboard",
    "theme": {
      "density": "normal",
      "spacing": 16,
      "radius": 4,
      "stroke": 2,
      "font": "base"
    },
    "screens": [
      {
        "id": "screen_dashboard",
        "name": "Dashboard",
        "viewport": { "width": 1280, "height": 720 },
        "root": { "ref": "node_root_1" }
      }
    ],
    "nodes": {
      "node_root_1": {
        "id": "node_root_1",
        "kind": "container",
        "type": "stack",
        "children": [ ... ]
      }
    }
  }
}

Schema Details

Project Object

Field	Type	Required	Description
`id`	string	Yes	Unique project identifier
`name`	string	Yes	Human-readable name
`theme`	object	No	Theme tokens (defaults applied if omitted)
`screens`	array	Yes	Screen definitions (at least 1)
`nodes`	object	Yes	All nodes referenced by screens

Theme Object

Field	Type	Values	Description
`density`	string	`compact`, `normal`, `comfortable`	UI compactness
`spacing`	number	4, 8, 16, 24, 32	Base spacing in pixels
`radius`	number	0, 2, 4, 8	Border radius in pixels
`stroke`	number	1, 2	Border width in pixels
`font`	string	`base`, `title`, `mono`	Typography family

Screen Object

Field	Type	Required	Description
`id`	string	Yes	Unique screen identifier
`name`	string	Yes	Human-readable name
`viewport`	object	Yes	Display dimensions `{width, height}`
`root`	ref	Yes	Reference to root layout node

Node Object (Container)

{
  "id": "node_stack_1",
  "kind": "container",
  "type": "stack",
  "properties": {
    "direction": "vertical",
    "gap": 16,
    "padding": 24,
    "align": "justify"
  },
  "children": [
    { "ref": "node_heading_1" },
    { "ref": "node_input_1" }
  ]
}

Field	Type	Description
`id`	string	Unique node ID
`kind`	string	`container` or `component`
`type`	string	Layout/component type
`properties`	object	Type-specific properties
`children`	array	Child node references (containers only)

Node Object (Component)

{
  "id": "node_button_1",
  "kind": "component",
  "type": "Button",
  "properties": {
    "text": "Submit",
    "variant": "primary"
  }
}

Field	Type	Description
`id`	string	Unique node ID
`kind`	string	Always `component`
`type`	string	Component name (e.g., `Button`, `Input`)
`properties`	object	Component-specific properties

Layout Type Properties

Stack

{
  "type": "stack",
  "properties": {
    "direction": "vertical" | "horizontal",
    "gap": 16,
    "padding": 24,
    "align": "justify" | "left" | "center" | "right"
  }
}

Grid

{
  "type": "grid",
  "properties": {
    "columns": 12,
    "gap": 16
  },
  "children": [
    {
      "ref": "cell_1",
      "span": 6,
      "align": "start" | "center" | "end"
    }
  ]
}

Split

{
  "type": "split",
  "properties": {
    "sidebarWidth": 260,
    "gap": 16
  },
  "children": [
    { "ref": "sidebar_node" },
    { "ref": "content_node" }
  ]
}

Panel

{
  "type": "panel",
  "properties": {
    "padding": 16,
    "background": "white"
  },
  "children": [{ "ref": "content_node" }]
}

Card

{
  "type": "card",
  "properties": {
    "padding": 16,
    "gap": 16,
    "radius": 4,
    "border": true
  },
  "children": [ ... ]
}

Component Properties

Components store properties specific to their type:

{
  "id": "node_input_1",
  "kind": "component",
  "type": "Input",
  "properties": {
    "label": "Email",
    "placeholder": "your@email.com"
  }
}

See Components Reference for all property options.

Example: Complete IR

{
  "irVersion": "1.0",
  "project": {
    "id": "proj_login",
    "name": "Login",
    "theme": {
      "density": "normal",
      "spacing": 16,
      "radius": 4,
      "stroke": 2,
      "font": "base"
    },
    "screens": [{
      "id": "screen_login",
      "name": "Login Screen",
      "viewport": { "width": 400, "height": 500 },
      "root": { "ref": "stack_root" }
    }],
    "nodes": {
      "stack_root": {
        "id": "stack_root",
        "kind": "container",
        "type": "stack",
        "properties": {
          "direction": "vertical",
          "gap": 16,
          "padding": 24
        },
        "children": [
          { "ref": "heading_title" },
          { "ref": "input_email" },
          { "ref": "input_password" },
          { "ref": "button_login" }
        ]
      },
      "heading_title": {
        "id": "heading_title",
        "kind": "component",
        "type": "Heading",
        "properties": { "text": "Sign In" }
      },
      "input_email": {
        "id": "input_email",
        "kind": "component",
        "type": "Input",
        "properties": {
          "label": "Email",
          "placeholder": "you@example.com"
        }
      },
      "input_password": {
        "id": "input_password",
        "kind": "component",
        "type": "Input",
        "properties": {
          "label": "Password",
          "placeholder": "••••••••"
        }
      },
      "button_login": {
        "id": "button_login",
        "kind": "component",
        "type": "Button",
        "properties": {
          "text": "Login",
          "variant": "primary"
        }
      }
    }
  }
}

Validation in IR

All IR documents are validated against a Zod schema:

Theme properties must exist and have valid values
Screen viewports must be positive integers
All node references must exist in the nodes dictionary
All component properties must be valid for that component type
Layout children references must exist

Invalid IR produces detailed validation errors.

Full Specification

For complete technical specification with all property definitions, see:

specs/IR-CONTRACT-EN.md in the repository