Générateur d'écrans ACUL

Génère des composants d'écrans ACUL Auth0 prêts pour la production, entièrement thématisés. Suit un flux de travail strict à 8 phases (Phases 0–7) : authentification CLI → détection d'intention → configuration du projet → exigences d'écrans → pile technologique et design → extraction de thème → génération de code structurée → câblage du mode dev.

Hiérarchie des références

Résolvez toujours la bonne référence pour un écran en utilisant cet ordre de priorité :

1. auth0-acul-samples  (31 écrans React, 3 écrans React-JS)
   → Implémentation modulaire complète : index.tsx + components/ + hooks/ + locales/
   → 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>

2. Exemples SDK  (68 React, 71 JS — tous les écrans)
   → Extraits de code montrant les importations SDK, hooks et fonctions d'action
   → 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

3. assets/react-templates/ ou assets/js-templates/
   → Motif de composant structurel uniquement — n'utilisez jamais leurs hooks/actions pour d'autres écrans

Pour savoir quels écrans se trouvent dans auth0-acul-samples → lisez references/screen-catalog.md.

Architecture auth0-acul-samples

Quand un écran est disponible dans auth0-acul-samples, générez du code en utilisant ce motif modulaire — pas un composant monolithique.

Structure de répertoire par écran :

<screen-name>/
├── index.tsx                        entrée légère : câble le hook manager + applique le thème + rend la mise en page
├── components/
│   ├── Header.tsx                   logo, titre, sous-titre de screen.texts
│   ├── <ScreenName>Form.tsx         champs de formulaire, submit, captcha, bouton passkey
│   ├── Footer.tsx                   lien d'inscription, mot de passe oublié, lien retour
│   └── AlternativeLogins.tsx        boutons de connexion sociale (si l'écran a du social)
├── hooks/
│   └── use<ScreenName>Manager.ts    encapsule les hooks SDK, expose des gestionnaires propres + drapeaux de fonctionnalités
└── locales/
    └── en.json                      chaînes de texte de secours

Motif 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'

export 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" />    {/* conditionnel */}
        <<ScreenName>Form />
        <Footer texts={texts} links={links} />
        <AlternativeLogins alignment="bottom" />  {/* conditionnel */}
      </ULThemeCard>
    </ULThemePageLayout>
  )
}

Motif 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()       // hook SDK spécifique à l'écran
  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,
  }
}

Quand un écran n'est pas dans auth0-acul-samples, basculez vers un composant à fichier unique basé sur l'exemple SDK.

Prérequis

• Auth0 CLI installé : brew install auth0
• Domaine personnalisé configuré sur le tenant Auth0 (exigence ACUL stricte)
• Node.js 18+

Phase 0 : Authentification CLI et vérification du tenant

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

Si auth0 acul config list renvoie une erreur concernant le domaine personnalisé : arrêtez et informez le client qu'il doit configurer un domaine personnalisé sur son tenant avant que ACUL soit disponible.

Pour une référence complète des drapeaux CLI → lisez references/cli-commands.md.

Phase 1 : Détection d'intention

Demandez au client quel mode il utilise :

• A) Construire à partir de zéro — nouveau projet, sélectionner les écrans, configuration complète
• B) Ajouter un écran — projet existant, ajouter un ou plusieurs nouveaux écrans
• C) Modifier un écran — projet existant, modifier le code ou le style d'un écran existant

Ce choix gère les Phases 2A / 2B / 2C.

Phase 2A : À partir de zéro — Initialisation du projet

Collectez : nom de l'application, framework (react ou js), liste d'écrans initiale.

auth0 acul init <app_name> -t react -s login-id,login-password,signup
auth0 acul config generate <screen-name>    # répétez par écran

Vérifiez que acul_config.json est créé dans le répertoire du projet. Passez à la Phase 3.

Phase 2B : Ajouter un écran — CLI et extraction de référence

1. Vérifiez que acul_config.json existe dans le répertoire du projet.

   • S'il manque → arrêtez. Instruisez le client d'exécuter auth0 acul init d'abord.

2. Exécutez :

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

   Si le CLI génère une erreur ou l'écran n'est pas reconnu → passez à l'étape 3.

