One shared source of truth for the Akku product surface. Nineteen reference pages, every token paste-ready, every pattern wired to the same variables. This is the front door — read it once, then come back when you need to look something up.
Pick the one that fits. Most teammates land on (2) first — the system is meant to be scanned, not read.
Every page is self-contained: ramps, role aliases, in-use examples, and the paste-ready CSS. Start with Palette and Type.
Mental model — tokens first, compositions second.
All variables live in _shared.css. Import once at the root; reference tokens, never raw hex.
<link rel="stylesheet" href="_shared.css">
Before reinventing — confirm we don't already have one. Patterns covers empty, loading, confirm, forms, and feedback.
If the pattern doesn't exist, propose one.
Flat. One HTML per reference page, two shared stylesheets, no build step. You can open any file directly in a browser.
Pages reference _shared.css for tokens and shell chrome; component pages also pull components.css. Change a variable in one place, every page updates.
Three layers. Pick the highest-level one that fits — it's the one that survives a re-theme.
Raw scale values — ramps, spacing steps, radii. Don't reference these in product code; they exist so the role tokens can move.
/* reference — do not consume directly */ --iris-500: #8D58FE; --coral-500: #FF7F50; --teal-500: #0ABAB5; --space-4: 16px; --radius-md: 8px;
What you actually use. Every role resolves to a reference token — swapping the reference updates every consumer.
/* role — consume these */ --color-primary: var(--iris-500); --color-danger: #DC2626; --ink: #0F172A; --ink-muted: #475569; --bg-elev: #FFFFFF; --rule: #E2E8F0;
The whole system, in one glance. Every page, grouped by where it sits.
Six rules everyone agrees to. These apply before taste, after needs.
If it exists, use it. If it almost exists, propose an extension. Raw hex values in product code get reverted.
If the button isn't in Components, it should be — not forked into a one-off stylesheet.
Contrast, focus, targets, reduced-motion — the a11y page is the contract. If you need to break it, document the exception.
Every surface sounds the same. Pillars are plain · calm · respectful — no exclamations, no emoji, no "please".
Empty states, errors, confirmations — use the recipes. We've already chosen how those moments read.
Three easings, five durations — that's the kit. Custom curves only for genuinely novel moments, reviewed with design.
The system grows from real product needs, not speculation. If you're about to hand-roll something — open a proposal first. Two lines describing the problem beat a polished RFC.
