# button

One link that starts the next step, to a screen of this app or a URL, such as Build an agent.

`label` is the words on the button (a verb first); `to` names a screen of this app, or `href` an `https://` URL or
a path starting with `/`; exactly one of the two. `emphasis` is `primary` (the one main step on a screen),
`secondary` (the default) or `quiet`. `icon` names an icon shown before the label. A button only navigates; it
never writes.

Category: action. Tier 1. Contract version 1.

## When to use

- The next step from a screen, such as building an agent from the agents screen.
- A link out to a document, such as the runbook or a schema.
- A way back, such as back to the queue from a ticket.

## When to use another block

- A change to the selected rows, such as closing tickets. Use [`grid`](/catalog/grid.md).
- Saving what a person typed. Use [`form`](/catalog/form.md).
- Several links, one per line. Use [`list`](/catalog/list.md).

## Props

- `id` (name: a-z, 0-9 and -): The block's id: its Markdown anchor and its actions' route (`/act/<id>/<action>`). Default `<type>-<n>`, n counting blocks of this type depth-first from 1.
- `label` (text ≤ 40, required): The button's words.
- `to` (name: a-z, 0-9 and -): The screen of this app it opens; or `href`.
- `href` (https:// URL or /path): An https:// URL (or a / path) it opens; or `to`.
- `emphasis` (one of primary, secondary, quiet, default `secondary`): primary (solid), secondary (outline) or quiet (ghost).
- `icon` (icon name): An icon before the label.

## Data

Reads none.

Shape: none.

## Actions

- `open`: navigates to the screen. Needs none; reversible; confirm page never; cost free.
  - `to` (name: a-z, 0-9 and -, required): The screen it opens.

## States

- **ready**: always drawn; it reads no data

## Examples

### The main step on a screen

```yaml
button: { label: Build an agent, to: build-agent, emphasis: primary, icon: plus }
```

As an agent reads it:

```markdown
<a id="button-1"></a>

[Build an agent](/a/catalog/build-agent)

- #button-1.open "Build an agent": GET /a/catalog/build-agent · opens the screen · approval: no · cost: free

```

### A link to a runbook

```yaml
button: { label: Open the VPN runbook, href: 'https://docs.example.com/runbooks/vpn', icon: file }
```

As an agent reads it:

```markdown
<a id="button-1"></a>

[Open the VPN runbook](https://docs.example.com/runbooks/vpn)

```

### A quiet way back

```yaml
button:
  label: Back to the queue
  to: queue
  emphasis: quiet
```

As an agent reads it:

```markdown
<a id="button-1"></a>

[Back to the queue](/a/catalog/queue)

- #button-1.open "Back to the queue": GET /a/catalog/queue · opens the screen · approval: no · cost: free

```

## Invalid

```yaml
button: { label: Build an agent, to: build-agent, href: /a/service-desk/build-agent }
```

Answers: `button: write to (a screen) or href (a URL), one of the two`

## Composition

- Sits in: screen, card, columns
- Pairs with: card, text, callout
- One primary button on a screen at most.
- Apple HIG: Use a verb that says what happens, and give the main action the most emphasis.

## Telemetry

button.open

JSON Schema: [/catalog/button.schema.json](/catalog/button.schema.json)