# Drawer

> A column from the right for the details of what you are working on. Kwark has two: the modal drawer for properties, and the comment dock that keeps the script readable beside it.

Source: https://kwark.space/designSystem/components/drawer

## Usage

### What it is
A full-height column that arrives from the right edge. Kwark draws it in two ways, and they behave differently on purpose:

| Kind | In the app | Behaviour | Use |
|---|---|---|---|
| Modal drawer | `Drawer.tsx` | 420px, a backdrop over the page, focus kept inside, Escape and the backdrop close it | Properties and settings of one thing: a scene's details, a location, an export's options |
| Dock | The comment dock | About 340–380px, no backdrop, the page reflows beside it | Things you read while you keep working: comments on Scene 12, notes, version history |

### The rule that decides
If people need to see the work while they use the panel, it is a dock. Comments are about the words, so the commented words stay visible and highlighted beside them. If the panel is a short task about one thing and they come back to the page when it is done, it is the modal drawer.

### When not to use
- For a question that blocks the work: a [dialog](https://kwark.space/designSystem/components/dialog.md).
- For a few facts about a reference: a [popover](https://kwark.space/designSystem/components/popover.md).
- On a phone: both become a [sheet](https://kwark.space/designSystem/components/sheet.md) from the foot (Decision 0016).

### Moving older code over
`Drawer.tsx` draws the backdrop as `bg-black/60` with a background blur and the panel in `zinc-900`. Kwark's flat rule (no blur, no glow) draws the backdrop as `--k-backdrop` and the panel in `--k-surface`. Use `appearance="story"` for module drawers so the ground and type match the story surface.

## Style

### Anatomy

**Modal drawer (`Drawer.tsx`)**
1. **Panel**: 420px (`w-[420px]`), full height, `--k-surface`, 1px `--k-line` on its left, `--k-shadow-pop` toward the page (it floats).
2. **Head**: 16px 12px 16px 20px (`px-5 py-4`), an 18px icon in `--k-text-2`, the title in Poppins 600 16px, an optional 12px tabular line (*Int. Edit suite – night · page 26*), a 32px close with 8px corners (`p-1.5 rounded-lg`, 18px ×).
3. **Body**: scrolls on its own, 16px 20px. Facts in a two-column list, 96px terms.
4. **Foot**: optional, a 1px line and story-surface buttons, primary last (*Done*).
5. **Backdrop**: `--k-backdrop`, flat; pressing it closes.

**Dock (comment dock)**
1. **Column**: 340px here (up to 380px), no backdrop, no shadow: it sits on the page, not over it.
2. **Threads**: the quoted words in Courier on a 2px `--k-accent-soft` rule, then the comment; the same words are marked on the page.

**Phone**: under 640px both become a sheet: full width, 14px top corners, at most 82% of the height.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-bg` | #f8fafc | #191919 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-backdrop` | rgba(15, 23, 42, 0.45) | rgba(0, 0, 0, .75) |
| `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-radius-sheet` | 14px |  |
| `--k-control-sm` | 32px |  |
| `--k-fs-title` | 16px |  |
| `--k-fs-meta` | 12px |  |

## Code

### React

In the Kwark app: `import Drawer from '@/components/ui/Drawer'`.

```tsx
<Drawer isOpen={open} onClose={close} title="Scene 12" icon={Clapperboard}
  ariaLabel="Scene 12 details" appearance="story">
  <SceneDetails scene={scene} />
</Drawer>
```

| Prop | Type | Notes |
|---|---|---|
| `isOpen` | `boolean` | Renders nothing when false. |
| `onClose` | `() => void` | Called by Escape, the close button and a press on the backdrop. |
| `title` | `string` | Shown as a 16px semibold heading; also the fallback accessible name. |
| `icon` | `LucideIcon` | 18px, before the title. |
| `width` | `string` | Tailwind width class; default 'w-[420px]'. |
| `ariaLabel` | `string` | Name when it differs from the title. |
| `appearance` | `'default' \| 'story'` | 'story' uses the story surface's ground and type. |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-drawer-stage">
  <div class="kw-drawer-stage__page" aria-hidden="true">
    <p>INT. EDIT SUITE – NIGHT</p>
    <p>Mira rewinds. The shot repeats. This time she sees <mark>a figure pass behind the camera</mark>.</p>
    <p class="kw-cue">MIRA</p>
    <p class="kw-dlg">That wasn’t in the dailies.</p>
  </div>
  <div class="kw-drawer-stage__scrim" aria-hidden="true"></div>
  <aside class="kw-sidepanel kw-sidepanel--modal" role="dialog" aria-modal="true" aria-label="Scene 12 details">
    <div class="kw-sidepanel__head"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20.2 6 3 11l-.9-2.4c-.3-1.1.3-2.2 1.3-2.5l13.5-4c1.1-.3 2.2.3 2.5 1.3Z"/><path d="m6.2 5.3 3.1 3.9M12.4 3.4l3.1 4M3 11h18v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2Z"/></svg><div><h2>Scene 12</h2><p>Int. Edit suite – night · page 26</p></div><button class="kw-sidepanel__close" type="button" aria-label="Close panel"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
    <div class="kw-sidepanel__body">
      <dl>
        <dt>Length</dt><dd>2 4/8 pages · about 2:30</dd>
        <dt>Cast</dt><dd>Mira, Aanya · Nana (V.O.)</dd>
        <dt>Shoots</dt><dd>Day 7 of 24 · Thu 20 Nov</dd>
        <dt>Location</dt><dd>Studio 2, Andheri</dd>
        <dt>Props</dt><dd>Splicer, reel 3, Zippo</dd>
      </dl>
    </div>
    <div class="kw-sidepanel__foot"><button class="kw-button kw-button--story" type="button">Open breakdown</button><button class="kw-button kw-button--story kw-button--primary" type="button">Done</button></div>
  </aside>
</div>
<div class="kw-drawer-stage">
  <div class="kw-drawer-stage__page">
    <p>INT. EDIT SUITE – NIGHT</p>
    <p>Mira rewinds. The shot repeats. This time she sees <mark>a figure pass behind the camera</mark>.</p>
    <p class="kw-cue">MIRA</p>
    <p class="kw-dlg">That wasn’t in the dailies.</p>
  </div>
  <aside class="kw-sidepanel kw-sidepanel--dock" aria-label="Comments on Scene 12">
    <div class="kw-sidepanel__head"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg><div><h2>Comments</h2><p>3 open on Scene 12</p></div><button class="kw-sidepanel__close" type="button" aria-label="Close comments"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
    <div class="kw-sidepanel__body">
      <div class="kw-thread"><div class="kw-thread__who"><span class="kw-avatar kw-avatar--sm" style="--kw-peer:var(--k-series-2)">AR</span>Aanya Rao<small>14:05</small></div><span class="kw-thread__quote">a figure pass behind the camera</span>Can we see the splice before she does? Two pages earlier.</div>
      <div class="kw-thread"><div class="kw-thread__who"><span class="kw-avatar kw-avatar--sm" style="--kw-peer:var(--k-series-1)">MR</span>Mira Rao<small>14:12</small></div>Agreed. I will move it to 12A.</div>
    </div>
  </aside>
</div>
```

## Accessibility

### Keyboard
| Key | Modal drawer | Dock |
|---|---|---|
| Opening | Focus moves to the first control inside | Focus moves to the dock's heading; the page keeps its caret |
| Tab | Cycles inside the drawer (focus trap) | Moves between the dock and the page normally |
| Escape | Closes, focus returns to the trigger | Closes, focus returns to the trigger |
| F6 | – | Moves focus between the page and the dock |

### ARIA
- Modal: `role="dialog"`, `aria-modal="true"`, a name from `ariaLabel` or the title; the page behind is inert and scroll is locked (`Drawer.tsx` sets `body { overflow: hidden }`).
- Dock: a landmark (`<aside aria-label="Comments on Scene 12">`), not a dialog.
- The close button is named for what it closes: *Close comments*. `Drawer.tsx`'s *Close panel* should take the title.

## For agents

### Rules

- **Must** use the dock, not the modal drawer, when people need to see the work while using the panel.
- **Never** cover the words a comment is about; the dock reflows the page and marks them.
- **Must** close on Escape and with a visible close button named for what it closes, and return focus to the trigger.
- **Never** blur the backdrop or the panel; use --k-backdrop and --k-surface.
- **Must** become a sheet from the foot on phones.

### AI readiness test

**Task:** Show version history next to the screenplay on desktop.

**Give the agent:** This page, Version history, Collaboration.

**Constraint:** Writers compare an old version with the page while reading it.

**A reliable answer:**
- Uses the dock (non-modal), not Drawer.tsx's modal
- Page stays readable and reflows
- Escape and "Close version history" close it
- Becomes a sheet on phones
