stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 12 Releases Wiki Activity
Files
d233fa3529150d073cb25963b12412494f1cbf88
git.stella-ops.org/docs/product-advisories/30-Nov-2025 - UI Micro-Interactions for StellaOps.md
StellaOps Bot e2e404e705
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
console-runner-image / build-runner-image (push) Has been cancelled
Details
Signals CI & Image / signals-ci (push) Has been cancelled
Details
Signals Reachability Scoring & Events / reachability-smoke (push) Has been cancelled
Details
Signals Reachability Scoring & Events / sign-and-upload (push) Has been cancelled
Details
up
2025-12-14 16:24:16 +02:00

5.0 KiB
Raw Blame History

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).