@cyberskill/design 1.0.0

package/components/overlays/Tour.jsx

@@ -0,0 +1,46 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+/** CyberSkill Tour — spotlight walkthrough over target elements (by CSS selector). Controlled via open/onClose. */
+export function Tour({ steps = [], open, onClose, lang, className }) {
+  const [i, setI] = React.useState(0);
+  const [rect, setRect] = React.useState(null);
+  const [ref, L] = useLang(lang);
+  const t = makeT("Tour", L);
+  React.useEffect(() => { if (open) setI(0); }, [open]);
+  React.useEffect(() => {
+    if (!open || !steps[i]) return;
+    const el = document.querySelector(steps[i].target);
+    if (el) {
+      const r = el.getBoundingClientRect();
+      setRect({ x: r.left - 6, y: r.top - 6, w: r.width + 12, h: r.height + 12 });
+    } else setRect(null);
+    const k = (e) => { if (e.key === "Escape") onClose && onClose(); };
+    document.addEventListener("keydown", k);
+    return () => document.removeEventListener("keydown", k);
+  }, [open, i, steps]);
+  if (!open || !steps.length) return <span ref={ref} style={{ display: "none" }} />;
+  const s = steps[i];
+  const last = i === steps.length - 1;
+  const popTop = rect ? Math.min(window.innerHeight - 170, rect.y + rect.h + 12) : 80;
+  const popLeft = rect ? Math.max(12, Math.min(window.innerWidth - 292, rect.x)) : 40;
+  return (
+    <div ref={ref} className={cx("cs-tour", className)}>
+      <div className="cs-tour__scrim" onClick={onClose} />
+      {rect ? <div className="cs-tour__hole" style={{ left: rect.x, top: rect.y, width: rect.w, height: rect.h }} /> : null}
+      <div className="cs-tour__pop" role="dialog" aria-label={typeof s.title === "string" ? s.title : undefined} style={{ left: popLeft, top: popTop }}>
+        <b>{s.title}</b>
+        {s.body ? <p>{s.body}</p> : null}
+        <div className="cs-tour__bar">
+          <span className="cs-tour__count">{(i + 1) + " / " + steps.length}</span>
+          <span className="cs-tour__btns">
+            <button type="button" className="cs-button cs-button--ghost cs-button--xs" onClick={onClose}>{t("skip")}</button>
+            {i > 0 ? <button type="button" className="cs-button cs-button--secondary cs-button--xs" onClick={() => setI(i - 1)}>{t("back")}</button> : null}
+            <button type="button" className="cs-button cs-button--primary cs-button--xs" onClick={() => (last ? onClose && onClose() : setI(i + 1))}>{last ? t("done") : t("next")}</button>
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}

package/components/overlays/Tour.prompt.md

@@ -0,0 +1,5 @@
+**Tour** — spotlight walkthrough over selectors (bilingual Skip/Back/Next/Done).
+
+```jsx
+<Tour open={on} onClose={()=>setOn(false)} steps={[{target:"#kpis",title:"Portfolio",body:"Filter by clicking a KPI."}]}/>
+```

package/components/overlays/overlays.card.html

@@ -0,0 +1,50 @@
+<!-- @dsCard group="Components" viewport="700x360" name="Overlays — Popover & Drawer" subtitle="Anchored popover + slide-in drawer" -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<link rel="stylesheet" href="../../styles.css" />
+<style>
+  body { margin: 0; background: var(--cs-color-surface-page); padding: 22px 24px; }
+  .lbl { font: 600 11px/1 var(--cs-font-family-ui); text-transform: uppercase; letter-spacing: .09em; color: var(--cs-color-text-muted); margin-bottom: 10px; }
+  .cols { display: grid; grid-template-columns: 1fr 1.2fr; gap: 24px; align-items: start; }
+  .frame { position: relative; overflow: hidden; height: 260px; border: 1px solid var(--cs-color-border-default); border-radius: var(--cs-radius-lg); background: var(--cs-color-surface-raised); }
+  .frame .cs-drawer-scrim, .frame .cs-drawer { position: absolute; animation: none; }
+</style>
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_ds_bundle.js"></script>
+</head>
+<body>
+<div id="root"></div>
+<script type="text/babel">
+const { Popover, Drawer, Button, RadioGroup, DescriptionList, Badge } = (window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]||{});
+const { useState } = React;
+function Demo() {
+  const [s, setS] = useState("active");
+  return (
+    <div className="cols">
+      <div>
+        <div className="lbl">Popover (open)</div>
+        <Popover open={true} onOpenChange={()=>{}} trigger={<Button variant="secondary" size="sm">Filter ▾</Button>}>
+          <RadioGroup legend="Status" value={s} onChange={setS} options={[{value:"active",label:"In progress"},{value:"done",label:"Shipped"},{value:"hold",label:"Blocked"}]} />
+        </Popover>
+      </div>
+      <div>
+        <div className="lbl">Drawer (contained preview)</div>
+        <div className="frame">
+          <Drawer open={true} onClose={()=>{}} title="Design System v1.6" actions={<Button size="sm">Open project</Button>}>
+            <Badge variant="ochre">In progress</Badge>
+            <p style={{color:"var(--cs-color-text-muted)",fontSize:13}}>Liquid Glass component bindings + 15 element packs.</p>
+            <DescriptionList items={[{term:"Owner",value:"An Le"},{term:"Squad",value:"Platform"},{term:"Progress",value:"72%"}]} />
+          </Drawer>
+        </div>
+      </div>
+    </div>
+  );
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Demo />);
+</script>
+</body>
+</html>

