providing-feedback

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Providing User Feedback and Notifications

用户反馈与通知实现指南

This skill implements comprehensive feedback and notification systems that enhance all other component skills by providing consistent patterns for communicating system state, displaying messages, and handling user confirmations.

本Skill实现了全面的反馈与通知系统，通过提供一致的模式来传达系统状态、展示消息和处理用户确认，从而增强所有其他组件Skill的功能。

When to Use This Skill

适用场景

Activate this skill when:

Implementing toast notifications or snackbars
Displaying success, error, warning, or info messages
Creating modal dialogs or confirmation dialogs
Implementing progress indicators (spinners, progress bars, skeleton screens)
Designing empty states or zero-result displays
Adding tooltips or contextual help
Determining notification timing, stacking, or positioning
Implementing accessible feedback patterns with ARIA
Communicating any system state to users

在以下场景中启用本Skill：

实现Toast通知或Snackbar
展示成功、错误、警告或提示消息
创建模态对话框（Modal Dialog）或确认对话框
实现进度指示器（加载动画、进度条、骨架屏）
设计空状态或无结果展示
添加工具提示（Tooltip）或上下文帮助
确定通知的显示时长、堆叠方式或位置
实现符合ARIA标准的无障碍反馈模式
向用户传达任何系统状态

Feedback Type Decision Matrix

反馈类型决策矩阵

Choose the appropriate feedback mechanism based on urgency and attention requirements:

Critical + Blocking       → Modal Dialog
Important + Non-blocking  → Alert Banner
Success/Info + Temporary  → Toast/Snackbar
Contextual Help          → Tooltip/Popover
In-progress              → Progress Indicator
No Data                  → Empty State

根据信息的紧急程度和注意力要求选择合适的反馈机制：

Critical + Blocking       → Modal Dialog
Important + Non-blocking  → Alert Banner
Success/Info + Temporary  → Toast/Snackbar
Contextual Help          → Tooltip/Popover
In-progress              → Progress Indicator
No Data                  → Empty State

Quick Reference by Urgency

按紧急程度快速参考

Urgency Level	Component	Duration	Blocks Interaction
Critical	Modal Dialog	Until action	Yes
Important	Alert Banner	Until dismissed	No
Standard	Toast	3-7 seconds	No
Contextual	Inline Message	Persistent	No
Help	Tooltip	On hover	No
Progress	Spinner/Bar	During operation	Optional

紧急程度	组件	持续时长	是否阻断交互
Critical（紧急）	Modal Dialog	直到用户操作	是
Important（重要）	Alert Banner	直到用户关闭	否
Standard（标准）	Toast	3-7秒	否
Contextual（上下文相关）	Inline Message	持续显示	否
Help（帮助）	Tooltip	悬停时显示	否
Progress（进度）	Spinner/Bar	操作进行中	可选

Implementation Approach

实现步骤

Step 1: Determine Feedback Type

步骤1：确定反馈类型

Assess the situation using these criteria:

Urgency: How critical is the information?
Duration: How long should it persist?
Action Required: Does user need to respond?
Context: Is it related to specific UI element?

根据以下标准评估场景：

紧急程度：信息的关键程度如何？
持续时长：信息需要保留多久？
是否需要操作：用户是否需要做出响应？
上下文：是否与特定UI元素相关？

Step 2: Choose Implementation Pattern

步骤2：选择实现模式

For Toasts/Snackbars:

Position: Bottom-right (recommended)
Duration: 3-4s (success), 5-7s (warning), 7-10s (error)
Stack limit: 3-5 maximum
See
```
references/toast-patterns.md
```
for detailed patterns

For Modal Dialogs:

Focus management: Trap focus within modal
Accessibility: ESC to close, proper ARIA labels
Backdrop: Click outside to close (optional)
See
```
references/modal-patterns.md
```
for implementation

For Progress Indicators:

<100ms: No indicator needed
100ms-5s: Spinner with message
5s-30s: Progress bar (determinate if possible)
30s: Progress bar + time estimate + cancel
See
```
references/progress-indicators.md
```
for patterns

For Empty States:

Include: Illustration, headline, body text, CTA
Types: First use, zero results, error, permission denied
See
```
references/empty-states.md
```
for designs

Toast/Snackbar实现：

位置：右下角（推荐）
时长：成功提示3-4秒，警告提示5-7秒，错误提示7-10秒
堆叠上限：最多3-5个
详细模式请参考
```
references/toast-patterns.md
```

Modal Dialog实现：

焦点管理：将焦点限制在模态框内
无障碍支持：按ESC关闭，设置正确的ARIA标签
背景层：可选择点击外部关闭
实现细节请参考
```
references/modal-patterns.md
```

进度指示器实现：

