DESIGN.md — Định dạng tệp đơn cho design system dành cho công cụ lập trình AI (bản tổng hợp bằng 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ẻ spec và nghĩ rằng chỉ mình xem thì thật phí, vì vậy tôi đã diễn giải lại bằng tiếng Hàn theo dạng một curriculum gồm 28 chương. Tôi làm nó với cảm giác muốn để những người cũng đang tìm hiểu cùng chủ đề này không phải lục lại spec tiếng Anh ngay từ đầu, và để những ai đang có cùng câu hỏi như tôi là “làm sao để AI đọc được design system” có thể xem qua toàn bộ trong một lần.

DESIGN.md là một định dạng nhằm biểu diễn design system trong chỉ một tệp Markdown. 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 bên dưới trong phần Markdown sẽ ghi lại các tiêu chí đánh giá 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”, hay “nên tránh mẫu nào”. Nói cách khác, nó không chỉ là một style guide đơn thuần mà gần với “tệp nguồn gốc của design system” để các AI coding agent như Claude Code, Cursor, Codex tham chiếu lặp đi lặp lại.

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

• Câu hỏi trước đây: “Làm sao sắp xếp design system cho tốt trong Figma”
• Câu hỏi hiện tại: “Làm sao để công cụ lập trình AI đọc design system của chúng ta”, “Cần gì để AI khi tạo trang mới sẽ tuân theo màu sắc, khoảng cách và quy tắc component của thương hiệu”
• Sự thay đổi khi gắn với các luồng như Claude Design, Claude Code, Figma MCP: design system 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 spec)

• Cấu trúc kép YAML (cho máy) + Markdown (cho người và AI) — token được máy parse, còn phần nội dung là lớp để con người lưu lại căn cứ ra quyết định
• Token là đáp án, phần nội dung là lý do — cách xác định sẵn thứ tự ưu tiên để biết nên tin bên nào khi hai bên lệch nhau rất gọn gàng
• Thứ tự 8 section được cố định — các section như colors, typography, spacing, components tự chúng đóng vai trò mental model của design system
• lint / diff / export / spec CLI — tự động kiểm tra các mục như tham chiếu 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 thông với DTCG, Tailwind, biến Figma được nêu rõ riêng

Cấu trúc curriculum (28 chương, 7 module)

• 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, thứ tự ưu tiên giữa token và phần nội dung
• 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, quan hệ với DTCG và Tailwind
• Tổng kết cuối · 1 chương — tóm tắt 27 chương + 10 nguyên tắc có thể mang vào thực tế

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

• Càng nhiều UI được AI tạo ra, tôi càng có cảm giác design system sẽ trở nên quan trọng hơn. Vấn đề dường như đang chuyển từ “AI có giỏi thiết kế hay không” sang “đội ngũ đã để lại tiêu chí 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 tiêu chí đó 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 được 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 làm design system, 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ần nào cũng khác nhau”. Nếu có phần nào tôi hiểu hoặc tổng hợp sai, xin hãy cho biết trong 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.