# Tooltip

> A name on hover and focus. Kwark uses the browser’s title today; the drawn tooltip adds a shortcut where a desk needs it.

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

## Usage

### What Kwark does today
Kwark uses the browser’s own `title` tooltip: every `IconButton` sets `title` to its label, and tags put their detail there (*2 changes are saved on this device and not in the cloud yet…*). The drawn tooltip on this page is for where a `title` is not enough: a shortcut beside the name, or a dense toolbar on a desk.

### When to use
- To name an icon button and show its shortcut on hover and keyboard focus.

### When not to use
- For anything a person needs on a phone: there is no hover. Put it in visible text.
- For instructions or teaching (Decision 0004).

## Style

### Anatomy

1. `--k-surface` with a 1px `--k-line` and `--k-shadow-pop` (it floats), 6px corners, 6px 8px padding, at most 240px.
2. 12px Poppins; the shortcut in `--k-text-2`.
3. Appears after 500ms on hover, at once on keyboard focus, never covering the control it names.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--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-radius-control` | 6px |  |
| `--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
<button class="kw-icon-button" type="button" aria-label="Keep a restore point" title="Keep a restore point (⇧⌘S)"><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="M20 6 9 17l-5-5"/></svg></button>
<span class="kw-tooltip" role="tooltip">Keep a restore point <kbd>⇧⌘S</kbd></span>
```

## Accessibility

- Appears on hover **and** focus; dismissible with Escape; does not vanish when the pointer moves onto it (WCAG 1.4.13).
- Linked with `aria-describedby`, or the control’s accessible name already says the same.

## For agents

### Rules

- **Never** put instructions or required information in a tooltip.
- **Must** show on focus as well as hover, and close on Escape.

### AI readiness test

**Task:** Explain the ⌘⇧N shortcut for adding a scene.

**Give the agent:** Tooltip, Menus and shortcuts.

**Constraint:** Must work for keyboard users.

**A reliable answer:**
- Tooltip "New scene ⌘⇧N" on hover and focus
- Also listed in the menu
- Escape closes
