experience-lwc-design-generate

デザインから LWC コンポーネントを作成する

デザイン入力（Figma、PRD、Aura のソース、またはユーザーの説明）から、新しい Lightning Web Component をエンドツーエンドで作成します。これは最上位のワークフロースキルであり、各段階を担当する専門的な兄弟スキルを順に実行します。組織に対応したデータ（LDS スキーマのイントロスペクション、デザインフレームの検査）は、experience-lds-data-requirements-generate への引き継ぎ、またはユーザーが提供するデザインツールの URL を通じて解決します。

使用する場面

• Figma フレーム、PRD、または文書化された仕様から、新しい LWC を構築する場合。
• Aura コンポーネントを新規構築として LWC に移行する場合（既存の Aura コンポーネントをその場で LWC に移植する作業は、このスキルの対象外です）。
• 要件がまだ一部暗黙的で、コーディングの前に PRD として整理する必要があるコンポーネントを作成する場合。

次の用途にはこのスキルを使用しないでください。

• 既存の LWC のリファクタリング（experience-lwc-generate を使用してください）。
• Aura → LWC のその場での移行（このスキルの対象外です）。
• スタイリングのみ、またはデータレイヤーのみの作業（専門スキルを直接使用してください）。

前提条件

• 少なくとも 1 つのデザイン入力があること：Figma URL、PRD の Markdown、Aura コンポーネントのソース、またはテキスト仕様。
• 新しい LWC の対象パス（モジュールフォルダー）。
• データを使用するコンポーネントの場合、experience-lds-data-requirements-generate と experience-lds-best-practices-apply がスキーマとアダプターの形式を解決できるよう、組織へのアクセス権があること。

ナレッジベース

• references/prd-analysis-template.md — PRD のセクション構成（PRD を作成する際は、そのままコピーしてください）。
• references/figma-to-prd-blueprint.md — フレームを PRD セクションに変換するための Figma 固有のガイダンス（componentName/tagName、contentRequirements、dataRequirements、interactions、componentCommunication、states、accessibility/responsiveness/styling/localization/security）。入力が Figma デザインの場合は、Phase 1.2 の前にこれを読んでください。

ワークフロー（必須の 5 フェーズ）

フェーズ 1 — PRD と要件の収集

目標： 後続のすべてのフェーズで使用する、統合された PRD を作成します。

1. 元の要件を入手する — PRD、設計仕様、Figma URL、Aura のソース、またはユーザーのテキストを収集します。

2. Figma → PRD（該当する場合）：Figma フレームの詳細な分析と PRD セクションのガイドラインについては、references/figma-to-prd-blueprint.md に従います。ユーザーから入手する必要がある入力は、Figma URL、対象フレームのスクリーンショット、（Dev Mode が利用可能な場合は）ノードのメタデータエクスポートです。blueprint のセクションごとのガイダンスに従って、references/prd-analysis-template.md の PRD のひな形に翻訳します。

3. Aura → PRD（移行する場合）：維持する必要がある Aura コンポーネントの機能を列挙します。マークアップ、コントローラー／ヘルパーのアクション、イベント、属性、配線されたデータを含め、この一覧を明示的な要件として PRD に反映します。（Aura → LWC のインプレース移植は対象外です。このステップでは、新規構築に向けた動作の把握のみを行います。）

4. データ要件（コンポーネントがデータを読み取る／書き込む場合）：experience-lds-data-requirements-generate に引き継ぎます。このスキルは、検証済みのデータ仕様（オブジェクト／項目の API 名、推奨 LDS API、実装方法）を作成します。その出力をそのまま PRD に貼り付けます。

5. アダプターの調査：アダプターの選択ルール（UI API、GraphQL、Apex）と、選択した方法に推奨される配線については、experience-lds-best-practices-apply に引き継ぎます。

6. 命名：componentName は camelCase（例：productCard）、tagName はその kebab-case 形式（例：product-card）にする必要があります。バンドルされたスクリプトで両方を検証してください。チェックを目視で済ませないでください。

   "<skill_dir>/scripts/check-component-name.sh" <componentName> <tagName>
   

   いずれかの名前の形式が不正な場合、または componentName の kebab-case 形式が tagName と一致しない場合、スクリプトは実行可能な内容を示す stderr メッセージとともにゼロ以外の終了コードを返します。

