acul-screen-generator

What this skill does

# ACUL Screen Generator

Generates production-ready, fully themed Auth0 ACUL screen components. Follows a strict 8-phase workflow (Phases 0–7): CLI authentication → intent detection → project setup → screen requirements → tech stack and design → theme extraction → structured code generation → dev mode wiring.

## Reference Hierarchy

Always resolve the correct reference for a screen using this priority order:

```
1. auth0-acul-samples  (31 React screens, 3 React-JS screens)
   → Complete modular implementation: 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. SDK examples  (68 React, 71 JS — all screens)
   → 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

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

For which screens are in auth0-acul-samples → read `references/screen-catalog.md`.

---

## auth0-acul-samples Architecture

When a screen is available in auth0-acul-samples, generate code using this modular pattern — not a monolithic component.

**Directory structure per screen:**
```
<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 pattern:**
```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" />    {/* conditional */}
        <<ScreenName>Form />
        <Footer texts={texts} links={links} />
        <AlternativeLogins alignment="bottom" />  {/* conditional */}
      </ULThemeCard>
    </ULThemePageLayout>
  )
}
```

**hooks/use\<ScreenName\>Manager.ts pattern:**
```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,
  }
}
```

When a screen is **not** in auth0-acul-samples, fall back to a single-file component based on the SDK example.

## Prerequisites

- Auth0 CLI installed: `brew install auth0`
- Custom domain configured on the Auth0 tenant (hard ACUL requirement)
- Node.js 18+

---

## Phase 0: CLI Authentication & Tenant Check

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

If `auth0 acul config list` returns an error about custom domain: stop and inform the customer they must configure a custom domain on their tenant before ACUL is available.

For full CLI flag reference → read `references/cli-commands.md`.

---

## Phase 1: Intent Detection

Ask the customer which mode they need:

- **A) Build from scratch** — new project, select screens, full setup
- **B) Add a screen** — existing project, add one or more new screens
- **C) Modify a screen** — existing project, change an existing screen's code or styling

This choice gates Phases 2A / 2B / 2C.

---

## Phase 2A: Scratch — Project Init

Gather: app name, framework (`react` or `js`), initial screen list.

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

Verify `acul_config.json` is created in the project directory. Proceed to Phase 3.

---

## Phase 2B: Add Screen — CLI + Reference Fetch

1. Verify `acul_config.json` exists in the project directory.
   - If missing → stop. Instruct customer to run `auth0 acul init` first.

2. Run:
   ```bash
   auth0 acul screen add <screen-name> -d <project-dir>
   ```
   If CLI errors or screen is not recognised → continue to step 3.

3. **Always resolve the reference using the hierarchy** (regardless of CLI success or failure):

   **Step 3a — Check auth0-acul-samples first:**
   - Read `references/screen-catalog.md` to check if the screen has a `✅` in the Samples column
   - If yes → fetch the screen directory from:
     - 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>`
   - Fetch `index.tsx` and the `hooks/use<ScreenName>Manager.ts` file to understand the full implementation
   - Use the samples architecture (modular: index + components + hooks + locales)

   **Step 3b — If not in samples, fetch SDK example:**
   - 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`
   - Parse for: exact import path, hook pattern (generic vs screen-specific), action functions and payload shapes
   - Use a single-file component (no modular split needed)

   This step is mandatory. The 68+ ACUL screens use fundamentally different hook patterns — wrong pattern = broken code.

   For all screen names and which are in samples → read `references/screen-catalog.md`.

---

## Phase 2C: Modify Screen — Fetch Current State

1. Verify `acul_config.json` exists.

2. Fetch current rendering configuration:
   ```bash
   auth0 acul config get <screen-name> -f <screen-name>.json
   auth0 acul config list --rendering-mode advanced
   ```

3. Read the existing screen file from the customer's codebase.

4. **Always resolve the reference using the same hierarchy as Phase 2B** (samples first, SDK example second). Even when modifying an existing file, the reference confirms whether the current code uses the correct hook pattern, action functions, and component structure before making changes.

---

## Phase 3: Screen Requirements

Gather from the customer:

- **Screen type** — for full list of available screens → read `references/screen-catalog.md`
- **Components needed:**
  - Social providers: Google, GitHub, Apple, Microsoft, Facebook
  - Form fields: email, username, phone, password, confirm-password
  - MFA type (if applicable): OTP,