Writing · 6 min read
How does a designer work in the developer’s tools?
Not by becoming an engineer. By running every change through the same tools the team does: a branch for each change, a commit that says why, a pull request as the unit of work, checks that run before the merge, a deploy you watch land, and a log you read when the page says nothing. Each of those tools answers one question a developer asks every day, and a designer who has shipped through them knows the questions in the order they get asked. That is what the tools are for, what they teach, and which of them a designer runs on day one.
Key idea 1 of 7
The repository is the one place that says what is true
A designer’s tools describe what something should be. A developer’s tools record what it is. The repository holds every file the product is made of, every version of every file, and a line for each change saying who made it and why. Nothing else on the team has that property. The design file is an intention, the ticket is a request, the demo is a moment; the repository is the only artifact that cannot disagree with the product, because it is the product.
That is the first thing shipping through the tools teaches, and it changes where a designer looks. When two people describe a screen differently, the question is not whose memory is better. It is what the file says, and when it last changed, and what the change said it was for. I have run this site through a repository since June, and the habit it built is the one a developer already has: before arguing about what shipped, open what shipped.
Key idea 2 of 7
A branch is a safe place to be wrong
Every change starts on a branch: a copy of the whole product where you can try something without touching what anyone else is working on or what the public sees. On a branch you can change every page and then throw all of it away, and nothing happened. That is the developer’s version of a scratch artboard, with one difference that matters: it is the real product, running, and not a picture of it.
A commit is a saved step on that branch, and the message on it is where the decision lives. Not “fix spacing”: the reason the spacing was wrong, what was tried, and why this is the answer. A developer reading it a year later, or an assistant reading it in a minute, gets the argument and not just the diff. The commit message is the design rationale, filed where the next person will actually find it. Every one of mine on this site says why, and it is the part of the tool I would tell any designer to learn first, because it costs nothing and it is the whole difference between a change and a decision.
- Brancha copy of the product where being wrong costs nothing
- Commita saved step, with the reason on it
- Pull requestthe change and its account, proposed together
- Checksthe rules, run against the rendered page before the merge
- Mergethe branch becomes the product
- Deploythe product becomes the site, about a minute later
- Verifyfetch the page and look; a merge is not a deploy
Key idea 3 of 7
A pull request is the change and its account, and the account outlives the change
When the branch is ready it becomes a pull request: the whole change, rendered as a difference against the product, with a description above it. The description is the second place the reasoning goes, and the more important one, because a pull request is the unit the team actually reads. Someone reviews it, comments on a line, asks for a change, approves it. Then it is merged, and the branch is folded into the product as one commit.
The part that took me longest to see is that the description is not a formality. On this site every pull request carries a written account of why the change was made and what it cost: which counts moved, by how many, and where. Months later that account is the history of the design, findable by anyone, in the order it happened. A design file has versions; a repository has reasons. The tool a developer uses to propose a change is also the best design-decision record I have ever kept, and I did not have to keep it separately.
Key idea 4 of 7
A green check and a live site are two different facts
Before a pull request merges, checks run. On a product team that means the tests, the linters, the build; on this site it means nine scripts, four of which open every page in a real browser and measure what is there: every color a reader can see against its floor, every rendered type size against the scale, every state a press can reach. A red check stops the merge and says which page and which element. This is where the design rules live now, and a designer who can read a red check can hold the product to a rule without asking anyone.
Then comes the lesson the tools teach hardest. A green check means the tree passed. It does not mean the site changed. The merge and the deploy are two separate machines that fail independently, and I learned that from a merge that ran every check, went green, and never deployed at all. The site did not look broken. It looked unchanged, which is indistinguishable from a change nobody made. Another deploy failed fourteen seconds in, on a green tree, because it carried one file the deploy machine could not follow. And a page fetched straight after a successful deploy can still show the old bytes, because the host caches for ten minutes.
It says
- The tree can be packaged for the host at all
- Every token the specs name exists
- Every color clears its floor, at rest and under a press
- Every rendered size is a step on the scale
It does not say
- The deploy ran
- The deploy finished
- The cache has let go of the old page
- A reader can see the change
So the last step of every change is to go and look, with a cache-buster on the address, at the page a stranger would get. A developer never confuses “it passed” with “it is live,” and once you have been caught by the gap you never do either.
Key idea 5 of 7
The log is where the truth is when the interface is silent
Most of what a developer’s tools tell you, they tell you in a log: a plain record of what ran, in order, with what result. The terminal is where it is read. It is the least designed surface in software and the most honest one, and learning to read it is not a technical skill so much as a habit of looking at the record instead of the screen that summarizes it.
The reason is that the interface goes quiet exactly when the record gets interesting. The build that produces one of this site’s stylesheets emits only the classes it has seen a page use, so a class named in the markup that the build never saw is not an error. It is nothing at all: the type measures wrong at every width and the console says nothing. The deploy that failed fourteen seconds in said so in a log nobody had open. In every case the screen was calm and the log had the answer, and the fix was to read the log first. A developer’s trust runs the opposite way from a designer’s instinct: the quieter the interface, the harder they look at the record underneath it.
Key idea 6 of 7
Developers ask the same five questions, in the same order
Ship through these tools for a season and a pattern shows. Whatever went wrong, a developer asks the same questions, and asks them in the same order: What is live right now? What failed? What changed since it last worked? What depends on the thing that changed? Can I put it back safely? Each of the tools above exists to answer one of those. The deploy log answers the first, the check the second, the diff the third, the repository’s history the fourth, and the branch the fifth, because a change that lives on one commit is a change you can revert with one.
That order is an information architecture, and it is the one to build any tool for developers around. It is also the same shape I have written about for an operations floor when an order stalls: what happened, what it affects, what can I safely do next. The person is different; the questions are not. A developer whose deploy just failed is a coordinator whose transaction just stalled, holding a system that technically contains the answer and does not say it. Knowing the questions in order, from having asked them yourself, is the qualification for designing the answer.
Key idea 7 of 7
What a designer runs on day one, and what takes a quarter
Here is the honest map, because a team finds it out either way. The branch, the commit, the pull request, the checks and a static deploy: I run all of that daily, on this site, with a terminal open and an assistant in it that writes the commands I describe and shows me the ones I do not know yet. That is the part of the developer’s toolset a designer can run from the first week, and the assistant is what makes it a week rather than a year.
- 175
- pull requests since June, each carrying a written account of why
- 9
- checks on every merge; four of them render every page in a real browser
- 1
- minute from a merge to the live site, with nothing in front of it
Containers, cloud infrastructure, a build pipeline at team scale, observability across many services: that is the part I have read and not run, and I would rather say so than have it discovered. The way in is the same way it was for the rest, which is to ship something through it and read what the log says. The judgment does not change with the tool. What changes is that the designer stops describing the workflow from outside it, and that is worth a quarter of learning the vocabulary.