feat: implement ecosystem contract and prepare v2.2.0

.github/workflows/ci.yml

@@ -8,6 +8,9 @@ on:
     branches:
       - main
 
+permissions:
+  contents: read
+
 jobs:
   quality:
     name: Lint, Build, Unit Tests
@@ -34,6 +37,82 @@ jobs:
       - name: Run unit tests
         run: npm run test:unit
 
+  ecosystem-packs:
+    name: Packed Ecosystem Contract
+    needs: quality
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout UI Style Kit
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install UI Style Kit dependencies
+        run: npm ci
+
+      # The compatibility contract, rather than a mutable branch or release tag,
+      # selects the exact companion artifacts exercised by this integration job.
+      - name: Resolve immutable ecosystem fixture sources
+        id: ecosystem_sources
+        shell: bash
+        run: node scripts/write-ecosystem-workflow-outputs.mjs
+
+      # The companion commits must be pushed first; checking remote object reachability
+      # makes that sequencing failure explicit before Actions attempts a checkout.
+      - name: Require pushed companion commits before UI validation
+        shell: bash
+        env:
+          INTERACTIVE_REPOSITORY: ${{ steps.ecosystem_sources.outputs.interactive_repository }}
+          INTERACTIVE_REVISION: ${{ steps.ecosystem_sources.outputs.interactive_revision }}
+          LAYOUT_REPOSITORY: ${{ steps.ecosystem_sources.outputs.layout_repository }}
+          LAYOUT_REVISION: ${{ steps.ecosystem_sources.outputs.layout_revision }}
+        run: |
+          set -euo pipefail
+          for source in "${INTERACTIVE_REPOSITORY}:${INTERACTIVE_REVISION}" "${LAYOUT_REPOSITORY}:${LAYOUT_REVISION}"; do
+            repository="${source%%:*}"
+            revision="${source##*:}"
+            fixture_dir="$(mktemp -d)"
+            if ! git init --bare "${fixture_dir}" >/dev/null || ! git -C "${fixture_dir}" fetch --no-tags --depth=1 "https://github.com/${repository}.git" "${revision}" >/dev/null 2>&1 || ! git -C "${fixture_dir}" cat-file -e "${revision}^{commit}"; then
+              echo "::error::${repository}@${revision} is unavailable. Push the companion commit, verify its remote object, then push or validate this UI branch."
+              rm -rf "${fixture_dir}"
+              exit 1
+            fi
+            rm -rf "${fixture_dir}"
+          done
+
+      - name: Checkout Layout Style CSS contract fixture
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ steps.ecosystem_sources.outputs.layout_repository }}
+          ref: ${{ steps.ecosystem_sources.outputs.layout_revision }}
+          path: _ecosystem/Layout-Style-CSS
+
+      - name: Checkout Interactive Surface CSS contract fixture
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ steps.ecosystem_sources.outputs.interactive_repository }}
+          ref: ${{ steps.ecosystem_sources.outputs.interactive_revision }}
+          path: _ecosystem/Interactive-Surface-CSS
+
+      - name: Install Layout Style CSS fixture dependencies
+        working-directory: _ecosystem/Layout-Style-CSS
+        run: npm ci
+
+      - name: Install Interactive Surface CSS fixture dependencies
+        working-directory: _ecosystem/Interactive-Surface-CSS
+        run: npm ci
+
+      - name: Install clean-consumer browser
+        run: npx playwright install --with-deps chromium
+
+      # Explicit candidate mode exempts only the unpublished UI version; every companion version still comes from npm.
+      - name: Run PR-safe ecosystem release preflight
+        run: npm run release:preflight -- --candidate-package ui-style-kit-css --layout-repo $GITHUB_WORKSPACE/_ecosystem/Layout-Style-CSS --interactive-repo $GITHUB_WORKSPACE/_ecosystem/Interactive-Surface-CSS --layout-docs-repo $GITHUB_WORKSPACE/_ecosystem/Layout-Style-CSS --interactive-docs-repo $GITHUB_WORKSPACE/_ecosystem/Interactive-Surface-CSS
+
   playwright:
     name: Playwright E2E
     needs: quality

