diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml
index 953d99c6d..49177e339 100644
--- a/.github/workflows/ruby.yml
+++ b/.github/workflows/ruby.yml
@@ -46,15 +46,15 @@ jobs:
       id: playwright-cache
       with:
         path: ~/.cache/ms-playwright
-        key: playwright-${{ runner.os }}-1.59.0
+        key: playwright-${{ runner.os }}-chromium-headless-shell-1.59.0
 
-    - name: Install Playwright browsers (cache miss)
+    - name: Install Playwright Chromium Headless Shell (cache miss)
       if: steps.playwright-cache.outputs.cache-hit != 'true'
-      run: npx --yes playwright@1.59.0 install --with-deps chromium
+      run: npx --yes playwright@1.59.0 install chromium-headless-shell
 
     - name: Install Playwright system deps (cache hit)
       if: steps.playwright-cache.outputs.cache-hit == 'true'
-      run: npx --yes playwright@1.59.0 install-deps chromium
+      run: npx --yes playwright@1.59.0 install-deps chromium-headless-shell
 
     - name: Setup test databases
       env:
diff --git a/spec/support/capybara.rb b/spec/support/capybara.rb
index da5ccc74a..a18952825 100644
--- a/spec/support/capybara.rb
+++ b/spec/support/capybara.rb
@@ -1,3 +1,10 @@
+# frozen_string_literal: true
+
+# Capybara driver using Playwright with Chromium Headless Shell
+# The headless shell is ~44% smaller than full Chromium (189MB vs 336MB)
+# while maintaining full web compatibility.
+# See: https://playwright.dev/docs/browsers#chromium-headless-shell
+
 Capybara.register_driver :playwright do |app|
   Capybara::Playwright::Driver.new(
     app,