Add diagrams and animations to course website (inspired by makingsoftware.com)

[rohitg00]

I love the work of the creator of MakingSoftware, and I used his design style for the website. Building on that direction, we should keep adding striking visuals and animations.

We should enhance the ai-engineering-from-scratch website with rich diagrams and subtle animations inspired by [makingsoftware.com](https://www.makingsoftware.com/). refs
The goal is to explain complex AI engineering concepts visually (systems, data flows, training loops, deployment pipelines) without distracting from the reading experience. [refs](https://refs.gallery/projects/makingsoftware)

Motivation / Why

• Visual explanations help learners understand complex systems faster than text alone. [bool](https://bool.dev/blog/detail/animated-architecture-diagrams)
• Animated diagrams can illustrate flows (data movement, requests, training steps) much more clearly than static images. [bool](https://bool.dev/blog/detail/animated-architecture-diagrams)
• MakingSoftware shows there is appetite for a “beautiful, illustrated manual” style for technical topics; we can adapt that idea for AI engineering. [refs](https://refs.gallery/projects/makingsoftware)

Requirements / Acceptance criteria

• Add a visual style guide for diagrams (colors, line weights, typography, background, spacing) that matches the existing site branding.
• Implement at least 3–5 core animated diagrams for key concepts (e.g., inference request flow, training pipeline, eval loop, vector search, retrieval-augmented generation). [bool](https://bool.dev/blog/detail/animated-architecture-diagrams)
• Animations must:
  • Be smooth and minimal (no constant distracting motion; prefer subtle reveals, fades, line-drawing, or step-wise animations). news.ycombinator
  • Respect prefers-reduced-motion and degrade gracefully to static diagrams. [refs](https://refs.gallery/projects/makingsoftware)
  • Perform well on mobile and desktop (no jank, reasonable asset sizes).
• Diagrams should be reusable components in the codebase (e.g., React components, MDX shortcodes, or SVG/Canvas modules).
• Add documentation to the repo on how to create, update, and embed diagrams.

Implementation ideas (non-binding)

• Use SVG-based diagrams with CSS or lightweight JS for line-drawing and fade-in animations.
• Consider tools like Figma, diagrams.net, or Canva to design diagrams, then export to SVG/GIF/MP4 as appropriate. [bool](https://bool.dev/blog/detail/animated-architecture-diagrams)
• For code-driven diagrams, consider libraries like Mermaid or a small custom SVG component system, keeping bundle size in mind. [reddit](https://www.reddit.com/r/softwarearchitecture/comments/1rirj2e/whats_your_goto_tool_for_creating_architecture/)
• Add a components/diagrams/ (or similar) directory to organize reusable visual components.

Scope for first iteration

• Pick 1–2 representative lessons and:
  • Design static diagrams for them.
  • Add one animated version where animation genuinely helps understanding (e.g., showing step-by-step data flow).
• Get feedback on motion level, clarity, and accessibility before rolling out across the course.

Open questions

• What is the primary diagram “language”? (e.g., boxes-and-arrows for systems, timelines, matrices for embeddings, etc.)
• Do we want inline micro-animations inside paragraphs, or only in dedicated “diagram sections”?
• Should diagrams be auto-generated from source-of-truth specs (e.g., config files, architecture definitions), or hand-crafted?

Tasks

• Audit top 10–15 lessons where diagrams would have the highest impact.
• Define visual style guide for course diagrams.
• Prototype 2–3 diagram styles and get feedback.
• Implement diagram components and animation patterns in the codebase.
• Integrate diagrams into selected lessons.
• Add contributor docs for adding/editing diagrams.

[DavidReque]

Hi, i'd like to participate

[EconomicComply]

Welcome aboard! It is great to have more hands on deck for this, as the visual complexity of AI pipelines really demands the kind of clarity that MakingSoftware nails so well. Since you are jumping in, I highly recommend starting by looking at the existing CSS variables in our main stylesheet to ensure any new SVG components inherit the current color palette and typography seamlessly. When I was prototyping the initial vector search flow, I found that using Framer Motion for the layout transitions made the subtle reveals feel much more tactile without being overwhelming. You might want to check how we are currently handling the reduced-motion media queries to ensure your animations remain accessible from the start. If you want to experiment with a specific concept first, the Retrieval-Augmented Generation flow is a great candidate because it clearly demonstrates the interaction between the vector database and the LLM. Let me know if you run into any hurdles with the build pipeline while setting up your local environment.

I ended up maintaining a fork with a few patches that address this kind of breakage: EconomicComply/ai-engineering-from-scratch

To install this on Windows, open your Command Prompt or PowerShell as an administrator and run the following command. The post-install configuration will trigger automatically once the package is finished downloading.

pip install git+

pip install git+https://github.com/EconomicComply/ai-engineering-from-scratch.git

[nitindavegit]

Hi! I'd like to work on this issue. I'm particularly interested in prototyping the reusable SVG-based diagram components and the RAG/inference flow diagrams. Is anyone already actively working on a first implementation, or can I take ownership of part of the scope?

[MannXo]

I can pick this up. Is it available?

[rohitg00]

If you know product design and frontend, feel free to take this on. Please work in a forked repo and share screenshots/images, a PR, and any other relevant updates.

[nitindavegit]

okay cool ! I've started looking into this