ui-style-kit-css 2.2.0 → 2.3.0

package/docs/ECOSYSTEM.md

@@ -14,11 +14,11 @@ The pinned Interactive Surface and Layout commits are published merge objects. B
 
 | Library | Current 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.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 |
 
-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`.
+The current combination is `ui-style-kit-css@2.3.0`, `interactive-surface-css@1.6.0`, and `layout-style-css@3.1.0`. UI Style Kit `2.3.0` is the current release target; the companion versions are published releases. 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`.
 
 ## Layout-to-visual pairing matrix
 
@@ -88,3 +88,7 @@ import "layout-style-css";
 - Layout Style CSS owns structural wrappers, layout recipes, grids, app shells, and section composition.
 
 The canonical theme bridge does not make Interactive Surface a dependency of UI Style Kit. It only maps shared `--usk-*` roles to `--interactive-surface-*` tokens and provides paint; `state-core.css` continues to own interaction mechanics. The older `interactive-surface-bridge` and `with-bridge` exports are deprecated compatibility paths whose stateful behavior remains unchanged.
+
+## Canonical ownership order
+
+Load UI visual CSS first, UI interaction-theme paint second, Interactive Surface state core third, Layout CSS fourth, and application overrides last. Layout `3.1.0` no longer exports `integrations/ui-style-kit.css` or `legacy.css`; use its root or supported `foundation.css`, wrapper, primitive, recipe, utility, and personality entrypoints.

package/docs/PUBLISHING.md

@@ -1,5 +1,11 @@
 # Publishing Guide
 
