◈ MISSION CONTROL

Case study · the failure museum

SCARS

Every rule in this codebase exists because something broke first. The rules are in the source, above the lines they defend. These are the bugs that put them there.

SCROLL

01

The gecko who was walking a thousand pixels below the page

SYMPTOM

Ms. Lil Buddy simply was not there. No console error, no broken layout, nothing in the network tab. She had been on the wall the week before.

CAUSE

A wall-wash effect added .mcr>* — specificity (0,1,1) — about seven hundred lines below .geckolayer, which is (0,1,0). The later, stronger rule quietly turned her absolutely-positioned layer into a zero-height in-flow block pinned to the bottom of the room. Her containing block moved to roughly y 1831, while the code that plans her route went on measuring panels against .mcr at y 20. Every position she computed was therefore about 1,830px too low.

She was walking her route perfectly, at the correct pace, in the correct order, a thousand pixels below the end of the document where nobody could see her. Nothing was wrong with her. The floor was in the wrong place.

THE RULE IT LEFTAn override must live next to the rule it is correcting, and after it in source order. A later rule of equal specificity wins, and a media query buys no specificity at all.
02

Two things named walk

SYMPTOM

Every time the gecko started a leg of her route she teleported to the corner of the screen, stayed there for the duration of the leg, then reappeared where she should have been.

CAUSE

She carried the class walk. So do the pedestrians in the facility cross-section, and theirs owns @keyframes walk — a 26-second transform that carries a figure across a floor. A bare class selector matches any element wearing that class, and a CSS animation beats an inline style. The building's walk cycle was driving her position.

The identical bug happened a second time, independently, with spark: the deck's star and the workshop's welding sparks shared a name, which put the board's star down in the workshop, blinking.

THE RULE IT LEFTIn one long file there is one namespace. A class is a global variable — name it like one.
03

The transition that interpolated from nowhere

SYMPTOM

Same visible fault as the last one — a pop to the corner and a slide back — but with the naming collision already fixed. Only in Chromium.

CAUSE

A CSS transition on the outer SVG's transform. Chromium interpolated it from the identity matrix rather than from her previous computed position, so every leg animated from the layer's origin instead of from where she actually was.

The fix was to stop asking CSS to do it. Her position is now advanced by a fixed pixels-per-second increment inside requestAnimationFrame, so her rendered position and her logical position are the same number by construction, and the pace is constant because it is computed rather than eased.

THE RULE IT LEFTNever transition an SVG transform that JavaScript also writes. Own the property in one place, and if the value changes every frame, that place is a rAF loop.
04

The wall that breathed on someone else's machine

SYMPTOM

The monitor wall was rock solid in testing and jumped 15px on the author's machine, once, a few seconds after load.

CAUSE

A panel whose value rotates through a list of readouts. In the fallback font every value fit on one line, so it looked stable everywhere it was tested. Measured against a metrically accurate stand-in for the real pixel typeface, every value wrapped to two lines except the one it happens to load with33.19°N, a single unbreakable seven-character token. The stable-looking first paint was the anomaly, and the first rotation was the correction.

Fixing one panel was not enough, because webfont arrival re-metrics every label at once. The wall's whole row is now measured after fonts settle and pinned to a fixed pixel height, so nothing inside any panel can move it again.

THE RULE IT LEFTThe wall does not breathe. Any readout whose text changes at runtime gets a reserved height and clips — reserved in em where a clamp is involved, and never reasoned about in the font you happen to be testing in.
05

One wall, three bottom edges

SYMPTOM

The monitor bank's premise is that it is one wall. At 1440 the left bank ended at 1090, the main board at 1080, and the right bank at 990.

CAUSE

align-content:start packed every panel to the top of its column and dumped all the leftover space at the foot. The slack needed to go between the screens instead, so the columns end together.

The correction then failed on its first attempt, for a second reason: it was written inside a min-width:901px media block that appears earlier in the sheet, and the offending declaration is later. A media query adds no specificity. The fix only worked once it was moved below the rule it was fixing.

THE RULE IT LEFTA transform cannot change a grid track's intrinsic height, and a media query cannot win an argument it is not specific enough to have. Order matters more than intent.
06

The most-wanted link, stranded on its own line

SYMPTOM

At 1100px and at every phone width, the résumé button — the single thing most visitors are looking for — sat alone on a line of its own, right-aligned, under a ragged row of channel buttons.

CAUSE

margin-left:auto. It does exactly what you want while everything fits on one line, and the moment the row wraps it pushes the last item onto a line by itself. The row was rebuilt as a two-track grid: the channels wrap among themselves in track one, the résumé holds track two. The row can grow to two lines; it can never leave one button alone on one.

THE RULE IT LEFTTest every layout at the width where it wraps, not the width where it looks good. The wrap is where the design decisions actually get made.
07

The back button that left the site unusable

SYMPTOM

Launch a game, then press back. You land on the hub with a full-screen black overlay up, no way to dismiss it, and nothing responding.

CAUSE

The back-forward cache restores a document exactly as it navigated away — mid-cinematic, overlay showing, the "a sequence is running" flag still latched true. No code re-ran, because from the browser's point of view nothing had been reloaded. The one signal that a cached copy has come back is pageshow with event.persisted, and until that was handled the site simply broke for anyone who used the back button.

THE RULE IT LEFTAny state that makes the page unusable while it is set must be reset on pageshow. "It cannot get stuck, the timer always clears it" is false the moment a document can be frozen and thawed.
08

A line of dialogue that lied for a whole release

SYMPTOM

The ambient comms chatter announced "manifest is two case studies" for weeks after the third case study shipped.

CAUSE

Somebody typed the number two. Nothing was broken, nothing threw, and no test could have caught it, because it was not wrong when it was written — it became wrong when something else changed. That line now counts the array it is describing, and so does every other count on the site: the log totals, the bay counters, the payload readout.

THE RULE IT LEFTNever hand-write a number you already have. A hard-coded count is a comment that lies, and it lies quietly, and it lies for longer than any bug that crashes.
09

The dimmer that was never written

SYMPTOM

Opening the cargo vault produced no dimmed backdrop, and clicking outside it — the normal way to close a drawer — did nothing at all.

CAUSE

The element existed in the markup. Its CSS rule did not exist anywhere. It was therefore an unstyled div with zero height: invisible, and physically unable to receive the click it was there to catch. Its sibling drawer had a nearly identical scrim which worked perfectly, which is why nobody looked.

THE RULE IT LEFTMarkup that exists is not a feature. If a thing has a job, click it — the second copy of a working pattern is exactly where the missing half hides.
10

A button that 404'd for a month, and what it was really telling us

SYMPTOM

Inside the TechBag IQ prototype, a "View Summary" button led to a page that did not exist.

CAUSE

Not a bad link. The deployed app was a stale partial copy — ten files behind its source, and missing two files entirely, one of which was the page the button pointed at. The app's source folder is a different tree from the folder that deploys, so publishing means copying, and copying by hand means copying only what you remember touching.

The dead link was not the bug. It was the only visible symptom of a deployment process that had silently been shipping half a build.

THE RULE IT LEFTWhen a link is broken, check whether the file is missing before you check whether the link is wrong. A 404 is more often a story about how things get published than about what someone typed.

Nobody publishes these.
That is why they are worth publishing.

Anyone can list principles. The principle is the easy half and the flattering half. The bug is the part that shows you actually hit the wall, worked out why, and wrote something down so the next person — usually a future version of yourself — only has to hit it once.

Every rule quoted here is still in the source, sitting above the line it defends. You can go and read them in place.