Principles
Eight principles, adapted from Apple’s Human Interface Guidelines and stated here in terms of this system. Each one names what actually holds it up — a token, a component, a rule, a tool — because a principle that nothing enforces is decoration. There is no single right way to apply them; they are for weighing one good idea against another when both cannot win.
Purpose
Make something meaningful.
Design starts with intention. A component earns its place by doing work a page genuinely needs — not by filling a gap in a catalogue. Before adding one, ask what it is for and whether something documented already answers the question.
- Every component is documented with a live demo; if it cannot be demonstrated, it is not ready.
- The linter rejects invented classes, so a new idea must be promoted into the system rather than smuggled into a page.
- The examples are built only from documented components — they are proof, not decoration.
On a product page: One idea per chapter. If a section cannot be summarised in a single sentence, it is two sections.
Agency
Let people do things their own way.
An interface exists so someone can finish something. Get out of the way, let people move freely, and make mistakes cheap to undo. Anything a person can reasonably choose, they should be able to choose.
- Theme, accent and wallpaper belong to the person:
data-theme,data-accentandBarua.wallpaper. - Overlays close the way people expect — Escape, outside click, and a visible control, everywhere.
- Destructive actions say what they will do, and are never the default in a row of buttons.
On a product page: Two ways in, never one: a primary action, and a quieter link for people who are not ready yet.
Responsibility
Act in people’s best interest.
Be plain about what a product does and why. Ask for what you need, when you need it, and say what it is for. Treat what someone tells you as theirs.
.b-redactedand its privacy variant hide sensitive content deliberately, and look different from loading.- Empty and error states explain the situation and the way out rather than apologising.
- Marketing claims carry footnotes: a figure with its conditions stated is worth more than a figure without.
On a product page: No claim on a landing page without the footnote that makes it true.
Familiarity
Build on what people know.
People arrive already knowing how software works. Use what they understand, keep it consistent, and answer every action with feedback. The premise of this system is that Apple’s vocabulary is the one most people already speak.
- Native elements first —
<dialog>, the Popover API,<details>— so platform behaviour arrives correct and free. - One grammar throughout:
.b-block__element--modifier,.is-*for state,--b-*for values. - States stay distinct and consistent: hover is a quiet fill, selection is accent-soft, focus is the ring.
On a product page: Put the chrome where people expect it. A product page is not the place to reinvent a navigation bar.
Flexibility
Adapt to diverse contexts and needs.
People will use this on a phone in bright sun, on a laptop with reduced motion, with a keyboard only, in another language, at twice the text size. The design should meet them rather than assume them.
- Light and dark through
light-dark(); a wallpaper can set the scheme for the surface it backs. - Every size is in
rem, so the system text-size preference scales the whole interface. - Reduced motion is honoured globally; every interactive element carries its keyboard path and accessible name.
- Components reflow on their own — most layouts need no media query at all.
On a product page: Every chapter must survive a phone. If the picture only works at 1600 pixels, it is not the picture.
Simplicity
Be clear and direct.
Simplicity is not minimalism. Keep what matters close and let the rest fall away, choose exactly the words a control needs, and make the hierarchy obvious enough that nobody has to hunt for it.
- The type ramp is eleven roles, each with complete metrics — hierarchy is a decision, not a font size.
- A screen ends at the screen: chrome stays put and only designated panes scroll.
- Surfaces never stack materials; a panel inside glass is a fill.
- Labels are written, not generated: a button says what will happen.
On a product page: The headline is capped at twenty characters of measure so it always breaks well. If it will not fit, the sentence is the problem.
Craft
Care about every detail.
Quality sets the tone, and shipping is not the finish line. The details nobody names — the metrics of a caption, the ceiling on a chart, the edge that catches light — are the difference between a system and a stylesheet.
- Every text style carries its own leading and tracking; small text opens up rather than borrowing body metrics.
- Charts have ceilings as well as floors, so a component that reads correctly in a demo still reads correctly in a wide card.
- Glass carries a specular edge, and the mail pane is literally the same card as everything else rather than a copy of its values.
- The validator and the linter run over the documentation itself — the docs obey the rules they publish.
On a product page: Real photographs, at one aspect, cropped deliberately. Ragged card heights are the first thing an eye notices and the last thing a brief mentions.
Delight
Make it human.
People remember how something felt. Decide which feeling is right — calm, brisk, celebratory — and let it shape the work. Delight is never decoration, and never gets in the way of the task.
- Motion runs on spring easings, and shared elements morph rather than cross-fade.
- Symbol effects answer an action: a bounce on send, a pulse while something is genuinely happening.
- Liquid Glass is one attribute, so a product can change its whole character without changing its markup.
- A wallpaper makes the glass mean something — the person’s own picture, and the system learning its colour from it.
On a product page: One moment of motion in the hero, muted and looping. A page that demands attention with noise is a page people close.