# card

Groups a few blocks under one title and an optional line of description, such as a ticket at a glance and its next step.

A card is a surface with a `title`, an optional `description` and 1 to 12 `blocks` inside it, top to bottom. It
reads no data itself; the blocks inside read their own sources. Use it to say "these belong together" — the title
names the group in the words a person would use, not the look ("Evidence for the auditor", not "grey box").

Category: layout. Tier 1. Contract version 1.

## When to use

- A few blocks describe one thing, such as one agent's budget bar and the sentence on what happens when it runs out.
- A section of a screen needs a title and a line saying why it is there.
- Two or three groups side by side inside `columns`, each with its own title.

## When to use another block

- A title over the rest of the screen with nothing grouped under it. Use [`heading`](/catalog/heading.md).
- A message a person must notice, such as a warning about hand-offs. Use [`callout`](/catalog/callout.md).
- A decision on a row, with Approve and Reject buttons. Use [`approval`](/catalog/approval.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.
- `title` (text ≤ 200, required): The card's title.
- `description` (text ≤ 500): A line under the title.
- `blocks` (list of 1–12 blocks, required): The blocks inside, in order.

## Data

Reads none.

Shape: none.

## Actions

None: this block only shows.

## States

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

## Examples

### A ticket at a glance

```yaml
card:
  title: VPN drops every 20 minutes
  description: Closed by the Network agent; the requester confirmed the fix.
  blocks:
    - text: { text: 'The agent matched a known pattern, pushed the corrected profile and replied.' }
    - button: { label: Open the ticket, to: ticket }
```

As an agent reads it:

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

### VPN drops every 20 minutes

Closed by the Network agent; the requester confirmed the fix.

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

The agent matched a known pattern, pushed the corrected profile and replied.

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

[Open the ticket](/a/catalog/ticket)

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

```

### One agent's budget

```yaml
card:
  title: Procurement agent
  description: Model budget this month
  blocks:
    - progress: { label: Budget used, source: budget, figure: value, column: used_usd, max: 120, format: usd }
    - text: { text: The agent pauses when the budget is reached; its tickets then go to a person. }
```

As an agent reads it:

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

### Procurement agent

Model budget this month

<a id="progress-1"></a>

Budget used: $96 of $120 (80%)

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

The agent pauses when the budget is reached; its tickets then go to a person.

```

### Evidence for the auditor

```yaml
card:
  id: evidence
  title: Evidence for the auditor
  description: What each export contains, and whether it is ready
  blocks:
    - grid:
        source: evidence
        plain: true
        columns:
          - { key: framework, label: Framework, kind: strong }
          - { key: contents, label: What the export contains }
          - { key: ready, label: Ready, kind: status, tones: { one click: ok, draft: warn } }
```

As an agent reads it:

```markdown
<a id="evidence"></a>

### Evidence for the auditor

What each export contains, and whether it is ready

<a id="grid-1"></a>

| Framework | What the export contains | Ready |
|---|---|---|
| SOC 2 | Access log, approvals, policy history | one click |
| ISO 27001 | Asset list, data locations, incident log | draft |

Showing 1–2 of 2

```

## Invalid

```yaml
card:
  title: Procurement agent
```

Answers: `card.blocks: missing; this key is required`

## Composition

- Sits in: screen, columns
- Pairs with: columns, progress, text, button
- Two to five blocks in a card; a card of twelve is a screen of its own.
- No card inside a card.
- Apple HIG: Use a grouped surface to show that items belong together, with a short title in sentence case.

## Telemetry

card.view

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