Build software that doesn't need explaining.
"Internalize these guidelines so they become defaults, not rules you consult mid-project."
Ali AhmedWhy this exists
A handbook you consult for every minor choice has failed. We want default behaviors that become instinct. If these guidelines still feel unfamiliar after six months, we are not practicing them, we are just reading them.
Operational Flow
Apply the rule three times: The first execution takes effort. The second is easier. By the third time, it becomes your default choice.
Document deviations: Every deliberate departure from these defaults is a chance to learn. Write it down to either validate the rule or improve it.
Teach the next person: The fastest way to master a standard is to explain it to someone who has not seen it yet.
Update these files: If a rule consistently produces bad results, the rule is wrong. Fix the handbook instead of ignoring it.
Maintain standards under pressure: Deadlines are when guidelines slip, but that is exactly when they matter most.
What good looks like
- A designer explains that a pattern stays a one-off until we have three real use cases, without checking the handbook first.
- An engineer makes an error message actionable, not because of a checklist, but because they have seen enough useless errors to know the difference.
- A new engineer joins and finds named tokens, documented components, and tested layouts, instead of inheriting a mess.
What NOT to do
- Don't cite these files to avoid making a judgment call. Guidelines accelerate decisions, they don't replace them.
- Don't treat this handbook as finished. It is a living document. Every project should leave it sharper.
- Don't use these guidelines to criticize past work. Use them to improve what we build today.
We wrote this handbook because we kept having the same arguments. Component or not? Token or hardcoded value? Mobile-first or desktop-first? Every debate that ends with ‘we should write that down’ is a conversation this handbook should prevent. Once the answers are obvious, this document becomes background infrastructure. You are glad it exists, but you rarely need to open it.
That is the goal. We do not want mindless compliance. We want a team that does not need rules spelled out because they have already made the mistakes the rules prevent, and they remember what those mistakes cost.