Kartu dan Hierarki Permukaan
Aturan penggunaan kartu konten, Shell area kerja, lapisan mengambang, bayangan, dan efek buram latar belakang.
Kartu konten tetap datar; cangkang luar menyampaikan pengelompokan ruang kerja.
Kartu konten standar tidak menggunakan bayangan luar.
Pemilihan dan status disampaikan melalui warna dan hierarki informasi.
Spesifikasi Material dan Hierarki Kartu
Dokumen ini menjelaskan secara terbuka kapan antarmuka Qokit menggunakan bayangan, transparansi, gradien, dan efek buram latar belakang. Berlaku untuk ekstensi platform, Builder, CMS, Dashboard, Studio, dan Admin. Halaman pemasaran dan situs hasil generate dapat lebih ekspresif, namun efek harus tetap mengikuti tema saat ini dan memastikan konten tetap mudah dibaca.
Prinsip Utama
Efek visual digunakan untuk mengekspresikan struktur, bukan untuk mendekorasi setiap blok:
- Konten dibedakan melalui perbedaan warna latar belakang.
- Wadah mengekspresikan keanggotaan melalui transparansi atau gradien yang terkendali.
- Lapisan mengambang mengekspresikan hierarki melalui bayangan.
- Interaksi mengekspresikan status melalui warna dan cincin fokus.
Kartun solid independen dan input menggunakan bayangan tingkat pertama yang sama; daftar, permukaan bersarang, dan grup transparan tetap datar; hanya lapisan mengambang yang sebenarnya yang menggunakan bayangan yang jelas.
Urutan Penilaian
Sebelum menambahkan efek material, tentukan peran permukaan terlebih dahulu:
- Apakah ini kartu solid independen atau input? Gunakan bayangan permukaan atau bidang tingkat pertama yang sama.
- Apakah ini baris daftar, kartu bersarang, opsi berulang, atau grup transparan? Tetap datar.
- Apakah ini mengelompokkan beberapa kartu konten internal menjadi satu area kerja? Gunakan Shell.
- Apakah ini menutupi konten halaman atau muncul di atas bidang saat ini? Gunakan bayangan lapisan mengambang.
- Apakah ini dalam keadaan seret, zoom, atau mengambang sementara? Gunakan bayangan sementara.
- Apakah ini hanya untuk mengekspresikan hover, terpilih, atau fokus? Gunakan peran hover yang sama, warna latar belakang interaksi, dan cincin fokus.
Jangan menumpuk bayangan, transparansi, gradien, dan efek buram secara bersamaan kecuali peran permukaan memang memerlukannya.
Matriks Skenario
| Peran Permukaan | Bayangan | Transparansi atau Gradien | Efek Buram Latar Belakang |
|---|---|---|---|
| Kartu konten solid independen, kartu metrik | Bayangan ringan tingkat pertama yang sama | Perbedaan warna latar belakang ringan diizinkan | Tidak ada |
| Baris daftar, kartu bersarang, grup transparan, opsi berulang | Tidak ada | Perbedaan warna latar belakang ringan diizinkan | Tidak ada |
| Shell grup dalam halaman | Tidak ada | Direkomendasikan | Biasanya tidak diperlukan |
| Sidebar atau Shell area kerja tetap | Ringan | Direkomendasikan | Diizinkan jika ada konten yang terlihat di belakangnya |
| Dialog, Popover, Dropdown, menu konteks | Bayangan lapisan mengambang yang jelas | Latar belakang harus cukup solid untuk memastikan keterbacaan | Diizinkan |
| Pratinjau seret, keadaan zoom, pratinjau mengambang | Sementara lebih kuat | Opsional | Biasanya tidak diperlukan |
| Hover | Tetap atau perkuat sedikit bayangan tingkat pertama | Dapat mengubah latar belakang | Tidak berubah |
| Status terpilih atau aktif | Tidak ada | Latar belakang warna aksen atau gradien terkendali | Tidak berubah |
| Input, kotak pencarian | Bayangan bidang yang sangat ringan | Gunakan warna permukaan kontrol | Biasanya tidak diperlukan |
| Aksi utama independen, kapsul independen, wadah kontrol tersegmentasi | Bayangan kontrol yang sangat ringan | Gunakan warna permukaan kontrol | Biasanya tidak diperlukan |
| Toolbar dan kontrol lapisan transparan internal | Tidak ada | Gunakan warna permukaan kontrol atau transparan | Biasanya tidak diperlukan |
| Kartu visual halaman pemasaran atau situs hasil generate | Ditentukan oleh tema | Diizinkan | Gunakan dengan terkendali |
Pemetaan Komponen
<Card>secara default menggunakanlayer="content": bayangan ringan tingkat pertama yang sama, tanpa batas, sudut bulat20pxdefault; varian muted, bersarang, daftar, dan transparan tetap datar.<Card layer="shell">: hanya bertanggung jawab untuk pengelompokan dalam halaman, menggunakan permukaan transparan atau gradien ringan dan tetap datar; Shell area kerja tetap menyediakan hierarki secara terpisah sesuai mode.<Card shape="pill">: digunakan untuk kartu baris tunggal yang ringkas, dengan sudut bulat berbentuk kapsul elips.SidebarNavigation: Shell area kerja independen, mempertahankan gradien, transparansi, efek buram, dan bayangan ringan yang jelas.PromptPanelStudio saat digunakan sebagai wadah area kerja: gunakan--workspace-shell-shadow.DialogPanel, menu dropdown, Popover, menu konteks, dan penjelajah konsep: gunakan bayangan lapisan mengambang.- Kanvas Builder, pratinjau perangkat, pratinjau situs hasil generate, pratinjau seret, dan keadaan zoom: karena mewakili bidang pratinjau independen atau lapisan interaksi sementara, dapat mempertahankan bayangan khusus.
Jangan membuat kartu konten yang mengambang berlapis-lapis. Jika pengelompokan luar memang diperlukan, harus berupa Shell yang datar. Selain lapisan mengambang yang sebenarnya, hanya satu bayangan konten atau kontrol biasa yang boleh muncul dalam rantai DOM ancestor yang sama.
Penggunaan Variabel Desain (Token)
Utamakan penggunaan Token bersama, jangan meng-hardcode efek:
- Bayangan kartu konten:
--card-shadow: var(--qk-shadow-surface) - Bayangan hover kartu konten:
--card-shadow-hover: var(--qk-shadow-surface-hover) - Bayangan bidang:
--input-shadow: var(--qk-shadow-field) - Bayangan bidang aktif:
--input-state-shadow: var(--qk-shadow-field-active) - Bayangan kontrol:
--qk-shadow-control/--qk-shadow-control-hover - Bayangan kontrol aksi utama:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - Efek buram kartu konten:
--card-backdrop-filter: none - Permukaan Shell:
--card-shell-surface - Efek buram Shell:
--card-shell-backdrop-filter - Bayangan Shell area kerja:
--workspace-shell-shadow - Permukaan Dialog:
--dialog-surface, menyediakan gradien tema yang terkendali - Efek buram Dialog:
--dialog-backdrop-filter - Bayangan lapisan mengambang Dialog:
--dialog-shadow - Sudut bulat Dialog: gunakan kembali
--card-radius - Fokus keyboard:
--focus-ring - Bayangan lapisan mengambang: gunakan Token lapisan mengambang Dialog, Dropdown, Menu, atau tingkat halaman yang sudah ada
Kartu konten biasa dan panel area kerja tidak boleh menggunakan Token --shadow umum yang lebih kuat.
Bayangan global menggunakan skala tenang dengan "pergeseran pendek, transparansi rendah, meningkat sesuai tingkat penempatan". Card, bidang, dan kontrol biasa tidak boleh memperdalam atau memperbesar bayangan bersama dalam rute; Popover dan Dialog mengekspresikan pemisahan dari halaman melalui pergeseran dan jangkauan blur yang lebih besar, bukan dengan menumpuk kabut abu-abu gelap.
Aturan Interaksi
Hover
- Kartu konten tidak boleh dinaikkan ke tingkat di atas
--qk-shadow-surface-hover. - Jangan menaikkan kartu konten melalui
translateY. - Gunakan perubahan latar belakang ringan atau umpan balik kontrol yang jelas.
- Jangan mengubah bentuk, hindari sudut bulat yang tidak konsisten atau pemotongan bayangan.
Terpilih dan Aktif
- Gunakan permukaan warna aksen, status ikon, status semantik, atau gradien terkendali.
- Jangan mengekspresikan status hanya melalui bayangan.
Fokus Keyboard
- Gunakan aturan focus-visible bersama atau
--focus-ring. - Bayangan kartu umum tidak boleh menggantikan petunjuk fokus.
- Harus terlihat jelas di tema terang dan gelap.
Seret dan Zoom
- Hanya gunakan bayangan yang lebih kuat saat lapisan sedang dipindahkan atau diubah ukurannya.
- Bayangan sementara harus dihapus setelah interaksi selesai.
- Wadah overflow tidak boleh memotong efek umpan balik lapisan yang bergerak.
Transparansi dan Efek Buram Latar Belakang
Transparansi digunakan untuk mengekspresikan hubungan keanggotaan antara permukaan luar dan area kerja. Efek buram latar belakang hanya bermakna jika memang ada konten, warna, atau gambar yang terlihat di belakang permukaan.
- Jangan gunakan efek buram pada latar belakang solid, hanya menambah biaya rendering tanpa mengekspresikan hierarki.
- Teks, ikon, dan kontrol harus tetap mudah dibaca terlepas dari latar belakang apa pun di belakangnya.
- Jika browser tidak mendukung efek buram latar belakang, harus ada latar belakang fallback yang tidak transparan atau mudah dibaca.
- Intensitas blur pada antarmuka kerja yang padat harus terkendali.
- Harus memvalidasi tema terang dan gelap secara bersamaan.
Pengecualian yang Diizinkan Mempertahankan Bayangan
- Shell sidebar area kerja
- Dialog, Popover, Dropdown, menu, dan panel modal
- Penjelajah konsep Studio dan lapisan konfirmasi mengambang
- Kanvas Builder, bingkai perangkat, dan bidang pratinjau situs hasil generate
- Pratinjau seret, umpan balik zoom, dan alat mengambang sementara
- Tombol aksi utama yang bayangannya sudah didefinisikan oleh Token tombol bersama
- Elemen visual halaman pemasaran dan situs hasil generate yang dikendalikan oleh tema saat ini
Pengecualian ini tidak boleh memengaruhi kartu konten biasa melalui selektor luas atau Token bersama.
Daftar Periksa
- Kartu konten solid independen dan input hanya menggunakan peran bayangan ringan tingkat pertama yang sama.
- Aksi utama independen, kapsul independen, dan wadah kontrol tersegmentasi hanya menggunakan bayangan kontrol sangat ringan yang sama.
- Grup halaman, baris daftar, kartu bersarang, grup transparan, Tab/Pill berulang, toolbar, dan item internal kontrol komposit tetap datar.
- Pencarian, filter, sortir, tampilan, dan aksi utama inline dalam toolbar tetap datar; bayangan ringan input biasa tidak boleh bocor ke toolbar, kecuali cincin fokus keyboard.
- Saat Segmented berada di dalam kartu, dialog, atau toolbar yang sudah memiliki bayangan, wadah dan item terpilih tetap datar; klik mouse tidak menampilkan cincin fokus keyboard.
- Selain lapisan mengambang yang sebenarnya, jangan menumpuk beberapa bayangan biasa dalam rantai ancestor yang sama.
- Hover tidak memindahkan kartu konten secara vertikal.
- Kartu konten bersarang telah dihapus, atau lapisan luar telah didefinisikan secara eksplisit sebagai Shell.
- Hanya Shell yang sebenarnya yang menggunakan
--workspace-shell-shadow. - Hanya lapisan mengambang yang sebenarnya dan lapisan interaksi sementara yang menggunakan bayangan yang lebih kuat.
- Ada konten yang terlihat di belakang efek buram latar belakang, dan ada latar belakang fallback yang mudah dibaca.
- focus-visible menggunakan cincin fokus.
- Tema terang dan gelap keduanya mempertahankan kontras yang cukup.
- Permukaan bersudut bulat tidak memotong umpan balik hover, fokus, seret, atau lapisan mengambang.
- Lebar desktop dan mobile tidak menghasilkan overflow horizontal baru.
- Pemeriksaan
npm run ui:check-card-surfaces --workspace @qokit-ai/weblulus.