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
| 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
| references/_sections.md | Category definitions and ordering
| assets/templates/_template.md | Template for new rules
| metadata.json | Version and reference information