onboarding-ux

入门引导体验

检查 Web 应用中的入门引导缺口，然后生成应用内引导内容来弥补这些缺口。目标是：新用户不应该盯着空白屏幕，不知该做什么。

要解决的问题

你已经构建了各项功能。它们都能正常使用。但新用户首次登录时，看到的却是：

• 只有列标题、除此之外空空如也的表格
• 侧边栏里满是他们尚不了解的标签
• 没有任何说明告诉他们从哪里开始，或应用的用途是什么
• 应用中的功能无人提及，因此他们不知道这些功能的存在

此技能会找出这些缺口，并生成相应的内容和代码来填补它们。

浏览器工具检测

与 ux-audit 相同——检测 Chrome MCP、Playwright MCP 或 playwright-cli。如有需要，请参阅 ux-audit 的 browser-tools.md。

URL 解析

与 ux-audit 相同——优先使用已部署的线上 URL，而不是 localhost。检查 wrangler.jsonc、CLAUDE.md 或正在运行的开发服务器。

工作流

阶段 1：审查——找出缺口

以全新用户的身份浏览应用。在每个页面上，评估以下内容：

空状态

浏览每个列表、表格和集合页面。针对每个页面：

检查项	好的示例	不好的示例
零数据页面会显示什么？	“还没有客户。添加第一位客户，开始使用。” + CTA 按钮	只有列标题的空表格，或一片空白
是否有明确的操作？	按钮：“添加你的第一个[对象]”	什么也没有——用户必须去导航栏或菜单中寻找操作
是否解释了该功能？	“客户是与你合作的个人和企业。添加一位客户，开始跟踪你们的关系。”	只有一个空容器
空状态是否经过设计？	插图或图标、实用文案、醒目的 CTA	与有数据的状态完全相同，只是没有数据

第一印象

以新用户身份登录（或清除状态来模拟）。评估以下内容：

检查项	关注点
着陆页	仪表板/主页是否展示了有用内容，还是空空如也？
方向指引	10 秒内，我能否了解这个应用的用途以及从哪里开始？
首要操作	我应该做的首要事项是否一目了然且足够醒目？
认知负荷	有多少菜单项、按钮和选项在争夺注意力？
欢迎内容	是否有欢迎消息、产品导览或入门指南？还是只有未经引导的应用界面？

功能可发现性

针对应用中的每项功能：

检查项	关注点
我能找到它吗？	它在导航栏中是否可见，还是藏在菜单/子菜单里？
我知道它的用途吗？	标签是否能说明用途，还是必须点进去才能知道？
键盘快捷键	是否有快捷键？用户能否发现它们（工具提示、帮助面板）？
高级功能	筛选器、批量操作、搜索等功能是否可见，还是被隐藏了？
设置与配置	我能找到设置吗？我知道每项设置的用途吗？

上下文帮助缺口

针对每个页面：

检查项	关注点
表单字段	复杂字段是否有帮助文本或工具提示？
专业术语	是否有非专业用户难以理解的标签？
操作后果	破坏性或不可逆操作是否说明了将会发生什么？
验证	我操作有误时，错误消息是否告诉我如何修正？

生成审查报告

写入 .jez/artifacts/onboarding/audit.md：

# Onboarding Audit: [App Name]
**Date**: YYYY-MM-DD
**URL**: [app url]

## First Impression Score
[1-5] — Can a new user figure out what to do within 30 seconds?

## Empty States Found
| Page | Current state | Recommendation |
|------|--------------|----------------|
| /clients | Empty table, no guidance | Add empty state with CTA |

## Missing Guidance
| Location | Gap | Priority |
|----------|-----|----------|
| Dashboard | No welcome or getting started | High |
| Settings | No descriptions on settings | Medium |

## Feature Discovery Issues
| Feature | Problem | Fix |
|---------|---------|-----|
| Keyboard shortcuts | No way to discover them | Add help panel |

## Quick Wins
[Top 5 changes that would have the biggest impact on new user experience]

---

阶段 2：生成——构建解决方案

完成审查后，生成实际的内容和代码。阅读项目代码库，以匹配现有技术栈和组件模式。

1. 空状态组件

为审查中发现的每种空状态生成一个组件：

// Pattern — adapt to the project's component library
function EmptyState({ icon, title, description, actionLabel, onAction }) {
  return (
    <div className="flex flex-col items-center justify-center py-16 text-center">
      <div className="text-muted-foreground mb-4">{icon}</div>
      <h3 className="text-lg font-medium mb-2">{title}</h3>
      <p className="text-muted-foreground mb-6 max-w-md">{description}</p>
      <Button onClick={onAction}>{actionLabel}</Button>
    </div>
  );
}

针对每个页面，编写有针对性的文案：

• 标题：说明功能是什么（“客户”）
• 描述：用一句话说明它为何重要（“跟踪与你合作的个人和企业”）
• 操作：说明接下来该做什么（“添加第一位客户”）

文案要像一位乐于助人的同事所写，而不是操作手册。

2. 欢迎 / 首次使用体验

根据应用的复杂程度，生成以下其中一种模式：

简单应用（3-5 项功能）：在仪表板上显示欢迎横幅

