Forty-Seven Palettes

For about a year I've been building Jared, a personal assistant that runs on my own hardware — a local-first multi-agent system with long-term memory, a proactive daemon, and opinions. This year it got a new face. This is a short account of how that went, including the part where I gave it fifty colour schemes and couldn't read most of them.

Jared got a second face

The first interface was an ordinary app: a sidebar, a chat column, twenty-nine React components accumulated one feature at a time. It worked. It also quietly decided what Jared was — a chat window with panels bolted on — because the shape of an interface argues for a shape of thinking.

The second one starts from a different premise. Seven domains — surveillance, home, vitals, ledger, recall, cadence, dialogue — and a canvas that composes itself per turn. Ask about training and the canvas puts up training panels. The layout is a response, not a destination you navigate to. Composition is data, and Jared emits it.

That reframing is the actual improvement. The chat is still there, but it stopped being the product.

The design system did the half I'm bad at

The other change was that V2 doesn't own its look. It installs one — @sesebon/ui, a brutalist vocabulary I'd been extracting alongside it: pure-black surfaces, monospace numerals, hairline borders, zero radius, one amber accent, red reserved strictly for alerts.

The part worth mentioning is how it's packaged. Thirty-four components, and each ships a .prompt.md next to its code saying what it's for and when to reach for it — plus a skill file describing the token contract and the rules of the house. It's a design system written to be read by an agent as much as by me.

The effect is hard to overstate for someone working alone. I stopped describing what a panel should look like. I'd name the domain and the data, and get something already in the house style, because the constraints were legible to the thing doing the work. Making Jared fashionable stopped being a design task and became a composition task.

Which is exactly the kind of leverage that makes it easy to ship fifty of something without looking at any of them.

I hoarded colour like a magpie

Somewhere in there I started collecting palettes. Anyone who has fallen into this knows the pattern — you find a five-swatch palette with a nice name, you save it, and it costs nothing, so you do it forty-seven more times.

Then I fed the hoard into a generator, got forty-seven themes out, added them to the skin picker next to the three I'd made by hand, and admired the grid. Fifty skins. Lovely.

What I never did was read one. A few seconds each in the picker, judging the swatch rather than the page behind it — and a swatch is four squares of colour with no words on it.

I had been collecting colours, not reading them.

When I finally measured, thirty-nine of the forty-seven were below the readable threshold. Eighteen were so far below that body text was effectively invisible — one sat at 1.13 against a bar of 4.5.

Five colours, nine jobs

The cause turned out to be mechanical rather than a matter of taste, which was a relief and also a little embarrassing.

Each palette had five colours. The generator assigned them to roles by position — first colour is the background, second is the heading, and so on — and never measured what came out. Three things followed:

The system has five levels of text emphasis. Five colours, no spare. So "body" and "supporting" got the same hex, and "caption" and "placeholder" got the same hex, in forty-two of forty-seven themes. A five-step hierarchy quietly collapsed into three.

Nothing sorted by lightness. In twenty-four of forty-seven, the palette's brightest colour landed on the accent — the one role whose entire job is standing out from the background.

And only seventeen of thirty-eight tokens were ever re-bound, so light themes were drawing chart colours still tuned for a black ground.

The palettes were never the problem. Assigning colour by position and not looking was the problem.

Every check passed and it looked worse

The fix is to stop taking ink from a palette slot and start computing it against each theme's own background. Walk each role away from the surface until it reaches the contrast it owes.

My first attempt held hue and saturation and moved only lightness. Every check passed. The themes looked worse, and it took me an embarrassing minute to see why.

HSL saturation isn't perceptual. A pale pink reports "100% saturation" at 90% lightness, because in that model saturation means distance from grey at this lightness, not how vivid this is. Hold that 100% while you darken it and #FFCAD4 becomes #E3002B — a dusty pink turns into a fire engine. Redone in OKLCh, which separates lightness from perceptual chroma properly, the same pink lands on #94656F. Same colour, just darker.

Both versions scored identically. The numbers could not tell them apart, because I'd asked them the wrong question. Only looking caught it.

The swatch, before and after

Here is the whole set — all forty-nine, filterable, with every ratio the audit produced. Each card paints itself with that theme's real values rather than describing them, which is the point: a contrast figure is easy to skim past and an unreadable caption isn't.

Every palette kept its five source colours; they're now the generator's input rather than its output. What changed is that lightness is computed against each theme's own ground, in OKLCh, so a palette keeps its character and loses its illegibility.

Seventeen backgrounds also had to move, because a mid-grey simply hasn't the room to carry five distinguishable steps — one had 6.5:1 of total range to work with. Those shift toward whichever end the palette had already put its ink, so a light theme stays a light theme.

What I'd tell myself

Three things, none of them about colour.

A generated file whose generator isn't in the repo can't be reviewed. Mine said "generated by generate-themes.js — do not edit by hand." That file wasn't there. Nobody could see what it did, so nobody did, for as long as it took me to notice. It exists now, next to the palettes it reads.

Measure the thing, then look at it. Those are two different checks and neither substitutes for the other. My contrast audit found thirty-nine broken themes the eye had missed; my eye found a fire engine the audit was perfectly happy with.

Then make the check permanent. There's a script now that reads the shipped stylesheet and fails the build on any of eight hundred and thirty-three contrast pairs, on any collapsed hierarchy, on series colours that aren't distinct from one another. Run against the old file it reports seven hundred and seven problems. It won't catch a fire engine — nothing automated will — but it means the next batch can't ship blind in the way this one did.

Fifty skins, and I can read all of them now. It only took admitting I'd never actually looked.