@cyberskill/design 1.2.0 → 1.3.8

package/docs/vi/quality-gates.md

@@ -2,9 +2,9 @@
 
 Mọi quality gate deterministic trong hệ thống, nó assert gì, tiêu chí pass, hard hay advisory, và chạy ở đâu.
 
-**Gate chạy ở đâu.** *Fast board CI* = job `fast-gates` trong `.github/workflows/design-system-gates.yml`, serve repo và điều khiển `_audit/run.html` headless qua `_audit/ci/run-gates.mjs` (mọi push/PR + nightly + thủ công) — hàng board mới được nhận tự động. Hai gate thêm chạy standalone như *merge blocker* (job `docs-consistency-blocker`, qua `_audit/ci/run-single-gate.mjs`). *Whole-set CI* = job `whole-set-audits` (mọi push/PR + nightly — quyết định B của owner). *Unit test* = `npm run test:unit` trong job `unit-tests` (Node thuần, không trình duyệt). *Node pre-checks* = job `node-prechecks` (authority không trình duyệt: bundle freshness, DESIGN.md freshness) cộng job `token-provenance`. Mọi browser gate publish verdict global (`window.__*`) mà headless runner đọc.
+**Gate chạy ở đâu.** *Fast board CI* = job `fast-gates` trong `.github/workflows/design-system-gates.yml`, serve repo và điều khiển `_audit/run.html` headless qua `_audit/ci/run-gates.mjs` (mọi push/PR + nightly + thủ công) — hàng board mới được nhận tự động. Hai gate thêm chạy standalone như *merge blocker* (job `docs-consistency-blocker`, qua `_audit/ci/run-single-gate.mjs`). *Whole-set CI* = job `whole-set-audits` (mọi push/PR + nightly — quyết định B của owner). *Unit test* = `npm run test:unit` trong job `unit-tests` (Node thuần, không trình duyệt). *Node pre-checks* = job `node-prechecks` (authority không trình duyệt: bundle freshness, DESIGN.md freshness, styles.min.css + contrast-report freshness, manifest coverage) cộng job `token-provenance`. *Storybook CI* = job `storybook-build` (`build:storybook` + freshness `--require`). Mọi browser gate publish verdict global (`window.__*`) mà headless runner đọc.
 
-## Fast board — 39 gates trong `_audit/run.html`
+## Fast board — 40 gates trong `_audit/run.html`
 
 Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở rộng style): [`docs/vi/benchmark-rubric.md`](benchmark-rubric.md).
 
@@ -13,7 +13,8 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | Contrast guard | `_audit/contrast-guard.html` | Không base rule sơn umber trên bề mặt themeable mà thiếu dark override; mọi cặp text×surface semantic ghi điểm light và dark | 0 rule không shield và 0 cặp fail (`__contrastguard`) | Hard | Fast board CI |
 | Axes guard | `_audit/axis-guard.html` | Không live source đưa lại bề mặt sản phẩm Expression/Density đã nghỉ | 0 hit trên source index bởi manifest (`__axisguard`) | Hard | Fast board CI |
 | Manifest CSS paths | `_audit/manifest-css-guard.html` | Mọi entry `globalCssPaths` của `_ds_manifest.json` tồn tại như raw CSS; mọi `@import` của `styles.css` được liệt kê | 0 thiếu / 0 chưa liệt kê (`__cssguard`) | Hard | Fast board CI |
-| Docs consistency | `_audit/docs-consistency.html` | Mọi claim đếm trong README/SKILL/llms.txt khớp compiler manifest; claim số card trong prose audit (`_audit/index` / README / namespace-portability) khớp `manifest.cards`; `VERSION` semver và `package.json` khớp (LAUNCH 1.1.0; auto-bump trên main); không tham chiếu changelog-file; blacklist stale-phrase (suite/pack count đã gỡ trong audit Th7 2026) sạch trên README/SKILL/llms + `docs/*.md` (ghi chú lịch sử dưới `_audit/archive/` không được quét); `DESIGN.md` tồn tại với front-matter version = `VERSION`; routing agent trung thực — Claude path cite `_esm/cs.mjs` + bundle prefix; Stitch path cấm `*.dc.html` làm SoT; tên package `@cyberskill/design` | 0 claim lệch, 0 blacklist hit, VERSION sync + stamp + routing nguyên (`__docs`) | Hard | Fast board CI + merge blocker |
+| Docs consistency | `_audit/docs-consistency.html` | Mọi claim đếm trong README/SKILL/llms.txt khớp compiler manifest; claim số card trong prose audit (`_audit/index` / README / namespace-portability) khớp `manifest.cards`; `VERSION` semver và `package.json` khớp (LAUNCH 1.1.0; auto-bump trên main); không tham chiếu changelog-file; blacklist stale-phrase sạch trên README/SKILL/llms + `docs/*.md`; `DESIGN.md` stamp = `VERSION`; routing agent trung thực; doctrine↔source — 10 role accent (gồm `on-strong`), depth scale đủ, default lang `vi`, breakpoint CSS↔JSON, fallback depth trong `base/` | 0 claim lệch + doctrine parity (`__docs`) | Hard | Fast board CI + merge blocker |
+| Asset-weight budget | `_audit/asset-weight-budget.html` | WebP aurora elemental (`assets/aurora-{tho,hoa,thuy,moc,kim}.webp`) dưới trần hồi quy (≤300 KB/file, ≤1.2 MB cả bộ); PNG aurora legacy thì fail; CSS wash không được trỏ JPEG Thổ | Cả năm dưới trần (`__assetweight`) | Hard | Fast board CI (+ Node twin `test-docs-consistency.mjs`) |
 | Docs language parity | `_audit/docs-lang-parity.html` | Mọi EN `docs/*.md` hướng operator có counterpart `docs/vi/`; VI không phải stub trống/TODO (≥40% độ dài EN); blacklist stale-phrase sạch trên cả EN và VI (ghi chú lịch sử dưới `_audit/archive/` không được theo dõi) | 0 cặp thiếu, 0 stub, 0 blacklist hit (`__docslangparity`) | Hard | Fast board CI |
 | DESIGN.md parity | `_audit/design-md-parity.html` | Root `DESIGN.md` (open-spec Stitch) byte-equals regeneration trong trình duyệt từ `tokens.dtcg.json` + `_ds_manifest.json` + `VERSION` qua `scripts/design-md-lib.mjs` dùng chung; từng hàng token được re-check riêng (số hàng in kèm verdict) | Byte-identical + 0 hàng drift (`__designmd`) | Hard | Fast board CI |
 | Version stamp | `_audit/version-stamp.html` | `package.json`, meta `tokens.json`/`tokens.js`, DTCG `$extensions`, `provenance.json` release + dtcgStamp, front matter `DESIGN.md`, và `_esm/cs.mjs` `export const VERSION` đều bằng `VERSION` (pin theo file; LAUNCH 1.1.0) | Cả 9 stamp bằng nhau (`__versionstamp`) | Hard | Fast board CI |
@@ -35,7 +36,7 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | Package exports integrity | `_audit/package-exports-integrity.html` | Mọi entry `files` của `package.json` và mọi target `module`/`types`/`style`/`exports` tồn tại; mọi target entry-point được `files` phủ (pack-safe); dual entry — `_esm/react.mjs` (mặc định / `./react`, React peer) + `_esm/cs.mjs` (`./legacy`) — hình ESM và re-export ⊆ export lộ trong header bundle | 0 thiếu / chưa phủ / lạ (`__pkgexports`) | Hard | Fast board CI |
 | Component children | `_audit/component-children-test.html` | Component void-element (Checkbox, Radio, Switch, SearchField, NumberField, Slider, Divider, TextField) mount với child lạc mà không throw React #137 | 0 throw (`__result.anyThrew === false`) | Hard | Fast board CI |
 | Component behavior | `_audit/component-behavior-test.html` | 79 assert tương tác thật — mọi public primary có hợp đồng tương tác người dùng (overlay, form, AI gate, shell, media/copy) cộng toast trên dialog; primary chỉ hiển thị loại trừ theo thiết kế | 79/79 assert pass (`__behavior`) | Hard | Fast board CI |