3. Résolvez toujours la référence en utilisant la hiérarchie (quel que soit le succès ou l'échec du CLI) :

   Étape 3a — Vérifiez d'abord auth0-acul-samples :

   • Lisez references/screen-catalog.md pour vérifier si l'écran a un ✅ dans la colonne Samples
   • Si oui → récupérez le répertoire d'écrans depuis :
     • 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>
   • Récupérez index.tsx et le fichier hooks/use<ScreenName>Manager.ts pour comprendre l'implémentation complète
   • Utilisez l'architecture samples (modulaire : index + components + hooks + locales)

   Étape 3b — Si pas dans samples, récupérez l'exemple SDK :

   • 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
   • Analysez pour : chemin exact de l'import, motif de hook (générique vs spécifique à l'écran), noms des fonctions d'action et formes de payload
   • Utilisez un composant à fichier unique (aucune division modulaire nécessaire)

   Cette étape est obligatoire. Les 68+ écrans ACUL utilisent des motifs de hook fondamentalement différents — un motif incorrect = code cassé.

   Pour tous les noms d'écrans et lesquels sont dans samples → lisez references/screen-catalog.md.

Phase 2C : Modifier un écran — Récupérer l'état actuel

1. Vérifiez que acul_config.json existe.

2. Récupérez la configuration de rendu actuelle :

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

3. Lisez le fichier d'écran existant depuis la base de code du client.

