# Hillcrest Living Website Development Guidelines

## Related Documents
- Brand/UI guide: [BRAND_STYLE_GUIDE.md](BRAND_STYLE_GUIDE.md)
- Engineering runbook: [ARCHITECTURE.md](ARCHITECTURE.md)

## Project Identity
- **Business Name:** HILLCREST LIVING LTD
- **Primary Domain:** `hillcrestlivingltd.co.uk`
- **Project Type:** CMS-driven marketing website + admin panel
- **Target Users:** families, referrers, older adults (65+), internal admin/editors

## Brand Direction
- Visual direction:
  - **Structure:** Lifeways-style content flow
  - **Design feel:** Active Care clean professional spacing/hierarchy
  - **Tone:** Home Instead warm, reassuring, family-centered language
- Logo asset:
  - `assets/c__dev-proj_hillcrest-web_hillcrest-living-logo.jpg`

## Suggested Color System (From Logo)
Use these as design tokens in Tailwind config and component library.

- `brand.navy`: `#3F4A5C` (primary headings/nav text)
- `brand.gold`: `#B99147` (accent lines, icons, CTA highlights)
- `brand.charcoal`: `#2F3744` (body emphasis, footer backgrounds)
- `brand.mist`: `#F5F6F8` (section backgrounds)
- `brand.white`: `#FFFFFF` (base canvas)
- `brand.textSoft`: `#6B7280` (secondary paragraph text)

### Recommended Usage
- Primary CTA: gold background + white text (`brand.gold` / `brand.white`)
- Secondary CTA: white background + navy border/text
- Heading text: navy
- Body text: charcoal and soft gray
- Dividers/icons/decorative strokes: gold

## Typography
- Display font: `Plus Jakarta Sans` or `DM Sans`
- Body font: `Inter`
- Keep clear hierarchy:
  - H1: strong, concise, trust-building
  - H2: section anchors
  - Body: short readable paragraphs for older audiences and families

## Canonical Stack
- Laravel 11 (PHP 8.3)
- Filament v3 (admin CMS)
- Blade + Tailwind CSS v3
- Alpine.js (light interactions)
- AOS (scroll animations)
- MySQL 8
- cPanel / Apache deployment

## Architecture Principles
- One Laravel codebase:
  - Public website (front-facing)
  - Admin panel (`/admin`) for content management
- Avoid SPA complexity for v1; prioritize SEO and maintainability.
- Keep all page content editable via CMS modules (except structural layout and base styling).
- Content on every public website page must be updateable from the admin panel, quickly and without developer intervention.
- Every newly introduced public website section or content block must be CMS-driven from the admin portal.
- Do not hardcode public-facing copy that editors are expected to update; expose it through CMS-managed fields.

## Implementation Delivery Approach (Mandatory)
- Build frontend and admin CMS **in parallel**, not as separate project phases.
- Deliver features in **vertical slices**: each slice includes DB model/fields, Filament resource/forms, public Blade rendering, validation/authorization, and QA.
- Do not mark a feature complete unless an editor can update content in admin and see the change reflected correctly on the public page.
- Frontend-only implementation is allowed only for short-lived visual prototypes; production implementation must immediately move to CMS-backed slices.
- Treat "website + admin editability + publish flow" as one deliverable for every page/module.

### Vertical Slice Definition of Done
For each page section or module (for example Home Hero, Services Grid, News List):
1. Add or update schema and model relationships.
2. Add Filament forms/tables and publish-state controls.
3. Bind frontend components/pages to persisted CMS data.
4. Apply validation, authorization, and security controls.
5. Validate editor workflow end-to-end (create/edit/publish -> frontend reflects changes).
6. Confirm mobile/desktop rendering and SEO/meta coverage where applicable.

## Engineering Quality Bar (Mandatory)
- All implementation must be **senior-level, production-grade** code quality.
- Code should be:
  - secure by default
  - modular and maintainable
  - well-validated and failure-aware
  - readable and consistent with Laravel conventions
- No quick hacks in core flows (auth, forms, uploads, settings, SEO, jobs, referrals).
- For every major feature:
  - use clear validation rules
  - include authorization checks
  - avoid duplicated logic (use service classes/helpers where appropriate)
  - keep controllers slim and business logic testable

## Public Information Architecture
- `/` Home
- `/about`
- `/services`
- `/who-we-support`
- `/referral`
- `/testimonials`
- `/news`
- `/news/{slug}`
- `/careers`
- `/downloads`
- `/contact`
- `/privacy`
- Custom `404`

## CMS Modules (Filament)
- Pages Manager
  - Provide per-page editable fields/sections for each public route.
  - Use Filament rich editor for long-form and formatted page content.
