# Evaluation Phase — Criteri e Rubric per il Valutatore

> Stylistic identity (design philosophy, theming pairing rules) and project
> language resolve from `baldart.config.yml`. See
> `framework/agents/project-context.md` § 4. Project-specific stricter
> thresholds live in `.baldart/overlays/ui-design.md` § Evaluation.

Questo file definisce come valutare i mockup HTML. Il valutatore è un agente SEPARATO dal generatore (pattern GAN — ref: Anthropic "Harness Design for Long-Running Apps").

**Principio fondamentale:** chi genera non si auto-valuta. La separazione generatore/valutatore
elimina il bias sistematico di auto-approvazione.

## Ruolo del Valutatore

1. Riceve i file HTML generati (`option-a.html`, `option-b.html`, `option-c.html`).
2. Apre ciascuno in browser via Playwright (`webapp-testing` skill).
3. Prende screenshot e valuta contro i criteri sotto.
4. Produce un report strutturato con punteggi e verdetto.
5. Se FAIL: rimanda al generatore con feedback specifico.

## Criteri di Valutazione (7 dimensioni)

Ogni criterio ha un punteggio 1-5 con soglie hard.

### C1 — Context Fidelity

Lo shell UI circostante (sidebar, header, nav) e fedele alle screenshot reali della piattaforma.

| Score | Descrizione |
|-------|-------------|
| 1 | Shell completamente assente o inventato |
| 2 | Shell presente ma layout/colori significativamente diversi |
| 3 | Shell riconoscibile, alcune discrepanze di dettaglio |
| 4 | Shell fedele, differenze minori trascurabili |
| 5 | Shell indistinguibile dagli screenshot reali |

### C2 — Layout & Spacing

Spacing, allineamento, nessun overflow/clipping, proporzioni responsive.

| Score | Descrizione |
|-------|-------------|
| 1 | Overflow visibile, elementi sovrapposti, layout rotto |
| 2 | Allineamento inconsistente, spacing irregolare |
| 3 | Layout funzionale, qualche disallineamento minore |
| 4 | Layout pulito, spacing coerente, nessun overflow |
| 5 | Layout perfetto, gerarchia visiva chiara, breathing room bilanciato |

### C3 — Design System Compliance

`identity.design_philosophy` applicato secondo `${paths.ui_guidelines}` e le regole di `${paths.design_system}/` (quando `features.has_design_system: true`). Se `design_philosophy` è vuoto, valuta solo l'aderenza alle linee guida del progetto.

| Score | Descrizione |
|-------|-------------|
| 1 | Sembra un template generico, nessuna aderenza alla design philosophy |
| 2 | Tracce di philosophy ma applicazione parziale o sbagliata |
| 3 | Philosophy parziale, mix di elementi corretti e generici |
| 4 | Philosophy coerente, dettagli minori fuori spec |
| 5 | Perfettamente aderente a `${paths.ui_guidelines}` in ogni elemento |

### C4 — Typography & Readability

Gerarchia leggibile, dimensioni font corrette, nessuna riga orfana o testo tagliato.

| Score | Descrizione |
|-------|-------------|
| 1 | Testo illeggibile, gerarchia assente |
| 2 | Testo leggibile ma gerarchia piatta o inconsistente |
| 3 | Gerarchia base presente, qualche problema di peso/dimensione |
| 4 | Gerarchia chiara, font scale corretto, buona leggibilita |
| 5 | Tipografia impeccabile, gerarchia enfatizza il contenuto giusto |

### C5 — Completeness

Tutti gli elementi UI presenti e correttamente renderizzati. No icone mancanti, placeholder rotti, sezioni vuote, o lorem ipsum dove dovrebbe esserci testo reale nella lingua del progetto (`identity.language`).

