Designing the Instructions

Context Xflow moves money across borders. Six designers, a dashboard with a few hundred screens, and the usual problem: the reasoning behind our work kept evaporating. PRD decisions lived in Slack, and rejected iterations got deleted when the Figma session ended.

Our engineers had solved their half. They keep a shared context folder describing every screen, state and persona, and their tooling reads it before touching anything. Design had no equivalent, so every session started with me explaining our own product from scratch, badly.

Three months later, what I'd designed wasn't screens. It was the instructions.

I described our product to the AI and asked for a settings page.

What came back was good. Clean hierarchy, sensible grouping, choices I could have defended in a review. It was also a settings page for a product that doesn't exist. Our real sidebar has a collapsible group our own IA never documented, our settings sit behind four entity states, and our fee display has eight variants because passthrough pricing is tiered per currency pair.

Wrong would've been fine. This was plausibly wrong, which is worse. A generic-but-competent screen survives a glance, gets built on, and three weeks later something feels off and nobody can say why.

The same week I asked the model for our brand colour. Instant answer, confident, one shade off, and I didn't notice for a week.

The model never touches the ground truth. It writes the extractor. The extractor reads the product.

Give it the product, not a description of it So I captured the dashboard instead of describing it. A headless browser walks a sitemap one persona at a time and saves each page as self-contained HTML: real DOM, real class names, real tokens, nothing linked out.

That last part was a decision. The first version linked to our production stylesheet, which worked until a deploy changed the build hash and every snapshot silently rendered unstyled.

Then I gave the rule teeth Having a baseline isn't the same as using one. Steps would sail past with the snapshot sitting unopened on disk.

So a missing snapshot blocks three steps now. It stops and offers two exits: capture it, or accept the gap in writing, where the gap stays visible in the artifact. And "present" had to mean "read", so the check makes the step quote a real class name out of the file.

Any product with a URL has this problem, so I generalised the layer, tried it against six others, and released it.

How the grounding layer works → The free tool it became →

Nine steps, and a gate between every one One enormous prompt was the obvious build, and I tried it. It behaves like a junior designer who's read a book about design: nine steps arrive at once, confidently, with nothing to push back on. So I cut it into fifteen small skills with a confirmation gate between each.

The gate is the product Generation turned out to be the cheap part. What matters is that nothing moves until a designer says so, and that every artifact lands somewhere the next step is forced to read it.

The chaining is what surprised me. Validation writes obligations the prototype has to honour, and the wireframe's task flow becomes the contract for what gets captured into Figma, so a nine-screen flow that lands one frame is a failure the system catches itself.

Then I ran it on a cheaper model On the strongest model it was flawless. On a cheaper one it skipped gates, renumbered steps and invented inputs, which told me my instructions were only suggestions a thoughtful reader would follow. The strong model had been covering for me.

So the file became a constitution: eight numbered rules, cited by ID from inside the skills rather than restated in them. The eighth is precedence, and it turned out to matter most: the designer's word in the room beats the constitution, which beats a procedure, which beats a learned preference.

Why small skills beat one big prompt → What breaks when the model gets cheaper →

One feature, two rounds, seven approaches These are the shots as the workflow emits them: grayscale HTML built on a captured snapshot of the live page, every value already a placeholder or a grey bar.

Round 1 came back with three framings of one question, which is why people hunt for settings at all. I rejected the round, because read together they were three arrangements of one idea. Round 2 broke the frame and picked up a second axis the first had ducked: whose account are you editing?

Corrections should compound, not repeat Correct the same thing three times and it stops being a correction. It's a preference somebody should have written down.

So each designer gets a plain markdown profile they can read and edit. An entry pairs what happened with a rule phrased "in this situation, do this, because that". The because is load-bearing; without it you've recorded a description, and descriptions can't be applied.

Then I checked whether any of it worked Capture worked. Consumption didn't. A rule I'd established weeks earlier said wireframes go to Figma as editable frames, not flat pictures. Three sessions running pushed flat pictures.

Nobody was careless. The procedure file said the opposite: it called captures "pixel-perfect", and an image fallback had blessed itself as fine for review canvases. The rule was real, recorded, in force, and losing to a document.

Four of the six principles on that skill were quoted verbatim inside the procedure. Those four held. The two that weren't, didn't.

