@haposoft/cafekit 0.16.7 → 0.18.0

package/src/claude/skills/ui-ux/references/components/small-controls.md

@@ -0,0 +1,340 @@
+# Chip và IconButton
+
+Nguồn: chip và nút icon của một dự án thật.
+
+```tsx
+// Chip: bộ lọc, tag chọn được. Luôn kèm aria-pressed={isActive}
+"inline-flex max-w-48 cursor-pointer items-center rounded-full px-3 py-1 text-xs font-medium outline-hidden transition-colors"
+isActive && "bg-primary text-primary-foreground"
+!isActive && "bg-foreground/5 text-foreground/70 hover:bg-foreground/10 hover:text-foreground"
+
+// IconButton: hành động phụ trong dòng hoặc header
+"inline-flex size-8 cursor-pointer items-center justify-center rounded-lg text-muted transition-colors"
+"hover:bg-foreground/5 hover:text-foreground"   // nằm trong dòng có nền rê: hover:bg-foreground/8
+"outline-hidden"
+"disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:bg-transparent disabled:hover:text-muted"
+```
+
+## Chip có hai cỡ, chọn theo vai trò
+
+Đây là chỗ hay sai: lấy cỡ chip trong widget đem ra làm bộ lọc chính của cả màn,
+rồi hàng đó trông teo lại.
+
+| Vai trò | Cỡ | Đi cạnh cái gì |
+| --- | --- | --- |
+| **Chip phụ trong widget**, tag, nhãn trạng thái | `px-3 py-1 text-xs` (cao ~26px) | Nằm trong card nhỏ, cạnh chữ `text-xs` |
+| **Chip lọc chính của cả màn** | `h-9 px-3.5 text-sm` | Nằm cạnh ô tìm `h-10`, cạnh nút `h-10` |
+
+Nguyên tắc chung: **chip đứng cùng hàng với ô nhập hay nút thì phải gần bằng
+chiều cao của chúng**, lệch quá một bậc là hàng đó trông hỏng. Chip cao 26px
+đứng cạnh input cao 40px thì mắt đọc ra cụm chip là thứ yếu, dù nó là bộ lọc
+chính.
+
+---
+
+**Vì sao ổn**
+
+- **Chip chưa chọn là viên mờ `bg-foreground/5`, chữ `foreground/70`**; rê vào `foreground/10`, chọn rồi tô `bg-primary`. Lớp phủ theo màu chữ nên **mờ như nhau trên cả nền trang xám lẫn card trắng**, không phải chọn token theo nền. Đừng `bg-background`: trên card trắng thành bảy viên xám rõ, hàng lọc chưa ai dùng nặng thứ nhì màn; trên nền trang thì trùng màu nền nên rê vào không thấy gì. Đừng bỏ hẳn nền, chỉ chữ `text-muted`: hàng chip đọc ra như **một hàng tab thứ hai** nằm ngay dưới hàng tab, và `--muted` trên `#f4f4f6` chỉ 3,5:1. Chip phải còn dáng viên thì mới khác tab. Không viền: mười chip mà chip nào cũng có viền thì đọc như hàng rào.
+- Chip nằm **trong popover có nút xác nhận** (popover Lọc) thì đang chọn không tô `bg-primary`, xem "Popover lọc" trong `../layouts/overlay.md`: chip đen đứng cạnh nút Áp dụng đen là hai khối nặng ngang nhau.
+- Nền chip đang chọn là **`bg-primary text-primary-foreground`**, đúng token, không `bg-[#…]`, không `text-white`. Dùng token thì nền tối tự đảo (`--primary` thành gần trắng, chữ thành gần đen); gõ cứng thì sang nền tối thành chữ trắng trên nền trắng. Cũng đừng lấy nhầm `--primary-hover`: chip đang chọn trông nhạt hơn nút chính ngay cạnh.
+- **Nhãn dài thì cắt, không để chip phình.** Chip `max-w-48`, chữ bọc trong `<span class="truncate">`, và `title` mang đủ tên để rê vào vẫn đọc được. Một chip "Hội chợ Triển lãm Quốc tế 2026" rộng gấp bốn chip "VIP" là cả hàng lệch, mắt dồn hết vào cái dài nhất.
+- **Chip lọc là nút bật/tắt, phải có `aria-pressed={isActive}`.** Trạng thái chọn hiện chỉ bằng màu nền, trình đọc màn hình không thấy màu, nên thiếu `aria-pressed` thì chip nào cũng đọc ra "nút" như nhau. Chip chọn một (kiểu tab) thì dùng `role="radio"` + `aria-checked` trong `role="radiogroup"`, không dùng `aria-pressed`.
+- Chip là `rounded-full`, nút là `rounded-xl` (cao dưới 40px thì `rounded-lg`, `F1`). Khác hình để mắt biết ngay cái nào chọn được nhiều cái nào là hành động.
+- IconButton vuông `size-8`, chữ `text-muted` lúc thường, chỉ đen lên khi hover. Icon phụ không được đen bằng nội dung.
+- **Nền rê của IconButton là lớp phủ `bg-foreground/5`, không `bg-background`.** Nút hay nằm trong dòng rê `hover:bg-item-hover` (`list-row.md`): rê vào nút thì nền nút trùng nền dòng, nút mất hẳn. Lớp phủ lấy màu nền phía sau nên đậm hơn nền quanh nó ở mọi chỗ. **Nằm trong dòng có nền rê thì lên `hover:bg-foreground/8`** (`I10`): `/5` chồng lên nền dòng đang rê gần như trùng.
+- Trạng thái disabled phải tắt luôn cả hover (`disabled:hover:bg-transparent`). Thiếu dòng đó thì nút chết vẫn sáng lên khi rê vào, người dùng bấm hoài không hiểu sao.
+- `aria-label` và `title` luôn nhận cùng một chuỗi `label`. Nút chỉ có icon thì bắt buộc.
+
+---
+
+## Chip lọc đang áp dụng (có ×) ⚑
+
+Hàng tóm tắt lọc cạnh số kết quả (*8 kết quả · [Gần bệnh viện ×] [Gần cao đẳng ×] Xoá lọc*)
+là **nút bỏ lọc**, không phải nút bật / tắt như chip lọc. Khác vai thì khác hình:
+
+```html
+<button type="button" aria-label="Bỏ lọc Gần bệnh viện"
+  class="inline-flex h-8 shrink-0 cursor-pointer items-center gap-1 rounded-full border border-border-strong bg-surface pr-2 pl-3 text-sm text-foreground outline-hidden transition-colors hover:bg-button-hover">
+  Gần bệnh viện <i data-lucide="x" class="size-3.5 text-muted"></i>
+</button>
+```
+
+- **Viền, không nền xám, không tô màu nhấn.** Nền `bg-foreground/5` là hình của chip **chưa
+  chọn** ở hàng lọc: hàng tóm tắt dùng nền đó thì đọc thành "chưa chọn", ngược nghĩa. Tô
+  `bg-primary` thì thành khối màu thứ ba, thứ tư cạnh chip đang chọn phía trên (`N3`). Viền
+  `--border-strong` như nút viền (`M14`): đọc ra "bấm được, bấm là bỏ".
+- **Cả chip là nút bỏ lọc**, không chỉ dấu ×; `aria-label` nói rõ bỏ lọc gì.
+- Nhãn ghi đủ nghĩa khi đứng một mình ("Gần bệnh viện", "Dưới 8 triệu"), không chỉ "Bệnh viện".
+- **Chỉ hiện lọc không nhìn thấy từ ngoài**: lọc chọn trong dropdown, popover, panel (khu vực,
+  giá thuê, dạng phòng). Lọc là chip hiện sẵn trên trang thì chip đang chọn đã nói rồi, không
+  lặp ở hàng tóm tắt ("Hai chỗ một việc", `V1b`; chủ dự án chốt).
+- **"Xoá lọc"** là nút ghost chữ cuối hàng, hiện khi có ít nhất một lọc, **kể cả lọc là chip**
+  ở trên: nó bỏ hết một lần. Không có lọc ẩn nào thì hàng chỉ còn số kết quả và "Xoá lọc".
+
+## Hàng chip ở màn hẹp
+
+Hàng chip lọc **không bao giờ `flex-wrap`**. Bốn chip ở 375px sẽ thành ba cái
+một hàng và một cái rớt xuống đứng một mình, đọc ra như lỗi chứ không như thiết
+kế.
+
+```html
+<!-- Khối bọc hàng có lề ngang ít hơn 4px so với các khối khác (card px-5 thì khối này px-4, R6):
+     hàng bên trong px-1 đưa chip đầu về thẳng cột. -->
+<div class="scrollbar-clean overflow-x-auto py-0.5">
+  <div class="flex items-center gap-2 px-1">
+    <button type="button" aria-pressed="true" class="shrink-0 cursor-pointer rounded-full bg-primary px-3 py-1 text-xs font-medium text-primary-foreground outline-hidden">Tất cả</button>
+    <button type="button" aria-pressed="false" class="shrink-0 cursor-pointer rounded-full bg-foreground/5 px-3 py-1 text-xs font-medium text-foreground/70 outline-hidden hover:bg-foreground/10 hover:text-foreground">Quá hạn</button>
+    <button type="button" aria-pressed="false" title="Hội chợ Triển lãm Quốc tế 2026" class="max-w-48 shrink-0 cursor-pointer rounded-full bg-foreground/5 px-3 py-1 text-xs font-medium text-foreground/70 outline-hidden hover:bg-foreground/10 hover:text-foreground">
+      <span class="block truncate">Hội chợ Triển lãm Quốc tế 2026</span>
+    </button>
+  </div>
+</div>
+```
+
+`shrink-0` để chip không bị bóp méo, `scrollbar-clean` để không lòi thanh cuộn ra. Ẩn thanh thì ở máy có chuột phải có nút mũi tên ở phía còn chip khuất (`responsive.md`, sau `R10`). Chip **đang lọc** (bấm để gỡ) thì khác: từ `sm` xuống dòng, "Xoá lọc" luôn thấy (`responsive.md`, sau `R6`).
+
+Lề thì đặt trên **hàng bên trong**, đừng đặt trên khung cuộn: `<div class="overflow-x-auto"><div
+class="flex gap-2 px-1">`. Padding bên phải của khung cuộn bị bỏ qua khi cuộn tới cuối, nên chip
+cuối sẽ dính sát mép. **Khung cuộn không kéo ra bằng `-mx-1`** (`N11`): khối bọc nó lùi lề ít hơn
+4px, các khối anh em giữ lề đủ (cách của `R6`).
+
+---
+
+## Thanh tab: bốn variant, chọn theo chỗ đứng
+
+Tab và chip trông na ná nhưng là hai thứ khác nhau:
+
+| | Tab | Chip lọc |
+| --- | --- | --- |
+| Chọn | **Đúng một**, luôn có một cái đang chọn | Không, một, hoặc nhiều |
+| Ví dụ | Tất cả / Đang giao dịch / Tiềm năng / Ngừng | Nhãn, người phụ trách, khoảng giá |
+| Hình | Theo variant bên dưới | Pill `rounded-full`, đang chọn tô đặc |
+
+### Chọn variant
+
+| Variant | Hình | Đặt ở đâu |
+| --- | --- | --- |
+| `boxed` (mặc định) | Chữ trơn, tab đang chọn là **ô nền nhạt viền mảnh** | Trên bảng / danh sách, chuyển trạng thái: Tất cả / Chờ xử lý / Đã giao |
+| `underline` | Đường kẻ chạy hết hàng, **vạch 2px** dưới tab đang chọn | Chia nội dung trang chi tiết hoặc khối lớn: Tổng quan / Hoạt động / Tệp. **Điều hướng giữa các trang cài đặt**: Hồ sơ / Thông báo / Bảo mật (`../layouts/app.md`, "Khu cài đặt có nhiều trang") |
+| `solid` | Tab đang chọn là **pill tô màu nhấn**, chữ đảo màu | Chỉ khi người dùng chọn. Không cho khu cài đặt: trang đầy công tắc bật đã tô `--primary`, viên đen ở đầu trang tranh với chúng |
+| `segmented` | **Rãnh chìm** nhạt, tab đang chọn là **ô trắng nổi** như phím bấm | 2–4 lựa chọn ngắn đổi cách xem: Ngày / Tuần / Tháng, Danh sách / Lưới |
+
+- **Ngay dưới hàng tab còn một hàng chip lọc thì tab dùng `underline`, không `boxed`.** Chip là viên xám bo tròn; tab `boxed` đang chọn cũng là viên xám bo góc. Hai hàng viên xám chồng nhau thì tab đang chọn đọc ra như một cái chip nữa, không ai thấy đó là trạng thái đang xem. Vạch dưới 2px là ngôn ngữ khác hẳn viên, hai hàng tách nhau ngay (`N5`).
+- **Một trang chỉ một variant cho mỗi vai.** Tab trạng thái trên bảng đã `boxed` thì mọi bảng trong app đều `boxed`.
+- **`solid` không dùng cho tab trạng thái trên bảng.** Pill tô đặc đứng đầu bảng thì kéo mắt mạnh hơn cả dữ liệu, và đọc ra như một nút bấm. Đừng dùng cho khu cài đặt: viên đen đứng trên sáu công tắc bật cũng đen, chữ trong viên thụt `px-3` lệch cột với tiêu đề mục bên dưới. Khu cài đặt dùng `underline`.
+- `segmented` quá 4 lựa chọn, hoặc nhãn dài hơn hai chữ, thì đổi sang `boxed` hoặc `underline`.
+
+### Mặc định khi đề không nói: không icon, không số
+
+Tab dựng ra khi người dùng không nhắc gì là **chữ trơn**, không icon, không số đếm.
+Chỉ thêm khi:
+
+- **Icon:** người dùng yêu cầu, hoặc dự án đã có hàng tab dùng icon (theo cái đã có).
+- **Số đếm:** người dùng yêu cầu ("có số đếm từng tab"), hoặc dữ liệu thật trả về sẵn số. Không bịa số cho có. Ca hay gặp: tab bản ghi con ở trang chi tiết ("Đơn hàng 24", "Tệp 4"); tab dòng chảy (Tin nhắn, Hoạt động) vẫn chữ trơn (`layouts/app.md`).
+
+### Icon: khi có thì theo ba luật
+
+Icon trước chữ **không bắt buộc**, xem mặc định ở trên. Có thì:
+
+- **Có thì mọi tab trong hàng đều có**, không tab có tab không.
+- Icon `size-4 shrink-0`, lấy từ thư viện icon của dự án, **màu ăn theo chữ** (`currentColor`): tab chưa chọn icon xám cùng chữ, tab đang chọn icon đậm cùng chữ. Không tô icon màu riêng.
+- `segmented` chỉ có icon, không chữ, thì mỗi tab phải có `aria-label` và tooltip.
+
+### Chung cho mọi variant
+
+```tsx
+<div role="tablist" aria-label="Lọc theo trạng thái" className={getTabListClasses(variant)}>
+  {views.map((view) => {
+    const isSelected = view.value === activeView;
+
+    return (
+      <Button
+        key={view.value}
+        variant="ghost"
+        role="tab"
+        aria-selected={isSelected}
+        tabIndex={isSelected ? 0 : -1}
+        onClick={() => onChange(view.value)}
+        className={getTabClasses(variant, isSelected)}
+      >
+        {view.icon && <view.icon className="size-4 shrink-0" />}
+        {view.label}
+        {view.count !== undefined && <span className="text-xs font-normal tabular-nums text-muted">{view.count}</span>}
+        {view.isNew && <span className={getNewBadgeClasses(isSelected)}>Mới</span>}
+      </Button>
+    );
+  })}
+</div>
+```
+
+- **Mọi tab cùng `font-medium`**, kể cả tab chưa chọn. Đổi độ đậm lúc chọn làm chữ nở ra và cả hàng xô ngang.
+- Tab chưa chọn chữ `foreground/70`. Hover dùng nền `foreground/5` (riêng `underline` thì chỉ đậm chữ, không nền, xem dưới); focus bàn phím không vòng (`I13`), **không bao giờ là nền xám**. Không dùng `--background` làm nền hover: tab hay nằm thẳng trên nền trang xám, tô `--background` ở đó thì rê vào không thấy gì.
+- Bàn phím theo WAI-ARIA: chỉ tab đang chọn nằm trong vòng Tab, mũi tên trái/phải chuyển và chọn luôn, Home/End về hai đầu.
+- Số đếm là số trơn `text-foreground/70`, không pill, không màu. **Không `text-muted`**: tab `boxed` đang chọn có nền `--secondary`, `--muted` trên đó chỉ 4.04 : 1 (`styles.md`). Trên tab đang chọn (chữ `--foreground`) số vẫn nhạt hơn nhãn một bậc; trên tab chưa chọn thì số và nhãn cùng màu, vậy là đủ. Không có số thì bỏ, đừng dựng số giả.
+- Hàng tab không bao giờ wrap, màn hẹp thì cuộn ngang trong khung `scrollbar-clean` (`R6`). Từ 6 tab trở lên thì gom phần dư vào tab "Thêm" mở dropdown (`R10`).
+
+### `boxed`: tab trạng thái trên bảng
+
+```ts
+// Khung cuộn py-0.5, khối bọc lề ít hơn 4px (R6, không -mx-1): nền hover tab đầu/cuối không bị cắt. Hàng: gap-1 px-1.
+"h-9 rounded-lg border px-3"
+isSelected && "border-transparent bg-secondary text-foreground"
+!isSelected && "border-transparent text-foreground/70 hover:bg-foreground/5 hover:text-foreground"
+```
+
+- **Mọi tab luôn có `border`**, tab chưa chọn là `border-transparent`. Không thì lúc bấm chuyển, tab đang chọn dày thêm 2px và cả hàng xô sang phải.
+- **Tab đang chọn: nền `--secondary`, chữ `--foreground`, viền trong suốt.** Đây là bậc xám duy nhất chìm đủ rõ trên **cả** card trắng lẫn nền trang `#f4f4f6`. Nền tối thì `--secondary` là trắng phủ 8%, sáng lên thay vì chìm, cùng độ chênh (`M21`).
+- **Không dùng `bg-surface` (trắng) và cũng không dùng `bg-surface-hover`.** Hai bậc đó chỉ chênh nền trắng 1-3% thì liếc vào không thấy tab nào đang chọn.
+- **Ô đang chọn phải chênh với nền NẰM DƯỚI nó**, không phải chênh với mấy tab anh em. Cùng một class mà đổi chỗ đặt (card trắng ↔ nền trang xám) là đổi luôn độ rõ, nên chọn bậc xám nào cũng phải thử ở cả hai nền (`N2`).
+- **Không đặt hàng `boxed` vào một khối xám riêng.** Nó nằm thẳng trên nền trang hoặc trên card. Bọc thêm khối xám là thành `segmented` hỏng: rãnh to, đậm, và ô trắng lọt thỏm.
+- **`h-9 rounded-lg`**, cao dưới 40px nên bo 8px (`F1`), không ngoại lệ. Đừng bo 12px: tab 36px bo 12px là quá tròn so với chiều cao. Đứng cạnh ô tìm `h-10` là lệch đúng một bậc, chấp nhận được.
+- Bên phải cùng hàng: ô tìm, nút **Lọc** (mở popover cho các trường khác ngoài trạng thái), nút **Sắp xếp** nếu cần. Đều là nút viền `h-10 rounded-xl` (`I1`), **cao bằng ô tìm `h-10`**: cả hàng công cụ một chiều cao, như bảng cỡ ở đầu file. Nút `h-9` đứng sát ô tìm `h-10` thì đáy lệch 4px, trông như hàng bị hỏng.
+
+### `underline`: chia nội dung trang chi tiết
+
+```ts
+// Hàng: đường kẻ chạy hết bề ngang, vẽ bên trong hàng (bóng inset 1px ở đáy), vạch của tab đang chọn đè lên nó.
+"flex min-w-full gap-2 px-2 shadow-[inset_0_-1px_0_var(--border-strong)]"
+// Tab: vạch là ::after nên không đẩy chiều cao. box-content h-10 pb-px: tab cao 41px phủ cả dòng kẻ, vạch bottom-0 đè đúng lên nó.
+"relative box-content h-10 rounded-xl px-2 pb-px after:absolute after:inset-x-2 after:bottom-0 after:h-0.5 after:rounded-full"
+isSelected && "text-foreground after:bg-foreground"
+!isSelected && "text-foreground/70 after:bg-transparent hover:text-foreground"
+```
+
+- **Hàng tab nằm chung hàng với ô tìm và nút (toolbar trên bảng) thì bỏ đường kẻ hết hàng, chỉ giữ vạch 2px dưới tab đang chọn.** Đường kẻ chạy nửa hàng rồi cụt ở mép ô tìm trông dở dang, và vì khung cuộn rộng hơn cột nội dung 8px mỗi bên (để chữ tab đầu thẳng cột) nên đầu trái của nó còn thò ra ngoài mép card bên dưới 8px. Đường kẻ hết hàng chỉ dùng khi hàng tab đứng riêng một hàng, như trang chi tiết.
+- Vạch màu `--foreground`, không màu nhấn có sắc: nhấn đã có ở nút chính của trang (`M3`).
+- **Vạch không kéo xuống bằng `after:-bottom-px`** đè lên `border-b` của hàng (`N11`). Khung cuộn `overflow-x-auto` cũng cắt theo chiều dọc, nên khi đường kẻ nằm ở khối bọc ngoài khung cuộn (khu cài đặt) thì mép dưới vạch bị cắt, vạch chỉ còn 1px trên đường kẻ. Bản `box-content pb-px` + `bottom-0` nhìn y hệt bản số âm ở hàng tab đứng riêng (trang chi tiết, panel), và ở khu cài đặt thì vạch hiện đủ 2px.
+- Khối bọc hàng tab lùi lề ít hơn 8px (`R6`), khung cuộn không `-mx-2` (`N11`): chữ tab đầu thẳng cột với nội dung bên dưới.
+- Tab đang chọn không tô nền, không đổi nền lúc hover. Vạch là tín hiệu duy nhất.
+- **Không tab nào có nền, kể cả lúc focus.** Tab bàn phím tới thì không đổi gì (`I13`). Tab là `Button variant="ghost"` mà `Button` dự án còn kiểu cũ "focus trông như hover" (nền xám) thì hàng tab dính theo: tab đang focus có nền xám, tab đang rê chuột đậm chữ, **hai tab cùng sáng** và không đọc ra tab nào đang chọn. Sửa ở `Button` dùng chung, không vá riêng từng tab.
+- Hàng tab nằm được cả trên card trắng lẫn trên dải header xám: đường kẻ `--border-strong` đủ nhìn ở cả hai.
+
+### `solid`: pill tô đặc (chỉ khi người dùng chọn)
+
+```ts
+"h-9 rounded-lg px-3"
+isSelected && "bg-primary text-primary-foreground hover:bg-primary"
+!isSelected && "text-foreground/70 hover:bg-foreground/5 hover:text-foreground"
+
+// Badge "Mới" cạnh nhãn: pill như mọi badge, đảo màu theo tab.
+function getNewBadgeClasses(isSelected: boolean) {
+  return cn(
+    "rounded-full px-2 py-0.5 text-xs font-medium",
+    isSelected && "bg-primary-foreground text-primary",
+    !isSelected && "bg-emerald-500/10 text-emerald-700",
+  );
+}
+```
+
+- Màu tô là `--primary` và `--primary-foreground`, không viết cứng `bg-black text-white`: ở nền tối màu nhấn đảo thành gần trắng.
+- **Chỉ một chỗ tô đặc trên màn.** Trang đã có nút chính tô `--primary` ngay cạnh thì cân nhắc `boxed`, hai khối tô đặc tranh nhau (`M2`).
+- Badge "Mới" là thông tin trạng thái nên dùng màu xanh báo trạng thái (`M4`), trên tab đang chọn thì đảo sang nền `--primary-foreground`. Mỗi hàng tối đa hai badge, nhiều hơn là mất tác dụng.
+- Pill `rounded-full text-xs`, chữ thường "Mới", không in hoa, không `text-[10px]`: chữ hoa 10px thì dấu tiếng Việt dính nhau, và `rounded` 4px là bậc bo thứ năm (`F1`).
+
+### `segmented`: chuyển cách xem, dạng phím nổi
+
+Rãnh **chìm** vào mặt (bóng trong), ô đang chọn **nổi** lên (bóng ngoài rất mờ + viền tóc). Hai lớp bóng ngược chiều mới ra cảm giác 3D, chỉ ô nổi thôi thì trông như dán giấy.
+
+```ts
+// Rãnh: nền nhạt --background, KHÔNG dùng --secondary (đậm quá, ô trắng lọt thỏm).
+// Bo 12px, cách 4px, ô bên trong bo 8px: hai góc đồng tâm (M19).
+"inline-flex w-fit max-w-full gap-1 rounded-xl bg-background p-1 shadow-(--shadow-segment-track)"
+// Ô
+"h-8 rounded-lg px-3 transition-[color,background-color,box-shadow] duration-150"
+isSelected && "bg-surface text-foreground shadow-(--shadow-segment-thumb)"
+!isSelected && "text-foreground/60 hover:text-foreground"
+```
+
+Hai token bóng khai trong `tokens.css`, có bản nền tối riêng:
+
+```css
+:root {
+  --shadow-segment-track: inset 0 0 0 1px rgb(0 0 0 / 0.05), inset 0 1px 2px rgb(0 0 0 / 0.04);
+  --shadow-segment-thumb: 0 0 0 1px rgb(0 0 0 / 0.04), 0 1px 2px rgb(0 0 0 / 0.06), 0 2px 6px -2px rgb(0 0 0 / 0.08);
+}
+.dark {
+  --shadow-segment-track: inset 0 0 0 1px var(--border), inset 0 1px 2px rgb(0 0 0 / 0.4);
+  --shadow-segment-thumb: 0 0 0 1px var(--border-strong), inset 0 1px 0 rgb(255 255 255 / 0.06), 0 1px 2px rgb(0 0 0 / 0.5);
+}
+```
+
+- **Rãnh nhạt, không đậm.** `--background` trên card trắng là vừa đủ thấy rãnh; `--secondary` thì rãnh thành mảng xám nặng, kéo mắt hơn cả nội dung widget.
+- Ô chưa chọn **không có nền hover**, chỉ đổi màu chữ. Nền hover xám trong rãnh xám thì thành ba sắc xám chồng nhau.
+- Bóng ở đây là **ngoại lệ có tên của `M15`**: ô đang chọn là một phím vật lý, bóng nói "đang nhấn nó". Không nhân rộng sang `boxed`, `underline`, `solid`, hay khối khác trong trang.
+- Nền tối: bóng đen khó thấy (`M23`), nên ô nổi lên nhờ viền `--border-strong` và vệt sáng `inset` trên mép trên.
+- Rãnh đặt trên nền trang xám (không nằm trong card) thì đổi rãnh sang `bg-foreground/5`, để rãnh vẫn chìm hơn nền quanh nó.
+
+---
+
+## Badge số đếm
+
+Số việc chưa đọc, số mục trong nhóm, số thành viên. Xuất hiện ở sidebar, ở tab,
+ở tiêu đề cột.
+
+Mặc định là **số trơn, chữ xám**, không khung, không nền. Pill trắng viền mảnh chỉ
+khi người dùng chọn. Năm pill viền cạnh nhau trên một cột là năm khung nhỏ kéo mắt
+(sidebar cũng vậy, `../layouts/app.md`).
+
+```html
+<!-- Mặc định: số trơn. Dòng đang chọn thì số lên text-foreground cùng chữ. -->
+<span class="ml-auto shrink-0 text-xs tabular-nums text-muted">4</span>
+
+<!-- Chỉ khi người dùng chọn: pill trắng, viền mảnh, chữ xám. -->
+<span class="ml-auto shrink-0 rounded-full border border-border-strong bg-surface px-2 py-0.5 text-xs font-medium tabular-nums text-muted">121</span>
+```
+
+- **Một danh sách chỉ MỘT kiểu.** Người dùng chọn pill thì mọi số đều là pill, kể cả số `4`. Đừng chia kiểu theo ý nghĩa con số (chưa đọc thì pill, số đếm thường thì trơn): đặt cạnh nhau thì chỉ thấy hai hàng lệch style, không ai đọc ra được ý nghĩa.
+- **Luôn căn phải**, cách nhãn bằng `ml-auto` hoặc `justify-between`.
+- **Không tô màu brand, không nền đặc.** Badge brand chữ trắng trông nặng và làm màu nhấn loang khắp sidebar. Số đếm là thông tin, không phải hành động (`M2`, `M4`). Dự án muốn badge màu thì để họ tự đổi, skill không tự đề xuất.
+- **Có pill thì nền pill là `--surface` (trắng)**, không phải `--secondary`. Pill trắng vẫn nổi rõ trên hàng đang rê (`--background`) và hàng đang chọn (`--secondary`), còn pill xám thì tan vào hàng.
+- Chỉ tô màu khi con số là **cảnh báo thật**, kiểu số việc quá hạn: chữ hổ phách, vẫn không nền đặc.
+- `tabular-nums` để các hàng thẳng cột nhau.
+- Số lớn thì rút gọn: `99+`, đừng để `1.284` phá bề rộng sidebar.
+
+---
+
+## Phân trang
+
+Nằm ở đáy khung bảng hoặc danh sách, cách thân bảng bằng `border-t border-border`. Một hàng,
+hai cụm: **số đếm bên trái, mọi control bên phải**.
+
+```
+1 tới 10 trong 1.284 đơn hàng          Mỗi trang [10 ▾]   ‹ 1 2 3 4 5 … 129 ›
+```
+
+```tsx
+<div className="flex items-center justify-between gap-4 border-t border-border px-4 py-3">
+  <p className="text-sm tabular-nums text-muted">1 tới 10 trong 1.284 đơn hàng</p>
+  <div className="flex shrink-0 items-center gap-4">
+    {/* "Mỗi trang" + select h-9 */}
+    <nav aria-label="Phân trang" className="flex items-center gap-1">{/* ‹ trang › */}</nav>
+  </div>
+</div>
+```
+
+```ts
+// Nút số trang: vuông h-9, luôn có border để lúc chuyển trang không xô hàng
+"inline-flex h-9 min-w-9 cursor-pointer items-center justify-center rounded-lg border px-2 text-sm font-medium tabular-nums outline-hidden"
+isCurrent && "border-transparent bg-secondary text-foreground"   // + aria-current="page"
+!isCurrent && "border-transparent text-foreground/70 hover:bg-foreground/5 hover:text-foreground"
+// Mũi tên ‹ ›: IconButton h-9 w-9, có aria-label "Trang trước" / "Trang sau"
+```
+
+- **Không bao giờ wrap, không nhảy chỗ.** Nav luôn ở cụm phải, cùng hàng với số đếm, bất kể có bao nhiêu trang. Chật thì **bớt số trang trước**: bỏ `2 3 4 5`, chỉ còn `‹ 1 … 12 … 129 ›`. Màn hẹp dưới `sm` thì chỉ còn `‹ 12 / 129 ›`. Không đẩy nav xuống dòng hai (nhiều trang thì nav rớt xuống căn trái, ít trang lại nằm phải).
+- **Dưới `sm` số đếm chỉ còn tổng**: "32 khách hàng", phần "1 tới 10 trong" bọc `<span class="hidden sm:inline">`. Nav `‹ 1 / 4 ›` đã nói đang ở đâu (`I16` vẫn đủ: tổng số bên trái, vị trí bên phải). Để nguyên câu thì ở 375px nó chỉ còn ~168px cạnh nav, rớt một chữ xuống dòng hai ("1 tới 10 trong 32 khách / hàng"), chân bảng cao gấp đôi.
+- **Trang đang chọn chép đúng class tab `boxed` đang chọn**: nền `--secondary`, viền trong suốt. **Không dùng nền trắng + viền**: đứng cạnh select `10 ▾` thì nó trông y như ô input, người dùng tưởng là ô gõ số trang để nhảy.
+- **Select "Mỗi trang" nằm trong cụm phải, sát nav**, không đứng ngay sau số đếm. Số đếm dài ra theo trang ("1 tới 10" rồi "1.271 tới 1.280"), đặt select sau nó là select xê dịch mỗi lần chuyển trang.
+- **Cửa sổ trang luôn đủ 7 ô** (tính cả `…`) khi tổng số trang lớn hơn 7. Ở gần hai đầu thì lấp thêm số cho đủ 7:
+
+  | Đang xem | Hiện |
+  | --- | --- |
+  | Trang 1 | `1 2 3 4 5 … 129` |
+  | Trang 12 | `1 … 11 12 13 … 129` |
+  | Trang 129 | `1 … 125 126 127 128 129` |
+
+  Số ô cố định thì nav rộng cố định, chuyển trang không kéo select xê dịch. `…` là chữ `text-muted`, không bấm được.
+- **Số ô chọn theo bề rộng khung, một lần cho cả bảng**, không chọn riêng từng trang. Desktop đủ chỗ là 7. Chỉ khi đo thấy tràn mới hạ **cả bộ** xuống 5 (`1 2 3 … 129`, `1 … 12 … 129`, `1 … 127 128 129`), rồi mới tới dạng `‹ 12 / 129 ›`. Khung còn trống mà hiện 5 ô là sai.
+- **Mũi tên ở trang đầu/cuối thì `disabled`**, giữ chỗ, không ẩn, để nav không co giãn.
+- **Chỉ vừa một trang: ẩn nav.** Chỉ còn số đếm ("7 thành viên"). Select "Mỗi trang" chỉ giữ khi tổng số lớn hơn lựa chọn nhỏ nhất, không thì ẩn luôn. Hai mũi tên khoá cộng một ô `1` là nhiễu.
+- **Không có dòng nào: ẩn cả footer.** Empty state của bảng đã nói hết, đừng để "0 khách hàng" cùng bốn control chết bên dưới.
+- Số dùng dấu chấm hàng nghìn (`1.284`) và `tabular-nums`. Chuỗi đếm theo `I16`: "51 tới 75 trong 312 đơn hàng".

