acul-screen-generator

ACUL スクリーンジェネレーター

本番環境ですぐに使える、テーマを完全に適用した Auth0 ACUL スクリーンコンポーネントを生成します。厳格な 9 フェーズのワークフロー（フェーズ 0～8）に従います：CLI 認証 → インテント検出 → プロジェクト設定 → スクリーン要件 → 技術スタックとデザイン → テーマ抽出 → 構造化コード生成 → ビルド検証と反復修正 → 開発モードの接続。

リファレンスの優先順位

スクリーンに適したリファレンスは、常に次の優先順位に従って選択してください。CLI を実行する前に、そのスクリーンが auth0-acul-samples にあるか確認してください。存在しない場合、CLI は失敗します。

1. Check auth0-acul-samples availability first  (gate for CLI usage)
   → Read `references/screen-catalog.md` for the Samples column
   → Verify the screen directory exists at:
     React:    https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/<screen-name>
     React-JS: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/<screen-name>
   → If the screen IS in samples → proceed to CLI (step 2)
   → If the screen is NOT in samples → skip CLI entirely, go to step 3

2. Auth0 CLI scaffolded code  (only for screens confirmed in auth0-acul-samples)
   → Use `auth0 acul screen add` or `auth0 acul init` to generate screen code locally
   → The CLI produces the correct project structure, SDK imports, and hook patterns
   → If the CLI succeeds, use the scaffolded code as-is — do NOT fetch from GitHub

3. SDK examples  (for screens NOT in auth0-acul-samples — do NOT attempt CLI for these)
   → Code snippets showing SDK imports, hooks, and action functions
   → React: https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/<screen-name>.md
   → JS:    https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/<screen-name>.md
   → Determine if the example is React or JS, then adapt to match the project's framework

4. assets/react-templates/ or assets/js-templates/
   → Structural component pattern only — never use their hooks/actions for other screens

auth0-acul-samples にあるスクリーンを確認するには → references/screen-catalog.md を読みます。

---

auth0-acul-samples のアーキテクチャ

スクリーンが auth0-acul-samples にある場合は、モノリシックなコンポーネントではなく、このモジュール式のパターンでコードを生成します。

スクリーンごとのディレクトリ構造：

<screen-name>/
├── index.tsx                        thin entry: wires manager hook + applies theme + renders layout
├── components/
│   ├── Header.tsx                   logo, title, subtitle from screen.texts
│   ├── <ScreenName>Form.tsx         form fields, submit, captcha, passkey button
│   ├── Footer.tsx                   signup link, forgot password, back link
│   └── AlternativeLogins.tsx        social login buttons (if screen has social)
├── hooks/
│   └── use<ScreenName>Manager.ts    wraps SDK hooks, exposes clean handlers + feature flags
└── locales/
    └── en.json                      fallback text strings

index.tsx のパターン：

import { ULThemeCard, ULThemePageLayout } from '@/components'
import { applyAuth0Theme } from '@/utils/theme/themeEngine'
import Header from './components/Header'
import <ScreenName>Form from './components/<ScreenName>Form'
import Footer from './components/Footer'
import { use<ScreenName>Manager } from './hooks/use<ScreenName>Manager'

const <ScreenName>Screen = () => {
  const { sdkInstance, texts, locales } = use<ScreenName>Manager()
  applyAuth0Theme(sdkInstance)
  document.title = texts?.pageTitle ?? locales.pageTitle

  return (
    <ULThemePageLayout>
      <ULThemeCard>
        <Header texts={texts} />
        <AlternativeLogins alignment="top" />    {/* conditional */}
        <<ScreenName>Form />
        <Footer texts={texts} links={links} />
        <AlternativeLogins alignment="bottom" />  {/* conditional */}
      </ULThemeCard>
    </ULThemePageLayout>
  )
}

export default <ScreenName>Screen   // REQUIRED: screenLoader registers via lazy(), which needs a default export

