Skip to main content

Core Help UI Contract

This contract defines how in-app contextual help binds UI elements to docs.

Components​

  • HelpChip

    • Inline trigger next to labels, section headers, or error banners.
    • Props: helpKey, variant, size, roleScope.

  • HelpTooltip

    • One-sentence preview for quick reference.
    • Must never contain critical-only instructions.

  • HelpPanel

    • Side panel with short summary, steps, and related links.
    • Primary source: docs article mapped by helpKey.

  • HelpSearchLauncher

    • Search entry in toolbar/navigation.
    • Seeds app context to bias search ranking.

Resolution flow​

  1. UI emits helpKey.
  2. core.help service resolves helpKey to doc id.
  3. Doc id resolves to route path in docs site.
  4. Panel renders summary and deep links.

Behavioral requirements​

  • Role-aware filtering when docs are role-limited.
  • Fallback to app home help page when key is missing.
  • Track events: help_opened, help_search, help_no_results, help_article_opened.

Accessibility​

  • HelpChip must be keyboard reachable.
  • Panel must trap focus and support Escape to close.
  • Tooltips must have screen reader labels.