@cyberskill/design 1.2.0 → 1.3.9

package/docs/vi/consuming.md

@@ -1,10 +1,14 @@
 # Tiêu thụ & nâng cấp CyberSkill Design System
 
-Cách mọi project — do người hoặc agent điều khiển — áp dụng design system HTML-first này, và cách nhận update an toàn.
+Cách mọi project — do người hoặc agent điều khiển — áp dụng design system HTML-first này, và cách nhận update an toàn. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **Tên package:** `@cyberskill/design` (xem `package.json`). Không coi `@cyberskill/react` lịch sử là đường cài cho monolith này.
 
-## Claude Code vs Google Stitch
+## Khi nào dùng
+
+Bạn đang cài, liên kết, hoặc nâng cấp hệ thống trong sản phẩm khác. Maintainer mở rộng hệ thống bắt đầu từ `docs/doctrine.md`.
+
+## Capability paths (DC-capable vs static)
 
 | Consumer | Bắt đầu tại | Hoạt động hôm nay | Không làm |
 |---|---|---|---|
@@ -17,11 +21,11 @@ Cách mọi project — do người hoặc agent điều khiển — áp dụng
 
 **Tín hiệu release:** đã LAUNCH ở **1.1.0**; **pin theo `VERSION`** (không CHANGELOG). Coi **git tip SHA** là chân lý kỹ thuật; đọc điểm nổi bật sản phẩm curated trong `docs/release-notes.md`.
 
-## Đường nhanh cho AI agent (Claude Code, hoặc điều khiển một agent)
+## Đường nhanh cho AI agent (DC-capable authoring, hoặc điều khiển một agent)
 
 **Bạn nhận:** `styles.css` (400+ token + class `.cs-*` + bề mặt Liquid Glass, `@import` `tokens/` + `base/`) · `_ds_bundle.js` (React component đã compile, không cần build) · `_esm/react.mjs` (entry React bundler-native — React là peerDependency; mặc định `exports["."]`) · `_esm/cs.mjs` (browser / no-build legacy qua `exports["./legacy"]`) · `_ds_manifest.json` (inventory máy đọc được) · mỗi component `Name.d.ts` (API) + `Name.prompt.md` (brief dùng) · `tokens/tokens.dtcg.json` (W3C DTCG) + `tokens.json`/`tokens.js`.
 
-**Checkout repo** — clone hoặc copy cả cây; mọi thứ là static đường dẫn tương đối. Điểm vào: Storybook trên host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (mọi component live, portable) · `templates/<slug>/` (điểm bắt đầu copy được — DC cho Claude Design; kitchen-sink / `.cs-*` cho Stitch). Đọc `SKILL.md` trước khi author bất kỳ thứ gì on-brand; reader Stitch bắt đầu tại `DESIGN.md`. Bản đồ sâu hơn ở `llms.txt` (inventory) và file này (hướng dẫn adopt + upgrade đầy đủ bên dưới).
+**Checkout repo** — clone hoặc copy cả cây; mọi thứ là static đường dẫn tương đối. Điểm vào: Storybook trên host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (mọi component live, portable) · `templates/<slug>/` (điểm bắt đầu copy được — DC khi có compiler; kitchen-sink / `.cs-*` cho Stitch / static). Đọc `SKILL.md` trước khi author bất kỳ thứ gì on-brand; reader Stitch bắt đầu tại `DESIGN.md`. Bản đồ sâu hơn ở `llms.txt` (inventory) và file này (hướng dẫn adopt + upgrade đầy đủ bên dưới).
 
 **Sau import — chứng minh health.** Mở `_audit/run.html`, để bảng gate chạy xong (mọi fast gate). Tất cả xanh = bản copy nhất quán nội bộ (contrast, docs, portability, tokens, consumer path, behavior, a11y, stories, bilingual parity). Chỉ full-clone — `_audit/` không nằm trong tarball npm.
 
@@ -34,7 +38,7 @@ Cách mọi project — do người hoặc agent điều khiển — áp dụng
 
 - Anchors (Umber/Ochre), tên class `.cs-*`, tên token `--cs-*` là hợp đồng ổn định.
 
