@cyberskill/design 2.8.0 → 2.9.0

package/docs/vi/entrypoints/README.md

@@ -4,20 +4,20 @@
 
 [![Design System Gates](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml/badge.svg)](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml)
 
-Hệ thống thiết kế ấm áp, chuẩn doanh nghiệp, **ưu tiên tiếng Việt** cho **CyberSkill** — studio phần mềm Sài Gòn (thành lập 2020) biến *điều ước* rõ ràng thành phần mềm hoạt động. Neo trên **Umber** và **Ochre**, dẫn dắt bởi thần đèn vàng **Lumi**, mọi bề mặt giải quyết bốn trục độc lập: **Theme** (light · dark · system) × **Element** (bản sắc sản phẩm Ngũ Hành: Kim · Mộc · Thủy · Hỏa · Thổ, 15 biến thể) × **Language** (EN · VI) × **Style** (`data-cs-style` — gói duy nhất **liquid-glass**; không khai báo ≡ mặc định). Phía sử dụng chỉ cần liên kết một tệp: **`styles.css`** (`dist/styles.css` là cùng closure được làm phẳng thành một tệp cho các môi trường không theo chuỗi `@import` như bộ hiển thị thẻ và một số sandbox; sinh lại bằng `npm run build:css` sau khi sửa `tokens/` hoặc `base/`).
+Hệ thống thiết kế ấm áp, chuẩn doanh nghiệp, **ưu tiên tiếng Việt** cho **CyberSkill** — studio phần mềm Sài Gòn (thành lập 2020) biến *điều ước* rõ ràng thành phần mềm hoạt động. Neo trên **Umber** và **Ochre**, dẫn dắt bởi thần đèn vàng **Lumi**, mọi bề mặt giải quyết bốn trục độc lập: **Theme** (light · dark · system) × **Element** (bản sắc sản phẩm Ngũ Hành: Kim · Mộc · Thủy · Hỏa · Thổ, 15 biến thể) × **Language** (VI · EN) × **Style** (`data-cs-style` — **liquid-glass** mặc định, không khai báo ≡ mặc định · **matte-paper** bề mặt giấy mờ đặc sắc nét). Phía sử dụng chỉ cần liên kết một tệp: **`styles.css`** (`dist/styles.css` là cùng closure được làm phẳng thành một tệp cho các môi trường không theo chuỗi `@import` như bộ hiển thị thẻ và một số sandbox; sinh lại bằng `npm run build:css` sau khi sửa `tokens/` hoặc `base/`).
 
 ---
 
 ## Bắt đầu tại đây
 
-Đây là **tài liệu điểm vào** của CyberSkill Design System — VERSION của bản nguồn **<!-- cs-source-version:checkout -->2.8.0<!-- /cs-source-version -->** (xem `VERSION`; không xác nhận phiên bản có trên registry). **Trang sản phẩm** là Storybook tại **`/`** trên `design.cyberskill.world` (chỉ trên host; cục bộ: `npm run storybook`). Tài liệu vận hành được công bố ở thanh bên **Docs** của Storybook và Thư viện tài liệu tại `/docs/viewer.html` (các đường dẫn cũ `/dashboard`, `/dashboard.html` và `/playground/*` chuyển hướng về `/`).
+Đây là **tài liệu điểm vào** của CyberSkill Design System — VERSION của bản nguồn **<!-- cs-source-version:checkout -->2.9.0<!-- /cs-source-version -->** (xem `VERSION`; không xác nhận phiên bản có trên registry). **Trang sản phẩm** là Storybook tại **`/`** trên `design.cyberskill.world` (chỉ trên host; cục bộ: `npm run storybook`). Tài liệu vận hành được công bố ở thanh bên **Docs** của Storybook và Thư viện tài liệu tại `/docs/viewer.html` (các đường dẫn cũ `/dashboard`, `/dashboard.html` và `/playground/*` chuyển hướng về `/`).
 
 ### Bắt đầu nhanh theo đối tượng
 
 - **Nhà thiết kế** — mở Storybook (**Foundations / Components / Templates / Pages / Docs**). **Templates** liệt kê toàn bộ <!-- cs-count:templates -->85<!-- /cs-count --> điểm khởi đầu (Gallery → Atomic View, cùng story theo nhóm, gồm bộ 38 tài liệu VN A4 (Employment Suite + khung thương mại) tại **Templates → HR**). Đổi trực tiếp Theme × Element × Language × Style qua thanh công cụ Storybook, Atomic View và mẫu Elements Geometry.
 - **Soạn template trình duyệt** (máy chủ HTTP tĩnh) — đọc `SKILL.md` (chọn runtime + ràng buộc thiết kế), rồi hướng dẫn bên dưới; phối hợp `styles.css` + ESM đã biên dịch `@cyberskill/design` (`dist/esm/_esm/react.mjs`; JSX thô qua `@cyberskill/design/source`) / `_esm/cs.mjs` cũ / `_ds_bundle.js` (tìm theo tiền tố). `support.js` được cung cấp thông dịch `*.dc.html` trong trình duyệt; xem `docs/template-grammar.md` về ngữ pháp và ranh giới chỉ ở host. Hợp đồng component nằm cạnh từng component (`.d.ts` + `.prompt.md`).
 - **Tĩnh / open-spec** (ví dụ Google Stitch) — bắt đầu từ **`DESIGN.md`** (open-spec được sinh) → `llms.txt` → `tokens/tokens.dtcg.json`. Dựng giao diện **tĩnh** bằng `styles.css` + `.cs-*` / kitchen-sink / `examples/static-hello/`. Dùng `.dc.html` qua trình thông dịch được cung cấp hoặc công cụ hiểu ngữ pháp; công cụ HTML thuần dùng `.cs-*` hoặc ảnh chụp kết quả hiển thị đã kiểm chứng.
