chrome-extension-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chrome Extensions UX/UI Best Practices

Chrome扩展UX/UI最佳实践

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.

这是一份针对Chrome扩展的全面UX/UI设计指南，已针对Manifest V3优化。指南包含8个类别共42条规则，按影响优先级排序，可用于指导扩展UI开发与代码评审。

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

在以下场景中可参考本指南：

构建新的Chrome扩展用户界面
在弹窗、侧边面板或内容脚本UI之间做选择
实现支持键盘导航的无障碍界面
设计加载状态、错误处理与反馈模式
创建选项页并实现设置持久化

Rule Categories by Priority

按优先级划分的规则类别


comp-
access-
popup-
panel-
inject-
feedback-
options-
brand-

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-`


comp-
access-
popup-
panel-
inject-
feedback-
options-
brand-

优先级	类别	影响程度	前缀
1	组件选择	关键	`comp-`
2	无障碍与导航	关键	`access-`
3	弹窗设计	高	`popup-`
4	侧边面板体验	高	`panel-`
5	内容脚本UI	中高	`inject-`
6	视觉反馈	中	`feedback-`
7	选项与设置	中	`options-`
8	图标与品牌	中低	`brand-`

Quick Reference

快速参考

1. Component Selection (CRITICAL)

1. 组件选择（关键）

```
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

```
comp-popup-vs-sidepanel
```
- 持久化任务优先选择侧边面板
```
comp-content-script-ui
```
- 内容脚本用于页面内嵌UI
```
comp-single-purpose
```
- 按单一用途设计
```
comp-minimal-permissions
```
- 请求最小权限
```
comp-action-tooltip
```
- 提供描述性操作提示

2. Accessibility & Navigation (CRITICAL)

2. 无障碍与导航（关键）

```
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

```
access-keyboard-navigation
```
- 支持完整键盘导航
```
access-focus-visible
```
- 保持可见的焦点指示器
```
access-aria-labels
```
- 纯图标按钮使用ARIA标签
```
access-color-contrast
```
- 确保足够的色彩对比度
```
access-focus-trap
```
- 避免键盘焦点陷阱
```
access-semantic-html
```
- 使用语义化HTML元素

3. Popup Design (HIGH)

3. 弹窗设计（高）

```
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

```
popup-size-constraints
```
- 在弹窗尺寸限制内设计
```
popup-instant-render
```
- 即时渲染弹窗内容
```
popup-primary-action
```
- 突出显示主要操作
```
popup-auto-close
```
- 优雅处理弹窗自动关闭
```
popup-external-js
```
- 将JavaScript放在外部文件中
```
popup-dynamic-switch
```
- 基于状态使用动态弹窗

4. Side Panel UX (HIGH)

4. 侧边面板体验（高）

```
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

```
panel-non-distracting
```
- 设计无干扰的侧边面板
```
panel-tab-vs-window
```
- 选择标签页专属或全窗口面板
```
panel-responsive-width
```
- 适配可变面板宽度
```
panel-page-context
```
- 同步面板内容与页面上下文
```
panel-lazy-sections
```
- 懒加载面板分区

5. Content Script UI (MEDIUM-HIGH)

5. 内容脚本UI（中高）

```
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

```
inject-shadow-dom
```
- 使用Shadow DOM实现样式隔离
```
inject-z-index
```
- 叠加层使用最大Z-index
```
inject-document-ready
```
- DOM加载完成后注入UI
```
inject-unique-ids
```
- 使用唯一ID避免冲突
```
inject-cleanup
```
- 移除时清理注入元素

6. Visual Feedback (MEDIUM)

6. 视觉反馈（中）

```
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

```
feedback-loading-states
```
- 异步操作显示加载状态
```
feedback-error-messages
```
- 编写可操作的错误提示
```
feedback-badge-status
```
- 使用徽章展示概览状态
```
feedback-success-confirmation
```
- 确认操作成功
```
feedback-notifications
```
- 谨慎使用通知
```
feedback-progress-indication
```
- 长时操作显示进度

7. Options & Settings (MEDIUM)

7. 选项与设置（中）

```
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

```
options-embedded-page
```
- 简单设置使用内嵌选项页
```
options-sync-storage
```
- 跨设备同步设置
```
options-auto-save
```
- 更改设置时自动保存
```
options-sensible-defaults
```
- 提供合理的默认设置

8. Icons & Branding (LOW-MEDIUM)

8. 图标与品牌（中低）

```
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

```
brand-icon-sizes
```
- 提供所有要求的图标尺寸
```
brand-distinctive-icon
```
- 设计独特的工具栏图标
```
brand-badge-text
```
- 徽章文本不超过4个字符
```
brand-consistent-styling
```
- 保持视觉风格一致
```
brand-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

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息