@cyberskill/design 1.0.0 → 1.1.0

package/docs/vi/ci-cd.md

@@ -12,15 +12,16 @@
 
 1. **`fast-gates`** — `npm ci` + Playwright Chromium cache, serve repo, mở `_audit/run.html` headless (`_audit/ci/run-gates.mjs`), fail khi hard-gate fail. Upload import-report khi fail. Hàng mới trên board (hardening Th7 2026 thêm 8: token-format-parity, version-stamp, support-runtime-identity, package-exports-integrity, template-lang-parity, dtcg-typing, design-md-parity, bundle-freshness) được nhận tự động — runner đọc `window.__run`, không phải danh sách gate phía job.
 2. **`token-provenance`** — kiểm Node không trình duyệt: natives + `provenance.json` khớp sha-256 nguồn DTCG.
-3. **`unit-tests`** — `npm run test:unit` (8 contract test Node thuần; nối vào CI bởi hardening Th7 2026 — trước đó chỉ local).
+3. **`unit-tests`** — `npm run test:unit` (11 contract test Node thuần; nối vào CI bởi hardening Th7 2026 — trước đó chỉ local). Gồm `test-element-packs` (freshness `node scripts/generate-element-packs.mjs --check`).
 4. **`node-prechecks`** — authority Node không trình duyệt: `_audit/ci/check-bundle-freshness.mjs` (nguồn chân lý bundle-freshness — khám phá source đầy đủ gồm file mới/xóa; hàng board chỉ re-hash file ghi trong header) và `scripts/generate-design-md.mjs --check` (`DESIGN.md` gốc byte-equals regeneration).
 5. **`docs-consistency-blocker`** — merge blocker `docs-consistency` + `bilingual-parity`.
 6. **`whole-set-audits`** — quyết định B của owner: mọi push/PR, cộng nightly `0 3 * * *` và `workflow_dispatch` (responsive + language + theme overflow, ~15–20 phút).
-7. **`figma-variables-push`** — trên push `main` + thủ công. Quyết định A (non-Enterprise): Variables REST soft-skip; secrets vẫn chứng minh mở file. Xem `docs/figma.md`.
-8. **`code-connect`** — trên PR + `main` + thủ công. Quyết định 1C: dry-run luôn (config + 99 mapping); publish soft-skip khi thiếu `FIGMA_TOKEN` / `FIGMA_FILE_KEY` hoặc API 403/404/429. Xem `docs/figma.md`.
-9. **`regenerate-tokens`** — path-filtered trên push/PR (`tokens.dtcg.json`, natives, generator, `VERSION`); luôn có trên schedule/manual. Output native deterministic; push với `contents: write` (hoặc `DS_PUSH_TOKEN`).
+7. **`figma-variables-push`** — trên push `main` + thủ công. **`FIGMA_TOKEN` / `FIGMA_FILE_KEY` trống → soft-skip** (exit 0 + report — cùng trung thực với Code Connect). Quyết định A (non-Enterprise): Variables REST cũng **soft-skip khi API 403** (và lỗi plan/scope liên quan) sau khi secret chứng minh mở file. Soft-skip ≠ sync Variables live. Xem `docs/figma.md`.
+8. **`code-connect`** — trên PR + `main` + thủ công. Quyết định 1C: dry-run luôn (config + 105 mapping); publish soft-skip khi thiếu `FIGMA_TOKEN` / `FIGMA_FILE_KEY` hoặc API 403/404/429. Xem `docs/figma.md`.
+9. **`regenerate-tokens`** (pull request) + **`regenerate-tokens-push`** (push `main` / schedule / thủ công) — path filter phủ element seeds/packs (`element-seeds.json`, `elements.css`, mirror JSON/JS/DTCG, `generate-element-packs.mjs`) cộng natives / `VERSION`. Regenerate chạy `npm run tokens:elements` rồi `node _audit/ci/generate-native-tokens.mjs`. Trên **pull request** job chạy với `contents: read`, không bao giờ push, và **exit 1** khi có drift: chạy cả hai ở local rồi commit. Chỉ job song sinh push/schedule/thủ công giữ `contents: write` và auto-commit với `DS_PUSH_TOKEN` (hoặc `github.token`).
+10. **`npm-hello-smoke`** — chứng minh consumer registry: `cd examples/npm-hello && npm ci && npm run smoke` (**hard fail**; package public). Path-filtered trên push/PR khi `examples/npm-hello/**`, bề mặt publish package, hoặc workflow này đổi; luôn chạy trên schedule / `workflow_dispatch`.
 
-Workflow riêng **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + tag `v*`; pack dry-run luôn; publish soft-skip khi thiếu `NPM_TOKEN`. Phiên bản giữ **1.0.0**; license **UNLICENSED**.
+Workflow riêng **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + tag `v*`; pack dry-run luôn; publish qua **npm Trusted Publishing (OIDC)** (`id-token: write`, không `NPM_TOKEN` trên bước publish). Soft-skip khi auth / 403 / 404 / EOTP / conflict phiên bản. Phiên bản là **1.1.0**; license **UNLICENSED**. Trusted Publisher trên npmjs phải khớp filename workflow `npm-publish.yml`. Publishing access package: **Require 2FA and disallow tokens** (OIDC vẫn chạy; token classic bị từ chối).
 
 Workflow riêng **`native-store`** (`.github/workflows/native-store.yml`): PR + `main` (path-filtered) + `workflow_dispatch`; dry-run scaffold luôn; kiểm signed-release soft-skip khi thiếu `ASC_KEY_ID` / `ASC_ISSUER_ID` / `ASC_KEY_P8` / `PLAY_SERVICE_ACCOUNT_JSON`. **Không bao giờ submit** lên App Store / Play — sample vẫn là sample. Xem `examples/native/README.md`.
 
@@ -39,7 +40,7 @@ Node **22** trên runner (tránh deprecation action Node 20). Cache key Playwrig
 
 ## Quyền auto-commit token
 
-Job yêu cầu `permissions: contents: write`. Nếu org khóa default token read-only, đặt repository secret `DS_PUSH_TOKEN` (fine-grained PAT, Contents read/write) hoặc mở write tại org Actions settings. Xem ghi chú trước trong git history / org settings.
+Chỉ `regenerate-tokens-push` yêu cầu `permissions: contents: write`; job song sinh cho pull request `regenerate-tokens` giữ `contents: read` và checkout không lưu credential, nên PR không bao giờ kích hoạt push của bot. Nếu org khóa default token read-only, đặt repository secret `DS_PUSH_TOKEN` (fine-grained PAT, Contents read/write) hoặc mở write tại org Actions settings. Xem ghi chú trước trong git history / org settings.
 
 ## Branch protection (khuyến nghị)
 
@@ -61,24 +62,29 @@ node _audit/ci/check-bundle-freshness.mjs
 node scripts/generate-design-md.mjs --check
 npm run test:unit
 node _audit/ci/run-single-gate.mjs http://127.0.0.1:8080/_audit/docs-consistency.html __docs
+npm run tokens:elements
+node scripts/generate-element-packs.mjs --check
 node _audit/ci/generate-native-tokens.mjs
 ```
 
 ## Những gì KHÔNG auto-fail (có chủ đích)
 
 - **Hàng visual / component baseline side-by-side** — chỉ advisory (drift đánh giá bằng mắt). So sánh `%` pixel Playwright là gate **hard** (job `pixel-diff` + hàng Pixel CI trên board).
-- **Figma Variables write trên non-Enterprise** — soft-skip kèm report artifact.
+- **Figma Variables** — soft-skip khi thiếu secret (cùng trung thực với Code Connect) hoặc write Variables gặp non-Enterprise / API **403**; report artifact ghi lại skip. Soft-skip ≠ sync live.
 - **Code Connect publish** — soft-skip khi thiếu secret hoặc API 403/404/429 (Quyết định 1C).
-- **npm publish** — soft-skip khi thiếu `NPM_TOKEN` (Quyết định 1C).
+- **npm publish** — Trusted Publishing (OIDC) trên `npm-publish.yml`; soft-skip khi auth / conflict (Quyết định 1C).
 - **Native store signed release** — soft-skip khi thiếu `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` (Quyết định 1C); submit store vẫn tắt.
+- **npm-hello registry smoke** — **hard fail** (`examples/npm-hello` → `npm ci` + `npm run smoke`); chứng minh đường install public `@cyberskill/design` (không soft-skip).
+
+Job `figma-variables-push` hay `code-connect` xanh — và do đó badge hay hàng Status xanh — chỉ có nghĩa job exit 0; nó **không** chứng minh sync Figma live, vì soft-skip và publish thật nhìn từ ngoài giống hệt nhau. Mở report artifact của run (`figma-push-report.json` / `code-connect-report.json`) để biết cái nào đã xảy ra.
 
 ## Soft-skip dry-run (local)
 
 ```bash
