कार्ड और सतह स्तर
सामग्री कार्ड, वर्कस्पेस शेल, ओवरले, छाया और पृष्ठभूमि फ्रॉस्टिंग के उपयोग के नियम।
सामग्री कार्ड फ्लैट रहते हैं; बाहरी खोल कार्यस्थल समूहन को संचारित करता है।
एक मानक सामग्री कार्ड बाहरी छाया का उपयोग नहीं करता है।
चयन और अवस्था रंग और सूचना प्राथमिकता के माध्यम से संचारित की जाती है।
कार्ड सामग्री और स्तर मानक
यह दस्तावेज़ सार्वजनिक रूप से बताता है कि Qokit कार्य इंटरफ़ेस किन परिदृश्यों में छाया, पारदर्शिता, ग्रेडिएंट और पृष्ठभूमि फ्रॉस्टिंग का उपयोग करता है। यह प्लेटफ़ॉर्म विस्तार, Builder, CMS, Dashboard, Studio और Admin पर लागू होता है। मार्केटिंग पेज और जनरेटेड साइट अधिक अभिव्यंजक हो सकती हैं, लेकिन प्रभाव वर्तमान थीम से संबंधित होने चाहिए और सामग्री की पठनीयता सुनिश्चित करनी चाहिए।
मूल सिद्धांत
दृश्य प्रभाव संरचना व्यक्त करने के लिए उपयोग किए जाते हैं, प्रत्येक ब्लॉक को सजाने के लिए नहीं:
- सामग्री पृष्ठभूमि रंग अंतर के माध्यम से अलग की जाती है।
- कंटेनर पारदर्शिता या संयमित ग्रेडिएंट के माध्यम से संबंध व्यक्त करते हैं।
- ओवरले छाया के माध्यम से स्तर व्यक्त करते हैं।
- इंटरैक्शन रंग और फोकस रिंग के माध्यम से स्थिति व्यक्त करते हैं।
स्वतंत्र ठोस रंग कार्ड और इनपुट फ़ील्ड साझा प्राथमिक हल्की छाया का उपयोग करते हैं; सूचियाँ, नेस्टेड सतहें और पारदर्शी समूह समतल रहते हैं; केवल वास्तविक ओवरले स्पष्ट छाया का उपयोग करते हैं।
निर्णय क्रम
सामग्री प्रभाव जोड़ने से पहले, पहले सतह की भूमिका निर्धारित करें:
- क्या यह स्वतंत्र ठोस रंग कार्ड या इनपुट फ़ील्ड है? साझा प्राथमिक सतह या फ़ील्ड छाया का उपयोग करें।
- क्या यह सूची पंक्ति, नेस्टेड कार्ड, दोहराया गया विकल्प या पारदर्शी समूह है? समतल रखें।
- क्या यह कई आंतरिक सामग्री कार्डों को एक वर्कस्पेस में व्यवस्थित करता है? शेल का उपयोग करें।
- क्या यह पेज सामग्री को कवर करता है या वर्तमान समतल के ऊपर दिखाई देता है? ओवरले छाया का उपयोग करें।
- क्या यह ड्रैग, ज़ूम या अस्थायी होवर स्थिति में है? अस्थायी छाया का उपयोग करें।
- क्या यह केवल hover, चयन या focus व्यक्त करने के लिए है? साझा hover भूमिका, इंटरैक्शन पृष्ठभूमि रंग और फोकस रिंग का उपयोग करें।
जब तक सतह की भूमिका को वास्तव में आवश्यकता न हो, तब तक छाया, पारदर्शिता, ग्रेडिएंट और फ्रॉस्टिंग को एक साथ न जोड़ें।
परिदृश्य मैट्रिक्स
| सतह भूमिका | छाया | पारदर्शिता या ग्रेडिएंट | पृष्ठभूमि फ्रॉस्टिंग |
|---|---|---|---|
| स्वतंत्र ठोस रंग सामग्री कार्ड, मेट्रिक कार्ड | साझा प्राथमिक हल्की छाया | हल्की पृष्ठभूमि रंग अंतर की अनुमति | नहीं |
| सूची पंक्ति, नेस्टेड कार्ड, पारदर्शी समूह, दोहराए गए विकल्प | नहीं | हल्की पृष्ठभूमि रंग अंतर की अनुमति | नहीं |
| पेज आंतरिक समूह शेल | नहीं | अनुशंसित | आमतौर पर आवश्यक नहीं |
| साइडबार या स्थायी वर्कस्पेस शेल | हल्का | अनुशंसित | पीछे दृश्य सामग्री होने पर अनुमति |
| Dialog, Popover, Dropdown, संदर्भ मेनू | स्पष्ट ओवरले छाया | पृष्ठभूमि पठनीयता सुनिश्चित करने के लिए पर्याप्त ठोस होनी चाहिए | अनुमति |
| ड्रैग पूर्वावलोकन, ज़ूम स्थिति, होवर पूर्वावलोकन | अस्थायी रूप से मजबूत | वैकल्पिक | आमतौर पर आवश्यक नहीं |
| Hover | प्राथमिक छाया बनाए रखें या हल्की रूप से बढ़ाएँ | पृष्ठभूमि बदल सकते हैं | नहीं बदलता |
| चयन या सक्रिय स्थिति | नहीं | एक्सेंट रंग पृष्ठभूमि या संयमित ग्रेडिएंट | नहीं बदलता |
| इनपुट फ़ील्ड, खोज बॉक्स | अत्यंत हल्की फ़ील्ड छाया | नियंत्रण सतह रंग का उपयोग करें | आमतौर पर आवश्यक नहीं |
| स्वतंत्र प्राथमिक क्रिया, स्वतंत्र कैप्सूल, सेगमेंटेड नियंत्रण शेल | अत्यंत हल्की नियंत्रण छाया | नियंत्रण सतह रंग का उपयोग करें | आमतौर पर आवश्यक नहीं |
| टूलबार और पारदर्शी आंतरिक नियंत्रण | नहीं | नियंत्रण सतह रंग या पारदर्शी का उपयोग करें | आमतौर पर आवश्यक नहीं |
| मार्केटिंग पेज या जनरेटेड साइट दृश्य कार्ड | थीम द्वारा निर्धारित | अनुमति | संयमित उपयोग |
घटक मैपिंग
<Card>डिफ़ॉल्ट रूप सेlayer="content"का उपयोग करता है: साझा प्राथमिक हल्की छाया, कोई बॉर्डर नहीं, डिफ़ॉल्ट20pxगोल कोने; muted, नेस्टेड, सूची और पारदर्शी वेरिएंट समतल रहते हैं।<Card layer="shell">: पेज में केवल समूहीकरण के लिए जिम्मेदार, पारदर्शी या हल्के ग्रेडिएंट सतह का उपयोग करता है और समतल रहता है; स्थायी वर्कस्पेस शेल अपने संबंधित मोड द्वारा अलग से स्तर प्रदान करता है।<Card shape="pill">: कॉम्पैक्ट एकल-पंक्ति कार्ड के लिए उपयोग किया जाता है, गोल कोने अंडाकार कैप्सूल आकार के होते हैं।SidebarNavigation: स्वतंत्र वर्कस्पेस शेल, स्पष्ट ग्रेडिएंट, पारदर्शिता, फ्रॉस्टिंग और हल्की छाया बनाए रखता है।- Studio का
PromptPanelजब वर्कस्पेस कंटेनर के रूप में उपयोग होता है:--workspace-shell-shadowका उपयोग करता है। DialogPanel, ड्रॉपडाउन मेनू, Popover, संदर्भ मेनू और अवधारणा ब्राउज़र: ओवरले छाया का उपयोग करता है।- Builder कैनवास, डिवाइस पूर्वावलोकन, जनरेटेड साइट पूर्वावलोकन, ड्रैग पूर्वावलोकन और ज़ूम स्थिति: क्योंकि ये स्वतंत्र पूर्वावलोकन समतल या अस्थायी इंटरैक्शन परत का प्रतिनिधित्व करते हैं, समर्पित छाया बनाए रख सकते हैं।
परत-दर-परत तैरती सामग्री कार्ड न बनाएँ। यदि बाहरी समूहीकरण वास्तव में आवश्यक है, तो यह समतल शेल होना चाहिए। वास्तविक ओवरले को छोड़कर, एक ही DOM पूर्वज श्रृंखला में अधिकतम एक सामान्य सामग्री या नियंत्रण छाया दिखाई दे सकती है।
डिज़ाइन वेरिएबल (Token) उपयोग
साझा Token को प्राथमिकता दें, प्रभावों को हार्ड-कोड न करें:
- सामग्री कार्ड छाया:
--card-shadow: var(--qk-shadow-surface) - सामग्री कार्ड hover छाया:
--card-shadow-hover: var(--qk-shadow-surface-hover) - फ़ील्ड छाया:
--input-shadow: var(--qk-shadow-field) - फ़ील्ड सक्रिय छाया:
--input-state-shadow: var(--qk-shadow-field-active) - नियंत्रण छाया:
--qk-shadow-control/--qk-shadow-control-hover - प्राथमिक क्रिया नियंत्रण छाया:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - सामग्री कार्ड फ्रॉस्टिंग:
--card-backdrop-filter: none - शेल सतह:
--card-shell-surface - शेल फ्रॉस्टिंग:
--card-shell-backdrop-filter - वर्कस्पेस शेल छाया:
--workspace-shell-shadow - Dialog सतह:
--dialog-surface, संयमित थीम ग्रेडिएंट प्रदान करता है - Dialog फ्रॉस्टिंग:
--dialog-backdrop-filter - Dialog ओवरले छाया:
--dialog-shadow - Dialog गोल कोने:
--card-radiusपुन: उपयोग करें - कीबोर्ड फोकस:
--focus-ring - ओवरले छाया: मौजूदा Dialog, Dropdown, Menu या पेज-स्तरीय ओवरले Token का उपयोग करें
सामान्य सामग्री कार्ड और वर्कस्पेस पैनल मजबूत सामान्य --shadow Token का उपयोग नहीं कर सकते हैं।
वैश्विक छाया "छोटा विस्थापन, कम अपारदर्शिता, रखे जाने के स्तर के अनुसार बढ़ती हुई" एक शांत पैमाना अपनाती है। सामान्य Card, फ़ील्ड और नियंत्रण राउटिंग में साझा छाया को गहरा या बड़ा नहीं कर सकते हैं; Popover और Dialog बड़े विस्थापन और धुँधले दायरे के माध्यम से पेज से अलग होना व्यक्त करते हैं, न कि गहरी ग्रे धुंध को जोड़कर।
इंटरैक्शन नियम
होवर (Hover)
- सामग्री कार्ड
--qk-shadow-surface-hoverसे ऊपर के स्तर पर नहीं उठना चाहिए। translateYके माध्यम से सामग्री कार्ड नहीं उठाएँ।- हल्की पृष्ठभूमि परिवर्तन या स्पष्ट नियंत्रण प्रतिक्रिया का उपयोग करें।
- आकार न बदलें, असंगत गोल कोने या छाया कटिंग से बचें।
चयन और सक्रियण
- एक्सेंट रंग सतह, आइकन स्थिति, अर्थपूर्ण स्थिति या संयमित ग्रेडिएंट का उपयोग करें।
- केवल छाया के माध्यम से स्थिति व्यक्त न करें।
कीबोर्ड फोकस
- साझा focus-visible नियम या
--focus-ringका उपयोग करें। - सामान्य कार्ड छाया फोकस संकेत का स्थान नहीं ले सकती है।
- हल्की और गहरी थीम दोनों के तहत स्पष्ट रूप से दिखाई देनी चाहिए।
ड्रैग और ज़ूम
- केवल तभी मजबूत छाया की अनुमति है जब परत वास्तव में चल रही हो या आकार बदल रही हो।
- इंटरैक्शन समाप्त होने पर अस्थायी छाया हटा दी जानी चाहिए।
- ओवरफ्लो कंटेनर चलती परत की प्रतिक्रिया प्रभाव को नहीं काट सकते हैं।
पारदर्शिता और पृष्ठभूमि फ्रॉस्टिंग
पारदर्शिता बाहरी सतह और वर्कस्पेस के संबंध को व्यक्त करने के लिए उपयोग की जाती है। पृष्ठभूमि फ्रॉस्टिंग केवल तभी सार्थक है जब सतह के पीछे वास्तव में दृश्य सामग्री, रंग या छवि हो।
- ठोस रंग पृष्ठभूमि पर फ्रॉस्टिंग का उपयोग न करें, यह केवल रेंडरिंग लागत बढ़ाता है, स्तर व्यक्त नहीं करता है।
- पीछे कोई भी पृष्ठभूमि हो, टेक्स्ट, आइकन और नियंत्रण स्पष्ट रूप से पठनीय होने चाहिए।
- जब ब्राउज़र पृष्ठभूमि फ्रॉस्टिंग का समर्थन नहीं करता है, तो अपारदर्शी या पठनीय फ़ॉलबैक पृष्ठभूमि होनी चाहिए।
- घने कार्य इंटरफ़ेस में धुँधपन की तीव्रता संयमित होनी चाहिए।
- हल्की और गहरी थीम दोनों का एक साथ सत्यापन आवश्यक है।
छाया बनाए रखने की अनुमति वाले अपवाद
- वर्कस्पेस साइडबार शेल
- Dialog, Popover, Dropdown, मेनू और मोडल पैनल
- Studio अवधारणा ब्राउज़र और पुष्टि ओवरले
- Builder कैनवास, डिवाइस फ्रेम और जनरेटेड साइट पूर्वावलोकन समतल
- ड्रैग पूर्वावलोकन, ज़ूम प्रतिक्रिया और अस्थायी होवर टूल
- प्राथमिक क्रिया बटन जिनके लिए साझा बटन Token ने छाया परिभाषित की है
- वर्तमान थीम द्वारा नियंत्रित मार्केटिंग पेज और जनरेटेड साइट दृश्य तत्व
ये अपवाद व्यापक चयनकर्ताओं या साझा Token के माध्यम से सामान्य सामग्री कार्ड को प्रभावित नहीं कर सकते हैं।
समीक्षा चेकलिस्ट
- स्वतंत्र ठोस रंग सामग्री कार्ड और इनपुट फ़ील्ड केवल साझा प्राथमिक हल्की छाया भूमिका का उपयोग करते हैं।
- स्वतंत्र प्राथमिक क्रिया, स्वतंत्र कैप्सूल और सेगमेंटेड नियंत्रण शेल केवल साझा अत्यंत हल्की नियंत्रण छाया का उपयोग करते हैं।
- पेज समूहीकरण, सूची पंक्तियाँ, नेस्टेड कार्ड, पारदर्शी समूह, दोहराए गए Tab/Pill, टूलबार और संयुक्त नियंत्रण आंतरिक आइटम समतल रहते हैं।
- टूलबार में खोज, फ़िल्टर, क्रमबद्ध करना, दृश्य और इनलाइन प्राथमिक क्रिया समतल रहती हैं; सामान्य इनपुट फ़ील्ड की हल्की छाया टूलबार में नहीं फैल सकती है, कीबोर्ड फोकस रिंग को छोड़कर।
- जब Segmented पहले से छाया वाले कार्ड, संवाद या टूलबार के अंदर होता है, तो शेल और चयनित आइटम दोनों समतल रहते हैं; माउस क्लिक कीबोर्ड फोकस रिंग नहीं दिखाता है।
- वास्तविक ओवरले को छोड़कर, एक ही पूर्वज श्रृंखला में कई सामान्य छायाएँ नहीं जोड़ी जाती हैं।
- hover सामग्री कार्ड को लंबवत रूप से स्थानांतरित नहीं करता है।
- नेस्टेड सामग्री कार्ड हटा दिए गए हैं, या बाहरी परत को स्पष्ट रूप से शेल के रूप में परिभाषित किया गया है।
- केवल वास्तविक शेल
--workspace-shell-shadowका उपयोग करते हैं। - केवल वास्तविक ओवरले और अस्थायी इंटरैक्शन परतें मजबूत छाया का उपयोग करती हैं।
- पृष्ठभूमि फ्रॉस्टिंग के पीछे दृश्य सामग्री मौजूद है, और पठनीय फ़ॉलबैक पृष्ठभूमि है।
- focus-visible फोकस रिंग का उपयोग करता है।
- हल्की और गहरी थीम दोनों पर्याप्त कंट्रास्ट बनाए रखती हैं।
- गोल कोने वाली सतहें hover, focus, ड्रैग या ओवरले प्रतिक्रिया को नहीं काटती हैं।
- डेस्कटॉप और मोबाइल चौड़ाई पर नया क्षैतिज ओवरफ्लो नहीं होता है।
npm run ui:check-card-surfaces --workspace @qokit-ai/webजाँच पास हो गई।