wi-site

Wonder Site（new-site ベース）

概要

wonder-image/new-site 内、またはそこから生成したプロジェクトでこのスキルを使用します。リポジトリが実行時の所有者です。フレームワークは vendor/wonder-image/app にあります（Composer。そこでの変更については wi-app を参照してください）。JS/CSS デザインシステムは assets/lib/wonder-image/dist/ にあります（npm の wonder-image/lib からコピーされています）。どちらもアップストリームとして扱い、その場で編集しないでください。

用語集

wi-app と wi-site で共通する用語です（両方のスキルで同じ表現を使用します）。

• フレームワーク — wonder-image/app（Composer パッケージ、github.com/wonder-image/app）。wi-app が有効な場合はリポジトリのルートにあり、サイト内では vendor/wonder-image/app/ にあります。
• lib — wonder-image/lib（npm パッケージ、github.com/wonder-image/lib）。JS / CSS デザインシステムです。ソースは node_modules/wonder-image/src/ にあり、コンパイル済みのコピーは assets/lib/wonder-image/dist/ にあります。
• スキャフォールド — wonder-image/new-site（github.com/wonder-image/new-site）。サイトのテンプレートです。スキャフォールド自体も有効なサイトです。
• サイト — composer.json が wonder-image/app に依存している（つまり、フレームワークを vendor/wonder-image/app にインストールする）プロジェクトです。通常はスキャフォールド、またはそこから派生したプロジェクトです。正式な用語です。「consumer project」や「consumer app」のような以前の混在した表現よりも、「site」を優先してください。
• モジュール — Composer（またはファイルシステムへのフォールバック）経由で検出される外部 Composer パッケージ wonder-image/<slug> です。module.json と ModuleInterface エントリーポイントを通じて、独自のモデル / リソース / ルートを提供します。
• custom/ — プロジェクトのページ、コンポーネント、レイアウト、ルート、設定、ヘルパーのためのサイト専用ディレクトリです。フレームワーク内には存在しません。
• app/Models / app/Resources — サイトの PSR-4 ルート（App\Models\... / App\Resources\...）です。フレームワークの class/App/Models / class/App/Resources（Wonder\App\Models\... / Wonder\App\Resources\...）とは異なります。

wi-app に切り替えるタイミング

次のいずれかに該当する場合は作業を中止し、wi-app に切り替えてください。作業の対象はこのサイトではなく、フレームワークです（frontmatter の SKIP ブロックにはルーター側のチェックがすでに記述されています。ここでは作業中の判断基準を示します）。

