- Status
- Draft
- Kata ID
- UX-003
- 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 token file in the W3C Design Tokens Community Group draft format that Penpot can import, with core values, semantic aliases and a theme.
For: Learners who have low-fidelity screens and are choosing the visual design.
Done when
- Core tokens hold raw values; semantic tokens only point at core tokens
- Every alias resolves, with no loop
- Text colours reach 4.5:1 and borders and focus rings 3:1 against the surfaces they sit on
- The file imports into Penpot and shows both sets and the theme
You make: Token file. Outcome: Define design tokens.
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.
- 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-tokens.json. Source: The UX pathway page. Terms: Dojo content, MIT licence.
- Design tokens (Penpot user guide). Source: penpot/design-tokens. Terms: Read on the publisher’s site under its terms.
Constraints
- Fictional data
- No personal data
- No paid tools
Capabilities practised
- Design systems
- Test accessibility
Stack, permissions and cost
| Part | Component | Version | Permissions | Cost |
|---|---|---|---|---|
| Tool | Penpot (self-hosted or penpot.app) | 2.18 (the example file was checked on a self-hosted 2.18.7) | Edit one practice project; importing tokens replaces that file’s global token set | Penpot 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. |
| Harness | Any chat assistant in a browser | Not available. Not fixed; any assistant can draft the text, and its version changes the wording, not the checks | Reads only what you paste into it; it never touches the design file | Not available. Depends on your assistant and plan; not measured |
| Instructions | The prompts on this page | Draft, 2026-11-20 | None | None |
| Data | Pocket Invoice, an invented invoicing app | Flow spec of 2026-11-20: 11 states, 19 transitions | Fictional; no real company, person or customer | None |
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
Drafting assistant
Proposes semantic names (text, surface, border, action, focus) and the core value each should point at.
Review gate: You compare every line with the flow and the done-when list before it goes into Penpot.
Reviewer
Computes the contrast of every text and border pair and lists any that fail.
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
- Open Penpot in a browser: sign up at penpot.app, or use your own self-hosted instance.
- Download pocket-invoice.penpot from the UX pathway page and import it (Projects, then Import .penpot).
- 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 the Tokens panel in the imported file.
- Expect
- Two sets, core and semantic, and one theme, Mode / Light, holding 54 tokens.
- Result
- Passed /examples/ux-pathway/penpot-import-check.json (check tokens)
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.
Name the semantic tokens
Separates what a colour is for from what it is.
Practice exercise
Design tokens (Penpot user guide). From Design tokens (Penpot).
Terms: Read on the publisher’s site under its terms.
Execution and handoffs
- Learner: Write core tokens: colours, spacing, radius, border widths, font family, sizes and weights.
- Drafting assistant: Propose semantic aliases with the prompt. Hand-off: You check each alias and the surface it is meant for.
- Reviewer: Compute contrast for every text and border pair. Hand-off: You change any failing core value and check again.
- Learner: Import the file into Penpot and apply the tokens to your screens.
Tests, failures and corrections
| Check | Expected | Result | Evidence |
|---|---|---|---|
| Resolve every alias in the example token file and compute contrast for text and controls | No unknown or circular alias; text 4.5:1 or more and borders 3:1 or more on their surfaces (for example, link on white 5.99:1, input border 4.64:1) | Passed on | /examples/ux-pathway/pocket-invoice-tokens.json, recomputed by the site’s unit tests on every pipeline |
| Import the example token file into Penpot | Sets core and semantic, theme Mode / Light, 54 tokens | Passed on | /examples/ux-pathway/penpot-import-check.json (check tokens) |
| Your own token file passes the same checks | All aliases resolve and every pair passes | Not run | Not run, so there is no evidence. This is not a pass. |
Failures and corrections
No failures have been recorded.
Adapt it
- Add a dark theme. Add a second semantic set or theme; every pair must pass again, because a colour that passes on white can fail on near-black.
- The brand colour is a light yellow. It cannot carry white text; use it for surfaces and pick a darker action colour that passes.
Unseen Randori
See the UX Randori recipe.
Constraints
- Every pair passes contrast
How it is judged: The token file imports and the contrast table has no failure.
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 alias resolves and every text and control colour pair meets its contrast ratio, computed from the token file (Automated check, against Web Content Accessibility Guidelines (WCAG))
- The token file imports into Penpot with its sets and theme (Self-check)
Belt criteria
- Practice: Imports the example tokens into Penpot and explains the difference between the core and semantic sets
- Adapt: Adds a dark theme whose semantic colours still pass contrast
- Demonstrate: Writes a token file for the Randori product from scratch and proves its contrast
Connections
- Used by
- No other kata names this one as a foundation yet.
- Fields
- 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
Penpot
Design tokens (opens the publisher's site in a new tab)
- Free
- Docs
- Beginner
Penpot's guide to design tokens: named values for colour, type, spacing and more, grouped in sets and themes, and imported or exported as JSON in the W3C Design Tokens Community Group draft format. Importing a token file replaces the file's existing global token set.
W3C
How to Meet WCAG (Quickref Reference) (opens the publisher's site in a new tab)
- Free
- Docs
- Intermediate
A filterable checklist of the WCAG 2.2 success criteria with techniques for each. Use it to write testable accessibility checks for your site.
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.
- Penpot imports tokens in the W3C Design Tokens Community Group draft format. The format is a draft and may change.



