AI Design Workflow

Where this came from

The tools arrived faster than anyone could keep up with. Hundreds of them, changing almost by the week, each promising the same thing and behaving differently once you tried it. Designers hopped between them and lost the task somewhere in the hopping: half of it in one tool, half in another, and the reasoning nowhere. What was missing was never another tool. It was one place a task could sit.

This built up over about half a year of running my own design tasks with an AI coding agent. The internal page opens by saying as much: it is not the one right way to do things, it is a working approach for keeping a task in one place from the first brief through to handing it over to development.

The part worth passing on was never the prompt. It was having the task, the decisions and the reasons behind them sitting in one folder that somebody can open two weeks later. Getting other designers there meant solving the first fifteen minutes, because the tooling expects you to open a terminal and most designers have never had a reason to.

That first quarter of an hour turned out to be the whole problem. Nothing technical stood in the way — what stood in the way was habit, and a fair suspicion of anything that asks you to change how you work in exchange for a payoff you have not seen yet. So the guide had to earn it early: eight steps, one command, and something on screen worth having before anyone had time to decide it was not for them.

Not the one right way. Just a working approach to keep a task in one place, from start to delivery.

What I wrote

The setup guide

Eight steps, written for someone who has never opened a terminal. It starts with asking IT for an account and ends with pasting a Figma link and getting a prototype back. The terminal appears once, in step two, as a single command that installs everything underneath, and the guide says plainly not to worry about what is inside it. The steps that break most often have their own boxes: what to do when macOS blocks the install, what to do when your account comes up on a free plan instead of the team one.

The task folder

Each task lives in its own folder. What goes inside is up to you, interviews, screenshots, competitor notes, whatever that task needs, and the only file that has to be there is context.md. The page says the project root does not need to be clean, and it means it: a README, scratch notes and half-finished ideas are all fine to leave lying around.

The skills

They follow the shape of a task: starting one, reporting on it, closing it, and writing up how a component behaves. There is more than one way to begin, which was deliberate. You can type /start-task on its own and get asked what you are working on, describe the task in plain words and let the agent work out what to run, or paste a ticket or a Slack thread straight in. Nobody has to memorise anything.

What running a task actually looks like

This is the walkthrough I recorded for the team, written out. A design task is almost always "add something to a screen that already exists", so I need that screen first. I take a link to the Figma frame, hand it to Claude and ask it to build the page from it. It reads the mockup and puts together a working environment, and that is where the rest of the work happens.

You take a task, drop it in, and get a clickable prototype. From that prototype, the design in Figma on our components.

Then I run /start-task. You can drop in whatever you already have, a Jira ticket, a Slack thread, a couple of sentences of your own, and it asks about anything that is unclear. In the walkthrough I paste nothing and just write "improve the design of the users table". It goes into the project, looks at what is already on that page, and comes back with questions: what is in scope, who we are improving this for. I answer and we carry on.

It reads the code, walks through the table and offers a few concepts as diagrams. I pick one and ask for a prototype. While it builds, context.md fills up on its own with what we decided, why, and what changed along the way. I do not maintain that file by hand.

What comes out is a clickable prototype of the table. I tweak a few things and take it to grooming, where I can make edits during the meeting while we are still discussing them.

I take it to grooming and make edits right there in the meeting, as we discuss.

The part I use most is the pointer in the preview. You hover over an element, click it, and Claude already knows which component you mean, so there is no describing it in words.

You rarely have only one task. You start one, something urgent lands on top, then an old one comes back, and when you return to the first one two weeks later you do not remember where you stopped. So I type /status and it reads context.md and tells me what is done, what is in progress and what is left.

When the prototype is ready I bring the design into Figma, built on our design system components. I open a new page, grab the link to it and ask Claude to build there. It is not always right the first time and I fix a few things by hand, but it saves a lot.

Then /finish-task goes through the checklist with me: states, flows, copy, accessibility, edge cases, and shows what is missing. And /dev-spec covers behaviour. I point at one component, a sticky column or a filter in the table, and it describes how that component behaves and writes the annotations next to it in Figma. That is where it earns its place, on states, animations and transitions, the things a static mockup cannot show.

The five skills

I wrote all five and I still maintain them. Below is what each one does, with a trimmed excerpt from the actual file. Role names, plan names and internal paths are covered over; everything else reads as it does in the original.

## STEP 1: DISCOVERY — 5 areas
   (MANDATORY before the card)

### Question rule: hypotheses + free text

Don't ask an open question into the void:

1. Phrase the question in one line.
2. Propose 2–4 hypothesis-answers, A/B/C/D.
3. Use the project's typical segments
   (roles redacted) as anchors.
4. Say: "Pick a letter, mark several, or
   answer in free text."
5. Wait → record → next area.

Don't dump all 5 areas in one message,
that produces a "yeah, all of them" answer.

## STEP 1: DETERMINE THE STAGE

| Stage       | Signals                    |
|-------------|----------------------------|
| Not started | context.md empty / missing |
| In progress | Problems + Goals exist     |
| Review      | Solution ready, awaiting   |
| Done        | Closed                     |

## STEP 2: SHORT FORMAT (default)