index.tsx には export default が必要です。 プロジェクトのスクリーンレジストリ（src/utils/screen/screenLoader.ts）は、各スクリーンを lazy(() => import('@/screens/<screen-name>')) で読み込み、React.lazy はモジュールの default エクスポートを解決します。名前付きエクスポートのみ（export const <ScreenName>Screen）でもコンパイルは成功しますが、実行時には画面が空白になる、または「screen not implemented」と表示されます。フェーズ 6 の「スクリーン登録」を参照してください。

hooks/use<ScreenName>Manager.ts のパターン：

import { useLoginId, useScreen, useTransaction } from '@auth0/auth0-acul-react/<screen-name>'
import { executeSafely } from '@/utils/helpers/executeSafely'
import locales from '../locales/en.json'

export const use<ScreenName>Manager = () => {
  const sdkInstance = useLoginId()       // screen-specific SDK hook
  const screen = useScreen()
  const { alternateConnections } = useTransaction()

  const handleSubmit = async (data) => executeSafely(() => login(data))
  const handleFederatedLogin = async (conn) => executeSafely(() => federatedLogin({ connection: conn }))

  return {
    sdkInstance,
    texts: screen.texts,
    locales,
    alternateConnections,
    handleSubmit,
    handleFederatedLogin,
    isPasskeyEnabled: screen.isPasskeyEnabled,
    isCaptchaAvailable: screen.isCaptchaAvailable,
  }
}

スクリーンが auth0-acul-samples になく、CLI がそのスクリーンをサポートしていない場合は、SDK の例に基づく単一ファイルのコンポーネントに切り替えます。

前提条件

• Auth0 CLI がインストールされていること：brew install auth0
• Auth0 テナントでカスタムドメインが設定されていること（ACUL の必須要件）
• Node.js ≥ 22（Auth0 CLI が生成する ACUL プロジェクトで必要）

---

フェーズ 0：環境の検証と CLI 認証

ステップ 1 — Node.js のバージョンを確認する

node --version 2>&1

出力を解析し、メジャーバージョンが ≥ 22 であることを確認します。Node.js がインストールされていない場合、またはバージョンが 22 未満の場合：

• 未インストール： 作業を停止し、Node.js 22 以降をインストールするようお客様に案内します（例：nvm install 22、または nodejs.org からダウンロード）。
• バージョン < 22： 作業を停止し、アップグレードするようお客様に案内します。例：nvm install 22 && nvm use 22。Auth0 CLI が生成する ACUL プロジェクトでは Node.js 22 以降が必要であり、それ以前のバージョンではビルドまたは実行に失敗します。

Node.js ≥ 22 が確認できるまで、後続のフェーズに進まないでください。

ステップ 2 — CLI 認証とテナントの確認

auth0 login
auth0 acul config list --rendering-mode advanced

auth0 acul config list がカスタムドメインに関するエラーを返した場合は、作業を停止し、ACUL を利用するにはテナントでカスタムドメインを設定する必要があることをお客様に伝えます。

CLI フラグの全リファレンスについては → references/cli-commands.md を読みます。

---

フェーズ 1：インテント検出

必要なモードをお客様に確認します。

• A) ゼロから作成 — 新規プロジェクト、スクリーンの選択、セットアップ全体
• B) スクリーンを追加 — 既存プロジェクトに新しいスクリーンを 1 つ以上追加
• C) スクリーンを変更 — 既存プロジェクトのスクリーンのコードまたはスタイルを変更

この選択によって、フェーズ 2A／2B／2C のいずれに進むかが決まります。

---

フェーズ 2A：ゼロから作成 — プロジェクトの初期化

アプリ名、フレームワーク（react または js）、最初に作成するスクリーンのリストを確認します。

auth0 acul init <app_name> -t react -s login-id,login-password,signup
auth0 acul config generate <screen-name>    # repeat per screen

プロジェクトディレクトリに acul_config.json が作成されていることを確認します。

