Skip to Content
Desain

Komponen Button

Spesifikasi semantik, ukuran, bentuk, status, dan aksesibilitas untuk Button dan IconButton.

Komponen langsungTombol / IconButton / AIButton

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 oleh aria-label.
  • Ikon yang tidak familier atau maknanya mungkin tidak jelas harus menggunakan Tooltip bersama; tooltip tidak dapat menggantikan aria-label.
  • Jangan menggunakan atribut DOM title sebagai petunjuk produk, dan jangan mengatur tooltip sekaligus 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 Button dengan teks kosong, teks tersembunyi, atau lebar tetap untuk meniru IconButton.
  • Jangan mengatur shape pada IconButton; 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 Button dengan href ketika penekanan visual tingkat tombol diperlukan.

3. Hierarki Semantik variant

VariantMaknaSkenario KhasBatasan Penggunaan
primaryTindakan utama di area saat iniSimpan, terbitkan, buat, coba sekarangBiasanya hanya satu tindakan utama per area tugas
secondaryTindakan jelas tetapi sekunderPratinjau, batal, kembali, imporTidak boleh bersaing dengan tindakan utama untuk perhatian visual
ghostTindakan alat kontekstual dengan penekanan rendahTutup, lainnya, tindakan toolbar, kembali ringanDefault transparan, tidak boleh menjadi satu-satunya CTA kunci
dangerTindakan yang menghapus atau menyebabkan kerusakan signifikanHapus item, hapus konten, kosongkan dataHanya 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:

  1. Temukan langkah berikutnya yang paling penting dan unik untuk tugas saat ini, jadikan sebagai primary.
  2. Tindakan pendukung yang masih harus terlihat jelas menggunakan secondary.
  3. Tindakan dengan penekanan rendah di toolbar atau konteks menggunakan ghost.
  4. 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

SizeTinggi/DiameterUkuran Font TeksSkenario yang Direkomendasikan
sm40px14pxNavigasi atas, toolbar kompak, area kerja padat
md44px15pxForm default, CMS, dialog, dan tindakan umum
lg48px16pxCTA 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 Button dan diameter IconButton menggunakan token ukuran yang sama, sehingga dapat disejajarkan dalam toolbar yang sama; ukuran ikon yang terlihat IconButton disatukan menjadi 18px.
  • Ukuran font teks Button ditentukan 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

ShapeTampilanCakupan Penggunaan
pillSudut membulat penuh; berbentuk oval saat ada teksDefault platform, berlaku untuk halaman pemasaran, Dashboard, Builder, CMS, dan Admin
roundedSudut membulat 12pxHanya 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 menggunakan trailingIcon.
  • 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 Button tanpa href, yang akhirnya dirender sebagai <button>.
  • Untuk pergi ke rute atau sumber daya lain, gunakan Button dengan href, yang akhirnya dirender sebagai Next.js <Link>.
  • Tombol non-submit dalam form harus secara eksplisit menulis type="button"; tombol submit secara eksplisit menulis type="submit".
  • Jangan menggunakan onClick untuk 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-hover saat hover; --control-surface-active saat ditekan, terpilih, atau diperluas. focus-visible mempertahankan --focus-ring pada 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".
  • IconButton harus menyediakan aria-label yang 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 danger dan 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:

PropertiNilai DefaultKeterangan
variantprimaryHierarki semantik dan visual
sizemdTinggi, ukuran font teks, dan padding horizontal
shapepillBentuk sudut membulat Button
leadingIconTidak adaIkon sebelum teks
trailingIconTidak adaIkon setelah teks
hrefTidak adaDirender sebagai tautan jika disediakan
disabledfalseNonaktifkan interaksi
tooltipTidak adaKonten pelengkap untuk Tooltip bersama; tidak boleh menggantikan informasi kunci yang terlihat atau aria-label
tooltipPlacementbottomArah yang dipilih; Tooltip bersama dapat membalik untuk tetap di viewport
tooltipPortaltrueDirender di luar kontainer yang dipotong, tanpa menambah lapisan pembungkus tata letak
skinTidak adaMenyediakan 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 Button atau IconButton diprioritaskan untuk digunakan ulang?
  • Apakah komponen yang benar dipilih untuk tombol dengan teks dan tombol ikon saja?
  • Apakah hanya ada satu primary yang jelas di area tugas saat ini?
  • Apakah secondary, ghost, danger digunakan berdasarkan semantik bukan preferensi warna?
  • Apakah Button platform mempertahankan pill default, dan IconButton tetap bulat?
  • Apakah setiap Tooltip masih merupakan lapisan informasi dengan sudut membulat kompak, bukan seperti tombol oval yang dapat diklik?
  • Apakah title native browser, gelembung CSS data-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 type yang benar?
  • Apakah ikon menyembunyikan informasi pembaca layar yang berulang, dan IconButton memiliki aria-label yang 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.

Di halaman ini