@cyberskill/design 1.3.8 → 1.3.10

package/docs/vi/sync.md

@@ -1,10 +1,10 @@
-# Repo ↔ Claude Design — round-trip fidelity & đồng bộ hai chiều
+# Repo ↔ môi trường authoring — round-trip fidelity & đồng bộ hai chiều
 
-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 GitHub (`cyberskill-official/design`) là **nguồn chân lý**. Session compiler (ví dụ 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. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 ## Repo có khôi phục nguyên hệ thống không?
 
-**Trong session Claude Design — có.** Mọi thứ định nghĩa hệ thống là file text/asset thuần và round-trip lossless:
+**Trong session compiler DC-capable — có.** Mọi thứ định nghĩa hệ thống là file text/asset thuần và round-trip lossless:
 - `styles.css` + `tokens/` + `base/` (mọi CSS + `tokens.json`/`tokens.js`)
 - `components/**` (`.jsx` + `.d.ts` + `.prompt.md` + `*.card.html`)
 - `templates/**/*.dc.html` (+ `ds-base.js`, `support.js`)
@@ -13,15 +13,15 @@ Repo GitHub (`cyberskill-official/design`) là **nguồn chân lý**. Session Cl
 - **`_esm/react.mjs`** — entry React bundler-native (export package mặc định; React peer). Regenerated qua `npm run build:react-entry`.
 - **`_esm/cs.mjs`** — entry ESM browser / no-build legacy (`@cyberskill/design/legacy`). Tiền tố underscore **không** nghĩa là build artifact hay gitignored ở đây (chỉ `uploads/`, `scraps/`, `_audit/exports/` là — xem Hygiene bên dưới); `_esm/` là source, cùng tầng với `templates/` hoặc `docs/`. Một lần port trước đã bỏ nó đúng vì giả định đó và làm gãy ESM smoke gate — nếu bạn port/copy cây này bằng tay, **explicit include mọi thư mục top-level danh sách này đặt tên**, đừng suy từ tiền tố `_`.
 
-- `README.md`, `CONTRIBUTING.md`, `SKILL.md`, `CLAUDE.md`, `VERSION`, `DESIGN.md` (open-spec surface generate — commit, chỉ regen qua `npm run build:design-md`, khóa bởi gate `design-md-parity`)
+- `README.md`, `CONTRIBUTING.md`, `SKILL.md`, `docs/doctrine.md`, shim host (`CLAUDE.md`), `VERSION`, `DESIGN.md` (open-spec surface generate — commit, chỉ regen qua `npm run build:design-md`, khóa bởi gate `design-md-parity`)
 
-Kéo chúng vào project mới (xem bên dưới) và compiler nhận lại như design system — nó khóa vào `styles.css`, cặp `.d.ts`/`.jsx`, HTML `@dsCard`, và `templates/`. File **derived** (`_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`) được regenerate mỗi turn từ source, nên không cần tin từ repo — chúng rebuild.
+Kéo chúng vào project mới (xem bên dưới) và compiler nhận lại như design system — nó khóa vào `styles.css`, cặp `.d.ts`/`.jsx`, HTML `@dsCard`, và `templates/`. Artifact compile đã commit (`_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`, `dist/styles.min.css`, `DESIGN.md`) là một phần hợp đồng consumer — giữ trong cây và regenerate bằng npm script đã ghi, đừng coi chúng là disposable.
 
-**Ở agent khác (Google Stitch, LLM tool generic) — một phần.** Chúng tiêu thụ được lớp **portable** — `tokens/tokens.json` + `tokens.js`, raw CSS, component `.jsx`, fonts, và Markdown docs — nhưng **không** hiểu format Design-Component `.dc.html` hay compiler điều khiển nó. Vậy agent non-Claude-Design nhận tokens, styles, và source component như file, không phải hành vi DC/tweak/compile live. Hướng những tool đó vào root **`DESIGN.md`** trước (open-spec kiểu Stitch generate: doctrine + mọi giá trị token + inventory, regen từ DTCG qua `npm run build:design-md` và khóa bởi gate `design-md-parity`), rồi `tokens.json` / `tokens.dtcg.json` và CSS cho hợp đồng máy; coi `.dc.html` + compiler là native Claude Design.
+**Ở agent khác (Google Stitch, LLM tool generic) — một phần.** Chúng tiêu thụ được lớp **portable** — `tokens/tokens.json` + `tokens.js`, raw CSS, component `.jsx`, fonts, và Markdown docs — nhưng **không** hiểu format Design-Component `.dc.html` hay compiler điều khiển nó. Vậy agent không-compiler nhận tokens, styles, và source component như file, không phải hành vi DC/tweak/compile live. Hướng những tool đó vào root **`DESIGN.md`** trước (open-spec kiểu Stitch generate: doctrine + mọi giá trị token + inventory, regen từ DTCG qua `npm run build:design-md` và khóa bởi gate `design-md-parity`), rồi `tokens.json` / `tokens.dtcg.json` và CSS cho hợp đồng máy; coi `.dc.html` + compiler là native DC.
 
 ## Đồng bộ hai chiều (repo = nguồn chân lý)
 
-Claude Design có thể **đọc/copy từ** GitHub nhưng **không push tới** nó. Vậy sync là *pull tự động, push thủ công*:
+Session compiler có thể **đọc/copy từ** GitHub nhưng thường **không push tới** nó. Vậy sync là *pull tự động, push thủ công*:
 **Bắt đầu session — pull (tin cậy, tự động):** bảo agent load repo. Nó copy cây vào project mới (đường `github_copy_files`), compiler validate, và bạn tiếp từ chân lý đã commit — không bao giờ từ project state cũ. Luôn bắt đầu đây; đừng resume từ project nửa nhớ.
 
 **Kết thúc session — push (thủ công, review):** tải project, rồi từ clone:
@@ -39,7 +39,7 @@ Diff PR là lưới an toàn — nó hiện đúng những gì đổi kể từ
 ## Hygiene giữ round-trip sạch
 - **`.gitignore`** transient (`uploads/`, `scraps/`, `_audit/exports/`); commit mọi thứ khác, **kể cả `_esm/`** (xem trên — nó là source, không phải build artifact, dù có tiền tố `_`). Compiled `_ds_bundle.js`/manifest được commit cho consumer không có bước build, nhưng kỳ vọng churn — hoặc ignore và để mỗi session regenerate.
 
-- **`VERSION` đã LAUNCH ở 1.1.0; pin theo `VERSION`** — auto-bump khi push lên `main` (`.github/workflows/version.yml` → tag `v*` → `npm-publish.yml`); owner vẫn có thể force bump. Không maintain file changelog. Continuity là git history; việc maintainer đang mở nằm ở `docs/decisions.md`.
+- **`VERSION` pin theo file** (auto-bump khi push lên `main` qua `.github/workflows/version.yml` → tag `v*` → `npm-publish.yml`; LAUNCH đầu tiên là **1.1.0**; owner vẫn có thể force bump). Không maintain file changelog. Continuity là git history; việc maintainer đang mở nằm ở `docs/decisions.md`.
 
 - **Một nguồn chân lý tại một thời điểm.** Đừng sửa repo và project Claude Design song song rồi push cả hai — pull, làm việc, push, theo thứ tự đó, để repo luôn là điểm merge.
 

package/docs/vi/template-schema-v2.md

@@ -1,6 +1,6 @@
 # Template content-schema v2 — content slot có kiểu
 
-Metadata thuần additive, opt-in: sidecar `templates/<slug>/content-schema.json` cạnh `.dc.html` của template, khai báo **kiểu** của mỗi `{{ hole }}` đã có trong template — để agent hoặc pipeline điền/validate nội dung khách thật theo chương trình mà không parse HTML hay đoán.
+Metadata thuần additive, opt-in: sidecar `templates/<slug>/content-schema.json` cạnh `.dc.html` của template, khai báo **kiểu** của mỗi `{{ hole }}` đã có trong template — để agent hoặc pipeline điền/validate nội dung khách thật theo chương trình mà không parse HTML hay đoán. Xuất bản trên Storybook **Docs** tại `design.cyberskill.world`.
 
 **Không cần đổi markup template.** `id` của slot là tên hole đã dùng trong `.dc.html` (ví dụ `{{ heroH }}`) và đã bind trong `renderVals()` của logic class — schema chỉ mô tả nó.
 

package/docs/viewer.html

@@ -43,12 +43,23 @@
   article hr{border:0;border-top:1px dashed var(--cs-color-border-default);margin:20px 0}
   article a{color:var(--cs-color-link)}article a:hover{color:var(--cs-color-link-hover)}
   #err{color:#B42318;font-family:var(--cs-font-family-mono);font-size:13px}
+  html.embed body{grid-template-columns:1fr}
+  html.embed aside{display:none}
+  html.embed main{padding:24px 32px}
   @media (max-width:640px){
     body{grid-template-columns:1fr}
     aside{border-inline-end:0;border-block-end:1px solid var(--cs-color-border-default);max-height:38vh}
     main{padding:18px 16px}
+    html.embed main{padding:18px 16px}
   }
-</style></head>
+</style>
+<script>
+(function(){
+  var q=new URLSearchParams(location.search);
+  if(q.get('embed')==='1'||q.get('chrome')==='0') document.documentElement.classList.add('embed');
+})();
+</script>
+</head>
 <body>
 <aside id="nav"><h1>CyberSkill Docs</h1>
 <div class="langtog" role="group" aria-label="Doc language"><button type="button" id="lang-en" data-lang="en">EN</button><button type="button" id="lang-vi" data-lang="vi">VI</button></div>
@@ -58,13 +69,13 @@
 <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/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']]]
+ ['Guides',[['docs/consuming.md','Consuming & upgrading'],['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/doctrine.md','Doctrine'],['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/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']]]
+ ['Maintainer',[['docs/doctrine.md','Học thuyết'],['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';
 function DOCS(){ return lang==='vi'?DOCS_VI:DOCS_EN; }

package/llms.txt

@@ -1,20 +1,23 @@
 # CyberSkill Design System
 
-> 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.
+> HTML-first, Vietnamese-first design system, current **v1.3.10** (first LAUNCH **v1.1.0**). 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 **capability** 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.10**, 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`.
+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`) needs a **Design Components compiler**. **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/doctrine.md`. Operator docs are published on the Storybook **Docs** sidebar at `design.cyberskill.world`.
 
 ## Consume by audience
 
-- **Claude Code** → [SKILL.md](SKILL.md) first, then [README.md](README.md): compose with `styles.css` + bundler `_esm/react.mjs` / legacy `_esm/cs.mjs` / `_ds_bundle.js` (prefix resolve). Optional DC templates only when the session has the compiler. Gates/`_audit/` need a full clone.
-- **Google Stitch** → [DESIGN.md](DESIGN.md) first, then this file + [tokens/tokens.dtcg.json](tokens/tokens.dtcg.json): generate **static** UI. Do **not** open or rewrite `templates/**/*.dc.html` as if they were plain HTML.
+- **DC-capable authoring** (compiler present — e.g. Claude Design, Claude Code with a full clone) → [SKILL.md](SKILL.md) first, then [README.md](README.md): compose with `styles.css` + bundler `_esm/react.mjs` / legacy `_esm/cs.mjs` / `_ds_bundle.js` (prefix resolve). Optional DC templates only when the session has the compiler. Gates/`_audit/` need a full clone.
+- **Static / open-spec** (e.g. Google Stitch) → [DESIGN.md](DESIGN.md) first, then this file + [tokens/tokens.dtcg.json](tokens/tokens.dtcg.json): generate **static** UI. Do **not** open or rewrite `templates/**/*.dc.html` as if they were plain HTML.
+- **Designers** → Storybook at `design.cyberskill.world` (`/` / `npm run storybook`): Foundations, Components, Docs, axis toolbar.
+- **Implementers (npm / Next / Vite)** → [docs/consuming.md](docs/consuming.md) + default `@cyberskill/design` React entry.
+- **Maintainers** → [docs/doctrine.md](docs/doctrine.md) + [docs/quality-gates.md](docs/quality-gates.md).
 - [styles.css](styles.css): any web / framework / email (Vue, Svelte, plain HTML, React) — link this one file for every `--cs-*` token, the `.cs-*` component classes, and the Liquid Glass surfaces. Framework-agnostic, no build step.
 - [_esm/react.mjs](_esm/react.mjs): **default** npm entry — `import { Button, … } from "@cyberskill/design"` (React peer; Next/Vite transpile). Also `@cyberskill/design/react`.
 - [_esm/cs.mjs](_esm/cs.mjs): browser / no-build legacy — `import { Button, … } from "@cyberskill/design/legacy"` (self-ensures React; still link `styles.css`). **Not for Next/SSR.**
 - [_ds_bundle.js](_ds_bundle.js): React (production) — `styles.css` + `<script src="_ds_bundle.js">`, then resolve the bundle global by prefix (its `_<projectId>` suffix is compiler-assigned and changes on re-import): `const CS = window[Object.keys(window).find(k => /^CyberSkillDesignSystem_/.test(k))]; const { Button, … } = CS`. Proven green by `_audit/consumer-smoke-test.html`. (Templates load via `ds-base.js`, which publishes a stable `window.CyberSkillDS` alias for the same reason.)
 - [tokens/tokens.json](tokens/tokens.json): design tools / native / token pipelines / other agents (Figma, Google Stitch, Style Dictionary) — every token grouped by category, plus theme/element override maps; also [tokens/tokens.js](tokens/tokens.js) (ESM) and [tokens/tokens.dtcg.json](tokens/tokens.dtcg.json) (**W3C DTCG** format for Tokens Studio for Figma / Style Dictionary). This is the canonical cross-tool contract.
 - [DESIGN.md](DESIGN.md): agents/tools that read a root DESIGN.md (Google Stitch open-spec style) — **this repo's** generated file with the brand doctrine, every token value (light + dark), and the component/template inventory. Generated from the DTCG source by `npm run build:design-md`; the `design-md-parity` gate pins it — do not hand-edit.
-- [templates/](templates/): Design Components (`templates/**/*.dc.html`) + the compiler (tweaks, `x-import`, `@dsCard` cards) for **Claude Design** only. Stitch and other non-DC tools: [templates/kitchen-sink.html](templates/kitchen-sink.html) + `.cs-*` / [examples/static-hello/](examples/static-hello/) — **not** `*.dc.html`.
+- [templates/](templates/): Design Components (`templates/**/*.dc.html`) + the compiler (tweaks, `x-import`, `@dsCard` cards) for **DC-capable authoring** only. Stitch and other non-DC tools: [templates/kitchen-sink.html](templates/kitchen-sink.html) + `.cs-*` / [examples/static-hello/](examples/static-hello/) — **not** `*.dc.html`.
 
 ## Key files
 
@@ -28,7 +31,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.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/npm-hello/](examples/npm-hello/): first registry **browser** consumer — `@cyberskill/design@1.3.10` 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 +40,15 @@ 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.3.8 (matches [package.json](package.json))
+- [docs/doctrine.md](docs/doctrine.md): expansion rule, verification depth, immutables
+- [VERSION](VERSION): pinned 1.3.10 (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.3.8` Trusted Publishing / grant pointer
+Published on Storybook **Docs** (`design.cyberskill.world`) and in [docs/viewer.html](docs/viewer.html) (EN|VI).
+
+- [docs/consuming.md](docs/consuming.md): adopting & upgrading, DC-capable vs static 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.3.10` 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
@@ -51,13 +57,14 @@ The portable contract covers browser and bundler entry points: `styles.css` · `
 - [docs/template-schema-v2.md](docs/template-schema-v2.md): typed content-slot spec for templates
 - [docs/deploy.md](docs/deploy.md): deploying the live site (Vercel / VPS / any static host)
 - [docs/live-hub.md](docs/live-hub.md): Storybook at `/` is the product surface; surface map
-- [docs/storybook.md](docs/storybook.md): host Storybook product surface at `/`
+- [docs/storybook.md](docs/storybook.md): host Storybook product surface at `/` — Docs sidebar is the published reading surface for operator docs
 - [docs/figma.md](docs/figma.md): Figma / Tokens Studio import recipe
 - [docs/vi/](docs/vi/): Vietnamese mirror of every operator-facing `docs/*.md`
 - [docs/viewer.html](docs/viewer.html): reader UI (EN|VI toggle for `docs/*.md`)
 
 ## Docs — maintainers
 
+- [docs/doctrine.md](docs/doctrine.md): expansion, verification, immutables
 - [docs/decisions.md](docs/decisions.md): recorded owner decisions + open maintainer tasks
 - [docs/ci-cd.md](docs/ci-cd.md): CI/CD automation — workflow, headless gate runner, provenance pre-check
 - [docs/quality-gates.md](docs/quality-gates.md): benchmark reference — every quality gate, its assertion, pass criterion, where it runs
@@ -66,7 +73,7 @@ The portable contract covers browser and bundler entry points: `styles.css` · `
 
 ## Non-negotiables
 
-- [CONTRIBUTING.md](CONTRIBUTING.md): the full non-negotiables list (with `docs/conventions.md`)
+- [CONTRIBUTING.md](CONTRIBUTING.md): the full non-negotiables list (with `docs/doctrine.md` and `docs/conventions.md`)
 - [tokens/colors.css](tokens/colors.css): immutable Umber/Ochre anchors · one accent per surface
 - [base/a11y.css](base/a11y.css): APCA Lc ≥ 75 body text · ≥44px touch targets · 3px ochre focus ring · honour `prefers-reduced-motion`/`prefers-contrast`
 - [docs/conventions.md](docs/conventions.md): Vietnamese-first bilingual — every UI string ships an EN + VN pair, diacritics preserved

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyberskill/design",
-  "version": "1.3.8",
+  "version": "1.3.10",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -95,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-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: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-docs-storybook-coverage.mjs && node _audit/ci/test-docs-link-check.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",

package/tokens/element-seeds.json

@@ -1,7 +1,7 @@
 {
   "$meta": {
     "system": "CyberSkill Design System",
-    "version": "1.3.8",
+    "version": "1.3.10",
     "note": "OKLCH seed contract for the 15 element packs × light/dark (30 sets). SoT for scripts/generate-element-packs.mjs — do not hand-edit tokens/elements.css. Owner bar (Jul 2026): soft/middle/deep clearly distinct; middle intensity synced across elements; harmonious role palettes; light↔dark same-hue identity. Public variant names unchanged."
   },
   "intensity": {

package/tokens/native/CSTokens.kt

@@ -1,6 +1,6 @@
 // CyberSkill Design System — native design tokens.
 // GENERATED from tokens/tokens.dtcg.json — do not hand-edit; regenerate on token change.
-// release v1.3.8 · source sha256 5d7d5587bec9b99e…
+// release v1.3.10 · source sha256 1b606c94a5612b02…
 // conversions: rem→px at 16 · em→…Em relative doubles · rgba alpha→ARGB byte (round(a*255)) · durations in ms
 // dark element packs: see $extensions.overrides.elementsDark
 // provenance: tokens/provenance.json · parity gate: _audit/token-pipeline-test.html

package/tokens/native/CSTokens.swift

@@ -1,6 +1,6 @@
 // CyberSkill Design System — native design tokens.
 // GENERATED from tokens/tokens.dtcg.json — do not hand-edit; regenerate on token change.
-// release v1.3.8 · source sha256 5d7d5587bec9b99e…
+// release v1.3.10 · source sha256 1b606c94a5612b02…
 // conversions: rem→px at 16 · em→…Em relative doubles · rgba alpha→ARGB byte (round(a*255)) · durations in ms
 // dark element packs: see $extensions.overrides.elementsDark
 // provenance: tokens/provenance.json · parity gate: _audit/token-pipeline-test.html

package/tokens/native/cs_tokens.dart

@@ -1,6 +1,6 @@
 // CyberSkill Design System — native design tokens.
 // GENERATED from tokens/tokens.dtcg.json — do not hand-edit; regenerate on token change.
-// release v1.3.8 · source sha256 5d7d5587bec9b99e…
+// release v1.3.10 · source sha256 1b606c94a5612b02…
 // conversions: rem→px at 16 · em→…Em relative doubles · rgba alpha→ARGB byte (round(a*255)) · durations in ms
 // dark element packs: see $extensions.overrides.elementsDark
 // provenance: tokens/provenance.json · parity gate: _audit/token-pipeline-test.html

package/tokens/provenance.json

@@ -1,10 +1,10 @@
 {
   "system": "CyberSkill Design System",
-  "release": "1.3.8",
+  "release": "1.3.10",
   "source": "tokens/tokens.dtcg.json",
-  "sourceSha256": "5d7d5587bec9b99e720da1f1ceba6a6804ccc0547243ae47897b6e34cc0f03ce",
+  "sourceSha256": "1b606c94a5612b02a1c9f0e48ef12443e5c5f7da653ade97c64fe1f520ba532a",
   "dtcgStamp": {
-    "version": "1.3.8",
+    "version": "1.3.10",
     "generated": "2026-07-23"
   },
   "conversions": {
@@ -36,17 +36,17 @@
     {
       "file": "tokens/native/CSTokens.swift",
       "lang": "swift",
-      "sha256": "dcabf92440dc19358959f30db2b9899a43da78c57cc9c6ca81e18e506497119f"
+      "sha256": "55d1be1a5a23ba75230d6110bff2d17c9fe88cd3f158ac9f992e94950a792edc"
     },
     {
       "file": "tokens/native/CSTokens.kt",
       "lang": "kotlin",
-      "sha256": "9a2599519538b6aeaded59c09076244501e09b9b48100ea3caf570391d3cd5a3"
+      "sha256": "1b0ff7f07cdff7f5134169e2a421f0d63660c3cac532c198feaed7ef0532108d"
     },
     {
       "file": "tokens/native/cs_tokens.dart",
       "lang": "dart",
-      "sha256": "4b012288aee948f63a59bd056a53cc04a82ee97a754fdda5d7e176ca9cdef0d4"
+      "sha256": "e312abf70155c54cc9f0369c08f896f8eb230965146804a22a979c159df7b474"
     }
   ]
 }

package/tokens/tokens.dtcg.json

@@ -3,7 +3,7 @@
   "$extensions": {
     "com.cyberskill": {
       "system": "CyberSkill Design System",
-      "version": "1.3.8",
+      "version": "1.3.10",
       "generated": "2026-07-23",
       "source": "tokens/tokens.json",
       "note": "Scope overrides (dark/system theme · 15 element×variant packs) are carried under $extensions.overrides keyed by CSS selector — apply the matching selector on :root/ancestor to activate.",

package/tokens/tokens.js

@@ -1,8 +1,8 @@
-// CyberSkill design tokens — generated from tokens/*.css (v1.3.8). Do not edit by hand.
+// CyberSkill design tokens — generated from tokens/*.css (v1.3.10). Do not edit by hand.
 export const tokens = {
   "$meta": {
     "system": "CyberSkill Design System",
-    "version": "1.3.8",
+    "version": "1.3.10",
     "generated": "2026-07-23",
     "note": "Generated from tokens/*.css. Root grouped by category; theme/element scopes carry overrides only. Regenerate after any token change (see docs/conventions.md)."
   },

package/tokens/tokens.json

@@ -1,7 +1,7 @@
 {
   "$meta": {
     "system": "CyberSkill Design System",
-    "version": "1.3.8",
+    "version": "1.3.10",
     "generated": "2026-07-23",
     "note": "Generated from tokens/*.css. Root grouped by category; theme/element scopes carry overrides only. Regenerate after any token change (see docs/conventions.md)."
   },