craft-site

Craft CMS 5 — フロントエンド Twig（アトミックデザイン）

Craft CMS 5 のサイトテンプレート向けアトミックデザインシステムのパターンです。Vanilla Twig — モジュールへの依存はありません。あらゆる Craft 5 プロジェクトで使用できます。

このスキルの対象はフロントエンドのテンプレートアーキテクチャ（コンポーネント設計、 ルーティング、構成、テーマ設定、ビルドチェーン）です。Craft の拡張（プラグイン、 モジュール、PHP）については、craftcms スキルを参照してください。

関連スキル — 必ず一緒に読み込む

このスキルが呼び出されたときは、次のスキルも読み込んでください。

• craft-twig-guidelines — Twig のコーディング規約：変数名、null の処理、空白制御、include の分離、Craft ヘルパー。Twig コードには必須です。
• craft-content-modeling — セクション、エントリータイプ、フィールド、Matrix、リレーション。どのコンテンツをクエリするか、テンプレートからデータにアクセスする方法を決める際に必須です。
• ddev — すべてのコマンドを DDEV 経由で実行します。Vite、npm、Craft CLI コマンドの実行に必須です。
• craft-cloud — サイトが Craft Cloud でホストされている場合（リポジトリのルートにある craft-cloud.yaml、または composer.json の craftcms/cloud で検出）。エッジの静的キャッシュルール、キャッシュされたページ内の動的な領域に対する cloud.esi(...)、エッジでの画像変換の制約、キャッシュ可能なページでの csrfInput() の要件に必須です。
• servd — サイトが Servd でホストされている場合（リポジトリのルートにある servd.yaml、または composer.json の servd/craft-asset-storage で検出）。Servd の静的キャッシュ、キャッシュされたページ内の {% dynamicInclude %} による領域、リバースプロキシモードでの Blitz の実行、サーバー外での画像変換に必須です。

ドキュメント

• Craft における Twig：https://craftcms.com/docs/5.x/development/twig.html
• テンプレートタグ：https://craftcms.com/docs/5.x/reference/twig/tags.html
• テンプレート関数：https://craftcms.com/docs/5.x/reference/twig/functions.html
• Twig 3 ドキュメント：https://twig.symfony.com/doc/3.x/

参照ファイルだけでは詳細が不十分な場合は、特定のドキュメントページで WebFetch を使用してください。

よくある落とし穴（横断的な注意点）

• {% include %} に only がない — 暗黙の変数が気付かないうちに漏れ込みます。
• extends/block ではなく、条件分岐（{% if variant == 'x' %}）でバリアントのロジックを実装する。
• 見た目の扱い（button--primary）ではなく、親のコンテキスト（hero-button）に基づいて atom に名前を付ける。
• utilities プロパティを上書き用として使う — これは追加用です。名前付きスロットのマージで上書きしてください。
• ビュー内でクエリを実行する — ビューはデータを受け取り、取得はしません。
• ビュー内のリレーションフィールドで .eagerly() を使わない — N+1 クエリの原因になります。
• 未知のブロックタイプに対するビルダー内の devMode フォールバックがない。
• CSP nonce、csrfInput()、アクティブなナビゲーション状態、言語切り替えを {% cache %} 内に置く。最初のレンダリング結果がすべてのユーザーに再利用されます。template-caching.md を参照してください。
• ブランドトークン（bg-brand-accent）ではなく、Tailwind の色（bg-yellow-600）をハードコードする。
• ボタンとリンクを混同する — ボタンはアクション（プロパティに応じて <a>、<button>、または <span> になる）、リンクはナビゲーション（常に <a>）です。別々の atom カテゴリにしてください。
• コンポーネント内にトラッキングや分析コードを置く — ビュー／ページレベルのデータ属性に分離してください。
• CP 外で YAML を編集した後に project-config/touch を忘れる — Git の pull、手動編集、マージ競合の解決では dateModified は更新されません。ddev craft project-config/touch を実行してから ddev craft up を実行してください。それ以外の環境では、craft up を実行しても変更を検出できません。

参照ファイル

タスクに関連する参照ファイルを読んでください。複数のファイルが該当することもよくあります。 タスクの例：

