Getting Started
Design principles
Principles are only useful when they can settle an argument. Each of these is stated with what it costs — a principle nobody could reasonably disagree with is not doing any work.
The principlesPermalink to this section
Five, in priority order. When two conflict, the earlier one wins.
Clarity before cleverness
When a novel interaction and an obvious one both work, the obvious one wins. People arrive at a product to do something, not to learn an interface.
The trade-off
The system will sometimes look plainer than it could. That is the price of being immediately legible to someone using it for the first time.
Restraint makes emphasis possible
Colour, shadow and motion are finite budgets. Every extra accent, every additional shadow, every animation spends from a total — and once it is spent, nothing can stand out.
The trade-off
Individual screens are quieter than they might be in isolation. In exchange, the one important thing on each screen is always findable.
Accessible by construction
Accessibility is a property of the components, not a review step. Where a requirement can be enforced by an API — a required label, a mandatory title — it is.
The trade-off
Some component APIs are stricter than they strictly need to be. IconButton refuses to render without a label, and that is deliberate friction.
One decision, one place
A value that appears twice will eventually disagree with itself. Tokens, variants and patterns exist so that changing something means changing it once.
The trade-off
There is more indirection than a one-off implementation would need. Reading a component means following a token chain rather than seeing a hex value.
Systems are documented, not just built
An undocumented component is a component that gets reimplemented. The reasoning matters as much as the code, because the reasoning is what tells someone whether their case is the exception.
The trade-off
Every component costs more to add than writing it would. That cost is paid once and recovered every time someone does not have to guess.
Principles in practicePermalink to this section
Each principle produces concrete decisions. These are the ones that come up most often.
Do — one primary action per screen
Restraint makes emphasis possible. The hierarchy is visible before a word is read.
Don't — give everything equal weight
Three primaries is the same as none — the eye has to read all three to find out which matters.
Do — state status in words
Clarity before cleverness, and accessibility by construction: colour reinforces, the word carries.
Don't — encode meaning in colour alone
A red dot requires the reader to already know the legend — and excludes anyone who cannot see the hue.
When principles conflictPermalink to this section
They will. The order above is the tie-breaker, but most real conflicts resolve by asking a narrower question.
A clearer layout would need a third accent colour.
Clarity wins, but check first whether the clarity can come from spacing or hierarchy instead. It usually can — restraint is rarely actually in tension with clarity.
A stricter API would be more accessible but more annoying.
Accessibility wins. IconButton's required label is exactly this case, and nobody has complained about it since.
A one-off design would be faster than extending the system.
Extend the system, unless the case is genuinely singular. If a second team asks for the same thing within a quarter, it was never a one-off.
Documenting the component will take longer than building it.
Document it anyway. The undocumented version gets rebuilt by someone else, and then there are two.
What the system is notPermalink to this section
Being clear about the boundary is part of being useful.
Not a brand system
Borneo covers product interface. Logo usage, illustration style, photography and marketing voice are outside it — the system provides a foundation those can sit on, not a replacement for them.
Not a component dump
Every component here is used in production by more than one surface. A component with one consumer belongs in that consumer's codebase.
Not a constraint on layout
The system supplies primitives and rules about spacing and breakpoints. It does not dictate what a page looks like.
Not finished
It is versioned, it deprecates things, and it will look different in two years. A design system that stops changing has stopped being used.