@comitor/ui 0.2.1 → 0.3.0

package/styles.css

@@ -29,6 +29,55 @@
       cạnh nhau thì phải bọc thêm một lớp: <div class="dark"><div>…</div></div>. */
 @custom-variant dark (&:is(.dark *));
 
+/* ════════════════════════════════════════════════════════════════════════════
+   NGUỒN SỰ THẬT — ĐỌC TRƯỚC KHI ĐỔI BẤT KỲ GIÁ TRỊ NÀO Ở DƯỚI
+
+   Bảng màu và style component của gói này KHỚP VỚI comitor-ds (repo design system đã được
+   duyệt). comitor-ds là bản duyệt về HÌNH THỨC và nó thắng khi có mâu thuẫn.
+
+   0.2.x từng đi hướng ngược lại: nó tự sửa một loạt giá trị của comitor-ds để đạt ngưỡng WCAG,
+   và hệ quả là app dựng trên gói KHÔNG còn giống bản duyệt — mất gold ở mọi control đang BẬT,
+   viền ô nhập đậm hẳn lên, đỏ và chữ phụ tối đi. 0.3.0 kéo tất cả về đúng comitor-ds.
+
+   ─ HAI BẢNG MÀU, MỘT BỘ COMPONENT ─
+   Bảng màu đã đo của 0.2.x KHÔNG bị xoá: nó thành bảng thứ hai, bật bằng
+   `<html data-contrast="high">` (khối 5b bên dưới), do NGƯỜI DÙNG chọn trong phần cài đặt của
+   app. Lý do có nó: bảng comitor-ds đủ rõ trên màn hình tốt nhưng không đủ trên màn hình rẻ,
+   độ sáng thấp, hoặc ngoài nắng.
+
+   Điều kiện để hai bảng cùng sống: MỌI component đi qua TOKEN VAI TRÒ (--control-on,
+   --control-edge, --control-check, --switch-track, --slider-track, --primary-ink, --link-ink…)
+   chứ không viết thẳng `bg-gold-300` / `bg-ash-300` / `text-gold-400`. Viết thẳng thang màu là
+   khoá cứng một bảng và bảng kia lặng lẽ sai — đó là lỗi dễ mắc nhất khi thêm component mới.
+
+   ─ NHỮNG KHOẢN DƯỚI NGƯỠNG CỦA BẢNG MẶC ĐỊNH, ĐÃ BIẾT VÀ ĐÃ CHẤP NHẬN ─
+   Ghi ra để không ai tưởng là lỗi bỏ sót và "sửa" lại lần nữa — chỗ để sửa là bảng tương phản
+   cao, không phải bảng mặc định. Cột cuối là ngưỡng WCAG mà khoản đó không đạt:
+
+       viền control (--input / --control-edge) trên nền trang    1,16:1   (1.4.11 · 3:1)
+       rãnh Switch BẬT (--control-on) ⇄ nền trang và ⇄ núm       1,86:1   (1.4.11 · 3:1)
+       gạch active của Tabs, viền focus ô nhập (gold)            1,86:1   (1.4.11 · 3:1)
+       --muted-foreground trên --muted                           3,58:1   (1.4.3 · 4,5:1)
+       chữ trắng trên nền --destructive                          4,38:1   (1.4.3 · 4,5:1)
+       Button variant link (--gold-400) trên nền trang           3,15:1   (1.4.3 · 4,5:1)
+       Badge destructive: --red trên red/10                      3,82:1   (1.4.3 · 4,5:1)
+
+   ─ HAI NGOẠI LỆ GIỮ BẢN SỬA Ở CẢ HAI BẢNG MÀU ─
+   Chỉ hai chỗ mà màu chữ của comitor-ds gần trùng màu nền tới mức không đọc nổi trên BẤT KỲ màn
+   hình nào, nên chúng không chờ người dùng bật tương phản cao. Nền giữ NGUYÊN của bản duyệt,
+   chỉ đậm chữ:
+
+       Badge warning   --yellow trên yellow/10 = 1,52:1  →  --yellow-ink = 6,24:1
+       Badge success   --green  trên green/10  = 2,82:1  →  --green-ink  = 5,88:1
+
+   ─ NGOÀI PHẠM VI ĐỐI CHIẾU ─
+   comitor-ds không có các cụm sau, nên không có bản duyệt nào để khớp và chúng giữ nguyên bảng
+   màu đã đo của gói: toàn bộ tầng composite (StatusPill, StatCard, DataTable, Toast,
+   FilterChips, LetterAvatar, EmptyState…), tầng shell (AppShell, Sidebar, AppLauncher…),
+   --app-accent-ink, và thang đổ bóng bản dark (--elevation-* trong .dark — comitor-ds không
+   khai bóng cho dark).
+   ════════════════════════════════════════════════════════════════════════════ */
+
 /* ────────────────────────────────────────────────────────────────────────────
    4. BIẾN — LIGHT
    ──────────────────────────────────────────────────────────────────────────── */