• 「新しいカードコンポーネントを作成する」→ atomic-patterns.md + composition-patterns.md + component-inventory.md + tailwind-conventions.md を読む
• 「新しいプロジェクトのテンプレート構造を設定する」→ boilerplate-routing.md + component-inventory.md を読む
• 「Matrix フィールド用のコンテンツビルダーを追加する」→ boilerplate-routing.md + composition-patterns.md を読む
• 「レスポンシブ画像を扱う」→ image-presets.md + plugins/image-optimize.md を読む
• 「{% cache %} でナビゲーション／フッターをキャッシュする」→ template-caching.md を読む
• 「{% cache %} の追加後に CSP でスクリプトがブロックされる／nonce が一致しない」→ template-caching.md（CSP Nonces）を読む
• 「アップロード後の最初のページ表示が遅い／画像が generate-transform URL になる理由」→ image-presets.md（Transform Generation Timing）+ plugins/image-optimize.md を読む
• 「複数ブランドのテーマ設定を追加する」→ tailwind-conventions.md を読む
• 「機能に Alpine と Vue のどちらを使うか決める」→ javascript-boundaries.md を読む
• 「競合を避けて Tailwind クラスを組み合わせる」→ tailwind-conventions.md + twig-collections.md を読む
• 「アトミックデザインの方法論を理解する」→ atomic-design.md を読む
• 「新しい Craft プロジェクトで Vite + Tailwind を設定する」→ vite-buildchain.md を読む
• 「本番環境でアセットが読み込まれない原因をデバッグする」→ vite-buildchain.md を読む
• 「craft.vite.* Twig 関数（asset、register、critical CSS）を調べる」→ plugins/vite.md を読む
• 「Craft プロジェクトに GTM／分析ツール／CMP をインストールする」→ third-party-integration.md を読む
• 「プラグインのフロントエンド CSS を上書きできない／プラグインのスタイルが優先される」→ third-party-integration.md（Plugin CSS Loads After Yours）を読む
• 「プラグインのテンプレートを独自のものに置き換える／プラグインのウィジェットが機能しなくなった」→ third-party-integration.md（Hand-Written Templates for Plugin Widgets）を読む
• 「セクション用に SEOMatic を設定する」→ plugins/seomatic.md を読む
• 「Cloudflare で Blitz キャッシュを設定する」→ plugins/blitz.md を読む
• 「ページにフォームを追加する」→ plugins/formie.md を読む
• 「ネストされたエントリで CKEditor を設定する」→ plugins/ckeditor.md を読む
• 「ナビゲーションメニューを作成する」→ plugins/navigation.md を読む
• 「コンポーネントにリンクフィールドを追加する」→ plugins/hyper.md を読む
• 「サイトのリダイレクトを設定する」→ plugins/retour.md を読む
• 「エントリに定期的／反復する日付を追加する」→ plugins/timeloop.md を読む
• 「JSON API エンドポイントを作成する」→ plugins/element-api.md を読む
• 「テンプレートの N+1 クエリをデバッグする」→ plugins/elements-panel.md を読む
• 「セキュリティ監査を実行する」→ plugins/sherlock.md を読む
• 「YouTube／Vimeo の動画をアセットとして埋め込む」→ plugins/embedded-assets.md を読む
• 「SES 経由のメール配信を設定する」→ plugins/amazon-ses.md + third-party-integration.md を読む
• 「言語切り替え機能を作成する」→ multi-site-patterns.md を読む
• 「フロントエンドにログイン／登録機能を追加する」→ auth-flows.md を読む
• 「ユーザープロフィール編集ページを作成する」→ auth-account.md を読む
• 「パスワードリセットのフローを設定する」→ auth-flows.md を読む
• 「hreflang タグを設定する」→ multi-site-patterns.md を読む
• 「多言語サイトのアーキテクチャを計画する」→ multi-site-patterns.md を読む
• 「JavaScript を使わずにライブ検索を追加する」→ plugins/sprig.md を読む
• 「リアクティブな絞り込みや「さらに読み込む」機能を作成する」→ plugins/sprig.md を読む
• 「外部フィードからデータをインポートする」→ plugins/feed-me.md を読む
• 「Imager-X でレスポンシブ画像を設定する」→ plugins/imager-x.md を読む
• 「検索ページを作成する」→ search.md を読む
• 「検索設定を構成する」→ search.md（Search Configuration）を読む
• 「検索インデックスを再構築する」→ search.md（Rebuilding）を読む
• 「RSS フィードを作成する」→ feeds.md を読む
• 「XML サイトマップを作成する」→ feeds.md（XML Sitemap）を読む
• 「JSON Feed を作成する」→ feeds.md（JSON Feed）を読む
• 「Next.js でヘッドレス Craft CMS を設定する」→ headless.md を読む
• 「GraphQL のプレビュー用トークンを修正する」→ headless.md を読む
• 「フロントエンドフレームワークから Craft GraphQL API を利用する」→ headless.md を読む
• 「再利用可能なカードコンポーネントに entry.render() を使う」→ element-partials.md を読む
• 「エントリ用の _partials/ テンプレートを設定する」→ element-partials.md を読む
• 「パーシャルを使って Matrix ブロックをレンダリングする」→ element-partials.md を読む
• 「プラグインにサンプルテンプレートを同梱して配布する（バンドル + インストールコマンド）」→ example-templates.md を読む
• 「流暢なフロントエンドのレンダリング／タグビルダーを作成する（craft..thing().render()）」→ example-templates.md を読む | 参照先 | 範囲 | |-----------|-------| | references/atomic-design.md | 方法論：Brad Frost のアトミックデザインの原則、5 層から 3 層への圧縮、コンポーザビリティ、コンテキストに依存しない命名、分類の問題、下位へ分解するワークフロー。技術に依存しません。 | | references/atomic-patterns.md | 個々のコンポーネントの構築：props/extends/block パターン、バリアントファイルの仕組み、ボタン／リンク／テキスト／アイコンのアトム実装 | | references/composition-patterns.md | コンポーネントの合成：モレキュールパターン、オーガニズムパターン、構造埋め込みパターン、include/extends/embed の選択表、呼び出し規約、新しいコンポーネントの作成 | | references/component-inventory.md | 分類方法：判断ツリー、命名規則、ファイル命名、props の設計、スキャフォールドのガイドライン、階層の昇格、監査チェックリスト | | references/boilerplate-routing.md | テンプレートチェーン：レイアウト階層、Craft セクションのテンプレートパス、グローバル変数、ルーター、ビュー、コンテンツビルダー、ディレクトリ構成 | | references/tailwind-conventions.md | クラスの合成：名前付きキーのコレクション、標準キー名、utilities prop、バリアントベースのダークモード、スペーシングの優先設定。Tailwind CSS を前提としています。パターンは使用する CSS フレームワークに合わせて調整してください。 | | references/vite-buildchain.md | Craft CMS の Vite 設定：nystudio107 プラグインブリッジ、config/vite.php、vite.config.ts、craft.vite.script()、ページごとの条件付き読み込み、Tailwind v4 との統合、DDEV の設定 | | references/image-presets.md | 画像の処理：プリセットを使う単一のアトム、srcset/sizes、ImageOptimize と Craft Cloud の比較、ホスティング戦略、変換生成のタイミング（generateTransformsBeforePageLoad） | | references/template-caching.md | {% cache %} タグ：キー設定（URL ごと、globally、using key）、パラメーターの順序、タグ内に含めてよいもの／いけないもの、CSP nonce、アクティブ状態と言語切り替えをキャッシュ対象外にしたナビゲーション／フッターの例、一時的な変換 URL、検証手順 | | references/javascript-boundaries.md | JS の判断ツリー：Twig → Alpine/DataStar → Vue、マウントポイント、データの受け渡し、共存ルール | | references/twig-collections.md | collect() メソッドのリファレンス：作成、アクセス、変換、フィルタリング、並べ替え、スライス、アロー関数 | | references/third-party-integration.md | スクリプトの読み込み順序、CMP（UserCentrics/CookieBot）、GTM/sGTM のデータレイヤー、アナリティクス（Fathom/Plausible）、AWS SES トランスポート、n8n Webhook、プラグインの CSS カスケード（自作 CSS の後に読み込まれます）とプラグインウィジェット用の手書きテンプレート、Blitz との互換性、head テンプレート全体の例 | | references/multi-site-patterns.md | 言語切り替え、hreflang タグ、サイトアーキテクチャ（サブフォルダー／ドメイン／サブドメイン／マルチブランド）、クロスサイトクエリ、静的翻訳、サイト固有のテンプレート、マルチサイトフォーム、サイトの検出 | | references/auth-flows.md | フロントエンド認証フォーム：ログイン、登録、パスワードリセット、新しいパスワードの設定 | | references/auth-account.md | アカウント管理：プロフィール編集、メール確認、ナビゲーションのパーシャル、アクセス制御タグ、ユーザーセッションヘルパー、GeneralConfig の認証設定 | | references/search.md | 検索：構文、Twig クエリ、設定、インデックス作成、再構築、スコアとランキング | | references/feeds.md | フィード：RSS 2.0、Atom、JSON Feed、XML サイトマップ、カスタムルート、日付フィルター | | references/headless.md | ヘッドレスとハイブリッド：headlessMode、GraphQL API、CORS、プレビュートークン、Next.js/Nuxt/Astro との統合 | | references/element-partials.md | エレメントパーシャル：entry.render()、_partials/ ディレクトリ、テンプレート検索、カスタム変数、パーシャル内の先行読み込み | | references/example-templates.md | プラグインのフロントエンド配信：Craft Commerce 形式のサンプルテンプレート一式（標準フォルダー、_private/layouts/ シェル、ページごとの {% extends %}／{% block main %}、リダイレクト用の index.twig、名前変更／--overwrite に対応したインストール用コンソールコマンド）、流暢な craft.<handle>.<thing>({...}).render() BaseTag ビルダー、プログレッシブエンハンスメントの徹底 |

