Bridge design system
The shared components, tokens, patterns and templates behind Bridge OS and every Bridge app, and the rules that keep them one product. Bridge OS sits at the center; each mini app, from Intros to Raise to Perks, does one job. This handbook shows how to build any of them.
It has two parts: @brdgapp/ui, the package every app installs, and these pages, which say how and when to use it. Every example here is the real component.
Surfaces, lines and ink
One Royal blue, saved for the next step. 64 tokens in all.
Aa
Mulish, set small
Rows at 13px, card titles at 15px, metadata at 12px. Numbers line up: 1,284 · 12.5K
Saltmarsh Partners
AcceptedPriya Natarajan and Leah Okonkwo
How a Bridge screen is made
Five steps, from deciding what a screen says to shipping it. Each one has its pages.
- 1Decide what it says
Before anything is drawn. Principles, voice and patterns decide what a screen must say and do.
- 2Arrange it
Put it in the right order. Templates, layout and spacing give every page one of a few known shapes.
- 3Style it
Choose the look. Tokens for color, type and shape: charcoal ink, one Royal blue, frosted glass.
- 4Reuse it
Never decide twice. Components hold the decisions, so every app gets them for free.
- 5Ship it
Make it work for everyone. Motion, states, phones and accessibility decide how it behaves in use.
What’s inside
The system follows atomic design. Tokens become atoms, atoms combine into molecules, molecules form organisms, and organisms fill templates.
| Layer | Pages | What it holds |
|---|---|---|
| Foundations | 15 | Tokens, color, type, spacing, layout, shape, motion, icons, theming and accessibility. |
| Atoms | 17 | The smallest parts that still mean something on their own: a button, a tag, a switch. |
| Molecules | 14 | A few atoms working as one control: tabs, a button group, a menu. |
| Organisms | 4 | A whole region of a screen with its own job: a data table, a dialog, a drawer. |
| Utilities | 1 | Parts with no look of their own that the rest depend on, like DataState. |
| Patterns | 19 | Problems that come up again and again, solved once: loading, forms, saving, feedback. |
| Templates | 8 | The page shapes every Bridge screen is built on, from dashboards to record pages. |
| Apps | 5 | Each Bridge app’s frame, widths and habits, starting with Bridge OS. |
Start here
Designing a screen
Start from the shape of the page, then reach for the parts that already exist.
Building a screen
Install @brdgapp/ui, build from tokens, and give every part that loads its own states.
Briefing an agent
Connect the agent to the handbook. It reads the same rules and pages you do.
Four rules to remember
Bridge has more named rules than these, and every page lists the ones that govern it. These four catch most mistakes.
One blue button per group
In each group of actions, only the single most important one is a primary (filled blue) button. The others are secondary, ghost or link. When everything is blue, nothing stands out.
Colors are tokens
Components use role tokens only: bg-[var(--surface-secondary)], text-[var(--text-muted)]. Never hex, rgb() or Tailwind palette classes such as bg-blue-500, and never a dark: patch to fix a color: if dark mode looks wrong, fix the token.
Each part loads on its own
The page frame shows straight away; each card, table or list shows its own skeleton, then its data. Never hold the whole page behind one if (isLoading) return <Skeleton />: a slow part would block the fast ones.
Never by color alone
Status and meaning are never carried by color alone. A colored tag has a word; a status color comes with an icon or text; a chart says in words what it shows.
The full set lives in Principles.
Where the system stands
Status and use are read from the code on every build, so this is never out of date.
0 of 36 documented components are used on a Bridge app’s main branch today. @brdgapp/ui 1.0.0 isn’t on npm yet; Bridge OS’s move onto it is in review.