Skip to Content
Desain

Kartu dan Hierarki Permukaan

Aturan penggunaan kartu konten, Shell area kerja, lapisan mengambang, bayangan, dan efek buram latar belakang.

Komponen langsungLapisan Kartu

Kartu konten tetap datar; cangkang luar menyampaikan pengelompokan ruang kerja.

Ringkasan proyekKesiapan peluncuran
Konten12 halaman selesai

Kartu konten standar tidak menggunakan bayangan luar.

CekSiap mobile

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:

  1. Apakah ini kartu solid independen atau input? Gunakan bayangan permukaan atau bidang tingkat pertama yang sama.
  2. Apakah ini baris daftar, kartu bersarang, opsi berulang, atau grup transparan? Tetap datar.
  3. Apakah ini mengelompokkan beberapa kartu konten internal menjadi satu area kerja? Gunakan Shell.
  4. Apakah ini menutupi konten halaman atau muncul di atas bidang saat ini? Gunakan bayangan lapisan mengambang.
  5. Apakah ini dalam keadaan seret, zoom, atau mengambang sementara? Gunakan bayangan sementara.
  6. 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 PermukaanBayanganTransparansi atau GradienEfek Buram Latar Belakang
Kartu konten solid independen, kartu metrikBayangan ringan tingkat pertama yang samaPerbedaan warna latar belakang ringan diizinkanTidak ada
Baris daftar, kartu bersarang, grup transparan, opsi berulangTidak adaPerbedaan warna latar belakang ringan diizinkanTidak ada
Shell grup dalam halamanTidak adaDirekomendasikanBiasanya tidak diperlukan
Sidebar atau Shell area kerja tetapRinganDirekomendasikanDiizinkan jika ada konten yang terlihat di belakangnya
Dialog, Popover, Dropdown, menu konteksBayangan lapisan mengambang yang jelasLatar belakang harus cukup solid untuk memastikan keterbacaanDiizinkan
Pratinjau seret, keadaan zoom, pratinjau mengambangSementara lebih kuatOpsionalBiasanya tidak diperlukan
HoverTetap atau perkuat sedikit bayangan tingkat pertamaDapat mengubah latar belakangTidak berubah
Status terpilih atau aktifTidak adaLatar belakang warna aksen atau gradien terkendaliTidak berubah
Input, kotak pencarianBayangan bidang yang sangat ringanGunakan warna permukaan kontrolBiasanya tidak diperlukan
Aksi utama independen, kapsul independen, wadah kontrol tersegmentasiBayangan kontrol yang sangat ringanGunakan warna permukaan kontrolBiasanya tidak diperlukan
Toolbar dan kontrol lapisan transparan internalTidak adaGunakan warna permukaan kontrol atau transparanBiasanya tidak diperlukan
Kartu visual halaman pemasaran atau situs hasil generateDitentukan oleh temaDiizinkanGunakan dengan terkendali

Pemetaan Komponen

  • <Card> secara default menggunakan layer="content": bayangan ringan tingkat pertama yang sama, tanpa batas, sudut bulat 20px default; 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.
  • PromptPanel Studio 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/web lulus.

Di halaman ini