hydrogen-ecommerce-ux

Hydrogen の E コマース UX のベストプラクティス

このスキルは、Shopify Hydrogen のストアフロント構築に役立つ、調査に裏付けられた UX の指針を Claude に提供します。ガイドラインは、Baymard Institute（米国および EU の主要な 90 以上のサイトで、約 200,000 時間以上にわたる E コマースのユーザビリティテストを実施）と、Nielsen Norman Group の E コマース調査（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（JavaScript を使用している場合は推奨します）
• Oxygen デプロイ先（エッジ、メモリ上限 128 MB、コールドスタート 400 ms 未満）
• Storefront API は context.storefront.query() と CacheLong／CacheShort／CacheNone ヘルパーを使用
• Customer Account API は認証フローに使用（従来の Storefront customer mutation は使用しません）
• @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 コンテンツをそのまま再配布するものではありません。