Name the Feeling, Not the Pixel

I forked VS Code to round some corners. What I actually got out of it was a way of talking about interface bugs.

The first few weeks went the way these things go. "This is 6px, make it 8px." Then the same overlay again three files later, at 4px. Then a nested surface inheriting the wrong one, and a menu that matched nothing. Every fix was locally correct and the whole thing kept drifting, because a number is not a reason, and a reason is what a second person needs in order to make the same call next week.

Values, principles, moves

The vocabulary I ended up borrowing from the fork's own conventions runs in three steps.

Name the feeling. Calm, focused, consistent, delightful. Start from what the surface should feel like, before touching anything.

Find the principle it breaks. Not "this looks off", but which principle. Hierarchy is inverted. The radius ramp skips a step. Two things at the same tier don't match.

Reach for the move. A token, a tier, a step on a ramp. Never a raw value.

So the sentence is not "this is 6px and it should be 8px". It is: this overlay is rounded at the control tier. Now the fix is obvious, it is the same fix everywhere that mistake appears, and someone else can find the next instance without asking me.

Tiers survive; numbers don't

The reason this holds up is that tiers compose and numbers don't.

Once surfaces have tiers, like window, panel, and control, nesting has an answer. A control inside a panel takes the smaller radius, always, and you never have to adjudicate it again. Once radii sit on a ramp, "slightly rounder" means one step rather than 2px, and it stays coherent when the ramp is retuned.

A number encodes the outcome of a decision and throws away the decision. A tier keeps the decision, which is the part you need when the same question arrives in a different file.

It changed how I review my own work

This portfolio is the same discipline pointed at a much smaller surface. There is one row component behind every index page, a hairline that is one token in one place, and a spacing ramp with more steps than I use.

None of that is because the site is complicated. It's because the alternative, a number chosen fresh each time it comes up, is the version I have already watched drift.