🌸 Phase 7: Guided Platform Zen Alignment¶
Status: In Progress — Phase A (Token Swap) complete
Started: 27 Apr 2026
Scope: Full visual alignment of the Guided Astro platform with the Zen Design System
Platforms: Guided (Astro + Tailwind v4) → align with Hugo (Zen CSS)
Vision¶
The Guided platform (/guided/) is a paid product — practice exams for 126 certifications across 13 vendors. It currently uses its own design system ("Midnight Ocean" — teal accent, Satoshi font, glassmorphism). Users navigating from the main site to Guided see a jarring visual transition.
Goal: Make Guided feel like the same product as the main site. Same font, same accent, same surfaces, same nav. A user moving from a blog post to a practice exam should feel like they never left.
Architecture¶
Two Platforms, One Visual Language¶
aguidetocloud.com (Hugo — Zen Design System)
├── /blog/ ← 3-column reading room
├── /study-guides/ ← 3-column reading room
├── /licensing-docs/ ← 3-column reading room (NEW)
├── /free-tools/ ← 3-column tool grid
└── /cert-tracker/{cert}/ ← Study guide content
└── "Start Practice Test →"
└── /guided/explore/ ← Astro (now Zen-aligned)
aguidetocloud.com/guided/ (Astro — Zen-aligned)
├── /guided/explore/ ← Practice test catalog
├── /guided/{cert}/ ← Cert landing page (exam details + buy)
├── /guided/{cert}/practice/ ← PracticeQuiz React component
├── /guided/{vendor}/ ← Vendor pages
└── /guided/dashboard/ ← User progress
What Changed (Token Mapping)¶
| Property | Before (Midnight Ocean) | After (Zen) |
|---|---|---|
| Accent | Teal #2DD4BF / #0F766E |
Indigo #818CF8 / #6366F1 |
| Font | Satoshi | Inter |
| Dark base | #0B1120 (midnight blue) |
#0A0A0A (near-black) |
| Light base | #F8FAFC (blue-white) |
#FAFAFA (warm white) |
| Surface (dark) | rgba(255,255,255,0.06) (translucent) |
#141414 (solid) |
| Text primary (dark) | #F1F5F9 (blue-tinted) |
#F5F5F5 (neutral) |
| Text body (dark) | #CBD5E1 (slate) |
#D4D4D4 (neutral) |
| Borders (dark) | rgba(255,255,255,0.1) (translucent) |
#262626 (solid) |
| Glass | backdrop-filter: blur(24px) |
Removed entirely |
| Orbs | Animated gradient blurs | Removed entirely |
| Shadows | Glow effects (0 0 20px rgba(...)) |
Clean (0 4px 12px rgba(...)) |
| Radii | 8px/12px/16px/20px |
6px/10px/16px (Zen scale) |
| Transitions | cubic-bezier bounce/spring, 200-500ms |
ease-out only, 150ms max |
Implementation Progress¶
| Phase | Status | Notes |
|---|---|---|
| A: Global Token Swap | ✅ | global.css @theme block, light overrides, glass→solid, orbs removed, Inter font |
| A2: Header inline glass | ✅ | Removed backdrop-filter from vendor dropdown inline style |
| A3: Hardcoded colors audit | ✅ | PracticeQuiz canvas → Zen palette, glow shadows removed, inline styles cleaned |
| B: Unified Nav | ✅ | Rebuilt Header.astro — Study Guides / Practice Exams / Free Tools / Licensing Wiki / Blog / Videos. Mobile hamburger. Matches Hugo nav. |
| C: Explore → 3-Column | ✅ | Ported zt-reading.css. Left vendor nav, center card grid, right companion. Token bridge. 422 lines dead code removed. |
| D: Cert Landing Pages | ✅ | Removed 301 redirect. 126 exam-focused reading rooms. Breadcrumb, exam details, domains, study guide, FAQ, CTAs. 762 lines dead code removed. |
| E: PracticeQuiz Polish | ✅ | Canvas colors → Zen, glow shadows removed, orange purchase UI preserved |
| F: Dashboard + Other | ✅ | Light mode polish, sidebar parity, dark default, cross-links removed |
| G: QA + Deploy | ✅ | Deployed: Hugo commit d567e3e, Guided commit ab6d83a. Playwright QA 9 screenshots. |
Files Changed (Phase A)¶
| File | Changes |
|---|---|
src/styles/global.css |
Full @theme token swap, light overrides, glass→solid, orbs removed, Inter font, clean transitions |
src/components/layout/Header.astro |
Removed inline backdrop-filter + hardcoded bg on vendor dropdown |
public/fonts/inter-*.woff2 |
Added Inter 400/500/600/700/800 weight files |
Lessons Learned¶
1. Dark-Default Mechanism Must Be Preserved¶
Guided uses dark as CSS default (no class needed) and html:not(.dark) for light mode. This is the OPPOSITE of Zen (light default, [data-theme="dark"] for dark). Swapping the mechanism would require rewriting every component that uses html:not(.dark) or .dark Tailwind variants.
Decision: Keep dark-default mechanism, swap only the token VALUES. This is an interim step — "Zen tokens on Guided theming behavior." Full mechanism alignment is a future project.
2. Token Swap Is Necessary But Not Sufficient¶
The rubber-duck critique found hardcoded colors in:
- PracticeQuiz.tsx — canvas export colors, purchase banners
- Header.astro — inline backdrop-filter style
- global.css — .prose pre bg, admin badge, select options
Rule for future migrations: After token swap, always do a repo-wide grep for hex/rgb before declaring done.
3. --color-on-strong Needs Care¶
Used for text on accent-colored buttons. With teal accent, dark text was needed. With indigo, white works for both modes. BUT on-strong is also used on achievement (amber) buttons — white on amber is fine, but the token should be scoped to context:
- --color-on-strong: #FFFFFF — safe for indigo and amber buttons
- If adding success/error buttons, consider per-context tokens
4. Glass Removal Is More Than CSS Classes¶
Glass effects appear in:
- .glass-card, .glass-nav, .glass-modal (global.css) — cleaned ✅
- Inline styles on components (Header vendor dropdown) — cleaned ✅
- Explore page sidebar — cleaned ✅ (was using backdrop-filter: var(--glass-blur))
5. Achievement Color Is Semantic, Not Decorative¶
The rubber-duck correctly identified that achievement amber/gold encodes reward/premium/progress semantics distinct from the accent color. Keep it — it's functional, not a second accent. Orange purchase UI in PracticeQuiz.tsx stays orange.
6. Font Path Needs /guided/ Base¶
Astro's base: '/guided' means all public asset paths need the base prefix. Font @font-face declarations must use /guided/fonts/inter-400.woff2, not /fonts/inter-400.woff2.
7. Token Bridge Pattern (Astro → Zen CSS)¶
zt-reading.css uses Zen token names (--text-primary, --bg-surface, etc.) but Astro defines tokens with different names (--color-text, --color-surface). The bridge maps them via CSS custom properties on .zt-reading:
.zt-reading {
--text-primary: var(--color-text);
--bg-surface: var(--color-surface);
--border: var(--color-border);
--accent: var(--color-accent);
/* etc. */
}
This pattern lets us use the EXACT same zt-reading.css file on both platforms without modification. Port the CSS file, add the bridge, done.
8. Dead Code After </BaseLayout> Still Renders¶
In Astro, HTML after </BaseLayout> is NOT safely ignored — it can appear in the page output. Always remove dead code below the closing tag. The old cert pages had 762 lines of dead HTML after the return Astro.redirect() that rendered visually when the redirect was removed.
9. Unified Nav = 6 Direct Links, No Mega-Menus¶
The simplified nav (Study Guides | Practice Exams | Free Tools | Licensing Wiki | Blog | Videos) removed 190 lines of mega-menu HTML from Hugo and ~120 lines of dropdown code from Astro. Every link goes to a 3-column landing page. This is the Zen way — "content is king" applies to navigation too.
10. Footer Parity = Same Content + Same Icons + Same Order¶
The rubber-duck correctly identified that text-only links on Guided while Hugo has icon+label links breaks Guardrail #12 (One Body Two Organs). Inline SVGs with the same Feather icon paths solve this without needing a partial system. Third-party brand elements (Ko-fi button) override the "one accent" rule — brands are brands.
11. Sidebar Title Consistency Across Reading Rooms¶
.zt-cert-nav-header had border-left accent line + border-bottom divider, but .zt-lic-nav-header (Videos, Licensing, Free Tools) had neither. Small CSS differences compound into "feels like a different site" perception. One pattern, applied everywhere.
Detection Commands (for hardcoded colors)¶
# Teal accent remnants
grep -rn "#2DD4BF\|#5EEAD4\|#0F766E\|#0D9488" src/
# Old dark backgrounds
grep -rn "#0B1120\|#131A2B" src/
# Translucent rgba surfaces
grep -rn "rgba(255,255,255,0\." src/styles/
# backdrop-filter (banned)
grep -rn "backdrop-filter" src/
# Satoshi font
grep -rn "Satoshi\|satoshi" src/
# Teal Tailwind classes
grep -rn "teal\|emerald\|cyan" src/ --include="*.astro" --include="*.tsx"
Key Reference Files¶
| File | Purpose |
|---|---|
src/styles/global.css |
✅ Zen-aligned design tokens |
src/components/layout/Header.astro |
✅ Unified nav matching Hugo |
src/components/layout/Footer.astro |
✅ Unified footer matching Hugo (Guardrail #12) |
src/pages/explore/index.astro |
✅ Explore catalog page |
src/pages/[slug]/index.astro |
✅ Cert landing page |
src/pages/[cert]/practice.astro |
✅ Practice quiz page |
src/components/interactive/PracticeQuiz.tsx |
133KB React component (paid product) |
src/content/certs/*.toml |
126 cert metadata files |
src/data/vendors.ts |
13 vendor definitions |