Skip to content

🎨 Guided Platform Redesign — UX & Architecture

Started: 24 April 2026
Status: ✅ Complete — all page types redesigned and live
Completed: 24 April 2026 (evening session)

Why this redesign exists

Guided grew from a Microsoft-only platform (21 certs, all with study guides) to a multi-vendor platform (126 certs, 13 vendors) over ~2 weeks in April 2026. The UX didn't keep up:

  • Homepage title said "Interactive Microsoft Certification Prep"
  • Explore page had 5 Microsoft-only category filters
  • category field was broken — AWS Solutions Architect was categorised as "ai"
  • 92 non-Microsoft certs had no landing page at all
  • PathLayout assumed every cert had a study guide
  • Pricing section showed 3 tiers even for practice-only certs

This redesign fixes the information architecture, makes the platform genuinely multi-vendor, and creates a design system that scales to 200+ certs without manual page edits.

Information Architecture Decision

Options evaluated

Option Description Verdict
A — Flat Homepage → Cert landing → Study/Practice ❌ 126 cards overwhelming, no vendor SEO
B — Vendor hierarchy Homepage → Vendor page → Cert landing → Study/Practice ❌ Extra click, sparse vendor pages
C — Hybrid ⭐ Homepage (search + filters) → Cert landing → Study/Practice, plus vendor pages as SEO side-doors ✅ Approved

Option C detail

Main flow (no extra clicks):
  Homepage → Cert landing → Study / Practice

Side-door flow (SEO entry):
  Google "aws practice exams" → /guided/aws/ → Cert landing → Practice

Filter axes on homepage:
  Vendor (13) × Topic (8) × Level (4) × Content tier (2)

Vendor pages are auto-generated from TOML data — zero maintenance.

Data Architecture

Category taxonomy (cross-vendor)

The old category field mixed vendor identifiers with technology domains. The new taxonomy separates them:

Field Purpose Values
vendor (required) Who issues the cert microsoft, aws, cisco, comptia, gcp, isc2, isaca, cncf, hashicorp, juniper, paloalto, eccouncil, fortinet
category (required) Technology domain cloud, security, networking, ai, data, devops, admin, business
Content tier (derived) Full course vs practice only modules > 0 ? 'full' : 'practice' — not stored

Category mapping reference

Category Label Example certs
cloud Cloud AZ-900, AZ-104, AWS SAA, GCP Architect, CompTIA Cloud+
security Security SC-900, CompTIA Sec+, CISSP, CEH, CKS
networking Networking CCNA, JNCIA, Network+, Fortinet NSE, Palo Alto NetSec
ai AI & Copilot AB-900, AI-901, AWS MLA, GCP ML Engineer, CompTIA DataAI
data Data & Analytics DP-600, AWS DBS, GCP Data Engineer, CompTIA Data+
devops DevOps AZ-400, AWS DevOps, Terraform, CKA, Cisco DevNet
admin IT Admin MS-102, MD-102, MS-700, GCP Workspace Admin, CompTIA A+
business Business Apps PL-900, PL-400, MB-800, CompTIA Project+

Content tiers

Tier What's included Count Vendors
Full course Study guide (MDX modules) + practice exam (JSON) 35 Microsoft only
Practice only Practice exam (JSON) only 89 AWS, Cisco, CompTIA, GCP, ISC², ISACA, CNCF, HashiCorp, Juniper, Palo Alto, EC-Council, Fortinet
Placeholder TOML registered, no content 2 AI-200 (coming soon), SC-500 (coming soon)

Zod schema (content.config.ts)

const certs = defineCollection({
  schema: z.object({
    code: z.string(),
    name: z.string(),
    vendor: z.enum([/* 13 vendors */]),        // REQUIRED (was optional)
    category: z.enum([/* 8 categories */]),     // NEW taxonomy
    level: z.enum([/* 12 levels */]),
    status: z.enum(['live', 'coming-soon', 'planned', 'retired']),
    modules: z.number().int().nonnegative(),
    questions: z.number().int().nonnegative(),
    // ... rest unchanged
  }),
});

Five Page Types (Exemplar Designs)

1. Homepage — Multi-vendor front door

Changes from current:

  • Title: ~~"Interactive Microsoft Certification Prep"~~ → "Cert prep that's actually interactive"
  • Stats: "126 certs · 13 vendors · Free to start"
  • New: Search bar in hero (client-side fuzzy, Cmd-K)
  • New: Vendor ribbon — scrollable pills linking to vendor pages
  • New: 4 "Not sure?" recommender cards (cross-vendor career paths)
  • New: Multi-axis filter bar: vendor + topic + level + content tier
  • Card redesign: Vendor badge, content tier indicator, level pill

