lily-lark-ui 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,235 @@
+# Changelog
+
+Mọi thay đổi đáng chú ý của `lily-lark-ui` được ghi ở đây. Định dạng theo
+[Keep a Changelog](https://keepachangelog.com/vi/1.1.0/), phiên bản theo
+[SemVer](https://semver.org/lang/vi/).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-11-05
+
+### Changed — đổi tên package sang `lily-lark-ui`
+
+- Bỏ scope `@lily` (chưa tồn tại trên npm, cần tạo org). Tên không scope cài
+  bằng `npx lily-lark-ui init`, không cần quyền org.
+- `scripts/rename-package.mjs` đổi tên ở 41 file, có `--dry-run` và validate tên.
+
+### Added — phát hành
+
+- `scripts/publish.sh` (`pnpm publish` / `pnpm publish:dry`): kiểm đăng nhập,
+  build, test, `check-lark`, `publint`, pack tarball rồi `import()` thật bằng
+  Node ESM, kiểm kích thước, `npm publish`, rồi cài lại từ registry.
+- Metadata đủ để publish: `license` MIT + `LICENSE`, `publishConfig.access=public`,
+  `author`, `keywords`, `prepublishOnly` chạy build+test+check.
+
+### Fixed — package không dùng được ngoài bundler
+
+- `dist` giữ import tương đối thiếu đuôi `.js` (`from './components/button'`),
+  Node ESM không resolve → `ERR_MODULE_NOT_FOUND dist/lib/utils` khi `import()`
+  từ tarball. Đã thêm `.js` cho 44 import trong `src/`. `publint` vẫn báo
+  "All good", chỉ `import()` thật mới phát hiện.
+- Installer `--skip-install` không gọi `npm i` cho bootstrap Tailwind nữa
+  (test offline từng timeout 5s vì tải package từ mạng).
+
+### Added
+
+- Trang showcase responsive (`pnpm showcase:dev`, `pnpm showcase:build`) render
+  đủ 20 component và một màn ví dụ dùng chung cho desktop/tablet/mobile; bản
+  đóng gói một file HTML tự chứa tại `lark-ui-components.html` (root repo).
+- `tests/showcase.test.ts` so hash nguồn, FAIL khi file HTML chưa build lại sau
+  khi sửa component/token/showcase.
+- Showcase có nút chuyển sáng/tối: đặt `data-theme` trên `<html>`, nhớ lựa chọn
+  trong `localStorage`, mặc định theo `prefers-color-scheme`; thêm `color-scheme`
+  để thanh cuộn và control của trình duyệt đổi theo.
+
+### Fixed
+
+- Tương phản chế độ tối: chữ accent dùng `text-brand-link` (`#75A4FF`) thay vì
+  `text-brand-secondary` (`#275FCE`, chỉ dùng làm nền) ở Button/Tabs/Select/
+  Dropdown/Tag — trước đó 3.0–3.6:1.
+- `LarkButton` variant `primaryError` và `LarkBadge` dùng `--danger-foreground`
+  thay vì chữ trắng cứng: nền danger bản tối là `#F6827E` nên chữ trắng chỉ
+  đạt 2.50:1; nay 6.97:1 (sáng 5.83:1). Token `--danger-foreground` bổ sung
+  cho khối sáng.
+- Chữ phụ 12–14px đổi `text-lark-n500` → `text-lark-n600`: `n500` ở chế độ tối
+  chỉ đạt 3.78:1, guide ghi "không dùng cho chữ nhỏ quan trọng".
+- `LarkTag` màu blue dùng nền `bg-lark-accent-soft` thay `bg-brand-secondary/20`
+  (4.26:1 → 5.16:1 ở bản sáng).
+- Audit tương phản bằng pixel thật (Chromium + ImageMagick): 0 vi phạm WCAG AA
+  ở cả sáng và tối cho chữ không bị disabled.
+
+### Added — tài liệu cài đặt
+
+- `INSTALL.md` viết lại: bảng yêu cầu (Tailwind v4 bắt buộc, không dùng v3),
+  công thức 3 dòng CSS, hướng dẫn cho app đã có CSS riêng, bảng 4 lỗi thường
+  gặp, cách kiểm `grep -c 'bg-brand-secondary' dist/assets/*.css`.
+- `README.md`: mục yêu cầu + 3 dòng CSS bắt buộc.
+- Skill `lark-ui` viết lại: style guide chính thức là nguồn quyết định (Figma
+  chỉ tham khảo), thêm mục cài một lệnh và ví dụ code đã kiểm chứng.
+
+### Fixed — installer (phát hiện khi chạy thử trên lily-store-division-kpis)
+
+- Không chèn `@import "lily-lark-ui/styles.css"` khi repo đích chưa có
+  Tailwind v4 (trước đây chèn mù làm `vite build` hỏng với `ENOENT`).
+- Thêm bước `@source "../node_modules/lily-lark-ui/src"`: Tailwind v4 không
+  quét `node_modules`, thiếu dòng này component render không style (nút trong
+  suốt, cao 22px thay vì 32px) trong khi build vẫn PASS.
+- Nhận cả `@import 'tailwindcss'` (nháy đơn) lẫn nháy kép khi chèn import;
+  trước chỉ khớp nháy kép nên chèn sai vị trí.
+- Test harness đọc cả stdout và stderr (thông báo `warn` ghi ra stderr).
+
+### Changed — căn theo style guide chính thức của Lark
+
+Nguồn số đo từ nay là Lark Design (MCP `lark-design`, `design-language/*` và
+`components/*`); file Figma chỉ còn để tham khảo đối chiếu.
+
+- Thang màu neutral đổi về đúng bảng "Màu chữ" và "Viền": N400 `#BBBFC4`,
+  N500 `#8F959E`, N600 `#646A73`, N700 `#2B2F36`, N300 `#D0D3D6`.
+  Trước đó dùng N400 `#C9CDD4`, N500 `#86909C`, N600 `#4E5969` (bảng cũ).
+- Viền control tương tác dùng `border-lark-n300` (`#D0D3D6`) cho nút secondary,
+  ô nhập, select — đúng "Viền điều khiển tương tác 1px" của guide.
+- Bo góc theo thang Radius-XS 4 / S 6 / M 8 / L 10: ô nhập, item menu, tab đổi
+  sang 6px (`rounded-lg`); tooltip sang 8px (`rounded-xl`); badge sang tròn
+  hoàn toàn (`rounded-full`) theo "Radius-XL: badge".
+- Focus chuyển sang utility `focus-visible:focus-ring` = `outline: 2px solid
+  var(--focus-ring-color)` + offset 2px, chỉ hiện với bàn phím/voice đúng
+  trạng thái "Focus-visible" của guide. Trước đó dùng `ring-2` (box-shadow)
+  và một số chỗ mất focus hoàn toàn.
+
+### Fixed — spacing và cắt nội dung
+
+- `LarkTable`: cột ghim phải (`pin: 'right'`) thiếu vạch phân cách, nội dung
+  cuộn bên dưới chạm thẳng vào cột nên trông như bị cắt giữa chữ. Thêm
+  `border-s border-lark-n200` cho `th` và `td` ghim, đúng mô tả trong
+  `patterns/table.md`.
+- Showcase: grid 2 cột skeleton/empty state thiếu `grid-cols-1` + `min-w-0`
+  nên mỗi khối rộng 360px trong khung 309px, tràn ra ngoài.
+- Showcase: nút icon trong header màn ví dụ dùng `size="sm"` (28×28) — dưới
+  ngưỡng chạm; đổi sang `size="md"` (32×36).
+- Showcase: badge số đè lên icon chuông (`-end-0.5 -top-0.5`); đổi thành
+  `-end-1 -top-1` + `pointer-events-none` để nằm ngoài góc.
+
+### Fixed
+
+- Installer khong con chen `@import "lily-lark-ui/styles.css"` vao repo dich
+  khi repo do chua co Tailwind v4 — truoc day chen mu va lam `vite build` hong
+  (`ENOENT: lily-lark-ui/styles.css`). Gio bao WARN + huong dan cai Tailwind,
+  giu nguyen file CSS goc. Phat hien khi chay thu tren `lily-store-division-kpis`.
+- `outline-[var(--focus-ring-color)]` không sinh CSS đúng (Tailwind v4 hiểu là
+  outline-width) khiến focus ring trắng/không màu; thay bằng `@utility focus-ring`.
+- `LarkTag` màu blue dùng nền `bg-lark-accent-soft` thay `bg-brand-secondary/20`
+  (4.26:1 → 5.16:1).
+
+## [0.1.1] — 2026-11-05
+
+### Changed
+
+- Mục đang chọn của `LarkSelect` dùng nền trắng
+  theo Figma (`Basic/Selected` nền `#FFFFFF`, `token/bg/float`),
+  phân biệt bằng `text-brand-secondary` + `font-medium` + indicator;
+  bỏ `bg-lark-accent-soft` của mẫu nội bộ (`patterns/dropdown.md`
+  là mẫu lệch). Mục đang chọn dropdown dùng prop `checked`
+  (icon + chữ brand, nền trắng theo Figma). Hover giữ `bg-lark-n100`
+  (adapt để thấy điểm hover; Figma ghi hover trong suốt).
+
+### Added
+
+- `LarkTooltipProvider` đặt ở root: `delayDuration`/`skipDelayDuration` của
+  provider giờ có tác dụng; `LarkTooltip` render độc lập vẫn tự bọc provider
+  dự phòng 300ms.
+- `LarkTooltip` nhận prop `delayDuration` riêng.
+- `LarkDropdownMenu.Item` nhận prop `checked` + icon dấu chọn thật.
+
+### Fixed
+
+- Dropdown trả focus về trigger khi đóng bằng Escape, chọn item, hoặc click
+  ngoài; click lần hai lên trigger đóng menu (có test chặn hồi quy).
+- Bỏ lớp neo `span.contents` làm `getBoundingClientRect()` bằng 0 khiến menu
+  hiện sai vị trí trên trình duyệt thật.
+- Dọn cảnh báo `act()` của Radix RovingFocus và `ToastAnnounce`; test chạy
+  không còn cảnh báo.
+- `LarkDropdownMenu.Item` dùng `data-[state=checked]` (Radix `Menu.Item`
+  không sinh state này) nên mục đang chọn trước đây không có dấu hiệu nào;
+  nay dùng prop `checked`.
+
+## [0.1.0] — 2026-11-05
+
+Bản phát hành đầu tiên: 20 component theo số đo Lark, token Tailwind v4,
+installer một lệnh, MCP server đọc specs.
+
+### Added — Phase 1: nền tảng
+
+- Scaffold package `lily-lark-ui` (TypeScript strict, Vite + Vitest + jsdom,
+  RTL + axe), build `tsc` sinh `dist/index.js` + `dist/index.d.ts`.
+- Token Lark tại `src/styles/lark-tokens.css`: màu (brand `#1456F0`), chữ,
+  bo góc (`--radius-lg: 6px`), hiệu ứng hai tầng (micro `120ms ease-base`,
+  overlay `300ms` vào / `200ms` ra), hai khối tối (`prefers-color-scheme`
+  và `[data-theme='dark']`), `prefers-reduced-motion`.
+- `cn()` (clsx + tailwind-merge) và script `check:lark` chặn hex trong TSX,
+  `dark:`, icon unicode/emoji, `#3370FF`, duration literal.
+- Component: `LarkButton` (24/28/32/40 PC, 32 mặc định, 40 form, responsive
+  mobile 36/48), `LarkTextField` (42 mobile / 36 PC), `LarkDropdownMenu`,
+  `LarkTabs` (34px, indicator 3px), `LarkTooltip` (delay 300ms).
+- Registry shadcn (`registry.json`), README, INSTALL, AGENTS, skill
+  `lark-ui`, MCP server `lui_list/lui_get/lui_search/lui_tokens`.
+- Installer `scripts/install.sh`: dry-run mặc định, `--apply`, `--skip-install`,
+  idempotent, backup `opencode.jsonc`.
+- Playwright visual: không tràn ngang 375/768/1280, nút 36@375–32@1280,
+  input 42@375–36@1280, dropdown trong viewport, motion 0.12s / 0.3s,
+  reduced-motion về 0s.
+
+### Added — Phase 2: form và overlay
+
+- `LarkTextArea` (dùng lại `inputClass`, tối thiểu 3 dòng 72px).
+- `LarkSelect` (trigger/item 32px, popover rộng bằng trigger, motion overlay).
+- `LarkCheckbox` (16px, bo 4, check 12px), `LarkRadioGroup` (16px, viền 5px),
+  `LarkSwitch` (rãnh 36×20, núm 16).
+- `LarkDialog` (+ `Content`/`Footer`, r=8, đệm 20/24, footer full-bleed),
+  `LarkAlertDialog` (chặn Escape và disable nút khi `isPending`).
+- `LarkToast` + `LarkToastProvider` + `useLarkToast` (nền n900, slide-up, 4s,
+  swipe right, pill trên mobile).
+- `LarkSpinner` (16/24), `LarkEmptyState`.
+- Chuẩn hoá prop: `disabled` cho trạng thái native; `isPending`/`isInvalid`/
+  `isIconOnly` cho trạng thái riêng của thư viện.
+- `forwardRef` cho toàn bộ component có phần tử gốc tương tác.
+
+### Added — Phase 3: hiển thị dữ liệu và phát hành
+
+- `LarkTable` (+ `Wrapper`, `Footer`, cột `pin: 'right'` dính phải, header
+  `sticky top-0`, skeleton loading, `LarkTruncatedCell`).
+- `LarkPagination` (+ `pageWindow` cửa sổ 7 mục, nút 28px, active bo 6px,
+  chọn số dòng qua `LarkSelect`).
+- `LarkTag` (24/16, 5 màu), `LarkBadge` (14px, `99+`, dot), `LarkAvatar`
+  (20/32/36, initials, nhóm tròn 36px).
+- Installer: `--components <list>` cài lẻ theo registry, kiểm Tailwind v4
+  (chỉ cảnh báo), chạy `check-lark` trên repo đích (chỉ báo cáo), E2E
+  `pnpm pack` → cài tarball → `vite build` fixture.
+- Docs: 20 trang `specs/`, skill mapping 20 component + quy tắc bố cục
+  trang, registry 20 item.
+- Package phát hành kèm `registry.json`, `skill/`, `specs/`, `mcp/`,
+  `scripts/`, `INSTALL.md`.
+
+### Fixed
+
+- Tailwind v4 không sinh utility `duration-*` vì sai namespace → đổi sang
+  `--transition-duration-*`; `anim-overlay-*` chuyển thành `@utility` để
+  variant `data-[state=*]` hoạt động.
+- CSS token còn 3 dòng `@import` giữa file làm vỡ build khi app import.
+- Import alias `@/` bị giữ trong `dist` khiến consumer build lỗi → đổi sang
+  import tương đối trong `src/components`.
+- `spinner.tsx` dùng `process.env` thiếu type → thêm `@types/node` cho build.
+- Pagination từng thiếu `lucide-react` trong registry dependencies.
+- Avatar nhóm từng bo vuông do đọc sai nguồn → luôn tròn theo Figma.
+
+### Known limitations
+
+- `LarkTable` chưa `forwardRef` (component generic, không có use case ref).
+- Tag màu `warning` dùng `brand-support` vì token chưa có `--color-lark-warning`.
+- `check-lark` chỉ quét `.ts`/`.tsx`, bỏ qua file CSS.
+- Núm `LarkSwitch` 16px trong khi Figma ghi 20×20; rãnh giữ đúng 36×20 nên
+  núm nhỏ hơn nguồn 4px (đã ghi trong `specs/switch.md`).
+- `LarkTooltip` dùng delay 300ms theo chuẩn overlay của repo; file Figma
+  feedback không ghi số delay riêng.
+
+[0.1.1]: https://github.com/KINHMATLILY/lark-ui/releases/tag/v0.1.1
+[0.1.0]: https://github.com/KINHMATLILY/lark-ui/releases/tag/v0.1.0

package/INSTALL.md

@@ -0,0 +1,278 @@
+# Cài đặt lily-lark-ui
+
+## Cài từ npm (sau khi package được publish)
+
+```bash
+npx lily-lark-ui init
+```
+
+Nếu `npx` báo không tìm thấy package, nghĩa là chưa publish lên registry — xem
+mục "Phát hành" bên dưới, hoặc cài từ tarball.
+
+## Phát hành (dành cho maintainer)
+
+Package dùng tên không scope: `lily-lark-ui`. Không cần tạo org, không cần
+quyền trên scope nào.
+
+Một lần chuẩn bị:
+
+1. Tạo tài khoản npm: https://www.npmjs.com/signup
+2. `npm login` rồi `npm whoami` để xác nhận.
+
+Sau đó:
+
+```bash
+cd ~/Sites/lark-ui
+pnpm release:dry   # kiểm tra toàn bộ, không publish
+pnpm release       # publish thật
+```
+
+Nếu tài khoản bật 2FA, `npm publish` sẽ dừng ở `EOTP`. Tạo một **Automation
+token** tại https://www.npmjs.com/settings/<user>/tokens (loại Automation bỏ qua
+OTP) rồi thêm vào `~/.npmrc`:
+
+```bash
+echo '//registry.npmjs.org/:_authToken=<token>' >> ~/.npmrc
+```
+
+Script tự: kiểm đăng nhập, build, test, `check-lark`, `publint`, pack tarball
+rồi `import()` thật bằng Node ESM, kiểm kích thước, `npm publish`, và cuối cùng
+cài lại từ registry để xác nhận.
+
+Nếu sau này muốn đổi tên (ví dụ sang scope riêng):
+
+```bash
+node scripts/rename-package.mjs --name @user/lark-ui   # dry-run trước, bỏ --dry-run để ghi
+```
+
+## Yêu cầu bắt buộc
+
+| Thứ | Phiên bản | Vì sao |
+|---|---|---|
+| **Tailwind CSS** | **v4** (`^4.0.0`) | Token dùng `@theme`/`@utility` của Tailwind v4. **v3 không chạy được.** |
+| `@tailwindcss/vite` | `^4.0.0` | Plugin build; không dùng PostCSS config kiểu v3. |
+| React / React DOM | `^19.0.0` | peerDependency của package. |
+| Node | `>= 20` | ESM + Vite hiện hành. |
+
+## Cách nhanh nhất — một lệnh CLI
+
+```bash
+npx lily-lark-ui init
+```
+
+Chạy trong thư mục app. CLI tự: cài `lily-lark-ui`, cài Tailwind v4 (nếu
+thiếu), thêm plugin vào `vite.config.ts`, chèn `@import` + `@source`, ghi
+`components.json`, symlink skill, chèn MCP, smoke test, `check-lark`.
+
+Các lệnh khác:
+
+```bash
+npx lily-lark-ui init --repo ../app          # cài vào app khác
+npx lily-lark-ui init --dry-run              # xem kế hoạch, không ghi
+npx lily-lark-ui init --no-bootstrap         # không cài Tailwind/sửa vite config
+npx lily-lark-ui init --components button,table
+npx lily-lark-ui check                       # chạy check-lark trên ./src
+npx lily-lark-ui tokens                      # in bảng token
+npx lily-lark-ui --help
+```
+
+Yêu cầu: chạy trong repo đã có `package.json` + `react`.
+
+### Nếu gọi thẳng installer (không qua CLI)
+
+```bash
+bash ~/Sites/lark-ui/scripts/install.sh --repo . --apply --bootstrap
+```
+
+Nếu package chưa publish lên registry, trỏ tới tarball:
+
+```bash
+cd ~/Sites/lark-ui && pnpm pack
+LARK_UI_TARBALL=~/Sites/lark-ui/lily-lark-ui-0.2.0.tgz \
+  bash ~/Sites/lark-ui/scripts/install.sh --repo . --apply --bootstrap
+```
+
+Lưu ý: `--bootstrap` cần `--apply` để ghi thật; thiếu `--apply` là dry-run.
+Installer không cài được `react`/`vite` — repo phải là app Vite + React sẵn.
+
+## Không dùng Vite
+
+`--bootstrap` tự nhận bundler và chỉ cài phần cần:
+
+| Bundler | Installer làm | Việc bạn cần làm |
+|---|---|---|
+| **Vite** | cài `tailwindcss@^4` + `@tailwindcss/vite`, sửa `vite.config.ts` | không cần gì |
+| **Next.js 15+** | chỉ cài `tailwindcss@^4` (không cài plugin Vite) | thêm 3 dòng vào `app/globals.css` |
+| **Nuxt** | chỉ cài `tailwindcss@^4` | thêm `@tailwindcss/vite` vào `nuxt.config` mục `vite.plugins`, khai `css: ['~/assets/css/main.css']` |
+| **Astro** | chỉ cài `tailwindcss@^4` | thêm `tailwindcss()` vào `astro.config.mjs` > `vite.plugins` |
+| **CRA** | chỉ cài `tailwindcss@^4` | CRA không hỗ trợ Tailwind v4 trực tiếp; cần eject hoặc chuyển sang Vite |
+| **Khác** | chỉ cài `tailwindcss@^4` | tự làm theo tài liệu bundler đó |
+
+Với mọi bundler, CSS vẫn cần đúng 3 dòng:
+
+```css
+@import "tailwindcss";
+@import "lily-lark-ui/styles.css";
+@source "../node_modules/lily-lark-ui/src";
+```
+
+Đường dẫn `@source` tính từ file CSS. Với Next.js đặt ở `app/globals.css` thì
+`../node_modules/...` trỏ từ `app/` — kiểm lại bằng
+`grep -c 'bg-brand-secondary' .next/static/css/*.css` sau khi build.
+
+### Next.js: ví dụ đầy đủ
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "lily-lark-ui/styles.css";
+@source "../node_modules/lily-lark-ui/src";
+```
+
+`next.config.ts` không cần sửa — Next 15 dùng PostCSS nội bộ cho `@import` CSS.
+
+## Cách thủ công (nếu muốn kiểm soát từng bước)
+
+Cài Tailwind v4 trước khi cài thư viện:
+
+```bash
+npm i -D tailwindcss@^4 @tailwindcss/vite
+```
+
+Thêm plugin vào `vite.config.ts`:
+
+```ts
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({ plugins: [react(), tailwindcss()] })
+```
+
+## Ba bước bắt buộc trong entry CSS
+
+Tailwind v4 **không tự quét `node_modules`**, nên ngoài `@import` còn phải có
+`@source` trỏ tới package. Thiếu `@source`, component render ra không có style
+(nút mất nền, sai chiều cao) dù build không báo lỗi.
+
+```css
+/* src/index.css */
+@import "tailwindcss";
+@import "lily-lark-ui/styles.css";
+
+/* Bắt buộc: sinh utility dùng trong component của thư viện */
+@source "../node_modules/lily-lark-ui/src";
+```
+
+Đường dẫn `@source` tính từ file CSS. Nếu entry CSS nằm ở `src/index.css` thì
+`../node_modules/...` là đúng; nếu ở chỗ khác thì chỉnh lại.
+
+**Thứ tự quan trọng:** `@import "tailwindcss"` phải đứng trước
+`@import "lily-lark-ui/styles.css"`.
+
+## Cài đặt
+
+### Cách A — npm
+
+```bash
+pnpm add lily-lark-ui
+```
+
+Nếu package chưa publish lên registry, cài từ tarball:
+
+```bash
+# trong repo lark-ui
+pnpm pack            # sinh lily-lark-ui-<version>.tgz
+
+# trong repo đích
+pnpm add ./lily-lark-ui-0.2.0.tgz
+```
+
+Dùng component:
+
+```tsx
+import { LarkButton } from 'lily-lark-ui'
+
+export function Demo() {
+  return <LarkButton variant="primary">Lưu</LarkButton>
+}
+```
+
+### Cách B — script tự động
+
+```bash
+scripts/install.sh --repo <path> [--apply] [--skip-install] [--components <list>]
+```
+
+- `<path>`: repo đích.
+- Không truyền `--apply` thì dry-run (chỉ in kế hoạch, không sửa file).
+- `--apply`: ghi thật.
+- `--skip-install`: bỏ qua `pnpm add` (dùng khi đã cài tarball, hoặc test offline).
+- `--components <list>`: cài lẻ vài component, cách nhau bằng phẩy
+  (`button,table`); tự thêm tiền tố `lark-`; tên sai thì exit 1 kèm danh sách
+  tên hợp lệ.
+- Idempotent: chạy lại nhiều lần không trùng lặp.
+
+Các bước installer thực hiện:
+
+1. `pnpm add lily-lark-ui`.
+1b. Kiểm Tailwind v4 trong `package.json` đích. **Thiếu hoặc v3 → không chèn
+    CSS** (vì sẽ làm `vite build` hỏng), chỉ cảnh báo và in hướng dẫn cài.
+2. Chèn `@import "lily-lark-ui/styles.css"` ngay sau `@import "tailwindcss"`
+   (nhận cả nháy đơn và nháy kép).
+2b. Thêm `@source "../node_modules/lily-lark-ui/src"` — bắt buộc với Tailwind v4.
+2c. Nếu có `--components`: copy file component theo `registry.json`
+    + `src/lib/utils.ts` + `src/styles/lark-tokens.css` (chỉ khi chưa có).
+3. Ghi `components.json` (dạng shadcn) nếu chưa có.
+4. Symlink skill `lark-ui` vào `~/.config/opencode/skills/`.
+5. Chèn block MCP `lark-ui` vào `~/.config/opencode/opencode.jsonc`
+   (backup trước khi sửa).
+6. Smoke test `lui_list`.
+7. Chạy `check-lark` trên `src/` đích (chỉ báo cáo, không fail cài).
+
+### Nếu app đã có CSS riêng (không dùng Tailwind từ đầu)
+
+CSS cũ đặt ngoài `@layer` sẽ **đè** utility của component (rule `button { font:
+inherit }` thắng `h-8`). Bọc CSS cũ vào `@layer base`:
+
+```css
+@import "tailwindcss";
+@import "lily-lark-ui/styles.css";
+@source "../node_modules/lily-lark-ui/src";
+
+@layer base {
+  /* toàn bộ CSS cũ của app ở đây */
+}
+```
+
+## Kiểm tra sau khi cài
+
+```bash
+npm run build          # phải PASS
+```
+
+Trong CSS build ra phải thấy utility của thư viện:
+
+```bash
+grep -c 'bg-brand-secondary' dist/assets/*.css   # > 0
+```
+
+Nếu bằng 0 → thiếu `@source` hoặc sai đường dẫn.
+
+## Chế độ tối
+
+Không dùng class `dark:`. Đặt `data-theme="dark"` trên `<html>`:
+
+```ts
+document.documentElement.dataset.theme = 'dark'
+```
+
+Token tự đổi. Nếu không set gì, thư viện theo `prefers-color-scheme` của hệ
+điều hành.
+
+## Lỗi thường gặp
+
+| Hiện tượng | Nguyên nhân | Cách sửa |
+|---|---|---|
+| Component không có style, nút trong suốt | Thiếu `@source` | Thêm `@source "../node_modules/lily-lark-ui/src"` |
+| `ENOENT: lily-lark-ui/styles.css` | Repo chưa có Tailwind, hoặc chưa `pnpm add` | Cài Tailwind v4 + package |
+| Style bị đè, chiều cao sai | CSS cũ ngoài `@layer` | Bọc CSS cũ vào `@layer base` |
+| Màu không đổi khi bật tối | Thiếu `[data-theme]` trên `<html>` | Set `data-theme` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LILY-EYE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# lily-lark-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Thu vien component React theo phong cach Lark (Universe Design), dung kieu shadcn:
+copy-paste component Tailwind v4 + Radix headless. Hien co 20 component.
+
+## Cài đặt
+
+Xem [INSTALL.md](./INSTALL.md) để biết đầy đủ. Tóm tắt 2 đường:
+
+- **CLI (khuyến nghị):** `npx lily-lark-ui init` — tự cài Tailwind v4, sửa
+  `vite.config.ts`, chèn CSS + `@source`.
+- npm thủ công: `pnpm add lily-lark-ui` rồi tự thêm 3 dòng CSS.
+- script: `scripts/install.sh --repo <path> --apply` (nếu dùng source checkout).
+
+### Yêu cầu bắt buộc
+
+| Thứ | Phiên bản | Ghi chú |
+|---|---|---|
+| **Tailwind CSS** | **v4** (`^4.0.0`) | Token dùng `@theme`/`@utility` của v4. **v3 không chạy.** |
+| `@tailwindcss/vite` | `^4.0.0` | Plugin build (không dùng PostCSS config kiểu v3). |
+| React / React DOM | `^19.0.0` | peerDependency. |
+| Node | `>= 20` | ESM + Vite hiện hành. |
+
+```bash
+npm i -D tailwindcss@^4 @tailwindcss/vite
+```
+
+### Ba dòng bắt buộc trong entry CSS
+
+Tailwind v4 **không tự quét `node_modules`**. Thiếu `@source` thì component
+render ra không có style (nút trong suốt, sai chiều cao) dù build không báo lỗi.
+
+```css
+@import "tailwindcss";
+@import "lily-lark-ui/styles.css";
+@source "../node_modules/lily-lark-ui/src";
+```
+
+`@import "tailwindcss"` phải đứng trước import của thư viện. Nếu app đã có CSS
+riêng, bọc CSS đó vào `@layer base` để không đè utility của component.
+
+Kiểm tra sau khi build: `grep -c 'bg-brand-secondary' dist/assets/*.css` phải
+lớn hơn 0.
+
+## Cai vao repo moi
+
+Mot lenh (6 buoc + kiem Tailwind v4, copy --components neu co, check-lark report):
+
+```bash
+scripts/install.sh --repo <path> --apply [--components button,text-field]
+```
+
+- Khong truyen `--apply` thi dry-run: chi in ke hoach, khong sua file.
+- `--skip-install`: bo qua buoc `pnpm add` (dung cho test offline).
+- `--components <list>`: chi copy component can (ten cach nhau boi dau phay,
+  vd `button,text-field`); kem `src/lib/utils.ts` + `src/styles/lark-tokens.css`
+  neu chua co. Ten sai thi bao loi + liet ke ten hop le.
+- Idempotent: chay lai khong them trung import/block MCP.
+
+## Component
+
+| Component | Import | Props chinh | So do |
+|---|---|---|---|
+| LarkButton | `import { LarkButton } from 'lily-lark-ui'` | `variant` (primary/secondary/danger/ghost/text), `size` (xs/sm/md/lg), `isIconOnly`, `fullWidth`, `isPending`, `asChild` | 32px mac dinh (h-8), 40px nut chinh form (h-10), 28/24 nho; mobile 36/48px |
+| LarkTextField (+inputClass) | `import { LarkTextField } from 'lily-lark-ui'` | `label`, `error`, `description`, `isRequired`, `isInvalid` | Cao 42 mobile / 36 PC (`md:min-h-9`), chu 16 mobile / 14 PC |
+| LarkDropdownMenu | `import { LarkDropdownMenu } from 'lily-lark-ui'` | `trigger`, `align` (start/center/end); `Item` (`value`, `onSelect?`, `danger?`, `disabled?`, `checked?`) | Popover toi thieu 200 rong, bo goc 8, bong overlay; item 32px, dropdown vien #DEE0E3 qua token; dong menu (Escape/chon/click ngoai) tra focus ve trigger, click lai dong menu |
+| LarkTabs | `import { LarkTabs } from 'lily-lark-ui'` | `defaultValue`/`value`/`onValueChange`, `LarkTabs.List/Tab/Panel` | Tab cao 34, gach duoi tab kich hoat |
+| LarkTooltip (+LarkTooltipProvider) | `import { LarkTooltip, LarkTooltipProvider } from 'lily-lark-ui'` | `content`, `side` (top/right/bottom/left); Provider `delayDuration` (=300), `skipDelayDuration?` | delay 300ms, lech 6, overlay 300ms ease-out; render doc lap van mo (fallback), trong Provider dung chung |
+| LarkTextArea | `import { LarkTextArea } from 'lily-lark-ui'` | `label`, `error`, `isRequired` (ke thua moi prop `textarea`) | toi thieu 72px (~3 dong), chu 16 mobile / 14 PC |
+| LarkSelect | `import { LarkSelect } from 'lily-lark-ui'` | `options`, `value`/`onValueChange`, `placeholder`, `disabled`, `isInvalid` | trigger 32px (`h-8`) bo 6 (`rounded-lg`), item 32px, dropdown bo 6 vien `#DEE0E3` qua token |
+| LarkCheckbox | `import { LarkCheckbox } from 'lily-lark-ui'` | `label`, `checked` (true/false/'indeterminate'), `onCheckedChange` | khung 16px (`size-4`) bo 4, dau `size-3` trang |
+| LarkRadioGroup | `import { LarkRadioGroup } from 'lily-lark-ui'` | `label?`, `options`, `value`/`onValueChange` | khung 16px tron, cham chon vien brand 5px |
+| LarkSwitch | `import { LarkSwitch } from 'lily-lark-ui'` | `label?`, `checked`/`onCheckedChange` | ranh 36x20 (`h-5 w-9`), num 16px trang |
+| LarkDialog | `import { LarkDialog } from 'lily-lark-ui'` | `open`/`onOpenChange`, `Content` (`title`, `description?`), `Footer` | bo 8 (`rounded-xl`), dem 20 mobile / 24 PC, toi da `max-w-md` |
+| LarkAlertDialog | `import { LarkAlertDialog } from 'lily-lark-ui'` | `title`, `confirmLabel`, `cancelLabel` (=`Huy`), `onConfirm`, `isPending` | khung nhu dialog; pending chan Escape + disable nut huy |
+| LarkToast (+Provider/useLarkToast) | `import { LarkToastProvider, useLarkToast } from 'lily-lark-ui'` | `toast({ title, description?, variant? })` (default/success/danger) | nen `n900`, bo 8 / pill mobile, hien 4s, quet phai de tat |
+| LarkSpinner / LarkEmptyState | `import { LarkSpinner, LarkEmptyState } from 'lily-lark-ui'` | Spinner `size` (sm/md), `label` bat buoc; EmptyState `icon`, `title`, `description?`, `action?` | spinner 16/24px xoay `n500`; empty can giua, icon 24px, dem doc 40px |
+| LarkTable (+Wrapper/Footer/TruncatedCell) | `import { LarkTable, LarkTableWrapper, LarkPagination } from 'lily-lark-ui'` | `columns`, `rows`, `rowKey`, `isLoading?`, `emptyState?`; cot `pin: 'right'`; caller tu boc `<LarkTable.Footer>` quanh `<LarkPagination>` | head 48 (`h-12`), body 47 (`h-[47px]`), divider `n200/n300`, ghim `z-10/z-20`, skeleton `animate-pulse` |
+| LarkPagination (+pageWindow) | `import { LarkPagination } from 'lily-lark-ui'` | `page`, `total`, `pageSize`, `onPageChange`, `pageSizes?` (mac dinh `[50, 100, 200]`), `onPageSizeChange?`, `isLoading?` | nut 28 (`size-7`), active 28x28 bo 6 (rounded-lg = --radius-lg 6px), footer `py-2 px-3`, pageWindow toi da 7 |
+| LarkTag | `import { LarkTag } from 'lily-lark-ui'` | `color` (blue/gray/success/danger/warning), `size` (md/sm) | cao 24 md (`h-6`) / 16 sm (`h-4`), bo 4 (`rounded-sm`) |
+| LarkBadge | `import { LarkBadge } from 'lily-lark-ui'` | `count?`, `max` (=`99`), `dot?` | cao 14 (`h-[14px]`), cham `size-2`, pill do `rounded-full` |
+| LarkAvatar (+getInitials) | `import { LarkAvatar } from 'lily-lark-ui'` | `name?`, `src?`, `team?`, `size` (sm/md/lg) | 20 sm (`size-5`) / 32 md (`size-8`) / 36 lg (`size-9`), team tron 36px (alias size lg) |
+
+## Nguon so do
+
+Moi so do trong thu vien lay tu `~/Sites/lily-projects/lark-design-guide`:
+uu tien mau noi bo `patterns/`, sau do so do goc Figma `figma/`
+(buttons, list, navigation, action-menu, feedback).
+Chi tiet xem `docs/specs/2026-11-05-lark-ui.md`.
+
+## Vi du
+
+```tsx
+import { LarkButton, LarkTextField } from 'lily-lark-ui'
+import 'lily-lark-ui/styles.css'
+
+export function LoginForm() {
+  return (
+    <form>
+      <LarkTextField label="So dien thoai" placeholder="Nhap so dien thoai" isRequired />
+      <LarkButton type="submit">Dang nhap</LarkButton>
+    </form>
+  )
+}
+```
+
+```tsx
+import { LarkTable, LarkTableWrapper, LarkPagination } from 'lily-lark-ui'
+
+export function RecordsTable({ columns, rows, page, total, pageSize, onPageChange }) {
+  return (
+    <LarkTableWrapper>
+      <LarkTable columns={columns} rows={rows} rowKey={(r) => r.id} />
+      <LarkTable.Footer>
+        <LarkPagination page={page} total={total} pageSize={pageSize} onPageChange={onPageChange} />
+      </LarkTable.Footer>
+    </LarkTableWrapper>
+  )
+}
+```
+
+## Phat trien
+
+Xem [AGENTS.md](./AGENTS.md) truoc khi sua code.