@bridge-ds/toolbar
The Bridge toolbar for a product built with the Bridge design system. Bridge Studio opens the product with
?bridge=<change> ("Try it in the product"); the toolbar then lets anyone browse the real product and flip between
Live product (before) and This change (after), with Show what changed.
-
Code changes (an exploration in the product's repository, a feature branch): Before is the product in production, After is the branch's preview. Flipping keeps the screen and the scroll position. Production is another origin, so the toolbar cannot measure the difference: the change marks each new or changed area of the UI with
data-bridge-change="<short plain label>"on its outermost element (Bridge tells Claude to, in every exploration). On This change those areas are outlined, counted ("1 changed", "1 / 3 changed") and stepped through like token changes, with Isolate, and the Changes list names them. On Live product the bar says how many wait on This change ("1 changed on This change"). A change that marks nothing says so.<div role="status" data-bridge-change="Orders waiting to ship alert">30 orders are waiting to ship</div> -
Token changes of the design system: the live tokens swap in without a reload. As soon as the toolbar is open, every surface that differs is outlined and counted in the bar ("13 changed", then "2 / 13 changed"). Previous and Next scroll to each one in reading order and outline it stronger than the others; Isolate dims the rest of the page (Esc turns it off). The outlines, the position and Isolate hold when you flip to Live product, since both sides are the same page.
Keyboard: B flips Live product and This change on the same screen and scroll position, C turns the outlines off and on, Esc ends Isolate. None of them fires while you type in a field.
Without ?bridge= (or the session that remembers it) it renders nothing and loads nothing: the toolbar and its styles
are one lazy chunk.
The toolbar is Bridge's chrome and looks the same on any product, whatever its design system, tokens or global CSS:
its chunk carries the Bridge components it renders (class names of their own, bridge-tb_*) and the Bridge token
values, scoped to the toolbar's own elements. It never reads the page's tokens for its own look.
Mount it
npm i @bridge-ds/toolbar
One line at the root of the app, inside the design system's ThemeProvider:
import { BridgeToolbar } from '@bridge-ds/toolbar';
<BridgeToolbar ds="acme/design-system" product="checkout" />
ds is the design system repository and product the product's key in its bridge.config.json products[]. When
Studio opens the page, the toolbar reads that config from GitHub once per session: the product's repository (where its
explorations are pull requests), production (Before of a code change), preview (the branch preview template, the
only hosts allowed to hand over to production) and production Studio (previews.production.docs, the way back and the
live tokens). bridge connect prints this line with your values.
{ "key": "checkout", "name": "Checkout", "repo": "acme/checkout", "framework": "react",
"preview": "https://checkout-git-{branch}-acme.vercel.app", "production": "https://checkout.acme.com" }
Options
| Prop | What it does |
|---|---|
studio, production, preview | Override what the config says (for example a staging URL as Before). |
deployEnv | "production" or "preview" when your build knows it (Vercel: VERCEL_ENV). Optional: on other hosts (Cloudflare Pages, Netlify) a page whose host matches the preview template counts as a preview. |
build | Every fact at once, read at build time: no config read at run time. |
scope | A hook returning { theme, brand, density, shop, set } when your app keeps theme and shop in state. Default: the data-theme, data-brand and data-density attributes ThemeProvider asRoot puts on <html>. |
shops | { id, name, brand }[] of a multi-brand product, for the screens list and "Switch to ". |
together | A loader of the latest library's token files (togetherBase from @bridge-ds/toolbar/together), so Studio's "Try them together" runs on your production. |
proxy | Bridge's origin, whose read proxy serves the toolbar's GitHub reads. Default https://bridge.floriangouloubi.com; null reads GitHub directly. |
Reads go through Bridge's read proxy (<proxy>/api/contribute?repo=<ds>&gh=<path>: allow-listed, cached, read-only
on the server), so visitors never meet GitHub's limit of 60 anonymous reads an hour. Bridge serves a public design
system and the public product repositories its bridge.config.json lists, to the origins that config names
(production and preview of each product, and localhost). When Bridge refuses or cannot be reached, the toolbar
reads GitHub directly (anonymous, public repositories): at most a few API reads per change and session.