@haposoft/cafekit 0.16.7 → 0.18.0

package/src/claude/skills/ui-ux/references/layouts/pricing.md

@@ -0,0 +1,204 @@
+# Bảng giá
+
+> ⚑ Rút ra từ một lượt dựng thật (trang giá khoá học 3 gói).
+
+**Một bố cục mặc định, dựng luôn.** Người dùng muốn kiểu khác (gộp một khối,
+nút lên trên, bảng so sánh, gói nổi bật chỉ viền thay vì đảo màu…) thì họ nói, mình sửa theo. Đừng bày
+phương án.
+
+Đây là trang trình diễn, **giá luôn là font body** (`T3`).
+
+---
+
+## Đầu trang
+
+**Căn giữa**, tên trang cỡ hero, câu dẫn một câu. Gần như mọi trang bảng giá đứng
+riêng đều làm vậy: ba card đối xứng bên dưới, đầu trang lệch trái thì cả trang
+nghiêng một bên. Đây là ngoại lệ của `T12`, chỉ vì chữ ngắn (tên một dòng, câu dẫn
+tối đa hai dòng).
+
+```html
+<header class="text-center">
+  <h1 class="text-balance font-heading text-2xl font-bold text-foreground sm:text-3xl">…</h1>
+  <p class="mx-auto mt-3 max-w-[55ch] text-balance text-sm/6 text-muted sm:text-base/7">…</p>
+</header>
+<div class="mt-8 sm:mt-12 …"><!-- dãy gói --></div>
+```
+
+- **Tên trang `sm:text-3xl`, không phải `2xl`.** Giá là `3xl`; tên trang `2xl`
+  (24px) nằm trên ba con số 30px thì trang không có đầu, mắt nhảy thẳng vào giá
+  mà không biết đang xem gì. Tên trang bằng cỡ giá là đủ: nó
+  đứng một mình, căn giữa, font tiêu đề, không cần to hơn nữa.
+- Trang bảng giá **nằm trong khung app** (Cài đặt → Gói cước) thì không theo mục
+  này: tên trang `xl` căn trái như mọi trang app (`budgets.md`).
+
+---
+
+## Bố cục
+
+```
+┌──────────┐ ┌──────────┐ ┌──────────┐
+│ Tên      │ │ Tên [bdg]│ │ Tên      │  1 tên, badge nổi bật bên phải
+│ mô tả    │ │ mô tả    │ │ mô tả    │  2 đúng 1 câu
+│ GIÁ /th  │ │ GIÁ /th  │ │ GIÁ /th  │  3 giá + đơn vị cùng dòng
+│ dòng phụ │ │ dòng phụ │ │ dòng phụ │  4 điều kiện của giá
+├──────────┤ ├──────────┤ ├──────────┤    đường chia tràn mép card (F25)
+│ Bao gồm: │ │ Mọi thứ… │ │ Mọi thứ… │  5 tiêu đề danh sách
+│ ✓ ...    │ │ ✓ ...    │ │ ✓ ...    │  6 tính năng
+│ – ...    │ │ ✓ ...    │ │ ✓ ...    │
+│ [ nút  ] │ │ [ NÚT  ] │ │ [ nút  ] │  7 nút, luôn đáy card
+└──────────┘ └──────────┘ └──────────┘
+```
+
+Các card rộng bằng nhau, cao bằng nhau. Hàng giữa các card căn bằng `subgrid`,
+không chừa `min-h-*` (đoán độ dài chữ là sai ngay ở ca `S8`):
+
+```html
+<div class="grid gap-4 lg:grid-cols-3">
+  <!-- row-span-7 = số hàng trong sơ đồ. Thêm hàng thì đổi cả hai số. -->
+  <!-- Card chỉ padding DỌC, từng hàng tự px-7: vạch dưới giá tự tràn mép, không margin âm (N11). -->
+  <article class="row-span-7 grid grid-rows-subgrid gap-y-0 rounded-2xl border border-border bg-surface py-7 *:px-7">
+    …
+  </article>
+</div>
+```
+
+Gói nào cũng đủ 7 hàng. Thiếu dòng phụ thì để phần tử rỗng, đừng bỏ.
+
+**Vạch giữa phần giá và phần tính năng kẻ bằng `--border-strong`**, tràn mép card
+(`F25`): `border-t border-border-strong` trên hàng tiêu đề danh sách. Card chỉ có
+padding dọc (`py-7`), padding ngang nằm ở từng hàng (`*:px-7`), nên vạch tự chạm hai
+mép card; không `-mx-7` (`N11`).
+Cùng lý do với đường chia "hoặc" ở `form.md`: `--border` (`#f7f7f8`) đứng một mình
+trên card trắng chỉ 1.06 : 1, vạch biến mất, card đọc thành một khối chữ liền. Viền ngoài card vẫn `--border`: card trắng trên nền trang xám đã
+tự tách.
+
+Màn hẹp: một cột dưới `lg`, giữ thứ tự rẻ đến đắt, và **chặn bề rộng khi xếp
+chồng**: `mx-auto max-w-lg lg:max-w-none`. Không chặn thì ở 768px mỗi card rộng
+650px: danh sách tính năng chiếm một phần ba bên trái, còn lại trống, nút dài
+615px trông như thanh ngang. Card gói là thứ đọc dọc, rộng
+~500px là vừa, như khi đứng cạnh nhau ở màn rộng.
+
+```html
+<div class="mx-auto mt-8 grid max-w-lg grid-cols-1 gap-4 sm:mt-12 lg:max-w-none lg:grid-cols-3">
+```
+
+---
+
+## Từng hàng
+
+| Hàng | Làm | Đừng |
+| --- | --- | --- |
+| Tên | `text-lg font-semibold`, tối đa khoảng 3 từ | To bằng giá. Đây là **ngoại lệ có chủ ý của `T8`**: giá là thứ đọc đầu tiên |
+| Mô tả | Đúng 1 câu, gói nào cũng có | Gói có gói không |
+| Giá | `text-3xl font-bold tabular-nums`, đơn vị `/tháng` cùng dòng, căn `baseline`. Gói miễn phí ghi "Miễn phí" | "0đ" |
+| Dòng phụ | Điều kiện riêng của gói (`T22`), **vừa một dòng**: "Trả theo năm: 990.000đ/tháng" | Câu dài bị chẻ giữa con số (`T10`) |
+| Tiêu đề danh sách | "Bao gồm:" ở gói thấp nhất, "Mọi thứ trong Pro, thêm:" ở gói trên. `text-sm text-muted` | "Toàn bộ quyền lợi của gói Pro" viết thành một mục có dấu check |
+| Tính năng | Check nét `Check` lucide `size-4`. Mục không có: `Minus` + chữ `--muted`. Con số đứng đầu: "4 buổi kèm 1-1 mỗi tháng" | Check tròn tô đặc, check mờ cho mục không có |
+| Nút | Rộng hết card, **`h-12`** ở mọi bề rộng, chữ `text-sm font-medium`. Chữ là động từ + gói: "Đăng ký gói Pro" | Ba nút cùng chữ "Chọn gói". Nút `h-10` của app |
+
+**Nút `h-12`, không `h-10`.** Đây là hành động chính của cả trang, nằm đáy một card
+cao ~520px dưới con số 30px: nút 40px trông mỏng, như nút phụ trong toolbar (chủ dự
+án thấy "hơi thấp"). Cùng ngoại lệ với form đăng nhập đứng riêng
+(`form.md`): màn chỉ có một việc thì nút của việc đó to hơn một bậc.
+
+---
+
+## Gói nổi bật: card đảo màu + badge
+
+1. **Card nền tối**: `bg-primary`, chữ `text-primary-foreground`. Tính năng, tên,
+   giá, check đều `text-primary-foreground`; chữ phụ (mô tả, `/tháng`, dòng phụ,
+   tiêu đề danh sách) `text-primary-foreground/70`; vạch dưới giá
+   `border-primary-foreground/15`. Viền card cùng màu nền.
+2. **Badge** góc phải hàng tên: `rounded-full px-2.5 py-1 text-xs font-medium
+   bg-primary-foreground/15 text-primary-foreground`, chữ nói lý do ("Phổ biến nhất").
+   Không emoji, không ngôi sao (`T21`).
+3. **Nút đảo theo card**: nền trắng chữ tối,
+   `bg-surface text-foreground hover:bg-surface/90`. Dự án trả vòng focus lại (`I14`) thì
+   `focus-visible:ring-primary-foreground/60 focus-visible:ring-offset-primary`: offset mặc định
+   là màu `--surface`, trên card tối thành một viền trắng thừa.
+
+```html
+<article class="… rounded-2xl border border-primary bg-primary py-7 text-primary-foreground *:px-7">
+  <div class="flex items-center justify-between gap-3">
+    <h2 class="text-lg font-semibold">Pro</h2>
+    <span class="rounded-full bg-primary-foreground/15 px-2.5 py-1 text-xs font-medium">Phổ biến nhất</span>
+  </div>
+  <p class="mt-2 text-sm/6 text-primary-foreground/70">…</p>
+  …
+  <button class="h-12 w-full cursor-pointer rounded-xl bg-surface text-sm font-medium text-foreground outline-hidden hover:bg-surface/90">Đăng ký gói Pro</button>
+</article>
+```
+
+**Vì sao đảo màu.** Chỉ có badge + nút primary thì ba card trắng giống hệt,
+mắt không có chỗ dừng (chủ dự án thấy "chưa wow"). So ba cách: chỉ badge + nút (phẳng, không gói nào nổi), viền 1px `--primary` quanh
+card (có nổi nhưng phải nhìn kỹ mới thấy), card đảo màu (thấy ngay từ xa, vẫn phẳng:
+không bóng, không phóng to). Card đảo màu là cách phổ biến nhất ở các trang giá dùng
+màu trung tính. Chữ phụ `/70` trên `#181818` đo ~8:1; `--primary` có sắc thì đo lại,
+dưới 4.5:1 thì lên `/80`.
+
+Không làm card cao hơn, to hơn, vòng sáng, bóng, `scale-105` (`F20`, `F22`): màu nền
+đã đủ. Đề không có gói nào cần đẩy thì ba card cùng trắng, không badge.
+
+Nút các gói khác: **nền `--secondary`**, không viền
+— variant `secondary` ở `../components/button.md`. Nút rộng hết card mà chỉ có
+viền mảnh thì trông rỗng.
+
+---
+
+## Màu thương hiệu
+
+Màu nhấn chỉ nằm ở **card của gói nổi bật**. Còn lại trung tính (`M2`, `M3`).
+
+| Thứ | Theo `--primary`? |
+| --- | --- |
+| Nền card gói nổi bật | Có. Cả badge và nút bên trong đi theo card (mục trên) |
+| Check, giá, tên gói ở card trắng | Không. Check tô màu ở cả dãy là gói nổi bật hết nổi; giá màu nhấn đọc ra là link, màu sáng còn không đạt tương phản (`P3`) |
+| Nút các gói khác | Không |
+
+---
+
+## Những thứ không dựng nếu đề không nhắc
+
+- **Nút chuyển tháng/năm.** Có giá năm thì ghi ở dòng phụ dưới giá. Đề nhắc giảm giá trả năm mà không đưa số thì hỏi số, không bịa (`S7`).
+- **FAQ** (`S1`). Có thì dựng theo mục "Câu hỏi thường gặp" dưới đây.
+- **Bảng so sánh** (`S1`).
+
+---
+
+## Câu hỏi thường gặp
+
+**Accordion trong MỘT khung trắng, đóng hết lúc vào trang**, một cột giữa trang.
+Người ta đến trang giá để chọn gói; FAQ là chỗ tra khi còn vướng, nên chỉ cần thấy
+danh sách câu hỏi, bấm câu nào mở câu đó. Bung hết thì FAQ dài gần bằng dãy gói
+(chủ dự án thấy "bung ra hết"). Hầu hết trang giá đều dùng accordion ở
+đây. Đây là ngoại lệ của `I17`: FAQ ở trang giá luôn accordion, dù dưới 6 câu.
+
+Mỗi câu là một mục accordion, dựng đúng theo `../components/accordion.md` (padding,
+chuyển động, hover, khung, cách kiểm đều nằm ở đó). Phần riêng của trang giá:
+
+```tsx
+// faq-section.tsx
+<section className="mx-auto mt-16 max-w-3xl sm:mt-20">
+  <h2 className="text-center font-heading text-xl font-bold text-foreground">Câu hỏi thường gặp</h2>
+
+  <div className="mt-6 divide-y divide-border overflow-hidden rounded-2xl border border-border bg-surface">
+    {faqItems.map((item) => (
+      <AccordionItem key={item.question} title={item.question}>{item.answer}</AccordionItem>
+    ))}
+  </div>
+</section>
+```
+
+- **Khung `max-w-3xl` giữa trang**, đủ để câu hỏi dài nhất vừa một dòng ở desktop. Đừng
+  `max-w-lg` (512px, chọn để câu trả lời ≤ 75 ký tự): câu hỏi "Đang học gói Tự học,
+  muốn lên gói Pro thì phần đã học có mất không?" xuống dòng khi hàng còn trống, và khung
+  chỉ rộng nửa dãy card. Đo:
+  `max-w-2xl` câu hỏi một dòng, câu trả lời 2 dòng ~89 ký tự; `max-w-3xl` cả hai một dòng.
+  Câu trả lời FAQ là 1–2 câu, đọc một hơi, không phải đoạn văn nên không tính trần `T11`.
+- **Tiêu đề `font-heading font-bold`, căn giữa, cùng họ chữ với tên trang.** Trang trình
+  diễn có font tiêu đề thì mọi tiêu đề cấp trang (`h1`, `h2` của từng phần) dùng chung nó;
+  để `h2` font body thì trang có hai tiêu đề lớn hai kiểu chữ. Tên
+  gói, câu hỏi vẫn font body (`T2`).
+- **Cách dãy gói `mt-16 sm:mt-20`**: phần khác của trang, không phải card thứ tư.
+- **Đóng hết lúc vào trang.**

