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

Priority	Category	Impact	Prefix
1	Component Selection	CRITICAL	comp-
2	Accessibility & Navigation	CRITICAL	access-
3	Popup Design	HIGH	popup-
4	Side Panel UX	HIGH	panel-
5	Content Script UI	MEDIUM-HIGH	inject-
6	Visual Feedback	MEDIUM	feedback-
7	Options & Settings	MEDIUM	options-
8	Icons & Branding	LOW-MEDIUM	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

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information