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