# Northfield Theatre - Demo Website Build Plan

## Project Overview

Build a fictional theatre website called "Northfield Theatre" as a portfolio demonstration piece. This will be used to showcase capability for theatre and venue tender bids (Victoria Theatre Halifax, future similar contracts).

The site should look and feel like a modern, professional UK theatre website inspired by the design language of the Barbican Centre (London), but with original branding. It must demonstrate every key feature that theatre clients typically request:

- Custom branded design with strong typography
- Dynamic event listings with filtering
- Custom shopping basket (simulating Spektrix API integration)
- Mobile-first responsive design
- WCAG 2.2 AA accessibility
- Fast performance (Lighthouse 90+)
- WordPress with Gutenberg block editor for content management

**This is a demo site, not a real client project.** It uses mock data because we don't have a real Spektrix account. The front-end logic, templates, and integration patterns are identical to what would be deployed against the real Spektrix API.

## Branding & Identity

**Site name:** Northfield Theatre
**Strapline:** "Where Yorkshire stages the world"
**Fictional location:** Northfield, West Yorkshire (made up)
**Capacity:** 1,200 seats (fictional)
**Type:** Receiving house presenting drama, comedy, music, dance

### Brand Colours

Inspired by Barbican's bold orange but distinct:

```
--color-primary: #1B4D3E;       /* Deep green - heritage/theatre velvet */
--color-accent: #E8A33D;        /* Warm gold - stage lighting */
--color-dark: #1A1A1A;          /* Near-black for body text */
--color-text: #333333;          /* Body text */
--color-text-muted: #666666;    /* Secondary text */
--color-bg: #FFFFFF;            /* Background */
--color-bg-soft: #FAF7F2;       /* Soft cream alt background */
--color-border: #E5E5E5;        /* Borders */
--color-success: #2D7A4F;       /* "Available" badges */
--color-warning: #D97706;       /* "Last few tickets" */
--color-danger: #B91C1C;        /* "Sold out" */
```

### Typography

Use free Google Fonts:

- **Headings:** "Fraunces" (serif, bold weights, theatrical feel) or "Playfair Display" as fallback
- **Body:** "Inter" (clean sans-serif, excellent readability)
- **H1 size:** 48-56px on desktop, 32-40px on mobile
- **Body size:** 17-18px for readability
- **Line height:** 1.6 for body, 1.2 for headings

## Tech Stack

| Component | Technology |
|---|---|
| CMS | WordPress (latest) |
| Theme base | Underscores (_s) starter theme - download from underscores.me |
| Editor | Gutenberg block editor (built-in) |
| Custom fields | ACF Free version (sufficient for demo - text, image, basic repeater) |
| Forms | Contact Form 7 (free) or Fluent Forms Lite (free) |
| SEO | Rank Math Free (better free tier than Yoast) or Yoast Free |
| Performance | LiteSpeed Cache or W3 Total Cache (both free) |
| Search | Default WordPress search or Relevanssi Free |
| Mock data source | Local JSON files in `/wp-content/themes/northfield-theatre/data/` |
| JavaScript | Vanilla JS (no jQuery dependency, no React) |
| CSS | Custom CSS using CSS custom properties (variables), no preprocessors needed |
| Security | Wordfence Free (same firewall, delayed threat updates) |
| Stock images | Unsplash, Pexels (free) |
| Fonts | Google Fonts (free, self-hosted for performance) |
| Deployment | Existing VPS (Hetzner) or any free WordPress host |

## File Structure