CLI が生成したコードを第一の情報源として使用してください。 生成されたスクリーンファイルを読み、プロジェクト構造、SDK のインポート、フックのパターン、コンポーネントのレイアウトを把握します。GitHub から取得しないでください。CLI の出力が正式な出発点です。お客様の要件（ブランディング、追加コンポーネントなど）に基づいて、生成されたコードをカスタマイズまたは拡張する場合に限って変更します。

フェーズ 3 に進みます。

---

フェーズ 2B：スクリーンの追加 — まずサンプルの有無を確認

1. プロジェクトディレクトリに acul_config.json があることを確認します。

   • 存在しない場合 → 停止します。先に auth0 acul init を実行するようお客様に案内します。

2. CLI を実行する前に、そのスクリーンが auth0-acul-samples にあるか確認します。 references/screen-catalog.md を読み、要求された画面について Samples (React) または Samples (React-JS) 列を確認します。次に、GitHub のディレクトリ一覧を取得して、画面が想定されるパスに実際に存在することを確認します。

   React:    https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/<screen-name>
   React-JS: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/<screen-name>
   

   この確認によって、CLI で画面をスキャフォールドできるかどうかが決まります。画面が auth0-acul-samples に存在しない場合、CLI の auth0 acul screen add コマンドは失敗するため、実行せずに Step 4 へ進みます。

3. 画面が auth0-acul-samples に存在する → CLI を試します：

   auth0 acul screen add <screen-name> -d <project-dir>
   

   • CLI が成功した場合 → スキャフォールドされたコードをそのまま使用します。 生成されたファイルを読み、構造、SDK のインポート、フックのパターンを把握します。GitHub から取得しないでください。顧客の要件（ブランディング、コンポーネントなど）に合わせて、CLI が生成したコードをカスタマイズします。Phase 3 に進みます。
   • 画面がサンプルに存在するにもかかわらず CLI でエラーが発生した場合（認証の問題やバージョンの不一致など）→ 復旧手段として Step 4 に進みます。

