Architecture decisions
An architecture decision record captures one significant choice — the context it was made in, the decision itself, and what the decision costs. This section records the choices that shaped motif.
Why this section exists
Most of these decisions were made in a single planning session before the first line of code,
and they have held since. The records here are retroactive — written after the fact, against a
library that already implements them — so each one is Accepted. They exist so that a
contributor, or a future maintainer, can see why a thing is the way it is without reverse-engineering
the intent from the code.
A decision recorded here is load-bearing. Changing one is not a refactor — it is a new ADR that supersedes the old one.
The records
| ADR | Decision |
|---|---|
| 0001 | Renderer model — two trees, one shared API |
| 0002 | Style-prop API and the styled() factory, side by side |
| 0003 | Two-layer tokens — primitive palette, semantic intent |
| 0004 | A progressive compiler — the runtime always works |
| 0005 | Three responsive syntaxes, not one |
| 0006 | A headless layer separate from the styled primitives |
| 0007 | The npm scope strategy and the rebrand history |
| 0008 | Uniform versioning across the workspace |