-- **Người triển khai** — gói npm ổn định đã công bố **`@cyberskill/design@2.7.0`** (xem `docs/consuming.md`; quyền dùng trong `docs/consumer-grant.md` — vẫn UNLICENSED). **Next/SSR:** `import { Button } from "@cyberskill/design"` (peer React). **Demo trình duyệt:** **`examples/npm-hello/`** (Lumi · Hỏa · plasma, `_esm/cs.mjs` cũ). Hoặc liên kết **`styles.css`** từ clone/subtree (một tệp cho toàn bộ), hoặc chép thư mục `templates/<slug>/` và sửa một dòng trong `ds-base.js` (đổi liên kết một dòng, được kiểm định đầu cuối tháng 7/2026). Xác định scope bằng `data-theme` · `data-cs-element` (+`data-cs-variant`) · `lang`. Dấu hiệu bản phát hành: SHA đầu nhánh + `docs/release-notes.md` (VERSION nguồn là **<!-- cs-source-version:release-signal -->2.8.0<!-- /cs-source-version -->**; không có CHANGELOG).
+- **Người triển khai** — gói npm ổn định đã công bố **`@cyberskill/design@2.8.0`** (xem `docs/consuming.md`; quyền dùng trong `docs/consumer-grant.md` — vẫn UNLICENSED). **Next/SSR:** `import { Button } from "@cyberskill/design"` (peer React). **Demo trình duyệt:** **`examples/npm-hello/`** (Lumi · Hỏa · plasma, `_esm/cs.mjs` cũ). Hoặc liên kết **`styles.css`** từ clone/subtree (một tệp cho toàn bộ), hoặc chép thư mục `templates/<slug>/` và sửa một dòng trong `ds-base.js` (đổi liên kết một dòng, được kiểm định đầu cuối tháng 7/2026). Xác định scope bằng `data-theme` · `data-cs-element` (+`data-cs-variant`) · `lang`. Dấu hiệu bản phát hành: SHA đầu nhánh + `docs/release-notes.md` (VERSION nguồn là **<!-- cs-source-version:release-signal -->2.9.0<!-- /cs-source-version -->**; không có CHANGELOG).
 - **Người bảo trì** — `docs/doctrine.md` (mở rộng + kiểm chứng), rồi `CONTRIBUTING.md` và `docs/quality-gates.md`.
 
 ### Bản đồ tài liệu — phía sử dụng
@@ -31,11 +31,11 @@ Hệ thống thiết kế ấm áp, chuẩn doanh nghiệp, **ưu tiên tiếng
 | `docs/consumer-grant.md` | Văn bản cấp quyền sử dụng gói npm (danh mục CyberSkill; UNLICENSED + sản phẩm được nêu tên) |
 | `docs/conventions.md` | Cách mở rộng hệ thống (ngữ pháp đặt tên, danh sách kiểm tra, bốn trục) |
 | `docs/release-notes.md` | Điểm nổi bật sản phẩm được biên tập (không phải changelog) |
-| `docs/design-styles.md` | Các trục kiểu trực tiếp (Theme × Element × Language × Style) và cách xử lý liquid-glass cố định |
+| `docs/design-styles.md` | Các trục kiểu trực tiếp (Theme × Element × Language × Style) và hai gói vật liệu bề mặt (liquid-glass · matte-paper) |
 | `docs/products.md` | Registry sản phẩm → hành (**đã khóa** — không tự đặt phân bổ) |
 | `docs/contrast-report.md` | Quét APCA Ngũ Hành được sinh — 0 lỗi tại ngưỡng nhãn UI Lc ≥ 60. Người soạn nội dung theo ngưỡng chặt hơn Lc ≥ 75 (xem Bất biến nền tảng); dòng Lc ≥ 60 của phép quét là cặp accent/nhãn, không phải văn bản nội dung. |
 | `docs/template-schema-v2.md` | Đặc tả slot nội dung có kiểu cho template — tùy chọn áp dụng, máy có thể kiểm tra |
-| `docs/deploy.md` | Triển khai trang trực tiếp — Vercel (không cấu hình) · VPS/nginx tổng quát · kiểm tra sau triển khai |
+| `docs/deploy.md` | Triển khai trang trực tiếp — GitHub Pages (`.github/workflows/pages.yml`) · Vercel · VPS/nginx tổng quát · kiểm tra sau triển khai |
 | `docs/live-hub.md` | Storybook tại `/` là bề mặt sản phẩm; bản đồ bề mặt |
 | `docs/storybook.md` | Host bề mặt sản phẩm Storybook tại `/` — thanh bên Docs là bề mặt đọc công bố |
 | `docs/figma.md` | Cách import Figma / Tokens Studio cho phía sử dụng và bảo trì |
@@ -71,7 +71,7 @@ Hệ thống thiết kế ấm áp, chuẩn doanh nghiệp, **ưu tiên tiếng
 | Ngôn ngữ | Ưu tiên tiếng Việt; mỗi chuỗi giao diện có cặp EN + VN |
 | Ngưỡng tiếp cận tối thiểu | APCA Lc ≥ 75 cho văn bản nội dung; không bao giờ bỏ vòng tiêu điểm; vùng chạm ≥ 44px |
 | Các trục | Theme × Element × Language × Style (độc lập) |
-| Gói phong cách | liquid-glass (gói duy nhất; không khai báo ≡ mặc định) |
+| Gói phong cách | liquid-glass (mặc định; không khai báo ≡ mặc định) · matte-paper |
 <!-- END DOCTRINE IMMUTABLES -->
 
 ---
@@ -96,7 +96,7 @@ Hệ thống thiết kế ấm áp, chuẩn doanh nghiệp, **ưu tiên tiếng
 
 ## Nền tảng thị giác
 
