# Activity fields and layouts

Field limits and platform-specific appearance for progress activities and interactive iOS cards. The lifecycle guide is [Track work](https://notify.belweave.ai/docs/activity-api).

HTML: https://notify.belweave.ai/docs/activity-reference

## State fields and iOS layouts

| Field | Type | Description |
| --- | --- | --- |
| `title` | string, required | Task name, maximum 80 characters. Required at start; may be replaced by an update. |
| `status` | string, required | Current stage, maximum 60 characters. Required at start. |
| `subtitle` | string | Optional short second-line summary replacing visible status in expanded/Lock Screen layouts only, maximum 120 characters. Compact and small-banner views retain status. `null` clears it. Display budgets below are smaller than the accepted payload limit. |
| `detail` | string | Optional supporting text, maximum 240 characters, shown in a two-line detail region. `null` clears it. Overflow remains bounded to the available layout. |
| `progress` | number | Optional fraction from 0 through 1. `null` clears it. |
| `symbol` | enum | Progress icon: `terminal` (default), `code`, `build`, `success`, or `warning`. |
| `accentColor` | string | Six-digit hex, `#RRGGBB`. Defaults to `#246BEB`. |
| `style` | enum | iOS progress layout: `standard` (default), `ring`, `hero`, `terminal`, or `steps`. Updates can select another layout; older builds may use the default. |
| `privacyMode` | enum | `standard` or `private`. On iOS/APNs, private replaces start-alert text with a generic message; the activity content still includes its title/status. |
| `key` | string, start only | Start-time alias, maximum 100 characters, accepted in place of the generated activity ID. Reusable after the previous activity becomes terminal. |
| `replace` | boolean, start only | Start-time replacement flag (default false). Ends only the matching active key owned by the same requester. The response includes `replaced`. |
| `deviceIds` | string[] | Start targeting list of 1–50 device IDs. Omit for eligible capable devices. |

These are iOS layout choices, illustrated below. Progress layouts and interactive choice layouts serve different requests. Native Android shows ordinary notifications; it does not reproduce ActivityKit, Dynamic Island, or this layout gallery. These captures illustrate layout rather than proving push delivery.

Use a short title for the task name, `status` for its current stage, and `subtitle` for a whole-word second-line summary when useful. Display budgets guide writing; they are not guaranteed fit or API rejection limits. Glyph widths, device size, locale, and text size change available space. The native layout measures text, can reduce it to 75% of its base size, then clips at a whole-word boundary if needed. Original text remains available to VoiceOver.

Expanded Dynamic Island and Lock Screen layouts keep a static second-line summary. Its overflow continues before explicit `detail` in a two-line detail region; title overflow does not crowd that region. Compact views hide title, subtitle, and detail; they retain status with a suggested eight-character authoring budget when progress is absent, except terminal, which shows its prompt icon. Actual fit uses measured width rather than a fixed character cutoff. With progress, the percentage takes precedence. Detail can still exceed its two-line space; do not rely on every accepted character being visible.

> A continuous marquee is not promised. [Apple limits widget and Live Activity animations to two seconds](https://developer.apple.com/documentation/widgetkit/animating-data-updates-in-widgets-and-live-activities), and Always-On presentation skips animations. Notify uses the static whole-word summary and two-line detail fallback, including with Reduce Motion enabled; this fallback does not animate.

| Field | Type | Description |
| --- | --- | --- |
| `standard` | Compact | title 0; subtitle 0; status 8; detail 0 |
| `standard` | Expanded / Lock Screen | title 32; subtitle 36; status 36; detail 100 |
| `ring` | Compact | title 0; subtitle 0; status 8; detail 0 |
| `ring` | Expanded / Lock Screen | title 32; subtitle 30; status 30; detail 80 |
| `hero` | Compact | title 0; subtitle 0; status 8; detail 0 |
| `hero` | Expanded / Lock Screen | title 24; subtitle 36; status 36; detail 100 |
| `terminal` | Compact | title 0; subtitle 0; status 0; detail 0 |
| `terminal` | Expanded / Lock Screen | title 36; subtitle 40; status 40; detail 100 |
| `steps` | Compact | title 0; subtitle 0; status 8; detail 0 |
| `steps` | Expanded / Lock Screen | title 32; subtitle 36; status 36; detail 100 |

> Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status.

- `standard` — Default progress card with an icon, two text lines, percentage, and horizontal track.
- `ring` — Circular progress display with the percentage inside the gauge.
- `hero` — Large status text above a bottom-edge progress track.
- `terminal` — Command-prompt presentation with monospaced status and secondary detail.
- `steps` — Five stage indicators for workflows better described by phases.
- `approval` — Default two-choice prompt with balanced decision buttons.
- `shell` — Compact command-style question and decision controls.
- `verdict` — Centered question with a divider and prominent primary action.
- `signal` — Decision card with distinct positive and negative controls.