# callout

A message a person must notice, such as a warning that an agent's hand-offs tripled, with an optional link to act on it.

`tone` says what kind of message it is: `info` (the default), `ok`, `warn` or `bad`; there is no neutral callout.
`title` is a few words, `text` the message (up to 1,000 characters). `action` adds one link to a screen of this
app: `{ label, to }`. The tone names the meaning; the theme decides the colour.

Category: content. Tier 1. Contract version 1.

## When to use

- Something changed that a person should act on, such as an agent handing off three times as often.
- A result a person waits for, such as a test run that passed.
- A rule that applies to the whole screen, such as the 72-hour hold on results.

## When to use another block

- A plain explanation with nothing to notice. Use [`text`](/catalog/text.md).
- A decision on a row, approved or rejected here. Use [`approval`](/catalog/approval.md).
- A figure, such as the forecast spend. Use [`kpis`](/catalog/kpis.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.
- `tone` (one of info, ok, warn, bad, default `info`): The message's tone.
- `title` (text ≤ 120): The message's title.
- `text` (text ≤ 1000, required): The message.
- `action` (mapping): A link to a screen of this app.
  - `label` (text ≤ 40, required): The link's words.
  - `to` (name: a-z, 0-9 and -, required): The screen it opens.

## 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

### An agent's hand-offs went up

```yaml
callout:
  tone: warn
  title: Apps agent
  text: Hand-offs tripled after the expense tool update on Monday; 94 tickets went to people instead.
  action: { label: Open the agents, to: agents }
```

As an agent reads it:

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

> warn: **Apps agent** — Hand-offs tripled after the expense tool update on Monday; 94 tickets went to people instead.

- #callout-1.open "Open the agents": GET /a/catalog/agents · opens the screen · approval: no · cost: free

```

### A test run passed

```yaml
callout:
  tone: ok
  title: Ready to turn on
  text: 'Test run: 83 of 100 procurement tickets closed the same way a person closed them.'
```

As an agent reads it:

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

> ok: **Ready to turn on** — Test run: 83 of 100 procurement tickets closed the same way a person closed them.

```

### A rule for the whole screen

```yaml
callout: { title: 72-hour hold, text: A closed ticket counts as a result only after 72 hours without a reply from a person. }
```

As an agent reads it:

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

> info: **72-hour hold** — A closed ticket counts as a result only after 72 hours without a reply from a person.

```

## Invalid

```yaml
callout: { tone: neutral, text: Three blocked attempts this month. }
```

Answers: `callout.tone: unknown value neutral; allowed: info, ok, warn, bad`

## Composition

- Sits in: screen, card, columns
- Pairs with: grid, kpis, form
- One or two callouts on a screen; more and none is noticed.
- Place it above or beside what it is about.
- Apple HIG: Reserve alerts for important information, say what happened and what to do next.

## Telemetry

callout.view, callout.open

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