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:

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

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

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

Verify
```
acul_config.json
```
exists in the project directory.
- If missing → stop. Instruct customer to run
```
auth0 acul init
```
  first.
Run:
bash
```
auth0 acul screen add <screen-name> -d <project-dir>
```
If CLI errors or screen is not recognised → continue to step 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

Verify
```
acul_config.json
```
exists.

Fetch current rendering configuration:

bash

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

Read the existing screen file from the customer's codebase.
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, 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 whether the screen is in auth0-acul-samples.

Path A — Screen is in auth0-acul-samples (modular architecture)

Generate the full directory structure using the samples pattern (see "auth0-acul-samples Architecture" above):

<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

— thin: calls

use<ScreenName>Manager()

, calls

applyAuth0Theme()

, renders

ULThemePageLayout

→

ULThemeCard

→ sub-components

```
use<ScreenName>Manager.ts
```
— wraps SDK hooks from the samples reference, exposes typed handlers and feature flags
Form component — uses react-hook-form, reads from manager hook, no direct SDK calls
Header/Footer — stateless, receive texts as props
```
en.json
```
— fallback strings matching keys used in
```
screen.texts.*
```

Apply design tokens from Phase 5 to the layout components and form component styling.

Path B — Screen is NOT in auth0-acul-samples (single-file component)

Generate a single

<screen-name>.tsx

(React) or

<screen-name>.js

(JS) using the structure from

assets/react-templates/

assets/js-templates/

as a pattern, with hooks and actions sourced entirely from the SDK example fetched in Phase 2.

JSX structure order:

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

Validation before outputting any code

SDK import path exactly matches the screen name (e.g.,
```
@auth0/auth0-acul-react/mfa-otp-challenge
```
)
Hook pattern (generic
```
useScreen()
```
vs screen-specific hook) sourced from the reference, not assumed
Action function names and payload shapes sourced from the reference
Error state uses SDK source (
```
hasErrors
```
/
```
getErrors()
```
) — never local-only error state
No hardcoded UI strings — use
```
screen.texts.*
```
with locale fallback
```
applyAuth0Theme()
```
called in index.tsx for Path A screens

All-screens scope: repeat Path A or Path B (whichever applies per screen) for every screen in the project, all importing from the shared theme file. Consistent component structure within each path.

Phase 7: Dev Mode Wiring

Provide the customer with ready-to-run commands:

bash

# 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>

⚠️ Always include this warning when connected mode is suggested:

Connected mode updates your Auth0 tenant in real time. Only use this on a stage or development tenant — never on production.

Reference Files

File	Load when
`references/acul-react-sdk.md`	Framework is React
`references/acul-js-sdk.md`	Framework is JS / Vanilla
`references/screen-catalog.md`	Selecting screen type or triggering CLI fallback
`references/social-providers.md`	Social login buttons are needed
`references/theming-patterns.md`	Generating or applying a shared theme file
`references/cli-commands.md`	Need full CLI flag details

Asset Templates

File	Use when
`assets/theme-templates/tailwind.config.ts`	Tailwind, all-screens scope
`assets/theme-templates/tokens.css`	CSS Modules, all-screens scope
`assets/theme-templates/theme-provider.ts`	styled-components
`assets/theme-templates/globals.css`	Plain CSS, all-screens scope
`assets/react-templates/<screen>.tsx`	React component boilerplate base
`assets/js-templates/<screen>.js`	JS component boilerplate base

acul-screen-generator

NPX Install

Tags

SKILL.md Content

ACUL Screen Generator

Reference Hierarchy

auth0-acul-samples Architecture

Prerequisites

Phase 0: CLI Authentication & Tenant Check

Phase 1: Intent Detection

Phase 2A: Scratch — Project Init

Phase 2B: Add Screen — CLI + Reference Fetch

Phase 2C: Modify Screen — Fetch Current State

Phase 3: Screen Requirements

Phase 4: Tech Stack Detection

Phase 5: Theme Extraction & Scope

Design input — detect which the customer has provided:

Theme scope — ask the customer:

Phase 6: Structured Code Generation

Path A — Screen is in auth0-acul-samples (modular architecture)

Path B — Screen is NOT in auth0-acul-samples (single-file component)

Validation before outputting any code

Phase 7: Dev Mode Wiring

Reference Files

Asset Templates