package/src/claude/skills/ui-ux/references/components/sortable-header.md

@@ -0,0 +1,86 @@
+# Tiêu đề cột sắp xếp
+
+Ô tiêu đề cột bảng bấm được để sắp xếp dòng. Bảng quanh nó (tab, lọc, chọn nhiều dòng,
+phân trang) xem "Bảng dữ liệu" trong `../layouts/app.md`. Dự án có `@tanstack/react-table`
+thì để nó giữ trạng thái sắp, skill chỉ lo hình ô (`N10`).
+
+## Ba trạng thái
+
+```
+Khách hàng ⇅        Ngày tạo ⇅        ⇅ Doanh thu     chưa sắp: chữ và mũi tên hai chiều text-muted
+Khách hàng ↑        Ngày tạo ⇅        ⇅ Doanh thu     tên A → Z: cột đang sắp chữ và mũi tên text-foreground
+Khách hàng ⇅        Ngày tạo ↓        ⇅ Doanh thu     mới nhất trên cùng
+```
+
+- **Cột nào sắp được cũng có mũi tên, kể cả khi chưa bấm**: `arrow-up-down` → `arrow-up` /
+  `arrow-down`, `size-3.5`, cách chữ `gap-1`. Màn chạm không có hover, thiếu mũi tên thì không
+  biết cột nào bấm được. Cột không sắp được thì không mũi tên, không phải nút.
+- **Cột đang sắp chỉ đổi màu chữ** `text-muted` → `text-foreground`, giữ cỡ và độ đậm
+  (`font-medium`) để hàng tiêu đề không xô (`N1`). Mỗi lúc chỉ một cột đang sắp.
+- **Mũi tên lên là tăng dần** (A → Z, cũ → mới, nhỏ → lớn), xuống là giảm dần.
+- **Cột số căn phải thì mũi tên đứng trước chữ** (`flex-row-reverse`), để chữ chạm mép phải
+  thẳng với con số bên dưới. Mũi tên sau chữ thì chữ thụt vào 18px so với số.
+- **`aria-sort="ascending" | "descending"` chỉ trên `<th>` đang sắp**, cột khác không gắn.
+
+## Bấm thế nào (mặc định cho người nối logic)
+
+Thứ tự vòng bấm là logic, component chỉ gọi `onSort` (`N10`). Khi đề không nói, ghi chú mặc
+định này cạnh handler:
+
+- Bấm lần một: **cột chữ tăng dần** (A → Z), **cột số và ngày giảm dần** (lớn nhất, mới nhất
+  trước: người bấm "Doanh thu" muốn xem ai cao nhất). Đây cũng là mặc định của TanStack Table.
+- Bấm lần hai đảo chiều, **lần ba về chưa sắp** (thứ tự dữ liệu trả về). Không có lần ba thì
+  "chưa sắp xếp" chỉ thấy lúc mới vào trang, không quay lại được.
+- Bấm cột khác: cột cũ về chưa sắp, cột mới bắt đầu lại từ lần một.
+
+## Ô và hover
+
+- **Nút phủ kín ô, padding ngang nằm trong nút**, bằng đúng padding của ô dữ liệu cùng cột:
+  chữ tiêu đề thẳng cột với dữ liệu mà không kéo lề bằng số âm (`N11`). `h-11`, `text-xs
+  font-medium`, `whitespace-nowrap`, `cursor-pointer`.
+- **Không nền hover. Rê vào thì chữ và mũi tên đậm lên** (`hover:text-foreground`). Ngoại lệ
+  của `I10`, cùng lý do với accordion (`accordion.md`). Đừng tô `--surface-hover` lúc rê:
+  nút phủ ô thành một mảng `#f8f8fa` rộng 505px cho một nhãn 12px, và ô cột đầu,
+  cột cuối chạm mép card, sát màu nền trang `#f4f4f6`, card như bị khoét một góc. Quy ước chia đôi:
+  có hệ thiết kế doanh nghiệp tô nền cả ô, có hệ chỉ hiện mũi tên và đậm chữ; skill
+  chọn không nền vì ca ở trên.
+
+```tsx
+<th scope="col" aria-sort={direction ?? undefined} className="p-0">
+  <Button
+    variant="ghost"
+    onClick={onSort}
+    className={cn(
+      "h-11 w-full justify-start gap-1 rounded-none px-4 py-0 text-xs whitespace-nowrap",
+      // Không nền hover: ô cột đầu, cột cuối chạm mép card, --surface-hover sát màu nền trang.
+      "text-muted hover:bg-transparent hover:text-foreground",
+      align === "right" && "flex-row-reverse",
+      isSorted && "text-foreground",
+    )}
+  >
+    {label}
+    <SortIcon direction={direction} />
+  </Button>
+</th>
+```
+
+## Màn hẹp
+
+- **Dưới `sm` bảng quản lý thành danh sách dòng** (`../layouts/app.md`), hàng tiêu đề mất theo,
+  nên **sắp xếp chuyển thành một nút dropdown** cạnh nút Lọc: nút viền `h-10`, nhãn
+  "Sắp xếp:" `text-muted` rồi lựa chọn đang dùng ("Sắp xếp: Doanh thu cao nhất"), `ChevronDown`,
+  `w-fit`, cùng khuôn nút "Trạng thái:" của bảng. Mở ra là danh sách mỗi mục một **cột + chiều
+  nói bằng chữ**: "Tên A → Z", "Tên Z → A", "Mới nhất", "Cũ nhất", "Doanh thu cao nhất", "Doanh
+  thu thấp nhất", cộng "Mặc định" cho chưa sắp; mục đang chọn có dấu check (khuôn Select ở
+  `choice-controls.md`). Chữ thay mũi tên vì không còn tên cột đứng cạnh để mũi tên bám vào.
+- **Bảng vẫn giữ dạng bảng ở màn hẹp thì mọi cột sắp được phải thấy mà không cuộn.** Bảng
+  ba cột `min-w-[28rem]` cuộn ngang trong khung 341px thì cột Doanh thu nằm hẳn ngoài khung:
+  sắp "Doanh thu tăng dần" ở 375px mà không thấy cột doanh thu nào.
+  Không vừa thì theo gạch trên, đừng để tiêu đề sắp xếp trôi khỏi màn.
+
+## Kiểm
+
+- Rê lên tiêu đề cột đầu và cột cuối ở 1280px: có mảng nền nào chạm mép card không?
+- Mép trái chữ tiêu đề bằng mép trái chữ dữ liệu cột đó; cột số: mép phải chữ tiêu đề bằng mép
+  phải con số (đo bằng `Range`).
+- Ở 375px: còn thấy tiêu đề (hoặc nút "Sắp xếp:") cho từng cột sắp được không?