4. 画面が auth0-acul-samples に存在しない（または CLI が失敗した）→ CLI を使わず、参照コードを直接取得します。

   CLI はこの画面をサポートしていないため、auth0 acul screen add を実行しないでください。エラーになります。代わりに、参照コードをもとに画面を構築します。

   Step 4a — プロジェクト構造を把握します（未確認の場合）： 手動で追加する最初の画面である場合（つまり、以前に CLI で生成した画面をもとに、プロジェクトのディレクトリ構成、設定の接続方法、ビルド設定をまだ把握していない場合）は、ダミーページを作成します。

   auth0 acul screen add login-id -d <project-dir>
   

   • 生成されたダミー画面のファイルを読み、プロジェクト構造、ディレクトリ構成、設定の接続方法、ビルド設定を把握します。
   • その後、ダミー画面のファイルを削除します（login-id/ 画面ディレクトリを削除します）。

   以前に CLI で生成した画面、または手動で作成した画面をもとに、すでにプロジェクト構造を把握している場合は、この手順を省略します。

   Step 4b — 画面の参照コードを取得します： プロジェクトファイルを調べて、既存プロジェクトの技術スタック（React または JS/Vanilla）を特定します。その後、参照コードを取得します。

   • React プロジェクト → universal-login リポジトリの SDK の例を確認します：
     • 取得先：https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/<screen-name>.md
     • 次の内容を解析します：正確なインポートパス、フックのパターン（Pattern A または B）、アクション関数名、ペイロードの形式
   • JS/Vanilla プロジェクト → JS SDK の例を確認します：
     • 取得先：https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/<screen-name>.md
     • 次の内容を解析します：マネージャークラス名、メソッド名、ペイロードの形式

   例が React（JSX/TSX、フック）かプレーンな JS（クラスベースのマネージャー）かを確認し、プロジェクトのフレームワークに合わせます。プロジェクトが React でも JS の例しかない場合（またはその逆の場合）は、適切な SDK のリファレンス（references/acul-react-sdk.md または references/acul-js-sdk.md）を使って、パターンを適宜調整します。

   Step 4c — プロジェクト構造に沿って画面ファイルを生成し、Step 4b の SDK リファレンス情報を反映します。 これにより、正しいディレクトリ構成、設定との連携、ビルドの互換性が確保されます。React の場合は「auth0-acul-samples Architecture」セクションのモジュラーアーキテクチャのパターンに従います。例が十分にシンプルな場合は、単一ファイルのコンポーネントにします。

   Step 4d — ローカル開発モードで解決できるように画面を登録します（必須）。 CLI はスキャフォールドした画面を自動的に登録しますが、手動で生成した画面は登録されません。そのため、ファイルが存在し、ビルドが成功していても、auth0 acul dev（ローカルモード）では 「Screen '' is not implemented」 と表示されます。（接続モードではテナントから画面を読み込むため、この手順なしでも動作します。このため、この不具合はローカル開発でのみ発生します。）画面は src/utils/screen/screenLoader.ts の SCREEN_COMPONENTS マップを通じて解決されます。

   まず、プロジェクトがこのマップをどのように管理しているかを確認します。手動編集されていると決めつけないでください。

   1. screenLoader.ts が自動生成ファイルかどうかを確認します。ファイルを開き、// Auto-generated file のようなバナーがあるか調べます。また、package.json のスクリプトにジェネレーター（例：generate:screenLoader）や scripts/generate-screen-loader.js があるか確認します。
      • ジェネレーターがある場合（CLI でスキャフォールドされたプロジェクトでは一般的です）： ローダーは、許可リスト（例：src/constants/validScreens.js）と照合しながら src/screens/*/index.tsx をスキャンして再生成されます。screenLoader.ts を手動で編集しないでください。編集内容は上書きされます。 代わりに、次の手順を実行します。
        • <screen-name> が許可リスト（VALID_SCREENS）に含まれていることを確認します。含まれていない場合は、追加します。
        • ジェネレーターを実行します：npm run generate:screenLoader（実際のスクリプト名は package.json で確認してください）。
        • 新しいエントリーが screenLoader.ts に表示されることを確認します。
      • ジェネレーターがない場合： SCREEN_COMPONENTS マップを直接手動で編集します。

        "<screen-name>": lazy(() => import("@/screens/<screen-name>")),
        

   2. どちらの場合も、画面の index.tsx に デフォルトエクスポート（export default <ScreenName>Screen）があることを確認します。lazy() はデフォルトエクスポートを解決します。名前付きエクスポートのみの場合、コンパイルは成功しますが、画面は空白または「未実装」として読み込まれます。

   すべての画面名とその利用可否については、references/screen-catalog.md を参照してください。

---

フェーズ 2C：画面の変更 — 現在の状態を取得

1. acul_config.json が存在することを確認します。

2. 現在のレンダリング設定を取得します。

   auth0 acul config get <screen-name> -f <screen-name>.json
   auth0 acul config list --rendering-mode advanced
   

3. 顧客のコードベースから既存の画面ファイルを読み取ります。ローカルのコードを主な参照元としてください。 変更を加える前に、現在の構造、SDK のインポート、フックのパターンを把握します。

4. ローカルのコードに重要な SDK パターンが不足している場合（例：フックのパターンが誤っている、アクション関数が不足している）で、既存のコードベースから正しいパターンを特定できない場合に限り、GitHub の参照情報を取得します。参照の優先順位（サンプルの利用可否 → 対応している場合は CLI でスキャフォールドされたコード → SDK の例）に従って検証してください。

---

フェーズ 3：画面の要件

顧客から次の情報を収集します。

• 画面の種類 — 利用可能な画面の一覧については、references/screen-catalog.md を参照してください。
• 必要なコンポーネント：
  • ソーシャルプロバイダー：Google、GitHub、Apple、Microsoft、Facebook
  • フォームフィールド：メールアドレス、ユーザー名、電話番号、パスワード、パスワードの確認
  • MFA の種類（該当する場合）：OTP、SMS、プッシュ通知、WebAuthn
  • 任意の追加要素：CAPTCHA、パスキーのボタン、「ログイン状態を保持」チェックボックス、利用規約のチェックボックス
• 変更モードの場合： 具体的な変更内容（レイアウト、色、コンポーネントの追加・削除）

---

フェーズ 4：技術スタックの検出

次の項目を確認または検出します。

• フレームワーク： React（@auth0/auth0-acul-react）または JS（@auth0/auth0-acul-js）
• スタイリングライブラリ： Tailwind CSS／CSS Modules／styled-components／プレーン CSS
• 既存のテーマファイル： tailwind.config.ts、styles/tokens.css、theme/index.ts を確認します。

適切な SDK リファレンスを読み込みます。

• React → references/acul-react-sdk.md を参照
• JS → references/acul-js-sdk.md を参照

ソーシャルボタンの実装については、references/social-providers.md を参照してください。

---

フェーズ 5：テーマの抽出と適用範囲

デザイン入力 — 顧客が提供したものを特定します。

オプション A — 画像またはモックアップ（jpeg／png／スクリーンショット）： 画像を分析して、次の情報を抽出します。

• プライマリ、セカンダリ、アクセントの色（16 進数）
• 背景とカード／サーフェスの色
• フォントファミリーとウェイト
• 角丸のスタイル（角張った／わずかな丸み／丸み／ピル型）
• 余白のリズム（コンパクト／標準／ゆったり）
• レイアウトの種類：中央配置のカード／全面表示／分割パネル／フローティングカード

オプション B — ブランドカラーのみ（画像なし）： 提供された 16 進数の値から、トークン一式を導き出します。

primary        → button bg, links, focus ring
primary-hover  → primary darkened ~10%
primary-text   → white if primary is dark, else #111827
background     → page background
surface        → card/panel background
text-primary   → headings (#111827 light / #F1F5F9 dark)
text-secondary → labels, placeholders
border         → input borders
error          → #EF4444 (unless specified)
success        → #22C55E (unless specified)

テーマの適用範囲 — お客様に確認します：

• 単一画面： トークンをこのコンポーネントのスタイルにインラインで適用します
• すべての画面： まず共有テーマファイルを生成し、その後、すべての画面に一貫して適用します

スタイリングライブラリごとのテーマファイルのパターンについては、references/theming-patterns.md を参照してください。

スタイリングライブラリごとに生成するテーマファイル（すべての画面に適用する場合）：

スタイリングライブラリ	使用するテンプレート	出力ファイル
Tailwind	assets/theme-templates/tailwind.config.ts	tailwind.config.ts
CSS Modules	assets/theme-templates/tokens.css	styles/tokens.css
styled-components	assets/theme-templates/theme-provider.ts	theme/index.ts
Plain CSS	assets/theme-templates/globals.css	styles/globals.css

すべての {{TOKEN}} プレースホルダーを、抽出したトークン値に置き換えます。

---

フェーズ 6：構造化コードの生成

生成方法は、画面コードのソースによって異なります。

パス A — CLI でスキャフォールドした画面（推奨）

CLI が画面の生成に成功した場合（auth0 acul init または auth0 acul screen add を使用）、CLI の出力をベースとして使用します。生成されたファイルを読み込み、お客様の要件に基づいてカスタマイズします。

• フェーズ 5 のデザイントークンを、生成されたコンポーネントのスタイリングに適用します
• 指定に従ってコンポーネントを追加または削除します（ソーシャルボタン、captcha、パスキーなど）
• お客様のデザイン入力に従ってレイアウトと構造を調整します
• CLI の SDK インポート、フックパターン、アクション関数は正しいため、そのまま保持します

GitHub のリファレンスから再生成するために、CLI が生成したコードを破棄しないでください。

パス B — auth0-acul-samples の画面（CLI がその画面をサポートしていない場合のみ）

CLI のダミーページ戦略（フェーズ 2B、ステップ 4a）で取得したプロジェクト構造を基盤として使用します。ダミーページのディレクトリ構成と設定の配線に合わせて、samples のパターン（上記「auth0-acul-samples のアーキテクチャ」を参照）を使用して画面ディレクトリを生成します。

<screen-name>/
├── index.tsx
├── components/
│   ├── Header.tsx
│   ├── <ScreenName>Form.tsx
│   ├── Footer.tsx
│   └── AlternativeLogins.tsx       (only if screen has social login)
├── hooks/
│   └── use<ScreenName>Manager.ts
└── locales/
    └── en.json

• index.tsx — 薄い構成にします。use<ScreenName>Manager() を呼び出し、applyAuth0Theme() を呼び出して、ULThemePageLayout → ULThemeCard → サブコンポーネントの順にレンダリングします
• use<ScreenName>Manager.ts — samples のリファレンスにある SDK フックをラップし、型付きハンドラーと機能フラグを公開します
• フォームコンポーネント — react-hook-form を使用し、マネージャーフックから値を読み取ります。SDK を直接呼び出しません
• ヘッダー／フッター — ステートレスにし、テキストをプロパティとして受け取ります
• en.json — screen.texts.* で使用されるキーに対応するフォールバック文字列を指定します

フェーズ 5 のデザイントークンを、レイアウトコンポーネントとフォームコンポーネントのスタイリングに適用します。

パス C — 画面が auth0-acul-samples にない場合（単一ファイルコンポーネント）

assets/react-templates/ または assets/js-templates/ の構造をパターンとして使用し、フェーズ 2 で取得した SDK の例のみをソースとして、フックとアクションを含む単一の <screen-name>.tsx（React）または <screen-name>.js（JS）を生成します。

JSX の構造順序：

Outer layout wrapper → Card/panel → Logo slot → Title (screen.texts) →
Error banner (conditional) → Form fields → Captcha (conditional) →
Submit button → Passkey button (conditional) → Social divider + buttons
(conditional on alternateConnections) → Footer links

画面の登録（Path B と Path C のみ）

CLI は、スキャフォールドする画面を自動登録します（Path A）。手動で生成した画面（Path B、Path C）は登録が必要です。登録しない場合、ファイルが存在し、ビルドが成功していても、ローカルの auth0 acul dev では 「Screen '' is not implemented」 と表示されます。（接続モードではテナントから画面が解決されるため、この手順がなくても動作します。そのため、この問題はローカル開発でのみ発生します。）画面は src/utils/screen/screenLoader.ts の SCREEN_COMPONENTS マップを通じて解決されます。

手動で生成した画面ごとに、次の手順を実行します。

1. screenLoader.ts の管理方法を確認してください。手動編集されているとは限りません。 // Auto-generated file というバナーがある場合、または package.json に（scripts/generate-screen-loader.js を使用する generate:screenLoader などの）生成スクリプトがある場合は、src/screens/*/index.tsx を許可リストと照合して再生成されます。
   • <screen-name> が許可リスト（例：src/constants/validScreens.js）に含まれていることを確認し、npm run generate:screenLoader を実行します。生成されたファイルを手動編集しないでください。上書きされます。
   • 生成スクリプトがない場合に限り、次のエントリーを手動で追加します："<screen-name>": lazy(() => import("@/screens/<screen-name>")),
