DOL Design System - Color

activeUpdated3 tuần trước

Scope: Semantic color usage for UI decisions - neutral hierarchy, property category, on-inverse, status/skill boundaries, CVD detail, shade scale math. For philosophy: see DIRECTION.md §4 Bản sắc màu DOL + §5 CVD accessibility. For code (Tailwind classes): see ../ui-style-guide/CORE.md §2 Color + ../../docs/tailwind-color-guideline.md (full 18-family mapping).

1. Purpose

Tài liệu này giúp designer và AI chọn đúng semantic color token trong các trường hợp text cơ bản, thay vì chỉ biết inventory token đang tồn tại.

Ưu tiên của file này:

chọn text-color/* đúng theo hierarchy
phân biệt text, icon, border, fill, surface
chốt default an toàn cho nền sáng và nền ngược
giữ product-pattern color không bị nhầm thành universal DS rule

Brand semantics, skill color rationale, CVD critical rule → DIRECTION.md.

1.1 Routing note for agents

File này chốt semantic color decision: nên dùng role màu nào, hierarchy nào, và khi nào chuyển sang on-inverse/*.
File này không là source of truth cho standard Tailwind class mapping.
Nếu task là code/prototype/runtime, sau khi đọc file này phải mở tiếp:
- DOL-DS-token/docs/tailwind-color-guideline.md
- DOL-DS-token/docs/ai-color-context.md khi cần prompt ngắn cho external AI tools
Guardrail: không suy ra text-slate-*, text-red-*, text-on-inverse-* chỉ từ tên token semantic trong file này nếu chưa đối chiếu DS-Token companion.

2. Hard rules

Dùng text-color/* cho typography content only.
Không dùng text-color/* cho icon. Icon phải dùng icon-color/*.
Không dùng border-color/* để tô text.
Không dùng color base trực tiếp nếu đã có semantic token tương ứng.
Trên nền ngược hoặc nền đậm, chuyển sang text-color/on-inverse/*.
Chọn on-inverse/* theo ý đồ thị giác xuyên theme, không theo tên token. Nếu background ở cả light và dark vẫn đọc như một bề mặt đậm / inverse / CTA màu, text trên đó vẫn dùng on-inverse/*.
Không truyền đạt status chỉ bằng màu. Status quan trọng phải có label, icon, hoặc context rõ.
Tối đa 2 semantic accent colors trong một view; neutral là nền tảng cho phần còn lại.
Nếu một element vừa có skill vừa có status, status là feedback chính, skill chỉ làm context phụ.
Không copy color rule từ một product pattern (score, leaderboard, exercise state) thành universal DS rule nếu chưa được DS-Token chốt.

2.1 Token category discipline

Chọn category theo property cần set, không theo màu giống nhau về mặt thị giác.

Category	Dùng cho	Không dùng cho
`fill/*`	background, filled shape, control fill, card tint	text, icon, border
`text-color/*`	text layer / typography content	icon vector, border, surface
`icon-color/*`	icon/vector icon	text layer, card background
`border-color/*`	stroke, border, divider	text, icon fill
`surface/*`	page, card, panel background	semantic status by itself
`control/`, `overlay/`	component family có token riêng	ad-hoc replacement cho core category

Common mistakes cần sửa:

Dùng fill token cho text vì cùng hex.
Dùng text token cho icon.
Dùng icon token cho background.
Tạo token theo tên feature như onboarding-card-title-color thay vì semantic role.

3. Neutral text hierarchy

Thứ tự hierarchy khuyến nghị trong DOL DS hiện tại:

neutral-stress → neutral-primary → neutral-subtle → neutral-secondary → neutral-dim → neutral-disabled

Lưu ý quan trọng:

Trong hệ hiện tại, neutral-subtle vẫn mạnh hơn neutral-secondary.
Khi chọn token, ưu tiên mức nhấn thị giác thực tế thay vì chỉ đọc nghĩa tiếng Anh của tên token.

4. Recommended defaults for basic text

4.1 Main content

Body text mặc định: text-color/neutral-primary
Paragraph dài, mô tả chính, nội dung form đã nhập: text-color/neutral-primary
Card title thông thường: text-color/neutral-primary

4.2 Strong emphasis

Hero title, số liệu nổi bật, heading cần nhấn mạnh cao: text-color/neutral-stress
Chỉ dùng cho số ít điểm nhấn trong một block; không dùng làm default cho toàn bộ page copy

4.3 Supportive text

Subtitle gần title, eyebrow, short supporting line vẫn cần đọc tốt: text-color/neutral-subtle
Secondary info, metadata, timestamp, helper phụ, mô tả nhẹ dưới title: text-color/neutral-secondary

4.4 Low-emphasis text

Placeholder, hint nhẹ, trạng thái chưa kích hoạt, meta rất phụ: text-color/neutral-dim
Disabled text thật sự: text-color/neutral-disabled

Không dùng:

neutral-dim cho paragraph dài
neutral-disabled cho content vẫn cần người dùng đọc bình thường

5. Quick mapping by use case

Use case	Recommended token	Notes
Page / section title	`text-color/neutral-stress` hoặc `text-color/neutral-primary`	`stress` khi cần high-emphasis, `primary` cho đa số screen title
Card title	`text-color/neutral-primary`	Default an toàn
Body paragraph	`text-color/neutral-primary`	Default cho mọi body copy
Subtitle gần title	`text-color/neutral-subtle`	Vẫn đủ contrast và giữ hierarchy rõ
Metadata / timestamp / category	`text-color/neutral-secondary`	Dùng cho info phụ, ngắn
Helper text	`text-color/neutral-secondary`	Nếu còn cần đọc rõ; nếu chỉ là hint nhẹ mới dùng `dim`
Placeholder	`text-color/neutral-dim`	Không dùng cho value thật
Disabled label / disabled value	`text-color/neutral-disabled`	Chỉ cho disabled state
Text trên nền dark / brand / overlay đậm, hoặc nền giữ cảm giác inverse tương tự giữa light/dark	`text-color/on-inverse/primary`	100% opacity - luôn trắng cả light/dark
Secondary text trên nền dark / brand / overlay đậm, hoặc nền giữ cảm giác inverse tương tự giữa light/dark	`text-color/on-inverse/secondary`	70% opacity - `rgba(255,255,255,0.7)`
Disabled text trên nền dark / brand / overlay đậm, hoặc nền giữ cảm giác inverse tương tự giữa light/dark	`text-color/on-inverse/disabled`	30% opacity - `rgba(255,255,255,0.3)`

6. Semantic text colors beyond neutral

Chỉ dùng semantic text màu khi bản thân nội dung mang meaning đó:

Success message: text-color/success-primary
Warning message: text-color/warning-primary
Error message: text-color/danger-primary
Info / system notice: text-color/info-primary
Brand-led accent text hoặc inline link nổi bật: text-color/brand-primary
AI/special/program-specific text chỉ dùng trong đúng feature lane có semantic đó

Không nên:

dùng brand-primary cho paragraph dài
dùng success/warning/danger chỉ để “cho đẹp”

6.1 English Skill Semantic Colors

Để tạo sự đồng nhất về mặt nhận diện trong toàn bộ hệ thống (app, web, KID), các kỹ năng tiếng Anh và dạng bài đánh giá được quy định màu sắc như sau:

Reading: Emerald / Green (Xanh lá) - Tượng trưng cho sự tiếp thu, đọc hiểu.
Listening: Blue (Xanh dương) - Tượng trưng cho luồng âm thanh thông suốt.
Writing: Amber / Yellow (Vàng kem) - Tượng trưng cho sự sáng tạo, tập trung viết.
Speaking: Rose (rose-600 / pink-pi100) - KHÔNG phải Brand Red (red-600). Tượng trưng cho sự tự tin, phát âm lớn.
Tổng hợp / Full Test / Online Test: Purple (Tím) - Tượng trưng cho dạng bài đa kỹ năng, đánh giá toàn diện.
AI Features / Smart Actions: Sky / Cyan (Xanh biển / Xanh ngọc) - Tượng trưng cho sự thông minh, magic (sparkles/stars icon), gợi ý cải thiện chữ, và chấm bài.

Quy tắc này áp dụng cho màu text của Title, màu Icon, và màu tint của tag/badge/card background liên quan trực tiếp đến kỹ năng đó.

Nếu một element vừa đại diện skill vừa phản hồi trạng thái, ưu tiên status:

Correct/incorrect answer: success/danger là feedback chính; skill color chỉ còn ở header/context nếu cần.
Locked/warning/error test state: state color thắng skill color.
Score thấp/cao: dùng score-level logic đã được product/spec xác nhận; không tự suy ra danger/success chỉ từ điểm.

6.2 Color blindness (CVD) considerations

Khoảng 8% nam và 0.5% nữ có một dạng color vision deficiency. Audit DS V2 (2026-04-15) phát hiện:

Pair	Normal ΔE	Deuteranopia ΔE	Risk
blue vs purple (info vs special)	21	2	🔴 confusing for ~5% of users
green vs red (success vs error)	105	23	✓ ok
green vs primary (success vs brand)	112	14	⚠ borderline

Critical rule - khi blue + purple xuất hiện cùng nhau (legend, chart, multi-state badge, navigation tabs):

KHÔNG rely on color alone - luôn pair với:
- Icon hình dạng khác nhau (e.g., Info icon for blue, Star for special)
- Text label rõ ràng
- Pattern/texture (last resort)
Đối với data viz (charts với multiple series): dùng patterns + labels, không chỉ blue vs purple.
Đối với navigation/tabs: thêm icon prefix bên cạnh tab label.

Examples:

// ✗ KHÔNG: chỉ dùng màu để phân biệt
<Tab color="blue">Info</Tab>
<Tab color="purple">Special</Tab>

// ✓ ĐÚNG: icon + label
<Tab color="blue" icon={InfoIcon}>Info</Tab>
<Tab color="purple" icon={StarIcon}>Special</Tab>

// ✗ KHÔNG: chart only by color
<Legend>
  <Series color="blue" />
  <Series color="purple" />
</Legend>

// ✓ ĐÚNG: pattern + label
<Legend>
  <Series color="blue" pattern="solid" label="Q1" />
  <Series color="purple" pattern="diagonal" label="Q2" />
</Legend>

Rule of thumb: nếu user phải distinguish 2 elements bằng VISUAL only, không dùng blue + purple cùng nhau. Tách ra dùng blue + green hoặc purple + amber.

6.3 Product-pattern color boundaries

Các pattern dưới đây thường có màu riêng trong Notion/product design, nhưng không phải core color rule nếu thiếu product context:

Pattern	Color decision rule	Source-of-truth boundary
Score level	Score cần label/range/context. Điểm thấp không tự động là danger; điểm cao không tự động là success nếu đó chỉ là learning feedback.	Product/spec chốt score band và threshold; DS chốt token/category/contrast.
Leaderboard/ranking	Ranking có thể có emphasis riêng cho top 1/2/3/other, nhưng không dùng như semantic status/accent chung.	Product/spec chốt metric, tie rule, privacy, attempt counted; DS chốt visual hierarchy và accessibility.
Test/practice lifecycle	Locked, waiting, in progress, done, warning, error phải có label/icon/context và ảnh hưởng CTA/navigation rõ.	Product/spec chốt lifecycle; DS chốt cách dùng status color và component state.
Online Test structure	Skill/section/group/question giúp UI organize progress, review, result.	Product/spec hoặc EduDoc chốt data model/scoring; DS chỉ ghi reusable UI implication.

Nếu cần UI recipe cho các pattern này, đọc ../ui-style-guide/practice.md §7.

7. Surface pairing defaults

Trên surface trung tính thông thường:

body/title mặc định vẫn dùng text-color/neutral-primary
supporting text dùng neutral-subtle hoặc neutral-secondary

Trên fill hoặc card tint nhẹ:

vẫn ưu tiên neutral text nếu content là general content
chỉ đổi sang semantic text khi bản thân content là state message

Trên nền đậm hoặc inverse:

main text: text-color/on-inverse/primary
supporting text: text-color/on-inverse/secondary
disabled: text-color/on-inverse/disabled

Quy tắc quyết định:

Nếu background đổi theme nhưng vẫn giữ vai trò một surface đậm / inverse / CTA màu ở cả hai theme, tiếp tục dùng text-color/on-inverse/*.
Không dùng token neutral/surface chỉ vì tên của nó là white. Nếu foreground phải luôn trắng ở cả light và dark, chọn text-color/on-inverse/primary.
Ví dụ: button tím kiểu Open in Wiki vẫn dùng text-color/on-inverse/primary, vì ý đồ là chữ luôn trắng trên một CTA đậm ở cả hai theme.

8. AI defaults

Nếu AI không có thêm context đặc biệt, hãy dùng:

Body text: text-color/neutral-primary
Secondary line gần body/title: text-color/neutral-secondary
Subtitle cần hiện diện rõ hơn metadata: text-color/neutral-subtle
Placeholder/hint nhẹ: text-color/neutral-dim
Text trên nền đậm hoặc CTA màu giữ contrast tương tự giữa theme: text-color/on-inverse/primary

9. Do and Dont

Do:

Chọn token theo hierarchy nội dung trước, rồi mới nghĩ đến màu sắc “đẹp”.
Giữ neutral text làm default cho đa số UI.
Dùng on-inverse/* khi background đã đảo ngữ cảnh sáng/tối.
Dùng on-inverse/* khi foreground phải giữ cảm giác chữ sáng cố định qua cả light và dark.
Dùng đúng category: text cho text, icon cho icon, fill/surface cho background, border cho stroke.
Thêm label/icon/context cho status quan trọng.

Dont:

Không dùng token accent cho body copy dài.
Không dùng dim hoặc disabled để “tạo cảm giác nhẹ” cho content vẫn cần đọc rõ.
Không suy luận rằng secondary luôn mạnh hơn subtle; trong hệ này không đúng.
Không dùng token neutral/surface chỉ vì tên lớp có chữ white nếu mục tiêu thật sự là chữ phải luôn trắng.
Không để skill color lấn át success/warning/danger/info khi element đang phản hồi trạng thái.
Không biến score/leaderboard/product-specific color thành universal DS rule.

10. Shade scale depth - consistent perception

Mỗi color family có 11 shade solid (05, 10, 20, 40, 60, 80, 100, 120, 140, 160, 180). Để cảm giác “độ đậm” nhất quán khi user lướt qua nhiều family (ví dụ Reading green vs Listening blue vs Writing amber), shade cùng số nên cảm giác cùng mức nhấn.

10.1 Hai rule bắt buộc

L* progression đều trong mỗi family. Step giữa shade liền kề nên rơi vào khoảng 6–11 L* - tránh step > 15 hoặc < 5 trong range chính (100–180).
L* target cho 180 phụ thuộc hue family - không set một con số cố định cho mọi family:

Hue group	Ví dụ	Target L* cho `180`
Cool (blue, navy, deep-sky)	`B`, `NB`, `DS`	15–16
Purple, magenta, pink	`P`, `MA`, `PI`	18–20
Neutral, green, teal	`N`, `G`, `TL`	20–22
Warm (orange, bronze, yellow, gold)	`OR`, `BZ`, `Y`, `GD`	24–27

Lý do: warm family ở L*16 mất identity warm/amber (thành “nâu đen bùn”), cool family ở L*24 thì không đủ contrast. Đây là đặc tính perceptual - không phải convention tùy chọn.

10.2 Tại sao quan trọng cho designer/AI

Chọn Y180 cho “maximum Writing emphasis” và B180 cho “maximum Listening emphasis” thì hai element đó phải cảm giác đậm tương đương khi đặt cạnh nhau. Nếu Y180 cảm giác nhạt hơn → Writing lesson trông “yếu” hơn Listening trong navigation, UI hierarchy bị lệch không có lý do.
Designer nên tin vào shade index (180 > 160 > 140 …) - không cần mỗi lần phải pick màu thủ công để “cân bằng”.

10.3 Khi scale không nhất quán - cách escalate

Nếu bạn nhận ra một family (ví dụ Y180) trông “nhạt hơn” hoặc “đậm hơn” so với family khác cùng shade:

Flag vào repo DS-Token - không tự fix trong prototype bằng cách đổi sang shade khác.
Reference DS-Token/docs/alpha-decomposition-spec.md §5 (Shade scale depth) và case study DOL-DS-token/ai-memory/archived/yellow-scale-depth-2026-04-14.md cho workflow chốt L* target + re-derive alpha.
Thay đổi solid phải re-derive alpha scale đi kèm (XA05…XA100) - pair này move together.

10.4 Alpha scale

Mọi family có alpha scale (XA00…XA100) được derive tự động từ solid bằng max-saturation decomposition - không phải giá trị tùy chọn. Designer không cần tính alpha bằng tay; khi solid đổi, alpha re-generate theo spec.

Chi tiết math + mapping ở DS-Token/docs/alpha-decomposition-spec.md. Tóm gọn:

XA00 = transparent, XA05…XA100 map sang X05, X10, X20, X40, X60, X80, X100, X120, X140, X160, X180 (skip X30).
NDA (neutral-dark-alpha) có mapping shifted đặc biệt - xem spec §2.3.
Alpha a = 1.0 là hợp lệ với shade có channel = 0 (ví dụ yellow dark) - không phải bug.

Hub: README.md
Direction & philosophy: DIRECTION.md
Related topic files: shadow.md
Code reference: ../ui-style-guide/CORE.md §2 Color (Tailwind classes, text hierarchy, status patterns, skill colors)
Deep reference:
- ../../docs/tailwind-color-guideline.md (full 18-family mapping)
- ../../docs/ai-color-context.md (AI prompt for external tools)
- ../../docs/alpha-decomposition-spec.md (shade scale + alpha math)