create-component

AEM コンポーネント作成スキル

Adobe のベストプラクティスに従って、完全な AEM コンポーネントを作成します。

設定ゲートの確認 — 最初に実行

設定の確認を最初に行う必要があります。これを行わないと、このスキルは誤ったプロジェクトパスとパッケージ名を使用し、生成されるすべてのファイルが間違ったものになるためです。

最初のツール呼び出し：プロジェクトルート（pom.xml と同じ階層）にある .aem-skills-config.yaml を読み込みます。

確認事項：ファイルが存在し、configured: true になっていますか？

状態	アクション
ファイルが存在しない、または configured: false	停止して、以下のエラーメッセージを表示します。コードベースを調査したり、先に進んだりしないでください — 正しいファイルパスと命名には設定値が必要です。ユーザーが設定するまで待ちます。
configured: true	YAML ファイルからプロジェクト、パッケージ、グループの値を読み込みます。コンポーネントの作成に進みます。

設定されていない場合は、このメッセージを表示して停止します：

Project configuration required!

Before creating components, configure your project settings in:
`.aem-skills-config.yaml` (in your project root, same level as pom.xml)

Open the file and update:
- project: Your AEM project name (e.g., 'mysite', 'wknd')
- package: Your Java package (e.g., 'com.mysite.core')
- group: Your component group (e.g., 'MySite Components')
- configured: true

After updating, ask me to create the component again.

設定されていない状態でコードベースを調査してはいけない理由：

設定前に以下のいずれかを行うと、誤った推測につながり、作業が無駄になります。

• リポジトリ内の他のファイルを読む
• 「プロジェクトを理解する」ためにディレクトリを一覧表示する
• 既存のコンポーネントを確認してパターンを調べる
• pom.xml、Java ファイル、フォルダー構成を確認する
• 何らかの情報源から値を推測する

設定ファイルはプロジェクト値の唯一の信頼できる情報源です。これを読み飛ばすと、生成されるすべてのファイルでパスとパッケージ名が誤ったものになります。

ハルシネーション禁止ルール

ユーザーが指定したフィールドだけを正確に作成してください。余分なフィールドを追加すると、オーサリング時の混乱やメンテナンス負担につながり、フィールド名を変更するとコンテンツの契約が壊れます。

ルールの全文を確認するには：references/no-hallucination-rules.md を読み込みます。

ワークフローの概要

ステップ	アクション
0	設定の検証（最初に実行 — 上記を参照）
1	コンポーネント名の抽出と検証
1.5	コンポーネント拡張の判断（拡張する場合）
2	要件の収集とダイアログ仕様の確認
2.3	Figma デザインの取得（Figma URL が指定されている場合）
3	コンポーネントファイルをすべて作成
3.11	依存関係の検証（サーブレットでは必須）
4	完了の概要

ステップ 0：設定の検証

0.1 設定を読み込む

1. プロジェクトルートから .aem-skills-config.yaml を読み込みます
2. configured: true であることを確認します
3. project、package、group の値を読み込みます

0.2 検証 — 設定ファイルのみを使用する

ファイルシステム、既存コンポーネント、Java ファイル、pom.xml、または既存の知識からプロジェクト値を推測しないでください。これらの情報源は古くなっている、または一貫性がない可能性があります。.aem-skills-config.yaml はユーザーが明示的に設定する唯一の信頼できる情報源です。

0.3 規約を読み込む

1. ファイル構造のテンプレート、命名規則、パターンについて、references/aem-conventions.md を読み込みます

0.4 プロジェクトの状態を分析する（設定の検証後）

1. コンポーネント名の重複を確認 — /apps/[project]/components/ を調べます
2. モデルクラスの競合を確認 — core/src/main/java/[package-path]/models/ を調べます
3. 既存のパターンを分析 — スタイルの参考として、最近のコンポーネントを1～2個確認します

ステップ 1：コンポーネント名の抽出と検証

• ユーザーのメッセージからコンポーネント名を解析します（指定されていない場合は尋ねます）
• 小文字のケバブケースに正規化します（例：My Component -> my-component）
• 検証します：英字で始まり、英字・数字・ハイフンのみを使用し、ハイフンを連続させないこと

ステップ 1.5：コンポーネント拡張の判断

ユーザーが「{component}を拡張して」と言った場合：

ティア 1：まずプロジェクトコンポーネントを確認する

• /apps/{project}/components/{component} を検索します
• 見つかった場合 -> sling:resourceSuperType として使用します

