# Quy ước cho người đóng góp

Áp dụng khi thêm hoặc sửa component trong `src/` và `components/`. Chạy `node scripts/build.js` trước khi xong: phải in `OK: không có lỗi`.

## Nguyên tắc

1. **Nguồn là sự thật:** chép đúng kích thước, padding, gap, bo góc, cỡ chữ, độ đậm, line-height, thời lượng animation từ game gốc (`css/style.css`, markup trong `js/game.js`). 5px vẫn là 5px. Màu hex của game đổi sang token theo "Bảng đổi màu" ở cuối file; màu nào chưa có trong bảng thì chọn token cùng vai trò gần nhất và ghi trong mục "Nguồn" của README component.
2. **Tệp được phép sửa:** `src/<NN>-<slug>.css|js|d.ts`, `components/<Comp>/README.md`, `components/<Comp>/preview.html`, `tokens.json` (qua `scripts/make-tokens.js`). `components/bundle.*`, `components/index.d.ts`, `tokens.css` và `index.html` do `scripts/build.js` sinh ra, không sửa tay.

## CSS

- Tiền tố `tt-`, kiểu BEM: khối `.tt-button`, biến thể `.tt-button--primary`, phần tử `.tt-button__icon`. Trạng thái ưu tiên thuộc tính gốc (`:disabled`, `[aria-pressed="true"]`, `[aria-selected="true"]`, `[aria-checked="true"]`, `[aria-current="page"]`), còn lại dùng `.is-*` (`is-done`, `is-low`, `is-locked`, `is-empty`, `is-want`, `is-picked`, `is-angry`, `is-shown`).
- Màu, khoảng cách, bo góc, bóng: chỉ `var(--<token>)` với tên token có trong `tokens.json`. Pha màu như game làm thì dùng `color-mix(in srgb, var(--mint) 14%, var(--panel))`. Cấm hex, `rgb()/rgba()/hsl()`, màu theo tên (`white`, `transparent` vẫn được). Biến cục bộ phải tên `--tt-*`.
- Không selector phần tử trần ở cấp cao (`button {}`), không `!important` (chỉ hai ngoại lệ: tắt animation khi `prefers-reduced-motion` và luật nền `:where(.tt-app) [hidden] { display: none !important; }` ở `00-base.css`, để thuộc tính `hidden` luôn thắng `display` của component; vì vậy ẩn / hiện phần tử bằng `hidden` chứ không viết `.tt-x[hidden]` riêng), không phụ thuộc lớp của game gốc. Độ đặc hiệu phẳng: một lớp + trạng thái. Ngoại lệ được phép (BEM chuẩn, trong cùng một khối): biến thể hoặc trạng thái của khối tác động lên phần tử của chính khối đó, `.tt-x--y .tt-x__z` hoặc `.tt-x.is-done .tt-x__z` (0,2,0). Cấm selector chéo khối (`.tt-a .tt-b`) và selector gắn tên thẻ (`button.tt-x`).
- Cỡ chữ lấy theo thang type trong `tokens.json` (2rem, 1.45rem, 1.35rem, 1.3rem, 2.4rem, 1rem, .92rem, .82rem, .78rem, 1.1rem, .9rem, .72rem, .7rem, .66rem; sân khấu 72/24/19/16px) hoặc đúng giá trị nguồn nếu nguồn khác thang. Font kế thừa từ `.tt-app` (Baloo 2, weight 500); không tự đặt font-family.
- Lớp có sẵn ở `src/00-base.css` (dùng lại, không định nghĩa lại): `.tt-app`, `.tt-preview`, `.tt-ico`, `.tt-ico--lg`, `.tt-num`, `.tt-sr-only`, `.tt-row`, `.tt-stack`, `.tt-stage-frame`, `.tt-stage`, `.tt-stage__tint`; keyframes `tt-shake`, `tt-pulse`, `tt-ring`, `tt-slide-in`, `tt-bob`. Base đã có `:focus-visible` (3px `--focus-ring`, offset 2px) và tắt animation khi `prefers-reduced-motion`.
- Phần reset ở base dùng `:where()` để giữ độ ưu tiên bằng 0, một lớp component luôn thắng.

## 5 theme