Worse: every principle those sessions honoured was also in the procedure they were following, so "profile loaded and applied" and "profile never opened, procedure obeyed" predict identical behaviour. I couldn't tell them apart. I'd built a learning loop whose success was unfalsifiable.

The fix was to stop pretending the profile steers anything By my own precedence rule a preference sits below a procedure, so one that contradicts a procedure loads and then correctly loses. The mechanism worked as designed. The design was wrong.

Each principle now declares its relationship to the text it touches, and that decides where it goes: a proposed edit to the file it argues with, a stance the skill loads where the procedure is silent, or an amendment to the constitution. Backfilling the set gave 29 already in, 7 new, 3 actively overridden, 1 for the constitution. All three overrides were known, so the yield wasn't bugs. It's that one search now names every principle losing to a procedure, and that search didn't exist the day the rule failed twice.

How you actually teach an AI your taste →

The workflow builds prototypes in code, the team lives in Figma, so they had to arrive as editable layers and the feedback had to come back.

Getting the push working took three hunts. My favourite: it quietly stopped working because a second integration had taken the same slot as the first. Both named for the same design tool, only one could capture. Nothing errored, it just did the lesser thing while reporting success.

An AI that silently does the lesser thing is more dangerous than one that fails. A failure gets fixed, a silent downgrade gets shipped. So capture is the declared norm now, and the image fallback has to announce itself and be confirmed.

Then the loop closed Every path in was one-way until the read worked. A round now pushes as a grid, one row per story and one column per iteration, because what a reviewer needs is the same job solved four ways side by side.

The push writes annotations too, in two categories: what the design is, and the research pointing at it. The live round carries 33, and 22 sit on the layer they describe rather than floating on the frame.

Then a rule landed that made me rewrite all of them. A product manager or an engineer reads these having sat in none of the sessions, so they have to be plain English. Forty-one got reworded; the seven a designer wrote stayed as they were. "Content region" became "the main part of the page", "CTAs" became "buttons competing for attention", and every research note names its source now.

One got missed. The verification pass caught it, named the node, and left it alone on purpose: the rewrite was the designer's pass, and one note in a third register is worse than one left stale.

The hunt for a capability that quietly vanished → Why our Figma design system is generated from code →

First on a real feature, with me refusing to help I'd tested it gently, on examples that were never going to embarrass it. So I ran a settings redesign we actually needed, start to finish, answering every gate but never stepping in when it wobbled. Nine steps, three validated prototypes, each captured to Figma. It also broke in twelve places, and those twelve findings were worth more than the three prototypes.

Then autonomously, to test the chain With me in every gate I was patching seams with judgment, so I handed a synthetic brief to an autonomous run and audited it step by step. No blocking failures, and the chain held: the task flow's nine screens became a nine-frame contract that landed nine of nine. The checks with teeth caught real problems inside the run that produced them, including the brief contradicting the product and missing states in wireframes the same agent had drawn ten minutes earlier.

What only breaks when you run it for real →

A system like this attracts overclaiming, so here's the ledger.

The first column is the one I'd push on hardest. Seventeen features carry baselined metrics and none has post-launch data yet, so the effect on the product is still a hypothesis with good instrumentation behind it.

What I am confident about is the record. Roughly 200 dated entries hold what changed and why, reversals included: a wireframe medium I picked then abandoned, a fix I announced as landed that was never written, a statistic I retracted once a proper count showed the estimate was out by sixteen times. Five separate times one diagram builder produced the same broken output, and I know it was five because they're numbered.

Documentation that maintains itself →

I set out to make design faster. What I learned was where the leverage sits once an AI does the drafting.

The instructions are the design surface. When an agent produces, the artifact you control is the text governing it, and that text has every property of a design system: hierarchy, precedence, drift, one canonical source. My best hour here went on working out why a rule everyone agreed with kept losing to a paragraph nobody had reread.

Ground truth is a design decision. Every serious failure traced back to a fact from a model's memory rather than the product. The fix is never a better prompt, it's a script or a captured page or a quoted class name.

Automate everything except the judgment. Nine steps, and the AI makes no decisions. Every choice that shapes the product still gets made by a person, out loud, on the record.

I wrote this up as it happened, in seventeen posts: the arguments, the reversals, the bugs, and the parts still open.

Notes from building an AI design collaborator →