How capability exposure is represented consistently across the product.

Server-side authorization = enforcement
React permission UI      = exposure control
Design system            = consistent exposure primitives

This button is secure because it is hidden.

This button uses the same permission decision model, fallback semantics, disabled/hide behavior, reason display, analytics policy, and test harness as the rest of the product.

unknown permission state => do not expose destructive action

// Page A
{canDelete && <Button>Delete</Button>}

// Page B
<Button disabled={!canDelete}>Delete</Button>

// Page C
<MenuItem hidden={!user.roles.includes("admin")}>Delete</MenuItem>

// Page D
<CommandItem action="delete" /> // forgot permission

You cannot delete this investigation because it is locked by Case Officer Maria.

You do not have access to delete this case.

This case cannot be deleted while it is under review.

The design system may decide how to render a decision.
It must not decide whether the user truly has permission.

export type PermissionStatus =
  | "allowed"
  | "denied"
  | "unknown"
  | "loading"
  | "stale"
  | "requires_step_up";

export type PermissionReasonCode =
  | "missing_permission"
  | "resource_locked"
  | "workflow_state"
  | "tenant_mismatch"
  | "requires_mfa"
  | "ownership_required"
  | "policy_unavailable"
  | "permission_stale"
  | "not_authenticated";

export interface PermissionDecision {
  status: PermissionStatus;
  action: string;
  resourceType?: string;
  resourceId?: string;
  tenantId?: string;
  policyVersion?: string;
  evaluatedAt?: string;
  reasonCode?: PermissionReasonCode;
  reason?: string;
  safeUserMessage?: string;
  canRequestAccess?: boolean;
  requestAccessHref?: string;
  stepUpHref?: string;
  constraints?: Record<string, unknown>;
}

Denied because no permission
Denied because resource locked
Denied because MFA needed
Unknown because permissions are loading
Stale because tenant changed

interface PermissionGateProps {
  decision: PermissionDecision;
  expose?: "hide" | "disable" | "readonly" | "replace";
  fallback?: React.ReactNode;
  children: React.ReactNode | ((decision: PermissionDecision) => React.ReactNode);
}

export function PermissionGate({
  decision,
  expose = "hide",
  fallback = null,
  children,
}: PermissionGateProps) {
  if (decision.status === "allowed") {
    return typeof children === "function" ? <>{children(decision)}</> : <>{children}</>;
  }

  if (decision.status === "requires_step_up") {
    return <StepUpRequired decision={decision} />;
  }

  if (decision.status === "loading" || decision.status === "unknown") {
    return expose === "hide" ? null : <PermissionSkeleton />;
  }

  if (expose === "replace") {
    return <>{fallback}</>;
  }

  if (expose === "hide") {
    return null;
  }

  return <DisabledPermissionWrapper decision={decision}>{children}</DisabledPermissionWrapper>;
}

Rendering is a function of a decision object, not a random boolean.

interface AuthorizedButtonProps extends ButtonProps {
  decision: PermissionDecision;
  deniedMode?: "hide" | "disable" | "explain";
  onUnauthorizedClick?: (decision: PermissionDecision) => void;
}

export function AuthorizedButton({
  decision,
  deniedMode = "disable",
  onUnauthorizedClick,
  onClick,
  children,
  ...buttonProps
}: AuthorizedButtonProps) {
  if (decision.status === "allowed") {
    return (
      <Button {...buttonProps} onClick={onClick}>
        {children}
      </Button>
    );
  }

  if (decision.status === "requires_step_up") {
    return (
      <Button {...buttonProps} onClick={() => navigateToStepUp(decision)}>
        Continue with verification
      </Button>
    );
  }

  if (deniedMode === "hide") {
    return null;
  }

  if (deniedMode === "explain") {
    return (
      <Tooltip content={decision.safeUserMessage ?? "You do not have access to this action."}>
        <Button
          {...buttonProps}
          aria-disabled="true"
          onClick={(event) => {
            event.preventDefault();
            onUnauthorizedClick?.(decision);
          }}
        >
          {children}
        </Button>
      </Tooltip>
    );
  }

  return (
    <Button {...buttonProps} disabled>
      {children}
    </Button>
  );
}

