The original hardening got the structural selectors right, but the
labs/kits/book sidebar still had two divergences from the instructors
reference: (a) section headers and leaf links rendered with the same
muted color (no hierarchy) because the section-header rule only matched
the chevron `<a class="sidebar-item-toggle">` and missed the section
text `<a class="sidebar-link text-start">`, and (b) the active-state
rule colored the text in the accent color rather than white on a subtle
accent tint, so active links read as loud accent fills instead of the
clean instructors look.
Changes per file:
* labs/, kits/: extend section-header selector list to include
`a.sidebar-link.text-start`; drop `font-weight: 400 !important` from
the leaf rule so the section-header weight (600) wins on elements
matching both; move active-state color/background/weight into the
high-specificity `#quarto-sidebar` guard block to beat Bootstrap's
default `.sidebar-link.active { color: var(--bs-primary) }`.
* book/quarto/: same treatment, plus include `.part-divider` in the
section-header selector list to keep the part-divider hierarchy.
* tinytorch/quarto/: same active-state hardening, plus rename
`$accent` → `$accent-dark` throughout (the theme partial
shared/styles/themes/_theme-tinytorch.scss declares both variables;
since Quarto auto-`!default`s every scss:defaults declaration, the
reassignment of `$accent` here was silently ignored and rgba calls
resolved with the light #D4740C value). Drop the unused
`$link-color-dark` definition that referenced `$accent-dark` from
scss:defaults — Quarto hoists user defaults above shared partial
defaults, so `$accent-dark` isn't yet defined when that line runs.
Rules in scss:rules resolve `$accent-dark` correctly because rules
are processed after all defaults are merged.
Verified with Playwright probes on /vol1.html (slides), /index.html
(labs, kits), /big-picture.html (tinytorch), /api-stability.html
(mlsysim), /foundations-syllabus.html (instructors): all six now show
white active text on rgba(accent, 0.15) tint, weight 500, with bright
section headers (#e6e6e6) at weight 600 and muted leaf links (#888888
or #cbd5e1).
Extends PR #1633's instructors fix to the rest of the Quarto ecosystem.
Quarto renders floating sidebars with `<a class="sidebar-link">` and
`<a class="sidebar-item-toggle">` directly (not nested inside an
`.sidebar-item a` wrapper), so the legacy selector missed all real DOM
nodes.
Sites updated:
* slides, interviews, tinytorch/quarto, mlsysim/docs: full hardening
(toggle, leaf-link, active-state, search input, TOC rail).
* labs, kits, book/quarto: added missing search-input theming
(core sidebar and TOC fix already present from earlier work).
Each site's accent color is preserved: indigo for instructors and
interviews, pink for slides, amber for tinytorch, cyan for mlsysim,
teal for kits and labs, crimson for book.
The h3 and pre code rules set near-white colors unconditionally, which
made these elements unreadable in light mode. Gate them on
[data-bs-theme="dark"] so light mode falls back to its own contrast.
Three small but layered fixes that together make every page under the
tito CLI module fully readable in light mode, dark mode, and the hybrid
state where data-bs-theme="dark" stays sticky on <html> while the light
stylesheet is the active bundle.
- Light-fill panel text-color safety net (style.scss). Pairs with the
bg-flip safety net upstream introduced in 2707c0546. The bg-flip only
fires in dark mode; this rule fires in both modes and pins text
inside inline-styled light-fill cards (tito/modules.qmd, tito/data.qmd,
etc.) to #1e293b regardless of what --bs-body-color resolves to.
Without it, cards stayed light-fill in the hybrid state but text
inherited the dark-palette light body color = invisible. The matching
!important `color: #e6e6e6` line in dark-mode.scss flips back when
the card flips to #2d2d2d.
- Code blocks inside cards. The previously-merged
`pre code { color: #e6e6e6 }` rule was painting plain (no-language)
fenced blocks light grey on the light card surface — visible on the
box-drawing console output blocks under "Understanding the Export
Process" on tito/modules.qmd. Nest a `pre code, code` override inside
the safety-net selector list so card code is dark in light/hybrid and
light in true dark mode.
- Scope existing global h3 + pre code overrides to [data-bs-theme="dark"].
Both rules were left unscoped previously to compensate for the hybrid
state. The card safety net above now handles hybrid for cards, so the
global rules can be properly scoped — fixes the "### Milestone
Achievements: `tito milestone status`" h3 on tito/data.qmd which was
rendering #d0d0d0 on white in true light mode.
- Table zebra-stripe override (style.scss). shared/styles/partials/_tables.scss
sets the even-row bg to #fafbfc unconditionally; on the dark body the
light text inheriting from --bs-body-color was invisible against the
light row stripe. Add a [data-bs-theme="dark"]-scoped rule using a
subtle white-overlay rgba so striping survives without hard-coding
a specific dark hue.
Light mode unchanged on every page that doesn't use inline-styled cards.
Map inline 700/600 Material accent text to 400-shade variants for WCAG on
#2d2d2d surfaces; add linear-gradient(e3f2fd...) panel rule missed by
solid background hex selectors.
Three small follow-ups on top of the recent dark-mode UX work
(#1529 / #1532-style fixes already on dev):
- _quarto.yml: split `highlight-style: github` into
`light: github` / `dark: github-dark` so code blocks pick up
proper dark theme tokens instead of the light theme over a
dark surface.
- style.scss: pin .who-card paragraphs to #475569 (slate-500)
so they stay readable on the #fafafa card surface even when
the page is in the hybrid state where data-bs-theme="dark"
is set on <html> but the light stylesheet is active — body
color flips to #dee2e6 in that case and inheriting it
invisibly bleached the cards. Also add the global
`#quarto-content h3 { color: #d0d0d0 !important }` and
`pre code { color: #e6e6e6 }` overrides so subheadings and
code text remain readable in dark mode (h3 here is needed
because Quarto re-loads the light bundle as
quarto-color-scheme-extra after the dark bundle, so equal-
specificity rules from _headers.scss otherwise win).
- dark-mode.scss: pair the .who-card paragraph fix above —
when the card flips to #2d2d2d in dark mode, paragraphs
go to #e6e6e6 to match.
Quarto's default styles set
div.sourceCode { background: rgba(233, 236, 239, 0.65) }
on every code block — a LIGHT fill at 65% opacity. Over the dark body
(#1a1a1a) that blends to a washed-out medium grey (~#a0a0a0) which
fights the syntax-highlighted foreground and makes code hard to read.
Override in dark-mode.scss with an explicit dark surface slightly
lighter than the body so blocks read as distinct rectangles, plus a
1px border using $border-color-dark for clean delineation.
Inline code (`tinytorch/`-style spans in prose) had the same washed-grey
problem from the same rgba-light pattern. Switched to a translucent
slate (rgba(110, 118, 129, 0.35)) with light text (#e6edf3) — keeps it
visually distinct from surrounding prose without competing with full
code blocks.
Verified locally on getting-started.html (the page with the most
visible code blocks). Computed bg now rgb(34, 38, 44) = #22262c with
border #454d55, body bg unchanged at #1a1a1a.
Adds a small amber pill below the existing "A Build-It-Yourself
Companion to..." subtitle showing "🔥 TinyTorch v0.1.10 →", linked to
the GitHub Releases page filtered for tinytorch tags.
Why: the previous sidebar had no persistent version indicator, and
the announcement-bar approach was rejected (see config/announcement.yml
header note: "Release news belongs in a changelog, not in the always-
visible nav bar"). The sidebar subtitle area is the natural home for
this kind of meta-info — sticky on desktop, not competing with content,
and follows the existing JS injection pattern.
Design choices:
- "🔥 TinyTorch" prefix + visual divider above the pill prevent the
reader from parsing "v0.1.10" as the textbook's version (which
would be wrong — the textbook is versioned by Volume).
- Amber border + amber text + faint amber background match the
TinyTorch brand color used throughout the announcement bar and
accent system.
- target="_blank" + rel="noopener" — the chip leaves the docs site,
so external-link semantics apply.
- !important on color rules because Quarto's link styles otherwise
win at higher specificity (matches the existing `.sidebar-subtitle
a:hover` pattern in this file).
Version source: hardcoded as "v0.1.10" with a TINYTORCH_VERSION_CHIP
sed marker. The tinytorch-publish-live workflow's UPDATE_VERSION step
already syncs 6 files (pyproject.toml, settings.ini, install.sh,
announcement, README badge, init); adding this file to that step is
a follow-up. For now, manual updates on each release.
Verified in Playwright on index + tito/milestones, light + dark mode.
Computed color rgb(212, 116, 12) light / rgb(245, 158, 11) dark; href
points to releases?q=tinytorch as intended.
#1529 fixed dark-mode contrast on preface.qmd by refactoring inline
style="background: #..." panels to .who-card / .callout-note. The
remaining 200+ inline-styled panels across other pages (big-picture,
index, tito/*, datasets, etc.) were still failing in dark mode — the
fix worked for one page but the user-visible experience was patchwork.
Two structural gaps closed:
1. Sidebar had zero dark-mode coverage. dark-mode.scss declared
$sidebar-bg-dark = #212529 but never applied it to a selector,
and shared/styles/partials/_sidebar.scss hardcodes #495057 link
text against an implicit white surface. Result: white sidebar
visible on every page in dark mode. Fixed by adding rules for
#quarto-sidebar, .sidebar-navigation, sidebar items, section
headers, and dividers — uses the existing $sidebar-bg-dark and
$border-color-dark variables instead of leaving them dead.
2. Inline-style panels site-wide. Cataloged the 14 light-fill hex
values that appear with `background: #X` across the .qmd corpus
(counts in the SCSS comments) and added a [style*=...] attribute
selector layer that flips them to #2d2d2d in dark mode, plus the
8 mid/dark-grey text colors used inline that fail when their
surface flips. !important is required because inline style= beats
class specificity. Decorative dark/saturated fills (#263238,
#0f172a, button blues/oranges, gradient banners) are deliberately
excluded — they render correctly in both modes.
Plus: thin 1px border on .who-card in dark mode for delineation
against the body bg ($body-bg-dark = #1a1a1a vs card #2d2d2d).
Verified across index, big-picture, and tito/milestones in Playwright
with colorScheme: 'dark' (uses Quarto's prefers-color-scheme initial
toggle path, not just data-bs-theme attribute setting). All measured
contrast ratios >= 11.0 WCAG AA. The defensive layer is a transitional
bridge — long-term, individual pages should be refactored to .who-card
/ .callout-note like preface and tito/milestones already are.
Welcome page and several adjacent surfaces had dark-on-dark text in dark
mode after the v0.1.10 release. Two root causes:
1. preface.qmd used inline `style="background: #..."` divs for the
"Why does this matter?" callout, the MLSysBook/TinyTorch comparison,
and the "Who This Is For" persona grid. Inline styles beat CSS
class specificity, so dark-mode rules were ignored.
2. dark-mode.scss had no overrides for several components defined in
style.scss with hardcoded light colors: .comparison-title, the
.tier-{foundation,architecture,optimization,olympics} cards, the
.milestone-card family, .ml-timeline-tech, .preview-badge, and the
callout-body / callout-content text-color cascade.
Changes:
- Refactor the three preface.qmd blocks to use existing .callout-note
and .who-card / .who-grid classes (kept colored left-borders inline
since they are mode-invariant accents).
- Append dark-mode rules covering every selector identified above.
Mirrors the .callout-body !important cascade pattern from
shared/styles/_ecosystem-base-dark.scss:577-584.
PDF branches (when-format="pdf") untouched. Light mode unchanged.
Two related fixes that landed together during a UX walkthrough.
1. H2–H6 decoration override was dropped in a merge conflict.
PR #1524 added an override in tinytorch/quarto/assets/styles/style.scss
that stripped the shared /partials/_headers.scss L-shape decoration
(thick accent left-border + thin accent bottom line) from H2–H6 on
TinyTorch only. The override disappeared at some point between that
merge and today — every H3 on a TinyTorch page is currently rendering
with `border-left: 4px solid #d4740c` + `border-bottom: 1px solid
rgba(212, 116, 12, .25)`. Restoring the override with `!important`
so it survives future shared-partial additions. Scoped to TinyTorch;
book/kits/labs/mlsysim keep their decoration.
2. Comparison-grid "Traditional ML Education" / "TinyTorch: Build →
Use → Reflect" titles converted from H3 to a styled <span>.
Problem: H3 at 24.65px with the accent L-shape reads as a page
heading jammed into a card — awkward scale, awkward hierarchy
(the whole card IS the content; the title isn't a separate
sub-section). Solution: use a `.comparison-title` span class
at 1.15rem (~18.4px), 600 weight, no border — properly card-
scaled, and no heading semantics pollute the doc outline / TOC.
Markup changed from `### Title {.unnumbered}` to
`[Title]{.comparison-title}`.
Verified via Playwright on `http://localhost:4123/`:
- No H3 exists inside `.comparison-bad` / `.comparison-good` now.
- New `.comparison-title` span renders at `font-size: 19.55px`,
`border-left: 0`, `border-bottom: 0`.
- Applied screenshot: /tmp/banner-work/compare-fixed.png shows the
card titles as clean bold text, no underline, no accent bar.
Font audit (same walk): body Inter 17px/25.5px, H1 42.5px/700,
H2 28.05px/600, H3 24.65px/600, code JetBrains-Mono 14.9px, sidebar
15.7px, TOC 15.3px. All consistent with the ecosystem font stack and
reasonable in isolation — no additional font changes needed.
Round-2 UX polish pass after a full Playwright walkthrough surfaced a few
cheap, high-impact wins. Scoped to three files.
HOME (index.qmd)
- Hero hierarchy swap. The prior markup rendered a 2.5rem <p> "Build
Your Own ML Framework" followed by an <h2> "Don't import it.
Build it." — which flipped the semantic hierarchy: the tagline
subtitle read as the most important element, and the memorable
slogan (which matches the pagetitle) read as secondary.
Fix: "Don't import it. Build it." is now the page's h1; "Build your
own ML framework — from tensors to systems." is the subtitle below
it. Screen readers, search engines, and the eye all agree now.
- Preview badge: "Classroom ready 2026" -> "Classroom ready Fall 2026".
The date is now unambiguous (we're in 2026; old copy read as "not
yet shipped in 2026" or "already shipped in 2026" depending on
reader).
- Star-count CTA copy: was "⭐ 23,763 learners · every ⭐ helps
support free ML education". Problem: the dynamic number is the
GitHub stars count, not a learner count — conflating the two is
misleading. Rewrite: "⭐ 23,763 stars on GitHub — add yours and
support free ML education". Concrete number, concrete verb, honest.
MILESTONES HUB (milestones/index.qmd)
- Add a six-card roster at the top showing 1958 -> 2018 at a glance
(Perceptron, XOR Crisis, MLP Revival, CNN Revolution, Transformers,
MLPerf). Previously the hub opened with two prose paragraphs before
the journey table; a first-time reader had to scroll past them to
see the milestone list. The 6-card grid makes the arc instantly
legible; the detailed per-milestone journey table stays in place
further down for the reader who wants module-by-module dependencies.
- Cards are links, each to the milestone's own page.
- Color coding mirrors the tier that produces the milestone's modules:
Foundation (blue), Architecture (purple), Optimization (orange).
CSS (tinytorch/quarto/assets/styles/style.scss)
- New .milestone-grid + .milestone-card classes, styled to match the
preface audience-card aesthetic shipped in the previous polish PR
(neutral #fafafa fill, colored left-border carrying the tier
identity). Responsive: 3-col desktop, 2-col tablet, 1-col mobile.
- data-era="{foundation|architecture|optimization}" attribute on each
card drives the border-left color via the attribute selector, so
the era -> color mapping stays declarative and doesn't need per-card
inline style.
Verified (Playwright against local quarto preview):
- Home h1 is now "Don't import it. Build it." at 42.5px; badge reads
"Preview · Classroom ready Fall 2026"; star link reads "⭐ {N}
stars on GitHub — add yours and support free ML education"
- Milestones hub renders the 6-card grid with correct data-era colors
(foundation = rgb(25, 118, 210), architecture = rgb(123, 31, 162),
optimization = rgb(245, 124, 0)).
Deferred — acknowledged as valid observations in the UX walkthrough but
out of scope for this PR:
- Swap module-page action cards above Module Info (touches ~20 module
files; wants a template-level change, not ad-hoc QMD rewrites).
- Sticky per-module progress indicator (wants JS + scroll listener).
- Announcement-bar collapse on narrow viewport (JS + cross-site).
- Olympics "Coming Soon" -> dated promise (intentionally left alone:
the real Olympics launch content is landing in a separate PR in
the next few days).
cards + header decoration + PDF milestone transitions
Polishes several rough edges in the TinyTorch site surfaced by a visual
walkthrough. Six independent fixes in one PR because they all landed on
the same mental pass:
HTML SIDEBAR
- Rename two sections so their titles don't wrap on the 250px sidebar:
"Capstone Competition" -> "Capstone"
"TITO CLI Reference" -> "TITO CLI"
(navbar link "TITO CLI Reference" -> "TITO CLI" too, for
consistency)
- Remove all three milestone sections ("Foundation Milestones",
"Architecture Milestones", "Optimization Milestones") from the HTML
sidebar. They interleaved between tiers and broke the
Foundation -> Architecture -> Optimization -> Capstone flow the
sidebar is meant to communicate. Milestones stay fully accessible
via the navbar's "Historical Milestones" entry, and the PDF build
(which has its own _quarto.yml) is untouched -- interleaved
milestones are the correct reading experience in print.
- YAML comment added where the milestone sections used to live so a
future contributor knows the removal was intentional.
SIDEBAR SCROLL
- shared/styles/partials/_sidebar.scss: add
`overscroll-behavior: contain` to #quarto-sidebar and
.sidebar-navigation. Before: hovering-and-scrolling over the sidebar
chained the scroll to the body the moment the sidebar hit a
boundary -- so scrolling the sidebar felt like it was never actually
engaging. After: the sidebar's scroll stays in the sidebar.
- Single-source-of-truth win: this improves every Quarto site in the
ecosystem (book/kits/labs/mlsysim/tinytorch/site), not just tinytorch.
H2 L-SHAPE DECORATION (TINYTORCH ONLY)
- shared/styles/partials/_headers.scss decorates H2-H6 with a thick
accent left-border + thin accent bottom line -- an "L-shape" that
reads well in long-form textbook prose. For tinytorch (framework
docs with code blocks, comparison grids, card-based layouts) the
decoration felt heavy and competed with the content itself.
- tinytorch/quarto/assets/styles/style.scss: add a local override
that strips border-left/border-bottom/padding-left/padding-bottom
from H2-H6. Scoped to tinytorch -- book/kits/labs/mlsysim keep the
decoration.
TIER CARDS
- index.qmd's .tier-foundation / .tier-architecture /
.tier-optimization / .tier-olympics cards used four different
gradient fills (blue/purple/orange/pink). Visually loud; fought
the comparison grid and hero on the same page; tier-optimization
read as specifically orange-heavy.
- Flatten to the same neutral #fafafa fill the .audience-card and
preface.qmd cards use, with just a 4px colored left-border carrying
the tier's identity. Each tier still has its distinct color cue;
the page calms down.
PDF NARRATIVE TRANSITIONS
Milestones appeared suddenly in the PDF when a tier ended. Readers
lost context for why they were there and which just-built modules
they were about to exercise. Six short transition paragraphs added
via the narrative-flow-analyzer subagent:
modules/08_training.qmd forward-hook into Foundation Milestones
modules/13_transformers.qmd forward-hook into Architecture Milestones
modules/19_benchmarking.qmd forward-hook into Optimization Milestone
milestones/01_perceptron.qmd tier-components open
(Tensor/Linear/BCELoss/SGD/Trainer)
milestones/04_cnn.qmd first-Architecture-Milestone framing +
three-tier arc explanation
milestones/06_mlperf.qmd sole-Optimization-Milestone +
"third act" framing
Files left as-is because the transitions were already good:
milestones/index.qmd, milestones/02_xor.qmd, milestones/03_mlp.qmd,
milestones/05_transformer.qmd.
DRIVE-BY FIX
modules/13_transformers.qmd had four lines of pre-existing corrupted
trailing content after the last callout (duplicate sentence,
orphan "44B parameters |" table row, orphan Capstone row). Removed
since this PR was already editing the file.
Verification (Playwright against local preview):
- Sidebar section labels: ["Getting Started", "Foundation Tier",
"Architecture Tier", "Optimization Tier", "Capstone",
"Conclusion", "TITO CLI", "Reference", "Community"] -- no
wrapping, no milestones.
- #quarto-sidebar overscroll-behavior: "contain"
- H2 "Don't import it. Build it." computed border-left-width: 0px,
border-bottom-width: 0px, padding-left: 0px
- .tier-card backgrounds: all rgb(250, 250, 250);
border-lefts: 4px solid {tier-color} each.
Wave 4 editorial content across 20 modules + new glossary back matter:
1. Module opener hooks (20 new 2-3 sentence paragraphs between the
chapter heading and Module Info callout). Every hook LEADS with
the systems angle (memory, bandwidth, arithmetic intensity,
cache, HBM, roofline, KV cache, hardware utilization, etc.) and
connects back to the ML story. Reinforces that this is a lab
guide for ML systems, not an ML-theory textbook.
2. Code-listing captions on substantive code blocks (roughly >10
lines, defines a class/function/algorithm). Populates Quarto's
List of Listings front matter. Combined across F1/F2/L/O
subagent waves: roughly 60 listings now carry
'**Listing N.M — Brief description**' captions.
3. Figure alt-text audit across 20 module diagrams. Most already
carried objective specific alt-text; a handful were rewritten
for precision.
4. Glossary at back matter (tinytorch/quarto/glossary.qmd + registered
in pdf/_quarto.yml). 90 alphabetical entries spanning tensor /
memory / autograd / training / architecture / optimization
terms. One-sentence definitions. Module cross-references where
the term is central. Lab-guide voice, not dictionary.
5. Style discipline: no em-dashes in prose (caption templates
'— Description' are the only exception, required by parser).
All agent outputs and the hand-revised hooks audited for em-dash
use.
6. SVG trailing-newline hygiene: 8 SVGs touched by the Gemini style
audit had lost their trailing newline. Restored per the SVG
file-hygiene rule.
Bring the six lab-guide-style SVGs introduced in 8928562e6 into visual
parity with the 57f9abed5 diagram polish:
- soften primary strokes from #555 to #bbb on all box borders and
arrow paths
- soften arrow marker fills from #555 to #bbb
- remove the opaque white background rect so the figures inherit the
page background (fixes dark-mode rendering)
- consolidate the arrow / arrow-muted markers in tito-module-workflow
(the dashed stroke alone carries the "secondary" signal)
Orange accent (#fdebd0 / #c87b2a) on the focal element and the MIT red
pills (#a31f34) for year / achievement badges are preserved. Text
colors and geometry unchanged.
Apply a consistent polish pass across all 22 module diag SVGs and the
two site-wide overview SVGs (big-picture-module-flow,
modules-transformer-gpt-architecture):
- soften primary strokes from #555 to #bbb so diagram linework reads
as structural guides rather than bold borders
- soften arrow marker fills from #555 to #bbb to match the lighter
stroke weight
- remove the opaque <rect fill="#ffffff"/> background so SVGs render
correctly in both light and dark page contexts
- narrow the canvas (viewBox 680 -> 640 where applicable) and adjust
the group transform to remove excess whitespace around content
Net effect: every figure in the lab guide and the website reads lighter
and breathier, matching the minimalist neutral + single-accent
convention without losing any semantic detail.
Convert the six remaining mermaid code fences across the tier overviews
(foundation, architecture, optimization) and tito developer pages
(modules, data, testing) into hand-authored SVGs that match the
minimalist convention used by the PDF lab-guide module diagrams:
- neutral #f7f7f7 fill + #555 stroke for all boxes
- one #fdebd0 / #c87b2a orange accent per figure marking the focal
element (essential command, pivot step, destructive action, or
deployable artifact)
- #a31f34 MIT red pills reserved for year and achievement badges
- panel header top-left at 12pt; fig-cap carries the long-form title
- stroke-width 1.2 throughout; typography 12 / 10 / 9 pt
Figures introduced:
- tito-module-workflow.svg (5-step build/export/test cycle)
- tito-progress-tracking.svg (6-step progress flow)
- tito-test-hierarchy.svg (7-level test stack)
- tiers-foundation-milestones.svg (1958 / 1969 / 1986)
- tiers-architecture-milestones.svg (1998 / 2017)
- tiers-optimization-milestones.svg (baseline -> MLPerf)
Why: the deployed site rendered mermaid timelines and flowcharts as
"syntax error in text" bombs on several pages (foundation, big-picture,
etc.). Switching to hand-authored SVGs embedded via the standard Quarto
figure-div pattern (::: {#fig-... fig-env=figure ...}) centers the
figures correctly, supplies proper fig-cap / fig-alt, and routes
through the existing svg-to-pdf.lua filter for HTML + PDF parity.
The minimalist two-tone palette (neutral + single accent) mirrors the
22 module diagrams in assets/images/diagrams/, giving the site and the
lab guide a single visual family.
Replace the 3-column dependency map with a layered stack figure, after
comparing three candidate layouts (horizontal journey, layered stack,
question-driven typography). The stack was chosen because:
- The "ML stack" mental model is already in the book's prose.
- Uniform pill widths within each tier (Foundation 54, Architecture
74, Optimization 70) read cleanly vs the prior layout's 34-50px
variance.
- Capstone gets a deliberate visual "summit" — entire top band is
orange, with a prominent MIT-red pill.
- Upward arrows between layers convey the dependency direction
without the prior cross-tier routing clutter.
The stack was generated as .claude/_reviews/big-picture-option2-stack.svg
and iteratively polished by gemini-3.1-pro-preview (3 rounds), which
normalised pill widths and pitches and tightened arrow marker
alignment. One small post-gemini fix: "08 Tr" → "08 Train" (the prior
abbreviation was a pre-polish artifact).
Caption and fig-alt in big-picture.qmd updated to describe the new
layout. "Three tiers" language replaced with "Four layers, bottom-up."
Ran gemini-3.1-pro-preview as a multimodal reviewer against the
rendered PNG. Gemini identified two subtle clearance issues and
applied minimal fixes:
- F/A gutter routing for DataLoader -> CNNs/Tokenization was at
x=250 (the dashed divider line itself). Moved to x=265 so the
red arrow ascender has 15px clearance from the divider stroke
and doesn't visually merge with it.
- Cross-tier bus for CNNs -> Profiling was at y=68. The tier
headers sit at y=66 (font-size 12, baseline). Raised... sorry,
LOWERED the bus to y=72 so it clears the descenders of the
tier-header text (~4px clearance below baseline).
Iteration-0 and iteration-1 PNG renders captured at
.claude/_reviews/big-picture-iter-{0,1}.png for the audit trail.
Two visible line-geometry defects in the big-picture Module Flow PDF
render that were making the arrows look "not clean" at print size:
1. DataLoader -> Tokenization arrow double-drew the bus segment
x=250..335 at y=78. The DataLoader -> CNNs path (arrow 1) draws
that segment once, then the DataLoader -> Tokenization path (arrow
2) started back at x=250 and drew the same segment again. At
stroke-width 1.5, the double-draw rendered visibly thicker than
the rest of the bus. Fix: start arrow 2 at x=335 (the CNNs branch
point) so the two paths share that point but do not overlap.
2. CNNs -> Profiling arrow exited CNNs by going straight UP at x=390
(the right edge of CNNs). From y=106 (exit point) to y=90 (CNNs
top), that 16px vertical runs ON TOP of the CNNs right-edge
stroke, making the box border look double-thick. Fix: exit right
10px to (400, 106) before turning up, so the path never overlaps
the box stroke.
No semantic change — same arrow heads, same targets, same ink ratio.
Just cleaner routing.
The big-picture Module Flow figure was using a 4-color tier palette
(blue/purple/orange/gold) while the other 22 module diagrams in the
Lab Guide use a single convention — neutral gray boxes with one orange
accent on the focal element. Crossing two visual languages inside the
same PDF made the overview feel like a figure from a different book.
Align to the module-diagram theme:
- Foundation boxes: blue (#cfe2f3) → neutral (#f7f7f7 / #bbb)
- Architecture boxes: purple (#e8dff0) → neutral (#f7f7f7 / #bbb)
- Optimization boxes: orange (#fdebd0) → neutral (#f7f7f7 / #bbb)
(applies to 14 Profiling, the 4 sub-modules, and 19 Benchmarking)
- Capstone accent: gold (#fff3c4) → orange (#fdebd0 / #c87b2a)
Capstone is now the single orange accent — the "focal element"
pattern every module diagram uses for its key box.
Tiers stay distinguishable by position (left/center/right), by the
tier-header text at y=66, and by the dashed vertical dividers at
x=250 and x=590. No color is needed to separate them.
Prose synced: tier descriptions in big-picture.qmd drop the color
parentheticals ("Foundation (blue)" → "Foundation"). Caption and
fig-alt updated to describe the neutral-with-orange-accent theme.
Side benefit: the figure now conforms to svg-style.md's palette
without any per-tier justification needed — every hex in the SVG
is from the approved palette list.
The big-picture Module Flow figure used two colors outside the ML
Systems SVG style guide palette:
- Architecture tier: muted purple (#e8dff0 / #7a5b8e)
- Capstone accent: gold (#fff3c4 / #c8a02a)
Neither has a justification under the style guide (per svg-style.md,
off-palette colors must be defensible in one sentence). Swap to:
- Architecture tier: data-flow green (#d4edda / #3d9e5a). Architecture
is where data flows through the model — the "healthy path" semantic
from the style guide fits naturally.
- Capstone accent: MIT red (#a31f34) fill with white text. Capstone
is the figure's key callout (final milestone), which matches the
accent-chip role in the style guide.
Foundation (blue = compute) and Optimization (orange = routing) already
conform and are unchanged.
Prose kept in sync: the sentence "Architecture (purple) applies them..."
in the caption and the fig-alt both now say "green". Two SVG comments
updated to describe the new semantic roles.
Lab Guide palette now contains only: book blue (#cfe2f3), book green
(#d4edda), book orange (#fdebd0), MIT red (#a31f34), neutrals (#bbb /
#f7f7f7 / #333 / #555 / #999). Zero off-palette colors.
The four parallel optimization modules (15 Quantization, 16 Compression,
17 Acceleration, 18 Memoization) were rendered as a single row of tiny
abbreviated boxes ("15 Q", "16 Cmp", "17 Ac", "18 Mm") at font-size 9.5
because a single row of 4 boxes couldn't fit full labels in the 160px
Optimization tier width. In the PDF at print size, the abbreviations are
hard to read and feel inconsistent with the full-word labels used
everywhere else in the figure.
Rearrange as a 2x2 grid with full labels:
Row 1: 15 Quantization 16 Compression
Row 2: 17 Acceleration 18 Memoization
Each box is now 90x32 (up from 34-50 wide) at font-size 10 (up from 9.5)
with the full word. The Optimization tier content widens from 160 to 190
(Profiling and Benchmarking match the new grid width for visual
alignment). Tier content now spans x=605..795 instead of x=620..780;
the three cross-tier red arrows (CNNs->Profiling, Transformers->Profiling,
Benchmarking->Capstone) are rerouted to enter the new left edge and to
route through the tighter A/O gutter at x=595 instead of the old x=605.
Arrow topology preserved: fan-out from Profiling reaches the top row;
fan-in to Benchmarking comes from the bottom row. The 2x2 grouping
visually communicates "four parallel optimization alternatives" without
requiring arrows to cross over the top row to reach the bottom row.
tinytorch/quarto/assets/images/diagrams/00_big-picture-module-flow.svg
was a duplicate of the canonical big-picture diagram, which lives at
assets/images/svg/big-picture-module-flow.svg and is the one actually
referenced from big-picture.qmd (line 408). The diagrams/ copy was
never wired into any .qmd, .yml, or markdown — a true orphan.
The two files had diverged visually (the canonical was hand-authored
per the book style guide; this one was Python-generated with the
Tailwind-palette drift that the sibling 22 diagrams had). The earlier
normalization pass on this branch (7d9eab7ed) patched the palette, but
rather than keep two files that could drift again, remove the dupe.
No .qmd change needed — no file referenced it. No PDF regression —
the canonical SVG is unaffected.
* polish(tinytorch/diagrams): align 23 Lab Guide SVGs with book style guide
The hand-authored diagrams under tinytorch/quarto/assets/images/diagrams/
were drifting from the ML Systems SVG style guide — they used Tailwind
CSS greys and custom oranges instead of the book palette. This made them
visually clash with the canonical big-picture-module-flow.svg (under
assets/images/svg/) and with every other diagram in the textbook.
Normalize to book style:
- Fills: #f4f5f7, #f8f9fa, #e5e7eb → #f7f7f7 / #bbb (book neutrals)
- Text: #1f2937, #6b7280 → #333 / #999 (book text hierarchy)
- Arrows: #9ca3af → #555 (book neutral stroke)
- Accent orange: #fff1e8 / #ff8246 → #fdebd0 / #c87b2a (book routing)
- Corner radius: rx="2" → rx="4" per style-guide standard
- Stroke width: flat "1" → "1.2" (secondary tier per style guide)
- Section titles: font-size="11" (bold) → "12" per style-guide headers
No content, layout, or positional changes — only style-token swaps.
All 23 SVGs re-validated as well-formed XML.
Side effect: the orphan diagrams/00_big-picture-module-flow.svg is also
normalized. The canonical big-picture is under assets/images/svg/ and
was already book-styled (not touched by this pass).
* polish(tinytorch/01_tensor): port Cache Tiling systems callout from ABOUT.md
The stashed work from the tinytorch-updates branch included a Cache
Tiling "Systems Implication" callout for Module 01, but it lived in
tinytorch/src/01_tensor/ABOUT.md — a path that was retired when the
module docs consolidated into tinytorch/quarto/modules/. The companion
"Contiguous Memory & Strides" callout from the same stash already made
it over during the consolidation; this one got left behind.
Insert the callout right after the matmul O(n³) explanation (the
natural bridge into "why does the naive loop lose to BLAS?"), and
before the Shape Manipulation section. Progressive-disclosure check:
every concept the callout introduces (cache misses, BLAS, O(n³) vs
O(n²)) is already on the page or introduced inline in the callout
itself (Memory-Bound / Compute-Bound are defined parenthetically).
The pattern matches the existing book-style sidebar on line 587.
* deps: bump TypeScript 5→6, @types/node 20→25, ipykernel 6→7
Resolves 9 stale Dependabot PRs (#1494, #1497, #1490, #1491, #1479,
#1477, #1475, #1467, #1454) whose package-lock conflicts blocked
auto-rebase.
VSCode extensions: bump TypeScript devDep to ^6.0.3 and @types/node to
^25.6.0 across book-ext, mlsysim-ext, labs-ext, kits-ext, tinytorch-ext.
Regenerate lockfiles.
TypeScript 6.0 no longer auto-includes ambient @types packages; add
explicit "types": ["node", "vscode"] to each tsconfig so
child_process / fs / Buffer / vscode API types continue to resolve.
All 5 extensions now compile clean with TS 6.0.3 + @types/node 25.6.0.
TinyTorch: bump ipykernel floor to >=7.2.0 in pyproject.toml,
requirements.txt, and binder/requirements.txt.
Two issues on the big-picture module flow diagram:
1. Cross-tier arrow vertical segments were routed inside the Foundation
and Architecture panels, making them read as intra-panel connectors.
All cross-tier verticals now sit in inter-panel gutters: F/A at
x=250 (on the divider), A/O at x=605, and the bottom margin at
y=410 for Benchmarking -> Capstone.
2. DataLoader sat at the top of the Architecture tier despite being M05
in Foundation per the module numbering convention in
tiers-foundation-dependencies.svg. The header "FOUNDATION (01-08)"
then advertised 8 modules while only 7 were drawn. DataLoader is
now placed in Foundation as M05, and Architecture holds only 09-13.
Cross-tier arrows originate from Foundation.DataLoader -> Architecture
CNNs and Tokenization. Module numbers added to every box for
consistency with the tiers diagrams.
Prose in big-picture.qmd updated to match the new structure: tier labels
carry their numeric ranges, DataLoader is described as part of
Foundation (referencing M05 from Architecture), and the Flexible paths
list uses tier-numbered short paths.
The hand-authored diagrams under tinytorch/quarto/assets/images/diagrams/
were flush to their viewBox bottom edge (typically 10px slack, one with
0px slack). In the PDF build this made figure captions visually collide
with the diagram — the 'F' of 'Figure 9.1' rendered cropped against the
pipeline container rectangle.
Fix: for each SVG, raise the viewBox height (and matching background
rect height) so the bottommost drawn element has 30px of whitespace
below it. Meets the svg-style.md 'Minimum 20px padding between any box
and the panel edge' rule with a small safety margin.
21 of 23 SVGs updated:
- old_slack: 0px (01_tensor-diag-3) or 10px (most) → 30px
- 2 diagrams already had ≥30px slack and were left alone
(00_big-picture-module-flow, 02_activations-diag-1)
No layout or content changes — only viewBox + background height bumps.
Lab Guide PDFs will re-render from these sources on next `make figures`.
Makefile:
- pdf/_quarto.yml writes to pdf/_build/ (via output-dir). The publish
workflow (tinytorch-publish-live.yml) expects the artifact at the
stable path pdf/TinyTorch-Guide.pdf. Copy _build/TinyTorch-Guide.pdf
up to pdf/ after render so publish finds it.
getting-started.qmd:
- Replace the mermaid "Your TinyTorch Journey" graph with a figure div
embedding 00_journey-diag-1.svg. Mermaid renders inconsistently in
the PDF pipeline; a hand-authored SVG gives identical output across
HTML and PDF and matches the book's figure grammar.
Diagrams:
- 00_journey-diag-1.svg: new 5-stage journey diagram (Install → Setup
→ Start → Complete → Milestone) with feedback loop back to Start.
- 00_big-picture-module-flow.svg: three-panel overview (Foundation,
Architecture, Optimization) leading to Capstone. Staged for a
future big-picture chapter; not yet referenced.
Style-guide conformance for both SVGs is a follow-up pass.
Pointed-at fixes from a visual PDF review:
- preface.qmd: drop emojis from the astronaut/rocket-scientist opener
(XeLaTeX renders them as zero-width glyphs, leaving phantom space
before the period); split the colored-card grids into HTML-only and
PDF-only branches via :::{.content-visible} so PDF readers get a
clean bold-paragraph layout instead of the divs flattening into
unstyled prose; remove the JIT/Pin compilers footnote.
- modules/04_losses.qmd: blank line before the Case 1/Case 2 bullet
lists so Pandoc actually emits them as a list (not run-on prose),
plus a PDF-only \medskip between the two cases since callouts
collapse paragraph spacing.
- milestones/index.qmd, conclusion.qmd: remove stray --- horizontal
rules in body content (per project rule: HRs only inside code or
style examples).
- assets/images/diagrams/03_layers-diag-1.svg: redraw per STYLE.md.
Old version had four L-shaped paths starting inside the source box.
New version: orange parent at top, three children fanning out below
with straight diagonal/vertical arrows, no overlapping geometry.
- pdf/_quarto.yml:
* fvextra Highlighting/verbatim envs with breaklines so long code
lines wrap cleanly inside the page column instead of overflowing
the right margin.
* \titleformat{\part} so Part divider pages carry the brand: a
flameorange "PART I" eyebrow above a torchnavy bold-sans title,
bracketed by hairline rules.
Audited every diagram by rendering SVG → PNG and inspecting visually,
then applied targeted fixes:
- 01_tensor-diag-1: removed bezier feedback loop that crashed through
the bottom row of boxes; tightened viewBox/panel to fit content.
- 02_activations-diag-1: spread the 5 right-side arrowheads across
the Output Tensor's left edge instead of piling them on one point.
- 05_dataloader-diag-1: redrew as a clean 3+2 grid (DataLoader on
top row, Iterator below it, Training Loop to its left), eliminating
two awkward Q-bezier paths in favor of straight orthogonal arrows.
- 10_tokenization-diag-1: redrew as a diamond topology with four
short clean diagonals (Base → Char/BPE → Vocab); previous L-shape
paths and right-side empty space are gone.
- 12_attention-diag-1: redrew with V flowing along the bottom into
Weighted Output rather than a long L-shaped path crossing the
diagram.
- 11/14/15/16/17/18/19/20: widened the orange accent box to span all
upstream columns so the N→1 fan-in arrows drop straight down
instead of bending inward.
- 20_capstone-diag-1: full redesign — now shows the actual submission
pipeline (Baseline/Optimized models → BenchmarkReport →
generate_submission() → results.json) instead of duplicating the
benchmarking diagram. Caption in 20_capstone.qmd updated to match.
- 04/06/07/09/11/14-20: trimmed viewBox heights from the default 360
down to the smallest value that still fits the content with ~10–20px
margin. Empty whitespace below the lowest row is gone.
PDF rebuilt and verified: every figure now centers cleanly with no
clipping, no floating arrows, no L-shape connectors.
Brings the TinyTorch lab guide's Quarto project in line with
book/quarto/, the only other in-tree Quarto publication that builds
both web and PDF outputs from a single source. The previous name had
three redundancies:
- already under tinytorch/, so "site-" prefix wasn't disambiguating
- also produces the PDF lab guide, so "site-" was misleading
- the top-level site/ dir made "site-quarto" read as "the site's
quarto config" rather than "the tinytorch site, in quarto"
After this rename the convention is straightforward:
book/quarto/ -> the textbook (web + PDF)
tinytorch/quarto/ -> the TinyTorch lab guide (web + PDF)
mlsysim/docs/ -> mlsysim API reference (kept as docs/, since it
really is API reference, not a publication)
Touches 7 GitHub workflows, both .gitignore files, the rename target's
own self-references (Makefile, _quarto.yml configs, STYLE.md,
measure-pdf-images.py), and 6 copies of subscribe-modal.js plus a few
shared scripts/configs whose comments documented the old path.
Verified: rebuilt pdf/TinyTorch-Guide.pdf (2.1M) cleanly from the new
location with 'make pdf' from tinytorch/quarto/.
