ci: enforce committed Linux visual baselines

.github/workflows/storybook.yml

@@ -9,12 +9,31 @@ on:
       - "packages/ui/scripts/**"
       - "packages/ui/styles.css"
       - "packages/ui/themes/**"
+      - "packages/ui/.snapshots/**"
+      - "packages/ui/playwright/**"
+      - "packages/ui/playwright-ct.config.ts"
+      - "packages/ui/postcss.config.mjs"
+      - "packages/ui/package.json"
+      - "pnpm-lock.yaml"
       - ".github/workflows/storybook.yml"
   push:
     branches: [main]
     paths:
       - "packages/ui/src/**"
       - "packages/ui/.storybook/**"
+      - "packages/ui/styles.css"
+      - "packages/ui/themes/**"
+      - "packages/ui/.snapshots/**"
+      - "packages/ui/playwright/**"
+      - "packages/ui/playwright-ct.config.ts"
+      - "packages/ui/postcss.config.mjs"
+      - "packages/ui/scripts/**"
+      - "packages/ui/package.json"
+      - "pnpm-lock.yaml"
+      - ".github/workflows/storybook.yml"
+
+permissions:
+  contents: read
 
 concurrency:
   group: storybook-${{ github.head_ref || github.ref }}
@@ -114,8 +133,10 @@ jobs:
 
   visual-regression:
     name: Visual Regression
-    needs: build-storybook
     runs-on: ubuntu-latest
+    container:
+      image: mcr.microsoft.com/playwright:v1.58.2-noble@sha256:6446946a1d9fd62d9ae501312a2d76a43ee688542b21622056a372959b65d63d
+      options: --ipc=host
     steps:
       - uses: actions/checkout@v5
 
@@ -128,19 +149,17 @@ jobs:
 
       - run: pnpm install --frozen-lockfile
 
-      - name: Install Playwright browsers
-        run: pnpm -F @vllnt/ui exec playwright install --with-deps chromium
-
-      - name: Run Playwright CT visual tests
+      - name: Compare committed visual baselines
         working-directory: packages/ui
-        run: pnpm test:visual --update-snapshots
+        run: pnpm test:visual --workers=2 --update-snapshots=none
 
       - name: Upload visual snapshots
         if: always()
         uses: actions/upload-artifact@v5
         with:
           name: visual-snapshots
-          path: packages/ui/.snapshots
+          path: packages/ui/.snapshots/linux
+          include-hidden-files: true
           retention-days: 30
 
       - name: Upload visual test results

docs/README.md

@@ -8,6 +8,7 @@ This folder contains in-repo documentation for `@vllnt/ui` contributors and down
 |-----|------|
 | [ARCHITECTURE.md](./ARCHITECTURE.md) | Monorepo layout, package boundaries, build graph |
 | [RELEASING.md](./RELEASING.md) | How releases are cut and published |
+| [VISUAL_TESTING.md](./VISUAL_TESTING.md) | Reproducible visual comparisons and reviewed baseline updates |
 
 ## External destinations
 

docs/VISUAL_TESTING.md

@@ -0,0 +1,35 @@
+# Visual regression testing
+
+The canonical screenshots live in `packages/ui/.snapshots/linux/`. Generate and compare them in `mcr.microsoft.com/playwright:v1.58.2-noble`, matching the Playwright version in the lockfile and the CI container. CI pins the image manifest digest `sha256:6446946a1d9fd62d9ae501312a2d76a43ee688542b21622056a372959b65d63d`. The suite fixes locale to `en-US`, timezone to `UTC`, and reduced motion to make layout comparisons reproducible. Animation behavior remains covered by component unit tests.
+
+Do not compare macOS screenshots with the Linux baseline set. The snapshot path includes the operating system to prevent accidental cross-platform updates.
+
+On Linux, the Playwright config loads `packages/ui/playwright/fonts.conf` to select the container's installed **Liberation Mono** for generic monospace text. Without this explicit preference, fresh font caches can select WenQuanYi instead and change text widths. This affects only the browser test environment, not shipped CSS or theme tokens; no additional font package is installed.
+
+## Compare
+
+From a clean checkout, run in the pinned Linux container:
+
+```sh
+corepack enable
+corepack prepare pnpm@9.15.4 --activate
+pnpm install --frozen-lockfile
+pnpm -F @vllnt/ui test:visual --workers=2 --update-snapshots=none
+```
+
+Mount or copy only the checkout into the container; install Linux dependencies there instead of sharing host `node_modules`. CI runs the same comparison and uploads test results on failure. Missing snapshots fail the job rather than being accepted.
+
+## Refresh deliberately
+
+In the same container, select only the affected fixtures:
+
+```sh
+pnpm -F @vllnt/ui test:visual sidebar --workers=1 --update-snapshots
+pnpm -F @vllnt/ui test:visual sidebar --workers=1 --update-snapshots=none
+```
+
+Keep fixture images local or inline rather than depending on third-party placeholder hosts. Wait for the image's intrinsic dimensions before capturing it; screenshot stability alone does not guarantee a remote image has loaded.
+
+Inspect expected/actual/diff images and commit only intentional changes together with their source changes. Never update snapshots in CI to make a failing comparison pass. When upgrading Playwright, upgrade the container version and review regenerated screenshots together.
+
+The initial Linux baseline set was generated from `main` at `38db630`, not from the Native feature branch. Snapshot equality proves the states exercised by the existing visual fixtures; it does not replace keyboard, accessibility, reduced-motion behavior, or physical-device tests.