Design a screen in Penpot

Generated from docs/how-to/design-a-screen.md. Edit that file in the repository: changes made in the wiki are overwritten.

Every change to what users see starts from a mockup (ADR-0017). This covers website pages, companion windows, WoW addon frames and Discord messages. The design is made in Penpot. Its source, <screen>.penpot, and the SVG rendered from it, <screen>.svg, are kept together in docs/mockups/ and nowhere else (ADR-0018).

One-time setup

1. Create a free account at penpot.app (the Professional plan is free for up to eight members), or use a self-hosted Penpot.
2. Create a team and a project named RaidManager, and invite the people who design or review screens.
3. Keep one Penpot file per screen, named like its future mockup file, for example character-review.
4. Use RaidManager's design system (ADR-0019): the dark palette, Open Sans, and the app shell on every website screen. The shell has a sidebar with the community, the Player and Officer navigation and the signed-in user, and a top bar with the breadcrumb and realm status.

Generate the first version

A screen's first version is generated in the repository, so it arrives in Penpot as a small design system:

• every text is an editable text layer;
• every layer and group has a function-based name;
• the design system's colors and text styles are shared library assets that the layers use;
• the buttons are linked into a clickable prototype.

1. Write scripts/mockups/<screen_name>.py with the scene model in scripts/penpot_scene.py: one board per state (filled, empty, error, dialogs), made of named groups, rectangles, circles and text. Draw each website board with app_screen from scripts/penpot_components.py, which adds the shell, and use its page header, cards, buttons, badges and notices. Take colors from the house palette and link each control to the board it leads to.
2. Run python scripts/mockups/<screen_name>.py. It checks that every color is a named palette color and that text meets WCAG AA contrast, then writes docs/mockups/<screen>.penpot and renders docs/mockups/<screen>.svg from it. Use lowercase words with hyphens for <screen>.
3. Import the .penpot file in Penpot (Import Penpot files on the dashboard) and check it: texts are editable, the Assets panel lists the colors and typographies, and View mode plays each flow.

Design in Penpot

1. Adjust the design in Penpot. Draw each state as a board, side by side in one file.
2. While the design is in progress, open View mode, choose Share, and copy the link into the issue's Mockup field. The issue's needs-mockup label goes away at the next hierarchy audit, which the agent's board report starts (GitHub's own schedule runs it only every few hours).
3. When the design is agreed, choose Download Penpot file (.penpot) from the main menu and save it over docs/mockups/<screen>.penpot. From then on, the downloaded file is the source; don't rerun the screen script.
4. Render its SVG: python scripts/penpot_render.py docs/mockups/<screen>.penpot. Never export or edit the SVG by hand; the docs check fails when the SVG isn't the current rendering of its .penpot file. The renderer draws boards, groups, rectangles, circles and text, and shows anything else as a labeled placeholder.
5. Commit both files together in the pull request of the design task or of the task that implements the screen. Never leave a .penpot or SVG in the repository root or any other folder; the docs check fails on it.
6. Show the committed image in the user story, its UI task and the pull request, for example ![Character review](https://github.com/AnnabiGihed/RaidManager/blob/main/docs/mockups/character-review.svg).

Implement and review

• Show the mockup in the pull request that changes the screen, as an image or a link to docs/mockups/<screen>.svg. The description check fails if a pull request changes user-interface files without one.
• A pull request that changes UI code without changing what users see, such as a refactor or a renamed field, states it on its own line: No visual change: <reason>.
• If the implementation must differ from the design, update the Penpot file and render its SVG again in the same pull request, so the mockup stays the truth.
• To change an existing screen, import docs/mockups/<screen>.penpot into Penpot (Import Penpot files on the dashboard), edit it, download it over the old file, and render its SVG again.

Which items need a mockup

Any epic, feature, story, improvement, bug, task or spike that changes what users see. Answer Yes to the User interface question in the issue form, or add the ui label. The item must then link or show its mockup, and the hierarchy workflow labels it needs-mockup until it does. An epic or feature can show the mockups of its stories in a short list.