Skip to Content
Tasarım

Button Düğmesi

Button ve IconButton için semantik, boyut, şekil, durum ve erişilebilirlik kuralları.

Canlı bileşenDüğme / İkon Düğmesi / AI Düğmesi

AI Düğmesi, düğme boyutları ve anlamlılığı korunurken, Qokit AI durumunu belirgin bir şekilde gösterir.

AI düğmesini seçerek çalışma durumunu önizleyin.

Qokit Düğme Bileşeni Kuralları

Bu belge, Qokit platformu, Builder, CMS, Dashboard, Admin, pazarlama sayfaları ve oluşturulan sitelerdeki düğme kullanım kurallarını tanımlar. Amaç; düğme bileşenlerini, semantiğini, şeklini, boyutunu, simgelerini, durumlarını ve erişilebilirliğini standartlaştırmak ve her yolun düğmeleri yerel CSS ile yeniden tasarlamasını önlemektir.

1. Temel Model

Düğmeler yalnızca "oval, yuvarlak" olarak sınıflandırılmaz; birbirinden bağımsız beş boyuttan oluşur:

Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating
  • Bileşen türü, düğmenin görünür metin içerip içermediğini ve kare tıklama alanını korumasının gerekip gerekmediğini belirler.
  • Semantik öncelik, düğmenin mevcut görevdeki önceliğini ve rengini belirler.
  • Boyut, sabit yüksekliği, metin yazı tipi boyutunu ve dokunma alanını belirler.
  • Şekil yalnızca köşe yuvarlaklığını belirler; öncelik veya iş semantiğini ifade etmez.
  • Uzamsal katman, kontrolün mevcut düzlemden yükselip yükselmediğini belirtir; işlem semantiğini değiştirmez.

Yeni sınıf kombinasyonlarıyla yeni düğme türleri oluşturmayın. Önce paylaşılan bileşenin mevcut özelliklerinden seçim yapın.

2. Bileşen Seçimi

Button

Görünür metin içeren tüm işlemler için kullanılır:

  • Yalnızca metin içeren düğmeler;
  • Simgesi metinden önce olan düğmeler;
  • Simgesi metinden sonra olan düğmeler;
  • Düğme gibi görünen sayfa bağlantıları.

Platformdaki Button varsayılan olarak tam yuvarlak pill kullanır ve görsel olarak oval görünür. Düğme görünür metin içeriyorsa, yuvarlak simge düğmesine geçilmemelidir.

variant gölgeden bağımsızdır: primary varsayılan olarak raised kullanır; secondary, danger, ghost varsayılan olarak flat kullanır. Liste satırları, kart içleri, araç çubukları ve birleşik kapsüller içindeki işlemler flat olmalıdır; bağımsız birincil işlemler raised kullanabilir; yalnızca içeriğin üzerinde yüzen işlemler floating kullanır. Bağımsız kapsüller veya segmentli kontrollerde gölge yalnızca en dış katman tarafından bir kez çizilir; yollar paylaşılan katmanı yerel CSS ile geçersiz kılmamalıdır.

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

Yalnızca bir simge içeren, görünür metin olmayan kompakt araç işlemleri için kullanılır; örneğin kapatma, daha fazla, geri, menü değiştirme veya silme.

IconButton her boyutta eşit genişlik, eşit yükseklik ve tam yuvarlak köşeleri korur; bu nedenle görsel olarak yuvarlak düğmedir. Varsayılan olarak ghost kullanır ve tür düzeyinde aria-label zorunluluğu getirir.

import { IconButton } from '@qokit/components/ui';

<IconButton aria-label="关闭" tooltip="关闭" type="button">
  <CloseIcon aria-hidden="true" />
</IconButton>

Kurallar:

  • Simgelerin kendisi aria-hidden="true" kullanır; düğme adları aria-label tarafından sağlanır.
  • Tanıdık olmayan veya anlamı belirsiz olabilecek simgeler için paylaşılan Tooltip de kullanılmalıdır; tooltip aria-label yerine geçemez.
  • DOM title özelliğini ürün ipucu olarak kullanmayın; ayrıca tooltip ayarlayıp manuel olarak Tooltip sarmayın.
  • Tooltip salt okunur bir bilgi katmanıdır, oval düğme değildir. Paylaşılan kompakt Tooltip köşe yuvarlaklığını kullanır; pill, düğme hover, pressed veya focus görsellerini yeniden kullanmamalıdır.
  • Boş metin, gizli metin veya sabit genişlikli Button kullanarak IconButton taklidi yapmayın.
  • IconButton için shape ayarlamayın; yuvarlaklık onun bileşen sözleşmesidir.

