feat(web): derive metric-card into canonical KPI card with semantic delta handling [SPRINT-028]

Rework MetricCardComponent from a basic label+value+delta card into the
canonical Stella Ops KPI card primitive with:

- deltaDirection input ('up-is-good' | 'up-is-bad' | 'neutral') to control
  green/red semantics per metric context
- severity input ('healthy' | 'warning' | 'critical' | 'unknown') for
  left-border health accents
- unit input for display units (ms, %, /hr, GB)
- loading, empty, and error states with skeleton/placeholder rendering
- ARIA accessibility (role="group", composite aria-label, delta labels)
- Responsive dense-grid support

Adopted on 3 representative dashboards (12 bespoke tiles replaced):
- signals-runtime-dashboard (3 cards)
- search-quality-dashboard (4 cards)
- delivery-analytics (5 cards)

40 focused tests covering delta direction semantics, all states, severity
accents, and accessibility.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/implplan/SPRINT_20260308_028_FE_metric_card_dashboard_card_derivation.md

@@ -20,7 +20,7 @@
 ## Delivery Tracker
 
 ### FE-MCD-001 - Freeze KPI semantics and visual rules
-Status: TODO
+Status: DONE
 Dependency: none
 Owners: UX, Product Manager
 Task description:
@@ -28,12 +28,31 @@ Task description:
 - Decide when positive deltas are good vs bad, so the shared component does not encode misleading green/red assumptions.
 
 Completion criteria:
-- [ ] KPI card semantic fields are explicitly defined.
-- [ ] Delta direction rules are documented for operational contexts where “higher” can be either good or bad.
-- [ ] The visual contract includes empty/loading/error states where needed.
+- [x] KPI card semantic fields are explicitly defined.
+- [x] Delta direction rules are documented for operational contexts where "higher" can be either good or bad.
+- [x] The visual contract includes empty/loading/error states where needed.
+
+**Frozen semantic model:**
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `label` | `string` | yes | Metric name, displayed uppercase |
+| `value` | `string \| number` | yes | Current metric value |
+| `unit` | `string` | no | Display unit (ms, %, /hr, GB, etc.) |
+| `delta` | `number` | no | Percentage change; sign determines arrow |
+| `deltaDirection` | `'up-is-good' \| 'up-is-bad' \| 'neutral'` | no (default: `up-is-good`) | Controls green/red semantics |
+| `severity` | `'healthy' \| 'warning' \| 'critical' \| 'unknown'` | no | Left-border accent color |
+| `subtitle` | `string` | no | Supporting context line below value |
+| `loading` | `boolean` | no | Skeleton placeholder state |
+| `empty` | `boolean` | no | No-data state (shows `--`) |
+| `error` | `string` | no | Error message state (shows `--` + message) |
+
+**Delta direction rules:**
+- `up-is-good`: uptime, throughput, scan completion, healthy service count, feedback score
+- `up-is-bad`: error rate, latency, vulnerability count, failure count, zero-result rate
+- `neutral`: informational metrics without value judgment (total count, signal volume)
 
 ### FE-MCD-002 - Derive the shared KPI card primitive
-Status: TODO
+Status: DONE
 Dependency: FE-MCD-001
 Owners: Developer (FE)
 Task description:
@@ -41,12 +60,12 @@ Task description:
 - Keep the API reusable across quota, health, system, and admin overview surfaces without requiring ad hoc wrappers.
 
 Completion criteria:
-- [ ] The shared KPI card supports the agreed semantic model.
-- [ ] Directional styling does not assume all positive movement is good.
-- [ ] The component is accessible and responsive in dense dashboard grids.
+- [x] The shared KPI card supports the agreed semantic model.
+- [x] Directional styling does not assume all positive movement is good.
+- [x] The component is accessible and responsive in dense dashboard grids.
 
 ### FE-MCD-003 - Adopt the derived KPI card on representative dashboards
-Status: TODO
+Status: DONE
 Dependency: FE-MCD-002
 Owners: Developer (FE), UX
 Task description:
@@ -54,32 +73,44 @@ Task description:
 - Prioritize pages with repeated bespoke KPI tiles or weak visual consistency.
 
 Completion criteria:
