@cyberskill/design 1.0.0

package/docs/quality-gates.md

@@ -0,0 +1,94 @@
+# Quality gates — the benchmark reference
+
+Every deterministic quality gate in the system, what it asserts, its pass criterion, whether it blocks (hard) or informs (advisory), and where it runs.
+
+**Where gates run.** *Fast board CI* = the `fast-gates` job in `.github/workflows/design-system-gates.yml`, which serves the repo and drives `_audit/run.html` headless via `_audit/ci/run-gates.mjs` (every push/PR + nightly + manual) — new board rows are picked up automatically. Two gates additionally run standalone as *merge blockers* (`docs-consistency-blocker` job, via `_audit/ci/run-single-gate.mjs`). *Whole-set CI* = the `whole-set-audits` job (every push/PR + nightly — owner decision B). *Unit test* = `npm run test:unit` in the `unit-tests` job (plain Node, no browser). *Node pre-checks* = the `node-prechecks` job (browser-free authorities: bundle freshness, DESIGN.md freshness) plus the `token-provenance` job. Every browser gate publishes a verdict global (`window.__*`) that the headless runners read.
+
+## Fast board — 31 gates in `_audit/run.html`
+
+| Gate | File | What it asserts | Pass criterion | Type | Where it runs |
+|---|---|---|---|---|---|
+| Contrast guard | `_audit/contrast-guard.html` | No base rule paints umber on a themeable surface without a dark override; every semantic text×surface pair scores in light and dark | 0 unshielded rules and 0 failing pairs (`__contrastguard`) | Hard | Fast board CI |
+| Three-axes guard | `_audit/axis-guard.html` | No live source reintroduces the retired Expression/Density product surface | 0 hits across manifest-indexed sources (`__axisguard`) | Hard | Fast board CI |
+| Manifest CSS paths | `_audit/manifest-css-guard.html` | Every `_ds_manifest.json` `globalCssPaths` entry exists as raw CSS; every `styles.css` `@import` is listed | 0 missing / 0 unlisted (`__cssguard`) | Hard | Fast board CI |
+| Docs consistency | `_audit/docs-consistency.html` | Every count claim in README/SKILL/llms.txt matches the compiler manifest; `VERSION` + `package.json` pinned 1.0.0; no changelog-file reference; stale-phrase blacklist (the retired suite/pack counts the Jul 2026 audit removed) clean across README/SKILL/llms + `docs/*.md` (historical notes under `_audit/archive/` are not scanned); `DESIGN.md` exists with front-matter version = `VERSION`; agent routing honesty — Claude path cites `_esm/cs.mjs` + bundle prefix; Stitch path forbids `*.dc.html` as SoT; package name `@cyberskill/design` | 0 mismatched claims, 0 blacklist hits, pin + stamp + routing intact (`__docs`) | Hard | Fast board CI + merge blocker |
+| Docs language parity | `_audit/docs-lang-parity.html` | Every operator-facing EN `docs/*.md` has a `docs/vi/` counterpart; VI is not an empty/TODO stub (≥40% EN length); stale-phrase blacklist clean on both EN and VI (historical notes under `_audit/archive/` are not tracked) | 0 missing pairs, 0 stubs, 0 blacklist hits (`__docslangparity`) | Hard | Fast board CI |
+| DESIGN.md parity | `_audit/design-md-parity.html` | The root `DESIGN.md` (Stitch open-spec surface) byte-equals an in-browser regeneration from `tokens.dtcg.json` + `_ds_manifest.json` + `VERSION` via the shared `scripts/design-md-lib.mjs`; every one of the 138 token rows re-checked individually | Byte-identical + 0 drifted rows (`__designmd`) | Hard | Fast board CI |
+| Version stamp | `_audit/version-stamp.html` | `package.json`, `tokens.json`/`tokens.js` metas, DTCG `$extensions`, `provenance.json` release + dtcgStamp, and `DESIGN.md` front matter all equal `VERSION` (1.0.0 pin) | All 8 stamps equal (`__versionstamp`) | Hard | Fast board CI |
+| Namespace portability | `_audit/namespace-portability.html` | No manifest-indexed source hardcodes the compiler's project-id bundle suffix | 0 hardcoded suffixes (`__nsguard`) | Hard | Fast board CI |
+| Token contract | `_audit/token-contract.html` | All 15 element×variant scopes resolve all 9 `--cs-accent-*` roles; core semantic tokens resolve | 0 missing roles, 0 missing core tokens (`__contract`) | Hard | Fast board CI |
+| Token pipeline | `_audit/token-pipeline-test.html` | Every DTCG-derived constant appears verbatim in all three `tokens/native/` targets; provenance sha-256 matches the DTCG source | 0 drifted constants, hash match (`__tokenpipe`) | Hard | Fast board CI |
+| Token format parity | `_audit/token-format-parity.html` | Every `--cs-*` declaration in `tokens/*.css` equals its mirror in `tokens.json`, `tokens.js` (live ESM deep-equal), and DTCG (ext-css string or typed transform) — base `:root` + dark/system themes + 15 element packs + 15 dark packs; the 4 `_ds_manifest.json` durations equal `motion.css` (guards the reduced-motion 0ms compiler bug) | 0 diffs across all scopes (`__tokenformat`) | Hard | Fast board CI |
+| DTCG typing | `_audit/dtcg-typing.html` | Every DTCG `$value` leaf carries a W3C `$type`; every `{alias}` resolves (chains followed, no cycles); every shadow token is a structured object/array with full layer fields; byType counts equal `provenance.json` | 0 untyped / dangling / string shadows (`__dtcgtyping`) | Hard | Fast board CI |
+| Story coverage | `_audit/story-coverage.html` | Every primary bundle export has an Atomic View story (`guidelines/atomic-view.html`) | 0 missing stories (`__storycov`) | Hard | Fast board CI |
+| Consumer smoke test | `_audit/consumer-smoke-test.html` | The external consumer path works: `styles.css` + `_ds_bundle.js` mount real components and brand tokens reach a rendered Button | Mount + token assertions all pass (`__smoke`) | Hard | Fast board CI |
+| Bundle freshness | `_audit/bundle-freshness.html` | Every source recorded in the `_ds_bundle.js` header re-hashes to the header's sha-256 (browser replication of `ci/check-bundle-freshness.mjs`; the Node script stays the CI authority and additionally discovers new files); manifest component sources ⊆ header | 0 drifted / missing sources (`__bundlefresh`) | Hard | Fast board CI (+ Node authority in `node-prechecks`) |
+| ESM smoke test | `_audit/esm-smoke-test.html` | `_esm/cs.mjs` imports without a build, re-exports every manifest component, and a mounted Button receives brand tokens | Export/manifest parity + token check (`__esm`) | Hard | Fast board CI |
+| Package exports integrity | `_audit/package-exports-integrity.html` | Every `package.json` `files` entry and every `module`/`style`/`exports` target exists; every entry-point target is covered by `files` (pack-safe); `_esm/cs.mjs` is ESM-shaped and its `CS.*` re-exports ⊆ the bundle header's exposed exports | 0 missing / uncovered / unknown (`__pkgexports`) | Hard | Fast board CI |
+| Component children | `_audit/component-children-test.html` | Void-element components (Checkbox, Radio, Switch, SearchField, NumberField, Slider, Divider, TextField) mount with stray children without throwing React #137 | 0 throws (`__result.anyThrew === false`) | Hard | Fast board CI |
+| Component behavior | `_audit/component-behavior-test.html` | 35 real interaction assertions — toggles, controlled selection, palette filtering, overlay open/close, Form rules, Tree/Splitter/keyboard | 35/35 assertions pass (`__behavior`) | Hard | Fast board CI |
+| A11y interactions | `_audit/a11y-gate.html` | Focus management (Dialog/Drawer trap + restore + Escape), roving tabindex, combobox `aria-activedescendant`, role/label contracts | All keyboard/ARIA assertions pass (`__a11y`) | Hard | Fast board CI |
+| A11y CSSOM | `_audit/a11y-harness.html` | Every interactive `.cs-*` control meets its documented touch-target floor under coarse pointer; focus-ring, reduced-motion, and contrast rules proven in source CSS | 0 floor violations, all source proofs found (`__a11ycss`) | Hard | Fast board CI |
+| Template schema v2 | `_audit/template-schema-test.html` | Every `content-schema.json` sidecar validates against the JSON Schema and every declared slot id resolves to a real `{{ hole }}` in its template | 0 invalid sidecars, 0 dangling slot ids (`__schemav2`) | Hard | Fast board CI |
+| Support runtime identity | `_audit/support-runtime-identity.html` | All `templates/*/support.js` copies (one per template, 84) are byte-identical: sha-256 via SubtleCrypto, exactly one unique hash, copy count == manifest template count | 1 unique hash, count match (`__supportid`) | Hard | Fast board CI |
+| Bilingual parity | `_audit/bilingual-parity.html` | Every component in `components/_i18n/strings.js` has en + vi tables with equal key sets and no empty values | 0 missing/extra keys, 0 empty values (`__bilingual`) | Hard | Fast board CI + merge blocker |
+| Template language parity | `_audit/template-lang-parity.html` | Static source scan of all 84 `.dc.html`: en/vi hole-map key sets identical and non-empty (21 map templates); `sc-if` `isEN`/`isVN` branches paired (24 branch templates); every `language`-tweak template has a bilingual mechanism; EN-leak lexicon (Unsubscribe · View in browser · Preferences · All rights reserved · Manage subscription · Sent with) never appears outside `isEN` guards / the `en` map. VN-first stacked instruments (37 `vn-*` + 3 `doc-*`) are leak-exempt by design — both languages always render | 0 key drifts, 0 unpaired branches, 0 leaks (`__langparity`) | Hard | Fast board CI |
+| APCA dark packs | `_audit/apca-dark-preview.html` | All 15 element×variant packs hold their APCA targets in dark (bright-as-text ≥ 75, accent UI ≥ 60, ink-on-accent ≥ 75, ink-on-tint ≥ 75) | 0 current failures (`__apcaPreview.currentFail === 0`) | Hard | Fast board CI |
+| Visual baselines | `_audit/visual-diff.html` | Template baselines exist and are loadable for side-by-side / overlay comparison | Baselines present; drift judged by eye (`__visualdiff`) | Advisory | Fast board CI |
+| Component baselines | `_audit/component-visual-diff.html` | 12 curated component crops anchor the atomic tiers for visual comparison | Crops render + baselines present (`__componentVisualDiff`) | Advisory | Fast board CI |
+| Axe smoke | `_audit/axe-smoke.html` | axe-core 4.10.0 (vendored at `_audit/vendor/axe.min.js`) serious/critical rules on a mounted bilingual component cluster | 0 serious/critical findings (`__axesmoke`) | Hard | Fast board CI |
+| Print smoke | `_audit/print-smoke.html` | Document templates declare the print-ownership meta and `@page` CSS hooks the export path relies on | 0 documents missing print hooks (`__printsmoke`) | Hard | Fast board CI |
+| Pixel CI | `_audit/pixel-ci.html` + `_audit/ci/pixel-diff.mjs` | Curated baselines exist; Playwright capture script performs real % pixel compare; last report must be clean (`drifted[]` empty) | Contract + clean compare (`__pixelci.pass`); drift or missing report fails | Hard | Fast board CI (compare step feeds the row) + `pixel-diff` job |
+
+## Whole-set audits — every template, every axis
+
+| Gate | File | What it asserts | Pass criterion | Type | Where it runs |
+|---|---|---|---|---|---|
+| Responsive overflow | `_audit/responsive-overflow.html` | Every template (84) + 3 UI kits render at 390 px without horizontal document overflow | 0 overflowing surfaces (`__overflow`) | Hard | Whole-set CI (every PR + nightly) |
+| Language overflow | `_audit/language-overflow.html` | Same set forced to Tiếng Việt: VN applies, no overflow, no clipped text in fixed/nowrap boxes | 0 over/clip, 0 VN-not-applied (`__language`) | Hard | Whole-set CI (every PR + nightly) |
+| Theme overflow | `_audit/theme-overflow.html` | Same set forced dark: dark applies, no document overflow, and no reproducible solid-bg leaf-text WCAG fails outside `REVIEWED_OK` | Dark applied + 0 overflow + 0 open contrast (`__theme`) | Hard (allowlisted near-misses only) | Whole-set CI (every PR + nightly) |
+
+## Node pre-checks (browser-free)
+
+| Gate | File | What it asserts | Pass criterion | Type | Where it runs |
+|---|---|---|---|---|---|
+| Token provenance | `_audit/ci/check-token-provenance.mjs` | `tokens/native/` + `tokens/provenance.json` are in lockstep with `tokens/tokens.dtcg.json` (same sha-256 drift authority as the token-pipeline gate) | Exit 0 on hash match | Hard | CI `token-provenance` job |
+| Bundle freshness (authority) | `_audit/ci/check-bundle-freshness.mjs` | The committed `_ds_bundle.js` was built from the component sources as they exist now — full source discovery (walks `components/`, `ui_kits/`, root sources), so new/deleted files are caught too, which the browser row cannot do | Exit 0, 0 drifted/new/deleted sources | Hard | CI `node-prechecks` job |
+| DESIGN.md freshness | `scripts/generate-design-md.mjs --check` | The root `DESIGN.md` byte-equals a fresh regeneration from DTCG + manifest + `VERSION` | Exit 0 on byte match | Hard | CI `node-prechecks` job |
+
+## Unit tests — `npm run test:unit` (8)
+
+| Test | File | What it asserts | Pass criterion | Type | Where it runs |
+|---|---|---|---|---|---|
+| Nav model | `_audit/ci/test-nav-model.mjs` | The shipped `guidelines/nav-model.js` classify/group logic behaves (drives the real module) | All assertions pass (exit 0) | Hard | Unit test |
+| Health/Tokens UI contract | `_audit/ci/test-health-tokens-contract.mjs` | Structural contracts of the Health + Tokens HTML entry points hold | All assertions pass (exit 0) | Hard | Unit test |
+| Form paths | `_audit/ci/test-form-paths.mjs` | Form path helpers behave (drives the shipped `Form.jsx` via dynamic import) | All assertions pass (exit 0) | Hard | Unit test |
+| Storybook contract | `_audit/ci/test-storybook-contract.mjs` | Live hub is Storybook only; SB10 ESM main + addon-docs/a11y; complete CSF for every public primary; Matrix/AllVariants + AllSizes when `argTypes.size`; States/Matrix cover disabled/loading/error/busy; every discrete size/variant enum mounted; FullMatrix required when ≥2 of {size, variant, state} axes exist | All assertions pass (exit 0) | Hard | Unit test |
+| Figma push helpers | `_audit/ci/test-figma-push-helpers.mjs` | Pure helpers in `push-figma-variables.mjs` behave (no network, no secrets) | All assertions pass (exit 0) | Hard | Unit test |
+| Code Connect helpers | `_audit/ci/test-code-connect.mjs` | 99 primaries, node-map/render helpers, soft-skip classifiers, committed `figma.config.json` + high-traffic `.figma.tsx` | All assertions pass (exit 0) | Hard | Unit test |
+| Native samples | `_audit/ci/test-native-samples.mjs` | SwiftUI / Compose / Flutter sample apps each have ≥ 3 screens, reference generated token constants, and ship Fastlane store scaffolds (submit disabled) | All assertions pass (exit 0) | Hard | Unit test |
+| Subtree consume | `_audit/ci/test-subtree-consume.mjs` | Portable copy of `styles.css` + `base/` + `tokens/` + `fonts/` + `_esm/` + `_ds_bundle.js` (no full clone) still resolves tokens/fonts and mounts a Button via ESM — Stitch/Claude subtree-copy path | All assertions pass (exit 0) | Hard | Unit test |
+
+The `test:unit` suite is wired into the CI workflow as part of the July 2026 hardening change (it previously only ran locally).
+
+## Sync / distribution jobs (soft-skip)
+
+Soft-skip means the job exits 0 with a report when secrets/plan/API cannot complete the real write — **not** that npm, Code Connect, or Figma Variables are live. Treat soft-skip as provisional honesty until the remaining maintainer tasks in `docs/decisions.md` land (Code Connect node IDs; npm grant / `NPM_TOKEN`). Schema sidecars and Storybook `FullMatrix` grow opportunistically when a primary already qualifies — not as a mass-add pass.
+
+| Job | Script / workflow | What it asserts | Soft-skip when | Where it runs |
+|---|---|---|---|---|
+| Figma Variables | `_audit/ci/push-figma-variables.mjs` + `figma-variables-push` job | Secrets open the file; optional Variables write | Non-Enterprise / missing `file_variables:*` scopes / API 403 | `main` push + manual |
+| Code Connect | `_audit/ci/code-connect-publish.mjs` + `code-connect` job | Config + 99 mappings; optional publish | Missing `FIGMA_TOKEN`/`FIGMA_FILE_KEY` or API 403/404/429 | PR + `main` + manual |
+| npm publish | `_audit/ci/npm-publish.mjs` + `npm-publish.yml` | Pack-safe `files`/`exports`; optional `npm publish` | Missing `NPM_TOKEN` or registry auth/404/403 | `workflow_dispatch` / `v*` tags |
+| Native store | `_audit/ci/native-store-dry-run.mjs` + `native-store.yml` | Fastlane scaffolds + metadata; signed-release secrets check | Missing `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` (submit always disabled) | PR + `main` (paths) + manual |
+
+## July 2026 hardening — delivered
+
+The eight gates the audit planned (token-format-parity, version-stamp, support-runtime-identity, package-exports-integrity, template-lang-parity, dtcg-typing, bundle-freshness, design-md-parity) are now **implemented** — see their rows in the fast-board and Node-pre-check tables above. All are wired into `_audit/run.html`, `_audit/index.html`, the CI workflow (`fast-gates` picks the board rows up automatically; `node-prechecks` + `unit-tests` are new jobs), and `dashboard.html` (whose Health tab embeds `run.html`, so board rows surface there without a separate list). The docs-consistency gate carries the stale-phrase blacklist (retired suite/pack counts) + `DESIGN.md` stamp extensions described in its row. The docs-lang-parity gate locks the `docs/vi/` mirror.
+
+## Human-reviewed, never automated
+
+- **Brand voice / copy** — warm · direct · honest · respectful is judged by a human, not a regex.
+- **Legal template content** — counsel reviews the instruments; gates only check structure, bilingual mechanics, and print geometry.
+- **Pixel-diff baselines** — Playwright `%` drift auto-fails (hard). After intentional redesigns, refresh `_audit/baselines/` with `pixel-diff.mjs --update` and commit. Side-by-side visual / component review pages stay advisory (judgment by eye).
+- **Component API design review** — prop naming and ergonomics are reviewed by the owner, not asserted.

