.gui vs CSS: a file format vs a styling language

CSS styles something that already exists. It is a rule language that attaches presentation to a DOM another format (HTML) already built — selectors, specificity, inheritance, a cascade that resolves at render time based on document order and rule weight. .gui is the thing itself. A .gui file is a zip package — design.guix markup, an assets/ folder, a preview.webp thumbnail — that fully describes one interface: structure, layout, and appearance, together, in one file. There is no separate document to style and no cascade to resolve, because there is nothing upstream of it.

What that actually changes

In CSS, the same element can end up styled by five different rules from three different files, and the final appearance depends on specificity math and load order. Reading a stylesheet does not tell you what anything looks like — you have to run the cascade in your head. In .gui, every node carries its own resolved appearance attributes directly, plus optional design tokens ($brand, $spacing-md) — a flat, named-reference system rather than CSS custom properties, since a --variable implies a CSS runtime and .gui is platform-agnostic (RFC-0005) — for values meant to repeat. There is one place a value lives and one place it’s read from.

Layout works the same way. CSS spacing between siblings is usually simulated — margins on the parent or child, sometimes an empty spacer element left over from table-layout habits. .gui’s row, col, and grid elements take a literal gap attribute — one declared number, no simulated elements. See Spacing and gaps.

Direction and alignment as values, not axis algebra

CSS expresses "these children run horizontally, evenly spaced" as a style declaration repeated on every container — display: flex; flex-direction: row; gap: 16px — whether it’s hand-written or generated by a utility system like Tailwind’s class list. .gui expresses the same thing as one element: <row gap="16">. Direction is the tag itself, not a property that has to be set correctly and can silently be left off — see RFC-0006.

Alignment follows the same pattern. CSS splits it into two axis-relative properties — justify-content for the main axis, align-items for the cross axis — and which axis is "main" flips depending on flex-direction, a piece of mental bookkeeping baked into the model. .gui replaced both with a single align attribute using nine positional values (top-left … bottom-right) that always name a visual position directly, the way a designer already describes layout, rather than a main-axis/cross-axis calculation — modeled on Figma’s own alignment grid, not flexbox terminology (see RFC-0012).

There’s no controlled benchmark for the token difference this makes, but the intent is explicit in the format’s own design record: a single row or one align="middle-center" value is harder for a model to get wrong than a multi-property, axis-relative CSS block, and there’s less text to generate for the same layout intent either way.

Why this matters for AI agents

An agent asked to "style this the way the mockup looks" using CSS has to reason about cascade order across every stylesheet that could touch the element. An agent asked to change a .gui node’s fill changes one attribute on one node — nothing else in the file is implicated. That’s also what makes .gui deterministically scoreable: a validator can check a CSS ruleset for syntax errors, but it can’t tell you the cascade produced a sane result. A .gui file’s resolved appearance is just sitting there, readable, checkable.

.gui is not trying to replace CSS on the web — a browser still needs CSS to paint DOM. What .gui replaces is using CSS (or a CSS-in-JS system, or Tailwind classes) as the source of truth for a design. The design lives in the .gui file; CSS, if it appears at all, is one possible render target for it, generated rather than hand-maintained.