package/components/textfield/TextField.d.ts

@@ -0,0 +1,18 @@
+import type * as React from "react";
+import type { ReactNode } from "react";
+
+/**
+ * Labelled text input with optional helper description and inline error. Label
+ * is always programmatically associated; errors wire up via aria-describedby +
+ * role="alert". Preserves Vietnamese diacritics / IME composition.
+ */
+export interface TextFieldProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  /** Visible, associated label. Required. */
+  label: ReactNode;
+  /** Optional helper text under the label. */
+  description?: ReactNode;
+  /** Inline error message; also flips aria-invalid. */
+  error?: ReactNode;
+}
+
+export function TextField(props: TextFieldProps): React.ReactElement;

package/components/textfield/TextField.figma.tsx

@@ -0,0 +1,14 @@
+import figma from '@figma/code-connect'
+import { TextField } from './TextField.jsx'
+
+figma.connect(TextField, 'https://www.figma.com/design/CS_FIGMA_FILE_KEY/CyberSkill?node-id=9999-86', {
+  props: {
+    label: figma.string('Label'),
+    description: figma.string('Description'),
+    error: figma.string('Error'),
+    disabled: figma.boolean('Disabled'),
+    placeholder: figma.string('Placeholder'),
+  },
+  example: (props) => <TextField {...props} />,
+  imports: ["import { TextField } from '@cyberskill/design'"],
+})

package/components/textfield/TextField.jsx

@@ -0,0 +1,44 @@
+import React from "react";
+import { cx } from "../_utils/cx.js";
+
+/**
+ * CyberSkill TextField — label + input with optional description and error.
+ * Programmatic label association and aria-describedby wiring; IME-safe.
+ */
+export function TextField({
+  id,
+  label,
+  description,
+  error,
+  disabled = false,
+  readOnly = false,
+  className,
+  children, // never rendered on purpose: keeps stray children out of {...props} → void <input>
+  ...props
+}) {
+  const generatedId = React.useId();
+  const inputId = id ?? generatedId;
+  const descriptionId = description ? `${inputId}-description` : undefined;
+  const errorId = error ? `${inputId}-error` : undefined;
+  const describedBy = [descriptionId, errorId].filter(Boolean).join(" ") || undefined;
+
+  return (
+    <label
+      className={cx("cs-field", disabled && "is-disabled", error && "is-invalid", className)}
+      htmlFor={inputId}
+    >
+      <span className="cs-field__label">{label}</span>
+      {description ? <span id={descriptionId} className="cs-field__description">{description}</span> : null}
+      <input
+        {...props}
+        id={inputId}
+        disabled={disabled}
+        readOnly={readOnly}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={describedBy}
+        className="cs-field__control"
+      />
+      {error ? <span id={errorId} className="cs-field__error" role="alert">{error}</span> : null}
+    </label>
+  );
+}

package/components/textfield/TextField.prompt.md

