ux-designer: design a feature’s UX before you build it

---
name: ux-designer
description: Design the user experience of a feature before it is built, for the people and the AI agents who will use it. Use before adding or changing any user-facing feature, screen, action, flow, message or agent tool, even a small one, and whenever someone asks for UX, a design, user journeys, jobs to be done or edge cases. Finds the job behind the request, the moment people are in and how often it comes, the journeys through every way in (a screen, a person's AI assistant, a coding agent, an API, email), the edge cases and states, then designs what each person and agent sees, and writes it as a UX spec with acceptance checks and the decisions only the person can make. Settles those decisions with the person, then builds or hands over, and walks the result against the spec.
license: MIT
metadata:
  source: https://alcoven.co/skills/ux-designer
  version: "2"
---

UX designer: design it, then build it

Every feature people or agents use starts with a UX spec: who needs it, in what moment, how often, how they get through it from each way in, what can go wrong, and exactly what they see. The spec is short for a small feature and never skipped. Building comes after the person has settled the spec's open decisions.

The feature is the one the person asked for, in their words. If it names a fix ("add a filter"), the work starts by finding the job that fix serves.

The loop

1. Frame the request (below).
2. Know the product before designing.
3. Design, in the ten steps of the method, and write the spec.
4. Check the spec's facts against the product.
5. Settle the open decisions with the person.
6. Build to the spec, or hand it over.
7. Walk the result against the spec.

If you can only talk and write (an AI chat with no code), do 1 to 5 and hand the decided spec to whoever builds. If you can read code and build (a coding agent), do all seven. If you can start helper agents, a helper may do steps 2 and 3 and return the spec; the conversation with the person stays with you.

1. Frame it

• Restate the request in one sentence, in the person's words. Note the problem behind it if they said one.
• Collect what the person already settled in this conversation (scope, who may do it, "both should be undoable"). Those are decided: design within them and never ask them again.
• Pick a short kebab-case slug. The spec goes in the project's UX folder if it has one (look for a README.md in ux/, docs/ux/, wiki/ux/ or design/, which says where specs go and what to read); otherwise ux/<slug>.md. If the spec exists, update it and keep its decided rows.

2. Know the product before designing

Read what bears on the feature, not everything:

• the project's instructions (AGENTS.md, CLAUDE.md) and its UX folder's README;
• the brief: who the product is for, what it is not, the words it uses;
• the jobs map, personas or user flows, if the project keeps them: place the feature's job there;
• the design system or style rules: use its components and words, not new ones;
• what is agreed: decisions on record, and anything people agreed to. A design that goes against an agreed line is a decision for the person, never an assumption;
• the code: find how the product already does the nearest thing (a delete with undo, a picker, a notice, an agent tool's answer) and design the new feature the same way. Consistency with the product beats a better idea used once.

Mark every fact about the product with where it came from (a file and line, a document's section). A spec built on a wrong fact designs the wrong thing.

3. Design: the method

Work through these in order; each feeds the next. Keep each section as short as the feature allows. The principles behind each step are in references/principles.md; read the parts the feature touches.

1. The job and the moment. For each kind of person (and agent) the feature serves, write the moment: who they are, what just happened, how much time they have, what they are afraid of. Then the job story: "When [situation], I want to [motivation], so I can [outcome]". The motivation names no button or screen. Cover what they need done, how they want to feel and how they want to look to others. Say what the feature is not for. If no person has said it, mark the job as a hypothesis and say what would confirm it.
2. Who and how often. A table: who, how often (daily, weekly, monthly, rarely, once), the situation, what matters most then (speed, safety, confidence, a record for others). Then the frequency verdict, which drives the design: frequent tasks are fast, visible and repeatable without thinking; rare and risky ones are safe, explained and kept out of the frequent ones' way.
3. Today. What people do now: in the product, with a workaround, in another tool, by asking someone. Their words for it, quoted with a source when there is one. What the product already has to reuse, with paths.
4. Journeys, through every way in. The main journey as numbered steps: the trigger (the job's "When"), then each step as "person or agent does → product answers", to the done state and what they see then. Then: the other ways in (each door the feature has: the screen, a phone, the person's AI assistant, a coding agent, an API, an email link), the way back (undo, restore, correct a mistake), and what others see afterwards (teammates, their AIs, notifications, history, lists). Mark where someone could get lost or stopped. Design the most common path first and keep it shortest.
5. The experience. For each screen: where the control sits and why there, the components, the exact copy, the confirmation or undo, the feedback, where focus goes after each step, and what people without permission see. For each agent door: the tool or command's name, what it takes, what it answers (the agent's "screen"), the errors that name the next step, and what it says when nothing is found. For anything the product's AI suggests or does: why it shows, how to dismiss or correct it, and what it never does on its own (references/ai-and-agents.md). Add a small text wireframe when placement is not obvious. List every other screen, list, count, export, import, email or agent answer that must change with it.
6. Edge cases and states. Go through references/edge-cases.md and keep every row that applies, each with what the person or agent sees and the rule behind it.
7. Decisions. Three kinds. Open: only the person can decide (scope, who may do it, a business rule, anything against an agreed line); at most four, each with options, the recommended one first, and the consequence for the people who use it. Assumed: a sensible default you chose that the person may overrule. Settled: already decided, with who decided.
8. Acceptance checks. Numbered "Given … when … then …" lines, one per behaviour that matters, each written so it can become a test or a check in the running product.
9. Size and the riskiest assumption. Small, medium or large to build. If large: the smallest first version that still does the job, and the rest under "Later". Name the assumption that would sink the design if wrong and has least evidence, and the smallest test of it, with its pass line set now.
10. Self-review. Check the design against the self-review in references/principles.md and fix what fails before showing it.

Write the spec with references/spec-template.md: plain words, short sentences, tables over prose, the title as the first heading. Use invented people and companies in examples, never real personal data.

4. Check the spec

Read the whole spec before showing it. Check each fact about the current product against the code or the documents it cites. Fix small errors; redo a section built on a wrong fact.

5. Settle the decisions with the person

• Ask the open decisions: at most four, one question each, the recommended option first and marked, and each option's consequence for the people using it. Use the question tool your client has; otherwise number them in plain text.
• Do not ask what the code, the brief or an agreed decision already answers; those are Assumed or Settled, and the person can still overrule them.
• Write the answers into the spec's Decisions table (who decided, the date) and set - Status: decided.
• Give the person a short summary: the job in one line, the main journey, what changes where, and the edge cases that changed the design. Link the spec. Their answers are the go-ahead to build unless they say to wait.

6. Build to the spec

• Follow the project's own rules for code, branches, review and release.
• Turn each acceptance check into a test where it can be one: a rule into a unit or service test, a state into a component test, a journey into an end-to-end test.
• When the feature changes a task people do, update the user guide and the jobs map.
• If building shows the design was wrong, change the spec too, and tell the person when it is a change they would notice. The spec describes what ships.

7. Walk the result

Walk each journey in the running product, through each door, as the person in the job's moment: references/walk.md. Go through the edge-case table row by row: each row is handled, or moved to "Later" with the person's agreement. Set - Status: built and link the change.

When a spec is not needed

A refactor with no visible change, a fix that restores what was specified, a typo: say in one line that you are skipping the UX pass and why. A small feature gets a short spec, not none.

Files

• references/principles.md: jobs, frequency, journeys, states, destructive actions, messages, accessibility, permissions, and the self-review, with sources.
• references/ai-and-agents.md: designing for AI agents as users, and for people using AI features.
• references/edge-cases.md: the edge cases and states checklist.
• references/spec-template.md: the spec's shape.
• references/walk.md: walking a journey and scoring it.

Designing for AI agents, and for people using AI

Two things most UX methods leave out. First, an AI agent is a user too: it reaches the product through tools, an API, a command line or files, and its "screen" is the answer it gets back. Second, when the product's own AI suggests or does something for a person, the person has to understand it, trust it the right amount, and correct it in one step. Letters in brackets point to the sources at the end; (synthesis) marks a rule with no single source.

The agent as a user

Design the agent's door with the same care as the screen. The agent is a capable reader with a small attention budget and no way to ask what you meant.

Finding the right tool

• Build a few tools for whole tasks people ask for, not one per endpoint: search_contacts over list_contacts; a schedule_event that checks availability and books in one call. [T]
• Group related tools under a shared prefix for the service and the resource (skills_add, skills_update). Names are 1 to 128 characters of letters, digits, _, - and ., unique on the server. Keep the tool order fixed. [T][M]
• Describe each tool as you would to a new teammate: what it does, when to use it and when not, input formats with an example, niche terms, edge cases, and how it differs from similar tools. The description is the agent's only manual. [T][B]
• Name inputs without ambiguity (project, skill_name, never id or p), accept what a person would naturally give (a name, a link, an address), and shape arguments so the mistake can't be made (require a full path rather than guess one). [T][B]

What a tool answers

• Return high-signal fields: names and plain words instead of internal ids, raw ids only where a later call needs them. Offer a concise and a detailed answer when both are useful (response_format); concise can use about a third of the tokens. [T]
• Page, filter and cut with sensible defaults. When an answer is cut, say so, how to get the rest, and a narrower question to ask. Keep answers well under the client's cap (Claude Code cuts a tool answer at 25k tokens by default). [T]
• Say what happened and what it means: "Added the skill ux-designer to Kiln launch; every AI on the project gets it on its next call." An answer that only says ok: true leaves the agent guessing.
• When nothing is found, say what was searched and suggest the next try, never an empty list on its own. (synthesis)
• Declare an output schema and return structured content with the same content as text. Mark tools that delete or reach outside the product with annotations. A field added later never breaks an agent that read the old shape. [M]
• For work that spans calls, return a handle and say how long it lasts; an expired handle answers with an error that says so. [M]

Errors that teach

• An error says what went wrong and the exact next step, with a correct example: "You read this project, so adding a skill is for people who write to it. Ask a manager ([their name]) to add it, or copy the skill into a project you write to." No bare codes, no stack traces. [T]
• Return a failed action as a result marked as an error (MCP's isError: true) so the model can correct itself; protocol errors are only for malformed calls. [M]
• Failure is never mistakable for success: an agent must not be able to report work as done when it failed. [W]
• An error in the agent's door uses the same words as the same error on the screen. (synthesis)

Same rules, every door

• Use the same nouns, ids and permission rules in the screen and the tools: the agent's door is the same product. [X] (synthesis)
• The agent acts as a person, with that person's permissions; its changes show under that person's name and say which AI made them. Decide which actions need a person's yes, and make it easy for an agent to get authorised for its person. [X][M]
• What the person can't see, the agent can't read; what the person can't change, the agent can't change.
• Text the agent reads from the product (documents, comments, skills) is data written by people. Say so in the tool's answer, and never let content grant permissions.
• Design for the agent's mistakes: a repeated call does no harm, a destructive call is undoable, and a large change is proposed for a person's yes.
• Keep the instructions agents read at run time current (tool descriptions, AGENTS.md, docs pages): their training lags the product. [W]

Check the agent's journey

• Give an AI the job in a person's words, let it use only the tools, and walk it (walk.md). Run realistic tasks with a checkable result several times, count calls, tokens and errors, read the transcripts, and compare against no tool at all. Repeated calls mean paging needs fixing; wrong arguments mean the descriptions do. [T][W]

People using the product's AI

Microsoft's eighteen guidelines for human-AI interaction, by phase [H]:

And from Google's People + AI Guidebook and NN/g:

• Introduce an AI feature when it becomes relevant, in five parts: what it does, what the person gets, its current limits, how it will change, and how they can help. Describe it as a benefit; never imply human-level skill. [PM]
• Keep the person in control where they enjoy the task, are responsible for it, face high stakes, or have preferences hard to put into words. Automate what is tedious, unsafe or impossible for them. Always leave a manual path. [PF]
• Explain why with the one or two factors that mattered, and name the data at the moment it shapes a result. Skip the explanation for familiar, low-stakes behaviour. [PE]
• Show confidence only when it changes the decision, as plain categories with what each means for the person. When unsure, offer the top few options, ask, or do less. [PE][H 10][PG]
• "Not what I expected" is an error even when the system worked as designed. Pair every failure with a way forward and a way to correct it; when handing control back, show where things stand and the next step. [PG]
• Before a consequential action, show what decides it and let the person adjust, review and approve. [NA]
• Let people see, edit and erase what the system learned about them, and reset it. Say what their feedback changes and when; promise only what the system does. [PF]
• Change behaviour cautiously, announce changes, and re-introduce a feature after a significant one. [H 14, 18][PM]

The AI proposes; a person decides. For anything others will see or that is hard to undo, the AI proposes and a person decides. What it may do on its own is written down and small. An automatic action is something people can read and reverse, with who asked for it. In a shared space others see the person's name on the change, with the AI named beside it.

Suggestions that are welcome

For any feature that recommends something (a skill, a template, a next step):

• At the moment of need. Suggest on a signal that the person would benefit now: right after they did something the suggestion helps with. Never on arrival, never at random. [O][H 3]
• Beside the task, quietly. The least intrusive thing on the screen, never competing with an alert or blocking the work. Understandable without opening anything. [H 4][S]
• Say exactly why. Name what triggered it ("Because the brief mentions user interviews") and the data it used, and whether it comes from this project or from everyone. No vague "and more". [R][PE][H 11]
• One step to dismiss, taking effect at once, leaving a placeholder so nothing jumps. A scoped "don't suggest this again", with the scope stated (just me, or everyone on the project) and undoable; a way to turn a kind of suggestion off. [R][H 8, 17][PF]
• Few, and never repeated. One or two at a time; never again after a dismiss; stop once the person acted on it; don't treat one weak signal as a pattern. No source gives a number: set a cap and test it. [S][PF] (synthesis)
• Preview before commit. Let the person see what they would get before it is added. Adding is undoable and changes nothing else.
• Narrow groups ("for client work", "for research") over one mixed list. [R]
• Measured by use. A suggestion accepted and then never used is a failure: track whether the added thing gets used. (synthesis)

Onboarding and time to value

• Measure the share of new people who reach value, not sign-ups. Activation runs setup, then the aha (a core action within a time window), then habit; check the aha against who stays. [P][A]
• Go in a straight line to first value. For each step: cut it, move it to the moment it matters, or keep it only if value is impossible without it. Remove setup steps that look like they change the result but don't. [P][AI]
• Help in context beats a tour. Where a new way of working needs a walkthrough, the person does the task rather than watches it, and can dismiss it and find it again. [O]
• Empty states do three jobs: say the status (never "nothing here" while loading), teach what the feature does and how to start, and give a labelled action, including sample content that produces a real result. [E][AI]
• Offer templates when the person is ready to use one, not as an early tutorial step. Ask about their goal at the start only if the answer sends them down a different path. [AI][P]
• Make the first actions low-risk and reversible. [PM]
• For a team product, value often needs a second person: the invite and the second person's first minute are part of onboarding. (synthesis)

Sources

• [T] Anthropic, Writing effective tools for agents: anthropic.com/engineering/writing-tools-for-agents
• [B] Anthropic, Building effective agents, appendix 2: anthropic.com/engineering/building-effective-agents
• [M] Model Context Protocol, tools: modelcontextprotocol.io/docs/concepts/tools
• Mathias Biilmann, One year of AX: biilmann.blog/articles/one-year-of-ax
• [W] Microsoft, What is agent experience (AX): developer.microsoft.com/blog/what-is-agent-experience-ax
• [H] Microsoft, Guidelines for Human-AI Interaction (HAX): microsoft.com/en-us/haxtoolkit/library
• [PM] [PE] [PF] [PG] Google PAIR, People + AI Guidebook: mental models, explainability and trust, feedback and controls, errors and failing gracefully (pair.withgoogle.com/chapter/...)
• [NA] NN/g, Designing AI agents: nngroup.com/articles/designing-ai-agents
• [R] NN/g, Recommendation guidelines: nngroup.com/articles/recommendation-guidelines
• [O] NN/g, Onboarding tutorials: nngroup.com/articles/onboarding-tutorials
• [S] NN/g, Smart home notifications: nngroup.com/articles/smart-home-notifications
• [E] NN/g, Empty states: nngroup.com/articles/empty-state-interface-design
• [AI] NN/g, Onboarding new AI users: nngroup.com/articles/new-AI-users-onboarding
• [P] ProductLed, the product-led growth engine: productled.com/product-led-growth-engine
• [A] Amplitude community, the four stages of activation (secondary): community.amplitude.com/discussion/12791

Edge cases and states checklist

Keep the rows that apply and add the feature's own. Each kept row goes in the spec's table with what the person or agent sees and the rule behind it.

UX principles

The rules behind each step of the method. Where they disagree, the product's existing pattern decides; where it has none, write the choice down as Assumed. Sources at the end.

Jobs, not features

• Write the moment first: who, what just happened, how much time they have, what they fear. A person late to a meeting has thirty seconds; design for the thirty seconds.
• Then the job story: "When [situation], I want to [motivation], so I can [outcome]". The situation is concrete; the motivation names no button, screen or field; the outcome is the progress the person wants.
• Cover the functional, emotional and social sides: what gets done, how they want to feel ("not anxious about the client call"), how they want to look ("not careless in front of a client", "not the one who lost a colleague's work").
• A job that only makes sense with your design in it ("I want to click Delete") is design-shaped: ask "so I can what?" until it is not.
• Measure success as outcomes: a direction, a metric and an object, with no design in it ("minimise the time to learn what changed while I was away").
• Every element in the design traces back to a job. Say what the feature is not for, so scope stays small.
• A job nobody has said out loud is a hypothesis. Mark it, and say what a person would have to say or do to confirm it.

Test the riskiest assumption before building

• Put one outcome at the top (what should change for people), the needs and pains under it, drawn from stories people told about a specific time, and the ideas under those. To catch an idea dressed as a need, ask "is there more than one way to answer this?"
• For the need you choose, think of at least three ways to answer it before picking one.
• List what must be true for the chosen design to work, in five kinds: people want it, it pays, it can be built, people can use it, it does no harm. Write each as something a person must do ("the keeper adds a skill on the first day").
• Test first what matters most and has least evidence, with the smallest test that finishes in an hour (a walk, a prototype in front of one person, a one-question message, existing data), and set the pass line before the test.
• Talk to the people the feature is for every week, while it is designed and after it ships.

Frequency drives the design

• Do a light task analysis: the goal, then each step with how often it happens, how long it takes and the decision in it. Then cut steps and repeated input.
• Show first what people need often; put the rest one labelled step away, two levels at most. Give frequent actions shortcuts that stay out of a newcomer's way.
• Friction follows severity and reversibility; how rare a task is doesn't decide it. Easy to undo: no friction. Harder to undo: one extra step. Hard to undo or cascading: a dialog that names the consequences.
• Keep destructive actions apart from routine ones (people on autopilot click what is near): never next to the primary action, never the primary button, marked by more than colour.

Journeys

• For one feature, draw a user flow: the trigger, the ways in and how people find them, each step with the product's answer, the decision points, the exits (done, cancelled, failed) and how to recover from each failure. Keep journey maps for a whole experience over days, and a service blueprint when the work behind the screen (people, systems, agents) is the problem.
• Walk the flow through every door the feature has. A person in the app, the same person through their AI assistant, and a coding agent in a folder should reach the same result by the same rules.
• Design the most common path first and keep it shortest; branch rare cases off it.
• Time to value: count the steps from the trigger to the moment the person gets what they came for. Every step before that moment is a reason to leave; cut it, defer it, or do it for them.

States and edge cases

• Design all five states of every view: ideal, empty, error, partial and loading. Empty comes three ways: first use, cleared by the person, no results. An error keeps everything the person typed.
• Empty is never blank: say how it fills up and give the action, or start it with useful content. Never show "nothing here" while data is still loading.
• Loading: nothing under 1 s; an indeterminate indicator for 1 to 3 s; progress for 3 to 10 s; beyond 10 s, progress with cancel, or run it in the background and say where the result will appear.
• A part that fails is replaced on its own; the rest stays usable, and nothing suggests data was lost.
• Two people on one record: on save, check the version; say who changed it and when, and offer to see their change. A record deleted since the page loaded says who deleted it and when, with Restore where the person may restore it, not a bare "not found".
• Long names are cut with an ellipsis and shown in full on hover and focus; titles, labels and error messages are never cut. Casing depends on the language (Turkish i → İ): never upper-case people's data yourself; compare and sort with the locale.
• Wording for zero, one and many, in every language the product speaks.

Destructive actions

• Deleting stored data is reversible, checked or confirmed (WCAG 3.3.4); being able to restore is enough on its own.
• Match the guard to the damage. Easy to recreate: one click. Hard to recreate, or several at once: a confirmation. Irreversible or cascading: a dialog that lists the consequences; typing the name only for a permanent purge.
• A confirmation names the thing ("Delete the project Kiln launch?"), says what goes with it ("its 12 documents and 4 tasks") and how to get it back. Buttons say what happens ("Delete project" / "Cancel"), never Yes/No and never "Are you sure?". Focus starts on Cancel.
• Prefer undo to warning. An undo in a notice only when the same undo exists elsewhere (a Restore in a deleted list); keep such a notice at least 10 s.
• A deleted list is a real view; restore and permanent delete are separate actions. Record who deleted and who restored, and when.

Messages and focus

• Errors are specific, plain and blameless, and say how to fix it; they sit next to the field and repeat its label's words. No "invalid", "oops", "please" or "sorry".
• Validate when the person leaves a field, clear the error as soon as it is fixed, validate again on submit.
• Inline for one field or row; a banner for the page (one, above the heading); a short notice for news that is not essential. Announce every result, including success, to screen readers (role="status"; role="alert" for errors).
• After an item is removed, focus moves to the next item, or to the list's heading when the list is empty.

Accessibility (WCAG 2.2 AA)

• Dialogs: focus moves in and stays in, Escape closes, focus returns to what opened it (or the next sensible place if that is gone), labelled by its title.
• Targets at least 24 px with space around them; 44 px on touch.
• Focus is never hidden behind a sticky header, a notice or a drawer (2.4.11); whatever drags also works with one click (2.5.7); nothing asks again for what was already entered (3.3.7).
• Never colour alone; reflow at 320 px without sideways scrolling (tables excepted); mark each language part with lang; honour reduced motion.

Permissions and tables

• Hide what this person can never use; disable, with one sentence why ("Only managers can remove people."), what they could get by asking. Never disable a form's submit button.
• The same rules through every door: what a person can't see in the app, their AI can't read either, and the agent's error says why in the same words.
• In tables the first column names the row; active filters and hidden columns show. Bulk actions: checkboxes with an all/none/some header box, a bar with the selected count, and the spec says whether "select all" means the page or every match.
• Consistency over novelty: reuse the product's components and words for the same thing.

Self-review

Nielsen's ten heuristics:

1. People always see what is happening.
2. The people's words, not ours.
3. A clear way out and back.
4. One word and one pattern for one thing.
5. Errors prevented before they are confirmed.
6. Options visible, nothing to remember.
7. Shortcuts for frequent work.
8. Nothing on screen that is rarely needed.
9. Errors say what happened and the fix.
10. No help needed, or help close by.

Then the checks this skill adds:

11. Each element traces to a job; the spec says what the feature is not for.
12. The most frequent path is the shortest, and the time to value is counted.
13. Every door reaches the same result by the same rules; the agent's answers and errors name the next step.
14. Anything the product's AI suggests or does says why, can be dismissed or corrected in one step, and never acts alone where the person expects to decide (see ai-and-agents.md).
15. Every row of the edge-case checklist that applies has an answer.

Sources

Teresa Torres on opportunity solution trees, assumption testing and the five kinds of assumptions (producttalk.org/opportunity-solution-trees, producttalk.org/assumption-testing, producttalk.org/five-types-of-assumptions); NN/g on cognitive walkthroughs, testing with five users, and user flows vs journey maps (nngroup.com/articles/cognitive-walkthroughs, /why-you-only-need-to-test-with-5-users, /user-journeys-vs-user-flows, /ux-mapping-cheat-sheet); Intercom on job stories (intercom.com/blog/using-job-stories-design-features-ui-ux); Christensen Institute (christenseninstitute.org/jobs-to-be-done); Strategyn outcome statements (strategyn.com/jobs-to-be-done/customer-needs); NN/g on progressive disclosure, task analysis, user flows, journey maps and service blueprints, empty states, response times, confirmation dialogs, error messages, data tables and the ten heuristics (nngroup.com/articles); GitLab Pajamas destructive actions (design.gitlab.com/patterns/destructive-actions); Cloudscape delete patterns and disabled states (cloudscape.design/patterns); Carbon modal accessibility, overflow content and data tables (carbondesignsystem.com); Primer loading and degraded experiences (primer.style/product/ui-patterns); Polaris toast (polaris.shopify.com); GOV.UK error messages, notification banners and design principles (design-system.service.gov.uk); Hurff's UI stack (scotthurff.com); Raskin, "Never use a warning when you mean undo" (alistapart.com/article/neveruseawarning); Smashing Magazine on dangerous actions and hidden vs disabled (smashingmagazine.com); Inclusive Components (inclusive-components.design); W3C WCAG 2.2 Understanding pages and the APG dialog pattern (w3.org/WAI).

The spec's shape

Plain words, short sentences, tables over prose. The title is the first heading. Name project people the way the project does (by member id where it uses them) and users by role. Keep every section as short as the feature allows.

# UX: <feature>

- Status: draft | decided | built
- Asked: <the request, in the person's words>
- For: <who asked> · Spec by: ux-designer · <YYYY-MM-DD>
- Read: <the documents and code paths this rests on>

## The job
<per kind of person or agent: the moment (who, what just happened, how much time, what they fear),
then "When …, I want to …, so I can …"; hypothesis or heard, and from whom; what it is not for>

## Who and how often
| Who | How often | Situation | What matters most |
Frequency verdict: <one or two lines>. Place in the jobs map: <section, if the project keeps one>.

## Today
<what people do now and their words for it; what the product already has to reuse, with paths>

## Journeys
### Main: <name>
Trigger: <the job's "When">
1. <person or agent does> → <product answers>
...
Done when: <what they see>. Steps to value: <n>.
### Other ways in
<each door: the screen, phone, the person's AI, a coding agent, an API, an email link>
### The way back
<undo, restore, correcting a mistake>
### What others see
<teammates, their AIs, notifications, history, lists>

## The experience
<placement and why; components; copy table (where | text); confirmation or undo; feedback; focus;
permissions; for each agent door: the tool's name, input, answer, errors and empty answer;
for each AI suggestion or action: why it shows, dismiss and correct, what it never does alone;
other screens and answers that change; a text wireframe if placement is not obvious>

## Edge cases and states
| Case | What the person or agent sees | Rule |

## Decisions
| | Decision | Options (recommended first) | Consequence | Decided by |
<rows marked Open, Assumed or Settled>

## Acceptance checks
1. Given … when … then …

## Size and later
<small / medium / large; the smallest first version; what is left for later>

What a helper returns

When a helper agent writes the spec for the main session, its last message says:

• the spec's path;
• five lines: the job, the frequency verdict, the main journey in one line, the two or three edge cases that shaped the design, the size;
• the open decisions, each as a question with its options (recommended first) and one line on the consequence of each, ready to ask;
• anything it could not check, and any fact about the code it is unsure of.

Walking a journey

A walk checks a design, or the built feature, the way a person in the job's moment meets it. Do it before building (on the spec, step by step, against the product as it is) to find what the design forgot, and after building (in the running product) to check what shipped. It is a cognitive walkthrough with a score, cheap enough to run on every feature.

How

1. Give the job a person. A role, the moment from the spec (what just happened, how much time they have), and the door they use: the app, a phone, their AI assistant, a coding agent, an email link. Walk each door the feature has as its own run.
2. Walk it as them. Do only what that person would do, knowing only what they would know. At each step ask the four walkthrough questions:
   • Will they try to do the right thing here (do they know this step is needed)?
   • Will they notice the control, command or tool that does it?
   • Will they connect it with what they want to do (the words match theirs)?
   • After it, will they see that it worked and what comes next? A "no" is a finding. For an agent, the questions are the same: will the agent know to call this, will it find the tool among the others, will the name and description match the request, and does the answer tell it what happened and what to do next?
3. Count and score.
   • Steps: each action by the person or their AI (a click, a field, a command, a tool call), from the trigger to the moment they have what they came for.
   • Ease, 1 to 5: 1 stuck, 3 needed thought or a second try, 5 nothing to think about.
   • Match, 1 to 5: how close the result came to the job's outcome. A journey can be easy and still not do the job.
4. Write what held it back, in one line per finding, with where it happened (the screen, the tool's answer, the file and line when it is code).

The scorecard

Then each journey's steps, numbered, with the findings under it, and a short list of the worst findings across the walk, each with the smallest fix.

Rules

• Use a test project or test data; never send invitations, emails or messages to real people during a walk, and never change real records.
• Walk what is there. Mark anything you inferred from the code instead of seeing it run.
• A walk finds what the design forgot; people find what the walk can't. When real people are within reach, test in rounds of five (five find about 85% of the problems; three rounds of five beat one of fifteen; three or four per distinct kind of person), and put what they say above what the walk says.
• For an agent door, the walk is a task evaluation: realistic tasks with a checkable result, run several times, transcripts read (ai-and-agents.md, "Check the agent's journey").