Key components:

  • SearchBar.tsx — React island, fuzzy search across certs
  • VendorRibbon.astro — Scrollable vendor pills with counts
  • CertCard.astro — Redesigned card with vendor + tier badges
  • FilterBar.astro / FilterBar.tsx — Multi-axis filtering with URL params
  • JourneyCard.astro — Career path recommender cards

2. Vendor Pages — SEO side-doors

URL: /guided/{vendor}/ (e.g., /guided/microsoft/, /guided/aws/)

Template: Single [vendor]/index.astro auto-generating 13 pages from:

  • getCollection('certs').filter(vendor === slug)
  • Vendor metadata from src/data/vendors.toml

Layout:

  • Vendor hero (name, description, cert count, official link)
  • Certs grouped by level (Fundamentals → Associate → Expert)
  • "Explore other vendors" cross-links at bottom

Metadata file: src/data/vendors.toml — 13 entries with slug, name, description, accent, official URL.

3. Cert Landing Page (PathLayout v2)

The big change: PathLayout becomes content-tier-aware.

Section Full Course (AZ-104) Practice Only (Sec+)
Breadcrumbs ✅ Guided > Microsoft > AZ-104 ✅ Guided > CompTIA > Security+
Hero Study Guide + Practice cards Single Practice card
What You'll Learn Standardised 4 highlights Hidden
Curriculum Domain accordions + module lists Hidden
Practice Lab Full section Main content
Pricing 3 tiers (Practice / Guide / Bundle) 1 centered tier
About Exam Vendor-agnostic official link Same
FAQ From [[faq]] in TOML Same
Bottom CTA "Ready to study?" "Ready to practice?"

Dynamic route: Single [cert]/index.astro replaces 34 static pages.

New TOML fields (added per cert for dynamic landing pages):

# Exam details (required for landing page)
[exam]
duration = "120 minutes"
passing_score = "700/1000"
question_types = "Multiple choice, drag-and-drop"
cost = "$165 USD"
official_link = "https://..."

# Domain details
[[domain]]
number = 1
name = "Manage Azure Identities and Governance"
weight = "20-25%"
description = "Microsoft Entra ID, RBAC..."
is_free = true

# FAQs
[[faq]]
q = "Is AZ-104 hard?"
a = "It's the hardest associate-level Azure cert..."

Derived at build time (not stored in TOML):

  • Module list per domain → content collection query
  • Question count per domain → JSON file scan
  • Difficulty breakdown → question JSON parsing
  • Sample question → first free domain question

4. Study Module (refinements only)

  • Breadcrumbs: Guided > Vendor > Cert > Domain > Module
  • "🧪 Test yourself" CTA at end → links to /practice/?domain=N
  • Practice link in sidebar nav
  • Domain progress ring

5. Practice Quiz (refinements only)

  • URL param ?domain=N pre-filter (deep links from modules)
  • Breadcrumbs
  • Question bookmarking (localStorage)
  • Enhanced results: domain breakdown + "Retest weak areas"

Deploy Plan (7 deploys, reviewed individually)

Deploy What Visual Change Status
1 TOML category fix + Zod schema + explore labels Explore filters update ✅ Done
2 vendors.toml metadata file None (data only) ✅ Done
3 Homepage redesign Major — new hero, search, filters, cards ✅ Done
4 Vendor pages ([vendor]/index.astro) 13 new pages ✅ Done
5 PathLayout v2 + dynamic [cert]/index.astro Major — 92 new landing pages ✅ Done
6 Module page refinements Free tier standardised, video removed, test CTA ✅ Done
7 Practice page refinements Readability, bookmarks, retest, URL params ✅ Done

Each deploy = git push → Cloudflare auto-builds → verify on live → review on phone → proceed.

"Add a new cert" workflow (post-redesign)

Practice-only cert (any vendor)

  1. Create src/content/certs/{code}.toml with all fields including [exam], [[domain]], [[faq]]
  2. Drop question JSONs in src/data/questions/{code}-domain-N.json
  3. Done. Homepage, explore, vendor page, cert landing, and practice page all auto-update.

