Start from the foundations
Read the Basics once, properly: colour roles, type scale, spacing, radius, elevation, layout, motion and icons. They are short. Almost every argument about a screen is settled by one of them: which surface, which size, how much space, whether it floats.
Then read the three foundations that make Kwark different from a general system:
- Principles: the writer first, private and safe, no judgement of the writing, structure optional, paper and digital as one act. Each has a test you can run on your design.
- Writing rooms: the five rooms a writer chooses for the screenplay editor. Anything you design that can appear inside the editor must work in all five.
- AI and authorship: how machine suggestions are shown and accepted, and what a machine is never allowed to do.
Then components, then patterns
Look for the part before you draw one. The component catalogue shows each part live, with its states, its tokens and the words it uses. If two things look different but do the same job, one of them is wrong.
For anything bigger than a part, read the pattern first. Saving and sync, errors, empty states, phones, menus and shortcuts, destructive actions and sharing by role are already decided. Designing them again from scratch produces a second answer, and the app then has two.
Open the Menu component page, take its geometry and states, and design the new Scene menu inside it.
Draw a fresh dropdown for one screen with its own corner radius, shadow and row height.
The Kwark method: UX before build
Nothing a person will see is built until four things are done and agreed. This is UX before build, and it applies to designers and to agents alike.
- Is it needed? Name the person, the situation and the problem in one sentence, from how they actually work. “A competitor has it” is not a reason; competitors are the floor, not the goal.
- The journey. Walk the whole path: where they come from, what they see at each step, what they do, what can go wrong, how they get back to writing.
- A wireframe, phone first. Draw it at 375 wide, then desktop. Include the empty, loading, error and offline states. Count what competes for attention above the fold.
- Agreement. The product owner confirms the journey and the wireframe. Open questions are asked, never silently defaulted.
Only then build, in small steps. Ask two or three questions, state your calls, and show something: long rounds of discovery questions wear people out.
Write the decision down
Every UI decision gets a record: one numbered file that says the problem, the alternatives, what was chosen, why, what every element on the screen means, and what evidence would make us remove it. See Decision records and the template on Contributing.
Every small thing that carries meaning (a dot, a badge, a count, a colour) also gets a line in the element register: what it means, when it appears and what the person is meant to do about it. A dot with no reason is removed.
Review with screenshots
“It works” is not done. A screen is looked at, not only run.
- Screenshots at 1440, 768 and 375 wide, and 320 for headers. Zoom in. Check alignment, clipping, centring and every state: hover, focus, pressed, checked, disabled.
- Check it in light, dark and the five writing rooms if it can appear in the editor.
- Then a review by someone who did not build it: a UI reviewer for the system (tokens, alignment, labels, contrast) and a UX reviewer for the journey (plain names, nothing lost, shortcuts that are real). See Review and quality.
Handing off
Write the spec so someone can build it without asking a question: parts by component name, values by token, every state, every string, phone and desktop separately, keyboard and accessible names, edge cases. The template is on Handoff; it works for a human engineer and for an agent.
Figma
There is no Kwark Figma library yet. It is planned; see Releases. Until then, design in whatever tool you like and name things by their component and token, so the handoff maps one to one. The live pages here are the reference for how each part looks: they render the real CSS.
Do not trace components from screenshots into a design file and treat that as the source. The source is the component page and kwark.css. A traced copy drifts the first time a value is corrected.
AI readiness test
Task. Plan the design of a new “Scene notes” panel for the screenplay editor, from problem to handoff.
Give the agent. This page, UX before build, Writing rooms, Patterns: phones.
Constraint. No pixels or hex values; name components and tokens. Phone first.
A reliable answer
- Starts with the person and problem in one sentence
- Walks the journey before any layout
- Gives a phone layout and a desktop layout
- Lists empty, loading, error and offline states
- Checks the five writing rooms
- Ends with a decision record and a review with screenshots