-| A11y interactions | `_audit/a11y-gate.html` | Focus management (Dialog/Drawer trap + restore + Escape), roving tabindex, combobox `aria-activedescendant`, hợp đồng role/label, cộng Esc/focus open-state cho Cascader · TreeSelect · Tour · HoverCard · ContextMenu | Mọi assert keyboard/ARIA pass (`__a11y`) | Hard | Fast board CI |
+| A11y interactions | `_audit/a11y-gate.html` | Focus trap/restore, roving, Mentions APG + Sortable buttons (hard-fail), role/label, open-state Esc | Mọi assert keyboard/ARIA pass (`__a11y`) | Hard | Fast board CI |
 | A11y CSSOM | `_audit/a11y-harness.html` | Mọi control `.cs-*` tương tác đạt floor touch-target đã ghi dưới coarse pointer; focus-ring, reduced-motion, và contrast rule chứng minh trong source CSS | 0 vi phạm floor, mọi source proof tìm thấy (`__a11ycss`) | Hard | Fast board CI |
 | Template schema v2 | `_audit/template-schema-test.html` | Mọi sidecar `content-schema.json` validate theo JSON Schema, mọi slot id khai báo resolve tới `{{ hole }}` thật trong template, và mọi template lộ **content** hole author được đều có sidecar (hole trục/control-flow và tweak boolean được loại trừ — xem `docs/template-schema-v2.md`) | 0 sidecar invalid, 0 slot id treo, 0 template hole-driven thiếu sidecar (`__schemav2`) | Hard | Fast board CI |
 | Support runtime identity | `_audit/support-runtime-identity.html` | Mọi bản `templates/*/support.js` (một mỗi template, 84) byte-identical: sha-256 qua SubtleCrypto, đúng một hash duy nhất, số bản == số template manifest | 1 hash duy nhất, count khớp (`__supportid`) | Hard | Fast board CI |
@@ -65,8 +66,12 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | Token provenance | `_audit/ci/check-token-provenance.mjs` | `tokens/native/` + `tokens/provenance.json` khóa với `tokens/tokens.dtcg.json` (cùng authority drift sha-256 như gate token-pipeline) | Exit 0 khi hash khớp | Hard | CI job `token-provenance` |
 | Bundle freshness (authority) | `_audit/ci/check-bundle-freshness.mjs` | `_ds_bundle.js` đã commit được build từ component source hiện tại — khám phá source đầy đủ (đi `components/`, `ui_kits/`, root sources), nên file mới/xóa cũng bị bắt, hàng trình duyệt không làm được | Exit 0, 0 source drift/mới/xóa | Hard | CI job `node-prechecks` |
 | DESIGN.md freshness | `scripts/generate-design-md.mjs --check` | Root `DESIGN.md` byte-equals regeneration mới từ DTCG + manifest + `VERSION` | Exit 0 khi byte khớp | Hard | CI job `node-prechecks` |
+| styles.min.css freshness | `scripts/flatten-styles.mjs --check` | `dist/styles.min.css` đã commit byte-equals flatten `styles.css` + tokens/base (FIND-026) | Exit 0 khi byte khớp | Hard | CI job `node-prechecks` |
+| contrast-report freshness | `scripts/generate-contrast-report.mjs --check` | Báo cáo contrast EN + VI khớp regeneration từ element packs (FIND-026) | Exit 0 khi byte khớp | Hard | CI job `node-prechecks` |
+| Manifest coverage | `_audit/ci/check-manifest-coverage.mjs` | `templates/` + `.card.html` + startingPoints khớp `_ds_manifest.json` (allowlist: `_vendor`, `schema`, `email-safe`) | Exit 0 | Hard | CI `node-prechecks` + unit |
+| Storybook build + freshness | `npm run build:storybook` + `test-storybook-freshness.mjs --require` | Storybook build trong CI; stamp khớp `stories/` + `.storybook/` (FIND-074 / FIND-075) | Exit 0 | Hard | CI job `storybook-build` |
 
-## Unit tests — `npm run test:unit` (13)
+## Unit tests — `npm run test:unit`
 
 | Test | File | Assert gì | Tiêu chí pass | Loại | Chạy ở đâu |
 |---|---|---|---|---|---|
