@hobui/viui-cli 0.0.2

package/README.md

@@ -0,0 +1,136 @@
+# @donan/cli (i-design-system CLI)
+
+CLI to sync i-design-system `.cursor` (rules, skills, commands, plans) into consumer repos. Use this so Cursor/AI in the consumer repo follows the same design system rules, tokens, and BEM conventions.
+
+**Scope:** Published under npm username `@donan`. If you published under a different scope, use that (e.g. `pnpm add @your-npm-username/cli`).
+
+## One-command UX (recommended)
+
+At the consumer repo root, run:
+
+```bash
+pnpm add @donan/cli
+```
+
+After install, **postinstall** runs an interactive **setup wizard** (only when the terminal is interactive — not in CI):
+
+1. **Step 1:** Init `.cursor` (rules, plans) and `src/plugins/viui-conf`, or sync if already present.
+2. **Step 2:** Optionally install `@viui/web` for Vi* components (`pnpm add @viui/web`).
+3. **Step 3:** Optionally add a postinstall script to auto-sync on future `pnpm install`.
+
+No need to run `viui-cli init` or `pnpm add @viui/web` separately. To run the wizard again: `pnpm exec viui-cli setup` (use `-y` to skip prompts).
+
+## Commands
+
+| Command   | Description |
+| --------- | ----------- |
+| `setup`   | Interactive wizard: init/sync .cursor, install @viui/web, optional postinstall. Runs automatically after `pnpm add @donan/cli` (postinstall). |
+| `init`    | Create `.cursor/` at repo root and copy rules, skills, commands (and optionally plans). Run once when onboarding. |
+| `sync`    | Update existing `.cursor/` from the design system (overwrite). Use after design system updates. |
+| `version` | Print CLI version and, if present, the synced design system version (from `.cursor/.design-system-version`). |
+
+## Usage at consumer repo
+
+**From npm (after publish) — one command:**
+
+```bash
+pnpm add @donan/cli
+# then follow the setup wizard (Y/n per step)
+```
+
+**Manual steps (if you skip the wizard):**
+
+```bash
+pnpm add -D @donan/cli
+pnpm exec viui-cli init
+pnpm add @viui/web
+```
+
+**Local development (from i-design-system monorepo):**
+
+1. Build the CLI from i-design-system root or `packages/cli`:
+
+   ```bash
+   pnpm build:cli
+   # or: cd packages/cli && pnpm build
+   ```
+
+2. From the consumer repo root (e.g. kpi-5):
+
+   ```bash
+   node path/to/i-design-system/packages/cli/dist/cli.js init
+   # or: pnpm exec --prefix path/to/i-design-system/packages/cli @donan/cli init
+   ```
+
+Always run `init` or `sync` from the **consumer repo root** (CWD = root). If you run from another folder (e.g. i-design-system), the wrong `.cursor` will be updated. The CLI logs `Syncing .cursor at: <path>` so you can confirm the target.
+
+**Auto-sync after install:** If the consumer has `@donan/cli` as a dependency (e.g. `"@donan/cli": "file:../../i-design-system/packages/cli"`), add a script so `.cursor` is synced automatically after each `pnpm install`:
+
+```json
+"scripts": {
+  "postinstall": "pnpm exec viui-cli sync"
+}
+```
+
+Run `setup:ds` (or `pnpm exec viui-cli init`) once when first onboarding the repo; after that, `postinstall` keeps `.cursor` in sync when dependencies are installed.
+
+## Init options
+
+| Option       | Description |
+| ------------ | ----------- |
+| `-y`, `--yes`   | Skip confirmation (no prompt). |
+| `--dry-run`     | Only print what would be copied; do not write files. |
+| `--no-plans`    | Do not sync `.cursor/plans`. |
+
+## Sync options
+
+Sync overwrites existing files from the design system bundle and **removes** any file or folder in your `.cursor/` that is not in the bundle (so your `.cursor/` mirrors the bundle; files excluded via `.cursorignore` at build time will be removed on sync).
+
+| Option            | Description |
+| ------------------ | ----------- |
+| `--dry-run`        | Only print what would be overwritten. |
+| `--backup`         | Backup existing files before overwrite (`.backup.<timestamp>`). |
+| `--rules-only`      | Sync only `.cursor/rules`. |
+| `--skills-only`     | Sync only `.cursor/skills`. |
+| `--commands-only`  | Sync only `.cursor/commands`. |
+
+## What gets synced
+
+- **rules** — Design system rules (tokens, BEM, component naming, Storybook, etc.).
+- **skills** — Cursor skills for design system and accessibility.
+- **commands** — Cursor commands (e.g. audit, generate from Figma).
+- **plans** — Optional plan docs (e.g. KPI template); use `--no-plans` on init to skip.
+
+After init/sync, `.cursor/.design-system-version` contains the design system version (from i-design-system at CLI build time).
+
+**For AI-generated code (Cursor / AI Agent):** Synced rules apply to **codegen** in the consumer repo. When generating Vue, Storybook or UI code, the agent must: (1) use **Vi\*** components from `@viui/web` (ViButton, ViInput, ViCard, ViMenu, ViButtonToggle, …) instead of raw Vuetify where available; (2) use **Tabler Icons** (`@tabler/icons-vue`) as the default icon set; (3) follow `.cursor/rules/storybook.mdc` (title, CSF3, vi-ui in stories) and `.cursor/rules/icons.mdc`. See also AGENTS.md in the design system repo (§ Codegen / AI Agent, § Rules 3 and 7) and `.cursor/plans/icons_free_sources.plan.md` if plans were synced.
+
+**viui-conf:** Init and sync also copy the design system's **Vuetify config folder** (theme-base, v-light, v-dark, defaults) to **`src/plugins/viui-conf/`** in the consumer repo. The file **`vuetify.ts`** is **not** synced — you keep your own `src/plugins/vuetify.ts` and import from `./viui-conf` (e.g. `import { defaults } from './viui-conf/defaults'`, `import LightTheme from './viui-conf/v-light'`). See [packages/docs/consumer-update.md](../docs/consumer-update.md) (§4).
+
+### Excluding files when building the CLI (`.cursorignore`)
+
+In **packages/cli**, the file **`.cursorignore`** is read by the copy script when building the CLI. Paths matching its patterns are not copied from i-design-system `.cursor/` into `dist/assets/cursor/`, so they are not synced to consumers. One pattern per line; lines starting with `#` and empty lines are ignored. Supported patterns:
+
+- **`filename`** — skip any file or folder with this name (e.g. `KPI_COMPONENT_TEMPLATE.md`).
+- **`*.ext`** — skip any file whose name ends with `.ext` (e.g. `*.plan.md`, `*.log`).
+- **`category/path`** — skip the path under that category (e.g. `plans/CLI_BUILD.plan.md`).
+
+Edit `packages/cli/.cursorignore` and run `pnpm build` in packages/cli (or `pnpm build:cli` from root) for changes to take effect.
+
+## Design system package
+
+To use components in the consumer app, install the design system package:
+
+```bash
+pnpm add @viui/web
+```
+
+Then import components: `import { ViButton, ViInput, ... } from '@viui/web'`. See [CLI_BUILD.plan.md](../../.cursor/plans/CLI_BUILD.plan.md) and root README for full setup.
+
+## Build
+
+```bash
+pnpm build
+```
+
+Runs `tsc` and copies `.cursor` from repo root into `dist/assets/cursor/`, and writes `.design-system-version` from root `package.json`. Published package includes `dist/` so `npx @donan/cli init` works without the source repo.

