ui-style-kit-css 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -4,12 +4,88 @@ All notable changes to **UI Style Kit CSS** will be documented here.
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-09-08
+
+### Added
+
+- Added native light/dark/contrast palettes for every preset when `data-theme` is omitted, while preserving explicit shared-theme precedence and the typed semantic handshake.
+- Added a native-aware demo workbench with None, per-preset/mode edits, shared-theme edits, material-color inventory, scoped CSS export, and active-context reset.
+- Added a unified style-specific gallery, including Industrial Utility instruments and alarm demonstration controls; full source boards remain available through `?view=reference`.
+- Added validated `ui`, `personality`, `theme`, and `mode` demo query parameters and updated README/wiki guidance for native palettes and review links.
+- Added a frozen native-control intent contract for every preset and complete per-preset mappings for choice, select, range, progress, meter, file, color, indicator, and scrollbar tokens.
+- Added Firefox range-progress paint, distinct single/multiple select behavior, indeterminate progress treatment, and a complete native-control demo specimen.
+- Added manifest-driven unit and cross-browser computed-style coverage proving all 20 presets resolve to unique native-control signatures.
+- Added frozen six-axis template signatures plus pairwise identity contracts across typography, density, geometry, material, feedback, data presentation, and the 48-token native-control surface.
+- Added fixed desktop and mobile component and native-control specimens for every preset, with direct pairwise visual-difference thresholds.
+- Added executable six-axis reference traits that assert concrete authored CSS for every preset, plus preset-, viewport-, mode-, and pair-scoped browser cases for exact reruns.
+- Added stable global UI-matrix case identifiers, 36 resumable 100-case blocks, exact-case reruns, and bounded range commands so passed coverage is not repeated during diagnosis.
+
+### Changed
+
+- Expanded preset identity beyond color and radius so native controls now inherit each system's typography, geometry, material, border, depth, indicator, range, progress, and loading language.
+- Reworked all 20 preset systems against the 39-image v2.4.0 reference archive and retained design contracts. Each identity now reaches components, native controls, feedback, data views, and interaction states.
+- Preserved theme-owned palette channels, semantic native HTML, v2 selectors and entrypoints, bridge ownership, forced-color behavior, reduced motion, and platform-owned picker/dialog boundaries.
+
+### Fixed
+
+- Restored the shared background token for standalone native palettes by resolving through each preset's active background.
+- Prevented native `strong` and `small` text paint from replacing trust-seal foregrounds, including Tactile's dark instrument seal.
+- Unified demo toolbar dropdown indicators, enlarged and strengthened Maximalist medallion artwork, centered its range thumb, matched busy indicators to its spinner, and removed the large native-form grid gap.
+- Exposed actual native material variables in the color editor instead of restricting it to generic shared roles.
+- Replaced stale per-style bundle-size estimates with build-measured focused preset examples.
+- Corrected Organic Modern native-light label and control-edge contrast while retaining shared-theme precedence.
+- Completed manifest discovery for existing Bento stage, Bauhaus alert text, Clay helper, and Tactile workspace classes; no existing classes were removed.
+- Applied bounded generated-file write retries to README measurements and demo asset hashes as well as distribution CSS.
+- Replaced broad `overflow-wrap: anywhere` inheritance with targeted `break-word` containment and normal word boundaries, and removed clipping from general surfaces, feature strips, and native tables while retaining deliberate progress, media, and accessibility masks.
+
+### Security
+
+- Updated the development-only `fast-uri` override to `3.1.6`, addressing the four URI-normalization advisories reported by the release dependency audit without adding runtime dependencies.
+
+## [2.3.0] - 2026-08-29
+
+### Added
+
+- Added nine new first-class UI systems: `editorial-luxe`, `organic-modern`, `industrial-utility`, `technical-blueprint`, `art-deco`, `clay`, `data-terminal`, `paper-editorial`, and `neo-noir`, bringing the library to 20 presets.
+- Added ten shared color themes—`chrome-navy`, `recycled-emerald`, `industrial-orange`, `performance-red`, `heritage-brass`, `service-blue-red`, `newsprint-crimson`, `foundry-amber`, `soft-orchid`, and `electric-noir`—with light, dark, and contrast modes, bringing the shared theme set to 20.
+- Added a universal commercial/marketing component vocabulary across all 20 UI systems: service and feature cards, card media and accent edges, icon medallions, clipped and heavy-outline buttons, seal badges, feature strips/items, callout bars, eyebrow text, and media scrims.
+- Added a live demo showcase and contract tests for the new cross-style component suffixes and published bundles.
+- Expanded the manifest-driven browser matrix to 20 presets × 20 themes × 3 modes × 3 engines (3,600 combinations).
+- Added manifest-generated shared containment and expanded-component inventories so all 20 presets stay synchronized with the public registry.
+- Added distinct preset-owned loader geometry for all 20 spinner utilities and native or component busy-button indicators.
+- Added a declared modern-browser support floor, exactly pinned Browserslist resolution, and a CSS Tree-backed `check:compat` release gate for every generated entrypoint.
+
+### Changed
+
+- Gave all 20 presets distinct CTA, card, medallion, strip, scrim, and callout identities while preserving the existing class names and theme color roles.
+- Separated filled service actions from framed callout actions so `button-cut` and `button-outline-heavy` express independent, preset-coherent roles instead of sharing one generic CTA silhouette.
+- Reworked the commercial and utility demo specimens to use active theme tokens, explicit utility composition, and container-aware native typography.
+- Aligned ecosystem verification and documentation with `layout-style-css@3.1.0` and `interactive-surface-css@1.7.0`, including the current exported manifests and `foundation.css`.
+- Expanded the commercial component documentation with composition, accessibility, and responsive-behavior guidance.
+- Routed every Lightning CSS formatting and minification pass through the shared package Browserslist targets, with stable fallbacks and guarded progressive enhancements.
+
+### Fixed
+
+- Prevented the outer showcase grid from leaking its twelve-column rules into the nested commercial component grid.
+- Kept busy indicators separated from labels and contained inside native busy buttons.
+- Removed the CTA modifier specificity conflict so `button-cut` geometry can express each preset instead of falling back to a generic shape.
+- Removed obsolete Layout `integrations/ui-style-kit.css` and `legacy.css` expectations from packed ecosystem verification.
+- Prevented shared switch foundations from shrinking the track or applying a second thumb translation over the preset-owned checked position.
+- Replaced the stretched faceted Clay CTA with a compact, softly clipped inflated pill that matches Clay controls.
+- Strengthened light-mode component edges to a verified 3:1 non-text contrast minimum without changing semantic theme colors.
+- Prevented editable-field background paint from leaking onto button, submit, and reset inputs when the Interactive Surface bridge adds its hook class.
+- Corrected the remaining light-mode soft-surface and primary-hover contrast failures and expanded the manifest-driven audit to all 1,200 preset, theme, and mode states.
+- Kept preset eyebrow and native strong-text rules from overriding the high-contrast foreground inside media-scrim captions.
+- Replaced Bento's fixed six-column feature helper with intrinsic, container-aware tiles so metric labels do not collapse into narrow vertical text columns.
+- Normalized semantic action inputs independently of bridge hook classes, stopped read-only field paint from overriding action controls, and kept deprecated bridge foreground/background swaps atomic so transient states remain readable.
+- Restored prefixed Retro Glass `backdrop-filter` output, removed obsolete intrinsic CTA sizing diagnostics, and guarded `color-mix()`, `text-wrap`, and `forced-color-adjust` enhancements for the declared support floor.
+
 ## [2.2.0] - 2026-08-09
 
 ### Added
 
 - Added the public 12-token shared semantic producer contract and its machine-readable manifest inventory for companion and third-party consumers.
