Atlassian เปิดเผย DESIGN.md - บทเรียนจากการทดสอบบริบทการออกแบบแบบพกพาในงานจริง

• เป็นฟอร์แมต Markdown แบบพกพาเพื่อแก้ปัญหา "slop" ของ UI ที่ AI สร้างซึ่งมักกลายเป็นงานโหลไร้อัตลักษณ์แบรนด์ โดยบรรจุองค์ประกอบหลักของดีไซน์ซิสเต็มไว้ในไฟล์เดียวแล้วแนบเข้าไปในพรอมป์ต์
• DESIGN.md ประกอบด้วย 2 ส่วนคือ ดีไซน์โทเค็น ที่เครื่องอ่านได้ และ เหตุผลเชิงออกแบบ (rationale) ที่คนและเอเจนต์อ่านได้ โดยเก็บ เจตนา (intent) ไม่ใช่สเปกทางเทคนิคทั้งหมดของระบบ
• เมื่อนำไปใช้กับการสร้างแดชบอร์ด Figma Make ในเดโมคีย์โน้ต Team '26 พบว่าสี ระยะห่าง รูปทรง และตัวอักษรจัดแนวเข้ากับระบบของ Atlassian ได้ และให้ผลดีพอสมควรในการสร้างต้นแบบแบบครั้งเดียวจบ
• อย่างไรก็ตาม ในโค้ดเบสสำหรับโปรดักชันเมื่อเทียบกับ MCP server·skills ภายในของตนเอง กลับใช้โทเค็นเพิ่มราว 92% ใช้เวลาสร้างนานขึ้น และปริมาณโทเค็นที่ใช้ระหว่างรันผันผวนราว 2.7 เท่า ทำให้ประสิทธิภาพลดลง
• จุดแข็งเฉพาะตัวด้านความพกพาและความกระชับยังมีคุณค่าสำหรับ การย้ายข้ามแพลตฟอร์ม การทำธีมให้ลูกค้า และการทำต้นแบบในสภาพแวดล้อมใหม่ โดยวางตำแหน่งเป็นส่วนเสริมมากกว่าตัวแทนของเครื่องมือดีไซน์ซิสเต็มแบบเต็มรูปแบบ

---

ภูมิหลัง - ปัญหา "slop" ของ AI UI

• เมื่อ AI สร้าง UI ผลลัพธ์มักมีแนวโน้มคล้ายกัน เช่น ปุ่มไล่เฉด หัวข้อพิมพ์ใหญ่ เลย์เอาต์การ์ดแบบทั่วไป หรือแอนิเมชันโฮเวอร์ที่ไม่จำเป็น ฟังก์ชันอาจใช้งานได้แต่ขาดอัตลักษณ์ทางภาพ
• ชุมชนด้านดีไซน์เรียกผลลัพธ์ลักษณะนี้ว่า "slop" คือเอาต์พุตที่ใช้งานได้แต่ไม่มีการตัดสินใจด้านการออกแบบอย่างมีเจตนา
• สาเหตุคือการขาดบริบทเกี่ยวกับแบรนด์ คอมโพเนนต์ และแพตเทิร์น ทำให้ AI ยึดค่ากลางจากข้อมูลฝึกเป็นค่าเริ่มต้น → "Generic in, generic out"
• ทีมดีไซน์ซิสเต็มของ Atlassian กำลังสร้าง context engine สำหรับยุค AI และมอบบริบทด้านดีไซน์ที่สมบูรณ์ให้เอเจนต์ผ่าน ADS MCP server และ AI skills แบบละเอียด
  • จากสิ่งนี้พบว่าสามารถลดค่าใช้จ่ายโทเค็นของ AI และเพิ่มความแม่นยำกับคุณภาพของผลลัพธ์ที่ผู้สร้างผลิตภัณฑ์หลายพันคนสร้างขึ้นได้

ภาพรวมของ DESIGN.md

• เป็นฟอร์แมต Markdown โอเพนซอร์สที่ Google ออกแบบสำหรับเครื่องมือดีไซน์ Stitch ของตน เป็นสแนปช็อตแบบพกพาที่บรรจุแบรนด์และแพตเทิร์น UI ของทีม
• หลักการทำงานเรียบง่าย เพียงใส่ไฟล์นี้ลงในพรอมป์ต์ ผลลัพธ์ที่สร้างก็จะเริ่มดูเหมือนเป็นผลิตภัณฑ์ขององค์กรนั้น