@@ -107,8 +156,14 @@
      % 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). */
+     ⚠ PHẠM VI ÁP DỤNG TỪ 0.3.0: hợp đồng này chỉ còn áp cho các cụm TONAL mà comitor-ds KHÔNG
+     có (Badge success/warning, StatusPill, LetterAvatar, StatCard, Toast) — đó là chỗ chữ đứng
+     trên tint của chính nó và bậc ink là thứ duy nhất giữ được chữ đọc ra. Với các primitive CÓ
+     trong comitor-ds (Button, Input, Switch, Checkbox, Tabs, Alert, Form…), bản duyệt là nguồn
+     sự thật và bậc ink đã được gỡ khỏi đường render — xem khối NGUỒN SỰ THẬT ở đầu file.
+
+     Ở DARK, --x-ink trỏ về var(--x): comitor-ds dùng một hex cho cả hai theme, nên bên dark bậc
+     ink chính là màu phụ. */
   --teal-ink: #1a6668;
   --green-ink: #216a48;
   --red-ink: #9a3537;
@@ -147,47 +202,44 @@
   --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);
+     trò ở khối "Bậc INK của màu phụ" bên trên.
+
+     ⚠ TỪ 0.3.0: --primary-ink TRỎ THẲNG VỀ --primary ở cả hai theme. comitor-ds tô gold #E8B824
+     cho mọi vai trò brand — kể cả những vai trò mà WCAG 1.4.11 đòi 3:1 (rãnh Switch BẬT, ô
+     Checkbox đã chọn, gạch active của Tabs, viền focus của ô nhập) — và bản duyệt đó là nguồn
+     sự thật. Bậc tối #7A5800 mà vòng token trước dùng cho các vai trò này ĐÃ ĐƯỢC GỠ; số đo còn
+     tồn: gold trên nền trắng 1,86:1 (dưới 3:1). Xem khối NGUỒN SỰ THẬT ở đầu file.
+
+     Token vẫn TỒN TẠI như API công khai (app đang import `text-primary-ink`) và vẫn là chỗ để
+     app ghi đè nếu muốn một bậc tối hơn cho brand của mình. Chỗ DUY NHẤT trong gói còn giữ bậc
+     tối là --app-accent-ink (accent theo app, không có bản duyệt nào để khớp) và ba tone tonal
+     của Badge/StatusPill. */
+  --primary-ink: var(--primary);
   --secondary: #ede8d8;
   --secondary-foreground: #0e1116;
   --muted: #f7f7f8;
