# Web Builder Framework\n\nA modern, modular web development framework built with Nushell for creating optimized static sites with shared assets and component reusability.\n\n## 🌟 Features\n\n- **Multi-page support** with shared asset management\n- **Modular CSS architecture** with automatic optimization\n- **SVG sprite generation** and optimization\n- **Critical CSS inlining** for performance\n- **Development server** with hot reload\n- **Production optimization** with compression\n- **Template system** for rapid page creation\n- **Asset resolution** (@shared/, @page/ references)\n\n## 📁 Project Structure\n\n```plaintext\n├── framework/          # Core framework\n│   ├── core/          # Build scripts (build.nu, dev.nu, prod.nu)\n│   ├── optimizers/    # CSS, HTML, SVG optimizers\n│   └── templates/     # Page templates\n├── shared/            # Shared assets across all pages\n│   ├── css/\n│   │   ├── base/      # Reset, typography\n│   │   ├── components/ # Reusable components\n│   │   └── utilities/ # Color, spacing utilities\n│   ├── svg/common/    # Shared icons, logos\n│   └── js/            # Shared JavaScript\n├── pages/             # Individual pages\n│   ├── homepage/\n│   ├── poster-rust/\n│   └── about/\n└── sites/             # Multi-page site configurations\n```\n\n## 🚀 Quick Start\n\n### Create a New Page\n\n```bash\n# Create a new page\n./wb page create about --template landing\n\n# Start development server with hot reload\n./wb page dev about --watch --port 3000\n\n# Build for production\n./wb page build about --prod\n```\n\n### Available Commands\n\n```bash\n# Page management\n./wb page create <name> [--template <type>]\n./wb page build <name> [--dev|--prod]\n./wb page dev <name> [--watch] [--port N]\n./wb page list\n\n# Site management (multi-page)\n./wb site create <name>\n./wb site build <name>\n./wb site list\n\n# Shared assets\n./wb shared add <file> --type <css|svg|js>\n./wb shared list\n\n# Initialize new project\n./wb init <project-name>\n```\n\n## 📝 Page Configuration\n\nEach page has a `config.toml` file:\n\n```toml\n[page]\nname = "homepage"\ntitle = "My Homepage"\ntype = "landing"\n\n[shared]\n# Reference shared assets\ncss_modules = [\n    "@shared/base/reset.css",\n    "@shared/components/animated-text.css",\n    "@shared/utilities/colors.css"\n]\n\n[local]\n# Page-specific assets\ncss_modules = ["main.css", "components.css"]\ncritical_modules = 2  # First 2 modules inlined\n\n[build]\nminify = true\ncache_bust = true\n```\n\n## 🎨 Shared Asset System\n\n### CSS Architecture\n\n- **Base**: Reset, typography, core styles\n- **Components**: Reusable UI components (buttons, cards, animated text)\n- **Utilities**: Colors, spacing, typography utilities\n- **Local**: Page-specific styles\n\n### Asset Resolution\n\n- `@shared/base/reset.css` → `shared/css/base/reset.css`\n- `@page/homepage/header.css` → `pages/homepage/src/assets/css/header.css`\n- `local/main.css` → Page's local CSS directory\n\n## 🛠️ Available Templates\n\n- **single**: Simple single page\n- **landing**: Landing page with hero section\n- **article**: Article/blog post layout\n- **poster**: Event poster layout\n\n## 🔧 Build Process\n\n1. **Asset Resolution**: Resolve @shared and @page references\n2. **CSS Compilation**: Combine shared + local CSS modules\n3. **Critical CSS**: Inline first N modules for performance\n4. **SVG Optimization**: Compress and sprite generation\n5. **HTML Optimization**: Minify and inject assets\n6. **Compression**: Generate gzipped versions\n\n## 📊 Performance Features\n\n- **Critical CSS inlining** (configurable threshold)\n- **Lazy loading** for non-critical assets\n- **SVG optimization** with precision control\n- **Gzip compression** (up to 78% reduction)\n- **Cache busting** for production builds\n- **Bundle analysis** with size reporting\n\n## 🎯 Use Cases\n\n### Single Page Projects\n\n```bash\n./wb page create portfolio --template single\n./wb page dev portfolio --watch\n```\n\n### Multi-Page Sites\n\n```bash\n./wb site create company-site\n./wb page create homepage --template landing\n./wb page create about --template article\n./wb site build company-site\n```\n\n### Shared Component Library\n\n```bash\n# Add shared button component\necho ".btn { ... }" > shared/css/components/button.css\n\n# Use in any page config.toml\ncss_modules = ["@shared/components/button.css"]\n```\n\n## 🔄 Migration from Single Page\n\nThe current poster project is already migrated as `pages/poster-rust/`. You can:\n\n1. Build it with the framework: `./wb page build poster-rust`\n2. Use it as a template for new posters\n3. Extract more components to shared/\n\n## 💡 Best Practices\n\n1. **Shared First**: Put reusable styles in `shared/`\n2. **Component Architecture**: Create small, focused CSS modules\n3. **Critical CSS**: Keep first 2-3 modules small for inlining\n4. **Asset References**: Use @shared/ for maximum reusability\n5. **Template Customization**: Extend templates rather than starting from scratch\n\n## 🚧 Future Enhancements\n\n- [ ] Hot module replacement for shared assets\n- [ ] Component documentation generator\n- [ ] Theme system with CSS custom properties\n- [ ] JavaScript bundling and optimization\n- [ ] Image optimization pipeline\n- [ ] Deployment integration (Netlify, Vercel)\n- [ ] Performance monitoring and scoring\n\n## 📖 Examples\n\nSee `pages/homepage/` for a basic landing page example and `pages/poster-rust/` for a complex poster layout using the framework.