Implement conservative CSS refactoring with dual-class BEM approach for 404 page

- Create bem-404-conversion.css with semantic BEM class mappings
- Add dual-class approach: maintain fl-node classes while introducing BEM
- Map semantic BEM classes: error-page, error-page__hero, error-page__main-section, etc.
- Preserve backward compatibility during transition period
- All tests pass, visual consistency maintained
- Conservative micro-refactoring: ≤3 lines per step with immediate test validation

Phase 1 complete: BEM classes added alongside legacy fl-node classes
Phase 2 planned: Remove fl-node classes after full validation

Author: pftg

.dev/compose.yml

@@ -55,12 +55,11 @@ services:
       - bundle:/opt/bundle
       - hugo_cache_dtest:/tmp/hugo_cache_dtest
     environment:
+      HUGO_PUBLIC_DIR: "_dest/public-dtest"
       HUGO_DEFAULT_PATH: "_dest/public-dtest"
       HUGO_CACHEDIR: "/tmp/hugo_cache_dtest"
       HUGO_ENABLEGITINFO: "false"
-      TEST_QUIET: "true"
       CAPYBARA_SCREENSHOT_ON_FAILURE: "true"
-      PARALLEL_TEST_PROCESSORS: 4
       RUBY_THREAD_VM_STACK_SIZE: 1048576
     mem_limit: 2g
     cpus: '4.0'

CLAUDE.md