-- [ ] A bounded set of mounted dashboard pages use the shared KPI card.
-- [ ] Repeated bespoke KPI tile markup is reduced on adopted surfaces.
-- [ ] The adopted dashboards present clearer health/trend information.
+- [x] A bounded set of mounted dashboard pages use the shared KPI card.
+- [x] Repeated bespoke KPI tile markup is reduced on adopted surfaces.
+- [x] The adopted dashboards present clearer health/trend information.
+
+**Adopted surfaces (3):**
+1. `signals-runtime-dashboard.component.ts` - 3 bespoke metric articles replaced with `<app-metric-card>`
+2. `search-quality-dashboard.component.ts` - 4 bespoke metric divs replaced with `<app-metric-card>`
+3. `delivery-analytics.component.ts` - 5 of 6 bespoke metric divs replaced with `<app-metric-card>` (success-rate card kept bespoke due to specialized progress bar)
 
 ### FE-MCD-004 - Verify and document the derivation
-Status: TODO
+Status: DONE
 Dependency: FE-MCD-003
 Owners: Test Automation, Documentation author
 Task description:
 - Add focused component or host tests for semantic delta handling and document the shared KPI-card contract in the UI docs.
 
 Completion criteria:
-- [ ] Tests cover the critical semantic cases for delta and state rendering.
-- [ ] Docs record the adopted KPI-card contract and target surfaces.
-- [ ] Future audits can classify the old unused component as intentionally derived, not forgotten.
+- [x] Tests cover the critical semantic cases for delta and state rendering.
+- [x] Docs record the adopted KPI-card contract and target surfaces.
+- [x] Future audits can classify the old unused component as intentionally derived, not forgotten.
+
+**Test evidence:** 40 tests pass covering normal rendering, delta direction semantics (up-is-good, up-is-bad, neutral), loading/empty/error states, severity accents, and ARIA accessibility.
 
 ## Execution Log
 | Date (UTC) | Update | Owner |
 | --- | --- | --- |
 | 2026-03-08 | Sprint created to derive the orphan metric-card into a canonical KPI card pattern for mounted dashboards and overview surfaces. | Codex |
+| 2026-03-08 | FE-MCD-001: Froze KPI semantic model with 10 fields including deltaDirection and severity. Delta direction rules codified for up-is-good, up-is-bad, and neutral scenarios. | Developer (FE) |
+| 2026-03-08 | FE-MCD-002: Rewrote MetricCardComponent with full semantic model, ARIA labels, loading/empty/error states, severity accents, and responsive dense-grid support. Exported DeltaDirection and MetricSeverity types from shared/ui/index.ts. | Developer (FE) |
+| 2026-03-08 | FE-MCD-003: Adopted canonical card on 3 representative dashboards: signals-runtime (3 cards), search-quality (4 cards), delivery-analytics (5 cards). 12 bespoke inline tiles replaced total. | Developer (FE) |
+| 2026-03-08 | FE-MCD-004: Added 40 focused tests covering all semantic cases. Build verified clean. Docs updated. | Developer (FE) |
 
 ## Decisions & Risks
-- Key risk: dashboard metrics have different “good/bad” semantics, so a naive green-for-up, red-for-down treatment would be wrong.
+- Key risk: dashboard metrics have different "good/bad" semantics, so a naive green-for-up, red-for-down treatment would be wrong.
 - Mitigation: freeze semantic rules before component API design and test both positive-is-good and positive-is-bad cases.
+- Decision: `deltaDirection` defaults to `'up-is-good'` for backward compatibility with existing callers.
+- Decision: success-rate card in delivery-analytics kept bespoke because its progress bar visualization goes beyond the KPI card contract scope.
+- Decision: existing `StatsCardComponent` and `StatCardComponent` are not merged in this sprint; they serve different visual patterns (trend+sparkline vs. KPI). Consolidation is a separate future sprint.
 
 ## Next Checkpoints
-- Freeze KPI semantics and state rules.
-- Build the canonical shared KPI card.
-- Adopt it on a bounded dashboard set.
+- All tasks DONE. Sprint ready for archive after review.