Kwark. Design System
Open Kwark

Layout

Where things go on a phone, a sideways phone, a tablet, a desk and a television, decided by one shared compact query, with the screenplay page at the centre of every one.

Basics
Compact
Overlay list
Desk

One question, asked the same way everywhere

Kwark used to ask “how wide is the window?” and got the wrong answer twice. A phone turned on its side is about 900px wide and 400px tall; it was handed the desktop, with a menu bar, the scene list and a shortcut strip over 200 pixels of page. So the question became: is this a phone, in either hand?

// pages/Understanding/EditorModule/hooks/useEditorLayout.ts
export const COMPACT_QUERY = '(max-width: 767px), (pointer: coarse) and (max-height: 520px)';

Compact is a narrow screen, or a touch screen too short for desktop chrome. It is the one definition of “phone” in Kwark:

  • In React, useEditorLayout().compact in the editor and usePhoneHeader() (from PageHeader) everywhere else. Both read COMPACT_QUERY.
  • In CSS, every phone rule uses exactly the same string: @media (max-width: 767px), (pointer: coarse) and (max-height: 520px). components/ui/system.css does this for every shared control. The build fails if a rule in the screenplay module goes back to a bare max-width: 767px; a rule that means upright phones only must say orientation in its query.

For phone layout, use COMPACT_QUERY (useEditorLayout() or usePhoneHeader() in React, the identical media query string in CSS). Never use useBreakpoint().isMobile or a bare max-width: 767px for new phone rules: they miss phones held sideways.

The ranges

Range How it is detected What changes
Compact: upright phones up to 767px, and any touch screen 520px tall or less COMPACT_QUERY One 44px header line, the floating dial, menus as bottom sheets, 44px targets, no breadcrumb, no rail. In the editor: one column, drawers, the writing keys docked, the timeline as a 22px strip
Narrow: up to 1023px OVERLAY_NAV_QUERY, (max-width: 1023px) The scene list comes over the page as a drawer with its own open state, and goes away once a scene is chosen
Middle: 1024–1279px Width Panels sit over the page inside the editor’s workspace (position: absolute), and the page keeps a minimum of 460px
Wide: 1280px and up Width Scene list, page, panel and the tool rail side by side; the page keeps at least 560px; the dial steps left of the rail
Very large: 2400 × 1300 and up Width and height The page opens at Fit page instead of 100%
Any touch ANY_TOUCH_QUERY, (any-pointer: coarse) An iPad with a trackpad or a touch laptop keeps the desk layout but gains touch affordances

hooks/useBreakpoint.ts still reports xs below 640, sm to 767, md (tablet) to 1023, lg to 1279 and xl above; older screens and Modal use its isMobile. It is width only, so it is right for an upright phone and wrong for a sideways one.

Tablets

A tablet upright (768–1023px) is not a phone: it gets the desktop header and menus, the scene list as an overlay drawer, and the page at full width. A tablet on its side (1024px and up) is a desk. Touch is detected separately, so a tablet’s controls stay large enough for a finger where (any-pointer: coarse) is used.

The screenplay at the centre

Every layout in the editor is built around one rule: the page is a page.

  • Width. min(816px, 100% − 32px): a US Letter page at 96 to the inch, or the room available minus a 16px gap either side, whichever is smaller. It never sits flush against the scene list or a panel.
  • Indents follow the page, not the window. The page is a container (container-name: script-page). Below 580px of page width (a full text column is 587px), the indents keep the printed proportions of a full column (Decision 0041). Before that fix, a narrow-page rule fired on every page, and cues sat at 2.08 inches instead of 2.2.
  • On a phone the page is the screen: no border, no corner, no shadow, 16px side padding, 20px at the head.

Zoom: Fit width, Fit page, or a size

The writer chooses how large the page is drawn (utils/pageZoom.ts). The page count never changes with any of it, only what fits on the screen.

Choice What it does
A size 60% to 200%, in steps of 10
Fit width The page as wide as the room, less 64px
Fit page A whole page in the room’s height (its two inch margins and its lines at 16px each), or its width if that is smaller

Fits are held between 50% and 400% and rounded down to the nearest 5%. With nothing chosen yet, a screen of 2400 × 1300 or larger opens at Fit page, because a 4K monitor or a television drew the page at a fifth of the room’s width. The choice is kept on the device, not in the script.

The editor on a desk

FileEditViewToolsHelpmenu bar · z 100
timeline · z 50
Scene list
clamp(180px, 16vw, 260px), resizable
INT. EDIT SUITE – NIGHT

Mira scrubs back. Stops.

MIRA
Play it again.

