@cyberskill/design 1.2.0 → 1.3.9

package/docs/benchmark-rubric.md

@@ -1,6 +1,6 @@
 # Design System Benchmark Rubric
 
-Self-audit checklist for evolving CyberSkill Design System — external standards plus CDS-owned rules. Pair with [`docs/quality-gates.md`](quality-gates.md) (deterministic gates) and [`docs/design-styles.md`](design-styles.md) (Element colour contract).
+Self-audit checklist for evolving CyberSkill Design System — external standards plus CDS-owned rules. Pair with [`docs/quality-gates.md`](quality-gates.md) (deterministic gates) and [`docs/design-styles.md`](design-styles.md) (Element colour contract). Published on Storybook **Docs** at `design.cyberskill.world`.
 
 ## External standards
 
@@ -22,7 +22,7 @@ Self-audit checklist for evolving CyberSkill Design System — external standard
 | Text never on mid `-accent`; Ochre focus ring never remapped; status colours never remapped | `elements.css` contract · contrast-report · conventions |
 | 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 |
+| Expansion Rule completeness + `_audit/run.html` green + docs EN·VI parity | `docs/doctrine.md` · docs-consistency · docs-lang-parity · docs-storybook-coverage |
 | 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` |
 

package/docs/ci-cd.md

@@ -1,29 +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. Published on Storybook **Docs** at `design.cyberskill.world`.
+
 **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; 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` (same `DS_PUSH_TOKEN` pattern as `regenerate-tokens-push` if branch protection blocks `github.token`).
+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 (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 on auth / 403 / 404 / EOTP / version conflict. 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`.
 
@@ -42,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
 
@@ -74,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

@@ -1,6 +1,6 @@
 # Consumer grant — `@cyberskill/design`
 
-**Status: in force** (Jul 2026). Policy text — not a secret. License on the package remains **UNLICENSED**; this grant is the approval layer for use in named products.
+**Status: in force** (Jul 2026). Policy text — not a secret. License on the package remains **UNLICENSED**; this grant is the approval layer for use in named products. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 ## Grant
 
@@ -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

@@ -1,10 +1,14 @@
 # Consuming & upgrading the CyberSkill Design System
 
-How any project — human-driven or agent-driven — adopts this HTML-first design system, and how to take updates safely.
+How any project — human-driven or agent-driven — adopts this HTML-first design system, and how to take updates safely. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 **Package name:** `@cyberskill/design` (see `package.json`). Do not treat historical `@cyberskill/react` as the install path for this monolith.
 
-## Claude Code vs Google Stitch
+## When to use
+
+You are installing, linking, or upgrading the system in another product. Maintainers extending the system start at `docs/doctrine.md`.
+
+## Capability paths (DC-capable vs static)
 
 | Consumer | Start here | Works today | Do not |
 |---|---|---|---|
@@ -17,11 +21,11 @@ How any project — human-driven or agent-driven — adopts this HTML-first desi
 
 **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)
+## Quick path for AI agents (DC-capable authoring, or driving one)
 
 **What you get:** `styles.css` (400+ tokens + `.cs-*` classes + Liquid Glass surfaces, `@import`s `tokens/` + `base/`) · `_ds_bundle.js` (compiled React components, no build step) · `_esm/react.mjs` (bundler-native React entry — React as peerDependency; default `exports["."]`) · `_esm/cs.mjs` (browser / no-build legacy via `exports["./legacy"]`) · `_ds_manifest.json` (machine-readable inventory) · per-component `Name.d.ts` (API) + `Name.prompt.md` (usage brief) · `tokens/tokens.dtcg.json` (W3C DTCG) + `tokens.json`/`tokens.js`.
 
-**Repo checkout** — clone or copy the whole tree; everything is relative-path static. Entry points: Storybook on the host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (every component live, portable) · `templates/<slug>/` (copyable starting points — DC for Claude Design; kitchen-sink / `.cs-*` for Stitch). Read `SKILL.md` before authoring anything on-brand; Stitch readers start at `DESIGN.md`. Deeper maps live in `llms.txt` (inventory) and this file (full adoption + upgrade guide below).
+**Repo checkout** — clone or copy the whole tree; everything is relative-path static. Entry points: Storybook on the host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (every component live, portable) · `templates/<slug>/` (copyable starting points — DC when a compiler is present; kitchen-sink / `.cs-*` for Stitch / static). Read `SKILL.md` before authoring anything on-brand; Stitch readers start at `DESIGN.md`. Deeper maps live in `llms.txt` (inventory) and this file (full adoption + upgrade guide below).
 
 **After import — prove health.** Open `_audit/run.html`, let the gate board finish (every fast gate). All green = the copy is internally consistent (contrast, docs, portability, tokens, consumer path, behavior, a11y, stories, bilingual parity). Full-clone only — `_audit/` is not in the npm tarball.
 
@@ -34,7 +38,7 @@ How any project — human-driven or agent-driven — adopts this HTML-first desi
 
 - Anchors (Umber/Ochre), `.cs-*` class names, `--cs-*` token names are stable contracts.
 
-- Extending the system? Follow `CONTRIBUTING.md` (Expansion Rule: propagate to every deliverable in one change; verify via `_audit/`).
+- Extending the system? Follow `docs/doctrine.md` and `CONTRIBUTING.md` (Expansion Rule: propagate to every deliverable in one change; verify via `_audit/`).
 
 ## Adopt via npm (optional)
 
@@ -54,7 +58,7 @@ 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[]`.
 
@@ -64,11 +68,11 @@ Add `transpilePackages: ["@cyberskill/design"]` in Next.js (JSX ships as source)
 
 ## 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 +80,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 +88,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,7 +96,7 @@ 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
 

package/docs/contrast-report.md

@@ -1,6 +1,8 @@
 # Contrast report — elemental pairings (APCA)
 
-Generated 2026-07-27 · sweep at VERSION 1.1.1 pin.
+Generated · sweep at VERSION 1.3.9.
+
+Published on Storybook **Docs** at `design.cyberskill.world`.
 
 **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 +92,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

@@ -1,6 +1,6 @@
 # Conventions — authoring the CyberSkill DS
 
-For humans and agents *extending this system*. (Consumers: read `SKILL.md`.) The compiler is the source of truth for counts; prose describes shape, never numbers.
+For humans and agents *extending this system*. (Consumers: read `SKILL.md`.) Expansion and verification doctrine: `docs/doctrine.md`. The compiler is the source of truth for counts; prose describes shape, never numbers. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 ## The expansion rule
 
@@ -16,7 +16,7 @@ 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
 
@@ -32,7 +32,7 @@ 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).
 