@@ -0,0 +1,11 @@
+**TextField** — labelled text input with optional description and inline error. The label is always associated; errors announce via `role="alert"`. Vietnamese diacritics and IME composition are preserved.
+
+```jsx
+<TextField label="Work email" type="email" placeholder="you@company.com" />
+<TextField label="Tên của bạn" description="Vietnamese diacritics welcome" />
+<TextField label="Email" error="Enter a valid email address." defaultValue="nope" />
+```
+
+- **label** (required), **description** (helper), **error** (inline + `aria-invalid`).
+
+- Passes through all native `<input>` props (`type`, `placeholder`, `value`, `disabled`, `readOnly`, …).

package/components/textfield/textfield.card.html

@@ -0,0 +1,34 @@
+<!-- @dsCard group="Components" viewport="700x260" name="TextField" subtitle="Label, description, error — diacritic-safe" -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<link rel="stylesheet" href="../../styles.css" />
+<style>
+  body { margin: 0; background: var(--cs-color-surface-page); padding: 22px 24px; }
+  .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 18px 24px; max-width: 640px; }
+</style>
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+<script src="../../_ds_bundle.js"></script>
+</head>
+<body>
+<div id="root"></div>
+<script type="text/babel">
+const { TextField } = (window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]||{});
+function Demo() {
+  return (
+    <div className="grid">
+      <TextField label="Work email" type="email" placeholder="you@company.com" />
+      <TextField label="Tên của bạn" description="Vietnamese diacritics preserved" defaultValue="Nguyễn Hoàng Vũ" />
+      <TextField label="Company" placeholder="Optional" />
+      <TextField label="Email" error="Enter a valid email address." defaultValue="not-an-email" />
+    </div>
+  );
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Demo />);
+</script>
+</body>
+</html>

package/docs/ci-cd.md

