Kwark. Design System
Open Kwark

Onboarding without teaching

Kwark helps people find its own controls when they look for them, through plain names, honest empty states, a sample film and an optional tour, and never teaches them how to write or make a film.

Patterns

The problem

Kwark has a lot in it: a screenplay editor with five rooms, an outline, characters, research boards, a breakdown, shots and boards, a schedule, call sheets, a budget. A new writer needs to find the parts she wants without being walked through the parts she does not. A working director needs none of it explained.

Two habits of software make this worse. One is the tour that opens itself, covers the page with arrows, and has to be dismissed before you can type. The other is the coach: empty fields that ask “What does your hero want more than anything?”, sliders for “tension”, panels that explain what a push-in “means”. Kwark’s founder rejected both. On teaching: “structure is our usp, not teaching them.” On menus full of explanation: “a lazy way to hand out options”.

Kwark’s people are students and part-time professionals. They need working structure and a tool that gets out of the way, not film school.

Kwark’s answer

Two kinds of help, and only one is allowed

Help about Kwark’s own controls Teaching the craft
“Dual dialogue: Two people speaking at the same time” “Use dual dialogue to show tension between characters”
“Fit width: The page as wide as the window” “A wider page helps you see rhythm”
“Writing insights: The character’s card beside a cue… Off by default.” “Track your character’s arc to keep readers engaged”
Allowed Never (Decision 0004)

Help may say what a control does and where its result goes. It never says how to write, what makes a scene good, or what a choice “means”.

Onboarding is the product being clear

Most of what other tools do with onboarding, Kwark does with ordinary design:

  • Plain names. Restore points, not snapshots; Prepare to shoot, not Pre-production; Shots & Boards, not “scene database”. A name that needs explaining is the wrong name.
  • Honest empty states that say where content comes from: “The schedule is built from the screenplay’s scene headings. Write or import the script, and every scene arrives here as a strip.” See Empty states.
  • Hints where a name is not enough, on phones in the Menu sheet: “Keep a restore point: A point inside this draft you can go back to.”
  • Settings rows with a line of meaning: “Finish transitions: The rest of a transition shown faint as it is typed; Tab takes it.”
  • A sample film to look at, not to be walked through (Decision 0035).
  • The first frame, which shows what one script becomes in five real pieces, then gets out of the way. See First run.

Help on demand, in one menu

The screenplay’s Help menu holds three things, and they appear only when asked for:

  • Keyboard shortcuts (⌘/): every key, from the one file that defines them, and the element digits the writer can reassign.
  • What each panel does: one line per panel.
  • Take the tour: “Two minutes round the room, on the room itself.” The tour never opens on its own; the automatic offer was removed (Decision 0015).

Open work, recorded in Decision 0015: the tour has fifteen chapters and is to be cut to five, and the separate “Learn the room” guide is to be removed, because its “How the page reads” heading is exactly the kind of menu-as-lesson the founder rejected.

Structure waits to be chosen

Structure features are off until the writer turns them on, and each is one switch away (Decision 0003). Kwark does not nudge toward them. A writer who only wants to write gets an empty page and a blinking cursor.

Coaching that was removed

These were in Kwark and are gone or going under Decision 0004: the Enneagram quiz, “Engine of…” text, tension sliders, camera “meaning” engines, the Director’s Manifesto’s rhetorical prompts, Idea “Conviction” percentages, Outline “Finder” trophies, and the empty outline card’s story-position questions (removed 4 November 2026; it now says “Add words…”).

Anatomy

Part Where Says
Name Everywhere What it is, in the person’s words
Hint Phone menu rows, Settings rows, field hints What it does or where the value goes
Empty state Any empty module What goes here and where it comes from
Help menu Screenplay, last menu Shortcuts, panels, the optional tour
Tour On request The room itself, briefly; skippable at every step
Sample film First frame, About A real film to look at, read-only

Rules

  • Must explain only Kwark’s own controls, and only where a plain name is not enough.
  • Must keep the tour optional: started only from Help, skippable at every step, never blocking typing.
  • Must say where a value goes, not why it matters to the story.
  • Never open a tour, a coach mark, a tooltip sequence or a “what’s new” dialog on its own.
  • Never put craft questions, prompts or examples of good writing in fields or empty states.
  • Never add a “Learn more” lesson about filmmaking beside a field.
  • Never reward exploring with badges, progress rings or a checklist (“3 of 7 steps done”).
  • Always prefer renaming a control to explaining it.
  • Always keep help in one place per surface (the Help menu, the Settings line), not scattered as popovers.

