System · BELLA
A design system people trust and AI can build with
BELLA is my open design system, and it runs the site you're reading. This page shows how I make one: who decides, where AI helps, and what stops drift from shipping.
01 · Why it matters
It looks right. The code says otherwise.
Same prompt, same agent. Without documentation it fills the gaps with guesses, and the guesses look almost right. You only see them in the code.
If a decision isn't written down, AI will make one up.
Two cards you can't tell apart, and four guesses hiding in the code.
Small guesses become drift. Documentation is what the gate checks against.
02 · How a component gets made
A human at every step, AI where it helps.
My workflow, adapted from TJ Pitre's context-based design systems lifecycle and run for real on BELLA.
I start with what the component is for: its job, its states, and the words we'll all use for it. Claude helps me synthesise the research and audits so the decision is grounded.
03 · Try your brand
Bring your brand. The system decides what ships.
Pick an accent, a corner and a density. The card follows, and the gate checks every choice live. Some brand colours won't make it, and it tells you why.
// --accent: #e8a83e · radius: 12px · density: system · mode: light
04 · Every merge
A system that can't refuse is a suggestion.
Colour is one check of 22. Every change walks this path, and any one of them can stop it.
A change travels through write, build, generate, check and ship. The check step runs 22 audits and passes only when all of them do.
0 of 22 passed
Tap any check to see what it stops.
04b · Accessibility
More than contrast. Built in, not bolted on.
Contrast is the easy check. These are the other six BELLA holds itself to, on every component, before anything merges.
Every control is reachable with Tab and shows a visible focus ring, separate from hover.
checked by audit:axe · keyboard pass by hand
Target: WCAG 2.2 AA everywhere, AAA for body text. Reference: w3.org/WAI/WCAG22. Automated checks catch about a third of issues, so every component also gets a keyboard and screen-reader pass by hand.
05 · Self-assessment
Where the system honestly stands.
Not a scoreboard. Scored against zeroheight's six-axis maturity model: strong where it can be for a team of one, early where it needs a team.
Stages: V1, Growing, Teenage, Healthy product. Model: zeroheight Design System Maturity Model. Self-assessed. Tap an axis for the why and what's next.
06 · What your team gets
One language, three kinds of people.
Decisions that stick.
Tokens and contracts mean a choice made once shows up everywhere, in both themes.
No guessing.
The same names in Figma and code, a contract per component, and a gate that tells you why before review does.
Faster, without drift.
AI can draft safely because the system can say no. New brands are a token file, not a redesign.
This is how I'd start with your system: an audit, one component through the whole lifecycle, and a gate your team owns.