@haposoft/cafekit 0.16.6 → 0.18.0

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

@@ -0,0 +1,246 @@
+# Accordion
+
+Danh sách mục mở/đóng tại chỗ: FAQ, "xem chi tiết" theo từng mục. Mỗi mục là một
+**nút tiêu đề** rộng hết hàng, bấm thì **nội dung** trượt ra ngay dưới.
+
+Nhóm ô tuỳ chọn thu gọn **trong form** ("Cài đặt nâng cao") không dùng khung accordion
+này: xem "Khu thu gọn trong form" ở cuối file.
+
+Khi nào dùng: danh sách dài hơn 6 mục, hoặc mỗi nội dung dài quá 3 dòng; dưới ngưỡng
+đó thì hiện hết (`I17`). Ngoại lệ: FAQ trang giá luôn accordion (`../layouts/pricing.md`).
+Mọi thứ mở/đóng dựng theo đúng công thức ở đây, không dùng `<details>` (`I30`).
+
+---
+
+## Mẫu
+
+Mỗi mục là một component con giữ `isOpen` riêng, nên mở nhiều mục cùng lúc được.
+
+```tsx
+// accordion-item.tsx
+interface AccordionItemProps {
+  title: string;
+  children: ReactNode;
+}
+
+export default function AccordionItem({ title, children }: AccordionItemProps) {
+  const [isOpen, setIsOpen] = useState(false);
+  const panelId = useId();
+
+  return (
+    <div>
+      <h3>
+        <button
+          type="button"
+          aria-expanded={isOpen}
+          aria-controls={panelId}
+          onClick={() => setIsOpen(!isOpen)}
+          // py-4 CỐ ĐỊNH ở cả hai trạng thái: chữ luôn cách đều hai mép nút.
+          className="group flex w-full cursor-pointer items-center justify-between gap-4 px-5 py-4 text-left text-pretty text-sm font-medium text-foreground outline-hidden"
+        >
+          {title}
+          <ChevronDown
+            className={cn(
+              "size-4 shrink-0 text-muted transition-[rotate,color] duration-200 group-hover:text-foreground motion-reduce:transition-none",
+              isOpen && "rotate-180",
+            )}
+            aria-hidden
+          />
+        </button>
+      </h3>
+
+      <div
+        id={panelId}
+        inert={!isOpen}
+        className={cn(
+          "grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none",
+          isOpen && "grid-rows-[1fr]",
+          !isOpen && "grid-rows-[0fr]",
+        )}
+      >
+        <div className="min-h-0 overflow-hidden">
+          {/* px-5 bằng đúng nút ở trên, không max-w, không pr riêng: lấp kín bề ngang. */}
+          <div className="px-5 pb-4 text-pretty text-sm/6 text-muted">{children}</div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Khung: MỘT khung trắng, các mục chia bằng divide-y.
+<div className="divide-y divide-border overflow-hidden rounded-2xl border border-border bg-surface">
+  {items.map((item) => (
+    <AccordionItem key={item.id} title={item.title}>{item.body}</AccordionItem>
+  ))}
+</div>
+```
+
+`<button>` thuần cho gọn ví dụ. Dự án có `Button` dùng chung thì dùng nó, miễn giữ được
+dòng tràn hết bề ngang, `rounded-none`, và **tắt nền hover của variant** (`ghost` có
+`hover:bg-foreground/5`): thêm `hover:bg-transparent`.
+
+---
+
+## Luật
+
+**Chuyển động**
+- **Trượt bằng `grid-rows` 0fr ↔ 1fr, `duration-200 ease-out`**, chevron xoay cùng nhịp.
+  Không `<details>`, không render có điều kiện, không `hidden`: đều mở đóng tức thì, bấm là
+  giật (`I30`). Không đo chiều cao bằng JS.
+- **Mục đóng gắn `inert`**: Tab không lọt vào nội dung đã ẩn, trình đọc màn hình không đọc.
+- **`motion-reduce:transition-none`** trên cả khối trượt và chevron.
+
+**Padding: mỗi khối tự đứng được**
+- **Nút tiêu đề `px-5 py-4`, cố định ở cả lúc mở và đóng.** Đừng bớt `pb` khi mở để kéo
+  nội dung lại gần: tô nền nút thì chữ cách mép trên 17px, mép dưới 7px.
+- **Nội dung `px-5 pb-4`, không `pt`**: nối tiếp padding dưới của nút. Đo:
+  mép trên → tiêu đề 17px, tiêu đề → nội dung 20px, nội dung → mép dưới 20px. Đừng để
+  nội dung `py-3` (tô màu khối nào cũng đều, nhưng nội dung cách tiêu đề 32px mà cách vạch
+  dưới 16px, trông thuộc về vạch dưới); chủ dự án chọn nối tiếp.
+- **Nội dung cùng `px` với nút, không `pr` riêng, không `max-w`.** `pr-12` (để chữ không
+  chạy dưới chevron) làm lề phải 48px mà lề trái 20px; `max-w-[65ch]` làm khối nội dung
+  hụt 55px so với khối bọc. Bề rộng đặt ở **khung ngoài**.
+- **Khung đủ rộng để tiêu đề dài nhất vừa một dòng ở desktop.** Đừng thu khung cho nội dung
+  ≤ 75 ký tự: nội dung 1–2 câu đọc một hơi, không tính `T11`; khung hẹp làm tiêu đề xuống
+  dòng khi hàng còn trống. Nội dung dài từ 3 dòng trở
+  lên mới xét `T11`, và khi đó thường là nên rút nội dung.
+- **Không số âm** để kéo nội dung lên (`N11`): margin âm trên khối con `overflow-hidden`
+  làm mục đang đóng lòi dòng đầu nội dung ra.
+
+**Hover và focus**
+- **Không nền hover. Rê vào thì chevron đậm lên** (`group-hover:text-foreground`) cộng
+  con trỏ bàn tay. Ngoại lệ của `I10`. Đừng dùng:
+  - nền `--surface-hover` (`#f8f8fa`) trên nút: gần màu nền trang `#f4f4f6` ngay ngoài mép
+    khung, hàng như bị khoét; mục đang mở thì nửa trên xám nửa dưới trắng;
+  - nền phủ cả mục (`has-[]`): vẫn là mảng gần màu nền trang chạm mép khung;
+  - hàng thụt vào có bo góc: một ô xám gần màu nền trang nằm trong card, như lỗ khoét.
+
+**Khung và chữ**
+- **Một khung trắng, `divide-y divide-border`** (`M13`). Không để vạch kẻ thẳng trên nền
+  trang xám: không khung thì vạch đọc ra như đường ngăn trang lơ lửng.
+- **Tiêu đề mục `text-sm font-medium`, `text-pretty`**, không `text-balance` dù là `h3`: nó
+  chung hàng với chevron, `balance` làm câu xuống dòng khi mới được nửa hàng (`T10`).
+- **Nội dung `text-sm/6 text-muted`.**
+- **Đóng hết lúc vào trang**, trừ khi đề nói mở sẵn mục nào.
+
+---
+
+## Khu thu gọn trong form
+
+"Cài đặt nâng cao", "Tuỳ chọn khác": một nhóm ô mà đa số người dùng bỏ qua, nằm giữa
+các ô của form. Dựng thành **một dòng chữ có chevron liền sau**, không khung, bấm thì các
+ô trượt ra **thẳng cột và rộng bằng các ô khác của form**. Đây là cách hầu hết app làm với
+tuỳ chọn phụ trong form tạo mới.
+
+Cùng cơ chế trượt, `inert`, chevron với accordion ở trên; khác ở chỗ không khung, nút
+không `px`, và khối cắt chỉ cắt dọc.
+
+```tsx
+// form-disclosure.tsx
+interface FormDisclosureProps {
+  title: string;
+  // Cha giữ trạng thái: bấm gửi mà ô bên trong bị sai thì cha phải tự mở khu ra.
+  isOpen: boolean;
+  onOpenChange: (isOpen: boolean) => void;
+  children: ReactNode;
+}
+
+export default function FormDisclosure({ title, isOpen, onOpenChange, children }: FormDisclosureProps) {
+  const panelId = useId();
+
+  return (
+    <div>
+      {/* h2 khi form nằm ngay dưới h1 của trang. */}
+      <h2>
+        <Button
+          type="button"
+          variant="ghost"
+          aria-expanded={isOpen}
+          aria-controls={panelId}
+          onClick={() => onOpenChange(!isOpen)}
+          // px-0: chữ thẳng mép trái với nhãn các ô. w-fit: vùng bấm là chữ + chevron,
+          // không phải cả hàng. Không nền hover, rê vào thì chevron đậm lên như accordion.
+          className="group h-11 w-fit gap-1.5 rounded-md px-0 py-0 text-sm font-medium text-foreground hover:bg-transparent md:h-10"
+        >
+          {title}
+          <ChevronDown
+            className={cn(
+              "size-4 shrink-0 text-muted transition-[rotate,color] duration-200 group-hover:text-foreground motion-reduce:transition-none",
+              isOpen && "rotate-180",
+            )}
+            aria-hidden
+          />
+        </Button>
+      </h2>
+
+      <div
+        id={panelId}
+        inert={!isOpen}
+        className={cn(
+          "grid transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none",
+          isOpen && "grid-rows-[1fr]",
+          !isOpen && "grid-rows-[0fr]",
+        )}
+      >
+        {/* overflow-y-clip, KHÔNG overflow-hidden: chỉ cắt dọc cho lúc trượt. Ô nhập rộng
+            bằng khối này, overflow-hidden cắt mất quầng focus 2px ở hai bên ô. */}
+        <div className="min-h-0 overflow-y-clip">
+          {/* pt-2.5 cộng khoảng dưới chữ của nút = 20px, bằng gap giữa các ô. */}
+          <div className="flex flex-col gap-5 pt-2.5">{children}</div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+Ô sai nằm trong khu đang đóng: bấm gửi thì mở khu rồi đưa con trỏ vào ô đó.
+
+```tsx
+// Khu đang đóng mang inert, focus() vào ô bên trong không ăn: gỡ inert ngay trong lượt này.
+flushSync(() => setIsAdvancedOpen(true));
+
+// Focus ngay nhưng chưa cuộn: khu còn đang trượt, scrollIntoView lúc này cuộn lệch.
+// Trượt xong (200ms) mới cuộn ô vào giữa màn.
+document.getElementById(fieldId)?.focus({ preventScroll: true });
+window.setTimeout(() => focusFieldById(fieldId), accordionDurationMs);
+```
+
+**Luật**
+- **Không khung, không vạch kẻ trên dưới khu.** Dựng
+  bằng khung accordion (viền `--border`, `rounded-xl`) lồng trong card form trắng thì
+  - lúc đóng, hàng có viền bo góc, rộng bằng ô nhập, chevron ở mép phải: nhìn y một ô
+    select tên "Cài đặt nâng cao";
+  - ô bên trong thụt 21px, hẹp hơn ô phía trên 42px: form
+    có hai mép trái;
+  - mở ra thì đáy khung và vạch trên hàng nút là hai đường kẻ cách nhau 24px;
+- **Chevron liền sau chữ (`gap-1.5`)**, không đẩy ra mép phải. Chevron ở mép phải của một
+  hàng rộng bằng ô nhập là dấu hiệu của select.
+- **Các ô bên trong như mọi ô khác của form**: cùng mép trái, cùng bề rộng, cùng `gap-5`.
+  Đo lại bằng `getBoundingClientRect`: nhãn ô đầu trong khu và nhãn ô phía trên cùng `left`.
+- **`overflow-y-clip` trên khối cắt.** Ở 375 và 1280px: quầng focus đủ bốn
+  phía, giữa lúc trượt không lòi chữ, không cuộn ngang. Ô cuối khu là ô nhập không có
+  dòng gợi ý thì thêm `pb-1` vào khối nội dung cho quầng dưới.
+- **Khoảng cách tự ra từ `h-10` của nút**: gợi ý của ô trên → tiêu đề 32px, tiêu đề → nhãn
+  ô đầu 22px. Tiêu đề gần nhóm của nó hơn, không cần kẻ thêm.
+- **Chỉ giấu thứ có mặc định dùng được.** Lựa chọn quyết định ai thấy dữ liệu (riêng tư /
+  công khai) thì đưa ra ngoài khu: hầu hết app để nó ngay trên form tạo, người tạo phải thấy
+  nó trước khi bấm. Khu này không tính theo ngưỡng `I17`: nó giấu để đường chính ngắn, không
+  phải vì dài.
+- **Đóng lúc vào trang.** Bấm gửi mà ô trong khu sai thì mở ra như mẫu trên.
+
+---
+
+## Kiểm
+
+- Tô nền đặc khác nhau cho nút, khối bọc nội dung, nội dung, ở lúc đóng, mở và hover
+  (`REVIEW.md` bước 4): chữ cách đều các mép trong từng khối, nội dung lấp kín khối bọc,
+  không lòi màu khối bọc.
+- Đo bằng `Range` trên chữ: mép trên → tiêu đề ≈ 17px, tiêu đề → nội dung ≈ 20px, nội dung
+  → mép dưới ≈ 20px. Mục đóng giữ nguyên chiều cao khi mục khác mở.
+- Chụp giữa lúc đang trượt (~90ms sau khi bấm): không lòi chữ ở mục đang đóng.
+- Tab qua các nút; Enter và Space mở đóng; Tab không vào nội dung của mục đóng.
+- Ở 375px, tiêu đề dài không xuống dòng khi mới được nửa hàng.
+- Khu thu gọn trong form: lúc đóng có trông như ô select không; mở ra thì nhãn và ô bên trong
+  có cùng `left` và bề rộng với ô phía trên không; focus ô nhập trong khu, chụp cận mép trái
+  mép phải xem quầng có bị cắt không; bấm gửi khi ô trong khu sai và khu đang đóng.

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

@@ -0,0 +1,153 @@
+# Avatar
+
+**Dự án đã có component avatar thì dùng của họ** (luật câu 2, mục 0). File này chỉ
+dùng khi grep ra rỗng.
+
+---
+
+## Không có ảnh thì là chữ cái đầu trên nền pastel
+
+Nền màu nhạt, chữ **cùng sắc** nhưng đậm hơn. Không phải chữ trắng trên nền đặc —
+nền đặc năm sáu màu cạnh nhau trong một danh sách là thành bảng màu cầu vồng.
+
+```
+  ╭───╮ ╭───╮ ╭───╮ ╭───╮
+  │ A │ │ H │ │ B │ │ L │     nền pastel, chữ cùng sắc đậm hơn,
+  ╰───╯ ╰───╯ ╰───╯ ╰───╯     viền mảnh cùng sắc
+```
+
+```tsx
+interface AvatarTone {
+  background: string;
+  text: string;
+  ring: string;
+}
+
+const avatarTones: AvatarTone[] = [
+  { background: "bg-emerald-50 dark:bg-emerald-500/15", text: "text-emerald-700 dark:text-emerald-300", ring: "ring-emerald-200 dark:ring-emerald-500/30" },
+  { background: "bg-sky-50 dark:bg-sky-500/15", text: "text-sky-700 dark:text-sky-300", ring: "ring-sky-200 dark:ring-sky-500/30" },
+  { background: "bg-indigo-50 dark:bg-indigo-500/15", text: "text-indigo-700 dark:text-indigo-300", ring: "ring-indigo-200 dark:ring-indigo-500/30" },
+  { background: "bg-pink-50 dark:bg-pink-500/15", text: "text-pink-700 dark:text-pink-300", ring: "ring-pink-200 dark:ring-pink-500/30" },
+  { background: "bg-amber-50 dark:bg-amber-500/15", text: "text-amber-700 dark:text-orange-400", ring: "ring-amber-200 dark:ring-amber-500/30" },
+  { background: "bg-violet-50 dark:bg-violet-500/15", text: "text-violet-700 dark:text-violet-300", ring: "ring-violet-200 dark:ring-violet-500/30" },
+];
+
+// Cùng một người thì luôn ra cùng một màu, ở mọi màn, mọi lần tải lại.
+function getAvatarTone(seed: string): AvatarTone {
+  let hash = 0;
+  for (let i = 0; i < seed.length; i++) {
+    hash = (hash * 31 + seed.charCodeAt(i)) | 0;
+  }
+
+  return avatarTones[Math.abs(hash) % avatarTones.length];
+}
+
+// "Trần Nguyễn Anh Tuấn" -> "T"; tên một chữ -> chữ đó
+function getInitial(name: string): string {
+  return name.trim().charAt(0).toLocaleUpperCase("vi");
+}
+```
+
+```tsx
+// Seed là id (hoặc email), KHÔNG phải tên hiển thị — xem "Vì sao ổn" bên dưới
+const tone = getAvatarTone(user.id);
+
+<span
+  className={cn(
+    "inline-flex size-10 shrink-0 items-center justify-center rounded-full",
+    "text-sm font-semibold ring-1",
+    tone.background,
+    tone.text,
+    tone.ring,
+  )}
+  aria-hidden
+>
+  {getInitial(name)}
+</span>
+```
+
+**Không dùng Tailwind** thì thay class bằng mã dưới đây. Đây chính là các class
+trên của Tailwind v4 đổi ra hex, nên hai kiểu dự án ra cùng một màu. Màu avatar là
+màu nhận diện, không mang nghĩa, nên không vào `tokens.css`: đặt thẳng trong mảng.
+
+| Sắc | Nền `-50` | Chữ `-700` | Viền `-200` | Tương phản chữ/nền |
+| --- | --- | --- | --- | --- |
+| emerald | `#ecfdf5` | `#007a55` | `#a4f4cf` | 5.1:1 |
+| sky | `#f0f9ff` | `#0069a8` | `#b8e6fe` | 5.5:1 |
+| indigo | `#eef2ff` | `#432dd7` | `#c6d2ff` | 7.2:1 |
+| pink | `#fdf2f8` | `#c6005c` | `#fccee8` | 5.4:1 |
+| amber | `#fffbeb` | `#bb4d00` | `#fee685` | 4.9:1 |
+| violet | `#f5f3ff` | `#7008e7` | `#ddd6ff` | 6.7:1 |
+
+**Nền tối** (`M32`): nền `-50` sang tối là sáu đốm trắng giữa màn đen. Nền là sắc `-500`
+phủ 15%, chữ `-300`, viền sắc `-500` phủ 30%; class `dark:` đã nằm sẵn trong mảng trên. Riêng amber chữ
+**`orange-400`**: `amber-300` trôi sang vàng 35° so với `amber-700` của bản sáng (`M7`, "Bản tối chọn theo sắc").
+Không Tailwind thì chữ: emerald `#5ee9b5`, sky `#74d4ff`, indigo `#a3b3ff`, pink `#fda5d5`,
+amber `#ff8904` (orange-400), violet `#c4b4ff`; nền và viền là `color-mix(in srgb, <mã -500> 15%, transparent)`
+và `30%` với emerald `#00bc7d`, sky `#00a6f4`, indigo `#615fff`, pink `#f6339a`, amber `#fe9a00`,
+violet `#8e51ff`.
+
+```ts
+const avatarTones: AvatarTone[] = [
+  { background: "#ecfdf5", text: "#007a55", ring: "#a4f4cf" },
+  // ... năm sắc còn lại theo bảng, giữ đúng thứ tự để cùng id ra cùng màu
+];
+// style={{ background: tone.background, color: tone.text, boxShadow: `0 0 0 1px ${tone.ring}` }}
+```
+
+**Vì sao ổn**
+
+- **Màu lấy theo `id` hoặc email, không theo tên.** Hai người trùng tên vẫn khác màu, và đổi tên hiển thị thì màu không nhảy. Lấy ngẫu nhiên lúc render thì mỗi lần tải lại là một màu khác — người dùng nhận ra nhau bằng màu, màu nhảy là mất.
+- **Cùng một người thì mọi chỗ cùng màu, trên cùng một màn cũng vậy.** Avatar ở header, chân sidebar, trang hồ sơ, danh sách thành viên gọi chung một component với cùng seed. Chỗ hay lệch là avatar cỡ to trên trang hồ sơ được dựng riêng: header nền chàm mà trang hồ sơ nền hổ phách, cùng chữ "T".
+- **Chữ cái theo tên đã lưu, không theo ô đang sửa, và không bao giờ là "?".** Tên rỗng (tài khoản mới, chưa đặt tên) thì lấy chữ đầu email.
+- **Sáu sắc, cố định.** Đủ để một danh sách mười người trông khác nhau, ít đủ để không thành cầu vồng. Đừng sinh màu từ hash ra HSL tự do — sẽ ra những sắc bùn xỉn không ai chọn. Màu nhận diện của dự án, board, danh mục (`M34`) dùng chung đúng sáu sắc này.
+- **Không có `red`, không có `rose`.** Hai sắc đó đã có nghĩa trong app: lỗi và hành động nguy hiểm (`M30`). Avatar một người mà đỏ thì trông như tài khoản đó đang có vấn đề. Hồng thì dùng `pink`.
+- **Nền `-50`, chữ `-700`, viền `-200`**: cả ba cùng một sắc. Chữ `-700` trên nền `-50` đạt tương phản đọc được ở cỡ `text-sm`.
+- **`aria-hidden`** — tên người dùng đã hiện ngay cạnh avatar. Trình đọc màn hình đọc "T" trước tên là thừa.
+- Viền dùng `ring-1`, không `border` — xem `M17` và `card.md`: thứ có kích thước cố định thì dùng ring để viền không ăn vào kích thước.
+
+---
+
+## Một chữ hay hai chữ
+
+**Một chữ.** Tên tiếng Việt lấy hai chữ đầu thì ra "TN" cho "Trần Nguyễn…" —
+hai chữ **họ**, không ai nhận ra ai. Lấy chữ đầu tên gọi ("Tuấn" → "T") thì đúng
+hơn, nhưng tách được tên gọi khỏi họ đệm trong mọi trường hợp là không làm được.
+
+Một chữ cái đầu của chuỗi tên thì luôn đúng, luôn đoán được, và màu nền đã lo
+phần phân biệt.
+
+Dự án đã quen hai chữ (đang dùng khắp nơi) thì theo dự án, đừng đổi.
+
+App tiếng Anh thì ngược lại: hai chữ, đầu tên và đầu họ (`Jane Doe` → `JD`). Tên
+tiếng Anh tên gọi đứng trước, họ đứng cuối, nên hai chữ luôn tách đúng (`T28`).
+
+---
+
+## Chồng lên nhau
+
+Nhóm người, danh sách thành viên, "3 người đang xem":
+
+```tsx
+// -space-x-2: chồng lên nhau là bản chất của nhóm avatar, không có cách dương nào (N11 bước 4).
+<div className="flex -space-x-2">
+  {members.map((member) => (
+    <Avatar key={member.id} className="ring-2 ring-surface" {...member} />
+  ))}
+</div>
+```
+
+- **`ring-2 ring-surface`** thay cho viền màu khi chồng — vòng trắng cắt rời từng avatar khỏi cái sau nó. Không có vòng này thì các hình tròn dính thành một cục.
+- Chồng `-space-x-2` với cỡ `size-10`. Chồng sâu hơn thì chữ cái bị che.
+- Quá 4 người thì hiện 3 cái rồi một ô `+5` cùng cỡ, nền `--background`, chữ `--muted`.
+
+---
+
+## Có ảnh
+
+```tsx
+<Image src={avatarUrl} alt="" width={40} height={40} className="size-10 rounded-full object-cover ring-1 ring-border" />
+```
+
+`alt=""` cùng lý do với `aria-hidden` ở trên. Ảnh lỗi thì rơi về chữ cái đầu, không
+để trống một vòng tròn xám.

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

