# Decision: Per-session Health Indicator in State column

**Date**: 2026-05-09
**Status**: Accepted
**Affected**: `MICROAPPS_PRODUCT_CONTEXT.md` §3 / §5 / §9, Figma file-local component `MicroApp State Pill`-area (row State cell layout), all session rows in MC + MS mockups, UX delivery annotations (A_State + likely a new A_Health section)

---

## Context

State column today shows: `[State Pill] [duration descriptor]` (e.g. `●ON-AIR  1h 10m` / `●PREVIEW  12m 04s` / `●INACTIVE —`).

Operators monitoring 8 cards × N sessions need to know not just "what state is this in" but also **"is anything wrong with it"**. A session can be On-air but degraded (bitrate fluctuation, output URL unreachable, audio level out of range, etc.).

## Decision

Append a **per-session Health Indicator** as a 16px icon at the right end of the State cell.

```
[State Pill] [duration]   [Health icon]
●ON-AIR  1h 10m            ✓ (green check)        ← healthy
●PREVIEW 12m 04s           ⚠ (amber warning)      ← issue, hover shows reason
●INACTIVE —                ✓                      ← healthy (idle)
```

### Icon states (TVU UX Design System imports)

All icons + colors are bound to **TVU UX Design System** (libraryKey `lk-057f6ba0...` per spec §8). Color tokens (variables) drive the appearance — fills inside icon components are aliases to the variables, not hardcoded hex.

| State | Library asset | Component key | Bound color variable | Hex (Dark mode) |
|---|---|---|---|---|
| Healthy | `icon/Message/Success 1` | `85588a1ace60a5430f45a4fe7aab9faaf52ad8dd` | `UX/Brand/Brand` | `#2fb54e` |
| Warning | `icon/Message/warning 1` | `cefe48b9e79a32f8386939be5febb9c2c983e91d` | `UX/Orange/Default` | `#f68512` |
| Error | `icon/Message/Error 3` | `164c7c224a9089f9bc5ec9be61bae3718103cb04` | `UX/Red/Default` | `#ea4233` |

> **Why these specific variants** (2026-05-11 修正):
> - `Success 1` — **outline circle with check inside** (line style)
> - `warning 1` — **outline circle with `!` inside** (line style) —— ⚠️ 注意：v1 错挑了 `warning 2`（fill 风格），与 Success / Error 不一致；2026-05-11 修正
> - `Error 3` — **outline triangle with `!` inside** (line style)
>
> **挑选标准**：3 个图标必须**视觉风格统一**（都 line / 都 fill），不只看颜色对。挑 variant 前必须 import 全部候选并排截图对比形状/填充。
>
> **避开**：
> - `Success 2`（filled green circle，with State Pill On-air 红撞），fill 风格
> - `warning 2`（filled orange circle），fill 风格——与 Success 1 + Error 3 line 不一致
> - `warning 3`（outline gray，无颜色强调）
> - `Error 4`（filled red triangle），fill 风格

> **Why orange = warning, not yellow**: TVU UX Design System uses `UX/Orange/Default` as its semantic warning token. There is no separate yellow/amber warning variable in the library. This aligns warnings with the broadcast convention (orange = "approaching limits" / "non-critical attention").

### Token reuse confirmation

`UX/Brand/Brand` is the same green used by:
- `State Pill / Counter Pill` Preview state (`#2fb54e`)
- Card header "X active" badge

`UX/Red/Default` is the same red used by:
- `State Pill / Counter Pill` On-air state (`#ea4233`)
- `Action Cluster` destructive icons (Stop, Stop X)

`UX/Orange/Default` (#f68512) is unique to warning-tier indicators — not used by State Pills or Action icons.

This means the cross-context color reuse warning in [`A_State` annotation](./../MICROAPPS_PRODUCT_CONTEXT.md) still holds, but with three buckets per hue:
- Green: positive action (Action icons) | Preview state (State Pill) | Healthy (Health Indicator).
- Red: destructive action | On-air state | Error health.
- Orange: warning health (and only warning health — no other component uses orange).

### Behavior

- **Always shown** for every session row, including Inactive (Inactive sessions are typically healthy by definition; ✓ confirms "no leftover errors before the session was stopped").
- **Hover** triggers the design-system Tooltip component with a short reason string supplied by backend (max ~50 chars).
- **Click** is non-interactive in v1 (purely informational). Phase 2 may open a diagnostic panel.

## Rationale

- **Operator scanning**: green/amber/red is preattentively distinguishable. Operator can scan 30 rows in under a second.
- **Decoupling state from health**: a session can be "On-air but unhealthy" — that's exactly what monitoring is for. State Pill alone doesn't carry that info.
- **Hover for detail, no UI clutter**: 16px icon adds minimal visual weight; tooltip carries the actual diagnostic.
- **Color reuse with intent**:
  - Green ✓ = healthy (matches Preview's "good" hue, but with check shape so different from Preview pill)
  - Red × = critical (matches On-air's hue, but with × shape so different from On-air pill)
  - Amber ⚠ = warning (intermediate, no equivalent in state palette → distinct hue).
  Cross-context warning still applies: see A_State annotation.

## Implementation

### Figma mockup (this commit)

- Add 16px Health Indicator to **every visible session row** in:
  - MC-1920 (`3278:1835`) — 8 rows
  - MS-1920 (`3289:2726`) — 8 rows
  - MC-1440 / MS-1440 — TBD if rows exist there; probably mirror MC/MS-1920 pattern.
- Distribution for mockup illustration:
  - **2 warning** rows (one in different state) so reviewers see ⚠ + the "Bitrate fluctuation detected" tooltip — references user's reference screenshot.
  - **The rest healthy** ✓.
- No "error" rows in mockup unless we want to demo the red state too (skipping for now — keep mockup clean).

### Library debt

- TBD: should `MicroApp State Pill` component absorb the Health Indicator as a sibling slot, or remain separate? **Provisional**: keep separate for v1 (less coupling); promote to a slot if feedback demands.
- Library may already have a `icon/status/check`, `icon/status/warning`, `icon/status/error`. **TBD**: probe library; if missing, file BRIDGE-MOCKUP debt.

### UX delivery annotation

- A_State (or new A_Health): document the 3 health states + tooltip behavior + "always visible per row" + cross-context color reuse notes.

## Open Questions

- Backend authority: who computes health? (Backend service per session — confirmed.)
- Should idle/Inactive sessions actually display ✓, or no icon at all? **Default**: show ✓ (cleaner alignment, "no issues" reading).
- Severity precedence: if a session has multiple issues, tooltip shows worst one or all? **Provisional**: show worst (single line), with `+N more` if applicable.
- Refresh cadence: is health re-computed on auto-refresh tick or push from backend? **TBD with backend team.**

## Source

User instruction, 2026-05-09, with reference mockup showing `●ON-AIR 1h 10m ✓` / `●PREVIEW 12m 04s ⚠` (with "Bitrate fluctuation detected" tooltip) / `●INACTIVE — ✓`.