Specialization kata · UX-004

Build components from tokens

Turn the repeated parts of your screens into components (buttons, fields, the error summary, the dialog) built from your tokens, so one change updates every screen.

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

Status
Draft
Kata ID
UX-004
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 small component library in Penpot (buttons, fields with and without errors, an error summary, a summary list and a dialog) styled only with your tokens, and high-fidelity screens built from it.

For: Learners with a token file who want screens they can change in one place.

Done when

  • Every repeated part is a main component with a clear name and path, such as Button/Primary
  • Components use library colours and typographies that match your tokens
  • The error summary sits above the heading and lists each error with the same words as the message by the field
  • The high-fidelity screens use copies of the components

You make: Component library. Outcome: Build components.

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

  • Your token file from UX-003. Source: Your own work. Terms: Your work.
  • Error summary pattern. Source: gov-uk/error-summary. Terms: Open Government Licence v3.0; the Dojo credits the pattern and copies no text or code.

Constraints

  • Fictional data
  • No personal data
  • No paid tools

Capabilities practised

  • Design systems
  • 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 the repeated parts across your screens and proposes a component name and the states each needs.

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

  2. Reviewer

    Checks each component against the tokens and the error summary pattern, and lists differences.

    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 03 Tokens and components in the imported file.
Expect
Eight main components, 16 library colours and 5 typographies.
Result
Passed /examples/ux-pathway/penpot-import-check.json (checks components, library-colours and library-typographies)

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.

Find the components

Finds what repeats before you build anything.

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: List the repeated parts and their states with the prompt. Hand-off: You check the list against your screens.
  2. Learner: Build each main component from your library colours and typographies, then rebuild the screens from copies.
  3. Reviewer: Change one main component and check that every copy follows; compare the error summary with the GOV.UK guidance. Hand-off: You fix differences.

Tests, failures and corrections

Checks with expected and recorded results
CheckExpectedResultEvidence
Count main components, library colours and typographies in the example file after import8 components, 16 colours, 5 typographiesPassed on /examples/ux-pathway/penpot-import-check.json (checks components, library-colours and library-typographies)
Change a main component in your file and look at the screensEvery copy changesNot runNot run, so there is no evidence. This is not a pass.

Failures and corrections

No failures have been recorded.

Adapt it

  • Add a second language with longer words. Buttons and fields must grow with their text; test with the longest label before you fix widths.
  • Share the library with another file. Publish the file as a shared library in Penpot and check that a second file can use its components.

Unseen Randori

See the UX Randori recipe.

Constraints

  • Screens built only from components

How it is judged: One change to a main component updates every screen.

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

  • The file has a main component for every repeated part, and the high-fidelity screens use them (Self-check)
  • A partner changes one main component and confirms every copy updates (Peer review)

Belt criteria

  • Practice: Finds the 8 main components on page 03 of the example and where each is used on page 04
  • Adapt: Adds a disabled or loading state to the button component
  • Demonstrate: Builds the components the Randori flow needs and uses them on every screen

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

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

    • Free
    • Docs
    • Beginner

    Penpot explains main components and their copies: change the main component once and every copy follows, with overrides where a copy needs to differ. The basis of a reusable screen library.

  • GOV.UK

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

    • Free
    • Docs
    • Beginner

    The GOV.UK Design System's tested pattern for form errors: a summary at the top of the page that takes focus and links to each field, with the same wording as the message next to the field. Published under the Open Government Licence v3.0.

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