Comparisons
.gui vs a screenshot or PNG mockup
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.
A mockup is a picture. However it was made — Figma export, a hand-drawn comp, a screenshot of a competitor’s app — once it’s a PNG, the structure that produced it is gone. An agent asked to build from it has to reverse-engineer spacing, hierarchy, and exact colors from pixels: is that gap 16px or 20px? Is that gray #F5F5F5 or #F4F4F4? Nothing in a screenshot answers that with certainty.
Structure survives, instead of being reverse-engineered
A .gui file keeps the values that produced the picture, not just the picture. A gap="16" attribute is unambiguous in a way that a rendered 16px visual gap in a PNG is not. A fill="$surface" token reference tells you a color is intentional and reused, something a screenshot can’t distinguish from a one-off. Editing a .gui file means changing one attribute; editing a mockup to explore a variant usually means regenerating the whole image and hoping the rest stayed consistent.
It still renders to a picture — that part didn’t go away
A .gui file always renders to a real preview image too (preview.webp, part of every package) — nothing is lost by moving to structured data. The difference is the picture is a byproduct of the file, not the only artifact that exists. An agent, a designer, and a renderer can all work from the same source instead of each starting over from pixels.
Still true as vision models improve
A more capable vision model closes some of this gap, but it doesn’t remove the extraction step — reading a screenshot still means inferring structure, spacing, and hierarchy from pixels, a lossy process that can guess wrong with just as much confidence as it guesses right. A .gui file skips extraction entirely: the structure is already data, not something to be reconstructed.
That’s what makes .gui work as a design handoff format specifically: export once, and any AI tool downstream reads the actual design, with nothing to reverse-engineer and nothing to hallucinate — the difference between receiving a file and receiving a description of one.
Frequently asked
Does a .gui file still have a visual preview like a screenshot?
Yes — every .gui package includes a preview.webp thumbnail. The difference is that the structured markup that produced it is preserved alongside it, not thrown away.
Why can’t an AI agent just work from a screenshot directly?
It can, but it has to guess exact spacing, hierarchy, and colors from pixels — there’s no way to tell an intentional 16px gap from an accidental 15px one in a raster image. A .gui file states the value directly.
Do better vision models make this comparison less relevant?
Not really — a stronger model still has to run an extraction step to infer structure from pixels, and extraction can produce a confident wrong answer. A .gui file has nothing to extract; the structure is already the data.