@haposoft/cafekit 0.16.6 → 0.18.0

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

@@ -0,0 +1,198 @@
+# Đang tải (loading)
+
+Câu cần hỏi trước khi vẽ: **người dùng đang chờ cái gì, và trên màn đã có gì rồi.**
+Mỗi ca một hình. Lỗi hay gặp nhất của AI là dùng một hình cho mọi ca: cứ chờ là
+skeleton, cứ bấm là spinner.
+
+| Ca | Hình |
+| --- | --- |
+| Tải lần đầu, dữ liệu qua mạng | Khung chờ đúng hình (mục dưới) |
+| Tải lần đầu, dữ liệu đọc từ máy (localStorage, state sẵn có) | Không khung chờ, không spinner. Một dòng chữ mờ như `empty-state.md`, chỉ khác chữ |
+| **Tải lần hai**: đổi lọc, đổi trang, đổi tab, gõ tìm | **Giữ dữ liệu cũ** + thanh mảnh trên đầu khung |
+| **Đổi ngay trên màn**: toggle, tick, kéo thẻ, đổi thứ tự | Đổi luôn, không spinner. Lỗi thì trả lại như cũ + toast |
+| Bấm nút gửi, lưu, tạo | Spinner thế chỗ icon trong nút (`button.md`) |
+| Tự lưu (cài đặt, trình soạn thảo) | Dấu "Đang lưu… / Đã lưu" cạnh chỗ vừa đổi |
+| "Xem thêm" cuối danh sách | Spinner đè giữa nút, nút giữ bề rộng (`timeline.md`) |
+| **Việc chạy lâu**: xuất tệp, nhập dữ liệu | Có tiến độ, chạy nền, xong báo toast |
+| Tải tệp lên | `file-upload.md` |
+| AI đang trả lời | `chat.md` |
+
+Không bao giờ một vòng xoay giữa màn thay cho cả trang (`I19`). Chuyển trang thì
+header, sidebar đứng yên, chỉ vùng nội dung thành khung chờ.
+
+---
+
+## Khung chờ (dữ liệu qua mạng, lần đầu)
+
+Theo `I19`: khung chờ **đúng hình** dòng thật, để lúc dữ liệu về trang không nhảy.
+
+```html
+<ul aria-busy="true" class="divide-y divide-border">
+  <li class="flex items-center gap-3 px-4 py-3">   <!-- cùng padding, cùng divide với dòng thật -->
+    <div class="size-8 shrink-0 animate-pulse rounded-full bg-foreground/5 motion-reduce:animate-none"></div>
+    <div class="min-w-0 flex-1 space-y-2">
+      <div class="h-3 w-2/5 animate-pulse rounded-full bg-foreground/5 motion-reduce:animate-none"></div>
+      <div class="h-3 w-1/4 animate-pulse rounded-full bg-foreground/5 motion-reduce:animate-none"></div>
+    </div>
+    <div class="h-3 w-16 animate-pulse rounded-full bg-foreground/5 motion-reduce:animate-none"></div>
+  </li>
+</ul>
+<span class="sr-only" role="status">Đang tải danh sách khách hàng</span>
+```
+
+- **Vệt chờ là lớp phủ `bg-foreground/5`, không `bg-background`** (`M21`). Bản sáng hai cách ra cùng một màu
+  (`#f4f4f4` / `#f4f4f6` trên card trắng); bản tối `bg-background` tối hơn card, cả khung chờ thành dãy lỗ đen
+  khoét xuống, còn lớp phủ thì sáng lên mờ như mọi vùng tô khác.
+- **Mượn nguyên khuôn dòng thật**: cùng cỡ avatar, cùng padding, cùng đường chia `divide-y`. Dòng thật có đường chia mà khung chờ không có thì lúc dữ liệu về vẫn thấy cả khối đổi hình.
+- **Thanh chữ cao `h-3`, chiều dài lệch nhau** giữa các dòng (`w-2/5`, `w-1/2`, `w-1/3`…). Dài bằng nhau thì trông như sọc kẻ, không giống chữ.
+- Số dòng bằng số dòng mỗi trang, hoặc đủ lấp khung, không bịa 3 dòng cho một khung 10 dòng.
+- **Bảng nhóm thì khung chờ bắt đầu bằng một hàng nhóm**, không thẳng vào dòng dữ liệu, kẻo lúc dữ liệu về cả bảng tụt một hàng (`../layouts/app.md`, mục Bảng nhóm theo trạng thái).
+- `animate-pulse` luôn đi kèm `motion-reduce:animate-none`. Trình đọc màn hình không thấy khung, nên phải có `aria-busy` và một câu `sr-only`.
+- **Không bao giờ hiện câu rỗng trong lúc chờ.** "Chưa có khách hàng nào" chớp lên rồi danh sách hiện ra là người dùng vừa được báo sai một lần. Chưa biết rỗng hay không thì là đang tải.
+
+---
+
+## Tải lần hai: giữ dữ liệu cũ
+
+Đổi lọc, đổi trang, đổi tab, gõ tìm, kéo lại: trên màn **đã có dữ liệu**. Thay cả bảng
+bằng khung chờ lần nữa là xoá mất thứ người dùng đang nhìn, rồi vẽ lại; mỗi phím gõ
+trong ô tìm là bảng chớp một lần. Giữ nguyên dữ liệu cũ tới khi dữ liệu mới về, chỉ
+báo "đang chạy" bằng một thanh mảnh chạy ở mép trên khung.
+
+```html
+<div aria-busy="true" class="relative overflow-hidden rounded-2xl border border-border">
+  <!-- Thanh chạy: chỉ có khi đang tải lại -->
+  <div class="absolute inset-x-0 top-0 h-0.5 overflow-hidden">
+    <div class="h-full w-1/3 animate-progress-slide bg-primary motion-reduce:animate-pulse"></div>
+  </div>
+  <table>…dữ liệu cũ, giữ nguyên…</table>
+</div>
+<span class="sr-only" role="status">Đang tải kết quả</span>
+```
+
+```css
+@theme {
+  --animate-progress-slide: progress-slide 1.2s ease-in-out infinite;
+  @keyframes progress-slide {
+    from { translate: -100% 0; }
+    to { translate: 300% 0; }
+  }
+}
+```
+
+- **Dữ liệu cũ không mờ, không khoá.** Mờ đi là chữ tụt dưới ngưỡng tương phản và đọc ra là "bị khoá"; người dùng vẫn đọc, vẫn chọn được dòng cũ trong lúc chờ.
+- **Thanh nằm trong khung đang tải**, không ở đỉnh trang: đổi lọc của bảng thì thanh ở mép bảng, mắt đang nhìn đúng chỗ đó. Thanh đè lên viền trên, không chèn thêm chỗ (`N1`).
+- **Thứ vừa bấm đổi ngay**: chip lọc đã chọn, tab đã chuyển, số trang đã tô. Chỉ phần dữ liệu là chờ.
+- Kết quả về là 0 dòng thì sang câu rỗng (`empty-state.md`). **Tải lần hai hỏng thì giữ dữ liệu cũ, báo bằng toast lỗi có Thử lại** (`../layouts/overlay.md`); khối "Không tải được…" của `empty-state.md` chỉ dành cho khi chưa có gì trên màn.
+- **Hỏng thì tab, chip, số trang trả về giá trị khớp dữ liệu đang hiện**, như ca đổi ngay trên màn. Để tab "Đang giao dịch 19" sáng trên một bảng toàn khách của "Tất cả", chân bảng ghi 32, là màn tự nói sai; câu giải thích "bảng đang hiện kết quả trước đó" là vá chỗ sai đó bằng chữ. Toast nói cái chưa tải được ("Chưa tải được khách hàng Đang giao dịch"), Thử lại là bấm lại đúng lựa chọn đó. **Riêng ô tìm giữ nguyên chữ đã gõ**, không xoá thứ người dùng gõ; toast "Chưa tìm được “ng”" + Thử lại.
+- Gõ tìm thì kết quả về sau mới thắng: phản hồi của "ng" về sau phản hồi của "nguyen" không được đè lên. Huỷ hay bỏ phản hồi cũ là logic người dùng (`N10`), skill chỉ nhắc.
+- Dự án có React Query, SWR thì đây là `placeholderData: keepPreviousData` / `keepPreviousData`, thanh mảnh hiện theo `isFetching`; React thuần thì `useTransition`, thanh theo `isPending`.
+
+---
+
+## Thời điểm hiện: chờ 300ms, đã hiện thì giữ 500ms
+
+Dữ liệu về trong 200ms mà vẫn vẽ khung chờ là màn **chớp** một cái: khung hiện rồi
+biến ngay, nhìn như lỗi. Ngược lại, khung vừa hiện được 50ms đã biến cũng chớp.
+
+- **Chưa tới 300ms thì chưa vẽ gì**: khung giữ đúng chiều cao, trống. Không câu rỗng, không khung chờ.
+- **Đã hiện thì giữ tối thiểu 500ms**, kể cả dữ liệu về ngay sau đó.
+- Áp cho khung chờ, thanh mảnh tải lần hai, và chữ "Đang lưu…". **Không áp cho spinner trong nút**: spinner thế chỗ icon nên không xô gì, và người vừa bấm cần thấy nút đã nhận.
+
+```ts
+// Hiện cờ đang tải sau delayMs; đã hiện thì giữ ít nhất minVisibleMs.
+export function useDelayedLoading(isLoading: boolean, delayMs = 300, minVisibleMs = 500) {
+  const [isVisible, setIsVisible] = useState(false);
+  const shownAtRef = useRef(0);
+
+  useEffect(() => {
+    if (isLoading) {
+      if (isVisible) return;
+
+      const showTimer = window.setTimeout(() => {
+        shownAtRef.current = Date.now();
+        setIsVisible(true);
+      }, delayMs);
+      return () => window.clearTimeout(showTimer);
+    }
+
+    if (!isVisible) return;
+
+    const remainingMs = Math.max(0, minVisibleMs - (Date.now() - shownAtRef.current));
+    const hideTimer = window.setTimeout(() => setIsVisible(false), remainingMs);
+    return () => window.clearTimeout(hideTimer);
+  }, [isLoading, isVisible, delayMs, minVisibleMs]);
+
+  return isVisible;
+}
+```
+
+Lúc giữ 500ms mà dữ liệu đã về thì vẫn hiện dữ liệu ngay; chỉ thanh mảnh hay chữ
+"Đang lưu…" ở lại cho đủ giờ. Khung chờ lần đầu thì đợi đủ giờ rồi mới thay bằng dữ liệu:
+
+```tsx
+const isSkeletonVisible = useDelayedLoading(isLoading);
+
+{isSkeletonVisible ? <CustomerListSkeleton /> : isLoading ? <div className="min-h-96" /> : <CustomerList />}
+```
+
+---
+
+## Đổi ngay trên màn
+
+Toggle, tick việc xong, kéo thẻ sang cột khác, đổi thứ tự, gắn nhãn, ghim: **đổi
+luôn trên màn lúc bấm**, không spinner, không khoá điều khiển trong lúc chờ máy chủ.
+Đây là việc nhỏ, gần như luôn thành công, và người dùng thường bấm liền mấy cái.
+
+- **Lỗi thì trả lại như cũ** (công tắc gạt về, thẻ về cột cũ, đúng vị trí cũ) **kèm toast lỗi** nói cái gì chưa lưu được và có Thử lại: "Chưa chuyển được 'Sửa trang thanh toán' sang Đang làm". Trả lại im lặng thì người dùng tưởng mình bấm trượt. Tên việc dài thì cắt ~30 ký tự + `…` (`../layouts/overlay.md`, Toast), dòng mô tả nói thẻ đang nằm đâu ("Thẻ đã về lại cột Cần làm").
+- Toast lỗi theo `../layouts/overlay.md`: không tự tắt, `role="alert"`. Chỗ đã có dấu tự lưu (hàng cài đặt) thì câu lỗi nằm ở dấu đó, không thêm toast (mục dưới).
+- **Không dùng cho việc không đổi lại được hoặc máy chủ phải quyết**: thanh toán, gửi lời mời, xoá vĩnh viễn, tạo bản ghi mà màn kế tiếp cần mã của nó. Mấy việc đó là nút đang xử lý (`button.md`).
+- Gạt thì đổi tại chỗ, có xảy ra hay không là logic (`N10`); skill chỉ dựng đủ hai hình: đã đổi, và đã trả lại + toast.
+
+---
+
+## Tự lưu: "Đang lưu… / Đã lưu"
+
+Trang cài đặt không nút Lưu tổng (`../layouts/app.md`) và trình soạn thảo tự lưu cần
+một dấu nhỏ nói đã lưu chưa, đặt **cạnh chỗ vừa đổi**: cạnh nhãn của hàng cài đặt,
+cạnh tiêu đề tài liệu ở header trình soạn thảo.
+
+```html
+<span role="status" class="inline-flex items-center gap-1 text-xs text-muted">
+  <!-- Đang lưu: chỉ chữ -->
+  Đang lưu…
+  <!-- Đã lưu: <i data-lucide="check" class="size-3.5"></i> Đã lưu -->
+</span>
+```
+
+| Trạng thái | Hình |
+| --- | --- |
+| Đang lưu | "Đang lưu…" `text-xs text-muted`, không spinner. Hiện theo luật 300ms |
+| Đã lưu | icon `check` `size-3.5` + "Đã lưu", cùng màu `text-muted`, không xanh lá. Cài đặt: tắt sau ~2 giây. Trình soạn thảo: ở lại, thành "Đã lưu lúc 14:32" |
+| Không lưu được | **Điều khiển trả về giá trị đã lưu** (công tắc gạt về, select về lựa chọn cũ), cạnh nhãn "Chưa lưu được" `text-red-600` + link chữ "Thử lại" (áp lại đúng thay đổi vừa hỏng). Ở lại tới khi lưu được. Không thêm toast: lỗi đã nói tại chỗ (`N3`) |
+
+- **Hỏng mà công tắc vẫn nằm ở vị trí mới thì màn đang nói sai**: công tắc tắt cạnh "Chưa lưu được", người đọc không biết máy chủ đang bật hay tắt. Trả về giá trị đã lưu, như ca đổi ngay trên màn. **Riêng ô chữ giữ nguyên chữ đã gõ**, không xoá thứ người dùng gõ.
+- **Không xanh lá cho "Đã lưu"**: lưu là việc thường xuyên, như dấu `Check` xám của bước công cụ trong `chat.md`. Xanh lá để dành cho trạng thái "đang ổn" (`rules-color.md`).
+- Dấu nằm trong cùng dòng với nhãn, `flex-wrap`, đổi chữ thì chỉ nó dài ra, không đẩy điều khiển (`N1`).
+- Công tắc mở luồng (quét mã, nhập mật khẩu) thì không có dấu này, xem `choice-controls.md`.
+
+---
+
+## Việc chạy lâu
+
+Xuất tệp, nhập dữ liệu, tạo báo cáo, chạy hàng loạt: vài giây tới vài phút. Ba điều:
+
+1. **Có tiến độ.** Biết tổng thì thanh có số: "Đã nhập 340 / 1.200 dòng", thanh `h-2` `role="progressbar"` (`charts.md`, "Thanh tiến độ đứng riêng"). Không biết tổng thì chữ nói đang làm bước nào ("Đang gom đơn tháng 9…"), không thanh chạy vô tận.
+2. **Chạy nền.** Không khoá cả màn bằng modal chờ. Bấm xong thì toast tiến độ ở lại tới khi xong: tiêu đề ngắn "Đang xuất 1.240 đơn", dòng dưới "340 / 1.240 · xong sẽ báo bạn". Tiêu đề dài kiểu "Đang xuất 1.240 đơn, xong sẽ báo bạn" ở màn hẹp rớt một chữ xuống dòng hai (`T10`). Người dùng làm việc khác. Màn nhập dữ liệu có modal thì đóng modal được, việc vẫn chạy.
+3. **Xong báo toast, kèm hành động**: "Đã xuất 1.240 đơn" + nút "Tải xuống"; "Đã nhập 1.180 dòng, 20 dòng lỗi" + "Xem dòng lỗi". Hỏng thì toast lỗi có Thử lại.
+
+- Dưới ~3 giây thì không cần chạy nền: nút đang xử lý là đủ (`button.md`).
+- **Nút đã bấm không quay spinner khi toast tiến độ đã hiện** (`N3`): một việc, một chỗ báo đang chạy. Spinner trong nút cộng thanh trong toast là hai tín hiệu cho một việc, mắt không biết nhìn chỗ nào. Nút giữ icon và chữ, không mờ, `aria-disabled` tới khi xong để không ai bấm xuất hai lần (`button.md`, đang xử lý, bỏ phần spinner).
+
+---
+
+## Spinner
+
+- Một hình cho cả app: `LoaderCircle` lucide, `animate-spin motion-reduce:animate-none`, cỡ bằng icon nó thế chỗ (`size-4` trong nút).
+- **Một việc đang chạy, một spinner** (`N3`). Spinner trong nút thì không thêm thanh mảnh, không thêm chữ "Đang gửi…" ở chỗ khác.
+- Spinner chỉ thế chỗ một icon hoặc đè giữa một nút. Không đứng một mình giữa khối thay cho dữ liệu: chỗ đó là khung chờ.

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