// Dismissable welcome banner — shown until user closes it or completes first action
function WelcomeBanner({ onDismiss }) {
  return (
    <div className="rounded-lg border bg-card p-6 mb-6">
      <h2 className="text-xl font-semibold mb-2">Welcome to [App Name]</h2>
      <p className="text-muted-foreground mb-4">Here's how to get started:</p>
      <ol className="space-y-2 mb-4">
        <li>1. Add your first client</li>
        <li>2. Create a policy for them</li>
        <li>3. Check your dashboard for what needs attention</li>
      </ol>
      <Button variant="outline" size="sm" onClick={onDismiss}>Got it</Button>
    </div>
  );
}

复杂应用（6 项及以上功能）：清单式引导流程

// Persistent getting-started checklist — tracks progress
function OnboardingChecklist({ steps, completedSteps }) {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Getting Started</CardTitle>
        <p className="text-sm text-muted-foreground">
          {completedSteps.length} of {steps.length} complete
        </p>
      </CardHeader>
      <CardContent>
        {steps.map(step => (
          <div key={step.id} className="flex items-center gap-3 py-2">
            <Checkbox checked={completedSteps.includes(step.id)} disabled />
            <span>{step.label}</span>
          </div>
        ))}
      </CardContent>
    </Card>
  );
}

3. 功能导览

为 react-joyride（或同类工具）生成导览配置：

const tourSteps = [
  {
    target: '[data-tour="sidebar-clients"]',
    content: 'Your clients live here. Add people and businesses you work with.',
    placement: 'right',
  },
  {
    target: '[data-tour="create-button"]',
    content: 'Click here to create something new — a client, policy, or email.',
    placement: 'bottom',
  },
  {
    target: '[data-tour="search"]',
    content: 'Use search to find anything fast. Try Cmd+K for the quick switcher.',
    placement: 'bottom',
  },
];

同时生成需要添加到现有组件中的 data-tour 属性。

4. 工具提示和帮助内容

为每个复杂的 UI 元素生成工具提示文案：

// Pattern for info tooltips
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <InfoIcon className="h-4 w-4 text-muted-foreground" />
    </TooltipTrigger>
    <TooltipContent>
      <p>Significance shows how important this client is to your business.
      5 = critical (your biggest client), 1 = minimal (one-off interaction).</p>
    </TooltipContent>
  </Tooltip>
</TooltipProvider>

为每个需要说明的字段生成内容映射：{ fieldName: tooltipText }。

5. 情境提示

为用户可能发现不了的功能生成行内提示：

// Shown once, dismissable, stored in localStorage
function ContextualHint({ id, children }) {
  const [dismissed, setDismissed] = useState(
    () => localStorage.getItem(`hint-${id}`) === 'dismissed'
  );
  if (dismissed) return null;
  return (
    <div className="text-sm text-muted-foreground bg-muted/50 rounded-md px-3 py-2 mb-3 flex items-center justify-between">
      <span>{children}</span>
      <button onClick={() => { localStorage.setItem(`hint-${id}`, 'dismissed'); setDismissed(true); }}>
        <XIcon className="h-3 w-3" />
      </button>
    </div>
  );
}

// Usage
<ContextualHint id="keyboard-shortcuts">
  Tip: Press Cmd+K to quickly jump to any page or record.
</ContextualHint>

6. 能够引导用户的种子数据

生成能够展示应用功能的示例记录：

• 一条包含真实信息的示例客户端记录（而不是“Test Client”）
• 每种状态各一条示例记录（草稿、启用、已完成、已归档）
• 展示关联关系的记录（客户端 → 联系人 → 保单 → 电子邮件）

编写种子脚本时，请使用适合引导用户的数据——这些记录应让用户了解优质数据是什么样的。

7. 帮助页面内容

根据应用的实际情况生成帮助/常见问题页面：

## Frequently Asked Questions

### How do I add a new client?
1. Click "Clients" in the sidebar
2. Click "Add Client" in the top right
3. Fill in the name and domain — everything else is optional
4. Click "Save"

### What does "significance" mean?
Significance is a 1-5 rating of how important a client is...

### Can I undo a deletion?
Deletions are permanent. You'll always see a confirmation before...

输出

所有生成的内容都放入 .jez/artifacts/onboarding/：

.jez/artifacts/onboarding/
├── audit.md                    # The gap analysis report
├── empty-states.tsx            # Empty state components with copy
├── welcome-banner.tsx          # First-run welcome component
├── onboarding-checklist.tsx    # Getting-started checklist (if complex app)
├── tour-steps.ts               # Feature tour configuration
├── tooltip-content.ts          # Tooltip copy map
├── contextual-hints.tsx        # Inline hint component + content
├── seed-data.ts                # Onboarding seed records
└── help-content.md             # FAQ / help page content

告知用户生成了哪些文件，以及这些文件应集成到哪里。为每个文件提供具体说明，例如：“当客户端列表为空时，将此组件添加到 /clients 页面。”

提示

• 生成内容前，先阅读项目现有的组件模式——保持风格一致，不要引入新模式
• 如果项目使用 shadcn/ui 组件，就使用它们
• 文案要像一位乐于助人的同事所写，而不是说明书
• 空状态是影响最大的一项改进——优先处理
• 功能导览步骤过多会让人厌烦——最多 5 步
• 情境提示应可关闭，且只显示一次
• 示例数据应看起来真实——使用符合澳大利亚习惯的姓名、域名和详情
• 帮助页面内容可以从 ux-audit 的“向同事解释”输出中生成

与其他技能配合使用

如果你还运行……	此技能会补充……
ux-audit（全面审查）	将审查结果作为输入，修复发现的问题
app-docs	帮助页面内容可用于用户指南
product-showcase	空状态和欢迎流程能让演示截图效果更好