Storefront Best Practices

• eコマースストアフロントの構築または拡張 — 任意のフレームワーク（Next.js、SvelteKit、TanStack Start、React、Vue）：商品ページ、商品一覧、カート、チェックアウト、ナビゲーション、ホームページ、検索、アカウントページ、または注文確認。
• バックエンドの統合（Medusaを含む） — SDKのセットアップ、商品・カテゴリ・リージョンの取得、価格表示、支払い方法の選択、およびカート管理。
• 既存ストアの最適化 — コンバージョン率の改善、モバイル体験の問題修正、SEO構造化データの追加、またはショッピングフローにおけるアクセシビリティの向上。
• ストアフロント実装の計画 — 正しい参照ファイルを参照し、コードを書く前に既知の落とし穴を回避する、ステップバイステップの構築計画の作成。

• 非eコマースプロジェクト — 管理ダッシュボード、SaaSアプリ、ブログ、またはショッピング/購入フローのないサイトには、このスキルのパターンは必要ありません。
• 純粋なバックエンドまたはAPI作業 — フロントエンドのストアフロントコンポーネントを含まないサーバーサイドのコマースロジックのみを扱っている場合、このスキルはほとんど価値をもたらしません。

バックエンドAPIまたはSDKを呼び出すコードを書く前に、スキルは5つのステップからなるワークフローを強制します：一時停止、ドキュメントまたはMCPサーバーへの問い合わせ、ユーザーとのメソッド確認、コードの記述、そしてTypeScriptエラーのチェック。これにより、推測によるメソッド名の使用、古い例の参照、および実行時の無言の失敗を防ぎます。

このスキルは、チェックアウト、商品リスティング、ナビゲーション、SEO、モバイル、Medusa連携など、すべてのストアフロントタスクを特定のリファレンスファイル（例：reference/layouts/checkout.md、reference/medusa.md）にマッピングします。各機能を実装する前に読み込むべきファイルを正確に指定することで、パターンが一貫して適用されることを保証します。

ストアフロント特有の高影響度ルールを網羅しています：スクリーンリーダー向けのカート数量に対する aria-live="polite"、iOSの固定ボタン向けの env(safe-area-inset-bottom)、44pxの最小タッチターゲット、スクロール領域以下の商品画像への必須 loading="lazy"、およびストアフロントUIにおける絵文字の使用禁止。

Next.js（App RouterおよびPages Router）、SvelteKit、TanStack Start、Remixに対して、商品ページおよびカテゴリページ向けの正しいダイナミックルートパターンを提供します。スケールしない静的な個別アイテムルートの使用について明示的に警告します。

Medusa SDKの初期化（公開APIキーが必要）、正しい価格表示（100で割らないこと）、商品取得時のregion_idの必須要件、CORSポート規則（8000）、Vite SSR設定、カスタム型の代わりに@medusajs/typesを使用すること、および注文確定後のカート状態のクリアについて説明します。

カート・ナビゲーション、商品ブラウジング、チェックアウト、モバイル、SEO、パフォーマンス、デザインの一貫性、バックエンド統合にわたる30以上の名付けられたアンチパターンを分類したリストです。それぞれは、実装前および実装中に確認すべき具体的な ❌ ルールとして表現されています。

このスキルは、ディスカバリー（design.md の読み込み）から基盤構築、コアコンポーネント、ショッピングフロー、最適化まで、10ステップの順次ワークフローを提供します。各ステップでは、実装前に読み込むべき正確なファイルを参照しており、見落としがなく、スタイルの一貫性が保たれます。

チェックアウトのアーキテクチャに関する決定（シングルページ方式 vs. マルチステップ方式）をガイドし、支払い方法をハードコーディングするのではなくバックエンドから取得することを徹底し、ゲストチェックアウトの要件を明示するとともに、reference/layouts/checkout.md および reference/medusa.md を通じてMedusa固有の支払いインテグレーション手順を提供します。

SDKのセットアップ、リージョンと価格設定のパターン、region_idを使用したプロダクトの取得、カートのリージョンにスコープされた国リスト、Vite SSR設定、およびメソッド検証のためのMedusa MCPサーバーの使用について解説します。これにより、最も一般的なMedusaストアフロント統合エラーを防ぐことができます。

タッチターゲットのサイズ、セーフエリアのインセット、および画像の最適化については reference/mobile-responsiveness.md を、また商品のJSON-LDスキーマ、メタタグ、Open Graph、およびPageSpeed Insightsを使用したCore Web Vitalsの計測については reference/seo.md を参照するよう、開発者に案内します。