Chapter 01
Principles
A design system is a set of decisions you stop having to make twice. These four are the ones every other choice in Inkwell comes back to.
Built with
- Design decisions
- Commit history
What we believe
Four beliefs, each with a receipt.
- 01
One source of truth.
A colour that lives in two places will, sooner or later, be two different colours. So every hex in the site is written exactly once, as a primitive, and everything else points at it. So when the palette needs to change, it changes in one place.
Where to see it
Primitives, semantic and component tokens, all in globals.css.
- 02
Restraint is the brand.
The page is mostly violet and its surfaces, with cream beside it and a single drop of peach. Because the accent is rare, it still means something when it appears. Louder would be easier. Quieter is what makes it feel considered.
Where to see it
A 70 / 20 / 10 split between primary, secondary and accent.
- 03
Paper by day, ink by night.
Light and dark are not a filter over one design. Each is a surface with its own character: lilac paper with ink text, or ink with cream text. Both are first-class, and the site opens in the dark one because that is where it is most at home.
Where to see it
One data-theme attribute, with dark overriding only what must differ.
- 04
Motion needs a reason.
Things move to explain a change, never to decorate it. An entrance tells you where to look. A spinner tells you the form is working, and stays long enough to read even when the server answers instantly. And loops and travelling hovers stop for people who ask them to.
Where to see it
A small set of house easings, and a reduced-motion fallback for loops.
Guard rails
What we never do.
Never: write a raw hex in a component.
Use var(--token) or a Tailwind alias. The only exception is a third-party brand colour, which lives with the primitives.
Never: use the stencil face for a paragraph.
Bespoke Stencil belongs to the hero lockup alone. Body copy uses Synonym and leads use Amulya.
Never: add a one-off font size.
If the size is missing from the scale, add it to the scale. Do not write a new clamp() in a component.
Never: animate without a way to stop.
Anything that loops or travels gets a motion-reduce fallback.
Never: ask a component which theme is active.
Read the token and let the theme decide. A component that checks for dark has already stopped being themeable.
Never: spend the accent on decoration.
Peach is a spark. If it appears three times on a screen, it has stopped being one.
The point
Why write it down at all?
Because the site will keep changing, and the person changing it is usually me, six months later, with no memory of why a colour was chosen. Writing the reasoning down turns taste into something that can be checked, repeated and handed over.
It is also the honest way to learn. Naming a principle is easy. Finding the line of code that breaks it is where it becomes useful, which is why every chapter that follows shows its workings.