Move theme-css docs to a dedicated file and auto-run on npm run dev

docs/setup/deployment.md

@@ -26,9 +26,7 @@ on:
 
 ## 🎨 Automatic Theme CSS Generation
 
-The Next.js app requires the `next/public/css/theme-generated.css` file to be generated before the Next.js build runs. This file is automatically generated from the WordPress theme configuration via WP-CLI.
-
-**How it works in CI:**
+The Next.js app requires `next/public/css/theme-generated.css` before its build runs. See [`./theme-css.md`](./theme-css.md) for the full how-to (what the file is, local-dev usage, troubleshooting). This section covers the CI integration only.
 
 During each deployment workflow:
 
@@ -38,23 +36,6 @@ During each deployment workflow:
 4. Places it at `next/public/css/theme-generated.css` (the location where Next.js expects it)
 5. The subsequent "Build Theme" step uses this CSS file during the build
 
-**Local development:**
-
-To generate the CSS file locally for development:
-
-```bash
-# From the project root
-WPCLI="wp @local" npm --prefix wordpress run generate:theme-css
-```
-
-This pulls the CSS from your local WordPress instance and writes it to `next/public/css/theme-generated.css`.
-
-**Troubleshooting:**
-
-- If the CI step fails with "SSH connection refused", verify that GitHub Actions runners can reach your remote server (check firewall/security groups)
-- If the step fails with "wp: command not found", ensure WP-CLI is installed on the remote WordPress server
-- If the CSS file is empty, check that the `wp spck theme-css` command works on the remote server by testing it manually
-
 ## 🔐 Github Actions variables & secrets
 
 The workflows use GitHub [Environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) (`staging` and `production`) to scope their configuration. Each environment holds its own set of **variables** (non-sensitive, `vars.*`) and **secrets** (sensitive, `secrets.*`).

docs/setup/theme-css.md

@@ -0,0 +1,53 @@
+# Theme CSS Generation
+
+The Next.js app consumes a CSS file generated from the WordPress theme's global styles. This document covers what it is, how it's built, and how to refresh it locally and in CI.
+
+## What it is
+
+- **Output file:** `next/public/css/theme-generated.css`
+- **Consumed by:** `next/src/app/layout.tsx` (loaded as a `<link rel="stylesheet">`)
+- **Content:** a `:root { ... }` block of CSS custom properties exported from `wp_get_global_stylesheet(['variables'])` — i.e. every CSS variable declared in `theme.json` and the site editor's Global Styles. No selectors, no resets, only the variables.
+
+The file must exist before Next.js builds, because the layout link is static.
+
+## Local development
+
+### Auto-run on dev
+
+`npm --prefix wordpress run dev` regenerates the CSS automatically via a `predev` hook before webpack starts. If WordPress isn't reachable (e.g. you haven't run `npm start` yet), the script logs a warning and skips — webpack still starts with whatever CSS file is currently on disk.
+
+### Manual run
+
+```sh
+WPCLI="wp @local" npm --prefix wordpress run generate:theme-css
+```
+
+Override `WPCLI` if you use a different WP-CLI target (e.g. `wp` directly, or a remote alias). The script will also fall back to a downloaded `wp-cli.phar` if `wp` is not on `PATH`.
+
+### Underlying CLI command
+
+```sh
+wp spck theme-css
+```
+
+Registered in `wordpress/theme/includes/cli/theme-css.php`. Use this if you want to inspect the output without writing the file.
+
+## CI / deployment
+
+In deploy workflows the CSS is generated on the **remote** WordPress server (via SSH + `wp spck theme-css`) and downloaded to the CI runner before the Next.js build step. See [`./deployment.md`](./deployment.md) for the workflow specifics.
+
+## Files
+
+| Path | Role |
+| --- | --- |
+| `wordpress/scripts/theme-css.sh` | Shell entrypoint — invokes WP-CLI and writes the output file |
+| `wordpress/theme/includes/cli/theme-css.php` | Registers the `wp spck theme-css` command |
+| `next/public/css/theme-generated.css` | Generated output (consumed by Next.js) |
+
+## Troubleshooting
+
+- **`WordPress is not installed/reachable for the selected WPCLI target`** — WP isn't running, or your `WPCLI` value doesn't match your environment. Run `npm --prefix wordpress start` first, or set `WPCLI` explicitly (e.g. `WPCLI="wp @local"`).
+- **`Skipping theme CSS generation (THEME_CSS_SOFT=1)` at the start of `npm run dev`** — the `predev` hook ran but WP wasn't reachable. Expected when WP is down; bring WP up and re-run `npm run generate:theme-css` manually if you need fresh CSS now.
+- **`Generated stylesheet is empty after filtering`** — `wp_get_global_stylesheet(['variables'])` returned no `:root{` block. Check that the active theme defines variables in `theme.json` and that the site is in a healthy state.
+- **CI step fails with `SSH connection refused`** — GitHub Actions runners can't reach your remote server. Check firewall/security groups.
+- **CI step fails with `wp: command not found`** — WP-CLI is not installed on the remote WordPress server.

wordpress/README.md

@@ -46,12 +46,7 @@ See [`wordpress/theme/migrations/README.md`](wordpress/theme/migrations/README.m
 
 ## Theme CSS Generation
 
-Theme CSS variables can be generated through a scripts in this repository.
-
-- Script location: `wordpress/scripts/theme-css.sh`
-- Command entrypoint (theme): `wp spck theme-css`
-
-Use this when you need to refresh frontend-consumed theme CSS from WordPress internals.
+See [`docs/setup/theme-css.md`](../docs/setup/theme-css.md).
 
 ## License
 

wordpress/package.json

@@ -11,6 +11,7 @@
     "generate:theme-css": "sh ./scripts/theme-css.sh",
     "test": "echo \"Error: no test specified\" && exit 1",
     "clear-cache": "wp @local transient delete --all && wp @local db query \"DELETE FROM wp_options where option_name LIKE '%wp_theme_files_patterns%'\"",
+    "predev": "THEME_CSS_SOFT=1 WPCLI=\"${WPCLI:-wp @local}\" npm run generate:theme-css",
     "dev": "npm --prefix ./theme run dev",
     "build": "npm --prefix ./theme run build",
     "setup-composer-auth": "sh ./scripts/setup-composer-auth.sh"

wordpress/scripts/theme-css.sh

@@ -19,10 +19,14 @@ if [ -z "${WPCLI}" ]; then
 	fi
 fi
 
-# Stop if WordPress is not reachable.
+# Stop if WordPress is not reachable (or skip in soft mode).
 if ! $WPCLI core is-installed --quiet >/dev/null 2>&1; then
 	echo 'WordPress is not installed/reachable for the selected WPCLI target.' >&2
 	echo 'Set WPCLI (or WORDPRESS_PATH) to match your environment.' >&2
+	if [ "${THEME_CSS_SOFT:-}" = "1" ]; then
+		echo 'Skipping theme CSS generation (THEME_CSS_SOFT=1).' >&2
+		exit 0
+	fi
 	exit 1
 fi