@comitor/ui 0.1.0 → 0.2.0

package/styles.css

@@ -74,6 +74,69 @@
   --green: #2ea56a;
   --yellow: #f2c94c;
 
+  /* ─ HỢP ĐỒNG BA VAI TRÒ CỦA MỘT TONE MÀU — đọc tên là biết dùng ở đâu ─
+
+     Đây là hợp đồng đặt tên của cả gói, áp cho MỌI cặp màu (brand, trạng thái, màu phụ, accent
+     app). Bảng "vai trò → token nên dùng" kèm ví dụ đúng/sai: docs/hop-dong-mau.md.
+
+       --x               → tô NỀN (fill đặc, hoặc tint /5–/20). TUYỆT ĐỐI không làm màu chữ/icon.
+       --x-foreground    → chữ/icon nằm TRÊN nền --x ĐẶC — đo tương phản với --x (ngưỡng 4,5:1).
+       --x-ink           → CHÍNH màu đó khi đi lên nền TRANG (--background/--card/--popover/
+                           --sidebar) hoặc lên tint /5–/20 của chính nó — đo với nền đó.
+                           /20 là TRẦN CHUNG an toàn cho mọi tone ở cả hai theme; tone nào chịu
+                           được đậm hơn thì xem bảng trần tint ở docs/hop-dong-mau.md §2 (chặt
+                           nhất là đỏ ở dark: --red-ink trên red/25 chỉ 4,29:1 ✗).
+
+     Vì sao phải có bậc ink riêng thay vì dùng thẳng --teal/--green/--red/--yellow: bản light của
+     màu phụ được chọn để TÔ NỀN nên quá nhạt cho vai trò chữ. Đo trên tint 15% của chính nó (nền
+     thật mà chữ initials avatar và badge tonal đứng lên) — cột trái là cách dùng SAI:
+
+         teal   #1F8A8B trên #DDEDEE = 3,44:1 ✗   → --teal-ink   #1A6668 = 5,54:1 ✓
+         green  #2EA56A trên #E0F2E9 = 2,69:1 ✗   → --green-ink  #216A48 = 5,60:1 ✓
+         red    #D64545 trên #F9E3E3 = 3,57:1 ✗   → --red-ink    #9A3537 = 5,83:1 ✓
+         yellow #F2C94C trên #FDF7E4 = 1,48:1 ✗   → --yellow-ink #7A5800 = 6,08:1 ✓
+
+     Bậc ink phải đạt trên CẢ nền trắng lẫn nền tint — hai phép đo, không phải một. Trên các nền
+     trang của light (--background · --sidebar #FAFAF9 · --sidebar-accent #FBF5DC):
+         teal 6,68 · 6,39 · 6,10   |   green  6,52 · 6,24 · 5,96
+         red  7,15 · 6,84 · 6,53   |   yellow 6,51 · 6,24 · 5,96        ✓ đều ≥ 4,5:1
+
+     Hex ở đây là kết quả ĐÃ ĐÓNG BĂNG của color-mix(in srgb, --<màu>, --ink 30/40%) mà vòng
+     trước tính tay trong từng component. Đóng băng thành token có chủ ý: (a) một chỗ duy nhất
+     để đo lại khi đổi màu phụ, (b) component không phải nhắc lại chuỗi color-mix (dễ chép lệch
+     % giữa Badge/LetterAvatar/Input), (c) `tokens.ts` mirror được ra hex thật.
+     ⚠ Đổi --teal/--green/--red/--yellow thì PHẢI tính lại bậc ink tương ứng — không tự theo.
+
+     Ở DARK không cần bậc ink riêng: khối .dark đã nâng chính --teal/--green/--red/--yellow lên
+     mức làm CHỮ được, nên bên đó --x-ink chỉ trỏ về var(--x). */
+  --teal-ink: #1a6668;
+  --green-ink: #216a48;
+  --red-ink: #9a3537;
+  /* Vàng không có bậc tối riêng: mượn thang gold (cùng sắc, đã đo) thay vì đẻ thêm một hex.
+     #7A5800 — nền trang 6,51:1 · yellow/15 6,08:1 · yellow/20 5,93:1 · yellow/25 5,82:1 ✓
+     (bản dark #FACC15 — nền trang 12,35:1 · yellow/15 trên --card 8,27:1 · yellow/25 6,23:1 ✓) */
+  --yellow-ink: var(--gold-500);
+  /* Navy vốn đã đủ tối ở light nên ink = chính nó; .dark mới cần bậc sáng (xem khối .dark). */
+  --navy-ink: var(--navy);
+
+  /* ─ Bậc FOREGROUND của màu phụ — chữ/icon nằm TRÊN nền --x ĐẶC ─
+     teal/green/yellow đều là sắc SÁNG-VỪA ở light và còn sáng hơn ở dark, nên chữ phải là MỰC
+     chứ không phải trắng; một giá trị chạy được cả hai theme (khối .dark không khai lại):
+         teal   mực 4,56:1 (light) · 10,16:1 (dark)   [trắng chỉ 4,14:1 ✗ — cặp CHẶT nhất gói]
+         green  mực 6,04:1 (light) · 10,85:1 (dark)   [trắng chỉ 3,13:1 ✗]
+         yellow mực 11,92:1 (light) · 12,35:1 (dark)  [trắng chỉ 1,59:1 ✗]
+         navy   TRẮNG 16,49:1 ở cả hai theme (.dark không override --navy)
+
+     ⚠ CỐ Ý KHÔNG CÓ --red-foreground. Nền --red ĐẶC không mang được chữ ở light: #D64545 với
+     chữ trắng = 4,38:1 ✗ và với chữ mực = 4,32:1 ✗ — không màu chữ nào của brand cứu được cặp
+     đó. Nền đỏ đặc CÓ CHỮ phải đi qua --destructive (#C93B3B, ghim cả hai theme) cùng
+     --destructive-foreground = 5,03:1 ✓. --red chỉ để tô TINT (badge/avatar) và làm màu chart.
+     ⚠ Đổi --teal/--green/--yellow/--navy thì phải đo lại bốn bậc này. */
+  --teal-foreground: #0e1116;
+  --green-foreground: #0e1116;
+  --yellow-foreground: #0e1116;
+  --navy-foreground: #ffffff;
+
   /* ─ Semantic shadcn ─ */
   --background: #ffffff;
   --foreground: #0e1116;
