@cyberskill/design 2.7.0 → 2.9.0

package/docs/UPSTREAM.md

@@ -16,15 +16,12 @@ Verified live in browser: **69/69** `D1`–`D10` checks (`10.0 / 10`), **64/64**
 | `components/feedback/feedback.card.html` | `.frame { flex: 1 1 100%; min-width: 0 }` | Prevents the toast demo frame from collapsing to zero width inside the flex row. |
 | `components/logo/logo.card.html` | Lockup wordmark `color: var(--cs-color-text-primary)`. | Ensures the wordmark remains visible in dark mode. |
 
-## 2 · Shipped verification suite (`audit/`)
+## 2 · Automated verification suite (`_audit/ci/`)
 
 | File | Purpose |
 |---|---|
-| `audit/v2.5.0-verification.html`, `audit/verify-v2.5.0.js`, `audit/fixture-v2.5.0.html` | Verification Audit & Specimen Workbench: 10 dimensions (`P0` tint safety · `P1` 32-scope WCAG 1.4.11 · `P2` Umber separation, 14-control invalid parity, VI diacritics · `P3` nested glass, `DESIGN.md`/asset contract · `D8`–`D10` Doctrine Immutables: dual-ring focus, ≥ 44px touch targets & motion safety, high-contrast, density & semantic status contrast), 69 checks × `v2.5.0+` / `v2.4.0` / `v2.3.1`, 32×6 contrast matrix, edge-case report, JSON export, and specimen switcher (`version × theme × element × variant`). |
-| `audit/v2.5.0-verification.json`, `_audit/ci/verify-audit-benchmarks-browser.mjs` | Machine-readable receipt and automated CI/prepublish non-regression gate (`npm run test:audit-regression`): **10.0 / 10** (`69/69` across `D1`–`D10`), embedded baseline suite **64/64** (`v2.4.0` tag `62/64`, `v2.3.1` `8/64`), render health **146/146**, and **0 watch** items. |
-| `audit/render-health.html` | Loads all 146 templates, component cards, and UI-kit/guideline pages in hidden frames (as authored / forced dark / high-contrast / any Ngũ Hành scope) and verifies zero unstyled, unresolved, erroring, empty, or low-contrast pages. |
-| `audit/fixture.html`, `audit/verify.js`, `audit/v2.4.0-verification.html` | Three-version loader (`?v=current|v240|baseline`) re-running the 64 baseline checks across `v2.5.0`, `v2.4.0`, and `v2.3.1`. |
-| `audit/baseline-2.4.0/styles.flat.css`, `audit/baseline-2.3.1/styles.flat.css` | Flattened `styles.css` closures from tags `v2.4.0` and `v2.3.1` for live three-version comparison. |
+| `_audit/ci/verify-audit-benchmarks-browser.mjs`, `_audit/ci/lib/benchmark-checks.mjs` | Automated CI/prepublish live-browser benchmark gate (`npm run test:audit-regression`): scores **10.0 / 10** (`129/129` across 20 dimensions `D1`–`D20`), core baseline suite **64/64** (`10.0 / 10`), 192/192 cells in the 32×6 non-text contrast matrix (`≥ 3.0:1`), 3/3 Generation-2 complex stress-test screens, and **0 watch** items. |
+| `_audit/ci/fixtures/benchmark-20d.html`, `_audit/ci/fixtures/benchmark-baseline.html`, `_audit/ci/fixtures/benchmark-gen2.html` | Current-tree DOM fixtures exercising 32 Theme × Element × Variant scopes, 14 form controls, Vietnamese diacritic metrics, container queries, print/glass rules, and complex multi-scope enterprise/AI/mobile screens against `/dist/styles.css` and `/styles.css`. |
 
 ## 3 · Host-specific items excluded from upstream
 

package/docs/benchmark-rubric.md

@@ -28,7 +28,7 @@ Self-audit checklist for evolving CyberSkill Design System — external standard
 
 ## Style expansion checklist (`data-cs-style`)
 
-Sole pack today: **liquid-glass** (`tokens/styles.css`, gate `_audit/style-contract.html`). When adding a style pack beyond liquid-glass:
+Live packs: **liquid-glass** (default; absent ≡ default) and **matte-paper** (`tokens/styles.css` + `base/glass.css`, gate `_audit/style-contract.html`). When adding another style pack:
 
 1. Token overlay that **consumes** the existing 10 `--cs-accent-*` roles, including `--cs-accent-on-strong` (do not invent parallel Element packs).
 2. Specimen card + Storybook / Atomic View wiring if the style is product-selectable.

package/docs/browser-support.md