-npm run code-connect:dry-run          # config + ≥99 mapping; không secret
+npm run code-connect:dry-run          # config + ≥105 mapping; không secret
 node _audit/ci/code-connect-publish.mjs   # thiếu secret → SOFT SKIP missing_secrets
-npm run npm:pack-dry-run              # inventory tarball; không NPM_TOKEN
-node _audit/ci/npm-publish.mjs        # thiếu NPM_TOKEN → SOFT SKIP missing_secrets
+npm run npm:pack-dry-run              # inventory tarball; không auth
+node _audit/ci/npm-publish.mjs        # GHA OIDC; không thì SOFT SKIP (package disallow tokens)
 npm run native:store-dry-run          # scaffold Fastlane + metadata; không ASC_*/Play JSON
 node _audit/ci/native-store-dry-run.mjs   # thiếu secret → SOFT SKIP missing_secrets
 ```

package/docs/vi/consumer-grant.md

@@ -0,0 +1,37 @@
+# Grant consumer — `@cyberskill/design`
+
+**Trạng thái: có hiệu lực** (Th7 2026). Văn bản chính sách — không phải secret. License trên package vẫn **UNLICENSED**; grant này là lớp duyệt dùng trong các sản phẩm đã nêu.
+
+## Grant
+
+CyberSkill cấp cho **CyberSkill** (công ty và các team kỹ thuật sản phẩm dưới `cyberskill-official`) quyền **không độc quyền** cài và dùng **`@cyberskill/design`** trong các sản phẩm liệt kê ở registry đã khóa `docs/products.md`:
+
+| Sản phẩm |
+|---|
+| Lumi — trợ lý điều ước |
+| Status Hub — cổng portfolio khách hàng |
+| CyberOS Agent Spine — hạ tầng agent, memory, gates |
+| CyberSkill Design System — thư viện này |
+| cyberskill.world — site studio |
+| Client delivery suite — kickoff · QBR · runbooks |
+| Board / investor collateral |
+| HR / employment instruments |
+
+Package vẫn **UNLICENSED**. Cài từ npm registry **không** tự cấp quyền redistribution. Redistribution ngoài các sản phẩm trên — gồm publish fork, đổi license, hoặc ship package như dependency của sản phẩm bên thứ ba không liên quan — cần **grant viết thêm** ghi trong file này (hoặc văn bản thay thế).
+
+## Ghi chú phạm vi
+
+- **Clone / subtree / link tĩnh** repo này cho cùng các sản phẩm trên được cover giống npm install.
+- **Tooling chỉ-host** (Storybook, `_audit/`) không nằm trong tarball npm và không redistribution theo grant này.
+- Thêm sản phẩm CyberSkill mới: cập nhật `docs/products.md` (+ VI) qua quyết định maintainer, rồi thêm hàng sản phẩm tại đây trong cùng change.
+- Duyệt **team/client bên ngoài**: thêm stanza grant có ngày bên dưới (team/org, sản phẩm đã nêu, liên hệ). Không invent ánh xạ product → element tại đây — giữ ở `docs/products.md`.
+
+## Grantee bổ sung
+
+*(Chưa có. Thêm entry có ngày tại đây.)*
+
+## Liên quan
+
+- Adopt / cài: `docs/consuming.md`
+- Biên bản quyết định: `docs/decisions.md` §7
+- Registry product → element: `docs/products.md`

package/docs/vi/consuming.md

@@ -8,18 +8,18 @@ Cách mọi project — do người hoặc agent điều khiển — áp dụng
 
 | Consumer | Bắt đầu tại | Hoạt động hôm nay | Không làm |
 |---|---|---|---|
-| **Claude Code** | `SKILL.md` → `README.md` → `styles.css` + `_esm/cs.mjs` / `_ds_bundle.js` (resolve theo prefix) | Mạnh — rules, components, prompts; gates qua full clone | Hardcode hậu tố bundle; coi Storybook host là hợp đồng portable |
+| **Claude Code** | `SKILL.md` → `README.md` → `styles.css` + bundler `@cyberskill/design` / legacy `_esm/cs.mjs` / `_ds_bundle.js` (resolve theo prefix) | Mạnh — rules, components, prompts; gates qua full clone | Hardcode hậu tố bundle; coi Storybook host là hợp đồng portable; import `_esm/cs.mjs` hoặc `@cyberskill/design/legacy` vào bundler Next/SSR |
 | **Google Stitch** | `DESIGN.md` → `llms.txt` → `tokens/tokens.dtcg.json` | Mạnh cho doctrine + tokens + HTML tĩnh `.cs-*` | Coi `templates/**/*.dc.html` là SoT — không có tweaks / `__dcSetProps` / DC compiler |
 | **Claude Design** | Full repo + DC compiler | Full fidelity (tweaks, `x-import`, template bilingual) | Bỏ qua vòng sync trong `docs/sync.md` |
-| **npm** | `@cyberskill/design` | Hình dạng package đã gate; dry-run luôn | Giả định cài public đã duyệt — cần grant owner + `NPM_TOKEN` (soft-skip cho đến khi đó) |
+| **npm** | `@cyberskill/design` | **1.1.0** trên registry; CI Trusted Publishing; grant tại `docs/consumer-grant.md` | Coi cài từ registry như license công khai (vẫn UNLICENSED) |
 
 **Quy tắc DC cho Stitch:** Stitch (và mọi tool non-DC) **không** được tiêu thụ `*.dc.html` như nguồn chân lý. Dùng pattern export tĩnh, `templates/kitchen-sink.html`, `examples/static-hello/`, và class `.cs-*` từ `styles.css`.
 
-**Tín hiệu release:** VERSION giữ **1.0.0** (không CHANGELOG). Coi **git tip SHA** là chân lý kỹ thuật; đọc điểm nổi bật sản phẩm curated trong `docs/release-notes.md`.
+**Tín hiệu release:** VERSION là **1.1.0** (không CHANGELOG). Coi **git tip SHA** là chân lý kỹ thuật; đọc điểm nổi bật sản phẩm curated trong `docs/release-notes.md`.
 
 ## Đường nhanh cho AI agent (Claude Code, hoặc điều khiển một agent)
 
-**Bạn nhận:** `styles.css` (400+ token + class `.cs-*` + bề mặt Liquid Glass, `@import` `tokens/` + `base/`) · `_ds_bundle.js` (React component đã compile, không cần build) · `_esm/cs.mjs` (entry ESM re-export mọi component) · `_ds_manifest.json` (inventory máy đọc được) · mỗi component `Name.d.ts` (API) + `Name.prompt.md` (brief dùng) · `tokens/tokens.dtcg.json` (W3C DTCG) + `tokens.json`/`tokens.js`.
+**Bạn nhận:** `styles.css` (400+ token + class `.cs-*` + bề mặt Liquid Glass, `@import` `tokens/` + `base/`) · `_ds_bundle.js` (React component đã compile, không cần build) · `_esm/react.mjs` (entry React bundler-native — React là peerDependency; mặc định `exports["."]`) · `_esm/cs.mjs` (browser / no-build legacy qua `exports["./legacy"]`) · `_ds_manifest.json` (inventory máy đọc được) · mỗi component `Name.d.ts` (API) + `Name.prompt.md` (brief dùng) · `tokens/tokens.dtcg.json` (W3C DTCG) + `tokens.json`/`tokens.js`.
 
 **Checkout repo** — clone hoặc copy cả cây; mọi thứ là static đường dẫn tương đối. Điểm vào: Storybook trên host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (mọi component live, portable) · `templates/<slug>/` (điểm bắt đầu copy được — DC cho Claude Design; kitchen-sink / `.cs-*` cho Stitch). Đọc `SKILL.md` trước khi author bất kỳ thứ gì on-brand; reader Stitch bắt đầu tại `DESIGN.md`. Bản đồ sâu hơn ở `llms.txt` (inventory) và file này (hướng dẫn adopt + upgrade đầy đủ bên dưới).
 
@@ -38,18 +38,29 @@ Cách mọi project — do người hoặc agent điều khiển — áp dụng
 
 ## Adopt qua npm (tùy chọn)
 
-Package có thể publish (`private: false`, phiên bản cố định **1.0.0**). License vẫn **UNLICENSED** — cài từ registry (hoặc tarball đã pack) **không** tự cấp quyền redistribution. Đến khi owner chọn license mở, **consumer cần grant tường minh** từ CyberSkill để dùng package trong sản phẩm. Org `@cyberskill` và `NPM_TOKEN` trên repo đã sẵn sàng vận hành; chạy **Actions → npm-publish** một lần để `@cyberskill/design` lên registry. Thiếu `NPM_TOKEN` thì workflow **soft-skip** (exit 0 + report) — đó là trung thực, không phải release registry thành công. Xem `docs/decisions.md` và `docs/quality-gates.md`.
+Package có thể publish (`private: false`, phiên bản **1.1.0**). License vẫn **UNLICENSED** — cài từ registry **không** tự cấp quyền redistribution. **`@cyberskill/design@1.1.0` là cut LAUNCH (publish qua tag `v1.1.0`).** CI republish qua **npm Trusted Publishing (OIDC)** trên workflow `npm-publish.yml` (không token publish dài hạn; Publishing access package **disallow tokens**). Dùng đã duyệt ghi tại **`docs/consumer-grant.md`** (sản phẩm portfolio CyberSkill từ `docs/products.md`). Xem `docs/decisions.md` và `docs/ci-cd.md`.
 
-**Grant consumer (chính sách owner — không phải secret).** Với mỗi team được duyệt, ghi lại kiểu: *CyberSkill cấp cho [Team/Org] quyền không độc quyền dùng `@cyberskill/design` trong [sản phẩm đã nêu]. Package vẫn UNLICENSED; redistribution ngoài các sản phẩm đó cần grant viết thêm.* Giữ văn bản grant nội bộ trừ khi muốn công khai.
+**Grant consumer (chính sách owner — không phải secret).** Đã viết và có hiệu lực tại `docs/consumer-grant.md` (+ `docs/vi/consumer-grant.md`). Team bên ngoài cần stanza có ngày thêm vào đó; redistribution ngoài sản phẩm đã grant cần grant viết thêm.
 
 ```bash
