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](references/comp-popup-vs-sidepanel.md) - Choose Side Panel for Persistent Tasks
• [comp-content-script-ui](references/comp-content-script-ui.md) - Use Content Scripts for In-Page UI
• [comp-single-purpose](references/comp-single-purpose.md) - Design for Single Purpose
• [comp-minimal-permissions](references/comp-minimal-permissions.md) - Request Minimal Permissions
• [comp-action-tooltip](references/comp-action-tooltip.md) - Provide Descriptive Action Tooltips

2. Accessibility & Navigation (CRITICAL)

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

3. Popup Design (HIGH)

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

4. Side Panel UX (HIGH)

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

5. Content Script UI (MEDIUM-HIGH)

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

6. Visual Feedback (MEDIUM)

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

7. Options & Settings (MEDIUM)

• [options-embedded-page](references/options-embedded-page.md) - Use Embedded Options for Simple Settings
• [options-sync-storage](references/options-sync-storage.md) - Sync Settings Across Devices
• [options-auto-save](references/options-auto-save.md) - Auto-Save Settings on Change
• [options-sensible-defaults](references/options-sensible-defaults.md) - Provide Sensible Default Settings

8. Icons & Branding (LOW-MEDIUM)

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

How to Use

Read individual reference files for detailed explanations and code examples:

• [Section definitions](references/_sections.md) - Category structure and impact levels
• [Rule template](assets/templates/_template.md) - Template for adding new rules

Reference Files