DESIGN.md — Định dạng tệp đơn cho hệ thống thiết kế dành cho công cụ lập trình AI (bản tổng hợp tiếng Hàn)

Tôi thấy định dạng DESIGN.md do Google Labs đề xuất trong dự án Stitch rất thú vị, nên đã dành vài ngày để mổ xẻ đặc tả và thấy tiếc nếu chỉ xem một mình rồi thôi, vì vậy tôi đã diễn giải lại bằng tiếng Hàn dưới dạng một curriculum gồm 28 chương. Tôi làm nội dung này với cảm giác muốn để những người đang học cùng chủ đề không cần phải lục tìm đặc tả tiếng Anh ngay từ đầu, và để những ai cũng có câu hỏi như tôi là “làm thế nào để AI đọc được hệ thống thiết kế” có thể xem lướt toàn bộ trong một lần.

DESIGN.md là một định dạng nhằm biểu diễn hệ thống thiết kế trong một tệp Markdown duy nhất. Các giá trị như màu sắc, typography, spacing, radius, component token được đặt trong YAML frontmatter ở dạng máy có thể đọc được, còn phần Markdown bên dưới ghi lại các tiêu chí ra quyết định thiết kế như “vì sao dùng màu này”, “kiểu nút này được dùng trong tình huống nào”, “nên tránh những pattern nào”. Nói cách khác, đây không chỉ là một style guide đơn thuần mà gần với “tệp gốc của hệ thống thiết kế” để các AI coding agent như Claude Code, Cursor, Codex tham chiếu mỗi lần làm việc.

Bối cảnh — những thay đổi tôi nhìn lại khi tổng hợp

• Câu hỏi trước đây: “làm sao sắp xếp hệ thống thiết kế thật tốt trong Figma”
• Câu hỏi hiện tại: “làm thế nào để công cụ lập trình AI đọc được hệ thống thiết kế của chúng ta”, “cần gì để AI khi tạo trang mới vẫn tuân theo màu sắc, khoảng cách, quy tắc component của thương hiệu”
• Cùng với các xu hướng như Claude Design, Claude Code, Figma MCP, hệ thống thiết kế không còn chỉ nằm trong Figma mà đi vào codebase, được review trong PR và trở thành “ngữ cảnh liên tục” của AI agent

Điểm cốt lõi của định dạng DESIGN.md (những phần gây ấn tượng khi đọc đặc tả)

• Cấu trúc kép YAML (cho máy) + Markdown (cho người·AI) — token được máy parse, còn phần thân là lớp để con người lưu lại căn cứ phán đoán
• Token là đáp án, phần thân là lý do — việc xác định sẵn thứ tự ưu tiên để biết nên tin bên nào khi hai phần lệch nhau là một điểm rất gọn gàng
• Thứ tự 8 section được cố định — các section như colors, typography, spacing, components tự thân đóng vai trò là mental model của hệ thống thiết kế
• lint / diff / export / spec CLI — tự động kiểm tra các mục như tham chiếu bị hỏng, độ tương phản không đủ, token mồ côi, vi phạm thứ tự section
• Chính sách tương tác liên vận với DTCG, Tailwind, biến của Figma cũng được nêu rõ riêng

Cấu trúc curriculum (28 chương, 7 mô-đun)

• M1 triết lý định dạng · 3 chương — vấn đề mà định dạng này muốn giải quyết, cấu trúc kép, độ ưu tiên giữa token và phần thân
• M2 schema token · 5 chương — toàn bộ schema / màu sắc / độ dài·đơn vị / font / tham chiếu token
• M3 cấu trúc section · 6 chương — thứ tự 8 section và nguyên tắc thiết kế của từng section
• M4 đọc ví dụ thực tế · 3 chương — các case Atmospheric Glass, Paws & Paths, Totality Festival
• M5 CLI · 4 chương — lint, diff, export, spec
• M6 quy tắc lint · 4 chương — 8 mục như broken-ref, contrast, orphaned, section-order
• M7 khả năng mở rộng · 2 chương — chính sách xử lý nội dung chưa biết, mối quan hệ với DTCG·Tailwind
• Tổng kết cuối cùng · 1 chương — tóm tắt 27 chương + 10 nguyên lý có thể mang vào thực tế

Những suy nghĩ khi tổng hợp

• Càng để AI tạo UI nhiều hơn thì hệ thống thiết kế dường như sẽ càng trở nên quan trọng hơn. Vấn đề không còn là “AI có thiết kế giỏi hay không” mà đang chuyển sang “đội ngũ đã để lại các tiêu chuẩn mà AI phải tuân theo rõ ràng đến mức nào”
• DESIGN.md là một nỗ lực thực dụng nhằm đặt những tiêu chuẩn đó vào trong codebase thay vì Notion hay PDF. Điều này cũng có nghĩa là đầu ra của designer trở thành đối tượng review ở cấp độ PR
• Tôi chia sẻ vì nghĩ rằng sẽ hữu ích nếu cùng xem với những ai đang xây dựng hệ thống thiết kế, hoặc từng cảm thấy “vì sao kết quả tạo UI bằng công cụ lập trình AI lúc nào cũng khác nhau”. Nếu có phần nào tôi hiểu và tổng hợp chưa đúng, rất mong mọi người cho biết ở phần bình luận để tôi cập nhật.

[m00nlygreat]

Mình có một thắc mắc: nếu hiểu DESIGN.md là tập chỉ dẫn để tạo ra thiết kế, thì rốt cuộc nó được dùng cho vài trang đầu... hoặc một trang, để tạo mood board. Sau đó chẳng phải sẽ phát sinh sự không khớp giữa code và tệp chỉ dẫn .md, nên phải liên tục đồng bộ hai chiều hay sao?

Cuối cùng thì ở giai đoạn sau, có vẻ nên xem code là source of truth cho thiết kế và tái sử dụng nhất quán các biến hay tên gọi. Nếu không liên tục cập nhật DESIGN.md và quản lý nó như SSoT, thì có phải rốt cuộc vẫn sẽ tiếp tục hardcode token không? Mình muốn biết trong thực tế sử dụng có gặp vấn đề này không.

[neostom432]

DESIGN.md => hướng đi của mã thì khá dễ tự động hóa, nhưng ngược lại, việc các mẫu mới phát sinh trong mã được cập nhật ngược lên DESIGN.md thì không tự động được nên con người phải tự theo dõi. Theo thời gian, trong mã sẽ tích tụ những chỗ hardcode lặt vặt nhưng lại không được phản ánh lên tài liệu, và chuyện đó cứ dồn lại.

Tuy vậy, bản thân triết lý của định dạng này là “tiếp tục vun đắp design system ngay bên trong codebase”, nên tôi nghĩ đây gần với cách vận hành được chủ đích hơn là một nhược điểm. Vì đã kéo những guideline vốn bị “đóng băng” trong Notion hay PDF xuống thành đối tượng review theo từng PR, nên có vẻ đây cũng là một cấu trúc mà trách nhiệm con người định kỳ chỉnh sửa sẽ đi kèm theo. Bên tôi đã thử áp dụng vào dự án, và so với trước khi áp dụng thì tính nhất quán của giao diện thực sự tăng lên rõ rệt; khi cảm nhận được hiệu quả đó, việc review thủ công cũng không còn thấy nặng nề. Cuối cùng, tôi đi đến kết luận rằng đây là vấn đề đội ngũ để lại rõ ràng đến mức nào những tiêu chuẩn mà AI phải tuân theo, và phần duy trì để những tiêu chuẩn ấy luôn “sống” thì vẫn là phần con người đảm nhận.