A learning website built for people who found existing Qiskit tutorials too abstract. Every concept starts with a widget you can drag, click, or animate. The math arrives after the intuition.
Live site: https://catomakyto.github.io/quantum/
Target audience: curious beginners — younger learners and anyone without a deep math/physics background.
32 lessons across 9 modules — the full quantum computing curriculum, from classical warmup to fault-tolerant hardware.
| # | Module | Lessons |
|---|---|---|
| 1 | Foundations | Bits & probability · Just enough complex numbers · Vectors & superposition |
| 2 | The Qubit | Meet the qubit · The Bloch sphere · Measurement & Born rule · Global vs relative phase |
| 3 | Single-qubit gates | Pauli gates · Hadamard · Phase gates (S, T) · Rotation gates · Universal single-qubit |
| 4 | Multi-qubit systems | Tensor products · Product vs entangled · CNOT/CZ/SWAP · Bell states |
| 5 | Entanglement | Bell's inequality (CHSH game) · Monogamy & no-cloning |
| 6 | Quantum protocols | Superdense coding · Quantum teleportation |
| 7 | Algorithms | Deutsch-Jozsa · Bernstein-Vazirani · Simon · Grover · QFT · Shor · VQE/QAOA |
| 8 | Noise & error correction | Decoherence · Repetition code · Shor/Steane · Surface code |
| 9 | Physical implementations | Tour of the hardware |
20 interactive widgets — including a draggable Bloch sphere, a CHSH-game Bell-inequality demonstrator, a step-through quantum teleportation lab, a Grover's search iteration visualizer, a 3-qubit repetition code simulator, and more.
A hand-rolled TypeScript quantum simulator with 63 passing unit tests. No Qiskit or math.js — just Complex, StateVector, and gate matrices built from the ground up. Read it as a learning resource in src/lib/quantum/.
- Astro 5 + React 18 + MDX — content-heavy site with islands architecture
- react-three-fiber + drei — 3D Bloch sphere and multi-qubit visuals
- Tailwind CSS — modern & minimal cream + ink + deep-teal theme
- KaTeX — math rendering
- Vitest — quantum library tests
- GitHub Actions — test + build + deploy to Pages on every push
Requires Node 22+.
npm install
npm run dev # http://localhost:4321/quantum/
npm run build # static export to dist/
npm run preview # serve the production build
npm test # run the 63 quantum library tests
npm run typecheck # astro check + tsc --noEmitBase path is /quantum in both dev and production so that local URLs match the deployed site.
src/
├── content/lessons/ # MDX lessons, one subdirectory per module
├── data/curriculum.ts # source of truth for the module/lesson hierarchy
├── lib/
│ ├── quantum/ # Complex, StateVector, gates, circuit + 63 tests
│ ├── utils/url.ts # base-path-aware link helper
│ └── progress/ # localStorage pub/sub
├── components/
│ ├── viz/ # BlochSphere, StateVectorDisplay, ProbabilityBar, etc.
│ ├── pedagogy/ # Flashcard, CHSHGameLab, TeleportationLab, GroverLab, etc.
│ ├── curriculum/ # ModuleCard, CurriculumMap
│ └── layout/ # Header, Footer
├── layouts/ # BaseLayout, LessonLayout
├── pages/ # landing, curriculum, about, /lessons/[slug], /explore/*
└── styles/global.css # tailwind directives + cream theme + lesson prose styling
These are the design rules every lesson follows:
- See it before you calculate with it. Every abstract concept gets a widget before it gets a formula.
- Classical probability must precede the Born rule. The #1 misconception in QC education is conflating amplitudes with probabilities. Lesson 1.1 sets up the trap; Lesson 2.3 springs it.
- Complex numbers must precede phase. Learners bounce off S/T gates otherwise.
- Measurement must precede multi-qubit. Entanglement before measurement is gibberish.
- Tensor products must precede CNOT. Otherwise CNOT is a mystery box that sometimes flips things.
- Do not lead with Dirac notation. Start with column vectors; introduce
|·⟩as shorthand by lesson 3. - One great lesson beats ten mediocre ones.
There's a CLAUDE.md at the repo root with agent-specific guidance: how to add lessons, common gotchas (MDX hydration, R3F SSR quirks, base path handling), visual conventions, and what not to do. Read it before touching anything meaningful.
This site stands on the shoulders of:
- Quantum Country (Nielsen & Matuschak) — proved spaced repetition + rigorous content can teach QC that sticks
- Quirk (Craig Gidney) — the gold standard for hands-on circuit building
- Brilliant.org — bite-sized, interactive, gamified lessons
- Bartosz Ciechanowski's blog — the definitive reference for how interactive technical explanations should feel
TBD.