imagewize · jasperf · Dec 6, 2025 · Dec 6, 2025
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,41 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Theme lives at `site/web/app/themes/nynaeve/`.
+- `app/`: PHP (Blocks, Providers, View Composers); `config/`: Sage/Acorn config.
+- `resources/`: Tailwind (`css/`), JS (`js/`), Blade views (`views/`), native blocks (`js/blocks/`); block styles live with each block.
+- Built assets in `public/build/` (Vite); static assets in `resources/images/`.
+- Utilities in `scripts/`; theme docs in `docs/`; `archive/` is deprecated/read-only.
+
+## Build, Test, and Development Commands
+- Install deps: `cd site && composer install`; then `cd site/web/app/themes/nynaeve && composer install && npm install`.
+- Dev server (Vite + HMR): `npm run dev`; open `http://imagewize.test/` (HTTPS breaks HMR WebSockets).
+- Production build: `npm run build`.
+- Quality: `cd site && composer test` (phpcs); `composer pint` or `npm run pint` for formatting.
+- Visual/E2E: `npm run pw`.
+
+## Coding Style & Block Standards
+- PHP: PSR-4 under `App\\`, prefer strict types; format with Pint.
+- JS/React: ES modules, functional components; block dirs kebab-case (`cta-block-blue`), components PascalCase.
+- Blocks: InnerBlocks-first; use real content (no placeholders); no horizontal padding (theme handles spacing); keep styling on containers, not core child blocks.
+- `block.json`: namespace/category/textdomain `imagewize`; default align `wide`; button styles via `core/buttons` container class (not individual buttons).
+- Blade views in `resources/views`; reuse via `partials/` and `sections/`. CSS is Tailwind-first, custom in `resources/css` or block `style.css`.
+
+## Block Development Workflow (Trellis VM)
+- DB lives in Trellis VM (local MySQL on 3306 conflicts). Run `trellis vm shell --workdir /srv/www/imagewize.com/current` and use `--path=web/wp`.
+- Create native block: `wp acorn sage-native-block:create`; ACF block: `wp acorn acf:block MyBlock`.
+- Blocks auto-register via ThemeServiceProvider; store under `resources/js/blocks/{block-name}/` with container-only CSS.
+
+## Testing Guidelines
+- Before commits: `composer test`, `composer pint`/`npm run pint`.
+- For block/JS edits: `npm run build` once to confirm clean Vite output; use real content to catch layout issues.
+- Playwright: `npm run pw` or scoped (e.g., `npm run pw:mobile`).
+
+## Commit & Pull Request Guidelines
+- Commits: short Title-Case (e.g., `Nynaeve Documentation Update`); scope narrowly.
+- PRs: include purpose, affected theme paths, manual test commands, linked issues/trellis tickets; add screenshots/GIFs for UI/block changes.
+
+## Security & Configuration Tips
+- Never commit `.env`, vault files, or generated credentials; use `.env.example`.
+- Work from Trellis VM for any `wp`/`wp acorn` tasks (DB lives there; host MySQL on 3306 conflicts). Theme path in VM: `/srv/www/imagewize.com/current/web/app/themes/nynaeve`; demo: `/srv/www/demo.imagewize.com/current`.
+- Flush caches with `wp cache flush` if changes look stale; prefer repo Playwright script for screenshots.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,16 @@ All notable changes to the Nynaeve theme will be documented in this file.
 
 For project-wide changes (infrastructure, tooling, cross-cutting concerns), see the [project root CHANGELOG.md](../../../../../CHANGELOG.md).
 
