# V1-AWEB-098 — Alert, Severity, SLA & Escalation Visuals Spec

Implementation spec for the Phase 17.10 alert / severity / SLA / escalation
visual system. Goal: **urgent when needed, never visually chaotic**.

## Reference: as-is

Severity / SLA visuals appear across:

- Trust-safety (`TrustSafetyMetricsDashboard`, `CrisisEscalationList`,
  `SafetyRuleHitsPanel`).
- Incidents (`IncidentDetailPanel`, `IncidentImpactCommsPanel`,
  `IncidentRunbookPostmortemPanel`).
- Privacy (`PrivacyRequestQueuePanel`, `RetentionManagementPanel`).
- Support (`SupportCaseInboxPanel`).
- Research-integrity (`ResearchIntegrityQueuePanel`).
- Models (`ReadinessDashboardPanel`, `ReleaseReadinessGoNoGoPanel`).

Each panel ships its own severity badges, SLA countdown, and escalation banners
— colours, icon sets, and animation are inconsistent.

### As-is pain points

1. **Colour palette is not normalised.** Critical reds drift between `#ef4444`,
   `#dc2626`, `#b91c1c` across panels.
2. **SLA countdown formats differ.** Some panels show `2h 13m`, some `00:02:13`,
   some absolute timestamps.
3. **Escalation banners animate.** Some panels animate the escalation banner on
   first render; the motion is distracting for operators reviewing back-to-back
   cases.
4. **Critical doesn't always mean critical.** A "critical" moderation row and a
   "critical" privacy request currently share the same red badge but route to
   very different action surfaces; operators learn to ignore the colour.
5. **No motion budget.** Animated badges + animated banners + animated SLA
   counters produce a chaotic feel during heavy queue periods.

## Design principles

1. **One severity scale, one colour map.** Four levels (`normal`, `attention`,
   `urgent`, `critical`) with one fixed colour each, used everywhere.
2. **One SLA format.** Relative time (`2h 13m left` or `2h 13m overdue`) with
   absolute timestamp on hover.
3. **No motion on render.** Severity stripes + badges render without animation.
   The only motion budget is for acknowledgement (a 200ms fade on banner
   dismiss).
4. **Severity level maps to action urgency, not domain.** A `critical` row
   anywhere on the admin app means "operator action needed within minutes";
   `urgent` means "within the hour"; `attention` means "before end of shift";
   `normal` means "no urgency".
5. **Escalation is a state, not a banner.** Escalated rows are rendered with a
   persistent left stripe + an icon; they don't need a separate banner.

## Severity colour map

| Level     | Stripe / badge bg      | Foreground         |
| --------- | ---------------------- | ------------------ |
| normal    | (no stripe)            | `#cbd5e1` text     |
| attention | `#fbbf24` (amber 400)  | `#0f172a` on badge |
| urgent    | `#fb923c` (orange 400) | `#0f172a` on badge |
| critical  | `#ef4444` (red 500)    | `#f8fafc` on badge |

The map is exposed as CSS custom properties in `globals.css`:

```css
:root {
  --severity-attention: #fbbf24;
  --severity-urgent: #fb923c;
  --severity-critical: #ef4444;
}
```

Per-panel severity rules read these custom properties so any future palette tune
happens once.

## SLA format

Shared `<SlaCountdown deadline={iso} now={iso} />` component:

- `> 0` time remaining: `"2h 13m left"` (rounded down to the next minute, `≥ 1h`
  rounded to hours+minutes, `≥ 1d` rounded to days+hours).
- `≤ 0` time remaining: `"2h 13m overdue"` with severity `critical`.
- Hover surfaces the absolute timestamp.

The component does NOT animate; it re-renders once per minute via a shared
`useSlaTick()` hook that broadcasts a tick to all mounted countdowns.

## Escalation rendering

Escalated rows render with:

- the canonical `attention` (or `urgent` / `critical` as appropriate) left
  stripe;
- a leading `↑` icon prefix on the title;
- no banner, no animation.

The escalation rationale (if present) renders inline in the row expansion drawer
(V1-AWEB-094), not as a separate banner.

## Implementation deliverables

1. `apps/oshun/admin/src/components/SlaCountdown.tsx` + `.module.css`.
2. `apps/oshun/admin/src/lib/use-sla-tick.ts` — once-per-minute tick broadcast
   hook with a single shared `setInterval`.
3. CSS custom property definitions added to `globals.css`.
4. Migration: every panel that ships severity visuals or SLA countdowns adopts
   the canonical map and component.
5. Tests: `SlaCountdown` unit test (covering remaining / overdue formatting),
   severity-stripe visual regression spec (Playwright screenshot under
   `apps/oshun/admin/e2e/admin-severity-visuals.spec.ts`).

## Out of scope

- Audio alerts for critical rows (deferred).
- Operator-configurable severity thresholds (deferred).
- Cross-workspace severity aggregation on the dashboard (deferred to
  V1-AWEB-100).

## Acceptance criteria

- Every severity stripe / badge across the admin app uses one of the four
  canonical colours via CSS custom properties.
- Every SLA countdown uses `<SlaCountdown />` with the canonical relative-time
  format and hover-to-show absolute.
- No banners or stripes animate on render; only acknowledgement dismissal (200ms
  fade) animates.
- Escalated rows render with the canonical severity stripe + `↑` prefix; no
  separate escalation banner.
- The Playwright visual regression spec passes (no diff > 0.1% per row across
  the four severity levels).
