providing-feedback

提供用户反馈和通知

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

何时使用此技能

在以下情况下启用此技能：

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

反馈类型决策矩阵

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

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

按紧急程度快速参考

紧急程度	组件	时长	是否阻止交互
严重	模态对话框	直到执行操作	是
重要	警告横幅	直到关闭	否
常规	Toast	3-7 秒	否
上下文相关	行内消息	持续显示	否
帮助	工具提示	悬停时	否
进度	加载动画/进度条	操作期间	可选

实施方法

第 1 步：确定反馈类型

根据以下标准评估情况：

1. 紧急程度：信息有多关键？
2. 时长：信息应持续显示多久？
3. 是否需要操作：用户是否需要回应？
4. 上下文：信息是否与特定 UI 元素相关？

第 2 步：选择实施模式

Toast/Snackbar：

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

模态对话框：

• 焦点管理：将焦点限制在模态框内
• 无障碍：支持按 ESC 关闭，并设置适当的 ARIA 标签
• 背景遮罩：点击外部关闭（可选）
• 实现方法请参阅 references/modal-patterns.md

进度指示器：

• <100ms：无需指示器
• 100ms-5s：显示带消息的加载动画
• 5s-30s：显示进度条（尽可能使用确定进度）

• 30s：显示进度条、时间估算和取消选项

• 模式请参阅 references/progress-indicators.md

空状态：

• 包含：插图、标题、正文和 CTA
• 类型：首次使用、零结果、错误、权限被拒
• 设计请参阅 references/empty-states.md

第 3 步：使用推荐的库进行实现

现代 React 技术栈（推荐）：

npm install sonner @radix-ui/react-dialog

Toast：使用 Sonner：

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'
});

模态框：使用 Radix UI：

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。

第 4 步：应用无障碍模式

用于播报的 ARIA 实时区域：

<div role="status" aria-live="polite">
  File uploaded successfully
</div>


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

模态框焦点管理：

1. 打开前保存当前焦点
2. 将焦点移至模态框中的第一个交互元素
3. 将焦点限制在模态框内（按 Tab 键循环切换）
4. 关闭时将焦点还原至触发元素

完整模式请参阅 references/accessibility-feedback.md。

第 5 步：集成设计令牌

所有反馈组件都使用 design-tokens 技能来保持主题一致：

/* 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);
}

使用的令牌类别：

• 颜色：Toast、警告、模态框和工具提示的背景
• 间距：所有组件的内部边距
• 排版：标题和消息的字号
• 阴影：浮动元素的层级效果
• 动效：动画时长和缓动

通知时长指南

自动关闭时长：

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

进度指示器阈值：

• <100ms：无指示器
• 100ms-5s：加载动画
• 5s-30s：进度条

• 30s：进度条和取消选项

资源

脚本（无令牌执行）

• 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	小	现代 React 18+、无障碍访问
react-hot-toast	Toast	<5KB	最小化捆绑包大小
react-toastify	Toast	~16KB	RTL 支持、移动端
Radix UI	Modal	小	设计系统、无头组件
Headless UI	Modal	小	Tailwind 项目

请根据项目需求进行选择。详细分析请参阅 references/library-comparison.md。

核心原则

1. 让紧迫程度与所需关注度相匹配：非关键信息不要使用模态框
2. 保持一致：相似操作使用相同类型的反馈
3. 提供上下文：说明发生了什么以及该怎么做
4. 支持恢复：提供撤销、重试或帮助选项
5. 尊重偏好：遵循减少动态效果设置
6. 测试无障碍访问：使用屏幕阅读器和键盘进行验证