Chrome Extensions UX/UI Best Practices

Comprehensive UX/UI design guide for Chrome Extensions, optimized for Manifest V3. Contains 42 rules across 8 categories, prioritized by impact to guide extension UI development and code review.

When to Apply

Reference these guidelines when:

• Building new Chrome extension user interfaces
• Choosing between popup, side panel, or content script UI
• Implementing accessible, keyboard-navigable interfaces
• Designing loading states, error handling, and feedback patterns
• Creating options pages and settings persistence

Rule Categories by Priority

Quick Reference

1. Component Selection (CRITICAL)

• comp-popup-vs-sidepanel – Choose Side Panel for Persistent Tasks
• comp-content-script-ui – Use Content Scripts for In-Page UI
• comp-single-purpose – Design for Single Purpose
• comp-minimal-permissions – Request Minimal Permissions
• comp-action-tooltip – Provide Descriptive Action Tooltips

2. Accessibility & Navigation (CRITICAL)

• access-keyboard-navigation – Enable Complete Keyboard Navigation
• access-focus-visible – Maintain Visible Focus Indicators
• access-aria-labels – Use ARIA Labels for Icon-Only Buttons
• access-color-contrast – Ensure Sufficient Color Contrast
• access-focus-trap – Avoid Keyboard Focus Traps
• access-semantic-html – Use Semantic HTML Elements

3. Popup Design (HIGH)

• popup-size-constraints – Design Within Popup Size Limits
• popup-instant-render – Render Popup Content Instantly
• popup-primary-action – Make the Primary Action Obvious
• popup-auto-close – Handle Popup Auto-Close Gracefully
• popup-external-js – Keep JavaScript in External Files
• popup-dynamic-switch – Use Dynamic Popups for State-Based UI

4. Side Panel UX (HIGH)

• panel-non-distracting – Design Non-Distracting Side Panels
• panel-tab-vs-window – Choose Tab-Specific vs Window-Wide Panels
• panel-responsive-width – Design for Variable Panel Widths
• panel-page-context – Sync Panel Content with Page Context
• panel-lazy-sections – Lazy Load Panel Sections

5. Content Script UI (MEDIUM-HIGH)

• inject-shadow-dom – Use Shadow DOM for Style Isolation
• inject-z-index – Use Maximum Z-Index for Overlays
• inject-document-ready – Inject UI After DOM Ready
• inject-unique-ids – Use Unique IDs to Prevent Conflicts
• inject-cleanup – Clean Up Injected Elements on Removal

6. Visual Feedback (MEDIUM)

• feedback-loading-states – Show Loading States for Async Operations
• feedback-error-messages – Write Actionable Error Messages
• feedback-badge-status – Use Badge for At-a-Glance Status
• feedback-success-confirmation – Confirm Successful Actions
• feedback-notifications – Use Notifications Sparingly
• feedback-progress-indication – Show Progress for Long Operations

7. Options & Settings (MEDIUM)

• options-embedded-page – Use Embedded Options for Simple Settings
• options-sync-storage – Sync Settings Across Devices
• options-auto-save – Auto-Save Settings on Change
• options-sensible-defaults – Provide Sensible Default Settings

8. Icons & Branding (LOW-MEDIUM)

• brand-icon-sizes – Provide All Required Icon Sizes
• brand-distinctive-icon – Design a Distinctive Toolbar Icon
• brand-badge-text – Keep Badge Text Under 4 Characters
• brand-consistent-styling – Maintain Consistent Visual Style
• brand-web-store-assets – Create Quality Web Store Assets

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions – Category structure and impact levels
• Rule template – Template for adding new rules

Reference Files