• リポジトリの composer.json に "name": "wonder-image/app" と宣言されている（サイトではなく、フレームワークのリポジトリ内にいます）。
• 変更対象が vendor/wonder-image/app/ にある。サイトから vendor を修正しないでください。変更を custom/ / app/Models / app/Resources に置く形に変更する（wi-site の範囲にとどまります）か、フレームワークのリポジトリに対して変更を行ってください（その場合は wi-app が適用されます）。
• Model / Resource の基底クラス、FormField ヘルパー、class/Elements/ 配下の要素、class/Themes/{Wonder,Bootstrap}/ 配下のテーマレンダラー、app/config/routes/* 内のルート、モジュール検出フロー、ブートストラップの順序、app/config/app/permission.php の権限ビルダーレジストリ、または共有ユーザー管理リソースを追加または変更する必要がある。
• タスクが「新しいフォーム入力タイプを追加する」「Wonder と Bootstrap でのフレームワークによる入力のレンダリング方法を変更する」「権限ビルダーを拡張する」「新しいコンソールコマンドのソースを登録する」、またはフレームワークの動作を利用するのではなく定義する作業である。
• wonder-image/lib（JS / CSS デザインシステムのソース）で作業する場合。これはまったく別のリポジトリであり、wi-site も wi-app も適用されません。

絶対に守るルール

• vendor/、node_modules/、assets/lib/wonder-image/dist/ は絶対に編集しないでください。最後のディレクトリは、wonder-image/lib から npm install によって再生成されます。
• サイトのタスクから vendor/wonder-image/app にパッチを当てないでください。変更が必要な場合は、wi-app に切り替えてください。
• このスキルから、次の Forge コマンドを絶対に実行しないでください。
  • php forge config
  • php forge credentials
  • php forge provision
  • php forge db:init
  • php forge build
• ユーザーに表示する文字列はすべて、lang/{locale}/*.json（pages.json、components.json、emails.json、legal.json など、JSON ファイルはいくつでも追加できます。サイトに必要な新しいファイルも含みます）にエントリーを用意して、__t(...) を通してください。URL には __r(string $name, array $parameters = []) を使用してください（推奨。名前付きルートから URL を生成し、アクティブなロケールを適用し、ルート名の変更にも対応できます）。名前付きルートがなく、自由なパスから URL を組み立てる必要がある場合（例：__u('contact')）に限り、__u(string $path) を使用してください。PHP にテキストや言語プレフィックスをハードコードしないでください。
• 新しい CSS クラス、JS の動作、UI 構造を作成する前に、wonder-image/lib を調べ、既存のデザインシステムを再利用してください。UI に関するルールブックの全文は references/style-and-lib.md にあります。UI、スタイリング、デザインシステムに関するタスクでは必ず読んでください。既定の方針は、ライブラリを変更せずに使用することです。
• <wi-card> は廃止されています。 サイトのバックエンドページに <wi-card> を記述しないでください。wonder-image/app の Card を使用してください。既存の使用箇所はライブラリから削除されるまでは動作しますが、編集する際に置き換えてください。
• 色（HEX／RGB／HSL）をハードコードしたり、.wi-*（またはその他の）接頭辞による命名規則を導入したり、独自の CSS システムを構築したりしないでください。{ASSETS_VERSION} は動的に検出してください。0.0/ など、特定のバージョンを前提にしないでください。
• プロジェクトに埋め込まれたモジュールのコードより、外部 Composer モジュール wonder-image/<slug> を優先してください。
• PSR-4 クラスは App\Models／App\Resources の名前空間を使用して、それぞれ app/Models と app/Resources に配置してください。プロジェクトのページ、コンポーネント、レイアウトのオーバーライド、ルート、設定、ヘルパーは custom/ に配置してください。
• 標準のモデル／テーブルのフローは Model::tableSchema() と Model::dataSchema() です。これと並行する別のテーブル定義システムを作成しないでください。

開始シーケンス

0. まず docs/ai/PRODUCT.md を読みます。 ここでは、レジスター（ブランドか製品か）、site_type、対象ユーザー、ブランドのパーソナリティ、声とトーン、デザイン原則が定義されています。以降の作業はすべて、その内容と一貫していなければなりません。配置の判断、コピー、モジュールの提案、UI の方向性も同様です。移行済みかどうかにかかわらず、すべてのサイトについて、各セッションで一度、ファイルが欠落または空かどうかを判断する前に、references/external-skills.md のサイト準備状況チェックを実行します。このチェックでは、ルートにある PRODUCT.md を docs/ai/ に移動し（追跡対象の場合は git mv、それ以外は mv を使用します。セクションが空のままの未編集のひな形テンプレートも対象です）、.gitignore と deploy.yml に行を追加し、docs/ai/reports/ を作成します。docs/ai/PRODUCT.md の内容を確認するのは、チェックが終わってからです。

   docs/ai/PRODUCT.md が存在しない、または必須セクションが空の場合は、まだユーザーの依頼に着手しないでください。 references/product-md.md § Compilation procedure のインタビュー手順を実行します。AskUserQuestion を使って一度に焦点を絞った質問を 2～4 個行い、回答が得られるたびに docs/ai/PRODUCT.md に保存します。その後、プロジェクトの明確度が少なくとも 80% に達するまでインタビューを続けます。明確度の基準は、必須の 6 セクション（Register、Site type、Target users、Brand personality、Voice / tone、Design principles）がすべて埋まり、さらに（Anti-references、Asset paths）の少なくとも一方が埋まっていることです。この条件を満たしてから、元の依頼に着手してください。理由：インタビューを省略すると、後でユーザーが修正しなければならない汎用的な成果物になってしまいます。インタビューにかける 10～15 分は、このセッションと今後のセッションにおける、その後のあらゆる判断に役立ちます。

   インタビューは順序立てて進め、回答に応じて調整します。ユーザーがすでに何かをさりげなく述べている場合（例：「abbiamo un brand di moda」）、該当するセクションにその内容をあらかじめ入力し、最初から聞き直すのではなく確認を求めます。完全なスキーマは references/product-md.md に、コピーして使えるテンプレートは references/examples.md §6 にあります。

   次に、タスクが UI に関係する場合（ページ、コンポーネント、スタイリング、トークン）は docs/ai/DESIGN.md を読みます。フレームワークは root.css を書き込むたびに CSS トークンからこのファイルを生成します。読み取り専用とし、編集しないでください。ファイルがない場合は、references/external-skills.md § Fallback without DESIGN.md に従います。

1. タスクを分類します。

   • ページまたはコンポーネントの作業
   • UI／スタイリング／デザインシステムの作業
   • モデル、リソース、リピーター、またはテーブルの作業
   • バックエンドで編集可能なコンテンツ
   • 権限、ロール、またはユーザー領域
   • 翻訳、ロケール URL、またはコンテンツテキスト
   • モジュールの統合
   • セットアップ、ランタイム、またはローカル環境

2. タスクに合ったリファレンスだけを読みます（「タスク別の参照先」を参照）。コピーして使えるひな形（Model と Resource の骨組み、フロントエンドページ、pages.json エントリー、permissions.php 拡張、modules.php）については、references/examples.md を直接参照します。

3. 作業場所が custom/、app/、外部の wonder-image/<slug> モジュール、または実際にフレームワーク内のいずれなのかを判断します（後者の場合は wi-app に切り替えます）。

4. 不適切な配置は拒否します。vendor/ を直接修正しないでください。node_modules/ や assets/lib/wonder-image/dist/ を手作業で編集しないでください。ユーザー管理ページを並行して作成しないでください。assets/{ASSETS_VERSION}/css/set-up/ 内にカスタム CSS を追加しないでください。

タスク別の参照先

ブランド、コピーライティング、ボイス、サイト種別

references/product-md.md を読んでください。docs/ai/PRODUCT.md は、文体、ターゲットユーザー、ブランドパーソナリティ、ボイス／トーン、デザイン原則、および site_type（landing／corporate／blog／ecom／rsvp）の信頼できる情報源です。コピーは lang/{locale}/*.json にあり、docs/ai/PRODUCT.md で定義されているボイスに従う必要があります。docs/ai/DESIGN.md はフレームワークが color.css と root.css から生成するファイルです。内容を確認し、編集しないでください。ビジュアルトークンについては、style-and-lib.md のルールが引き続き優先されます。

ページまたはコンポーネント

references/implementation-playbook.md と references/style-and-lib.md を読んでください。フロントエンドページのコピー＆ペースト用スケルトンは references/examples.md にあります。

• 手書きのマークアップよりも、Badge::inline()、Wonder\Elements\Frontend\EmptyState、Wonder\Elements\Frontend\Pagination、および Text／RichText の Wonder レンダラー（アプリ ≥ v2.4.0-beta.5）を優先してください。API については、wi-app/references/component-catalogue.md § Frontend list and text components を参照してください。
• 1つの再帰的なナビゲーションツリーで制御する再利用可能なヘッダーについては、references/header-navigation.md を読んでください。classic／mega の仕様、list のデフォルト、任意の card 表示、アクションリンク、外観オプション、デスクトップでのホバー動作、モバイルでのカスケードを定義しています。
• ページは custom/view/pages/{frontend,backend}/... に配置します。
• コンポーネントのオーバーライドは、フレームワークのパスを custom/view/components/{frontend,backend}/... に反映します。
• 手動の include よりも \Wonder\View\View::component(...) を再利用してください。
• 新しいマークアップを追加する前に、既存のページコンポーネントを確認してください。
• 公開ページですか？references/external-skills.md のルーティング表に従ってください。新しい公開ページまたはセクション → design-taste-frontend、既存の公開ページの作り直し → redesign-existing-projects、モックアップまたはスクリーンショットが提供されている場合 → image-to-code。バックエンドページでは外部スキルを使用しません。

UI／スタイリング／デザインシステム

まず references/style-and-lib.md を読んでください。ボタン、入力欄、フォーム、モーダル、カード、アラート、バッジ、タイポグラフィ、画像、インタラクティブ要素、カラートークン、ルート変数、カスタム CSS／JS に関わるすべてのタスクに適用されます。

• デフォルトの方針：ライブラリを 使用 し、変更しないでください。wonder-image/lib の変更には、ユーザーからの明示的な依頼が必要です。
• 新しいものを書く前に、既存のライブラリのクラスとトークンを再利用してください。.wi-*（またはその他の）接頭辞ベースの命名は禁止です。並行する CSS システムも作成しないでください。色をハードコードしないでください。
• トークンファイル：assets/{ASSETS_VERSION}/css/set-up/color.css と root.css。カスタム CSS／JS は assets/{ASSETS_VERSION}/css/ と assets/{ASSETS_VERSION}/js/ に配置し、set-up/ 内には置かないでください。
• トークンファイルを読み書きする前に、実際の assets/ ディレクトリから {ASSETS_VERSION} を特定してください。
• 公開 HTML／CSS に関わるタスクを完了する前に、references/external-skills.md の説明に従い、375／768／1280 で playwright-cli のスクリーンショットとコンソールを確認し、続いて変更したファイルに web-design-guidelines を適用してください。バックエンドのみのタスクでは、どちらも不要です。
• すべての UI タスクの最後に、references/style-and-lib.md の Required Final Report と Pre-Submit Checklist を記載してください。

外部スキル

references/external-skills.md を読んでください。ルーティング表（taste、redesign、image-to-code、web-design-guidelines、playwright-cli）、検出と --global によるオンデマンドインストール、外部からの提案より docs/ai/PRODUCT.md ＋ docs/ai/DESIGN.md ＋ style-and-lib.md を優先すること、docs/ai/reports/ でのレポート命名、サイトの準備状況チェックを記載しているのは、このファイルだけです。これらのルールをここで繰り返さないでください。

モデル、リソース、リピーター、テーブル — サイト向け補足

配置ワークフローについては references/implementation-playbook.md を読み、その後、references/examples.md のひな形から始めてください。API の完全な仕様（メソッドシグネチャ、ライフサイクル、レジストリの動作、リピーターの詳細）については、wi-app/references/model-and-resource.md を読んでください。wi-site と一緒に wi-app をインストールすると、ローカルで参照できるようになります。

新しいサイト Model と Resource の手順：

1. Model を app/Models/<Name>.php に作成し、名前空間を App\Models として、フレームワークの Model 基底クラスを継承します。
2. SQL は Model::tableSchema() で定義します。データの動作は Model::dataSchema() で定義します。
3. Resource を app/Resources/<Name>Resource.php に作成し、名前空間を App\Resources として、Model にバインドします。
4. バックエンド入力には formSchema()、ルートのアクセス制御には permissionSchema()、ナビゲーションの配置には navigationSchema() を定義します。
5. 繰り返し可能な行には FormField::repeater(...) と RepeaterColumn を使用し、CRUD 以外のページに限って CustomPageSchema を使用します。
6. composer dump-autoload を実行し、その後 php forge update --local を実行して、ランタイム生成を適用します。

標準的なフローは Model::tableSchema() と Model::dataSchema() です。これらとは別に、並行するテーブル定義ファイルを作成しないでください。

訪問者データ、手書きフォーム、トラッキング、.htaccess、デプロイ、バックアップ

references/security-and-deploy.md を読んでください。カスタムバックエンドページやメールでの訪問者データのエスケープ、手書きフォームとサイトルートでの CSRF、SafeRedirect、downloadAsText() によるエクスポート、同意の取得後に限った GTM のトラッキング、.htaccess の管理対象 WONDER ブロック、データベースのバックアップ、デプロイ時の除外に関する提案を取り上げています。同じ仕様のフレームワーク側の説明は wi-app/references/security.md にあります。

バックエンドで編集可能なコンテンツ

references/implementation-playbook.md を読んでください。実際の Model と Resource のフローを優先してください。メディアは既存のメディアリソースに接続してください。編集可能なコンテンツを静的配列や単独のファイルに保存しないでください。

権限、ロール、またはユーザー領域 — サイト向け補足

ビルダー API の全容、フレームワークのユーザーリソース、ランタイムの $PERMITS エクスポートは、wi-app の wi-app/references/permissions-and-users.md にあります。サイトで変更する箇所は、次の 1 か所だけです。

• custom/config/permissions.php — ベースファイル（フレームワークでは app/config/app/permission.php）とモジュールのマージ処理が完了した後で、レジストリを拡張または上書きします。ひな形のコピー＆ペースト例は references/examples.md にあります。

サイトの権限を追加または上書きする手順：

1. custom/config/permissions.php を開きます。
2. app/config/app/permission.php で初期化され、モジュールの権限とマージされたビルダーレジストリを拡張します。
3. 生成された権限キーを、プロジェクト内の任意の Resource::permissionSchema() とナビゲーションのアクセス制御で参照します。
4. 独自のユーザー管理ページを作成しないでください。ユーザー CRUD は共有フレームワークリソースに一元化されています。サイトで本当に別のユーザーフローが必要な場合は、フレームワークレベルの変更が必要です。wi-app に切り替えてください。

wi-app がまだローカルにインストールされていない場合は、npx skills add wonder-image/skills --skill wi-app を実行すると、リファレンス全体を利用できるようになります。

翻訳、ロケール URL、コンテンツテキスト

references/workflows.md を参照してください。references/examples.md に lang/it/pages.json のサンプルエントリがあります。

• 文字列は lang/{locale}/*.json に格納します。JSON ファイルの数に制限はありません。サイトにはデフォルトで pages.json、components.json、emails.json、legal.json が含まれます。新しいファイル（例：lang/{locale}/terms.json）も自動的に認識されます。
• __t("path.to.key") で翻訳済み文字列にアクセスします。
• URL を構築します。
  • __r(string $name, array $parameters = []) を優先してください。名前付きルートから URL を生成します。フロントエンドページ、リソースの CRUD ルート、カスタムバックエンドルートを含め、app/config/routes/ または custom/routes/ に登録されたすべてのルートで機能します。名前で解決するため、スラッグやパスが変更されても影響を受けません。
  • 名前付きルートがなく、パス文字列からロケール対応 URL を構築する必要がある場合（例：<a href="<?= __u('contact') ?>">）に限り、__u(string $path) を使用してください。
• 法的ページ（プライバシー、Cookie、利用規約）は wonder-image/app の LegalDocument::make('privacy') でレンダリングします。データベースの legal_documents のみが情報源であり、lang/{locale}/legal.json はシード用にすぎません。ページ内で __t('legal...') から法的文書のテキストを出力しないでください。
• サイトのテキストと法的文書は、クライアントが Set-up → Traduzioni で翻訳します（XLSX/CSV エクスポート、プレビュー付きインポート）。翻訳可能なコンテンツフィールドでは、サイトの Model に Translatable と HasTranslations を実装し、Model::translated($rows) で行を読み込んでください。スケジューラーが自動的に翻訳します。詳細は vendor/wonder-image/app/docs/app/concetti/traduzioni.md を参照してください。

モジュールの統合

references/project-structure.md と references/workflows.md を参照してください。

• 埋め込みコードより、外部 Composer パッケージ wonder-image/<slug> を優先してください。
• custom/config/modules.php でモジュールを有効にします。references/examples.md にコピーして使えるひな形があります。

セットアップ、ランタイム、またはローカル環境

references/workflows.md を参照してください。プロジェクトルートから実行します。

• composer install（Composer スクリプト経由で php forge config も実行します）
• npm install（wonder-image/lib を assets/lib/wonder-image/dist/ にコピーします）
• php forge credentials（ユーザーが Bitwarden dev-shared からの復旧を明示的に要求した場合に限ります。シークレットを .env に書き込みます）
• php forge update --local（DB とランタイムの生成を適用します）
• php forge start（ローカルサーバーを起動し、不足している .env の値を補完する場合があります）

検証

• 変更したすべての PHP ファイルに対して php -l を実行します。
• PSR-4 クラスを追加、移動、または名前変更した場合は composer dump-autoload を実行します。
• 統合に影響する変更の場合は、php forge update --local を実行してから php forge start を実行します。
• 変更が wonder-image/lib の assets/lib/wonder-image/dist/ に依存する場合に限り、npm install を再実行します。

出力に関する要件

• 変更した具体的なサイトパスを明記します（例：custom/view/pages/frontend/about.php、app/Models/Project.php、lang/it/pages.json）。
• 要求された変更が実際にはフレームワーク（→ wi-app）または wonder-image/lib に属する場合は、その旨を明記します。
• 該当する場合は、翻訳ファイルの更新、権限／認可の変更、Forge／npm の再ビルド手順を列挙します。
• vendor/、node_modules/、assets/lib/wonder-image/dist/、または Forge が生成したファイルへの編集は、理由を一行で添えて拒否します。