Button Kullanılmaması Gereken Durumlar

  • Sekmeler için Tabs/PillTabs/Segmented gibi ilgili bileşenleri kullanın.
  • Menü öğeleri için Menu/ActionMenu ilgili bileşenlerini kullanın.
  • Durum, etiket ve filtre sonuçları için Pill veya durum bileşenlerini kullanın.
  • Normal metin gezinmesi için semantik bağlantıları kullanın; yalnızca düğme düzeyinde görsel vurgu gerektiğinde href içeren Button kullanın.

3. Semantik Katmanlar variant

VariantAnlamTipik SenaryoKullanım Kısıtlaması
primaryMevcut alanın birincil işlemiKaydet, yayımla, oluştur, hemen deneBir görev alanında genellikle yalnızca bir birincil işlem bulunur
secondaryAçık ancak ikincil işlemÖnizleme, iptal, geri, içe aktarBirincil işlemle görsel dikkat için yarışmamalıdır
ghostDüşük vurgulu, bağlamsal araç işlemiKapat, daha fazla, araç çubuğu işlemi, hafif geriVarsayılan olarak şeffaftır; tek başına kritik CTA olarak kullanılamaz
dangerSilme veya belirgin zarar verme işlemiÖğe sil, içerik kaldır, veriyi temizleYalnızca yıkıcı semantiği ifade eder; normal vurgu rengi olarak kullanılmaz

variant semantik ve görsel katmanı ifade eder, şekli değil. Örneğin ghost metinli oval düğme olabileceği gibi, yuvarlak IconButton de olabilir.

Seçim sırası:

  1. Mevcut görev için tek en önemli sonraki adımı bulun ve onu primary olarak ayarlayın.
  2. Hala net görünmesi gereken yardımcı işlemler için secondary kullanın.
  3. Araç çubuğu veya bağlamdaki düşük vurgulu işlemler için ghost kullanın.
  4. Yalnızca gerçekten yıkıcı işlemler için danger kullanın ve mevcut onay akışını sürdürün.

Variant seçimini "hangi renk daha güzel görünüyor"a göre yapmayın.

4. Boyut size

SizeYükseklik/ÇapMetin Yazı Tipi BoyutuÖnerilen Senaryo
sm40px14pxÜst gezinme, kompakt araç çubukları, yoğun çalışma alanları
md44px15pxVarsayılan formlar, CMS, iletişim kutuları ve genel işlemler
lg48px16pxPazarlama sayfası birincil CTA'ları, daha güçlü dokunma gerektiren birincil işlemler

Varsayılan boyut md'tür.

  • Aynı düğme grubu aynı boyutu kullanır.
  • Kompakt kontroller 40px'in altında olmamalıdır; mobil birincil işlemler için en az 44px tercih edilmelidir.
  • Button yüksekliği ve IconButton çapı aynı boyut token setini kullanır; bu nedenle aynı araç çubuğunda hizalanabilirler; IconButton görünür simge boyutu tek tip 18px'dir.
  • Button metin yazı tipi boyutu, size'a karşılık gelen paylaşılan token tarafından belirlenir; Header, Dialog veya diğer üst kapların yazı tipi boyutunu devralmaz.
  • Yol CSS'i düğmelerin sıralamasını, aralıklarını ve gerekli genişliğini kontrol edebilir; ancak paylaşılan düğme yüksekliğini veya yazı tipi boyutunu yeniden tanımlayamaz.
  • Metin uzun olduğunda, yüksekliği, yazı tipini veya yatay aralığı sıkıştırmak yerine önce düzeni veya düğme kapsayıcısını ayarlamayı tercih edin.

5. Şekil shape

ShapeGörünümKullanım Kapsamı
pillTam yuvarlak; metin içerdiğinde ovalPlatform varsayılanı; pazarlama sayfaları, Dashboard, Builder, CMS ve Admin için uygundur
rounded12px köşe yuvarlaklığıYalnızca oluşturulan site teması açıkça daha küçük köşe yuvarlaklığı gerektirdiğinde kullanılır

Button varsayılan olarak shape="pill"'dir. Platform ön ucu rounded'nü açıkça ayarlamamalı ve yerel CSS'de köşe yuvarlaklığını geçersiz kılmamalıdır.

// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>

// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
  预约咨询
</Button>

IconButton her zaman yuvarlaktır; pill / rounded iş seçimlerine katılmaz.