@@ -83,18 +146,127 @@
   --popover-foreground: #0e1116;
   --primary: #e8b824;
   --primary-foreground: #0e1116;
+  /* Bậc INK của brand — gold khi nó phải ĐI LÊN nền trang thay vì tô nền. Đúng hợp đồng ba vai
+     trò ở khối "Bậc INK của màu phụ" bên trên, chỉ khác ở chỗ thang gold đã có sẵn bậc tối nên
+     mượn `--gold-500` thay vì đẻ thêm hex.
+     Vì sao brand cũng cần bậc ink: gold `#E8B824` là màu SÁNG (L = 0,516) — tô nền thì tuyệt, làm
+     nền cho chi tiết nhỏ hoặc đứng trên nền trang thì chỉ được **1,86:1** so với nền trắng, dưới
+     xa 3:1 của WCAG 1.4.11. Đó là gốc bệnh chung của rãnh `Switch` khi BẬT và ô `Checkbox` đã
+     chọn — hai chỗ mà trạng thái BẬT/ĐÃ CHỌN là thông tin, không phải trang trí; vai trò đó nay
+     có tên riêng là `--control-on` (khai ở khối RANH GIỚI bên dưới) và trỏ về chính biến này.
+         light `--gold-500` #7A5800 : 6,51:1 trên --background · 6,09:1 trên --muted ✓
+         dark  = chính --primary (#F5D060, gold-200) : 12,67:1 trên --background ✓
+     Ở dark không cần bậc riêng vì bảng màu dark đã nâng --primary lên bậc sáng — cùng lối với
+     --teal-ink/--green-ink.
+     ⚠ App ghi đè --primary thì PHẢI ghi đè kèm --primary-ink (một bậc đủ tối cho light), y như
+     hợp đồng của --app-accent. */
+  --primary-ink: var(--gold-500);
   --secondary: #ede8d8;
   --secondary-foreground: #0e1116;
   --muted: #f7f7f8;
-  --muted-foreground: #7e8290;
+  /* Bậc chữ phụ (placeholder, mô tả, nhãn trục biểu đồ) — là CHỮ nên ngưỡng là AA 4,5:1,
+     không phải 3:1. Trước đây lấy thẳng --ash-500 #7E8290 và hỏng ở khắp nơi: 3,83:1 trên
+     nền trắng, 3,58:1 trên --muted. Nay tách khỏi thang ash (ash-500 vẫn là #7E8290 — bậc
+     bảng màu là dữ kiện trung tính, token semantic mới là chỗ mang hợp đồng tương phản):
+     #686C7A = 5,23:1 trên --background · 4,89:1 trên --muted · 5,01:1 trên --sidebar. */
+  --muted-foreground: #686c7a;
   --accent: #fbf5dc;
   --accent-foreground: #0e1116;
