Specialization kata · UX-005

Implement the screens and check accessibility

Build the screens as a working web page from the same flow and tokens, then prove keyboard use, screen reader structure, contrast and reflow with automated checks.

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

Status
Draft
Kata ID
UX-005
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 working, accessible web page for every Pocket Invoice state, built from the same flow and tokens as the Penpot file, with a QA report.

For: Learners who can write some HTML, CSS and JavaScript, or who work with an agent that can.

Done when

  • Every state in the sitemap can be reached in the page with a keyboard only
  • Errors use an error summary that takes focus and links to each field, and the page title starts with Error:
  • The dialog traps focus, closes with Escape and returns focus to the button that opened it
  • axe finds no serious or critical WCAG A or AA issue in any state, and the page reflows at 320 px without sideways scrolling

You make: Prototype, Qa report. Outcome: Implement and qa screens.

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 example page. Source: /examples/pocket-invoice/. Terms: Dojo content, MIT licence.
  • Error summary pattern. Source: gov-uk/error-summary. Terms: Open Government Licence v3.0; pattern credited, no text or code copied.
  • WCAG 2.2 quick reference. Source: w3c/wcag-quickref. Terms: Read on the publisher’s site under its terms.

Constraints

  • Fictional data
  • No personal data
  • No paid tools

Capabilities practised

  • Test accessibility
  • Verify evidence

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)Read the example file; no write needed for this stepPenpot 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

    Writes the page from the flow and tokens, one state at a time.

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

  2. Reviewer

    Runs the automated checks and a keyboard pass, and lists failures by state.

    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 the Pocket Invoice example page in a browser.
  2. Open the downloaded token file next to it.

Sign-in and access: None.

Smoke test

Do
Press Tab from the address bar and submit the empty sign-up form with Enter.
Expect
Focus moves to the error summary, which links to both fields.
Result
Passed /examples/ux-pathway/qa-report.md (row signup-error, both projects)

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.

Implement one state

Builds the page a state at a time, so each can be checked.

You can also select and copy the text.

Practice exercise

Error summary (GOV.UK Design System). From Error summary (GOV.UK).

Terms: Read on the publisher’s site. GOV.UK Design System guidance is published under the Open Government Licence v3.0 unless it says otherwise; the Dojo credits the pattern and copies no text or code.

Execution and handoffs

  1. Drafting assistant: Implement each state with the prompt. Hand-off: You run each state with a keyboard before the next.
  2. Reviewer: Run axe in every state, in light and dark mode, and check reflow at 320 px. Hand-off: You fix each finding and run the checks again.

Tests, failures and corrections

Checks with expected and recorded results
CheckExpectedResultEvidence
Run the site’s browser checks on the example page: every state, axe in light and dark, reflow at 320 px, keyboard and dialog focusNo serious or critical WCAG A or AA issue in any state; no sideways scroll; focus lands as describedPassed on /examples/ux-pathway/qa-report.md (11 of 11 states, desktop and mobile)
Keyboard-only pass of your own pageEvery state reachable; focus always visibleNot runNot run, so there is no evidence. This is not a pass.

Failures and corrections

No failures have been recorded.

Adapt it

  • Implement the screens in a framework (for example React or Svelte). Keep the same states and focus rules; move focus after each state change yourself, because the browser will not.
  • Send the invoice to a real email service. Out of scope for practice: it needs real personal data and a privacy review. Keep the fictional .invalid rule.

Unseen Randori

See the UX Randori recipe.

Constraints

  • No serious or critical axe issue

How it is judged: The QA report shows every state checked.

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

  • axe checks for WCAG A and AA in every state, light and dark, plus reflow at 320 px and keyboard and dialog focus, run in the site pipeline (Automated check, against Web Content Accessibility Guidelines (WCAG))
  • A keyboard-only pass from sign-up to a sent invoice and through every error (Self-check)

Belt criteria

  • Practice: Uses the Pocket Invoice example with a keyboard only and reaches every state
  • Adapt: Changes one token and shows the page and the design changing together
  • Demonstrate: Implements the Randori screens and attaches a QA report with no serious or critical failure

See the belt stages

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.

Standards in scope

  • Web Content Accessibility Guidelines (WCAG), 2.2. Applies to: The practice screens and the Pocket Invoice example only. Review scope: What the listed checks test: axe rules tagged WCAG A and AA, keyboard focus, reflow at 320 px, and text and control contrast computed from the tokens. No conformance claim for any product.

Sources

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