# Toolbar

> The tools for one surface in one line, laid out like an edit bay: what is selected, the transport, the timecode, the tools, then everything else under a word.

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

## Usage

### What it is
One line of tools that belong to one working surface: the animatic, the storyboard, the timeline, the shot planner. Project-wide actions (share, export, settings) are not here; they stay in the top bar and the five menus (Decision 0015).

### The Kwark idea: an edit bay, read left to right
An editor's eye goes to the same places every time: what is selected, where the playhead is, which tool is in hand. Kwark's toolbars keep that order on every surface:

1. **Scope**: what the tools will act on, in words and figures (*Shot 12A · Mid · 3s 12f · 4 of 9*). If nothing is selected it says so (*No shot selected*), and the tools that need a selection are disabled.
2. **Transport**: previous frame, play, next frame. Play is the one filled control.
3. **Timecode**: hours, minutes, seconds and frames in tabular figures on an inset well, frames in the quiet colour. It never jitters in width while playing.
4. **Tools**: modes that stay on (*Select*, *Trim*, *Split*), each an icon and a word; the one in hand is lit with the accent's light.
5. **Commands**: one-off actions (*Add frame*, *Fit*) after a spacer.
6. **More**: when the bar is narrower than 780px, the commands and the least-used tool fold into **More ▾**. Scope, transport and timecode never fold.

### When to use
- A surface with its own tools that are used again and again while the work is on screen.

