@hobui/viui-cli 0.0.2

package/dist/assets/cursor/rules/bem-class-style.mdc

@@ -0,0 +1,107 @@
+---
+description: BEM class naming và style theo class — dễ tìm DOM, cập nhật quy mô lớn, tránh phình file do inline style
+globs: src/design-system/**/*, src/components/**/*, src/storybook/**/*, **/*.stories.ts, **/*.vue, src/assets/styles/**/*
+alwaysApply: false
+---
+
+# BEM Class & Style theo class (Rule bắt buộc khi tạo/cập nhật design-system, components, stories)
+
+Khi tạo mới hoặc cập nhật component, foundation story hoặc bất kỳ file thuộc design system, **luôn dùng cấu hình class theo BEM** và **ưu tiên style qua class (CSS/SCSS)** thay vì attribute `style` inline. Rule này bổ sung `component-naming.mdc` và `storybook.mdc`.
+
+## Mục đích
+
+| Mục tiêu | Cách đạt |
+|----------|----------|
+| **Dễ tìm kiếm theo DOM** | Root và section có class BEM cố định; querySelector / test / DevTools tìm theo class. |
+| **Dễ cập nhật, chỉnh sửa style quy mô lớn** | Một class nhiều chỗ dùng; sửa một định nghĩa trong CSS/SCSS là đủ. |
+| **Không bị scale dung lượng file vì attribute style** | Tránh object `style: { ... }` lặp lại hàng chục/dòng; đưa vào class trong CSS/SCSS. |
+
+## Quy ước BEM
+
+- **Block**: thành phần độc lập; tên **kebab-case**, một từ hoặc cụm (vd: `spacing-layout-stories`, `vi-button`, `colors-stories`).
+- **Element**: phần con thuộc block; nối bằng `__` (hai gạch dưới): `block__element` (vd: `spacing-layout-stories__overview`, `spacing-layout-stories__card`).
+- **Modifier**: biến thể của block hoặc element; nối bằng `--`: `block--modifier` hoặc `block__element--modifier` (vd: `vi-button--primary`, `spacing-layout-stories__card--highlight`).
+
+Tên class: **chỉ lowercase, số và dấu gạch nối**; không dùng camelCase hay PascalCase trong class.
+
+## Áp dụng theo loại file
+
+### 1. Foundation stories (`src/storybook/Foundations/*.stories.ts`)
+
+- **Root element** (div/vue wrapper của toàn bộ story): luôn có **một block class** tương ứng tên story, ví dụ:
+  - `SpacingLayout.stories.ts` → `class: 'spacing-layout-stories'`
+  - `Colors.stories.ts` → `class: 'colors-stories'`
+  - `Typography.stories.ts` → `class: 'typography-stories'`
+- **Section / nhóm nội dung**: dùng element class, ví dụ `spacing-layout-stories__overview`, `spacing-layout-stories__grid`, `spacing-layout-stories__card`.
+- **Style**: Ưu tiên đưa vào file SCSS/CSS (cùng thư mục hoặc `src/assets/styles/`) và gắn class; **inline `style`** chỉ dùng khi giá trị **động** (theme CSS variable, token runtime, prop). Ví dụ nền/ chữ theo theme có thể giữ `style` với `var(--v-theme-*)` hoặc chuyển sang class + CSS variable trong SCSS.
+
+### 2. Component Vue (`*.vue` trong `src/design-system/`, `src/components/`)
+
+- **Root element** của component: có **block class** trùng với tên component dạng kebab-case (vd: `vi-button` → class `vi-button`, `BaseAlert` → `base-alert`).
+- **Phần con**: dùng `__element` (vd: `vi-button__icon`, `base-alert__title`). Biến thể dùng `--modifier` (vd: `vi-button--primary`).
+- **Style**: Trong `<style scoped>` hoặc file `.css`/`.scss` cùng thư mục; tránh style inline trừ khi dynamic.
+
+### 3. Stories của component (`*.stories.ts` cạnh component)
+
+- **Root wrapper** (nếu có) hoặc **canvas container**: nên có block class, ví dụ `vi-button-stories` hoặc dùng trực tiếp component (component đã có block class).
+- **Style** cho layout story: dùng class + CSS/SCSS thay vì inline.
+
+## Vị trí đặt CSS/SCSS — Tổng thể dự án
+
+Toàn bộ SCSS/CSS dùng chung (BEM, layout, foundations, component blocks) nằm dưới **một điểm vào**: `src/assets/styles/`. Không tách riêng SCSS chỉ cho Storybook Foundations; mọi phần (foundations, design-system, components, app) đều tham chiếu hoặc import từ đây.
+
+### Cấu trúc gợi ý `src/assets/styles/`
+
+| File / thư mục | Mục đích | Ai dùng |
+|----------------|----------|---------|
+| `main.scss` | Entry: import tokens + các partial; được load bởi app/Storybook. | Toàn app, Storybook (qua plugin Vite/Vuetify). |
+| `inet-tokens.scss` | Biến CSS từ design tokens (đã có). | Mọi SCSS khác qua `@use`. |
+| `_variables.scss` | Biến/mixin dùng chung (nếu cần). | Các partial. |
+| `foundations/` | Partial theo từng foundation story (BEM block). | Story import hoặc `main.scss` import. |
+| `foundations/_spacing-layout-stories.scss` | Class `.spacing-layout-stories`, `.spacing-layout-stories__*`. | `SpacingLayout.stories.ts` (import trong story hoặc qua main). |
+| `foundations/_colors-stories.scss` | Class `.colors-stories`, `.colors-stories__*`. | `Colors.stories.ts`. |
+| `foundations/_typography-stories.scss` | Class `.typography-stories`, `.typography-stories__*`. | `Typography.stories.ts`. |
+| `foundations/_index.scss` | `@forward` các partial foundations. | `main.scss` import một lần. |
+| `components/` hoặc `design-system/` | Partial cho Vi* / brands / errors (block BEM component). | Component Vue import file rời hoặc dùng `<style scoped>`; có thể forward từ đây nếu cần dùng chung. |
+
+- **Foundation stories**: Style theo class BEM đặt trong `src/assets/styles/foundations/`; story file có thể import trực tiếp `@/assets/styles/foundations/spacing-layout-stories.scss` hoặc dùng chung qua `main.scss` (đã load toàn app).
+- **Component Vue (vi-ui, brands, errors)**: Có thể (1) `<style scoped>` trong `.vue`, hoặc (2) file SCSS cùng thư mục component và import trong component, hoặc (3) partial trong `src/assets/styles/components/` và import từ `main.scss` nếu style dùng nhiều nơi.
+- **Chung toàn app**: Reset, layout, utility — trong `main.scss` hoặc partial `_base.scss` / `_utilities.scss` trong `src/assets/styles/`.
+
+### Nguyên tắc
+
+- **Một nguồn sự thật**: Tokens → `inet-tokens.scss`; class BEM cho story/component → partial trong `src/assets/styles/` (foundations, components), không rải file SCSS riêng lẻ ngoài cấu trúc này (trừ `<style scoped>` trong Vue).
+- **Foundations** là một phần của tổng thể: không tạo thư mục SCSS riêng cho `src/storybook/Foundations/`; dùng `src/assets/styles/foundations/` và import từ entry chung hoặc từ story.
+
+## Ví dụ (theo SpacingLayout.stories.ts)
+
+- Root:
+  ```ts
+  h('div', { class: 'spacing-layout-stories', style: { padding: '24px', ... } }, [...])
+  ```
+  Chuẩn hóa: root giữ `class: 'spacing-layout-stories'`; các thuộc tính tĩnh (padding, borderRadius, minHeight) nên chuyển vào `.spacing-layout-stories { ... }` trong file SCSS; chỉ giữ inline khi dùng biến theme (vd `backgroundColor: themeColors.surfaceBackground` hoặc `var(--v-theme-background)`).
+
+- Section/ card:
+  ```ts
+  h('div', { class: 'spacing-layout-stories__card', ... }, [...])
+  ```
+
+## Ngoại lệ (inline style chấp nhận được)
+
+- Giá trị **phụ thuộc runtime**: theme (CSS variable), token đọc từ composable, prop (vd width/height từ args).
+- **Một lần**, ít lặp: một vài thuộc tính đơn lẻ không đáng kể dung lượng.
+
+## Checklist khi tạo/cập nhật
+
+- [ ] Root element có **block class** BEM (kebab-case) chưa?
+- [ ] Section/ element con có **element class** (`block__element`) hoặc modifier khi cần?
+- [ ] Style **tĩnh** đã đưa vào class (CSS/SCSS) chưa, tránh lặp object `style` lớn?
+- [ ] Có thể **tìm nhanh trong DOM** bằng class (DevTools, test, script) không?
+
+## Tham chiếu
+
+- Naming component/file: `component-naming.mdc`
+- Cấu trúc Storybook: `storybook.mdc`
+- Design system & tokens: `design-system-component-library.mdc`, `tokens.mdc`
+
+Khi được kích hoạt (file khớp glob), **chủ động gợi ý hoặc áp dụng** class BEM và chuyển style sang class/CSS để đạt ba mục đích trên.

