storybook

colors

hệ thống màu 1thay tổ chức theo 3 lớp token (học từ SAP + Calcite): lớp 1 — reference (--ref-*) là raw values không đổi, lớp 2 — semantic (--color-*, --text-*, --surface-*) được theme override, lớp 3 — component (--btn-*, --card-*, --input-*) tự động kế thừa từ lớp 2. các swatch bên dưới dùng mã hex cứng — không bị ảnh hưởng bởi brand hay theme đang active.

brand palettes

4 brand, mỗi brand 10 mức (50→900). chuyển brand qua dropdown BrandSwitch trên navbar hoặc data-brand="tên-brand" trên container. mỗi brand có display font riêng — thay đổi theo brand đang active.

reputa-blue base: #064BAE · display: Hanken Grotesk · chuyên nghiệp, tài chính, analytics

50 #e8f0fc fail
100 #c5d8f6 fail
200 #9dbff0 fail
300 #75a6ea fail
400 #5798e8 fail
500 #3870d0 AA
600 #064BAE AAA
700 #053c92 AAA
800 #042e6e AAA
900 #031f4a AAA

reputa-premier base: #A10B2E · display: Hanken Grotesk · sang trọng, thương mại, media

50 #fce8ec fail
100 #f5c5cd fail
200 #ed9eab fail
300 #e57788 fail
400 #e8576e large
500 #c93048 AA
600 #A10B2E AAA
700 #920b28 AAA
800 #6e081d AAA
900 #4a0412 AAA

tramnghe base: #044f44 · display: Merriweather · tự nhiên, y tế, bền vững

50 #e6f0ed fail
100 #bfd9d2 fail
200 #93c1b5 fail
300 #68a998 fail
400 #3d8b7a large
500 #1a6d5c AA
600 #044f44 AAA
700 #044440 AAA
800 #033830 AAA
900 #022621 AAA

1thay base: #FBC000 · display: Space Grotesk · năng lượng, sáng tạo, startup

50 #fff9e6 fail
100 #fff0bf fail
200 #ffe793 fail
300 #ffdd66 fail
400 #ffd54a fail
500 #e0a800 fail
600 #FBC000 fail
700 #d9a300 fail
800 #b88a00 large
900 #7a5d00 AA

neutral-ghi

12 cấp xám — từ trắng tinh đến gần đen. "ghi" là từ thuần việt cho màu xám. dùng cho toàn bộ bề mặt, văn bản, viền trong hệ thống. không bao giờ tham chiếu trực tiếp --ref-neutral-* trong component — luôn qua semantic tokens.

0 #ffffff background chính
50 #f8fafc sidebar, row striped
100 #f1f5f9 surface raised, card fill
200 #e2e8f0 border mặc định
300 #cbd5e1 border mạnh, placeholder
400 #94a3b8 text muted, icon phụ
500 #64748b text secondary, caption
600 #475569 body text (nền sáng)
700 #334155 heading text
800 #1e293b text chính (nền sáng)
900 #0f172a text primary, emphasis
1000 #020617 shadow base, max emphasis

semantic colors

màu trạng thái — không thay đổi giữa các brand. dùng cho alerts, badges, form validation, và toast notifications.

success

#16a34a

thành công, xác nhận — badges, alerts, toast

warning

#d97706

cảnh báo, đang chờ — alerts, status indicators

error

#dc2626

lỗi, nguy hiểm — validation, destructive actions

info

#2563eb

thông tin, trợ giúp — tooltips, help text, guides

dark mode

kích hoạt qua data-theme="dark". override các semantic tokens — surface chuyển tối, text chuyển sáng, border đậm hơn. brand colors và component tokens không thay đổi — chúng tự động kế thừa từ semantic tokens đã được override.

tokenlightdarkcách dùng
--surface-bg #ffffff #0f172a nền trang
--surface-dim #f8fafc #1e293b sidebar, nền section phụ
--surface-raised #ffffff #1e293b card, dropdown, modal
--surface-overlay #1e293b #020617 backdrop, overlay scrim
--text-primary #0f172a #f1f5f9 headings, body text
--text-secondary #64748b #94a3b8 văn bản phụ, chú thích
--text-muted #94a3b8 #64748b placeholder, disabled text
--text-inverse #ffffff #0f172a text trên nền tối/brand
--border-color #e2e8f0 #334155 viền mặc định
--border-color-strong #cbd5e1 #475569 viền nổi bật
--border-color-focus #5798e8 #5798e8 viền khi focus (giữ nguyên brand)

kiến trúc token 3 lớp

học từ SAP và Calcite — mỗi lớp có phạm vi override khác nhau. lớp 2 là nơi duy nhất theme được phép thay đổi.

lớpprefixví dụtheme override?số lượng
1 — reference --ref-* --ref-blue-600: #064BAE không ~120 ref tokens
2 — semantic --color-* --text-* --surface-* --border-* --color-brand-600: var(--ref-blue-600) có — brand + dark ~70 semantic tokens
3 — component --btn-* --card-* --input-* --table-* --btn-primary-bg: var(--color-brand-600) không — kế thừa ~50 component tokens

luồng dữ liệu token

--ref-blue-600raw value: #064BAE
→
--color-brand-600semantic: brand override here
→
--btn-primary-bgcomponent: auto-inherits

component token mapping

mỗi component có bộ token riêng — luôn trỏ đến semantic tokens. component code không bao giờ dùng raw values.

componentcomponent tokens
button --btn-primary-bg, --btn-primary-text, --btn-secondary-bg, --btn-ghost-text, --btn-destructive-bg, --btn-font, --btn-radius, --btn-px, --btn-h-*
card --card-bg, --card-radius, --card-padding, --card-shadow, --card-border
input --input-bg, --input-text, --input-placeholder, --input-border, --input-border-focus, --input-radius, --input-px, --input-h-*, --input-font
table --table-header-bg, --table-header-text, --table-row-hover, --table-border, --table-cell-px, --table-cell-py, --table-font, --table-number-font

chuyển đổi brand

4 brand: reputa-blue (mặc định), reputa-premier, tramnghe, 1thay. chuyển qua dropdown BrandSwitch trên navbar. component không cần biết đang ở brand nào — mọi thứ tự động qua semantic tokens.

hướng dẫn sử dụng

nên

  • dùng neutral-ghi cho bề mặt và văn bản, brand colors cho điểm nhấn
  • kiểm tra contrast ratio trước khi ship (tối thiểu AA — 4.5:1)
  • dùng semantic colors đúng ý nghĩa — success, warning, error, info
  • tham chiếu surface/text tokens, không bao giờ dùng raw --ref-neutral-*
  • luôn test dark mode khi thêm component mới

không nên

  • dùng brand colors làm nền toàn trang
  • thêm màu mới mà không định nghĩa token trước trong tokens.css
  • pha trộn brand palettes trong cùng một view
  • hardcode hex — luôn dùng var()
  • override component tokens trực tiếp trong page CSS