What counts as a change to the system
- A new component, variant, token or pattern.
- A change to a rule on any page, or to a value in
kwark.css. - A screen in the app that does something the system does not cover yet. That is a gap, and the gap is the contribution.
Fixing a typo or making a page match the app as it already is does not need a proposal. Say what you corrected in the pull request.
Propose
Write the proposal before you design anything final. It answers four questions, and it is short:
- Who needs this, in what situation? One sentence, from how they actually work. “Mira is on set with a phone and needs to mark a take without leaving the call sheet.”
- What happens to them without it? If nothing does, stop.
- What already exists? Name the components and patterns you checked, and why none of them does the job. If two things look different but do the same job, one of them is wrong.
- What would make us remove it? The evidence that would tell us it is not helping.
“A competitor has it” is never the answer to the first question. Competitors set the floor: say what this does that none of them do. See Competitors are the floor.
For anything larger than a part, walk the journey and draw the wireframe at phone size first, then desktop, before you build. See UX before build.
Write the decision record
Every accepted change has a record in docs/ux/decisions/, one numbered file per decision (0046-short-title.md). Take the next free number. This is the template Kwark uses, as it is in the repository:
# NNNN · Title
- **Status:** Accepted | Draft (rationale to confirm) | Under review | Superseded by NNNN | Removed
- **Date:** YYYY-MM-DD
- **Source:** who said or decided this, and where it is recorded (a note, a commit, a doc)
## Problem
Who has it, in what situation, in their own words where we have them.
## Why this needs to exist
What happens to the person if we do nothing.
## Alternatives we considered
At least two, with why each was not chosen.
## Decision
What we built or chose, in plain words.
## Why this is the best solution
Tied to the principles (docs/ux/mission-and-principles.md). Name the principle.
## Every element, and what it means
The screen's parts, including dots, badges, counts and colours (each also in the element register).
## What would make us remove it
The evidence that would tell us this is not helping.
## Open questions and history
Dated one-line notes; what changed and why.
A record starts as Draft and becomes Accepted only when the product owner accepts it. When a decision changes, add a dated line to its history instead of rewriting the past. See Decision records. The kwark-decision-record skill writes one with an agent.
Every control says what it is
This is the rule most often broken, and the one people notice first. Kwark wrote it down after a phone menu shipped as plain text with a bare “⋯”, no icons and no chevrons.
- Must give every control a word, or an icon with a word. Icon-only is for universal glyphs (back, close, more, add, search) and always has an accessible name that includes its object: “Close scene 12”, “More actions for Act 2”.
- Must show a chevron on anything that opens something: ▸ opens a page or a flyout, ▾ opens a dropdown.
- Never label a menu with “⋯” alone in a header. The word is Menu.
- Always use the shared component (
Button,IconButton,TextButton,Sheet,ListRow) so the label, the size and the focus ring come with it.
Review
A change is not done when it works. It is done when it has been looked at, reviewed by someone who did not build it, and fixed.
- Built from the system. Shared components; tokens only; icons at 14, 16 or 20; 44px tap targets on phones.
- Looked at. Screenshots at 1440, 768 and 375 wide, and 320 for headers, zoomed in. Alignment, clipping, centring, and every state: hover, focus, checked, disabled. Light, dark and the writing rooms where it applies.
- Two reviewers, review-only. A UI reviewer checks system use, alignment, spacing, icons, labels, contrast in every room and clipping. A UX reviewer walks the person’s journeys: plain names, one home for each command, nothing lost from the old design, shortcuts that really work. Other reviewers join when the change touches them: security for anything about sharing or data, a producer for anything that leaves the script, an engineer for types, tests and performance.
- Fixed, then re-checked by the same reviewer. A finding is never dismissed without a written reason in the decision record.
- Recorded. Decision record updated, element register updated for any new dot, badge, count or colour, tests and build green.
At Kwark the reviewers are separate agents running on the strongest model available (Opus), with review-only instructions, and creative work (look, wording, layout) is done or reviewed at that level rather than left to a cheaper default. A human reviewer is just as good. What matters is that the reviewer did not build it and is not allowed to fix it themselves.
The kwark-ux-review skill sets an agent up as a review-only supervisor with this checklist.
Pull requests to the system itself
- Prose pages are in
design-system/content/, components indesign-system/components*.mjs, styles indesign-system/css/. - Component CSS uses only
--k-*tokens andkw-classes. A new token goes in:rootwith a comment, and a light and a dark value taken from the app. - Run
node design-system/build.mjsand check the page and its.mdtwin. - Every foundation, pattern, kit and component page ends with an AI readiness test. Add one for anything new. See Readiness tests.
AI readiness test
Task. Propose a new “Take marker” component for marking takes from the call sheet on a phone, and write its decision record.
Give the agent. This page, Decision records, components.json, Patterns: phones.
Constraint. Check existing components first and name them. Leave the status as Draft.
A reliable answer
- Names the person and situation in one sentence
- Lists the components checked and why none fits
- Gives at least two alternatives with reasons
- Fills every section of the template
- Says what would make us remove it
- Every control has a word or a named icon