Twenty design decisions behind itsmeray, drawn as animated blueprints and traced back to the ideas, observations and experiments that shaped them.

A A A A A

Deconstructing itsmeray

7,571 words ยท 350 sentences ยท 170 paragraphs ยท Avg: 22 words/sentence (Hemingway: ~21) ยท Flesch: 66 Standard

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.

Flows
mounts the sidebar slot and the mobile barmounts the command paletteloads theme.ts and the quote fieldloads data-prefetch.tshydrates CalloutIconsGET /api/now-playingpost titles, at buildprivate posts, after unlockGET /api/vinyls and /api/booksprivate posts, on hoverMarkdown and MDXrendered HTMLMDX importsPOST /api/viewsGET /api/story.pngfinds the quote in the postcollections, at buildeats.jsonphotography.jsonpassword, then the private listfetchJSON('/api/vinyls')fetchJSON('/api/books')Letterboxd films, at buildcollection, books, trackview countersattempt counterprivate posts, read on requestcached answerscurrently playingcollectionGraphQL querymember RSS feedLAICNVPFFLVIEAARPVBFSCSPAPDG

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
The frame
The writing
The shelves
On demand
Outside world
Paths

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.

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

1Controls get bordersexplain ยท 1 of 5

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.

2. Three greys, and not one more

1Drop the alpharedesign ยท 1 of 4

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.

3. Anatomy of a list page

1Search comes firstexplain ยท 1 of 4

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.

4. The mobile bar

1Nav within reachredesign ยท 1 of 4

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.

5. Waiting, without looking like it

CHANGING PAGESKELETON WAITS 100MSNext pageprefetched ยท 60msnew pageNext pageslow network ยท 650msskeletonnew pageAN ACTIONSPINNER WAITS 300MSUnlock a postwarm ยท 180mspressedunlockedUnlock a postcold start ยท 1,050mspressedspinnerDATA AFTER RENDERVinylsfirst visit ยท 520msskeletonrecordsVinylsrevisit ยท from the cacherecords, at once02004006008001,0001,200ms
  • 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.

6. Loading before you click

HOVER A LINK TO /VINYLSCLICKWithout prefetchloads after the clickskeletonWith prefetchloads during the hoverpage + datapage + records, at onceWith prefetcha slow networkpage + datapage + records02004006008001,000ms
  • 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.

7. Arriving slowly, leaving quickly

openclosed0100200300msREMOVED ยท 190MSOVERSHOOT ยท SCALE 1.018
  • 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 --ease has 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.

8. A portrait isnโ€™t a small landscape

1Equal area, not heightredesign

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.

9. A placeholder needs a box

1Nothing on first openredesign ยท 1 of 2

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.

10. A calendar, not a spreadsheet

1Fill, not bordersexplain ยท 1 of 5

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.

11. A record, not a picture

1A record in the sleeveredesign ยท 1 of 3

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: screen at 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.
FIRST PRESSPLAYER READYIf the disc waitednot built this waynothing movesplaysWhat it doesspins at oncespinning, still silentplaysANY LATER PRESSPlayer loadedbuffering ยท 200msplays02004006008001,0001,200ms
  • 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.

12. Nobody is always first

1Firstredesign ยท 1 of 4

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:

  1. First: measure where every card is.
  2. Last: reorder all the cards in the page at once, and measure them again.
  3. Invert: push each card back to its old spot with a transform in the same frame, so the jump is never seen.
  4. 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:

RULKIMI.COMAzrul Hakimi
FITRIMAKMOR.COMFitri Makmor
ALIFMAZLI.XYZAlif Mazli
RITH.DEVHarith Bennet
ANIQAQIL.XYZAniq Aqil
BYSHAWNCHEEShawn Chee
ZACHARYY.DEVZach Khong
MALCOLMKEE.COMMalcolm Kee
AFRIEIRHAM.COMAfrie Irham
ZAFRANUDIN.MYZafranudin Zafrin
RASHADCODES.COMFathy Rashad
HAZIQZIKRY.XYZHaziq Zikry (Qiqi)

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.

13. The backdrop that steps aside

1Out from behind contentexplain ยท 1 of 4

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

1Donโ€™t block zoomredesign ยท 1 of 2

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:

  1. Raise the fields to 16px on phones. That stopped the zoom, but the fields stopped matching the design too.
  2. 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.
  3. 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.

15. The 36px box that swallowed a panel

1Out of the 36px boxredesign

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.

16. Corners that line up

1Radius minus insetredesign

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.

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.

CHANGING PAGE IN DARK MODEPAGE SWAPBefore the fixuntil 29 Septemberold pagenew pageAfter the fixtheme stamped firstold pagenew page050100150200ms
  • 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.

18. A spring, written in CSS

100200400600msCUT ยท 340MSZOOMED ยท 150โ€“600MS1.0151.0093 โ†’ 1
  • --ease-spring: 21 samples joined by linear(), 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.

19. Notes in the margin

1Beside, not belowredesign ยท 1 of 2

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.

20. A secret is only a secret if it never ships

1The secret leaves the buildredesign ยท 1 of 4

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, and SameSite=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.

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.