ux-extract

UX 提取

全面研究一个参考 Web 应用，并制作可复用的模式库。遍历所有页面，捕捉所有内容，再整理成一份文档，供后续审查或构建时参考。

与 ux-audit 相反：

• 审查会问：这是否符合标准？
• 提取会问：标准是什么？

没有提取结果的审查，往往会默认拿“我对其他应用的记忆”作比较——既脆弱又不一致。提取能将这些记忆转化为具体、可浏览的资料。这样，审查就可以说：“/app/clients 上的空状态没有 CTA。参考（claude.ai）在相同位置显示 3 个键盘快捷键，以及‘新建聊天’”，而不是说：“感觉有点空”。

适用场景

• 构建新功能前——研究一流应用如何处理该功能
• 对构建结果进行基准比较——提取参考应用，再据此进行审查
• 帮助设计师或工程师入职——以具体示例说明优秀设计的样子
• 竞品研究——记录竞争对手的 UX，以便有针对性地做出差异化
• 更新旧应用——从现代同类应用中提取模式，为更新提供指引

范围与伦理

开始前，请确认目标应用适合研究：

1. 使用自己的账户——不要抓取任何需要你并未合法持有的凭据才能访问的内容
2. 对未认证的爬取，遵守 robots.txt
3. 限制请求频率——像普通用户一样操作，而不是像爬虫。页面之间暂停一下。
4. 检查服务条款——大多数 SaaS 服务条款允许个人查看，但禁止自动抓取
5. 不要在公开场合转载竞争对手在线应用的截图——模式库仅供内部参考

如果目标应用有付费墙或需要试用账户，请先询问用户是否具有合法访问权限。

设置

1. 浏览器工具

目标	工具	说明
需认证的参考应用（你有账户）	Chrome MCP	使用你已登录的会话
公开参考应用（营销页面、文档、公开演示）	Playwright MCP	无需登录

命令请参阅 ../ux-audit/references/browser-tools.md。

2. 视口

将 1440×900 设为基准（MacBook 标准尺寸）。另外捕捉 768 和 375 尺寸下的响应式模式。宽度不要超过 2000px。

2b. 截图后处理

在 Retina Mac 上，Chrome 会以逻辑视口的 2 倍尺寸捕捉画面——宽度为 1440 的窗口会生成宽度为 2880 的 PNG。每批截图后都进行后处理，避免模式库中充斥着过大的文件：

img-process batch ./screenshots --action optimise --max-width 1440

此操作具有幂等性——对已经较小的文件不做任何处理。每完成一条路由的截图后运行，或在提取结束时对整个 screenshots/ 文件夹运行。Playwright MCP 用户可以在上下文选项中设置 deviceScaleFactor: 1，跳过此步骤。

3. 范围

开始前确定范围：

• 整个应用——遍历所有可访问内容（可能需要数小时，但会生成全面的模式库）
• 功能区域——一个版块（“设置流程”“仪表板”或“账单流程”）
• 模式类别——只研究空状态、错误处理或入门引导

范围越窄，生成的模式库就越精炼、实用。只有在要构建与某个应用直接对应的产品时，才值得研究“整个应用”。

4. 关注重点（可选）

可设置捕捉内容的侧重点。示例：

• “关注数据密集型列表的模式”——优先捕捉表格、筛选、搜索和虚拟化相关截图
• “关注入门引导和空状态”——优先捕捉首次使用流程和无数据视图
• “关注权限边界”——使用多个角色登录，并记录差异

如果未指定关注重点，则进行广泛捕捉。

探索

网站地图爬取

构建完整的路由清单：

1. 公开网站地图 — 检查 /sitemap.xml、/robots.txt，了解网站的可发现性
2. 导航爬取 — 点击顶部导航、侧边栏和页脚中显示的每个分区
3. 应用内发现 — 进入应用后，记录出现的每个链接（面包屑、标签页、上下文菜单）
4. URL 检查 — 有些应用在 /settings、/preferences、/admin 中包含实用页面，但这些页面不会显示在主导航中

记录每个路由的用途：/settings/billing — 订阅方案、付款方式、发票历史记录。

模式清单

深入捕获之前，先扫描一遍应用，列出要记录的模式类型。常见类别包括：

• 导航定位（导航、面包屑、当前位置、返回）
• 列表和表格（行、悬停、显示操作、选择、排序、筛选、分页、空状态）
• 表单（标签、验证、错误、必填、行内帮助）
• 模态框和对话框（触发、焦点、退出、滚动、确认）
• 反馈（Toast、行内提示、进度、加载、已保存）
• 引导和空状态（首次运行、无数据时的行动号召、引导教程）
• 权限和角色（受限视图、拒绝访问、角色指示器）
• 文案和微文案（按钮、标题、错误、占位文本、工具提示）
• 键盘（快捷键面板、焦点、Tab 顺序、命令面板）
• 动效（过渡、显示、加载、手势）
• 响应式设计（断点、移动端专属模式：底部抽屉、标签页、滑动）

并非每个应用都会用到所有类别。标明适用项。

捕获阶段

对每个路由进行全面捕获。截图成本很低——宁可多拍。

截取所有状态

对每个有意义的元素进行截图：

状态	触发方式
默认	页面已加载，尚未进行任何交互
悬停	鼠标悬停在按钮、行或导航项上
焦点	通过 Tab 键获得键盘焦点
激活	按钮正处于点击过程中，或输入框正被输入
打开	下拉菜单已打开，菜单已展开
关闭	下拉菜单已关闭，菜单已折叠
展开	手风琴已打开，详情面板已展开
折叠	手风琴已关闭
已选中	复选框已勾选、行已选中、标签页处于激活状态
加载中	骨架屏、旋转指示器、待处理状态
空	列表中没有项目
已填充	列表中有许多项目
错误	行内错误、Toast 或整页错误
成功	操作完成后的确认

