# ThothII: survey e piano di revisione grafica

Data: 12 settembre 2026. Stato: **proposta, da approvare; nessuna modifica all'interfaccia**.

## Sintesi e direzione consigliata

L'incoerenza segnalata è confermata. Non dipende soltanto da dettagli sfuggiti nelle singole pagine: il design system attuale prescrive tre registri tipografici, ai quali alcuni componenti aggiungono un secondo stack serif. Titoli, etichette operative, documenti e istruzioni finiscono così per sembrare parti di prodotti diversi.

Propongo una direzione unica: **interfaccia operativa interamente sans-serif, rosso istituzionale come accento, colori aggiuntivi soltanto quando comunicano uno stato, maggiore coerenza senza impoverire le informazioni**. Non serve una nuova impaginazione del Core né una nuova collocazione delle sessioni.

Ho usato **Impeccable**, nel registro product, per orientare la valutazione di gerarchia, tipografia, densità, colore e microcopy. La varietà visiva dovrà venire da spaziatura, pesi e organizzazione, non dall'alternanza di famiglie tipografiche. Le grazie non sono intrinsecamente incompatibili con un prodotto tecnologico, ma qui contrastano con la direzione richiesta e non svolgono una funzione necessaria: le eliminerei dalla UI, compresi i lettori di documenti.

## 1. Metodo, copertura e limiti

Verifica tramite Playwright nel browser dell'app, con screenshot, navigazione e lettura degli stili CSS calcolati. La survey principale riguarda la **versione Docker reale su `http://127.0.0.1:8080/`**, autenticata con l'account autorizzato. Una precedente esplorazione dell'anteprima sintetica non è usata come prova dei dati o del funzionamento del Docker.

| Area | Verifica sulla versione reale |
| --- | --- |
| Workspace | Preparation, Specific actions, About, Authentication |
| Database | Elenco database, navigazione alle tabelle e alle colonne |
| Memory | Elenco vuoto e apertura del form New card, chiuso senza modifiche |
| Evidence | Fonti/importazione, elenco, dettaglio di un documento |
| Pi | Runtime e Host maintenance, scheda macOS |
| Core | Stato iniziale, compositore e controlli presenti senza avviare una domanda |
| Sessioni | My sessions, All sessions, archivio e lettura di una sessione archiviata |
| Navigazione | Drawer responsive, accessi Admin e contesto globale |

Non ho salvato form, lanciato elaborazioni, ripreso sessioni, importato documenti o modificato configurazioni. Il controllo del Core attivo, delle fasi, dei gate e del log è limitato alla lettura del codice: non è stato eseguito un ciclo LLM per una survey grafica.

Il viewport misurato nel pannello browser era **649 × 1091 CSS px**. Questo offre evidenza concreta del comportamento a larghezza ridotta, ma non sostituisce una matrice desktop/mobile. Tema scuro, contrasto numerico, navigazione completa da tastiera, zoom e integrazione effettiva in Omics Portal restano da verificare. Non è una certificazione WCAG né un audit automatizzato completo. Le famiglie riportate sono gli stack CSS calcolati, non una verifica del font effettivamente caricato dal sistema.

## 2. Problemi riscontrati

### Tipografia: quattro stack e gerarchie variabili

| Esempio osservato | Trattamento attuale | Problema |
| --- | --- | --- |
| Titoli delle pagine Admin | Fraunces/serif, 30 px | Registro editoriale molto più marcato del resto dell'app |
| Sources and imports; titolo del form Memory | Altro stack `ui-serif`, 18–20 px | Nemmeno i titoli serif usano tutti la stessa famiglia |
| Evidence library; Original question; Revised question | Monospace, 11 px | Etichette ordinarie trattate come identificatori tecnici |
| Working context | Monospace maiuscolo, 10 px | Informazione globale importante resa molto piccola |
| Guida Pi Host maintenance | Testo 12 px, interlinea 16 px; titoletti serif 12 px | Istruzioni lunghe troppo dense e gerarchia debole |
| Sessione archiviata | Titolo sessione serif 14 px; titolo nel documento serif 23,2 px | Il contenuto sovrasta il contesto del pannello |

La causa è documentata in `DESIGN.md`, nella regola dei tre registri. Nel codice, `frontend/src/index.css` assegna globalmente il font heading a `h1`–`h6` e ai titoli della prosa; Memory ed Evidence aggiungono classi `font-serif`. Il problema ricompare quindi anche quando un componente non richiede esplicitamente un titolo decorativo.

### Colore: troppi significati impliciti