Full-course cert (with study guide)

  1. All of the above
  2. Create MDX modules in src/content/{cert}/domain-N/*.mdx
  3. Done. Study module pages auto-generate from content collection.

Zero page edits in either case.

Key Files Reference

File Purpose
src/content/certs/*.toml 126 cert registry files (single source of truth)
src/content.config.ts Zod schemas for certs + modules collections
src/data/vendors.toml Vendor metadata (name, accent, official URL) — NEW
src/pages/index.astro Homepage
src/pages/explore/index.astro Explore/catalog page
src/pages/[cert]/index.astro Dynamic cert landing (replaces 34 static pages) — NEW
src/pages/[vendor]/index.astro Dynamic vendor page (13 pages) — NEW
src/pages/[cert]/practice.astro Dynamic practice route
src/pages/[...slug].astro Dynamic study module route (MDX)
src/layouts/PathLayout.astro Cert landing page template (enhanced for content tiers)
src/layouts/ModuleLayout.astro Study module template
src/layouts/BaseLayout.astro Site shell
src/styles/global.css Design tokens

Design Principles

  1. Dark mode default. Light mode equally polished.
  2. Mobile-first. Most study happens on phones.
  3. Astro islands. Don't add client-side frameworks for static content.
  4. WCAG AA. Focus rings, screen reader, prefers-reduced-motion.
  5. Base path. Site runs at /guided/ — use import.meta.env.BASE_URL.
  6. Content is sacred. Never edit MDX or question JSON files during redesign.
  7. PathLayout is the template. Enhance it, don't replace it.
  8. One deploy per change. Small pushes, reviewed on phone.
  9. Data-driven everything. New cert = drop TOML + content files. Zero page edits.

Business Model (locked — do not change)

Item Detail
Payments Lemon Squeezy (Merchant of Record)
Auth Licence keys → Cloudflare Worker → JWT in localStorage. No accounts.
Pricing Fundamentals $29 / Associate $49 / Expert $69 / All-Access $149/yr
Launch pricing $19 / $29 / $39 / $79
Free tier 1 full domain of study guide + 20 practice questions. No account needed.
Access 1 year + updates. 50% off renewal.

Session Log

Session 1 — 24 April 2026

What was done:

  • Full site audit (supplementary to Phase 1 audit from 21 April)
  • IA decision: Option C (Hybrid) approved
  • Designed all 5 exemplar page types
  • All 7 deploys shipped:
  • TOML category taxonomy (126 files fixed) + Zod schema
  • vendors.toml metadata (13 vendors)
  • Homepage redesign (search, filters, vendor ribbon, card redesign)
  • Vendor pages (13 auto-generated SEO pages)
  • Cert landing pages (92 new SEO pages via dynamic [slug] route)
  • Module refinements (free tier standardised: Domain 1 + 5 lessons, video placeholders removed, test-yourself CTA)
  • Practice quiz UX overhaul (readability, bookmarks, retest, URL params)
  • Post-deploy QA pass with Playwright (8 visual test flows):
  • Fixed hardcoded "200 questions" text
  • Fixed remaining "Microsoft Learn" reference
  • Unified scenario + question into single readable block
  • Added question navigation grid (like MeasureUp/Whizlabs/Kaplan)
  • Added multi-select "Select ALL that apply" indicator
  • Added streak counter (🔥 3 streak)
  • Added "Retest Wrong Questions" button (separate from weak areas)
  • Fixed score display ("0 of 10" instead of "0/0 correct")
  • Fixed header overflow (capped featured certs at 3)
  • Fixed mobile button layout (flex-col on mobile, flex-row on desktop)
  • Added scroll-mt-20 to prevent sticky header overlap
  • Timer pacing feedback in results
  • Widened quiz container (max-w-3xl → max-w-4xl)
  • Created this documentation + learn portal docs
  • Playwright + Chromium installed for visual testing

Total: 1,210 pages (was 1,105 at start — +105 new pages)

Key decisions:

  • Category taxonomy: 8 cross-vendor categories
  • Vendor field: Required enum with 13 values
  • Content tier: Derived from modules > 0, not stored
  • Vendor pages: Auto-generated, not in main nav flow
  • PathLayout: Content-tier-aware (conditional sections)
  • Free tier: Domain 1 + first 5 modules only (override at route level)
  • Practice quiz: Nav grid + bookmarks + retest = competitive with MeasureUp/Whizlabs

What's still missing in practice quiz (Round 2):

  • Historical progress tracking (attempt history, improvement trends over time)
  • Confidence rating per answer (Kaplan-style: sure/unsure/guessing)
  • Answer change tracking (did user change their answer? did it help?)
  • Matching question review rendering (currently basic)
  • Bookmarked questions filter mode on setup screen ("Practice only bookmarked")
  • Community discussion links per question (GitHub Discussions)
  • Floating accessibility widget investigation (overlapping content in screenshots)
  • Per-domain score history ("You improved D2 from 45% to 78%")
  • Custom quiz builder (pick specific questions by ID/topic)
  • Exam readiness score ("Based on 3 attempts, you're 72% ready")

Pick up here:

  • Practice quiz Round 2 — use starter prompt below
  • Also pending: design/layout tweaking for homepage, vendor pages, cert landing pages
  • Also pending: enrich TOMLs with [exam], [[domain]], [[faq]] data for richer cert landing pages
  • Also pending: migrate 34 static Microsoft landing pages to dynamic route