shop-advance-theme-development

Shop Advance テーマ開発

インストール済みの Bagisto のコマース、拡張機能、コンテンツ、ランタイムの契約を維持しながら、独自性のあるストアフロントを構築します。Bagisto の公式規約に従い、ドキュメントと対象のチェックアウト環境を照合し、有効化の前に動作を検証します。

絶対に守るルール

• 作業を始める前に、適用されるリポジトリの指示ファイルをすべて読みます。
• インストール済みのコードと設定を実行可能な唯一の信頼できる情報源として扱い、意図を把握するには公式のバージョン対応 Bagisto ソースを使用します。
• テーマコード、表示名、名前空間、パッケージパス、チャネル、ロケール、ビルドパス、ツールのバージョン、コマンドはすべてパラメーター化するか、検出します。
• ユーザーとリポジトリのポリシーで許可されていない限り、Bagisto Shop のソース、vendor/、生成済みビルド出力、依存関係、ロックファイル、稼働中のチャネル状態は編集しません。
• 疎なビューオーバーレイ／パッケージを優先します。アップグレードの影響範囲についてユーザーの承諾を得た場合に限り、完全なフォークを作成します。
• インストール済みの Shop パッケージからアセットのランタイム全体を把握します。ビューのフォールバックが Vite／JavaScript／CSS の継承を意味するわけではありません。
• レイアウトのランタイム処理、レンダーイベント、コントローラー変数、ルート、フォームフィールド、API 形式、商品タイプの動作、有効な拡張機能を維持します。
• 設定の編集はマージのみとします。隣接するテーマ／プロバイダー／オートロードのマッピングを削除したり、shop-default を暗黙的に変更したりしません。
• ドライランと競合チェックを実施します。強制公開、削除、ディレクトリのシンボリックリンクへの置き換え、破壊的なデータのシード、競合の自動上書きは行いません。
• コピー／派生したソースには、インストール済み Bagisto のライセンス表示をそのまま維持します。配布前にテーマ独自のライセンスを明示的に選択し、同梱するすべてのアセットについて再配布条件を確認します。
• 生成されたデザインの推奨は候補として扱い、絶対的な判断基準にはしません。コマースの明瞭さ、アクセシビリティ、パフォーマンス、ライセンス、マーチャントの制御、インストール済みの依存関係、Bagisto のランタイム契約を損なう提案は採用しません。
• デザインに関する情報収集には、このスキルに同梱された bagisto-ui-ux の知識とジェネレーターのみを使用します。実行時に別のデザインスキルを要求、検出、インポート、呼び出ししてはなりません。
• 「動的」「管理者が制御可能」「すべての機能が動作する」は、証拠が必要な主張として扱います。成功したビルドやホームページのスクリーンショットから推測せず、表示されるすべての画面と、インストール済み／有効なコマースの利用経路をすべて確認します。
• デザインツールが推奨したという理由だけで、アニメーションライブラリ、UI フレームワーク、アイコンパッケージ、リモートフォント、外部スクリプト、その他の依存関係を追加しません。まずインストール済みの機能を調べ、依存関係やネットワークの変更について許可を得ます。
• いずれかのチャネルでテーマを選択する前に、ビルドと検証を完了します。ロールバック方法を明示します。

ワークフロー

1. 対象を確認する

この SKILL.md から <skill-dir> を解決し、次を実行します。

python3 <skill-dir>/scripts/inspect_theme_environment.py \
  --project-root <project-root> \
  --theme-code <existing-theme-code> \
  --json

テーマがまだ存在しない場合、または設定済みのテーマをすべて意図的に調査する場合に限り、--theme-code を省略します。

報告された以下の内容を確認します。

• Bagisto／Shop のソースとバージョン。
• リポジトリの指示と保護されたパス。
• 設定済みのテーマ、フォールバック、パス、名前空間、Vite レジストリ。
• Shop の Composer／フロントエンド依存関係、スクリプト、Vite／Tailwind／PostCSS のファイル、エントリーポイント、コンポーネント、ルート、テスト、ロケール。
• 既存のテーマパッケージ、公開先パス、シンボリックリンク、マニフェスト、オーバーライドの範囲。

スクリプトがアーキテクチャを安全に解析できない場合は中止します。推測せず、ファイルを直接確認します。ドキュメントやバージョンが関係する場合は、official-sources.md を読みます。

2. 成果とモードを定義する

新しいビジュアルシステムを作成する場合や、大幅な再設計を行う場合は、次の手順に従います。