-  --destructive: #d64545;
+  /* Đỏ dùng làm NỀN (nút xoá, chấm huy hiệu): ghim MỘT giá trị cho cả hai theme vì chữ trắng
+     trên nó phải đọc được ở cả hai. Đậm hơn --red một bậc là bắt buộc, không phải thẩm mỹ:
+     #D64545 + chữ trắng chỉ được 4,38:1 — thiếu 0,12 so với AA 4,5:1; #C93B3B đạt 5,03:1.
+     ĐỪNG đồng nhất với --red (#D64545 ở light, #F87171 ở dark): --red là màu TÔ (tint của Badge,
+     chart-5), còn màu để làm CHỮ đỏ là --red-ink / --destructive-ink ngay dưới. */
+  --destructive: #c93b3b;
   --destructive-foreground: #ffffff;
+  /* Chữ báo lỗi trên nền TRANG (helper text của Input, dòng lỗi của Form) — KHÁC hai biến ngay
+     trên: --destructive là NỀN, --destructive-foreground là chữ TRẮNG nằm trên nền đó. Dùng
+     nhầm một trong hai thì mỗi bên hỏng một nửa: --destructive qua được light (5,03:1) nhưng chỉ
+     3,53:1 trên --card ở dark ✗, --red thì ngược lại — 4,38:1 ở light ✗. Đi qua bậc ink mới đạt
+     cả hai: 7,15:1 (light, trên --background) và 6,42:1 (dark, trên --card). Trên tint của chính
+     nó cũng đạt: destructive/10 6,18 · /15 5,76 · /20 5,33:1 (light) · 5,94 · 5,71 · 5,42:1
+     (dark, tint hợp lên --card). Alias vào --red-ink theo đúng lối --success: var(--green) — đỏ
+     báo lỗi và đỏ định danh là cùng một sắc. */
+  --destructive-ink: var(--red-ink);
+  /* ─ RANH GIỚI: HAI VAI TRÒ, HAI TOKEN, TUYỆT ĐỐI ĐỪNG LẪN ─
+
+       --border (+ --sidebar-border)   VIỀN TRANG TRÍ. Đường kẻ chia, khung Card lúc nghỉ, vạch
+           ngăn nhóm menu, đường kẻ bảng — thứ chỉ tách khối cho mắt dễ quét, KHÔNG mang thông
+           tin. Cố ý để nhạt và KHÔNG chịu ngưỡng nào: WCAG 1.4.11 chỉ đòi tương phản cho thông
+           tin thị giác cần để NHẬN RA thành phần và trạng thái của nó. Số thật, ghi ra để không
+           ai tưởng là lỗi bỏ sót:
+               light #EDEEF1 trên trắng = 1,16:1 · dark #1E2128 trên #0E1116 = 1,17:1
+               dark #1E2128 trên --card #16181D = 1,10:1 · --sidebar-border/--sidebar = 1,11:1
+
+       --control-edge (+ alias --input)   VIỀN CONTROL, ngưỡng 3:1. Khi nền control trong suốt
+           thì VIỀN là thứ duy nhất khoanh vùng nó → viền chính là "thông tin cần để nhận ra
+           thành phần". Dùng cho: Input/Textarea/Select/Combobox, ô Checkbox chưa chọn, viền
+           Radio, rãnh Switch khi TẮT, rãnh Slider, Button variant outline/secondary, Badge
+           variant outline, ô tìm của WorkspaceSwitcher.
+
+       --control-edge-strong   Cùng vai trò nhưng ở HOVER/ACTIVE: phải ĐẬM HƠN lúc nghỉ, không
+           nhạt đi. Lỗi kinh điển đang có trong repo là `hover:border-ash-300` ở light — 1,62:1,
+           tức hover làm control gần như BIẾN MẤT.
+
+     ⚠ `@layer base { * { @apply border-border } }` ở mục 7 gán viền TRANG TRÍ cho MỌI phần tử.
+     Control nào chỉ viết `border` mà không nêu màu sẽ lặng lẽ nhận bậc 1,16:1 — luôn phải nêu
+     `border-input` / `border-control-edge` tường minh. Bảng đầy đủ: docs/hop-dong-mau.md §3. */
   --border: #edeef1;
-  --input: #edeef1;
+  /* Viền ô nhập = ranh giới nhận dạng control theo 1.4.11 → phải là --control-edge (khai bên
+     dưới), không phải bậc trang trí. 3,83:1 (light, nền trắng) · 4,94:1 (dark, nền #0E1116) ✓.
+     Vì --control-edge ghim một giá trị cho cả hai theme nên khối .dark không khai lại --input. */
+  --input: var(--control-edge);
   --ring: #e8b824;
 