-- Implemented the manifest-backed semantic component API with 29 exact `.ui-*` selectors, context-constrained `data-ui-variant` values, and unchanged-markup runtime switching across all 11 presets.
+- Implemented the manifest-backed semantic component API with 29 exact `.ui-*` selectors, context-constrained `data-ui-variant` values, and unchanged-markup runtime switching across every preset supported by that release.
 - Added a persistent semantic component demo whose DOM nodes and classes remain stable through every preset switch.
 - Documented native `<dialog>` as the neutral modal/dialog fallback without inventing `.ui-modal` or `.ui-dialog` selectors.
 

package/CONTRIBUTING.md

@@ -13,11 +13,18 @@ The library is CSS-only for consumers. Build and validation scripts run with Nod
 
 1. Keep the public `data-ui`, `data-theme`, and `data-mode` API stable unless preparing a documented major version.
 2. Preserve class prefixes and prefixed functional tokens.
-3. Define concrete color scheme values in `styles/theme-colors.css` as shared `--usk-*` roles; UI style files should only alias those roles and define visual treatment.
+3. Define named color schemes in `styles/theme-colors.css` as shared `--usk-*` roles. Keep each preset's native light/dark/contrast palette in its source file, preserve explicit-theme precedence, and verify both paths.
 4. Include the native HTML coverage and accessibility layer.
 5. Run `npm run check` before publishing.
 6. Update `STYLE-MAP.md`, `docs/TOKENS.md`, `README.md`, wiki pages, and `CHANGELOG.md` for public API changes.
 
+Use focused tests during implementation and the complete release gate at the end.
+Rebuild after source CSS edits because both demo entrypoints load generated `dist/`
+assets. The build also refreshes manifests, bundled icons, README size measurements,
+and demo cache hashes. Reusable JavaScript helpers should carry JSDoc-compatible
+comments; do not hand-edit generated output. The tracked `wiki/` pages are local
+wiki sources; updating them alone does not publish the hosted GitHub Wiki.
+
 ## Versioning
 
 - Patch: CSS fixes, docs fixes, small accessibility corrections.

package/README.md

@@ -5,11 +5,13 @@
 
 **UI Style Kit CSS** is a CSS-only theme and UI style preset library for accessible websites, dashboards, admin interfaces, and customer-facing pages.
 
-It is separate from, but complementary to, **Interactive Surface CSS**. Use **UI Style Kit CSS** for visual identity, color themes, UI presets, layout mood, and native HTML styling. Use **Interactive Surface CSS** for interaction-state animation systems and surface behavior.
+It is separate from, but complementary to, **Interactive Surface CSS** and **Layout Style CSS**. Use **UI Style Kit CSS** for visual identity, color themes, UI presets, layout mood, and native HTML styling. Use **Interactive Surface CSS** for interaction-state animation systems and surface behavior. Use **Layout Style CSS** for responsive layout wrappers, grid systems, macro-structure positioning, and container scaffolding.
 
-## Current Release
+## Current release target
 