-- **Bảng màu — đất ấm, không lạnh.** Umber `#45210E` làm nền tảng mọi thứ (chính là màu chữ chính); Ochre `#F4BA17` là accent duy nhất — CTA trên nền tối, vòng tiêu điểm, điểm nhấn, thần đèn. Bề mặt là giấy ấm: page `#FFFDF8`, panel `#FFFFFF`, raised `#FBF4E9`. Mọi màu trung tính ngả về umber — viền `#E7D9C6`, chữ mờ `#3F2D21`. Màu ngữ nghĩa (success `#166534`, danger `#B42318`, warning `#92400E`, info `#1D4ED8`) dùng tiết chế và không bao giờ là tín hiệu duy nhất. **Tối đa một accent trên mỗi bề mặt** — bề mặt lõi dùng Ochre; *sản phẩm* có thể thay bằng accent Ngũ Hành, không thêm sắc thứ hai cạnh nó. Không dùng gradient tím xanh.
+- **Bảng màu — đất ấm, không lạnh.** Umber `#45210E` làm nền tảng mọi thứ (chính là màu chữ chính); Ochre `#F4BA17` là accent duy nhất — CTA trên nền tối, vòng tiêu điểm, điểm nhấn, thần đèn. Bề mặt là giấy ấm: page `#FFFDF8`, panel `#FFFFFF`, raised `#FBF4E9`. Mọi màu trung tính ngả về umber — viền `#E7D9C6`, chữ mờ `#5E4436`. Màu ngữ nghĩa (success `#166534`, danger `#B42318`, warning `#92400E`, info `#1D4ED8`) dùng tiết chế và không bao giờ là tín hiệu duy nhất. **Tối đa một accent trên mỗi bề mặt** — bề mặt lõi dùng Ochre; *sản phẩm* có thể thay bằng accent Ngũ Hành, không thêm sắc thứ hai cạnh nó. Không dùng gradient tím xanh.
 - **Chữ.** UI: **Be Vietnam Pro** (300–800; họ chữ ưu tiên tiếng Việt) — mặc định trên mọi bề mặt, gồm cả tiêu đề. Display/tiêu đề lớn: **Space Grotesk** (biến thiên 300–700), font **tùy chọn** của `--cs-font-family-display`; không thành phần nào trỏ đến nó trước khi scope chọn `.cs-display-face`, chuyển `--cs-heading-family` và giữ văn bản nội dung ở font UI. Mã/dữ liệu: **JetBrains Mono**. Tiêu đề display đậm (800 ở font UI; trong `.cs-display-face`, Space Grotesk tối đa 700), giãn ký tự chặt (−0.02em); nội dung 400/500 ở 1.5. Dòng dẫn chữ hoa giãn 0.08–0.12em. Thang cỡ chạy từ xs 12 → 5xl 60 trên nền 16px.
 - **Khoảng cách và bố cục.** Lưới cơ sở 4px; padding section từ 64 đến 96px; max-width nội dung khoảng 1200–1320px. Khoảng trắng rộng rãi, tĩnh tại.
 - **Bo góc và thẻ.** Bán kính: sm 4, md 8 (mặc định), **lg 14 (thẻ/panel)**, full 999 (pill, input, chip). Thẻ mặc định = panel trắng, viền ấm 1px `#E7D9C6`, bán kính 14px, bóng ấm mềm. Không dùng thẻ có viền trái tô màu.
@@ -151,7 +151,7 @@ CyberSkill **không kèm thư viện icon bên ngoài**. Hệ thống dùng **b
 <!-- END CATALOG COMPONENT INVENTORY -->
 
 - **Điểm nổi bật:** **Button** — primary Umber; biến thể primary/secondary/tertiary/ghost/danger/danger-ghost; cỡ xs–lg; loading, icon, fullWidth. **TextField / Textarea / Select / NativeSelect** dùng chung khung `.cs-field` (nhãn + mô tả/lỗi; an toàn dấu/IME). **DataTable** — caption, header có scope, render theo cột, bộ trạng thái idle/loading/error/empty. **Card** — panel ấm + header/body/footer. **Logo** hiển thị đúng biểu trưng chính thức; **Icon** điều khiển bộ icon nét nội bộ. Họ **AI-native** mang doctrine giải trình của thương hiệu — công bố, review của con người, thu nhận điều ước và độ tin cậy, đều diễn đạt bằng lời (không chỉ bằng màu).
-- **Cài đặt / tên gói:** Tên gói là **`@cyberskill/design`** (VERSION bản nguồn **<!-- cs-source-version:package-source -->2.8.0<!-- /cs-source-version -->**; quyền trong `docs/consumer-grant.md` chi phối *sử dụng* — gói vẫn UNLICENSED). **Không** cài `@cyberskill/react` cho cây này — tên đó thuộc danh mục trang marketing lịch sử, không phải gói này.
+- **Cài đặt / tên gói:** Tên gói là **`@cyberskill/design`** (VERSION bản nguồn **<!-- cs-source-version:package-source -->2.9.0<!-- /cs-source-version -->**; quyền trong `docs/consumer-grant.md` chi phối *sử dụng* — gói vẫn UNLICENSED). **Không** cài `@cyberskill/react` cho cây này — tên đó thuộc danh mục trang marketing lịch sử, không phải gói này.
 - **Danh mục nguồn và phần mở rộng:** Bề mặt CyberSkill trước đây có sáu primitive — `Button`, `TextField`, `Dialog`, `DataTable`, `AIDisclosureBadge`, `HumanReviewGate` — cùng `Logo` thương hiệu. Mọi thành phần khác trong gói **này** là **mở rộng có chủ ý**, dựng bằng vốn token riêng của thương hiệu: `Icon`, các primitive Forms / Feedback / Data / Navigation / Overlays chuẩn, nhóm AI-native (`PromptInput`, `ChatMessage`, `ConfidenceMeter`, `PromptSuggestions`, `TypingIndicator`, `CitationList`) chính thức hóa luồng điều ước Lumi, và linh vật `LumiAvatar`.
 
 ---
