# Generation Phase — Regole per il Generatore

Questo file definisce come produrre i mockup HTML. Il generatore è l'agente (o persona) che crea le opzioni di design. NON si auto-valuta — la valutazione spetta a un agente separato (vedi [evaluation.md](evaluation.md)).

> Paths and stylistic identity in this file resolve from `baldart.config.yml`.
> See `framework/agents/project-context.md` § 4. Project-specific stylistic
> defaults (e.g. forced design philosophy, hard-coded UI language) live in
> `.baldart/overlays/ui-design.md`.

## Regola del Filesystem (ASSOLUTA — rispettare prima di tutto)

Ogni file HTML generato DEVE essere scritto su disco con il tool `Write` PRIMA di aprirlo nel browser. Non è sufficiente mostrare il codice in un blocco inline.

- Path di destinazione: `/tmp/prd-design-<slug>/option-a.html` (e varianti b, c).
- Dopo la scrittura, apri nel browser di default (macOS):
  ```bash
  open /tmp/prd-design-<slug>/option-a.html
  ```
  (Linux: `xdg-open`. Windows: `start`.)
- Il file esiste su disco → l'utente può interagire, ispezionare, condividere.
- Solo codice inline → non verificabile, non apribile, non consegnabile.

## Skill HTML (OBBLIGATORIA)

Invocare la skill `huashu-design` all'inizio della fase di generazione. Essa fornisce:

- Junior Designer workflow (assunzioni + reasoning + placeholder → iterazioni)
- App Prototype shell: per ogni iPhone include AppPhone state manager interattivo
- Immagini reali da Wikimedia/Met/Unsplash (default per app prototype)
- Tweaks panel per varianti di design in-page
- Validazione Playwright click-test prima della consegna
- Export animazioni → MP4/GIF quando necessario

## Prerequisiti

1. **MUST** invocare skill `huashu-design` (vedi sopra).
2. **MUST** leggere `${paths.ui_guidelines}` prima di generare qualsiasi cosa.
3. **MUST** eseguire il [Component Discovery](component-discovery.md) cascade completo.
4. **MUST** avere screenshot delle pagine reali dove la feature vivrà (context capture).

## Context Capture (obbligatorio)

Prima di generare mockup:

1. Identifica 1-3 pagine dove la feature sarà integrata o adiacente.
2. Se `npm run dev` non è in esecuzione, avvialo.
3. Usa `webapp-testing` skill (Playwright CLI) per navigare e fare screenshot. Salva in `/tmp/prd-design-<slug>/context/`.
4. Questi screenshot sono il **riferimento visivo** — i mockup DEVONO integrarsi con sidebar, header, navigazione, theming e stile dei componenti reali.
5. Se le pagine richiedono auth, usa credenziali di test (verifica `MEMORY.md` o chiedi all'utente).

## Regole di Generazione dei 3 Mockup

Produce 3 file HTML distinti con approcci di design diversi.

### Requisiti obbligatori per ogni file

- **In-context**: ogni file DEVE includere lo shell UI esistente (sidebar, header, nav) che circonda l'area della feature. Riprodurre fedelmente il chrome della piattaforma basandosi sugli screenshot catturati.
- **Contenuto nuovo nell'area principale**: chiaramente distinguibile dal chrome esistente.
- **Stili reali**: usa gli stili dei componenti visibili negli screenshot (border radius, shadow style, button style, card style, colori, spacing).
- **Pagina esistente modificata**: se la feature modifica una pagina esistente, mostra la pagina INTERA con le modifiche evidenziate (bordo tratteggiato attorno ai nuovi elementi).
- **Self-contained**: CSS inline, Tailwind CDN, nessuna dipendenza esterna.
- **Nomi file**: `option-a.html`, `option-b.html`, `option-c.html`.
- **Rationale**: commento HTML in cima a ogni file che spiega l'approccio e come si integra con la UI esistente.
- **Design philosophy**: applica `identity.design_philosophy` (es. "Neo-Brutalism", "Minimalist", "Glassmorphism") come definito in `${paths.ui_guidelines}` e nell'overlay del progetto. Se `design_philosophy` è vuoto, mantieni uno stile neutro coerente con gli screenshot.
- **Lingua**: usa `identity.language` (BCP-47) per tutti i testi UI. Default `en` se non impostato.
- **Marker**: segna aree nuove/cambiate con label floating in lingua del progetto, es. `NUOVO`/`MODIFICATO` (it) o `NEW`/`CHANGED` (en).
- **3 differenze significative**: le opzioni devono differire in layout, gerarchia o pattern di interazione — non solo in colori.

### Scheletro HTML minimo

```html
<!DOCTYPE html>
<html lang="<identity.language>">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>UI Design — <Feature Name></title>
  <script src="https://cdn.tailwindcss.com"></script>
  <style>
    html { scroll-behavior: smooth; }
  </style>
</head>
<body>
  <!-- Existing UI shell (sidebar, header, nav) reproduced from screenshots -->
  <!-- New feature content in main area -->
</body>
</html>
```

## Presentazione all'Utente

Dopo che il valutatore ha approvato (vedi [evaluation.md](evaluation.md)):

1. **Apri tutti e 3 i file nel browser di default (OBBLIGATORIO):**
   ```bash
   open /tmp/prd-design-<slug>/option-a.html
   open /tmp/prd-design-<slug>/option-b.html
   open /tmp/prd-design-<slug>/option-c.html
   ```
2. Mostra screenshot inline come supplemento.
3. Per ogni opzione, elenca solo: nome dell'approccio e quali componenti esistenti riusa vs. crea nuovi. **NON dare valutazioni, punteggi, o suggerimenti su quale opzione scegliere. La scelta spetta all'utente.**

## Iterazione su Feedback Utente

1. L'utente sceglie un'opzione o chiede modifiche.
2. Applica le modifiche all'opzione scelta, passando gli screenshot di contesto come riferimento.
3. Sottometti al valutatore per ri-valutazione.
4. Una volta approvato dal valutatore, apri nel browser e mostra screenshot.
5. Ripeti fino ad approvazione esplicita dell'utente.