2. 画面の index.tsx（または単一ファイルのコンポーネント）に export default があることを確認します。React.lazy が解決するのは、名前付きエクスポートではなく デフォルト エクスポートです。

コード出力前の検証

• SDK のインポートパスが画面名と完全に一致している（例：@auth0/auth0-acul-react/mfa-otp-challenge）
• フックのパターン（汎用の useScreen() と画面固有のフックのどちらを使うか）は、推測ではなく CLI が生成したコードまたはリファレンスを参照している
• アクション関数名とペイロードの形状は、CLI が生成したコードまたはリファレンスを参照している
• エラー状態には SDK のソース（hasErrors / getErrors()）を使用している。ローカルだけのエラー状態は使用しない
• UI に文字列をハードコードしていない。ロケールへのフォールバックを使用して screen.texts.* を使う
• モジュール型アーキテクチャ（Path A、Path B）を使用する場合、index.tsx で applyAuth0Theme() を呼び出している
• 手動で生成した画面（Path B、Path C）が、対応する export default とともに src/utils/screen/screenLoader.ts に登録されている。これはローカルの auth0 acul dev に必要です

全画面が対象です： プロジェクト内のすべての画面について、それぞれに適用される Path A、B、C のいずれかを繰り返し、すべての画面で共有テーマファイルをインポートします。各パス内では、一貫したコンポーネント構成にします。