- In Database il tipo di connessione REST e la data di aggiornamento ricevono accenti blu pur essendo informazioni ordinarie.
- La guida ordinaria di manutenzione Pi è racchiusa in una cornice ambra, visivamente simile a un avviso. Il colore non distingue un pericolo concreto.
- Gli stati Ready in Pi usano anche testo verde molto chiaro: è un rischio di leggibilità da misurare, non una violazione numericamente accertata in questa survey.
- Stato operativo, azione primaria, contenitore informativo e semplice categoria non seguono una grammatica cromatica sufficientemente riconoscibile.

Non eliminerei invece indiscriminatamente verde e ambra: successo, errore, attesa di revisione e avvertimento devono restare distinguibili, sempre anche tramite testo o icona.

### Spazio e linguaggio

| Area | Evidenza | Intervento proposto |
| --- | --- | --- |
| Workspace | Identità e descrizioni ripetute fra contesto, selezione e intestazioni; molte gerarchie prima delle azioni | Mantenere le quattro schede, ridurre ripetizioni e uniformare sezioni e azioni |
| Database | Intestazione, stato, cronologia, Fleet summary, breadcrumb e toolbar precedono i dati; a 649 px il riepilogo occupa più righe | Compattare il riepilogo, dare priorità alla griglia; sostituire il gergo Fleet con un nome corrispondente al suo ambito |
| Memory | Stato vuoto formulato come assenza di risultati filtrati anche senza carte; ampie aree vuote e paginazione disabilitata | Distinguere libreria vuota da ricerca senza risultati; stesso linguaggio visivo di toolbar e form del resto dell'Admin |
| Evidence | Percorso tecnico e istruzioni di importazione dominano la parte superiore; ricerca compressa rispetto agli altri filtri | Istruzioni brevi con dettagli espandibili; percorso secondario ma copiabile; filtri che si dispongono su più righe prima di diventare illeggibili |
| Pi | Guida molto lunga e piccola; spiegazioni dell'architettura mescolate con istruzioni all'operatore | Separare stato, azioni e guida; rendere la guida leggibile e consultabile per attività |
| Sessioni | Molti registri tipografici; a 649 px il pannello documenti è stretto e tronca il titolo | Coerenza dei titoli e dei documenti; adeguare il pannello alla larghezza disponibile senza cambiare la gestione delle sessioni |
| Core e navigazione | Branding ripetuto, microetichette e controlli di taglie diverse | Riallineare la gerarchia e i componenti condivisi, conservando struttura e comportamento |

Gli stili comunicativi oscillano fra introduzione promozionale nel Core, manuale tecnico in Pi/Evidence e terminologia da dashboard infrastrutturale in Database. La soluzione è un tono operativo unico, non la rimozione delle informazioni tecniche necessarie.

## 3. Regole del sistema visivo proposto

### Una famiglia UI, cinque ruoli dimensionali

Consiglio di **mantenere Manrope**, già adottato per l'interazione, e usarlo per tutta la UI. Non aggiungerei una nuova famiglia per il solo gusto di cambiare. Pesi ordinari 400, 500 e 600; monospace soltanto per SQL, codice, percorsi e identificatori quando serve riconoscerli o copiarli.

| Ruolo | Dimensione proposta | Uso |
| --- | --- | --- |
| Titolo pagina | 24 px / 1,5 rem, peso 600 | Core/Admin, senza effetto copertina |
| Titolo sezione | 20 px / 1,25 rem, peso 600 | Sezioni principali e pannelli di lettura |
| Lettura | 16 px / 1 rem, peso 400 | Risposte, documenti, istruzioni articolate; interlinea circa 1,5 |
| Interazione e dati | 14 px / 0,875 rem, peso 400–600 | Form, tab, pulsanti, griglie; sottosezioni compatte in peso 600 |
| Metadati secondari | 12 px / 0,75 rem, peso 400–500 | Timestamp, conteggi e indicazioni accessorie |

Sono ruoli, non l'obbligo di rendere ogni titolo di sezione grande: una sottosezione compatta può usare il ruolo da 14 px in semibold. Niente ridimensionamento fluido che faccia oscillare continuamente i caratteri con la larghezza. Prima si riorganizza il layout, poi si valutano eccezioni documentate.

Ulteriori regole:

- Eliminare Fraunces e le classi serif dall'interfaccia e dalla resa dei documenti. Non riscrivere il contenuto dei documenti.
- Usare etichette sans-serif in sentence case; limitare maiuscole e spaziatura espansa.
- Nessun testo operativo ordinario sotto 12 px; non far stare più contenuto riducendolo a 8–11 px.
- Numeri tabulari nelle colonne numeriche; testo libero proporzionale; codice monospace leggibile.
- Distribuire il font con l'app, evitando che Google Fonts sia necessario alla coerenza della UI in un ambiente intranet. Verificare fallback e caricamento, senza presumere che oggi il font remoto non funzioni.