-  /* 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;
+  /* Bậc chữ phụ (placeholder, mô tả, nhãn trục biểu đồ). Giá trị của comitor-ds, bằng đúng
+     --ash-500. Số đo còn tồn (dưới AA 4,5:1 — ĐÃ BIẾT VÀ CHẤP NHẬN, xem khối NGUỒN SỰ THẬT ở
+     đầu file): 3,83:1 trên --background · 3,58:1 trên --muted · 3,67:1 trên --sidebar. */
+  --muted-foreground: #7e8290;
   --accent: #fbf5dc;
   --accent-foreground: #0e1116;
-  /* Đỏ 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;
+  /* Đỏ dùng làm NỀN (nút xoá, chấm huy hiệu). Giá trị của comitor-ds, ghim cho cả hai theme và
+     BẰNG ĐÚNG --red (bản duyệt không tách hai bậc). Số đo còn tồn: chữ trắng trên nền này được
+     4,38:1 — thiếu 0,12 so với AA 4,5:1. Xem khối NGUỒN SỰ THẬT ở đầu file. */
+  --destructive: #d64545;
   --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);
+  /* Nền nút xoá lúc HOVER. Phải là token riêng vì hai bảng màu đi hai HƯỚNG ngược nhau:
+     comitor-ds viết `hover:bg-red/90`, tức NHẠT dần về phía nền — #DA5A5A là đúng thứ nó render
+     trên trang trắng. Bảng tương phản cao thì phải ĐẬM thêm, nếu không chữ trắng tụt xuống
+     4,32:1. Ghim hex thay vì `/90` vì `/90` phụ thuộc nền phía sau: trên nền tối nó cho ra một
+     màu khác hẳn và không ai đo được. */
+  --destructive-hover: #da5a5a;
+  /* Chữ báo lỗi trên nền TRANG (helper text của Input, dòng lỗi của Form). comitor-ds viết thẳng
+     `text-destructive` / `border-red` cho vai trò này, tức CÙNG một hex với nền đỏ — nên token
+     trỏ về --destructive. Số đo: 4,38:1 trên --background (light) · 4,06:1 trên --card (dark).
+     Token giữ lại vì là API công khai và là chỗ app ghi đè nếu muốn bậc đỏ tối hơn. */
+  --destructive-ink: var(--destructive);
   /* ─ 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
@@ -198,74 +250,73 @@
                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 (= --input)   VIỀN CONTROL. TỪ 0.3.0 token này TRỎ VỀ --input, tức bằng
+           đúng bậc trang trí của comitor-ds (#EDEEF1 light · #1E2128 dark). Bản duyệt vẽ viền ô
+           nhập ở bậc đó và bản duyệt là nguồn sự thật; số đo còn tồn là 1,16:1, dưới 3:1 của
+           WCAG 1.4.11 — xem khối NGUỒN SỰ THẬT ở đầu file.
+           Dùng cho: Input/Textarea/Select/Combobox, ô Checkbox chưa chọn, viền Radio, rãnh
+           Slider, Button variant outline/secondary, Badge variant outline, ô tìm của
+           WorkspaceSwitcher. (Rãnh Switch khi TẮT KHÔNG đi qua đây — comitor-ds dùng
+           `bg-gray-300 dark:bg-gray-700`, xem switch.tsx.)
 
-       --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.
+       --control-edge-strong   Cùng vai trò nhưng ở HOVER/ACTIVE. Giá trị của comitor-ds:
+           `hover:border-gray-300` ở light (--ash-300) và `dark:hover:border-gray-500` ở dark
+           (--ash-500).
 
      ⚠ `@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;
-  /* 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);
+  /* Viền ô nhập — giá trị của comitor-ds, cùng bậc với --border. Khối .dark khai lại (#1E2128). */
+  --input: #edeef1;
+  /* LỚP TÔ của ô nhập ở dark — comitor-ds viết `dark:bg-input/30`, và nó không phải trang trí:
+     ở dark viền --input (#1E2128) trên --card (#16181D) chỉ 1,10:1, nên lớp tô mờ này là thứ
+     DUY NHẤT còn khoanh vùng được ô Radio và ô OTP. Phải là token riêng chứ không viết thẳng
+     `bg-input/30`: ở bảng tương phản cao --input là #7E8290, tô 30% ra một mảng xám sáng làm
+     placeholder tụt còn 3,22:1 — bên đó viền đã đủ đậm nên lớp tô thành trong suốt.
+     Ở light comitor-ds không tô (class chỉ có nhánh `dark:`) nên giá trị này không được dùng. */
+  --input-fill: transparent;
   --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);