-`v2.2.0` adds the shared 12-token semantic producer contract and a manifest-backed 29-selector `.ui-*` component API across all 11 presets. Existing default and focused entrypoints remain compatible, including their deprecated structural helpers, and parser-based minification remains exactly pinned.
+`v2.4.0` gives all 20 UI style systems a complete native-control identity across selects, choices, ranges, progress, meters, file/color/date launch controls, indicators, and scrollbars. Existing themes, modes, selectors, default/focused/visual/bridge entrypoints, and the 3,600-case browser matrix remain compatible, and parser-based minification remains exactly pinned.
+
+This is the local 2.4.0 release candidate, not a claim of npm publication. It also adds native light/dark/contrast palettes when `data-theme` is omitted, a palette-aware color workbench, and a unified demo with style-specific components. See the [2.4.0 release preparation notes](docs/RELEASE-2.4.0.md) for scope and verification boundaries.
 
 [Showcase website](https://foscat.github.io/ui-style-kit-css/)
 
@@ -19,7 +21,7 @@ UI Style Kit CSS owns visual identity: themes, semantic `.ui-*` component paint,
 
 ```mermaid
 flowchart LR
-  App["Application markup"] --> Attrs["data-ui + data-theme + data-mode"]
+  App["Application markup"] --> Attrs["data-ui + data-mode; optional data-theme"]
   Attrs --> USK["ui-style-kit-css"]
   USK --> Themes["Shared --usk-* theme roles"]
   USK --> Components["Prefixed component classes"]
@@ -38,11 +40,13 @@ flowchart TB
   Rgb --> Modes["Light, dark, and contrast modes"]
   Modes --> Prefixes["Per-style prefixed aliases"]
   Prefixes --> Rules["Component, utility, and native rules"]
-  Demo["Demo token workbench"] --> Overrides["Copyable :where([data-ui][data-theme][data-mode]) override block"]
+  Demo["Demo token workbench"] --> Overrides["Scoped native-palette or shared-theme overrides"]
   Overrides --> Rgb
 ```
 
-The demo page documents this flow directly: it shows computed RGB color tokens for the active theme and mode, lets developers edit them live, and copies the exact override block to drop into an app stylesheet.
+The demo shows computed RGB colors for the active native palette or shared theme, supports live edits, and copies a scoped override block. Native mode includes preset-specific material channels such as paper, ink, and brass; shared-theme mode exposes the 23 semantic RGB roles.
+
+The [demo showcase guide](docs/DEMO-SHOWCASE.md) explains the unified component gallery, Industrial Utility instruments, palette editing, and the opt-in `?view=reference` boards. Existing `?personality=maximalist` links work; `?ui=tactile&theme=None&mode=dark` selects a native-palette preview.
 
 ## Ecosystem compatibility
 
@@ -50,11 +54,11 @@ These libraries stay standalone, but the current aligned set is:
 
 | Library | Aligned version | Owns |
 |---|---:|---|
-| `ui-style-kit-css@2.2.0` | current package version | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
-| `interactive-surface-css@1.6.0` | published release | interaction-state primitives, surface behavior, state layers, and input affordances |
-| `layout-style-css@3.0.1` | published release | structural wrappers, grids, sections, app shells, and layout recipes |
+| `ui-style-kit-css@2.4.0` | current release target | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
+| `interactive-surface-css@1.7.0` | compatible state release | interaction-state primitives, surface behavior, state layers, and input affordances |
+| `layout-style-css@3.1.0` | compatible structural release | structural wrappers, grids, sections, app shells, and layout recipes |
 
-The current combination is `ui-style-kit-css@2.2.0`, `interactive-surface-css@1.6.0`, and `layout-style-css@3.0.1`. UI Style Kit `2.2.0` is the current package version, and the release pipeline treats it as the active candidate only while that exact npm version is absent. Interactive Surface `1.6.0` and Layout Style `3.0.1` are published releases. The validated minimum remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
+UI Style Kit `2.4.0` is the current release target and is verified with Interactive Surface `1.7.0`. Layout Style `3.1.0` is the compatible structural release. The validated minimum remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
 
 Use one, two, or all three depending on the project. UI Style Kit does not require the sibling libraries, and the optional bridge only maps shared `--usk-*` roles into Interactive Surface tokens when consumers import it.
 
@@ -66,9 +70,10 @@ For import order, ownership boundaries, and adoption paths, see the [Ecosystem g
 
 ## Features
 
-- 11 UI style systems
-- 10 shared color schemes
+- 20 UI style systems
+- 20 shared color schemes
 - `light`, `dark`, and `contrast` modes
+- Native preset colors when no shared theme is selected
 - Combined CSS bundle and per-style production imports
 - Visual-only full and focused entrypoints for consumer-owned layouts
 - Machine-readable `manifest.json` preset, theme, mode, class, and native-part capabilities
@@ -108,7 +113,7 @@ Use the generated default bundle for semantic components that can switch across
 import "ui-style-kit-css";
 ```
 
-Use `ui-style-kit-css/visual.css` for the same 29-selector semantic runtime API without the deprecated prefixed layout selectors. The generated default, visual, and with-bridge bundles all support all 11 `data-ui` values.
+Use `ui-style-kit-css/visual.css` for the same 29-selector semantic runtime API without the deprecated prefixed layout selectors. The generated default, visual, and with-bridge bundles all support all 20 `data-ui` values.
 
 Applications fixed to one preset can use a generated focused visual entrypoint. It includes semantic aliases scoped to that preset only:
 
@@ -128,7 +133,7 @@ import "ui-style-kit-css/minimal-saas.css";
 import "ui-style-kit-css/styles/minimal-saas.css";
 ```
 
-In `v2.1.0`, legacy standalone style files continue to import the shared color-scheme, native-element fallback, and content-overflow layers. Bundlers that understand CSS `@import` resolve them automatically. If your build pipeline does not resolve CSS imports, import the shared dependencies before the style file:
+Compatible standalone style files continue to import the shared color-scheme, native-element fallback, and content-overflow layers. Bundlers that understand CSS `@import` resolve them automatically. If your build pipeline does not resolve CSS imports, import the shared dependencies before the style file:
 
 ```js
 import "ui-style-kit-css/theme-colors.css";
@@ -162,14 +167,15 @@ When the bridge is attached, add `.interactive-surface` to interactable elements
 
 | Import | Raw | Gzip | Best for |
 |---|---:|---:|---|
-| `ui-style-kit-css/dist/ui-style-kit.min.css` | ~357 KB | ~44 KB | Compatible runtime UI-system switchers and demos |
-| `ui-style-kit-css/visual.min.css` | ~348 KB | ~43 KB | Runtime visual switching with consumer-owned layout |
-| `ui-style-kit-css/with-bridge.css` | ~431 KB | ~52 KB | Deprecated runtime switcher plus stateful bridge |
-| `ui-style-kit-css/theme-colors.css` | ~25 KB | ~3 KB | Shared color schemes for standalone style imports |
-| `ui-style-kit-css/native-elements.css` | ~22 KB | ~4 KB | Shared native HTML fallback styling |
-| `ui-style-kit-css/content-overflow.css` | ~7 KB | ~1 KB | Shared long-text containment for standalone style imports |
-| `ui-style-kit-css/interactive-surface-theme.css` | ~8 KB | ~1 KB | Canonical token-and-paint bridge for Interactive Surface state core |
-| Single style imports | ~26-28 KB | ~5-6 KB | Production apps with one visual system |
+| `ui-style-kit-css/dist/ui-style-kit.min.css` | ~1978 KB | ~379 KB | Compatible runtime UI-system switchers and demos |
+| `ui-style-kit-css/visual.min.css` | ~1962 KB | ~377 KB | Runtime visual switching with consumer-owned layout |
+| `ui-style-kit-css/with-bridge.css` | ~2309 KB | ~400 KB | Deprecated runtime switcher plus stateful bridge |
+| `ui-style-kit-css/theme-colors.css` | ~50 KB | ~6 KB | Shared color schemes for standalone style imports |
+| `ui-style-kit-css/native-elements.css` | ~31 KB | ~5 KB | Shared native HTML fallback styling |
+| `ui-style-kit-css/content-overflow.css` | ~20 KB | ~3 KB | Shared long-text containment for standalone style imports |
+| `ui-style-kit-css/interactive-surface-theme.css` | ~9 KB | ~1 KB | Canonical token-and-paint bridge for Interactive Surface state core |
+| `ui-style-kit-css/visual/minimal-saas.css` | ~205 KB | ~30 KB | Focused Minimal SaaS, including semantic aliases and shared foundations |
+| `ui-style-kit-css/visual/industrial-utility.css` | ~278 KB | ~39 KB | Focused Industrial Utility, including its instrumentation styles |
 
 ## CDN usage
 
@@ -182,7 +188,7 @@ Use the latest published NPM package:
 For production, pin the exact approved release rather than relying on `latest`:
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@2.2.0/dist/ui-style-kit.min.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@2.4.0/dist/ui-style-kit.min.css" />
 ```
 
 ## Basic usage
@@ -210,23 +216,37 @@ document.body.dataset.mode = "dark";
 
 This changes the semantic components' visual preset without replacing their DOM nodes or rewriting their `.ui-*` classes.
 
+### Native palettes and None
+
+Keep `data-ui` and `data-mode`, and omit `data-theme` to display the selected style's native palette:
+
+```html
+<body data-ui="tactile" data-mode="light">
+```
+
+```js
+document.body.removeAttribute("data-theme");
+```
+
+The demo labels this choice **None — style defaults**. Do not assign the literal strings `"None"` or `"null"` to the HTML attribute. Native editor exports use `--<prefix>-*-rgb` variables scoped to the active preset/mode without a theme; named-theme exports use `--usk-*-rgb` and remain reusable across presets. Check contrast again after changing colors.
+
 ## Semantic component API
 
-`manifest.json#semanticComponentApi` is the authoritative specification for the implemented generic component API. Its 29 selectors keep the same class names while `data-ui` changes across all 11 presets. `implementationStatus` records the two retained `.ui-spinner` and `.ui-tooltip` hooks, the 27 generated semantic aliases, and an empty pending set.
+`manifest.json#semanticComponentApi` is the authoritative specification for the implemented generic component API. Its 29 selectors keep the same class names while `data-ui` changes across all 20 presets. `implementationStatus` records the two retained `.ui-spinner` and `.ui-tooltip` hooks, the 27 generated semantic aliases, and an empty pending set.
 
 | Role | Generic selectors | Switching coverage |
 |---|---|---|
-| Buttons | `.ui-button`, `.ui-icon-button` | all 11 presets |
-| Card | `.ui-card` | all 11 presets |
-| Forms | `.ui-field`, `.ui-label`, `.ui-help-text`, `.ui-input`, `.ui-select`, `.ui-textarea` | all 11 presets |
-| Choice controls | `.ui-check`, `.ui-check-control`, `.ui-radio`, `.ui-radio-control`, `.ui-switch`, `.ui-switch-track`, `.ui-switch-thumb` | all 11 presets |
-| Badge | `.ui-badge` | all 11 presets |
-| Alert | `.ui-alert`, `.ui-alert-title`, `.ui-alert-body` | all 11 presets |
-| Navigation | `.ui-nav`, `.ui-nav-link` | all 11 presets |
-| Table | `.ui-table`, `.ui-table-wrap` | all 11 presets |
-| Progress | `.ui-progress`, `.ui-progress-bar` | all 11 presets |
-| Toolbar | `.ui-toolbar` | all 11 presets |
-| Existing generic hooks | `.ui-spinner`, `.ui-tooltip` | all 11 presets |
+| Buttons | `.ui-button`, `.ui-icon-button` | all 20 presets |
+| Card | `.ui-card` | all 20 presets |
+| Forms | `.ui-field`, `.ui-label`, `.ui-help-text`, `.ui-input`, `.ui-select`, `.ui-textarea` | all 20 presets |
+| Choice controls | `.ui-check`, `.ui-check-control`, `.ui-radio`, `.ui-radio-control`, `.ui-switch`, `.ui-switch-track`, `.ui-switch-thumb` | all 20 presets |
+| Badge | `.ui-badge` | all 20 presets |
+| Alert | `.ui-alert`, `.ui-alert-title`, `.ui-alert-body` | all 20 presets |
+| Navigation | `.ui-nav`, `.ui-nav-link` | all 20 presets |
+| Table | `.ui-table`, `.ui-table-wrap` | all 20 presets |
+| Progress | `.ui-progress`, `.ui-progress-bar` | all 20 presets |
+| Toolbar | `.ui-toolbar` | all 20 presets |
+| Existing generic hooks | `.ui-spinner`, `.ui-tooltip` | all 20 presets |
 
 The only new attribute is context-constrained `data-ui-variant`. Omit it for the neutral treatment.
 
@@ -251,19 +271,48 @@ For example, a fixed Minimal SaaS integration may continue to use `<button class
 
 ## UI systems
 
-| UI style | `data-ui` | Class prefix | Best for |
-|---|---:|---:|---|
-| Minimal SaaS | `minimal-saas` | `saas` | dashboards, admin tools, SaaS apps |
-| Bento UI | `bento` | `bento` | landing pages, feature sections, showcases |
-| Maximalist / Playful | `maximalist` | `max` | creators, entertainment, bold client sites |
-| Bauhaus / Swiss Modern | `bauhaus` | `bau` | agencies, editorial layouts, design-forward brands |
-| Skeuomorphic / Tactile | `tactile` | `tactile` | premium tactile interfaces, control panels |
-| Neumorphism | `neumorphism` | `neo` | soft dashboards, experimental UI |
-| Retrofuturism | `retrofuturism` | `retro` | futuristic portfolios and product pages |
-| Brutalism | `brutalism` | `brutal` | bold creative websites |
-| Cyberpunk | `cyberpunk` | `cyber` | security, gaming, encryption, tech demos |
-| Y2K | `y2k` | `y2k` | nostalgic, playful, fashion/music/event sites |
-| Retro Glass | `retro-glass` | `rg` | futuristic glass dashboards and hero sections |
+| UI style | `data-ui` | Prefix | Defining visual contract | Best for |
+|---|---:|---:|---|---|
+| Minimal SaaS | `minimal-saas` | `saas` | compact flat modules, cool 1px rules, tight radii, restrained type, negligible elevation | dense dashboards, admin tools, focused SaaS workflows |
+| Bento UI | `bento` | `bento` | Soft Mosaic tiles, Manrope, fine borders, compact rounded controls, restrained elevation | friendly product surfaces, feature mosaics, showcase dashboards |
+| Maximalist / Playful | `maximalist` | `max` | loud poster collage, sticker offsets, hard ink strokes, expressive condensed typography | creators, entertainment, bold client sites |
+| Bauhaus / Swiss Modern | `bauhaus` | `bau` | strict grids, heavy rules, primary geometry, flat construction, condensed uppercase type | agencies, editorial layouts, design-forward brands |
+| Skeuomorphic / Tactile | `tactile` | `tactile` | paper plates, serif headings, keylines, chamfered keycaps, dark troughs, mechanical controls | physical workspace configuration and instrument-like product UI |
+| Neumorphism | `neumorphism` | `neo` | borderless same-surface shells, opposing extrusion shadows, concave fields and pressed states | sculpted dashboards and quiet configuration workflows |
+| Retrofuturism | `retrofuturism` | `retro` | atomic enamel shells, metallic rims, inset instrument bays, oval actions, dial controls | atomic-age dashboards and configuration workspaces |
+| Brutalism | `brutalism` | `brutal` | square full-bleed grids, heavy rules, numbered modules, blunt controls, segmented meters | direct operational and bold creative interfaces |
+| Cyberpunk | `cyberpunk` | `cyber` | chamfered HUD panels, clipped controls, technical condensed type, signal-colored edges | security, gaming, routing, and high-tech command tools |
+| Y2K | `y2k` | `y2k` | dense portal panels, 1px bevels, title bars, system typography, segmented indicators | nostalgic fashion, music, event, and community portals |
+| Retro Glass | `retro-glass` | `rg` | brushed application chrome, glossy navigation, beveled controls, glass panes, dark dock treatment | dense desktop-style media and productivity applications |
+| Editorial Luxe | `editorial-luxe` | `luxe` | Didone hierarchy, double rules, rigid editorial geometry, restrained couture material | luxury brands, architecture, hospitality, premium editorial sites |
+| Organic Modern | `organic-modern` | `organic` | matte limestone/forest surfaces, Cormorant Garamond + DM Sans, pointed actions, material photography, fine ledger rules | architecture, sustainable materials, natural product workspaces |
+| Industrial Utility | `industrial-utility` | `utility` | metal-framed panels, recessed instruments, mechanical actions, safety gauges, technical type | operations, manufacturing, logistics, fleet, and equipment systems |
+| Technical Blueprint | `technical-blueprint` | `blueprint` | drafting grids, technical linework, square measured controls, annotations, calibrated geometry | engineering, architecture, technical documentation, scientific tools |
+| Art Deco | `art-deco` | `deco` | stepped symmetry, metallic double keylines, fanbursts, elegant display type, jewel controls | luxury, hospitality, heritage brands, and distinctive showcases |
+| Clay | `clay` | `clay` | hand-molded imperfect edges, mineral grain, raised lower shadows, carved fields, debossed type, and clay-bead loaders | collaborative tools, education, and approachable product sites |
+| Data Terminal | `data-terminal` | `terminal` | dense 1px command grid, mono typography, bracketed actions, strict semantic signal colors | operator consoles, telemetry, infrastructure, monitoring, developer tools |
+| Paper Editorial | `paper-editorial` | `paper` | physical field-manual sheet, binder and index details, print rules, condensed and monospaced type | news, journals, cultural sites, and story-led publishing |
+| Neo-Noir | `neo-noir` | `noir` | cinematic slants, trapezoid controls, diagonal cuts, subtle grain, semantic amber/teal/red signaling | cinematic portfolios, production tools, and dramatic product sites |
+
+Each description is backed by concrete CSS declaration checks and preset-scoped visual cases. This lets a failing preset or pair be rerun directly without repeating unrelated green coverage.
+
+The demo uses one shared layout with a **Style-specific components** gallery. Industrial Utility's switchgear, instruments, and alarm workflow are showcased alongside each preset's distinctive components. Original template boards remain available for visual QA at `index.html?view=reference` (also supported by `demo/index.html`). See the [demo showcase guide](docs/DEMO-SHOWCASE.md) for the gallery, native/shared palettes, and reference-fixture workflow.
+
+See the [Retro Glass component guide](docs/RETRO-GLASS.md) for the full reference-board API, native palette selection, token customization, and accessible interaction contracts. Preset-specific demo components appear only while their owning style is selected.
+
+The [Art Deco component guide](docs/ART-DECO.md) covers the 17-group Metropolitan Moderne specimen, its complete public component inventory, paired reference palettes, theme-token integration, and keyboard interactions. Select Art Deco in the reference view to reveal its complete board.
+
+The [Editorial Lux component guide](docs/EDITORIAL-LUX.md) covers the couture reference specimen, its ten component groups, token-based palettes, accessible interactions, and responsive layout. Its existing `editorial-luxe` preset ID and `luxe-*` public API remain compatible.
+
+The [Neo Noir component guide](docs/NEO-NOIR.md) covers all 15 Midnight Cut reference groups, portable textures, canonical `noir-*` components, light/dark palettes and keyboard interactions. The complete specimen appears in the reference view when Neo-Noir is selected.
+
+The [Organic Modern component guide](docs/ORGANIC-MODERN.md) maps the architecture workspace and Control Lab to public `organic-*` classes. Both reference palettes are fallbacks only; shared themes paint the complete UI. Its complete specimen appears in the reference view when Organic Modern is selected.
+
+The [Bento component guide](docs/BENTO.md) maps the retained Soft Mosaic template one-to-one to public `bento-*` classes, including service status, quota, listbox, loading, and dialog components. Reference colors are fallbacks behind shared theme roles. Its complete interactive specimen appears in the reference view when Bento UI is selected.
+
+The [Tactile workspace guide](docs/TACTILE.md) documents its optional navigation,
+settings, and instrument-panel composition, native material colors, and theme-safe
+foregrounds. These advanced classes are included in the public manifest.
 
 ## Color themes
 
@@ -278,10 +327,67 @@ desert-sage
 rose-quartz
 cyber-lime
 arctic-indigo
+chrome-navy
+recycled-emerald
+industrial-orange
+performance-red
+heritage-brass
+service-blue-red
+newsprint-crimson
+foundry-amber
+soft-orchid
+electric-noir
 ```
 
 Color schemes are defined once in `styles/theme-colors.css` as shared `--usk-*` RGB roles. Each UI style maps those shared roles back to its public prefix, so existing component rules still consume variables such as `--saas-primary`, `--bau-surface`, and `--rg-on-primary`.
 
+## Commercial component modifiers
+
+The cross-style API also includes reusable marketing and service-site patterns. These suffixes are available for all 20 UI systems and inherit the active `data-theme` / `data-mode` palette:
+
+```txt
+card-media
+card-service
+card-feature
+card-accent-edge
+icon-medallion
+button-cut
+button-outline-heavy
+badge-seal
+feature-strip
+feature-item
+callout-bar
+eyebrow
+media-scrim
+```
+
+Combine them with the preset prefix and existing base components:
+
+```html
+<article class="saas-card saas-card-service">
+  <img class="saas-card-media" src="service.jpg" alt="">
+  <span class="saas-icon-medallion" aria-hidden="true">★</span>
+  <p class="saas-eyebrow">Professional Service</p>
+  <h3 class="saas-heading">A reusable service card</h3>
+  <p class="saas-copy">The visual treatment changes with the selected UI system.</p>
+  <a class="saas-button saas-button-primary saas-button-cut" href="#">Learn More</a>
+</article>
+```
+
+The components intentionally contain no domain-specific content. Icons, media, labels, and copy remain consumer-owned.
+
+### Component composition
+
+- Service cards combine the base `card` with `card-service`; add `card-media` for responsive media, `icon-medallion` for an overlapping symbol, and `button-primary button-cut` for the filled service action.
+- Feature cards use `card-feature` or `card-accent-edge` when information needs a stronger preset-specific edge treatment without changing the semantic element.
+- Media treatments place an image and its caption inside `media-scrim`. The scrim supplies readable theme-token paint; the image and alternative text remain application content.
+- Feature strips contain one or more `feature-item` children. They use balanced columns when space permits and collapse without requiring a new class.
+- Callout bars use `callout-bar` as the visual lane and `button-outline-heavy` for the framed supporting action. There is no separate `button-cta` API.
+
+`button-cut` and `button-outline-heavy` are independent modifiers: the first supplies the preset's filled-action silhouette and the second supplies its framed-action geometry and material. Do not combine them unless a deliberate hybrid is required. The same preset identity continues through service cards, media scrims, feature strips, callout bars, native action controls, and dialogs; color still comes only from the active theme and mode tokens.
+
+All modifiers consume the active theme and mode tokens. Keep controls as real links or buttons, provide useful accessible names, mark decorative medallions with `aria-hidden="true"`, and avoid placing essential text in CSS artwork. The shared containment layer allows cards, strips, scrims, callouts, controls, and preset-specific specimens to shrink inside consumer-owned grids; application layout remains responsible for choosing the outer column count.
+
 ## Modes
 
 ```txt
@@ -292,9 +398,9 @@ contrast
 
 ## Native HTML coverage
 
-`styles/native-elements.css` owns the shared native selectors under `[data-ui][data-theme][data-mode]`. Each style system maps those selectors to its visual identity through `--usk-native-*` tokens, so native controls keep the same coverage while inheriting each preset's radius, shadows, borders, typography, and color surfaces.
+`styles/native-elements.css` owns the shared native selectors under `[data-ui][data-mode]`; `data-theme` is optional. Each style system maps the complete `--usk-native-*` identity contract, so choices, selects, ranges, progress, meters, file/color/date launch controls, indicators, and scrollbars inherit preset-specific geometry, material, borders, depth, typography, and either the active theme or the preset's accessible fallback palette. Browser/OS popup internals remain platform-owned.
 
-`styles/content-overflow.css` owns the shared text containment contract under `[data-ui][data-theme][data-mode]`. It keeps headings, paragraphs, links, table cells, controls, badges, nav links, and common UI wrappers from widening their parent wrapper when content contains long words, hashes, URLs, or copyable tokens.
+`styles/content-overflow.css` owns the shared text containment contract under `[data-ui][data-mode]`, with or without `data-theme`. Text and compact controls use `overflow-wrap: break-word` with normal word boundaries so long hashes, URLs, and copyable tokens wrap only when necessary. Structural wrappers receive shrink constraints without inheriting a forced wrapping policy.
 
 The shared native layer covers common native elements, including:
 
@@ -325,7 +431,7 @@ Every style includes theme-driven spinner utilities:
 <button class="saas-button saas-button-primary" aria-busy="true">Saving</button>
 ```
 
-Spinner track, stroke, and accent colors come from the active `data-theme` and `data-mode`. The generic `.ui-spinner`, `.loading-spinner`, and `[data-loading-spinner]` hooks are also themed inside any `[data-ui="..."]` scope.
+Spinner track, stroke, and accent colors come from the native palette or active `data-theme` and `data-mode`, while geometry, motion cadence, depth, and busy-button indicators follow the active UI preset. The generic `.ui-spinner`, `.loading-spinner`, and `[data-loading-spinner]` hooks receive the same preset identity inside any `[data-ui="..."]` scope.
 
 ## Tooltip surfaces
 
@@ -433,14 +539,26 @@ The checked-in demo, favicon pack, and social preview image stay in the reposito
 
 ```bash
 npm run check
+npm run check:compat
 npm run test:e2e
+npm run test:e2e:full
 npm run test:axe
-npm run test:visual
+npm run test:axe:full
+npm run test:visual:full
 npm run test:matrix
+npm run test:matrix:block -- --block 33
+npm run test:matrix:case -- --case 3245
+npm run test:matrix:range -- --from 3201 --to 3244
+npm run release:verify
+npm run release:verify:full
 npm run pack:dry-run
 ```
 
-`npm run check` rebuilds the bundles, runs stylelint, verifies package metadata, checks the documented class API, and validates contrast for base text/link pairs and filled component `on-*` pairs. Browser release gates add all-engine Playwright coverage, representative Axe scans, curated visual smoke checks, and the sharded `11 presets x 10 themes x 3 modes x 3 engines` matrix.
+`npm run check` rebuilds the bundles, runs stylelint, verifies package metadata and the documented class API, validates 4.5:1 text/link/filled-component contrast plus 3:1 light-mode component-edge contrast, and invokes `check:compat` for every generated entrypoint. `npm run test:e2e` is the bounded release smoke path: a curated Chromium-only Playwright suite that covers representative accessibility scans, demo switching, semantic runtime contracts, and the regression-prone preset checks. `npm run test:e2e:full` keeps the exhaustive Chromium/Firefox/WebKit suite available for explicit manual review. `npm run test:visual:full` preserves the historical visual-baseline suite for deliberate manual demo review; it is not part of the default PR, tag, or npm publish gate.
+
+The full UI matrix is intentionally opt-in. Local matrix checks are divided into 36 stable blocks of 100 cases. `npm run test:matrix` runs the blocks in order and stops after the first failing block; use `-- --from-block N` to start at any untested block without repeating earlier green blocks. Each test title includes a stable global case number. Rerun only each failing case with `npm run test:matrix:case -- --case N`; because the other cases in that block have already completed, continue at the next block after the targeted fixes pass. Use `test:matrix:range` only when a bounded follow-up range is useful. `test:matrix:raw` is reserved for the manual sharded automation workflow.
+
+The package browser policy is the last two major Chrome, Edge, and Firefox releases plus Safari and iOS 16 or newer, excluding dead browsers. The build resolves that single `package.json` policy into Lightning CSS targets, while `check:compat` verifies required prefix pairs, stable fallbacks, guarded `color-mix()`, `text-wrap`, and `forced-color-adjust` enhancements, and the absence of obsolete intrinsic CTA sizing declarations.
 
 ## v2.1.0 Architecture Notes
 

package/STYLE-MAP.md

@@ -11,7 +11,7 @@ Lead with stable semantic classes when an interface can switch visual presets:
 </article>
 ```
 
-Changing only the ancestor `data-ui` value restyles that markup across all 11 presets in the generated default, visual, and with-bridge bundles. A generated `visual/<preset>.css` focused entrypoint supplies the same semantic aliases for its selected preset only. Raw `styles/*` and standalone preset exports remain advanced prefixed APIs and do not promise multi-preset semantic switching.
+Changing only the ancestor `data-ui` value restyles that markup across all 20 presets in the generated default, visual, and with-bridge bundles. A generated `visual/<preset>.css` focused entrypoint supplies the same semantic aliases for its selected preset only. Raw `styles/*` and standalone preset exports remain advanced prefixed APIs and do not promise multi-preset semantic switching.
 
 ## UI systems
 
@@ -30,6 +30,19 @@ Color schemes are defined once in `styles/theme-colors.css`. Native HTML fallbac
 | Cyberpunk | `cyberpunk` | `cyber` | `styles/cyberpunk.css` |
 | Y2K | `y2k` | `y2k` | `styles/y2k.css` |
 | Retro Glass | `retro-glass` | `rg` | `styles/retro-glass.css` |
+| Editorial Luxe | `editorial-luxe` | `luxe` | `styles/editorial-luxe.css` |
+| Organic Modern | `organic-modern` | `organic` | `styles/organic-modern.css` |
+| Industrial Utility | `industrial-utility` | `utility` | `styles/industrial-utility.css` |
+| Technical Blueprint | `technical-blueprint` | `blueprint` | `styles/technical-blueprint.css` |
+| Art Deco | `art-deco` | `deco` | `styles/art-deco.css` |
+| Clay | `clay` | `clay` | `styles/clay.css` |
+| Data Terminal | `data-terminal` | `terminal` | `styles/data-terminal.css` |
+| Paper Editorial | `paper-editorial` | `paper` | `styles/paper-editorial.css` |
+| Neo-Noir | `neo-noir` | `noir` | `styles/neo-noir.css` |
+
+Each row is also bound to an internal six-axis template signature covering typography, density, geometry, material, feedback, and data presentation. The release contracts compare every preset pair across those visible axes and require substantial differences across the 48-token native-control identity surface. Color remains owned by the active semantic theme and mode rather than by a fixed preset palette.
+
+The release registry turns those signatures into executable reference traits. Each trait checks a real selector, property, and required value fragment. Preset-scoped browser cases isolate each viewport, mode, and cross-preset comparison.
 
 ## Shared color file
 
@@ -43,15 +56,15 @@ Color schemes are defined once in `styles/theme-colors.css`. Native HTML fallbac
 |---|---|
 | Shared native HTML element fallback selectors | `styles/native-elements.css` |
 
-Native selectors stay generic under `[data-ui][data-theme][data-mode]`. Presets only provide token mappings such as `--usk-native-surface`, `--usk-native-radius`, and `--usk-native-shadow`, which avoids repeating the same fieldset, table, dialog, details, form, and semantic-element rules in every UI file.
+Native selectors stay generic under `[data-ui][data-mode]`; `data-theme` is optional. Every preset maps the complete choice, select, range, progress, meter, file, color, indicator, and scrollbar identity token set while retaining theme-owned color channels. The shared `--ui-color-bg` handshake uses the preset's `--usk-native-bg` mapping in both native and named-theme mode. Vendor selectors remain safely separated.
 
 ## Shared overflow layer
 
 | Purpose | Import |
 |---|---|
-| Shared long-text containment for UI wrappers and controls | `styles/content-overflow.css` |
+| Shared long-text containment for text and controls | `styles/content-overflow.css` |
 
-The overflow layer keeps headings, paragraphs, links, table cells, controls, badges, nav links, and common layout wrappers from widening the page when content includes long tokens or URLs.
+The overflow layer uses `break-word` with normal word boundaries for text and compact controls. Layout wrappers keep only their shrink constraints, avoiding inherited emergency wrapping across entire component trees.
 
 ## Bridge bundle
 
@@ -73,6 +86,16 @@ The bridge inherits from shared `--usk-*` color roles, then applies `.interactiv
 - `rose-quartz`
 - `cyber-lime`
 - `arctic-indigo`
+- `chrome-navy`
+- `recycled-emerald`
+- `industrial-orange`
+- `performance-red`
+- `heritage-brass`
+- `service-blue-red`
+- `newsprint-crimson`
+- `foundry-amber`
+- `soft-orchid`
+- `electric-noir`
 
 ## Modes
 
@@ -82,7 +105,7 @@ The bridge inherits from shared `--usk-*` color roles, then applies `.interactiv
 
 ## Semantic component contract
 
-The machine-readable source of truth is `manifest.json#semanticComponentApi`. Its 29 implemented generic selectors map only to source suffixes with 11-of-11 composed preset coverage. The `implementationStatus` section records `.ui-spinner` and `.ui-tooltip` as retained hooks, the other 27 selectors as generated aliases, and no pending selectors.
+The machine-readable source of truth is `manifest.json#semanticComponentApi`. Its 29 implemented generic selectors map only to source suffixes with 20-of-20 composed preset coverage. The `implementationStatus` section records `.ui-spinner` and `.ui-tooltip` as retained hooks, the other 27 selectors as generated aliases, and no pending selectors.
 
 | Role | Generic selector -> current source suffix |
 |---|---|