@cyberskill/design 1.2.0 → 1.3.8

package/docs/release-runbook.md

@@ -0,0 +1,78 @@
+# Release runbook (authoritative)
+
+One page for how a release happens and how to tell it worked. Consolidates areas 21/23. Related detail: `docs/ci-cd.md`, `docs/deploy.md`, `docs/decisions.md` §7 / §13.
+
+## Trigger
+
+| Path | When |
+|------|------|
+| **Auto** | Push to `main` with Conventional Commits → `version.yml` bumps `VERSION`, stamps artifacts, commits `chore(release): X.Y.Z`, tags `vX.Y.Z` |
+| **Force** | `Release-As: X.Y.Z` trailer on a commit, or `workflow_dispatch` on `version.yml` with a level |
+| **Manual publish** | `workflow_dispatch` on `npm-publish.yml` (also runs on `v*` tags) |
+
+Never push/deploy/merge without an explicit operator instruction when operating as an agent.
+
+## What fires (happy path)
+
+```
+main push (feat/fix/…)
+  → version.yml  (bump VERSION + stamps + bundle + tag vX.Y.Z)
+  → npm-publish.yml  (OIDC Trusted Publishing; post-publish version + dist-tags.latest)
+  → Vercel (host)  (build:site → .vercel-static; headers from vercel.json)
+  → sbom.yml on tag  (CycloneDX artifact)
+```
+
+Scorecard runs on a weekly schedule + `main` pushes (`.github/workflows/scorecard.yml`).
+
+## Success signals
+
+1. GitHub Actions: `version` green; `npm-publish` green (**not** soft-skip) with registry presence **and** `dist-tags.latest === VERSION` (FIND-094).
+2. `npm view @cyberskill/design version` **and** `npm view @cyberskill/design dist-tags.latest` both equal root `VERSION`.
+3. `npm-hello-smoke` green on the tip (fail-closed registry install of that VERSION — FIND-087).
+4. Production: `/` is Storybook; `/VERSION` is plain semver; `/_audit/run.html` fast board green.
+5. Artifacts: `cyclonedx-sbom` on the tag run; Scorecard SARIF on Security / Actions artifacts.
+6. Post-deploy Health protocol in `docs/deploy.md`.
+
+## Historical unpublished tags (do not backfill)
+
+| Tag | Status | Operator action |
+|-----|--------|-----------------|
+| `v1.2.1` | Historical git tag; **not** published to npm as `latest` | Leave unpublished |
+| `v1.3.0` | Historical git tag; **not** published to npm as `latest` | Leave unpublished |
+| `v1.3.1` (current tip) | **Publish target** when operator instructs | Publish **only** `1.3.1` as `dist-tags.latest` |
+
+Do **not** publish `1.2.1` or `1.3.0` to close registry drift — close FIND-102 by publishing **`1.3.1` only** (operator-gated). npm `latest` may still read `1.2.0` until that publish lands.
+
+## Failure / recovery
+
+| Symptom | Action |
+|---------|--------|
+| `npm-publish` 403 / EOTP / ENEEDAUTH / 404 / 402 on tag or `workflow_dispatch` | **Fail-closed.** Fix Trusted Publisher binding for repo **`cyberskill-official/design`** (FIND-088) / 2FA / OIDC; re-run on the tag. Soft-skip must **not** report success for these. |
+| Soft-skip `already_published` | Expected no-op — confirm registry; do not treat as success if you intended a new version. |
+| Soft-skip `missing_secrets` | Expected only **off** GitHub Actions (local). On GHA release this is a hard fail. |
+| `version.yml` push soft-warn | Set `PUSH_TOKEN` or allow Actions to push past branch protection (see `docs/ci-cd.md`). |
+| `npm-hello-smoke` red (VERSION missing on registry) | Expected until publish lands (FIND-087). Follow **Incident: unpublished release** below — do not set `NPM_HELLO_ALLOW_LOCAL_PACK` on the canonical repo. |
+| Nightly `design-system-gates` red | GitHub notifies the default workflow subscribers; see “Scheduled-job alerting” below. Re-run `workflow_dispatch`. |
+| Partial Vercel deploy | Re-run deploy; follow Health re-run protocol; do not invent live header claims without `curl -sSI`. |
+
+## Incident: unpublished release (FIND-100 / FIND-101 / FIND-107)
+
+Use when git/`VERSION`/site are ahead of npm `dist-tags.latest` (e.g. tip `1.3.1`, registry still `1.2.0`).
+
+1. **Confirm skew** — `cat VERSION`; `npm view @cyberskill/design version`; `npm view @cyberskill/design dist-tags.latest`; note git tags `v1.2.1` / `v1.3.0` / `v1.3.1` as historical vs publish target.
+2. **Do not** treat a green `npm-publish` soft-skip (or a green `npm-hello` local-pack proof) as evidence the version is public — smoke is fail-closed; publish auth errors hard-fail on GHA.
+3. **Fix Trusted Publisher** if needed — npm package settings must list org/repo **`cyberskill-official/design`**, workflow **`npm-publish.yml`**, and the correct environment (FIND-088). Classic `NPM_TOKEN` is disallowed. CI uses a clean OIDC userconfig (no empty `_authToken` from `actions/setup-node`) so Trusted Publishing can exchange the GitHub OIDC token.
+4. **Operator-gated publish** — only after an explicit instruction: re-run `npm-publish.yml` on tag **`v1.3.1`** (or `workflow_dispatch` at that tip). Publish target is **`1.3.1` only**; do not backfill `1.2.1` / `1.3.0`.
+5. **Verify** — `npm view @cyberskill/design@1.3.1 version` and `dist-tags.latest` both `1.3.1`; re-run `npm-hello-smoke` (or wait for the next gates run) to green.
+6. **Rollback / deprecate (if a bad version reached `latest`)** — `npm deprecate @cyberskill/design@<bad> "…"` and/or `npm dist-tag add @cyberskill/design@<good> latest`. npm does not allow unpublishing recent public versions in the normal case — prefer deprecate + retag `latest`. Site/Vercel rollback is independent (`docs/deploy.md`).
+
+## Scheduled-job alerting (area 27)
+
+- Nightly cron `0 3 * * *` on `design-system-gates.yml`.
+- On schedule failure the workflow’s `notify-schedule-failure` job (`needs` every scheduled job — FIND-108) emits an Actions error annotation and fails when `contains(needs.*.result, 'failure')`, which triggers **GitHub’s native workflow-failure email** to repository watchers / the last actor as configured under Settings → Notifications.
+- Optional: add a repo Actions variable / secret for Slack webhook later; do not require it for green CI.
+- Operators should watch the Actions badge in `docs/ci-cd.md` and enable “Actions” notification for failed workflows.
+
+## Product vs CyberOS
+
+See `docs/decisions.md` §13. The npm package and portable tree are the product; `.cyberos/` is orchestration only.

