Permissions & Role-Based UI Checklist

1. Fundamental Rule

Backend validates permissions on every API call
Hiding a button is UX only — not security
User who knows API endpoint is still blocked by backend
Frontend never enforces permissions alone
Frontend only reflects backend permissions
Supabase permissions live in RLS policies
Xano permissions live in check_workspace_permission function
Django permissions live in LoginRequiredMixin and DB-backed view checks

2. Hide vs Disable

Approach	When to Use
Hide	User role has no access at all and seeing option would confuse them
Disable	User might have access in some contexts or needs to know feature exists
Show with explanation	Upgrade or role change would grant access

Disabled elements have tooltip explaining why
Tooltip says Admin access required, Owner access required, etc.
Disabled elements visually distinct from active elements
Disabled elements not completely hidden when user should know feature exists
Hidden elements only when completely irrelevant to the role
Navigation items user can see but not use are disabled with tooltip

3. Reading the User's Role

User role read from authenticated session/token
Role is not read from URL param, query string, or localStorage setting
Role read fresh from backend on each page load
Supabase role read from workspace_members table via RLS or dedicated query
Xano role read in check_workspace_permission function
Django role read from database in view or mixin
Frontend stores role in auth context/state, not localStorage
Role never accepted from user-controlled source

4. Buttons

Add Project visible to members, admin, owner; hidden from viewers
Edit visible to record owner and admins; disabled for others
Delete visible only to admins/owners
Delete hidden from members and viewers
Invite Member visible only to admins/owners
Export visible only if user has export permission
Export disabled with tooltip when not allowed

5. Form Fields

Fields user cannot edit shown as read-only or disabled
Read-only fields are not removed from the page
Read-only fields have tooltip explaining why
Entire form shown as read-only if user has view-only access
Save button hidden if entire form is read-only

6. Navigation

Navigation items user cannot access are hidden or disabled with tooltip
Hide nav items completely outside the user's role
Disable nav items that could be accessible with upgrade
Admin panel/settings link hidden for non-admin roles
Billing section hidden for non-owner roles

7. Tables / Lists

Action column adjusted per row based on user's permission for that row
Member can edit own rows but not others' rows
Admin can edit all rows
Do not show active Edit button on row user cannot edit
Disabled row action includes tooltip
Bulk delete hidden or disabled if user lacks delete permission

8. Page-Level Access

Unauthorized page shows: You don't have permission to view this
Unauthorized page does not redirect to 404
Unauthorized page never renders blank
Unauthorized page provides link back to accessible page
Locked feature shows locked/upgrade state, not 404
Protected routes redirect unauthenticated users to login
Intended URL restored after login

9. Partial Access

Show accessible parts fully
Restricted parts shown locked/blurred/disabled with clear explanation
Viewer on project settings sees general info but Danger Zone hidden or Admin only
Member on billing sees plan but Manage billing disabled with Owner access required
Backend restricts data and actions; frontend only displays state

10. Role Changes

Backend enforces new role on next API call after role change
Role-change rejection shows: You no longer have permission to do this
Removed workspace user redirected with explanation
Token refresh re-reads current role from database
User role is not cached indefinitely
Role refresh happens on login and token refresh