package/dist/assets/cursor/rules/component-naming.mdc

@@ -0,0 +1,57 @@
+---
+description: Component naming (bắt buộc) — quy ước tên component, file, props, thư mục
+globs: src/design-system/**/*, src/components/**/*, src/storybook/**/*, **/*.stories.ts
+alwaysApply: false
+---
+
+# Component Naming (Rule bắt buộc)
+
+Khi tạo hoặc đổi tên component, story, thư mục trong design system, tuân theo quy ước dưới đây. Chi tiết vị trí file: `project-structure.mdc`; workflow NHÓM: `design-system-workflow.mdc`.
+
+## Quy tắc đặt tên tổng quát (dự án)
+
+| Đối tượng | Quy ước | Ví dụ |
+|-----------|---------|--------|
+| Tên Component (.vue) | PascalCase | `ProductCard.vue` |
+| Thư mục chứa Component | PascalCase | `src/components/ProductCard/` |
+| Interfaces / Types | PascalCase | `ProductInfo` |
+| Composables (.ts) | camelCase | `useAuth.ts`, `useLocalStorage.ts` |
+| Biến (props, refs) | camelCase | `const isLoading = ref(false)` |
+| Sự kiện (emit) | kebab-case | `emit('close-modal')` |
+
+**Ngoại lệ:** Trong `src/design-system/vi-ui/` thư mục component dùng **kebab-case** `vi-<tên>` (vd. `vi-button/`, `vi-input/`) theo quy ước vi-ui; tên file và component vẫn PascalCase (`ViButton.vue`).
+
+**src/storybook:** Thư mục con PascalCase (`Introduction/`, `Foundations/`, `Themes/`); file `.vue`, `.stories.ts`, `.mdx` PascalCase (vd. `NeoBrutalism.vue`, `Colors.stories.ts`). Chi tiết: `storybook.mdc`.
+
+## Quy ước chính (chi tiết)
+
+| Loại | Quy ước | Ví dụ |
+|------|---------|--------|
+| **Component Vue** | PascalCase; BaseX nếu là base/primitive | `Button.vue`, `BaseAlert.vue`, `ErrorPage.vue`, `ViButton.vue` |
+| **Component vi-ui** | Tiền tố `Vi` + PascalCase; thư mục `vi-<tên>` | `ViButton.vue` trong `vi-button/`, `ViInput.vue` trong `vi-input/` |
+| **Stories** | `ComponentName.stories.ts`, cùng thư mục với component | `ViButton.stories.ts`, `BaseAlert.stories.ts` |
+| **Props / events** | kebab-case trong template; camelCase trong script; emit: kebab-case | `variant="primary"`, `defineProps<{ variant: string }>()`, `emit('close-modal')` |
+| **Thư mục component** | PascalCase (xem bảng trên); vi-ui: kebab `vi-<tên>` | `ProductCard/`, `vi-button/`, `brands/` (nhóm) |
+| **Composables** | camelCase, tiền tố `use` | `useAuth.ts`, `useLocalStorage.ts` |
+| **Token / types** | Token file: lowercase hoặc camelCase; types: PascalCase, file `*-types.ts` hoặc `*.d.ts` | `inet-design-tokens.ts`, `inet-tokens-types.ts` |
+| **CSS/SCSS** | lowercase, gạch nối nếu cần | `main.scss`, `_error-page.css` |
+| **Class (BEM)** | block__element--modifier; kebab-case | `spacing-layout-stories`, `spacing-layout-stories__card` — chi tiết: `bem-class-style.mdc` |
+
+## Vi-ui (design-system)
+
+- **Tên component:** `Vi` + tên (PascalCase), vd: `ViButton`, `ViCard`, `ViAlert`.
+- **Thư mục:** `vi-<tên>` (kebab-case), vd: `src/design-system/vi-ui/vi-button/`.
+- **File:** `ViName.vue` và `ViName.stories.ts` trong cùng thư mục.
+- **Export:** Re-export qua `src/design-system/vi-ui/index.ts` nếu có.
+- **Story Vue (khi component có slot):** Nếu component dùng nhiều slot (activator + default, list + items) và story dùng `render()` dễ khiến preview trống, tạo thêm `ViNameStory.vue` chứa template đầy đủ + dữ liệu demo; trong `ViName.stories.ts` dùng `component: ViNameStory` và chỉ truyền `args`. Chi tiết: `storybook.mdc` § "Vi-ui: Component có slot → dùng Story Vue".
+
+## Components (brands, errors, icons)
+
+- **Tên component:** PascalCase, không bắt buộc tiền tố Vi (vd: `BrandLogo`, `ErrorPage`, `ArrowLeftRight`).
+- **Thư mục:** Một thư mục per component, tên lowercase (vd: `src/components/brands/`, `src/components/errors/`).
+
+## Story title (sidebar)
+
+- Theo cấu trúc trong `storybook.mdc`: `{Nhóm}/{Tên}`, vd: `vi-ui/Button`, `Brands/Logo`, `Errors/ErrorPage`, `Foundations/Colors`.
+
+Khi được kích hoạt (file khớp glob), áp dụng quy ước naming trên và gợi ý chỉnh nếu lệch.

package/dist/assets/cursor/rules/design-system-component-library.mdc

@@ -0,0 +1,59 @@
+---
+description: Design system & component architecture — Vue 3 + Vuetify, tokens, API, NHÓM; naming PascalCase, vi-*, *.stories.ts. Cùng dùng: component-naming.mdc, design-system-workflow.mdc. Skill: .cursor/skills/vue-vuetify-design-system-architect.md
+globs: src/components/**/*, src/design-system/**/*, src/tokens/**/*, src/storybook/**/*, src/assets/styles/**/*, docs/**/*
+alwaysApply: false
+---
+
+# Design System & Component Library (Subagent)
+
+**Bạn là design system và component library trong dự án này.**
+
+## Vai trò
+
+- **Nguồn chân lý** cho tokens, components và quy ước giao diện của dự án.
+- **Hướng dẫn** khi tạo/sửa component, tokens, stories hoặc tài liệu design system.
+- **Đảm bảo** mọi output dùng Vue 3 + Vuetify và design tokens từ `src/tokens/`.
+
+## Nguyên tắc khi áp dụng rule này
+
+1. **Tokens trước** — Màu, spacing, typography lấy từ design system; không hard-code giá trị theme/layout.
+2. **Vue 3 + Vuetify** — Composition API, `<script lang="ts" setup>`, component/theme Vuetify 3; theme bắt nguồn từ tokens.
+3. **Accessibility** — ARIA, bàn phím, focus, HTML ngữ nghĩa; kiểm tra tương phản và vùng chạm.
+4. **API rõ ràng** — Props, slots, events nhất quán; tùy biến qua props/theme thay vì override từng chỗ.
+5. **Tuân AGENTS.md** — Không tự chạy lệnh shell khi chưa có đồng ý; giải thích rủi ro với thao tác hạ tầng.
+6. **Class BEM & style theo class** — Root component/story có block class BEM; style qua CSS/SCSS, tránh inline style trừ giá trị động. Chi tiết: `bem-class-style.mdc`.
+7. **Vi-ui & Icons khi gen code** — Khi tạo/sửa UI, story hoặc demo: dùng component **Vi\*** từ vi-ui (không gọi trực tiếp `v-btn`, `v-text-field`, `v-card`, `v-menu` khi đã có ViButton, ViInput, ViCard, ViMenu); **không dùng raw `<button>`** cho action (copy, submit, link-style) — dùng **ViButton** (variant text/outlined/… tùy ngữ cảnh); icon mặc định **Tabler Icons** (`@tabler/icons-vue`). Chi tiết: `icons.mdc`, `storybook.mdc`. Áp dụng cho toàn dự án và repo consumer dùng @viui/cli (AI codegen).
+
+## Naming (tóm tắt)
+
+| Loại | Quy ước | Ví dụ |
+|------|---------|--------|
+| **Component vi-ui** | Tiền tố `Vi` + PascalCase; thư mục `vi-<tên>` | `ViButton.vue` trong `vi-button/` |
+| **Component khác** | PascalCase | `ErrorPage.vue`, `BrandLogo.vue` |
+| **Stories** | `ComponentName.stories.ts`, cùng thư mục | `ViButton.stories.ts` |
+| **Props / events** | kebab-case template; camelCase script | `variant="primary"`, `defineProps<{ variant: string }>()` |
+| **Thư mục** | lowercase, số ít, gạch nối | `vi-button/`, `errors/` |
+
+Chi tiết: `component-naming.mdc`.
+
+## NHÓM (workflow)
+
+| NHÓM | Vị trí | Items |
+|------|--------|-------|
+| vi-ui | `src/design-system/vi-ui/vi-<tên>/` | ViButton, ViInput, ViCard, … |
+| Brands | `src/components/brands/` | BrandLogo, StyleGuide |
+| Errors | `src/components/errors/` | ErrorPage, … |
+| Icons | `src/components/icons/` | … |
+| Tokens | `src/tokens/` | design-tokens.ts, inet-design-tokens.ts |
+| Docs | `src/docs/` | design-system.md, … |
+| Storybook foundations | `src/storybook/Foundations/` | Colors.stories.ts, Typography.stories.ts, … |
+
+Workflow: **thêm mới** (chọn NHÓM → tạo đúng vị trí → story/index), **tìm kiếm** (theo tên hoặc NHÓM). Chi tiết: `design-system-workflow.mdc`, `project-structure.mdc`.
+
+## Tham chiếu nhanh
+
+- Tokens & types: `src/tokens/`, `src/types/inet-tokens-types.ts`
+- Components: `src/components/` (brands, errors, icons), `src/design-system/vi-ui/` (Vi*)
+- Quy ước chi tiết: skill `.cursor/skills/vue-vuetify-design-system-architect.md` và `AGENTS.md`
+
+Khi được kích hoạt (file khớp glob), hành xử như **subagent design system và component library** của dự án và áp dụng các nguyên tắc trên.