<100ms：无需指示器
100ms-5s：带提示文字的加载动画（Spinner）
5s-30s：进度条（尽可能使用确定型进度条）
30s：进度条 + 时间预估 + 取消按钮
模式参考
```
references/progress-indicators.md
```

空状态实现：

包含元素：插图、标题、正文、CTA按钮
类型：首次使用、无结果、错误、权限拒绝
设计参考
```
references/empty-states.md
```

Step 3: Implement with Recommended Libraries

步骤3：使用推荐库实现

Modern React Stack (Recommended):

bash

npm install sonner @radix-ui/react-dialog

For Toasts - Use Sonner:

tsx

import { Toaster, toast } from 'sonner';

// In your app root
<Toaster position="bottom-right" />

// Trigger notifications
toast.success('Changes saved successfully');
toast.promise(saveData(), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Failed to save'
});

For Modals - Use Radix UI:

tsx

import * as Dialog from '@radix-ui/react-dialog';

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

See

references/library-comparison.md

for alternative libraries and selection criteria.

现代React技术栈（推荐）：

bash

npm install sonner @radix-ui/react-dialog

Toast组件 - 使用Sonner：

tsx

import { Toaster, toast } from 'sonner';

// 在应用根组件中
<Toaster position="bottom-right" />

// 触发通知
toast.success('Changes saved successfully');
toast.promise(saveData(), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Failed to save'
});

Modal组件 - 使用Radix UI：

tsx

import * as Dialog from '@radix-ui/react-dialog';

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

替代库及选择标准请参考

references/library-comparison.md

。

Step 4: Apply Accessibility Patterns

步骤4：应用无障碍模式

ARIA Live Regions for Announcements:

html

<!-- For non-critical notifications -->
<div role="status" aria-live="polite">
  File uploaded successfully
</div>

<!-- For critical alerts -->
<div role="alert" aria-live="assertive">
  Error: Failed to save
</div>

Focus Management for Modals:

Save current focus before opening
Move focus to first interactive element in modal
Trap focus within modal (Tab cycles)
Restore focus to trigger on close

See

references/accessibility-feedback.md

for complete patterns.

用于消息播报的ARIA实时区域：

html

<!-- 非关键通知 -->
<div role="status" aria-live="polite">
  File uploaded successfully
</div>

<!-- 关键警报 -->
<div role="alert" aria-live="assertive">
  Error: Failed to save
</div>

Modal组件的焦点管理：

打开前保存当前焦点
将焦点移动到Modal内第一个可交互元素
将焦点限制在Modal内（Tab键循环）
关闭后恢复焦点到触发元素

完整模式请参考

references/accessibility-feedback.md

。

Step 5: Integrate Design Tokens

步骤5：集成设计令牌

All feedback components use the design-tokens skill for consistent theming:

css

/* Example token usage */
.toast {
  background: var(--toast-bg);
  color: var(--toast-text);
  padding: var(--toast-padding);
  border-radius: var(--toast-border-radius);
  box-shadow: var(--toast-shadow);
  animation-duration: var(--toast-enter-duration);
}

Token categories used:

Colors: Toast, alert, modal, tooltip backgrounds
Spacing: Internal padding for all components
Typography: Font sizes for titles and messages
Shadows: Elevation for floating elements
Motion: Animation durations and easing

所有反馈组件通过design-tokens Skill实现一致的主题样式：

css

/* 令牌使用示例 */
.toast {
  background: var(--toast-bg);
  color: var(--toast-text);
  padding: var(--toast-padding);
  border-radius: var(--toast-border-radius);
  box-shadow: var(--toast-shadow);
  animation-duration: var(--toast-enter-duration);
}

使用的令牌类别：

颜色：Toast、Alert、Modal、Tooltip的背景色
间距：所有组件的内边距
排版：标题和消息的字体大小
阴影：浮动元素的层级阴影
动画：动画时长和缓动效果

Notification Timing Guidelines

通知时长指南

Auto-dismiss durations:

Success: 3-4 seconds
Info: 4-5 seconds
Warning: 5-7 seconds
Error: 7-10 seconds or manual dismiss
With action button: 10+ seconds or no auto-dismiss

Progress indicator thresholds:

<100ms: No indicator
100ms-5s: Spinner
5s-30s: Progress bar
30s: Progress bar + cancel option

自动关闭时长：

成功提示：3-4秒
提示信息：4-5秒
警告提示：5-7秒
错误提示：7-10秒或手动关闭
带操作按钮：10秒以上或不自动关闭

进度指示器阈值：

<100ms：无需指示器
100ms-5s：加载动画（Spinner）
5s-30s：进度条
30s：进度条 + 取消选项

Resources

资源

Scripts (Token-Free Execution)

脚本（无需令牌即可执行）