page · min(816px, 100% − 32px)
Panel
beside the page at 1280px and up; over it below
<div style="display:grid;grid-template-columns:clamp(120px,16%,180px) 1fr 200px 46px;grid-template-rows:36px 24px 1fr;height:340px;background:var(--k-bg);border:1px solid var(--k-line);border-radius:var(--k-radius-card);overflow:hidden;font:500 var(--k-fs-meta)/1.3 var(--k-font-ui);color:var(--k-text-2)">
  <div style="grid-column:1/-1;display:flex;align-items:center;gap:var(--k-space-4);padding:0 var(--k-space-3);background:var(--k-surface);border-bottom:1px solid var(--k-line);color:var(--k-text)">File<span>Edit</span><span>View</span><span>Tools</span><span>Help</span><span style="margin-left:auto;color:var(--k-text-2)">menu bar · z 100</span></div>
  <div style="grid-column:1/-1;display:flex;align-items:center;padding:0 var(--k-space-3);background:var(--k-surface);border-bottom:1px solid var(--k-line)">timeline · z 50</div>
  <div style="padding:var(--k-space-3);background:var(--k-surface);border-right:1px solid var(--k-line)">Scene list<br>clamp(180px, 16vw, 260px), resizable</div>
  <div style="display:flex;justify-content:center;padding:var(--k-space-4);overflow:hidden"><div style="width:min(100%,320px);padding:var(--k-space-4);background:var(--k-surface);border:1px solid var(--k-line);border-radius:4px;font:400 var(--k-fs-meta)/1.3 var(--k-font-screenplay);color:var(--k-text)">INT. EDIT SUITE – NIGHT<br><br>Mira scrubs back. Stops.<br><br><span style="padding-left:11ch">MIRA</span><br><span style="padding-left:5ch">Play it again.</span><br><br><span style="font:500 var(--k-fs-meta)/1.3 var(--k-font-ui);color:var(--k-text-2)">page · min(816px, 100% − 32px)</span></div></div>
  <div style="padding:var(--k-space-3);background:var(--k-surface);border-left:1px solid var(--k-line)">Panel<br>beside the page at 1280px and up; over it below</div>
  <div style="display:grid;align-content:start;justify-items:center;gap:var(--k-space-1);padding-top:var(--k-space-2);background:var(--k-surface);border-left:1px solid var(--k-line)"><span style="width:34px;height:34px;border-radius:var(--k-radius-control);background:var(--k-raise)"></span><span style="width:34px;height:34px;border-radius:var(--k-radius-control)"></span><span style="width:34px;height:34px;border-radius:var(--k-radius-control)"></span></div>
</div>
  • The menu bar holds five menus: File, Edit, View, Tools, Help (Decision 0015). It is the only toolbar on a desk.
  • The tool rail is 46px on the right edge with 34px buttons, shown at 1280px and up. It is the home for the editor’s panels; below 1280px they move into the menus, and on a phone into the ⋯ menu.
  • The scene list is clamp(180px, 16vw, 260px) and the writer can drag it wider. Below 1024px it becomes an overlay.
  • Panels sit beside the page from 1280px; below that they sit over the page inside the workspace, below the menu bar, and the editor root carries data-panel while one is open.
  • The app’s quick note and comments do not float in the editor: they are rail buttons on a desk and ⋯ menu entries on a phone.

The production office

Pre-production modules share one shell (pages/PreProduction/shared/ProductionShell.tsx, ProductionOffice.css):

  • Width: min(1280px, 100%), centred, with gutters of clamp(16px, 3.5vw, 40px). A module that needs more room sets data-wide and gets min(1600px, 100%).
  • Two panes: a module whose work is two panes (the stripboard and its tray) sets data-full and takes the window exactly. The header is what it is, and everything left over belongs to the panes. No arithmetic against a guessed header height.
  • Beside the script: Breakdown, Shots & Boards and Schedule can open as a panel beside the live screenplay. Nothing else in the office can, because nothing else has a page to sit beside. On a phone this choice is not offered.
  • Trail: on a desk, the shared breadcrumb (--k-crumb-*, Decision 0044). On a phone, PageHeader.

Drawers, dialogs and sheets

Surface On a desk Compact
Modal sizes sm, md, lg Centred, 384, 512 or 672px wide, up to 90% of the height A bottom sheet, up to 85–90% of the height
Modal sizes xl, full 896px, or 95% of the window Full screen
Drawer From the right edge, 420px, the full height Full width
Sheet Not used From the foot, up to 560px wide and 88% of the height
Menus Dropdowns, 224–296px wide Bottom sheets that drill down one page at a time

Modal still decides with useBreakpoint().isMobile, so a phone held sideways gets the centred desktop dialog. New dialogs on a phone use Sheet behind COMPACT_QUERY.

Line lengths

  • Interface prose: 60–75 characters (max-width: 70ch is the app’s usual).
  • The script: its format’s measure, never the window’s.
  • Settings and forms: one column of fields up to about 480px; labels above fields, not beside them, so they survive a phone and a translation.
  • The script prints on the paper chosen at export: US Letter or A4, @page sized to it.
  • Production paper (the call sheet, the one-liner) is drawn on screen at up to 900px wide (.po-paper) and prints at its own paper size; on a phone it runs to the screen’s edges.
  • Chrome never prints: the dial, the beat ribbon and editor markers are hidden under @media print. See Print and export.

Rules

  • Must use COMPACT_QUERY for phone layout, in React and in CSS.
  • Must keep the page at min(816px, 100% − 32px) and let the indents follow the page’s container, never the window.
  • Never change desktop layout as part of a phone fix. Phone rules live inside the compact query.
  • Always check a layout at 375 × 812, 320 × 568, a sideways phone (about 844 × 390, touch), 1024, 1280 and 1440.
  • Never let zoom change the page count.

AI readiness test

Task. Add a “Notes” panel to the screenplay editor that a writer opens from the tool rail.

Give the agent. This page, Elevation (layers), Spacing, useEditorLayout.ts.

Constraint. It must work on a 1440 desk, a 1100 laptop, an upright phone and a sideways phone, without changing how the page is measured.

A reliable answer

  • At 1280px and up it sits beside the page and the page keeps at least 560px
  • From 1024 to 1279 it sits over the page inside the workspace, below the menu bar
  • In compact it opens as a sheet from the ⋯ menu, not from a rail
  • Phone detection uses COMPACT_QUERY or useEditorLayout().compact, not isMobile
  • The page width and indents are untouched

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

Open .mdllms.txt
Loading…