The Details Are the Software

Photo by Art Institute of Chicago on Unsplash

There is a particular kind of itch that only afflicts people who make things. You finish a piece of work, you ship it, you move on — and then weeks later your eye snags on some tiny detail that is very nearly right but not actually right, and from that moment you are no longer a free man. You will think about it on the walk to the office. You will think about it in the shower. You will think about it when your attention really should be on something else. The detail in question will be something that ninety-nine people out of a hundred would never notice, and the hundredth person would notice and immediately not care. But you noticed, and you care, and that is the whole problem.

This week’s itch was Tugboat’s menu-bar icon.

A tool nobody else uses

Some context. Tugboat is an internal-only utility — it never shipped, it has no product page, and the user base volume is one, me. It exists because Apple gutted the LaunchServices private interface that used to let an app flip itself in and out of the Dock at runtime. macOS 26 took that away, so Tugboat does the job a different way: it sits in the menu bar, shows me every Jorvik app, and lets me hide or reveal each one from the Dock and commandtab. It manages the Dock, hence “Tugboat”… see what I did there?

Because it manages the Dock, its menu-bar icon is a little representation of the Dock. A rounded rectangle for the screen — drawn as a thin stroked outline — and a single rounded bar tucked just inside one edge for the Dock itself. Eighteen points by fourteen, a bar two points thick. Tidy. Recognisable. Done.

Except the bar was always along the bottom.

The Dock does not always live at the bottom

Here is the thing I had ignored when I drew that icon: the macOS Dock can live on three edges. Bottom, left, or right. It’s right there in System Settings, and plenty of people — people with wide monitors who’d rather not waste vertical pixels — move it to the side and never look back. But I had the Dock at the bottom in my icon, the default position, because it seemed the right thing to do at the time.

Here’s the embarrassing part. I am, and have always been, a Dock-on-the-left person. My Dock has lived on the left edge of the screen for as long as I can remember. Which means the icon I’d drawn wasn’t occasionally wrong on some off-day when I’d moved the Dock for a lark — it was wrong the entire time. Every single day, sitting there in my own menu bar, a little picture of a Dock at the bottom of a screen, while my actual Dock sat resolutely down the left-hand side just inches away from it. I’d drawn the default and never looked again, and the one configuration I personally use was the one it got wrong.

It was lying to me. Cheerfully. In miniature. And it had been doing so to my face for weeks.

Now, in the grand accounting of software defects, this does not register. Nobody filed a bug, because nobody else has the app. The icon being wrong changed no behaviour, lost no data, cost no money. If I had decided to leave it, the universe would have continued on undisturbed. But I knew. And once you know, “it doesn’t matter” stops being a statement of fact and becomes a small daily negotiation with yourself about the kind of work you’re willing to put your name on.

So I fixed it.

How an icon learns where the Dock is

The good news is that macOS doesn’t make you guess. The Dock keeps its configuration in its own preferences domain, com.apple.dock, and the edge it’s pinned to lives in a key called orientation — a string that reads left, right, or, when it’s anywhere else or hasn’t been set, the sensible default of bottom. One call to CFPreferencesCopyAppValue and you know, definitively, where the Dock is right now.

Reading it once is easy. The interesting part — the part that earns the phrase “in real time” — is noticing when it changes. You don’t want an icon that’s correct at launch and then slowly drifts out of step with reality the moment I drag the Dock somewhere new. An icon that’s right once is arguably worse than one that’s always wrong, because it has earned a trust it then quietly betrays.

The Dock is polite enough to announce itself. Whenever its preferences change — position, size, autohide, any of it — it posts a distributed notification, com.apple.dock.prefchanged, that anyone listening can hear. Subscribe to that, and the moment the orientation flips you get a tap on the shoulder. Re-read the key, and redraw. (I wire the same handler to the light/dark-mode and screen-reconfiguration notifications too, so the icon repaints correctly no matter which way the world shifts under it.)

And redrawing is where the earlier work paid off. Every Jorvik menu-bar icon is composed as a single image with a drawing handler — a small block of code that runs every time the system needs to paint the icon, rather than a fixed picture baked once at startup. We adopted that pattern originally so the icons could adapt to light and dark mode, to wallpaper-tinted menu bars, to all the ways macOS now quietly re-tints things under your feet. But a drawing handler that re-runs on demand turns out to be exactly the right shape for this problem too. The handler reads the current orientation and draws the bar on the matching edge: along the bottom, down the left, down the right. Three small geometry cases over one shared glyph — not three separate pictures, just one that knows where to put its bar. Tell it to repaint when the Dock moves, and the icon simply follows.

Drag the Dock to the left edge of the screen, and the bar in the menu bar slides to the left edge of its little rectangle, instantly, as if the icon had been watching the whole time. Which, in a sense, it now is.

The whole change is a handful of lines. A key read, an observer, three drawing cases instead of one. It took an afternoon, most of which was spent making sure the orientation cases lined up with the actual geometry and that I hadn’t put the right-hand Dock on the left like some sort of mirror-world saboteur. The payoff is an icon that tells the truth, every time, without being asked.

Hand-crafted versus the other thing

I want to dwell on why this is worth an afternoon, because it’s the crux of something I think about a lot.