package/src/claude/skills/ui-ux/references/components/tag-input.md

@@ -0,0 +1,14 @@
+# Ô nhập nhiều tag (tag input)
+
+Gõ một giá trị rồi Enter thành một thẻ: email người nhận, nhãn, người được gán.
+Ô theo `input.md`, thẻ là pill như badge (`M7`, `F1`), câu lỗi theo
+`layouts/form.md`.
+
+- **Enter và dấu phẩy đều thành thẻ.** Dán cả danh sách thì tách theo dấu phẩy. Backspace lúc **chưa gõ chữ nào** thì bỏ thẻ cuối.
+- **Giá trị sai khuôn vẫn được thêm thành thẻ**, không chặn lúc gõ. Dán 30 email mà chặn ngay thì người dùng mất dòng và không biết mất dòng nào. Thẻ sai đổi sang tông đỏ kèm icon, sửa bằng cách bỏ thẻ rồi gõ lại.
+- **Lỗi ở thẻ nào thì đỏ ở thẻ đó, viền ô giữ nguyên.** Chỉ lỗi của **cả ô** (chưa thêm được ai) mới viền đỏ cả ô như mọi ô nhập khác. Hai phạm vi lỗi, hai cách hiện, không lẫn (`N3`).
+- **Câu lỗi nói đúng thứ code đang kiểm**, không bịa thêm luật (`N6`): hàm kiểm "có `@` và tên miền có dấu chấm" thì câu phải là "cần có dấu @ và tên miền", **không** phải "phải có đuôi .com" — `@saoviet.vn` là hợp lệ.
+- **Giá trị dài xuống dòng trong thẻ** (`wrap-anywhere`), không `truncate`, không tooltip: email là thứ người dùng phải đọc đủ mới biết gửi đúng ai (`N8`). Thẻ hết chỗ thì xuống dòng và ô cao theo.
+- **Nút bỏ trên mỗi thẻ có `aria-label` kèm giá trị** ("Bỏ ngoc.tran@saoviet.vn"), không chỉ "Bỏ".
+- **Placeholder là câu hướng dẫn** (`T25`: "Nhập email người nhận"), không dùng ví dụ giả `ten@congty.com`. Dòng gợi ý dưới ô nói cách thêm ("Gõ xong bấm Enter để thêm người nhận") — đây là thứ người dùng chưa biết trước khi gõ, không phải chữ thừa (`T20`).
+- **Khoá**: ô chìm xuống nền trang, **thẻ giữ nguyên màu để còn đọc được**, chỉ nút bỏ tắt, và nói lý do ngay dưới ("Chỉ người tạo chiến dịch sửa được danh sách này") (`N6`).

