Skip to content

🏠 Guided — Homepage Design

Last updated: 8 May 2026 (v2 — embedded real PracticeQuiz + tone reframe) File: src/pages/index.astro URL: aguidetocloud.com/guided/ Latest commits: 0e128e7 (v2), 0ca214c (v1 reframe)

Purpose

The homepage is the conversion funnel entry point. It must:

  1. Communicate "$9 per cert, not $79" immediately (price-as-philosophy hook)
  2. Show credibility via tone honesty (no fluff, no upsells, founder voice)
  3. Let users taste the real product (embedded PracticeQuiz with 20 free AZ-900 questions)
  4. Let users find their cert quickly (search + dropdown filters)
  5. Convert browsers without aggressive CTAs (informational pricing > pushy upsells)

Section Layout (top → bottom — 9 sections)

1. Hero (single-column, centered)

Pivoted from V1's 2-column layout (text + interactive previews on right) to single-column centered because section 2 (embedded quiz) replaces what the right column did, and single-column delivers more "statement" weight.

Element Content Voice
Badge study guides free forever — no account needed Lowercase, success-coloured pill
h1 practice exams that don't gatekeep. Lowercase, philosophy-first
Pricing line $9, not $79. free study guides forever. no signup, no account. Indigo accent on "$9, not $79" — names the gatekeeping price explicitly
Description {N} certs across Microsoft, AWS, Cisco, CompTIA, GCP — every answer explained, why it's right and why the others aren't. Vendor names capitalised (proper nouns), lowercase narrative
Primary CTA browse {N} certs → → #catalog
Secondary CTA try AZ-900 free → #sample-exam-section Cert code uppercase
Trust stats {N} certifications · {N}+ questions · {N} vendors All dynamic
Free guides badge row {N} free study guides + chips of cert codes Auto-populated from studyGuideCerts.length

2. Try the real exam, free (NEW v1 → reworked v2)

