up

2025-12-14 23:20:14 +02:00
parent 3411e825cd
commit b058dbe031
356 changed files with 68310 additions and 1108 deletions
--- a/docs/modules/ui/micro-interactions-map.md
+++ b/docs/modules/ui/micro-interactions-map.md
@@ -53,8 +53,165 @@ This document maps StellaOps UI components to their interaction types and motion
 3. **Playwright check**: Snapshot tests run with `--disable-animations` and reduced-motion emulation
 4. **CI gate**: Perf budget failures block merge

+---
+
+## TTFS Component Interactions
+
+> Per advisory §15: Component-to-interaction mapping for Time-to-First-Signal.
+
+### FirstSignalCard Component
+
+**Location:** `src/app/features/runs/components/first-signal-card/`
+
+| Interaction | Trigger | Duration | Easing | Token |
+|-------------|---------|----------|--------|-------|
+| Skeleton shimmer | Initial load | 2s loop | linear | Custom keyframe |
+| Skeleton → Content | Signal loaded | 200ms | easeEntrance | `durationMd` |
+| Badge appear | Kind change | 140ms | easeEntrance | `durationSm` |
+| Progress update | Phase change | 140ms | easeStandard | `durationSm` |
+| Button hover | Mouse enter | 80ms | easeStandard | `durationXs` |
+| Button press | Click | 80ms | easeExit | `durationXs` |
+| Error shake | Load error | 260ms | easeStandard | `durationLg` |
+
+**Telemetry Events:**
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `ttfs_start` | Component mount | `{ runId, surface, t }` |
+| `ttfs_signal_rendered` | Signal displayed | `{ runId, surface, cacheHit, source, kind, ttfsMs }` |
+| `ui.click.action` | Action button click | `{ runId, actionType, target }` |
+| `ui.retry` | Retry button click | `{ runId, errorCode }` |
+
+**Accessibility:**
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Focus visible | `:focus-visible` outline on buttons |
+| Screen reader | `aria-live="polite"` on content area |
+| Loading state | `aria-busy="true"` on card |
+| Status | `role="status"` on badge |
+| Keyboard | Tab navigation, Enter/Space activation |
+| Reduced motion | Disable shimmer, use instant transitions |
+
+### EvidencePanel Component
+
+**Location:** `src/app/features/evidence/evidence-panel.component.ts`
+
+| Interaction | Trigger | Duration | Easing | Token |
+|-------------|---------|----------|--------|-------|
+| Tab switch | Tab click | 200ms | easeStandard | `durationMd` |
+| Panel expand | Accordion open | 260ms | easeEntrance | `durationLg` |
+| Panel collapse | Accordion close | 200ms | easeExit | `durationMd` |
+| Copy success | Copy button | 140ms | easeEntrance | `durationSm` |
+| Copy tooltip | After copy | 2s visible | — | — |
+| Export progress | Export start | Indeterminate | linear | Spinner |
+
+**Telemetry Events:**
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `finding_open` | Panel mount | `{ findingId, entryPoint, t }` |
+| `proof_rendered` | Proof visible | `{ findingId, proofKind, source, t }` |
+| `ui.copy.verify_command` | Copy verify cmd | `{ type: 'cosign'|'rekor'|'bundle' }` |
+| `evidence.export` | Export complete | `{ findingId, fileSize }` |
+
+### ProofSpine Component
+
+**Location:** `src/app/features/evidence/components/proof-spine/`
+
+| Interaction | Trigger | Duration | Easing | Token |
+|-------------|---------|----------|--------|-------|
+| Hash truncation expand | Hover/focus | 140ms | easeStandard | `durationSm` |
+| Copy single | Copy button | 80ms | easeExit | `durationXs` |
+| Copy all | Copy all button | 140ms | easeEntrance | `durationSm` |
+| Status badge | Load | 200ms | easeEntrance | `durationMd` |
+
+---
+
+## TTFS Telemetry Event Catalog
+
+### Core Events
+
+| Event | Category | Sampling | Always Sample |
+|-------|----------|----------|---------------|
+| `ttfs_start` | ttfs | Per config | No |
+| `ttfs_signal_rendered` | ttfs | Per config | No |
+| `ttfs_timeout` | ttfs | — | Yes |
+| `ttfs_error` | ttfs | — | Yes |
+
+### TTE Events
+
+| Event | Category | Sampling | Always Sample |
+|-------|----------|----------|---------------|
+| `finding_open` | tte | Per config | No |
+| `proof_rendered` | tte | Per config | No |
+
+### UX Events
+
+| Event | Category | Sampling | Always Sample |
+|-------|----------|----------|---------------|
+| `ux.bounce` | ui | — | Yes |
+| `ux.non_bounce` | ui | Per config | No |
+| `ux.open_to_action` | ui | Per config | No |
+| `ui.copy.*` | ui | Per config | No |
+| `ui.click.*` | ui | Per config | No |
+| `evidence.export` | ui | Per config | No |
+
+### Sampling Configuration
+
+| Environment | TTFS Rate | TTE Rate | UI Rate |
+|-------------|-----------|----------|---------|
+| Development | 100% | 100% | 100% |
+| Staging | 100% | 100% | 100% |
+| Production | ≥25% | 50% | 25% |
+
+---
+
+## TTFS State Machine
+
+```
+FirstSignalCard:
+  idle → loading → loaded
+                ↘ unavailable
+                ↘ error → (retry) → loading
+
+EvidencePanel:
+  idle → loading → loaded
+                ↘ partial (some proofs failed)
+                ↘ error
+```
+
+---
+
+## File Locations (TTFS)
+
+| Deliverable | Path |
+|-------------|------|
+| FirstSignalCard | `src/Web/StellaOps.Web/src/app/features/runs/components/first-signal-card/` |
+| FirstSignalStore | `src/Web/StellaOps.Web/src/app/features/runs/stores/first-signal.store.ts` |
+| EvidencePanel | `src/Web/StellaOps.Web/src/app/features/evidence/evidence-panel.component.ts` |
+| ProofSpine | `src/Web/StellaOps.Web/src/app/features/evidence/components/proof-spine/` |
+| TTFS Telemetry | `src/Web/StellaOps.Web/src/app/core/telemetry/ttfs-telemetry.service.ts` |
+| Sampling Config | `src/Web/StellaOps.Web/src/app/core/telemetry/telemetry-config.ts` |
+| i18n Keys | `src/Web/StellaOps.Web/src/assets/i18n/en.json` |
+| Test Fixtures | `tests/fixtures/ttfs/ttfs-fixtures.ts` |
+| E2E Tests | `src/Web/StellaOps.Web/tests/e2e/micro-interactions.spec.ts` |
+
+---
+
 ## Evidence

 - Token catalog: `src/Web/StellaOps.Web/src/styles/tokens/_motion.scss`
 - TypeScript tokens: `src/Web/StellaOps.Web/src/app/styles/motion-tokens.ts`
 - Storybook stories: `src/Web/StellaOps.Web/src/stories/motion-tokens.stories.ts`
+- TTFS Architecture: `docs/modules/telemetry/ttfs-architecture.md`
+- Advisory: `docs/product-advisories/14-Dec-2025 - UX and Time-to-Evidence Technical Reference.md`
+
+---
+
+## References
+
+- Sprint 0338: TTFS Foundation
+- Sprint 0339: First Signal API
+- Sprint 0340: FirstSignalCard UI
+- Sprint 0341: TTFS Enhancements