feat: tailwind support

DEVELOPMENT.md

@@ -84,3 +84,17 @@ composer dump-autoload
 
 - Do not use `classmap` autoloading for namespaced classes.
 - Keep the `rtCamp\Theme\Elementary\` PSR-4 root aligned with `inc/`.
+
+## Tailwind CSS
+
+Tailwind CSS v4 is integrated into the webpack build pipeline via PostCSS (`postcss.config.js`).
+
+**Entry point:** `src/css/frontend/tailwind.css` — compiled to `assets/build/css/frontend/tailwind.css`.
+
+**Preflight is disabled** by importing only `tailwindcss/theme.css` and `tailwindcss/utilities.css`, omitting `tailwindcss/preflight.css`. Tailwind's preflight is a CSS reset that conflicts with the block editor's own base styles and `wp-block-styles`.
+
+**Design tokens:** The `@theme {}` block in `tailwind.css` maps Tailwind utility names to WordPress CSS custom properties generated from `theme.json` (e.g. `--color-primary: var(--wp--preset--color--primary)`). This means tokens stay in sync with `theme.json` automatically — no manual duplication.
+
+**Content detection:** `tailwind.css` contains an `@source` directive pointing from the CSS file's directory back to the project root (e.g. `@source "../../../";`). This is generated automatically by `GenerateTailwindThemePlugin` using `path.relative(cssDir, process.cwd())` — `process.cwd()` is assumed to be the project root (where webpack is invoked). Tailwind v4 auto-detection is not relied on.
+
+**Opt-in:** The stylesheet is only enqueued when `src/css/frontend/tailwind.css` is present. The init script (TASK-008) controls whether this file is created during project setup.

functions.php

@@ -23,6 +23,10 @@
 	define( 'ELEMENTARY_THEME_BUILD_DIR', untrailingslashit( get_template_directory() ) . '/assets/build' );
 endif;
 
+if ( ! defined( 'ELEMENTARY_THEME_ENABLE_TAILWIND' ) ) :
+	define( 'ELEMENTARY_THEME_ENABLE_TAILWIND', file_exists( get_template_directory() . '/src/css/frontend/tailwind.css' ) );
+endif;
+
 if ( ! defined( 'ELEMENTARY_THEME_DISABLE_BROWSER_SYNC' ) ) :
 	define( 'ELEMENTARY_THEME_DISABLE_BROWSER_SYNC', false );
 endif;

inc/Core/Assets.php

@@ -22,10 +22,35 @@ class Assets {
 	use AssetLoaderTrait;
 	use Singleton;
 
+	/**
+	 * Whether Tailwind CSS is enabled for this theme.
+	 *
+	 * Tailwind support is opt-in. It defaults to true when
+	 * src/css/frontend/tailwind.css exists (generated by GenerateTailwindThemePlugin).
+	 *
+	 * To force-enable or disable before the theme loads, define the constant in
+	 * wp-config.php or a must-use plugin:
+	 *
+	 *   define( 'ELEMENTARY_THEME_ENABLE_TAILWIND', true );
+	 *   define( 'ELEMENTARY_THEME_ENABLE_TAILWIND', false );
+	 *
+	 * To override at runtime (e.g. from a child theme or plugin):
+	 *
+	 *   add_filter( 'elementary_theme_tailwind_enabled', '__return_true' );
+	 *   add_filter( 'elementary_theme_tailwind_enabled', '__return_false' );
+	 *
+	 * @var bool
+	 */
+	private bool $tailwind_enabled = false;
+
 	/**
 	 * Constructor.
 	 */
 	protected function __construct() {
+		$this->tailwind_enabled = (bool) apply_filters(
+			'elementary_theme_tailwind_enabled',
+			ELEMENTARY_THEME_ENABLE_TAILWIND
+		);
 		// Setup hooks.
 		$this->setup_hooks();
 	}
@@ -52,6 +77,10 @@ public function register_assets(): void {
 		$this->register_script( 'core-navigation', 'js/frontend/core-navigation.js' );
 		$this->register_style( 'core-navigation', 'css/frontend/core-navigation.css' );
 		$this->register_style( 'elementary-theme-styles', 'css/frontend/styles.css' );
+
+		if ( $this->tailwind_enabled ) {
+			$this->register_style( 'elementary-theme-tailwind', 'css/frontend/tailwind.css' );
+		}
 	}
 
 	/**
@@ -85,6 +114,10 @@ public function enqueue_block_specific_assets( string $markup, array $block ): s
 	public function enqueue_assets(): void {
 		wp_enqueue_style( 'elementary-theme-styles' );
 
+		if ( $this->tailwind_enabled ) {
+			wp_enqueue_style( 'elementary-theme-tailwind' );
+		}
+
 		if ( 'local' === wp_get_environment_type() && ! ELEMENTARY_THEME_DISABLE_BROWSER_SYNC ) {
 			if ( defined( 'ELEMENTARY_THEME_BROWSER_SYNC_URL' ) ) {
 				$bs_url = ELEMENTARY_THEME_BROWSER_SYNC_URL;