Skip to Content
Tasarım

Kart ve Yüzey Katmanları

İçerik kartları, çalışma alanı kabuğu, katmanlar, gölgeler ve arka plan bulanıklığı kullanım kuralları.

Canlı bileşenKart katmanları

İçerik kartları düz kalır; dış kabuk çalışma alanı gruplamasını iletir.

Proje özetYayın hazırlığı
İçerik12 sayfa tamamlandı

Standart içerik Kartı, dış gölge kullanmaz.

KontrollerMobil uyumlu

Seçim ve durum renkler ve bilgi hiyerarşisiyle iletilir.

Kart Malzemesi ve Katman Kuralları

Bu belge, Qokit çalışma arayüzünün hangi durumlarda gölge, şeffaflık, gradyan ve arka plan bulanıklığı kullandığını açıkça belirtir. Platform uzantıları, Builder, CMS, Dashboard, Studio ve Admin için geçerlidir. Pazarlama sayfaları ve oluşturulan siteler daha ifade gücüne sahip olabilir, ancak efektler mevcut temaya ait olmalı ve içerik okunabilirliğini sağlamalıdır.

Temel İlkeler

Görsel efektler yapıyı ifade etmek için kullanılır, her bloğu süslemek için değil:

  • İçerik, arka plan renk farkıyla ayrılır.
  • Konteynerler, şeffaflık veya kontrollü gradyanlarla aidiyeti ifade eder.
  • Katmanlar, gölgelerle katmanlaşmayı ifade eder.
  • Etkileşimler, renk ve odak halkasıyla durumu ifade eder.

Bağımsız düz renk kartlar ve giriş alanları paylaşımlı birinci düzey hafif gölge kullanır; listeler, iç içe yüzeyler ve şeffaf gruplar düz kalır; yalnızca gerçek katmanlar belirgin gölge kullanır.

Karar Sırası

Malzeme efekti eklemeden önce yüzeyin rolünü belirleyin:

  1. Bağımsız düz renk kart veya giriş alanı mı? Paylaşımlı birinci düzey yüzey veya alan gölgesi kullanın.
  2. Liste satırı, iç içe kart, tekrarlanan seçenek veya şeffaf grup mu? Düz tutun.
  3. Birden fazla dahili içerik kartını bir çalışma alanı olarak mı düzenliyor? Kabuk (Shell) kullanın.
  4. Sayfa içeriğini mi kaplıyor veya mevcut düzlemin üzerinde mi görünüyor? Katman gölgesi kullanın.
  5. Sürükleme, yakınlaştırma veya geçici yükleme durumunda mı? Geçici gölge kullanın.
  6. Yalnızca hover, seçili veya odak durumunu mu ifade ediyor? Paylaşımlı hover rolü, etkileşim arka plan rengi ve odak halkası kullanın.

Yüzey rolü gerçekten gerektirmedikçe gölge, şeffaflık, gradyan ve bulanıklığı aynı anda birleştirmeyin.

Senaryo Matrisi

Yüzey RolüGölgeŞeffaflık veya GradyanArka Plan Bulanıklığı
Bağımsız düz renk içerik kartı, metrik kartıPaylaşımlı birinci düzey hafif gölgeHafif arka plan renk farkına izin verilirYok
Liste satırı, iç içe kart, şeffaf grup, tekrarlanan seçenekYokHafif arka plan renk farkına izin verilirYok
Sayfa içi gruplama kabuğuYokÖnerilirGenellikle gerekmez
Kenar çubuğu veya kalıcı çalışma alanı kabuğuHafifÖnerilirArkasında görünür içerik olduğunda izin verilir
Dialog, Popover, Dropdown, bağlam menüsüBelirgin katman gölgesiArka plan okunabilirliği sağlamak için yeterince düz olmalıdırİzin verilir
Sürükleme önizlemesi, yakınlaştırma durumu, yükleme önizlemesiGeçici olarak daha güçlüİsteğe bağlıGenellikle gerekmez
HoverBirinci düzey gölgeyi koru veya hafifçe güçlendirArka plan değiştirilebilirDeğişmez
Seçili veya etkin durumYokVurgu rengi arka planı veya kontrollü gradyanDeğişmez
Giriş alanı, arama kutusuÇok hafif alan gölgesiKontrol yüzey rengini kullanGenellikle gerekmez
Bağımsız birincil eylem, bağımsız kapsül, segmentli kontrol kabuğuÇok hafif kontrol gölgesiKontrol yüzey rengini kullanGenellikle gerekmez
Araç çubuğu ve şeffaf dahili kontrollerYokKontrol yüzey rengini veya şeffaflığı kullanGenellikle gerekmez
Pazarlama sayfası veya oluşturulan site görsel kartıTema tarafından belirlenirİzin verilirKontrollü kullanım

