## Công việc liên quan đến giao diện (UI) và thiết kế
- Đọc `DESIGN.md` trước khi thực hiện bất kỳ thay đổi nào đối với giao diện người dùng.
- Coi `DESIGN.md` là nguồn cho các quyết định về mặt hình ảnh.
- Sử dụng các design tokens và components hiện có.
- Không tự ý phát minh ra màu sắc, kiểu chữ hoặc giá trị khoảng cách mới.
- Cập nhật `DESIGN.md` khi thêm một pattern tái sử dụng đã được phê duyệt.
Những gì nên đưa vào DESIGN.md
Nếu bạn muốn có được một thiết kế nhất quán do Claude Code tạo ra, bạn cần đầu tư xây dựng một tệp DESIGN.md thật vững chắc. Tệp này nên chứa các quyết định thiết kế mang tính bền vững để Claude dựa vào đó sản xuất ra các giao diện đồng bộ.
1. Định hướng thiết kế và các ưu tiên (Design direction and priorities)
Mô tả định hướng trực quan và tương tác sẽ đi về đâu. Hãy càng cụ thể càng tốt. Tránh các hướng dẫn mơ hồ như “làm cho nó đẹp” hoặc “sử dụng thiết kế hiện đại” vì chúng không mang tính thực thi đối với AI. Thay vào đó, hãy mô tả các đặc điểm có thể quan sát và đánh giá được.
# Định hướng thiết kế
Thiết kế sản phẩm phải mang lại cảm giác bình yên và dễ quét thông tin (scan). Nó không được làm người dùng ngộp với quá nhiều hành động hoặc thông tin. Hãy tuân theo cách tiếp cận: một màn hình, một hành động cốt lõi.
Các ưu tiên:
1. Thông tin rõ ràng
2. Hệ thống phân cấp thị giác mạnh mẽ
3. Quét thông tin hiệu quả
4. Hạn chế sử dụng các yếu tố trang trí
5. Nhất quán trên toàn bộ quy trình làm việc
2. Các nguyên tắc trực quan (Visual principles)
Các nguyên tắc trực quan giúp củng cố thêm cho định hướng thiết kế đã nêu ở phần trước.
## Nguyên tắc trực quan
- Ưu tiên các bề mặt phẳng hơn là hiệu ứng gradient trang trí.
- Sử dụng đường viền (borders) và khoảng cách (spacing) thay vì đổ bóng quá đậm.
- Giữ cho màn hình có mật độ thông tin cao nhưng không mang lại cảm giác chật chội.
- Sử dụng duy nhất một hành động chính rõ ràng cho mỗi phần.
- Tránh các tiêu đề quá khổ và không gian trống quá mức.
- Tránh thẩm mỹ kiểu "trang landing page do AI tạo ra" chung chung.
3. Các Design Tokens
Hãy tài liệu hóa hệ thống thay vì rải rác các giá trị tùy tiện trong các prompt của bạn. Lý tưởng nhất là bạn nên bao quát các phần sau: Vai trò màu sắc, Kiểu chữ, Bo góc (Border radii), Đổ bóng, Kích thước icon, Chiều rộng nội dung, Các điểm gãy (Breakpoints).
## Design tokens
Sử dụng các tokens được định nghĩa trong `src/styles/tokens.css`.
### Khoảng cách (Spacing)
Sử dụng thang đo khoảng cách hiện có:
- `space-1`: 4px
- `space-2`: 8px
- `space-3`: 12px
- `space-4`: 16px
- `space-6`: 24px
- `space-8`: 32px
Không đưa vào các giá trị khoảng cách tự phát trừ khi thực sự cần thiết.
Lưu ý quan trọng: Tránh sao chép toàn bộ một file token lớn vào DESIGN.md. Một danh sách dài bị trùng lặp cuối cùng sẽ trở nên lỗi thời.
4. Quy tắc bố cục (Layout rules)
Nêu rõ các quy tắc quan trọng nhất mà Claude nên tuân theo khi tạo bố cục trang hoặc màn hình. Kỹ thuật ở đây là “phóng to/thu nhỏ”: xem xét cấu trúc tổng thể của trang trước khi tập trung vào các thành phần riêng lẻ.
## Bố cục
- Các trang trên máy tính dùng thanh điều hướng cố định bên trái (persistent left navigation).
- Nội dung chính có chiều rộng tối đa là 1440px.
- Sử dụng hệ lưới 12 cột (12-column grid) cho các bố cục máy tính phức tạp.
- Thu gọn các bảng phụ xuống dưới nội dung chính trên giao diện di động.
- Giữ cho các hành động chính luôn hiển thị mà không cần phải cuộn ngang.
5. Các mẫu thành phần (Component patterns)
Đối với các thành phần, hãy sử dụng kỹ thuật “phóng to”, tập trung vào từng thành phần riêng biệt và ngữ cảnh hoạt động của nó.
## Các thành phần
### Nút (Buttons)
- Một nút chính (primary button) cho mỗi nhóm hành động.
- Sử dụng các nút phụ (secondary buttons) cho các hành động bổ trợ.
- Sử dụng nút ghost cho các hành động có mức ưu tiên thấp trên thanh công cụ.
- Các hành động mang tính hủy hoại (destructive actions) yêu cầu phải có xác nhận.
### Thẻ (Cards)
- Thẻ dùng để nhóm các thông tin có liên quan, không phải các mảnh văn bản riêng lẻ.
- Tránh lồng thẻ bên trong thẻ.
- Sử dụng đường viền theo mặc định; chỉ giữ đổ bóng cho các lớp phủ (overlays).
### Bảng (Tables)
- Giữ cho các tiêu đề luôn hiển thị khi cuộn qua các tập dữ liệu dài (sticky header).
- Căn phải cho dữ liệu dạng số.
- Luôn cung cấp các trạng thái: đang tải (loading), trống (empty) và lỗi (error).
6. Tương tác và Chuyển động (Interaction and motion)
Chuyển động thường là phần bị bỏ quên trong quá trình thiết kế. Các đội ngũ thường thêm hoạt ảnh vào sau khi giao diện đã được thiết kế xong, điều này khiến chuyển động có cảm giác bị rời rạc.
## Chuyển động
- Sử dụng các hiệu ứng chuyển động để thông báo về sự thay đổi trạng thái.
- Giữ các chuyển tiếp thông thường trong khoảng từ 150ms đến 250ms.
- Tôn trọng các tùy chọn hạn chế chuyển động của hệ điều hành (reduced-motion).
- Tránh sử dụng hiệu ứng xuất hiện (entrance animations) cho mọi phần tử trên trang.
7. Hành vi đáp ứng (Responsive behavior)
Mô tả cách bố cục sẽ biến đổi, chứ không chỉ đơn thuần là liệt kê các breakpoint nào tồn tại.
## Hành vi đáp ứng
- Thiết kế các trạng thái máy tính, máy tính bảng và di động một cách có chủ đích.
- Chuyển đổi các bảng rộng thành dạng xem có thể cuộn được hoặc dạng tóm tắt.
- Giữ nguyên mức độ ưu tiên của hành động trên các màn hình nhỏ hơn.
8. Khả năng tiếp cận (Accessibility)
Hướng dẫn về khả năng tiếp cận nên bao gồm cấu trúc, hành vi cũng như độ tương phản hình ảnh.
## Khả năng tiếp cận
- Đáp ứng các yêu cầu về độ tương phản WCAG AA cho nội dung và các phần tử chức năng.
- Tất cả các bộ điều khiển phải có thể tiếp cận bằng bàn phím.
- Không truyền tải ý nghĩa chỉ thông qua màu sắc.
- Cung cấp các trạng thái focus rõ ràng.
- Liên kết các thông báo lỗi với các trường nhập liệu tương ứng của chúng.
9. Các phản mẫu cần tránh (Anti-patterns)
Một phần về phản mẫu sẽ cho Claude các ví dụ rõ ràng về những quyết định thiết kế có vẻ ngoài bắt mắt khi đứng độc lập nhưng lại xung đột với định hướng thiết kế chung của sản phẩm.
## Những điều cần tránh khi tạo thiết kế UI
- Các hiệu ứng gradient không cần thiết.
- Các thẻ được bo góc quá mức.
- Văn bản hero trang trí quá lớn bên trong các màn hình sản phẩm.
- Màu sắc tùy tiện nằm ngoài hệ thống token.
- Sử dụng biểu tượng cảm xúc (emojis) làm icon sản phẩm.
- Hiệu ứng kính mờ (glassmorphism) trừ khi được yêu cầu rõ ràng.
- Làm cho mọi phần đều nổi bật về mặt thị giác.
- Tạo các thành phần mới khi đã có một thành phần tương tự sẵn có.
CLAUDE.md có nên import DESIGN.md không?
Claude Code hỗ trợ import các tệp vào CLAUDE.md bằng cú pháp @path. Các hướng dẫn được import sẽ trở thành một phần ngữ cảnh của dự án.
Một cách thông thường là sử dụng import trực tiếp:
-- File CLAUDE.md --
## Hệ thống thiết kế
@DESIGN.md
Nhưng tôi không khuyên bạn làm theo cách này.
Với hướng dẫn này, tài liệu thiết kế sẽ luôn được tải vào ngữ cảnh dự án mọi lúc mọi nơi, ngay cả khi Claude không cần đến nó (ví dụ: khi đang sửa logic backend hoặc viết test tự động cho backend, và DESIGN.md sẽ làm quá tải cửa sổ ngữ cảnh bằng những chi tiết không liên quan).
Thiết lập tốt hơn cho hầu hết các dự án là một hướng dẫn có điều kiện:
-- File CLAUDE.md --
## Hệ thống thiết kế
Đối với bất kỳ tác vụ nào làm thay đổi UI, styling, tương tác, khả năng tiếp cận hoặc hành vi đáp ứng:
1. Đọc `DESIGN.md` trước khi triển khai.
2. Coi nó là nguồn sự thật.
3. Kiểm tra các thành phần hiện có trước khi tạo mới.
Chỉ sử dụng import @DESIGN.md trực tiếp khi:
– Dự án chủ yếu là frontend hoặc bản mẫu thiết kế (design prototype).
– Tài liệu cực kỳ ngắn gọn (nhưng điều này hiếm khi xảy ra nếu bạn đưa thông tin design system vào).
Sử dụng hướng dẫn có điều kiện để đọc nó khi:
– DESIGN.md rất chi tiết hoặc dài.
– Kho lưu trữ (repository) chứa lượng lớn công việc backend.
– Ngữ cảnh thiết kế không liên quan đến nhiều tác vụ.
Cấu trúc dự án được khuyến nghị
Cuối cùng, tôi muốn chia sẻ một ảnh chụp cấu trúc dự án chứa cả hai tệp để bạn có thể hình dung vị trí đặt chúng:
project/
├── CLAUDE.md
├── DESIGN.md
├── README.md
├── package.json
├── src/
│ ├── app/
│ ├── components/
│ ├── features/
│ └── styles/
└── docs/
├── architecture.md
└── workflows.md
