Guides

The most common misread is that .gui is another framework you have to set up and run. It isn’t. Like an image, a .gui file stands on its own: you open it and see the interface, with no runtime required.

The honest version: .gui isn’t trying to replace HTML, CSS, or your design tool. It adds one missing thing: a portable, throwaway design layer for the AI era.

The question that decides whether a UI format is worth having: does it record where things landed, or the rules that put them there? .gui stores intent, which is also its hardest spec problem.

Where the format is (v0.2), where it’s going (v1.0 visual completeness, v2.0 motion), and the honest answer to "the ecosystem is the existential question."

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.

The most common reaction to .gui is "isn’t this just XAML?" It has the same markup shape and a different job: those are UI languages bound to a runtime; .gui is a portable target that can emit them.

A question that comes up fast: "why is the dotgui site built in Vue, not .gui?" Because .gui isn’t a framework you deploy; it’s the design the framework gets built from. Here’s the distinction.

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.

The fair developer objection: "a designer sends me a .gui, AI interprets it, it won’t be pixel-perfect, and it won’t map to our internal components." True, and not what .gui is claiming to do.