ティア 2：コアコンポーネントを確認する

ユーザーの指定	対応先
画像	core/wcm/components/image/v3/image
ティーザー、カード	core/wcm/components/teaser/v2/teaser
テキスト、リッチテキスト	core/wcm/components/text/v2/text
タイトル、見出し	core/wcm/components/title/v3/title
リスト	core/wcm/components/list/v4/list
ボタン、CTA	core/wcm/components/button/v2/button
ナビゲーション、ナビ	core/wcm/components/navigation/v2/navigation
コンテナー、セクション	core/wcm/components/container/v1/container
アコーディオン	core/wcm/components/accordion/v1/accordion
タブ	core/wcm/components/tabs/v1/tabs
カルーセル	core/wcm/components/carousel/v1/carousel
埋め込み、動画	core/wcm/components/embed/v2/embed

ティア 3：見つからない場合 - ユーザーに確認を求めます。

拡張パターンについては、以下を読み込みます： references/extending-core-components.md

ステップ 1.6：コアコンポーネントの拡張要件

「非表示」「削除」「カスタムフィールドの追加」「オーバーライド」による拡張時に必須（これらの操作を正しく機能させるには、Sling Resource Merger のパターンが必要です）：

参照を読み込みます： references/extending-core-components.md

ユーザーのリクエスト	アクション
「カスタムフィールドを追加」	新しいタブを作成する、または既存のタブに追加します
「{tab}を非表示にする」	sling:hideResource="{Boolean}true" を使用します
「{field}を非表示にする」	sling:hideResource="{Boolean}true" を使用します
「{field}をオーバーライドする」	sling:hideProperties と新しい値を使用します

コアコンポーネントを拡張する場合：

• モデル委譲には @Self @Via(type = ResourceSuperType.class) を使用します
• ComponentExporter インターフェースを実装します
• @Model アノテーションに resourceType を追加します
• 継承したタブ／フィールドには、ダイアログで sling:hideResource を使用します

注： 親コンポーネントがプロジェクトコンポーネント（コアコンポーネントではない）の場合は、委譲パターンではなく、Java クラスを直接拡張します（extends ParentModel）。@Self @Via(type = ResourceSuperType.class) パターンはコアコンポーネント専用です。判断表については、references/extending-core-components.md を読み込みます。

ステップ 2：要件を収集する

2.1 ダイアログ仕様を解析する

作成前に、理解した内容をそのまま正確に返します：

Dialog Specification Confirmed:
I will create exactly {N} fields:
| # | Field Label | Field Type | Property Name |
|---|-------------|------------|---------------|
| 1 | {label1}    | {type1}    | {name1}       |
No additional fields will be added.
Is this correct?

2.2 モックアップ画像の扱い

• モックアップと仕様の両方が提供された場合： ダイアログ仕様を優先します。モックアップは HTML/CSS にのみ使用します。
• モックアップのみが提供された場合： フィールドを提案し、確認を求めます。

2.3 Figma デザイン入力

読み込み： references/figma-design-rules.md

ユーザーが Figma URL（figma.com/design/...、figma.com/make/...、または figma.com/board/...）を指定した場合：

1. URL を解析して fileKey と nodeId を抽出します（references/figma-design-rules.md Rule 1 を参照）。

• node-id クエリパラメーター内の - を : に変換します。
• ブランチ URL では branchKey を fileKey として使用します。

1. plugin-figma-figma MCP サーバー経由で get_design_context を呼び出します（Rule 2 を参照）：{ "server": "plugin-figma-figma", "toolName": "get_design_context", "arguments": { "nodeId": "<extracted-node-id>", "fileKey": "<extracted-file-key>", "clientLanguages": "html,css,javascript", "clientFrameworks": "htl" } }
2. 応答からデザイントークン（色、フォント、サイズ、スペーシング、レイアウト）を抽出します（Rules 3-4 を参照）。
3. HTL 構造、CSS スタイル、JS の動作には Figma の出力を使用します。ダイアログのフィールドには使用しません。

ダイアログ仕様と Figma URL の両方が指定されている場合の優先順位：

• ダイアログ仕様 → ダイアログのフィールドを決定します（絶対的に優先し、推測で補完しません）。
• Figma デザイン → HTML 構造、CSS スタイル、JS の動作のみを決定します。

Figma URL のみが指定されている場合（ダイアログ仕様なし）：