1. design-quality.md、commerce-design-direction.md、bagisto-ui-ux-foundations.md を読みます。モーションやインタラクティブな演出が対象に含まれる場合は、bagisto-ui-ux-interactions.md も読みます。これらはデザインリソースです。ビジュアルの方向性を承認してから、アーキテクチャと実装のリファレンスを使用してください。

2. ブランドの約束、業界、対象ユーザー、価格帯、カタログの特性、トーン、コンテンツの制約、避けるべき要素を集めます。仮の variance／motion／density ダイヤルを選びます。

3. バンドルされた自己完結型の bagisto-ui-ux ジェネレーターを実行します。このジェネレーターは、このスキルに含まれる Bagisto コマースデザインの知識を読み込み、チェックアウトを調査し、アクセシブルな候補を選択して、ページ単位のデザイン例外と Laravel／Vue／Tailwind のガイダンスを導き出し、ネットワークアクセスや永続化を行わずに候補レポートを出力します。

   python3 <skill-dir>/scripts/generate_bagisto_ui_ux.py \
     --project-root <project-root> \
     --project-name <display-name> \
     --industry <industry> \
     --audience <audience> \
     --tone <tone-keywords> \
     --catalog <catalog-character> \
     --price-position <price-position> \
     --variance <1-10> \
     --motion <1-10> \
     --density <1-10> \
     --json
   

4. 選択されたアーキタイプ、補完する影響要素、パレット、タイポグラフィ戦略、特徴、トークン、ページの設計図、ページごとのダイヤル、インタラクションポリシー、代替案、スタックのガイダンスを確認します。bagisto_review の指摘をすべて解決します。出力はすべて未承認の候補として扱い、実際のフォント、アイコン、画像、モーションのアセットは個別に承認してください。

5. ブランドに合わせたアーキタイプ、構成、マーチャンダイジングの階層、セマンティックトークンシステム、ページ単位の例外を統合します。承認済みのタスクメモまたはブリーフファイルで、assets/theme-brief.template.md の該当する項目を記入します。bagisto-ui-ux のクエリと、採用、調整、却下した推奨事項を記録します。ユーザーまたはリポジトリのポリシーで許可されていない限り、プロジェクトのドキュメントファイルを作成しないでください。

6. ブリーフファイルを作成した場合は、スタイリングの前に検証します。

   python3 <skill-dir>/scripts/validate_theme_brief.py \
     --brief <theme-brief.md> \
     --strict
   

バンドルされたナレッジファイルまたはジェネレーターの検証に失敗した場合は、作業を中止してこのスキルを修復するか、明示的に文書化された手動のデザイン方針を使用してください。別のスキルを暗黙に呼び出したり、ネットワーク上の推奨事項を使用したり、ジェネレーターの結果を捏造したりしないでください。

ユーザーが説明、引き継ぎ、または段階的な支援を求める場合、あるいは初心者だと述べた場合は、developer-guidance.md を読み、ガイド付きの提供モードを使用します。どの経験レベルでも、同じ技術的なゲートを維持してください。変えるのは説明と実装の粒度であり、品質基準ではありません。

architecture.md を読み、次の中から選択します。

• overlay：ベースのアセットバンドルとビジュアルシステムを意図的に再利用する、小規模なビューのみの変更。
• package：独自の Shop アセットランタイムをインストールするテーマを所有する、簡素なビューを使った、独立した本番環境向けテーマのデフォルト。
• full-fork：アップグレードの責任を記録した、Shop の完全なスナップショット。

複数のアプリケーションへの配布が必要な場合は、Composer で検出されるパッケージを使用します。アプリケーション内限定のパッケージには、チェックアウトのローカル PSR-4／プロバイダーの規約のみを使用します。両方の登録方式を組み合わせないでください。

実装前に、対象チャネル、有効なロケール／通貨／商品タイプ／拡張機能、マーチャントが管理するコンテンツ、サポート対象ブラウザー、アクセシビリティの目標、パフォーマンス予算、必須のユーザージャーニー、テーマのライセンス、アセットの出所を確認します。

3. 衝突を避けて計画し、スキャフォールドを作成する

まず --apply を付けずにスキャフォルダーを実行します。

python3 <skill-dir>/scripts/scaffold_theme.py \
  --project-root <project-root> \
  --theme-code <theme-code> \
  --display-name <display-name> \
  --mode package \
  --registration local \
  --vendor <php-vendor> \
  --package <php-package> \
  --override <shop-relative-blade-path>

すべての識別情報と統合用スニペットに加え、各 planned_actions のソース、宛先、状態、チェックサムを確認します。計画が要求されたモードと一致する場合にのみ、--apply を付けて再実行します。このスクリプトは新しいファイルを作成し、バイト単位で同一の再実行は受け入れ、競合は拒否します。ホストの設定を編集したり、チャネルを有効にしたりすることはありません。

配布可能なパッケージで、Bagisto の対象範囲が明示的にテスト済みであり、テーマライセンスが承認されている場合にのみ、--registration composer --bagisto-constraint <supported-range> --theme-license <spdx-expression> --theme-license-file <project-relative-license-file> を使用します。スキャフォールドでは、検出された Bagisto の通知は別途保持されます。同じプロバイダーを Composer でインストールし、ローカルでも登録しないでください。

既存のテーマの場合は、スキャフォールドを作成しないでください。テーマを調査してから、実際のソースツリー（設定済みの公開先にすぎない場所ではありません）を比較します。

python3 <skill-dir>/scripts/diff_theme_overrides.py \
  --project-root <project-root> \
  --theme-path <theme-package-or-views-path> \
  --expected-theme-code <theme-code> \
  --fail-on baseline-drift

差分ツールは、テーマソースのルートと完全に一致する .bagisto-theme-baseline.json を自動検出し、ビュー、アセット、検出されたビルド契約グラフ全体で、テーマの編集とインストール済み Shop の変更を区別します。Shop のビュー、アセット、ビルド契約を完全にインベントリ化するため、上流で追加・削除されたファイルを検出します。テーマが所有するファイルのハッシュにより、新たに追加、削除、または同時に変更されたオーバーライドを検出します。このベースラインでは、Shop の PHP、コントローラー、プロバイダー、ランタイムデータ契約はインベントリ化されません。これらは記録された Bagisto のリリースと回帰テストで確認します。設定された views_path が存在し、それが正式なオーバーライドツリーである場合にのみ、--theme-code <theme-code> を使用します。

既存のテーマにベースラインがない場合は、ゼロ以外の終了コードを「まだ監査できない」として扱います。現在の上流差分を確認してください。ゲートを通すためだけに現在のハッシュを受け入れないでください。

4. インストール済みの規約に従って統合する

必要なテーマエントリーと、選択したパッケージ登録方法のいずれか1つだけを統合します。現在の設定はすべて維持してください。有効なテーマの Vite 設定は Vite の出力と同期させます。名前空間付きのアセット呼び出しが明示的にある場合、またはインストール済みの要件がある場合にのみ、名前付きの Vite レジストリを追加します。

ビューとアセットのみのテーマでは、モデルや Concord を登録しないでください。テーマはまだ有効化しないでください。

ビルドファイルまたは依存関係を変更する前に、assets-build.md を読んでください。対象のロックファイルとパッケージマネージャーのポリシーに従い、インストール、ネットワーク利用、または依存関係の変更について承認を得てください。

5. インストール済みの契約に基づいて実装する

Blade Tracer は開発時のみ使用し、使用後は以前の状態に戻してください。上書きする前に、Shop からの正確な相対パスを確認してビューをコピーしてください。

• レイアウト、コンポーネント、インライン Vue、スクリプトの実行タイミング、レンダリングイベントについては、blade-vue-events.md を読んでください。
• ホーム／フッター／サービスのコンテンツ、チャネル、CMS、ロゴ、ファビコン、テーマカスタマイズのレコードについては、cms-channels-data.md を読んでください。
• Admin → Settings → Themes でマーチャントが編集できるホームページの新しいセクションを求められた場合、カスタムタイプを追加する前に、インストール済みのタイプで十分かどうかを判断してください。新しいタイプまたはエディターを追加する場合は、admin-theme-customization-components.md を読み、assets/theme-customization-component.contract.template.md を完成させてください。拡張機能はパッケージのスコープ内にとどめ、コンポーネントを追加するためだけに、インストール済みの Admin パッケージや Theme パッケージを変更しないでください。
• カタログ、商品、カート、チェックアウト、アカウント、決済、配送、または拡張機能の影響を受けやすいビューを変更する前に、commerce-contracts.md を読んでください。
• 翻訳、RTL、メタデータ、セマンティクス、画像、アイコン、フォントについては、localization-seo-media.md を読んでください。
• テーマブリーフで承認されたセマンティックトークンとページ構成を適用してください。継承されたビューでは、インストール済みの Tailwind 互換トークンを維持してください。Blade テンプレート内に、生の色、任意のスペーシング、単発のシャドウ、無関係なモーションを散在させないでください。

一貫性のある最小限のオーバーライド一式を実装してください。マーチャントがコンテンツを編集できる状態を保ち、コマースの状態はサーバーを正とし、Vue による拡張の前にも意味のあるサーバーレンダリング出力を維持してください。