+## 2.3.0 release workflow
+
+Prepare `ui-style-kit-css@2.3.0` on its release branch, open a pull request against `main`, and merge only after the complete gate is green. The aligned companion set is `layout-style-css@3.1.0` and `interactive-surface-css@1.6.0`.
+
+Do not push `v2.3.0` before the reviewed release commit is on `main`. A pushed version tag runs Release Version Alignment, which validates the tag/package/changelog contract and creates the GitHub Release; publishing that release triggers the protected npm workflow.
+
 ## Dry run
 
 ```bash
@@ -8,21 +14,21 @@ npm run release:verify
 
 `npm run release:verify` is the non-publishing release gate. It runs `npm run check`, `npm run test:e2e`, `npm run test:axe`, `npm run test:visual`, `npm run test:matrix`, the explicit UI-candidate release preflight, `npm audit --audit-level=moderate`, and `npm run pack:dry-run`.
 
-`npm run release:preflight` validates the shared manifests and compatibility contract, queries npm for every exact minimum/current version, resolves every export from the candidate tarball, checks maintained documentation against installed packages, and reuses the current/minimum clean-install browser matrix. Normal UI preflight remains strict and queries `ui-style-kit-css@2.2.0` alongside every other documented exact version. The release workflows pass `--candidate-package ui-style-kit-css`, which excludes only that exact current version while it is absent from npm and still requires every published minimum and companion version. The gate performs no publish, tag, release, or deployment mutation and is therefore safe to execute on pull requests.
+`npm run release:preflight` validates the shared manifests and compatibility contract, queries npm for every exact minimum/current version, resolves every export from the candidate tarball, checks maintained documentation against installed packages, and reuses the current/minimum clean-install browser matrix. Normal UI preflight remains strict and queries `ui-style-kit-css@2.3.0` alongside every other documented exact version. The release workflows pass `--candidate-package ui-style-kit-css`, which excludes only that exact current version while it is absent from npm and still requires every published minimum and companion version. The gate performs no publish, tag, release, or deployment mutation and is therefore safe to execute on pull requests.
 
-`npm run check` rebuilds dist CSS, runs stylelint, executes package, class API, shared theme-color, and vendor-prefix unit checks, validates core text/link contrast pairs and filled component `on-*` contrast pairs, and confirms package metadata. Browser gates cover regular demo flows, representative Axe scans, curated visual smoke checks, and the sharded 990-combination matrix. `npm run check:ecosystem:packs` verifies standalone, pairwise, and all-three packed package compatibility for the canonical visual/theme/state/layout imports and the deprecated bridge imports in both supported matrices. `npm run pack:dry-run` shows the exact files that would publish.
+`npm run check` rebuilds dist CSS, runs stylelint, executes package and API contracts, validates all theme/mode contrast pairs, enforces the Browserslist compatibility contract through `check:compat`, verifies CSS ownership, and confirms package metadata. Browser gates cover regular demo flows, representative Axe scans, curated visual checks, and the sharded 3,600-combination matrix. `npm run check:ecosystem:packs` verifies standalone, pairwise, and all-three packed package compatibility for canonical visual/theme/state/layout imports and deprecated bridge imports in both supported matrices. `npm run pack:dry-run` shows the exact files that would publish.
 
 `npm run check:ecosystem:current` packs this repository and the sibling `../Layout-Style-CSS` and `../Interactive-Surface-CSS` checkouts. It extracts imports from the explicitly maintained current documentation in all three repositories and resolves every documented specifier from the installed tarballs. Deprecated UI bridge guides are validated as a separate supported-compatibility class; changelogs and Layout migration guides are reviewed historical material rather than current setup. Use `-- --ui-spec <specifier>`, `-- --layout-repo <path>`, `-- --layout-spec <specifier>`, `-- --interactive-spec <specifier>`, `-- --interactive-repo <path>`, `-- --layout-docs-repo <path>`, or `-- --interactive-docs-repo <path>` when validating different package or documentation sources.
 
 `npm run check:ecosystem:minimum` downloads and repacks the declared minimum published runtime versions: `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`. Those tarballs predate the additive shared-manifest policy introduced on the coordinated branches, so the minimum matrix validates their exact installed versions and published CSS entry points; current packed heads retain the stricter manifest-schema and current-documentation checks. `npm run check:ecosystem:packs` runs current first and minimum second.
 
-The current matrix checks `ui-style-kit-css@2.2.0` as the active candidate only while its exact npm version is absent, `interactive-surface-css@1.6.0` as a published release, and `layout-style-css@3.0.1` as a published release. UI Style Kit `2.2.0` remains the current package version. The minimum published matrix remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
+The current matrix checks `ui-style-kit-css@2.3.0` as the active candidate only while its exact npm version is absent, `interactive-surface-css@1.6.0` as a published release, and `layout-style-css@3.1.0` as a published release. The minimum published matrix remains `ui-style-kit-css@2.1.0`, `interactive-surface-css@1.5.0`, and `layout-style-css@3.0.0`.
 
 Both matrices install fresh tarball consumers for UI only, Interaction only, Layout only, every pair, and all three. Chromium then checks selected theme paint, native and prefixed components, interaction focus/disabled/loading/selected/persistent states, Layout wrappers/primitives/recipes/personalities, console cleanliness, and an empty external-request log. Three text-free baselines under `tests/snapshots/clean-install/` cover the highest-risk integrated combinations.
 
 Snapshot verification decodes PNG pixels, requires exact dimensions, ignores pixelmatch-classified antialias noise, uses a `0.1` color threshold, and permits at most `0.25%` differing pixels. The committed fixtures render at 720-721 by 261 pixels and therefore allow 469-470 changed pixels while rejecting the tested 42% meaningful change. A mismatch retains both `SCENARIO-actual.png` and `SCENARIO-diff.png` in the reported safe temporary directory. CI only validates committed baselines and never passes the generation flag. To intentionally refresh them locally, run the current checker with `--update-snapshots`, inspect all three images, and rerun without that flag.
 
-The PR integration and npm-publish workflows read the companion repository and immutable revision pins from `ecosystem-compatibility.json`, then pack those coordinated reviewed artifacts. Advance those pins whenever a later release changes a companion contract. The current values pin the published Interactive Surface CSS merge at `b50a60d8ffd804d8227b1a16903c394556b88511` and the published Layout Style CSS merge at `44c34693554879790c54a6205b37160ff63a1747`.
+The PR integration and npm-publish workflows read the companion repository and immutable revision pins from `ecosystem-compatibility.json`, then pack those coordinated reviewed artifacts. Advance those pins whenever a later release changes a companion contract. The current values pin the published Interactive Surface CSS merge at `b50a60d8ffd804d8227b1a16903c394556b88511` and the published Layout Style CSS merge at `afcb1fdf70d4635e35739e621ee1598400fed103`.
 
 Use this exact bootstrap and merge sequence:
 
@@ -33,15 +39,13 @@ Use this exact bootstrap and merge sequence:
 
 The workflows enforce immutable remote-object reachability and do not fall back to mutable branches or registry packages. The stable bootstrap ref lets companion workflows load the reviewed preflight implementation before the final UI commit references their heads.
 
-`npm run build` uses exactly pinned CSS Tree parsing and Lightning CSS formatting/minification. Generated minified bundles retain the release banner while preserving grammar-sensitive selector and `calc()` whitespace.
+`npm run build` synchronizes manifest-driven component and overflow inventories and uses exactly pinned CSS Tree parsing and Lightning CSS formatting/minification. Every transform resolves the package Browserslist policy through `browserslistToTargets`. Generated minified bundles retain the release banner while preserving grammar-sensitive selector and `calc()` whitespace.
 
 The npm artifact is library-focused: `dist/`, `styles/`, docs, and metadata. Demo pages, favicon source assets, and social preview images remain checked in for GitHub Pages but are excluded from the tarball to keep package installs small.
 
 ## Publish
 
-No package, tag, or registry release occurs without explicit approval.
-
-The completed 2.0.4 correctness hotfix is historical context. Do not create replacement tags or registry releases merely to verify the coordinated compatibility contract.
+No package, tag, or registry release occurs without explicit approval. Release tags must use the `v<package-version>` form and point to the reviewed commit on `main`.
 
 Run the coordinated checked-out ecosystem proof from this repository:
 
@@ -53,7 +57,7 @@ npm run check:ecosystem:packs -- --layout-repo ../Layout-Style-CSS --interactive
 npm publish
 ```
 