4. Résolvez toujours la référence en utilisant la même hiérarchie que la Phase 2B (samples d'abord, exemple SDK ensuite). Même lors de la modification d'un fichier existant, la référence confirme si le code actuel utilise le motif de hook correct, les fonctions d'action et la structure de composant avant d'apporter des modifications.

Phase 3 : Exigences des écrans

Collectez auprès du client :

• Type d'écran — pour la liste complète des écrans disponibles → lisez references/screen-catalog.md
• Composants nécessaires :
  • Fournisseurs sociaux : Google, GitHub, Apple, Microsoft, Facebook
  • Champs de formulaire : email, username, phone, password, confirm-password
  • Type MFA (le cas échéant) : OTP, SMS, push, WebAuthn
  • Extras optionnels : captcha, bouton passkey, remember-me, case à cocher conditions
• Pour le mode modification : ce qui doit être changé précisément (mise en page, couleurs, ajouter/supprimer un composant)

Phase 4 : Détection de la pile technologique

Confirmez ou détectez :

• Framework : React (@auth0/auth0-acul-react) ou JS (@auth0/auth0-acul-js)
• Bibliothèque de style : Tailwind CSS / CSS Modules / styled-components / CSS simple
• Fichier de thème existant ? Vérifiez la présence de tailwind.config.ts, styles/tokens.css, theme/index.ts

Chargez la référence SDK appropriée :

• React → lisez references/acul-react-sdk.md
• JS → lisez references/acul-js-sdk.md

Pour l'implémentation de bouton social → lisez references/social-providers.md.

Phase 5 : Extraction et portée du thème

Entrée de design — détectez lequel le client a fourni :

Option A — Image ou maquette (jpeg / png / capture d'écran) : Analysez l'image et extrayez :

• Couleurs primaire, secondaire, accentuation (en hexadécimal)
• Couleurs de fond et surfaces/cartes
• Famille de police et poids
• Style de rayon de bordure (net / léger / arrondi / pilule)
• Rythme d'espacement (compact / normal / spacieux)
• Type de mise en page : carte centrée / full-bleed / panneau divisé / carte flottante

Option B — Couleurs de marque uniquement (pas d'image) : Dérivez l'ensemble complet de jetons à partir des valeurs hexadécimales fournies :

primary        → bg du bouton, liens, anneau de focus
primary-hover  → primary assombri ~10%
primary-text   → blanc si primary est foncé, sinon #111827
background     → fond de page
surface        → fond de carte/panneau
text-primary   → titres (#111827 clair / #F1F5F9 foncé)
text-secondary → labels, placeholders
border         → bordures d'entrée
error          → #EF4444 (sauf indication contraire)
success        → #22C55E (sauf indication contraire)

Portée du thème — demandez au client :

• Écran unique : appliquez les jetons en ligne aux styles de ce seul composant
• Tous les écrans : générez d'abord un fichier de thème partagé, puis appliquez-le de manière cohérente à tous les écrans

Pour les motifs de fichiers de thème par bibliothèque de style → lisez references/theming-patterns.md.

Fichier de thème à générer par bibliothèque de style (portée tous-écrans) :

Remplacez tous les placeholders {{TOKEN}} par les valeurs de jetons extraites.

Phase 6 : Génération de code structurée

L'approche de génération dépend du fait que l'écran se trouve ou non dans auth0-acul-samples.

Chemin A — L'écran est dans auth0-acul-samples (architecture modulaire)

Générez la structure complète du répertoire en utilisant le motif samples (voir « Architecture auth0-acul-samples » ci-dessus) :

<screen-name>/
├── index.tsx
├── components/
│   ├── Header.tsx
│   ├── <ScreenName>Form.tsx
│   ├── Footer.tsx
│   └── AlternativeLogins.tsx       (uniquement si l'écran a une connexion sociale)
├── hooks/
│   └── use<ScreenName>Manager.ts
└── locales/
    └── en.json

• index.tsx — légère : appelle use<ScreenName>Manager(), appelle applyAuth0Theme(), rend ULThemePageLayout → ULThemeCard → sous-composants
• use<ScreenName>Manager.ts — encapsule les hooks SDK de la référence samples, expose des gestionnaires typés et des drapeaux de fonctionnalités
• Composant Form — utilise react-hook-form, lit depuis le hook manager, aucun appel SDK direct
• Header/Footer — sans état, reçoivent les textes en props
• en.json — chaînes de secours correspondant aux clés utilisées dans screen.texts.*

Appliquez les jetons de design de la Phase 5 aux composants de mise en page et au style du composant formulaire.

Chemin B — L'écran n'est PAS dans auth0-acul-samples (composant à fichier unique)

Générez un <screen-name>.tsx (React) ou <screen-name>.js (JS) unique en utilisant la structure de assets/react-templates/ ou assets/js-templates/ comme motif, avec hooks et actions provenant entièrement de l'exemple SDK récupéré à la Phase 2.

Ordre de structure JSX :

Wrapper de mise en page externe → Carte/panneau → Logement de logo → Titre (screen.texts) →
Banneau d'erreur (conditionnel) → Champs de formulaire → Captcha (conditionnel) →
Bouton Submit → Bouton Passkey (conditionnel) → Diviseur social + boutons
(conditionnel sur alternateConnections) → Liens de pied de page

Validation avant de générer du code

• Le chemin d'import SDK correspond exactement au nom de l'écran (par ex. @auth0/auth0-acul-react/mfa-otp-challenge)
• Le motif de hook (générique useScreen() vs hook spécifique à l'écran) provient de la référence, pas supposé
• Les noms des fonctions d'action et les formes de payload proviennent de la référence
• L'état d'erreur utilise la source SDK (hasErrors / getErrors()) — jamais un état d'erreur local uniquement
• Aucune chaîne UI codée en dur — utilisez screen.texts.* avec fallback de locale
• applyAuth0Theme() appelé dans index.tsx pour les écrans du Chemin A

Portée tous-écrans : répétez le Chemin A ou B (celui qui s'applique par écran) pour chaque écran du projet, tous important depuis le fichier de thème partagé. Structure de composant cohérente dans chaque chemin.

Phase 7 : Câblage du mode dev

Fournissez au client les commandes prêtes à exécuter :

# Aperçu local — aucune connexion au tenant nécessaire
auth0 acul dev -p 3000 -d <project-dir>

# Mode connecté — synchronise les assets au tenant (stage/dev uniquement)
auth0 acul dev --connected -s <screen-name> -d <project-dir>

⚠️ Incluez toujours cet avertissement quand le mode connecté est suggéré :

Le mode connecté met à jour votre tenant Auth0 en temps réel. N'utilisez cela que sur un tenant stage ou de développement — jamais en production.

Fichiers de référence

Modèles d'assets