Export · Integrations · UX

Bristlenose → Miro: the flow & setup experience

The hard part isn't placing stickies — it's the journey across two apps and getting a researcher past first-run setup. The whole design goal: cross the app boundary as few times as possible, and never make someone do the setup twice.

The journey — two app crossings, that's the budget

Bristlenose

Review quotes

Quotes tab, in the report
Export ▾
Send to Miro
Bristlenose

Send-to-Miro panel

Connect (first run only) → configure
⤴ leaves
the app
Miro · browser

Approve access

One “Allow”, first run only
⤵ returns
automatically
Bristlenose

Push board

Progress → done
↗ opens
the board
Miro

Your board

Rearrange with the team
Bristlenose (on your machine) Miro (browser / app) app-boundary crossing — the risky moments

First run crosses the boundary twice (consent out + back). Every run after that crosses only once — the final “open your board” handoff. The consent step never reappears.

The setup experience, screen by screen

1 · Entry — the menu encodes the state

The Export popover item changes by connection state

Not connected yet
Once connected
Connect to Miro… (disconnected) routes to consent (step 2–3); Send to Miro board… (connected) jumps straight to Configure (step 4). The menu never hides which state you're in.
2 · First run only — the “key dance”

One button, not a developer setup

Default path is one-click OAuth. The developer “paste a token” route is demoted to a quiet fallback for locked-down orgs.
3 · Crossing out

Browser opens, expectation set

🔒 miro.com/oauth/authorize
Miro

Bristlenose wants to create boards in your team.

boards:read · boards:write

Panel meanwhile shows “Waiting for Miro… approve in your browser, then come back here.” — no dead-end, no guessing.
4 · Configure & consent

Returns connected — choose and confirm

The privacy reality (“data leaves your machine”) is stated at the moment of action, not buried.
5 · Pushing

Honest progress, cancellable

Runs as a background job (10–30s). Rate-limit backoff is invisible to the user.
6 · The payoff crossing

One button into the finished board

The only crossing on repeat use. Hands off to the Miro app/browser where the actual team synthesis happens.

The returning researcher never sees the dance again

Because the connection is stored once in the system keychain and auto-refreshed, the second export and every one after skips steps 2–3 entirely: Export ▾ → Send to Miro… → (already Connected) → Configure → Create → Open. Setup is a one-time tax, paid once per machine.

The three friction-killers this flow is built around

Connect once, never again

Token + refresh live in the keychain. Step 2 appears exactly once per machine. Returning users land straight on Configure.

One click, not six steps build M2

OAuth “Connect” replaces create-app → scopes → install → copy-token. The paste path stays only as a fallback for orgs that block third-party apps.

No silent dead-ends

The browser handoff sets the expectation (“come back here”); the return is automatic via localhost callback; the finish gives one obvious “Open in Miro” button.

One-way only — Bristlenose pushes a new board and never syncs back (Miro retired webhooks; the spatial arrangement is the researcher's analysis). Mockup — not a shipped screen. paste-token path available now connect button = M2