site-builder/docs/plans/2026-01-26-site-builder-design.md

# Site Builder - Phase 1 Design

## Overview

A visual website builder using GrapesJS that allows users to create multi-page websites through drag-and-drop without writing code. Phase 1 focuses on core editor functionality with local storage persistence.

## Architecture

### File Structure

```
site-builder/
├── index.html          # Main editor page
├── preview.html        # Preview page (renders saved content)
├── CLAUDE.md           # Comprehensive project documentation
├── css/
│   └── editor.css      # Custom editor styles (dark theme)
├── js/
│   └── editor.js       # Editor initialization and configuration
└── docs/
    └── plans/
        └── 2026-01-26-site-builder-design.md
```

### Dependencies (CDN)

- **GrapesJS Core** - The main editor engine
- **grapesjs-blocks-basic** - Basic building blocks (columns, text, images)
- **grapesjs-preset-webpage** - Comprehensive webpage blocks (hero, features, etc.)
- **grapesjs-plugin-forms** - Form elements (inputs, textareas, buttons)
- **grapesjs-style-gradient** - Gradient background support
- **Font Awesome 5** - Icons for blocks
- **Google Fonts** - 8 font families

## Features Implemented

### Editor Interface

1. **Top Navigation Bar**
   - Logo/branding
   - Device switcher (Desktop/Tablet/Mobile)
   - Undo/Redo buttons
   - Clear canvas button
   - Export button (download site as ZIP)
   - Preview button

2. **Left Panel - Blocks/Pages/Layers**
   - Blocks tab: Draggable components organized by category
   - Pages tab: Multi-page management (add, edit, delete, switch pages)
   - Layers tab: Component hierarchy tree view

3. **Center - Canvas**
   - Live preview of the website being built
   - Click to select components
   - Drag to reposition components
   - Resize handles on selected components
   - Right-click context menu

4. **Right Panel - Styles/Settings**
   - **Guided Mode**: Context-aware quick presets based on element type
   - **Advanced Mode**: Full GrapesJS style manager with all CSS properties
   - **Settings tab**: Component-specific traits/attributes

### Block Categories

**Layout**
- Section: Basic content section with centered container
- Section (Background): Section with image background and customizable overlay
- Section (Video BG): Section with video background (YouTube/Vimeo/MP4 support)
- Logo: Styled logo element with icon and text
- Navigation: Dynamic nav bar with automatic page sync
- Footer: Footer with links and copyright
- Columns (1-4): Flexible column layouts
- 2 Columns 3/7: Asymmetric column layout

**Basic**
- Text: Paragraph text
- Heading: H2 heading
- Button: Styled link button
- Divider: Horizontal rule with color/thickness controls
- Spacer: Vertical spacing element
- Text Box: Styled container for overlaying on backgrounds

**Media**
- Image: Responsive image
- Video: Universal video block (supports YouTube, Vimeo, and direct files)

**Sections**
- Hero (Image): Hero section with image background and overlay
- Hero (Video): Hero section with video background and overlay
- Hero (Simple): Hero section with gradient background
- Features Grid: 3-column feature cards
- Testimonials: Customer testimonials with star ratings
- Pricing Table: 3-tier pricing comparison
- Contact Section: Contact info with form
- Call to Action: CTA banner with gradient background

**Forms**
- Form, Input, Textarea, Select, Button, Label, Checkbox, Radio

### Video System

The unified Video block and Section Video BG support multiple sources:
- **YouTube**: Paste any youtube.com or youtu.be URL
- **Vimeo**: Paste any vimeo.com URL
- **Direct Files**: .mp4, .webm, .ogg, .mov files
- URLs are auto-detected and converted to proper embed format
- Background videos auto-play muted and loop

### Context-Aware Styling

The guided panel shows only relevant options based on selected element type:

*For Text Elements (p, h1-h6, span, label):*
- Text Color: 8 preset colors
- Font Family: 8 Google Fonts
- Text Size: XS, S, M, L, XL, 2XL
- Font Weight: Light, Normal, Medium, Semi, Bold

*For Links/Buttons (a):*
- Link URL input with "Open in new tab" option
- Button Color: 8 preset colors (auto-adjusts text for contrast)
- Text Color, Font, Size, Weight options
- Border Radius and Padding

