@cyberskill/design 1.1.1 → 1.3.8

package/docs/benchmark-rubric.md

@@ -23,7 +23,7 @@ Self-audit checklist for evolving CyberSkill Design System — external standard
 | One element per surface; Tương sinh gradients only | products registry · conventions |
 | Product→element registry locked; UI kits Thổ-faithful | [`docs/products.md`](products.md) |
 | Expansion Rule completeness + `_audit/run.html` green + docs EN·VI parity | CLAUDE.md · docs-consistency · docs-lang-parity |
-| VERSION **1.1.1** post-LAUNCH | version-stamp · docs-consistency |
+| VERSION tracks file (LAUNCHED 1.1.0; auto-bump on main) | version-stamp · docs-consistency |
 | Element packs from seeds only (30 sets) | `element-geometry` · `tokens:elements` |
 
 ## Style expansion checklist (`data-cs-style`)

package/docs/ci-cd.md

@@ -1,27 +1,32 @@
 # CI/CD — automating the gate board
 
+**Release how-to (authoritative):** [`docs/release-runbook.md`](./release-runbook.md) — trigger → version → tag → npm OIDC → Vercel; SBOM + Scorecard; nightly failure alerting.
+
 **Gate CI** (this workflow) still treats the design system as a static tree: serve the repo, open `_audit/run.html` headlessly, read verdict globals. No product bundler is required for gates.
 
 **Host deploy** (Vercel, separate from this workflow) does run `npm install` + `npm run build:site` so Storybook ships as the product surface at `/` — see `docs/deploy.md` and `docs/storybook.md`. That host packaging path is not required for consuming projects or for the gate jobs below.
 
 ## Badge
 