-- Mở rộng hệ thống? Theo `CONTRIBUTING.md` (Expansion Rule: lan tới mọi deliverable trong một change; verify qua `_audit/`).
+- Mở rộng hệ thống? Theo `docs/doctrine.md` và `CONTRIBUTING.md` (Expansion Rule: lan tới mọi deliverable trong một change; verify qua `_audit/`).
 
 ## Adopt qua npm (tùy chọn)
 
@@ -54,7 +58,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 +68,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 +80,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 +88,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 +96,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,8 @@
 # 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.9.
+
+Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **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 +92,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

@@ -1,6 +1,6 @@
 # Conventions — authoring CyberSkill DS
 
-Cho người và agent *mở rộng hệ thống này*. (Consumer: đọc `SKILL.md`.) Compiler là nguồn chân lý cho đếm; prose mô tả hình dạng, không bao giờ số.
+Cho người và agent *mở rộng hệ thống này*. (Consumer: đọc `SKILL.md`.) Học thuyết mở rộng và kiểm chứng: `docs/doctrine.md`. Compiler là nguồn chân lý cho đếm; prose mô tả hình dạng, không bao giờ số. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## Quy tắc expansion
 
@@ -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

@@ -1,6 +1,6 @@
 # Quyết định (maintainer)
 
-Các lựa chọn của owner định hình CI, đồng bộ Figma, và phân phối. How-to nằm ở `docs/figma.md` và `docs/ci-cd.md` — file này chỉ là biên bản quyết định. Không phải hướng dẫn consumer.
+Các lựa chọn của owner định hình CI, đồng bộ Figma, và phân phối. How-to nằm ở `docs/figma.md` và `docs/ci-cd.md` — file này chỉ là biên bản quyết định. Không phải hướng dẫn consumer. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## 1. Whole-set audits trên mọi PR
 
@@ -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

@@ -1,5 +1,7 @@
 # Deploy site Atomic live (Vercel / VPS / mọi static host)
 
+Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
+
 Hai track:
 
 1. **Design system portable (consumers)** — vẫn là cây file tĩnh: không cần bundler. Link `styles.css` + tùy chọn `_ds_bundle.js` / ESM. Claude Design, Google Stitch, và product app không cần Node hay Storybook.
@@ -48,11 +50,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 +66,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 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 +95,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
 

package/docs/vi/design-styles.md

@@ -1,6 +1,6 @@
 # Phong cách thiết kế
 
-Các trục styling sống là **Theme × Element × Language × Style**. Pack Style duy nhất hôm nay là **liquid-glass** (vắng `data-cs-style` ≡ liquid-glass — cùng pattern mặc định với light theme / Thổ middle).
+Các trục styling sống là **Theme × Element × Language × Style**. Pack Style duy nhất hôm nay là **liquid-glass** (vắng `data-cs-style` ≡ liquid-glass — cùng pattern mặc định với light theme / Thổ middle). Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 | Trục | Cách đặt | Thay đổi gì |
 |---|---|---|

package/docs/vi/doctrine.md