+  /* --control-edge #7E8290 — bậc xám DUY NHẤT được phép làm ranh giới control. Ràng buộc là HAI
+     PHÍA, nên phải là token riêng chứ không mượn --border (thuần trang trí) hay --muted-foreground
+     (token CHỮ: nó bị kéo tối/sáng theo nhu cầu đọc chữ — đã đổi một lần #7E8290 → #686C7A/#888D9B
+     — và khi đó ràng buộc phía núm không còn gì bảo vệ):
+
+         đủ TỐI để hiện trên nền trang       → ≥3:1 với --background/--card/--muted/--secondary
+         đủ tương phản với NÚM / DẤU CHECK   → ≥3:1 với --control-knob (= --background của theme)
+
+     MỘT giá trị chạy được cả hai theme nên không cần biến thể dark:
+
+         light: --background 3,83 · --card 3,83 · --muted 3,58 · --sidebar 3,67 · --accent 3,50
+                · --secondary 3,13 · núm (trắng) 3,83:1   ✓
+         dark : --background 4,94 · --card 4,64 · --popover 4,64 · --muted 4,21 · --sidebar 4,64
+                · núm (#0E1116) 4,94:1                      ✓
+
+     ⚠ Chú thích bản trước ghi "núm Switch tô trắng ở CẢ hai theme" và kèm dải L cho dark — SAI cả
+     hai: núm là `bg-background` nên ở dark nó là #0E1116 (xem --control-knob), tức ở dark ràng
+     buộc phía núm TRÙNG với ràng buộc phía nền, không có chặn trên nào. Bỏ hẳn dải L: đó đúng là
+     chỗ số đã sai một lần; giữ phép đo tương phản là đủ và không tự mâu thuẫn. */
+  --control-edge: #7e8290;
+  /* Hover/active của viền control. Light = --ash-700, dark = --ash-300 — đúng thứ `Checkbox` đang
+     viết tay bằng `border-ash-700 dark:border-ash-300`; token hoá để Input/Select/Combobox khỏi
+     chép lệch (Select hiện đang sai chiều: hover NHẠT hơn lúc nghỉ).
+         light #3A3F4A: --background 10,55 · --muted 9,86 · --sidebar 10,11 · --secondary 8,61:1 ✓
+         dark  #C8CBD3: --background 11,65 · --card 10,94 · --muted 9,93:1 ✓ */
+  --control-edge-strong: var(--ash-700);
+
+  /* ─ CONTROL Ở TRẠNG THÁI BẬT / ĐÃ CHỌN ─
+     Rãnh `Switch` khi BẬT, ô `Checkbox` đã chọn, chấm `Radio`, đoạn đã chọn của `Slider`. Cũng
+     là WCAG 1.4.11 và cũng ràng buộc HAI PHÍA (nền trang · núm/dấu check), y hệt --control-edge.
+
+     KHÔNG dùng --primary cho vai trò này: gold #E8B824 chỉ 1,86:1 với nền trắng VÀ 1,86:1 với
+     núm trắng → BẬT/TẮT chỉ còn phân biệt được bằng VỊ TRÍ núm; ở dark rãnh #F5D060 nổi trên nền
+     (12,67:1) nhưng núm trắng lại chìm vào rãnh (1,49:1 ✗). --primary-ink đạt cả hai phía ở cả
+     hai theme, nên --control-on trỏ về nó:
+         light #7A5800: rãnh ⇄ nền trang 6,51:1 · núm ⇄ rãnh 6,51:1   ✓
+         dark  #F5D060: rãnh ⇄ nền trang 12,67:1 · núm ⇄ rãnh 12,67:1 ✓
+
+     --control-knob là NÚM Switch / DẤU CHECK / chấm Radio, và cố ý mang màu NỀN TRANG (trắng ở
+     light, #0E1116 ở dark) — nhờ vậy nó luôn tương phản ĐÚNG CHIỀU với cả rãnh BẬT lẫn rãnh TẮT.
+     `bg-white` cứng chỉ đúng ở light. Bốn tổ hợp trạng thái × theme:
+         light BẬT 6,51 · light TẮT 3,83 · dark BẬT 12,67 · dark TẮT 4,94:1   ✓
+     ⚠ KHÔNG dùng --primary-foreground cho núm/dấu check: nó là MỰC ở cả hai theme, mà mực trên
+     --control-on ở light (#7A5800) chỉ 1,86:1 ✗.
+     ⚠ App ghi đè --primary PHẢI ghi đè kèm --primary-ink, nếu không control giữ nguyên gold mặc
+     định — sai màu mà không sai chuẩn, đúng thứ tự ưu tiên của repo. */
+  --control-on: var(--primary-ink);
+  --control-knob: var(--background);
+
   --sidebar: #fafaf9;
   --sidebar-foreground: #0e1116;
   --sidebar-border: #edeef1;