@@ -272,6 +272,12 @@ SKILL.md                   Agent-Skills-compatible entry
 - **Kiểm chứng tiếp cận:** `_audit/a11y-harness.html` và `npm run test:a11y-harness` kiểm tra tên tiếp cận bằng axe cục bộ được ghim trên Chromium, Firefox và WebKit.
 - **Cổng benchmark trình duyệt trực tiếp & chống thoái lui:** `npm run test:audit-regression` (`_audit/ci/verify-audit-benchmarks-browser.mjs`) chấm **129/129** phép kiểm tra trên 20 chiều (`D1`–`D20`) đạt **10.0 / 10**, **64/64** phép kiểm tra cơ sở cốt lõi đạt **10.0 / 10**, **192/192** ô (`≥ 3.0:1`) trong ma trận tương phản phi văn bản 32×6, và **3/3** màn hình phức hợp Generation-2 với **0 watch**. Mực nền nhuộm phạm vi mặc định tối đạt **8.42:1–10.54:1** (`.cs-result__icon` đạt **8.42:1**, `.cs-item.is-selected` đạt **10.54:1** — cả hai đều vượt chuẩn WCAG AAA `7:1`).
 
+### Thiết lập, mở rộng & quy trình benchmark
+
+- **Thiết lập & máy chủ cục bộ:** Chạy `node scripts/bootstrap-toolchain.mjs && node scripts/npm.mjs ci` một lần trên Node >=22.12.0. Khởi chạy Storybook bằng `node scripts/npm.mjs run storybook` (`http://127.0.0.1:6006`) hoặc phục vụ bảng audit tĩnh bằng `node scripts/npm.mjs run verify:serve` (`http://127.0.0.1:8765/_audit/run.html`). Các bản đẩy lên nhánh `main` được triển khai tự động qua `.github/workflows/pages.yml` tới `https://design.cyberskill.world/`.
+- **Mở rộng token, component, template & open-spec:** Chỉnh sửa `tokens/*.css`, `tokens/base-inventory.json` và `base/*.css`, sau đó chạy `node scripts/npm.mjs run tokens:generate && node scripts/npm.mjs run build:css`. Thêm hoặc cập nhật primitive React trong `components/<group>/<Name>.{jsx,d.ts,prompt.md}`, `stories/<Name>/<Name>.stories.jsx` và `components/lifecycle.json`, rồi chạy `node scripts/npm.mjs run build`. Đăng ký template trong `templates/<slug>/` và `_ds_manifest.json` (`node scripts/generate-template-inventory.mjs`), đồng thời dựng lại open-spec cho Stitch/LLM bằng `node scripts/npm.mjs run build:design-md`.
+- **Audit, review & benchmark trong tương lai:** Chạy `node scripts/npm.mjs run test:audit-regression` để thực thi bộ benchmark Chromium trực tiếp 20 chiều (`D1`–`D20`) định nghĩa trong `_audit/ci/lib/benchmark-checks.mjs` trên `_audit/ci/fixtures/benchmark-20d.html`, `_audit/ci/fixtures/benchmark-baseline.html` và `_audit/ci/fixtures/benchmark-gen2.html`. Khi chạy benchmark thiết kế AI bên ngoài (Google Stitch hoặc Claude Design), hãy mã hóa mọi quy tắc thị giác/công thái học mới phát hiện vào `_audit/ci/lib/benchmark-checks.mjs`, kiểm chứng bằng `node scripts/npm.mjs run build:check`, và dọn sạch các tệp HTML/ảnh chụp benchmark tạm thời sau khi assertion chống thoái lui đã được khóa vào CI.
+
 <!-- BEGIN PINNED TOOLCHAIN BOOTSTRAP -->
 Trước khi chạy các lệnh `npm ci` hoặc `npm run` trong kho nguồn, dùng Node >=22.12.0 và chạy trực tiếp `node scripts/bootstrap-toolchain.mjs`. Lệnh này cài fixture npm 11.21.1 đã audit, ghim bằng lockfile, với lifecycle scripts bị tắt. Thêm `_audit/ci/fixtures/npm-cli/node_modules/.bin` vào PATH, hoặc chạy `node scripts/npm.mjs ci` và dùng `node scripts/npm.mjs` thay cho `npm` ở các lệnh tiếp theo (`devEngines` từ chối phiên bản npm khác trong kho nguồn; người dùng gói đã phát hành giữ package manager riêng). Xem [hướng dẫn kiểm tra và toolchain](../../../docs/validation.md).
 <!-- END PINNED TOOLCHAIN BOOTSTRAP -->

package/docs/vi/entrypoints/SKILL.md

@@ -81,7 +81,7 @@ Các bất biến của doctrine (suy ra từ nguồn):
 | Ngôn ngữ | Ưu tiên tiếng Việt; mỗi chuỗi giao diện có cặp EN + VN |
 | Ngưỡng tiếp cận tối thiểu | APCA Lc ≥ 75 cho văn bản nội dung; không bao giờ bỏ vòng tiêu điểm; vùng chạm ≥ 44px |
 | Các trục | Theme × Element × Language × Style (độc lập) |
-| Gói phong cách | liquid-glass (gói duy nhất; không khai báo ≡ mặc định) |
+| Gói phong cách | liquid-glass (mặc định; không khai báo ≡ mặc định) · matte-paper |
 
 - **static-html** — `styles.css`; [hướng dẫn](../../../DESIGN.md). Dùng lớp .cs-*; .dc.html còn cần trình thông dịch được cung cấp hoặc runtime hiểu ngữ pháp đã được kiểm chứng.
 - **react** — `@cyberskill/design`; [hướng dẫn](../../../docs/consuming.md). ESM đã biên dịch với peer React; @cyberskill/design/source tường minh là JSX thô. Không cam kết CommonJS.

