Skip to Content
Design

Card e livelli di superficie

Regole di utilizzo per schede contenuto, shell dell'area di lavoro, livelli sovrapposti, ombre e sfondo smerigliato.

Componente in tempo realeLivelli carta

Le carte contenuto rimangono piatte; l'involucro esterno comunica il raggruppamento dello spazio di lavoro.

Panoramica progettoProntezza al lancio
Contenuto12 pagine completate

Una carta contenuto standard non utilizza un'ombra esterna.

VerifichePronto per dispositivi mobili

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:

  1. È una card a tinta unita indipendente o un campo di input? Usa l'ombra di superficie o di campo di primo livello condivisa.
  2. È una riga di lista, una card annidata, un'opzione ripetuta o un gruppo trasparente? Mantienila piatta.
  3. Organizza più card di contenuto interne in un'area di lavoro? Usa una Shell.
  4. Copre il contenuto della pagina o appare sopra il piano corrente? Usa l'ombra di livello sovrapposto.
  5. È in stato di trascinamento, zoom o passaggio temporaneo? Usa un'ombra temporanea.
  6. 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 superficieOmbraTrasparenza o gradienteSfondo smerigliato
Card di contenuto a tinta unita indipendenti, card di metricheOmbra leggera di primo livello condivisaLeggera differenza di colore dello sfondo consentitaNessuno
Righe di lista, card annidate, gruppi trasparenti, opzioni ripetuteNessunaLeggera differenza di colore dello sfondo consentitaNessuno
Shell di gruppo all'interno della paginaNessunaConsigliatoDi solito non necessario
Sidebar o Shell di area di lavoro persistenteLeggeraConsigliatoConsentito quando c'è contenuto visibile dietro
Dialog, Popover, Dropdown, menu contestualiOmbra di livello sovrapposto marcataLo sfondo deve essere sufficientemente opaco per garantire la leggibilitàConsentito
Anteprima di trascinamento, stato di zoom, anteprima al passaggioTemporanea più marcataOpzionaleDi solito non necessario
HoverMantenere o rafforzare leggermente l'ombra di primo livelloLo sfondo può cambiareNessun cambiamento
Stato selezionato o attivoNessunaSfondo accentato o gradiente sobrioNessun cambiamento
Campi di input, campi di ricercaOmbra di campo molto leggeraUsa il colore di superficie del controlloDi solito non necessario
Azione primaria indipendente, capsula indipendente, involucro di controllo segmentatoOmbra di controllo molto leggeraUsa il colore di superficie del controlloDi solito non necessario
Barra degli strumenti e controlli interni trasparentiNessunaUsa il colore di superficie del controllo o trasparenteDi solito non necessario
Pagine di marketing o card visive di siti generatiDeterminato dal temaConsentitoUso sobrio

Mappatura dei componenti

  • <Card> utilizza di default layer="content": ombra leggera di primo livello condivisa, nessun bordo, raggio 20px di 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 PromptPanel di 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/web superato.

In questa pagina