A template for engineering writing in the Atlas system — De Stijl bones, Fett headlines, and room for code and charts. Replace this copy; keep the structure.
Most design systems document what a component looks like. Few document why a decision was made, or let you replay it later. This piece argues that the most valuable artifact a team can ship isn't the component library — it's the decision record underneath it, and the instrumentation that proves the decision worked. Everything else is downstream of that.
01. The problem with snapshots
A screenshot captures a state, not a rationale. When a reviewer asks "why is this threshold 200ms and not 500?", a Figma frame can't answer. The answer lives in a benchmark, a tradeoff, and a conversation that happened three sprints ago. If that context isn't captured next to the artifact, it evaporates — and the next engineer re-litigates a settled question.
Capture the decision, not just the deliverable.
02. Make the reasoning executable
The fix is to treat the rationale as code. A decision record is a small, versioned object: the question, the options, the chosen path, and the evidence. Here's the shape we settled on — deliberately boring, deliberately diffable.
// decision-record.ts
type Decision = {
id: string;
question: string;
options: Option[];
chosen: string; // option id
evidence: Benchmark[]; // numbers, not vibes
reversibleBy: string; // the codemod, if any
};Because it's versioned, you can git blame a decision. Because it carries evidence, you can re-run the benchmark and check whether the premise still holds. Decisions that depend on stale numbers surface themselves.
03. Evidence, charted
The benchmark below is the kind of evidence a decision record should carry — p95 latency across three builds. The point isn't the absolute numbers; it's that the claim is reproducible and lives next to the decision it justifies.
"If a number on the page can't be reproduced from an artifact, it's marketing — not evidence."
04. What this buys you
Replayability turns a design system from a museum into a workshop. New contributors don't inherit folklore; they inherit decisions with receipts. And when the context changes — a new framework, a faster runtime — you don't guess which decisions to revisit. The stale ones raise their hands.