Files
Khaemhat/docs/wiki/Design-UI.md
T
Alby96andClaude Opus 5.5 cf6f849cc1 feat: application shell, localized texts and user preferences (M3, part 1)
The pages built so far now live inside the shell of the mockups instead of the
M0 placeholder, every interface text comes from Resources/it-IT, and each user
keeps their own look and start page.

- Shell: top bar, collapsible side menu with fly-out sub-menus, status bar and
  tabs that keep each page alive (page type and route values per tab, so a tab
  never shows another page); at most 12 tabs, least-used clean tab evicted.
- One shortcut table with Alt variants for the combinations browsers keep
  (Ctrl+W, Ctrl+Tab, Ctrl+N); command palette for pages and commands.
- ITexts over embedded JSON; tests forbid literal texts in .razor components
  and check that every key used exists.
- User settings in sys_user_settings / user_settings; theme written on the
  server; profile page with live preview, start page, sessions and shortcuts.
- Home, coming-soon pages for later milestones, localized sign-in and error
  pages; ADR 0020; wiki, CHANGELOG, STATUS and data model updated.

Refs #25 #26 #31 #33

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 16:44:59 +01:00

260 lines
18 KiB
Markdown

# Design UI
> **Stato:** in corso · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.3.0 in sviluppo (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/`
sostituiscono progressivamente i mockup nelle pagine della wiki.
## 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 `<html>`:
| 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 ancora i valori del tema alto contrasto**: vanno definiti in `tokens.css` rispettando il
contrasto AAA, con gli stessi nomi di token, e documentati in questa pagina.
## 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 `<html>` 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 `<KhPageTitle Text="..." Icon="..." />` 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 (`<label for>`), contrasto **AA** (AAA nel tema alto
contrasto), tutto operabile da tastiera.
- Desktop-first, usabile da tablet a partire da **768 px**.
- **Testi**: nessun testo hard-coded nei componenti; `ITexts` (iniettato in ogni componente come `T`) risolve chiavi
come `Shell.Menu.Parties` da `src/Khaemhat.Web/Resources/it-IT/*.json` (risorse incorporate). Gli oggetti annidati
danno le chiavi puntate, la proprietà `_` dà il testo all'oggetto che ha figli, una chiave doppia blocca l'avvio e
una mancante appare come `[chiave]`. Uso: `@T["Pages.Profile.Title"]`, `@T.Format("Pages.Home.Coming", "M4")`,
`T.Money(1234.5m)`, `T.Date(...)`. Due test lo garantiscono: nessun testo letterale fra i tag e negli attributi
`title`, `placeholder`, `alt`, `aria-label`, `label` dei `.razor`, e ogni chiave usata esiste (ADR 0020).
- **Formati**: `CultureInfo("it-IT")` per numeri, importi e date; date memorizzate in UTC e mostrate nel fuso
`Europe/Rome`.
## Stampa
Le stampe e i PDF sono **sempre in tema chiaro** (`print.css`), indipendentemente dal tema dell'utente. L'anteprima
usa `.paper` (pagina bianca larga 794 px, cioè un A4 a 96 dpi, margini 40/44 px, tabelle con intestazione in
maiuscoletto e bordo inferiore marcato).
## Regola di aggiornamento
Ogni cambiamento visivo (nuovo componente, token modificato, schermata ridisegnata) aggiorna **nella stessa unità di
lavoro**:
1. lo **screenshot** corrispondente in `docs/wiki/img/` (e, se il mockup diventa superato, la nota nella pagina
[Mockup](Mockup));
2. **questa pagina** (token, tabella classi/componenti, regole);
3. `CHANGELOG.md`.
## Pagine correlate
[Mockup](Mockup) · [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie) · [Preferenze utente](Preferenze-utente) ·
[Architettura](Architettura) · [Contribuire](Contribuire) · [Processo di sviluppo](Processo-di-sviluppo)