@cyberskill/design 2.3.1 → 2.5.0

package/DESIGN.md

@@ -1,6 +1,6 @@
 ---
 name: "CyberSkill Design System"
-version: "2.3.1"
+version: "2.5.0"
 generated: "2026-07-23"
 generator: "scripts/generate-design-md.mjs (npm run build:design-md)"
 sources:
@@ -164,7 +164,7 @@ Semantic aliases into the ramp — write intent, not magic numbers. `Resolves to
 
 ### 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`).
+- **Role utility hierarchy (`base/typography.css`):** `.cs-display` (`--cs-text-display` `3.75rem`, weight `800`, line-height `1.15`, `1.22` under `:lang(vi)`, 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
@@ -287,7 +287,7 @@ Scoped overrides (distinct from the base token rows):
 ### 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`.
+- **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`; official logo assets live at `assets/logo-mark.svg`, `assets/logo-mark.png`, `assets/favicon.svg`, and `components/logo/logo-data.js` (no `assets/logos/*` directory).
 
 ## Elevation
 
@@ -404,8 +404,8 @@ Static HTML consumers and zero-runtime generators style semantic HTML elements d
 - **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`.
+- **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, var(--_cs-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, var(--_cs-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-*)
@@ -423,8 +423,8 @@ Layouts compose on a `4px` spatial rhythm (`--cs-space-1` to `--cs-space-24`) wi
 
 ## 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 (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`, and the override-hook fallbacks `var(--cs-color-border-subtle, var(--_cs-border-subtle))` / `var(--cs-color-surface-scrim, var(--_cs-surface-scrim))` so light, `[data-theme="dark"]`, `[data-theme="system"]`, `[data-cs-contrast="high"]`, and all 15 Ngũ Hành element packs adapt automatically; always pair light-mode ink (`#45210E`) with light surfaces (`#FFFDF8` / `#FFFFFF`) and dark-mode cream ink (`#f5ead9`) with dark surfaces (`#1a1108` / `#221710`).
+- **Don't (Brand & colour):** never place body text on mid-tone `--cs-accent` (pair `--cs-accent-strong` with `--cs-accent-on-strong`, and `--cs-accent-bright` with `--cs-accent-on`), never mix dark ink onto un-themed light parent wrappers, 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`.

package/README.md

@@ -14,14 +14,14 @@ A warm, enterprise-grade, **Vietnamese-first** design system for **CyberSkill**
 
 ## Start here
 
-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 `/`).
+This is the **entrance document** for the CyberSkill Design System — source checkout VERSION **<!-- cs-source-version:checkout -->2.5.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 `/`).
 
 ### 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@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).
+- **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.5.0<!-- /cs-source-version -->**; no CHANGELOG).
 - **Maintainers** — `docs/doctrine.md` (expansion + verification), then `CONTRIBUTING.md` and `docs/quality-gates.md`.
 
 ### Document map — consumers
@@ -155,7 +155,7 @@ Generated from the public source catalog and actual Atomic story AST. **125 expo
 <!-- 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.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.
+- **Install / package name:** The package name is **`@cyberskill/design`** (source checkout VERSION **<!-- cs-source-version:package-source -->2.5.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 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.
 
 ---

package/VERSION

@@ -1 +1 @@
-2.3.1
+2.5.0