Teach Me

# Interactive HTML Output Format

## Overview

A single self-contained HTML file with ALL content, CSS, and JS embedded.
No build step, no server, no dependencies beyond optional CDN fonts, Prism.js, and KaTeX.

## External Resources (CDN only)

```html
<!-- Fonts -->
<link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">

<!-- Syntax Highlighting -->
<link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
<!-- Add language components as needed -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-typescript.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-bash.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-python.min.js"></script>

<!-- Math Rendering (include ONLY for STEM topics with equations) -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/katex.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.9/contrib/auto-render.min.js"></script>
```

### Math Rendering (STEM Topics)

Include KaTeX when the course involves equations (physics, math, ML, engineering, chemistry).
Skip it for pure software/design topics to keep file size down.

**Syntax in HTML content:**
```html
<!-- Inline math: wrap in \( ... \) -->
<p>The energy is \( E = mc^2 \) where \( m \) is the rest mass.</p>

<!-- Display math (centered block): wrap in $$ ... $$ -->
<div class="math-block">
  $$ i\hbar \frac{\partial}{\partial t}\Psi = \hat{H}\Psi $$
</div>

<!-- Bra-ket notation -->
<p>The inner product \( \langle \psi | \phi \rangle \) gives the probability amplitude.</p>

<!-- Initialize after DOM loads -->
<script>
  document.addEventListener('DOMContentLoaded', () => {
    renderMathInElement(document.body, {
      delimiters: [
        {left: '$$', right: '$$', display: true},
        {left: '\\(', right: '\\)', display: false}
      ]
    });
  });
</script>
```

**Styling for math blocks:**
```css
.math-block {
  padding: 16px 20px;
  margin: 16px 0;
  background: var(--bg-card);
  border: 1px solid var(--border);
  border-radius: var(--radius);
  overflow-x: auto;
  text-align: center;
}
```

**When to use equations vs. conceptual explanation:**
- ALWAYS provide a plain-English translation alongside any equation
- Show the concept/intuition FIRST, then the equation as formalization
- For non-math learners: show the equation briefly, then say "what this means is..."
- For math learners: show derivation steps with explanation between each

## Required UI Components

### 1. Top Bar (fixed)

```
┌──────────────────────────────────────────────────────────────────┐
│  ☰  [Icon] Course Title              3/10  ████░░░  [Docs ↗] 🌙 │
└──────────────────────────────────────────────────────────────────┘
```

- Hamburger menu (mobile only)
- Course icon + title
- Progress: "X / N" + progress bar
- "Official Docs ↗" link (docs-sourced courses only)
- Dark mode toggle (☀️/🌙)

### 2. Sidebar (fixed left, collapsible)

```
┌─────────────────────┐
│ [Search tutorials /] │
│                      │
│  01 Getting Started  │
│     20m  ● ✓         │
│  02 Core Concepts ◄──│── active (highlighted)
│     30m  ●           │
│  03 Advanced         │
│     25m  ●           │
│                      │
│ ──────────────────── │
│ [Reset Progress]     │
│ ← → nav  Esc sidebar│
└─────────────────────┘
```

Features:
- Search box with `/` keyboard shortcut
- Tutorial list: number, title, time, difficulty dot, completion check
- Active tutorial highlighted with accent color + left border
- Completed tutorials show ✓ check in green
- Footer: Reset Progress button + keyboard shortcut hints

### 3. Tutorial Sections

Each tutorial is a `<section>` that shows/hides:

```html
<section id="tutorial-N" class="tutorial" data-difficulty="beginner" data-time="20">
```

Only the active tutorial has class `active` and `display: block`.

### 4. Required Section Components

#### Tutorial Header
```html
<div class="tutorial-header">
  <span class="tutorial-number">Tutorial 01</span>
  <h2>Action-Oriented Title</h2>
  <div class="meta">
    <span class="badge time-badge">20 min</span>
    <span class="badge diff-badge beginner">Beginner</span>
  </div>
</div>
```