package/dist/assets/cursor/.design-system-version

@@ -0,0 +1 @@
+0.0.0

package/dist/assets/cursor/commands/audit-accessibility.md

@@ -0,0 +1,25 @@
+---
+name: audit accessibility
+description: Chạy/addon a11y, liệt kê lỗi (contrast, ARIA, keyboard); ưu tiên sửa color-contrast theo accessibility-contrast.mdc.
+---
+
+Bạn là chuyên gia accessibility cho design system.
+
+**Nhiệm vụ:** Kiểm tra (audit) accessibility của component hoặc story và đưa ra danh sách lỗi + hướng sửa.
+
+## Các bước
+
+1. **Xác định phạm vi** — Một story, một component, hay toàn bộ Storybook. Nếu user không chỉ rõ, ưu tiên story/component đang mở hoặc vừa sửa.
+2. **Liệt kê lỗi a11y** — Dựa trên:
+   - Addon a11y (Storybook) hoặc axe: color-contrast, aria-*, role, label, focus, keyboard.
+   - Code review: thiếu aria-label, thiếu role, màu chữ/nền không đạt WCAG AA.
+3. **Ưu tiên sửa** — Ưu tiên **color-contrast** (WCAG 2.1 AA): theo `.cursor/rules/accessibility-contrast.mdc` (text.disabled, semantic .text trên nền màu, #000/#fff trên swatch). Sau đó: ARIA, keyboard, focus.
+4. **Đề xuất chỉnh sửa** — Với mỗi lỗi, đề xuất thay đổi cụ thể (file, dòng, token hoặc attribute).
+
+## Tham chiếu
+
+- Rule contrast: `.cursor/rules/accessibility-contrast.mdc`
+- Skill a11y (gồm color contrast): `.cursor/skills/accessibility.md`
+- AGENTS.md: mục "Color contrast (WCAG AA)"
+
+Đầu ra: danh sách lỗi (mức độ nếu có) + patch hoặc hướng dẫn sửa từng mục.

package/dist/assets/cursor/commands/audit-ui.md

@@ -0,0 +1,35 @@
+---
+name: audit UI
+description: Audit tổng thể UI — a11y (contrast, ARIA, keyboard), tokens (không hard-code), và tùy chọn drift so với Figma. Gọi audit-accessibility cho phần a11y.
+---
+
+Bạn là chuyên gia audit giao diện cho design system.
+
+**Nhiệm vụ:** Kiểm tra (audit) **tổng thể** component, story hoặc trang theo: (1) **Accessibility**, (2) **Tokens** (không hard-code màu/spacing/typography), (3) **Figma drift** (tùy chọn — so với design nếu có).
+
+## Các bước
+
+1. **Xác định phạm vi** — Một story, một component, một trang, hay một nhóm. User có thể chỉ rõ; nếu không, ưu tiên file đang mở hoặc vừa sửa.
+
+2. **Audit Accessibility** — Áp dụng cùng quy trình command **audit-accessibility**:
+   - Addon a11y / axe: color-contrast, ARIA, role, label, focus, keyboard.
+   - Ưu tiên color-contrast (WCAG 2.1 AA) theo `.cursor/rules/accessibility-contrast.mdc`; sau đó ARIA, keyboard, focus.
+   - Tham chiếu: `.cursor/commands/audit-accessibility.md`, `.cursor/skills/accessibility.md`.
+
+3. **Audit Tokens** — Kiểm tra code không hard-code giá trị thiết kế:
+   - Màu: dùng `colorTokens`, `inetDesignTokens`, hoặc theme Vuetify từ tokens; không hex/rgba trực tiếp cho quyết định thiết kế.
+   - Spacing/typography: dùng `spacingTokens`, `typographyTokens` hoặc theme; không px/rem cố định cho layout/type.
+   - Tham chiếu: `.cursor/rules/tokens.mdc`, `src/tokens/design-tokens.ts`.
+
+4. **Audit Figma drift (tùy chọn)** — Nếu user cung cấp Figma URL hoặc bản thiết kế: so sánh layout, màu, spacing với code; liệt kê chênh lệch; đề xuất chỉnh code hoặc cập nhật token/Figma. Tham chiếu `.cursor/rules/figma-mapping.mdc`.
+
+5. **Tổng hợp** — Đầu ra: danh sách lỗi/theo từng mục (a11y, tokens, drift) + mức độ + hướng sửa (file, dòng, token hoặc attribute). Với a11y, có thể trỏ trực tiếp tới command **audit-accessibility** để xử lý chi tiết.
+
+## Tham chiếu
+
+- **A11y (chi tiết):** `.cursor/commands/audit-accessibility.md`, `.cursor/rules/accessibility-contrast.mdc`, `.cursor/skills/accessibility.md`
+- **Tokens:** `.cursor/rules/tokens.mdc`
+- **Figma:** `.cursor/rules/figma-mapping.mdc`, `.cursor/skills/figma-interpretation.md`
+- **AGENTS.md:** mục Color contrast và rules bắt buộc
+
+Đầu ra: báo cáo audit (a11y + tokens [+ drift nếu có]) + danh sách lỗi và hướng sửa.

package/dist/assets/cursor/commands/component.md

@@ -0,0 +1,18 @@
+---
+name: component
+description: Tạo component Vue mới hoặc gợi ý reuse từ design system hiện có, theo Vuetify primitives.
+---
+
+Bạn là chuyên gia Vue 3 + Vuetify cho design system.
+
+Luôn ưu tiên:
+1. Reuse component hiện có từ src/components/ui/ hoặc Vuetify built-ins (VBtn, VCard, VInput, v.v.).
+2. Nếu tạo mới: dùng Composition API, props với defineProps, emits với defineEmits.
+3. Áp dụng theme từ Vuetify: useTheme() hook, colors từ $vuetify.theme.current.colors.primary, v.v.
+4. Đảm bảo accessibility: aria-label, role, v-bind cho states (disabled, loading).
+5. Naming: PascalCase cho component (MyButton.vue), kebab-case cho props/events.
+6. Output: 
+   - Code full component (.vue file)
+   - Folder gợi ý: src/components/atoms/buttons/Button.vue
+   - Props default + types (PropType nếu cần)
+   - Example usage: <Button variant="primary">Label</Button>

package/dist/assets/cursor/commands/fix-storybook.md

@@ -0,0 +1,24 @@
+---
+name: fix storybook
+description: Sửa lỗi story (title, CSF3, controls, a11y); đảm bảo đúng cấu trúc sidebar và rule storybook.mdc.
+---
+
+Bạn là chuyên gia Storybook cho design system Vue 3 + Vuetify.
+
+**Nhiệm vụ:** Sửa lỗi hoặc cải thiện story hiện tại (file `*.stories.ts` hoặc cấu hình `.storybook/`).
+
+## Cần kiểm tra và sửa
+
+1. **Cấu trúc sidebar** — Story title đúng hierarchy: `Foundations/Colors`, `vi-ui/Button`, `Brands/Logo`, `Errors/ErrorPage`, v.v. Thứ tự nhóm theo `.storybook/preview.ts` (Introduction → Foundations → vi-ui → Brands → Errors → Icons).
+2. **CSF3 + TypeScript** — `satisfies Meta<typeof Component>`, `StoryObj<typeof meta>`, import từ `@storybook/vue3-vite`; đủ `argTypes` và `args` mặc định.
+3. **Controls & docs** — Prop quan trọng có `control` và `description`; `tags: ["autodocs"]` khi cần; events dùng `fn()`.
+4. **Vuetify & tokens** — Story dùng theme/tokens từ design system; không override CSS tùy tiện.
+5. **Accessibility** — Chạy addon a11y nếu có; sửa lỗi color-contrast theo `.cursor/rules/accessibility-contrast.mdc`.
+
+## Tham chiếu
+
+- Rule: `.cursor/rules/storybook.mdc`
+- Config: `.storybook/main.ts`, `preview.ts`
+- Mẫu: `src/design-system/vi-ui/vi-button/ViButton.stories.ts`
+
+Đầu ra: chỉnh sửa cụ thể (file, đoạn code) để story đúng cấu trúc và không lỗi.

package/dist/assets/cursor/commands/generate-component-from-figma.md

@@ -0,0 +1,26 @@
+---
+name: generate component from Figma
+description: Nhận Figma URL/node, sinh hoặc cập nhật component Vue + story theo design; bám tokens, component-naming.mdc và storybook.mdc.
+---
+
+Bạn là chuyên gia chuyển component Figma sang code Vue 3 + Vuetify cho design system.
+
+**Nhiệm vụ:** Từ Figma URL (và node-id nếu có), lấy design rồi sinh hoặc cập nhật **component** Vue và story tương ứng, đúng naming và tokens.
+
+## Các bước
+
+1. **Lấy design** — User cung cấp Figma URL. Trích `fileKey`, `nodeId`. Nếu có MCP: gọi `get_design_context(fileKey, nodeId?)`. Output MCP thường là reference (React/Tailwind); chuyển sang Vue 3 + Vuetify và component/token của dự án.
+2. **Map tokens** — Màu → `colorTokens.*` / `inetDesignTokens.colors.*`; spacing → `spacingTokens`; radius → `shapeTokens`; typography → `typographyTokens`. Không thêm giá trị mới ngoài token trừ khi đã cập nhật `design-tokens.ts`. Tham chiếu `.cursor/rules/figma-mapping.mdc`.
+3. **Chọn hoặc tạo component** — Nếu đã có Vi* hoặc component trong `src/components/` khớp design → đề xuất dùng lại hoặc mở rộng. Nếu tạo mới: đặt đúng NHÓM và vị trí theo `.cursor/rules/component-naming.mdc` và `.cursor/rules/design-system-workflow.mdc` (vi-ui → `src/design-system/vi-ui/vi-<tên>/ViName.vue`; Brands/Errors/Icons → `src/components/<nhóm>/`).
+4. **Sinh component + story** — Component: `<script setup>`, `defineProps`, `defineEmits`; dùng Vuetify và tokens. Story: `ComponentName.stories.ts` cùng thư mục; `title` = `{Nhóm}/{Tên}` theo `.cursor/rules/storybook.mdc`; CSF3, argTypes, args mặc định.
+5. **Kiểm tra** — Story chạy đúng; contrast và a11y đạt; không hard-code màu/spacing; export qua `src/design-system/vi-ui/index.ts` nếu là Vi*.
+
+## Tham chiếu
+
+- Rule Figma: `.cursor/rules/figma-mapping.mdc`
+- Skill Figma: `.cursor/skills/figma-interpretation.md`
+- Naming: `.cursor/rules/component-naming.mdc`, `.cursor/rules/design-system-component-library.mdc`
+- Storybook: `.cursor/rules/storybook.mdc`
+- Tokens: `.cursor/rules/tokens.mdc`, `src/tokens/design-tokens.ts`
+
+Đầu ra: component Vue (.vue) + story (.stories.ts) hoặc patch; đúng thư mục và naming.

package/dist/assets/cursor/commands/generate-page-from-figma.md

@@ -0,0 +1,26 @@
+---
+name: generate page from Figma
+description: Nhận Figma URL/node, dùng MCP get_design_context (và get_screenshot nếu có), sinh hoặc cập nhật page/story/route theo design; bám tokens và rules (figma-mapping.mdc, storybook.mdc).
+---
+
+Bạn là chuyên gia chuyển design Figma sang code cho design system Vue 3 + Vuetify.
+
+**Nhiệm vụ:** Từ Figma URL (và node-id nếu có), lấy design context rồi sinh hoặc cập nhật **page** (story, route, hoặc trang foundation) theo đúng tokens và cấu trúc dự án.
+
+## Các bước
+
+1. **Lấy thông tin Figma** — User cung cấp URL (vd `figma.com/design/<fileKey>/...?node-id=...`). Trích `fileKey` và `nodeId` (đổi `-` thành `:` trong node-id nếu cần). Nếu có MCP Figma: gọi `get_design_context(fileKey, nodeId?)` để lấy code/screenshot/hints.
+2. **Phân tích design** — Xác định sections, layout, components dùng, màu/spacing/typography. Map giá trị Figma sang token: màu → `colorTokens.*` / `inetDesignTokens.colors.*`; spacing → `spacingTokens`; typography → `typographyTokens`. Không hard-code; tham chiếu `.cursor/rules/tokens.mdc` và `.cursor/rules/figma-mapping.mdc`.
+3. **Chọn đầu ra** — Page có thể là: (a) story trong `src/storybook/Foundations/` (vd page Colors, Typography), (b) story cho nhóm vi-ui/Brands/Errors, hoặc (c) route/view nếu dự án có router. Đặt đúng thư mục và `title` theo `.cursor/rules/storybook.mdc` (`{Nhóm}/{Tên}`).
+4. **Sinh/cập nhật code** — Vue 3 + Vuetify, Composition API; dùng component và tokens có sẵn. Thêm hoặc sửa file story/route; đảm bảo không có `[object Object]` hay chuỗi render lỗi.
+5. **Kiểm tra** — Story chạy đúng; color contrast và a11y đạt WCAG AA (`.cursor/rules/accessibility-contrast.mdc`).
+
+## Tham chiếu
+
+- Rule Figma: `.cursor/rules/figma-mapping.mdc`
+- Skill Figma: `.cursor/skills/figma-interpretation.md`
+- Tokens: `.cursor/rules/tokens.mdc`, `src/tokens/design-tokens.ts`
+- Storybook: `.cursor/rules/storybook.mdc`
+- Contrast: `.cursor/rules/accessibility-contrast.mdc`
+
+Đầu ra: file mới hoặc patch (story, route, hoặc page) bám design và tokens; gợi ý chỉnh nếu Figma lệch token.

package/dist/assets/cursor/plans/DESIGN_SYSTEM_PLAN.md

@@ -0,0 +1,177 @@
+---
+name: Design System Plan (tập trung)
+overview: Một file plan duy nhất cho iNET Design System — Workflow lớn (thêm mới, tìm kiếm, tổng kết), NHÓM, phase, foundation, Figma, tích hợp, SaaS/vi-ui, locale, chất lượng, roadmap. Quản lý tập trung, dễ tìm kiếm.
+todos: []
+isProject: false
+---
+
+# iNET Design System — Plan tập trung
+
+**Rule workflow:** `.cursor/rules/design-system-workflow.mdc`  
+**Mục tiêu chi tiết:** [docs/design-system-plan.md](docs/design-system-plan.md)
+
+---
+
+## Mục lục (tìm nhanh)
+
+1. [I. Workflow lớn](#i-workflow-lớn) — NHÓM, thêm mới, tìm kiếm, tổng kết
+2. [II. Tổng quan phase](#ii-tổng-quan-phase) — Phase hiện tại, thiếu sót
+3. [III. Foundation](#iii-foundation) — Design principles, token system, Storybook structure
+4. [IV. Figma → page/component](#iv-figma--pagecomponent) — Quy trình, checklist
+5. [V. Tích hợp nền tảng](#v-tích-hợp-nền-tảng) — Figma, v0, bolt, Vercel, Lovable
+6. [VI. SaaS / vi-ui](#vi-saas--vi-ui) — Folder, token 8pt, Vi*, ESLint
+7. [VII. Locale & song ngữ Storybook](#vii-locale--song-ngữ-storybook) — Toolbar locale, i18n
+8. [VIII. Chất lượng](#viii-chất-lượng) — No hardcode màu, audit
+9. [IX. Roadmap & ưu tiên](#ix-roadmap--ưu-tiên) — Thứ tự thực hiện, bắt đầu từ đâu
+10. [X. Mở rộng](#x-mở-rộng) — Quy ước thêm plan, NHÓM, rule, command, skill
+
+---
+
+## I. Workflow lớn
+
+Workflow = **thêm mới**, **tìm kiếm**, **tổng kết**. Mọi item (component, token, doc) thuộc đúng **NHÓM**.
+
+### 1. NHÓM (7 nhóm)
+
+| NHÓM | Vị trí code | Items ví dụ |
+|------|-------------|-------------|
+| **vi-ui** | `src/design-system/vi-ui/vi-<tên>/` | ViButton, ViInput, ViCard, ViAlert, ViDialog, … |
+| **Brands** | `src/components/brands/` | BrandLogo, StyleGuide |
+| **Errors** | `src/components/errors/` | ErrorPage, OvvErrorPage, … |
+| **Icons** | `src/components/icons/` | ArrowLeftRight, … |
+| **Tokens** | `src/tokens/` | design-tokens.ts, inet-design-tokens.ts |
+| **Docs** | `src/docs/`, `docs/` | design-system.md, integration-guide.md |
+| **Storybook foundations** | `src/storybook/Foundations/` | Colors, Typography, SpacingLayout, Configure.mdx |
+
+Không tạo item “lạc” ngoài các NHÓM trên.
+
+### 2. Thêm mới — Bước chuẩn
+
+1. **Chọn NHÓM** — vi-ui, Brands, Errors, Icons, Tokens, Docs, hoặc Storybook foundations.
+2. **Tạo đúng vị trí** — Theo `.cursor/rules/project-structure.mdc`, `.cursor/rules/component-naming.mdc`. Ví dụ: Vi* → `src/design-system/vi-ui/vi-<tên>/ViName.vue` + `ViName.stories.ts`.
+3. **Cập nhật index/re-export** — Ví dụ `src/design-system/vi-ui/index.ts` nếu thêm Vi*.
+4. **Story/docs** — Component mới có story; token/docs cập nhật nếu cần.
+
+**Command theo ngữ cảnh:** Từ Figma → `generate-page-from-figma`, `generate-component-from-figma`. Tạo component thuần → `component`. Sửa story → `fix-storybook`.
+
+### 3. Tìm kiếm
+
+- **Theo tên** — Search codebase, Storybook sidebar, docs.
+- **Theo NHÓM** — Mở thư mục (vd `src/design-system/vi-ui/`, `src/tokens/`).
+
+### 4. Tổng kết
+
+- **Số NHÓM:** 7. **Số items:** đếm theo nhóm.
+- **Trạng thái:** documented, có story, dùng token — dùng cho review/QA.
+- **Command:** `audit-accessibility`, `audit-ui` (a11y + tokens + drift).
+
+---
+
+## II. Tổng quan phase
+
+**Phase 1 (Foundation):** Project structure Done; Design tokens Done; Vuetify theme Done; Design principles 1 trang Done; Storybook token preview Done. Còn rà soát: manager.ts dùng design-tokens; 8pt spacing; doc TS↔SCSS trong tokens.mdc.
+
+**Phase 2 (vi-ui):** ViButton, ViInput, ViSelect, ViCheckbox, ViCard, ViAlert, ViDialog, ViDataTable, ViPagination, ViAvatar, ViMenu — Done. Thiếu: Badge, Dropdown, Tooltip, Tabs, Accordion, Navigation, Breadcrumb.
+
+**Phase 3–5:** Composite (ViDropdown, ViTooltip, ViTabs…); Data & Navigation; Forms & Templates; Docs & Polish (Getting Started, CHANGELOG, npm package tùy chọn).
+
+**Thiếu sót chung:** manager.ts từ design-tokens; 8pt document; stylelint no raw color; ViSkeleton/ViEmptyState; CHANGELOG/semver; migration app → Vi*; Design Principles “Atoms” → “vi-ui”.
+
+---
+
+## III. Foundation
+
+**Mục tiêu:** (1) Design principles 1 trang, (2) Token system một nguồn, (3) Storybook structure cố định.
+
+**Design principles:** Một file (vd `src/docs/foundations/design-principles.md`) — Simple – Secure – Stable + 4 trụ cột (Human-Centered, Clarity & Consistency, Motion & Meaning, Adaptivity). Link từ design-system.md; tùy chọn MDX Introduction trong Storybook.
+
+**Token system:** design-tokens.ts = single source of truth. Cập nhật `.storybook/manager.ts` import color từ design-tokens. Document quy ước TS↔SCSS trong tokens.mdc/design-system.md. Legacy inet-design-tokens: deprecate hoặc ghi rõ “tương thích”.
+
+**Storybook structure:** Sidebar order trong `.storybook/preview.ts`: Introduction → Foundations → vi-ui → Brands → Errors → Icons. Title thống nhất: `Foundations/Colors`, `Brands/Logo`, `Errors/ErrorPage`. Document trong storybook.mdc.
+
+---
+
+## IV. Figma → page/component
+
+**Quy trình:** (1) Input Figma URL + node-id; (2) MCP `get_design_context(fileKey, nodeId?)`; (3) Map tokens (màu, spacing, radius, typography); (4) Chọn đầu ra: page (Foundations/route) hoặc component (vi-* hoặc components/); (5) Sinh/cập nhật Vue + Vuetify, không hard-code; (6) Kiểm tra contrast và a11y.
+
+**Command:** `.cursor/commands/generate-page-from-figma.md`, `.cursor/commands/generate-component-from-figma.md`. **Rule:** `.cursor/rules/figma-mapping.mdc`. **Skill:** `.cursor/skills/figma-interpretation.md`.
+
+**Checklist:** Figma URL rõ; MCP đã gọi; tokens không hard-code; đúng vị trí và naming; story title `{Nhóm}/{Tên}`; a11y đạt.
+
+---
+
+## V. Tích hợp nền tảng
+
+**Mục tiêu:** Một bộ quy tắc UI (tokens, 8pt, Vi*) khi dùng Figma, v0, bolt.new, Vercel, Lovable, Framer AI, designcode.io.
+
+**Nguồn chung:** design-tokens.ts, inet-tokens.scss; docs/AI-prompt-rules.md; vi-ui index. **Deliverable:** [docs/integration-guide.md](docs/integration-guide.md) — từng nền tảng: chỗ paste prompt, link Storybook, quy trình sync (nếu có).
+
+**Figma:** Variables trùng tên token; Dev Mode lấy giá trị từ tokens. **v0/Lovable/Framer:** Paste Universal/Minimal; output = reference; port sang Vue + Vi* khi production. **bolt.new:** Paste Developer + Universal; project Vue dùng Vi* + tokens. **Vercel:** Deploy Storybook, output `storybook-static`; URL trong integration-guide.
+
+---
+
+## VI. SaaS / vi-ui
+
+**Folder:** Vi* trong `src/design-system/vi-ui/vi-<tên>/`; export từ `vi-ui/index.ts`. App chỉ import Vi*.
+
+**Token:** 8pt spacing (space.1=8px, 2=16px, …); semantic color only; single source design-tokens.ts; Vi* không raw #hex/rgba/8px.
+
+**Theme:** Vuetify theme từ tokens; Vi* dùng `color="primary"` xuống v-btn, không style background trực tiếp. **Design style themes** (minimalist-2, neo-brutalism): mỗi theme tương ứng bộ default variants; cấu hình theo [themes.plan.md](themes.plan.md) — viui-conf by-theme, getDefaults(themeId), VITE_VIUI_THEME.
+
+**ESLint:** no-restricted-imports — cấm import Vuetify components ngoài vi-ui và plugins. (Tùy chọn) no raw color ngoài tokens/styles.
+
+**Vi*:** Một wrapper một Vuetify component; props semantic; forward attrs + slots; token-only styling.
+
+---
+
+## VII. Locale & song ngữ Storybook
+
+**Locale integration:** Toolbar locale (preview.ts) đổi được vi/en. Mục tiêu: description/intro theo locale (ít nhất Docs tab). Decorator cấp story (không global); helper `createLocaleIntroDecorator(viBlock, enBlock)`. Foundations: description theo locale ở Docs.
+
+**Bilingual academic:** Song ngữ (vi/en) + thuật ngữ học thuật (common + semantic) cho Docs. File locale: `src/locales/vi.json`, `src/locales/en.json`; namespace introduction, foundations, viUi, brands, errors. Có thể dùng vue-i18n trong preview; stories import JSON hoặc `t()`.
+
+---
+
+## VIII. Chất lượng
+
+**No hardcode màu:** Colors.stories, Typography.stories, SpacingLayout.stories, Configure.mdx — chỉ dùng `colorTokens`/`inetDesignTokens` hoặc `var(--color-*)`. Thay hex/rgba trong UI story bằng token. Viết `src/docs/foundations/color.md` ghi quy ước no hardcode. Grep kiểm tra không còn literal màu trong .vue/.ts/.mdx (trừ tokens và SCSS).
+
+**Audit:** Command `audit-accessibility` — a11y (contrast, ARIA, keyboard). Command `audit-ui` — a11y + tokens (no hardcode) + tùy chọn Figma drift.
+
+---
+
+## IX. Roadmap & ưu tiên
+
+**Thứ tự gợi ý:**
+
+1. **Rà soát foundation** — manager.ts từ design-tokens; 8pt và TS↔SCSS trong tokens.mdc; Design Principles “Atoms” → “vi-ui”.
+2. **No hardcode** — Colors/Typography/SpacingLayout stories + docs chỉ tokens.
+3. **Component** — Chọn 2–3 ưu tiên (ViTooltip, ViTabs, Navigation) theo sản phẩm.
+4. **Figma → page/component** — Dùng quy trình mục IV và commands.
+5. **Docs & locale** — Getting Started, migration guide; song ngữ Storybook nếu cần.
+6. **Tùy chọn** — Vercel URL, CLI idesign rules, Figma token sync, npm package.
+
+**Bắt đầu từ đâu:** (1) Cần thêm item → chọn NHÓM → bước chuẩn mục I.2; từ Figma → mục IV. (2) Cần tìm → mục I.3. (3) Cần tổng kết/ưu tiên → mục II + IX.
+
+---
+
+## X. Mở rộng
+
+**Plan:** Mở rộng = thêm section (X, XI, …) trong file này. Không tách file plan mới trừ khi có nhu cầu đặc biệt. Giữ một file `.md` trong `plans/` (quy ước: chỉ `.md`, không `.plan.md`).
+
+**NHÓM mới:** Khi thêm NHÓM → cập nhật mục I (bảng NHÓM), `.cursor/rules/design-system-workflow.mdc`, và `docs/design-system-plan.md`.
+
+**Rule / Command / Skill:** Thêm file mới trong đúng thư mục (rules/ chỉ .mdc; commands/ và skills/ .md). Cập nhật `.cursor/INDEX.md` để liệt kê mục mới.
+
+---
+
+## Tham chiếu nhanh
+
+- **Chỉ mục .cursor:** [.cursor/INDEX.md](.cursor/INDEX.md) — bảng rules, commands, skills, plans
+- **Workflow rule:** `.cursor/rules/design-system-workflow.mdc`
+- **Mục tiêu:** [docs/design-system-plan.md](docs/design-system-plan.md), [AGENTS.md](AGENTS.md)
+- **Tokens:** [src/tokens/design-tokens.ts](src/tokens/design-tokens.ts), [.cursor/rules/tokens.mdc](.cursor/rules/tokens.mdc)
+- **Storybook:** [.cursor/rules/storybook.mdc](.cursor/rules/storybook.mdc)
+- **Commands:** `.cursor/commands/` (generate-page-from-figma, generate-component-from-figma, audit-accessibility, audit-ui, fix-storybook, component)
+- **Integration:** [docs/integration-guide.md](docs/integration-guide.md), [docs/AI-prompt-rules.md](docs/AI-prompt-rules.md)

package/dist/assets/cursor/plans/PLANS_INDEX.md

@@ -0,0 +1,35 @@
+# .cursor/plans — Chỉ mục (plan tập trung)
+
+**Entry point:** **[DESIGN_SYSTEM_PLAN.md](DESIGN_SYSTEM_PLAN.md)** — Một file plan duy nhất: Workflow lớn (thêm mới, tìm kiếm, tổng kết), NHÓM, phase, foundation, Figma, tích hợp, SaaS/vi-ui, locale, chất lượng, roadmap.
+
+**KPI — Component mẫu & template:** **[KPI_COMPONENT_TEMPLATE.md](KPI_COMPONENT_TEMPLATE.md)** — Checklist: Button variants/sizes/states, Storybook template chuẩn, kiểm tra Cursor generate story đúng format. *(Nếu file không có trong .cursor/plans/ sau sync, xem bản gốc tại repo i-design-system.)*
+
+**Themes — Design style & default variants:** **[themes.plan.md](themes.plan.md)** — Hài hòa Themes (minimalist-2, neo-brutalism) với Vuetify variants; viui-conf by-theme, getDefaults(themeId), cấu hình vuetify.ts theo VITE_VIUI_THEME; triển khai từng bước.
+
+---
+
+## Cấu trúc trong DESIGN_SYSTEM_PLAN.md (tìm nhanh)
+
+| Phần | Nội dung |
+|------|----------|
+| **KPI — Component mẫu** | [KPI_COMPONENT_TEMPLATE.md](KPI_COMPONENT_TEMPLATE.md) — Checklist Button + template Storybook + kiểm tra Cursor |
+| **I. Workflow lớn** | NHÓM (7), thêm mới (bước chuẩn + command), tìm kiếm, tổng kết |
+| **II. Tổng quan phase** | Phase 1–5, thiếu sót so với design-system-plan |
+| **III. Foundation** | Design principles, token system, Storybook structure |
+| **IV. Figma → page/component** | Quy trình MCP, mapping token, checklist; commands generate-page/component-from-figma |
+| **V. Tích hợp nền tảng** | Figma, v0, bolt, Vercel, Lovable; integration-guide |
+| **VI. SaaS / vi-ui** | Folder, token 8pt, Vi*, ESLint |
+| **VII. Locale & song ngữ Storybook** | Toolbar locale, i18n vi/en |
+| **VIII. Chất lượng** | No hardcode màu, audit-accessibility, audit-ui |
+| **IX. Roadmap & ưu tiên** | Thứ tự thực hiện, bắt đầu từ đâu |
+| **X. Mở rộng** | Quy ước thêm plan, NHÓM, rule, command, skill |
+| **Themes (plan riêng)** | [themes.plan.md](themes.plan.md) — Theme id ↔ default variants, viui-conf by-theme, getDefaults, VITE_VIUI_THEME |
+
+---
+
+## Tóm tắt
+
+- **Bắt đầu:** Mở [DESIGN_SYSTEM_PLAN.md](DESIGN_SYSTEM_PLAN.md) — đủ workflow, NHÓM, phase, và từng chủ đề trong một file.
+- **KPI component mẫu:** Mở [KPI_COMPONENT_TEMPLATE.md](KPI_COMPONENT_TEMPLATE.md) — checklist từng bước; tick `[x]` khi hoàn thành.
+- **Tìm nhanh:** Dùng mục lục (TOC) trong file plan hoặc bảng trên.
+- **Rule workflow:** `.cursor/rules/design-system-workflow.mdc`. **Mục tiêu:** `docs/design-system-plan.md`.

package/dist/assets/cursor/rules/accessibility-contrast.mdc

@@ -0,0 +1,38 @@
+---
+description: Accessibility & WCAG AA color contrast — chữ/nền ≥ 4.5:1; semantic .text trên nền màu; #000/#fff trên swatch. Skill a11y: .cursor/skills/accessibility.md
+globs: src/**/*.{vue,ts,tsx,jsx}, src/storybook/**/*
+alwaysApply: false
+---
+
+# Accessibility (Color contrast WCAG AA)
+
+Mọi chữ và nền phải đạt **WCAG 2.1 AA**: chữ thường ≥ 4.5:1, chữ lớn (18pt+ hoặc 14pt đậm) ≥ 3:1. Tham chiếu: [Deque color-contrast](https://dequeuniversity.com/rules/axe/4.11/color-contrast?application=axeAPI).
+
+## Quy tắc bắt buộc
+
+1. **Không dùng `colorTokens.text.disabled` cho nội dung đọc được**  
+   Chỉ dùng cho trạng thái disabled thật (control bị tắt). Body text, label, caption dùng `text.primary` hoặc `text.secondary` trên nền có tương phản đủ.
+
+2. **Chữ trên nền có màu (success, warning, error, info)**  
+   Luôn dùng **semantic .text** tương ứng (vd: `colors.success.light.text` trên `colors.success.light.surface`). Không thay bằng neutral 400/500/600 cho mô tả.
+
+3. **Chữ trên swatch / ô màu**  
+   Dùng màu đặc theo luminance: `#000` khi nền sáng (lum > 0.5), `#fff` khi nền tối (lum ≤ 0.5). Tránh rgba với opacity thấp.
+
+4. **Tag / pill / chip trên swatch hoặc nền đặc biệt**  
+   Chọn màu chữ và nền pill theo luminance nền bên dưới để cặp đạt ≥ 4.5:1.
+
+5. **Token secondary / subtle**  
+   Chỉ dùng khi cặp với nền đã kiểm tra. Nếu nghi ngờ, dùng bậc đậm hơn (neutral 600/700 thay cho 400/500).
+
+## Ví dụ trong dự án
+
+- **Colors.stories.ts:** SectionBrand, SectionNeutral, SectionSuccess, SectionWarning dùng ColorCard (hex #000/#fff, tag theo luminance), ScaleBar (#000/#fff), AlertChip (descColor = semantic .text), TokenBlock và panelStyles không dùng text.disabled cho nội dung.
+
+## Khi thêm component hoặc story mới
+
+- Ưu tiên token (`colorTokens`, `inetDesignTokens`); tránh hardcode hex/rgba cho chữ.
+- Chạy axe (hoặc addon a11y) trên story; sửa mọi lỗi color-contrast trước khi merge.
+- Theme Vuetify: `on-success` / `on-warning` lấy từ `inet-design-tokens` (đã map trong `v-light.ts` / `v-dark.ts`).
+
+Khi chỉnh sửa file khớp glob, áp dụng các quy tắc trên để tránh lặp lỗi contrast. Skill tổng thể (ARIA, keyboard, focus, contrast): `.cursor/skills/accessibility.md`.