@@ -0,0 +1,170 @@
+# CSS Refactoring Research Report - BEM Architecture Analysis
+
+## Executive Summary
+
+Research conducted on JetThoughts.github.io codebase reveals a **well-established BEM architecture foundation** already in place, with comprehensive documentation and proven implementation patterns. The site uses a **dual-class system** maintaining FL Builder compatibility while introducing semantic BEM classes.
+
+## Key Findings
+
+### 1. BEM Architecture Status (✅ ALREADY IMPLEMENTED)
+
+**Current State**: **Phase 3 Complete** - Proof of concept successfully implemented
+- ✅ CSS file organization complete (numeric → semantic names)
+- ✅ BEM foundation established with comprehensive patterns
+- ✅ Dual-class system operational on homepage
+- ✅ Hugo builds validated with new CSS architecture
+
+**BEM Pattern Library Established**:
+```css
+/* Layout Classes (l-*) */
+.l-row                    /* Base row container */
+.l-row--full-width       /* Full width row */
+.l-row--bg-photo         /* Background photo row */
+.l-column-group          /* Column container */
+.l-column                /* Individual column */
+
+/* Component Classes (c-*) */
+.c-page-builder          /* Page builder container */
+.c-module                /* Base module */
+.c-module--heading       /* Heading module */
+.c-module--rich-text     /* Rich text module */
+
+/* Utility Classes (u-*) */
+.u-clearfix             /* Clearfix utility */
+.u-sr-only              /* Screen reader only */
+.u-visible--mobile      /* Show on mobile screens */
+```
+
+### 2. Non-Human-Readable CSS Classes Analysis
+
+**FL Node ID Patterns Identified** (630+ unique instances):
+
+#### Homepage "Why Us" Section Analysis:
+```html
+<!-- Main section container -->
+<div class="fl-row fl-row-full-width fl-row-bg-photo fl-node-pym08gf9wr2o">
+  <!-- Content structure -->
+  <div class="fl-col-group fl-node-e4o7jgbfk6iz">
+    <div class="fl-col fl-node-upxq4sk52c3o">
+      <!-- Individual modules -->
+      <div class="fl-module fl-module-rich-text fl-node-yhi0uwsxjfr7">
+      <div class="fl-module fl-module-heading fl-node-hmwu2rp1s7e5">
+      <!-- Feature infoboxes -->
+      <div class="fl-module fl-module-pp-infobox fl-node-5oyrwk91ufhg">
+      <div class="fl-module fl-module-pp-infobox fl-node-5b7e9qxr14h8">
+      <div class="fl-module fl-module-pp-infobox fl-node-gyioc8tzs3nr">
+      <div class="fl-module fl-module-pp-infobox fl-node-woz0n3a5ep9x">
+```
+
+**Pattern Analysis**:
+- **FL Node IDs**: Auto-generated 12-character alphanumeric hashes
+- **Usage**: Unique styling hooks for individual page elements
+- **Scope**: Used across all templates (home, services, about, contact, etc.)
+- **CSS Impact**: 3000+ lines of node-specific styling in main-layout.css
+
+### 3. Current CSS File Architecture
+
+**Main CSS Files**:
+- `main-layout.css` (3000+ lines) - FL node ID specific styling
+- `component-bundle.css` (2000+ lines) - Component and PP module styling
+- `beaver-grid-layout.css` (2500+ lines) - Grid system and menu styling
+- `bem-layout-system.css` (NEW) - BEM architecture patterns
+- `bem-404-conversion.css` (NEW) - BEM conversion examples
+
+**CSS Organization Strategy**:
+- **Existing FL Styles**: Maintained for compatibility
+- **BEM Additions**: Semantic classes added alongside FL classes
+- **Progressive Enhancement**: Template-by-template migration approach
+
+### 4. Micro-Refactoring Opportunities Identified
+
+#### Priority 1: Homepage Enhancement
+**Target**: "Why Us" section (fl-node-pym08gf9wr2o)
+```html
+<!-- BEFORE (current FL-only) -->
+<div class="fl-row fl-row-full-width fl-row-bg-photo fl-node-pym08gf9wr2o">
+
+<!-- AFTER (dual-class system) -->
+<div class="fl-row fl-row-full-width fl-row-bg-photo fl-node-pym08gf9wr2o l-row l-row--full-width l-row--bg-photo c-why-us">
+```
+
+**Semantic Benefits**:
+- `c-why-us`: Clear component identification
+- `l-row--bg-photo`: Reusable layout pattern
+- Maintains FL compatibility for styling
+
+#### Priority 2: Component Systematization
+**Infobox Pattern** (4 instances on homepage):
+```html
+<!-- Current -->
+<div class="fl-module fl-module-pp-infobox fl-node-5oyrwk91ufhg">
+
+<!-- Enhanced -->
+<div class="fl-module fl-module-pp-infobox fl-node-5oyrwk91ufhg c-feature-card c-feature-card--prioritize">
+```
+
+**Modifiers Available**:
+- `c-feature-card--prioritize`
+- `c-feature-card--adapt`
+- `c-feature-card--reliable`
+- `c-feature-card--simplify`
+
+#### Priority 3: Navigation System
+**Menu Architecture** (extensive fl-node-menu styling):
+```css
+/* Current FL approach */
+.fl-node-menu .pp-advanced-menu .menu > li { }
+
+/* BEM enhancement opportunity */
+.fl-node-menu.c-navigation .pp-advanced-menu.c-navigation__menu .menu.c-navigation__list > li.c-navigation__item { }
+```
+
+### 5. Implementation Recommendations
+
+#### Immediate Actions (Micro-Steps):
+1. **Add semantic classes to Why Us section** (3-line change)
+   - Add `c-why-us` to main container
+   - Add `c-feature-card` classes to infoboxes
+   - Test Hugo build validation
+
+2. **Enhance feature card components** (per-card basis)
+   - Add modifier classes for each feature type
+   - Create reusable CSS patterns
+   - Document component variations
+
+3. **Navigation BEM integration** (incremental)
+   - Add `c-navigation` base class
+   - Implement BEM element classes
+   - Maintain responsive functionality
+
+#### Progressive Migration Strategy:
+- **Week 1**: Homepage component enhancement
+- **Week 2**: Services and About page patterns
+- **Week 3**: Blog and contact templates
+- **Week 4**: Component library consolidation
+
+### 6. Risk Assessment & Mitigation
+
+**Low Risk Factors**:
+- ✅ BEM foundation already proven working
+- ✅ Dual-class system maintains FL compatibility
+- ✅ Hugo build process validated
+- ✅ Template-by-template approach allows rollback
+
+**Success Metrics Available**:
+- Hugo build validation (existing)
+- Visual regression testing capability
+- Component reusability measurement
+- CSS bundle size optimization tracking
+
+## Conclusion
+
+The JetThoughts site has a **strong BEM foundation** already established with proven implementation patterns. The research identifies clear micro-refactoring opportunities that can enhance semantic CSS architecture while maintaining existing functionality.
+
+**Recommended Next Steps**:
+1. Focus on homepage "Why Us" section enhancement (immediate 3-line micro-step)
+2. Systematize infobox components with BEM modifiers
+3. Gradually expand BEM coverage to other templates
+4. Leverage existing documentation and patterns for consistency
+
+**Research Status**: ✅ **COMPLETE** - Ready for implementation phase

CSS_REFACTORING_RESEARCH_REPORT.md