プラグインリファレンス

プラグインごとの設定、Twig API、注意点は craft-plugins スキル（skills/craft-plugins/references/<plugin>.md）に記載されています。フロントエンドのタスクだけでなく、バックエンド、移行、デプロイのタスクからも見つけられるよう、そこにまとめています。

フロントエンドのタスクで特定のプラグイン（Formie のフォームスタイリング、SEOmatic のメタデータ、Blitz のキャッシュ、Imager-X / ImageOptimize の変換、Sprig のコンポーネント、CKEditor、Hyper リンク、Navigation、Embedded Assets、Vite、Typogrify、Colour Swatches）を扱う場合は、craft-plugins スキルを読み込み、該当するリファレンスを開いてください。

コンポーネントシステムの規約

すべてのプロジェクトで、単一の標準コンポーネントシステムを使用します。アトムはコンテキストに依存しません。名前は常に視覚的なスタイルに基づけ、親要素に基づけないでください。HTML 要素の種類は props から決定します（url → <a>、type → <button>、それ以外の場合 → <span>）。

外部リンクかどうかは URL から判定し、props として渡しません。URL が外部リンクの場合、コンポーネントは target="_blank"、rel="noopener noreferrer"、外部リンクアイコン、スクリーンリーダー専用テキストを自動的に適用します。

