@cyberskill/design 1.0.0 → 1.1.1

package/docs/vi/benchmark-rubric.md

@@ -0,0 +1,46 @@
+# Rubric benchmark Design System
+
+Checklist tự kiểm khi tiến hóa CyberSkill Design System — chuẩn bên ngoài cộng rule CDS. Ghép với [`docs/vi/quality-gates.md`](quality-gates.md) (gate xác định) và [`docs/vi/design-styles.md`](design-styles.md) (hợp đồng màu Element).
+
+## Chuẩn bên ngoài
+
+| Lĩnh vực | Chuẩn / thực hành | Cách đo |
+|---|---|---|
+| Sàn a11y pháp lý | WCAG 2.2 AA contrast (4.5:1 chữ thường / 3:1 chữ lớn / UI non-text ≥ 3:1) | `contrast-guard`, theme-overflow, axe-smoke |
+| Đọc theo cảm nhận | APCA Bronze-style Lc (body ≥ 75, nhãn UI ≥ 60, lớn ≥ 45, non-text ≥ 15; dark max ~90) | `apca-dark-preview`, [`docs/vi/contrast-report.md`](contrast-report.md) |
+| Không gian màu | Ramp OKLCH ưu tiên luminance; giữ hue qua mode | `element-geometry` + `npm run tokens:elements` |
+| Kiến trúc token | W3C DTCG 2025.10 — primitive → semantic → component; leaf có `$type`; modifier đa chiều (theme × element) | `dtcg-typing`, token-format-parity, token-pipeline |
+| Theming hai mode | Cùng họ hue light↔dark; remap role (không đảo hết) | `element-geometry` hue-lock |
+| Audit dual-standard | Phân loại cặp: pass-both / fail-both / WCAG-only / APCA-only | Ghi trong workflow contrast-report sau đổi token |
+| An toàn gamut | Ưu tiên chroma sRGB-safe; clamp trước khi emit | Generator + geometry gate |
+
+## Rule CDS sở hữu
+
+| Rule | Thực thi |
+|---|---|
+| Trục = Theme × Element × Language × Style cho tới khi có Style Expansion Rule | `axis-guard` (Expression/Density đã nghỉ); doctrine trong design-styles |
+| Chữ không trên mid `-accent`; focus Ochre không remap; màu status không remap | Hợp đồng `elements.css` · contrast-report · conventions |
+| Một element mỗi bề mặt; gradient chỉ Tương sinh | Registry products · conventions |
+| Registry product→element khóa; UI kit trung thành Thổ | [`docs/vi/products.md`](products.md) |
+| Expansion Rule đủ + `_audit/run.html` xanh + docs EN·VI parity | CLAUDE.md · docs-consistency · docs-lang-parity |
+| VERSION **1.1.1** post-LAUNCH | version-stamp · docs-consistency |
+| Pack Element chỉ từ seed (30 bộ) | `element-geometry` · `tokens:elements` |
+
+## Checklist mở rộng style (`data-cs-style`)
+
+Sole pack hôm nay: **liquid-glass** (`tokens/styles.css`, gate `_audit/style-contract.html`). Khi thêm style pack ngoài liquid-glass:
+
+1. Overlay token **tiêu thụ** 9 role `--cs-accent-*` sẵn có (không invent pack Element song song).
+2. Specimen card + Storybook / Atomic View nếu style chọn được ở sản phẩm.
+3. Adoption template / kit chỉ khi cố ý — UI kit giữ Thổ trừ khi quyết định nói khác.
+4. Regen contrast nếu style remap nền chứa chữ.
+5. Expansion Rule grep enum mới qua templates, docs EN+VI, gates.
+6. Mở rộng allowlist style-contract; giữ `_audit/run.html` xanh.
+7. Ghi quyết định trong [`docs/vi/decisions.md`](decisions.md).
+
+## Cách chạy một lượt benchmark
+
+1. `npm run tokens:elements` (nếu đổi seed) → regen native → `node scripts/generate-contrast-report.mjs`
+2. Fast board: mở `_audit/run.html` (hoặc CI `fast-gates`) — mọi hard gate xanh, gồm **Element geometry**
+3. Whole-set Atomic View / Elements Geometry: đủ **30** bộ (soft/middle/deep × light/dark × năm element) — soft là pastel wash, middle đồng bộ cường độ giữa các element, deep rõ ràng tối hơn, role hài hòa, light↔dark giữ cùng họ hue. Gate geometry yêu cầu **cả** `minDeltaE` và `minDeltaL` (cộng L đơn điệu) từ `tokens/element-seeds.json`
+4. Chỉ sửa rubric này khi chuẩn hoặc doctrine CDS đổi — giữ EN·VI parity

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.1**; 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.1** 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:** đã LAUNCH ở **1.1.0**; pin hiện tại **1.1.1** (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.1**). License vẫn **UNLICENSED** — cài từ registry **không** tự cấp quyền redistribution. **LAUNCH là `@cyberskill/design@1.1.0`; pin hiện tại `@cyberskill/design@1.1.1` (publish qua tag `v1.1.1`).** 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.1
 ```
 
-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.1` 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.1**. 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.1.
 
-**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 |