### Palette: neutri e rosso, con eccezioni semantiche

| Ruolo | Regola |
| --- | --- |
| Superfici | Bianco e pochi grigi neutri, bordi leggeri; niente colorazione per ogni sezione |
| Testo | Grafite per testo principale, grigio leggibile per secondario |
| Rosso istituzionale | Azione primaria, selezione e focus; tonalità coerente con il tema Omics, da verificare nell'integrazione |
| Successo | Indicatore verde sobrio con testo sufficientemente scuro; non interi paragrafi verde pallido |
| Avvertimento/attesa umana | Ambra soltanto quando occorre attenzione, con motivazione esplicita |
| Errore/distruzione | Trattamento distinto tramite icona, etichetta e conferma dove prevista; non affidarsi al solo rosso condiviso con il brand |
| Informazioni ordinarie | Neutre: timestamp, protocollo, conteggi, guide e configurazione non sono automaticamente stati colorati |

SQL, grafici e visualizzazioni possono mantenere colori utili alla comprensione dei dati. Questa revisione non impone un monocromo indiscriminato. Gli stati del workflow conserveranno il loro significato; ogni modifica cromatica dovrà avere una mappatura esplicita.

### Componenti e testi condivisi

- Un'unica famiglia di intestazioni Admin, toolbar, tab, campi, pulsanti, badge e messaggi.
- Scala di spaziatura comune basata su multipli di 4 px, con distinzione chiara fra spazio dentro un gruppo e spazio fra gruppi.
- Una primaria per il compito locale; azioni secondarie neutre, pericolose riconoscibili senza rendere tutto rosso.
- Tab allo stesso livello con lo stesso trattamento. Le schede OS di una guida possono essere più compatte, ma non appartenere a un altro sistema grafico.
- Istruzione essenziale accanto all'azione; procedure e dettagli di implementazione in una sezione di aiuto espandibile.
- Testi UI in inglese; documenti e dati conservano la propria lingua. I titoli italiani di Evidence e sessioni non sono un errore di uniformità.

Esempi di microcopy da affinare nell'implementazione:

| Attuale | Proposta |
| --- | --- |
| Fleet summary | Catalog summary, se confermato l'ambito del riepilogo |
| No cards match these filters… in una libreria vuota | No memory cards yet. Create a card to add reusable knowledge. |
| Session models in Pi | Available models, con indicazione dell'effettiva idoneità Core/Admin |
| Spiegazione che la pagina “never creates a second model default” | Installation default, con breve indicazione di dove modificarlo e dettagli tecnici separati |

Il pulsante che prova il default d'installazione deve continuare a dichiarare **quale modello testa**: non va confuso con il modello selezionato nel contesto globale. Anche la distinzione fra importazione, revisione e consolidamento Evidence deve rimanere esplicita.

## 4. Vincoli funzionali e integrazione

La revisione deve conservare:

1. Core originale: domanda/risposta, otto fasi in alto, gate di revisione, log sul lato sinistro e controlli esistenti.
2. Sessioni nella navigazione destra con **My sessions / All sessions**, archivio e azioni attuali. Nessuna sezione sostitutiva in fondo alla pagina.
3. Contesto globale A espandibile in alto: workspace e modello unici per tutta l'app; scelte ricordate indipendentemente e default esistenti.
4. Blocco delle attività senza contesto valido e del cambio contesto durante un'elaborazione; protezione delle modifiche Admin non salvate.
5. Cinque pagine Admin, preprocessing in Workspace Preparation e gestione database/tabelle/campi/relazioni in Database.
6. Unificazione già realizzata della configurazione LLM, senza introdurre selettori o default alternativi.
7. Prototipi precedenti conservati e recuperabili.

**Omics Portal possiede header rosso e sidebar sinistra.** ThothII non deve duplicarli. Le regole globali attuali su `:root`, `body` e titoli richiedono una verifica di isolamento: se l'integrazione avviene nello stesso DOM, gli stili vanno circoscritti alla radice ThothII; se avviene in iframe, vanno verificati dimensionamento, tema e scrolling. È un rischio di integrazione da verificare, non una sovrapposizione già osservata sul portale.

A larghezze ridotte pannelli e filtri devono adattarsi alla larghezza del contenitore reale, non soltanto della finestra. Nel lettore della sessione il testo non dovrebbe restare confinato in una colonna di circa 195 px come nello screenshot a 649 px: prevedere un pannello più ampio o sovrapposto nella modalità compatta, mantenendo accessi e funzione originali.

