Design system

Phong cách chung: màu đặc, nét rõ, không dùng màu chuyển sắc và bóng mờ. Hệ chỉ có một màu hành động: cta bằng chính primary.

1. Màu

Bảng màu

Nguồn duy nhất là design-system/tokens.json ở gốc kho. Bảng dưới đây in ra đúng token của bản dựng này — sửa màu thì sửa tokens.json rồi chạy npm run sync:tokens ở cả ba app trong cùng một PR, đừng sửa theme/tokens.css.

Độ tương phản chữ trên nền (tính từ token, theo WCAG 2.1)

Quy tắc màu

• Nền primary chỉ cõng chữ trắng. primarySoft không cõng chữ nào, và trên nền primary thì nó gần như biến mất — nét vẽ trang trí nằm trên nền xanh dùng cta hoặc accent.
• Liên kết nằm trên nền trắng hoặc nền xám dùng link, không dùng primary: primary chỉ đủ tương phản khi làm nền hoặc viền.
• Dải màu đầu trang đi từ primaryDeep xuống primaryMid, và chỉ một dải đó. Đậm ở trên vì thanh trạng thái của máy nằm chồng lên đỉnh dải; cả hai bậc đều cõng được chữ trắng.
• accent trên Website là màu nhận diện kiểu Đông Hồ: dải doanh nghiệp, số thứ tự bước, bóng đổ sau khung điện thoại. Không dùng nó làm màu chữ của liên kết — việc đó là của link. Trong Mini App, accent chỉ dành cho lỗi, từ chối và huỷ.
• Màu hành động của bề mặt máy tính là vàng nghệ: cta là #e8b23a, chữ trên nút là onCta — navy, không bao giờ trắng. Mỗi tầm mắt chỉ một nút vàng; việc phụ đi bằng nút viền.
• primaryVeil là pill sáng nổi trên nền xanh — chữ trên nó là primaryDeep, không bao giờ là trắng.
• Đổi mã màu trong tokens.json thì đọc lại bảng tương phản ở trên — bảng tự tính lại, cặp nào tụt xuống “không đạt” là chặn.

2. Chữ

• Khoảng cách dòng của tiêu đề tối thiểu là 1.18. Thấp hơn thì chữ có hai dấu chồng nhau (ộ, ặ) bị cắt dấu và dễ đọc sai.
• Không viết hoa toàn bộ chữ trong nhãn hay tiêu đề.
• Mỗi dòng chữ dài tối đa khoảng 40em.
• File font lưu cùng trang, không tải từ Google Fonts. Chỉ nạp các độ đậm có trong bảng, cắt gọn còn bộ ký tự vietnamese và latin.

3. Bo góc

Bản thiết kế đang dùng 11 mức bo góc khác nhau. Khi chuyển sang code, gộp lại còn 6 mức:

• Khối lồng nhau: bo góc bên trong nhỏ hơn bên ngoài một bậc.
• Bóng chat: --radius-lg ở ba góc, --radius-xs ở góc phía người nói.
• Mọi nút đều bo tròn hai đầu (--radius-pill), không có nút góc vuông.

4. Khoảng cách và bố cục

Bố cục dùng flex-wrap và flex-basis, nên các khối tự xếp thành một cột trên điện thoại mà không cần thêm điểm chuyển.

5. Viền, bóng, focus

Trang không dùng bóng mờ. Chỉ có một bóng đổ màu accent đặc, đặt sau khung điện thoại ở đầu trang để tạo điểm nhấn. Dùng bóng này ở nhiều chỗ thì nó không còn nổi bật.

6. Nút

Mọi nút bo tròn hai đầu (--radius-pill), cao tối thiểu 44px, dùng font Be Vietnam Pro, không thêm mũi tên “→” ở cuối nhãn.

Trạng thái

• Rê chuột lên link: chữ chuyển sang màu đỏ.
• Focus: viền --focus-ring.
• Đang chọn hoặc đang bật: đặt aria-pressed="true" và đổi giao diện theo trạng thái này.
• Chưa nối chức năng: nút vẫn bấm được và hiện thông báo “Chưa hoàn thiện”. Không làm mờ nút và không để nút bấm mà không có phản hồi.

7. Component

Chip lọc

Bo tròn hai đầu, viền 2px màu primary. Chưa chọn: nền surface, chữ link. Đang chọn: nền primary, chữ on-primary, aria-pressed="true". Trên điện thoại, các chip nằm trên một hàng, vuốt ngang để xem tiếp, không xuống dòng.

Tag / nhãn

Thẻ việc làm

Nền surface-alt, bo góc --radius-md, khoảng đệm 20px trên dưới và 22px hai bên. Tên công việc 18px, độ đậm 600. Nơi làm việc 14px màumuted. Nhãn loại việc nằm bên phải, xuống dòng khi trên điện thoại.

Thẻ bước (hành trình điểm thưởng)

