# Button group

> A few commands on the same object, joined. On a locked script each one says the scene number it will create.

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

## Usage

### What it is
Two to four buttons that act on the same thing, drawn as one strip so the eye reads them as one set. There are two forms:

| Form | Class | Use |
|---|---|---|
| Joined | `kw-btngroup` | Commands of equal weight on one object: the scene's insert and omit, a frame's duplicate and replace |
| Spaced | `kw-btngroup--spaced` | A dialog or sheet footer with one primary: *Preview*, *Print*, **Issue Rev 3** |

### The Kwark idea: the number it will make
Once a screenplay is locked, Kwark never renumbers (`EditorModule/utils/revision.ts`): a scene added after 12 becomes **12A**, a cut scene keeps its number and says OMITTED. Forty people are holding page 12, and the first AD has scene 46 on a strip. So the insert buttons carry the number they will create in a small tabular tag (*Add after 12A*), and **Omit** is offered instead of delete. On a draft that is not locked, the tags show plain numbers (*31*) and Omit is unavailable with a reason, because a draft simply renumbers.

### When to use
- Two to four related commands, same scope, same weight.
- When the result of each command can be shown in a word or number before it is pressed.

### When not to use
- Choosing a view or mode (*Script · Cards*): that is a [segmented control](https://kwark.space/designSystem/components/segmented-control.md), which shows one choice as on.
- More than four commands: use a [toolbar](https://kwark.space/designSystem/components/toolbar.md) or a [menu](https://kwark.space/designSystem/components/menu.md).
- Mixed scopes (one acts on the scene, one on the act): split them.

### Phone
Under 768px a joined group stacks into full-width rows, each 44px, with the number tag at the right edge. A spaced footer wraps.

**Do:** **Add after** with a *12A* tag on a locked script, and **Omit Scene 12** next to it, so nobody's call sheet changes.

**Don't:** A generic *Add | Delete | More* strip that renumbers every scene after it and breaks the stripboard.

## Style

### Anatomy

1. **Group**: `role="group"` with a name that says the object (*Scene 12 on a locked script*).
2. **Members**: [buttons](https://kwark.space/designSystem/components/button.md) at 36px; joined members share their 1px borders (`margin-left: -1px`); outer corners 8px, inner corners square.
3. **Number tag**: 20px tall, 6px padding, 4px corners, 7% `--k-text` wash, Poppins 600 12px tabular in `--k-text-2`.
4. **Pressed toggle** (only if a member toggles): `--k-surface` ground and a `--k-text-2` border, drawn above its neighbours.
5. **Spaced form**: 8px gaps, each member keeps its own corners; one primary at most, last.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-radius-control` | 6px |  |
| `--k-control-md` | 36px |  |
| `--k-tap` | 44px |  |
| `--k-fs-meta` | 12px |  |

## 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-btngroup" role="group" aria-label="Scene 12 on a locked script">
  <button class="kw-button" type="button" aria-label="Add a scene before Scene 12, numbered 11A"><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>Add before<span class="kw-btngroup__num">11A</span></button>
  <button class="kw-button" type="button" aria-label="Add a scene after Scene 12, numbered 12A"><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>Add after<span class="kw-btngroup__num">12A</span></button>
  <button class="kw-button" type="button">Omit Scene 12</button>
</div>
<div class="kw-btngroup" role="group" aria-label="Scene 30 on a draft">
  <button class="kw-button" 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>Add before<span class="kw-btngroup__num">30</span></button>
  <button class="kw-button" 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>Add after<span class="kw-btngroup__num">31</span></button>
  <button class="kw-button" type="button" aria-disabled="true" title="A draft renumbers itself; Omit is for locked scripts">Omit</button>
</div>
<p class="kw-hint" style="margin:-6px 0 0">On a draft the numbers simply follow on, and Omit waits until the script is locked.</p>
<div class="kw-btngroup kw-btngroup--spaced" role="group" aria-label="Call sheet Rev 2">
  <button class="kw-button kw-button--quiet" type="button">Preview</button>
  <button class="kw-button" 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>Print</button>
  <button class="kw-button kw-button--primary" type="button">Issue Rev 3</button>
</div>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Reaches each member in order. A button group is not a toolbar; no arrow-key model. |
| Enter / Space | Runs the focused command. |

### ARIA
- `role="group"` and an `aria-label` that names the object.
- When the visible label is short (*Add after*), the accessible name says all of it: *Add a scene after Scene 12, numbered 12A*.
- An unavailable member uses `aria-disabled="true"` and stays focusable, so its reason (*A draft renumbers; Omit is for locked scripts*) can be read in a tooltip or hint.
- The focused member's ring is drawn above its neighbours (`z-index: 2`) so it is never clipped.

## For agents

### Rules

- **Must** keep every member acting on the same object, and name that object in the group's aria-label.
- **Never** renumber scenes on a locked script: offer insert with the letter it will take (12A) and Omit, never delete.
- **Must** keep one primary at most, and only in the spaced form.
- **Always** stack a joined group into 44px full-width rows under 768px.
- **Never** use a button group to pick a mode or view; that is a segmented control.

### AI readiness test

**Task:** Add scene actions to the Outline card menu for a locked screenplay.

**Give the agent:** This page, Breadcrumb for scope, revision.ts rules quoted here.

**Constraint:** The script is on its Pink revision; Scene 46 is on tomorrow's call sheet.

**A reliable answer:**
- Insert after 46 shows "46A"
- Omit Scene 46 instead of delete
- No renumbering
- aria-label names Scene 46
- Stacks on phones
