Flat, by rule
Kwark’s surfaces do not glow, blur, lift on hover or cast light. On 15 November 2026 the founder saw a soft accent glow in the corner of a dialog and said to remove that lighting glow everywhere in the app; it was taken out of the Modal and four screens the same day. Three days earlier, Decision 0041 had removed the coloured light layers from the screenplay editor’s rooms and the glow, brightness filter and rising particles from the timeline’s current scene.
The reason is the same both times. A writer spends hours on one screen. Light effects compete with the words, cost contrast, and make the interface louder than the work. The tools Kwark’s writers measure it against (Final Draft, Highland, Fade In) have flat desks.
So depth in Kwark is made of two things only:
- A line.
--k-line, one pixel, where one surface meets another. - A step in tone. The page, then a surface on it, then a raised area on that surface.
Never add a glow, a coloured or blurred shadow, a radial wash, a backdrop blur used as decoration, or a gradient fill to app chrome. Never give a resting card, row or panel a shadow. Depth is --k-line plus a step from --k-bg to --k-surface to --k-raise.
Three tones
| Step | Token | Light | Dark | Is |
|---|---|---|---|---|
| Page | --k-bg |
#f8fafc | #191919 | The page behind everything: the desk |
| Surface | --k-surface |
#ffffff | #1a1a1a | Cards, panels, dialogs, inputs, menus |
| Raised | --k-raise |
#f1f5f9 | #252525 | Hover, the selected row, the pressed segment |
| Inset | --k-inset |
#f1f5f9 | #141414 | Wells sunk into a surface: a code block, a drop zone |
In light the surface is a clear step brighter than the page. In dark the steps are small (#191919, #1a1a1a, #252525), so a surface is set apart mostly by its line, and the raised tone carries hover and selection; a dark interface that brightens sharply toward the viewer reads as lit from the front. Inside the screenplay editor the three steps come from the room (desk, chrome, chrome hover), so the same order holds in Paper or Midnight.
Selection is a tone, not a lift. A selected scene in the list takes --k-raise; it does not grow, cast a shadow or gain a border colour.
What floats
A thing floats when it sits above the page for a moment and goes away: you opened it, and you will close it. Only these carry a shadow.
| Floats | Shadow in the app | Here |
|---|---|---|
| Dropdown and context menus | 0 16px 36px at 55%, 0 2px 6px at 20% (DropdownMenu.css) |
--k-shadow-pop |
| Dialogs on a desktop | The Modal panel has a border and sits on a backdrop of the page at 82% |
--k-shadow-pop |
| Toasts | A large soft shadow (shadow-2xl) |
--k-shadow-pop |
| The phone dial and its items | 0 6px 20px rgba(0,0,0,.35) (components/ui/system.css) |
--k-shadow-pop |
| The timeline loupe while scrubbing | 0 12px 30px rgba(0,0,0,.35) (editor.css) |
--k-shadow-pop |
| The editor’s phone tools menu | 0 16px 48px at 40% |
--k-shadow-pop |
--k-shadow-pop is 0 1px 2px rgba(15,23,42,.06), 0 12px 32px rgba(15,23,42,.12) in light and 0 2px 6px rgba(0,0,0,.2), 0 16px 36px rgba(0,0,0,.55) in dark (the dropdown menu’s own shadow): a tight contact shadow and a soft ambient one, both neutral, never tinted with the accent. The app’s floating things predate the token and each wrote its own; they converge on it as they are touched.
Bottom sheets do not need a shadow. A sheet rises over a backdrop (--overlay-backdrop, the page dimmed), so the backdrop already separates it. The app’s .k-sheet has a border and no shadow.
The page on the desk
One resting thing has a shadow: the screenplay page in the editor, on a desktop. It is paper lying on a desk, and the writer needs to see where the sheet ends.
editorTheme.tsworks the shadow out from the room’s desk colour, so it is never a grey smudge on a coloured desk. In light rooms:0 1px 2pxand0 18px 44px, both the desk colour mixed 70% toward black at 10% and 14% opacity. In dark rooms: a 1px inner highlight at 3% white and0 24px 60px rgba(0,0,0,.45).- The page also has a 1px edge (
--page-edge): the paper colour mixed 9% toward black in light rooms and 7% toward white in dark ones. - On a phone the page is the screen: no edge, no shadow, no corner.
This is not a glow. It falls downward, it is the colour of the desk in shade, and it exists because paper on a desk casts one. The production office’s paper (.po-paper, the call sheet) also sits on its desk with a downward shadow (0 30px 60px -30px #000, 0 2px 5px #0006); it is not yet worked out from the desk colour as the screenplay page’s is.
Layers
Things that float are stacked in a fixed order. Each layer has one number, and a component picks its layer; it never picks a number.
| Layer | z-index | What sits there |
|---|---|---|
| The page | 5 | The screenplay page inside its scroll box |
| Side panels | 20 | The scene list and the editor’s panels |
| Sticky header | 30 | PageHeader on a phone |
| Timeline | 50 | The timeline band and the phone strip |
| Editor menu bar | 100 | File, Edit, View, Tools, Help |
| Timeline bay | 110 | The full-screen sideways edit bay, above the menu bar (Decision 0007) |
| Dial | 320 | The phone’s one floating button |
--ds-z-base / --k-z-base |
500 | Floating controls inside a screen (the focus-mode exit) |
--ds-z-high / --k-z-high |
1000 | Bottom sheets, toasts, combobox lists, the editor’s own dialogs |
--ds-z-critical / --k-z-critical |
2000 | Reserved for what must cover everything the app draws |
The app’s --ds-z-* tokens live in styles/tokens.css; this site’s --k-z-* tokens are the same numbers under the new names.
The Modal’s priority
components/ui/Modal.tsx takes a priority prop: 'base' | 'high' | 'critical', default 'base'.
| Priority | Used for | z-index in the app today |
|---|---|---|
base |
Ordinary dialogs: Scene details, Import | 10000 |
high |
A dialog that may open over another: Sign in, the project form, Create view | 50000 |
critical |
Confirmations and locks that must win: ConfirmDialog, Unlock project |
99999 |
These numbers are far above the --ds-z-* scale; the dropdown menu sits at 60000 and the full-screen loader at 9999. They work, but they are a second scale. The rule for new work is to choose a priority, never a number, so the scale can be brought back to 500 / 1000 / 2000 in one place.
<div style="position:relative;height:280px;background:var(--k-bg);border:1px solid var(--k-line);border-radius:var(--k-radius-card);overflow:hidden">
<div style="position:absolute;inset:16px 16px auto 16px;display:flex;align-items:center;gap:var(--k-space-2);height:44px;padding:0 var(--k-space-3);background:var(--k-surface);border:1px solid var(--k-line);border-radius:var(--k-radius-card);font:600 var(--k-fs-title)/1 var(--k-font-display)">Blank Pages<span style="margin-left:auto;font:500 var(--k-fs-meta)/1 var(--k-font-ui);color:var(--k-text-2)">Page · surface · line</span></div>
<div style="position:absolute;left:16px;top:76px;width:52%;padding:var(--k-space-2);background:var(--k-surface);border:1px solid var(--k-line);border-radius:var(--k-radius-card)">
<div style="display:flex;align-items:center;height:36px;padding:0 var(--k-space-2);border-radius:var(--k-radius-control);font:400 var(--k-fs-body)/1 var(--k-font-ui)">Scene 11</div>
<div style="display:flex;align-items:center;height:36px;padding:0 var(--k-space-2);border-radius:var(--k-radius-control);background:var(--k-raise);font:500 var(--k-fs-body)/1 var(--k-font-ui)">Scene 12 <span style="margin-left:auto;font-size:var(--k-fs-meta);color:var(--k-text-2)">raised</span></div>
<div style="display:flex;align-items:center;height:36px;padding:0 var(--k-space-2);border-radius:var(--k-radius-control);font:400 var(--k-fs-body)/1 var(--k-font-ui)">Scene 13</div>
<div style="margin-top:var(--k-space-2);padding:var(--k-space-2);background:var(--k-inset);border-radius:var(--k-radius-control);font:400 var(--k-fs-meta)/1.4 var(--k-font-mono);color:var(--k-text-2)">inset: 12A · 1 3/8</div>
</div>
<div class="kw-menu" style="position:absolute;right:24px;top:110px;min-width:0;width:38%"><button class="kw-menu-item" type="button">Rename scene</button><button class="kw-menu-item" type="button">Move to Act 2</button><div class="kw-menu-sep"></div><button class="kw-menu-item" type="button" style="color:var(--k-danger)">Delete scene</button></div>
<div class="kw-toast" style="position:absolute;left:50%;bottom:16px;transform:translateX(-50%);white-space:nowrap">Scene 12 moved to Act 2 <button class="kw-text-button" type="button">Undo</button></div>
</div>
Switch to Dark: the order holds. The header and the scene list are flat, separated from the page by a line and a tone. Only the menu and the toast, which you opened and will close, carry --k-shadow-pop.
Do and don’t
A selected scene row in --k-raise with no border change. A context menu with --k-shadow-pop over a flat list. A card that is separated from the page by a 1px --k-line and nothing else.
Cards that lift and gain a shadow on hover. A coloured shadow in the project accent under the primary button. A blurred glass panel over the timeline. A dialog with a soft light in its corner.
A confirmation opened from the Share dialog uses ConfirmDialog, which is priority="critical", so it appears above the dialog that opened it.
A new dialog that sets style={{ zIndex: 100001 }} to win a fight with another dialog, so the next dialog needs 100002.
Rules
- Must choose a layer by name (
--k-z-base,--k-z-high,--k-z-critical, or the Modal’spriority). Never write a z-index above 2000 in new code. - Must use
--k-shadow-popfor anything that floats, and nothing else for a shadow. - Never put a shadow on something at rest. The screenplay page on a desk is the one exception and is drawn by the room, not by a component.
- Always pair a floating surface with a way out: Escape, a Close button, or a tap on the backdrop; and return focus to what opened it.
- Never use
backdrop-filter: bluras decoration. A backdrop is the page dimmed (--k-backdrop), not frosted.
AI readiness test
Task. Add a “Jump to scene” popover that opens from the editor’s menu bar and lists scenes, with a search field at the top.
Give the agent. This page, Radius, the layers table, the editor’s menu bar markup.
Constraint. It must sit above the timeline and the menu bar but below any confirmation dialog, in every room.
A reliable answer
- Popover uses --k-surface, a 1px --k-line border, --k-radius-card and --k-shadow-pop
- Its layer is above the menu bar (100) and below --k-z-high, chosen by token, not a five-digit number
- Rows take --k-raise when selected, no lift
- Escape closes it and focus returns to the menu bar button
- No glow, blur or tinted shadow