Mọi component phải đẹp và đọc được ở `data-theme` = `kem`, `nau`, `socola`, `dem` và `hc` (Tương phản cao, do design system thêm, đạt ngưỡng tương phản AAA cho chữ (SC 1.4.6) và 3:1 cho viền, focus, đồ hoạ (SC 1.4.11) trên các preview, kể cả các trạng thái mở bằng JS có `data-audit-click`). Bề mặt và chữ dùng token theo theme (`bg`, `panel`, `line`, `fill-muted`, `ink`, `soft`, `pink`, `pink-d`, `on-pink`, `focus-ring`); các token trạng thái và tranh (`mint`, `warn`, `gold`, `link`, `stage-*`, `patience`, `target`, `pour-low`/`pour-high`, `bin-label-bg`, `toast-success/warn/info/reward`, `timer-ok/soon/overdue`, `urgent-title`…) giữ giá trị của game ở bốn theme gốc nhưng đổi ở `hc`, cùng các token chỉ phục vụ `hc` (`fill-tabs`, `alpha-*`, `shadow-tab-on`, `shadow-edge*`, `shadow-on`, `shadow-fill-edge`); chỉ `counter`, `chalk`, `sign-*`, `awning-white`, `scrim`, `on-fill`, `stage-ground`/`stage-paper`/`stage-ink`, `outline*`, `wood-dark`, `bin-badge`, `pour-mid`, `urgent-bg`, `urgent-sub`, `urgent-bar-from`, `urgent-bar-to`, các token vật thể minigame (`chip-*-bg`, `felt-mid`/`felt-lo`/`felt-line`/`felt-ink`/`felt-money`/`felt-bet`, `plate-hi`/`plate-mid`/`plate-lo`, `die-face`, `tile-win`, `card-*-bg`, `card-den-ink`, `cardback-hi`/`cardback-lo`) và các bóng nhoè là cố định ở cả năm theme. Dùng đúng vai trò trong usage note của từng token.

## Xếp lớp (z-index)

Lớp nổi toàn màn hình xếp theo thứ tự cố định, từ dưới lên: Toast `100000` < Dialog `100050` < UrgentAlert `100060` < Tooltip `100070`. Component mới có lớp nổi phải chọn số trong dải này và ghi lý do trong README; phần tử trong luồng dùng `z-index` nhỏ (≤ 10).

## Danh sách thẻ

Nhóm thẻ lặp lại (UpgradeCard, StaffCard, OnlineOrder, FriendRow…) đặt trong `<ul class="tt-business-list">` / `<ol>` với mỗi thẻ là một `<li>` (danh sách có xếp hạng như bạn bè dùng `<ol>`) để trình đọc màn hình đọc "danh sách N mục". Nhóm thẻ chọn một (GiftCard) dùng `role="radiogroup"` + `role="radio"` `aria-checked` và roving tabindex, không dùng `aria-pressed`. Không đặt `aria-label` lên `span`/`div` không có role: chữ bổ sung dùng `tt-sr-only`. Nút `disabled` vì thiếu điều kiện (thiếu tiền, chưa đủ cấp) có lý do hiển thị bằng chữ và `aria-describedby` trỏ tới lý do đó.

## Huy hiệu tâm trạng

Huy hiệu tâm trạng (khách) dùng PNG trong `assets/` (`stk_heart.png` vui, `ic_angry.png` giận, bình thường không có huy hiệu), không dùng emoji, vì emoji đổi hình theo hệ điều hành. Mọi trạng thái tâm trạng phải kèm chữ `tt-sr-only` hoặc `[data-tt-state]` để không chỉ dựa vào hình hay màu viền. ShipperBadge không có huy hiệu: tâm trạng chỉ là cột mặt trong `ship.webp` (`--mood-*`), cũng kèm chữ `tt-sr-only[data-tt-state]`. Trạng thái mặc định (`is-pickup` của ShipperBadge, `--mood-normal`) không cần CSS riêng.

## Chuyển động

Transition tối đa .25s; nút nổi dùng lò xo `cubic-bezier(.34,1.56,.64,1)` .18s như game; keyframes tự định nghĩa phải có tiền tố `tt-`. Ngoại lệ cho chuyển động của vật thể bên trong minigame (nhấc bát .45s, mờ .35s; lắc bát .12s lặp; nhịp ô trúng .6s lặp): được theo thời lượng của game, kèm ghi chú trong CSS và README component; mọi chuyển động vẫn tắt khi `prefers-reduced-motion`.

## Tiếp cận

Hành động là `<button>` thật; nút chỉ có icon phải có `aria-label`; ảnh có `alt` (ảnh trang trí `alt=""`); thanh tiến độ `role="progressbar"` + `aria-valuemin/max/now` + `aria-label`; dialog `role="dialog" aria-modal="true" aria-labelledby`; toast `role="status" aria-live="polite"`; cảnh báo khẩn `role="alertdialog"` + khoá focus; công tắc `role="switch" aria-checked`; tooltip `role="tooltip"` + `aria-describedby`; nhóm lựa chọn dùng `role="radiogroup"` hoặc `aria-pressed`.

## preview.html

