DESIGN.md là gì?

DESIGN.md đến từ đâu#

Cấu trúc của một tệp DESIGN.md#

---
name: DevFocus Dark
colors:
  primary: "#2665fd"
  secondary: "#475569"
  surface: "#0b1326"
  on-surface: "#dae2fd"
  error: "#ffb4ab"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
rounded:
  md: 8px
---

# 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

Tám mục chuẩn#

Phần thân markdown dùng tiêu đề ##. Có thể bỏ qua những mục không liên quan, nhưng các mục có mặt nên theo đúng thứ tự này. Một tiêu đề xuất hiện hai lần sẽ khiến tệp không hợp lệ; các mục không xác định vẫn được giữ lại.

1. Overview (hoặc Brand & Style). Giao diện và cảm giác trong vài câu: không khí, mật độ, cá tính.
2. Colors. Từng token màu và vai trò của nó, chẳng hạn hành động chính hay bề mặt trang.
3. Typography. Các họ font và thang kiểu chữ, từ tiêu đề lớn đến nhãn nhỏ.
4. Layout (hoặc Layout & Spacing). Thang khoảng cách, lưới, độ rộng nội dung và khoảng đệm giữa các cột.
5. Elevation & Depth (hoặc Elevation). Cách các bề mặt tách biệt nhau: đổ bóng, viền, sắc màu.
6. Shapes. Bán kính bo góc và các quy tắc hình dạng khác.
7. Components. Nút, ô nhập liệu, thẻ và các thành phần cơ bản khác, cùng token và trạng thái của chúng.
8. Do's and Don'ts. Những quy tắc agent không được phá vỡ.

Một phần thân markdown gọn gàng với từng mục chuẩn theo thứ tự. Điều chỉnh nội dung cho sản phẩm của bạn, giữ nguyên tiêu đề và thứ tự.

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

## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds

## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase

## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile

## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces

## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view

## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast

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

Design token và schema#

DESIGN.md nhúng design token dưới dạng front matter YAML ở đầu tệp. Khối front matter bắt đầu bằng một dòng chỉ chứa đúng --- và kết thúc bằng chính dấu phân cách đó.

version: <string>
name: <string>
description: <string>
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Các tên thang phổ biến gồm xs, sm, md, lg, xl và full, nhưng bất kỳ khóa mô tả nào cũng hợp lệ. Token khoảng cách nằm trong YAML dưới spacing: và được mô tả trong mục Layout của phần thân markdown.

Các loại token

Color

Bất kỳ chuỗi màu CSS hợp lệ nào. Mã hex dạng #RRGGBB là mặc định được khuyến nghị, ví dụ "#1A1C1E".

Dimension

Một số kèm đơn vị px, em hoặc rem. Ví dụ:48px,-0.02em.

Token Reference

Đặt trong dấu ngoặc nhọn và trỏ tới một giá trị trong cây YAML. Ví dụ:{colors.primary}.

Typography

Một đối tượng tổng hợp chứa các thuộc tính font như họ font, cỡ chữ, độ đậm, chiều cao dòng và khoảng cách chữ. Xem Thuộc tính kiểu chữ.

Thuộc tính kiểu chữ

fontFamily

Tên họ font.

fontSize

Cỡ chữ dưới dạng một dimension.

fontWeight

Độ đậm dạng số, chẳng hạn 400 hoặc 700.

lineHeight

Một dimension hoặc hệ số nhân không đơn vị. Nên dùng giá trị không đơn vị.

letterSpacing

Điều chỉnh khoảng cách chữ dưới dạng một dimension.

fontFeature

Cấu hình font-feature-settings.

fontVariation

Cấu hình font-variation-settings.

Tham chiếu token

Tham chiếu token được đặt trong dấu ngoặc nhọn và chứa đường dẫn đối tượng tới một giá trị khác trong cây YAML. Với hầu hết các nhóm token, tham chiếu nên trỏ tới một giá trị nguyên thủy thay vì một nhóm. Trong mục components, được phép tham chiếu tới giá trị tổng hợp như các cấp kiểu chữ.

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

Component

backgroundColor

Color

textColor

Color

typography

Typography

rounded

Dimension

padding

Dimension

size

Dimension

height

Dimension

width

Dimension

Tên token được khuyến nghị

Agent AI dùng DESIGN.md như thế nào#

## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.

Claude Code

Đọc các tệp trong repo của bạn và nạp CLAUDE.md khi khởi động. Thêm một dòng ở đó trỏ tới DESIGN.md, hoặc nhắc đến tệp trong prompt.

Cursor

Thêm DESIGN.md vào ngữ cảnh chat, hoặc tham chiếu nó từ một project rule để áp dụng cho mọi yêu cầu UI.

GitHub Copilot

Trỏ tới DESIGN.md từ tệp Copilot instructions của repository, hoặc đính kèm nó trong chat khi bạn yêu cầu làm UI.

Google Stitch

Nơi định dạng này ra đời. Stitch dùng DESIGN.md để các màn hình được tạo ra dùng chung một bảng màu, thang kiểu chữ và ngôn ngữ component.

Sau đó agent lấy giá trị chính xác từ token (mã hex của nút chính, cỡ chữ của nhãn body-md) và dựa vào phần văn bản để quyết định dùng chúng ở đâu.

DESIGN.md, AGENTS.md và README.md#

Ba tệp nằm cạnh nhau và trả lời những câu hỏi khác nhau. DESIGN.md không thay thế AGENTS.md; hai tệp bổ trợ cho nhau.

Ví dụ DESIGN.md thực tế#

Cách nhanh nhất để hiểu định dạng là đọc vài tệp thật. Mỗi trang trong thư viện mẫu dưới đây hiển thị một DESIGN.md được trích xuất từ trang web công khai của thương hiệu, kèm bảng màu và mẫu kiểu chữ. Đây không phải hướng dẫn thương hiệu chính thức.

• DESIGN.md của Stripe
• DESIGN.md của Anthropic
• DESIGN.md của Airbnb
• DESIGN.md của Linear
• DESIGN.md của Notion
• DESIGN.md của Supabase

Xem tất cả mẫu DESIGN.md

Cách có được một DESIGN.md#

1. Tự viết. Bắt đầu từ đặc tả và các ví dụ ở trên, rồi kiểm tra tệp bằng Trình kiểm tra DESIGN.md miễn phí hoặc lệnh lint của Google.
2. Bắt đầu từ một ví dụ. Sao chép một tệp từ thư viện mẫu và sửa token cùng phần văn bản cho khớp với sản phẩm của bạn.
3. Tạo từ một trang web đang hoạt động. Dán một URL công khai vào Design Extractor. Công cụ hiển thị trang web trong trình duyệt và trả về một DESIGN.md với màu sắc, kiểu chữ, khoảng cách và component của trang, tuân theo đặc tả ở trên. Trang Trình tạo DESIGN.md giải thích bạn nhận được gì. Cùng quy trình trích xuất đó cũng chạy được từ tiện ích mở rộng Chrome và từ agent của bạn qua máy chủ MCP.