Skip to content

Zen Design System Quickref

This page is the fast lookup. The full Zen Design System lives in /zen-system/ with philosophy, components, spacing, typography, and migration playbooks.

Use this page when you need to remember a token name or a guardrail mid-edit. Use the full system when you're starting new work.

The five principles

  1. Content is king. Reading, tools, tests, study guides — everything else gets out of their way.
  2. Everything earns its place. Ask: does this serve the user? If decorative, remove it.
  3. Consistent, not unique. All tools look the same. Visual identity comes from the system, not from per-tool flair.
  4. Deliberate, not accidental. Every colour has a semantic role. Every font size has a purpose. Nothing is "close enough".
  5. Room for growth. Strict but not rigid. New components fine — must follow the rules.

Tokens (Hugo names)

:root {
  /* Backgrounds */
  --bg-page: #FAFAFA;
  --bg-surface: #FFFFFF;
  --bg-elevated: #F5F5F5;

  /* Text */
  --text-primary: #1A1A1A;
  --text-secondary: #404040;
  --text-tertiary: #737373;
  --text-muted: #A3A3A3;

  /* Borders */
  --border: #E5E5E5;
  --border-emphasis: #D4D4D4;

  /* Accent — indigo, ONE for the whole site */
  --accent: #6366F1;
  --accent-hover: #4F46E5;
  --accent-subtle: #EEF2FF;

  /* Semantic — used ONLY for meaning, never decoration */
  --success: #22C55E;
  --warning: #EAB308;
  --error:   #EF4444;

  /* Spacing — 8px grid */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-6: 24px;
  --space-8: 32px;
  --space-12: 48px;
  --space-16: 64px;
  --space-24: 96px;

  /* Radius */
  --radius-sm: 4px;
  --radius-md: 6px;
  --radius-lg: 8px;
  --radius-full: 999px;

  /* Reading widths */
  --max-reading: 720px;   /* prose */
  --max-content: 1080px;  /* with sidebar */
  --max-page: 1200px;     /* full chrome */
}

[data-theme="dark"] {
  --bg-page: #0A0A0A;
  --bg-surface: #141414;
  --bg-elevated: #1A1A1A;
  --text-primary: #F5F5F5;
  --text-secondary: #D4D4D4;
  --text-tertiary: #A3A3A3;
  --text-muted: #737373;
  --border: #262626;
  --border-emphasis: #404040;
  --accent: #818CF8;
  --accent-hover: #6366F1;
  --accent-subtle: rgba(99, 102, 241, 0.1);
  --success: #4ADE80;
  --warning: #FACC15;
  --error:   #F87171;
}

Guardrails (what you must NOT do)

Rule What breaks if violated
No hardcoded colours — all color/background/border-color use var(--token) Theme toggle stops working for that element
One accent: indigo. No per-tool colours. The whole consistency principle dies
No gradients, glows, glassmorphism, shimmer, cursor effects "Cherry blossom tree, not a jungle"
No backdrop-filter — permanently banned (performance) Mobile FPS tanks
No arbitrary values — spacing from 8px grid, font from type scale, radii from token scale Visual drift accumulates per tool
Both modes must work — light (default) and dark (toggle). Test both. Half the audience hates the look
Transitions ≤200ms ease-out, only on transform / opacity / colour / background-color / border-color / box-shadow Long animations feel slow; wrong properties trigger layout
All tools look identical. Differentiate by feature, not visual chrome. Each tool becomes its own brand

One Body, Two Organs

Hugo (aguidetocloud-revamp) and Astro (guided) are one product, two implementations. Every change to nav, footer, fonts, tokens, theme toggle, or shared chrome MUST be applied to both organs in the same session. No "I'll sync it later".

Parity file map

Surface Hugo file Astro file
Top nav aguidetocloud-revamp/layouts/partials/nav.html + static/css/style.css (.nav-* + .drawer-*) guided/src/components/layout/Header.astro (HTML + scoped <style is:global>)
Footer aguidetocloud-revamp/layouts/partials/footer.html guided/src/components/layout/Footer.astro
Theme toggle inline in nav.html + static/js/theme-toggle.js inline <script> in Header.astro
Design tokens aguidetocloud-revamp/static/css/style.css (:root + .dark) guided/src/styles/global.css (different prefix, same values)
Logo / favicon aguidetocloud-revamp/static/images/ guided/public/images/

CSS variable name mapping (Hugo → Astro)

Same hex values, different prefixes. Translate names when porting code; don't paste raw.