package/src/claude/skills/ui-ux/references/components/timeline.md

@@ -0,0 +1,38 @@
+# Dòng thời gian hoạt động (timeline)
+
+Lịch sử của một đối tượng: đơn hàng, hồ sơ, ticket. Nằm trong card (`card.md`).
+**Không dùng cho "Hoạt động gần đây" của cả workspace** (nhiều người, nhiều dự án):
+ở đó câu hỏi là ai vừa đụng gì, khuôn là avatar + một câu, xem `layouts/app.md`
+mục Dashboard.
+Vòng và đường nối mượn thanh các bước (`layouts/form.md`), chữ mượn dòng danh
+sách (`list-row.md`). Mượn là chép class, không chỉ chép dáng (`N5`).
+
+```html
+<ol class="text-sm">
+  <!-- MỚI NHẤT Ở TRÊN. Hàng cuối (cũ nhất) không có đường nối -->
+  <li class="relative flex gap-3 pb-6 last:pb-0">
+    <span class="absolute top-10 bottom-1 left-[15px] w-0.5 bg-border" aria-hidden="true"></span>
+    <span class="grid size-8 shrink-0 place-items-center rounded-full bg-red-50 text-red-600">
+      <!-- icon lucide size-4, riêng cho từng loại việc -->
+    </span>
+    <div class="min-w-0 flex-1 pt-1.5"><!-- dòng đầu 20px nằm giữa vòng 32px -->
+      <div class="flex flex-col gap-0.5 sm:flex-row sm:items-baseline sm:justify-between sm:gap-4">
+        <p class="font-medium text-foreground">Giao hàng thất bại</p>
+        <time class="shrink-0 text-xs whitespace-nowrap text-muted tabular-nums">11:47 · 19/09</time>
+      </div>
+      <p class="mt-1 max-w-[55ch] text-pretty text-muted">Shipper gọi 3 lần không liên lạc được người nhận…</p>
+      <p class="mt-1 text-xs text-muted">Lê Văn Phúc · Vận chuyển Sao Việt</p>
+    </div>
+  </li>
+</ol>
+```
+
+- **Mới nhất ở trên.** Người mở lịch sử muốn biết "giờ đang thế nào"; để cũ trên thì với lịch sử dài, việc vừa thất bại nằm tận đáy phải cuộn mới thấy. Người dùng muốn đọc xuôi thì đảo mảng, component không tự sắp xếp.
+- **Vòng `size-8`, icon `size-4`, màu lấy từ bảng badge trạng thái** (`M7`, `N4`): việc thường `bg-zinc-100 text-zinc-600`, thất bại `bg-red-50 text-red-600`, xong hẳn `bg-emerald-50 text-emerald-700`. **Việc lặp lại thường ngày thì xám, kể cả khi nó là "xong"**: trong lịch sử khách hàng, mỗi đơn giao xong là việc bình thường, tô xanh cả 24 đơn thành một cột vòng xanh, mất tác dụng báo hiệu (`N3`). Xanh chỉ cho mốc kết thúc của chính đối tượng (đơn hàng đã giao trong lịch sử của đơn đó). Chỉ tô vòng; **nhãn luôn `text-foreground`**, kể cả việc thất bại (`N3`). Icon riêng cho từng loại việc, màu không đứng một mình.
+- **Dòng đầu nằm giữa tâm vòng**: khối chữ `pt-1.5` (vòng 32px, dòng `text-sm` 20px). Không có thì nhãn bám mép trên vòng, lệch so với thanh các bước.
+- **Hai cỡ chữ**: nhãn và mô tả `text-sm`, giờ và người làm `text-xs`. Không `text-base`.
+- Mô tả `max-w-[55ch] text-pretty` (`T10`, `T11`): card rộng thì câu dài vẫn không chạy quá 75 ký tự và không chui xuống dưới cột giờ. Không `max-w-prose` (65ch ≈ 90 ký tự chữ Việt), lý do ở `T11`.
+- Giờ `tabular-nums whitespace-nowrap` (`T16`), bám mép phải từ `sm`, màn hẹp xuống dưới nhãn. Mã vận đơn, mã đơn trong mô tả bọc `font-mono` (`T17`).
+- Đường nối `w-0.5 bg-border`, cùng độ dày với thanh các bước (`N5`); `w-px` mờ gần như mất trên nền trắng. Hở một khoảng trên dưới, không chạm vòng. Chỉ một việc thì không có đường nối.
+- **Lịch sử dài thì hiện khoảng 10 việc gần nhất, cuối danh sách là nút `ghost` "Xem hoạt động cũ hơn"** (`I7`, không icon), **chữ** trên nút thẳng cột với chữ của các hàng: `ml-8` (vòng 32px + `gap-3` = 44px, trừ `px-3` của nút ghost). Bấm thì nối thêm 10 việc ngay bên dưới, không phân trang, không mở trang khác; đang tải thì spinner đè giữa nút (`button.md`). Hết việc thì bỏ nút: hàng cũ nhất ("Tạo khách hàng", "Tạo đơn") tự là điểm kết. Không dựng cả trăm hàng một lượt, và không cắt cụt ở 5 hàng rồi nhảy thẳng về mốc tạo: người đọc thấy ô số ghi 24 đơn mà lịch sử có một đơn.
+- Hàng không bấm được thì không hover. Bấm được (mở chi tiết) thì theo hover của `list-row.md`.