Dòng 1 là marker, `height` xấp xỉ chiều cao nội dung ở bề rộng 400px (gallery đọc `group` và `height` từ đó). Khung:

```html
<!-- @dsCard group="<Nhóm>" height=<N> -->
<!doctype html>
<html lang="vi">
<head>
<meta charset="utf-8">
<title><Comp> — preview</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@500;600;700;800&display=swap">
<script>/* đặt data-theme từ ?theme=kem|nau|socola|dem|hc */</script>
<link rel="stylesheet" href="../../tokens.css">
<link rel="stylesheet" href="../bundle.css">
<script src="../bundle.js"></script>
</head>
<body class="tt-app tt-preview">
  <!-- vài biến thể + trạng thái, nhãn mẫu bằng chữ thường của game -->
  <script>/* tuỳ chọn: gọi window.TTMU.* để chạy hành vi */</script>
</body>
</html>
```

- Phần `<head>` sau link font (script theme, `tokens.css`, `bundle.css`, `bundle.js`) giống hệt nhau ở mọi preview: chép từ một preview có sẵn.
- Không `<style>` chứa màu, không iframe/object/embed/portal/noscript. Ảnh dùng đường dẫn tương đối `../../assets/<Group>/<file>`. Không tràn ngang ở bề rộng 360px. Nội dung là chữ thật của game (tiếng Việt), không lorem ipsum.

## README của component

Tiếng Việt có dấu, giữ thuật ngữ chuyên môn gốc, tối đa 120 dòng. Dòng 1 là `# <Comp>`, câu tóm tắt đứng ngay sau. Trong README, ảnh ghi dạng `assets/<Group>/<file>` (tính từ gốc `design-system/`).

```md
# <Comp>
<Một câu tóm tắt: nó là gì, dùng ở đâu trong game.>

## Khi nào dùng
## Biến thể            (bảng: Biến thể | Lớp | Dùng khi)
## Cấu trúc            (khối html tối thiểu, người dùng tự cung cấp gì)
## Trạng thái          (bảng)
## Hành vi JS          (chỉ khi có: chữ ký TTMU.* và ví dụ)
## Token sử dụng
## Khả năng tiếp cận   (role, bàn phím, screen reader)
## Nên / Không nên     (bảng)
## Nguồn               (selector gốc + file, ví dụ `.big` — css/style.css)
```

## JS

- Mỗi file là MỘT IIFE: `(function(){ 'use strict'; var TTMU = (window.TTMU = window.TTMU || {}); TTMU.xxx = function(...){...}; })();`. Vanilla, không thư viện, không network, không biến global nào ngoài TTMU, không chuỗi `</script` hay `<!--`.
- Hàm nhận phần tử DOM, gắn một lần (đánh dấu `data-tt-bound="1"`), trả về object API hoặc hàm huỷ. Hai hợp đồng khi gắn lại lên phần tử đã gắn: hầu hết hàm trả `null`; `TTMU.alertBanner` và `TTMU.countdown` lưu API trên phần tử và trả lại đúng API đó (idempotent). Muốn đổi tuỳ chọn (ví dụ hạn của Countdown) thì `destroy()` rồi gọi lại. Chữ người dùng nhập hoặc chuỗi động gán bằng `textContent`, không `innerHTML`.
- Quy ước `onChange`: chỉ thao tác của người dùng mới gọi `onChange`, và chỉ khi giá trị thật sự đổi; `set()` / `select()` gọi từ code thì không bao giờ gọi.
- Kiểu viết ở `src/<NN>-<slug>.d.ts`: `export interface TTMU<Slug> { ... }` (xem mẫu `src/00-core.d.ts`). Có sẵn trong core: `TTMU.themes`, `TTMU.setTheme(id, root?)`, `TTMU.getTheme()`, `TTMU.formatMoney(n)`, `TTMU.starString(r)`, `TTMU.fitStage(stageEl, {width,height,maxHeight})`.

## Văn phong

Tiếng Việt thân thiện như game ("bạn", "mình"); tiền theo `TTMU.formatMoney` (25k, 237,5k, 1,25tr, −5k); sao ★☆; giờ 11:10; "Ngày 2". Emoji chỉ dùng đúng chỗ game dùng (🧋 Vào Quầy, 📣 Xin Phước, 🛵 shipper, 🏮 biển tên); icon giao diện ưu tiên PNG trong nhóm Icons.

## Kiểm tra