Hugo Astro
--text-primary --color-text
--text-secondary --color-text-body
--text-tertiary --color-text-secondary
--text-muted --color-text-muted
--accent --color-accent
--accent-subtle --color-accent-subtle
--accent-hover --color-accent-hover
--border --color-border

Pre-commit gate

Before git push on any pair file, ask: "Did I touch the matching organ?" If no → DO NOT push. Open the matching file, apply the same change, push BOTH in the same commit (or two commits in the same session — never split across sessions).

Incident — 2 May 2026

Hugo nav got underline-active + Mind Maps + group dividers + ko-fi CTA in commit f3dda5c. Astro Header.astro was overlooked. Guided pages still showed the old rectangle pill and were missing Mind Maps for ~14 hours until 3 May session caught it.

Fix: the parity gate above is now mandatory.

Hub page Zen pattern (Layer 1)

Set 3 May 2026 across 9 main pages (homepage, about, study-guides, licensing-docs, blog, free-tools, videos, mind-maps, /guided/explore/). Every first-layer hub follows this structure:

1. zt-blog-header           Title + count badge (no dry one-liner here)
2. zt-hub-intro             Belief paragraph — why this exists, in plain English
                            Optional <strong> + <em> for emphasis
3. zt-hub-voice             ONE testimonial pull-quote (skip if no honest fit)
                            Voices > self-stat blocks (brag-allergy rule)
4. zt-hub-disclosure        OPTIONAL small footnote (currency, freshness, etc.)
5. zt-hub-featured          OPTIONAL "Where to start" / "Most useful" / "Most watched" row
                            Hand-picked, 3-5 items max — first stop for newcomers
6. Search input             Standard zt-sg-search-wrap pattern
7. Catalog                  Existing per-hub grid (cards/rows)

CSS classes live in aguidetocloud-revamp/static/css/zt-reading.css AND guided/public/css/zt-reading.css. Both copies must stay in sync per One Body Two Organs.

Voice library (testimonials safe to cite)

Handle Quote (excerpt) Use on
@lalitds (YouTube) "Even the paid courses do not organize the stuff this way. Clarity and depth are more than other tutors." Blog, homepage
@pablonleon (YouTube) "I work at Microsoft and I have passed many of my exams using your videos…" Study guides, cert success
@yourdream8 (YouTube) "I just passed with a 777 (Yes, Seriously). This video helped me tremendously." Practice exams, cert success
@maestus6 (YouTube) "Sir thank you so much for this awesome course." Videos, course gratitude

When to skip the voice block

If no testimonial in the library cleanly matches the page topic, skip it. Don't cargo-cult. Honest move = silence over forced fit. Used on Licensing, Free Tools, Mind Maps.

Brag-allergy enforcement on hubs

❌ Don't ✅ Do
Stat-pill rows in hero ("N exams · M vendors · X free") Counts as small badges next to title ({N} guides)
"Quick stats" companion sections that duplicate counts Single relevant facts in companion
Per-card view counts on videos (12-view videos look embarrassing) "Most watched" featured row (top-N selection without showing the numbers)
Inline style="color:..." overrides Use accent token via class

Layer 2 cert-landing pattern (paid-product specific)

Set 3 May 2026 on guided/src/pages/[slug]/index.astro (~80 cert pages):

H1 + level/vendor badges
tagline                     What this cert is, plain English
.guided-belief              "$79 practice exams are gatekeeping. Mine are $9 because it should be."
.guided-cert-voice          @yourdream8 testimonial pull-quote
.guided-cta-row {
  primary (filled indigo)   "Try 20 questions free →"
  secondary (bordered)      "Unlock all {N} — $9"
}
.guided-cta-bonus           Inline benefit line if hasStudyGuide
.guided-trust-grid          6 cells (3 cols desktop, 2 cols mobile, ✓ checkmarks indigo)
.guided-quiz-anchor         "↓ Try the actual questions below — no sign-up needed."
[ Embedded PracticeQuiz ]   Direct, no extra clicks

Color philosophy: indigo only. No green for the buy button (Zen brand integrity > payment-product convention). The 3 May commit removed #16a34a !important.

Two CTAs, not three. "Try first, buy second" matches new-user psychology. Bundled benefits (study guide) appear as inline benefit text, not competing buttons.

Reference points (where the system was inspired)

  • Notion — tool consistency, calm density
  • Linear — typography, spacing, micro-interactions
  • Stripe Docs — reading sidebar, top tabs, code-on-the-right (aspirational, not shipped)

Cross-references