@@ -0,0 +1,147 @@
+# Logo sản phẩm ⚑
+
+**Dự án đã có logo thì dùng của họ**, không vẽ lại, không chỉnh (logo là nhận diện, `V1` trong
+`review.md`). File này chỉ dùng khi dự án mới chưa có logo mà màn có chỗ cho logo: đầu sidebar,
+màn xác thực (`layouts/form.md`), trang lỗi đứng riêng (`layouts/app.md`). Việc nhỏ hơn một màn
+mà màn đó không có chỗ cho logo thì không vẽ (`S3`).
+
+Tìm trước khi vẽ:
+
+```bash
+find . -path ./node_modules -prune -o \( -iname "*logo*" -o -iname "*brand*" -o -iname "icon.svg" -o -iname "favicon.svg" \) -print 2>/dev/null | head
+```
+
+**Không tính là đã có logo**: ô chữ cái đầu tên sản phẩm (dấu cũ của skill, tên file kiểu
+`brand-mark`), favicon mặc định của framework (tia sét tím của Vite, logo Next, `favicon.ico` của
+create-react-app). Gặp chúng thì thay theo file này, giữ tên component đang được import.
+
+Logo ở đây là **logo đơn giản cho dự án mới**: một dấu hình học và tên sản phẩm. Không phải bộ
+nhận diện của agency; người dùng có logo thật thì thay vào một chỗ.
+
+---
+
+## Hình: dấu trong ô màu nhấn, tên bên phải
+
+```
+  ╭────╮
+  │ ◐  │  Tên sản phẩm        ô size-8 bo 8px, nền màu nhấn, dấu trắng size-5
+  ╰────╯
+```
+
+- **Dấu là SVG vẽ tay, không phải chữ cái trong ô.** Ô chữ cái đầu là cách của avatar và của
+  logo công ty giả trong dữ liệu mẫu (`S16`); dùng nó cho logo sản phẩm thì đầu sidebar trông
+  như một dòng danh sách, sản phẩm không có mặt.
+- **Không lấy icon lucide làm dấu.** Cùng bộ với icon các mục sidebar ngay bên dưới, logo đọc ra
+  là một mục nav.
+- **viewBox `0 0 24 24`, vẽ trong vùng 4–20**, một đến ba hình cơ bản (tròn, vuông bo, cung,
+  thanh). Khối đặc, hoặc nét `strokeWidth` từ 2.5; không chi tiết nào mảnh hơn 2 đơn vị, vì ở
+  16px (favicon) chúng biến mất.
+- **Một màu, `currentColor`**: không gradient, không bóng, không màu thứ hai. Màu đến từ ô
+  (`bg-primary text-primary-foreground`), nên đổi `--primary` là logo đổi theo, nấc Xám của
+  wireframe và dark mode tự đúng.
+- **Tên sản phẩm** `text-sm font-semibold text-foreground truncate`, cách ô `gap-2.5`, cùng font
+  của app. Không vẽ tên thành SVG, không đổi font riêng cho tên.
+- **Đừng ra hình sáo**: tia sét, ngôi sao lấp lánh, lục giác, khối lập phương, chữ cái trong
+  vòng tròn. Mười app mới thì sáu cái dùng các hình này, người dùng nhìn là biết logo đặt tạm.
+  Cũng đừng ra hình người ta nhận ra ngay là logo của một hãng lớn.
+
+## Ba hướng, nặn từ brief
+
+Lấy tên sản phẩm và việc chính ở `U1`, `U2`. Mỗi hướng một dấu:
+
+| Hướng | Cách nặn | Ví dụ |
+| --- | --- | --- |
+| **1. Chữ đầu dựng bằng khối** (khuyên dùng khi tên ngắn, dễ nhớ) | Chữ cái đầu tên dựng lại từ hình cơ bản, không gõ bằng font: có một khoảng cắt hay một góc lệch để nó thành dấu, không còn là chữ | "Lumen": chữ L từ hai thanh, góc trong là một chấm tròn |
+| **2. Ẩn dụ việc chính** | Một hình gợi việc người dùng làm, trừu tượng hoá tới mức không còn là icon | đặt lịch: hai ô vuông bo lệch nhau; tài chính: ba thanh tăng dần, thanh cuối là nửa tròn |
+| **3. Hai hình ghép** | Hai hình cơ bản chồng hay cắt nhau, phần giao là khoảng trống | vòng tròn bị một hình vuông cắt mất góc |
+
+Ghi một câu vì sao cho mỗi hướng, bám tên hay việc chính, không viết "hiện đại, tối giản".
+
+## Kiểm trước khi đưa
+
+Render dấu ở **16px, 32px, 64px**, trên nền màu nhấn và trên nền trắng (dấu `text-foreground`),
+xem ảnh:
+
+- 16px còn nhận ra hình, không thành một đốm.
+- Ba hướng khác nhau thật khi nhìn nhỏ, không phải một hình xoay ba kiểu.
+- Đặt cạnh icon các mục sidebar không lẫn vào chúng.
+
+Hướng nào hỏng một câu thì vẽ lại hướng đó, không đưa lên wireframe.
+
+## Code
+
+```tsx
+// src/components/product-brand/product-mark.tsx
+import type { ComponentProps } from "react";
+
+// Dấu của sản phẩm. Thay path khi có logo thật.
+export function ProductMark(props: ComponentProps<"svg">) {
+  return (
+    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" {...props}>
+      <path d="M6 4h3.5v12.5H18V20H6z" />
+      <circle cx="15.5" cy="8.5" r="2.5" />
+    </svg>
+  );
+}
+```
+
+```tsx
+// src/components/product-brand/product-brand.tsx
+import { cn } from "@/lib/utils";
+import { ProductMark } from "./product-mark";
+
+interface ProductBrandProps {
+  name: string;
+  className?: string;
+}
+
+export default function ProductBrand({ name, className }: ProductBrandProps) {
+  return (
+    <span className={cn("flex min-w-0 items-center gap-2.5", className)}>
+      <span className="flex size-8 shrink-0 items-center justify-center rounded-lg bg-primary text-primary-foreground">
+        <ProductMark className="size-5" />
+      </span>
+      <span className="truncate text-sm font-semibold text-foreground">{name}</span>
+    </span>
+  );
+}
+```
+
+- Sidebar thu gọn: ô đứng yên, tên bị cắt và mờ đi như chữ các mục (`layouts/app.md`, thu gọn
+  sidebar). Màn xác thực và trang lỗi đứng riêng dùng đúng component này, không vẽ bản thứ hai.
+- **Favicon từ cùng dấu**: một file SVG gồm ô vuông bo nền màu nhấn và dấu trắng (tab trình duyệt
+  sáng hay tối đều thấy). Next.js App Router đặt ở `app/icon.svg`; dự án khác `public/favicon.svg`
+  kèm `<link rel="icon" type="image/svg+xml" href="/favicon.svg">`. Xoá favicon mặc định của
+  framework để không còn hai cái.
+
+## Trong luồng thiết kế
+
+- **Đề xin logo** ("làm logo", "dựng logo", "thay logo", "design a logo"; dòng logo ở câu 1 của
+  `SKILL.md`): vẽ **trang chọn logo** (dưới), dừng chờ chọn. Đây là cổng duy nhất của lối này.
+  Đề có "luôn" ("làm logo luôn") hoặc ghi sẵn hướng thì bỏ trang, dựng thẳng.
+- **Wireframe (`U3`)**: dự án chưa có logo thì thanh công cụ có nhóm **Logo: 1 · 2 · 3** (`?logo=`),
+  đổi dấu ở mọi chỗ có logo trên trang. Người dùng chọn logo cùng lúc chọn phương án, không thêm
+  cổng. Mở không tham số thì hướng khuyên dùng.
+- **Dựng luôn, không wireframe**: vẽ hướng khuyên dùng, không hỏi.
+
+### Trang chọn logo ⚑
+
+Một file `$TMPDIR/evon-design/logo.html`, khung và thanh công cụ như wireframe của `U3`
+(`design-process.md`: Tailwind trình duyệt, token của dự án, thanh sáng một dòng, segmented
+control, khung lý do). Chưa chọn thì không đụng file nào của dự án.
+
+- **Thanh công cụ**: **Logo: 1 · 2 · 3** (`?logo=`, hướng khuyên dùng có chấm màu nhấn) ·
+  **Màu** (công tắc: tắt là nấc Xám, bật là màu nhấn của dự án) · Nhấn (dự án chưa có màu brand,
+  như `U3`).
+- **Khung lý do**: tên hướng, nhãn "Khuyên dùng", một câu vì sao bám tên hay việc chính.
+- **Mỗi hướng hiện dấu ở chỗ nó sẽ sống**, không hiện một dấu to giữa trang trắng:
+  1. Đầu sidebar thật của dự án (ô, tên, vài mục nav có icon bên dưới), cả bản mở và bản thu gọn.
+  2. Khối logo của màn đăng nhập.
+  3. Một dải tab trình duyệt sáng và một dải tối, favicon 16px cạnh tên trang.
+  4. Hàng cỡ 16, 32, 64px trên nền màu nhấn và trên nền trắng.
+- Chụp ảnh trang ở cả ba hướng, tự xem theo "Kiểm trước khi đưa" (trên) rồi mới gửi.
+- Gửi link bấm được kèm một câu: *"Chọn `1`, `2` hay `3`; trả lời `ok` là dựng hướng khuyên dùng.
+  Muốn sửa một hướng thì nói (ví dụ "2 nhưng bo tròn hơn")."* Người dùng xin sửa thì vẽ lại hướng
+  đó trên cùng trang, gửi lại.
+- **Lúc giao** một dòng trong phần mặc định của `S15`: *"Logo: hướng [n], [một câu vì sao]. Dấu
+  ở `product-mark.tsx`, có logo thật thì thay path ở đó; muốn hướng khác thì nói."*

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