export function exposureFor(decision: PermissionDecision, surface: "nav" | "button" | "field" | "rowAction") {
  if (decision.status === "allowed") return "show";

  if (surface === "nav") return "hide";

  if (decision.status === "requires_step_up") return "explain";

  if (decision.canRequestAccess) return "explain";

  if (decision.reasonCode === "workflow_state") return "disable";

  if (surface === "field") return "readonly";

  return "hide";
}

export interface ProductAction<TResource = unknown> {
  id: string;
  label: string;
  icon?: React.ComponentType;
  intent?: "default" | "primary" | "danger";
  getDecision: (resource: TResource, context: PermissionContext) => PermissionDecision;
  run: (resource: TResource) => Promise<void> | void;
  exposure?: "hide" | "disable" | "explain";
}

function PermissionedMenuItem<T>({ action, resource }: { action: ProductAction<T>; resource: T }) {
  const context = usePermissionContext();
  const decision = action.getDecision(resource, context);

  if (decision.status !== "allowed" && action.exposure === "hide") {
    return null;
  }

  return (
    <MenuItem
      disabled={decision.status !== "allowed"}
      danger={action.intent === "danger"}
      onSelect={() => {
        if (decision.status !== "allowed") return;
        return action.run(resource);
      }}
    >
      {action.label}
    </MenuItem>
  );
}

function CommandPalette() {
  const commands = useRegisteredCommands();
  const context = usePermissionContext();

  const visibleCommands = commands.filter((command) => {
    const decision = command.getDecision(context);
    return decision.status === "allowed" || decision.status === "requires_step_up";
  });

  return <CommandList commands={visibleCommands} />;
}

useKeyboardShortcut("mod+shift+d", () => {
  const decision = can("case.delete", currentCase);

  if (decision.status !== "allowed") {
    showDeniedToast(decision);
    return;
  }

  openDeleteDialog(currentCase);
});

interface RowActionSet {
  view: PermissionDecision;
  edit: PermissionDecision;
  delete: PermissionDecision;
  assign: PermissionDecision;
}

{
  "items": [
    {
      "id": "case_123",
      "title": "Case 123",
      "state": "UNDER_REVIEW",
      "allowedActions": {
        "case.view": { "status": "allowed" },
        "case.edit": { "status": "denied", "reasonCode": "workflow_state" },
        "case.delete": { "status": "denied", "reasonCode": "resource_locked" }
      }
    }
  ],
  "policyVersion": "pol_2026_07_08_01"
}

function CaseRowActions({ row }: { row: CaseRow }) {
  return (
    <RowActionMenu>
      <PermissionedMenuItem decision={row.allowedActions["case.view"]}>View</PermissionedMenuItem>
      <PermissionedMenuItem decision={row.allowedActions["case.edit"]}>Edit</PermissionedMenuItem>
      <PermissionedMenuItem decision={row.allowedActions["case.delete"]} intent="danger">
        Delete
      </PermissionedMenuItem>
    </RowActionMenu>
  );
}

export interface BulkEligibility {
  action: string;
  total: number;
  eligible: number;
  ineligible: number;
  requiresStepUp: number;
  reasons: Array<{
    reasonCode: PermissionReasonCode;
    count: number;
    safeUserMessage: string;
  }>;
  eligibleIds?: string[];
  previewToken?: string;
}

Approve selected (15 eligible, 5 skipped)

Delete 15 eligible cases. 5 cannot be deleted.