Đổi màu (token hoặc CSS) phải giữ hai điều: `node scripts/audit.js hc` vẫn 0 lỗi, và `node scripts/audit.js --snapshot-check kem nau socola dem` vẫn "GIỐNG HỆT" (màu của bốn theme gốc không đổi). Cần khác biệt cho `hc` thì thêm token có giá trị theo theme trong `scripts/make-tokens.js` (alias token cũ ở bốn theme gốc), không viết `[data-theme="hc"]` trong `src/*.css`; chỗ cần nền trung tính dùng `fill-muted`, không lấy `line` làm nền. Thêm preview mới thì chạy lại audit để preview đó được đo. Trạng thái chỉ có sau thao tác JS (dialog mở, toast, splash sau khi tải, PourGauge trúng / trượt) chỉ được đo khi nút kích hoạt trong preview có `data-audit-click` (giá trị `click`, hoặc `hold:<ms>`, nhiều bước cách nhau bằng `|`); thêm thuộc tính này không làm đổi snapshot.

`node scripts/build.js` kiểm tra: marker dòng 1, thẻ cấm, không còn đường dẫn blob cũ, mọi `src`/`href`/`url()` tương đối trỏ tới file có thật, không màu literal trong preview, mọi lớp `tt-` dùng trong preview đều có trong `bundle.css`, cú pháp `bundle.js`, lint từng file `src/*.css` (màu literal, `var(--…)` không phải token).

## Bảng đổi màu (hex game → token)

| Hex game | Token | | Hex game | Token |
|---|---|---|---|---|
| `#fdf3e4` | `bg` | | `#ea580c` | `street` |
| `#fffaf2` | `panel` | | `#f97316` | `street-hi` |
| `#ead7bd` | `line` | | `#ffedd5` | `street-line` |
| `#3a2317` | `ink` | | `#4a90c8` | `coach` |
| `#7a5a48` | `soft` | | `#2f6c9c` | `coach-d` |
| `#ef6f8e` (`--pink`) | `pink` | | `#f4e2cc` | `stage-ground` |
| `#c24c69` (`--pink-d`) | `pink-d` | | `#fffaf0` | `stage-paper` |
| `#fff` chữ trên pink | `on-pink` | | `#4a3526` | `stage-ink` |
| `#fff` chữ/viền trên nền đậm cố định | `on-fill` | | `#6b4e38` | `stage-soft` |
| `#fff` sọc mái hiên | `awning-white` | | `#8a6f58` | `stage-muted` |
| `#4fa883` | `mint` | | `#d8c6ae` | `stage-track` |
| `#e2574c` | `warn` | | `#ef7f98` | `stage-pink` |
| `#f0b43c` | `gold` | | `#c95c76` | `stage-pink-d` |
| `#8a5a3b` | `counter` | | `#c2506c` | `stage-accent` |
| `#a8714c` | `counter-top` | | `#4a3120` | `outline` |
| `#2f4a3a` | `chalk` | | `#5a4030` | `outline-soft` |
| `#f4efe2` | `chalk-ink` | | `#5b3f25` | `wood-dark` |
| `#fff7e8` | `sign-paper` | | `#f3d6b0` | `bin-badge` |
| `#8a3a50` | `sign-ink` | | `#8fcf8f` | `patience` |
| `#2b78c5` | `link` | | `#f4b73a` | `pour-mid` |
| `#fde2e2` / `#b83a3a` | `fresh-1-bg` / `fresh-1-ink` | | `#5aae86` | `target` |
| `#fdf0cf` / `#8a6412` | `fresh-3-bg` / `fresh-3-ink` | | `#ff6a00` | `want` |
| `#b8433a` | `toast-alert` | | `rgba(40,20,10,.65)` | `scrim` |
| `0 4px 0 var(--pink-d)` | `shadow-press` | | `0 1px 0 var(--pink-d)` | `shadow-press-down` |
| `0 0 0 2px var(--pink)` | `shadow-ring-pink` | | `0 3px 0 rgba(0,0,0,.12)` | `shadow-sign` |
| `0 4px 0 rgba(0,0,0,.12)` | `shadow-board` | | `0 16px 40px rgba(0,0,0,.35)` | `shadow-modal` |
| `0 6px 22px rgba(0,0,0,.35)` | `shadow-toast` | | `0 2px 8px rgba(234,88,12,.35)` | `shadow-street` |
| `0 4px 0 #2f6c9c` | `shadow-coach` | | `0 0 0 3px #fff,0 0 0 6px #ff6a00` | `shadow-want` |
| `0 0 0 4px #5aae86` | `shadow-pick` | | | |

Spacing token: `space-2/4/6/8/10/12/14/16/22/26`, `space-openbar` (90px). Radius token: `radius-3/6/8/10/12/14/16/20/24`, `radius-round` (50%), `radius-pill` (999px). Giá trị nguồn lệch khỏi thang (5px, 7px, 9px…) thì giữ nguyên số px.