Acul Screen Generator

ACUL Screen Generator

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

Reference Hierarchy

Always resolve the correct reference for a screen using this priority order. Before running the CLI, check if the screen exists in auth0-acul-samples — if it does not, the CLI will fail.

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/
     React-JS: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/
   → 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/.md
   → JS:    https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/.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

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:

/
├── index.tsx                        thin entry: wires manager hook + applies theme + renders layout
├── components/
│   ├── Header.tsx                   logo, title, subtitle from screen.texts
│   ├── 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/
│   └── useManager.ts    wraps SDK hooks, exposes clean handlers + feature flags
└── locales/
    └── en.json                      fallback text strings

index.tsx pattern:

import { ULThemeCard, ULThemePageLayout } from '@/components'
import { applyAuth0Theme } from '@/utils/theme/themeEngine'
import Header from './components/Header'
import Form from './components/Form'
import Footer from './components/Footer'
import { useManager } from './hooks/useManager'

const Screen = () => {
  const { sdkInstance, texts, locales } = useManager()
  applyAuth0Theme(sdkInstance)
  document.title = texts?.pageTitle ?? locales.pageTitle

  return (
    
      
        
            {/* conditional */}
        Form />
        
          {/* conditional */}
      
    
  )
}

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

> index.tsx must have a export default. The project's screen registry (src/utils/screen/screenLoader.ts) loads each screen with lazy(() => import('@/screens/')), and React.lazy resolves the module's default export. A named-only export (export const Screen) compiles fine but renders blank / "screen not implemented" at runtime. See "Screen Registration" in Phase 6.

hooks/use\Manager.ts pattern:

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