-`prepublishOnly` runs `npm run release:verify`, so a direct `npm publish` still has the full release gate. For GitHub releases, create or dispatch a release for the matching package tag, such as `v2.2.0`. The release workflows verify that `package.json`, `package-lock.json`, `CHANGELOG.md`, and generated dist banners are aligned before publishing.
+`prepublishOnly` runs `npm run release:verify`, so a direct `npm publish` still has the full release gate. For GitHub releases, push or dispatch the matching package tag, such as `v2.3.0`, only after the release PR is merged. The release workflows verify that `package.json`, `package-lock.json`, `CHANGELOG.md`, generated dist banners, and ecosystem pins are aligned before publishing.
 
 ## Versioning
 
@@ -63,4 +67,4 @@ npm run release:minor
 npm run release:major
 ```
 
-Use patch for fixes, minor for new themes/styles, and major for breaking public API changes. The 2.x release line is major because color-scheme authoring moved from per-UI `--<prefix>-*-rgb` blocks to shared `--usk-*-rgb` roles in `styles/theme-colors.css`.
+Use patch for compatible fixes, minor for new themes, presets, component capabilities, or browser-support contracts, and major for incompatible public API changes. The nine additional presets, ten additional schemes, universal component vocabulary, and compatibility contract make `2.3.0` a minor release.

package/docs/STYLE-GUIDE.md

@@ -2,22 +2,62 @@
 
 | UI style | Best for |
 |---|---|
-| Minimal SaaS | Dashboards, admin tools, SaaS apps, documentation, internal systems |
-| Bento UI | Landing pages, portfolio sections, feature pages, product showcases |
-| Maximalist / Playful | Creators, entertainment brands, events, bold client sites |
-| Bauhaus / Swiss Modern | Agencies, artists, editorial pages, design-forward brands |
-| Tactile / Skeuomorphic | Premium sites, distinctive client interfaces, control-panel metaphors |
-| Neumorphism | Soft dashboards, experimental UI, visual demos |
-| Retrofuturism | Futuristic product pages, portfolios, technology showcases |
-| Brutalism | Bold landing pages, anti-template websites, creative brands |
-| Cyberpunk | Security, gaming, encryption, developer demos, nightlife/tech branding |
-| Y2K | Nostalgic, playful, music/fashion/event sites |
-| Retro Glass | Futuristic premium apps, glass dashboards, hero sections |
-
-All styles share the same 10 color schemes through `styles/theme-colors.css`, so changing `data-theme` affects the active color scheme independently from the selected UI treatment.
+| Minimal SaaS | Dashboards, admin tools, SaaS apps |
+| Bento UI | Landing pages, feature sections, showcases |
+| Maximalist / Playful | Creators, entertainment, bold client sites |
+| Bauhaus / Swiss Modern | Agencies, editorial layouts, design-forward brands |
+| Skeuomorphic / Tactile | Premium tactile interfaces, control panels |
+| Neumorphism | Soft dashboards, experimental UI |
+| Retrofuturism | Futuristic portfolios and product pages |
+| Brutalism | Bold creative websites |
+| Cyberpunk | Security, gaming, encryption, tech demos |
+| Y2K | Nostalgic, playful, fashion/music/event sites |
+| Retro Glass | Futuristic glass dashboards and hero sections |
+| Editorial Luxe | Luxury brands, architecture, hospitality, premium editorial sites |
+| Organic Modern | Wellness, sustainability, hospitality, natural product brands |
+| Industrial Utility | Operations software, manufacturing, logistics, fleet and equipment systems |
+| Technical Blueprint | Engineering, architecture, technical documentation, scientific tools |
+| Art Deco | Luxury, hospitality, heritage brands, events and distinctive showcases |
+| Clay | Friendly SaaS, collaborative tools, education and approachable product sites |
+| Data Terminal | Operator consoles, telemetry, infrastructure, monitoring and developer tools |
+| Paper Editorial | News, magazines, journals, cultural sites and story-led publishing |
+| Neo-Noir | Cinematic portfolios, nightlife, premium creative studios and dramatic product sites |
+
+All styles share the same 20 color schemes through `styles/theme-colors.css`, so changing `data-theme` affects the active color scheme independently from the selected UI treatment.
 
 Use `data-mode="contrast"` for high-contrast variants and pair it with semantic HTML for best accessibility outcomes.
 
+## Preset identity and component roles
+
+UI presets own geometry, material, spacing, depth, and typographic character. Color schemes own semantic color roles. A preset should therefore remain recognizable when its `data-theme` changes, while every component continues to consume the active theme tokens instead of fixed artwork colors.
+
+| UI style | Repeated component identity |
+|---|---|
+| Minimal SaaS | Restrained single-corner folds and low-elevation outlines |
+| Bento UI | Stepped tile edges and compact block composition |
+| Maximalist / Playful | Skewed silhouettes, layered fills and pronounced shadows |
+| Bauhaus / Swiss Modern | Asymmetric primary geometry and hard-edged composition |
+| Skeuomorphic / Tactile | Chamfered physical keys, bevels and pressed depth |
+| Neumorphism | Softly clipped surfaces with raised and inset shadows |
+| Retrofuturism | Elongated console geometry and metallic rims |
+| Brutalism | Blunt cuts, thick borders and offset shadows |
+| Cyberpunk | Multi-notch technical polygons and luminous edges |
+| Y2K | Glossy capsule geometry and playful depth |
+| Retro Glass | Frosted angular tabs with inner highlights |
+| Editorial Luxe | Slim bookplates, hairlines and restrained framing |
+| Organic Modern | Asymmetric pebble and leaf contours with soft depth |
+| Industrial Utility | Octagonal hazard-control geometry and dense framing |
+| Technical Blueprint | Drafting-corner outlines and technical markings |
+| Art Deco | Symmetric chevrons and double-rule framing |
+| Clay | Inflated clipped pills and chunky soft shadows |
+| Data Terminal | Terminal brackets and luminous operator outlines |
+| Paper Editorial | Ticket or tab notches with inked offset edges |
+| Neo-Noir | Cinematic slants and high-contrast edge lighting |
+
+For filled service actions, compose `<prefix>-button`, `<prefix>-button-primary`, and `<prefix>-button-cut`. For framed callout actions, compose `<prefix>-button` and `<prefix>-button-outline-heavy`. These modifiers are independent; the library does not expose a `button-cta` class. Carry the same preset identity into service cards, media scrims, feature strips, callout bars, native actions, and dialogs rather than treating each specimen as isolated artwork.
+
+Preset-specific grids must size from their own container. Bento feature tiles, for example, use intrinsic columns and only introduce a feature span when their container can support it, preventing metric labels from collapsing into vertical text.
+
 ## Visual regression baseline
 
 The repository includes optional Playwright visual smoke checks:

package/docs/TOKENS.md

@@ -63,6 +63,15 @@ UI Style Kit entrypoints publish all 12 values. Standalone consumer packages mus
 | Cyberpunk | `cyber` |
 | Y2K | `y2k` |
 | Retro Glass | `rg` |
+| Editorial Luxe | `luxe` |
+| Organic Modern | `organic` |
+| Industrial Utility | `utility` |
+| Technical Blueprint | `blueprint` |
+| Art Deco | `deco` |
+| Clay | `clay` |
+| Data Terminal | `terminal` |
+| Paper Editorial | `paper` |
+| Neo-Noir | `noir` |
 
 ## Stable functional tokens
 
@@ -243,7 +252,7 @@ Loading indicators use theme variables by default:
 --<prefix>-spinner-accent
 ```
 
-The class utilities are `<prefix>-spinner`, `<prefix>-loading-spinner`, `<prefix>-spinner-sm`, and `<prefix>-spinner-lg`. Native buttons and prefixed buttons also render an inline spinner when `aria-busy="true"` is present.
+The class utilities are `<prefix>-spinner`, `<prefix>-loading-spinner`, `<prefix>-spinner-sm`, and `<prefix>-spinner-lg`. Each preset owns its loader silhouette, cadence, and depth while consuming only these active theme roles. Native buttons and prefixed buttons render the matching preset-owned indicator when `aria-busy="true"` is present.
 
 ## Interactive Surface bridge tokens