building-blocks

ブロックの構築

このスキルでは、確立されたパターンとベストプラクティスに従って、AEM Edge Delivery ブロックを実装する方法を説明します。ブロックは、JavaScript による装飾と CSS のスタイル設定を通じて、作成されたコンテンツを豊かでインタラクティブなエクスペリエンスに変換します。

重要：このスキルは、Step 5（実装）で content-driven-development スキルからのみ呼び出してください。

CDD プロセスに従っていない場合は、作業を中止して、まず content-driven-development スキルを呼び出してください。

関連スキル

• content-driven-development：コンテンツとコンテンツモデルが準備できていることを確認するため、このスキルを使用する前に必ず呼び出してください
• da-auth：実装を開始する前に、テスト用コンテンツを DA にプッシュする必要がある場合は、有効な Adobe IMS トークンを取得します
• block-collection-and-party：パターンを探すため、類似したブロックを見つける際に使用します
• testing-blocks：包括的なテストのため、Step 5 で自動的に呼び出されます

このスキルを使用する場面

このスキルは、Step 5（実装）で content-driven-development によって自動的に呼び出されます。以下を扱います。

ブロックの開発：

• 新しいブロックファイルと構造の作成
• JavaScript による装飾の実装
• CSS のスタイル設定の追加

コア機能：

• Scripts.js の変更（装飾、ユーティリティ、自動ブロック化）
• グローバルスタイル（styles.css、lazy-styles.css）
• 遅延機能（delayed.js）
• 設定の変更

組み合わせ：

• サポートするコア部分の変更（ユーティリティ、グローバルスタイルなど）を伴うブロック

前提条件（CDD により確認済み）：

• ✅ テスト用コンテンツが存在する（CMS またはローカルの下書き）
• ✅ コンテンツモデルが定義・文書化されている（該当する場合）
• ✅ テスト用コンテンツの URL が利用可能
• ✅ 開発サーバーが起動している

ブロックの実装ワークフロー

進捗を記録してください。

• Step 1：パターンを参考にするため、類似したブロックを探す（新しいブロックまたは大幅な変更の場合）
• Step 2：ブロックの構造（ファイルとディレクトリ）を作成または変更する
• Step 3：JavaScript による装飾を実装する（CSS のみの場合はスキップ）
• Step 4：CSS のスタイル設定を追加する
• Step 5：実装をテストする（testing-blocks スキルを呼び出します）

注： 変更にコア部分の修正（scripts.js のユーティリティ、グローバルスタイルなど）が必要な場合は、まずその変更を行ってテストしてから、このワークフローに戻ってください。以下の「コアファイルを変更する場合」を参照してください。

Step 1：類似したブロックを探す

使用する場面： 新しいブロックを作成する場合、または構造を大幅に変更する場合

このステップをスキップする場面： 既存のブロックに小規模な変更（CSS の微調整、小規模な装飾の変更）を加える場合

クイックスタート：

1. コードベースで類似したブロックを検索します。

   ls blocks/
   

2. block-collection-and-party スキルを使用して、参考となる実装を見つけます

3. 類似したブロックのパターンを確認します。

   • DOM 操作の方針
   • CSS のアーキテクチャ
   • バリアントの処理
   • パフォーマンスの最適化

Step 2：ブロックの構造を作成または変更する

新しいブロックの場合：

1. ブロックのディレクトリとファイルを作成します。

   mkdir -p blocks/{block-name}
   touch blocks/{block-name}/{block-name}.js
   touch blocks/{block-name}/{block-name}.css
   

2. JavaScript の基本構造：

   /**
    * decorate the block
    * @param {Element} block the block
    */
   export default async function decorate(block) {
     // Your decoration logic here
   }
   

3. CSS の基本構造：

   /* All selectors scoped to block */
   main .{block-name} {
     /* block styles */
   }
   

既存のブロックの場合：

1. ブロックのディレクトリを確認します：blocks/{block-name}/
2. 現在の実装を確認します。

   # View the initial HTML structure from the server
   curl http://localhost:3000/{test-content-path}
   

3. 既存の装飾ロジックとスタイルを把握します

Step 3：JavaScript による装飾を実装する

必須パターン — 既存の DOM 要素を再利用します。

export default async function decorate(block) {
  // Platform delivers images as <picture> elements with <source> tags
  const picture = block.querySelector('picture');
  const heading = block.querySelector('h2');

  // Create new structure, re-using existing elements
  const figure = document.createElement('figure');
  figure.append(picture);  // Re-uses picture element

  const wrapper = document.createElement('div');
  wrapper.className = 'content-wrapper';
  wrapper.append(heading, figure);

  block.replaceChildren(wrapper);

  // Only check variants when they affect decoration logic
  // CSS-only variants like 'dark', 'wide' don't need JS
  if (block.classList.contains('carousel')) {
    // Carousel variant needs different DOM structure/behavior
    setupCarousel(block);
  }
}

