ux-feedback

UX 反馈状态生成器

使用时机

当你需要为组件或页面添加适当的用户反馈状态（加载、成功、错误、空状态）时，使用此技能。

不适用时机

• 仅处理状态中的文字 → 使用 /ss-copy
• 处理现有状态的无障碍问题 → 使用 /ss-a11y
• 创建全新组件 → 使用 /ss-component
• 处理分析或错误日志接入——仅负责 UI 展示

目标：$ARGUMENTS

指令

1. 读取目标文件，并识别所有依赖数据的区域。

2. 阅读设计语言参考：

   • 如果目标项目中存在 DESIGN-LANGUAGE.md，请阅读其中关于加载状态（骨架屏）、空状态和错误状态的部分。此参考文件未随附；否则请使用项目现有的组件和设计令牌。

3. 对每个依赖数据的区域，实现全部 4 种状态：

状态 1：加载（骨架屏）

// Skeleton must match the final layout shape
<div className="bg-card rounded-2xl p-6 shadow-[var(--shadow-card)]">
  <div className="flex items-center gap-2 mb-3">
    <div className="size-7 bg-surface-muted rounded-lg animate-pulse" />
    <div className="h-3 w-16 bg-surface-muted rounded animate-pulse" />
  </div>
  <div className="h-9 w-24 bg-surface-muted rounded-lg animate-pulse mb-3" />
  <div className="h-3 w-12 bg-surface-muted rounded animate-pulse" />
</div>

规则：

• 骨架屏至少显示 300ms（防止闪烁）
• 延迟 300ms 后再显示骨架屏（快速加载时完全跳过骨架屏）
• 使用 animate-pulse（周期为 1.5s）
• 骨架屏形状应与实际内容尺寸相匹配
• 卡片内绝不使用加载动画

状态 2：空状态（无数据）

<EmptyState
  icon={PackageIcon}
  title="No activity yet"
  description="Create your first project to get started."
  action={<Button>Create Project</Button>}
/>

规则：

• 在卡片内居中对齐
• 图标：32px，text-text-tertiary
• 标题：14px，text-text-secondary
• 始终建议下一步操作
• 零值显示为 “0”（不要隐藏或显示为破折号）

状态 3：错误（加载失败）

<div className="flex flex-col items-center justify-center py-8 text-center">
  <AlertCircle className="size-8 text-destructive mb-3" />
  <p className="text-[14px] text-text-secondary mb-4">Couldn't load the data</p>
  <Button variant="brandGhost" size="sm" onClick={retry}>Try again</Button>
</div>

规则：

• 部分失败：仅受影响的卡片显示错误，其余部分正常加载
• 整页失败：显示带重试功能的全屏 EmptyState
• 错误消息：使用通俗易懂的语言，并将责任归于系统
• 仅在重试安全时提供重试；否则提供准确的恢复操作。

状态 4：成功（操作反馈）

// Toast notification for action confirmations
toast("Changes saved")

// With undo for destructive actions
// Only offer Undo when handleUndo genuinely restores the deleted item.
toast("Item deleted", { action: { label: "Undo", onClick: handleUndo } })

规则：

• 信息提示 toast：显示 3s
• 操作提示 toast（带撤销）：不要将短暂显示的 toast 作为唯一的恢复方式；应提供持久的恢复途径或可调整的显示时长。
• toast 位置：位于 BottomNav 上方
• 一次只显示一个 toast（新 toast 替换旧 toast）

4. 实现模式：

function DataCard({ data, isLoading, error, refetch }) {
  if (isLoading) return <DataCardSkeleton />
  if (error) return <DataCardError onRetry={refetch} />
  if (!data || data.length === 0) return <DataCardEmpty />
  return <DataCardContent data={data} />
}

5. 检查 prefers-reduced-motion——当用户偏好减少动态效果时，禁用 animate-pulse。

限制

• 仅当任务与其上游来源及本地项目上下文明确匹配时，才使用此技能。
• 应用更改前，核实命令、生成的代码、依赖项、凭据和外部服务行为。
• 不要将示例视为环境专属测试、安全审查或破坏性、高成本操作所需的用户批准的替代品。