package/docs/vi/entrypoints/llms.txt

@@ -62,7 +62,7 @@ Các bất biến của doctrine (suy ra từ nguồn):
 | Ngôn ngữ | Ưu tiên tiếng Việt; mỗi chuỗi giao diện có cặp EN + VN |
 | Ngưỡng tiếp cận tối thiểu | APCA Lc ≥ 75 cho văn bản nội dung; không bao giờ bỏ vòng tiêu điểm; vùng chạm ≥ 44px |
 | Các trục | Theme × Element × Language × Style (độc lập) |
-| Gói phong cách | liquid-glass (gói duy nhất; không khai báo ≡ mặc định) |
+| Gói phong cách | liquid-glass (mặc định; không khai báo ≡ mặc định) · matte-paper |
 
 - **static-html** — `styles.css`; [hướng dẫn](../../../DESIGN.md). Dùng lớp .cs-*; .dc.html còn cần trình thông dịch được cung cấp hoặc runtime hiểu ngữ pháp đã được kiểm chứng.
 - **react** — `@cyberskill/design`; [hướng dẫn](../../../docs/consuming.md). ESM đã biên dịch với peer React; @cyberskill/design/source tường minh là JSX thô. Không cam kết CommonJS.

package/docs/vi/four-axes.md

@@ -4,8 +4,8 @@ Hệ thống thiết kế cung cấp bốn trục **độc lập** — cùng cá
 
 1. **Theme** — `data-theme` — light (mặc định) · dark · **system** (`prefers-color-scheme` của hệ điều hành)
 2. **Element** — `data-cs-element` (+ `data-cs-variant` tùy chọn) — nhận diện sản phẩm Ngũ Hành: Kim · Mộc · Thủy · Hỏa · Thổ, các bộ khai báo trong [danh mục hiện hành](../reference-catalog.json) nằm trên thanh Element (cùng tập hợp với **Foundations/Elements**, Atomic View và các ánh xạ EL của mẫu)
-3. **Language** — `lang` — `en` · `vi` (xem **I18n**)
-4. **Style** — `data-cs-style` — hiện có duy nhất `liquid-glass` (không khai báo ≡ liquid-glass)
+3. **Language** — `lang` — `vi` (mặc định) · `en` (xem **I18n**)
+4. **Style** — `data-cs-style` — `liquid-glass` (mặc định; không khai báo ≡ liquid-glass) · `matte-paper` (bề mặt giấy mờ đặc sắc nét)
 
 Đặt các trục trên phần tử chứa cho những thành phần sử dụng phạm vi này. Mức hỗ trợ của từng mẫu được khai báo trong `docs/reference-catalog.json` (số lượng công bố); tài liệu in tĩnh, UI kit và tài liệu có ngôn ngữ cố định có ranh giới được ghi rõ. Đổi ngôn ngữ cũng cần nội dung đã dịch và trình dựng chọn nội dung đó:
 
@@ -33,4 +33,4 @@ Mặc định của Storybook: `light · tho · vi · liquid-glass`.
 - Không đổi màu trạng thái ngữ nghĩa hoặc quầng focus Ochre theo nguyên tố
 - Không trộn hai màu nhấn nguyên tố làm chính + phụ (chỉ dùng lớp chuyển màu theo Tương sinh)
 - Không viết giao diện thành phần cố định một ngôn ngữ
-- Không tạo bộ Style thứ hai khi chưa theo checklist Expansion Rule
+- Không tạo bộ Style chưa qua rà soát khi chưa theo checklist Expansion Rule

package/docs/vi/quality-gates.md

@@ -49,7 +49,7 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | Template language parity | `_audit/template-lang-parity.html` | Quét source tĩnh cả 85 `.dc.html`: en/vi hole-map key set giống và không rỗng (21 map template); nhánh `sc-if` `isEN`/`isVN` cặp (24 branch template); mọi template có language-tweak có cơ chế bilingual; lexicon EN-leak (Unsubscribe · View in browser · Preferences · All rights reserved · Manage subscription · Sent with) không bao giờ xuất hiện ngoài guard `isEN` / map `en`. Instrument VN-first stacked (38 `vn-*` + 3 `doc-*`) miễn leak theo thiết kế — cả hai ngôn ngữ luôn render | 0 key drift, 0 nhánh không cặp, 0 leak (`__langparity`) | Hard | Fast board CI |
 | APCA dark packs | `_audit/apca-dark-preview.html` | Cả 15 pack element×variant giữ mục tiêu APCA ở dark (bright-as-text ≥ 75, accent UI ≥ 60, ink-on-accent ≥ 75, ink-on-tint ≥ 75) | 0 fail hiện tại (`__apcaPreview.currentFail === 0`) | Hard | Fast board CI |
 | Element geometry | `_audit/element-geometry.html` | Sync cường độ soft/middle/deep giữa năm element; tách variant; khóa hue light↔dark; Thổ middle ghim ochre logo; pack generate từ seed | `__elementgeometry.pass` | Hard | Fast board CI |