+  /* Trỏ về --input, không còn là một bậc xám riêng. Token giữ lại vì component trong gói đang
+     viết `border-control-edge` và vì app có thể ghi đè MỘT chỗ này để làm đậm viền control mà
+     không đụng đường kẻ trang trí (--border). Số đo còn tồn: 1,16:1 light · 1,17:1 dark. */
+  --control-edge: var(--input);
+  /* Hover/active của viền control — đúng cặp của comitor-ds: `hover:border-gray-300` (ash-300,
+     #C8CBD3) ở light và `dark:hover:border-gray-500` (ash-500, #7E8290) ở dark. Token hoá để
+     Input/Select/Combobox/Checkbox khỏi chép lệch. */
+  --control-edge-strong: var(--ash-300);
 
   /* ─ 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);
+     Rãnh `Switch` khi BẬT, ô `Checkbox` đã chọn, chấm `Radio`, đoạn đã chọn của `Slider`.
+
+     comitor-ds tô GOLD cho toàn bộ nhóm này (`data-[state=checked]:bg-gold-300`), nên --control-on
+     trỏ thẳng về --primary. Số đo còn tồn, ghi ra để không ai tưởng là bỏ sót: rãnh BẬT so với nền
+     trang 1,86:1 và so với núm trắng cũng 1,86:1 (dưới 3:1 của WCAG 1.4.11) — tức ở light, BẬT/TẮT
+     phân biệt chủ yếu bằng VỊ TRÍ núm và bằng sắc, không bằng độ sáng. Đây là đánh đổi ĐÃ CHỌN, xem
+     khối NGUỒN SỰ THẬT ở đầu file.
+
+     --control-knob là NÚM Switch / chấm Radio: TRẮNG ở cả hai theme, đúng `bg-white` của bản duyệt.
+     ⚠ DẤU CHECK của Checkbox KHÔNG dùng token này — comitor-ds vẽ nó bằng `text-ink` trên nền gold
+     (10,19:1), xem checkbox.tsx.
+     ⚠ App ghi đè --primary là control đổi màu theo ngay, không cần ghi đè thêm gì. */
+  --control-on: var(--primary);
+  --control-knob: #ffffff;
+  /* DẤU CHECK của Checkbox và chữ trên ô ngày ĐANG CHỌN của Calendar — tách khỏi --control-knob
+     vì hai vai trò đòi hai chiều tương phản khác nhau khi --control-on đổi giữa hai bảng màu:
+     bảng comitor-ds tô nền gold SÁNG nên dấu phải là MỰC (10,19:1); bảng tương phản cao tô nền
+     gold-500 TỐI nên dấu phải là màu nền trang (6,51:1). Núm Switch thì luôn trắng ở bảng duyệt,
+     nên nó ở lại --control-knob. */
+  --control-check: var(--ink);
+  /* Rãnh Switch khi TẮT và rãnh Slider — comitor-ds cho hai thứ này hai bậc khác nhau
+     (`bg-gray-300 dark:bg-gray-700` cho Switch, `bg-muted` cho Slider) nên phải là hai token,
+     không gộp được vào --control-edge. */
+  --switch-track: var(--ash-300);
+  --slider-track: var(--muted);
+  /* Button variant `link`. Tách khỏi --primary-ink vì comitor-ds dùng gold-400 cho chữ link
+     nhưng gold-300 cho viền focus/vạch active — hai bậc khác nhau của cùng thang. */
+  --link-ink: var(--gold-400);
+  --link-ink-hover: var(--gold-300);
 
   --sidebar: #fafaf9;
   --sidebar-foreground: #0e1116;
