+```
+
+### Features
+- Default 2-column layout on desktop
+- 1 column on mobile (< 640px)
+- 4px gap between items (configurable)
+- All child elements prevent column breaks
+
+---
+
+## 2-Column Layout
+
+Use `ease-masonry-2` for a dedicated 2-column grid.
+
+```html
+
+```
+
+---
+
+## Accessibility
+
+### Reduced Motion Support
+
+All masonry layouts automatically respect the `prefers-reduced-motion` media query. Animations and transitions are disabled for users who prefer minimal motion.
+
+```css
+/* Automatically applied if user prefers reduced motion */
+@media (prefers-reduced-motion: reduce) {
+ .ease-masonry > *,
+ .ease-masonry-2 > *,
+ .ease-masonry-3 > *,
+ .ease-masonry-4 > * {
+ transition: none !important;
+ }
+}
+```
+
+### Semantic HTML
+
+Always use semantic HTML within masonry items:
+
+```html
+
+
+
+
Article Title
+
Content...
+
+
+
+
+
+
+
Article Title
+
Content...
+
+
+```
+
+---
+
+## Browser Support
+
+The masonry utilities use CSS Columns, which is supported in all modern browsers:
+
+| Browser | Version |
+|---------|---------|
+| Chrome | 50+ |
+| Firefox | 52+ |
+| Safari | 9+ |
+| Edge | 12+ |
+| Opera | 37+ |
+
+For older browsers, content will render as a single column (graceful degradation).
+
+---
+
+## Performance Tips
+
+1. **Limit column count**: More columns = more layout calculations
+ - Use `ease-masonry-2` or `ease-masonry-3` for best performance
+ - Avoid `ease-masonry-4` on mobile or with 100+ items
+
+2. **Optimize images**: Use responsive images with `srcset` for better performance
+ ```html
+
+ ```
+
+3. **Batch rendering**: If adding items dynamically, batch DOM updates
+ ```javascript
+ const fragment = document.createDocumentFragment();
+ items.forEach(item => fragment.appendChild(item));
+ container.appendChild(fragment);
+ ```
+
+---
+
+## Common Use Cases
+
+### Portfolio Grid
+```html
+
+
My Work
+
+
+
+
+```
+
+### Blog Feed
+```html
+
+
Latest Articles
+
+
+
+
+```
+
+### Image Gallery
+```html
+
+
Photo Collection
+
+
+
+
+```
+
+### Testimonial Wall
+```html
+
+
Client Testimonials
+
+
+
+
+```
+
+---
+
+## Troubleshooting
+
+### Items Not Breaking Properly
+
+**Problem**: Long items span multiple columns unexpectedly.
+
+**Solution**: Ensure parent container has sufficient width or use `ease-masonry-2` for simpler layouts.
+
+### Images Distorting
+
+**Problem**: Images are stretching or shrinking unevenly.
+
+**Solution**: The masonry utilities set `width: 100%` and `height: auto` on images. Check your image aspect ratio or use `object-fit`:
+
+```css
+img {
+ object-fit: cover;
+ aspect-ratio: 1 / 1; /* or your desired ratio */
+}
+```
+
+### Mobile Layout Issues
+
+**Problem**: Content appears in wrong column order on mobile.
+
+**Solution**: Columns naturally reflow to single column on mobile. If items appear out of order, ensure DOM order matches visual order.
+
+---
+
+## Migration Guide
+
+### From CSS Grid
+If migrating from `ease-grid` utilities:
+
+**Before** (Fixed columns):
+```html
+
+
+
+```
+
+**After** (Masonry):
+```html
+
+
+
+```
+
+### From Flexbox
+If migrating from `ease-flex` utilities:
+
+**Before** (Complex wrapping):
+```html
+
Modern responsive website redesign for tech startup with focus on performance and accessibility.
+
+
+
+
+
+
+ Project 2
+
+
Mobile App Design
+
2024
+
+
Complete UI/UX design system for fitness tracking application with custom animations and micro-interactions.
+
+
+
+
+
+
+ Project 3
+
+
Brand Identity
+
2023
+
+
Complete brand identity system including logo, color palette, and design guidelines.
+
+
+
+
+
+
+ Project 4
+
+
E-commerce Platform
+
2023
+
+
Full-featured e-commerce platform with product filtering, cart, and checkout experience.
+
+
+
+
+
+
+ Project 5
+
+
Dashboard Design
+
2023
+
+
Analytics dashboard with real-time data visualization and interactive charts.
+
+
+
+
+
+
+ Project 6
+
+
SaaS Landing
+
2023
+
+
High-converting SaaS landing page with testimonials and pricing comparison.
+
+
+
+
+
+
+
+
+
+
+
+
+
Example 2
+
Image Gallery Masonry (4 Columns)
+
+ Dense 4-column image gallery that adapts responsively: 3 columns on small desktop, 2 on tablet, 1 on mobile.
+
+
+
// Gallery with ease-masonry-4
+
+
+
Image 1
+ Mountain Valley
+
+
+
Image 2
+ Forest Green
+
+
+
Image 3
+ Sunset Gold
+
+
+
Image 4
+ Ocean Blue
+
+
+
Image 5
+ Pink Blossom
+
+
+
Image 6
+ Purple Dreams
+
+
+
Image 7
+ Cyan Sky
+
+
+
Image 8
+ Emerald Leaf
+
+
+
+
+
+
+
+
+
+
+
Example 3
+
Blog Card Masonry (3 Columns)
+
+ Blog articles in a masonry layout with varying content lengths. Each card adapts naturally.
+
+
+
// Blog posts with ease-masonry-3
+
+
+
+ Tutorial
+
+
Getting Started with Masonry
+
Published on Jan 15, 2024
+
+
Learn how to create responsive Pinterest-style layouts using CSS columns. This comprehensive guide covers all masonry utilities and responsive breakpoints.
+
+
+
+
+
+
+ Announcement
+
+
EaseMotion v2.0 Released
+
Published on Jan 10, 2024
+
+
New masonry layout utilities, improved accessibility, and performance enhancements. Download the latest version and start building beautiful layouts.
+
Features include responsive columns, gap variants, and seamless card integration.
+
+
+
+
+
+
+ Tip
+
+
Optimizing Masonry for Performance
+
Published on Jan 5, 2024
+
+
Pro tips for getting the best performance from masonry layouts. Learn about optimal column counts, image optimization, and rendering techniques.
+
+
+
+
+
+
+ Case Study
+
+
Portfolio Redesign with Masonry
+
Published on Dec 28, 2023
+
+
See how one designer increased engagement by 340% using masonry layouts. Includes before/after screenshots and detailed breakdown of design decisions.
+
Learn from real-world implementation and best practices.
+
+
+
+
+
+
+ Guide
+
+
Responsive Design Patterns
+
Published on Dec 20, 2023
+
+
Comprehensive guide to responsive design patterns with masonry. Perfect for designers and developers of all levels.
+
+
+
+
+
+
+ Video
+
+
Masonry Layouts Explained (8 min video)
+
Published on Dec 15, 2023
+
+
Quick video walkthrough of masonry layout utilities. Perfect for getting started quickly and understanding responsive behavior.
+
+
+
+
+
+
+
+
+
+
+
+
+
Responsive Info
+
Responsive Behavior
+
+ All masonry layouts automatically adjust column count based on viewport width. Resize your browser to see the changes.
+
+
+
+
+
ease-masonry-2
+
+
Mobile: 1 column
+
Tablet+: 2 columns
+
Best for: Two-column layouts, image pairs, side-by-side content.
+
+
+
+
+
ease-masonry-3
+
+
Mobile: 1 column
+
Tablet: 2 columns
+
Desktop: 3 columns
+
Best for: Portfolios, galleries, blogs.
+
+
+
+
+
ease-masonry-4
+
+
Mobile: 1 column
+
Tablet: 2 columns
+
Sm Desktop: 3 columns
+
Lg Desktop: 4 columns
+
Best for: Dense galleries, image walls.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/scripts/validate-masonry.py b/scripts/validate-masonry.py
new file mode 100644
index 00000000..e6ad343c
--- /dev/null
+++ b/scripts/validate-masonry.py
@@ -0,0 +1,61 @@
+#!/usr/bin/env python
+"""Validate masonry utilities implementation."""
+
+from pathlib import Path
+
+def validate():
+ errors = []
+
+ # Test 1: Check CSS file syntax
+ css_file = Path('components/masonry.css')
+ if not css_file.exists():
+ errors.append('❌ masonry.css not found')
+ else:
+ css_content = css_file.read_text()
+ brace_count = css_content.count('{') - css_content.count('}')
+ if brace_count == 0:
+ print('✓ CSS Brace Balance: OK')
+ else:
+ errors.append(f'❌ CSS Brace Balance: {brace_count}')
+
+ # Test 2: Check if masonry is imported in main bundle
+ main_css = Path('easemotion.css').read_text()
+ if '@import "./components/masonry.css"' in main_css:
+ print('✓ Masonry imported in bundle: OK')
+ else:
+ errors.append('❌ Masonry not imported in easemotion.css')
+
+ # Test 3: Check doc file
+ doc_file = Path('docs/masonry-layout-guide.md')
+ if doc_file.exists():
+ doc_size = len(doc_file.read_text())
+ print(f'✓ Documentation file exists: OK ({doc_size} bytes)')
+ else:
+ errors.append('❌ masonry-layout-guide.md not found')
+
+ # Test 4: Check demo file
+ demo_file = Path('examples/masonry-layouts.html')
+ if demo_file.exists():
+ print('✓ Demo file exists: OK')
+ else:
+ errors.append('❌ masonry-layouts.html not found')
+
+ # Test 5: Check masonry classes
+ masonry_classes = ['ease-masonry', 'ease-masonry-2', 'ease-masonry-3', 'ease-masonry-4']
+ for cls in masonry_classes:
+ if f'.{cls}' in css_content:
+ print(f'✓ Class {cls}: OK')
+ else:
+ errors.append(f'❌ Class {cls} not found')
+
+ if errors:
+ print('\nValidation Errors:')
+ for error in errors:
+ print(error)
+ return False
+
+ print('\n✓✓✓ All validations passed! ✓✓✓')
+ return True
+
+if __name__ == '__main__':
+ validate()
+ 
+ 
+ 
+
+ 
+ 
+
+
+ 
+ ```
+
+3. **Batch rendering**: If adding items dynamically, batch DOM updates
+ ```javascript
+ const fragment = document.createDocumentFragment();
+ items.forEach(item => fragment.appendChild(item));
+ container.appendChild(fragment);
+ ```
+
+---
+
+## Common Use Cases
+
+### Portfolio Grid
+```html
+