## 5. Sequenza di lavoro proposta

### Fase 1: regole e campione rappresentativo

Dopo approvazione, aggiornare `DESIGN.md` eliminando la regola dei tre registri e allineando gli eventuali riferimenti superati ai modelli e alla navigazione. Definire token tipografici, colori semantici e componenti comuni.

Applicare un primo campione a **Workspace e Pi**: insieme verificano form, stato operativo, selezioni, istruzioni lunghe e codice. Mostrare il confronto prima/dopo mantenendo stessi contenuti e viewport. Non servono tre nuovi design alternativi: serve validare un sistema coerente.

### Fase 2: shell e tutte le pagine Admin

Uniformare contesto globale, navigazione, titoli, tab e controlli; estendere il sistema a Database, Memory ed Evidence. Compattare riepiloghi e istruzioni senza eliminare funzionalità. Correggere stati vuoti, larghezze dei filtri e formattazione dei blocchi di codice nella guida Pi.

### Fase 3: Core, documenti e sessioni

Applicare gli stessi token a compositore, fasi, log, widget di revisione, documenti e navigazione sessioni. Nessuna nuova struttura del workflow. Controllare separatamente liste, documento aperto, sessione attiva e pannelli nella modalità compatta.

### Fase 4: verifica e consegna

Eseguire typecheck, test dei componenti interessati e regressione Playwright con dati di test, senza consumare chiamate LLM reali soltanto per verificare gli stili. Includere prove di flusso per navigazione con modifiche non salvate e blocco del contesto durante un'operazione.

Preparare screenshot comparabili e verifiche a 390, 649, 768, 1280 e 1600 px, oltre alla larghezza effettiva assegnata da Omics con sidebar presente. Verificare tema chiaro/scuro, zoom 200%, tastiera, focus, testo lungo, stato vuoto/errore/caricamento e griglie larghe. L'integrazione finale nel server resta una fase distinta, secondo le decisioni già prese.

## 6. Criteri di accettazione

- Una sola famiglia sans per la UI; monospace solo per contenuto tecnico. Nessuna classe serif residua nei componenti operativi o nei lettori.
- Dimensioni e pesi derivati dai ruoli condivisi; ogni eccezione ha un motivo documentato.
- Colori dei componenti da token semantici; nessun blu decorativo per date o protocolli e nessuna cornice di warning intorno a una guida ordinaria.
- Contrasto del testo almeno 4,5:1, salvo le eccezioni previste per testo grande e altri casi specifici; non assumere che ogni semibold sia testo grande. Riferimento: [W3C, Contrast Minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html).
- Contrasto almeno 3:1 per informazioni visive necessarie a identificare controlli e stati, nei casi applicabili; non è un obbligo per ogni bordo decorativo. Riferimento: [W3C, Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html).
- Stato e azione distinguibili anche senza colore; focus visibile e controlli utilizzabili da tastiera.
- Nessuna sovrapposizione o scroll orizzontale dell'intera pagina ai viewport concordati; scroll locale consentito per tabelle e codice quando necessario.
- Nessuna regressione funzionale di Core, sessioni, Admin, selezione globale o salvataggio; test dei flussi critici invariati o rafforzati.
- Nessuna modifica del contenuto scientifico, dei default LLM, delle autorizzazioni o delle procedure di manutenzione mascherata da intervento grafico.

## 7. Punti principali del codice interessati in una futura implementazione

- `DESIGN.md`: regole tipografiche e cromatiche.
- `frontend/index.html`: caricamento delle famiglie di caratteri.
- `frontend/src/index.css`: token, titoli globali, etichette e prosa.
- `frontend/src/shell/WorkingContextShelf.css`: contesto globale e microtipografia.
- `frontend/src/shell/administration/AdministrationPage.css`: intestazioni comuni.
- `frontend/src/shell/WorkspaceManager.css`: gerarchie e densità Workspace.
- `frontend/src/shell/database-management/FleetLedgerShell.css`: riepiloghi, toolbar e griglie.
- Componenti Memory/Evidence: override serif di titoli e form.
- Componenti Pi: guida, stati, tab OS e microcopy operativo.
- Componenti Core/sessioni: fasi, lettura documenti, log, navigazione e pannelli responsive.

**Decisione richiesta:** approvare questa direzione visiva e il campione Workspace/Pi prima di estenderla. Questa survey non crea ticket, non aggiorna il design normativo e non ricostruisce Docker.