Storybook hay tài liệu tĩnh cho Design System

Chốt nhanh

Nếu đội kỹ thuật dưới 5 người và giao tiếp trực tiếp được, file tĩnh như Figma hoặc Notion là đủ. Storybook thực sự có giá trị khi đội từ 5 người trở lên, component có nhiều trạng thái phức tạp, hoặc Anh Chị muốn tích hợp kiểm tra tự động vào quy trình build. Tài liệu không được dùng thì không tồn tại, nên chọn hình thức nào đội kỹ thuật thực sự mở ra mỗi ngày.

Storybook (công cụ tài liệu tương tác cho component, cho phép xem và thao tác component ở các trạng thái khác nhau ngay trong trình duyệt) không phải lúc nào cũng là lựa chọn đúng. Quyết định phụ thuộc vào một câu hỏi thực tế: đội kỹ thuật của Anh Chị có thực sự mở tài liệu đó không, hay chỉ hỏi trực tiếp nhau?

Tài liệu tốt nhất là tài liệu gần code nhất

Nguyên tắc cốt lõi: tài liệu hiệu quả là tài liệu được cập nhật bắt buộc cùng với code, không phải tài liệu viết một lần rồi để đó. Storybook thỏa mãn điều này hơn file tĩnh vì story (đơn vị tài liệu trong Storybook) nằm ngay trong codebase, developer thấy ngay khi mở project. File tĩnh như PDF hay Notion nằm ở chỗ khác, cần ý chí chủ động để cập nhật, và thường bị bỏ lại phía sau.

Tuy nhiên, lợi thế đó chỉ có giá trị khi đội kỹ thuật thực sự viết và bảo trì story. Storybook cài mà không ai viết story mới thì tệ hơn không có Storybook, vì Anh Chị có thêm một thứ cần bảo trì và lại trở thành tài liệu sai.

Khi nào cần Storybook, khi nào file tĩnh là đủ

Chọn Storybook khi:

Đội kỹ thuật từ 5 người trở lên, không giao tiếp trực tiếp được mọi lúc.
Component có nhiều trạng thái cần xem riêng lẻ: loading, error, empty, disabled, hover. Storybook cho phép chuyển giữa các trạng thái trong vài giây thay vì phải tái tạo điều kiện trong sản phẩm thật.
Anh Chị muốn tích hợp visual regression testing (kiểm tra tự động xem component có thay đổi giao diện ngoài ý muốn không) vào CI/CD (quy trình tự động build và kiểm tra code).
Khách hàng hoặc QA cần xem component mà không có quyền vào Figma hoặc môi trường dev.

File tĩnh đủ dùng khi:

Team dưới 5 người, hỏi nhau trực tiếp nhanh hơn tra tài liệu.
Sản phẩm đơn giản, component ít variant, ít trạng thái cần kiểm tra riêng lẻ.
Đội kỹ thuật không có thời gian để viết và bảo trì story đúng cách.

Lỗi thường gặp khi dùng Storybook

Cài xong không viết story mới. Component mới ra đời mà không có story, Storybook nhanh chóng thành tài liệu lỗi thời. Đây là lỗi phổ biến nhất.
Chỉ viết happy path. Story chỉ có trạng thái bình thường, bỏ qua loading, error, edge case. Mất đi giá trị chính của công cụ.
Không đưa Storybook vào quy trình review. Designer không biết xem, developer không bắt buộc cập nhật, Storybook trở thành thứ không ai dùng.
Nhầm Storybook thay thế Figma. Hai công cụ phục vụ đối tượng khác nhau. Figma cho designer và người ra quyết định xem thiết kế. Storybook cho developer tra cứu và kiểm tra component thực tế.

Góc nhìn của Sinh Vũ

Trong dịch vụ A3 (gói design system đầy đủ), Sinh Vũ đưa Storybook hoặc Ladle (phương án nhẹ hơn, phù hợp project dùng React muốn bớt chi phí cài đặt) vào phạm vi mặc định vì đây là deliverable thực sự có ích cho đội kỹ thuật phía khách.

Tuy nhiên, khi làm việc với khách có đội kỹ thuật nhỏ, Sinh Vũ thường đề xuất bắt đầu bằng Figma documentation kết hợp video onboarding, rồi bổ sung Storybook ở phase 2 khi đội lớn hơn và nhu cầu rõ hơn. Quyết định này được thảo luận ngay trong buổi brief đầu tiên sau khi Sinh Vũ hiểu quy mô đội kỹ thuật của Anh Chị.

Tài liệu không được dùng là tài liệu không tồn tại. Nếu đội kỹ thuật không mở Storybook mà hỏi trực tiếp nhau, đầu tư vào Storybook lúc đó chỉ tạo thêm gánh nặng bảo trì.
Quan điểm thực hành ngành, đúc kết từ kinh nghiệm triển khai thực tế

Câu hỏi Sinh Vũ hay hỏi khách trước khi quyết định: "Khi developer mới join, họ hiện đang tra cứu component bằng cách nào?" Câu trả lời thường cho biết ngay hình thức tài liệu nào phù hợp nhất với đội ngũ đó.

Nguồn tham khảo

Storybook documentation và phương pháp Component-Driven Development, được nhiều tổ chức kỹ thuật lớn áp dụng. Kinh nghiệm thực hành từ Sinh Vũ Studio qua các dự án A3.

Câu hỏi thường gặp

Ladle là gì và khác Storybook thế nào?

Ladle là công cụ tài liệu tương tác cho component tương tự Storybook nhưng nhẹ hơn đáng kể về cấu hình và tốc độ build. Ladle phù hợp với project dùng React và muốn có tài liệu tương tác mà không muốn chịu chi phí cài đặt nặng của Storybook đầy đủ. Sinh Vũ đánh giá Ladle như một lựa chọn thay thế khả thi trong nhiều dự án.

Figma có thể thay thế Storybook không?

Không, hai công cụ phục vụ đối tượng khác nhau. Figma dành cho designer và stakeholder xem thiết kế, Storybook dành cho developer tra cứu và test component trong môi trường thực. Dùng Figma thay Storybook nghĩa là developer phải dịch thiết kế sang code mà không kiểm tra được component thực tế đang chạy như thế nào.

Khi nào nên bổ sung Storybook vào phase sau thay vì làm ngay từ đầu?

Nên trì hoãn Storybook khi đội kỹ thuật hiện tại nhỏ và bandwidth eo hẹp, vì story cần được bảo trì liên tục cùng component. Bắt đầu với Figma documentation và video onboarding là hợp lý. Bổ sung Storybook khi đội lớn hơn, có người chịu trách nhiệm bảo trì story, hoặc khi nhu cầu test trạng thái phức tạp phát sinh rõ ràng.