.gui vs HTML: a closed vocabulary vs an open runtime

HTML, in practice, is never just HTML — it’s HTML plus CSS plus JavaScript, an open runtime where arbitrary code can mutate the DOM at any time. Two loads of the same page can render differently depending on network timing, a feature flag, or a script that hasn’t finished executing yet. .gui has no scripting. It is a closed, fixed vocabulary — row, col, frame, grid, text, img, rect, ellipse, line — and nothing in that vocabulary can execute logic. A given .gui file renders to the same picture every time, on every renderer, because there is no code path for it to do otherwise.

What "closed vocabulary" buys you

A file that can’t run code is a file that can be fully understood by reading it. That’s what makes a .gui file diffable (two versions differ by exactly the attributes that changed, not by whatever a script does at runtime), validatable (a fixed vocabulary has a fixed set of legal shapes to check against), and scoreable (see the CCAC model) — none of which is meaningfully possible for an arbitrary HTML+JS bundle, because the actual rendered result depends on execution, not just the source.

Where HTML still wins

HTML is the right choice when the interface needs behavior — a live feed, client-side validation, a WebSocket connection. .gui is not a competitor there; it’s a source-of-truth format for the design that a real app (in HTML, SwiftUI, Jetpack Compose, whatever) then gets built from. The <gui-embed> library renders a .gui file directly on a web page with one script tag when you do want it live in a browser, but the file itself stays inert — no logic, no side effects, same output every render.

The role vocabulary closes the same gap semantic HTML tries to close with tags like <nav> or <article> — except .gui’s 53 roles (RFC-0041) are a closed, enumerated set rather than a loose convention, so role="button" means the same thing in every file, not "probably a button, check the click handler to be sure."

Borrowing the idea, not the tax

HTML started as a simple trio — markup, style, script. In practice almost nobody hand-writes plain HTML for a real interface today; the actual authoring surface is a JavaScript framework (React, Vue, and the rest) sitting on top, and that layer is where most of the weight now lives. HTML won by adoption, not because raw markup is a great design representation — it’s the one format every browser, tool, and person already knows, so "design in code" defaults to it by network effect more than by merit.

The markup itself is a deliberate, direct descendant of that instinct: .gui is XML-inspired rather than JSON, specifically because a tag name carries meaning a JSON "type" key has to fake, and because every major model has been trained on enormous amounts of tag-based markup — asking an agent to write .gui is closer to asking it to write JSX than to invent a new schema (RFC-0001).

.gui borrows HTML’s actual insight — plain markup any tool can parse, no proprietary format underneath — while trying not to inherit what widespread adoption did to it. A small, concrete example lives in its own layout vocabulary: the underlying primitive is a single <stack direction="..."> element, but writing direction="horizontal" on every row-shaped container turned out to be noisy in practice, so <row>, <col>, and <grid> exist as sugar that drop the direction attribute for the common case (RFC-0006). Same capability, less to write, less for an agent to get wrong — cutting tax on an idea, not just copying it.