@@ -0,0 +1,43 @@
+# Ô nhập mã OTP
+
+Sáu ô một số, dùng ở màn xác thực email, đăng nhập hai bước. Màn đứng riêng giữa
+trang thì theo card một mình (`M29`) và chiều cao `h-12` của form xác thực
+(`layouts/form.md`).
+
+```html
+<p class="text-sm text-muted">Mã gồm 6 số vừa được gửi tới</p>
+<p class="text-sm font-medium">
+  <!-- In email bằng EmailText (description-list.md), không wrap-anywhere trơn -->
+  tran.anh.tuan@gmail.com
+  <a href="#" class="ml-1 whitespace-nowrap font-normal text-muted underline underline-offset-2 outline-hidden hover:text-foreground">Đổi email</a>
+</p>
+
+<fieldset class="mt-6">
+  <legend class="mb-2 text-sm font-medium">Mã xác thực</legend>
+  <div class="grid grid-cols-6 gap-2 sm:gap-3">
+    <!-- Ô đầu có autocomplete="one-time-code" và maxlength="6": iOS tự điền cả sáu số vào
+         ô đầu, onInput chia lại sang năm ô sau. maxlength="1" thì tự điền bị cắt còn một số. -->
+    <input inputmode="numeric" autocomplete="one-time-code" maxlength="6" aria-label="Số thứ 1 trên 6"
+      class="aspect-square w-full min-w-0 rounded-xl border border-border-strong bg-surface text-center text-2xl font-semibold tabular-nums outline-hidden focus:border-focus focus:ring-2 focus:ring-focus" />
+    <!-- 5 ô còn lại y hệt nhưng maxlength="1", aria-label "Số thứ n trên 6", không có autocomplete -->
+  </div>
+  <!-- Dòng lỗi luôn có mặt, rỗng khi chưa lỗi: giữ chỗ để nút Xác nhận không tụt xuống ngay dưới con trỏ -->
+  <p aria-live="polite" class="mt-2 min-h-4 text-xs text-red-600"></p>
+</fieldset>
+```
+
+- **Viền ô là `--border-strong`**, như mọi ô nhập (`M14`, `N5`), không lấy `--border` nhạt hơn của card.
+- **Ô vuông `aspect-square`, sáu ô chia đều bề ngang**, `min-w-0` để không tràn ở 375px. Số `text-2xl font-semibold tabular-nums`, căn giữa.
+- **Dán cả mã vào ô nào cũng được**, tách ra sáu ô (cần `onPaste` đọc clipboard; dự án có `input-otp` như InputOTP của shadcn thì dùng nó, nó là một ô thật vẽ thành sáu ô và lo sẵn tự điền, dán); gõ xong một số thì con trỏ sang ô sau; Backspace ở ô trống thì lùi về ô trước. Đây là cách ô phản hồi, skill lo (`N9`). Gõ đủ sáu số thì tự gửi hay chờ bấm Xác nhận là logic, người dùng quyết.
+- **Email đích hiện đậm, đủ, không cắt** (`N8`), kèm link **"Đổi email"**: gõ nhầm email thì đây là lối ra duy nhất (`N6`). **Bấm vào thì về bước trước với dữ liệu đã gõ điền sẵn** (họ tên, email; mật khẩu thì để trống, không mang mật khẩu qua state của router), con trỏ nằm ở ô email vì đó là thứ cần sửa. Về form trống thì người dùng phải gõ lại mọi thứ chỉ để sửa một chữ trong email. Link `whitespace-nowrap`: email dài đẩy nó xuống dòng thì cả cụm "Đổi email" xuống cùng nhau, không bị bẻ thành "Đổi" cuối dòng trên và "email" dòng dưới (`T10`).
+- Mở màn là con trỏ nằm sẵn ở ô đầu.
+- **Đếm ngược gửi lại** dùng `tabular-nums`, không thì chữ số nhảy qua lại mỗi giây (`N1`). Hai trạng thái, dựng đủ cả hai (`N2`):
+  - Đang đếm: "Chưa nhận được mã? Gửi lại sau 0:57", cả câu `text-muted`.
+  - Hết đếm: "Chưa nhận được mã?" `text-muted` + **"Gửi lại mã"** là nút ghost chữ `text-foreground font-medium`, có hover. Đừng để nó xám như lúc đang đếm, trông như vẫn còn khoá (`I8`).
+  - **Bấm "Gửi lại mã" thì báo đã gửi**: dòng đổi thành "Đã gửi mã mới · Gửi lại sau 1:00" trong một vùng `role="status"`, chữ "Đã gửi mã mới" giữ tới khi đếm xong. Xoá sáu ô, con trỏ về ô đầu. Chỉ có bộ đếm chạy lại thì người dùng không chắc bấm đã ăn chưa, và trình đọc màn hình không nghe gì.
+- **Sai mã**: cả sáu ô viền `red-500` (quầng đỏ chỉ ở ô đang focus, `input.md`), câu lỗi dưới hàng ô nói cách sửa: "Mã chưa đúng, kiểm tra lại email mới nhất". **Mã hết hạn**: câu lỗi "Mã đã hết hạn, bấm Gửi lại mã để nhận mã mới", **không** thêm nút trong câu lỗi. Hai lỗi khác nhau thì hai câu khác nhau.
+- **Sau sai mã hoặc mã hết hạn: xoá sáu ô, con trỏ về ô đầu**, câu lỗi và viền đỏ giữ tới khi gõ số đầu tiên. Người dùng gần như luôn gõ lại cả mã (nhìn lại email hoặc lấy mã mới), sáu số cũ còn nằm đó thì phải Backspace sáu lần trước. Cùng cách với ô mật khẩu sau khi đăng nhập sai (`layouts/form.md`). Trang `/states` vẽ trạng thái này bằng sáu ô trống viền đỏ, không phải sáu số đỏ.
+- **Một việc, một nút.** Mã hết hạn thì đếm ngược cũng đã hết, dòng dưới đã có "Gửi lại mã". Thêm "Gửi mã mới" trong câu lỗi là hai nút cùng làm một việc, khác tên, người dùng phải đoán có khác nhau không (`N3`, `N5`).
+- **Dòng lỗi giữ chỗ sẵn** (`min-h-4`, bằng một dòng `text-xs`, rỗng khi chưa lỗi). Câu lỗi `text-xs` như mọi câu lỗi dưới ô (`input.md`, `layouts/form.md`). Người dùng bấm Xác nhận, lỗi hiện ra mà không giữ chỗ thì nút tụt xuống một dòng ngay dưới con trỏ (`N1`).
+- **Bấm Xác nhận khi chưa đủ sáu số thì phải có phản hồi**: câu lỗi "Chưa nhập mã" (chưa gõ số nào) hoặc "Mã còn thiếu số, nhập đủ 6 số", viền đỏ ở **các ô còn trống** (số đã gõ không sai, giữ viền thường), con trỏ nhảy về ô trống đầu tiên. Bấm mà im lặng thì người dùng tưởng nút hỏng.
+- Nút Xác nhận `primary` rộng hết card, `h-12`. Đang kiểm mã thì spinner thay chỗ icon hoặc thêm trước chữ, chữ giữ nguyên (`components/button.md`).

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