---

フェーズ 7：ビルドの検証と反復的な修正

画面コードを生成または変更した後は、次に進む前に必ず出力を検証します。生成されたコードには、誤ったインポートパスや不適切なインポート形式（デフォルトと名前付きの取り違え）、無効なコンポーネントの props、存在しないエクスポートへの参照が含まれることがあります。このフェーズでは、こうした問題を検出し、自動的に修正します。

ステップ 1 — 新しい依存関係をインストールする（ある場合）

生成または変更したコードによって package.json に新しい依存関係が追加され（dependencies / devDependencies に記載されていて、まだ node_modules にインストールされていない項目）、lint またはビルドを実行する前に、プロジェクトのルートから npm install を実行します。新しいパッケージが追加されていない場合は、この手順を省略します。

# Run from the project root
npm install

インストールに失敗した場合（peer dependency の競合、レジストリエラー、バージョンの不一致）は、エラーをお客様に伝えて停止します。解決するまで lint / ビルドには進まないでください。

ステップ 2 — lint を実行する

プロジェクトのリンターを実行し、インポートエラー、型の不一致、無効な props を検出します。

# Detect the lint command from package.json scripts
npm run lint 2>&1 || npx eslint src/screens/<screen-name>/ --ext .ts,.tsx,.js,.jsx 2>&1

