# Design UI
> **Stato:** completa · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.3.0 (milestone M3)
> **Pagina per chi sviluppa** · **Specifica:** SPEC §10 (in particolare §10.1, §10.6, §10.7, §10.8), Appendice A
Questa pagina è il riferimento visivo per chi sviluppa l'interfaccia di Khaemhat: come si usano i mockup, i token di
design `--kh-*`, i temi, la corrispondenza tra le classi CSS dei mockup e i componenti Razor `Kh*`, le regole di
accessibilità e localizzazione. L'indice delle schermate è nella pagina [Mockup](Mockup).
File di riferimento nel repository:
- [`docs/mockups/mockup.css`](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/docs/mockups/mockup.css) — token e classi dei componenti usati per disegnare le schermate;
- [`docs/mockups/png/`](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/docs/mockups/png) — schermate ad alta risoluzione (23 + galleria);
- [`docs/mockups/thumbs/`](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/docs/mockups/thumbs) — miniature di tutte le 88 schermate;
- [`docs/SPEC.md`](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/docs/SPEC.md) §10 e Appendice A.
## I mockup sono la specifica
Regole vincolanti (SPEC §10.1):
1. Prima della milestone 3 si legge `mockup.css` **per intero** e si guardano almeno le schermate 004, 006, 007, 008,
012, 014, 020, 021, 024, 040, 064, 078, 084. Le classi si riproducono come componenti Razor **con gli stessi nomi
semantici**: `toolbar.icons`, `ib`, `ctx`, `dochead`, `fgroup`, `panel`, `form`/`f`, `grid`, `badge`, `tile`,
`widget`, `tabs`, `dialog`, `drawer`, `kanban`, `timeline`, `tree`, `cal`, `att`, `strip`, `vsteps`.
2. `src/Khaemhat.Web/wwwroot/css/tokens.css` nasce da `mockup.css`: **stessi nomi e valori** dei token (temi, otto
accenti, densità). I nomi non si cambiano; si aggiungono token solo se servono.
3. I dati visibili nelle schermate sono esempi del seed demo: non vanno nel markup.
4. Le maschere senza mockup si compongono con i mattoni della schermata più simile: tutte le **tabelle di base**
seguono 012 + 076, tutti i **documenti** seguono 020 / 021.
5. **Ogni cambiamento visivo aggiorna lo screenshot corrispondente e questa pagina nella stessa unità di lavoro.**
Solo 23 schermate sono disponibili in alta risoluzione; per le altre si lavora dalla miniatura, da `mockup.css` e
dalla descrizione in SPEC §10-§12 (emendamento E4 in `CLAUDE.md`). Gli screenshot reali in `docs/wiki/img/`
affiancano i mockup nelle pagine della wiki: dalla versione 0.3.0 ci sono la shell, la dashboard, il profilo, l'aiuto,
le notifiche, il documento di prova con allegati e storico e l'anteprima di stampa.
Gli screenshot si rifanno su un'istanza nuova (database SQLite vuoto, azienda DEMO, tema chiaro, finestra
1440x900, telefono 390x844), così non mostrano dati o notifiche di prova; i nomi dei file sono quelli usati dalle
pagine, ad esempio `interfaccia-home.png` o `allegati-pannello.png`.

*Khaemhat 0.3.0 — i mattoni di 020 e 021 dal vero: toolbar a icone, intestazione documento, schede interne, griglia delle righe.*

