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>
18 KiB
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.
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/
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) 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, 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.
- 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
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:
- 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