export const useManager = () => {
  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 and the CLI doesn't support it, 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 ≥ 22 (required by Auth0 CLI-generated ACUL projects)

---

Phase 0: Environment Validation & CLI Authentication

Step 1 — Verify Node.js version

node --version 2>&1

Parse the output and verify the major version is ≥ 22. If Node.js is not installed or the version is below 22:

• Not installed: Stop and instruct the customer to install Node.js 22+ (e.g., nvm install 22 or download from nodejs.org).
• **Version -t react -s login-id,login-password,signup

auth0 acul config generate # repeat per screen

Verify `acul_config.json` is created in the project directory.

**The CLI-scaffolded code is your primary source.** Read the generated screen files to understand the project structure, SDK imports, hook patterns, and component layout. Do NOT fetch from GitHub — the CLI output is the canonical starting point. Only customize or extend the generated code based on the customer’s requirements (branding, extra components, etc.).

Proceed to Phase 3.

---

## Phase 2B: Add Screen — Check Samples Availability First

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

2. **Check if the screen exists in auth0-acul-samples before attempting CLI.**

   Read `references/screen-catalog.md` and check the `Samples (React)` or `Samples (React-JS)` column for the requested screen. Then fetch the GitHub directory listing to **confirm** the screen actually exists at the expected path:

   ```text
   React:    https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/
   React-JS: https://github.com/auth0-samples/auth0-acul-samples/tree/main/react-js/src/screens/
   ```

   This check determines whether the CLI can scaffold the screen. If the screen is NOT present in auth0-acul-samples, the CLI `auth0 acul screen add` command will fail — so skip it entirely and go straight to Step 4.

3. **Screen IS in auth0-acul-samples → try the CLI:**
   ```bash
   auth0 acul screen add  -d 
   ```
   - **If CLI succeeds → use the scaffolded code directly.** Read the generated files to understand the structure, SDK imports, and hook patterns. Do NOT fetch from GitHub. Customize the CLI-generated code based on the customer’s requirements (branding, components, etc.). Proceed to Phase 3.
   - **If CLI errors despite the screen being in samples** (e.g., auth issues, version mismatch) → fall through to Step 4 as a recovery path.

4. **Screen is NOT in auth0-acul-samples (or CLI failed) → skip CLI, fetch reference directly.**

   Since the CLI does not support this screen, do NOT attempt `auth0 acul screen add` — it will error. Instead, build the screen from reference code.

   **Step 4a — Capture project structure (if not already known):**
   If this is the first screen being added manually (i.e., you don’t already have a reference for the project’s directory layout, config wiring, and build setup from a previous CLI-generated screen), create a dummy page:
   ```bash
   auth0 acul screen add login-id -d 
   ```
   - Read the generated dummy screen files to capture the project structure, directory layout, config wiring, and build setup
   - Then remove the dummy screen files (delete the `login-id/` screen directory)

   If you already have the project structure from a previous CLI-generated or manually-created screen, skip this step.

   **Step 4b — Fetch the screen reference code:**
   Determine the tech stack of the existing project (React or JS/Vanilla) by inspecting the project files. Then fetch the reference:

   - **React project → check SDK examples in universal-login repo:**
     - Fetch: `https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/.md`
     - Parse for: exact import path, hook pattern (Pattern A or B), action function names, and payload shapes
   - **JS/Vanilla project → check JS SDK examples:**
     - Fetch: `https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-js/examples/.md`
     - Parse for: manager class name, method names, and payload shapes

   Determine whether the example is React (JSX/TSX, hooks) or plain JS (class-based manager) and match it to the project’s framework. If the project is React but only a JS example exists (or vice versa), adapt the patterns accordingly using the appropriate SDK reference (`references/acul-react-sdk.md` or `references/acul-js-sdk.md`).

   **Step 4c — Generate the screen files using the project structure**, populated with the SDK reference data from step 4b. This ensures correct directory layout, config integration, and build compatibility. Follow the modular architecture pattern from the "auth0-acul-samples Architecture" section if React, or a single-file component if the example is simple enough.

   **Step 4d — Register the screen so local dev mode can resolve it (REQUIRED).**
   The CLI auto-registers screens it scaffolds, but **manually generated screens are not registered** — so `auth0 acul dev` (local mode) renders **"Screen '' is not implemented"** even though the files exist and the build passes. (Connected mode reads screens from the tenant, so it works without this step — which is why the bug only shows in local dev.) The screen resolves through a `SCREEN_COMPONENTS` map in `src/utils/screen/screenLoader.ts`.

   **First determine how the project maintains that map — do NOT assume it is hand-edited:**

   1. Check whether `screenLoader.ts` is auto-generated. Open it and look for a banner like `// Auto-generated file`, and check `package.json` scripts for a generator (e.g. `generate:screenLoader`) and `scripts/generate-screen-loader.js`.
      - **If a generator exists (the common case for CLI-scaffolded projects):** the loader is regenerated by scanning `src/screens/*/index.tsx` against an allowlist (e.g. `src/constants/validScreens.js`). **Do NOT hand-edit `screenLoader.ts` — your edit will be overwritten.** Instead:
        - Confirm `` is present in the allowlist (`VALID_SCREENS`). If missing, add it there.
        - Run the generator: `npm run generate:screenLoader` (use the actual script name from `package.json`).
        - Verify the new entry now appears in `screenLoader.ts`.
      - **If there is no generator:** hand-edit the `SCREEN_COMPONENTS` map directly:
        ```ts
        "": lazy(() => import("@/screens/")),
        ```
   2. Either way, confirm the screen's `index.tsx` has a **default export** (`export default Screen`) — `lazy()` resolves the default export. A named-only export compiles but loads as blank / "not implemented".

   For all screen names and their availability → 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  -f .json
   auth0 acul config list --rendering-mode advanced
   ```

3. Read the existing screen file from the customer's codebase. **The local code is your primary reference.** Understand its current structure, SDK imports, and hook patterns before making any changes.

4. Only fetch from GitHub references if the local code is missing critical SDK patterns (e.g., wrong hook pattern, missing action functions) and you cannot determine the correct pattern from the existing codebase. Use the Reference Hierarchy (samples availability → CLI scaffolded code when supported → SDK examples) to validate.

---

## 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, SMS, push, WebAuthn
  - Optional extras: captcha, passkey button, remember-me, terms checkbox
- **For modify mode:** what specifically to change (layout, colors, add/remove a component)

---

## Phase 4: Tech Stack Detection

Confirm or detect:

- **Framework:** React (`@auth0/auth0-acul-react`) or JS (`@auth0/auth0-acul-js`)
- **Styling library:** Tailwind CSS / CSS Modules / styled-components / plain CSS
- **Existing theme file?** Check for `tailwind.config.ts`, `styles/tokens.css`, `theme/index.ts`

Load the appropriate SDK reference:
- React → read `references/acul-react-sdk.md`
- JS → read `references/acul-js-sdk.md`

For social button implementation → read `references/social-providers.md`.

---

## Phase 5: Theme Extraction & Scope

### Design input — detect which the customer has provided:

**Option A — Image or mockup (jpeg / png / screenshot):**
Analyze the image and extract:
- Primary, secondary, accent colors (as hex)
- Background and card/surface colors
- Font family and weights
- Border radius style (sharp / slight / rounded / pill)
- Spacing rhythm (compact / normal / spacious)
- Layout type: centered card / full-bleed / split-panel / floating card

**Option B — Brand colors only (no image):**
Derive the full token set from the provided hex values:

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)

### Theme scope — ask the customer:

- **Single screen:** apply tokens inline to just this component's styles
- **All screens:** generate a shared theme file first, then apply consistently across every screen

For theme file patterns per styling library → read `references/theming-patterns.md`.

**Theme file to generate per styling library (all-screens scope):**

| Styling library | Template to use | Output file |
|----------------|-----------------|-------------|
| 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` |

Replace all `{{TOKEN}}` placeholders with extracted token values.

---

## Phase 6: Structured Code Generation

Generation approach depends on the source of the screen code.

### Path A — CLI-scaffolded screen (preferred)

When the CLI successfully generates the screen (via `auth0 acul init` or `auth0 acul screen add`), use the CLI output as the base. Read the generated files and customise them based on the customer's requirements:

- Apply design tokens from Phase 5 to the generated component styling
- Add/remove components as specified (social buttons

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [auth0](https://github.com/auth0)
- **Source:** [auth0/agent-skills](https://github.com/auth0/agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.