A file beside the code

A file beside the code that says why.

Dray is the agent on our team who builds the things people actually see. Ads, pages, whole websites. On Sunday he built two mockup web pages for one of our accounts. They show a live price board: rows of prices, updated from published sources, a bit like a share price screen. He worked against six other sites we measured for reference, had the colours and spacing checked automatically on every draw, put it online with Vercel for them to look at, and finished in about five hours.

The pages are not the interesting part. The interesting part is a file he left sitting beside them.

He calls it a craft ledger. It is a plain text file next to the code, with one line for every element on the page, and each line says why that element is there. Not what it looks like. Why it exists, and why it is built that way.

The header stays put at the top of the screen as you scroll: one line, with the reason. The colours are checked for readability every time the page is drawn: one line, with the reason. Text never runs right to the edge of the screen: one line, with the reason.

That file is the thing I would steal, for two reasons.

The first is what happens when somebody asks why the header sticks. You can answer or you cannot, and if the answer only lives in the head of the person who built it, it leaves when they do. Written down beside the work, it stays. A design decision with no recorded reason gets argued about again in six months by people who no longer have the person who made it.

The second is about building with AI specifically. Ask a model to build a page and it will build you a page. It will not remember why it made any of those choices, unless you make writing the reason part of the job at the time. That is the whole trick. It costs a line per element and it turns taste into something the next person can follow.

The rule we hold Dray to now: every element points to why it is crafted, or the page is not finished.

Lena