以下を含む JavaScript の詳しいガイドラインについては：

• 高度な DOM 操作パターン
• データの取得とモジュールの読み込み
• パフォーマンス最適化の手法
• aem.js のヘルパー関数
• コードスタイルとリンティングのルール

references/js-guidelines.md をお読みください。

ステップ 4：CSS スタイルを追加する

基本パターン：スコープ化、レスポンシブ対応、カスタムプロパティの使用

/* All selectors MUST be scoped to block */
main .my-block {
  /* Use CSS custom properties for consistency */
  background-color: var(--background-color);
  color: var(--text-color);
  font-family: var(--body-font-family);
  max-width: var(--max-content-width);

  /* Mobile-first styles (default) */
  padding: 1rem;
  flex-direction: column;
}

main .my-block h2 {
  font-family: var(--heading-font-family);
  font-size: var(--heading-font-size-m);
}

main .my-block .item {
  display: flex;
  gap: 1rem;
}

/* Tablet and up */
@media (width >= 600px) {
  main .my-block {
    padding: 2rem;
  }
}

/* Desktop and up */
@media (width >= 900px) {
  main .my-block {
    flex-direction: row;
    padding: 4rem;
  }
}

/* Variants - most are CSS-only */
main .my-block.dark {
  background-color: var(--dark-color);
  color: var(--clr-white);
}

CSS のガイドライン全般については、以下を参照してください：

• 使用可能なすべての CSS カスタムプロパティ
• 最新の CSS 機能（グリッド、論理プロパティなど）
• パフォーマンスの最適化
• 命名規則
• 一般的なパターンとアンチパターン

references/css-guidelines.md をお読みください

反復的な検証に関する注意： 構築中は、作業を進めながらブラウザーで変更をテストできます（テストコンテンツの URL を読み込み、コンソールを確認し、レイアウトと機能を検証します）。ブラウザーテストの手法、レスポンシブテスト、検証方法を含む包括的なテストガイダンスについては、ステップ 5 で呼び出す testing-blocks スキルを参照してください。

ステップ 5：実装をテストする

実装が完了したら、testing-blocks スキルを呼び出してください。

testing-blocks スキルでは、以下について案内します：

• ブラウザーテスト（機能、各ビューポートでのレスポンシブ動作）
• リントと問題の修正
• ロジックが複雑なユーティリティのユニットテスト作成（必要な場合）
• 検証用のスクリーンショット撮影
• パフォーマンスの検証

testing-blocks スキルに以下を渡してください：

• テスト対象のブロック名
• テストコンテンツの URL（CDD プロセスのステップ 4 から）
• テストが必要なバリエーション
• 照合用の既存実装／デザイン／モックアップのスクリーンショット
• 検証する受け入れ基準（CDD プロセスのステップ 2 から）

テストが完了したら、CDD ワークフローに戻ってください。

---

コアファイルを変更する場合

変更にコアファイル（scripts.js、styles.css、delayed.js）の編集が必要な場合は、以下の原則に従ってください：

一般的なコアファイル：

• scripts.js - 装飾ユーティリティ、自動ブロック化ロジック、ページ読み込み
• styles.css - グローバルスタイル（先行読み込み）、CSS カスタムプロパティ
• lazy-styles.css - グローバルスタイル（遅延読み込み）
• delayed.js - マーケティング、分析、サードパーティ統合

主な原則：

1. 最初にコアを変更する（依存するブロックの変更より前に行います）
2. ブロックで使用する前に、既存コンテンツでコアの変更を個別にテストする
3. 影響を考慮する - コアの変更は複数のブロックやページに影響する可能性があります
4. 十分にテストする - 既存機能に問題が生じていないことを確認します
5. 最小限にとどめる - 必要なものだけを追加します
6. コードコメントで説明する - ほとんどのコア変更には個別のドキュメントは不要です

コア変更のテスト：

• 影響を受ける機能を使用している既存コンテンツの URL でテストします
• 自動ブロック化の場合：自動ブロック化が適用されるべきページと、されるべきでないページをテストします
• グローバルスタイルの場合：複数のブロックやページでテストします
• コンソールにエラーがないか確認します
• レスポンシブ動作を検証します

詳細なパターンについて：

• JavaScript：references/js-guidelines.md を参照してください
• CSS：references/css-guidelines.md を参照してください

---

参考資料

• references/js-guidelines.md - JavaScript のパターンとベストプラクティス全般
• references/css-guidelines.md - CSS のパターンとベストプラクティス全般