feat: add UI Build Artifacts Check workflow

.github/CODEOWNERS

@@ -4,6 +4,7 @@
 # Docs Management ownership for code, config, and related docs
 snippets             @auth0/project-docs-management-codeowner
 ui                   @auth0/project-docs-management-codeowner
+universal-components @auth0/project-docs-management-codeowner
 scripts              @auth0/project-docs-management-codeowner
 **/package.json      @auth0/project-docs-management-codeowner
 **/package-lock.json @auth0/project-docs-management-codeowner

.github/workflows/ui-build-check.yml

@@ -0,0 +1,46 @@
+name: UI Build Artifacts Check
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened, ready_for_review]
+
+jobs:
+  ui-build-check:
+    name: UI Build Artifacts Check
+    runs-on: ubuntu-latest
+    if: ${{ !github.event.pull_request.draft }}
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+        with:
+          fetch-depth: 0
+
+      - name: Check ui artifacts are committed
+        run: |
+          BASE=${{ github.event.pull_request.base.sha }}
+          HEAD=${{ github.event.pull_request.head.sha }}
+          CHANGED=$(git diff --name-only "$BASE"..."$HEAD")
+
+          UI_SRC_CHANGED=$(echo "$CHANGED" | grep -cE '^ui/src/|^ui/package\.json' || true)
+          UI_ARTIFACT_CHANGED=$(echo "$CHANGED" | grep -cE '^main/ui/auth0-docs-ui-' || true)
+
+          UC_SRC_CHANGED=$(echo "$CHANGED" | grep -cE '^universal-components/src/|^universal-components/package\.json' || true)
+          UC_ARTIFACT_CHANGED=$(echo "$CHANGED" | grep -cE '^main/ui/universal-components/' || true)
+
+          FAILED=0
+
+          if [ "$UI_SRC_CHANGED" -gt 0 ] && [ "$UI_ARTIFACT_CHANGED" -eq 0 ]; then
+            echo "::error::ui/src changes detected but main/ui/ artifacts were not updated."
+            echo "::error::Run: cd ui && npm run copy:build — then commit the updated files in main/ui/."
+            FAILED=1
+          fi
+
+          if [ "$UC_SRC_CHANGED" -gt 0 ] && [ "$UC_ARTIFACT_CHANGED" -eq 0 ]; then
+            echo "::error::universal-components/src changes detected but main/ui/universal-components/ artifacts were not updated."
+            echo "::error::Run: cd universal-components && pnpm run copy:assets — then commit the updated files in main/ui/universal-components/."
+            FAILED=1
+          fi
+
+          exit $FAILED

ui/README.md

@@ -40,20 +40,21 @@ pnpm dev
 
 ```bash
 pnpm copy:build
-# Builds UMD bundle and copies artifacts to /main/ui/ directory
+# Bumps patch version, builds UMD bundle, and copies artifacts to /main/ui/
 ```
 
-> **Note:** The `pnpm copy:build` command runs both `pnpm build` (TypeScript compilation + Vite bundling) and copies the output to the documentation site. You don't need to run `pnpm build` separately.
+> **Note:** `pnpm copy:build` automatically bumps the patch version in `package.json`, runs the full build (TypeScript compilation + Vite bundling), and copies the output to the documentation site. You don't need to run `pnpm build` separately. Always use `pnpm copy:build` when deploying UI changes — running `pnpm build` alone will not update `main/ui/`.
 
 ## Build Process
 
 ### How It Works
 
 The `pnpm copy:build` command handles the complete build and deployment workflow:
 
-1. **TypeScript Compilation** - `tsc -b` compiles all TypeScript files
-2. **Vite Build** - Bundles into UMD format with version-stamped filenames
-3. **Copy to Main** - Removes old build artifacts and copies new ones to `/main/ui/` directory
+1. **Version Bump** - `pnpm version patch --no-git-tag-version` increments the patch version in `package.json`
+2. **TypeScript Compilation** - `tsc -b` compiles all TypeScript files
+3. **Vite Build** - Bundles into UMD format with version-stamped filenames
+4. **Copy to Main** - Removes old build artifacts and copies new ones to `/main/ui/` directory
 
 ### Build Configuration
 
