feat(traces): UX guidance + Spotlight as default tab (PR G)

[coccyx]

Summary

PR G of the v0.9.0 faceted-nav thread (sibling of #46/#47/#48 — all merged). The faceted-nav surface works, but the Traces page felt experts-only. This pass makes it novice-friendly without adding any new capability.

What changes for the user

• Spotlight is now the default rail tab. Facets is one click away. For someone debugging, Spotlight is the higher-value primitive — Facets tells them what they already implicitly know, Spotlight surfaces what they didn't.

• Rich empty state on the rail replaces the one-line hint:

  • Explains what Facets vs Spotlight do
  • Three sample-filter chips (`HTTP 5xx errors`, `POST requests`, `gRPC calls`) that one-click seed a filter row
  • Brand-new users can see the panel light up without guessing attribute names

• Per-panel captions explain what the bars mean:

  • Spotlight: "For each attribute, the colored bar shows your selection's share of values; the gray bar shows the rest of the time window's share. A big gap means that attribute is a strong differentiator."
  • Facets: "Top values for each attribute in your selection. Click any value to add it as a filter and narrow further."

• Loading states explain themselves — "Loading facets — querying each attribute in parallel; values appear as queries return…" so users understand the streaming behavior they're seeing.

• Sidebar hints — Filters section leads with "Narrow the spans your search and the side rail will analyze."

• Center banner is richer — explicitly tells the user that the Spotlight rail works independently of the trace results.

Screenshots

Empty state with explanatory copy + example chips + Spotlight as default tab:

Clicking "HTTP 5xx errors" chip seeds a filter and Spotlight populates:

Facets tab with new caption + streaming-load message:

Test plan

• `npx tsc --noEmit` — clean
• `npm run lint` — 0 errors
• `npm test` — 101/101 passing
• `npm run deploy` — packed + uploaded + provisioned on staging
• Playwright capture spec (`tests/traces-ux-screenshots.spec.ts`) succeeds
• PR F's smoke spec (`tests/faceted-nav.spec.ts`) still passes

Validate on staging

1. Open the Traces page with no service/filter set
2. Verify the right rail shows the rich empty state with three sample chips
3. Click "HTTP 5xx errors" — filter row appears, Spotlight (default tab) starts streaming
4. Switch to Facets — caption visible, loading message explains the streaming
5. Center banner explains how to find traces AND that the rail works independently

What's next

• PR H: Spotlight on Errors page (per-ErrorClass differential)
• PR I: Spotlight on Service Detail
• After all merge → cut v0.9.0

Session log

`docs/sessions/2026-05-28-traces-ux.md`

🤖 Generated with Claude Code