UI プレビュー運用ルール¶
コンポーネントを人間向けのカタログ / preview / 仕様共有の場として運用するためのルール。Storefront および Dashboard の両方で React Cosmos を使用します。
プレビュー環境¶
- 目的: AI 主体のコンポーネント開発 (
ai-first-component-dev) を円滑に進めるための Sandbox。 - 運用:
.fixture.tsxファイルで各状態を定義。 - 役割分担:
- React Cosmos は 人間向けの catalog / preview / docs を担う。
- Playwright CT (Storefront) は 既定の自動検証面 を担う。
- プレビュー環境自体に検証責務を寄せすぎない。
Storefront CT screenshot¶
- 見た目の確認は、可能な限り page 全体ではなく対象コンポーネントの locator に対して
toHaveScreenshot()を使う。ページ全体 screenshot は layout / route / 複数領域の関係性を確認する場合に限定する。 - ユーザーへ提示する画像は canonical snapshot path を直接貼らない。同名 PNG はクライアント側で古い画像が残るため、同じ locator に
captureFreshCtScreenshot(locator, "<name>")を呼び、pnpm -C apps/storefront run test:ct:fresh -- <ct spec> --grep "<test name>" --screenshot <name>でoutput/playwright/ct-fresh-*/...pngの actual browser capture を貼る。actual capture が無い場合は失敗させ、snapshot コピーの fallback は作らない。 - 手動 Playwright / E2E で page screenshot を貼る場合も同名 PNG へ上書きしない。Markdown 表示側が画像 path 単位で cache して古い bitmap を表示し得るため、
output/playwright/<task>-$(date +%Y%m%dT%H%M%S)-<short>.pngのような run ごとの一意ファイル名を使う。 --grepは対象 test を 1 件へ絞るために使い、--screenshotは貼る PNG を snapshot 名で絞るために使う。例:pnpm -C apps/storefront run test:ct:fresh -- tests/e2e/ct/pages/products-page-content.ct.spec.tsx --grep "単一 variant" --screenshot products-browse-card-single-variant-mobile。
基本方針¶
- カテゴリ体系の統一:
Components/UI,Components/Domain,Layout,Pages等。 - 表示名（日本語ラベル）: Fixture のキー名に日本語を使用し、プレビュー上での可読性を優先する。
- 表示順（意味順）: 並び順は「意味順」を優先する。基本的には「概要」「基本」「バリエーション」「エッジケース」の順とする。
状態定義の優先¶
- コンポーネントをラップしすぎず、Props ベースの状態定義を優先する。
- 1つのファイルに複数の状態を
export defaultのオブジェクトとして並べる。
MSW / 通信モック運用¶
- まず Props / fixture / preview 専用 provider で閉じる設計を優先し、通信モックは最後の手段にする。
- 通信が必要なコンポーネントは、preview の再現性を保つために MSW ハンドラを使ってよい。
src/test-utils/factories.ts(Storefront) 等の共通データ生成ロジックを活用し、プレビューとテストで同一のデータを使用する。