Live and running states
Syncing and other work that runs on its own.
Syncing and other background work always shows where it's up to — when it last ran, that it's running, and whether it worked — in words, with the icon to match.
The problem
Bridge does a lot of work in the background: syncing contacts, syncing calendars, importing an account. It can take minutes, and it can fail without anyone watching. If the screen doesn't say where things are up to, people press Sync again and again, or trust a list that stopped updating days ago.
What to do
- Always say where it's up to. When it last ran, that it's running, that it finished, or that it failed: in words, with the icon to match.
- Show progress when you know it. "Syncing contacts… 642 / 1,284". When the total isn't known, just "Syncing…".
- Only say done when it's done. "Synced" appears when the last-synced time has actually moved. If it never moves, that's an error, never a quiet success.
- When it can't run, say what to do. No button that can't work: "Calendar can't sync. Reconnect this account."
Which one do I use?
| Situation | Do this | Bridge example |
|---|---|---|
| Nothing running | Say when it last ran | Calendar synced 2 days ago |
| It has never run | Say so plainly | Calendar not synced · Never synced |
| A newly connected account that hasn't synced yet | Say when it was connected, not "Never synced" | Yesterday · connected |
| "Sync now" for one thing | A refresh IconButton: refresh → spinner → check, or a red alert if it fails | Calendar status line on the rail |
| Running, total known | The count, in the slot where the actions were | Syncing 120 of 480… |
| Running, total unknown | The verb and the thing, with a spinner | Syncing calendar… |
| Started something that takes minutes | Say it has started and how long it can take | Sync started. This can take a few minutes. |
| It failed | Red icon and words that say what to do. It clears after a few seconds so Sync can be tried again | Sync failed. Try again. |
| It can't run on this account | Words, and no sync button. Offer Reconnect if that fixes it | Calendar sync not available for Microsoft |
See it work
Live examples built from the package on the sample network. Click through them.
Sync now: refresh, spinner, check
Press the refresh button (hover it to see its label). The line says it's syncing, then "Calendar synced just now", then settles back to rest.
When it fails, and when it can't run
The first account fails when synced: a red alert and what to try. The second can't sync at all, so it has no sync button, only words and Reconnect.
ana@lanternfield.example
Calendar synced 3 days agoana@juniperrow.example
Calendar can’t sync. Reconnect this account.
Progress in the row's own slot
Sync this account: the count replaces the row's actions while it runs, then the last-sync time updates.
ana@lanternfield.example
Sep 9
last sync
What to write
| Part | Rule | Example |
|---|---|---|
| At rest | "{Thing} synced {when}", using Bridge's date words. | Calendar synced 2 days ago |
| Running | Verb in -ing, the thing, and an ellipsis. | Syncing calendar… |
| Progress | What's done out of the total, with commas in thousands. | Syncing contacts… 642 / 1,284 |
| Just finished | Say it, briefly, then go back to the resting line. | Calendar synced just now |
| Failed | What happened and what to do. | Sync failed. Try again. |
| Can't run | Why, and the fix if there is one. | Calendar can't sync. Reconnect this account. |
| Icon button name | The current state, in the aria-label and the tooltip. | Sync now → Syncing… → Synced |
Accessibility
- The sync IconButton's name carries its state (Sync now, Syncing…, Synced), and a tooltip shows the same words to mouse users.
- While running, the button is disabled and marked busy, so a second press can't start a second sync.
- A failure is never color alone: the alert icon comes with words.
- Spinners keep turning when reduced motion is on; the count is plain text.
| Keys | What happens |
|---|---|
| Tab | Moves to the sync button (its tooltip shows on focus). |
| Enter / Space | Starts the sync. |
Components this uses
Each opens that component’s own page, with its options and code.
| Component | Its job here |
|---|---|
| IconButton | "Sync now": refresh, loading while running, check when done, alert with variant="danger" on failure. |
| InfoHint, HoverTip and Tip | Tip shows the sync button's current state on hover and focus. |
| Button | A row's labeled Sync (ghost, xs) and Reconnect. |
| DataState | The skeleton rows during a first sync, when there's nothing to show yet. |
Where Bridge OS differs today
Follow this page, not the gap.
- Some sync labels use Title Case or an em dash mid-sentence; they follow the Writing rules as they're touched.
- Progress is written two ways: "Syncing contacts… 120 / 480" (contacts list) and "Syncing 120 of 1,200…" (account row).
- The sync status hard-codes its green (
#0EA02E) and red (#E13535) instead of the success and danger tokens (calendar-sync-status.tsx).
Sources
- Bridge OS
calendar-sync-status.tsx,connected-accounts-section.tsx - Bridge OS
calendar-sync-status.tsx,connectors-tab.tsx - components.md → IconButton (Sync now convention)
- Bridge OS
calendar-sync-status.tsx - Bridge OS
hooks/use-calendar-sync.ts,calendar-sync-status.tsx - Bridge OS components.md → CalendarSyncControl;
hooks/use-calendar-sync.ts - Bridge OS
calendar-sync-status.tsx(calendarStatus); components.md → ConnectedAccountsSection - Bridge OS
connected-accounts-section.tsx; components.md → ConnectedAccountsSection - Bridge OS
connected-accounts-section.tsx(formatSyncTime); components.md - Bridge OS
connected-accounts-section.tsx - Bridge OS
calendar-sync-status.tsx(CalendarSyncButton iconOnly); components.md