Kwark. Design System
Open Kwark

Elevation

Kwark is flat. Depth is a line and a step in tone; a shadow is only for something that floats above the page, and the layers it floats on are numbered once.

Basics
Scene 11
Scene 12
Scene 13

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.ts works 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 2px and 0 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 and 0 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.

Blank PagesPage · surface · line
Scene 11
Scene 12 raised
Scene 13
inset: 12A · 1 3/8
Scene 12 moved to Act 2
<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.

Do

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.

Don’t

A confirmation opened from the Share dialog uses ConfirmDialog, which is priority="critical", so it appears above the dialog that opened it.

Do

A new dialog that sets style={{ zIndex: 100001 }} to win a fight with another dialog, so the next dialog needs 100002.

Don’t

Rules

  • Must choose a layer by name (--k-z-base, --k-z-high, --k-z-critical, or the Modal’s priority). Never write a z-index above 2000 in new code.
  • Must use --k-shadow-pop for 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: blur as 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

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

Open .mdllms.txt
Loading…