• デザインを分析し、ダイアログのフィールドをユーザーに提案します。
• 続行する前に、確認を求めます。

Figma の応答の取り扱い：

• 応答は React+Tailwind です。製品コードではなく、参考資料として扱います。
• JSX を BEM クラスを使用したセマンティックな HTL に変換します（Rule 5 を参照）。
• すべての CSS 値をコンポーネントの clientlib に抽出します（Rule 6 を参照）。
• インタラクティブ性が示唆されている場合のみ JS を作成します（Rule 7 を参照）。
• Figma の一時的な画像 URL をハードコードしないでください。有効期限が切れると、本番環境で動作しなくなります（Rule 8 を参照）。

2.4 動的コンテンツの要件

ユーザーの指定	Servlet が必要か？
外部 API との連携	はい（GET）
動的データの読み込み	はい（GET）
フォーム送信	はい（POST）
検索／フィルター	はい（GET）
静的なダイアログコンテンツ	いいえ

ステップ 3：コンポーネントファイルの作成

以下の順序ですべてのファイルを作成します。

3.1 コンポーネント定義

パス： ui.apps/src/main/content/jcr_root/apps/[project]/components/{component-name}/.content.xml

読み込み：references/aem-conventions.md

3.2 コンポーネントダイアログ

パス： ui.apps/.../components/{component-name}/_cq_dialog/.content.xml

読み込み： references/dialog-patterns.md

拡張コンポーネントの場合： references/extending-core-components.md を読み込みます。ダイアログの継承はマージャーを介してのみ機能するため、ここでは Sling Resource Merger が必須です。使用しないと、親ダイアログのノードが解決されません。

3.2.1 画像フィールドの取り扱い

ユーザーが画像または写真のフィールドを指定した場合：

• デフォルトの方法： data-sly-resource を使用して Core Image コンポーネントを埋め込みます。手動の <img> レンダリングを行う fileupload ダイアログフィールドは作成しないでください。
• fileupload を使用するのは画像以外のファイル（PDF、ドキュメントなど）の場合のみです。ユーザーが画像以外のファイルのアップロードを明示的に要求した場合に限り、cq/gui/components/authoring/dialog/fileupload を使用してください。
• 正しい埋め込みパターンについて、references/htl-patterns.md（画像の取り扱いのセクション）を読み込みます。

3.3 HTL テンプレート

パス： ui.apps/.../components/{component-name}/{component-name}.html

読み込み： references/htl-patterns.mdFigma URL が指定されている場合は、さらに読み込み： references/figma-design-rules.md（Rules 5, 8）。JSX 構造を BEM クラスを使用したセマンティックな HTL に変換します。静的テキストを Sling Model の式に置き換えます。要素の階層構造は、視覚的な基準として Figma のスクリーンショットを使用します。

i18n の確認： コンポーネントに静的な表示テキスト（ラベル、ボタンテキスト、プレースホルダー文字列）がある場合は、HTL i18n 式を使用します：${'Label Text' @ i18n}。静的テキストの翻訳を Sling Model で処理しないでください。翻訳が自動的に行われる HTL 内に記述します。

3.4 Sling Model

パス： core/src/main/java/[package-path]/models/{ComponentName}Model.java

読み込み： references/model-patterns.md、references/java-standards.md

拡張の場合： references/extending-core-components.md を読み込みます。

委譲パターン（Core Component の拡張用）：

@Model(adaptables = SlingHttpServletRequest.class,
       adapters = {CustomModel.class, ComponentExporter.class},
       resourceType = CustomModel.RESOURCE_TYPE)
@Exporter(name = ExporterConstants.SLING_MODEL_EXPORTER_NAME,
          extensions = ExporterConstants.SLING_MODEL_EXTENSION)
public class CustomModel implements ComponentExporter {
    @Self @Via(type = ResourceSuperType.class)
    private com.adobe.cq.wcm.core.components.models.List coreList;
    // Use FQN for core interfaces to avoid import collision
}

3.5 子アイテムモデル — Multifield の場合

パス： core/src/main/java/[package-path]/models/{ItemName}.java

3.6 単体テスト

パス： core/src/test/java/[package-path]/models/{ComponentName}ModelTest.java

読み込み： references/test-patterns.md

3.7 コンポーネント Clientlib — すべてのコンポーネントで作成

パス： ui.apps/.../clientlibs/clientlib-{component-name}/

