create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/ui-kit/README.md

@@ -0,0 +1,173 @@
+<div align="center">
+
+# 🎨 @wakii/ui-kit
+
+**A production-grade React design system built AI-first — 90+ components, 31 hooks, tokens-first, motion, dark theme.**
+
+Benchmarked against Ant Design & PrimeReact. Ships with `AGENTS.md` + recipes so AI agents build real features correctly on day one.
+
+[![npm](https://img.shields.io/npm/v/@wakii/ui-kit?logo=npm&label=%40wakii%2Fui-kit)](https://www.npmjs.com/package/@wakii/ui-kit)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Storybook](https://img.shields.io/badge/Storybook-683%20stories-ff4785?logo=storybook&logoColor=white)](https://storybook-static-khaki-two.vercel.app)
+
+## 🤖 Built for AI agents — not just humans
+
+This library is **AI-consumable by design**. Every agent (Claude Code, Codex, ZCode, Cursor…) that opens this repo gets productive immediately:
+
+| Mechanism | What it does for AI |
+|---|---|
+| **[`AGENTS.md`](../../AGENTS.md)** (repo root) | Auto-read by agent CLIs on session start — feature→component map, mandatory rules, anti-patterns. Zero onboarding cost. |
+| **[`docs/ai/recipes.md`](../../docs/ai/recipes.md)** | 10 copy-paste recipes for real features: CRUD pages, login flows, wizards, upload pipelines, dashboards. Agent picks a recipe, renames fields, ships. |
+| **Behavior tests (1290)** | Every component tested by *what it does* (clicks→callbacks, state classes, keyboard flows) — agents verify their work against the same assertions. |
+| **Tokens-first + z-scale + size scale** | Hard constraints instead of conventions: one source of truth CSS vars, `--z-*` layers, `h-8/9/10`. Machine-checkable, no aesthetic guessing. |
+| **Living Storybook (683 stories, [live](https://storybook-static-khaki-two.vercel.app))** | Every state of every component rendered — ground truth for visual verification loops. |
+| **Strict single-button rule & friends** | Sharp opinions (no dividers on split buttons, focus-ring standard) so agents converge on ONE correct output, not five variants. |
+
+**Dogfooded by the multi-agent workflow itself**: this library was audited, restyled and completed by *5 coordinated AI terminals in parallel* (coordinator + workers pattern), gated by pixel-level automated verification. The AI-facing docs, checklists and recipes in this repo are the same ones those agents used.
+
+> Practical loop that works today: agent reads `AGENTS.md` → picks recipe → implements → runs `vitest` (1290 tests catch wiring mistakes) → checks Storybook for visual truth → done.
+
+[![Tests](https://img.shields.io/badge/tests-1290%20passing-brightgreen)](#-quality)
+[![React](https://img.shields.io/badge/React-%E2%89%A518-61dafb?logo=react)](#)
+
+[📖 Live Storybook](https://storybook-static-khaki-two.vercel.app) ·
+[📦 npm](https://www.npmjs.com/package/@wakii/ui-kit) ·
+[🏠 GitHub](https://github.com/wakii-dev/architecture-overview) ·
+[📚 Full docs](./USAGE.md)
+
+</div>
+
+---
+
+## ✨ Why @wakii/ui-kit
+
+| | |
+|---|---|
+| 🧩 **90+ components** | From DataTable with **virtual scroll (5k+ rows)** to Upload Dropzone, TreeSelect, TimePicker, range DatePicker — the parts real apps actually need |
+| 🪝 **31 battle-tested hooks** | `useForm` (zod-powered), `useDebounce`, `useClickAway`, `useInView`, `useScrollProgress`, `useControllableState`… every hook ships behavior tests |
+| 🌗 **Dark theme, done right** | One attribute — `<html data-bp-theme="dark">`. CSS-variable cascade, no flash, no JS, no rebuild — dark tokens polished mirror-antd (alert tints, disabled, shadows), Storybook manager chrome ships both palettes |
+| 🎯 **Tokens-first** | One `tokens.css` is the single source of truth — colors, spacing, radii, shadows, even a **z-index scale**. No hardcoded hex in components |
+| 🚀 **Motion with taste** | Scroll-linked & mount primitives — `Reveal`, `Parallax`, `CountUp`, `Transition` family (Fade/Zoom/Collapse), `ScrollPage` — zero animation deps, respects `prefers-reduced-motion` |
+| ♿ **Real a11y** | Focus trap + focus restore in Modal/Drawer, ARIA roles, full keyboard support — verified in Storybook |
+| 🪶 **Smart weight** | Heavy engines (Swiper, Chart.js, Tiptap, FullCalendar) are optional peers behind subpath exports — your bundle stays lean |
+| 🧪 **1290 behavior tests** | We test clicks → callbacks, state classes, keyboard flows. Not smoke renders |
+
+## 🚀 Quick start
+
+```bash
+npm install @wakii/ui-kit
+```
+
+```tsx
+// one CSS file — tokens + utilities + motion, all compiled
+import '@wakii/ui-kit/styles/ui-kit.css';
+
+import { Button } from '@wakii/ui-kit';
+
+export function App() {
+  return <Button variant="primary" icon="check">Get started</Button>;
+}
+```
+
+### 🌗 Dark mode in one line
+
+```html
+<html data-bp-theme="dark">
+```
+
+### 📝 Forms with zod — schema is the single source of truth
+
+```tsx
+import { z } from 'zod';
+import { useForm, Field, Input } from '@wakii/ui-kit';
+
+const schema = z.object({
+  email: z.string().email('Invalid email'),
+});
+
+const form = useForm({ schema, mode: 'onBlur' });
+
+<Field label="Email" error={form.errors.email} required>
+  <Input
+    value={form.values.email}
+    invalid={!!form.errors.email}
+    onChange={form.handleChange('email')}
+    onBlur={form.handleBlur('email')}
+  />
+</Field>
+```
+
+## 🆕 What's new in 0.4.0
+
+- **Hooks wave — barrel mở trọn**: 12 lifecycle/scroll hooks (`useScrollProgress`, `useInView`, `useInfiniteScroll`, `useControllableState`, `useMeasure`…) + **utils** (`formatCurrency`, `formatRelativeTime`, `chunk`, `groupBy`, `flattenTree`, `getScrollParent`, `cx`…) + `ScrollPage` section-snap — table grouped below.
+- **Dark theme, toàn diện**: dark tokens polish mirror-antd (alert alpha tints, disabled surface, heavier shadows) + `color-scheme` per-theme — Storybook **manager chrome ships both palettes**.
+- **Motion showcases**: `Landing` + `Parallax Landing` (depth-trio hero, parallax lab) + `Cinematic Experience` (glass-nav chaptershell) templates.
+- **Team-OS domain pack**: `PingFeed`, `StagePipeline`, `DebtBoard`, `TeamDashboard`, `InboxThread`.
+- **Chart dark-live**: `useChartColors` probe + `data-bp-theme` observer — charts re-resolve colors on theme toggle, no reload.
+- **Icon set 52** (`filter-fill` / `filter-slash` mới) — glyph characters swept to SVG everywhere. Full detail: [CHANGELOG.md](./CHANGELOG.md).
+
+## 🧩 Component map
+
+| Group | Components |
+|---|---|
+| **Layout & Navigation** | Sidebar (collapsible 200→80px) · Menu / nested Submenu · Breadcrumb · Steps · Tabs · Pagination (antd look) · TabMenu · Menubar · Dropdown · SpeedDial |
+| **Data display** | DataTable (filters, selection kept across pages, **virtual scroll**) · List · Tree · TreeSelect · Descriptions · Timeline · Statistic · Avatar · AvatarGroup · Badge · Tag · Collapse · Card · Image · Galleria · Carousel (Swiper) · Chart · Calendar · DatePicker (range + time + vi/en locale) · TimePicker · Schedule |
+| **Forms** | Input · Textarea · InputNumber · InputMask · InputOTP · Select · AutoComplete · CascadeSelect · Checkbox · Radio · Switch · Slider · Rate · ColorPicker · Upload + UploadDropzone (drag & drop) · Field wrapper · Editor (Tiptap) |
+| **Feedback** | Alert (filled by default + outlined) · Message · Notification · Modal · Drawer · Popconfirm · Progress · Skeleton · Spinner · Result · EmptyState · BlockUI |
+| **Overlay** | Tooltip · Popover · ContextMenu — all on the tokenized `--z-*` scale |
+| **Motion & scroll** | `Reveal` (IntersectionObserver stagger) · `Parallax` (scroll-linked) · `CountUp` · `Transition` family (Fade / Zoom / CollapseTransition) · `Backdrop` · `ScrollPage` (section snap) |
+| **Team-OS domain** | `PingFeed` · `StagePipeline` · `DebtBoard` · `TeamDashboard` · `InboxThread` |
+| **Utils** | `formatCurrency` / `formatBytes` / `formatRelativeTime` / `formatNumber` · `chunk` / `groupBy` / `flattenTree` / `findTreeNode` · `getScrollParent` / `getFocusableElements` / `cx` |
+| **Icons** | `Icon` component — 52 primeicons-derived SVG paths, tree-shakeable |
+
+<details>
+<summary><b>31 Hooks — grouped</b></summary>
+
+| Group | Hooks |
+|---|---|
+| **Forms** | `useForm` (zod) · `useFieldArray` · `useFocusTrap` |
+| **State** | `useLocalStorage` · `useSessionStorage` · `useToggle` · `usePrevious` · `useDefault` · `useControllableState` |
+| **Time** | `useDebounce` · `useThrottle` · `useTimeout` · `useCountdown` |
+| **DOM & viewport** | `useHover` · `useKeyPress` · `useClickAway` · `useMediaQuery` · `useWindowSize` · `useLockBodyScroll` · `useCopyToClipboard` · `useEventListener` · `useMeasure` · `useFullscreen` |
+| **Scroll & lifecycle** | `useScrollProgress` · `useInView` · `useInfiniteScroll` · `useOnlineStatus` · `useTitle` · `useMountEffect` · `useUpdateEffect` · `useIsFirstRender` |
+
+</details>
+
+## 🧩 Templates — full pages composed from the kit
+
+Mỗi template là **1 story sống** trong Storybook — controlled state thật (drag card, filter,
+log giờ đều chạy), không phải mock render. Copy về app, đổi data là dùng.
+
+| Template | Components chính | Story path (`?path=/story/…` trên :6006 hoặc live Storybook) |
+|---|---|---|
+| **Dashboard** (admin) | `Layout` (Sider+Header) · `Row/Col` · `Card`/`Statistic` · `Table` · `Timeline` · `Chart` | `templates-dashboard--dashboard` |
+| **Kanban Project** | `KanbanBoard` (4 cột + WIP limit) · `Segmented`/`Input.Search`/`Select` filter · `Avatar`/`Badge`/`Tag` · `Timesheet` · `message` | `templates-kanban-project--project-board` |
+| **CRUD Table** | `Table` (sort/filter/pagination/expandable/loading) · `Modal` form · `message` | `templates-crud-table--full-demo` |
+| **Auth** (Sign in / Sign up / split) | `useForm` + `zod` · `Field`/`Input`/`Button`/`Checkbox` · `Layout` split | `templates-auth--sign-in` · `--sign-up` · `--split-layout` |
+| **Settings** | `Tabs`/`Segmented` · `Switch`/`Checkbox` · `ColorPicker` (accent live qua `UiKitProvider`) · dark preview | `templates-settings--settings` |
+| **Landing** | `Button` · `Tag` · `Typography` · `Divider` + motion hero | `templates-landing--landing-alive` · `--landing-minimal` |
+| **Parallax Landing** | `Parallax` · `Reveal` · `CountUp`/`Statistic` — depth-trio hero + parallax lab | `templates-parallax-landing--landing` · `--hero-depth` · `--parallax-lab-only` |
+| **Cinematic Experience** | `ChapterShell` glass-nav chapters + hero variants | `templates-cinematic-experience--experience` · `--hero-only` · `--atlas` · `--dark-snow` |
+
+> Trạng thái thật (0.4.0): **8 templates live** — Dashboard, Kanban Project, CRUD Table,
+> Auth, Settings, Landing, Parallax Landing, Cinematic Experience (kèm demo Team-OS
+> components trong story riêng). Recipes copy-chạy: [recipes.md](../../docs/ai/recipes.md).
+
+## 🔬 Quality
+
+- **1290 behavior tests / 163 test files** (clicks → callbacks, state classes, keyboard flows)
+- **Storybook test-runner**: stories render-verified on every push
+- Dark-mode audited across every component (light antd default + dark direction-B)
+- `prefers-reduced-motion` respected globally
+
+## 📚 Documentation
+
+- [USAGE.md](./USAGE.md) — deep dives per group (forms, icons, subpaths, z-index)
+- [CHANGELOG.md](./CHANGELOG.md) / [MIGRATION.md](./MIGRATION.md) — releases & breaking changes (Alert filled, antd Pagination, subpath heavy engines)
+- [parity-matrix.md](../docs/parity-matrix.md) — component-by-component benchmark vs antd/PrimeReact
+
+<div align="center">
+
+**MIT** © [wakii-dev](https://github.com/wakii-dev) — built with 🤖 multi-agent pair-coding
+
+</div>

package/stack-template/app/ui-kit/RELEASE.md

@@ -0,0 +1,77 @@
+# RELEASE — quy trình publish version mới
+
+2 registry, 2 token, 3 lệnh. Tokens (lưu an toàn, đừng commit):
+
+| Env | Token | Tạo ở đâu |
+|---|---|---|
+| `GH_PACKAGES_TOKEN` | `ghp_...` (Classic, `write:packages`) — account **wakii-dev** | github.com/settings/tokens (wakii-dev) |
+| `NPM_TOKEN` | `npm_...` (Classic **Automation** — bypass 2FA) — account npm **wakii** | npmjs.com/settings/wakii/tokens |
+
+## 1. Chuẩn bị
+
+```bash
+cd app/ui-kit
+pnpm test && pnpm typecheck        # 540 tests phải xanh
+# bump version trong package.json (vd 0.1.4 → 0.2.0 / 1.0.0)
+```
+
+## 2. Publish GitHub Packages (chính thức — tên @wakii/ui-kit, hiện trên repo)
+
+```bash
+GH_PACKAGES_TOKEN=ghp_xxx pnpm --filter "@wakii/ui-kit" publish --no-git-checks
+```
+
+## 3. Publish npmjs.org (public — tên @wakii/ui-kit)
+
+```bash
+./scripts/publish-npm.sh
+# 2026-10-24: token wakii đã lưu trong ~/.npmrc (user duyệt) — chạy thẳng
+# không cần env. NPM_TOKEN=npm_xxx vẫn ưu tiên nếu có.
+```
+
+## 4. Deploy Storybook mới lên Vercel
+
+```bash
+pnpm build-storybook
+# 2026-10-25: deploy TRỰC TIẾP từ trong repo bị Vercel BLOCKED ("commit author
+# doesn't have permission" — git author Wakii không phải member team vuhoi).
+# Quy trình: copy ra ngoài git + link đúng project (build-storybook clean xoá
+# .vercel mỗi lần build):
+rm -rf /tmp/sb-deploy && cp -r storybook-static /tmp/sb-deploy
+cd /tmp/sb-deploy
+vercel link --project storybook-static --yes --team vuhois-projects
+vercel deploy --prod --yes --team vuhois-projects
+cd - && rm -rf /tmp/sb-deploy
+```
+
+## 5. Chốt
+
+```bash
+git add -A && git commit -m "release: <version>" && git push   # PR → merge main
+```
+
+## 6. Publish npmjs qua CI (GitHub Action — nhánh `release/ui-kit`)
+
+Workflow `.github/workflows/publish-uikit.yml` tự publish khi push vào nhánh
+`release/ui-kit` (hoặc chạy tay qua tab Actions → Run workflow). Điều kiện:
+
+1. Repo bật GitHub Actions (2026-10-24 đang DISABLE vì billing — xem CLAUDE.md mục CI).
+2. Secret `NPM_TOKEN` (bảng token ở đầu file này) set trong Settings → Secrets
+   and variables → Actions.
+3. Bump version trong `app/ui-kit/package.json` + thêm mục CHANGELOG.md, rồi
+   push/merge vào `release/ui-kit`.
+
+CI tự làm: install workspace → gate test + typecheck + build → gọi
+`scripts/publish-npm.sh` với `NPM_TOKEN` từ secret → tag `v<version>` +
+GitHub release với notes trích từ CHANGELOG.md (tag đã tồn tại = bỏ qua,
+chạy lại an toàn).
+
+## Bản đồ tên (đừng nhầm)
+
+| Registry | Package | Ai cài |
+|---|---|---|
+| npmjs.org | `@wakii/ui-kit` | Mọi người — `npm i @wakii/ui-kit`, không cần auth |
+| GitHub Packages | `@wakii/ui-kit` | Org — `.npmrc` thêm `@wakii-dev:registry=https://npm.pkg.github.com` + token |
+
+GitHub ép scope = owner (`wakii-dev`); npmjs theo org `wakii` — khác tên là chủ ý, cùng nội dung.
+Vercel production URL: https://storybook-static-khaki-two.vercel.app

package/stack-template/app/ui-kit/USAGE.md

@@ -0,0 +1,380 @@
+# USAGE — @wakii/ui-kit
+
+Storybook :6006 = docs sống (mọi props/states demo thật). File này gồm 2 phần:
+**Bắt đầu nhanh** (install/theme/form/icon/subpath/z-index) và **Tham chiếu theo component**.
+Đổi behavior gần đây xem [CHANGELOG.md](./CHANGELOG.md) + [MIGRATION.md](./MIGRATION.md);
+đối chiếu benchmark xem [docs/parity-matrix.md](../docs/parity-matrix.md).
+
+---
+
+## Bắt đầu nhanh
+
+### Install
+
+ui-kit là **workspace package consumed qua source** (ADR-0009) — không build, không publish:
+
+```bash
+# trong workspace monorepo
+pnpm add @wakii/ui-kit --workspace   # hoặc "dependencies": { "@wakii/ui-kit": "workspace:*" }
+```
+
+Tương lai publish npm: cùng API, thay scope thật — source-consumption giúp KHÔNG phải
+đợi build để tiêu thụ.
+
+**Peer-dep**: `zod ^4` (useForm) · `swiper` (subpath carousel) · `chart.js` (chart) ·
+`@fullcalendar/*` (schedule — optional, có fallback) · `@tiptap/*` (editor).
+
+### Dark theme
+
+Dark là theme phụ — bật bằng attribute `data-bp-theme="dark"` ở node bao ngoài
+(CSS var cascade xuống subtree, không đụng `:root` light):
+
+```tsx
+<html data-bp-theme="dark">  {/* cả app */}
+// hoặc subtree:
+<div data-bp-theme="dark" className="bg-canvas p-4">…</div>
+```
+
+Không tự chế token mới — thiếu token flag coordinator (`tokens.css` là source of truth;
+dark chỉ override dưới `[data-bp-theme='dark']` trong `themes/dark.css`).
+
+### Form — useForm + Field + zod
+
+Schema là source of truth; `useForm` trả `values/errors/touched` + handlers:
+
+```tsx
+import { z } from 'zod';
+import { useForm, Field, Input, Button } from '@wakii/ui-kit';
+
+const schema = z.object({
+  email: z.string().min(1, 'Email bắt buộc').email('Email không hợp lệ'),
+  password: z.string().min(8, 'Mật khẩu tối thiểu 8 ký tự'),
+});
+
+function LoginForm() {
+  const form = useForm({ schema, initialValues: { email: '', password: '' }, mode: 'onSubmit' });
+  return (
+    <form onSubmit={form.handleSubmit((data) => login(data))}>
+      <Field label="Email" htmlFor="email" error={form.errors.email} required>
+        <Input id="email" name="email" value={form.values.email} invalid={!!form.errors.email}
+          onChange={form.handleChange('email')} onBlur={form.handleBlur('email')} />
+      </Field>
+      <Field label="Mật khẩu" htmlFor="password" error={form.errors.password} required>
+        <Input id="password" name="password" type="password" value={form.values.password}
+          invalid={!!form.errors.password} onChange={form.handleChange('password')} />
+      </Field>
+      {/* sai → focus tự rơi vào field đầu (`[name=…]`); đúng → handleSubmit nhận data ĐÃ transform */}
+      <Button htmlType="submit">Đăng nhập</Button>
+    </form>
+  );
+}
+```
+
+`mode`: `onSubmit` (mặc định) · `onBlur` (validate khi rời input) · `onChange` (validate
+khi gõ, lỗi tự xoá khi sửa đúng). `reset()` xoá values/errors/touched về initial.
+
+### Icon
+
+48 icon path data gốc primeicons; `fill=currentColor` nên kế thừa màu text cha:
+
+```tsx
+import { Icon } from '@wakii/ui-kit';
+
+<Icon name="chevron-right" />          // default 14px
+<Icon name="settings" size={20} className="text-accent" />
+<Icon name="search" aria-hidden={false} /> // icon có nghĩa, cho screen reader
+```
+
+Danh sách `IconName` hợp lệ (union — gõ sai compile lỗi ngay):
+
+`chevron-up · chevron-down · chevron-left · chevron-right · angle-double-left · angle-double-right · search · plus · minus · times · check · check-circle · info-circle · exclamation-triangle · upload · download · calendar · clock · user · users · home · settings · menu-bars · ellipsis-h · ellipsis-v · pencil · trash · eye · eye-slash · refresh · filter · sort · sort-up · sort-down · arrow-up · arrow-down · arrow-left · arrow-right · caret-up · caret-down · caret-left · caret-right · star · heart · bell · external-link · copy · help-circle`
+
+Runtime nhận name lạ (bypass type) → render fallback `help-circle`. Xem tất cả ở
+Storybook **Primitives/Icons → AllIcons**.
+
+### Component nặng — subpath
+
+Barrel chính KHÔNG kéo CSS của comp nặng. Import qua subpath tương ứng:
+
+```tsx
+import { Carousel } from '@wakii/ui-kit/carousel';   // kèm swiper CSS; swiper là peer-dep
+import { Chart } from '@wakii/ui-kit/chart';         // chart.js
+import { Schedule } from '@wakii/ui-kit/schedule';   // @fullcalendar/* optional, có fallback
+import { Editor } from '@wakii/ui-kit/editor';       // @tiptap/*
+```
+
+### Z-index tier
+
+Thứ tự tầng cố định — component trong kit đã dùng token, consumer overlay tự viết
+đừng hardcode số:
+
+| Tier | Token | Giá trị | Dùng cho |
+|---|---|---|---|
+| 1 | `--z-dropdown` | 1000 | menu, select panel, context menu |
+| 2 | `--z-popover` | 1030 | popover |
+| 3 | `--z-modal` | 1050 | modal, drawer, image preview |
+| 4 | `--z-toast` | 1070 | message/notification toast |
+| 5 | `--z-tooltip` | 1090 | tooltip trên cùng |
+
+```tsx
+<div className="fixed inset-0 z-[var(--z-modal)]">…</div>
+```
+
+---
+
+## Tham chiếu theo component
+
+### Import
+
+```tsx
+// UI primitives
+import { Badge, EmptyState, Skeleton, Spinner, Button, Input, Textarea, Tag,
+  Alert, Modal, Popconfirm, Select, Tooltip, Card, Statistic, Pagination,
+  Checkbox, Radio, RadioGroup, Switch, InputNumber, Tabs, Dropdown, Segmented,
+  Avatar, Drawer, Progress, Result, Descriptions, Collapse, UiImage, Table,
+  Breadcrumb, Steps, BusyBox, Typography, Divider, Space,
+  UiKitProvider, message, notification } from '@wakii/ui-kit';
+
+// Styles (shell import global; remote standalone tự import)
+import '@wakii/ui-kit/styles/tokens.css';
+import '@wakii/ui-kit/styles/base.css';
+import '@wakii/ui-kit/styles/tailwind.css'; // shell làm chủ; remote import trong app.css
+```
+
+### Badge
+
+```tsx
+<Badge variant="doing">Đang làm</Badge>
+// variant: todo|doing|done|failed + created|updated|assigned|deleted|assignmentFailed
+```
+
+### EmptyState
+
+```tsx
+<EmptyState title="Chưa có task nào" description="Tạo task đầu tiên."
+  action={<Button>Tạo</Button>} image={<img src="…" />} />
+```
+
+### Skeleton
+
+```tsx
+<Skeleton variant="row" count={4} className="custom" />
+// variant: text|row|card
+```
+
+### Spinner
+
+```tsx
+<Spinner label="Đang xử lý" variant="dots" size="large" color="muted" />
+// variant: ring|dots|bars · size: small|default|large · color: accent|muted|inverse
+```
+
+### BusyBox
+
+```tsx
+<BusyBox busy={loading} variant="row" count={4}>
+  <TaskList items={items} />
+</BusyBox>
+// busy=true → Skeleton thay content (aria-busy); busy=false → content
+```
+
+### Button
+
+```tsx
+<Button type="primary" htmlType="submit" loading={saving} block>Tạo task</Button>
+<Button type="text" danger icon={<span>🗑</span>}>Xoá</Button>
+// type: primary|default|text · danger · size: small|middle|large · loading · block · icon
+```
+
+### Input / Textarea
+
+```tsx
+<Input value={v} onChange={e => setV(e.target.value)} placeholder="Nhập…"
+  prefix="🔍" allowClear invalid size="large" />
+<Textarea rows={3} maxLength={200} showCount value={d} onChange={setD} invalid />
+// prefix/suffix kích hoạt affix wrapper · allowClear cần controlled (value+onChange)
+```
+
+### Select
+
+```tsx
+<Select ariaLabel="Trạng thái" value={status} onChange={setStatus}
+  options={[{label:'Cần làm', value:'todo'}, …]}
+  placeholder="Chọn…" disabled />
+// a11y: combobox + listbox + keyboard (Enter/Space/Arrow/Esc)
+```
+
+### Checkbox / Radio / Switch / InputNumber
+
+```tsx
+<Checkbox checked={remember} onChange={setRemember}>Nhớ tôi</Checkbox>
+<RadioGroup value={sort} onChange={setSort} options={[{label:'Mới', value:'new'}]} />
+<Switch checked={on} onChange={setOn} checkedChildren="Bật" unCheckedChildren="Tắt" />
+<InputNumber value={n} onChange={setN} min={0} max={100} step={1} ariaLabel="Số" />
+```
+
+### Alert
+
+```tsx
+<Alert type="error" message="Lỗi" description="Chi tiết" closable onClose={fn} />
+// type: success|info|warning|error · mặc định filled (nền đặc, chữ trắng);
+// variant="outlined" giữ look tint + viền cũ
+```
+
+### Modal
+
+```tsx
+<Modal open={open} title="Xoá?" danger okText="Xác nhận xoá"
+  confirmLoading={busy} onOk={handleDelete} onCancel={() => setOpen(false)}>
+  Hành động không thể hoàn tác.
+</Modal>
+// ESC + overlay click = cancel; zoom-in/out motion
+```
+
+### Drawer
+
+```tsx
+<Drawer open={open} title="Chi tiết" width={378} onClose={close}
+  footer={<Button>Lưu</Button>}>
+  Nội dung
+</Drawer>
+// slide-in/slide-out motion
+```
+
+### Popconfirm
+
+```tsx
+<Popconfirm open={open} title="Xoá?" danger okText="Xoá"
+  onConfirm={del} onCancel={close}>
+  <Button danger>Xoá</Button>
+</Popconfirm>
+```
+
+### message / notification (static API)
+
+```tsx
+import { message, notification } from '@wakii/ui-kit';
+message.success('Đã xoá'); message.error('Lỗi');
+notification.info('Tiêu đề', 'Mô tả chi tiết');
+```
+
+### Card
+
+```tsx
+<Card title="Tiêu đề" extra={<a>Thêm</a>} hoverable actions={[<span>Action</span>]}>
+  Nội dung
+</Card>
+```
+
+### Statistic
+
+```tsx
+<Statistic title="Tổng task" value={42} prefix="↑" suffix="việc" valueStyle={{color:'var(--accent)'}} />
+```
+
+### Tooltip
+
+```tsx
+<Tooltip title="Gợi ý"><Button>?</Button></Tooltip>
+// placement: top (mặc định) | bottom · hover + focus
+```
+
+### Table (DataTable)
+
+```tsx
+<Table columns={[
+  { key: 'title', title: 'Tiêu đề', sortable: true, filterable: true },
+  { key: 'act', title: '', render: r => <Button>Xoá</Button> },
+  { key: 'exp', title: '', expander: true },
+]} dataSource={data} rowKey="id"
+  paginator pageSize={10} rowsPerPageOptions={[5,10,20]}
+  selectionMode="checkbox" onSelectionChange={setSelected}
+  sortMode="multiple" onSort={setSorts}
+  scrollHeight={400} striped size="small" loading={loading}
+  rowExpansion={r => <Detail id={r.id} />}
+  emptyMessage={<EmptyState title="Trống" />}
+/>
+```
+
+Table contracts:
+
+- Sort click: asc → desc → none (cycle); Shift/Meta click: multi-sort
+- Filter: contains (mặc định) / equals / startsWith — per-column match mode
+- Paginator: Pagination + Select số dòng
+
+### Tabs
+
+```tsx
+<Tabs items={[{key:'1', label:'Tab 1', children:<Content1/>}]} onChange={setKey} />
+```
+
+### Pagination
+
+```tsx
+<Pagination current={page} pageSize={10} total={100} onChange={setPage} />
+```
+
+### Breadcrumb
+
+```tsx
+<Breadcrumb items={[{title:'Home', href:'/'}, {title:'Task A'}]} />
+```
+
+### Steps
+
+```tsx
+<Steps items={[{title:'Đặt hàng', description:'Giỏ hàng'}]} current={1} />
+```
+
+### Dropdown
+
+```tsx
+<Dropdown trigger={<Button>Menu</Button>} onItemClick={k => go(k)}
+  items={[{key:'edit', label:'Sửa'}, {key:'---', label:''}, {key:'del', label:'Xoá', danger:true}]} />
+```
+
+### Segmented
+
+```tsx
+<Segmented options={[{label:'Ngày', value:'day'}]} value={view} onChange={setView} />
+```
+
+### Theming
+
+Dark theme bật qua attribute (xem **Bắt đầu nhanh → Dark theme**):
+
+```tsx
+<div data-bp-theme="dark">…</div>
+```
+
+`UiKitProvider` vẫn cung cấp context chung cho kit (accent override qua CSS vars cascade,
+không cần JS re-render).
+
+### Motion
+
+Xem `docs/motion.md` — motion scale, easing, guidelines. Tất cả animation tôn trọng
+`prefers-reduced-motion`.
+
+### Composition Rule
+
+Composite components GHÉP từ primitives của chính kit — KHÔNG tay chế raw
+`<select>/<input>/<button>` nội bộ.
+
+| Composite | Dùng primitives |
+|---|---|
+| Table | Pagination + Select + Checkbox + Input + Button + EmptyState + Skeleton |
+| Select | Button (trigger) + Checkbox (multi) + Spinner (loading) |
+| Popconfirm | Button (OK/Cancel) |
+| Modal/Drawer | Button (OK/Cancel/Đóng) |
+| FilterMenu | Select (match mode) + Input (value) + Button (Apply/Reset) |
+
+**Verify:** `grep -rn '<select\|<button' app/ui-kit/src/ui/*/index.tsx | grep -v primitives`
+→ 0 kết quả (trừ primitives tự thân).
+
+### Viết component mới (quy ước)
+
+- Màu/radius/motion/z-index **chỉ dùng token** — thiếu token flag coordinator, không tự thêm (`docs/parity-matrix.md` §Nguyên tắc).
+- Ngôn ngữ nút: thường `transparent + hover:bg-s3` · active `bg-accent text-white font-medium` · disabled `text-ink3/ink4` không hover.
+- Icon: dùng `<Icon name="…">` — không tự vẽ SVG chevron riêng.
+- A11y: `role`/`aria-expanded`/`aria-current`/`aria-label` tiếng Việt như các comp hiện có.
+- Test: behavior thật colocated `*.test.tsx` (vitest + testing-library); story matrix `*.stories.tsx` **phải có ≥1 `export const`** (file 0-export bị indexer drop — bài học batch ⑮).

package/stack-template/app/ui-kit/eslint.config.js

@@ -0,0 +1,47 @@
+// ESLint flat config — ui-kit (batch ⑭ worker B, chuẩn bị publish npm).
+// Chính sách: guard code mới/sửa mới; legacy KHÔNG auto-fix (script lint không --fix),
+// vi phạm cũ chỉ 'warn' — đổi dần thành error khi worker chạm tới file. Target: 0 error.
+import tseslint from 'typescript-eslint';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+
+export default tseslint.config(
+  // generated/heavy output — không lint
+  { ignores: ['dist/**', 'storybook-static/**', 'coverage/**', 'node_modules/**', '.changeset/**', 'scripts/**'] },
+  // Directive disable tham chiếu rule chưa cài (prettier/prettier trong icons/index.tsx —
+  // file sinh bằng script của worker khác, không sửa ngoài story) → tắt báo cáo; plugin
+  // prettier không thuộc plan lint của ui-kit
+  { linterOptions: { reportUnusedDisableDirectives: 'off' } },
+  // typescript-eslint recommended (flat)
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx}'],
+    plugins: {
+      // Đăng ký tường minh (react-hooks v7 configs.recommended vẫn eslintrc-shape → lỗi flat)
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    rules: {
+      // react-hooks — rules-of-hooks giữ ERROR cho component thật (0 vi phạm hiện tại)
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn',
+      // Story/stories export component + demo helper — chỉ cảnh báo
+      'react-refresh/only-export-components': ['warn', { allowConstantExport: true }],
+      // Legacy tolerance — warn thay error (spec batch ⑭: no-unused-vars off→warn)
+      '@typescript-eslint/no-unused-vars': 'warn',
+      '@typescript-eslint/no-explicit-any': 'warn',
+      // Pattern legacy của repo — @ts-nocheck trên peer-lazy (schedule/editor/chart),
+      // expression-statement (`flag && fn()`), let chưa gán lại: demote, không auto-fix
+      '@typescript-eslint/ban-ts-comment': 'warn',
+      '@typescript-eslint/no-unused-expressions': 'warn',
+      'prefer-const': 'warn',
+    },
+  },
+  {
+    // Stories: hook trong render-callback CSF3 là pattern hợp lệ — rules-of-hooks chỉ warn
+    files: ['**/*.stories.tsx', '**/*.test.tsx'],
+    rules: {
+      'react-hooks/rules-of-hooks': 'warn',
+    },
+  },
+);