@@ -87,22 +88,21 @@ build: {
 
 ### Version Management
 
-The build automatically includes the version from `package.json` in the output filenames:
+The version in `package.json` is automatically bumped by `pnpm copy:build` and embedded in the output filenames. Mintlify uses the versioned filenames to bust its cache on each deploy.
 
 ```
-ui/package.json (version: 1.1.0)
+pnpm copy:build
+    ↓
+ui/package.json version: 1.1.0 → 1.1.1
     ↓
-ui/dist/auth0-docs-ui-1.1.0.umd.js
-ui/dist/auth0-docs-ui-1.1.0.css
+ui/dist/auth0-docs-ui-1.1.1.umd.js
+ui/dist/auth0-docs-ui-1.1.1.css
     ↓
-main/ui/auth0-docs-ui-1.1.0.umd.js
-main/ui/auth0-docs-ui-1.1.0.css
+main/ui/auth0-docs-ui-1.1.1.umd.js
+main/ui/auth0-docs-ui-1.1.1.css
 ```
 
-**To update the version:**
-1. Edit `version` in `ui/package.json`
-2. Run `pnpm copy:build`
-3. Commit both `/ui` and `/main/ui/` changes
+You don't need to manually edit the version — it's handled by the script. If you need a minor or major bump, update `package.json` manually before running `pnpm copy:build`.
 
 ### CSS Scoping Strategy
 
@@ -302,17 +302,12 @@ export const Button = () => (
 
 ### Version Bumping Strategy
 
-**When to bump version:**
-- **Major (2.0.0)** - Breaking API changes
-- **Minor (1.2.0)** - New features, new components
-- **Patch (1.1.1)** - Bug fixes, style tweaks
+`pnpm copy:build` always does a **patch** bump automatically. For larger changes:
 
-**How to bump:**
-1. Update version in `ui/package.json`
-2. Run `pnpm copy:build`
-3. Commit the version change and new build files
+- **Minor (1.2.0)** - New features, new components: edit `package.json` manually first, then run `pnpm copy:build`
+- **Major (2.0.0)** - Breaking API changes: edit `package.json` manually first, then run `pnpm copy:build`
 
-> **Note:** Old build files are automatically removed by the `copy:build` script before copying new ones.
+> **Note:** Old build files are automatically removed by the `copy:build` script before copying new ones. A PR check will fail if `ui/src/` changes are detected but `main/ui/` artifacts were not updated.
 
 ### Code Quality
 

ui/scripts/copy-build.sh

@@ -1,3 +1,11 @@
+#!/bin/bash
+
+# Bump patch only if the version field hasn't been manually changed already
+BASE_VER=$(git show HEAD:package.json | jq -r '.version')
+CUR_VER=$(jq -r '.version' package.json)
+if [ "$BASE_VER" = "$CUR_VER" ]; then
+  pnpm version patch --no-git-tag-version
+fi
 pnpm build
 rm -f ../main/ui/*
 cp -r dist/*.{js,css} ../main/ui/

universal-components/README.md

@@ -42,7 +42,7 @@ Both packages are installed via `pnpm` and used throughout the docs-v2 project f
    pnpm build
    ```
 
-   This runs TypeScript build, Vite build, and copies assets as needed.
+   This automatically bumps the patch version in `package.json`, runs TypeScript build, Vite build, and copies artifacts to `main/ui/universal-components/`.
 
 3. **Move to the main docs-v2 folder:**
 
@@ -84,7 +84,8 @@ node --version
 
 ## Notes
 
-- Make sure we update package.json to next version(minor/major/patch) so that our component bundle gets created with that version and mintlify automatically bursts the cache for us once its redeployed.
+- `pnpm build` automatically bumps the patch version in `package.json` so the bundle filename changes and Mintlify busts its cache on redeploy. For a minor or major bump, edit `package.json` manually before running `pnpm build`.
+- A CI check will fail PRs that change `universal-components/src/` without updated artifacts in `main/ui/universal-components/`.
 - All component previews are rendered with fixed height and scrollbars for overflow.
 - Modals/dialogs are scoped to the preview container for accurate demo experience.
 - Use the snippets (e.g., `ComponentLoader`, `SsoProviderTablePreview`) for consistent preview styling and loading states.

universal-components/scripts/build-all.sh

@@ -1,5 +1,12 @@
 #!/bin/bash
 
+# Bump patch only if the version field hasn't been manually changed already
+BASE_VER=$(git show HEAD:package.json | jq -r '.version')
+CUR_VER=$(jq -r '.version' package.json)
+if [ "$BASE_VER" = "$CUR_VER" ]; then
+  pnpm version patch --no-git-tag-version
+fi
+
 # Build TypeScript
 pnpm tsc -b