@cyberskill/design 2.2.0 → 2.3.1

package/docs/template-inventory.json

@@ -16641,7 +16641,7 @@
         },
         {
           "path": "ui_kits/website/site.css",
-          "sha256": "9bbb53ab56fb1b740c0d812a8970fcd94482bd46420d6f43dcf297e906b3a2f6"
+          "sha256": "e6f142d768535b0116d33c58a1c99ce31c2e4075363456a76a062f0635de6fa1"
         },
         {
           "path": "ui_kits/website/work.html",

package/docs/vi/component-scenarios.md

@@ -2,7 +2,7 @@
 
 `components/scenarios.json` là danh mục kiểm tra trạng thái có gắn nguồn. Danh mục lấy thành viên từ API công khai, dùng fixture tham chiếu HTML đã viết và suy ra miền hữu hạn từ declaration. `scripts/fixtures/component-scenarios.json` chứa kỳ vọng runtime cùng hash JSX/declaration làm bằng chứng. Thay đổi component không tự cập nhật bằng chứng này.
 
-Phạm vi gồm fixture mặc định cho mọi component công khai; mọi giá trị khai báo của `variant`, `size`, `tone`, `status`, `state`, `mode`; tích variant × size được hỗ trợ của Button; mọi prop `disabled`, `error`, `errors` đã khai báo; và tám hợp đồng collection rỗng được viết rõ. Miền hữu hạn hoặc prop disabled/error mới khiến bước sinh thất bại cho đến khi có kỳ vọng. Hành vi rỗng ngoài tám collection vẫn chưa phân loại, không tự được tính là đã xác minh hay không áp dụng.
+Phạm vi gồm fixture mặc định cho mọi component công khai; mọi giá trị khai báo của `variant`, `size`, `tone`, `status`, `state`, `mode`; tích variant × size được hỗ trợ của Button; mọi prop `disabled`, `error`, `errors` đã khai báo; và hai mươi hợp đồng collection rỗng được viết rõ. Miền hữu hạn hoặc prop disabled/error mới khiến bước sinh thất bại cho đến khi có kỳ vọng. Hành vi rỗng ngoài hai mươi collection vẫn chưa phân loại, không tự được tính là đã xác minh hay không áp dụng.
 
 Với component có miền hữu hạn, cảnh mặc định bỏ các prop đó và kiểm tra default đã review, gồm ProgressBar không có variant và fallback alias của AlertDialog. Các mặc định khác giữ trạng thái fixture tham chiếu đã tài liệu hóa. Kỳ vọng kiểm tra thay đổi class/trạng thái thực, kích thước SVG, disabled/focus native, alert lỗi và liên kết mô tả, hoặc collection không còn dữ liệu. Cascader và TreeSelect chỉ cam kết mở popup rỗng, không tự tạo yêu cầu về thông báo rỗng. FormField dùng composition TextField đã tài liệu hóa. Mỗi cảnh được mount riêng bằng tiếng Anh và tiếng Việt; cleanup phải xóa floating host cũ trước khi cảnh mới nhận host của mình.
 

package/docs/vi/consuming.md

@@ -1,6 +1,6 @@
 # Tiêu thụ & nâng cấp CyberSkill Design System
 
-**Checkout nguồn:** VERSION **<!-- cs-source-version:checkout -->2.2.0<!-- /cs-source-version -->** là định danh nguồn cục bộ, không xác nhận phiên bản có trên registry. Với bản ứng viên chưa công bố, kiểm chứng tarball gói cục bộ hoặc checkout nguồn đã rà soát. Lệnh registry và inventory sibling bên dưới chỉ bản ổn định 1.7.2 đã công bố, không tự đổi khi chuẩn bị bản phát hành. Chuẩn bị không cấp quyền công bố.
+**Checkout nguồn:** VERSION **<!-- cs-source-version:checkout -->2.3.1<!-- /cs-source-version -->** là định danh nguồn cục bộ, không xác nhận phiên bản có trên registry. Với bản ứng viên chưa công bố, kiểm chứng tarball gói cục bộ hoặc checkout nguồn đã rà soát. Lệnh registry bên dưới chỉ bản ổn định 2.3.0 đã công bố (và inventory sibling ADOPT-001 ghi ngày tại 1.7.2), không tự đổi khi chuẩn bị bản phát hành. Chuẩn bị không cấp quyền công bố.
 
 Cách mọi project — do người hoặc agent điều khiển — áp dụng design system HTML-first này, và cách nhận update an toàn. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 

package/docs/vi/contrast-report.md

@@ -1,6 +1,6 @@
 # Báo cáo contrast — cặp elemental (APCA)
 
-Tạo · quét tại VERSION 2.2.0.
+Tạo · quét tại VERSION 2.3.1.
 
 Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 

package/docs/vi/conventions.md

@@ -79,7 +79,7 @@ phần tử HTML, không dùng trong URL, thuộc tính, CSS hay script.
 
 **Element variant mới** — ở trong envelope oklch của element; đặt 10 token hợp đồng `--cs-accent-*` (gồm `--cs-accent-on-strong` ≥4.5:1 và APCA75 cho nội dung thường trên `-strong`) cộng `--cs-color-text-accent`/`--cs-color-link` (APCA-check cả hai); aurora wash kế thừa từ element qua `.cs-aurora-wash` (chỉ override class rule nếu variant thật sự cần ảnh riêng); đối tác gradient (`grad-b`) phải theo Tương sinh.
 
-**Ship check** — theo gate kiểm chứng portable trong `docs/doctrine.md`, rồi chạy `_audit/docs-consistency.html` **và** `_audit/namespace-portability.html` (cả hai phải xanh). VERSION của checkout nguồn **<!-- cs-source-version:checkout -->2.2.0<!-- /cs-source-version -->**.
+**Ship check** — theo gate kiểm chứng portable trong `docs/doctrine.md`, rồi chạy `_audit/docs-consistency.html` **và** `_audit/namespace-portability.html` (cả hai phải xanh). VERSION của checkout nguồn **<!-- cs-source-version:checkout -->2.3.1<!-- /cs-source-version -->**.
 
 ## Decision log (owner duyệt)
 

package/docs/vi/decisions/component-specification-evidence.md

@@ -4,7 +4,7 @@
 
 Thẻ JSX, thuộc tính, phép trải, phím literal và biểu thức tham chiếu tham số giữ vị trí chính xác trong nguồn. Phép trải ghi đích/thứ tự ghi đè chưa xác minh; biểu thức là ứng viên slot, không phải slot được chấp nhận. Class hook giữ scope tệp hiện có. Định nghĩa prop chuẩn được tham chiếu thay vì sao chép thành hệ kiểu thứ hai. Khai báo native tồn tại vẫn không chứng minh có forwarding.
 
-`scripts/component-semantics-source.json` quản lý một dữ kiện đã rà soát có giới hạn trong từng nhóm trong sáu nhóm ngữ nghĩa cho đủ 120 component, cùng 161 yêu cầu hành vi trên đủ 120 component. 39 export trước đây không có yêu cầu, mỗi export nay ánh xạ một ca cổng trợ năng có tên. Yêu cầu ánh xạ tới khẳng định có tên chính xác. Mọi prop do tác giả khai báo vẫn được liệt kê vì một dữ kiện nhóm không phải hợp đồng theo từng prop. Việc có constructor trong ca có tên chỉ là tham chiếu fixture, không bao giờ đủ chứng minh bao phủ. `completeBehaviorSpecifications` đếm export đã rà soát cấu trúc, slot và ví dụ và có khẳng định trên board hành vi. `completeAccessibilitySpecifications` đếm export đã rà soát vai trò, trạng thái và bàn phím và có khẳng định trên cổng trợ năng. Hai số này không phải ma trận prop đầy đủ hay nghiệm thu trợ năng thủ công.
+`scripts/component-semantics-source.json` quản lý một dữ kiện đã rà soát có giới hạn trong từng nhóm trong sáu nhóm ngữ nghĩa cho đủ 120 component, cùng 253 yêu cầu hành vi trên đủ 120 component. Mọi export nay đều ánh xạ ít nhất một ca board hành vi có tên và một ca cổng trợ năng có tên. Yêu cầu ánh xạ tới khẳng định có tên chính xác. Mọi prop do tác giả khai báo vẫn được liệt kê vì một dữ kiện nhóm không phải hợp đồng theo từng prop. Việc có constructor trong ca có tên chỉ là tham chiếu fixture, không bao giờ đủ chứng minh bao phủ. `completeBehaviorSpecifications` đếm export đã rà soát cấu trúc, slot và ví dụ và có khẳng định trên board hành vi. `completeAccessibilitySpecifications` đếm export đã rà soát vai trò, trạng thái và bàn phím và có khẳng định trên cổng trợ năng. Hai số này không phải ma trận prop đầy đủ hay nghiệm thu trợ năng thủ công.
 
 Ghi thực thi thật bằng `node scripts/capture-component-behavior-evidence.mjs .`, rồi `node scripts/verify-component-behavior-evidence.mjs .`. Capture chạy mọi ca hành vi và board trợ năng có tên trong Chromium, Firefox, WebKit, cộng hồi quy field-association ba engine hiện có. Verifier yêu cầu khớp chính xác nguồn, bundle, CSS, kiểm thử, vị trí assertion, tập ca và tập engine. Nó từ chối producer cũ, ca lỗi/thiếu và engine trùng. Đầu ra đạt chỉ xác minh các yêu cầu được ánh xạ trên đúng producer đã ghi. Không thay thế gate board đầy đủ, trợ năng thủ công hay nghiệm thu release.
 

package/docs/vi/entrypoints/DESIGN.md

@@ -1,6 +1,6 @@
 ---
 name: "CyberSkill Design System"
-version: "2.2.0"
+version: "2.3.1"
 generated: "2026-07-23"
 generator: "scripts/generate-design-md.mjs (npm run build:design-md)"
 sources:
@@ -27,6 +27,10 @@ gate: "_audit/design-md-parity.html (window.__designmd)"
 - **Ngưỡng khả năng tiếp cận:** APCA Lc ≥ 75 cho văn bản nội dung · vùng chạm ≥ 44px · không loại bỏ vòng focus · tôn trọng `prefers-reduced-motion` / `prefers-contrast`.
 - **Giọng điệu:** ấm áp · trực tiếp · trung thực · tôn trọng — luôn đủ cả bốn, không theo kiểu “vui nhộn/tinh nghịch/gây sốc”.
 
+### Chủ đề thị giác, bầu không khí và nhịp bề mặt
+
+CyberSkill kết hợp tay nghề kiến trúc ấm áp với độ chính xác quang học: trang mở đầu trên nền Warm Alabaster `--cs-color-surface-page` (`#FFFDF8` sáng / `#1a1108` tối), nâng nội dung lên `--cs-color-surface-panel` (`.cs-card`) hoặc `--cs-color-surface-raised` ấm (`.cs-card--raised`), làm nổi bật gói tiêu điểm bằng `.cs-card--featured` (viền `--cs-accent-strong` / `--cs-accent`), và xếp lớp bốn cấp kính quang học Liquid Glass (`.cs-surface-whisper`, `.cs-surface-light`, `.cs-surface-standard`, `.cs-surface-heavy`) cùng nền hero `.cs-aurora`.
+
 ## Màu sắc
 
 Màu ngữ nghĩa cốt lõi. Giá trị tối là phần ghi đè `[data-theme="dark"]` (chủ đề `system` áp dụng cùng giá trị khi có `prefers-color-scheme: dark`).
@@ -59,6 +63,12 @@ Màu ngữ nghĩa cốt lõi. Giá trị tối là phần ghi đè `[data-theme=
 | `--cs-color-semantic-warning-text` | `#441801` | `#FFD887` |
 | `--cs-color-semantic-info-text` | `#000A75` | `#C7DFFF` |
 
+### Vai trò chức năng của màu sắc
+
+- **Thương hiệu và tác vụ chính:** `--cs-color-brand-umber` (`#45210E`) và `--cs-color-brand-ochre` (`#F4BA17`) định hình nhận diện; `--cs-component-button-primary-bg` và `--cs-component-button-primary-fg` điều khiển nút kêu gọi hành động chính trên cả nền sáng và `[data-theme="dark"]`.
+- **Phân cấp bề mặt và đường viền:** luân phiên `--cs-color-surface-page`, `--cs-color-surface-panel`, và `--cs-color-surface-raised` để tạo nhịp phân đoạn; đóng khung bằng `--cs-color-border-default`, kẻ hàng bảng/danh sách nội bộ bằng `var(--cs-color-border-subtle)`, và phủ nền mờ hộp thoại/ngăn trượt/hướng dẫn bằng `var(--cs-color-surface-scrim)`.
+- **Văn bản và cặp trạng thái ngữ nghĩa:** dùng `--cs-color-text-primary`, `--cs-color-text-muted`, và `--cs-color-text-accent` cho phân cấp chữ (ngưỡng nội dung `APCA Lc >= 75`); ghép nền trạng thái đặc (`--cs-color-semantic-success`, `--cs-color-semantic-danger`, `--cs-color-semantic-warning`, `--cs-color-semantic-info`) với token `*-fg` và bề mặt pha sắc nhẹ với token `*-text`.
+
 ### Vai trò màu nhấn (Ngũ Hành)
 
 Gói màu nhấn mặc định = Thổ (nguyên tố của studio). Toàn bộ 15 gói nguyên tố×biến thể và các gói tối suy ra theo APCA nằm trong `tokens/elements.css` và DTCG `$extensions["com.cyberskill"].overrides.elements` / `.elementsDark`.
@@ -152,6 +162,11 @@ Bí danh ngữ nghĩa trỏ vào thang chữ — thể hiện ý định thay v
 | `--cs-heading-weight` | `var(--cs-font-weight-bold)` | `700` |
 | `--cs-heading-tracking` | `var(--cs-letter-spacing-tight)` | `-0.01em` |
 
+### Hệ thống phân cấp kiểu chữ đầy đủ và phông chữ thay thế
+
+- **Phân cấp lớp tiện ích chữ (`base/typography.css`):** `.cs-display` (`--cs-text-display` `3.75rem`, độ đậm `800`, chiều cao dòng `1.15`, giãn chữ `-0.01em`) và lớp co giãn `.cs-display--fluid`; `.cs-h1` (`--cs-text-h1` `2.25rem`, độ đậm `800`, chiều cao dòng `1.35`) và `.cs-h1--fluid`; `.cs-h2` (`--cs-text-h2` `1.875rem`, độ đậm `700`); `.cs-h3` (`--cs-text-h3` `1.5rem`, độ đậm `700`); `.cs-h4` (`--cs-text-h4` `1.25rem`, độ đậm `600`); `.cs-body-lg` (`--cs-text-body-lg` `1.125rem`, chiều cao dòng `1.5`); `.cs-body` (`--cs-text-body` `1rem`, chiều cao dòng `1.5`); `.cs-secondary` (`--cs-text-secondary` `0.875rem`); `.cs-caption` (`--cs-text-caption` `0.75rem`); `.cs-eyebrow` (`--cs-text-eyebrow` `0.75rem`, độ đậm `700`, chữ hoa, giãn chữ `0.08em`); `.cs-mono` (`--cs-font-family-mono`), `.cs-tabular` (`tabular-nums`), và `.cs-prose` (`--cs-prose-measure` `45rem`).
+- **Phông chữ thay thế và an toàn dấu tiếng Việt:** khi tệp WOFF2 tự lưu trữ không khả dụng trong môi trường bên ngoài, `--cs-font-family-ui` (`Be Vietnam Pro`) rơi về `ui-sans-serif, system-ui, sans-serif` (hoặc `Inter`), `--cs-font-family-display` (`Space Grotesk`) rơi về `'Be Vietnam Pro', ui-sans-serif, system-ui, sans-serif`, và `--cs-font-family-mono` (`JetBrains Mono`) rơi về `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace`; luôn giữ `--cs-font-line-height-body` (`1.5`) và `--cs-font-line-height-heading` (`1.35`) để dấu tiếng Việt chồng tầng không bao giờ bị cắt.
+
 ## Khoảng cách và bán kính
 
 | Token | Giá trị |
@@ -269,6 +284,11 @@ Các giá trị ghi đè theo phạm vi (tách biệt với các hàng token cơ
 | `--cs-icon-md` | `20px` |
 | `--cs-icon-lg` | `24px` |
 
+### Triết lý khoảng trắng, thang bán kính bo góc và hình học đa phương tiện
+
+- **Khoảng trắng và nhịp phân đoạn:** tách các dải nội dung lớn bằng `--cs-space-16` (`64px`) đến `--cs-space-24` (`96px`), giữ đệm trong của thẻ ở `--cs-space-4` (`16px`) đến `--cs-space-6` (`24px`), và giới hạn độ rộng cột đọc dài bằng `.cs-prose` (`--cs-prose-measure` `45rem`).
+- **Thang bán kính bo góc và hình học đa phương tiện (`Shapes`):** `--cs-radius-sm` (`4px`) cho `.cs-kbd`, `.cs-code`, và nhãn nhỏ; `--cs-radius-md` (`8px`) cho `.cs-button`, `.cs-field__control`, `.cs-popover__panel`, và `.cs-menu__list`; `--cs-radius-lg` (`14px`) cho `.cs-card`, `.cs-dialog`, `.cs-cmdk`, và tấm kính `.cs-surface-*`; `--cs-radius-full` (`999px`) cho `.cs-badge`, `.cs-tag`, và `.cs-avatar` tròn; đóng khung hình ảnh bằng `.cs-card__media`, `AspectRatio` (`16:9`, `4:3`, `1:1`), `.cs-image__zoom`, và `.cs-aurora--photo`.
+
 ## Độ nổi
 
 Giá trị bóng là chuỗi CSS box-shadow nguyên gốc từ `$extensions["com.cyberskill"].css` (đối tượng DTCG có cấu trúc lưu cùng các lớp). Bảng có giá trị ghi đè cho chủ đề tối.
@@ -306,6 +326,11 @@ Giá trị bóng là chuỗi CSS box-shadow nguyên gốc từ `$extensions["com
 | `--cs-glass-heavy-saturate` | `180%` |
 | `--cs-glass-heavy-opacity` | `90%` |
 
+### Phân cấp độ nổi (Cấp 0–5) và chiều sâu trang trí
+
+- **Phân cấp bề mặt và bóng đổ sáu mức:** Cấp 0 (`--cs-depth-bg` `0`) nền phẳng `--cs-color-surface-page`; Cấp 1 (`--cs-depth-section` `5`) dải nền `--cs-color-surface-raised`, `.cs-card--flat`, và `.cs-card--raised`; Cấp 2 (`--cs-depth-card` `10`) thẻ `.cs-card` mặc định với `--cs-shadow-xs` / `--cs-shadow-sm` và `.cs-surface-whisper` / `.cs-surface-light`; Cấp 3 thẻ tương tác/tiêu điểm `.cs-card--interactive:hover` và `.cs-card--featured` với `--cs-shadow-md` cùng `.cs-surface-standard`; Cấp 4 (`--cs-depth-nav` `50`, `--cs-depth-dropdown` `60`, `--cs-depth-overlay` `80`) thanh đầu trang cố định, `.cs-popover__panel`, `.cs-menu__list`, và `.cs-surface-heavy` với `--cs-shadow-lg`; Cấp 5 (`--cs-depth-modal` `100`, `--cs-depth-toast` `200`) `.cs-dialog`, `.cs-drawer`, `.cs-cmdk`, và `.cs-toast` với `--cs-shadow-xl` trên lớp chắn `var(--cs-color-surface-scrim)`.
+- **Chiều sâu trang trí:** kết hợp bóng đổ đa lớp tông Umber ấm với viền sáng nội bộ `1px` (`--_cs-glass-border`) trên các tấm `.cs-surface-*` và dải chuyển sắc hướng tâm Ochre/Umber trên nền hero `.cs-aurora`; khi bật `prefers-reduced-transparency: reduce` hoặc `forced-colors: active`, bề mặt tự chuyển về nền đặc `.cs-surface-solid`.
+
 ## Chuyển động
 
 Chuyển động điềm tĩnh, có mục đích; lớp bảo vệ toàn cục `prefers-reduced-motion` giảm thời lượng animation/transition xuống 0.01ms và tắt cuộn mượt khi chạy; thành phần có thể tắt hoàn toàn animation — các giá trị xuất này là giá trị thực (80/120/200/320ms).
@@ -372,6 +397,48 @@ Quyết định thiết kế ở cấp thành phần (button · textfield). Giá
 | `--cs-component-textfield-padding-x` | `12px` | — |
 | `--cs-component-textfield-min-height` | `44px` | — |
 
+## Cấu trúc thành phần HTML tĩnh (.cs-*)
+
+Bên dùng HTML tĩnh và công cụ sinh mã không kèm runtime định kiểu trực tiếp cho phần tử HTML ngữ nghĩa bằng các lớp `.cs-*` từ `styles.css` (hoặc `styles.layered.css`). Quản lý trạng thái tương tác, điều hướng bàn phím, giữ focus trong lớp phủ và thông báo ARIA động cần thành phần React hoặc mã kịch bản do bên dùng cung cấp; xem `docs/static-html-reference.md` để đối chiếu DOM đã kết xuất.
+
+- **Tác vụ và nút bấm (`base/components.css`):** nút chính `.cs-button`, các biến thể `.cs-button--secondary`, `.cs-button--tertiary`, `.cs-button--ghost`, `.cs-button--danger`, `.cs-button--danger-ghost`; kích thước `.cs-button--xs` (`28px`, nâng lên `44px` khi `pointer: coarse`), `.cs-button--sm` (`36px`, nâng lên `44px` khi `pointer: coarse`), cỡ trung bình mặc định (`44px`), `.cs-button--lg` (`52px`), trải rộng toàn khung `.cs-button--full`; trạng thái `.is-disabled`, `.is-loading` kèm `.cs-button__spinner`.
+- **Điều khiển biểu mẫu và trường nhập (`base/components.css`, `base/forms.css`, `base/controls.css`):** khung trường `.cs-field` gồm `.cs-field__label`, `.cs-field__control`, `.cs-field__description`, `.cs-field__error` và trạng thái lỗi `.cs-field.is-invalid`; điều khiển lựa chọn `.cs-check`, `.cs-radio`, `.cs-switch` (`.cs-switch__track`); ô nhập phức hợp `.cs-select`, `.cs-native-select`, `.cs-search` (`.cs-search__clear`), `.cs-stepper`, `.cs-otp`, `.cs-slider`, `.cs-segmented`.
+- **Thẻ nội dung và bề mặt Liquid Glass (`base/data.css`, `base/glass.css`):** khung thẻ `.cs-card` (biến thể `.cs-card--flat`, `.cs-card--raised`, `.cs-card--featured`, `.cs-card--interactive`; vùng con `.cs-card__media`, `.cs-card__header`, `.cs-card__title`, `.cs-card__subtitle`, `.cs-card__body`, `.cs-card__footer`); các cấp vật liệu kính `.cs-surface-whisper`, `.cs-surface-light`, `.cs-surface-standard` (bí danh `.cs-glass-card`), `.cs-surface-heavy`, bề mặt đặc dự phòng `.cs-surface-solid` (bí danh `.cs-surface-matte`), và nền hero thương hiệu `.cs-aurora` (`.cs-aurora--photo`).
+- **Hiển thị dữ liệu và kiểu chữ (`base/components.css`, `base/data.css`, `base/typography.css`, `base/collections.css`):** khung bảng thích ứng `.cs-table-wrap` và `.cs-table` với ô số căn phải dạng bảng `.cs-table__cell--numeric` cùng đường kẻ hàng dịu `var(--cs-color-border-subtle)`; khối chỉ số `.cs-stat` (`.cs-stat__label`, `.cs-stat__value`, `.cs-stat__delta--up`, `.cs-stat__delta--down`, `.cs-stat__delta--flat`); nhãn trạng thái `.cs-badge` (`.cs-badge--solid`, `.cs-badge--ochre`, `.cs-badge--success`, `.cs-badge--warning`, `.cs-badge--danger`, `.cs-badge--info`, `.cs-badge__dot`) và thẻ xóa được `.cs-tag`; `.cs-avatar` (`.cs-avatar--sm`, `.cs-avatar--md`, `.cs-avatar--lg`, `.cs-avatar--square`, `.cs-avatar-group`); `.cs-kbd`, `.cs-code`, `.cs-dl`; các lớp vai trò chữ `.cs-display`, `.cs-display--fluid`, `.cs-h1`, `.cs-h1--fluid`, `.cs-h2`, `.cs-h3`, `.cs-h4`, `.cs-body-lg`, `.cs-body`, `.cs-secondary`, `.cs-caption`, `.cs-eyebrow`, `.cs-mono`, `.cs-tabular`, `.cs-prose`, và phạm vi chọn họ chữ tiêu đề `.cs-display-face`.
+- **Phản hồi và lớp phủ (`base/feedback.css`, `base/components.css`, `base/shell.css`):** thông báo nội tuyến `.cs-alert` (`.cs-alert--info`, `.cs-alert--success`, `.cs-alert--warning`, `.cs-alert--danger`, `.cs-alert__icon`, `.cs-alert__title`, `.cs-alert__body`, `.cs-alert__dismiss`); ngăn xếp `.cs-toast-stack` và `.cs-toast`; hộp thoại `.cs-dialog-layer` với nền mờ thích ứng chủ đề `.cs-dialog__overlay` (`var(--cs-color-surface-scrim)`), khung `.cs-dialog` (`.cs-dialog__header`, `.cs-dialog__title`, `.cs-dialog__body`, `.cs-dialog__actions`) và `.cs-alert-dialog` (`.cs-alert-dialog--destructive`); ngăn trượt `.cs-drawer-scrim` và `.cs-drawer` (`.cs-drawer--left`); `.cs-popover` (`.cs-popover__panel`), `.cs-tooltip` (`.cs-tooltip__bubble`), `.cs-progress` (`.cs-progress__fill`), `.cs-spinner`, `.cs-skeleton`.
+- **Điều hướng, khung ứng dụng và AI (`base/navigation.css`, `base/shell.css`, `base/ai.css`, `base/controls.css`):** thanh bên `.cs-sidebar` (`.cs-sidebar__label`, `.cs-nav-item`, `.cs-nav-item.is-active`), `.cs-tabs` (`.cs-tab`, `.cs-tab__count`), `.cs-breadcrumb`, `.cs-pagination`, `.cs-menu` (`.cs-menu__list`, `.cs-menu__item`, `.cs-menu__item--danger`, `.cs-menu__sep`), `.cs-steps` (`.cs-step`, `.cs-step--done`, `.cs-step--active`), bảng lệnh `.cs-cmdk-scrim` và `.cs-cmdk` (`.cs-cmdk__search`, `.cs-cmdk__list`, `.cs-cmdk__item`); bề mặt AI `.cs-prompt`, `.cs-chat-msg`, `.cs-ai-disclosure` (`.cs-ai-disclosure__badge`, `.cs-ai-disclosure__panel`), `.cs-review-gate`, và `.cs-terminal`.
+
+### Thành phần đặc trưng và các bề mặt mẫu chuẩn (ex-*)
+
+- **Bề mặt đặc trưng của CyberSkill:** (1) 4 cấp kính quang học Liquid Glass (`.cs-surface-whisper` đến `.cs-surface-heavy`), (2) nền hero hướng tâm Ochre/Umber `.cs-aurora`, (3) bộ ba AI đáng tin cậy (`AIDisclosureBadge` `.cs-ai-disclosure`, `ConfidenceMeter`, `HumanReviewGate` `.cs-review-gate`, `LumiAvatar` `.cs-lumi`), (4) 15 gói màu nhấn Ngũ Hành (`data-cs-element`), và (5) 85 mẫu tài liệu song ngữ `.dc.html`.
+- **Các bề mặt mẫu chuẩn đối chiếu (`ex-*`):** `ex-pricing-tier` → `.cs-card` gồm `.cs-card__header`, `.cs-stat__value.cs-tabular`, và `.cs-button--secondary`; `ex-pricing-tier-featured` → `.cs-card.cs-card--featured` kèm `.cs-badge--ochre` và nút chính `.cs-button`; `ex-product-selector` → `.cs-card.cs-card--raised` kèm `.cs-segmented` và `.cs-check`; `ex-cart-drawer` → `.cs-drawer-scrim` + `.cs-drawer` kèm danh sách khoản mục `.cs-dl` và `.cs-drawer__footer`; `ex-app-shell-row` → `.cs-sidebar` + `.cs-nav-item.is-active`; `ex-data-table-cell` → `.cs-table-wrap` + `.cs-table` + `.cs-table__cell--numeric`; `ex-auth-form-card` → `.cs-card` + `.cs-form` + `.cs-field` + `.cs-button--full`; `ex-modal-card` → `.cs-dialog-layer` + `.cs-dialog__overlay` + `.cs-dialog`; `ex-empty-state-card` → `.cs-card.cs-card--flat` + `EmptyState`; `ex-toast` → `.cs-toast-stack` + `.cs-toast`.
+
+## Bố cục, lưới và chiến lược đáp ứng
+
+Bố cục dựa trên nhịp không gian `4px` (`--cs-space-1` đến `--cs-space-24`) với giới hạn khung chứa (`--cs-container-sm` `640px` đến `--cs-container-2xl` `1440px`) và hai phạm vi mật độ (`data-cs-density="comfortable"` mặc định so với `data-cs-density="compact"`). Đánh dấu các vùng chia hoặc khung thay đổi kích thước bằng `.cs-cq` (`container-type: inline-size`) để thu gọn lưới con qua `.cs-cq-cols-2`, `.cs-cq-cols-3`, `.cs-cq-cols-4`, `.cs-cq-stack`, và `.cs-cq-hide-narrow` độc lập với độ rộng khung nhìn.
+
+- **Màn hình máy tính và rộng (`> 1024px`, `--cs-breakpoint-lg` / `--cs-breakpoint-xl` `1280px` / `--cs-breakpoint-2xl` `1536px`):** giữ nguyên lưới nhiều cột, thanh bên `.cs-sidebar` `248px` cố định + vùng làm việc chính `1fr`, đệm trang rộng (`40px+`), và cỡ chữ tiêu đề đầy đủ (`--cs-text-display` `3.75rem`, `--cs-text-h1` `2.25rem`). Bài trình chiếu 16:9 và khung mạng xã hội cố định trong `.cs-canvas-desk` giữ nguyên cột gốc và cuộn ngang khi nhỏ hơn `1280px` (`min-width: 960px`).
+- **Máy tính bảng (`<= 768px`, `--cs-breakpoint-md`):** lưới nội tuyến 3–6 cột thu gọn về `repeat(2, 1fr)`; `.cs-sidebar` chuyển từ cột cố định sang dải điều hướng ngang tự xuống dòng; `.cs-table-wrap` và `.cs-table-scroll` cuộn ngang; `.cs-display` giảm xuống `--cs-font-size-4xl` (`3rem`) và `.cs-h1` xuống `--cs-font-size-2xl` (`1.875rem`) bên ngoài `.cs-canvas-desk` (hoặc co giãn mượt khi dùng `.cs-display--fluid` / `.cs-h1--fluid`); `.cs-nav-item` và `.cs-search` áp dụng chiều cao chạm tối thiểu `44px`.
+- **Điện thoại và màn hình hẹp (`<= 640px` `--cs-breakpoint-sm`, `<= 480px` `--cs-breakpoint-xs`, ngưỡng dàn trang `<= 360px`):** mọi lưới nội dung nhiều cột thu về `1fr`; `.cs-dialog` mở rộng thành `calc(100vw - 1rem)` ở vị trí `4vh` (hỗ trợ vùng an toàn `4dvh`) với các nút tác vụ co giãn toàn hàng; `.cs-display` giảm xuống `--cs-font-size-3xl` (`2.25rem`) và `.cs-h1` xuống `--cs-font-size-xl` (`1.5rem`); tại `<= 360px` (WCAG 1.4.10), `.cs-tabs`, `.cs-pagination`, `.cs-otp`, và `.cs-dl` tự xuống dòng hoặc cuộn nội bộ mà không gây tràn ngang trang, đồng thời giữ vùng chạm `>= 44px`.
+
+## Nguyên tắc thực hành (Nên và Không nên)
+
+- **Nên (Thương hiệu và màu sắc):** neo giao diện vào Umber `#45210E` và Ochre `#F4BA17`; dùng `--cs-color-surface-page`, `--cs-color-surface-panel`, `--cs-color-surface-raised`, `--cs-color-border-default`, `var(--cs-color-border-subtle)`, và `var(--cs-color-surface-scrim)` để chế độ sáng, `[data-theme="dark"]`, `[data-theme="system"]`, `[data-cs-contrast="high"]`, và cả 15 gói nguyên tố Ngũ Hành tự động thích ứng.
+- **Không nên (Thương hiệu và màu sắc):** không đặt văn bản nội dung trên nền trung gian `--cs-accent` (hãy ghép `--cs-accent-strong` với `--cs-accent-on-strong`, hoặc dùng `--cs-accent-tint` / `--cs-accent-bright` với chữ tối), và không gán cứng viền `rgba(69, 33, 14, ...)` hay màn chắn `rgba(31, 19, 11, ...)` chỉ hợp nền sáng trong CSS thành phần.
+- **Nên (Kiểu chữ và bản địa hóa tiếng Việt):** giữ `--cs-font-line-height-body` (`1.5`) và `--cs-font-line-height-heading` (`1.35`) để dấu tiếng Việt chồng tầng (`ẫ`, `ệ`, `ự`, `ở`) không bị cắt; áp dụng `.cs-tabular` hoặc `.cs-table__cell--numeric` (`font-variant-numeric: tabular-nums`) cho chỉ số KPI, giá tiền, mốc thời gian, huy hiệu và số trang; cung cấp đủ cặp chuỗi EN và VI cho giao diện đã đăng ký.
+- **Không nên (Kiểu chữ và bản địa hóa tiếng Việt):** không ép chiều cao dòng văn bản xuống dưới `1.5` hoặc tiêu đề xuống dưới `1.35` đối với tiếng Việt, không lược bỏ dấu, và không đặt `--cs-font-family-display` (`Space Grotesk`) làm phông chữ nội dung mặc định (chỉ bật cho tiêu đề qua `.cs-display-face` hoặc `--cs-heading-family`).
+- **Nên (Khả năng tiếp cận và chuyển động):** giữ chỉ báo focus hai vòng (`outline: 2px solid var(--cs-color-text-primary)` + `box-shadow: 0 0 0 5px var(--cs-color-accent-ochre)`), duy trì `APCA Lc >= 75` cho văn bản nội dung, đảm bảo vùng chạm `>= 44px` khi `@media (pointer: coarse)`, và cung cấp bề mặt đặc dự phòng khi `prefers-reduced-transparency: reduce` hoặc `forced-colors: active`.
+- **Không nên (Khả năng tiếp cận và ranh giới runtime):** không xóa đường viền `:focus-visible` nếu phần tử cha không có vòng focus kết hợp `:focus-within`, không dùng màu sắc đơn lẻ để biểu đạt trạng thái (luôn kết hợp màu ngữ nghĩa với biểu tượng, nhãn chữ hoặc độ dày viền), và không coi HTML tĩnh `.cs-*` tự có sẵn điều hướng bàn phím, giữ focus hay cập nhật trạng thái ARIA như thành phần React.
+
+## Hướng dẫn prompt cho Agent và khung khởi tạo
+
+- **Thuộc tính gốc (`<html>`):** đặt `lang="vi"` (hoặc `lang="en"`), `data-theme="light"` (`"dark"` | `"system"`), tùy chọn `data-cs-element="tho"` (`"kim"` | `"moc"` | `"thuy"` | `"hoa"` | `"tho"`), tùy chọn `data-cs-density="comfortable"` (`"compact"`), và tùy chọn `data-cs-contrast="high"`.
+- **Chọn runtime:** nạp `styles.css` (hoặc `styles.layered.css`) cho HTML tĩnh `.cs-*`; nhập `@cyberskill/design` (`dist/esm/_esm/react.mjs`) cho React ESM đã biên dịch hoặc `@cyberskill/design/source` (`_esm/react.mjs`) cho JSX nguồn; chỉ dùng `templates/_vendor/support.js` khi xem trước tài liệu `.dc.html`.
+- **Danh sách kiểm tra khi viết prompt cho AI:** nêu rõ (1) runtime đích (`static-html` hay `react`), (2) chủ đề và nguyên tố Ngũ Hành (`data-theme`, `data-cs-element`), (3) cặp nội dung song ngữ (`vi` + `en` giữ nguyên dấu tiếng Việt), (4) khung chứa đáp ứng (`max-width: var(--cs-container-xl)` hoặc `.cs-cq`), và (5) căn chỉnh chữ số dạng bảng (`.cs-tabular` / `.cs-table__cell--numeric`) cho chỉ số và bảng.
+- **Tham chiếu nhanh màu sắc và token:** Màu thương hiệu chính Umber `#45210E` (`--cs-color-brand-umber`) · Màu nhấn Ochre `#F4BA17` (`--cs-color-brand-ochre`) · Nền trang `#FFFDF8` / tối `#1a1108` (`--cs-color-surface-page`) · Nền bảng `#FFFFFF` / tối `#221710` (`--cs-color-surface-panel`) · Nền nổi `#FBF4E9` / tối `#2b1e14` (`--cs-color-surface-raised`) · Viền mặc định `#E7D9C6` / tối `#4a3a2c` (`--cs-color-border-default`).
+- **Mẫu prompt dùng ngay:** (1) Dải Hero: phân đoạn `.cs-aurora` gồm `.cs-eyebrow`, `.cs-display--fluid`, đoạn dẫn `.cs-prose`, nút chính `.cs-button` + `.cs-button--secondary`; (2) Không gian làm việc SaaS: lưới `.cs-sidebar` + `main` với hàng 3 thẻ KPI `.cs-card` / `.cs-card--featured` (`.cs-stat__value.cs-tabular`) và `.cs-table-wrap` > `.cs-table` có `.cs-table__cell--numeric`; (3) Khung rà soát AI đáng tin cậy: `.cs-card.cs-surface-standard` kết hợp `.cs-chat-msg`, `.cs-ai-disclosure`, và `.cs-review-gate`.
+- **Hướng dẫn tinh chỉnh lặp và giới hạn phạm vi:** chỉnh sửa từng thành phần hoặc dải phân đoạn một bằng các thuộc tính `--cs-*` (không gán cứng mã hex); kiểm tra chế độ sáng, `[data-theme="dark"]`, dàn trang di động `360px`, và vùng chạm `pointer: coarse` `44px`; lưu ý HTML tĩnh `.cs-*` chỉ cung cấp định kiểu thị giác (điều hướng bàn phím, giữ focus và thông báo ARIA động cần thành phần React hoặc mã kịch bản của bên dùng, và tệp `.dc.html` cần `templates/_vendor/support.js`).
+
 ## Danh mục thành phần
 
 107 tệp thành phần · 125 mục xuất (từ `_ds_manifest.json`). Mỗi thành phần chính có `.jsx` + `.d.ts` + `.prompt.md`.