# heading

Names a section of a screen in a few words, so a person scanning the page finds it.

`text` is the heading's words (up to 200 characters); `level` is 2 for a section and 3 for a sub-section. Level 1
is the screen's own title, written by the page head from the screen's `title`, so a block never uses it. The
Markdown rendering writes `##` or `###`; the HTML writes `h2` or `h3`.

Category: content. Tier 1. Contract version 1.

## When to use

- A screen has more than one part, such as the policies and then the evidence for the auditor.
- A part has a sub-part a person should find on its own, such as this week's hand-offs under the agents.
- An agent reading the Markdown needs a section to anchor to.

## When to use another block

- A sentence that explains something rather than naming it. Use [`text`](/catalog/text.md).
- A title over a few blocks that belong together on one surface. Use [`card`](/catalog/card.md).
- A title over one chart; the chart has its own title. Use [`chart`](/catalog/chart.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 ≤ 200, required): The heading's words.
- `level` (whole number 2–3, default `2`): 2 for a section, 3 for a sub-section.

## Data

Reads none.

Shape: none.

## Actions

None: this block only shows.

## States

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

## Examples

### A section of the compliance screen

```yaml
heading: { text: Evidence for the auditor }
```

As an agent reads it:

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

## Evidence for the auditor

```

### A sub-section

```yaml
heading: { text: This week, level: 3 }
```

As an agent reads it:

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

### This week

```

### A heading with an id for its anchor

```yaml
heading: { id: hand-offs, text: Tickets handed to a person }
```

As an agent reads it:

```markdown
<a id="hand-offs"></a>

## Tickets handed to a person

```

## Invalid

```yaml
heading: { text: Queue, level: 1 }
```

Answers: `heading.level: write a whole number from 2 to 3`

## Composition

- Sits in: screen, card, columns
- Pairs with: grid, text, chart
- One heading per part of a screen; a heading over a single block is usually that block's own title.
- Two to six words.
- Apple HIG: Use headings to give a page a clear hierarchy, in sentence case and short.

## Telemetry

heading.view

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