6. Simge Kuralları

  • Metinden önceki simgeler leadingIcon kullanır; metinden sonraki simgeler trailingIcon kullanır.
  • Bir düğme genellikle yalnızca bir yardımcı simge kullanır.
  • Kaydet, ekle, geri gibi tanıdık işlemler tanımayı güçlendirmek için simge kullanabilir; ancak simgeler kritik düğmelerin görünür metninin yerine geçemez.
  • Oklar devam etme, girme veya genişletme anlamında genellikle metinden sonra yer alır; geri simgesi genellikle metinden önce yer alır.
  • children içinde simge ve metin düzenini elle yazmayın; bileşen zaten icon ve label yuvalarını sağlar.
  • Paylaşılan simgeleri kullanın ve currentColor'i devralın; yol CSS'inde simge rengini veya boyutunu sabit kodlamayın.
  • Yükleme durumu düğmenin mevcut genişlik ve yüksekliğini korumalı ve anlaşılır kısa metin veya mevcut yükleme geri bildirimi sağlamalıdır; metin değişiminin araç çubuğunu zıplatmasına izin vermeyin.

7. Düğmeler ve Bağlantılar

İşlemler ve gezinme doğru semantik kullanmalıdır:

  • Gönder, kaydet, katman aç, durum değiştir gibi mevcut sayfa işlemleri için href içermeyen Button kullanın; nihai olarak <button> olarak işlenir.
  • Başka bir yola veya kaynağa gitmek için href içeren Button kullanın; nihai olarak Next.js <Link> olarak işlenir.
  • Form içindeki gönderme dışı düğmeler açıkça type="button" yazmalıdır; gönderme düğmeleri açıkça type="submit" yazmalıdır.
  • Normal sayfa gezinmesini taklit etmek için onClick kullanmayın.

Devre dışı bırakılan bağlantılar aria-disabled kullanır ve Tab sırasından çıkar; devre dışı bırakılan yerel düğmeler disabled kullanır. Devre dışı durumu yalnızca saydamlığı azaltarak ifade etmeyin; iş mantığı da işlemi engellemelidir.

8. Durumlar ve Erişilebilirlik

Paylaşılan bileşenler hover, focus-visible, disabled ve renk durumlarını tek tip yönetir. İş kodu yine de şunları karşılamalıdır:

  • Normal seçili olmayan düğme hover için --control-surface-hover; basılı, seçili ve genişletilmiş için --control-surface-active kullanılır. focus-visible nötr yüzeylerde --focus-ring'i korur; yol stilleri hover ile kalıcı durumu aynı açık mavi kurala birleştirmemelidir.
  • Düğme adları doğrudan, somut olmalı ve ne olacağını açıklamalıdır; örneğin "Kaydet", "Siteyi Yayımla", "Öğeyi Sil".
  • IconButton yerelleştirilmiş aria-label sağlamalıdır.
  • Dekoratif simgeler aria-hidden="true" kullanmalıdır; ekran okuyucunun tekrar okumasını önlemek için.
  • Klavye odağı görünür olmalıdır; yol CSS'i paylaşılan focus ring'i kaldırmamalıdır.
  • Yalnızca hover'ı tek ipucu olarak kullanmayın; etkileşim hem klavyeyi hem de dokunmayı desteklemelidir.
  • Devre dışı düğmeler yalnızca kullanıcının geçici olarak yapamadığı işlemler için kullanılır; nedenini açıklamak gerekiyorsa yakın açıklama veya tooltip sağlayın.
  • Hata, izin gereksinimi, risk, maliyet ve diğer görev açısından kritik bilgiler görünür kalmalıdır; Tooltip yalnızca bilgiyi tamamlayabilir, bu bilgileri keşfetmenin tek yolu olamaz.
  • Asenkron işlemler tekrar gönderimi önlemeli ve anlaşılır devam eden geri bildirimi korumalıdır.
  • Tehlikeli işlemler danger kullanır ve mevcut tehlikeli onay desenini yeniden kullanır; riski yalnızca kırmızı ile iletmeye güvenmeyin.
  • Çince veya diğer dillerdeki düğme metinleri anlaşılamayacak kadar kısaltılmamalıdır. Uzun metinleri ve mobil genişliği doğrulamak zorunludur.

9. Stil Sorumluluk Sınırları

Paylaşılan düğmenin yapısı, semantiği ve durumları Button / IconButton tarafından yönetilir; görsel token'lar ve paylaşılan CSS bileşen paketi tarafından yönetilir; yollar yalnızca düzeni yönetir.

Paylaşılan Katmanın Sorumlulukları

  • DOM, bağlantı/düğme semantiği, disabled davranışı;
  • icon/label yuvaları ve erişilebilirlik tür kısıtlamaları;
  • variant, size, shape sınıfları;
  • yükseklik, köşe yuvarlaklığı, iç boşluk, yazı tipi boyutu, yazı tipi kalınlığı;
  • arka plan, metin rengi, gölge, hover, focus-visible ve disabled durumları.

Yol Katmanının Sorumlulukları

  • Düğme grubu yönü, aralığı, hizalaması ve satır geçişi;
  • Responsive sıralama;
  • Belirli iş akışları için gereken width: 100% veya kapsayıcı genişliği;
  • Temel görselliği değiştirmeyen konumlandırma sınıfları.

