storybook

design principles

những nguyên tắc cốt lõi chi phối mọi quyết định thiết kế trong 1thay. đây không phải là quy tắc cứng nhắc — mà là la bàn để định hướng khi đứng trước lựa chọn.

6 nguyên tắc

01

code-first

tokens.css là single source of truth cho mọi giá trị thiết kế. figma mirror — không phải nguồn gốc. component được build và test trong storybook trước khi tích hợp vào astro.

02

lowercase

toàn bộ ui text viết thường — button, label, heading, caption. giảm nhiễu thị giác, tăng legibility. ngoại lệ duy nhất: tên riêng và nhãn hiệu.

03

bento grid

layout dùng css grid 12 cột với module chữ nhật. radius đồng nhất --radius-lg. gap và padding dùng spacing tokens.

04

reading first

contrast ratio đạt WCAG AA (4.5:1). line-height 1.5-1.625 cho body text. max-width content area ~75 ký tự/dòng. typography tối ưu cho đọc trước thẩm mỹ.

05

data clarity

số liệu, biểu đồ, bảng biểu phải rõ ràng và dễ so sánh. không che giấu thông tin sau hiệu ứng. dùng --font-number cho mọi numeric display. chart colors được chọn để distinguishable ngay cả khi grayscale.

06

accessible by default

WCAG AA là tiêu chuẩn tối thiểu. focus indicator rõ ràng (2px brand-600). touch target >= 24x24px. semantic HTML. aria labels đầy đủ. không chỉ dùng màu để truyền tải thông tin.

cognitive load

tối đa 7±2 hành động chính trên một view (Miller's law). nhóm secondary actions. dùng progressive disclosure để ẩn complexity — show tối thiểu, reveal thêm khi cần. cùng một hành động phải có cùng vị trí, màu sắc, và icon trên mọi page.

visual hierarchy

primary 1 CTA chính mỗi view — brand-600, size lg, vị trí nổi bật
secondary tối đa 3 actions — ghost hoặc secondary variant, size md
tertiary còn lại — link text, icon button, dropdown menu

giải quyết xung đột thiết kế

khi có 2 lựa chọn mâu thuẫn:

  1. render cả 2 ra màn hình
  2. đặt cạnh nhau
  3. chọn cái nhìn rõ hơn, dễ đọc hơn, ít gây phân tâm hơn
  4. nếu vẫn không rõ — chọn cái đơn giản hơn

microcopy

nên

  • tone thân thiện, trực tiếp, lowercase
  • động từ cụ thể: "lưu thay đổi" thay vì "submit"
  • giải thích lỗi + hướng dẫn sửa, không blame user
  • hiển thị timestamp cập nhật dữ liệu

không nên

  • robotic, quá formal, hoặc quá technical
  • dùng từ mơ hồ: "đã xảy ra lỗi" — nói rõ lỗi gì
  • uppercase như phong cách
  • ẩn thông tin sau icon hoặc hover