# 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 · documento](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/design-documento.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 · tema scuro](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/design-tema-scuro.png) *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 (`