UX Playbook
Build UI that is correct for the business, easy to use, and consistent. Mantine gives the components; this playbook tells you when to use which, which states a screen needs, and how to check the result. Read only the pages your task needs.
Precedence
When sources disagree, the higher one wins:
- Business requirements: the spec, ticket or owner's instruction. Never change one silently.
- The product's own rules:
AGENTS.md/CLAUDE.md, its UX and design docs, its existing components. - This playbook.
- Mantine's docs and defaults.
If 2 and 3 disagree, follow 2. If you think 2 or 1 is wrong, follow it anyway and raise a UX proposal.
Before UI work, look for the product's UX rules (search the repo docs for "UX", "UI", "design", "panel"). If there are none, draft them with the product brief template and propose the draft in the plan or PR, with every guess labelled [Assumption].
Pick the tier
| Tier | The change | What you do |
|---|---|---|
| S | Small change on an existing screen: a field, a button, a message, a column | Read the page for the component you touch. Run its checklist. Take screenshots if the layout changed. |
| M | A new screen, dialog or form, or a large change to one | Write a short UX spec first. Build it. Do the visual check. Self-review with the rubric. |
| L | A new flow across screens, a new feature area, or a change to navigation | Do a research note with 2–3 options. Build the safe option, A. Then treat each screen as tier M. |
Details and deliverables for each tier: workflow.
Find the page
| You are deciding … | Read |
|---|---|
| Page structure, hierarchy, spacing, responsive layout | decisions/layout |
| Buttons, primary vs secondary, icon buttons, action menus | decisions/actions |
| Modal vs Drawer vs Popover vs inline, tooltips | decisions/overlays |
| App navigation, tabs, breadcrumbs, steppers, pagination, link vs button | decisions/navigation |
| Tables, lists, cards, status labels, dates, long text | decisions/data-display |
| Toasts, alerts, banners, inline messages | decisions/feedback |
| Which input for a choice: checkbox, switch, radio, segmented control, select, combobox, chips | decisions/selection |
| Forms, labels, validation, required fields | patterns/forms |
| Save buttons, autosave, unsaved changes | patterns/saving |
| Nothing to show yet, no results | patterns/empty-states |
| Waiting for data or for work to finish | patterns/loading |
| Advanced options, "show more", details on demand | patterns/progressive-disclosure |
| Introducing a feature, first run, hints | patterns/feature-onboarding |
| Backend down, offline, partial failure, missing permission | patterns/degraded-experiences |
| Delete, reset, revoke, overwrite | flows/destructive-actions |
| Labels, button text, error text, empty-state text | writing |
| Keyboard, focus, labels, contrast, ARIA | accessibility |
| Looking up a Mantine API, theme tokens, versions | mantine |
| The reason behind a rule | principles |
Always
- Use the product's existing components and Mantine before writing your own. Use one component per job.
- Give every data view its loading, empty and error states. Give every action a pending state and a result.
- Keep one primary action per view. Secondary actions are quieter. Rare actions go in a menu.
- An action that is unavailable right now stays visible and says why, in text the user can reach by keyboard and
touch, not only in a tooltip. Prefer an inactive look (
data-disabled) to thedisabledattribute, and never disable a submit button: actions. - Confirm or allow undo for anything that destroys data. Never lose the user's input on an error.
- Every input has a visible label. Meaning is never carried by colour alone. Everything is reachable by keyboard.
- Check the result at phone width and desktop width, in light and dark: visual check.
- Examples here use literal English strings. Use the product's i18n instead.
When you think it could be better
You may, and should, propose better flows and components. The rule is build the safe default, attach the proposal:
- Build what the spec asks for, using the patterns here.
- Add your idea as a UX proposal in the plan or PR, in the fixed format.
- Stop and ask before building only when the spec would lose data, expose a secret, block a user who relies on a keyboard or screen reader, or contradicts itself.
Report
Close every UI task with a UX notes section in the PR or report:
## UX notes
- Tier: M — new "Mods" tab
- States: loading ✓ empty ✓ error ✓ disabled-with-reason ✓
- Screenshots: 1280 light/dark, 390 light/dark (attached)
- Rubric: all pass; n/a: destructive (none)
- Assumptions: [Assumption] mods list is short (< 50), so no pagination
- UX proposals: 1 (see below)