Big change between v1 and v2: v1 had a custom <SampleExam> component with 5 hardcoded questions and a buggy CSS focus mode (used var(--base) which doesn't exist in this design system — should have been var(--color-base)). v2 deleted SampleExam entirely and embedded the real <PracticeQuiz> component, configured for AZ-900 with the existing 20-question free tier.

Why this is better: - Same component cert pages already use — battle-tested. - Free tier (FREE_QUESTION_LIMIT = 20 from src/lib/access.ts) handles the cap natively. - All 5 question types (mcq, tf, multi-select, match, ordering) work natively. - Real focus mode (CSS overlay, already-working). - Real explanations, real progress tracking, real exam mode. - client:visible directive — quiz hydrates only when scrolled into view, hero stays fast.

Visual framing for "oomph":

<div class="surface-card p-3 sm:p-5 ring-1 ring-accent/15 shadow-lg" id="home-practice-wrap">
  <PracticeQuiz client:visible
                dataUrl={`${base}data/questions/az-900.json`}
                certCode="az-900"
                vendorSlug="microsoft" />
</div>

Above the quiz: a pulsing "live demo · AZ-900" badge so users know it's the real product, not marketing.

Below the quiz: "not the cert you want? browse {N} certs →" CTA back to the catalog.

3. What's inside $9 (NEW)

3-card row replacing v1's "Why Guided?" (which was generic).

Card Status Tagline
study guide free forever every concept in plain english. flashcards. ELI5 toggle. no signup.
200 questions $9 · once three modes: study (instant feedback), exam (timed), flashcards (SM-2 spaced).
exam mode included timed simulation, 80% pass threshold, no peeking, review at the end.

Closing: every answer explained — why it's right and why the others aren't.

Icons: simple line SVGs (lucide-style — book, pencil, clock). No emojis, no gradients.

4. Browse by Vendor (KEPT from v1)

Auto-scrolling carousel of vendor cards. Each card: SVG logo + vendor name + cert count + accent left border. Click → /guided/{vendor}/.

Implementation note: track is duplicated for seamless infinite loop. prefers-reduced-motion media query disables animation.

Shows certs with featured: true in TOML. Max 4 cards.

6. Not Sure Where to Start? (KEPT — recommender)

4 cards for paths: cloud / security / AI / networking. Click sets dropdown filters and scrolls to #catalog.

7. All Certifications Catalog (KEPT, polished)

Search bar + 4 dropdown filters (vendor / topic / level / type). Dynamic count "Showing N certifications". Default vendor: Microsoft (rubber-duck flagged this contradicts "All Certs" framing — open issue to consider).

Cert cards: - Card click → cert landing page (/{code}/) - "Try Practice →" button → practice page (/{code}/practice/) - Button uses delegated e.stopPropagation() via .cert-practice-link

8. How Guided Compares (KEPT)

10-row feature comparison table: Guided vs "Typical Competitor". Includes "Starting price: $9 (guides free) vs $20–$50+".

9. Why this exists (NEW — replaces "About")

Founder voice block in lowercase brainbar register. Lifted from FAQ #11 + reordered.

why this exists

cert prep was always overpriced. $50, $79, $99 for practice questions,
on top of an exam that already costs $165–$200.

so i built guided. free study guides. $9 practice. the same content
i'd want for myself, priced like i'd want it.

no fluff, no gatekeeping, no upsells. just the prep.

The closing line no fluff, no gatekeeping, no upsells. just the prep. deliberately echoes the BrainBar about page's no fluff, no gatekeeping, no five paragraphs of seo. just the answer. — Sush's voice as the constant across planets.

Sub-block: i'm Sutheesh — Microsoft Copilot Solution Engineer in NZ. started as an infra admin. sat every exam i could get my hands on. (Proper nouns capitalised — voice rule.) Links to YouTube + help page.

10. FAQ (KEPT, trimmed)

<details>-based accordion matching FAQPage JSON-LD. First item open by default.

v2 trim: removed mentions of $59 vendor pass and $149 all-access per Sush's call to de-feature tier upsells (FAQ #1 was the worst offender). FAQ #1 now uses dynamic studyGuideCerts.length count instead of inaccurate "every cert has a study guide" claim.

Voice / tone register (locked in v2)

Where Case
Hero h1 + section h2 headings lowercase ("practice exams that don't gatekeep")
Founder voice / philosophy paragraphs lowercase ("cert prep was always overpriced…")
Cert codes UPPERCASE (AZ-900, AI-901, CCNA) — proper nouns
Vendor names Title Case (Microsoft, AWS, CompTIA, GCP) — proper nouns
Product names Title Case (Azure Fundamentals, Stripe) — proper nouns
Personal name Lowercase or Capitalised contextually (i'm Sutheesh — Microsoft Copilot Solution Engineer in NZ)
Acronym country code UPPERCASE (NZ) — proper noun

The rubber-duck overcorrection in v1 lowercased proper nouns. Fixed in v2. Voice rule: "lowercase voice for founder/philosophy copy. Proper nouns / cert codes / vendor names stay capitalised." Capitalisation is grammar, not style.

Canonical tone reference: BrainBar about page (aguidetocloud-revamp/brainbar/layouts/_default/about.html).

Tier upsell de-featuring (v2)

Sush's call (8 May 2026): de-feature $59 vendor pass and $149 all-access from the homepage. Lead with $9 per cert only. Tier SKU deletion from Stripe / backend deferred to a separate session.

What was removed in v2: - The "Pick a tier" 3-card pricing block (was planned, never shipped — cancelled before v1 deploy) - FAQ #1 Vendor passes ($59) and all-access ($149) are also available. fragment - Comparison table tier rows (none existed in V1, no change needed)

What still exists in code (intentional — for active customers / direct-link checkouts): - Stripe products for vendor pass / all-access still functional - Backend /api/checkout still handles productType: 'vendor' | 'all' - Checkout-return logic in src/lib/checkout.ts still handles all 3 product types

Future session will remove the SKU code paths once Sush is ready.

SLA-protected files NOT touched in v1 / v2

File Why
src/components/interactive/PracticeQuiz.tsx Locked. v2 EMBEDS it from homepage but does not modify it.
src/pages/[cert]/practice.astro Practice page route — paid product.
src/pages/[slug]/index.astro Cert landing page — paid product.
src/pages/embed/[cert]/practice.astro Embed route — paid product.
src/data/questions/*.json Question banks — content.
scripts/build-question-data.mjs Data pipeline.
package.json build scripts Pipeline trigger.
astro.config.mjs Build config.
functions/guided/api/* Cloudflare Pages Functions (checkout, webhook, activate, verify).
Cloudflare env vars / bindings Locked per CF API DANGER ZONE.
Header / Footer / theme toggle / fonts / tokens One Body Two Organs rule.

Tests + ship gates

test-guided-home.cjs    18/18 pass    (rewritten in v2 to test the embedded PracticeQuiz; was 28 SampleExam checks in v1)
test-guided-qa.cjs      22/26 pass    PRE-EXISTING failures (Fullscreen header / Quiz Complete / Domain breakdown) — NOT v1 or v2 regressions
build                   2284 pages, ~120s, clean
practice page size      32.7 KB       (under 50 KB SLA limit — questions are runtime-fetched, not inlined)
homepage size           ~411 KB       (down from 434 KB v1; smaller because PracticeQuiz hydrates client-side)

Smoke tests (mandatory pre-push and post-deploy):

curl -sf https://www.aguidetocloud.com/guided/data/questions/az-900.json | head -c 50
# Must return JSON starting with [{"meta":

curl -sf -X POST https://www.aguidetocloud.com/guided/api/checkout -H "Content-Type: application/json" \
  -d '{"productType":"cert","certCode":"az-900","vendorSlug":"microsoft"}' | head -c 50
# Must return {"url":"https://checkout.stripe.com/...

curl -sf https://www.aguidetocloud.com/guided/az-900/practice/ -o /dev/null -w "%{http_code}"
# Must return 200

Structured Data (JSON-LD)

Schema Purpose
FAQPage Trimmed FAQ items → rich FAQ snippets in Google
WebSite Site entity + SearchAction for sitelinks search box
Organization Publisher info, logo, social links (YouTube channels)

Title and description in <BaseLayout> are now dynamic:

title={`guided — ${totalCerts} certs · practice exams that don't gatekeep`}
description={`$9 per cert, not $79. Free study guides forever. ${totalCerts} certs across ${activeVendors.slice(0, 5).map(v => v.shortName).join(', ')}…`}

(Was hardcoded 13 Vendors in v0 — fixed.)

JavaScript Behavior

Filter system (<script is:inline data-astro-rerun>)

  • Reads all 4 <select> dropdown values
  • Filters .cert-card elements by data-vendor, data-category, data-level, data-tier
  • Also filters by search text against data-search attribute
  • Updates result count text
  • Runs applyFilters() on load (applies Microsoft default)
  • Delegated event listener on document for .cert-practice-link clicks
  • Calls e.stopPropagation() to prevent card link navigation
  • Reads data-href and navigates to practice page

Embedded PracticeQuiz

  • Hydrated via client:visible (IntersectionObserver)
  • Fetches /guided/data/questions/az-900.json at runtime
  • Standard PracticeQuiz lifecycle: setup screen → quiz → results
  • Free-tier user gets 20 questions; clicking "Unlock" initiates Stripe checkout for AZ-900 (returns to /guided/az-900/practice/?checkout_session=… per functions/guided/api/checkout.ts)

Maintenance Checklist

When adding a new cert:

  1. Drop TOML in src/content/certs/ — homepage auto-updates (totalCerts, vendor counts)
  2. No page edits needed — card appears in catalog grid
  3. If featured: true, it appears in Featured section (max 4)
  4. Vendor card count auto-increments
  5. Hero stat strip auto-updates

When adding a new vendor:

  1. Add to src/data/vendors.ts (including logo field)
  2. Add SVG logo to public/vendors/{slug}.svg
  3. Add vendor slug to Zod enum in src/content.config.ts
  4. Homepage auto-generates vendor card + dropdown option

When changing tier strategy (e.g., re-introducing $59 / $149):

  1. Update FAQ #1 to mention the tier
  2. Add a section between catalog and comparison (tier card row)
  3. Decide: informational links to existing pages, or homepage-direct checkout?
  4. Informational = safer, no new SLA failure modes
  5. Direct checkout = needs new homepage handleCheckoutReturn() wiring + Playwright tests covering all 3 product types

Pre-existing test-guided-qa failures (not v1/v2 regressions)

After v1 ship (7 May), test-guided-qa.cjs shows 4 failures:

Test Status Likely cause
ab-100: Fullscreen header — missing ❌ Test pattern drift — UI text "Exit" may have changed
ab-730: Fullscreen header — missing ❌ Same
Results: Quiz Complete — missing ❌ Same — pattern looks for "Quiz Complete" text
Results: Domain breakdown — missing ❌ Same

These were failing before v1. Verified by checking PracticeQuiz.tsx mtime (5/3/2026 — untouched in this session). Sush flagged for a separate session to investigate test pattern drift.