DESIGN.md – “Ngôn ngữ mẹ đẻ” mới cho AI coding agent

DESIGN.md là gì, cấu trúc ra sao, vì sao markdown lại là format phù hợp cho LLM, và một kho tài nguyên có sẵn để dùng ngay.

Gần đây có một khái niệm đang lan khá nhanh trong cộng đồng AI dev: DESIGN.md – một file markdown duy nhất mô tả toàn bộ design system của sản phẩm, để AI agent đọc và tuân thủ khi sinh UI. Google Stitch giới thiệu khái niệm này, mình cũng giới thiệu repo chứa nhiều tiêu chuẩn design của các service nổi tiếng đã được đưa vào DESIGN.md

---

DESIGN.md là gì?

Một file markdown nằm ở root project, mô tả design system ở dạng plain-text. Không cần export Figma, không cần JSON schema, không cần plugin. Chỉ cần một file .md mà cả người lẫn AI đều đọc được.

Cách dùng:

1. Đặt DESIGN.md vào thư mục root

2. Để AI agent (Claude Code, Cursor, Gemini CLI, Copilot…) đọc

3. Yêu cầu: “Build the UI according to this design system”

Agent sẽ sinh giao diện bám sát màu sắc, typography, spacing, component styles đã định nghĩa – thay vì UI “generic AI” mặc định.

---

Tại sao markdown?

LLM được train trên text. Khi chúng ta export design system ra JSON schema hay qua Figma API, thông tin phải đi qua nhiều layer chuyển đổi – mỗi layer là cơ hội mất mát ngữ nghĩa. Markdown thì model đọc trực tiếp: headings, tables, bullet points – đúng format mà nó đã xử lý hàng tỷ lần trong quá trình huấn luyện.

Google Stitch gọi markdown là primitive chuẩn để mô tả design system cho LLM.

Vài điểm đáng chú ý:

• Single source of truth – mọi agent đọc cùng một nguồn, hạn chế drift giữa các lần prompt

• Không phụ thuộc design tool, plugin hay schema format cụ thể nào

• Versionable, reviewable, mergeable – sống trong Git như mọi file code khác

DESIGN.md biến design system thành thứ mà engineering workflow đã biết cách xử lý.

---

Cấu trúc một file DESIGN.md

Google Stitch cung cấp format chuẩn. Một file đầy đủ thường gồm:

• Visual Theme & Atmosphere – Mood, triết lý thiết kế

• Color Palette & Roles – Mã màu, vai trò (primary, success, danger…)

• Typography Rules – Font, scale, hierarchy H1 đến caption

• Component Stylings – Button, card, input, navbar kèm states

• Layout Principles – Spacing scale, grid, whitespace

• Depth & Elevation – Shadow, surface layer

• Do’s and Don’ts – Guardrails, anti-patterns

• Responsive Behavior – Breakpoint, touch target, collapse strategy

• Agent Prompt Guide – Quick reference và prompt mẫu

Format vừa đủ structured để agent parse, vừa đủ tự nhiên để người đọc không thấy đang đọc config file.

Ví dụ:

# Design System

## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.

## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions

## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14–16px
- **Labels**: Inter, medium, 12px, uppercase for section headers

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast

## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text

---

DESIGN.md và AGENTS.md

Trong thực tế, DESIGN.md thường đi cùng AGENTS.md:

• AGENTS.md – Cho coding agent: architecture, naming convention, CI/CD, quy trình

• DESIGN.md – Cho design/UI agent: sản phẩm nên trông và cảm giác như thế nào

Nghĩ theo mô hình onboarding: AGENTS.md là engineering handbook, DESIGN.md là brand guideline. Chúng ta onboard AI agent giống cách onboard một engineer mới – cho đọc tài liệu trước khi đụng vào code.

---

Kho DESIGN.md tham khảo của các dịch vụ nổi tiếng

VoltAgent đã build repo với hơn 40 file DESIGN.md trích xuất từ các sản phẩm nổi tiếng: Stripe, Vercel, Linear, Notion, Claude, Cursor, Warp, Zapier, Airbnb, Spotify, Uber, Coinbase…

Link: https://github.com/VoltAgent/awesome-design-md/tree/main/design-md

Mỗi thư mục chứa DESIGN.md theo format Stitch, kèm preview.html và preview-dark.html để xem trực quan trước khi dùng.

Cách dùng:

1. Chọn site có style gần với brand của chúng ta

2. Copy DESIGN.md vào project root

3. Cho agent đọc và build UI theo

4. Refactor dần thành bản custom riêng

Repo MIT license, community maintain. Có thể mở issue yêu cầu thêm DESIGN.md cho website khác.

---

Kết

DESIGN.md là một ý tưởng đơn giản: biến design system thành file markdown, đúng format mà cả người lẫn LLM đọc tốt nhất. Khi kết hợp với AI coding agent, nó giúp chúng ta thu hẹp khoảng cách từ brand guideline đến UI thực tế, và chuẩn hóa cách AI agent làm việc trong team.

Link tham khảo:

• Docs chính thức của Google Stitch: stitch.withgoogle.com/docs/design-md/overview

• Repo tài nguyên: github.com/VoltAgent/awesome-design-md

“Viết code đúng” và “viết code đúng style“ là hai chuyện khác nhau. DESIGN.md là mảnh ghép ở giữa.