commit f3bd01ef3b69d979d08ca6d1b8be4c4d266cd7e5 Author: Hanson.xyz Dev Date: Fri Nov 28 15:52:47 2025 -0600 Initial commit: project documentation and gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..d60d3d75 --- /dev/null +++ b/.gitignore @@ -0,0 +1,42 @@ +# Dependencies +node_modules/ + +# Build outputs (keep dist/ for deployment) +# dist/ + +# Environment +.env +.env.local +.env.*.local + +# WordPress config with secrets (keep sample) +# wp-config.php # Commenting out - we want to track this for snapshots + +# Uploads (too large for git, backup separately) +wp-content/uploads/ + +# Cache and temp files +*.log +*.cache +.DS_Store +Thumbs.db + +# IDE +.idea/ +.vscode/ +*.swp +*.swo + +# Debug +wp-content/debug.log + +# Vite +*.local + +# OS +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..76148f9d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,285 @@ +# HomeProz WordPress Website Development + +## Project Overview + +**Client:** HomeProz Real Estate (Albert Lea, MN area) +**Developer:** Hanson.xyz +**Contract:** $6,000 development + $600/yr hosting + +**Goal:** Build a custom WordPress theme with ACF-powered property listing system, replacing their current GoDaddy Website Builder site while maintaining their dark/rust brand aesthetic. + +## Reference Documents + +All planning documents located in: +`/var/www/html/contract/Contracts/WordPress-Website/_scratch/site_analysis/` + +| Document | Purpose | +|----------|---------| +| `DESIGN-DOCUMENT.md` | Visual design specs, colors, typography, layouts, all template specifications | +| `IMPLEMENTATION-PLAN.md` | Technical architecture, ACF fields, CPT structure, phase breakdown | +| `homepage-full.png` | Screenshot of existing site (full page) | +| `homepage-viewport.png` | Screenshot of existing site (above fold) | + +Contract documents in parent directory: +- `CONTRACT-AT-A-GLANCE.txt` +- `DRAFT-HomeProz-WordPress-Website-Contract.txt` + +--- + +## Development Mandates + +### UI & Styling + +1. **Use Tailwind CSS** as the UI framework +2. **Use SCSS** for custom styles, compiled via Vite +3. **Page-scoped SCSS**: Every page-specific SCSS file must be wrapped: + ```scss + .The_Page_Name { + // all rules for this page go here + } + ``` +4. **Page body classes**: Every page template must add a class to the `` tag: + ```php + + + + + + + + ``` + +### JavaScript + +1. **Use jQuery** for all JS functionality +2. **Page-scoped JS**: All page-specific JS must start with early return: + ```javascript + (function($) { + if (!$('.The_Page_Name').length) return; + + // page-specific code here + })(jQuery); + ``` +3. **No inline scripts** - all JS in external files +4. **No inline event handlers** - use jQuery event binding +5. **Use Vite** to bundle JS/CSS + +### File Organization + +1. **Co-locate related files** - JS and SCSS files live alongside their related PHP templates, NOT in separate `/js/` or `/css/` directories +2. Example structure: + ``` + template-parts/ + ├── property/ + │ ├── property-card.php + │ ├── property-card.scss + │ └── property-card.js + ├── components/ + │ ├── hero-section.php + │ ├── hero-section.scss + ``` + +### Error Handling + +1. **No empty catch blocks** - never write `try {} catch() { /* error occurred */ }` +2. **Let errors surface** - only use try/catch when genuinely required for functionality +3. **No fallback/legacy implementations** - assume modern browser, assume libraries exist +4. Dual implementations create security holes and maintenance nightmares + +### Rendering + +1. **Server-side render everything** - no client-side template rendering +2. **No preloaders/spinners** except: + - AJAX lookups (property filtering, search) + - Only show spinner on FIRST data load + - Subsequent AJAX calls show stale data until new data arrives +3. **Exception**: Search page will be AJAX-based and refined iteratively + +### Animations + +1. **No custom animations** - no hover effects, no transitions, no "slide up on scroll" +2. **Exception**: Animations built into Tailwind/UI library are acceptable +3. Keep it static and fast + +### Version Control + +1. **Git is for SNAPSHOTS** - not optimized for public/collaboration +2. After every development phase: + ```bash + mysqldump -u [user] -p [database] > db-snapshot-phase-X.sql + git add -A + git commit -m "Phase X: [description]" + ``` +3. Database dumps committed alongside code + +### Decision Making + +1. **ASK before implementing** when facing architectural choices +2. Examples of decisions requiring developer input: + - CSS framework choice + - Preprocessor choice + - JS library choice + - Plugin alternatives + - Data structure approaches +3. Get clarity, then proceed + +--- + +## Technology Stack + +| Component | Choice | +|-----------|--------| +| CMS | WordPress 6.x | +| PHP | 8.1+ | +| Database | MySQL/MariaDB | +| CSS Framework | Tailwind CSS | +| CSS Preprocessor | SCSS | +| JavaScript | jQuery | +| Build Tool | Vite | +| Custom Fields | ACF Pro | +| Forms | Contact Form 7 | +| SEO | Yoast SEO | + +--- + +## Theme Structure + +``` +themes/homeproz/ +├── assets/ +│ └── images/ +├── src/ # Vite source files +│ ├── main.js # JS entry point +│ ├── main.scss # SCSS entry point +│ └── tailwind.css # Tailwind imports +├── dist/ # Vite build output +├── inc/ +│ ├── acf-fields.php +│ ├── custom-post-types.php +│ ├── enqueue.php +│ ├── theme-setup.php +│ └── template-functions.php +├── template-parts/ +│ ├── header/ +│ │ ├── site-header.php +│ │ ├── site-header.scss +│ │ └── navigation.js +│ ├── footer/ +│ │ └── site-footer.php +│ ├── property/ +│ │ ├── property-card.php +│ │ ├── property-card.scss +│ │ ├── property-filters.php +│ │ ├── property-filters.js +│ │ └── property-filters.scss +│ └── components/ +│ ├── agent-card.php +│ ├── agent-card.scss +│ └── ... +├── patterns/ +├── front-page.php +├── page.php +├── page-about.php +├── page-contact.php +├── archive.php +├── single.php +├── archive-property.php +├── single-property.php +├── search.php +├── 404.php +├── header.php +├── footer.php +├── functions.php +├── style.css +├── theme.json +├── package.json +├── vite.config.js +├── tailwind.config.js +└── postcss.config.js +``` + +--- + +## Brand Specifications + +### Colors + +| Name | Hex | Usage | +|------|-----|-------| +| Background Dark | `#0A0A0A` | Primary background | +| Background Card | `#161616` | Elevated surfaces | +| Accent Primary | `#9F3730` | CTAs, buttons | +| Accent Hover | `#C8473F` | Button hover | +| Accent Light | `#BF524B` | Links | +| Text Primary | `#F5F5F5` | Headlines | +| Text Muted | `#B0B0B0` | Body text | +| Border | `#2A2A2A` | Dividers | +| Success | `#2E7D32` | Active listings | +| Warning | `#F9A825` | Pending listings | +| Sold | `#757575` | Sold listings | + +### Typography + +| Element | Font | +|---------|------| +| Headlines | Abril Fatface | +| Body | Inter (or Droid Sans) | + +--- + +## Page Class Names Reference + +| Template | Body Class | +|----------|------------| +| `front-page.php` | `Home_Page` | +| `page.php` | `Default_Page` | +| `page-about.php` | `About_Page` | +| `page-contact.php` | `Contact_Page` | +| `archive.php` | `Blog_Archive` | +| `single.php` | `Single_Post` | +| `archive-property.php` | `Properties_Archive` | +| `single-property.php` | `Single_Property` | +| `search.php` | `Search_Page` | +| `404.php` | `Error_404` | + +--- + +## Development Phases + +1. **Foundation** - Theme scaffold, Vite setup, Tailwind config, header/footer +2. **Property System** - CPT, ACF fields, archive, single, filters +3. **Page Templates** - Homepage, About, Contact, Blog, 404, Search +4. **Block Patterns** - Reusable Gutenberg patterns +5. **Content & SEO** - Schema markup, meta tags, initial content +6. **Performance & Security** - Caching, optimization, security hardening +7. **Testing & Training** - QA, documentation, client training + +Each phase ends with: +```bash +mysqldump homeproz > db-snapshot-phase-X.sql +git add -A +git commit -m "Phase X complete: [description]" +``` + +--- + +## Open Decisions (Resolve Before Starting) + +1. ~~CSS Framework~~ → **Tailwind CSS** (confirmed) +2. ~~JS Library~~ → **jQuery** (confirmed) +3. ~~Preprocessor~~ → **SCSS** (confirmed) +4. ~~Build tool~~ → **Vite** (confirmed) +5. Agents: ACF options page vs Agent CPT? +6. Testimonials: Static content vs Testimonial CPT? +7. Maps: Embed codes vs Google Maps API? +8. Form notifications: Which email address(es)? + +--- + +## Notes + +- Dark theme is unconventional for real estate but matches client brand +- Property images use 16:10 aspect ratio (better for real estate than 16:9) +- No individual agent pages - all agents on single About page +- Sold properties remain visible (social proof) +- MLS numbers are display-only (no API integration) diff --git a/README.md b/README.md new file mode 100644 index 00000000..eaf1f099 --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +# HomeProz Real Estate WordPress Site + +Custom WordPress theme for HomeProz Real Estate (Albert Lea, MN). + +## Project Structure + +- `/wp-content/themes/homeproz/` - Custom theme +- `/db-snapshots/` - Database snapshots for each development phase +- `/contract/` - Project documentation and planning +- `/CLAUDE.md` - Development mandates and specifications + +## Development + +```bash +cd wp-content/themes/homeproz +npm install +npm run dev # Development with hot reload +npm run build # Production build +``` + +## Technology Stack + +- WordPress 6.x +- PHP 8.1+ +- Tailwind CSS +- SCSS (via Vite) +- jQuery +- ACF Pro + +## Client + +HomeProz Real Estate, LLC +111 E Clark St, Albert Lea, MN 56007