# Menu

> A short list of commands that opens from a button or a right-click. Desktop-grade, with shortcuts.

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

## Usage

### What it is
A short list of commands that opens from a button: the ⋯ on a project, **Menu ▾** on Project home, the breadcrumb’s module switch, and the screenplay’s five menus (File, Edit, Format, View, Help; Decision 0015). The specimen is the project ⋯ menu from Home, as the app draws it.

### Variants
| Variant | Where | Look |
|---|---|---|
| Popover menu | ⋯ on a project, Home’s sort and filters, Project home’s Menu (`DropdownMenu`, `.k-popover`) | 38px rows, 14px icon, 4px 12px |
| App menu | The screenplay menu bar (`.ui-menu`) | 264px wide, 32px rows, shortcuts at the end, accent-tinted hover |
| Breadcrumb menu | Phase and module switch (`.k-crumb-menu`) | Groups with tone dots; see [Breadcrumb](https://kwark.space/designSystem/components/breadcrumb.md) |
| Phone | Every menu on a phone | A [Sheet](https://kwark.space/designSystem/components/sheet.md) that drills down one page at a time |

### Rules for the list
- Group with separators; the destructive item comes last in `--k-danger`, worded as where things go (*Move to trash*).
- An item that opens a dialog ends with an ellipsis: *Export…*, *Settings…*.
- A current choice carries a 14px tick in `--k-accent-soft` (*Last edited ✓* in Home’s sort).
- A not-yet item can be shown with a *Coming soon* badge and does nothing; never hide its row and leave a gap.
- Group headings are sentence case here; the app’s are still upper case with 0.08em tracking.

## Style

### Anatomy

1. **Surface**: `--k-surface`, 1px `--k-line`, 10px corners, 4px padding, at least 200px wide, `--k-shadow-pop` (it floats). The app adds a backdrop blur; the system does not.
2. **Row**: at least 38px (44 under a thumb), 4px 12px, 8px gap, 6px corners, Poppins 500 14px.
3. **Icon**: 14px in `--k-text-2`, `--k-text` on hover.
4. **Hint**: a second line in 12px `--k-text-2` that wraps.
5. **Shortcut**: 12px Poppins 500 in `--k-text-2`, 0.04em, at the row’s end (app menus).
6. **Separator**: 1px `--k-line`, 5px 6px margin.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-danger` | #b4382c | #e0685c |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-radius-card` | 10px |  |
| `--k-radius-control` | 6px |  |
| `--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-fs-body` | 14px |  |
| `--k-fs-meta` | 12px |  |

## Code

### React

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

```tsx
<DropdownMenu label={`Actions for ${project.name}`} trigger={<MoreHorizontal size={16} />} triggerClassName="k-iconbtn" align="right"
  items={[{ label: 'Edit project', icon: Pencil, onClick: edit }, { label: 'Move to trash', icon: Trash2, onClick: trash, danger: true }]} />
```

| Prop | Type | Notes |
|---|---|---|
| `items` | `DropdownItem[]` | { label, icon?, onClick, danger?, selected?, section?, hint?, checkbox?, soon?, action? } |
| `trigger` | `ReactNode` |  |
| `label` | `string` | the menu’s accessible name |
| `align` | `'left' \| 'right'` |  |
| `withinDialog` | `boolean` | keeps the menu in a modal’s top layer |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-menu" role="menu" aria-label="Actions for Untitled Story">
  <button type="button" class="kw-menu-item" role="menuitem"><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="M12 3v12M17 8l-5-5-5 5M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/></svg><span>Upload cover</span></button>
  <button type="button" class="kw-menu-item" role="menuitem"><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="M12 22a1 1 0 0 1 0-20 10 9 0 0 1 10 9 5 5 0 0 1-5 5h-2.2a1.8 1.8 0 0 0-1.3 3.1 1.6 1.6 0 0 1-1.5 2.9z"/><circle cx="13.5" cy="6.5" r=".5"/><circle cx="17.5" cy="10.5" r=".5"/><circle cx="8.5" cy="7.5" r=".5"/></svg><span>Change illustration</span></button>
  <button type="button" class="kw-menu-item" role="menuitem"><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="M7 7h10v10M7 17 17 7"/></svg><span>Open in new tab</span></button>
  <button type="button" class="kw-menu-item" role="menuitem"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M12 20h9M16.5 3.5a2.1 2.1 0 1 1 3 3L7 19l-4 1 1-4z"/></svg><span>Edit project</span></button>
  <button type="button" class="kw-menu-item" role="menuitem"><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="M12 15V3M7 10l5 5 5-5M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/></svg><span>Export project</span></button>
  <button type="button" class="kw-menu-item is-danger" role="menuitem"><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 6h18M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/></svg><span>Move to trash</span></button>
</div>
<div class="kw-menu kw-menu--app" role="menu" aria-label="File">
  <button type="button" class="kw-menu-item" role="menuitem"><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="M15.5 3H5a2 2 0 0 0-2 2v14c0 1.1.9 2 2 2h14a2 2 0 0 0 2-2V8.5L15.5 3Z"/><path d="M15 3v6h6"/></svg><span>Drafts…</span></button>
  <button type="button" class="kw-menu-item" role="menuitem"><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="M4 7V4h16v3M9 20h6M12 4v16"/></svg><span>Title page</span></button>
  <div class="kw-menu-sep" role="separator"></div>
  <button type="button" class="kw-menu-item" role="menuitem"><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 6 9 17l-5-5"/></svg><span>Keep a restore point</span><kbd>⇧⌘S</kbd></button>
  <button type="button" class="kw-menu-item" role="menuitem"><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="M12 15V3M7 10l5 5 5-5M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/></svg><span>Export…</span><kbd>⇧⌘E</kbd></button>
  <div class="kw-menu-sep" role="separator"></div>
  <button type="button" class="kw-menu-item" role="menuitem"><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="12" cy="12" r="3"/><path d="M19.4 15a1.7 1.7 0 0 0 .3 1.8l.1.1a2 2 0 1 1-2.8 2.8l-.1-.1a1.7 1.7 0 0 0-1.8-.3 1.7 1.7 0 0 0-1 1.5V21a2 2 0 1 1-4 0v-.1a1.7 1.7 0 0 0-1.1-1.5 1.7 1.7 0 0 0-1.8.3l-.1.1a2 2 0 1 1-2.8-2.8l.1-.1a1.7 1.7 0 0 0 .3-1.8 1.7 1.7 0 0 0-1.5-1H3a2 2 0 1 1 0-4h.1a1.7 1.7 0 0 0 1.5-1.1 1.7 1.7 0 0 0-.3-1.8l-.1-.1a2 2 0 1 1 2.8-2.8l.1.1a1.7 1.7 0 0 0 1.8.3H9a1.7 1.7 0 0 0 1-1.5V3a2 2 0 1 1 4 0v.1a1.7 1.7 0 0 0 1 1.5 1.7 1.7 0 0 0 1.8-.3l.1-.1a2 2 0 1 1 2.8 2.8l-.1.1a1.7 1.7 0 0 0-.3 1.8V9a1.7 1.7 0 0 0 1.5 1H21a2 2 0 1 1 0 4h-.1a1.7 1.7 0 0 0-1.5 1z"/></svg><span>Settings…</span><kbd>⌘,</kbd></button>
</div>
```

## Accessibility

- `role="menu"` / `menuitem`; arrows move, Enter activates, Escape closes and returns focus to the trigger.
- Type-ahead jumps to the first item starting with that letter.

## For agents

### Rules

- **Must** return focus to the trigger when a menu closes.
- **Must** put destructive items last, after a separator.
- **Always** show keyboard shortcuts in desktop menus.
- **Must** become a Sheet on phones.

### AI readiness test

**Task:** Add a ⋯ menu to a scene card with rename, duplicate, move to act and delete.

**Give the agent:** Menu, Destructive actions pattern, Menus and shortcuts.

**Constraint:** Use the shortcuts listed in the Menus and shortcuts pattern only.

**A reliable answer:**
- Delete last after a separator
- "Move to act…" has an ellipsis
- Escape returns focus
