Mở đầu — vì sao bài này quan trọng
Hãy tưởng tượng bạn vừa dành ba tháng trời để xây dựng một design system hoàn chỉnh trong Figma: hàng trăm component, variants, design tokens, color system, typography scale — tất cả đều gọn gàng và đẹp đẽ. Nhưng rồi một tuần sau, một bạn developer mới vào team nhắn tin hỏi: "Anh ơi, cái button 'destructive' này khi nào thì dùng ạ? Còn nút này với nút kia khác nhau chỗ nào?". Rồi một bạn designer khác vô tình tạo lại một component đã có sẵn vì không biết nó tồn tại. Rồi bên marketing tự chế màu mới vì không ai nói cho họ biết palette chính thức là gì.
Đó chính là khoảnh khắc bạn nhận ra: một design system không có documentation thì chỉ là một thư viện file, không phải một hệ thống. Component library trả lời câu hỏi "cái gì" (what) — đây là button, đây là màu primary. Nhưng documentation mới trả lời câu hỏi "khi nào" (when) và "tại sao" (why) — khi nào dùng button primary thay vì secondary, tại sao khoảng cách này là 16px chứ không phải 20px, quy tắc nào không được phá vỡ.
Trong toàn bộ khóa học này, chúng ta đã đi qua rất nhiều lớp: từ visual hierarchy, spacing system, đến components, variants, design tokens và Figma variables. Bài 36 này là lớp cuối cùng nối tất cả lại — lớp documentation. Đây là thứ biến một bộ file rời rạc thành một sản phẩm mà cả team (designer, developer, PM, QA, thậm chí cả stakeholder) có thể tự phục vụ mà không cần hỏi bạn liên tục. Với một UI designer đang muốn lên senior hoặc bước vào Design Ops, khả năng viết documentation tốt là một trong những kỹ năng phân biệt rõ nhất giữa người "làm màn hình" và người "xây hệ thống".
Khái niệm cốt lõi
Documentation layer là gì và không phải là gì
Documentation trong design system là lớp giải thích và hướng dẫn đi kèm mỗi thành phần của hệ thống. Nó không thay thế component library — nó bổ sung ngữ cảnh cho library. Một mục documentation tốt cho một component thường gồm:
- Mô tả (Description): Component này là gì, giải quyết vấn đề gì.
- Anatomy: Các phần cấu thành (ví dụ: button gồm container, label, icon tùy chọn).
- Usage guidelines — Do & Don't: Khi nào nên dùng, khi nào không, kèm ví dụ đúng/sai trực quan.
- Props / API: Các thuộc tính có thể tùy chỉnh (variant, size, state, disabled...).
- States: Default, hover, focus, active, disabled, loading.
- Accessibility notes: Contrast tối thiểu, keyboard behavior, ARIA cần thiết.
- Code reference: Tên component trong code, cách import (nếu có).
Ba tầng nội dung của một docs site
Một docs site trưởng thành thường được tổ chức theo ba tầng, đi từ trừu tượng đến cụ thể:
- Foundations (Nền tảng): Color, typography, spacing, elevation, motion, iconography, grid. Đây là các quyết định gốc, thường gắn với design tokens. Ví dụ: giải thích tại sao chọn spacing scale theo hệ số 8, bảng màu semantic và ý nghĩa của từng token.
- Components (Thành phần): Từng UI component với anatomy, states, guidelines, props.
- Patterns (Mẫu tổ hợp): Cách ghép nhiều component thành giải pháp — ví dụ form pattern, empty state pattern, navigation pattern. Đây là nơi documentation thể hiện "cách suy nghĩ" chứ không chỉ "cách dùng".
Hai lựa chọn công cụ chính: Zeroheight vs Storybook + MDX
Đây là hai trường phái phổ biến nhất, và lựa chọn giữa chúng phản ánh văn hóa team của bạn.
Zeroheight là công cụ no-code chuyên cho documentation design system. Điểm mạnh:
- Tích hợp trực tiếp với Figma: bạn kéo frame/component từ Figma vào và nó tự cập nhật khi design thay đổi.
- Không cần biết code — designer tự viết và xuất bản được.
- Giao diện WYSIWYG, dễ tạo trang đẹp nhanh, có hỗ trợ versioning và permission.
- Phù hợp khi "source of truth" của bạn nằm ở phía Figma và người viết docs chủ yếu là designer.
Storybook + MDX là trường phái "docs sống cùng code". Storybook là môi trường chạy component thực (component playground), còn MDX cho phép viết Markdown xen lẫn component React/Vue sống động. Điểm mạnh:
- Documentation hiển thị chính component code thật, không phải ảnh chụp — nên không bao giờ lệch với thứ developer thực sự dùng.
- Có addon kiểm tra accessibility, responsive, interaction test ngay trong docs.
- Miễn phí, open-source, developer rất thích.
Nhiều team lớn dùng cả hai: Zeroheight cho tầng Foundations + Patterns + guidelines (đối tượng đọc rộng), Storybook cho tầng Components chi tiết (đối tượng developer). Ngoài ra còn Supernova (mạnh về đồng bộ tokens), Notion/Confluence (rẻ, linh hoạt nhưng thủ công), hay tự build docs bằng Docusaurus.
Nguyên tắc vàng: docs phải dễ cập nhật hơn design
Một sự thật phũ phàng: documentation lỗi thời còn tệ hơn không có documentation, vì nó khiến người ta tin vào thông tin sai. Vì vậy tiêu chí quan trọng nhất khi chọn công cụ không phải là "trang có đẹp không" mà là "cập nhật một thay đổi mất bao nhiêu công sức". Nếu mỗi lần đổi màu bạn phải sửa ở 5 chỗ, docs của bạn sẽ chết trong vòng vài tháng.
Tình huống thực tế
Tình huống 1 — Startup fintech Việt Nam và cái giá của việc không có docs
Một startup fintech ở TP.HCM (gọi là VíXanh) có 4 designer và 12 developer, phát triển một ví điện tử. Họ có một Figma library khá tốt nhưng không có documentation. Kết quả sau 6 tháng: trong sản phẩm có 7 sắc thái xanh lá khác nhau cho cùng ý nghĩa "thành công", 3 kiểu button "primary" với border-radius lệch nhau (8px, 10px, 12px), và mỗi màn hình xác nhận giao dịch lại có spacing khác nhau.
Vấn đề không phải là library thiếu — màu primary có sẵn trong Figma. Vấn đề là không ai biết quy tắc: dùng token success khi nào, khác gì positive, khi nào được tạo màu mới. Mỗi khi có thắc mắc, mọi người nhắn thẳng lead designer, và bạn ấy trở thành "nút cổ chai" trả lời câu hỏi cả ngày.
Họ giải quyết bằng cách dựng một trang Zeroheight trong 3 tuần, tập trung trước vào Foundations (color semantic + spacing + button guidelines với Do/Don't rõ ràng). Sau đó, số câu hỏi gửi cho lead designer giảm khoảng 60%, và trong sprint tiếp theo họ dọn được về đúng 1 màu success duy nhất.
Bài học: Documentation không phải để làm đẹp, nó để giải phóng con người khỏi việc trả lời cùng một câu hỏi lặp đi lặp lại. Bắt đầu từ đúng chỗ đang gây đau nhất (ở đây là color và button), đừng cố viết hết mọi thứ.
Tình huống 2 — Team sản phẩm dùng Storybook để chống lệch design-code
Một công ty SaaS quy mô vừa (khoảng 40 người, có văn phòng ở Singapore và Đà Nẵng) gặp vấn đề ngược lại: họ có docs đẹp trên Notion, nhưng docs mô tả một đằng, component thực tế render một nẻo. Ví dụ, docs ghi input field có padding 12px, nhưng code thực tế là 10px vì developer sửa gấp mà quên báo. QA test theo docs, báo bug, developer bảo "code đúng rồi", cãi nhau mất cả buổi.
Họ chuyển tầng Components sang Storybook + MDX. Vì docs render chính component code thật, cái người đọc thấy trên docs chính xác là cái chạy trong app. Họ thêm addon a11y để kiểm tra contrast tự động và addon interaction để demo các state. Kết quả: những tranh cãi kiểu "docs nói vậy nhưng code khác" gần như biến mất, vì giờ chỉ còn một nguồn sự thật.
Điều thú vị là họ không vứt bỏ Notion. Notion vẫn giữ phần "tư duy" — nguyên tắc thiết kế, patterns, quyết định lịch sử — vì những thứ đó không phải là code và không cần render.
Bài học: Khi độ chính xác kỹ thuật quan trọng (đặc biệt với team engineering-driven), hãy để component tự nói cho chính nó qua playground sống. Docs dạng ảnh tĩnh luôn có nguy cơ lệch.
Tình huống 3 — "Design system" một người và sự cám dỗ overdocument
Một designer freelance nhận làm design system cho một agency nhỏ. Bạn ấy hào hứng viết documentation cực kỳ chi tiết cho tất cả component — kể cả những cái chỉ dùng một lần — với đầy đủ anatomy, 6 state, accessibility notes dài dòng. Mất 5 tuần. Nhưng khi bàn giao, agency chỉ có 2 người dùng và họ... không đọc, vì quá nhiều.
Sau đó bạn ấy làm lại theo hướng "documentation vừa đủ": mỗi component chỉ có 3 dòng mô tả + 1 ví dụ Do + 1 ví dụ Don't + tên props. Toàn bộ mất 1 tuần và được dùng thật.
Bài học: Mức độ documentation phải tương xứng với quy mô team và độ phức tạp. Với team nhỏ, documentation quá chi tiết là lãng phí và không ai đọc. Viết vừa đủ để giải quyết vấn đề thực, rồi mở rộng khi có nhu cầu.
Hướng dẫn từng bước
Đây là quy trình thực tế để dựng documentation cho một design system từ con số 0.
Bước 1 — Xác định đối tượng đọc và câu hỏi họ hay hỏi. Trước khi viết chữ nào, liệt kê: ai sẽ đọc docs này (designer, dev, PM, QA)? Họ đang hỏi bạn những câu gì lặp lại nhiều nhất? Chính những câu hỏi đó là mục lục đầu tiên của bạn.
Bước 2 — Chọn công cụ theo văn hóa team, không theo trend. Nếu team designer-driven và source of truth ở Figma → Zeroheight. Nếu team engineering-driven và cần độ chính xác code → Storybook + MDX. Nếu budget = 0 và team nhỏ → Notion/Confluence trước, nâng cấp sau. Đừng chọn công cụ phức tạp chỉ vì công ty lớn dùng nó.
Bước 3 — Dựng khung ba tầng. Tạo cấu trúc Foundations → Components → Patterns. Điền phần khung (mục lục, tiêu đề trang) trước khi viết nội dung. Có bộ xương giúp bạn không lạc.
Bước 4 — Viết Foundations trước. Đây là phần dùng chung nhiều nhất và ít thay đổi nhất, nên đầu tư ở đây có ROI cao nhất. Với mỗi token nhóm (color, spacing, type), giải thích tên, giá trị, và khi nào dùng — đừng chỉ liệt kê giá trị.
Bước 5 — Viết một component mẫu thật tốt làm template. Chọn một component quan trọng (thường là Button). Viết đầy đủ: description, anatomy, states, Do/Don't, props. Đây trở thành khuôn mẫu để mọi component sau copy theo, đảm bảo tính nhất quán.
Bước 6 — Kết nối docs với source of truth. Trong Zeroheight, link component tới Figma library để tự đồng bộ. Trong Storybook, docs render trực tiếp component code. Mục tiêu: giảm số nơi bạn phải sửa khi có thay đổi.
Bước 7 — Thiết lập quy trình cập nhật. Quy định rõ: mỗi khi thêm/sửa component thì cập nhật docs là một phần của "definition of done". Không có quy trình, docs sẽ chết.
Bước 8 — Công bố và onboarding. Gửi link cho cả team, làm một buổi walkthrough 20 phút. Docs không được dùng nếu không ai biết nó tồn tại.
Lỗi thường gặp & mẹo
Lỗi 1 — Viết docs như từ điển kỹ thuật, thiếu "khi nào" và "tại sao". Rất nhiều docs chỉ liệt kê thuộc tính mà không giải thích ngữ cảnh sử dụng. Người đọc vẫn không biết chọn component nào. Mẹo: mỗi component bắt buộc có phần "When to use" và cặp Do/Don't trực quan.
Lỗi 2 — Docs lệch với design/code. Đây là kẻ giết design system số một. Mẹo: ưu tiên công cụ tự đồng bộ (Zeroheight linked với Figma, Storybook render code thật). Giảm tối đa thông tin phải nhập tay hai lần.
Lỗi 3 — Overdocument. Viết quá nhiều đến mức không ai đọc và bạn không đủ sức duy trì. Mẹo: áp dụng nguyên tắc "documentation vừa đủ" — bắt đầu tối giản, mở rộng theo nhu cầu thật.
Lỗi 4 — Không có người chủ (owner) rõ ràng. Docs không ai chịu trách nhiệm sẽ thối rữa. Mẹo: chỉ định một owner và đưa việc cập nhật docs vào Definition of Done của mọi thay đổi component.
Lỗi 5 — Chỉ có ảnh chụp màn hình. Screenshot đóng băng tại thời điểm chụp, design đổi là ảnh sai. Mẹo: dùng embed/live component thay vì ảnh tĩnh bất cứ khi nào có thể.
Mẹo bổ sung: Thêm phần "Changelog" cho mỗi trang để người đọc biết gì vừa thay đổi. Thêm phần "Contact / How to contribute" để người ta biết hỏi ai và đề xuất thế nào. Dùng ngôn ngữ thống nhất với naming convention của hệ thống (đã học ở Bài 34) để docs và library gọi cùng một thứ bằng cùng một tên.
Bài tập thực hành
- Chọn công cụ có lý do: Với một team giả định gồm 3 designer và 8 developer, engineering rất mạnh và muốn docs không bao giờ lệch code, hãy quyết định dùng Zeroheight, Storybook + MDX, hay kết hợp. Viết 3–4 câu giải thích lựa chọn.
- Viết trang documentation cho một component: Chọn component Button từ những gì bạn đã dựng trong khóa học. Viết đầy đủ: (a) Description, (b) Anatomy, (c) 4 states, (d) 2 ví dụ Do và 2 ví dụ Don't, (e) danh sách props với giá trị hợp lệ. Cố gắng làm phần "When to use" thật rõ.
- Audit một docs thật: Vào một trong các design system công khai (Material Design, Atlassian Design System, hoặc Shopify Polaris). Chọn một component, phân tích: họ tổ chức thông tin theo tầng nào? Phần Do/Don't của họ thuyết phục ra sao? Có gì bạn muốn áp dụng và có gì bạn thấy thừa?
- Thiết kế quy trình cập nhật: Viết ra một quy trình 3–5 bước mô tả điều gì phải xảy ra với documentation mỗi khi một component được thêm hoặc sửa, sao cho docs không bao giờ lỗi thời.
Tóm tắt
Documentation là lớp biến một tập hợp file Figma và component thành một hệ thống mà cả team có thể tự phục vụ. Component library trả lời "cái gì"; documentation trả lời "khi nào" và "tại sao". Một docs site trưởng thành được tổ chức ba tầng — Foundations, Components, Patterns — và mỗi component nên có mô tả, anatomy, states, guidelines Do/Don't, props và accessibility notes.
Về công cụ, hai trường phái chính là Zeroheight (no-code, tích hợp Figma, hợp team designer-driven) và Storybook + MDX (docs render component code thật, hợp team engineering-driven cần độ chính xác). Nhiều team lớn kết hợp cả hai. Tiêu chí chọn quan trọng nhất không phải độ đẹp mà là độ dễ cập nhật, vì docs lỗi thời còn tệ hơn không có docs.
Cuối cùng, hãy nhớ ba điều từ các tình huống thực tế: bắt đầu từ chỗ đau nhất (thường là Foundations và Button), ưu tiên công cụ tự đồng bộ để chống lệch, và viết vừa đủ với quy mô team. Một design system tốt không phải là cái có nhiều component nhất, mà là cái mà người mới có thể tự hiểu và dùng đúng — và đó chính là công việc của documentation.