Twenty design decisions behind itsmeray, drawn as animated blueprints and traced back to the ideas, observations and experiments that shaped them.
Deconstructing itsmeray
The first draft of this post was written with Claude, since it has the context of all my commit history and my design-system notes. Iโve since slowly rewritten it to match my writing style.
If Building itsmeray v6 was about the what and the when (the features, the late nights and, of course, the Safari bugs), then this one is about the why.
Iโve always been rather particular about the details of an interface. I first learnt the term pixel-perfect frontend engineer from Atif at Decube, during my (failed) job interview with him. It stuck with me, not so much because of the term itself, but because it gave a name to something Iโve always cared about: getting the little things right.
Letโs face it, most of the decisions on this site are invisible by design. Nobody visits a personal site to admire the difference between a border and a shadow (unless youโre a fellow nerd, in which case ni hao). But every single one of those choices was made at some point, usually after something looked off and I simply couldnโt unsee it. Over time, they piled up into a design-system document thatโs now around 1,400 lines long. Itโs less a set of rules I sat down to invent, and more a record of the things Iโve learnt by building the site.
Words can be a rather clumsy and verbose way to explain visual decisions, so this time I wanted to draw them instead. After all, they say seeing is believing. And since almost none of these ideas originated from me, each section ends with where it came from: the tweet, article, site or experiment that changed how I saw the problem. The aim isnโt to claim these ideas as my own, but to show how I came across them, adapted them and eventually made them part of the site.
The whole map
Before diving into the details, hereโs the whole thing at a glance: every part of the site, laid out as a small city. Each building is one part of the code, sized by how much code it actually holds, while the neighbourhoods group them by what theyโre for. The lines between them are real calls in the codebase, and pressing any of the flows at the top plays a request from one end to the other.
Pick a flow to watch it travel, or a building to read about it. Drag to pan; โ or Ctrl and scroll to zoom; drag the slider to go back in time.Swipe sideways to pan, + and โ to zoom, or expand it; the slider goes back in time.
itsmeray
An Astro site, mostly static, with a few functions on the side.
Nearly every page is HTML built ahead of time and served from a CDN. What canโt be built ahead, like the records I own, the song Iโm playing or a private post, comes from a handful of serverless functions that talk to the outside world.
Each building is one part of the code, sized by how much code it really holds; this map counts its own files, so it canโt fall behind. Pick a flow to watch a request travel, or a building to read about it.
All 24 buildings and 32 paths5 flowsevery file mapped
What each building does is written down, but how big it is gets measured. A script counts the files behind every building before each build and flags any file that no building claims, so the map canโt quietly fall behind the code whenever I add something new.
Where it came from
The map is architecture-map, a skill by almendili for turning a repository into an isometric map you can walk around. Iโve tweaked it to fit inside a postโs column instead of taking up the whole screen, and to route its lines around the buildings on its own.
How these were made
The animations below follow blueprint-animation, a skill by Oฤuz for turning a screen into an animated blueprint. A cyan scan line sweeps down and turns the real interface into its wireframe, where the parts that matter get moved around, measured and labelled, before a second sweep brings the real interface back.
It comes with two modes, and I ended up using both. Explain takes a single screen and annotates why each part is built the way it is, while Redesign takes a before and an after, and rebuilds the old version into the new one step by step.
The original skill runs inside Claude Design and reads its screens from Figma, neither of which this site has. So I ported its timing and drawing kit into a small React component that runs right here in the post. Every โrealโ screen you see is built from the siteโs own colour tokens and classes, which means it switches between light and dark mode along with everything else. The skill is licensed under CC BY-NC 4.0, so the original blueprint-animation approach is credited to Oฤuz; the adaptation and the examples here are mine.
A few of these decisions are about time rather than space though, and a blueprint canโt really show time. Those get a timeline or a curve instead, drawn in the same ink.
Each one plays while itโs on screen and pauses once you scroll past it. The bar under each animation shows its steps, and clicking on one jumps straight to it. If youโve asked your device to reduce motion, nothing plays at all; each step shows its finished blueprint instead, with a button to switch over to the real interface.
1. Borders, rings and shadows
Buttons, fields and pills draw a 1px border.
A control should assert itself as something to press.
For the first few months, everything on this site that had an edge got a 1px border: buttons, cards, modals, you name it. It worked, sure, but squint at the page and it looked more like a spreadsheet, a grid of boxes all shouting at the same volume.
The fix back in June, was to stop treating every edge the same, and to pick an edge by what kind of thing a surface is:
- Controls get a border. Buttons, inputs and pills should look like something you can press, and a crisp border is how they assert themselves.
- Cards get a ring. A content card gets
--shadow-edge, a hairline ring at 6% opacity that holds the content together without boxing it in. - Floating things get a ring and a drop shadow. Modals, tooltips and popovers sit above the page, and the shadow says exactly that, while the ring keeps their edges sharp however high they float.
Two smaller rules fell out of that. A divider inside a card uses the subtlest border, at 10% instead of the usual 20%, since a line at full weight would outweigh the faint ring around it and read as a weird sort of weight inversion. And hovering over a card adds height rather than a border, lifting it by 2px and giving it a shadow, because itโs still the same kind of surface, just a lil closer to you.
Where it came from
The whole token layer started with a tweet from Hartdrawss telling frontend developers to build a real design system once, instead of reaching for Tailwindโs default colours every single time.
The specific distinction between borders and rings came from working through the visual weight of each surface type; I donโt have a single external reference for that part. If you need convincing that a system like this is worth the effort at all, Devouring Details is a good read.
2. Three greys, and not one more
Faded grey text fell below 4.5:1 contrast.
Text colours are solid tokens; nothing is dimmed with opacity.
This one goes all the way back to day one. A Lighthouse audit on 2 January flagged the sidebarโs work dates and copyright line, which Iโd faded to 80% and 60% opacity because they โfelt quieterโ. Quieter they were, but they were also failing contrast: on this background, 60% grey comes out at about 2.5:1, nowhere near the 4.5:1 that body text needs.
Fading text with opacity is a trap, to say the least. Every new shade of โslightly softerโ quietly becomes another unofficial text level, and nearly all of them fail. So the rule now is rather blunt: text colours are solid tokens, and there are exactly three of them, namely primary, secondary and muted. If something needs to be quieter than secondary, itโs muted, and thatโs where it ends.
Dark mode needed a fix of its own. The old dark secondary sat right at the edge of passing, which left no room beneath it for a muted tier. So in August, I brightened secondary and let its old value become muted, which opened up a real third step without dropping anything below 4.5:1.
The last change is about weight rather than colour. Light text on a dark background tends to glow, so it reads heavier than the same text set dark-on-light, a phenomenon called the irradiation illusion. Since March, body text is set at weight 350 in light mode and 300 in dark, so both themes read about as heavy as each other.
Where it came from
The contrast fix came straight from that Lighthouse audit, while the third tier came from an accessibility review of the siteโs shell in August, which dug up every faded grey still lurking in the code.
As for the weight trick, I wrote up the irradiation illusion as a TIL: road-sign fonts ship a thinner cut for light-on-dark, so both read the same to a driver at speed. I first came across it in a tweet, which is where the image at the top of that TIL comes from.
3. Anatomy of a list page
Search, then filters, then results, top to bottom.
The field stays put, however many rows the pills wrap to.
Thoughts, TIL, Bookmarks, Changelog and Eats are all lists you can search and filter, and for the longest time, they couldnโt quite agree on how to do exactly that. Even with my best efforts at prompt engineering (if itโs still relevant these days), developing each module separately means the context doesnโt always transfer fully.
Some pages put the filter pills above the search bar, while others put them below it. The result count lived inside the search bar on one page and was nowhere to be found on another.
At the end of October, I realised the discrepancies and made them all standardised:
- Search, then filters, then results. Pills wrap onto more rows as the tags grow, so if they sat above the search bar, the bar would shift every time a tag got added. Put them below it instead, and the field stays put.
- The button next to the field is a peer, not a ghost. The sort toggle borrows the fieldโs border and radius, and rather than setting its own height, it stretches to match the field, so the two can never drift apart.
- The count belongs to the filters. โ3 of 44โ describes what the filters did, so it sits in the corner of the pill row and only shows up while something is actually narrowing the list.
The detail I like the most is that the two toggles mean different things on purpose. The sort button shows the current order, because an order is a state youโd want to read at a glance. The view button on Bookmarks, on the other hand, shows the view youโll be switching to, because that icon is an action. They share the same shape and sit in the same row but carry opposite meanings, so each one is labelled to match.
Where it came from
The standardisation came from comparing the pages side by side. The โpeer, not a ghostโ distinction followed from treating adjacent controls as parts of the same interface rather than unrelated elements.
The labelling rule is the same one that Let the Action Buttons in the Dialog Box Scream its Outcome makes about dialog buttons, in that a control that does something should say what itโll do. Thatโs why the view button is labelled โSwitch to list viewโ rather than just โList viewโ.
4. The mobile bar
Tabs at the top sat furthest from the thumb.
Navigation moved to a floating bar along the bottom edge.
Until 6 March, the mobile site was basically the desktop site squeezed down. There was a sticky header at the top with the navigation as a row of emoji, while everything from the desktop sidebar (profile, Spotify, quotes) sat in a footer under every page, where almost nobody would ever bother scrolling to.
The redesign moved the navigation to a floating bar at the bottom, right where your thumb already is, and turned the sidebar into a drawer you can open from the bar on any page. A day later, the bar and drawer started persisting across navigations with Astroโs transition:persist, so if you open the drawer and change pages, it stays exactly as you left it, much like a native app would.
The last fix only came much later, in August. The bar sat 1rem from the bottom of the screen, which on an iPhone lands right on top of the home indicator, so anything pinned to a screen edge now adds env(safe-area-inset-bottom) to clear it.
Thereโs one thing this animation doesnโt fix though, and Iโd rather be upfront about it. The bar holds 13 links in one row, which clears the 24px minimum for a touch target but not the 44px youโd actually want. Getting there means either splitting it into two rows or moving some of the links into the drawer, and I havenโt made that call just yet.
On the map: Sidebar & nav.
Where it came from
The drawer moves like vaul, Emil Kowalskiโs drawer for React, with the site borrowing its spring curve as --ease-drawer. The haptic tap you feel on a phone is Web Haptics, which my friend Kimi showed me.
The bottom-bar layout itself grew out of rethinking desktop navigation for a narrow screen; I donโt have one specific reference to credit for that decision. As for the touch-target gap, Expand your hit areas is the article I keep going back to.
5. Waiting, without looking like it
- What was already there: the old page, or the pressed button
- Skeleton, pulsing every 0.9s
- Spinner, one turn every 0.6s
- The answer. The delays are the site's real ones; the response times are examples.
Loading states are the decisions that readers feel the most and yet notice the least. The rule I eventually settled on is an order of preference: show content from the cache first, then a skeleton, then nothing at all, which means a pageโs own data never gets a spinner.
In other words, a spinner has to earn its place. Itโs only meant for an action you started, where the wait is unknown and nothing else on screen tells you that something is happening. Even then, it waits before it appears, so a quick answer never flashes one at you:
- Unlocking a private post waits 300ms, since the password check runs on a serverless function and a cold start can take a second or two.
- The lofi player waits for 300ms of buffering, because with audio, silence is the only other feedback you get.
- The photo lightbox waits 450ms. A blurred placeholder that sits still for too long reads as the finished photo, so past that point, it needs a lil help.
The same idea applies when changing pages, where the navigation skeleton waits 100ms before showing up, so a prefetched page swaps straight in without a flash of grey.
Even the speeds are deliberate. Skeletons pulse every 0.9s, since a pulse under a second reads as โarriving nowโ while anything slower reads as idle. Spinners turn every 0.6s; they used to turn every 0.8s or 1s, but a slower spinner somehow makes the same wait feel longer.
Where it came from
These rules came out of The perfect app has no loading states, which I bookmarked on 28 September, the very same day the loading states got their overhaul. It makes the case better than I ever could: the best loading state is the one you never need to show.
6. Loading before you click
- The page youโre on
- The next page and its data loading in the background
- Skeleton, from 100ms after the click
- The new page. The 100ms is the siteโs; the hover-to-click gap and load times are examples.
Thereโs a gap of a few hundred milliseconds between pointing at a link and actually clicking it, and the site puts that gap to good use. Every internal link is prefetched the moment you show intent, be it hovering over it or tabbing to it with the keyboard. It doesnโt happen the moment a link scrolls into view though, since a list page has dozens of links, and loading all of them just because they happened to be on screen would be a waste.
The page itself is only half the story. Some pages render from data they fetch after they arrive: the vinyls come from Discogs, the readings from Hardcover, and the list of private thoughts only appears once youโve unlocked it. A small script warms up that data on the same hover, so by the time you click, both the page and its data are already here, and the page renders straight from the cache without a skeleton in sight.
Both kinds of request are shared too, so hovering over the same link ten times still only costs one fetch.
One thing the site deliberately doesnโt do is prerender pages in the background. The siteโs router fetches each page by itself on click, so a prerendered copy would never get used; it would just build the page, and run its scripts, a second time for nothing.
On the map: the Open vinyls flow.
Where it came from
Mostly trial and error. Prefetching went in on day one, on hover, and then changed its mind five times (viewport, page load, hover, viewport again) before settling back on hover in June, once list pages started firing off dozens of requests on scroll. The page half is Astroโs own prefetch, set to โhoverโ, while the data half is mine, added in the same loading-state overhaul as section 5.
7. Arriving slowly, leaving quickly
- Opening: 300ms on
--ease-bounce, overshooting slightly before it settles - Closing: 180ms on
--ease, with no overshoot - The browser's bare
ease, not used: 18ms into a close it has moved 9%, where--easehas moved 35%
Every modal on the site shares the same timing, be it the password prompt, the brain dumps, the share card, the command palette, the lightboxes, or the book and network cards. A modal pops in over 0.3s with a slight overshoot, and leaves over 0.18s with none. The practical takeaway is simple: give an arriving element enough time to establish itself, but donโt make someone wait for an element theyโre already trying to dismiss.
Leaving is faster than arriving on purpose. When something opens, youโre waiting to see it, so a little time and a little bounce help you follow where it came from. But by the time you close it, youโre already done with it, and every millisecond of exit is just another millisecond standing between you and the page.
The curve matters just as much as the duration. The browserโs built-in ease speeds up before it slows down, so a press feels like it starts late, whereas the siteโs own --ease moves on the very first frame. Just 18ms into a close, it has covered 35% of the distance, while ease has only covered 9%.
Funnily enough, all of this only landed on 9 November, the very same day I was writing this post. Modals used to take 0.38s to open and 0.25s to close, and --ease used to start slowly as well. Shortening them uncovered a sneaky bug, where reopening a modal mid-close would get it hidden by the close timer that was still pending. So the script now removes a modal at 190ms, one frame after its exit ends, and a reopen cancels that timer altogether.
Where it came from
Almost everything I believe about motion comes from Emil Kowalski and his animations.dev course, which I bought during this build. The latest round of tightening (faster exits, an ease-out --ease and quicker spinners) came from a short list of tips on making an app feel faster that I came across on 9 November, though I canโt for the life of me remember where. 12 Principles of Animation is also a good map of where web motion borrows from Disneyโs animators.
8. A portrait isnโt a small landscape
At the same height, a portrait covered under half the area.
Every tile now fills the same area, so a portrait carries as much weight as a landscape.
In June, the photography page swapped its rather cliche masonry grid layout for a reel, where photos stream along a curve and the one at the centre lifts forward. Within hours of shipping it, something looked off: the portraits looked smaller than the landscapes, even though they were all the same height.
As it turns out, they were smaller. Every tile was 250px tall with its width following the photo, so a 2:3 portrait covered about 41,700pxยฒ while a 3:2 landscape covered 93,750pxยฒ. In focus, a portrait carried less than half the visual weight of a landscape, and a reel is all about the photo in focus.
So instead of holding the height constant, the reel now holds the area constant. Every tile fills 90,000pxยฒ: a landscape comes out at about 367ร245, barely changing at all, while a portrait comes out at about 246ร367, growing into the empty space above and below the reel. Very tall or very wide photos are clamped though, so a panorama doesnโt end up as a sliver.
The reel has a few other details that are worth a sentence each:
- Depth is real 3D, not stacking order, so a tile rising to the front crosses its neighbours smoothly instead of popping over them.
- The reel slows down on narrow screens, where the same speed would whip photos past too fast to see.
- The scrub tick is capped at about 35 a second, so a fast flick stays a run of ticks rather than a buzz.
- With reduced motion on, thereโs no reel at all, and you get the original masonry grid instead.
Where it came from
The reel was inspired by a tweet by Bardhyl Bytyqi. I noticed the imbalance after the reel shipped: equal heights looked consistent in code, but not in the amount of visual space each photograph occupied.
9. A placeholder needs a box
The blur filled a frame that had no size yet.
The frame is sized from the photo's 32px placeholder before the photo loads.
Open a photo, and while the full-size version downloads, youโre supposed to see a blurred preview of it made from a tiny 32px copy. For two whole months, that preview was mostly invisible.
The blur was laid over the frame that holds the photo, but the frame took its size from the photo. So before the photo loaded, the frame had no size at all, and neither did the blur. Moving on to the next photo was even worse, since the frame kept the previous photoโs shape, so a portraitโs blur would get cropped into a landscape box.
In September, the frame started sizing itself from the incoming photoโs tiny copy (which the reel has already downloaded anyway) before the full photo arrives. Once the photo loads, the frame lets go and fits it exactly, while the old photo hides in the meantime, since it no longer fits the frame.
The rest of the lightbox tries to make the blur rare in the first place. Hovering over a photo for about 80ms starts downloading the full version, so itโs often ready before you even click. And if it still isnโt ready after 450ms, a spinner appears, for the reason in section 5.
Where it came from
The lightboxโs opening animation is inspired by Raphael Salajaโs Cambio, which the first version was built on in March. In May I rebuilt it with Motion: Cambioโs bounce changed with the size and position of whatever you clicked, and a fixed spring from the centre makes every lightbox on the site open the same way.
The blurred preview follows a familiar perceived-performance pattern; the sizing fix and the way it fits into this lightbox came from working through the implementation. Base64 & perceived performance is a nice deep dive on why a tiny blurred preview makes a page feel faster than it actually is.
10. A calendar, not a spreadsheet
A day with a purchase gets a faint accent fill.
A border on 42 small cells reads as a table, and as noise.
The vinyls page had stats for how much Iโd spent and how often I bought records, but nothing about when. So in September, it got a purchase calendar that shows one month at a time, with that monthโs purchases listed beside it.
A grid of 42 small cells is surprisingly easy to get wrong, so a few rules keep it in check:
- A day with a purchase gets a faint fill, never a border. A border on a 35px cell reads as a table, and 42 of them read as noise, whereas fills alone let the busy days read as a shape.
- The hover ring is drawn inside the cell, and only on hover. A ring on the outside would eat into the 4px gap between cells, and a ring at rest would just outline every box all over again.
- The day and the list are linked both ways, so hovering over a day lights up its purchases, and hovering over a purchase lights up its day.
- The row is the unit. One purchase can cover several records, and back when each album lit up on its own, a single haul read as three purchases. Now the whole row tints as one, with a small gap so two purchases on the same day never merge.
- Every month draws six weeks, even when it only needs five, so the panel doesnโt change height as you page through.
The stats got the same honesty pass that week. โPriciest recordโ used to rank whole purchases, so a three-record haul at RM 629.70 won, as if a single record had cost that much. It now ranks single-record purchases only, which makes the honest answer Oppenheimer at RM 480. On top of that, whenever the Discogs request failed, the page used to quietly fill itself with sample data, including Kind of Blue, a record I donโt even own. Now, a failure simply owns up to being one.
Where it came from
This one was my own idea, since I needed a proper way to keep track of how much Iโve been spending on vinyl.
11. A record, not a picture
On its own, a cover is just a square picture.
A disc sits behind it, peeking out 20%, wearing the cover as its label.
Back in March, the vinyls page swapped a scattered, draggable layout for a plain grid. I did so because it looked hella messy and I wanted to give the visitors a chance to listen to my vinyl collection. The problem with a grid of album covers though is that it looks like a grid of pictures, since nothing about a square image says record. So each card gets built up in layers until it does:
- A disc behind the sleeve. A record sits behind every cover, peeking out of the top by 20% and wearing the album art as its centre label. Both use the same image at the same sizes, so the browser fetches the cover once and uses it twice.
- Plastic over the art. On top of the cover sits a scan of a real plastic sleeve, which is almost entirely black save for a streak of glare down the spine and along the top edge. Itโs laid over the art with
mix-blend-mode: screenat half opacity, and since black changes nothing in screen mode while light gets through, the black disappears completely and all thatโs left on the cover is the glare. - Out to play. Press play and the disc slides further out to 45% above the sleeve, spinning once every three seconds, the same speed as the turntables elsewhere on the site.
- Pressed, but nothing on the page has changed
- The disc spins, before thereโs any sound
- Spinning and playing. The disc speed is real; the wait times are examples.
Each record on the vinyls page can play a song from it, which comes through YouTubeโs player at about 150KB of script plus a set of cookies. Even though itโs a handy feature, I admit that most visitors (if any) are unlikely to press play, so that script only loads the first time someone does.
That does create a gap, though. On the first press, the player takes a moment to arrive, and a record that sits still during that moment looks like a broken button. So the disc starts spinning the instant you press play, and the sound only joins in once the player is ready. The same goes for a slow network halfway through a visit, where the disc always answers first.
The disc remembers where it was, too. Stop a record and it freezes at that angle, then play it again and it picks up right where it left off instead of snapping back to the start. Itโs a small thing, but itโs what makes it feel like a record rather than just another icon.
On the map: Vinyls.
Where it came from
The page itself grew out of Displaying my vinyl collection from the Discogs API. The spin-first idea comes from the same instinct as the loading rules above, and as The perfect app has no loading states: answer the press first, and catch up after. As for the sheen, it was inspired by a design I came across on Behance, since I wanted the cards to have a slightly realistic, premium look.
12. Nobody is always first
Before anything moves, every card's position is measured.
Those twelve boxes are where the cards start.
The Networks page lists twelve people (so far) whose work I admire. Since 10 March, the order is shuffled on every visit, so nobody is permanently at the top, and the order doesnโt imply any preference or bias.
Shuffling is the easy part; making it look good is where it gets tricky, and thatโs done with a technique called FLIP:
- First: measure where every card is.
- Last: reorder all the cards in the page at once, and measure them again.
- Invert: push each card back to its old spot with a transform in the same frame, so the jump is never seen.
- Play: let go of the transform, and watch every card glide from where it was to where it now belongs.
The details are what make it feel right. Each card waits a tiny random delay of up to 25ms before moving, so the grid shifts like a hand of cards rather than a single block. They glide over 0.45s with a soft overshoot, and the previous order is remembered for the session, so the glide always starts from what you last saw. On a first visit, thereโs nothing to glide from, so the cards deal in one after another instead. Try both here, using the pageโs own timings:
Safari is the exception because itโs Safari. It gets the simple one-by-one entrance and no shuffle at all, simply because the browser support just isnโt there.
Where it came from
The page itself, shuffle and all, came from a tweet by Alexey Taktarov showing off a section of his site dedicated to his friends. FLIP is the kind of thing that takes five minutes to describe and five hours to get right, and the CSS-Tricks write-up is still the clearest explanation of it that Iโve come across.
13. The backdrop that steps aside
The backdrop fades out every glyph behind content.
So its text never surfaces behind anything competing for your eye.
On a wide screen, the space around this site is filled with faint text: the quotes from my sidebar, set in small uppercase and drifting slowly. Move your cursor over it and more of it reveals itself. It went in on 27 August, replacing a plain dot grid.
A backdrop made of text has one obvious problem though, in that text behind text is unreadable. And because the cards on this site are rings with no fill, the quotes would show straight through them. So the field cuts itself out from behind anything that matters:
- It cuts out behind content, walking the page for the outermost elements that carry visual weight (anything with text, an image, a fill or a shadow) and fading out every glyph inside them.
- A ring counts too. Ring-only cards have no fill to detect, so itโs the box-shadow that gives them away.
- The reading column is cleared top to bottom, so no glyph threads through the gaps between paragraphs.
- Each cut-out is trimmed to whatever clips it. The tools marquee in the sidebar keeps its off-screen icons laid out past its edge, and before the trim, those invisible icons cut a bar through the margin beside it.
It also has to be cheap. Every glyph is redrawn each frame, which is what lets the text drift and ripple in the first place, so it sticks to a rather strict budget. The idle drift runs at about 30fps, and past 8,000 glyphs, the type gets bigger instead of the field getting sparser. All in all, it costs about 6ms a frame on anything from a laptop screen up to 4K.
On phones and under reduced motion, it doesnโt run at all since itโs useless given the viewport size. The principle is that decorative detail should make room for content, not compete with it; if the effect gets in the way of reading or costs too much to draw, it should step aside.
14. Zoom, without blocking zoom
Capping the viewport stopped the jump, and blocked pinch-zoom too.
The cap came out, and the fieldโs text went up to 16px instead.
Tap a search field on an iPhone, and Safari zooms in if the fieldโs text is under 16px. This siteโs base size is 14px, so every single field triggered it, and Safari never bothers zooming back out.
This took three tries, all within a few days in August:
- Raise the fields to 16px on phones. That stopped the zoom, but the fields stopped matching the design too.
- Cap the zoom with
maximum-scale=1. That kept the design intact, but on Android it also blocks pinch-to-zoom for every reader on every page, all just to protect four fields. That fails WCAGโs rule on resizing text, so the cap came out the very same day. - Measure big, draw small. The fields now are 16px, which is what Safari checks, while a CSS transform shrinks them back down to the designed 12.6px, which it doesnโt check. Theyโre drawn wider to begin with, so they still fill their box once shrunk.
The third one is the kind of fix I love, since it gives the browser what it asks for while giving the reader what the design asked for.
Where it came from
The cap in step 2 came out during an accessibility review of the whole site shell. The final workaround came from testing how Safari determines the field size, then separating the size it measures from the size the reader sees.
15. The 36px box that swallowed a panel
A compositing hint on its wrapper trapped the 290px panel inside 36px.
The hint moved to the button, and the panel answers to the viewport again.
In July, iOS Safari was making the icons in the mobile bar jiggle as you scrolled. The fix was a small rendering hint, translateZ(0), which tells the browser to keep each icon as its own image instead of redrawing it.
One of those hints went on the wrapper around the lofi playerโs button. As it turns out, a transform on an element, even one that moves nothing, makes it the frame that its fixed-position children are placed against. So the playerโs 290px panel suddenly believed it lived inside a 36px box, and the bar, which clips anything that spills out of it, simply cut it away.
The fix in August was to move the hint from the wrapper onto the button itself, but the lesson I took away is a broader one: before adding transform, filter, will-change or backdrop-filter to anything, check whether something inside it is fixed-position. Itโs also the reason why the siteโs tooltips live outside the things that trigger them, so nothing a parent does can ever trap them.
Where it came from
Hard experience, mostly. The bug surfaced in the same August accessibility pass as section 14.
16. Corners that line up
A photo with the cardโs own radius left a fat gap at the corner.
The photoโs radius is the cardโs minus the inset, so both curves share a centre.
The cards on the eats page hold their photo slightly inside the card, like a print in a mount. The cardโs corners are rounded at 0.75rem, the photo sits 0.375rem in, and the photoโs corners are rounded at exactly the difference, 0.375rem.
That subtraction is the whole trick. When the inner radius equals the outer radius minus the gap, both curves share one centre, so the gap stays the same width all the way round the corner. Give the photo the cardโs own radius instead and the gap swells at every corner, the kind of thing you canโt quite put your finger on, but you can definitely feel that somethingโs off.
Where it came from
This one is straight from Jakub Krehelโs Details that make interfaces feel better. On 11 March, I went through it and applied what the site was missing: concentric corners on the Spotify widget, balanced heading wraps, numbers that donโt jitter as they change, and a hairline outline on images. The eats cards inherited the rule when they arrived in September.
17. A theme that sweeps in
- To dark:
circle(0% โ 150% at 50% 100%), from the bottom edge, 1.2s on--ease - To light: the same circle from the top edge
- With reduced motion: no transition at all, the theme just swaps
Switching between light and dark doesnโt just snap. The browser takes a snapshot of the page, and the new theme is revealed over it by a circle that grows to cover the screen over 1.2s. Since 12 January, it alternates too: going dark, the circle rises from the bottom edge like dusk, and going light, it drops from the top.
With reduced motion on, none of that happens and the theme simply swaps, which took more care than it sounds. The siteโs global reduced-motion rule works by shrinking every CSS animation down to almost nothing, but it canโt reach the layers the browser creates for this kind of transition. Left alone, the wipe would have played at full length for exactly the people who asked it not to, so the theme script checks the setting and skips the transition entirely, with the CSS naming those layers explicitly as a backstop.
- The page, in dark mode
- One frame in light mode (about 17ms), while the new page hadnโt been given its theme yet
The other bug was much harder to spot, because it only lasted one frame. In dark mode, changing pages would occasionally flash the new page in light mode. The router builds the incoming page from the serverโs HTML, which has no idea which theme you picked, so for that one frame, the page had no dark class, and moving focus back to the link you clicked forced the browser to draw it. Since 29 September, the theme is stamped onto the incoming page before it swaps in, so it never arrives without one.
Where it came from
The circle wipe is inspired by Zach Khongโs old site, the very same one that got this whole rebuild started. Itโs built on the browserโs View Transitions API.
18. A spring, written in CSS
--ease-spring: 21 samples joined bylinear(), ending on 1 at 340ms- The real spring (stiffness 400, damping 32, mass 1), still creeping long after 340ms
The site has a few segmented controls, i.e. two or three options with a pill that slides behind the chosen one. The career toggle in the sidebarโs work timeline is a React component, and its pill rides a real physics spring from the Motion library. The others (the vinyl calendarโs month/year switch, the toggles in the story-card dialog and the bio tabs on the Media page) are plain CSS, and loading React into each of them just to get a spring would be a lot of JavaScript for one tiny slide. The takeaway: the controls should feel consistent, but that doesnโt mean they all need to share the same implementation.
CSS easing curves are usually written with cubic-bezier(), which only has two control points, so it can roughly imitate a spring but never quite trace one. The practical challenge was to keep the same motion language without paying the JavaScript cost of a shared animation library. The newer linear() function can, though. Give it a list of points and it joins them with straight lines, which is why --ease-spring is the real spring, sampled at 21 points. With enough points, the straight lines become indistinguishable from the curve, and a CSS pill moves exactly like the React one.
Two numbers explain the shape. The springโs damping ratio is 32 รท (2 ร โ400) = 0.8, just under the point where it would stop overshooting, so it overshoots once by 1.5% and settles without a wobble. And in theory, a spring never really stops; it keeps creeping towards rest forever. By 340ms though, itโs within half a pixel of where itโs going and the rest only looks like lag, so the samples stop at 340ms and end exactly on 1.
That makes the duration part of the curve itself. Every use is written as transform var(--duration-spring) var(--ease-spring), since a shorter duration would squeeze the overshoot into a snap, and a longer one would stretch the lag right back in.
Where it came from
19. Notes in the margin
Footnotes sat at the bottom, a long scroll from their numbers.
On wide screens each note moves into the margin, beside its number.
Footnotes on the web are awkward. You tap a tiny number, jump all the way to the bottom of the post, read the note, then jump back up hoping you land where you left off. So since 16 March, posts here turn their footnotes into sidenotes instead.
On a wide screen with no table of contents in the way, each note floats into the right margin, beside the line that mentions it. A small script lines its top up with its number, but never closer than 8px to the note above it, so two notes that sit close together stack instead of overlapping. The notes stay hidden until theyโre placed, so you never see them jump into position, and hovering over a note also highlights its number in the text.
When there isnโt enough room, like on a phone or beside a table of contents, the same notes sit inline as small cards right where theyโre referenced. In print, they become bracketed text instead. And a post that prefers plain old footnotes can opt out with a single line of frontmatter.
On the map: Markdown plugins.
Where it came from
Notes beside the text are the style that Edward Tufte made famous in his books, and Tufte CSS brought it to the web. I came across the approach through Tufteโs work and later through Tufte CSS, which adapts the marginal-note layout for the web.
20. A secret is only a secret if it never ships
The password's hash and signing secret shipped inside the site.
On 23 March checking moved into a server function, and the secret with it.
Some posts here are private, tucked behind a password. Getting that right took five fixes over ten months, with each one closing a leak that the one before had missed. The takeaway is that privacy isnโt just a password prompt: the content, metadata, rendering path and supporting APIs all have to respect the same boundary.
- January: The first version checked the password in the browser. It worked, but it also meant the passwordโs hash and the key that signs the unlock were shipped inside the site, for anyone who bothered to open the developer tools.
- 23 March: The check moved into a server function, and the secret went along with it. The private pages themselves were still built as static files though, so anyone who knew the address could load one.
- 28 March: Private pages started rendering on the server, and only after a cookie checks out. Itโs
httpOnly, so no script on the page can read it, andSameSite=Strict, so another site canโt send it on your behalf. The password check also got a limit of 10 tries every 15 minutes. - 29 September: That fix came at a cost: every post was being rendered on request, so public posts were paying for privacy with slower loads. Public posts went back to being static files served from the CDN, and only the private ones render on demand, since a private postโs address simply has no file behind it and the request falls through to the server.
- 29 October: One leak was left: private postsโ titles, tags and slugs were still in every page, both in the command paletteโs data and hidden in the Thoughts list. Now both fetch them from a cookie-gated API after you unlock. The changelog also drops any commit that names a private post, and the view counter wonโt even confirm that one exists.
On the map: the Unlock flow.
Where it came from
Every one of these fixes was about tightening security, since the private posts are very personal and having them leaked would be dangerous. The last leak turned up when I asked Claude for a round of suggestions on the app, and it flagged the titles still sitting in the page source.
Writing it down
Itโs almost been a year since I kickstarted the journey of revamping my portfolio website and turning it into a digital representation of myself. It really isnโt a hyperbole to say that this project made me fall in love with programming all over again, and rediscover my appreciation for the art and craft of building pixel-perfect interfaces.
Building with AI doesnโt have to mean settling for slop. The tools may have changed, but the level of craftsmanship you bring to the table is still very much a choice. Ultimately, itโs in your hands to decide what you want to create and how much thought you put into it.
None of these rules were planned. Each one is the written-down version of a moment where something looked off and I had to work out why. Writing them down is how I make sure I donโt have to learn the same lesson twice. It also means that the next page I build starts with a set of answers rather than a blank canvas.
Visualising them was a different exercise altogether. With the help of almendiliโs skills and blueprint-animation, I turned these otherwise abstract design decisions into animated blueprints. What started as a way to document the decisions became another way to examine them. A rule you canโt explain clearly is probably a rule you havenโt fully understood yet. Having to translate each one into a visual representation helped me refine a couple of them along the way.
The design system is still evolving, and I suspect it always will. These twenty blueprints arenโt meant to be a definitive set of rules, but a snapshot of the thinking that has shaped itsmeray so far. At the very least, the next time something looks off, Iโll have somewhere to start.