@@ -0,0 +1,43 @@
+# Thanh thông báo (banner)
+
+Nằm **trong trang**, ngay dưới đầu trang hoặc đầu form. Không nổi, không bóng,
+không tự tắt. Khác toast (`../layouts/overlay.md`): toast báo một việc vừa xong
+rồi đi; banner báo một **tình trạng** còn kéo dài tới khi được xử lý.
+
+```html
+<div role="status" class="flex gap-3 rounded-2xl border border-amber-200 bg-amber-50 p-4">
+  <i data-lucide="triangle-alert" class="mt-0.5 size-5 shrink-0 text-amber-700"></i>
+  <div class="min-w-0 flex-1">
+    <p class="text-sm font-medium text-amber-800">Gói Pro hết hạn sau 3 ngày</p>
+    <p class="mt-0.5 text-sm text-pretty text-foreground/80">Sau 25/09/2026, tài khoản về gói Miễn phí và chỉ giữ 3 thành viên</p>
+  </div>
+  <!-- Nút và ✕ chung một cụm, căn giữa theo chiều dọc với khối chữ -->
+  <div class="flex shrink-0 items-center gap-1 self-center">
+    <!-- nút viền nền trắng h-9, chỉ chữ: "Gia hạn gói" -->
+    <!-- IconButton ✕, aria-label "Đóng thông báo" -->
+  </div>
+</div>
+```
+
+## Ba tông
+
+| Tông | Khi nào | Nền · viền | Icon | Tiêu đề | ✕ |
+| --- | --- | --- | --- | --- | --- |
+| Thông tin | Không ai làm sai gì, chỉ cần biết | `bg-background` · `border-border` | `info` `text-muted` | `text-foreground` | Có |
+| Cần chú ý | Sắp thành chuyện nếu không làm gì | `bg-amber-50` · `border-amber-200` | `triangle-alert` `text-amber-700` | `text-amber-800` | Có |
+| Lỗi | Đã hỏng, phải xử lý | `bg-red-50` · `border-red-200` (`M30`) | `circle-alert` `text-red-600` | `text-red-700` | **Không** |
+
+Không có banner `rose`: nguy hiểm là lời nhắc trước khi bấm, không phải một
+tình trạng (`M30`). Không có banner xanh lá "thành công": xong việc thì là toast.
+
+## Luật
+
+- **Chỉ icon và tiêu đề mang màu. Mô tả `text-foreground/80`**, không tô cả đoạn. Mô tả `text-pretty` (`T10`): banner rộng hết cột, câu hai dòng dễ trơ một chữ ở dòng cuối ("…để giữ gói" / "Pro."). Hai dòng cùng hổ phách, cùng đỏ thì cả khối hét lên, và câu mô tả dài đọc mỏi hơn chữ tối.
+- **Hai tầng**: tiêu đề `font-medium` nói chuyện gì; mô tả nói hệ quả hoặc vì sao, có số, có mốc thời gian. Một câu đủ thì bỏ tầng dưới.
+- **Nút và ✕ chung một cụm, `self-center`** theo khối chữ. Đừng để nút căn giữa còn ✕ bám góc trên: hai thứ cùng hàng mà lệch cao là lỗi thấy ngay.
+- **Nút trong banner chỉ có chữ, không icon**, nền trắng viền mảnh (`outline`), `h-9`. Cùng ngoại lệ với hộp xác nhận: icon đã đứng ở đầu khối. Tối đa một nút. Không nút `primary` trong banner: màu tông đã đủ gọi mắt.
+- **Chỉ dẫn tới một chỗ khác thì là link hoặc nút**, không để thành câu chữ trơn. "Đổi địa chỉ nhận trong Cài đặt, mục Thanh toán" thì "Cài đặt" là link, hoặc thêm nút "Mở cài đặt".
+- **Lỗi không có ✕**: đứng đó tới khi xử lý xong. Thông tin và cần chú ý có ✕. Đóng rồi có hiện lại không, bao lâu hiện lại là logic, người dùng quyết.
+- **Rộng bằng vùng nội dung**, bo `rounded-2xl`, `p-4`. Không bóng (`M15`). Tối đa hai banner chồng nhau một lúc; nhiều hơn là trang đang có vấn đề khác cần gom lại.
+- **`role`**: lỗi `role="alert"`, còn lại `role="status"`.
+- Tiền trong câu dùng `đ`, không `₫` (`charts.md`).

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