読み込み： references/clientlib-patterns.mdFigma URL が指定されている場合は、さらに読み込みます： references/figma-design-rules.md（ルール 6、7）— Figma のレスポンスから正確な色、フォント、サイズ、間隔、border-radius を抽出します。BEM 命名規則を使用して、すべての CSS を css/{component-name}.css に記述します。デザインからインタラクティブ性が必要と判断される場合に限り、js/{component-name}.js を作成します。Figma のスクリーンショットと照らし合わせ、ピクセル単位で正確に再現されていることを確認します。

3.8 Dialog Clientlib — 条件付きロジックがある場合

パス： ui.apps/.../clientlibs/clientlib-{component-name}-dialog/

読み込み： references/clientlib-patterns.md（Dialog JavaScript Pattern セクション）

3.9 Sling Servlet — 動的コンテンツがある場合

パス： core/src/main/java/[package-path]/servlets/{ComponentName}Servlet.java

読み込み： references/sling-servlet-standards.md

3.10 Servlet 単体テスト

パス： core/src/test/java/[package-path]/servlets/{ComponentName}ServletTest.java

3.11 依存関係の検証 — Servlet では必須

完了する前に、core/pom.xml** の依存関係を検証します：**

• バージョンをハードコードしないでください。ハードコードしたバージョンは同期がずれ、ビルドの競合を引き起こすため、代わりに親の pom.xml でバージョンプロパティを確認してください。
• 最も一般的な API は aem-sdk-api（GSON、Jackson、Commons）に含まれています。
• AEM ランタイムライブラリには provided スコープを使用してください。

ステップ 4：完了サマリー

Component '{component-name}' created successfully!

## Files Created
- ui.apps/.../components/{component-name}/.content.xml
- ui.apps/.../components/{component-name}/_cq_dialog/.content.xml
- ui.apps/.../components/{component-name}/{component-name}.html
- core/.../models/{ComponentName}Model.java
- core/.../models/{ComponentName}ModelTest.java
- ui.apps/.../clientlibs/clientlib-{component-name}/
[+ servlet files if applicable]

## Dialog Fields (Exact Match)
{table matching specification}

Would you like me to add any additional fields or build the project?

クイックリファレンス：フィールドタイプのマッピング

ユーザーの指定	Granite Resource Type
Textfield	granite/ui/components/coral/foundation/form/textfield
Textarea	granite/ui/components/coral/foundation/form/textarea
Richtext、RTE	cq/gui/components/authoring/dialog/richtext
Pathfield、Path	granite/ui/components/coral/foundation/form/pathfield
Image、Photo	Core Image コンポーネントを埋め込みます（references/htl-patterns.md の Image Handling セクションを参照）。画像の表示に fileupload を使用しないでください。
Fileupload、File Upload	cq/gui/components/authoring/dialog/fileupload（PDF やドキュメントなど、画像以外のファイル用）
Multifield	granite/ui/components/coral/foundation/form/multifield
Checkbox	granite/ui/components/coral/foundation/form/checkbox
Select、Dropdown	granite/ui/components/coral/foundation/form/select
Numberfield	granite/ui/components/coral/foundation/form/numberfield
Datepicker	granite/ui/components/coral/foundation/form/datepicker

完全なマッピングについては、assets/field-type-mappings.md を参照してください。

参照ファイル

作成する内容に応じて、必要なときに読み込みます。

作成対象	読み込む参照資料
任意のコンポーネント	.aem-skills-config.yaml（プロジェクトのルートにあります。Configuration Gate Checkを参照して、最初に読み込んでください）、続いてreferences/aem-conventions.md
Dialog XML	references/dialog-patterns.md
HTL Template	references/htl-patterns.md
Sling Model	references/model-patterns.md、references/java-standards.md
Unit Tests	references/test-patterns.md
Clientlibs	references/clientlib-patterns.md
Core Componentの拡張	references/extending-core-components.md
Core Componentの拡張 — 実例とチェックリスト	Core Componentの拡張、ユニットテストのパターン、または実装チェックリストについて、完全な実例が必要な場合はreferences/extending-core-components-example.mdを読み込んでください
Sling Servlet	references/sling-servlet-standards.md
Core Componentのパターン	references/core-components.md
ハルシネーション禁止ルール	references/no-hallucination-rules.md
Figmaデザインの統合	references/figma-design-rules.md
トラブルシューティング	references/troubleshooting.md
例	references/examples.md

コンポーネントの作成中または作成後に問題が発生した場合は、よくある問題と解決策についてreferences/troubleshooting.mdを参照してください。