Yol Katmanının Sorumluluğu Olmamalı

  • Düğme yüksekliğini, yazı tipi boyutunu, köşe yuvarlaklığını, arka planı, metin rengini, gölgeyi veya focus ring'i yeniden yazmak;
  • Sabit kodlanmış renkler veya border-radius: 999px ile paylaşılan düğmeyi yeniden uygulamak;
  • primary-alt, outline-blue, icon-round gibi yerel görsel varyantlar eklemek;
  • !important ile paylaşılan düğme sözleşmesiyle yarışmak;
  • .qk-ui-button temel stillerini doğrudan kopyalamak.

Birden fazla sayfanın ihtiyaç duyduğu yeni semantik varyantlar gerçekten ortaya çıkarsa, yollarda yeni stiller eklemek yerine önce paylaşılan ButtonVariant, token'lar ve primitives.css içinde tek tip bir sözleşme oluşturulmalıdır.

10. API Hızlı Başvuru

type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';

Button ana özellikleri:

ÖzellikVarsayılanAçıklama
variantprimarySemantik ve görsel katman
sizemdYükseklik, metin yazı tipi boyutu ve yatay iç boşluk
shapepillButton köşe yuvarlaklık şekli
leadingIconYokMetin öncesi simge
trailingIconYokMetin sonrası simge
hrefYokSağlandığında bağlantı olarak işlenir
disabledfalseEtkileşimi devre dışı bırakır
tooltipYokPaylaşılan Tooltip için ek içerik; görünür kritik bilgilerin veya aria-label yerine geçemez
tooltipPlacementbottomTercih edilen yön; paylaşılan Tooltip viewport içinde kalmak için tersine dönebilir
tooltipPortaltrueKırpma kapsayıcısının dışında işlenir ve düzen sarma katmanı eklemez
skinYokskeleton/skin sözleşmesine göre class yuvaları ve değişken uyarlaması sağlar

IconButton geçerli Button özelliklerini devralır; ancak shape, leadingIcon veya trailingIcon sağlamaz; aria-label gerektirir, varsayılan variant="ghost"'dir.

İş kodunda variant ve yerel düğme type'nü açıkça yazmanız önerilir; böylece işlem semantiği kod incelemesinde net görünür.

11. Yaygın Kombinasyonlar

// 主要操作:椭圆形文字按钮
<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. İnceleme Kontrol Listesi

Düğmeyle ilgili UI göndermeden önce doğrulayın:

  • Önce Button veya IconButton yeniden kullanıldı mı?
  • Metinli ve yalnızca simge içeren düğmeler için doğru bileşen seçildi mi?
  • Mevcut görev alanında yalnızca bir net primary var mı?
  • secondary, ghost, danger renk tercihine göre değil semantiğe göre mi kullanılıyor?
  • Platform Button varsayılan pill'yi koruyor mu, IconButton yuvarlak mı kalıyor?
  • Her Tooltip hâlâ kompakt köşe yuvarlaklı bilgi katmanı mı, tıklanabilir oval düğme gibi değil mi?
  • Tarayıcı yerel title, CSS data-tooltip balonları, tekrarlanan ipuçları ve metin düğmelerinin eşanlamlı Tooltip'leri kaldırıldı mı?
  • Boyutlar yalnızca sm, md, lg kullanıyor mu ve aynı grupta yükseklik ile yazı tipi boyutu tutarlı mı?
  • Yerel düğmeler doğru type'nü açıkça ayarladı mı?
  • Simgeler tekrarlanan ekran okuyucu bilgilerini gizledi mi, IconButton yerelleştirilmiş aria-label içeriyor mu?
  • focus-visible, disabled, asenkron ve tehlikeli onay durumları eksiksiz mi?
  • Yol CSS'i yalnızca düzeni mi yönetiyor, düğme temel görselliğini geçersiz kılmıyor mu?
  • Masaüstü ve mobil genişlikte uzun metin, dokunma boyutu ve düğme grubu sıralaması doğrulandı mı?

13. Uygulama Kaynakları

  • Bileşen API'si: packages/components/src/ui/Button/Button.tsx
  • Bileşen dışa aktarımları: packages/components/src/ui/Button/index.ts
  • Boyut ve renk token'ları: packages/components/src/styles/foundations.css
  • Paylaşılan düğme stilleri: packages/components/src/styles/primitives.css
  • Açık bileşen entegrasyon sözleşmesi: docs/public/design/component-integration.md

Belge ile uygulama arasında farklılıklar ortaya çıktığında, bileşen, token'lar, stiller ve bu belge aynı değişiklikle senkronize edilmelidir.

Bu Sayfada