-# sau khi workflow npm-publish chạy thành công (hoặc từ tarball đã pack)
-npm install @cyberskill/design@1.0.0
+npm install @cyberskill/design@1.1.0
 ```
 
-Rồi link styles và import từ entry package (`_esm/cs.mjs` qua `exports["."]`) , hoặc tiếp tục dùng đường cây tĩnh bên dưới. Tarball đã publish là **cả cây portable** (styles, tokens, components, templates, guidelines, docs, UI kits) — không phải subset “chỉ lib” tối thiểu. Tooling chỉ-host (Storybook, `_audit/`) không nằm trong `files[]`.
+Rồi link styles và import component. **App Next.js / Vite / SSR** dùng entry mặc định (bundler-native):
 
-**Đường publish (maintainer):** `prepublishOnly` chạy `build:bundle` + `build:design-md --check`. Workflow `.github/workflows/npm-publish.yml` trên `workflow_dispatch` / tag `v*`; publish cần `NPM_TOKEN` (`node _audit/ci/npm-publish.mjs --dry-run` luôn liệt kê tarball). Xem `docs/ci-cd.md` và `docs/decisions.md`.
+```ts
+import { Button, TextField } from "@cyberskill/design";
+// tương đương: import { Button } from "@cyberskill/design/react";
+import "@cyberskill/design/styles.css";
+```
+
+Thêm `transpilePackages: ["@cyberskill/design"]` trong Next.js (JSX ship dạng source). React và react-dom là **peerDependencies** — app của bạn cung cấp. Types publish dùng `export type *` (**TypeScript 5.0+**). **Không** import `_esm/cs.mjs` (hay `@cyberskill/design/legacy`) vào bundler SSR; đường đó self-ensure React qua CDN và side-load `_ds_bundle.js` chỉ cho browser.
+
+**Browser / no-build:** import `@cyberskill/design/legacy` (`_esm/cs.mjs`) hoặc tiếp tục dùng đường cây tĩnh bên dưới. Tarball đã publish là **cả cây portable** (styles, tokens, components, templates, guidelines, docs, UI kits) — không phải subset “chỉ lib” tối thiểu. Tooling chỉ-host (Storybook, `_audit/`) không nằm trong `files[]`.
+
+**Cài thật đầu tiên (Lumi).** Consumer **browser** copy-paste: `examples/npm-hello/` — cài `@cyberskill/design@1.1.0` từ registry, link `styles.css`, mount `Button` qua entry **legacy** (`_esm/cs.mjs`), scope **Lumi** với `data-cs-element="hoa" data-cs-variant="plasma"` (hàng đã khóa trong `docs/products.md`). Trong thư mục đó: `npm install && npm run smoke && npm start` → mở `http://127.0.0.1:8766/`. Team Status Hub dùng cùng install và đổi sang `data-cs-element="thuy"` — không invent ánh xạ. Cho app Next/SSR (ví dụ Lumi landing), dùng `import { Button } from "@cyberskill/design"` như trên — không dùng import map của npm-hello.
+
+**Đường publish (maintainer):** `prepublishOnly` chạy `build:bundle` + `build:design-md --check`. Workflow `.github/workflows/npm-publish.yml` trên `workflow_dispatch` / tag `v*` dùng **Trusted Publishing** (`permissions.id-token: write`; không đặt `NODE_AUTH_TOKEN` trên bước publish). `node _audit/ci/npm-publish.mjs --dry-run` luôn liệt kê tarball. Xem `docs/ci-cd.md` và `docs/decisions.md`.
 
 ## Adopt (hai đường, cộng shortcut module)
 
