UI Generator

The UI Generator is the core engine that transforms natural language prompts into compiled React components.

Architecture

The generation pipeline is built around the harness — a configured execution plan derived per-contract from the data contract’s risk and axes. A harness bundles three things: a workflow (the topology of LLM phases and tasks), a system prompt + boilerplate (the “how” of authoring), and a check leg (the post-conditions the output must satisfy). Generation runs the workflow to produce source, runs the check leg, and — if the check fails — derives a revised harness and re-runs, up to a bounded number of iterations.

The default workflow is single_pass (one LLM impl loop). Higher-risk contracts can opt into staged (plan → execute) or staged_concurrent (plan → parallel skeleton tasks → integrate). All workflows share the same check + derive loop:

1. Workflow — Run the configured phases × tasks. Each task receives pre-injected context (primitives docs, design tokens, the data contract) and emits source via apply_changes
2. Check — Run the harness’s check leg: TypeScript type-checking against @ggui-ai/design, render smoke test, and per-axis assertions
3. Derive — If checks fail, derive a revised harness (e.g., upgrade workflow, swap fragments, adjust prompt) and re-run
4. Stop — Return the first iteration that passes the check threshold, or surface the failure after maxIterations

Enforced Tool Call Pattern

The coding phase uses an enforced pattern where the system auto-runs quality checks:

• The LLM receives all context pre-injected (primitives docs, design system tokens, data contract with examples)
• The LLM writes component code as text — no tool calls needed
• The system automatically runs self_check and compile_component on the output
• If errors are found, they’re fed back for the LLM to fix

This eliminates wasted turns on deterministic tool calls and prevents “no tool calls” failures.

Multi-Provider Support

The generator supports multiple LLM providers through adapter implementations:

• Claude (Anthropic) — Raw API and Claude Agent SDK
• OpenAI — Raw Responses API and OpenAI Agents SDK
• Google (Gemini) — Raw GenAI API and Google ADK

Each provider plugs into the same harness pipeline — only the LLM transport layer differs. Workflow, check, and derive logic are provider-agnostic.

TypeScript Type-Checking

Generated components are type-checked against the actual @ggui-ai/design type definitions using the TypeScript compiler API with a virtual filesystem. This catches:

• Wrong prop types on primitives
• Missing required props
• Invalid imports
• Null/undefined access (strictNullChecks)

Render Smoke Test

After compilation, a render smoke test runs ReactDOMServer.renderToString() with contract-derived sample props to catch runtime errors (like undefined.toLowerCase()) before the component reaches the user.

Data Contracts

Each generation includes a data contract (PropsSpec, ActionSpec, StreamSpec) that defines:

• What props the component accepts (with examples)
• What user actions it emits (with example payloads)
• What real-time data it receives (with example events)

The contract is validated at compile time and at the MCP handler boundary.