Nền surface đặt trên nền surface-alt, bo góc --radius-lg, khoảng đệm 24px (trên điện thoại là 18px trên dưới, 20px hai bên). Số thứ tự bước dùng font Phudu cỡ 40px (28px trên điện thoại), màu accent. Bước đang chạy được đánh dấu bằng đồng xu nảy lên, không đổi nền. Dưới cùng là thanh tiến trình 3 đoạn: phần chưa chạy màu track, phần đã chạy màu accent.

Khối nền tối

Nền primary-deep, chữ on-primary. Ô thông tin bên cạnh bo góc --radius-lg, khối “Mở Mini App” bo góc --radius-xl.

Bóng chat (trợ lý AI)

Câu hỏi của người dùng: nền primary, chữ on-primary, căn phải. Câu trả lời: nền surface, chữ ink, căn trái. Cả hai nằm trong khối nền primary-deep bo góc --radius-xl.

Thông báo “Chưa hoàn thiện”

Nền primary-deep, bo góc --radius-md, nằm giữa, cách đáy màn hình 24px. Trên điện thoại cách đáy 84px để không bị thanh thao tác che. Dòng tiêu đề màu on-primary-soft, độ đậm 700; dòng lý do màu on-primary, cỡ 15px. Nút đóng 44×44px. Thông báo tự ẩn sau 4 giây và nằm trong vùng role="status" aria-live="polite".

Thanh thao tác ở đáy (chỉ hiện khi màn hình rộng từ 760px trở xuống)

Nền trắng, đường kẻ phía trên màu --color-border. Có hai nút cao 48px: “Việc làm” (kiểu Outline-light, chiếm 1 phần chiều ngang) và “Mở Mini App trên Zalo” (kiểu Primary, chiếm 2 phần). Thêm khoảng đệm env(safe-area-inset-bottom) ở dưới.

Icon

Icon là SVG dạng nét, đặt thẳng trong mã, nét dày 1.6–2.4, màu theo currentColor. Icon chỉ để trang trí thì đặt aria-hidden="true". Không dùng emoji làm icon.

Hình trang trí

Có hai hình: bông hoa tròn (một vòng tròn với 8 nét toả ra) và đường lượn sóng. Vẽ bằng nét primary-soft hoặc line-on-primary, chỉ đặt trên nền primary-deep. Hai hình này chỉ để trang trí, luôn đặt aria-hidden.

8. Chuyển động

Chỉ tạo chuyển động trên transform, opacity và background. Mỗi trang chỉ có một chỗ chuyển động chính, và không có khối nào tự trượt vào khi cuộn. Khi người dùng bật prefers-reduced-motion, tắt mọi chuyển động: hành trình hiện tĩnh, thanh tiến trình hiện đầy, cuộn trang nhảy thẳng tới vị trí.

9. CSS tokens

Không dán tay đoạn nào vào theme/tokens.css — file đó sinh ra từ design-system/tokens.json. Đoạn dưới đây là bản in của token đang hiệu lực, để đối chiếu:

/* theme/tokens.css — FILE SINH RA từ design-system/tokens.json */
:root {
  --c-primary: #1c3179;
  --c-primary-deep: #111d47;
  --c-primary-mid: #2e4fb0;
  --c-primary-soft: #2e4fb0;
  --c-primary-veil: #c2cdf2;
  --c-on-primary: #ffffff;
  --c-on-primary-soft: #dce3fa;
  --c-line-on-primary: #9db2f2;
  --c-cta: #e8b23a;
  --c-on-cta: #1c3179;
  --c-link: #1c3179;
  --c-accent: #c2352b;
  --c-success: #0b7a43;
  --c-success-bright: #19a35c;
  --c-warn-bg: #f4efe3;
  --c-warn-ink: #5b4a1f;
  --c-reward: #5b4a1f;
  --c-ink: #1a1b22;
  --c-ink-soft: #444857;
  --c-muted: #555a6b;
  --c-note: #6b5a2a;
  --c-tag-text: #5b4a1f;
  --c-surface: #ffffff;
  --c-surface-alt: #f4efe3;
  --c-surface-tint: #dce3fa;
  --c-tile-violet: #f4efe3;
  --c-tile-mint: #dce3fa;
  --c-border: #e3e5ee;
  --c-track: #ddd3bc;

  --r-xs: 6px;
  --r-md: 16px;
  --r-lg: 24px;
  --r-xl: 32px;
}

/* app/globals.css nối chúng vào Tailwind, thêm vài hằng số riêng của Website */
@theme {
  --color-primary: var(--c-primary);   /* … đủ 28 vai trò */
  --radius-md: var(--r-md);
}

:root {
  --radius-device: 34px;         /* khung điện thoại ở đầu trang */
  --radius-pill: 9999px;
  --container: 1240px;
  --gutter: 24px;
  --tap-min: 44px;
  --border-control: 2px;
  --shadow-offset: 18px 18px 0 var(--c-accent);
  --focus-ring: 3px solid var(--c-primary);
  --journey-cycle: 9s;
  --notice-hide-after: 4s;
  --lh-display: 1.18;            /* thấp hơn mức này thì dấu tiếng Việt bị cắt */
  --lh-body: 1.6;
}

10. Nên và không nên