.github/workflows/npm-publish.yml

@@ -122,6 +122,13 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      # Release verification packs the immutable Task 4 companion artifacts
+      # selected by the checked-in compatibility contract.
+      - name: Resolve immutable ecosystem fixture sources
+        id: ecosystem_sources
+        shell: bash
+        run: node scripts/write-ecosystem-workflow-outputs.mjs
+
       - name: Check if version already exists on npm
         id: npm_version_check
         shell: bash
@@ -138,6 +145,30 @@ jobs:
             echo "${PACKAGE_NAME}@${PACKAGE_VERSION} is not published yet. Proceeding to publish."
           fi
 
+      # Publishing validates the same remote companion objects after they are
+      # pushed, so a release never substitutes a stale registry artifact.
+      - name: Require pushed companion commits before publish verification
+        if: steps.npm_version_check.outputs.already_published != 'true'
+        shell: bash
+        env:
+          INTERACTIVE_REPOSITORY: ${{ steps.ecosystem_sources.outputs.interactive_repository }}
+          INTERACTIVE_REVISION: ${{ steps.ecosystem_sources.outputs.interactive_revision }}
+          LAYOUT_REPOSITORY: ${{ steps.ecosystem_sources.outputs.layout_repository }}
+          LAYOUT_REVISION: ${{ steps.ecosystem_sources.outputs.layout_revision }}
+        run: |
+          set -euo pipefail
+          for source in "${INTERACTIVE_REPOSITORY}:${INTERACTIVE_REVISION}" "${LAYOUT_REPOSITORY}:${LAYOUT_REVISION}"; do
+            repository="${source%%:*}"
+            revision="${source##*:}"
+            fixture_dir="$(mktemp -d)"
+            if ! git init --bare "${fixture_dir}" >/dev/null || ! git -C "${fixture_dir}" fetch --no-tags --depth=1 "https://github.com/${repository}.git" "${revision}" >/dev/null 2>&1 || ! git -C "${fixture_dir}" cat-file -e "${revision}^{commit}"; then
+              echo "::error::${repository}@${revision} is unavailable. Push the companion commit and verify its remote object before publish verification."
+              rm -rf "${fixture_dir}"
+              exit 1
+            fi
+            rm -rf "${fixture_dir}"
+          done
+
       - name: Ensure npm token exists
         if: steps.npm_version_check.outputs.already_published != 'true'
         shell: bash
@@ -157,26 +188,48 @@ jobs:
         if: steps.npm_version_check.outputs.already_published != 'true'
         run: npm run test:e2e:install:ci
 
-      # The package prepublish gate runs packed ecosystem checks against the
-      # staged Layout Style CSS 2.1 line before this UI package reaches npm.
+      # Stage the immutable companion sources so the prepublish gate packs the
+      # coordinated artifacts and scans their explicitly maintained documentation.
       - name: Checkout Layout Style CSS for publish verification
         if: steps.npm_version_check.outputs.already_published != 'true'
         uses: actions/checkout@v6
         with:
-          repository: Foscat/Layout-Style-CSS
-          ref: 2.1.0
+          repository: ${{ steps.ecosystem_sources.outputs.layout_repository }}
+          ref: ${{ steps.ecosystem_sources.outputs.layout_revision }}
           path: _ecosystem/Layout-Style-CSS
 
+      - name: Checkout Interactive Surface CSS documentation for publish verification
+        if: steps.npm_version_check.outputs.already_published != 'true'
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ steps.ecosystem_sources.outputs.interactive_repository }}
+          ref: ${{ steps.ecosystem_sources.outputs.interactive_revision }}
+          path: _ecosystem/Interactive-Surface-CSS
+
       # Layout's prepack contract tests inspect its installed UI dependency, so
       # install its locked dependency graph before packing it as an ecosystem fixture.
       - name: Install Layout Style CSS dependencies for publish verification
         if: steps.npm_version_check.outputs.already_published != 'true'
         working-directory: _ecosystem/Layout-Style-CSS
         run: npm ci
 
