Files
Khaemhat/docs/wiki/Design-UI.md
T
Alby96andClaude Opus 5.5 b4a2802bed
CI / Build and test (SQLite) (pull_request) Successful in 1m36s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Successful in 1m13s
docs: close M3 with real screenshots, ADR 0024 and the 0.3.0 changelog (#36)
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>
2026-11-11 20:26:36 +01:00

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:

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 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 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, 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.

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 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-choices usati 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 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 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 · anteprima di stampa 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:

  1. lo screenshot corrispondente in docs/wiki/img/ (e, se il mockup diventa superato, la nota nella pagina Mockup);
  2. questa pagina (token, tabella classi/componenti, regole);
  3. CHANGELOG.md.

Pagine correlate

Mockup · Interfaccia e scorciatoie · Preferenze utente · Architettura · Contribuire · Processo di sviluppo