• คืออะไร (What it is)

  • เป็นไฟล์ Markdown แบบพกพาที่อธิบายเฉพาะองค์ประกอบหลักของดีไซน์ซิสเต็ม
  • ส่วนแรกแสดง ดีไซน์โทเค็น สำหรับให้เครื่องอ่าน
  • ส่วนที่สองอธิบาย เหตุผลเชิงออกแบบ เช่น สี ระยะห่าง เลย์เอาต์ elevation และคอมโพเนนต์ สำหรับให้คนและเอเจนต์อ่าน

• ไม่ใช่อะไร (What it isn't)

  • ไม่ใช่สเปกทางเทคนิคทั้งหมดหรือรายละเอียดครบถ้วนของระบบที่ใช้ให้ดีไซน์ซิสเต็มทำงานในโปรดักชัน
  • ไม่ได้รวมไลบรารีโค้ดเดิม, linter สำหรับคงมาตรฐานการเขียนโค้ด, หรือสเปกดีไซน์แบบละเอียดใน Figma
  • สเปกระบุว่าฟอร์แมตนี้มีไว้เพื่อจับ เจตนา (intent) ไม่ใช่รายละเอียดทั้งหมดของระบบ

การสร้าง DESIGN.md ของตนเอง

• Atlassian เตรียมดีไซน์ซิสเต็มของตนให้พร้อมสำหรับการใช้งานโดย AI มาระยะหนึ่งแล้ว ผ่าน MCP server, ไปป์ไลน์คอนเทนต์แบบมีโครงสร้าง และ agent skills หลากหลายแบบ
• Atlassian สร้าง DESIGN.md ของตนจาก ไปป์ไลน์คอนเทนต์แบบมีโครงสร้าง เดียวกับที่ใช้ขับเคลื่อน MCP และ agent skills
• นำฟอร์แมตนี้ไปทดสอบกับเครื่องมือ vibe coding ทั่วไป และเพิ่มคำแนะนำที่เข้มงวดขึ้นสำหรับข้อผิดพลาดที่พบบ่อยซึ่งไม่มีอยู่ในคู่มือเดิม

การทดสอบใน Team '26

• เดโมคีย์โน้ต Team '26 ที่เพิ่งจบลงใน Anaheim เมื่อเดือนก่อนถูกใช้เป็นกรณีทดสอบที่เหมาะสม
• ในเดโมหนึ่งของคีย์โน้ต Figma Make ใช้ Teamwork Graph เพื่อสร้างแดชบอร์ดแบบกำหนดเอง โดยตั้งเป้าให้สอดคล้องกับภาษาการออกแบบได้ในครั้งเดียวโดยไม่พึ่ง MCP server หรือเครื่องมือภายใน
• เมื่อนำ DESIGN.md มาใช้ ผลลัพธ์เปลี่ยนจาก "slop" ทั่วไปเป็นงานที่ดูเป็น Atlassian อย่างชัดเจน โดยใช้ค่าสี ระยะห่าง รูปทรง และตัวอักษรตามที่คาดหวัง และใช้ elevation ของคอมโพเนนต์ให้สอดคล้องกับระบบ
• คำแนะนำและสเปกระดับสูงในไฟล์เหมาะสำหรับการคัสตอมไลบรารีทั่วไปอย่าง Tailwind และ Shadcn เพื่อสร้าง UI ตั้งแต่ต้น

trade-off เมื่อนำไปใช้ในโปรดักชัน

• โค้ดเบสสำหรับโปรดักชันต่างจากสภาพแวดล้อมแยกที่สร้างทุกอย่างตั้งแต่ต้นอย่างมาก เพราะมีทั้งโทเค็นและไลบรารีคอมโพเนนต์เดิม รวมถึงกฎ lint และการตรวจ type ที่เข้มงวด
• ในงานง่าย ๆ อย่างหน้าล็อกอิน หากใช้ DESIGN.md เป็นคู่มือดีไซน์เพียงอย่างเดียว พบว่าใช้โทเค็นเพิ่มราว 92% ใช้เวลาสร้างนานขึ้น และปริมาณโทเค็นที่ใช้ระหว่างรันผันผวนราว 2.7 เท่า
  • อย่างไรก็ตามมีการระบุชัดว่าผลลัพธ์นี้ยังไม่เด็ดขาด และอาจเปลี่ยนไปตามโมเดล พรอมป์ต์ ดีไซน์ซิสเต็ม สภาพแวดล้อม และคุณภาพของบริบท

• ข้อจำกัด 1 - บริบทถูกส่งมาทีเดียว ไม่ใช่ on-demand

  • MCP server จะดึงคำแนะนำเฉพาะคอมโพเนนต์ตามต้องการผ่าน tool call อย่าง ads_plan
  • ช่วยหลีกเลี่ยงการโหลดส่วนที่หนักโดยไม่จำเป็น เช่น ไอคอนหลายร้อยรายการหรือดีไซน์โทเค็นเชิงความหมายจำนวนมาก
  • แต่ DESIGN.md ต้องโหลดทั้งหมดทุกครั้ง จึงมีต้นทุนสูงและตอบสนองช้าตั้งแต่เริ่ม อีกทั้งในรอบสนทนาที่สั้นอาจเกิดการตัดทอนบริบทจนความแม่นยำลดลง

• ข้อจำกัด 2 - ถ้าทำไฟล์ให้สั้น บริบทจะหายไป

  • ดีไซน์ซิสเต็มเป็นสิ่งซับซ้อนที่อัดแน่นภาษาร่วมของวิวหลายพันแบบ ไฟล์ Figma และคอมโพเนนต์ฟรอนต์เอนด์
  • MCP และ skills แบบ on-demand ถูกกลั่นเป็นคำแนะนำขนาดราว 2.5 MB ขณะที่ DESIGN.md ต้องโหลดทีเดียวจึงจำเป็นต้องย่อมากกว่านั้นมาก
  • ไฟล์ที่ได้มีขนาด 80 KB หรือประมาณ 19,800 LLM tokens (หากไม่รวม frontmatter ราว 10,700) ซึ่งถือว่าใหญ่เมื่อเทียบกับตัวอย่างในชุมชน
  • เพื่อให้ได้ขนาดนี้ ต้องตัดคำแนะนำการใช้งานส่วนใหญ่ของคอมโพเนนต์กว่า 50 รายการ ย่อคำแนะนำพื้นฐานลงมาก และลบดีไซน์โทเค็นที่ใช้น้อยบางส่วนออก
  • เมื่อบริบทขาดหาย เอเจนต์ที่มุ่งหวังคุณภาพระดับโปรดักชันจึงมีแนวโน้มแม่นยำน้อยลง หรือพยายามรวบรวมบริบทเอง เช่น อ่าน implementation ของคอมโพเนนต์โดยตรงเพื่อหาคำแนะนำการใช้งานที่ไม่มีในสเปก

• ข้อจำกัด 3 - สเปกเปิดเผยภายในของดีไซน์ซิสเต็ม

  • DESIGN.md เป็นสแนปช็อตแบบพกพาที่เขียนดีไซน์ซิสเต็มใหม่ในรูปแบบร้อยแก้ว มีจุดประสงค์เพื่อให้หลักการ สเปก และแนวทางสำหรับการทำซ้ำระบบตั้งแต่ต้น
  • ในสภาพแวดล้อมโปรดักชันที่ตั้งมั่นแล้ว ข้อมูลนี้อาจไม่จำเป็นหรืออาจชักนำเอเจนต์ไปสู่การสร้าง หนี้เทคนิค (tech debt) โดยเฉพาะในส่วนคอมโพเนนต์
  • แทนที่จะอ่านและตีความรายละเอียดทั้งหมดของการจัดสไตล์ปุ่ม เช่น backgroundColor, textColor, borderColor การ import คอมโพเนนต์ที่มีอยู่แล้วมาใช้จะเหมาะสมกว่า
    • ตัวอย่าง: import Button from '@atlaskit/button'; แล้วใช้ <Button appearance="primary" spacing="compact" />
  • การใช้คอมโพเนนต์ร่วมกันเป็นสิ่งจำเป็นต่อการบำรุงรักษา เพราะหากเปลี่ยนปุ่มในที่เดียวก็สะท้อนทั้งโค้ดเบส และช่วยให้ code review กับการดูแลง่ายขึ้น
  • DESIGN.md ตั้งใจไม่รวมคำแนะนำด้านโค้ดและให้เพียงสเปกสำหรับการนำไปทำใหม่ จึงพบว่าในการทดสอบมีแนวโน้มจะสร้างคอมโพเนนต์ขึ้นใหม่มากกว่าการใช้ระบบเดิม
  • MCP server และ skills มอบระดับนามธรรมที่ดีกว่าโดยยึดโยงกับฐานเทคนิคจริง ทำหน้าที่เป็นคู่มือการใช้ระบบที่มีอยู่มากกว่าคู่มือสร้างใหม่
  • เมื่อนำสิ่งนี้ไปรวมกับ กฎ lint ที่บังคับมาตรฐานการเขียนโค้ดได้โดยไม่ใช้โทเค็น ก็จะเกิดวงจรป้อนกลับเชิงบวกสำหรับเอเจนต์

กรณีที่ DESIGN.md มีประโยชน์ที่สุด

• ทิศทางศิลปะระดับสูง (High-level artistic direction)

  • DESIGN.md แบบง่ายที่สุดมุ่งเน้นทิศทางภาพและความรู้สึกของระบบ ซึ่งหากยังไม่เคยบันทึกไว้ ก็ถือเป็นผลลัพธ์ที่มีประโยชน์
  • แต่ frontmatter นั้นซ้ำกับสิ่งที่มีอยู่ในโค้ดเบสแล้ว

• การทำต้นแบบอย่างรวดเร็วในสภาพแวดล้อมที่ไม่คุ้นเคย

  • สำหรับการทำต้นแบบแบบ blue-sky หรือทดสอบเครื่องมือใหม่ ช่วยสร้าง UI ที่ยังคงแบรนด์ได้โดยไม่ต้องแบกรับภาระการตั้งค่าเทคสแตกทั้งหมดหรือข้อจำกัดของคอมโพเนนต์เดิม

• การทำงานร่วมกับเครื่องมือออกแบบ (Interoperability)

  • เครื่องมือ AI บางตัวประกอบ UI โดยคัสตอมคอมโพเนนต์สำเร็จรูปให้เข้ากับภาษาการออกแบบ ซึ่ง DESIGN.md ให้คำแนะนำในระดับที่เหมาะกับเครื่องมือประเภทนี้

• การทำธีมให้ลูกค้าเพื่อ UI แบบปรับตัวได้ (Customer theming)

  • ในผลิตภัณฑ์ที่ต้องสร้างอินเทอร์เฟซแบบไดนามิก เช่น รายงาน แผนภูมิ หรือแดชบอร์ด ช่วยให้ลูกค้าอธิบายแบรนด์ของตนได้ง่ายขึ้น และทำให้ผลลัพธ์จาก AI ดูเหมือนแบรนด์ของลูกค้า
  • สามารถจินตนาการเป็นตัวเลือกให้แอดมินหรือทีมแบรนด์อัปโหลดเข้ากับเครื่องมือทำงานได้
• สิ่งที่เหมือนกันของกรณีเหล่านี้คือเป็นงานสร้าง UI โดยเอเจนต์ในสภาพแวดล้อมที่ผลลัพธ์จากดีไซน์ซิสเต็มเดิมใช้ไม่ได้หรือไม่สะดวกในทางปฏิบัติ

การเริ่มต้นและการมีส่วนร่วมกับมาตรฐาน

• Atlassian เปิดเผยไฟล์ DESIGN.md ของตนที่ atlassian.design/DESIGN.md เพราะต้องการมีส่วนกำหนดมาตรฐาน ไม่ใช่เพียงตอบสนองต่อมัน
• ไฟล์ของบริษัทมีบางส่วนต่างจากมาตรฐานปัจจุบัน มีพร็อพเพอร์ตีที่ไม่เป็นมาตรฐานสำหรับการเรนเดอร์คอมโพเนนต์ และเนื่องจากมาตรฐานยังไม่รองรับการทำธีม จึงมีเวอร์ชัน dark mode แยกต่างหาก
• บริษัทได้แชร์ฟีดแบ็กบน GitHub และข้อเสนอบางส่วนก็ถูกสะท้อนเข้าสู่สเปกแล้ว พร้อมสนับสนุนให้ทั้งอุตสาหกรรมเข้าร่วม

บทสรุป

• DESIGN.md เป็นฟอร์แมตแบบพกพาที่มีประโยชน์ในฐานะสแนปช็อตของดีไซน์ซิสเต็ม แต่ไม่ใช่สิ่งทดแทนเครื่องมือดีไซน์ซิสเต็มที่สมบูรณ์กว่า
• หากเอเจนต์รองรับ MCP หรือ skills ก็จะให้ผลลัพธ์ที่ดีกว่าในต้นทุนที่ต่ำกว่า
• สำหรับการย้ายข้ามแพลตฟอร์ม การทำธีมให้ลูกค้า และการทำต้นแบบแบบ blue-sky นั้น DESIGN.md ที่มีโครงสร้างดีสามารถยกระดับผลลัพธ์ได้อย่างมีนัยสำคัญ
• เมื่อดีไซน์ซิสเต็มถูกทำให้อ่านได้โดย AI ระบบนิเวศทั้งหมดก็จะได้รับประโยชน์