Draft

Education and onboarding

Helping people get started and complete their profile.

Bridge teaches mainly through its empty states: each says what will appear and how to make it happen. Signed-out and locked views show what you'd get, not just a gate. There are no tours.

The problem

Most of Bridge starts empty: no contacts until an account is connected, no new people until you meet someone, no intros until you make one. An empty area that only says "Nothing here" looks broken, and people don't learn what it's for or how to fill it. Bridge has no tours, so the screen itself has to do the teaching.

What to do

Teach where the feature is. The empty state says what will appear and gives one action to make it happen. A signed-out page shows what you'd get, not just a gate.
Give the first wait a shape. The first sync shows skeleton rows of the real list and a count, so people can see it working.
One nudge at a time. A page-wide nudge is one PageBanner with an action. Under an empty state, a second prompt sits below a line, never as another banner.

Which one do I use?

Situation	Do this	Bridge example
Nothing here yet, and the person can fix that	DataState's empty body: what will appear, and one primary action	No contacts yet · Connect a work email to sync your contacts with Bridge. · Connect an account
Nothing here yet, and it fills on its own	Empty body that says what will appear and when; no button needed	No one new yet · New people you meet or get introduced to in the last 60 days show up here.
A second way to fill it (a calendar to sync)	A small muted line under the empty state, after a divider, with its own button	Sync your calendar to catch the people from your recent meetings.
Empty because of a search or filter	Say nothing matched and offer to clear it. Don't teach here	No contacts match "quill" · Clear search
The first sync is running	Skeleton rows of the real shape, and a progress line with the count	Syncing contacts… 642 / 1,284
Something page-wide is unfinished	One PageBanner with an action, first on the page	Your profile is 60% complete
A number or label whose meaning isn't obvious	An InfoHint ⓘ beside it	Intros accepted ⓘ
The visitor isn't signed in	Show what they'd get, then "Log in to Bridge" (Permissions and availability)	Log in to see your network

See it work

Live examples built from the package on the sample network. Click through them.

An empty state that leads to the first sync

The empty card says what it's for and offers one action. Connecting starts the first sync: skeleton rows and a running count, then the real list.

Contacts

No contacts yet

Connect a work email to sync your contacts with Bridge.

No matches is not a first visit

When a search finds nothing, say so and offer to clear it. The teaching copy is only for a truly empty list. Clear the search to see the rows.

No contacts match “zz”

One nudge, at the top of the page

A page-wide nudge is a single PageBanner with an action that goes where the work is done.

Your profile is 60% complete

Activity

Explain a number where it sits

Hover, focus or tap the ⓘ. Only the number that needs it gets one.

Intros this year

Intros accepted

What to write

Part	Rule	Example
Empty title	"No {things} yet". Say what would be here, not that it's empty.	No contacts yet
Empty line	What the person gets, or how it fills. One sentence.	Connect a work email to sync your contacts with Bridge.
Empty action	One button, verb and object.	Connect an account
No matches	Quote what was searched, and offer to clear it.	No contacts match "quill" · Clear search
First sync	What's happening, with the count when it's known.	Syncing contacts… 642 / 1,284
Banner	One short line, sentence case, with the action at the end.	Your profile is 60% complete · Complete profile
InfoHint	What the number means and how it's counted. No full stop.	Intros the other person agreed to, out of all you made

Approved, not built yet

No product tours or pop-up tips: teach in the empty state and the PageBanner, where the feature is.
At most one nudge banner per page, and it can be dismissed.

Accessibility

DataState announces its changes politely, and marks the skeleton as busy while the first sync runs.
The empty state's icon is decorative; the title and line carry the meaning.
InfoHint opens on hover, keyboard focus or tap, and its button is named by its text, so screen readers hear the explanation without opening it.
PageBanner isn't a live region. If a banner appears after the page has loaded, announce it separately.

Keys	What happens
`Tab`	Reaches the empty state's action, the banner's action and each ⓘ.
`Enter / Space`	Presses the focused button.
`Esc`	Closes an open InfoHint.

Components this uses

Each opens that component’s own page, with its options and code.

Component	Its job here
DataState	Draws the empty body (title, line, one action) and the skeleton while the first sync runs.
Button	`primary` for the one action in an empty state; `link` for Clear search and the banner's action.
PageBanner	The single page-wide nudge, with its action.
InfoHint, HoverTip and Tip	Explains a number or label in place.
SearchInput	The search whose empty result offers Clear search instead of teaching.

Not decided yet

Proposals for Aman to approve, change or reject. Not rules.

What counts toward "profile complete", and where the banner's action takes you, isn't defined yet.
Whether a dismissed nudge banner comes back later (and when) isn't decided.

Where Bridge OS differs today

Follow this page, not the gap.

Bridge OS's ProfileCompletionBanner (really a network-sharing nudge) isn't used by any page; remove it or put it on PageBanner.

Sources

Bridge OS DESIGN.md → principle 5
Bridge OS connectors-tab.tsx
components.md → PageBanner
Bridge OS connectors-tab.tsx (people tab empty state)
Bridge OS recently-met-rail.tsx (RailEmptyState, RailCalendarLine)
Bridge OS DESIGN.md → Auth-Aware UI; network-logged-out-view.tsx
Handbook InfoHint guidance; Bridge OS outcomes-page-content.tsx
Proposals approved by Aman 2026-11-02.