Six steps
Every gap, padding and margin in Kwark’s interface is one of six values. A 4px base keeps type, icons and controls on the same grid; six steps are few enough that two people choosing a gap pick the same one.
| Token | Value | Use |
|---|---|---|
--k-space-1 |
4px | Between a crumb and its separator (--k-crumb-gap), between an icon and a tight label in a chip, between a menu’s edge and its first item |
--k-space-2 |
8px | Between an icon and its word in a button (TextButton), between two buttons, between stacked floating items (the dial) |
--k-space-3 |
12px | A row’s inner gap, a chip’s side padding, a menu item’s side padding |
--k-space-4 |
16px | The phone gutter, a card’s padding, a sheet’s side padding, the dial’s distance from the screen edge |
--k-space-5 |
24px | A dialog’s padding, the gap between groups inside a card, the foot of a sheet above the home bar |
--k-space-6 |
32px | Between sections of a page, an empty state’s padding |
Proximity carries meaning. Things that belong together sit closer than things that do not. A scene’s title and its meta line are 2px apart; two scenes are a row apart; Act 1 and Act 2 are a section apart. If every gap is the same, nothing is grouped.
Off the scale, on purpose. Three values outside the six are allowed, and only for these jobs:
- 1px lines and borders.
- 2px insets that exist for the nested radius rule: the segmented control’s track padding, a title-to-meta gap in a row (
.k-row__text). - The paper’s own geometry: the screenplay page, the call sheet and the stripboard are measured in inches and lines, not in this scale (Typography).
Use --k-space-1 to --k-space-6 for every gap, padding and margin in a component. Never write 10px, 14px, 18px or 20px. If a design seems to need one, take the step above or below and say which you chose.
Two densities: a desk and a thumb
The same control is smaller under a mouse than under a finger. Kwark has two sizes for every pressable thing and switches between them with the compact query (see Layout).
| Thing | On a desk | Under a thumb (phone, sideways phone) |
|---|---|---|
IconButton, TextButton |
32px | 44px (--k-tap) |
Chip |
32px | 44px |
| Segmented choice | 30px inside a 2px track | 44px, and its word steps from 12 to 14px |
| Breadcrumb item | 32px (--k-crumb-height) |
No breadcrumb on a phone (Decision 0016) |
| Dropdown menu item | 38px | 44px |
Phone menu row (MenuSheet) |
— | 44px, 56px with a second line |
List row (ListRow) |
56px, 72px with a leading image | 56px; the whole row is the target |
| Editor tool rail button | 34px in a 46px rail | No rail on a phone; its tools are in the ⋯ menu |
The desk density is dense on purpose. Kwark is a working tool, and a writer on a laptop wants to see the scene list, the page and a panel at once. A 44px row on a desk wastes a third of the list.
Never make a desk control smaller than 32px, and never make a thumb target smaller than 44 × 44px, even when the visible part is smaller (a 24px comment pin still has a 44px hit area).
Phones: gutter, header, content, foot
<div style="width:300px;height:520px;display:flex;flex-direction:column;background:var(--k-bg);border:1px solid var(--k-line-strong);border-radius:var(--k-radius-sheet);overflow:hidden;position:relative">
<div style="display:flex;align-items:center;gap:var(--k-space-1);height:var(--k-tap);padding:0 var(--k-space-1);border-bottom:1px solid var(--k-line);flex:none">
<span style="display:grid;place-items:center;width:var(--k-tap);height:var(--k-tap);color:var(--k-text-2)" aria-hidden="true"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m15 18-6-6 6-6"/></svg></span>
<span style="flex:1;font:600 var(--k-fs-title)/1 var(--k-font-display)">Outline</span>
<span style="display:inline-flex;align-items:center;height:var(--k-tap);padding:0 var(--k-space-3);gap:var(--k-space-1);font:500 var(--k-fs-body)/1 var(--k-font-ui)">Menu <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></span>
</div>
<div style="display:flex;align-items:center;gap:var(--k-space-2);height:44px;padding:0 var(--k-space-4);flex:none;font:500 var(--k-fs-meta)/1 var(--k-font-ui);color:var(--k-text-2)">Act 2 · 14 scenes</div>
<div style="flex:1;display:grid;align-content:start;gap:var(--k-space-2);padding:0 var(--k-space-4) var(--k-fab-slot);overflow:hidden">
<div style="padding:var(--k-space-3) var(--k-space-4);background:var(--k-surface);border:1px solid var(--k-line);border-radius:var(--k-radius-card)"><div style="font:600 var(--k-fs-title)/1.25 var(--k-font-display)">Scene 12</div><div style="margin-top:2px;font:400 var(--k-fs-meta)/1.4 var(--k-font-ui);color:var(--k-text-2)">INT. EDIT SUITE – NIGHT</div></div>
<div style="padding:var(--k-space-3) var(--k-space-4);background:var(--k-surface);border:1px solid var(--k-line);border-radius:var(--k-radius-card)"><div style="font:600 var(--k-fs-title)/1.25 var(--k-font-display)">Scene 13</div><div style="margin-top:2px;font:400 var(--k-fs-meta)/1.4 var(--k-font-ui);color:var(--k-text-2)">EXT. ROOFTOP – DAWN</div></div>
<div style="padding:var(--k-space-3) var(--k-space-4);background:var(--k-surface);border:1px solid var(--k-line);border-radius:var(--k-radius-card)"><div style="font:600 var(--k-fs-title)/1.25 var(--k-font-display)">Scene 14</div><div style="margin-top:2px;font:400 var(--k-fs-meta)/1.4 var(--k-font-ui);color:var(--k-text-2)">INT. MIRA'S FLAT – DAY</div></div>
</div>
<div style="position:absolute;left:0;right:0;bottom:0;height:78px;border-top:1px dashed var(--k-line-strong);display:flex;align-items:center;padding-left:var(--k-space-4);font:500 var(--k-fs-meta)/1 var(--k-font-ui);color:var(--k-text-2)">--k-fab-slot</div>
<button class="kw-dial" type="button" aria-label="Comments, quick note and account" style="position:absolute;right:var(--k-space-4);bottom:var(--k-space-4)"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M22 17a2 2 0 0 1-2 2H6.828a2 2 0 0 0-1.414.586l-2.202 2.202A.71.71 0 0 1 2 21.286V5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2z"/><path d="M7 11h10"/><path d="M7 15h6"/><path d="M7 7h8"/></svg></button>
</div>
- Gutter: 16px (
--k-space-4) on both sides. The production office usesclamp(16px, 3.5vw, 40px), so it is 16 on a phone and grows to 40 on a wide desk. - Header: one 44px line. Back, a one-word title, the labelled Menu. Nothing else up there (Decision 0016).
- Content by y ≈ 200 on a 375 × 812 phone. Above the fold, the header plus at most one 40–48px band: a segmented control, one summary line, or one active filter (
docs/design-system.md). Decision 0016 set the goal at y ≈ 120; on 18 October 2026 the Outline measured y ≈ 222 (it had been 392), with the act and view bar still to be folded into the header. - The foot:
--k-fab-slot. Every phone page keepscalc(78px + env(safe-area-inset-bottom))free at its foot so the floating dial never sits on the last row. The 78px is the pen’s 46px, 16px off the edge, and a 16px gap above.
Outline on a phone: one header line, one line that says Act 2 · 14 scenes, then the first card at about y = 100. The last card can scroll clear of the dial because the page keeps --k-fab-slot at its foot.
A two-line header with the story name under the title, then a row of six chips, then a sentence explaining the view, so the first scene starts halfway down the screen and the last one sits under the dial.
Inside components
- A card’s padding is
--k-space-4on every side. A dialog’s is--k-space-5. - Buttons in a row are
--k-space-2apart, with the primary action last (on the right). - A form field’s label sits
6pxabove the input in the kit (.kw-field); in new work use--k-space-2. - Icon and word:
--k-space-2in a button,--k-space-1in a chip. - A list has no gap between rows; rows are separated by a 1px line or by their own padding, never both.
Known differences in the app
- The dial in
components/ui/system.cssis 48px, while--k-fab-slotis reckoned for a 46px pen. The slot leaves 14px instead of 16 above it. The slot should becalc(80px + env(safe-area-inset-bottom))or the dial 46px. - The screenplay timeline and parts of the production office still use 9, 10, 11 and 14px gaps. They move to the scale when those files are touched.
AI readiness test
Task. Lay out the phone version of the Characters list: a header, a search field, and rows for Mira and eleven other characters.
Give the agent. This page, Layout, Typography, the ListRow and PageHeader components.
Constraint. The first row must start by y = 200 on a 375 x 812 screen, and the last row must not sit under the floating dial.
A reliable answer
- One 44px header line with back, Characters, Menu
- Search is the one band above the list, 44px tall
- Rows are 56px with no buttons inside them
- 16px side gutters
- The list ends with --k-fab-slot of padding
- Every gap is a --k-space token