CLAUDE.md — PyStatR+ Website Project Guardrails

Last updated: 2026-02-06 Maintainer: Alierwai Reng — Founder & Lead Educator, PyStatR+ Site: https://pystatrplus.org Stack: Quarto static site + SCSS/CSS + Vanilla JavaScript + Python Deployment: Netlify

---

1. Brand Identity — Non-Negotiable Standards

Official Color Palette

Every page, component, and section MUST use only these brand colors. No unauthorized colors.

Token	Hex	Usage
--pystatr-deep-blue	#003366	Primary backgrounds, headers, trust elements
--pystatr-deep-blue-alt	#1E3A8A	Secondary blue, category accents
--pystatr-cyan	#38BDF8	Links, icons, interactive elements, hover states
--pystatr-cyan-alt	#00BFFF	Alternate cyan for gradients
--pystatr-yellow	#FFD700	Primary CTAs only, gold accents (sparingly)
--pystatr-yellow-alt	#FACC15	Softer gold for badges, highlights
--pystatr-grey	#F7F9FC	Light backgrounds, card surfaces
--pystatr-deep-black	#0B1120	Dark sections, navbar, footer
--pystatr-slate	#1E293B	Dark gradients, secondary dark

Accent Colors (service differentiation only):

Token	Hex	Context
Violet	#8b5cf6	Design services
Rose	#f43f5e	Compassion / community
Emerald	#10b981	Accessibility / growth
Amber	#ea580c	Premium / development