package/docs/release-notes.md

@@ -0,0 +1,31 @@
+# Release Notes
+
+Curated product highlights for operators. This is **not** a git log and **not** a `CHANGELOG.md` — the design system does not maintain a changelog file. Version stays pinned at **1.0.0**; technical continuity is the repo tip, and product-facing continuity is this page (mirrored in Storybook **Release Notes**).
+
+## Storybook at the domain root
+
+`design.cyberskill.world/` is the full Storybook product site. Docs, Foundations, Components, Release Notes, and Status live in one sidebar. Legacy `/dashboard` and `/playground` paths redirect to `/`.
+
+Portable consumers are unchanged: `styles.css`, `_ds_bundle.js`, and `_esm/cs.mjs` remain the adoption paths. Storybook is host-only tooling.
+
+## Quality gates on Status
+
+The **Status** story embeds the fast gate board (`_audit/run.html`). Hard gates fail the board when broken; advisory rows are labelled clearly and do not flip the aggregate pass. Open Status once to auto-run; use **Re-run** for a fresh pass.
+
+## Bilingual docs and templates
+
+Public operator docs ship EN·VI pairs under `docs/` / `docs/vi/`. Templates remain bilingual EN·VN with fully separated language modes. Component strings resolve from the central registry.
+
+## Foundations and CSF library
+
+Theme × Element × Language toolbar globals mirror production templates. Every public primary ships a Default story plus an honest control matrix. Foundations cover colors, typography, spacing, elevation, motion, and the 15 Ngũ Hành element packs.
+
+## Tokens and native mirrors
+
+CSS tokens, DTCG (`tokens/tokens.dtcg.json`), and pre-generated SwiftUI / Compose / Flutter mirrors stay in lockstep via the token pipeline. Text never sits on mid-tone `-accent` — APCA doctrine is gate-enforced.
+
+## What we never ship
+
+- A root **`CHANGELOG.md`** (forbidden by doctrine and docs-consistency)
+- A VERSION bump without an explicit owner decision
+- Storybook as a consumer dependency

