Specialization kata · UX-001

Map a sitemap with branches and error states

Map every screen and state of a small SaaS flow, including errors, empty states, a dialog and the way back, before you draw a single screen.

Draft. This recipe is a draft. Its checks may not have been run, and it can change.

Status
Draft
Kata ID
UX-001
Maintainer
UX pathway maintainer
Last verified
Not available. Built and checked by the Dojo maintainers; no independent review yet.
Found a problem?
Report it

The outcome

A sitemap of Pocket Invoice that shows every screen state, every way between them, and how a user recovers from each error.

For: Anyone starting UX work, including people who have never drawn a sitemap.

Done when

  • Every state has at least one way in, and only the start state has none from outside
  • Every error state has a way back to a state the user can complete
  • Empty, error, success and dialog states are drawn, not only the happy path
  • Each arrow is numbered and listed with what causes it

You make: Sitemap. Outcome: Map user flow.

Showcase and provenance

The Dojo’s worked example, made by the maintainers rather than by a learner: Pocket Invoice as an editable Penpot file, a token file and a working, accessible page.

See the showcase

Made by
Developer Dojo maintainers
Source
Generated from the Pocket Invoice flow and tokens with Penpot’s official library
Licence
MIT
Date

Brief, inputs and constraints

Inputs

  • Pocket Invoice flow (11 states, 19 transitions). Source: The UX pathway page and page 01 of pocket-invoice.penpot. Terms: Dojo content, MIT licence.
  • Prototyping in Penpot. Source: penpot/prototyping. Terms: Read on the publisher’s site under its terms.

Constraints

  • Fictional data
  • No personal data
  • No paid tools

Capabilities practised

  • Map flows
  • Design interaction

Stack, permissions and cost

Stack components with version, permissions and cost
PartComponentVersionPermissionsCost
ToolPenpot (self-hosted or penpot.app)2.18 (the example file was checked on a self-hosted 2.18.7)Edit one practice project of your ownPenpot Professional plan: $0, up to 8 members and 10 GB, no file limits (penpot.app/pricing, checked 2026-11-20). Self-hosting is free under MPL-2.0; you pay for your own server.
HarnessAny chat assistant in a browserNot available. Not fixed; any assistant can draft the text, and its version changes the wording, not the checksReads only what you paste into it; it never touches the design fileNot available. Depends on your assistant and plan; not measured
InstructionsThe prompts on this pageDraft, 2026-11-20NoneNone
DataPocket Invoice, an invented invoicing appFlow spec of 2026-11-20: 11 states, 19 transitionsFictional; no real company, person or customerNone

Stack recipes

  • Penpot and browser
  • Assistant and browser

Why this stack

Penpot is open source, runs in a browser, can be self-hosted and has a free plan with no file limits, so every learner can open the same editable file. The assistant only drafts text you check; the design work and the checks stay with you.

Alternatives

  • Figma. Widely used. The free Starter plan allows unlimited drafts but is limited elsewhere (for example 20 MCP tool calls a month); Professional seats cost $3 to $16 a month and there is no self-hosting (figma.com/pricing, checked 2026-11-20). The example file is Penpot-only and has not been tried in Figma. Not tested for this recipe.
  • Penpot MCP server with an agent. Lets an agent edit the open page directly, but uses a personal key with no permission scopes. Not run for this pathway: no native write by an agent was verified. Not tested for this recipe.

Agents and review gates

  1. Drafting assistant

    Lists states and transitions for the flow you describe, and flags any state with no way in or out.

    Review gate: You compare every line with the flow and the done-when list before it goes into Penpot.

  2. Reviewer

    Walks the finished sitemap from the start state and lists unreachable states and dead ends.

    Depends on: Drafting assistant

    Review gate: A finding counts only when the reviewer can point to the board, layer or line it is about.

Setup and smoke test

  1. Open Penpot in a browser: sign up at penpot.app, or use your own self-hosted instance.
  2. Download pocket-invoice.penpot from the UX pathway page and import it (Projects, then Import .penpot).
  3. Open each of the four pages once in the workspace before you use View mode, so Penpot lays out the text.

Sign-in and access: Your own Penpot account. The chat assistant needs no access to Penpot.