成果物： 目的、コンテンツ、データ、インタラクション、状態、アクセシビリティ、レスポンシブ対応、スタイルの方針、ローカライズ、セキュリティを網羅した包括的な PRD。ワークスペースにチェックインしておきます（例：packages/skills/<skill>-workspace/<iteration>/PRD.md）。

フェーズ 2 — コンポーネントコードの生成

目標： PRD を厳密に反映した初期の .html、.js、.css、.js-meta.xml を作成します。

1. PRD の内容を仕様として experience-lwc-generate に引き継ぎます。このスキルが PRD からコードへの変換（イベント、ゲッター、@api、.js-meta.xml、AI メタデータ）を担い、作成時の信頼できる唯一の情報源となります。
2. design-systems-slds-apply の SLDS 判断の優先順位に従います。
   1. 適合する Lightning Base Component を優先します（experience-lwc-base-components-integrate）。
   2. それ以外の場合は、SLDS Blueprint またはユーティリティクラスを選択します（design-systems-slds-apply に従います）。
   3. それ以外の場合は、SLDS スタイリングフックを使用してカスタム CSS を記述します（これについても design-systems-slds-apply で説明しています）。
3. 次に進む前に、experience-lwc-generate のチェックリストを確認して、作成時の基準を再確認します。
4. PRD のすべてのデータ要件を、ワイヤーアダプター（UIAPI／GraphQL）または明示的な TODO のいずれかに対応付けます。
5. PRD を厳密に遵守します。
   • PRD に記述されている機能と動作のみを含めます。
   • 不確かな箇所には、曖昧さの原因となった PRD の文言を引用した // TODO: コメントを付けます。
   • 意図を説明する詳細なコードコメントを追加します。
   • PRD が示す以上にコンポーネントを複数のサブコンポーネントに分割しないでください。

成果物： 対象パスに作成した LWC バンドルの初回版。

フェーズ 3 — コンポーネントの最適化

目標： パフォーマンス、保守性、ベストプラクティスに関する修正を適用します。

1. 他のレビューを行う前に、以下の最適化チェックリストを確認します。
   • 単一責任、カプセル化、再利用性。
   • DOM 操作を最小限に抑え、プロパティを通じて更新をまとめます。
   • イベントハンドラーとライフサイクルフックの使用状況を監査します（renderedCallback のガード）。
   • 負荷の高い子コンポーネントには遅延読み込みを検討します。
2. LWC のベストプラクティスに関するレビュー（アンチパターン、リアクティビティ、コンポジション）を experience-lwc-generate に引き継ぎます。
3. リリース前レビューのため、コンプライアンススイートに引き継ぎます。experience-accessibility-validate（a11y）、experience-lwc-security-validate（LWS + Product Security）、experience-lwc-rtl-validate（RTL i18n）を実行します。品質確認をすべて行うため、これらをまとめて実行します。
4. コンポーネントがデータを扱う場合は、キャッシュ／整合性と参照整合性のチェックを experience-lds-best-practices-apply に引き継ぎます。
5. 採用した指摘事項をすべて適用します。PRD を信頼できる唯一の情報源とし、最適化を口実にスコープを追加しないでください。

フェーズ 4 — Lint、フォーマット、コンパイルチェック

条件：プロジェクトでツールが設定されている場合に限り、該当する手順を実行します。

1. プロジェクトのツールを検出する — プロジェクトのルートから同梱の検出スクリプトを実行し、<tool>=yes|no の各行を読み取ります。package.json／ドットファイルを文章上で目視確認してはいけません。

   "<skill_dir>/scripts/detect-project-tools.sh" <projectRoot>
   

   出力例：

   eslint=yes
   prettier=yes
   cursor-rules=no
   lwc-compiler=yes
   

   以下のサブステップは、yes と報告されたツールに対してのみ実行し、それ以外はスキップします。

2. ESLint（eslint=yes の場合）— 実行し、すべての違反を修正します。

