Design System

In-product help

Help that sounds like the rest of the system.

This pass locks the foundations. The full pattern catalog - walkthroughs, onboarding flows, contextual overlays, embedded documentation, coach marks - lands once specific products ship live help surfaces. Everything below is binding; the catalog inherits from it.

Foundational decisions

  • Voice matches the rest of the system. Help content follows the Voice & microcopy rules: doctrinal register, precise, declarative, no apology, no “feel free to…” softeners. Help is instruction, not service copy.
  • ? key opens contextual help for the current view. Registered in the global keyboard shortcut set (Keyboard shortcuts). ⌘ + / remains the keyboard shortcut overlay; ? is general contextual help.
  • Non-blocking by default. Help surfaces render as side panels, overlays, or tooltips - never as modal dialogs that block the operator. An operator should never be forced to dismiss help to continue working.
  • Progressive discovery. Help surfaces appear on request (? key, help icon, command palette). No auto-popping tooltips, no “welcome!” modals on every page, no checklist badges demanding completion.
  • First-run surfaces are one-shot. A product shows first-run help once per user per product. Re-accessible from settings; never re-triggered automatically on subsequent launches.
  • Localization-aware. Help content is authored in English and translated to French and German alongside the rest of the UI copy - it is not treated as a separate content pipeline.

Deferred to next pass

  • Contextual help overlay pattern - shape, position, content anatomy, dismissal
  • Walkthrough / guided tour flow - step sequencing, progress indication, skip rules
  • First-run onboarding anatomy - landing surface, key-concept tour, “you’re ready” close
  • Embedded documentation architecture - where full docs live (in-app panel? external site? both?), how they link out
  • Coach marks and feature-reveal patterns - trigger conditions, dismissal, rate-limiting to avoid fatigue
  • Keyboard shortcut cheat-sheet presentation - printable PDF, in-app overlay, or both
  • Search within help content
  • Context-awareness - different help for first-time users vs veterans vs admins
  • Per-product inventory - what help surfaces GRIDWATCH vs QRF vs GHOST GRID actually ship