@cyberskill/design 2.2.0 → 2.3.1

package/DESIGN.md

@@ -1,6 +1,6 @@
 ---
 name: "CyberSkill Design System"
-version: "2.2.0"
+version: "2.3.1"
 generated: "2026-07-23"
 generator: "scripts/generate-design-md.mjs (npm run build:design-md)"
 sources:
@@ -27,6 +27,10 @@ gate: "_audit/design-md-parity.html (window.__designmd)"
 - **Accessibility floor:** APCA Lc ≥ 75 body text · ≥ 44px touch targets · focus rings never removed · honour `prefers-reduced-motion` / `prefers-contrast`.
 - **Voice:** warm · direct · honest · respectful — all four at once, never "fun/playful/edgy".
 
+### Visual theme, atmosphere & surface pacing
+
+CyberSkill pairs warm architectural craft with optical precision: pages open on Warm Alabaster `--cs-color-surface-page` (`#FFFDF8` light / `#1a1108` dark), elevate content into crisp `--cs-color-surface-panel` (`.cs-card`) or warm `--cs-color-surface-raised` (`.cs-card--raised`), highlight spotlight tiers with `.cs-card--featured` (`--cs-accent-strong` / `--cs-accent` rim), and layer four optical Liquid Glass tiers (`.cs-surface-whisper`, `.cs-surface-light`, `.cs-surface-standard`, `.cs-surface-heavy`) plus `.cs-aurora` hero washes.
+
 ## Colors
 
 Core semantic colours. Dark values are the `[data-theme="dark"]` overrides (the `system` theme mirrors them under `prefers-color-scheme: dark`).
