The Rest

The Payload Contract

I rebuilt my command center with an AI. Full design system, contracts documented in every component file, the works. Then I opened the real thing with real data, took a screenshot, and asked: "Can you spot the problem? Don't solve anything yet."

It went straight for the clever answer. The data was lying — issues marked "in motion" that hadn't moved in 28 days, a state machine hole, green dots on dead work. Smart find. Real bug, even.

Wrong answer.

I told it: maybe, but that's nearly not as important. Look at the most common molecule on this page. The issue tile. I would argue the most basic, foremost, primal CONTRACT with the user is to show the issue title.

And when I look at the screen: on the left column I see maybe two words. On the middle column — three characters. Three. On the right, barely one word.

Does this honor the contract?

Here's what had happened, and it happens everywhere: every piece of metadata on that row was protected. The repo ref in monospace — protected, no-shrink. The scope crumb — protected. The state word, the age — protected, nowrap. The title — the one thing the row exists to deliver — was the only flexible element. So when width ran out, the title paid for everything. The least important content was the most protected. The reason for the row's existence got three characters.

And the metadata wasn't even honest about its cost. The repo name appeared twice on the same row — once in the ref, once in the crumb. The state appeared twice — a colored dot AND the word. Every duplicate stole width from the title, on every row, hundreds of times per screen.

Then I pushed one more level, because the fix it proposed still assumed single-line rows: why? Each column is a single-column list of tiles. Nothing aligns across them. How important is it REALLY that every tile is exactly the same height?

It isn't. At all. Equal row height buys you one thing — comparability across a grid, when the eye tracks columns through rows. A vertical list has no columns to track. Peer-ness in a list comes from repeated anatomy — same padding, same hairline, same structure — not from equal height. The single-line row is inherited table-thinking, a habit from spreadsheets, carried like a law into a place where it buys nothing and costs the payload.

So the rules, the way I'd teach them:

1. Every molecule has ONE payload — the element it exists to deliver. A row exists to show its title. A card exists to show its name. Name the payload before you lay anything out. It gets the space. Metadata yields, shrinks, dies first. If something must truncate to three characters, it is never the payload. 2. Say each fact once. Duplication isn't emphasis — it's theft from the payload. 3. In single-column lists, let the payload wrap. Two-line clamp. Heights vary. Nobody dies. 4. Test the molecule at the narrowest container it will actually live in. A row designed in a full-width ledger and shipped into a 400px column was never tested at all.

And the meta-lesson, the one for reviewers: check the most common molecule's primal contract before anything else. The user hits the broken title a hundred times before they ever notice your clever state-machine bug.