export interface FieldPermissionDecision extends PermissionDecision {
  field: string;
  mode: "hidden" | "masked" | "readonly" | "editable" | "requires_step_up";
  constraints?: {
    maxLength?: number;
    min?: number;
    max?: number;
    allowedValues?: string[];
    requiresChangeReason?: boolean;
  };
}

function PermissionedTextField({
  field,
  decision,
  value,
  onChange,
  label,
}: {
  field: string;
  decision: FieldPermissionDecision;
  value: string;
  onChange: (value: string) => void;
  label: string;
}) {
  if (decision.mode === "hidden") return null;

  if (decision.mode === "masked") {
    return <ReadOnlyField label={label} value="••••••" />;
  }

  if (decision.mode === "readonly") {
    return <TextField label={label} value={value} readOnly />;
  }

  if (decision.mode === "requires_step_up") {
    return <StepUpField label={label} decision={decision} />;
  }

  return <TextField label={label} value={value} onChange={(e) => onChange(e.target.value)} />;
}

Field authorization must be represented as a first-class field mode, not improvised with CSS.

No projects yet. Create your first project.

<EmptyState action={<Button>Create project</Button>} />

<PermissionedEmptyState
  title="No projects yet"
  actionDecision={canCreateProject}
  allowedAction={<Button>Create project</Button>}
  deniedAction={<RequestAccessLink action="project.create" />}
/>

function DeleteCaseDialog({ caseId }: { caseId: string }) {
  const decision = useCan("case.delete", { type: "case", id: caseId });
  const mutation = useDeleteCaseMutation();

  return (
    <Dialog>
      <DialogTitle>Delete case?</DialogTitle>
      <DialogBody>This action cannot be undone.</DialogBody>
      <DialogFooter>
        <Button variant="secondary">Cancel</Button>
        <AuthorizedButton
          intent="danger"
          decision={decision}
          onClick={() => mutation.mutate({ caseId })}
        >
          Delete
        </AuthorizedButton>
      </DialogFooter>
    </Dialog>
  );
}

The server still enforces DELETE /cases/:id.

const deleteCaseAction: ProductAction<CaseSummary> = {
  id: "case.delete",
  label: "Delete case",
  intent: "danger",
  getDecision: (resource, context) =>
    context.permissions.forResource(resource.id).decision("case.delete"),
  run: async (resource) => {
    await api.deleteCase({
      id: resource.id,
      idempotencyKey: crypto.randomUUID(),
    });
  },
};

const permissionTokens = {
  deniedOpacity: "0.56",
  deniedIcon: "lock",
  requiresStepUpIcon: "shield-check",
  accessRequestIcon: "key-plus",
};

const roleTokens = {
  adminButtonColor: "red",
  managerCanEdit: true,
};

type ReasonVisibility = "public" | "same_tenant" | "privileged" | "internal_only";

interface DenialReasonDefinition {
  code: PermissionReasonCode;
  defaultMessage: string;
  visibility: ReasonVisibility;
  allowAccessRequest: boolean;
}

Denied by POL_CASE_DELETE_AFTER_ESCALATION_V3 because user missing senior_enforcement_officer role.

You do not have access to delete this case.

function DeniedActionHint({ decision }: { decision: PermissionDecision }) {
  if (!decision.canRequestAccess || !decision.requestAccessHref) {
    return <span>{decision.safeUserMessage ?? "You do not have access."}</span>;
  }

  return (
    <InlineMessage>
      {decision.safeUserMessage ?? "You do not have access."}
      <Link to={decision.requestAccessHref}>Request access</Link>
    </InlineMessage>
  );
}

function PermissionedPageHeader({
  title,
  actions,
}: {
  title: string;
  actions: ProductAction[];
}) {
  const context = usePermissionContext();

  return (
    <PageHeader title={title}>
      {actions.map((action) => {
        const decision = action.getDecision(context);
        return (
          <AuthorizedButton key={action.id} decision={decision}>
            {action.label}
          </AuthorizedButton>
        );
      })}
    </PageHeader>
  );
}

