Design

Acceptance Criteria

A Join button is visible in the site top bar. Tapping Join opens a modal within the app that shows the site name and two options: Create identity in Hypermedia and Already have a Hypermedia identity, plus a quick link labeled "I have an identity from another site?"

The modal copy explains that the site is built with Hypermedia and that creating an identity takes two minutes — no technical language

Tapping "Already have a Hypermedia identity" takes the user to the email screen inside the Hypermedia sign-in flow

Valid email advances to the passkey screen showing "Good to see you again" and the email address to remind

Passkey confirmation uses device biometrics or PIN

On successful passkey confirmation, the user sees a "Join [site name]" screen showing all their available identities; the currently active identity is pre-selected with a checkmark

Primary CTA is "Start participating" — one tap, no further steps

On joining, the site is added to Joined Sites in the sidebar immediately and the Join button disappears from the site top bar

A toast alert appears: "You've joined [site name] — you can now comment and participate" and auto-dismisses after ~3 seconds

No new identity is created — the user's existing remote identity is used throughout and user is as a full member with participation features

Basic Flow

User is viewing a site in the app — Join button visible in top bar

Taps Join — modal opens showing "Join [site name]"

Taps "Already have a Hypermedia identity"

Enters email linked to their Hypermedia identity

Taps Continue — passkey screen appears

Confirms with passkey

"Join [site name]" screen shows available identities — primary identity pre-selected

Taps "Start participating"

Returns to site as member — Join button gone, site added to sidebar, toast appears

Edge Cases

⚠️ Invalid email format → inline error: "That doesn't look like a valid email. Check for typos and try again." Button disabled until fixed

⚠️ Email not linked to any Hypermedia identity → "No Hypermedia identity found for this email." with option to create one instead

Passkey

⚠️ Device does not support passkeys → fallback method offered, user not blocked (password needs to be developed later)

⚠️User cancels the biometric prompt → returns to passkey screen, can retry

⚠️ Passkey creation fails due to device error → retry option shown

Clear error messages: avoid: "Failed to fletched" "Invalid Handoff token" _ review this one by one

⚠️ User taps "Use another email" → returns to email screen, previous entry cleared

⚠️ User is already a member of this site → join confirmation is skipped, user lands directly as a member with no duplicate entry created

⚠️ User taps "I have an identity from another site?" → path TBD

⚠️ User closes the modal mid-flow → returns to site as guest, no partial state created, Join button remains visible