@@ -59,6 +63,12 @@ Core semantic colours. Dark values are the `[data-theme="dark"]` overrides (the
 | `--cs-color-semantic-warning-text` | `#441801` | `#FFD887` |
 | `--cs-color-semantic-info-text` | `#000A75` | `#C7DFFF` |
 
+### Functional color roles
+
+- **Brand & primary actions:** `--cs-color-brand-umber` (`#45210E`) and `--cs-color-brand-ochre` (`#F4BA17`) anchor identity; `--cs-component-button-primary-bg` and `--cs-component-button-primary-fg` drive primary CTAs across light and `[data-theme="dark"]`.
+- **Surface hierarchy & borders:** alternate `--cs-color-surface-page`, `--cs-color-surface-panel`, and `--cs-color-surface-raised` to pace sections; frame containers with `--cs-color-border-default`, internal table/list rules with `var(--cs-color-border-subtle)`, and modal/drawer/tour backdrops with `var(--cs-color-surface-scrim)`.
+- **Text & semantic status pairs:** use `--cs-color-text-primary`, `--cs-color-text-muted`, and `--cs-color-text-accent` for hierarchy (`APCA Lc >= 75` body floor); pair solid status fills (`--cs-color-semantic-success`, `--cs-color-semantic-danger`, `--cs-color-semantic-warning`, `--cs-color-semantic-info`) with `*-fg` tokens and tinted surfaces with `*-text` tokens.
+
 ### Accent roles (Ngũ Hành)
 
 Default accent pack = Thổ (the studio's own element). All 15 element×variant packs and their APCA-derived dark packs live in `tokens/elements.css` and DTCG `$extensions["com.cyberskill"].overrides.elements` / `.elementsDark`.
@@ -152,6 +162,11 @@ Semantic aliases into the ramp — write intent, not magic numbers. `Resolves to
 | `--cs-heading-weight` | `var(--cs-font-weight-bold)` | `700` |
 | `--cs-heading-tracking` | `var(--cs-letter-spacing-tight)` | `-0.01em` |
 
+### Full typography hierarchy & font substitutes
+
+- **Role utility hierarchy (`base/typography.css`):** `.cs-display` (`--cs-text-display` `3.75rem`, weight `800`, line-height `1.15`, tracking `-0.01em`) and fluid `.cs-display--fluid`; `.cs-h1` (`--cs-text-h1` `2.25rem`, weight `800`, line-height `1.35`) and `.cs-h1--fluid`; `.cs-h2` (`--cs-text-h2` `1.875rem`, weight `700`); `.cs-h3` (`--cs-text-h3` `1.5rem`, weight `700`); `.cs-h4` (`--cs-text-h4` `1.25rem`, weight `600`); `.cs-body-lg` (`--cs-text-body-lg` `1.125rem`, line-height `1.5`); `.cs-body` (`--cs-text-body` `1rem`, line-height `1.5`); `.cs-secondary` (`--cs-text-secondary` `0.875rem`); `.cs-caption` (`--cs-text-caption` `0.75rem`); `.cs-eyebrow` (`--cs-text-eyebrow` `0.75rem`, weight `700`, uppercase, tracking `0.08em`); `.cs-mono` (`--cs-font-family-mono`), `.cs-tabular` (`tabular-nums`), and `.cs-prose` (`--cs-prose-measure` `45rem`).
+- **Font substitutes & Vietnamese diacritic safety:** when self-hosted WOFF2 faces are unavailable in external sandboxes, `--cs-font-family-ui` (`Be Vietnam Pro`) falls back to `ui-sans-serif, system-ui, sans-serif` (or `Inter`), `--cs-font-family-display` (`Space Grotesk`) falls back to `'Be Vietnam Pro', ui-sans-serif, system-ui, sans-serif`, and `--cs-font-family-mono` (`JetBrains Mono`) falls back to `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace`; always preserve `--cs-font-line-height-body` (`1.5`) and `--cs-font-line-height-heading` (`1.35`) so stacked Vietnamese diacritics never clip.
+
 ## Spacing & radius
 
 | Token | Value |
@@ -269,6 +284,11 @@ Scoped overrides (distinct from the base token rows):
 | `--cs-icon-md` | `20px` |
 | `--cs-icon-lg` | `24px` |
 
+### Whitespace philosophy, border radius scale & media geometry
+
+- **Whitespace & section rhythm:** separate major page bands with `--cs-space-16` (`64px`) to `--cs-space-24` (`96px`), keep card internal padding at `--cs-space-4` (`16px`) to `--cs-space-6` (`24px`), and cap long-form reading columns with `.cs-prose` (`--cs-prose-measure` `45rem`).
+- **Border radius scale & media geometry (`Shapes`):** `--cs-radius-sm` (`4px`) for `.cs-kbd`, `.cs-code`, and compact tags; `--cs-radius-md` (`8px`) for `.cs-button`, `.cs-field__control`, `.cs-popover__panel`, and `.cs-menu__list`; `--cs-radius-lg` (`14px`) for `.cs-card`, `.cs-dialog`, `.cs-cmdk`, and `.cs-surface-*` glass panels; `--cs-radius-full` (`999px`) for `.cs-badge`, `.cs-tag`, and circular `.cs-avatar`; frame media with `.cs-card__media`, `AspectRatio` (`16:9`, `4:3`, `1:1`), `.cs-image__zoom`, and `.cs-aurora--photo`.
+
 ## Elevation
 
 Shadow values are the raw CSS box-shadow strings from `$extensions["com.cyberskill"].css` (structured DTCG objects carry the same layers). Dark overrides shown.
@@ -306,6 +326,11 @@ Shadow values are the raw CSS box-shadow strings from `$extensions["com.cyberski
 | `--cs-glass-heavy-saturate` | `180%` |
 | `--cs-glass-heavy-opacity` | `90%` |
 
+### Elevation hierarchy (Levels 0–5) & decorative depth
+
+- **Six-level surface & shadow hierarchy:** Level 0 (`--cs-depth-bg` `0`) flat `--cs-color-surface-page` canvas; Level 1 (`--cs-depth-section` `5`) `--cs-color-surface-raised` bands, `.cs-card--flat`, and `.cs-card--raised`; Level 2 (`--cs-depth-card` `10`) default `.cs-card` with `--cs-shadow-xs` / `--cs-shadow-sm` and `.cs-surface-whisper` / `.cs-surface-light`; Level 3 interactive/spotlight `.cs-card--interactive:hover` and `.cs-card--featured` with `--cs-shadow-md` and `.cs-surface-standard`; Level 4 (`--cs-depth-nav` `50`, `--cs-depth-dropdown` `60`, `--cs-depth-overlay` `80`) sticky headers, `.cs-popover__panel`, `.cs-menu__list`, and `.cs-surface-heavy` with `--cs-shadow-lg`; Level 5 (`--cs-depth-modal` `100`, `--cs-depth-toast` `200`) `.cs-dialog`, `.cs-drawer`, `.cs-cmdk`, and `.cs-toast` with `--cs-shadow-xl` over `var(--cs-color-surface-scrim)`.
+- **Decorative depth:** combine warm Umber multi-layer ambient shadows with a `1px` specular inner border (`--_cs-glass-border`) on `.cs-surface-*` panels and radial Ochre/Umber washes on `.cs-aurora` hero bands; under `prefers-reduced-transparency: reduce` or `forced-colors: active`, surfaces fall back to opaque `.cs-surface-solid`.
+
 ## Motion
 
 Calm, purposeful motion; the global `prefers-reduced-motion` safety net reduces animation/transition durations to 0.01ms and disables smooth scrolling at runtime; components can disable animation entirely — these exported values are the real ones (80/120/200/320ms).
@@ -372,6 +397,48 @@ Component-level design decisions (button · textfield). Dark values are theme ov
 | `--cs-component-textfield-padding-x` | `12px` | — |
 | `--cs-component-textfield-min-height` | `44px` | — |
 
+## Static HTML component anatomy (.cs-*)
+
+Static HTML consumers and zero-runtime generators style semantic HTML elements directly with `.cs-*` classes from `styles.css` (or `styles.layered.css`). Interactive state management, keyboard roving, focus trapping and ARIA live announcements require the React components or consumer-supplied scripts; see `docs/static-html-reference.md` for rendered DOM snapshots.
+
+- **Actions & buttons (`base/components.css`):** primary `.cs-button`, variants `.cs-button--secondary`, `.cs-button--tertiary`, `.cs-button--ghost`, `.cs-button--danger`, `.cs-button--danger-ghost`; sizes `.cs-button--xs` (`28px`, `44px` on `pointer: coarse`), `.cs-button--sm` (`36px`, `44px` on `pointer: coarse`), default medium (`44px`), `.cs-button--lg` (`52px`), full-width `.cs-button--full`; states `.is-disabled`, `.is-loading` with `.cs-button__spinner`.
+- **Form controls & fields (`base/components.css`, `base/forms.css`, `base/controls.css`):** field wrapper `.cs-field` with `.cs-field__label`, `.cs-field__control`, `.cs-field__description`, `.cs-field__error` and invalid state `.cs-field.is-invalid`; selection controls `.cs-check`, `.cs-radio`, `.cs-switch` (`.cs-switch__track`); composite inputs `.cs-select`, `.cs-native-select`, `.cs-search` (`.cs-search__clear`), `.cs-stepper`, `.cs-otp`, `.cs-slider`, `.cs-segmented`.
+- **Cards & Liquid Glass surfaces (`base/data.css`, `base/glass.css`):** card container `.cs-card` (modifiers `.cs-card--flat`, `.cs-card--raised`, `.cs-card--featured`, `.cs-card--interactive`; slots `.cs-card__media`, `.cs-card__header`, `.cs-card__title`, `.cs-card__subtitle`, `.cs-card__body`, `.cs-card__footer`); optical glass tiers `.cs-surface-whisper`, `.cs-surface-light`, `.cs-surface-standard` (alias `.cs-glass-card`), `.cs-surface-heavy`, opaque fallback `.cs-surface-solid` (alias `.cs-surface-matte`), and brand hero wash `.cs-aurora` (`.cs-aurora--photo`).
+- **Data display & typography (`base/components.css`, `base/data.css`, `base/typography.css`, `base/collections.css`):** responsive table wrapper `.cs-table-wrap` and `.cs-table` with right-aligned tabular numeric cells `.cs-table__cell--numeric` and subtle row rule `var(--cs-color-border-subtle)`; KPI block `.cs-stat` (`.cs-stat__label`, `.cs-stat__value`, `.cs-stat__delta--up`, `.cs-stat__delta--down`, `.cs-stat__delta--flat`); status pills `.cs-badge` (`.cs-badge--solid`, `.cs-badge--ochre`, `.cs-badge--success`, `.cs-badge--warning`, `.cs-badge--danger`, `.cs-badge--info`, `.cs-badge__dot`) and removable `.cs-tag`; `.cs-avatar` (`.cs-avatar--sm`, `.cs-avatar--md`, `.cs-avatar--lg`, `.cs-avatar--square`, `.cs-avatar-group`); `.cs-kbd`, `.cs-code`, `.cs-dl`; type role classes `.cs-display`, `.cs-display--fluid`, `.cs-h1`, `.cs-h1--fluid`, `.cs-h2`, `.cs-h3`, `.cs-h4`, `.cs-body-lg`, `.cs-body`, `.cs-secondary`, `.cs-caption`, `.cs-eyebrow`, `.cs-mono`, `.cs-tabular`, `.cs-prose`, and opt-in display scope `.cs-display-face`.
+- **Feedback & overlays (`base/feedback.css`, `base/components.css`, `base/shell.css`):** inline banner `.cs-alert` (`.cs-alert--info`, `.cs-alert--success`, `.cs-alert--warning`, `.cs-alert--danger`, `.cs-alert__icon`, `.cs-alert__title`, `.cs-alert__body`, `.cs-alert__dismiss`); toast stack `.cs-toast-stack` and `.cs-toast`; modal `.cs-dialog-layer` with theme-adaptive backdrop `.cs-dialog__overlay` (`var(--cs-color-surface-scrim)`), panel `.cs-dialog` (`.cs-dialog__header`, `.cs-dialog__title`, `.cs-dialog__body`, `.cs-dialog__actions`) and `.cs-alert-dialog` (`.cs-alert-dialog--destructive`); slide-over `.cs-drawer-scrim` and `.cs-drawer` (`.cs-drawer--left`); `.cs-popover` (`.cs-popover__panel`), `.cs-tooltip` (`.cs-tooltip__bubble`), `.cs-progress` (`.cs-progress__fill`), `.cs-spinner`, `.cs-skeleton`.
+- **Navigation, app shell & AI (`base/navigation.css`, `base/shell.css`, `base/ai.css`, `base/controls.css`):** app sidebar `.cs-sidebar` (`.cs-sidebar__label`, `.cs-nav-item`, `.cs-nav-item.is-active`), `.cs-tabs` (`.cs-tab`, `.cs-tab__count`), `.cs-breadcrumb`, `.cs-pagination`, `.cs-menu` (`.cs-menu__list`, `.cs-menu__item`, `.cs-menu__item--danger`, `.cs-menu__sep`), `.cs-steps` (`.cs-step`, `.cs-step--done`, `.cs-step--active`), command palette `.cs-cmdk-scrim` and `.cs-cmdk` (`.cs-cmdk__search`, `.cs-cmdk__list`, `.cs-cmdk__item`); AI surfaces `.cs-prompt`, `.cs-chat-msg`, `.cs-ai-disclosure` (`.cs-ai-disclosure__badge`, `.cs-ai-disclosure__panel`), `.cs-review-gate`, and `.cs-terminal`.
+
+### Signature components & canonical surface examples (ex-*)
+
+- **Signature CyberSkill surfaces:** (1) 4-tier Liquid Glass (`.cs-surface-whisper` to `.cs-surface-heavy`), (2) `.cs-aurora` radial Ochre/Umber hero wash, (3) Trustworthy AI triad (`AIDisclosureBadge` `.cs-ai-disclosure`, `ConfidenceMeter`, `HumanReviewGate` `.cs-review-gate`, `LumiAvatar` `.cs-lumi`), (4) Ngũ Hành 15-pack elemental accents (`data-cs-element`), and (5) 85 bilingual `.dc.html` document templates.
+- **Canonical cross-collection examples (`ex-*`):** `ex-pricing-tier` → `.cs-card` with `.cs-card__header`, `.cs-stat__value.cs-tabular`, and `.cs-button--secondary`; `ex-pricing-tier-featured` → `.cs-card.cs-card--featured` with `.cs-badge--ochre` and primary `.cs-button`; `ex-product-selector` → `.cs-card.cs-card--raised` with `.cs-segmented` and `.cs-check`; `ex-cart-drawer` → `.cs-drawer-scrim` + `.cs-drawer` with `.cs-dl` line items and `.cs-drawer__footer`; `ex-app-shell-row` → `.cs-sidebar` + `.cs-nav-item.is-active`; `ex-data-table-cell` → `.cs-table-wrap` + `.cs-table` + `.cs-table__cell--numeric`; `ex-auth-form-card` → `.cs-card` + `.cs-form` + `.cs-field` + `.cs-button--full`; `ex-modal-card` → `.cs-dialog-layer` + `.cs-dialog__overlay` + `.cs-dialog`; `ex-empty-state-card` → `.cs-card.cs-card--flat` + `EmptyState`; `ex-toast` → `.cs-toast-stack` + `.cs-toast`.
+
+## Layout, grid & responsive strategy
+
+Layouts compose on a `4px` spatial rhythm (`--cs-space-1` to `--cs-space-24`) with container caps (`--cs-container-sm` `640px` through `--cs-container-2xl` `1440px`) and two density scopes (`data-cs-density="comfortable"` default vs `data-cs-density="compact"`). Mark resizable panes or split regions with `.cs-cq` (`container-type: inline-size`) to collapse child grids via `.cs-cq-cols-2`, `.cs-cq-cols-3`, `.cs-cq-cols-4`, `.cs-cq-stack`, and `.cs-cq-hide-narrow` independent of viewport width.
+
+- **Desktop & wide (`> 1024px`, `--cs-breakpoint-lg` / `--cs-breakpoint-xl` `1280px` / `--cs-breakpoint-2xl` `1536px`):** full multi-column grids, persistent `248px` `.cs-sidebar` + `1fr` main workspace, generous sheet padding (`40px+`), and full display typography (`--cs-text-display` `3.75rem`, `--cs-text-h1` `2.25rem`). Fixed-aspect 16:9 decks and social canvases inside `.cs-canvas-desk` preserve authored tracks and scroll horizontally below `1280px` (`min-width: 960px`).
+- **Tablet (`<= 768px`, `--cs-breakpoint-md`):** 3–6 column inline grids collapse to `repeat(2, 1fr)`; `.cs-sidebar` converts from a fixed column into a horizontal wrapping navigation strip; `.cs-table-wrap` and `.cs-table-scroll` scroll horizontally; `.cs-display` steps down to `--cs-font-size-4xl` (`3rem`) and `.cs-h1` to `--cs-font-size-2xl` (`1.875rem`) outside `.cs-canvas-desk` (or scale smoothly when opted into `.cs-display--fluid` / `.cs-h1--fluid`); `.cs-nav-item` and `.cs-search` enforce the `44px` touch height.
+- **Mobile & narrow (`<= 640px` `--cs-breakpoint-sm`, `<= 480px` `--cs-breakpoint-xs`, `<= 360px` reflow floor):** all multi-column content grids collapse to `1fr`; `.cs-dialog` widens to `calc(100vw - 1rem)` at `4vh` (`4dvh` safe-area aware) with full-flex action buttons; `.cs-display` steps down to `--cs-font-size-3xl` (`2.25rem`) and `.cs-h1` to `--cs-font-size-xl` (`1.5rem`); at `<= 360px` (WCAG 1.4.10), `.cs-tabs`, `.cs-pagination`, `.cs-otp`, and `.cs-dl` wrap or scroll without horizontal page overflow while preserving `>= 44px` coarse-pointer targets.
+
+## Guardrails (Do's & Don'ts)
+
+- **Do (Brand & colour):** anchor interfaces on Umber `#45210E` and Ochre `#F4BA17`; use `--cs-color-surface-page`, `--cs-color-surface-panel`, `--cs-color-surface-raised`, `--cs-color-border-default`, `var(--cs-color-border-subtle)`, and `var(--cs-color-surface-scrim)` so light, `[data-theme="dark"]`, `[data-theme="system"]`, `[data-cs-contrast="high"]`, and all 15 Ngũ Hành element packs adapt automatically.
+- **Don't (Brand & colour):** never place body text on mid-tone `--cs-accent` (pair `--cs-accent-strong` with `--cs-accent-on-strong`, or use `--cs-accent-tint` / `--cs-accent-bright` with dark ink), and never hardcode light-only `rgba(69, 33, 14, ...)` borders or `rgba(31, 19, 11, ...)` scrims in component stylesheets.
+- **Do (Typography & Vietnamese localization):** keep `--cs-font-line-height-body` (`1.5`) and `--cs-font-line-height-heading` (`1.35`) so stacked Vietnamese diacritics (`ẫ`, `ệ`, `ự`, `ở`) never clip; apply `.cs-tabular` or `.cs-table__cell--numeric` (`font-variant-numeric: tabular-nums`) on KPIs, prices, timestamps, badges, and pagination counts; ship both EN and VI copy for registered UI strings.
+- **Don't (Typography & Vietnamese localization):** never tighten body line-height below `1.5` or heading line-height below `1.35` on Vietnamese text, never strip diacritics, and never make `--cs-font-family-display` (`Space Grotesk`) the default body font (opt in only for headlines via `.cs-display-face` or `--cs-heading-family`).
+- **Do (Accessibility & motion):** preserve the dual-ring focus indicator (`outline: 2px solid var(--cs-color-text-primary)` + `box-shadow: 0 0 0 5px var(--cs-color-accent-ochre)`), maintain `APCA Lc >= 75` for body text, enforce `>= 44px` hit targets under `@media (pointer: coarse)`, and provide opaque surface fallbacks under `prefers-reduced-transparency: reduce` and `forced-colors: active`.
+- **Don't (Accessibility & runtime boundary):** never remove `:focus-visible` outlines without an ancestor `:focus-within` composite ring, never rely on colour alone to communicate status (always pair semantic colour with an icon, badge text, or border weight), and never claim static `.cs-*` HTML markup alone provides React keyboard navigation, focus trapping, or ARIA state updates.
+
+## Agent prompt guide & starter blueprint
+
+- **Root attributes (`<html>`):** set `lang="vi"` (or `lang="en"`), `data-theme="light"` (`"dark"` | `"system"`), optional `data-cs-element="tho"` (`"kim"` | `"moc"` | `"thuy"` | `"hoa"` | `"tho"`), optional `data-cs-density="comfortable"` (`"compact"`), and optional `data-cs-contrast="high"`.
+- **Runtime selection:** load `styles.css` (or `styles.layered.css`) for static `.cs-*` HTML; import `@cyberskill/design` (`dist/esm/_esm/react.mjs`) for compiled React ESM or `@cyberskill/design/source` (`_esm/react.mjs`) for raw JSX; use `templates/_vendor/support.js` only when previewing `.dc.html` documents.
+- **Prompting checklist for AI generators:** specify (1) target runtime (`static-html` vs `react`), (2) theme and Ngũ Hành element (`data-theme`, `data-cs-element`), (3) bilingual copy pair (`vi` + `en` with full Vietnamese diacritics), (4) responsive container (`max-width: var(--cs-container-xl)` or `.cs-cq`), and (5) tabular numeral alignment (`.cs-tabular` / `.cs-table__cell--numeric`) for metrics and tables.
+- **Quick color & token reference:** Primary brand Umber `#45210E` (`--cs-color-brand-umber`) · Accent Ochre `#F4BA17` (`--cs-color-brand-ochre`) · Page canvas `#FFFDF8` / dark `#1a1108` (`--cs-color-surface-page`) · Panel `#FFFFFF` / dark `#221710` (`--cs-color-surface-panel`) · Raised `#FBF4E9` / dark `#2b1e14` (`--cs-color-surface-raised`) · Default border `#E7D9C6` / dark `#4a3a2c` (`--cs-color-border-default`).
+- **Ready-to-use example prompts:** (1) Hero band: `.cs-aurora` section with `.cs-eyebrow`, `.cs-display--fluid`, `.cs-prose` lead, primary `.cs-button` + `.cs-button--secondary`; (2) SaaS workspace: `.cs-sidebar` + `main` grid with 3-up `.cs-card` / `.cs-card--featured` KPI row (`.cs-stat__value.cs-tabular`) and `.cs-table-wrap` > `.cs-table` with `.cs-table__cell--numeric`; (3) Trustworthy AI review panel: `.cs-card.cs-surface-standard` pairing `.cs-chat-msg`, `.cs-ai-disclosure`, and `.cs-review-gate`.
+- **Iteration guide & known scope boundaries:** modify one component or section band at a time using `--cs-*` custom properties (never raw hex); verify light, `[data-theme="dark"]`, `360px` mobile reflow, and `pointer: coarse` `44px` targets; remember that static `.cs-*` HTML provides visual styling only (interactive keyboard roving, focus trapping, and ARIA live announcements require React components or consumer scripts, and `.dc.html` files require `templates/_vendor/support.js`).
+
 ## Components inventory
 
 107 component files · 125 exports (from `_ds_manifest.json`). Every primary ships `.jsx` + `.d.ts` + `.prompt.md`.

package/README.md

@@ -8,26 +8,27 @@
 
 [![Design System Gates](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml/badge.svg)](https://github.com/cyberskill-official/design/actions/workflows/design-system-gates.yml)
 
+A warm, enterprise-grade, **Vietnamese-first** design system for **CyberSkill** — a Saigon software studio (est. 2020) that turns a clear *wish* into working software. Anchored on **Umber** and **Ochre**, guided by **Lumi** the golden genie, every surface resolves four independent axes: **Theme** (light · dark · system) × **Element** (Ngũ Hành product identity: Kim · Mộc · Thủy · Hỏa · Thổ, 15 variants) × **Language** (EN · VI) × **Style** (`data-cs-style` — sole pack **liquid-glass**; absent ≡ default). Consumers link one file: **`styles.css`**.
+
+---
+
 ## Start here
 
-This is the **entrance document** for the CyberSkill Design System — source checkout VERSION **<!-- cs-source-version:checkout -->2.2.0<!-- /cs-source-version -->** (see `VERSION`; this does not establish registry availability). The **product site** is Storybook at **`/`** on `design.cyberskill.world` (host-only; local: `npm run storybook`). Operator documentation is published in the Storybook **Docs** sidebar (and the Documentation Library at `/docs/viewer.html`). Legacy `/dashboard`, `/dashboard.html`, and `/playground/*` redirect to `/`. One sentence: a warm, Vietnamese-first, enterprise-grade system where every surface resolves four independent axes — **Theme** (light · dark · system) × **Element** (Ngũ Hành product identity: Kim · Mộc · Thủy · Hỏa · Thổ, 15 variants) × **Language** (EN · VI) × **Style** (`data-cs-style` — sole pack **liquid-glass**; absent ≡ default).
+This is the **entrance document** for the CyberSkill Design System — source checkout VERSION **<!-- cs-source-version:checkout -->2.3.1<!-- /cs-source-version -->** (see `VERSION`; this does not establish registry availability). The **product site** is Storybook at **`/`** on `design.cyberskill.world` (host-only; local: `npm run storybook`). Operator documentation is published in the Storybook **Docs** sidebar and the Documentation Library at `/docs/viewer.html` (legacy `/dashboard`, `/dashboard.html`, and `/playground/*` redirect to `/`).
 
-**Quick start by audience**
-- **Designers** — open Storybook (**Foundations / Components / Templates / Pages / Docs**). **Templates** lists all <!-- cs-count:templates -->85<!-- /cs-count --> starting points (Gallery → Atomic View, plus category stories including the 38-document VN A4 suite (Employment Suite + commercial framework) under **Templates → HR**). Flip Theme × Element × Language × Style live via the Storybook toolbar, Atomic View, and the Elements Geometry specimen.
+### Quick start by audience
 
+- **Designers** — open Storybook (**Foundations / Components / Templates / Pages / Docs**). **Templates** lists all <!-- cs-count:templates -->85<!-- /cs-count --> starting points (Gallery → Atomic View, plus category stories including the 38-document VN A4 suite (Employment Suite + commercial framework) under **Templates → HR**). Flip Theme × Element × Language × Style live via the Storybook toolbar, Atomic View, and the Elements Geometry specimen.
 - **Browser template authoring** (static HTTP server) — read `SKILL.md` (runtime routing + design constraints), then the guide below; compose with `styles.css` + compiled ESM `@cyberskill/design` (`dist/esm/_esm/react.mjs`; raw JSX via `@cyberskill/design/source`) / legacy `_esm/cs.mjs` / `_ds_bundle.js` (prefix resolve). The shipped `support.js` interprets `*.dc.html` in a browser; see `docs/template-grammar.md` for grammar and host-only boundaries. Component contracts live beside each component (`.d.ts` + `.prompt.md`).
-
 - **Static / open-spec** (e.g. Google Stitch) — start at **`DESIGN.md`** (generated open-spec) → `llms.txt` → `tokens/tokens.dtcg.json`. Build **static** UI with `styles.css` + `.cs-*` / kitchen-sink / `examples/static-hello/`. Use `.dc.html` through the shipped interpreter or a grammar-aware tool; plain HTML tools consume `.cs-*` or a verified rendered snapshot.
-
-- **Implementers** — published stable npm package **`@cyberskill/design@1.7.2`** (see `docs/consuming.md`; grant in `docs/consumer-grant.md` — still UNLICENSED). **Next/SSR:** `import { Button } from "@cyberskill/design"` (peer React). **Browser demo:** **`examples/npm-hello/`** (Lumi · Hỏa · plasma, legacy `_esm/cs.mjs`). Or link **`styles.css`** from a clone/subtree (one file = everything), or copy a `templates/<slug>/` folder and edit one line in its `ds-base.js` (one-line rebind, validated end-to-end Jul 2026). Scope identity with `data-theme` · `data-cs-element` (+`data-cs-variant`) · `lang`. Release signal: tip SHA + `docs/release-notes.md` (source VERSION is **<!-- cs-source-version:release-signal -->2.2.0<!-- /cs-source-version -->**; no CHANGELOG).
-
+- **Implementers** — published stable npm package **`@cyberskill/design@2.3.0`** (see `docs/consuming.md`; grant in `docs/consumer-grant.md` — still UNLICENSED). **Next/SSR:** `import { Button } from "@cyberskill/design"` (peer React). **Browser demo:** **`examples/npm-hello/`** (Lumi · Hỏa · plasma, legacy `_esm/cs.mjs`). Or link **`styles.css`** from a clone/subtree (one file = everything), or copy a `templates/<slug>/` folder and edit one line in its `ds-base.js` (one-line rebind, validated end-to-end Jul 2026). Scope identity with `data-theme` · `data-cs-element` (+`data-cs-variant`) · `lang`. Release signal: tip SHA + `docs/release-notes.md` (source VERSION is **<!-- cs-source-version:release-signal -->2.3.1<!-- /cs-source-version -->**; no CHANGELOG).
 - **Maintainers** — `docs/doctrine.md` (expansion + verification), then `CONTRIBUTING.md` and `docs/quality-gates.md`.
 
-**Document map — consumers** (also on Storybook **Docs**)
+### Document map — consumers
 
 | Doc | What it answers |
 |---|---|
-| `README.md` (this file, below) | The full guide: anchors, voice, visual foundations, components, templates, index |
+| `README.md` (this file) | The full guide: anchors, voice, visual foundations, components, templates, repository index |
 | `DESIGN.md` | **This repo's** generated open-spec surface (Stitch-style) — doctrine + every token value + inventory, from DTCG; regenerate via `npm run build:design-md`. Do not hand-edit. |
 | `SKILL.md` | Agent entry — runtime routing + design constraints |
 | `docs/consuming.md` | Adopting & upgrading — DC-capable vs static dual path, npm package name, axes, upgrade + extend |
@@ -44,7 +45,7 @@ This is the **entrance document** for the CyberSkill Design System — source ch
 | `docs/figma.md` | Figma / Tokens Studio import recipe for consumers and maintainers |
 | `docs/vi/*.md` | Vietnamese mirror of every operator-facing `docs/*.md` (toggle EN\|VI in `docs/viewer.html`; paired entry translations live under `docs/vi/entrypoints/`) |
 
-**Document map — maintainers** (CI, decisions, gates — not consumer onboarding)
+### Document map — maintainers
 
 | Doc | What it answers |
 |---|---|
@@ -54,24 +55,15 @@ This is the **entrance document** for the CyberSkill Design System — source ch
 | `docs/quality-gates.md` | Benchmark reference — every quality gate, what it asserts, pass criterion, where it runs |
 | `docs/sync.md` | Repo ↔ authoring-environment round-trip fidelity & two-way sync |
 
----
+### Sources & upstream repositories
 
-A warm, enterprise-grade, **Vietnamese-first** design system for **CyberSkill** — a Saigon software studio (est. 2020) that turns a clear *wish* into working software. Anchored on **Umber** and **Ochre**, guided by **Lumi** the golden genie. This project packages CyberSkill's tokens, components, brand assets, and product recreations so any agent can design on-brand artifacts and production UI.
-Consumers link one file: **`styles.css`**.
-
-## Sources
-
-**This repository** (`cyberskill-official/design`) is the design-system source of truth: tokens, React components, brand assets, templates, and gates live here.
-
-Related CyberSkill repos (not in this tree — explore for product/marketing fidelity):
-- **Marketing site** (Next.js, bilingual, Lumi genie, in-repo icon set): https://github.com/cyberskill-official/landing-page
-- **Audit framework** (referenced tooling): https://github.com/cyberskill-official/design-system-audit-framework
-
-**[`DESIGN.md`](DESIGN.md) in this repo** is the generated open-spec surface (Google-Stitch-style: brand doctrine, every token value light + dark, component/template inventory). It is built from `tokens/tokens.dtcg.json` + `_ds_manifest.json` by `npm run build:design-md`. Never edit it by hand; the `design-md-parity` gate pins it byte-for-byte to the token source. It is not a separate upstream doctrine file.
+- **Source of truth:** `cyberskill-official/design` holds all tokens, React components, brand assets, templates, and verification gates.
+- **Generated open-spec:** [`DESIGN.md`](DESIGN.md) is built from `tokens/tokens.dtcg.json` + `_ds_manifest.json` by `npm run build:design-md` (`design-md-parity` pins it byte-for-byte).
+- **Related CyberSkill repos:** Marketing site (`https://github.com/cyberskill-official/landing-page`) and Audit framework (`https://github.com/cyberskill-official/design-system-audit-framework`).
 
 ---
 
-## Anchor immutables (never change these)
+## Anchor immutables
 
 <!-- BEGIN DOCTRINE IMMUTABLES -->
 | Immutable | Value |
@@ -88,15 +80,14 @@ Related CyberSkill repos (not in this tree — explore for product/marketing fid
 
 ---
 
-## CONTENT FUNDAMENTALS
+## Content & voice fundamentals
 
 **Voice is a four-axis chord, sounded all at once:** *warm · direct · honest · respectful.* Never "fun/playful/edgy" — that is explicitly off-brand.
 
-- **Warm, human, second-person.** Speak to "you"; the studio is "we". Lumi speaks as "I". Copy is gentle and encouraging, never corporate. e.g. *"Lovely. What should I call you?"*, *"The lamp is resting for a moment."*
-- **Direct and concrete.** Short sentences, plain outcomes, no hedging. e.g. *"Send a short note. We reply within one business day."*, *"Built to ship, and built to last."*
+- **Warm, human, second-person.** Speak to "you"; the studio is "we". Lumi speaks as "I". Copy is gentle and encouraging, never corporate (e.g. *"Lovely. What should I call you?"*, *"The lamp is resting for a moment."*).
+- **Direct and concrete.** Short sentences, plain outcomes, no hedging (e.g. *"Send a short note. We reply within one business day."*, *"Built to ship, and built to last."*).
 - **Honest about trade-offs.** The brand advertises candour: *"senior, small, and honest about trade-offs."* Risks are stated in words, never hidden or colour-only.
-
-- **Respectful of consent & privacy.** Ask before contacting; promise not to share. e.g. *"Your details go straight to the team. We never share them."*
+- **Respectful of consent & privacy.** Ask before contacting; promise not to share (e.g. *"Your details go straight to the team. We never share them."*).
 - **The "wish" metaphor is the spine.** Products are *wishes*; Lumi (a golden genie) *grants* them by handing them to a real human team. Verbs: *make a wish, grant, shape it, ship, last.* Use it warmly, never gimmicky.
 
 **Casing & mechanics:** Sentence case for headings and buttons (*"Make a wish"*, *"Tell us your wish"*). UPPERCASE + wide tracking only for small eyebrows/labels/table headers. Titles avoid trailing punctuation; body uses full stops. Numerals as digits (*"one business day"* in prose is fine, but *"3 business days"* for concrete SLAs). Em dashes for asides.
@@ -107,43 +98,28 @@ Related CyberSkill repos (not in this tree — explore for product/marketing fid
 
 ---
 
-## VISUAL FOUNDATIONS
-
-**Palette — warm earth, never cold.** Umber `#45210E` grounds everything (it *is* the primary text colour); Ochre `#F4BA17` is the single accent — CTAs on dark, focus rings, highlights, the genie. Surfaces are warm paper: page `#FFFDF8`, panel `#FFFFFF`, raised `#FBF4E9`. Every neutral is warmed toward umber — borders are `#E7D9C6`, muted text `#3F2D21`. Semantic colours (success `#166534`, danger `#B42318`, warning `#92400E`, info `#1D4ED8`) are used sparingly and never as the only signal. **Max one accent per surface** — on core surfaces that accent is Ochre; a *product* may swap in its element accent (see Elemental identity below), never add a second hue beside it. No bluish-purple gradients.
-
-**Typography.** UI: **Be Vietnam Pro** (300–800; a Vietnamese-first Google family) — the default for every surface, headings included. Display/headline: **Space Grotesk** (variable 300–700), the **opt-in** face behind `--cs-font-family-display`; nothing points at it until a scope opts in with `.cs-display-face`, which retargets `--cs-heading-family` and leaves body copy on the UI face. Code/data: **JetBrains Mono**. Display headings are heavy (800 on the UI face; under `.cs-display-face`, Space Grotesk tops out at 700 so 800 clamps within that family), tight tracking (−0.02em); body is 400/500 at 1.5. Uppercase eyebrows at 0.08–0.12em tracking. The size ramp runs xs 12 → 5xl 60 on a 16px base.
-
-**Spacing & layout.** 4px base grid; section padding lives between 64 and 96px; content max-width ~1200–1320px. Generous, calm whitespace.
+## Visual foundations
 
-**Corners & cards.** Radii: sm 4, md 8 (default), **lg 14 (cards/panels)**, full 999 (pills, inputs, chips). A default card = white panel, 1px warm border `#E7D9C6`, 14px radius, soft warm shadow. No coloured-left-border cards.
+- **Palette — warm earth, never cold.** Umber `#45210E` grounds everything (it *is* the primary text colour); Ochre `#F4BA17` is the single accent — CTAs on dark, focus rings, highlights, the genie. Surfaces are warm paper: page `#FFFDF8`, panel `#FFFFFF`, raised `#FBF4E9`. Every neutral is warmed toward umber — borders are `#E7D9C6`, muted text `#3F2D21`. Semantic colours (success `#166534`, danger `#B42318`, warning `#92400E`, info `#1D4ED8`) are used sparingly and never as the only signal. **Max one accent per surface** — on core surfaces that accent is Ochre; a *product* may swap in its element accent, never add a second hue beside it. No bluish-purple gradients.
+- **Typography.** UI: **Be Vietnam Pro** (300–800; a Vietnamese-first Google family) — the default for every surface, headings included. Display/headline: **Space Grotesk** (variable 300–700), the **opt-in** face behind `--cs-font-family-display`; nothing points at it until a scope opts in with `.cs-display-face`, which retargets `--cs-heading-family` and leaves body copy on the UI face. Code/data: **JetBrains Mono**. Display headings are heavy (800 on the UI face; under `.cs-display-face`, Space Grotesk tops out at 700 so 800 clamps within that family), tight tracking (−0.02em); body is 400/500 at 1.5. Uppercase eyebrows at 0.08–0.12em tracking. The size ramp runs xs 12 → 5xl 60 on a 16px base.
+- **Spacing & layout.** 4px base grid; section padding lives between 64 and 96px; content max-width ~1200–1320px. Generous, calm whitespace.
+- **Corners & cards.** Radii: sm 4, md 8 (default), **lg 14 (cards/panels)**, full 999 (pills, inputs, chips). A default card = white panel, 1px warm border `#E7D9C6`, 14px radius, soft warm shadow. No coloured-left-border cards.
+- **Surfaces — Liquid Glass (the default treatment).** Five materials over the anchors: **Whisper** (hero washes), **Light** (nav/sidebar), **Standard** (cards over imagery), **Heavy** (modals/popovers), **Solid** (dense content, tables). Glass = `color-mix` translucency + `backdrop-filter` blur/saturate + a 1px lens-edge gradient. It is **opt-in and additive** — apply a `cs-surface-*` class after checking APCA against the backdrop; dense content stays Solid. Collapses to solid under `prefers-reduced-transparency`, `forced-colors`, print, and unsupported browsers. Surfaces resolve **Theme × Element × Language × Style** independently.
+- **Shadows & depth.** Shadows are warm and umber-tinted (`rgba(69,33,14,…)`), a soft five-step scale from `xs` hairline to `xl` dialog lift. Depth is an explicit z-scale mapped to glass tiers: bg 0 → section 5 → card 10 → nav 50 → dropdown 60 → overlay 80 → modal 100 → toast 200.
+- **Backgrounds & imagery.** Deep-umber darks glow with **warm gold particle light** (`aurora-tho.webp`), never cold or flat — each element carries its own wash (`assets/aurora-{tho,hoa,thuy,moc,kim}.webp`, applied via the `.cs-aurora-wash` overlay class; Thổ's is the official gold). Full-bleed umber sections anchor heroes, careers bands, and footers. The mascot, **Lumi**, is a polished golden genie rendered on transparent backgrounds.
+- **Elemental product identity — Ngũ Hành.** The studio itself is **Thổ/Earth** (Umber + Ochre); each CyberSkill *product* may take one element — **Kim** (metal) · **Mộc** (wood) · **Thủy** (water) · **Hỏa** (fire) · **Thổ** (earth) — via `data-cs-element` (+ `data-cs-variant`, e.g. Hỏa: ember · lava · plasma). Each pack sets the ten **`--cs-accent-*`** role tokens (accent / strong / bright / on / on-strong / tint / ink / glow / grad-a / grad-b) defined in `tokens/elements.css`; inside the scope the element fully takes Ochre's accent roles. Never elemental: semantic statuses, and the **composite focus indicator** (text-primary contour + ochre halo). Mixing follows the cycles: a secondary element may appear only as a gradient endpoint along **Tương sinh** (Mộc→Hỏa→Thổ→Kim→Thủy→Mộc); **Tương khắc** pairs never mix. Product→element mapping lives in `docs/products.md`. Every template carries the Element tweak (`--cs-accent-*`, never raw hex). **Lumi stays golden in every element.**
+- **Motion & interaction states.** Calm durations (120–320ms) with soft decelerate `cubic-bezier(0.2,0,0,1)`; `prefers-reduced-motion` reduces animation and transition durations to 0.01ms and disables smooth scrolling. Hover brightens ~8% (filled) or fills to `surface-raised` (subtle); press nudges 0.5–1px; focus preserves the **composite indicator** (2px text-primary contour + Ochre halo) as specified in `docs/doctrine.md`. Touch targets ≥ 44px on coarse pointers. Transparency & blur appear only on glass surfaces and the hero wish-input.
 
-**Surfaces — Liquid Glass (the default treatment).** Five materials over the anchors: **Whisper** (hero washes), **Light** (nav/sidebar), **Standard** (cards over imagery), **Heavy** (modals/popovers), **Solid** (dense content, tables). Glass = `color-mix` translucency + `backdrop-filter` blur/saturate + a 1px lens-edge gradient. It is **opt-in and additive** — apply a `cs-surface-*` class after checking APCA against the backdrop; dense content stays Solid. Collapses to solid under `prefers-reduced-transparency`, `forced-colors`, print, and unsupported browsers.
-
-**Shadows** are warm and umber-tinted (`rgba(69,33,14,…)`), a soft five-step scale from `xs` hairline to `xl` dialog lift. Never grey, never harsh.
-
-**Depth** is an explicit z-scale mapped to glass tiers: bg 0 → section 5 → card 10 → nav 50 → dropdown 60 → overlay 80 → modal 100 → toast 200.
-
-**Backgrounds & imagery** glow from within: deep-umber darks with **warm gold particle light** (`aurora-tho.webp`), never cold or flat — and each element carries its own wash (`assets/aurora-{tho,hoa,thuy,moc,kim}.webp`, applied via the `.cs-aurora-wash` overlay class; Thổ's is the official gold). Photography is warm-toned. Full-bleed umber sections anchor heroes, careers bands, and footers; on umber, the Ochre slogan and white body carry the message. The mascot, **Lumi**, is a polished golden genie rendered on transparent backgrounds.
-
-**Elemental product identity — Ngũ Hành.** The studio itself is **Thổ/Earth** (Umber + Ochre — the traditional earth-yellow); each CyberSkill *product* may take one element — **Kim** (metal) · **Mộc** (wood) · **Thủy** (water) · **Hỏa** (fire) · **Thổ** (earth) — via `data-cs-element` (+ `data-cs-variant`, e.g. Hỏa: ember · lava · plasma). Each pack sets the ten **`--cs-accent-*`** role tokens (accent / strong / bright / on / on-strong / tint / ink / glow / grad-a / grad-b) defined in `tokens/elements.css`; inside the scope the element fully takes Ochre's accent roles. Never elemental: semantic statuses, and the **composite focus indicator** (text-primary contour + ochre halo) — the studio's accessibility signature on every product. Mixing follows the cycles: a secondary element may appear only as a gradient endpoint along **Tương sinh** (Mộc→Hỏa→Thổ→Kim→Thủy→Mộc); **Tương khắc** pairs never mix. Product→element mapping lives in `docs/products.md`. **Every template carries the Element tweak** — anything that should follow the product's element must consume `--cs-accent-*`, never raw hex. **Lumi stays golden in every element** — the genie is the studio's constant; only the environment re-tints.
-
-**Surface treatment.** Liquid-glass is fixed. Surfaces resolve **Theme × Element × Language × Style** independently.
-
-
-
-**Motion** is calm and purposeful: short durations (120–320ms), a soft decelerate `cubic-bezier(0.2,0,0,1)`, small translate/scale and fades (e.g. the hero mascot's gentle float). No bounce, no flash. Under `prefers-reduced-motion`, the global safety net reduces animation and transition durations to 0.01ms and disables smooth scrolling; individual components can disable animation entirely.
-
-**Interaction states.** Hover: brighten ~8% (filled) or fill to `surface-raised` (subtle). Press: a 0.5–1px nudge. Focus: preserve the **composite indicator** — a 2px text-primary contour plus an Ochre halo, as specified in `docs/doctrine.md`; component rules keep the contour visible when their focus indicator is inset or displayed by a wrapper. Native buttons, ranges, checks and radios retain their browser appearance and an Ochre glow fallback where box shadows are suppressed. Disabled presentation follows each component’s contract. Touch targets ≥ 44px on coarse pointers.
+---
 
-**Transparency & blur** appear only on glass surfaces and the hero wish-input — deliberate, backed by fallbacks — never as decoration.
+## Iconography & brand assets
 
----
+CyberSkill ships **no external icon library**. It uses its own **in-repo line-icon set** (`TASK-DS-010`): each icon is data (a viewBox + primitive paths) rendered through one `<Icon>` component.
 
-## ICONOGRAPHY
+- **Style:** line icons, `currentColor` stroke, 1.75 weight, round caps/joins, 24×24 viewBox — sizes come from `--cs-icon-sm|md|lg` (16/20/24).
+- **Inventory:** `close · sun · moon · arrow-right · check · sparkle · chat · sound-on · sound-off`, extended in v2.0 with `search · sliders · upload · download · calendar · user · plus · trash · external · menu` and in v2.13 with `chevron-down/up/left/right · edit · copy · info · alert-triangle`. `sparkle` is the brand's **"wish"** glyph. **No emoji** and no unicode-glyph icons in product UI.
+- **Master brand artwork:** `assets/` holds `logo-mark.svg` / `logo-mark.png` (official master mark, Umber ground + Ochre genie), `favicon.svg`, `aurora-tho.webp` (`aurora-gold.jpg` kept as a sample still), and `lumi-poster.webp`. **Never recreate, recolour, or approximate the master logo;** for third-party tenants, swap the tenant's own logo.
 
-CyberSkill ships **no external icon library**. It uses its own small **in-repo line-icon set** (from the marketing site, `TASK-DS-010`): each icon is data (a viewBox + primitive paths) rendered through one `<Icon>` component. Style: **line icons, `currentColor` stroke, 1.75 weight, round caps/joins, 24×24 viewBox** — so icons follow the surrounding text token and recolour by setting `color`. Sizes come from `--cs-icon-sm|md|lg` (16/20/24).
-The set: `close · sun · moon · arrow-right · check · sparkle · chat · sound-on · sound-off`, extended in v2.0 with `search · sliders · upload · download · calendar · user · plus · trash · external · menu` and in v2.13 with `chevron-down/up/left/right · edit · copy · info · alert-triangle` (same grammar, marked as extensions). `sparkle` is the brand's **"wish"** glyph. **No emoji** and no unicode-glyph icons in product UI. The one exception to "line icons" is the **brand mark** (`Logo`) and **Lumi** mascot, which are filled artwork.
-Copied assets live in `assets/`: `logo-mark.svg` / `logo-mark.png` (official master mark, Umber ground + Ochre genie), `favicon.svg`, `aurora-tho.webp` (warm gold hero wash; `aurora-gold.jpg` kept as a sample still), `lumi-poster.webp` (the golden-genie mascot). **The logo is the real master file — never recreate, recolour, or approximate it;** for third-party tenants, swap the tenant's own logo.
 ---
 
 ## Components
@@ -178,92 +154,67 @@ Generated from the public source catalog and actual Atomic story AST. **125 expo
 - **Organism** — `Accordion`, `AlertDialog`, `Avatar`, `Badge`, `Button`, `Calendar`, `Carousel`, `Cascader`, `Chart`, `ChatMessage`, `CommandPalette`, `Comment`, `DataGrid`, `DataTable`, `DatePicker`, `Dialog`, `Dock`, `Drawer`, `Editor`, `EmptyState`, `Form`, `FormField`, `FormFieldArray`, `FormWizard`, `HotKeys`, `HumanReviewGate`, `Icon`, `Kbd`, `LocaleProvider`, `Masonry`, `Menubar`, `NavItem`, `NavigationMenu`, `OverlayProvider`, `Pagination`, `Popover`, `PromptInput`, `RadioGroup`, `Result`, `Sidebar`, `Sortable`, `Splitter`, `Terminal`, `TextField`, `TimePicker`, `Timeline`, `Tour`, `Transfer`, `Tree`, `TreeSelect`, `TreeTable`
 <!-- END CATALOG COMPONENT INVENTORY -->
 
-Highlights: **Button** — Umber primary; variants primary/secondary/tertiary/ghost/danger/danger-ghost; sizes xs–lg; loading, icon, fullWidth. **TextField / Textarea / Select / NativeSelect** share one `.cs-field` frame (label + description/error; diacritic/IME-safe). **DataTable** — caption, scoped headers, per-column render, idle/loading/error/empty triad. **Card** — warm panel + header/body/footer. **Logo** renders the exact official mark; **Icon** drives the in-repo line-icon set. The **AI-native** family carries the brand's explainability doctrine — disclosure, human review, wish capture, and confidence, all stated in words (never colour alone).
-
-**Install / package name.** The package name is **`@cyberskill/design`** (source checkout VERSION **<!-- cs-source-version:package-source -->2.2.0<!-- /cs-source-version -->**; grant in `docs/consumer-grant.md` governs *use* — package remains UNLICENSED). Do **not** install `@cyberskill/react` for this tree — that name is historical marketing-site inventory, not this package.
-
-**Source inventory vs. extensions.** An earlier CyberSkill surface shipped six primitives — `Button`, `TextField`, `Dialog`, `DataTable`, `AIDisclosureBadge`, `HumanReviewGate` — plus a brand `Logo`. Everything else in **this** package is an **intentional extension** built in the brand's own token vocabulary so consumers have a complete working kit: `Icon` (the marketing site's real in-repo line-icon set), the standard Forms / Feedback / Data / Navigation / Overlays primitives (search, stepper, slider, file upload, list, description list, timeline, accordion, kbd, code block, sidebar, steps, command palette, popover, drawer, and more), added AI-native pieces (`PromptInput`, `ChatMessage`, `ConfidenceMeter`, `PromptSuggestions`, `TypingIndicator`, `CitationList`) that formalise the Lumi wish-flow, and the `LumiAvatar` mascot. None invent new visual language — they reuse the anchors, surfaces, type, and motion already defined.
+- **Highlights:** **Button** — Umber primary; variants primary/secondary/tertiary/ghost/danger/danger-ghost; sizes xs–lg; loading, icon, fullWidth. **TextField / Textarea / Select / NativeSelect** share one `.cs-field` frame (label + description/error; diacritic/IME-safe). **DataTable** — caption, scoped headers, per-column render, idle/loading/error/empty triad. **Card** — warm panel + header/body/footer. **Logo** renders the exact official mark; **Icon** drives the in-repo line-icon set. The **AI-native** family carries the brand's explainability doctrine — disclosure, human review, wish capture, and confidence, all stated in words (never colour alone).
+- **Install / package name:** The package name is **`@cyberskill/design`** (source checkout VERSION **<!-- cs-source-version:package-source -->2.3.1<!-- /cs-source-version -->**; grant in `docs/consumer-grant.md` governs *use* — package remains UNLICENSED). Do **not** install `@cyberskill/react` for this tree — that name is historical marketing-site inventory, not this package.
+- **Source inventory vs. extensions:** An earlier CyberSkill surface shipped six primitives — `Button`, `TextField`, `Dialog`, `DataTable`, `AIDisclosureBadge`, `HumanReviewGate` — plus a brand `Logo`. Everything else in **this** package is an **intentional extension** built in the brand's own token vocabulary so consumers have a complete working kit: `Icon`, the standard Forms / Feedback / Data / Navigation / Overlays primitives, added AI-native pieces (`PromptInput`, `ChatMessage`, `ConfidenceMeter`, `PromptSuggestions`, `TypingIndicator`, `CitationList`) that formalise the Lumi wish-flow, and the `LumiAvatar` mascot.
 
 ---
 
 ## Templates
 
-Copyable starting points for consuming projects (the **Templates** picker — these replace the old per-component "starting points"). Each lives in `templates/<slug>/` as a Design Component that loads this system via a sibling `ds-base.js`.
+Copyable starting points for consuming projects (`templates/<slug>/`, each loading this system via a sibling `ds-base.js`):
 
 - **Marketing page** (`templates/marketing-page/`) — bilingual landing: umber hero with a `PromptInput` wish box, service cards, process band, Lumi chat launcher.
-
 - **Dashboard** (`templates/dashboard/`) — Status-Hub-style portfolio: KPI `Stat`s, `Tabs` board/table lenses, status cards with `ProgressBar` + `Badge`, and a `DataTable`.
-
 - **Slide deck** (`templates/slide-deck/`) — 16:9 brand deck: umber title + closing, ochre accents, light content layouts.
-
 - **Sign in** (`templates/auth/`) — split auth: umber brand panel + form (`TextField`, `Switch`, `Button`).
-
 - **Settings** (`templates/settings/`) — `Tabs`, form fields, switches, and a danger zone.
-
 - **App shell** (`templates/app-shell/`) — `Sidebar` nav, topbar with `SearchField`, KPI `Stat`s, and a `DataTable`.
-
 - **Article** (`templates/article/`) — long-form post: title, author meta, prose, `Alert` callout, `CodeBlock`.
-
 - **Email** (`templates/email/`) — centred 600px announcement: umber header, ochre CTA, footer.
 
-Every template declares the **Element (Ngũ Hành)** selector (15 variants). The source catalog declares <!-- cs-count:templatesWithBooleanControl -->15<!-- /cs-count --> templates with at least one boolean control and <!-- cs-count:templatesWithoutBooleanControl -->70<!-- /cs-count --> without one; behavior controls vary by template. <!-- cs-count:templatesWithThemeControl -->16<!-- /cs-count --> templates declare a Theme control, while <!-- cs-count:templatesWithoutThemeControl -->69<!-- /cs-count --> do not. These counts describe declared controls; inspect the chosen artifact’s actual states and print behavior. Letter-print business documents remain light-only under the print doctrine.
+Every template declares the **Element (Ngũ Hành)** selector (15 variants). The source catalog declares <!-- cs-count:templatesWithBooleanControl -->15<!-- /cs-count --> templates with at least one boolean control and <!-- cs-count:templatesWithoutBooleanControl -->70<!-- /cs-count --> without one; <!-- cs-count:templatesWithThemeControl -->16<!-- /cs-count --> templates declare a Theme control, while <!-- cs-count:templatesWithoutThemeControl -->69<!-- /cs-count --> do not. Letter-print business documents remain light-only under the print doctrine.
 
 ### Team artifact templates
 
-Branded documents, emails, reports, and decks per department — each a copyable `.dc.html` using design-system tokens, branded markup and selected components. Many documents import only Logo; the markup is not automatically composed from React components. Groups now cover **Tech, Team, HR, Board, Marketing, Culture, Delivery, Legal, Finance, Sales** — the full operations map (coverage research, Jul 2026). Counsel-gated drafts (PIP, board resolution, VN employment contract) ship **banner-marked**: legal/HR review is mandatory before real use.
-
-- **Tech** — `tech-release-notes` (release email), `tech-incident-report` (blameless postmortem: timeline + action table), `tech-rfc` (design doc: proposal, trade-offs, rollout).
+Branded `.dc.html` documents, emails, reports, and decks across **Tech, Team, HR, Board, Marketing, Culture, Delivery, Legal, Finance, Sales** (counsel-gated drafts ship banner-marked):
 
+- **Tech** — `tech-release-notes` (release email), `tech-incident-report` (blameless postmortem), `tech-rfc` (design doc).
 - **Team** — `team-meeting-agenda` (time-boxed items, owners, decisions log, ground rules).
-
-- **HR** — `hr-announcement` (team-news email). *(The offer letter, onboarding checklist, and job description now live in the client-supplied Employment Suite below as `vn-offer-letter`, `vn-onboarding-checklist`, and `vn-job-description`.)*
-- **Board** — `bod-report` (quarterly review: KPI stats, portfolio table, risks, AI-assisted disclosure), `bod-deck` (16:9 board deck — stacked slides, browser print styling and host-dependent PPTX capture), `bod-memo` (one-page exec memo with a single ask).
-
-- **Marketing** — `marketing-campaign-brief` (objective, audience, channels, metrics), `marketing-newsletter` (“The Lamp” issue email), `marketing-launch` (product launch announcement), `marketing-case-study` (result hero, proof stats, quote — print-ready), `marketing-press-release` (dateline, boilerplate, media contact — print-ready).
+- **HR** — `hr-announcement` (team-news email; offer letter, onboarding checklist, and job description live in the Employment Suite as `vn-offer-letter`, `vn-onboarding-checklist`, and `vn-job-description`).
+- **Board** — `bod-report` (quarterly review), `bod-deck` (16:9 board deck), `bod-memo` (one-page exec memo).
+- **Marketing** — `marketing-campaign-brief`, `marketing-newsletter`, `marketing-launch`, `marketing-case-study`, `marketing-press-release`.
 
 ### Business, legal & sales templates
 
-Print-ready letter documents and client decks — the paperwork a studio actually sends. Legal and finance docs are Letter-sized with an `@page` + `@media print` block, so **File → Print / Save as PDF** paginates cleanly with 0.6in margins; on screen they render as a warm sheet on a desk.
-
-- **Legal** — `legal-msa` (master services agreement — the umbrella SOWs hang off: definitions, IP, fees, liability, term), `legal-sow` (statement of work: deliverables & milestone tables, fees, acceptance, sign-off). *(The standalone mutual NDA now lives in the Employment Suite as the client-supplied `vn-mutual-nda`.)*
-- **Finance** — `finance-invoice` (bill-to/from, line items in đồng, VAT, total, bank details), `finance-quote` (scoped estimate with optional add-on, valid-until, accept CTA).
-
-- **Sales** — `sales-one-pager` (leave-behind: umber hero, services, proof stats, the wish process, contact CTA), `sales-proposal-deck` (8-slide 16:9 client proposal — the wish, understanding, approach, scope, timeline, team, investment, next steps).
-
-**Template language is scoped.** The source catalog declares <!-- cs-count:templatesWithLanguageControl -->44<!-- /cs-count --> entries with a Language control and <!-- cs-count:templatesWithoutLanguageControl -->41<!-- /cs-count --> without one. Static stacked documents and switchable content are different contracts. A declared language option does not certify complete or accurate translation; inspect the selected template, its source content and the applicable language checks. Caller-provided content remains the caller's translation responsibility. Legal and finance documents expose Vietnamese text as an **unreviewed draft** where indicated; retain the governing-language warning and obtain content-owner review before real use.
+Print-ready Letter documents (`@page` + `@media print`, 0.6in margins) and client decks:
 
-### Reference documents (govern EVERY template)
+- **Legal** — `legal-msa` (master services agreement), `legal-sow` (statement of work; standalone mutual NDA lives in the Employment Suite as `vn-mutual-nda`).
+- **Finance** — `finance-invoice` (line items in đồng, VAT, total, bank details), `finance-quote` (scoped estimate with accept CTA).
+- **Sales** — `sales-one-pager` (leave-behind), `sales-proposal-deck` (8-slide 16:9 client proposal).
 
-Three suite-wide reference documents define and catalogue the whole template library — legal, HR, finance, sales, client-facing paperwork, and EN-first communications alike. They live in `templates/doc-*/` and print as A4 bilingual documents themselves:
-- **Documents · Style Guide** (`templates/doc-style-guide/`) — the presentation standard: palette, type ramp, bilingual Ink/Slate rule, tables, fill-ins, tick-boxes, signing blocks, data hygiene, header/footer (Articles 1–10 from the recorded client-supplied source; complete current text identity requires source comparison), plus **Article 11 — scope & archetypes**, mapping the A4 rules onto Letter-print, email, product-screen, deck and social archetypes.
+**Template language is scoped.** The source catalog declares <!-- cs-count:templatesWithLanguageControl -->44<!-- /cs-count --> entries with a Language control and <!-- cs-count:templatesWithoutLanguageControl -->41<!-- /cs-count --> without one. Legal and finance documents expose Vietnamese text as an **unreviewed draft** where indicated; retain the governing-language warning and obtain content-owner review before real use.
 
-- **Documents · Suite Index & Usage Guide** (`templates/doc-suite-index/`) — Part I catalogues every template by group (HR suite, legal, finance, sales, product, comms); Part II is the usage guide (employment lifecycle, which documents carry disciplinary force, the eight house presentation rules, and the 8-step “add a new template” workflow).
+### Reference documents (govern every template)
 
-- **Documents · Templates** (`templates/doc-templates/`) — Part A is the blank A4 bilingual shell (header, title block, sample clause, Party A pre-filled / Party B blank, signing block); Part B is the archetype map (A4 · Letter print · email · product screen · deck · social) with an example per family.
+- **Documents · Style Guide** (`templates/doc-style-guide/`) — presentation standard (Articles 1–10) plus **Article 11 — scope & archetypes**.
+- **Documents · Suite Index & Usage Guide** (`templates/doc-suite-index/`) — Part I catalogues every template by group; Part II covers the employment lifecycle, presentation rules, and 8-step template workflow.
+- **Documents · Templates** (`templates/doc-templates/`) — Part A blank A4 bilingual shell; Part B archetype map.
 
 ### HR & Employment Suite (client-supplied)
 
-Thirty-eight bilingual A4 instruments (**thirty-seven** Employment Suite docs supplied by the client, plus **`vn-framework-agreement`** commercial framework) (built on an earlier version of the system) were **converted one-by-one into templates and re-skinned to the latest design system**. The recorded Word-source inventory and retained normalized-text fixtures are described in `docs/hr-suite-sources.md`; the current phrase guard does not establish complete clause identity or current Word-source identity. They live under the **HR Suite** group (`templates/vn-*/`) and follow the house standard set out in the reference documents above: **A4, Vietnamese-first bilingual** (Ink `#1A1614` VN over Slate `#26323A` italic EN pairs), state-motto header, umber table title bars, yellow fill-in blanks, PDPL data-hygiene (Party B always blank), and signing blocks that never split. Every one carries the Element (15) tweaks like all templates; none carries a language tweak (they are inherently bilingual). Because these are client-supplied instruments (keep content verbatim; counsel must review before real use), **`vn-labor-contract` supersedes the earlier fictional `legal-employment-contract`**, and `vn-mutual-nda` / `vn-offer-letter` / `vn-onboarding-checklist` / `vn-job-description` supersede the fictional `legal-nda` / `hr-offer-letter` / `hr-onboarding` / `hr-job-description` (all removed); the remaining fictional templates are EN-first comms (announcements, newsletters, press releases) and client-facing sales/finance paperwork — a different purpose, so they stay.
+Thirty-eight bilingual A4 instruments (**thirty-seven** Employment Suite docs plus **`vn-framework-agreement`** commercial framework) live under `templates/vn-*/` (see `docs/hr-suite-sources.md`). They follow the A4 Vietnamese-first bilingual house standard (Ink `#1A1614` VN over Slate `#26323A` italic EN pairs, state-motto header, umber table title bars, yellow fill-in blanks, PDPL data-hygiene, non-splitting signing blocks). **`vn-labor-contract`** supersedes `legal-employment-contract`, and `vn-mutual-nda` / `vn-offer-letter` / `vn-onboarding-checklist` / `vn-job-description` supersede `legal-nda` / `hr-offer-letter` / `hr-onboarding` / `hr-job-description`.
 
 - **Compensation & rewards** — `vn-total-rewards-appendix`, `vn-phantom-stock`, `vn-salary-scale`, `vn-compensation-regulation`.
-
 - **Policies & regulations** — `vn-internal-labor-regulations`, `vn-disciplinary-schedule`, `vn-performance-evaluation-regulation`, `vn-grassroots-democracy`, `vn-code-of-conduct`, `vn-infosec-policy`, `vn-data-protection-policy`, `vn-remote-work-policy`, `vn-travel-expense-policy`.
-
 - **Hiring & records** — `vn-job-description`, `vn-onboarding-checklist`, `vn-receipt-acknowledgement`, `vn-labour-management-book`, `vn-foreign-employee-pack`, `vn-pdpl-consent`.
-
-- **Performance & requests** — `vn-performance-review-form`, `vn-employee-request` (leave · overtime consent · other).
-
+- **Performance & requests** — `vn-performance-review-form`, `vn-employee-request`.
 - **Outside relationships** — `vn-internship-agreement`, `vn-contractor-agreement`, `vn-sow-appendix`, `vn-mutual-nda`.
+- **Commercial / client framework** — `vn-framework-agreement` (counsel-gated).
+- **Discipline & exit** — `vn-disciplinary-case-file`, `vn-resignation-letter`, `vn-certificate-of-employment`, `vn-training-commitment`.
 
-- **Commercial / client framework (VN A4 skin, not employment)** — `vn-framework-agreement` (Hợp đồng nguyên tắc — software services & account provisioning; specimen Ban QLDA Bình Quới; counsel-gated).
+### Component & archetype coverage maps
 
-- **Discipline & exit** — `vn-disciplinary-case-file` (4-part A→D), `vn-resignation-letter`, `vn-certificate-of-employment` (deliberately neutral), `vn-training-commitment`.
-
-These instruments have recorded client-supplied provenance. The current phrase guard does not establish complete text identity or content-owner acceptance; keep the content as-is and obtain counsel review before real use or source updates.
-
-### Component coverage map
-
-How the templates exercise the component library — every group is covered by at least one starting point:
 | Component group | Exercised by templates |
 |---|---|
 | **Core** (Button, Dialog) | marketing-page · auth · settings · sales-one-pager · finance-quote |
@@ -274,12 +225,7 @@ How the templates exercise the component library — every group is covered by a
 | **AI-native** (AIDisclosureBadge, PromptInput) | marketing-page · bod-report |
 | **Brand** (Logo, Icon, LumiAvatar) | every template |
 
-Raw markup (numbered clauses, invoice tables, milestone rows) in the legal/finance/HR-suite docs is composed from tokens + `.cs-*` type utilities rather than components, by design — these are documents, not app UI. Their frame is defined by the three reference documents (Style Guide · Suite Index & Usage Guide · Templates), not the component library.
-
-### Archetype coverage map
-
-Every template resolves to one of six archetypes, framed by `templates/doc-templates`:
-| Archetype | Frame | Templates |
+| Archetype (`templates/doc-templates`) | Frame | Templates |
 |---|---|---|
 | **A4 bilingual instrument** | State-motto header · Articles · Party A/B tables · signing block; Style-Guide 1–10 in full | the 38 `vn-*` A4 instruments |
 | **Letter print doc** | Letter, 0.6in margins, desk + sheet, clean Print/PDF | `finance-invoice` · `finance-quote` · `finance-expense-report` · `legal-msa` · `legal-sow` · `sales-one-pager` · `bod-*` docs |
@@ -290,7 +236,7 @@ Every template resolves to one of six archetypes, framed by `templates/doc-templ
 
 ---
 
-## Index / manifest
+## Repository layout & UI kits
 
 ```
 styles.css                 ← single entry point (@import manifest only) · checkout version: see VERSION
@@ -315,37 +261,22 @@ thumbnail.html             project tile
 SKILL.md                   Agent-Skills-compatible entry
 ```
 
-The VN A4 source inventory contains <!-- cs-count:vietnameseInstrumentTemplates -->38<!-- /cs-count --> bilingual instruments (`vn-*`), covering the Employment Suite and the commercial framework agreement. Obtain counsel review before real use.
-
-**UI kits** (product recreations, composing the tokens + `.cs-*` classes): **Status Hub** (portfolio dashboard — KPIs, board/table/releases lenses, drawer — plus **sign-in**, **settings**, **project detail**). Live axis demos: Storybook toolbar · Atomic View · Elements Geometry specimen, **cyberskill.world** (bilingual marketing home with Lumi chat — plus **Work**, **Careers**, and a full-page **Lumi assistant**), and a **Brand deck** (16:9, `deck-stage`, browser print and host capture hooks). See each kit's `README.md`.
-
-**Storybook** renders every card: Components (<!-- cs-count:publicExports -->125<!-- /cs-count --> exports — Core, Forms, Data, Feedback, Navigation, Overlays, AI-native, Brand), Foundations (Colors, Type, Spacing, Surfaces, Brand, Motion, Responsive & Bilingual, **Elements**), **Templates** (<!-- cs-count:templates -->85<!-- /cs-count --> starting points from the manifest, including HR Suite / VN A4), **Pages** (Status Hub, Website, Deck), plus Maintainer mirrors for gates.
+- **VN A4 source inventory:** contains <!-- cs-count:vietnameseInstrumentTemplates -->38<!-- /cs-count --> bilingual instruments (`vn-*`), covering the Employment Suite and the commercial framework agreement. Obtain counsel review before real use.
+- **UI kits:** **Status Hub** (portfolio dashboard, sign-in, settings, project detail), **cyberskill.world** (bilingual marketing home with Lumi chat, Work, Careers, Lumi assistant), and **Brand deck** (16:9, `deck-stage`, browser print and host capture hooks). See each kit's `README.md`.
+- **Storybook:** renders Components (<!-- cs-count:publicExports -->125<!-- /cs-count --> exports — Core, Forms, Data, Feedback, Navigation, Overlays, AI-native, Brand), Foundations, **Templates** (<!-- cs-count:templates -->85<!-- /cs-count --> starting points from the manifest), **Pages** (Status Hub, Website, Deck), and Maintainer gate mirrors.
 
 ---
 
+## Substitutions, verification & toolchain
 
-## Substitutions & caveats
-
-- **Fonts:** Be Vietnam Pro (300–800 + italics), Space Grotesk (variable 300–700), and JetBrains Mono are **self-hosted** in `fonts/` as subset-split woff2 (latin · latin-ext · vietnamese) — no CDN dependency. The declared families match the recorded product recreation. `_audit/font-face-integrity.html` checks local WOFF2 sources, subset declarations, manifest parity, a Vietnamese subset per brand family, sample loading and the display-face scope. It does not establish identical rendering to another product, every glyph or exported-file font fidelity.
-
-- **Display face is opt-in, not a second default.** `--cs-font-family-display` (Space Grotesk) exists so a product with a headline face — cyberskill.world / Lumi — consumes a DS token instead of hand-rolling its own `@font-face`. Nothing in the DS points at it: opt a subtree in with `.cs-display-face`. Product → element mappings are unaffected (`docs/products.md` stays locked).
-
-- **Type size ramp & motion tokens** are local conventions layered on the doctrine and are shipped in `tokens/typography.css` and `tokens/motion.css`. The typography source records the family/line-height provenance separately from the local size, weight and icon conventions. The ramp also carries semantic role aliases (`--cs-text-h1`…) and `.cs-h1` / `.cs-body` / … utilities in `base/typography.css`.
-
-- **UI kits are cosmetic recreations** — data is fictional, interactions are shallow, and the marketing site's production 3D/genie layer is not reproduced (the HTML-first base is).
-
-*Welcome. Hiện Thực Hoá Ý Chí.*
-
-Current declared counts and public document roles are generated in [the reference catalog](docs/reference-catalog.json). They describe inventory and source authority, not human acceptance or runtime capability.
-
-The accessibility fixture gate (`_audit/a11y-harness.html`) checks actual accessible names with the pinned local axe engine and an explicit 20-control inventory. `npm run test:a11y-harness` exercises broken names, references, fixtures and audit-engine failures across Chromium, Firefox and WebKit. These checks cover fixture naming and declared CSS rules; screen-reader speech and human acceptance remain separate.
-
-Semantic statuses expose separate fill, paired foreground (`-fg`) and surface-text (`-text`) roles. Use the text role for messages and labels on page/panel/raised surfaces. Fixed white print sheets use an explicit Light scope with their own primary text color; adaptive sheets follow the selected theme.
-
-`--cs-accent-on-strong` is the paired foreground for strong callout fills, with body APCA75 and WCAG4.5 in both modes. The generator targets78; see the contrast report and `test:strong-text-contrast` for their declared scopes.
+- **Self-hosted fonts:** Be Vietnam Pro (300–800 + italics), Space Grotesk (variable 300–700), and JetBrains Mono are self-hosted in `fonts/` as subset-split WOFF2 (latin · latin-ext · vietnamese) — no CDN dependency. `_audit/font-face-integrity.html` checks local WOFF2 sources, subset declarations, manifest parity, Vietnamese subsets, sample loading, and the display-face scope.
+- **Display face is opt-in:** `--cs-font-family-display` (Space Grotesk) is activated only when a subtree opts in with `.cs-display-face` (`docs/products.md` stays locked).
+- **Type ramp, motion & contrast roles:** `tokens/typography.css` and `tokens/motion.css` ship semantic role aliases (`--cs-text-h1`…) and `.cs-h1` / `.cs-body` utilities in `base/typography.css`. Semantic statuses expose separate fill, paired foreground (`-fg`), and surface-text (`-text`) roles. `--cs-accent-on-strong` is the paired foreground for strong callout fills (APCA ≥ 75 body text and WCAG ≥ 4.5 in both modes; generator targets 78, verified by `test:strong-text-contrast`).
+- **UI kits & reference catalog:** UI kits are cosmetic HTML-first recreations with fictional data. Declared counts and public document roles are generated in [the reference catalog](docs/reference-catalog.json).
+- **Accessibility verification:** `_audit/a11y-harness.html` and `npm run test:a11y-harness` check accessible names with the pinned local axe engine across Chromium, Firefox, and WebKit.
 
 <!-- BEGIN PINNED TOOLCHAIN BOOTSTRAP -->
-Before the source-repository `npm ci` or `npm run` commands, use Node >=22.12.0 and run `node scripts/bootstrap-toolchain.mjs` directly. This installs the audited, lockfile-pinned npm11.21.1 fixture with lifecycle scripts disabled; it works from the npm bundled with Node and does not install npm globally. Add `_audit/ci/fixtures/npm-cli/node_modules/.bin` to PATH, or run `node scripts/npm.mjs ci` and use `node scripts/npm.mjs` in place of `npm` for later commands. Source `devEngines` rejects another npm version. Published-package consumers keep their own package manager; this guard is not an installation lifecycle hook. See [validation and toolchain guidance](docs/validation.md).
-
-Trước các lệnh `npm ci` hoặc `npm run` trong kho nguồn, dùng Node >=22.12.0 và chạy trực tiếp `node scripts/bootstrap-toolchain.mjs`. Lệnh cài fixture npm11.21.1 có lockfile đã audit, tắt lifecycle scripts và không cài npm toàn cục. Thêm `_audit/ci/fixtures/npm-cli/node_modules/.bin` vào PATH, hoặc dùng `node scripts/npm.mjs ci`; các lệnh sau dùng `node scripts/npm.mjs` thay cho `npm`. `devEngines` chỉ ràng buộc dự án nguồn; người dùng gói đã phát hành giữ package manager của họ. [Hướng dẫn kiểm tra và toolchain](docs/vi/validation.md).
+Before running source-repository `npm ci` or `npm run` commands, use Node >=22.12.0 and run `node scripts/bootstrap-toolchain.mjs` directly. This installs the audited, lockfile-pinned npm 11.21.1 fixture with lifecycle scripts disabled. Add `_audit/ci/fixtures/npm-cli/node_modules/.bin` to PATH, or run `node scripts/npm.mjs ci` and use `node scripts/npm.mjs` in place of `npm` for subsequent commands (`devEngines` rejects other npm versions in the source repository; published-package consumers keep their own package manager). See [validation and toolchain guidance](docs/validation.md).
 <!-- END PINNED TOOLCHAIN BOOTSTRAP -->
+
+*Welcome. Hiện Thực Hoá Ý Chí.*

package/SECURITY.md

@@ -17,13 +17,13 @@ Please disclose privately via **GitHub Security Advisories** for [`cyberskill-of
 
 | Release line | Security maintenance |
 |---|---|
-| Latest published stable minor, currently **2.0.x** | Security triage and fixes target this line. |
+| Latest published stable minor, currently **2.3.x** | Security triage and fixes target this line. |
 | Earlier stable minor/major lines | Upgrade guidance; no backport commitment. |
 | Unreleased working tree and prereleases | Development evidence; not a supported published release. |
 
-The latest-published snapshot is **2.0.0**, observed at
-`2026-10-30T16:59:22.000Z` from the official npm registry. Snapshot SHA-256:
-`091130f87f852a11a513a03a839d21e7da11ba140134e04ee5d83925d34bcd80`. This is a recorded publication identity, not a live registry query.
+The latest-published snapshot is **2.3.0**, observed at
+`2026-11-06T03:56:00.000Z` from the official npm registry. Snapshot SHA-256:
+`fa7104b11267e27203b0f7fa5e86faa1ff9bdb925f27af194efd375203ed76b3`. This is a recorded publication identity, not a live registry query.
 Refresh the snapshot and this generated block after a separately authorized
 publication; a local VERSION change does not establish publication or support.
 

package/VERSION

@@ -1 +1 @@
-2.2.0
+2.3.1