@@ -4,7 +4,7 @@ The supported web target is the latest two stable releases of Chrome, Firefox, S
 
 ## Required capabilities
 
-The system uses `color-mix(in oklab, ...)`, inline-size container queries, `:has()`, `text-wrap: balance` and native `inert`. These features predate the selected floor in the [pinned MDN browser compatibility data](https://github.com/mdn/browser-compat-data/tree/12bc0268c7fe89a4b23fab5c54702c1fb9c34f7a). The retained source record is `_audit/remediation/browser-compatibility-source.json`. No legacy-browser fallback or `inert` polyfill is promised.
+The system uses `color-mix(in oklab, ...)`, inline-size container queries, `:has()`, `text-wrap: balance` and native `inert`. These features predate the selected floor in the [pinned MDN browser compatibility data](https://github.com/mdn/browser-compat-data/tree/12bc0268c7fe89a4b23fab5c54702c1fb9c34f7a). The retained source record is `_audit/ci/fixtures/browser-compatibility-source.json`. No legacy-browser fallback or `inert` polyfill is promised.
 
 For the selected latest-two stable floor, native `inert` is available and no `inert` polyfill is required. Its introduction versions are Chrome 102 ([Chrome release notes](https://developer.chrome.com/blog/new-in-chrome-102)), Firefox 112 ([Mozilla developer release notes](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/112)), and Safari 15.5 on macOS, iOS and iPadOS ([WebKit release notes](https://webkit.org/blog/12669/new-webkit-features-in-safari-15-5/)); the [HTML Standard](https://html.spec.whatwg.org/multipage/interaction.html#the-inert-attribute) documents the native behavior. This is a feature-availability conclusion for the declared floor, not certification of every admitted browser release, physical-device focus behavior or assistive-technology behavior. Older targets remain outside this promise and need a separately validated fallback.
 

package/docs/component-api.md

@@ -8,7 +8,7 @@ Removing a public contract requires a major release **and both** at least two di
 
 The authored `components/release-compatibility.json` records the pre-candidate baseline, reviewed pending change classifications, dated notices and publication evidence. Release planning, prepared-candidate verification and tag verification enforce it alongside the unchanged support-approval and exact-source gates. The approved compiled-default entry, APG Menu keyboard, SegmentedControl radio default and default floating placement changes are classified as breaking for the current unreleased revision; patch/minor preparation is blocked. This does not assign a new release identifier, approve support evidence, create a tag or authorize publication. Before a later release cycle, reconcile the baseline and pending entries against the actual accepted publication; never silently clear notice history.
 
-SegmentedControl retains deprecated semantic aliases `role="tablist"` and `role="radiogroup"`. When `mode` is omitted, the alias selects matching tab or radio children; explicit `mode` takes precedence, and the default remains radio. Other role values reject rather than producing mismatched ARIA semantics. Prefer `mode="tabs"` or `mode="radio"`. The earlier removal proposal is archived in `_audit/remediation/segmented-role-removal-proposal-history.json`; it is not a current removal. Rejecting arbitrary roles remains classified as breaking. Announcement fields remain null: this local guidance does not establish a published notice, date or version. Any future removal still requires a major release after two distinct published minor releases and 90 days of recorded notice, alongside all other release gates.
+SegmentedControl retains deprecated semantic aliases `role="tablist"` and `role="radiogroup"`. When `mode` is omitted, the alias selects matching tab or radio children; explicit `mode` takes precedence, and the default remains radio. Other role values reject rather than producing mismatched ARIA semantics. Prefer `mode="tabs"` or `mode="radio"`. The earlier removal proposal is archived in `_audit/ci/fixtures/segmented-role-removal-proposal-history.json`; it is not a current removal. Rejecting arbitrary roles remains classified as breaking. Announcement fields remain null: this local guidance does not establish a published notice, date or version. Any future removal still requires a major release after two distinct published minor releases and 90 days of recorded notice, alongside all other release gates.
 
 The currently declared React support lines are 18.x and 19.x; packed-consumer and hydration fixtures test their pinned versions. This is a major-version support window, not proof of every historical patch or a promise about unreleased React majors. Removing a declared line follows the same major-release and deprecation policy. New React majors require explicit compatibility validation before widening peer ranges. Browser targets remain the latest-two policy in the browser-support guide, with engine and physical-device evidence reported separately.
 

package/docs/consuming.md

@@ -1,6 +1,6 @@
 # Consuming & upgrading the CyberSkill Design System
 
-**Source checkout:** VERSION **<!-- cs-source-version:checkout -->2.7.0<!-- /cs-source-version -->** is local source identity, not a registry-availability claim. For an unpublished candidate, validate the reviewed local package tarball or source checkout. Registry commands below refer to published stable 2.6.0 (and the dated ADOPT-001 1.7.2 sibling inventory) and are not automatically updated by preparation. Preparation does not authorize publication.
+**Source checkout:** VERSION **<!-- cs-source-version:checkout -->2.9.0<!-- /cs-source-version -->** is local source identity, not a registry-availability claim. For an unpublished candidate, validate the reviewed local package tarball or source checkout. Registry commands below refer to published stable 2.8.0 (and the dated ADOPT-001 1.7.2 sibling inventory) and are not automatically updated by preparation. Preparation does not authorize publication.
 
 How any project — human-driven or agent-driven — adopts this HTML-first design system, and how to take updates safely. Published on Storybook **Docs** at `design.cyberskill.world`.
 

package/docs/contrast-report.md

@@ -1,6 +1,6 @@
 # Contrast report — elemental pairings (APCA)
 
-Generated · sweep at VERSION 2.7.0.
+Generated · sweep at VERSION 2.9.0.
 
 Published on Storybook **Docs** at `design.cyberskill.world`.
 
@@ -104,10 +104,10 @@ Rows use the declared light or dark `--cs-color-link` colour. White, reference-p
 | tho · sand | link on tint (body) | #695300 / #FEF8E7 | 6.98:1 | ✓ |
 | tho · sand | link on reference raised cream (body) | #695300 / #FBF4E9 | 6.77:1 | ✓ |
 | tho · sand | link on reference dark panel (body) | #F9E5AE / #221710 | 14.06:1 | ✓ |
-| tho | link on white (body) | #644A05 / #FFFFFF | 8.32:1 | ✓ |
-| tho | link on reference page (body) | #644A05 / #FFFDF8 | 8.19:1 | ✓ |
-| tho | link on tint (body) | #644A05 / #FBF4E9 | 7.62:1 | ✓ |
-| tho | link on reference raised cream (body) | #644A05 / #FBF4E9 | 7.62:1 | ✓ |
+| tho | link on white (body) | #744000 / #FFFFFF | 8.48:1 | ✓ |
+| tho | link on reference page (body) | #744000 / #FFFDF8 | 8.34:1 | ✓ |
+| tho | link on tint (body) | #744000 / #FBF4E9 | 7.76:1 | ✓ |
+| tho | link on reference raised cream (body) | #744000 / #FBF4E9 | 7.76:1 | ✓ |
 | tho | link on reference dark panel (body) | #FFD57A / #221710 | 12.56:1 | ✓ |
 | tho · clay | link on white (body) | #462402 / #FFFFFF | 13.87:1 | ✓ |
 | tho · clay | link on reference page (body) | #462402 / #FFFDF8 | 13.65:1 | ✓ |
@@ -184,8 +184,8 @@ Pair `--cs-accent-strong` with `--cs-accent-on-strong`: both light and dark pack
 |---|---|---|---|---|
 | tho · sand | light | #FFFFFF / #856A03 | 80.8 | ✓ |
 | tho · sand | dark | #FFFFFF / #80671A | 82.2 | ✓ |
-| tho | light | #FFFFFF / #916D11 | 78.4 | ✓ |
-| tho | dark | #FFFFFF / #6E5205 | 90.1 | ✓ |
+| tho | light | #FFFFFF / #A4631E | 78.4 | ✓ |
+| tho | dark | #FFFFFF / #7D480C | 90.5 | ✓ |
 | tho · clay | light | #FFFFFF / #5A3004 | 99.5 | ✓ |
 | tho · clay | dark | #FFFFFF / #5C3001 | 99.3 | ✓ |
 | hoa · plasma | light | #FFFFFF / #896163 | 81.7 | ✓ |
@@ -221,7 +221,7 @@ Proposal targets in `_audit/apca-dark-preview.html`: bright ≥ 75 · accent ≥
 | Pack | bright | accent | on | ink |
 |---|---|---|---|---|
 | tho · sand | 90.5 | 76.1 | 82.2 | 87.4 |
-| tho | 81.9 | 64.7 | 90.1 | 81 |
+| tho | 81.9 | 64.7 | 90.5 | 81 |
 | tho · clay | 77.1 | 60.6 | 99.3 | 79.4 |
 | hoa · plasma | 89.4 | 75.1 | 82.8 | 86.4 |
 | hoa | 81.2 | 63.2 | 90.9 | 80.3 |

package/docs/conventions.md

@@ -13,10 +13,10 @@ Every rendered surface resolves four orthogonal scopes — never encode one axis
 |---|---|---|---|
 | **Theme** | `data-theme="dark\|system"` | light / dark / system (OS) | `tokens/colors.css` |
 | **Element** (Ngũ Hành) | `data-cs-element` + `data-cs-variant` | hue identity per product | `tokens/elements.css` |
-| **Language** | `lang` / Language tweak | EN · VI required; `ja` spike (BCP-47 primary subtags) | component registry + template props — see `docs/decisions/locale-architecture.md` |
-| **Style** | `data-cs-style` (optional; absent ≡ `liquid-glass`) | surface material pack | `tokens/styles.css` |
+| **Language** | `lang` / Language tweak | EN · VI (`vi` default on UI surfaces; internal `ja` i18n spike) | component registry + template props — see `docs/decisions/locale-architecture.md` |
+| **Style** | `data-cs-style` (optional; absent ≡ `liquid-glass`) | surface material pack (`liquid-glass` · `matte-paper`) | `tokens/styles.css` + `base/glass.css` |
 
-Style’s sole pack today is **liquid-glass**. Immutable under all axes: Umber/Ochre anchors, voice, type families, semantic status colors, the composite focus indicator (text-primary contour + ochre halo), APCA floors, ≥44px targets.
+Style ships two packs: **liquid-glass** (default) and **matte-paper** (opaque crisp paper surfaces). Immutable under all axes: Umber/Ochre anchors, voice, type families, semantic status colors, the composite focus indicator (text-primary contour + ochre halo), APCA floors, ≥44px targets.
 
 ## Naming grammar
 
@@ -78,13 +78,13 @@ only for HTML element content, never URL, attribute, CSS or script contexts.
 
 **New element variant** — stay inside the element's oklch envelope; set the 10 `--cs-accent-*` contract tokens (incl. `--cs-accent-on-strong` ≥4.5:1 and body APCA75 on `-strong`) plus `--cs-color-text-accent`/`--cs-color-link` (APCA-check both); the aurora wash inherits from the element via `.cs-aurora-wash` (override the class rule only if the variant truly needs its own image); gradient partner (`grad-b`) must follow Tương sinh.
 
-**Ship check** — follow the portable verification gate in `docs/doctrine.md`, then run `_audit/docs-consistency.html` **and** `_audit/namespace-portability.html` (both must be green). source checkout VERSION **<!-- cs-source-version:checkout -->2.7.0<!-- /cs-source-version -->**.
+**Ship check** — follow the portable verification gate in `docs/doctrine.md`, then run `_audit/docs-consistency.html` **and** `_audit/namespace-portability.html` (both must be green). source checkout VERSION **<!-- cs-source-version:checkout -->2.9.0<!-- /cs-source-version -->**.
 
 ## Decision log (owner-approved)
 
 - Elements fully replace Ochre inside product scopes; plasma's hot-pink edge approved (Jul 2026).
 
-- Axes are Theme × Element × Language × Style. Style pack is liquid-glass (sole pack; absent ≡ default).
+- Axes are Theme × Element × Language × Style. Style packs are `liquid-glass` (default; absent ≡ default) and `matte-paper`.
 
 - Product registry is **locked** (Jul 2026) — eight portfolio mappings in `docs/products.md`; do not invent new product → element assignments.
 

package/docs/decisions.md

@@ -15,7 +15,7 @@ The numbered sections below preserve dated decisions and stable citation IDs; th
 | Security release window and acknowledgement target | `SECURITY.md` |
 | Support acceptance and retained approvals | `components/lifecycle.json`, `docs/conventions.md` |
 | Release preparation and separate authorization | `docs/release-notes.md`, `.github/workflows/release.yml` |
-| Validation and current finding dispositions | `_audit/remediation/assessment-remediation.md`, `test-results/final-validation.json` |
+| Validation and current finding dispositions | `_audit/ci/unit-suites.json`, `test-results/final-validation.json` |
 
 Published release notes remain historical records. A local build, a prepared candidate, an approved support record and a published release are distinct states.
 
@@ -104,7 +104,7 @@ Operational follow-ups — not product marketing, not a backlog surface:
 
 7. **Element colour geometry** (Jul 2026; owner palette bar Jul 2026) — **30** default sets (5 × soft/middle/deep × light/dark) from `tokens/element-seeds.json` (`npm run tokens:elements`): soft = washed pastel, middle = intensity-synced default (Thổ middle pins logo ochre), deep = clearly darker sibling in the same hue family; harmonious role ramps; light↔dark hue lock; APCA dark floors. Geometry gate requires both minΔE and minΔL plus monotonic L. Public variant names unchanged. Hard gate: `_audit/element-geometry.html`. Benchmark rubric: `docs/benchmark-rubric.md`.
 
-8. **Style axis (`data-cs-style`)** (Jul 2026) — Fourth product axis; sole live pack **liquid-glass** (absent ≡ liquid-glass). Contract: `tokens/styles.css` + hard gate `_audit/style-contract.html`. Future Style packs may expand indefinitely, each with its own colour-combination language — only via owner approval + Expansion Rule checklist in `docs/benchmark-rubric.md` (do not invent packs casually).
+8. **Style axis (`data-cs-style`)** (Jul 2026; expanded Nov 2026) — Fourth product axis; live packs **liquid-glass** (default; absent ≡ liquid-glass) and **matte-paper** (zero-blur opaque crisp paper surfaces for editorial/dense workspaces). Contract: `tokens/styles.css` + `base/glass.css` + hard gate `_audit/style-contract.html`. Future Style packs may expand only via owner approval + Expansion Rule checklist in `docs/benchmark-rubric.md` (do not invent packs casually).
 
 9. **Identity Lab retired** (Jul 2026) — Owner choice: delete `ui_kits/status-hub/identity-lab.html` and every product/docs/Storybook reference. Axis demos live in the Storybook Theme × Element × Language × Style toolbar, Atomic View, and the Elements Geometry specimen. Theme × Element × Language × Style **axes remain** product infrastructure (templates, tokens, kits Thổ-faithful). Do not revive the Lab under another name without a new decision.
 
@@ -130,7 +130,7 @@ Rules:
 
 Normative record: [`docs/decisions/locale-architecture.md`](./decisions/locale-architecture.md).
 
-- Language stays a product axis (Theme × Element × Language × Style). Values are primary language subtags (`en` · `vi` · spike `ja`), not a nested locale axis and not full region tags yet.
+- Language stays a product axis (Theme × Element × Language × Style). UI surfaces expose `vi` · `en` only (`vi` default); `ja` remains an internal programmatic BCP-47 fallback spike for Pagination, not a UI toolbar locale.
 - Registry keeps required EN·VI pairs; optional spike tables must match `en` keys when present.
 - Vietnamese-first default unchanged (`lang` unset → `vi`). Plural/ICU and region variants are follow-on.
 

package/docs/deploy.md

@@ -5,7 +5,7 @@ Published on Storybook **Docs** at `design.cyberskill.world`.
 Two tracks:
 
 1. **Portable design system (consumers)** — HTML consumers can link the reviewed `styles.css` and optional `_ds_bundle.js`, or use the browser legacy entry `_esm/cs.mjs`, without a bundler. The default npm import (`dist/esm/_esm/react.mjs`) is compiled ESM with React peers; React apps need a compatible module resolver. Source JSX remains available through the explicit source export. Storybook is host tooling. The npm portable payload follows `package.json` → `files`; public hosting uses the reviewed allowlist in `scripts/public-site-policy.json`.
-2. **Host site (`design.cyberskill.world`)** — static output packaged for Vercel. Packaging **does** run Node once at deploy time so Storybook ships as the product surface at `/`. There is still no long-running app server.
+2. **Host site (`design.cyberskill.world`)** — static output packaged for GitHub Pages (`.github/workflows/pages.yml` publishing `.vercel-static/` with `.nojekyll` and `CNAME`) or any static host. Packaging **does** run Node once at deploy time so Storybook ships as the product surface at `/`. There is still no long-running app server.
 
 Production **`/`** is the Storybook static build. Legacy `/dashboard`, `/dashboard/`, `/dashboard.html`, `/dashboard/:path*`, `/playground`, `/playground/`, and `/playground/:path*` redirect to `/`.
 
@@ -48,7 +48,7 @@ If you host under a **different** domain, change the absolute URLs in those meta
 
 **Without Storybook:** after provenance review and explicit deployment approval, serve the reviewed portable inventory as the webroot.
 
-**With Storybook at `/`:** `npm run build:site` writes a reviewed portable mirror to `.vercel-static/` and the Vercel deployment artifact to `.vercel/output/`. Vercel uses the latter's `config.json`; do not supply an old Output Directory override or rewrite `vercel.json` during a build to predict hashes that do not exist yet.
+**With Storybook at `/`:** `npm run build:site` writes a reviewed portable mirror to `.vercel-static/` (including `.nojekyll` and `CNAME` for GitHub Pages deployment via `.github/workflows/pages.yml`) and the Vercel deployment artifact to `.vercel/output/`. Vercel uses the latter's `config.json`; do not supply an old Output Directory override or rewrite `vercel.json` during a build to predict hashes that do not exist yet.
 
 Other static hosts need an adapter that maps each final HTML path and its aliases to the exact CSP in `public-site-csp.json`, retains the security headers and legacy redirects from `scripts/site-deployment-policy.json`, and denies inline scripts on unknown paths. Hashes must come from the final emitted bytes, including the deterministic template logic wrapper. A single copied CSP string cannot represent these page-specific permissions.
 

package/docs/design-styles.md

@@ -1,13 +1,13 @@
 # Design styles
 
-The live styling axes are **Theme × Element × Language × Style**. Style’s sole pack today is **liquid-glass**. An absent style attribute selects that pack. Unmarked descendants inherit their nearest theme and element scopes; the neutral root defaults to light with the studio brand anchors. Published on Storybook **Docs** at `design.cyberskill.world`.
+The live styling axes are **Theme × Element × Language × Style**. Style ships two surface material packs: **liquid-glass** (default; an absent style attribute selects it) and **matte-paper** (opaque crisp paper surfaces with zero backdrop blur). Unmarked descendants inherit their nearest theme and element scopes; the neutral root defaults to light with the studio brand anchors. Published on Storybook **Docs** at `design.cyberskill.world`.
 
 | Axis | How to set it | What it changes |
 |---|---|---|
 | **Theme** | `data-theme="light"`, `"dark"` or `"system"`; absence inherits the nearest scope (light at the neutral root) | light/dark semantic colours (product UI axis). Explicit light resets a dark ancestor. System follows the OS light/dark preference through `prefers-color-scheme`; Storybook toolbar and Atomic View expose all three values |
 | **Element** | `data-cs-element` + optional `data-cs-variant` | Ngũ Hành product identity (**15 packs** = 5 elements × soft/middle/deep) |
-| **Language** | `lang` / Language tweak | EN · VI built-in copy, Vietnamese by default; optional `ja` is a bounded Pagination spike, not full Japanese coverage |
-| **Style** | `data-cs-style` (optional; absent ≡ `liquid-glass`) | Surface material pack. Sole pack today: **liquid-glass** (`tokens/styles.css` + `base/glass.css`) |
+| **Language** | `lang` / Language tweak | EN · VI built-in copy (`vi` default on UI surfaces); programmatic `ja` remains an internal Pagination i18n spike, not a UI toolbar locale |
+| **Style** | `data-cs-style` (optional; absent ≡ `liquid-glass`) | Surface material pack: **liquid-glass** (default frosted optical blur) · **matte-paper** (opaque crisp paper surfaces, `tokens/styles.css` + `base/glass.css`) |
 
 ## Element colour contract
 
@@ -24,11 +24,12 @@ Source of truth: [`tokens/element-seeds.json`](../tokens/element-seeds.json) →
 | **Never remap** | composite focus indicator (text-primary contour + ochre halo) · semantic status colours |
 | **Geometry gate** | [`_audit/element-geometry.html`](../_audit/element-geometry.html) — intensity sync · variant distinctness · hue identity |
 
-## Style pack — liquid-glass
+## Style packs — liquid-glass & matte-paper
 
-- Liquid-glass materials (`cs-surface-*`) are the default surface language.
+- **liquid-glass** (`cs-surface-*`, default when `data-cs-style` is absent) is the optical frosted-glass surface language.
+- **matte-paper** (`data-cs-style="matte-paper"`) removes backdrop blur, switches `.cs-surface-*` and `.cs-card` / `.cs-dialog` / `.cs-drawer` / `.cs-popover__panel` / `.cs-menu__list` to crisp opaque `--cs-color-surface-panel` / `--cs-color-surface-raised` fills with `1px` solid `--cs-color-border-default` borders and tactile flat elevation (`--cs-shadow-xs`), ideal for legal/editorial instruments, dense ERP tables, and SOC War-Rooms; a nested `[data-cs-style="liquid-glass"]` restores optical blur.
 - Radius, shadow, and glass tokens come from `tokens/elevation.css` + `base/glass.css`; the Style axis contract lives in [`tokens/styles.css`](../tokens/styles.css).
-- Gate: [`_audit/style-contract.html`](../_audit/style-contract.html) — allowlists `liquid-glass` only.
+- Gate: [`_audit/style-contract.html`](../_audit/style-contract.html) — allowlists `liquid-glass` and `matte-paper`.
 - Rejected by doctrine: neon/cyberpunk cold hues, memphis playfulness, full skeuomorphism, emoji in UI chrome.
 - Type families are fixed and token-named: Be Vietnam Pro (UI) · Space Grotesk (`--cs-font-family-display`, opt-in headline face) · JetBrains Mono (code). The display face is a **role a scope may opt into** with `.cs-display-face`, not a product axis.
 
@@ -40,7 +41,7 @@ Prefer:
 3. A documented pattern in `docs/conventions.md` + a specimen card when the pattern should be reusable.
 4. A new **`data-cs-style`** pack only after an Expansion Rule pass — see [`docs/benchmark-rubric.md`](benchmark-rubric.md) style-expansion checklist. Styles consume the same 10 accent roles (incl. `on-strong`); they must not invent parallel Element packs.
 
-Do not invent a fifth product axis, and do not add a second Style pack without the Expansion Rule checklist.
+Do not invent a fifth product axis, and do not add an unreviewed Style pack without the Expansion Rule checklist.
 
 ## Internal theme switches
 
@@ -53,7 +54,7 @@ Maintain the authored generator and run `npm run tokens:generate` and `npm run t
 
 ## Density and public spacing roles
 
-`data-cs-density="compact"` currently affects Button and shared `.cs-field__control` metrics. The latter is used by TextField, Textarea, Select, NativeSelect and Mentions. Component tokens carry these overrides directly; the separate `--cs-density-*` utility exports do not establish broader component adoption. Existing coarse-pointer target floors remain in force.
+`data-cs-density="compact"` tightens Button, shared `.cs-field__control` metrics (TextField, Textarea, Select, NativeSelect, Mentions), and container rhythm across `.cs-card`, `.cs-table`, `.cs-dialog`, `.cs-field`, `.cs-review-gate`, `.cs-alert`, `.cs-toast`, `.cs-tag`, `.cs-tab`, `.cs-menu`, `.cs-stat`, and `.cs-divider` (with nested `[data-cs-density="comfortable"]` reset). Existing `>= 44px` coarse-pointer target floors remain strictly in force. `data-cs-contrast="high"` (and `prefers-contrast: more`) reinforces text/border tokens plus form controls, glass surface borders, and table/datagrid cell dividers.
 
 Spacing roles can replace a literal only when they express the same layout role. The current remediations verify unchanged geometry plus actual token intervention for controls and collection layouts. Border widths, font sizes, fixed geometry and touch targets are not automatically spacing-token candidates. A `px` census therefore measures literals, not defects.
 

package/docs/doctrine.md

@@ -42,7 +42,7 @@ Deep checks, never surface spot-checks. Cover the **whole set and every relevant
 | Language | Vietnamese-first; every UI string ships an EN + VN pair |
 | Accessibility floor | APCA Lc ≥ 75 body text; focus rings never removed; ≥ 44px touch targets |
 | Axes | Theme × Element × Language × Style (independent) |
-| Style pack | liquid-glass (sole pack; absent ≡ default) |
+| Style pack | liquid-glass (default; absent ≡ default) · matte-paper |
 
 One accent per surface. Semantic statuses and the composite focus indicator (text-primary contour + ochre halo) are never elemental. Lumi stays golden in every element.
 

package/docs/four-axes.md

@@ -4,8 +4,8 @@ The design system exposes four **independent** axes — the same switches in thi
 
 1. **Theme** — `data-theme` — light (default) · dark · **system** (OS `prefers-color-scheme`)
 2. **Element** — `data-cs-element` (+ optional `data-cs-variant`) — Ngũ Hành product identity: Kim · Mộc · Thủy · Hỏa · Thổ, the packs declared by the [current catalog](reference-catalog.json) in the Element toolbar (same set as **Foundations/Elements**, Atomic View, and template EL maps)
-3. **Language** — `lang` — `en` · `vi` (see **I18n**)
-4. **Style** — `data-cs-style` — sole pack today: `liquid-glass` (absent ≡ liquid-glass)
+3. **Language** — `lang` — `vi` (default) · `en` (see **I18n**)
+4. **Style** — `data-cs-style` — `liquid-glass` (default; absent ≡ liquid-glass) · `matte-paper` (opaque crisp paper surfaces)
 
 State them on a container for components that consume these scopes. Template support is declared per template in `docs/reference-catalog.json` (published counts); static print documents, UI kits and fixed-language collateral have documented boundaries. Language changes also require translated content and a renderer that selects it:
 
@@ -33,4 +33,4 @@ Storybook defaults: `light · tho · vi · liquid-glass`.
 - Don't remap semantic status colours or the Ochre focus halo per element
 - Don't mix two element accents as primary + secondary (gradient wash along Tương sinh only)
 - Don't inline one-language UI chrome in components
-- Don't invent a second Style pack without the Expansion Rule checklist
+- Don't invent an unreviewed Style pack without the Expansion Rule checklist

package/docs/quality-gates.md

@@ -49,7 +49,7 @@ Benchmark principles (WCAG · APCA · OKLCH · DTCG · CDS doctrine + style expa
 | Template language parity | `_audit/template-lang-parity.html` | Static source scan of all 85 `.dc.html`: en/vi hole-map key sets identical and non-empty (21 map templates); `sc-if` `isEN`/`isVN` branches paired (24 branch templates); every `language`-tweak template has a bilingual mechanism; EN-leak lexicon (Unsubscribe · View in browser · Preferences · All rights reserved · Manage subscription · Sent with) never appears outside `isEN` guards / the `en` map. VN-first stacked instruments (38 `vn-*` + 3 `doc-*`) are leak-exempt by design — both languages always render | 0 key drifts, 0 unpaired branches, 0 leaks (`__langparity`) | Hard | Fast board CI |
 | APCA dark packs | `_audit/apca-dark-preview.html` | All 15 element×variant packs hold their APCA targets in dark (bright-as-text ≥ 75, accent UI ≥ 60, ink-on-accent ≥ 75, ink-on-tint ≥ 75) | 0 current failures (`__apcaPreview.currentFail === 0`) | Hard | Fast board CI |
 | Element geometry | `_audit/element-geometry.html` | Soft/middle/deep intensity sync across five elements; variant distinctness; light↔dark hue identity; Thổ middle pins logo ochre; packs generated from seeds | `__elementgeometry.pass` | Hard | Fast board CI |
-| Style contract | `_audit/style-contract.html` | Style axis allowlist: sole pack `liquid-glass` (absent ≡ default); `styles.css` imports `tokens/styles.css`; `--cs-style-pack` resolves; no unknown `data-cs-style` in scanned sources | `__stylecontract.pass` | Hard | Fast board CI |
+| Style contract | `_audit/style-contract.html` | Style axis allowlist: `liquid-glass` (default; absent ≡ default) and `matte-paper`; `styles.css` imports `tokens/styles.css`; `--cs-style-pack` resolves for both; no unknown `data-cs-style` in scanned sources | `__stylecontract.pass` | Hard | Fast board CI |
 | Visual baselines | `_audit/visual-diff.html` | Template baselines exist and are loadable for side-by-side / overlay comparison | Baselines present; drift judged by eye (`__visualdiff`) | Advisory | Fast board CI |
 | Component baselines | `_audit/component-visual-diff.html` | 12 curated component crops anchor the atomic tiers for visual comparison | Crops render + baselines present (`__componentVisualDiff`) | Advisory | Fast board CI |
 | Component state paint | `_audit/component-state-paint.html` | Primary, secondary, ghost and danger buttons, an open dialog, an open menu, a field error and a selected data row paint the authored light and dark colors. Channel delta uses `PIXEL_CHANNEL_TOLERANCE` from the pixel contract. The 15 Linux page PNGs stay the pixel-diff set. | `__statepaint.pass` | Hard | Fast board CI + three-engine unit test |
@@ -160,3 +160,5 @@ The packed-assets check parses every packed JS/CJS/MJS/JSX file for literal impo
 Packed HTML inline scripts are also scanned when their type is absent, `module`, `text/javascript`, `application/javascript`, `text/ecmascript`, `application/ecmascript`, `text/babel` or `text/jsx`. Data and other script types are excluded. Inline module paths resolve relative to the HTML file. Missing-import and invalid-syntax probes must fail; JSON data blocks must remain unparsed. This scans dependency syntax without executing the inline programs or certifying every runtime resource.
 
 `npm run test:font-rendering` uses Chromium platform-font inspection to reject system fallback for the defined Vietnamese repertoire in NFC and NFD forms. It is part of `test:unit`. The D82 font-subset repair passes the defined NFC/NFD repertoire on both source and flattened stylesheets, with no system fallback in the Chromium fixture. This does not certify every Unicode character, native platform or human visual acceptance. Static cmap coverage and `document.fonts.ready` are not sufficient rendering proof; do not normalize caller data silently to bypass the gate.
+
+`npm run test:audit-regression` (`node _audit/ci/verify-audit-benchmarks-browser.mjs`) runs headless Chromium across `_audit/ci/fixtures/benchmark-20d.html`, `_audit/ci/fixtures/benchmark-baseline.html`, and `_audit/ci/fixtures/benchmark-gen2.html` using shared assertions in `_audit/ci/lib/benchmark-checks.mjs`. It verifies **129/129** checks across 20 dimensions (`D1`–`D20`) at **10.0 / 10**, **64/64** baseline checks at **10.0 / 10**, **192/192** cells (`≥ 3.0:1`) across the 32×6 non-text contrast matrix, and **3/3** Generation-2 stress-test product screens with **0 watch** items. To extend the benchmark after internal reviews or external AI evaluations (Google Stitch / Claude Design), add new assertions to `_audit/ci/lib/benchmark-checks.mjs` and remove temporary external artifacts once verified.