@@ -360,7 +411,11 @@
      đ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);
+  /* Bậc ink của accent app là chỗ DUY NHẤT còn giữ bậc tối sau khi 0.3.0 kéo --primary-ink về
+     gold: vai trò của nó là icon/vạch active của SidebarMenuItem và khung icon của PageHeader —
+     những cụm CHỈ có trong gói, comitor-ds không có bản duyệt nào để khớp. Gold đặc trên
+     --sidebar-accent #FBF5DC chỉ 1,70:1 (icon biến mất), gold-500 được 5,96:1. */
+  --app-accent-ink: var(--gold-500);
 
   /* ─ Số đo khung ứng dụng (shell dùng ở cả CSS lẫn TS — xem tokens.ts) ─ */
   --sidebar-width: 16rem; /* 256px */
@@ -381,7 +436,9 @@
        overlay  — lớp phủ lên nội dung (Dialog, Sheet, Popover, menu, Select, Tooltip) */
   --elevation-surface: 0 1px 2px rgba(14, 17, 22, 0.04);
   --elevation-control: 0 1px 2px rgba(14, 17, 22, 0.08);
-  --elevation-card: 0 1px 2px rgba(14, 17, 22, 0.04), 0 8px 24px rgba(14, 17, 22, 0.04);
+  /* Lớp thứ hai để 0.06 — đúng thứ Card variant="elevated" của comitor-ds render
+     (bản duyệt khai --shadow-card 0.04 nhưng không component nào đọc biến đó). */
+  --elevation-card: 0 1px 2px rgba(14, 17, 22, 0.04), 0 8px 24px rgba(14, 17, 22, 0.06);
   --elevation-overlay: 0 8px 32px rgba(14, 17, 22, 0.16);
 
   --radius: 0.375rem; /* 6px — chữ ký thị giác của Comitor */
@@ -405,23 +462,27 @@
   --secondary: #1e2128;
   --secondary-foreground: #f7f7f8;
   --muted: #1e2128;
-  /* 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;
+  /* Cùng một giá trị với bản light — comitor-ds không khai lại token này trong .dark. Số đo còn
+     tồn (dưới AA, ĐÃ BIẾT VÀ CHẤP NHẬN): 4,21:1 trên --muted · 4,73:1 trên --card. Xem khối
+     NGUỒN SỰ THẬT ở đầu file. */
+  --muted-foreground: #7e8290;
   --accent: #1e2128;
   --accent-foreground: #f7f7f8;
-  /* Ghim đúng giá trị của light — xem chú thích ở :root. */
-  --destructive: #c93b3b;
+  /* Ghim đúng giá trị của light — comitor-ds dùng chung một hex cho cả hai theme. */
+  --destructive: #d64545;
   --destructive-foreground: #ffffff;
   --border: #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);
+  /* Viền ô nhập bản dark của comitor-ds. --control-edge trỏ vào --input nên tự theo; --control-on
+     và --control-knob cũng không khai lại (chúng trỏ vào --primary — đã có bản dark ngay trên —
+     và vào trắng cố định, đúng như núm Switch của comitor-ds). */
+  --input: #1e2128;
+  --input-fill: color-mix(in srgb, var(--input) 30%, transparent);
+  /* Hover viền control bản dark của comitor-ds là dark:hover:border-gray-500, tức ash-500. */
+  --control-edge-strong: var(--ash-500);
+  /* Rãnh Switch khi TẮT bản dark của comitor-ds (dark:bg-gray-700). --slider-track không khai lại
+     vì nó trỏ vào --muted, biến đã có bản dark ngay trong khối này. --control-check cũng vậy:
+     comitor-ds vẽ dấu check bằng text-ink ở CẢ hai theme. */
+  --switch-track: var(--ash-700);
   --ring: #f5d060;
 
   --sidebar: #16181d;
