Atlassian công bố DESIGN.md - Bài học rút ra từ việc thử nghiệm thực tế ngữ cảnh thiết kế có thể di chuyển

• Đây là một định dạng Markdown có thể di chuyển nhằm giải quyết vấn đề "slop" khi AI tạo UI theo kiểu chung chung, thiếu bản sắc thương hiệu; cách làm là gom các yếu tố cốt lõi của hệ thống thiết kế vào một tệp và đưa vào prompt
• DESIGN.md gồm hai phần: design token để máy đọc và cơ sở lý giải thiết kế (rationale) để con người và agent đọc, chứa ý đồ (intent) chứ không phải toàn bộ đặc tả kỹ thuật của hệ thống
• Khi áp dụng trong demo keynote Team '26 để tạo dashboard bằng Figma Make, màu sắc, khoảng cách, hình khối và typography được căn chỉnh theo hệ thống của Atlassian, cho hiệu quả tốt trong các nguyên mẫu one-shot
• Tuy nhiên trong codebase production, so với MCP server·skills nội bộ, mức tiêu thụ token tăng thêm khoảng 92%, thời gian sinh lâu hơn, và độ dao động token giữa các lần chạy tăng khoảng 2,7 lần, làm giảm hiệu quả
• Thế mạnh riêng là tính di động và sự gọn nhẹ vẫn có giá trị trong di chuyển đa nền tảng, theming cho khách hàng, tạo nguyên mẫu ở môi trường mới, và nó phù hợp vai trò công cụ bổ trợ chứ không thay thế bộ công cụ hệ thống thiết kế phong phú

---

Bối cảnh - vấn đề "slop" của AI UI

• Khi AI tạo UI, kết quả thường có xu hướng giống nhau như nút gradient, tiêu đề viết hoa, bố cục thẻ phổ biến, animation hover không cần thiết; chức năng thì chạy nhưng thiếu bản sắc thị giác
• Cộng đồng thiết kế gọi các kết quả như vậy là "slop", tức đầu ra có chức năng nhưng không có quyết định thiết kế mang chủ đích
• Nguyên nhân là thiếu ngữ cảnh về thương hiệu, component và pattern, nên AI mặc định tạo ra đầu ra theo giá trị trung bình của dữ liệu huấn luyện → "Generic in, generic out"
• Nhóm hệ thống thiết kế của Atlassian đang xây dựng một context engine cho thời đại AI, đồng thời cung cấp ngữ cảnh thiết kế phong phú cho agent thông qua ADS MCP server và các AI skills chi tiết
  • Qua đó họ xác nhận có thể giảm chi phí token AI và nâng cao độ chính xác, chất lượng của các kết quả do hàng nghìn product builder tạo ra

Tổng quan về DESIGN.md

• Đây là định dạng Markdown mã nguồn mở do Google thiết kế cho công cụ thiết kế Stitch, là một ảnh chụp di động chứa thương hiệu và UI pattern của đội ngũ
• Cơ chế hoạt động rất đơn giản: đưa tệp này vào prompt thì kết quả sinh ra bắt đầu trông giống sản phẩm của công ty hơn

• Nó là gì (What it is)

  • Một tệp Markdown di động chỉ mô tả các yếu tố cốt lõi của hệ thống thiết kế
  • Phần đầu liệt kê design token để máy đọc
  • Phần thứ hai mô tả cơ sở lý giải thiết kế như màu sắc, khoảng cách, layout, elevation, component... để con người và agent đọc