```
wp-content/themes/northfield-theatre/
├── style.css                    # Theme metadata + main styles
├── functions.php                # Theme setup, custom post types, scripts
├── header.php                   # Header with navigation and basket icon
├── footer.php                   # Footer with newsletter signup
├── front-page.php               # Homepage template
├── page.php                     # Default page template
├── page-whats-on.php            # What's On listing page
├── page-basket.php              # Custom basket page
├── page-checkout.php            # Checkout placeholder
├── page-visit.php               # Visit Us page
├── page-access.php              # Accessibility page
├── single-event.php             # Single event detail page
├── archive-event.php            # Event archive (fallback)
├── 404.php                      # Custom 404
├── searchform.php               # Search form
├── search.php                   # Search results
├── inc/
│   ├── custom-post-types.php   # Register Event post type
│   ├── theme-setup.php          # Theme supports, menus
│   ├── enqueue.php              # Scripts and styles
│   ├── spektrix-mock-api.php    # Mock API endpoints simulating Spektrix
│   ├── basket-handler.php       # Basket session management
│   └── helpers.php              # Utility functions
├── data/
│   ├── events.json              # Mock event data (15-20 events)
│   ├── instances.json           # Mock performance instances
│   └── ticket-types.json        # Mock ticket types and prices
├── blocks/
│   ├── hero-gallery/            # Custom Gutenberg block - rolling hero
│   ├── now-and-next/            # Custom block - this week highlights
│   ├── event-grid/              # Custom block - event cards
│   ├── alert-banner/            # Custom block - admin-controlled banner
│   └── newsletter-signup/       # Custom block - email signup
├── assets/
│   ├── css/
│   │   ├── main.css             # Core styles
│   │   ├── header.css
│   │   ├── footer.css
│   │   ├── homepage.css
│   │   ├── whats-on.css
│   │   ├── single-event.css
│   │   ├── basket.css
│   │   └── responsive.css
│   ├── js/
│   │   ├── main.js              # Core interactions, mobile menu
│   │   ├── basket.js            # Basket state management
│   │   ├── basket-summary.js    # Header basket icon updates
│   │   ├── whats-on-filter.js   # Event filtering and calendar
│   │   └── spektrix-api.js      # API client (calls mock endpoints)
│   ├── images/
│   │   └── ... (placeholder images)
│   └── fonts/
│       └── ... (if self-hosting fonts)
└── template-parts/
    ├── content-event-card.php   # Reusable event card
    ├── content-hero.php         # Hero section
    ├── header-basket.php        # Header basket icon
    ├── header-navigation.php    # Main navigation
    └── footer-newsletter.php    # Footer signup
```

## Mock Data Structure

Mock JSON files should mirror the real Spektrix API v3 response structure so the code works identically when swapped to real API.

### data/events.json (15-20 events)

```json
[
  {
    "id": "evt_001",
    "name": "Hamlet",
    "slug": "hamlet",
    "summary": "Shakespeare's greatest tragedy returns to Northfield",
    "description": "Full event description with multiple paragraphs...",
    "image": "hamlet-hero.jpg",
    "thumbnail": "hamlet-thumb.jpg",
    "category": "Drama",
    "tags": ["Shakespeare", "Classic", "Adult themes"],
    "ageGuidance": "12+",
    "runTime": 180,
    "warnings": ["Strobe lighting", "Stage blood"],
    "venue": "Main Auditorium",
    "instances": ["inst_001", "inst_002", "inst_003"],
    "minPrice": 15.00,
    "maxPrice": 45.00,
    "currency": "GBP",
    "saleStatus": "OnSale",
    "availability": "Available",
    "featured": true
  }
]
```

### data/instances.json (specific performance dates)

```json
[
  {
    "id": "inst_001",
    "eventId": "evt_001",
    "datetime": "2026-05-15T19:30:00",
    "venue": "Main Auditorium",
    "availability": "Available",
    "availableSeats": 234,
    "totalSeats": 1200,
    "saleStatus": "OnSale"
  }
]
```

### data/ticket-types.json

```json
[
  {
    "id": "tt_adult",
    "name": "Adult",
    "price": 35.00
  },
  {
    "id": "tt_concession",
    "name": "Concession",
    "price": 28.00
  },
  {
    "id": "tt_child",
    "name": "Under 18",
    "price": 18.00
  }
]
```

## Pages to Build

### 1. Homepage (front-page.php)

Mirror Barbican's homepage structure but with original content:

- **Hero section:** Full-width black background with large white serif heading "Welcome to Northfield Theatre". Single CTA button "Explore the new season". Background can rotate through 6 images managed in CMS.
- **This Week:** Tab navigation ("On this week", "Free things to do", "Plan your visit"). Default tab shows 3-4 event cards with image, title, date, "More info" button.
- **Now Booking:** Grid of 6 events, dynamically pulled from mock event data
- **About Northfield:** Brief intro with image, "Read our story" link
- **Newsletter signup:** Cream background section with email input

### 2. What's On (page-whats-on.php)

Mirror Barbican's What's On page:

- **Page heading:** "What's On" with subtitle "All events"
- **Tab nav:** "Events" / "Seasons"
- **Two-column layout (desktop):**
  - Main column: Event cards grouped by date with day header (e.g., "Thu 16 Apr"). Each card: thumbnail image, category tag (coloured), title, time, brief description, "More info" button. Star icon for favouriting.
  - Right sidebar: View toggle ("Full view" / "List view"), date filter checkboxes ("Today", "Next 7 days", "Next 30 days"), date range pickers ("From Anytime / To Anytime"), interactive calendar for current month
- **Mobile:** Sidebar collapses to a "Filter" button at top, opens as overlay
- **Filtering:** JavaScript-based, no page reload. Filter by date range, category, venue