@@ -106,24 +278,89 @@
      Vì trỏ bằng var(), khối .dark bên dưới đổi --green/--yellow/--teal là
      --success/--warning/--info tự sáng theo, không cần khai lại. */
   --success: var(--green);
-  --success-foreground: #ffffff;
   --warning: var(--yellow);
-  --warning-foreground: #0e1116;
   --info: var(--teal);
-  --info-foreground: #ffffff;
-
-  /* ─ Bảng màu biểu đồ (đổi độc lập với brand) ─ */
+  /* Chữ/icon trên nền trạng thái ĐẶC. Cả ba sắc đều SÁNG ở light và còn sáng hơn ở dark → chữ là
+     MỰC ở CẢ hai theme, nên khối .dark không khai lại (trước đây success/info để #FFFFFF ở light
+     rồi lật về mực ở dark — bản light hỏng thẳng ngưỡng AA):
+         success mực 6,04:1 (light) · 10,85:1 (dark)    [trắng chỉ 3,13:1 / 1,74:1 ✗]
+         info    mực 4,56:1 (light) · 10,16:1 (dark)    [trắng chỉ 4,14:1 / 1,86:1 ✗]
+         warning mực 11,92:1 (light) · 12,35:1 (dark)   [trắng chỉ 1,59:1 / 1,53:1 ✗]
+     ⚠ info ở light là cặp CHẶT nhất gói (4,56:1, dư 0,06). Đổi --teal thì phải đo lại ngay. */
+  --success-foreground: #0e1116;
+  --warning-foreground: #0e1116;
+  --info-foreground: #0e1116;
+  /* Bậc ink của trạng thái — chữ/icon trạng thái trên nền trang hoặc trên tint của chính nó
+     (Badge tonal, dòng lỗi, chip cảnh báo, icon Alert). Trỏ vào bậc ink của màu phụ đúng như
+     --success trỏ vào --green, nên .dark đổi màu phụ là cả hai tầng tự đúng theo.
+     Đo trên nền trang / trên tint 15% của chính nó — hai phép đo, phải đạt cả hai:
+         success #216A48 6,52 / 5,60:1 (light) · #4ADE80 10,85 / 7,44:1 (dark)   ✓
+         warning #7A5800 6,51 / 6,08:1 (light) · #FACC15 12,35 / 8,27:1 (dark)   ✓
+         info    #1A6668 6,68 / 5,54:1 (light) · #2DD4BF 10,16 / 7,12:1 (dark)   ✓ */
+  --success-ink: var(--green-ink);
+  --warning-ink: var(--yellow-ink);
+  --info-ink: var(--teal-ink);
+
+  /* ─ Bảng màu biểu đồ (đổi độc lập với brand) ─
+     ⚠ CÒN TỒN, biết và cố ý chưa động tới trong vòng token này: các bậc chart là màu TÔ cho vùng
+     lớn (cột, cung tròn, vùng area) nên đứng trên nền trang chúng nhạt — chart-1 #E8B824 chỉ
+     1,86:1 · chart-4 #2EA56A 3,13:1 · chart-2 #1F8A8B 4,14:1 · chart-5 #D64545 4,38:1 với nền
+     trắng. Với vùng tô lớn kèm nhãn/chú giải văn bản thì WCAG không đòi 3:1 cho chính mảng màu,
+     nhưng NÉT MẢNH (đường line 1–2px, chấm điểm) thì có. Nếu vẽ nét mảnh, dùng bậc ink của cùng
+     sắc (--teal-ink/--green-ink/--red-ink/--primary-ink) chứ đừng dùng --chart-*; quyết định dứt
+     điểm cho tầng chart nằm ngoài phạm vi vòng này. */
   --chart-1: var(--gold-300);
   --chart-2: var(--teal);