export const handle = {
  auth: {
    requiresAuth: true,
    actions: ["case.view", "case.update", "case.close"],
  },
};

function SecureLayout() {
  const matches = useMatches();
  const routeActions = matches.flatMap((m) => m.handle?.auth?.actions ?? []);

  return <PermissionedLayout routeActions={routeActions} />;
}

unknown => hide sensitive controls or show skeleton

function PermissionSkeleton() {
  return <span className="permission-skeleton" aria-hidden="true" />;
}

{
  "event": "permission_denied_ui_exposed",
  "action": "case.delete",
  "resourceType": "case",
  "reasonCode": "workflow_state",
  "tenantScope": "same_tenant",
  "policyVersion": "pol_2026_07_08_01"
}

{
  "resourceTitle": "Investigation into ACME Bank Fraud",
  "deniedBecause": "User lacks Senior Fraud Investigator role",
  "caseOwner": "maria@example.com"
}

interface PermissionTelemetryAdapter {
  onDeniedExposure?(decision: PermissionDecision, surface: string): void;
  onUnauthorizedClick?(decision: PermissionDecision, surface: string): void;
  onStepUpPrompt?(decision: PermissionDecision, surface: string): void;
}

allowed

stale session / tenant switched / policy updated

If server and client permission snapshots disagree, client must not preserve a more privileged UI without revalidation.

interface PermissionSnapshotMeta {
  subjectId: string;
  tenantId: string;
  sessionEpoch: number;
  policyVersion: string;
  issuedAt: string;
}

function isSnapshotCompatible(server: PermissionSnapshotMeta, client: PermissionSnapshotMeta) {
  return (
    server.subjectId === client.subjectId &&
    server.tenantId === client.tenantId &&
    server.sessionEpoch === client.sessionEpoch &&
    server.policyVersion === client.policyVersion
  );
}

<Button visibleForRoles={["admin", "manager"]}>Delete</Button>

<AuthorizedButton decision={canDeleteCase}>Delete</AuthorizedButton>

<AuthorizedButton permission="case.delete" resourceId={case.id} />

.disabled {
  pointer-events: none;
  opacity: 0.5;
}

You can view this case, but editing is locked after escalation.

You cannot view this suspicious transaction because it belongs to the AML team.

@company/auth-ui
  PermissionProvider
  usePermissionContext
  useCan
  Can
  PermissionGate
  AuthorizedButton
  PermissionedMenuItem
  PermissionedCommand
  PermissionedField
  PermissionedBulkActionBar
  PermissionedEmptyState
  PermissionDeniedMessage
  StepUpRequired
  RequestAccessLink
  createActionDescriptor
  createPermissionTestHarness

const actions = [viewCaseAction, editCaseAction, closeCaseAction, deleteCaseAction];

function CaseHeader({ caseSummary }: { caseSummary: CaseSummary }) {
  return (
    <PermissionedActionBar
      resource={caseSummary}
      actions={actions}
      placement="page-header"
    />
  );
}

it("does not expose destructive action while permission is unknown", () => {
  render(
    <AuthorizedButton
      decision={{ status: "unknown", action: "case.delete" }}
      deniedMode="hide"
    >
      Delete
    </AuthorizedButton>
  );

  expect(screen.queryByRole("button", { name: /delete/i })).not.toBeInTheDocument();
});

1. Components do not check roles directly.
2. Components consume permission decisions or action descriptors.
3. Unknown permission never exposes privileged controls.
4. Every action surface uses the same authorization primitive.
5. Keyboard shortcuts and command palette are action surfaces.
6. Denial copy is policy-controlled and leak-aware.
7. Disabled is UX, not security.
8. Hidden is exposure control, not security.
9. Backend re-check is mandatory.
10. Permission UI is tested as a design-system behavior.

Should I hide this button or disable it?

What does the permission decision say, and what is the approved exposure mode for this surface?