Back to Details

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 LevelComponentDurationBlocks Interaction
CriticalModal DialogUntil actionYes
ImportantAlert BannerUntil dismissedNo
StandardToast3-7 secondsNo
ContextualInline MessagePersistentNo
HelpTooltipOn hoverNo
ProgressSpinner/BarDuring operationOptional
紧急程度组件持续时长是否阻断交互
Critical（紧急）Modal Dialog直到用户操作是
Important（重要）Alert Banner直到用户关闭否
Standard（标准）Toast3-7秒否
Contextual（上下文相关）Inline Message持续显示否
Help（帮助）Tooltip悬停时显示否
Progress（进度）Spinner/Bar操作进行中可选

Implementation Approach

实现步骤

Step 1: Determine Feedback Type

步骤1：确定反馈类型

Assess the situation using these criteria:
  1. Urgency: How critical is the information?
  2. Duration: How long should it persist?
  3. Action Required: Does user need to respond?
  4. Context: Is it related to specific UI element?
根据以下标准评估场景：
  1. 紧急程度：信息的关键程度如何？
  2. 持续时长：信息需要保留多久？
  3. 是否需要操作：用户是否需要做出响应？
  4. 上下文：是否与特定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:
  1. Save current focus before opening
  2. Move focus to first interactive element in modal
  3. Trap focus within modal (Tab cycles)
  4. 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组件的焦点管理：
  1. 打开前保存当前焦点
  2. 将焦点移动到Modal内第一个可交互元素
  3. 将焦点限制在Modal内（Tab键循环）
  4. 关闭后恢复焦点到触发元素
完整模式请参考
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

库快速对比

LibraryTypeSizeBest For
SonnerToastSmallModern React 18+, accessibility
react-hot-toastToast<5KBMinimal bundle size
react-toastifyToast~16KBRTL support, mobile
Radix UIModalSmallDesign systems, headless
Headless UIModalSmallTailwind projects
Choose based on project requirements. See 
references/library-comparison.md
for detailed analysis.
库类型大小最佳适用场景
SonnerToast小现代React 18+、无障碍支持
react-hot-toastToast<5KB最小包体积
react-toastifyToast~16KBRTL支持、移动端
Radix UIModal小设计系统、无头组件
Headless UIModal小Tailwind项目
根据项目需求选择，详细分析请参考
references/library-comparison.md
。

Key Principles

核心原则

  1. Match urgency to attention: Don't use modals for non-critical info
  2. Be consistent: Same feedback type for similar actions
  3. Provide context: Explain what happened and what to do
  4. Enable recovery: Include undo, retry, or help options
  5. Respect preferences: Honor reduced motion settings
  6. Test accessibility: Verify with screen readers and keyboard
  1. 紧急程度匹配注意力：非关键信息不要使用Modal
  2. 保持一致性：相似操作使用相同的反馈类型
  3. 提供上下文：说明发生了什么以及该怎么做
  4. 支持恢复：包含撤销、重试或帮助选项
  5. 尊重偏好：遵循减少动画的设置
  6. 测试无障碍：使用屏幕阅读器和键盘验证