Designing the Instructions

It was the instructions. Took me three months to notice.

Xflow moves money across borders. Six designers, a few hundred screens, and the reasoning behind our work kept evaporating into Slack threads and closed Figma sessions.

Our engineers had already solved their half, with a shared context folder their tooling reads before touching anything. Design had nothing like it, so every session started with me explaining our own product from scratch, badly.

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've 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, full confidence, one shade off, and I didn't catch it 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 cost me a week, because the first version linked to our production stylesheet and a deploy changed the build hash.

Having a baseline isn't the same as using one, so a missing snapshot now blocks three steps outright, and "present" has to mean "read".

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

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 gate between the steps.

Cut up that way, you can also take the stages a feature actually needs and leave the rest. Somebody runs the lo-fi wireframes out of it, finishes in Figma, and ships.

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

A cheaper model exposed the writing. It skipped gates and invented inputs, so my instructions had only ever been suggestions a thoughtful reader would follow. They became a constitution, whose eighth rule is precedence: the designer in the room beats the constitution, beats a procedure, beats a learned preference. Hold on to that order, it comes back.

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

Corrections should compound, not repeat Correct the same thing three times and it stops being a correction. It's a preference somebody should've written down, so each designer gets a plain markdown profile they can read and edit. Every entry says what happened and why, because without the why it's 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.

It gets worse. Every principle those sessions honoured was also sitting in the procedure they were following, so "profile loaded and applied" and "profile never opened, procedure obeyed" predict exactly the same behaviour. I couldn't tell them apart. I'd built a learning loop whose success was unfalsifiable.

Remember that precedence order. 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.

So each principle now declares its relationship to the text it touches, and that decides where it lands. Backfilling the set gave 29 already in, 7 new, 3 actively overridden. The point isn't the new ones, it's that one search now names every principle losing to a procedure.

How you teach an AI your taste →

Getting the push working took three hunts. My favourite: a second integration had taken the same slot as the first. Both were named for the same design tool, only one could capture, and 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 fallback has to announce itself.

The capability that quietly vanished → Our design system, generated from code →

I'd been testing it gently, on examples that were never going to embarrass it. So I ran a settings redesign we actually needed, answering every gate but never stepping in when it wobbled. It broke in twelve places, and those twelve findings were worth more to me than the three prototypes. A second run took a synthetic brief with nobody in the gates at all.

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

The first column is the one I'd push on hardest. Eight of the seventeen features have shipped, and a UX project now finishes roughly 3x faster than it used to, because we can run the work in parallel and delegate the research and the iteration. All seventeen 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'm confident about is the record. Roughly 200 dated entries hold what changed and why, reversals included: a wireframe medium I picked and then abandoned, a fix I announced as landed that was never written, a statistic I retracted once a proper count showed my 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.

What breaks when you run it for real → Documentation that maintains itself →

I set out to make design faster. What I got was an answer about where the leverage sits once an AI does the drafting, and it wasn't where I'd have guessed.

Ground truth is a design decision. Every serious failure here traced back to a fact from a model's memory rather than from the product, and 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.

And the line at the top holds up, though I'd have argued with it in month one. My best hour on this went on working out why a rule everyone agreed with kept losing to a paragraph nobody had reread.

I wrote this up as it happened, in seventeen posts, including the parts still open.

Notes from building an AI design collaborator →