@@ -0,0 +1,84 @@
+# CI/CD — automating the gate board
+
+**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)
+
+## 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` (8 plain-Node contract tests; wired into CI by the Jul 2026 hardening — previously local-only).
+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).
+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. Owner decision A (non-Enterprise): Variables REST soft-skips; secrets still prove file open. See `docs/figma.md`.
+8. **`code-connect`** — on PR + `main` + manual. Decision 1C: dry-run always (config + 99 mappings); publish soft-skips when `FIGMA_TOKEN` / `FIGMA_FILE_KEY` missing or API 403/404/429. See `docs/figma.md`.
+9. **`regenerate-tokens`** — path-filtered on push/PR (`tokens.dtcg.json`, natives, generator, `VERSION`); always available on schedule/manual. Deterministic native output; pushes with `contents: write` (or `DS_PUSH_TOKEN`).
+
+Separate workflow **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + `v*` tags; pack dry-run always; publish soft-skips without `NPM_TOKEN`. Version stays **1.0.0**; license **UNLICENSED**.
+
+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`.
+
+Node **22** on runners (avoids Node 20 action deprecation). Playwright browser cache key: `package-lock.json`.
+
+## Runner install pattern (Playwright jobs)
+
+```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
+```
+
+## Token auto-commit permissions
+
+Job requests `permissions: contents: write`. 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.
+
+## Branch protection (recommended)
+
+Require status checks on `main` before merge:
+
+- `fast-gates`
+- `docs-consistency-blocker`
+
+Optional: `whole-set-audits` (long). Configure under repo **Settings → Branches** or via `gh api` (admin).
+
+## Running locally
+
+```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
+```
+
+## What this does NOT auto-fail (by design)
+
+- **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 write on non-Enterprise** — soft-skip with report artifact.
+- **Code Connect publish** — soft-skip when secrets missing or API 403/404/429 (Decision 1C).
+- **npm publish** — soft-skip when `NPM_TOKEN` absent (Decision 1C).
+- **Native store signed release** — soft-skip when `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` absent (Decision 1C); store submit stays disabled.
+
+## Soft-skip dry-runs (local)
+
+```bash
+npm run code-connect:dry-run          # config + ≥99 mappings; no secrets
+node _audit/ci/code-connect-publish.mjs   # without secrets → SOFT SKIP missing_secrets
+npm run npm:pack-dry-run              # tarball inventory; no NPM_TOKEN
+node _audit/ci/npm-publish.mjs        # without NPM_TOKEN → SOFT SKIP missing_secrets
+npm run native:store-dry-run          # Fastlane scaffolds + metadata; no ASC_*/Play JSON
+node _audit/ci/native-store-dry-run.mjs   # without secrets → SOFT SKIP missing_secrets
+```

package/docs/consuming.md

@@ -0,0 +1,109 @@
+# 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.
+
+**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
+
+| Consumer | Start here | Works today | Do not |
+|---|---|---|---|
+| **Claude Code** | `SKILL.md` → `README.md` → `styles.css` + `_esm/cs.mjs` / `_ds_bundle.js` (prefix resolve) | Strong — rules, components, prompts; gates via full clone | Hardcode the bundle suffix; treat Storybook host as the portable contract |
+| **Google Stitch** | `DESIGN.md` → `llms.txt` → `tokens/tokens.dtcg.json` | Strong for doctrine + tokens + static `.cs-*` HTML | Treat `templates/**/*.dc.html` as SoT — no tweaks / `__dcSetProps` / DC compiler |
+| **Claude Design** | Full repo + DC compiler | Full fidelity (tweaks, `x-import`, bilingual templates) | Skip the sync loop in `docs/sync.md` |
+| **npm** | `@cyberskill/design` | Org + `NPM_TOKEN` ready; dry-run always | Assume registry install is live before first **npm-publish** run + written consumer grant |
+
+**Stitch DC rule:** Stitch (and any non-DC tool) must **not** consume `*.dc.html` as source of truth. Use static export patterns, `templates/kitchen-sink.html`, `examples/static-hello/`, and `.cs-*` classes from `styles.css`.
+
+**Release signal:** VERSION stays pinned at **1.0.0** (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)
+
+**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/cs.mjs` (ESM entry re-exporting every component) · `_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).
+
+**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.
+
+**Rules that keep transfer lossless:**
+- Never hardcode the bundle namespace suffix (see "Resolve by prefix" below — gate-enforced).
+
+- Never recreate/recolour the logo — use `assets/logo-mark.svg` / the `Logo` component.
+
+- Every UI string ships EN + VN via the registry; don't inline one-language strings in components.
+
+- 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/`).
+
+## Adopt via npm (optional)
+
+The package is publishable (`private: false`, version pinned **1.0.0**). License remains **UNLICENSED** — installing from the registry (or a packed tarball) does **not** grant redistribution rights by itself. Until the owner chooses an open license, **consumers need an explicit grant** from CyberSkill to use the package in a product. The `@cyberskill` org and repo `NPM_TOKEN` are operator-ready; run **Actions → npm-publish** once so `@cyberskill/design` is on the registry. Without `NPM_TOKEN` the workflow **soft-skips** (exit 0 + report) — that is honesty, not a successful registry release. See `docs/decisions.md` and `docs/quality-gates.md`.
+
+**Consumer grant (owner policy — not a secret).** For each approved team, record something like: *CyberSkill grants [Team/Org] a non-exclusive right to use `@cyberskill/design` in [named products]. The package remains UNLICENSED; redistribution outside those products needs a further written grant.* Keep grant text internal unless you want it public.
+
+```bash
+# after a successful npm-publish workflow run (or from a packed tarball)
+npm install @cyberskill/design@1.0.0
+```
+
+Then link styles and import from the package entry (`_esm/cs.mjs` via `exports["."]`), or continue using 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[]`.
+
+**Publish path (maintainers):** `prepublishOnly` runs `build:bundle` + `build:design-md --check`. Workflow `.github/workflows/npm-publish.yml` on `workflow_dispatch` / `v*` tags; publish requires `NPM_TOKEN` (`node _audit/ci/npm-publish.mjs --dry-run` always lists the tarball). See `docs/ci-cd.md` and `docs/decisions.md`.
+
+## Adopt (two paths, plus a module shortcut)
+
+**1. Static / prototypes / mocks — link the stylesheet.** Copy `styles.css` (+ the `tokens/`, `base/`, `fonts/` it `@import`s, or serve the whole tree) and link it; you now have every `--cs-*` token, the `.cs-*` component classes, and the Liquid Glass surfaces. Compose with the classes (see `templates/kitchen-sink.html`). Copy any asset you reference from `assets/`.
+
+**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**:
+```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>
+```
+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. ESM (module) path — one import, no build.** `import { Button, TextField } from "<path>/_esm/cs.mjs"` — the module self-ensures React (pinned; 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.
+
+**Templates.** Each `templates/<slug>/` is a Design Component seeded from `ds-base.js` (one `base` line to rebind the path to wherever this system lives relative to the consuming page). Copy the folder and edit copy/tweaks.
+
+**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`.
+
+## The three axes
+
+State Theme (`data-theme`), Element (`data-cs-element` + `data-cs-variant`), and Language (`lang` / template Language tweak) on a container; everything inside re-skins with no code change (see `templates/playground.html`). Defaults: `light · tho · en`. Surface treatment is liquid-glass (fixed). Bilingual: components resolve strings from `lang` (`lang="vi"` on any container → full Vietnamese).
+
+## Upgrading
+
+- **Version is pinned.** `VERSION` and `package.json` stay at **1.0.0**. There is no design-system changelog file — treat the **git tip SHA** as the technical truth, and read curated **Release Notes** (Storybook + `docs/release-notes.md`) for product-facing highlights.
+
+- Anchors (Umber/Ochre), the `.cs-*` class names, and the `--cs-*` token names are stable contracts — safe to depend on. Breaking renames of those contracts should be rare and called out in the PR/docs when they happen.
+
+- **Re-run the smoke test after upgrading.** Open `_audit/consumer-smoke-test.html` and the full Health board (`_audit/run.html`) against the new tip — the runner proves the packaged path still resolves.
+
+## Host Storybook (optional)
+
+The live site serves Storybook at `/` as the **product surface** for operators (Theme × Element × Language + control matrices). That is **host-only tooling** — do not depend on Storybook in product apps. Portable Atomic View remains at `guidelines/atomic-view.html`. See `docs/storybook.md` and `docs/live-hub.md`.
+
+## Five-minute consumer spike
+
+```bash
+# from monorepo root
+python3 -m http.server 8765 --bind 127.0.0.1
+# open http://127.0.0.1:8765/examples/static-hello/
+# then http://127.0.0.1:8765/_audit/consumer-smoke-test.html
+```
+
+Edit `examples/static-hello/index.html`: flip `data-theme="dark"` or `data-cs-element="thuy"` on `<body>`. No install, no Storybook.
+
+## Native sample hosts (optional)
+
+Multi-screen samples (Sign in · Home · Settings) live under `examples/native/swiftui`, `compose`, and `flutter`. They sync generated tokens via `node examples/native/sync-tokens.mjs`. See `examples/native/README.md`. Not required for web consumers.
+
+## Extending
+
+If you're changing the system itself (not just consuming it), follow `CONTRIBUTING.md` — the Expansion Rule (propagate to every deliverable in one change) and the verification doctrine (deep checks via `_audit/`).