-| Style contract | `_audit/style-contract.html` | Allowlist trục Style: sole pack `liquid-glass` (vắng ≡ mặc định); `styles.css` import `tokens/styles.css`; `--cs-style-pack` resolve; không `data-cs-style` lạ | `__stylecontract.pass` | Hard | Fast board CI |
+| Style contract | `_audit/style-contract.html` | Allowlist trục Style: `liquid-glass` (mặc định; vắng ≡ mặc định) và `matte-paper`; `styles.css` import `tokens/styles.css`; `--cs-style-pack` resolve cho cả hai; không `data-cs-style` lạ | `__stylecontract.pass` | Hard | Fast board CI |
 | Visual baselines | `_audit/visual-diff.html` | Baseline template tồn tại và load được để so sánh side-by-side / overlay | Baseline có; drift đánh giá bằng mắt (`__visualdiff`) | Advisory | Fast board CI |
 | Component baselines | `_audit/component-visual-diff.html` | 12 crop component curated neo các tầng atomic cho so sánh visual | Crop render + baseline có (`__componentVisualDiff`) | Advisory | Fast board CI |
 | Component state paint | `_audit/component-state-paint.html` | Nút primary, secondary, ghost và danger, dialog mở, menu mở, lỗi field và dòng data được chọn sơn đúng màu light và dark đã khai báo. Sai lệch kênh dùng `PIXEL_CHANNEL_TOLERANCE` của hợp đồng pixel. 15 PNG trang Linux vẫn là bộ pixel-diff. | `__statepaint.pass` | Hard | Fast board CI + unit test ba engine |
@@ -160,3 +160,5 @@ Kiểm tra packed-assets phân tích mọi file JS/CJS/MJS/JSX trong gói để
 Script inline trong HTML của gói cũng được quét khi không có type hoặc type là `module`, `text/javascript`, `application/javascript`, `text/ecmascript`, `application/ecmascript`, `text/babel`, `text/jsx`. Data block và type khác được loại trừ. Đường dẫn module inline được resolve theo file HTML. Fixture thiếu import và sai cú pháp phải thất bại; JSON không được parse như JavaScript. Kiểm tra này chỉ phân tích cú pháp dependency, không chạy chương trình inline hay xác nhận mọi tài nguyên runtime.
 
 `npm run test:font-rendering` dùng dữ liệu font thực sự render của Chromium để phát hiện system fallback cho tập ký tự tiếng Việt đã định nghĩa ở dạng NFC và NFD. Kiểm tra nằm trong `test:unit`. Bản sửa font subset của D82 vượt kiểm tra tập ký tự NFC/NFD đã định nghĩa trên cả stylesheet nguồn và bản gộp, không dùng system fallback trong fixture Chromium. Kết quả này chưa xác nhận mọi ký tự Unicode, nền tảng native hay nghiệm thu hình ảnh của người phụ trách. Cmap tĩnh và `document.fonts.ready` chưa đủ chứng minh render đúng; không tự chuẩn hóa dữ liệu người dùng để vượt gate.
+
+`npm run test:audit-regression` (`node _audit/ci/verify-audit-benchmarks-browser.mjs`) chạy Chromium headless qua `_audit/ci/fixtures/benchmark-20d.html`, `_audit/ci/fixtures/benchmark-baseline.html` và `_audit/ci/fixtures/benchmark-gen2.html` bằng tập assertion dùng chung trong `_audit/ci/lib/benchmark-checks.mjs`. Cổng này khẳng định **129/129** phép kiểm tra trên 20 chiều (`D1`–`D20`) đạt **10.0 / 10**, **64/64** phép kiểm tra cơ sở đạt **10.0 / 10**, **192/192** ô (`≥ 3.0:1`) trong ma trận tương phản phi văn bản 32×6, và **3/3** màn hình sản phẩm chịu tải Generation-2 với **0 watch**. Để mở rộng bộ benchmark sau các đợt review nội bộ hoặc đánh giá AI bên ngoài (Google Stitch / Claude Design), hãy thêm assertion mới vào `_audit/ci/lib/benchmark-checks.mjs` và dọn sạch các tệp tạm thời sau khi kiểm chứng.

package/docs/vi/release-notes.md

@@ -1,6 +1,6 @@
 # Ghi chú phát hành
 
-Điểm nổi bật sản phẩm cho operator — **không** phải git log và **không** phải `CHANGELOG.md`. Hệ thống thiết kế không maintain file changelog. VERSION của checkout nguồn **<!-- cs-source-version:checkout -->2.8.0<!-- /cs-source-version -->** là phiên bản trong repository. Trang này cung cấp nội dung Storybook **Release Notes**; sửa cục bộ chưa xác nhận nội dung đang triển khai tại `design.cyberskill.world`.
+Điểm nổi bật sản phẩm cho operator — **không** phải git log và **không** phải `CHANGELOG.md`. Hệ thống thiết kế không maintain file changelog. VERSION của checkout nguồn **<!-- cs-source-version:checkout -->2.9.0<!-- /cs-source-version -->** là phiên bản trong repository. Trang này cung cấp nội dung Storybook **Release Notes**; sửa cục bộ chưa xác nhận nội dung đang triển khai tại `design.cyberskill.world`.
 
 ## Bản sửa đổi chưa phát hành — đã triển khai cục bộ, chờ nghiệm thu
 
@@ -18,6 +18,10 @@ Các thay đổi này thuộc working tree đang sửa đổi. Đây chưa phả
 
 - AlertDialog cho thao tác phá hủy đặt focus ban đầu vào Hủy; hộp xác nhận thông thường đặt focus vào Xác nhận. Thứ tự ưu tiên `tone`/`variant`, callback, đóng bằng Escape và trả focus được giữ lại. Chính sách đã được operator phê duyệt vẫn cần bằng chứng kiểm tra hiện tại trên trình duyệt và công nghệ hỗ trợ.
 - Các control chọn dạng popup tùy chỉnh (`Combobox`, `DatePicker`, `TimePicker`, `ColorPicker`, `Cascader` và `TreeSelect`) hỗ trợ `"aria-labelledby"` trên cả nút mở và vùng popup để liên kết trực tiếp với nhãn trường bên ngoài mà không lặp chuỗi `aria-label`.