-  --chart-3: var(--navy);
+  /* Vai trò "navy" của biểu đồ đi qua bậc ink: nó là nét/khối phải NỔI trên nền trang, nên ở
+     dark tự lấy bậc sáng của navy mà không cần .dark khai lại --chart-3. */
+  --chart-3: var(--navy-ink);
   --chart-4: var(--green);
   --chart-5: var(--red);
 
   /* ─ Accent theo từng app trong hệ sinh thái (Tasks/Chat/CRM/HR…) ─
-     App set lại 2 biến này ở <body> là đổi được ô app trong AppLauncher và
-     thanh active của sidebar, không cần build lại package. */
+
+     ⚠ HỢP ĐỒNG DÙNG — ba biến, ba vai trò, KHÔNG hoán đổi cho nhau.
+
+       --app-accent             CHỈ tô NỀN (fill đặc `bg-app-accent`, hoặc tint `/5`–`/15`).
+                                CẤM dùng làm màu chữ/icon/viền: `text-app-accent`,
+                                `border-app-accent`, `fill-app-accent` là SAI theo định nghĩa.
+       --app-accent-foreground  Chữ/icon nằm TRÊN nền `bg-app-accent` đặc.
+       --app-accent-ink         Chính màu app khi nó phải ĐI LÊN nền trang: chữ, icon rời,
+                                viền, vạch chỉ mục active, dấu check.
+
+     Vì sao phải tách chứ không cấm suông: một biến không thể vừa làm nền vừa làm chữ trên
+     chính cái nền đó — hai vai trò đòi hai hướng tương phản ngược nhau. Bằng chứng là chỗ tệ
+     nhất của 0.1.0, `AppLauncher` với `bg-app-accent/15 text-app-accent`: accent mặc định
+     = --primary = gold #E8B824, icon vàng trên nền vàng 15% (đã trộn ra #FCF4DE) chỉ được
+     1,69:1 — dưới xa 3:1 mà WCAG 1.4.11 đòi cho icon. Không có giá trị gold nào cứu được
+     cặp đó, vì nền càng đúng brand thì chữ cùng màu càng chìm.
+
+     Số đo của bộ mặc định (accent = gold):
+       nền đặc + --app-accent-foreground : 10,19:1 (light) · 12,67:1 (dark)  ✓ AA
+       --app-accent-ink trên nền trang   : 6,51:1 trên --background, 6,24:1 trên --sidebar,
+                                           5,96:1 trên --sidebar-accent, 6,14:1 trên chính
+                                           tint `bg-app-accent/10` (light);
+                                           12,67 / 11,90 / 10,80:1 (dark)     ✓ AA
+
+     Chỗ đọc các biến này (mô tả VAI TRÒ, không phải kiểm kê từng file — kiểm kê chạy theo mỗi
+     vòng sửa component nên chép vào đây là chép một thứ chóng hỏng; nguồn chuẩn là
+     docs/hop-dong-mau.md §5):
+       • nền ĐẶC + foreground : ô app trong `AppLauncher`, chip lọc đang bật
+       • nền TINT + …-ink      : khung icon của `PageHeader`/`StatCard` (`/10`), dòng đang chọn
+                                 của `DataTable` (`/5`) — trên tint thì màu chữ là INK, không
+                                 phải …-foreground (đó là chữ cho nền ĐẶC)
+       • ink : icon/vạch active của `SidebarMenuItem`, mọi chỗ màu app phải đi lên nền trang.
+     ⚠ `text-app-accent` (không hậu tố) vẫn còn ở vài component — đó là vi phạm hợp đồng, không
+     phải cách dùng hợp lệ; xem docs/hop-dong-mau.md §5 và docs/quyet-dinh-tich-hop.md §8.
+
+     ⚠ App ghi đè: set --app-accent thì PHẢI set kèm --app-accent-ink (và --app-accent-foreground
+     nếu accent của app sáng/tối khác gold). Quên thì vạch active vẫn ĐỌC ĐƯỢC nhưng còn màu
+     gold mặc định — sai màu mà không sai chuẩn, đúng thứ tự ưu tiên của repo. Cố ý KHÔNG suy
+     --app-accent-ink bằng color-mix từ --app-accent: dẫn xuất tự động cho ra con số không ai
+     đo, mà đây đúng là chỗ 0.1.0 đã ngã. */
   --app-accent: var(--primary);
   --app-accent-foreground: var(--primary-foreground);
+  --app-accent-ink: var(--primary-ink);
 
   /* ─ Số đo khung ứng dụng (shell dùng ở cả CSS lẫn TS — xem tokens.ts) ─ */
   --sidebar-width: 16rem; /* 256px */
@@ -162,16 +399,29 @@
   --popover-foreground: #f7f7f8;
   --primary: #f5d060;
   --primary-foreground: #0e1116;