### 3. Single Event (single-event.php)

- **Hero banner:** Large event image, gradient overlay, event title in large white text
- **Sticky "BOOK NOW" button:** Stays visible as user scrolls
- **Tab navigation:** Details / Visit Info / Access / Cast & Creatives / Reviews / Gallery
- **Performance dates list:** Each instance with date, time, availability badge ("Available", "Last Few", "Sold Out"), individual BOOK button
- **Cross-sell:** "You might also like" section at bottom with 3 related events
- **Add to Basket flow:** Click BOOK opens a modal with ticket type selector (Adult/Concession/Child quantity), running total, "Add to Basket" button

### 4. Basket (page-basket.php)

The hero feature - custom-built basket using JavaScript:

- **Page heading:** "Your Basket"
- **Two-column layout:**
  - Main column: List of items in basket. Each item: thumbnail, event name, date/time, ticket type, quantity controls (+/-), price per ticket, line total, remove button (trash icon)
  - Right sidebar: Order summary box (sticky on scroll). Subtotal, optional booking fee line, donation prompt ("Add a £2 donation?"), grand total, large "Proceed to Checkout" button
- **Empty state:** "Your basket is empty" with link to What's On
- **Update flow:** Quantity changes update the running total in real-time via JavaScript
- **Persistence:** Basket state stored in browser localStorage (simulating Spektrix session cookie)
- **Cross-sell:** "Add to your visit" section showing 3 events you don't have in basket yet

### 5. Checkout Placeholder (page-checkout.php)

Since we can't process real payments:

- Bordered box on the page with the message: "Spektrix Express Checkout iframe would load here in production. The basket session would be passed to Spektrix and customers would complete payment securely on Spektrix-hosted pages."
- Below it: List of basket items being "checked out"
- Disabled "Complete Payment" button
- Note explaining this is a demo

### 6. Visit Us (page-visit.php)

Static content page demonstrating Gutenberg block editing:

- Address, opening times, getting here (with mock map)
- Parking information
- Pre-show dining
- FAQs accordion

### 7. Accessibility (page-access.php)

Take inspiration from Scunthorpe Theatres approach (mentioned in VT Halifax brief):

- Statement of commitment to accessibility
- Information by need: wheelchair users, hearing aid users, visual impairment, sensory needs
- Captioned/signed/relaxed performance dates
- Downloadable access guide (placeholder PDF)
- Web accessibility statement complying with Public Sector Bodies Accessibility Regulations 2018

### 8. 404 Page

- Custom 404 with theatre-themed humour
- Useful links: What's On, Visit Us, Contact

## Header & Footer (consistent across all pages)

### Header

- **Top bar:** Solid colour band (dark green primary). Logo "Northfield Theatre" in white serif. Search box. Basket icon with item count and total ("3 items £83.00"). Login button.
- **Nav bar:** Below top bar. Items: What's On / Your Visit / Take Part / Our Story / Hire / Read & Watch / Shop. Each with optional dropdown menu.
- **Mobile:** Logo and hamburger menu. Tap hamburger reveals fullscreen overlay nav.
- **Alert banner:** Optional dismissible banner above header, controlled from CMS, used for show cancellations or important messages.

### Footer

- **Newsletter section:** Cream background. "Subscribe to our newsletters" heading, bullet list of benefits, "Subscribe" button
- **Footer links:** Multi-column layout - About, Visit, Support Us, Contact, Legal (Privacy, T&Cs, Accessibility statement)
- **Bottom bar:** Copyright, social icons (Facebook, Instagram, Twitter, YouTube), funder logos placeholder

## Custom Post Type: Event

Register a custom post type for events with these fields (using ACF Free or native WordPress meta boxes):

- Title (post title)
- Summary (text)
- Description (WYSIWYG - native WP editor)
- Featured image (native WP)
- Gallery (multiple images - native WP gallery block)
- Category (taxonomy: Drama, Comedy, Music, Dance, Family, Other)
- Tags (native WP tags)
- Age guidance (text field via ACF Free)
- Running time (number field via ACF Free)
- Content warnings (text field with comma separation - ACF Free does not include unlimited repeaters)
- Venue (select field via ACF Free: Main Auditorium, Studio, Foyer)
- Performance dates (use a custom post type "Instance" instead of repeater, since ACF Free repeater is limited)
- Min price / Max price (number fields via ACF Free)
- Featured (true/false field via ACF Free)

