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 — CRITICAL
   • 1.1 Choose Side Panel for Persistent Tasks — CRITICAL (5-10× longer engagement sessions)
   • 1.2 Design for Single Purpose — CRITICAL (required for Chrome Web Store approval)
   • 1.3 Provide Descriptive Action Tooltips — CRITICAL (prevents user confusion and misdirected clicks)
   • 1.4 Request Minimal Permissions — CRITICAL (40-60% higher install conversion rate)
   • 1.5 Use Content Scripts for In-Page UI — CRITICAL (eliminates context switching entirely)
2. Accessibility & Navigation — CRITICAL
   • 2.1 Avoid Keyboard Focus Traps — CRITICAL (WCAG 2.1.2 - users must be able to exit any UI)
   • 2.2 Enable Complete Keyboard Navigation — CRITICAL (required for accessibility compliance)
   • 2.3 Ensure Sufficient Color Contrast — CRITICAL (WCAG AA requires 4.5:1 for normal text)
   • 2.4 Maintain Visible Focus Indicators — CRITICAL (WCAG 2.4.7 requirement for keyboard users)
   • 2.5 Use ARIA Labels for Icon-Only Buttons — CRITICAL (makes UI comprehensible to screen reader users)
   • 2.6 Use Semantic HTML Elements — CRITICAL (built-in keyboard and screen reader support)
3. Popup Design — HIGH
   • 3.1 Design Within Popup Size Limits — HIGH (prevents content clipping and scroll issues)
   • 3.2 Handle Popup Auto-Close Gracefully — HIGH (prevents data loss and user frustration)
   • 3.3 Keep JavaScript in External Files — HIGH (required by Content Security Policy)
   • 3.4 Make the Primary Action Obvious — HIGH (reduces time-to-action by 60-80%)
   • 3.5 Render Popup Content Instantly — HIGH (200-500ms perceived as laggy by users)
   • 3.6 Use Dynamic Popups for State-Based UI — HIGH (reduces cognitive load by showing relevant UI)
4. Side Panel UX — HIGH
   • 4.1 Choose Tab-Specific vs Window-Wide Panels — HIGH (determines context relevance and user expectations)
   • 4.2 Design for Variable Panel Widths — HIGH (prevents layout breaking when users resize)
   • 4.3 Design Non-Distracting Side Panels — HIGH (increases session duration by 3-5×)
   • 4.4 Lazy Load Panel Sections — HIGH (50-80% faster initial panel render)
   • 4.5 Sync Panel Content with Page Context — HIGH (makes panel feel integrated rather than disconnected)
5. Content Script UI — MEDIUM-HIGH
   • 5.1 Clean Up Injected Elements on Removal — MEDIUM-HIGH (prevents memory leaks and DOM pollution)
   • 5.2 Inject UI After DOM Ready — MEDIUM-HIGH (prevents null reference errors and race conditions)
   • 5.3 Use Maximum Z-Index for Overlays — MEDIUM-HIGH (ensures UI visibility on all websites)
   • 5.4 Use Shadow DOM for Style Isolation — MEDIUM-HIGH (prevents 100% of CSS conflicts with host pages)
   • 5.5 Use Unique IDs to Prevent Conflicts — MEDIUM-HIGH (prevents ID collision with page elements)
6. Visual Feedback — MEDIUM
   • 6.1 Confirm Successful Actions — MEDIUM (builds user confidence and trust)
   • 6.2 Show Loading States for Async Operations — MEDIUM (reduces perceived wait time by 40%)
   • 6.3 Show Progress for Long Operations — MEDIUM (reduces abandonment during multi-step processes)
   • 6.4 Use Badge for At-a-Glance Status — MEDIUM (communicates state without opening extension)
   • 6.5 Use Notifications Sparingly — MEDIUM (prevents notification fatigue and user annoyance)
   • 6.6 Write Actionable Error Messages — MEDIUM (60% faster error recovery when users know what to do)
7. Options & Settings — MEDIUM
   • 7.1 Auto-Save Settings on Change — MEDIUM (eliminates lost settings and save button friction)
   • 7.2 Provide Sensible Default Settings — MEDIUM (extension works immediately without configuration)
   • 7.3 Sync Settings Across Devices — MEDIUM (seamless experience across user's computers)
   • 7.4 Use Embedded Options for Simple Settings — MEDIUM (keeps users in context without tab switching)
8. Icons & Branding — LOW-MEDIUM
   • 8.1 Create Quality Web Store Assets — LOW-MEDIUM (30-50% higher conversion from store listing)
   • 8.2 Design a Distinctive Toolbar Icon — LOW-MEDIUM (improves findability in crowded toolbar)
   • 8.3 Keep Badge Text Under 4 Characters — LOW-MEDIUM (ensures text is fully visible on toolbar)
   • 8.4 Maintain Consistent Visual Style — LOW-MEDIUM (builds brand recognition and professional appearance)
   • 8.5 Provide All Required Icon Sizes — LOW-MEDIUM (ensures crisp display across all contexts)

References

1. https://developer.chrome.com/docs/extensions/develop/ui
2. https://developer.chrome.com/docs/extensions/mv3/a11y/
3. https://developer.chrome.com/docs/webstore/best-practices
4. https://developer.chrome.com/docs/extensions/develop/ui/add-popup
5. https://developer.chrome.com/docs/extensions/reference/api/sidePanel
6. https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts
7. https://developer.chrome.com/docs/webstore/branding
8. https://www.w3.org/WAI/WCAG21/Understanding/

Source Files

This document was compiled from individual reference files. For detailed editing or extension: