# text

A paragraph of plain text that explains what a person is looking at, such as what "Needs a person" means.

`text` is plain text up to 2,000 characters, drawn as one paragraph. Nothing in it is formatted: `**` and `#` show
as written. For formatting, links or lists use `markdown`. Quote the text when it holds `: ` or starts with a
quote mark, as YAML requires.

Category: content. Tier 1. Contract version 1.

## When to use

- One or two sentences explain a screen or the block under them.
- A rule a person should know before acting, such as when a closed ticket counts as a result.
- A line inside a card, under its title.

## When to use another block

- Text with headings, lists, links or bold. Use [`markdown`](/catalog/markdown.md).
- Something a person must notice or act on, such as a warning. Use [`callout`](/catalog/callout.md).
- The name of a section. Use [`heading`](/catalog/heading.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.
- `text` (text ≤ 2000, required): The paragraph, plain text.

## Data

Reads none.

Shape: none.

## Actions

None: this block only shows.

## States

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

## Examples

### What a status means

```yaml
text:
  text: '"Needs a person" is a status, not a failure: the ticket moves to a person and is never metered.'
```

As an agent reads it:

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

"Needs a person" is a status, not a failure: the ticket moves to a person and is never metered.

```

### The rule behind a figure

```yaml
text: { text: A ticket an agent closed counts as a result only after 72 hours without a reply from a person. }
```

As an agent reads it:

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

A ticket an agent closed counts as a result only after 72 hours without a reply from a person.

```

### A paragraph with an id

```yaml
text:
  id: builder-note
  text: The builder is free. A new agent runs on the last 100 tickets of its kind before anyone turns it on.
```

As an agent reads it:

```markdown
<a id="builder-note"></a>

The builder is free. A new agent runs on the last 100 tickets of its kind before anyone turns it on.

```

## Invalid

```yaml
text: { txt: The builder is free. }
```

Answers: `text.txt: unknown key; allowed: id, text; did you mean text?`

## Composition

- Sits in: screen, card, columns
- Pairs with: heading, grid, card
- One paragraph per block; three sentences at most read at a glance.
- Apple HIG: Write in plain, direct language a person understands without help.

## Telemetry

text.view

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