package/src/claude/skills/ui-ux/references/components/tree.md

@@ -0,0 +1,30 @@
+# Cây thư mục (tree)
+
+Danh sách lồng nhau mở đóng được: thư mục tài liệu, cây trang, cây danh mục.
+Mượn khuôn **menu con của sidebar** (`layouts/app.md`): cùng chiều cao hàng, cùng
+nền hover, cùng đường dọc, cùng cách báo mục đang chọn (`N5`).
+
+```html
+<ul class="space-y-0.5 text-sm"><!-- 2px giữa các hàng, xem list-row.md -->
+  <li>
+    <button type="button" class="flex h-10 w-full cursor-pointer items-center gap-2 rounded-xl px-2 outline-hidden hover:bg-item-hover" aria-expanded="true">
+      <!-- h-10 rounded-xl: cao bằng link sidebar, bo theo F1. ChevronDown size-4 text-muted, xoay -rotate-90 khi đóng. Hàng file: một ô size-4 trống giữ chỗ.
+         Hàng đang chọn: bỏ hover, thêm bg-secondary font-medium, aria-current="page" -->
+      <!-- FolderOpen / Folder / FileText size-4 shrink-0 -->
+      <span class="min-w-0 truncate">Khách hàng doanh nghiệp</span>
+    </button>
+    <ul class="ml-4 space-y-0.5 border-l border-border-strong pl-2"><!-- đường dọc chạy ở tâm icon cha -->
+      …
+    </ul>
+  </li>
+</ul>
+```
+
+- **Hàng đang chọn**: nền `bg-secondary` + `font-medium` + **đoạn đường dọc của nó đậm lên `--foreground`**, y như menu con của sidebar. Không tô màu nhấn, không viền. Đoạn đậm là `before:absolute before:inset-y-0 before:w-px before:bg-foreground` trên hàng, lùi sang trái đúng `pl` của danh sách cộng 1px viền (`before:-left-[9px]` với `pl-2`); số âm giữ có chủ ý (`N11` bước 4), comment ngay trên dòng. Cách không âm là mỗi `<li>` tự `border-l` và đoạn đang chọn đổi màu viền, nhưng khe `space-y-0.5` giữa các hàng làm đường dọc đứt từng quãng 2px, còn đổi khe sang `pt-0.5` thì đoạn đậm dài hơn nền hàng 2px.
+- **Rê `hover:bg-item-hover`, đang chọn đậm hơn một bậc `bg-secondary`**, như link sidebar (`I10`; chủ dự án chốt). Cây không có checkbox, nền là dấu chọn duy nhất: rê ra đúng nền đang chọn thì rê qua hàng nào cũng trông như vừa chọn nó. "Rê và đã chọn cùng một nền mờ" chỉ còn cho dòng bảng tick checkbox. Hai hàng cạnh nhau cùng sáng nền (một đang chọn, một đang rê) vẫn xảy ra, nên danh sách **phải có `space-y-0.5`**, nếu không hai hàng dính thành một khối.
+- **Chevron chỉ ở hàng mở được.** Hàng file vẫn chừa đúng một ô `size-4` để chữ thẳng cột với hàng thư mục. Icon thư mục đổi theo trạng thái: `FolderOpen` khi mở, `Folder` khi đóng. Icon file lấy theo đuôi từ **bảng chung trong `file-upload.md`** (cùng dáng tờ giấy, một màu).
+- **Thư mục rỗng có một hàng chữ xám "Thư mục trống"**, `text-muted`, **thẳng mép chữ của hàng con cùng cấp** — không thụt ít hơn, không có icon. Không có hàng này thì mở thư mục ra chẳng thấy gì đổi, người dùng tưởng bấm hụt (`N2`).
+- **Tên dài cắt giữa, giữ vài ký tự cuối của tên cộng đuôi file** ("bao-cao…quy-3.xlsx", không "bao-cao-doanh….xlsx" bốn chấm), dấu `…` dính liền (`T14`). Tooltip tên đầy đủ **chỉ gắn khi tên thật sự bị cắt** (so `scrollWidth` với `clientWidth`) và không che hàng kế (`N8`). **Tooltip tên dài được xuống dòng, không `whitespace-nowrap`**: `max-w-[min(20rem,calc(100vw-1rem))] whitespace-normal wrap-anywhere`, và `side="right"` hết chỗ thì lật xuống dưới hàng. Tooltip `nowrap` với tên 90 ký tự ở 375px rộng 765px, tràn khỏi màn gần 400px, cắt mất đúng nửa tên nó sinh ra để hiện.
+- **Mỗi tầng thụt `ml-4`**, đường dọc `border-l border-border-strong` chạy ở tâm icon của hàng cha. Cột hẹp cỡ sidebar (288px) vẫn phải lồng được bốn tầng; sâu hơn thì thụt ít lại chứ không cho cuộn ngang (`R1`).
+- **Mở/đóng trượt bằng `grid-rows` 0fr ↔ 1fr**, phần đang đóng gắn `inert`; không render có điều kiện, không `hidden`, không `<details>` (`I30`, mẫu ở `accordion.md`).
+- Bàn phím (`N9`): mặc định là **nút mở đóng thường** — cả cây là `<ul>` lồng, hàng mở đóng là `<button aria-expanded>`, đi bằng Tab, Enter/Space mở đóng. Muốn điều hướng bằng mũi tên thì phải dựng **đủ mẫu tree của WAI-ARIA** (`role="tree"`, `treeitem`, `group`, `aria-level`, `aria-selected`, roving tabindex), đừng gắn phím mũi tên lên nút thường: trình đọc màn hình không báo mô hình đó.