WS4 premium minimalism: error states that act, teaching empty state, design tokens

[r3dbars]

Visual/UX polish from docs/TRANSCRIPTED_PREMIUM_PRD.md WS4 (Premium minimalism) — making the app feel like a $99 tool, not a project. Additive and backward-compatible. Perf/latency budget untouched (a separate thread owns WS4.2).

An audit found the app is already ~80% premium: the gold-standard patterns exist (MeetingFailureCopy, HomeListEmptyState, HomeActionFailureCopy). This PR closes the concentrated gaps and pins them so they can't regress.

What changed

WS4.3 — Error states that act (the spine)

No user-facing surface dumps a raw error.localizedDescription anymore. Two new Foundation-pure copy primitives (AgentSetupFailureCopy, SettingsActionFailureCopy) hold plain-words messages; each failure keeps its existing control as the retry and tucks the raw error behind a Copy Details reveal.

Surface	Before	After
Agent page — connect row	Label(error.localizedDescription) (e.g. "The file couldn't be opened because you don't have permission…")	"Transcripted couldn't connect Claude Desktop. Check that it's installed and not already running, then try Connect again." + Copy Details
Agent page — Codex inbox / 4× live-meeting setup paths	"Could not set up Live Meetings: <raw NSError>"	plain-words copy + Copy Details
Onboarding — Claude Desktop connect card (first run)	raw NSError on the first-run card	plain words + the button flips to "Try again"
Settings — beta sidecar, local-summary prep, model-cache cleanup ×3, launch-at-login, capture-library migration	"Could not …: <raw NSError>"	plain-words status + Copy Details reveal (launch-at-login is a tooltip, so plain words only; raw error already goes to telemetry)

WS4.5 — Empty state that teaches

The Speakers All speakers empty state was a bare gray caption ("No speakers yet. After your next meeting, the people in it will appear here."). It now teaches what will fill the screen and offers a real next action, reusing the Home teaching-empty-state pattern:

No speakers yet
Transcripted learns each voice as you record. After your first meeting, the people in it show up here, so you can name someone once and have them recognized in every meeting after.
[ Start a meeting ]

Search-no-match keeps its plain caption (correct there). Home's meeting/dictation empty states were already teaching and were left as-is.

WS4.4 — Design tokens

• docs/DESIGN_TOKENS.md is the new single source: a 6-step SF Pro type scale, a 4pt spacing grid, and a 4-value corner-radius set — each grounded in the app's most-common existing values (so adoption is snap-to-grid, not a redesign; the app carried ~21 ad-hoc font sizes, 12 radii, ~26 padding values).
• MenuTokens.Font now owns the menubar's type roles; the menubar rows and header read fonts from there instead of raw NSFont.systemFont(ofSize:) literals. This is the reference adoption that sets the pattern; the exact current sizes were preserved, so there's no menubar pixel change — the win is centralization. SwiftUI surfaces (Home, Settings) are intentionally left for incremental follow-up per the doc.

Verification

• ✅ Full app build (build.sh --no-open) — build complete, launch smoke + performance budget pass
• ✅ Full fast suite (run-tests.sh) — 12755 tests, 0 failed
• ✅ New UIAutomationSurfaceContract guards (3 suites) pin the new state: teaching empty state present + old caption gone; zero raw error.localizedDescription on the hardened surfaces (Agent page, onboarding, Settings); tokens are the single source. Existing 229 contract assertions still green (287 total now).
• ✅ Repo-hygiene duplicate-declaration check + agent-preflight

Still needs local human visual sign-off on

I did the code-level work and proved it via automated build + contracts + full suite. The subjective "does it actually feel premium" pass is yours:

1. Speakers empty state — render the Speakers page with zero saved speakers; confirm the teaching card + "Start a meeting" button look right and the button starts a meeting.
2. Error reveals — trigger an Agent-page connect failure and a Settings action failure; confirm the plain-words line + "Copy Details" link read well and Copy Details puts the raw error on the clipboard.
3. Menubar typography — confirm the popover looks identical to before (sizes were preserved; this should be a no-op visually, but eyes-on confirms the token routing didn't shift anything).
4. Onboarding — confirm the first-run Claude Desktop card shows plain words + "Try again" on a forced failure.

Deferred (documented, not done)

• WS4.1 surface reduction (General "Advanced" group). The audit produced a turnkey plan: add one GeneralDisclosureRow and reparent Show in Dock, Confirm meeting quits, Auto-detect calls, Missed-call reminders behind it (reuses the existing GeneralDisclosureRow/GeneralExpandedContent; keeps the contract-pinned identifiers in source), taking the General top group from ~13 at-rest rows toward the ≤7 target. Deferred because it's a whole-page relayout and an information-architecture judgment (is "Show in Dock" really advanced?) that wants your product call + visual sign-off — better as its own focused PR than bundled with this verified polish.
• Two lower-visibility raw-error paths not in the audit's top-9: the Home meeting-preview read error (already framed under a plain "Could not preview this meeting" header) and the local-summary generation failure notice. Both are follow-ups; fixing the latter well needs the local-summary failure taxonomy.

🤖 Generated with Claude Code