3. Prettier（prettier=yes の場合）— 一貫したフォーマットにするために実行します。

4. Cursor ルール（cursor-rules=yes の場合）— プロジェクトに含まれるすべてのルールを適用します。

5. LWC コンパイラー（lwc-compiler=yes の場合）— ローカル開発サーバーまたは SFDX を使って実行し、先に進む前にすべての構文／テンプレートエラーを解消します。

成果物： 問題がなく、検証済みのコンポーネントコード。

フェーズ 5 — テストの作成

自動アクセシビリティ Jest カバレッジについては experience-lwc-accessibility-jest-run に引き継ぎます。同じ工程で、experience-lwc-generate のテストガイダンスに従って汎用 Jest カバレッジを追加し、チームが必要とする場合は UTAM ページオブジェクトも生成します。

成果物： プロジェクトのカバレッジしきい値以上を満たし、テストスイートが合格する LWC バンドル。

完了の定義

このワークフローで作成した新しいコンポーネントは、以下の項目がすべて満たされた場合にのみ「完了」です。これを正式な準備完了チェックリストとして扱い、レビュー担当者が各項目を確認できるよう、PR の説明にコピーしてください。

コードの完成度 — 実装漏れがないこと：

1. PRD の要件がすべて実装されているか、TODO: と追跡項目へのリンクを明記していること。見落としがあってはなりません。
2. 本番環境の処理経路に TODO、FIXME、console.log、console.table、alert() が残っていないこと。
3. コメントアウトされたコードブロック、空の関数本体、プレースホルダー値、ダミーデータ、参照されていないインポートがないこと。
4. lwc:dom="manual" 領域やサードパーティライブラリを使った回避策には、ネイティブな LWC パターンを使わなかった理由を説明するコメントがあること。

コンプライアンスと品質：

5. .js-meta.xml の AI メタデータが experience-lwc-generate の監査に合格していること（コンポーネント全体の <ai><description> が設定され、<targetConfig> を通じて公開されるすべての @api メンバーに <ai><property name="…" aiDescription="…"/></ai> エントリーがあること。マーケティング表現は含めないこと）。
6. SLDS のスタイル設定が design-systems-slds-apply の検証に合格していること — 生の hex 値や px 値を使わず、スタイリングフックと SLDS ユーティリティクラスのみを使用すること。
7. アクセシビリティチェックが完了していること：ソースレビューの experience-accessibility-validate と、自動テストの experience-lwc-accessibility-jest-run の両方が合格していること。
8. セキュリティと RTL のチェックが完了していること：experience-lwc-security-validate と experience-lwc-rtl-validate の両方が合格していること。

データとテスト：

9. データレイヤーが、参照されている LDS アダプターに照らして検証済みであること（すべての wire 呼び出し／命令型呼び出しが PRD のデータセクションに記載され、experience-lds-best-practices-apply または experience-lds-data-requirements-generate のアダプターのいずれかと一致していること）。
10. プロジェクトで求められるカバレッジレベルで Jest テストがすべて合格していること。新しいテストで、すべての @api インターフェース、すべてのディスパッチイベント、すべてのエラーパス（wire の失敗、apex の失敗、検証による拒否）を網羅すること。
11. コンポーネント間のブラウザーレベルテストが必要な UI フローには UTAM ページオブジェクトを作成していること（不要な場合は省略）。

相互参照

• このワークフローが連携するスキル（フェーズ順）：
  • experience-lds-data-requirements-generate — フェーズ 1.4 のデータ仕様（および experience-lds-best-practices-apply と並行して行うフェーズ 1.5 のアダプター調査）。
  • design-systems-slds-apply、experience-lwc-base-components-integrate — フェーズ 2 のスタイル決定。
  • experience-lwc-generate — フェーズ 2 の作成基準、フェーズ 3 のベストプラクティスレビュー、フェーズ 5 の AI メタデータ監査。
  • experience-lds-best-practices-apply — フェーズ 2／3 のデータレイヤーアダプターの選定と一貫性のレビュー。
  • experience-accessibility-validate、experience-lwc-security-validate、experience-lwc-rtl-validate — フェーズ 3 のアクセシビリティ／セキュリティ／RTL のレビュー。
  • experience-lwc-accessibility-jest-run — フェーズ 5 の自動アクセシビリティテスト生成。
  • 任意：コンポーネントが安定したら、別の工程として o11y インストルメンテーションを追加します。
  • experience-lwc-typescript-migrate — JS が合格した後に任意で実施します。
  • 新しいコンポーネントをフラグの背後でリリースする場合は、ロールアウト中にフィーチャーフラグで制御してください。
  • 公開 API が安定したら、API インターフェースのドキュメントを生成します（現時点では専用のスキルはありません）。