+  /* Bản dark của --primary vốn đã là bậc sáng đủ nổi trên nền tối (12,67:1 trên --background),
+     nên bậc ink trỏ thẳng về nó — cùng lối với --teal-ink/--green-ink ở khối dưới. */
+  --primary-ink: var(--primary);
   --secondary: #1e2128;
   --secondary-foreground: #f7f7f8;
   --muted: #1e2128;
-  --muted-foreground: #7e8290;
+  /* Phải SÁNG hơn bản light (không phải cùng một giá trị): chữ phụ hay nằm trên --card #16181D
+     và --muted #1E2128 chứ ít khi trên nền nền trang. #7E8290 cũ chỉ 4,21:1 trên --muted ✗.
+     #888D9B: 5,70:1 trên --background · 5,35:1 trên --card · 4,86:1 trên --muted ✓ — và tình cờ
+     vẫn ≥3:1 với núm Switch ở cả hai theme (3,32:1 với núm trắng của light, 5,70:1 với núm
+     #0E1116 của dark). "Tình cờ" là chữ đúng: đây là token CHỮ, ràng buộc phía núm KHÔNG được
+     bảo đảm ở đây — chỗ cần rãnh control phải dùng --control-edge. */
+  --muted-foreground: #888d9b;
   --accent: #1e2128;
   --accent-foreground: #f7f7f8;
-  --destructive: #d64545;
+  /* Ghim đúng giá trị của light — xem chú thích ở :root. */
+  --destructive: #c93b3b;
   --destructive-foreground: #ffffff;
   --border: #1e2128;
-  --input: #1e2128;
+  /* --input và --control-edge KHÔNG khai lại: --control-edge ghim MỘT giá trị cho cả hai theme
+     (xem chứng minh hai phía ở :root). --control-on/--control-knob cũng không, vì chúng trỏ vào
+     --primary-ink/--background — hai biến đã có bản dark ngay trong khối này. */
+  --control-edge-strong: var(--ash-300);
   --ring: #f5d060;
 
   --sidebar: #16181d;
@@ -187,9 +437,22 @@
   --green: #4ade80;
   --yellow: #facc15;
 
-  /* Foreground của trạng thái phải lật lại: nền sáng → chữ tối. */
-  --success-foreground: #0e1116;
-  --info-foreground: #0e1116;
+  /* Bậc ink ở dark = CHÍNH màu phụ: bốn giá trị ngay trên vốn đã được chọn cho vai trò CHỮ.
+     Vẫn phải khai lại (chứ không để rơi về hex của :root) vì bản light là bậc tối đóng băng,
+     bỏ dòng nào thì bên dark rơi về đúng bậc tối đó và chìm nghỉm vào nền. Đo trên tint của
+     chính nó ở --card: teal/15 7,12 · green/15 7,44 · red/15 5,18 · yellow/20 7,19:1 ✓ */
+  --teal-ink: var(--teal);
+  --green-ink: var(--green);
+  --red-ink: var(--red);
+  --yellow-ink: var(--yellow);
+  /* navy nguyên bản (#0F1E3D) chìm hẳn vào nền dark — 1,15:1 (bản trước ghi 1,17:1, sai). Bậc
+     ink gánh vai trò đó (7,40:1 trên --background · 6,95:1 trên --card), và --chart-3 vì trỏ vào
+     --navy-ink nên tự đúng, không cần khai lại ở đây nữa. */
+  --navy-ink: #7ea2e8;
+
+  /* KHÔNG khai lại --*-foreground của trạng thái và của màu phụ: chúng là MỰC (#0E1116) ở cả hai
+     theme vì cả hai bản màu đều sáng — xem bảng số ở :root. --navy-foreground cũng vậy (trắng),
+     vì khối này không override --navy. */
 
   /* Đổ bóng bản dark — bóng "mực" 4–16% trên nền #0E1116 gần như vô hình, lớp overlay
      mất sạch tín hiệu độ cao (dialog/popover trông như dán phẳng vào nền). Trên nền tối,
@@ -199,9 +462,6 @@
   --elevation-control: 0 1px 2px rgba(0, 0, 0, 0.4);
   --elevation-card: 0 1px 2px rgba(0, 0, 0, 0.32), 0 8px 24px rgba(0, 0, 0, 0.4);
   --elevation-overlay: 0 8px 32px rgba(0, 0, 0, 0.64);
-
-  /* navy nguyên bản chìm hẳn vào nền dark → chỉ nâng ở vai trò biểu đồ. */
-  --chart-3: #7ea2e8;
 }
 
 /* ────────────────────────────────────────────────────────────────────────────
@@ -232,6 +492,7 @@
   --color-popover-foreground: var(--popover-foreground);
   --color-primary: var(--primary);
   --color-primary-foreground: var(--primary-foreground);
+  --color-primary-ink: var(--primary-ink);
   --color-secondary: var(--secondary);
   --color-secondary-foreground: var(--secondary-foreground);
   --color-muted: var(--muted);
@@ -240,9 +501,17 @@
   --color-accent-foreground: var(--accent-foreground);
   --color-destructive: var(--destructive);
   --color-destructive-foreground: var(--destructive-foreground);
+  --color-destructive-ink: var(--destructive-ink);
+  /* Ranh giới: `border-border` là TRANG TRÍ (không ngưỡng) · `border-input` /
+     `border-control-edge` là VIỀN CONTROL (3:1) · `border-control-edge-strong` cho hover/active.
+     `bg-control-on` + `text-control-knob` là cặp của control BẬT/ĐÃ CHỌN. */
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
+  --color-control-edge: var(--control-edge);
+  --color-control-edge-strong: var(--control-edge-strong);
+  --color-control-on: var(--control-on);
+  --color-control-knob: var(--control-knob);
 
   /* Sidebar */
   --color-sidebar: var(--sidebar);
