- Pick a starter or write your own, then press Run. Python, NumPy, pandas, - scikit-learn and matplotlib all work, for free, with no sign-up, and your + Pick a starter or write your own, then press Run. Or open the ML builder + and drag blocks together to train a real model. Free, no sign-up, and your code never leaves this page.
++ Building a web page instead?{" "} + + Open the HTML & CSS editor + + , or pick a guided{" "} + + project + + . +
+ Web playground +
++ Pick a starter or clear it out and write your own. Change one thing, watch the preview, + and keep going. +
+ +{item.body}
++ New to all this? The{" "} + + HTML and CSS track + {" "} + starts from what a web page is. Prefer Python? Try the{" "} + + Python playground + + . +
+{project.intro}
+ +
+
+
+ {isWeb + ? "It already shows something on the page. The TODO comments mark where to start." + : "It already runs. The TODO comments mark where to start."} +
++ One way to finish it. Have a go first; yours doesn't need to match. +
+
+
+ Projects +
++ Guided projects for when you've learned a little and want to make something with it. + Everything runs free in your browser, with nothing to install. +
+ +{item.body}
++ Want to brush up first? Every project links to the course chapters that help, and the + playground is always open if you'd rather just tinker. +
+ +{eyebrow}
{lead}
- + {lead &&{lead}
} +{step.body}
+- Listed in no particular order. CodeWithPurpose isn’t affiliated with any of these companies. -
+ + ); + })} +{item.why}
-
- {item.prompt}
-
- {step.body}
+{group.blurb}
{tool.description}
++ Listed in no particular order. CodeWithPurpose isn’t affiliated with any of these companies. +
{rule.body}
-
- Our free Vibe Coding course walks you through building real projects with AI, one step at a
- time. Questions along the way? Ask the community.
+ {/* Next steps */}
+
+ Our free Vibe Coding course walks you through building real projects with AI, one step at a time.
+ Or try some code right now in the playground.
+ Questions along the way?{" "}
+
+ Ask in our Discord
+ (opens in a new tab)
+
+
+ Here is IoU as a function, with a 100-by-100 prediction slid further and further right
+ of the true box.
+
+ A 25-pixel slide still scores 0.60, a hit. At 50 pixels it is 0.33, the miss from the
+ exercise above. Change the threshold to 0.75 and the 25-pixel box becomes a miss
+ without moving.
+
0.5 is the threshold you will see quoted most often, but it is a convention, not a
property of geometry. A benchmark can and does choose differently — some standard
- evaluations report accuracy at 0.75, a noticeably stricter bar, and some report a whole
+ evaluations report results at 0.75, a noticeably stricter bar, and some report a whole
curve of scores across every threshold from 0.5 to 0.95 rather than commit to one.
diff --git a/src/components/computer-vision/ColourAndChannelsLesson.tsx b/src/components/computer-vision/ColourAndChannelsLesson.tsx
index 97300d95..8ee9989a 100644
--- a/src/components/computer-vision/ColourAndChannelsLesson.tsx
+++ b/src/components/computer-vision/ColourAndChannelsLesson.tsx
@@ -1,7 +1,8 @@
import { Callout } from "@/components/learn/primitives/Callout";
import { CompareGrid, TakeawayCard } from "@/components/learn/primitives/Cards";
-import { InlineCode } from "@/components/learn/primitives/CodeBlock";
+import { CodeBlock, InlineCode } from "@/components/learn/primitives/CodeBlock";
import { Lead, LessonSection, P, Strong } from "@/components/learn/primitives/LessonSection";
+import { RevealCard } from "@/components/learn/primitives/RevealCard";
export function ColourAndChannelsLesson() {
return (
@@ -27,7 +28,7 @@ export function ColourAndChannelsLesson() {
channel until you ask a specific question about a specific image.
- Green gets nearly five times the weight of blue because human vision is
- far more sensitive to green light — your eye has more receptors tuned to that part of
- the spectrum than to red or blue. A grayscale conversion that used equal weights would
+ Green gets about five times the weight of blue because human brightness
+ perception peaks in the green part of the spectrum: the cones that respond to red and to
+ green both respond strongly there, while blue-sensitive cones are comparatively few and
+ contribute little to how bright something looks. A grayscale conversion that used equal
+ weights would
produce a technically valid image that looked wrong to every person who looked at it,
because it would not match how brightness actually registers for a human observer.
+ A two-pixel image, a sky and a leaf, pulled apart into channels, turned grey, and then
+ read in the wrong channel order.
+
+ The weighted grey for the sky is 188, as in the exercise above. Reversed, the sky
+ becomes 235, 206, 135, a pale orange, while the leaf barely changes, because its red
+ and blue were close to begin with.
+
- Click through the matrix above and one pair dominates. Cats, dogs and foxes are each
- confused with something else once or twice out of fifty — noise, essentially. Wolves and
+ Click through the matrix above and one pair dominates. Cats, dogs and foxes each lose
+ only three or four photos out of fifty, scattered one or two at a time across the other
+ classes — noise, essentially. Wolves and
coyotes are a different story: 19 wolves called coyotes, 21 coyotes called wolves, out of
50 of each. That is 40 of the 54 total errors in the entire matrix, from one pair of
classes out of five.
That number changes what you would do next. Improving every class’s accuracy by a
- point each is 5 points of work for a few points of overall gain. Fixing the wolf/coyote
+ point each is five separate pieces of work for one point of overall gain. Fixing the wolf/coyote
confusion alone — better ear and muzzle features, more training photos of exactly this
pair side by side — recovers up to 40 of the 54 errors on its own, which would push
- accuracy from 78.4% into the low-to-mid 90s. The matrix tells you where to spend
+ accuracy from 78.4% to as high as 94.4%. The matrix tells you where to spend
the next month, and the single number never could.
+ Try it on real images: a deliberately weak digit classifier, then the off-diagonal
+ cells sorted by count.
+
+ Overall it scores 84.4%. The biggest single error is 21 eights called ones, then 16
+ threes called nines. Change the 60 training images to 300 and see which confusions
+ survive.
+
+ You can check the 2n + 1 rule by following a single pixel through a stack of 3-by-3
+ layers.
+
+ Each layer adds two pixels: 3, 5, 7, 9, then 11 after five layers.
+
Depth is not free. More layers means more parameters to learn, more
computation for every photo you show it, and a model that needs far more labelled
diff --git a/src/components/computer-vision/DatasetBiasLesson.tsx b/src/components/computer-vision/DatasetBiasLesson.tsx
index 0e7242d9..60c302cc 100644
--- a/src/components/computer-vision/DatasetBiasLesson.tsx
+++ b/src/components/computer-vision/DatasetBiasLesson.tsx
@@ -1,5 +1,6 @@
import { Callout } from "@/components/learn/primitives/Callout";
import { CompareGrid, TakeawayCard } from "@/components/learn/primitives/Cards";
+import { CodeBlock } from "@/components/learn/primitives/CodeBlock";
import { Lead, LessonSection, P, Strong } from "@/components/learn/primitives/LessonSection";
export function DatasetBiasLesson() {
@@ -45,9 +46,9 @@ export function DatasetBiasLesson() {
This is not hypothetical. Joy Buolamwini and Timnit Gebru’s 2018 “Gender
- Shades” study tested three commercial facial-analysis systems and found error rates
- on darker-skinned women running as high as 34%, against under 1% for lighter-skinned men
- on the same systems. The gap was not a mysterious algorithmic quirk — it traced directly
+ Shades” study tested three commercial systems that classify the gender of a face and
+ found error rates on darker-skinned women running as high as 34%, against under 1% for
+ lighter-skinned men on the same systems. The gap was not a mysterious algorithmic quirk — it traced directly
back to benchmark and training datasets that were overwhelmingly lighter-skinned and
male.
+ A generated test set where one group makes up about 4% of the photos and the model is
+ much worse on it. One overall number, then the same results grouped.
+
+ Overall accuracy is 96.4%. Grouped, it is 97.1% for the well-represented photos and
+ 79.1% for the rest.
+
+ Here it is on a tiny wall with a darker doorway, plus a little sensor noise. Each
+ pixel is compared with its right neighbour and the one below.
+
+ Inside the wall and the doorway the slope stays under 20; along the door frame it
+ jumps past 75. A threshold of 40 keeps just the frame. Drop it to 5 and the noise
+ starts drawing lines of its own.
+
- The previous chapter’s Gender Shades findings apply directly here, and soberly: that
+ The Gender Shades findings from the dataset bias chapter apply here, and soberly: that
research measured commercial facial-analysis error rates as high as 34% for darker-skinned
- women against under 1% for lighter-skinned men, on systems already deployed commercially.
+ women against under 1% for lighter-skinned men, on systems already sold commercially.
+ Gender Shades tested gender classification rather than identity matching, but the U.S.
+ government’s own testing of face recognition algorithms in 2019 also found error
+ rates that varied across demographic groups for many of the systems it evaluated.
A wrongful match from a recognition system is not an abstract inconvenience — it can mean
being stopped, questioned, or investigated for something you did not do.
- None of this stayed theoretical. Several cities and police departments in the United
- States have restricted or banned police use of facial recognition outright, after
- documented wrongful arrests traced back to recognition errors. A number of large
- companies paused or ended sales of facial recognition to law enforcement following the
- same evidence.
+ None of this stayed theoretical. Several U.S. cities have restricted or banned police
+ use of facial recognition outright, and documented wrongful arrests traced back to false
+ matches have since strengthened the case for limits. In 2020, amid public scrutiny that
+ included independent audits of uneven error rates, a number of large companies paused or
+ ended sales of facial recognition to police.
+ An edge sits in between. Slide the window across an edge and the view changes sharply;
+ slide it along the edge and it barely changes at all. That makes an edge locatable in one
+ direction and ambiguous in the other, which is why detectors prefer corners, where no
+ direction is ambiguous.
+
+ Shift across the edge and the pixels change; shift along it and they do not. You
+ can pin down one direction, never both.
+
+ Here is that test as arithmetic, on a bright square. The score adds up how brightness
+ changes across and down a small window, and is only large when it changes in both
+ directions at once.
+
+ The flat patch scores 0, the edge scores below 0, and the corner scores 1.74. This is
+ the idea behind the Harris corner detector.
+
A live video feed at 30 frames per second hands the model a new frame every 33
- milliseconds, whether or not it has finished with the last one. A large, highly accurate
- model that takes 200 milliseconds per frame is not a slower version of a usable system —
- it is unusable at that frame rate, full stop, regardless of how it scored offline.
+ milliseconds, whether or not it has finished with the last one. Take a large, highly
+ accurate model that needs 200 milliseconds per frame, running on a single worker. That
+ worker cannot keep up with the frame rate, regardless of how the model scored offline:
+ it has to skip five frames in every six, and whatever happens in those gaps goes unseen.
+
+ Two numbers are tangled together here. Throughput is how many frames
+ per second the system can get through; latency is how long any one
+ frame waits for its answer. Running six or seven copies of the model side by side, each
+ taking every sixth or seventh frame, can bring throughput back up to 30 frames per
+ second, at the cost of that much more hardware. It does nothing for latency. Every
+ answer still arrives at least 200 milliseconds after its frame, which for a robot arm
+ or a car can already be too late.
+
+ A three-second simulation of a 30 fps feed and a 200 ms model, with one worker and
+ then seven.
+
+ One worker processes 15 of the 90 frames. Seven process all 90. Either way, every
+ answer arrives 200 ms after its frame.
This is a genuine trade-off against accuracy, not an implementation footnote to solve
- later. A smaller, faster, slightly less accurate model that keeps up with 33 milliseconds
- per frame is often the only real option; a bigger model that cannot keep up does not get
- partial credit for its offline score.
+ later. A smaller, faster, slightly less accurate model that fits inside 33 milliseconds
+ per frame on the hardware you actually have is often the only real option; a bigger model
+ that cannot keep up does not get partial credit for its offline score.
That narrowness is the whole design, not a limitation someone forgot to
- fix. Detection and segmentation, two chapters ahead, exist specifically to
+ fix. Detection and segmentation, later in this track, exist specifically to
answer the questions classification refuses to.
- A well-known example: a model trained to tell huskies from wolves reported 97%
- confidence on a photo of a wolf standing in a grassy field — correctly, this time,
- identifying it as a wolf, but for the wrong reason entirely. In earlier tests the same
- model had called wolves “husky” whenever the photo had snow in the
- background, because most of its husky training photos happened to have snow in them
- and most of its wolf photos did not. The model had learned to detect snow, not dogs,
- and reported startling confidence while doing it.
+ A well-known demonstration from research on explaining classifiers: a model was
+ trained to tell huskies from wolves on photos where the wolves were nearly always
+ pictured against snow. It then labelled a husky standing in snow as a wolf. When the
+ researchers asked which parts of the image drove the decision, the answer was mostly
+ the snow, not the animal. The model had learned to detect snow, not wolves, and on
+ most of its test photos that shortcut happened to give the right answer — which is
+ exactly why nobody would have noticed from the accuracy alone.
A confidence score describes how sure the model is, not how right it
@@ -86,6 +87,39 @@ export function ImageClassificationLesson() {
fine-grained categories — breeds of dog, species of bird — where the correct answer and
the model’s honest second guess are easy to confuse.
+ Four photos, six classes, and a model’s probabilities for each. Rank the guesses
+ and score them both ways.
+
+ Only the first photo’s best guess is right, so top-1 accuracy is 25%. Every
+ correct answer is somewhere in the top three, so top-3 accuracy is 100%. Same model,
+ same probabilities.
+
+ Both halves of that in one run. Normalising uses numbers from the training photos only,
+ and then a 6 from the test set is rotated by 180 degrees.
+
+ The model reads the 6 correctly, and calls the rotated one a 9. If that rotation were
+ used as augmentation, the training set would be full of 9s labelled 6.
+
+ Ready to build something?
+
+
+ A small semantic mask with two round dogs. First, how much of a box around one of them + is not dog; then, counting the dogs by finding connected blobs. +
++ 32 of the 81 pixels in the box are background. The blob count finds two dogs, but only + while they do not touch. Move them together and the same mask reports one. +
A colour pixel is not one number, it is three — one each for red, green and blue, @@ -68,6 +69,36 @@ export function ImagesAsNumbersLesson() { times the numbers to store and four times the numbers a model has to process, for roughly twice the visible detail. +
+ Build a small face from nothing but numbers, then halve its resolution by averaging + each 2-by-2 block into one pixel. +
++ 144 numbers become 36, and the eyes and mouth smear into two greys. Change the 200 or + the 30 and rerun to see that the picture is nothing but those values. +
- Average precision sidesteps the choice: instead of one threshold, take - the precision value at every point along the sweep and average them. It is a way of + Average precision sidesteps the choice: instead of one threshold, walk + down the sorted list and note the precision each time another real object is caught. + Add those up and divide by the number of real objects in the scene — so an object the + detector never found contributes zero. In the panel above that is (1 + 1 + 1 + 0.8 + + 0.83 + 0.75) / 8 ≈ 0.67. It is a way of scoring the whole trade-off curve with one number instead of committing to a threshold nobody agreed on in advance. Mean average precision then averages that score again, across every object class the detector was tested on — one AP for “pedestrian”, one for “bicycle”, one for “traffic light”, meaned into the single number that gets reported.
++ The panel’s ten detections, walked down by hand. +
++ It prints the same 0.67. Flip one of the last two detections to True and see how much + a single late hit is worth. +
It also treats every miss as equally costly, which is never true in practice. A detector that misses a parked car and one that misses a pedestrian stepping into the road produce - the same one-point deduction to AP, and only one of those two failures matters at + the same deduction from AP, and only one of those two failures matters at highway speed. A single mAP number is a fair summary of overall detection quality and a poor guide to which failures you can actually tolerate.
diff --git a/src/components/computer-vision/NonMaxSuppressionLesson.tsx b/src/components/computer-vision/NonMaxSuppressionLesson.tsx index 8b1e6a2f..815b7ff1 100644 --- a/src/components/computer-vision/NonMaxSuppressionLesson.tsx +++ b/src/components/computer-vision/NonMaxSuppressionLesson.tsx @@ -1,6 +1,7 @@ import { TakeawayCard } from "@/components/learn/primitives/Cards"; import { Lead, LessonSection, P, Strong } from "@/components/learn/primitives/LessonSection"; import { NmsThreshold } from "@/components/computer-vision/NmsThreshold"; +import { CodeBlock } from "@/components/learn/primitives/CodeBlock"; export function NonMaxSuppressionLesson() { return ( @@ -48,6 +49,11 @@ export function NonMaxSuppressionLesson() { It is one dog, described twice. Suppressing the extra box loses nothing; keeping it would double-count the same animal in the final result. ++ In practice this runs separately for each class. A box labelled “dog” never + suppresses a box labelled “person”, however much they overlap — someone + holding a puppy is two objects, not one described twice. +
+ The six boxes from the interactive, run through the algorithm at three thresholds. All + of them are labelled dog, so every box is compared with every kept box. +
++ At 0.5 it keeps a and f, one box per dog. At 0.1 the second dog’s box f is + swallowed by a, and at 0.9 all six survive.
diff --git a/src/components/computer-vision/ObjectDetectionLesson.tsx b/src/components/computer-vision/ObjectDetectionLesson.tsx index 1932130c..8d05fc01 100644 --- a/src/components/computer-vision/ObjectDetectionLesson.tsx +++ b/src/components/computer-vision/ObjectDetectionLesson.tsx @@ -54,9 +54,8 @@ export function ObjectDetectionLesson() { The next idea is to run the classifier again and again, on every possible rectangle the image could contain — every position, every width, every height. A modest 224×224 photo has tens of thousands of plausible box positions at just a handful of sizes; check every - size at every position and you are into the millions. That is a combinatorial explosion, - not a plan, and it is exactly the problem the next two lessons exist to avoid solving the - brute-force way. + size at every position and you are into the hundreds of millions. That is a combinatorial + explosion, not a plan, and it is why real detectors take a different route. diff --git a/src/components/computer-vision/OverfittingInVisionLesson.tsx b/src/components/computer-vision/OverfittingInVisionLesson.tsx index 90997eea..63caad92 100644 --- a/src/components/computer-vision/OverfittingInVisionLesson.tsx +++ b/src/components/computer-vision/OverfittingInVisionLesson.tsx @@ -88,8 +88,9 @@ export function OverfittingInVisionLesson() { being a defence against the actual signal in the photo.+ The same failure shows up on real handwriting. This model gives every pixel of an + 8-by-8 digit its own weight, then is tested on digits nudged one or two pixels to the + right. +
++ It reads 95% of the digits as drawn, 40% after a one-pixel shift, and 9% after two. + Nothing about the digits changed except where they sit. +
A convolution kernel, from the earlier chapter on filters, fixes exactly this failure. Instead of one independent weight per pixel position, a kernel is a small set of diff --git a/src/components/computer-vision/ThresholdCurve.tsx b/src/components/computer-vision/ThresholdCurve.tsx index 82bae3df..b91597e8 100644 --- a/src/components/computer-vision/ThresholdCurve.tsx +++ b/src/components/computer-vision/ThresholdCurve.tsx @@ -51,8 +51,18 @@ const CURVE: readonly CurvePoint[] = Array.from({ length: DETECTIONS.length + 1 }; }); +/** + * Standard (non-interpolated) average precision: the precision at each rank + * where a correct detection is added, summed and divided by the number of + * real objects. Objects that were never detected contribute zero, so the two + * missed objects pull AP down — averaging precision over every cut-off, + * correct or not, would ignore them. + */ const AVERAGE_PRECISION = - CURVE.slice(1).reduce((sum, point) => sum + (point.precision ?? 0), 0) / DETECTIONS.length; + CURVE.slice(1).reduce( + (sum, point, index) => (DETECTIONS[index].correct ? sum + (point.precision ?? 0) : sum), + 0, + ) / TOTAL_GROUND_TRUTH; /** The recall ceiling: even flagging every detection never recovers the two * ground-truth objects nothing was ever proposed for. */ diff --git a/src/components/computer-vision/TransferLearningLesson.tsx b/src/components/computer-vision/TransferLearningLesson.tsx index a9109a0b..591c6cd1 100644 --- a/src/components/computer-vision/TransferLearningLesson.tsx +++ b/src/components/computer-vision/TransferLearningLesson.tsx @@ -69,6 +69,14 @@ export function TransferLearningLesson() { up to the last, doing the seeing; the head is the final layer, doing the naming. Transfer learning keeps the body and swaps the head.
+ Freezing everything is the cautious end of a dial. With a few thousand photos rather + than a few hundred, a common next step is fine-tuning: once the new + head has trained, unfreeze the last few layers of the body as well and keep training + with a small learning rate, so the later, more specific features can adjust to your + images without wiping out what the early layers already know. With very little data, + leave the body frozen; there is not enough to adjust it without overfitting. +
- A car moving at highway speed covers roughly 30 metres every second. Convert that to + A car moving at highway speed — about 110 km/h — covers roughly 30 metres every + second. Convert that to something more concrete: a vision pipeline that takes 200 milliseconds to decide “object ahead, brake” has already let the car travel about 6 metres before the decision even exists, before the brakes have engaged at all. @@ -39,10 +40,10 @@ export function VisionInSelfDrivingCarsLesson() { it is measuring the same thing your eyes measure: visible light bouncing off surfaces.
- That is why no production self-driving system trusts a camera by itself. Radar keeps + That is why most self-driving systems do not trust a camera by itself. Radar keeps working in rain, fog and darkness that would blind a camera, and measures distance and closing speed directly and precisely — but it is weak at telling you what kind of object - it found, a plastic bag and a small dog can look similar to it. Lidar gives precise 3D + it found, and a stationary car and an overhead sign can be hard for it to tell apart. Lidar gives precise 3D distance to every surface it hits regardless of lighting, at real hardware cost, and can struggle with dark or reflective surfaces that absorb or scatter its laser pulses.
@@ -118,8 +119,8 @@ export function VisionInSelfDrivingCarsLesson() {+ You can look at that wall of numbers yourself. scikit-learn ships with a set of small + handwritten digits; here is the first one. +
++ The array is the image. The picture underneath is drawn from those same 64 numbers, + and nothing in them says “zero”. +
+
{hasProgress ? "Saved on this device" : "Free, interactive, and saved as you go"}
Entering course
+Entering course
{active.title}
Manual saving asks you to make the same disciplined decision, correctly, roughly thirty - times a month, forever. Automation asks you to make it once. Every study of habit - formation says the same thing in different words: a system that removes a repeated - decision beats a system that relies on repeating it correctly. + times a month, forever. Automation asks you to make it once. Research on habits + keeps pointing the same way: a system that removes a repeated decision tends to beat a + system that relies on repeating it correctly.
This isn't a character judgement. A decision made under willpower has to win against every other pull on that same balance — a card declined at the register, a friend's birthday, a bad week where a takeout order feels earned. An automated transfer never has to win an argument, because by the time the argument would start, the - money has already left. Willpower is a finite resource spent once per decision. - Automation spends it once, total. + money has already left. Willpower has to show up again for every decision. Automation + needs it once, on the day you set the transfer up.
- The result is a bounced transfer and, on many accounts, an overdraft fee - averaging around {formatCurrency(35)} — on a {formatCurrency(50)} automatic - transfer, that's a 70% penalty for the automation working exactly as - configured. + The result is a bounced transfer and, at banks that still charge one, an + overdraft fee that can run around {formatCurrency(35)} — on a{" "} + {formatCurrency(50)} automatic transfer, that's a 70% penalty for the + automation working exactly as configured.
> ), diff --git a/src/components/financial-literacy/AvoidingScamsAndPredatoryProductsLesson.tsx b/src/components/financial-literacy/AvoidingScamsAndPredatoryProductsLesson.tsx index e0789e18..d914c7cb 100644 --- a/src/components/financial-literacy/AvoidingScamsAndPredatoryProductsLesson.tsx +++ b/src/components/financial-literacy/AvoidingScamsAndPredatoryProductsLesson.tsx @@ -42,10 +42,11 @@ export function AvoidingScamsAndPredatoryProductsLesson() { Do the arithmetic once and the number stops sounding abstract. Borrow {formatCurrency(300)}{" "} for two weeks at a typical $15-per-$100 fee, and the fee alone is {formatCurrency(45)} — which annualizes to roughly 391% APR, because a fee sized for two weeks gets multiplied - out across a full year. Miss the deadline and roll it over three times, which is - common, and that same {formatCurrency(300)} loan has cost {formatCurrency(135)} in fees - in six weeks — more than a normal personal loan would charge in interest over an entire - year, on a fraction of the balance. + out across a full year. Miss the deadline and roll it over twice, which is common, + and that same {formatCurrency(300)} loan has cost {formatCurrency(135)} in fees in six + weeks — with the original {formatCurrency(300)} still owed in full. That is more than a + normal personal loan would charge in interest over an entire year, on a fraction of the + balance. @@ -98,8 +99,8 @@ export function AvoidingScamsAndPredatoryProductsLesson() { ]} />
- None of these are new scams wearing new clothes so much as the exact same four tells
- from the first section, run through a medium that makes them faster to send, harder to
+ None of these are new scams so much as the same tells from the first section and the
+ checklist below, run through a medium that makes them faster to send, harder to
trace, and easier to send to thousands of people at once at zero marginal cost. The
checklist below catches the online versions exactly as well as it catches the phone
call.
@@ -130,8 +131,8 @@ export function AvoidingScamsAndPredatoryProductsLesson() {
- Run that same $28,000 through the chart at a ten-year horizon instead of five, and the
- number it could have become dwarfs the total cost of ownership above. That's the
+ Run that same $28,000 through the chart at a ten-year horizon and it grows to about
+ $55,000 at a 7% average return — more than the car's entire five-year cost of
+ ownership above. That's the
full picture a car purchase actually represents: the sticker price, the recurring costs
of keeping it running, and whatever all of that money would have grown into if it had
gone into an index fund instead.
diff --git a/src/components/financial-literacy/BudgetAllocator.tsx b/src/components/financial-literacy/BudgetAllocator.tsx
index fa429984..ce4ad7d1 100644
--- a/src/components/financial-literacy/BudgetAllocator.tsx
+++ b/src/components/financial-literacy/BudgetAllocator.tsx
@@ -18,7 +18,7 @@ const CATEGORIES: readonly Category[] = [
{ key: "housing", label: "Housing", min: 0, max: 2000, step: 25 },
{ key: "food", label: "Food", min: 0, max: 800, step: 25 },
{ key: "transportation", label: "Transportation", min: 0, max: 600, step: 25 },
- { key: "fun", label: "Fun", min: 0, max: 600, step: 25 },
+ { key: "fun", label: "Fun", min: 0, max: 1200, step: 25 },
{ key: "savings", label: "Savings", min: 0, max: 1200, step: 25 },
];
@@ -30,12 +30,16 @@ const DEFAULTS: Record
@@ -179,7 +185,7 @@ export function CompoundInterestLesson() { "Dividing 72 by an interest rate gives a doubling time accurate to a few months either way — at 7% that's about 10.3 years, close enough to plan around without a calculator.", `${formatCurrency(200)} a month at 7% starting ten years earlier is worth ${formatCurrency(280968)} more at the finish line than starting late, even though the early saver only contributed ${formatCurrency(24000)} more.`, "The first five to ten years of a compounding plan barely move the balance beyond what was contributed — growth only overtakes contributions somewhere between year ten and year twenty, which is exactly when most people give up on it.", - `The same mechanism runs in reverse on debt — a ${formatCurrency(5000)} balance at 24% APR, left untouched, doubles in three years, because compounding doesn't care which direction it's working.`, + `The same mechanism runs in reverse on debt — a ${formatCurrency(5000)} balance at 24% APR, left untouched, doubles in about three years, because compounding doesn't care which direction it's working.`, ]} />
Run the numbers on a concrete case. A $40,000 nursing degree, financed at 6% over ten years, costs roughly $444 a month and about $13,300 in total interest. If that degree - moves your income from $32,000 a year to $58,000, the raise pays the entire loan - payment inside the first four months of the first year, every year, for as long as - you hold the job. The debt bought a permanently higher earning line, not a thing that + moves your income from $32,000 a year to $58,000, the $26,000 raise covers a full + year of loan payments — about $5,300 — in roughly the first three months of every + year, before tax, for as long as you hold the job. The debt bought a permanently higher earning line, not a thing that sits on a shelf losing value.
@@ -73,8 +73,8 @@ export function GoodDebtBadDebtLesson() { a purchase with nothing left to show for it except the balance.
- Put a number on it. A new car bought with a $30,000 loan typically loses{" "} - {formatPercent(20)} of its value the moment it leaves the lot and roughly{" "} + Put a number on it. A new car bought with a $30,000 loan commonly loses + around {formatPercent(20)} of its value in its first year and roughly{" "} {formatPercent(50)} within five years — meaning the loan balance can outpace the car's resale value for years at a stretch. A $3,000 vacation charged to a card at {" "}{formatPercent(22)} APR and paid off at $100 a month takes 44 months — three and a diff --git a/src/components/financial-literacy/HowCreditCardsReallyWorkLesson.tsx b/src/components/financial-literacy/HowCreditCardsReallyWorkLesson.tsx index 9dfe53d5..7c6e90fa 100644 --- a/src/components/financial-literacy/HowCreditCardsReallyWorkLesson.tsx +++ b/src/components/financial-literacy/HowCreditCardsReallyWorkLesson.tsx @@ -25,8 +25,9 @@ export function HowCreditCardsReallyWorkLesson() { Everything charged inside that window — the {formatCurrency(180)} of groceries on day 2, the {formatCurrency(425)} laptop accessory on day 24 — lands on the same statement and shares the same due date, regardless of when in the cycle it happened. A purchase made - the day the cycle opens can get almost 60 days of interest-free credit before it's - due; the same purchase made the day before the cycle closes gets barely 30. + the day the cycle opens can get around 50 days of interest-free credit — the whole + cycle plus the grace period — before it's due; the same purchase made the day + before the cycle closes gets only the grace period, roughly three weeks.
@@ -131,16 +132,17 @@ export function HowCreditCardsReallyWorkLesson() {A {formatCurrency(1200)} purchase financed at 0% for 18 months, with{" "} {formatCurrency(1150)} paid off and {formatCurrency(50)} still outstanding on day 540, - doesn't owe interest on the leftover {formatCurrency(50)}. It owes interest on the - entire {formatCurrency(1200)}, backdated to the day of purchase, at whatever the - card's regular APR is — often {formatPercent(29.99, 2)} or higher. Worked out at - that rate over 18 months, that backdated interest comes to about {formatCurrency(671)}, - on a plan that was marketed as free. + doesn't just owe interest on the leftover {formatCurrency(50)}. It owes every + dollar of interest that quietly accrued on the purchase from the day it was made — on + the full {formatCurrency(1200)} in month one, on whatever was still owed each month + after — at the card's regular APR, often {formatPercent(29.99, 2)} or higher. Paid + down in equal monthly instalments, that backdated interest comes to about{" "} + {formatCurrency(296)}, landing in a single month on a plan that was marketed as free.
A typical checking account pays close to nothing — often 0.01% APY. A high-yield savings account, usually offered by an online-only bank with lower overhead than a branch - network, can pay forty or more times that rate. On a {formatCurrency(10000)} balance, + network, can pay hundreds of times that rate. On a {formatCurrency(10000)} balance, the difference between 0.01% and 4.5% APY is roughly {formatCurrency(449)} a year — for holding the exact same cash, doing nothing differently except which account it sits in.
diff --git a/src/components/financial-literacy/IndexFundsAndTimeInMarketLesson.tsx b/src/components/financial-literacy/IndexFundsAndTimeInMarketLesson.tsx index 2a77052a..744a318d 100644 --- a/src/components/financial-literacy/IndexFundsAndTimeInMarketLesson.tsx +++ b/src/components/financial-literacy/IndexFundsAndTimeInMarketLesson.tsx @@ -19,7 +19,7 @@ export function IndexFundsAndTimeInMarketLesson() { An index fund doesn't try to pick winning companies — it simply buys all of them, in proportion to a benchmark like the S&P 500, and holds them. There's no manager guessing which stock outperforms; the fund's return is just - whatever the whole market did, minus a very small fee. + whatever its index did, minus a very small fee.The alternative is an actively managed fund, where a manager and a @@ -75,8 +75,9 @@ export function IndexFundsAndTimeInMarketLesson() { />
That gap is the whole argument. Independent scorecards that track this every year - consistently find that over any 15-year stretch, somewhere around 85% of actively - managed US large-cap funds fail to beat the S&P 500 itself — not because their + consistently find that over 15-year stretches, a large majority of actively managed US + large-cap funds — in recent scorecards, well over 80% — fail to beat the S&P 500 + itself — not because their managers are bad at picking stocks, but because the fee and turnover drag is a cost the index fund never has to pay back.
@@ -84,7 +85,7 @@ export function IndexFundsAndTimeInMarketLesson() { summaryTag="A fair question" summary="Doesn't that mean some active funds do beat the index — so why not just find one of those?" detailTag="The catch" - detail="Some do, in any given year. The problem is picking one in advance, and having it keep winning. Studies that track the same funds forward find almost no persistence — this year's top-quartile active fund has close to a coin-flip's chance of being top-quartile again next year. Fund rankings you see are also usually built from funds that survived long enough to still exist, quietly dropping the ones that closed after underperforming, which flatters the average further." + detail="Some do, in any given year. The problem is picking one in advance, and having it keep winning. Studies that track the same funds forward find almost no persistence — this year's top-quartile active fund has about the one-in-four chance of staying top-quartile next year that luck alone would predict, and often less. Fund rankings you see are also usually built from funds that survived long enough to still exist, quietly dropping the ones that closed after underperforming, which flatters the average further." footnote="Picking the market's best day in advance and picking next decade's best fund in advance are the same problem wearing different clothes." />- A 1% annual fee sounds trivial, and by itself it is easy to wave off. Compounded over 30 - years at a hypothetical 7% average market return, though, the difference between paying - it and not turns $10,000 into roughly $57,000 instead of roughly $76,000 — nearly - $19,000 gone to a percentage point most people never look at on a statement. Trying to - beat the market and merely matching it after fees produces a worse outcome than simply - buying the market outright. + Walk through what dodging a crash actually requires. Sell after the market has already + dropped, and the first decision locked in part of the loss. To come out ahead, you then + have to buy back in below the price you sold at — but rebounds usually + start while the news still looks bad, so the moment that finally feels safe to re-enter + tends to arrive at a higher price. A few missed weeks of recovery can erase everything + the exit was meant to save, and the next toggle shows how few days that takes.
@@ -135,7 +136,7 @@ export function IndexFundsAndTimeInMarketLesson() { "An index fund buys the entire market in proportion to a benchmark, rather than trying to pick individual winners.", "Before fees, the average active investor's return must equal the index return exactly, because active and passive money together make up the whole market.", "Active funds typically charge several times an index fund's fee and trade more often, which is a cost an index fund almost never pays.", - "Around 85% of actively managed large-cap funds fail to beat the S&P 500 over a 15-year stretch, and this year's winning fund rarely stays a winner.", + "Well over 80% of actively managed US large-cap funds fail to beat the S&P 500 over 15-year stretches, and this year's winning fund rarely stays a winner.", "The market's best days cluster right alongside its worst ones, so trying to dodge the bad days tends to mean missing the good ones too.", ]} /> diff --git a/src/components/financial-literacy/InsuranceBasicsLesson.tsx b/src/components/financial-literacy/InsuranceBasicsLesson.tsx index 201c460c..1ef2373f 100644 --- a/src/components/financial-literacy/InsuranceBasicsLesson.tsx +++ b/src/components/financial-literacy/InsuranceBasicsLesson.tsx @@ -57,7 +57,7 @@ export function InsuranceBasicsLesson() { }, { label: "Out-of-pocket max", - text: "The absolute ceiling on what you'll pay in a policy period — deductible, co-pays, and coinsurance combined. Once you hit it, the insurer covers 100% of covered costs for the rest of the period.", + text: "The absolute ceiling on what you'll pay in a policy period — deductible, co-pays, and coinsurance (your percentage share of a bill once the deductible is met) combined. Once you hit it, the insurer covers 100% of covered costs for the rest of the period.", }, { label: "Coverage limit", @@ -72,10 +72,10 @@ export function InsuranceBasicsLesson() { detail={ <> You pay the first {formatCurrency(500)} yourself. The insurer covers the remaining{" "} - {formatCurrency(100)}. Filing a claim this small is rarely worth it — the{" "} - {formatCurrency(600)} monthly premiums saved over the same period, plus the risk of - a rate increase after a claim, usually costs more than the {formatCurrency(100)} the - insurer would have paid. + {formatCurrency(100)}. Filing a claim this small is rarely worth it — a claim on + your record can raise your premium at renewal, and even a modest increase on a + policy costing {formatCurrency(600)} a year can outweigh the{" "} + {formatCurrency(100)} the insurer paid out. > } footnote="A higher deductible generally means a lower premium — you're accepting more of the small, likely losses yourself in exchange for a cheaper policy against the large, unlikely one." diff --git a/src/components/financial-literacy/MissedDaysChart.tsx b/src/components/financial-literacy/MissedDaysChart.tsx index eebc5f63..a9a3ed70 100644 --- a/src/components/financial-literacy/MissedDaysChart.tsx +++ b/src/components/financial-literacy/MissedDaysChart.tsx @@ -152,7 +152,8 @@ export function MissedDaysChart() {{DAYS_REMOVED} days out of {TOTAL_DAYS.toString()} trading days — a tiny fraction of the - whole period — account for the entire gap between these two numbers. + whole period — account for the entire gap between these two numbers. The daily returns + here are simulated to resemble a broad index fund, not taken from real market history.
); diff --git a/src/components/financial-literacy/NeedsVsWantsLesson.tsx b/src/components/financial-literacy/NeedsVsWantsLesson.tsx index b6aeb711..146d55e2 100644 --- a/src/components/financial-literacy/NeedsVsWantsLesson.tsx +++ b/src/components/financial-literacy/NeedsVsWantsLesson.tsx @@ -23,7 +23,7 @@ export function NeedsVsWantsLesson() {That test is stricter than it feels. A {formatCurrency(6)}-a-day coffee habit adds up - to about {formatCurrency(165)} a month — real money, and a real routine — but it fails + to about {formatCurrency(180)} a month — real money, and a real routine — but it fails the test cleanly. Skip it for a week and nothing breaks except your morning habit. The question was never how much you want something. It was always what happens if you don't get it. diff --git a/src/components/financial-literacy/OpportunityCostChart.tsx b/src/components/financial-literacy/OpportunityCostChart.tsx index 96a8fa0d..16b3ae72 100644 --- a/src/components/financial-literacy/OpportunityCostChart.tsx +++ b/src/components/financial-literacy/OpportunityCostChart.tsx @@ -50,7 +50,7 @@ export function OpportunityCostChart() { id={priceId} type="range" min={200} - max={10000} + max={40000} step={100} value={price} onChange={(event) => setPrice(Number(event.target.value))} diff --git a/src/components/financial-literacy/RetirementAccountsLesson.tsx b/src/components/financial-literacy/RetirementAccountsLesson.tsx index 2e892c85..6af64e11 100644 --- a/src/components/financial-literacy/RetirementAccountsLesson.tsx +++ b/src/components/financial-literacy/RetirementAccountsLesson.tsx @@ -18,8 +18,8 @@ export function RetirementAccountsLesson() { individually) are both containers, not investments. Inside either one, you still choose stocks, bonds, or funds — the same building blocks from two chapters ago. What the container adds is a tax rule: a traditional account reduces your taxable income now and - taxes withdrawals in retirement; a Roth account is taxed now and withdrawals are entirely - tax-free later. + taxes withdrawals in retirement; a Roth account is taxed now and qualified withdrawals in + retirement are entirely tax-free.
Nothing about that mechanism is uniquely American, even though the names are. Whatever @@ -37,8 +37,9 @@ export function RetirementAccountsLesson() { traditional account and the full $100 goes in — no tax paid now — but withdrawals in retirement get taxed as ordinary income at whatever rate applies then. Contribute it to a Roth account instead and you pay the 22% first, - landing about $78 in the account, but every dollar it grows into later comes out - completely untaxed. + landing about $78 in the account, but every dollar it grows into comes out completely + untaxed in retirement, as long as the account's rules for qualified withdrawals are + met.
If your tax rate is identical at contribution and at withdrawal, the two options land in @@ -66,8 +67,8 @@ export function RetirementAccountsLesson() { tone: "neutral", children: (
- Contribution is taxed now, so less of it lands in the account. Withdrawals in - retirement are entirely tax-free. Favours a tax rate later that is the same or + Contribution is taxed now, so less of it lands in the account. Qualified + withdrawals in retirement are entirely tax-free. Favours a tax rate later that is the same or higher than now.
), diff --git a/src/components/financial-literacy/RiskAndDiversificationLesson.tsx b/src/components/financial-literacy/RiskAndDiversificationLesson.tsx index a69ab81c..9c72d357 100644 --- a/src/components/financial-literacy/RiskAndDiversificationLesson.tsx +++ b/src/components/financial-literacy/RiskAndDiversificationLesson.tsx @@ -116,9 +116,9 @@ export function RiskAndDiversificationLesson() {Systematic risk — also called market risk — is the part that hits - nearly everything at once: a recession, a spike in interest rates, a war, a pandemic. In - 2008, broad stock indices fell by roughly half across nearly every industry and nearly - every country simultaneously. Owning twenty companies instead of one did nothing to + nearly everything at once: a recession, a spike in interest rates, a war, a pandemic. In the + 2007–2009 financial crisis, broad stock indices fell by roughly half from peak to trough, + across nearly every industry and nearly every country at once. Owning twenty companies instead of one did nothing to soften that, because the source of the risk was never any individual company to begin with.
diff --git a/src/components/financial-literacy/StatementSimulator.tsx b/src/components/financial-literacy/StatementSimulator.tsx index f758ce0c..81749dfe 100644 --- a/src/components/financial-literacy/StatementSimulator.tsx +++ b/src/components/financial-literacy/StatementSimulator.tsx @@ -101,7 +101,7 @@ export function StatementSimulator() {{choice === "full" - ? `Paid in full before the due date, so the ${formatPercent(APR, 2)} APR never applies — this purchase ends up costing exactly its sticker price.` + ? `Paid in full before the due date, so the ${formatPercent(APR, 2)} APR never applies — these purchases end up costing exactly their sticker prices.` : `Paying only the ${formatCurrency(MIN_PAYMENT)} minimum leaves ${formatCurrency(remaining)} carrying over, and ${formatPercent(APR, 2)} APR adds ${formatCurrency(interest)} in interest before next month's statement even opens.`}
The US uses a marginal tax system: income is sliced into bands, and each - band is taxed only at its own rate. Someone earning $60,000 doesn't pay one rate on - the full amount — the first slice is taxed at 10%, the next slice at 12%, and so on, only + band is taxed only at its own rate. Someone with $60,000 of taxable income — what's + left after deductions like the standard deduction — doesn't pay one rate on the + full amount — the first slice is taxed at 10%, the next slice at 12%, and so on, only up to wherever their income actually stops.
- Run the actual numbers for that $60,000. The first $11,600 is taxed at 10%, which is
+ Run the actual numbers for that $60,000, using the 2024 single-filer brackets (the
+ thresholds are adjusted for inflation every year, so check the current ones). The first
+ $11,600 is taxed at 10%, which is
$1,160. The next $35,550, up to $47,150, is taxed at 12%, which is $4,266. The remaining
$12,850, up to the full $60,000, is taxed at 22%, which is $2,827. Add the three slices
together — $1,160 plus $4,266 plus $2,827 — and the total tax bill is $8,253, not the
@@ -34,16 +37,18 @@ export function TaxesTheBasicsLesson() {
Your marginal rate is the rate on your next dollar earned. Your{" "}
- effective rate is total tax divided by total income — a blend of every
+ effective rate is total tax divided by income — a blend of every
bracket you passed through on the way up. The effective rate is always lower than the
marginal rate, often by a wide margin, because the earlier, lower-taxed slices are still
part of the average.
- For the $60,000 example above, that's $8,253 in tax divided by $60,000 in income —
- an effective rate of about 13.8%, even though the marginal rate sitting on the last
- dollar earned is 22%. Nobody actually pays 22% of their income in this scenario; they pay
- 13.8% of it, and the 22% only describes what the next dollar would face.
+ For the $60,000 example above, that's $8,253 in tax divided by $60,000 of taxable
+ income — an effective rate of about 13.8% on taxable income, even though the marginal
+ rate sitting on the last dollar earned is 22%. Measured against total income it is lower
+ still: if this person took the 2024 standard deduction of $14,600, they earned $74,600,
+ and $8,253 is about 11.1% of that. Either way, nobody pays 22% of their income here; the
+ 22% only describes what the next dollar would face.
- There is a second, quieter mechanic working against you: because the minimum is a{" "} - percentage of the balance, it shrinks along with the balance. A balance that - starts at {formatCurrency(1000)} might carry a minimum near {formatCurrency(35)}. Once - interest has eaten away at the progress and the balance is down to {formatCurrency(700)}, - the minimum recalculates too — smaller, at the same percentage — which is part of why the - final stretch of a minimum-only payoff takes so much longer than the first stretch. + There is a second, quieter mechanic working against you on larger balances: because the + minimum is a percentage of the balance, it shrinks along with the balance. At + 2%, a {formatCurrency(5000)} balance carries a {formatCurrency(100)} minimum; by the time + it's down to {formatCurrency(3000)}, the minimum has recalculated to{" "} + {formatCurrency(60)}. Every step of progress makes the next required payment smaller, + which is exactly why a minimum-only payoff drags on. +
++ On the {formatCurrency(1000)} balance in the chart below, the{" "} + {formatCurrency(25)} floor is what sets the minimum instead (2% of{" "} + {formatCurrency(1000)} is only {formatCurrency(20)}). Work out the first month:{" "} + {formatPercent(22.99, 2)} ÷ 12 is about {formatPercent(1.92, 2)}, so roughly{" "} + {formatCurrency(19.16, 2)} of interest accrues. Of the {formatCurrency(25)} payment, only + about {formatCurrency(5.84, 2)} actually reduces what you owe.
Two beliefs about credit scores are common, confidently repeated, and wrong. Both lead people to either waste money or avoid a useful habit out of caution that - isn't earned. + isn't earned — and the second one clears up once you know what actually does + count as a hard pull.
A handful of other files get special treatment on GitHub, all of them optional and all of - them ordinary files in the repository — most can live at the root or in a{" "} - .github/ directory to keep the root tidy. + them ordinary files in the repository. LICENSE belongs at the root; most of the others can + live there or in a .github/ directory to keep the root tidy.
A licence is how you grant the rest. There is no need to write one — pick a standard one, @@ -141,8 +141,8 @@ git switch --detach v1.2.0 # look at the code as it was at that release
A release is a GitHub feature built on top of a tag. It adds release - notes, downloadable binaries, and a pre-release flag. Every release has a tag; most tags are - not releases. + notes, downloadable binaries, and a pre-release flag. Every release has a tag; not every tag is + a release.
- The simplest model that supports review, and by a wide margin the most common on GitHub. One + The simplest model that supports review, and a very common one on GitHub. One permanent branch — main, always deployable — and short-lived branches off it.
Three rules do almost all the work, and the third one surprises everybody. @@ -174,7 +187,7 @@ RESEND_API_KEY=`}
- Check first — you may already have it. macOS ships a Git, and most Linux distributions - install one by default. + Check first — you may already have it. macOS offers to install Apple's Git the first + time you type the command, and many Linux distributions include one.
@@ -111,8 +111,8 @@ git config --global core.editor nano`} Press Esc, then type{" "} :wq and press Enter to save and quit, or :q! to - quit without saving. This is one of the most-searched programming questions of - all time. + quit without saving. Being stuck here is a famously common first experience, so do + not feel bad about it.
- This is the most popular option on GitHub by a wide margin, and the reason is worth stating - plainly: every commit on main builds and passes. Bisect becomes reliable, + Many teams default to this option, and the reason is worth stating plainly: when the build + and the tests are required checks that gate every change to main,{" "} + every commit on main has passed them. Bisect becomes reliable, reverting is one commit with no flags, and the log reads as a list of features rather than a list of afternoons.
@@ -130,7 +131,7 @@ rows and aborted the download. Fixes #482.`}Whether that is good depends on your taste. Some teams want a clean straight line; others - want the record that these three commits were one piece of work reviewed together. Git + want the record that these commits were one piece of work reviewed together. Git lets you insist on the record:
- M is a merge commit, and it is the only kind of commit with two parents. + M is a merge commit, and it is the only kind of commit with more than one + parent. It contains the combined result, it records that these two lines of development joined here, and Git writes its message for you.
@@ -231,7 +232,7 @@ git branch -d fix/login # safe delete: refuses if the work is NOT merged`} "Stand on main and merge the branch to publish work; stand on the branch and merge main to catch up.", "A fast-forward happens when the target has not moved: no commit is created, the label slides.", "--no-ff forces a merge commit anyway; --ff-only refuses to merge unless it can fast-forward.", - "A three-way merge builds a merge commit — the only commit with two parents.", + "A three-way merge builds a merge commit — the only kind of commit with more than one parent.", "The merge base is the most recent shared commit, and it is what lets Git tell an addition from a deletion.", "A line changed on one side is taken silently. A line changed on both sides is a conflict.", "git merge --abort undoes a merge in progress completely.", diff --git a/src/components/github/OpeningAPullRequestLesson.tsx b/src/components/github/OpeningAPullRequestLesson.tsx index c2e7fdcc..4e9e283b 100644 --- a/src/components/github/OpeningAPullRequestLesson.tsx +++ b/src/components/github/OpeningAPullRequestLesson.tsx @@ -206,7 +206,7 @@ gh pr ready # mark it ready when it is`} }, { label: "The commit tested never existed", - text: "The tested commit is a temporary merge that is not on any branch. This is why a pull request can go red without you pushing anything.", + text: "The tested commit is a temporary merge that is not on any branch. Re-running an old run tests that same merge again. But when main moves, GitHub builds a fresh merge, and the new check run on it can go red without you pushing anything.", }, { label: "Required vs optional", @@ -249,7 +249,7 @@ gh pr view --web # open the failing run's logs`} "The description is read by more people than the diff. Say why, and say what you are unsure about.", "A draft pull request cannot be merged and does not request reviewers — good from day one of the work.", "The merge button is gated by required checks, no outstanding changes requested, and enough approvals.", - "Checks run against a temporary merge with the base, not your branch, so a pull request can go red with no push.", + "Checks run against a temporary merge with the base, not your branch, so when main moves, a fresh check run can go red with no push from you.", "Small pull requests get reviewed. Large ones get approved.", ]} /> diff --git a/src/components/github/ReadingHistoryLesson.tsx b/src/components/github/ReadingHistoryLesson.tsx index 8038c221..c07536bb 100644 --- a/src/components/github/ReadingHistoryLesson.tsx +++ b/src/components/github/ReadingHistoryLesson.tsx @@ -108,7 +108,7 @@ git log -S "loadUser"`} { label: "git diff", text: "Working tree against the index. What you have changed and NOT staged. Silent if everything is staged." }, { label: "--staged", text: "Index against HEAD. Exactly what your next commit will contain. Read this before every commit." }, { label: "HEAD", text: "Working tree against the last commit. Everything you have done since, staged or not." }, - { label: "a..b", text: "Any two commits, branches, or tags. git diff main..fix/login shows what the branch adds." }, + { label: "a..b", text: "Any two commits, branches, or tags, compared tip to tip. git diff main..fix/login is the same as git diff main fix/login." }, ]} />A rebase takes each of your commits in turn, computes the change it made, and applies that change on top of a different commit. The result is a new commit with the same message, the - same author, the same content — and a different hash, because the parent is different and + same author, the same change — and a different hash, because the parent is different and the hash covers the parent.
- Every commit is now duplicated. If they merge, both copies land and the diff applies twice. + Every commit is now duplicated. If they merge, both copies end up in the history side by + side, and anything they built on the originals is tangled up with your rewritten ones. Untangling this is unpleasant and it is always somebody else's afternoon, not yours.
diff --git a/src/components/github/RepositoriesAndTheThreeTreesLesson.tsx b/src/components/github/RepositoriesAndTheThreeTreesLesson.tsx index 7ec14861..a0d9de90 100644 --- a/src/components/github/RepositoriesAndTheThreeTreesLesson.tsx +++ b/src/components/github/RepositoriesAndTheThreeTreesLesson.tsx @@ -180,8 +180,8 @@ Untracked files: variant="terminal" code={`# Same information, one line per file, once you know the letters git status --short -# M src/auth/redirect.ts staged modification -# M src/lib/users.ts modified, not staged +# M src/auth/redirect.ts left column: staged +# M src/lib/users.ts right column: modified, not staged # ?? notes.md untracked`} /> @@ -205,12 +205,13 @@ git status --short code={`git add report.md # index now matches disk # ... you keep typing ... git status --short -# M report.md staged: the version from the git add -# M report.md not staged: everything you typed since`} +# MM report.md +# left M: a staged version, from the git add +# right M: newer edits on disk, not staged`} />- The same file appears twice, because there are two different versions of it. The - fix is to git add again before committing. This is not a bug and it is not + The file carries two letters, one per column, because there are two different versions of + it — and in the full git status it is listed under both headings. The fix is to git add again before committing. This is not a bug and it is not a trap — it is exactly the behaviour that makes staging useful — but it is the most common source of "I committed it and the change is not there".
@@ -220,6 +221,25 @@ git status --short every commit catches the half-staged file, the stray debug print, and the accidentally pasted password — in that order of frequency. ++ Try it yourself. Make a throwaway repository and watch one file move + through the three places. The comments show the expected output from the status and diff commands. +
+This looks like arbitrary pedantry and it is not. Git itself writes messages in the - imperative when it generates them — "Merge branch feature into main", "Revert - Add the caching layer". Your messages sit in the same list, and matching the mood makes + imperative when it generates them — Merge branch 'feature',{" "} + Revert "Add the caching layer". Your messages sit in the same list, and matching the mood makes the log read as one document rather than a pile of styles.
diff --git a/src/components/github/UndoingThingsLesson.tsx b/src/components/github/UndoingThingsLesson.tsx index c6b8ea03..46a03f07 100644 --- a/src/components/github/UndoingThingsLesson.tsx +++ b/src/components/github/UndoingThingsLesson.tsx @@ -2,6 +2,7 @@ import { Lead, LessonSection, P, Strong } from "@/components/learn/primitives/Le import { Callout } from "@/components/learn/primitives/Callout"; import { CodeBlock } from "@/components/learn/primitives/CodeBlock"; import { CompareGrid, LabelRows, TakeawayCard } from "@/components/learn/primitives/Cards"; +import { RevealCard } from "@/components/learn/primitives/RevealCard"; import { StepList } from "@/components/learn/primitives/StepList"; import { UndoChooser } from "@/components/github/UndoChooser"; @@ -19,9 +20,8 @@ export function UndoingThingsLesson() { title="Name what you regret before picking a command" >
- This chapter exists because the top search result for "git undo" is a Stack - Overflow answer with eleven commands and forty thousand upvotes, and running the wrong one - of them destroys work. + This chapter exists because searching for "git undo" turns up long answers + listing many commands side by side, and running the wrong one of them destroys work.
The reliable method is to stop and say out loud what you want to lose. There are only six
@@ -32,13 +32,13 @@ export function UndoingThingsLesson() {
- git restore overwrites a file in your working tree with the version from
- the last commit. Whatever you had typed is gone — not in the index, not in a commit, not in
+ git restore overwrites a file in your working tree with the version in
+ the index — which is the last commit, unless you had staged a newer version. Whatever you had typed is gone — not in the index, not in a commit, not in
the reflog. Gone.
@@ -191,7 +191,7 @@ git revert HEAD # undo the very last commit, safely`}
One file per branch, each containing one commit hash and a newline. Forty-one bytes. That
diff --git a/src/components/github/WhyVersionControlLesson.tsx b/src/components/github/WhyVersionControlLesson.tsx
index 41989e5e..b0cee3a2 100644
--- a/src/components/github/WhyVersionControlLesson.tsx
+++ b/src/components/github/WhyVersionControlLesson.tsx
@@ -57,8 +57,8 @@ site-final-USE-THIS-ONE (copy)/`}
/>
Git answers all four, and the price is learning a handful of ideas that are
- strange the first time. It is worth it — this is the tool every professional developer on
- earth uses, every day, and it has been the standard for twenty years.
+ strange the first time. It is worth it — this is the tool nearly every software team uses,
+ every day, and it has been around since 2005.
Two systems can share the exact same underlying number and behave completely differently - once a hospital deploys them, because the number itself commits to nothing. A model that - says 0.61 has not said “probably positive” or “probably + once a hospital deploys them, because the number itself commits to nothing. A well-calibrated + model that says 0.61 has not said “probably positive” or “probably negative” — it has said “more likely than not, by not very much,” and it is entirely up to the people deploying it to decide how much weight that deserves. + (Many models' raw scores aren't even calibrated probabilities, which is one + more reason the score alone commits to nothing.)
@@ -147,6 +149,12 @@ Positive predictive value: 90 / 1,080 ≈ 8%`} catch more true cases at a low prevalence still returns mostly false alarms — it just returns a different mix of them. +- A proxy variable standing in for illness is one mechanism. Two more, both well - documented and both simpler than anything involving a learned model, so learn them - by name. + A proxy variable standing in for illness is one mechanism. Two more are both well + documented, and both are simpler than anything involving a learned model.
- Twenty-four chapters ago, this track opened with a claim: health tech is not four + Twenty-four chapters ago, this track opened with a claim: health tech is not six separate topics, it is one connected system, and every part of it changes shape the moment it touches an actual patient. The exercise you just ran is the proof of that claim, not a summary of it. You didn't just sketch an app — you touched every diff --git a/src/components/health-in-tech/CybersecurityInHealthcareLesson.tsx b/src/components/health-in-tech/CybersecurityInHealthcareLesson.tsx index b1581deb..91d59ced 100644 --- a/src/components/health-in-tech/CybersecurityInHealthcareLesson.tsx +++ b/src/components/health-in-tech/CybersecurityInHealthcareLesson.tsx @@ -21,9 +21,8 @@ export function CybersecurityInHealthcareLesson() { Ransomware works by locking an organisation out of its own systems until it pays. That threat only has teeth if the organisation cannot simply wait it out — and a hospital, unlike almost any other kind of business, cannot pause patient care for a - week while IT rebuilds servers from backup. Attackers know this. It is exactly why - healthcare gets targeted disproportionately relative to how much money actually flows - through it. + week while IT rebuilds servers from backup. Attackers know this, and it is exactly why + healthcare is such an attractive target.
The way in is rarely a sophisticated exploit. It is a phishing email, and clinical @@ -45,11 +44,13 @@ export function CybersecurityInHealthcareLesson() {
Patch a laptop and the update finishes in minutes. Patch an MRI machine, and a hospital often cannot do it at all. Medical imaging and monitoring equipment routinely - runs for fifteen to twenty years, frequently on an operating system its vendor stopped - supporting long ago, because changing the software of a certified medical device can - trigger a fresh regulatory review before it is allowed back into service. Updating it - is not the routine, low-stakes patch it would be on an ordinary office computer — it is - closer to re-certifying the device from scratch. + stays in service for well over a decade, frequently on an operating system that stopped + getting security updates long ago. The hospital usually isn't allowed to patch it + on its own: the device maker controls the software, has to test every change against + the device's validated, cleared configuration before releasing it, and may stop + supporting older models entirely. US regulators have said routine security patches + generally don't need a fresh review — but a fix nobody ships is a fix the hospital + never gets.
The result is a building full of machines nobody can safely update, sitting on the
@@ -147,7 +148,7 @@ export function CybersecurityInHealthcareLesson() {
items={[
"Hospitals are a disproportionate ransomware target because they cannot pause patient care to wait out an attack the way most businesses can.",
"Attackers targeting healthcare aim at urgency, not carelessness — clinical staff working under time pressure are primed to act fast on anything marked urgent, which is exactly the instinct phishing depends on.",
- "Legacy imaging and monitoring equipment often can't be patched at all, because changing a certified medical device's software can trigger a fresh regulatory review, leaving networks full of machines nobody can safely update.",
+ "Legacy imaging and monitoring equipment often can't be patched by the hospital at all — the device maker controls and validates every software change, and may stop supporting older models — leaving networks full of machines nobody can safely update.",
"Staff training, network segmentation, and offline tested backups stop most of these attacks before they start, and none of the three are exotic or expensive relative to a single ransom payment.",
"The real cost of hospital downtime isn't a dollar figure — it's a diverted ambulance and a delayed diagnosis, neither of which gets undone once the systems come back online.",
]}
diff --git a/src/components/health-in-tech/DigitalDivideChart.tsx b/src/components/health-in-tech/DigitalDivideChart.tsx
index 6a93d626..65c55f4c 100644
--- a/src/components/health-in-tech/DigitalDivideChart.tsx
+++ b/src/components/health-in-tech/DigitalDivideChart.tsx
@@ -57,7 +57,8 @@ export function DigitalDivideChart() {
return (
Both are real, and both are also two of the narrowest stages in the pipeline above —
which is exactly why the improvement doesn't show up as a shorter overall timeline
- yet. Be precise about which tool did which job before crediting AI with the whole
- pipeline.
+ yet. Before crediting AI with a whole new drug, ask which stage it actually sped up.
- DeepMind's AlphaFold is a well-known example of AI in this space, and
- be exact about what it did, because the popular version of the story
- credits it with more than it delivered. Predicting the three-dimensional shape a protein
+ DeepMind's AlphaFold is a well-known example of AI in this space, and it is
+ worth being exact about what it did, because the popular version of the story credits
+ it with more than it delivered. Predicting the three-dimensional shape a protein
folds into, from nothing but the sequence of amino acids that make it up, was an open
problem biologists had chased for decades. Solving it well enough to compete with a
physical lab measurement was a scientific breakthrough, and the resulting
@@ -101,8 +100,8 @@ export function DrugDiscoveryAndAiLesson() {
children: (
Given a protein's sequence, predicting the shape it physically folds into —
- to an accuracy that rivals a lab measurement, for the vast majority of proteins
- ever catalogued.
+ often to an accuracy that rivals a lab measurement, with a confidence score
+ attached to show where a prediction is less reliable.
- The numbers are blunt. Something close to a quarter of people who download a health
- app never open it a second time at all, and by the two-week mark most of the people
- who did have already stopped. By three months, ongoing daily use is the exception
+ The pattern is blunt. A sizeable share of people who download a health app never open
+ it a second time at all, and within the first couple of weeks most of the rest have
+ drifted away. By three months, ongoing daily use is the exception
rather than the rule for anything that stands alone — a wellness app someone
downloaded on their own after a symptom worried them at 2 a.m., say, with nobody and
nothing else pulling them back to it.
@@ -164,7 +164,7 @@ export function HealthAppsAndPatientEngagementLesson() {
- FHIR is not the first attempt at this. It is the fourth major generation of a
- standard published by the same organisation, HL7, and it only makes sense once you
+ FHIR is not the first attempt at this. It is the newest in a line of standards from
+ the same organisation, HL7, and it only makes sense once you
have seen what it replaced — a format that is, remarkably, still running underneath
most of American healthcare today.
Before FHIR, the standard almost every hospital system spoke was{" "}
- HL7 version 2, first published in 1987. Its job was narrower than
+ HL7 version 2, dating back to the late 1980s. Its job was narrower than
FHIR's: get a lab result, an admission notice, or an order from one hospital
system to another in real time, without a courier walking a printout down a hallway.
For that job it worked, and it is the reason a message typed at a nurse's station
@@ -58,12 +58,14 @@ PV1|1|I|MED^204^1||||1234^SMITH^ROBERT|||MED`}
code and each field inside it separated by a pipe:
- That positional format was fast to parse and cheap to implement in 1987, which is
+ That positional format was fast to parse and cheap to implement in the late 1980s, which is
exactly why it spread. What it did not solve is the problem from the last chapter:
v2 lets a message get from one system to another, but
it never forced two hospitals to fill those positions with the same codes. Each
@@ -103,7 +105,12 @@ PV1|1|I|MED^204^1||||1234^SMITH^ROBERT|||MED`}
},
"subject": { "reference": "Patient/482" },
"recordedDate": "2026-03-14",
- "clinicalStatus": "active"
+ "clinicalStatus": {
+ "coding": [{
+ "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
+ "code": "active"
+ }]
+ }
}`}
/>
Reading each field in plain English:
@@ -206,13 +213,14 @@ PV1|1|I|MED^204^1||||1234^SMITH^ROBERT|||MED`}
"display": "Hemoglobin A1c/Hemoglobin.total in Blood"
}]
},
+ "status": "final",
"subject": { "reference": "Patient/482" },
"valueQuantity": { "value": 7.2, "unit": "%" }
}`}
/>
-
- Melanin absorbs green light more strongly than lighter, less pigmented skin does,
+ Darker, more melanin-rich skin absorbs more green light than lighter skin does,
which means less light reaches the blood vessels and less of it returns to the
photodiode — a weaker signal sitting under the same amount of motion and ambient
noise. A tattoo directly over the sensor compounds the same problem: ink absorbs
light too, regardless of skin tone underneath it, and can degrade the reading further
- still. Neither effect is a hypothetical edge case — it is a real accuracy gap that
- contributed to a 2021 FDA safety communication warning that pulse oximeter readings
- can be less accurate on patients with darker skin pigmentation.
+ still. Neither effect is a hypothetical edge case. The same light-absorption problem in pulse
+ oximeters, which use red and infrared light rather than green, led to a 2021 FDA
+ safety communication warning that their readings can be less accurate on patients with
+ darker skin pigmentation.
- Both records below describe one real patient's one real diagnosis. Nothing about
+ Both mock records below describe one patient's single diagnosis. Nothing about
the medicine is different — only how each system happened to write it down.
An emergency room doctor at a hospital you have never visited before can request your
records from your regular clinic in the middle of treating you, without a new consent
- form, because that request falls inside treatment. The one blanket document you sign —
- the Notice of Privacy Practices, usually on a clipboard at a first visit — is what
- covers all three going forward. Anything outside TPO, like selling PHI to a
- marketer, needs the patient's specific authorisation instead.
+ form, because that request falls inside treatment. The document usually handed to you on
+ a clipboard at a first visit — the Notice of Privacy Practices — is not
+ what grants that permission; the law already does. The notice explains how the practice
+ uses your information, and the signature it asks for typically just confirms you
+ received it. Anything outside TPO, like selling PHI to a marketer, needs the
+ patient's specific authorisation instead.
Bandages, tongue depressors, most step-counting wellness trackers. General controls only. No premarket review required at all. Bandages, tongue depressors, manual stethoscopes. General controls only. Most are exempt from premarket review.
That 16-day threshold on 99454 is the number that quietly runs the
whole programme. A patient who wears the device for nine days out of thirty generates
- real data and real staff attention, and the practice still cannot bill for that
- patient's monitoring that month at all. Reimbursement is not a footnote here — it
+ real data and real staff attention, and still falls short of the code that pays for a
+ full month of device monitoring. Billing rules like these are revised regularly —
+ newer codes have been added for shorter stretches of transmission — so the exact
+ thresholds are worth checking against current Medicare guidance, but the pressure they
+ create stays the same. Reimbursement is not a footnote here — it
is the reason a monitoring programme that cannot keep patients transmitting reliably
eventually gets shut down regardless of how well the alerts themselves work.
- The gap is not evenly spread. Compare access across a few different groups below — the
- difference between the best-connected and least-connected group is not a rounding error,
+ The gap is not evenly spread. Compare access across a few different groups in the
+ illustrative chart below — the figures are simulated to show the shape of the gap, not
+ taken from a specific survey — and notice that the difference between the
+ best-connected and least-connected group is not a rounding error,
it is the difference between a product that works for someone and one that quietly does
not.
Roughly two out of three people who followed up on an alert did not
- actually have the condition. Roughly two out of three people who followed up on an alert showed no
+ sign of the condition on the confirmation patch.
- Checked your step count or resting heart rate on a phone or watch? Roughly a third of
- adults in the US now own a wearable that tracks something health-adjacent, and a
- meaningful share of those readings get shown to an actual clinician at some point.
+ Checked your step count or resting heart rate on a phone or watch? Wearables that track
+ something health-adjacent are now an everyday purchase, and some of those readings end
+ up in front of an actual clinician — shown at an appointment, or fed into a monitoring
+ programme.
Had a video call with a doctor instead of driving to a clinic? Telehealth visits
@@ -160,8 +161,8 @@ export function WhatIsHealthTechLesson() {
Skip a stage and the others stop making sense. Bias in a diagnosis model (Part 4)
is only dangerous because that model's output reaches a real patient through an
- app or a doctor's screen (Part 5) built on a record that was supposed to be
- protected the whole way through (Part 2). Treat health tech as one system and every
+ app or a doctor's screen (Part 5), built on a record (Part 2) that was supposed to
+ be protected the whole way through (Part 6). Treat health tech as one system and every
later chapter has somewhere to attach to.
Fully autonomous diagnosis — a model that receives your symptoms and
- returns a confident, unsupervised verdict with no clinician in the loop — is essentially
- not deployed anywhere serious today, for reasons the next chapter covers directly.
+ returns a confident, unsupervised verdict with no clinician in the loop — is barely
+ deployed today. The rare exceptions are tightly scoped screening tasks: the best-known
+ is an FDA-authorised system that checks retinal photos for diabetic eye disease without
+ a specialist reading the image, and even its output is a decision about whether to
+ refer the patient to an eye specialist, not a treatment plan. The next chapter covers
+ why the boundary sits there.
Predicting rare, highly individual outcomes from limited data, the kind
@@ -148,7 +152,7 @@ export function WhatMedicalAiIsActuallyDoingTodayLesson() {
"Medical AI's real advantage is exposure at scale — millions of training examples against one career's worth of cases — not a deeper kind of reasoning.",
"Imaging review, triage worklists, and narrowing drug candidates are three places it is deployed today, always with a clinician reviewing the output.",
"The highest-volume use isn't diagnostic at all — it's turning conversations into notes, notes into billing codes, and calendars into fuller schedules.",
- "Fully autonomous diagnosis with no clinician in the loop is essentially not deployed anywhere serious, despite the headlines it generates.",
+ "Fully autonomous diagnosis with no clinician in the loop is barely deployed outside a few tightly scoped screening tasks, despite the headlines it generates.",
"A model that looks brilliant on data resembling its training set can quietly get worse on data that doesn't — the subject the next few chapters take on directly.",
]}
/>
diff --git a/src/components/health-in-tech/WhyHealthcareIsDifferentLesson.tsx b/src/components/health-in-tech/WhyHealthcareIsDifferentLesson.tsx
index cbf4bd29..1028b20e 100644
--- a/src/components/health-in-tech/WhyHealthcareIsDifferentLesson.tsx
+++ b/src/components/health-in-tech/WhyHealthcareIsDifferentLesson.tsx
@@ -223,7 +223,7 @@ export function WhyHealthcareIsDifferentLesson() {
items={[
"A shopping-app bug costs a transaction and is fully recoverable — refund it, patch it, move on.",
"A health-app bug can drop an allergy or miscalculate a dose, and neither failure has an undo button.",
- "The patient, the provider who buys the software, and the payer who settles the bill want three different things, and none of them is guaranteed to be the same as what's best for the patient.",
+ "The patient, the provider who buys the software, and the payer who settles the bill want three different things, and the one choosing the software is rarely the one living with the outcome.",
"Procurement here runs eighteen months to three years, not a sprint, because integration, security review, and clinical validation all have to clear before a patient is exposed to it.",
"\"Move fast and break things\" assumes bugs are cheap and reversible, and cheap to notice — healthcare breaks all three assumptions at once.",
]}
diff --git a/src/components/html-css/AccessibilityBasicsLesson.tsx b/src/components/html-css/AccessibilityBasicsLesson.tsx
index 22b6a994..4b1766d4 100644
--- a/src/components/html-css/AccessibilityBasicsLesson.tsx
+++ b/src/components/html-css/AccessibilityBasicsLesson.tsx
@@ -43,7 +43,7 @@ export function AccessibilityBasicsLesson() {
{" "}
with two keyboard handlers is a worse{" "}
<button>. Bad
- ARIA is measurably worse than no ARIA.
+ ARIA is worse than no ARIA, because it announces things that are not true.
These are the ARIA attributes most likely to appear on a static site:
@@ -172,7 +172,7 @@ export function AccessibilityBasicsLesson() {
@@ -213,7 +213,7 @@ export function AccessibilityBasicsLesson() {
"Read the page with CSS off. That is roughly the screen reader experience",
]}
/>
-
- They all produce the same pixels. The difference is which one you can read and adjust.
+ Hex, rgb, and hsl can describe exactly the same colour; keywords only cover about 140 named
+ ones, so the keyword below is the nearest match rather than the same green. The real
+ difference is which one you can read and adjust.
- A full-width paragraph on a 27-inch monitor is around 200 characters. Which is why an
+ A full-width paragraph on a large monitor can run past 200 characters a line. Which is why an
unstyled page feels hard to read even though nothing is wrong with it.
+ Try it: set line-height to 1, then back
+ to 1.6. Change max-width to 30ch, then
+ change the font size and watch the measure follow.
+
+ Long lines make your eyes travel a long way back to the start of the
+ next one, and it is easy to land on the wrong line. Short lines break
+ the rhythm of reading. Somewhere in between is comfortable.
+
+ Spacing between lines matters just as much: too tight and the lines
+ blur together, too loose and they stop feeling like one paragraph.
+
With an element selected, the Styles panel on the right lists every rule that matched it —
- in cascade order, most specific first, with the file and line number each came from.
+ in cascade order, with the winning rules at the top and the file and line number each came
+ from.
- Three things in that list explain most of the panel's behaviour.
+ Four things in that list explain most of the panel's behaviour.
Some text
- There are about fourteen in total and those six are all you will use. Note that{" "}
+ There are thirteen in total and those six are the ones you will use most. Note that{" "}
<link> is void — it points at a stylesheet — while{" "}
<a>, the one people call a link, wraps content and definitely
closes.
@@ -121,8 +122,8 @@ export function ElementsAndTagsLesson() {
{" "}
and{" "}
</br>.
- There is no content to wrap and nothing to close. Browsers ignore the stray closing
- tag, so it looks like it works.
+ There is no content to wrap and nothing to close. Browsers patch over both — the
+ stray closing tag is dropped or reinterpreted — so it looks like it works.
+ Try it: change the h2 to an h1, wrap a
+ word in <em>, and add a third list item. Then delete one closing tag
+ and see what the browser decides you meant.
+
+ Some text with a link in it,
+ and one important word.
+
+ Try it: change space-between to center,
+ then space-evenly. Then add flex-direction: column and
+ notice that justify-content now works top to bottom.
+
Note that the CSS file contains no HTML, no <style> tags, nothing
- but rules. Putting a style tag inside a .css file is a common first-day mistake and it
- breaks the whole file — everything after it is treated as invalid.
+ but rules. Putting a style tag inside a .css file is a common first-day mistake: the browser reads
+ the tag as part of the next selector, decides that rule is invalid, and throws it away —
+ and developer tools may report a stylesheet parsing error.
Those are the image's real pixel dimensions and they are not a display size. The
- browser uses the ratio to reserve the right shape, then your CSS scales it. This
- is the modern advice and it reverses guidance from about 2015. Older tutorials say the
- opposite because browsers used to handle images differently.
+ browser uses the ratio to reserve the right shape, then your CSS scales it. Some
+ older tutorials say to leave the dimensions off; that advice dates from before browsers
+ used them this way, and it no longer applies.
- Without those two lines an 4000-pixel photo blows out your layout on a phone and produces
+ Without those two lines a 4,000-pixel photo blows out your layout on a phone and produces
horizontal scrolling. Three more image rules matter:
- A custom domain costs roughly £10 a year from any registrar and points at your host with
+ A custom domain is a small yearly fee from any registrar, and it points at your host with
one DNS record. Chapter 1 explains why the change takes a while to appear everywhere.
Two bugs account for nearly every "it worked on my laptop" report, and both are
@@ -146,7 +146,7 @@ export function PublishingYourSiteLesson() {
macOS and Windows treat{" "}
Photo.JPG and{" "}
photo.jpg as the
- same file. Every Linux web server does not. So a mis-cased path works perfectly
+ same file. Most Linux web servers do not. So a mis-cased path works perfectly
locally and 404s the instant you publish.
@@ -146,6 +148,39 @@ export function ResponsiveDesignLesson() {
@media (max-width: 899px) {
.layout { display: block; }
.sidebar { display: none; }
+}`}
+ />
+
+ Try it: this preview is only as wide as the lesson column. Change
+ min-width: 400px to 1000px and you get the single-column
+ base styles; set it to 200px and you get two columns, whatever your screen.
+
@@ -244,10 +279,10 @@ h1 { font-size: clamp(1.75rem, 5vw, 3rem); }
+ Try it: the rule below uses nav > a, so nothing turns
+ green. Replace the > with a space and watch every link change.
+ A link outside the nav keeps its default colour either way.
The order of these five passes matters more than any individual rule in them. Each one
settles decisions the next one depends on.
@@ -110,7 +110,7 @@ input, textarea, select, button {
{ label: "Overridable", text: "Redeclare any of these inside a media query or a class and everything using it changes." },
]}
/>
-
+ One token moves in the opposite direction: --accent-ink is the link
+ colour, and a dark green that reads well on a pale page disappears on a dark one, so it
+ flips to a light green. Check every token you use for text, not just the obvious ones.
+
- HTML collapses whitespace on the first page you build:
- any run of spaces, tabs, and newlines becomes a single space.
+ HTML collapses whitespace, and it surprises almost everyone on their first page: any run
+ of spaces, tabs, and newlines becomes a single space.
+ Try it: both boxes below say width: 240px. Change the
+ padding to 40px and watch which one grows, then add
+ box-sizing: border-box to the first.
+
There is no downside and essentially every real project starts with it. It is not the
default only because changing a default would have broken a large part of the existing web
@@ -140,6 +169,15 @@ Actual space on screen:
*::before, *::after are
in the selector too.
+
The escaping-child case is the one that produces a genuine bug report. Anything that
- establishes a new formatting context stops it — padding, a border, or the modern one-liner:
+ separates the two margins stops it — padding or a border on the parent — or the modern
+ one-liner, which gives the parent its own formatting context:
- Step through that and notice how little of it is yours. You write the file in step five.
+ Step through that and notice how little of it is yours. The file the server sends in step five is the one you wrote.
Everything before it is infrastructure you will never touch, and everything after it is the
browser interpreting what you wrote.
- Chapters unlock in order. Pass the quick check on{" "}
- {prev.title}, and this one opens
- up.
+ Finish the quick check at the end of{" "}
+ {prev.title}, and this chapter
+ opens up.
Why line length matters
+ Hello
", label: "h1", kind: "element", note: "A child of body. In CSS, `body h1` and `body > h1` both match it here — but only because it is a direct child." },
+ { id: "h1", depth: 2, source: "Hello
", label: "h1", kind: "element", note: "A child of body. In CSS, `body h1` matches it, and so does `body > h1` — the second only because h1 is a direct child of body." },
{ id: "p", depth: 2, source: "A post
+
+
`}
/>
diff --git a/src/components/html-css/FlexboxLesson.tsx b/src/components/html-css/FlexboxLesson.tsx
index 278c518f..ca8e7ed9 100644
--- a/src/components/html-css/FlexboxLesson.tsx
+++ b/src/components/html-css/FlexboxLesson.tsx
@@ -2,7 +2,9 @@ import { Lead, LessonSection, P, Strong } from "@/components/learn/primitives/Le
import { Callout } from "@/components/learn/primitives/Callout";
import { CodeBlock } from "@/components/learn/primitives/CodeBlock";
import { CompareGrid, LabelRows, TakeawayCard } from "@/components/learn/primitives/Cards";
+import { RevealCard } from "@/components/learn/primitives/RevealCard";
import { FlexPlayground } from "@/components/html-css/FlexPlayground";
+import { WebPlayground } from "@/components/webplay/WebPlayground";
export function FlexboxLesson() {
return (
@@ -94,6 +96,15 @@ flex-direction: column-reverse; /* bottom to top */`}
main axis is whatever flex-direction says. Toggle direction in the widget above and watch
them swap.
+
or pressing Enter.",
"strong is importance, em is stress emphasis; b and i are conventional appearance with no added meaning.",
- "blockquote, code, time, abbr and cite all say something a span would not.",
+ "blockquote, q, code, time, abbr and s all say something a span would not.",
"Write < > & as entities. With utf-8 everything else can be typed directly.",
"Comments are ignored by the browser and fully visible in view source.",
]}
diff --git a/src/components/html-css/TheBoxModelLesson.tsx b/src/components/html-css/TheBoxModelLesson.tsx
index c157e24c..110e17ab 100644
--- a/src/components/html-css/TheBoxModelLesson.tsx
+++ b/src/components/html-css/TheBoxModelLesson.tsx
@@ -2,13 +2,15 @@ import { Lead, LessonSection, P, Strong } from "@/components/learn/primitives/Le
import { Callout } from "@/components/learn/primitives/Callout";
import { CodeBlock } from "@/components/learn/primitives/CodeBlock";
import { CompareGrid, LabelRows, TakeawayCard } from "@/components/learn/primitives/Cards";
+import { RevealCard } from "@/components/learn/primitives/RevealCard";
import { BoxModelExplorer } from "@/components/html-css/BoxModelExplorer";
+import { WebPlayground } from "@/components/webplay/WebPlayground";
export function TheBoxModelLesson() {
return (
- Finish the previous chapter first
+ One chapter at a time