Bileşen Eşlemesi

  • <Card> varsayılan olarak layer="content" kullanır: paylaşımlı birinci düzey hafif gölge, kenarlık yok, varsayılan 20px köşe yuvarlaklığı; muted, iç içe, liste ve şeffaf varyantlar düz kalır.
  • <Card layer="shell">: Sayfa içinde yalnızca gruplamadan sorumludur, şeffaf veya hafif gradyan yüzey kullanır ve düz kalır; kalıcı çalışma alanı kabuğu, ait olduğu mod tarafından ayrı katman sağlar.
  • <Card shape="pill">: Kompakt tek satırlık kartlar için kullanılır, köşe yuvarlaklığı oval kapsül şeklindedir.
  • SidebarNavigation: Bağımsız çalışma alanı kabuğu, belirgin gradyan, şeffaflık, bulanıklık ve hafif gölgeyi korur.
  • Studio'nun PromptPanel çalışma alanı konteyneri olarak kullanıldığında: --workspace-shell-shadow kullanın.
  • DialogPanel, açılır menü, Popover, bağlam menüsü ve kavram gezgini: katman gölgesi kullanın.
  • Builder tuvali, cihaz önizlemesi, oluşturulan site önizlemesi, sürükleme önizlemesi ve yakınlaştırma durumu: bağımsız önizleme düzlemini veya geçici etkileşim katmanını temsil ettiğinden özel gölgeyi koruyabilir.

İç içe katmanlı içerik kartları oluşturmayın. Dış gruplama gerçekten gerekiyorsa, düz bir kabuk olmalıdır. Gerçek katmanlar dışında, aynı DOM ata zincirinde en fazla bir normal içerik veya kontrol gölgesi bulunmalıdır.

Tasarım Değişkenleri (Token) Kullanımı

Paylaşımlı Token'ları önceliklendirin, efektleri sabit kodlamayın:

  • İçerik kartı gölgesi: --card-shadow: var(--qk-shadow-surface)
  • İçerik kartı hover gölgesi: --card-shadow-hover: var(--qk-shadow-surface-hover)
  • Alan gölgesi: --input-shadow: var(--qk-shadow-field)
  • Alan etkin gölgesi: --input-state-shadow: var(--qk-shadow-field-active)
  • Kontrol gölgesi: --qk-shadow-control / --qk-shadow-control-hover
  • Birincil eylem kontrol gölgesi: --qk-shadow-control-accent / --qk-shadow-control-accent-hover
  • İçerik kartı bulanıklığı: --card-backdrop-filter: none
  • Kabuk yüzeyi: --card-shell-surface
  • Kabuk bulanıklığı: --card-shell-backdrop-filter
  • Çalışma alanı kabuğu gölgesi: --workspace-shell-shadow
  • Dialog yüzeyi: --dialog-surface, kontrollü tema gradyanı sağlar
  • Dialog bulanıklığı: --dialog-backdrop-filter
  • Dialog katman gölgesi: --dialog-shadow
  • Dialog köşe yuvarlaklığı: --card-radius yeniden kullanılır
  • Klavye odağı: --focus-ring
  • Katman gölgesi: Mevcut Dialog, Dropdown, Menu veya sayfa düzeyi katman Token'ını kullanın

Normal içerik kartları ve çalışma alanı panelleri daha güçlü genel --shadow Token'ını kullanmamalıdır.

Genel gölgeler "kısa yer değiştirme, düşük opaklık, yerleşim katmanına göre artan" sessiz bir ölçek kullanır. Normal Card, alan ve kontroller rota içinde paylaşımlı gölgeleri koyulaştırmamalı veya büyütmemelidir; Popover ve Dialog, sayfa düzeyi katman Token'ını kullanır.

Etkileşim Kuralları

Hover

  • İçerik kartları --qk-shadow-surface-hover üzerindeki katmana yükseltilmemelidir.
  • translateY ile içerik kartlarını yükseltmeyin.
  • Hafif arka plan değişikliği veya net kontrol geri bildirimi kullanın.
  • Şekli değiştirmeyin, tutarsız köşe yuvarlaklığı veya gölge kırpılmasından kaçının.

