@haposoft/cafekit 0.16.6 → 0.18.0

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

@@ -0,0 +1,142 @@
+# Button
+
+> ⚠️ Bản trước của file này dạy ba variant `primary` / `ghost` / `danger` và
+> "nút mặc định không icon". **Cả hai đã đảo** — xem luật `I1`. Chủ dự án chốt:
+> nút mặc định là **nút viền**. Icon lucide bên trái chữ chỉ khi glyph gọi đúng
+> hành động; nút form và nút trong modal chỉ có chữ (xem `I1`).
+
+---
+
+## Bốn dạng, hết
+
+```tsx
+type ButtonVariant = "outline" | "primary" | "secondary" | "ghost";
+
+function getVariantClasses(variant: ButtonVariant): string {
+  return cn(
+    // MẶC ĐỊNH. Dựng nút mới thì dùng cái này.
+    // Hover: CHỈ đổi nền sang --button-hover (màu đặc), viền giữ nguyên.
+    variant === "outline" &&
+      "border border-border-strong bg-surface text-foreground hover:bg-button-hover",
+    // Hành động chính DUY NHẤT của một khu, khi thật cần nổi.
+    variant === "primary" &&
+      "bg-primary text-primary-foreground hover:bg-primary-hover",
+    // Nút phụ cần nhỉnh hơn ghost mà không tranh chỗ nút chính. Không viền.
+    variant === "secondary" &&
+      "bg-secondary text-foreground hover:bg-secondary-hover",
+    // Hành động phụ nằm trong hàng, mờ đi lúc thường.
+    // Hover foreground/5, KHÔNG bg-background: ghost hay đứng thẳng trên nền trang
+    // xám (header, toolbar), tô --background ở đó thì rê vào không thấy gì.
+    variant === "ghost" &&
+      "bg-transparent text-muted hover:bg-foreground/5 hover:text-foreground",
+  );
+}
+
+<button
+  className={cn(
+    "inline-flex cursor-pointer items-center justify-center gap-2 rounded-xl",
+    // Cao 40px cố định cho nhãn một dòng, viền hay không viền cũng vậy. min-h chứ không h:
+    // nhãn dài xuống dòng thì nút cao thêm (T15).
+    "min-h-10 px-4 py-2 text-sm font-medium transition-colors",
+    // Nhãn tiếng Việt dài thì cho xuống dòng, đừng để tràn. Luật T15.
+    "max-w-full text-center leading-tight [overflow-wrap:anywhere]",
+    // Không vòng focus (I13). Dự án cần accessibility thì trả vòng lại đúng ở dòng này (I14)
+    "outline-hidden",
+    "disabled:cursor-not-allowed disabled:not-aria-busy:opacity-50",
+    getVariantClasses(variant),
+  )}
+>
+  {Icon ? <Icon className="size-4 shrink-0" aria-hidden /> : null}
+  {children}
+</button>
+```
+
+**Đang xử lý (loading)**
+
+```tsx
+<Button variant="primary" aria-disabled={isSending || undefined} aria-busy={isSending || undefined}
+  onClick={(event) => { if (isSending) event.preventDefault(); }}>
+  {isSending ? <LoaderCircle className="size-4 shrink-0 animate-spin motion-reduce:animate-none" aria-hidden /> : <Send className="size-4 shrink-0" aria-hidden />}
+  Gửi lời mời
+</Button>
+```
+
+- Spinner **thế chỗ icon**, cùng `size-4`, chữ giữ nguyên. Nút không đổi bề rộng, hàng nút không xô. **Nút chỉ chữ** (không icon để thế chỗ): nút `relative`, chữ thêm `invisible` để vẫn giữ bề rộng, spinner `absolute inset-0 m-auto` nằm giữa.
+- Không đổi chữ sang "Đang gửi…": chữ dài ngắn khác nhau là nút co giãn. Đổi thì phải giữ `min-w` bằng bản cũ.
+- **Đang xử lý thì chặn bấm bằng `aria-disabled` + `preventDefault` trong `onClick`, KHÔNG đặt `disabled`.** Nút `disabled` bị trình duyệt tước tiêu điểm: người dùng bàn phím bấm Enter xong rơi về `<body>`, lúc xong việc phải Tab lại từ đầu trang. Chặn ở `onClick` là chặn luôn Enter trong ô nhập, vì submit ngầm của form cũng đi qua cú click của nút submit. Nên cài một lần trong component `Button` (prop `isLoading`), đừng viết lại ở từng trang.
+- Nút đang xử lý **không mờ** như nút khoá thường, chỉ spinner nói đang chạy, con trỏ `cursor-progress`. Mờ đi thì đọc ra là "bấm không được vì sai gì đó". Class gốc vẫn giữ `disabled:not-aria-busy:opacity-50` cho dự án nào lỡ đặt `disabled` lúc đang xử lý.
+
+**Vì sao ổn**
+
+- **`outline` là mặc định**, không phải `primary`. Nút nền nhấn rải khắp nơi thì màu thương hiệu loang ra, tới lúc có một nút thật sự cần nổi thì nó không nổi được nữa (`I1`, `M2`).
+- **Nút viền rê vào thì chỉ đổi nền, viền giữ nguyên** (`hover:bg-button-hover`, `#f1f1f3`), như phần lớn các bộ component. Nền hover phải là **màu đặc**, tách được cả khỏi nền ngay sau nút lẫn khỏi màu viền. Ba cách đã hỏng: `hover:bg-item-hover` ra đúng `#f4f4f6` của nền trang, nút tan vào trang; lớp phủ `foreground/5` trong suốt nên lấy màu nền phía sau, trên nền trang ra `#e9e9eb` **trùng màu viền** `#eaeaea`, nút thành mảng xám không viền; `--surface-hover` `#f8f8fa` thì trên card gần như không đổi. Cách chữa tạm "viền đậm lên `foreground/20`" thấy được ở đâu cũng được nhưng nặng, trông như nút đang bấm giữ hoặc đang chọn (chủ dự án chốt chỉ đổi nền). **Màu rê theo nền ngay sau nút**, tự đổi qua biến (`tokens.css`, khối "NỀN RÊ CỦA NÚT VIỀN"): trên card trắng `#f1f1f3`, thẳng trên nền trang hoặc trong dòng đang rê `#e4e4e7`. Một màu `#f1f1f3` cho mọi chỗ thì trên nền trang `#f4f4f6` chỉ lệch 3 mức, nút như tan vào trang (bác lý lẽ "chìm nhẹ mà viền vẫn còn"). Màu nền trang phải đậm hơn viền `#eaeaea` ít nhất 5 mức: `#e7e7ea` chỉ lệch 3, viền tan, nút thành mảng xám; `#e4e4e7` lệch 6. Màu đó trên card trắng thì quá nặng, nên card giữ `#f1f1f3`. Class vẫn là `hover:bg-button-hover`, không viết màu theo chỗ đặt. Nút có mũi tên mở danh sách lựa chọn thì không theo mục này mà theo ô Select (xem dưới).
+- **`ghost` rê vào `hover:bg-foreground/5`**, không `bg-background` (ghost trong suốt, không có viền để đậm lên, nên phải là lớp phủ). Nút ghost nằm **trong dòng bảng / danh sách có nền rê** (⋯, icon button, ô sửa tại chỗ) thì `/8`, vì nó chồng lên nền dòng đang rê (`I10`).
+- **Nút mở danh sách lựa chọn** (nút lọc "Vai trò ▾", "Trạng thái: Tất cả ▾", "Mỗi trang 10 ▾") **là ô Select, không phải nút viền**: dùng đúng class của ô Select (`choice-controls.md`), tức **không có hover**, chỉ `cursor-pointer`; lúc mở `aria-expanded:border-focus aria-expanded:ring-2 aria-expanded:ring-focus`, nền giữ `bg-surface`, mũi tên xoay. Mũi tên + con trỏ đã nói "bấm được", như ô Select trong form và ô nhập vốn không có hover; thêm hover nữa là tín hiệu thứ hai cho một ý (`N3`), và lệch khuôn với ô Select ngay trong modal (`N5`). Chủ dự án chốt. Nút mở **menu thao tác** (⋯, "Xuất ▾") thì không phải ô chọn: lúc mở giữ nền rê `aria-expanded:bg-foreground/5`.
+- **`secondary` (nền xám, không viền)** dùng khi nút phụ cần có mặt rõ hơn `ghost` nhưng viền mảnh trông rỗng: nút rộng hết card (các gói thường trong bảng giá, `layouts/pricing.md`), hoặc nút phụ đứng cạnh nút `primary` trong footer. Không thay `outline` làm mặc định (chủ dự án chốt).
+- **`ghost` đứng đầu hàng, thẳng cột với chữ phía trên.** Nền trong suốt nên mắt thấy mép của chữ chứ không thấy mép nút, để nguyên thì cả hàng trông lệch vào 16px so với tiêu đề và nhãn bên dưới. Nút có nền hoặc viền thì không bù. Bù theo thứ tự, không kéo nút ra bằng `-ml-*` / `-mr-*` (`N11`):
+  1. **Nút nằm ở đầu hay cuối một hàng riêng** (header, dòng danh sách): **hàng bớt padding phía đó** đúng bằng `px` của nút, ví dụ header `pl-4 pr-3` khi nút cuối `h-8 px-3` trong hàng `px-6`. Chữ "Đánh dấu đã đọc" ở header panel thông báo thẳng cột với chấm chưa đọc bên dưới; lúc rê vào nền xám sát mép panel hơn tiêu đề bên trái là đúng ý. Trùng từng pixel với bản số âm.
+  2. **Nút chỉ đổi màu chữ khi rê, không nền** (nút mở danh sách bước công cụ trong chat): bỏ `px`, chữ tự thẳng mép.
+  3. **Nút có nền rê nằm giữa một cột chữ** (hàng Sao chép / Tạo lại dưới câu trả lời): không có hàng riêng để bớt padding; chia padding từng khối thì mọi khối con phải tự nhớ `px-2` và `max-w` phải cộng bù (bong bóng `max-w-[80%]` và cột `55ch` lệch theo). Giữ `-ml-2` kèm comment lý do (`N11` bước 4).
+- Icon lucide **bên trái chữ**, `size-4`, `shrink-0` để nó không bị bóp khi nhãn dài. `aria-hidden` vì chữ đã nói rồi.
+- **Không `white-space: nowrap`.** Đo thật ở một dự án: hộp 140px, nút nowrap rộng 192px, tràn 60px ra ngoài. `leading-tight` để hai dòng không dính nhau. Luật `T15`.
+- **Không `shadow`.** Nút nằm trong trang (`M15`).
+- Chỉ `transition-colors`. Nút không phóng to, không nhấc lên, không đổ bóng thêm khi hover (`F22`).
+- **Không vòng focus** (`I13`), kể cả khi Tab tới.
+- **Chiều cao đặt bằng `min-h-10`, không để `py` tự lo.** `py-2.5` + `leading-tight` thì nút đặc cao 38px, nút viền cao 40px vì cộng 2px viền: hai nút cạnh nhau lệch đáy. `min-h-10` gồm cả viền, nên nút nào cũng 40px; nhãn dài xuống dòng thì nút cao thêm, không tràn (`T15`). Nút chỉ icon `size-10`, cao bằng.
+- **Nút trong form hoặc footer modal** thêm `min-h-11 md:min-h-10` để cao đúng bằng ô nhập (`budgets.md`).
+- Không có prop `size`. Cần nút khác cỡ thì truyền `className` — đỡ đẻ ra ma trận variant nhân size (`I6`). **Nút thấp hơn 40px thì truyền cả `min-h-*`** (`size-8 min-h-8`, link chữ `h-auto min-h-0`): `h-8` hay `size-8` không đè được `min-h-10` của class gốc, nút vẫn cao 40px.
+- Logic class nằm trong `getVariantClasses()` ngoài JSX, không nhét ternary vào giữa markup.
+
+---
+
+## Nút xoá
+
+Nền đỏ mờ 10% và chữ đỏ, **lúc nào cũng vậy**, không đợi rê vào. Rê vào hoặc Tab
+tới thì nền đậm lên một bậc:
+
+```tsx
+<Button
+  variant="ghost"
+  className="bg-rose-500/10 text-rose-700 hover:bg-rose-500/15 hover:text-rose-700 dark:text-rose-400"
+>
+  <Trash2 className="size-4 shrink-0" aria-hidden />
+  Xoá
+</Button>
+```
+
+- **Chữ `rose-700`, không `rose-500`** (nút nguy hiểm `I4`). Đo trên nền `rose-500/10` phủ trắng: `rose-500` chỉ 3.2:1, `rose-600` 3.9:1, đều trượt mức 4.5:1 của chữ 14px. `rose-700` được 5.2:1 mà vẫn đọc ra là đỏ. Nền tối thì ngược lại, chữ sáng lên `rose-400`.
+- **Không dùng Tailwind** thì: nền `var(--danger-bg)`, rê vào `var(--danger-bg-hover)`, chữ + icon `var(--danger)`. Khối `.dark` trong `tokens.css` đã đổi sẵn sang `rose-400`.
+- **Nền mờ, không đỏ đặc.** Nhận ra ngay là nút nguy hiểm nhưng không hét như nút `bg-rose-500 text-white` (`I4`).
+- **Không viền đỏ** (`M30`). Nền mờ đã đủ tách nút khỏi nền trang.
+- Icon cùng màu chữ — không để icon `text-muted` riêng.
+- Bị khoá thì vẫn `opacity-50` như mọi nút.
+- Chỉ áp cho **nút đứng riêng**: hàng nút, hộp xác nhận, khu nguy hiểm trong cài đặt. **Mục trong menu** (dropdown, sidebar) vẫn trung tính lúc thường, rê vào mới đỏ — xem `I4`.
+
+> Chủ dự án chốt: nút xoá là nền danger 10% + chữ danger. Bản trước
+> (xám lúc thường, rê vào mới đỏ) đã bỏ cho nút; vẫn giữ cho mục menu.
+
+---
+
+## Nút chỉ có icon
+
+Vuông, cao **bằng đúng** nút chữ đứng cạnh nó, và luôn có `aria-label`:
+
+```tsx
+<button
+  aria-label="Lọc danh sách"
+  className="inline-flex size-10 cursor-pointer items-center justify-center rounded-xl border border-border-strong bg-surface text-muted outline-hidden hover:bg-button-hover hover:text-foreground"
+>
+  <SlidersHorizontal className="size-4" aria-hidden />
+</button>
+```
+
+Chênh chiều cao với ô nhập hay nút chữ bên cạnh dù chỉ một bậc là nhìn ra ngay.
+
+---
+
+## Cảnh báo
+
+Một bản `Button` ở project cũ đã phình lên **8 variant, 3 size** và một variant
+`glow` dùng ba lớp radial gradient. Đó là ví dụ ngược. Muốn thêm variant thứ năm
+thì phải trả lời được: nó khác bốn cái kia ở chỗ nào, và vì sao bốn cái kia không
+làm được việc đó.

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

