ui-style-kit-css 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to **UI Style Kit CSS** will be documented here.
 
+## [Unreleased]
+
+## [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.6.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.
+- 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.
+
+### Changed
+
+- Clarified that generated default, visual, with-bridge, and focused entrypoints provide semantic aliases, while raw preset sources, partial extras, and deprecated structural aliases remain prefixed compatibility or advanced APIs.
+- Preserved `.ui-spinner` and `.ui-tooltip` as retained hooks while generating the other 27 selectors from existing preset declarations.
+
 ## [2.1.0] - 2026-07-20
 
 ### Added

package/README.md

@@ -5,17 +5,17 @@
 
 **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
 
-`v2.1.0` introduces a visual-only public API, a machine-readable capability manifest, a five-layer build architecture, and a canonical token-only Interactive Surface theme bridge. Existing default and focused entrypoints remain compatible, including their deprecated structural helpers, and parser-based minification remains exactly pinned.
+`v2.3.0` expands the library to 20 UI style systems and 20 shared color schemes, adds a universal commercial component vocabulary and a declared modern-browser support floor, and grows the browser matrix to 3,600 preset/theme/mode/engine combinations. Existing default, focused, visual-only, and bridge entrypoints remain compatible, and parser-based minification remains exactly pinned.
 
 [Showcase website](https://foscat.github.io/ui-style-kit-css/)
 
 ## How the library fits together
 
-UI Style Kit CSS owns visual identity: themes, component paint, native HTML styling, and the prefixed class API. It can be used alone, or paired with the sibling libraries when a project needs structural layout primitives or richer interaction-state behavior.
+UI Style Kit CSS owns visual identity: themes, semantic `.ui-*` component paint, native HTML styling, and the advanced prefixed class API. It can be used alone, or paired with the sibling libraries when a project needs structural layout primitives or richer interaction-state behavior.
 
 ```mermaid
 flowchart LR
@@ -50,20 +50,24 @@ These libraries stay standalone, but the current aligned set is:
 
 | Library | Aligned version | Owns |
 |---|---:|---|
-| `ui-style-kit-css@2.1.0` | staged source target | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
-| `interactive-surface-css@1.5.0` | published release | interaction-state primitives, surface behavior, state layers, and input affordances |
-| `layout-style-css@2.1.0` | staged source target | structural wrappers, grids, sections, app shells, and layout recipes |
+| `ui-style-kit-css@2.3.0` | current release target | visual identity, color themes, UI paint, native HTML styling, content wrapping, and bridge tokens |
+| `interactive-surface-css@1.6.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 |
 
-UI Style Kit `2.1.0` and Layout Style `2.1.0` remain staged source targets until their release approvals complete. Interactive Surface `1.5.0` is the released companion state engine for this upgrade path.
+UI Style Kit `2.3.0` is the current release target and is verified with Interactive Surface `1.6.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.
 
+Every UI Style Kit visual or preset entrypoint also publishes a small, fully typed `--ui-*` semantic handshake. These tokens let companion libraries and third-party themes share paint, control geometry, focus, and default motion without depending on preset-specific names. They are optional fallbacks for consumers: package-specific tokens still take precedence, and standalone packages keep their existing legacy and literal defaults when the handshake is absent. See the [token contract](docs/TOKENS.md#shared-semantic-token-handshake) for the exact 12-token inventory.
+
+A third-party producer can load its semantic token stylesheet before `interactive-surface-css/standalone-preset.css`. UI Style Kit's visual entrypoints support the same portable composition; keep the canonical theme bridge with `state-core.css` when specialized variant, level, and icon-role mappings are required.
+
 For import order, ownership boundaries, and adoption paths, see the [Ecosystem guide](docs/ECOSYSTEM.md).
 
 ## Features
 
-- 11 UI style systems
-- 10 shared color schemes
+- 20 UI style systems
+- 20 shared color schemes
 - `light`, `dark`, and `contrast` modes
 - Combined CSS bundle and per-style production imports
 - Visual-only full and focused entrypoints for consumer-owned layouts
@@ -77,7 +81,7 @@ For import order, ownership boundaries, and adoption paths, see the [Ecosystem g
 - Visible tooltip classes and native `[role="tooltip"]` styling inside each UI scope
 - Font-family override variables for body, headings, controls, and mono text
 - Canonical token-and-paint-only theme bridge for `interactive-surface-css/state-core.css`
-- Deprecated stateful bridge exports retained unchanged for backward compatibility
+- Deprecated stateful bridge exports retained for backward compatibility
 - Reduced-motion, high-contrast, forced-colors, and print support
 - Cascade-layered CSS for easier consumer overrides
 - No runtime dependencies
@@ -88,64 +92,67 @@ For import order, ownership boundaries, and adoption paths, see the [Ecosystem g
 npm install ui-style-kit-css
 ```
 
+### v2 distribution defaults
+
+The default bundle remains unchanged for all v2 releases. The root package and canonical `.` export resolve to the readable `dist/ui-style-kit.css`; the canonical `./min.css` export resolves to the minified `dist/ui-style-kit.min.css`. The focused `visual/<preset>.css` entrypoints remain available for applications fixed to one visual system.
+
+`ui-style-kit-css/visual.css` is the recommended entrypoint when consumers own layout. Making `visual.css` the package default remains only a v3 proposal; no v2 export is redirected as part of that proposal.
+
+The `./css`, `./css.css`, and `./min` exports are redundant deprecated compatibility aliases. They remain available throughout v2 with their existing targets: `./css` and `./css.css` match `.`, while `./min` matches `./min.css`. New integrations should use the canonical exports.
+
 ## Import
 
-Use a single style import for production apps that use one visual system:
+Use the generated default bundle for semantic components that can switch across every preset at runtime:
 
 ```js
-import "ui-style-kit-css/minimal-saas.css";
+import "ui-style-kit-css";
 ```
 
-The existing focused entrypoints retain the v2 structural helpers. New integrations that already own layout should use a focused visual-only entrypoint:
+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:
 
 ```js
 import "ui-style-kit-css/visual/minimal-saas.css";
 ```
 
-Use `ui-style-kit-css/visual.css` for runtime preset switching without the deprecated prefixed layout selectors. The exact preset, theme, mode, class, and native-part capability matrix is available from `ui-style-kit-css/manifest.json`.
+The exact preset, theme, mode, class, and native-part capability matrix is available from `ui-style-kit-css/manifest.json`.
+
+### Advanced prefixed and raw imports
 
-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:
+The standalone preset exports and longer `styles/*` paths remain advanced compatibility entrypoints. They preserve the prefixed API and do not promise multi-preset semantic switching:
 
 ```js
-import "ui-style-kit-css/theme-colors.css";
-import "ui-style-kit-css/native-elements.css";
-import "ui-style-kit-css/content-overflow.css";
 import "ui-style-kit-css/minimal-saas.css";
+// Equivalent raw source export:
+import "ui-style-kit-css/styles/minimal-saas.css";
 ```
 
-The longer `styles/*` paths are also exported:
+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/styles/minimal-saas.css";
-import "ui-style-kit-css/styles/cyberpunk.css";
+import "ui-style-kit-css/theme-colors.css";
+import "ui-style-kit-css/native-elements.css";
+import "ui-style-kit-css/content-overflow.css";
+import "ui-style-kit-css/minimal-saas.css";
 ```
 
-Use the full bundle when users need to switch `data-ui` systems at runtime:
+The explicit distribution path is also available for runtime switching:
 
 ```js
 import "ui-style-kit-css/dist/ui-style-kit.css";
 ```
 
-For the canonical state-only integration, import visual paint, the token-only theme bridge, and Interactive Surface state mechanics as separate ownership layers:
+For the canonical all-three integration, import visual paint, the token-only theme bridge, Interactive Surface state mechanics, and Layout structure in this order:
 
 ```js
-import "ui-style-kit-css/visual/minimal-saas.css";
+import "ui-style-kit-css/visual.css";
 import "ui-style-kit-css/interactive-surface-theme.css";
 import "interactive-surface-css/state-core.css";
+import "layout-style-css";
 ```
 
-The older stateful bridge and combined bundle remain available for compatibility, but they are deprecated and have not been redirected to the token-only behavior:
-
-```js
-import "ui-style-kit-css/with-bridge.css";
-```
-
-Or import the bridge by itself when you are using a single style file:
-
-```js
-import "ui-style-kit-css/minimal-saas.css";
-import "ui-style-kit-css/interactive-surface-bridge";
-```
+The older stateful bridge and combined bundle remain public, deprecated compatibility paths. See the [bridge migration guide](docs/BRIDGE-MIGRATION.md) when upgrading an existing v2 integration.
 
 The default and visual-only bundles do **not** include either bridge. That keeps UI paint independent and prevents accidental duplicate bridge imports.
 
@@ -155,12 +162,12 @@ 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` | ~299 KB | ~39 KB | Compatible runtime UI-system switchers and demos |
-| `ui-style-kit-css/visual.min.css` | ~290 KB | ~38 KB | Runtime visual switching with consumer-owned layout |
-| `ui-style-kit-css/with-bridge.css` | ~369 KB | ~44 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` | ~21 KB | ~3 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/dist/ui-style-kit.min.css` | ~855 KB | ~125 KB | Compatible runtime UI-system switchers and demos |
+| `ui-style-kit-css/visual.min.css` | ~841 KB | ~123 KB | Runtime visual switching with consumer-owned layout |
+| `ui-style-kit-css/with-bridge.css` | ~1015 KB | ~143 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` | ~24 KB | ~4 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` | ~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 |
 
@@ -175,22 +182,20 @@ 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.1.0/dist/ui-style-kit.min.css" />
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ui-style-kit-css@2.3.0/dist/ui-style-kit.min.css" />
 ```
 
 ## Basic usage
 
 ```html
 <body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="light">
-  <main class="saas-page">
-    <section class="saas-container saas-stack">
-      <article class="saas-card">
-        <h1 class="saas-title">UI Style Kit CSS</h1>
-        <p class="saas-subtitle">Switch UI systems, themes, and modes with attributes.</p>
-        <button class="saas-button saas-button-primary">Primary Action</button>
-        <span class="saas-spinner" aria-label="Loading"></span>
-      </article>
-    </section>
+  <main>
+    <article class="ui-card">
+      <h1>UI Style Kit CSS</h1>
+      <p>Switch UI systems, themes, and modes without changing component classes.</p>
+      <button class="ui-button" data-ui-variant="primary">Primary Action</button>
+      <span class="ui-spinner" role="status" aria-label="Loading"></span>
+    </article>
   </main>
 </body>
 ```
@@ -203,6 +208,47 @@ document.body.dataset.theme = "midnight-gold";
 document.body.dataset.mode = "dark";
 ```
 
+This changes the semantic components' visual preset without replacing their DOM nodes or rewriting their `.ui-*` classes.
+
+## 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 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 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.
+
+| Selector | `data-ui-variant` values |
+|---|---|
+| `.ui-button` | `primary`, `secondary`, `danger`, `ghost` |
+| `.ui-badge` | `primary`, `secondary`, `success`, `warning`, `danger` |
+| `.ui-alert` | `success`, `warning`, `danger` |
+
+```html
+<body data-ui="minimal-saas" data-theme="arctic-indigo" data-mode="light">
+  <button class="ui-button" data-ui-variant="primary">Save</button>
+  <article class="ui-card">...</article>
+</body>
+```
+
+Modal and dialog roles deliberately use a neutral native `<dialog>` fallback. There is no `.ui-modal` or `.ui-dialog` selector. The semantic API also does not define `data-ui-state`, `data-ui-size`, or `data-ui-placement`; continue to use native and ARIA state hooks, `.is-active`, and `[data-ui-tooltip-anchor]` where supported.
+
+Preset-prefixed classes remain supported compatibility and advanced APIs. Partial preset extras, typography and paint utilities, surface/size/placement helpers, shape and accessibility utilities, and the deprecated `page`, `container`, `section`, `grid`, `stack`, `cluster`, and `split` structural aliases remain prefix-bound rather than entering the generic contract.
+
+For example, a fixed Minimal SaaS integration may continue to use `<button class="saas-button saas-button-primary">`. Prefer `.ui-button` plus `data-ui-variant="primary"` when markup must survive runtime preset changes.
+
 ## UI systems
 
 | UI style | `data-ui` | Class prefix | Best for |
@@ -218,6 +264,15 @@ document.body.dataset.mode = "dark";
 | 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 |
+| Editorial Luxe | `editorial-luxe` | `luxe` | luxury brands, architecture, hospitality, premium editorial sites |
+| Organic Modern | `organic-modern` | `organic` | wellness, sustainability, hospitality, natural product brands |
+| Industrial Utility | `industrial-utility` | `utility` | operations software, manufacturing, logistics, fleet and equipment systems |
+| Technical Blueprint | `technical-blueprint` | `blueprint` | engineering, architecture, technical documentation, scientific tools |
+| Art Deco | `art-deco` | `deco` | luxury, hospitality, heritage brands, events and distinctive showcases |
+| Clay | `clay` | `clay` | friendly SaaS, collaborative tools, education and approachable product sites |
+| Data Terminal | `data-terminal` | `terminal` | operator consoles, telemetry, infrastructure, monitoring and developer tools |
+| Paper Editorial | `paper-editorial` | `paper` | news, magazines, journals, cultural sites and story-led publishing |
+| Neo-Noir | `neo-noir` | `noir` | cinematic portfolios, nightlife, premium creative studios and dramatic product sites |
 
 ## Color themes
 
@@ -232,10 +287,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
@@ -279,7 +391,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 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
 
@@ -387,6 +499,7 @@ 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:axe
 npm run test:visual
@@ -394,7 +507,9 @@ npm run test:matrix
 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. Browser release gates add all-engine Playwright coverage, representative Axe scans, curated visual smoke checks, and the sharded `20 presets x 20 themes x 3 modes x 3 engines` matrix.
+
+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

@@ -1,5 +1,18 @@
 # UI Style Kit CSS Style Map
 
+## Recommended runtime API
+
+Lead with stable semantic classes when an interface can switch visual presets:
+
+```html
+<article class="ui-card">
+  <button class="ui-button" data-ui-variant="primary">Continue</button>
+  <span class="ui-badge" data-ui-variant="success">Ready</span>
+</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.
+
 ## UI systems
 
 Color schemes are defined once in `styles/theme-colors.css`. Native HTML fallback selectors are defined once in `styles/native-elements.css`. Long-text containment rules are defined once in `styles/content-overflow.css`. Each UI system file imports all shared layers, aliases `--usk-*` RGB roles back to its prefix, and maps `--usk-native-*` tokens into the preset's visual identity.
@@ -17,6 +30,15 @@ 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` |
 
 ## Shared color file
 
@@ -60,9 +82,42 @@ 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
 
 - `light`
 - `dark`
 - `contrast`
+
+## 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.
+
+| Role | Generic selector -> current source suffix |
+|---|---|
+| Button | `.ui-button` -> `button`; `.ui-icon-button` -> `icon-button` |
+| Card | `.ui-card` -> `card` |
+| Form | `.ui-field` -> `field`; `.ui-label` -> `label`; `.ui-help-text` -> `help-text`; `.ui-input` -> `input`; `.ui-select` -> `select`; `.ui-textarea` -> `textarea` |
+| Choice control | `.ui-check` -> `check`; `.ui-check-control` -> `check-control`; `.ui-radio` -> `radio`; `.ui-radio-control` -> `radio-control`; `.ui-switch` -> `switch`; `.ui-switch-track` -> `switch-track`; `.ui-switch-thumb` -> `switch-thumb` |
+| Badge | `.ui-badge` -> `badge` |
+| Alert | `.ui-alert` -> `alert`; `.ui-alert-title` -> `alert-title`; `.ui-alert-body` -> `alert-body` |
+| Navigation | `.ui-nav` -> `nav`; `.ui-nav-link` -> `nav-link` |
+| Table | `.ui-table` -> `table`; `.ui-table-wrap` -> `table-wrap` |
+| Progress | `.ui-progress` -> `progress`; `.ui-progress-bar` -> `progress-bar` |
+| Toolbar | `.ui-toolbar` -> `toolbar` |
+| Loading | `.ui-spinner` -> `spinner` |
+| Tooltip | `.ui-tooltip` -> `tooltip` |
+
+`data-ui-variant` is the only new attribute. Omission means neutral. `.ui-button` accepts `primary`, `secondary`, `danger`, and `ghost`; `.ui-badge` accepts `primary`, `secondary`, `success`, `warning`, and `danger`; `.ui-alert` accepts `success`, `warning`, and `danger`.
+
+Modal and dialog roles retain native `<dialog>` as their one neutral fallback; `.ui-modal` and `.ui-dialog` are not defined. Preset-prefixed classes remain supported for compatibility and advanced use. Partial preset extras and the seven deprecated structural suffixes stay out of the semantic contract.