Seçili ve Etkin

  • Vurgu rengi yüzeyi, ikon durumu, anlamsal durum veya kontrollü gradyan kullanın.
  • Durumu yalnızca gölge ile ifade etmeyin.

Klavye Odağı

  • Paylaşımlı focus-visible kuralını veya --focus-ring kullanın.
  • Genel kart gölgesi odak ipucunun yerine geçemez.
  • Açık ve koyu temalarda net görünür olmalıdır.

Sürükleme ve Yakınlaştırma

  • Yalnızca katman hareket halindeyken veya yeniden boyutlandırılırken daha güçlü gölgeye izin verilir.
  • Etkileşim bittikten sonra geçici gölge kaldırılmalıdır.
  • Taşan konteynerler, hareket eden katmanın geri bildirim efektini kırpamaz.

Şeffaflık ve Arka Plan Bulanıklığı

Şeffaflık, dış yüzey ile çalışma alanı arasındaki aidiyeti ifade etmek için kullanılır. Arka plan bulanıklığı yalnızca yüzeyin arkasında gerçekten görünür içerik, renk veya görsel olduğunda anlam ifade eder.

  • Düz renk arka planda bulanıklık kullanmayın, yalnızca işleme maliyetini artırır ve katmanlaşmayı ifade etmez.
  • Arkasındaki arka plan ne olursa olsun, metin, ikon ve kontroller net okunabilir olmalıdır.
  • Tarayıcı arka plan bulanıklığını desteklemediğinde, opak veya okunabilir bir yedek arka plan olmalıdır.
  • Yoğun çalışma arayüzlerinde bulanıklık yoğunluğu kontrollü olmalıdır.
  • Hem açık hem de koyu tema doğrulanmalıdır.

Gölge Korunmasına İzin Verilen İstisnalar

  • Çalışma alanı kenar çubuğu kabuğu
  • Dialog, Popover, Dropdown, menüler ve modal paneller
  • Studio kavram gezgini ve onay katmanı
  • Builder tuvali, cihaz çerçevesi ve oluşturulan site önizleme düzlemi
  • Sürükleme önizlemesi, yakınlaştırma geri bildirimi ve geçici yükleme araçları
  • Paylaşımlı düğme Token'ında gölge tanımlanmış birincil eylem düğmeleri
  • Mevcut tema tarafından kontrol edilen pazarlama sayfası ve oluşturulan site görsel öğeleri

Bu istisnalar, geniş seçiciler veya paylaşımlı Token'lar aracılığıyla normal içerik kartlarını etkileyemez.

İnceleme Kontrol Listesi

  • Bağımsız düz renk içerik kartları ve giriş alanları yalnızca paylaşımlı birinci düzey hafif gölge rolünü kullanır.
  • Bağımsız birincil eylemler, bağımsız kapsüller ve segmentli kontrol kabukları yalnızca paylaşımlı çok hafif kontrol gölgesini kullanır.
  • Sayfa gruplaması, liste satırları, iç içe kartlar, şeffaf gruplar, tekrarlanan Tab/Pill, araç çubukları ve bileşik kontrol dahili öğeleri düz kalır.
  • Araç çubuğundaki arama, filtreleme, sıralama, görünüm ve satır içi birincil eylemler düz kalır; normal giriş alanlarının hafif gölgesi araç çubuğuna sızamaz, klavye odak halkası hariç.
  • Segmented, zaten gölgeli bir kart, dialog veya araç çubuğu içinde olduğunda, kabuk ve seçili öğe düz kalır; fare tıklaması klavye odak halkası göstermez.
  • Gerçek katmanlar dışında, aynı ata zincirinde birden fazla normal gölge birleştirilmez.
  • hover, içerik kartını dikey olarak hareket ettirmez.
  • İç içe içerik kartları kaldırılmış veya dış katman açıkça kabuk olarak tanımlanmış.
  • Yalnızca gerçek kabuklar --workspace-shell-shadow kullanır.
  • Yalnızca gerçek katmanlar ve geçici etkileşim katmanları daha güçlü gölge kullanır.
  • Arka plan bulanıklığının arkasında görünür içerik var ve okunabilir bir yedek arka plan mevcut.
  • focus-visible odak halkası kullanır.
  • Açık ve koyu temalarda yeterli kontrast korunur.
  • Köşe yuvarlaklı yüzeyler hover, focus, sürükleme veya katman geri bildirimini kırpma.
  • Masaüstü ve mobil genişliklerde yeni yatay taşma oluşmaz.
  • npm run ui:check-card-surfaces --workspace @qokit-ai/web kontrolü geçti.

Bu Sayfada