Documentation और Styleguide एकीकरण

हर कॉम्पोनेंट के लिए उसे उपयोग करने हेतु न्यूनतम HTML दिखाएँ: <app-button variant="primary">Save</app-button>। वेरिएंट (प्राथमिक, द्वितीयक, जोखिमपूर्ण), स्थितियाँ (लोड हो रहा है, अक्षम) और किनारे के मामले (लंबा पाठ, आइकन सहित, पूरी चौड़ाई) दिखाएँ। ऐसे उदाहरण जिन्हें वास्तविक पेज में ठीक उसी तरह कॉपी-पेस्ट किया जा सके, वही टीमें वास्तव में उपयोग करती हैं।

सबसे अच्छे दस्तावेज़ स्रोत कोड के बगल में उदाहरण रेंडर करते हैं। Storybook यह मूल रूप से करता है; mdx-deck, Docusaurus और Astro Starlight लाइव JSX के साथ MDX का समर्थन करते हैं। मार्कअप पढ़ते समय वास्तविक परिणाम देखना “क्या यह काम करेगा?” वाली शंका को तुरंत दूर कर देता है।

हर कॉम्पोनेंट में शामिल किए गए अभिगम्यता व्यवहार का दस्तावेज़ीकरण करें: कौन-सी कीबोर्ड अंतःक्रियाएँ, कौन-सी ARIA भूमिकाएँ और कौन-सा फ़ोकस प्रबंधन। कॉम्पोनेंट अपनाने वाले उपभोक्ताओं को अभिगम्यता बिना अतिरिक्त प्रयास मिलती है और समीक्षक यह जाँच सकते हैं कि वे अनुबंध नहीं तोड़ रहे हैं।

स्पष्ट प्रतिकूल पैटर्न दिखाएँ: “महत्वपूर्ण अस्थायी प्रतिक्रिया के लिए मोडल का उपयोग न करें—इसके बजाय टोस्ट का उपयोग करें।” नकारात्मक उदाहरण अक्सर सकारात्मक उदाहरण से अधिक याद रहता है। विफलता के तरीकों को स्पष्ट करने के लिए हर क्या करें के साथ एक स्पष्ट क्या न करें भी दें।

नामकरण के पैटर्न का दस्तावेज़ीकरण करें: BEM, परमाणु CSS, CSS मॉड्यूल और Tailwind यूटिलिटी संयोजन। क्लास नामों, कस्टम प्रॉपर्टी नामों और फ़ाइल पथों के नियम स्पष्ट रूप से लिखें। एकसमान नामकरण मानसिक बोझ घटाता है; असंगत नामकरण हमेशा हर डेवलपर का समय खर्च करता है।

केवल यह नहीं, बल्कि यह भी दर्ज करें कि निर्णय क्यों लिए गए। “हमने Vue के बजाय React चुना क्योंकि…” भविष्य के योगदानकर्ताओं के लिए संदर्भ सुरक्षित रखता है। ADR (वास्तु-निर्णय अभिलेख) कोड के पास मार्कडाउन में रखने का एक हल्का प्रारूप है, जो टीम बदलने के बाद भी उपयोगी रहता है।

नए टीम सदस्यों को एक दिन में अपना पहला कॉम्पोनेंट जारी कर पाना चाहिए। जाँच-सूची: रिपॉज़िटरी सेट अप करें, निर्भरताएँ स्थापित करें, Storybook चलाएँ, सही कॉम्पोनेंट टेम्पलेट खोजें, दस्तावेज़ लिखें और PR खोलें। पहले PR तक लगने वाले समय को मापदंड के रूप में ट्रैक करें; कम समय बेहतर है।

सबसे अच्छे दस्तावेज़ नए खोजकर्ताओं और अनुभवी उपयोगकर्ताओं, दोनों के लिए आसानी से मिल जाने चाहिए। खोज-सक्षम दस्तावेज़ साइट का उपयोग करें (Docusaurus के लिए Algolia, Starlight के लिए अंतर्निर्मित खोज)। कॉम्पोनेंट को कई वैकल्पिक नामों से टैग करें—“मोडल” को डायलॉग, पॉपअप और ओवरले खोजों से भी खोजा जा सके।

दस्तावेज़ों के साथ दृश्य प्रतिगमन जोड़ें: Chromatic हर PR पर हर Storybook कहानी का स्नैपशॉट लेता है और दृश्य अंतर दिखाता है। ऐसा मर्ज किया गया PR जो गलती से दस्तावेज़ों में बटन की शैली बदल देता है, स्वयं रुक जाता है। इससे दस्तावेज़ीकरण और डिज़ाइन सिस्टम का सक्रिय परीक्षण एक साथ हो जाता है।

उन बातों का दस्तावेज़ीकरण करें जिन्हें केवल रखरखावकर्ता जानता है: सावधानियाँ, आधे-अधूरे अमूर्तन और साफ़ किए जाने की प्रतीक्षा कर रहे अस्थायी जुगाड़। भविष्य का आप (या आपका स्थान लेने वाला व्यक्ति) इस संस्थागत ज्ञान को भूलने से पहले दर्ज करने के लिए वर्तमान के आप के आभारी होंगे।

दस्तावेज़ीकरण डिज़ाइन सिस्टम के मूल्य को कई गुना बढ़ाता है। ऐसे जीवंत दस्तावेज़ीकरण (Storybook, Histoire, Ladle) का उपयोग करें जो वास्तविक कॉम्पोनेंट कोड आयात करते हैं। न्यूनतम-उपयोगी उदाहरण दिखाएँ, अभिगम्यता का दस्तावेज़ीकरण करें, निर्णय दर्ज करें, क्या करें और क्या न करें की जोड़ियाँ लिखें और दृश्य प्रतिगमन परीक्षणों के साथ इनका उपयोग करें। दस्तावेज़ों को बाद में याद आने वाली चीज़ नहीं, बल्कि प्रथम-श्रेणी का सुपुर्दगी-योग्य कार्य मानें।