@@ -274,12 +543,23 @@
   --color-ash-700: var(--ash-700);
   --color-ash-900: var(--ash-900);
 
-  /* Màu phụ */
+  /* Màu phụ (tô NỀN) và bậc ink của chúng (làm CHỮ/ICON/VIỀN trên nền trang) */
   --color-navy: var(--navy);
   --color-teal: var(--teal);
   --color-red: var(--red);
   --color-green: var(--green);
   --color-yellow: var(--yellow);
+  --color-navy-ink: var(--navy-ink);
+  --color-teal-ink: var(--teal-ink);
+  --color-red-ink: var(--red-ink);
+  --color-green-ink: var(--green-ink);
+  --color-yellow-ink: var(--yellow-ink);
+  /* Chữ trên nền màu phụ ĐẶC. Không có `red-foreground`: nền --red đặc không mang được chữ ở
+     light (4,38 / 4,32:1) → dùng `bg-destructive text-destructive-foreground`. */
+  --color-navy-foreground: var(--navy-foreground);
+  --color-teal-foreground: var(--teal-foreground);
+  --color-green-foreground: var(--green-foreground);
+  --color-yellow-foreground: var(--yellow-foreground);
 
   /* Trạng thái */
   --color-success: var(--success);
@@ -288,6 +568,9 @@
   --color-warning-foreground: var(--warning-foreground);
   --color-info: var(--info);
   --color-info-foreground: var(--info-foreground);
+  --color-success-ink: var(--success-ink);
+  --color-warning-ink: var(--warning-ink);
+  --color-info-ink: var(--info-ink);
 
   /* Biểu đồ */
   --color-chart-1: var(--chart-1);
@@ -296,9 +579,13 @@
   --color-chart-4: var(--chart-4);
   --color-chart-5: var(--chart-5);
 
-  /* Accent theo app */
+  /* Accent theo app — `bg-app-accent` (nền) · `text-app-accent-foreground` (chữ trên nền đó)
+     · `text-app-accent-ink`/`bg-app-accent-ink` (màu app trên nền trang). Utility
+     `text-app-accent` VẪN được sinh ra vì Tailwind sinh cả bộ cho mọi --color-*; nó nằm ngoài
+     hợp đồng dùng — xem chú thích ở :root trước khi định dùng. */
   --color-app-accent: var(--app-accent);
   --color-app-accent-foreground: var(--app-accent-foreground);
+  --color-app-accent-ink: var(--app-accent-ink);
 
   /* Đổ bóng — sinh shadow-surface / shadow-control / shadow-card / shadow-overlay.
      BẮT BUỘC là @theme *inline* và tên biến nguồn phải KHÁC (--elevation-*): khai
@@ -328,6 +615,9 @@
    7. BASE LAYER + utility riêng của Comitor
    ──────────────────────────────────────────────────────────────────────────── */
 @layer base {
+  /* ⚠ Dòng `border-border` này gán VIỀN TRANG TRÍ (1,16:1) làm mặc định cho MỌI phần tử — tiện
+     cho đường kẻ, nhưng nghĩa là control nào chỉ viết `border` mà quên nêu màu sẽ tàng hình mà
+     không có gì báo. Control luôn phải nêu `border-input`/`border-control-edge`. */
   * {
     @apply border-border outline-ring/50;
   }