VapeHub Homepage — Developer Spec

What the homepage prototype demonstrates and what production must supply. It looks presentational, but it carries three real systems — the Find Your Vape finder, the hero carousel, and the mega-menu (the mega-menu has its own spec). Everything renders from data arrays at the top of the script, so wiring live data means replacing arrays, not markup.

Source of truth: vapehub-homepage-src/handover/vapehub-homepage.html (vanilla HTML/CSS/JS, all ids/classes vh-* namespaced).

1. Find Your Vape finder — the rules engine

The prototype's FINDER_RULES(answers) is a stub returning hard-coded in-stock picks. It must be replaced with the real catalogue query.

• Three questions, one card, no page change: pref (value/compact/refill/simple) → strength (20mg/10mg/low/0mg) → flavour (fruit/menthol/dessert/any). Answers collected client-side; the panel only collects and hands off.
• On completion, POST the answers to the catalogue filter and rank:

device_type ∈ target AND strength available AND in_stock AND !discontinued, ranked by popularity → 1 hero pick + 3 alternatives + a "see all matches" link to the pre-filtered collection.

• Fallback ladder (also in that function): drop flavour → widen strength → drop format → category bestsellers. Never return an empty result.
• Progress announced as "Step n of 3" (role="progressbar" + aria-label). The card height is reserved so answering causes no layout shift.

2. Hero carousel — the banner builder

Slide 0 is the finder (the approved hero, unchanged). Slides 1+ are product promo banners driven by a data model a merchandiser edits in a backend builder — the prototype hardcodes a BANNERS array standing in for it.

Per banner: enabled · order · background (colour/gradient) · theme (light/dark → text treatment) · accentColour · brandLogo · productImage (transparent PNG) · kicker · headline · subtext · buttonLabel · buttonUrl (real 200 product/collection page). Carousel: autoplaySeconds (6) · pauseOnHover · loop. The finder is a special reusable slide type.

Behaviour contract (built — preserve): ~6s autoplay; pauses on hover/focus and while the user is mid-finder; prefers-reduced-motion disables autoplay; dots + prev/next + pause, keyboard-operable; grid-stacked so zero CLS. Product banners are real HTML (<h2> + real <a href>), never text baked into an image; responsive (desktop 2-col, mobile stacked).

Banner background art: the prototype uses the light "Studio Pearl" treatment because the only product images available are white-bg/watermarked. With clean transparent PNGs, flip theme:'dark' + the Obsidian background per the banner brief — one data field per banner.

3. Product rails, categories, facets, deals

All data-driven — replace the arrays with live data, no markup change: RAILS (4 product rails) · CATEGORIES (self-qualifying tiles) · FACETS (puffs/strength/flavour → pre-filtered collections) · DEALS (multibuy offers) · BRANDS (top-brands wall) · REVIEWS · GUIDES · FAQS · USPS. Rail cards carry image + name + price + puffs/spec + rating + review count + multibuy hook — wire each to its real PDP (href currently /).

4. Trust / USP bar + countdown

• USP bar: free next-day over £30 · order-by-4pm · Trustpilot score · age-verified 18+. On mobile it auto-scrolls (swipeable; pauses on touch; off under reduced-motion).
• Dispatch countdown targets 16:00 UK; real/server time, never resets per visit; needs a working-days + bank-holiday calendar (shared with basket/checkout).

5. Non-negotiables (SEO + a11y + perf)

• SSR everything. The JS-heavy migration is what caused the traffic collapse — the production homepage must render markup server-side (finder card, rails, mega-menu all present in view-source with JS disabled). The prototype is client-rendered for demo convenience only.
• No CLS (reserve hero + card heights; skeletons while data loads).
• a11y: keyboard-operable finder/carousel/menu, visible focus rings, aria-live on the finder progress and price/subtotal updates, prefers-reduced-motion respected throughout.
• Self-contained assets for the prototype; production uses the CDN/catalogue image pipeline.

6. Data model / open items

• Arrays to replace with live data: USPS, MENU, CATEGORIES, FACETS, DEALS, RAILS, BRANDS, REVIEWS, GUIDES, FAQS, HERO_STEPS, BANNERS.
• Confirm: the finder rules-engine endpoint + ranking; the banner builder data model + CMS; real product/collection hrefs on every rail card; loyalty rate, dispatch calendar (shared); clean transparent product art (unblocks the dark banner treatment).
• Mega-menu is specified separately (SSR of the menu is the single biggest SEO item).

7. Compliance

No "disposable" wording · 18+ present · no health / "safer" / quit claims · every figure traces to a real source or is flagged.