Button बटन
Button और IconButton के अर्थ, आकार, रूप, स्थिति और पहुँच योग्यता के नियम।
AIबटन बटन के आकार और अर्थ का उपयोग करता है, जबकि एक अलग, अनुभवी Qokit AI अवस्था जोड़ता है।
AI बटन का चयन करें ताकि इसकी कार्यात्मक अवस्था का पूर्वावलोकन किया जा सके।
Qokit बटन घटक नियम
यह दस्तावेज़ Qokit प्लेटफ़ॉर्म, Builder, CMS, Dashboard, Admin, मार्केटिंग पेज और जनरेटेड साइट्स में बटन के उपयोग के नियमों को परिभाषित करता है। इसका उद्देश्य बटन घटकों, अर्थ, रूप, आकार, आइकन, स्थिति और पहुँच योग्यता को एकीकृत करना है, ताकि विभिन्न रूट आंशिक CSS के माध्यम से बटन को पुनः डिज़ाइन न करें।
1. कोर मॉडल
बटन केवल "अंडाकार, गोलाकार" के आधार पर वर्गीकृत नहीं होते, बल्कि ये पाँच स्वतंत्र आयामों से बने होते हैं:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- घटक प्रकार यह निर्धारित करता है कि बटन में दृश्यमान टेक्स्ट है या नहीं, और क्या इसे वर्गाकार क्लिक क्षेत्र बनाए रखना आवश्यक है।
- अर्थ प्राथमिकता वर्तमान कार्य में बटन की प्राथमिकता और रंग निर्धारित करती है।
- आकार स्थिर ऊँचाई, टेक्स्ट फ़ॉन्ट साइज़ और टच क्षेत्र निर्धारित करता है।
- रूप केवल कॉर्नर रेडियस निर्धारित करता है, प्राथमिकता या व्यावसायिक अर्थ व्यक्त नहीं करता।
- स्थानिक स्तर केवल यह बताता है कि नियंत्रण वर्तमान सतह से ऊपर उठता है या नहीं, कार्य अर्थ नहीं बदलता।
नए क्लास संयोजनों से नए बटन प्रकार न बनाएँ। पहले साझा घटक के मौजूदा गुणों में से चुनें।
2. घटक चयन
Button
सभी दृश्यमान टेक्स्ट वाले कार्यों के लिए उपयोग करें, जिनमें शामिल हैं:
- केवल टेक्स्ट बटन;
- आइकन टेक्स्ट से पहले वाला बटन;
- आइकन टेक्स्ट के बाद वाला बटन;
- बटन के रूप में दिखने वाले पेज लिंक।
प्लेटफ़ॉर्म में Button डिफ़ॉल्ट रूप से पूर्ण गोल pill का उपयोग करता है, जो दृश्य रूप से अंडाकार दिखता है। जब तक बटन में दृश्यमान टेक्स्ट हो, गोलाकार आइकन बटन का उपयोग नहीं करना चाहिए।
variant शैडो से अलग है: primary डिफ़ॉल्ट रूप से raised का उपयोग करता है, secondary, danger, ghost डिफ़ॉल्ट रूप से flat का उपयोग करते हैं। सूची पंक्तियों, कार्ड के अंदर, टूलबार और संयुक्त कैप्सूल के अंदर के कार्य flat होने चाहिए; स्वतंत्र मुख्य कार्य raised का उपयोग कर सकते हैं; केवल सामग्री पर तैरने वाले कार्य floating का उपयोग करते हैं। स्वतंत्र कैप्सूल या सेगमेंटेड नियंत्रण केवल सबसे बाहरी परत द्वारा एक बार शैडो खींचते हैं, रूट को साझा स्तर को आंशिक CSS से ओवरराइट नहीं करना चाहिए।
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
केवल एक आइकन वाले, बिना दृश्यमान टेक्स्ट के संक्षिप्त उपकरण कार्यों के लिए उपयोग करें, जैसे बंद करें, अधिक, वापस, मेनू टॉगल या हटाएँ।
IconButton प्रत्येक आकार में समान चौड़ाई, समान ऊँचाई और पूर्ण गोल बनाए रखता है, इसलिए दृश्य रूप से यह गोलाकार बटन है। यह डिफ़ॉल्ट रूप से ghost का उपयोग करता है और प्रकार स्तर पर aria-label को अनिवार्य करता है।
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>नियम:
- आइकन स्वयं
aria-hidden="true"का उपयोग करता है, बटन का नामaria-labelद्वारा प्रदान किया जाता है। - अपरिचित या अस्पष्ट अर्थ वाले आइकन को साझा
Tooltipके साथ उपयोग करना चाहिए; tooltiparia-labelका विकल्प नहीं हो सकता। - DOM
titleगुण को उत्पाद संकेत के रूप में उपयोग न करें, और न हीtooltipसेट करें और मैन्युअल रूप से Tooltip लपेटें। - Tooltip केवल पठनीय जानकारी परत है, अंडाकार बटन नहीं। यह साझा संक्षिप्त Tooltip कॉर्नर रेडियस का उपयोग करता है,
pill, बटन hover, pressed या focus दृश्य का पुन: उपयोग नहीं करना चाहिए। - खाली टेक्स्ट, छिपे टेक्स्ट या निश्चित चौड़ाई वाले
Buttonका उपयोग करकेIconButtonकी नक़ल न करें। IconButtonकोshapeसेट न करें; गोलाकार इसका घटक अनुबंध है।
ऐसे परिदृश्य जहाँ Button का उपयोग नहीं करना चाहिए
- टैब के लिए Tabs/PillTabs/Segmented जैसे संबंधित घटकों का उपयोग करें।
- मेनू आइटम के लिए Menu/ActionMenu संबंधित घटकों का उपयोग करें।
- स्थिति, लेबल और फ़िल्टर परिणामों के लिए Pill या स्थिति घटकों का उपयोग करें।
- सामान्य टेक्स्ट नेविगेशन के लिए अर्थ लिंक का उपयोग करें; केवल बटन स्तरीय दृश्य ज़ोर की आवश्यकता होने पर ही
hrefवालेButtonका उपयोग करें।
3. अर्थ स्तर variant
| Variant | अर्थ | सामान्य परिदृश्य | उपयोग सीमा |
|---|---|---|---|
primary | वर्तमान क्षेत्र का मुख्य कार्य | सहेजें, प्रकाशित करें, बनाएँ, अभी आज़माएँ | एक कार्य क्षेत्र में आमतौर पर केवल एक मुख्य कार्य |
secondary | स्पष्ट लेकिन कम प्राथमिकता वाला कार्य | पूर्वावलोकन, रद्द करें, वापस, आयात करें | मुख्य कार्य के साथ दृश्य ध्यान के लिए प्रतिस्पर्धा नहीं करनी चाहिए |
ghost | कम ज़ोर, संदर्भ उपकरण कार्य | बंद करें, अधिक, टूलबार कार्य, हल्का वापस | डिफ़ॉल्ट पारदर्शी, एकमात्र महत्वपूर्ण CTA नहीं हो सकता |
danger | हटाने या स्पष्ट नुकसान पहुँचाने वाला कार्य | आइटम हटाएँ, सामग्री हटाएँ, डेटा साफ़ करें | केवल विनाशकारी अर्थ व्यक्त करता है, सामान्य ज़ोर रंग के रूप में नहीं |
variant अर्थ और दृश्य स्तर व्यक्त करता है, रूप नहीं। उदाहरण के लिए ghost टेक्स्ट वाला अंडाकार बटन हो सकता है, या गोलाकार IconButton हो सकता है।
चयन क्रम:
- वर्तमान कार्य का एकमात्र सबसे महत्वपूर्ण अगला कदम खोजें, उसे
primaryके रूप में सेट करें। - स्पष्ट रूप से दृश्यमान सहायक कार्यों के लिए
secondaryका उपयोग करें। - टूलबार या संदर्भ में कम ज़ोर वाले कार्यों के लिए
ghostका उपयोग करें। - केवल वास्तविक विनाशकारी कार्यों के लिए
dangerका उपयोग करें, और मौजूदा पुष्टि प्रक्रिया का पालन करें।
"कौन सा रंग बेहतर दिखता है" के आधार पर variant न चुनें।
4. आकार size
| Size | ऊँचाई/व्यास | टेक्स्ट फ़ॉन्ट साइज़ | अनुशंसित परिदृश्य |
|---|---|---|---|
sm | 40px | 14px | शीर्ष नेविगेशन, संक्षिप्त टूलबार, घने कार्यक्षेत्र |
md | 44px | 15px | डिफ़ॉल्ट फ़ॉर्म, CMS, संवाद और सामान्य कार्य |
lg | 48px | 16px | मार्केटिंग पेज मुख्य CTA, बेहतर टच आवश्यकता वाले मुख्य कार्य |
डिफ़ॉल्ट आकार md है।
- एक ही बटन समूह में एक ही आकार का उपयोग करें।
- संक्षिप्त नियंत्रण 40px से कम नहीं हो सकते; मोबाइल मुख्य कार्यों के लिए कम से कम 44px को प्राथमिकता दें।
Buttonकी ऊँचाई औरIconButtonका व्यास एक ही आकार token का उपयोग करते हैं, इसलिए एक ही टूलबार में संरेखित हो सकते हैं;IconButtonका दृश्यमान आइकन आकार 18px पर एकीकृत है।Buttonटेक्स्ट फ़ॉन्ट साइज़ size के संबंधित साझा token द्वारा निर्धारित होता है, Header, Dialog या अन्य पैरेंट कंटेनर के फ़ॉन्ट साइज़ को इनहेरिट नहीं करता।- रूट CSS बटन की व्यवस्था, अंतराल और आवश्यक चौड़ाई को नियंत्रित कर सकता है, लेकिन साझा बटन की ऊँचाई या फ़ॉन्ट साइज़ को पुन: परिभाषित नहीं कर सकता।
- जब कॉपी लंबी हो, तो लेआउट या बटन कंटेनर को समायोजित करने को प्राथमिकता दें, ऊँचाई, फ़ॉन्ट या बाएँ-दाएँ अंतराल को सिकोड़कर हल न करें।
5. रूप shape
| Shape | प्रदर्शन | उपयोग सीमा |
|---|---|---|
pill | पूर्ण गोल; टेक्स्ट के साथ अंडाकार | प्लेटफ़ॉर्म डिफ़ॉल्ट, मार्केटिंग पेज, Dashboard, Builder, CMS और Admin के लिए उपयुक्त |
rounded | 12px कॉर्नर रेडियस | केवल जब जनरेटेड साइट थीम स्पष्ट रूप से छोटे कॉर्नर रेडियस की आवश्यकता करे |
Button डिफ़ॉल्ट shape="pill" है। प्लेटफ़ॉर्म फ्रंटएंड को स्पष्ट रूप से rounded सेट नहीं करना चाहिए, और न ही आंशिक CSS में कॉर्नर रेडियस को ओवरराइट करना चाहिए।
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton हमेशा गोलाकार होता है, pill / rounded के व्यावसायिक चयन में भाग नहीं लेता।
6. आइकन नियम
- टेक्स्ट से पहले के आइकन के लिए
leadingIconका उपयोग करें, टेक्स्ट के बाद के आइकन के लिएtrailingIconका उपयोग करें। - एक बटन में आमतौर पर केवल एक सहायक आइकन होता है।
- सहेजें, जोड़ें, वापस जैसे परिचित कार्यों के लिए आइकन का उपयोग पहचान को मजबूत करने के लिए किया जा सकता है, लेकिन आइकन महत्वपूर्ण बटन के दृश्यमान कॉपी का विकल्प नहीं हो सकता।
- तीर जारी रखने, प्रवेश करने या विस्तार करने का संकेत देता है तो आमतौर पर टेक्स्ट के बाद रखा जाता है; वापस आइकन आमतौर पर टेक्स्ट से पहले रखा जाता है।
childrenमें आइकन और टेक्स्ट का लेआउट मैन्युअल रूप से न लिखें, घटक पहले से icon और label स्लॉट प्रदान करता है।- साझा आइकन का उपयोग करें और
currentColorको इनहेरिट करें, रूट CSS में आइकन रंग या आकार को हार्डकोड न करें। - लोडिंग स्थिति में बटन की मूल चौड़ाई और ऊँचाई बनाए रखनी चाहिए, और समझने योग्य संक्षिप्त कॉपी या मौजूदा लोडिंग फ़ीडबैक प्रदान करनी चाहिए; कॉपी बदलने से टूलबार हिलने न दें।
7. बटन और लिंक
कार्य और नेविगेशन के लिए सही अर्थ का उपयोग करना आवश्यक है:
- सबमिट, सहेजें, पॉपअप खोलें, स्थिति टॉगल जैसे वर्तमान पेज कार्य,
hrefके बिनाButtonका उपयोग करें, अंतिम रूप से<button>के रूप में रेंडर होता है। - दूसरे रूट या संसाधन पर जाने के लिए,
hrefवालेButtonका उपयोग करें, अंतिम रूप से Next.js<Link>के रूप में रेंडर होता है। - फ़ॉर्म के अंदर गैर-सबमिट बटन को स्पष्ट रूप से
type="button"लिखना चाहिए; सबमिट बटन को स्पष्ट रूप सेtype="submit"लिखना चाहिए। - सामान्य पेज नेविगेशन की नक़ल के लिए
onClickका उपयोग न करें।
अक्षम लिंक aria-disabled का उपयोग करता है और Tab क्रम से बाहर निकलता है; अक्षम नेटिव बटन disabled का उपयोग करता है। अक्षम स्थिति केवल पारदर्शिता कम करके नहीं व्यक्त की जा सकती, व्यावसायिक तर्क को भी कार्य को रोकना चाहिए।
8. स्थिति और पहुँच योग्यता
साझा घटक hover, focus-visible, disabled और रंग स्थिति को एकीकृत रूप से संभालता है। व्यावसायिक कोड को अभी भी पूरा करना चाहिए:
- सामान्य अचयनित बटन hover
--control-surface-hoverका उपयोग करता है; pressed, चयनित और विस्तारित--control-surface-activeका उपयोग करता है।focus-visibleतटस्थ सतह पर--focus-ringबनाए रखता है, रूट शैली hover और निरंतर स्थिति को एक ही हल्के नीले नियम में नहीं मिला सकती। - बटन का नाम सीधा, विशिष्ट होना चाहिए और बताना चाहिए कि क्या होगा, जैसे "सहेजें" "वेबसाइट प्रकाशित करें" "आइटम हटाएँ"।
IconButtonको स्थानीयकृतaria-labelप्रदान करनी चाहिए।- सजावटी आइकन
aria-hidden="true"का उपयोग करते हैं, स्क्रीन रीडर द्वारा दोहराए जाने से बचने के लिए। - कीबोर्ड फ़ोकस दृश्यमान होना चाहिए; रूट CSS साझा focus ring को नहीं हटा सकता।
- hover को एकमात्र संकेत के रूप में उपयोग न करें, इंटरैक्शन को कीबोर्ड और टच दोनों का समर्थन करना चाहिए।
- अक्षम बटन केवल उन कार्यों के लिए है जो उपयोगकर्ता अस्थायी रूप से नहीं कर सकता; यदि कारण समझाने की आवश्यकता हो, तो निकटस्थ स्पष्टीकरण या tooltip प्रदान करें।
- त्रुटि, अनुमति आवश्यकताएँ, जोखिम, शुल्क और अन्य कार्य-महत्वपूर्ण जानकारी दृश्यमान रहनी चाहिए; Tooltip केवल जानकारी का पूरक हो सकता है, इन जानकारी को खोजने का एकमात्र तरीका नहीं।
- एसिंक ऑपरेशन को दोहराए सबमिट से रोकना चाहिए, और समझने योग्य प्रगति फ़ीडबैक बनाए रखना चाहिए।
- खतरनाक कार्य
dangerका उपयोग करते हैं, और मौजूदा खतरनाक पुष्टि pattern का पुन: उपयोग करते हैं; केवल लाल रंग पर जोखिम传达 करने पर निर्भर न करें। - चीनी या अन्य भाषाओं के बटन कॉपी को इतना काटा नहीं जाना चाहिए कि समझ में न आए। लंबी कॉपी और मोबाइल चौड़ाई की पुष्टि करनी चाहिए।
9. शैली जिम्मेदारी सीमाएँ
साझा बटन की संरचना, अर्थ और स्थिति Button / IconButton की जिम्मेदारी है; दृश्य token और साझा CSS घटक पैकेज की जिम्मेदारी है; रूट केवल लेआउट की जिम्मेदारी लेता है।
साझा परत जिम्मेदार है
- DOM, लिंक/बटन अर्थ, disabled व्यवहार;
- icon/label स्लॉट और पहुँच योग्यता प्रकार बाधाएँ;
- variant, size, shape class;
- ऊँचाई, कॉर्नर रेडियस, पैडिंग, फ़ॉन्ट साइज़, फ़ॉन्ट वेट;
- पृष्ठभूमि, टेक्स्ट रंग, शैडो, hover, focus-visible और disabled स्थिति।
रूट परत जिम्मेदार हो सकती है
- बटन समूह दिशा, अंतराल, संरेखण और रैपिंग;
- प्रतिसादी व्यवस्था;
- विशिष्ट कार्यप्रवाह के लिए आवश्यक
width: 100%या कंटेनर चौड़ाई; - मूल दृश्य को न बदलने वाले पोजिशनिंग क्लास।
रूट परत जिम्मेदार नहीं हो सकती
- बटन ऊँचाई, फ़ॉन्ट साइज़, कॉर्नर रेडियस, पृष्ठभूमि, टेक्स्ट रंग, शैडो या focus ring को फिर से लिखना;
- हार्डकोडेड रंग या
border-radius: 999pxका उपयोग करके साझा बटन को पुन: लागू करना; primary-alt,outline-blue,icon-roundजैसे स्थानीय दृश्य variant जोड़ना;!importantके साथ साझा बटन अनुबंध से प्रतिस्पर्धा करना;.qk-ui-buttonकी मूल शैली की सीधी प्रतिलिपि बनाना।
यदि वास्तव में कई पेजों को नए अर्थ variant की आवश्यकता हो, तो पहले साझा ButtonVariant, token और primitives.css में एकीकृत अनुबंध स्थापित करें, रूट में नई शैली न जोड़ें।
10. API त्वरित संदर्भ
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Button के मुख्य गुण:
| गुण | डिफ़ॉल्ट मान | विवरण |
|---|---|---|
variant | primary | अर्थ और दृश्य स्तर |
size | md | ऊँचाई, टेक्स्ट फ़ॉन्ट साइज़ और क्षैतिज पैडिंग |
shape | pill | Button का कॉर्नर रेडियस रूप |
leadingIcon | कोई नहीं | टेक्स्ट से पहले का आइकन |
trailingIcon | कोई नहीं | टेक्स्ट के बाद का आइकन |
href | कोई नहीं | प्रदान होने पर लिंक के रूप में रेंडर |
disabled | false | इंटरैक्शन अक्षम करें |
tooltip | कोई नहीं | साझा Tooltip का पूरक सामग्री; दृश्यमान महत्वपूर्ण जानकारी या aria-label का विकल्प नहीं हो सकता |
tooltipPlacement | bottom | प्राथमिकता दिशा; साझा Tooltip व्यूपोर्ट में रहने के लिए पलट सकता है |
tooltipPortal | true | क्लिपिंग कंटेनर के बाहर रेंडर करता है, और लेआउट रैपर नहीं जोड़ता |
skin | कोई नहीं | skeleton/skin अनुबंध के अनुसार class स्लॉट और चर अनुकूलन प्रदान करता है |
IconButton लागू Button गुणों को इनहेरिट करता है, लेकिन shape, leadingIcon या trailingIcon प्रदान नहीं करता; इसे aria-label आवश्यक है, डिफ़ॉल्ट variant="ghost"।
व्यावसायिक कोड में स्पष्ट रूप से variant और नेटिव बटन type लिखने की अनुशंसा की जाती है, ताकि कार्य अर्थ कोड समीक्षा में स्पष्ट रूप से दिखाई दे।
11. सामान्य संयोजन
// 主要操作:椭圆形文字按钮
<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. समीक्षा चेकलिस्ट
बटन संबंधित UI सबमिट करने से पहले, पुष्टि करें:
- क्या
ButtonयाIconButtonका पुन: उपयोग प्राथमिकता दी गई? - टेक्स्ट वाले और केवल आइकन वाले बटनों के लिए सही घटक चुना गया?
- वर्तमान कार्य क्षेत्र में केवल एक स्पष्ट
primaryहै? secondary,ghost,dangerका उपयोग अर्थ के आधार पर किया गया है, रंग प्राथमिकता के आधार पर नहीं?- प्लेटफ़ॉर्म
Buttonडिफ़ॉल्टpillबनाए रखता है,IconButtonगोलाकार बनाए रखता है? - प्रत्येक Tooltip अभी भी संक्षिप्त कॉर्नर रेडियस वाली जानकारी परत है, क्लिक करने योग्य अंडाकार बटन जैसी नहीं?
- क्या ब्राउज़र नेटिव
title, CSSdata-tooltipबबल, दोहरे संकेत और टेक्स्ट बटन के समानार्थी Tooltip हटा दिए गए हैं? - क्या आकार केवल
sm,md,lgका उपयोग करता है, और एक ही समूह में ऊँचाई और फ़ॉन्ट साइज़ सुसंगत है? - क्या नेटिव बटन को स्पष्ट रूप से सही
typeसेट किया गया है? - क्या आइकन ने दोहराए स्क्रीन रीडर जानकारी को छिपाया है,
IconButtonमें स्थानीयकृतaria-labelहै? - focus-visible, disabled, एसिंक और खतरनाक पुष्टि स्थिति पूर्ण है?
- क्या रूट CSS केवल लेआउट संभालता है, बटन मूल दृश्य को ओवरराइट नहीं करता?
- क्या डेस्कटॉप और मोबाइल चौड़ाई पर लंबी कॉपी, टच आकार और बटन समूह व्यवस्था की पुष्टि की गई है?
13. कार्यान्वयन स्रोत
- घटक API:
packages/components/src/ui/Button/Button.tsx - घटक निर्यात:
packages/components/src/ui/Button/index.ts - आकार और रंग token:
packages/components/src/styles/foundations.css - साझा बटन शैली:
packages/components/src/styles/primitives.css - सार्वजनिक घटक एकीकरण अनुबंध:
docs/public/design/component-integration.md
जब दस्तावेज़ और कार्यान्वयन में अंतर हो, तो उसी बदलाव में घटक, token, शैली और इस दस्तावेज़ को सिंक्रनाइज़ करना चाहिए।