@@ -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

@@ -1,6 +1,6 @@
 # Decisions (maintainer)
 
-Owner choices that shape CI, Figma sync, and distribution. How-tos live in `docs/figma.md` and `docs/ci-cd.md` — this file is the decision record only. Not a consumer guide.
+Owner choices that shape CI, Figma sync, and distribution. How-tos live in `docs/figma.md` and `docs/ci-cd.md` — this file is the decision record only. Not a consumer guide. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 ## 1. Whole-set audits on every PR
 
@@ -53,7 +53,7 @@ Stay on the current Figma plan. Variables REST API is Enterprise-only — write
 **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 tracks root `VERSION`. Approved use is recorded in **`docs/consumer-grant.md`** (CyberSkill portfolio products). Registry install alone is not a public license.
 
@@ -100,7 +100,7 @@ Operational follow-ups — not product marketing, not a backlog surface:
 
 ~~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

@@ -1,5 +1,7 @@
 # Deploying the live Atomic site (Vercel / VPS / any static host)
 
+Published on Storybook **Docs** at `design.cyberskill.world`.
+
 Two tracks:
 
 1. **Portable design system (consumers)** — still a static file tree: no bundler required. Link `styles.css` + optionally `_ds_bundle.js` / ESM. Claude Design, Google Stitch, and product apps never need Node or Storybook.
@@ -48,11 +50,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 +66,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` mirrors the same three headers for hosts that read Netlify-style `_headers` files. Keep it 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 +95,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

@@ -1,6 +1,6 @@
 # Design styles
 
-The live styling axes are **Theme × Element × Language × Style**. Style’s sole pack today is **liquid-glass** (absent `data-cs-style` ≡ liquid-glass — same default pattern as light theme / Thổ middle).
+The live styling axes are **Theme × Element × Language × Style**. Style’s sole pack today is **liquid-glass** (absent `data-cs-style` ≡ liquid-glass — same default pattern as light theme / Thổ middle). Published on Storybook **Docs** at `design.cyberskill.world`.
 
 | Axis | How to set it | What it changes |
 |---|---|---|
@@ -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