experience-ui-bundle-frontend-generate

UI Bundle UI

バンドルディレクトリを解決する

以下のルールを適用したり、ファイルを書き込んだりする前に、必ず node scripts/resolve-ui-bundle.mjs [project-root] を実行してください。場当たり的な find／ls は代わりになりません。以下の終了コードゲートを適用できないためです。Windows と macOS／Linux の両方で動作するよう、必ず node 経由で実行してください（実行ファイルを直接呼び出さないでください）。このスクリプトは sfdx-project.json の packageDirectories[0].path を読み取り（force-app とは限りません。ソースパスは設定可能です）、<sourceDir>/main/default/uiBundles/ を検索します。

• 終了コード 0、バンドルパスが標準出力に表示される：バンドルディレクトリが1つだけ見つかりました。それがバンドルディレクトリです。表示されたディレクトリ名をそのまま使用してください。実際に表示された名前を、別の名前（例：プロンプトテンプレートにある一般的な「AcmePortal」の例）に置き換えてはいけません。
• 終了コード 2、候補が標準エラー出力に表示される：複数の uiBundles/* サブディレクトリがあります。推測してはいけません。また、表示されたリストにない名前のバンドルにも書き込んではいけません。編集やコマンドの実行に進む前に、どのアプリ／バンドルを指しているのかユーザーに確認してください。
• 終了コード 1：sfdx-project.json が存在しないか無効である、またはバンドルディレクトリが見つかりません。

すべての npm／lint／build／dev コマンドは、プロジェクトルートではなく、解決したバンドルディレクトリ内から実行してください。

前提条件

以下のルールを適用する前に、これが既存のスキャフォールド済み UI バンドルであることを確認してください。resolve-ui-bundle.mjs が表示したディレクトリを指定して、必ず node scripts/check-preconditions.mjs <bundle-dir> を実行してください。

• バンドルが1つ（終了コード 0）の場合：そのバンドルに対して1回実行してください。
• 複数バンドル（終了コード 2）の場合：まだ実行してはいけません。まず、上記の「バンドルディレクトリを解決する」の手順に従って、どのアプリ／バンドルを指しているのかユーザーに確認してください。ユーザーがバンドルを指定したら、そのバンドルだけに対して check-preconditions.mjs を実行してください。ユーザーが選ぶ前に、推測で複数の候補に対して実行してはいけません。これは、ユーザーが依頼していないバンドルに触れたり、調べたりすることになります。
• 終了コード 0：バンドルに src/appLayout.tsx、src/routes.tsx、src/components/ui/ があります。続行してください。
• 終了コード 1、不足している項目が表示される：これは新規の SFDX プロジェクト、UI バンドルではない React プロジェクト、またはスキャフォールドが不完全なバンドルです。停止してください。一般的な React の知識（例：react-router-dom、ハードコードされたベース名、生の HTML）に頼ったり、不足しているスキャフォールドを「補う」ために appLayout.tsx／routes.tsx／ページ／コンポーネントを手書きしたりしてはいけません。たとえ依頼が気軽で曖昧な場合や、急ぎを示す表現（「ヘッダーだけ変更して」「背景を青くして」など）であっても同様です。バンドルがまだスキャフォールドされていないことをユーザーに伝え、まず experience-ui-bundle-app-coordinate（または experience-ui-bundle-metadata-generate）を使ってスキャフォールドするよう案内してください。ユーザーが対象のバンドルを指定した後、そのバンドルがスキャフォールドされていないと判明した場合は、そこで停止して案内してください。代わりに別の候補のスキャフォールドへ黙って切り替えてはいけません。

実際の <sourceDir>/main/default/uiBundles/ のディスク上の一覧にないバンドル名を、作り出したり、あるものと仮定したり、代わりに使ったりしてはいけません。これには、プロンプト、ディレクティブ、以前の会話など、ほかの場所に例やテンプレートの文言としてのみ登場する名前も含まれます。ディスク上の内容がその例と一致しない場合は、ディスク上の内容を優先してください。

タスクを特定する

依頼がどのカテゴリに該当するか判断してください。

カテゴリ	例	実装ガイド
ページ	新しいルート付きページ（連絡先、ダッシュボード、設定）	references/page.md
ヘッダー／フッター	サイト全体のナビゲーションバー、フッター、ブランディング、アプリ名の変更	references/header-footer.md
コンポーネント	ウィジェット、カード、テーブル、フォーム、ダイアログ	references/component.md

アプリ名の変更／リブランディングの依頼（例：「ユーザーに見えるところはすべて X という名前にする」）は、「ヘッダー」に言及していなくても、ヘッダー／フッターのタスクです。最低でも次の2つのファイルに必ず変更が加わります。src/appLayout.tsx（ヘッダー／ナビゲーションのブランドテキスト）と、index.html の <title>（ブラウザータブのタイトル）です。これらは一体の変更として扱ってください。どちらか一方しか更新しない名前変更は不完全です。

---

事前構築済み機能（手作業で構築する前に確認）

一部の機能は、事前構築済みのテスト済み機能パッケージとして提供されています。カタログは更新されるため、記憶だけでは把握できません。リクエストの文言だけから、ある機能が機能パッケージに「含まれる」かどうかを決めてはいけません。このスキルで、単純なページ、コンポーネント、スタイル変更を超える機能を手作業で構築する前に、次の手順を実行してください。

1. 信頼できる最新のカタログを確認します。 experience-ui-bundle-features-generate を呼び出して list を実行し、現在インストール可能な機能を表示します。ハードコードされたリストや記憶に頼ってはいけません。このスキルで機能名を一切挙げていないのは、記載した名前がいずれ古くなるためです。
2. バンドルに一致する機能がすでにインストールされているかを確認します。package.json の依存関係と既存の src/ ファイルを調べてください。存在する場合は、再インストールや再実装をしてはいけません。ただし、必ずその機能を採用してください。experience-ui-bundle-features-generate を呼び出して describe を実行します（機能の README を読み込みます。これは採用時の要件です）。アプリに組み込み、機能に設定ファイル（例：config.json）が含まれる場合は、このアプリのデータと用途に合わせて設定してください。インストールしただけで未設定の状態では完了ではありません。
3. カタログに一致する機能があり、まだインストールされていない場合は、experience-ui-bundle-features-generate でテスト済みパッケージをインストールしてください。ここで一から構築してはいけません。
4. 一致するカタログ機能がない場合に限り、手作業で構築してください。

このスキルを experience-ui-bundle-app-coordinate のフェーズとして実行する場合、一致する機能がすでに含まれていることがよくあります。前のフェーズでインストールされたか、テンプレートに含まれているためです。すでに含まれていることを理由に手順を省略してはいけません。手順 2 では、引き続きその機能を採用し、このアプリ向けに設定する必要があります。省略してよいのはインストールや再実装だけで、組み込みや設定は省略できません。

---

レイアウトとナビゲーション

appLayout.tsx は、ナビゲーションとレイアウトの信頼できる情報源です。すべてのページがこのシェルを共有します。

ナビゲーション、ヘッダー、フッター、サイドバー、テーマ、レイアウトに影響する変更を行う場合は、次の手順に従ってください。

1. routes.tsx で使用されるレイアウトである src/appLayout.tsx を編集します。
2. デフォルトやテンプレートのナビゲーション項目とラベルをすべて、アプリ固有のリンクと名前に置き換えます。
3. ヘッダー、ナビゲーションのブランド表示、フッター、index.html の <title> にあるプレースホルダーのアプリ名をすべて置き換えます。

index.html はバンドルのルートにあり（src/ の下ではありません）、ブランディングやアプリ名を変更する場合は、このスキルの対象に含まれます。残った <title>React App</title> や Vite + React の定型コードは、npm run lint や npm run build では検出されない、よくあるリリース阻止要因です。

完了する前に、appLayout.tsx のナビゲーション項目とブランディングを実際のものに更新したか確認してください。その後、node scripts/verify-rules.mjs を実行して定型コードが残っていないか確認します（「検証」を参照）。

対象	場所
レイアウト、ナビゲーション、ブランディング	src/appLayout.tsx
ドキュメントのタイトル	index.html（バンドルのルートにあり、src/ の外ですが、ブランディングの対象です）
ルートページのコンテンツ	routes.tsx のルートにあるコンポーネント

---

React と TypeScript の規約

ルーティング

ルーターパッケージは 1 つだけ使用してください。createBrowserRouter / RouterProvider を使う場合、すべてのインポート元は react-router にしてください（react-router-dom ではありません）。

アプリがクライアント側ルーター（React Router、Remix Router、Vue Router など）を使用する場合は、実行時にドキュメントの <base href> タグから常に basename / basepath / base を取得してください。basename をハードコードしてはいけません。

const basename = document.querySelector('base')
  ? new URL(document.querySelector('base').href).pathname.replace(/\/$/, '')
  : '/';
const router = createBrowserRouter(routes, { basename });

コンポーネントライブラリとスタイル設定

• コンポーネントには shadcn/ui を使用します：import { Button } from '@/components/ui/button';
• Tailwind CSS のユーティリティクラス

URL とパスの処理

アプリは動的なベースパスの背後で実行されます。ルーターのナビゲーション（<Link to>、navigate()）では絶対パス（/x）を使用します。ルーター以外の属性（<img src>）ではドット相対パス（./x）を使用します。静的アセットには Vite の import を優先してください。

TypeScript

• any は使用しないでください。適切な型、ジェネリクス、または型ガードと組み合わせた unknown を使用してください
• イベントハンドラー：(event: React.FormEvent<HTMLFormElement>): void
• 状態：useState<User | null>(null) — 必ず型パラメーターを指定してください
• 安全でない型アサーション（obj as User）は使用しないでください。代わりに型ガードを使用してください

モジュールの制限

React UI バンドルから lightning/* や @wire などの Salesforce プラットフォームモジュールをインポートしてはいけません（LWC 専用）。**データアクセスのコード（GraphQL、REST、SDK の初期化、またはデータを取得するフック）を書く前に、必ず最初に experience-ui-bundle-salesforce-data-access スキルを呼び出してください。**このスキル内で fetch／axios の呼び出しを書いたり、別のデータ API を独自に作成したりしないでください。確認質問への回答でデータ取得がさらっと示されているだけの場合も同様です。

---

デザインの考え方

このセクションと以下の「フロントエンドの美学」のルールはクリエイティブな指針であり、厳格な制約ではありません。リンターやビルドで確認できず、レビューで評価されます。ただし、厳格かつ確認可能な例外が 2 つあります。Inter／Roboto／Arial／Space Grotesk／システムフォントをデフォルトで使用しないこと、そしてモバイル対応（Tailwind のブレークポイント、44px のタッチターゲット）はスタイル上の好みではなく必須です。

コーディングを始める前に、大胆な美的方向性を定めてください。

• **目的：**このインターフェースはどのような問題を解決しますか？誰が使いますか？
• **トーン：**明確な方向性を選んでください。極限までミニマル、マキシマリスト、レトロフューチャー、オーガニック、ラグジュアリー、遊び心のあるもの、エディトリアル、ブルータリスト、アールデコ、柔らかい／パステル調、インダストリアルなど。これらをヒントにしつつ、文脈に合った独自のデザインにしてください。
• **差別化：**何がこのデザインを忘れがたいものにしますか？見る人が覚えている、ただ一つの要素は何ですか？

明確なコンセプトの方向性を選び、精密に形にしてください。大胆なマキシマリズムも洗練されたミニマリズムも効果的です。重要なのは強度ではなく、意図を持たせることです。

---

フロントエンドの美学

• **タイポグラフィ：**個性的で表情豊かなフォントを選んでください。ディスプレイフォントと洗練された本文フォントを組み合わせてください。Inter、Roboto、Arial、Space Grotesk、システムフォントをデフォルトで使用しないでください。

• **色：**CSS 変数を使って統一感のあるパレットを採用してください。控えめで均等に配色されたパレットより、存在感のある色に鮮やかなアクセントを加えるほうが効果的です。白地にありがちな紫のグラデーションは避けてください。

• **モーション：**効果の高い場面に集中してください。animation-delay を使った段階的な表示を伴う、よく演出されたページ読み込みは、散発的な細かなインタラクションよりも大きな喜びを生みます。スクロールをトリガーとする演出や、意外性のあるホバー状態を使ってください。CSS のみの実装を優先し、利用可能な場合は React の Motion ライブラリを使用してください。

• **空間構成：**非対称、重なり、斜めの流れ、グリッドを崩す要素など、意外性のあるレイアウトにしてください。広々とした余白、または意図的に調整された密度を活用してください。

• **背景と奥行き：**単色をデフォルトにせず、雰囲気を作り出してください。グラデーションメッシュ、ノイズテクスチャ、幾何学模様、重ねた半透明レイヤー、ドラマチックなシャドウ、装飾的なボーダー、グレインオーバーレイなどを活用してください。

• **モバイル対応：**生成する UI はすべてモバイルに対応している必要があります。Tailwind のレスポンシブプレフィックス（sm:、md:、lg:）を使用して、ブレークポイントに合わせてレイアウトを調整してください。小さな画面ではカラムを縦に並べ、柔軟なグリッドを使い、タッチターゲットは少なくとも 44px を確保してください。ナビゲーション、タイポグラフィ、余白がモバイルのビューポートで適切に機能することをテストしてください。

実装の複雑さは美的ビジョンに合わせてください。マキシマリストなデザインには凝ったアニメーションやエフェクトが必要です。ミニマリストなデザインには抑制、精密さ、慎重に調整された余白とタイポグラフィが必要です。生成するデザインがどれも同じ見た目にならないよう、テーマ、フォント、美学を変化させてください。

---

確認質問

一度に質問するのは 1 つだけにし、十分な情報が得られたら終了してください。

ページの場合

1. 名前と目的は何ですか？
2. URL パスは何ですか？
3. ナビゲーションに表示しますか？
4. アクセス制御はどうしますか？（公開、PrivateRoute 経由で認証、または AuthenticationRoute 経由で未認証）
5. コンテンツのセクションは何ですか？（リスト、フォーム、テーブル、詳細ビュー）
6. データ取得は必要ですか？

ヘッダー / フッターの場合

1. ヘッダー、フッター、またはその両方ですか？
2. 内容は？（ロゴ、ナビゲーションリンク、ユーザーアバター、著作権表示、ソーシャルアイコン）
3. スティッキーヘッダーにしますか？
4. カラースキームやスタイルの方向性は？

コンポーネントの場合

1. 何をするべきですか？
2. どのページに属しますか？
3. 共有/再利用可能ですか、それとも特定の機能専用ですか？
4. 必要なデータや props は？
5. 内部状態は？（ローディング、トグル、フォームの状態）
6. 使用する特定の shadcn コンポーネントは？

---

検証

完了する前に、解決された UI バンドルのディレクトリ（上記の「バンドルディレクトリの解決」を参照）から、以下のすべてを実行してください。

1. npm run lint — エラーが 0 件になる必要があります。
2. npm run build — 成功する必要があります。
3. npm run dev（またはプロジェクトの開発サーバースクリプト） — アプリがクリーンに起動することを確認し、ビルド時だけでなく実行時にも変更が検証されるようにします。

このスキルで最もリスクの高いルールは lint/build だけでは検出できません — 誤った react-router-dom のインポート、ハードコードされた basename、インラインの style={{}}、または紛れ込んだ lightning/* のインポートは、すべて lint と build をクリーンに通過しながら実行時に壊れる可能性があります。ルーティング、レイアウト、スタイリング、またはモジュールのインポートに触れる変更を行った後は、node scripts/verify-rules.mjs <files-or-dirs-you-edited> を実行してください。

• 終了コード 0: 違反は見つかりませんでした。
• 終了コード 1、ルールとファイルごとに違反が一覧表示される: lint と build が通過したとしても、タスク完了と見なす前にすべて修正してください。