@@ -65,7 +76,9 @@ Rồi link styles và import từ entry package (`_esm/cs.mjs` qua `exports["."]
 </script>
 ```
 Đây đúng là những gì `_audit/consumer-smoke-test.html` chạy (và assert xanh) — và `ds-base.js` của templates làm tương tự, publish alias ổn định `window.CyberSkillDS`.
-**2b. Đường ESM (module) — một import, không build.** `import { Button, TextField } from "<path>/_esm/cs.mjs"` — module tự ensure React (pinned; bỏ qua khi đã có `window.React`), side-load `_ds_bundle.js` một lần, resolve namespace theo prefix, và re-export mọi component (`_audit/esm-smoke-test.html` giữ danh sách export khóa với manifest). Vẫn tự link `styles.css`.
+**2b. React bundler-native (Next / Vite / SSR) — entry package mặc định.** `import { Button, TextField } from "@cyberskill/design"` resolve tới `_esm/react.mjs` (cũng export như `@cyberskill/design/react`). Re-export mọi component từ JSX source với **React là peer external** — không CDN, không side-load `_ds_bundle.js`. Bundler của bạn phải transpile package (Next: `transpilePackages: ["@cyberskill/design"]`). Vẫn tự link `styles.css`. Regenerated bằng `npm run build:react-entry`; parity được gate bởi `package-exports-integrity` + `test:react-entry`.
+
+**2c. ESM browser legacy — một import, không build.** `import { Button, TextField } from "@cyberskill/design/legacy"` (hoặc `"<path>/_esm/cs.mjs"`) — module tự ensure React qua **umd-react@19.2.8** (CDN pin SRI; React 19 chính thức không còn UMD; bỏ qua khi đã có `window.React`), side-load `_ds_bundle.js` một lần, resolve namespace theo prefix, và re-export mọi component (`_audit/esm-smoke-test.html` giữ danh sách export khóa với manifest). Vẫn tự link `styles.css`. **Không dùng cho Next/SSR.** App bundler vẫn cung cấp peer `react` / `react-dom` (`^18 || ^19`).
 
 **Templates.** Mỗi `templates/<slug>/` là Design Component seed từ `ds-base.js` (một dòng `base` để rebind đường dẫn tới nơi hệ thống này nằm tương đối với trang tiêu thụ). Copy thư mục và sửa copy/tweaks.
 
@@ -73,13 +86,17 @@ Rồi link styles và import từ entry package (`_esm/cs.mjs` qua `exports["."]
 
 **HTML tĩnh / không React / không build tooling.** Link `styles.css` và compose bằng class `.cs-*` — catalog đầy đủ trong `templates/kitchen-sink.html`.
 
-## Ba trục
+**Font, kể cả mặt chữ display.** Cả ba họ chữ brand đều self-host trong `fonts/` và khai báo ở `tokens/fonts.css` (được `styles.css` `@import`): **Be Vietnam Pro** (`--cs-font-family-ui`), **JetBrains Mono** (`--cs-font-family-mono`), và **Space Grotesk** (`--cs-font-family-display`, variable 300–700, có subset tiếng Việt). Mặt chữ display là **opt-in** — không thứ gì trong DS trỏ vào nó. Sản phẩm muốn mặt chữ tiêu đề thêm `class="cs-display-face"` (hoặc đặt `--cs-heading-family: var(--cs-font-family-display)`) trên scope; các utility heading theo sau, body copy vẫn ở mặt chữ UI.
+
+Consumer bỏ qua `styles.css` để tự kiểm soát font loading (`cyberskill.world` / Lumi import riêng các sheet token + base và giữ chiến lược `font-display: optional` của mình) có thể chuyển từ `brand-fonts.css` tự chế sang package: hoặc `@import "@cyberskill/design/tokens/fonts.css"` để lấy face đóng gói, hoặc giữ block `@font-face` cục bộ và trỏ `--cs-heading-family` vào `var(--cs-font-family-display)` để **role** đến từ DS ngay cả khi **byte** vẫn phục vụ cục bộ. Cách nào thì mặt chữ display cũng thôi là ngoại lệ riêng của một sản phẩm. Space Grotesk không có weight 800, nên `--cs-heading-weight-strong` (800) dưới `.cs-display-face` clamp về 700 trong Space Grotesk — CSS không nhảy sang Be Vietnam Pro vì thiếu weight.
 
-Đặt Theme (`data-theme`), Element (`data-cs-element` + `data-cs-variant`), và Language (`lang` / Language tweak trên template) trên một container; mọi thứ bên trong re-skin không cần đổi code (xem `templates/playground.html`). Mặc định: `light · tho · en`. Xử lý bề mặt là liquid-glass (cố định). Bilingual: component resolve chuỗi từ `lang` (`lang="vi"` trên mọi container → tiếng Việt đầy đủ).
+## Bốn trục
+
+Đặt Theme (`data-theme` — light / dark / system), Element (`data-cs-element` + `data-cs-variant`), Language (`lang` / Language tweak trên template), và Style (`data-cs-style`) trên một container; mọi thứ bên trong re-skin không cần đổi code (xem `templates/playground.html`). Mặc định: `light · tho · en · liquid-glass` (vắng theme / style ≡ các mặc định đó). Bilingual: component resolve chuỗi từ `lang` (`lang="vi"` trên mọi container → tiếng Việt đầy đủ).
 
 ## Nâng cấp
 
-- **Phiên bản cố định.** `VERSION` và `package.json` giữ **1.0.0**. Không có file changelog design-system — coi **git tip SHA** là chân lý kỹ thuật, và đọc **Release Notes** curated (Storybook + `docs/release-notes.md`) cho điểm nổi bật hướng sản phẩm.
+- **Phiên bản cố định.** `VERSION` và `package.json` là **1.1.0**. Không có file changelog design-system — coi **git tip SHA** là chân lý kỹ thuật, và đọc **Release Notes** curated (Storybook + `docs/release-notes.md`) cho điểm nổi bật hướng sản phẩm.
 
 - Anchors (Umber/Ochre), tên class `.cs-*`, và tên token `--cs-*` là hợp đồng ổn định — an toàn để phụ thuộc. Đổi tên phá vỡ những hợp đồng đó phải hiếm và được gọi ra trong PR/docs khi xảy ra.
 
@@ -87,10 +104,22 @@ Rồi link styles và import từ entry package (`_esm/cs.mjs` qua `exports["."]
 
 ## Host Storybook (tùy chọn)
 
-Site live phục vụ Storybook tại `/` như **bề mặt sản phẩm** cho operator (Theme × Element × Language + ma trận điều khiển). Đó là **tooling chỉ-host** — đừng phụ thuộc Storybook trong product app. Atomic View portable vẫn ở `guidelines/atomic-view.html`. Xem `docs/storybook.md` và `docs/live-hub.md`.
+Site live phục vụ Storybook tại `/` như **bề mặt sản phẩm** cho operator (Theme × Element × Language × Style + ma trận điều khiển). Đó là **tooling chỉ-host** — đừng phụ thuộc Storybook trong product app. Atomic View portable vẫn ở `guidelines/atomic-view.html`. Xem `docs/storybook.md` và `docs/live-hub.md`.
 
 ## Spike consumer năm phút
 
+**Đường registry (ưu tiên cho product app):**
+
+```bash
+cd examples/npm-hello
+npm install
+npm run smoke
+npm start
+# mở http://127.0.0.1:8766/
+```
+
+**Đường clone / tĩnh (không npm):**
+
 ```bash
 # từ monorepo root
 python3 -m http.server 8765 --bind 127.0.0.1
@@ -102,7 +131,7 @@ Sửa `examples/static-hello/index.html`: flip `data-theme="dark"` hoặc `data-
 
 ## Native sample hosts (tùy chọn)
 
-Sample đa màn hình (Sign in · Home · Settings) nằm dưới `examples/native/swiftui`, `compose`, và `flutter`. Chúng sync token generate qua `node examples/native/sync-tokens.mjs`. Xem `examples/native/README.md`. Không bắt buộc cho web consumer.
+Sample đa màn hình (Sign in · Home · Settings) nằm dưới `examples/native/swiftui`, `compose`, và `flutter`. Chúng sync token generate qua `node examples/native/sync-tokens.mjs`. Compose mở bằng **Android Studio** (không commit `gradlew` — CLI cần JDK 17+ + SDK; xem `examples/native/README.md`). Không bắt buộc cho web consumer.
 
 ## Mở rộng
 

package/docs/vi/contrast-report.md

@@ -1,11 +1,11 @@
 # Báo cáo contrast — cặp elemental (APCA)
 
-Sinh 2026-07-22 · sweep tại pin VERSION 1.0.0.
+Tạo 2026-07-27 · quét tại pin VERSION 1.1.0.
 
-**Doctrine mã hóa bởi sweep này:** chữ nằm trên `-bright` hoặc `-tint`, không bao giờ trên mid-tone `-accent` — ở mọi kích thước. Accent chỉ cho thanh, border, progress fill, và fill không-chữ. (Quy tắc trong `tokens/elements.css` và conventions.)
+**Doctrine của sweep này:** chữ ngồi trên `-bright` hoặc `-tint`, không bao giờ trên mid-tone `-accent`. Accent chỉ cho bar, border, progress, fill không chữ. (Rule trong `tokens/elements.css` và conventions.)
 
-Nudge token cho v2.0: bright làm sáng cho clay, hoa, lava, plasma, thủy, ocean, forest, titanium; `-on` đảo tối cho lava, ocean, forest, titanium.
-| Phạm vi | Cặp | fg / bg | Lc | Kết quả |
+Pack được generate từ `tokens/element-seeds.json` (thang soft / middle / deep, khóa hue light↔dark). Gate hình học: `_audit/element-geometry.html`.
+| Scope | Pairing | fg / bg | Lc | Verdict |
 |---|---|---|---|---|
 | root (Thổ default) | text-accent on white (bold labels) | #6E3B0E / #FFFFFF | 90.7 | ✓ |
 | root (Thổ default) | text-accent on tint (bold labels) | #6E3B0E / #FBF4E9 | 84.6 | ✓ |
@@ -16,110 +16,98 @@ Nudge token cho v2.0: bright làm sáng cho clay, hoa, lava, plasma, thủy, oce
 | tho | text-accent on tint (bold labels) | #6E3B0E / #FBF4E9 | 84.6 | ✓ |
 | tho | accent-bright on ink (headings) | #F4BA17 / #45210E | 66.3 | ✓ |
 | tho | accent-on on accent-bright (CTA text) | #45210E / #F4BA17 | 66.3 | ✓ |
-| tho | accent-bright on dark panel (dark labels) | #F4BA17 / #221710 | 69.2 | ✓ |
-| tho   · clay | text-accent on white (bold labels) | #8F5230 / #FFFFFF | 80.4 | ✓ |
-| tho   · clay | text-accent on tint (bold labels) | #8F5230 / #F8EDE4 | 70.7 | ✓ |
-| tho   · clay | accent-bright on ink (headings) | #EDBF9D / #2E1607 | 71.6 | ✓ |
-| tho   · clay | accent-on on accent-bright (CTA text) | #2E1607 / #EDBF9D | 72 | ✓ |
-| tho   · clay | accent-bright on dark panel (dark labels) | #EDBF9D / #221710 | 72 | ✓ |
-| tho   · sand | text-accent on white (bold labels) | #8A6F3C / #FFFFFF | 72.9 | ✓ |
-| tho   · sand | text-accent on tint (bold labels) | #8A6F3C / #FAF3E3 | 66 | ✓ |
-| tho   · sand | accent-bright on ink (headings) | #EFDCB2 / #3A2A10 | 82 | ✓ |
-| tho   · sand | accent-on on accent-bright (CTA text) | #3A2A10 / #EFDCB2 | 80.8 | ✓ |
-| tho   · sand | accent-bright on dark panel (dark labels) | #EFDCB2 / #221710 | 85.1 | ✓ |
-| hoa | text-accent on white (bold labels) | #A93E14 / #FFFFFF | 80 | ✓ |
-| hoa | text-accent on tint (bold labels) | #A93E14 / #FBEADF | 69.3 | ✓ |
-| hoa | accent-bright on ink (headings) | #F6A26B / #231007 | 62 | ✓ |
-| hoa | accent-on on accent-bright (CTA text) | #231007 / #F6A26B | 63.3 | ✓ |
-| hoa | accent-bright on dark panel (dark labels) | #F6A26B / #221710 | 61.6 | ✓ |
-| hoa   · lava | text-accent on white (bold labels) | #9B2D14 / #FFFFFF | 85.1 | ✓ |
-| hoa   · lava | text-accent on tint (bold labels) | #9B2D14 / #FAE5DC | 72.1 | ✓ |
-| hoa   · lava | accent-bright on ink (headings) | #F6AC85 / #1D0B05 | 66.5 | ✓ |
-| hoa   · lava | accent-on on accent-bright (CTA text) | #1D0B05 / #F6AC85 | 67.6 | ✓ |
-| hoa   · lava | accent-bright on dark panel (dark labels) | #F6AC85 / #221710 | 65.7 | ✓ |
-| hoa   · plasma | text-accent on white (bold labels) | #B02348 / #FFFFFF | 81.2 | ✓ |
-| hoa   · plasma | text-accent on tint (bold labels) | #B02348 / #FBE6EB | 69.3 | ✓ |
-| hoa   · plasma | accent-bright on ink (headings) | #F7A8B8 / #200812 | 66.8 | ✓ |
-| hoa   · plasma | accent-on on accent-bright (CTA text) | #200812 / #F7A8B8 | 67.9 | ✓ |
-| hoa   · plasma | accent-bright on dark panel (dark labels) | #F7A8B8 / #221710 | 66.1 | ✓ |
-| thuy | text-accent on white (bold labels) | #2F5E6B / #FFFFFF | 84.7 | ✓ |
-| thuy | text-accent on tint (bold labels) | #2F5E6B / #E6F1F2 | 75.1 | ✓ |
-| thuy | accent-bright on ink (headings) | #A6D0DA / #0E1D20 | 72.4 | ✓ |
-| thuy | accent-on on accent-bright (CTA text) | #0E1D20 / #A6D0DA | 72.8 | ✓ |
-| thuy | accent-bright on dark panel (dark labels) | #A6D0DA / #221710 | 72.5 | ✓ |
-| thuy   · ocean | text-accent on white (bold labels) | #1C3E56 / #FFFFFF | 95.7 | ✓ |
-| thuy   · ocean | text-accent on tint (bold labels) | #1C3E56 / #E4EEF4 | 84.7 | ✓ |
-| thuy   · ocean | accent-bright on ink (headings) | #A9CCE0 / #0B161E | 71.8 | ✓ |
-| thuy   · ocean | accent-on on accent-bright (CTA text) | #0B161E / #A9CCE0 | 72.6 | ✓ |
-| thuy   · ocean | accent-bright on dark panel (dark labels) | #A9CCE0 / #221710 | 71.4 | ✓ |
-| thuy   · mist | text-accent on white (bold labels) | #4A686E / #FFFFFF | 80 | ✓ |
-| thuy   · mist | text-accent on tint (bold labels) | #4A686E / #F0F6F7 | 73.9 | ✓ |
-| thuy   · mist | accent-bright on ink (headings) | #C4DADD / #16262A | 78.9 | ✓ |
-| thuy   · mist | accent-on on accent-bright (CTA text) | #16262A / #C4DADD | 78.5 | ✓ |
-| thuy   · mist | accent-bright on dark panel (dark labels) | #C4DADD / #221710 | 80.3 | ✓ |
-| moc | text-accent on white (bold labels) | #4C6B35 / #FFFFFF | 80.2 | ✓ |
-| moc | text-accent on tint (bold labels) | #4C6B35 / #EEF3E2 | 71.8 | ✓ |
-| moc | accent-bright on ink (headings) | #A9C177 / #18200F | 62.3 | ✓ |
-| moc | accent-on on accent-bright (CTA text) | #18200F / #A9C177 | 63.2 | ✓ |
-| moc | accent-bright on dark panel (dark labels) | #A9C177 / #221710 | 62.8 | ✓ |
-| moc   · bamboo | text-accent on white (bold labels) | #5B7237 / #FFFFFF | 76.7 | ✓ |
-| moc   · bamboo | text-accent on tint (bold labels) | #5B7237 / #F3F7E8 | 70.8 | ✓ |
-| moc   · bamboo | accent-bright on ink (headings) | #C4D69B / #1C240F | 75 | ✓ |
-| moc   · bamboo | accent-on on accent-bright (CTA text) | #1C240F / #C4D69B | 75 | ✓ |
-| moc   · bamboo | accent-bright on dark panel (dark labels) | #C4D69B / #221710 | 76 | ✓ |
-| moc   · forest | text-accent on white (bold labels) | #31481F / #FFFFFF | 93.4 | ✓ |
-| moc   · forest | text-accent on tint (bold labels) | #31481F / #E9EFE1 | 82.6 | ✓ |
-| moc   · forest | accent-bright on ink (headings) | #B3CE9B / #101708 | 71 | ✓ |
-| moc   · forest | accent-on on accent-bright (CTA text) | #101708 / #B3CE9B | 71.8 | ✓ |
-| moc   · forest | accent-bright on dark panel (dark labels) | #B3CE9B / #221710 | 70.5 | ✓ |
-| kim | text-accent on white (bold labels) | #6E6151 / #FFFFFF | 80.1 | ✓ |
-| kim | text-accent on tint (bold labels) | #6E6151 / #F3EFE6 | 70.7 | ✓ |
-| kim | accent-bright on ink (headings) | #D8CCB6 / #221C12 | 74.7 | ✓ |
-| kim | accent-on on accent-bright (CTA text) | #221C12 / #D8CCB6 | 74.9 | ✓ |
-| kim | accent-bright on dark panel (dark labels) | #D8CCB6 / #221710 | 75.1 | ✓ |
-| kim   · steel | text-accent on white (bold labels) | #565C5E / #FFFFFF | 83.5 | ✓ |
-| kim   · steel | text-accent on tint (bold labels) | #565C5E / #EFF1F1 | 74.9 | ✓ |
-| kim   · steel | accent-bright on ink (headings) | #C2C6C6 / #191D1E | 70 | ✓ |
-| kim   · steel | accent-on on accent-bright (CTA text) | #191D1E / #C2C6C6 | 70.6 | ✓ |
-| kim   · steel | accent-bright on dark panel (dark labels) | #C2C6C6 / #221710 | 70.3 | ✓ |
-| kim   · titanium | text-accent on white (bold labels) | #56504A / #FFFFFF | 87.6 | ✓ |
-| kim   · titanium | text-accent on tint (bold labels) | #56504A / #EFEBE5 | 76 | ✓ |
-| kim   · titanium | accent-bright on ink (headings) | #D9CFC0 / #171310 | 77.5 | ✓ |
-| kim   · titanium | accent-on on accent-bright (CTA text) | #171310 / #D9CFC0 | 77.9 | ✓ |
-| kim   · titanium | accent-bright on dark panel (dark labels) | #D9CFC0 / #221710 | 76.9 | ✓ |
+| tho | accent-bright on dark panel (dark labels) | #FEC42C / #221710 | 75 | ✓ |
+| tho · sand | text-accent on white (bold labels) | #90825E / #FFFFFF | 65.4 | ✓ |
+| tho · sand | text-accent on tint (bold labels) | #90825E / #FBF7EA | 60.6 | ✓ |
+| tho · sand | accent-bright on ink (headings) | #F6EBCC / #292414 | 92.3 | ✓ |
+| tho · sand | accent-on on accent-bright (CTA text) | #292414 / #F6EBCC | 90.8 | ✓ |
+| tho · sand | accent-bright on dark panel (dark labels) | #F6EBCC / #221710 | 93.8 | ✓ |
+| tho · clay | text-accent on white (bold labels) | #201300 / #FFFFFF | 104.8 | ✓ |
+| tho · clay | text-accent on tint (bold labels) | #201300 / #FFF6E7 | 100 | ✓ |
+| tho · clay | accent-bright on ink (headings) | #DEC7A2 / #2D220E | 71.7 | ✓ |
+| tho · clay | accent-on on accent-bright (CTA text) | #2D220E / #DEC7A2 | 71.8 | ✓ |
+| tho · clay | accent-bright on dark panel (dark labels) | #E4CDA8 / #221710 | 76.7 | ✓ |
+| hoa | text-accent on white (bold labels) | #B47054 / #FFFFFF | 66.2 | ✓ |
+| hoa | text-accent on tint (bold labels) | #B47054 / #FFF4F0 | 60.9 | ✓ |
+| hoa | accent-bright on ink (headings) | #FED3C3 / #381B10 | 82.8 | ✓ |
+| hoa | accent-on on accent-bright (CTA text) | #381B10 / #FED3C3 | 82.1 | ✓ |
+| hoa | accent-bright on dark panel (dark labels) | #FED3C3 / #221710 | 84.2 | ✓ |
+| hoa · plasma | text-accent on white (bold labels) | #967C75 / #FFFFFF | 66.1 | ✓ |
+| hoa · plasma | text-accent on tint (bold labels) | #967C75 / #FEF4F2 | 60.7 | ✓ |
+| hoa · plasma | accent-bright on ink (headings) | #FCE6DF / #2C211E | 91.8 | ✓ |
+| hoa · plasma | accent-on on accent-bright (CTA text) | #2C211E / #FCE6DF | 90.4 | ✓ |
+| hoa · plasma | accent-bright on dark panel (dark labels) | #FCE6DF / #221710 | 93.2 | ✓ |
+| hoa · lava | text-accent on white (bold labels) | #280D00 / #FFFFFF | 104.7 | ✓ |
+| hoa · lava | text-accent on tint (bold labels) | #280D00 / #FFF4EF | 99.4 | ✓ |
+| hoa · lava | accent-bright on ink (headings) | #F1BEA4 / #361D0F | 71 | ✓ |
+| hoa · lava | accent-on on accent-bright (CTA text) | #361D0F / #F1BEA4 | 71.2 | ✓ |
+| hoa · lava | accent-bright on dark panel (dark labels) | #F8C4AA / #221710 | 76.2 | ✓ |
+| thuy | text-accent on white (bold labels) | #108EA0 / #FFFFFF | 65.8 | ✓ |
+| thuy | text-accent on tint (bold labels) | #108EA0 / #E7FBFF | 61.2 | ✓ |
+| thuy | accent-bright on ink (headings) | #99EEFF / #012A30 | 85.3 | ✓ |
+| thuy | accent-on on accent-bright (CTA text) | #012A30 / #99EEFF | 84.3 | ✓ |
+| thuy | accent-bright on dark panel (dark labels) | #99EEFF / #221710 | 87.2 | ✓ |
+| thuy · mist | text-accent on white (bold labels) | #5A8A90 / #FFFFFF | 65.8 | ✓ |
+| thuy · mist | text-accent on tint (bold labels) | #5A8A90 / #EBFAFC | 61.1 | ✓ |
+| thuy · mist | accent-bright on ink (headings) | #CDF4F9 / #13282B | 93.1 | ✓ |
+| thuy · mist | accent-on on accent-bright (CTA text) | #13282B / #CDF4F9 | 91.5 | ✓ |
+| thuy · mist | accent-bright on dark panel (dark labels) | #CDF4F9 / #221710 | 94.7 | ✓ |
+| thuy · ocean | text-accent on white (bold labels) | #011A21 / #FFFFFF | 104.5 | ✓ |
+| thuy · ocean | text-accent on tint (bold labels) | #011A21 / #EAFAFF | 99.8 | ✓ |
+| thuy · ocean | accent-bright on ink (headings) | #A8D3E0 / #10282F | 72.7 | ✓ |
+| thuy · ocean | accent-on on accent-bright (CTA text) | #10282F / #A8D3E0 | 72.6 | ✓ |
+| thuy · ocean | accent-bright on dark panel (dark labels) | #ABD6E3 / #221710 | 76.1 | ✓ |
+| moc | text-accent on white (bold labels) | #629122 / #FFFFFF | 64.9 | ✓ |
+| moc | text-accent on tint (bold labels) | #629122 / #EFFCE3 | 60.5 | ✓ |
+| moc | accent-bright on ink (headings) | #C5ED9C / #182A00 | 85.2 | ✓ |
+| moc | accent-on on accent-bright (CTA text) | #182A00 / #C5ED9C | 84.2 | ✓ |
+| moc | accent-bright on dark panel (dark labels) | #C5ED9C / #221710 | 86.9 | ✓ |
+| moc · bamboo | text-accent on white (bold labels) | #7C8965 / #FFFFFF | 64.9 | ✓ |
+| moc · bamboo | text-accent on tint (bold labels) | #7C8965 / #F4F9ED | 60.2 | ✓ |
+| moc · bamboo | accent-bright on ink (headings) | #E5F1D2 / #212617 | 93 | ✓ |
+| moc · bamboo | accent-on on accent-bright (CTA text) | #212617 / #E5F1D2 | 91.4 | ✓ |
+| moc · bamboo | accent-bright on dark panel (dark labels) | #E5F1D2 / #221710 | 94.5 | ✓ |
+| moc · forest | text-accent on white (bold labels) | #051D00 / #FFFFFF | 104.4 | ✓ |
+| moc · forest | text-accent on tint (bold labels) | #051D00 / #ECFDE7 | 100.2 | ✓ |
+| moc · forest | accent-bright on ink (headings) | #B0D8A3 / #162A0E | 73.2 | ✓ |
+| moc · forest | accent-on on accent-bright (CTA text) | #162A0E / #B0D8A3 | 73.2 | ✓ |
+| moc · forest | accent-bright on dark panel (dark labels) | #B0D8A3 / #221710 | 75 | ✓ |
+| kim | text-accent on white (bold labels) | #AC780B / #FFFFFF | 65.8 | ✓ |
+| kim | text-accent on tint (bold labels) | #AC780B / #FFF5E7 | 60.5 | ✓ |
+| kim | accent-bright on ink (headings) | #FDD89F / #312002 | 83.5 | ✓ |
+| kim | accent-on on accent-bright (CTA text) | #312002 / #FDD89F | 82.8 | ✓ |
+| kim | accent-bright on dark panel (dark labels) | #FDD89F / #221710 | 85 | ✓ |
+| kim · titanium | text-accent on white (bold labels) | #947F65 / #FFFFFF | 65.8 | ✓ |
+| kim · titanium | text-accent on tint (bold labels) | #947F65 / #FDF5ED | 60.5 | ✓ |
+| kim · titanium | accent-bright on ink (headings) | #FBE8D2 / #2B2217 | 92 | ✓ |
+| kim · titanium | accent-on on accent-bright (CTA text) | #2B2217 / #FBE8D2 | 90.6 | ✓ |
+| kim · titanium | accent-bright on dark panel (dark labels) | #FBE8D2 / #221710 | 93.4 | ✓ |
+| kim · steel | text-accent on white (bold labels) | #1F1400 / #FFFFFF | 104.8 | ✓ |
+| kim · steel | text-accent on tint (bold labels) | #1F1400 / #FEF6E7 | 99.8 | ✓ |
+| kim · steel | accent-bright on ink (headings) | #DCC8A2 / #2D220E | 71.8 | ✓ |
+| kim · steel | accent-on on accent-bright (CTA text) | #2D220E / #DCC8A2 | 71.9 | ✓ |
+| kim · steel | accent-bright on dark panel (dark labels) | #DFCBA5 / #221710 | 75.1 | ✓ |
 
-**Thất bại: 0.** Mọi cặp chữ pass Lc ≥ 60.
+**Failures: 0.** All text pairings pass Lc ≥ 60.
 
-## Màu semantic dark-theme (WCAG, thêm v2.8.0)
+## Dark pack APCA floors (gate twin)
 
-Foreground semantic light-theme fail trên bề mặt tối (~2.5:1), nên dark theme override chúng. Contrast WCAG trên panel tối `#221710` (và khi làm fill kèm dark ink `#1a1108`):
-| Vai trò | Giá trị dark | trên panel | làm fill w/ ink | Kết quả |
+Targets match `_audit/apca-dark-preview.html`: bright ≥ 75 · accent ≥ 60 · on/strong ≥ 75 · ink-on-tint ≥ 75.
+| Pack | bright | accent | on | ink |
 |---|---|---|---|---|
-| success | #4ADE80 | 10.06 | 10.69 | ✓ |
-| danger | #F87171 | 6.34 | 6.73 | ✓ |
-| warning | #FBBF24 | 10.50 | 11.16 | ✓ |
-| info | #7CB2FB | 8.03 | 8.53 | ✓ |
+| tho | 75 | 69.2 | 75.6 | 76.8 |
+| tho · sand | 93.8 | 92.7 | 75.6 | 91.5 |
+| tho · clay | 76.7 | 60.4 | 94.1 | 76.2 |
+| hoa | 84.2 | 68.2 | 75.1 | 81.9 |
+| hoa · plasma | 93.2 | 91.2 | 75 | 90.9 |
+| hoa · lava | 76.2 | 61.1 | 94 | 75.7 |
+| thuy | 87.2 | 72.8 | 76 | 84.4 |
+| thuy · mist | 94.7 | 94 | 75.9 | 92 |
+| thuy · ocean | 76.1 | 60.1 | 93.9 | 75.1 |
+| moc | 86.9 | 71.8 | 75.4 | 84.4 |
+| moc · bamboo | 94.5 | 93.6 | 75.3 | 92 |
+| moc · forest | 75 | 60.8 | 93.7 | 76.3 |
+| kim | 85 | 69.2 | 75.6 | 82.6 |
+| kim · titanium | 93.4 | 92.1 | 75.8 | 91.1 |
+| kim · steel | 75.1 | 60.7 | 94 | 76.4 |
 
-Core dark cũng remap nút primary sang Ochre (`#f4ba17` trên `#1a1108`) và làm ấm border field — để không control dark nào low-contrast. Shadow dark nhuốm umber (yếu trên nền tối vốn vậy); hairline border dark tách panel thay thế.
-File này được generate — chạy lại script APCA sweep sau mọi đổi token.
-
-## Pack elemental dark — xác minh APCA (v4.0.0, Th7 2026)
-
-Sinh với pack dark đã owner duyệt; đo bằng cùng implementation SAPC-4g như `_audit/apca-dark-preview.html` (cũng là regression gate). Mục tiêu: bright ≥ 75 · accent ≥ 60 · button ink ≥ 75 · ink-on-tint ≥ 75 — **15/15 pack pass**.
-| Pack | bright | accent | on/strong | ink/tint |
-|---|---|---|---|---|
-| tho | 75 | 69.2 | 75.1 | 75.3 |
-| tho · clay | 75.7 | 61.5 | 76 | 76.1 |
-| tho · sand | 85.1 | 74.3 | 75.7 | 83.6 |
-| hoa | 75.1 | 61.5 | 75.6 | 75.9 |
-| hoa · lava | 75 | 60.6 | 83.5 | 75.8 |
-| hoa · plasma | 75.9 | 60.8 | 75.4 | 76.7 |
-| thuy | 76.6 | 61.6 | 76.7 | 76.6 |
-| thuy · ocean | 77.2 | 60 | 86.6 | 75.5 |
-| thuy · mist | 80.3 | 66.6 | 76 | 78.7 |
-| moc | 76 | 60.1 | 76 | 76.1 |
-| moc · bamboo | 76 | 62.8 | 75 | 76.2 |
-| moc · forest | 76.4 | 60.9 | 88.6 | 76.6 |
-| kim | 75.1 | 60.1 | 75.2 | 75.4 |
-| kim · steel | 76.3 | 61.1 | 76 | 76.6 |
-| kim · titanium | 76.9 | 60.9 | 79.4 | 75.5 |

package/docs/vi/conventions.md

@@ -4,24 +4,25 @@ Cho người và agent *mở rộng hệ thống này*. (Consumer: đọc `SKILL
 
 ## Quy tắc expansion
 
-**Khi bất kỳ thứ gì lớn lên, mọi thứ cập nhật trong cùng một change.** Element/variant, icon, component, token role, ngôn ngữ, hoặc pattern template mới phải lan tới: tokens/source → specimen cards (guidelines + card nhóm component) **và trang guideline liên quan** → bộ ba hợp đồng component (`.jsx` + `.d.ts` + `.prompt.md`) → **mọi** template (tweak enum và map) → Storybook Live / Identity Lab → docs (đếm README, SKILL, **và mọi tài liệu liên quan change chạm** — kit README, registry, contrast report regen sau đổi token). **Không bump `VERSION` và không maintain file changelog** — version giữ 1.0.0. Continuity là git history cộng **Release Notes** curated (`docs/release-notes.md` / Storybook). Gate mọi expansion bằng compiler check **và grep enum/list cũ** — không ship nửa lan. Ranh giới phạm vi đã ghi (doctrine, không phải lỗ): trang UI-kit giữ tái tạo Thổ pixel-faithful (trục demo ở Storybook Live và Identity Lab); mọi template bilingual EN·VN và mặc định tiếng Anh (collateral client/media giữ English-primary), và biến thể ngôn ngữ render **tách hoàn toàn** — xem decision log.
+**Khi bất kỳ thứ gì lớn lên, mọi thứ cập nhật trong cùng một change.** Element/variant, icon, component, token role, ngôn ngữ, hoặc pattern template mới phải lan tới: tokens/source → specimen cards (guidelines + card nhóm component) **và trang guideline liên quan** → bộ ba hợp đồng component (`.jsx` + `.d.ts` + `.prompt.md`) → **mọi** template (tweak enum và map) → Storybook toolbar / Atomic View → docs (đếm README, SKILL, **và mọi tài liệu liên quan change chạm** — kit README, registry, contrast report regen sau đổi token). **Chỉ bump `VERSION` khi có chỉ thị owner; không maintain file changelog** — version là 1.1.0 (post-LAUNCH). Continuity là git history cộng **Release Notes** curated (`docs/release-notes.md` / Storybook). Gate mọi expansion bằng compiler check **và grep enum/list cũ** — không ship nửa lan. Ranh giới phạm vi đã ghi (doctrine, không phải lỗ): trang UI-kit giữ tái tạo Thổ pixel-faithful (trục demo ở Storybook toolbar và Atomic View); mọi template bilingual EN·VN và mặc định tiếng Anh (collateral client/media giữ English-primary), và biến thể ngôn ngữ render **tách hoàn toàn** — xem decision log.
 
-## Ba trục
+## Bốn trục
 
-Mọi bề mặt render resolve ba scope trực giao — không bao giờ mã hóa một trục trong trục khác:
+Mọi bề mặt render resolve bốn scope trực giao — không bao giờ mã hóa một trục trong trục khác:
 | Trục | Attribute | Sở hữu | Pack sống ở |
 |---|---|---|---|
-| **Theme** | `data-theme="dark\|system"` | đảo light/dark | `tokens/colors.css` |
+| **Theme** | `data-theme="dark\|system"` | light / dark / system (OS) | `tokens/colors.css` |
 | **Element** (Ngũ Hành) | `data-cs-element` + `data-cs-variant` | bản sắc hue theo sản phẩm | `tokens/elements.css` |
 | **Language** | `lang` / Language tweak | copy EN · VI | registry component + props template |
+| **Style** | `data-cs-style` (tuỳ chọn; vắng ≡ `liquid-glass`) | pack vật liệu bề mặt | `tokens/styles.css` |
 
-Xử lý bề mặt là liquid-glass (cố định). Bất biến dưới mọi trục: anchors Umber/Ochre, voice, họ chữ, màu semantic status, vòng focus Ochre 3px, sàn APCA, target ≥44px.
+Pack Style duy nhất hiện nay là **liquid-glass**. Bất biến dưới mọi trục: anchors Umber/Ochre, voice, họ chữ, màu semantic status, vòng focus Ochre 3px, sàn APCA, target ≥44px.
 
 ## Ngữ pháp đặt tên
 
 - Tokens: `--cs-<layer>-<role>[-<state>]` (`--cs-color-text-muted`). Layer role element: `--cs-accent-*` (hợp đồng 9-token — xem header `tokens/elements.css`).
 
-- Classes: `.cs-<block>[-<part>][--modifier]`. Data attributes: `data-theme`, `data-cs-element`, `data-cs-variant`.
+- Classes: `.cs-<block>[-<part>][--modifier]`. Data attributes: `data-theme`, `data-cs-element`, `data-cs-variant`, `data-cs-style`.
 
 - Files: `tokens/<concern>.css` · `base/<concern>.css` (tên concern, không tên changelog — "interaction", không "refinements2") · `components/<group>/<Name>.{jsx,d.ts,prompt.md}` · `templates/<dept>-<artifact>/` · `guidelines/<group>-<topic>.html`.
 
@@ -37,18 +38,20 @@ Xử lý bề mặt là liquid-glass (cố định). Bất biến dưới mọi
 
 **Element variant mới** — ở trong envelope oklch của element; đặt 9 token hợp đồng `--cs-accent-*` 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** — chạy compiler check đến sạch, rồi chạy `_audit/docs-consistency.html` **và** `_audit/namespace-portability.html` (cả hai phải xanh). Version giữ pin 1.0.0.
+**Ship check** — chạy compiler check đến sạch, rồi chạy `_audit/docs-consistency.html` **và** `_audit/namespace-portability.html` (cả hai phải xanh). Version giữ pin 1.1.0.
 
 ## Decision log (owner duyệt)
 
 - Element thay thế hoàn toàn Ochre trong scope sản phẩm; cạnh hot-pink của plasma được duyệt (Th7 2026).
 
-- Trục chỉ Theme × Element × Language. Xử lý bề mặt liquid-glass (cố định).
+- Trục: Theme × Element × Language × Style. Pack Style liquid-glass (sole pack; vắng ≡ mặc định).
 
 - Product registry **đã khóa** (Th7 2026) — tám ánh xạ portfolio trong `docs/products.md`; không invent ánh xạ product → element mới.
 
 - Chữ không bao giờ ngồi trên mid-tone `-accent` — mã hóa sau APCA sweep (xem `docs/contrast-report.md`).
 
+- **Mặt chữ display là một token role, không phải mặc định thứ hai (Th7 2026).** `--cs-font-family-display` ship Space Grotesk (variable 300–700, có subset tiếng Việt) self-host cạnh Be Vietnam Pro và JetBrains Mono, để sản phẩm có mặt chữ tiêu đề — `cyberskill.world` / Lumi — tiêu thụ một role của DS thay vì tự nuôi `@font-face` ngoại lệ riêng. **Không thứ gì trong DS trỏ vào nó**: `--cs-heading-family` vẫn resolve về `--cs-font-family-ui`, mọi template và UI kit không đổi, và một scope chọn dùng qua `.cs-display-face` (`base/typography.css`) — chỉ chuyển `--cs-heading-family`, body copy vẫn ở mặt chữ UI. Space Grotesk không có 800, nên heading weight extrabold clamp về 700 trong family đó (CSS không nhảy sang Be Vietnam Pro vì thiếu weight). Thêm một họ chữ nghĩa là thêm face vào `tokens/fonts.css` **và** file vào `fonts/` **và** entry vào `fonts[]`/`brandFonts[]` của `_ds_manifest.json` — `_audit/font-face-integrity.html` fail nếu một trong ba lệch, và fail nếu family nào thiếu subset tiếng Việt. Điều này không đổi mapping sản phẩm → element nào; `docs/products.md` vẫn khóa.
+
 - Biến thể ngôn ngữ render **tách hoàn toàn**: đổi Language tweak cho artifact một ngôn ngữ đầy đủ — không dịch dở trong heading, label, helper text, footer, hoặc body. Phần bilingual-by-design duy nhất là lockup tên + slogan CyberSkill (`Hiện Thực Hoá Ý Chí · Turn Your Will Into Real`, dạng chuẩn — không bao giờ một nửa lẻ) và khối identity pháp lý A4 (tên pháp lý công ty + khẩu hiệu nhà nước). Mọi thứ khác đổi theo tweak (Th7 2026).
 
 - **Namespace được resolve, không hardcode** — compiler đặt tên bundle global `window.CyberSkillDesignSystem_<projectId>`, và hậu tố 6-hex dẫn từ project id, nên đổi khi hệ thống import vào project khác. Templates đọc alias ổn định `window.CyberSkillDS` mà `ds-base.js` publish lúc bundle load; cards, trang UI-kit, email standalone, và audit harness resolve theo prefix (`window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]`). `_ds_bundle.js`/`_ds_manifest.json` và snapshot đóng băng `_audit/exports/` hợp pháp mang hậu tố thật (chúng *định nghĩa* nó). Enforce bởi `_audit/namespace-portability.html`, quét mọi source index bởi manifest — giữ re-import **zero-touch** (Th7 2026).
@@ -65,7 +68,7 @@ Mọi template export; đường đúng phụ thuộc archetype. Mọi đường
 | Email / product page / mọi DC | **Standalone offline HTML** | DC load CSS + bundle động qua `ds-base.js`, mà `super_inline_html` không thấy. Để bundle: tạo bản `*-standalone.html` **cùng thư mục** (giữ `./support.js` relative) với `<link rel="stylesheet" href="../../styles.css">` + `<script src="../../_ds_bundle.js">` **static** trong raw `<head>` (cả hai inline được) thay `ds-base.js`, cộng `<template id="__bundler_thumbnail">`. Nướng ngôn ngữ đích vào props default. Rồi `super_inline_html`. |
 | Bất kỳ | **Editor-native + Claude Code handoff** | Cả project sẵn sàng handoff-dev (compiled bundle + `.d.ts` + `prompt.md` mỗi component); generate package theo request qua handoff skill. |
 
-**Hành vi font lúc export.** Font brand self-host (`Be Vietnam Pro` UI, mono). PPTX giữ **tên** font brand nhưng không embed file — trên máy không có chúng PowerPoint thay fallback (text Unicode VN được giữ; shape có thể reflow nhẹ). Để hand-off tự chứa đầy đủ, hoặc bảo người nhận cài font, hoặc export với swap web-safe (`fontSwaps:[{from:'Be Vietnam Pro',to:'Arial'}]` — Arial phủ tiếng Việt). Standalone HTML **embed** font (`@font-face` inline từ `styles.css`), nên luôn trung thành offline (Th7 2026).
+**Hành vi font lúc export.** Font brand self-host (`Be Vietnam Pro` UI, `Space Grotesk` display opt-in, mono). PPTX giữ **tên** font brand nhưng không embed file — trên máy không có chúng PowerPoint thay fallback (text Unicode VN được giữ; shape có thể reflow nhẹ). Để hand-off tự chứa đầy đủ, hoặc bảo người nhận cài font, hoặc export với swap web-safe (`fontSwaps:[{from:'Be Vietnam Pro',to:'Arial'}]` — Arial phủ tiếng Việt). Standalone HTML **embed** font (`@font-face` inline từ `styles.css`), nên luôn trung thành offline (Th7 2026).
 
 ## Accessibility (base/a11y.css + component ARIA)