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

comp-

access-

popup-

panel-

inject-

feedback-

options-

brand-

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