*For Containers (div, section, etc):*
- Background Color: 8 preset colors
- Background Gradient: 12 gradient presets
- Background Image: URL input with size/position controls
- Padding: None, S, M, L, XL
- Border Radius: None, S, M, L, Full

*For Overlays (.bg-overlay):*
- Overlay Color: 6 preset colors (black, white, blue, green, purple, gray)
- Opacity Slider: 0-100% with real-time preview

*For Navigation (nav):*
- Sync with Pages: Auto-generate links from page list
- Add Link: Add new navigation link
- Link Management: View and delete individual links
- Background Color and Spacing controls

*For Dividers (hr):*
- Divider Color: 8 preset colors
- Line Thickness: 1px, 2px, 3px, 4px, 6px

### Multi-Page Support

- **Pages Tab**: View all pages in project
- **Add Page**: Create new pages with name and slug
- **Edit Page**: Modify page name and slug
- **Delete Page**: Remove pages (cannot delete last page)
- **Page Switching**: Auto-saves content when switching
- **Navigation Sync**: Auto-generate nav links from pages
- **Preview**: Multi-page preview with page selector

### Context Menu (Right-Click)

- Edit Content: Enable inline text editing
- Duplicate: Copy element in place (Ctrl+D)
- Copy/Paste: Clipboard operations (Ctrl+C/V)
- Move Up/Down: Reorder elements
- Select Parent: Navigate up component tree
- Wrap in Container: Wrap element in div
- Delete: Remove element (Del)

### Google Fonts

The following Google Fonts are preloaded and available:
- Inter (sans-serif)
- Roboto (sans-serif)
- Open Sans (sans-serif)
- Poppins (sans-serif)
- Montserrat (sans-serif)
- Playfair Display (serif)
- Merriweather (serif)
- Source Code Pro (monospace)

### Responsive Design

- Desktop (default full width)
- Tablet (768px viewport)
- Mobile (375px viewport)
- Automatic column stacking on mobile

### Persistence

- Auto-save to localStorage every change
- Auto-load on page refresh
- Multi-page storage with per-page HTML/CSS
- Preview saves all pages for multi-page preview

### Export Feature

- **Export to ZIP**: Download all pages as HTML files in a ZIP archive
- **Options**:
  - Minify CSS: Remove whitespace and comments from CSS
  - Include Google Fonts: Add font preload links
- Uses JSZip library (loaded dynamically on demand)
- Each page becomes a standalone HTML file with embedded styles
- Includes responsive CSS reset and mobile column stacking

### Keyboard Shortcuts

- `Ctrl/Cmd + Z` - Undo
- `Ctrl/Cmd + Shift + Z` or `Ctrl/Cmd + Y` - Redo
- `Ctrl/Cmd + C` - Copy
- `Ctrl/Cmd + V` - Paste
- `Ctrl/Cmd + D` - Duplicate
- `Delete` / `Backspace` - Remove selected component
- `Escape` - Deselect / Close modals

## Usage

1. Open via HTTP server (e.g., `python -m http.server 8000`)
2. Navigate to `http://localhost:8000`
3. Drag blocks from the left panel onto the canvas
4. Click elements to select and style them
5. Use Pages tab to create multiple pages
6. Use Navigation block and "Sync with Pages" for dynamic menus
7. Add Video blocks and paste YouTube/Vimeo URLs in Settings
8. Switch between Guided/Advanced styling modes
9. Test responsiveness with device switcher
10. Right-click for context menu options
11. Click Preview to see the final output with page navigation
12. Changes auto-save to browser storage

## Technical Notes

### Video Embedding
- YouTube/Vimeo embeds may show errors in the GrapesJS canvas due to nested iframe restrictions
- Videos display correctly in Preview mode and on published sites
- Use the Settings tab to edit video URLs

### Local Storage Keys
- `sitebuilder-project` - GrapesJS auto-save data
- `sitebuilder-pages` - Multi-page data
- `sitebuilder-project-preview` - Preview data

## Future Phases

### Phase 2: Backend Integration
- PHP backend for user authentication
- Database storage for projects
- Multiple project support

### Phase 3: Publishing
- Save/publish sites to server
- Subdomain or custom domain support
- Template library

### Phase 4: Enhancements
- More block types
- Custom CSS injection
- Asset manager for images
- SEO settings per page
- Export to HTML/CSS files