# 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.

Source: https://kwark.space/designSystem/foundations/spacing

## 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](https://kwark.space/designSystem/foundations/radius.md#corners-inside-corners): 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](https://kwark.space/designSystem/foundations/typography.md#the-screenplay-page)).

> **For agents:** 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](https://kwark.space/designSystem/foundations/layout.md)).

| 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

```html
<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.

**Do:** 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.

**Don't:** 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-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