package/dist/assets/cursor/rules/design-system-workflow.mdc

@@ -0,0 +1,48 @@
+---
+description: Workflow Design system — mục tiêu đầu ra như Cloud Panel: NHÓM + items, thêm mới, tìm kiếm
+globs: src/components/**/*, src/design-system/**/*, src/tokens/**/*, src/docs/**/*, src/storybook/**/*, docs/**/*
+alwaysApply: false
+---
+
+# Workflow Design system (Mục tiêu đầu ra như Cloud Panel)
+
+Design system được quản lý theo **mô hình panel**: **iNET Design system** là đơn vị tổ chức; bên trong có **NHÓM** và **items** (components, token files, docs). Workflow phải đạt: **thêm mới**, **tìm kiếm**, **tổng kết** rõ ràng.
+
+## NHÓM chuẩn (Design System)
+
+| NHÓM | Vị trí code | Items |
+|------|--------------|-------|
+| 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, ErrorKnowledgeList |
+| Icons | `src/components/icons/` | ArrowLeftRight, … |
+| Tokens | `src/tokens/` | color.json, typography.json, inet-design-tokens.ts |
+| Docs | `src/docs/` | design-system.md, foundations/*, usage/* |
+| Storybook foundations | `src/storybook/Foundations/` | Colors.stories.ts, Typography.stories.ts, SpacingLayout.stories.ts, Configure.mdx |
+
+Mỗi item (component, token file, doc) **chỉ thuộc một NHÓM**. Chi tiết mục tiêu đầu ra và số NHÓM: xem `docs/design-system-plan.md`.
+
+## Workflow: Thêm item mới (Component/Token mới)
+
+1. **Chọn NHÓM** — vi-ui, Brands, Errors, Icons, Tokens, Docs, hoặc Storybook foundations.
+2. **Tạo đúng vị trí** — theo rule `project-structure.mdc` (vd: component Vi* → `src/design-system/vi-ui/vi-<tên>/ViName.vue` + `ViName.stories.ts`). Nếu component có **nhiều slot** (menu activator + content, list + items): thêm `ViNameStory.vue` và dùng trong stories để preview không trống (chi tiết `storybook.mdc` § Vi-ui Story Vue).
+3. **Cập nhật index/re-export** — nếu nhóm có `index.ts` (vd: `src/design-system/vi-ui/index.ts`) hoặc cần export chung.
+4. **Story/docs** — component mới có story; token/docs cập nhật nếu cần.
+
+Không tạo component/token “lạc” ngoài các NHÓM trên.
+
+## Workflow: Tìm component hoặc nhóm
+
+- **Tìm theo tên component** — search trong codebase, Storybook sidebar, hoặc docs.
+- **Tìm theo NHÓM** — mở thư mục tương ứng (vd: `src/design-system/vi-ui/`, `src/tokens/`).
+- Mọi item phải **có thể tìm được** qua tên hoặc qua nhóm.
+
+## Tổng kết (dashboard)
+
+- **Số NHÓM:** 7 (vi-ui, Brands, Errors, Icons, Tokens, Docs, Storybook foundations).
+- **Số items:** đếm được theo nhóm (components, token files, docs).
+- **Trạng thái:** documented, có story, dùng token — dùng cho review (rule `verifier` / QA).
+
+**AI codegen (toàn dự án & consumer @viui/cli):** Khi generate code UI/story/demo, dùng vi-ui (Vi*) và Tabler Icons mặc định; nút action dùng ViButton, không dùng raw `<button>`; xem `icons.mdc`, `storybook.mdc`, AGENTS.md § Codegen / AI Agent.
+
+Khi thêm file hoặc review, đảm bảo item thuộc đúng **NHÓM** và workflow **thêm mới / tìm kiếm** tuân theo mục tiêu đầu ra trong `docs/design-system-plan.md`. **Kế hoạch tập trung:** `.cursor/plans/DESIGN_SYSTEM_PLAN.md` (một file; chỉ mục: `.cursor/plans/PLANS_INDEX.md`).

package/dist/assets/cursor/rules/figma-mapping.mdc

@@ -0,0 +1,37 @@
+---
+description: Figma ↔ code — ánh xạ token names, component names, MCP get_design_context. Skill: .cursor/skills/figma-interpretation.md
+globs: "**/*.vue", "**/*.stories.@(ts|tsx)", "src/tokens/**/*", "docs/**/*"
+alwaysApply: false
+---
+
+# Figma Mapping
+
+Quy ước ánh xạ design Figma sang code iNET Design System (Vue 3 + Vuetify, tokens, naming). **Skill khi làm từ Figma:** `.cursor/skills/figma-interpretation.md`. **Rules liên quan:** `tokens.mdc`, `component-naming.mdc`, `storybook.mdc`, `accessibility-contrast.mdc`.
+
+## Nguyên tắc
+
+1. **Tokens là nguồn chân lý** — Giá trị trong Figma (màu, spacing, radius, shadow) map sang key trong `src/tokens/design-tokens.ts`. Nếu Figma khác token, ưu tiên token; ghi chú với designer để cập nhật Figma.
+2. **Figma Variables ↔ token names** — Map tên (vd `brand/primary` → `colorTokens.brand.primary`). Tham chiếu `tokens.mdc`.
+3. **Component naming** — Component sinh từ Figma tuân `component-naming.mdc`: Vi* trong `vi-<tên>/`, PascalCase, `*.stories.ts` cùng thư mục. Story title = `{Nhóm}/{Tên}` theo `storybook.mdc`.
+4. **MCP workflow** — Figma MCP: `get_design_context(fileKey, nodeId?)` để lấy code/screenshot/hints. Output thường là reference (React/Tailwind); chuyển sang Vue 3 + Vuetify và component/token của dự án.
+5. **Accessibility** — Màu chữ/nền đạt WCAG 2.1 AA; semantic `.text` trên nền màu. Xem `accessibility-contrast.mdc` và `.cursor/skills/accessibility.md`.
+
+## Map nhanh (Figma → code)
+
+| Figma | Code / token |
+|-------|---------------|
+| Màu (fill/text) | `colorTokens.*`, `inetDesignTokens.colors.*` |
+| Spacing / layout | `spacingTokens`, `space8pt` (8pt grid) |
+| Radius / corner | `shapeTokens` |
+| Shadow / elevation | `elevationTokens` |
+| Typography | `typographyTokens` |
+| Component mới | Vi* trong `vi-<tên>/ViName.vue` + `ViName.stories.ts`; hoặc `src/components/<nhóm>/` |
+
+## Quy trình gợi ý
+
+1. **Lấy design** — MCP `get_design_context` hoặc mô tả/screenshot. Xác định sections, components, giá trị (màu, spacing, typography).
+2. **Map tokens** — Màu → `colorTokens.*` / `inetDesignTokens.colors.*`; spacing → `spacingTokens`; radius → `shapeTokens`; không thêm giá trị mới ngoài token trừ khi đã cập nhật `design-tokens.ts`.
+3. **Chọn component** — Dùng Vi* có sẵn nếu khớp; không thì tạo mới đúng thư mục và naming. Thêm story.
+4. **Kiểm tra** — Storybook chạy đúng; contrast và a11y đạt.
+
+Khi chỉnh file khớp glob (đặc biệt khi implement từ Figma), áp dụng quy ước trên và tham chiếu skill `figma-interpretation.md`.

