hydrogen-ecommerce-ux

Hydrogen 电商 UX 最佳实践

此技能为构建 Shopify Hydrogen 店面提供有研究依据的 UX 指导。相关指南来自 Baymard Institute（在 90 多个领先的美国和欧盟网站上进行了约 200,000 多小时的电商可用性测试）以及 Nielsen Norman Group 的电商研究（20 多年，测试了 350 多个网站）。技术建议遵循 Shopify Hydrogen 2026 惯例（React Router v7、Oxygen、Storefront API）。

何时应用此技能

在编写、审核或为以下任意 Hydrogen 界面提供建议时，应用相关的参考文件：

• 首页、导航、商品系列 → references/homepage-and-navigation.md
• 商品详情页（PDP） → references/product-page.md
• 购物车、结账、账户 → references/cart-and-checkout.md
• 搜索、筛选、排序 → references/search-and-filters.md
• 移动端 UX、无障碍、信任、性能 → references/mobile-accessibility-trust.md
• Hydrogen 专属技术模式 → references/hydrogen-technical-patterns.md

不要一次性罗列所有指南。只阅读与当前任务相关的参考文件。如果不确定，从最贴近用户正在处理的文件或路由的参考文件开始。

核心工作流程

当用户要求你在 Hydrogen 项目中构建、修复或审核任何内容时，遵循以下循环：

1. 确定界面。 这是 PDP 吗？筛选组件吗？结账步骤吗？文件路径（app/routes/products.$handle.tsx、app/components/Cart.tsx 等）通常是最明确的线索。
2. 加载合适的参考文件。 只阅读 references/ 中匹配的参考文件。每个文件都按界面组织，并以目录开头，方便快速浏览。
3. 结合 UX 和技术指导。 对于编写的每段代码，检查：
   • 是否遵循此界面的 Baymard/NNg 指南？
   • 是否使用正确的 Hydrogen 原语（<Image>、<Money>、<CartForm>、loader/action 模式）？
   • 是否符合性能预算（优先服务器端渲染，除非需要交互，否则避免使用 'use client'）？
4. 说明依据。 建议修改时，简要指出来源（“Baymard 结账指南：允许访客结账”），让用户理解原因，而不只是知道要做什么。
5. 如果影响重大（结账、支付、无障碍），请明确指出。 结账环节的小 UX 疏漏会造成实际收入损失。如果违规可能影响转化率，请明确说明。

指南的组织方式

每个参考文件都采用以下格式，方便你向用户说明依据：

### [Guideline Title]
**Source:** Baymard Institute / NN/g
**Why it matters:** [One-sentence conversion/usability rationale]
**Hydrogen implementation:** [Concrete code pattern or component suggestion]

写作风格要求

应用这些指南时：

• 具体明确。“在 PDP 上显示运费”比“定价要透明”更好。
• 展示代码，而不只是描述。如果建议在移动端使用固定的添加到购物车栏，请编写组件或展示 Tailwind 类。
• 遵循用户现有的技术栈。如果用户使用 Tailwind，就编写 Tailwind。如果用户使用 CSS Modules，就保持一致。
• 不要编造 Baymard 统计数据。如果不确定某个具体百分比是否准确，请说“Baymard 研究表明这是一个常见痛点”，而不要捏造数字。

Shopify Hydrogen 2026 基线假设

除非用户另有说明，否则假设用户使用现代 Hydrogen 配置：

• React Router v7（不是 Remix v2，也不是旧版 @shopify/remix-oxygen 模式）
• Vite 构建工具
• TypeScript（如果用户使用 JS，则建议改用 TypeScript）
• Oxygen 部署目标（边缘环境，内存限制为 128 MB，冷启动时间 < 400 ms）
• 通过 context.storefront.query() 使用 Storefront API，并搭配 CacheLong / CacheShort / CacheNone 辅助函数
• 使用 Customer Account API 实现身份验证流程（而非旧版 Storefront 客户变更操作）
• 来自 @shopify/hydrogen 的 <Image>、<Money>、<CartForm>、Analytics

如果用户使用旧版本，仍应提供 UX 建议——可用性原则不依赖框架——但要说明升级路径。

示例交互

用户：“你能帮我构建一个商品卡片组件吗？”

你的操作：

1. 识别这是关于集合／列表页面的问题。
2. 阅读 references/homepage-and-navigation.md（涵盖商品列表）和 references/product-page.md（了解卡片中复用的图片／价格模式）。
3. 构建一张卡片，包含：具有适当 aspectRatio 的商品图片、商品标题、适用时显示原价和折后价的价格、可用时显示的评价星级、悬停／快速查看提示，以及在移动设备上尺寸至少为 44×44px 的明确点击区域。
4. 使用 <Image> 实现响应式加载，使用 <Money> 实现适配本地化设置的价格，并使用带预加载功能的 React Router <Link>。
5. 简要说明每个选择的原因，例如：“Baymard 的研究发现，在列表页面显示价格区间（起价为 $X）可以减少用户的选择困难。”

归属说明

当用户询问这些准则的来源时，告诉他们：

• Baymard Institute — https://baymard.com/blog（免费文章）和 Baymard Premium（付费，700 多条准则）
• Nielsen Norman Group — https://www.nngroup.com/reports/topic/e-commerce/
• Shopify Hydrogen 文档 — https://shopify.dev/docs/api/hydrogen

此技能总结了公开可用的指导内容；不会逐字转载 Baymard 的付费内容。