permissions-and-settings

Permissions Should Be Felt, Not Fought

Every user should see exactly what they need to get their job done — no more, no less.

Three Strategies for Restricted Features

All three are needed — choose per feature:

Strategy	When to Use	Example
Hide completely	Entire section irrelevant to the role	Admin-only billing section hidden from members
Show but disable (with tooltip)	User should know the feature exists — upsell path	Plan-gated feature with "Upgrade to Pro" tooltip
Show with reduced functionality	Read access appropriate, write access isn't	View-only dashboard for member role

RBAC Progression

Follow WorkOS's practical progression, building incrementally:

1. Simple admin/member differentiation — start here
2. Fine-grained permissions per feature — define what each role can do
3. Roll-up roles — combine permissions into named roles
4. Resource groups — scope roles to orgs, teams, projects
5. Custom roles — let admins define their own
6. IdP attribute mapping — for enterprise SSO

Key UX guardrail: Expose permission bundles that map to real product concepts, not 40 atomic checkboxes. Enforce limits like "max 20 custom roles per tenant" to prevent configuration chaos.

Invitation Flows

Three mechanisms are needed:

1. Email Invite (Default)

Admin enters addresses, sets access level before sending.

2. Link Invite (Bulk)

For bulk invitations. Support expiration dates and domain restrictions.

3. Domain-Based Provisioning (Enterprise SSO)

Accounts auto-created on first login.

Invitation email must include:

• Who invited them
• What the product does
• Who else from their team is already using it

Differentiate onboarding for invited users — they get a shorter, different flow because context already exists.

Settings Architecture

Clean split between two concerns:

Settings Type	Belongs To	Examples
Account settings	The person	Profile, password, notifications, appearance
Workspace settings	The organization	Members, billing, integrations, security policies

Never mix them.

Layout: Sidebar navigation + content area. This is the standard used by GitHub, Linear, and Vercel.

Avoid tab-based settings when there are more than 5–6 categories — tabs don't scale.

Two-column layout (Shopify Polaris pattern):

• Left column: scannable labels and descriptions
• Right column: grouped settings in cards

Review Checklist

When reviewing or building permissions and settings:

• Restricted features use the correct strategy (hide / disable with tooltip / reduced functionality)
• RBAC uses permission bundles, not atomic checkboxes
• Custom roles have a reasonable limit per tenant
• Email, link, and domain-based invitation flows all supported
• Invitation emails include who invited, what the product does, and who else is using it
• Invited users get a shorter, differentiated onboarding
• Account settings (person) and workspace settings (org) are fully separated
• Settings use sidebar navigation, not tabs (if >5–6 categories)
• Two-column layout: labels/descriptions on left, controls on right