Atlassian का DESIGN.md प्रकाशित - portable design context को व्यवहार में टेस्ट करने से मिली सीख

• AI द्वारा बनाए गए UI के brand identity के बिना generic बन जाने वाली "slop" समस्या को हल करने के लिए portable Markdown format; design system के मुख्य तत्वों को एक फ़ाइल में रखकर prompt में शामिल करने का तरीका
• DESIGN.md दो हिस्सों से बना है: machine-readable design tokens और इंसानों व agents के लिए पढ़ने योग्य design rationale; यह system की पूरी technical specification नहीं, बल्कि intent को समेटता है
• Team '26 keynote demo में Figma Make dashboard generation पर लागू करने पर रंग, spacing, shape और typography Atlassian system के अनुरूप align हुए और one-shot prototype में अच्छा प्रदर्शन दिखा
• हालांकि production codebase में अपने MCP server और skills की तुलना में लगभग 92% अधिक tokens खर्च हुए, generation time बढ़ा, और runs के बीच token consumption में लगभग 2.7 गुना variation रहा, जिससे efficiency घटी
• Portability और conciseness जैसी इसकी विशिष्ट ताकतें cross-platform portability, customer theming, नए environments में prototyping के लिए मूल्यवान हैं; यह rich design system tools का replacement नहीं, बल्कि complement है

---

पृष्ठभूमि - AI UI की "slop" समस्या

• जब AI UI generate करता है, तो gradient buttons, uppercase titles, generic card layouts, गैर-ज़रूरी hover animations जैसे outputs मिलते-जुलते होने लगते हैं; functionality काम करती है, पर visual identity की कमी रहती है
• design community ऐसे outputs को "slop" कहती है: functional, लेकिन intended design decisions के बिना बना output
• कारण brand, components और patterns पर context की कमी है; AI training data के average पर default output देता है → "Generic in, generic out"
• Atlassian design system team AI युग के लिए context engine बना रही है, और ADS MCP server व detailed AI skills के ज़रिए agents को rich design context देती है
  • इसके जरिए AI token cost में कमी और हज़ारों product builders द्वारा बनाए गए outputs की accuracy व quality में सुधार देखा गया

DESIGN.md overview

• Google ने अपने Stitch design tool के लिए बनाया open source Markdown format, जो team के brand और UI patterns का portable snapshot है
• इसे फ़ाइल में शामिल कर prompt में डालने पर generated outputs अपने product जैसे दिखने लगते हैं—काम करने का सिद्धांत इतना सरल है

• यह क्या है (What it is)

  • design system के केवल core elements को describe करने वाली portable Markdown file
  • पहला हिस्सा machine-readable design tokens की सूची देता है
  • दूसरा हिस्सा इंसानों और agents के पढ़ने के लिए रंग, spacing, layout, elevation, components आदि का design rationale बताता है

