# Command palette

> One field that goes anywhere in the film: type 12 for Scene 12, Mira for the character, p26 for page 26, or the name of any command from the five menus.

Source: https://kwark.space/designSystem/components/command-palette

## Usage

### What it is
A dialog opened with ⌘K (Ctrl K elsewhere) from anywhere inside a project. One field, one list, keyboard first. It is a shortcut, not a second home: every command it offers is already in one of the five menus (File, Edit, Format, View, Help; Decision 0015), with the same name and the same shortcut.

### The Kwark idea: it knows the film
A generic palette searches command names. Kwark's understands how filmmakers already point at things:

| Type | Finds | Example result |
|---|---|---|
| `12` or `#12` | Scene 12, then 12A, 12B on a locked script | **12** INT. EDIT SUITE – NIGHT · Act 2 · page 26 · 2 4/8 |
| `Mira` or `@mi` | The character, then scenes where they speak | **Mira Rao** · Lead · 41 scenes · first in Scene 2 |
| `p26` | The page, with its revision colour | **Page 26** · Blue revision |
| `Day 7` | The shooting day and its call sheet | **Day 7 of 24** · Thursday 20 Nov · call 06:30 |
| `>restore` | Commands only | **Keep a restore point** ⇧⌘S |

Results show where the thing lives (act, page, length in eighths), so the writer knows they are going to the right Scene 12 before they press Enter. Scene headings are in Courier Prime because they are screenplay text.

### When to use
- Inside a project, on a desk, for people who know what they want.

### When not to use
- As the only way to reach something. The menus and the breadcrumb are the permanent routes.
- On a phone: there is no keyboard shortcut to open it. The Places sheet from the title (Decision 0016) does the same job by touch.
- To search inside the text of the script: that is Find (⌘F), which highlights matches on the page.

### Permissions
Commands a person cannot use are shown, not hidden, when hiding them would leave people guessing: *Issue call sheet for Day 7 · Needs Production access · ask Aanya*. They cannot be run (Decision 0042).

### Empty result
Say what exists, never *No results*: *Blank Pages ends at Scene 96. Try a number up to 96, a character’s name, or a page such as p26.*

## Style

### Anatomy

