How Forge Was Born: The Deterministic AI Compiler That Changes How Websites Are Built

Every AI website builder works the same way: you type a prompt, an LLM writes HTML, and you get whatever it gives you. Sometimes it is good. Sometimes it is not. You hit "generate" again and you get something completely different — different layout, different colours, different quality. The output is, fundamentally, unpredictable.

We shipped that model. It worked. People made real websites with it. But as we watched thousands of sites get generated, a pattern emerged: the LLM was spending most of its tokens reinventing things it should not have been deciding. Navigation systems. Colour contrast. Mobile breakpoints. Anchor links. Font loading. Contact form markup.

Every generation was a fresh roll of the dice on problems that have correct answers.

Forge is our response to that observation. It is not an incremental improvement — it is a fundamentally different architecture for how AI builds websites.

The Problem With Letting AI Write Raw HTML

When you ask an LLM to "create a website for a barbershop," it has to make thousands of decisions simultaneously: What sections to include. What order to put them in. What the navigation looks like. What colours to use. How to handle mobile layouts. How to load fonts. How to wire up anchor links. How to structure the HTML semantically. How to handle contrast ratios. How to format opening hours. How to render a phone number as a clickable link.

Some of those decisions are creative: what sections to include, what colour palette suits a barbershop, what the overall feel should be.

Most of them are engineering: the navigation must scroll to real anchors, the contrast ratio must be at least 4.5:1, the phone number must be in E.164 format, the font must be loaded from Google Fonts with preconnect, the mobile layout must stack vertically below 480px.

When you let the LLM handle both, the creative decisions are good but the engineering decisions are inconsistent. Some generations have perfect contrast. Others do not. Some have working anchor links. Others have dead hrefs pointing to sections that do not exist. Some load fonts correctly. Others inline a font-face that never resolves.

The insight behind Forge: separate the creative decisions from the engineering decisions. Let AI handle creativity. Let a compiler handle correctness.

The Two-Phase Architecture

Forge splits website generation into two distinct phases:

Phase 1: The AI Decides What to Build (SiteSpec)

Instead of writing raw HTML, the AI produces a structured specification — a JSON document we call a SiteSpec. The SiteSpec describes what sections the site should have, what content goes in each section, what the colour palette and typography should be, what the navigation looks like, and what the overall design treatment is.

The AI makes all the creative decisions: is this a dark, luxurious aesthetic or a bright, editorial feel? Should the hero use a condensed headline font like Bebas Neue or an elegant serif like Cormorant Garamond? Should the sections include a gallery, a stat band, an FAQ, or a team grid?

But the AI does NOT decide how to render any of it. It does not write a single line of HTML or CSS. It describes intent.

Phase 2: The Compiler Renders It Perfectly (Every Time)

The SiteSpec feeds into a deterministic compiler — a pure function that takes a specification and a playbook and outputs self-contained, production-grade HTML. The same input always produces the same output.

The compiler owns every engineering decision:

• Navigation anchors — every nav link points to a real section. Dead anchors are impossible; the compiler reconciles every #href against the actual section IDs.
• Contrast safety — text-on-background contrast is checked and enforced to WCAG AA (4.5:1). The AI chooses the palette; the compiler ensures readability.
• Surface alternation — no two adjacent sections share the same background shade. The compiler auto-alternates base and secondary surfaces to create visual rhythm.
• Contact normalisation — phone numbers are formatted to E.164 for tel: links, WhatsApp channels are auto-detected, opening hours and addresses are tidied up. Every contact fact works as a real, clickable link.
• Font loading — Google Fonts are loaded with preconnect and display-swap. No broken font-faces, no layout shift.
• Responsive layout — every block renders correctly at mobile, tablet, and desktop breakpoints. The AI does not choose breakpoints; the compiler enforces them.
• Footer and nav synthesis — if the AI omits a footer or navigation (which saves tokens), the compiler derives them from the sections that exist. Nothing is ever missing from the final output.

Why This Matters: Speed and Determinism

Speed

Because the AI is producing structured data instead of raw HTML, the output is dramatically smaller. A full-page HTML generation requires 15,000–25,000 tokens of LLM output. A SiteSpec for the same site requires 4,000–6,000 tokens — a 3–4× reduction. That translates directly to faster generation (under 90 seconds for a full site) and lower cost.