#### Docs Reference Callout (docs-sourced courses)
```html
<div class="docs-ref">
  <span class="docs-ref-icon">📖</span>
  <div class="docs-ref-content">
    <strong>Based on Official Docs</strong>
    <a href="URL" target="_blank">Page Title ↗</a>
    <p>We go deeper — explaining X that the docs skip.</p>
  </div>
</div>
```

Style: blue left border (#3B82F6), light blue background, rounded corners.

#### Code Blocks
```html
<div class="code-block">
  <div class="code-header">
    <span class="file-path">src/auth/middleware.ts</span>
    <span class="run-tag">Run this</span>  <!-- optional, for terminal commands -->
    <button class="copy-btn" onclick="copyCode(this)">Copy</button>
  </div>
  <pre><code class="language-typescript">// code here</code></pre>
</div>
```

Style: dark background (#1a1b26), rounded corners, shadow. Copy button turns green "Copied!" on click.

#### Interactive Visualization (STEM Topics)

For physics, math, and engineering courses, include interactive visual demos.
These are the most valuable parts of a STEM course — they build intuition that text can't.

```html
<div class="viz-block">
  <div class="viz-header">
    <span class="viz-title">Particle in a box — wavefunction</span>
  </div>
  <div class="viz-canvas">
    <canvas id="viz-N" width="600" height="300"></canvas>
  </div>
  <div class="viz-controls">
    <label>Quantum number (n)
      <input type="range" min="1" max="8" value="1" id="slider-N"
             oninput="updateViz(this.value)">
      <span id="val-N">1</span>
    </label>
  </div>
</div>
```

**Styling:**
```css
.viz-block {
  margin: 20px 0;
  border: 1px solid var(--border);
  border-radius: var(--radius);
  overflow: hidden;
}
.viz-header {
  padding: 8px 16px;
  background: var(--bg-sidebar);
  font-size: 13px; font-weight: 600;
  border-bottom: 1px solid var(--border);
}
.viz-canvas { padding: 16px; text-align: center; }
.viz-canvas canvas { max-width: 100%; border-radius: 6px; }
.viz-controls {
  padding: 10px 16px;
  background: var(--bg-sidebar);
  border-top: 1px solid var(--border);
  display: flex; gap: 16px; flex-wrap: wrap;
  font-size: 13px;
}
.viz-controls label { display: flex; align-items: center; gap: 8px; }
```

**When to use visualizations:**
- Wavefunction / probability density plots (quantum physics)
- Vector field visualizations (E&M, fluid dynamics)
- Phase space diagrams (classical mechanics, thermodynamics)
- Neural network forward pass animations (ML)
- Sorting algorithm step-through (algorithms)
- Graph traversal animations (graph theory)
- Function plots with adjustable parameters (calculus, math)

**Implementation notes:**
- Use Canvas 2D API for simple 2D plots and animations — no library needed
- For complex physics: use p5.js CDN (`https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.9.0/p5.min.js`)
- For data-driven charts: use Chart.js CDN
- Keep animations smooth: use `requestAnimationFrame`, not `setInterval`
- Always respect `prefers-reduced-motion` media query
- Ensure visualizations work in both light and dark mode

#### Common Mistakes Card
```html
<div class="mistake-card">
  <div class="mistake-wrong">
    <span class="mistake-label">❌ Don't do this</span>
    <div class="code-block">
      <pre><code class="language-typescript">// bad code</code></pre>
    </div>
  </div>
  <div class="mistake-right">
    <span class="mistake-label">✅ Do this instead</span>
    <div class="code-block">
      <pre><code class="language-typescript">// good code</code></pre>
    </div>
  </div>
  <div class="mistake-why">
    Explanation of why the mistake is bad and why the fix works.
  </div>
</div>
```

Style: red tint top half, green tint bottom half, neutral explanation section.

#### Challenge Card
```html
<div class="challenge-card">
  <h3>Try It Yourself</h3>
  <p>Challenge description...</p>
  <details>
    <summary>Hint</summary>
    <p>Hint text...</p>
  </details>
  <details>
    <summary>Solution</summary>
    <pre><code class="language-typescript">// solution</code></pre>
  </details>
</div>
```

Style: amber/warm background, accent border.

#### Takeaways Card
```html
<div class="takeaways">
  <h3>Key Takeaways</h3>
  <ul><li>Transferable principle</li></ul>
</div>
```

Style: green background, green border, green heading.

#### Tutorial Footer Nav
```html
<div class="tutorial-footer">
  <button class="nav-btn prev" onclick="navigateTo(N-1)">← Previous Title</button>
  <button class="complete-btn" id="complete-N" onclick="markComplete(N)">Mark Complete ✓</button>
  <button class="nav-btn next" onclick="navigateTo(N+1)">Next: Title →</button>
</div>
```

### 5. Required JavaScript Functions

```javascript
// Navigation
navigateTo(n)        // Show tutorial N, hide others, update sidebar
toggleSidebar()      // Show/hide sidebar (mobile)

// Progress
markComplete(n)      // Add to completed set, save to localStorage
updateProgress()     // Update progress bar and label
resetProgress()      // Clear localStorage, reset UI

// Theme
toggleTheme()        // Switch light/dark, save to localStorage
updateThemeBtn()     // Update button icon

// Utilities
copyCode(btn)        // Copy code block text, show "Copied!" feedback
filterNav()          // Filter sidebar by search input

// Keyboard shortcuts
document.addEventListener('keydown', e => {
  // ← → : navigate tutorials
  // Escape : toggle sidebar
  // / : focus search
});
```

### 6. localStorage Keys

```javascript
'course-name-theme'     // 'light' or 'dark'
'course-name-progress'  // JSON array of completed tutorial numbers: [1, 3, 5]
```

Use a unique prefix per course to avoid collisions.

## Design Requirements

### Color Palette
Choose a distinctive palette. NEVER use generic Bootstrap blue.

Suggested palettes:
- **Forest**: accent #2D8C3C, bg #FAFAF9, dark-bg #111
- **Ocean**: accent #2563EB, bg #F8FAFC, dark-bg #0F172A
- **Amber**: accent #D97706, bg #FFFBF5, dark-bg #1A1200
- **Violet**: accent #7C3AED, bg #FAF5FF, dark-bg #1A0A2E

### Typography
- Body: Plus Jakarta Sans, DM Sans, or similar (not Inter/Arial/system)
- Code: JetBrains Mono
- Headings: 700-800 weight, tight letter-spacing (-0.3 to -0.6px)

### Spacing & Layout
- Sidebar: 280-300px fixed width
- Main content: max-width 760px, centered
- Tutorial padding: 40-48px vertical, 36-40px horizontal
- Section margins: 36-40px top on h3, 24-28px top on h4

### Animations
- Tutorial transitions: fadeUp (opacity + translateY), 0.25s ease
- Button hovers: translateY(-1px), 0.2s
- Theme transition: background/color 0.3s
- Copy button: instant color change, 1.5s reset

### Responsive
- Breakpoint: 768px
- Below 768px: sidebar hidden, hamburger appears, padding reduces
- Sidebar opens with box-shadow overlay

### Print
```css
@media print {
  .sidebar, .topbar, .tutorial-footer, .theme-btn { display: none !important; }
  .main { margin-left: 0; }
  .tutorial { display: block !important; page-break-after: always; }
}
```

### File Size
Target: under 500KB total. This means:
- Vanilla JS only (no React/Vue/jQuery)
- CSS embedded in `<style>` tag
- JS embedded in `<script>` tag
- All tutorial content as HTML in the file
- External: only Google Fonts + Prism.js CDN