-[![Design System Gates](https://github.com/cyberskill-official/design-system/actions/workflows/design-system-gates.yml/badge.svg)](https://github.com/cyberskill-official/design-system/actions/workflows/design-system-gates.yml)
+[![Design System Gates](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml/badge.svg)](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml)
 
 ## What's wired up (`.github/workflows/design-system-gates.yml`)
 
 1. **`fast-gates`** — `npm ci` + cached Playwright Chromium, serves the repo, opens `_audit/run.html` headlessly (`_audit/ci/run-gates.mjs`), fails on any hard-gate failure. Uploads import-report on failure. New rows added to the board (the Jul 2026 hardening added 8: token-format-parity, version-stamp, support-runtime-identity, package-exports-integrity, template-lang-parity, dtcg-typing, design-md-parity, bundle-freshness) are picked up automatically — the runner reads `window.__run`, not a job-side gate list.
 2. **`token-provenance`** — browser-free Node check that natives + `provenance.json` match DTCG source sha-256.
 3. **`unit-tests`** — `npm run test:unit` (11 plain-Node contract tests; wired into CI by the Jul 2026 hardening — previously local-only). Includes `test-element-packs` (`node scripts/generate-element-packs.mjs --check` freshness).
-4. **`node-prechecks`** — browser-free Node authorities: `_audit/ci/check-bundle-freshness.mjs` (the bundle-freshness source of truth — full source discovery incl. new/deleted files; the board row only re-hashes header-recorded files) and `scripts/generate-design-md.mjs --check` (root `DESIGN.md` byte-equals regeneration).
+4. **`node-prechecks`** — browser-free Node authorities: `_audit/ci/check-bundle-freshness.mjs` (the bundle-freshness source of truth — full source discovery incl. new/deleted files; the board row only re-hashes header-recorded files), `scripts/generate-design-md.mjs --check` (root `DESIGN.md` byte-equals regeneration), `scripts/flatten-styles.mjs --check` + `scripts/generate-contrast-report.mjs --check` (FIND-026), and `_audit/ci/check-manifest-coverage.mjs` (FIND-078).
+4b. **`storybook-build`** — `npm run build:storybook` then `test-storybook-freshness.mjs --require` (FIND-074 / FIND-075). A Storybook break fails CI before deploy.
 5. **`docs-consistency-blocker`** — `docs-consistency` + `bilingual-parity` merge blockers.
 6. **`whole-set-audits`** — owner decision B: every push/PR, plus nightly `0 3 * * *` and `workflow_dispatch` (responsive + language + theme overflow, ~15–20 min).
 7. **`figma-variables-push`** — on `main` push + manual. **Empty `FIGMA_TOKEN` / `FIGMA_FILE_KEY` soft-skip** (exit 0 + report — same honesty as Code Connect). Owner decision A (non-Enterprise): Variables REST also **soft-skips on API 403** (and related plan/scope failures) after secrets prove file open. Soft-skip ≠ live Variables sync. See `docs/figma.md`.
 8. **`code-connect`** — on PR + `main` + manual. Decision 1C: dry-run always (config + 105 mappings); publish soft-skips when `FIGMA_TOKEN` / `FIGMA_FILE_KEY` missing or API 403/404/429. See `docs/figma.md`.
-9. **`regenerate-tokens`** (pull requests) + **`regenerate-tokens-push`** (push to `main` / schedule / manual) — path filter covers element seeds/packs (`element-seeds.json`, `elements.css`, JSON/JS/DTCG mirrors, `generate-element-packs.mjs`) plus natives / `VERSION`. Regeneration runs `npm run tokens:elements` then `node _audit/ci/generate-native-tokens.mjs`. On a **pull request** the job runs with `contents: read`, never pushes, and **exits 1** on drift: run both locally and commit. Only the push/schedule/manual twin holds `contents: write` and auto-commits with `DS_PUSH_TOKEN` (or `github.token`).
-10. **`npm-hello-smoke`** — registry consumer proof: `cd examples/npm-hello && npm ci && npm run smoke` (**hard fail**; package is public). Path-filtered on push/PR when `examples/npm-hello/**`, package publish surface, or this workflow changes; always on schedule / `workflow_dispatch`.
+9. **`regenerate-tokens`** (pull requests) + **`regenerate-tokens-push`** (push to `main` / schedule / manual) — path filter covers element seeds/packs (`element-seeds.json`, `elements.css`, JSON/JS/DTCG mirrors, `generate-element-packs.mjs`) plus natives / `VERSION`. Regeneration runs `npm run tokens:elements` then `node _audit/ci/generate-native-tokens.mjs`. On a **pull request** the job runs with `contents: read`, never pushes, and **exits 1** on drift: run both locally and commit (PR-required freshness). Only the push/schedule/manual twin holds `contents: write` and may auto-commit with `PUSH_TOKEN` (or `github.token`). Auto-commits **do not** use `[skip ci]` — the pushed tip re-enters the gate board (FIND-021 / TASK-IMP-008); a deterministic second pass is a no-op.
+10. **`npm-hello-smoke`** — registry consumer proof for `@cyberskill/design@$VERSION` (**fail-closed**, FIND-087): `examples/npm-hello` → registry `npm install` + `npm run smoke`. If the exact VERSION is **not** on the registry, the job **fails** (no soft-skip pack proof on `cyberskill-official/design`). Forks may opt into local-pack proof only by setting repo variable **`NPM_HELLO_ALLOW_LOCAL_PACK=true`**. Path-filtered on push/PR when `examples/npm-hello/**`, package publish surface, or this workflow changes; always on schedule / `workflow_dispatch`.
+
+Separate workflow **`version`** (`.github/workflows/version.yml`): on push to `main`, Conventional-Commit bump of `VERSION` + stamp shippable artifacts; then regenerates natives/provenance hashes and `npm run build:bundle` so tip stays gate-clean; commits `chore(release): X.Y.Z`, pushes, and tags `vX.Y.Z`. Skips its own release commits (loop-safe). Owner can force a level via `workflow_dispatch` or a `Release-As:` trailer. Needs `contents: write`. Checkout uses `secrets.PUSH_TOKEN || github.token` — if branch protection requires status checks (or blocks `github.token`), set repository secret **`PUSH_TOKEN`** (fine-grained PAT with Contents: Read and write); otherwise the bump computes but the push soft-warns and does not land.
 
-Separate workflow **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + `v*` tags; pack dry-run always; publish via **npm Trusted Publishing (OIDC)** (`id-token: write`, no `NPM_TOKEN` on the publish step). Soft-skips on auth / 403 / 404 / EOTP / version conflict. version is **1.1.1**; license **UNLICENSED**. Trusted Publisher on npmjs must match workflow filename `npm-publish.yml`. Package Publishing access is **Require 2FA and disallow tokens** (OIDC still works; classic tokens rejected).
+Separate workflow **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + `v*` tags (normally created by `version.yml`); pack dry-run always; publish via **npm Trusted Publishing (OIDC)** (`id-token: write`, no `NPM_TOKEN` on the publish step). Soft-skips only **`already_published`** and true **non-GHA** `missing_secrets`. On tag / `workflow_dispatch`, **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** **fail closed**. Post-publish asserts `npm view @cyberskill/design@VERSION` **and** `dist-tags.latest === VERSION` (FIND-094). License **UNLICENSED**. Trusted Publisher on npmjs must match workflow filename `npm-publish.yml` for repo **`cyberskill-official/design`** (FIND-088). Package Publishing access is **Require 2FA and disallow tokens** (OIDC still works; classic tokens rejected).
 
 Separate workflow **`native-store`** (`.github/workflows/native-store.yml`): PR + `main` (path-filtered) + `workflow_dispatch`; scaffold dry-run always; signed-release check soft-skips without `ASC_KEY_ID` / `ASC_ISSUER_ID` / `ASC_KEY_P8` / `PLAY_SERVICE_ACCOUNT_JSON`. **Never submits** to App Store / Play — samples remain samples. See `examples/native/README.md`.
 
@@ -40,16 +45,18 @@ Node **22** on runners (avoids Node 20 action deprecation). Playwright browser c
 
 ## Token auto-commit permissions
 
-Only `regenerate-tokens-push` requests `permissions: contents: write`; the pull-request twin `regenerate-tokens` stays on `contents: read` and checks out without persisted credentials, so a PR can never trigger a bot push. If org locks the default token to read-only, set repository secret `DS_PUSH_TOKEN` (fine-grained PAT, Contents read/write) or unlock write at org Actions settings. See earlier notes in git history / org settings.
+`regenerate-tokens-push` and `version.yml` request `permissions: contents: write` and check out with `secrets.PUSH_TOKEN || github.token`. The pull-request twin `regenerate-tokens` stays on `contents: read` and never pushes. If rulesets/branch protection require status checks before push (or lock the default Actions token), set repository secret **`PUSH_TOKEN`** (fine-grained PAT, Contents: Read and write on this repo) or allow GitHub Actions to bypass the ruleset. Without that, bot pushes soft-warn and exit 0; content drift is still hard-failed by `token-provenance` / fast-gates / `node-prechecks`.
+
+## Branch protection (recommended) — NV-18.1 out-of-band
 
-## Branch protection (recommended)
+**NV-18.1 (assessment):** which checks are **required** to merge to `main`, whether administrators are included, and whether CODEOWNERS / review / conversation-resolution are enforced are **GitHub settings, not in the repo**. Observed state from a clone alone: **unknown / confirm out-of-band**. Do not invent live ruleset values from workflow YAML.
 
-Require status checks on `main` before merge:
+**Recommended** (documentation only — apply in GitHub Settings → Branches / Rulesets, or via admin `gh api`):
 
 - `fast-gates`
 - `docs-consistency-blocker`
 
-Optional: `whole-set-audits` (long). Configure under repo **Settings → Branches** or via `gh api` (admin).
+Optional: `whole-set-audits` (long).
 
 ## Running locally
 
@@ -72,11 +79,11 @@ node _audit/ci/generate-native-tokens.mjs
 - **Side-by-side visual / component baseline rows** — advisory only (drift judged by eye). Playwright `%` pixel compare is a **hard** gate (`pixel-diff` job + board Pixel CI row).
 - **Figma Variables** — soft-skip when secrets missing (same honesty as Code Connect) or Variables write hits non-Enterprise / API **403**; report artifact records the skip. Soft-skip ≠ live sync.
 - **Code Connect publish** — soft-skip when secrets missing or API 403/404/429 (Decision 1C).
-- **npm publish** — Trusted Publishing (OIDC) on `npm-publish.yml`; soft-skip on auth / conflict (Decision 1C).
+- **npm publish** — Trusted Publishing (OIDC) on `npm-publish.yml`; soft-skip on `already_published` / non-GHA `missing_secrets` only; on GHA release **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** fail closed + post-publish version **and** `dist-tags.latest` check (Decision §7 / FIND-020 / FIND-094).
 - **Native store signed release** — soft-skip when `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` absent (Decision 1C); store submit stays disabled.
-- **npm-hello registry smoke** — **hard fail** (`examples/npm-hello` → `npm ci` + `npm run smoke`); proves the public `@cyberskill/design` install path (not soft-skip).
+- **npm-hello registry smoke** — **fail-closed** (`examples/npm-hello` → registry install + `npm run smoke`); missing `@cyberskill/design@$VERSION` fails the job (FIND-087). Local-pack proof is fork opt-in only (`NPM_HELLO_ALLOW_LOCAL_PACK`).
 
-A green `figma-variables-push` or `code-connect` job — and therefore a green badge or Status row — only means the job exited 0; it does **not** prove a live Figma sync, because a soft-skip and a real publish look identical from outside. Open the run's report artifact (`figma-push-report.json` / `code-connect-report.json`) to see which one happened.
+A green `figma-variables-push` or `code-connect` job still exits 0 on Decision 1C soft-skip, but FIND-095 makes the outcome visible on the public run page via `$GITHUB_STEP_SUMMARY` plus a distinct annotation (`::error::` on schedule/main, `::warning::` elsewhere) — soft-skip is never identical silent green to a live publish. Report artifacts (`figma-push-report.json` / `code-connect-report.json`) still carry detail.
 
 ## Soft-skip dry-runs (local)
 

package/docs/consumer-grant.md

@@ -19,10 +19,13 @@ CyberSkill grants **CyberSkill** (the company and its product engineering teams
 
 The package remains **UNLICENSED**. Installing from the npm registry does **not** by itself grant redistribution rights. Redistribution outside the products above — including publishing a fork, re-licensing, or shipping the package as a dependency of an unrelated third-party product — needs a **further written grant** recorded in this file (or a superseding instrument).
 
+**Third-party carve-out:** OFL fonts under `fonts/`, MIT-vendored runtimes under `_vendor/`, and other assets listed in root `THIRD-PARTY-NOTICES.md` keep their **upstream** licenses. The UNLICENSED assertion and this grant do **not** supersede those terms; redistributors must comply with `fonts/OFL.txt` and the notices file.
+
 ## Scope notes
 
 - **Clone / subtree / static link** of this repo for the same products is covered the same way as an npm install.
 - **Host-only tooling** (Storybook, `_audit/`) is not part of the npm tarball and is not redistributable under this grant.
+- **Third-party notices:** see root `THIRD-PARTY-NOTICES.md` and `fonts/OFL.txt`.
 - Adding a new CyberSkill product: update `docs/products.md` (+ VI) via a maintainer decision, then add the product row here in the same change.
 - Approving an **external** team or client: append a dated grant stanza below (team/org, named products, contact). Do not invent product → element mappings here — that stays in `docs/products.md`.
 

package/docs/consuming.md

@@ -11,11 +11,11 @@ How any project — human-driven or agent-driven — adopts this HTML-first desi
 | **Claude Code** | `SKILL.md` → `README.md` → `styles.css` + bundler `@cyberskill/design` / legacy `_esm/cs.mjs` / `_ds_bundle.js` (prefix resolve) | Strong — rules, components, prompts; gates via full clone | Hardcode the bundle suffix; treat Storybook host as the portable contract; import `_esm/cs.mjs` or `@cyberskill/design/legacy` into Next/SSR bundlers |
 | **Google Stitch** | `DESIGN.md` → `llms.txt` → `tokens/tokens.dtcg.json` | Strong for doctrine + tokens + static `.cs-*` HTML | Treat `templates/**/*.dc.html` as SoT — no tweaks / `__dcSetProps` / DC compiler |
 | **Claude Design** | Full repo + DC compiler | Full fidelity (tweaks, `x-import`, bilingual templates) | Skip the sync loop in `docs/sync.md` |
-| **npm** | `@cyberskill/design` | **1.1.1** on registry; CI Trusted Publishing; grant in `docs/consumer-grant.md` | Treat registry install as a public license (still UNLICENSED) |
+| **npm** | `@cyberskill/design` | Registry version tracks repo `VERSION` (auto-bump → tag → Trusted Publishing); grant in `docs/consumer-grant.md` | Treat registry install as a public license (still UNLICENSED) |
 
 **Stitch DC rule:** Stitch (and any non-DC tool) must **not** consume `*.dc.html` as source of truth. Use static export patterns, `templates/kitchen-sink.html`, `examples/static-hello/`, and `.cs-*` classes from `styles.css`.
 
-**Release signal:** version is LAUNCHED at **1.1.0**; current pin **1.1.1** (no CHANGELOG). Treat the **git tip SHA** as technical truth; read curated product highlights in `docs/release-notes.md`.
+**Release signal:** version is LAUNCHED at **1.1.0**; **pin tracks `VERSION`** (no CHANGELOG). Treat the **git tip SHA** as technical truth; read curated product highlights in `docs/release-notes.md`.
 
 ## Quick path for AI agents (Claude Code, or driving one)
 
@@ -38,12 +38,12 @@ How any project — human-driven or agent-driven — adopts this HTML-first desi
 
 ## Adopt via npm (optional)
 
-The package is publishable (`private: false`, version **1.1.1**). License remains **UNLICENSED** — installing from the registry does **not** grant redistribution rights by itself. **LAUNCH was `@cyberskill/design@1.1.0`; current pin is `@cyberskill/design@1.1.1` (publish via tag `v1.1.1`).** CI republishes via **npm Trusted Publishing (OIDC)** on workflow `npm-publish.yml` (no long-lived publish token; package Publishing access **disallows tokens**). Approved use is recorded in **`docs/consumer-grant.md`** (CyberSkill portfolio products from `docs/products.md`). See `docs/decisions.md` and `docs/ci-cd.md`.
+The package is publishable (`private: false`; version equals root `VERSION`). License remains **UNLICENSED** — installing from the registry does **not** grant redistribution rights by itself. **LAUNCH was `@cyberskill/design@1.1.0`; pin follows `VERSION` thereafter** (auto-bump on `main` creates tag `vX.Y.Z`, which fires `npm-publish.yml`). CI publishes via **npm Trusted Publishing (OIDC)** (no long-lived publish token; package Publishing access **disallows tokens**). Approved use is recorded in **`docs/consumer-grant.md`** (CyberSkill portfolio products from `docs/products.md`). See `docs/decisions.md` and `docs/ci-cd.md`.
 
 **Consumer grant (owner policy — not a secret).** Written and in force at `docs/consumer-grant.md` (+ `docs/vi/consumer-grant.md`). External teams need a dated stanza appended there; redistribution outside granted products needs a further written grant.
 
 ```bash
-npm install @cyberskill/design@1.1.1
+npm install @cyberskill/design@<VERSION>
 ```
 
 Then link styles and import components. **Next.js / Vite / SSR apps** use the default entry (bundler-native):
@@ -54,21 +54,21 @@ import { Button, TextField } from "@cyberskill/design";
 import "@cyberskill/design/styles.css";
 ```
 
-Add `transpilePackages: ["@cyberskill/design"]` in Next.js (JSX ships as source). React and react-dom are **peerDependencies** — your app provides them. Published types use `export type *` (**TypeScript 5.0+**). Do **not** import `_esm/cs.mjs` (or `@cyberskill/design/legacy`) into an SSR bundler; that path self-ensures React via CDN and side-loads `_ds_bundle.js` for browsers only.
+Add `transpilePackages: ["@cyberskill/design"]` in Next.js (JSX ships as source). The default entry (`_esm/react.mjs`) is a **`"use client"` barrel** — App Router Server Components can `import { Button } from "@cyberskill/design"` without per-import client shims. React and react-dom are **peerDependencies** — your app provides them. Published types use `export type *` (**TypeScript 5.0+**). Do **not** import `_esm/cs.mjs` (or `@cyberskill/design/legacy`) into an SSR bundler; that path self-ensures React via CDN and side-loads `_ds_bundle.js` for browsers only.
 
 **Browser / no-build:** import `@cyberskill/design/legacy` (`_esm/cs.mjs`) or continue with the static tree paths below. The published tarball is the **full portable tree** (styles, tokens, components, templates, guidelines, docs, UI kits) — not a minimal “lib-only” subset. Host-only tooling (Storybook, `_audit/`) is not in `files[]`.
 
-**First real install (Lumi).** Copy-paste working **browser** consumer: `examples/npm-hello/` — installs `@cyberskill/design@1.1.1` from the registry, links `styles.css`, mounts `Button` via the **legacy** browser entry (`_esm/cs.mjs`), scopes **Lumi** with `data-cs-element="hoa" data-cs-variant="plasma"` (locked row in `docs/products.md`). From that folder: `npm install && npm run smoke && npm start` → open `http://127.0.0.1:8766/`. Status Hub teams use the same install and swap to `data-cs-element="thuy"` — do not invent mappings. For Next/SSR product apps (e.g. Lumi landing), use `import { Button } from "@cyberskill/design"` as above — not the npm-hello import map.
+**First real install (Lumi).** Copy-paste working **browser** consumer: `examples/npm-hello/` — installs `@cyberskill/design` at the repo `VERSION` from the registry, links `styles.css`, mounts `Button` via the **legacy** browser entry (`_esm/cs.mjs`), scopes **Lumi** with `data-cs-element="hoa" data-cs-variant="plasma"` (locked row in `docs/products.md`). From that folder: `npm install && npm run smoke && npm start` → open `http://127.0.0.1:8766/`. Status Hub teams use the same install and swap to `data-cs-element="thuy"` — do not invent mappings. For Next/SSR product apps (e.g. Lumi landing), use `import { Button } from "@cyberskill/design"` as above — not the npm-hello import map.
 
 **Publish path (maintainers):** `prepublishOnly` runs `build:bundle` + `build:design-md --check`. Workflow `.github/workflows/npm-publish.yml` on `workflow_dispatch` / `v*` tags uses **Trusted Publishing** (`permissions.id-token: write`; do not set `NODE_AUTH_TOKEN` on the publish step). `node _audit/ci/npm-publish.mjs --dry-run` always lists the tarball. See `docs/ci-cd.md` and `docs/decisions.md`.
 
 ## Adopt (two paths, plus a module shortcut)
 
-**1. Static / prototypes / mocks — link the stylesheet.** Copy `styles.css` (+ the `tokens/`, `base/`, `fonts/` it `@import`s, or serve the whole tree) and link it; you now have every `--cs-*` token, the `.cs-*` component classes, and the Liquid Glass surfaces. Compose with the classes (see `templates/kitchen-sink.html`). Copy any asset you reference from `assets/`.
+**1. Static / prototypes / mocks — link the stylesheet.** For **production static**, link the flattened bundle `dist/styles.min.css` (also `@cyberskill/design/styles.min.css`) — one file, no `@import` waterfall. Keep `styles.css` (+ the `tokens/`, `base/`, `fonts/` it `@import`s) as the readable source/dev path, or serve the whole tree. Either way you get every `--cs-*` token, the `.cs-*` component classes, and the Liquid Glass surfaces. Compose with the classes (see `templates/kitchen-sink.html` and `examples/static-hello/`). Copy any asset you reference from `assets/`.
 
-**2. Production React — load the compiled bundle.** Link `styles.css` and `<script src="_ds_bundle.js">`, then read components off the namespace. **Resolve by prefix, never hardcode:** the bundle exposes `window.CyberSkillDesignSystem_<projectId>`, and that 6-hex suffix is compiler-assigned and **changes on import into another project**:
+**2. Production React — load the compiled bundle.** Link `dist/styles.min.css` (or `styles.css` in dev) and `<script src="_ds_bundle.js">`, then read components off the namespace. **Resolve by prefix, never hardcode:** the bundle exposes `window.CyberSkillDesignSystem_<projectId>`, and that 6-hex suffix is compiler-assigned and **changes on import into another project**:
 ```html
-<link rel="stylesheet" href="<path>/styles.css">
+<link rel="stylesheet" href="<path>/dist/styles.min.css">
 <script src="<path>/_ds_bundle.js"></script>
 <script>
  const CS = window[Object.keys(window).find(k => /^CyberSkillDesignSystem_/.test(k))];
@@ -76,7 +76,7 @@ Add `transpilePackages: ["@cyberskill/design"]` in Next.js (JSX ships as source)
 </script>
 ```
 This is exactly what `_audit/consumer-smoke-test.html` exercises (and asserts green) — and the templates' `ds-base.js` does the same, publishing a stable `window.CyberSkillDS` alias.
-**2b. Bundler-native React (Next / Vite / SSR) — default package entry.** `import { Button, TextField } from "@cyberskill/design"` resolves to `_esm/react.mjs` (also exported as `@cyberskill/design/react`). Re-exports every component from source JSX with **React as an external peer** — no CDN, no `_ds_bundle.js` side-load. Your bundler must transpile the package (Next: `transpilePackages: ["@cyberskill/design"]`). Still link `styles.css` yourself. Regenerated with `npm run build:react-entry`; parity is gated by `package-exports-integrity` + `test:react-entry`.
+**2b. Bundler-native React (Next / Vite / SSR) — default package entry.** `import { Button, TextField } from "@cyberskill/design"` resolves to `_esm/react.mjs` (also exported as `@cyberskill/design/react`). The generated file starts with `"use client"` so App Router / RSC consumers import interactive components directly. Re-exports every component from source JSX with **React as an external peer** — no CDN, no `_ds_bundle.js` side-load. Your bundler must transpile the package (Next: `transpilePackages: ["@cyberskill/design"]`). Still link styles yourself (`styles.min.css` recommended for production static sheets). Regenerated with `npm run build:react-entry`; parity is gated by `package-exports-integrity` + `test:react-entry`.
 
 **2c. Browser ESM legacy — one import, no build.** `import { Button, TextField } from "@cyberskill/design/legacy"` (or `"<path>/_esm/cs.mjs"`) — the module self-ensures React via **umd-react@19.2.8** (SRI-pinned CDN; official React 19 has no UMD; skipped when `window.React` exists), side-loads `_ds_bundle.js` once, resolves the namespace by prefix, and re-exports all components (`_audit/esm-smoke-test.html` keeps the export list in lockstep with the manifest). Still link `styles.css` yourself. **Not for Next/SSR.** Bundler apps should keep providing their own `react` / `react-dom` peers (`^18 || ^19`).
 
@@ -84,7 +84,7 @@ This is exactly what `_audit/consumer-smoke-test.html` exercises (and asserts gr
 
 **Machine-readable tokens.** `tokens/tokens.json` + `tokens/tokens.js` (ESM) + `tokens/tokens.dtcg.json` (W3C DTCG, for Tokens Studio/Style Dictionary) expose every token grouped by category + theme/element maps — for native/mobile/design-tool pipelines. **Native builds ship pre-generated** in `tokens/native/` (SwiftUI `CSTokens.swift` · Compose `CSTokens.kt` · Flutter `cs_tokens.dart`) with `tokens/provenance.json` (release, source sha-256, conversion rules, per-target sha-256); the `token-pipeline` gate keeps them in lockstep with the DTCG source.
 
-**Static HTML / no React / no build tooling.** Link `styles.css` and compose with `.cs-*` classes — full catalog demonstrated in `templates/kitchen-sink.html`.
+**Static HTML / no React / no build tooling.** Link `dist/styles.min.css` (production) or `styles.css` (source/dev) and compose with `.cs-*` classes — full catalog demonstrated in `templates/kitchen-sink.html`.
 
 **Fonts, including a display face.** All three brand families are self-hosted in `fonts/` and declared by `tokens/fonts.css` (which `styles.css` `@import`s): **Be Vietnam Pro** (`--cs-font-family-ui`), **JetBrains Mono** (`--cs-font-family-mono`), and **Space Grotesk** (`--cs-font-family-display`, variable 300–700, Vietnamese subset included). The display face is **opt-in** — nothing in the DS points at it. A product that wants a headline face adds `class="cs-display-face"` (or sets `--cs-heading-family: var(--cs-font-family-display)`) on the scope; heading utilities follow, body copy stays on the UI face.
 
@@ -92,11 +92,11 @@ Consumers that skip `styles.css` to control font loading (`cyberskill.world` / L
 
 ## The four axes
 
-State Theme (`data-theme` — light / dark / system), Element (`data-cs-element` + `data-cs-variant`), Language (`lang` / template Language tweak), and Style (`data-cs-style`) on a container; everything inside re-skins with no code change (see `templates/playground.html`). Defaults: `light · tho · en · liquid-glass` (absent theme / style ≡ those defaults). Bilingual: components resolve strings from `lang` (`lang="vi"` on any container → full Vietnamese).
+State Theme (`data-theme` — light / dark / system), Element (`data-cs-element` + `data-cs-variant`), Language (`lang` / template Language tweak), and Style (`data-cs-style`) on a container; everything inside re-skins with no code change (see `templates/playground.html`). Defaults: `light · tho · vi · liquid-glass` (absent theme / style ≡ those defaults; set `lang="en"` for EN surfaces). Bilingual: components resolve strings from `lang` (`lang="en"` on any container → full English; unset → Vietnamese-first fallback).
 
 ## Upgrading
 
-- **Version is pinned.** `VERSION` and `package.json` stay at **1.1.1**. There is no design-system changelog file — treat the **git tip SHA** as the technical truth, and read curated **Release Notes** (Storybook + `docs/release-notes.md`) for product-facing highlights.
+- **Version tracks `VERSION`.** `package.json` stays equal to the root `VERSION` file (auto-bumped on `main`). There is no design-system changelog file — treat the **git tip SHA** as the technical truth, and read curated **Release Notes** (Storybook + `docs/release-notes.md`) for product-facing highlights.
 
 - Anchors (Umber/Ochre), the `.cs-*` class names, and the `--cs-*` token names are stable contracts — safe to depend on. Breaking renames of those contracts should be rare and called out in the PR/docs when they happen.
 

package/docs/contrast-report.md

@@ -1,6 +1,6 @@
 # Contrast report — elemental pairings (APCA)
 
-Generated 2026-07-27 · sweep at VERSION 1.1.1 pin.
+Generated · sweep at VERSION 1.3.8.
 
 **Doctrine encoded by this sweep:** text sits on `-bright` or `-tint`, never on the mid-tone `-accent` — at any size. The accent is for bars, borders, progress fills, and non-text fills only. (Rule stated in `tokens/elements.css` and conventions.)
 
@@ -90,6 +90,84 @@ Packs are generated from `tokens/element-seeds.json` (soft / middle / deep ladde
 
 **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/conventions.md

@@ -4,7 +4,7 @@ For humans and agents *extending this system*. (Consumers: read `SKILL.md`.) The
 
 ## The expansion rule
 
-**When anything grows, everything updates in the same change.** A new element/variant, icon, component, token role, language, or template pattern must propagate to: tokens/source → specimen cards (guidelines + the component group card) **and related guideline pages** → component contract trio (`.jsx` + `.d.ts` + `.prompt.md`) → **all** templates (tweak enums and maps) → Storybook toolbar / Atomic View → docs (README counts, SKILL, **and every related document the change touches** — kit READMEs, registry, contrast report regenerated after token changes). **Bump `VERSION` only with an explicit owner instruction; do not maintain a changelog** — current release is **1.1.1**. Continuity is git history plus curated **Release Notes** (`docs/release-notes.md` / Storybook). Gate every expansion with the compiler check **and a grep for the old enum/list** — nothing ships half-propagated. Documented scope boundaries (doctrine, not gaps): UI-kit pages stay pixel-faithful Thổ recreations (axes demoed in Storybook toolbar and Atomic View); every template is bilingual EN·VN and English-default (client/media collateral stays English-primary), and language variants render **fully separated** — see the decision log.
+**When anything grows, everything updates in the same change.** A new element/variant, icon, component, token role, language, or template pattern must propagate to: tokens/source → specimen cards (guidelines + the component group card) **and related guideline pages** → component contract trio (`.jsx` + `.d.ts` + `.prompt.md`) → **all** templates (tweak enums and maps) → Storybook toolbar / Atomic View → docs (README counts, SKILL, **and every related document the change touches** — kit READMEs, registry, contrast report regenerated after token changes). **`VERSION` auto-bumps on push to `main`** (Conventional Commits); owner may still force a bump. **Do not maintain a changelog** — LAUNCHED at **1.1.0**; pin tracks `VERSION`. Continuity is git history plus curated **Release Notes** (`docs/release-notes.md` / Storybook). Gate every expansion with the compiler check **and a grep for the old enum/list** — nothing ships half-propagated. Documented scope boundaries (doctrine, not gaps): UI-kit pages stay pixel-faithful Thổ recreations (axes demoed in Storybook toolbar and Atomic View); every template is bilingual EN·VN and English-default (client/media collateral stays English-primary), and language variants render **fully separated** — see the decision log.
 
 ## The four axes
 
@@ -16,11 +16,11 @@ Every rendered surface resolves four orthogonal scopes — never encode one axis
 | **Language** | `lang` / Language tweak | EN · VI copy | component registry + template props |
 | **Style** | `data-cs-style` (optional; absent ≡ `liquid-glass`) | surface material pack | `tokens/styles.css` |
 
-Style’s sole pack today is **liquid-glass**. Immutable under all axes: Umber/Ochre anchors, voice, type families, semantic status colors, the 3px Ochre focus ring, APCA floors, ≥44px targets.
+Style’s sole pack today is **liquid-glass**. Immutable under all axes: Umber/Ochre anchors, voice, type families, semantic status colors, the composite focus indicator (text-primary contour + ochre halo), APCA floors, ≥44px targets.
 
 ## Naming grammar
 
-- Tokens: `--cs-<layer>-<role>[-<state>]` (`--cs-color-text-muted`). Element role layer: `--cs-accent-*` (9-token contract — see `tokens/elements.css` header).
+- Tokens: `--cs-<layer>-<role>[-<state>]` (`--cs-color-text-muted`). Element role layer: `--cs-accent-*` (10-token contract including `--cs-accent-on-strong` for text on strong fills — see `tokens/elements.css` header).
 
 - Classes: `.cs-<block>[-<part>][--modifier]`. Data attributes: `data-theme`, `data-cs-element`, `data-cs-variant`, `data-cs-style`.
 
@@ -32,13 +32,13 @@ Style’s sole pack today is **liquid-glass**. Immutable under all axes: Umber/O
 
 **New component** — `Name.jsx` + `Name.d.ts` + `Name.prompt.md` in `components/<group>/`; add to the group's card html (resolve the bundle namespace **by prefix** — `const CS = window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]` — never a hardcoded `…_<projectId>` suffix); add to readme's group line. Consume tokens only; no hex literals except inside `tokens/`.
 
-**Responsive** — reflow is global (`base/responsive.css`, loaded last): media never overflows, print docs relax padding, `.cs-sheet` tables scroll, `.cs-sidebar` collapses, inline fixed-column grids collapse (3+→2 tablet, →1 phone), unbreakable long tokens (write-on `______` lines, long URLs/IDs) get `overflow-wrap: anywhere` on doc surfaces so they can't prop a phone column open, the app-shell shell grid collapses to one column with `main{min-width:0}`+`.cs-table-wrap` scroll, and fixed-geometry export canvases (`class="cs-canvas-desk"`: decks, social) **always** `overflow-x:auto` so a slide wider than the window scrolls inside the desk rather than pushing the page wide. Verified whole-set at 390 by `_audit/responsive-overflow.html` (all 84 = 0 document overflow). **Two hard gotchas:** (1) the DC runtime compiles inline `style="…"` into React objects, so the rendered attribute is *spaced* — any `[style*=…]` responsive selector must match `grid-template-columns: repeat(4, 1fr)` (colon-space, comma-space), never the authored no-space form; (2) a global CSS rule can only override a property the template sets **inline** via an **attribute** selector (`[style*="grid-template-columns: 248px 1fr"]`) — a **class** selector loses to the inline style. Prefer fixing overflow in the template source (add `min-width:0`, `flex-wrap:wrap` inline) over fighting inline from the stylesheet.
+**Responsive** — reflow is global (`base/responsive.css`, loaded last): media never overflows, print docs relax padding, `.cs-sheet` tables scroll, `.cs-sidebar` collapses, inline fixed-column grids collapse (3+→2 tablet, →1 phone), unbreakable long tokens (write-on `______` lines, long URLs/IDs) get `overflow-wrap: anywhere` on doc surfaces so they can't prop a phone column open, the app-shell shell grid collapses to one column with `main{min-width:0}`+`.cs-table-wrap` scroll, and fixed-geometry export canvases (`class="cs-canvas-desk"`: decks, social) **always** `overflow-x:auto` so a slide wider than the window scrolls inside the desk rather than pushing the page wide. **Width stops must match the token scale** in `tokens/spacing.css` (`xs` · `phone` 360 · `sm` 640 · `md` 768 · `lg` 1024 · `xl` 1280 · `2xl` 1536) — `docs-consistency` fails off-scale `@media`/`@container` widths in `base/` (FIND-007). Verified whole-set at 390 by `_audit/responsive-overflow.html` (all 84 = 0 document overflow). **Two hard gotchas:** (1) the DC runtime compiles inline `style="…"` into React objects, so the rendered attribute is *spaced* — any `[style*=…]` responsive selector must match `grid-template-columns: repeat(4, 1fr)` (colon-space, comma-space), never the authored no-space form; (2) a global CSS rule can only override a property the template sets **inline** via an **attribute** selector (`[style*="grid-template-columns: 248px 1fr"]`) — a **class** selector loses to the inline style. Prefer fixing overflow in the template source (add `min-width:0`, `flex-wrap:wrap` inline) over fighting inline from the stylesheet.
 
 **New template** — `templates/<slug>/<Slug>.dc.html` with `<!-- @template name description -->` first; `ds-base.js` stays single-entry (`styles.css` only — the one-line rebind was validated end-to-end Jul 2026 from a deeper path; the test scaffold has since been removed) and publishes the id-independent `window.CyberSkillDS` alias on bundle load, so mount DS components via `component-from-global-scope="CyberSkillDS.…"` — **never** a hardcoded `CyberSkillDesignSystem_<projectId>` suffix (it changes on re-import; enforced by `_audit/namespace-portability.html`); inline styles only; 1–3 tweaks (never plain copy/color — in-place editing covers those); printable docs add the `@page` + `.cs-desk`/`.cs-sheet` print block and carry **no dark tweak** (print is light-only).
 
-**New element variant** — stay inside the element's oklch envelope; set the 9 `--cs-accent-*` contract tokens plus `--cs-color-text-accent`/`--cs-color-link` (APCA-check both); the aurora wash inherits from the element via `.cs-aurora-wash` (override the class rule only if the variant truly needs its own image); gradient partner (`grad-b`) must follow Tương sinh.
+**New element variant** — stay inside the element's oklch envelope; set the 10 `--cs-accent-*` contract tokens (incl. `--cs-accent-on-strong` ≥4.5:1 on `-strong`) plus `--cs-color-text-accent`/`--cs-color-link` (APCA-check both); the aurora wash inherits from the element via `.cs-aurora-wash` (override the class rule only if the variant truly needs its own image); gradient partner (`grad-b`) must follow Tương sinh.
 
-**Ship check** — run the compiler check until clean, then run `_audit/docs-consistency.html` **and** `_audit/namespace-portability.html` (both must be green). Version is LAUNCHED at 1.1.0; current pin is **1.1.1**.
+**Ship check** — run the compiler check until clean, then run `_audit/docs-consistency.html` **and** `_audit/namespace-portability.html` (both must be green). Version is LAUNCHED at 1.1.0; pin tracks `VERSION` (auto-bump on `main`).
 
 ## Decision log (owner-approved)
 
@@ -52,7 +52,7 @@ Style’s sole pack today is **liquid-glass**. Immutable under all axes: Umber/O
 
 - **The display face is a token role, not a second default (Jul 2026).** `--cs-font-family-display` ships Space Grotesk (variable 300–700, Vietnamese subset) self-hosted alongside Be Vietnam Pro and JetBrains Mono, so a product with a headline face — `cyberskill.world` / Lumi — consumes a DS role instead of maintaining its own `@font-face` exception. **Nothing in the DS points at it**: `--cs-heading-family` still resolves to `--cs-font-family-ui`, every template and UI kit is unchanged, and a scope opts in with `.cs-display-face` (`base/typography.css`), which retargets `--cs-heading-family` only — body copy stays on the UI face. Space Grotesk has no 800, so the extrabold heading weight clamps to 700 within that family (CSS does not hop to Be Vietnam Pro for a missing weight). Adding a family means adding its faces to `tokens/fonts.css` **and** its files to `fonts/` **and** its entries to `_ds_manifest.json` `fonts[]`/`brandFonts[]` — `_audit/font-face-integrity.html` fails on any of the three being out of step, and on any family missing the Vietnamese subset. This changes no product → element mapping; `docs/products.md` stays locked.
 
-- Language variants render **fully separated**: switching the Language tweak yields a complete single-language artifact — no partial translation left in headings, labels, helper text, footers, or body. The only bilingual-by-design elements are the CyberSkill name + slogan lockup (`Hiện Thực Hoá Ý Chí · Turn Your Will Into Real`, the canonical form — never a lone half) and the A4 legal identity block (company legal name + state motto). Everything else swaps with the tweak (Jul 2026).
+- Language variants render **fully separated**: switching the Language tweak yields a complete single-language artifact — no partial translation left in headings, labels, helper text, footers, or body. The only bilingual-by-design elements are the CyberSkill name + slogan lockup (`Hiện Thực Hoá Ý Chí · Turn Your Will Into Real`, the canonical form — never a lone half) and the A4 legal identity block (company legal name + state motto). Everything else swaps with the tweak — including skip links and doc-type eyebrows (FIND-125). Catalog `<title>` / `@template name` strings stay English for the template index and are not language-mode chrome; `_audit/template-lang-parity.html` masks them when scanning the EN-leak lexicon (Jul 2026; FIND-125 follow-up).
 
 - **Namespace is resolved, never hardcoded** — the compiler names the bundle global `window.CyberSkillDesignSystem_<projectId>`, and that 6-hex suffix is derived from the project id, so it changes whenever the system is imported into another project. Templates read the stable `window.CyberSkillDS` alias that `ds-base.js` publishes on bundle load; cards, UI-kit pages, the standalone email, and audit harnesses resolve by prefix (`window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]`). `_ds_bundle.js`/`_ds_manifest.json` and the frozen `_audit/exports/` snapshot legitimately carry the real suffix (they *define* it). Enforced by `_audit/namespace-portability.html`, which scans every manifest-indexed source — keeps re-import **zero-touch** (Jul 2026).
 
@@ -70,9 +70,22 @@ Every template exports; the right path depends on the archetype. All paths prese
 
 **Font behavior on export.** Brand fonts are self-hosted (`Be Vietnam Pro` UI, `Space Grotesk` opt-in display, mono). PPTX keeps the brand-font **names** but does not embed the files — on a machine without them PowerPoint substitutes a fallback (VN Unicode text is preserved; shapes may reflow slightly). For a fully self-contained hand-off, either tell the recipient to install the fonts, or export with a web-safe swap (`fontSwaps:[{from:'Be Vietnam Pro',to:'Arial'}]` — Arial covers Vietnamese). Standalone HTML **embeds** the fonts (inlined `@font-face` from `styles.css`), so it is always faithful offline (Jul 2026).
 
+## Async data states (FIND-020 — thin pattern)
+
+Collection surfaces that own a fetch must distinguish **loading · error · empty · idle-with-data**. Do not render the empty message while a request is in flight.
+
+| State | Compose | Notes |
+|---|---|---|
+| **loading** | `Skeleton` (table rows / lines) + polite status text | `aria-busy` on the region; keep column headers when possible |
+| **error** | `Result status="error"` (or a custom `errorState`) | `role="alert"`; offer retry in the host |
+| **empty** | `emptyState` / `EmptyState` | Only after a successful idle response with zero rows |
+| **idle** | Normal rows | Default — omit `state` for static specimens |
+
+**Reference API:** `DataTable` accepts `state?: "idle" \| "loading" \| "error"` plus optional `loadingState` / `errorState` / `loadingRows`. Other collection components (`DataGrid`, `TreeTable`, …) should follow the same triad when they gain async ownership — do not invent a parallel loading API per surface. Long operations that are not tabular still use `Spinner` (`role="status"`) or `ProgressBar` with a real `aria-label`; pair decorative `Skeleton` (`aria-hidden`) with a live status string.
+
 ## Accessibility (base/a11y.css + component ARIA)
 
-- **Focus rings are systematic** — global `:where(:focus-visible)` ochre ring in `base/reset.css`, plus per-component 3px ochre rings (`components/forms/navigation/controls`). Never set `outline: none` on a `:focus-visible` state without replacing the ring (the menu-item regression, fixed Jul 2026). The soft 5px glow in `interaction.css` layers on the 3px ring, never replaces it.
+- **Focus rings are systematic** — global `:where(:focus-visible)` in `base/reset.css` is a **composite** indicator: 2px `text-primary` contour (≥3:1 non-text contrast on light and dark) plus a 5px ochre brand halo. Wrapper controls (`SearchField`, `NumberField`, `PromptInput`, `Terminal`, `CommandPalette`) mirror that via `:focus-within`. Never set `outline: none` on a focusable control without a paired wrapper/replacement ring.
 
 - **Touch targets** — `base/a11y.css` guarantees 44px on `@media (pointer: coarse)` (tabs, pagination, menu items, stepper, checkbox/radio; segmented 40px in its padded track). Desktop mouse density is preserved. `pointer: coarse` is used deliberately over a width breakpoint — a touch laptop at 1280px still needs 44px. Button carries its own coarse block in `components.css`.
 

package/docs/decisions.md

@@ -50,12 +50,12 @@ Stay on the current Figma plan. Variables REST API is Enterprise-only — write
 
 ## 7. npm publish — live via Trusted Publishing (OIDC)
 
-**Status: LAUNCHED `@cyberskill/design@1.1.0`; current pin `@cyberskill/design@1.1.1`; CI publish uses npm Trusted Publishing; tokens disallowed** (Jul 2026; LAUNCH 2026-07-27)
+**Status: LAUNCHED `@cyberskill/design@1.1.0`; pin tracks `VERSION` (auto-bump on main since Aug 2026); CI publish uses npm Trusted Publishing; tokens disallowed** (Jul 2026; LAUNCH 2026-07-27)
 
 - `package.json` is `private: false`; package name **`@cyberskill/design`** (`publishConfig.access: public`); `repository.url` matches this GitHub repo for provenance.
-- Workflow `.github/workflows/npm-publish.yml`: `id-token: write` + GitHub-hosted runner; **no** `NPM_TOKEN` / `NODE_AUTH_TOKEN` on the publish step (OIDC). npm Trusted Publisher must list workflow filename **`npm-publish.yml`** for `cyberskill-official/design-system`. Soft-skip on auth / 403 / 404 / EOTP / version conflict.
+- Workflow `.github/workflows/npm-publish.yml`: `id-token: write` + GitHub-hosted runner; **no** `NPM_TOKEN` / `NODE_AUTH_TOKEN` on the publish step (OIDC). npm Trusted Publisher must list workflow filename **`npm-publish.yml`** for `cyberskill-official/design` (FIND-088). Soft-skip only for expected no-ops (`already_published` / EPUBLISHCONFLICT, and true non-GHA `missing_secrets`). On GHA tag / `workflow_dispatch`, **ENEEDAUTH** / **404** / **402** / **403** / **EOTP** fail the job; a successful publish is gated by post-publish `npm view @cyberskill/design@VERSION` **and** `dist-tags.latest === VERSION` (FIND-020 / FIND-094).
 - Package **Publishing access** on npmjs: **Require two-factor authentication and disallow tokens** (OIDC Trusted Publishing still works; classic / granular publish tokens are rejected). Long-lived `NPM_TOKEN` secrets are revoked.
-- License stays **UNLICENSED**; version is **1.1.1**. Approved use is recorded in **`docs/consumer-grant.md`** (CyberSkill portfolio products). Registry install alone is not a public license.
+- License stays **UNLICENSED**; version tracks root `VERSION`. Approved use is recorded in **`docs/consumer-grant.md`** (CyberSkill portfolio products). Registry install alone is not a public license.
 
 ## 8. Native store packaging — scaffolds shipped; submit disabled
 
@@ -77,7 +77,7 @@ Recorded Jul 2026 — unlock defaults (updated as operator steps land):
 
 - **Figma Variables** — stay Tokens Studio / non-Enterprise (decision §3). Soft-skip on Variables REST remains honest.
 - **Code Connect** — **skipped while on Figma free**; revisit only after Org + published library + real `nodeId`s (decision §6). Soft-skip ≠ publish.
-- **npm** — **LAUNCH `@cyberskill/design@1.1.0`**; current pin **`@cyberskill/design@1.1.1`** (publish via `v*` tag / Trusted Publishing); CI uses **Trusted Publishing (OIDC)** via `npm-publish.yml`; npmjs **disallow tokens**; consumer grant in force at `docs/consumer-grant.md` (decision §7). Default package entry is bundler-native `_esm/react.mjs` (React peer); browser path is `@cyberskill/design/legacy` → `_esm/cs.mjs` (decision §10).
+- **npm** — **LAUNCH `@cyberskill/design@1.1.0`**; pin tracks `VERSION` (auto-bump on `main` → tag `v*` → Trusted Publishing); CI uses **Trusted Publishing (OIDC)** via `npm-publish.yml`; npmjs **disallow tokens**; consumer grant in force at `docs/consumer-grant.md` (decision §7). Default package entry is bundler-native `_esm/react.mjs` (React peer); browser path is `@cyberskill/design/legacy` → `_esm/cs.mjs` (decision §10).
 
 ## 10. Bundler-native React export (Next / SSR)
 
@@ -85,7 +85,7 @@ Recorded Jul 2026 — unlock defaults (updated as operator steps land):
 
 - React / react-dom are **peerDependencies** (`^18 || ^19`); the entry re-exports source JSX (consumer transpiles — e.g. Next `transpilePackages`). Host Storybook / CI **devDependencies** pin **react@19.2.8** / **react-dom@19.2.8**.
 - Browser / no-build keeps `_esm/cs.mjs` at `exports["./legacy"]` (CDN self-ensure + `_ds_bundle.js`). Official React 19 dropped UMD builds — the CDN path loads **`umd-react@19.2.8`** (SRI-pinned) to populate `window.React` / `window.ReactDOM` for `_ds_bundle.js`. Same pin is used in audit HTML, specimen cards, UI kits, and the byte-identical `templates/*/support.js` runtime.
-- Alias `@cyberskill/design/react` mirrors the default entry. VERSION is **1.1.1** post-LAUNCH; republish via Trusted Publishing after merge / tag.
+- Alias `@cyberskill/design/react` mirrors the default entry. VERSION auto-bumps on `main` post-LAUNCH; republish via Trusted Publishing when `version.yml` pushes tag `v*`.
 - Docs: `docs/consuming.md` (+ VI); gates: `package-exports-integrity` + `test:react-entry`.
 
 ## Maintainer tasks (open)
@@ -98,9 +98,9 @@ Operational follow-ups — not product marketing, not a backlog surface:
 
 ~~3. Finalize products registry~~ — **done** (Jul 2026): see decision §9; `docs/products.md` is locked.
 
-~~4. First registry consumer path~~ — **done** (Jul 2026): `examples/npm-hello/` installs `@cyberskill/design` for locked **Lumi** identity; documented in `docs/consuming.md` (+ VI) and `docs/release-notes.md`. Now targets **1.1.1** post-LAUNCH.
+~~4. First registry consumer path~~ — **done** (Jul 2026): `examples/npm-hello/` installs `@cyberskill/design` for locked **Lumi** identity; documented in `docs/consuming.md` (+ VI) and `docs/release-notes.md`. Pin follows repo `VERSION`.
 
-5. **Native + element-pack drift on PRs is fail-closed** (Jul 2026) — `regenerate-tokens` runs read-only on pull requests and exits 1 instead of pushing; only `regenerate-tokens-push` (main / schedule / manual) holds `contents: write`. When a PR fails it, run `npm run tokens:elements && node _audit/ci/generate-native-tokens.mjs` and commit packs + natives. See `docs/ci-cd.md`.
+5. **Native + element-pack drift on PRs is fail-closed** (Jul 2026; FIND-021 re-gate Aug 2026) — `regenerate-tokens` runs read-only on pull requests and exits 1 instead of pushing; only `regenerate-tokens-push` (main / schedule / manual) holds `contents: write`. When a PR fails it, run `npm run tokens:elements && node _audit/ci/generate-native-tokens.mjs` and commit packs + natives. Auto-commits from `regenerate-tokens-push` **must not** use `[skip ci]` so the tip re-enters the gate board (TASK-IMP-008); PR fail-closed freshness remains the primary contributor path. Branch-protection required-check reality is NV-18.1 (out-of-band). See `docs/ci-cd.md`.
 
 6. **Shadcn gap / Wave 2** (Jul 2026) — CyberSkill already covers ~53 of shadcn’s 62 primitives as CS-native (forms / overlays / nav / data). Shipped: pilot `ScrollArea`, `Collapsible`, `AspectRatio`; Wave 2 `AlertDialog` (vs Popconfirm), `Item` row primitive, `NativeSelect`. Residual shadcn gaps are intentional non-ports (blocks, Tailwind, Radix CLI). Do **not** port those — map patterns to existing `templates/` + `ui_kits/`.
 
@@ -112,6 +112,44 @@ Operational follow-ups — not product marketing, not a backlog surface:
 
 Storybook `FullMatrix` is required whenever a public primary has ≥1 of {size enums, variant enums, state keys} (contract floor ≥28 stories). Schema sidecars remain complete for content-hole templates; axis-only templates omit by design. See `docs/quality-gates.md` and `docs/storybook.md`.
 
+## 11. Audit paper trails — archive, do not delete
+
+**Owner choice: archive-don't-delete** (Aug 2026; TASK-IMP-001 / assessment FIND-001)
+
+- Closed UX / AT / quality-audit artifacts MUST remain reconstructable from a fresh clone. Prefer `_audit/archive/` and/or `docs/audits/` over silent deletion.
+- Commit `8646dbf` deleted the Aug-8 UX audit plan, AT matrix, archive README, and `TASK-UX-AUDIT-20260808` “with no permanent record.” Those bodies are restored under `docs/audits/ux-audit-2026-08-08/` (plus `_audit/archive/ux-audit-2026-08-08/` pointer). Historical D1–D6 operator choices that drove that remediation stay in the restored plan; they do **not** authorize future deletion of audit trails.
+- Status-feed / ledger edits that hide completed audit work are discouraged; if a commit must be ledger-exempted, record the exemption and the archived path in the same change.
+- Claims that need provenance (e.g. “AT complete”, “lawyer-validated”) require a dated in-tree record or an explicit decision entry — not oral attestation alone.
+
+## 12. 12-month evolution plan — adoption status
+
+**Owner choice: partially superseded (near-term); plan retained as long-horizon reference** (Aug 2026; TASK-IMP-001 / assessment FIND-002)
+
+Source: `docs/plans/cyberskill-design-system-audit-and-12-month-evolution-plan.md` (audit date 2026-07-28). A prior `task-author` PLAN for that document was approved (manifest `docs/tasks/.workflow/task-author.design-system-evolution.manifest.json`) but most artefacts were never landed in `docs/tasks/`.
+
+| Horizon | Status | Notes |
+|---------|--------|-------|
+| Assessment Phases 0–3 | **Adopted** (HITL 2026-08-09) | `TASK-IMP-001`…`TASK-IMP-012` |
+| Assessment Phases 4–5 | **Implemented → ready_to_review** | `TASK-IMP-013`…`TASK-IMP-020` |
+| Full 12-month plan phases 0–6 task materialization | **Deferred** | Do not auto-expand the pending manifest artefacts until operator triages against tip `1.2.1` / post-assessment state |
+| Items already shipped outside backlog (e.g. Aug-8 UX remediation commits) | **Superseded as live tasks** | Evidence lives in `docs/audits/ux-audit-2026-08-08/` + git history; do not re-open as duplicate ready work without a fresh finding |
+
+Phases 3–5 of the **assessment** roadmap are authored as `TASK-IMP-009`…`020`; Phase 3 accepted HITL 2026-08-09; Phases 4–5 await final HITL at `ready_to_review`.
+
+## 13. Product vs CyberOS boundary
+
+**Owner choice: explicit fence** (Aug 2026; assessment area 28 / TASK-IMP-020)
+
+| Layer | Ships to consumers? | Lives where | Purpose |
+|-------|---------------------|-------------|---------|
+| **Product design system** | Yes — `@cyberskill/design`, portable tree (`styles.css`, `tokens/`, `components/`, `templates/`, `_audit/` gates, Storybook host) | repo root (non-`.cyberos`) | Tokens, components, templates, kits, deterministic quality gates |
+| **CyberOS orchestration** | No (gitignored / installable agent kit) | `.cyberos/`, `docs/tasks/`, BRAIN under `.cyberos/memory/` | Task lifecycle, HITL gates, agent entry, ship-tasks workflow |
+
+Rules:
+- Product acceptance criteria must not require `.cyberos/` to be present for consumers or for `npm` publish.
+- Agents operating this repo follow `.cyberos/AGENT-ENTRY.md`; humans shipping the DS follow `docs/release-runbook.md`.
+- Do not move product tokens/components into `.cyberos/`; do not publish CyberOS orchestration as part of the npm package.
+
 ## How to change a decision
 
 Edit the **Owner choice** line here. Implementer rewires CI and related docs in the same change.

package/docs/deploy.md

@@ -48,11 +48,15 @@ If you host under a **different** domain, change the absolute URLs in those meta
 
 **With Storybook at `/`:** run `npm run build:site` on the host or CI, then serve `.vercel-static/` as the webroot. Configure the same redirects as `vercel.json` (`/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/`) if your host supports them.
 
-Nginx example (`.vercel-static` as `root`):
+Nginx example (`.vercel-static` as `root`) — **same security headers as `vercel.json`** (FIND-019):
+```nginx
 server {
   server_name design.cyberskill.world;
   root /var/www/design-system/.vercel-static;
   index index.html;
+  add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data: blob:; connect-src 'self'; frame-src 'self'; worker-src 'self' blob:; base-uri 'self'; form-action 'self'" always;
+  add_header X-Content-Type-Options "nosniff" always;
+  add_header Referrer-Policy "strict-origin-when-cross-origin" always;
   location = /dashboard { return 301 /; }
   location = /dashboard/ { return 301 /; }
   location = /dashboard.html { return 301 /; }
@@ -60,8 +64,11 @@ server {
   location = /playground { return 301 /; }
   location /playground/ { return 301 /; }
 }
+```
 Portable paths remain real files (`guidelines/atomic-view.html`, `_audit/run.html`, `styles.css`, etc.). Storybook owns `/` and `/index.html`.
 
+**Netlify / Cloudflare Pages / similar:** commit root `_headers` (and `public/_headers`) mirrors the same three headers for hosts that read Netlify-style `_headers` files. Keep them byte-aligned with `vercel.json`.
+
 ## Post-deploy checklist
 1. Open `/` — confirm Storybook loads (not a 404, directory listing, or the old dashboard shell).
 2. Open `/_audit/run.html` — let the board finish, confirm all fast gates pass on the *deployed* copy (CDN caching, MIME types, or a missed file can surface here even when local checks were clean).
@@ -86,12 +93,16 @@ After every production deploy:
 
 ## Content-Security-Policy notes
 
-Static hosting can ship a strict CSP. Typical allowances for this system:
-- `script-src 'self' https://unpkg.com` if you load React from CDN for Atomic View
-- `font-src 'self'`
+Canonical CSP lives in `vercel.json` and is mirrored in `_headers` + the nginx snippet above (FIND-015 / FIND-019). Current 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'`
 
-- `img-src 'self' data:`
-Prefer self-hosting React next to `_ds_bundle.js` for air-gapped installs.
+Rationale:
+- **`unsafe-eval` removed** — React is vendored locally; Storybook static export does not need site-wide `eval`.
+- **CDN script/connect origins removed** (`unpkg.com`, `cdnjs.cloudflare.com`) — local-first React / `_ds_bundle.js`.
+- **`unsafe-inline` retained** — Storybook’s static shell still emits inline scripts/styles; a nonce/hash migration is a follow-on. Do not re-add open CDN allowlists without pinning.
+- Prefer self-hosting React next to `_ds_bundle.js` for air-gapped installs.
+- Live served-header truth confirmed 2026-08-09 via operator `curl -sSI https://design.cyberskill.world/` (OQ-003 closed — see `docs/audits/nv-rendered-inrepo-2026-08-09.md`).
 
 ## Multi-domain OG
 

package/docs/design-styles.md

@@ -21,7 +21,7 @@ Source of truth: [`tokens/element-seeds.json`](../tokens/element-seeds.json) →
 | **Character offsets** | Small explicit `dh`/`dc` in the seed file only (e.g. Hỏa·plasma, Kim·steel) — not freehand drift |
 | **Light ↔ dark** | Same hue family (Δh locked); roles remapped + APCA-solved — 15 × 2 = **30 colour sets** |
 | **Text rule** | Text on `-bright` or `-tint` only — never on mid-tone `-accent` |
-| **Never remap** | `--cs-color-accent-ochre` focus ring · semantic status colours |
+| **Never remap** | composite focus indicator (text-primary contour + ochre halo) · semantic status colours |
 | **Geometry gate** | [`_audit/element-geometry.html`](../_audit/element-geometry.html) — intensity sync · variant distinctness · hue identity |
 
 ## Style pack — liquid-glass
@@ -38,6 +38,6 @@ Prefer:
 1. A new **Element** intensity tweak (seed offset) when the shift is hue/identity inside Ngũ Hành.
 2. Local composition with existing tokens/classes when the shift is one-off layout.
 3. A documented pattern in `docs/conventions.md` + a specimen card when the pattern should be reusable.
-4. A new **`data-cs-style`** pack only after an Expansion Rule pass — see [`docs/benchmark-rubric.md`](benchmark-rubric.md) style-expansion checklist. Styles consume the same 9 accent roles; they must not invent parallel Element packs.
+4. A new **`data-cs-style`** pack only after an Expansion Rule pass — see [`docs/benchmark-rubric.md`](benchmark-rubric.md) style-expansion checklist. Styles consume the same 10 accent roles (incl. `on-strong`); they must not invent parallel Element packs.
 
 Do not invent a fifth product axis, and do not add a second Style pack without the Expansion Rule checklist.