## When to use

Whenever a user wants to extend a resource's audience past its default (workspace-only). The three surfaces compose into one "Share" dialog: scope picker as the headline decision; link or people surfaces depending on which scope the user chose. Don't show all three at once — that asks the user to pick a primitive instead of an outcome.

## Visibility scope picker

Four scopes as `option-card-ui` in a stacked radio group: Private, Link, Organization, Public. Each shows the audience and the action the user takes after picking.

Public on the web Indexable

## Share link with expiry

Surfaces when the user picks Link or Public scope. Generated URL with copy button; `select-ui` for expiry; revoke button as a danger-tone secondary action.

Share link Anyone with the link
Never 24 hours 7 days 30 days Custom date… Can view Can comment Can edit
Created
  Apr 22 · by Kim Granlund
Used
  14 opens · last 2 hours ago

## Add people with role

Surfaces in the Private and Org scopes. Autocomplete `search-ui` for people; per-row `select-ui` for the access role; existing-shares list below the input.

Share with people
Can view Can comment Can edit Kim Granlund kim@example.com Owner Avery Chen avery@example.com Can view Can comment Can edit Remove access Jordan Park jordan@example.com Can view Can comment Can edit Remove access

## Composition rules

- Scope picker drives the surface — pick scope, then surface the matching control (link UI for Link/Public, people UI for Private/Org). Don't show all three at once.
- Default to Private — every share dialog starts at the most restrictive scope. Public is a deliberate decision, never an accident.
- Public scope carries an "Indexable" warning tag — search engines can find it. Make this visible at the picker, not buried in a tooltip.
- Link shares show the open count — telling users "14 opens · 2 hours ago" prompts them to revoke when activity surprises them.
- Existing shares list always sorts owner first — the rest in invite-time order. Don't sort by role; users can't predict where their own row will be.
- Remove is a select option, not a separate button — keeps the row tidy and uses the same control surface for change-role and remove.

## See also

- option-card-ui — scope picker primitive.
- search-ui — people autocomplete.
- permissions-role-picker — sibling for role assignment.
- permissions-matrix — sibling for full RBAC grid.