Determinism

The compiler is a pure function. Given the same SiteSpec, it always produces the same HTML. This means:

• Editing is safe. When you change a section heading in the visual editor, only that section changes. The compiler re-renders the spec and the rest of the site is identical. No cascading side effects.
• Quality is guaranteed. Contrast, anchors, contact formatting, font loading — all of it is correct on every single generation, not just some of the time.
• Testing is possible. A deterministic engine can be evaluated systematically. We run automated checks on colour contrast, anchor integrity, block variety, and design variance across generations.

Bounded Creativity

Here is the counterintuitive insight: constraints make the AI more creative, not less. When the LLM is freed from writing boilerplate HTML and CSS, it spends its entire token budget on the decisions that actually matter — section selection, content strategy, design treatment, colour theory. The creative output is better precisely because the engineering output is handled.

The Playbook System

The compiler does not hardcode how any block renders. Instead, it takes a Playbook — a module that defines the block library (how each section type renders to HTML/CSS), the design resolution system (how palettes and typography are resolved), and the base stylesheet.

Swap the playbook and the same SiteSpec renders in a completely different visual language. The engine stays the same. The blocks change. This is what makes Forge extensible: new section types, new design treatments, new rendering strategies — all without touching the compiler core.

Today, the site-generator playbook includes over 26 distinct block types — from hero sections and service lists to stat bands, galleries, FAQs, team grids, marquees, booking CTAs, and more. The AI chooses from this library based on the business type and content, and the compiler renders them with pixel-perfect precision.

How Forge Came Into Being

Forge did not start as a grand plan. It started with a prototype — a single compile.mjs file that took a hand-written JSON spec and rendered it to HTML. The question was simple: if we defined the blocks ourselves and had the AI fill in the content, would the result be better than raw LLM HTML?

It was. Dramatically better. The prototype rendered a barbershop site with perfect contrast, working navigation, proper font loading, and a coherent dark/gold aesthetic — all from a JSON spec that was a fraction of the size of the equivalent HTML.

From there, the architecture took shape:

1. The prototype became a typed, framework-free engine — importable by any JavaScript runtime with no dependencies on React, Next.js, or SiteDrop internals.
2. The hardcoded block renderers became a pluggable Playbook system — each playbook defines its own blocks, design tokens, and CSS.
3. The LLM integration moved from raw HTML output to structured tool-use (the SiteSpec schema IS the tool schema — it teaches the model what to produce while constraining the output shape).
4. A self-documenting schema replaced the traditional system prompt — the schema descriptions teach the AI what each field means, so the "grammar" is just a few lines.
5. Quality gates — contrast checking, anchor reconciliation, surface alternation, contact normalisation — were built into the compiler so they run on every generation, not as optional post-processing.

The result is an engine that is provider-agnostic (it works with Claude, GPT, Gemini, DeepSeek, xAI — any model that supports structured output), framework-free (extractable as a standalone package), and deterministic (same spec → same HTML, always).

What This Means for You

If you are a SiteDrop user, Forge is already running when you generate a site. You do not need to do anything differently — the improvement is in the quality, speed, and consistency of the output:

• Faster generation — sites generate in under 90 seconds because the AI output is 3–4× smaller.
• Consistent quality — every generation has correct contrast, working navigation, proper font loading, and formatted contact details.
• Better design variety — the AI chooses from 26+ block types, 4+ design archetypes, and a wide palette of typography pairings. A barbershop gets a dark, condensed aesthetic; a dental practice gets a clean, editorial feel; a fine-dining restaurant gets a luxe serif treatment.
• Safer editing — the visual editor modifies the SiteSpec and re-renders through the compiler, so changes are predictable and side-effect-free.

Where Forge Goes Next

The compiler architecture is the foundation for everything we are building. Because the engine is spec-driven, every new capability is a new block type, a new playbook, or a new design token — not a rewrite of the generation pipeline. That is the power of the separation: the AI gets better at deciding, the compiler gets better at rendering, and both improve independently.

We believe this two-phase pattern — AI for intent, compiler for execution — is how web applications will be built going forward. Not just single-page websites, but multi-page applications, dashboards, and interactive experiences. The AI describes what should exist. The compiler guarantees it works.