agent-clarifier

• I first wanted to build an artifact editor like Claude’s, with collaborative editing. It’s a huge build, and I’d already built something like it at work. So I picked something smaller and more personal.
• Claude’s question card is one of my favourites. It rescues a lazy, vague prompt, and lazy people like me love it. I’d used it a lot, and was always curious when Claude decides to show it, and when it doesn’t.

• I started with a vague Claude research about the card itself: how other frontier tools do it, and what’s public to learn from. That’s where I met its name, an ambiguity resolver. Sounds wild, right? I asked Claude to write the design tensions down in a learnings file as we went.
• That’s when it clicked. The real moat isn’t the card. It’s teaching the agent when to use it, and when not to. And the card has many personalities: several questions or one decision, all at once or strictly one by one.

• Reading done, I took the card itself apart. I lined it up against the AskUserQuestion docs, then against how Cursor, ChatGPT, MCP and LangGraph ask.
• Three things stuck. Multi-select must never move on by itself. Skip and close mean different things. And when to ask matters as much as how, so the README ships a prompt that tells the model when.

• I wanted each exit to tell the agent something different, so it can say what it did about it. Skip means “say what you assumed”. Decide for me means “say what you chose”.
• So Decide for me takes Skip’s place instead of sitting next to it, to avoid the overload. And × became minimise, so nothing is lost. A message typed while it’s folded is the answer.

Try Decide for me ↑Try writing it yourself ↑

• After v1 I asked for a draft mode: pick, get the answer prefilled, add context, then send. It came back as three levels of opt-in, an Edit first button and a prefill strip. Reviewing it, I couldn’t say what Edit first was for.
• So we cut it: one way to answer, the card, and one way out to your own words, the composer. Later Claude designed branching, and I said no to that too, to build a top-notch core first.

Sketch Live

Open the real board ⤢

scroll the real board ↓

• Plan and visuals came first: research, a written plan, a board of every state, then a build plan we agreed on before any code. Each round was snapshotted into process/, and never edited after.
• Then I hit a wall: I couldn’t judge a shadow, a grey or a 120ms confirm from a drawing. So the board was frozen in round 6, and every call after it was made on the real component, in a playground like the one above.

• We worked as a pair in Claude Code. Claude researched, drafted, built and tested. I set the direction and made the calls, from options with a recommendation, one round at a time. When I delegated a batch of calls in round 8, I audited them after.
• For the audits I brought in skills from people whose craft I trust: Emil Kowalski’s for motion, and Jakub Krehel’s for the interface. Each ran read-only first. I picked. Then Claude built it, and broke each fix on purpose to prove its test could fail.

• I asked why the card mixed black and blue. The answer found a real problem: blue had four jobs on one card, and the agent’s Recommended badge looked like my pick.
• So we prototyped a monochrome card, and I kept the blue anyway. The badge went grey instead. The same habit, see the options on the real thing, then pick, settled the row spacing and the pencil too.

01 · Focus and colour02 · Row spacing03 · Active pencil

Blue had four jobs on one card, and the agent’s Recommended badge sat right next to my pick. Claude prototyped two monochrome cards from a shadcn reference I liked.

Blue, as it wasmy call Blue pick, blue badge, blue dot Ink Monochrome, with an ink ring Grey Monochrome, with a grey ring

Enlarge Enlarge

Look at the picked key, the Recommended badge and the focus ring.

The callKept the blue: it says “your pick” best. The badge and the “Asked by” dot went grey.

• Most rounds started with a doubt from using it: an arrow that lingered, a header that lost its padding, a checkbox that felt plain. Each got a measurement before a fix, a test that fails without it, and a before and after.
• I wanted it to feel calm, and calm is a long list of small things. Every default now has a written reason in DESIGN.md. If a value has no reason, it’s a guess, and guesses get fixed.

Round 17

A limit that informs, not scolds

“Up to 2 picks” was a black toast, louder than the picks themselves. Black is for toasts you can press, so now it’s quiet ink text.

Try it ↑ pick four

Before After

Look at the footer, left of Skip.

Round 21

Back goes where the card doesn’t move

The card sits at the bottom, so its header is the edge that moves between steps. Back moved to the footer, and the dashes now show what’s answered.

Try it ↑

Before After

Look at the top-left corner, then the bottom-left.

Round 14

“Something else”, typed in place

It used to open a second box under the row. Now the row becomes the field. On single choice, once you type, the other options fade to grey, never see-through.

Try it ↑ press 4

Before After

Look at the last row.

Round 21

The number key answers the hover

The key was 2% away from the hover fill, so it vanished into it. Now it steps toward ink, mixed from the tokens, so a theme’s key follows.

Try it ↑ hover a row

Before After

Look at the 1 key on the hovered row.

Round 18

A stuck header keeps its padding

A margin was collapsing out of the sticky header, so “Asked by” touched the card’s edge once you scrolled. The fix was one line: display: flow-root.

Try it ↑ scroll the options

Before After

Look above “Asked by”.

Round 20

The arrow travels with its partner

Moving the mouse across rows left an arrow on a row it had already left. Now the arrow shows only with its partner: the fill for a mouse, the ring for the keyboard.

Try it ↑ sweep the mouse

Before After

Look at the right end of row 1, in the second and third frames.

Round 9

The pill that turned into an oval

Slowed down 10 times, the fold showed the minimised pill stretched into an oval mid-way. No test was looking for that. Now the pill only fades in.

Try it ↑ press Esc

Mid-fold, before

0 of 4 answered · Reopen

After

0 of 4 answeredReopen Or reply in your own words…

Round 15

The checkbox animation that didn’t exist

I wanted the feel of Claude’s checkbox. Frame by frame, it fills in one frame: the feel was my screen recorder’s click circle. We animated ours anyway, by Emil’s rules: a 0.8px press and a 120ms tick, mouse only.

Try it ↑ click, then press Space

Watch the tick draw in, left to right, over the first 60ms.

• I wanted it light, so nobody thinks twice about installing it. Claude measured first: 25 comparable packages, built with the same settings. Every safe saving added up to about 0.6 KB.
• So the honest result was a better target, not a smaller number: about 21 KB gzipped, among single-purpose widgets that do less, and nothing at page load if it loads on first use. The playground above does exactly that.

• MissTrusted 100% test coverage. Two tests checked either side of a limit, never the limit itself.

  LessonTest at the boundary. Then break the code on purpose, and watch a test fail.

• MissTrusted an “after” screenshot. The gap looked right only because a focus ring drew it.

  LessonA screenshot can agree with you for the wrong reason. Measure the thing itself.

• MissAssumed the audits still held. Two rounds of my own changes later, an accessibility fix had quietly gone.

  LessonAudits expire. Re-run them after every change to the parts they judged.

• MissTested against the source for 22 rounds. Three README recipes didn’t work, and some TypeScript users got no types.

  LessonRead it as a stranger. Install the package, and follow your own README.

• The end goal is bigger than one card: a skill and a knowledge base for crafting UX elements like this, faster. This one took a whole weekend of learning and care. Can the next one take a day?
• The first two are out: a skill for the clarifier itself, when to use it, when not to, and which variant fits, and one for the design engineering habits from this build. Now anyone can check their agent is using it right.

For the card itselfA VoiceOver pass, and a real phone with its keyboard.