完整的模式检查清单请参见 references/capture-checklist.md。

原样捕获文案

逐字复制文本，包括标点、删节号和语气：

• 按钮标签："Start chat"、"Upgrade plan"、"Delete forever"
• 空状态："No conversations yet. Start one to see it here."
• 错误消息："We couldn't save that change. Try again, or contact support if it keeps happening."
• 确认对话框："Delete this project? All 14 tasks and 3 members will be removed. This cannot be undone."
• 占位文本："e.g. [email protected]"
• 工具提示："Pressing Cmd+K opens this from anywhere"

原始文案对文案撰写者很有价值，也有助于了解应用的语气。

捕获交互

对每个交互元素，记录：

• 触发方式：点击／悬停／键盘／长按／拖动
• 目标：受影响的对象（打开模态框、筛选列表、导航）
• 反馈：是否有即时视觉响应？是否有延迟确认？
• 可逆性：能否撤销？是否具有破坏性？

捕获键盘模式

• 快捷键面板：是否有 ? 或 Cmd+/ 用于显示快捷键列表？请截图记录。
• 命令面板：是否有 Cmd+K 或类似快捷键？请捕获面板打开、搜索、选中结果和执行操作的状态。
• 焦点指示器：通过 Tab 键遍历页面，记录焦点环的样式、颜色和粗细
• Tab 顺序：顺序是否合理？是否有意外跳转？

记录响应式处理

对每个路由，分别在 1440、768、375 像素宽度下截图。记录具体变化，不要只写“能正常工作”：

• 导航在 [断点] 处从侧边栏变为汉堡菜单
• 表格在 [断点] 处折叠为纵向堆叠的卡片
• 模态框在 [断点] 处变为全屏
• 多列表单在 [断点] 处变为单列

记录动效

使用 Chrome MCP 的 gif_creator 录制值得记录的动画 GIF：

• 页面切换
• 模态框进入／退出
• 列表项进入／退出
• 加载中 → 已加载
• 成功动画（彩纸、勾号）
• 拖放反馈

一段 3 秒的 GIF，胜过一段描述文字。

去重阶段

捕获后，许多模式会出现在多个页面上。请进行去重：

• 同一种行模式出现在 5 个列表页面上 → 创建一个“列表行”条目，并注明 “使用于：/clients、/projects、/invoices、/reports、/team”
• 相同的空状态布局，文案不同 → 创建一个“空状态”条目，并列出文案变体
• 相同的模态框外观 → 创建一个“模态框”条目；将具体模态框列为使用场景

每种模式都记录两个计数：

• 出现次数 — 该模式出现的次数
• 变体 — 有意义的差异（有图标或无图标、小号或大号、有 CTA 或无 CTA）

只出现一次的模式通常不值得记录，除非它独特且值得关注。

输出

写入 docs/ux-extracts/<app-name>/（如果该目录存在，则写入 .jez/artifacts/ux-extracts/<app-name>/）：

docs/ux-extracts/claude-ai/
├── pattern-library.md      ← main document
├── copy-corpus.md          ← optional, raw copy by page (for writers)
└── screenshots/
    ├── 001-home-default.png
    ├── 002-home-hover-cta.png
    ├── 003-new-chat-empty.png
    └── ...

请参阅 references/pattern-library-template.md 了解输出结构。

模式库应当：

• 便于浏览 — 顶部有目录，并为每个章节添加跳转链接
• 交叉引用 — “另请参阅：模态框外观”
• 截图详实 — 每项说明都有对应截图作为依据
• 文案准确 — 在代码块或引用块中逐字呈现文本，不要改写
• 客观诚实 — 除优点外，也记录缺失或不足之处。参考库并非绝对标准。

ux-audit 如何使用这些内容

ux-audit 会在 .jez/artifacts/ux-extracts/<ref>/pattern-library.md 或 docs/ux-extracts/<ref>/pattern-library.md 中查找模式库。如果找到，就会以此作为对照标准。随后，审计结果可以引用具体模式：

“/app/clients 上的空状态没有说明文案，也没有 CTA。参考库 [claude.ai § 空状态] 显示，此处应有 CTA 和 2 个示例提示词。”

只需在预期路径下生成模式库，无需进行其他集成。

自主操作范围

• 直接执行：导航、截图、复制文本、注入 JavaScript 以读取计算样式、下载静态资源（徽标、图标）供参考
• 先询问：需要使用用户尚未授权提供的凭据登录，或网站的服务条款／限速规则不明确、无法判断能否抓取
• 停止并确认：如果目标网站有登录墙，且没有明确授权，则停止并在继续前确认

参考文件

何时	阅读
编写 pattern-library.md 输出	references/pattern-library-template.md
每种模式的捕获清单（截图内容、记录事项）	references/capture-checklist.md
浏览器工具命令	../ux-audit/references/browser-tools.md

提示

• 截图成本很低——尽量多截图。从素材库中删掉一张截图，比重新运行提取来获取截图容易。
• 看到文案就立刻记录——别想着之后再回来记录；等你回来时，它可能已经处于另一种状态。
• 记录缺失的内容——如果应用没有键盘快捷键列表，这也是值得记录的设计模式。
• 将观察与评价分开——提取内容记录的是实际存在的内容，而非它是否优秀。观点应放在审查中，而不是提取内容里。
• 提取内容会过时——应用会不断变化。为素材库标注时间戳，如果可以，也添加指向 archive.org 对应日期的链接；对于经常对比的应用，计划每隔 6–12 个月重新提取一次。
• 逐步构建——开始时就打开素材库文件，边做边补充。不要等到最后才尝试整理全部内容。