# Split button

> One action you run all the time, joined to the few close variants of it. The left half runs the default; the chevron half opens the formats.

Source: https://kwark.space/designSystem/components/split-button

## Usage

### What it is
Two buttons joined into one object. The left half runs the thing people do nine times in ten, and says exactly what it is: **Export PDF**. The right half is only a chevron; it opens the handful of close variants of the same act (Final Draft, Fountain, Print). A writer who exports every evening never opens the menu. A writer who sends an .fdx to a producer once a month finds it one press away, under the same button.

### The Kwark idea: the label names the format
Generic split buttons change their main label to whatever was picked last, so the same button exports a different file on Tuesday. In Kwark the main half always names its format, and the menu marks the default with a tick and a line that says what will come out: page size, page count, and whether scene numbers print in both margins. Choosing **Final Draft** in the menu runs it once; it does not quietly become the new default. *Export settings…* is the place to change the default, and then the label changes with it (*Export FDX*).

### When to use
- One dominant action with two to five variants of the same act: export formats, issue the call sheet now or schedule it, add a scene or an act.
- In a toolbar or a module head where a second button beside it would compete.

### When not to use
- The variants are different acts (*Export* and *Delete*): use a button and a [menu](https://kwark.space/designSystem/components/menu.md).
- There is no dominant choice: use a [button](https://kwark.space/designSystem/components/button.md) that opens a menu, labelled with a chevron.
- On a phone header: put the variants in the Menu sheet (Decision 0016); the split button stays in page content only.

### States
| State | What changes |
|---|---|
| Rest | One object; the seam between halves is a 1px line, not a gap |
| Hover | Only the half under the pointer steps its tone |
| Pressed / open | The chevron half stays pressed while its menu is open; the chevron turns 180° |
| Focus | Each half takes its own 2px ring, drawn above its neighbour |
| Busy | The quark spinner replaces the main icon, the label counts (*Exporting 48 of 112*), the chevron is disabled |
| Disabled | Both halves at 50%; say why next to it (*Read only: ask Mira for Write access*) |

**Do:** **Export PDF** on the left, a drawn chevron on the right, and a menu where the default carries a tick and *US Letter · 112 pages*.

**Don't:** **Formats ⌄** typed as text, a native disclosure triangle, or a main label that silently becomes whatever was chosen last.

## Style

### Anatomy

1. **Group**: `role="group"` with a name (*Export the screenplay*), 36px tall (28px at `--sm`), 8px outer corners, inner corners square.
2. **Main half**: icon 14px + verb and object, Poppins 500 14px, 14px padding. It never truncates the format; the object may truncate on very narrow screens.
3. **Seam**: secondary halves overlap their 1px borders into one line; on the primary the seam is an inset 1px line of `--k-on-accent` at 30%.
4. **Chevron half**: 34px wide (28px small), a 14px SVG chevron at stroke 2. Never a typed ⌄ or ▾.
5. **Menu**: the shared [menu](https://kwark.space/designSystem/components/menu.md), at least 300px. Rows carry a 14px format icon, the format's name, and a 12px line saying what it makes. The default carries a 14px tick in `--k-accent-soft`. Print and settings sit after a separator and end in an ellipsis.
6. **Busy**: the 14px [spinner](https://kwark.space/designSystem/components/spinner.md) and a tabular count replace the icon; the width is kept so nothing jumps.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-accent` | #98633f | #98633f |
| `--k-on-accent` | #ffffff | #ffffff |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--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-control-md` | 36px |  |
| `--k-fs-body` | 14px |  |
| `--k-fs-meta` | 12px |  |
| `--k-icon-sm` | 14px |  |
| `--k-dur-1` | 120ms |  |
| `--k-dur-2` | 200ms |  |

| Property | Value |
|---|---|
| Height | 36 · 28px |
| Outer radius | 8px (`.ds-btn`), inner 0 |
| Chevron half | 34 · 28px wide, 14px icon |
| Hover | 7% `--k-text` into `--k-raise`; primary brightens 10% |
| Pressed | 11% into `--k-raise`; primary 92% brightness |
| Focus | 2px `--k-accent-soft`, 2px offset, `z-index: 2` |
| Chevron turn | 180° over `--k-dur-2` with `--k-ease` |

## 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-splitbtn-anchor">
  <div class="kw-splitbtn kw-splitbtn--primary" role="group" aria-label="Export the screenplay">
    <button class="kw-splitbtn__main" type="button"><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 PDF</span></button>
    <button class="kw-splitbtn__more" type="button" aria-haspopup="menu" aria-expanded="true" aria-label="More export formats"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button>
  </div>
  <div class="kw-menu kw-formats" role="menu" aria-label="Export formats">
    <div class="kw-menu__group" role="presentation">Export as</div>
    <button class="kw-menu-item" role="menuitemradio" aria-checked="true" type="button"><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 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h6M8 13h8M8 17h5"/></svg><span>Screenplay PDF<small>US Letter · 112 pages · scene numbers both sides</small></span><svg class="kw-menu__check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M20 6 9 17l-5-5"/></svg></button>
    <button class="kw-menu-item" role="menuitemradio" aria-checked="false" type="button"><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 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h6M10 12l-2 2 2 2M14 12l2 2-2 2"/></svg><span>Final Draft<small>.fdx, opens in Final Draft 10 and later</small></span></button>
    <button class="kw-menu-item" role="menuitemradio" aria-checked="false" type="button"><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 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h6M10 12l-2 2 2 2M14 12l2 2-2 2"/></svg><span>Fountain<small>Plain text any screenwriting app can read</small></span></button>
    <div class="kw-menu-sep" role="separator"></div>
    <button class="kw-menu-item" role="menuitem" type="button"><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="M6 9V3h12v6M6 18H4a2 2 0 0 1-2-2v-5a2 2 0 0 1 2-2h16a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2h-2"/><path d="M6 14h12v7H6z"/></svg><span>Print…</span><kbd>⌘P</kbd></button>
    <button class="kw-menu-item" role="menuitem" type="button"><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>Export settings…</span></button>
  </div>
</div>
<div style="display:flex;flex-wrap:wrap;gap:12px;align-items:center">
  <div class="kw-splitbtn" role="group" aria-label="Issue the call sheet">
    <button class="kw-splitbtn__main" type="button"><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>Issue Rev 3</span></button>
    <button class="kw-splitbtn__more" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="More ways to issue the call sheet"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button>
  </div>
  <div class="kw-splitbtn kw-splitbtn--primary" role="group" aria-label="Export the screenplay" aria-busy="true">
    <button class="kw-splitbtn__main" type="button" aria-disabled="true"><svg class="kw-quarks kw-quarks--sm" viewBox="0 0 80 80" aria-hidden="true"><circle cx="24" cy="22" r="14"/><circle cx="58" cy="40" r="11"/><circle cx="38" cy="64" r="10"/></svg><span>Exporting <span class="kw-splitbtn__count">48 of 112</span></span></button>
    <button class="kw-splitbtn__more" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="More export formats" disabled><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button>
  </div>
  <div class="kw-splitbtn kw-splitbtn--sm" role="group" aria-label="Add a beat">
    <button class="kw-splitbtn__main" type="button"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg><span>Add beat</span></button>
    <button class="kw-splitbtn__more" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="More things to add"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button>
  </div>
</div>
```

Opening the menu: the chevron half sets `aria-expanded`, the menu takes focus on its checked row, Escape returns focus to the chevron half. On a phone the menu opens as a [sheet](https://kwark.space/designSystem/components/sheet.md).

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Moves to the main half, then to the chevron half. Two stops, two names. |
| Enter / Space on the main half | Runs the default (*Export PDF*). |
| Enter / Space / ↓ on the chevron | Opens the menu with focus on the checked format. |
| ↑ ↓ | Move through formats; Home and End jump to the ends. |
| Enter | Runs that format once and closes the menu. |
| Escape | Closes the menu and returns focus to the chevron half. |

### ARIA
- The wrapper is `role="group"` with `aria-label` naming the act.
- The chevron half has an accessible name of its own (*More export formats*), `aria-haspopup="menu"` and `aria-expanded`.
- Formats are `menuitemradio` with `aria-checked` on the default; Print and settings are plain `menuitem`.
- While busy, set `aria-busy="true"` on the group, keep the label readable, and announce *Screenplay exported* once in a polite live region.

### Touch
Under a thumb both halves grow to 44px tall and the chevron half to 44px wide. They stay two separate targets.

## For agents

### Rules

- **Must** name the default format in the main half ("Export PDF"), and never change it because someone picked another format once.
- **Must** draw the chevron as an inline SVG in its own button with its own accessible name; never type ⌄ or ▾ or use a native disclosure triangle.
- **Always** mark the default format with a tick and say what it produces (page size, page count) in the row's second line.
- **Never** put a different act (delete, share, rename) in a split button's menu; it holds variants of the main act only.
- **Must** become a Sheet on phones and keep both halves at 44px.

### AI readiness test

**Task:** Put screenplay export in the screenplay's File area with PDF as the default and Final Draft, Fountain and Print as alternatives.

**Give the agent:** This page, Menu, Print and export pattern.

**Constraint:** Some writers have a page size of A4; the default label must stay truthful.

**A reliable answer:**
- Main half reads "Export PDF"
- Chevron half is a separate named button with an SVG chevron
- Default row is ticked and says "A4 · 112 pages"
- Picking Fountain exports once without changing the default
- Print… has ⌘P and sits after a separator
