Best practices
Common mistakes AI agents make in .gui files
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.
An agent that generates .gui without the dotgui skill installed (see Prompting your agent) will often fall back on HTML/CSS habits that technically validate but miss what the format is actually for. These are the five that show up most.
1. Faking spacing with an empty row
Adding an empty
Use the gap attribute on the parent row or col. One declared number, no dead markup. Full explanation in Spacing and gaps.
2. Hardcoding colors instead of using tokens
Repeating the same literal fill="#2B6BE4" across a dozen nodes instead of declaring it once as a token and referencing $brand. This directly costs points on the Consistent level of CCAC scoring — a file that hand-repeats a value doesn’t agree with itself the way a token-backed one does.
3. Skipping role= entirely
Leaving structural nodes without a role= anchor. It costs nothing to add and it’s the entire basis of the Comprehensible CCAC level — a button without role="button" is invisible to any tool trying to read the file’s semantics, not just to a human. Roles are declared, not inferred, on purpose: only the author (or the agent writing the file) actually knows a subtree is a nav-bar rather than a breadcrumb trail that happens to look similar (RFC-0041).
4. Over-nesting containers
Wrapping a row inside a col inside a frame when a single row would do — an old defensive-div habit. Extra nesting with no layout purpose is exactly what the Clean CCAC level flags as waste.
5. Forgetting the assets folder
Referencing an img src that doesn’t point to a real file inside the package’s assets/ folder. A file can be syntactically valid and still be broken this way — the Intact gate (part of CCAC’s scoring gate) exists specifically to catch it.
Frequently asked
Why do AI agents fake spacing with empty elements in .gui?
It’s a carried-over habit from HTML/CSS, where an invisible spacer element is a common (if outdated) way to force a gap. .gui’s row and col elements take a literal gap attribute instead, so the workaround is unnecessary.
Does a hardcoded color still produce a valid .gui file?
Yes — it validates fine. But it costs points on the Consistent CCAC level, since the file doesn’t agree with itself the way a token-backed value does, and it makes global color changes harder to make correctly.
What happens if role= is left off a node?
The file still validates and renders — role is optional structurally. But it’s the entire basis of the Comprehensible CCAC level, so leaving it off means the node is invisible to any tool or agent trying to read the file’s semantics.