@lucasvu/scope-ui 0.1.0 → 0.1.1

package/AI_SETUP.md

@@ -1,51 +1,271 @@
 # AI Setup
 
-Mục tiêu của file này là để AI của project dùng `@lucasvu/scope-ui` đúng cách, không import lung tung, không hardcode màu sai chỗ và không chọn nhầm component.
+Muc tieu cua file nay la de AI cua project dung `@lucasvu/scope-ui` dung cach, khong import lung tung, khong hardcode mau sai cho, va giu dung base `Vite + micro frontend` khi repo duoc setup o may khac.
 
-Nếu project consumer đã cài package, cách nhanh nhất là chạy:
+Tu phien ban nay, cac phan generic truoc day thuong nam o `packages/shared/theme` da duoc ship ngay trong package nay:
+
+- base stylesheet
+- color-mode runtime
+- bundled theme layers
+- preset theme token generator
+- layout preset va AI playbook
+
+Surface duoc chia thanh 2 lo:
+
+- `@lucasvu/scope-ui`: React components + full UI surface
+- `@lucasvu/scope-ui/core`: theme/runtime/contracts khong phu thuoc React
+
+Vi vay consumer project o may khac chi can cai mot package la du.
+
+Neu project consumer da cai package, cach nhanh nhat la chay:
 
 ```bash
 npm install @lucasvu/scope-ui
 npx scope-ui-init --theme forest
 ```
 
-Nếu chưa biết chọn preset nào thì chạy thêm:
+Neu chua biet chon preset nao thi chay them:
 
 ```bash
 npx scope-ui-init --list-themes
 ```
 
-Nếu chưa cài `@lucasvu/scope-ui`, các lệnh trên sẽ báo `E404` vì npm sẽ cố tải package tên `scope-ui-init`.
+Neu chua cai `@lucasvu/scope-ui`, cac lenh tren se bao `E404` vi npm se co tai package ten `scope-ui-init`.
+
+CLI nay se tao:
+
+- `AGENTS.md`
+- `src/styles/ui-theme.css`
+- `src/layout-presets/workspace-admin-v1.ts`
+
+`AGENTS.md` khoa flow hoi input -> doc layout preset -> dung shell -> moi toi page body. `src/layout-presets/workspace-admin-v1.ts` giu shared shell contract. `src/styles/ui-theme.css` giu token theme cua project. Neu khong truyen `--theme`, preset mac dinh la `ocean`.
+
+## 1. Chot dung ranh gioi trach nhiem
+
+Voi base `Vite + micro frontend`, nen giu dung 3 lop nay:
+
+- `@lucasvu/scope-ui`: React surface
+- `@lucasvu/scope-ui/core`: design token, theme runtime, bundled theme layers, AI contract
+- `apps/shell`: host app, so huu sidebar, topbar, remote mount, routing tong, va theme toan cuc.
+- `apps/*-mfe`: remote app, chi so huu page business cua chinh no.
+
+Neu repo van co `packages/shared`, hay giu no cho business util, constant, hoac remote loader noi bo. Khong nen de generic theme runtime nam ben ngoai package nua neu muc tieu la cai o may khac cung chay ngay.
+
+Khong nen de moi MFE tu dung shell rieng, tu tao palette rieng, hoac tu viet lai `Button/Input/Card`.
+
+## 2. Cau truc folder khuyen nghi
+
+```text
+.
+├─ package.json
+├─ pnpm-workspace.yaml
+├─ tsconfig.base.json
+└─ apps/
+   ├─ shell/
+   │  ├─ src/app/
+   │  ├─ src/layouts/
+   │  ├─ src/routes/
+   │  ├─ src/remotes/
+   │  ├─ src/styles/
+   │  │  ├─ index.css
+   │  │  └─ ui-theme.css
+   │  ├─ src/main.tsx
+   │  └─ vite.config.ts
+   └─ users-mfe/
+      ├─ src/features/
+      ├─ src/pages/
+      ├─ src/routes/
+      ├─ src/services/
+      ├─ src/styles/
+      │  └─ index.css
+      ├─ src/bootstrap.tsx
+      └─ vite.config.ts
+```
 
