Card e livelli di superficie
Regole di utilizzo per schede contenuto, shell dell'area di lavoro, livelli sovrapposti, ombre e sfondo smerigliato.
Le carte contenuto rimangono piatte; l'involucro esterno comunica il raggruppamento dello spazio di lavoro.
Una carta contenuto standard non utilizza un'ombra esterna.
La selezione e lo stato vengono comunicati tramite colore e gerarchia delle informazioni.
Materiali delle card e norme sui livelli
Questo documento descrive pubblicamente in quali scenari l'interfaccia di Qokit utilizza ombre, trasparenza, gradienti e sfondo smerigliato. Si applica alla piattaforma estesa, Builder, CMS, Dashboard, Studio e Admin. Le pagine di marketing e i siti generati possono essere più espressivi, ma gli effetti devono appartenere al tema corrente e garantire la leggibilità del contenuto.
Principi fondamentali
Gli effetti visivi servono a esprimere la struttura, non a decorare ogni blocco:
- I contenuti si distinguono attraverso la differenza di colore dello sfondo.
- I contenitori esprimono l'appartenenza tramite trasparenza o gradienti sobri.
- I livelli sovrapposti esprimono la gerarchia tramite ombre.
- Le interazioni esprimono lo stato tramite colore e anelli di focus.
Le card a tinta unita indipendenti e i campi di input condividono un'ombra leggera di primo livello; liste, superfici annidate e gruppi trasparenti rimangono piatti; solo i veri livelli sovrapposti utilizzano ombre marcate.
Ordine di valutazione
Prima di aggiungere un effetto materiale, determina il ruolo della superficie:
- È una card a tinta unita indipendente o un campo di input? Usa l'ombra di superficie o di campo di primo livello condivisa.
- È una riga di lista, una card annidata, un'opzione ripetuta o un gruppo trasparente? Mantienila piatta.
- Organizza più card di contenuto interne in un'area di lavoro? Usa una Shell.
- Copre il contenuto della pagina o appare sopra il piano corrente? Usa l'ombra di livello sovrapposto.
- È in stato di trascinamento, zoom o passaggio temporaneo? Usa un'ombra temporanea.
- Serve solo a esprimere hover, selezione o focus? Usa il ruolo hover condiviso, il colore di sfondo interattivo e l'anello di focus.
A meno che il ruolo della superficie non lo richieda davvero, non sovrapporre contemporaneamente ombra, trasparenza, gradiente e smerigliatura.
Matrice degli scenari
| Ruolo della superficie | Ombra | Trasparenza o gradiente | Sfondo smerigliato |
|---|---|---|---|
| Card di contenuto a tinta unita indipendenti, card di metriche | Ombra leggera di primo livello condivisa | Leggera differenza di colore dello sfondo consentita | Nessuno |
| Righe di lista, card annidate, gruppi trasparenti, opzioni ripetute | Nessuna | Leggera differenza di colore dello sfondo consentita | Nessuno |
| Shell di gruppo all'interno della pagina | Nessuna | Consigliato | Di solito non necessario |
| Sidebar o Shell di area di lavoro persistente | Leggera | Consigliato | Consentito quando c'è contenuto visibile dietro |
| Dialog, Popover, Dropdown, menu contestuali | Ombra di livello sovrapposto marcata | Lo sfondo deve essere sufficientemente opaco per garantire la leggibilità | Consentito |
| Anteprima di trascinamento, stato di zoom, anteprima al passaggio | Temporanea più marcata | Opzionale | Di solito non necessario |
| Hover | Mantenere o rafforzare leggermente l'ombra di primo livello | Lo sfondo può cambiare | Nessun cambiamento |
| Stato selezionato o attivo | Nessuna | Sfondo accentato o gradiente sobrio | Nessun cambiamento |
| Campi di input, campi di ricerca | Ombra di campo molto leggera | Usa il colore di superficie del controllo | Di solito non necessario |
| Azione primaria indipendente, capsula indipendente, involucro di controllo segmentato | Ombra di controllo molto leggera | Usa il colore di superficie del controllo | Di solito non necessario |
| Barra degli strumenti e controlli interni trasparenti | Nessuna | Usa il colore di superficie del controllo o trasparente | Di solito non necessario |
| Pagine di marketing o card visive di siti generati | Determinato dal tema | Consentito | Uso sobrio |
Mappatura dei componenti
<Card>utilizza di defaultlayer="content": ombra leggera di primo livello condivisa, nessun bordo, raggio20pxdi default; le varianti muted, annidate, di lista e trasparenti rimangono piatte.<Card layer="shell">: all'interno della pagina si occupa solo del raggruppamento, utilizza una superficie trasparente o con gradiente leggero e rimane piatta; la Shell di area di lavoro persistente fornisce il proprio livello tramite la modalità di appartenenza.<Card shape="pill">: utilizzato per card compatte a riga singola, con raggio a forma di capsula ellittica.SidebarNavigation: Shell di area di lavoro indipendente, conserva gradienti, trasparenza, smerigliatura e ombre leggere ben definiti.- Quando
PromptPaneldi Studio funge da contenitore di area di lavoro: utilizza--workspace-shell-shadow. DialogPanel, menu a discesa, Popover, menu contestuali e browser concettuale: utilizzano l'ombra di livello sovrapposto.- Canvas del Builder, anteprima dispositivo, anteprima sito generato, anteprima di trascinamento e stato di zoom: poiché rappresentano un piano di anteprima indipendente o un livello di interazione temporaneo, possono conservare ombre dedicate.
Non creare card di contenuto sovrapposte a più livelli. Se è davvero necessario un raggruppamento esterno, deve essere una Shell piatta. Ad eccezione dei veri livelli sovrapposti, nella stessa catena di antenati DOM può apparire al massimo un'ombra normale di contenuto o controllo.
Utilizzo delle variabili di design (Token)
Dai priorità ai Token condivisi, non codificare gli effetti in modo rigido:
- Ombra card di contenuto:
--card-shadow: var(--qk-shadow-surface) - Ombra hover card di contenuto:
--card-shadow-hover: var(--qk-shadow-surface-hover) - Ombra di campo:
--input-shadow: var(--qk-shadow-field) - Ombra di campo attivo:
--input-state-shadow: var(--qk-shadow-field-active) - Ombra di controllo:
--qk-shadow-control/--qk-shadow-control-hover - Ombra di controllo per azione primaria:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - Smerigliatura card di contenuto:
--card-backdrop-filter: none - Superficie Shell:
--card-shell-surface - Smerigliatura Shell:
--card-shell-backdrop-filter - Ombra Shell di area di lavoro:
--workspace-shell-shadow - Superficie Dialog:
--dialog-surface, fornisce un gradiente di tema sobrio - Smerigliatura Dialog:
--dialog-backdrop-filter - Ombra di livello sovrapposto Dialog:
--dialog-shadow - Raggio Dialog: riutilizza
--card-radius - Focus da tastiera:
--focus-ring - Ombra di livello sovrapposto: utilizza i Token esistenti per Dialog, Dropdown, Menu o livelli sovrapposti a livello di pagina
Le card di contenuto normali e i pannelli di area di lavoro non devono utilizzare il Token generico più marcato --shadow.
Le ombre globali adottano una scala discreta con "spostamento breve, bassa opacità, crescente in base al livello di posizionamento". Card, campi e controlli normali non devono approfondire o ingrandire le ombre condivise durante la navigazione; Popover e Dialog esprimono il distacco dalla pagina tramite uno spostamento e un raggio di sfocatura maggiori, non sovrapponendo una nebbia grigia scura.
Regole di interazione
Hover
- Le card di contenuto non devono essere elevate a un livello superiore a
--qk-shadow-surface-hover. - Non elevare le card di contenuto tramite
translateY. - Utilizza leggere variazioni di sfondo o un feedback di controllo chiaro.
- Non cambiare la forma, per evitare raggi incoerenti o ritagli di ombra.
Selezione e attivazione
- Utilizza superfici accentate, stati delle icone, stati semantici o gradienti sobri.
- Non esprimere lo stato solo tramite ombra.
Focus da tastiera
- Utilizza le regole focus-visible condivise o
--focus-ring. - L'ombra generica della card non può sostituire l'indicazione di focus.
- Deve essere chiaramente visibile sia nei temi chiari che scuri.
Trascinamento e zoom
- Ombre più marcate sono consentite solo quando il livello è in movimento o ridimensionamento.
- L'ombra temporanea deve essere rimossa al termine dell'interazione.
- I contenitori con overflow non devono ritagliare gli effetti di feedback del livello in movimento.
Trasparenza e sfondo smerigliato
La trasparenza serve a esprimere l'appartenenza tra la superficie esterna e l'area di lavoro. Lo sfondo smerigliato ha senso solo quando dietro la superficie c'è effettivamente contenuto, colore o immagine visibile.
- Non utilizzare la smerigliatura su sfondi a tinta unita: aumenta solo il costo di rendering senza esprimere gerarchia.
- Testo, icone e controlli devono essere chiaramente leggibili indipendentemente dallo sfondo sottostante.
- Quando il browser non supporta lo sfondo smerigliato, deve essere presente uno sfondo di fallback opaco o leggibile.
- L'intensità della sfocatura deve essere sobria nelle interfacce di lavoro dense.
- È necessario verificare sia il tema chiaro che quello scuro.
Eccezioni in cui è consentito conservare le ombre
- Shell della sidebar dell'area di lavoro
- Dialog, Popover, Dropdown, menu e pannelli modali
- Browser concettuale di Studio e livelli sovrapposti di conferma
- Canvas del Builder, frame del dispositivo e piani di anteprima dei siti generati
- Anteprima di trascinamento, feedback di zoom e strumenti temporanei al passaggio
- Pulsanti di azione primaria in cui il Token condiviso dei pulsanti ha già definito un'ombra
- Elementi visivi delle pagine di marketing e dei siti generati controllati dal tema corrente
Queste eccezioni non devono influenzare le card di contenuto normali tramite selettori generici o Token condivisi.
Checklist di revisione
- Le card di contenuto a tinta unita indipendenti e i campi di input utilizzano solo il ruolo di ombra leggera di primo livello condivisa.
- Le azioni primarie indipendenti, le capsule indipendenti e gli involucri di controllo segmentati utilizzano solo l'ombra di controllo molto leggera condivisa.
- Raggruppamenti di pagina, righe di lista, card annidate, gruppi trasparenti, Tab/Pill ripetuti, barre degli strumenti e elementi interni di controlli compositi rimangono piatti.
- Ricerca, filtri, ordinamento, viste e azioni primarie inline nella barra degli strumenti rimangono piatti; l'ombra leggera dei campi di input normali non deve propagarsi alla barra degli strumenti, ad eccezione dell'anello di focus da tastiera.
- Quando Segmented si trova all'interno di una card, dialog o barra degli strumenti con ombra, sia l'involucro che l'elemento selezionato rimangono piatti; il click del mouse non mostra l'anello di focus da tastiera.
- Ad eccezione dei veri livelli sovrapposti, non sovrapporre più ombre normali nella stessa catena di antenati.
- L'hover non sposta verticalmente le card di contenuto.
- Le card di contenuto annidate sono state rimosse o il livello esterno è stato definito esplicitamente come Shell.
- Solo le vere Shell utilizzano
--workspace-shell-shadow. - Solo i veri livelli sovrapposti e i livelli di interazione temporanei utilizzano ombre più marcate.
- Dietro lo sfondo smerigliato è presente contenuto visibile ed è disponibile uno sfondo di fallback leggibile.
- focus-visible utilizza un anello di focus.
- Sia il tema chiaro che quello scuro mantengono un contrasto sufficiente.
- Le superfici con raggio non ritagliano il feedback di hover, focus, trascinamento o livello sovrapposto.
- Le larghezze desktop e mobile non presentano nuovi overflow orizzontali.
- Controllo
npm run ui:check-card-surfaces --workspace @qokit-ai/websuperato.