• このワークフローで使用する組織を考慮した入力：
  • Figma URL とスクリーンショット（利用可能な場合は、開発者の Dev Mode メタデータのエクスポートも） — フェーズ 1.2 の Figma 入力。
  • experience-lds-data-requirements-generate は、コンポーネントが組織のデータを必要とする場合にフェーズ 1 で使用する組織スキーマのイントロスペクションとデータ仕様の検証を担当します。この作業を重複して行わず、該当スキルに引き継いでください。

例

フェーズ 1 の PRD 骨子（Figma／PRD／Aura の入力から記入）

Component: productCard (<product-card>)
Purpose: Render a compact summary of a product with quick actions.

Content requirements
- Hero image (Product.HeroImage__c)
- Title (Product.Name)
- Subtitle (Product.Tagline__c)
- Primary CTA button ("Add to cart")
- Secondary CTA icon button ("Favorite")

Data requirements
- Input: @api recordId (Product Id)
- Adapter: getRecord (UIAPI) with fields Name, Tagline__c, HeroImage__c
- Events out: addtocart{detail.recordId}, favorite{detail.recordId, detail.value}

States
- Loading (data not yet resolved)
- Error (adapter error)
- Empty (no record found)
- Default

Accessibility
- Title uses <h3>
- Icon-only button carries aria-label="Favorite"
- Card is a labelled region (role="group", aria-labelledby)

Responsiveness
- Full width < 480px
- Side-by-side image + text >= 480px

Styling
- Uses lightning-card wrapper
- Surface color: --slds-g-color-surface-container-1
- Shadow: --slds-g-shadow-1

フェーズ 2 の骨子

import { LightningElement, api, wire } from 'lwc';
import { getRecord } from 'lightning/uiRecordApi';
import NAME from '@salesforce/schema/Product__c.Name';
import TAGLINE from '@salesforce/schema/Product__c.Tagline__c';
import HERO from '@salesforce/schema/Product__c.HeroImage__c';

const FIELDS = [NAME, TAGLINE, HERO];

export default class ProductCard extends LightningElement {
    @api recordId;

    @wire(getRecord, { recordId: '$recordId', fields: FIELDS })
    record;

    get hasRecord() { return this.record?.data != null; }
    get isLoading() { return !this.record; }
    get hasError()  { return !!this.record?.error; }
    get name()      { return this.record?.data?.fields?.Name?.value ?? ''; }
    get tagline()   { return this.record?.data?.fields?.Tagline__c?.value ?? ''; }
    get heroUrl()   { return this.record?.data?.fields?.HeroImage__c?.value ?? ''; }

    handleAddToCart() {
        this.dispatchEvent(new CustomEvent('addtocart', { detail: { recordId: this.recordId }, bubbles: true, composed: true }));
    }
    handleFavorite(event) {
        this.dispatchEvent(new CustomEvent('favorite', { detail: { recordId: this.recordId, value: event.detail.value }, bubbles: true, composed: true }));
    }
}

検証

• PRD のすべてのセクションが、少なくとも 1 つのコードブロックまたは明示的な TODO に紐づいています。
• フェーズ 1～5 は順番どおりに実行されており、スキップされたステップはありません。
• アクセシビリティ、SLDS、データレイヤー、AI メタデータのレビューはすべて合格しています。
• カバレッジは、プロジェクトのしきい値を満たしているか、それを上回っています。
• コンポーネントは、PRD に列挙されたレスポンシブブレークポイント全体で experience-lwc-runtime-observe 上に正しくレンダリングされます。