@@ -0,0 +1,51 @@
+# Học thuyết
+
+Quy tắc chuẩn cho việc mở rộng và kiểm chứng Hệ thống Thiết kế CyberSkill. File theo từng host (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`) chỉ là shim trỏ về đây. Người tiêu thụ bắt đầu từ `SKILL.md` và thanh bên **Docs** trên Storybook tại `design.cyberskill.world`. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
+
+## Khi nào dùng
+
+- Bạn đang thêm hoặc đổi element, variant, icon, component, vai trò token, ngôn ngữ, hoặc mẫu template.
+- Bạn đang kiểm chứng một thay đổi trước khi tuyên bố xong.
+- Bạn cần các bất biến không được thiết kế lại tùy tiện.
+
+## Ngoài phạm vi
+
+File này không phải changelog, không phải sổ đăng ký sản phẩm, và không phải hướng dẫn tiêu thụ. Ánh xạ sản phẩm → element nằm ở `docs/products.md`. Đường dẫn adoption nằm ở `docs/consuming.md`.
+
+## Quy tắc mở rộng
+
+Khi **bất kỳ thứ gì** trong hệ thống này lớn lên, cập nhật **mọi deliverable trong cùng một thay đổi**:
+
+1. Token và nguồn (`tokens/`, component `.jsx` + `.d.ts` + `.prompt.md`).
+2. Thẻ mẫu (guidelines cộng thẻ nhóm component) **và mọi trang guideline liên quan**.
+3. **Tất cả** template (enum tweak, bản đồ EL/EX, accent đã quét).
+4. UI kit — trang kit trung thành Thổ; demo trục qua thanh công cụ Storybook và Atomic View (Identity Lab đã nghỉ).
+5. Docs: README (số đếm theo compiler), `SKILL.md`, file này, `docs/conventions.md`, **và mọi tài liệu liên quan mà thay đổi chạm tới** (README kit, `docs/products.md`, tái sinh `docs/contrast-report.md` sau khi đổi token). Xuất bản cùng các trang đó qua Storybook Docs (xem `docs/storybook.md`). **`VERSION` tự tăng khi đẩy lên `main`** từ Conventional Commits (`.github/workflows/version.yml` → tag `v*` → `npm-publish.yml`); chủ sở hữu vẫn có thể ép bump qua `Release-As:` / `workflow_dispatch`. **Không duy trì file changelog** — LAUNCHED tại **1.1.0**; pin theo `VERSION`. Tính liên tục là lịch sử git cộng Release Notes đã chọn lọc.
+6. Bề mặt duyệt và sức khỏe: component mới hoặc đổi được một story Atomic View trong `guidelines/atomic-view.html` (cộng playground sống nếu có prop chỉnh được — `_audit/story-coverage.html` bắt story) và phủ hành vi trong `_audit/component-behavior-test.html` nếu tương tác; mọi trục, công cụ, hoặc tab mới được nối vào `_audit/index.html` và Storybook **Status** (`_audit/run.html` full-bleed — `dashboard.html` chỉ redirect); gate xác định tương ứng được thêm hoặc cập nhật (`contrast-guard` cho quy tắc màu mới, `token-contract` cộng ma trận contrast cho token, `story-coverage` cho component, `docs-storybook-coverage` cho docs đã xuất bản).
+
+**Gate:** `check_design_system` sạch (chỉ phiên compiler) **cộng** `_audit/run.html` (mọi gate nhanh) xanh **cộng** `docs-consistency` xanh **cộng** grep enum hoặc danh sách cũ để chứng minh không bỏ sót. Trên clone portable, tương đương là bảng nhanh cộng `npm run test:unit`.
+
+Ranh giới phạm vi đã ghi (học thuyết, không phải lỗ hổng): trang UI-kit vẫn tái tạo trung thành Thổ; song ngữ EN·VN phủ email cộng tài liệu team, pháp lý, và tài chính (tài sản khách/truyền thông ưu tiên EN); chữ không bao giờ nằm trên `-accent` tông giữa.
+
+## Độ sâu kiểm chứng
+
+Kiểm sâu, không điểm danh bề mặt. Phủ **cả tập và mọi trạng thái liên quan** — không lấy mẫu. Ưu tiên quét xác định, theo chương trình chạm **mọi** mục (ví dụ parity khóa EN/VI, phủ lỗ, và quét rò trên mọi template; probe computed-style và overflow ở mọi breakpoint qua harness `_audit/` dùng `__dcSetProps` cho ngôn ngữ và postMessage `__dc_theme` cho theme), rồi thêm xác nhận visual hoặc export đại diện. Vài ảnh chụp là bằng chứng, không phải chứng minh. Không tuyên bố đã kiểm vì “spot-check” khi kiểm đủ là khả thi; nếu kiểm đủ thật sự không khả thi, nói rõ và nêu cái đã và chưa phủ. Ngôn ngữ, theme, và trạng thái responsive mỗi cái một lượt — một ngôn ngữ, chiều rộng, hoặc theme render sạch không phải bằng chứng cho cái khác.
+
+## Bất biến
+
+| Bất biến | Giá trị |
+|---|---|
+| Khẩu hiệu | *Turn Your Will Into Real* / *Hiện Thực Hoá Ý Chí* |
+| Thương hiệu chính | Umber `#45210E` |
+| Accent chính | Ochre `#F4BA17` |
+| Giọng | ấm · thẳng · thật · tôn trọng (cả bốn cùng lúc) |
+| Ngôn ngữ | Việt Nam trước; mọi chuỗi UI gửi cặp EN + VN |
+| Sàn a11y | APCA Lc ≥ 75 chữ thân; không bao giờ gỡ focus ring; mục tiêu chạm ≥ 44px |
+| Trục | Theme × Element × Language × Style (độc lập) |
+| Gói Style | liquid-glass (gói duy nhất; vắng ≡ mặc định) |
+
+Một accent mỗi bề mặt. Trạng thái ngữ nghĩa và chỉ báo focus tổ hợp (viền text-primary + hào quang ochre) không bao giờ elemental. Lumi luôn vàng trong mọi element.
+
+## Tài liệu đã xuất bản
+
+Docs operator và entrance là markdown chuẩn trong kho. Chúng **cũng** bắt buộc trên site Storybook sống: mọi trang được theo dõi phải xuất hiện trên thanh bên Docs và trong Thư viện tài liệu (`docs/viewer.html`). Tài liệu chỉ có trong repo mà không nằm trong tập xuất bản đó là lỗi, bị `docs-storybook-coverage` và `docs-link-check` bắt.

package/docs/vi/figma.md

@@ -1,5 +1,7 @@
 # Figma / Tokens Studio — ghi chú
 
+
+Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 ## Những gì ship trong repo
 - Design tokens dạng CSS + DTCG (`tokens/tokens.dtcg.json`) kèm mirror native Swift/Kotlin/Flutter.
 - UI kits dưới `ui_kits/` là tái tạo HTML giữ pixel-faithful theo doctrine brand (kit Thổ-first; demo trục ở Storybook / Atomic View).

package/docs/vi/live-hub.md

@@ -1,5 +1,7 @@
 # Live hub = Storybook
 
+Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
+
 ## Quyết định
 
 **Storybook là live interactive hub duy nhất** cho operator trên `design.cyberskill.world`. Không có trang Live View riêng và không còn shell dashboard HTML làm sản phẩm. Production **`/`** là Storybook.
@@ -8,7 +10,7 @@
 
 | Nhóm | Vai trò |
 |---|---|
-| **Docs** | Hướng dẫn MDX công khai (consuming, deploy, conventions, styles, products, schema, Figma, contrast, voice, axes) |
+| **Docs** | Docs operator đã xuất bản: **Start** (Introduction, README, SKILL, Contributing, llms, Library) · **Guides** (consuming, grant, deploy, schema, conventions, styles, products, Figma, contrast, storybook, live-hub, runbook phát hành, benchmark, …) · **Maintainers** (học thuyết, decisions, CI/CD, quality gates, sync). MDX curated cộng một mục sidebar mỗi trang tracked. EN·VI qua Thư viện tài liệu (`/docs/viewer.html`) |
 | **Foundations** | Colors, typography, spacing, elevation, motion, elements |
 | **Components** | Thư viện CSF đầy đủ |
 | **Release Notes** | Prose sản phẩm curated (**không CHANGELOG.md**) |

package/docs/vi/products.md

@@ -1,6 +1,6 @@
 # Product registry — ánh xạ element
 
-> **Đã khóa / locked** (Th7 2026). Registry product → element chuẩn cho agent và kit. **Không** invent ánh xạ product → element mới; thêm hoặc đổi hàng chỉ qua quyết định maintainer trong `docs/decisions.md`.
+> **Đã khóa / locked** (Th7 2026). Registry product → element chuẩn cho agent và kit. **Không** invent ánh xạ product → element mới; thêm hoặc đổi hàng chỉ qua quyết định maintainer trong `docs/decisions.md`. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **Nguồn chân lý.** Ánh xạ sản phẩm portfolio CyberSkill sang pack element Ngũ Hành. Một element mỗi sản phẩm; accent phụ chỉ trong gradient wash theo Tương sinh.