Guides

CSS styles a document that already exists somewhere else. .gui is the document — structure, layout, and appearance in one file, with no cascade to fight.

HTML is a programming surface that happens to describe UI. .gui is a static, closed vocabulary that always terminates in the same picture, everywhere.

A Figma file only exists inside Figma. A .gui file is plain text in a zip — readable, diffable, and versionable without opening any design tool.

A picture is a dead end — an agent has to guess spacing, hierarchy, and color from pixels. A .gui file hands those values over directly, already structured.

SVG made graphics text. .gui borrows that idea but is purpose-built for interface layout and semantics — things SVG was never designed to express.

gui setup teaches your own agent the format. Here’s the mental model and what to actually say.

An agent that hasn’t been taught the format brings habits over from HTML and CSS that don’t belong in .gui. Here are the five that show up most.

The single most common habit agents bring over from HTML/CSS — and the one-attribute fix.

The four levels explained on /spec/quality, turned into concrete things to actually go fix.

Three layout elements cover almost every screen. Here’s how to pick between them without guessing.

The tells of an unedited AI-generated screen, and the structural (not aesthetic) fixes .gui makes available.