Three essays, from the files
What the argument each case file makes, on its ownFor anyone who wants the thinking before the screensProblem a case file proves its argument at length, and the argument gets lost in the proof
Each case file makes one argument and spends most of its length proving it. These are three of those arguments on their own: why a design system should be run like case law, why a diary for teenagers had to be private by default, and why a number needs its basis. Nothing here is new evidence. Every claim is in the file it links to, and every figure is the canon’s.
Three essays drawn as their paragraphs, each bar as long as its words. Run a hand down the rows.
Rules as case law
A design system lasts when its decisions can be found, argued with and changed on the record, which makes it a legal problem as much as a visual one.
A design system is usually sold as a library: so many components, so many tokens, a Storybook to browse them in. The library is the cheap part. What decides whether a system outlives the person who started it is whether its decisions can be found, argued with and changed on the record. That is a legal problem more than a visual one, and the most useful thing I did on the OI design system was to treat it like one.
The rules are numbered, and the numbers are never reissued. The system runs on 91 of them. Two have been retired, and their numbers stay vacant, so the sequence carries its own history: anyone reading down the list can see where a number is missing and go and find out why. Rule 4 is the one most people quote, no hex above this line, because the whole token chain follows from that one prohibition. A component may never touch a raw value. It reads a component token, which reads a semantic one, which reads a primitive, and a theme is a swap at the bottom of the chain rather than an edit in every file.
A rule nobody checks is a suggestion. Skipping a layer fails the build, not the review, and a component is not promoted until its eight files exist. When I counted the system’s stylesheets for this site, none of the 1,304 colour declarations in them held a raw hex, rgb, hsl or named colour. That is what a rule looks like when it is held rather than hoped for.
A rule book also has to say who may change it. The governance file carries a decision-authority matrix: eighteen classes of change, each resolved to the one role whose sign-off a pull request cannot merge without. One approver, never two, because two approvers diffuse ownership. A component owner can add an atom without asking anyone. Only the design-system owner can add an iron rule, and that row has no optional review at all, because a rule anyone can add is not a rule.
The part that costs something is the log. Any decision that locks a pattern, picks between alternatives or changes a rule produces an entry, and reverts are recorded too. Mine are in it under my name. One day I mandated a canvas gutter across the whole system, hardened a rule to enforce it and added a guard. Hours later I reverted all three, because the mandate rested on a wrong reading of the architecture: bricks carry their own padding precisely because they are the frame. The entry stays, so that the next person with the same idea finds out it was tried. The same day, another entry retired two of my own earlier decisions and changed a public API, which is the expensive kind of correct.
Precedent works because it is written once and read by everyone. The decisions, the rules and the reasoning behind them live in a vault of 378 documents with 6,683 cross-links between them, written once and rendered twice: as prose for people, and as structured rules for the agents that build prototypes from the system. An engineer and an agent read the same canon, so when a product manager writes a sentence of plain English and gets back a working prototype in about fifteen seconds, it is built from the shipped components under the same rules a person would be held to.
The conversation changed shape. When we disagree now, we cite a number, look up why it exists, and either follow it or retire it in the log. That is slower than taste on any single afternoon and much faster over a year, because the argument is had once.
The thing I would change is the order. I built the library and then put the rule book and the memory in front of the engineers. It should have been the other way round: the system was not the hard part; getting engineers to want it was.
This site runs on the same idea at a smaller scale. Its figures live in one file, each with the command that reproduces it, and a suite fails the build when a page disagrees with the canon or a command stops reproducing its number. The second of those checks found that the token count this site had published, 3,444, came from a command that also counted documentation. The count is 3,396, and the old number is kept in the record as superseded rather than quietly overwritten. That is case law too.
The evidence is in the files: 001, governance and the decisions log, the token chain, this site’s figures.
Private by default
A diary for teenagers in mental health care was worth reading only because nothing in it left without their choice.
When an NHS mental health service for young people moved its care home during COVID, the clinic kept one hour a fortnight and lost the other thirteen days. Between appointments the clinical team had no signal at all: no mood, no sleep, no incident, unless the young person volunteered it at the next session. The obvious product was a tracker, something that would send the week to the people who needed it. The research said that product would come back empty.
The finding that shaped everything was about who reads. In the survey of forty young people and parents, sixty-four per cent of the teenagers were comfortable with a clinician reading their entries. Thirty-four per cent were comfortable with a parent seeing their activity. Asked the same question, eighty per cent of parents wanted exactly that. Two of the three relationships were uncontested and one was not, by forty-six points, inside the same family and about the same screen. A diary that satisfies the eighty per cent loses the thirty-four, and then has nothing in it to read.
So the diary is private by default, and it shares entry by entry, only when the young person chooses. Nothing syncs on a schedule. Between the diary on the phone and the record the trust holds sits a consent gate that is crossed one entry at a time and can be withdrawn, and a clinician cannot see an entry the young person did not share, because it never reached the record. The privacy model was designed with the trust’s clinical safety officer and its digital governance, and drawn in that order the rest of the product decides itself: the dashboard is the fourth thing in the service, not the first.
The decisions that mattered most were refusals. Peer-to-peer messaging died in the workshops, killed by the teenagers themselves on privacy grounds. The parents’ side shows that their child wrote and which way the week went, never the words, the messages or the notes. And no model reads the diary: eighty-eight per cent of the young people worried about who could see what they wrote, and a model is one more reader, the one they could not see. If one ever helped, the place it would have to earn is the clinician’s five minutes before a call, over what the young person had already chosen to share, saying it was a model wherever it spoke.
Privacy stopped being the footnote and became the pitch. The poster in the waiting room led with it: “My Mind Diary, your private space to share, only if you want.”
It cost something to hold that line, and the beta is where it was tested. Twenty-one people used the service as part of real care, three clinicians, ten patients and eight parents, at one clinic for about three weeks, against rollout metrics agreed before it ran. The teenagers wrote four entries a week each, in a product with no streaks and no escalating reminders. All eight parents opened every weekly summary, which tells them how the week went and nothing their child did not choose to share. Ninety-four per cent of beta users said the service should continue. Privacy did not make the diary emptier. It is the reason there was anything in it.
The same rule carries over to work that has nothing to do with health. When I wrote the measurement plan for the rebuilt Astrato in case file 002, the first decision was what it would not collect. A question typed into an analytics assistant can hold a customer’s own figures, so its words never leave the page; the plan records where the question came from and how many fields it could draw on, and no property anywhere holds free text. The rebuild checks every call against that plan, and a suite fails the build if a question’s words ever reach one.
Private by default is not a setting. It is a decision about who the product is for, taken before the first screen, and every refusal after it is that decision being kept.
The evidence is in the files: 003, the research, the privacy boundary, the beta, 002’s measurement plan.
The number that is true twice
A figure without its basis is an opinion held on the reader’s behalf, on a finance team’s screen and on a portfolio alike.
In the first quarter of 2026 Novo Nordisk reported sales up 32% at constant exchange rates and adjusted sales down 4% at constant exchange rates. Neither figure is wrong and neither is spin. They are the same sales measured on two bases, and the gap between them is a DKK 26.8bn provision reversal with no cash attached to it. In a meeting, though, only one of them goes in the deck, and someone always asks which number.
The question is never really which number. It is which basis, and who chose it. The same quarter reads four ways. Reported at constant currency it is up 32 per cent; reported in kroner, up about 7; adjusted in kroner, down about 1; adjusted at constant currency, down 4. Two switches make the difference, reported against adjusted and kroner against constant currency, and neither was visible on the dashboards people were reading. A figure without its basis is not a figure. It is an opinion held on the reader’s behalf.
The instinct in that room is to pick a default and move on. I argued against it, and the argument is the whole design. A default basis is a silent editorial decision, taken by whoever built the dashboard, applied to everyone who reads it, and invisible at the moment it matters most. The company had introduced adjusted measures precisely because the reported figures had stopped describing trading. Choosing one for the reader throws that away.
So the rule the screens enforce is narrow and absolute: no measure renders without the basis it was computed on. The basis sits against the number, in the same visual breath, and it is the one control that restates everything at once, every tile, every chart and the generated SQL. My first version let you set the basis per chart. It demoed well and it was wrong: two tiles side by side on different bases is a chart that lies by adjacency. The basis went global, and a per-chart override became an explicit, labelled exception that marks its tile, so an override is never silent.
The same failure happens to a portfolio. For a year this site published the size of the design system’s component library as 216 on the landing screen, 216 three times on case file 001, 220 further down that same file, and 214 inside a product demo under the words “one source of truth”. None of the numbers was invented. Each was true of a different count, taken at a different time, by a method nobody wrote down, and because nothing was watching they drifted apart in public. They were true twice, and three times, and that is the same disease as the quarter that grew 32% and fell 4%.
The fix was the cockpit’s rule applied to the site. Every figure now lives in one file with its definition, its source, the date of the thing it counts and, where the repository can count it, the command that reproduces it. A test reads every page and fails the build when one states a figure the file has superseded. The library is 231 components , counted as one file an engineer imports, and the definition is printed beside the number wherever it appears.
It was not finished then, and the way it was not finished is the point. In October 2026 a new check ran every command in that file for the first time. The token count, published as 3,444, came from a command that counted the token documentation and story files as well as the stylesheets, because its file filter sat where grep reads a file name. Counted the way its own definition says, the system has 3,396 tokens. The site says so now, everywhere, and the old number is kept in the file as superseded, not overwritten, so the check can hunt it down if it ever comes back.
One true number is the wrong goal. Numbers are true of something, under a definition, at a time. The goal is that every number carries those three things with it, so a reader never has to trust whoever chose them. A screen can do that for a finance team, and a file and a test can do it for a portfolio.
The evidence is in the files: 004, the basis problem, the cockpit, running, this site’s figures.