Comparisons
.gui vs SVG: graphics format vs interface format
SVG made graphics text. .gui borrows that idea but is purpose-built for interface layout and semantics — things SVG was never designed to express.
SVG proved something important: a graphic doesn’t have to be a raster of pixels. It can be readable text — <circle>, <path>, <rect> — that any tool can parse, diff, and edit directly. .gui takes that same premise and applies it to interfaces instead of arbitrary graphics: the way .svg is to graphics, .gui is to UI.
Why SVG alone doesn’t cover interfaces
SVG has no concept of a layout system — no flex-like row/col with a gap, no responsive behavior, no design tokens, no idea of what a "button" or "nav bar" is. Everything in an SVG is either an absolutely positioned shape or a manually computed path. That’s exactly right for an icon or an illustration, and exactly wrong for a screen that needs to lay itself out, carry semantic roles, and reference reusable tokens.
.gui adds the layer SVG is missing: row/col/grid for layout with a real gap, design tokens for values meant to repeat, and a closed 53-role vocabulary so a node can declare what it is (role="button"), not just how it’s drawn. Shape primitives (rect, ellipse, line) exist in .gui too, so an icon or illustration can sit inside a .gui file natively — it just isn’t the whole story the way it is in SVG.
For genuinely complex vector artwork, .gui doesn’t reject SVG outright — an <svg> node can hold raw inline SVG markup directly, with no asset file or indirection needed, specifically so an AI agent that already knows how to write SVG paths can emit a logo or icon in place, in the layout tree, instead of fabricating an asset pipeline for a few shapes (RFC-0020). SVG is exactly right for that job — it’s just not asked to be the layout language too.
Why .gui is a package, not a single file
There’s a second gap SVG leaves for interfaces: a single SVG file has nowhere good to put a real photo. Embedding an actual raster image means either linking an external URL — the file alone no longer carries what it needs, so portability breaks — or inlining it as base64 text, which bloats the file enormously. If an AI model has to pass that file through, it pays the token cost of every base64 character even though the image data is completely opaque to it.
That cost is measured, not assumed: in early testing, inlining just two to four images as base64 consumed roughly half the token budget of a multi-hour session converting a file (RFC-0004). Plain path references cost nothing to reference — which is also why .gui skips a separate asset-manifest block entirely: an image just declares src="assets/hero.webp" inline, at the point it appears, the same way HTML, SwiftUI, and Android handle images (RFC-0031).
That’s one of the two reasons .gui is defined as a zip package rather than a flat text file: real image files sit in an assets/ folder alongside the markup, referenced by a plain relative path. See .gui vs a screenshot for why keeping the structure itself — not just the image — is the bigger point.
Frequently asked
Can I put SVG shapes inside a .gui file?
.gui has its own shape primitives — rect, ellipse, line — that cover the same ground for icons and simple graphics. For more complex artwork, an <svg> node can also hold raw inline SVG markup directly, no asset file required.
Why not just extend SVG with a layout system instead of a new format?
SVG’s design targets arbitrary vector graphics, not application interfaces — it has no concept of roles, tokens, or a UI-shaped element vocabulary. .gui borrows SVG’s "readable text, not pixels" idea but is purpose-built for UI from the ground up.
Why is .gui a zip package instead of a single text file like SVG?
Mainly to keep real images as real files instead of inlined base64 text. Testing found that inlining a handful of images as base64 could consume roughly half the token budget of a long AI session — a plain path reference into the package’s assets/ folder costs almost nothing by comparison.