package/docs/contrast-report.md

@@ -0,0 +1,125 @@
+# Contrast report — elemental pairings (APCA)
+
+Generated 2026-07-22 · sweep at VERSION 1.0.0 pin.
+
+**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.)
+
+Token nudges applied for v2.0: bright lightened for clay, hoa, lava, plasma, thủy, ocean, forest, titanium; `-on` flipped dark for lava, ocean, forest, titanium.
+| Scope | Pairing | fg / bg | Lc | Verdict |
+|---|---|---|---|---|
+| 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 | ✓ |
+
+**Failures: 0.** All text pairings pass Lc ≥ 60.
+
+## Dark-theme semantic colours (WCAG, added v2.8.0)
+
+The light-theme semantic foregrounds failed on dark surfaces (~2.5:1), so the dark theme overrides them. WCAG contrast on the dark panel `#221710` (and as a fill paired with dark ink `#1a1108`):
+| Role | Dark value | on panel | as fill w/ ink | Verdict |
+|---|---|---|---|---|
+| 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 also remaps the primary button to Ochre (`#f4ba17` on `#1a1108`) and warms the field border — so no dark control is low-contrast. Dark shadows are umber-tinted (weak on dark by nature); the dark hairline border provides panel separation instead.
+This file is generated — re-run the APCA sweep script after any token change.
+
+## Dark elemental packs — APCA verification (v4.0.0, Jul 2026)
+
+Generated with the owner-approved dark packs applied; measured by the same SAPC-4g implementation as `_audit/apca-dark-preview.html` (also the regression gate). Targets: bright ≥ 75 · accent ≥ 60 · button ink ≥ 75 · ink-on-tint ≥ 75 — **15/15 packs 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 |