diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..37cd6ef
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,37 @@
+name: CI
+
+on:
+    push:
+        branches:
+            - main
+            - dev
+    pull_request:
+        branches:
+            - main
+
+jobs:
+    quality-checks:
+        name: Lint, Format & Build
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v7
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v6
+              with:
+                  node-version: '24.x'
+                  cache: 'npm'
+
+            - name: Install dependencies (clean install)
+              run: npm ci
+
+            - name: Run Stylelint (CSS linting)
+              run: npm run lint
+
+            - name: Check Prettier formatting
+              run: npm run format -- --check
+
+            - name: Build package (verify it compiles)
+              run: npm run build
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 2ece9ba..767fc26 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -1,32 +1,53 @@
+# Publish to npm when a release is published or manually triggered.
+# Also verifies version consistency, runs linters, builds the package, and publishes with provenance.
 name: Publish to npm
 
 on:
     release:
-        types: [published]
-    workflow_dispatch:
+        types: [published] # triggers when a GitHub Release is published
+    workflow_dispatch: # allows manual trigger from Actions tab
 
 jobs:
     publish:
+        name: Build & Publish
         runs-on: ubuntu-latest
         permissions:
             contents: read
-            id-token: write
+            id-token: write # required for npm provenance
+
         steps:
-            - name: 'Checkout code'
+            - name: Checkout repository
               uses: actions/checkout@v7
 
-            - name: 'Setup Node.js'
+            - name: Setup Node.js
               uses: actions/setup-node@v6
               with:
                   node-version: '24.x'
                   registry-url: 'https://registry.npmjs.org'
-            - name: 'Install dependencies'
+                  cache: 'npm'
+
+            - name: Install dependencies (clean install)
               run: npm ci
 
-            # - name: 'Build'
-            #   run: npm run build
-            # - name: 'Test'
-            #   run: npm test
+            - name: Verify version matches the release tag (if triggered by release)
+              if: github.event_name == 'release'
+              run: |
+                  PACKAGE_VERSION=$(node -p "require('./package.json').version")
+                  RELEASE_TAG=${github.event.release.tag_name#v}
+                  if [ "$PACKAGE_VERSION" != "$RELEASE_TAG" ]; then
+                    echo "❌ Package version ($PACKAGE_VERSION) does not match release tag ($RELEASE_TAG)"
+                    exit 1
+                  fi
+                  echo "✅ Package version $PACKAGE_VERSION matches release tag $RELEASE_TAG"
+
+            - name: Run Stylelint (CSS linting)
+              run: npm run lint
+
+            - name: Check Prettier formatting
+              run: npm run format -- --check
+
+            - name: Build package
+              run: npm run build
 
-            - name: 'Publish to npm'
+            - name: Publish to npm with provenance
               run: npm publish --provenance --access public