Kart ve Yüzey Katmanları
İçerik kartları, çalışma alanı kabuğu, katmanlar, gölgeler ve arka plan bulanıklığı kullanım kuralları.
İçerik kartları düz kalır; dış kabuk çalışma alanı gruplamasını iletir.
Standart içerik Kartı, dış gölge kullanmaz.
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:
- Bağımsız düz renk kart veya giriş alanı mı? Paylaşımlı birinci düzey yüzey veya alan gölgesi kullanın.
- Liste satırı, iç içe kart, tekrarlanan seçenek veya şeffaf grup mu? Düz tutun.
- Birden fazla dahili içerik kartını bir çalışma alanı olarak mı düzenliyor? Kabuk (Shell) kullanın.
- Sayfa içeriğini mi kaplıyor veya mevcut düzlemin üzerinde mi görünüyor? Katman gölgesi kullanın.
- Sürükleme, yakınlaştırma veya geçici yükleme durumunda mı? Geçici gölge kullanın.
- 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 Gradyan | Arka Plan Bulanıklığı |
|---|---|---|---|
| Bağımsız düz renk içerik kartı, metrik kartı | Paylaşımlı birinci düzey hafif gölge | Hafif arka plan renk farkına izin verilir | Yok |
| Liste satırı, iç içe kart, şeffaf grup, tekrarlanan seçenek | Yok | Hafif arka plan renk farkına izin verilir | Yok |
| Sayfa içi gruplama kabuğu | Yok | Önerilir | Genellikle gerekmez |
| Kenar çubuğu veya kalıcı çalışma alanı kabuğu | Hafif | Önerilir | Arkasında görünür içerik olduğunda izin verilir |
| Dialog, Popover, Dropdown, bağlam menüsü | Belirgin katman gölgesi | Arka 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 önizlemesi | Geçici olarak daha güçlü | İsteğe bağlı | Genellikle gerekmez |
| Hover | Birinci düzey gölgeyi koru veya hafifçe güçlendir | Arka plan değiştirilebilir | Değişmez |
| Seçili veya etkin durum | Yok | Vurgu rengi arka planı veya kontrollü gradyan | Değişmez |
| Giriş alanı, arama kutusu | Çok hafif alan gölgesi | Kontrol yüzey rengini kullan | Genellikle gerekmez |
| Bağımsız birincil eylem, bağımsız kapsül, segmentli kontrol kabuğu | Çok hafif kontrol gölgesi | Kontrol yüzey rengini kullan | Genellikle gerekmez |
| Araç çubuğu ve şeffaf dahili kontroller | Yok | Kontrol yüzey rengini veya şeffaflığı kullan | Genellikle gerekmez |
| Pazarlama sayfası veya oluşturulan site görsel kartı | Tema tarafından belirlenir | İzin verilir | Kontrollü kullanım |
Bileşen Eşlemesi
<Card>varsayılan olaraklayer="content"kullanır: paylaşımlı birinci düzey hafif gölge, kenarlık yok, varsayılan20pxköş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-shadowkullanı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-radiusyeniden 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. translateYile 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-ringkullanı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-shadowkullanı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/webkontrolü geçti.