# Button

> Starts an action. Kwark draws it in three places with three weights: the shared button, the story-surface button in modules and dialogs, and the light resume control on Project home.

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

## Usage

### What it is
A button starts something: saves, creates, issues, opens a dialog. If it only goes somewhere, it is a link. Kwark draws buttons in three weights, and each has a home. The specimen is Home’s first frame for a new visitor: **Start a new story** and **Open the sample film**, measured from the running app.

### Variants and where they live
| Variant | Class | Where in Kwark | Geometry |
|---|---|---|---|
| Primary | `kw-button--primary` | *Start a new story*, *Save changes* in Project settings | The accent (#98633f, or the project’s colour) with white text; hover brightens 10% |
| Secondary | `kw-button` | *Open the sample film* | Raised ground, a 1px border a step stronger than a line |
| Quiet | `kw-button--quiet` | *Cancel*, *Dailies*, *Filter* on Home | No fill, quiet text, text colour on hover |
| Danger | `kw-button--danger` | Confirming *Move to trash*, *Decline* in access requests | The danger colour as a fill. Only inside a confirmation |
| Story surface | `kw-button--story` | Module pages, story dialogs, the production office (*Open the screenplay* on an empty Breakdown) | 36px, 6px corners, 12px; secondary is a 1px outline on nothing |
| Resume | `kw-button--resume` | Project home’s *Add a character* (where to go on) | The text colour as a fill, a trailing ↗, 44px, as wide as its column |

Home’s blue **New project** is a fourth, single-use button: see [Top bar](https://kwark.space/designSystem/components/top-bar.md). Never use it inside a project.

### Sizes
28px (`--sm`, inside panels and toasts), 36px by default, 44px (`--lg`) where it is the main action of a screen and everywhere under a thumb. On a phone every button grows to 44px.

### Writing the label
- A verb and its object, in sentence case: **Save changes**, **Move to trash**, **Open the screenplay**. Never *Submit*, *OK* or *Yes, do it*.
- The same word through the flow: the button says *Move to trash*, the toast says *Project moved to trash*.
- A chevron only when it opens a choice (*New project ▾*); a ↗ only on the resume control.

### Moving older code over
`Button.tsx` still renders the old `ds-btn` (upper case, 0.05em tracking, 10px at the small size). Every visible use adds `k-btn-plain` for sentence case. Use the shared `Button` with `className="k-btn-plain"` until the base class is changed.

**Do:** One primary, named for what happens: **Issue call sheet**. *Cancel* beside it is quiet.

**Don't:** Two primaries side by side, or an upper-case **EXECUTE ACTION** that makes the reader guess.

## Style

### Anatomy

1. **Container**: 8px corners (`.ds-btn`); the story-surface and resume variants use 6px (`--k-radius-control`).
2. **Heights**: 28 · 36 · 44px. Padding 10 · 14 · 18px.
3. **Label**: Poppins 500, 14px (12px in the story surface and at 28px).
4. **Icon**: 14px, leading, 8px gap. Trailing only for a chevron or the resume ↗.
5. **States**: hover brightens the primary by 10% and steps the secondary’s ground; disabled is 50% opacity with `cursor: not-allowed`; busy keeps the width and shows the 16px ring.
6. **Focus**: 2px ring in `--k-accent-soft`, 2px off the edge.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-accent` | #98633f | #98633f |
| `--k-on-accent` | #ffffff | #ffffff |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-danger` | #b4382c | #e0685c |
| `--k-bg` | #f8fafc | #191919 |
| `--k-accent-soft` | #e8b58b | #e8b58b |
| `--k-radius-control` | 6px |  |
| `--k-control-md` | 36px |  |
| `--k-tap` | 44px |  |
| `--k-fs-body` | 14px |  |
| `--k-fs-meta` | 12px |  |

## Code

### React

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

```tsx
<Button variant="primary" onClick={save}>Save scene</Button>
<Button variant="secondary" icon={Share2}>Share</Button>
<Button variant="ghost" onClick={close}>Cancel</Button>
```

| Prop | Type | Notes |
|---|---|---|
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | `ghost` is the quiet button |
| `size` | `'sm' \| 'md' \| 'lg'` | 32, 36, 44 px |
| `icon` | `LucideIcon` | leading icon |
| `iconRight` | `LucideIcon` | trailing icon, e.g. a chevron |
| `loading` | `boolean` | sets aria-busy and keeps the width |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div style="display:flex;flex-wrap:wrap;gap:12px;align-items:center">
  <button class="kw-button kw-button--primary kw-button--lg" type="button">Start a new story</button>
  <button class="kw-button kw-button--lg" type="button">Open the sample film</button>
</div>
<div style="display:flex;flex-wrap:wrap;gap:12px;align-items:center">
  <button class="kw-button kw-button--quiet" type="button">Cancel</button>
  <button class="kw-button kw-button--primary" type="button">Save changes</button>
  <button class="kw-button kw-button--danger" 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="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> Move to trash</button>
</div>
<div style="display:flex;flex-wrap:wrap;gap:12px;align-items:center">
  <button class="kw-button kw-button--story" type="button">Cancel</button>
  <button class="kw-button kw-button--story kw-button--primary" type="button">Open the screenplay</button>
  <button class="kw-button kw-button--sm" type="button">Retry</button>
</div>
<button class="kw-button kw-button--resume" type="button" style="width:min(100%,416px)">Add a character <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></button>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Moves focus to the button. Focus shows a 2px ring in `--k-focus`, 2px off the edge. |
| Enter / Space | Activates it. |

### Rules
- Use a real `<button type="button">`. A `div` with a click handler is not a button to a keyboard or a screen reader.
- Disabled buttons stay focusable with `aria-disabled="true"` when the reason matters; say the reason next to them.
- While working, set `aria-busy="true"`, keep the width, and announce the result (*Saved*) in a polite live region.
- Text on the accent must reach 4.5:1. `--k-on-accent` is chosen so it does in every room.

## For agents

### Rules

- **Must** use the shared `Button` (or `.kw-button`) for every clickable action; never style a `div` or `a` to look like one.
- **Never** put two primary buttons in one view, sheet or dialog.
- **Must** label with a verb and an object in sentence case: "Save scene", never "Submit" or "OK".
- **Never** write a colour, font size or radius into a button; take them from `--k-*` tokens.
- **Always** use 44px (`size="lg"`) where a thumb is the pointer.

### AI readiness test

**Task:** Build the footer of a dialog that issues a call sheet to the crew, with a way to back out.

**Give the agent:** This page, the Dialog page, tokens.json.

**Constraint:** Use only existing variants and sizes. Say if anything you need is missing.

**A reliable answer:**
- One primary labelled "Issue call sheet"
- A quiet "Cancel" to its left
- No raw colours or pixel values
- Primary is last in the row and receives focus only when the dialog has no field
