---
name: ux-observability
description: Define and review end-to-end measurement for important user journeys during user-facing interface work. Select purposeful semantic events and outcome metrics without instrumenting every control.
---

# UX Observability

Important user journeys must be measurable end-to-end. Instrument journeys to
understand whether users achieve their goals and where they fail. Do not add
events merely because a UI control or screen exists.

## Define the journey before implementation

- Identify important journeys before implementing complex or business-critical
  flows. For smaller UI changes, identify the affected journey and inspect its
  existing measurement; reuse it when sufficient rather than adding events.
- Inspect existing journey definitions, telemetry, and product conventions.
  Follow established conventions over generic recommendations unless a concrete
  problem justifies changing them. Do not prescribe vendors, SDKs, or UI frameworks.
- Define success and UX quality measures before building the flow. Record its
  start, actual successful outcome, failure states, abandonment rule, and any
  meaningful intermediate or recovery states needed for diagnosis.
- Define the measurement window and what counts as a journey attempt. Specify
  how retries or resumed journeys affect counts and duration. Measure abandonment
  through an explicit exit or a defined period without completion; do not assume
  every missing completion is abandonment while asynchronous work is pending.
- Measure the actual user outcome whenever possible. A successful local UI action
  does not prove the underlying operation succeeded. If only a proxy is available,
  label it and document the measurement gap instead of claiming outcome coverage.
- When reconstruction requires it, correlate events across screens and asynchronous
  operations with a scoped journey or correlation identifier. Define its lifetime
  and retry behavior; avoid using sensitive identity data as the identifier.

## Choose semantic events

Distinguish these layers:

| Layer | Example | Meaning |
| --- | --- | --- |
| UI interaction | A submit control is activated | A control was used |
| User intent | The user requests payment | The user tried to advance a goal |
| Journey state | Payment is submitted and processing | The operation reached a meaningful stage |
| Business/UX outcome | Payment is confirmed or fails | The user's goal succeeded or encountered failure |

The closer an event is to a meaningful outcome, the more valuable it generally
is. Keep intent and completion distinct; one does not imply the other.

- Track semantic actions, meaningful transitions, and outcomes. Prefer a small
  number of stable, high-value events over exhaustive UI telemetry.
- Avoid indiscriminate click tracking and speculative metrics. Events such as
  `ButtonClicked`, `DropdownOpened`, `FieldFocused`, `FieldChanged`, and
  `SubmitClicked` should not be added without a clear analytical purpose.
- Prefer events such as `payment_started`, `payment_submitted`,
  `payment_succeeded`, and `payment_failed` only when those names correspond to
  meaningful states in the actual product journey. These are examples, not a
  required event list. Emit success from evidence of the confirmed outcome.
- Keep event meaning independent of widget names, component hierarchy, screen
  structure, coordinates, or other UI implementation details. A UI refactor
  should not invalidate the journey definition or its metrics.
- For each event, record its meaning, emission condition, necessary properties,
  and known purpose, consumer, or decision supported. Omit events with no such use.

## Measure quality with minimal data

- Make it possible to calculate successful completion/conversion, abandonment,
  drop-off between meaningful steps, duration, failure rate, and relevant error
  or recovery states. Define denominators and time boundaries so results are
  interpretable; use only intermediate steps that help diagnose the journey.
- Reuse existing outcome signals where possible. Keep correlation sufficient to
  reconstruct important journeys without collecting unrelated activity.
- Respect privacy and data-minimization requirements. Collect only properties
  needed for the stated analytical purpose; do not capture sensitive user data,
  form contents, or raw error payloads merely to simplify analysis.
- Validate representative success, failure, retry, and abandonment scenarios
  against emitted or existing signals. Check that retries or duplicate delivery
  do not inflate outcomes and that cross-screen/asynchronous correlation works.
  Document unavailable signals or measurement limitations honestly.
- Keep measurement from blocking the user journey or changing its outcome when
  telemetry is unavailable. Analytics should diagnose UX problems, not merely
  demonstrate that users interacted with the interface.

## UX Review

Apply to important journeys affected by the change, using existing measurement
where adequate. Record evidence and any gaps; a cosmetic change does not require
new events, and absent instrumentation does not justify speculative telemetry.

- [ ] Is the important journey observable end-to-end, with a defined start and
  actual successful outcome rather than only a UI interaction?
- [ ] Can completion, failure, abandonment, drop-off, duration, and relevant
  recovery states be measured with defined attempts and measurement windows?
- [ ] Are meaningful intermediate states measurable where they aid diagnosis?
- [ ] Are events based on semantic intent, states, and outcomes rather than
  individual controls, and would they remain meaningful after a UI refactor?
- [ ] Can related events be correlated across screens and asynchronous operations
  when necessary, with retries and duplicate events accounted for?
- [ ] Does every event have a known purpose, consumer, or decision it supports?
- [ ] Is collection limited to telemetry necessary to understand and improve the
  experience, consistent with privacy requirements?
- [ ] Have representative journeys been checked and measurement gaps identified,
  without claiming that rendering correctly proves UX completion?