VapeHub Product Page (PDP) — Developer Spec

What the PDP prototype demonstrates and what the production build must supply. One type-aware page on a single shared skeleton, adapting across four product types. Real VapeHub design system, not the mock's chrome. Companion to the design pack's product brief.

The prototype's 4-type switcher and the stock-state toggle are review affordances (they let you flip between templates and lifecycle states in one file) — in production each type renders as its own URL and stock comes from the catalogue, not a button.

★ The #1 fix — Server-render the buy box

The current live PDP ships the entire <main> as a "Loading product…" spinner: H1, price, variant selector, gallery, description, reviews are all client-rendered, absent from the server HTML. This is both the organic-decline root cause (crawlers see a spinner) and a conversion/reliability risk (a JS error, slow 4G or old Android leaves a spinner-locked buy box).

Server-render (or stream) the buy box — title, price, flavour selector, stock, add-to-basket, specs, reviews, FAQ, and the whole content deck below. The existing JSON-LD (Product + Breadcrumb + FAQ + aggregateRating) is the right shape — keep it, but see §7 on aggregateRating. This one change aligns the SEO-recovery and conversion agendas and is the highest-ROI fix on the site. The skeleton treatment in the prototype is for deferred data only (live stock, review counts) — never for the buy box itself.

SEO head tags — server-render these too (per type)

SSR'ing the buy box is necessary but not sufficient. Each of the four type URLs must serve, in the initial HTML: a unique <title> and meta description, a self-referential rel=canonical (the prototype ships neither), and OG/Twitter tags. Pick one canonical URL form and hold it everywhere — the prototype is inconsistent (schema @id/url are slash-less like /hayati-pro-max-plus while nav/internal links use trailing slashes, and the pod category appears as /prefilled-pod-kits/, /prefilled-pods/ and /hayati-pods/). Align nav, breadcrumb, JSON-LD @id/url, internal links and rel=canonical to the single chosen form before it fragments canonical signals.

1. The four types — one skeleton

All four share the same skeleton: sticky gallery + buy box (2-col desktop; single column + sticky Add bar on mobile, container-query breakpoint ~860px), then a content deck (description → specs → VapeHub Tested → reviews → FAQ → cross-sell). What changes per type is which selectors lead and which content blocks appear:

Each type keeps its own JSON-LD Product schema with its real canonical URL, brand, price and aggregateRating. Don't invent variants, stock or review counts — every one resolves to a real catalogue SKU or is flagged.

2. Variant selector — logic

The flavour is the product for kits/pods — treat it as first-class, never a <select>.

• Flavour = named rows/swatches with the tasting note leading (the note is the asset), a colour dot, and a live readout above the list ("Flavour: Blue Razz Lemonade"; "Please select" before choice). States: default / selected (green ring + mint wash + tick) / out-of-stock (muted, struck, shown-not-hidden so the range reads full, aria-disabled, not selectable). A search box + profile filters (fruit / menthol / etc.) are pure in-place filters over present DOM nodes — they never fetch.
• Strength = segmented control (real catalogue strengths, e.g. 20mg·2% / 10mg·1%). For E-Liquid and Pouches this leads.
• Flavour select swaps the gallery image to that colourway (per-variant image; fall back to the default where none exists) and syncs the sticky-bar thumbnail.

3. Bundle selector — multibuy as a tappable choice

Multibuy is a primary AOV lever, so it's selectable bundle cards (radio-style), not a footnote. Real deal tiers from the prototype (confirm against the promo engine):

• Each card shows the per-unit price; the better tier carries BEST VALUE; selecting one shows "Save £X vs singles", updates the CTA price and the mobile sticky-bar price, and keeps the "was" RRP in lock-step (a single-unit RRP is never shown against a bundle price).
• Default = Single (never pre-select the larger spend).
• Server-render the bundle price + saving as static text, not JS-computed — per §★, deferral/skeleton is for live stock and review counts only, never price maths. The initial HTML must carry the selected tier's price, the CTA price and the "Save £X" line so no-JS/crawler views see real numbers. (Every saving is anchored to RRP so the headline and the per-tier card badges show the same figure.)
• Promo model: the prototype demonstrates mix-and-match across a group ("Mix & match across Ban-Proof Big Puffs — applied automatically in the basket"), i.e. the customer picks the tier here and chooses flavours in the basket, where the multibuy engine handles the group. Build to that unless the promo engine is actually per-SKU (3× the chosen flavour) — confirm which against the engine (shared open item with basket §3) before wiring the add-to-basket payload.

4. Add to Basket — logic

• Disabled until a flavour is chosen — but not a dead button: tapping early shows an inline prompt ("Please choose a flavour first") and scrolls to the swatches. Once chosen, the label carries the price ("Add to Basket · £7.99").
• Qty stepper (min 1); crossing a multibuy threshold reflects the deal in price/label.
• On add: open the basket drawer with a subtle confirmation — never auto-navigate away from the PDP.

5. Stock lifecycle — four states

One stock value per product/variant drives the whole buy box. instock + low are buyable; soldout + discontinued are not, and must suppress every promise we can't honour:

