# 30-Nov-2025 - UI Micro-Interactions for StellaOps

## Purpose
Define canonical micro-interaction rules (MI1-MI10) for the StellaOps Console so motion, latency, error, and offline behaviors stay accessible, deterministic, and offline-ready. This advisory is the source of truth for UI sprints 0209/0210/0211 and Storybook/Playwright harnesses.

## Scope
- Applies to Angular workspace `src/Web/StellaOps.Web` (Console), shared UI tokens, Storybook stories, and Playwright/axe/perf checks.
- Covers micro-copy/localisation, telemetry events, reduced-motion behavior, and deterministic seeds/snapshots.

## Principles
- Prefer informative micro-interactions over decorative motion; default to reduced-motion safe values.
- Deterministic by default: fixed seeds, frozen fixtures, stable ordering, UTC timestamps.
- Offline-first: no CDN assets; latency/error/offline states always represented with cached assets and copy.
- WCAG 2.1 AA (focus order, keyboard, contrast, reduced motion, status messaging).

## MI Tracks (acceptance)
| ID | Requirement | Acceptance Signals |
| --- | --- | --- |
| MI1 | Motion tokens catalogue (durations 80/140/200/260/320ms; easings `standard`,`decel`,`accel`,`emphasized`; distance scales XS-XL) in `tokens/motion.ts` and SCSS variables. | Storybook token page renders tokens; tokens consumed by at least 3 components (button, modal, banner). |
| MI2 | Reduced-motion rules: prefers-reduced-motion -> durations clamp to 0-80ms, disable parallax/auto-animations; focus/hover states remain visible. | Playwright + axe snapshots with reduced-motion emulate; no animated GIF/Lottie autoplay; acceptance screenshots stable. |
| MI3 | Latency/idle/load patterns: skeletons (<=400ms show), progress (400-1200ms), optimistic states, and offline banners with retry/backoff copy. | Fixtures for slow/failed/offline in Storybook; Playwright asserts state transitions and retry button wiring. |
| MI4 | Error/cancel/undo: deterministic snackbar/toast pattern with keyboard focus, `aria-live=polite`, and 8s undo window. | Playwright e2e shows undo restores prior state; axe passes; snapshot stable. |
| MI5 | Perf budgets: interaction response <=100ms, animation frame budget 16ms avg/50ms p95; LCP placeholder shown; no layout shift >0.05. | Lighthouse CI (offline config) JSON attached; flamechart samples stored under `tests/perf/micro/`. |
| MI6 | Component mapping: table of components -> interaction type -> token usage; avoid bespoke easing outside catalog. | Mapping lives in `docs/modules/ui/micro-interactions-map.md`; lint rule blocks non-catalog easings. |
| MI7 | Telemetry schema: `ui.micro.*` events with versioned schema, fields (tenant, surface, component, action, latency_ms, outcome, reduced_motion, offline_mode, error_code); PII-free. | JSON schema under `docs/modules/ui/telemetry/ui-micro.schema.json`; unit test validates sample payloads. |
| MI8 | Deterministic seeds/snapshots: RNG seeds fixed per story/test; timestamps frozen; CSS animations paused in snapshots. | Storybook stories set `parameters.chromatic.disableAnimation`; Playwright uses `useFakeTimers` + fixed seeds exported from `micro-fixtures.ts`. |
| MI9 | Micro-copy localisation: keys and ICU messages for micro-interaction copy; defaults EN, fallbacks present; no hard-coded strings in components. | i18n extraction shows zero TODO keys; snapshot verifies translated skeleton/error/undo copy. |
| MI10 | Theme/contrast guidance: light/dark/HC tokens for backgrounds, borders, focus rings, and status colors; contrast >= 4.5:1 text, 3:1 UI elements. | Theming doc `docs/modules/ui/micro-theme.md`; axe-color passes for sample stories; focus ring visible in HC mode. |

## Deliverables
- Token catalog: `src/Web/StellaOps.Web/src/styles/tokens/motion.{ts,scss}` with reduced-motion overrides.
- Storybook stories: `apps/storybook/src/stories/micro/*` covering slow, error, offline, reduced-motion, undo flows; deterministic seeds.
- Playwright suite: `tests/e2e/micro-interactions.spec.ts` covering MI2/MI3/MI4/MI8.
- Telemetry schema + validators: `docs/modules/ui/telemetry/ui-micro.schema.json` plus unit test in `src/app/telemetry/__tests__/ui-micro.schema.spec.ts`.
- Mapping doc: `docs/modules/ui/micro-interactions-map.md` linking components to token usage.

## Test & Determinism Rules
- Freeze timers to 2025-12-04T12:00:00Z in stories/e2e; seed RNG with `0x5EED2025` unless scenario-specific.
- All fixtures and snapshots stored under `tests/fixtures/micro/`; no network calls; offline assets bundled.
- Playwright runs with `--disable-animations` and reduced-motion emulation variant.

## Risks & Mitigations
- Workspace absence blocks implementation -> tracked in sprint action #7.
- Token drift across sprints -> add lint rule and CI check for non-catalog easings.
- Localisation regressions -> include i18n extraction in PR CI for micro stories.

## Traceability
- Sprint: `docs/implplan/SPRINT_0209_0001_0001_ui_i.md` (task UI-MICRO-GAPS-0209-011).
- Findings reference: `docs/product-advisories/31-Nov-2025 FINDINGS.md` (MI1-MI10 gap family).