Mở đầu — vì sao bài này quan trọng
Hãy tưởng tượng bạn vừa cùng team dựng xong một design system khá hoành tráng: hàng trăm component trong Figma, token màu chỉn chu, variant đầy đủ. Ai cũng tự hào. Ba tháng sau, một bạn designer mới vào team mở file lên, nhìn vào component Button và bối rối: có tới năm kiểu nút khác nhau, không rõ cái nào dùng cho hành động chính, cái nào dùng cho hành động phụ, và cái Button/Ghost/Danger kia thì… để làm gì? Bạn ấy đoán mò, chọn đại một cái, và thế là sản phẩm bắt đầu xuất hiện những nút "lệch chuẩn" một cách âm thầm.
Đó chính là vấn đề mà documentation (tài liệu hóa) giải quyết. Một design system không có tài liệu giống như một thư viện sách không có nhãn gáy và không có thẻ mục lục: sách thì có đó, nhưng không ai biết tìm cái mình cần ở đâu, và càng không biết cách dùng cho đúng.
Trong các bài trước của khóa học, chúng ta đã học cách xây dựng component (Bài 13), tư duy Atomic Design (Bài 14), nền tảng của một design system (Bài 15), kiến trúc token (Bài 16) và theming đa thương hiệu (Bài 17). Tất cả những thứ đó là "phần cứng". Bài 18 này nói về "phần mềm vận hành" — thứ biến một bộ component thành một hệ thống mà cả team thực sự dùng được. Documentation không phải việc làm cho đẹp hồ sơ. Nó là yếu tố quyết định một design system sẽ được adoption (được áp dụng rộng rãi) hay bị bỏ xó.
Mục tiêu của bài: bạn sẽ biết chính xác cần tài liệu hóa những gì cho mỗi component, cấu trúc tài liệu ra sao để vừa đủ — không thiếu, không thừa — và quy trình viết tài liệu mà không tốn cả tháng trời.
Khái niệm cốt lõi
Documentation là gì và không phải là gì
Documentation trong design system là tập hợp các hướng dẫn mô tả cái gì có sẵn, khi nào dùng, dùng như thế nào cho mỗi thành phần trong hệ thống. Nó là cầu nối giữa designer tạo ra component và những người tiêu thụ chúng: designer khác, developer, product manager, thậm chí cả người làm content.
Documentation không phải là bản sao chép lại file Figma. Nếu tài liệu chỉ chụp lại đúng những gì người ta đã nhìn thấy trong Figma thì nó vô dụng. Giá trị của tài liệu nằm ở phần không nhìn thấy được chỉ bằng mắt: ý định thiết kế, ngữ cảnh sử dụng, và đặc biệt là ranh giới — khi nào KHÔNG nên dùng.
Cấu trúc tài liệu cho mỗi component
Đây là phần xương sống của bài. Một trang tài liệu component chuẩn nên có sáu phần. Hãy ghi nhớ chúng như một checklist:
1. Name + Screenshot (Tên + Ảnh minh họa). Mỗi component cần một cái tên rõ ràng, nhất quán với tên trong Figma và trong code. Nếu trong Figma tên là Button/Primary mà trong tài liệu lại gọi là "Nút chính" còn developer gọi là BtnMain, bạn vừa tạo ra ba ngôn ngữ cho cùng một thứ. Kèm theo tên là ít nhất một ảnh hiển thị component ở trạng thái mặc định, lý tưởnh là ảnh "live" lấy thẳng từ component thật để không bao giờ lỗi thời.
2. Description (Mô tả). Một đến hai câu trả lời câu hỏi "component này là gì và làm gì". Ví dụ: "Button kích hoạt một hành động ngay lập tức khi người dùng nhấn vào, ví dụ gửi form, lưu thay đổi, hoặc mở một luồng mới." Mô tả tốt phải nói về chức năng, không phải về hình thức. "Một nút màu xanh bo góc 8px" là mô tả tồi; "nút kích hoạt hành động chính" mới là mô tả tốt.
3. Usage (Cách dùng — khi nào DÙNG và khi nào KHÔNG dùng). Đây là phần quan trọng nhất và thường bị bỏ qua. Phần Usage cần nói rõ:
- When to use: ngữ cảnh phù hợp. "Dùng Primary Button cho hành động quan trọng nhất trên màn hình — và chỉ một cái mỗi màn hình."
- When NOT to use: ranh giới. "KHÔNG dùng Button cho hành động điều hướng đơn thuần (chuyển trang) — hãy dùng Link." Phần "không dùng" này ngăn chặn 80% các trường hợp lạm dụng component.
5. States (Các trạng thái). Default, hover, focus, active, disabled, loading. Người tiêu thụ component cần biết component phản ứng ra sao khi tương tác — đặc biệt là trạng thái disabled và loading vì chúng dễ bị quên khi handoff cho developer.
6. Props / Anatomy (Cấu tạo & thuộc tính). Với tài liệu nhắm tới developer, đây là phần liệt kê các thuộc tính có thể tùy chỉnh (size, icon, label, variant). Với tài liệu nhắm tới designer, "anatomy" mô tả các bộ phận cấu thành: vùng label, vùng icon, padding, khoảng cách tối thiểu.
Ba tầng tài liệu: Foundations, Components, Patterns
Một design system trưởng thành thường có tài liệu chia ba tầng:
- Foundations (Nền tảng): màu, typography, spacing, token, grid, iconography. Đây là các quy tắc gốc.
- Components (Thành phần): từng component đơn lẻ với cấu trúc 6 phần ở trên.
- Patterns (Mẫu): cách kết hợp nhiều component để giải quyết một bài toán lặp lại — ví dụ "mẫu form đăng nhập", "mẫu empty state", "mẫu xác nhận xóa". Patterns là tầng dễ bị bỏ quên nhất nhưng lại tạo ra nhiều giá trị nhất, vì nó dạy người dùng cách ghép chứ không chỉ cách dùng từng mảnh.
"Single source of truth" — một nguồn sự thật duy nhất
Nguyên tắc vàng: tài liệu phải là nguồn sự thật duy nhất. Nếu có ba nơi cùng mô tả Button (một file Figma, một trang Notion, một file PDF gửi qua email), chắc chắn sẽ có lúc chúng mâu thuẫn nhau, và khi đó không ai biết tin cái nào. Hãy chọn MỘT nơi làm chuẩn và mọi nơi khác chỉ trỏ về đó.
Tình huống thực tế
Tình huống 1 — Tiki và bài học "component không tài liệu"
Giả định một bối cảnh quen thuộc ở các công ty công nghệ Việt Nam quy mô lớn như Tiki. Đội thiết kế khoảng 12 người, làm trên Figma với một thư viện component dùng chung. Ban đầu mọi thứ ổn vì cả team ngồi cạnh nhau, có gì không rõ thì hỏi miệng. Khi công ty mở rộng, có thêm team ở chi nhánh, các bạn designer mới không còn ai để "hỏi miệng" nữa.
Hậu quả cụ thể: component Tag (thẻ nhãn) có một variant Tag/Promo được tạo riêng cho campaign khuyến mãi Tết, với màu đỏ đặc trưng. Không có tài liệu nói rõ "chỉ dùng cho khuyến mãi giới hạn thời gian". Một bạn mới thấy đẹp, dùng Tag/Promo cho cả nhãn "Hàng chính hãng" trên trang sản phẩm thông thường. Kết quả là màu đỏ "giảm giá" xuất hiện tràn lan, làm loãng tín hiệu khuyến mãi thật. Mất hai sprint review mới phát hiện và sửa.
Diễn giải: vấn đề không nằm ở component — Tag/Promo được thiết kế hoàn hảo. Vấn đề nằm ở chỗ thiếu phần Usage / "When NOT to use". Một dòng tài liệu — "Tag/Promo chỉ dùng cho ưu đãi có giới hạn thời gian; không dùng cho nhãn thuộc tính sản phẩm cố định" — đã đủ ngăn toàn bộ sự cố.
Bài học: tài liệu Usage không phải để khoe component đẹp; nó tồn tại để chặn việc dùng sai. Mỗi khi tạo một variant có ngữ cảnh đặc biệt, hãy ghi ngay ranh giới sử dụng của nó.
Tình huống 2 — Grab và mô hình "tài liệu sống đi kèm component"
Grab vận hành một design system lớn (nội bộ gọi là hệ thống dùng chung cho nhiều quốc gia Đông Nam Á). Bài toán của họ: hàng trăm designer và developer ở Singapore, Việt Nam, Indonesia, Malaysia cùng tiêu thụ chung một bộ component, nói nhiều ngôn ngữ, múi giờ khác nhau, không thể "hỏi miệng".
Cách tiếp cận: họ không tách tài liệu ra một nơi riêng rồi cập nhật thủ công. Thay vào đó, tài liệu được đặt ngay cạnh component — mỗi component trong thư viện đều có một trang docs đi kèm, và screenshot trong tài liệu được render trực tiếp từ chính component thật. Khi component đổi, ảnh tự đổi theo. Phần Usage và Variants được viết một lần, review bởi cả design lẫn engineering, rồi khóa lại làm chuẩn.
Một con số minh họa cho giá trị: với một team phân tán mà mỗi câu hỏi "component này dùng sao?" tốn trung bình 15–20 phút chờ trả lời qua chat (do lệch múi giờ), việc có tài liệu tự phục vụ giúp loại bỏ hàng trăm câu hỏi mỗi tuần. Quy ra thời gian, đó là nhiều ngày công được trả lại cho việc thiết kế thực sự.
Diễn giải: điểm mấu chốt là tài liệu sống (living documentation) — tài liệu gắn liền với component đến mức không thể lỗi thời. Khi tài liệu nằm tách rời (một file PDF, một trang slide cũ), nó bắt đầu "chết" ngay từ phút component đầu tiên thay đổi.
Bài học: ưu tiên cơ chế khiến tài liệu khó lỗi thời hơn là cố gắng nhớ cập nhật thủ công. Screenshot lấy từ component thật, ví dụ embed bằng instance thật, mô tả gắn ngay trong file — tất cả đều giảm "độ trôi" giữa tài liệu và thực tế.
Tình huống 3 — Startup fintech 8 người và bài học "đừng tài liệu hóa quá đà"
Một startup fintech ở TP.HCM, đội thiết kế chỉ 2 người trong tổng số 8 nhân sự. Bạn lead design đọc về Material Design, Polaris (Shopify), thấy tài liệu của họ đồ sộ và quyết định làm tương tự: viết tài liệu chi tiết cho từng component với cả lý thuyết, lịch sử thiết kế, mười ví dụ Do/Don't mỗi cái.
Sau ba tuần, bạn ấy mới tài liệu hóa được… 6 component, trong khi sản phẩm cần ra mắt gấp. Tệ hơn, các tài liệu công phu đó gần như không ai đọc vì team quá nhỏ — hai designer ngồi cạnh nhau vẫn hỏi miệng nhanh hơn.
Diễn giải: tài liệu hóa có chi phí. Với một team 8 người, mức độ tài liệu phù hợp khác hẳn team 120 người. Họ chỉ cần phần tối thiểu: tên, một câu mô tả, và một dòng Usage "dùng khi nào". Phần Variants chỉ cần liệt kê tên, không cần luận giải dài dòng.
Bài học: lượng tài liệu phải tỉ lệ thuận với quy mô và độ phân tán của team. Tài liệu là để giải quyết vấn đề giao tiếp; nếu team chưa có vấn đề đó, tài liệu quá chi tiết chỉ là gánh nặng. Hãy bắt đầu mỏng, dày dần theo nhu cầu thực tế.
Hướng dẫn từng bước
Đây là quy trình tài liệu hóa một component từ đầu, áp dụng được ngay:
Bước 1 — Chọn nơi đặt tài liệu (single source of truth). Quyết định MỘT nơi: có thể là trang docs ngay trong Figma (dùng tính năng "page" để viết mô tả cạnh component), hoặc một công cụ như Zeroheight, Notion, Storybook. Tiêu chí: nơi mà cả designer lẫn developer đều mở được, và càng gần component càng tốt.
Bước 2 — Lập template cho trang component. Tạo một khuôn mẫu có sẵn 6 mục: Name + Screenshot, Description, Usage (When / When NOT), Variants, States, Anatomy/Props. Có template thì mỗi component mới chỉ việc "điền vào chỗ trống", đảm bảo nhất quán và nhanh.
Bước 3 — Bắt đầu với component dùng nhiều nhất. Đừng tài liệu hóa theo thứ tự bảng chữ cái. Hãy bắt đầu từ Button, Input, Card, Typography — những thứ bị dùng (và dùng sai) nhiều nhất. Tài liệu cho 10 component cốt lõi giải quyết 90% nhu cầu thực tế.
Bước 4 — Viết Description bằng ngôn ngữ chức năng. Trả lời "component này làm gì cho người dùng cuối", không mô tả màu sắc hay kích thước.
Bước 5 — Viết Usage với cả hai chiều. Luôn viết "When to use" và "When NOT to use". Nếu chỉ viết được một dòng, hãy ưu tiên "When NOT to use" vì nó ngăn lỗi tốt hơn.
Bước 6 — Dùng screenshot "live". Lấy ảnh từ chính instance component thật, không vẽ lại. Nếu công cụ hỗ trợ embed instance, càng tốt.
Bước 7 — Review chéo với developer. Cho ít nhất một developer đọc thử trang tài liệu và thử áp dụng. Nếu họ hiểu mà không cần hỏi thêm, tài liệu đạt. Nếu họ phải nhắn tin hỏi, đó là chỗ tài liệu còn thiếu.
Bước 8 — Đặt lịch rà soát định kỳ. Tài liệu trôi theo thời gian. Mỗi quý, rà lại các trang tài liệu của component đã thay đổi. Tốt nhất là gắn việc cập nhật tài liệu thành một bước bắt buộc trong quy trình mỗi khi sửa component (làm cho nó là một phần của "definition of done").
Lỗi thường gặp & mẹo
Lỗi 1: Tài liệu chỉ mô tả "cái gì" mà quên "khi nào KHÔNG dùng". Đây là lỗi phổ biến nhất. Phần "When NOT to use" mới là nơi tạo ra giá trị thật. Mẹo: với mỗi component, hãy nghĩ ra ít nhất một cách người ta dễ dùng sai nó, rồi ghi rõ "đừng làm vậy".
Lỗi 2: Tài liệu lỗi thời vì tách rời component. Khi tài liệu là một file PDF/slide riêng, nó "chết" ngay khi component đổi. Mẹo: đặt tài liệu càng gần component càng tốt; dùng screenshot live thay vì ảnh tĩnh tự chụp.
Lỗi 3: Tài liệu hóa quá đà cho team nhỏ. Viết tài liệu đồ sộ trong khi team 5 người ngồi cạnh nhau là lãng phí. Mẹo: bắt đầu với tài liệu tối thiểu (tên + 1 câu mô tả + 1 dòng usage), dày dần khi team lớn lên.
Lỗi 4: Tên không nhất quán giữa Figma, tài liệu và code. Mẹo: thống nhất một quy ước đặt tên duy nhất, dùng chung cho cả ba nơi. Một component, một cái tên.
Lỗi 5: Quên đối tượng người đọc. Designer cần "anatomy", developer cần "props", PM cần "khi nào dùng". Mẹo: viết Usage cho mọi người, nhưng có thể tách phần kỹ thuật (props) ra để developer xem riêng.
Mẹo vàng: tài liệu tốt nhất là tài liệu được đọc, không phải tài liệu đầy đủ nhất. Hãy đo lường bằng số câu hỏi lặp lại giảm đi, không phải bằng số trang viết ra.
Bài tập thực hành
Bài 1 — Tài liệu hóa một component. Chọn component Button trong file design system của bạn (hoặc tự dựng một Button đơn giản). Viết một trang tài liệu đầy đủ 6 phần: Name + Screenshot, Description (1–2 câu, ngôn ngữ chức năng), Usage (ít nhất 1 dòng "when to use" và 1 dòng "when NOT to use"), Variants (liệt kê và giải thích), States, Anatomy. Giới hạn: toàn bộ trang gói gọn trong một màn hình cuộn — buộc bạn phải súc tích.
Bài 2 — Săn ranh giới sử dụng. Lấy 3 component bất kỳ trong sản phẩm bạn đang làm. Với mỗi cái, viết ra 2 trường hợp người ta DỄ dùng sai. Đây chính là nguyên liệu cho phần "When NOT to use".
Bài 3 — Kiểm tra "single source of truth". Liệt kê tất cả những nơi hiện đang chứa thông tin về design system của bạn (Figma, Notion, Slack, email, đầu của một bạn senior nào đó…). Đánh dấu nơi nào nên là nguồn chuẩn duy nhất, và lập kế hoạch để mọi nơi khác trỏ về đó.
Bài 4 (nâng cao) — Test với người thật. Đưa trang tài liệu Button ở Bài 1 cho một đồng nghiệp (lý tưởng là developer) chưa từng dùng component này. Yêu cầu họ áp dụng nó vào một màn hình giả định mà không hỏi bạn câu nào. Ghi lại mọi chỗ họ phải đoán hoặc làm sai — đó chính là lỗ hổng tài liệu cần vá.
Tóm tắt
Documentation là thứ biến một bộ component rời rạc thành một design system thực sự được dùng. Những điểm cần nhớ:
- Mỗi component cần tài liệu theo 6 phần: Name + Screenshot, Description, Usage (when / when NOT), Variants, States, Anatomy/Props.
- Phần Usage, đặc biệt là "khi nào KHÔNG dùng", là nơi tạo ra nhiều giá trị nhất vì nó ngăn lạm dụng — như bài học từ tình huống
Tag/Promo. - Ưu tiên tài liệu sống gắn liền component (screenshot live, đặt cạnh component) để tránh lỗi thời — như cách một hệ thống phân tán quy mô Grab vận hành.
- Lượng tài liệu phải tỉ lệ với quy mô team: team nhỏ chỉ cần tối thiểu, đừng tài liệu hóa quá đà.
- Luôn có một nguồn sự thật duy nhất, đặt tên nhất quán giữa Figma — tài liệu — code, và rà soát định kỳ.