@@ -430,17 +491,13 @@
   --sidebar-accent: #1e2128;
   --sidebar-accent-foreground: #f7f7f8;
 
-  /* Màu phụ bản dark — bản light quá tối để làm CHỮ trên nền #0E1116 (không đạt AA).
-     Các giá trị dưới đây đều ≥ 6:1 trên nền dark. Cần đo lại nếu đổi nền. */
-  --teal: #2dd4bf;
-  --red: #f87171;
-  --green: #4ade80;
-  --yellow: #facc15;
+  /* Màu phụ KHÔNG có bản dark — comitor-ds dùng đúng một hex cho cả hai theme, và bản này theo.
+     Số đo trên tint /20 hợp lên --card (đọc được, tuy dưới AA ở hai tone): teal 3,39 · green 4,26
+     · red 3,34 · yellow 7,02:1.
 
-  /* 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 ✓ */
+     Bậc ink ở dark PHẢI khai lại (chứ không để rơi về hex của :root) vì bản light của --*-ink là
+     bậc tối đóng băng cho vai trò chữ-trên-nền-sá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. Trỏ về chính màu phụ = đúng thứ comitor-ds render ở dark. */
   --teal-ink: var(--teal);
   --green-ink: var(--green);
   --red-ink: var(--red);
@@ -449,6 +506,9 @@
      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;