6. ビルドと検証

リポジトリで承認されているフォーマッター、翻訳チェッカー、影響を受ける PHP テスト、テーマビルドを実行します。次に、以下を実行します。

python3 <skill-dir>/scripts/validate_theme.py \
  --project-root <project-root> \
  --theme-code <theme-code> \
  --package-dir <package-dir>

失敗を解消し、警告について説明します。承認済みの方針が変更された場合は、validate_theme_brief.py を再実行します。testing-deployment.md を読み、コンソール、ページエラー、失敗したリクエスト、モバイル、RTL、アクセシビリティ、パフォーマンスの証拠を含め、該当するストアフロントのテストマトリックスを実行します。チェックアウトに同等のカバレッジがない場合に限り、assets/storefront-smoke.template.spec.ts を調整します。

新規または再設計したすべてのテーマ、すべての有効化／リリース判断、動的コンテンツや管理画面で制御されるコンテンツ、またはストアフロント機能全体の証明を求める依頼については、埋め込みの bagisto-theme-testing スキル を読み、指示に従います。フォルダー内のリソースを使用して、次の作業を行います。

1. インストール済みの Shop／Admin の Playwright カバレッジと、条件に応じた商品／拡張機能の対象範囲を一覧化します。
2. ストアフロントで表示されるすべてのブロックを、それぞれの Bagisto の管理元に対応付けます。
3. 分離された環境で、管理画面での保存 → 対象範囲に応じたストアフロントへの反映 → 復元を実証します。
4. 該当するすべてのコマース利用シナリオを実施し、除外事項を明示します。
5. 完了した所有権マニフェストを検証してから、準備完了を宣言します。

静的な Blade の調査とスクリーンショットは、調査および視覚的な証拠にすぎません。マーチャントによる制御やコマースの正確性を証明するものではありません。

新しいスキャフォールドでは、生成された .bagisto-theme-baseline.json を保持します。このファイルには、絶対ホストパスを埋め込まずに、テーマが所有する Shop のソースと、Shop のビュー／アセット／検出されたビルド契約の完全なインベントリが記録されます。既存テーマの調整が完了し、該当するすべてのテストに合格したら、--json を使用して完全なパス／ハッシュ文書をプレビューし、内容を確認してから、適用フラグを付けて再実行します。

python3 <skill-dir>/scripts/snapshot_upgrade_baseline.py \
  --project-root <project-root> \
  --theme-code <theme-code> \
  --theme-path <theme-package-or-views-path> \
  --scaffold-mode <overlay-or-package-or-full-fork> \
  --json

その後、--json を --apply --acknowledge-reviewed に置き換えます。

外部プロセスで同じスキーマを作成する必要がある場合に限り、assets/override-baseline.template.json を使用します。アップグレード後にオーバーライドの差分を再実行し、検証に合格した場合に限り、承認済みハッシュを更新します。 以降の調整済みアップグレードでは、--refresh --json でプレビューし、続いて --refresh --apply --acknowledge-reviewed で適用します。更新では、同じテーマと Shop の識別情報に紐付いた有効なベースラインのみが、アトミックに置き換えられます。

7. 有効化と引き継ぎ

必要なゲートをすべて通過した後、次の作業を行います。

1. テーマカスタマイズのコンテンツが存在すること、または承認済みの空状態／フォールバック方針があることを確認します。
2. 対象チャネルの現在のテーマとロールバック手順を記録します。
3. 対象チャネルでのみ新しいテーマを選択します。
4. 必要に応じて、関連するキャッシュをクリア／再構築し、長時間稼働するプロセスを再読み込みします。
5. 本番環境のスモークテストを実行し、失敗した場合はソース／アセット／チャネルの選択をまとめてロールバックします。

変更ファイル、検出されたベースライン、スキャフォールドモード、統合戦略、ライセンス／通知およびアセットの出所に関する判断、ビルド／マニフェストの結果、テストと対象にしたブラウザー／ロケール／商品タイプ／拡張機能、アクセシビリティ／パフォーマンスの証拠、有効化の状態、ロールバック、オーバーライドの差分、リスクを伴う未実施のチェックをすべて報告します。

完了の定義

テーマがブランド固有で、視覚的に一貫性があり、レスポンシブで、マーチャントが利用でき、アップグレードの監査が可能で、依頼されたコマース利用シナリオ全体で実証されるまでは、完了を宣言しないでください。ブリーフの完成、ホームページの表示成功、またはアセットのビルドだけでは不十分です。