@@ -0,0 +1,100 @@
+# Ô nhập số lượng
+
+Số lượng trong giỏ, số ghế, số bản in: một số nguyên nhỏ trong khoảng biết trước.
+Nút − và + hai bên, số ở giữa gõ thẳng được. Số lớn hoặc có phần thập phân (giá,
+cân nặng) thì dùng ô nhập thường (`input.md`), không dùng khuôn này.
+
+```tsx
+<div
+  className={cn(
+    // Mượn nguyên class của ô nhập (viền, nền, bo, focus, lỗi, cao h-11 md:h-10),
+    // bỏ padding ngang, ôm vừa nội dung. Khung đổi viền khi ô số bên trong focus.
+    getFieldControlClasses(hasError, true),
+    "inline-flex h-11 w-fit items-stretch overflow-hidden px-0 md:h-10",
+    isDisabled && "cursor-not-allowed bg-background text-muted",
+  )}
+>
+  <Button
+    variant="ghost"
+    aria-label="Giảm số lượng"
+    aria-controls={id}
+    tabIndex={-1}
+    disabled={isDecreaseDisabled}
+    onMouseDown={(event) => event.preventDefault()}
+    onClick={() => handleStep(-1)}
+    className="group h-full w-11 shrink-0 rounded-none p-0 hover:bg-transparent md:w-10"
+  >
+    {/* Vùng bấm là cả ô cao (44px ở màn hẹp), nền rê chỉ là ô vuông bo thụt vào. */}
+    <span className="grid size-8 place-items-center rounded-lg text-muted transition-colors group-enabled:group-hover:bg-foreground/5 group-enabled:group-hover:text-foreground">
+      <Minus className="size-4" aria-hidden />
+    </span>
+  </Button>
+
+  <input
+    id={id}
+    type="text"
+    inputMode="numeric"
+    role="spinbutton"
+    aria-valuemin={min}
+    aria-valuemax={max}
+    aria-valuenow={value}
+    aria-invalid={hasError || undefined}
+    aria-describedby={describedById}
+    autoComplete="off"
+    // Nhiều hơn số chữ số của max đúng một: gõ hay dán quá tay thì vẫn kéo về max.
+    maxLength={String(max).length + 1}
+    disabled={isDisabled}
+    className="w-12 min-w-0 bg-transparent text-center tabular-nums outline-hidden disabled:cursor-not-allowed"
+  />
+
+  {/* Nút + y hệt nút −, icon Plus */}
+</div>
+```
+
+## Hình
+
+- **Một khung duy nhất, viền của ô nhập** (`border-border-strong`, `rounded-xl`,
+  focus viền nhấn + quầng mờ khi ô số bên trong focus). Không kẻ vạch dọc giữa nút và số:
+  thêm hai đường chia là thêm tín hiệu cho việc ba phần đã tự rõ (`N3`).
+- **Nền rê của nút − + là ô vuông `size-8 rounded-lg` thụt vào giữa ô**, cùng khuôn nút
+  xoá trong ô tìm (`input.md`, `N5`). **Không** cho nền rê phủ kín cả khúc cao từ viền tới
+  viền: nền đó cắt ngang lưng chừng khung, không vạch chia nào đỡ mép trong, một bên vuông
+  thành một bên theo góc bo, trông như ô bị khuyết một mảng. Vùng **bấm** vẫn là cả khúc cao, `w-11` màn hẹp, `md:w-10` (`N9`); chỉ
+  phần **nhìn thấy** là thụt vào.
+- Icon `Minus` / `Plus` `size-4`, `text-muted`, rê vào đậm lên `text-foreground`.
+- Tới đầu nào thì nút phía đó `disabled`: mờ `opacity-50`, con trỏ cấm, rê không đổi nền.
+  Nút giữ chỗ, không ẩn (`N1`).
+- Số `tabular-nums`, căn giữa, ô số `w-12` đủ hai ba chữ số.
+- **Bị khoá**: cả khung chìm xuống `bg-background`, số `text-muted`, hai nút mờ; lý do
+  khoá nói ngay dưới ô như ô nhập thường.
+
+## Hành vi
+
+- `type="text" inputMode="numeric" role="spinbutton"`, **không `type="number"`**: ô số của
+  trình duyệt tự vẽ mũi tên lên xuống chồng lên hai nút, và nhận cả `1e2`, `-3`.
+- **Số gõ vào chỉ áp khi rời ô hoặc bấm Enter.** Gõ dở "9" trong "99" mà đã áp thì nơi dùng
+  tính lại tiền theo từng phím. Ô gõ trống rồi rời đi thì **giữ số cũ**, không tự điền `min`
+  (`N7`). Số ngoài khoảng thì kéo về trong khoảng khi áp.
+- Đang gõ dở mà bấm + thì cộng vào số đang gõ, không vào số cũ.
+- **`maxLength` bằng số chữ số của `max` cộng một**, không bằng đúng số chữ số. Bằng đúng
+  thì trình duyệt cắt bớt chữ số thừa trước khi ô kịp kéo về: kho còn 8 mà gõ 20 ra 2, ô
+  tới 99 mà dán 150 ra 15, một số sai lặng lẽ thay vì số tối đa. Thêm một chữ số thì số
+  bị cắt vẫn luôn lớn hơn `max`, và kéo về đúng `max`.
+- Phím trong ô theo mẫu spinbutton: mũi tên lên xuống đổi 1, PageUp/PageDown đổi 10,
+  Home/End về `min`/`max`.
+- Hai nút `tabIndex={-1}`: ô số đã đổi được bằng phím, Tab qua ba điểm dừng cho một ô là
+  thừa. `onMouseDown` chặn mặc định để bấm − + không kéo tiêu điểm ra khỏi ô đang gõ,
+  và trên điện thoại bàn phím không bật lên theo.
+
+## Giới hạn và lỗi
+
+- **Giới hạn biết trước là `max`, không phải lỗi.** Kho còn 8 thì `max={8}`: nút + mờ ở 8,
+  gõ 20 thì về 8, dòng gợi ý dưới ô nói con số thật: *"Còn 8 sản phẩm."* Không để
+  `max={99}` rồi báo lỗi khi người dùng vượt 8: để người ta bấm một nút rồi mới mắng là
+  nút đó không nên bấm được.
+- **Trạng thái lỗi dành cho điều ô không biết trước**: kho giảm sau khi hàng đã nằm trong
+  giỏ, server từ chối lúc đặt. Khi đó `max` đã là 8 mà số đang là 12: viền đỏ, nút + mờ,
+  câu lỗi thay dòng gợi ý và nói cách sửa (*"Kho vừa giảm còn 8, giảm xuống 8 hoặc ít
+  hơn."*). Bấm − một lần thì về thẳng 8.
+- Dòng gợi ý nói giới hạn thật của thứ đang mua, không phải khoảng kỹ thuật chung chung
+  ("Từ 1 đến 99"). Không có giới hạn đáng nói thì không có dòng gợi ý.

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

@@ -0,0 +1,16 @@
+# Thanh trượt khoảng giá (range slider)
+
+Lọc theo một khoảng số: giá, diện tích, số lượng. Gồm **thanh trượt hai tay cầm
++ hai ô nhập "Từ" / "Đến"**. Ô nhập theo `input.md`, dòng 0 kết quả theo
+`empty-state.md`.
+
+- **Luôn có hai ô nhập đi kèm thanh trượt.** Thanh trượt đi nhanh theo bậc, ô nhập là đường vào thứ hai và là chỗ đặt số lẻ mà bậc trượt không tới (7.350.000). Hai ô `tabular-nums`, `text-base` ở mobile (iOS phóng to trang khi ô dưới 16px), hậu tố `đ` xám nằm trong ô, nhãn "Từ" / "Đến" ở trên.
+- **Số trong ô chỉ áp khi rời ô hoặc bấm Enter**, không áp theo từng ký tự: gõ dở "5" trong "5.000.000" mà áp ngay thì đầu kia bị kéo theo, và danh sách nhảy loạn (`N7`).
+- **Tay cầm `size-5`, viền 2px, nhưng vùng bấm 44×44** (`before:-inset-3.5`, neo theo *border box* — `-inset-3` chỉ ra 40px vì viền đã ăn 4px; số âm giữ có chủ ý, `N11` bước 4: không có cách dương nào nới vùng bấm mà giữ tay cầm 20px, comment ngay trên dòng). **Cả dải rãnh cao 44px** (`h-11`) và bấm vào rãnh thì tay cầm gần nhất chạy tới, nên trên điện thoại không phải nhắm trúng vòng nhỏ (`N9`).
+- **Vùng kéo `touch-none`**: chạm vào dải này thì không cuộn trang theo. Đây là đánh đổi có chủ ý của dải 44px.
+- **Hai tay cầm không đổi chỗ cho nhau.** Kéo sát thì chúng chạm nhau và dừng (Từ = Đến), không vượt qua. Lúc đang chồng nhau, bấm phím sang phải là tay cầm phải đi, sang trái là tay cầm trái đi.
+- **Bàn phím** (`N9`): Tab tới từng tay cầm, mũi tên đi một bậc, PageUp/PageDown đi bậc lớn, Home/End về hai đầu. Sau khi kéo, tiêu điểm ở đúng tay cầm vừa kéo.
+- **Hai đầu rãnh có nhãn giá trị nhỏ nhất và lớn nhất** (`0 đ`, `50.000.000 đ`), `text-xs text-muted`.
+- **Lọc ra 0 kết quả không tô đỏ gì cả** (`M30`, `empty-state.md`): một dòng `text-sm text-muted` ở chỗ đáng lẽ có danh sách, nói số cụ thể và cách nới lọc ("Không có sản phẩm nào từ 47.500.000 đ trở lên. Đắt nhất đang bán là 42.900.000 đ, hạ giá Từ xuống để xem thêm"). Dòng đó và dòng đếm kết quả cùng `py-6` nên khối không co giãn khi đổi qua lại (`N1`).
+- **Khoá**: rãnh, tay cầm và hai ô cùng chìm xuống, con trỏ `not-allowed`, và **nói lý do ngay bên dưới** ("Gói Cơ bản chưa lọc được theo giá") — khoá mà không nói vì sao là bế tắc (`N6`).
+- Ràng buộc nghiệp vụ (khoảng tối thiểu, bước làm tròn) là **logic của người dùng**, skill không tự bịa ra để có thêm một ca lỗi (`N10`).