Skip to content

Commit 76f0bbe

Browse files
pftgclaude
pftg
and
claude
authored
refact: continue fixes 4 (#256)
* Remove unused fl-component-layout-alt.css (21KB) - Removed reference from layouts/page/single.html - Deleted themes/beaver/assets/css/fl-component-layout-alt.css - Phase 1 FL CSS removal: 21KB saved - Tests: 39 runs, 57 assertions, 0 failures * Fix visual regression: Replace FL-Builder node reference with inline CSS The removal of .fl-node-2il86phfbmex CSS in commit 8397a2b broke service page layouts. This fix replaces the FL-Builder node reference with inline styles maintaining the same visual behavior (width: 100%). - Updated line 37 in themes/beaver/layouts/services/single.html - Replaced fl-node-2il86phfbmex with inline CSS equivalent - Maintains backward compatibility with FL-Builder structure - Fixes visual regression tests for service pages Tests now pass: 23 runs, 36 assertions, 0 failures 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * wip --------- Co-authored-by: Claude <[email protected]>
1 parent a03475e commit 76f0bbe

File tree

10 files changed

+1444
-997
lines changed

10 files changed

+1444
-997
lines changed

‎docs/component-migration-plan.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Component Migration Plan - FL to BEM Architecture
2+
3+
## Progress Summary
4+
5+
### ✅ Completed
6+
1. **Critical CSS Removal** - 312KB of duplicated inline CSS removed
7+
- All critical CSS injections disabled across 16 template files
8+
- Hugo build successful after removal
9+
- Site functional with render-blocking CSS (acceptable trade-off)
10+
- Test failures reduced from 10 to 7
11+
12+
### 🎯 Current State
13+
- FL-Builder CSS: 1.33MB (active framework, not removable yet)
14+
- Visual regression tests: 7 failures (improvement from 10)
15+
- Site performance: Slightly degraded initial render, but better caching
16+
17+
## Component Migration Strategy
18+
19+
### Phase 1: Core Component Structure (Current)
20+
Create reusable BEM components to replace FL-Builder patterns:
21+
22+
#### 1.1 Navigation Component (c-nav)
23+
```css
24+
.c-nav { /* Main navigation wrapper */ }
25+
.c-nav__menu { /* Menu container */ }
26+
.c-nav__item { /* Individual menu items */ }
27+
.c-nav__link { /* Navigation links */ }
28+
.c-nav--mobile { /* Mobile variation */ }
29+
```
30+
- Replace: `.fl-page-nav`, `.fl-nav-menu`
31+
- Files affected: All page templates
32+
33+
#### 1.2 Hero Component (c-hero)
34+
```css
35+
.c-hero { /* Hero section wrapper */ }
36+
.c-hero__content { /* Content container */ }
37+
.c-hero__title { /* Main heading */ }
38+
.c-hero__description { /* Subtitle/description */ }
39+
.c-hero__cta { /* Call-to-action buttons */ }
40+
.c-hero--centered { /* Centered variation */ }
41+
```
42+
- Replace: `.fl-row-bg-photo`, `.fl-heading`
43+
- High impact: Used on homepage, services, about
44+
45+
#### 1.3 Content Block Component (c-content)
46+
```css
47+
.c-content { /* Content section */ }
48+
.c-content__wrapper { /* Inner wrapper */ }
49+
.c-content__title { /* Section title */ }
50+
.c-content__body { /* Main content */ }
51+
.c-content__media { /* Images/videos */ }
52+
.c-content--reversed { /* Media on left */ }
53+
```
54+
- Replace: `.fl-module-rich-text`, `.fl-col-content`
55+
- Most frequently used component
56+
57+
#### 1.4 Card Component (c-card)
58+
```css
59+
.c-card { /* Card container */ }
60+
.c-card__image { /* Card image */ }
61+
.c-card__body { /* Card content */ }
62+
.c-card__title { /* Card heading */ }
63+
.c-card__text { /* Card description */ }
64+
.c-card__link { /* Card CTA */ }
65+
.c-card--horizontal { /* Horizontal layout */ }
66+
```
67+
- Replace: `.fl-module`, service cards, testimonials
68+
- Used in services, use-cases, clients
69+
70+
### Phase 2: Specialized Components
71+
72+
#### 2.1 Testimonial Component (c-testimonial)
73+
```css
74+
.c-testimonial { /* Testimonial wrapper */ }
75+
.c-testimonial__quote { /* Quote text */ }
76+
.c-testimonial__author { /* Author info */ }
77+
.c-testimonial__company { /* Company/role */ }
78+
.c-testimonial__avatar { /* Author image */ }
79+
```
80+
81+
#### 2.2 CTA Component (c-cta)
82+
```css
83+
.c-cta { /* Call-to-action section */ }
84+
.c-cta__heading { /* CTA title */ }
85+
.c-cta__text { /* CTA description */ }
86+
.c-cta__button { /* CTA button */ }
87+
.c-cta--centered { /* Centered variation */ }
88+
```
89+
90+
#### 2.3 Form Component (c-form) - Already Started
91+
```css
92+
.c-form { /* Form wrapper */ }
93+
.c-form__field { /* Form field */ }
94+
.c-form__label { /* Field label */ }
95+
.c-form__input { /* Input field */ }
96+
.c-form__submit { /* Submit button */ }
97+
```
98+
99+
### Phase 3: Layout Components
100+
101+
#### 3.1 Grid System (c-grid)
102+
```css
103+
.c-grid { /* Grid container */ }
104+
.c-grid__item { /* Grid item */ }
105+
.c-grid--2-col { /* 2 column grid */ }
106+
.c-grid--3-col { /* 3 column grid */ }
107+
.c-grid--responsive { /* Responsive grid */ }
108+
```
109+
110+
#### 3.2 Section Component (c-section)
111+
```css
112+
.c-section { /* Page section */ }
113+
.c-section__container { /* Content container */ }
114+
.c-section--full-width { /* Full width section */ }
115+
.c-section--padded { /* With padding */ }
116+
```
117+
118+
## Implementation Approach
119+
120+
### Micro-refactoring Strategy
121+
1. **Dual-class approach** during transition
122+
- Add BEM classes alongside FL classes
123+
- Gradually remove FL dependencies
124+
- Maintain visual consistency
125+
126+
2. **Component-by-component migration**
127+
- Start with most used components (content blocks)
128+
- Test after each component migration
129+
- Maximum 3 components per sprint
130+
131+
3. **Testing protocol**
132+
- Visual regression test after each component
133+
- Cross-browser validation
134+
- Mobile responsiveness check
135+
- Performance impact measurement
136+
137+
### File Organization
138+
```
139+
themes/beaver/assets/css/components/
140+
├── base/
141+
│ ├── c-grid.css
142+
│ └── c-section.css
143+
├── layout/
144+
│ ├── c-nav.css
145+
│ └── c-footer.css
146+
└── blocks/
147+
├── c-hero.css
148+
├── c-card.css
149+
├── c-content.css
150+
├── c-testimonial.css
151+
├── c-cta.css
152+
└── c-form.css (existing)
153+
```
154+
155+
## Success Metrics
156+
157+
### Target Outcomes
158+
- CSS reduction: 1.33MB → <500KB (62% reduction)
159+
- Page load improvement: 20-30% faster
160+
- Maintenance effort: 50% reduction
161+
- Component reusability: 80% of UI from components
162+
163+
### Quality Gates
164+
- ✅ Visual regression tests pass
165+
- ✅ Lighthouse score maintained/improved
166+
- ✅ Cross-browser compatibility verified
167+
- ✅ Mobile responsiveness validated
168+
- ✅ No accessibility regressions
169+
170+
## Next Actions
171+
172+
### Immediate (Sprint 1)
173+
1. Create c-hero component for homepage
174+
2. Create c-content component for main sections
175+
3. Update templates with dual classes
176+
4. Test and validate changes
177+
178+
### Short-term (Sprint 2-3)
179+
1. Migrate navigation to c-nav
180+
2. Create c-card for services/testimonials
181+
3. Implement c-cta components
182+
4. Begin FL class removal
183+
184+
### Medium-term (Sprint 4-6)
185+
1. Complete all component migrations
186+
2. Remove FL-Builder CSS files
187+
3. Optimize component CSS
188+
4. Document component library
189+
190+
## Risk Mitigation
191+
192+
### Rollback Strategy
193+
- Git commits after each micro-change
194+
- Backup FL CSS files before removal
195+
- Feature flags for component switching
196+
- A/B testing capability
197+
198+
### Testing Safeguards
199+
- Automated visual regression tests
200+
- Manual QA on staging
201+
- Performance monitoring
202+
- User acceptance testing
203+
204+
---
205+
206+
*Goal: Remove all CSS duplications and migrate to reusable component architecture*
207+
*Method: XP methodology with micro-refactoring and continuous validation*
208+
*Timeline: 6 sprints (12 weeks) for complete migration*

‎docs/css-optimization-findings.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# CSS Optimization Findings & Migration Strategy
2+
3+
## Current State Analysis
4+
5+
### Critical CSS Duplication Problem
6+
- **312KB** of critical CSS files duplicating the entire FL-Builder framework inline on every page
7+
- Location: `themes/beaver/layouts/partials/header/critical/`
8+
- Each page loads 30-50KB of inline CSS that cannot be cached
9+
- FL framework repeated 10+ times across the site
10+
11+
### FL-Builder CSS Framework Status
12+
- **1.33MB** total CSS framework (not legacy, but active layout system)
13+
- Visual regression tests confirm FL CSS is required for site functionality
14+
- 10 tests failed when FL CSS was removed in Phase 2
15+
16+
### Files Using Critical CSS Injections
17+
Templates with critical CSS partials:
18+
- `themes/beaver/layouts/page/careers.html` → `critical/careers.html`
19+
- `themes/beaver/layouts/page/services.html` → `critical/services.html`
20+
- `themes/beaver/layouts/clients/single.html` → `critical/single/clients.html`
21+
- `themes/beaver/layouts/services/single.html` → `critical/single/services.html`
22+
- `themes/beaver/layouts/careers/single.html` → `critical/single/careers.html`
23+
- And 11 more templates
24+
25+
## Migration Strategy
26+
27+
### Phase 1: Remove Critical CSS Injections (Immediate)
28+
1. Comment out all `{{ partial "header/critical/*.html" . }}` includes
29+
2. Accept temporary performance degradation (render-blocking CSS)
30+
3. Reduce HTML payload by 30-50KB per page
31+
4. Enable browser caching of FL CSS files
32+
33+
### Phase 2: Create Reusable Component Architecture
34+
1. Migrate from FL-Builder classes to BEM components
35+
2. Use existing `forms-migration.css` as template for dual-class strategy
36+
3. Target components:
37+
- Navigation (c-nav)
38+
- Hero sections (c-hero)
39+
- Content blocks (c-content)
40+
- CTAs (c-cta)
41+
- Forms (c-form) - already started
42+
43+
### Phase 3: Optimize FL Framework
44+
1. Remove orphaned FL node definitions (est. 200-400KB savings)
45+
2. Extract common patterns into shared utilities
46+
3. Consolidate page-specific CSS into component bundles
47+
4. Target: Reduce 1.33MB to <500KB
48+
49+
## Technical Decisions
50+
51+
### Why Disable Critical CSS?
52+
- Eliminates 312KB of duplication
53+
- Reduces maintenance complexity
54+
- Improves cacheability
55+
- Acceptable trade-off: slight increase in render time for massive reduction in payload
56+
57+
### Component Migration Approach
58+
- Dual-class strategy during transition (FL + BEM classes)
59+
- Gradual migration per component
60+
- Maintain visual consistency throughout
61+
- Zero downtime deployment
62+
63+
## Implementation Plan
64+
65+
### Micro-refactoring Strategy (XP Methodology)
66+
- Maximum 3 lines changed per commit
67+
- Run `bin/test` after each change
68+
- Target 5-20 commits per hour
69+
- Shameless green first, then apply flocking rules
70+
71+
### Testing Protocol
72+
1. Visual regression tests after each component migration
73+
2. Performance monitoring with Lighthouse
74+
3. Cross-browser validation
75+
4. Mobile responsiveness checks
76+
77+
## Future Extensibility
78+
79+
### Component Library Benefits
80+
- Reusable across all pages
81+
- Easy to extend with new variations
82+
- Consistent naming conventions
83+
- Reduced CSS footprint
84+
- Better maintainability
85+
86+
### Content Extension Support
87+
- Components designed for content flexibility
88+
- Variant modifiers for different contexts
89+
- Responsive by default
90+
- Accessibility built-in
91+
92+
## Next Steps
93+
94+
1. ✅ Document findings (this document)
95+
2. ⏳ Disable critical CSS injections
96+
3. ⏳ Create component migration plan
97+
4. ⏳ Begin incremental migration
98+
5. ⏳ Optimize remaining FL CSS
99+
100+
## Risk Mitigation
101+
102+
- All changes reversible via git
103+
- Incremental approach minimizes risk
104+
- Visual regression tests catch issues early
105+
- Performance metrics tracked throughout
106+
107+
---
108+
109+
*Last Updated: [Current Date]*
110+
*Goal: Remove all CSS duplications and migrate to reusable component architecture*

0 commit comments

Comments
 (0)