SKILL.md
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
Category definitions and ordering
Template for new rules
Version and reference information