• यह क्या नहीं है (What it isn't)

  • production में design system कैसे काम करता है, इसकी पूरी technical specification या system की complete details नहीं है
  • existing code libraries, coding standards बनाए रखने वाले linters, या Figma की detailed design specs इसमें शामिल नहीं हैं
  • specification इस format को system की पूरी details नहीं, बल्कि intent capture करने वाला बताती है

अपना DESIGN.md बनाना

• Atlassian पहले से MCP server, structured content pipeline और कई agent skills के जरिए design system को AI consumption के लिए तैयार कर रहा था
• MCP और agent skills चलाने वाली उसी structured content pipeline से अपना DESIGN.md generate किया गया
• सामान्य vibe coding tools में format test किया गया, और existing guides में नहीं थीं ऐसी common mistakes के लिए ज्यादा strict instructions जोड़ी गईं

Team '26 में test

• एक महीने पहले Anaheim में खत्म हुआ Team '26 keynote demo उपयुक्त test case के रूप में इस्तेमाल हुआ
• keynote के एक demo में Figma Make ने Teamwork Graph का उपयोग करके custom dashboard generate किया; लक्ष्य था internal MCP servers और tools पर निर्भर हुए बिना, एक ही बार में design language align करना
• DESIGN.md लागू करने पर output generic "slop" से बदलकर पहचानने योग्य Atlassian result बन गया: रंग, spacing, shape और typography में expected values का इस्तेमाल हुआ और components में system-aligned elevation लागू हुआ
• फ़ाइल के high-level instructions और specs Tailwind, Shadcn जैसी common libraries को customize करके शुरू से UI बनाने के लिए उपयुक्त हैं

production में लागू करने पर trade-offs

• production codebase ऐसा environment होता है जिसमें existing tokens और component libraries, strict lint rules और type checks लागू होते हैं; यह scratch से बनाने वाले isolated environment से काफी अलग है
• user login screen जैसे simple task में DESIGN.md को एकमात्र design guide के रूप में इस्तेमाल करने पर लगभग 92% अधिक tokens खर्च हुए, generation time ज्यादा लगा, और runs के बीच token consumption में लगभग 2.7 गुना variation दर्ज हुआ
  • हालांकि यह स्पष्ट किया गया कि ये results निर्णायक नहीं हैं और model, prompt, design system, environment और context quality के हिसाब से बदल सकते हैं

• सीमा 1 - context on-demand नहीं, एक साथ दिया जाता है

  • MCP server ads_plan जैसे tool call के जरिए किसी specific component के लिए instructions on-demand लाता है
  • सैकड़ों icons और विशाल semantic design tokens जैसे भारी हिस्सों में अनावश्यक items load होने से बचाता है
  • DESIGN.md हर बार पूरा load करता है, जिससे शुरुआत से ही high cost और slow response आते हैं; कम turns में context truncation होने से accuracy घट सकती है

• सीमा 2 - फ़ाइल छोटी रखने पर context loss होता है

  • design system हजारों views, Figma files और frontend components की shared language को compress करने वाला complex object है
  • on-demand MCP और skills इसे लगभग 2.5 MB instructions में distill करते हैं; DESIGN.md एक साथ load होता है, इसलिए इसे और अधिक छोटा करना पड़ता है
  • final file 80 KB, लगभग 19,800 LLM tokens (frontmatter छोड़कर लगभग 10,700) की रही, जो community examples की तुलना में बड़ी है
  • इस size में फिट करने के लिए 50 से अधिक components की usage guidance का बड़ा हिस्सा हटाया गया, foundational guidance बहुत घटाई गई, और low-usage design tokens में से कुछ हटाए गए
  • context missing होने के कारण production quality लक्ष्य रखने वाले agents की accuracy कम होती दिखी, या वे खुद context collect करने और specs में न दिए गए usage instructions खोजने के लिए component implementations सीधे पढ़ने लगे

• सीमा 3 - specification design system के internals expose करती है

  • DESIGN.md design system का prose में rewrite किया गया portable snapshot है, जिसका उद्देश्य system को शुरू से replicate implement करने के लिए principles, specs और guidance देना है
  • स्थापित production environment में यह information गैर-ज़रूरी हो सकती है या agent को tech debt बनाने की ओर ले जा सकती है, खासकर components में
  • button styling की पूरी details (backgroundColor, textColor, borderColor आदि) पढ़कर interpret करने के बजाय existing component import कर इस्तेमाल करना बेहतर है
    • उदाहरण: import Button from '@atlaskit/button'; के बाद <Button appearance="primary" spacing="compact" />
  • shared components का इस्तेमाल maintainability के लिए जरूरी है; button को एक जगह बदलने पर वह पूरे codebase में reflect होता है और code review व maintenance आसान होते हैं
  • DESIGN.md जानबूझकर code guidance को बाहर रखता है और केवल reimplementation specs देता है, इसलिए tests में existing system इस्तेमाल करने के बजाय components को फिर से बनाने की tendency अधिक दिखी
  • MCP server और skills technical foundation के आधार पर बेहतर abstraction level देते हैं; वे reimplementation guide नहीं, बल्कि existing system की usage manual की तरह काम करते हैं
  • इसे token consumption के बिना coding standards enforce करने वाले lint rules के साथ मिलाकर agents के लिए positive feedback loop बनता है

DESIGN.md सबसे उपयोगी कहाँ है

• high-level artistic direction

  • सबसे simple DESIGN.md system की visual direction और feel पर focus करता है; अगर इसे document नहीं किया गया है तो यह उपयोगी output हो सकता है
  • लेकिन frontmatter वही चीज़ें duplicate करता है जो codebase में पहले से मौजूद हैं

• अपरिचित environments में तेज़ prototyping

  • blue-sky prototyping या नए tools test करते समय, पूरी technical stack setup किए बिना या existing component constraints का बोझ लिए बिना on-brand UI generation में मदद करता है

• design tools के साथ interoperability

  • कुछ AI tools design language के अनुरूप prebuilt components को customize करके UI assemble करते हैं; DESIGN.md ऐसे tools के लिए उपयुक्त level की guidance देता है

• adaptive UI के लिए customer theming

  • reports, charts, dashboards जैसे dynamic interfaces generate करने वाले products में customers को अपना brand आसानी से describe करने में मदद करता है, ताकि AI output customer brand जैसा महसूस हो
  • इसे admins या brand teams द्वारा work tools में upload किए जाने वाले option के रूप में सोचा जा सकता है
• इन सबमें common scope है: agent-generated UI ऐसे environments में, जहाँ existing design system output उपलब्ध नहीं है या practical नहीं है

शुरू करना और standard में योगदान

• Atlassian standard पर सिर्फ react करने के बजाय उसे shape करना चाहता है, इसलिए उसने अपनी DESIGN.md file atlassian.design/DESIGN.md पर publish की
• उनकी file में current standard से कुछ differences हैं, component rendering के लिए non-standard properties शामिल हैं, और standard theming support नहीं करता इसलिए अलग dark mode variant दिया गया है
• GitHub पर feedback share किया गया, कुछ suggestions पहले ही specification में शामिल हो चुके हैं, और पूरे industry को भागीदारी के लिए प्रोत्साहित किया गया है

निष्कर्ष

• DESIGN.md design system के snapshot के रूप में उपयोगी portable format है, लेकिन richer design system tools का replacement नहीं है
• अगर agents MCP या skills support करते हैं, तो वे कम cost में बेहतर results देते हैं
• cross-platform portability, customer theming और blue-sky prototyping में well-structured DESIGN.md meaningful improvement देता है
• जब design systems AI के लिए readable बनते हैं, तो पूरा ecosystem लाभ पाता है