Edge cases

  • A brand-new feature. Announce nothing. If people need to know, the release notes say it, and the feature’s name and empty state make it findable.
  • A complex tool (the Camera & Light gates and sun). Label each control plainly and give its result a visible place on the page; the skeuomorphic camera gear is the explanation.
  • A writer who asks for teaching. That would be a separate, opt-in place, if the evidence ever came (Decision 0004 names this as what would make us revisit it). It is not built.
  • A phone. Hints replace keyboard shortcuts in the Menu sheet; the tour is the same chapters, sized for one hand.
  • Read-only collaborators. They see the same names and help, minus controls they cannot use; nothing explains a feature they cannot reach.

Phone and desktop

On desktop, help lives in the Help menu and in Settings’ row lines; tooltips name icon buttons. On a phone there are no hover tooltips, so every icon has a word, and the Menu sheet rows carry a one-line hint where needed. The tour on a phone sits at the bottom of the screen, never covering the line being written.

Writing

  • Hints describe the effect: “The running time of the script laid out end to end.”
  • Say “Off by default.” when a feature is off by default, so people know it is a choice.
  • The tour’s voice is the app’s: plain, brief, no exclamation marks, no “Let’s get started”.
  • Tour chapter titles name things: “Every kind of line, by name”, “Every scene, down the side”, “The film, end to end”.

Accessibility

  • Help never depends on hover: every hint is visible text or an accessible description.
  • The tour is a non-modal region; the page stays reachable, focus is not trapped, and Escape ends it.
  • Keyboard shortcuts are listed as text in the sheet, not only drawn as keycaps.

Dual dialogue, hint “Two people speaking at the same time”.

Do

A coach mark that pops up on first use: “Pro tip: dual dialogue creates tension.”

Don’t

An empty outline card that says “Add words…”.

Do

An empty outline card that asks “What does an ordinary day look like before anything changes?”

Don’t

Take the tour in Help, two minutes, skippable.

Do

A tour that opens on first launch and must be finished before the page can be typed on.

Don’t

Demo

Finish transitions
The rest of a transition shown faint as it is typed; Tab takes it.
Writing insights This project
The character's card beside a cue, and the markers on a speech that open what it is doing.
<div class="kw-card" style="width:100%;max-width:480px;display:grid;gap:12px">
<div style="display:flex;justify-content:space-between;gap:12px;align-items:flex-start"><span><strong>Finish transitions</strong><br><span class="kw-row__meta">The rest of a transition shown faint as it is typed; Tab takes it.</span></span><label class="kw-switch"><input type="checkbox" role="switch" checked><span class="kw-track"></span><span class="kw-visually-hidden">Finish transitions</span></label></div>
<div style="display:flex;justify-content:space-between;gap:12px;align-items:flex-start;border-top:1px solid var(--k-line);padding-top:12px"><span><strong>Writing insights</strong> <span class="kw-badge">This project</span><br><span class="kw-row__meta">The character's card beside a cue, and the markers on a speech that open what it is doing.</span></span><label class="kw-switch"><input type="checkbox" role="switch"><span class="kw-track"></span><span class="kw-visually-hidden">Writing insights</span></label></div>
</div>
<div class="kw-sheet" style="width:100%;max-width:360px"><div class="kw-sheet__grip" aria-hidden="true"></div>
<button class="kw-menu-item" type="button" style="height:auto;padding:8px;display:grid;justify-items:start;gap:2px">Keep a restore point<span class="kw-row__meta">A point inside this draft you can go back to</span></button>
<button class="kw-menu-item" type="button" style="height:auto;padding:8px;display:grid;justify-items:start;gap:2px">Dual dialogue<span class="kw-row__meta">Two people speaking at the same time</span></button>
</div>

First run, Empty states, Settings, Menus and shortcuts, Structure, not teaching, Tooltip.

AI readiness test

Task. Writers cannot find the Timeline. Make it discoverable.

Give the agent. This page, Decision 0003, Decision 0015, Menus and shortcuts.

Constraint. No automatic tour, coach mark or nudge.

A reliable answer

  • Checks the name and its home (View › Around the page › Timeline) before adding help
  • Adds or improves a one-line hint (“The running time of the script laid out end to end.”)
  • Adds it to the tour chapters without making the tour automatic
  • Leaves the Timeline off by default and switchable

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…