Typography

Typography System Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo Typography System — hệ thống chữ hoàn chỉnh bao gồm các semantic text roles ánh xạ đến typography tokens.

1. Mục tiêu (Objective)

Tạo hệ thống Typography với các component/utility class cho mọi vai trò text (display, headline, title, body, label, caption). Đảm bảo nhất quán, accessible, và mapping 100% từ typography tokens.

2. AI Context & Intent (Ngữ cảnh cho AI)

Khi nào dùng Typography?

• MỌI LÚC hiển thị text: heading, paragraph, label, caption
• Đảm bảo nhất quán: Không tự ý chọn font-size/weight — phải dùng typography role

Typography Roles — Hệ thống vai trò chữ

Mỗi role phục vụ một mục đích cụ thể trong hierarchy:

Decision Tree cho AI

Văn bản cần hiển thị?
├─ Xác định LAYER trước (Ground / Card / Surface)
│  ├─ Ground (page-level) → dùng headline + body
│  ├─ Card (component) → dùng title + body-sm
│  └─ Surface (overlay) → dùng title-sm + caption
│
├─ Chọn ROLE theo mục đích:
│  ├─ Hero / landing / branding → Display (xl, lg)
│  ├─ Page section heading → Headline (lg, md, sm)
│  ├─ Component title (card, dialog) → Title (lg, md, sm)
│  ├─ Main content paragraph → Body (lg, md, sm)
│  ├─ UI control label → Label (lg, md, sm)
│  ├─ Secondary / time / footnote → Caption
│  └─ Inline emphasis → Body + bold/italic
│
└─ Kiểm tra 3-AXIS CONTRAST (T16, T17):
   ├─ Title weight ≥ 600? ✓
   ├─ Description dùng muted-foreground? ✓
   └─ Size gap ≥ 2 step? ✓

3. Ngữ nghĩa & Phân loại (Semantics)

3.1. Typography Scale — Mapping đến Tokens

3.2. Color Tokens cho Typography

3.3. Title/Description Pairing Rules (T16, T17, T18)

Source: title-hierarchy-systems.md — MD3 + shadcn research

3-Axis Contrast — Mọi cặp Title/Description PHẢI đạt ít nhất 2/3 trục:

Elevation × Typography Matrix (T18):

3.4. Component Typography Spec

3.5. Anti-patterns (Typography)

4. Token Mapping

📦 Atomic Mapping: See ATOMIC-MAPPING.md for complete token spec.

Xem bảng chi tiết mục 3.1 — mỗi typography role ánh xạ trực tiếp đến bộ 4 tokens:

• font.size.* → font-size
• font.weight.* → font-weight
• font.leading.* → line-height
• font.tracking.* → letter-spacing

5. Props & API

interface TextProps {
  /** Typography role — quyết định toàn bộ visual */
  role?: 'display-xl' | 'display-lg' | 'display-md' |
         'headline-lg' | 'headline-md' | 'headline-sm' |
         'title-lg' | 'title-md' | 'title-sm' |
         'body-lg' | 'body-md' | 'body-sm' |
         'label-lg' | 'label-md' | 'label-sm' |
         'caption';
  /** Render as HTML tag (override default) */
  as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label' | 'small' | 'div';
  /** Color variant */
  color?: 'default' | 'muted' | 'inverse' | 'primary' | 'destructive' | 'success' | 'warning' | 'info';
  /** Text alignment */
  align?: 'left' | 'center' | 'right';
  /** Truncate with ellipsis */
  truncate?: boolean;
  /** Max lines before truncation */
  maxLines?: number;
  /** Weight override (trong cùng role) */
  weight?: 'normal' | 'medium' | 'semibold' | 'bold';
  /** Content */
  children: ReactNode;
}

6. Accessibility (a11y)

• Heading hierarchy: Phải tuân thủ H1 → H2 → H3 theo thứ tự, không nhảy level.
• Không dùng heading cho style: Nếu chỉ cần text to, dùng role="body-lg" + as="p", KHÔNG dùng <h2>.
• Contrast ratio: Text trên background phải đạt tối thiểu 4.5:1 (WCAG AA), 3:1 cho large text.
• Line length: Body text nên 45–75 ký tự/dòng (readability).
• Truncation: Nếu truncate, toàn bộ text phải accessible qua title attribute hoặc tooltip.

7. Best Practices & Rules

• Semantic HTML: Role ánh xạ đến HTML tag đúng (headline → <h*>, body → <p>, label → <label>/<span>).
• Prop as override: Cho phép tách visual (role) khỏi semantic (HTML tag) — vd: role="headline-md" as="h3".
• Không Hardcode: KHÔNG BAO GIỜ viết font-size: var(--font-size-sm) trực tiếp — phải dùng token.
• Responsive: Display/Headline sizes có thể giảm trên mobile via media query.
• Dark Mode: Tự động qua color tokens.

8. Example Usage

{/* Page headline */}
<Text role="headline-lg" as="h1">Tổng quan tài khoản</Text>

{/* Card title */}
<Text role="title-md">Giao dịch gần đây</Text>

{/* Body paragraph */}
<Text role="body-md" color="muted">
  Tài khoản của bạn đã được kích hoạt thành công.
</Text>

{/* Form label */}
<Text role="label-md" as="label" htmlFor="email">
  Email
</Text>

{/* Caption */}
<Text role="caption" color="muted">
  Cập nhật lần cuối: 26/02/2026
</Text>

{/* Truncated text */}
<Text role="body-sm" truncate maxLines={2}>
  Đây là một đoạn text rất dài sẽ bị cắt sau 2 dòng...
</Text>