Smoke test

Do
Open page 01 Sitemap and flow in the imported file.
Expect
One board shows 11 state boxes, numbered arrows and a legend of 19 transitions.
Result
Passed /examples/ux-pathway/penpot-import-check.json (checks import, pages, text-layout-02 and text-layout-04)

Prompts

Copy a prompt into the assistant you use. Replace anything that does not fit your situation, and never paste private or personal data you are not allowed to share.

List the states

Gets a first list of states and transitions you can check against the brief.

You can also select and copy the text.

Walk the sitemap

Has an assistant check your finished table for gaps.

You can also select and copy the text.

Practice exercise

Making prototypes (GOV.UK Service Manual). From Making prototypes (GOV.UK Service Manual).

Terms: Read on the publisher’s site. GOV.UK guidance is published under the Open Government Licence v3.0 unless it says otherwise.

Execution and handoffs

  1. Learner: Read the brief and open page 01 of the example file. Hand-off: Describe your own flow to the drafting assistant.
  2. Drafting assistant: List states and transitions with the first prompt. Hand-off: You check the list and draw the sitemap.
  3. Learner: Draw the sitemap in Penpot: one box per state, one numbered arrow per transition, error paths dashed. Hand-off: The table of transitions goes to the reviewer.
  4. Reviewer: Walk the sitemap with the second prompt and list gaps. Hand-off: You fix each gap and note what changed.

Tests, failures and corrections

Checks with expected and recorded results
CheckExpectedResultEvidence
Every state in the example sitemap is reachable from the start, and every error has a way back11 states, 19 transitions, no unreachable state and no dead endPassed on /examples/ux-pathway/penpot-import-check.json (prototype-walk-02 reaches every transition from the start board)
Your own sitemap passes the same walkNo unreachable state and no dead endNot runNot run, so there is no evidence. This is not a pass.

Failures and corrections

No failures have been recorded.

Adapt it

  • The product becomes a school trip permission form for parents. The flow needs a state for a second parent, and errors must be written for people reading on a phone in a hurry.
  • Users must be able to save and come back later. Add a saved-draft state with its own way in from the list, and decide what happens to an expired draft.

Unseen Randori

See the UX Randori recipe: map an unseen flow with a constraint you learn only after you start.

Constraints

  • Fictional data only
  • Every error state has a way back

How it is judged: A partner walks your sitemap and finds no unreachable state or dead end.

More Randori challenges

Belt evidence

Belt stages are proposed practice stages, not issued credentials. Evidence below is what a reviewer would look for; it is not a record that anyone has shown it.

Evidence a reviewer looks for

  • Every state is reachable from the start and every error state has a way back, checked against the flow table (Self-check)
  • A partner walks the sitemap from the start and names any state they cannot reach or leave (Peer review)

Belt criteria

  • Practice: Reproduces the Pocket Invoice sitemap and finds all 11 states and 19 transitions in the example file
  • Adapt: Adds one new state (for example, a failed sign-in) with its way in and its way out
  • Demonstrate: Maps an unseen flow in the UX Randori with no unreachable or dead-end state

See the belt stages · Prepare a practice review

Connections

Used by
No other kata names this one as a foundation yet.
Professional review
Not required for practice. Real work in a regulated field still follows that field’s rules.

Sources

  • Penpot

    Prototyping (opens the publisher's site in a new tab)

    • Free
    • Docs
    • Beginner

    Penpot explains how to connect boards into interactive user flows and preview them. Use any assistant to propose a flow, build it in your own file, then test the navigation and review the result. The guide is public; editor access and any optional integration depend on your setup and permissions.

Downloads

Plain text files. Read them before you use them; nothing runs when you download one.

Maintenance and caveats

Review cadence: Every six months, or when Penpot changes its file format or token import

  • This recipe is a draft: the example was built and checked by the Dojo maintainers, and no learner has run it yet.
  • Penpot plans, versions and features change; check penpot.app/pricing and help.penpot.app before you rely on a limit.
  • The example file was checked on a self-hosted Penpot 2.18.7. Penpot cloud (penpot.app) was not checked.

All kata recipes · Back to katas