@@ -0,0 +1,201 @@
+# Đường dẫn (breadcrumb)
+
+Dòng các cấp cha của trang đang xem, mỗi cấp là link. Nằm ở một trong hai chỗ: thanh header
+`h-16` của khung app, hoặc trên tên trang trong đầu trang (`../layouts/app.md`, "Đầu trang trong
+vùng nội dung"). Không bao giờ cả hai.
+
+## Khi nào có
+
+- **Trang nằm sâu hơn mục sidebar đang sáng**: chi tiết bản ghi, form tạo, trang con của một
+  bản ghi. Trang danh sách cấp một thì mục sidebar đã nói đủ, không đường dẫn; tên trang trên
+  thanh header là `<h1>`.
+- **Không dùng cho luồng nhiều bước** (đó là thanh các bước, `../layouts/form.md`) và **không
+  phải lịch sử duyệt**: đường dẫn ghi cây trang, vào từ đâu cũng ra một dòng như nhau.
+
+## Hình
+
+```
+Khách hàng  ›  Công ty TNHH Minh Phát  ›  Đơn hàng       <- chỉ các cấp CHA, đều là link
+Đơn DH-10412                                             <- <h1>, không có trong đường dẫn
+```
+
+- **Chỉ ghi các cấp cha, không ghi trang đang đứng.** Tên trang là `<h1>` ngay dưới (hoặc
+  ngay cạnh trên thanh header), ghi lại là lặp. Nhiều bộ thiết kế thêm trang hiện tại làm mục
+  cuối, nhưng các bộ đặt đường dẫn ngay trên tên trang thì bỏ nó đi, và skill luôn ở ca đó.
+  Ca hiếm đường dẫn là chỗ **duy nhất** ghi tên trang (trình duyệt tệp, không có tiêu đề
+  nào khác): mục cuối là chữ trơn `font-medium text-foreground` có `aria-current="page"`,
+  không phải link.
+- **Chữ mỗi mục đúng bằng `<h1>` của trang đích.** Bấm "Công ty TNHH Minh Phát" mà ra trang
+  tên "Hồ sơ khách hàng" thì người đọc không biết mình vừa đi đâu.
+- **`text-sm text-muted`, rê vào `hover:text-foreground`, không gạch chân, không nền.** Cùng
+  cách rê của link sidebar: đường dẫn là thanh điều hướng, không phải link trong câu văn.
+- **Dấu ngăn `ChevronRight` `size-4` `text-muted`, `aria-hidden`**, `gap-2` cả ở `<ol>` lẫn
+  trong `<li>`. Nét dấu › chỉ rộng 4px giữa hộp 16px, nên nét chữ tới nét dấu là 14px mỗi bên.
+  Dấu "/" cũng phổ biến ngang, skill chọn một kiểu cho cả app (`D1`), đừng trộn.
+- **Mỗi mục `inline-flex h-8 items-center`**: chữ 20px nhưng vùng bấm 32px dọc. Ở đầu trang,
+  tên trang ngay dưới **không `mt`**: hàng 32px đã chừa 6px dưới chữ.
+- **Tên dài: `max-w-48 truncate` kèm `title`**, cắt từng mục, không cắt cả dòng. 192px ở
+  `text-sm` là khoảng 28 ký tự.
+- **Không xuống dòng** (`R6`): đường dẫn đọc theo một chiều, rớt nửa sau xuống hàng hai thì dấu
+  › đầu hàng đọc như mục mới. Chật thì cắt tên và thu gọn theo mục dưới.
+- **Tab tới: chữ gạch chân**, không vòng (`I13`).
+
+## Đường dài
+
+```
+Tài liệu  ›  …  ›  Hợp đồng 2026  ›  Quý 3                <- 5 cấp cha, giữa gom vào "…"
+            └ Dự án Minh Phát
+              Pháp lý
+```
+
+- **Tới 3 cấp cha thì hiện hết.** Từ 4 cấp: giữ **cấp đầu** và **hai cấp gần nhất**, các cấp
+  giữa gom vào một nút "…". Cấp đầu cho biết đang ở khu nào, hai cấp gần là chỗ hay quay về
+  nhất.
+- **Nút "…" mở dropdown menu**, không bung tại chỗ: bung ra là dòng dài lại và phải xuống
+  dòng. `aria-label="Hiện các cấp bị ẩn"`, `aria-haspopup="menu"`. Menu liệt kê các cấp ẩn
+  theo thứ tự từ trên xuống, mỗi mục là link, khuôn mục menu ở `../layouts/overlay.md`.
+- **Nút "…" trông như một mục chữ, không phải icon button.** Hộp ôm sát icon (`h-5 w-4 p-0`,
+  icon `MoreHorizontal size-4`), không nền, `text-muted` rê vào `text-foreground`, đang mở giữ
+  `text-foreground`. Vùng bấm nới bằng `before:` (`before:absolute before:-inset-x-1.5
+  before:-inset-y-1.5`, 28×32px, cùng cách tay cầm ở `range-slider.md`). Đừng dùng nút `ghost size-8`: padding 8px mỗi bên, nét "…"
+  cách dấu › 22px trong khi chữ cách dấu 12px, và rê vào hiện một ô nền xám giữa hàng chữ
+  chỉ đổi màu.
+
+## Màn hẹp (dưới `sm`)
+
+```
+☰  ‹ Khách hàng                                  🔔  (T)
+```
+
+- **Chỉ còn cấp cha gần nhất, có `ChevronLeft` đứng trước**: một link "quay về", không phải
+  đường dẫn thu nhỏ. 375px không đủ chỗ cho ba mục cắt còn "Khách…", "Công t…". Các cấp xa
+  hơn vẫn tới được qua sidebar.
+- **Vùng bấm `h-10`** (`h-10 sm:h-8`): trên điện thoại đây là nút quay lại, bấm bằng ngón cái.
+- Tên cấp cha vẫn `max-w-48 truncate`, không bị ép chung hàng với mục khác nên hiếm khi cắt.
+- Tên bị cắt có dấu "…" thì khe tới dấu › có thể rộng hơn vài px: trình duyệt cắt ở ký tự cuối
+  còn vừa, phần thừa để trống. Không sửa được bằng CSS, đừng đuổi theo.
+
+## Khung
+
+```tsx
+interface BreadcrumbItem {
+  label: string;
+  href: string;
+}
+
+interface BreadcrumbProps {
+  // Chỉ các cấp cha, từ xa tới gần. Không đưa trang đang đứng vào đây.
+  items: BreadcrumbItem[];
+  className?: string;
+}
+
+// Link cao 32px để dễ bấm; Tab tới thì <span> chữ bên trong gạch chân (breadcrumbTextClass).
+const breadcrumbLinkClass =
+  "group inline-flex h-8 max-w-48 items-center text-muted outline-hidden transition-colors hover:text-foreground";
+
+const breadcrumbTextClass = cn(
+  "truncate rounded-sm",
+  "group-focus-visible:underline",
+);
+
+export default function Breadcrumb({ items, className }: BreadcrumbProps) {
+  const nearestParent = items.at(-1);
+  if (!nearestParent) return null;
+
+  // Từ 4 cấp: giữ cấp đầu và hai cấp gần nhất, cấp giữa vào menu "…".
+  const isCollapsed = items.length > 3;
+  const leadingItems = isCollapsed ? items.slice(0, 1) : [];
+  const hiddenItems = isCollapsed ? items.slice(1, -2) : [];
+  const trailingItems = isCollapsed ? items.slice(-2) : items;
+
+  return (
+    <nav aria-label="Đường dẫn" className={cn("min-w-0", className)}>
+      {/* Màn hẹp: một link quay về cấp cha gần nhất. */}
+      <Link
+        href={nearestParent.href}
+        title={nearestParent.label}
+        className={cn(breadcrumbLinkClass, "h-10 gap-1 text-sm sm:hidden")}
+      >
+        {/* Vòng bọc cả ‹ lẫn chữ; pr-1.5 bù khoảng trống bên trái nét ‹ trong hộp icon. */}
+        <span className={cn(breadcrumbTextClass, "inline-flex min-w-0 items-center gap-1 pr-1.5")}>
+          <ChevronLeft className="size-4 shrink-0" aria-hidden />
+          <span className="truncate">{nearestParent.label}</span>
+        </span>
+      </Link>
+
+      <ol className="hidden min-w-0 items-center gap-2 text-sm sm:flex">
+        {leadingItems.map((item) => (
+          <BreadcrumbCrumb key={item.href} item={item} hasSeparator={false} />
+        ))}
+
+        {hiddenItems.length > 0 ? (
+          <li className="flex shrink-0 items-center gap-2">
+            <ChevronRight className="size-4 text-muted" aria-hidden />
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                {/* Trông như một mục chữ: hộp ôm sát icon, không nền. Vùng bấm nới ra 28×32px
+                    bằng before: (số âm có chủ ý, N11: nới vùng bấm mà không đẩy hình). */}
+                <Button
+                  variant="ghost"
+                  aria-label="Hiện các cấp bị ẩn"
+                  className={cn(
+                    "group relative h-5 min-h-0 w-4 rounded-sm p-0 text-muted hover:bg-transparent hover:text-foreground",
+                    "before:absolute before:-inset-x-1.5 before:-inset-y-1.5",
+                    "aria-expanded:text-foreground",
+                  )}
+                >
+                  <MoreHorizontal className="size-4" aria-hidden />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="start">
+                {hiddenItems.map((item) => (
+                  <DropdownMenuItem key={item.href} asChild>
+                    <Link href={item.href}>{item.label}</Link>
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </li>
+        ) : null}
+
+        {trailingItems.map((item, index) => (
+          <BreadcrumbCrumb key={item.href} item={item} hasSeparator={isCollapsed || index > 0} />
+        ))}
+      </ol>
+    </nav>
+  );
+}
+
+// breadcrumb-crumb.tsx: một mục, dấu › đứng trước trong cùng <li>.
+export default function BreadcrumbCrumb({ item, hasSeparator }: BreadcrumbCrumbProps) {
+  return (
+    <li className="flex min-w-0 items-center gap-2">
+      {hasSeparator ? <ChevronRight className="size-4 shrink-0 text-muted" aria-hidden /> : null}
+      <Link href={item.href} title={item.label} className={breadcrumbLinkClass}>
+        <span className={breadcrumbTextClass}>{item.label}</span>
+      </Link>
+    </li>
+  );
+}
+```
+
+`Link` là link của router dự án (`next/link`, `react-router`). Dự án đã có `ActionMenu` hay
+`DropdownMenu` bọc sẵn thì dùng cái đó cho nút "…", đừng dựng menu thứ hai.
+
+## Không làm
+
+- **Không dropdown trên từng mục để chuyển sang bản ghi cùng cấp** (bấm "Dự án A ⌄" ra danh
+  sách dự án). Đường dẫn để đi lên; đổi workspace, đổi dự án là việc của sidebar
+  (`../layouts/app.md`). Hai việc chung một chỗ thì bấm vào tên không biết sẽ đi hay mở menu.
+- Không icon nhà ở mục đầu, không in đậm mục nào: mục nào cũng là cấp cha ngang nhau.
+- Không ghi lại đường dẫn ở đầu trang khi thanh header đã có.
+
+## Kiểm
+
+- Đường dẫn có trùng chữ với `<h1>` ngay dưới không? Có thì đang ghi trang hiện tại.
+- Bấm từng mục: tên trang đích có đúng chữ trên mục không?
+- Ở 1280px với 5 cấp cha: một hàng, có "…" mở menu, Tab tới "…" rồi Enter mở được?
+- Nét dấu › tới nét chữ hai bên bằng nhau, kể cả quanh "…" (probe đo: "dấu ngăn cách không đều").
+- Ở 375px: chỉ còn "‹ Cấp cha", cao 40px, không có mục nào bị cắt còn vài chữ. Tab tới: chữ gạch chân.
+- Rê vào mục và vào "…": chỉ đổi màu, không hiện ô nền. Tab tới: chỉ gạch chân, không vòng.
+- Trình đọc màn hình: `nav` có tên "Đường dẫn", mục trong `ol`, dấu › không bị đọc.