Acul Screen Generator

SKILL.md

---
name: acul-screen-generator
description: Generates complete, branded Auth0 Advanced Custom Universal Login (ACUL) screen implementations using the React or Vanilla JS SDK. Use when a developer asks to create, add, or modify ACUL login screens with custom branding, social login, theming, or specific authentication flows. Triggers on requests like "generate a custom login screen", "add a signup screen to my ACUL project", "customize my Auth0 Universal Login with our brand colors", "apply our theme to all ACUL screens", or any task involving Auth0 Universal Login customization with @auth0/auth0-acul-react or @auth0/auth0-acul-js.
license: Apache-2.0
metadata:
  author: Auth0 <support@auth0.com>
  version: '1.0.1'
  openclaw:
    emoji: "🔐"
    homepage: https://github.com/auth0/agent-skills
---

# 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, 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/` or `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 |