| Score | Descrizione |
|-------|-------------|
| 1 | Sezioni mancanti, placeholder visibili, layout incompleto |
| 2 | La maggior parte degli elementi presenti, alcuni placeholder/mancanze |
| 3 | Tutto presente, qualche dettaglio visivamente grezzo |
| 4 | Completo e curato, tutti gli stati rappresentati |
| 5 | Ogni elemento e pixel-perfect, inclusi empty/loading/error states |

### C6 — Integration Clarity

Elementi nuovi/modificati chiaramente marcati e visivamente coerenti con gli elementi
circostanti esistenti.

| Score | Descrizione |
|-------|-------------|
| 1 | Impossibile distinguere cosa e nuovo vs esistente |
| 2 | Marker presenti ma confusi, nuovo sembra disconnesso |
| 3 | Marker chiari, integrazione visiva accettabile |
| 4 | Marker chiari, nuovo si integra naturalmente con l'esistente |
| 5 | Perfetta integrazione + distinzione: nuovo e ovvio ma coerente |

### C7 — Polish (production-readiness)

Sembra production-ready, non un wireframe grezzo. Qualcuno vedendo questo dovrebbe
pensare "e un design reale" non "e una bozza".

| Score | Descrizione |
|-------|-------------|
| 1 | Wireframe grezzo, box grigi, nessun dettaglio visivo |
| 2 | Aspetto da prototipo, manca rifinitura |
| 3 | Decente, sembra un mockup funzionale ma non rifinito |
| 4 | Curato, sembra quasi pronto per la produzione |
| 5 | Indistinguibile da un design professionale finito |

## Soglie Hard (FAIL se violate)

- **Nessun criterio sotto 2** — qualsiasi 1 = FAIL immediato
- **Media complessiva >= 3.5** — sotto = FAIL
- **C1 (Context Fidelity) >= 3** — il mockup DEVE essere in-context
- **C3 (Design System) >= 3** quando `identity.design_philosophy` è impostato — DEVE rispettare la philosophy del progetto

L'overlay del progetto può aggiungere soglie più strette (es. C3 >= 4) — vedi `.baldart/overlays/ui-design.md` § Evaluation.

## Contrast Check (MUST — ZERO TOLERANCE)

Oltre ai 7 criteri, il valutatore DEVE eseguire un check contrasto:

- Per ogni elemento con `bg-*`, verificare che esista un `text-*` esplicito
- Se `features.multi_tenant_theming: true`: themed primary bg DEVE usare il text-token accoppiato per il tenant secondo la regola di pairing del progetto (vedi `${paths.design_system}/patterns/` o overlay)
- Ratio minimo: 4.5:1 testo normale, 3:1 testo grande

Violazione contrasto = FAIL indipendentemente dai punteggi.

## Formato Report di Valutazione

Salva in `/tmp/prd-design-<slug>/evaluation-report.md`:

```markdown
# Evaluation Report — <slug>

Data: YYYY-MM-DD
Iterazione: N

## Option A — <nome approccio>

| Criterio | Score | Note |
|----------|-------|------|
| C1 Context Fidelity | X/5 | ... |
| C2 Layout & Spacing | X/5 | ... |
| C3 Design System | X/5 | ... |
| C4 Typography | X/5 | ... |
| C5 Completeness | X/5 | ... |
| C6 Integration Clarity | X/5 | ... |
| C7 Polish | X/5 | ... |
| **Media** | **X.X/5** | |
| Contrast Check | PASS/FAIL | ... |

**Verdetto: PASS / FAIL**
Feedback per il generatore: [se FAIL, cosa correggere specificamente]

## Option B — ...
(stessa struttura)

## Option C — ...
(stessa struttura)
```

## Loop di Iterazione

1. Generatore produce/aggiorna i file HTML.
2. Valutatore li apre in Playwright, screenshot, valuta.
3. Se FAIL: report con feedback → torna al generatore.
4. Se PASS: report finale → si procede con presentazione all'utente.
5. **Max 5 iterazioni per opzione.** Se ancora sotto soglia dopo 5, procedi con
   la versione migliore e annota i problemi residui nel report.
