ux-metrics

name	ux-metrics
description	This skill should be used when quantifying user experience — instrumenting performance, defining analytics events, or scoring usability. Trigger phrases include "measure UX", "Core Web Vitals", "set up web vitals", "track LCP/INP/CLS", "Lighthouse score", "design analytics events", "SUS score", "usability metrics", and "how do I quantify UX". Use it to pick the right metrics, instrument them, and interpret the numbers.
version	0.1.0

UX metrics

The quantitative measurement layer for UX. Use it to choose meaningful metrics, instrument them, and read the results honestly — covering performance, automated quality scores, analytics events, and self-reported usability.

When to use

Trigger when the user wants to "measure UX", set up or "track LCP/INP/CLS", instrument "Core Web Vitals", interpret a "Lighthouse score", "design analytics events", compute a "SUS score", define "usability metrics", or asks "how do I quantify UX". Detect the project's stack first via ../ux-foundations/references/stack-detection.md and adapt to any analytics or perf library already present.

1. Core Web Vitals

Google's user-centric performance signals. Thresholds (the "good" boundary is the one to design for; "poor" begins past the second number):

Metric	What it measures	Good	Needs improvement	Poor
LCP Largest Contentful Paint	Loading — when the largest content element renders	≤ 2.5s	2.5s–4.0s	> 4.0s
INP Interaction to Next Paint	Responsiveness — worst-case input latency across the visit	≤ 200ms	200ms–500ms	> 500ms
CLS Cumulative Layout Shift	Visual stability — unexpected layout movement (unitless)	≤ 0.1	0.1–0.25	> 0.25

INP replaced FID as a Core Web Vital in March 2024 — use INP.

Instrument with the bundled scripts/web-vitals-snippet.js (a copy-paste template using the web-vitals v4 library). It reports each metric to console and an endpoint.

Field vs lab data — distinguish the two and report both when you can:

• Field (RUM) — real users, real devices and networks. The source of truth for CWV (e.g. CrUX, your own web-vitals beacons). Aggregate at the 75th percentile across page loads, per metric.
• Lab — synthetic, controlled run (Lighthouse, WebPageTest). Reproducible and good for debugging regressions, but a single device/network — not the user-experienced number. Note: lab cannot measure INP (no real interactions); it reports TBT as a proxy.

2. Lighthouse / axe scores

• Lighthouse runs five categories: Performance, Accessibility, Best Practices, SEO, and PWA. The Performance score is a weighted blend of lab metrics (FCP, LCP, TBT, CLS, Speed Index).
• Limits — Lighthouse Performance is a lab proxy, not a field result; a 100 does not mean fast for real users, and a low score may just reflect a slow test device. The Accessibility score (axe-based) only covers automatable checks (~a third of WCAG) — a 100 is not a passed accessibility audit. For real conformance, run the accessibility-audit skill.
• Treat scores as trend indicators and regression alarms, not certificates.

3. Analytics event taxonomy

Design a consistent schema before adding tracking; retrofitting is expensive.

• Naming — pick one convention and enforce it. Object-Action is recommended: <object>_<action> (e.g. checkout_started, video_played, signup_completed). Use past tense, snake_case (or match the existing codebase), and never free-form per-developer names.
• Properties — attach structured context (e.g. plan: "pro", source: "nav", value: 49). Define a shared property dictionary. Never log PII (email, name, raw IP, precise location) in event payloads; use a stable hashed/opaque user id.
• Metrics to build from events:
  • Funnel / conversion — step-to-step drop-off through a flow.
  • Task success rate — % of attempts that reach the goal event.
  • Time on task — duration from start event to success event.
  • Error rate — error events ÷ attempts.
• Adapt to the project — if an analytics lib is present (Segment, PostHog, GA4, Amplitude, Mixpanel, etc.), use its track(event, properties) API and identify conventions rather than inventing a parallel system.

4. Self-reported usability (SUS)

The System Usability Scale — a validated 10-item questionnaire, fast and benchmarkable.

• Items (odd = positive, even = negative), each rated 1 (strongly disagree) – 5 (strongly agree):
  1. I think I would like to use this system frequently.
  2. I found the system unnecessarily complex.
  3. I thought the system was easy to use.
  4. I think I would need support of a technical person to use this system.
  5. I found the various functions in this system were well integrated.
  6. I thought there was too much inconsistency in this system.
  7. I imagine most people would learn to use this system very quickly.
  8. I found the system very cumbersome to use.
  9. I felt very confident using the system.
  10. I needed to learn a lot of things before I could get going.
• Scoring — odd items contribute (response − 1); even items contribute (5 − response); sum all ten and multiply by 2.5 → a 0–100 score (it is not a percentage).
• Interpretation — the average across products is ~68 (grade C). Use the Sauro–Lewis curved grade: ≥80.3 = A (excellent), ~68 = C (average / "OK"), <51 = F (poor). Pair with an adjective rating (e.g. "Good", "OK", "Poor").
• When to use — a quick post-task or post-study perception measure; needs ~5+ respondents to be meaningful and is best compared to your own prior scores or the 68 benchmark.
• Compute with node scripts/sus-score.mjs r1 r2 ... r10.

How to pick metrics

Don't measure everything. Tie each metric to a goal using the HEART framework (Google): Happiness, Engagement, Adoption, Retention, Task success. For each chosen dimension, define a Goal → Signal → Metric chain. Map metrics to specific user goals, and avoid vanity metrics (raw pageviews, total signups) that move without reflecting real value — prefer rates, percentiles, and per-user measures.

References

• references/metrics-glossary.md — thresholds and one-line definitions for CWV, lab metrics, Lighthouse, HEART, and common UX metrics.
• scripts/sus-score.mjs — SUS calculator with grade interpretation.
• scripts/web-vitals-snippet.js — copy-paste Core Web Vitals instrumentation template.