*Khaemhat 0.3.0 — la dashboard con tema scuro e accento Nilo.*
## Token di design
Tutti i token hanno il prefisso `--kh-` e sono definiti su `:root`.
| Gruppo | Token | Valori (tema chiaro) |
|---|---|---|
| Caratteri | `--kh-font`, `--kh-mono` | `"Inter", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif` · `"JetBrains Mono", "Cascadia Mono", "DejaVu Sans Mono", monospace` |
| Dimensioni testo | `--kh-fs`, `--kh-fs-sm`, `--kh-fs-lg`, `--kh-fs-xl` | 13px · 11.5px · 15px · 20px |
| Raggi | `--kh-radius`, `--kh-radius-lg` | 6px · 10px |
| Shell | `--kh-topbar-h`, `--kh-tabs-h`, `--kh-status-h`, `--kh-sidebar-w` | 46px · 36px · 24px · 228px |
| Ritmo | `--kh-gap`, `--kh-row-h` | 12px · 30px |
| Ombre | `--kh-shadow`, `--kh-shadow-lg` | ombra leggera dei pannelli · ombra di finestre e cassetti |
| Marchio | `--kh-brand`, `--kh-brand-deep`, `--kh-papyrus` | `#C8962E` · `#8B6318` · `#F1E6C8` |
| Semantici | `--kh-ok`, `--kh-warn`, `--kh-err`, `--kh-info` (+ `-soft`) | `#1E8E5A` · `#C27A1A` · `#C2453A` · `#1F5FA8` |
| Accento | `--kh-accent`, `--kh-accent-strong`, `--kh-accent-soft`, `--kh-accent-text` | dipendono da `data-accent` e dal tema |
| Superfici | `--kh-bg`, `--kh-surface`, `--kh-surface-2`, `--kh-surface-3` | `#F3F5F8` · `#FFFFFF` · `#F8FAFC` · `#EEF2F6` |
| Bordi | `--kh-border`, `--kh-border-strong` | `#DDE3EA` · `#C5CDD7` |
| Testo | `--kh-text`, `--kh-text-2`, `--kh-text-3` | `#1E2733` · `#5B6776` · `#8A95A3` |
| Barra superiore | `--kh-topbar`, `--kh-topbar-text`, `--kh-topbar-muted` | `#17243A` · `#E8EDF5` · `#9FB0C8` |
| Menu e campi | `--kh-sidebar`, `--kh-input`, `--kh-input-ro` | `#FFFFFF` · `#FFFFFF` · `#F3F5F8` |
| Righe griglia | `--kh-row-alt`, `--kh-row-hover`, `--kh-row-sel` | `#FAFBFD` · `#F1F5FB` · `var(--kh-accent-soft)` |
Tema scuro (`data-theme="dark"`): superfici `#12161C` / `#1B2028` / `#20262F` / `#262D37`, bordi `#2E3744` /
`#3C4756`, testo `#E7ECF2` / `#A5B0BD` / `#73808F`, barra superiore `#0E131A`, menu `#171C23`, campi `#12161C` (sola
lettura `#1B2028`), righe `#1E242D` / `#252D38` / selezione `#24354D`; varianti `-soft` dei semantici scurite
(`#163B2A`, `#3E2E13`, `#44201D`, `#1C2F4A`) e ombre più dense.
### Gli otto accenti
Ogni accento definisce quattro token. Valori come in `mockup.css` (`accent` · `strong` · `soft` · `text`):
| `data-accent` | Nome UI | Tema chiaro | Tema scuro |
|---|---|---|---|
| `nilo` (predefinito) | Nilo | `#1F5FA8` · `#174A85` · `#E3ECF8` · `#174A85` | `#4C8EDB` · `#6AA3E6` · `#1C2F4A` · `#8DB8EE` |
| `lapislazzuli` | Lapislazzuli | `#3F51B5` · `#303F9F` · `#E6E9F7` · `#303F9F` | `#7986CB` · `#9FA8DA` · `#232A4D` · `#AAB3E6` |
| `malachite` | Malachite | `#1E8E5A` · `#167347` · `#DDF3E6` · `#167347` | `#3DBB7E` · `#62CC97` · `#163B2A` · `#8ADBB1` |
| `turchese` | Turchese | `#0F8A96` · `#0B6D77` · `#D9F0F2` · `#0B6D77` | `#30B4C1` · `#5BC8D3` · `#143A3E` · `#8EDBE3` |
| `ocra` | Ocra | `#C27A1A` · `#9A6013` · `#FBEFD9` · `#8B5511` | `#E09A3A` · `#EBB266` · `#3E2E13` · `#F0C27A` |
| `corniola` | Corniola | `#C2453A` · `#9E362D` · `#FADEDC` · `#9E362D` | `#E0665A` · `#EA8A80` · `#44201D` · `#F0A39B` |
| `ametista` | Ametista | `#7E57C2` · `#65449C` · `#ECE4F8` · `#65449C` | `#A98BE0` · `#BFA8EA` · `#2E2345` · `#CBB8F0` |
| `grafite` | Grafite | `#4B5563` · `#374151` · `#E5E7EB` · `#374151` | `#9CA3AF` · `#B9C0CC` · `#2A3038` · `#C9D0DA` |
## Temi, accenti e densità
Le preferenze dell'utente (vedi [Preferenze utente](Preferenze-utente)) sono salvate in `user_settings` e applicate
con tre attributi sull'elemento radice ``:
| Attributo | Valori | Note |
|---|---|---|
| `data-theme` | `light`, `dark`, `high-contrast`; `auto` risolto in `light` o `dark` | `auto` segue `prefers-color-scheme`; prima del login vale il tema di sistema |
| `data-accent` | `nilo`, `lapislazzuli`, `malachite`, `turchese`, `ocra`, `corniola`, `ametista`, `grafite` | i selettori combinano tema e accento (`[data-theme="dark"][data-accent="…"]`) |
| `data-density` | `compact` (assente = comoda) | compatta: `--kh-row-h: 26px`, `--kh-fs: 12.5px`, `--kh-gap: 8px` |
Altre preferenze di presentazione: dimensione del testo, carattere numerico tabellare (`.num` usa già
`font-variant-numeric: tabular-nums`), animazioni ridotte, tooltip sì/no, stato del menu (enum `ThemeMode`,
`AccentColor`, `Density`, `MenuState`). `ThemeService` e `MenuStateService` applicano gli attributi senza ricaricare
la pagina.
`mockup.css` non contiene i valori del tema **alto contrasto**: sono definiti in `tokens.css` con gli stessi nomi di
token (testo nero su bianco, bordi neri, un solo accento blu scuro per tutti gli accenti), per il contrasto AAA.
## Classi dei mockup e componenti `Kh*`
I componenti vivono in `Components/Ui` con prefisso `Kh` (SPEC §10.7). La tabella indica la classe di `mockup.css` da
cui ogni componente prende l'aspetto; dove la specifica non indica un componente dedicato la corrispondenza è una
proposta da confermare in sviluppo.
| Classe CSS (`mockup.css`) | Componente | Uso |
|---|---|---|
| `.app`, `.app.collapsed` | `MainLayout` | griglia della shell (barra, menu, contenuto, stato) |
| `.topbar`, `.brand`, `.company`, `.userbox`, `.tbtn` | `TopBar`, `CompanySwitcher`, `UserMenu` | barra superiore |
| `.gsearch`, `.palette`, `.hit` | `GlobalSearch`, `KhCommandPalette` | ricerca globale `Ctrl+K` |
| `.tbtn .dot` | `KhNotificationBell` | campanella con pallino |
| `.sidebar`, `.nav`, `.nav.sub`, `.toggle`, `.flyout` | `KhSideMenu` | menu comprimibile con sottomenu a comparsa |
| `.tabs-strip`, `.wtab`, `.wtab .mod` | `KhTabHost` | schede delle maschere aperte |
| `.statusbar` | `KhStatusBar` | barra di stato |
| `.toolbar.icons`, `.grp`, `.sep` | `KhIconToolbar` | toolbar a sole icone su una riga |
| `.ib`, `.ib .cnt`, `.tip` | `KhIconButton` | pulsante icona con tooltip e contatore |
| `.ctx` (`.primary`, `.ok`, `.warn`, `.danger`) | `KhContextAction` | azione contestuale icona + etichetta |
| `.btn`, `.seg` | (pulsanti standard, segmenti) | pulsanti testuali e selettori a segmenti |
| `.dochead`, `.kind`, `.party`, `.tot` | `KhDocHead` | intestazione documento a tre blocchi |
| `.ichip`, `.chip` | `KhChip` | chip delle condizioni e dei filtri |
| `.tabs`, `.tabs.i`, `.tab .n`, `.tab .k` | `KhTabs` | schede interne con icone, contatori, tasto |
| `.fgroups`, `.fgroup`, `.fgh` | `KhFieldGroup` | gruppi di campi |
| `.form`, `.f`, `.c1`…`.c12`, `.hint`, `.req` | `KhForm`, `KhField` | griglia a 12 colonne dei campi |
| `.f .in` | `KhTextBox`, `KhNumberBox`, `KhDateBox`, `KhSelect` | campi di input |
| `.f .in .code` + `.desc` + `.lk` | `KhHotlink` | codice + descrizione + icone cerca/apri |
| `.f .in.ta` | `KhTextArea` | testo su più righe |
| `.bx`, `.chk` | `KhCheck` | casella di spunta |
| `.switch` | `KhSwitch` | interruttore |
| `.grid`, `.gridwrap`, `.gridfoot`, `.pager` | `KhGrid`, `KhLinesGrid` | griglie e righe documento (`td.ed` cella in modifica, `tr.sel`, `tr.hl`, `td.desc-row`) |
| `.filters` | parte di `KhRadar` | barra filtri del radar |
| `.panel`, `.ph`, `.pb` | `KhPanel` | pannelli |
| `.tile` | `KhTile` | indicatori KPI con mini-grafico |
| `.strip` | `KhStrip` | striscia di indicatori |
| `.wgrid`, `.w3`…`.w12`, `.widget`, `.widget.editing` | `KhWidgetGrid`, `KhWidget` | dashboard personalizzabile |
| `.overlay`, `.dialog` | `KhDialog`, `KhConfirm` | finestre modali |
| `.drawer` | `KhDrawer` | pannelli laterali (personalizza, allegati, dettaglio log) |
| `.badge` (`gray`, `blue`, `green`, `amber`, `red`, `accent`) | `KhBadge` | stati |
| `.totals`, `.num` | `KhMoney` | importi allineati |
| `.steps`, `.step` | `KhSteps` | passi orizzontali |
| `.vsteps`, `.vstep` | `KhVSteps` | procedure guidate verticali |
| `.kanban`, `.kcol`, `.card` | `KhKanban` | pipeline CRM |
| `.timeline`, `.tl` | `KhTimeline` | cronologie |
| `.tree`, `.tn`, `.lv1`…`.lv4` | `KhTree` | piano dei conti |
| `.cal`, `.ev` | `KhCalendar` | agenda |
| `.att`, `.ft.pdf`/`.xml`/`.xlsx`… | `KhAttachmentList` | allegati con colore per formato e *Genera file* |
| `.paper` | `KhPrintPreview` | anteprima di stampa (pagina A4 a 794 px) |
| `.loglvl`, `.secnav`, `.codebox` | `KhLogViewer` | log avanzato |
| `.callout`, `.kv`, `.list`, `.ico-box`, `.bar`, `.deadline`, `.chk-row` | (elementi di contenuto) | avvisi, coppie chiave/valore, liste, barre, scadenze e checklist dei widget |
| `.modcard`, `.swatches`/`.sw`, `.themecard`, `.login` | pagine specifiche | licenze, preferenze tema, accesso |
Altri componenti della libreria senza una classe dedicata nei mockup: `KhToast`, `KhAuditList`, `KhHelpLink`,
`KhRadar` (composizione di toolbar, filtri e `KhGrid`).
Comportamenti richiesti ai componenti (SPEC §10.7): `KhNumberBox` in formato it-IT con calcolo inline (`=10*3`);
`KhDateBox` `gg/mm/aaaa` con `+`/`-` giorno, `T` oggi, `F` fine mese; `KhHotlink` con ricerca incrementale, `F4`
radar, `Ctrl+Invio` apre, creazione al volo; `KhGrid` con colonne tipizzate, ordinamento, filtri, paginazione lato
server, virtualizzazione, selezione multipla, editing inline, riga dei totali, layout colonne salvato, export,
evidenziazioni, menu di riga.
## File CSS
| File | Contenuto |
|---|---|
| `css/tokens.css` | token `--kh-*` di `mockup.css`, temi (automatico, chiaro, scuro, alto contrasto), accenti, densità, dimensioni del testo; generato da `mockup.css` |
| `css/components.css` | classi dei mockup (shell, toolbar, pannelli, campi, griglie, badge, dialoghi…), riprese da `mockup.css` |
| `css/interactive.css` | ciò che i mockup statici non hanno: reset dei pulsanti, focus, suggerimenti, menu a comparsa, schede, notifiche a scomparsa, interruttori `data-*` |
| `css/print.css` | stampa sempre in chiaro, shell nascosta |
| `app.css` | pagine costruite finora (accesso, home, profilo, messaggi) |
Gli attributi sull'elemento `` comandano l'aspetto: `data-theme` (`auto`, `light`, `dark`, `high-contrast`),
`data-accent`, `data-density`, `data-text-size` (`100`, `110`, `120`), `data-tabular`, `data-motion`,
`data-tooltips`, `data-row-hover`. Il server li scrive dalle preferenze dell'utente; il profilo li cambia dal vivo.
## Shell
- Griglia: barra superiore 46 px, area centrale, barra di stato 24 px; menu 228 px (60 px compresso).
- **Barra superiore** scura (`--kh-topbar`): marchio (icona a 4 tessere su gradiente `--kh-brand` → `--kh-brand-deep`,
nome, versione), selettore azienda, ricerca (max 520 px, con `kbd` *Ctrl K*), pulsanti 32x32, utente.
- **Menu**: sezioni in maiuscoletto (`.sec`), voce attiva su `--kh-accent-soft`; compresso: solo icone 20 px, barretta
d'accento a sinistra della voce attiva, sottomenu in `.flyout` (min 190 px, ombra grande). Pulsante **Comprimi
menu** tratteggiato in fondo. Sotto 1100 px parte compresso; stato salvato per utente.
- **Schede** (`.wtab`): altezza 30 px, massimo 260 px di larghezza, pallino `--kh-warn` se modificata. Ogni pagina
imposta il titolo della sua scheda con `` e segnala le modifiche con il
`KhTab` in cascata (`Tab?.SetModified(true)`).
- **Barra di stato**: testo 11.5 px, pallino `--kh-ok` per la connessione.
Dettagli d'uso in [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie).
## Toolbar
- Pulsanti icona 32x32 con icona 18 px, raggio 7 px; gruppi separati da `.sep` (1x22 px).
- Ordine: Nuovo, **Salva** (`.ib.primary`), Annulla, Elimina (`.ib.danger`) · Duplica, Stampa, E-mail, Genera file ·
Allegati, Storico, Collegamenti · a destra Radar, precedente/successivo, `⋯`.
- Tooltip (`.tip`) scuro sotto il pulsante con nome e `kbd` della scorciatoia.
- Azioni contestuali `.ctx`: alte 30 px, icona 16 px nel colore d'accento, etichetta di al massimo tre parole; la
principale `.ctx.primary`; **al massimo 4**, le altre nel menu `⋯`.
- **Sempre su una riga**: quando lo spazio manca le icone meno usate passano nel menu `⋯`; le etichette non vanno mai
a capo.
## Intestazione documento
`.dochead` è una griglia a tre colonne (`minmax(260px,1.05fr) minmax(320px,1.7fr) minmax(290px,.95fr)`):
1. **Tipo**: riquadro 40x40 con icona 22 px su `--kh-accent-soft`, etichetta in maiuscoletto (*Fattura immediata ·
TD01*), numero a 19 px peso 650 con cifre tabellari, riga meta 12 px, badge di stato.
2. **Controparte**: iniziali in riquadro 40x40, nome 15 px con codice in `--kh-mono` su `--kh-accent-soft`, riga di
dettaglio, chip `.ichip` (varianti `.acc`, `.warn`, `.err`).
3. **Totale**: etichetta in maiuscoletto, valore a 24 px peso 650, tre sotto-valori.
Le anagrafiche usano lo stesso blocco con identità, contatti, chip delle condizioni e KPI (mockup 014, 016, 017).
## Gruppi di campi
- `.fgroups`: griglia `repeat(auto-fit, minmax(300px, 1fr))`, gap 12 px; `.fgroup.wide` occupa tutta la riga.
- `.fgroup`: sfondo `--kh-surface-2`, intestazione `.fgh` in maiuscoletto 11.5 px con icona d'accento 14 px.
- Dentro, `.form` su 12 colonne (`.c1`…`.c12`), etichette sopra i campi (11.5 px), obbligatori con `.req` rosso,
suggerimenti `.hint` sotto (11 px), errori `.in.err` con alone `--kh-err-soft`, focus `.in.focus` con alone
`--kh-accent-soft`; campi di sola lettura `.in.ro`.
## Icone
Icone SVG **proprie** in un unico sprite `wwwroot/icons/sprite.svg`, ridisegnate riprendendo i tracciati dei mockup:
stile a tratto, senza riempimento (`stroke: currentColor`, `stroke-width: 1.75`, estremi e giunzioni arrotondati),
16 px di base (`svg.i`), 20 px (`.lg`) e 13 px (`.sm`); 18 px nei pulsanti della toolbar. Le icone ereditano il colore
dal testo. Nessuna libreria di icone esterna. L'icona dell'applicazione è descritta in SPEC Appendice B.
## Accessibilità e localizzazione
- **Caratteri di sistema**: `Inter` se installato sul sistema dell'utente, altrimenti `Segoe UI` / `system-ui`;
**nessun font scaricato**, nessuna CDN.
- **Focus sempre visibile**, etichette collegate ai campi (`