chrome-extension-ui

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