Pembaruan Kontrak Desain
Catatan perubahan untuk Token Desain, API Komponen, dan Kontrak Integrasi yang dipublikasikan oleh Qokit.
Pembaruan Kontrak Desain
2026-10-21 · Tindakan tetap dalam menu yang dapat digulir
ActionItem.pinned menerima start atau end agar tindakan dan ActionMenu.dropdownHeader tetap di luar daftar gulir. Navigasi keyboard dan pemilihan mencakup semua wilayah. Host portal dapat membatasi tinggi dengan --qk-menu-available-height, yang diukur pada sisi pemicu yang dipilih. Tanpa pinned, struktur menu yang ada tetap dipertahankan.
2026-10-17 · Titik masuk kustomisasi widget
Kustomisasi widget halaman menggunakan titik masuk header bersama di seluruh Proyek, Konten, dan dasbor. CustomizableWidgetLayoutControls menambahkan opsi customizeButtonRef dan disabledCustomize; kontrol lipatan bersifat opsional. CustomizableWidgetLibrary berbagi geometri seluler, fokus awal, Escape, dan pengembalian fokus di seluruh host. Persistensi widget dan perintah tetap dimiliki oleh host. Lihat integrasi kustomisasi widget.
2026-10-17 · Kontrol panel workbench terkelola
WorkspaceHeaderPortal menerima opsi startControl dan endControl, dengan target host opsional yang sesuai. Tampilan Files Terkelola menggunakan slot panel header dan geometri area kerja yang sama dengan pengeditan dan pratinjau aset tunggal. Host yang ada dapat terus menyediakan judul, status, dan tindakan saja. Lihat integrasi EditorHeader.
2026-10-17 · Default editor terukur
useWorkspaceResponsiveProfile menambahkan opsi onWidthChange(width) untuk pengukuran area kerja yang tersedia. useEditorLayout sekarang menerapkan batas lebar bersama yang dikonfigurasi ke penyimpanan host juga, dan readEditorLayout menerima batas opsional sebagai argumen keempatnya. Pemanggil yang ada mempertahankan default mereka. Lihat Integrasi Komponen.
2026-09-26 · Creator · Skema gaya
Jarak terperinci · v3: site.theme.spacingOverrides 按 desktop/tablet/mobile → sectionPadding (0–240px), pageGutter, cardGap (0–96px). --qk-site-custom-{sectionPadding|pageGutter|cardGap}-{desktop|tablet|mobile}. 980px / 720px.
Tombol dan tautan: primaryButtonStyle, secondaryButtonStyle (solid/outline), buttonFontSize (12–24px), linkUnderline (always/hover/none), linkHoverStyle (none/tint). --qk-site-{primary|secondary}-button-{background|color|border|shadow}, --qk-site-button-font-size, --qk-site-button-size-{sm|md|lg}, --qk-site-link-decoration, --qk-site-link-hover-decoration, --qk-site-link-hover-background. initial → Otomatis.
Warna lanjutan: mutedColor, borderColor, buttonTextColor, cardSurfaceColor 与对应 dark* 字段 (--qk-site-color-card-rgb).
2026-09-09 · Pintasan navigasi global
SidebarNavigation / WorkspaceNavigationMenu: Navigasi global memakai Command+\ di Mac atau Control+\ di Windows/Linux, termasuk secara mandiri di Creator. T dan Shift+T tetap mengatur tata letak editor. Target yang dapat diedit, komposisi teks, pengulangan, dan kejadian yang sudah ditangani diabaikan.
2026-09-08 · EmptyState
Panduan pembuatan proyek dan artikel/produk CMS berbagi EmptyState: terpusat, transparan, ringkas, dengan aksi yang dapat membungkus baris. icon, layout, style, dan description bersifat opsional. Judul memakai h2; pindahkan selektor strong khusus ke slot skin title. Aksi memakai wadah bersama. Izin dan pembuatan tetap dikelola host.
2026-09-08 · SidebarNavigation
SidebarNavigation memuat awal rute dengan asal yang sama setelah penunjuk berhenti 180 ms atau saat fokus keyboard. Navigasi tetap dan popup berbagi batas 8 tujuan per 30 detik. Pemuatan awal berhenti saat offline, tab tersembunyi, Save-Data atau 2G; unduhan, tautan nonaktif, jendela baru dan jangkar halaman yang sama dikecualikan. Navigasi dan perlindungan perubahan tetap berlaku.
2026-09-08 - Primary button foreground
Tombol utama berbentuk pil mempertahankan biru Logo #4695D8 dengan teks, ikon, dan indikator pemuatan putih pada kedua tema. Hover tetap sedikit lebih terang. Tombol sekunder dan bahaya mempertahankan warna semantiknya.
2026-09-07 - AccountDropdown / SidebarProfile
AccountDropdown menerima opsi compact dan preferences: mode ringkas menyembunyikan pengenal dan riwayat pembuatan; secara default konten lama dipertahankan. Appearance dan Language menerima triggerRole="menuitem" dalam menu akun. Navigasi keyboard memulihkan fokus dan dialog bahasa bertingkat menangani Escape sendiri. SidebarNavigation.searchEnabled bernilai true secara default; gunakan false untuk navigasi singkat dan tetap. SidebarProfile dengan href tanpa menu membuka tujuan yang sama dalam mode terbuka dan ikon.
2026-09-07 - FormField / AdminEntityDialog / EditorWorkspace
Formulir berbagi skala huruf dan membungkus teks panjang, mempertahankan bentuk pil dan warna merek. FormField menamai grup: controlId dan id di dalam menghubungkan label. SearchField mengembalikan fokus setelah dihapus. Segmented dan ControlMenu mendukung opsi nonaktif; item ActionMenu nonaktif tidak memiliki tautan. Tombol sibuk mempertahankan ukuran dan indikator. AdminEntityDialog memvalidasi kolom wajib, email, dan JSON, memfokuskan kesalahan, mencegah penyimpanan ganda, dan mempertahankan input saat gagal. EditorWorkspace menyediakan ref.focusControl(element) untuk menampilkan panel tersembunyi sebelum memfokuskan. Pengurangan gerak menonaktifkan transisi kontrol. WorkspaceDialog menggulir konten panjang dengan judul dan tindakan tetap terlihat; dialog seluler pendek mengikuti tinggi konten.
2026-09-07 · WorkspaceLocationSync / ProjectSwitcher
Setelah perpindahan rute selesai, WorkspaceLocationSync menutup pemilih ruang sementara agar alat tujuan langsung terlihat. Preferensi pencarian dan bagian tetap tersimpan. Nama cakupan dan konteks ditampilkan pada baris terpisah; nama panjang di header dipotong di dalam tombol.
2026-09-07 · Navigasi terpadu dan permukaan membulat Qokit
WorkspaceNavigationDock memakai kembali navigasi dan izin host melalui items, fallback, className, dan onClickCapture, tanpa memuat sesi tambahan. Preferensi terbuka, ikon, atau tersembunyi tetap dibagikan; hingga 860px menggunakan laci navigasi. PlatformHeader.leadingContext juga muncul di EditorHeader. Tombol kapsul dan permukaan membulat tetap dipertahankan, sedangkan bingkai berulang dihapus.
Di desktop, mengeklik menu menyembunyikan bilah sisi atau memulihkan mode tampilan terakhirnya. Menyeret menu atau tepi bilah sisi beralih antara tersembunyi, hanya ikon, dan diperluas. Tombol panah kiri/kanan mengikuti arah baca. Membatalkan seretan mempertahankan preferensi tersimpan; perangkat seluler tetap menggunakan panel navigasi.
Pasang WorkspaceLocationSync sekali di bawah Suspense dalam layout Next. useWorkspaceQueryState(key, defaultValue, validate) mengembalikan [value, setValue, ready]; useWorkspaceQueryRecord(key, defaults, validators) hanya memulihkan filter datar yang dinyatakan. Jangan menyimpan kredensial atau draf dalam URL. WorkspacePage memulihkan posisi gulir sesi dengan batas penyimpanan; area dalam menggunakan data-workspace-scroll-region dan WorkspaceScrollRestoration. Navigasi mundur/maju asli yang dapat dibatalkan memakai perlindungan keluar tanpa menambah riwayat. AdminEntityDialog mempertahankan input setelah kegagalan dan render ulang; versi dan hasil simpan tetap milik host.
Tipografi pengelolaan memakai peran tetap: judul halaman 20px/650, bagian 16px/600, teks dan navigasi 14px, label 13px, keterangan 12px. --qk-workspace-body-ink dan --qk-workspace-active-ink berasal dari warna yang ada.
Tombol utama berbentuk pil memakai biru Logo #4695D8 langsung melalui --accent-action, tanpa gradasi gelap. Hover menambahkan 8% putih; label memakai warna tinta merek dengan 10% hitam agar terbaca. Sorotan navigasi mempertahankan biru yang sama dan teks sesuai tema.
Dropdown dan pemilih ruang kerja memakai --menu-option-font-size (14px) serta --menu-option-font-weight (500), dengan tinggi baris 1.45; pilihan aktif memakai 600 dan metadata 12px/400. WorkspaceNavigationDock memuat tujuan dengan origin yang sama saat kursor diarahkan atau fokus keyboard, dengan deduplikasi terbatas. Perlindungan saat keluar dan rute host tetap berlaku.
2026-09-07 - ColumnLayout
ColumnLayout memenuhi jendela pengelolaan dengan navigasi tetap, area gulir terpisah, dan bilah alat halaman yang melekat di atas. WorkspacePage memakai bagian datar dan Token radius bersama. Pada 860px ke bawah, navigasi tetap berupa laci yang tidak interaktif saat ditutup. Properti dan perilaku bisnis tidak berubah. Hapus margin luar ganda dan batasi lebar baca di dalam formulir.
2026-09-05 · WorkspaceNavigationMenu / WorkspacePageHeader
Ruang kerja setelah masuk memakai PlatformHeader.workspaceActions untuk berbagi area akun dan navigasi pada setiap lebar. WorkspacePageHeader menyatukan judul dan tindakan. WorkspaceNavigationMenu menampilkan bilah samping saat ini beserta izin dan konteksnya; EditorNavigationMenu tetap menjadi alias yang kompatibel. Studio mempertahankan bilah alatnya. Header publik mempertahankan tampilannya.
WorkspaceNavigationGuard melindungi navigasi global melalui dirty, busy, error, dan onSave opsional. Pengguna hanya boleh keluar setelah penyimpanan terkonfirmasi mengembalikan true; kegagalan mempertahankan draf. Language.onBeforeChange(apply) memungkinkan perlindungan yang sama sebelum mengganti bahasa. Nonaktifkan bidang formulir saat menyimpan.
2026-09-05 · EditorNavigationMenu
EditorNavigationMenu menggunakan seluruh SidebarNavigation aplikasi dalam panel lapisan dengan izin dan konteks proyek tanpa menggeser kanvas. Bahasa dan tema berada di bawah; submenu menangani Escape terlebih dahulu. Pada lebar hingga 1120px, header memakai dua baris dan menu menampilkan nama tampilan aktif. Fokus dan layar penuh browser berdiri sendiri. Navigasi menunggu penyimpanan yang berlangsung dan melindungi draf.
2026-09-05 · EditorHeader
EditorHeader mempertahankan logo, akun, dan menu global aplikasi dalam editor aktif. startControl dan endControl mengontrol panel samping, center memuat perintah tampilan, dan actions memuat tindakan simpan. PlatformHeader.editorActions menggunakan kembali navigasi responsif, bahasa, dan tema. onNavigate harus menangani perubahan yang belum disimpan sebelum menjalankan callback. Pada layar sempit, header memakai dua baris; submenu menangani Escape terlebih dahulu.
2026-09-05 · SidebarToggleSlot
SidebarToggleSlot menempatkan tombol bilah samping di header ruang kerja. Gunakan satu slot dengan satu bilah samping kiri. SidebarNavigation tetap mengelola status, pintasan, dan panel seluler; tanpa slot, kontrol tetap di posisi semula. Tombol di header juga menutup panel seluler; setelah ditutup, fokus kembali ke tombol yang sama.
2026-09-05 · EditorWorkspace / Dialog / Segmented
view / onViewChange beralih antara edit, focus, dan preview tanpa mengganti editor. preview menyediakan pratinjau; previewPanel memakai panel yang ada. layout mendukung writing, structure, dan canvas. storageKey mengingat lebar dan panel yang dilipat, bukan dokumen.
onSaveAndClose mengembalikan true setelah penyimpanan dikonfirmasi, false saat gagal, handled jika aplikasi sudah berpindah, atau pending jika validasi membutuhkan keputusan. Kegagalan membuat editor tetap terbuka. Gunakan closeBehavior="collapse" hanya jika aplikasi mempertahankan draf. EditorSaveStatus menampilkan status terkonfirmasi. EditorViewControls, EditorLeaveDialog, dan useEditorLayout juga dapat digabungkan secara terpisah.
Perubahan keyboard: Segmented memiliki satu perhentian Tab dan memakai panah / Home / End. Dialog menghormati Escape yang ditangani lapisan anak; editor lalu keluar dari fokus atau pratinjau sebelum ditutup. LivePreviewToolbar.exitControl menerima kontrol tampilan bersama. Penyimpanan, penerbitan, dan izin tetap dikelola aplikasi.
2026-09 · EditorWorkspace
EditorWorkspace memadukan dialog layar penuh, pengelolaan fokus, dan panel responsif. dirty meminta konfirmasi sebelum membuang perubahan, busy mencegah penutupan saat menyimpan, dan onSave menangani Ctrl/Cmd+S. Aplikasi induk mengelola izin, data, penyimpanan, dan penerbitan.
2026-08 · Kepadatan Metrik Ringkas
- Menambahkan API opsional
density="compact"untukMetricCard, guna mendukung ruang kerja operasional berdensitas tinggi; - Mempertahankan kepadatan default dan semantik DOM yang ada tanpa perubahan;
- Menyatukan padding ringkas, skala nilai, dan tinggi minimum ke dalam gaya komponen bersama, sehingga rute tidak perlu lagi melakukan override visual.
2026-07 · Penyatuan Kontrol Formulir
- Menambahkan
FormField,Input,Textarea,Checkbox,RadioGroup, danSwitchke@qokit/components/ui; - Mengaitkan label, deskripsi, kesalahan, status wajib, dan referensi ARIA melalui kerangka
FormFieldbersama; - Menyatukan
Input,Textarea,Select, danSearchFieldke dalam ukuran 40px, 44px, 48px serta Token interaksi bersama; - Menambahkan resep Skin untuk platform, Admin, dan situs yang dihasilkan bagi komponen dasar formulir baru;
- Mempertahankan gaya
.qk-fieldyang ada sebagai jalur migrasi yang kompatibel ke belakang.
2026-07 · Tipografi Ukuran Tombol
- Menambahkan tiga Token semantik
--button-font-size-sm,--button-font-size-md, dan--button-font-size-lg; Buttonsekarang menggunakan ukuran teks tetap sebesar 14px, 15px, dan 16px untuksm,md, danlgsecara berurutan, tidak lagi mewarisi ukuran font dari Header, Dialog, atau kontainer halaman;- Jika Skin Situs perlu menyesuaikan tipografi tombol, seharusnya menimpa Token semantik yang sesuai, bukan menulis ulang
font-sizemelalui class rute.
2026-07 · Kerangka Navigasi Publik Platform
- Menambahkan
PlatformHeaderyang tidak bergantung pada login, di mana platform dan situs dokumentasi menggunakan kerangka semantik yang sama; - Menambahkan
PublicPlatformHeaderdanbuildPublicHeaderNavItems, di mana status anonim platform dan situs dokumentasi berbagi kombinasi Header publik yang sama serta konfigurasi navigasi; HeaderNavItemmenambahkan tipemenu, Header desktop menggunakan menu dropdown yang dapat ditutup, sedangkan Header mobile otomatis berkembang menjadi kelompok tautan;SiteFootermenambahkan opsibrandHrefdancontrols, mendukung skenario integrasi berbeda seperti dokumentasi publik;- Menambahkan
PublicPlatformFooter, di mana platform dan situs dokumentasi berbagi Shell Footer yang sama, dan memungkinkan resolusi lintas domain untuk tautan platform; - Semua ini adalah API opsional yang kompatibel ke belakang, logika status Header platform asli dan kontrol default Footer tetap tidak berubah.
2026-07 · Panduan Desain Publik
- Memisahkan kontrak desain publik dari spesifikasi implementasi AI internal;
- Mempublikasikan Token visual, impor komponen, batas Skeleton/Skin, Button, Card, dan persyaratan aksesibilitas;
- Menegaskan bahwa perubahan komponen yang bersifat breaking harus menyertakan panduan migrasi;
- Publikasi pencarian, Sitemap, dan output LLM hanya mencakup konten yang dapat diandalkan secara eksternal.
Keterangan Kompatibilitas
-
Penambahan properti opsional, slot Skin, dan Token semantik biasanya menjaga kompatibilitas ke belakang;
-
Penghapusan atau penamaan ulang properti, serta perubahan perilaku DOM/semantik/keyboard default merupakan perubahan breaking;
-
Perubahan breaking akan menjelaskan cakupan dampak, API alternatif, dan langkah migrasi di halaman ini.
-
2026-09-06: Navigasi desktop mempertahankan mode diperluas dan ikon serta menambahkan sembunyi otomatis. SidebarNavigation / WorkspaceNavigationMenu / Dialog
-
2026-09-06: EditorViewControls memisahkan Edit/Fokus dari layar penuh bawaan. EditorViewControls
-
2026-09-06:
LanguagedanAppearance variant="menu"mendukunglayout="row"untuk menampilkan label, nilai saat ini, dan panah. Tata letak ringkas bawaan dan perlindungan perubahan bahasa tetap berlaku.SiteHeaderCopy.helpResourcesdancontactSupportdapat memberi nama tautan bantuan ruang kerja. Language / Appearance -
2026-09-06: Halaman dengan bilah samping menghapus tombol menu duplikat; tombol yang ada dan API navigasi tetap tersedia. WorkspaceNavigation
-
2026-09-06: Navigasi global memakai ikon menu, alat memakai ikon panel berarah. WorkspacePanelReveal / EditorViewControls
-
2026-09-06: Mode tampilan ·
E/T/V/F·Segment.shortcut. EditorViewControls -
2026-09-06:
PlatformHeader.workspaceNavigationmenempatkan navigasi global sebelum logo PlatformHeader.workspaceNavigation
2026-09-06 - EditorHeader.preview / EditorViewControls.returnView
EditorHeader.preview hanya menampilkan center sebagai bilah pratinjau ringkas tanpa garis tepi; logo, akun, simpan, dan panel tetap terpasang tetapi tersembunyi. Dengan LivePreviewToolbar terpisah, sembunyikan header editor dan gunakan EditorViewControls.returnView (edit atau focus) untuk kembali ke mode sebelumnya. Pertahankan akses kembali dan layar penuh independen; header situs tetap terlihat.
2026-09-06 · Builder / CMS
Builder dan CMS berbagi BuilderWorkspace, EditorCatalog, dan EditorComponentSettings untuk panel, ilustrasi penyisipan, dan pengaturan tampilan. Preset menerapkan pengaturan terkait sekaligus tanpa mengubah konten; penyimpanan dan urungkan ditangani aplikasi masing-masing. Kontrol mengikuti tema platform, sedangkan konten mengikuti tema situs.
2026-09-06 - EditorViewControls
Satu tombol beralih dua arah: saat mengedit menampilkan Fokus, saat fokus menampilkan Edit. Klik atau tekan T; E langsung kembali ke edit. Pada header sempit, tombol tetap terlihat; pratinjau, layar penuh dan tindakan tambahan berada di Lainnya. EditorViewControls
2026-09 · Ruang kerja administrasi
Tabel sempit (WorkspaceDataTable, AdminDataTable) menampilkan rekaman berlabel dengan pilihan, kepala tabel khusus, dan tindakan. Gunakan mobileLayout="scroll" untuk matriks perbandingan. WorkspaceFilterToolbar menempatkan pencarian dan filter sebelum urutan dan tampilan. Bilah samping memakai h2; halaman memakai h1.
2026-09-08 · Task focus
useSidebarTaskFocus(active) menyembunyikan navigasi sementara selama tugas yang memerlukan fokus. Saat keluar, tampilan sebelumnya dipulihkan kecuali pengguna mengubah mode secara eksplisit. Penyembunyian otomatis tidak menimpa preferensi tersimpan.
Referensi API tambahan (bahasa Inggris; terjemahan menyusul)
Optional FloatingToolPanel.viewKey animates tool changes without remounting the body. Shared opening, closing, unfolding and pin feedback respect reduced motion; pointer geometry updates run at most once per animation frame. Closed Dialog keepMounted surfaces become inert and hidden from assistive technology immediately, including during an exit transition. Existing props and document state ownership are unchanged.
The opt-in useWorkspacePanelEdgeDrag hook connects existing workspace borders to expanded, icon and hidden states in one mouse or touch gesture, with keyboard resizing, RTL and cancellation. ResizablePanels now marks its separators with data-workspace-panel-edge; existing hosts retain their behavior until they enable the hook. Hosts own widths, state, focus and visual skins. See the integration contract.
Referensi API tambahan (bahasa Inggris; terjemahan menyusul) · 2026-10
2026-10-08 · Workspace title navigation
WorkspaceLayout and WorkspacePageHeader accept optional backControl before the title. Use WorkspaceBackButton with a localized label and the existing href or onClick; it supplies an icon, accessible name, Tooltip and RTL mirroring. Hosts retain return destinations, list state and navigation guards. Existing headers without this slot keep their layout.