# Icon button

> A button that is only a glyph. Allowed for universal symbols, and it always carries a name.

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

## Usage

### When to use
Only for glyphs nearly everyone reads the same way: back, close, more (⋯), add, search. For anything else use a [Text button](https://kwark.space/designSystem/components/text-button.md): a control says what it is with a word.

**Do:** ⋯ on a scene row, with the accessible name *More actions for Scene 12*.

**Don't:** A lone sparkle, wand or lightning icon that means something different in every app.

## Style

### Anatomy

1. **Target**: 32 × 32px on a desk, 44 × 44px under a thumb (`.k-iconbtn`).
2. **Glyph**: 16px lucide, stroke 1.75, `--k-text-2`.
3. **Hover and open**: `--k-raise` ground, `--k-text` glyph.
4. **Name**: `aria-label` and the same words in `title` (IconButton sets both from its required `label`).

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-icon-lg` | 20px |  |
| `--k-control-md` | 36px |  |
| `--k-radius-control` | 6px |  |

## Code

### React

In the Kwark app: `import { IconButton } from '@/components/ui/IconButton'`.

```tsx
<IconButton icon={MoreHorizontal} label={`Actions for ${project.name}`} onClick={open} />
```

| Prop | Type | Notes |
|---|---|---|
| `icon` | `LucideIcon` |  |
| `label` | `string` | required; becomes aria-label and title |
| `iconSize` | `'sm' \| 'md' \| 'lg'` | 14 · 16 · 20px |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<button class="kw-icon-button" type="button" aria-label="Actions for Untitled Story" title="Actions for Untitled Story"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><circle cx="5" cy="12" r="1.8"/><circle cx="12" cy="12" r="1.8"/><circle cx="19" cy="12" r="1.8"/></svg></button>
<button class="kw-icon-button" type="button" aria-label="Back to the project" title="Back to the project"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="m15 18-6-6 6-6"/></svg></button>
<button class="kw-icon-button" type="button" aria-label="Close dialog" title="Close dialog"><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="M18 6 6 18M6 6l12 12"/></svg></button>
<button class="kw-icon-button" type="button" aria-label="Search the screenplay" title="Search the screenplay"><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="8"/><path d="m21 21-4.3-4.3"/></svg></button>
```

## Accessibility

- Every icon button has `aria-label` (or visually hidden text) that names the action **and** its object when there are many: *Delete Scene 12*, not *Delete*.
- Show a tooltip with the same name on hover and focus, for sighted people who do not know the glyph.
- The glyph itself is `aria-hidden="true"`.

## For agents

### Rules

- **Must** give every icon button an accessible name that includes its object.
- **Never** use an icon button for an action without a universal glyph; use a Text button.
- **Always** choose the shared icon sizes: 14, 16 or 20px.

### AI readiness test

**Task:** Add row actions to a list of scenes.

**Give the agent:** Icon button, List row, Menu.

**Constraint:** Do not invent new glyphs.

**A reliable answer:**
- One ⋯ icon button per row opening a Menu
- Name includes the scene, e.g. "More actions for Scene 12"
- Destructive actions live inside the menu, not as separate icons
