@cyberskill/design 1.0.0

package/docs/vi/conventions.md

@@ -0,0 +1,114 @@
+# Conventions — authoring CyberSkill DS
+
+Cho người và agent *mở rộng hệ thống này*. (Consumer: đọc `SKILL.md`.) Compiler là nguồn chân lý cho đếm; prose mô tả hình dạng, không bao giờ số.
+
+## Quy tắc expansion
+
+**Khi bất kỳ thứ gì lớn lên, mọi thứ cập nhật trong cùng một change.** Element/variant, icon, component, token role, ngôn ngữ, hoặc pattern template mới phải lan tới: tokens/source → specimen cards (guidelines + card nhóm component) **và trang guideline liên quan** → bộ ba hợp đồng component (`.jsx` + `.d.ts` + `.prompt.md`) → **mọi** template (tweak enum và map) → Storybook Live / Identity Lab → docs (đếm README, SKILL, **và mọi tài liệu liên quan change chạm** — kit README, registry, contrast report regen sau đổi token). **Không bump `VERSION` và không maintain file changelog** — version giữ 1.0.0. Continuity là git history cộng **Release Notes** curated (`docs/release-notes.md` / Storybook). Gate mọi expansion bằng compiler check **và grep enum/list cũ** — không ship nửa lan. Ranh giới phạm vi đã ghi (doctrine, không phải lỗ): trang UI-kit giữ tái tạo Thổ pixel-faithful (trục demo ở Storybook Live và Identity Lab); mọi template bilingual EN·VN và mặc định tiếng Anh (collateral client/media giữ English-primary), và biến thể ngôn ngữ render **tách hoàn toàn** — xem decision log.
+
+## Ba trục
+
+Mọi bề mặt render resolve ba scope trực giao — không bao giờ mã hóa một trục trong trục khác:
+| Trục | Attribute | Sở hữu | Pack sống ở |
+|---|---|---|---|
+| **Theme** | `data-theme="dark\|system"` | đảo light/dark | `tokens/colors.css` |
+| **Element** (Ngũ Hành) | `data-cs-element` + `data-cs-variant` | bản sắc hue theo sản phẩm | `tokens/elements.css` |
+| **Language** | `lang` / Language tweak | copy EN · VI | registry component + props template |
+
+Xử lý bề mặt là liquid-glass (cố định). Bất biến dưới mọi trục: anchors Umber/Ochre, voice, họ chữ, màu semantic status, vòng focus Ochre 3px, sàn APCA, target ≥44px.
+
+## Ngữ pháp đặt tên
+
+- Tokens: `--cs-<layer>-<role>[-<state>]` (`--cs-color-text-muted`). Layer role element: `--cs-accent-*` (hợp đồng 9-token — xem header `tokens/elements.css`).
+
+- Classes: `.cs-<block>[-<part>][--modifier]`. Data attributes: `data-theme`, `data-cs-element`, `data-cs-variant`.
+
+- Files: `tokens/<concern>.css` · `base/<concern>.css` (tên concern, không tên changelog — "interaction", không "refinements2") · `components/<group>/<Name>.{jsx,d.ts,prompt.md}` · `templates/<dept>-<artifact>/` · `guidelines/<group>-<topic>.html`.
+
+- Tên hiển thị template: `<Group> · <Artifact>` ("Finance · Invoice").
+
+## Checklist
+
+**Component mới** — `Name.jsx` + `Name.d.ts` + `Name.prompt.md` trong `components/<group>/`; thêm vào card html của nhóm (resolve namespace bundle **theo prefix** — `const CS = window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]` — không bao giờ hậu tố `…_<projectId>` hardcode); thêm vào dòng nhóm của readme. Chỉ consume token; không hex literal trừ trong `tokens/`.
+
+**Responsive** — reflow là global (`base/responsive.css`, load cuối): media không overflow, print docs nới padding, bảng `.cs-sheet` scroll, `.cs-sidebar` thu gọn, lưới cột cố định inline thu (3+→2 tablet, →1 phone), token dài không gãy (dòng write-on `______`, URL/ID dài) nhận `overflow-wrap: anywhere` trên bề mặt doc để không chống cột phone mở, shell grid app-shell thu một cột với `main{min-width:0}`+`.cs-table-wrap` scroll, và canvas export hình học cố định (`class="cs-canvas-desk"`: decks, social) **luôn** `overflow-x:auto` để slide rộng hơn cửa sổ scroll trong desk thay vì đẩy trang rộng. Đã verify whole-set ở 390 bởi `_audit/responsive-overflow.html` (cả 84 = 0 document overflow). **Hai gotcha cứng:** (1) DC runtime compile `style="…"` inline thành object React, nên attribute render *có khoảng* — mọi selector responsive `[style*=…]` phải khớp `grid-template-columns: repeat(4, 1fr)` (colon-space, comma-space), không bao giờ dạng không-space lúc author; (2) rule CSS global chỉ override property template đặt **inline** qua selector **attribute** (`[style*="grid-template-columns: 248px 1fr"]`) — selector **class** thua inline style. Ưu tiên sửa overflow trong source template (thêm `min-width:0`, `flex-wrap:wrap` inline) hơn đấu inline từ stylesheet.
+
+**Template mới** — `templates/<slug>/<Slug>.dc.html` với `<!-- @template name description -->` đầu tiên; `ds-base.js` giữ single-entry (`styles.css` thôi — rebind một dòng đã validate end-to-end Th7 2026 từ path sâu hơn; scaffold test đã gỡ) và publish alias độc lập-id `window.CyberSkillDS` lúc bundle load, nên mount DS component qua `component-from-global-scope="CyberSkillDS.…"` — **không bao giờ** hậu tố `CyberSkillDesignSystem_<projectId>` hardcode (đổi khi re-import; enforce bởi `_audit/namespace-portability.html`); chỉ inline styles; 1–3 tweaks (không plain copy/color — in-place editing phủ những cái đó); printable docs thêm khối print `@page` + `.cs-desk`/`.cs-sheet` và **không** mang dark tweak (print chỉ light).
+
+**Element variant mới** — ở trong envelope oklch của element; đặt 9 token hợp đồng `--cs-accent-*` cộng `--cs-color-text-accent`/`--cs-color-link` (APCA-check cả hai); aurora wash kế thừa từ element qua `.cs-aurora-wash` (chỉ override class rule nếu variant thật sự cần ảnh riêng); đối tác gradient (`grad-b`) phải theo Tương sinh.
+
+**Ship check** — chạy compiler check đến sạch, rồi chạy `_audit/docs-consistency.html` **và** `_audit/namespace-portability.html` (cả hai phải xanh). Version giữ pin 1.0.0.
+
+## Decision log (owner duyệt)
+
+- Element thay thế hoàn toàn Ochre trong scope sản phẩm; cạnh hot-pink của plasma được duyệt (Th7 2026).
+
+- Trục chỉ Theme × Element × Language. Xử lý bề mặt liquid-glass (cố định).
+
+- Product registry **đã khóa** (Th7 2026) — tám ánh xạ portfolio trong `docs/products.md`; không invent ánh xạ product → element mới.
+
+- Chữ không bao giờ ngồi trên mid-tone `-accent` — mã hóa sau APCA sweep (xem `docs/contrast-report.md`).
+
+- Biến thể ngôn ngữ render **tách hoàn toàn**: đổi Language tweak cho artifact một ngôn ngữ đầy đủ — không dịch dở trong heading, label, helper text, footer, hoặc body. Phần bilingual-by-design duy nhất là lockup tên + slogan CyberSkill (`Hiện Thực Hoá Ý Chí · Turn Your Will Into Real`, dạng chuẩn — không bao giờ một nửa lẻ) và khối identity pháp lý A4 (tên pháp lý công ty + khẩu hiệu nhà nước). Mọi thứ khác đổi theo tweak (Th7 2026).
+
+- **Namespace được resolve, không hardcode** — compiler đặt tên bundle global `window.CyberSkillDesignSystem_<projectId>`, và hậu tố 6-hex dẫn từ project id, nên đổi khi hệ thống import vào project khác. Templates đọc alias ổn định `window.CyberSkillDS` mà `ds-base.js` publish lúc bundle load; cards, trang UI-kit, email standalone, và audit harness resolve theo prefix (`window[Object.keys(window).find(k=>/^CyberSkillDesignSystem_[0-9a-f]{6}$/.test(k))]`). `_ds_bundle.js`/`_ds_manifest.json` và snapshot đóng băng `_audit/exports/` hợp pháp mang hậu tố thật (chúng *định nghĩa* nó). Enforce bởi `_audit/namespace-portability.html`, quét mọi source index bởi manifest — giữ re-import **zero-touch** (Th7 2026).
+
+- Verification dùng harness dev `_audit/` (xem `_audit/README.md`): `responsive-harness.html` (Responsive preview hướng user — **mọi** template ở 390/768/1280), `responsive-overflow.html` (gate horizontal-overflow whole-set ở 390 — **dùng fresh iframe mỗi template; tái dùng một cái race `@import` CSS và cho false positive**), và `vn-overflow.html` (ép VN trên mọi template, đo clip). Force state từ context của chính frame: `__dcSetProps(__dcRootName(), {language:"Tiếng Việt"})`, theme qua `postMessage({type:"__dc_theme",theme:"dark"})`. `_audit/` chỉ-dev — không compile, không card. Không bao giờ truyền value cho `TextField` như **children** (crash React #137 lúc re-render — input là void element); dùng `default-value` (Th7 2026).
+
+## Đường export (theo archetype)
+
+Mọi template export; đường đúng phụ thuộc archetype. Mọi đường giữ Unicode tiếng Việt (đã verify bằng unzip PPTX slide XML và probe standalone bundle — dấu VN sống như text native, xem `_audit/exports/`).
+| Archetype | Đường | Ghi chú |
+|---|---|---|
+| Deck (`*-deck`, `slide-deck`) | **PPTX (editable)** | `gen_pptx` ở 960×540; ép VN từng slide với `showJs: __dcSetProps(__dcRootName(),{language:'Tiếng Việt'})`. Text export như native runs; chỉ Logo là ảnh. |
+| Document (mọi cái có `@page{size:…}`) | **One-click PDF** | Cả 61 doc template mang `<meta name="omelette-owns-print">` trong raw `<head>`, nên engine print trình duyệt paginate chúng ở A4/Letter với chrome-strip `@media print`. Print CSS được scope `@media screen` nơi khác để screen reflow không rò lên giấy. |
+| Email / product page / mọi DC | **Standalone offline HTML** | DC load CSS + bundle động qua `ds-base.js`, mà `super_inline_html` không thấy. Để bundle: tạo bản `*-standalone.html` **cùng thư mục** (giữ `./support.js` relative) với `<link rel="stylesheet" href="../../styles.css">` + `<script src="../../_ds_bundle.js">` **static** trong raw `<head>` (cả hai inline được) thay `ds-base.js`, cộng `<template id="__bundler_thumbnail">`. Nướng ngôn ngữ đích vào props default. Rồi `super_inline_html`. |
+| Bất kỳ | **Editor-native + Claude Code handoff** | Cả project sẵn sàng handoff-dev (compiled bundle + `.d.ts` + `prompt.md` mỗi component); generate package theo request qua handoff skill. |
+
+**Hành vi font lúc export.** Font brand self-host (`Be Vietnam Pro` UI, mono). PPTX giữ **tên** font brand nhưng không embed file — trên máy không có chúng PowerPoint thay fallback (text Unicode VN được giữ; shape có thể reflow nhẹ). Để hand-off tự chứa đầy đủ, hoặc bảo người nhận cài font, hoặc export với swap web-safe (`fontSwaps:[{from:'Be Vietnam Pro',to:'Arial'}]` — Arial phủ tiếng Việt). Standalone HTML **embed** font (`@font-face` inline từ `styles.css`), nên luôn trung thành offline (Th7 2026).
+
+## Accessibility (base/a11y.css + component ARIA)
+
+- **Focus rings có hệ thống** — vòng ochre global `:where(:focus-visible)` trong `base/reset.css`, cộng vòng ochre 3px theo component (`components/forms/navigation/controls`). Không bao giờ đặt `outline: none` trên state `:focus-visible` mà không thay vòng (regression menu-item, đã sửa Th7 2026). Soft glow 5px trong `interaction.css` chồng lên vòng 3px, không thay thế.
+
+- **Touch targets** — `base/a11y.css` đảm bảo 44px trên `@media (pointer: coarse)` (tabs, pagination, menu items, stepper, checkbox/radio; segmented 40px trong track đã pad). Mật độ chuột desktop được giữ. `pointer: coarse` dùng có chủ đích thay breakpoint chiều rộng — touch laptop ở 1280px vẫn cần 44px. Button mang khối coarse riêng trong `components.css`.
+
+- **Reduced motion** — `base/a11y.css` tôn trọng `prefers-reduced-motion: reduce` global (duration animation/transition gần-zero); ngoại lệ cấp component (spinner slow-spin, status pulse tắt) đã có.
+
+- **Ngôn ngữ screen-reader** — mọi template bilingual mang root `lang`: 37 instrument tiếng Việt (`vn-*`) là `lang="vi"` tĩnh; 44 template bilingual có tweak bind `lang="{{ langAttr }}"` với Language tweak (`langAttr = language === "Tiếng Việt" ? "vi" : "en"`, inject vào `renderVals`). Template dual-block thêm bọc mỗi khối `sc-if isVN` trong `<div lang="vi" style="display:contents">` (trung lập layout) để chữ VN được đánh dấu `vi` kể cả chế độ **Both** nơi root là `en` chính. Kết quả: phát âm đúng mọi chế độ ngôn ngữ.
+
+- **Component ARIA đủ** — mọi component tương tác ship role/label đúng (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`+label prev/next; Dialog/Drawer `aria-modal`; Toast `role=status`/`region`; ConfidenceMeter `role=meter`; Accordion `aria-expanded`; Logo `role=img`/`aria-hidden`). Giữ chúng khi compose.
+
+- **Quy tắc API void-element** — component render void element (`<input>`/`<hr>`: TextField, Checkbox, Radio, Switch, SearchField, NumberField, Slider, Divider) destructure `children` khỏi `...props` để child lạc không bao giờ spread lên void element (crash React với #137, bug từng hit `settings`). Nội dung luôn từ props tường minh (`label` / `value` / `defaultValue`), không `children`. Theo khi thêm mọi component dựa input (Th7 2026).
+
+- **Contrast dark-theme** — mọi cặp text/surface pass WCAG AA body (9–15:1). Màu semantic có dark override (`success #4ADE80`, `danger #F87171`, `warning #FBBF24`, `info #7CB2FB`) vì semantic light-theme fail trên bề mặt tối (~2.5:1); verify mọi cặp semantic mới trên `#221710`/`#2b1e14` (toán contrast `_audit/`). Hairline border dark cố ý tinh tế (separator, không biên 3:1) (Th7 2026). **Component tương tác đặt `color`/`border-color: var(--cs-color-brand-umber)` trên bề mặt themeable** (nav-item active, nút secondary/tertiary/ghost, v.v.) PHẢI ship override `[data-theme="dark"]` — umber gần vô hình trên tối; remap sang ochre (nhấn) hoặc `--cs-color-text-primary` (body). Wordmark brand screen-template dùng `--cs-color-text-primary` (không umber hardcode) để flip ở dark; header print-doc giữ umber theo thiết kế. Cột ID/code bảng (ví dụ `R-26-07`) mang `white-space:nowrap` để mã có gạch ngang không word-break trong cột hẹp (Th7 2026, user-reported). Quy tắc umber-trên-bề-mặt-themeable giờ **enforce deterministic** bởi `_audit/contrast-guard.html` (static source lint + ma trận WCAG token-pair ghi điểm light *và* dark) — gate đáng tin mà theme advisory DOM-walk không thể (v2.21.0). Ghi chú: `accent-strong` (role "accent text on light") được APCA-validate nhưng WCAG-borderline (~3.2–4.3) cho vài pack element (tho, tho/sand, thuy/mist, moc/bamboo) — dành cho accent text semibold/large; guard liệt kê chúng advisory và chỉ gate egregious <3.0 (v2.21.1).
+
+## RTL readiness (xác nhận Th7 2026)
+
+Hệ thống **sẵn RTL** — `base/*.css` gần như toàn bộ author bằng CSS **logical properties** (`inline-start`/`inline-end`, `margin-inline`, `padding-block`, `border-inline-*`, `inset-inline-*`), nên đặt `dir="rtl"` mirror layout tự động. Đã verify bằng render kitchen-sink ở `dir="rtl"` — nav, nút, label căn phải, và field/error text mirrored đều flip đúng. Physical props còn lại chỉ cố ý bất biến hướng: centering `left:50%`+`translateX(-50%)` của dialog (đối xứng) và `border-right-color` của spinner (chi tiết visual xoay). Giữ CSS mới logical; dành physical `left`/`right` chỉ cho centering thật sự đối xứng. (Tiếng Việt là LTR, nên RTL không ship trong templates — nhưng nền tảng sẵn cho tenant Arabic/Hebrew.)
+
+## Ảnh thật (image-slot retrofit)
+
+Templates dựa gradient `.cs-aurora-wash` mặc định; để nhận photography **thật**, thả `<image-slot>` vào. Load component một lần mỗi template qua helmet (`<script src="../../image-slot.js"></script>` — path relative tới template) và đặt `<image-slot id="…" shape="rect" style="position:absolute;inset:0;z-index:0">` làm con **đầu** của hero `position:relative`, rồi chồng `.cs-aurora-wash` (z-index:1, `pointer-events:none`) và scrim umber ấm (`linear-gradient(90deg,rgba(42,26,13,.86),rgba(42,26,13,.34))`, z-index:1, `pointer-events:none`) phía trên, content ở z-index:2. Scrim giữ drop-tile trống tinh tế và copy đọc được trên mọi ảnh. Đã verify trong `marketing-case-study`; cùng pattern 4-dòng khớp `marketing-page`, `marketing-social-kit`, `culture-event-invite`, và hero `article` (mỗi cái theo request). Tham chiếu standalone: `templates/image-slots-demo.html`. Slot persist qua sidecar sibling (Th7 2026).
+
+## Typography & locale tiếng Việt (đã verify Th7 2026)
+
+Tiếng Việt là ngôn ngữ chính; hệ chữ xây cho nó — đã verify, không cần đổi:
+- **Line-heights an toàn VN** — token body 1.5 / heading 1.35 / tight 1.15 chừa chỗ cho dấu chồng (dấu trên + nặng dưới). `:where(h1–h6)` mặc định 1.35 + `text-wrap: balance`; `:where(p)` nhận `text-wrap: pretty` (cả hai `base/reset.css`). Templates có thể hardcode line-height chặt hơn (≈1.0–1.15) **chỉ** trên heading hero display một dòng; heading VN nhiều dòng giữ ≥1.15.
+
+- **Định dạng locale** — mỗi ngôn ngữ render convention riêng: **VN** dùng hậu tố `₫`, `DD/MM/YYYY`, hàng nghìn chấm (`1.000.000`); **EN** dùng tiền tố `$`, `DD Mon YYYY`, hàng nghìn phẩy (`1,000,000`). Ngày format Anh chỉ sống trong nhánh Anh — không bao giờ rò vào nhánh VN. Xác nhận bằng scan mọi template.
+
+## Whole-set state audits — language · theme · responsive (mỗi cái một pass riêng, Th7 2026)
+
+Doctrine owner: language, theme, và responsive mỗi cái có pass whole-set RIÊNG; một state sạch không phải bằng chứng cho state khác. Cả ba giờ race-free, manifest-driven, gate pass/fail **all-84** trên cùng pattern — **fresh single-navigation iframe mỗi template** (tái dùng một iframe qua `src` swap race CSS `@import` và cho kết quả sai), state ép qua `__dcSetProps`, settle, rồi đo:
+- **Language** — `_audit/language-overflow.html` — ép `Tiếng Việt`; 0 VN overflow/clip @390; cũng assert VN thật sự áp dụng trên mọi template.
+
+- **Theme** — `_audit/theme-overflow.html` — ép dark; hard gate = dark-applies + 0 dark overflow @390 + 0 fail contrast leaf-text solid-bg mở ngoài `REVIEWED_OK`.
+
+## Theme-overflow contrast là hard gate (Th7 2026)
+
+`theme-overflow.html` fail `window.__theme.pass` trên fail WCAG AA tái lập được cho leaf text trên nền solid đọc được, trừ template trong allowlist `REVIEWED_OK` của trang (hiện: ba canvas deck có eyebrow accent-bright trên accent-strong ~4.22:1 — pack APCA dark vẫn pass; không retune token cho near-miss WCAG body đó). Walker chuyển nền oklab/`color-mix` qua canvas để bề mặt element-pack không bị nhầm với fallback `body` sáng. Gradient / image / wash brand bị skip (không tính được). **CTA đặc trên màn themeable** dùng `background: var(--cs-accent-strong); color: var(--cs-accent-on)` — pack dark đặt `--cs-accent-on` = cream cho `on/strong` (APCA ≥ 75); cream trên `--cs-accent-bright` fail. Print / VN legal light-only vẫn n/a. Proof kèm: `contrast-guard.html`, `apca-dark-preview.html`, `docs/contrast-report.md`.
+
+## Token exports (Th7 2026)
+
+Export token máy đọc được sống trong `tokens/`: `tokens.json` (nhóm theo category + map scope-override), `tokens.js` (ESM), và `tokens.dtcg.json` (**W3C DTCG** — `$value`/`$type`, key CSS-var cho round-trip lossless tới `styles.css`, override dark/system + element + expression dưới `$extensions`; cho Tokens Studio for Figma / Style Dictionary). Cả ba generate từ `tokens/*.css` qua `tokens.json` — regen **cả** sau mọi đổi token (Expansion rule).

package/docs/vi/decisions.md

@@ -0,0 +1,94 @@
+# Quyết định (maintainer)
+
+Các lựa chọn của owner định hình CI, đồng bộ Figma, và phân phối. How-to nằm ở `docs/figma.md` và `docs/ci-cd.md` — file này chỉ là biên bản quyết định. Không phải hướng dẫn consumer.
+
+## 1. Whole-set audits trên mọi PR
+
+**Lựa chọn owner: B — Bật trên mọi PR** (Th7 2026)
+
+`whole-set-audits` chạy trên push, pull_request, schedule (`0 3 * * *`), và `workflow_dispatch`. Dự kiến ~15–20 phút cho job đó.
+
+## 2. Pixel-threshold CI auto-fail
+
+**Lựa chọn owner: bật — hard gate** (Th7 2026)
+
+So sánh `%` pixel Playwright (`_audit/ci/pixel-diff.mjs`) là hard gate. Drift trên ngưỡng làm fail hàng Pixel CI trên board và job CI `pixel-diff` (không `continue-on-error`). Trang review side-by-side visual / component baseline vẫn advisory (drift đánh giá bằng mắt). Sau redesign có chủ đích, làm mới `_audit/baselines/` bằng `--update` và commit các PNG.
+
+## 3. Figma / Tokens Studio
+
+**Lựa chọn owner: A — non-Enterprise hiện tại** (Th7 2026)
+
+Giữ plan Figma hiện tại. Variables REST API chỉ Enterprise — job ghi **soft-skip** (exit 0 + report) khi plan hoặc secret không hoàn tất được write. Soft-skip đó **không** phải sync Variables live — đừng coi CI xanh là chứng minh Figma Variables đã cập nhật. Đồng bộ màu = hand-sync và/hoặc Tokens Studio từ `tokens/tokens.dtcg.json`. Xem `docs/figma.md`.
+
+## 4. Live hub = chỉ Storybook
+
+**Lựa chọn owner: Storybook là live hub duy nhất** (Th7 2026)
+
+- Operator dùng Storybook tại `/` cho Theme × Element × Language và ma trận điều khiển component.
+- Không có trang Live View riêng trong tree.
+- Legacy `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` redirect về `/`.
+- Atomic View portable và HTML tĩnh khác vẫn phục vụ gate zero-build và consumer; chúng không phải entry sản phẩm của site.
+- Bản đồ bề mặt: `docs/live-hub.md`.
+
+## 5. Hai nguồn token JSON
+
+**Lựa chọn owner: giữ cả `tokens.json` và `tokens.dtcg.json`** (Th7 2026)
+
+| File | Vai trò |
+|---|---|
+| `tokens/tokens.dtcg.json` | Interchange W3C DTCG / regen native |
+| `tokens/tokens.json` | Export nhóm theo hướng CSS |
+| `tokens/*.css` + `styles.css` | UI runtime |
+
+## 6. Code Connect — đường đã ship; **hoãn** trên Figma free
+
+**Trạng thái: provisional / soft-skip — không phải publish library live** (Th7 2026; hoãn Th7 2026)
+
+- Job CI `code-connect` + `figma.config.json` + 99 mapping `*.figma.tsx` đã trong repo (snippet import dùng `@cyberskill/design`).
+- Publish soft-skip khi thiếu secret hoặc API trả 403/404/429. Soft-skip ≠ publish Code Connect thành công.
+- **Owner hoãn:** giữ **Figma free / non-Org** — không theo đuổi Code Connect live đến khi có ghế Org/Enterprise và team library đã publish. Khi đó thay stub `9999:*` trong `code-connect/node-map.json` bằng `nodeId` thật. Xem `docs/figma.md`.
+
+## 7. npm publish — đường đã ship; đang mở khóa
+
+**Trạng thái: sẵn sàng vận hành; package chưa có trên registry dưới tên `@cyberskill/design`** (Th7 2026)
+
+- `package.json` là `private: false`; tên package **`@cyberskill/design`** (convention scoped `@cyberskill/*`; `publishConfig.access: public`); `prepublishOnly` chạy `build:bundle` + `build:design-md --check`.
+- Workflow `.github/workflows/npm-publish.yml` trên `workflow_dispatch` / tag `v*`; thiếu `NPM_TOKEN` thì job **soft-skip** (exit 0 + báo cáo tarball). Soft-skip ≠ release đã publish.
+- **Tiến độ owner:** org npm **`@cyberskill`** đã publish package khác; `NPM_TOKEN` đã đặt trên repo. **Vẫn cần:** chạy **Actions → npm-publish → Run workflow** một lần để `@cyberskill/design@1.0.0` lên registry, rồi cấp **grant consumer tường minh** (văn bản chính sách — không phải secret) cho team được phép cài. License giữ **UNLICENSED**; phiên bản giữ **1.0.0**. Xem `docs/consuming.md`.
+
+## 8. Đóng gói store native — scaffold đã ship; submit tắt
+
+**Trạng thái: đường Fastlane live; secret signing do operator sở hữu; không submit store** (Th7 2026)
+
+- Scaffold dưới `examples/native/{swiftui,compose,flutter}/fastlane/` + placeholder metadata listing.
+- Workflow `.github/workflows/native-store.yml`; dry-run luôn; kiểm signed-release cần `ASC_KEY_ID` / `ASC_ISSUER_ID` / `ASC_KEY_P8` / `PLAY_SERVICE_ACCOUNT_JSON`.
+- Lane `upload_store` từ chối submit — sample vẫn là sample đến khi có nhu cầu sản phẩm. Xem `examples/native/README.md`.
+
+## 9. Registry products — đã khóa
+
+**Lựa chọn owner: khóa registry product → element** (Th7 2026)
+
+`docs/products.md` (+ `docs/vi/products.md`) là nguồn chân lý **đã khóa** cho tám ánh xạ portfolio. Agent và kit phải dùng các hàng đó; không invent ánh xạ product → element mới. Mọi thay đổi cần sửa biên bản quyết định này trong cùng change.
+
+## Mặc định roadmap (mở khóa phân phối)
+
+Ghi nhận Th7 2026 — mặc định mở khóa (cập nhật khi bước vận hành xong):
+
+- **Figma Variables** — giữ Tokens Studio / non-Enterprise (quyết định §3). Soft-skip Variables REST vẫn trung thực.
+- **Code Connect** — **bỏ qua khi còn Figma free**; chỉ xem lại sau Org + library đã publish + `nodeId` thật (quyết định §6). Soft-skip ≠ publish.
+- **npm** — org `@cyberskill` + `NPM_TOKEN` sẵn sàng; lần publish đầu `@cyberskill/design` + grant consumer viết tay vẫn do owner chạy (quyết định §7). Soft-skip ≠ release đã publish của *package này*.
+
+## Việc maintainer (đang mở)
+
+Theo dõi vận hành — không phải marketing sản phẩm, không phải backlog công khai:
+
+1. **Code Connect** — hoãn (Figma free). Khi lên Org: thay stub `9999:*` trong `code-connect/node-map.json` bằng node ID library đã publish.
+2. **npm publish lần đầu + grant** — ~~org / `NPM_TOKEN`~~ **xong**. Còn lại: Actions → **npm-publish** → Run workflow; xác nhận `npm view @cyberskill/design`; viết grant consumer cho team được duyệt (xem `docs/consuming.md`).
+
+~~3. Chốt registry products~~ — **xong** (Th7 2026): xem quyết định §9; `docs/products.md` đã khóa.
+
+Schema sidecar và Storybook `FullMatrix` tiếp tục lớn **theo cơ hội** khi primary đã đủ điều kiện (hiện chỉ Button có FullMatrix theo contract) — không phải đợt mass-add. Xem `docs/quality-gates.md`.
+
+## Cách đổi một quyết định
+
+Sửa dòng **Lựa chọn owner** tại đây. Người triển khai nối lại CI và docs liên quan trong cùng một change.

package/docs/vi/deploy.md

@@ -0,0 +1,110 @@
+# Deploy site Atomic live (Vercel / VPS / mọi static host)
+
+Hai track:
+
+1. **Design system portable (consumers)** — vẫn là cây file tĩnh: không cần bundler. Link `styles.css` + tùy chọn `_ds_bundle.js` / ESM. Claude Design, Google Stitch, và product app không cần Node hay Storybook.
+2. **Host site (`design.cyberskill.world`)** — output tĩnh đóng gói cho Vercel. Packaging **có** chạy Node một lần lúc deploy để Storybook ship làm bề mặt sản phẩm tại `/`. Vẫn không có app server chạy dài.
+
+Production **`/`** là build tĩnh Storybook. Legacy `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, và `/playground/:path*` redirect về `/`.
+
+## Vercel (khuyến nghị)
+
+1. Push repo (xem `docs/sync.md`) lên GitHub.
+2. Vercel → **Add New Project** → import repo.
+3. **Framework preset: "Other"** (không Next.js/CRA). Ưu tiên tin `vercel.json` hơn là gõ lệnh trên dashboard.
+4. Deploy. `/` phục vụ Storybook. URL hub/playground cũ 301 về `/`.
+5. Custom domain: Project → Settings → Domains, thêm domain, trỏ DNS theo hướng dẫn Vercel.
+
+**`vercel.json` khóa đường đóng gói host:**
+
+| Field | Value | Why |
+|---|---|---|
+| `framework` | `null` | Không auto-detect framework |
+| `installCommand` | `npm install` | Chỉ-host: cài Storybook/dev tooling cho build sản phẩm tĩnh |
+| `buildCommand` | `npm run build:site` | `build:storybook` rồi `scripts/vercel-static-output.mjs` |
+| `outputDirectory` | `.vercel-static` | Webroot đóng gói (cây portable + Storybook overlay ở root) |
+| `redirects` | `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/` | Nghỉ hub HTML cũ và path Storybook subdirectory |
+
+Tương đương local: `npm install && npm run build:site`, rồi serve `.vercel-static/`.
+
+Consumer clone repo vẫn mở file trực tiếp — họ **không** chạy `build:site`.
+
+## Ảnh social preview (OG)
+
+Ship cho production (`design.cyberskill.world`):
+- Head manager Storybook (`.storybook/manager-head.html`) và stub redirect `dashboard.html` gồm:
+  - `og:image` → `https://design.cyberskill.world/assets/og-dashboard.png`
+  - `twitter:card` = `summary_large_image`
+  - `twitter:image` (cùng URL)
+  - `og:url` / canonical → `https://design.cyberskill.world/`
+
+Nếu host dưới **domain khác**, đổi absolute URL trong các meta tag cho khớp origin, hoặc re-export PNG và giữ path `assets/og-dashboard.png`.
+
+**Misconfig thường gặp:** chọn preset JS framework (Next/CRA) — Vercel chạy đồ thị build sai và có thể 404 root docs. Preset phải giữ **"Other"** và `vercel.json` phải sở hữu install/build/output (xem bảng trên). `package.json` có thể publish (`"private": false`) cho đường npm; nó cũng mang script **chỉ-host** (`build:storybook`, `build:site`, verify/test) mà product app không nên phụ thuộc (xem `docs/consuming.md` và `docs/storybook.md`). Packaging copy webroot portable rồi overlay Storybook tại root `.vercel-static/` (path portable như `/styles.css`, `/_audit/`, `/guidelines/` vẫn cạnh asset Storybook). **Phân biệt misconfig hosting với bug docs thật:** mở `/_audit/docs-consistency.html` trên URL *đã deploy* — gate phát hiện body HTML/error nơi lẽ ra là raw `.md`/`.json` và báo "hosting is intercepting this path".
+
+## VPS generic / nginx / mọi static host
+
+**Không Storybook:** serve root repo làm webroot (chỉ cây portable).
+
+**Có Storybook tại `/`:** chạy `npm run build:site` trên host hoặc CI, rồi serve `.vercel-static/` làm webroot. Cấu hình cùng redirect như `vercel.json` (`/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*` → `/`) nếu host hỗ trợ.
+
+Ví dụ Nginx (`.vercel-static` làm `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 /; }
+}
+Path portable vẫn là file thật (`guidelines/atomic-view.html`, `_audit/run.html`, `styles.css`, v.v.). Storybook sở hữu `/` và `/index.html`.
+
+## Checklist sau deploy
+1. Mở `/` — xác nhận Storybook load (không 404, directory listing, hay shell dashboard cũ).
+2. Mở `/_audit/run.html` — để board chạy xong, xác nhận mọi fast gate pass trên bản *đã deploy* (CDN cache, MIME type, hoặc file thiếu có thể lộ ở đây dù check local sạch).
+3. Nếu có đỏ, đọc hàng gate fail và mở trang gate đó để chi tiết — xem `docs/consuming.md` → "After import — prove health".
+4. Kiểm `/guidelines/atomic-view.html` load trực tiếp (trang nặng nhất — React + compiled bundle qua mạng).
+5. Xác nhận `/dashboard.html` và `/playground/` redirect về `/`, và một story vẫn render (ví dụ Components/Button).
+
+## Việc KHÔNG làm
+- Đừng ép **consumer** qua Storybook hoặc app bundler — hợp đồng của họ vẫn là clone-and-link `styles.css` (+ bundle tùy chọn). Host-site packaging (`build:site`) chỉ cho shell Storybook `/` của site live này và layout package tĩnh.
+- Đừng đổi Vercel framework preset khỏi "Other" / `framework: null`.
+- Đừng gitignore bất kỳ thư mục top-level nào ngoài những gì `.gitignore` đã liệt kê (`uploads/`, `scraps/`, `_audit/exports/`, `storybook-static/`, `.vercel-static/`) — mọi thư mục khác, **kể cả tiền tố underscore như `_esm/`**, là source và phải ship trong cây portable. Xem `docs/sync.md`.
+- Đừng đặt Storybook dưới `/playground/` nữa — `base: '/'` trong `.storybook/main.js` kỳ vọng asset tại domain root.
+
+
+## Protocol re-run Health sau deploy (release gate)
+
+Sau mỗi deploy production:
+2. Mở `docs/viewer.html#README.md` — body không được kẹt ở Loading…
+3. `curl -sS https://<host>/VERSION` phải trả plain semver text, không HTML.
+4. `curl -sS -I https://<host>/package.json` phải là `application/json` hoặc `text/plain`, không SPA shell.
+
+
+## Ghi chú Content-Security-Policy
+
+Static hosting có thể ship CSP chặt. Allowance điển hình cho hệ thống này:
+- `script-src 'self' https://unpkg.com` nếu load React từ CDN cho Atomic View
+- `font-src 'self'`
+
+- `img-src 'self' data:`
+Ưu tiên self-host React cạnh `_ds_bundle.js` cho cài air-gapped.
+
+## OG đa domain
+
+Meta production trỏ `https://design.cyberskill.world/assets/og-dashboard.png`. Trên host khác, chỉ thay absolute origin trong `.storybook/manager-head.html` (và stub `dashboard.html`) `og:image` / `twitter:image` / `og:url` — giữ path `/assets/og-dashboard.png`.
+
+## Bề mặt sản phẩm Storybook (chỉ-host)
+
+Path production: **`/`** (Storybook static export overlay trên `.vercel-static/`).
+
+| Lệnh | Kết quả |
+|---|---|
+| `npm run storybook` | Dev server (chỉ local) |
+| `npm run build:storybook` | Ghi `storybook-static/` với `base: '/'` |
+| `npm run build:site` | Build Storybook + cây portable → `.vercel-static/` (Storybook ở root) |
+
+Xem `docs/storybook.md`. Consumer portable không cần đường này — họ dùng `styles.css` + `_ds_bundle.js` / ESM.

package/docs/vi/design-styles.md

@@ -0,0 +1,25 @@
+# Phong cách thiết kế
+
+Xử lý bề mặt hiện tại là **liquid-glass** (cố định). Các trục styling sống là **Theme × Element × Language** thôi.
+| Trục | Cách đặt | Thay đổi gì |
+|---|---|---|
+| **Theme** | `data-theme="light\|dark"` | màu semantic sáng/tối |
+| **Element** | `data-cs-element` + tùy chọn `data-cs-variant` | bản sắc sản phẩm Ngũ Hành (15 pack) |
+| **Language** | `lang` / Language tweak | bản sao EN · VI |
+
+## Xử lý cố định
+
+- Vật liệu liquid-glass (`cs-surface-*`) là ngôn ngữ bề mặt mặc định.
+
+- Radius, shadow và token kính đến từ hệ base — không phải trục "style pack" song song.
+
+- Từ chối theo doctrine: hue neon/cyberpunk lạnh, memphis vui nhộn, skeuomorphism đầy đủ, emoji trong chrome UI.
+
+## Thêm một look mới
+
+Ưu tiên:
+1. **Element** hoặc **variant** mới khi dịch chuyển là hue/bản sắc.
+2. Composition cục bộ với token/class sẵn có khi dịch chuyển là layout một lần.
+3. Pattern đã ghi trong `docs/conventions.md` + specimen card khi pattern cần tái sử dụng.
+
+Không invent trục sản phẩm thứ tư nếu chưa Expansion Rule qua tokens, Storybook Live, templates, docs và gates.

package/docs/vi/figma.md

@@ -0,0 +1,119 @@
+# Figma / Tokens Studio — ghi chú
+
+## Những gì ship trong repo
+- Design tokens dạng CSS + DTCG (`tokens/tokens.dtcg.json`) kèm mirror native Swift/Kotlin/Flutter.
+- UI kits dưới `ui_kits/` là tái tạo HTML giữ pixel-faithful theo doctrine brand (Identity Lab Thổ-first).
+- Mapping **Code Connect** cho cả **99** public primaries (`components/**/*.figma.tsx` + `figma.config.json` + `code-connect/node-map.json`).
+
+## Công thức import Tokens Studio (hand-sync)
+
+Interchange màu/type/spacing khuyến nghị đến khi org thiết kế lên Figma Enterprise (Variables REST). Nguồn chân lý vẫn **code → design**.
+
+1. Mở file Figma đích (cùng file với `FIGMA_FILE_KEY` khi đã có secrets).
+2. Cài / mở **[Tokens Studio](https://tokens.studio/)** (plugin Figma).
+3. **Import** → chọn **W3C DTCG / JSON** → chọn file repo `tokens/tokens.dtcg.json` (hoặc dán nội dung).
+4. Map token set vào một collection (ví dụ **CyberSkill Tokens**). Ưu tiên giữ key CSS-var / nhóm slash gần với `toFigmaName` của `_audit/ci/push-figma-variables.mjs` (`color/brand/umber`, …) để REST push Enterprise sau này không đổi tên hàng loạt.
+5. Áp token vào local variables / styles trong Figma. Re-import sau token PR — **không** round-trip chỉnh sửa phía design vào DTCG trừ khi cố ý sở hữu thay đổi đó trong code.
+6. Tùy chọn: Style Dictionary / consumer DTCG khác đọc cùng file; mirror native vẫn generate qua `node _audit/ci/generate-native-tokens.mjs`.
+
+**Ghi chú phạm vi:** REST auto-push (bên dưới) chỉ phủ leaf **màu**. Tokens Studio có thể mang spacing/type/shadow từ cùng file DTCG bằng tay.
+
+## Push biến màu tự động
+
+Job CI **`figma-variables-push`** (trong `.github/workflows/design-system-gates.yml`) đọc `tokens/tokens.dtcg.json` và tạo/cập nhật collection biến local Figma **CyberSkill Tokens** với biến màu.
+
+| Trigger | Hành vi |
+|---|---|
+| Push lên `main` | Chạy push (cần secrets) |
+| `workflow_dispatch` | Chạy thủ công từ tab Actions |
+| PR | Không push (tránh nhiễu); dry helpers vẫn có local |
+
+### Secrets (repo → Settings → Secrets and variables → Actions)
+
+| Tên | Giá trị |
+|---|---|
+| `FIGMA_TOKEN` | Figma personal access token với scope **Variables** (và scope Code Connect khi publish mapping) |
+| `FIGMA_FILE_KEY` | File key từ `https://www.figma.com/design/<KEY>/...` |
+
+Phải là **repository secrets** dưới tab Actions (tên đúng, phân biệt hoa thường). Không phải Environment secrets (chỉ inject khi job đặt `environment:`), không Variables, và không org secrets loại trừ repo này. Log CI khi thiếu secret hiện `FIGMA_TOKEN:` / `FIGMA_FILE_KEY:` giá trị rỗng.
+
+**Scope bắt buộc cho Variables push** (từ [Figma scopes](https://developers.figma.com/docs/rest-api/scopes/) + [Variables API](https://developers.figma.com/docs/rest-api/variables/)):
+
+| Scope | Vì sao | Availability |
+|---|---|---|
+| `file_variables:read` | `GET /v1/files/:key/variables/local` | **Chỉ Enterprise** |
+| `file_variables:write` | tạo/cập nhật collection + biến màu | **Chỉ Enterprise** |
+| `file_content:read` / `file_metadata:read` | xác nhận truy cập file trước push | mọi plan |
+
+Nếu hover PAT chỉ thấy scope kiểu `file_content:read`, `file_comments:*`, `webhooks:*`, `library_*` — đó là bình thường trên ghế **Professional / Organization**. Figma **không liệt kê** `file_variables:*` trừ khi account là **Enterprise**. Tạo lại PAT trên plan non-Enterprise không mở được Variables REST API.
+
+**CI làm gì hôm nay:** secrets + mở file chạy trên mọi plan; Variables write soft-skip kèm report khi Figma trả 403 / scope không hợp lệ cho `file_variables` (để gates vẫn xanh). Auto-push đầy đủ cần Enterprise + hai scope đó trên PAT.
+
+**Lựa chọn non-Enterprise:** hand-sync colour styles từ `tokens/tokens.dtcg.json`, hoặc dùng [Tokens Studio](https://tokens.studio/) / Plugin API trong desktop app (đường plugin không dùng job REST này) — xem công thức import ở trên.
+
+### Local
+
+```bash
+# không secrets — chỉ in plan
+node _audit/ci/push-figma-variables.mjs --dry-run
+
+# với secrets trong env (không bao giờ commit)
+export FIGMA_TOKEN=...
+export FIGMA_FILE_KEY=...
+node _audit/ci/push-figma-variables.mjs --check   # truy cập file + list collections
+node _audit/ci/push-figma-variables.mjs           # tạo/cập nhật màu
+```
+
+Sau push thành công, mở file trong Figma → **Local variables** → collection **CyberSkill Tokens**.
+
+### Lấy Figma token ở đâu
+
+1. Đăng nhập [figma.com](https://www.figma.com).
+2. **Settings → Security → Personal access tokens** → generate.
+3. File key: mở file đích; đoạn URL sau `/design/` hoặc `/file/`.
+
+## Figma Code Connect (live + soft-skip)
+
+**Quyết định 1C:** đường publish đã nối; CI **soft-skip** (exit 0 + `code-connect-report.json`) khi thiếu `FIGMA_TOKEN` / `FIGMA_FILE_KEY` hoặc API trả **403 / 404 / 429** (plan, node chưa publish, rate limit).
+
+| Thành phần | Đường |
+|---|---|
+| Config | `figma.config.json` (parser React, `components/**/*.figma.tsx`) |
+| Node registry | `code-connect/node-map.json` (mỗi primary: `nodeId` + cờ `published`) |
+| Mapping | `components/**/<Name>.figma.tsx` — **99** primaries; Button / TextField / Dialog / Card / Alert có prop map; còn lại là stub |
+| Generator | `npm run code-connect:generate` → `_audit/ci/generate-code-connect.mjs` |
+| Job CI | `code-connect` trong `design-system-gates.yml` (PR + `main` + thủ công) |
+| Dry-run local | `npm run code-connect:dry-run` (không secrets; assert config + ≥99 file) |
+
+URL tài liệu dùng file key placeholder **`CS_FIGMA_FILE_KEY`**. Publish thay `FIGMA_FILE_KEY` qua `documentUrlSubstitutions`.
+
+### Checklist operator (lần publish thật đầu tiên)
+
+1. Publish từng Figma component lên **team library** (Code Connect yêu cầu component đã publish; plan Org/Enterprise).
+2. Đặt `nodes.<Name>.nodeId` trong `code-connect/node-map.json` (dạng colon hoặc hyphen) và `published: true`.
+3. `npm run code-connect:generate` để viết lại URL `.figma.tsx`.
+4. Có secrets: `node _audit/ci/code-connect-publish.mjs` (hoặc để job CI chạy trên `main`).
+
+Đến khi có node ID thật, stub tổng hợp `9999:*` vẫn còn; publish báo cáo và thoát sạch trên 404. Blocker còn lại: `docs/decisions.md` §6.
+
+```bash
+npm run code-connect:dry-run
+# với secrets
+export FIGMA_TOKEN=...
+export FIGMA_FILE_KEY=...
+node _audit/ci/code-connect-publish.mjs
+```
+
+## Hand-sync / Tokens Studio (quyết định A của owner — non-Enterprise)
+
+Đường khuyến nghị đến khi org thiết kế lên Enterprise:
+
+1. Coi `tokens/tokens.dtcg.json` là nguồn interchange màu/type/spacing.
+2. **Tokens Studio** (hoặc tương tự): theo công thức import ở trên; chỉ re-export khi cố ý đổi giá trị phía design (ưu tiên hướng code → design).
+3. Bản đồ hand-sync: đường DTCG → tên biến Figma qua cùng naming slash như `_audit/ci/push-figma-variables.mjs` (`toFigmaName`).
+4. Code Connect đã nối live kèm soft-skip (file này) — điền `node-map.json` khi library component tồn tại.
+5. Khi org lên Enterprise, bật lại REST push đầy đủ (bỏ nhu cầu soft-skip) với `file_variables:read` + `file_variables:write` trên PAT.
+
+## Giới hạn phạm vi (thành thật)
+
+Job Variables chỉ push biến **màu** (hex leaves từ DTCG). Spacing, type, và pack multi-mode light/dark chưa auto-sync — dùng Tokens Studio cho những phần đó đến khi sync sau mở rộng job REST.

package/docs/vi/live-hub.md

@@ -0,0 +1,58 @@
+# Live hub = Storybook
+
+## Quyết định
+
+**Storybook là live interactive hub duy nhất** cho operator trên `design.cyberskill.world`. Không có trang Live View riêng và không còn shell dashboard HTML làm sản phẩm. Production **`/`** là Storybook.
+
+## Sidebar IA
+
+| Nhóm | Vai trò |
+|---|---|
+| **Docs** | Hướng dẫn MDX công khai (consuming, deploy, conventions, styles, products, schema, Figma, contrast, voice, axes) |
+| **Foundations** | Colors, typography, spacing, elevation, motion, elements |
+| **Components** | Thư viện CSF đầy đủ |
+| **Release Notes** | Prose sản phẩm curated (**không CHANGELOG.md**) |
+| **Status** | Nhúng full-bleed `_audit/run.html` (auto-run lần đầu; **Re-run** khi cần) |
+| **A11y / I18n** | Specimen a11y + song ngữ |
+| **Maintainer** | Iframe HTML portable cho gates (Atomic View chôn ở đây — không phải entry công khai top-level) |
+
+## Bề mặt
+
+| Bề mặt | Vai trò |
+|---|---|
+| **Storybook** (`/`) | Bề mặt sản phẩm host: toolbar Theme × Element × Language, Docs/Foundations/Components/Release Notes/Status, và Maintainer/* iframe vào HTML portable |
+| **Atomic View** (`guidelines/atomic-view.html`) | Lưới component zero-build portable cho gates và duyệt clone-and-open — không phải entry sản phẩm công khai |
+| **Guidelines / templates khác** | Specimen portable; mở từ Storybook Maintainer/* khi khám phá Motion, Identity Lab, kitchen-sink, v.v. |
+| **Legacy `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, `/playground/:path*`** | Redirect về `/` (stub + redirect Vercel) |
+
+## Bản đồ bề mặt (story Maintainer/*)
+
+| Storybook entry | Portable HTML |
+|---|---|
+| Components/* CSF | Nguồn React dưới `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` |
+
+## Hành vi Status
+
+- Mở Status load `_audit/run.html`, **auto-run** bảng gate nhanh một lần.
+- Storybook có thể giữ iframe cache khi điều hướng đi rồi về — **không** tự chạy lại im lặng.
+- Dùng nút **Re-run** trên board để chạy lại (mỗi gate iframe được cache-bust).
+
+## Consumer portable (không đổi)
+
+Consumer vẫn link `styles.css` / `_ds_bundle.js` / ESM / templates. **Không** yêu cầu Storybook trong product app. Xem `docs/consuming.md`.
+
+## Local
+
+```bash
+npm run storybook          # Storybook sản phẩm tại http://localhost:6006
+npm run build:site         # đóng gói Storybook tại .vercel-static/ (root `/`)
+```

package/docs/vi/products.md

@@ -0,0 +1,26 @@
+# Product registry — ánh xạ element
+
+> **Đã khóa / locked** (Th7 2026). Registry product → element chuẩn cho agent và kit. **Không** invent ánh xạ product → element mới; thêm hoặc đổi hàng chỉ qua quyết định maintainer trong `docs/decisions.md`.
+
+**Nguồn chân lý.** Ánh xạ sản phẩm portfolio CyberSkill sang pack element Ngũ Hành. Một element mỗi sản phẩm; accent phụ chỉ trong gradient wash theo Tương sinh.
+
+| Sản phẩm | Element | Variant | Phụ (Tương sinh) | Markup |
+|---|---|---|---|---|
+| **Lumi** — trợ lý wish | Hỏa · fire | plasma | tho | `data-cs-element="hoa" data-cs-variant="plasma"` |
+| **Status Hub** — portal portfolio khách | Thủy · water | river (mặc định) | moc | `data-cs-element="thuy"` |
+| **CyberOS Agent Spine** — infra agent, memory, gates | Kim · metal | steel | thuy | `data-cs-element="kim" data-cs-variant="steel"` |
+| **CyberSkill Design System** — thư viện này | Mộc · wood | leaf (mặc định) | hoa | `data-cs-element="moc"` |
+| **cyberskill.world** — site studio | Thổ · earth | studio (mặc định) | — | *(không attribute — studio là 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 (mặc định) | thuy | `data-cs-element="kim"` |
+| **HR / employment instruments** | Mộc · wood | bamboo | hoa | `data-cs-element="moc" data-cs-variant="bamboo"` |
+
+**Vì sao:** Lumi là tia hội thoại (plasma). Status Hub là dòng trạng thái bình (Thủy). Agent Spine là hạ tầng chính xác (Kim·steel). Design System nuôi mọi thứ khác (Mộc). Brand studio là Thổ. Delivery là đất vững (clay). Board collateral là kim loại chính xác. HR instruments nuôi người (bamboo).
+
+## Phạm vi
+
+- **UI kits giữ trung thành Thổ.** `ui_kits/status-hub` và `ui_kits/website` vẫn là tái tạo Thổ; demo theo element nằm ở **Identity Lab** / Storybook Live.
+
+- **Dùng một ánh xạ:** scope root sản phẩm bằng Markup của hàng và dùng `--cs-accent-*`.
+
+- Cặp Tương khắc (Hỏa×Thủy · Kim×Mộc · Thổ×Thủy · Mộc×Thổ · Hỏa×Kim) không bao giờ kết hợp primary + secondary.