Rules: - NEVER introduce new colors without updating this document - All gradients must use combinations from the palette above - Dark sections: linear-gradient(180deg, #0B1120 0%, #1E293B 100%) - Light sections: #ffffff or #F7F9FC backgrounds - Text on dark: #E5E7EB (primary), #9CA3AF (muted) - Text on light: #374151 (body), #0B1120 (headings)

Typography

Element	Font Family	Weight	Size (Desktop)	Size (Mobile)
Headings	Poppins	600–800	See scale	See scale
Body	Roboto	300–500	1rem (16px)	1rem
Code	JetBrains Mono / Fira Code	400	0.9rem	0.85rem

Heading Scale (Desktop → Mobile):

Level	Desktop	Mobile
H1	2.5rem	2rem
H2	2rem	1.75rem
H3	1.5rem	1.25rem
H4	1.25rem	1.125rem

Rules: - Line height: 1.6–1.7 for body, 1.2–1.4 for headings - Max paragraph width: 68ch (CSS variable --paragraph-max-width) - Font imports via Google Fonts: Poppins:wght@400;500;600;700;800 and Roboto:wght@300;400;500;700 - NEVER use system fonts alone — always include brand fonts first - Code blocks: dark background (#0B1120), cyan border accent

Visual Language

• Aesthetic: Futuristic, geometric, minimalist, luminous
• Feel: Metallic blues, deep blacks, PyStatR+ gold accents
• Motion: Subtle, purposeful animations (fade-in, translateY, glow effects)
• Reduced motion: Always respect prefers-reduced-motion: reduce
• Icons: Use custom PNG icons from images/icons/ — not emoji in formal sections
• Emoji usage: Permitted only in informal contexts (blog, community). Remove from services, about, mission sections
• Photography: Use real images from images/ directory. Optimize all to WebP when possible

---

2. SEO Guardrails — Every Page, Every Time

Required Meta Tags (Every Page)

<!-- Required on every .qmd page via YAML front matter -->
pagetitle: "Page Title | PyStatR+"        <!-- 50-60 chars, keyword-first -->
description: "..."                         <!-- 120-160 chars, action-oriented -->
canonical: "https://pystatrplus.org/page/" <!-- Full canonical URL -->

<!-- Open Graph (every page) -->
open-graph:
  title: "..."
  description: "..."
  image: "images/og/page-name-og.png"     <!-- 1200x630px -->
  image-alt: "..."
  type: website
  locale: en_US
  site-name: "PyStatR+"

<!-- Twitter Card (every page) -->
twitter-card:
  title: "..."
  description: "..."
  image: "images/og/page-name-og.png"
  image-alt: "..."
  card: summary_large_image
  creator: "@PyStatRPlus"
  site: "@PyStatRPlus"

Structured Data (JSON-LD)

Required schemas by page type:

Page Type	Required Schema
Homepage	Organization, WebSite, WebPage, EducationalOrganization
Blog listing	CollectionPage, BreadcrumbList
Blog article	Article, BreadcrumbList, Person (author)
Course page	Course, BreadcrumbList, EducationalOrganization
Services page	Service, BreadcrumbList, Organization
About page	AboutPage, BreadcrumbList, Organization
Contact page	ContactPage, BreadcrumbList

Heading Hierarchy

• ONE <h1> per page — the page title
• H2 for major sections
• H3 for subsections within H2
• H4 sparingly for detailed sub-subsections
• NEVER skip heading levels (e.g., H1 → H3 without H2)
• All headings must have id attributes for anchor linking

Image Optimization

• ALL images must have descriptive alt text
• Use loading="lazy" for below-fold images
• Recommended formats: WebP (primary), PNG (fallback), SVG (icons)
• Thumbnail naming: thumbnail-sq.jpg (600x600), thumbnail-wd.jpg (1200x675)
• OG images: og-image.png (1200x630)
• Maximum file size: 200KB for thumbnails, 500KB for hero images
• Use srcset or responsive images where possible

URL Structure

• All lowercase, hyphenated (kebab-case)
• Blog posts: /posts/descriptive-slug/
• Pages: /page-name.html (Quarto default)
• No special characters, no trailing numbers
• Keep URLs under 75 characters

Internal Linking

• Every page must link to at least 2 other internal pages
• Use descriptive anchor text (not “click here”)
• Blog posts must include “Related Articles” section
• Breadcrumb navigation on all pages except homepage

Performance (Core Web Vitals)

• Target LCP < 2.5s
• Target CLS < 0.1
• Target INP < 200ms
• Minimize render-blocking CSS/JS
• Inline critical CSS for above-fold content
• Defer non-essential JavaScript

---

3. Mobile Optimization — Every Page, Every Component

Responsive Breakpoints

/* Mobile-first approach — these are the breakpoints */
/* Default: Mobile (< 640px) */
@media (min-width: 640px)  { /* Tablet */ }
@media (min-width: 1024px) { /* Desktop */ }
@media (min-width: 1400px) { /* Wide desktop */ }

Layout Rules

Component	Mobile	Tablet	Desktop
Grid cards	1 column	2 columns	3 columns
Navigation	Hamburger menu	Condensed	Full navbar
Hero section	Stacked (text above video)	Side-by-side	Two-column grid
Sidebar	Collapsed above content	Visible	Full sidebar
Footer	Stacked single column	2 columns	4 columns
Service cards	1 column	2 columns	3 columns
Testimonials	1 column carousel	2 columns	3 columns

Touch & Interaction

• Minimum touch target: 48px × 48px
• Button padding: minimum 0.75rem 1.5rem
• No hover-only interactions — all hover effects must have touch alternatives
• Swipe gestures for carousels on mobile
• Sticky header on all devices (pinned navbar)

Typography Scaling

• Body text: 1rem on all devices (never smaller than 16px)
• Headings: Scale down per the heading table above
• Line height: 1.6–1.7 body, 1.2–1.4 headings
• No horizontal scroll — ever. Use overflow-x: hidden on body

Mobile-Specific CSS

• scss/mobile-core.css — Core mobile overrides
• scss/mobile-dropdown.css — Mobile navigation menu
• All page CSS files in scss/pages/ must include mobile breakpoints
• Test every page at 320px, 375px, 414px, 768px, 1024px, 1440px

---

4. Accessibility Standards

WCAG AA Compliance (Minimum)

• Color contrast ratio: 4.5:1 for normal text, 3:1 for large text
• All interactive elements keyboard-accessible
• Visible focus indicators on all focusable elements
• Skip-to-content link on every page
• ARIA labels for icon-only buttons
• alt text on all images (decorative images: alt="")
• Semantic HTML: <nav>, <main>, <article>, <aside>, <footer>

Motion & Animation

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

This is already implemented globally. NEVER remove it. All new animations must be non-essential and respect this media query.

---

5. Page Architecture

Homepage Section Order (index.qmd)

1. Hero section (two-column: text + video)
2. Our Focus (brief value statement)
3. Mission section (image + text, left-right layout)
4. Vision section (image + text, right-left layout — reversed)
5. Services grid (6 cards: Education, Design, Development, Resume, Documents, Advertising)
6. C.E.I.A. Charter (values grid: Compassion, Excellence, Integrity, Accessibility)
7. Ethics CTA bridge
8. Latest Blog Posts (3 cards, dynamically loaded)
9. Testimonials (6 cards, dynamically loaded)
10. Ethics & Independence statement
11. Community social links grid
12. Final CTA section

Navigation Structure

[Logo] About Us | Learn [dropdown] | Blog | Services [dropdown] | Products [dropdown] | Contact | [Search]

Learn dropdown:
  COURSES → courses-upcoming.qmd
  - Getting Started in Data Science
  - Prompt Engineering
  - Data Analysis with Polars
  - Fundamentals of Statistics
  TUTORIALS → tutorials.qmd
  - YouTube Channel
  - Facebook Community
  - Medium Articles
  - Blog Tutorials

Services dropdown:
  - Services Overview → services.qmd
  - Portfolio → portfolio.qmd

Products dropdown:
  - Digital Products → digital-products.qmd
  - Merchandise Store → external

File Architecture

pystatrplus-dev-redesign/
├── CLAUDE.md                    ← THIS FILE (project guardrails)
├── _quarto.yml                  ← Main Quarto config
├── index.qmd                    ← Homepage
├── about.qmd                    ← About page
├── blog.qmd                     ← Blog listing
├── services.qmd                 ← Services overview
├── contact.qmd                  ← Contact page
├── courses-upcoming.qmd         ← Course catalog
├── tutorials.qmd                ← Tutorial listing
├── digital-products.qmd         ← Products page
├── portfolio.qmd                ← Portfolio showcase
├── testimonials.qmd             ← Full testimonials
├── shop.qmd                     ← Merchandise
├── support-access-education.qmd ← Education access
├── privacy.qmd / terms.qmd / cookie-policy.qmd
├── scss/
│   ├── styles.css               ← Master stylesheet (326KB)
│   ├── custom.scss              ← SCSS theme for Quarto
│   ├── mobile-core.css          ← Mobile overrides
│   ├── mobile-dropdown.css      ← Mobile nav
│   ├── megamenu.css             ← Desktop dropdown menus
│   ├── hero-reimagined.css      ← Hero section styles
│   ├── pages/                   ← Page-specific CSS
│   │   ├── index.css
│   │   ├── about.css
│   │   ├── blog.css
│   │   ├── article.css
│   │   ├── contact.css
│   │   ├── portfolio.css
│   │   └── ... (one CSS per page)
│   └── components/              ← Component CSS
│       ├── atoch-chat.css
│       ├── cookie-consent.css
│       └── giscus-pystatrplus.css
├── _includes/                   ← HTML includes (footer, navbar, etc.)
├── js/                          ← JavaScript modules
├── images/                      ← All image assets
├── posts/                       ← Blog content
├── data/                        ← JSON data files
└── .skills/                     ← Skills reference files

---

6. Design Patterns — Inspired by Coursera/edX

Course Card Design

Based on Coursera/edX research, every course card must include:

1. Thumbnail image — topic visual (consistent aspect ratio)
2. Course title — H3, linked to course page
3. Duration — e.g., “4 weeks”, “Self-paced”
4. Difficulty level — Beginner / Intermediate / Advanced
5. Category tags — colored pills from brand palette
6. CTA — “Start Learning” or “Learn More”

Trust Elements (Homepage)

• Impact metrics section: learners count, countries, satisfaction rate
• Testimonials with star ratings, names, roles, locations
• Ethics/independence statement
• Social proof via community size

CTA Strategy

• ONE primary CTA per section — clear visual hierarchy
• Primary: Solid gradient button (cyan → blue), white text
• Secondary: Outline button (cyan border), transparent background
• Microcopy beneath CTAs to reduce friction
• CTAs must be thumb-friendly on mobile (48px min height)

Section Design Pattern

[Section Label — small caps, brand cyan]
[Section Title — H2, Poppins bold]
[Section Subtitle — Roboto light, muted text]
[Content grid / cards]
[Section CTA — centered, single action]

---

7. Blog System Standards

Blog Post Front Matter (Required)

---
title: "Descriptive Title in Title Case"
date: YYYY-MM-DD
author: "Author Name"
categories: [Primary, Secondary]
tags: [python, statistics, data-visualization]
description: "150-160 character meta description"
image: featured.png
image-alt: "Descriptive alt text"
---

Blog Card Design

• Square or wide thumbnail
• Category badge (colored pill)
• Title (H3, max 2 lines)
• Excerpt (1-2 sentences)
• Date + reading time
• “Read →” link

Naming Conventions

• Folder: posts/descriptive-slug/
• File: index.qmd inside folder
• Images: featured.png, thumbnail-sq.jpg, thumbnail-wd.jpg
• All lowercase, hyphenated

---

8. Quarto-Specific Rules

Configuration

• Theme: cosmo with scss/custom.scss overrides
• Output: _site/ directory
• TOC: Enabled by default (toc: true, toc-depth: 3)
• Code: code-copy: true, code-overflow: wrap, highlight-style: monokai
• External links: Open in new window with icon
• Smooth scroll: Enabled
• Back-to-top: Enabled

HTML Includes (injected after body)

1. footer-enhancements-v9.html — Custom footer
2. navbar-effects.html — Navbar animations
3. mobile-dropdown.html — Mobile menu
4. cookie-consent.html — Cookie banner
5. atoch-chat.html — Chat widget
6. megamenu-enhancements.html — Desktop dropdowns

CSS Loading Order

All CSS files are loaded via _quarto.yml → format.html.css. Page-specific CSS follows global styles. Do not duplicate style declarations across files.

---

9. Deployment & Build

• Host: Netlify
• Build command: Quarto render (via netlify-plugin-quarto)
• Output directory: _site
• Python version: 3.14.0 (see .python-version)
• Git: All changes committed to repository
• robots.txt: Present at root
• sitemap.xml: Present at root — update when adding new pages

---

10. Quality Checklist — Before Every Deploy

SEO

• Every page has unique pagetitle (50-60 chars)
• Every page has unique description (120-160 chars)
• Every page has canonical URL
• Every page has Open Graph + Twitter Card meta
• JSON-LD structured data present on key pages
• All images have alt text
• Heading hierarchy is correct (one H1, proper nesting)
• Internal links use descriptive anchor text
• sitemap.xml is current

Mobile

• No horizontal scroll at any breakpoint
• Touch targets ≥ 48px
• Text readable without zooming (≥ 16px)
• Images scale properly
• Navigation works on mobile
• Forms usable on small screens

Brand

• Only approved brand colors used
• Poppins for headings, Roboto for body
• Consistent button styles (primary/secondary)
• No unauthorized emoji in formal sections
• Footer matches brand template
• Favicon present

Performance

• Images optimized (WebP preferred, < 500KB)
• Lazy loading on below-fold images
• No render-blocking resources
• CSS is not duplicated across files

Accessibility

• Color contrast passes WCAG AA
• Keyboard navigation works
• Screen reader compatible
• Skip-to-content link present
• Reduced motion respected