Braip design system — from library to system

Context

Braip is a sales and affiliate platform, and its design system exists to support a web app running in light and dark with genuine parity — not as a visual courtesy, but because a sizeable share of the operation happens in the dark.

The design team is small and engineering consumes Figma directly: whatever is named in the file is what lands in the code. That makes variable naming a product decision, not internal housekeeping.

The constraint that shaped everything: the system was in production and there was no window to rebuild it from scratch. All of it was done on the live library, with components being instanced in other people's files while the change was underway.

The problem

The system didn't have an appearance problem. It had a naming problem.

Numeric suffixes with no defined role. The State group in the ❖ Color collection exposed each colour across four tiers — 01, 02, 03, 04. The number described luminosity, never function. State/Purple/03 doesn't answer the only question that matters while designing: can I use this as text? In practice, everyone picked a different tier for the same role, and the divergence only surfaced when two screens sat side by side.

Contrast never measured. Coloured text over tinted backgrounds was chosen by eye. In dark mode, where the chip background blends into the #0B0B0E canvas, "looks readable" and "is readable" are not the same thing — and nobody had the number to tell which one was happening.

Motion as a loose value. Hover, sheet and toast had durations set screen by screen. There was no scale, no vocabulary, and therefore no way to review a micro-interaction other than by opinion.

My role

I owned the token, contrast and documentation track inside the design team, under the design system epic TI-2036. That covers the variable naming architecture, the contrast audit, the motion scale and the handoff specs.

What isn't mine: the product components themselves, drawn by the team over time, and the code implementation consuming those tokens. My job was to give those components a base that explains itself.

Process

I started by auditing the ❖ Color collection and, rather than proposing a convention from scratch, I read the actual usage. I inspected how the Tags and Chips components already consumed the tiers: in the Solid variant the container used tier 03 with white text; in Minimalist, the container used 01/02 and the text used 03. There was an implicit convention there, working, unnamed.

With the implicit pattern mapped, I compared it against what mature design systems do for state scales — Ant Design, Atlassian, Polaris and IBM Carbon converge on the same sequence of roles: background, border, icon, text. Braip's convention was already that; it just needed saying out loud.

From there: rename without touching values, measure contrast on the renamed scale, fix the pairs that failed, and finally extend the same "a name that states the function" logic to motion.

Each stage became a versioned spec and plan before execution — 20 specs and 28 design plans between 3 and 24 July 2026. The plan exists less to remember what to do and more to leave a record of what was discarded.

Key decisions

Decision 1 — Semantic role instead of a numeric scale

Context: State/<Colour>/01–04, across nine colours. The number indicated luminosity, not function.

Alternative discarded: keep the numbers and publish a legend explaining what each tier maps to.

Why this one: a legend is documentation nobody opens mid-handoff. A name, by contrast, travels with the token — it shows up in the inspector, in the code, in the conversation. And adopting the sequence Ant Design, Atlassian, Polaris and Carbon already use lowers the entry cost for anyone arriving from another system: they don't need to learn Braip, only to recognise the pattern.

Decision 2 — Rename without touching values

Context: there was a temptation to fix colour and name in a single pass, since the file was open anyway.

Alternative discarded: rename and value rebind in one movement.

Why this one: separating the two operations makes each of them verifiable. If nothing changes visually after the rename, the rename is correct — any pixel difference would be a bug, not intent. The chromatic adjustment came afterwards, guided by the contrast report, and could be judged on its own because the naming layer was already stable.

Decision 3 — Legacy retired by documentation, not by deletion

Context: the Motion collection carried an old scale, value/duration/100 through 600, unlinked from the new semantic tokens.

Alternative discarded: delete the legacy variables alongside publishing the new scale.

Why this one: deleting a variable in a live library breaks instances in files that aren't yours, and the affected person finds out through the damage. Explicitly marking it "do not use" in the reference documentation stops adoption without breaking anyone; removal waits until consumption reaches zero.

Solution

Braip's final base is 839 tokens across seven categories — colour, semantic colour, primitives, typography, spacing, layout and responsiveness.

State colour. Nine colours (Neutral, Purple, Green, Blue, Pink, Orange, Red, Yellow and Off) exposed by role rather than index: background → border → icon → text. That's 35 renamed variables, in two modes, with no value change in the process. Off is the documented exception: it has only three tiers, because it never needed an emphasis level.

Contrast. Chips and Tags audited against WCAG 2.0 AA across the nine colours, in both modes, with every pair's ratio recorded in a table. Pairs falling short of 4.5:1 were corrected before publishing, not after someone reported them.

Motion. Five duration tokens (instant, fast, base, slow, slower) and three easing tokens (standard, enter, exit), each with a guideline for when to use it — fast for micro-hover, base for toast, slow for sheet; enter for elements appearing, exit for elements leaving, standard for neutral transitions. The scale was applied to three reference components: Sheet, Toast and the Button hover.

The whole scale lives documented on the file's Foundations page, with animatable previews — the documentation is the working file itself, not a parallel PDF ageing on its own.

Outcome

The token started explaining itself at handoff. Asking "which tier do I use here?" stopped making sense, because the name already answers it: if it's text, use text.

Contrast became a verifiable criterion instead of an opinion. There is a table with the measured ratio for every Chips and Tags combination, across the nine colours, in both modes — and the argument in a design review shifted from "I think that's too light" to a line in that table.

Motion became shared vocabulary. Debating whether a sheet should use slow is a productive conversation; debating 320 versus 340 milliseconds is not.

And the system absorbed all of it without breaking anyone's file — the legacy left circulation through documentation, at the pace consumption dropped.

What I'd do differently

I inverted the order. I renamed before measuring contrast, and the consequence was having to return to the already-renamed scale to fix the pairs that failed — the final report carries "corrected" marks that wouldn't exist had the measurement come first. Measuring is cheap; renaming twice is not.

And I treated visual evidence as a step after execution. Several plans ended up with their screenshot pending once the change was already applied, which means part of the "before" is gone. Documenting isn't the step that follows the work — it's part of it, and when it's left for later, it usually doesn't happen.