package/src/claude/skills/ui-ux/references/locked-rules.md

@@ -0,0 +1,35 @@
+# Luật chủ dự án đã chốt
+
+Những luật dưới đây chủ dự án đã xem bản dựng thật rồi mới quyết. **Không lật, không làm
+khác đi**, kể cả khi số đông làm khác hay có lý lẽ nghe hợp lý. Muốn đổi thì hỏi chủ dự án
+trước.
+
+Cột **"Lý lẽ đã bị bác"** ghi đúng những câu từng dẫn tới bản sai. Viết spec mà thấy mình
+đang nghĩ ra một câu giống vậy thì dừng lại: đó là lỗi cũ quay lại.
+
+**Khi nào mở file này:** viết mục mới hoặc sửa spec có nói tới màu nút, mức nặng của nút
+(`primary`, `outline`, `secondary`, đỏ, trung tính), bo góc, cỡ chữ tiêu đề, hover, focus,
+chuyển động. Sửa skill xong chạy `node skills/ui-ux/scripts/lint-skill.mjs` (từ gốc repo).
+
+| # | Luật đã chốt | Chốt ngày | Lý lẽ đã bị bác | Luật gốc |
+| --- | --- | --- | --- | --- |
+| 1 | Việc nguy hiểm tô đỏ theo ba câu của `I4` (mất dữ liệu, kết thúc thứ đang chạy, cắt quyền). Đăng xuất, đăng xuất hàng loạt, huỷ gói đều đỏ | 23/09, 26/09, 27/09/2026 | "Không mất dữ liệu nên trung tính". "Vẫn dùng được tới hết kỳ nên không đỏ". "Nhiều app để trung tính" | `rules-state.md` `I4` |
+| 2 | Nút nguy hiểm là nền mờ `rose-500/10`, chữ `rose-700`, luôn hiện | 21/09/2026 | Đỏ đặc `bg-rose-500 text-white`. Viền đỏ | `rules-state.md` `I4`, `components/button.md` |
+| 3 | Hộp xác nhận việc nguy hiểm đỏ như hộp xoá. Hộp trung tính (icon xám, nút `primary`) chỉ khi ba câu của `I4` đều "không" | 26/09, 27/09/2026 | Lấy hộp đăng xuất hàng loạt, hộp huỷ gói làm ví dụ cho hộp trung tính | `layouts/overlay.md` |
+| 4 | `outline` là nút mặc định; `secondary` không thay nó | 21/09/2026 | Đổi mặc định sang `secondary` cho "có mặt rõ hơn" | `components/button.md` |
+| 5 | Nút viền rê vào chỉ đổi nền `--button-hover` (`#f1f1f3`), viền giữ nguyên | 26/09/2026 | Viền đậm lên `foreground/20`. `hover:bg-background` (tan vào nền trang) | `components/button.md` |
+| 6 | Nút lọc dạng dropdown ngoài form không có hover, như ô Select | 25/09/2026 | Mượn hover nút viền: tô nền xám, rồi viền đậm lên | `components/choice-controls.md` |
+| 7 | Tab trạng thái dưới `sm` thành nút dropdown có nhãn "Trạng thái:" | 25/09/2026 | Nút chỉ ghi "Tất cả · 32", không nhãn | `layouts/app.md`, "Bảng dữ liệu" |
+| 8 | Dòng bảng tick checkbox: đã chọn và đang rê cùng một nền mờ (`I10`). Chỉ dòng bảng: sidebar và cây thư mục rê `hover:bg-item-hover`, đang chọn `bg-secondary` + `font-medium`, không màu nhấn, không viền (đổi 29/09/2026) | 23/09, 29/09/2026 | "Mỗi trạng thái phải một nền khác" cho dòng bảng. Áp "cùng một nền" sang sidebar, cây thư mục. Tô màu nhấn mục sidebar đang chọn | `principles.md` `N2`, `layouts/app.md`, `components/tree.md` |
+| 9 | Focus ô nhập: viền `--border-focus` + `ring-2` mờ (`I13`) | 21/09/2026 | Tăng độ đậm ring thành vòng viền thứ hai | `components/input.md` |
+| 10 | Bo góc theo chiều cao: từ 40px trở lên tối thiểu 12px, dưới 40px thì 8px | 21/09/2026 | Chọn theo tên loại ("mục menu thì 8px") | `rules-form.md` |
+| 11 | Tên trang `xl`, `2xl` chỉ cho hero | 16/09/2026 | Tên trang `2xl` ở desktop | `budgets.md` |
+| 12 | Panel trượt 500ms vào, 350ms ra | 23/09/2026 | Rút ngắn 300/200ms cho "nhanh hơn". `linear` | `layouts/overlay.md` |
+| 13 | Thanh cuộn ẩn bằng màu trong suốt, giữ bề rộng 4px | 08/09/2026 | `scrollbar-width: none` (nội dung bị đẩy ngang khi thanh hiện) | `tokens.css` |
+| 14 | Hàng tab cuộn ngang ở màn hẹp: chỉ gợi ý cho người dùng chọn cách báo "còn nữa", không áp sẵn | 25/09/2026 | Tự áp dropdown hoặc thanh cuộn luôn hiện | `responsive.md` |
+| 15 | Dấu `*` trường bắt buộc tô đỏ | 25/09/2026 | Dấu `*` xám cho "đỡ ồn" | `rules-color.md`, `principles.md` |
+| 16 | Không vẽ vòng focus ở nút, link, tab, chip, checkbox, card, dòng; chỉ trả lại khi đề yêu cầu accessibility (`I14`). Ngoại lệ lúc soi: dự án tự vẽ vòng focus mà một chỗ Tab tới không thấy gì thì báo Lệch hệ, sửa theo vòng của họ | 28/09, 30/09/2026 | "Thiếu vòng focus là trượt WCAG 2.4.7", thêm lại khi soi thấy Tab tới không có dấu | `rules-state.md` `I13` |
+| 17 | Mặc định là nhánh `U` (brief, wireframe, chọn, dựng) cho mọi đề dựng hay làm lại một màn, tiếng Việt hay tiếng Anh; lối khác chỉ khi đề nói rõ | 29/09/2026 | "Dựng luôn một bố cục mặc định, không hỏi" cho đề chỉ nói "dựng màn X" | `SKILL.md` câu 1, `design-process.md` |
+| 18 | Đường kẻ dưới header và dưới đầu sidebar dùng `border-border`, cùng màu vạch chia trong menu, popover | 01/10/2026 | "`--border` trên nền trắng gần như tàng hình, đường chia mất tác dụng" nên dùng `--border-strong` (luật 21/09/2026) | `layouts/app.md` "Khung app có sidebar", `rules-color.md` |
+
+Chủ dự án chốt thêm luật nào thì thêm một dòng ở đây, cùng lúc với chỗ sửa ở luật gốc.