diff --git a/CLAUDE.md b/CLAUDE.md index 50daf9ad..97f711ac 100755 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,480 +1,56 @@ +# HomeProz WordPress Theme -## TOOLING: BEADS (Issue Tracking) +Custom WordPress theme for HomeProz Real Estate (Albert Lea, MN). Dark/rust brand aesthetic with ACF-powered property listings. -Git-backed issue tracker for AI agents. Use `bd` for task management, NOT markdown TODOs or TodoWrite. +## Development Rules -**Git policy**: `.beads/` directory IS committed. `issues.jsonl` is the source of truth (db rebuilds from it). Issue state travels with code. +1. **No emojis** - nowhere in code, commits, docs, or conversation +2. **Tailwind CSS + SCSS** - compiled via Vite +3. **jQuery** - for all JS functionality +4. **Co-locate files** - SCSS/JS live alongside PHP templates +5. **Page-scoped styles** - wrap in `.Page_Class_Name { }`, early return in JS +6. **Server-side render** - no client-side templating +7. **No custom animations** - keep it static and fast +8. **ASK before architectural decisions** -**Hooks installed**: SessionStart and PreCompact hooks auto-run `bd prime` to inject workflow context. - -### Essential Commands - -| Command | Purpose | -|---------|---------| -| `bd ready` | Show unblocked issues ready to work | -| `bd create "title"` | Create new issue | -| `bd show ` | View issue details | -| `bd update --status in_progress` | Claim/start work | -| `bd close ` | Complete issue | -| `bd sync` | Sync with git remote | -| `bd list --status open` | List open issues | -| `bd dep add ` | Add dependency | - -### Workflow - -1. `bd ready` ^f^r find available work -2. `bd update --status in_progress` ^f^r claim it -3. Work on the issue -4. Discover new work? ^f^r `bd create "title" --deps discovered-from:` -5. `bd close ` ^f^r mark complete -6. `bd sync` ^f^r push changes - -### Issue Types & Priorities - -**Types**: `bug`, `feature`, `task`, `epic`, `chore` -**Priorities**: `0` (critical) ^f^r `4` (backlog), default `2` - -**End of session**: Create issues for discovered work, `bd sync`, verify clean git state. - - - -# PROJECT: 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 - -### Communication & Output - -1. **No emojis** - Never use emojis in code, website output, commit messages, documentation, or conversation. This is a professional project. - -### 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. **Commit everything** - build artifacts (`dist/`, `node_modules/`), database dumps, and all generated files are committed. No `.gitignore` exclusions for build output. -3. After every development phase: - ```bash - mysqldump -u [user] -p [database] > db-snapshot-phase-X.sql - git add -A - git commit -m "Phase X: [description]" - ``` -4. 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 | - -## Tools Available - -### WP-CLI - -WP-CLI is installed at `/usr/local/bin/wp`. Use it for WordPress administration tasks: +## Build ```bash -# Theme management -wp theme list -wp theme activate homeproz - -# Plugin management -wp plugin install --activate -wp plugin list - -# Database operations -wp db export backup.sql -wp db import backup.sql - -# Cache and transients -wp cache flush -wp transient delete --all - -# User management -wp user list -wp user create username email@example.com --role=administrator - -# Options -wp option get siteurl -wp option update blogname "HomeProz Real Estate" - -# Rewrite rules -wp rewrite flush - -# Run with --allow-root since we're running as root -# All commands should use: wp --allow-root +cd wp-content/themes/homeproz +npm run build ``` -**Note:** Always use `--allow-root` flag when running as root user. +## Tools -### dev_commit.sh +- **WP-CLI**: `wp --allow-root ` +- **Dev commits**: `./dev_commit.sh "message"` (includes DB snapshot) -A helper script for development checkpoints. Located at `/var/www/html/dev_commit.sh`. +## Theme Options -```bash -# Usage -./dev_commit.sh "Step X.X: Description of what was done" - -# What it does: -# 1. Dumps database to db-snapshots/db-snapshot.sql (overwrites each time) -# 2. Runs git add -A -# 3. Commits with your message -``` - -**MANDATE:** Use `./dev_commit.sh` after completing each step in the implementation plan. This ensures we have a database snapshot with every code commit. - -Example: -```bash -./dev_commit.sh "Step 1.3: Configure theme.json with brand colors" -``` - ---- - -## 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 # All ACF field definitions -│ ├── custom-post-types.php # Property & Agent CPTs -│ ├── 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 -│ │ ├── property-gallery.php -│ │ ├── property-gallery.js -│ │ ├── property-gallery.scss -│ │ ├── property-agent.php # Agent card for property sidebar -│ │ └── single-property.scss -│ ├── agent/ -│ │ ├── single-agent.scss -│ │ └── archive-agent.scss -│ └── components/ -│ ├── hero-section.php -│ ├── hero-section.scss -│ ├── cta-section.php -│ ├── cta-section.scss -│ └── ... -├── patterns/ -├── front-page.php -├── page.php -├── page-about.php -├── page-contact.php # Supports ?property= prefill -├── archive.php -├── single.php -├── archive-property.php -├── single-property.php -├── archive-agent.php # Agent listing page -├── single-agent.php # Agent profile page -├── 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` | -| `archive-agent.php` | `Agents_Archive` | -| `single-agent.php` | `Single_Agent` | -| `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~~ → **Agent CPT** (implemented) -6. Testimonials: Static content vs Testimonial CPT? -7. Maps: Embed codes vs Google Maps API? -8. Form notifications: Which email address(es)? - ---- +Access via `homeproz_get_option('key')`: +- `phone`, `email`, `address`, `facebook`, `tiktok` ## Custom Post Types -### Property CPT (`property`) +### Property (`/properties/`) +- ACF: price, address, beds/baths/sqft, gallery, documents, listing_agent +- Taxonomies: `property_status` (Active/Pending/Sold), `property_type`, `property_location` +- Location dropdown only shows communities with active/pending properties -**URL Structure:** `/properties/` (archive), `/properties/{slug}/` (single) +### Agent (`/agents/`) +- ACF: phone, email, bio, gallery, social links, order, disabled toggle +- Disabled agents: 404 on profile, office contact on property cards -**ACF Fields:** -- **Basic Info:** `property_price`, `street_address`, `city`, `state`, `zip_code`, `mls_number` -- **Details:** `bedrooms`, `bathrooms`, `square_feet`, `lot_size`, `year_built`, `garage` -- **Content:** `short_description`, `property_features` (checkbox), `property_gallery` (gallery) -- **Documents:** `property_documents` (repeater with file + label) -- **External:** `external_listing_url` (URL to Zillow/MLS listing) -- **Agent:** `listing_agent` (post_object → Agent CPT) +## Key Helpers -**Taxonomies:** -- `property_status`: Active, Pending, Sold, Coming Soon -- `property_type`: Single Family, Townhouse, Condo, Land, Commercial, Multi-Family - -### Agent CPT (`agent`) - -**URL Structure:** `/agents/` (archive), `/agents/{slug}/` (single) - -**ACF Fields:** -- **Contact:** `agent_phone`, `agent_email`, `agent_website`, `agent_title`, `agent_license` -- **Bio:** `agent_short_bio` (textarea, max 300 chars) -- **Gallery:** `agent_gallery` (gallery for additional photos; featured image is primary headshot) -- **Social:** `agent_social_links` (repeater: platform select + URL) -- **Settings:** `agent_order` (number, default 10), `agent_disabled` (toggle) - -**Disabled Agent Behavior:** -- Does not appear on `/agents/` listing -- Profile page returns 404 -- On property listings: shows name/photo but uses office phone, no profile link, "Contact Us" button instead of email - ---- - -## Theme Options (ACF Options Page) - -Located at **Appearance → Theme Options** - -| Field | Key | Usage | -|-------|-----|-------| -| Phone | `theme_phone` | Office phone number (used via `homeproz_get_option('phone')`) | -| Email | `theme_email` | Office email | -| Address | `theme_address` | Office address | -| Facebook | `theme_facebook` | Facebook page URL | -| TikTok | `theme_tiktok` | TikTok profile URL | - -Access in templates: ```php -$phone = homeproz_get_option('phone'); -$email = homeproz_get_option('email'); +// Get locations with active/pending properties only +$locations = homeproz_get_active_locations(); + +// Contact page with property inquiry prefill +$url = add_query_arg('property', urlencode($title), home_url('/contact/')); ``` ---- +## Page Classes -## Contact Page Property Inquiry - -The contact page supports pre-filling the message textarea with a property inquiry. - -**URL Format:** `/contact/?property=Property+Name+Here` - -**Behavior:** -- Extracts `property` GET parameter -- Pre-fills message with: "I would like to get more information on property: {Property Name}" -- Works with fallback form and Contact Form 7 (via JavaScript) - -**Usage in templates:** -```php -$contact_url = add_query_arg('property', urlencode($property_title), home_url('/contact/')); -``` - ---- - -## 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) -- Agent listing page shows agents ordered by `agent_order` field, then alphabetically -- Sold properties remain visible (social proof) -- MLS numbers are display-only (no API integration) -- Properties imported from homeprozrealestate.com with external listing URLs to Zillow +`Home_Page`, `Properties_Archive`, `Single_Property`, `About_Page`, `Contact_Page`, `Blog_Archive`, `Single_Post`, `Agents_Archive`, `Single_Agent`, `Search_Page`, `Error_404`