Using the system

Bridge’s components, tokens and styles ship as one package, @brdgapp/ui. An app installs it once and imports the stylesheet after Tailwind. That brings every token in light and dark, and tells Tailwind to read the package’s files.

/* The app's main CSS file, after Tailwind */
@import "tailwindcss";
@import "@brdgapp/ui/globals.css";

• Needs React 18 or 19 and Tailwind CSS 4.
• Load the Mulish font the way the app loads fonts. With next/font, name the variable --font-mulish.
• The theme follows data-theme on <html> (see Theming below).
• Mount <Toaster /> once in the root layout, so toast.success() works from any screen.

Import each part from its own file. There is no single index file to import from.

What you can import, read from the package’s package.json

Typical imports

import { Button } from "@brdgapp/ui/components/button";
import { DataState } from "@brdgapp/ui/components/data-state";
import { formatCount, formatDate } from "@brdgapp/ui/lib/format";
import { cn } from "@brdgapp/ui/lib/utils";

Always import cn from @brdgapp/ui/lib/utils, never clsx or a copy in the app, so a class you pass can override the component’s own.

Style with Bridge’s role tokens, never raw colors. A token names a job (--text-muted, --surface-secondary), so the same class is right in light and dark.

The type scale

• Every number that changes or gets compared uses tabular-nums. Write it with formatCount, formatMoney, formatPercent or formatDate, never by hand.
• A package component’s look comes from its props (variant, size). Use className on it only for layout: mt-4, w-full, shrink-0.

Every token with its light and dark value is in Design tokens; the custom utilities, such as liquid-glass, are in Styles and utilities.

Build a screen builds a whole Bridge OS page from the package, in the order you’d build any page: pick the app, pick the template, lay out the parts, then fill each one. Start there once the package is set up.

Every card, table and panel that loads data owns its own loading, empty and error states. DataState takes the query’s status and data and shows a skeleton, an empty state, an error with Retry, or your content.

• Never hold up a whole page while one part loads. The card and its title always show; only the inside waits.
• Shape the skeleton like the loaded content, so nothing moves when the data arrives.
• An empty state says what will be here and how to fill it. An error says what failed and offers Retry.
• useMockQuery is for handbook examples and prototypes. In an app, pass the real query’s status and data.

The full rules are in Loading, empty and error.

Every action shows that it worked. If the result is visible where the person clicked (a row says Copied, a switch turns on), that is the feedback. If it isn’t, because a menu closed or the result happens somewhere else, a toast says what happened.

• A toast is past tense, under 10 words, with no period: “Invite sent”.
• An error people must act on stays next to the problem. It is never a toast that fades.
• Bridge has no undo. Anything that removes or stops something asks first with ConfirmDialog.

See Feedback and undo and Destructive actions.

Light and dark come from one set of tokens. data-theme="dark" on <html> switches every token at once; data-theme="light" on an element keeps that area light inside a dark page. Bridge follows the member’s choice, not the device setting.

• Bridge OS stores the choice in localStorage as bridge-theme and sets it before the page draws, so there is no flash of the wrong theme.
• A screen built from tokens needs no dark: classes. Use dark: only for something a token can’t say.
• Every example on this site has a Light and Dark switch. Check both before you ship.

Base UI gives the package’s components their roles, focus handling and keyboard behavior. Naming things and choosing the right element stay with you.

• Every control has a name. An icon-only button has an aria-label that says the action.
• Focus always shows: a 2px ring with a 2px gap. Never remove it.
• Nothing clickable is smaller than 28px.
• Everything a pointer can do, the keyboard can do. Every dialog has a title.
• Status is never shown by color alone; a word always goes with it.
• Motion respects reduced motion.

The full checklist is in Accessibility.

Every component, pattern and template has a page. Press / anywhere on this site to search the sidebar by title and description.

DESIGN.md at the root of the design-system repo is the visual spec. The handbook explains it and shows it running; no app reinterprets it. When code and DESIGN.md disagree, DESIGN.md wins.

• Each app gets its character from layout, density and behavior, not from new colors, fonts or corner sizes.
• If the system can’t do something a screen needs, change the system first (Component lifecycle), not the one screen.

Where new code goes

New to the code itself? See Repository and Component lifecycle.