### When not to use
- For two or three related commands: a [button group](https://kwark.space/designSystem/components/button-group.md).
- For project actions: the [top bar](https://kwark.space/designSystem/components/top-bar.md) and menus.
- Floating over the work on a phone: the phone gets one floating control only (Decision 0016); the toolbar stays docked.

### Phone
At 375px the bar keeps scope (*12A*), Play, the timecode (*01:24:06*), the tool in hand and **More ▾**. Every target is 44px.

**Do:** *Shot 12A · 3s 12f*, then transport, then *00:01:24:06* in tabular figures, then **Select** lit and **Trim** beside it, each with a word.

**Don't:** A row of twelve unlabelled icons with the selection nowhere on screen, and a timecode that shifts width every frame.

## Style

### Anatomy

1. **Bar**: at least 44px, 4px 8px padding, `--k-surface`, 1px `--k-line`, 10px corners. Flat: it is docked, so no shadow.
2. **Scope**: Poppins 600 12px name, 11px tabular meta in `--k-text-2`; truncates first.
3. **Tool**: 32px tall (44px under a thumb), 32px minimum width, 8px padding, 6px corners, 16px icon, 12px word, `--k-text-2` at rest.
4. **Play**: 32px circle in `--k-text` with a `--k-bg` glyph.
5. **Pressed tool**: 20% `--k-accent-soft` wash and a 1px inset ring of it at 60%; text goes to `--k-text`.
6. **Timecode**: 32px well in `--k-inset`, 1px line, Poppins 500 14px, tabular, 0.03em tracking; `:ff` in `--k-text-2`.
7. **Separator**: 1px `--k-line`, 6px from top and bottom.
8. **Overflow**: a container query at 780px hides `.kw-toolbar__wide` and shows **More ▾**; at 420px the frame steps, separators and the tools not in hand move into More too.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-inset` | #f1f5f9 | #141414 |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-bg` | #f8fafc | #191919 |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-radius-card` | 10px |  |
| `--k-radius-control` | 6px |  |
| `--k-control-sm` | 32px |  |
| `--k-tap` | 44px |  |
| `--k-fs-body` | 14px |  |
| `--k-fs-meta` | 12px |  |
| `--k-fs-dense` | 11px |  |
| `--k-icon-md` | 16px |  |

## 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-toolbar">
  <div class="kw-toolbar__bar" role="toolbar" aria-label="Animatic for Scene 12">
    <div class="kw-toolbar__scope"><strong>Shot 12A</strong><span>Mid · 3s 12f · 4 of 9</span></div>
    <span class="kw-toolbar__sep" aria-hidden="true"></span>
    <div class="kw-toolbar__group">
      <button class="kw-tool kw-tool--step" type="button" aria-label="Previous frame"><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="M5 5v14M19 6l-9 6 9 6z"/></svg></button>
      <button class="kw-tool kw-tool--play" type="button" aria-label="Play"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M7 4.5v15a1 1 0 0 0 1.5.86l12-7.5a1 1 0 0 0 0-1.72l-12-7.5A1 1 0 0 0 7 4.5Z"/></svg></button>
      <button class="kw-tool kw-tool--step" type="button" aria-label="Next frame"><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="M19 5v14M5 6l9 6-9 6z"/></svg></button>
    </div>
    <span class="kw-timecode" role="timer" aria-label="Timecode 1 minute 24 seconds 6 frames">00:01:24<span class="kw-timecode__ff">:06</span></span>
    <span class="kw-toolbar__sep" aria-hidden="true"></span>
    <div class="kw-toolbar__group" role="group" aria-label="Tool">
      <button class="kw-tool" type="button" aria-pressed="true"><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 4 7 17 2.5-7.5L21 11z"/></svg>Select</button>
      <button class="kw-tool" type="button" aria-pressed="false"><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="M8 4v16M16 4v16M8 12H4M20 12h-4"/></svg>Trim</button>
      <button class="kw-tool kw-toolbar__wide" type="button" aria-pressed="false"><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="6" cy="6" r="3"/><circle cx="6" cy="18" r="3"/><path d="M20 4 8.1 15.9M14.5 14.5 20 20M8.1 8.1 12 12"/></svg>Split</button>
    </div>
    <span class="kw-toolbar__spacer"></span>
    <div class="kw-toolbar__group kw-toolbar__wide">
      <button class="kw-tool" 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="5" width="18" height="14" rx="2"/><path d="M3 9h18"/></svg>Add frame</button>
      <button class="kw-tool" type="button" aria-haspopup="menu" aria-expanded="false"><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-4M8 11h6M11 8v6"/></svg>Fit<svg class="kw-tool__chev" 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>
    <button class="kw-tool kw-tool--more" type="button" aria-haspopup="menu" aria-expanded="false">More<svg class="kw-tool__chev" 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>
<div class="kw-toolbar" style="max-width:375px">
  <div class="kw-toolbar__bar" role="toolbar" aria-label="Animatic for Scene 12, compact">
    <div class="kw-toolbar__scope"><strong>12A</strong><span>3s 12f</span></div>
    <div class="kw-toolbar__group">
      <button class="kw-tool kw-tool--play" type="button" aria-label="Play"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M7 4.5v15a1 1 0 0 0 1.5.86l12-7.5a1 1 0 0 0 0-1.72l-12-7.5A1 1 0 0 0 7 4.5Z"/></svg></button>
    </div>
    <span class="kw-timecode" role="timer" aria-label="Timecode 1 minute 24 seconds 6 frames">01:24<span class="kw-timecode__ff">:06</span></span>
    <span class="kw-toolbar__spacer"></span>
    <button class="kw-tool" type="button" aria-pressed="true"><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 4 7 17 2.5-7.5L21 11z"/></svg>Select</button>
    <button class="kw-tool" type="button" aria-haspopup="menu" aria-expanded="false">More<svg class="kw-tool__chev" 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>
```

## Accessibility

### Keyboard (the ARIA toolbar pattern)
| Key | Does |
|---|---|
| Tab | Enters the toolbar on the last-used control, and leaves it in one stop. |
| ← → | Move between controls; Home and End jump to the ends. |
| Enter / Space | Activates; on a tool, makes it the tool in hand. |
| Space while the surface has focus | Play and pause (as in every editing app), unless a text field has focus. |
| , and . | Previous and next frame, the editors' keys; shown in the tooltips. |

### ARIA
- `role="toolbar"` with `aria-label` naming the surface (*Animatic for Scene 12*). One tab stop, roving `tabindex`.
- Tools are toggle buttons with `aria-pressed`; only one is `true`.
- Transport buttons are icon-only and named (*Previous frame*); Play changes its name to *Pause* while playing.
- The timecode is `role="timer"` with a spoken label; it is not announced on every frame. Announce it when playback stops.
- **More** has `aria-haspopup="menu"` and lists the hidden controls with their words.

## For agents

### Rules

- **Must** start every toolbar with the scope: what the tools will act on, in words and figures.
- **Must** keep scope, transport and the timecode visible at every width; fold commands into "More ▾" first.
- **Always** give a tool a word beside its icon; icon-only is for transport and universal glyphs, with a name.
- **Must** use role="toolbar" with roving tabindex and arrow keys, or no toolbar role at all.
- **Never** put project-wide actions in a surface toolbar, and never float a toolbar on a phone.

### AI readiness test

**Task:** Build the toolbar for the storyboard, which has frames, a camera setup per frame, and an export.

**Give the agent:** This page, Storyboard frame, Shot module steps (Shots · Blocking · Storyboard · Animatic).

**Constraint:** Export already lives in File; a phone must still reach Add frame.

**A reliable answer:**
- Starts with "Frame 4 · Shot 12A"
- Tools Select and Draw with words and aria-pressed
- Add frame after a spacer
- No Export in the toolbar
- Under 640px Add frame moves to More ▾ with 44px targets