package/dist/assets/cursor/rules/icons.mdc

@@ -0,0 +1,42 @@
+---
+description: Bộ icon mặc định Tabler; vi-ui trong demo/story; áp dụng toàn dự án và repo consumer (@viui/cli) khi AI gen code
+globs: "**/*.vue", "**/*.ts", "**/*.tsx", "src/storybook/**/*", "src/design-system/**/*", "src/components/**/*"
+alwaysApply: false
+---
+
+# Icons — Mặc định Tabler (áp dụng toàn dự án & AI codegen)
+
+**Rule này áp dụng cho:** i-design-system và mọi repo consumer đã chạy `@viui/cli init` / `sync`. Khi **AI Agent generate code** Vue, Storybook hoặc UI, phải tuân nội dung dưới đây. AGENTS.md § Codegen / AI Agent và § Rules bắt buộc (7).
+
+## Bộ icon mặc định
+
+- **Tabler Icons** (`@tabler/icons-vue`) là bộ icon **mặc định** cho dự án và cho mọi repo đã dùng **@viui/cli** (sync `.cursor`).
+- License: MIT. Hơn 4.000 icon (outline/filled), tree-shakable, Vue 3.
+
+## Cách dùng
+
+1. **Import từng icon** — Chỉ icon được import mới vào bundle.
+   ```ts
+   import { IconArrowRight, IconSettings, IconUser } from '@tabler/icons-vue'
+   ```
+2. **Trong template:** Dùng như component Vue (`<IconArrowRight />`). Có thể truyền `size`, `stroke`, `color` theo [tài liệu Tabler](https://tabler.io/icons).
+3. **Vuetify `v-icon`:** Các component Vuetify dùng prop `icon` dạng chuỗi (vd. `prepend-icon="mdi-account"`) vẫn dùng **MDI** (đã cấu hình sẵn). Khi viết component mới, ưu tiên Tabler; nếu cần tương thích trực tiếp với `v-icon` có thể giữ MDI cho prop đó.
+
+## Nguồn khác (khi cần)
+
+- **MDI:** Đã có trong Vuetify; dùng khi cần `v-icon` với tên chuỗi.
+- **Lucide, Phosphor, Heroicons:** Ghi trong Storybook **Icons/Overview**; dùng khi team chọn phong cách khác.
+
+## Vi-ui trong demo Icons
+
+- Demo Icons (vd. **TablerIconsDemo.vue**) dùng **vi-ui** cho UI: ViInput (search), ViButton (mọi nút action kể cả copy line trong popover: Vue name, Import, SVG), ViCard (popover nội dung), ViMenu (popover), ViButtonToggle (Outline/Filled). Không dùng raw `<button>`; nút copy/link-style dùng ViButton. Nếu thiếu component trong vi-ui thì bổ sung (vd. đã thêm ViButtonToggle) rồi dùng trong demo. Rule: `storybook.mdc` § Vi-ui trong Storybook.
+
+## Tham chiếu
+
+- Storybook: **Icons/Overview**, **Icons/Tabler** — bảng nguồn và demo popover.
+- Package: `@tabler/icons-vue`
+- Vi-ui: `@/design-system/vi-ui` (ViInput, ViButton, ViCard, ViMenu, ViButtonToggle)
+
+Khi được kích hoạt (file khớp glob), ưu tiên **Tabler Icons** cho icon mới; không thêm bộ icon khác làm mặc định nếu chưa thống nhất với design system.
+
+**Plan liên quan:** `.cursor/plans/icons_free_sources.plan.md` (demo Icons, vi-ui, ViButtonToggle, sidebar Storybook).

package/dist/assets/cursor/rules/project-structure.mdc

@@ -0,0 +1,137 @@
+---
+description: Cấu trúc dự án và quy ước review cấu trúc — nơi đặt file, naming, phân cấp thư mục
+globs: src/**/*, docs/**/*, .storybook/**/*, public/**/*, vite.config.*, tsconfig*.json, package.json
+alwaysApply: false
+---
+
+# Cấu trúc dự án & Review cấu trúc
+
+Rule này định nghĩa **cấu trúc chuẩn** của dự án design system và tiêu chí **review cấu trúc**. Cấu trúc hướng tới **mục tiêu đầu ra như Cloud Panel**: **iNET Design system** chứa **NHÓM** (vi-ui, Brands, Errors, Tokens, Docs, Storybook foundations) và **items** (components, token files, docs). Chi tiết workflow: `design-system-workflow.mdc` và `docs/design-system-plan.md`. Khi thêm file mới hoặc review layout, tuân theo cấu trúc dưới đây.
+
+---
+
+## Cấu trúc thư mục chuẩn
+
+### Root
+
+| Thư mục / file | Mục đích |
+|----------------|----------|
+| `src/` | Mã nguồn chính (Vue, tokens, components, docs nội bộ) |
+| `docs/` | Tài liệu dự án (plan, kế hoạch) — không nhầm với `src/docs/` |
+| `public/` | Static assets dùng trực tiếp (favicon, logo, ảnh error page) |
+| `.storybook/` | Cấu hình Storybook (main, preview, manager) |
+| `.agent/rules/` | Agent/subagent rules (design-system, verifier, …) |
+| `.cursor/rules/` | Cursor rules (.mdc) |
+| `AGENTS.md` | Chỉ dẫn chung cho agent; luôn tuân thủ |
+
+### `src/`
+
+| Thư mục | Mục đích | Quy ước |
+|---------|----------|---------|
+| `src/design-system/vi-ui/` | Component Vi* (app-facing) | Mỗi component: `vi-<tên>/ViName.vue` + `ViName.stories.ts`; nếu component có nhiều slot (menu, list, dialog…) thêm `ViNameStory.vue` để preview không trống; export từ `index.ts`. |
+| `src/components/` | Component library (brands, errors, icons) | Phân cấp: brands, errors, icons. Mỗi component trong thư mục riêng. |
+| `src/tokens/` | Design tokens | JSON + TS (inet-design-tokens, index re-export). |
+| `src/types/` | TypeScript types (tokens, Vuetify, global). | `.d.ts` cho ambient, `.ts` cho module. |
+| `src/plugins/` | Vue/Vuetify plugins (theme, vuetify). | Một file per theme/plugin. |
+| `src/storybook/` | Stories dùng chung (Colors, Typography, Spacing, Configure). | Không đặt story của từng component ở đây. |
+| `src/docs/` | Tài liệu design system (VitePress): foundations, philosophy, usage. | `.md`; cấu hình VitePress trong `.vitepress/`. |
+| `src/assets/` | CSS, SCSS, hình ảnh dùng trong app. | **Tổng thể dự án**: `styles/` (main.scss, inet-tokens.scss, foundations/, components/); class BEM và style chung đặt ở đây. Xem `project-structure.mdc` § src/assets/styles và `bem-class-style.mdc`. |
+| `src/utils/` | Hàm tiện ích (theme, color, forward). | Re-export qua `index.ts` nếu cần. |
+| `src/figma/` | File Figma (tokens, components). | Tùy chọn. |
+
+### `src/components/`
+
+| Cấp | Thư mục | Ví dụ | Quy ước |
+|-----|---------|--------|---------|
+| Khác | `brands/`, `errors/`, `icons/` | BrandLogo, ErrorPage, ArrowLeftRight | Cùng cấp; có thể có `.ts` data (ErrorData.ts). |
+
+Component Vi* (ViButton, ViInput, …) nằm trong `src/design-system/vi-ui/` — xem `design-system-workflow.mdc` khi thêm component mới.
+
+- **Stories**: Đặt cùng thư mục với component, tên `*.stories.ts`. Component có slot (activator + content, list + items): thêm `ViNameStory.vue` chứa template + demo, stories dùng component Story; xem `storybook.mdc`.
+- **CSS scope**: Có thể dùng file `.css` riêng trong thư mục component (vd: `button.css`, `header.css`). Class theo BEM: `bem-class-style.mdc`. Style chung (BEM block) có thể đặt trong `src/assets/styles/components/` và import từ tổng thể (xem § src/assets/styles).
+
+### `src/assets/styles/` (SCSS tổng thể dự án)
+
+Toàn bộ SCSS/CSS dùng chung (tokens, foundations, component blocks BEM) thuộc **một cấu trúc** dưới đây; không tách riêng SCSS chỉ cho Storybook Foundations.
+
+| Thành phần | Mục đích |
+|------------|----------|
+| `main.scss` | Entry: import tokens + foundations (+ components nếu cần). Load bởi app/Storybook. |
+| `inet-tokens.scss` | CSS custom properties từ design tokens (đã có). |
+| `foundations/` | Partial theo từng foundation story: `_spacing-layout-stories.scss`, `_colors-stories.scss`, `_typography-stories.scss`; file `_index.scss` forward để `main.scss` import một lần. |
+| `foundations/_index.scss` | `@forward` từng partial; `main.scss` chỉ `@use "foundations"` hoặc tương đương. |
+| `components/` (tùy chọn) | Partial BEM cho component dùng chung nhiều nơi; component Vue có thể dùng `<style scoped>` hoặc import file cùng thư mục. |
+
+- **Foundation stories** (Colors, Typography, Spacing & Layout): class BEM định nghĩa trong `src/assets/styles/foundations/`; story hoặc `main.scss` import từ đây.
+- **Component**: Ưu tiên `<style scoped>` trong `.vue`; nếu tách file thì cùng thư mục component hoặc partial trong `src/assets/styles/components/`.
+
+Chi tiết BEM và quy ước class: `bem-class-style.mdc`.
+
+### `src/tokens/`
+
+- **JSON**: Token gốc — `color.json`, `typography.json`, `motion.json`, `elevation.json`.
+- **TS**: `inet-design-tokens.ts` (nguồn truth), `design-tokens.ts` nếu có, `index.ts` re-export.
+- Types: Định nghĩa trong `src/types/` (vd: `inet-tokens-types.ts`).
+
+### `public/`
+
+- Favicon, logo, SVG/WebP dùng qua `/` (vd: `/favicon.ico`, `/error/client-error-status.svg`).
+- **Không** đặt mã nguồn (Vue/TS) trong `public/`.
+
+### `docs/` (root)
+
+- Tài liệu quản lý dự án (plan, kế hoạch). Khác với `src/docs/` (nội dung design system).
+
+---
+
+## Naming
+
+| Loại | Quy ước | Ví dụ |
+|------|---------|--------|
+| Component Vue | PascalCase, một từ hoặc cụm (BaseX nếu base component) | `Button.vue`, `BaseAlert.vue`, `ErrorPage.vue` |
+| Stories | `ComponentName.stories.ts` | `Button.stories.ts`, `BaseTabs.stories.ts` |
+| Token file | lowercase, có dấu gạch nếu cần | `color.json`, `inet-design-tokens.ts` |
+| CSS/SCSS | lowercase, gạch nếu cần | `main.scss`, `_error-page.css`, `button.css` |
+| Thư mục component | lowercase, số ít | `buttons/`, `card/`, `forms/` |
+| Types | PascalCase cho type/interface; file: `*-types.ts` hoặc `*.d.ts` | `inet-tokens-types.ts`, `vuetify.d.ts` |
+
+---
+
+## Checklist review cấu trúc
+
+Khi review cấu trúc dự án, kiểm tra:
+
+### Vị trí file
+
+- [ ] Component Vi* mới nằm trong `src/design-system/vi-ui/vi-<tên>/` (xem `design-system-workflow.mdc`).
+- [ ] Component brands/errors/icons nằm trong `src/components/` đúng cấp, mỗi component một thư mục.
+- [ ] Stories đặt cùng thư mục với component, tên `*.stories.ts`.
+- [ ] Token chỉ trong `src/tokens/`; types trong `src/types/`.
+- [ ] Theme/plugin trong `src/plugins/`; không rải cấu hình theme ở root.
+- [ ] Tài liệu design system trong `src/docs/`; tài liệu plan/process trong `docs/`.
+
+### Nhất quán
+
+- [ ] Không có file “lạc chỗ” (vd: component trong `src/utils/`, token trong `src/components/`).
+- [ ] Re-export rõ ràng (vd: `src/components/index.ts`, `src/tokens/index.ts`) khi có nhiều file cần export.
+
+### Naming
+
+- [ ] Component và stories đúng PascalCase / `*.stories.ts`.
+- [ ] Thư mục component lowercase, số ít.
+
+### Cấu hình & Agent
+
+- [ ] Cấu hình build (Vite, TS, Storybook) ở root hoặc `.storybook/`; không duplicate không cần thiết.
+- [ ] Agent rules trong `.agent/rules/`; Cursor rules trong `.cursor/rules/`; không trộn lẫn định dạng.
+
+---
+
+## Khi thêm file mới
+
+- **Component Vi* mới**: Tạo `src/design-system/vi-ui/vi-<tên>/` với `ViName.vue` + `ViName.stories.ts`; nếu component dùng nhiều slot (menu, list, dialog…) thì thêm `ViNameStory.vue` và dùng nó trong stories để tránh preview trống (rule `storybook.mdc`); export từ `src/design-system/vi-ui/index.ts`. Quy trình chi tiết: `design-system-workflow.mdc`.
+- **Token mới**: Thêm vào file JSON tương ứng trong `src/tokens/` và cập nhật `inet-design-tokens.ts` / types nếu cần.
+- **Story dùng chung (foundation)**: Thêm vào `src/storybook/Foundations/` (vd: `Colors.stories.ts`, `Configure.mdx`).
+- **Trang/docs design system**: Thêm vào `src/docs/` (foundations, philosophy, usage) và cấu hình trong `src/docs/.vitepress/config.ts` nếu cần.
+
+Khi được kích hoạt (file khớp glob), dùng rule này để **đánh giá cấu trúc** hoặc **hướng dẫn nơi đặt file mới**.

package/dist/assets/cursor/rules/storybook-component-template.mdc

@@ -0,0 +1,103 @@
+---
+description: Template chuẩn cho story component mới — cấu trúc meta, Default, Variants/Sizes/Colors/States; file mẫu ViButton.stories.ts
+globs: "**/*.stories.@(ts|tsx)", ".cursor/plans/KPI_COMPONENT_TEMPLATE.md"
+alwaysApply: false
+---
+
+# Storybook component template (chuẩn cho component mới)
+
+**File mẫu bắt buộc:** `src/design-system/vi-ui/vi-button/ViButton.stories.ts`
+
+Khi tạo **story mới** cho component (vi-ui, Brands, Errors, Icons), copy cấu trúc dưới đây. Mục đích: Cursor và developer generate story đúng format; kiểm tra theo `.cursor/plans/KPI_COMPONENT_TEMPLATE.md`.
+
+---
+
+## 1. Cấu trúc file
+
+- **Vị trí:** `ComponentName.stories.ts` **cùng thư mục** với `ComponentName.vue`.
+- **vi-ui:** `src/design-system/vi-ui/vi-<tên>/ViName.stories.ts`
+- **Brands/Errors/Icons:** `src/components/<nhóm>/ComponentName.stories.ts`
+
+---
+
+## 2. Meta (const meta)
+
+| Trường | Bắt buộc | Mô tả |
+|--------|----------|--------|
+| `title` | Có | `ViUi/Button` | `Brands/Logo` | `Errors/ErrorPage` — đúng nhóm sidebar (xem `storybook.mdc`). |
+| `component` | Có | Import component Vue tương ứng. |
+| `tags` | Có | `['autodocs']` để bật Docs tab. |
+| `parameters.docs.description.component` | Nên có | Dùng `docIntro(vi.viUi.xxx.descriptionComponent, en.viUi.xxx.descriptionComponent)` từ `@/locales` nếu có key; nếu chưa có locale thì string mô tả ngắn. |
+| `argTypes` | Có | Mỗi prop quan trọng: `control` (select/boolean/text/…), `options` nếu select, `description` ngắn. |
+| `args` | Có | Giá trị mặc định cho Controls (label, variant, color, …). |
+
+**Ví dụ (rút gọn):**
+
+```ts
+const meta = {
+  title: 'ViUi/Button',
+  component: ViButton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: docIntro(vi.viUi.button.descriptionComponent, en.viUi.button.descriptionComponent),
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'select', options: ['elevated', 'flat', 'outlined', 'text', 'tonal'], description: '...' },
+    color: { control: 'select', options: ['primary', 'secondary', ...], description: '...' },
+    size: { control: 'select', options: ['x-small', 'small', 'default', 'large', 'x-large'] },
+    loading: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+  },
+  args: { label: 'Vi Button', variant: 'elevated', color: 'primary' },
+} satisfies Meta<typeof ViButton>
+export default meta
+type Story = StoryObj<typeof meta>
+```
+
+---
+
+## 3. Stories (export const)
+
+- **Default** — Bắt buộc: một story chỉ dùng `args` (vd. `args: { label: 'Primary Action' }`).
+- **Theo chiều biến thể** (thêm tùy component):
+  - **Variants** — Nếu component có variant (elevated, flat, outlined, text, tonal): story render tất cả variant.
+  - **Sizes** — Nếu có prop size: story render x-small → x-large.
+  - **Colors** — Nếu có prop color semantic: story render primary, secondary, success, warning, error, info.
+  - **States** — Story gộp default + loading + disabled (và các state khác nếu có).
+  - **Loading** / **Disabled** — Có thể tách riêng hoặc chỉ dùng trong States.
+
+Layout story (nhiều nút/card): dùng wrapper với class BEM (vd `vi-button-stories`) hoặc inline style ngắn; ưu tiên class + CSS/SCSS theo `bem-class-style.mdc`.
+
+---
+
+## 4. Khi Cursor generate story mới — Checklist kiểm tra
+
+Sau khi generate, kiểm tra:
+
+- [ ] File đặt đúng vị trí: `vi-<tên>/ViName.stories.ts` (vi-ui) hoặc `src/components/<nhóm>/ComponentName.stories.ts`.
+- [ ] `title` đúng nhóm: `ViUi/...` | `Brands/...` | `Errors/...` | `Foundations/...`.
+- [ ] Có **Default** và ít nhất một story theo biến thể (Variants/Sizes/Colors/States) nếu component có prop tương ứng.
+- [ ] `argTypes` và `args` đủ cho props quan trọng; `tags: ['autodocs']`.
+- [ ] `parameters.docs.description.component` có (docIntro từ locale hoặc string).
+- [ ] Layout story: class BEM hoặc style nhất quán; không phá quy ước `bem-class-style.mdc`.
+
+Nếu lệch: chỉnh lại story hoặc cập nhật rule / file mẫu ViButton.
+
+---
+
+## 5. File template có placeholder (tùy chọn)
+
+- **Đường dẫn:** `.cursor/templates/ViComponent.stories.template.ts`
+- Copy vào thư mục component, đổi tên file và thay `ViComponent` / `ComponentName` / `componentKey` theo component thật; thêm/bớt argTypes, args, stories theo nhu cầu.
+
+---
+
+## Tham chiếu
+
+- Plan & checklist KPI: `.cursor/plans/KPI_COMPONENT_TEMPLATE.md`
+- Story mẫu đầy đủ: `src/design-system/vi-ui/vi-button/ViButton.stories.ts`
+- Rule Storybook: `storybook.mdc` — Rule naming: `component-naming.mdc` — BEM: `bem-class-style.mdc`