@haposoft/cafekit 0.16.7 → 0.18.0

package/src/claude/skills/ui-ux/references/rules-color.md

@@ -0,0 +1,623 @@
+# Màu — luật M
+
+Đây là **nguồn duy nhất** cho mọi luật về màu, viền và bóng. `SKILL.md` chỉ chép
+một dòng tóm tắt kèm số hiệu; giải thích, ngoại lệ và bằng chứng nằm ở đây.
+
+Luật có dấu ⚑ là chưa qua vòng test nào.
+
+---
+
+## Nền và thứ bậc bề mặt
+
+**M1. Nền trang xám nhạt, không trắng tinh. Card mới trắng.**
+
+*Gu flat — phong cách khác đã chọn theo `P1` thì xem `P2` trong `references/styles.md`.*
+
+**M2. 95% trung tính, 5% điểm nhấn.**
+
+*Gu flat — phong cách khác đã chọn theo `P1` thì xem `P2` trong `references/styles.md`.*
+
+Đây là luật quan trọng nhất trong nhóm, và là thứ quyết định một màn hình trông
+có chủ ý hay trông như chưa ai quyết định gì.
+
+Bằng chứng thật (một dự án): một trang tích dần tới **năm màu
+nền** cho năm loại khối — vàng be cho dặn dò, đỏ hồng cho nội quy, xanh nhạt cho
+quà và nhật ký, tím indigo cho chip quà, cộng xanh/vàng của trạng thái. Khối nào
+cũng đòi được chú ý nên **không khối nào nổi**, và trang đọc ra như "rainbow UI".
+
+Hệ quả ngược cũng đã dính: gỡ hết màu đi thì thẻ "dặn dò" trắng nằm
+giữa các thẻ task trắng, bị đọc lẫn thành một task. Nên trung tính **không phải
+là không có điểm neo**:
+
+> Nổi bằng **một điểm màu nhỏ**, không tô cả khối. Giữ thẻ trắng, đặt icon trong
+> một **ô vuông nhạt 28px** kèm nhãn cùng màu.
+
+**M3. Đúng một màu nhấn cho cả app.** Nút chính, link, control đang bật (checkbox,
+switch, chip lọc đã chọn) dùng chung nó. Mục **điều hướng** đang chọn (sidebar, tab,
+trang hiện tại) thì dùng nền xám hoặc vạch `--foreground`, không màu nhấn (bảng
+công thức phần tử bên dưới, `small-controls.md`). Màu thứ hai phải xin phép.
+
+---
+
+## Màu nói gì
+
+**M4. Màu để báo trạng thái, không để phân loại.**
+
+*Có màu công thức B — ô icon card số liệu, ô icon đầu dòng theo loại và chuỗi biểu đồ dashboard được tô màu phân loại, xem `P12` trong `references/styles.md`.*
+
+> `M4` và `M5` là **gu mặc định cho dự án chưa có ngôn ngữ màu**. Dự án đã tô màu
+> theo cách riêng (đếm ở `P4`) thì theo dự án; chỉ giữ các luật về nghĩa và đọc được
+> liệt kê ở đầu `principles.md` (đỏ cho lỗi và phá huỷ, một bảng trạng thái, màu không
+> đứng một mình, tương phản 4.5:1).
+
+Bảng màu của MỘT màn hình, không thêm:
+
+| Màu | Chỉ dùng cho |
+| --- | --- |
+| Xám trung tính | Mọi thứ còn lại: khung, chữ phụ, badge, icon, viền |
+| Màu nhấn | Nút hành động chính khi thật cần nổi, mục đang chọn, link. **Không** cho badge số đếm, **không** cho trạng thái |
+| Xanh lá | "Đang ổn", "đã xong": badge, thanh tiến độ xong (`M7`). Cố định, không lấy màu nhấn |
+| Hổ phách | "Cần chú ý": quá hạn, nộp trễ, bỏ lỡ |
+| Đỏ lỗi — `red` | Lỗi thật mà người dùng phải xử lý: bài bị từ chối, lỗi form |
+| Đỏ nguy hiểm — `rose` | Hành động trả lời "có" ở một trong ba câu của `I4` (mất dữ liệu, kết thúc thứ đang chạy, cắt quyền): xoá, huỷ gói, thu hồi khoá, rời nhóm, đăng xuất. Lấy lại được không làm việc đó hết đỏ. Nút đứng riêng thì nền mờ + chữ đỏ luôn hiện; mục menu thì chỉ đỏ khi rê vào (`I4`) |
+
+Hai sắc đỏ là cố ý, không phải gõ nhầm — xem `M30`.
+
+Cách áp: định thêm một màu nền cho một loại khối thì **dừng lại và hỏi — màu đó
+báo trạng thái gì?** Không trả lời được thì nó là trang trí, dùng xám.
+
+Nội quy không phải lỗi → không đỏ. Quà không phải trạng thái → không màu riêng.
+
+**M5. Phân loại khối bằng icon + chữ + viền, không bằng nền màu.**
+
+Dặn dò, nội quy, quà, nhật ký đều là thẻ trắng viền mảnh; cái gì là gì do **icon
+lucide + nhãn** nói. Thứ bậc đến từ cỡ chữ, độ đậm và khoảng cách: chữ chính đen,
+chữ phụ xám; giữa các khu vực thoáng, trong từng thẻ gọn.
+
+**M6. Một tín hiệu cho một ý.** Nhãn cộng ô màu đã nói "lưu ý" thì không thêm
+badge "Lưu ý" nữa. Cùng tinh thần với `F6`: phần tử nổi bật chỉ cần một dấu hiệu.
+
+**M7. Trạng thái đứng riêng một ô thì là badge màu. Nằm lẫn trong câu thì chữ màu.**
+
+Cột trạng thái trong bảng, góc thẻ kanban, đầu trang chi tiết: **badge pill nền
+nhạt, chấm tròn + chữ cùng tông**. Liếc dọc một cột 20 dòng thì mắt bắt màu nhanh
+hơn bắt chữ; chấm xám + chữ đen thì cả cột trông như nhau ("Đang giao dịch"
+với "Ngừng giao dịch" chỉ khác nhau ở độ mờ của một chấm 4px).
+
+```html
+<span class="inline-flex items-center gap-1.5 whitespace-nowrap rounded-full bg-emerald-50 px-2.5 py-1 text-xs font-medium text-emerald-700">
+  <span class="size-1.5 rounded-full bg-current"></span>Đang giao dịch
+</span>
+```
+
+Bốn tông, không thêm. Trạng thái nào vào tông nào theo **nghĩa**, không theo sở thích:
+
+| Tông | Nền / chữ | Token (không Tailwind) | Nghĩa | Ví dụ |
+| --- | --- | --- | --- | --- |
+| Xám | `bg-zinc-100 text-zinc-600` | `--neutral-bg` / `--neutral` | Chờ, nháp, chưa bắt đầu, trung lập | Tiềm năng, Nháp, Cần làm |
+| Xanh lá | `bg-emerald-50 text-emerald-700` | `--success-bg` / `--success` | Đang ổn, đang chạy, đã xong | Đang giao dịch, Hoạt động, Đã thanh toán, Đã giao |
+| Hổ phách | `bg-amber-50 text-amber-700` | `--warning-bg` / `--warning` | Cần chú ý | Quá hạn, Sắp hết hạn, Tạm dừng |
+| Đỏ | `bg-red-50 text-red-700` | `--error-bg` / `--error-strong` | Đã dừng, thất bại, bị từ chối | Ngừng giao dịch, Đã huỷ, Lỗi |
+
+**Dự án có dark mode thì mọi class `-700` của bảng trên đi kèm bản `dark:` `-400`**
+(`text-red-700 dark:text-red-400`; **riêng hổ phách là `text-amber-700 dark:text-orange-400`**, xem
+dưới; không Tailwind thì token, đã lật sẵn). `-700` không tự
+đổi ở nền tối: chữ trạng thái còn 2,9–3,7:1 (`red-700` 2,9, `emerald-700` 3,5, `amber-700`
+3,7). Sót một chỗ là cùng một nghĩa ra hai sắc trên một dòng ("Khẩn cấp" `text-amber-700` cam sẫm 3,74:1 cạnh "Quá hạn 3 ngày"
+`dark:text-amber-400` vàng sáng). Gom mỗi tông vào một helper để
+không phải nhớ từng chỗ.
+
+**Bản tối chọn theo sắc, không theo số bậc.** Lên bậc sáng hơn thì phần lớn thang Tailwind giữ sắc
+(đỏ, xanh lá, xanh dương, tím lệch 0–6° OKLCH), riêng **amber trôi sang vàng**: `amber-700` 49°,
+`amber-400` 84°. "Quá hạn" cam ở bản sáng thành vàng ở bản tối, đọc ra hai màu, hai nghĩa. Hổ phách tối dùng **`orange-400`** (56°, lệch 7°, 7,9:1 trên card); nền
+badge giữ `amber-500/15` (nền mờ không đọc ra sắc như chữ). Màu khác ngoài bảng này (avatar, chart, nhãn
+tự chọn) cũng vậy: lệch quá ~20° OKLCH với bản sáng thì đổi họ màu gần sắc hơn. Probe `--dark` đo cặp này.
+
+**Mọi badge có thêm `ring-1 ring-inset ring-black/5`** (nền tối `ring-white/10`). Nền badge
+nhạt tới mức chỉ chênh vài phần trăm với nền dưới nó: `zinc-100` (#f4f4f5) đặt lên dòng
+bảng đã chọn hay nền trang (#f4f4f6) là mất hẳn khung, "Tiềm năng" chỉ còn chấm với chữ.
+Vòng trong 5% giữ khung ở mọi nền mà không nặng thêm.
+
+**Một luồng có cả bước "đang" lẫn bước "xong" thì xanh dành cho "xong".** Đơn hàng:
+Chờ xử lý → **hổ phách** (người bán phải làm gì đó), Đang giao → **xám** (đang chạy nhưng
+không ai phải làm gì), Đã giao → **xanh**, Đã huỷ → **đỏ**. Để "Đang giao" cũng xanh thì
+hai trạng thái khác nghĩa trùng màu (`N2`). "Đang giao dịch" của khách hàng vẫn xanh vì
+luồng đó không có bước "xong".
+
+**Luồng có từ hai trạng thái cùng tông thì chấm đổi thành icon, mỗi trạng thái một hình.**
+Bốn tông không đủ cho luồng công việc: theo đoạn trên thì Cần làm và Đang làm cùng xám, và
+bảng nhóm theo trạng thái ra ba nhóm xám một nhóm xanh, liếc không tách được nhóm nào với
+nhóm nào. Các app quản lý công việc lớn tách bằng **hình**, không thêm màu:
+
+| Trạng thái | Tông | Icon lucide | Vì sao |
+| --- | --- | --- | --- |
+| Cần làm | xám | `circle` | vòng rỗng: chưa bắt đầu |
+| Đang làm | xám | `circle-dot` | có lõi: đang có người làm, không ai khác phải làm gì |
+| Chờ duyệt | hổ phách | `circle-ellipsis` | người duyệt phải làm gì đó, cùng lý với "Chờ xử lý" |
+| Xong | xanh lá | `circle-check` | |
+| Đã huỷ | đỏ | `circle-x` | |
+
+Icon `size-3.5` trong badge (thay chấm), `size-4` ở đầu nhóm và đầu cột kanban, màu
+`-600` cùng tông (`text-zinc-500` cho xám). Một bảng này dùng cho mọi bề mặt (`D2`).
+
+Nền tối: class Tailwind thì thêm `dark:` (nền `-500/15`, chữ `-400`), token thì
+khối `.dark` trong `tokens.css` đã đổi sẵn.
+
+- Xanh lá là màu **cố định**, không lấy màu nhấn. Màu nhấn mặc định gần đen, badge đen đặc giữa bảng trông như nút bấm.
+- Chữ `-700`, không `-500`: chữ nhỏ trên nền nhạt cần đậm để đạt tương phản (`P3`).
+- Không `border`. Vòng trong `ring-black/5` ở trên là khung giữ badge không tan vào nền, không tính là tín hiệu thứ hai (`M6`).
+- Cả app một bảng ánh xạ, xem `D2` trong `system.md`.
+
+Nhãn **nằm trong dòng chữ phụ** ("Hằng tuần · quá hạn 2 ngày") thì vẫn là chữ màu,
+không nền. Pill chen giữa câu làm dòng chữ gồ lên.
+
+---
+
+## Ngoại lệ đã duyệt
+
+**M8. Màu mã hoá dữ liệu không tính vào ngân sách một màu nhấn.**
+
+Tag phân loại, nhãn ngành, nhãn mô hình được phép nhiều màu, vì màu ở đó **mang
+thông tin**. Bốn điều kiện, thiếu một là bỏ:
+
+- Chỉ cho phân loại thật, thứ mà người ta cần liếc là phân biệt được.
+- Luôn **pastel nhạt**: nền khoảng 10%, chữ đậm cùng tông, viền một bậc đậm hơn nền.
+- **Một nhãn một màu cố định** trong cả app. "Technology" xanh dương thì ở đâu cũng xanh dương.
+- Không lan sang nút, nền khối, hay đường kẻ.
+
+Đặt tên thang màu phân loại **khác tên trạng thái**. Dự án thật tách riêng
+`iris` / `magenta` / `coral` thay vì dùng lại `accent` / `danger`, để badge đỏ
+"B2C" không bị đọc nhầm thành lỗi.
+
+**M9. Biểu tượng quen thuộc được giữ màu của nó, dù đó không phải trạng thái.**
+
+Chủ dự án duyệt, sau khi trung tính hoá làm mất nghĩa:
+
+- Huy chương top 3 tô đặc vàng / bạc / đồng — màu **trên icon**, không tô thẻ.
+- Thẻ hạng nhất viền vàng, **nền vẫn trắng**. Nền vàng nhạt ra màu be, đọc như thẻ cũ hoặc thẻ đã khoá. Đã thử và đã bỏ.
+- Ngọn lửa chuỗi ngày tô đặc: ruột vàng, viền cam. Lửa xám nét mảnh chìm hẳn.
+- Dấu `*` của trường bắt buộc tô đỏ. Không phải lỗi, nhưng "`*` đỏ = bắt buộc" là quy ước phổ biến tới mức xám lại khó đọc.
+
+Nguyên tắc chung: khi màu trung tính làm **một biểu tượng mất nghĩa**, chọn nghĩa,
+nói một câu lý do, rồi ghi ngoại lệ vào đây.
+
+**M10. Nội dung người dùng tự viết thì không kiểm soát màu.** SOP, ghi chú có
+emoji, chữ đỏ trong markdown — chỉ làm KHUNG bao quanh trung tính, đừng đi sửa
+ruột.
+
+**M34. Thứ người dùng tạo ra thì có màu nhận diện.** Dự án, board, workspace, danh
+mục, cột kanban, kênh: thứ người dùng tự đặt tên, hiện ở nhiều chỗ, và cần nhận ra
+bằng một cái liếc trong danh sách dài. App một màu nhấn nhìn gọn nhưng dễ đơn điệu;
+điểm màu nên nằm ở **dữ liệu**, còn **khung** (nút, sidebar, header, ô nhập) vẫn một
+màu nhấn như `M2`. Khác `M8`: `M8` là nhãn phân loại gắn lên một mục, `M34` là màu
+của chính thực thể. Một card có thể mang cả hai.
+
+- **Khi nào dùng:** app có thực thể như trên, và nó xuất hiện từ hai chỗ trở lên (sidebar, bảng, breadcrumb, ô chọn) hoặc có từ năm cái trở lên. Không có thì thôi, đừng bịa ra thực thể để có chỗ tô. Có thì làm luôn, không hỏi.
+- **Sáu sắc của avatar**, cùng thứ tự (`components/avatar.md`): emerald, sky, indigo, pink, amber, violet. Không thêm sắc, không `red` / `rose` (`M30`).
+- **Màu nằm trên dấu nhỏ**, không trên mảng lớn: chấm tròn `size-2` sắc `-500` (nền tối `-400`) cạnh tên; ô vuông bo góc chữ cái đầu theo khuôn avatar; dải `h-1` ở đỉnh card hay đầu cột; ảnh bìa người dùng tải lên. **Không** tô nền cả card, nền dòng, nền cột, không tô chữ tên.
+- **Màu là dữ liệu, không tính lúc render.** Tạo mới thì có ô chọn sáu màu, mặc định lấy theo `id` như avatar; lưu lại cùng thực thể. Ở sidebar, bảng, breadcrumb, ô chọn đều cùng một màu.
+- **Tên luôn hiện cạnh màu.** Màu giúp liếc, không thay chữ; chấm và ô vuông để `aria-hidden`.
+- **Trạng thái của khung không đổi:** mục sidebar đang chọn vẫn nền `bg-secondary` trung tính (`checklist.md`, mục Sidebar), chấm giữ nguyên màu, không đổi sang màu thực thể.
+- Không tính vào ngân sách một màu nhấn (`budgets.md`). Dự án đã có cách tô riêng cho thực thể thì theo họ.
+
+```
+  DỰ ÁN                         ┌─────────────────────┐
+  ● Website khách A             │▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔│ ← dải h-1 màu dự án
+  ● App nội bộ                  │ Sửa form đăng ký     │
+  ● Marketing Q4                │ [Bug] [Gấp]          │ ← nhãn M8
+                                └─────────────────────┘
+```
+
+**M11. Chữ chỉ ba sắc độ.** Chữ chính, chữ phụ, và màu nằm trên nền nhấn.
+
+Ngoại lệ duy nhất: **mục điều hướng lúc chưa rê/chưa chọn** dùng
+`foreground/70`, để hover có chỗ "sáng lên" mà lúc thường vẫn đọc rõ. Dùng
+`--muted` ở đó thì tên mục mờ quá trên nền trắng.
+
+⚠️ Bẫy đã dính ở dự án thật: token tên `--text-muted` bị alias về `--text-normal`,
+tức "chữ phụ" và "chữ chính" cùng một màu đen. Đừng tin tên token — mở giá trị
+thật ra xem. Xem `refactor.md` luật L3.
+
+**M12. Không gradient.** Ngoại lệ duy nhất: **ảnh đại diện và dấu hiệu nhận diện**
+— avatar người dùng, icon workspace, logo tổ chức. Chúng là hình tròn hoặc vuông
+nhỏ dưới 40px, và gradient ở đó đóng vai ảnh chứ không đóng vai nền.
+
+*Gu flat — phong cách khác đã chọn theo `P1` thì xem `P2` trong `references/styles.md`.*
+
+Không bao giờ cho nút, card, nền trang, hay chữ (`bg-clip-text text-transparent`).
+
+---
+
+## Viền và bóng
+
+> **⚠️ Đảo luật.** Bản cũ của skill này cấm viền card và bắt tách khối bằng chênh
+> lệch nền. **Luật đó đã bỏ.** Chủ dự án chốt phong cách "đường tóc 1px + bo góc,
+> không bóng". Đừng hồi sinh luật cũ.
+
+**M13. Tách khối bằng đường tóc 1px + bo góc, không bằng bóng.**
+
+*Gu flat — phong cách khác đã chọn theo `P1` thì xem `P2` trong `references/styles.md`.*
+
+Trang phẳng, sạch; thứ bậc đến từ cỡ chữ, độ đậm và màu chữ.
+
+*Ngoại lệ: card đứng một mình giữa trang trống — xem `M29`.*
+
+| Phần tử | Công thức |
+| --- | --- |
+| Thẻ / khung | trắng, viền 1px xám rất nhạt, bo 16px `rounded-2xl` (`F1`), **không bóng** |
+| Danh sách nhiều mục | MỘT khung, các dòng chia bằng `divide-y`. Dòng tiêu đề và dòng hành động cuối nằm TRONG khung |
+| Khối tóm tắt phụ | nền xám nhạt + viền, bo như thẻ |
+| Mục sidebar, cây thư mục đang chọn | nền `--secondary` + `font-medium`, **không viền**, không màu nhấn; rê vào `--background`, mục chưa chọn không nền. Đang chọn đậm hơn nền rê một bậc (`I10`, `I15`) |
+| Tab ngang trên bảng / danh sách | tab đang chọn **nền `--secondary`, viền trong suốt** (không nền trắng, không `--surface-hover`: trên card trắng liếc không thấy), mọi tab có `border`, mục chưa chọn `border-transparent`. Xem "Thanh tab" trong `components/small-controls.md` |
+| Ô nhập | viền — đây là chỗ viền đúng vai nhất, người ta phải nhìn ra ranh giới vùng gõ được |
+
+**M14. Hai token viền, chia theo vai trò. Không có cái thứ ba.**
+
+| Token | Cho | Vì sao |
+| --- | --- | --- |
+| `--border` | Viền card, khung dropdown, đường chia trong danh sách và menu, **đường kẻ dưới đầu sidebar và dưới header** (cùng màu vạch trong menu, chủ dự án chốt, `layouts/app.md`) | **Trang trí**: chỉ vạch ranh giới, nhạt được bao nhiêu thì nhạt |
+| `--border-strong` | **Viền ô nhập**, **viền nút outline**, select, viền card khi hover, đường kẻ nằm trên nền trang xám (dưới hàng tab khu cài đặt), kẻ dọc sidebar **chỉ khi vùng nội dung cũng trắng** (`layouts/app.md`) | **Chức năng**: ô nhập và nút outline cùng nền trắng với card, viền là thứ duy nhất báo "đây là chỗ gõ", "đây là chỗ bấm" (`I8`) |
+
+Trong mỗi nhóm thì mọi chỗ dùng chung đúng một token, để đường tóc không chỗ
+đậm chỗ nhạt. Muốn viền card nhạt đi thì hạ `--border`, ô nhập không nhạt theo.
+
+Checkbox, radio chưa chọn cũng dùng `--border-strong`, cùng độ đậm với ô nhập.
+
+Nền tối giữ đúng hai vai đó, cả hai là `rgba` mờ: `--border` 1.23:1 trên card, `--border-strong`
+1.33:1 (đừng dùng lại `0.2`: 1.47:1, dòng bảng thành lưới kẻ ô). Ô nhập ở nền tối
+**giữ viền** `--border-strong` (`M32`).
+
+**Dự án đã có token viền riêng** (dựng mới trong dự án có sẵn, hai chế độ dựng lại): xám
+viền là **dáng, không phải vai màu** (`review.md`), nên xếp token của họ vào hai vai trên
+chứ không giữ cách bản cũ dùng. Bậc nhạt nhất của dự án cho vai trang trí (viền card, khung
+dropdown, đường chia). Đường kẻ khung app: **đoạn dưới đầu sidebar và đoạn dưới header
+cùng một token**, vì hai đoạn nối thành một đường (probe: "đường ngăn thẳng hàng mà khác
+màu"). Bậc nào đậm cỡ `#e4e4e7` trở lên (~1.25:1 trên trắng, mức đã bị chê "đường kẻ sidebar
+đậm") thì không dùng cho đường kẻ khung và viền card, chỉ cho ô nhập, nút
+viền. Đã dính: vạch dưới logo `border-light` `#f1f5f9` nối vào
+vạch dưới header `border` `#e2e8f0`, card lọc, card danh sách, card chi tiết cũng
+`#e2e8f0`: đường ở sidebar ổn, ngoài thì đậm, người xem tưởng brand bắt vậy.
+
+> Đã thử làm đậm viền điều khiển cho đạt 3:1 (WCAG 1.4.11): ô nhập,
+> select, nút outline lên `#8a8a91`; checkbox, radio lên `--muted`; track công
+> tắc lên `muted/75`. Chủ dự án xem thật thấy **đậm và xấu**, trả về hết.
+> Đừng đề xuất lại cho dự án thường; chỉ dự án bắt buộc AA (xem `P3`).
+
+⚠️ **Đừng lấy `--border` cho ô nhập hay nút outline để "cho đồng bộ".** Hạ
+`--border` cho card và dropdown nhẹ đi là ô nhập và nút tan luôn vào nền. Đã xảy
+ra thật: `--border` hạ từ `#f3f3f4` xuống `#f7f7f8` cho khung dropdown,
+nút outline đang dùng chung token nên trông như đã bị khoá.
+
+⚠️ Thiếu class màu viền thì Tailwind v4 để `border-color: currentColor` — nút chữ
+đen sẽ ra **viền gần đen**. Thấy viền đậm bất thường thì kiểm chỗ này trước khi
+nghi mã màu.
+
+**M15. Bóng CHỈ cho lớp nổi.**
+
+*Gu flat — phong cách khác đã chọn theo `P1` thì xem `P2` trong `references/styles.md`.*
+
+Modal, command palette, dropdown, popover, toast được đổ bóng vì chúng nằm **trên**
+trang. Mọi thứ nằm **trong** trang thì không.
+
+Bóng lớp nổi đi qua hai token, không viết `shadow-lg`, `shadow-xl` trần: `shadow-popover`
+(dropdown, menu, popover, toast) và `shadow-modal` (modal, panel trượt, command palette).
+Nền sáng chúng bằng đúng `shadow-lg` / `shadow-xl`; nền tối đậm hơn (`M23`). Khung nào
+cũng `border border-border`. Bảng nền của từng khối ở đầu `layouts/overlay.md`.
+
+Định thêm `shadow-*` cho khối nằm trong trang → thử viền trước, xem có đủ tách
+khối không. Gần như luôn là đủ.
+
+*Ngoại lệ: card đứng một mình giữa trang trống — xem `M29`. Ô đang chọn của tab
+`segmented` (phím nổi trên rãnh chìm), dùng đúng hai token `--shadow-segment-*` —
+xem "Thanh tab" trong `components/small-controls.md`.*
+
+**M16. Không đẻ token viền mới từ màu nhấn.**
+
+Viền tĩnh chỉ có token viền thường (và tối đa một bậc đậm hơn). Viền trạng thái
+chỉ có `--border-focus`, và nó chỉ hiện lúc focus.
+
+Thấy mình sắp viết `--primary-ring`, `--accent-border` là dấu hiệu đang muốn nhấn
+một khối bằng viền — mà nhấn bằng viền là cách rẻ nhất. Đã xảy ra thật: một bản
+dựng tự chế `--primary-ring: rgba(233,237,245,0.22)` rồi viền card nổi bật, trên
+nền tối trông sáng chói.
+
+**M17. `ring` khi không được đụng bố cục, `border` cho phần còn lại.**
+
+`border` ăn vào hộp theo `box-sizing: border-box` nên phần tử cỡ cố định sẽ co
+lại. Cần đường bao quanh avatar, quanh ô vuông cỡ chuẩn thì dùng `ring-1`.
+
+**M18. Phần tử con trong hàng có hover không được trùng token với nền hover của hàng.**
+
+Hàng hover đổi nền (luật `I10`: `--item-hover` hoặc `--surface-hover`). Nếu ô vuông trạng thái, checkbox hay
+avatar bên trong cũng dùng đúng token đó làm nền, hoặc chỉ có viền nhạt, thì rê
+chuột vào là chúng **biến mất**.
+
+*Cách kiểm:* rê chuột lên hàng, đếm xem còn nhìn thấy đủ mọi thứ không.
+
+---
+
+## Bo góc lồng nhau
+
+**M19. Bo lồng nhau: ngoài = trong + khoảng cách giữa hai mép.**
+
+```
+R_ngoài = r_trong + d        d = padding của khung ngoài + độ dày viền (nếu có)
+```
+
+**Vì sao:** hai góc chỉ trông song song, khe hở đều nhau suốt đường cong, khi
+chúng có **chung một tâm**. Công thức trên chính là điều kiện để hai tâm trùng
+nhau. Lệch khỏi nó thì khe hở ở góc khác khe hở ở cạnh:
+
+| Bán kính trong | Khe hở ở góc | Trông |
+| --- | --- | --- |
+| **Bằng** bán kính ngoài (12 trong 12) | **≈ 1.4 × d**, rộng hơn ở cạnh | Góc phình ra, như hai hình không khớp |
+| **= R − d** | **= d**, bằng đúng ở cạnh | Song song, gọn |
+| Nhỏ hơn nhiều, hoặc vuông | Hẹp hơn d, có thể về 0 | Góc trong bị ép sát, chọc vào đường cong ngoài |
+
+**Các cặp hay dùng, đều nằm trên thang Tailwind:**
+
+| Khung ngoài | Padding | Phần tử trong |
+| --- | --- | --- |
+| `rounded-xl` 12px | `p-1` 4px | `rounded-lg` 8px |
+| `rounded-2xl` 16px | `p-1` 4px | `rounded-xl` 12px |
+| `rounded-2xl` 16px | `p-2` 8px | `rounded-lg` 8px |
+
+Cả ba cặp chỉ dùng bậc có trong thang bốn bậc của `F1`. Công thức ra một số
+ngoài thang (ví dụ `p-1.5` ra 6px) thì **đổi padding cho khớp thang**, đừng đẻ
+thêm bậc bo góc.
+
+**Chỉ áp khi hai mép ở gần nhau** — khi `d` không lớn hơn `R`. Dropdown, menu,
+thanh tab dạng viên thuốc, ô nhập có nút bên trong: đều là ca này, và mắt so hai
+góc với nhau ngay.
+
+**Khoảng cách lớn thì bỏ công thức.** Card `rounded-2xl` 16px với `p-5` 20px chứa
+một nút: công thức ra `16 − 20 = −4`. Hai góc cách nhau quá xa để mắt so, nên dùng
+bo theo vai trò (`F1`): card 16px, nút và ô nhập 12px, control nhỏ 8px. Đừng ép
+công thức ra số âm hay 0.
+
+Có viền 1px thì `d` cộng thêm 1. Lệch 1px không ai thấy, nên cứ lấy bậc gần nhất
+trên thang.
+
+Không trộn nút bo tròn hẳn với nút bo vuông trong cùng một nhóm; badge trạng thái
+là ngoại lệ.
+
+---
+
+## Dark mode
+
+**M20. Mặc định chỉ làm light mode.** Dark mode là việc gấp đôi và gấp đôi chỗ
+phải kiểm tương phản. Chỉ làm khi người dùng nói cần, và hỏi một câu lúc giao.
+Làm thì theo đủ `M21`–`M23`, `M31`–`M33`, và khối `.dark` của `tokens.css`.
+
+*Gu flat — phong cách khác đã chọn theo `P1` thì xem `P2` trong `references/styles.md`.*
+
+**M21. Tầng nổi sáng dần ở nền tối; vùng tô là lớp phủ, giữ độ chênh với nền phía sau
+chứ không giữ chiều.**
+
+Hai loại bề mặt, hai cách đổi theme:
+
+| Loại | Gồm | Nền sáng | Nền tối |
+| --- | --- | --- | --- |
+| **Tầng** | nền trang → card → lớp nổi nhỏ (`--surface-overlay`) | trang xám, card và lớp nổi trắng | **sáng dần**: `#05060f` → `#0f111a` → `#171a26`, mỗi bậc ~1.07–1.09:1 |
+| **Vùng tô** | nút phụ, mục / tab đang chọn (`--secondary`), nền rê (`--item-hover`, `--button-hover`), rãnh, chip | phủ **tối** hơn nền phía sau | phủ **trắng mờ**, **sáng** hơn nền phía sau |
+
+Vùng tô ở nền sáng tối hơn card, ở nền tối sáng hơn card: đúng ở cả hai. Thứ phải giữ
+là **độ chênh** với nền ngay sau nó, ngang nhau giữa hai theme (đang chọn `--secondary`
+1.22:1 cả hai bản; nền rê 1.10 / 1.12:1). Đây là cách gần như mọi bộ thiết kế lớn làm
+(7/7 bộ có số liệu).
+
+- **Vùng tô nền tối viết bằng trắng phủ mờ** (`white/4`–`white/10`), không bằng xám đặc.
+  Phủ mờ thì đặt trên nền trang, card hay lớp nổi đều đúng; xám đặc chỉ đúng trên một nền.
+  Trong code: lớp phủ `bg-foreground/5` (tự đảo theo theme) hoặc token, không `dark:bg-zinc-800`.
+- **Không dùng `--background` làm nền rê hay nền chọn.** Ở nền tối nó tối hơn card, rê vào
+  là chìm xuống 1.07:1, gần như không thấy. Nền rê mục thụt vào là `--item-hover` (`I10`).
+- **Đang chọn đậm hơn rê đúng một bậc ở cả hai theme** (`I10`, `I15`).
+
+*Cách kiểm:* liệt kê nền trang, card, lớp nổi của mỗi theme: nền tối phải sáng dần. Rồi đo
+nền rê và nền đang chọn trên card ở cả hai theme: độ chênh hai bản xấp xỉ nhau, đang chọn
+đậm hơn rê.
+
+> Đừng bắt nút phụ **chìm hơn card** ở nền tối: `--secondary` tối `#010207`, dưới cả nền
+> trang, thì nút và tab đang chọn gần như không tách khỏi nền. Nút phụ `#1c2030` trên card
+> `#0f111a` trông "nổi lên" là đúng chiều; thứ cần canh là độ chênh, không phải chiều.
+
+**M22. Ở nền tối, màu nhấn chỉ dùng làm nền, không dùng làm đường mảnh.**
+
+Màu nhấn trong dark mode thường là gần trắng. Tô nền nút thì đẹp; đem làm viền ô
+nhập lúc focus, gạch chân, hay chỉ báo đang chọn thì thành sợi trắng đặc một
+pixel, gắt và rẻ. Đường mảnh dùng chính màu đó **hạ độ đục xuống khoảng 42%**, vừa đủ 3:1 với nền
+(WCAG 1.4.11). Xuống 35% là còn 2.9:1, trượt.
+
+**M23. Dark mode mặc định của skill là navy rất tối. Đây là gu, không phải quy ước:
+dự án đã có bảng tối riêng thì theo dự án.**
+
+Phần lớn các bộ thiết kế lớn để nền tối trung tính hoặc gần trung tính; navy là một
+trong nhiều gu. Dự án có xám kẽm, xám trung tính, hay nền tối ám màu thương hiệu thì giữ
+nguyên (`P10`, `V4`). Dự án chưa có thì lấy khối `.dark` của `tokens.css`.
+
+Dù gu nào:
+
+- **Không đen tuyệt đối, không trắng tuyệt đối**, kể cả nền rê của nút chính. Nền gần đen,
+  chữ gần trắng. `--primary-hover` lệch **về phía nền** một bậc ở cả hai theme: nền sáng nhạt
+  đi, nền tối tối đi (`#e9edf5` → `#cfd5e0`), không sáng lên `#ffffff`.
+- **Viền là `rgba` mờ**, không phải màu đặc, không thì thành lưới kẻ ô. Ở nền tối viền
+  **đảo vai**: nền trang và card chênh nhau quá ít (1.07:1) nên viền là thứ chính để tách khối.
+- **Bóng giữ, đậm hơn, đi cặp viền 1px.** Bóng 10% trên nền gần đen gần như không thấy, nên
+  lớp nổi tối có ba thứ cùng lúc: nền sáng hơn một bậc (`M21`), viền `border-border`, bóng
+  đậm (`--elevation-*` khối `.dark`). Không bỏ bóng, không thay bằng vầng sáng.
+- **Không bóng màu ở nền tối** (bóng cam, bóng hổ phách dưới nút): trên nền tối nó thành
+  vầng sáng bẩn. `dark:shadow-none` cho mọi bóng có sắc.
+
+*Gu flat — phong cách khác đã chọn theo `P1` thì xem `P2` trong `references/styles.md`.*
+
+**M31. Nút đổi theme: Sáng / Tối / Hệ thống, mặc định Hệ thống.**
+
+- **Ba lựa chọn thấy hết một lần**, không một nút bấm xoay vòng (người dùng phải bấm thử mới
+  biết lần sau ra gì). Mặc định **Hệ thống** (`prefers-color-scheme`), không mặc định Sáng.
+- **Chỗ đặt:** trong app là **Cài đặt → Giao diện** hoặc mục Giao diện trong **menu tài khoản**;
+  đề bảo đặt trên header thì là **icon button** (`Sun` / `Moon`) mở menu ba mục, mục đang chọn
+  có dấu ✓. Trang công khai, docs: nhóm ba icon (radiogroup) ở footer hoặc nút icon trên header.
+- **Màn xác thực, trang lỗi không cần nút đổi theme**: script đầu trang áp lựa chọn đã lưu hoặc theo
+  hệ thống cho mọi route, người dùng đổi trong app.
+- **Nhớ lựa chọn, không nháy trắng khi tải.** Script đặt class trên `<html>` trước khi vẽ;
+  `<html suppressHydrationWarning>` vì script sửa `<html>` trước React.
+- **Lật theme thì tắt transition một nhịp**, không thì nền trang đổi tức thì còn nút, card
+  chuyển màu 200ms lệch nhịp.
+- **Tầng trình duyệt:** `color-scheme` đi cùng theme (khối `:root` / `.dark` của `tokens.css`
+  đã có), để thanh cuộn gốc, ô chọn ngày, autofill, `<select>` vẽ đúng bản. `theme-color` hai thẻ
+  theo `media` là tuỳ chọn.
+- **`dark:` phải theo class, không theo máy.** Tailwind v4 mặc định `dark:` chạy theo
+  `prefers-color-scheme`; thiếu dòng `@custom-variant dark` trong `tokens.css` thì bấm Tối trên
+  máy đang sáng ra token tối, class `dark:` sáng.
+
+Next.js: `next-themes`.
+
+```tsx
+// app/layout.tsx
+<html lang="vi" suppressHydrationWarning>
+  <body>
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+      {children}
+    </ThemeProvider>
+  </body>
+</html>
+```
+
+Icon button trên header đọc `resolvedTheme` sau khi mount (trước đó render icon cố định), không
+thì lệch HTML lúc hydrate. Không Next thì script nội tuyến đầu `<head>` đọc `localStorage` +
+`matchMedia("(prefers-color-scheme: dark)")` rồi gắn `.dark`, và nghe đổi của máy khi đang Hệ thống.
+
+**M32. Ở nền tối, vài thứ đổi cách vẽ chứ không chỉ đổi màu.**
+
+| Thứ | Nền tối | Vì sao |
+| --- | --- | --- |
+| Ô nhập, select, textarea | **giữ viền** `--border-strong`, nền phủ mờ `dark:bg-white/4` | bỏ viền chỉ còn nền mờ là mất ranh giới vùng gõ; mọi bộ lớn đều giữ viền |
+| Nút đảo màu (nền `--foreground`, không phải `--primary`) | về variant `secondary`, hoặc nền trắng mờ + viền | đảo thẳng ra khối trắng chói, nặng hơn cả nút chính. Chỉ màu nhấn được thành khối sáng |
+| Tooltip | **đảo màu**: `bg-foreground text-background` | nền tối thì tooltip sáng, nổi khỏi mọi tầng |
+| Lớp phủ sau modal, panel, sidebar trượt | **`bg-black/…`** ở cả hai theme, không `bg-foreground/…` | `foreground` đảo sang gần trắng, lớp phủ thành màn sương sáng che trang |
+| Mục đang trỏ, đang chọn viết bằng điều kiện JS (`isHighlighted && …`, `isActive && …`) | `bg-item-hover` (trỏ), `bg-secondary` (chọn), như class `hover:` | `bg-background` trong điều kiện JS lọt khỏi mọi phép grep `hover:`; ở nền tối thành lỗ khoét trong dropdown (ô chọn, bảng lệnh) |
+| Chữ, icon màu trạng thái không nền (`text-amber-700`, `text-red-700`, `text-emerald-700`) | kèm `dark:text-*-400` cùng sắc (token `--warning`, `--error-strong`, `--success` đã lật sẵn) | `-700` trên nền tối chỉ 2,9–3,7:1, dưới ngưỡng chữ (`M7`) |
+| Nền nhạt `-50`, `-100` (badge, banner, chip, ô đáp án) | màu `-500` phủ 10–20%, chữ `-300`/`-400` | nền `-50` sang tối là khối trắng hồng giữa màn đen. Màu mang nghĩa đã có sẵn trong `tokens.css` |
+| Gradient, vệt màu loang trang trí | tắt (`dark:hidden`) hoặc thay bản tối | loang màu sáng trên nền tối là chói |
+| Biểu đồ | cột, vùng tô dùng `--chart-fill` (màu nhấn 70% ở nền tối); thang phân loại có bản tối (`components/charts.md`) | cột màu nhấn gần trắng 100% là khối chói nhất màn; xám "Khác" `slate-300` thành nổi nhất |
+| Ảnh nền trắng, logo | ảnh cần bản tối thì `<picture><source media="(prefers-color-scheme: dark)">` hoặc hai ảnh theo class; logo chuyển bản sáng | |
+| Avatar, ảnh nhỏ | vòng `ring-1 ring-border` | ảnh tối tan vào nền |
+
+**M33. Vùng khoá theme khai lại token tại chỗ; thư viện bên ngoài đọc token.**
+
+- **Vùng luôn sáng / luôn tối** (trang chia sẻ nền kem, hero luôn tối): class `.force-light` /
+  `.force-dark` trên khung ngoài cùng, `tokens.css` đã cho hai class này đọc lại đúng bộ token,
+  mọi component con đổi theo mà không truyền gì xuống. `@custom-variant dark` của `tokens.css`
+  đã loại vùng `.force-light`, nên `dark:` không rò vào. Cả trang khoá theme thì `next-themes`
+  `forcedTheme`, và ẩn nút đổi theme ở trang đó.
+- **Thư viện bên ngoài đọc token**, không để màu mặc định của nó: toast, hộp thoại, thanh tiến
+  trình chuyển trang, trình soạn thảo, lịch. Đè style bằng `var(--surface-overlay)`,
+  `var(--border)`, `var(--foreground)`, `var(--primary)` là tự lật theo theme. Để màu mặc định
+  của thư viện thì nền tối còn một hộp trắng giữa màn (chỉ người bật tối mới thấy, nên rất lâu
+  mới có người báo).
+
+---
+
+## Token
+
+**M24. Mọi màu đi qua token đặt tên theo vai trò.** Không rải mã hex trong markup.
+
+**M25. Một khái niệm một token.** Mọi đường kẻ và viền dùng chung một tên. Đừng
+chỗ thì `divide-border` chỗ thì `border-muted/25`.
+
+**M26. Mọi màu và font gom vào khối đánh dấu ở đầu file.** Ngoài khối đó không
+được xuất hiện mã màu. Có dark mode thì màu nhấn có **hai chỗ**: `:root` và
+`.dark`. Thiếu chỗ thứ hai là màu nhấn tàng hình trên nền tối.
+
+**M27. Khối đổi thương hiệu phải chép nguyên văn từ `tokens.css`.** Mở file ra
+copy, không gõ lại từ trí nhớ, không tự nghĩ mã hex. Đã có lần AI tự chế ra
+`#a99cff` tím và `#fa99cff0d` sai cú pháp. Cần màu khác thì thay đúng một dòng.
+
+**M28. Lúc giao phải chỉ rõ chỗ đổi thương hiệu.** Một dòng: "đổi màu nhấn ở dòng
+14, font ở dòng 8". Có dark mode thì nói rõ là hai chỗ.
+
+---
+
+## Card đứng một mình
+
+**M29. Màn chỉ có đúng MỘT card giữa trang trống thì bỏ viền. Chìm quá thì dùng
+bóng rất mờ, không phải viền đậm hơn.**
+
+*Gu flat — phong cách khác đã chọn theo `P1` thì xem `P2` trong `references/styles.md`.*
+
+Đăng nhập, đăng ký, quên mật khẩu, màn onboarding một khối. (Trang lỗi không dùng card, xem
+"Trang lỗi" ở `layouts/app.md`.) Đặc điểm
+chung: **không có khối thứ hai nào để mà tách khỏi.**
+
+`M13` bắt viền vì viền là thứ phân định ranh giới giữa các khối nằm cạnh nhau.
+Trên màn chỉ có một card, không còn việc đó để làm — đường viền lúc này chỉ là
+một nét vẽ quanh hộp, và nó làm card trông như một cái khung chờ nội dung.
+
+Thứ tự thử, dừng ngay khi đủ:
+
+1. **Không viền, không bóng.** Nền trang xám (`--background`) + card trắng (`--surface`) đã đủ chênh để đọc ra ranh giới. Đây là mặc định.
+2. **Chìm quá thì thêm bóng rất mờ.** Cỡ `shadow-sm` của Tailwind — mờ đến mức chỉ cảm thấy chứ không nhìn ra. Card lúc này đang **nổi trên** một trang trống, nên nó hợp tinh thần "lớp nổi" của `M15` hơn là khối nằm trong trang.
+3. **Không bao giờ dùng cả viền lẫn bóng.** Hai thứ cùng làm một việc. Có bóng rồi mà vẫn thấy cần viền thì bóng đang đặt sai, không phải thiếu viền.
+
+**Đừng chữa cháy bằng viền đậm hơn.** Thấy card chìm mà tăng độ đậm của viền là
+đi ngược `M14` — viền đậm lên thì cái hộp hiện ra rõ hơn nội dung bên trong nó.
+
+Có từ hai card trở lên trên màn thì quay về `M13` như thường.
+
+**Nền tối giữ y như vậy, không thêm viền dù `M23` nói viền gánh việc tách khối.** Card tối chênh nền
+1.07:1, ngang bản sáng 1.10:1, đủ đọc ra ranh giới. Đã thử trên màn đăng nhập: viền
+`--border` biến card thành khung, bóng `--elevation-popover` gần như không thấy. `M23` nói về các khối
+nằm cạnh nhau trong trang, không về một card một mình.
+
+---
+
+## Hai sắc đỏ
+
+**M30. Đỏ có hai sắc cho hai việc. Không dùng lẫn, không thêm sắc thứ ba.**
+
+| | Sắc | Việc | Khi nào hiện | Ở đâu |
+| --- | --- | --- | --- | --- |
+| **Lỗi** | `red` | *Đã có gì đó sai*, phải sửa mới đi tiếp được | Sau khi người dùng làm sai | Ô nhập, câu lỗi, banner lỗi máy chủ |
+| **Nguy hiểm** | `rose` | *Bấm vào thì không lấy lại được* | Nút: luôn hiện, nền mờ. Mục menu: chỉ lúc rê vào (`I4`) | Xoá, huỷ tài khoản, rời nhóm, đăng xuất (mục menu) |
+
+**Vì sao tách.** Hai việc khác nhau về thời điểm và mức nặng:
+
+- **Lỗi** là chuyện **đã xảy ra**. Nó phải nhận ra ngay, không lẫn với gì — nên dùng `red`, sắc đỏ chuẩn mà ai nhìn cũng đọc ra "sai".
+- **Nguy hiểm** là **lời nhắc trước khi bấm**, hiện lên chỉ vì chuột đi ngang qua. Chưa có gì sai cả. Nếu nó đỏ y như lỗi thì mỗi lần rê chuột qua menu, người dùng thấy như vừa làm hỏng gì — nên dùng `rose`, ngả hồng hơn, mềm hơn một bậc. Cùng tinh thần `I4`: nút xoá không hét vào mặt người dùng.
+
+**Phép thử khi phân vân:** *người dùng đã làm sai gì chưa?* Rồi → `red`. Chưa,
+chỉ đang sắp bấm → `rose`.
+
+### Bậc dùng — đừng tự chế
+
+Mỗi ô ghi class Tailwind, token CSS trong ngoặc. Hai cách ra cùng một màu
+(`tokens.css`), dự án không có Tailwind thì dùng token.
+
+| Việc | Lỗi (`red`) | Nguy hiểm (`rose`) |
+| --- | --- | --- |
+| Chữ, icon | câu lỗi dưới ô: `text-red-600` (`--error-text`) — `red-500` trên nền trắng chỉ 3.8:1, trượt 4.5:1. Dấu `*` trường bắt buộc cũng sắc này (ngoại lệ `M9`) | `text-rose-700` (`--danger`) (nút luôn hiện, mục menu lúc rê vào) — `rose-500` trên nền mờ chỉ 3.2:1 |
+| Viền | `border-red-500` (`--error`) | — *(không có viền đỏ)* |
+| Nền mờ | `ring-red-500/10` (`--error-ring`) quanh ô nhập lỗi **đang focus** | nút: `bg-rose-500/10` (`--danger-bg`), rê vào `/15` (`--danger-bg-hover`) · mục menu: `hover:bg-rose-500/10` |
+| Banner | `bg-red-50` (`--error-bg`) · `border-red-200` (`--error-border`) · tiêu đề `red-700` (`--error-strong`), mô tả `text-foreground/80` (`components/banner.md`) | — *(không có banner)* |
+
+Ô "—" là **cố ý trống**: hành động nguy hiểm không bao giờ có viền đỏ hay banner
+đỏ. Thấy mình định viết `border-rose-*` là đang biến lời nhắc thành cảnh báo.
+
+**Không có sắc thứ ba.** Không `pink`, không `orange-red`, không đỏ tuỳ chế
+`#e53e3e` để **báo trạng thái**. Cần một kiểu "nhẹ hơn lỗi nhưng vẫn cần chú ý"
+thì đó là **hổ phách** (`M4`), không phải một sắc đỏ mới.
+
+**Phạm vi: `M30` chỉ áp cho màu mang NGHĨA.** Màu nhận diện — nền avatar chữ cái
+đầu, icon workspace — không báo gì cả, nên không thuộc luật này. Cùng lý do với
+ngoại lệ của `M12`: ở đó màu đóng vai ảnh, không đóng vai trạng thái. Nhưng để
+không ai phải phân vân, bộ màu avatar **không dùng `red` hay `rose`** — xem
+`references/components/avatar.md`.
+
+### Đổi thương hiệu
+
+Thương hiệu có đỏ riêng thì sửa khối `--danger*` / `--error*` trong `tokens.css`,
+và đổi **cả hai nhóm cùng lúc**, giữ khoảng cách giữa chúng: lỗi đậm và chuẩn
+hơn, nguy hiểm mềm hơn. Đổi một nhóm mà quên nhóm kia thì hai việc lại trông như
+một. Dự án dùng class Tailwind thì phải map lại trong `@theme` hoặc thay class,
+sửa token thôi không đổi được `text-rose-700` (xem `tailwind-v4-traps.md`).
+Đổi xong đo lại tương phản: chữ trên nền phải từ 4.5:1.