+      - name: Install Interactive Surface CSS dependencies for publish verification
+        if: steps.npm_version_check.outputs.already_published != 'true'
+        working-directory: _ecosystem/Interactive-Surface-CSS
+        run: npm ci
+
+      # Explicit candidate mode exempts only the UI package being published; all
+      # minimum and companion versions must already resolve from npm.
+      - name: Run ecosystem release preflight
+        if: steps.npm_version_check.outputs.already_published != 'true'
+        run: npm run release:preflight -- --candidate-package ui-style-kit-css --layout-repo $GITHUB_WORKSPACE/_ecosystem/Layout-Style-CSS --interactive-repo $GITHUB_WORKSPACE/_ecosystem/Interactive-Surface-CSS --layout-docs-repo $GITHUB_WORKSPACE/_ecosystem/Layout-Style-CSS --interactive-docs-repo $GITHUB_WORKSPACE/_ecosystem/Interactive-Surface-CSS
+
       - name: Publish package
         if: steps.npm_version_check.outputs.already_published != 'true'
-        run: npm publish --access public
+        run: npm publish --access public --ignore-scripts
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
           UI_STYLE_KIT_LAYOUT_REPO: ${{ github.workspace }}/_ecosystem/Layout-Style-CSS
+          UI_STYLE_KIT_LAYOUT_DOCS_REPO: ${{ github.workspace }}/_ecosystem/Layout-Style-CSS
+          UI_STYLE_KIT_INTERACTIVE_REPO: ${{ github.workspace }}/_ecosystem/Interactive-Surface-CSS
+          UI_STYLE_KIT_INTERACTIVE_DOCS_REPO: ${{ github.workspace }}/_ecosystem/Interactive-Surface-CSS

.github/workflows/release-version-alignment.yml

@@ -49,6 +49,37 @@ jobs:
       - name: Run full UI matrix
         run: npm run test:matrix
 
+      - name: Resolve immutable ecosystem fixture sources
+        id: ecosystem_sources
+        shell: bash
+        run: node scripts/write-ecosystem-workflow-outputs.mjs
+
+      - name: Checkout Layout Style CSS contract fixture
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ steps.ecosystem_sources.outputs.layout_repository }}
+          ref: ${{ steps.ecosystem_sources.outputs.layout_revision }}
+          path: _ecosystem/Layout-Style-CSS
+
+      - name: Checkout Interactive Surface CSS contract fixture
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ steps.ecosystem_sources.outputs.interactive_repository }}
+          ref: ${{ steps.ecosystem_sources.outputs.interactive_revision }}
+          path: _ecosystem/Interactive-Surface-CSS
+
+      - name: Install Layout Style CSS fixture dependencies
+        working-directory: _ecosystem/Layout-Style-CSS
+        run: npm ci
+
+      - name: Install Interactive Surface CSS fixture dependencies
+        working-directory: _ecosystem/Interactive-Surface-CSS
+        run: npm ci
+
+      # Explicit candidate mode exempts only the UI tag under review while retaining every published companion check.
+      - name: Run ecosystem release preflight
+        run: npm run release:preflight -- --candidate-package ui-style-kit-css --layout-repo $GITHUB_WORKSPACE/_ecosystem/Layout-Style-CSS --interactive-repo $GITHUB_WORKSPACE/_ecosystem/Interactive-Surface-CSS --layout-docs-repo $GITHUB_WORKSPACE/_ecosystem/Layout-Style-CSS --interactive-docs-repo $GITHUB_WORKSPACE/_ecosystem/Interactive-Surface-CSS
+
       - name: Restrict manual runs to main
         if: github.event_name == 'workflow_dispatch' && github.ref != 'refs/heads/main'
         shell: bash

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to **UI Style Kit CSS** will be documented here.
 
+## [Unreleased]
+
+## [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