diff --git a/.github/workflows/release-version-alignment.yml b/.github/workflows/release-version-alignment.yml
new file mode 100644
index 0000000..b6286fb
--- /dev/null
+++ b/.github/workflows/release-version-alignment.yml
@@ -0,0 +1,113 @@
+name: Release Version Alignment
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  publish-and-label:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Restrict manual runs to main
+        if: github.event_name == 'workflow_dispatch' && github.ref != 'refs/heads/main'
+        shell: bash
+        run: |
+          echo "::error::workflow_dispatch is only allowed from refs/heads/main."
+          exit 1
+
+      - name: Resolve release version
+        id: version
+        shell: bash
+        run: |
+          set -euo pipefail
+          PACKAGE_NAME="$(node -p "require('./package.json').name")"
+          PACKAGE_VERSION="$(node -p "require('./package.json').version")"
+          EXPECTED_TAG="v${PACKAGE_VERSION}"
+
+          if [[ "${GITHUB_REF_TYPE:-}" == "tag" && "${GITHUB_REF_NAME}" != "${EXPECTED_TAG}" ]]; then
+            echo "::error::Tag '${GITHUB_REF_NAME}' must match package version tag '${EXPECTED_TAG}'."
+            exit 1
+          fi
+
+          if ! grep -qE "^## \\[${PACKAGE_VERSION//./\\.}\\] - " CHANGELOG.md; then
+            echo "::error::CHANGELOG.md is missing an entry for version ${PACKAGE_VERSION}."
+            exit 1
+          fi
+
+          echo "package_name=${PACKAGE_NAME}" >> "$GITHUB_OUTPUT"
+          echo "package_version=${PACKAGE_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "expected_tag=${EXPECTED_TAG}" >> "$GITHUB_OUTPUT"
+
+      - name: Check npm for target version
+        id: npm_check
+        shell: bash
+        env:
+          PACKAGE_NAME: ${{ steps.version.outputs.package_name }}
+          PACKAGE_VERSION: ${{ steps.version.outputs.package_version }}
+        run: |
+          set -euo pipefail
+          if npm view "${PACKAGE_NAME}@${PACKAGE_VERSION}" version >/dev/null 2>&1; then
+            echo "already_published=true" >> "$GITHUB_OUTPUT"
+            echo "Version ${PACKAGE_VERSION} is already published on npm."
+          else
+            echo "already_published=false" >> "$GITHUB_OUTPUT"
+            echo "Version ${PACKAGE_VERSION} is not yet published on npm."
+          fi
+
+      - name: Ensure npm token is configured
+        if: steps.npm_check.outputs.already_published == 'false'
+        shell: bash
+        env:
+          PACKAGE_NAME: ${{ steps.version.outputs.package_name }}
+          PACKAGE_VERSION: ${{ steps.version.outputs.package_version }}
+        run: |
+          echo "::error::Missing NPM_TOKEN secret; cannot publish ${PACKAGE_NAME}@${PACKAGE_VERSION}."
+          exit 1
+
+      - name: Publish package to npm
+        if: steps.npm_check.outputs.already_published == 'false'
+        shell: bash
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public
+
+      - name: Create tag on manual run
+        if: github.event_name == 'workflow_dispatch'
+        shell: bash
+        env:
+          EXPECTED_TAG: ${{ steps.version.outputs.expected_tag }}
+        run: |
+          set -euo pipefail
+          if git rev-parse -q --verify "refs/tags/${EXPECTED_TAG}" >/dev/null; then
+            echo "Tag ${EXPECTED_TAG} already exists."
+          else
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git tag "${EXPECTED_TAG}"
+            git push origin "${EXPECTED_TAG}"
+            echo "Created and pushed tag ${EXPECTED_TAG}."
+          fi
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.expected_tag }}
+          name: ${{ steps.version.outputs.expected_tag }}
+          generate_release_notes: true
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc6cf84..a35827f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.0.2]-2026-05-25
+
+### Added
+
+- `.github/workflows/sync-package-version-with-main.yml` to keep pull request branch versions aligned with `main`.
+- `.github/workflows/release-version-alignment.yml` to enforce matching GitHub tag, `package.json`, changelog entry, and npm publish target version.
+
+### Changed
+
+- Bumped package version to `1.0.2`.
+- Upgraded `stylelint` from `^16.24.0` to `^17.12.0`.
+- Updated GitHub Actions in CI:
+  - `actions/checkout` from `v4` to `v6`
+  - `actions/setup-node` from `v4` to `v6`
+
+## [1.0.1] - 2026-05-25
+
+### Fixed
+
+- Patched release metadata and demo HTML (`package.json`, `index.html`) for package stability.
+
 ## [1.0.0] - 2026-05-24
 
 ### Added
diff --git a/package-lock.json b/package-lock.json
index 3efad0f..37edce8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "ui-style-kit-css",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ui-style-kit-css",
-      "version": "1.0.0",
+      "version": "1.0.2",
       "license": "MIT",
       "dependencies": {
         "ajv": "~8.20.0",