DESIGN.md là gì? Cho AI đọc design system của bạn

DESIGN.md là một file Markdown đặt ở gốc dự án, mô tả design system theo cách AI agent đọc được. Phần đầu file chứa token (màu, chữ, bo góc, khoảng cách) viết bằng YAML. Phần sau giải thích bằng chữ vì sao các giá trị đó tồn tại và dùng chúng ra sao. Google Labs mở mã nguồn định dạng này vào tháng 4/2026.

Tôi là Hai Le, UI/UX designer biết code. Site bạn đang đọc được dựng bằng Next.js và Tailwind, và mọi quyết định về giao diện của nó nằm trong một file DESIGN.md ở gốc repo. Bài này dùng chính file đó làm ví dụ.

DESIGN.md là gì và từ đâu ra?

DESIGN.md là một đặc tả (spec) do Google Labs công bố trên GitHub, kho google-labs-code/design.md. Nó gắn với Stitch, công cụ thiết kế giao diện bằng AI của Google, nhưng bản thân định dạng không phụ thuộc vào Stitch. Bất kỳ agent nào đọc được Markdown đều dùng được nó: Claude Code, Cursor, Gemini CLI.

Tài liệu chính thức mô tả nó là "định dạng để mô tả nhận diện thị giác cho coding agent". Nói gọn hơn, đây là bản hướng dẫn thương hiệu viết cho người mới vào team, chỉ khác là người mới đó là một mô hình ngôn ngữ.

Vài thông tin nền, kiểm ngày 2026-10-04:

• Giấy phép Apache 2.0.
• Trường version hiện là alpha. Cấu trúc còn thay đổi được.
• Có kèm CLI chạy qua npx @google/design.md, với các lệnh lint, diff, export và spec.

Vì sao AI cần một file như vậy?

Khi bạn nhờ AI dựng một trang mà không đưa gì thêm, nó sẽ chọn giá trị mặc định: một màu xanh tím quen thuộc, bóng đổ dưới mọi thẻ, chữ đậm 600 cho tiêu đề. Kết quả trông ổn nhưng chẳng giống sản phẩm của bạn. Người ta hay gọi đó là giao diện "nhìn là biết AI làm".

AI làm vậy vì nó không thấy design system của bạn. Figma variables nằm trong file Figma. Lý do chọn màu nằm trong đầu bạn hoặc trong một trang Notion. Thứ duy nhất agent chắc chắn đọc được là các file trong thư mục dự án.

DESIGN.md đặt cả hai thứ vào đó. Token cho biết giá trị chính xác. Phần chữ cho biết ý đồ, để khi gặp tình huống file không nói tới, agent vẫn đoán gần đúng thay vì quay về mặc định.

Ví dụ thật từ site này: màu thương hiệu #FF009D trên nền trắng chỉ đạt tỉ lệ tương phản 3.66:1. Nếu chỉ có token, AI sẽ dùng nó cho cả nút lẫn link chữ nhỏ, và link chữ nhỏ sẽ trượt chuẩn WCAG AA. Phần chữ trong DESIGN.md ghi rõ: chữ magenta từ 20px trở xuống phải dùng primary-text (#be0074, 6.09:1). Một dòng giải thích đó chặn được cả một loại lỗi.

Một file DESIGN.md gồm những phần nào?

File có hai lớp.

Lớp 1: YAML front matter. Nằm giữa hai dòng --- ở đầu file. Các khoá theo đặc tả là version, name, description, rồi năm nhóm token: colors, typography, rounded, spacing, components. Token có thể trỏ tới nhau bằng cú pháp ngoặc nhọn, ví dụ {colors.primary}.

Đây là đoạn đầu file của site này, rút gọn:

---
version: alpha
name: Haile-design-analysis
description: The Haile design language — a portfolio site whose surface
  pairs a pure-white canvas and a strictly neutral grey ladder with a
  single saturated magenta accent (#FF009D) ...

colors:
  background: "{neutral.50}"
  foreground: "{neutral.950}"
  primary: "{primary.500} / {primary.400}"
  primary-text: "{primary.700} / {primary.400}"   # extension — magenta at body size
  muted: "{neutral.100}"
  border: "{neutral.200}"

rounded:
  sm: 8px
  md: 12px
  pill: 9999px
---

Lớp 2: phần thân Markdown. Đặc tả đề xuất tám mục theo thứ tự này:

Mục lạ không làm file hỏng. README của đặc tả ghi rằng heading không nằm trong danh sách sẽ được giữ nguyên, không báo lỗi. File của tôi có thêm mục "UI & Design System" ở đầu và mục "Motion" ở giữa.

DESIGN.md khác gì Figma variables, file token JSON và CLAUDE.md?

Người mới thường hỏi câu này đầu tiên, vì cả bốn thứ đều "chứa design system" theo một nghĩa nào đó.

Điểm cần nhớ: Claude Code tự nạp CLAUDE.md khi bắt đầu phiên, và đọc được AGENTS.md theo tài liệu chính thức. DESIGN.md thì không được nạp tự động. Bạn phải trỏ tới nó.

Nếu bạn chưa rõ token là gì, đọc trước bài Design token là gì. DESIGN.md chỉ là một cách đóng gói token, nên hiểu ba lớp raw, alias, semantic sẽ giúp bạn viết phần màu gọn hơn nhiều.

Tôi dùng DESIGN.md trong site này như thế nào?

Site này có ba file liên quan, mỗi file một việc:

1. DESIGN.md là nguồn sự thật về thiết kế. Token ở đầu, giải thích ở sau.
2. app/globals.css là bản dịch token sang CSS variables mà Tailwind dùng. Trình duyệt chỉ đọc file này.
3. AGENTS.md là quy ước dự án cho agent. Dòng đầu tiên của nó trỏ về DESIGN.md. CLAUDE.md chỉ có một dòng @AGENTS.md, cú pháp import của Claude Code, để Claude nạp AGENTS.md vào mỗi phiên.

Mỗi khi tôi nhờ Claude Code dựng một khối giao diện mới, nó đọc AGENTS.md, thấy chỉ dẫn mở DESIGN.md, và làm theo các quy tắc trong đó. Ba quy tắc tôi thấy hiệu quả nhất:

Ba bề mặt, bốn bậc chữ. File ghi rằng toàn trang chỉ có ba giá trị nền (#ffffff, #f8f8f8, #efefef) và bốn bậc chữ xám. Câu "nếu thiết kế cần thêm một giá trị nữa thì bố cục đã sai" cho AI một cách tự kiểm: khi muốn thêm màu nền mới, nó biết phải dừng lại.

Không có box-shadow ở bất kỳ đâu. Đây là quy tắc AI hay vi phạm nhất khi không có hướng dẫn, vì gần như mọi mẫu UI trên mạng đều có bóng đổ. Mục Elevation & Depth của tôi liệt kê đúng ba cách tách lớp được phép, và ghi rõ modal tách khỏi trang bằng lớp phủ, không bằng bóng.

Thang xám đánh số theo khoảng cách tới nền. Tôi dùng quy ước của Radix: neutral-50 luôn là nền, neutral-950 luôn là chữ đậm nhất, ở cả chế độ sáng lẫn tối. Quy ước này ngược với Tailwind, nên tôi viết hẳn một mục giải thích. Không có mục đó, AI sẽ đoán neutral-50 là màu sáng nhất và dark mode sẽ sai.

Cách tôi làm việc với Figma và Claude Code từ đầu đến cuối nằm ở bài Claude Code cho designer. Phần lấy token trực tiếp từ file Figma qua MCP nằm ở bài Figma MCP và Claude Code.

Viết DESIGN.md đầu tiên của bạn thế nào?

Bạn chưa cần code để bắt đầu. Tôi đề xuất thứ tự này:

1. Ghi ba câu Overview. Giao diện của bạn có tính cách gì? Màu chủ đạo dùng cho việc gì? Có điều gì bạn không bao giờ làm? Ba câu này định hướng cho mọi quyết định AI phải tự đoán.
2. Chép token màu từ Figma. Bắt đầu với màu ngữ nghĩa (nền, chữ, viền, màu chính). Bạn có thể bỏ thang màu thô ở lần đầu.
3. Viết lý do cho từng màu ngữ nghĩa. Dùng ở đâu, không dùng ở đâu, đạt tương phản bao nhiêu trên nền nào.
4. Thêm thang chữ. Ghi cỡ, line-height, độ đậm, letter-spacing, và quy tắc chung (ví dụ của tôi: weight 400 ở mọi cỡ, phân cấp bằng cỡ chữ và màu).
5. Viết mục Do's and Don'ts. Liệt kê những lỗi bạn thấy AI hay mắc trên giao diện của mình. Đây là mục tôi sửa nhiều nhất.
6. Trỏ tới file từ CLAUDE.md hoặc AGENTS.md. Một dòng là đủ, ví dụ: "Nguồn sự thật về thiết kế là DESIGN.md, đọc trước khi sửa giao diện."

Đặc tả có kèm lệnh kiểm tra cấu trúc. Lệnh dưới đây lấy từ README chính thức. Tôi chưa chạy nó trên file của site này, nên chưa biết file của tôi qua được bao nhiêu quy tắc.

npx @google/design.md lint DESIGN.md

README liệt kê các quy tắc lint như tham chiếu bị gãy (broken-ref), thiếu màu chính (missing-primary), tỉ lệ tương phản (contrast-ratio) và sai thứ tự mục (section-order). Trên Windows PowerShell, README khuyên dùng tên designmd thay cho design.md để tránh xung đột với cách Windows mở file.

Nếu chưa cài Claude Code, bài Cài đặt Claude Code đi từng bước từ việc mở terminal.

Những lỗi hay gặp khi viết DESIGN.md là gì?

Chỉ có token, không có chữ. Một file toàn YAML thì không khác gì file JSON. Giá trị riêng của DESIGN.md nằm ở phần giải thích.

Viết như tài liệu marketing. Những cụm như "hiện đại, tinh tế, thân thiện" không giúp được AI quyết định gì. Viết điều kiểm chứng được: "tiêu đề luôn weight 400", "hover chỉ đổi nền sang muted".

Để file cũ đi. Tôi đổi font chính của site từ Be Vietnam Pro sang Google Sans Flex vào tháng 9/2026. Nếu hôm đó tôi chỉ sửa CSS mà quên DESIGN.md, mọi trang AI dựng sau đó sẽ lại xin dùng font cũ.

Đặt quy tắc trái nhau ở hai nơi. Như ví dụ weight 600 ở trên. Chọn một file làm nguồn sự thật, file còn lại chỉ trỏ tới.

Cố nhồi mọi thứ. Quy ước code (cấu trúc thư mục, thư viện i18n, cách đặt tên file) thuộc về CLAUDE.md hoặc AGENTS.md. DESIGN.md chỉ nên nói về những gì người dùng nhìn thấy.

Bắt đầu từ đâu?

Nếu bạn có sẵn file Figma với variables, hãy mở một file Markdown trống và viết mục Overview trong mười phút. Sau đó nhờ AI dựng một màn hình đơn giản, xem nó sai chỗ nào, và ghi chỗ sai đó vào Do's and Don'ts. Lặp lại vài vòng, file sẽ tự dày lên theo đúng những gì giao diện của bạn cần.

Tôi từng dựng design system hơn 50 component cho Joyme khi chưa có định dạng này, và phần khó nhất luôn là truyền đạt lý do cho dev. Bạn có thể xem cách tôi làm ở case study Joyme. Nếu team bạn cần người dựng design system đọc được bởi cả người lẫn AI, xem thêm về tôi ở trang giới thiệu.

Nguồn

• google-labs-code/design.md trên GitHub: đặc tả, danh sách mục, CLI, quy tắc lint. Truy cập 2026-10-04.
• Đặc tả DESIGN.md trên trang tài liệu Stitch. Truy cập 2026-10-04.
• The Decoder: Google's open-source DESIGN.md gives AI agents a prompt-ready blueprint: thời điểm mở mã nguồn (23/4/2026).
• Claude Code docs: How Claude remembers your project: CLAUDE.md, AGENTS.md, cú pháp @path.
• DESIGN.md, AGENTS.md, CLAUDE.md và app/globals.css trong repo của site này.