Build Specification — Shared Page Structure

Events Page — Build Specification

Status: DRAFT — Review before launching build agents Date: 2026-03-16

1. Page Purpose (One Sentence)

Help users find and register for AlMaghrib events near them in under 30 seconds.

2. Shared Page Structure (All 3 Directions)

Every direction implements these sections in this order:

Section 1: Hero

• Headline + subheadline
• Optional: background image or illustration
• Quick context: what AlMaghrib onsite events are

Section 2: Filter Bar (sticky on scroll)

• Row 1: Continent tabs — "All", "North America", "Europe" (built from API data)
• Row 2: City pills — update when continent changes
• Active state: purple fill (#811CE5) / Inactive: white with border
• GeoIP note: default to nearest city (but we'll use stored sort order for static mockup)

Section 3: Event Cards Grid

• Responsive: 3 columns desktop, 2 tablet, 1 mobile
• Each card shows summary view by default
• Click/tap to expand for full details
• Cards filter live when continent/city changes

Section 4: Expanded Event Detail (inline or modal)

• Full description, pricing, venue, schedule
• Registration count + attendee avatars
• "Register Now" CTA → links to event's site_url
• Instructor bio section

Section 5: Footer

• Exact replica of almaghrib.org footer (dark geometric pattern, 4 columns)
• Must match design system spec precisely

3. Content Specification

Hero Copy Options (for each direction to choose from)

• Option A (warm): "Find Your Next AlMaghrib Experience" / "Weekend seminars and evening events in 19 cities across North America and Europe"
• Option B (direct): "Upcoming Events Near You" / "Browse all AlMaghrib seminars by city — find what's happening in your community"
• Option C (aspirational): "Your Journey of Knowledge Starts Here" / "In-person Islamic education from world-class scholars, coming to a city near you"

Filter Labels

• Continent tabs: Use continent names directly ("All", "North America", "Europe")
• City pills: Use city names directly ("Ottawa", "Boston", "London", etc.)
• Event type tabs (if shown): "All Events", "Weekend Seminars", "Ilm Nights"

Card Summary Fields (priority order)

1. Course image (image_bg for wide cards, image for portrait cards)
2. Event title (heading)
3. Subtitle (sub_heading)
4. Instructor name + avatar
5. City + country
6. Date (formatted: "Sat, April 18, 2026")
7. Event type badge ("Weekend Seminar" / "Ilm Night")
8. Credits badge (if credits is not null)
9. Price (current pricing tier with currency symbol)

Expanded View Fields (additional)

1. Full description (HTML stripped to text)
2. Pricing breakdown (standard + early bird if available)
3. Schedule with local times (from schedule_tz)
4. Registration count ("46 students registered")
5. Attendee avatars (first 5)
6. Venue (if event_schedule_venue is not null)
7. "Register Now" button → site_url (or slug-based URL as fallback)

Empty States

• No events in selected city: "No upcoming events in {city} right now. Check back soon or explore events in other cities nearby."
• No events in selected continent: "No upcoming events in {continent}. Browse all events to see what's coming up."

CTA Labels

• Card expand: "View Details" or expand icon
• Registration: "Register Now" (gold button)
• Share: "Share Event" with share icon (WhatsApp, copy link)

4. Data Integration

Static Mockup Approach

• Embed the contents of data/data-mockup-events.json as a const EVENTS_DATA = [...] in a <script> tag
• All filtering/sorting done client-side with vanilla JS
• Easy to swap to fetch('https://api2.almaghrib.org/v1/wp/mega-menu-events') later

Data Transformations Needed in JS

• Parse date_start → format as "Sat, April 18, 2026"
• Strip HTML from description_clean
• Build continent → city index from event data
• Sort: by date (default), grouped by continent when "All" is selected

5. Design System Constraints (Non-Negotiable)

These MUST be followed across all 3 directions:

Typography

• Headings: Montserrat (700-900 weight)
• UI / Body: Readex Pro (400-600 weight)
• Body fallback: Lato, Open Sans

Colors (from design-system-audit.md)

• Primary purple: #811CE5
• Purple dark text: #201B42
• Gold CTA: #FDCA17 (Learn More, Register)
• Active filter pill: #811CE5 (white text)
• Inactive filter pill: #F5F4F7 or white with border
• Body text: #676767
• Muted text: #9391A8
• Card border: 1.11px solid #D9DBE1

Components

• Cards: border-radius 16px (desktop), 15px (mobile)
• Filter pills: border-radius 40px
• CTA buttons: border-radius 8px, gold background
• Box shadows: 0px 4px 10px rgba(0,0,0,0.08)

Footer

• Replicate exactly from design-system-audit.md Section 7
• Dark geometric pattern background
• 4-column layout: Logo | About Us | Contact Us | Join Us

Mobile

• Breakpoint at 768px
• Cards stack to single column
• Filter pills horizontal scroll
• Sticky filter bar at top

6. Technical Requirements

• Single HTML file per direction (Tailwind CDN + Google Fonts)
• Vanilla JavaScript only (no React, no build step)
• IntersectionObserver for scroll animations
• Event data embedded as JSON in script tag
• Lazy loading on images
• All images from CDN URLs (public.assets.almaghrib.org)
• Target: <50KB HTML + CSS (before CDN loads)

7. Quality Bar

• Must look like a professional production page, not a mockup
• Must pass visual comparison with existing almaghrib.org pages
• Mobile must feel native, not "shrunk desktop"
• Every interactive element needs hover/active/focus states
• Filter interactions must feel instant (<100ms)
• Card expand/collapse must animate smoothly
• No placeholder text — all real data from API