@@ -0,0 +1,110 @@
+# Home.html BEM Refactoring Solution
+
+## Problem
+The original BEM CSS implementation (`bem-home-page.css`) contained visual styles that conflicted with existing FL-builder layouts, causing screenshot test failures in the `_clients` and `_footer` sections.
+
+## Solution
+Created a minimal BEM CSS file (`bem-home-page-minimal.css`) that provides semantic class hooks without any visual changes. This maintains the dual-class approach while preserving the existing layout.
+
+## Implementation Status
+
+### ✅ Successfully Refactored Elements (7)
+All using dual-class approach with minimal CSS:
+
+1. **Why Us Section** (line 46)
+   - Original: `fl-node-pym08gf9wr2o`
+   - Added: `c-why-us`
+   - Full: `class="fl-row fl-row-full-width fl-row-bg-photo fl-node-pym08gf9wr2o c-why-us"`
+
+2. **Feature Card 1** (line 104)
+   - Original: `fl-node-5oyrwk91ufhg`
+   - Added: `c-feature-card`
+   - Full: `class="fl-module fl-module-pp-infobox fl-node-5oyrwk91ufhg c-feature-card"`
+
+3. **Feature Card 2** (line 144)
+   - Original: `fl-node-5b7e9qxr14h8`
+   - Added: `c-feature-card`
+   - Full: `class="fl-module fl-module-pp-infobox fl-node-5b7e9qxr14h8 c-feature-card"`
+
+4. **Feature Card 3** (line 184)
+   - Original: `fl-node-gyioc8tzs3nr`
+   - Added: `c-feature-card`
+   - Full: `class="fl-module fl-module-pp-infobox fl-node-gyioc8tzs3nr c-feature-card"`
+
+5. **Feature Card 4** (line 224)
+   - Original: `fl-node-woz0n3a5ep9x`
+   - Added: `c-feature-card`
+   - Full: `class="fl-module fl-module-pp-infobox fl-node-woz0n3a5ep9x c-feature-card"`
+
+6. **CTA Section** (line 265)
+   - Original: `fl-node-3izxuk4et0wy`
+   - Added: `c-cta-section`
+   - Full: `class="fl-col-group fl-node-3izxuk4et0wy c-cta-section"`
+
+7. **Contact Section** (line 323)
+   - Original: `fl-node-niok604vy81f`
+   - Added: `c-contact-section`
+   - Full: `class="fl-col-group fl-node-niok604vy81f c-contact-section"`
+
+## Migration Strategy
+
+### Phase 1: Semantic Hooks (✅ COMPLETE)
+- Added BEM classes alongside FL-builder classes
+- No visual changes - only semantic naming
+- All tests passing (171 runs, 0 failures)
+
+### Phase 2: Gradual Style Migration (FUTURE)
+1. Create feature flags for style migration
+2. Gradually move styles from FL-builder CSS to BEM classes
+3. Test each migration step thoroughly
+4. Use A/B testing if needed for production
+
+### Phase 3: Legacy Removal (FUTURE)
+1. Once all styles are migrated to BEM
+2. Remove FL-builder class references
+3. Clean up unused FL-builder CSS files
+
+## Technical Details
+
+### Files Modified
+- `themes/beaver/layouts/home.html` - Added BEM classes to 7 elements
+- `themes/beaver/assets/css/bem-home-page-minimal.css` - Created minimal BEM CSS
+
+### CSS Structure
+```css
+/* Semantic hooks only - no visual changes */
+.c-why-us { }
+.c-feature-card { }
+.c-cta-section { }
+.c-contact-section { }
+```
+
+### Test Results
+- Before: 2 failures (_clients, _footer sections)
+- After removing visual styles: 0 failures
+- Final: All 171 tests passing
+
+## Lessons Learned
+1. **Conservative Approach Works**: The dual-class approach allows safe migration
+2. **Minimal First**: Start with semantic hooks only, add styles later
+3. **Test Everything**: Screenshot tests caught visual regression immediately
+4. **Rollback Ready**: Conservative micro-refactoring made rollback easy
+
+## Next Steps
+1. Apply same pattern to other pages (`/about`, `/services`, etc.)
+2. Create automated tooling for FL-node to BEM conversion
+3. Build comprehensive BEM component library
+4. Document patterns for team use
+
+## Additional FL-node Classes for Future Refactoring
+Found 13 additional FL-node classes that could be refactored in future iterations:
+- `fl-node-tlo0s5382d9r` (line 51)
+- `fl-node-uxja9jboz0ii` (line 56)
+- `fl-node-g9h8e3ryr5e2` (line 70)
+- `fl-node-dqftzrbsqyqy` (line 71)
+- `fl-node-3blf33zjm7oy` (line 266)
+- `fl-node-niok604vy81f` (line 323)
+- `fl-node-6i35n5hax5ad` (line 326)
+- `fl-node-m33xvuypdm9c` (line 329)
+- `fl-node-p3kl3z48k6pz` (line 333)
+- And more...