**Note on ACF Free limitations:** ACF Free supports text, image, file, select, true/false, number, and basic relational fields. It does NOT include flexible content, unlimited repeaters, or gallery field. Work around this by using:
- Separate custom post types instead of nested repeaters (e.g., "Instance" post type linked to "Event" via relationship field)
- Native WordPress gallery blocks instead of ACF gallery field
- Comma-separated text fields where simple lists are needed

Events should be auto-imported from the JSON mock data on theme activation, or via a WP-CLI command for repeatability.

## Spektrix API Mock Layer

Build a mock API layer that exposes the same endpoints Spektrix would, but reads from local JSON files. This means the front-end JavaScript code is identical to what would run against real Spektrix - only the backend data source differs.

Mock endpoints to implement (in functions.php using WordPress REST API):

```
GET  /wp-json/spektrix-mock/v1/events
GET  /wp-json/spektrix-mock/v1/events/{id}
GET  /wp-json/spektrix-mock/v1/instances?event_id={id}
GET  /wp-json/spektrix-mock/v1/basket
POST /wp-json/spektrix-mock/v1/basket/items
PATCH /wp-json/spektrix-mock/v1/basket/items/{id}
DELETE /wp-json/spektrix-mock/v1/basket/items/{id}
```

Basket state stored in PHP session or browser localStorage.

## Key Features Checklist

Each of these must work in the final demo:

- [ ] Custom branded design (not a template)
- [ ] Mobile-first responsive (test 320px to 1920px)
- [ ] Gutenberg block editor for all pages
- [ ] At least 3 custom Gutenberg blocks (hero gallery, event grid, alert banner)
- [ ] What's On filtering (date, category, venue)
- [ ] Calendar widget that filters events
- [ ] "Today / Next 7 days / Next 30 days" quick filters
- [ ] Single event page with sticky BOOK NOW button
- [ ] Tab navigation on event pages
- [ ] Cross-sell suggestions on event pages
- [ ] Add to Basket flow with ticket type and quantity
- [ ] Custom basket page with quantity controls and live totals
- [ ] Header basket icon with live count and total
- [ ] Basket persistence via localStorage
- [ ] Donation prompt in basket
- [ ] Newsletter signup in footer
- [ ] Site search
- [ ] Alert banner controllable from CMS
- [ ] WCAG 2.2 AA compliant (test with axe DevTools, WAVE)
- [ ] Keyboard navigation works for all interactive elements
- [ ] Visible focus indicators
- [ ] Semantic HTML5 (proper headings, landmarks, ARIA where needed)
- [ ] Skip to main content link
- [ ] Accessibility statement page
- [ ] Lighthouse Performance score 90+
- [ ] Lighthouse Accessibility score 95+
- [ ] Lighthouse SEO score 95+
- [ ] Lighthouse Best Practices score 95+
- [ ] GA4 placeholder code in header
- [ ] Cookie consent banner (GDPR compliant)
- [ ] 404 page

## Build Phases

Recommend Claude Code works through these in order:

### Phase 1: Foundation (3-4 hours)
1. Confirm WordPress is installed and accessible
2. Create the theme folder `northfield-theatre`
3. Set up `style.css` (theme metadata) and `functions.php`
4. Build core templates: header.php, footer.php, index.php
5. Set up brand tokens (CSS variables) in main.css
6. Implement responsive breakpoints
7. Build navigation (desktop and mobile hamburger)

### Phase 2: Mock Data & API (2-3 hours)
1. Create JSON files in `/data/` with 15-20 mock events
2. Build mock API endpoints in `/inc/spektrix-mock-api.php`
3. Register Event custom post type
4. Build helper functions to fetch events from JSON

### Phase 3: Homepage (2-3 hours)
1. Build front-page.php template
2. Create Hero Gallery custom Gutenberg block
3. Create Now and Next section
4. Create Now Booking event grid
5. Style everything to match Barbican-inspired design

### Phase 4: What's On (3-4 hours)
1. Build page-whats-on.php
2. Create event card template part
3. Build sidebar with filters
4. Implement JavaScript filtering (no page reload)
5. Build calendar widget
6. Test mobile responsive

### Phase 5: Single Event (2-3 hours)
1. Build single-event.php
2. Sticky BOOK NOW button
3. Tab navigation
4. Performance instances list with availability badges
5. Cross-sell suggestions
6. Add to Basket modal

### Phase 6: Basket (3-4 hours)
1. Build page-basket.php
2. Build basket.js for state management
3. Build basket-summary.js for header icon
4. localStorage persistence
5. Quantity controls with live total updates
6. Empty state
7. Donation prompt
8. Cross-sell

### Phase 7: Static Pages (2 hours)
1. Visit Us page
2. Accessibility page (using GDS template)
3. About / Our Story page
4. Contact page with form
5. 404 page