プロジェクトで TypeScript を使用している場合は、型チェッカーも実行します。

npx tsc --noEmit 2>&1

ステップ 3 — ビルドを実行する

npm run build 2>&1

ステップ 4 — エラーを解析し、反復して修正する

lint またはビルドでエラーが発生した場合は、各エラーを解析し、適切な修正を適用します。

エラーパターン	根本原因	修正方法
does not have a default export	名前付きエクスポートに import X を使用している	import { X } に変更する
has no exported member	モジュールに存在しないシンボルをインポートしている	ソースモジュールを確認し、正しいエクスポート名を見つける
Module not found / Cannot find module	インポートパスが間違っている	node_modules またはプロジェクトのソースツリーで正しいパスを確認する
Property 'X' does not exist on type	コンポーネントに無効なプロパティを渡している	コンポーネントの型定義またはソースを確認し、有効なプロパティを見つける
is not assignable to type	プロパティの型が一致していない	値をキャストまたは変換し、期待される型に合わせる
JSX element type 'X' does not have any construct or call signatures	コンポーネントのインポートが間違っているか、存在しない	コンポーネントが存在し、モジュールから正しくエクスポートされていることを確認する

修正ワークフロー：

1. エラー出力を読み、ファイル、行、エラーコードを特定します。
2. エラーが発生した箇所のソースファイルを読み、文脈を把握します。
3. エラーがインポートに関する場合は、対象モジュール（node_modules またはプロジェクトのソース）を読み、正しいエクスポート名とパスを見つけます。
4. 修正を適用します。
5. npm run build 2>&1 を再実行します。
6. ビルドが成功するまで、ステップ 1 から繰り返します。