+- Khắc phục hài hòa thị giác và độ tương phản trước `2.9.0` trên nền tảng token, component, biểu mẫu, thẻ hướng dẫn, UI kit và bộ xuất tài liệu:
+  - **Phân cấp trung tính ấm & Ngũ Hành (`tokens/colors.css`, `tokens/elevation.css`, `tokens/elements.css`, `scripts/generate-element-packs.mjs`, `scripts/lib/theme-resolver.mjs`):** Hiệu chỉnh `--cs-color-text-muted` ở Light Mode sang `#5E4436` (`APCA Lc 84.3` trên `#FFFDF8`) tách bạch rõ với chữ chính Umber `#45210E` (`Lc 100.3`), đưa `--cs-accent-strong` hành Thổ ở Light Mode (`#A4631E` studio/sand, `#7D480C` clay) về sắc độ hổ phách ấm `62°`, đồng bộ bóng đổ `md`/`xl` về sắc Umber `#45210E`, đồng thời nâng màu chữ phụ của `CodeBlock` (`--cs-code-muted`), `Terminal` (`--cs-term-muted`) và hằng số mẫu native lên `#E9D6C2` (`APCA Lc >= 81.2`) kèm `color-scheme: dark`.
+  - **Tách bạch gói phong cách, viền form picker, khoảng hở chạm & tương phản điều hướng (`base/glass.css`, `base/forms.css`, `base/controls.css`, `base/navigation.css`, `base/ai.css`, `base/data.css`, `tokens/viewer.html`, `ui_kits/`):** Tắt hoàn toàn độ mờ `backdrop-filter` và áp dụng nền giấy phẳng dưới `[data-cs-style="matte-paper"]` trên các lớp `.cs-glass-*` cùng thanh điều hướng/khung soạn thảo UI kit, đồng bộ viền nghỉ của `Select`, `NativeSelect`, `DatePicker`, `TimePicker`, `ColorPicker`, `Cascader`, `TreeSelect` và `PromptInput` về `--cs-component-textfield-border-default` (`2.33:1` ở Light Mode), nâng dấu phân cách `/` của `Breadcrumb` (`.cs-breadcrumb__sep`) lên `--cs-color-text-muted` (`APCA Lc >= 77` ở cả Light và Dark), và bổ sung khoảng đệm cuối `20px` cho `#tablePanel` trong `tokens/viewer.html` để các nút sao chép `44px` không bị thanh cuộn ngang che khuất trên khung nhìn hẹp.
+  - **Thẻ hướng dẫn/specimen Dark Mode, email CTA/VML & ngắt dòng `<br>` trong DOCX (`guidelines/*.html`, `components/data/data.card.html`, `templates/email/Email-VN-standalone.html`, `templates/email-safe/email-*.html`, `templates/_vendor/doc-export.js`):** Thay các mã hex trắng/Umber cố định, chữ vàng Ochre dưới ngưỡng ở Dark Mode và nền `--cs-accent-tint` gốc trung tính trong thẻ hướng dẫn/component sang token thích ứng chủ đề, đồng bộ nút CTA của `Email-VN-standalone.html` (`--cs-accent-strong` / `--cs-accent-on-strong`) cùng màu chữ `.muted` của `7` mẫu VML `email-safe` ở Light (`#5E4436`) và Dark (`#E9D6C2`) vượt ngưỡng `APCA Lc >= 75`, và tuần tự hóa thẻ `<br>` thành `<w:r><w:br/></w:r>` chuẩn OpenXML khi xuất DOCX. Kiểm tra tự động và ảnh chuẩn Linux `909×540` không thay thế nghiệm thu thị giác của con người hoặc kiểm tra công nghệ hỗ trợ thủ công.
 
 ### Trước khi áp dụng bản sửa đổi
 
@@ -28,11 +32,23 @@ Các thay đổi này thuộc working tree đang sửa đổi. Đây chưa phả
 
 Release vẫn chờ nghiệm thu thị giác của con người, kiểm tra native/công nghệ hỗ trợ thủ công bắt buộc, quyết định về nguồn gốc tài nguyên và nghiệm thu hiện vật pilot đã thay đổi. Bằng chứng hỗ trợ đã thay đổi phải được review lại trong `components/lifecycle.json`. EN/VI là phạm vi ngôn ngữ mục tiêu; tiếng Nhật vẫn là spike chưa đầy đủ. Ghi chú này không cho phép mở rộng cam kết hỗ trợ, deprecate hay loại bỏ API.
 
+## Release — `@cyberskill/design@2.8.0`
+
+Phiên bản minor ổn định đã công bố được ghi nhận trong `_audit/ci/fixtures/npm-published-release.json` (quan sát lúc `2026-11-10T13:04:18.764Z`, tag `v2.8.0` tại commit `5e7fdc7fc0ca49844d476a101205c8893591cae2`).
+
+- **Mẫu giao diện Benchmark AI Gen-2 & Bí danh Token phòng thủ (`tokens/variables.css`, `tokens/theme-dark.css`, `base/glass.css`, `base/shell.css`, `base/layout.css`, `base/controls.css`, `base/components.css`, `base/data.css`, `base/ai.css`, `DESIGN.md`):** Bổ sung các biến bí danh chống suy đoán tên token (`--cs-glass-card-bg`, `--cs-glass-card-border`, `--cs-color-bg-elevated`, `--cs-color-bg-glass`, `--cs-shadow-glow`), tự động thu gọn `.cs-sidebar` trên mobile và tự giãn chiều rộng `.cs-theme-toggle` dạng viên thuốc, cùng các lớp `.cs-app-shell--topnav`, `.cs-grid-kpi`, `.cs-canvas`, `.cs-SplitPane`, `.cs-code-editor`, `.cs-checklist`, `.cs-file-dropzone`, `.cs-photo-grid`, `.cs-signature-pad`, `.cs-bottom-bar`, `.cs-sync-banner`, `.cs-table-toolbar` và `.cs-status-dot--live`.
+- **Bộ Benchmark trình duyệt trực tiếp 20 chiều & Dọn dẹp hồ sơ kiểm toán (`_audit/ci/verify-audit-benchmarks-browser.mjs`, `_audit/ci/lib/benchmark-checks.mjs`, `_audit/ci/fixtures/benchmark-20d.html`, `_audit/ci/fixtures/benchmark-gen2.html`):** Mở rộng bộ kiểm toán trình duyệt tự động lên **20 chiều (`129/129` phép kiểm tra đạt `10.0 / 10`, `0 watch` + `64/64` phép kiểm tra cơ sở = `193/193` khẳng định trình duyệt trực tiếp)** kèm 3 màn hình stress-test phức tạp thế hệ 2, đồng thời loại bỏ hoàn toàn các bản chụp lịch sử trong `audit/` và `_audit/remediation/`.
+- **Đường ống triển khai trực tiếp lên GitHub Pages (`.github/workflows/pages.yml`, `scripts/vercel-static-output.mjs`, `docs/vi/deploy.md`):** Đóng gói `.nojekyll` và `CNAME` (`design.cyberskill.world`) vào `.vercel-static/` và tự động triển khai webroot tĩnh lên GitHub Pages qua `actions/upload-pages-artifact` và `actions/deploy-pages`.
+
+```bash
+npm install @cyberskill/design@2.8.0
+```
+
 ## Release — `@cyberskill/design@2.7.0`
 
 Phiên bản minor ổn định đã công bố được ghi nhận trong `_audit/ci/fixtures/npm-published-release.json` (quan sát lúc `2026-11-09T20:01:08.112Z`, tag `v2.7.0` tại commit `d951d7d74077913d5d957f75c9d50d873b9dd937`).
 