@@ -0,0 +1,113 @@
+# Card
+
+```tsx
+<section className="flex flex-col rounded-2xl border border-border bg-surface p-5">
+  <header className="mb-4 flex items-start justify-between gap-3">
+    {/* min-h-10 = cao bằng nút action, CHỈ khi có action: một dòng thì tiêu đề nằm giữa nút, nhiều dòng thì nút bám góc trên */}
+    <div className={cn("flex min-w-0 items-center gap-2", action && "min-h-10")}>
+      {icon}
+      <h2 className="text-base font-semibold text-balance text-foreground">{title}</h2>
+    </div>
+    <div className="shrink-0">{action}</div>
+  </header>
+
+  <div className="min-h-0 flex-1">{children}</div>
+</section>
+```
+
+**Vì sao ổn**
+
+- Card tách khỏi nền bằng **đường tóc 1px + bo góc**, không bằng bóng. Đây là luật `M13`.
+- Dùng đúng `--border`, cùng token với đường chia và khung dropdown, nên trong app không có chỗ đậm chỗ nhạt. Ô nhập thì dùng `--border-strong`, đậm hơn một bậc (`M14`).
+- **Không `shadow-*`.** Bóng chỉ dành cho lớp nổi lên trên trang — modal, dropdown, popover (`M15`). Card nằm trong trang thì không.
+- Tiêu đề card là `text-base font-semibold`, đúng một bậc trên chữ bên trong (`T8`). Không `text-2xl`, không uppercase, không tracking rộng.
+- Header và body cách nhau `mb-4`, padding card `p-5`. Hai con số này lặp lại ở mọi card, không card nào tự chế.
+- Chỗ đặt hành động là một slot `action` ở góc phải header, nên nút thêm hay nút lọc không bao giờ trôi xuống giữa nội dung.
+- **Header `items-start`, không `items-center`.** Tiêu đề dài xuống hai dòng thì nút vẫn bám góc trên phải, không trôi xuống giữa. Khối tiêu đề `min-h-10` bằng chiều cao nút nên lúc chỉ một dòng, chữ vẫn nằm giữa nút. Tiêu đề `min-w-0 text-balance` để xuống dòng đều, nút `shrink-0` để không bị bóp.
+- **`min-h-10` chỉ khi header có nút.** Card chỉ có tiêu đề mà vẫn giữ `min-h-10` thì dòng chữ 24px nằm giữa khung 40px, dư 8px trên 8px dưới: chữ tiêu đề cách mép trên ~32px trong khi nội dung cuối cách mép dưới ~20px, và tiêu đề cách nội dung của nó cũng ~32px. Tiêu đề lơ lửng giữa mép card và nội dung, không bám vào khối nó đặt tên, card hẫng đầu. Ngoại lệ: các card đứng cùng một hàng lưới mà chỉ vài cái có nút thì cả hàng giữ `min-h-10`, để tiêu đề thẳng hàng nhau.
+
+---
+
+## Card chứa dòng có nền rê: padding đặt ở từng khối, không ở card
+
+`p-5` trên card chỉ đúng khi thân card là chữ, số, form. Thân là danh sách có nền rê
+(`list-row.md`, dòng `px-2`/`px-3` để nền rê không ôm sát chữ, `F13`) thì chữ dòng thụt
+vào đúng bằng `px` của dòng, lệch mép tiêu đề card. Component `Card` dùng chung phải có sẵn
+cách thứ hai, không để từng chỗ tự vá:
+
+```tsx
+// isFlushList: thân là danh sách dòng có nền rê. Card không px, tiêu đề px-5, khối danh
+// sách px-2 (= 5 − 3), dòng px-3: chữ dòng thẳng mép chữ tiêu đề, nền rê vẫn tràn ra 12px.
+<section className={cn("flex flex-col rounded-2xl border border-border bg-surface", isFlushList ? "py-5" : "p-5")}>
+  <header className={cn("flex items-start justify-between gap-3", isFlushList ? "px-5" : "mb-4", isFlushList && !action && "mb-1.5")}>…</header>
+  <div className={cn("min-h-0 flex-1", isFlushList && "px-2")}>{children}</div>
+</section>
+```
+
+- Khối danh sách `px` = padding card − `px` của dòng: dòng `px-3` thì `px-2`, dòng `px-2` thì `px-3`.
+  Màn hẹp card `p-4` thì trừ từ 16.
+- **Bớt `mb-4` của header khi thân là danh sách**: dòng đã có `py-2.5` ở trên chữ. Header có
+  action thì `mb-0` (khối `min-h-10` đã dư ~10px dưới chữ tiêu đề), không action thì `mb-1.5`.
+  Chữ tiêu đề tới chữ dòng đầu khi đó ~20px, bằng khoảng giữa hai dòng. Giữ `mb-4` thì thành
+  36px, tiêu đề lơ lửng.
+- Không kéo danh sách ra bằng `-mx-3` (`N11`).
+
+Card `p-5` mà dòng `px-2` nằm thẳng trong thân thì chữ dòng lệch chữ tiêu đề 8px, chữ tiêu đề tới
+chữ dòng đầu 36px trong khi giữa hai dòng 20px.
+
+---
+
+## Khi nào dùng `ring` thay `border`
+
+`border` ăn vào hộp theo `box-sizing: border-box`, nên phần tử **cỡ cố định** sẽ
+co lại 1px mỗi bên khi bật viền. Với card thì không sao — card co giãn được.
+
+Dùng `ring-1` cho thứ có kích thước cố định: avatar, ô vuông icon 28px, thumbnail.
+Xem luật `M17`.
+
+---
+
+## Nhiều mục cùng loại thì MỘT khung, không phải nhiều card
+
+Bốn card trắng giống hệt nhau xếp lưới thì mắt đọc ra bốn khối ngang hàng, không
+đọc ra một danh sách. Gom lại:
+
+```tsx
+<section className="rounded-2xl border border-border bg-surface">
+  <header className="flex items-center justify-between gap-3 px-5 py-4">
+    <h2 className="text-base font-semibold text-foreground">{title}</h2>
+    {action}
+  </header>
+
+  <ul className="divide-y divide-border border-t border-border">
+    {items.map((item) => <ListRow key={item.id} item={item} />)}
+  </ul>
+
+  <footer className="flex justify-end border-t border-border px-5 py-3">
+    <ViewAllButton />
+  </footer>
+</section>
+```
+
+Dòng tiêu đề và dòng hành động cuối nằm **TRONG** khung. Luật `F3`.
+
+---
+
+## Slot `action` ở header
+
+Chỗ đặt hành động phụ của cả khối: "Xem tất cả", "Đọc thêm", nút lọc, nút thêm
+mới. **Luôn căn phải, cùng hàng với tiêu đề.**
+
+**Kiểu nút theo loại hành động**, không dùng chung một kiểu cho mọi action:
+
+| Hành động | Nút |
+| --- | --- |
+| Dẫn sang màn khác: "Xem tất cả", "Đọc thêm" | **link chữ** `h-8`, không padding ngang, rê vào gạch chân, **không icon** (`I7`) |
+| Làm một việc: tải, xuất, thêm, lọc | nút viền `outline` **có icon trái** (`I1`): `download`, `plus`, `filter` |
+
+Đừng dựng "Tải báo cáo" y như "Xem tất cả" (không icon): đọc ra là link sang trang khác chứ không phải nút tải.
+
+"Xem tất cả" là link chữ `text-foreground/70`, không màu nhấn, không icon mũi tên,
+không padding ngang nên chữ thẳng mép phải nội dung card. Header có link thì khối
+tiêu đề vẫn `min-h-10` như có nút (link cao `h-8`, thêm `my-1` để thẳng tâm dòng
+tiêu đề). Xem luật `I7`.