name: providing-feedback description: 实现反馈和通知系统，包括toast通知、警报、模态对话框、进度指示器和错误状态。用于通信系统状态、显示消息、确认操作或显示错误。

提供用户反馈和通知

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

何时使用此技能

在以下情况下激活此技能：

实现toast通知或snackbars
显示成功、错误、警告或信息消息
创建模态对话框或确认对话框
实现进度指示器（spinners、进度条、骨架屏幕）
设计空状态或零结果显示
添加工具提示或上下文帮助
确定通知时机、堆叠或定位
实现可访问的反馈模式，使用ARIA
通信任何系统状态给用户

反馈类型决策矩阵

基于紧急性和注意力要求选择适当的反馈机制：

关键 + 阻塞       → 模态对话框
重要 + 非阻塞    → 警报横幅
成功/信息 + 临时 → Toast/Snackbar
上下文帮助       → 工具提示/弹出框
进行中           → 进度指示器
无数据           → 空状态

按紧急性快速参考

紧急级别	组件	持续时间	阻塞交互
关键	模态对话框	直到操作	是
重要	警报横幅	直到关闭	否
标准	Toast	3-7 秒	否
上下文	内联消息	持久	否
帮助	工具提示	悬停时	否
进度	Spinner/Bar	操作期间	可选

实现方法

步骤 1: 确定反馈类型

使用以下标准评估情况：

紧急性: 信息有多关键？
持续时间: 应持续多久？
需要操作: 用户是否需要响应？
上下文: 是否与特定UI元素相关？

步骤 2: 选择实现模式

对于Toasts/Snackbars:

位置: 右下角（推荐）
持续时间: 3-4秒（成功），5-7秒（警告），7-10秒（错误）
堆叠限制: 最多3-5个
参见 references/toast-patterns.md 获取详细模式

对于模态对话框:

焦点管理: 在模态内捕获焦点
可访问性: ESC关闭，适当的ARIA标签
背景: 点击外部关闭（可选）
参见 references/modal-patterns.md 获取实现

对于进度指示器:

<100毫秒: 无需指示器
100毫秒-5秒: Spinner带消息
5秒-30秒: 进度条（尽可能可确定）
30秒: 进度条 + 时间估计 + 取消
参见 references/progress-indicators.md 获取模式

对于空状态:

包括: 插图、标题、正文文本、CTA
类型: 首次使用、零结果、错误、权限被拒
参见 references/empty-states.md 获取设计

步骤 3: 使用推荐库实现

现代React堆栈（推荐）:

npm install sonner @radix-ui/react-dialog

对于Toasts - 使用Sonner:

import { Toaster, toast } from 'sonner';

// 在应用根目录
<Toaster position="bottom-right" />

// 触发通知
toast.success('更改成功保存');
toast.promise(saveData(), {
  loading: '保存中...',
  success: '已保存！',
  error: '保存失败'
});

对于Modals - 使用Radix UI:

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

<Dialog.Root>
  <Dialog.Trigger>打开</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Title>确认操作</Dialog.Title>
      <Dialog.Description>确定吗？</Dialog.Description>
      <Dialog.Close>取消</Dialog.Close>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog.Root>

参见 references/library-comparison.md 获取替代库和选择标准。

步骤 4: 应用可访问性模式

用于公告的ARIA Live Regions:

<!-- 对于非关键通知 -->
<div role="status" aria-live="polite">
  文件上传成功
</div>

<!-- 对于关键警报 -->
<div role="alert" aria-live="assertive">
  错误: 保存失败
</div>

对于Modals的焦点管理:

打开前保存当前焦点
将焦点移动到模态中的第一个交互元素
在模态内捕获焦点（Tab循环）
关闭时将焦点恢复到触发器

参见 references/accessibility-feedback.md 获取完整模式。

步骤 5: 集成设计令牌

所有反馈组件使用设计令牌技能进行一致的主题化：

/* 示例令牌使用 */
.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、警报、模态、工具提示背景
间距: 所有组件的内部填充
排版: 标题和消息的字体大小
阴影: 浮动元素的提升
动效: 动画持续时间和缓动

通知时机指南

自动关闭持续时间:

成功: 3-4 秒
信息: 4-5 秒
警告: 5-7 秒
错误: 7-10 秒或手动关闭
带操作按钮: 10+ 秒或无自动关闭

进度指示器阈值:

<100毫秒: 无指示器
100毫秒-5秒: Spinner
5秒-30秒: 进度条
30秒: 进度条 + 取消选项

资源

脚本（无令牌执行）

scripts/generate_toast_manager.js - 生成带时机和堆叠的toast配置
scripts/format_messages.py - 基于上下文格式化用户面向的消息
scripts/calculate_timing.js - 计算自动关闭时机

参考资料（详细文档）

references/toast-patterns.md - Toast定位、堆叠、动画
references/alert-patterns.md - 警报横幅实现
references/modal-patterns.md - 模态对话框与焦点管理
references/progress-indicators.md - 加载状态和进度
references/empty-states.md - 无数据和零结果模式
references/accessibility-feedback.md - ARIA模式和焦点管理
references/library-comparison.md - 详细库分析

示例（实现代码）

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

资产（模板和配置）

assets/message-templates.json - 可重用消息模板
assets/error-catalog.json - 错误代码到消息映射
assets/timing-config.json - 时机推荐

跨技能集成

此技能增强所有其他组件技能：

表单: 验证反馈、成功确认
数据可视化: 加载状态、错误消息
表格: 批量操作反馈、操作确认
AI聊天: 流式指示器、速率限制警告
仪表板: 小部件加载、系统状态
搜索/过滤: 零结果、搜索进度
媒体: 上传进度、处理状态
设计令牌: 所有视觉样式通过令牌系统

库快速比较

库	类型	大小	最佳用于
Sonner	Toast	小	Modern React 18+、可访问性
react-hot-toast	Toast	<5KB	最小包大小
react-toastify	Toast	~16KB	RTL支持、移动端
Radix UI	Modal	小	设计系统、无头
Headless UI	Modal	小	Tailwind项目

根据项目需求选择。参见 references/library-comparison.md 获取详细分析。

关键原则

匹配紧急性到注意力: 不要为不关键信息使用模态
保持一致: 对类似操作使用相同反馈类型
提供上下文: 解释发生了什么和要做什么
启用恢复: 包括撤销、重试或帮助选项
尊重偏好: 遵守减少动效设置
测试可访问性: 用屏幕阅读器和键盘验证