ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
8b9ab52138
TenantAtlas/specs/055-ops-ux-rollout/contracts/ux-contracts.md
Ahmed Darrazi 8b9ab52138 feat(ops-ux): constitution rollout v1.3.0
2026-01-18 14:44:16 +01:00

2.1 KiB
Raw Blame History

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.