VI EN
Tools

DESIGN.md: đưa “gu thiết kế” vào repo để AI build UI không còn generic

Binh Cập nhật 4 phút đọc Read this article in English

Tóm tắt

DESIGN.md là file Markdown mô tả hệ thống thiết kế (màu, typography, spacing, elevation, responsive) để coding agent đọc khi dựng UI. Repo VoltAgent/awesome-design-md và trang getdesign.md cung cấp hàng trăm mẫu tham khảo. Dùng làm điểm khởi đầu, không sao chép nhận diện thương hiệu của người khác.

Nhờ coding agent dựng một trang landing, bạn thường nhận được một giao diện “đúng nhưng nhạt”: gradient tím, card bo góc, font mặc định — trông giống hàng nghìn trang AI khác. Lý do đơn giản: agent không biết gu thiết kế của bạn. DESIGN.md giải quyết đúng chỗ đó: một file Markdown mô tả hệ thống thiết kế để agent đọc trước khi viết UI, giống như AGENTS.md mô tả cách build dự án.

DESIGN.md là gì?

Đó là tài liệu hệ thống thiết kế viết bằng Markdown thuần. Vì model đọc Markdown rất tốt, bạn không cần export Figma, JSON token hay công cụ build nào — chỉ cần một file trong thư mục gốc dự án. Định dạng này dựa trên đặc tả DESIGN.md của Google Stitch, công cụ thiết kế AI của Google.

Một DESIGN.md đầy đủ gồm những gì?

MụcNội dung
1. Visual theme & atmosphereTinh thần chung: tối giản, editorial, vui tươi, kỹ thuật…
2. Color palette & rolesMàu kèm vai trò: primary, surface, text, border, trạng thái; cả light và dark
3. Typography rulesFont, thang cỡ chữ, line-height, độ đậm cho heading/body/label
4. Component stylingsButton, card, input… với trạng thái hover/focus/disabled
5. Layout principlesThang spacing 4/8px, max-width, grid, nhịp khoảng trắng
6. Depth & elevationShadow, radius, cách phân lớp
7. Do’s and don’tsĐiều nên/không nên — phần giúp tránh UI “AI slop” nhất
8. Responsive behaviorBreakpoint, cách co giãn trên mobile
9. Agent prompt guideBảng màu tra nhanh và prompt mẫu dùng ngay

Kho mẫu: VoltAgent/awesome-design-md

Thay vì viết từ đầu, bạn có thể bắt đầu từ repo awesome-design-md của VoltAgent — theo BrightCoding, repo có 73 file DESIGN.md được trích xuất từ website của các thương hiệu thật và đạt khoảng 102.000 sao GitHub:

  • Nền tảng AI: Claude, Cohere, ElevenLabs…
  • Công cụ dev: Vercel, Cursor, Warp…
  • Fintech: Stripe, Coinbase, Revolut…
  • Ô tô: BMW, Tesla, Ferrari…
  • “Retro Web”: Dell 1996, Nintendo.com 2001 — cho dự án hoài cổ.

Mỗi mẫu kèm preview.html và preview-dark.html để bạn mở trình duyệt xem trực quan token trước khi đưa cho agent. Trang getdesign.md cho phép duyệt và tải từng file.

Cách dùng với Claude Code (hoặc agent bất kỳ)

  1. Chọn mẫu gần phong cách bạn muốn trên getdesign.md hoặc trong repo, mở file preview để kiểm tra.
  2. Sao chép vào thư mục gốc dự án thành DESIGN.md.
  3. Tuỳ biến: đổi màu, font, tên thương hiệu thành của bạn; bỏ những thành phần không dùng. Đây là bước bắt buộc — không dùng nguyên nhận diện của thương hiệu khác.
  4. Nối vào agent: thêm một dòng vào CLAUDE.md hoặc AGENTS.md: “Mọi việc UI phải tuân thủ DESIGN.md ở thư mục gốc”.
  5. Bắt agent tự kiểm: yêu cầu agent review UI vừa làm so với mục Do’s and Don’ts trước khi báo xong.
Prompt mẫu:
Dựng trang pricing 3 gói theo DESIGN.md. Dùng đúng token màu và thang spacing.
Sau khi xong, liệt kê những chỗ bạn đã áp dụng mục "Do's and Don'ts".

Lưu ý quan trọng

  • Bản quyền thương hiệu: cấu trúc repo và công trích xuất được cấp phép MIT, nhưng nhận diện thị giác (logo, màu đặc trưng, font riêng) thuộc chủ sở hữu thương hiệu. Học cấu trúc và nguyên tắc, đừng clone giao diện của người khác cho sản phẩm thương mại.
  • Có thể sai: các file được trích từ CSS công khai nên có thể sai mã màu hoặc thiếu token; giá trị phản ánh thời điểm trích xuất.
  • Nền tảng ngoài web: với React Native hay SwiftUI, chất lượng phụ thuộc nhiều vào khả năng của agent.

Áp dụng thế nào?

  • Dev: Với dự án đang có design system, nhờ agent đọc CSS/theme hiện tại và viết ngược ra DESIGN.md — từ đó mọi màn hình mới sẽ nhất quán.
  • Tech Lead: Đặt DESIGN.md cạnh AGENTS.md trong repo, review thay đổi của nó như review design token.
  • PM / Designer: DESIGN.md là cách rẻ nhất để chuyển “gu” của team thành thứ agent hiểu được. Viết mục Do’s and Don’ts từ các phản hồi UI bạn hay phải nhắc lại.

Nguồn & tham khảo

  1. VoltAgent/awesome-design-md: DESIGN.md Files for AI UI Generation — BrightCoding
  2. VoltAgent/awesome-design-md — GitHub
  3. getdesign.md — getdesign.md
Thêm bài về Tools