+## [2.0.22] - 2025-12-06
+
+### Added
+- **Product Detail Field Groups**: New ACF fields for Features, What’s Included, and Pricing Details registered in [app/setup.php](app/setup.php#L203) and rendered as accordion sections on single product pages.
+- **Automation Guidance**: Added theme-specific agent docs ([AGENTS.md](AGENTS.md), [CLAUDE.md](CLAUDE.md)) covering structure, commands, block standards, and Trellis VM workflows.
+
+### Changed
+- **Single Product Layout Refresh**: Rebuilt WooCommerce single product template ([content-single-product.php](resources/views/woocommerce/content-single-product.php)) with a simplified hero (title/price/category), streamlined image rendering, short description, and ACF-driven accordion for detailed product info.
+- **Product Typography Override**: Enforced dark text color for headings and paragraphs within product content areas in [resources/css/app.css](resources/css/app.css#L768) to keep product pages readable when block color classes are applied.
+
 ## [2.0.21] - 2025-12-03
 
 ### Changed
@@ -1145,4 +1155,4 @@ For project-wide changes (infrastructure, tooling, cross-cutting concerns), see
 ### Fixed
 - Fixed related-articles block ignoring parent container constraints when resizing browser window
 - Related articles now properly adapt column count based on available container width rather than viewport width
-- Improved tag-based article matching to avoid overly generic results
+- Improved tag-based article matching to avoid overly generic results
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -487,6 +487,43 @@ We use **WordPress-native layout approach** with minimal custom CSS.
 - Adds "Request Quote" buttons on single product pages
 - Custom REST API endpoint to intercept checkout requests
 
+**Creating Product Content (CRITICAL):**
+
+When creating or editing WooCommerce product content using Gutenberg blocks:
+
+❌ **DO NOT** add color classes to text, headings, or paragraphs:
+- ❌ `textColor: "primary-accent"` in block attributes
+- ❌ `has-primary-accent-color` classes
+- ❌ `has-primary-color` classes
+- ❌ `has-base-color` or `has-base-accent-color`
+- ❌ `has-contrast-color` or `has-text-color`
+
+✅ **DO** let CSS control all colors automatically:
+- ✅ Use only typography attributes (fontFamily, fontSize, fontWeight)
+- ✅ Use spacing and layout attributes
+- ✅ Headings automatically use contrast color (dark)
+- ✅ Paragraphs automatically use main-accent color (readable gray)
+- ✅ Cover blocks with dark backgrounds automatically use white text
+
+**Why:**
+- Product page CSS (`app.css`) controls all colors for consistency
+- Hardcoded color classes override CSS and break the design system
+- Users cannot change colors in the editor when hardcoded
+- Color accessibility is managed centrally via CSS variables
+
+**Example - Clean block markup:**
+```html
+<!-- ✅ CORRECT - No color classes -->
+<h3 class="has-text-align-center has-montserrat-font-family has-xl-font-size">
+  Professional WordPress Development
+</h3>
+
+<!-- ❌ WRONG - Has color classes -->
+<h3 class="has-text-align-center has-primary-accent-color has-text-color">
+  Professional WordPress Development
+</h3>
+```
+
 ### Modifying Styles
 
 1. Edit `resources/css/app.css` for theme styles

diff --git a/app/setup.php b/app/setup.php
@@ -203,6 +203,78 @@
     }
 });
 
+/**
+ * ACF Product Details Field Group
+ */
+add_action('acf/init', function () {
+    if (! function_exists('acf_add_local_field_group')) {
+        return;
+    }
+
+    acf_add_local_field_group([
+        'key' => 'group_product_details',
+        'title' => 'Product Details',
+        'fields' => [
+            [
+                'key' => 'field_product_features',
+                'label' => 'Features',
+                'name' => 'product_features',
+                'type' => 'wysiwyg',
+                'instructions' => 'Describe the key features of this product or service.',
+                'required' => 0,
+                'default_value' => '',
+                'tabs' => 'all',
+                'toolbar' => 'full',
+                'media_upload' => 0,
+                'delay' => 0,
+            ],
+            [
+                'key' => 'field_product_included',
+                'label' => 'What\'s Included',
+                'name' => 'product_included',
+                'type' => 'wysiwyg',
+                'instructions' => 'List what\'s included with this product or service.',
+                'required' => 0,
+                'default_value' => '',
+                'tabs' => 'all',
+                'toolbar' => 'full',
+                'media_upload' => 0,
+                'delay' => 0,
+            ],
+            [
+                'key' => 'field_product_pricing',
+                'label' => 'Pricing Details',
+                'name' => 'product_pricing',
+                'type' => 'wysiwyg',
+                'instructions' => 'Provide detailed pricing information for this product or service.',
+                'required' => 0,
+                'default_value' => '',
+                'tabs' => 'all',
+                'toolbar' => 'full',
+                'media_upload' => 0,
+                'delay' => 0,
+            ],
+        ],
+        'location' => [
+            [
+                [
+                    'param' => 'post_type',
+                    'operator' => '==',
+                    'value' => 'product',
+                ],
+            ],
+        ],
+        'menu_order' => 10,
+        'position' => 'normal',
+        'style' => 'default',
+        'label_placement' => 'top',
+        'instruction_placement' => 'label',
+        'hide_on_screen' => '',
+        'active' => true,
+        'description' => 'Custom fields for product detail sections displayed in accordion format on single product pages.',
+    ]);
+});
+
 /**
  * WooCommerce Support
  */

diff --git a/resources/css/app.css b/resources/css/app.css
@@ -18,6 +18,7 @@
  * 10. Button Style Variants
  * 11. WordPress Layout Fixes
  * 12. Mobile Navigation Accordion
+ * 13. WooCommerce Product Page Content Styling
  */
 
 /* -----------------------------------------------------------------------------
@@ -764,4 +765,28 @@ body .gform_wrapper .gform_body {
     opacity: 1;
     pointer-events: auto;
   }
-}
+}
+
+/* -----------------------------------------------------------------------------
+ * 13. WooCommerce Product Page Content Styling
+ * -------------------------------------------------------------------------- */
+
+/**
+ * Single Product Page - Typography and Color Overrides
+ *
+ * Forces consistent dark text color (var(--color-main)) for all headings and
+ * paragraphs in product content area, overriding any block editor color classes.
+ *
+ * This ensures:
+ * - Headings (H2, H3) use main color (#171b23 - dark)
+ * - Paragraphs use main color for maximum readability
+ * - No hardcoded block editor color classes interfere with design
+ *
+ * Note: This overrides the default WordPress block color system for products only.
+ * Regular blog posts and pages use different color hierarchy via .e-content styles.
+ */
+.single-product .product-full-content h3,
+.single-product .product-full-content h2,
+.single-product .product-full-content p {
+  color: var(--color-main);
+}