@cyberskill/design 1.0.0 → 1.1.1

package/components/overlays/AlertDialog.jsx

@@ -0,0 +1,142 @@
+import React from "react";
+import { makeT, useLang } from "../_i18n/i18n.js";
+import { cx } from "../_utils/cx.js";
+
+const FOCUSABLE = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'audio[controls]',
+  'video[controls]',
+  'summary',
+  'iframe',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+/**
+ * CyberSkill AlertDialog — first-class destructive/confirm modal (role=alertdialog).
+ * Distinct from Popconfirm (inline bubble) and Dialog (general modal). Focus trap +
+ * restore; bilingual confirm/cancel via the registry.
+ */
+export function AlertDialog({
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  title,
+  description,
+  children,
+  confirmLabel,
+  cancelLabel,
+  tone,
+  variant,
+  onConfirm,
+  onCancel,
+  lang,
+  className,
+  ...props
+}) {
+  const baseId = React.useId();
+  const titleId = baseId + "-title";
+  const descId = baseId + "-desc";
+  const [ref, L] = useLang(lang);
+  const t = makeT("AlertDialog", L);
+  const panel = React.useRef(null);
+  const uncontrolled = open === undefined;
+  const [internal, setInternal] = React.useState(!!defaultOpen);
+  const isOpen = uncontrolled ? internal : !!open;
+  const setOpen = (next) => {
+    if (uncontrolled) setInternal(next);
+    onOpenChange?.(next);
+  };
+  const destructive = (tone ?? variant) === "destructive";
+  const confirmRef = React.useRef(onConfirm); confirmRef.current = onConfirm;
+  const cancelRef = React.useRef(onCancel); cancelRef.current = onCancel;
+
+  React.useEffect(() => {
+    if (!isOpen) return;
+    const prev = document.activeElement;
+    const prevOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    const focusables = () => (panel.current ? [...panel.current.querySelectorAll(FOCUSABLE)] : []);
+    // Prefer the confirm action for destructive prompts (WAI-ARIA alertdialog).
+    const preferred = panel.current?.querySelector(".cs-alert-dialog__confirm") || focusables()[0];
+    (preferred || panel.current)?.focus?.();
+    const k = (e) => {
+      if (e.key === "Escape") {
+        setOpen(false);
+        cancelRef.current?.();
+        return;
+      }
+      if (e.key !== "Tab" || !panel.current) return;
+      const f = focusables();
+      if (!f.length) { e.preventDefault(); panel.current.focus(); return; }
+      const a = f[0], z = f[f.length - 1];
+      const active = document.activeElement;
+      const inside = panel.current.contains(active);
+      if (e.shiftKey && (!inside || active === a)) { e.preventDefault(); z.focus(); }
+      else if (!e.shiftKey && (!inside || active === z)) { e.preventDefault(); a.focus(); }
+    };
+    document.addEventListener("keydown", k);
+    return () => {
+      document.removeEventListener("keydown", k);
+      document.body.style.overflow = prevOverflow;
+      if (prev && prev.focus) prev.focus();
+    };
+  }, [isOpen]);
+
+  const cl = cancelLabel != null ? cancelLabel : t("cancel");
+  const cf = confirmLabel != null ? confirmLabel : t("confirm");
+  const body = description ?? children;
+  const hasDesc = body != null && body !== false && body !== "";
+
+  if (!isOpen) return null;
+  return (
+    <div ref={ref} className="cs-dialog-layer cs-alert-dialog-layer">
+      <div
+        className="cs-dialog__overlay"
+        onClick={() => { setOpen(false); cancelRef.current?.(); }}
+        aria-hidden="true"
+      />
+      <section
+        {...props}
+        ref={panel}
+        tabIndex={-1}
+        role="alertdialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        aria-describedby={hasDesc ? descId : undefined}
+        className={cx("cs-dialog", "cs-alert-dialog", destructive && "cs-alert-dialog--destructive", className)}
+      >
+        <header className="cs-dialog__header">
+          <h2 id={titleId} className="cs-dialog__title">{title}</h2>
+        </header>
+        {hasDesc ? <div id={descId} className="cs-dialog__body">{body}</div> : null}
+        <footer className="cs-dialog__actions">
+          <button
+            type="button"
+            className="cs-button cs-button--ghost cs-button--md"
+            onClick={() => { setOpen(false); cancelRef.current?.(); }}
+          >
+            {cl}
+          </button>
+          <button
+            type="button"
+            className={cx(
+              "cs-button",
+              "cs-button--md",
+              "cs-alert-dialog__confirm",
+              destructive ? "cs-button--danger" : "cs-button--primary"
+            )}
+            onClick={() => { setOpen(false); confirmRef.current?.(); }}
+          >
+            {cf}
+          </button>
+        </footer>
+      </section>
+    </div>
+  );
+}

