extension-ui-surfaces

name	extension-ui-surfaces
description	Choose and implement the right Chromium extension UI surfaces such as popup, side panel, options page, commands, context menus, and offscreen documents. Use when deciding how the user should enter a workflow, where state should live, or how much UI should persist across tabs.

Extension UI Surfaces

Overview

Pick one or two surfaces that fit the extension job. Popups are for short, ephemeral actions. Side panels are for persistent, workspace-style tools. Options pages are for configuration, not daily work. Commands and context menus are invocation paths, not complete experiences. Offscreen documents are a bridge for DOM-only work, not a hidden UI framework.

Read these references as needed:

• references/popup-options-side-panel.md for the main UI trade-offs
• references/context-menus-and-commands.md for invocation design
• references/offscreen-documents.md for non-visual DOM-backed work

Core workflow

1) Map the task to a surface

• Use a popup for one quick action or a short status glance.
• Use a side panel when the user needs a persistent workflow that survives browsing across tabs.
• Use an options page for preferences, onboarding, or admin-style settings.

2) Plan state handoff explicitly

• Assume popups are short-lived and can be reopened often.
• Persist any state that matters outside the popup.
• Keep long-running workflows in a side panel or extension page rather than in a popup that disappears on blur.

3) Separate invocation from experience

• Use commands and context menus to enter a workflow quickly.
• Route from those entry points into the popup, side panel, or direct page action that actually completes the task.

4) Reach for offscreen documents sparingly

• Use them only when the job requires DOM APIs unavailable to the service worker.
• Treat them as worker-adjacent infrastructure, not as a secret background app.

5) Validate discoverability and permissions

• Make sure the entry point matches user expectations.
• Confirm any surface-specific permissions or manifest fields are justified and documented.

Strong defaults

• Keep the popup minimal and deterministic.
• Use the side panel for workflows that need persistence or rich layout.
• Put setup and preference-heavy flows in options, not the popup.
• Bind commands and menus to meaningful actions, not generic "open extension" placeholders.

Anti-patterns

• Treating the popup like a full app shell with hidden long-lived state.
• Using an options page as the primary experience for daily tasks.
• Adding context menus everywhere without a crisp action model.
• Using offscreen documents to bypass architectural decisions.

Notes

• Primary references:
  • https://developer.chrome.com/docs/extensions/reference/sidePanel
  • https://developer.chrome.com/docs/extensions/reference/contextMenus/
  • https://developer.chrome.com/docs/extensions/reference/offscreen
• UI surface availability can change across Chromium channels. Re-check the current docs when picking a newer API such as side panel behavior.