|Agent-editable design files

The generated-code trap

Prompt-to-code is genuinely fast, and for a prototype it is often the right answer. It stops being the right answer the moment you want to change one thing.

The reason is that a component file has no stable identity for the things inside it. There is no ID for "the price row in the pricing card" — only a position in a tree of JSX that shifts every time the file is regenerated. So a change means either regenerating the file, which throws away every manual edit, or a textual patch, which is a diff against something the model half-remembers.

What a design file gives you instead

A design document is a normalized set of nodes with stable IDs. That is a small-sounding property with large consequences:

• +A change can be scoped to one node and three fields, leaving everything else provably untouched.
• +You and the agent can refer to the same thing across sessions, because the ID outlives the conversation.
• +The document can be diffed, merged, and rolled back, because it is data rather than text.
• +Layout can be validated. A structured layout value is either coherent or rejected; a class string is neither.

The round-trip that never works

Every few years something promises two-way sync between a design tool and a codebase. It does not hold, and the reason is not effort. Code carries information the design does not — logic, state, data, conditionals — and the design carries intent that code has already dissolved into utility classes and computed values. Mapping either direction loses something, and mapping both directions loses something twice, continuously.

One-way export is the honest version. Compile the document to code, deterministically, and let the code be code. If a change belongs to the design, make it in the design and export again. If it belongs to the application, it was never the design tool’s to hold.

Shared vocabulary

The last requirement is that the human and the agent use the same operations. Not similar ones — the same ones. When a drag on the canvas and an agent’s moveNodes call are the same transaction against the same engine, there is no sync layer to get out of step and no reconciliation to lose an edit in.

That is also what makes correction cheap. The agent builds a section, you widen a column by hand, the agent reads the tree and sees the width you set. Neither of you has to be told about the other.

What this looks like day to day

Ask for a page and the agent inserts real nodes onto a canvas you can see. Something is off, so you drag it — no prompt, no regeneration. Ask for a variant and it makes a branch; the version you liked is untouched while it works. Compare the two, keep the better one, and export React when you are done.

None of that is possible when the artifact is a folder of files whose only stable name is a filename.

Questions