### Phase 8: Polish (3-4 hours)
1. Run axe DevTools - fix all accessibility issues
2. Run WAVE - fix any remaining issues
3. Manual keyboard testing
4. Screen reader testing (VoiceOver or NVDA)
5. Lighthouse audit - optimise to 90+ across all metrics
6. Image optimisation (WebP conversion, lazy loading)
7. CSS/JS minification
8. Test on real mobile devices (or browser device emulation)

### Phase 9: Content Population (2-3 hours)
1. Add real-feeling content to all pages
2. Source 15-20 free stage/performance images from Unsplash
3. Write believable event descriptions
4. Add fictional venue address (Northfield, West Yorkshire)
5. Configure menus
6. Configure widgets

### Phase 10: Deployment (1-2 hours)
1. Export theme files
2. Document setup steps in a README
3. (User handles): Buy domain, set up hosting, deploy

## Important Constraints

1. **No real Spektrix integration** - all event data and basket logic uses mock JSON
2. **No real payment processing** - checkout is a styled placeholder
3. **Free tools only** - no premium plugin licences (use ACF Free, Contact Form 7, Wordfence Free, Rank Math Free)
4. **No external dependencies beyond Google Fonts** - keep the theme self-contained
5. **No JavaScript frameworks** - vanilla JS only, no React/Vue/jQuery
6. **No CSS preprocessors** - vanilla CSS with custom properties
7. **Must be deployable to standard WordPress hosting** - no Node.js requirements at runtime
8. **Total external cost: £0-10** (only domain if wanted; can deploy as subdomain on existing hosting)

## Quality Standards

- All HTML must be semantic (proper use of `<article>`, `<section>`, `<nav>`, `<aside>`, `<header>`, `<footer>`, `<main>`)
- All interactive elements keyboard-accessible
- All images have meaningful alt text
- Colour contrast ratios meet WCAG AA (4.5:1 normal text, 3:1 large text)
- Focus states clearly visible
- No console errors or warnings
- Mobile menu works on touch devices
- Page load under 2.5s on 3G simulation
- No layout shift (CLS under 0.1)

## Subtle Animations and Polish

To make the site feel premium without being distracting, add these subtle interactions throughout:

- **Fade-in on scroll:** Event cards, hero sections, and content blocks fade in and slide up slightly as they enter the viewport. Use Intersection Observer API in vanilla JavaScript - no libraries needed
- **Hover lifts on cards:** Event cards and clickable cards lift slightly (2-4px translate Y) with a subtle shadow on hover. Use CSS `transform: translateY(-2px)` with a `transition: transform 0.2s ease, box-shadow 0.2s ease`
- **Smooth button transitions:** Background colour, text colour, and border transitions of 200ms on hover/focus
- **Image hover zoom:** Event card images scale slightly (1.03x) on hover with `overflow: hidden` on the container so the image stays within bounds
- **Smooth scroll:** Use `scroll-behavior: smooth` for anchor links
- **Loading states:** Skeleton screens for the basket and event lists while data loads (avoids layout shift)
- **Basket icon pulse:** When an item is added to the basket, the header basket icon briefly pulses or shows a count animation
- **Page transitions:** Subtle fade between page loads (optional, only if it doesn't hurt performance)
- **Reduced motion respect:** Wrap all animations in `@media (prefers-reduced-motion: no-preference)` so users who prefer reduced motion get a static experience

All animations should respect the user's motion preferences and never block interaction. Performance budget: animations must not drop frame rate below 60fps on a mid-range mobile device.

## Final Deliverable

A working WordPress theme that, when activated on a fresh WordPress install with the mock data imported, produces a fully functional theatre website demo. The site should be ready to deploy to any standard WordPress hosting provider (Cloudways, Kinsta, WP Engine, or a generic VPS).

The README should explain:
- How to install
- How to import the mock data
- How to customise brand colours via CSS variables
- How to swap the mock API for real Spektrix API (which functions to modify)

## Reference Sites for Design Inspiration

When making design decisions, reference these (mentioned in actual theatre client briefs):
- Barbican Centre: https://www.barbican.org.uk - homepage layout, basket design, brand boldness
- Harrogate Theatre: https://www.harrogatetheatre.co.uk - What's On page
- Hampstead Theatre: https://www.hampsteadtheatre.com - homepage, show pages, seating plan
- National Theatre: https://www.nationaltheatre.org.uk - clean homepage hierarchy
- Scunthorpe Theatres: https://www.scunthorpetheatres.co.uk/your-visit/access - accessibility approach

Take inspiration but do not copy. The Northfield Theatre brand identity is original.