```
scripts/generate_toast_manager.js
```
- Generate toast configurations with timing and stacking
```
scripts/format_messages.py
```
- Format user-facing messages based on context
```
scripts/calculate_timing.js
```
- Calculate auto-dismiss timings

```
scripts/generate_toast_manager.js
```
- 生成包含时长和堆叠规则的Toast配置
```
scripts/format_messages.py
```
- 根据上下文格式化用户可见消息
```
scripts/calculate_timing.js
```
- 计算自动关闭时长

References (Detailed Documentation)

参考文档（详细说明）

```
references/toast-patterns.md
```
- Toast positioning, stacking, animations
```
references/alert-patterns.md
```
- Alert banner implementations
```
references/modal-patterns.md
```
- Modal dialogs with focus management
```
references/progress-indicators.md
```
- Loading states and progress
```
references/empty-states.md
```
- No-data and zero-result patterns
```
references/accessibility-feedback.md
```
- ARIA patterns and focus management
```
references/library-comparison.md
```
- Detailed library analysis

```
references/toast-patterns.md
```
- Toast的位置、堆叠、动画
```
references/alert-patterns.md
```
- Alert Banner的实现
```
references/modal-patterns.md
```
- 带焦点管理的Modal Dialog
```
references/progress-indicators.md
```
- 加载状态和进度展示
```
references/empty-states.md
```
- 无数据和无结果模式
```
references/accessibility-feedback.md
```
- ARIA模式和焦点管理
```
references/library-comparison.md
```
- 详细的库对比分析

Examples (Implementation Code)

示例代码（实现示例）

```
examples/success-toast.tsx
```
- Success notification with Sonner
```
examples/confirmation-modal.tsx
```
- Delete confirmation with Radix UI
```
examples/progress-upload.tsx
```
- File upload with progress bar
```
examples/inline-validation.tsx
```
- Form validation errors

```
examples/success-toast.tsx
```
- 使用Sonner实现的成功通知
```
examples/confirmation-modal.tsx
```
- 使用Radix UI实现的删除确认框
```
examples/progress-upload.tsx
```
- 带进度条的文件上传
```
examples/inline-validation.tsx
```
- 表单验证错误提示

Assets (Templates and Configs)

资源文件（模板和配置）

```
assets/message-templates.json
```
- Reusable message templates
```
assets/error-catalog.json
```
- Error code to message mappings
```
assets/timing-config.json
```
- Timing recommendations

```
assets/message-templates.json
```
- 可复用的消息模板
```
assets/error-catalog.json
```
- 错误码与消息映射
```
assets/timing-config.json
```
- 时长建议配置

Cross-Skill Integration

跨Skill集成

This skill enhances all other component skills:

Forms: Validation feedback, success confirmations
Data Visualization: Loading states, error messages
Tables: Bulk operation feedback, action confirmations
AI Chat: Streaming indicators, rate limit warnings
Dashboards: Widget loading, system status
Search/Filter: Zero results, search progress
Media: Upload progress, processing status
Design Tokens: All visual styling via token system

本Skill可增强所有其他组件Skill：

Forms：验证反馈、成功确认
Data Visualization：加载状态、错误消息
Tables：批量操作反馈、操作确认
AI Chat：流加载指示器、速率限制警告
Dashboards：组件加载、系统状态
Search/Filter：无结果提示、搜索进度
Media：上传进度、处理状态
Design Tokens：所有视觉样式通过令牌系统实现

Library Quick Comparison

库快速对比

Library	Type	Size	Best For
Sonner	Toast	Small	Modern React 18+, accessibility
react-hot-toast	Toast	<5KB	Minimal bundle size
react-toastify	Toast	~16KB	RTL support, mobile
Radix UI	Modal	Small	Design systems, headless
Headless UI	Modal	Small	Tailwind projects

Choose based on project requirements. See

references/library-comparison.md

for detailed analysis.

库	类型	大小	最佳适用场景
Sonner	Toast	小	现代React 18+、无障碍支持
react-hot-toast	Toast	<5KB	最小包体积
react-toastify	Toast	~16KB	RTL支持、移动端
Radix UI	Modal	小	设计系统、无头组件
Headless UI	Modal	小	Tailwind项目

根据项目需求选择，详细分析请参考

references/library-comparison.md

。

Key Principles

核心原则

Match urgency to attention: Don't use modals for non-critical info
Be consistent: Same feedback type for similar actions
Provide context: Explain what happened and what to do
Enable recovery: Include undo, retry, or help options
Respect preferences: Honor reduced motion settings
Test accessibility: Verify with screen readers and keyboard

紧急程度匹配注意力：非关键信息不要使用Modal
保持一致性：相似操作使用相同的反馈类型
提供上下文：说明发生了什么以及该怎么做
支持恢复：包含撤销、重试或帮助选项
尊重偏好：遵循减少动画的设置
测试无障碍：使用屏幕阅读器和键盘验证