@@ -82,9 +87,11 @@ Nguyên tắc benchmark (WCAG · APCA · OKLCH · DTCG · doctrine CDS + mở r
 | React entry | `_audit/ci/test-react-entry.mjs` | Dual package exports (`.` / `./react` → `_esm/react.mjs`, `./legacy` → `_esm/cs.mjs`); `package.json` version = `VERSION`; peerDeps React; react.mjs không CDN/bundle bridge và re-export khớp header bundle; `generate-react-entry --check` xanh | Mọi assert pass (exit 0) | Hard | Unit test |
 | Element packs | `_audit/ci/test-element-packs.mjs` | `tokens/elements.css` + mirror JSON/JS/DTCG byte-equal regeneration từ `tokens/element-seeds.json` | `generate-element-packs --check` exit 0 | Hard | Unit test |
 | i18n builtins + doc/font residuals | `_audit/ci/test-i18n-builtins.mjs` | Không literal EN UI cứng ngoài registry; 0 hex doc-palette trong templates; 0 font-size px thô trong `base/` | Exit 0 | Hard | Unit test |
-| Storybook static freshness | `_audit/ci/test-storybook-freshness.mjs` | Khi có `storybook-static/`, `.cs-freshness.json` `sourceHash` khớp `stories/` + `.storybook/` (UX-030). Không có cây static thì bỏ qua. | Exit 0 | Hard | Unit test |
+| Manifest coverage | `_audit/ci/check-manifest-coverage.mjs` | Disk templates/cards/startingPoints ⊆ manifest (`email-safe` allowlist) | Exit 0 | Hard | Unit test |
+| Pack hygiene | `_audit/ci/test-pack-hygiene.mjs` | Tarball loại `docs/tasks|audits|plans|status`; gồm notices + fonts + `_vendor/` (FIND-064) | Exit 0 | Hard | Unit test |
+| CI verdict selftest | `_audit/ci/ci-verdict.mjs --selftest` | Helper annotation soft-skip vs success (FIND-095) | Exit 0 | Hard | Unit test |
 
-Suite `test:unit` được nối vào CI workflow như một phần của hardening Th7 2026 (trước đó chỉ chạy local).
+Suite `test:unit` được nối vào CI workflow như một phần của hardening Th7 2026 (trước đó chỉ chạy local). Storybook freshness chạy trong `storybook-build` với `--require` (không skip trong CI).
 
 ## Audit probe suite — `npm run test:audit-probe`
 
@@ -92,20 +99,20 @@ Entry thúc đẩy cho proxy audit UX (`_audit/ci/audit-probe-suite.mjs`): suite
 
 ## Job sync / phân phối (soft-skip)
 
-Soft-skip nghĩa là job exit 0 kèm report khi secret/plan/API không hoàn tất write thật — **không** có nghĩa Code Connect hay Figma Variables đang live. npm CI publish dùng Trusted Publishing; soft-skip là trung thực auth/conflict. Coi việc maintainer còn lại trong `docs/decisions.md` là danh sách mở (Code Connect hoãn; grant consumer tại `docs/consumer-grant.md`). Storybook `FullMatrix` bắt buộc cho mọi public primary có ≥1 trong {size enums, variant enums, state keys} — helper chung tại `stories/lib/matrix.jsx`.
+Soft-skip nghĩa là job exit 0 kèm report khi secret/plan/API không hoàn tất write thật — **không** có nghĩa Code Connect hay Figma Variables đang live. Soft-skip ghi `$GITHUB_STEP_SUMMARY` và annotation CI riêng (`::error::` trên schedule/main, `::warning::` nơi khác) nên không bao giờ xanh im lặng giống live success (FIND-095). npm CI publish dùng Trusted Publishing; soft-skip chỉ **already-published** và `missing_secrets` thật sự ngoài GHA — auth/404/402 trên GHA release fail closed (xem `docs/release-runbook.md`). Coi việc maintainer còn lại trong `docs/decisions.md` là danh sách mở (Code Connect hoãn; grant consumer tại `docs/consumer-grant.md`). Storybook `FullMatrix` bắt buộc cho mọi public primary có ≥1 trong {size enums, variant enums, state keys} — helper chung tại `stories/lib/matrix.jsx`.
 
 | Job | Script / workflow | Assert gì | Soft-skip khi | Chạy ở đâu |
 |---|---|---|---|---|
 | Figma Variables | `_audit/ci/push-figma-variables.mjs` + job `figma-variables-push` | Secret mở được file; write Variables tùy chọn | Soft-skip khi thiếu secret (cùng trung thực với Code Connect) hoặc non-Enterprise / thiếu scope `file_variables:*` / API **403** sau khi secret đã có. Soft-skip ≠ sync live | Push `main` + thủ công |
 | Code Connect | `_audit/ci/code-connect-publish.mjs` + job `code-connect` | Config + 105 mapping; publish tùy chọn | Thiếu `FIGMA_TOKEN`/`FIGMA_FILE_KEY` hoặc API 403/404/429 | PR + `main` + thủ công |
-| npm publish | `_audit/ci/npm-publish.mjs` + `npm-publish.yml` | `files`/`exports` pack-safe; `npm publish` qua OIDC Trusted Publishing (package disallow tokens) | Auth / 403 / 404 / EOTP / conflict phiên bản | `workflow_dispatch` / tag `v*` |
+| npm publish | `_audit/ci/npm-publish.mjs` + `npm-publish.yml` | `files`/`exports` pack-safe (gồm `_vendor/`); `npm publish` qua OIDC Trusted Publishing (package disallow tokens); sau publish `npm view` version **và** `dist-tags.latest === VERSION` (FIND-094) | Soft-skip: `already_published` / `missing_secrets` ngoài GHA. **Fail trên GHA release:** ENEEDAUTH / 404 / 402 / 403 / EOTP / thiếu trên registry hoặc `latest` sai | `workflow_dispatch` / tag `v*` |
 | Native store | `_audit/ci/native-store-dry-run.mjs` + `native-store.yml` | Scaffold Fastlane + metadata; kiểm secret signed-release | Thiếu `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` (submit luôn tắt) | PR + `main` (paths) + thủ công |
 
-## Registry consumer smoke (hard)
+## Registry consumer smoke (fail-closed)
 
 | Job | Script / workflow | Assert gì | Tiêu chí pass | Chạy ở đâu |
 |---|---|---|---|---|
-| npm-hello smoke | `examples/npm-hello` + job `npm-hello-smoke` | Install registry public `@cyberskill/design@VERSION` resolve đúng tên package + exports (`npm install` + `npm run smoke`; pack proof local nếu VERSION chưa trên registry) | Exit 0 (**hard fail** khi đã publish; soft-skip pack proof nếu VERSION chưa trên registry) | Push/PR path-filtered + nightly + thủ công |
+| npm-hello smoke | `examples/npm-hello` + job `npm-hello-smoke` | Install registry public `@cyberskill/design@$VERSION` resolve đúng tên package + exports (`npm install` + `npm run smoke`) | Exit 0 chỉ khi VERSION có trên registry (**fail-closed**, FIND-087). Pack proof local chỉ khi fork đặt `NPM_HELLO_ALLOW_LOCAL_PACK=true` | Push/PR path-filtered + nightly + thủ công |
 
 ## Hardening Th7 2026 — đã giao
 

package/docs/vi/release-runbook.md

@@ -0,0 +1,78 @@
+# Runbook phát hành (chuẩn)
+
+Một trang về cách một bản phát hành diễn ra và cách biết nó đã thành công. Gộp các vùng 21/23. Chi tiết liên quan: `docs/ci-cd.md`, `docs/deploy.md`, `docs/decisions.md` §7 / §13.
+
+## Kích hoạt
+
+| Đường | Khi nào |
+|------|------|
+| **Tự động** | Push lên `main` với Conventional Commits → `version.yml` bump `VERSION`, stamp artifact, commit `chore(release): X.Y.Z`, tag `vX.Y.Z` |
+| **Ép** | Trailer `Release-As: X.Y.Z` trên commit, hoặc `workflow_dispatch` trên `version.yml` với một level |
+| **Publish thủ công** | `workflow_dispatch` trên `npm-publish.yml` (cũng chạy trên tag `v*`) |
+
+Không bao giờ push/deploy/merge nếu không có chỉ thị operator tường minh khi vận hành như agent.
+
+## Những gì chạy (happy path)
+
+```
+main push (feat/fix/…)
+  → version.yml  (bump VERSION + stamp + bundle + tag vX.Y.Z)
+  → npm-publish.yml  (OIDC Trusted Publishing; sau publish kiểm version + dist-tags.latest)
+  → Vercel (host)  (build:site → .vercel-static; headers từ vercel.json)
+  → sbom.yml trên tag  (artifact CycloneDX)
+```
+
+Scorecard chạy theo lịch tuần + push `main` (`.github/workflows/scorecard.yml`).
+
+## Tín hiệu thành công
+
+1. GitHub Actions: `version` xanh; `npm-publish` xanh (**không** soft-skip) với registry presence **và** `dist-tags.latest === VERSION` (FIND-094).
+2. `npm view @cyberskill/design version` **và** `npm view @cyberskill/design dist-tags.latest` đều bằng root `VERSION`.
+3. `npm-hello-smoke` xanh trên tip (cài registry fail-closed của VERSION đó — FIND-087).
+4. Production: `/` là Storybook; `/VERSION` là semver thuần; bảng nhanh `/_audit/run.html` xanh.
+5. Artifact: `cyclonedx-sbom` trên lần chạy tag; Scorecard SARIF trên Security / Actions artifacts.
+6. Health sau deploy trong `docs/deploy.md`.
+
+## Tag lịch sử chưa publish (không backfill)
+
+| Tag | Trạng thái | Hành động operator |
+|-----|--------|-----------------|
+| `v1.2.1` | Tag git lịch sử; **không** publish lên npm như `latest` | Để unpublished |
+| `v1.3.0` | Tag git lịch sử; **không** publish lên npm như `latest` | Để unpublished |
+| `v1.3.1` (tip hiện tại) | **Mục tiêu publish** khi operator chỉ thị | Chỉ publish **`1.3.1`** làm `dist-tags.latest` |
+
+**Không** publish `1.2.1` hay `1.3.0` để đóng lệch registry — đóng FIND-102 bằng cách publish **chỉ `1.3.1`** (có cổng operator). npm `latest` có thể vẫn đọc `1.2.0` cho tới khi publish đó land.
+
+## Thất bại / phục hồi
+
+| Triệu chứng | Hành động |
+|---------|--------|
+| `npm-publish` 403 / EOTP / ENEEDAUTH / 404 / 402 trên tag hoặc `workflow_dispatch` | **Fail-closed.** Sửa Trusted Publisher binding cho repo **`cyberskill-official/design`** (FIND-088) / 2FA / OIDC; chạy lại trên tag. Soft-skip **không** được báo success cho các lỗi này. |
+| Soft-skip `already_published` | No-op kỳ vọng — xác nhận registry; đừng coi là success nếu bạn định phát hành bản mới. |
+| Soft-skip `missing_secrets` | Chỉ kỳ vọng **ngoài** GitHub Actions (local). Trên GHA release đây là hard fail. |
+| `version.yml` push soft-warn | Đặt `PUSH_TOKEN` hoặc cho Actions push qua branch protection (xem `docs/ci-cd.md`). |
+| `npm-hello-smoke` đỏ (VERSION thiếu trên registry) | Kỳ vọng cho tới khi publish land (FIND-087). Theo **Sự cố: bản phát hành chưa publish** bên dưới — không đặt `NPM_HELLO_ALLOW_LOCAL_PACK` trên repo chuẩn. |
+| Nightly `design-system-gates` đỏ | GitHub thông báo subscriber workflow mặc định; xem “Cảnh báo job lịch” bên dưới. Chạy lại `workflow_dispatch`. |
+| Deploy Vercel một phần | Chạy lại deploy; theo protocol Health; không bịa claim header live nếu chưa `curl -sSI`. |
+
+## Sự cố: bản phát hành chưa publish (FIND-100 / FIND-101 / FIND-107)
+
+Dùng khi git/`VERSION`/site đi trước npm `dist-tags.latest` (ví dụ tip `1.3.1`, registry vẫn `1.2.0`).
+
+1. **Xác nhận lệch** — `cat VERSION`; `npm view @cyberskill/design version`; `npm view @cyberskill/design dist-tags.latest`; ghi nhận tag git `v1.2.1` / `v1.3.0` / `v1.3.1` là lịch sử vs mục tiêu publish.
+2. **Không** coi soft-skip xanh của `npm-publish` (hay proof pack local xanh của `npm-hello`) là bằng chứng VERSION đã public — smoke fail-closed; lỗi auth publish hard-fail trên GHA.
+3. **Sửa Trusted Publisher** nếu cần — cấu hình npm package phải liệt kê org/repo **`cyberskill-official/design`**, workflow **`npm-publish.yml`**, và đúng environment (FIND-088). Classic `NPM_TOKEN` bị cấm. CI dùng userconfig OIDC sạch (không `_authToken` rỗng từ `actions/setup-node`) để Trusted Publishing đổi token OIDC GitHub.
+4. **Publish có cổng operator** — chỉ sau chỉ thị tường minh: chạy lại `npm-publish.yml` trên tag **`v1.3.1`** (hoặc `workflow_dispatch` tại tip đó). Mục tiêu publish là **chỉ `1.3.1`**; không backfill `1.2.1` / `1.3.0`.
+5. **Xác minh** — `npm view @cyberskill/design@1.3.1 version` và `dist-tags.latest` đều `1.3.1`; chạy lại `npm-hello-smoke` (hoặc chờ lần gates kế) tới xanh.
+6. **Rollback / deprecate (nếu bản xấu đã lên `latest`)** — `npm deprecate @cyberskill/design@<bad> "…"` và/hoặc `npm dist-tag add @cyberskill/design@<good> latest`. npm thường không cho unpublish bản public gần đây — ưu tiên deprecate + retag `latest`. Rollback site/Vercel độc lập (`docs/deploy.md`).
+
+## Cảnh báo job lịch (area 27)
+
+- Cron nightly `0 3 * * *` trên `design-system-gates.yml`.
+- Khi schedule fail, job `notify-schedule-failure` (`needs` mọi job lịch — FIND-108) emit annotation lỗi Actions và fail khi `contains(needs.*.result, 'failure')`, kích hoạt **email native GitHub khi workflow fail** tới watcher repo / actor cuối theo Settings → Notifications.
+- Tuỳ chọn: thêm biến/secret Actions cho Slack webhook sau; không bắt buộc để CI xanh.
+- Operator nên theo dõi badge Actions trong `docs/ci-cd.md` và bật thông báo “Actions” cho workflow fail.
+
+## Product vs CyberOS
+
+Xem `docs/decisions.md` §13. Gói npm và cây portable là sản phẩm; `.cyberos/` chỉ là orchestration.

package/docs/vi/sync.md

@@ -1,6 +1,6 @@
 # Repo ↔ Claude Design — round-trip fidelity & đồng bộ hai chiều
 
-Repo GitHub (`cyberskill-official/design-system`) là **nguồn chân lý**. Session Claude Design là filesystem project tạm — tài liệu này nói cách chúng giữ sync mà không mất việc.
+Repo GitHub (`cyberskill-official/design`) là **nguồn chân lý**. Session Claude Design là filesystem project tạm — tài liệu này nói cách chúng giữ sync mà không mất việc.
 
 ## Repo có khôi phục nguyên hệ thống không?
 

package/docs/viewer.html

@@ -58,12 +58,12 @@
 <script>
 const DOCS_EN=[
  ['Start',[['README.md','README'],['SKILL.md','SKILL (agent rules)'],['llms.txt','llms.txt'],['CONTRIBUTING.md','Contributing']]],
- ['Guides',[['docs/consuming.md','Consuming & upgrading (incl. AI-agent quick path)'],['docs/consumer-grant.md','Consumer grant (npm · UNLICENSED)'],['docs/deploy.md','Deploy (Vercel/VPS)'],['docs/template-schema-v2.md','Template content-schema v2'],['docs/conventions.md','Conventions'],['docs/release-notes.md','Release Notes'],['docs/storybook.md','Storybook (product at /)'],['docs/live-hub.md','Live hub (Storybook at /)'],['docs/design-styles.md','Design styles'],['docs/benchmark-rubric.md','Benchmark rubric'],['docs/products.md','Products'],['docs/contrast-report.md','Contrast report'],['docs/figma.md','Figma']]],
+ ['Guides',[['docs/consuming.md','Consuming & upgrading (incl. AI-agent quick path)'],['docs/consumer-grant.md','Consumer grant (npm · UNLICENSED)'],['docs/deploy.md','Deploy (Vercel/VPS)'],['docs/template-schema-v2.md','Template content-schema v2'],['docs/conventions.md','Conventions'],['docs/release-notes.md','Release Notes'],['docs/release-runbook.md','Release runbook'],['docs/storybook.md','Storybook (product at /)'],['docs/live-hub.md','Live hub (Storybook at /)'],['docs/design-styles.md','Design styles'],['docs/benchmark-rubric.md','Benchmark rubric'],['docs/products.md','Products'],['docs/contrast-report.md','Contrast report'],['docs/figma.md','Figma']]],
  ['Maintainers',[['docs/decisions.md','Decisions'],['docs/ci-cd.md','CI/CD automation'],['docs/quality-gates.md','Quality gates'],['docs/sync.md','Git sync & hygiene']]]
 ];
 const DOCS_VI=[
  ['Bắt đầu',[['README.md','README (EN)'],['SKILL.md','SKILL (EN)'],['llms.txt','llms.txt (EN)'],['CONTRIBUTING.md','Contributing (EN)']]],
- ['Hướng dẫn',[['docs/consuming.md','Tiêu thụ & nâng cấp'],['docs/consumer-grant.md','Grant consumer (npm · UNLICENSED)'],['docs/deploy.md','Deploy (Vercel/VPS)'],['docs/template-schema-v2.md','Template schema v2'],['docs/conventions.md','Conventions'],['docs/release-notes.md','Ghi chú phát hành'],['docs/storybook.md','Storybook (sản phẩm tại /)'],['docs/live-hub.md','Live hub (Storybook tại /)'],['docs/design-styles.md','Phong cách'],['docs/benchmark-rubric.md','Rubric benchmark'],['docs/products.md','Sản phẩm'],['docs/contrast-report.md','Báo cáo contrast'],['docs/figma.md','Figma']]],
+ ['Hướng dẫn',[['docs/consuming.md','Tiêu thụ & nâng cấp'],['docs/consumer-grant.md','Grant consumer (npm · UNLICENSED)'],['docs/deploy.md','Deploy (Vercel/VPS)'],['docs/template-schema-v2.md','Template schema v2'],['docs/conventions.md','Conventions'],['docs/release-notes.md','Ghi chú phát hành'],['docs/release-runbook.md','Runbook phát hành'],['docs/storybook.md','Storybook (sản phẩm tại /)'],['docs/live-hub.md','Live hub (Storybook tại /)'],['docs/design-styles.md','Phong cách'],['docs/benchmark-rubric.md','Rubric benchmark'],['docs/products.md','Sản phẩm'],['docs/contrast-report.md','Báo cáo contrast'],['docs/figma.md','Figma']]],
  ['Maintainer',[['docs/decisions.md','Quyết định'],['docs/ci-cd.md','CI/CD'],['docs/quality-gates.md','Quality gates'],['docs/sync.md','Đồng bộ Git']]]
 ];
 let lang=(localStorage.getItem('cs-docs-lang')==='vi')?'vi':'en';

package/fonts/OFL.txt

@@ -0,0 +1,98 @@
+Copyright notices for Font Software redistributed in fonts/:
+
+Copyright 2021 The Be Vietnam Pro Project Authors (https://github.com/bettergui/BeVietnamPro),
+
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+Copyright 2020 The Space Grotesk Project Authors (https://github.com/floriankarsten/space-grotesk)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/guidelines/atomic-view.html

@@ -136,7 +136,7 @@ function AlertDialogD({L}){ const [on,setOn]=useState(false); const V=L==="vi";
 function DialogDemo({title,startOpen=false}){ const [on,setOn]=useState(!!startOpen); return <div><Button size="sm" onClick={()=>setOn(true)}>Open dialog</Button><Dialog open={on} title={title} onClose={()=>setOn(false)} actions={<><Button variant="secondary" onClick={()=>setOn(false)}>Not now</Button><Button onClick={()=>setOn(false)}>Send wish</Button></>}>A real person on the team replies within one business day.</Dialog></div>; }
 function DrawerDemo({title,L,startOpen=false}){ const [on,setOn]=useState(!!startOpen); const V=L==="vi"; return <div><Button size="sm" variant="secondary" onClick={()=>setOn(true)}>{V?"Mở ngăn kéo":"Open drawer"}</Button><Drawer open={on} onClose={()=>setOn(false)} title={title} actions={has(Button)?<Button size="sm">{V?"Mở dự án":"Open project"}</Button>:null}>{has(Badge)&&<Badge variant="ochre">{V?"Đang làm":"In progress"}</Badge>}<p style={{color:"var(--cs-color-text-muted)",fontSize:13}}>{V?"Liên kết component Liquid Glass + 15 gói Ngũ Hành.":"Liquid Glass component bindings + 15 element packs."}</p></Drawer></div>; }
 function GridD({L}){ const [sel,setSel]=useState(["CDS"]); const V=L==="vi"; return has(DataGrid)?<DataGrid selectable selected={sel} onSelect={setSel} rowKey="key" height={220} columns={[{key:"key",header:V?"Mã":"Key",sortable:true},{key:"name",header:V?"Dự án":"Project",sortable:true},{key:"pct",header:V?"Tiến độ":"Progress",sortable:true,render:(r)=>r.pct+"%"}]} rows={[{key:"CDS",name:"Design System",pct:72},{key:"GENIE",name:"Lumi Genie",pct:58},{key:"SITE",name:"cyberskill.world",pct:84}]}/>:<Miss n="DataGrid"/>; }
-function SortD({L}){ const [it,setIt]=useState(L==="vi"?[{key:"a",label:"Ước một điều"},{key:"b",label:"Định hình"},{key:"c",label:"Xây để ra mắt"}]:[{key:"a",label:"Make a wish"},{key:"b",label:"Shape it"},{key:"c",label:"Build to ship"}]); return has(Sortable)?<Sortable items={it} onChange={setIt}/>:<Miss n="Sortable"/>; }
+function SortD({L}){ const [it,setIt]=useState(L==="vi"?[{key:"a",label:"Ước một điều"},{key:"b",label:"Định hình"},{key:"c",label:"Xây để ra mắt"}]:[{key:"a",label:"Make a wish"},{key:"b",label:"Shape it"},{key:"c",label:"Build to ship"}]); return has(Sortable)?<Sortable lang={L} items={it} onChange={setIt}/>:<Miss n="Sortable"/>; }
 function TreeSelD({L}){ const [k,setK]=useState("ds"); return has(TreeSelect)?<TreeSelect value={k} onChange={setK} nodes={L==="vi"?[{key:"p",label:"Nền tảng",children:[{key:"ds",label:"Design System"},{key:"tok",label:"Token Pipeline"}]},{key:"ai",label:"AI",children:[{key:"lumi",label:"Lumi Genie"}]}]:[{key:"p",label:"Platform",children:[{key:"ds",label:"Design System"},{key:"tok",label:"Token Pipeline"}]},{key:"ai",label:"AI",children:[{key:"lumi",label:"Lumi Genie"}]}]}/>:<Miss n="TreeSelect"/>; }
 function CascD({L}){ const [p,setP]=useState(["hcm","d1"]); return has(Cascader)?<Cascader value={p} onChange={setP} nodes={[{key:"hcm",label:"TP.HCM",children:[{key:"d1",label:L==="vi"?"Quận 1":"District 1"},{key:"d3",label:L==="vi"?"Quận 3":"District 3"}]},{key:"hn",label:L==="vi"?"Hà Nội":"Hanoi",children:[{key:"hk",label:L==="vi"?"Hoàn Kiếm":"Hoan Kiem"}]}]}/>:<Miss n="Cascader"/>; }
 function TransD({L}){ const [v,setV]=useState(["web"]); return has(Transfer)?<Transfer value={v} onChange={setV} items={L==="vi"?[{key:"web",label:"Ứng dụng web"},{key:"mob",label:"Ứng dụng di động"},{key:"auto",label:"Tự động hóa"},{key:"ds",label:"Design system"}]:[{key:"web",label:"Web apps"},{key:"mob",label:"Mobile apps"},{key:"auto",label:"Automation"},{key:"ds",label:"Design systems"}]}/>:<Miss n="Transfer"/>; }
@@ -270,7 +270,7 @@ const STORIES = [
   { tier:"Organism", name:"TreeSelect", grp:"Forms", render:(L)=> <div style={{minHeight:260}}><TreeSelD L={L}/></div> },
   { tier:"Organism", name:"Cascader", grp:"Forms", render:(L)=> <div style={{minHeight:240}}><CascD L={L}/></div> },
   { tier:"Organism", name:"Transfer", grp:"Forms", render:(L)=> <TransD L={L}/> },
-  { tier:"Molecule", name:"Mentions", grp:"Forms", render:(L)=> has(Mentions)?<Mentions users={["anle","baovu","lumi"]} defaultValue={L==="vi"?"Cảm ơn @":"Thanks @"} rows={2}/>:<Miss n="Mentions"/> },
+  { tier:"Molecule", name:"Mentions", grp:"Forms", render:(L)=> has(Mentions)?<Mentions lang={L} users={["anle","baovu","lumi"]} defaultValue={L==="vi"?"Cảm ơn @":"Thanks @"} rows={2}/>:<Miss n="Mentions"/> },
   { tier:"Organism", name:"Form + FormField", grp:"Forms", render:(L)=> has(Form,FormField,Button)?<div style={{maxWidth:420}}><Form onSubmit={()=>{}} errors={{email:L==="vi"?"Nhập email hợp lệ.":"Enter a valid email."}}><FormField label={L==="vi"?"Email công việc":"Work email"} required error={L==="vi"?"Nhập email hợp lệ.":"Enter a valid email."}><input name="email" className="cs-field__control" defaultValue="not-an-email"/></FormField><FormField label={L==="vi"?"Công ty":"Company"} hint={L==="vi"?"Không bắt buộc":"Optional"}><input name="company" className="cs-field__control"/></FormField><Button type="submit" size="sm">{L==="vi"?"Gửi":"Send"}</Button></Form></div>:<Miss n="Form"/> },
   { tier:"Organism", name:"Tree", grp:"Data", render:(L)=> has(Tree)?<div style={{maxWidth:340}}><Tree defaultOpen nodes={L==="vi"?[{key:"p",label:"Nền tảng",children:[{key:"ds",label:"Design System"},{key:"tok",label:"Token Pipeline"}]},{key:"ai",label:"AI",children:[{key:"lumi",label:"Lumi Genie"}]}]:[{key:"p",label:"Platform",children:[{key:"ds",label:"Design System"},{key:"tok",label:"Token Pipeline"}]},{key:"ai",label:"AI",children:[{key:"lumi",label:"Lumi Genie"}]}]}/></div>:<Miss n="Tree"/> },
   { tier:"Molecule", name:"Watermark", grp:"Data", render:(L)=> has(Watermark)?<Watermark text={L==="vi"?"BẢN NHÁP":"DRAFT"}><div style={{border:"1px solid var(--cs-color-border-default)",borderRadius:"var(--cs-radius-md)",padding:"30px 22px",maxWidth:420}}>{L==="vi"?"Nội dung tài liệu được đánh dấu bản nháp.":"Document content marked as a draft."}</div></Watermark>:<Miss n="Watermark"/> },

package/guidelines/brand-imagery.html

@@ -4,7 +4,7 @@
 <link rel="stylesheet" href="../styles.css" />
 <style>
   body { margin: 0; font-family: var(--cs-font-family-ui); }
-  .stage { position: relative; min-height: 260px; background-image: url("../assets/aurora-gold.jpg"); background-size: cover; background-position: center; overflow: hidden; }
+  .stage { position: relative; min-height: 260px; background-image: url("../assets/aurora-tho.webp"); background-size: cover; background-position: center; overflow: hidden; }
   .lumi { position: absolute; right: 34px; bottom: -6px; height: 250px; filter: drop-shadow(0 18px 40px rgba(0,0,0,.45)); }
   .copy { position: absolute; left: 26px; top: 24px; max-width: 340px; color: #fff; }
   .k { font: 600 11px/1 var(--cs-font-family-ui); text-transform: uppercase; letter-spacing: .1em; color: var(--cs-color-brand-ochre); }

package/guidelines/elements-variants.html

@@ -39,11 +39,11 @@ a{color:var(--cs-color-link)}a:hover{color:var(--cs-color-link-hover)}
     <div class="v"><span class="sw" style="background:#AEE2ED"></span><div><div class="vn">mist</div><div class="vx">#AEE2ED</div></div></div></div>
 </div>
 <div style="display:grid;grid-template-columns:repeat(5,1fr);gap:14px">
-  <div class="wash"><img src="../assets/aurora-moc.png" alt="Mộc aurora wash"><span class="wl">Mộc</span></div>
-  <div class="wash"><img src="../assets/aurora-hoa.png" alt="Hỏa aurora wash"><span class="wl">Hỏa</span></div>
-  <div class="wash"><img src="../assets/aurora-gold.jpg" alt="Thổ aurora wash (official gold)"><span class="wl">Thổ · official</span></div>
-  <div class="wash"><img src="../assets/aurora-kim.png" alt="Kim aurora wash"><span class="wl">Kim</span></div>
-  <div class="wash"><img src="../assets/aurora-thuy.png" alt="Thủy aurora wash"><span class="wl">Thủy</span></div>
+  <div class="wash"><img src="../assets/aurora-moc.webp" alt="Mộc aurora wash"><span class="wl">Mộc</span></div>
+  <div class="wash"><img src="../assets/aurora-hoa.webp" alt="Hỏa aurora wash"><span class="wl">Hỏa</span></div>
+  <div class="wash"><img src="../assets/aurora-tho.webp" alt="Thổ aurora wash (official gold)"><span class="wl">Thổ · official</span></div>
+  <div class="wash"><img src="../assets/aurora-kim.webp" alt="Kim aurora wash"><span class="wl">Kim</span></div>
+  <div class="wash"><img src="../assets/aurora-thuy.webp" alt="Thủy aurora wash"><span class="wl">Thủy</span></div>
 </div>
 <footer style="display:flex;gap:16px;margin-top:14px;font-size:12px;color:var(--cs-color-text-muted);align-items:center"><b style="color:var(--cs-color-text-primary)">Rules</b><span>Slots soft · middle · deep share intensity across elements — same 9-token contract (generated)</span><span>·</span><span>Washes apply via .cs-aurora-wash</span><span>·</span><span><b style="color:var(--cs-color-text-primary)">Lumi stays golden</b> — only the environment re-tints</span></footer>
 </body></html>

package/guidelines/spacing-breakpoints.html

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Spacing" viewport="700x150" name="Breakpoints" subtitle="Mobile-first · sm → 2xl" -->
+<!-- @dsCard group="Spacing" viewport="700x150" name="Breakpoints" subtitle="Mobile-first · phone → 2xl" -->
 <!DOCTYPE html>
 <html lang="en"><head><meta charset="utf-8" />
 <link rel="stylesheet" href="../styles.css" />
@@ -11,6 +11,7 @@
 </style></head>
 <body>
 <div class="row">
+  <div class="bp"><div class="n">phone</div><div class="v">360</div></div>
   <div class="bp"><div class="n">sm</div><div class="v">640</div></div>
   <div class="bp"><div class="n">md</div><div class="v">768</div></div>
   <div class="bp"><div class="n">lg</div><div class="v">1024</div></div>

package/guidelines/surfaces-glass.html

@@ -4,7 +4,7 @@
 <link rel="stylesheet" href="../styles.css" />
 <style>
   body { margin: 0; padding: 0; font-family: var(--cs-font-family-ui); }
-  .stage { position: relative; min-height: 230px; background-image: url("../assets/aurora-gold.jpg"); background-size: cover; background-position: center; padding: 22px 24px; display: flex; gap: 14px; align-items: center; }
+  .stage { position: relative; min-height: 230px; background-image: url("../assets/aurora-tho.webp"); background-size: cover; background-position: center; padding: 22px 24px; display: flex; gap: 14px; align-items: center; }
   .m { flex: 1; border-radius: var(--cs-radius-lg); padding: 16px 14px; min-height: 128px; display: flex; flex-direction: column; justify-content: flex-end; color: var(--cs-color-text-primary); }
   .nm { font-weight: 700; font-size: 14px; }
   .d { font-size: 12px; color: var(--cs-color-text-muted); margin-top: 3px; }

package/llms.txt

@@ -1,6 +1,6 @@
 # CyberSkill Design System
 
-> HTML-first, Vietnamese-first design system, LAUNCHED **v1.1.0**; current **v1.1.1**. Immutable anchors: Umber #45210E · Ochre #F4BA17. Four independent axes — Theme (light · dark · system) × Element (Ngũ Hành, 15 variants) × Language (EN · VI) × Style (`data-cs-style` — sole pack **liquid-glass**; absent ≡ default). It ships 106 components / 122 exports, 84 copyable templates (EN·VN for emails + team/legal/finance; client/media collateral EN-first), and tokens in CSS + JSON + ESM + W3C DTCG + native mirrors. This file is the agent/tool front door: it maps each audience to the format it should consume. npm package name is **`@cyberskill/design`** (not `@cyberskill/react`). Release signal: tip SHA + [docs/release-notes.md](docs/release-notes.md) — VERSION **1.1.1**, no CHANGELOG.
+> HTML-first, Vietnamese-first design system, LAUNCHED **v1.1.0**; current **v1.3.8**. Immutable anchors: Umber #45210E · Ochre #F4BA17. Four independent axes — Theme (light · dark · system) × Element (Ngũ Hành, 15 variants) × Language (EN · VI) × Style (`data-cs-style` — sole pack **liquid-glass**; absent ≡ default). It ships 106 components / 122 exports, 84 copyable templates (EN·VN for emails + team/legal/finance; client/media collateral EN-first), and tokens in CSS + JSON + ESM + W3C DTCG + native mirrors. This file is the agent/tool front door: it maps each audience to the format it should consume. npm package name is **`@cyberskill/design`** (not `@cyberskill/react`). Release signal: tip SHA + [docs/release-notes.md](docs/release-notes.md) — VERSION **1.3.8**, no CHANGELOG.
 
 The portable contract covers browser and bundler entry points: `styles.css` · `_esm/cs.mjs` legacy · `_ds_bundle.js` · tokens work without a build step; `_esm/react.mjs` is bundler-native JSX (Next/Vite must transpile — not a bare-browser import). The DC layer (`templates/**/*.dc.html`) is **Claude Design / authoring-environment-only**. **Google Stitch must not treat `*.dc.html` as source of truth** — use `DESIGN.md`, DTCG, `styles.css`, kitchen-sink, and `.cs-*` static HTML instead. Dual path: [docs/consuming.md](docs/consuming.md). The full non-negotiables list lives in `CONTRIBUTING.md` and `docs/conventions.md`.
 
@@ -28,7 +28,7 @@ The portable contract covers browser and bundler entry points: `styles.css` · `
 - [templates/](templates/): 84 copyable starting points (`.dc.html`); `email-safe/` send-ready emails; `kitchen-sink.html`; `playground.html`
 - [guidelines/](guidelines/): specimen cards + `atomic-view.html` (portable component grid) — host product surface is Storybook at `/`
 - [examples/static-hello/](examples/static-hello/): zero-install static consumer (Stitch / plain HTML)
-- [examples/npm-hello/](examples/npm-hello/): first registry **browser** consumer — `@cyberskill/design@1.1.1` legacy entry (Lumi · Hỏa · plasma); Status Hub teams swap to `thuy`; Next/SSR apps use default `@cyberskill/design` React entry instead
+- [examples/npm-hello/](examples/npm-hello/): first registry **browser** consumer — `@cyberskill/design@1.3.8` legacy entry (Lumi · Hỏa · plasma); Status Hub teams swap to `thuy`; Next/SSR apps use default `@cyberskill/design` React entry instead
 - [examples/native/](examples/native/): SwiftUI / Compose / Flutter sample apps + store scaffolds — Compose is **Android Studio**-first (no committed `gradlew`; see `examples/native/README.md`)
 - [ui_kits/](ui_kits/): product recreations — status-hub · website · deck
 - [fonts/](fonts/): self-hosted Be Vietnam Pro (UI) + Space Grotesk (opt-in display, `--cs-font-family-display`) + JetBrains Mono woff2
@@ -37,12 +37,12 @@ The portable contract covers browser and bundler entry points: `styles.css` · `
 - [DESIGN.md](DESIGN.md): generated open-spec surface (doctrine + tokens + inventory) for Stitch-style consumers — pinned to DTCG by the design-md-parity gate
 - [SKILL.md](SKILL.md): agent entry — hard rules + fast orientation
 - [CONTRIBUTING.md](CONTRIBUTING.md): one-page onboarding for extending the system
-- [VERSION](VERSION): pinned 1.1.1 (matches [package.json](package.json))
+- [VERSION](VERSION): pinned 1.3.8 (matches [package.json](package.json))
 
 ## Docs — consumers
 
 - [docs/consuming.md](docs/consuming.md): adopting & upgrading, Claude Code vs Stitch dual path, package name `@cyberskill/design`; first registry install at [examples/npm-hello/](examples/npm-hello/) (Lumi · Hỏa · plasma); native mirrors at [examples/native/](examples/native/) (SwiftUI / Compose / Flutter samples)
-- [docs/release-notes.md](docs/release-notes.md): curated product highlights (not a changelog) — includes `@cyberskill/design@1.1.1` Trusted Publishing / grant pointer
+- [docs/release-notes.md](docs/release-notes.md): curated product highlights (not a changelog) — includes `@cyberskill/design@1.3.8` Trusted Publishing / grant pointer
 - [docs/consumer-grant.md](docs/consumer-grant.md): written npm grant (CyberSkill portfolio; UNLICENSED)
 - [docs/conventions.md](docs/conventions.md): authoring rules (naming grammar, the four axes)
 - [docs/design-styles.md](docs/design-styles.md): the live styling axes and the fixed liquid-glass treatment

package/package.json

@@ -1,16 +1,24 @@
 {
   "name": "@cyberskill/design",
-  "version": "1.2.0",
+  "version": "1.3.8",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cyberskill-official/design-system.git"
+    "url": "git+https://github.com/cyberskill-official/design.git"
   },
   "module": "_esm/react.mjs",
   "types": "_esm/react.d.ts",
+  "sideEffects": [
+    "**/*.css",
+    "./_ds_bundle.js",
+    "./_esm/cs.mjs",
+    "./image-slot.js",
+    "./ui_kits/**/*.js",
+    "./ui_kits/**/*.jsx"
+  ],
   "exports": {
     ".": {
       "types": "./_esm/react.d.ts",
@@ -23,6 +31,7 @@
     "./legacy": {
       "import": "./_esm/cs.mjs"
     },
+    "./components/*": "./components/*",
     "./styles.css": "./styles.css",
     "./tokens/*": "./tokens/*",
     "./_ds_bundle.js": "./_ds_bundle.js",
@@ -46,14 +55,18 @@
     "_ds_manifest.json",
     "llms.txt",
     "SKILL.md",
-    "docs/",
+    "docs/*.md",
+    "docs/vi/",
+    "docs/viewer.html",
     "components/",
     "templates/",
     "guidelines/",
     "ui_kits/",
+    "_vendor/",
     "DESIGN.md",
     "VERSION",
-    "dist/styles.min.css"
+    "dist/styles.min.css",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "keywords": [
     "design-system",
@@ -68,12 +81,12 @@
     "build:bundle": "node scripts/build-bundle.mjs",
     "build:react-entry": "node scripts/generate-react-entry.mjs",
     "build:design-md": "node scripts/generate-design-md.mjs",
-    "prepublishOnly": "npm run build:bundle && npm run build:react-entry && node scripts/generate-design-md.mjs --check",
+    "prepublishOnly": "npm run build:bundle && npm run build:react-entry && npm run build:styles && node scripts/generate-design-md.mjs --check && node scripts/flatten-styles.mjs --check && node scripts/generate-contrast-report.mjs --check && npm run version:stamp:check",
     "code-connect:generate": "node _audit/ci/generate-code-connect.mjs",
     "code-connect:dry-run": "node _audit/ci/code-connect-publish.mjs --dry-run",
     "npm:pack-dry-run": "node _audit/ci/npm-publish.mjs --dry-run",
     "native:store-dry-run": "node _audit/ci/native-store-dry-run.mjs --dry-run",
-    "storybook": "storybook dev -p 6006",
+    "storybook": "storybook dev -p 6006 --host 127.0.0.1",
     "build:storybook": "storybook build -o storybook-static && node scripts/stamp-storybook-freshness.mjs",
     "build:site": "npm run build:storybook && node scripts/vercel-static-output.mjs",
     "verify:serve": "python3 -m http.server 8765 --bind 127.0.0.1",
@@ -82,7 +95,7 @@
     "test:nav-model": "node _audit/ci/test-nav-model.mjs",
     "test:ui-contracts": "node _audit/ci/test-health-tokens-contract.mjs",
     "test:form-paths": "node _audit/ci/test-form-paths.mjs",
-    "test:unit": "node _audit/ci/test-nav-model.mjs && node _audit/ci/test-health-tokens-contract.mjs && node _audit/ci/test-form-paths.mjs && node _audit/ci/test-storybook-contract.mjs && node _audit/ci/test-axe-coverage.mjs && node _audit/ci/test-figma-push-helpers.mjs && node _audit/ci/test-native-samples.mjs && node _audit/ci/test-code-connect.mjs && node _audit/ci/test-subtree-consume.mjs && node _audit/ci/test-react-entry.mjs && node _audit/ci/test-element-packs.mjs && node _audit/ci/test-i18n-builtins.mjs && node _audit/ci/test-storybook-freshness.mjs",
+    "test:unit": "node _audit/ci/test-nav-model.mjs && node _audit/ci/test-health-tokens-contract.mjs && node _audit/ci/test-docs-consistency.mjs && node _audit/ci/test-base-hex-allowlist.mjs && node _audit/ci/test-form-paths.mjs && node _audit/ci/test-storybook-contract.mjs && node _audit/ci/test-axe-coverage.mjs && node _audit/ci/test-figma-push-helpers.mjs && node _audit/ci/test-native-samples.mjs && node _audit/ci/test-code-connect.mjs && node _audit/ci/test-npm-publish.mjs && node _audit/ci/test-subtree-consume.mjs && node _audit/ci/test-react-entry.mjs && node _audit/ci/test-element-packs.mjs && node _audit/ci/test-i18n-builtins.mjs && node _audit/ci/test-format-currency.mjs && node _audit/ci/check-manifest-coverage.mjs && node _audit/ci/ci-verdict.mjs --selftest && node _audit/ci/test-pack-hygiene.mjs && npm run version:stamp:check && node _audit/ci/test-docs-lang-parity.mjs && node _audit/ci/test-email-safe.mjs && node _audit/ci/test-prop-parity.mjs",
     "test:audit-probe": "node _audit/ci/audit-probe-suite.mjs",
     "test:element-packs": "node _audit/ci/test-element-packs.mjs",
     "test:react-entry": "node _audit/ci/test-react-entry.mjs",
@@ -93,13 +106,20 @@
     "test:figma-helpers": "node _audit/ci/test-figma-push-helpers.mjs",
     "test:code-connect": "node _audit/ci/test-code-connect.mjs",
     "test:native-samples": "node _audit/ci/test-native-samples.mjs",
+    "test:storybook-freshness": "node _audit/ci/test-storybook-freshness.mjs",
+    "test:manifest-coverage": "node _audit/ci/check-manifest-coverage.mjs",
+    "test:pack-hygiene": "node _audit/ci/test-pack-hygiene.mjs",
     "tokens:elements": "node scripts/generate-element-packs.mjs",
     "tokens:contrast": "node scripts/generate-contrast-report.mjs",
     "build:styles": "node scripts/flatten-styles.mjs",
     "version:check": "node scripts/ds-version.mjs --check",
     "version:selftest": "node scripts/ds-version.mjs --selftest",
     "version:stamp": "node scripts/stamp-release-version.mjs",
-    "version:stamp:apply": "node scripts/stamp-release-version.mjs --apply"
+    "version:stamp:apply": "node scripts/stamp-release-version.mjs --apply",
+    "version:stamp:check": "node scripts/stamp-release-version.mjs --check",
+    "sbom": "npx --yes @cyclonedx/cyclonedx-npm@3.1.0 --output-file bom.cdx.json --output-reproducible --spec-version 1.5",
+    "test:docs-lang-parity": "node _audit/ci/test-docs-lang-parity.mjs",
+    "test:email-safe": "node _audit/ci/test-email-safe.mjs"
   },
   "devDependencies": {
     "@figma/code-connect": "^1.4.9",

package/templates/app-shell/AppShell.dc.html

@@ -13,7 +13,7 @@
 <script src="./ds-base.js"></script>
 </helmet>
 <div data-theme="{{ rootTheme }}" lang="{{ langAttr }}" data-cs-element="{{ elAttr }}" data-cs-variant="{{ vaAttr }}" style="display:grid;grid-template-columns:248px 1fr;min-height:100vh;font-family:var(--cs-font-family-ui);color:var(--cs-color-text-primary);background:var(--cs-color-surface-page)">
-  <a class="cs-skip" href="#main" style="position:absolute;left:-999px;top:auto;width:1px;height:1px;overflow:hidden">Skip to content</a>
+  <a class="cs-skip" href="#main" style="position:absolute;left:-999px;top:auto;width:1px;height:1px;overflow:hidden">{{ skipLabel }}</a>
   <nav class="cs-sidebar" aria-label="{{ navLabel }}">
     <div style="display:flex;align-items:center;gap:10px;font-weight:800;font-size:17px;color:var(--cs-color-text-primary);padding:6px 12px 14px">
       <x-import component-from-global-scope="CyberSkillDS.Logo" size="28" hint-size="28px,28px"></x-import>CyberSkill
@@ -64,8 +64,8 @@ class Component extends DCLogic {
     const EL = {"Thổ · studio":["tho",""],"Thổ · clay":["tho","clay"],"Thổ · sand":["tho","sand"],"Hỏa · ember":["hoa",""],"Hỏa · lava":["hoa","lava"],"Hỏa · plasma":["hoa","plasma"],"Thủy · river":["thuy",""],"Thủy · ocean":["thuy","ocean"],"Thủy · mist":["thuy","mist"],"Mộc · leaf":["moc",""],"Mộc · bamboo":["moc","bamboo"],"Mộc · forest":["moc","forest"],"Kim · champagne":["kim",""],"Kim · steel":["kim","steel"],"Kim · titanium":["kim","titanium"]};
     const [elAttr, vaAttr] = EL[this.props.element] || EL["Thổ · studio"];
 const vn = this.props.language === "Tiếng Việt";
-    const en = { navLabel:"Workspace", nav1:"Overview", nav2:"Projects", nav3:"Releases", nav4:"Team", nav5:"Settings", searchPh:"Search projects…", newBtn:"New project", h1:"Overview", sub:"Every wish in flight, at a glance.", s1:"Projects", s2:"In progress", s3:"Shipped", s4:"Avg progress", s4d:"+6 this week", tblCap:"Projects", cKey:"Key", cName:"Project", cSquad:"Squad", cProg:"Progress", cStatus:"Status", stInprog:"In progress", stBlocked:"Blocked" };
-    const vi = { navLabel:"Không gian", nav1:"Tổng quan", nav2:"Dự án", nav3:"Phát hành", nav4:"Đội ngũ", nav5:"Cài đặt", searchPh:"Tìm dự án…", newBtn:"Dự án mới", h1:"Tổng quan", sub:"Mọi điều ước đang chạy, trong một cái nhìn.", s1:"Dự án", s2:"Đang làm", s3:"Đã ra mắt", s4:"Tiến độ TB", s4d:"+6 tuần này", tblCap:"Dự án", cKey:"Mã", cName:"Dự án", cSquad:"Nhóm", cProg:"Tiến độ", cStatus:"Trạng thái", stInprog:"Đang làm", stBlocked:"Bị chặn" };
+    const en = { skipLabel:"Skip to content", navLabel:"Workspace", nav1:"Overview", nav2:"Projects", nav3:"Releases", nav4:"Team", nav5:"Settings", searchPh:"Search projects…", newBtn:"New project", h1:"Overview", sub:"Every wish in flight, at a glance.", s1:"Projects", s2:"In progress", s3:"Shipped", s4:"Avg progress", s4d:"+6 this week", tblCap:"Projects", cKey:"Key", cName:"Project", cSquad:"Squad", cProg:"Progress", cStatus:"Status", stInprog:"In progress", stBlocked:"Blocked" };
+    const vi = { skipLabel:"Bỏ qua nội dung", navLabel:"Không gian", nav1:"Tổng quan", nav2:"Dự án", nav3:"Phát hành", nav4:"Đội ngũ", nav5:"Cài đặt", searchPh:"Tìm dự án…", newBtn:"Dự án mới", h1:"Tổng quan", sub:"Mọi điều ước đang chạy, trong một cái nhìn.", s1:"Dự án", s2:"Đang làm", s3:"Đã ra mắt", s4:"Tiến độ TB", s4d:"+6 tuần này", tblCap:"Dự án", cKey:"Mã", cName:"Dự án", cSquad:"Nhóm", cProg:"Tiến độ", cStatus:"Trạng thái", stInprog:"Đang làm", stBlocked:"Bị chặn" };
     const t = vn ? vi : en;
     return Object.assign({ langAttr: (this.props.language ?? "English") === "Tiếng Việt" ? "vi" : "en", elAttr, vaAttr, rootTheme: this.props.theme === "dark" ? "dark" : "",
       cols: [ { key: "key", header: t.cKey }, { key: "name", header: t.cName }, { key: "squad", header: t.cSquad }, { key: "pct", header: t.cProg, render: (r) => r.pct + "%" }, { key: "status", header: t.cStatus } ],

package/templates/app-shell/content-schema.json

@@ -2,6 +2,13 @@
   "$schemaVersion": "2.0",
   "template": "app-shell",
   "slots": [
+    {
+      "id": "skipLabel",
+      "type": "text",
+      "label": "Skip-to-content link label",
+      "maxLength": 40,
+      "required": true
+    },
     {
       "id": "navLabel",
       "type": "text",