Button Düğmesi
Button ve IconButton için semantik, boyut, şekil, durum ve erişilebilirlik kuralları.
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-labeltarafından sağlanır. - Tanıdık olmayan veya anlamı belirsiz olabilecek simgeler için paylaşılan
Tooltipde kullanılmalıdır; tooltiparia-labelyerine geçemez. - DOM
titleözelliğini ürün ipucu olarak kullanmayın; ayrıcatooltipayarlayı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
ButtonkullanarakIconButtontaklidi yapmayın. IconButtoniçinshapeayarlamayı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
hrefiçerenButtonkullanın.
3. Semantik Katmanlar variant
| Variant | Anlam | Tipik Senaryo | Kullanım Kısıtlaması |
|---|---|---|---|
primary | Mevcut alanın birincil işlemi | Kaydet, yayımla, oluştur, hemen dene | Bir görev alanında genellikle yalnızca bir birincil işlem bulunur |
secondary | Açık ancak ikincil işlem | Önizleme, iptal, geri, içe aktar | Birincil işlemle görsel dikkat için yarışmamalıdır |
ghost | Düşük vurgulu, bağlamsal araç işlemi | Kapat, daha fazla, araç çubuğu işlemi, hafif geri | Varsayılan olarak şeffaftır; tek başına kritik CTA olarak kullanılamaz |
danger | Silme veya belirgin zarar verme işlemi | Öğe sil, içerik kaldır, veriyi temizle | Yalnı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ı:
- Mevcut görev için tek en önemli sonraki adımı bulun ve onu
primaryolarak ayarlayın. - Hala net görünmesi gereken yardımcı işlemler için
secondarykullanın. - Araç çubuğu veya bağlamdaki düşük vurgulu işlemler için
ghostkullanın. - Yalnızca gerçekten yıkıcı işlemler için
dangerkullanı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
| Size | Yükseklik/Çap | Metin Yazı Tipi Boyutu | Önerilen Senaryo |
|---|---|---|---|
sm | 40px | 14px | Üst gezinme, kompakt araç çubukları, yoğun çalışma alanları |
md | 44px | 15px | Varsayılan formlar, CMS, iletişim kutuları ve genel işlemler |
lg | 48px | 16px | Pazarlama 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.
Buttonyüksekliği veIconButtonçapı aynı boyut token setini kullanır; bu nedenle aynı araç çubuğunda hizalanabilirler;IconButtongörünür simge boyutu tek tip 18px'dir.Buttonmetin 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
| Shape | Görünüm | Kullanım Kapsamı |
|---|---|---|
pill | Tam yuvarlak; metin içerdiğinde oval | Platform varsayılanı; pazarlama sayfaları, Dashboard, Builder, CMS ve Admin için uygundur |
rounded | 12px 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
leadingIconkullanır; metinden sonraki simgelertrailingIconkullanı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.
childreniç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
hrefiçermeyenButtonkullanın; nihai olarak<button>olarak işlenir. - Başka bir yola veya kaynağa gitmek için
hrefiçerenButtonkullanı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çatype="submit"yazmalıdır. - Normal sayfa gezinmesini taklit etmek için
onClickkullanmayı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-activekullanılır.focus-visiblenö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".
IconButtonyerelleştirilmişaria-labelsağ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
dangerkullanı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: 999pxile paylaşılan düğmeyi yeniden uygulamak; primary-alt,outline-blue,icon-roundgibi yerel görsel varyantlar eklemek;!importantile paylaşılan düğme sözleşmesiyle yarışmak;.qk-ui-buttontemel 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:
| Özellik | Varsayılan | Açıklama |
|---|---|---|
variant | primary | Semantik ve görsel katman |
size | md | Yükseklik, metin yazı tipi boyutu ve yatay iç boşluk |
shape | pill | Button köşe yuvarlaklık şekli |
leadingIcon | Yok | Metin öncesi simge |
trailingIcon | Yok | Metin sonrası simge |
href | Yok | Sağlandığında bağlantı olarak işlenir |
disabled | false | Etkileşimi devre dışı bırakır |
tooltip | Yok | Paylaşılan Tooltip için ek içerik; görünür kritik bilgilerin veya aria-label yerine geçemez |
tooltipPlacement | bottom | Tercih edilen yön; paylaşılan Tooltip viewport içinde kalmak için tersine dönebilir |
tooltipPortal | true | Kırpma kapsayıcısının dışında işlenir ve düzen sarma katmanı eklemez |
skin | Yok | skeleton/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
ButtonveyaIconButtonyeniden 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
primaryvar mı? secondary,ghost,dangerrenk tercihine göre değil semantiğe göre mi kullanılıyor?- Platform
Buttonvarsayılanpill'yi koruyor mu,IconButtonyuvarlak 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, CSSdata-tooltipbalonları, tekrarlanan ipuçları ve metin düğmelerinin eşanlamlı Tooltip'leri kaldırıldı mı? - Boyutlar yalnızca
sm,md,lgkullanı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,
IconButtonyerelleştirilmişaria-labeliç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.