反復回数の上限： 最大 5 回とします。エラーが停滞した場合（連続する 2 回の反復でエラー数またはエラー内容が同じ場合）は、上限に達する前でも直ちに停止します。上限に達してもエラーが残っている場合は、残りのエラーを顧客に提示し、コードの変更を続けるのではなく、指示を求めてください。

このフェーズで検出する一般的な落とし穴

• ファイルで export const Component（名前付きエクスポート）が使われているのに、import Component from './Component' とする — 修正：import { Component } from './Component' にする
• 画面固有のパス @auth0/auth0-acul-react/login-id ではなく、import { useLoginId } from '@auth0/auth0-acul-react' とする — 修正：正しいサブパスを使ってインポートする
• ULThemeCard が title プロパティを受け付けないのに、<ULThemeCard title={...}> を使用する — 修正：無効なプロパティを削除し、代わりに子コンポーネントとして <Header> を使う
• プロジェクトに存在しないパスからテーマユーティリティをインポートする — 修正：プロジェクトツリーで実際のパスを確認する
• applyAuth0Theme がデフォルトエクスポートなのに名前付きインポートとして使用する（またはその逆） — 修正：モジュールで実際に使われているエクスポート形式に合わせる

ビルドでは検出できないランタイムチェック：未登録の画面

npm run build が正常に終了しても、手動で追加した画面がローカル開発環境で表示されるとは限りません。ビルドは成功していても、次の場合には auth0 acul dev に "Screen '' is not implemented" と表示されます。

• src/utils/screen/screenLoader.ts の SCREEN_COMPONENTS マップに画面が登録されていない、または
• 画面の index.tsx に export default がないため、lazy() がコンポーネントを解決できない。

Path B または Path C を通じて生成されたすべての画面について、作業を完了する前に両方を確認してください。これはランタイム／レジストリの問題であり、コンパイルエラーではありません。lint と tsc では検出されません。プロジェクトが screenLoader.ts を自動生成する場合は、手動編集ではなく、ジェネレーター（npm run generate:screenLoader）を使って登録してください。（Phase 6 の「Screen Registration」を参照してください。）

検証の成功

ビルドが 終了コード 0 で完了し、lint エラーがなく、さらに手動で追加したすべての画面が screenLoader.ts に登録されていて、export default があることを確認したら、Phase 8 に進みます。

---

Phase 8: 開発モードの設定

すぐに実行できるコマンドを顧客に提示します。

# Local preview — no tenant connection needed
auth0 acul dev -p 3000 -d <project-dir>

# Connected mode — syncs assets to tenant (stage/dev only)
auth0 acul dev --connected -s <screen-name> -d <project-dir>

⚠️ コネクテッドモードを提案する場合は、必ず次の警告を含めてください。

コネクテッドモードでは、Auth0 テナントがリアルタイムで更新されます。このモードはステージングまたは開発用テナントでのみ使用し、本番環境では決して使用しないでください。

参照ファイル

ファイル	読み込むタイミング
references/acul-react-sdk.md	フレームワークが React の場合
references/acul-js-sdk.md	フレームワークが JS / Vanilla の場合
references/screen-catalog.md	画面タイプの選択、または CLI フォールバックの実行時
references/social-providers.md	ソーシャルログインボタンが必要な場合
references/theming-patterns.md	共通のテーマファイルを生成または適用する場合
references/cli-commands.md	CLI の全フラグの詳細が必要な場合

アセットテンプレート

ファイル	使用するタイミング
assets/theme-templates/tailwind.config.ts	Tailwind、すべての画面が対象の場合
assets/theme-templates/tokens.css	CSS Modules、すべての画面が対象の場合
assets/theme-templates/theme-provider.ts	styled-components の場合
assets/theme-templates/globals.css	通常の CSS、すべての画面が対象の場合
assets/react-templates/<screen>.tsx	React コンポーネントのボイラープレートのベース
assets/js-templates/<screen>.js	JS コンポーネントのボイラープレートのベース