The milestone's Definition of Done asks for real screenshots, complete wiki pages and a changelog for everything delivered. Fifteen screenshots taken on a fresh instance now sit next to the mockups in the wiki; Interfaccia, Dashboard, Preferenze, Design UI and Allegati are marked complete, with the date-field shortcuts and the profile tabs that are not built yet described as they really are. ADR 0024 records the Kh component library, record pages and the shared list query, which shipped without one, and the changelog gains its entries and a 0.3.0 section. The visual check against the mockups found three layout bugs, fixed here: the document total label took the timeline's .tl style and was cut, the radar's .kh-choices class stacked the profile's theme cards in a column (renamed .kh-radio-set), and on phones the top bar wrapped; it now keeps icons only and the status bar shows only the live values. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
20 KiB
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.
File di riferimento nel repository:
docs/mockups/mockup.css— token e classi dei componenti usati per disegnare le schermate;docs/mockups/png/— schermate ad alta risoluzione (23 + galleria);docs/mockups/thumbs/— miniature di tutte le 88 schermate;docs/SPEC.md§10 e Appendice A.
I mockup sono la specifica
Regole vincolanti (SPEC §10.1):
- Prima della milestone 3 si legge
mockup.cssper 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. src/Khaemhat.Web/wwwroot/css/tokens.cssnasce damockup.css: stessi nomi e valori dei token (temi, otto accenti, densità). I nomi non si cambiano; si aggiungono token solo se servono.- I dati visibili nelle schermate sono esempi del seed demo: non vanno nel markup.
- 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.
- 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) 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 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 <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, conkbdCtrl 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-warnse modificata. Ogni pagina imposta il titolo della sua scheda con<KhPageTitle Text="..." Icon="..." />e segnala le modifiche con ilKhTabin cascata (Tab?.SetModified(true)). - Barra di stato: testo 11.5 px, pallino
--kh-okper la connessione.
Dettagli d'uso in 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 ekbddella 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)):
- 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. - Controparte: iniziali in riquadro 40x40, nome 15 px con codice in
--kh-monosu--kh-accent-soft, riga di dettaglio, chip.ichip(varianti.acc,.warn,.err). - 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: grigliarepeat(auto-fit, minmax(300px, 1fr)), gap 12 px;.fgroup.wideoccupa tutta la riga..fgroup: sfondo--kh-surface-2, intestazione.fghin maiuscoletto 11.5 px con icona d'accento 14 px.- Dentro,
.formsu 12 colonne (.c1….c12), etichette sopra i campi (11.5 px), obbligatori con.reqrosso, suggerimenti.hintsotto (11 px), errori.in.errcon alone--kh-err-soft, focus.in.focuscon 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:
Interse installato sul sistema dell'utente, altrimentiSegoe 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 e su telefono con la barra superiore a sole icone (vedi Interfaccia e scorciatoie).
- Nomi di classe unici: una classe dei mockup ha un solo significato. Se un componente ha bisogno di una variante, usa un nome nuovo (
kh-…) invece di riusarne uno esistente: in 0.3.0.tl(timeline) e.kh-choicesusati in due sensi diversi spostavano l'etichetta del totale documento e le schede dei temi. - Testi: nessun testo hard-coded nei componenti;
ITexts(iniettato in ogni componente comeT) risolve chiavi comeShell.Menu.Partiesdasrc/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 attributititle,placeholder,alt,aria-label,labeldei.razor, e ogni chiave usata esiste (ADR 0020). - Formati:
CultureInfo("it-IT")per numeri, importi e date; date memorizzate in UTC e mostrate nel fusoEurope/Rome.
Stampa
Le stampe e i PDF sono sempre in tema chiaro (print.css), indipendentemente dal tema dell'utente. L'anteprima di
stampa (KhPrintPreview, mockup 025) mostra il documento come foglio .kh-sheet largo 210 mm e alto almeno 297 mm,
con ingrandimento 75/100/125%; @media print nasconde tutto tranne il foglio e imposta @page A4 senza margini.
La classe .paper di mockup.css resta per le anteprime piccole dentro le pagine.
Khaemhat 0.3.0 — l'anteprima di stampa del documento di prova.
Regola di aggiornamento
Ogni cambiamento visivo (nuovo componente, token modificato, schermata ridisegnata) aggiorna nella stessa unità di lavoro:
- lo screenshot corrispondente in
docs/wiki/img/(e, se il mockup diventa superato, la nota nella pagina Mockup); - questa pagina (token, tabella classi/componenti, regole);
CHANGELOG.md.
Pagine correlate
Mockup · Interfaccia e scorciatoie · Preferenze utente · Architettura · Contribuire · Processo di sviluppo