- Media Library
- Services Manager
- Team Manager
- Testimonials Manager
- News Manager
- Jobs Manager
- Job Applications Inbox
- Referral Submissions
- Contact Submissions
- Downloads Manager
- SEO Manager
- Settings (global contact/map/social/footer/cookie text)
- Navigation/Menu Manager (create, edit, reorder, and remove menu items/labels)
- User Management (Super Admin only)

## Role Model
- **Super Admin:** full system access, user management, settings
- **Editor:** page/content/media/forms management without user admin
- **Admin Auth Requirement:** secure authentication must be fully implemented before go-live, including role enforcement, login throttling, and secure session handling.

## Key Functional Standards
- Content management:
  - New website sections and additional content must be modeled and managed through CMS resources.
  - Content updates for each page must be easy for non-technical editors without code changes.
  - Prefer Filament rich editor where formatted text editing is required.
- Navigation menus:
  - Menu text must be editable from admin.
  - Admin users must be able to create, reorder, and remove menu entries.
  - Navigation updates must publish seamlessly without deployment.
- Forms:
  - CSRF + honeypot + server-side validation
  - Inline error display
  - Success message on-page
  - Save submissions to DB
  - Email notification to admin inbox
- Careers:
  - Dynamic jobs from DB
  - Open/closed state
  - Closing-date-based visibility
  - CV upload validation
- SEO:
  - Per-page meta + OG
  - XML sitemap
  - robots.txt
  - JSON-LD structured data (Organization / LocalBusiness)
- Contact page:
  - Embedded map is required
  - Map embed URL must be editable in admin settings
  - Contact details and social links must update from the same settings module
- Security:
  - HTTPS redirect
  - Upload MIME/size restrictions
  - Rate limiting on public forms
  - Secure admin auth at `/admin` with role-based authorization
  - Login attempt throttling and lockout/backoff
  - Strong password policy and protected sessions

## Environment and Local Setup
- Recommended local tools (Windows): **Laravel Herd** (first choice), **Laragon** (second)
- Minimum versions:
  - PHP 8.3+
  - Composer 2.x
  - Node.js LTS
  - MySQL 8+
- Development commands:
  - `php artisan serve`
  - `npm install`
  - `npm run dev`
- Production build:
  - `npm run build`
  - Laravel cache optimization commands on deploy

## Developer Guidance Mode (Non-PHP Friendly)
- For every implementation phase, provide:
  - exact commands to run
  - expected output/what success looks like
  - common error fixes if command fails
- Prefer copy-paste-ready command blocks.
- Assume the operator is new to Laravel unless stated otherwise.

## File and Component Conventions
- Keep reusable sections under Blade components (hero, services-grid, CTA-band, testimonial-slider).
- Keep design tokens centralized in Tailwind config.
- Keep page templates thin; move repeated fragments to components/partials.
- Keep admin resources grouped by business domain.

## Content Guidelines
- Write for reassurance, clarity, and dignity.
- Avoid heavy clinical language.
- Reiterate independence + structured support positioning.
- Keep paragraphs short and scannable.
- Ensure all important CTAs are visible without excessive scrolling.

## Definition of Done (Per Feature)
- Implemented in code
- CMS editable where required
- Every new public section/content block is CMS-backed (model/resource/fields)
- Editor flow is validated (edit/update/publish) for affected page content
- Navigation changes are manageable from admin and reflected on frontend
- Mobile/tablet/desktop validated
- SEO/meta fields present
- Accessible interactions (keyboard/tab focus and contrast)
- No critical lints/errors
- Included in handover notes if behavior is non-obvious

## Change Log (Living Document)
Update this section as requirements evolve.

- `2026-05-03`: Initial guideline created with domain, logo-driven color scheme, architecture baseline, and CMS scope.
- `2026-05-03`: Added Contact page requirement for admin-editable embedded map, contact details, and social links.
- `2026-05-03`: Added explicit secure admin authentication requirement for `/admin` with RBAC and login protection controls.
- `2026-05-03`: Added mandatory senior-level production-grade coding standard and non-PHP-friendly command guidance requirement.
- `2026-05-05`: Enforced CMS-first governance for all new public sections/content, required Filament rich editor for formatted content, and mandated admin-managed navigation/menu CRUD.
- `2026-05-05`: Added mandatory vertical-slice implementation approach: build public pages and admin CMS together for each feature, with editor flow verification as completion criteria.

## Update Process
When new requirements arrive:
1. Add requirement to this file under the relevant section.
2. Record date and summary in **Change Log**.
3. Mark affected modules/pages before implementation starts.
4. Confirm whether requirement is v1, v1.1, or backlog.