+  /* Accent app tách khỏi --primary-ink (xem :root): ở dark gold-500 chìm vào nền, nên bậc sáng
+     của brand gánh vai trò này. */
+  --app-accent-ink: var(--primary);
 
   /* 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),
@@ -464,6 +524,74 @@
   --elevation-overlay: 0 8px 32px rgba(0, 0, 0, 0.64);
 }
 
+/* ────────────────────────────────────────────────────────────────────────────
+   5b. BẢNG MÀU THỨ HAI — TƯƠNG PHẢN CAO  `<html data-contrast="high">`
+
+   Bảng mặc định (khối 4 và 5) là comitor-ds: đẹp, đúng brand, và có một số cặp nằm dưới ngưỡng
+   WCAG — trên màn hình tốt thì không thành vấn đề, trên màn hình rẻ / độ sáng thấp / ngoài nắng
+   thì thành vấn đề thật. Khối này là bảng màu đã đo của 0.2.x, bật theo LỰA CHỌN CỦA NGƯỜI DÙNG.
+
+   ─ CÁCH BẬT ─
+   `<ContrastProvider>` của @comitor/ui/shell gắn `data-contrast="high"` lên <html> (kèm script
+   chống nháy, cùng lối với next-themes). App chỉ cần bọc provider và đặt `<ContrastToggle>` vào
+   trang cài đặt — KHÔNG app nào tự khai lại màu.
+
+   ─ VÌ SAO CHỈ KHAI LẠI BIẾN, KHÔNG ĐỘNG VÀO COMPONENT ─
+   Mọi component trong gói đi qua TOKEN VAI TRÒ (--control-on, --control-edge, --control-check,
+   --primary-ink, --link-ink…) chứ không viết thẳng `bg-gold-300`. Nhờ vậy hai bảng màu chỉ khác
+   nhau ở khối này; không có nhánh `data-contrast:` nào rải trong component, và cũng không có cách
+   nào để một bảng màu "quên" một component.
+
+   ⚠ ĐỘ ĐẶC TẢ: [data-contrast="high"] và .dark cùng là (0,1,0). Khối này phải đứng SAU .dark để
+   thắng ở những token nó khai; token nào bản dark của bảng tương phản cao khác bản light thì
+   PHẢI khai lại ở .dark[data-contrast="high"] (0,2,0) bên dưới. Đảo thứ tự hai khối là hỏng.
+   ──────────────────────────────────────────────────────────────────────────── */
+[data-contrast="high"] {
+  /* Chữ phụ: 5,23:1 trên --background · 4,89:1 trên --muted (bảng duyệt: 3,83 / 3,58) */
+  --muted-foreground: #686c7a;
+  /* Nền đỏ + chữ trắng: 5,03:1 (bảng duyệt #D64545 chỉ 4,38:1) */
+  --destructive: #c93b3b;
+  /* Ngược chiều bảng duyệt: color-mix(--destructive, --ink 15%) — chữ trắng 6,19:1 */
+  --destructive-hover: #ad3535;
+  --destructive-ink: var(--red-ink);
+  /* Viền control: 3,83:1 trên nền trắng (bảng duyệt #EDEEF1 chỉ 1,16:1).
+     --control-edge trỏ vào --input nên tự theo. */
+  --input: #7e8290;
+  /* Viền đã đủ đậm ở cả hai theme nên bỏ hẳn lớp tô — nó chỉ làm placeholder khó đọc. */
+  --input-fill: transparent;
+  --control-edge-strong: var(--ash-700);
+  /* Control BẬT/ĐÃ CHỌN: rãnh ⇄ nền 6,51:1 và rãnh ⇄ núm 6,51:1 (bảng duyệt: 1,86 / 1,86) */
+  --control-on: var(--gold-500);
+  --control-knob: var(--background);
+  --control-check: var(--control-knob);
+  --switch-track: var(--control-edge);
+  --slider-track: var(--control-edge);
+  /* Brand khi phải ĐI LÊN nền trang: viền focus, gạch active của Tabs, ngày chọn của Calendar */
+  --primary-ink: var(--gold-500);
+  --link-ink: var(--gold-500);
+  --link-ink-hover: var(--gold-600);
+}
+
+.dark[data-contrast="high"] {
+  /* Sáng hơn bản light: chữ phụ ở dark hay nằm trên --card/--muted chứ ít khi trên nền trang.
+     5,70:1 trên --background · 5,35:1 trên --card · 4,86:1 trên --muted */
+  --muted-foreground: #888d9b;
+  /* Viền control ghim MỘT giá trị cho cả hai theme: 4,94:1 trên nền #0E1116 */
+  --input: #7e8290;
+  --control-edge-strong: var(--ash-300);
+  /* Bảng màu dark đã nâng --primary lên bậc sáng nên bậc ink trỏ thẳng về nó: 12,67:1 */
+  --control-on: var(--primary);
+  --primary-ink: var(--primary);
+  --link-ink: var(--gold-200);
+  --link-ink-hover: var(--gold-100);
+  /* Màu phụ bản dark — bản light quá tối để làm CHỮ trên nền #0E1116. Đo trên tint /15 hợp lên
+     --card: teal 7,12 · green 7,44 · red 5,18 · yellow /20 7,19:1 ✓ */
+  --teal: #2dd4bf;
+  --red: #f87171;
+  --green: #4ade80;
+  --yellow: #facc15;
+}
+
 /* ────────────────────────────────────────────────────────────────────────────
    6. MAP BIẾN → NAMESPACE TAILWIND (sinh bg-*, text-*, border-*, rounded-*…)
 
@@ -501,6 +629,7 @@
   --color-accent-foreground: var(--accent-foreground);
   --color-destructive: var(--destructive);
   --color-destructive-foreground: var(--destructive-foreground);
+  --color-destructive-hover: var(--destructive-hover);
   --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.
@@ -508,10 +637,16 @@
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
+  --color-input-fill: var(--input-fill);
   --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);
+  --color-control-check: var(--control-check);
+  --color-switch-track: var(--switch-track);
+  --color-slider-track: var(--slider-track);
+  --color-link-ink: var(--link-ink);
+  --color-link-ink-hover: var(--link-ink-hover);
 
   /* Sidebar */
   --color-sidebar: var(--sidebar);