-- **Bộ Benchmark trình duyệt trực tiếp 20 chiều (`_audit/ci/verify-audit-benchmarks-browser.mjs`, `_audit/ci/lib/benchmark-checks.mjs`, `_audit/ci/fixtures/benchmark-20d.html`, `_audit/ci/fixtures/benchmark-gen2.html`):** Mở rộng bộ kiểm toán trình duyệt tự động lên **20 chiều (`129/129` phép kiểm tra đạt `10.0 / 10`, `0 watch` + `64/64` phép kiểm tra cơ sở = `193/193` khẳng định trình duyệt trực tiếp)** với `D11` (tương phản văn bản thân bài APCA $L_c \ge 75$ & nhịp điệu chữ), `D12` (thang cao độ z-index 7 tầng `--cs-depth-*` & cô lập cuộn lớp phủ), `D13` (container query đáp ứng, vùng an toàn & bố cục lại bảng), `D14` (thuộc tính logic RTL, trạng thái vô hiệu/chỉ đọc & tắt nhấp nháy khung xương khi giảm chuyển động), `D15` (`@media print`, `@media (forced-colors: active)` WHCM & bất biến thương hiệu), `D16` (tính trực giao 5 trục `Theme × Element × Density × Contrast × Style` & vật lý cao độ bề mặt), `D17` (đồng bộ bàn phím & bộ gõ tiếng Việt IME trên 3 trình duyệt), `D18` (tính tất định máy trạng thái 20 họ component), `D19` (hình học xuất bản tài liệu/mẫu & bảo toàn độ rộng cột bảng) và `D20` (đóng gói production, toàn vẹn SHA-256 & không lỗi console).
+- **Bộ Benchmark trình duyệt trực tiếp 16 chiều (`_audit/ci/verify-audit-benchmarks-browser.mjs`, `_audit/ci/lib/benchmark-checks.mjs`, `_audit/ci/fixtures/benchmark-20d.html`, `_audit/ci/fixtures/benchmark-gen2.html`):** Mở rộng bộ kiểm toán trình duyệt tự động lên **16 chiều (`105/105` phép kiểm tra đạt `10.0 / 10`, `0 watch` + `64/64` phép kiểm tra cơ sở = `169/169` khẳng định trình duyệt trực tiếp)** với `D11` (tương phản văn bản thân bài APCA $L_c \ge 75$ & nhịp điệu chữ), `D12` (thang cao độ z-index 7 tầng `--cs-depth-*` & cô lập cuộn lớp phủ), `D13` (container query đáp ứng, vùng an toàn & bố cục lại bảng), `D14` (thuộc tính logic RTL, trạng thái vô hiệu/chỉ đọc & tắt nhấp nháy khung xương khi giảm chuyển động), `D15` (`@media print`, `@media (forced-colors: active)` WHCM & bất biến thương hiệu) và `D16` (tính trực giao 5 trục `Theme × Element × Density × Contrast × Style` & vật lý cao độ bề mặt).
 - **Bộ kiểm thử trả focus & bảo vệ bộ gõ tiếng Việt IME trên 3 engine (`components/forms/TreeSelect.jsx`, `components/forms/Cascader.jsx`, `components/forms/ColorPicker.jsx`, `components/forms/SearchField.jsx`, `_audit/ci/test-picker-focus-ime-browser.mjs`):** Đảm bảo trả focus về nút kích hoạt trên Chromium, Firefox và WebKit khi đóng `DatePicker`, `TreeSelect`, `Cascader`, `ColorPicker` hoặc xóa nhanh `SearchField`, đồng thời xác minh chốt chặn phím Enter khi đang gõ tổ hợp dấu tiếng Việt (`isComposing`) trên `Combobox`, `TagInput`, `Mentions`, `PromptInput` và `SearchField`.
 - **Kiểm kê máy trạng thái & Xác thực nhanh `fast-gates` qua `act` (`scripts/generate-state-inventory.mjs`, `_audit/state-machines.*`, `scripts/run-act-ci.mjs`, `scripts/verify-ci-checks.mjs`, `.github/workflows/design-system-gates.yml`):** Bổ sung bộ kiểm kê máy trạng thái từ mã nguồn cùng kiểm thử chuyển tiếp `InlineEdit` trên 3 trình duyệt và mở rộng biên nhận `act` gắn với commit/tree sang `ci/act/fast-gates`.