DOL Design System - Typography

Scope: Typography deep-dive - font family, text scale, density taxonomy, text group matrix. For philosophy: see DIRECTION.md §6 Typography philosophy. For code (Tailwind classes): see ../ui-style-guide/CORE.md §3 Typography.

1. Purpose

Tài liệu này tập trung vào:

• font family
• font size
• line-height density (compact, standard, extended, fit)
• cách chọn style theo độ dài nội dung (1 dòng, 2 dòng, nhiều dòng)

Triết lý chung, core pillars, và anti-patterns cross-topic → xem DIRECTION.md.

2. Nền tảng typography

2.1 Font family

• Heading/Display: Plus Jakarta Sans (--font-family-heading)
• Body/Label: Inter (--font-family-body)
• Quote: Noto Serif (--font-family-quote)

2.2 Font weight

• regular: 400
• medium: 500
• semibold: 600
• bold: 700
• black: 900

2.3 Text scale cơ bản

• xs: 10px
• sm: 12px
• base: 14px
• md: 16px (mobile body md map sang md-sub = 15px)
• lg: 18px
• xl: 20px
• 2xl: 24px
• 3xl: 28px
• 4xl: 32px
• 5xl: 40px
• 6xl: 44px
• 7xl: 48px
• 8xl: 56px
• 9xl: 60px
• 10xl: 64px

3. Cách dùng theo nhóm text

3.0 Fit policy (quy tắc cứng)

• fit chỉ dùng cho mục đích trang trí.
• Chỉ dùng khi text đúng 1 dòng duy nhất.
• Không dùng fit cho nội dung cần đọc, kể cả heading nội dung.

3.1 Display (hero, key number, title impact cao)

Current styles:

• display/8xl/bold-standard
• display/8xl/bold-fit
• display/9xl/bold-standard
• display/9xl/bold-fit

Quy tắc:

• Mặc định dùng standard.
• fit chỉ dùng khi là text trang trí, đúng 1 dòng.
• Không dùng fit cho đoạn text dài hoặc cần dễ đọc.

3.2 Heading (title section, title card, title page)

Pattern:

• heading/{size}/{weight-density}

Current matrix:

• base, md, lg: chỉ có standard (medium/semibold/bold)
• xl: standard, fit, và 1 style đặc biệt heading/xl/medium-compact
• 2xl -> 7xl: standard + fit (medium/semibold/bold)

Quy tắc:

• Mặc định dùng standard.
• Không dùng fit cho heading nội dung.
• Nếu dùng fit thì phải là text trang trí, 1 dòng duy nhất.
• heading/xl/medium-compact chỉ dùng khi layout rất chật và text tối đa 1-2 dòng.

3.3 Body (mô tả, paragraph, nội dung chính)

Pattern:

• body/{size}/{weight-density}

Current matrix:

• xs, sm: compact, standard
• base, md: compact, standard, extended
• lg, xl, 2xl: standard

Default để team dùng nhanh:

• Body thường: body/base/regular-standard (14/20)
• Body ngắn trong UI chật: body/base/regular-compact (14/16)
• Body dài để đọc: body/base/regular-extended (14/24)

Quy tắc:

• standard = default cho đa số body text.
• compact = text ngắn, mật độ cao, không ưu tiên đọc dài.
• extended = text dài nhiều dòng, ưu tiên đọc, thoáng hơn.

3.4 Label (button label, tag, overline)

Pattern:

• label/{size}/{weight-uppercase}

Current styles:

• label/xs|sm|base/{semibold|bold}-uppercase

Quy tắc:

• Luôn uppercase theo token.
• Không dùng cho paragraph.
• Hạn chế 1 dòng; nếu cần 2 dòng thì cần xem lại content.

3.5 Quote (testimonial, trích dẫn)

Pattern:

• quote/{size}/{weight-standard}

Current styles:

• quote/lg|xl|2xl/{regular|semibold}-standard

Quy tắc:

• Dùng Noto Serif (qua token quote).
• Giữ standard để đảm bảo readability.

4. Rule line-height theo độ dài nội dung

Bảng quyết định nhanh:

Tình huống	Density nên dùng	Ghi chú
Text trang trí 1 dòng duy nhất	fit	Chỉ dùng cho mục đích trang trí
Heading 1-2 dòng thông thường	standard	Lựa chọn mặc định
Heading rất chật layout (chỉ 1 style cho phép)	compact	Dùng heading/xl/medium-compact
Body 1-2 dòng trong UI dense	compact	VD: table, chips, metadata ngắn
Body 2-4 dòng thông thường	standard	Lựa chọn mặc định
Body 3+ dòng, ưu tiên đọc	extended	VD: helper text dài, article snippet
Label	uppercase set riêng	Không thay density ngoài token
Quote	standard	Ổn định để đọc

5. Rule theo context sử dụng

• Button text: ưu tiên label/* hoặc body/sm|base/*-standard tùy component.
• Form field label: ưu tiên label/sm/semibold-uppercase hoặc style label trong component spec.
• Helper/error text: body/xs/*-standard hoặc body/sm/*-standard; tránh fit.
• Card description: body/base/regular-standard; nếu copy dài thì extended.
• Hero title: mặc định dùng display/*/bold-standard; chỉ dùng fit nếu là text trang trí và đúng 1 dòng.

6. Responsive rule

• Luôn dùng semantic token, không hardcode px theo breakpoint.
• Hệ thống đã map Desktop/Tablet/Mobile sẵn:
  • Typography semantic: Desktop, Tablet, Mobile
  • Mobile có downscale một số cấp (vd body/md -> 15px)
• Giữ nguyên style key xuyên suốt các breakpoint; để token layer xử lý scale.

7. Do and Dont

Do:

• Dùng standard làm default trừ khi có lý do rõ ràng.
• Chọn style theo vai trò text trước (display/heading/body/label/quote).
• Dùng token naming pattern thay vì set tay font-size/line-height.

Dont:

• Không dùng fit cho text nội dung (heading/body/label/quote).
• fit chỉ dùng cho text trang trí, 1 dòng duy nhất.
• Không dùng label uppercase cho body copy.
• Không mix font heading vào body text.
• Không set line-height tùy ý ngoài token khi không có exception được phê duyệt.

8. Checklist trước handoff

• Đã dùng đúng group text (display/heading/body/label/quote)?
• Density có đúng với độ dài content?
• Body copy >= 3 dòng đã xem xét extended chưa?
• Mobile có giữ semantic token (không hardcode)?
• Có token nào bị phá vỡ naming/contract không?

Navigation

• Hub: README.md
• Direction & philosophy: DIRECTION.md
• Related topic files: color.md, spacing.md
• Code reference: ../ui-style-guide/CORE.md §3 Typography (Tailwind classes, typography-by-context table)