# Text button

> An icon and a word, used in headers, toolbars and sheets. A chevron means it opens something.

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

## Usage

### What it is
An icon and a word, for headers and sheets: Kwark’s answer to toolbars of bare icons. A control says what it is, with a word (docs/design-system.md). A chevron after the word means it opens something.

### Variants and where they live
| Variant | Where | Look |
|---|---|---|
| Plain | The phone header’s **Menu ▾** (`TextButton opens`) | 32px (44 under a thumb), 14px, no border, `--k-raise` on hover and while open |
| Bordered | Project home’s **Menu ▾**, the module head’s **Just the work** | 34px, 1px line, 12px, quiet text |
| Filled | Project home’s **Start session** | 1px line on the raised ground, 12px |

### When not to use
- For the one main action of a screen: that is a [Button](https://kwark.space/designSystem/components/button.md).
- For a universal glyph alone (back, close, ⋯): that is an [Icon button](https://kwark.space/designSystem/components/icon-button.md).

## Style

### Anatomy

1. **Height**: 32px (`.k-textbtn`), 44px under a thumb; the bordered variant is 34px.
2. **Padding**: 0 12px (10px bordered); 8px between icon and word (6px bordered).
3. **Icon**: 16px; chevron 14px in `--k-text-2`.
4. **Word**: Poppins 500, 14px (12px bordered and filled). It never shrinks or clips: `flex: none; white-space: nowrap`.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-raise` | #f1f5f9 | #252525 |
| `--k-control-sm` | 32px |  |
| `--k-icon-sm` | 14px |  |

## Code

### React

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

```tsx
<TextButton icon={Menu} label="Menu" opens aria-expanded={open} onClick={toggle} />
```

| Prop | Type | Notes |
|---|---|---|
| `label` | `string` | the word; required |
| `icon` | `LucideIcon` |  |
| `opens` | `boolean` | adds the chevron |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<button class="kw-text-button" 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"><path d="M4 6h16M4 12h16M4 18h16"/></svg><span>Menu</span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button>
<button class="kw-text-button kw-text-button--bordered" type="button" aria-haspopup="menu"><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 6h16M4 12h16M4 18h16"/></svg><span>Menu</span><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button>
<button class="kw-text-button kw-text-button--filled" 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 3 14 9-14 9V3z"/></svg><span>Start session</span></button>
<button class="kw-text-button kw-text-button--bordered" 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="M7 7h10v10M7 17 17 7"/></svg><span>Just the work</span></button>
```

## Accessibility

- When it opens a menu: `aria-haspopup="menu"` and `aria-expanded`.
- The word is the accessible name; do not repeat it in `aria-label`.

## For agents

### Rules

- **Must** show a chevron when the control opens a menu or sheet, and never otherwise.
- **Always** pair the icon with a word in headers and toolbars.

### AI readiness test

**Task:** Design a phone header for the Characters screen with search, a filter and five other actions.

**Give the agent:** Text button, Page header, Phones pattern.

**Constraint:** One 44px line.

**A reliable answer:**
- Back, one-word title, at most two labelled actions
- Everything else under "Menu ▾"
- No subtitle or breadcrumb on the phone
