218 lines
9.0 KiB
Markdown
218 lines
9.0 KiB
Markdown
# UI Micro-Interactions Component Map (MI6)
|
|
|
|
This document maps StellaOps UI components to their interaction types and motion token usage. Components must use tokens from the catalog (`tokens/motion.scss`, `motion-tokens.ts`) rather than bespoke values.
|
|
|
|
## Token Catalog Reference
|
|
|
|
| Token | CSS Variable | Duration | Use Case |
|
|
| --- | --- | --- | --- |
|
|
| durationXs | --motion-duration-xs | 80ms | Focus rings, instant feedback |
|
|
| durationSm | --motion-duration-sm | 140ms | Hover states, button presses |
|
|
| durationMd | --motion-duration-md | 200ms | Modal open/close, panel slide |
|
|
| durationLg | --motion-duration-lg | 260ms | Page transitions, accordions |
|
|
| durationXl | --motion-duration-xl | 320ms | Complex sequences, onboarding |
|
|
| easeStandard | --motion-ease-standard | cubic-bezier(0.2,0,0,1) | Default for all transitions |
|
|
| easeEntrance | --motion-ease-entrance | cubic-bezier(0.18,0.89,0.32,1) | Elements appearing |
|
|
| easeExit | --motion-ease-exit | cubic-bezier(0.36,0,-0.56,-0.56) | Elements leaving |
|
|
| easeBounce | --motion-ease-bounce | cubic-bezier(0.34,1.56,0.64,1) | Playful feedback only |
|
|
|
|
## Component Mapping
|
|
|
|
| Component | Interaction Type | Tokens Used | Reduced-Motion Behavior |
|
|
| --- | --- | --- | --- |
|
|
| Button (primary) | Hover lift, press scale | durationSm, easeStandard, scaleSm | No transform, instant state change |
|
|
| Button (secondary) | Hover border, press | durationXs, easeStandard | Instant state change |
|
|
| Modal/Dialog | Fade + slide up | durationMd, easeEntrance/Exit, translateMd | Instant show/hide |
|
|
| Dropdown/Menu | Fade + scale | durationSm, easeStandard, scaleSm | Instant show/hide |
|
|
| Toast/Snackbar | Slide in, auto-dismiss | durationMd, easeEntrance, translateLg | Instant show/hide |
|
|
| Accordion | Height expand | durationMd, easeStandard | Instant toggle |
|
|
| Tabs | Indicator slide | durationSm, easeStandard | Instant indicator |
|
|
| Progress bar | Width fill | durationMd, easeStandard | No animation, instant fill |
|
|
| Spinner/Loader | Rotate animation | N/A (CSS keyframe) | Static icon or hidden |
|
|
| Skeleton | Shimmer pulse | durationXl, easeStandard | Static skeleton, no shimmer |
|
|
| Badge (status) | Scale pop on change | durationXs, easeBounce, scaleSm | No scale, instant |
|
|
| Focus ring | Fade in | durationXs, easeStandard | Always visible, no fade |
|
|
| Tooltip | Fade + offset | durationSm, easeEntrance, translateSm | Instant show/hide |
|
|
| Banner (info) | Slide down | durationMd, easeEntrance, translateMd | Instant show/hide |
|
|
| Error state | Shake animation | durationSm, easeStandard | No shake, border only |
|
|
|
|
## Perf Budget Compliance (MI5)
|
|
|
|
| Metric | Budget | Measurement |
|
|
| --- | --- | --- |
|
|
| Interaction response | <= 100ms | Time to visual feedback |
|
|
| Animation frame (avg) | <= 16ms | Chrome DevTools Performance |
|
|
| Animation frame (p95) | <= 50ms | Chrome DevTools Performance |
|
|
| Layout shift | <= 0.05 CLS | Lighthouse CI |
|
|
| LCP placeholder | Show within 400ms | Lighthouse CI |
|
|
|
|
## Validation Rules
|
|
|
|
1. **Lint rule**: ESLint/Stylelint blocks non-catalog easing values in `.scss` and `.ts` files
|
|
2. **Storybook check**: All component stories must demonstrate reduced-motion variant
|
|
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
|