-CLI này sẽ tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts` theo đúng convention bên dưới. `AGENTS.md` giờ khóa luôn flow hỏi input -> đọc layout preset -> dựng shell -> mới tới page body. Nếu không truyền `--theme`, preset mặc định là `ocean`.
+Neu base cua ban dang dung `mfes/` thay vi `apps/`, co the giu nguyen ten folder. Dieu can giu on dinh la trach nhiem cua `shell`, `remote`, va package UI chung.
 
-## 1. Import style đúng thứ tự
+## 3. Root config toi thieu
 
-Import package CSS trước, rồi mới import file override theme của project.
+### `pnpm-workspace.yaml`
+
+```yaml
+packages:
+  - apps/*
+  - packages/*
+```
+
+### `tsconfig.base.json`
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": "."
+  }
+}
+```
+
+`@lucasvu/scope-ui` nen duoc dung nhu workspace package that hoac npm package that. Neu project khong dung React, import tu `@lucasvu/scope-ui/core`.
+
+## 4. Import style dung thu tu
+
+Import package CSS truoc, roi moi toi bundled theme layer cua package neu can, roi moi toi file override rieng cua app.
 
 ```ts
 import '@lucasvu/scope-ui/styles.css'
+import '@lucasvu/scope-ui/themes/theme-ui-new-main-fe.css'
 import './styles/ui-theme.css'
+import './styles/index.css'
 ```
 
-`ui-theme.css` nên là nơi duy nhất override màu, surface, border, shadow và gradient của thư viện.
+Thu tu nay co chu dich:
 
-## 2. Chọn preset theme của project
+1. `@lucasvu/scope-ui/styles.css`: nap token va component style goc.
+2. `@lucasvu/scope-ui/themes/*.css`: optional bundled shell/theme layer ship cung package.
+3. `./styles/ui-theme.css`: app shell override nhe neu can.
+4. `./styles/index.css`: reset va layout cuc bo cua shell.
 
-Đặt file tại `src/styles/ui-theme.css`.
+Neu khong muon them bundled theme layer, co the bo qua buoc 2 va import `src/styles/ui-theme.css` ngay sau package stylesheet.
 
-Dùng `--list-themes` để xem preset được duyệt, rồi generate preset đã chọn:
+## 5. Color mode va packaged theme layer
 
-```bash
-npx scope-ui-init --list-themes
-npx scope-ui-init --theme graphite
+Package da export san color-mode runtime:
+
+```tsx
+import {
+  applyDocumentClientTheme,
+  initializeDocumentColorMode,
+} from '@lucasvu/scope-ui/core'
+
+initializeDocumentColorMode()
+applyDocumentClientTheme('neo-slate')
 ```
 
-File generate ra sẽ là source of truth cho palette, surface, radius và shadow của project. Agent phải bám vào file này thay vì tự nghĩ màu mới.
+Dung `applyDocumentClientTheme(...)` khi ban import theme layer dang attribute-scoped, vi du:
+
+```ts
+import '@lucasvu/scope-ui/themes/theme-ui-neo-slate.css'
+```
+
+Theme layer co 2 nhom:
+
+- global: import la apply ngay, vi du `theme-default.css`, `theme-ui-new-main-fe.css`
+- data-client-theme: can them `data-client-theme` vao `document.documentElement`, vi du `theme-ui-neo-slate.css`
+
+Danh sach nay co san trong `uiThemeLayerAssets`.
+
+## 6. Step-by-step dung shell app
+
+### Buoc 1: Tao folder shell
+
+```text
+apps/shell/src/
+├─ app/
+├─ layouts/
+├─ routes/
+├─ remotes/
+├─ styles/
+│  ├─ index.css
+│  └─ ui-theme.css
+└─ main.tsx
+```
+
+### Buoc 2: Khoi dong theme o entry
+
+```tsx
+import '@lucasvu/scope-ui/styles.css'
+import '@lucasvu/scope-ui/themes/theme-ui-new-main-fe.css'
+import './styles/ui-theme.css'
+import './styles/index.css'
+
+import { initializeDocumentColorMode } from '@lucasvu/scope-ui'
+
+initializeDocumentColorMode()
+```
+
+Neu dung mot client theme nhu `neo-slate`, `pure-white`, `solstice-pop`, them:
+
+```tsx
+import { applyDocumentClientTheme } from '@lucasvu/scope-ui'
+
+applyDocumentClientTheme('neo-slate')
+```
 
-`AGENTS.md` sẽ có thêm shell brief + screen brief dạng YAML để agent điền các giá trị như `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` trước khi bắt đầu viết JSX.
+### Buoc 3: Shell so huu app frame
 
-`src/layout-presets/workspace-admin-v1.ts` là source of truth cho shared shell: dark sidebar, gradient topbar, intro card, optional segmented tabs, toolbar card, rồi mới tới body card/table/form.
+Shell nen so huu:
+
+- sidebar
+- topbar
+- route container
+- remote mount point
+- theme selector
+- toaster/modal root neu co
+
+Remote khong nen tu render mot shell khac neu dang chay ben trong host shell.
+
+### Buoc 4: Shell doc layout preset truoc khi dung page
+
+`src/layout-presets/workspace-admin-v1.ts` la source of truth cho shared shell:
+
+- dark sidebar
+- gradient topbar
+- intro card
+- optional segmented tabs
+- toolbar card
+- body card/table/form
+
+Khong nen bo qua preset nay roi ve mot page frame phang moi lan AI code.
+
+## 7. Step-by-step dung remote app
+
+### Folder toi thieu
+
+```text
+apps/users-mfe/src/
+├─ features/users/
+├─ pages/
+├─ routes/
+├─ services/
+├─ styles/
+│  └─ index.css
+└─ bootstrap.tsx
+```
+
+### Rule cho remote
+
+- Dung component tu `@lucasvu/scope-ui`.
+- Khong tao them bo token/theme moi trong remote neu khong that can.
+- Chi them CSS cho page hoac behavior dac thu cua remote.
+- Neu remote chay standalone de local dev, van import style theo dung thu tu o tren.
+- Remote so huu page business, khong so huu app shell chung.
+
+## 8. Theme chung nen dat o dau
+
+Nen chia thanh 3 lop:
+
+### Lop 1: UI base
+
+`@lucasvu/scope-ui/styles.css`
+
+Lop nay dinh nghia token mac dinh va style component.
+
+### Lop 2: Bundled theme layer cua package
+
+`@lucasvu/scope-ui/themes/*.css`
+
+Vi du:
+
+- `@lucasvu/scope-ui/themes/theme-default.css`
+- `@lucasvu/scope-ui/themes/theme-ui-new-main-fe.css`
+- `@lucasvu/scope-ui/themes/theme-ui-neo-slate.css`
+
+Day la noi package ship them shell token, typography, va visual language dung lai duoc tren may khac.
+
+### Lop 3: App override rat mong
+
+`apps/shell/src/styles/ui-theme.css`
+
+File nay chi nen override mot vai token neu shell can branding rieng:
 
 ```css
 :root {
@@ -53,37 +273,58 @@ File generate ra sẽ là source of truth cho palette, surface, radius và shado
   --tw-accent: 24 95% 52%;
   --primary-grad-from: 24 95% 52%;
   --primary-grad-to: 12 88% 56%;
-  --surface: rgba(255, 248, 240, 0.92);
 }
 
 .dark {
   --tw-primary: 18 100% 62%;
   --tw-accent: 35 100% 58%;
-  --surface: rgba(24, 24, 27, 0.82);
 }
 ```
 
-Không nên override màu trực tiếp trong từng component nếu chỉ đang đổi theme.
+Khong nen doi mau truc tiep trong tung component neu chi dang doi theme.
+
+## 9. Chon preset theme cua project
+
+Dat file tai `src/styles/ui-theme.css`.
+
+Dung `--list-themes` de xem preset duoc duyet, roi generate preset da chon:
+
+```bash
+npx scope-ui-init --list-themes
+npx scope-ui-init --theme graphite
+```
+
+File generate ra se la source of truth cho palette, surface, radius va shadow cua project. Agent phai bam vao file nay thay vi tu nghi mau moi.
+
+Neu can them mot bundled package theme layer de co shell tone dung san, import no o app entry. Neu theme layer do la attribute-scoped, set them `data-client-theme` bang `applyDocumentClientTheme`.
 
-`src/layout-presets/workspace-admin-v1.ts` không cần import vào runtime. Đây là layout contract cho agent/codegen đọc để giữ dark sidebar, gradient topbar, intro card, tab row, và toolbar card nhất quán giữa các màn.
+`AGENTS.md` se co them shell brief + screen brief dang YAML de agent dien cac gia tri nhu `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` truoc khi bat dau viet JSX.
 
-## 3. Rule cho AI của project
+`src/layout-presets/workspace-admin-v1.ts` khong can import vao runtime. Day la layout contract cho agent/codegen doc de giu dark sidebar, gradient topbar, intro card, tab row, va toolbar card nhat quan giua cac man.
 
-Copy phần này vào system prompt, repo instructions, `AGENTS.md`, Cursor rules, hoặc bất kỳ chỗ nào project đang dùng để ép AI theo convention:
+## 10. Rule cho AI cua project
+
+Copy phan nay vao system prompt, repo instructions, `AGENTS.md`, Cursor rules, hoac bat ky cho nao project dang dung de ep AI theo convention:
 
 ```md
-Use `@lucasvu/scope-ui` as the default UI library.
+Use `@lucasvu/scope-ui` for React projects and `@lucasvu/scope-ui/core` for framework-agnostic theme/runtime usage.
 
 Always:
+- use `@lucasvu/scope-ui` as the shared React UI package when the app is React
+- use `@lucasvu/scope-ui/core` when the app only needs theme/runtime/contracts
 - import `@lucasvu/scope-ui/styles.css` once at the app entry
-- import the project theme override file after the package stylesheet
+- if the repo chooses a bundled theme layer, import it from `@lucasvu/scope-ui/themes/*` after the package stylesheet
+- import the project theme override file after the bundled theme layer
+- use `initializeDocumentColorMode` from `@lucasvu/scope-ui/core` when the app shell owns dark/light mode
+- if a bundled theme layer is client-theme-scoped, set `data-client-theme` via `applyDocumentClientTheme` from `@lucasvu/scope-ui/core`
 - use root exports from `@lucasvu/scope-ui`
 - stay inside the approved preset declared by `src/styles/ui-theme.css`
 - read `src/layout-presets/workspace-admin-v1.ts` before changing the app shell or page frame
 - follow the step-by-step UI build workflow from `AGENTS.md` before writing JSX
+- keep the shell in the host app and keep remotes focused on page business content
 - fill the shell + screen brief first: `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, and the page-specific schema
 - read `uiAiManifest` to choose the right component by intent
-- read `uiScreenBlueprint` and `uiThemeContract` before changing layout, colors, surfaces, borders, or shadows
+- read `uiScreenBlueprint`, `uiThemeContract`, and `uiThemeLayerAssets` before changing layout, colors, surfaces, borders, or shadows
 
 Do not:
 - import from `MainFe` unless the task explicitly targets a legacy screen
@@ -91,6 +332,7 @@ Do not:
 - replace the shared dark-sidebar + gradient-topbar shell unless the task explicitly asks for a new shell
 - hardcode brand colors inside page components when a theme token already exists
 - create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
+- let each remote define a different shell or a different palette
 
 Component choice:
 - `Input` for short text
@@ -104,32 +346,53 @@ Component choice:
 - `DataTable` for tabular records
 ```
 
-## 4. Runtime contract cho AI/codegen
+## 11. Runtime contract cho AI/codegen
 
-Trong code, AI có thể đọc trực tiếp:
+Trong code, AI co the doc truc tiep:
 
 ```ts
-import { uiAiManifest, uiScreenBlueprint, uiThemeContract, uiThemePresets, uiProjectAiRules } from '@lucasvu/scope-ui'
+import {
+  applyDocumentClientTheme,
+  initializeDocumentColorMode,
+  uiAiManifest,
+  uiProjectAiRules,
+  uiScreenBlueprint,
+  uiThemeContract,
+  uiThemeLayerAssets,
+  uiThemePresets,
+} from '@lucasvu/scope-ui/core'
 ```
 
-- `uiAiManifest`: chọn component theo intent
-- `uiScreenBlueprint`: brief input và khung layout chuẩn cho `list | form | detail | dashboard`, gồm cả shell fields như `layoutPreset`, `workspaceLabel`, `pageTabs`, `searchPlaceholder`
-- `uiThemeContract`: biết override token nào và override ở đâu
-- `uiThemePresets`: danh sách preset được duyệt để nhiều project dùng chung một visual language
-- `uiProjectAiRules`: rule ngắn gọn để inject vào agent của project
+- `initializeDocumentColorMode`: dong bo dark/light mode o document root
+- `applyDocumentClientTheme`: set `data-client-theme` cho bundled theme layer dang attribute-scoped
+- `uiAiManifest`: chon component theo intent
+- `uiScreenBlueprint`: brief input va khung layout chuan cho `list | form | detail | dashboard`, gom ca shell fields nhu `layoutPreset`, `workspaceLabel`, `pageTabs`, `searchPlaceholder`
+- `uiThemeContract`: biet override token nao va override o dau
+- `uiThemeLayerAssets`: danh sach bundled theme layer co san trong package, gom ca import path va activation mode
+- `uiThemePresets`: danh sach preset duoc duyet de nhieu project dung chung mot visual language
+- `uiProjectAiRules`: rule ngan gon de inject vao agent cua project
+
+Neu project dung React components cua package, van import component tu root package:
+
+```ts
+import { Button, Card, Input, Select } from '@lucasvu/scope-ui'
+```
 
-## 5. Chỗ override theme
+## 12. Cho override theme
 
-Nếu project có app shell:
+Neu project co app shell:
 
-- import `@lucasvu/scope-ui/styles.css` ở app entry
-- import `src/styles/ui-theme.css` ngay sau đó
-- để agent đọc `src/layout-presets/workspace-admin-v1.ts` trước khi build page shell
-- toggle dark mode bằng class `.dark` trên `html` hoặc `body`, hoặc dùng `[data-ui-theme='dark']`
+- import `@lucasvu/scope-ui/styles.css` o app entry
+- import mot bundled package theme layer neu muon
+- import `src/styles/ui-theme.css` ngay sau do
+- goi `initializeDocumentColorMode()` o host app
+- neu dung client theme layer, goi `applyDocumentClientTheme('<theme-id>')`
+- de agent doc `src/layout-presets/workspace-admin-v1.ts` truoc khi build page shell
+- toggle dark mode bang class `.dark` tren `html` hoac `body`, hoac dung `[data-ui-theme='dark']`
 
-Nếu project có nhiều brand/theme:
+Neu project co nhieu brand/theme:
 
-- giữ `:root` là theme mặc định
-- tạo selector như `[data-ui-theme='brand-a']`, `[data-ui-theme='brand-b']`
-- vẫn nên xuất phát từ một preset duyệt sẵn rồi mới override token cần thiết
-- chỉ override token trong file theme, không fork component
+- giu `:root` la theme mac dinh
+- tao selector nhu `[data-ui-theme='brand-a']`, `[data-ui-theme='brand-b']` hoac dung `data-client-theme`
+- van nen xuat phat tu mot preset duyet san roi moi override token can thiet
+- chi override token trong file theme, khong fork component

package/README.md

@@ -1,6 +1,9 @@
 # @lucasvu/scope-ui
 
-Bộ component phong cách **shadcn** dùng chung cho các app/micro-frontend trong workspace. Tất cả đều là React component thuần, kèm sẵn theme tối và hiệu ứng kính mờ.
+Bộ UI dùng chung cho các app/micro-frontend trong workspace.
+
+- Root package `@lucasvu/scope-ui`: React components + full UI surface
+- Core subpath `@lucasvu/scope-ui/core`: theme/runtime/contracts không phụ thuộc React
 
 ## Cách dùng nhanh
 
@@ -10,13 +13,40 @@ Bộ component phong cách **shadcn** dùng chung cho các app/micro-frontend tr
 npm install @lucasvu/scope-ui
 ```
 
-2. Import global style một lần ở entry (ví dụ `main.tsx`):
+2. Nếu dùng React, import từ root package:
 
 ```ts
 import '@lucasvu/scope-ui/styles.css';
+import '@lucasvu/scope-ui/themes/theme-ui-new-main-fe.css';
+import './styles/ui-theme.css';
+```
+
+Nếu muốn dùng theme layer dạng client-theme, ví dụ `neo-slate`, set thêm ở app entry:
+
+```ts
+import { applyDocumentClientTheme, initializeDocumentColorMode } from '@lucasvu/scope-ui';
+
+initializeDocumentColorMode();
+applyDocumentClientTheme('neo-slate');
 ```
 
-3. Nếu muốn bootstrap rule/theme/layout cho AI trong project consumer:
+3. Nếu không dùng React, import phần generic từ `@lucasvu/scope-ui/core`:
+
+```ts
+import '@lucasvu/scope-ui/styles.css';
+import '@lucasvu/scope-ui/themes/theme-ui-neo-slate.css';
+
+import {
+  applyDocumentClientTheme,
+  initializeDocumentColorMode,
+  uiThemeLayerAssets,
+} from '@lucasvu/scope-ui/core';
+
+initializeDocumentColorMode();
+applyDocumentClientTheme('neo-slate');
+```
+
+4. Nếu muốn bootstrap rule/theme/layout cho AI trong project consumer:
 
 ```bash
 npm install @lucasvu/scope-ui
@@ -33,7 +63,7 @@ Lưu ý: các lệnh này chỉ chạy được sau khi project đã cài `@luca
 
 Lệnh này sẽ tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts` trong repo hiện tại theo preset đã chọn. `AGENTS.md` giờ có thêm playbook step-by-step để agent hỏi đủ input, đọc layout preset, rồi dựng màn hình đúng layout/component/theme chung. Nếu không truyền `--theme`, preset mặc định là `ocean`. Dùng `--force` nếu muốn overwrite file đã tồn tại.
 
-4. Dùng component:
+5. Dùng component:
 
 ```tsx
 import {
@@ -104,12 +134,49 @@ export function Example() {
 - `Field` phù hợp khi bạn cần bọc một control custom hoặc gom nhiều control dưới cùng một nhãn.
 - Nếu bạn đổi tên package trước khi publish, thay `@lucasvu/scope-ui` trong các ví dụ bằng package name mới.
 
+## Bundled Theme Layers
+
+Package ship sẵn các theme asset để máy khác cài vào là dùng được ngay:
+
+- Global apply ngay khi import: `@lucasvu/scope-ui/themes/theme-default.css`, `@lucasvu/scope-ui/themes/theme-ui-new-main-fe.css`
+- Client-theme scoped: `@lucasvu/scope-ui/themes/theme-ui-neo-slate.css`, `@lucasvu/scope-ui/themes/theme-ui-facebook-blue.css`, `@lucasvu/scope-ui/themes/theme-ui-solstice-pop.css`, ...
+
+Bạn có thể đọc manifest ngay trong code:
+
+```ts
+import { uiThemeLayerAssets } from '@lucasvu/scope-ui/core';
+```
+
+Nếu một theme có `activation: 'data-client-theme'`, hãy gọi `applyDocumentClientTheme('<theme-id>')` sau khi import CSS của theme đó.
+
+## Core Surface
+
+Nếu project không dùng React nhưng vẫn muốn dùng theme/runtime/contracts của package, dùng:
+
+```ts
+import {
+  applyDocumentClientTheme,
+  initializeDocumentColorMode,
+  uiAiManifest,
+  uiProjectAiRules,
+  uiScreenBlueprint,
+  uiThemeContract,
+  uiThemeLayerAssets,
+  uiThemePresets,
+} from '@lucasvu/scope-ui/core';
+```
+
+`@lucasvu/scope-ui/core` không export React component surface.
+
 ## Dùng cho AI/codegen
 
 Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng chỉ đưa mỗi tên package. Hãy để agent bám vào một surface chuẩn:
 
 - Import CSS global một lần: `@lucasvu/scope-ui/styles.css`
-- Import file theme override của project ngay sau package CSS, ví dụ `./styles/ui-theme.css`
+- Nếu project muốn dùng shell/theme layer dựng sẵn, import từ `@lucasvu/scope-ui/themes/*` ngay sau package CSS
+- Import file theme override của project ngay sau bundled theme layer, ví dụ `./styles/ui-theme.css`
+- Dùng `initializeDocumentColorMode()` từ `@lucasvu/scope-ui` khi shell sở hữu dark/light mode
+- Nếu bundled theme layer là client-theme scoped, set `data-client-theme` bằng `applyDocumentClientTheme(...)`
 - Cài package trước khi bootstrap: `npm install @lucasvu/scope-ui`
 - Chạy `npx scope-ui-init --list-themes` để xem preset được duyệt
 - Chạy `npx scope-ui-init --theme <preset>` ở project consumer sau khi đã cài `@lucasvu/scope-ui` để tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts`
@@ -123,12 +190,15 @@ Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng
 
 ```ts
 import {
+  applyDocumentClientTheme,
+  initializeDocumentColorMode,
   uiAiManifest,
   uiProjectAiRules,
   uiScreenBlueprint,
   uiThemeContract,
+  uiThemeLayerAssets,
   uiThemePresets,
-} from '@lucasvu/scope-ui';
+} from '@lucasvu/scope-ui/core';
 ```
 
 `uiAiManifest` mô tả luật chọn component theo intent như: text input, textarea, fixed select, searchable select, async combobox, multi select, data table, alert, card và field wrapper.
@@ -137,13 +207,15 @@ import {
 
 `uiThemeContract` mô tả token màu, surface, border, shadow, radius, gradient và selector theme (`:root`, `.dark`, `[data-ui-theme='*']`) để AI không hardcode màu sai chỗ.
 
+`uiThemeLayerAssets` mô tả các theme layer CSS được ship sẵn trong package, import path tương ứng, và theme nào cần `data-client-theme`.
+
 `uiThemePresets` là danh sách preset được duyệt sẵn để nhiều project có thể chọn cùng một visual language mà không cần tự dựng theme từ đầu.
 
 `AI_SETUP.md` và CLI `scope-ui-init` giúp bootstrap rule/theme/layout cho repo consumer mà không cần copy tay.
 
 ## Theme Override
 
-Nên để toàn bộ override theme của project vào một file riêng, ví dụ `src/styles/ui-theme.css`, rồi import file này sau `@lucasvu/scope-ui/styles.css`.
+Nên để toàn bộ override theme của project vào một file riêng, ví dụ `src/styles/ui-theme.css`, rồi import file này sau `@lucasvu/scope-ui/styles.css` và sau bundled theme layer nếu có.
 
 Cách nhanh nhất là generate bộ file này từ preset:
 
@@ -155,6 +227,7 @@ npx scope-ui-init --theme ocean
 
 ```ts
 import '@lucasvu/scope-ui/styles.css';
+import '@lucasvu/scope-ui/themes/theme-ui-new-main-fe.css';
 import './styles/ui-theme.css';
 ```
 

package/bin/copy-theme-assets.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+const sourceDir = resolve(process.cwd(), '../shared/theme')
+const targetDir = resolve(process.cwd(), 'dist/themes')
+
+if (!existsSync(sourceDir)) {
+  console.error(`Theme asset source not found: ${sourceDir}`)
+  process.exit(1)
+}
+
+rmSync(targetDir, { force: true, recursive: true })
+mkdirSync(targetDir, { recursive: true })
+
+const themeFiles = readdirSync(sourceDir)
+  .filter((fileName) => fileName.endsWith('.css'))
+  .sort()
+
+for (const fileName of themeFiles) {
+  const sourceFile = join(sourceDir, fileName)
+  const targetFile = join(targetDir, fileName)
+
+  mkdirSync(dirname(targetFile), { recursive: true })
+  copyFileSync(sourceFile, targetFile)
+}
+
+console.log(`Copied ${themeFiles.length} theme assets to dist/themes`)