**[Name]** — [stage]
What we're doing: [one line]
Solutions: [N]/[total] implemented
Next step: [what's planned]
Blockers: [if any]
Figma: link redacted

## FULL CHECKLIST

### 1. UI states
- [ ] Default / Loading / Error
- [ ] Empty / Success / Disabled
- [ ] Hover / Focus

### 4. Accessibility
- [ ] Contrast WCAG AA (4.5:1, 3:1 large)
- [ ] Keyboard navigation (tab order)
- [ ] Screen reader labels
- [ ] Touch targets 44x44px

### 5. Corner cases
- [ ] Long text, what happens?
- [ ] Lots of data, pagination or scroll
- [ ] Different roles: redacted

# Dev Spec — behavior & annotations

**Why behavior, not composition.** When the
design sits on design-system components with
code mapping, the developer already gets the
composition for free. Re-listing it is noise.
What a static mock does NOT carry is
*behavior*. That is the gap this skill fills.

## STEP 1: EXTRACT BEHAVIOR

- States & transitions, what triggers each
- Interactivity, per element
- Conditional logic, show/hide rules
- Edge cases: long text, empty, slow, error
- Data / API, what loads, what on failure

## Step order (follow the numbers)

1. Verify the design-tool connector is alive.
   On error: stop, don't guess the layout.
2. Load the design-system context
   (reference paths redacted).
3. Screenshot the frame from the URL the user
   gave, keep it for pixel comparison.
4. Build the UI with design-system components
   only. Do not paste generated markup as the
   final result, adapt it.
5. Mount the page. Ask the user for names
   first, don't default to a placeholder.
6. Run the pitfalls review.

The decision log

context.md is the file the whole thing rests on. The agent creates it with four sections, and the first one is never edited, so the brief as it originally arrived stays on the page next to everything that happened to it afterwards. In practice the exact format drifts from task to task, and that is fine. What has to survive is the decision log itself: which decisions were made and why.

[ORIGINAL]

The requirements as they first arrived. Nobody edits this part, so when the scope grows you can see exactly how far it has moved from what was asked for.

[CHANGELOG]

Every change of scope, with the date and the reason for it.

[DECISIONS]

What we decided, who asked for it, and the argument that settled it.

[CURRENT]

Where the task stands right now. /status reads this section, and /finish-task builds the handoff on top of it.

It writes the decisions and the changes as we go. I don't keep it by hand.

Decisions I made along the way

Discovery asks with hypotheses, not open questions. The agent reads the folder and the analytics first, then asks one question at a time with two to four guesses attached, labelled A to D. People answer that in seconds. Asking someone "so who is the user here" gets you a promise to think about it.

Four concepts before anyone opens Figma. A minimal version, a sensible one, an extended one and a deliberately odd one, all drawn as ASCII sketches. At that fidelity an extra concept costs about a minute, so it is worth drawing the odd one — every so often it is the one that gets picked.

The log only ever grows. The agent can add to it and cannot rewrite what is already there. Once someone starts tidying a decision log, it stops being useful for the argument you keep it for.

The dev spec covers behaviour, not composition. Developers already get components and tokens from the design file. What a static mock does not tell them is what the thing does: states and transitions, what shows and hides when, what happens with long text or no data, and what the API is doing behind it.

Where it landed

The team works this way now. When a product manager asks how a task is going, they get a written answer the same day instead of waiting for the next sync. Stakeholders see the concepts and the reasoning behind them early, while changing direction is still cheap. Developers get a handoff that already covers the states, the empty cases and the analytics events they used to send questions about.

It went to a hundred-person development organisation first, on the reasoning that a process nobody outside my own team had tried is not a process yet. It held there, and that bought the next half-year of shaping it to fit the rest of the company.

Every case on this site went through the pipeline, which is why each one can point at a real history of iterations with names and reasons attached, instead of my recollection of what probably happened. I maintain the process page and answer questions in the team channel.

What the team said

Half a year in, I ran a survey across the design team — the first honest look at whether any of this was helping. Everyone who answered had at least met the process; the shares below are of those answers.

Would you recommend it to a colleague? 4.4 out of 5.

The guide is what carries people in: seven of every ten started there, and almost nobody worked it out alone. That is worth knowing, because the guide was the part I nearly skipped — writing setup instructions for designers who never open a terminal felt like the least interesting thing on the list.

Nobody rated the speed-up below the middle of the scale, and the bulk of the team sits one notch above it. Quality lands lower than speed, and that gap is the honest headline: it is faster than it is finished. People mostly use it for prototypes and for copy, and a few now keep the whole task in the decision file the way the process intends.

What stakeholders said back. "The prototype carried the idea of a new feature more clearly than a Figma prototype would have." "I showed a live prototype and it landed." "It makes explaining and defending a decision easier." That is the argument for the pipeline in one line: the thing you bring to the meeting is clickable, so the meeting is about the idea instead of about what the idea might feel like.

What gets in the way. Two things, and both are fixable. Without the skills installed, the output drifts off the design system — the model builds it its own way, and the result looks close but is not on our components. And the heaviest users run into token limits. The first one is a setup problem, not a model problem, which is exactly why the guide matters more than it looks.

What it points at next. The survey confirmed the demand for a prototype portal: somewhere the prototypes live, connected to the developers' codebase, where people can make edits themselves instead of asking for them.