package/docs/sync.md

@@ -1,6 +1,6 @@
 # Repo ↔ Claude Design — round-trip fidelity & two-way sync
 
-The GitHub repo (`cyberskill-official/design-system`) is the **source of truth**. Claude Design sessions are ephemeral project filesystems — this doc is how they stay in sync without losing work.
+The GitHub repo (`cyberskill-official/design`) is the **source of truth**. Claude Design sessions are ephemeral project filesystems — this doc is how they stay in sync without losing work.
 
 ## Does the repo restore the full system intact?
 

package/docs/vi/ci-cd.md

@@ -6,24 +6,25 @@
 
 ## Badge
 
-[![Design System Gates](https://github.com/cyberskill-official/design-system/actions/workflows/design-system-gates.yml/badge.svg)](https://github.com/cyberskill-official/design-system/actions/workflows/design-system-gates.yml)
+[![Design System Gates](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml/badge.svg)](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml)
 
 ## Những gì đã nối (`.github/workflows/design-system-gates.yml`)
 
 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` (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).
+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), `scripts/generate-design-md.mjs --check` (`DESIGN.md` gốc byte-equals regeneration), `scripts/flatten-styles.mjs --check` + `scripts/generate-contrast-report.mjs --check` (FIND-026), và `_audit/ci/check-manifest-coverage.mjs` (FIND-078).
+4b. **`storybook-build`** — `npm run build:storybook` rồi `test-storybook-freshness.mjs --require` (FIND-074 / FIND-075). Storybook gãy sẽ fail CI trước deploy.
 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. **`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`.
+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 (freshness bắt buộc trên PR). Chỉ job song sinh push/schedule/thủ công giữ `contents: write` và có thể auto-commit với `PUSH_TOKEN` (hoặc `github.token`). Auto-commit **không** dùng `[skip ci]` — tip được push phải chạy lại bảng gate (FIND-021 / TASK-IMP-008); lần chạy thứ hai deterministic là no-op.
+10. **`npm-hello-smoke`** — chứng minh consumer registry cho `@cyberskill/design@$VERSION` (**fail-closed**, FIND-087): `examples/npm-hello` → `npm install` từ registry + `npm run smoke`. Nếu VERSION **không** có trên registry, job **fail** (không soft-skip pack proof trên `cyberskill-official/design`). Fork chỉ được opt-in pack local khi đặt biến repo **`NPM_HELLO_ALLOW_LOCAL_PACK=true`**. 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 **`version`** (`.github/workflows/version.yml`): mỗi push lên `main`, bump `VERSION` theo Conventional Commits + stamp artifact; commit `chore(release): X.Y.Z`, push, và tạo tag `vX.Y.Z`. Bỏ qua chính commit release (an toàn vòng lặp). Owner có thể force level qua `workflow_dispatch` hoặc trailer `Release-As:`. Cần `contents: write` (cùng pattern `DS_PUSH_TOKEN` như `regenerate-tokens-push` nếu branch protection chặn `github.token`).
+Workflow riêng **`version`** (`.github/workflows/version.yml`): mỗi push lên `main`, bump `VERSION` theo Conventional Commits + stamp artifact; rồi regen natives/provenance hash và `npm run build:bundle` để tip sạch gate; commit `chore(release): X.Y.Z`, push, và tạo tag `vX.Y.Z`. Bỏ qua chính commit release (an toàn vòng lặp). Owner có thể force level qua `workflow_dispatch` hoặc trailer `Release-As:`. Cần `contents: write`. Checkout dùng `secrets.PUSH_TOKEN || github.token` — nếu branch protection yêu cầu status checks (hoặc chặn `github.token`), đặt repository secret **`PUSH_TOKEN`** (fine-grained PAT, Contents: Read and write); không thì bump tính được nhưng push soft-warn và không land.
 
-Workflow riêng **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + tag `v*` (thường do `version.yml` tạo); 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. 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 **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + tag `v*` (thường do `version.yml` tạo); 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 chỉ **`already_published`** và `missing_secrets` thật sự **ngoài GHA**. Trên tag / `workflow_dispatch`, **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** **fail closed**. Sau publish assert `npm view @cyberskill/design@VERSION` **và** `dist-tags.latest === VERSION` (FIND-094). License **UNLICENSED**. Trusted Publisher trên npmjs phải khớp filename workflow `npm-publish.yml` cho repo **`cyberskill-official/design`** (FIND-088). 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`.
 
@@ -42,16 +43,18 @@ Node **22** trên runner (tránh deprecation action Node 20). Cache key Playwrig
 
 ## Quyền auto-commit token
 
-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.
+`regenerate-tokens-push` và `version.yml` yêu cầu `permissions: contents: write` và checkout với `secrets.PUSH_TOKEN || github.token`. Job song sinh pull request `regenerate-tokens` giữ `contents: read` và không bao giờ push. Nếu ruleset/branch protection yêu cầu status checks trước khi push (hoặc khóa default Actions token), đặt repository secret **`PUSH_TOKEN`** (fine-grained PAT, Contents: Read and write trên repo này) hoặc cho phép GitHub Actions bypass ruleset. Không có thì bot push soft-warn và exit 0; drift nội dung vẫn hard-fail qua `token-provenance` / fast-gates / `node-prechecks`.
 
-## Branch protection (khuyến nghị)
+## Branch protection (khuyến nghị) — NV-18.1 ngoài repo
 
-Require status checks trên `main` trước merge:
+**NV-18.1 (assessment):** check nào **bắt buộc** trước khi merge `main`, admin có bị ràng buộc không, và CODEOWNERS / review / conversation-resolution có được enforce — đều là **cài đặt GitHub, không nằm trong repo**. Trạng thái quan sát từ clone: **không biết / xác nhận ngoài băng**. Không bịa giá trị ruleset live từ YAML workflow.
+
+**Khuyến nghị** (chỉ tài liệu — áp dụng trong GitHub Settings → Branches / Rulesets, hoặc `gh api` admin):
 
 - `fast-gates`
 - `docs-consistency-blocker`
 
-Tùy chọn: `whole-set-audits` (dài). Cấu hình dưới repo **Settings → Branches** hoặc qua `gh api` (admin).
+Tùy chọn: `whole-set-audits` (dài).
 
 ## Chạy local
 
@@ -74,11 +77,11 @@ node _audit/ci/generate-native-tokens.mjs
 - **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** — 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** — Trusted Publishing (OIDC) trên `npm-publish.yml`; soft-skip khi auth / conflict (Quyết định 1C).
+- **npm publish** — Trusted Publishing (OIDC) trên `npm-publish.yml`; soft-skip khi `already_published` / `missing_secrets` ngoài GHA; trên GHA release **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** fail closed + kiểm version **và** `dist-tags.latest` sau publish (Quyết định §7 / FIND-020 / FIND-094).
 - **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).
+- **npm-hello registry smoke** — **fail-closed** (`examples/npm-hello` → install registry + `npm run smoke`); thiếu `@cyberskill/design@$VERSION` thì job fail (FIND-087). Pack proof local chỉ opt-in trên fork (`NPM_HELLO_ALLOW_LOCAL_PACK`).
 
-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.
+Job `figma-variables-push` hay `code-connect` vẫn exit 0 khi soft-skip (Quyết định 1C), nhưng FIND-095 làm outcome hiện trên trang run công khai qua `$GITHUB_STEP_SUMMARY` kèm annotation riêng (`::error::` trên schedule/main, `::warning::` nơi khác) — soft-skip không còn xanh im lặng giống publish thật. Report artifact (`figma-push-report.json` / `code-connect-report.json`) vẫn mang chi tiết.
 
 ## Soft-skip dry-run (local)
 

package/docs/vi/consumer-grant.md

@@ -19,10 +19,13 @@ CyberSkill cấp cho **CyberSkill** (công ty và các team kỹ thuật sản p
 
 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ế).
 
+**Ngoại lệ bên thứ ba:** font OFL trong `fonts/`, runtime MIT trong `_vendor/`, và các asset liệt kê ở `THIRD-PARTY-NOTICES.md` giữ license **upstream**. Khẳng định UNLICENSED và grant này **không** thay thế các điều khoản đó; người redistribute phải tuân `fonts/OFL.txt` và file notices.
+
 ## 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.
+- **Notices bên thứ ba:** xem `THIRD-PARTY-NOTICES.md` và `fonts/OFL.txt` ở root.
 - 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`.
 

package/docs/vi/consuming.md

@@ -54,7 +54,7 @@ import { Button, TextField } from "@cyberskill/design";
 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.
+Thêm `transpilePackages: ["@cyberskill/design"]` trong Next.js (JSX ship dạng source). Entry mặc định (`_esm/react.mjs`) là **barrel `"use client"`** — Server Component App Router có thể `import { Button } from "@cyberskill/design"` mà không cần shim client từng import. 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[]`.
 
@@ -64,11 +64,11 @@ Thêm `transpilePackages: ["@cyberskill/design"]` trong Next.js (JSX ship dạng
 
 ## Adopt (hai đường, cộng shortcut module)
 
-**1. Static / prototype / mock — link stylesheet.** Copy `styles.css` (+ `tokens/`, `base/`, `fonts/` mà nó `@import`, hoặc serve cả cây) và link; bạn có mọi token `--cs-*`, class component `.cs-*`, và bề mặt Liquid Glass. Compose bằng class (xem `templates/kitchen-sink.html`). Copy mọi asset bạn tham chiếu từ `assets/`.
+**1. Static / prototype / mock — link stylesheet.** Cho **static production**, link bản flatten `dist/styles.min.css` (cũng `@cyberskill/design/styles.min.css`) — một file, không waterfall `@import`. Giữ `styles.css` (+ `tokens/`, `base/`, `fonts/` mà nó `@import`) làm đường source/dev dễ đọc, hoặc serve cả cây. Cách nào cũng có mọi token `--cs-*`, class component `.cs-*`, và bề mặt Liquid Glass. Compose bằng class (xem `templates/kitchen-sink.html` và `examples/static-hello/`). Copy mọi asset bạn tham chiếu từ `assets/`.
 
-**2. React production — nạp compiled bundle.** Link `styles.css` và `<script src="_ds_bundle.js">`, rồi đọc component từ namespace. **Resolve theo prefix, không hardcode:** bundle expose `window.CyberSkillDesignSystem_<projectId>`, và hậu tố 6-hex đó do compiler gán và **đổi khi import vào project khác**:
+**2. React production — nạp compiled bundle.** Link `dist/styles.min.css` (hoặc `styles.css` khi dev) và `<script src="_ds_bundle.js">`, rồi đọc component từ namespace. **Resolve theo prefix, không hardcode:** bundle expose `window.CyberSkillDesignSystem_<projectId>`, và hậu tố 6-hex đó do compiler gán và **đổi khi import vào project khác**:
 ```html
-<link rel="stylesheet" href="<path>/styles.css">
+<link rel="stylesheet" href="<path>/dist/styles.min.css">
 <script src="<path>/_ds_bundle.js"></script>
 <script>
  const CS = window[Object.keys(window).find(k => /^CyberSkillDesignSystem_/.test(k))];
@@ -76,7 +76,7 @@ Thêm `transpilePackages: ["@cyberskill/design"]` trong Next.js (JSX ship dạng
 </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. 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`.
+**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`). File generated bắt đầu bằng `"use client"` để consumer App Router / RSC import component tương tác trực tiếp. 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 (`styles.min.css` khuyến nghị cho sheet static production). 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`).
 
@@ -84,7 +84,7 @@ Thêm `transpilePackages: ["@cyberskill/design"]` trong Next.js (JSX ship dạng
 
 **Token máy đọc được.** `tokens/tokens.json` + `tokens/tokens.js` (ESM) + `tokens/tokens.dtcg.json` (W3C DTCG, cho Tokens Studio/Style Dictionary) expose mọi token nhóm theo category + map theme/element — cho pipeline native/mobile/design-tool. **Native build ship sẵn** trong `tokens/native/` (SwiftUI `CSTokens.swift` · Compose `CSTokens.kt` · Flutter `cs_tokens.dart`) kèm `tokens/provenance.json` (release, source sha-256, quy tắc chuyển đổi, sha-256 từng target); gate `token-pipeline` giữ chúng khóa với nguồn DTCG.
 
-**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`.
+**HTML tĩnh / không React / không build tooling.** Link `dist/styles.min.css` (production) hoặc `styles.css` (source/dev) và compose bằng class `.cs-*` — catalog đầy đủ trong `templates/kitchen-sink.html`.
 
 **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.
 
@@ -92,7 +92,7 @@ Consumer bỏ qua `styles.css` để tự kiểm soát font loading (`cyberskill
 
 ## 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 đủ).
+Đặ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 · vi · liquid-glass` (vắng theme / style ≡ các mặc định đó; đặt `lang="en"` cho bề mặt EN). Bilingual: component resolve chuỗi từ `lang` (`lang="en"` trên mọi container → tiếng Anh đầy đủ; không đặt → fallback tiếng Việt trước).
 
 ## Nâng cấp
 

package/docs/vi/contrast-report.md

@@ -1,6 +1,6 @@
 # Báo cáo contrast — cặp elemental (APCA)
 
-Tạo 2026-07-27 · quét tại pin VERSION 1.1.1.
+Tạo · quét tại VERSION 1.3.8.
 
 **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.)
 
@@ -90,6 +90,84 @@ Pack được generate từ `tokens/element-seeds.json` (thang soft / middle / d
 
 **Failures: 0.** All text pairings pass Lc ≥ 60.
 
+## Element-pack link contrast (WCAG AA · body text)
+
+`--cs-color-link` is scored at **4.5:1** (regular-weight body). `--cs-color-text-accent` remains on the APCA Lc ≥ 60 bold-label floor above.
+| Scope | Pairing | fg / bg | Ratio | Verdict |
+|---|---|---|---|---|
+| tho · sand | link on white (body) | #7B6D4A / #FFFFFF | 5.09:1 | ✓ |
+| tho · sand | link on element page (body) | #7B6D4A / #FFFDF8 | 5.00:1 | ✓ |
+| tho · sand | link on tint (body) | #7B6D4A / #FBF7EA | 4.75:1 | ✓ |
+| tho · sand | link on raised cream (body) | #7B6D4A / #FBF4E9 | 4.66:1 | ✓ |
+| tho · sand | link on dark panel (body) | #F6EBCC / #221710 | 14.75:1 | ✓ |
+| tho · clay | link on white (body) | #201300 / #FFFFFF | 18.19:1 | ✓ |
+| tho · clay | link on element page (body) | #201300 / #FFFDF8 | 17.89:1 | ✓ |
+| tho · clay | link on tint (body) | #201300 / #FFF6E7 | 16.97:1 | ✓ |
+| tho · clay | link on raised cream (body) | #201300 / #FBF4E9 | 16.65:1 | ✓ |
+| tho · clay | link on dark panel (body) | #E4CDA8 / #221710 | 11.35:1 | ✓ |
+| hoa | link on white (body) | #A15E43 / #FFFFFF | 5.00:1 | ✓ |
+| hoa | link on element page (body) | #A15E43 / #FFFDF8 | 4.92:1 | ✓ |
+| hoa | link on tint (body) | #A15E43 / #FFF4F0 | 4.63:1 | ✓ |
+| hoa | link on raised cream (body) | #A15E43 / #FBF4E9 | 4.58:1 | ✓ |
+| hoa | link on dark panel (body) | #FED3C3 / #221710 | 12.79:1 | ✓ |
+| hoa · plasma | link on white (body) | #846B64 / #FFFFFF | 4.92:1 | ✓ |
+| hoa · plasma | link on element page (body) | #846B64 / #FFFDF8 | 4.84:1 | ✓ |
+| hoa · plasma | link on tint (body) | #846B64 / #FEF4F2 | 4.55:1 | ✓ |
+| hoa · plasma | link on raised cream (body) | #846B64 / #FBF4E9 | 4.50:1 | ✓ |
+| hoa · plasma | link on dark panel (body) | #FCE6DF / #221710 | 14.63:1 | ✓ |
+| hoa · lava | link on white (body) | #280D00 / #FFFFFF | 18.30:1 | ✓ |
+| hoa · lava | link on element page (body) | #280D00 / #FFFDF8 | 18.00:1 | ✓ |
+| hoa · lava | link on tint (body) | #280D00 / #FFF4EF | 16.94:1 | ✓ |
+| hoa · lava | link on raised cream (body) | #280D00 / #FBF4E9 | 16.74:1 | ✓ |
+| hoa · lava | link on dark panel (body) | #F8C4AA / #221710 | 11.24:1 | ✓ |
+| thuy | link on white (body) | #027B8B / #FFFFFF | 4.99:1 | ✓ |
+| thuy | link on element page (body) | #027B8B / #FFFDF8 | 4.91:1 | ✓ |
+| thuy | link on tint (body) | #027B8B / #E7FBFF | 4.67:1 | ✓ |
+| thuy | link on raised cream (body) | #027B8B / #FBF4E9 | 4.57:1 | ✓ |
+| thuy | link on dark panel (body) | #99EEFF / #221710 | 13.38:1 | ✓ |
+| thuy · mist | link on white (body) | #48787E / #FFFFFF | 4.93:1 | ✓ |
+| thuy · mist | link on element page (body) | #48787E / #FFFDF8 | 4.85:1 | ✓ |
+| thuy · mist | link on tint (body) | #48787E / #EBFAFC | 4.60:1 | ✓ |
+| thuy · mist | link on raised cream (body) | #48787E / #FBF4E9 | 4.51:1 | ✓ |
+| thuy · mist | link on dark panel (body) | #CDF4F9 / #221710 | 14.94:1 | ✓ |
+| thuy · ocean | link on white (body) | #011A21 / #FFFFFF | 17.93:1 | ✓ |
+| thuy · ocean | link on element page (body) | #011A21 / #FFFDF8 | 17.64:1 | ✓ |
+| thuy · ocean | link on tint (body) | #011A21 / #EAFAFF | 16.75:1 | ✓ |
+| thuy · ocean | link on raised cream (body) | #011A21 / #FBF4E9 | 16.41:1 | ✓ |
+| thuy · ocean | link on dark panel (body) | #ABD6E3 / #221710 | 11.23:1 | ✓ |
+| moc | link on white (body) | #517B13 / #FFFFFF | 5.01:1 | ✓ |
+| moc | link on element page (body) | #517B13 / #FFFDF8 | 4.93:1 | ✓ |
+| moc | link on tint (body) | #517B13 / #EFFCE3 | 4.70:1 | ✓ |
+| moc | link on raised cream (body) | #517B13 / #FBF4E9 | 4.58:1 | ✓ |
+| moc | link on dark panel (body) | #C5ED9C / #221710 | 13.33:1 | ✓ |
+| moc · bamboo | link on white (body) | #687451 / #FFFFFF | 4.99:1 | ✓ |
+| moc · bamboo | link on element page (body) | #687451 / #FFFDF8 | 4.91:1 | ✓ |
+| moc · bamboo | link on tint (body) | #687451 / #F4F9ED | 4.67:1 | ✓ |
+| moc · bamboo | link on raised cream (body) | #687451 / #FBF4E9 | 4.57:1 | ✓ |
+| moc · bamboo | link on dark panel (body) | #E5F1D2 / #221710 | 14.89:1 | ✓ |
+| moc · forest | link on white (body) | #051D00 / #FFFFFF | 17.76:1 | ✓ |
+| moc · forest | link on element page (body) | #051D00 / #FFFDF8 | 17.47:1 | ✓ |
+| moc · forest | link on tint (body) | #051D00 / #ECFDE7 | 16.72:1 | ✓ |
+| moc · forest | link on raised cream (body) | #051D00 / #FBF4E9 | 16.26:1 | ✓ |
+| moc · forest | link on dark panel (body) | #B0D8A3 / #221710 | 11.02:1 | ✓ |
+| kim | link on white (body) | #966700 / #FFFFFF | 4.96:1 | ✓ |
+| kim | link on element page (body) | #966700 / #FFFDF8 | 4.88:1 | ✓ |
+| kim | link on tint (body) | #966700 / #FFF5E7 | 4.59:1 | ✓ |
+| kim | link on raised cream (body) | #966700 / #FBF4E9 | 4.54:1 | ✓ |
+| kim | link on dark panel (body) | #FDD89F / #221710 | 12.94:1 | ✓ |
+| kim · titanium | link on white (body) | #826D54 / #FFFFFF | 4.92:1 | ✓ |
+| kim · titanium | link on element page (body) | #826D54 / #FFFDF8 | 4.84:1 | ✓ |
+| kim · titanium | link on tint (body) | #826D54 / #FDF5ED | 4.56:1 | ✓ |
+| kim · titanium | link on raised cream (body) | #826D54 / #FBF4E9 | 4.51:1 | ✓ |
+| kim · titanium | link on dark panel (body) | #FBE8D2 / #221710 | 14.67:1 | ✓ |
+| kim · steel | link on white (body) | #1F1400 / #FFFFFF | 18.13:1 | ✓ |
+| kim · steel | link on element page (body) | #1F1400 / #FFFDF8 | 17.83:1 | ✓ |
+| kim · steel | link on tint (body) | #1F1400 / #FEF6E7 | 16.88:1 | ✓ |
+| kim · steel | link on raised cream (body) | #1F1400 / #FBF4E9 | 16.59:1 | ✓ |
+| kim · steel | link on dark panel (body) | #DFCBA5 / #221710 | 11.04:1 | ✓ |
+
+**Link failures: 0.**
+
 ## Dark pack APCA floors (gate twin)
 
 Targets match `_audit/apca-dark-preview.html`: bright ≥ 75 · accent ≥ 60 · on/strong ≥ 75 · ink-on-tint ≥ 75.

package/docs/vi/conventions.md

@@ -16,11 +16,11 @@ Mọi bề mặt render resolve bốn scope trực giao — không bao giờ mã
 | **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` |
 
-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.
+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, chỉ báo focus ghép (contour text-primary + halo ochre), 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`).
+- Tokens: `--cs-<layer>-<role>[-<state>]` (`--cs-color-text-muted`). Layer role element: `--cs-accent-*` (hợp đồng 10-token gồm `--cs-accent-on-strong` — xem header `tokens/elements.css`).
 
 - Classes: `.cs-<block>[-<part>][--modifier]`. Data attributes: `data-theme`, `data-cs-element`, `data-cs-variant`, `data-cs-style`.
 
@@ -36,7 +36,7 @@ Pack Style duy nhất hiện nay là **liquid-glass**. Bất biến dưới mọ
 
 **Template mới** — `templates/<slug>/<Slug>.dc.html` với `<!-- @template name description -->` đầu tiên; `ds-base.js` giữ single-entry (`styles.css` thôi — rebind một dòng đã validate end-to-end Th7 2026 từ path sâu hơn; scaffold test đã gỡ) và publish alias độc lập-id `window.CyberSkillDS` lúc bundle load, nên mount DS component qua `component-from-global-scope="CyberSkillDS.…"` — **không bao giờ** hậu tố `CyberSkillDesignSystem_<projectId>` hardcode (đổi khi re-import; enforce bởi `_audit/namespace-portability.html`); chỉ inline styles; 1–3 tweaks (không plain copy/color — in-place editing phủ những cái đó); printable docs thêm khối print `@page` + `.cs-desk`/`.cs-sheet` và **không** mang dark tweak (print chỉ light).
 
-**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.
+**Element variant mới** — ở trong envelope oklch của element; đặt 10 token hợp đồng `--cs-accent-*` (gồm `--cs-accent-on-strong` ≥4.5:1 trên `-strong`) cộng `--cs-color-text-accent`/`--cs-color-link` (APCA-check cả hai); aurora wash kế thừa từ element qua `.cs-aurora-wash` (chỉ override class rule nếu variant thật sự cần ảnh riêng); đối tác gradient (`grad-b`) phải theo Tương sinh.
 
 **Ship check** — 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). Pin theo `VERSION` (auto-bump trên `main`).
 
@@ -52,7 +52,7 @@ Pack Style duy nhất hiện nay là **liquid-glass**. Bất biến dưới mọ
 
 - **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).
+- 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 — gồm skip link và eyebrow loại tài liệu (FIND-125). Chuỗi catalog `<title>` / `@template name` giữ tiếng Anh cho chỉ mục template, không phải chrome chế độ ngôn ngữ; `_audit/template-lang-parity.html` che chúng khi quét lexicon rò EN (Th7 2026; follow-up FIND-125).
 
 - **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).
 
@@ -70,9 +70,22 @@ Mọi template export; đường đúng phụ thuộc archetype. Mọi đường
 
 **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).
 
+## Trạng thái dữ liệu bất đồng bộ (FIND-020 — pattern mỏng)
+
+Bề mặt collection sở hữu một fetch phải phân biệt **loading · error · empty · idle-có-dữ-liệu**. Không render thông báo trống trong lúc request đang chạy.
+
+| Trạng thái | Ghép | Ghi chú |
+|---|---|---|
+| **loading** | `Skeleton` (hàng bảng / dòng) + chuỗi status lịch sự | `aria-busy` trên vùng; giữ header cột khi có thể |
+| **error** | `Result status="error"` (hoặc `errorState` tùy chỉnh) | `role="alert"`; host cung cấp thử lại |
+| **empty** | `emptyState` / `EmptyState` | Chỉ sau phản hồi idle thành công với zero rows |
+| **idle** | Các hàng bình thường | Mặc định — bỏ `state` cho specimen tĩnh |
+
+**API tham chiếu:** `DataTable` nhận `state?: "idle" \| "loading" \| "error"` cùng `loadingState` / `errorState` / `loadingRows` tùy chọn. Các component collection khác (`DataGrid`, `TreeTable`, …) nên theo cùng triad khi có async ownership — không invent API loading song song từng bề mặt. Tác vụ dài không dạng bảng vẫn dùng `Spinner` (`role="status"`) hoặc `ProgressBar` với `aria-label` thật; ghép `Skeleton` trang trí (`aria-hidden`) với chuỗi status live.
+
 ## Accessibility (base/a11y.css + component ARIA)
 
-- **Focus rings có hệ thống** — vòng ochre global `:where(:focus-visible)` trong `base/reset.css`, cộng vòng ochre 3px theo component (`components/forms/navigation/controls`). Không bao giờ đặt `outline: none` trên state `:focus-visible` mà không thay vòng (regression menu-item, đã sửa Th7 2026). Soft glow 5px trong `interaction.css` chồng lên vòng 3px, không thay thế.
+- **Focus rings có hệ thống** — global `:where(:focus-visible)` trong `base/reset.css` là chỉ báo **ghép**: contour 2px `text-primary` (≥3:1 trên light và dark) cộng halo ochre 5px. Control wrapper (`SearchField`, `NumberField`, `PromptInput`, `Terminal`, `CommandPalette`) lặp lại qua `:focus-within`. Không bao giờ đặt `outline: none` trên control focusable mà không có vòng thay thế/wrapper.
 
 - **Touch targets** — `base/a11y.css` đảm bảo 44px trên `@media (pointer: coarse)` (tabs, pagination, menu items, stepper, checkbox/radio; segmented 40px trong track đã pad). Mật độ chuột desktop được giữ. `pointer: coarse` dùng có chủ đích thay breakpoint chiều rộng — touch laptop ở 1280px vẫn cần 44px. Button mang khối coarse riêng trong `components.css`.
 

package/docs/vi/decisions.md

@@ -53,7 +53,7 @@ Giữ plan Figma hiện tại. Variables REST API chỉ Enterprise — job ghi *
 **Trạng thái: LAUNCH `@cyberskill/design@1.1.0`; pin theo `VERSION` (auto-bump trên main từ Th8 2026); CI publish dùng npm Trusted Publishing; token bị cấm** (Th7 2026; LAUNCH 2026-07-27)
 
 - `package.json` là `private: false`; tên package **`@cyberskill/design`** (`publishConfig.access: public`); `repository.url` khớp repo GitHub này cho provenance.
-- Workflow `.github/workflows/npm-publish.yml`: `id-token: write` + runner GitHub-hosted; **không** đặt `NPM_TOKEN` / `NODE_AUTH_TOKEN` trên bước publish (OIDC). Trusted Publisher trên npm phải liệt kê filename workflow **`npm-publish.yml`** cho `cyberskill-official/design-system`. Soft-skip khi auth / 403 / 404 / EOTP / conflict phiên bản.
+- Workflow `.github/workflows/npm-publish.yml`: `id-token: write` + runner GitHub-hosted; **không** đặt `NPM_TOKEN` / `NODE_AUTH_TOKEN` trên bước publish (OIDC). Trusted Publisher trên npm phải liệt kê filename workflow **`npm-publish.yml`** cho `cyberskill-official/design` (FIND-088). Soft-skip chỉ no-op mong đợi (`already_published` / EPUBLISHCONFLICT, và `missing_secrets` thật sự ngoài GHA). Trên GHA tag / `workflow_dispatch`, **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** fail job; publish thành công được khóa bởi `npm view @cyberskill/design@VERSION` **và** `dist-tags.latest === VERSION` (FIND-020 / FIND-094).
 - **Publishing access** trên npmjs: **Require two-factor authentication and disallow tokens** (Trusted Publishing OIDC vẫn hoạt động; token publish classic / granular bị từ chối). Secret `NPM_TOKEN` dài hạn đã thu hồi.
 - License giữ **UNLICENSED**; phiên bản theo root `VERSION`. Dùng đã duyệt ghi tại **`docs/consumer-grant.md`** (sản phẩm portfolio CyberSkill). Cài từ registry một mình không phải license công khai.
 
@@ -100,7 +100,7 @@ Theo dõi vận hành — không phải marketing sản phẩm, không phải ba
 
 ~~4. Đường consumer registry đầu tiên~~ — **xong** (Th7 2026): `examples/npm-hello/` cài `@cyberskill/design` cho identity **Lumi** đã khóa; ghi trong `docs/consuming.md` (+ VI) và `docs/release-notes.md`. Nay target **1.1.1** post-LAUNCH.
 
-5. **Drift native + element-pack trên PR là fail-closed** (Th7 2026) — `regenerate-tokens` chạy read-only trên pull request và exit 1 thay vì push; chỉ `regenerate-tokens-push` (main / schedule / thủ công) giữ `contents: write`. Khi PR fail, chạy `npm run tokens:elements && node _audit/ci/generate-native-tokens.mjs` rồi commit packs + natives. Xem `docs/ci-cd.md`.
+5. **Drift native + element-pack trên PR là fail-closed** (Th7 2026; FIND-021 re-gate Th8 2026) — `regenerate-tokens` chạy read-only trên pull request và exit 1 thay vì push; chỉ `regenerate-tokens-push` (main / schedule / thủ công) giữ `contents: write`. Khi PR fail, chạy `npm run tokens:elements && node _audit/ci/generate-native-tokens.mjs` rồi commit packs + natives. Auto-commit từ `regenerate-tokens-push` **không** được dùng `[skip ci]` để tip chạy lại bảng gate (TASK-IMP-008); freshness fail-closed trên PR vẫn là đường chính cho contributor. Thực tế required-check branch protection là NV-18.1 (ngoài repo). Xem `docs/ci-cd.md`.
 
 6. **Shadcn gap / Wave 2** (Th7 2026) — CyberSkill đã phủ ~53/62 primitive shadcn dưới dạng CS-native (forms / overlays / nav / data). Đã ship: pilot `ScrollArea`, `Collapsible`, `AspectRatio`; Wave 2 `AlertDialog` (vs Popconfirm), `Item` row primitive, `NativeSelect`. Phần còn lại của shadcn là non-port có chủ đích (block, Tailwind, Radix CLI). **Không** port những thứ đó — map pattern sang `templates/` + `ui_kits/` hiện có.
 
@@ -112,6 +112,43 @@ Theo dõi vận hành — không phải marketing sản phẩm, không phải ba
 
 Storybook `FullMatrix` bắt buộc khi public primary có ≥1 trong {size enums, variant enums, state keys} (sàn contract ≥28 story). Schema sidecar đã đủ cho template content-hole; template chỉ-axis bỏ qua theo thiết kế. Xem `docs/quality-gates.md` và `docs/storybook.md`.
 
+## 11. Giấy tờ audit — lưu trữ, không xóa
+
+**Lựa chọn owner: archive-don't-delete** (Th8 2026; TASK-IMP-001 / assessment FIND-001)
+
+- Artifact audit UX / AT / chất lượng đã đóng MUST còn tái dựng được từ clone mới. Ưu tiên `_audit/archive/` và/hoặc `docs/audits/` thay vì xóa im lặng.
+- Commit `8646dbf` đã xóa plan UX audit 8/8, AT matrix, README archive, và `TASK-UX-AUDIT-20260808` “không để lại bản ghi vĩnh viễn.” Nội dung được khôi phục tại `docs/audits/ux-audit-2026-08-08/` (kèm pointer `_audit/archive/ux-audit-2026-08-08/`). Các quyết định D1–D6 lịch sử trong plan đã khôi phục **không** ủy quyền xóa audit trail trong tương lai.
+- Chỉnh status-feed / ledger để che công việc audit đã làm nên tránh; nếu commit phải ledger-exempt, ghi exemption và đường dẫn archive trong cùng change.
+- Claim cần provenance (ví dụ “AT complete”, “lawyer-validated”) đòi bản ghi có ngày trong cây hoặc mục quyết định tường minh — không chỉ attestation miệng.
+
+## 12. Kế hoạch tiến hóa 12 tháng — trạng thái adoption
+
+**Lựa chọn owner: partially superseded (gần); giữ plan làm tham chiếu dài hạn** (Th8 2026; TASK-IMP-001 / assessment FIND-002)
+
+Nguồn: `docs/plans/cyberskill-design-system-audit-and-12-month-evolution-plan.md` (ngày audit 2026-07-28). PLAN `task-author` trước đó đã APPROVED (manifest `docs/tasks/.workflow/task-author.design-system-evolution.manifest.json`) nhưng hầu hết artefact chưa land vào `docs/tasks/`.
+
+| Tầm | Trạng thái | Ghi chú |
+|-----|------------|---------|
+| Assessment Phases 0–2 (tập con FIND-001…025) | **Adopted** — hàng đợi improvement CyberOS đang chạy | `TASK-IMP-001`…`TASK-IMP-008` trong `docs/tasks/improvement/`; index `docs/tasks/BACKLOG.md` |
+| Materialize đủ phase 0–6 của plan 12 tháng | **Deferred** | Không tự bung artefact PENDING trong manifest cho tới khi operator triage với tip `1.2.1` / hậu assessment |
+| Việc đã ship ngoài backlog (vd. commit remediation UX 8/8) | **Superseded** với tư cách task sống | Bằng chứng ở `docs/audits/ux-audit-2026-08-08/` + git history; không mở lại trùng trừ khi có finding mới |
+
+Phases 3–5 của **roadmap assessment** (RSC `"use client"`, APG Rating/Tree/Toolbar, CSP, SBOM, …) vẫn là follow-on hoãn — chưa author trong tranche này trừ khi operator yêu cầu.
+
+## 13. Ranh giới Product vs CyberOS
+
+**Lựa chọn owner: hàng rào tường minh** (Th8 2026; assessment area 28 / TASK-IMP-020)
+
+| Lớp | Ship tới consumer? | Nằm ở đâu | Mục đích |
+|-------|---------------------|-------------|---------|
+| **Product design system** | Có — `@cyberskill/design`, cây portable (`styles.css`, `tokens/`, `components/`, `templates/`, gates `_audit/`, host Storybook) | root repo (không-`.cyberos`) | Token, component, template, kit, quality gate xác định |
+| **CyberOS orchestration** | Không (gitignored / agent kit cài được) | `.cyberos/`, `docs/tasks/`, BRAIN dưới `.cyberos/memory/` | Vòng đời task, cổng HITL, agent entry, workflow ship-tasks |
+
+Quy tắc:
+- Tiêu chí chấp nhận product không được đòi `.cyberos/` có mặt cho consumer hoặc cho `npm` publish.
+- Agent vận hành repo này theo `.cyberos/AGENT-ENTRY.md`; người ship DS theo `docs/release-runbook.md`.
+- Không chuyển token/component product vào `.cyberos/`; không publish orchestration CyberOS như một phần của gói npm.
+
 ## Cách đổi một quyết định
 
 Sửa dòng **Lựa chọn owner** tại đây. Người triển khai nối lại CI và docs liên quan trong cùng một change.

package/docs/vi/deploy.md

@@ -48,11 +48,15 @@ Nếu host dưới **domain khác**, đổi absolute URL trong các meta tag cho
 
 **Có Storybook tại `/`:** chạy `npm run build:site` trên host hoặc CI, rồi serve `.vercel-static/` làm webroot. Cấu hình cùng redirect như `vercel.json` (`/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/`) nếu host hỗ trợ.
 
-Ví dụ Nginx (`.vercel-static` làm `root`):
+Ví dụ Nginx (`.vercel-static` làm `root`) — **cùng security headers với `vercel.json`** (FIND-019):
+```nginx
 server {
   server_name design.cyberskill.world;
   root /var/www/design-system/.vercel-static;
   index index.html;
+  add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data: blob:; connect-src 'self'; frame-src 'self'; worker-src 'self' blob:; base-uri 'self'; form-action 'self'" always;
+  add_header X-Content-Type-Options "nosniff" always;
+  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
   location = /dashboard { return 301 /; }
   location = /dashboard/ { return 301 /; }
   location = /dashboard.html { return 301 /; }
@@ -60,8 +64,11 @@ server {
   location = /playground { return 301 /; }
   location /playground/ { return 301 /; }
 }
+```
 Path portable vẫn là file thật (`guidelines/atomic-view.html`, `_audit/run.html`, `styles.css`, v.v.). Storybook sở hữu `/` và `/index.html`.
 
+**Netlify / Cloudflare Pages / tương tự:** file `_headers` ở root (và `public/_headers`) mirror cùng ba header cho host đọc `_headers` kiểu Netlify. Giữ khớp `vercel.json`.
+
 ## Checklist sau deploy
 1. Mở `/` — xác nhận Storybook load (không 404, directory listing, hay shell dashboard cũ).
 2. Mở `/_audit/run.html` — để board chạy xong, xác nhận mọi fast gate pass trên bản *đã deploy* (CDN cache, MIME type, hoặc file thiếu có thể lộ ở đây dù check local sạch).
@@ -86,12 +93,16 @@ Sau mỗi deploy production:
 
 ## Ghi chú Content-Security-Policy
 
-Static hosting có thể ship CSP chặt. Allowance điển hình cho hệ thống này:
-- `script-src 'self' https://unpkg.com` nếu load React từ CDN cho Atomic View
-- `font-src 'self'`
+CSP chuẩn nằm trong `vercel.json` và được mirror ở `_headers` + snippet nginx ở trên (FIND-015 / FIND-019). Policy hiện tại:
+
+`default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data: blob:; connect-src 'self'; frame-src 'self'; worker-src 'self' blob:; base-uri 'self'; form-action 'self'`
 
-- `img-src 'self' data:`
-Ưu tiên self-host React cạnh `_ds_bundle.js` cho cài air-gapped.
+Lý do:
+- **Đã bỏ `unsafe-eval`** — React vendored local; Storybook static không cần `eval` toàn site.
+- **Đã bỏ CDN script/connect** (`unpkg.com`, `cdnjs.cloudflare.com`) — local-first React / `_ds_bundle.js`.
+- **Giữ `unsafe-inline`** — shell Storybook vẫn emit inline script/style; migrate nonce/hash là follow-on.
+- Ưu tiên self-host React cạnh `_ds_bundle.js` cho cài air-gapped.
+- Header thật trên production đã xác nhận 2026-08-09 qua `curl -sSI https://design.cyberskill.world/` (OQ-003 đóng — xem `docs/audits/nv-rendered-inrepo-2026-08-09.md`).
 
 ## OG đa domain