# UI V3 Revamp — Spec operativa per FLOTTA di agenti

> **Obiettivo**: migrare l'interfaccia di NIS2 Agile dal **V2 attuale** (Bootstrap Italia, **sidebar** a sinistra) al **V3** proposto nei mockup (`docs/mockup Ui/`): **top-nav a mega-menu**, tema **navy + oro**, font **Inter**, icone **Lucide**, card/stat moderne.
> **Vincolo madre**: è un redesign **SOLO di presentazione**. Tutto il backend, l'auth, il wiring dati (`api.js`), l'help, l'i18n, ARIA e il bug-reporter **devono continuare a funzionare**. NON si tocca PHP/DB/controller.
> **Fonte di verità visiva**: i 3 mockup in `docs/mockup Ui/` (`index.html` = chrome + dashboard; `assessment.html` = pagina-modulo/GAP; `calendario.html` = app full-page). I mockup sono **mock**: NON copiarne i dati finti né la logica fittizia — ricablare sui **dati reali** via `api.js`.

---

## 0. TL;DR per chi orchestra
1. **FASE 0 (1 agente, sequenziale, foundation)** — estrarre il design system in `public/css/v3.css` + costruire la chrome condivisa `public/js/topnav-v3.js` (appbar + mega-menu, data-driven) + **self-hostare Inter e Lucide** in `/vendor` + migrare **`dashboard.html`** come pagina pilota cablata sui dati reali. **Blocca**: le altre pagine dipendono da questa.
2. **FASE 1 (flotta in parallelo, N agenti, worktree isolati)** — ogni agente migra **un gruppo IA** di pagine reali al V3 riusando `v3.css` + `topnav-v3.js`, cablando i dati reali.
3. **FASE 2 (1–2 agenti, verifica)** — smoke per pagina (200, console pulita, dati reali, auth, responsive, a11y), cache-buster, commit.
> ⚠️ **Decisione utente da confermare PRIMA della Fase 1** (vedi §7).

---

## 1. Design system V3 (estratto dai mockup — usare ESATTAMENTE)

**Token CSS** (`:root` in `public/css/v3.css`):
```css
:root{
  --navy-top:#0A2E54; --navy-nav:#103A61; --navy-hover:#1B4A75; --gold:#F0B429;
  --bg:#EFF4FA; --card:#FFFFFF; --ink:#15263C; --muted:#64748B; --line:#E3E9F0;
  --c-green:#1E8A5A; --c-blue:#1F5FA8; --c-amber:#D98324; --c-red:#C62828;
  --radius:12px; --shadow:0 1px 2px rgba(16,40,80,.06),0 8px 24px rgba(16,40,80,.06);
}
```
- **Font**: **Inter** (400–800). ⚠️ **Self-host** in `/vendor/inter/` (NO Google Fonts CDN: AGID/privacy/PWA-offline). Fallback `system-ui`.
- **Icone**: **Lucide**. ⚠️ **Self-host** lo UMD in `/vendor/lucide/lucide.min.js` (NO `unpkg` CDN: CSP/offline). Uso `<i data-lucide="...">` + `lucide.createIcons()`.
- **Focus**: `:focus-visible{outline:2px solid var(--gold)}` (a11y).

**Chrome condivisa** (sostituisce la sidebar V2): `.appbar` = `.bar-top` (flag IT, logo-mark, brand, `.search`, `.btn-incident` "Registra incidente", `.user`) + `.bar-nav` con `.nav-item > .nav-link` e dropdown `.mega` / `.mega.no-promo` (vedi `index.html` righe 196–217). Attivo: `.nav-link.active` (bordo oro sotto).

**Componenti** (classi dai mockup, da portare in `v3.css`): `.card`/`.card-pad`, `.stat` (+`.green/.amber/.blue`, `.ibox`, `.val`, `.bar`), `.badge-t` (+ varianti colore), `.btn-primary`/`.btn-ghost`/`.btn-incident`, `.sec-head`, `.page-head`/`.crumb`, `.sca`/`.act` (liste scadenze/attività), `.anag*` (anagrafica), `.doc` (documenti), `.fab-stack`/`.fab` (trittico), calendario (`.daystrip`/`.weekstrip`/`.daycell`/`.mini`/`.cal-pop` per dashboard; `.cal-app`/`.cal-main`/`.cal-side`/`.mv-grid`/`.view-switch`/`.legend` per la pagina Calendario).
**Responsive** (dai mockup): breakpoint `≤900px` (collassa griglie/mega, nasconde search) e `≤560px`.

**FAB trittico**: nel mockup sono 3 (Notifiche / Assistenza / **AI**). ⚠️ NON reinventarli: NIS2 ha già il trittico cablato in `common.js` (campana notifiche + bug-reporter widget + **ARIA** chat con voce/puntatore/dati). Il V3 deve **riusare** quei FAB reali (eventualmente ri-stilarli), non i bottoni statici del mockup.

---

## 2. Architettura tecnica della migrazione (CRITICA)

Oggi (V2) ogni pagina carica: `common.js` (helper: auth `checkAuth`, `showModal`, `showNotification`, `escHtml`, FAB ARIA+bug-reporter, org-switcher) → `api.js` (client REST) → bundle Bootstrap Italia → **`common-bi.js`** (`loadSidebar()` = sidebar V2) → `i18n.js` → `help.js` → `<pagina>.js`.

Il V3 **sostituisce solo la CHROME** (sidebar → top-nav) e il **CSS**, **riusando tutti gli helper**. Strategia:
- **`public/css/v3.css`** — design system completo (token + chrome + componenti). Sostituisce/affianca `style.css` sulle pagine V3.
- **`public/js/topnav-v3.js`** — renderizza l'appbar + mega-menu (come `common-bi.js` fa per la sidebar), **data-driven** da un array `navGroups` (la mappa IA §6), con `aria-current` sul gruppo attivo, ed espone gli stessi hook usati a init (`window.loadSidebar` può essere ridefinito a `loadTopnav`, così le pagine non cambiano l'init). Riusa org-switcher/utente/logout/versione da `common.js`.
- **Per pagina**: nuovo `<head>` (Inter+Lucide self-host + `v3.css`), nuovo **markup** (struttura dal mockup), ma **stessi script** `common.js`/`api.js`/`i18n.js`/`help.js`/`<pagina>.js` **+ `topnav-v3.js` al posto di `common-bi.js`**. Il `<pagina>.js` resta quello reale (dati veri); si adatta solo il markup/i selettori se necessario.
- **Help/ARIA**: aggiornare `help.js` (`_pageMap` invariato) e `AIService::navigationMapBlock` **solo se** cambiano i nomi delle voci di menu (la nuova IA li raggruppa: vedi §6 — riconciliare con la mappa ARIA, che oggi riflette le sezioni sidebar). Vedi memoria `project_aria_chat_wiring`.

> Conseguenza: **non si butta `<pagina>.js`** (è il wiring reale). Si rifà il guscio HTML + la chrome. Questo è ciò che rende parallelizzabile per pagina.

---

## 3. FASE 0 — Foundation (1 agente, sequenziale, NO parallelo)
Deliverable (in un solo commit, pagina pilota verificata):
1. `public/css/v3.css` con token + chrome + tutti i componenti dei mockup.
2. `public/js/topnav-v3.js` (appbar + mega-menu data-driven, riusa helper common.js, `aria-current`, responsive/mobile toggle).
3. Self-host **Inter** (`/vendor/inter/`) e **Lucide** (`/vendor/lucide/lucide.min.js`) + relativi `@font-face`/`<script>` locali (no CDN).
4. **`dashboard.html` migrata** end-to-end al V3, **cablata sui dati reali** (`api.js`: overview/score/deadlines/recent-activity ecc., stati loading/empty/error), con il **trittico FAB reale** (ARIA/bug-reporter/notifiche) e l'help "?".
5. La **mappa IA** §6 finalizzata in `topnav-v3.js`.
**Acceptance F0**: dashboard 200, console pulita, dati reali, nav attivo, responsive ≤900/≤560, a11y focus/contrasto, `node --check` su `topnav-v3.js`. Commit `[FEAT] UI V3 — foundation + dashboard pilota`.

---

## 4. FASE 1 — Migrazione pagine (flotta in parallelo)
- **1 agente per GRUPPO IA** (§6), in **worktree isolato** (`isolation: worktree`) per evitare conflitti su file condivisi.
- Ogni agente, per ogni pagina del suo gruppo: rifà `<head>` + markup V3 (dal pattern della dashboard pilota + dai mockup `assessment.html`/`calendario.html` per i pattern modulo/app), aggancia `topnav-v3.js` + `v3.css`, **mantiene il `<pagina>.js` reale** (adatta i selettori se il markup cambia), verifica i dati reali.
- **NON** inventare endpoint: usare quelli già in `api.js`. Se manca un dato che il mockup mostra, renderlo "—"/placeholder, non fingerlo.
**Acceptance F1 per pagina**: vedi §8.

---

## 5. FASE 2 — Verifica & rilascio (1–2 agenti)
- Smoke ogni pagina su prod: 200, console JS pulita, dati reali caricano, `checkAuth`, i18n IT/EN, help "?", trittico FAB, responsive, a11y (focus/contrasto/aria), nessun CDN esterno (CSP/PWA).
- **Cache-buster** `?v=` aggiornato su tutte le pagine che referenziano `v3.css`/`topnav-v3.js`/`common.js` modificati (la propagazione JS/CSS statica è via bind-mount; **nessun USR2** perché non si toccano `.php`).
- Aggiornare `sw.js` (cache shell V3) + bump nome cache; `manifest` theme-color resta `#0066CC` o si valuta il navy (decisione utente).

---

## 6. Mappa IA (gruppi mega-menu → pagine reali)
Dal mockup `index.html`. Riconciliare con TUTTE le ~30 pagine reali; le pagine **non presenti nel mockup** sono marcate ➕ e vanno collocate dalla flotta (proposta tra parentesi).
- **Dashboard** → `dashboard.html`
- **Calendario** → `calendario.html`
- **Stakeholders** (mega): `stakeholders.html` · `supply-chain.html` · `stakeholder-activities.html`
- **Struttura interna** (mega): `organigramma.html` · `competenze.html` · GAP Analysis `assessment.html` · `training.html`
- **Rischi** (mega): Mappa rischi `risks.html` · Inventario `assets.html` · `policies.html` · ➕ Connettori Discovery `connettori-discovery.html` (Inventario/Operativo)
- **Monitoraggio** (mega): Segnalazioni `whistleblowing.html` · `internal-audits.html` · Audit ACN `reports.html` · ➕ `controlli-periodici.html` · ➕ Riesame di Direzione `management-review.html`
- **Lex e ISO** (mega): `normative.html` · Modello SGSI `isms.html` · `misure-requisiti.html`
- **AI** (mega): `cross-analysis.html` · `kb.html`
- **Guida** (mega): `guida.html` · `integrazioniext.html` · Impostazioni `settings.html` · `architecture.html` · ➕ `simulate.html`
> ➕ da decidere: `companies.html` (consulente), pagine admin (`admin/*`). Pagine **pubbliche** (`index.html` landing, `login/register/onboarding`, `segnala-anonimo.html`) **NON** ricevono la chrome top-nav (restano pubbliche).

---

## 7. ⚠️ Decisioni da confermare con l'utente PRIMA della Fase 1
1. **Big-bang vs graduale**: il V3 **sostituisce** il V2 su tutte le pagine in un'unica ondata, oppure convive **dietro flag** (es. `?ui=v3` / preferenza utente) durante la transizione? (Consigliato: pagina pilota + rollout graduale per gruppo, non big-bang.)
2. **Sidebar → top-nav su tutto**: confermare l'abbandono della sidebar V2 (è cambio di IA e di abitudini per gli utenti già formati).
3. **Brand/temi**: il navy/oro sostituisce il blu Italia `#0066CC`? Impatta `theme-color`/manifest/AGID (Bootstrap Italia è un requisito AGID per la PA — verificare che il target NIS2 lo consenta; vedi memoria `project_bootstrap_italia_rollout`).
4. **i18n**: i mockup sono solo IT — il V3 deve mantenere il toggle IT/EN (`i18n.js`).

---

## 8. Acceptance criteria PER PAGINA (Fase 1)
- [ ] Chrome V3 (appbar + mega-menu) presente; gruppo/voce attiva corretta (`aria-current`).
- [ ] **Dati REALI** via `api.js` (zero mock); stati **loading / empty / error** gestiti.
- [ ] `checkAuth` (auth + redirect login) funzionante; i18n IT/EN; help "?"; **trittico FAB reale** (ARIA + bug-reporter + notifiche).
- [ ] Responsive ≤900 e ≤560; a11y WCAG 2.1 AA (focus-visible, contrasto, touch ≥44px, aria-label, zoom non bloccato).
- [ ] Nessun CDN esterno (Inter/Lucide self-host); CSP/PWA ok.
- [ ] `node --check` sui JS toccati; pagina **200**; console pulita.
- [ ] Cache-buster `?v=` aggiornato.

---

## 9. Guardrail VINCOLANTI (per ogni agente)
- **Solo UI**: NON toccare PHP/controller/DB/migrazioni/api.js (a meno di aggiungere metodi mancanti, da concordare). Il wiring dati è quello esistente.
- **Riusare** gli helper di `common.js` (auth, modal, notify, FAB ARIA/bug-reporter, org-switcher) — non duplicarli.
- **Self-host** font/icone (no CDN: CSP, offline-PWA, privacy, AGID).
- **Lock** `/tmp/agent-working.lock` mentre si lavora (il supervisore cron lo rispetta e salta). Rimuoverlo a fine lavoro.
- **Worktree isolation** per gli agenti paralleli (Fase 1).
- **Commit chirurgico** per batch: `[FEAT] UI V3: <gruppo/pagina>` + footer `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`. `git push origin main` (helper vault dal devenv) — sequenziale tra worktree per evitare race sul push.
- **Deploy**: HTML/JS/CSS statici → live via bind-mount + cache-buster, **nessun USR2** (solo se si toccasse un `.php`, qui no). Reload host non necessario per sola UI.
- **A11y/AGID**: mantenere o migliorare il livello attuale (Bootstrap Italia era conforme AGID; il V3 deve restare WCAG 2.1 AA).
- **Verità, non finzione**: se un dato del mockup non esiste nel backend, mostrarlo come placeholder/empty, non inventarlo.

---

## 10. Orchestrazione consigliata
- **FASE 0**: 1 agente (sequenziale). Output = foundation + dashboard pilota. *Gate manuale*: l'utente valida la pilota prima di aprire la flotta.
- **FASE 1**: `Workflow`/`Agent` con `isolation: worktree`, **1 agente per gruppo IA** (§6) → ~8 agenti paralleli. Ogni agente legge: questo spec + i 3 mockup + la dashboard pilota (pattern) + il `<pagina>.js` reale.
- **FASE 2**: 1–2 agenti di verifica + sweep cache-buster + `sw.js`.
- Riferimenti memoria: `project_bootstrap_italia_rollout` (il V2 attuale è BI), `project_aria_chat_wiring` (nav-map ARIA da riconciliare), `reference_jsonpaginated_contract` (contratto liste), `project_prod_topology_host_fpm` (deploy).

> **Nota**: questo è il **piano**. Lanciare la flotta solo dopo le decisioni §7. Per partire in sicurezza: eseguire **solo la FASE 0** (foundation + pilota), revisionare, poi aprire la Fase 1.