• In stock — green pill, full buy box.
• Low stock — amber pill + "Only a few left" notice; still buyable.
• Out of stock — grey pill, greyed gallery + "SOLD OUT" overlay, buy row hidden, notify-me email capture shown, dispatch countdown / free-delivery chase / bundle tiers / loyalty points all suppressed, variant selectors inert (aria-disabled).
• Discontinued — "DISCONTINUED" overlay, no commerce, a replacement card pointing at the closest live alternative.

Notify-me validates the email client-side in the prototype; production posts it to a back-in-stock list keyed to the variant SKU and emails on restock.

6. VapeHub Tested — the differentiator

The one inverted band on the page (Device type). It reports VapeHub's own measured data vs the manufacturer claim — e.g. measured 4,872 puffs vs a claimed 6,000 — plus per-profile real-use estimates and cost-per-day. This is genuine E-E-A-T and the block competitors don't have. It must carry real test figures or be withheld — never fabricated numbers, and the disclosure line (how/when tested) stays.

7. Content deck, reviews, trust

• Description — compliant marketing copy: no "disposable" (post-June-2025 ban — "prefilled pod kit"), no health / cessation / "safer" claims. Rendered server-side.
• Spec grid — the at-a-glance table (battery, coil, capacity, nicotine, puffs, type). Already SSR today — keep it.
• Reviews — big-number summary + distribution histogram (5★→1★ with counts) + cards carrying a verified-purchase tag and the flavour purchased ("Bought: Blue Razz Lemonade · 20mg"). Flavour context is what makes vape reviews useful. aggregateRating / review in the JSON-LD must mirror genuinely displayed, real reviews — emit it only when it does. The prototype's ratings are sample data (flagged in a markup comment); shipping star ratings in structured data that aren't backed by shown reviews breaches Google's review-snippet policy (manual-action risk) and the no-fabrication rule.
• Align schema name to the visible H1 — the prototype's schema names drift from the on-page titles on two types (e.g. schema "Hayati Pro Max Plus Pods" vs H1 "…Refill Pods"). Emit the same product name in both.
• Add the newer Offer fields for product rich results — priceValidUntil, hasMerchantReturnPolicy, shippingDetails. The data already exists on-page (30-day returns, £30 free-delivery threshold, dispatch calendar) to populate them.
• Trust row is static, not a carousel (MHRA Notified · UKVIA · TPD/TRPR · Challenge 25 · Trustpilot). Rotating trust badges hurt trust and get missed.
• FAQ — accordion populated from the existing FAQ schema (keeps rich-result eligibility).
• Cross-sell ("Complete your kit") — relevant refills / nic salt / accessories with one-tap add; mirrors the basket cross-sell relevance rules.

8. Delivery reassurance + dispatch countdown

In the buy box: "Free next-day delivery over £30 · £2.99 under", 30-day returns, plain packaging. Live dispatch countdown (same engine as basket/checkout): before 16:00 UK Mon–Fri → "Order within {Xh Ym Zs} for same-day dispatch" (tabular-nums); after cutoff / weekend / holiday → "ships {next working day}". Real/server time, never resets per visit. Fix the sitewide copy mismatch: same-day dispatch, not "shipping".

9. Accessibility & performance

• Swatches / segmented / bundle cards are proper buttons with aria-pressed; OOS options aria-disabled; the flavour readout is an aria-live region.
• SSR (§★) + no CLS; skeleton only for deferred data. Viewport meta mandatory; inputs ≥16px; 390px zero horizontal overflow (prototype verified). prefers-reduced-motion disables the gallery zoom + transitions.
• Analytics layer (built): dataLayer events — view_item, select_variant, bundle_option_select, add_to_cart, atb_blocked, crosssell_click — wire these to the real tag manager so nothing silently breaks again.

10. Data model the back-end needs

• Product: id, name, brand, type, description, images (multiple + per-variant), category/breadcrumb, price, RRP, promo/multibuy rule, aggregateRating, FAQ, specs, and (Device) the range-comparison rows + VapeHub Tested figures.
• Variant matrix: flavours (name, tasting note, colour, per-variant stock, per-variant image) × strengths, each resolving to a SKU shared with the basket (inline edit) and checkout.
• Compatibility (Pod): which devices a refill fits / doesn't fit.
• Config (shared): free-delivery threshold (£30), delivery prices/ETAs, dispatch cutoff (16:00 + working-days/holidays), loyalty earn rate.

11. Still to confirm

Multibuy promo model (per-SKU vs mix-and-match group) · real variant matrix + per-variant stock/SKUs/images · real review data + Trustpilot score · VapeHub Tested figures per product · dispatch calendar · loyalty earn rate · back-in-stock provider.

12. Compliance

No "disposable" wording · 18+ throughout · no health / "safer" / quit claims · plain unbranded packaging · factual button + description copy.

Compliance eyeball — pouch copy. The Nicotine Pouches descriptor "no vapour, no smoke, no smell" is factual (it describes the format) and low-risk, but reads as an implicit comparison to smoking — get it signed off with the rest of the copy.

Open compliance item — the "Ban-Proof Big Puffs" range name. It carries no "disposable" and no health claim, so it clears the black-letter rules, but framing a range around the ban and high puff-counts is exactly what Trading Standards / ASA are scrutinising next. Get legal/ASA sign-off on the range name (used in nav, breadcrumb, gallery tag, JSON-LD breadcrumb and body copy) before production.