Tóm tắt nhanh
DESIGN.md là một định dạng văn bản kết hợp design tokens có cấu trúc với phần giải thích bằng Markdown, giúp AI coding agents hiểu đúng nhận diện trực quan của dự án thay vì suy đoán từ prompt ngắn hoặc mã nguồn rời rạc.
Giá trị lớn nhất của DESIGN.md là tạo ra một “nguồn sự thật” bền vững cho design system: màu sắc, typography, spacing, bo góc, component rules và rationale đều nằm trong một file mà cả con người lẫn AI đều đọc được.
Với frontend hiện đại và workflow có Copilot, Cursor, Gemini hoặc agent nội bộ, DESIGN.md giúp giảm lệch giao diện, giảm vòng sửa tay, tăng tính nhất quán xuyên component và giúp AI tạo UI gần đúng ngay từ lần đầu.
DESIGN.md là một format specification dùng để mô tả visual identity cho coding agents. File này cung cấp cho agent một cách hiểu bền vững và có cấu trúc về design system của sản phẩm. Thay vì để AI suy ra phong cách giao diện từ vài ảnh chụp, một prompt ngắn hoặc một số component đã có, DESIGN.md biến các quyết định thiết kế thành dữ liệu chuẩn hóa mà agent có thể đọc, đối chiếu và tái sử dụng trong suốt vòng đời dự án.
Điểm quan trọng nằm ở chỗ DESIGN.md không chỉ là một danh sách token. Nó kết hợp hai lớp: YAML front matter để chứa giá trị máy đọc được và phần Markdown prose để giải thích tại sao các giá trị đó tồn tại, nên áp dụng khi nào, và những nguyên tắc nào cần giữ nguyên. Điều này rất phù hợp với AI coding agents, vì agent không chỉ cần “giá trị đúng”, mà còn cần “ngữ cảnh đúng” để sinh giao diện nhất quán ở nhiều màn hình và nhiều lần chỉnh sửa khác nhau.
Trong dự án phần mềm hiện đại, frontend không còn là công việc chỉ diễn ra trong Figma rồi chuyển tay sang code. Nhiều nhóm đang dùng AI để scaffold trang, refactor component, viết token mapping hoặc generate màn hình mới từ yêu cầu nghiệp vụ. Vấn đề là AI rất dễ tạo ra UI “hợp lý nhưng không đúng thương hiệu”. DESIGN.md giải quyết khoảng trống đó bằng cách cung cấp một chuẩn trung gian giữa design system và AI agent. Tài liệu chuẩn chính thức của Stitch cũng định vị DESIGN.md như một đặc tả dành cho việc mô tả visual identity để agent có thể tiêu thụ một cách nhất quán.
Cấu trúc cốt lõi của file DESIGN.md
Hai lớp bắt buộc trong một file
Theo đặc tả hiện tại, một file DESIGN.md gồm hai phần rõ ràng. Phần đầu là YAML front matter, được đặt trong cặp dấu ---, chứa machine-readable design tokens. Phần sau là Markdown body, nơi bạn viết rationale, nguyên tắc áp dụng và mô tả hệ thống thiết kế. Các token là lớp chuẩn mực để agent bám vào; phần prose đóng vai trò giải thích cách dùng và tinh thần thương hiệu.
Một skeleton tối thiểu có thể bắt đầu như sau:
---
name: Aurora
description: Design system cho dashboard B2B
colors:
primary: "#111827"
secondary: "#6B7280"
accent: "#2563EB"
surface: "#F9FAFB"
typography:
h1:
fontFamily: Inter
fontSize: 2.5rem
fontWeight: 700
body-md:
fontFamily: Inter
fontSize: 1rem
lineHeight: 1.6
rounded:
sm: 6px
md: 10px
spacing:
sm: 8px
md: 16px
components:
button-primary:
backgroundColor: "{colors.accent}"
textColor: "#FFFFFF"
rounded: "{rounded.md}"
padding: 12px
---
## Overview
Thiết kế hướng tới giao diện quản trị hiện đại, trung tính, ưu tiên độ rõ ràng và mật độ thông tin hợp lý.
## Colors
Primary dùng cho tiêu đề và văn bản chính. Accent dùng cho hành động chính và trạng thái tương tác.
## Typography
Inter là font mặc định. Heading đậm, body ưu tiên khả năng đọc dài.Những nhóm token quan trọng nhất
Đặc tả hiện tại hỗ trợ các nhóm token như colors, typography, rounded, spacing và components. Ngoài ra còn có name, description và version ở cấp gốc. Phần components đặc biệt hữu ích vì cho phép ánh xạ token vào những phần tử UI thực tế như button-primary, button-primary-hover, card-default hoặc input-error, giúp agent không chỉ biết “bảng màu là gì” mà còn hiểu “component này phải trông như thế nào”.
Cách tham chiếu token
DESIGN.md dùng token reference theo dạng {path.to.token}. Ví dụ, "{colors.primary}" hoặc "{rounded.sm}". Đây là điểm cực kỳ quan trọng khi làm việc với agent, vì nó giúp giảm lặp, giữ tính nhất quán và làm rõ quan hệ giữa component và hệ token gốc. Nếu về sau bạn đổi colors.primary, agent có thể theo token mới thay vì giữ lại giá trị cũ ở từng component rời rạc.
Cách thiết lập DESIGN.md trong dự án thật
Đặt file ở đâu trong repository
Tiêu chuẩn không ép cứng một cấu trúc thư mục duy nhất, nhưng cách thực dụng nhất là đặt DESIGN.md ở root repository hoặc trong thư mục tài liệu chuẩn như docs/. Với AI coding agents, vị trí dễ truy cập là rất quan trọng. Nếu agent thường được cấp quyền đọc toàn repo, đặt file ở root sẽ giúp nó được phát hiện sớm cùng với README.md, package.json và thư mục src/.
Một cấu trúc dễ vận hành có thể là:
project/
├── DESIGN.md
├── README.md
├── src/
│ ├── components/
│ ├── pages/
│ └── styles/
└── docs/
└── ui-guidelines/Viết phần prose theo đúng mục đích
Ngoài token, phần prose nên mô tả các mục như Overview, Colors, Typography, Layout, Shapes, Components và Do’s and Don’ts. Đặc tả nêu thứ tự section chuẩn và cho phép bỏ qua một số mục, nhưng các section có mặt nên đi theo canonical order để công cụ lint và agent diễn giải nhất quán hơn. Đây là phần nhiều đội ngũ hay xem nhẹ, trong khi thực tế chính prose mới giúp AI hiểu vì sao không nên lạm dụng accent color, khi nào nên dùng card elevation thấp, hoặc đâu là style phù hợp cho dashboard so với marketing site.
Dùng CLI để kiểm tra file trước khi giao cho agent
Bộ công cụ đi kèm hỗ trợ lint, diff, export và spec. Trong đó, lint là lệnh nên dùng đầu tiên vì nó phát hiện broken token references, cảnh báo contrast ratio theo WCAG, cảnh báo section order và các thiếu sót cấu trúc khác. Điều này biến DESIGN.md thành tài sản có thể kiểm tra tự động trong CI thay vì một file tài liệu chỉ để tham khảo.
npm install @google/design.md
npx @google/design.md lint DESIGN.mdNếu muốn so sánh hai phiên bản design system để phát hiện regression ở mức token và prose:
npx @google/design.md diff DESIGN.md DESIGN-v2.mdNếu muốn xuất token sang định dạng khác như Tailwind hoặc DTCG:
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format dtcg DESIGN.md > tokens.jsonCách AI coding agents sử dụng DESIGN.md trong thực tế
Luồng làm việc điển hình
Khi một agent như Cursor, Gemini hoặc Copilot được yêu cầu “tạo một dashboard settings page”, nếu agent chỉ có prompt văn bản, kết quả thường đúng chức năng nhưng sai phong cách. Nếu agent đọc được DESIGN.md, nó có thêm nền tảng để quyết định dùng màu nào cho nút chính, typography nào cho heading, khoảng cách nào giữa các section và bo góc nào cho card. Agent không cần suy diễn từ các file CSS rời rạc nữa, mà có thể ánh xạ trực tiếp từ design tokens và component rules sang code.
Ví dụ prompt thực tế cho agent
Bạn có thể dùng một prompt kiểu:
Đọc file DESIGN.md ở root repo trước khi sinh code.
Tạo component React tên SettingsPanel.
Yêu cầu:
- dùng token button-primary cho CTA chính
- card nền theo surface
- heading theo typography.h1
- spacing theo scale đã định nghĩa
- không tạo màu mới ngoài DESIGN.mdNếu DESIGN.md được viết đúng, agent sẽ có đủ dữ liệu để sinh JSX, CSS variables hoặc Tailwind config gần đúng với hệ thống thiết kế ngay từ đầu. Đây là khác biệt lớn so với cách làm cũ, nơi cùng một yêu cầu có thể tạo ra ba phiên bản UI khác nhau tùy model và ngữ cảnh hội thoại.
Ví dụ component mà agent có thể sinh ra
export function SettingsPanel() {
return (
<section className="rounded-md bg-surface p-md">
<h1 className="text-h1 text-primary">Cài đặt hệ thống</h1>
<p className="text-body-md text-secondary">
Quản lý thông tin chung, bảo mật và thông báo.
</p>
<button className="button-primary">Lưu thay đổi</button>
</section>
);
}
Ở đây, giá trị thực tế của rounded-md, bg-surface, text-h1 hay button-primary không còn là quyết định ngẫu nhiên của agent. Chúng phải bám vào DESIGN.md. Nếu đội ngũ đổi brand color hoặc tăng border radius ở file trung tâm, các lần sinh UI về sau cũng có xu hướng đồng bộ theo.
[Ảnh minh họa: AI agent đọc DESIGN.md rồi sinh component React nhất quán với design system]
Những lưu ý để DESIGN.md thật sự hiệu quả
Đừng chỉ chép token, hãy viết rationale
Một DESIGN.md tốt không phải file dài nhất, mà là file giúp agent hiểu đúng nhất. Nếu bạn chỉ ghi mã màu và font size mà không giải thích đâu là accent duy nhất, đâu là giọng điệu thương hiệu, đâu là trường hợp không nên dùng shadow mạnh, agent vẫn có thể sinh UI đúng token nhưng sai tinh thần. Phần prose vì vậy là nơi chuyển hóa design system từ “giá trị tĩnh” thành “quy tắc sống”.
Dùng DESIGN.md như hợp đồng giữa design và engineering
Với nhóm sản phẩm hiện đại, file này nên được xem như một contract. Designer cập nhật nó khi visual identity thay đổi; frontend dùng nó để map vào token implementation; AI agent dùng nó để scaffold UI; CI dùng linter để chặn lỗi cấu trúc. Khi mọi bên cùng xoay quanh một nguồn sự thật, chi phí đồng bộ sẽ giảm đáng kể.
DESIGN.md đáng chú ý vì nó đưa design system vào đúng định dạng mà AI coding agents có thể hiểu ổn định: có cấu trúc, có kiểm tra được và vẫn giữ phần giải thích cho con người. Với xu hướng lập trình đồng hành cùng AI ngày càng mạnh, đây không chỉ là tài liệu thiết kế mới mà là một lớp hạ tầng giúp frontend, UI/UX và agent automation làm việc cùng nhau hiệu quả hơn. Nếu bạn đang xây một sản phẩm có nhiều màn hình, nhiều contributor và nhiều agent tham gia viết code, việc thêm một file DESIGN.md vào repo có thể là bước nhỏ nhưng mang lại tác động rất lớn lên tính nhất quán giao diện.