package/components/overlays/AlertDialog.prompt.md

@@ -0,0 +1,12 @@
+**AlertDialog** — first-class confirm / destructive modal (`role="alertdialog"`). Distinct from Popconfirm (inline bubble) and Dialog (general modal). Bilingual Confirm/Cancel via the registry.
+
+```jsx
+<AlertDialog
+  open={open}
+  onOpenChange={setOpen}
+  title="Delete workspace?"
+  description="Removes every project. This cannot be undone."
+  tone="destructive"
+  onConfirm={wipe}
+/>
+```

package/components/overlays/Drawer.jsx

@@ -36,7 +36,7 @@ export function Drawer({ open, onClose, title, side = "right", children, actions
             <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round"><path d="M6 6l12 12M18 6L6 18" /></svg>
           </button>
         </div>
-        <div className="cs-drawer__body">{children}</div>
+        <div className="cs-drawer__body" tabIndex={0}>{children}</div>
         {actions ? <div className="cs-drawer__footer">{actions}</div> : null}
       </aside>
     </>

package/components/overlays/Popconfirm.jsx

@@ -16,9 +16,22 @@ export function Popconfirm({ trigger, title, onConfirm, onCancel, okLabel, cance
     document.addEventListener("keydown", k);
     return () => { document.removeEventListener("mousedown", d); document.removeEventListener("keydown", k); };
   }, [open]);
+  const toggle = () => setOpen((o) => !o);
+  // ARIA attrs must live on the interactive trigger (button), not a wrapping <span>
+  // — axe aria-allowed-attr flags aria-haspopup/aria-expanded on generic elements.
+  const triggerNode = React.isValidElement(trigger)
+    ? React.cloneElement(trigger, {
+        "aria-haspopup": "dialog",
+        "aria-expanded": open,
+        onClick: (e) => {
+          if (typeof trigger.props.onClick === "function") trigger.props.onClick(e);
+          if (!e.defaultPrevented) toggle();
+        },
+      })
+    : <button type="button" aria-haspopup="dialog" aria-expanded={open} onClick={toggle}>{trigger}</button>;
   return (
     <span ref={(el) => { wrap.current = el; ref.current = el; }} className={cx("cs-popconfirm", className)}>
-      <span onClick={() => setOpen((o) => !o)} aria-haspopup="dialog" aria-expanded={open}>{trigger}</span>
+      {triggerNode}
       {open ? (
         <span className="cs-popconfirm__panel" role="alertdialog" aria-label={typeof title === "string" ? title : undefined}>
           <span className="cs-popconfirm__title">{title}</span>

package/components/overlays/Popover.jsx

@@ -15,9 +15,22 @@ export function Popover({ trigger, children, align = "start", open: controlled,
     document.addEventListener("keydown", k);
     return () => { document.removeEventListener("mousedown", d); document.removeEventListener("keydown", k); };
   }, [open]);
+  const toggle = () => set(!open);
+  // ARIA attrs must live on the interactive trigger (button), not a wrapping <span>
+  // — axe aria-allowed-attr flags aria-haspopup/aria-expanded on generic elements.
+  const triggerNode = React.isValidElement(trigger)
+    ? React.cloneElement(trigger, {
+        "aria-haspopup": "dialog",
+        "aria-expanded": open,
+        onClick: (e) => {
+          if (typeof trigger.props.onClick === "function") trigger.props.onClick(e);
+          if (!e.defaultPrevented) toggle();
+        },
+      })
+    : <button type="button" aria-haspopup="dialog" aria-expanded={open} onClick={toggle}>{trigger}</button>;
   return (
     <span className={cx("cs-popover", className)} ref={ref}>
-      <span onClick={() => set(!open)} aria-haspopup="dialog" aria-expanded={open}>{trigger}</span>
+      {triggerNode}
       {open ? <div className={cx("cs-popover__panel", align === "end" && "cs-popover__panel--end")} role="dialog">{children}</div> : null}
     </span>
   );

package/components/overlays/alertdialog.card.html

@@ -0,0 +1,42 @@
+<!-- @dsCard group="Components" viewport="700x320" name="AlertDialog" subtitle="Confirm / destructive modal (alertdialog)" -->
+<!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; }
+  .frame { position: relative; height: 256px; border: 1px solid var(--cs-color-border-default); border-radius: var(--cs-radius-lg); overflow: hidden; background: var(--cs-color-surface-raised); }
+  .frame .cs-dialog-layer { position: absolute; }
+  .frame .cs-dialog { top: 28px; }
+</style>
+<script src="https://unpkg.com/umd-react@19.2.8/dist/react.development.js" integrity="sha384-r22tQd8qRIHDPIkmdXZcVtvPi1Tj2x1QaW2tmFQHEvHscATUnHQ5siTyxWw5PMUs" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/umd-react@19.2.8/dist/react-dom.development.js" integrity="sha384-gJZYmumEmwqVmX3JVsLZq+4QrxoPGh/BW47Rk7SqNPCPFpTGnRtvmeRPJ7//ZDPk" 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 { AlertDialog, Button } = (window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]||{});
+function Demo() {
+  const [open, setOpen] = React.useState(true);
+  return (
+    <div className="frame">
+      {!open && <div style={{padding:24}}><Button variant="danger-ghost" onClick={() => setOpen(true)}>Delete workspace</Button></div>}
+      <AlertDialog
+        open={open}
+        onOpenChange={setOpen}
+        title="Delete workspace?"
+        description="Removes every project and release. This cannot be undone."
+        tone="destructive"
+        onConfirm={() => setOpen(false)}
+      />
+    </div>
+  );
+}
+ReactDOM.createRoot(document.getElementById("root")).render(<Demo />);
+</script>
+</body>
+</html>

package/components/overlays/overlays.card.html

@@ -11,8 +11,8 @@
   .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/umd-react@19.2.8/dist/react.development.js" integrity="sha384-r22tQd8qRIHDPIkmdXZcVtvPi1Tj2x1QaW2tmFQHEvHscATUnHQ5siTyxWw5PMUs" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/umd-react@19.2.8/dist/react-dom.development.js" integrity="sha384-gJZYmumEmwqVmX3JVsLZq+4QrxoPGh/BW47Rk7SqNPCPFpTGnRtvmeRPJ7//ZDPk" 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>

package/components/textfield/textfield.card.html

@@ -9,8 +9,8 @@
   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/umd-react@19.2.8/dist/react.development.js" integrity="sha384-r22tQd8qRIHDPIkmdXZcVtvPi1Tj2x1QaW2tmFQHEvHscATUnHQ5siTyxWw5PMUs" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/umd-react@19.2.8/dist/react-dom.development.js" integrity="sha384-gJZYmumEmwqVmX3JVsLZq+4QrxoPGh/BW47Rk7SqNPCPFpTGnRtvmeRPJ7//ZDPk" 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>

package/docs/benchmark-rubric.md

@@ -0,0 +1,46 @@
+# Design System Benchmark Rubric
+
+Self-audit checklist for evolving CyberSkill Design System — external standards plus CDS-owned rules. Pair with [`docs/quality-gates.md`](quality-gates.md) (deterministic gates) and [`docs/design-styles.md`](design-styles.md) (Element colour contract).
+
+## External standards
+
+| Domain | Standard / practice | How we measure |
+|---|---|---|
+| Legal a11y floor | WCAG 2.2 AA contrast (4.5:1 normal / 3:1 large / UI non-text ≥ 3:1) | `contrast-guard`, theme-overflow, axe-smoke |
+| Perceptual readability | APCA Bronze-style Lc bands (body ≥ 75, UI labels ≥ 60, large ≥ 45, non-text ≥ 15; dark max ~90) | `apca-dark-preview`, [`docs/contrast-report.md`](contrast-report.md) |
+| Color space | OKLCH luminance-first ramps; hue preserved across modes | `element-geometry` + `npm run tokens:elements` |
+| Token architecture | W3C DTCG 2025.10 — primitive → semantic → component; typed leaves; multi-dimensional modifiers (theme × element) | `dtcg-typing`, token-format-parity, token-pipeline |
+| Dual-mode theming | Same hue family light↔dark; role remap (not invert-everything) | `element-geometry` hue-lock |
+| Dual-standard audit | Classify pairs: pass-both / fail-both / WCAG-only / APCA-only | Document in contrast-report workflow after token changes |
+| Gamut safety | Prefer sRGB-safe chroma; clamp before emit | Generator + geometry gate |
+
+## CDS-owned rules
+
+| Rule | Enforcement |
+|---|---|
+| Axes = Theme × Element × Language × Style until a Style Expansion Rule pass | `axis-guard` (retired Expression/Density); doctrine in design-styles |
+| Text never on mid `-accent`; Ochre focus ring never remapped; status colours never remapped | `elements.css` contract · contrast-report · conventions |
+| One element per surface; Tương sinh gradients only | products registry · conventions |
+| Product→element registry locked; UI kits Thổ-faithful | [`docs/products.md`](products.md) |
+| Expansion Rule completeness + `_audit/run.html` green + docs EN·VI parity | CLAUDE.md · docs-consistency · docs-lang-parity |
+| VERSION **1.1.1** post-LAUNCH | version-stamp · docs-consistency |
+| Element packs from seeds only (30 sets) | `element-geometry` · `tokens:elements` |
+
+## Style expansion checklist (`data-cs-style`)
+
+Sole pack today: **liquid-glass** (`tokens/styles.css`, gate `_audit/style-contract.html`). When adding a style pack beyond liquid-glass:
+
+1. Token overlay that **consumes** the existing 9 `--cs-accent-*` roles (do not invent parallel Element packs).
+2. Specimen card + Storybook / Atomic View wiring if the style is product-selectable.
+3. Template / kit adoption only where the style is intentional — UI kits stay Thổ-faithful unless a decision says otherwise.
+4. Regenerate contrast surfaces if the style remaps backgrounds that host text.
+5. Expansion Rule grep for the new enum across templates, docs EN+VI, gates.
+6. Extend the style-contract allowlist; keep `_audit/run.html` green.
+7. Record the decision in [`docs/decisions.md`](decisions.md) (+ VI).
+
+## How to run a benchmark pass
+
+1. `npm run tokens:elements` (if seeds changed) → native regen → `node scripts/generate-contrast-report.mjs`
+2. Fast board: open `_audit/run.html` (or CI `fast-gates`) — all hard gates green, including **Element geometry**
+3. Whole-set Atomic View / Elements Geometry: all **30** sets (soft/middle/deep × light/dark × five elements) — soft reads as a washed pastel, middle intensity syncs across elements, deep is clearly darker, roles feel harmonious, and light↔dark keeps hue identity. Geometry gate requires **both** `minDeltaE` and `minDeltaL` (plus monotonic L) from `tokens/element-seeds.json`
+4. Update this rubric only when standards or CDS doctrine change — keep EN·VI parity

package/docs/ci-cd.md

@@ -12,15 +12,16 @@
 
 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).
+3. **`unit-tests`** — `npm run test:unit` (11 plain-Node contract tests; wired into CI by the Jul 2026 hardening — previously local-only). Includes `test-element-packs` (`node scripts/generate-element-packs.mjs --check` freshness).
 4. **`node-prechecks`** — browser-free Node authorities: `_audit/ci/check-bundle-freshness.mjs` (the bundle-freshness source of truth — full source discovery incl. new/deleted files; the board row only re-hashes header-recorded files) and `scripts/generate-design-md.mjs --check` (root `DESIGN.md` byte-equals regeneration).
 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`).
+7. **`figma-variables-push`** — on `main` push + manual. **Empty `FIGMA_TOKEN` / `FIGMA_FILE_KEY` soft-skip** (exit 0 + report — same honesty as Code Connect). Owner decision A (non-Enterprise): Variables REST also **soft-skips on API 403** (and related plan/scope failures) after secrets prove file open. Soft-skip ≠ live Variables sync. See `docs/figma.md`.
+8. **`code-connect`** — on PR + `main` + manual. Decision 1C: dry-run always (config + 105 mappings); publish soft-skips when `FIGMA_TOKEN` / `FIGMA_FILE_KEY` missing or API 403/404/429. See `docs/figma.md`.
+9. **`regenerate-tokens`** (pull requests) + **`regenerate-tokens-push`** (push to `main` / schedule / manual) — path filter covers element seeds/packs (`element-seeds.json`, `elements.css`, JSON/JS/DTCG mirrors, `generate-element-packs.mjs`) plus natives / `VERSION`. Regeneration runs `npm run tokens:elements` then `node _audit/ci/generate-native-tokens.mjs`. On a **pull request** the job runs with `contents: read`, never pushes, and **exits 1** on drift: run both locally and commit. Only the push/schedule/manual twin holds `contents: write` and auto-commits with `DS_PUSH_TOKEN` (or `github.token`).
+10. **`npm-hello-smoke`** — registry consumer proof: `cd examples/npm-hello && npm ci && npm run smoke` (**hard fail**; package is public). Path-filtered on push/PR when `examples/npm-hello/**`, package publish surface, or this workflow changes; always on schedule / `workflow_dispatch`.
 
-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 **`npm-publish`** (`.github/workflows/npm-publish.yml`): `workflow_dispatch` + `v*` tags; pack dry-run always; publish via **npm Trusted Publishing (OIDC)** (`id-token: write`, no `NPM_TOKEN` on the publish step). Soft-skips on auth / 403 / 404 / EOTP / version conflict. version is **1.1.1**; license **UNLICENSED**. Trusted Publisher on npmjs must match workflow filename `npm-publish.yml`. Package Publishing access is **Require 2FA and disallow tokens** (OIDC still works; classic tokens rejected).
 
 Separate workflow **`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`.
 
@@ -39,7 +40,7 @@ Node **22** on runners (avoids Node 20 action deprecation). Playwright browser c
 
 ## 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.
+Only `regenerate-tokens-push` requests `permissions: contents: write`; the pull-request twin `regenerate-tokens` stays on `contents: read` and checks out without persisted credentials, so a PR can never trigger a bot push. If org locks the default token to read-only, set repository secret `DS_PUSH_TOKEN` (fine-grained PAT, Contents read/write) or unlock write at org Actions settings. See earlier notes in git history / org settings.
 
 ## Branch protection (recommended)
 
@@ -61,24 +62,29 @@ 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
+npm run tokens:elements
+node scripts/generate-element-packs.mjs --check
 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.
+- **Figma Variables** — soft-skip when secrets missing (same honesty as Code Connect) or Variables write hits non-Enterprise / API **403**; report artifact records the skip. Soft-skip ≠ live sync.
 - **Code Connect publish** — soft-skip when secrets missing or API 403/404/429 (Decision 1C).
-- **npm publish** — soft-skip when `NPM_TOKEN` absent (Decision 1C).
+- **npm publish** — Trusted Publishing (OIDC) on `npm-publish.yml`; soft-skip on auth / conflict (Decision 1C).
 - **Native store signed release** — soft-skip when `ASC_*` / `PLAY_SERVICE_ACCOUNT_JSON` absent (Decision 1C); store submit stays disabled.
+- **npm-hello registry smoke** — **hard fail** (`examples/npm-hello` → `npm ci` + `npm run smoke`); proves the public `@cyberskill/design` install path (not soft-skip).
+
+A green `figma-variables-push` or `code-connect` job — and therefore a green badge or Status row — only means the job exited 0; it does **not** prove a live Figma sync, because a soft-skip and a real publish look identical from outside. Open the run's report artifact (`figma-push-report.json` / `code-connect-report.json`) to see which one happened.
 
 ## Soft-skip dry-runs (local)
 
 ```bash
-npm run code-connect:dry-run          # config + ≥99 mappings; no secrets
+npm run code-connect:dry-run          # config + ≥105 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 npm:pack-dry-run              # tarball inventory; no auth
+node _audit/ci/npm-publish.mjs        # GHA OIDC; else SOFT SKIP (tokens disallowed on package)
 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/consumer-grant.md

@@ -0,0 +1,37 @@
+# Consumer grant — `@cyberskill/design`
+
+**Status: in force** (Jul 2026). Policy text — not a secret. License on the package remains **UNLICENSED**; this grant is the approval layer for use in named products.
+
+## Grant
+
+CyberSkill grants **CyberSkill** (the company and its product engineering teams under `cyberskill-official`) a **non-exclusive** right to install and use **`@cyberskill/design`** in the products listed in the locked registry `docs/products.md`:
+
+| Product |
+|---|
+| Lumi — wish assistant |
+| Status Hub — client portfolio portal |
+| CyberOS Agent Spine — agent infra, memory, gates |
+| CyberSkill Design System — this library |
+| cyberskill.world — the studio site |
+| Client delivery suite — kickoff · QBR · runbooks |
+| Board / investor collateral |
+| HR / employment instruments |
+
+The package remains **UNLICENSED**. Installing from the npm registry does **not** by itself grant redistribution rights. Redistribution outside the products above — including publishing a fork, re-licensing, or shipping the package as a dependency of an unrelated third-party product — needs a **further written grant** recorded in this file (or a superseding instrument).
+
+## Scope notes
+
+- **Clone / subtree / static link** of this repo for the same products is covered the same way as an npm install.
+- **Host-only tooling** (Storybook, `_audit/`) is not part of the npm tarball and is not redistributable under this grant.
+- Adding a new CyberSkill product: update `docs/products.md` (+ VI) via a maintainer decision, then add the product row here in the same change.
+- Approving an **external** team or client: append a dated grant stanza below (team/org, named products, contact). Do not invent product → element mappings here — that stays in `docs/products.md`.
+
+## Additional grantees
+
+*(None yet. Append dated entries here.)*
+
+## Related
+
+- Adopt / install: `docs/consuming.md`
+- Decision record: `docs/decisions.md` §7
+- Product → element registry: `docs/products.md`

package/docs/consuming.md

@@ -8,18 +8,18 @@ How any project — human-driven or agent-driven — adopts this HTML-first desi
 
 | 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 |
+| **Claude Code** | `SKILL.md` → `README.md` → `styles.css` + bundler `@cyberskill/design` / legacy `_esm/cs.mjs` / `_ds_bundle.js` (prefix resolve) | Strong — rules, components, prompts; gates via full clone | Hardcode the bundle suffix; treat Storybook host as the portable contract; import `_esm/cs.mjs` or `@cyberskill/design/legacy` into Next/SSR bundlers |
 | **Google Stitch** | `DESIGN.md` → `llms.txt` → `tokens/tokens.dtcg.json` | Strong for doctrine + tokens + static `.cs-*` HTML | Treat `templates/**/*.dc.html` as SoT — no tweaks / `__dcSetProps` / DC compiler |
 | **Claude Design** | Full repo + DC compiler | Full fidelity (tweaks, `x-import`, bilingual templates) | Skip the sync loop in `docs/sync.md` |
-| **npm** | `@cyberskill/design` | Org + `NPM_TOKEN` ready; dry-run always | Assume registry install is live before first **npm-publish** run + written consumer grant |
+| **npm** | `@cyberskill/design` | **1.1.1** on registry; CI Trusted Publishing; grant in `docs/consumer-grant.md` | Treat registry install as a public license (still UNLICENSED) |
 
 **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`.
+**Release signal:** version is LAUNCHED at **1.1.0**; current pin **1.1.1** (no CHANGELOG). Treat the **git tip SHA** as technical truth; read curated product highlights in `docs/release-notes.md`.
 
 ## 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`.
+**What you get:** `styles.css` (400+ tokens + `.cs-*` classes + Liquid Glass surfaces, `@import`s `tokens/` + `base/`) · `_ds_bundle.js` (compiled React components, no build step) · `_esm/react.mjs` (bundler-native React entry — React as peerDependency; default `exports["."]`) · `_esm/cs.mjs` (browser / no-build legacy via `exports["./legacy"]`) · `_ds_manifest.json` (machine-readable inventory) · per-component `Name.d.ts` (API) + `Name.prompt.md` (usage brief) · `tokens/tokens.dtcg.json` (W3C DTCG) + `tokens.json`/`tokens.js`.
 
 **Repo checkout** — clone or copy the whole tree; everything is relative-path static. Entry points: Storybook on the host site (`/` / `npm run storybook`) · `guidelines/atomic-view.html` (every component live, portable) · `templates/<slug>/` (copyable starting points — DC for Claude Design; kitchen-sink / `.cs-*` for Stitch). Read `SKILL.md` before authoring anything on-brand; Stitch readers start at `DESIGN.md`. Deeper maps live in `llms.txt` (inventory) and this file (full adoption + upgrade guide below).
 
@@ -38,18 +38,29 @@ How any project — human-driven or agent-driven — adopts this HTML-first desi
 
 ## 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`.
+The package is publishable (`private: false`, version **1.1.1**). License remains **UNLICENSED** — installing from the registry does **not** grant redistribution rights by itself. **LAUNCH was `@cyberskill/design@1.1.0`; current pin is `@cyberskill/design@1.1.1` (publish via tag `v1.1.1`).** CI republishes via **npm Trusted Publishing (OIDC)** on workflow `npm-publish.yml` (no long-lived publish token; package Publishing access **disallows tokens**). Approved use is recorded in **`docs/consumer-grant.md`** (CyberSkill portfolio products from `docs/products.md`). See `docs/decisions.md` and `docs/ci-cd.md`.
 
-**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.
+**Consumer grant (owner policy — not a secret).** Written and in force at `docs/consumer-grant.md` (+ `docs/vi/consumer-grant.md`). External teams need a dated stanza appended there; redistribution outside granted products needs a further written grant.
 
 ```bash
-# after a successful npm-publish workflow run (or from a packed tarball)
-npm install @cyberskill/design@1.0.0
+npm install @cyberskill/design@1.1.1
 ```
 
-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[]`.
+Then link styles and import components. **Next.js / Vite / SSR apps** use the default entry (bundler-native):
 
-**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`.
+```ts
+import { Button, TextField } from "@cyberskill/design";
+// equivalent: import { Button } from "@cyberskill/design/react";
+import "@cyberskill/design/styles.css";
+```
+
+Add `transpilePackages: ["@cyberskill/design"]` in Next.js (JSX ships as source). React and react-dom are **peerDependencies** — your app provides them. Published types use `export type *` (**TypeScript 5.0+**). Do **not** import `_esm/cs.mjs` (or `@cyberskill/design/legacy`) into an SSR bundler; that path self-ensures React via CDN and side-loads `_ds_bundle.js` for browsers only.
+
+**Browser / no-build:** import `@cyberskill/design/legacy` (`_esm/cs.mjs`) or continue with the static tree paths below. The published tarball is the **full portable tree** (styles, tokens, components, templates, guidelines, docs, UI kits) — not a minimal “lib-only” subset. Host-only tooling (Storybook, `_audit/`) is not in `files[]`.
+
+**First real install (Lumi).** Copy-paste working **browser** consumer: `examples/npm-hello/` — installs `@cyberskill/design@1.1.1` from the registry, links `styles.css`, mounts `Button` via the **legacy** browser entry (`_esm/cs.mjs`), scopes **Lumi** with `data-cs-element="hoa" data-cs-variant="plasma"` (locked row in `docs/products.md`). From that folder: `npm install && npm run smoke && npm start` → open `http://127.0.0.1:8766/`. Status Hub teams use the same install and swap to `data-cs-element="thuy"` — do not invent mappings. For Next/SSR product apps (e.g. Lumi landing), use `import { Button } from "@cyberskill/design"` as above — not the npm-hello import map.
+
+**Publish path (maintainers):** `prepublishOnly` runs `build:bundle` + `build:design-md --check`. Workflow `.github/workflows/npm-publish.yml` on `workflow_dispatch` / `v*` tags uses **Trusted Publishing** (`permissions.id-token: write`; do not set `NODE_AUTH_TOKEN` on the publish step). `node _audit/ci/npm-publish.mjs --dry-run` always lists the tarball. See `docs/ci-cd.md` and `docs/decisions.md`.
 
 ## Adopt (two paths, plus a module shortcut)
 
@@ -65,7 +76,9 @@ Then link styles and import from the package entry (`_esm/cs.mjs` via `exports["
 </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.
+**2b. Bundler-native React (Next / Vite / SSR) — default package entry.** `import { Button, TextField } from "@cyberskill/design"` resolves to `_esm/react.mjs` (also exported as `@cyberskill/design/react`). Re-exports every component from source JSX with **React as an external peer** — no CDN, no `_ds_bundle.js` side-load. Your bundler must transpile the package (Next: `transpilePackages: ["@cyberskill/design"]`). Still link `styles.css` yourself. Regenerated with `npm run build:react-entry`; parity is gated by `package-exports-integrity` + `test:react-entry`.
+
+**2c. Browser ESM legacy — one import, no build.** `import { Button, TextField } from "@cyberskill/design/legacy"` (or `"<path>/_esm/cs.mjs"`) — the module self-ensures React via **umd-react@19.2.8** (SRI-pinned CDN; official React 19 has no UMD; skipped when `window.React` exists), side-loads `_ds_bundle.js` once, resolves the namespace by prefix, and re-exports all components (`_audit/esm-smoke-test.html` keeps the export list in lockstep with the manifest). Still link `styles.css` yourself. **Not for Next/SSR.** Bundler apps should keep providing their own `react` / `react-dom` peers (`^18 || ^19`).
 
 **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.
 
@@ -73,13 +86,17 @@ This is exactly what `_audit/consumer-smoke-test.html` exercises (and asserts gr
 
 **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
+**Fonts, including a display face.** All three brand families are self-hosted in `fonts/` and declared by `tokens/fonts.css` (which `styles.css` `@import`s): **Be Vietnam Pro** (`--cs-font-family-ui`), **JetBrains Mono** (`--cs-font-family-mono`), and **Space Grotesk** (`--cs-font-family-display`, variable 300–700, Vietnamese subset included). The display face is **opt-in** — nothing in the DS points at it. A product that wants a headline face adds `class="cs-display-face"` (or sets `--cs-heading-family: var(--cs-font-family-display)`) on the scope; heading utilities follow, body copy stays on the UI face.
+
+Consumers that skip `styles.css` to control font loading (`cyberskill.world` / Lumi imports the token + base sheets individually and keeps its own `font-display: optional` strategy) can switch from their ad-hoc `brand-fonts.css` to the package: either `@import "@cyberskill/design/tokens/fonts.css"` for the packaged faces, or keep the local `@font-face` block and point `--cs-heading-family` at `var(--cs-font-family-display)` so the **role** comes from the DS even when the **bytes** are served locally. Either way the display face stops being a per-product exception. Space Grotesk has no 800 weight, so `--cs-heading-weight-strong` (800) under `.cs-display-face` clamps to 700 within Space Grotesk — CSS does not hop to Be Vietnam Pro for a missing weight.
 
-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).
+## The four axes
+
+State Theme (`data-theme` — light / dark / system), Element (`data-cs-element` + `data-cs-variant`), Language (`lang` / template Language tweak), and Style (`data-cs-style`) on a container; everything inside re-skins with no code change (see `templates/playground.html`). Defaults: `light · tho · en · liquid-glass` (absent theme / style ≡ those defaults). Bilingual: components resolve strings from `lang` (`lang="vi"` on any container → full Vietnamese).
 
 ## 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.
+- **Version is pinned.** `VERSION` and `package.json` stay at **1.1.1**. There is no design-system changelog file — treat the **git tip SHA** as the technical truth, and read curated **Release Notes** (Storybook + `docs/release-notes.md`) for product-facing highlights.
 
 - 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.
 
@@ -87,10 +104,22 @@ State Theme (`data-theme`), Element (`data-cs-element` + `data-cs-variant`), and
 
 ## 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`.
+The live site serves Storybook at `/` as the **product surface** for operators (Theme × Element × Language × Style + 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
 
+**Registry path (preferred for product apps):**
+
+```bash
+cd examples/npm-hello
+npm install
+npm run smoke
+npm start
+# open http://127.0.0.1:8766/
+```
+
+**Clone / static path (no npm):**
+
 ```bash
 # from monorepo root
 python3 -m http.server 8765 --bind 127.0.0.1
@@ -102,7 +131,7 @@ Edit `examples/static-hello/index.html`: flip `data-theme="dark"` or `data-cs-el
 
 ## 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.
+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`. Compose opens in **Android Studio** (no committed `gradlew` — CLI needs JDK 17+ + SDK; see `examples/native/README.md`). Not required for web consumers.
 
 ## Extending