← Context / specs

Tooltip System — A Versatile First-Class Family, Plus a Walkthrough for New and Returning Users

Most apps don't succeed or fail at functionality. They succeed or fail at onboarding, orientation, and re-orientation when a returning user comes back to find things have moved. Tooltips are the load-bearing affordance for all three — and they have to be a versatile first-class family, not a single component bolted onto the browser's half-working `title=`. This spec scopes a family of tooltip primitives (Simple, Rich, Popover), the geometry they share (directional `from` placement with arrow connector, configurable distance, dismissal discipline, accessibility), and the **Tooltip-Walkthrough** surface that sits on top — a guided series of tooltips that fire for users who haven't logged in since a given milestone, so they discover what changed without reading release notes.