• Nó không phải là gì (What it isn't)

  • Không phải toàn bộ đặc tả kỹ thuật hay chi tiết đầy đủ về cách hệ thống thiết kế vận hành trong production
  • Không bao gồm thư viện mã hiện có, linter để duy trì tiêu chuẩn code, hay đặc tả thiết kế chi tiết trong Figma
  • Đặc tả này định nghĩa định dạng như cách nắm bắt ý đồ (intent) thay vì toàn bộ chi tiết của hệ thống

Xây dựng DESIGN.md riêng

• Atlassian vốn đã chuẩn bị hệ thống thiết kế cho AI sử dụng thông qua MCP server, pipeline nội dung có cấu trúc và nhiều agent skills khác nhau
• Họ tạo DESIGN.md riêng từ chính pipeline nội dung có cấu trúc đang dùng để vận hành MCP và agent skills
• Họ thử định dạng này trong các công cụ vibe coding phổ biến và bổ sung chỉ dẫn nghiêm ngặt hơn cho những lỗi thường gặp mà hướng dẫn hiện có chưa đề cập

Thử nghiệm tại Team '26

• Demo keynote Team '26, kết thúc tại Anaheim cách đó một tháng, được dùng làm ca kiểm thử phù hợp
• Trong một demo của keynote, Figma Make dùng Teamwork Graph để tạo dashboard tùy chỉnh, với mục tiêu căn chỉnh ngôn ngữ thiết kế ngay trong một lần mà không phụ thuộc vào MCP server và công cụ nội bộ
• Khi áp dụng DESIGN.md, kết quả chuyển từ kiểu "slop" chung chung sang đầu ra nhận ra được là của Atlassian, như dùng đúng kỳ vọng về màu sắc, khoảng cách, hình khối, typography và áp dụng elevation đồng bộ hệ thống cho component
• Chỉ dẫn và đặc tả ở mức cao trong tệp phù hợp để tùy biến các thư viện phổ biến như Tailwind, Shadcn và tạo UI từ đầu

Đánh đổi khi áp dụng vào production

• Codebase production rất khác với môi trường cô lập nơi mọi thứ được xây từ đầu, vì ở đây đã có token và thư viện component sẵn có, cùng các quy tắc lint nghiêm ngặt và kiểm tra kiểu
• Với các tác vụ đơn giản như màn hình đăng nhập người dùng, nếu dùng DESIGN.md làm hướng dẫn thiết kế duy nhất thì ghi nhận mức tiêu thụ token tăng khoảng 92%, thời gian sinh lâu hơn, và độ dao động token giữa các lần chạy tăng khoảng 2,7 lần
  • Tuy nhiên họ cũng nói rõ kết quả này không mang tính kết luận tuyệt đối, vì còn tùy theo model, prompt, hệ thống thiết kế, môi trường và chất lượng ngữ cảnh

• Giới hạn 1 - ngữ cảnh không được cung cấp theo nhu cầu mà đưa vào một lần

  • MCP server dùng tool call như ads_plan để chỉ lấy hướng dẫn cho component cần thiết theo nhu cầu
  • Điều này tránh phải nạp các phần nặng như hàng trăm icon hay khối lượng lớn semantic design token không cần thiết
  • Trong khi đó, DESIGN.md phải tải toàn bộ mỗi lần, nên chi phí ban đầu cao hơn, phản hồi chậm hơn và dễ bị cắt ngữ cảnh trong các phiên ít lượt, từ đó có thể làm giảm độ chính xác

• Giới hạn 2 - giữ tệp ngắn sẽ làm mất ngữ cảnh

  • Hệ thống thiết kế là một đối tượng phức tạp, nén lại ngôn ngữ dùng chung của hàng nghìn view, tệp Figma và component frontend
  • MCP và skills theo nhu cầu được chưng cất thành khoảng 2.5 MB hướng dẫn, còn DESIGN.md phải nạp một lần nên cần rút gọn nhiều hơn nữa
  • Tệp kết quả có kích thước 80 KB, khoảng 19.800 token LLM, hoặc khoảng 10.700 nếu không tính frontmatter, lớn hơn nhiều ví dụ trong cộng đồng
  • Để đạt kích thước đó, họ đã phải loại bỏ phần lớn hướng dẫn sử dụng của hơn 50 component, cắt giảm mạnh chỉ dẫn nền tảng và xóa một số design token ít dùng
  • Khi thiếu ngữ cảnh, họ quan sát thấy các agent nhắm tới chất lượng production dễ giảm độ chính xác hoặc tự đi thu thập ngữ cảnh, thậm chí đọc trực tiếp phần triển khai component để tìm hướng dẫn sử dụng không có trong đặc tả

• Giới hạn 3 - đặc tả làm lộ phần nội bộ của hệ thống thiết kế

  • DESIGN.md là một ảnh chụp di động được viết lại bằng văn xuôi của hệ thống thiết kế, nhằm cung cấp nguyên tắc, đặc tả và hướng dẫn để tái hiện hệ thống từ đầu
  • Trong môi trường production đã ổn định, thông tin này có thể không cần thiết hoặc khiến agent tạo ra nợ kỹ thuật (tech debt), đặc biệt rõ ở component
  • Thay vì đọc và diễn giải mọi chi tiết tạo kiểu của nút như backgroundColor, textColor, borderColor..., cách tốt hơn là import component sẵn có và dùng lại
    • Ví dụ: import Button from '@atlaskit/button'; rồi dùng <Button appearance="primary" spacing="compact" />
  • Việc dùng component dùng chung là điều thiết yếu cho bảo trì; thay đổi nút ở một nơi sẽ phản ánh trên toàn codebase và giúp code review, bảo trì dễ hơn
  • Vì DESIGN.md cố ý loại trừ chỉ dẫn về code và chỉ cung cấp đặc tả tái triển khai, nên trong thử nghiệm nó có xu hướng khiến agent tái tạo component nhiều hơn thay vì dùng hệ thống sẵn có
  • MCP server và skills, dựa trên nền tảng kỹ thuật, mang lại mức trừu tượng phù hợp hơn, đóng vai trò như hướng dẫn sử dụng hệ thống hiện có thay vì chỉ dẫn tái triển khai
  • Khi kết hợp với quy tắc lint để áp chuẩn code mà không tốn token, điều này tạo nên vòng phản hồi tích cực cho agent

Khi nào DESIGN.md hữu ích nhất

• Định hướng nghệ thuật cấp cao (High-level artistic direction)

  • Phiên bản DESIGN.md đơn giản nhất tập trung vào định hướng thị giác và cảm giác của hệ thống, và nếu doanh nghiệp chưa tài liệu hóa phần này thì đây là đầu ra hữu ích
  • Tuy nhiên frontmatter lại trùng lặp với nội dung đã có sẵn trong codebase

• Tạo nguyên mẫu nhanh trong môi trường chưa quen thuộc

  • Với blue-sky prototyping hoặc thử công cụ mới, nó giúp tạo UI đúng thương hiệu mà không phải gánh chi phí cấu hình toàn bộ tech stack hay ràng buộc của component hiện có

• Khả năng tương tác với công cụ thiết kế (Interoperability)

  • Một số công cụ AI lắp ráp UI bằng cách tùy biến các component dựng sẵn để phù hợp ngôn ngữ thiết kế, và DESIGN.md cung cấp đúng mức chỉ dẫn phù hợp cho các công cụ đó

• Theming cho khách hàng phục vụ UI thích ứng (Customer theming)

  • Với những sản phẩm cần tạo giao diện động như report, chart, dashboard, nó giúp khách hàng dễ mô tả thương hiệu của mình để đầu ra AI mang cảm giác đúng với thương hiệu đó
  • Có thể hình dung như một tùy chọn để admin hoặc đội thương hiệu tải lên trong các công cụ làm việc
• Điểm chung của các trường hợp này là UI do agent tạo ra trong những môi trường mà đầu ra từ hệ thống thiết kế hiện có không dùng được hoặc không thực tế

Bắt đầu và đóng góp cho tiêu chuẩn

• Atlassian công khai tệp DESIGN.md của mình tại atlassian.design/DESIGN.md với mục tiêu không chỉ phản ứng mà còn góp phần định hình tiêu chuẩn
• Tệp của họ hiện khác tiêu chuẩn ở một số điểm, có cả thuộc tính phi chuẩn phục vụ render component, và vì tiêu chuẩn chưa hỗ trợ theming nên họ cung cấp biến thể dark mode riêng
• Họ đã chia sẻ phản hồi trên GitHub, một số đề xuất đã được phản ánh vào đặc tả, và khuyến khích toàn ngành cùng tham gia

Kết luận

• DESIGN.md là một định dạng di động hữu ích như ảnh chụp của hệ thống thiết kế, nhưng không phải vật thay thế cho các công cụ hệ thống thiết kế phong phú hơn
• Nếu agent hỗ trợ MCP hoặc skills thì có thể cho kết quả tốt hơn với chi phí thấp hơn
• Trong các tình huống như di chuyển đa nền tảng, theming cho khách hàng hay blue-sky prototyping, một DESIGN.md được cấu trúc tốt có thể mang lại cải thiện đáng kể
• Khi hệ thống thiết kế trở nên có thể đọc được với AI, toàn bộ hệ sinh thái đều được hưởng lợi