# UX Contracts (non-API) — Ops-UX Constitution Rollout (055)

This feature does not introduce new public HTTP APIs. Instead it defines **internal UX contracts**: shared builders/presenters that all operation-related UI must use.

## Surfaces

### A) Toast (queued only)

**Trigger**: user clicks “Start operation” / submits a form that enqueues a job.

**Contract**

- Toast must appear immediately.
- Must **not** write a DB notification for `queued`.
- Copy (canonical) (OPS-UX Constitution v1.3.0):
  - Title: `{OperationLabel} queued`
  - Body: `Running in the background.`

Optional alternative body (not additive):

- `You can monitor progress in Operations.`

Forbidden in toast:

- counts/metrics
- percentages/progress
- terminal outcomes (completed/failed/partial)
- feature-specific copy

Notes:

- Toast is queued-only.
- Terminal outcomes are delivered via DB notification (initiator-only).
- Live awareness is via Progress Widget + Monitoring → Operations.

### B) Progress widget (queued/running only)

**Audience**: tenant-wide for users with Monitoring access.

**Contract**

- Only shows runs with status `queued` or `running`.
- At most 5 items.
- If more than 5, show `+N more` link to canonical Operations index.
- Each row must include a canonical `View run` action linking to Run Detail.
- Must use centralized label + status copy.
- Polling cadence must be “calm”: start fast when there are actives, then back off.

### C) Terminal DB notification

**Trigger**: transition to a terminal state.

**Audience**: initiator-only.

**Contract**

- Exactly one notification per run per initiator.
- Must not write `queued` notifications.
- Title/body/status must be derived via centralized presenter.
- Must include canonical `View run` link.
- Optional summary uses `summary_counts` with whitelist rules.

## Strings

All copy that appears in these surfaces must come from a shared source (presenter or resource strings), not ad-hoc in Blade/Livewire.

## Metrics (summary_counts)

Allowed keys:

- See spec.md (FR-012) “Canonical allowed summary keys (single source of truth)”.

Any other keys must not render.