1. **Surface**: up to 640px wide, at most 560px tall, `--k-surface`, 1px `--k-line`, 14px corners, `--k-shadow-pop`; 20vh from the top over a flat `--k-backdrop`.
2. **Field**: 52px row, 16px search glyph, Poppins 400 16px, and a pill naming the project it searches (*Blank Pages*).
3. **Filters**: 28px pills, *All · Scenes # · Characters @ · Pages p · Commands >*; the prefix key is shown in 11px.
4. **Group heading**: Poppins 500 12px in `--k-text-2`, sentence case.
5. **Result**: at least 44px, a 36px lead column, title and one meta line, a trail.
   - Scene lead: the scene number in a 26px box, Courier Prime 700, as in the margin of the page.
   - Page lead: a 20 × 26 page with a 5px band in its revision colour.
   - Character lead: their [avatar](https://kwark.space/designSystem/components/avatar.md) in their colour.
   - Command lead: a 16px icon on a bordered tile; trail is its shortcut.
6. **Active result**: `--k-raise` and a 2px inset line of `--k-accent-soft` on the left; the ↵ glyph shows only here.
7. **Match**: `<mark>` at 38% `--k-accent-soft`, 2px corners.
8. **Foot**: keys for Move, Open, Close, and the result count in tabular figures. Hidden on phones.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-bg` | #f8fafc | #191919 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-line-strong` | var(--k-text-2) | var(--k-text-2) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-revision-white` | #ffffff |  |
| `--k-revision-blue` | #d6e4f0 |  |
| `--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-radius-sheet` | 14px |  |
| `--k-radius-control` | 6px |  |
| `--k-tap` | 44px |  |
| `--k-fs-title` | 16px |  |
| `--k-fs-body` | 14px |  |
| `--k-fs-meta` | 12px |  |
| `--k-font-screenplay` | 'Courier Prime', 'Courier New', monospace |  |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-cmdk" role="dialog" aria-modal="true" aria-label="Go to anything in Blank Pages">
  <div class="kw-cmdk__search"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="11" cy="11" r="7.5"/><path d="m20.5 20.5-4-4"/></svg><input type="text" value="mi" aria-label="Go to a scene, character, page or command" autocomplete="off"><span class="kw-cmdk__where">Blank Pages</span></div>
  <div class="kw-cmdk__filters" role="group" aria-label="Look in">
    <button type="button" aria-pressed="true">All</button>
    <button type="button" aria-pressed="false">Scenes <kbd>#</kbd></button>
    <button type="button" aria-pressed="false">Characters <kbd>@</kbd></button>
    <button type="button" aria-pressed="false">Pages <kbd>p</kbd></button>
    <button type="button" aria-pressed="false">Commands <kbd>&gt;</kbd></button>
  </div>
  <div class="kw-cmdk__list" role="listbox" aria-label="Results">
    <p class="kw-cmdk__group" role="presentation">Characters</p>
    <div class="kw-cmdk__item" role="option" aria-selected="true"><span class="kw-cmdk__lead"><span class="kw-avatar kw-avatar--sm" style="--kw-peer:var(--k-series-1)">MR</span></span><span class="kw-cmdk__text"><span class="kw-cmdk__title"><mark>Mi</mark>ra Rao</span><span class="kw-cmdk__meta">Lead · 41 scenes · first in Scene 2</span></span><span class="kw-cmdk__trail kw-cmdk__enter"><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 4v7a4 4 0 0 1-4 4H4"/><path d="m9 10-5 5 5 5"/></svg></span></div>
    <p class="kw-cmdk__group" role="presentation">Scenes</p>
    <div class="kw-cmdk__item" role="option" aria-selected="false"><span class="kw-cmdk__lead"><span class="kw-cmdk__scene">12</span></span><span class="kw-cmdk__text"><span class="kw-cmdk__title kw-cmdk__title--script">INT. EDIT SUITE – NIGHT</span><span class="kw-cmdk__meta"><mark>Mi</mark>ra finds the splice · page 26 · 2 4/8</span></span><span class="kw-cmdk__trail kw-cmdk__enter"><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 4v7a4 4 0 0 1-4 4H4"/><path d="m9 10-5 5 5 5"/></svg></span></div>
    <div class="kw-cmdk__item" role="option" aria-selected="false"><span class="kw-cmdk__lead"><span class="kw-cmdk__page" style="--kw-rev:var(--k-revision-blue)"></span></span><span class="kw-cmdk__text"><span class="kw-cmdk__title">Page 26</span><span class="kw-cmdk__meta">Blue revision · <mark>MI</mark>RA (V.O.) on this page</span></span><span class="kw-cmdk__trail kw-cmdk__enter"><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 4v7a4 4 0 0 1-4 4H4"/><path d="m9 10-5 5 5 5"/></svg></span></div>
    <p class="kw-cmdk__group" role="presentation">Commands</p>
    <div class="kw-cmdk__item" role="option" aria-selected="false"><span class="kw-cmdk__lead kw-cmdk__lead--tile"><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="M3 12a9 9 0 1 0 3-6.7L3 8"/><path d="M3 3v5h5M12 7v5l3 2"/></svg></span><span class="kw-cmdk__text"><span class="kw-cmdk__title">Keep a restore point</span><span class="kw-cmdk__meta">File</span></span><span class="kw-cmdk__trail"><kbd class="kw-keycap kw-keycap--sm">⇧⌘S</kbd></span></div>
    <div class="kw-cmdk__item" role="option" aria-selected="false" aria-disabled="true"><span class="kw-cmdk__lead kw-cmdk__lead--tile"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="17" rx="2"/><path d="M8 2v4M16 2v4M3 10h18M8 15h4"/></svg></span><span class="kw-cmdk__text"><span class="kw-cmdk__title">Issue call sheet for Day 7</span><span class="kw-cmdk__meta"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="4" y="11" width="16" height="10" rx="2"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg>Needs Production access · ask Aanya</span></span><span class="kw-cmdk__trail"></span></div>
  </div>
  <div class="kw-cmdk__foot"><span><kbd class="kw-keycap kw-keycap--sm">↑</kbd><kbd class="kw-keycap kw-keycap--sm">↓</kbd> Move</span><span><kbd class="kw-keycap kw-keycap--sm">↵</kbd> Open</span><span><kbd class="kw-keycap kw-keycap--sm">Esc</kbd> Close</span><span class="kw-cmdk__count">5 results</span></div>
</div>
<div class="kw-cmdk" role="dialog" aria-modal="true" aria-label="Go to anything in Blank Pages, no results">
  <div class="kw-cmdk__search"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="11" cy="11" r="7.5"/><path d="m20.5 20.5-4-4"/></svg><input type="text" value="Scene 140" aria-label="Go to a scene, character, page or command" autocomplete="off"></div>
  <div class="kw-cmdk__empty" role="status"><strong>Blank Pages ends at Scene 96</strong>Try a number up to 96, a character’s name, or a page such as p26.</div>
</div>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| ⌘K / Ctrl K | Opens it from anywhere in a project, except while composing in a text field where ⌘K is taken (it then waits for the field to blur). |
| Typing | Filters; the first result becomes active. |
| ↑ ↓ | Move the active result; focus stays in the field. |
| Enter | Opens the active result and closes the palette. |
| ⌘ Enter | Opens a scene or page in a split view beside the current one. |
| Tab | Moves to the filters and back. |
| Escape | Clears the field; a second Escape closes and returns focus where it was, with the caret where it was. |

### ARIA
- The surface is a modal `role="dialog"` named *Go to anything in Blank Pages*.
- The field is a `combobox` with `aria-controls` pointing at the `listbox` and `aria-activedescendant` on the active option.
- Group headings are `role="presentation"` and the options carry the group in their name: *Scene 12, INT. EDIT SUITE – NIGHT, page 26*.
- The result count is announced politely when it settles, not on every key.
- Disabled commands are `aria-disabled="true"` and say why in their description.

## For agents

### Rules

- **Must** use exactly the command names and shortcuts of the five menus; the palette never has a command the menus lack.
- **Must** understand scene numbers (12, 12A), character names, pages (p26) and shooting days, and show where each result lives (act, page, eighths).
- **Never** move the writer's caret or selection until a result is opened; Escape restores them.
- **Always** show unavailable commands with the reason and who can grant access, instead of hiding them silently.
- **Never** say "No results"; say what exists and what to type.

### AI readiness test

**Task:** Let a writer jump to the scene where Aanya first speaks.

**Give the agent:** This page, Menus and shortcuts pattern, Decision 0015.

**Constraint:** The script is locked and has scenes 12A and 12B.

**A reliable answer:**
- Typing "@aanya" shows the character first, then scenes where she speaks in script order
- Scene results show number, heading in Courier Prime, act, page and eighths
- Enter opens the scene and closes the palette
- Escape returns the caret where it was
