Kwark. Design System
Open Kwark

Spacing

Six steps from 4 to 32, two densities (a desk and a thumb), a 16px phone gutter, and the room a phone page keeps free at its foot.

Basics
space-1 4
space-2 8
space-3 12
space-4 16
space-5 24
space-6 32

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

Outline Menu
Act 2 · 14 scenes
Scene 12
INT. EDIT SUITE – NIGHT
Scene 13
EXT. ROOFTOP – DAWN
Scene 14
INT. MIRA'S FLAT – DAY
--k-fab-slot
<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 uses clamp(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 keeps calc(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.

Do

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.

Don’t

Inside components

  • A card’s padding is --k-space-4 on every side. A dialog’s is --k-space-5.
  • Buttons in a row are --k-space-2 apart, with the primary action last (on the right).
  • A form field’s label sits 6px above the input in the kit (.kw-field); in new work use --k-space-2.
  • Icon and word: --k-space-2 in a button, --k-space-1 in 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.css is 48px, while --k-fab-slot is reckoned for a 46px pen. The slot leaves 14px instead of 16 above it. The slot should be calc(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

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

Open .mdllms.txt
Loading…