We are now firmly in the era where code can be generated by the yard. Ask a machine for “a menu-bar app that shows the Dock,” and it will hand you something that compiles, runs, and draws a little Dock at the bottom of the screen. It will look finished. It will demo beautifully. And it will draw the bar at the bottom forever, because the bottom is the default, the common case, the answer that’s right often enough to look right in a screenshot.

That’s the tell. AI slop — and I use the term with affection for the genuinely useful tool underneath it — is software that handles the common case and stops. It’s plausible. It’s the shape of correct. It nails the eighty per cent that everyone sees and silently abandons the twenty per cent that only shows up when someone actually lives in the thing. The Dock-on-the-left user. The cursor that slips off a display that doesn’t physically exist. The rainbow logo sitting a few pixels proud of the real one.

Hand-crafted code is what happens when someone keeps going past “looks finished.” It’s not cleverer code — the orientation fix is, frankly, boring. It’s more cared-about code. The difference between the two isn’t visible in any single line. It’s visible in the accumulation of decisions where someone chose the correct answer over the convenient one, knowing nobody would ever check.

The irony, which I’m well aware of, is that I built this fix with AI assistance, the same way I build most things now. The tool isn’t the problem. The tool is excellent. The question is whether you stop where the tool would stop, or whether you’re the one who looks at the confident little icon, knows the Dock is on the left, and refuses to let it lie.

The other little things nobody asked for

Once you start paying this kind of attention, you can’t stop, and the Jorvik suite is quietly full of details that exist for no reason other than that they’re correct. A quick and non-exhaustive tour, then, of things you were never meant to notice.

The menu-bar pills are grey, and you can’t change that. Several of the apps offer an optional coloured background “pill” behind their icon, for contrast against busy wallpapers. The first version let you pick the colour. It was a disaster — half the colours vanished against a tinted menu bar, and the pill kept fading into alert states. So we threw out the colour picker entirely and fixed the pill to two specific greys, one for light mode and one for dark, chosen because they contrast reliably against any bar. Fewer options, more correct. A setting removed is sometimes a feature.

RainbowApple measures the real Apple logo rather than guessing where it is. RainbowApple lays the classic six-colour 1977 rainbow back over the monochrome Apple logo at the left end of your menu bar. To pull that off convincingly, the overlay has to sit exactly on top of the real thing — same position, same size, to the pixel — or the illusion collapses and it just looks like a sticker someone slapped on slightly wonky. The easy way would be to hard-code it: the Apple menu sits about so-many points in from the left, the menu bar is twenty-two points tall, paint the rainbow there and call it done. And that holds right up until it doesn’t — a notched display, a scaled resolution, a taller-than-standard menu bar, and suddenly your rainbow is floating a few pixels off, which on a glyph that small reads as immediately, glaringly wrong. So instead of assuming, RainbowApple asks. It queries the macOS Accessibility API for the actual on-screen frame of the Apple menu item — its real position and its real size, as the system reports them at that instant — and sizes and places the overlay to match precisely, the logo scaled to a fixed fraction of the measured height. Switch spaces or rearrange your displays and it re-asks and re-aligns. There’s a fall-back that computes a position from the menu bar’s height for the case where you haven’t granted Accessibility permission, but the precise, screen-reading path is the one that runs.

ActiveSpace builds an invisible fence for your cursor. This one’s my favourite, because the bug it prevents is so esoteric. On single-monitor Macs, ActiveSpace conjures a virtual display to do its work, and that virtual display happens to share a screen corner with your real one. macOS, being helpful, lets the cursor slip diagonally across shared corners — which meant your pointer could wander off into a display that doesn’t physically exist. So there’s a small mechanism that pins the cursor to the real screen for as long as the virtual one is alive. A fence around a field nobody can see.

Tugboat will never relaunch your Dock without permission. Relaunching the Dock causes a visible flicker, and it’s the kind of thing a lazier tool does constantly. Tugboat is built in two layers precisely so the everyday action — hiding and showing apps — never touches the Dock process at all. The only thing that can trigger a Dock relaunch is explicitly un-pinning an app, and only because you clicked the button that does exactly that. The flicker is opt-in.

The menu order is identical in every app. About at the top, the app’s own actions in the middle, Settings near the bottom, Quit at the end. Every single one. So that muscle memory built in one app works in all of them, and you never have to look.

None of these were requested. None of them are in a changelog anyone reads. Each of them cost real time that could have gone to a feature. And collectively they are the entire point.

The cost, and the trade

The Dock-orientation fix was an afternoon for a tool one person uses, to correct a detail that changed no behaviour and that almost nobody could ever have seen. By any reasonable productivity metric it was a waste of time.

I don’t think it was. I think it was the opposite — I think these are the only afternoons that really count. Anyone, now, can generate the eighty per cent. The machines are very good at the common case, and getting better by the month. What they can’t do, and what I’m increasingly convinced is the whole of the job, is care about the last bit — the Dock on the left, the cursor wandering off a cliff that isn’t there. The details are not decoration on top of the software. The details are the software. Everything else is just the part that compiles.

So the little boat’s icon now knows which way the Dock is facing, and it’ll tell you the truth the instant you move it. Nobody asked. Nobody will notice.

I noticed. That’ll do.