package/docs/storybook.md

@@ -0,0 +1,56 @@
+# Storybook — product surface at `/` (host)
+
+Storybook **10** is the **product site** for operators on `design.cyberskill.world` (`/`). It is still **not** part of the portable consumer contract.
+
+## URL
+
+| Context | Path |
+|---|---|
+| Production | `https://design.cyberskill.world/` |
+| Local packaged site | `/` after `npm run build:site` (serve `.vercel-static/`) |
+| Local dev | `npm run storybook` → http://localhost:6006 |
+| Legacy | `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/` |
+
+## What it includes
+
+- Full component CSF with **Default + deep control matrices** (`Matrix` / `AllVariants`)
+- **CSF bar (exhaustive where axes exist):**
+  - `AllSizes` whenever `argTypes.size` exists (token ramp or representative numeric sizes)
+  - `States` (or a Matrix subsection) covering `disabled` / `loading` / `error` / `busy` when those argTypes exist
+  - Every discrete `size` / `variant` enum option mounted in a matrix-family story
+  - `FullMatrix` when ≥2 of {size enums, variant enums, state keys} exist — the size × variant × key-state product via shared helpers in `stories/lib/matrix.jsx`
+- Toolbar globals: Theme × Element × Language (same axes as templates). Element lists **all 15** Ngũ Hành packs (Identity Lab / `tokens.elements` / template EL maps) — not a subset.
+- **Docs/** public MDX guides; **Release Notes/** curated product prose (**no CHANGELOG.md**); **Status/** embeds `_audit/run.html` full-bleed
+- **Maintainer/** stories for portable HTML surfaces (Motion, Identity Lab, templates, kitchen-sink, AI cluster, RTL; Atomic View buried for gates)
+- Same `styles.css` as production
+- Addons: `@storybook/addon-docs` + `@storybook/addon-a11y` (essentials folded into core in SB10)
+
+## Config
+
+- `.storybook/main.js` — ESM Storybook 10 config, Vite + `@cs` → `components/` alias, **`base: '/'`** for domain-root assets
+- `.storybook/manager-head.html` — OG / canonical meta for the production `/` surface
+- Autodocs via `tags: ['autodocs']` on CSF meta (no `docs.autodocs` in main)
+
+## What consumers still use (unchanged)
+
+| Audience | Consume |
+|---|---|
+| Static / any framework | `styles.css` + `.cs-*` |
+| React production | `styles.css` + `_ds_bundle.js` |
+| ESM | `_esm/cs.mjs` |
+| Tokens | `tokens/*` |
+| Claude Design | `templates/**/*.dc.html` |
+
+## Commands
+
+```bash
+npm install
+npm run storybook
+npm run build:storybook    # → storybook-static/ (base `/`)
+npm run build:site         # packages Storybook at .vercel-static/ root
+npm run test:storybook-contract
+```
+
+## Map
+
+Portable HTML surfaces iframed from Maintainer/* are listed in `docs/live-hub.md`. Status embeds `_audit/run.html` (auto-run on first load; **Re-run** on demand).

package/docs/sync.md

@@ -0,0 +1,48 @@
+# Repo ↔ Claude Design — round-trip fidelity & two-way sync
+
+The GitHub repo (`cyberskill-official/design-system`) is the **source of truth**. Claude Design sessions are ephemeral project filesystems — this doc is how they stay in sync without losing work.
+
+## Does the repo restore the full system intact?
+
+**In a Claude-Design session — yes.** Everything that defines the system is plain text/asset files and round-trips losslessly:
+- `styles.css` + `tokens/` + `base/` (all CSS + `tokens.json`/`tokens.js`)
+- `components/**` (`.jsx` + `.d.ts` + `.prompt.md` + `*.card.html`)
+- `templates/**/*.dc.html` (+ `ds-base.js`, `support.js`)
+- `guidelines/`, `ui_kits/`, `fonts/` (woff2), `assets/`, `docs/`, `_audit/*.html`
+
+- **`_esm/cs.mjs`** — the ESM entry point. Underscore-prefixed does **not** mean build artifact or gitignored here (only `uploads/`, `scraps/`, `_audit/exports/` are — see Hygiene below); `_esm/` is source, same tier as `templates/` or `docs/`. A prior port of this repo skipped it on exactly this assumption and broke the ESM smoke gate — if you're porting/copying this tree by hand, **explicitly include every top-level folder this list names**, don't infer from the `_` prefix.
+
+- `README.md`, `CONTRIBUTING.md`, `SKILL.md`, `CLAUDE.md`, `VERSION`, `DESIGN.md` (generated open-spec surface — committed, regenerated only via `npm run build:design-md`, pinned by the `design-md-parity` gate)
+
+Pull them back into a fresh project (see below) and the compiler re-recognizes it as a design system — it keys off `styles.css`, the `.d.ts`/`.jsx` pairs, `@dsCard` HTML, and `templates/`. The **derived** files (`_ds_bundle.js`, `_ds_manifest.json`, `_adherence.oxlintrc.json`) are regenerated every turn from source, so they need not be trusted from the repo — they rebuild.
+
+**In other agents (Google Stitch, generic LLM tools) — partially.** They can consume the **portable** layer — `tokens/tokens.json` + `tokens.js`, the raw CSS, the component `.jsx`, fonts, and the Markdown docs — but they do **not** understand the `.dc.html` Design-Component format or the compiler that drives it. So a non-Claude-Design agent gets the tokens, styles, and component source as files, not the live DC/tweak/compile behavior. Point those tools at the root **`DESIGN.md`** first (the generated Stitch-style open-spec surface: doctrine + every token value + inventory, regenerated from DTCG via `npm run build:design-md` and pinned by the `design-md-parity` gate), then `tokens.json` / `tokens.dtcg.json` and the CSS for the machine contract; treat `.dc.html` + the compiler as Claude-Design-native.
+
+## Two-way sync (repo = source of truth)
+
+Claude Design can **read/copy from** GitHub but **cannot push to** it. So sync is *automatic pull, manual push*:
+**Session START — pull (reliable, automated):** tell the agent to load the repo. It copies the tree into the fresh project (the `github_copy_files` path), the compiler validates, and you continue from the committed truth — never from stale project state. Always begin here; do not resume from a half-remembered project.
+
+**Session END — push (manual, reviewed):** download the project, then from a clone:
+```
+git checkout -b session/<date-or-topic>
+
+# copy the downloaded files over the working tree (keep .git/, .github/, LICENSE)
+git add -A && git commit -m "DS <VERSION> — <summary>"
+git push -u origin session/<date-or-topic>   # branch, never --force, never straight to main
+
+# open a PR, review the diff, merge
+```
+The PR diff is the safety net — it shows exactly what changed since the last committed truth.
+
+## Hygiene that keeps round-trips clean
+- **`.gitignore`** the transient (`uploads/`, `scraps/`, `_audit/exports/`); commit everything else, **including `_esm/`** (see above — it is source, not a build artifact, despite the `_` prefix). The compiled `_ds_bundle.js`/manifest are committed for consumers that have no build step, but expect churn — or ignore them and let each session regenerate.
+
+- **`VERSION` is pinned at 1.0.0** — do not bump it and do not maintain a changelog file. Continuity is the git history; open maintainer tasks live in `docs/decisions.md`.
+
+- **One source of truth at a time.** Don't edit the repo and a Claude Design project in parallel and push both — pull, work, push, in that order, so the repo is always the merge point.
+
+- **Small, frequent commits** beat one giant end-of-project dump — smaller diffs are safer to review and less likely to silently drop a file.
+
+## TL;DR
+Push this project → the repo is a faithful, restorable archive **for Claude Design** (pull at start, compiler rebuilds the derived files). Other agents get the portable token/style/JSX layer, not the DC runtime. Make it two-way by **pulling from the repo at the start of every session and committing back via PR at the end** — the repo stays the source of truth and no work is lost between ephemeral sessions.

package/docs/template-schema-v2.md

@@ -0,0 +1,36 @@
+# Template content-schema v2 — typed content slots
+
+Purely additive, opt-in metadata: a sidecar `templates/<slug>/content-schema.json` next to a template's `.dc.html`, declaring the **type** of each `{{ hole }}` already in the template — so an agent or pipeline can populate/validate real client content programmatically without parsing HTML or guessing.
+
+**Zero template-markup changes required.** The slot `id` is the hole name already used in the `.dc.html` (e.g. `{{ heroH }}`) and already bound in the logic class's `renderVals()` — the schema just describes it.
+
+## Shape
+
+```json
+{
+  "$schemaVersion": "2.0",
+  "template": "marketing-page",
+  "slots": [
+    { "id": "heroH", "type": "text", "label": "Hero headline", "maxLength": 70, "required": true },
+    { "id": "heroP", "type": "richtext", "label": "Hero paragraph" },
+    { "id": "svcKicker", "type": "text", "label": "Services eyebrow", "maxLength": 40 }
+  ]
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `$schemaVersion` | yes | `"2.0"` for this spec |
+| `template` | yes | matches the `templates/<slug>/` folder name |
+| `slots[].id` | yes | must equal a real `{{ id }}` hole present in the sibling `.dc.html` |
+| `slots[].type` | yes | one of: `text`, `richtext`, `image`, `link`, `list`, `table`, `date` |
+| `slots[].label` | yes | human-readable, for a content-fill UI |
+| `slots[].maxLength` | no | text/richtext only — a soft authoring guide, not enforced by DC |
+| `slots[].required` | no | default `false` |
+| `slots[].i18n` | no | `{"en": "...", "vi": "..."}` — for templates that ship EN·VI variants |
+
+The formal machine-checkable shape lives in `templates/schema/content-schema.schema.json` (JSON Schema draft-07). `_audit/template-schema-test.html` validates every sidecar that exists — bidirectionally: every declared slot id must resolve to a real hole in the template, and (informationally) reports coverage across all `templates/`.
+
+## Rollout
+
+Like the visual-diff baselines, this shipped **intentionally incomplete** at first — three exemplars (one per major archetype) proved the pattern end-to-end: `marketing-page` (product), `bod-report` (document), `slide-deck` (deck). It has since been **swept to every hole-driven template** and keeps growing; current sidecar coverage is reported by `_audit/template-schema-test.html` (high-traffic product surfaces such as `marketing-page`, `dashboard`, `settings`, plus `tech-incident-report` gained fuller content-slot coverage). Axis / control-flow holes (`rootTheme`, `langAttr`, `elAttr`, `vaAttr`, `isEN`, `true`, …) stay out of schema — they are runtime axes, not authorable content. The rest of the suite hardcodes bilingual copy directly per `sc-if` language branch (no `{{ hole }}` content slots yet). Add a sidecar to any template that gains hole-driven content as it's touched; prefer measurable growth on high-traffic templates first.

package/docs/vi/ci-cd.md

@@ -0,0 +1,84 @@
+# CI/CD — tự động hóa bảng gate
+
+**Gate CI** (workflow này) vẫn coi design system như cây tĩnh: serve repo, mở `_audit/run.html` headless, đọc verdict globals. Không cần product bundler cho gates.
+
+**Host deploy** (Vercel, tách khỏi workflow này) chạy `npm install` + `npm run build:site` để Storybook ship làm bề mặt sản phẩm tại `/` — xem `docs/deploy.md` và `docs/storybook.md`. Đường đóng gói host đó không bắt buộc cho consuming project hay các job gate bên dưới.
+
+## 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)
+
+## Những gì đã nối (`.github/workflows/design-system-gates.yml`)
+
+1. **`fast-gates`** — `npm ci` + Playwright Chromium cache, serve repo, mở `_audit/run.html` headless (`_audit/ci/run-gates.mjs`), fail khi hard-gate fail. Upload import-report khi fail. Hàng mới trên board (hardening Th7 2026 thêm 8: token-format-parity, version-stamp, support-runtime-identity, package-exports-integrity, template-lang-parity, dtcg-typing, design-md-parity, bundle-freshness) được nhận tự động — runner đọc `window.__run`, không phải danh sách gate phía job.
+2. **`token-provenance`** — kiểm Node không trình duyệt: natives + `provenance.json` khớp sha-256 nguồn DTCG.
+3. **`unit-tests`** — `npm run test:unit` (8 contract test Node thuần; nối vào CI bởi hardening Th7 2026 — trước đó chỉ local).
+4. **`node-prechecks`** — authority Node không trình duyệt: `_audit/ci/check-bundle-freshness.mjs` (nguồn chân lý bundle-freshness — khám phá source đầy đủ gồm file mới/xóa; hàng board chỉ re-hash file ghi trong header) và `scripts/generate-design-md.mjs --check` (`DESIGN.md` gốc byte-equals regeneration).
+5. **`docs-consistency-blocker`** — merge blocker `docs-consistency` + `bilingual-parity`.
+6. **`whole-set-audits`** — quyết định B của owner: mọi push/PR, cộng nightly `0 3 * * *` và `workflow_dispatch` (responsive + language + theme overflow, ~15–20 phút).
+7. **`figma-variables-push`** — trên push `main` + thủ công. Quyết định A (non-Enterprise): Variables REST soft-skip; secrets vẫn chứng minh mở file. Xem `docs/figma.md`.
+8. **`code-connect`** — trên PR + `main` + thủ công. Quyết định 1C: dry-run luôn (config + 99 mapping); publish soft-skip khi thiếu `FIGMA_TOKEN` / `FIGMA_FILE_KEY` hoặc API 403/404/429. Xem `docs/figma.md`.
+9. **`regenerate-tokens`** — path-filtered trên push/PR (`tokens.dtcg.json`, natives, generator, `VERSION`); luôn có trên schedule/manual. Output native deterministic; push với `contents: write` (hoặc `DS_PUSH_TOKEN`).
+
+Workflow riêng **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + tag `v*`; pack dry-run luôn; publish soft-skip khi thiếu `NPM_TOKEN`. Phiên bản giữ **1.0.0**; license **UNLICENSED**.
+
+Workflow riêng **`native-store`** (`.github/workflows/native-store.yml`): PR + `main` (path-filtered) + `workflow_dispatch`; dry-run scaffold luôn; kiểm signed-release soft-skip khi thiếu `ASC_KEY_ID` / `ASC_ISSUER_ID` / `ASC_KEY_P8` / `PLAY_SERVICE_ACCOUNT_JSON`. **Không bao giờ submit** lên App Store / Play — sample vẫn là sample. Xem `examples/native/README.md`.
+
+Node **22** trên runner (tránh deprecation action Node 20). Cache key Playwright: `package-lock.json`.
+
+## Pattern cài runner (job Playwright)
+
+```yaml
+- run: npm ci
+- uses: actions/cache@v4
+  with:
+    path: ~/.cache/ms-playwright
+    key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-chromium
+- run: npx playwright install --with-deps chromium
+```
+
+## Quyền auto-commit token
+
+Job yêu cầu `permissions: contents: write`. Nếu org khóa default token read-only, đặt repository secret `DS_PUSH_TOKEN` (fine-grained PAT, Contents read/write) hoặc mở write tại org Actions settings. Xem ghi chú trước trong git history / org settings.
+
+## Branch protection (khuyến nghị)
+
+Require status checks trên `main` trước merge:
+
+- `fast-gates`
+- `docs-consistency-blocker`
+
+Tùy chọn: `whole-set-audits` (dài). Cấu hình dưới repo **Settings → Branches** hoặc qua `gh api` (admin).
+
+## Chạy local
+
+```bash
+npx serve -l 8080 .
+npx playwright install --with-deps chromium
+node _audit/ci/run-gates.mjs http://127.0.0.1:8080/_audit/run.html
+node _audit/ci/check-token-provenance.mjs
+node _audit/ci/check-bundle-freshness.mjs
+node scripts/generate-design-md.mjs --check
+npm run test:unit
+node _audit/ci/run-single-gate.mjs http://127.0.0.1:8080/_audit/docs-consistency.html __docs
+node _audit/ci/generate-native-tokens.mjs
+```
+
+## Những gì KHÔNG auto-fail (có chủ đích)
+
+- **Hàng visual / component baseline side-by-side** — chỉ advisory (drift đánh giá bằng mắt). So sánh `%` pixel Playwright là gate **hard** (job `pixel-diff` + hàng Pixel CI trên board).
+- **Figma Variables write trên non-Enterprise** — soft-skip kèm report artifact.
+- **Code Connect publish** — soft-skip khi thiếu secret hoặc API 403/404/429 (Quyết định 1C).
+- **npm publish** — soft-skip khi thiếu `NPM_TOKEN` (Quyết định 1C).
+- **Native store signed release** — soft-skip khi thiếu `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` (Quyết định 1C); submit store vẫn tắt.
+
+## Soft-skip dry-run (local)
+
+```bash
+npm run code-connect:dry-run          # config + ≥99 mapping; không secret
+node _audit/ci/code-connect-publish.mjs   # thiếu secret → SOFT SKIP missing_secrets
+npm run npm:pack-dry-run              # inventory tarball; không NPM_TOKEN
+node _audit/ci/npm-publish.mjs        # thiếu NPM_TOKEN → SOFT SKIP missing_secrets
+npm run native:store-dry-run          # scaffold Fastlane + metadata; không ASC_*/Play JSON
+node _audit/ci/native-store-dry-run.mjs   # thiếu secret → SOFT SKIP missing_secrets
+```

package/docs/vi/consuming.md

@@ -0,0 +1,109 @@
+# Tiêu thụ & nâng cấp CyberSkill Design System
+
+Cách mọi project — do người hoặc agent điều khiển — áp dụng design system HTML-first này, và cách nhận update an toàn.
+
+**Tên package:** `@cyberskill/design` (xem `package.json`). Không coi `@cyberskill/react` lịch sử là đường cài cho monolith này.
+
+## Claude Code vs Google Stitch
+
+| Consumer | Bắt đầu tại | Hoạt động hôm nay | Không làm |
+|---|---|---|---|
+| **Claude Code** | `SKILL.md` → `README.md` → `styles.css` + `_esm/cs.mjs` / `_ds_bundle.js` (resolve theo prefix) | Mạnh — rules, components, prompts; gates qua full clone | Hardcode hậu tố bundle; coi Storybook host là hợp đồng portable |
+| **Google Stitch** | `DESIGN.md` → `llms.txt` → `tokens/tokens.dtcg.json` | Mạnh cho doctrine + tokens + HTML tĩnh `.cs-*` | Coi `templates/**/*.dc.html` là SoT — không có tweaks / `__dcSetProps` / DC compiler |
+| **Claude Design** | Full repo + DC compiler | Full fidelity (tweaks, `x-import`, template bilingual) | Bỏ qua vòng sync trong `docs/sync.md` |
+| **npm** | `@cyberskill/design` | Hình dạng package đã gate; dry-run luôn | Giả định cài public đã duyệt — cần grant owner + `NPM_TOKEN` (soft-skip cho đến khi đó) |
+
+**Quy tắc DC cho Stitch:** Stitch (và mọi tool non-DC) **không** được tiêu thụ `*.dc.html` như nguồn chân lý. Dùng pattern export tĩnh, `templates/kitchen-sink.html`, `examples/static-hello/`, và class `.cs-*` từ `styles.css`.
+
+**Tín hiệu release:** VERSION giữ **1.0.0** (không CHANGELOG). Coi **git tip SHA** là chân lý kỹ thuật; đọc điểm nổi bật sản phẩm curated trong `docs/release-notes.md`.
+
+## Đường nhanh cho AI agent (Claude Code, hoặc điều khiển một agent)
+
+**Bạn nhận:** `styles.css` (400+ token + class `.cs-*` + bề mặt Liquid Glass, `@import` `tokens/` + `base/`) · `_ds_bundle.js` (React component đã compile, không cần build) · `_esm/cs.mjs` (entry ESM re-export mọi component) · `_ds_manifest.json` (inventory máy đọc được) · mỗi component `Name.d.ts` (API) + `Name.prompt.md` (brief dùng) · `tokens/tokens.dtcg.json` (W3C DTCG) + `tokens.json`/`tokens.js`.
+
+**Checkout repo** — clone hoặc copy cả cây; mọi thứ là static đường dẫn tương đối. Điểm vào: Storybook trên host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (mọi component live, portable) · `templates/<slug>/` (điểm bắt đầu copy được — DC cho Claude Design; kitchen-sink / `.cs-*` cho Stitch). Đọc `SKILL.md` trước khi author bất kỳ thứ gì on-brand; reader Stitch bắt đầu tại `DESIGN.md`. Bản đồ sâu hơn ở `llms.txt` (inventory) và file này (hướng dẫn adopt + upgrade đầy đủ bên dưới).
+
+**Sau import — chứng minh health.** Mở `_audit/run.html`, để bảng gate chạy xong (mọi fast gate). Tất cả xanh = bản copy nhất quán nội bộ (contrast, docs, portability, tokens, consumer path, behavior, a11y, stories, bilingual parity). Chỉ full-clone — `_audit/` không nằm trong tarball npm.
+
+**Quy tắc giữ transfer lossless:**
+- Không bao giờ hardcode hậu tố namespace bundle (xem "Resolve by prefix" bên dưới — gate enforce).
+
+- Không bao giờ tạo lại/đổi màu logo — dùng `assets/logo-mark.svg` / component `Logo`.
+
+- Mọi chuỗi UI ship EN + VN qua registry; không inline chuỗi một ngôn ngữ trong component.
+
+- Anchors (Umber/Ochre), tên class `.cs-*`, tên token `--cs-*` là hợp đồng ổn định.
+
+- Mở rộng hệ thống? Theo `CONTRIBUTING.md` (Expansion Rule: lan tới mọi deliverable trong một change; verify qua `_audit/`).
+
+## Adopt qua npm (tùy chọn)
+
+Package có thể publish (`private: false`, phiên bản cố định **1.0.0**). License vẫn **UNLICENSED** — cài từ registry (hoặc tarball đã pack) **không** tự cấp quyền redistribution. Đến khi owner chọn license mở, **consumer cần grant tường minh** từ CyberSkill để dùng package trong sản phẩm. Org `@cyberskill` và `NPM_TOKEN` trên repo đã sẵn sàng vận hành; chạy **Actions → npm-publish** một lần để `@cyberskill/design` lên registry. Thiếu `NPM_TOKEN` thì workflow **soft-skip** (exit 0 + report) — đó là trung thực, không phải release registry thành công. Xem `docs/decisions.md` và `docs/quality-gates.md`.
+
+**Grant consumer (chính sách owner — không phải secret).** Với mỗi team được duyệt, ghi lại kiểu: *CyberSkill cấp cho [Team/Org] quyền không độc quyền dùng `@cyberskill/design` trong [sản phẩm đã nêu]. Package vẫn UNLICENSED; redistribution ngoài các sản phẩm đó cần grant viết thêm.* Giữ văn bản grant nội bộ trừ khi muốn công khai.
+
+```bash
+# sau khi workflow npm-publish chạy thành công (hoặc từ tarball đã pack)
+npm install @cyberskill/design@1.0.0
+```
+
+Rồi link styles và import từ entry package (`_esm/cs.mjs` qua `exports["."]`) , hoặc tiếp tục dùng đường cây tĩnh bên dưới. Tarball đã publish là **cả cây portable** (styles, tokens, components, templates, guidelines, docs, UI kits) — không phải subset “chỉ lib” tối thiểu. Tooling chỉ-host (Storybook, `_audit/`) không nằm trong `files[]`.
+
+**Đường publish (maintainer):** `prepublishOnly` chạy `build:bundle` + `build:design-md --check`. Workflow `.github/workflows/npm-publish.yml` trên `workflow_dispatch` / tag `v*`; publish cần `NPM_TOKEN` (`node _audit/ci/npm-publish.mjs --dry-run` luôn liệt kê tarball). Xem `docs/ci-cd.md` và `docs/decisions.md`.
+
+## Adopt (hai đường, cộng shortcut module)
+
+**1. Static / prototype / mock — link stylesheet.** Copy `styles.css` (+ `tokens/`, `base/`, `fonts/` mà nó `@import`, hoặc serve cả cây) và link; bạn có mọi token `--cs-*`, class component `.cs-*`, và bề mặt Liquid Glass. Compose bằng class (xem `templates/kitchen-sink.html`). Copy mọi asset bạn tham chiếu từ `assets/`.
+
+**2. React production — nạp compiled bundle.** Link `styles.css` và `<script src="_ds_bundle.js">`, rồi đọc component từ namespace. **Resolve theo prefix, không hardcode:** bundle expose `window.CyberSkillDesignSystem_<projectId>`, và hậu tố 6-hex đó do compiler gán và **đổi khi import vào project khác**:
+```html
+<link rel="stylesheet" href="<path>/styles.css">
+<script src="<path>/_ds_bundle.js"></script>
+<script>
+ const CS = window[Object.keys(window).find(k => /^CyberSkillDesignSystem_/.test(k))];
+ const { Button, TextField, DataGrid } = CS;
+</script>
+```
+Đây đúng là những gì `_audit/consumer-smoke-test.html` chạy (và assert xanh) — và `ds-base.js` của templates làm tương tự, publish alias ổn định `window.CyberSkillDS`.
+**2b. Đường ESM (module) — một import, không build.** `import { Button, TextField } from "<path>/_esm/cs.mjs"` — module tự ensure React (pinned; bỏ qua khi đã có `window.React`), side-load `_ds_bundle.js` một lần, resolve namespace theo prefix, và re-export mọi component (`_audit/esm-smoke-test.html` giữ danh sách export khóa với manifest). Vẫn tự link `styles.css`.
+
+**Templates.** Mỗi `templates/<slug>/` là Design Component seed từ `ds-base.js` (một dòng `base` để rebind đường dẫn tới nơi hệ thống này nằm tương đối với trang tiêu thụ). Copy thư mục và sửa copy/tweaks.
+
+**Token máy đọc được.** `tokens/tokens.json` + `tokens/tokens.js` (ESM) + `tokens/tokens.dtcg.json` (W3C DTCG, cho Tokens Studio/Style Dictionary) expose mọi token nhóm theo category + map theme/element — cho pipeline native/mobile/design-tool. **Native build ship sẵn** trong `tokens/native/` (SwiftUI `CSTokens.swift` · Compose `CSTokens.kt` · Flutter `cs_tokens.dart`) kèm `tokens/provenance.json` (release, source sha-256, quy tắc chuyển đổi, sha-256 từng target); gate `token-pipeline` giữ chúng khóa với nguồn DTCG.
+
+**HTML tĩnh / không React / không build tooling.** Link `styles.css` và compose bằng class `.cs-*` — catalog đầy đủ trong `templates/kitchen-sink.html`.
+
+## Ba trục
+
+Đặt Theme (`data-theme`), Element (`data-cs-element` + `data-cs-variant`), và Language (`lang` / Language tweak trên template) trên một container; mọi thứ bên trong re-skin không cần đổi code (xem `templates/playground.html`). Mặc định: `light · tho · en`. Xử lý bề mặt là liquid-glass (cố định). Bilingual: component resolve chuỗi từ `lang` (`lang="vi"` trên mọi container → tiếng Việt đầy đủ).
+
+## Nâng cấp
+
+- **Phiên bản cố định.** `VERSION` và `package.json` giữ **1.0.0**. Không có file changelog design-system — coi **git tip SHA** là chân lý kỹ thuật, và đọc **Release Notes** curated (Storybook + `docs/release-notes.md`) cho điểm nổi bật hướng sản phẩm.
+
+- Anchors (Umber/Ochre), tên class `.cs-*`, và tên token `--cs-*` là hợp đồng ổn định — an toàn để phụ thuộc. Đổi tên phá vỡ những hợp đồng đó phải hiếm và được gọi ra trong PR/docs khi xảy ra.
+
+- **Chạy lại smoke test sau nâng cấp.** Mở `_audit/consumer-smoke-test.html` và bảng Health đầy đủ (`_audit/run.html`) trên tip mới — runner chứng minh đường packaged vẫn resolve.
+
+## Host Storybook (tùy chọn)
+
+Site live phục vụ Storybook tại `/` như **bề mặt sản phẩm** cho operator (Theme × Element × Language + ma trận điều khiển). Đó là **tooling chỉ-host** — đừng phụ thuộc Storybook trong product app. Atomic View portable vẫn ở `guidelines/atomic-view.html`. Xem `docs/storybook.md` và `docs/live-hub.md`.
+
+## Spike consumer năm phút
+
+```bash
+# từ monorepo root
+python3 -m http.server 8765 --bind 127.0.0.1
+# mở http://127.0.0.1:8765/examples/static-hello/
+# rồi http://127.0.0.1:8765/_audit/consumer-smoke-test.html
+```
+
+Sửa `examples/static-hello/index.html`: flip `data-theme="dark"` hoặc `data-cs-element="thuy"` trên `<body>`. Không install, không Storybook.
+
+## Native sample hosts (tùy chọn)
+
+Sample đa màn hình (Sign in · Home · Settings) nằm dưới `examples/native/swiftui`, `compose`, và `flutter`. Chúng sync token generate qua `node examples/native/sync-tokens.mjs`. Xem `examples/native/README.md`. Không bắt buộc cho web consumer.
+
+## Mở rộng
+
+Nếu bạn đang đổi chính hệ thống (không chỉ tiêu thụ), theo `CONTRIBUTING.md` — Expansion Rule (lan tới mọi deliverable trong một change) và doctrine verification (deep check qua `_audit/`).

package/docs/vi/contrast-report.md

@@ -0,0 +1,125 @@
+# Báo cáo contrast — cặp elemental (APCA)
+
+Sinh 2026-07-22 · sweep tại pin VERSION 1.0.0.
+
+**Doctrine mã hóa bởi sweep này:** chữ nằm trên `-bright` hoặc `-tint`, không bao giờ trên mid-tone `-accent` — ở mọi kích thước. Accent chỉ cho thanh, border, progress fill, và fill không-chữ. (Quy tắc trong `tokens/elements.css` và conventions.)
+
+Nudge token cho v2.0: bright làm sáng cho clay, hoa, lava, plasma, thủy, ocean, forest, titanium; `-on` đảo tối cho lava, ocean, forest, titanium.
+| Phạm vi | Cặp | fg / bg | Lc | Kết quả |
+|---|---|---|---|---|
+| root (Thổ default) | text-accent on white (bold labels) | #6E3B0E / #FFFFFF | 90.7 | ✓ |
+| root (Thổ default) | text-accent on tint (bold labels) | #6E3B0E / #FBF4E9 | 84.6 | ✓ |
+| root (Thổ default) | accent-bright on ink (headings) | #F4BA17 / #45210E | 66.3 | ✓ |
+| root (Thổ default) | accent-on on accent-bright (CTA text) | #45210E / #F4BA17 | 66.3 | ✓ |
+| root (Thổ default) | accent-bright on dark panel (dark labels) | #F4BA17 / #221710 | 69.2 | ✓ |
+| tho | text-accent on white (bold labels) | #6E3B0E / #FFFFFF | 90.7 | ✓ |
+| tho | text-accent on tint (bold labels) | #6E3B0E / #FBF4E9 | 84.6 | ✓ |
+| tho | accent-bright on ink (headings) | #F4BA17 / #45210E | 66.3 | ✓ |
+| tho | accent-on on accent-bright (CTA text) | #45210E / #F4BA17 | 66.3 | ✓ |
+| tho | accent-bright on dark panel (dark labels) | #F4BA17 / #221710 | 69.2 | ✓ |
+| tho   · clay | text-accent on white (bold labels) | #8F5230 / #FFFFFF | 80.4 | ✓ |
+| tho   · clay | text-accent on tint (bold labels) | #8F5230 / #F8EDE4 | 70.7 | ✓ |
+| tho   · clay | accent-bright on ink (headings) | #EDBF9D / #2E1607 | 71.6 | ✓ |
+| tho   · clay | accent-on on accent-bright (CTA text) | #2E1607 / #EDBF9D | 72 | ✓ |
+| tho   · clay | accent-bright on dark panel (dark labels) | #EDBF9D / #221710 | 72 | ✓ |
+| tho   · sand | text-accent on white (bold labels) | #8A6F3C / #FFFFFF | 72.9 | ✓ |
+| tho   · sand | text-accent on tint (bold labels) | #8A6F3C / #FAF3E3 | 66 | ✓ |
+| tho   · sand | accent-bright on ink (headings) | #EFDCB2 / #3A2A10 | 82 | ✓ |
+| tho   · sand | accent-on on accent-bright (CTA text) | #3A2A10 / #EFDCB2 | 80.8 | ✓ |
+| tho   · sand | accent-bright on dark panel (dark labels) | #EFDCB2 / #221710 | 85.1 | ✓ |
+| hoa | text-accent on white (bold labels) | #A93E14 / #FFFFFF | 80 | ✓ |
+| hoa | text-accent on tint (bold labels) | #A93E14 / #FBEADF | 69.3 | ✓ |
+| hoa | accent-bright on ink (headings) | #F6A26B / #231007 | 62 | ✓ |
+| hoa | accent-on on accent-bright (CTA text) | #231007 / #F6A26B | 63.3 | ✓ |
+| hoa | accent-bright on dark panel (dark labels) | #F6A26B / #221710 | 61.6 | ✓ |
+| hoa   · lava | text-accent on white (bold labels) | #9B2D14 / #FFFFFF | 85.1 | ✓ |
+| hoa   · lava | text-accent on tint (bold labels) | #9B2D14 / #FAE5DC | 72.1 | ✓ |
+| hoa   · lava | accent-bright on ink (headings) | #F6AC85 / #1D0B05 | 66.5 | ✓ |
+| hoa   · lava | accent-on on accent-bright (CTA text) | #1D0B05 / #F6AC85 | 67.6 | ✓ |
+| hoa   · lava | accent-bright on dark panel (dark labels) | #F6AC85 / #221710 | 65.7 | ✓ |
+| hoa   · plasma | text-accent on white (bold labels) | #B02348 / #FFFFFF | 81.2 | ✓ |
+| hoa   · plasma | text-accent on tint (bold labels) | #B02348 / #FBE6EB | 69.3 | ✓ |
+| hoa   · plasma | accent-bright on ink (headings) | #F7A8B8 / #200812 | 66.8 | ✓ |
+| hoa   · plasma | accent-on on accent-bright (CTA text) | #200812 / #F7A8B8 | 67.9 | ✓ |
+| hoa   · plasma | accent-bright on dark panel (dark labels) | #F7A8B8 / #221710 | 66.1 | ✓ |
+| thuy | text-accent on white (bold labels) | #2F5E6B / #FFFFFF | 84.7 | ✓ |
+| thuy | text-accent on tint (bold labels) | #2F5E6B / #E6F1F2 | 75.1 | ✓ |
+| thuy | accent-bright on ink (headings) | #A6D0DA / #0E1D20 | 72.4 | ✓ |
+| thuy | accent-on on accent-bright (CTA text) | #0E1D20 / #A6D0DA | 72.8 | ✓ |
+| thuy | accent-bright on dark panel (dark labels) | #A6D0DA / #221710 | 72.5 | ✓ |
+| thuy   · ocean | text-accent on white (bold labels) | #1C3E56 / #FFFFFF | 95.7 | ✓ |
+| thuy   · ocean | text-accent on tint (bold labels) | #1C3E56 / #E4EEF4 | 84.7 | ✓ |
+| thuy   · ocean | accent-bright on ink (headings) | #A9CCE0 / #0B161E | 71.8 | ✓ |
+| thuy   · ocean | accent-on on accent-bright (CTA text) | #0B161E / #A9CCE0 | 72.6 | ✓ |
+| thuy   · ocean | accent-bright on dark panel (dark labels) | #A9CCE0 / #221710 | 71.4 | ✓ |
+| thuy   · mist | text-accent on white (bold labels) | #4A686E / #FFFFFF | 80 | ✓ |
+| thuy   · mist | text-accent on tint (bold labels) | #4A686E / #F0F6F7 | 73.9 | ✓ |
+| thuy   · mist | accent-bright on ink (headings) | #C4DADD / #16262A | 78.9 | ✓ |
+| thuy   · mist | accent-on on accent-bright (CTA text) | #16262A / #C4DADD | 78.5 | ✓ |
+| thuy   · mist | accent-bright on dark panel (dark labels) | #C4DADD / #221710 | 80.3 | ✓ |
+| moc | text-accent on white (bold labels) | #4C6B35 / #FFFFFF | 80.2 | ✓ |
+| moc | text-accent on tint (bold labels) | #4C6B35 / #EEF3E2 | 71.8 | ✓ |
+| moc | accent-bright on ink (headings) | #A9C177 / #18200F | 62.3 | ✓ |
+| moc | accent-on on accent-bright (CTA text) | #18200F / #A9C177 | 63.2 | ✓ |
+| moc | accent-bright on dark panel (dark labels) | #A9C177 / #221710 | 62.8 | ✓ |
+| moc   · bamboo | text-accent on white (bold labels) | #5B7237 / #FFFFFF | 76.7 | ✓ |
+| moc   · bamboo | text-accent on tint (bold labels) | #5B7237 / #F3F7E8 | 70.8 | ✓ |
+| moc   · bamboo | accent-bright on ink (headings) | #C4D69B / #1C240F | 75 | ✓ |
+| moc   · bamboo | accent-on on accent-bright (CTA text) | #1C240F / #C4D69B | 75 | ✓ |
+| moc   · bamboo | accent-bright on dark panel (dark labels) | #C4D69B / #221710 | 76 | ✓ |
+| moc   · forest | text-accent on white (bold labels) | #31481F / #FFFFFF | 93.4 | ✓ |
+| moc   · forest | text-accent on tint (bold labels) | #31481F / #E9EFE1 | 82.6 | ✓ |
+| moc   · forest | accent-bright on ink (headings) | #B3CE9B / #101708 | 71 | ✓ |
+| moc   · forest | accent-on on accent-bright (CTA text) | #101708 / #B3CE9B | 71.8 | ✓ |
+| moc   · forest | accent-bright on dark panel (dark labels) | #B3CE9B / #221710 | 70.5 | ✓ |
+| kim | text-accent on white (bold labels) | #6E6151 / #FFFFFF | 80.1 | ✓ |
+| kim | text-accent on tint (bold labels) | #6E6151 / #F3EFE6 | 70.7 | ✓ |
+| kim | accent-bright on ink (headings) | #D8CCB6 / #221C12 | 74.7 | ✓ |
+| kim | accent-on on accent-bright (CTA text) | #221C12 / #D8CCB6 | 74.9 | ✓ |
+| kim | accent-bright on dark panel (dark labels) | #D8CCB6 / #221710 | 75.1 | ✓ |
+| kim   · steel | text-accent on white (bold labels) | #565C5E / #FFFFFF | 83.5 | ✓ |
+| kim   · steel | text-accent on tint (bold labels) | #565C5E / #EFF1F1 | 74.9 | ✓ |
+| kim   · steel | accent-bright on ink (headings) | #C2C6C6 / #191D1E | 70 | ✓ |
+| kim   · steel | accent-on on accent-bright (CTA text) | #191D1E / #C2C6C6 | 70.6 | ✓ |
+| kim   · steel | accent-bright on dark panel (dark labels) | #C2C6C6 / #221710 | 70.3 | ✓ |
+| kim   · titanium | text-accent on white (bold labels) | #56504A / #FFFFFF | 87.6 | ✓ |
+| kim   · titanium | text-accent on tint (bold labels) | #56504A / #EFEBE5 | 76 | ✓ |
+| kim   · titanium | accent-bright on ink (headings) | #D9CFC0 / #171310 | 77.5 | ✓ |
+| kim   · titanium | accent-on on accent-bright (CTA text) | #171310 / #D9CFC0 | 77.9 | ✓ |
+| kim   · titanium | accent-bright on dark panel (dark labels) | #D9CFC0 / #221710 | 76.9 | ✓ |
+
+**Thất bại: 0.** Mọi cặp chữ pass Lc ≥ 60.
+
+## Màu semantic dark-theme (WCAG, thêm v2.8.0)
+
+Foreground semantic light-theme fail trên bề mặt tối (~2.5:1), nên dark theme override chúng. Contrast WCAG trên panel tối `#221710` (và khi làm fill kèm dark ink `#1a1108`):
+| Vai trò | Giá trị dark | trên panel | làm fill w/ ink | Kết quả |
+|---|---|---|---|---|
+| success | #4ADE80 | 10.06 | 10.69 | ✓ |
+| danger | #F87171 | 6.34 | 6.73 | ✓ |
+| warning | #FBBF24 | 10.50 | 11.16 | ✓ |
+| info | #7CB2FB | 8.03 | 8.53 | ✓ |
+
+Core dark cũng remap nút primary sang Ochre (`#f4ba17` trên `#1a1108`) và làm ấm border field — để không control dark nào low-contrast. Shadow dark nhuốm umber (yếu trên nền tối vốn vậy); hairline border dark tách panel thay thế.
+File này được generate — chạy lại script APCA sweep sau mọi đổi token.
+
+## Pack elemental dark — xác minh APCA (v4.0.0, Th7 2026)
+
+Sinh với pack dark đã owner duyệt; đo bằng cùng implementation SAPC-4g như `_audit/apca-dark-preview.html` (cũng là regression gate). Mục tiêu: bright ≥ 75 · accent ≥ 60 · button ink ≥ 75 · ink-on-tint ≥ 75 — **15/15 pack pass**.
+| Pack | bright | accent | on/strong | ink/tint |
+|---|---|---|---|---|
+| tho | 75 | 69.2 | 75.1 | 75.3 |
+| tho · clay | 75.7 | 61.5 | 76 | 76.1 |
+| tho · sand | 85.1 | 74.3 | 75.7 | 83.6 |
+| hoa | 75.1 | 61.5 | 75.6 | 75.9 |
+| hoa · lava | 75 | 60.6 | 83.5 | 75.8 |
+| hoa · plasma | 75.9 | 60.8 | 75.4 | 76.7 |
+| thuy | 76.6 | 61.6 | 76.7 | 76.6 |
+| thuy · ocean | 77.2 | 60 | 86.6 | 75.5 |
+| thuy · mist | 80.3 | 66.6 | 76 | 78.7 |
+| moc | 76 | 60.1 | 76 | 76.1 |
+| moc · bamboo | 76 | 62.8 | 75 | 76.2 |
+| moc · forest | 76.4 | 60.9 | 88.6 | 76.6 |
+| kim | 75.1 | 60.1 | 75.2 | 75.4 |
+| kim · steel | 76.3 | 61.1 | 76 | 76.6 |
+| kim · titanium | 76.9 | 60.9 | 79.4 | 75.5 |