Komponen Button
Spesifikasi semantik, ukuran, bentuk, status, dan aksesibilitas untuk Button dan IconButton.
AIButton menggunakan ukuran dan makna Tombol, sambil menambahkan status AI Qokit yang khas dan mudah dikenali.
Pilih tombol AI untuk melihat status kerjanya.
Spesifikasi Komponen Button Qokit
Dokumen ini mendefinisikan aturan penggunaan tombol di platform Qokit, Builder, CMS, Dashboard, Admin, halaman pemasaran, dan situs yang dihasilkan. Tujuannya adalah menyatukan komponen, semantik, bentuk, ukuran, ikon, status, dan aksesibilitas tombol, serta menghindari perancangan ulang tombol melalui CSS lokal di setiap rute.
1. Model Inti
Tombol tidak hanya dikategorikan sebagai "oval" atau "bulat", melainkan terdiri dari lima dimensi yang saling independen:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- Tipe komponen menentukan apakah tombol memiliki teks yang terlihat dan apakah area klik harus tetap persegi.
- Prioritas semantik menentukan prioritas dan warna tombol dalam tugas saat ini.
- Ukuran menentukan tinggi tetap, ukuran font teks, dan area sentuh.
- Bentuk hanya menentukan sudut membulat, tidak mengekspresikan prioritas atau semantik bisnis.
- Hierarki spasial hanya menjelaskan apakah kontrol melayang dari bidang saat ini, tanpa mengubah semantik tindakan.
Jangan membuat tipe tombol baru dengan menggabungkan nama kelas baru. Pilih terlebih dahulu dari properti yang ada di komponen bersama.
2. Pemilihan Komponen
Button
Digunakan untuk semua tindakan dengan teks yang terlihat, termasuk:
- Tombol teks saja;
- Tombol dengan ikon di depan teks;
- Tombol dengan ikon di belakang teks;
- Tautan halaman yang terlihat seperti tombol.
Button di platform secara default menggunakan pill dengan sudut membulat penuh, sehingga secara visual berbentuk oval. Selama tombol memiliki teks yang terlihat, jangan menggunakan tombol ikon bulat.
variant dipisahkan dari bayangan: primary secara default menggunakan raised, secondary, danger, ghost secara default menggunakan flat. Tindakan di dalam baris daftar, kartu, toolbar, dan kapsul komposit harus menggunakan flat; tindakan utama independen dapat menggunakan raised; hanya tindakan yang melayang di atas konten yang menggunakan floating. Kapsul independen atau kontrol segmented hanya menggambar bayangan sekali di lapisan terluar, rute tidak boleh menulis ulang hierarki bersama dengan CSS lokal.
import { Button } from '@qokit/components/ui';
<Button type="button" variant="primary">
保存
</Button>
<Button
leadingIcon={<SaveIcon aria-hidden="true" />}
type="button"
variant="primary"
>
保存
</Button>
<Button
href="/projects"
trailingIcon={<ArrowRightIcon aria-hidden="true" />}
variant="secondary"
>
查看项目
</Button>IconButton
Digunakan untuk tindakan alat kompak yang hanya memiliki satu ikon tanpa teks yang terlihat, seperti tutup, lainnya, kembali, alihkan menu, atau hapus.
IconButton mempertahankan lebar, tinggi, dan sudut membulat penuh yang sama di setiap ukuran, sehingga secara visual merupakan tombol bulat. Secara default menggunakan ghost dan pada tingkat tipe mewajibkan aria-label.
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>Aturan:
- Ikon itu sendiri menggunakan
aria-hidden="true", nama tombol disediakan oleharia-label. - Ikon yang tidak familier atau maknanya mungkin tidak jelas harus menggunakan
Tooltipbersama; tooltip tidak dapat menggantikanaria-label. - Jangan menggunakan atribut DOM
titlesebagai petunjuk produk, dan jangan mengaturtooltipsekaligus membungkus Tooltip secara manual. - Tooltip adalah lapisan informasi hanya-baca, bukan tombol oval. Menggunakan sudut membulat Tooltip kompak bersama, tidak boleh menggunakan ulang
pill, visual hover, pressed, atau focus tombol. - Jangan menggunakan
Buttondengan teks kosong, teks tersembunyi, atau lebar tetap untuk meniruIconButton. - Jangan mengatur
shapepadaIconButton; bentuk bulat adalah kontrak komponennya.
Skenario yang Tidak Seharusnya Menggunakan Button
- Tab menggunakan komponen yang sesuai seperti Tabs/PillTabs/Segmented.
- Item menu menggunakan komponen yang sesuai seperti Menu/ActionMenu.
- Status, label, dan hasil filter menggunakan Pill atau komponen status.
- Navigasi teks biasa menggunakan tautan semantik; hanya gunakan
Buttondenganhrefketika penekanan visual tingkat tombol diperlukan.
3. Hierarki Semantik variant
| Variant | Makna | Skenario Khas | Batasan Penggunaan |
|---|---|---|---|
primary | Tindakan utama di area saat ini | Simpan, terbitkan, buat, coba sekarang | Biasanya hanya satu tindakan utama per area tugas |
secondary | Tindakan jelas tetapi sekunder | Pratinjau, batal, kembali, impor | Tidak boleh bersaing dengan tindakan utama untuk perhatian visual |
ghost | Tindakan alat kontekstual dengan penekanan rendah | Tutup, lainnya, tindakan toolbar, kembali ringan | Default transparan, tidak boleh menjadi satu-satunya CTA kunci |
danger | Tindakan yang menghapus atau menyebabkan kerusakan signifikan | Hapus item, hapus konten, kosongkan data | Hanya mengekspresikan semantik destruktif, bukan sebagai warna penekanan biasa |
variant mengekspresikan hierarki semantik dan visual, bukan bentuk. Misalnya ghost bisa berupa tombol oval dengan teks, atau IconButton bulat.
Urutan pemilihan:
- Temukan langkah berikutnya yang paling penting dan unik untuk tugas saat ini, jadikan sebagai
primary. - Tindakan pendukung yang masih harus terlihat jelas menggunakan
secondary. - Tindakan dengan penekanan rendah di toolbar atau konteks menggunakan
ghost. - Hanya tindakan yang benar-benar destruktif menggunakan
danger, dan ikuti alur konfirmasi yang sudah ada.
Jangan memilih variant berdasarkan "warna mana yang terlihat lebih bagus".
4. Ukuran size
| Size | Tinggi/Diameter | Ukuran Font Teks | Skenario yang Direkomendasikan |
|---|---|---|---|
sm | 40px | 14px | Navigasi atas, toolbar kompak, area kerja padat |
md | 44px | 15px | Form default, CMS, dialog, dan tindakan umum |
lg | 48px | 16px | CTA utama halaman pemasaran, tindakan utama yang memerlukan sentuhan lebih kuat |
Ukuran default adalah md.
- Grup tombol yang sama menggunakan ukuran yang sama.
- Kontrol kompak tidak boleh kurang dari 40px; tindakan utama di mobile sebaiknya menggunakan minimal 44px.
- Tinggi
Buttondan diameterIconButtonmenggunakan token ukuran yang sama, sehingga dapat disejajarkan dalam toolbar yang sama; ukuran ikon yang terlihatIconButtondisatukan menjadi 18px. - Ukuran font teks
Buttonditentukan oleh token bersama yang sesuai dengan size, tidak mewarisi ukuran font dari Header, Dialog, atau kontainer induk lainnya. - CSS rute dapat mengontrol penyusunan, jarak, dan lebar tombol yang diperlukan, tetapi tidak boleh mendefinisikan ulang tinggi atau ukuran font tombol bersama.
- Ketika teks panjang, utamakan menyesuaikan tata letak atau kontainer tombol, jangan atasi dengan mengompres tinggi, font, atau jarak kiri-kanan.
5. Bentuk shape
| Shape | Tampilan | Cakupan Penggunaan |
|---|---|---|
pill | Sudut membulat penuh; berbentuk oval saat ada teks | Default platform, berlaku untuk halaman pemasaran, Dashboard, Builder, CMS, dan Admin |
rounded | Sudut membulat 12px | Hanya digunakan ketika tema situs yang dihasilkan secara eksplisit memerlukan sudut membulat lebih kecil |
Button secara default shape="pill". Frontend platform tidak boleh mengatur rounded secara eksplisit, dan tidak boleh menimpa sudut membulat di CSS lokal.
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton selalu bulat, tidak berpartisipasi dalam pemilihan bisnis pill / rounded.
6. Aturan Ikon
- Ikon sebelum teks menggunakan
leadingIcon, ikon setelah teks menggunakantrailingIcon. - Satu tombol biasanya hanya menggunakan satu ikon pendukung.
- Tindakan yang familier seperti simpan, tambah, kembali dapat menggunakan ikon untuk memperkuat pengenalan, tetapi ikon tidak boleh menggantikan teks yang terlihat pada tombol kunci.
- Panah yang menunjukkan lanjutkan, masuk, atau perluas biasanya diletakkan setelah teks; ikon kembali biasanya diletakkan sebelum teks.
- Jangan menulis tata letak ikon dan teks secara manual di
children, komponen sudah menyediakan slot icon dan label. - Gunakan ikon bersama dan warisi
currentColor, jangan meng-hardcode warna atau ukuran ikon di CSS rute. - Status loading harus mempertahankan lebar dan tinggi tombol asli, dan menyediakan teks pendek yang dapat dipahami atau umpan balik loading yang sudah ada; jangan biarkan pergantian teks menyebabkan toolbar melompat.
7. Tombol dan Tautan
Tindakan dan navigasi harus menggunakan semantik yang benar:
- Tindakan halaman saat ini seperti kirim, simpan, buka overlay, alihkan status, gunakan
Buttontanpahref, yang akhirnya dirender sebagai<button>. - Untuk pergi ke rute atau sumber daya lain, gunakan
Buttondenganhref, yang akhirnya dirender sebagai Next.js<Link>. - Tombol non-submit dalam form harus secara eksplisit menulis
type="button"; tombol submit secara eksplisit menulistype="submit". - Jangan menggunakan
onClickuntuk meniru navigasi halaman biasa.
Tautan yang dinonaktifkan menggunakan aria-disabled dan keluar dari urutan Tab; tombol native yang dinonaktifkan menggunakan disabled. Status dinonaktifkan tidak boleh hanya diekspresikan dengan mengurangi transparansi, logika bisnis juga harus memblokir tindakan.
8. Status dan Aksesibilitas
Komponen bersama secara seragam menangani status hover, focus-visible, disabled, dan warna. Kode bisnis tetap harus memenuhi:
- Tombol biasa yang tidak terpilih menggunakan
--control-surface-hoversaat hover;--control-surface-activesaat ditekan, terpilih, atau diperluas.focus-visiblemempertahankan--focus-ringpada permukaan netral, gaya rute tidak boleh menggabungkan hover dan status persisten menjadi satu aturan biru muda. - Nama tombol harus langsung, spesifik, dan menjelaskan apa yang akan terjadi, seperti "Simpan", "Terbitkan situs", "Hapus item".
IconButtonharus menyediakanaria-labelyang dilokalkan.- Ikon dekoratif menggunakan
aria-hidden="true"untuk menghindari pembaca layar membacakan berulang. - Fokus keyboard harus terlihat; CSS rute tidak boleh menghapus focus ring bersama.
- Jangan menjadikan hover sebagai satu-satunya petunjuk, interaksi harus mendukung keyboard dan sentuhan secara bersamaan.
- Tombol yang dinonaktifkan hanya digunakan untuk tindakan yang sementara tidak dapat dilakukan pengguna; jika perlu menjelaskan alasannya, sediakan penjelasan terdekat atau tooltip.
- Error, persyaratan izin, risiko, biaya, dan informasi penting lainnya untuk tugas harus tetap terlihat; Tooltip hanya dapat melengkapi informasi, tidak boleh menjadi satu-satunya cara untuk menemukan informasi ini.
- Tindakan asinkron harus mencegah pengiriman berulang dan mempertahankan umpan balik proses yang dapat dipahami.
- Tindakan berbahaya menggunakan
dangerdan gunakan ulang pattern konfirmasi berbahaya yang sudah ada; jangan hanya mengandalkan warna merah untuk menyampaikan risiko. - Teks tombol dalam bahasa Mandarin atau bahasa lain tidak boleh dipotong hingga tidak dapat dipahami. Harus memverifikasi teks panjang dan lebar mobile.
9. Batasan Tanggung Jawab Gaya
Struktur, semantik, dan status tombol bersama ditangani oleh Button / IconButton; token visual dan CSS bersama ditangani oleh paket komponen; rute hanya menangani tata letak.
Tanggung Jawab Lapisan Bersama
- DOM, semantik tautan/tombol, perilaku disabled;
- Slot icon/label dan batasan tipe aksesibilitas;
- Kelas variant, size, shape;
- Tinggi, sudut membulat, padding, ukuran font, berat font;
- Latar belakang, warna teks, bayangan, status hover, focus-visible, dan disabled.
Tanggung Jawab Lapisan Rute
- Arah, jarak, perataan, dan pembungkusan grup tombol;
- Penyusunan responsif;
width: 100%atau lebar kontainer yang diperlukan untuk alur kerja tertentu;- Nama kelas posisi yang tidak mengubah visual dasar.
Bukan Tanggung Jawab Lapisan Rute
- Menulis ulang tinggi, ukuran font, sudut membulat, latar belakang, warna teks, bayangan, atau focus ring tombol;
- Mengimplementasikan ulang tombol bersama dengan warna hardcode atau
border-radius: 999px; - Menambahkan varian visual lokal seperti
primary-alt,outline-blue,icon-round; - Bersaing dengan kontrak tombol bersama menggunakan
!important; - Menyalin langsung gaya dasar
.qk-ui-button.
Jika memang muncul varian semantik baru yang diperlukan di beberapa halaman, sebaiknya bangun kontrak terpadu di ButtonVariant, token, dan primitives.css bersama terlebih dahulu, bukan menambahkan gaya baru di rute.
10. Referensi Cepat API
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Properti utama Button:
| Properti | Nilai Default | Keterangan |
|---|---|---|
variant | primary | Hierarki semantik dan visual |
size | md | Tinggi, ukuran font teks, dan padding horizontal |
shape | pill | Bentuk sudut membulat Button |
leadingIcon | Tidak ada | Ikon sebelum teks |
trailingIcon | Tidak ada | Ikon setelah teks |
href | Tidak ada | Dirender sebagai tautan jika disediakan |
disabled | false | Nonaktifkan interaksi |
tooltip | Tidak ada | Konten pelengkap untuk Tooltip bersama; tidak boleh menggantikan informasi kunci yang terlihat atau aria-label |
tooltipPlacement | bottom | Arah yang dipilih; Tooltip bersama dapat membalik untuk tetap di viewport |
tooltipPortal | true | Dirender di luar kontainer yang dipotong, tanpa menambah lapisan pembungkus tata letak |
skin | Tidak ada | Menyediakan slot kelas dan adaptasi variabel sesuai kontrak skeleton/skin |
IconButton mewarisi properti Button yang berlaku, tetapi tidak menyediakan shape, leadingIcon, atau trailingIcon; memerlukan aria-label, default variant="ghost".
Disarankan untuk secara eksplisit menulis variant dan type tombol native dalam kode bisnis, agar semantik tindakan terlihat jelas dalam tinjauan kode.
11. Kombinasi Umum
// 主要操作:椭圆形文字按钮
<Button type="submit" variant="primary">
保存
</Button>
// 次要操作
<Button type="button" variant="secondary" onClick={onPreview}>
预览
</Button>
// 低强调文字操作
<Button type="button" variant="ghost" onClick={onCancel}>
取消
</Button>
// 图标 + 文字,仍然使用 Button
<Button
leadingIcon={<PlusIcon aria-hidden="true" />}
type="button"
variant="primary"
>
新建内容
</Button>
// 纯图标:圆形按钮
<IconButton aria-label="更多操作" tooltip="更多操作" type="button">
<MoreIcon aria-hidden="true" />
</IconButton>
// 危险操作
<Button type="button" variant="danger" onClick={openDeleteConfirm}>
删除项目
</Button>12. Checklist Tinjauan
Sebelum mengirimkan UI terkait tombol, konfirmasi:
- Apakah
ButtonatauIconButtondiprioritaskan untuk digunakan ulang? - Apakah komponen yang benar dipilih untuk tombol dengan teks dan tombol ikon saja?
- Apakah hanya ada satu
primaryyang jelas di area tugas saat ini? - Apakah
secondary,ghost,dangerdigunakan berdasarkan semantik bukan preferensi warna? - Apakah
Buttonplatform mempertahankanpilldefault, danIconButtontetap bulat? - Apakah setiap Tooltip masih merupakan lapisan informasi dengan sudut membulat kompak, bukan seperti tombol oval yang dapat diklik?
- Apakah
titlenative browser, gelembung CSSdata-tooltip, petunjuk berulang, dan Tooltip sinonim untuk tombol teks telah dihilangkan? - Apakah ukuran hanya menggunakan
sm,md,lg, dan tinggi serta ukuran font dalam grup yang sama konsisten? - Apakah tombol native secara eksplisit mengatur
typeyang benar? - Apakah ikon menyembunyikan informasi pembaca layar yang berulang, dan
IconButtonmemilikiaria-labelyang dilokalkan? - Apakah status focus-visible, disabled, asinkron, dan konfirmasi berbahaya lengkap?
- Apakah CSS rute hanya menangani tata letak, tanpa menimpa visual dasar tombol?
- Apakah teks panjang, ukuran sentuh, dan penyusunan grup tombol telah diverifikasi di lebar desktop dan mobile?
13. Sumber Implementasi
- API komponen:
packages/components/src/ui/Button/Button.tsx - Ekspor komponen:
packages/components/src/ui/Button/index.ts - Token ukuran dan warna:
packages/components/src/styles/foundations.css - Gaya tombol bersama:
packages/components/src/styles/primitives.css - Kontrak akses komponen publik:
docs/public/design/component-integration.md
Ketika terdapat perbedaan antara dokumentasi dan implementasi, komponen, token, gaya, dan dokumen ini harus disinkronkan dalam perubahan yang sama.