Chrome Extension Ui

# Chrome Extensions

**Version 0.1.0**  
Chrome Extensions Community  
January 2026

> **Note:**  
> This document is mainly for agents and LLMs to follow when maintaining,  
> generating, or refactoring codebases. Humans may also find it useful,  
> but guidance here is optimized for automation and consistency by AI-assisted workflows.

---

## Abstract

Comprehensive UX/UI design guide for Chrome Extensions, optimized for Manifest V3. Contains 42 rules across 8 categories, prioritized by impact from critical (component selection, accessibility) to incremental (icons and branding). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide extension development and code review.

---

## Table of Contents

1. [Component Selection](references/_sections.md#1-component-selection) — **CRITICAL**
   - 1.1 [Choose Side Panel for Persistent Tasks](references/comp-popup-vs-sidepanel.md) — CRITICAL (5-10× longer engagement sessions)
   - 1.2 [Design for Single Purpose](references/comp-single-purpose.md) — CRITICAL (required for Chrome Web Store approval)
   - 1.3 [Provide Descriptive Action Tooltips](references/comp-action-tooltip.md) — CRITICAL (prevents user confusion and misdirected clicks)
   - 1.4 [Request Minimal Permissions](references/comp-minimal-permissions.md) — CRITICAL (40-60% higher install conversion rate)
   - 1.5 [Use Content Scripts for In-Page UI](references/comp-content-script-ui.md) — CRITICAL (eliminates context switching entirely)
2. [Accessibility & Navigation](references/_sections.md#2-accessibility-&-navigation) — **CRITICAL**
   - 2.1 [Avoid Keyboard Focus Traps](references/access-focus-trap.md) — CRITICAL (WCAG 2.1.2 - users must be able to exit any UI)
   - 2.2 [Enable Complete Keyboard Navigation](references/access-keyboard-navigation.md) — CRITICAL (required for accessibility compliance)
   - 2.3 [Ensure Sufficient Color Contrast](references/access-color-contrast.md) — CRITICAL (WCAG AA requires 4.5:1 for normal text)
   - 2.4 [Maintain Visible Focus Indicators](references/access-focus-visible.md) — CRITICAL (WCAG 2.4.7 requirement for keyboard users)
   - 2.5 [Use ARIA Labels for Icon-Only Buttons](references/access-aria-labels.md) — CRITICAL (makes UI comprehensible to screen reader users)
   - 2.6 [Use Semantic HTML Elements](references/access-semantic-html.md) — CRITICAL (built-in keyboard and screen reader support)
3. [Popup Design](references/_sections.md#3-popup-design) — **HIGH**
   - 3.1 [Design Within Popup Size Limits](references/popup-size-constraints.md) — HIGH (prevents content clipping and scroll issues)
   - 3.2 [Handle Popup Auto-Close Gracefully](references/popup-auto-close.md) — HIGH (prevents data loss and user frustration)
   - 3.3 [Keep JavaScript in External Files](references/popup-external-js.md) — HIGH (required by Content Security Policy)
   - 3.4 [Make the Primary Action Obvious](references/popup-primary-action.md) — HIGH (reduces time-to-action by 60-80%)
   - 3.5 [Render Popup Content Instantly](references/popup-instant-render.md) — HIGH (200-500ms perceived as laggy by users)
   - 3.6 [Use Dynamic Popups for State-Based UI](references/popup-dynamic-switch.md) — HIGH (reduces cognitive load by showing relevant UI)
4. [Side Panel UX](references/_sections.md#4-side-panel-ux) — **HIGH**
   - 4.1 [Choose Tab-Specific vs Window-Wide Panels](references/panel-tab-vs-window.md) — HIGH (determines context relevance and user expectations)
   - 4.2 [Design for Variable Panel Widths](references/panel-responsive-width.md) — HIGH (prevents layout breaking when users resize)
   - 4.3 [Design Non-Distracting Side Panels](references/panel-non-distracting.md) — HIGH (increases session duration by 3-5×)
   - 4.4 [Lazy Load Panel Sections](references/panel-lazy-sections.md) — HIGH (50-80% faster initial panel render)
   - 4.5 [Sync Panel Content with Page Context](references/panel-page-context.md) — HIGH (mak