FontAwesome を共通のアイコンシステムとして使用します。アイコンは FA クラス文字列で渡します。

見た目のバリエーションには extends/block を使用します。ベーステンプレートで構造を定義し、バリエーション側でクラスをオーバーライドします。バリエーションのスタイルを切り替えるために条件分岐を使用しないでください。コンテンツスロットを持つ構造的な骨組みには {% embed %} を使用します。composition-patterns.md を参照してください。

画像の処理には、コンテキストごとに別々のバリエーションファイルを用意するのではなく、設定駆動のプリセットを使う単一のアトムを使用します。

CSS とテーマ設定の規約

このスキルでは、クラスを組み合わせる例として Tailwind CSS を想定しています。パターンは使用する CSS フレームワークに合わせて調整してください。名前付きキー、追加的なユーティリティ、セマンティックトークンといったアーキテクチャ上の原則は、フレームワークに依存しません。

クラスのコレクションは、スタイルの関心事ごとに名前付きキーを使用します。これが競合を防ぐ主要な仕組みです。utilities prop は追加（拡張）用であり、上書き用ではありません。名前付きスロットのマージを使って、特定の関心事のみをオーバーライドしてください。

マルチブランドのテーマ設定では、<html> に data-brand="{{ currentSite.handle }}" を指定して CSS カスタムプロパティを有効にします。コンポーネントはセマンティックな Tailwind クラス（bg-brand-accent）を参照し、CSS 変数によって解決します。テンプレートレベルのブランド別オーバーライドが必要なのは、ブランド間で HTML 構造自体が異なる場合に限ります。色、フォント、間隔の違いには使用しません。

トークンの命名は 3 層に分かれます。プリミティブ（--brand-{color}-{shade}）、セマンティクス（--brand-{purpose}）、フレームワークマッピング（--color-brand-{purpose}）です。

Tailwind v4 のカスケードレイヤーでは、同じユーティリティレイヤー内のクラス競合は解決されません。名前付きキーによるコレクションは引き続き必要です。

ルーティングの規約

データは PHP が処理し、表示は Twig が処理します。ビューは include を通じてデータを受け取り、自身でデータをクエリすることはありません。

props の構築とクラスの構築の両方に collect() を使用します。Craft を通じて、Collection の API 全体を Twig から利用できます。

JS との境界では、次の判断ツリーに従います。デフォルトは Twig → UI の状態には Alpine/DataStar → アプリケーションの状態には Vue。