@cyberskill/design 1.0.0

package/docs/conventions.md

@@ -0,0 +1,114 @@
+# Conventions — authoring the CyberSkill DS
+
+For humans and agents *extending this system*. (Consumers: read `SKILL.md`.) The compiler is the source of truth for counts; prose describes shape, never numbers.
+
+## The expansion rule
+
+**When anything grows, everything updates in the same change.** A new element/variant, icon, component, token role, language, or template pattern must propagate to: tokens/source → specimen cards (guidelines + the component group card) **and related guideline pages** → component contract trio (`.jsx` + `.d.ts` + `.prompt.md`) → **all** templates (tweak enums and maps) → Storybook Live / Identity Lab → docs (README counts, SKILL, **and every related document the change touches** — kit READMEs, registry, contrast report regenerated after token changes). **Do not bump `VERSION` and do not maintain a changelog file** — version stays at 1.0.0. Continuity is git history plus curated **Release Notes** (`docs/release-notes.md` / Storybook). Gate every expansion with the compiler check **and a grep for the old enum/list** — nothing ships half-propagated. Documented scope boundaries (doctrine, not gaps): UI-kit pages stay pixel-faithful Thổ recreations (axes demoed in Storybook Live and Identity Lab); every template is bilingual EN·VN and English-default (client/media collateral stays English-primary), and language variants render **fully separated** — see the decision log.
+
+## The three axes
+
+Every rendered surface resolves three orthogonal scopes — never encode one axis inside another:
+| Axis | Attribute | Owns | Packs live in |
+|---|---|---|---|
+| **Theme** | `data-theme="dark\|system"` | light/dark inversion | `tokens/colors.css` |
+| **Element** (Ngũ Hành) | `data-cs-element` + `data-cs-variant` | hue identity per product | `tokens/elements.css` |
+| **Language** | `lang` / Language tweak | EN · VI copy | component registry + template props |
+
+Surface treatment is liquid-glass (fixed). Immutable under all axes: Umber/Ochre anchors, voice, type families, semantic status colors, the 3px Ochre focus ring, APCA floors, ≥44px targets.
+
+## Naming grammar
+
+- Tokens: `--cs-<layer>-<role>[-<state>]` (`--cs-color-text-muted`). Element role layer: `--cs-accent-*` (9-token contract — see `tokens/elements.css` header).
+
+- Classes: `.cs-<block>[-<part>][--modifier]`. Data attributes: `data-theme`, `data-cs-element`, `data-cs-variant`.
+
+- Files: `tokens/<concern>.css` · `base/<concern>.css` (concern names, never changelog names — "interaction", not "refinements2") · `components/<group>/<Name>.{jsx,d.ts,prompt.md}` · `templates/<dept>-<artifact>/` · `guidelines/<group>-<topic>.html`.
+
+- Template display names: `<Group> · <Artifact>` ("Finance · Invoice").
+
+## Checklists
+
+**New component** — `Name.jsx` + `Name.d.ts` + `Name.prompt.md` in `components/<group>/`; add to the group's card html (resolve the bundle namespace **by prefix** — `const CS = window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]` — never a hardcoded `…_<projectId>` suffix); add to readme's group line. Consume tokens only; no hex literals except inside `tokens/`.
+
+**Responsive** — reflow is global (`base/responsive.css`, loaded last): media never overflows, print docs relax padding, `.cs-sheet` tables scroll, `.cs-sidebar` collapses, inline fixed-column grids collapse (3+→2 tablet, →1 phone), unbreakable long tokens (write-on `______` lines, long URLs/IDs) get `overflow-wrap: anywhere` on doc surfaces so they can't prop a phone column open, the app-shell shell grid collapses to one column with `main{min-width:0}`+`.cs-table-wrap` scroll, and fixed-geometry export canvases (`class="cs-canvas-desk"`: decks, social) **always** `overflow-x:auto` so a slide wider than the window scrolls inside the desk rather than pushing the page wide. Verified whole-set at 390 by `_audit/responsive-overflow.html` (all 84 = 0 document overflow). **Two hard gotchas:** (1) the DC runtime compiles inline `style="…"` into React objects, so the rendered attribute is *spaced* — any `[style*=…]` responsive selector must match `grid-template-columns: repeat(4, 1fr)` (colon-space, comma-space), never the authored no-space form; (2) a global CSS rule can only override a property the template sets **inline** via an **attribute** selector (`[style*="grid-template-columns: 248px 1fr"]`) — a **class** selector loses to the inline style. Prefer fixing overflow in the template source (add `min-width:0`, `flex-wrap:wrap` inline) over fighting inline from the stylesheet.
+
+**New template** — `templates/<slug>/<Slug>.dc.html` with `<!-- @template name description -->` first; `ds-base.js` stays single-entry (`styles.css` only — the one-line rebind was validated end-to-end Jul 2026 from a deeper path; the test scaffold has since been removed) and publishes the id-independent `window.CyberSkillDS` alias on bundle load, so mount DS components via `component-from-global-scope="CyberSkillDS.…"` — **never** a hardcoded `CyberSkillDesignSystem_<projectId>` suffix (it changes on re-import; enforced by `_audit/namespace-portability.html`); inline styles only; 1–3 tweaks (never plain copy/color — in-place editing covers those); printable docs add the `@page` + `.cs-desk`/`.cs-sheet` print block and carry **no dark tweak** (print is light-only).
+
+**New element variant** — stay inside the element's oklch envelope; set the 9 `--cs-accent-*` contract tokens plus `--cs-color-text-accent`/`--cs-color-link` (APCA-check both); the aurora wash inherits from the element via `.cs-aurora-wash` (override the class rule only if the variant truly needs its own image); gradient partner (`grad-b`) must follow Tương sinh.
+
+**Ship check** — run the compiler check until clean, then run `_audit/docs-consistency.html` **and** `_audit/namespace-portability.html` (both must be green). Version stays pinned at 1.0.0.
+
+## Decision log (owner-approved)
+
+- Elements fully replace Ochre inside product scopes; plasma's hot-pink edge approved (Jul 2026).
+
+- Axes are Theme × Element × Language only. Surface treatment is liquid-glass (fixed).
+
+- Product registry is **locked** (Jul 2026) — eight portfolio mappings in `docs/products.md`; do not invent new product → element assignments.
+
+- Text never sits on the mid-tone `-accent` — codified after the APCA sweep (see `docs/contrast-report.md`).
+
+- Language variants render **fully separated**: switching the Language tweak yields a complete single-language artifact — no partial translation left in headings, labels, helper text, footers, or body. The only bilingual-by-design elements are the CyberSkill name + slogan lockup (`Hiện Thực Hoá Ý Chí · Turn Your Will Into Real`, the canonical form — never a lone half) and the A4 legal identity block (company legal name + state motto). Everything else swaps with the tweak (Jul 2026).
+
+- **Namespace is resolved, never hardcoded** — the compiler names the bundle global `window.CyberSkillDesignSystem_<projectId>`, and that 6-hex suffix is derived from the project id, so it changes whenever the system is imported into another project. Templates read the stable `window.CyberSkillDS` alias that `ds-base.js` publishes on bundle load; cards, UI-kit pages, the standalone email, and audit harnesses resolve by prefix (`window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]`). `_ds_bundle.js`/`_ds_manifest.json` and the frozen `_audit/exports/` snapshot legitimately carry the real suffix (they *define* it). Enforced by `_audit/namespace-portability.html`, which scans every manifest-indexed source — keeps re-import **zero-touch** (Jul 2026).
+
+- Verification uses the `_audit/` dev harnesses (see `_audit/README.md`): `responsive-harness.html` (the user-facing Responsive preview — **every** template at 390/768/1280), `responsive-overflow.html` (whole-set horizontal-overflow gate at 390 — **use a fresh iframe per template; reusing one races the `@import` CSS and gives false positives**), and `vn-overflow.html` (forces VN across every template, measures clipping). Force states from a frame's own context: `__dcSetProps(__dcRootName(), {language:"Tiếng Việt"})`, theme via `postMessage({type:"__dc_theme",theme:"dark"})`. `_audit/` is dev-only — not compiled, not a card. Never pass a value to `TextField` as **children** (crashes React #137 on re-render — the input is a void element); use `default-value` (Jul 2026).
+
+## Export paths (per archetype)
+
+Every template exports; the right path depends on the archetype. All paths preserve Vietnamese Unicode (verified by unzipping PPTX slide XML and probing the standalone bundle — VN diacritics survive as native text, see `_audit/exports/`).
+| Archetype | Path | Notes |
+|---|---|---|
+| Deck (`*-deck`, `slide-deck`) | **PPTX (editable)** | `gen_pptx` at 960×540; force VN per-slide with `showJs: __dcSetProps(__dcRootName(),{language:'Tiếng Việt'})`. Text exports as native runs; only the Logo is an image. |
+| Document (any with `@page{size:…}`) | **One-click PDF** | All 61 doc templates carry `<meta name="omelette-owns-print">` in the raw `<head>`, so the browser print engine paginates them at A4/Letter with the `@media print` chrome-strip. Print CSS is `@media screen`-scoped elsewhere so screen reflow never leaks onto paper. |
+| Email / product page / any DC | **Standalone offline HTML** | The DC loads CSS + bundle dynamically via `ds-base.js`, which `super_inline_html` can't see. To bundle: make a `*-standalone.html` copy **in the same folder** (keeps `./support.js` relative) with **static** `<link rel="stylesheet" href="../../styles.css">` + `<script src="../../_ds_bundle.js">` in the raw `<head>` (both inlinable) instead of `ds-base.js`, plus a `<template id="__bundler_thumbnail">`. Bake the target language into the props default. Then `super_inline_html`. |
+| Any | **Editor-native + Claude Code handoff** | The whole project is dev-handoff-ready (compiled bundle + `.d.ts` + `prompt.md` per component); generate the package on request via the handoff skill. |
+
+**Font behavior on export.** Brand fonts are self-hosted (`Be Vietnam Pro` UI, mono). PPTX keeps the brand-font **names** but does not embed the files — on a machine without them PowerPoint substitutes a fallback (VN Unicode text is preserved; shapes may reflow slightly). For a fully self-contained hand-off, either tell the recipient to install the fonts, or export with a web-safe swap (`fontSwaps:[{from:'Be Vietnam Pro',to:'Arial'}]` — Arial covers Vietnamese). Standalone HTML **embeds** the fonts (inlined `@font-face` from `styles.css`), so it is always faithful offline (Jul 2026).
+
+## Accessibility (base/a11y.css + component ARIA)
+
+- **Focus rings are systematic** — global `:where(:focus-visible)` ochre ring in `base/reset.css`, plus per-component 3px ochre rings (`components/forms/navigation/controls`). Never set `outline: none` on a `:focus-visible` state without replacing the ring (the menu-item regression, fixed Jul 2026). The soft 5px glow in `interaction.css` layers on the 3px ring, never replaces it.
+
+- **Touch targets** — `base/a11y.css` guarantees 44px on `@media (pointer: coarse)` (tabs, pagination, menu items, stepper, checkbox/radio; segmented 40px in its padded track). Desktop mouse density is preserved. `pointer: coarse` is used deliberately over a width breakpoint — a touch laptop at 1280px still needs 44px. Button carries its own coarse block in `components.css`.
+
+- **Reduced motion** — `base/a11y.css` honours `prefers-reduced-motion: reduce` globally (near-zero animation/transition durations); component-level exceptions (spinner slow-spin, status pulse off) already existed.
+
+- **Screen-reader language** — every bilingual template carries a root `lang`: the 37 Vietnamese instruments (`vn-*`) are static `lang="vi"`; the 44 tweakable bilingual templates bind `lang="{{ langAttr }}"` to the Language tweak (`langAttr = language === "Tiếng Việt" ? "vi" : "en"`, injected into `renderVals`). Dual-block templates additionally wrap each `sc-if isVN` block in `<div lang="vi" style="display:contents">` (layout-neutral) so VN text is marked `vi` even in **Both** mode where the root is the primary `en`. Result: correct pronunciation in every language mode.
+
+- **Component ARIA is complete** — every interactive component ships correct roles/labels (Button `aria-busy`; TextField/Textarea `aria-invalid`+`aria-describedby`+`role=alert`; Switch `role=switch`; SearchField `role=searchbox`; Menu `aria-haspopup`/`aria-expanded`/`role=menu(item)`; Pagination `nav`+`aria-current`+prev/next labels; Dialog/Drawer `aria-modal`; Toast `role=status`/`region`; ConfidenceMeter `role=meter`; Accordion `aria-expanded`; Logo `role=img`/`aria-hidden`). Preserve these when composing.
+
+- **Void-element API rule** — components that render a void element (`<input>`/`<hr>`: TextField, Checkbox, Radio, Switch, SearchField, NumberField, Slider, Divider) destructure `children` out of `...props` so a stray child can never spread onto the void element (that crashes React with #137, the bug that hit `settings`). Content always comes from explicit props (`label` / `value` / `defaultValue`), never `children`. Follow this when adding any input-based component (Jul 2026).
+
+- **Dark-theme contrast** — all text/surface pairings pass WCAG AA body (9–15:1). Semantic colours have dark overrides (`success #4ADE80`, `danger #F87171`, `warning #FBBF24`, `info #7CB2FB`) because the light-theme semantics failed on dark surfaces (~2.5:1); verify any new semantic pairing on `#221710`/`#2b1e14` (`_audit/` contrast math). The dark hairline border is intentionally subtle (separator, not a 3:1 boundary) (Jul 2026). **Interactive components that set `color`/`border-color: var(--cs-color-brand-umber)` on a themeable surface** (nav-item active, secondary/tertiary/ghost buttons, and the like) MUST ship a `[data-theme="dark"]` override — umber is near-invisible on dark; remap to ochre (emphasis) or `--cs-color-text-primary` (body). Screen-template brand wordmarks use `--cs-color-text-primary` (never hardcoded umber) so they flip in dark; print-doc headers stay umber by design. Table ID/code columns (e.g. `R-26-07`) carry `white-space:nowrap` so a hyphenated code never word-breaks in a narrow column (Jul 2026, user-reported). The umber-on-themeable-surface rule is now **enforced deterministically** by `_audit/contrast-guard.html` (static source lint + a token-pair WCAG matrix scored in light *and* dark) — the reliable gate the DOM-walk theme advisory couldn't be (v2.21.0). Note: `accent-strong` (the "accent text on light" role) is APCA-validated but WCAG-borderline (~3.2–4.3) for a few element packs (tho, tho/sand, thuy/mist, moc/bamboo) — reserve it for semibold/large accent text; the guard lists these as advisory and gates only egregious <3.0 (v2.21.1).
+
+## RTL readiness (confirmed Jul 2026)
+
+The system is **RTL-ready** — `base/*.css` is authored almost entirely in CSS **logical properties** (`inline-start`/`inline-end`, `margin-inline`, `padding-block`, `border-inline-*`, `inset-inline-*`), so setting `dir="rtl"` mirrors layouts automatically. Verified by rendering the kitchen-sink at `dir="rtl"` — nav, buttons, right-aligned labels, and mirrored fields/error text all flip correctly. The only physical props left are intentionally direction-agnostic: the dialog's `left:50%`+`translateX(-50%)` centering (symmetric) and the spinner's `border-right-color` (a rotating visual detail). Keep new CSS logical; reserve physical `left`/`right` for genuinely symmetric centering only. (Vietnamese is LTR, so RTL isn't shipped in templates — but the foundation is there for an Arabic/Hebrew tenant.)
+
+## Real imagery (image-slot retrofit)
+
+Templates lean on the `.cs-aurora-wash` gradients by default; to accept **real** photography, drop `<image-slot>` in. Load the component once per template via the helmet (`<script src="../../image-slot.js"></script>` — path relative to the template) and place `<image-slot id="…" shape="rect" style="position:absolute;inset:0;z-index:0">` as the **first** child of a `position:relative` hero, then layer `.cs-aurora-wash` (z-index:1, `pointer-events:none`) and a warm umber scrim (`linear-gradient(90deg,rgba(42,26,13,.86),rgba(42,26,13,.34))`, z-index:1, `pointer-events:none`) above it, with the content at z-index:2. The scrim keeps the empty drop-tile subtle and copy legible over any photo. Verified in `marketing-case-study`; the same 4-line pattern fits `marketing-page`, `marketing-social-kit`, `culture-event-invite`, and an `article` hero (each on request). Standalone reference: `templates/image-slots-demo.html`. Slots persist via a sibling sidecar (Jul 2026).
+
+## Vietnamese typography & locale (verified Jul 2026)
+
+Vietnamese is the primary language; the type system is built for it — verified, no changes needed:
+- **Line-heights are VN-safe** — tokens body 1.5 / heading 1.35 / tight 1.15 leave room for stacked diacritics (dấu on top + nặng below). `:where(h1–h6)` defaults to 1.35 + `text-wrap: balance`; `:where(p)` gets `text-wrap: pretty` (both `base/reset.css`). Templates may hardcode a tighter line-height (≈1.0–1.15) **only** on single-line hero display headings; multi-line VN headings keep ≥1.15.
+
+- **Locale formatting** — each language renders its own conventions: **VN** uses `₫` suffix, `DD/MM/YYYY`, dot-thousands (`1.000.000`); **EN** uses `$` prefix, `DD Mon YYYY`, comma-thousands (`1,000,000`). English-format dates live only in English branches — never leak into a VN branch. Confirmed by scan across all templates.
+
+## Whole-set state audits — language · theme · responsive (each its own pass, Jul 2026)
+
+Owner doctrine: language, theme, and responsive each get their OWN whole-set pass; one clean state is not evidence for another. All three are now race-free, manifest-driven, **all-84** pass/fail gates built on the same pattern — a **fresh single-navigation iframe per template** (reusing one iframe across `src` swaps races the `@import`ed CSS and yields false results), state forced via `__dcSetProps`, settle, then measure:
+- **Language** — `_audit/language-overflow.html` — forces `Tiếng Việt`; 0 VN overflow/clip @390; also asserts VN actually applied on every template.
+
+- **Theme** — `_audit/theme-overflow.html` — forces dark; hard gate = dark-applies + 0 dark overflow @390 + 0 open solid-bg leaf-text contrast fails outside `REVIEWED_OK`.
+
+## Theme-overflow contrast is a hard gate (Jul 2026)
+
+`theme-overflow.html` fails `window.__theme.pass` on reproducible WCAG AA fails for leaf text over a resolvable solid background, except templates in the page's `REVIEWED_OK` allowlist (today: three canvas decks whose accent-bright eyebrows on accent-strong sit ~4.22:1 — APCA dark packs still pass; do not retune tokens for that WCAG body near-miss). The walker converts oklab/`color-mix` backgrounds via canvas so element-pack surfaces are not mistaken for the light `body` fallback. Gradients / images / branded washes stay skipped (uncomputable). **Filled CTAs on themeable screens** use `background: var(--cs-accent-strong); color: var(--cs-accent-on)` — dark packs set `--cs-accent-on` to cream for `on/strong` (APCA ≥ 75); cream on `--cs-accent-bright` fails. Light-only print / VN legal instruments stay n/a. Companion proofs: `contrast-guard.html`, `apca-dark-preview.html`, `docs/contrast-report.md`.
+
+## Token exports (Jul 2026)
+
+Machine-readable token exports live in `tokens/`: `tokens.json` (grouped by category + scope-override maps), `tokens.js` (ESM), and `tokens.dtcg.json` (**W3C DTCG** — `$value`/`$type`, CSS-var keys for lossless round-trip to `styles.css`, dark/system + element + expression overrides under `$extensions`; for Tokens Studio for Figma / Style Dictionary). All three are generated from `tokens/*.css` via `tokens.json` — regenerate **all** after any token change (Expansion rule).

package/docs/decisions.md

@@ -0,0 +1,94 @@
+# Decisions (maintainer)
+
+Owner choices that shape CI, Figma sync, and distribution. How-tos live in `docs/figma.md` and `docs/ci-cd.md` — this file is the decision record only. Not a consumer guide.
+
+## 1. Whole-set audits on every PR
+
+**Owner choice: B — Enable on every PR** (Jul 2026)
+
+`whole-set-audits` runs on push, pull_request, schedule (`0 3 * * *`), and `workflow_dispatch`. Plan ~15–20 minutes for that job.
+
+## 2. Pixel-threshold CI auto-fail
+
+**Owner choice: enabled — hard gate** (Jul 2026)
+
+Playwright `%` pixel compare (`_audit/ci/pixel-diff.mjs`) is a hard gate. Drift above threshold fails the Pixel CI board row and the `pixel-diff` CI job (no `continue-on-error`). Side-by-side visual / component baseline review pages remain advisory (drift judged by eye). After intentional redesigns, refresh `_audit/baselines/` with `--update` and commit the PNGs.
+
+## 3. Figma / Tokens Studio
+
+**Owner choice: A — non-Enterprise for now** (Jul 2026)
+
+Stay on the current Figma plan. Variables REST API is Enterprise-only — write jobs **soft-skip** (exit 0 + report) when the plan or secrets cannot complete the write. That soft-skip is **not** a live Variables sync — do not treat CI green as proof that Figma Variables were updated. Colour sync = hand-sync and/or Tokens Studio from `tokens/tokens.dtcg.json`. See `docs/figma.md`.
+
+## 4. Live hub = Storybook only
+
+**Owner choice: Storybook is the single live hub** (Jul 2026)
+
+- Operators use Storybook at `/` for Theme × Element × Language and component control matrices.
+- No separate Live View page exists in the tree.
+- Legacy `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` redirect to `/`.
+- Portable Atomic View and other static HTML remain for zero-build gates and consumers; they are not the site product entry.
+- Surface map: `docs/live-hub.md`.
+
+## 5. Dual token JSON sources
+
+**Owner choice: keep both `tokens.json` and `tokens.dtcg.json`** (Jul 2026)
+
+| File | Role |
+|---|---|
+| `tokens/tokens.dtcg.json` | W3C DTCG interchange / native regen |
+| `tokens/tokens.json` | CSS-oriented grouped export |
+| `tokens/*.css` + `styles.css` | Runtime UI |
+
+## 6. Code Connect — path shipped; **deferred** on free Figma
+
+**Status: provisional / soft-skip — not a live library publish** (Jul 2026; deferred Jul 2026)
+
+- CI job `code-connect` + `figma.config.json` + 99 `*.figma.tsx` mappings are in-repo (import snippets use `@cyberskill/design`).
+- Publish soft-skips when secrets are missing or the API returns 403/404/429. Soft-skip ≠ successful Code Connect publish.
+- **Owner deferral:** stay on **Figma free / non-Org** for now — do not pursue live Code Connect until an Org/Enterprise seat with a published team library is available. Then replace synthetic `9999:*` stubs in `code-connect/node-map.json` with real `nodeId`s. See `docs/figma.md`.
+
+## 7. npm publish — path shipped; unlock in progress
+
+**Status: operator-ready; package not yet on the registry as `@cyberskill/design`** (Jul 2026)
+
+- `package.json` is `private: false`; package name **`@cyberskill/design`** (scoped `@cyberskill/*` convention; `publishConfig.access: public`); `prepublishOnly` runs `build:bundle` + `build:design-md --check`.
+- Workflow `.github/workflows/npm-publish.yml` on `workflow_dispatch` / `v*` tags; without `NPM_TOKEN` the job **soft-skips** (exit 0 + tarball report). Soft-skip ≠ a published release.
+- **Owner progress:** npm org **`@cyberskill`** already publishes other packages; `NPM_TOKEN` is set on the repo. **Still required:** run **Actions → npm-publish → Run workflow** once so `@cyberskill/design@1.0.0` appears on the registry, then issue an **explicit consumer grant** (policy text — not a secret) for teams allowed to install. License stays **UNLICENSED**; version stays **1.0.0**. See `docs/consuming.md`.
+
+## 8. Native store packaging — scaffolds shipped; submit disabled
+
+**Status: Fastlane path live; signing secrets operator-owned; no store submit** (Jul 2026)
+
+- Scaffolds under `examples/native/{swiftui,compose,flutter}/fastlane/` + listing metadata placeholders.
+- Workflow `.github/workflows/native-store.yml`; dry-run always; signed-release checks need `ASC_KEY_ID` / `ASC_ISSUER_ID` / `ASC_KEY_P8` / `PLAY_SERVICE_ACCOUNT_JSON`.
+- `upload_store` lanes refuse submit — samples remain samples until product need. See `examples/native/README.md`.
+
+## 9. Products registry — locked
+
+**Owner choice: lock the product → element registry** (Jul 2026)
+
+`docs/products.md` (+ `docs/vi/products.md`) is the **locked** source of truth for the eight portfolio mappings. Agents and kits must use those rows; do not invent new product → element assignments. Changes require an edit to this decision record in the same change.
+
+## Roadmap defaults (distribution unlocks)
+
+Recorded Jul 2026 — unlock defaults (updated as operator steps land):
+
+- **Figma Variables** — stay Tokens Studio / non-Enterprise (decision §3). Soft-skip on Variables REST remains honest.
+- **Code Connect** — **skipped while on Figma free**; revisit only after Org + published library + real `nodeId`s (decision §6). Soft-skip ≠ publish.
+- **npm** — org `@cyberskill` + `NPM_TOKEN` ready; first publish of `@cyberskill/design` + written consumer grant still owner-run (decision §7). Soft-skip ≠ a published release of *this* package.
+
+## Maintainer tasks (open)
+
+Operational follow-ups — not product marketing, not a backlog surface:
+
+1. **Code Connect** — deferred (Figma free). When upgrading to Org: replace `9999:*` stubs in `code-connect/node-map.json` with real published-library node IDs.
+2. **npm first publish + grant** — ~~org / `NPM_TOKEN`~~ **done**. Remaining: Actions → **npm-publish** → Run workflow; confirm `npm view @cyberskill/design`; write the consumer grant for approved teams (see `docs/consuming.md`).
+
+~~3. Finalize products registry~~ — **done** (Jul 2026): see decision §9; `docs/products.md` is locked.
+
+Schema sidecars and Storybook `FullMatrix` continue to grow **opportunistically** when a primary already qualifies (today only Button has FullMatrix under the contract) — not as a mass-add pass. See `docs/quality-gates.md`.
+
+## How to change a decision
+
+Edit the **Owner choice** line here. Implementer rewires CI and related docs in the same change.

package/docs/deploy.md

@@ -0,0 +1,110 @@
+# Deploying the live Atomic site (Vercel / VPS / any static host)
+
+Two tracks:
+
+1. **Portable design system (consumers)** — still a static file tree: no bundler required. Link `styles.css` + optionally `_ds_bundle.js` / ESM. Claude Design, Google Stitch, and product apps never need Node or Storybook.
+2. **Host site (`design.cyberskill.world`)** — static output packaged for Vercel. Packaging **does** run Node once at deploy time so Storybook ships as the product surface at `/`. There is still no long-running app server.
+
+Production **`/`** is the Storybook static build. Legacy `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, and `/playground/:path*` redirect to `/`.
+
+## Vercel (recommended)
+
+1. Push the repo (see `docs/sync.md`) to GitHub.
+2. Vercel → **Add New Project** → import the repo.
+3. **Framework preset: "Other"** (not Next.js/CRA). Prefer trusting `vercel.json` rather than typing commands in the dashboard.
+4. Deploy. `/` serves Storybook. Old hub/playground URLs 301 to `/`.
+5. Custom domain: Project → Settings → Domains, add it, point DNS per Vercel's instructions.
+
+**`vercel.json` pins the host packaging path:**
+
+| Field | Value | Why |
+|---|---|---|
+| `framework` | `null` | No framework auto-detect |
+| `installCommand` | `npm install` | Host-only: install Storybook/dev tooling for the static product build |
+| `buildCommand` | `npm run build:site` | `build:storybook` then `scripts/vercel-static-output.mjs` |
+| `outputDirectory` | `.vercel-static` | Packaged webroot (portable tree + Storybook overlaid at root) |
+| `redirects` | `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/` | Retire the old HTML hub and subdirectory Storybook path |
+
+Local equivalent: `npm install && npm run build:site`, then serve `.vercel-static/`.
+
+Consumers cloning this repo still open files directly — they do **not** run `build:site`.
+
+## Social preview image (OG)
+
+Shipped for production (`design.cyberskill.world`):
+- Storybook manager head (`.storybook/manager-head.html`) and the legacy `dashboard.html` redirect stub include:
+  - `og:image` → `https://design.cyberskill.world/assets/og-dashboard.png`
+  - `twitter:card` = `summary_large_image`
+  - `twitter:image` (same URL)
+  - `og:url` / canonical → `https://design.cyberskill.world/`
+
+If you host under a **different** domain, change the absolute URLs in those meta tags to match your origin, or re-export the PNG and keep the path `assets/og-dashboard.png`.
+
+**Common misconfig:** picking a JS framework preset (Next/CRA) — Vercel then runs the wrong build graph and may 404 root docs. The preset must stay **"Other"** and `vercel.json` must own install/build/output (see table above). `package.json` is publishable (`"private": false`) for the npm path; it also carries **host-only** scripts (`build:storybook`, `build:site`, verify/test) that product apps should not depend on (see `docs/consuming.md` and `docs/storybook.md`). Packaging copies the portable webroot then overlays Storybook at `.vercel-static/` root (portable paths like `/styles.css`, `/_audit/`, `/guidelines/` stay available beside Storybook assets). **How to tell a hosting misconfig from a real docs bug:** open `/_audit/docs-consistency.html` on the *deployed* URL — the gate detects an HTML/error body where a raw `.md`/`.json` was expected and reports "hosting is intercepting this path".
+
+## Generic VPS / nginx / any static host
+
+**Without Storybook:** serve the repo root as the webroot (portable tree only).
+
+**With Storybook at `/`:** run `npm run build:site` on the host or CI, then serve `.vercel-static/` as the webroot. Configure the same redirects as `vercel.json` (`/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/`) if your host supports them.
+
+Nginx example (`.vercel-static` as `root`):
+server {
+  server_name design.cyberskill.world;
+  root /var/www/design-system/.vercel-static;
+  index index.html;
+  location = /dashboard { return 301 /; }
+  location = /dashboard/ { return 301 /; }
+  location = /dashboard.html { return 301 /; }
+  location ^~ /dashboard/ { return 301 /; }
+  location = /playground { return 301 /; }
+  location /playground/ { return 301 /; }
+}
+Portable paths remain real files (`guidelines/atomic-view.html`, `_audit/run.html`, `styles.css`, etc.). Storybook owns `/` and `/index.html`.
+
+## Post-deploy checklist
+1. Open `/` — confirm Storybook loads (not a 404, directory listing, or the old dashboard shell).
+2. Open `/_audit/run.html` — let the board finish, confirm all fast gates pass on the *deployed* copy (CDN caching, MIME types, or a missed file can surface here even when local checks were clean).
+3. If anything is red, read the failed gate row and open that gate page for detail — see `docs/consuming.md` → "After import — prove health".
+4. Check `/guidelines/atomic-view.html` directly loads (it's the heaviest page — React + the compiled bundle over the network).
+5. Confirm `/dashboard.html` and `/playground/` redirect to `/`, and a story still renders (e.g. Components/Button).
+
+## What NOT to do
+- Don't force **consumers** through a Storybook or app bundler — their contract remains clone-and-link `styles.css` (+ optional bundle). Host-site packaging (`build:site`) is only for this live site's `/` Storybook shell and static package layout.
+- Don't switch Vercel framework preset away from "Other" / `framework: null`.
+- Don't gitignore any top-level folder beyond what `.gitignore` already lists (`uploads/`, `scraps/`, `_audit/exports/`, `storybook-static/`, `.vercel-static/`) — every other folder, **including underscore-prefixed ones like `_esm/`**, is source and must ship in the portable tree. See `docs/sync.md`.
+- Don't put Storybook under `/playground/` again — `base: '/'` in `.storybook/main.js` expects domain-root assets.
+
+
+## Post-deploy Health re-run protocol (release gate)
+
+After every production deploy:
+2. Open `docs/viewer.html#README.md` — body must not stay on Loading…
+3. `curl -sS https://<host>/VERSION` must return plain semver text, not HTML.
+4. `curl -sS -I https://<host>/package.json` must be `application/json` or `text/plain`, not an SPA shell.
+
+
+## Content-Security-Policy notes
+
+Static hosting can ship a strict CSP. Typical allowances for this system:
+- `script-src 'self' https://unpkg.com` if you load React from CDN for Atomic View
+- `font-src 'self'`
+
+- `img-src 'self' data:`
+Prefer self-hosting React next to `_ds_bundle.js` for air-gapped installs.
+
+## Multi-domain OG
+
+Production meta points at `https://design.cyberskill.world/assets/og-dashboard.png`. On another host, replace the absolute origin in `.storybook/manager-head.html` (and the `dashboard.html` stub) `og:image` / `twitter:image` / `og:url` — keep the path `/assets/og-dashboard.png`.
+
+## Storybook product surface (host-only)
+
+Production path: **`/`** (Storybook static export overlaid on `.vercel-static/`).
+
+| Command | Result |
+|---|---|
+| `npm run storybook` | Dev server (local only) |
+| `npm run build:storybook` | Writes `storybook-static/` with `base: '/'` |
+| `npm run build:site` | Storybook build + portable tree → `.vercel-static/` (Storybook at root) |
+
+See `docs/storybook.md`. Portable consumers never need this path — they use `styles.css` + `_ds_bundle.js` / ESM.

package/docs/design-styles.md

@@ -0,0 +1,25 @@
+# Design styles
+
+Current surface treatment is **liquid-glass** (fixed). The live styling axes are **Theme × Element × Language** only.
+| Axis | How to set it | What it changes |
+|---|---|---|
+| **Theme** | `data-theme="light\|dark"` | light/dark semantic colours |
+| **Element** | `data-cs-element` + optional `data-cs-variant` | Ngũ Hành product identity (15 packs) |
+| **Language** | `lang` / Language tweak | EN · VI copy |
+
+## Fixed treatment
+
+- Liquid-glass materials (`cs-surface-*`) are the default surface language.
+
+- Radius, shadow, and glass tokens come from the base system — not a parallel "style pack" axis.
+
+- Rejected by doctrine: neon/cyberpunk cold hues, memphis playfulness, full skeuomorphism, emoji in UI chrome.
+
+## Adding a new look
+
+Prefer:
+1. A new **Element** or **variant** when the shift is hue/identity.
+2. Local composition with existing tokens/classes when the shift is one-off layout.
+3. A documented pattern in `docs/conventions.md` + a specimen card when the pattern should be reusable.
+
+Do not invent a fourth product axis without an Expansion Rule pass across tokens, Storybook Live, templates, docs, and gates.

package/docs/figma.md

@@ -0,0 +1,119 @@
+# Figma / Tokens Studio notes
+
+## What ships in-repo
+- Design tokens in CSS + DTCG (`tokens/tokens.dtcg.json`) with native Swift/Kotlin/Flutter mirrors.
+- UI kits under `ui_kits/` are HTML recreations that stay pixel-faithful to the brand doctrine (Thổ-first Identity Lab).
+- **Code Connect** mappings for all **99** public primaries (`components/**/*.figma.tsx` + `figma.config.json` + `code-connect/node-map.json`).
+
+## Tokens Studio import recipe (hand-sync)
+
+Recommended colour/type/spacing interchange until the design org is on Figma Enterprise (Variables REST). Source of truth stays **code → design**.
+
+1. Open the target Figma file (same file as `FIGMA_FILE_KEY` when you have secrets).
+2. Install / open **[Tokens Studio](https://tokens.studio/)** (Figma plugin).
+3. **Import** → choose **W3C DTCG / JSON** → select repo file `tokens/tokens.dtcg.json` (or paste its contents).
+4. Map token sets to a collection (e.g. **CyberSkill Tokens**). Prefer keeping CSS-var keys / slash groups close to `_audit/ci/push-figma-variables.mjs` `toFigmaName` (`color/brand/umber`, …) so a later Enterprise REST push does not rename everything.
+5. Apply tokens to local variables / styles in Figma. Re-import after token PRs — do **not** round-trip design edits back into DTCG unless you intentionally own that change in code.
+6. Optional: Style Dictionary / other DTCG consumers can read the same file; native mirrors stay generated via `node _audit/ci/generate-native-tokens.mjs`.
+
+**Scope note:** REST auto-push (below) covers **colour** leaves only. Tokens Studio can carry spacing/type/shadow from the same DTCG file by hand.
+
+## Automated colour variable push
+
+CI job **`figma-variables-push`** (in `.github/workflows/design-system-gates.yml`) reads `tokens/tokens.dtcg.json` and creates/updates a Figma local variable collection **CyberSkill Tokens** with colour variables.
+
+| Trigger | Behaviour |
+|---|---|
+| Push to `main` | Runs push (needs secrets) |
+| `workflow_dispatch` | Manual run from Actions tab |
+| PR | Does not push (avoids noise); dry helpers still available locally |
+
+### Secrets (repo → Settings → Secrets and variables → Actions)
+
+| Name | Value |
+|---|---|
+| `FIGMA_TOKEN` | Figma personal access token with **Variables** scopes (and Code Connect scopes when publishing mappings) |
+| `FIGMA_FILE_KEY` | File key from `https://www.figma.com/design/<KEY>/...` |
+
+Must be **repository secrets** under the Actions tab (exact names, case-sensitive). Not Environment secrets (those only inject when a job sets `environment:`), not Variables, and not org secrets that exclude this repo. CI log for a missing secret shows `FIGMA_TOKEN:` / `FIGMA_FILE_KEY:` with empty values.
+
+**Required scopes for the Variables push** (from [Figma scopes](https://developers.figma.com/docs/rest-api/scopes/) + [Variables API](https://developers.figma.com/docs/rest-api/variables/)):
+
+| Scope | Why | Availability |
+|---|---|---|
+| `file_variables:read` | `GET /v1/files/:key/variables/local` | **Enterprise only** |
+| `file_variables:write` | create/update collection + colour variables | **Enterprise only** |
+| `file_content:read` / `file_metadata:read` | confirm file access before push | all plans |
+
+If you hover a PAT and only see scopes like `file_content:read`, `file_comments:*`, `webhooks:*`, `library_*` — that is expected on **Professional / Organization** seats. Figma **does not list** `file_variables:*` unless the account is on **Enterprise**. Regenerating a PAT on a non-Enterprise plan cannot unlock the Variables REST API.
+
+**What CI does today:** secrets + file open work on any plan; the Variables write soft-skips with a report when Figma returns 403 / invalid scopes for `file_variables` (so gates stay green). Full auto-push needs Enterprise + those two scopes on the PAT.
+
+**Non-Enterprise alternatives:** hand-sync colour styles from `tokens/tokens.dtcg.json`, or use [Tokens Studio](https://tokens.studio/) / the Plugin API inside the desktop app (plugin path does not use this REST job) — see the import recipe above.
+
+### Local
+
+```bash
+# no secrets — print plan only
+node _audit/ci/push-figma-variables.mjs --dry-run
+
+# with secrets in env (never commit them)
+export FIGMA_TOKEN=...
+export FIGMA_FILE_KEY=...
+node _audit/ci/push-figma-variables.mjs --check   # file access + list collections
+node _audit/ci/push-figma-variables.mjs           # create/update colours
+```
+
+After a successful push, open the file in Figma → **Local variables** → collection **CyberSkill Tokens**.
+
+### Where to get a Figma token
+
+1. Log into [figma.com](https://www.figma.com).
+2. **Settings → Security → Personal access tokens** → generate.
+3. File key: open the target file; URL segment after `/design/` or `/file/`.
+
+## Figma Code Connect (live + soft-skip)
+
+**Decision 1C:** the publish path is wired; CI **soft-skips** (exit 0 + `code-connect-report.json`) when `FIGMA_TOKEN` / `FIGMA_FILE_KEY` are missing or the API returns **403 / 404 / 429** (plan, unpublished nodes, rate limit).
+
+| Piece | Path |
+|---|---|
+| Config | `figma.config.json` (React parser, `components/**/*.figma.tsx`) |
+| Node registry | `code-connect/node-map.json` (per-primary `nodeId` + `published` flag) |
+| Mappings | `components/**/<Name>.figma.tsx` — **99** primaries; Button / TextField / Dialog / Card / Alert have prop maps; others are stubs |
+| Generator | `npm run code-connect:generate` → `_audit/ci/generate-code-connect.mjs` |
+| CI job | `code-connect` in `design-system-gates.yml` (PR + `main` + manual) |
+| Local dry-run | `npm run code-connect:dry-run` (no secrets; asserts config + ≥99 files) |
+
+Document URLs use placeholder file key **`CS_FIGMA_FILE_KEY`**. Publish substitutes `FIGMA_FILE_KEY` via `documentUrlSubstitutions`.
+
+### Operator checklist (first real publish)
+
+1. Publish each Figma component to the **team library** (Code Connect requires published components; Org/Enterprise plan).
+2. Set `nodes.<Name>.nodeId` in `code-connect/node-map.json` (colon or hyphen form) and `published: true`.
+3. `npm run code-connect:generate` to rewrite `.figma.tsx` URLs.
+4. With secrets: `node _audit/ci/code-connect-publish.mjs` (or let the CI job run on `main`).
+
+Until real node IDs exist, synthetic `9999:*` stubs remain; publish reports and exits cleanly on 404. Remaining blockers: `docs/decisions.md` §6.
+
+```bash
+npm run code-connect:dry-run
+# with secrets
+export FIGMA_TOKEN=...
+export FIGMA_FILE_KEY=...
+node _audit/ci/code-connect-publish.mjs
+```
+
+## Hand-sync / Tokens Studio (owner decision A — non-Enterprise)
+
+Recommended path until the design org is on Enterprise:
+
+1. Treat `tokens/tokens.dtcg.json` as the colour/type/spacing interchange source.
+2. **Tokens Studio** (or similar): follow the import recipe above; re-export only when you intentionally change design-side values (prefer code → design direction).
+3. Hand-sync map: DTCG path → Figma variable name via the same slash naming as `_audit/ci/push-figma-variables.mjs` (`toFigmaName`).
+4. Code Connect is live-wired with soft-skip (this file) — fill `node-map.json` when library components exist.
+5. When the org moves to Enterprise, re-enable full REST push (remove soft-skip need) with `file_variables:read` + `file_variables:write` on the PAT.
+
+## Scope limits (honest)
+
+Variables job pushes **colour** variables only (hex leaves from DTCG). Spacing, type, and multi-mode light/dark packs are not auto-synced yet — use Tokens Studio for those until a later sync expands the REST job.

package/docs/live-hub.md

@@ -0,0 +1,58 @@
+# Live hub = Storybook
+
+## Decision
+
+**Storybook is the single live interactive hub** for operators on `design.cyberskill.world`. There is no separate Live View page and no separate HTML dashboard product shell. Production **`/`** is Storybook.
+
+## Sidebar IA
+
+| Group | Role |
+|---|---|
+| **Docs** | Public MDX guides (consuming, deploy, conventions, styles, products, schema, Figma, contrast, voice, axes) |
+| **Foundations** | Colors, typography, spacing, elevation, motion, elements |
+| **Components** | Full CSF library |
+| **Release Notes** | Curated product prose (**no CHANGELOG.md**) |
+| **Status** | Full-bleed embed of `_audit/run.html` (auto-run on first load; **Re-run** on demand) |
+| **A11y / I18n** | Accessibility + bilingual specimens |
+| **Maintainer** | Portable HTML iframes for gates (Atomic View buried here — not a public top-level entry) |
+
+## Surfaces
+
+| Surface | Role |
+|---|---|
+| **Storybook** (`/`) | Host product surface: Theme × Element × Language toolbar, Docs/Foundations/Components/Release Notes/Status, and Maintainer/* iframes into portable HTML |
+| **Atomic View** (`guidelines/atomic-view.html`) | Portable zero-build component grid for gates and clone-and-open browsing — not the public product entry |
+| **Other guidelines / templates** | Portable specimens; opened from Storybook Maintainer/* when exploring Motion, Identity Lab, kitchen-sink, etc. |
+| **Legacy `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*`** | Redirect to `/` (stubs + Vercel redirects) |
+
+## Surface map (Maintainer/* stories)
+
+| Storybook entry | Portable HTML |
+|---|---|
+| Components/* CSF | React sources under `components/` |
+| Maintainer/Surfaces → Motion | `guidelines/motion.html` |
+| Maintainer/Surfaces → Identity Lab | `ui_kits/status-hub/identity-lab.html` |
+| Maintainer/Surfaces → Template Playground | `templates/playground.html` |
+| Maintainer/Surfaces → Kitchen Sink | `templates/kitchen-sink.html` |
+| Maintainer/Surfaces → Image Slots | `templates/image-slots-demo.html` |
+| Maintainer/Surfaces → AI Cluster | `templates/ai-cluster-demo.html` |
+| Maintainer/Surfaces → RTL | `guidelines/rtl-preview.html` |
+| Maintainer/Surfaces → Atomic View (gates) | `guidelines/atomic-view.html` |
+| Status/Gate board | `_audit/run.html` |
+
+## Status behavior
+
+- Opening Status loads `_audit/run.html`, which **auto-runs** the fast board once.
+- Storybook may keep a cached iframe when you navigate away and back — that does **not** silently re-run gates.
+- Use the board **Re-run** button for a fresh pass (each gate iframe is cache-busted).
+
+## Portable consumers (unchanged)
+
+Consumers still link `styles.css` / `_ds_bundle.js` / ESM / templates. **Do not** require Storybook in product apps. See `docs/consuming.md`.
+
+## Local
+
+```bash
+npm run storybook          # product Storybook at http://localhost:6006
+npm run build:site         # packages Storybook at .vercel-static/ (site root `/`)
+```

package/docs/products.md

@@ -0,0 +1,26 @@
+# Product registry — element mapping
+
+> **Locked** (Jul 2026). Canonical product → element registry for agents and kits. Do **not** invent new product → element assignments; add or change rows only via a maintainer decision in `docs/decisions.md`.
+
+**Source of truth.** Maps CyberSkill portfolio products to Ngũ Hành element packs. One element per product; secondary accents only in gradient washes along Tương sinh.
+
+| Product | Element | Variant | Secondary (Tương sinh) | Markup |
+|---|---|---|---|---|
+| **Lumi** — wish assistant | Hỏa · fire | plasma | tho | `data-cs-element="hoa" data-cs-variant="plasma"` |
+| **Status Hub** — client portfolio portal | Thủy · water | river (default) | moc | `data-cs-element="thuy"` |
+| **CyberOS Agent Spine** — agent infra, memory, gates | Kim · metal | steel | thuy | `data-cs-element="kim" data-cs-variant="steel"` |
+| **CyberSkill Design System** — this library | Mộc · wood | leaf (default) | hoa | `data-cs-element="moc"` |
+| **cyberskill.world** — the studio site | Thổ · earth | studio (default) | — | *(no attributes — studio is Thổ)* |
+| **Client delivery suite** — kickoff · QBR · runbooks | Thổ · earth | clay | kim | `data-cs-element="tho" data-cs-variant="clay"` |
+| **Board / investor collateral** | Kim · metal | champagne (default) | thuy | `data-cs-element="kim"` |
+| **HR / employment instruments** | Mộc · wood | bamboo | hoa | `data-cs-element="moc" data-cs-variant="bamboo"` |
+
+**Why these:** Lumi is conversational spark (plasma). Status Hub is calm status flow (Thủy). Agent Spine is precision infrastructure (Kim·steel). Design System grows everything else (Mộc). Studio brand is Thổ. Delivery is grounded earth (clay). Board collateral is metal precision. HR instruments grow people (bamboo).
+
+## Scope
+
+- **UI kits stay Thổ-faithful.** `ui_kits/status-hub` and `ui_kits/website` remain Thổ recreations; per-element demos live in **Identity Lab** / Storybook Live.
+
+- **Consuming a mapping:** scope the product root with the row's Markup and consume `--cs-accent-*`.
+
+- Tương khắc pairs (Hỏa×Thủy · Kim×Mộc · Thổ×Thủy · Mộc×Thổ · Hỏa×Kim) are never combined as primary + secondary.